mky-vent-base/docs/ai-changes

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 收敛