# AI 使用说明（O-3）

本文件说明 JSONMend 的开发过程中**用到了哪些 AI 工具、用在什么地方、哪些判断不能外包**，
以及如何核验「写下来的结论」确实是跑出来的。目的是让评审者能区分
「AI 生成的文字」与「本仓库里可复现的证据」。

## 1. 用了什么

| 工具 | 用途 | 不用于 |
| --- | --- | --- |
| AI 编码代理（Claude / DeepSeek 系列，经命令行界面） | 起草实现、重构、写测试与文档、跑命令并读结果 | 决定验收标准、决定设计取舍、判断「算不算达标」 |
| `moon` 工具链 | 编译、测试、覆盖率、格式化、打包 | — |
| `json-repair`（Python）/ `jsonrepair`（Node） | 差分对照的**参照实现**（进程外调用） | 不作为真值来源（它们是另一个实现，不是事实） |
| Python / Node 脚本 | 语料生成、评测驱动、报告生成 | — |

参照实现的代码不进入本仓库、不进入任何构建产物，只在测试时以子进程方式调用。

## 2. 人工判断点（不可外包）

以下决策由人做出，并且在文档里写明了理由；AI 只负责执行与记录：

1. **验收判据**：`code/docs/EVAL_REGISTRATION.md` 里的四条判据、数据集种子、
   排除规则，都在**跑之前**写好并冻结（含数据集 sha256）。评测脚本只负责执行，
   不允许在看过结果之后改判据。
2. **语料修订的边界**：`eval-1` 跑完后发现 101 条「差异」其实是语料本身站不住
   （撇号歧义、裸 token 合并、标量根 prose、截断的祖先语义）。修订只允许
   **收紧生成器的适用条件**（让用例有唯一正确答案），不允许「事后排除用例」；
   全部 101 条与 300 条标签误报的归因写在 `EVAL_REGISTRATION.md` §10。
3. **严重级别的语义**：哪条修复算「只改记法」（Info）、哪条算「发明或丢弃信息」
   （Warning），由人判断并写进 `docs/RULES.md`。它直接决定 `Exactness` 标签，
   因此是最不能交给 AI 的一步。
4. **未达标项的公开**：增量流吞吐（1.39–1.51× 基线）、内存（17.6–38.0×）、
   JS 线性度（4n/2n 到 2.8）都写在 README、`BENCHMARK.md`、`TRACEABILITY.md`
   和本文档里，标注为未达标。**这些数字不是 AI 算出来的「成绩」，是命令的输出。**
5. **竞品声明的引用**：`README.md` 的对照表逐条引用对方 README 原文（英文原文保留），
   并在 2026-10-15 重新抓取页面核对。引用而不是转述，是为了让读者能自己验证。

## 3. 证据链：怎么核验

每条结论都能追到一条命令。最短路径：

```bash
export PATH="$HOME/.moon/bin:$PATH"
cd code

moon check --deny-warn          # 0 警告（警告即错误）
moon fmt --check                # 格式无差异
moon test && moon test --target native && moon test --target js   # 69/69 × 3
bash tests/cli_smoke.sh         # 36/36
bash tests/examples.sh          # 6/6
node tests/demo_smoke.mjs       # 演示 bundle
python3 tests/gen_llm_fixtures.py --check                  # 夹具与生成器同源
python3 tests/eval/run_eval.py --cli <jsonmend>            # 真值评测（四条判据）
python3 tests/diff/run_diff.py --cli <jsonmend> --no-stamp # 差分（与 docs/DIVERGENCES.md 逐字节相同）
bash tests/bench.sh             # 性能与体积
```

完整清单与期望值见 `docs/REPRODUCE.md`。CI（`.github/workflows/ci.yml`）执行同一组命令，
并把评测报告作为 artifact 上传。

## 4. AI 参与的部分与人工验证方式

| 部分 | AI 的参与 | 人工/机器验证 |
| --- | --- | --- |
| 引擎与 API（`*.mbt`） | 起草与重构 | 126 条黄金用例 + 3 200 次属性测试 + 三后端同源结果 |
| 规则与级别 | 按人工给出的语义实现 | `error_api_wbtest.mbt` 机器校验 22 个码的编号/名称/级别/消息一一对应 |
| 增量流 | 设计与实现 | 800 份文档的「增量重放 == 快照」属性测试 |
| `jsonmend/llm` | 设计与实现 | 9 个夹具（生成器与 MoonBit 内嵌副本同源）× 双 provider，19 个测试 |
| 评测语料与驱动 | 按人工冻结的协议实现 | 语料 sha256 写进登记文件；四条判据由脚本判定 |
| 文档数字 | 起草 | 每个数字都来自本文 §3 的命令；差分报告由脚本生成，`--no-stamp` 逐字节可复现 |
| 竞品对照表 | 起草 | 引用对方 README 原文，页面抓取日期写在表头 |
| 0.5.0 安全层（`policy`/`decision`/`plan`/`schema`） | 设计（按 `优化.md` 的优先级）与实现 | 34 条新测试；其中 5 条是「测试先失败再改实现」，改了哪些、为什么改单独列在产品文档 §19.1 等你复核 |
| 0.5.0 独立语料与骨架就绪表 | 起草 harness | 语料逐字节 vendor（`diff -r` 与上游一致）、指纹写进报告；就绪表的 `--check` 强制「既有落差也有并列」，否则脚本失败 |

## 5. 已知的 AI 参与带来的风险

- **文档与实现漂移**：AI 容易写出「应该是这样」的描述。对策是让关键表格由测试
  或脚本生成（`EVAL.md`、`DIVERGENCES.md`），其余表格在每次改动后按命令输出重抄，
  并在 `REPRODUCE.md` 里给出复现命令。
- **过拟合评测**：语料与实现若由同一个模型提出，容易互相迁就。对策是
  ①协议先冻结、②语料真值由**变异前的原值**决定（不是由 jsonmend 的输出决定）、
  ③同时保留与两个独立参照实现的差分测试。
- **未验证的声明**：`nightly.yml` / `release.yml` 是本机无法触发的（`curl` 到 github.com
  超时、`gh` 未认证），因此在文档里明确写成「已写好、未在 GitHub 上跑过」，
  而不是默认它会工作。0.5.0 新增的 `live.html` 同理：浏览器验证只在本机做过
  （Playwright 无头），CI 里只跑帧级断言。
- **「AI 起草文档」的最大风险是自我一致**。0.5.0 的三处改动是**测试先失败**逼出来的
  （`stringify` 丢了 `?`、`hex_digit` 大小写、`one_line` 的转义），
  且都写进产品文档 §19.1 请你复核——因为这三处都是「我改实现去迎合我的测试」
  还是「我改测试去迁就实现」的判断题，AI 不该自己拍板。