update-docs

更新文档页面，使其反映当前分支中的源代码变更。分析与 main 的差异，将变更的源文件映射到对应的文档页面，并进行有针对性的编辑。

此技能与仓库无关，可供多个仓库共享。它由 pipecat-dev-skills marketplace 发布，所有变更会进入 pipecat-ai/docs 的仓库都会使用它，因此必须避免包含任何特定于某个仓库的内容。

所有特定于仓库的信息——范围、文件与页面的映射方式、新页面的样式以及注册位置——均来自该仓库的 profile： .claude/skills/update-docs/SOURCE_DOC_MAPPING.md，该文件位于正在编写文档的仓库中。此技能不会硬编码源路径、页面模板或导航分组。有关 profile 必须提供的内容，请参阅 PROFILE_CONTRACT.md。

页面的编写方式——需要记录的内容、需要省略的内容、页面模板和文风——由文档仓库的风格指南 DOCS_PATH/STYLE.md 决定。此技能负责流程：查找变更、判断文档需要更新什么，以及检查结果。

REVIEW.md 会在更新完成后进行第二轮检查，并在一个未参与编写的全新会话中运行。自动化流程会在此技能运行后执行该检查；本地更新后，也应以相同方式手动运行。

参数

/update-docs [DOCS_PATH]

• DOCS_PATH（可选）：文档仓库根目录的路径。如果未提供，请询问用户。

示例：

• /update-docs /Users/me/src/docs
• /update-docs

说明

第 1 步：确定文档路径、profile 和风格指南

如果提供了 DOCS_PATH 参数，请使用该路径。否则，请询问用户文档仓库的路径。

验证该路径存在且包含 docs.json。

读取源仓库中的 profile：.claude/skills/update-docs/SOURCE_DOC_MAPPING.md。该文件定义此仓库的范围、映射表、页面模板和注册步骤。如果缺少该文件，请停止并说明原因——没有它，就无法将文件对应到页面；猜测会导致编辑不存在的页面。

完整阅读 DOCS_PATH/STYLE.md。所有编辑都必须遵循该文件。如果它与此技能对页面写法的要求不一致，以风格指南为准。如果该文件缺失，请遵循此技能末尾的指南。

第 2 步：创建文档分支

获取当前源分支名称：

git rev-parse --abbrev-ref HEAD

在文档仓库中，从 main 分支创建一个名称相同的新分支：

cd DOCS_PATH && git checkout main && git pull && git checkout -b {branch-name}-docs

例如，如果源分支为 feat/new-service，文档分支则为 feat/new-service-docs。

后续步骤中的所有文档编辑都在此分支上进行。

第 3 步：检测变更的源文件

运行：

git diff main..HEAD --name-only

profile 的 Scope 部分指定的根目录下的所有源文件都属于范围。各仓库发布的公共 API 远不止最明显的入口点，因此范围采用排除规则，而非允许列表：新目录一经出现就自动纳入范围，无需等到有人想起来将其列入清单。

排除 profile 的 Scope 部分中列出的内容，以及构建和缓存产物（__pycache__/、*.pyc、node_modules/、dist/）和仅重新导出内容、不定义任何内容的索引文件。

这些根目录之外的变更——如示例、CI 配置和文档目录——本身不会触发文档更新。

随后应用 profile 的跳过列表（第 4 步），其中列出了少数真正仅供内部使用的文件。不要自行编造其他理由来跳过文件：文件属于基类、共享模块或“核心架构”都不构成跳过理由。公共构造函数参数和可观察行为无论出现在哪里都应记录；如果某个文件对应的页面不明显，应在第 8 步将其作为缺失项报告，而不是直接忽略。

第 4 步：将源文件映射到文档页面

对于每个已更改的源文件，按照配置文件中的表格依次确定要编辑的文档页面。使用前，先确认每个候选路径都存在于 DOCS_PATH 中。

1. 跳过列表 — 如果文件符合跳过列表中的条件，则停止处理。无需更新文档。
2. 基类 — 如果文件列在基类表中，则使用表中列出的所有页面。此处的更改会影响所有继承该类的内容，因此要逐一检查每个页面，不要在找到第一个页面后就停止。
3. 非标准位置 — 如果文件列在非标准位置表中，则将该条目作为候选路径，并确认路径存在。
4. 模式匹配 — 使用模式表确定候选路径，然后确认 .mdx 文件存在（在 DOCS_PATH 下使用 glob/ls 查找）。如果存在，就使用该路径。
5. 搜索 — 如果步骤 2–4 中没有候选路径存在于磁盘上，则在 DOCS_PATH 中 grep 文件的主类名或导出符号名（参见配置文件的“搜索”部分）。
6. 未映射 — 如果无法解析路径，则将该文件视为未映射，并在第 8 步报告。

切勿编辑尚未确认存在的路径。如果候选路径无法解析，则继续执行搜索步骤。

执行到第 6 步本身就是一项发现，而不是死胡同：未映射文件意味着某个公共 API 在文档站点上没有归属页面，而这正是第 8 步要揭示的问题。

切勿通过丢弃文件来解决问题。

第 5 步：确定文档需要更新什么

列出读者会遇到的变化

打开任何页面进行编辑前，先阅读完整 PR：其描述（包括任何 Breaking Changes 部分）、新增的所有变更日志片段，以及差异。然后为自己列出面向读者的变化：用户现在可以设置、调用、观察或以不同方式处理的内容。Breaking Changes 部分中的每一条都要列入清单，每条项目符号对应一项，除非它只影响子类化内部实现或调用内部实现的代码；只要用户的代码或预期发生了变化，就应列入清单。

对于每一项，都要记录源代码中的事实，而不是描述这些事实的文字：

• 代码中声明的名称、类型和默认值
• 允许的值、限制条件和必需的组合
• 在什么情况下会引发什么错误
• 调用方能察觉到的副作用：重新连接、裁剪、传递给提供方的值、顺序
• 如果某项功能已弃用或移除，它取代了什么

阅读产生相应结果的代码，核实你准备说明的每个结果。PR 描述、变更日志和文档字符串说明的是作者的意图；代码才说明实际行为。如果两者不一致，应以代码为准，并检查 Breaking Changes 部分是否遗漏了摘要中未提及的情况。

文档字符串、注释、PR 描述和变更日志条目都是事实来源，而不是可直接使用的句子。它们是为维护者编写的，包含读者不需要的理由（例如“Early Access”、错误代码，以及代码为何采用当前实现方式）。请用页面自身的措辞向读者重述事实。

在确定无需编写文档之前，先检查文档中已有的内容。 搜索映射后的页面，查找差异涉及的行为，并将每条描述与更改后的代码进行比较。如果某条描述因更改而不再正确，就要将其列入清单，即使代码更改仅涉及文档字符串或注释也不例外：文档经常沿用旧文档字符串的措辞，而这些措辞现在已经不正确。

如果清单仍为空，则此项更改无需更新文档。 常见情况包括：内部重构、恢复文档所述行为的修复、日志文本更改。记录原因（即自动化的 NOOP 行），然后停止。不要仅仅因为文件发生了更改就编写内容。

分析每组源文件与文档的对应关系

对于每组映射项：

1. 阅读完整的源文件，了解当前状态
2. 阅读该文件的差异：git diff main..HEAD -- <source_file>
3. 完整阅读当前文档页面

针对 Step 5 列表中的每一项，找出页面中已有的相关内容（如有）。配置文件的 Section vocabulary 列出了此仓库页面使用的章节及其内容来源；检查所有适用项：

• 构造函数／初始化器参数：将签名与 Configuration 章节的 <ParamField> 条目进行比较
• 选项或设置对象：将声明的字段与页面中对应的表格进行比较
• 事件处理程序：将注册的事件和处理程序签名与 Event Handlers 章节进行比较
• 类名／导入：检查 Usage 示例是否引用了正确的名称
• 行为变更：检查页面中的陈述是否有任何已不再正确
• 命令行接口（如果仓库提供）：将标志、参数、默认值和退出行为与命令参考进行比较

Step 6: 进行有针对性的编辑

Step 5 列表中的每一项都应放在读者最可能查找它的位置，并采用页面现有格式。STYLE.md 的「Changing Existing Pages」表格说明了各类编辑的预期规模：新增参数只需添加一条，不需要说明、示例或概述变更。

规则

• 仅当变更导致某行内容不正确或不完整时，才编辑该行。 不要改写、精简或合并相邻的句子或项目符号。改写未受变更影响的文本，容易引入错误或丢失信息。
• 与新增条目矛盾或重复的行，也视为内容已不正确。 添加或修改条目后，检查页面中关于同一内容的其他陈述。删除仅重复该条目的内容；修正与之矛盾的内容（查阅代码确认正确内容）。
• 每项事实只陈述一次。 添加句子前，先在页面中搜索该事实。如果已经存在，应更新原有内容，而不是重复添加。说明不得重复 <ParamField> 或表格行中的内容。
• 修正变更导致错误的内容，包括示例和操作指南。如果示例现在会产生错误行为、使用了已弃用的参数，或与新行为矛盾，即使它之前是正确的，也要更新。
• 除非相应源内容已删除或变更使其不再正确，否则绝不删除内容。
• 匹配现有格式——如果页面使用 <ParamField> 标签，就使用该标签；如果页面使用表格，就使用表格。
• 保留 CardGroup、链接和示例，除非它们引用了已移除的功能。
• 不要修改 frontmatter，除非类名已重命名。
• 变更涉及但尚未记录的接口——如果变更修改了从未记录的公开 API，请简要记录：只添加相应条目，不要新建说明章节。

弃用项

当源代码将某项标记为弃用时（例如 DeprecationWarning、@deprecated 装饰器、文档字符串说明或移除版本），文档中对应的条目也应注明弃用，并采用 STYLE.md 规定的格式。直接标记该条目，不要在页面其他位置另加说明。

• 如果源代码注明了替代项和移除版本，请一并注明
• 只要弃用的项目仍存在于源代码中，就绝不要删除
• 如果已弃用的 API 没有对应的文档条目，但相关页面包含迁移表格或章节，请在那里添加一行。否则在 Step 8 中报告

步骤 7：找出此次更改导致的其他错误

此次更改可能会导致映射页面以外的页面出错。请在 DOCS_PATH（配置文件的 Guide directories，以及 api-reference/）中搜索以下内容：

1. 更改的名称：差异中涉及的类名、重命名的参数和更改的导入。更新所有现已不正确的引用。
2. 新类的同类项。 如果此次更改在某个类别中新增了类（例如新的分类器、服务、传输层或序列化器），请查找列出其同类项的页面：同时 grep 两到三个同类类名，并检查受支持的服务和比较表、功能列表以及数量（例如“两个分类器”）。请按列表本身的形式将新类添加到每个列表中：比较表应增加一列或一行，而不是在旁边加一句话；数量也应与所统计的表格或列表一并更新。
3. 使用已更改行为的操作指南。 如果行为发生了变化，请在整个 DOCS_PATH 中 grep 受影响的类、事件和参数。对于找到的每个代码片段或说明，请逐步追踪它在新行为下的效果：会运行什么、会触发什么、用户会听到什么。如果结果现在有误、重复或多余（例如代码片段手动执行了框架现在默认执行的操作），请修复该代码片段。
4. 需要为弃用新增行的迁移表。

对于引用已更改代码的每篇指南：请通读全文，修复发生变化的具体引用，不要重写其中的说明文字。如果指南只是提及相关主题，并未使用任何已更改的 API，请勿改动。

步骤 8：找出文档缺口

处理完所有映射的页面对后，检查以下两类缺口：

缺失页面：源文件未能对应到任何文档页面（模式、非标准表格和搜索均未找到结果），且不在跳过列表中。请针对每个文件报告：

• 源文件路径
• 其中定义的主要类或导出符号
• 是否应创建新的文档页面

缺失章节：映射的文档页面缺少源代码所表明应有的章节——例如，类型有构造函数参数，但页面没有 Configuration 章节；或源代码定义了设置类，但页面没有选项表。请标记这些缺口，并提出补充。

如果需要新页面，请遵循配置文件的 New pages 章节，其中提供了页面模板、目标路径，以及此代码库要求的每项注册步骤（导航，以及任何索引或支持矩阵页面）。请全部完成：页面虽已创建但未注册，仍然不可见。页面结构请遵循 STYLE.md；frontmatter 请遵循文档库中的 CLAUDE.md。

Frontmatter 规范

新页面的 title 和 description 会成为其 llms.txt 条目及 AI 工具中的引用标签，文档库的元数据 lint 也会检查它们：

• title：最多 50 个字符，不要添加 - Pipecat 后缀（Mintlify 会自动追加）。如果标题超过 30 个字符，请添加 sidebarTitle。
• description：110–140 个字符；列出页面所述的类，并在相关时注明模态缩写（STT/TTS/LLM/VAD）。全站必须唯一；有效的预览标题（若设置了 og:title 则用它，否则用 title）也必须唯一——如果其他页面已使用相同的短标题，请添加 og:title。

复查每个已编辑页面

最后，以从未看过差异的读者身份，通读你编辑过的每个页面：

• 第 5 步列表中的每个条目都已在正确位置出现一次
• 页面上没有事实重复出现（对照条目，检查概述、功能列表、备注和用法注释）
• 没有句子叙述改动或解释维护者的理由
• 每个示例都仍可使用当前 API 运行：没有已弃用的参数，也没有未定义的名称
• 正文中的数量和列表与其描述的表格一致
• 差异中只有你预期的编辑：在 DOCS_PATH 中运行 git diff

然后运行配置文件 Checks 部分中的每条命令（如果有）。修复你编辑页面上的所有发现，无论其成因是什么：文档仓库的 CI 会对 PR 修改的每个页面运行相同的检查，并在发现任何问题时让 PR 失败，因此这会覆盖第 6 步中禁止编辑非本次改动行的规则 false。按照页面格式和 STYLE.md 修复每项问题（类型使用 Python 语法）。如果问题出现在你未编辑的页面上，且由本次改动引起（例如差异新增的设置或更改的默认值），则由你修复；否则保留，并将其列在差距项下。

继续之前，先修复所有失败项。

第 9 步：格式化并重新生成 llms.txt

文档仓库会提交 llms.txt（根据每个页面的 frontmatter 构建、按导航顺序排列的索引）和 llms-full.txt（包含每个页面的完整正文）。如果其中任一文件过时，元数据 lint 就会失败，因此编辑页面、更改 docs.json 导航或添加新页面后，都要重新生成这两个文件。

Prettier 会重新排版 MDX，而 llms-full.txt 会原样嵌入页面正文，因此必须先完成格式化，再生成文件：

cd DOCS_PATH
npx prettier --ignore-unknown --write <edited files>
node scripts/gen-llms-txt.mjs

将文档编辑与重新生成的 llms.txt 和 llms-full.txt 一起提交。先生成再格式化会导致文件过时——依赖仓库的 pre-commit hook 也一样，因为它会在生成完成后才格式化页面。

node scripts/docs-meta-lint.mjs 会报告 CI 检查到的相同过时问题和 frontmatter 问题。

第 10 步：输出摘要

完成所有编辑后，打印摘要：

## Documentation Updates

### Updated reference pages
- `<page path>` — what changed, and in which section

### Updated guides
- `<guide path>` — what changed

### New pages
- `<page path>` — created, plus every place it was registered

### Unmapped source files
- `<source path>` — ClassName (no doc page exists)

### Skipped files
- `<source path>` — why

指南

STYLE.md 是页面行文规范的权威依据。若没有该文件，至少遵循以下要求：

• 面向未来的读者，而不是差异 — 文档应描述当前 API。绝不要叙述改动本身：不要写“新添加”“这替代了”“最近更改”，也不要提及先前的行为。
• 不写理由，不写内部实现 — 省略代码为何如此工作以及内部如何工作的说明，除非读者必须据此编写自己的代码。
• 提示框只用于避免读者产生误解 — 能放进现有句子的信息，就写在该句中。
• 保持代码与正文一致 — 页面提到参数、类或标识符时，正文中的拼写必须与源代码以及 <ParamField>/表格条目完全一致。
• 行内技术术语使用反引号 — 参数名、类名、文件名、环境变量和配置键都要加反引号。
• 正文简洁明了 — 不写填充内容、占位文本或助手元信息。此技能会在 CI 中无人值守地运行，因此后续流程不会检查这些内容。

流程：

• 先阅读，再编辑 — 修改前务必通读完整文档页面，以了解现有结构。
• 一次处理一个 PR — 此技能针对当前分支与 main 之间的差异运行。不要查看其他分支。
• 共享源文件 — 基类和共享模块会影响所有导入它们的内容。检查哪些页面涵盖这些使用者，并更新所有相关页面。

检查清单

完成前，请确认：

• 已阅读个人资料和 STYLE.md
• 已编写第 5 步的面向读者的变更清单，并根据代码核实事实；如果清单为空，则以 NOOP 结束本次运行
• 清单中的每一项都已按照页面现有格式记录一次
• 未编辑任何未因本次变更而变得错误或不完整的行
• 已标记弃用项，并在迁移表格中添加行
• 已搜索受本次变更影响的同级清单、教程和指南（第 7 步）
• 每个编辑过的页面都通过了第 8 步末尾的审查，包括个人资料中的检查项
• 已在个人资料要求的所有位置登记新页面
• 已格式化编辑过的页面，随后重新生成并提交 llms.txt 和 llms-full.txt
• 已报告未映射的文件