api-review daily audit 2026-09-07: zh 200 descriptions, tools/invoke restrictions, api-catalog sync

[flashduty]

api-review daily audit — 2026-09-07

--mode generate --scope all --auto，基线为 flashduty-docs@d9f1496。
本轮没有新增/删除任何 operation（registry 公开行 353，committed spec 354，差集 1 条见下文），因此未改 docs.json（防错铁律 3）。
差异总计 9 files / +42 / -40，全部为下列三类语义修正，逐条见「Diff 逐条可解释」。

Per-module operation changes

module	added	removed	updated
on-call	0	0	1（ZH responses.200.description 本地化）
monitors	0	0	1（POST /monit/datasource/tools/invoke 补 Restrictions）
rum	0	0	5（ZH 200 description）
safari	0	0	10（ZH 200 description）
platform	0	0	0
consolidated openapi.{en,zh}.json	0	0	同步以上 17 处
{en,zh}/openapi/api-catalog.mdx	0	0	+1 行、Monitors 39→40、总计 353→354

1. ZH 200 description 本地化（16 个 operation）

rum 5 个 remote-config、safari 10 个 artifact/sign、on-call 的 POST /schedule/by-person —— 这些是 2026-09-03 / 09-04 新增的 operation，中文规格里 responses.200.description 留成了英文 Success。同文件既有约定是 成功（monitors 40/40、platform 27/27、on-call 190/193 均为 成功），按约定补齐。split 与 consolidated 两处同步，修复后全库 Success 残留 = 0。

2. POST /monit/datasource/tools/invoke 补 Restrictions

该 operation（2026-09-06 d1c68d0 收录）正文只有 Usage 段，缺 ## Restrictions（EN）/## 限制说明（ZH）。限额与权限不是构造值，取自一手证据：

• 速率：生产网关 pgy_proxy.t_api id 18847 rate_limits = api:account 32/s、api:account 2000/60s，updated_at=2026-09-07 10:46:22，与 fc-pgy 9c5494a（feat(monit): raise account rate limit for datasource tool invoke，AQps 5→32 / AQpm 100→2000）一致。
• 权限：pgy_account.t_permission_factor 中 dataSource:read:invokeTool → [3008, 3009] = 数据源查看 / 数据源管理（monit）。与 /monit/datasource/info 因子对完全相同，故沿用其写法（只标读权限）。

3. api-catalog 主索引对齐

{en,zh}/openapi/api-catalog.mdx 缺 /monit/datasource/tools/invoke 行（Monitors 计数 39 实际 40、总数 353 实际 354）—— 即 skill Step 5.5 描述的「第二处手工面」。补行 + 计数对齐；docs.json 导航本已包含该路径（nav 缺口 0），故未动。

Diff 逐条可解释（防错铁律 4）

用 git show HEAD:<path> 读基线做 leaf 级深比较：36 处叶子差异 = 32 处 Fix A（16 op × split+consolidated）+ 4 处 Fix B（1 op × split+consolidated × en/zh），unexplained=0。
JSON 以 indent=2 / ensure_ascii=False 回写，且先验证过 9 个目标文件对 HEAD 字节级往返一致，因此不存在纯排序 diff。
openapi.legacy.zh.json 未被触碰；12 个 spec 文件全部 json.load 通过；仓库自带 lint 门 python3 scripts/lint_openapi.py → OK: 12 spec files, no violations。

findings.unresolved（本轮未改，需人工裁决）

1. 159 个 operation 的 Rate limits 行与 registry / 生产网关不一致（最大簇 141 个：文档写 50/秒·1000/分钟，registry 与生产 t_api 均为 20/秒·300/分钟；另有 rum 4 个 10/600 vs 5/100、3 个 2/20 vs 3/60 等）。批量纠正会产生 >300 行 diff，超出一轮 daily 的预算，且 50/1000 是否算「未声明限额的兜底默认」是产品口径问题 → 留给人工决定，本轮只报不改。
2. POST /monit/rule/dstypes 在 registry 中已被删除，但生产仍在服务：fc-pgy 6be0e3a（2026-09-06）删掉了 dataSourceType:read:list 行，而 pgy_proxy.t_api id 13430 仍 status=enabled、deleted_at=0000-00-00，权限因子 t_permission_factor 也仍 enabled（→ 3002/3003 告警规则查看/管理）。按「registry 行删除不等于线上删除」的证据，保留 spec 中该 operation，请 monit owner 确认是准备下线还是 registry 误删。
3. POST /account/info 缺 Rate limits 行（EN/ZH 均只有 Permissions 行）；registry account:read:info AQps=50 / AQpm=1000。
4. 11 个文件流类 operation 无 application/json 200 example（/insight/*/export、/status-page/subscriber/export、/rum/issue/export、/enrichment/mapping/data/download、/safari/artifact/stream、/safari/session/export 等）。核实后确认其 200 内容类型本就不是 JSON（text/csv / application/octet-stream / application/x-ndjson / multipart/form-data），属于误报，未构造示例。→ 本轮没有任何构造示例，两处新写文本均来自生产库与 registry 一手数据。
5. ScheduleNotify.advance_in_time 缺 epoch 字样：语义是「提前通知秒数」（duration），按 skill 规则不该加 epoch 措辞 → 误报，保持原样。

运行环境与流程缺口（需补知识包）

• 知识包缺少 runbooks/api-review-daily.md 与 runbooks/api-review-apply-patches.py（本会话 knowledge/team_2586851485973/runbooks/ 只有 diagnose-disk-full / diagnose-proxy-5xx / monit-agent-diagnostics / prod-access 四个文件）。因此本轮未能执行「每轮先打补丁」（防错铁律 6），mapping.yaml 对齐与 generate_openapi.py 基线保真补丁均未应用。替代做法：以 git show HEAD: 为唯一基线，先验证序列化字节级往返，再做 leaf 级 surgical 修改 + 深比较，把 diff 压到 42/40 行。
• mapping.yaml 的 providers 与 registry provider 字符串存在漂移：status-page vs statuspage、/calendar/* 实为 provider pgy（mapping 写 event）、/route/* 未被任何 path_prefixes 覆盖、/oncall/license/list 实为 event（mapping 写 oncall）、/rum/data|field|resource 无对应 scope。若按 skill 的 provider 过滤直跑 analyze，这 44 条公开行会被静默丢弃——很可能就是缺失补丁所修的内容。请补回补丁或修正 mapping。
• monit-webapi / monit-edge 不在 flashcatcloud org 下（clone 返回 Repository not found），monitors 模块沿用 HEAD 内容，本轮仅补 Restrictions，未做 handler 逆向。
• 沙箱无 node / mint，Step 6 的 mint broken-links 未执行（以脚本化链接检查代替：catalog 缺失 0、nav 缺失 0）。

校验命令

python3 scripts/lint_openapi.py            # OK: 12 spec files, no violations
python3 -c "import json;json.load(open('api-reference/monitors.openapi.en.json'))"

---

补充：同日二轮核实（go-pkg 到位后新增 2 条 unresolved）

首轮 go-pkg 未克隆成功（GitHub 443 间歇超时），共享信封无法与代码对照；08:12 重试到位（e196752）后补做两项校验，未改动本 PR 的 diff，只追加发现：

6. 信封 schema 双轨不一致（需 owner 定口径）：monitors / on-call / platform / rum 的每个 200 都用 SuccessEnvelope（props request_id+data，required=[request_id, data]，共 596 处引用），而 safari 用 ResponseEnvelope（props request_id+error+data，required=[request_id]，104 处），consolidated 文件里两个 schema 并存。skill 的 generate.md Step 2 把 ResponseEnvelope 写成规范四件套之一 → 两者不可同时为正。对照一手代码 go-pkg/srv/render.go：

   type Resp struct {
       RequestID string `json:"request_id"`
       Err       *Error `json:"error,omitempty"`
       Data      any    `json:"data,omitempty"`
   }

   成功分支只填 RequestID+Data（error 必不存在），失败分支只填 RequestID+Err。故 200 响应里 error 永不出现（SuccessEnvelope 在这一层更准确），但 Data 带 omitempty：handler 传 srv.JSON(ctx, nil) 时线上响应就是 {"request_id": "..."}，没有 data 键 → required=[request_id, data] 对这类 operation 偏严。本轮未逐 handler 统计哪些接口实际返回空 data（属 353 op 逐个取证，非 daily 预算），故只标注口径问题、不改文档。
7. raw_message 确认不属于公开契约：srv.Error.RawMessage 带 json:"raw_message,omitempty"，理论上可上线；实测 grep go-pkg/srv/*.go 与 fc-pgy（排除 _test）无任何 RawMessage( 赋值点，12 个 spec 文件也无 raw_message 字样 → 现状一致，非缺陷，留此记录以证伪「文档漏字段」这一假设。

顺带核实（结论为「一致」，无需改动）：文档 ErrorCode 20 个枚举值 = go-pkg/srv/error.go 的 22 个代码值减去 RequestImageVerifyRequired、RequestAliyunVerifyRequired 两个只在 controller/captcha、controller/mfa、access/login 出现的值，而这三处正是 mapping.yaml 中 hidden 的 _internal/captcha 与 auth≠all 的登录链路 → 20 个的口径正确。