当产品有周期性变更日志时…

适用于维护一套面向当前行为的技能/文档仓库，需要根据已合并的变更日志做定向更新并提交 PR 的场景。

适用场景

解决思路

1. 从自动化触发器或用户消息中解析出 CHANGELOG_DATE（YYYY-MM-DD）。
2. 用 gh api 拉取已合并的变更日志文件：gh api "repos/<org>/<repo>/contents/<path>/${CHANGELOG_DATE}.md?ref=main" --jq '.content' | base64 -d > "/tmp/changelog-${CHANGELOG_DATE}.md"；若文件不存在则停止并报告该日期没有已合并的变更日志。
3. 必要时同时阅读已发布的变更日志页面（如 https://<docs-site>/changelog#${CHANGELOG_DATE}T00:00:00.000Z）。
4. 做相关性过滤：把变更逐条映射到受影响的技能，判断标准是是否影响技能中记录的模型表、代码示例、参数文档、配置表或 CLI 命令；只影响内部/管理 API、无使用层影响的可选字段、向后兼容重命名、与 API key 设置流程无关的定价/仪表盘 UI 的变更视为不相关。
5. 若没有任何技能受影响，成功停止且不开 PR，报告 `No skills-relevant changes for CHANGELOG_DATE`。
6. 对每个相关项记录受影响技能和受影响区域（模型表、代码示例、LLM 提供商表、工具章节、CLI 章节、参数文档、配置表等）。
7. 读取每个受影响技能的 SKILL.md 及其 references/ 下的所有文件。
8. 编辑前先抓取并阅读真实源文档（如 agents 的 create/update、TTS 的 convert、STT 的 convert 等 API 参考页），核对每个字段名、类型、嵌套、允许值、端点、模型 ID、SDK 方法签名；绝不从变更日志措辞推断 schema。
9. 若某功能出现在变更日志但源文档没有足够 schema 细节，不要为它写字段表或代码示例，放入报告的 `Needs Manual Authoring`。
10. 对每个变更项跑适配门：能否映射到现有章节/表/列表/示例的自然位置；只收录主要能力、常见工作流或重要顶层配置概念；跳过边缘情况、优先级规则、持久化细节、回退顺序、实现细节、狭窄例外和弃用说明；没有自然位置就保持不动并归入 `No Skill Change Needed`；只有概念足够重大、可复用、面向用户、高层且当前结构明显缺失时才新增章节；优先记录当前路径，若某字段/端点/模型/模式取代另一个，只记录当前受支持方式，弃用上下文留在报告里。
11. 做最小且定向的编辑，匹配现有标题层级、表格格式、代码块语言、缩进和命名风格；按模式更新：模型表增删改行并核对模型 ID 与描述；代码示例更新方法签名、导入和重要参数，Python/JavaScript/CLI 示例保持一致；LLM 提供商表更新到 agents/SKILL.md 或 agent-configuration.md；工具章节按现有风格加入新工具类型；CLI 章节更新 agents/ 下现有示例；参数文档把已核实参数加入参数列表或表；配置表更新 agent-configuration.md、voice-settings.md 等参考文件中的字段表；输出格式表更新 text-to-speech/SKILL.md 中的输出格式表。
12. 硬性规则：绝不编造字段名、类型、schema、模型 ID、配置名、端点路径或示例值；未核实确切 API 形状前不写新功能的代码示例；把变更日志当作发现输入而非技能文件正文；技能文件必须常青，SKILL.md 和 references/*.md 中绝不出现 changelog、issue、PR、发布日期、"added in"、"introduced in"、"as of"、"now supports" 等字样；记录当前正向工作流而非负面历史；不因变更日志有某条就新建章节；不插入孤立内容；表格只聚焦当前受支持字段；若 SDK 版本升级没有方法签名变化，只在已有版本注释时更新该注释。
13. 提交前自检每处改动：每个编辑过的字段名都出现在第 4 步读过的源文档中；每个代码示例使用已核实的参数名和嵌套；没有仅凭变更日志措辞推断的内容；没有编造的值；没有技能文件引用变更日志/issue/PR/发布日期/发布历史措辞；每个新标题或章节都能被适配门证明合理；没有孤立句子或强行的一次性章节；没有仅作为负面指引记录已弃用/已移除/被取代字段；每个相关变更项都被归为文档更新、合理新章节、`No Skill Change Needed` 或 `Needs Manual Authoring` 之一；任何未通过自检的改动回退并移入 `Needs Manual Authoring` 或 `No Skill Change Needed`。
14. 用分支名 skills-update/YYYY-MM-DD；建分支前先检查是否已有打开的 PR 并停止：gh pr list --repo <org>/<repo> --head "skills-update/${CHANGELOG_DATE}" --state open --json number --jq 'length == 0'。
15. 从当前 origin/main 建分支、仅在文件有变化时提交并推送：git fetch origin main; git checkout -b "skills-update/${CHANGELOG_DATE}" origin/main; git add -A; git diff --cached --quiet || git commit -m "Update skills from changelog ${CHANGELOG_DATE}"; git push -u origin "skills-update/${CHANGELOG_DATE}"。
16. 把报告写到 /tmp/skills-update-report.md，然后开 PR：gh pr create --repo <org>/<repo> --base main --head "skills-update/${CHANGELOG_DATE}" --title "Update skills from changelog ${CHANGELOG_DATE}" --body-file /tmp/skills-update-report.md。
17. 若分析后没有文件变化，不要推送也不要开 PR，报告 `No skill file changes needed for CHANGELOG_DATE` 并把相关项列在 `No Skill Change Needed` 下。
18. 按固定模板写报告并用作 PR 正文，包含：Outcome（变更日志日期、分支、commit、PR URL、结果）、Summary（若变更# 描述破坏性 API/SDK 变更则加简短迁移警告）、Changes（按技能列出改动）、Verification（字段/区域 + 文件 + 已核实的 API 参考页链接）、Needs Manual Authoring（因 schema 无法核实而未应用的项，含变更日志说法、无法核实原因、待查源链接）、No Skill Change Needed（已核实但无自然位置或过于底层的项，含改动内容、为何不编辑、源链接）、Open Questions、Source（变更日志页面与 GitHub 文件链接）。
19. 在自动化/无头代理且有仓库写权限时，除非没有技能文件变化，否则必须开 PR；最终响应只返回完成的 markdown 报告，除非调用方明确要求额外说明。
20. 不要改动技能文件的 YAML frontmatter，除非变更日志明确要求；变更日志日期和发布历史措辞只保留在报告/PR 上下文中；变更项没有自然位置时宁可不动也不要强行结构化；错误的代码示例比缺失的示例更糟；若变更日志只给功能名和高层描述而无源文档或 schema 细节，放入 `Needs Manual Authoring`。

适用边界 · 注意事项

• 没有已合并的变更日志文件时（应停止并报告，而不是凭猜测更新）。
• 变更只影响内部/管理 API、无使用层影响的可选字段、向后兼容重命名或与 API key 设置流程无关的定价/仪表盘 UI 时。
• 源文档无法提供足够 schema 细节时，不要写字段表或代码示例，应归入 Needs Manual Authoring。