Nacos API Doc Update

Nacos API 文档更新

根据 Swagger 导出的 api.json 更新文档仓库中的 API 文档（console-api、admin-api、open-api）。建议按每个 api.json 拆分子计划执行，避免混淆不同文档的格式。

0. 冻结输入基线，避免一次任务使用多套事实

每轮更新只能使用一份已冻结并校验过的输入快照。开始编辑前必须完成：

1. 记录来源：记录六份 Swagger 的 URL、抓取时间、info.version、operation 数量和 SHA-256，以及参考 Nacos 源码的 branch、HEAD 与工作区状态。子任务只读这份快照，不得各自重新抓取或覆盖 Swagger。
2. 源码新鲜度门禁：若 live Swagger 包含本地源码没有的 operation，或本地源码包含 live Swagger 没有的已实现 operation，先判定为 freshness mismatch；不得用较旧一侧删除 API 或修改业务语义。参考源码是否同步必须遵守工作区 AGENTS.md，未经允许不得自行 pull、切分支或修改源码。
3. 安全刷新：禁止使用 curl ... > public/swagger/.../api.json 直接覆盖已跟踪文件。必须先写临时文件，确认 HTTP 成功、JSON 可解析、存在 openapi、paths 非空、operation 数量合理、同一 API 的中英文结构一致，再批量替换。
4. 同轮一致性：一个 API family 的 zh/en 必须来自同一次服务快照；任一 locale 失败时保留该 family 原有的一对文件，禁止一新一旧。运行中若版本、operation 数量或结构 fingerprint 变化，废弃旧对比结果并从头重跑。

本 skill 提供安全刷新脚本，内部仍使用 curl --fail，但只在整批校验成功后替换目标文件：

python3 .agents/skills/nacos-api-doc-update/scripts/refresh_swagger.py

只校验仓库中现有快照而不联网、不写文件：

python3 .agents/skills/nacos-api-doc-update/scripts/refresh_swagger.py --validate-existing

冲突时按信息维度裁决

• 已适用且已实现的 Spec：业务语义、生命周期和兼容方向。
• 与该构建匹配的 Controller、Form、公共模型、服务校验和 IT：实际字段、FQCN、业务必填及错误路径。
• 同构建 live Swagger：wire operation 清单、method/path、媒体类型和已正确表达的参数契约。
• checked-in Swagger 与旧文档：仅作为抓取失败时的回退参考。

标记为 target、future 或 experimental 且尚未实现的 Spec 不能单独作为“当前已有 API”的依据。若 live Swagger 与 Spec/源码冲突，先报告生成问题，不得机械用冲突后的 component 覆盖正确文档。

执行顺序：必须先尝试更新 api.json

每次执行本 skill 时，在生成或更新文档之前，必须先尝试用 curl 拉取最新的 api.json（覆盖对应 public/swagger/... 下的文件）。
仅在安全刷新失败时（例如本地 Nacos 未启动、端口不可用、网络错误、JSON/OpenAPI 校验失败或 zh/en 结构不一致）才使用仓库中已有的完整 api.json 快照进行生成，并在结论报告中说明「本次未更新 api.json，原因：xxx」。

不得以「仓库中 api.json 已修改」「担心本地服务未启动」等为由跳过更新步骤；默认行为是先执行更新，失败再回退到已有文件。

交付要求：交付经过验证的正确状态

通常应把已确认的差异实际修改并保存到文档文件，而不是只创建脚本或生成未写入的文本。但验证后无差异的 no-op 是合法结果；禁止为了“产生变更”而改写措辞、类型格式或示例，制造下一轮反向修改。

• 结论报告中「已更新文档」须与仓库中实际发生变更的文件一致；若最终没有任何 .md 文件被修改，须说明「全量门禁通过，无需修改文档」。

更新方式：对比后针对性更新（禁止整段覆盖）

禁止使用批量替换脚本。禁止使用会整体覆盖文档段落或整篇的 sync/patch 脚本（如 sync_doc_from_swagger.py 及其同类脚本）。此类脚本会覆盖已有内容，导致参数描述、返回说明、示例（如 curl 中的真实示例值）丢失。仅允许使用仅对比、不写文件的脚本（如 compare_doc_with_swagger.py）生成差异报告，再在文档上做针对性、逐处修改。

正确流程：

1. 用 swagger_to_md.py 根据 api.json 生成参考用的 Markdown 片段（可针对单个接口或整篇，用 --filter-path 等控制）。
2. 对比「生成的片段」与「已有文档」中对应接口（按 #### 请求URL + 请求方式 匹配）。
3. 在已有文档上做针对性更新（直接编辑对应的 .md 文件）：
   • 与 api.json 对齐：参数表增删（文档多出的参数删掉、缺失的参数补上）、类型/必填与 api.json 一致；请求 URL、请求方式、鉴权状态按需修正；curl 示例中的 URL/参数名与 api.json 一致。
   • 起始版本同步（强制）：每个 Swagger operation 若包含 x-nacos-api-since.version，文档中对应 API 小节必须在「接口描述」之后、「请求方式」之前增加或更新 #### 起始版本，内容为反引号包裹的版本号，如 `3.2.0`。若已有起始版本与 api.json 不一致，以 api.json 为准更新。新增 API 小节也必须包含该字段。
   • 保留已有内容：已有文档中的参数描述、返回字段描述、请求示例 / 返回示例（含手写示例）应尽量保留；仅当某参数已从 api 移除时删掉该参数行，仅当缺少某参数时补上一行（描述可先来自生成片段或简写，后续再润色）。
   • 手写增强内容保护（强制）：对文档中已有的手写增强内容（如参数说明扩展表、命令映射表、注意事项）即使 swagger 中无对应字段，也不得删除。这类内容默认视为高优先级人工补充，除非用户明确要求移除。
   • 空描述补全（强制）：对“新增参数但描述为空/占位符（如 -）”的情况，必须结合接口描述、参数名、上下文给出可读描述；不要直接保留空描述。已有参数描述除非明显错误，否则保持原文。
   • 语言一致性（强制）：zh-cn 文档新增或修改的参数描述必须是中文；en 文档必须是英文。禁止在 zh-cn 参数表中出现英文描述（专有名词除外）。
   • 文件字段类型约定（强制）：对 multipart/form-data 请求体中 format: binary 的字段（如 file），文档参数类型统一写为 file（或 file(binary)），禁止回写为普通 string。对比时需把 string(binary) 识别为文件字段语义，不得误判为普通字符串。
   • 类型写法统一（强制）：基础类型和容器关键字统一使用小写规范：string、integer、number、boolean、file、object、array、map。容器必须保留元素和值类型，如 array<integer>、array<string>、map<string, string>；禁止把已知的 array<T> 简化成 array。
   • 命名领域类型保护（强制）：上述小写规则不适用于 Swagger $ref 指向的命名 schema。只要字段引用了明确的领域类型，尤其文档紧邻位置已有该类型的展开表或说明，就必须保留 schema 名称及其上下文，例如 ServerVersionDetail、McpServerRemoteServiceConfig、McpServerValidationItem、AgentCapabilities、array<AgentSkill>；禁止泛化为 object 或 array<object>。只有在排除同名碰撞、并由 operation 上下文和源码确认后，才能按当前 Swagger 同步 schema 名称及展开说明。
   • 必填语义分层（强制）：区分 transport required、business required 和 conditional required。Swagger 正确表达时按其 required；源码明确缺失必然失败但 Swagger 漏标时，文档标为必填并添加精准、可追溯豁免；互斥或按场景生效的字段写“条件必填”及条件，禁止把两端都简单标成必填。
   • 统一返回体层级（强制）：Result<T> 的 code、message、data 位于响应根层级。返回数据表若只描述业务数据，应写作 data、data.field；禁止把统一返回体再次包进 data，生成 data.code、data.message、data.data。data 自身引用命名 schema 时，类型必须写为 T（分页则为 Page<T>），不能只展开字段而丢掉根类型。
   • 文档结构约定：请求体类型仅在「请求方式」中标注，不要在「请求参数」下重复写「请求体为 xxx」。若接口无 query 仅有 body，请求参数下只保留一个参数表，不要添加「无（Query 参数）」或单独的「请求参数」块；对比脚本已适配「单表且 api 无 query 则视为 body」。
   • 单标题单表约定（强制）：每个 API 小节下仅允许一个 #### 请求参数 标题。即使同时存在 query 与 body 参数，也必须合并为一个参数表展示；禁止再拆出第二个 #### 请求参数。如需提示来源，可在“描述”列中注明“Query 参数/Body 参数”。
   • 表格结构约定（强制）：若现有文档在同一接口下有“参数表 + 说明表”等上下关联的连续表格，禁止在两表之间新增任何小标题（如 #### 命令说明）；保持原有标题层级与相邻表格结构不变。
4. 若某接口在 api.json 中为新增（文档中尚无对应小节），可将生成片段作为新小节插入文档，再按需润色描述与示例。

即：以生成片段为参考做对比，只改需要同步的项，不整段替换，避免覆盖掉已有的描述和示例。

额外强约束：按 API 粒度比对并保持原有顺序

为避免“新增接口导致整篇顺序漂移”，更新时必须遵守以下规则：

1. 比对粒度必须是单个 API：以 请求方式 + 请求URL 作为唯一键，逐个接口比对与修改；禁止把整章/整段作为比对与替换单位。
2. 保持原文档章节顺序：已有章节（如 ## 4. MCP 管理、## 5. A2A 管理）及其先后顺序必须保持不变，除非用户明确要求调整。
3. 保持原接口顺序：已存在的接口小节顺序必须保持不变；仅在对应章节中插入“新增 API”小节，默认追加到该章节末尾（或按用户指定位置插入）。
4. 禁止整段替换到章节尾：禁止执行“从某个 ## 标题替换到文件末尾”这类操作；如需修改多个接口，也必须逐个接口定位并编辑。
5. 编号仅做局部修正：若插入新增接口影响 x.y 编号，只在该章节内做连续编号修正；不得跨章节重排编号。

建议执行顺序：

• 先从现有文档抽取接口顺序清单（method + path）。
• 再将 swagger 差异映射到该清单，按接口逐项更新参数/URL/curl。
• 最后仅为新增接口补充小节，并在该章节内校正编号。

1. 更新 Swagger api.json

在文档仓库根目录（nacos-group.github.io）下执行（需本地 Nacos Console 端口 8080、Nacos Server 端口 8848 可用）：

python3 .agents/skills/nacos-api-doc-update/scripts/refresh_swagger.py

可用 --scope admin|console|client 只刷新一个 family，但该 family 的 zh/en 仍必须成对刷新和校验。脚本失败时不得手工把失败响应写进目标文件；保留旧快照，并在结论中报告失败原因及本次实际采用的 Swagger provenance。

2. Swagger JSON 与文档路径映射

i18n → locale：Swagger 目录为 en、zh；文档路径中 en 不变，zh 对应 zh-cn。

双 locale 同步：同一类型文档（console-api / admin-api / open-api）存在 zh-cn 与 en 两套。对任一侧做了修改（参数表、新增接口、curl 示例、描述等）后，应对另一侧做同等更新，保持中英文一致。仅当用户明确要求「只更新 zh-cn」或「只更新 en」时，才只改一侧；否则默认同时更新 zh-cn 与 en。

3. 找出变更并生成参考 Markdown

• 读取 api.json（paths、components/schemas）与对应的 *.md。
• 通过 path + method 对齐已有文档中的接口（如 #### 请求URL 后的 path 或标题）。
• 找出新增或发生变更的 API（path/method/参数/返回结构/x-nacos-api-since.version 起始版本变化）。
• 使用本 skill 自带的 Python 脚本（仅 swagger_to_md.py）生成符合现有 api.md 风格的 Markdown 片段，作为对比参考，不要用任何 sync 脚本把生成内容整段写回文档。