docs(api): daily audit 2026-10-06 — localize the remaining English text in the zh specs

[flashduty]

本轮结论

--mode generate --scope all --auto 的每日审计。新增/删除/变更的公开 API operation 均为 0；本轮唯一落地的是中文规格里残留的英文人类可读文本（60 处，纯文本值替换，不动任何 key、schema、示例值）。

scope 与公开面判定

• --scope all，公开面判定按 skill：auth == "all"、路径不以 /event/push/ 开头、模块未标 hidden: true。
• registry（fc-pgy logic/api/api_test.go）共 1209 行，其中 auth == "all" 366 行，与上一轮（PR docs(api): daily audit 2026-10-05 — document the Monitors dashboard family (18 new app_key operations) #1011）完全一致 → 无 auth 翻转。
• 332 行被 mapping.yaml 认领；另 34 行（/monit/dashboard/* 17、/monit/query/* 2、/integration/* 9、/route/* 3、/rum/data|field|resource 3）未被 skill 内 mapping.yaml 认领，但这些路径已全部在 committed spec 中（由已合并的 docs(api): daily audit 2026-09-25 — document the new /integration API family #472、docs(api): daily audit 2026-10-05 — document the Monitors dashboard family (18 new app_key operations) #1011 落地），只是本 skill 的工作副本 mapping.yaml 未同步 —— 不是文档缺口，已在本轮 PR body 记录（见「环境事实」）。

窗口 diff（2026-10-05T08:25Z → 2026-10-06T08:25Z）

对 8 个源仓库做窗口 diff（git rev-list -1 --before=... origin/main + git diff --name-only <base> origin/main，后者用于兜住「作者日期在窗口前、窗口内被 merge 进 main」的提交）：

仓库	origin/main	窗口内变更
fc-pgy	ac1e2bc8	3 提交（2a93b64f/d6f5d743/c25a23a6）
fc-event / fc-oncall / fc-rum / fc-statuspage / fc-datasource / go-pkg / monit-webapi	未变动	—

fc-pgy 的 3 个提交只改 logic/api/api_test.go、deploy/permission.sql、logic/permission/permission_test.go，内容是 Knowledge Pack → Knowledge 的中文改名：5 行 NameCN（知识.知识包：X → 知识.知识：X）、权限 4004/4009 的 知识库 → 知识。path / method / auth 未变。

对 spec 无影响：committed 的 5 个 split + 2 个 consolidated 中 知识包 / Knowledge Pack / knowledge pack 残留为 0 处，ZH summary 早已是「查看账户知识 / 查询知识列表 / 删除知识 / 确保知识存在 / 更新知识」。operationId 由 registry name（knowledge.pack:*，未变）派生，也不受影响。→ 本轮不为这个改名改任何东西。

各模块 operation 变化

模块	added	removed	updated（operation 形状）	本地化文本替换
on-call	0	0	0	16
monitors	0	0	0	0
platform	0	0	0	0
rum	0	0	0	4
safari	0	0	0	13
consolidated openapi.zh.json	0	0	0	27

docs.json 与 {en,zh}/openapi/api-catalog.mdx 未改动：无页面增删，按规则 3 不动（改导航顺序也会造成大 diff）。

本轮改了什么（规则 7 的类别）

ZH 规格中没有中文字符的人类可读文本（description / summary / allOf[].properties.data.description 等文档字段，不含 example/examples 载荷值）。判据是仓库里已有既成中文译文，属于「同一字段在不同模块被翻译、在少数模块漏翻」的漂移：

• safari split 是共享组件的漏翻者：AppKeyAuth、BadRequest/Unauthorized/Forbidden/TooManyRequests/ServerError、ResponseEnvelope 在 safari 是英文，而在 on-call/monitors/platform/rum 四个 ZH split 中早已是逐字相同的中文。修法是从既成译文照抄（如 Status page ID. → 状态页 ID。，Invalid request — … → 请求非法 — 通常是参数缺失或格式不正确。），不新造措辞。
• safari 自身也不一致：Always null on success. 有 6 处英文，同一文件里同类字段另有 7 处已是中文 成功时恒为 null。 → 按多数派取值统一。
• on-call ZH：16 处 GET parameters[].description 为英文（/status-page/*、/incident/post-mortem/info）。
• rum ZH：4 处（/rum/issue/export 的 CSV schema 与 X-Export-Total/X-Export-Truncated 响应头、/rum/session-replay/segments 的 NDJSON schema）。
• consolidated openapi.zh.json：同上 27 处。

改动脚本 /tmp/apirev/apply-zh.py：只替换「非 example 块内、且取值恰好等于英文原文」的 description/summary/title/x-mint.content，不新建、不删除、不重排任何 key；默认 dry-run，--apply 才落盘。

规则 4：PR 前全树深比较

• 逐叶校验：对 4 个改动文件做 HEAD（git show HEAD:<path>）与工作区的递归叶比较，共 60 个叶变化，全部落在 description/summary/title 且均不在 example 块内（脚本断言，非本地化字段的变化数 = 0）。
• 无假删除：默认 Myers 与最小化算法给出同一结果 ——
  • git diff --numstat → 16/16、27/27、4/4、13/13
  • git diff --numstat --minimal → 完全相同（没有出现大块「先删后加」）
• EN 与 legacy 未被触碰：git diff --name-only 无 *.en.json，无 openapi.legacy.zh.json。

改后复核（全部重跑）

• 5 个模块 EN/ZH 结构 parity（屏蔽 summary/description/title/x-mint/tags/name/x-enumDescriptions/examples 后）= 0 差异。
• EN/ZH example 块逐字相等 = 0 差异（429/91/73/102/114 个 example 块）。
• epoch int64 字段描述缺口 = 0（*_at/*_time/ts/timestamp 均含 Unix/epoch/timestamp 字样，go-flashduty SDK 约定满足）。
• 未翻译 ZH 文本重扫：每个文件仅剩 servers[0].description = "Flashduty Open API"（服务名，与 EN 一致且五个模块一致，按 skeleton 不本地化）。
• Step 5.5 可达性：五个模块 spec path → docs.json nav / en catalog / zh catalog 全部 0 缺口，catalog 计数与 spec path 数一致（202/41/28/41/53，总 365）。
• 全部 13 个 JSON 通过 json.load()；mint broken-links 未能执行（本环境无 node/npx），已用 skill 的 Step 5.5 可达性检查替代。

仍按原样保留的 committed 内部漂移（未动，附判据）

1. DutyError.reason：存在于 monitors split + 两份 consolidated，缺于 on-call/platform/rum/safari 四个 split。skill 的 references/response-envelope.md 明确要求 DutyError 恰好只有 code + message；go-pkg main srv/error.go 的 Error 结构体也是 code/message/raw_message，没有 reason。未删的原因：该字段带 "x-flashduty-preserve-absence": true 标记，而该标记在本仓库是既成约定（76 处，涉及 monitors/rum/consolidated，由 d1c68d0e docs(monit): define datasource diagnostics and host-only agent tools 等多个人工提交引入），属人工有意为之而非生成漂移；直接按「以 split 为准」删掉会抹掉人工内容。→ 建议人工裁决：若 reason 不在公开契约内则应统一移除（含 monitors split），否则应补齐到其余四个 split 并放宽 reference。
2. on-call work-item：consolidated 的 WorkItemItem.required 含 assignees（13 项 vs split 12 项）、work-item 的 example 载荷带 assignees 数组、x-mint 使用说明多出 assignee_type/ai_sre 两条 —— split 均无。未动的原因：fc-event main 的 structs/work_item.go 没有 WorkItemItem.assignees/agent_session_id/agent_session_venue，createWorkItemIn 没有 assignees，listWorkItemIn 没有 assignee_type（logic/post_incident 的 CreateInput/ListInput 同样没有）；支撑该特性的提交落在 origin/feat/work-item-ai-sre、不在 main。所以两侧都与 main 不一致，无法用「哪一侧对」来单向对齐 —— 该特性是否已上线本环境无法验证，属开放假设。注意：split 与 consolidated 都有这些 properties 与 WorkItemAssignee schema，差异仅在 required/example/使用说明文本，所以 Mintlify 渲染面已存在该字段，不是本轮引入。

   顺带修正上一轮 memory 的一条判断：上一轮记「consolidated 领先、split 缺 AI SRE 字段」，本轮实测两者都有 properties，领先面仅在 required/example/文案。

3. 上一轮 memory 记「monit-webapi / monit-edge 不在 GitHub」已被证伪：git clone https://github.com/flashcatcloud/monit-webapi.git 成功，origin/main = 41b236a（窗口内未变动）。monitors 的 handler/schema 提取已可直接取源码。

unresolved 清单

path	状态	轮次
POST /channel/incident/daily-counts	registry auth=all，找不到 handler；skill 要求记入 findings.unresolved，不编造路径	连续第 4 轮未决

构造示例说明

本轮没有新增任何 operation（365 个 path 全部沿用 committed 内容），因此没有新构造的示例值。本环境无法调用 dev API 抓真实响应（不能引用凭据环境变量），若未来新增 operation，其示例将按 schema 构造并在 PR body 注明，不会使用 "string" 占位符。

环境事实与阻塞项（影响本轮做法）

1. 团队知识包仍缺 runbooks/api-review-daily.md 与 runbooks/api-review-apply-patches.py（2026-09-30 起连续 3 轮确认缺失）。因此「每轮先打补丁再运行」这一步无法执行；skill 工作副本的 mapping.yaml 因缺少该补丁仍是旧版（未认领 /monit/dashboard、/monit/query、/integration、/route、/rum/data|field|resource 前缀）。
2. scripts/generate_openapi.py 跑不起来：它读取 .api-review/modules/<scope>.json，而 .api-review/ 在 .gitignore 中且不存在；重建这些 module 数据文件正是上述缺失补丁脚本的职责。其自带 guard_no_path_drop() 会在路径丢失时中止（设计如此，不能带伤运行）。
3. 因此本轮按规则 6 的既定替代流程执行：committed 基线（只用 git show HEAD:<path>）+ registry 集合双向比对 + 定向最小 diff。
4. skill 本体未改动（sync_skill 未调用）—— 与既往轮次一致，避免未来从其他来源同步 skill 时约束丢失。
5. mint broken-links 无法执行（无 node/npx）。

复核命令

git show HEAD:api-reference/openapi.zh.json > /tmp/base.json
python3 -c "import json;json.load(open('api-reference/openapi.zh.json'))"
git diff --minimal --numstat