# AI 改动说明（ai-changes）

本目录存放**由 AI 协助完成的改动**的说明文档，目的是让人工审核在 Gogs 的「改动对照」页面上
就能直接看到「改了什么 / 为什么这么改 / 与原来的差别 / 怎么验收的 / 有什么已知取舍」，
不必再去翻外部文档。

## 为什么要放进分支里

改动说明**必须随改动一起提交到分支**，这样它才会出现在改动对照（compare）页面里：

```
http://39.97.59.228:8013/hrx/<repo>/compare/master...<分支名>
```

放在仓库外面的说明文件（例如 `/root/TFAgents/docs/...`）不会出现在对照页，审核人看不到。

## 命名约定

```
docs/ai-changes/<YYYYMMDD>-<简短主题>.md
```

- 日期用**改动/交付当天**的日期（本地时区 Asia/Shanghai），便于按文件名排序找到最新一批；
- 主题用 ASCII 短横线连接的小写单词（例：`agent-token`、`sec-cleanup`、`perf-load-v5`）；
- 同一天同一分支多次追加说明时，直接**更新同一个文件**，不要新建（避免同一批改动出现多份说明）。

## 每份说明应包含

1. **头部**：对照网址、依据文档、分支、基线、日期、交付版本、状态（是否已验收/已交付/已部署）；
2. **提交清单**：本次分支上有哪些提交（功能提交 + merge 提交）；
3. **改动面**：涉及哪些文件、各改了什么；
4. **逐项说明**：每项都写清「原来的行为 / 现在的行为 / 为什么这么改 / 与原来的差别」，
   关键取舍（例如「令牌是可选语义，不能改成强制登录」）必须写明，便于人工判断有没有改错业务形态；
5. **验收证据**：怎么验的、结果如何、失败项的实际现象；**验收中发现并修复的缺陷要单独标出**；
6. **静态检查**：lint / 类型检查的命令与结果，以及**哪些是既有问题**（避免被误认为新引入）；
7. **已知取舍**：明确写清未做的部分与原因，不要让审核人以为漏了；
8. **交付状态与上游同步**：fork / 主仓库 / 是否 merge 了最新 `upstream/master` / 是否部署。

## 已有说明

| 日期 | 文件 | 分支 | 主题 |
|---|---|---|---|
| 2026-09-15 | `20260915-mky-vent-base-agent-token.md` | `fix/base-agent-token` | M1 点选补令牌 / M2 结构化错误 / M3 管理入口按 `is_admin` 收敛 |