用途:把 docs/api/*.yaml 自定义 YAML API 规范发布到 Confluence,一个端点对应一个页面,按域分组挂在父页面下,父页面承载服务概览。输入规范由 neo 的 Architect 编写;本技能只读取规范,不生成规范。
主要能力:扫描端点页(标题为 <METHOD>: <path>),由端点 YAML 组装正文——description 作引言,path_params/query_params/request_body.fields/responses[].fields 转字段表,example 转示例块,business_logic 单独成节,errors[] 转错误响应表;父页面正文为 _meta.overview + _meta.field_info + _meta.common_errors;跳过 health/。按标题匹配已有子页面,规划创建/更新,先建分组再建端点页。
使用方式:先确认 docs/api/*.yaml 存在,否则停止并先运行 neo 生成;取 Confluence 父页面 URL 转页面 ID;用 acli auth status 获取 CONFLUENCE_URL 与 EMAIL,推送时解析写令牌($CONFLUENCE_API_TOKEN 或询问一次)。转换按 publish-reference.md 的规则将 markdown 转为 Confluence storage,页面暂存到 .api-doc-publish/。推送前运行 python3 <ASSET_DIR>/pubcheck.py .api-doc-publish/ 做预检,失败不得推送;推送后做往返校验 python3 <ASSET_DIR>/pubcheck.py --roundtrip .api-doc-publish/storage/<page>.xml .api-doc-publish/refetched/<page>.xml。可选独立复核(默认询问一次)与完整性扫描,确认每个端点与域分组都已同步。
适用场景:需要把 API 规范批量同步为 Confluence 文档树的团队。
限制:不是规范生成器,不是 Bruno OpenCollection 生成器,也不是通用 Confluence 页面编辑器;HTTP 200 不代表内容正确,需依赖往返校验与独立复核。具体认证细节、转换规则与命令参数以 references/publish-reference.md 为准。