# TraceCite Roadmap

更新日期：2026-10-04（北京时间）。

按 **正式交付 → 日常维护体验 → 真实项目验证 → 生态接入** 推进。
项目持续围绕引用与来源的一致性、来源变化后的文档维护，保留人工复核入口。

## 当前基础

0.6.1 已发布到 Mooncakes 和 GitHub，继承 0.5.0 的项目配置、init/check、GitHub Action 和 portable 核心库。
验收说明、第三方许可及 13 步和 14 步离线维护演示已纳入正式源码包；实际注册表安装与两平台独立包均已验证。
已发布内容与后续改动见 [版本记录](CHANGELOG.md)，交付证据见 [验收说明](docs/acceptance.md)。

下列版本为规划目标，尚未完成的事项保持未勾选；执行顺序与范围根据实际反馈调整。

## 0.5.1：发布收口（已完成）

优先让 GitHub 和 Mooncakes 的正式交付材料一致。

- [x] 将新增验收材料、许可通知纳入正式 Mooncakes 包。
- [x] 同步模块、CLI、安装示例和版本记录中的版本号。
- [x] 创建 GitHub 版本标签和正式 Release，长期提供 Linux/macOS 独立包与 SHA-256 校验文件。
- [x] 发布脚本防止重复发布已有版本，核对构建来源与交付身份。
- [x] 从实际注册表安装发布后的库和 CLI，验证公开 API 与维护流程。

**完成标准**：Mooncakes 安装、源码构建、独立包运行均通过，发布版本可对应固定提交。
执行步骤以 [发布指南](docs/publishing.md)为基础。

发布成果：[GitHub Release](https://github.com/Freakz2z/tracecite/releases/tag/v0.5.1)、[Mooncakes](https://mooncakes.io/docs/Freakz2z/tracecite)。固定提交、摘要和验证回执见 [0.5.1 交付记录](docs/releases/0.5.1.json)。

## 0.6.0：降低维护成本（已完成）

优先改善团队反复检查、定位问题和复核来源变化的体验。

- [x] 项目配置支持常用文件通配符，明确匹配、排除与空范围的行为。
- [x] 补充 Setext 标题解析，并验证与当前锚点和快照机制的兼容性。
- [x] 提供来源变化的集中复核报告和基线更新预览。
- [x] 允许项目明确要求检查覆盖范围，复核网页跳过项与未绑定源码的代码块。
- [x] 增加上述能力的边界测试和可运行维护示例。

**完成标准**：在一个示例项目中完成扫描、定位、修复、复核和更新基线，新增边界测试全部通过。
现有 [离线演示](examples/maintenance/README.md)继续作为维护闭环的回归验证。

发布成果与消费验证见 [0.6.0 交付记录](docs/releases/0.6.0.json)、[14 步维护复核演示](examples/review/README.md)及 [验收说明](docs/acceptance.md)。

## 0.6.x：真实项目验证

用实际维护反馈决定后续功能优先级。

- [x] 在本地接入两个实际仓库的固定版本：moonbitlang/async 与 moonbitlang/moon；不是上游采用。
- [ ] 记录自然发生的来源变化、误报、漏检及修复过程。
- [x] 为两个首轮案例保存固定提交、检查配置、结果和人工复核记录。
- [x] 首轮报告区分真实断链、工具误报、兼容性限制和未检查内容。
- [x] 根据首轮反馈修复三类兼容性问题，并为可复现问题增加回归测试。

**完成标准**：每个案例都可沿固定提交与复核记录追溯；采用与收益结论由实际数据支持。

首轮已扫描 65 份真实文档、287 条可检查引用，发现两条已核实断链和三类工具兼容性问题。
复现与结论见 [真实仓库验证](docs/field-validation.md)，不推算采用率、总体误报率或工时收益。

## 0.6.1：修复真实仓库暴露的边界（已完成）

- [x] 与 GitHub 一致地处理标题中的 Unicode 标点，消除长破折号锚点误报。
- [x] 区分脚注与普通引用链接，不将脚注正文当作文件路径。
- [x] 支持仓库根路径链接，保留工作区边界与越界拒绝。
- [x] 添加对应回归，重跑两个固定案例，确认真实断链仍被报告。

**完成标准**：三个已复核问题得到修复，前后结果可追溯；新增行为及限制写入使用说明。

0.6.1 发布与消费验证见 [交付记录](docs/releases/0.6.1.json)及 [GitHub Release](https://github.com/Freakz2z/tracecite/releases/tag/v0.6.1)。
兼容性最小样例和两个固定仓库的修复前后结果均已复现；待复核与未检查项继续保留。

## 0.7.0：完善生态接入（开发完成，待正式发布）

让新的 MoonBit 项目更容易使用核心库、CLI 或 Action。

- [x] 增加可直接编译运行的 MoonBit 库接入样例。
- [x] 简化 CI 模板，继续复用项目配置。
- [x] 完善 JSON 诊断字段和兼容性说明，支持消费方稳定处理结果。
- [x] 改善网页失败诊断，帮助维护者区分回源失败和引文需要复核的情况。
- [x] 验证新项目按文档完成库、CLI 或 Action 接入。

**完成标准**：新项目可按文档完成接入，核心库的 native、JS、Wasm 三个编译目标保持验证通过。

开发验证见 [独立库及 CI 接入](examples/library/README.md)、[JSON 契约](docs/json-report.md)。
源码消费、三目标样例和本地新项目接入已通过；正式注册表验证在发布流程中完成，不作为外部采用数据。

## 0.7.x：接入反馈与诊断补齐

- [ ] 收集实际维护者对库、CLI、CI 接入的反馈，继续区分受控演示与外部采用。
- [ ] 根据真实失败案例改进诊断与兼容性回归，不改变报告 v1 的已有字段含义。
- [ ] 评估非 ASCII 大小写和站点特有锚点规则，保留目前说明的限制。

## 更新与发布原则

每次更新都应包含清晰提交、CHANGELOG、可运行示例、相关测试和发布验证。
优先保持现有公开 API、命令和项目配置的兼容性；发生兼容性变化时，在版本记录中明确说明。
第三方组件继续保留各自许可和来源，具体要求见 [第三方通知](THIRD_PARTY_NOTICES.md)。

0.6.1 已正式交付；下一步推进 0.7.0 的库接入样例、CI 模板和 JSON 诊断契约，同时继续收集自然来源变化与实际维护反馈。
项目安装与当前用法见 [README](README.mbt.md)。