Skip to content

docs(api): translate safari zh envelope descriptions (daily audit 2026-08-27) - #316

Merged
ysyneu merged 1 commit into
mainfrom
api-review/20260827-081510
Aug 27, 2026
Merged

docs(api): translate safari zh envelope descriptions (daily audit 2026-08-27)#316
ysyneu merged 1 commit into
mainfrom
api-review/20260827-081510

Conversation

@flashduty

@flashdutyflashdutyBot commented Aug 27, 2026

Copy link
Copy Markdown

Daily API audit 2026-08-27 (scope: all, audit-only)

本轮按确定性审计流程执行(知识包缺少 api-review-apply-patches.py / api-review-daily.md,生成管线被阻塞,沿用 08-24 起建立的审计流程;审计方法见记忆程序)。

审计结果(registry vs 基线,均以 git show HEAD:<path> 读取)

  • pgy registry(fc-pgy origin/main @ 7c1c7a86):auth=all 行 338(含 /event/push/ 行 0)
  • spec 操作合计:338(on-call 191 / platform 27 / monitors 42 / rum 36 / safari 42)—— 与 registry 逐条 (method, path) 比对:missing=0, extra=0
  • en/zh parity:5 模块 paths / operationId / schema 键全部一致
  • consolidated openapi.en/zh.json vs split:0 drift
  • docs.json pages allow-list:5 模块 × 2 语言 missing=0 / extra=0(无需 reconcile;无操作增删,docs.json 未改动)
  • {en,zh}/openapi/api-catalog.mdx:均 338 行,模块计数与 spec 逐一吻合(未改动)
  • scripts/lint_openapi.pyOK: 12 spec files, no violations
  • 示例契约(requestBody/200 的 application/json example):0 缺失(/rum/issue/export 为 text/csv、/safari/session/export 为 application/x-ndjson、/safari/skill/upload 为 multipart/form-data,均非 JSON 通道,不适用 JSON example 要求)
  • Unix 毫秒时间字段描述规范扫描:0 问题

本次修复(唯一 drift)

safari zh 双语契约漂移safari.openapi.zh.jsonResponseEnvelope.request_id / ResponseEnvelope.data 的 description 为英文句子(其余模块 zh 文件均为中文/空),违反 bilingual contract。已译为中文,并同步 consolidated openapi.zh.json 保持一致。

  • diff:2 文件,各 2 行;无 API 表面变化(新增/删除/更新 operation:0)
  • 纯文本翻译,无需 dev API 调用,本轮无构造示例

观察项(未改动,记录备查)

  • mapping.yaml(skill 侧)缺少 17 条已注册路径的 path_prefixes/monit/query/*/monit/servicemap/*/monit/targets/monit/tools/*(11 条)、/route/*(3 条)、/rum/data/*/rum/field/*/rum/resource/*(3 条)。这些路径已在 spec 中(registry==spec 零漂移),但下次全量生成时若无 mapping 覆盖会被当作 unresolved 丢弃,建议后续补 mapping 前缀。
  • 本环境无法调用 dev API 抓真实响应示例(无凭据环境变量),本轮不涉及示例构造。

验证

  • python3 scripts/lint_openapi.py → OK
  • consolidated vs split 深比较 → 0 drift
  • JSON 解析全部通过

@ysyneu
ysyneu merged commit 86d94ed into mainAug 27, 2026
2 checks passed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@ysyneu