# 持续维护试用

TraceCite 的价值需要由反复维护时的结果验证：发现了什么、需要读多少诊断、如何决定修复或接受变化，以及再次检查能否通过。本页记录可重放的历史案例，并提供实际接入时的记录方法。

## 已完成：真实提交的历史回放

范围为 moon 项目的 docs/manual/src/commands.md 和 docs/manual-zh/src/commands.md。
固定提交、诊断、覆盖统计和各步骤的退出码见 [机器回执](field-validation/maintenance-history.json)。
这是上游真实提交的本地回放，没有修改上游文档，也不代表上游使用了 TraceCite。

这次上游改动为搜索结果增加仓库地址，并同步更新了两份文档。原有目录链接观察的搜索章节发生变化，所以两处目录链接要求复核。
本次开发复核上游差异后的结论是：文档已正确更新，可以接受新的基线；本案例没有新发现的错误文档。这是开发过程中的分析，尚未取得上游维护者反馈。
两处变化继续返回退出码 2；复核并更新基线后返回 0。80 条本地引用得到检查，2 条网页引用未检查。

这暴露了阅读负担：原报告为这两处各增加 17 个字符的变化展示完整章节。
0.8.0将来源变化的展示文本聚焦到变化附近，保留省略标记；检测结果、覆盖数量和完整候选快照保持一致。
本次开发构建的展示量从 3170 字符降到 850 字符，减少约 73%；二进制摘要见回执。这不是正式发布记录。
具体字符数见回执中的 changed_display_characters，按 items 中两条变化的 previous 和 actual 各统计一次，不重复计入 review 分组或完整预览 JSON。
字符数减少不是人工工时减少；尚未测得维护者实际复核时间。

## 复现

需要 Git、Python 3，以及0.8.0 native CLI（从源码构建或安装独立包）。首次获取固定上游提交需要网络，TraceCite 检查本身离线执行。
输出目录必须尚不存在；脚本只在该目录的隔离仓库中写配置和基线。

```sh
moon build --target native
python3 scripts/maintenance_history_replay.py \
  --binary _build/native/debug/build/cmd/main/main.exe \
  --out _build/maintenance-history/new-run
```

如果已有包含两个固定提交的本地 moon 仓库，可加 --repository 指向它，省去下载。
如需复现展示量对比，先从 TraceCite 提交 08bb25c3f3127bf491dce4b5c11347a929792103 构建旧 CLI，复制到独立路径，再给上述命令增加 --compare-binary 指向旧 CLI。
脚本会核对两个构建的全部诊断与完整快照，只有变化条目的展示文本和工具版本允许不同。

输出保留每一步 JSON、stderr、原始文档差异和 receipt.json。回执记录二进制 SHA-256、上游提交、命令参数、退出码、机器执行时间与覆盖范围。
脚本只接受已逐字核对的这一次仓库地址说明更新，不是通用的自动基线审批工具。
原始报告和上游文本保留在本地输出目录；提交的回执不复制上游正文。

## 实际项目试用记录

实际使用先按 [维护说明](maintenance.md) 选择文档范围，完成 init 后把同一条 check 命令加入 CI。
来源变化先运行 --preview-baseline，结合真实提交判断是否需要修改文档，再决定是否更新基线。
来源变化提示本身不等于文档错误；需要把有效变更复核与真正发现的断链、过期片段分开记录。

| 记录项 | 填写要求 |
| --- | --- |
| 项目和范围 | 仓库、前后提交、文档路径、排除项、工具版本与配置 |
| 首次接入 | 初始诊断、人工分类、配置理由、实际接入分钟数 |
| 自然变化 | 真实提交、失败命令和退出码、文档行、诊断码 |
| 分类与依据 | 真实文档问题、正常来源变化、工具错误或待确认；附复核依据 |
| 处置 | 修正文档、修复工具或接受基线；保存差异与再次检查结果 |
| 维护成本 | 维护者实际记录的阅读和处置分钟数；未测量填未记录 |
| 覆盖与反馈 | 网页跳过、未绑定片段、引号策略；维护者是否愿意保留 CI 及原因 |

下一步需要至少一轮真实维护者的持续使用记录，才能评价保留 CI 的意愿和实际维护收益。
历史回放及工具测试不能替代这一证据；没有反馈时保持未完成，不推算采用率或节省工时。