update-skills-from-changelog

根据 elevenlabs-dx 中已合并的每周变更日志，更新 ElevenLabs Agent 技能。不要读取 GitHub issues。如果技能文件有变更，请在此仓库中创建拉取请求。

技能文件是记录当前行为的常青权威文档。使用变更日志了解发生了什么变化，但最终的 SKILL.md 和 references/*.md 内容应采用永不过时的现在时文档形式。

技能文件是关于如何使用 ElevenLabs 的高层任务导向指南，并非旨在复述变更日志或 API 参考中的每个细节。优先记录主要工作流、核心功能和重要配置界面。通常省略边缘情况、优先级链、持久化机制、回退顺序、实现细节和狭窄例外，除非省略这些内容会使技能产生重大误导或无法使用。

工作流

1. 从自动化触发信息或用户消息中确定 CHANGELOG_DATE。
2. 从 elevenlabs-dx 的 main 分支获取已合并的变更日志。
3. 应用相关性筛选。如果没有受影响的技能，则停止。
4. 阅读所有受影响的技能文件和参考文件。
5. 根据权威源文档核实每项候选更新。
6. 仅应用通过适配门槛的、有针对性的常青技能编辑。
7. 自检所有编辑。
8. 创建 skills-update/YYYY-MM-DD，提交、推送并创建 PR。

不要修改变更日志未涉及的技能。

第 1 步：获取变更日志

从自动化触发信息或用户消息中确定 CHANGELOG_DATE（YYYY-MM-DD）。

获取已合并的变更日志文件：

gh api "repos/elevenlabs/elevenlabs-dx/contents/fern/docs/pages/changelog/${CHANGELOG_DATE}.md?ref=main" \
  --jq '.content' | base64 -d > "/tmp/changelog-${CHANGELOG_DATE}.md"

如果该文件不存在，请停止并报告该日期没有已合并的变更日志。

必要时也阅读已发布的页面：

https://elevenlabs.io/docs/changelog#${CHANGELOG_DATE}T00:00:00.000Z

第 2 步：应用相关性筛选

读取 /tmp/changelog-${CHANGELOG_DATE}.md，并将变更与以下技能对应：

技能	触发更新的变更
text-to-speech	新模型或弃用模型、新 TTS 参数、语音设置变更、输出格式变更、text_to_speech.convert() 的 SDK 方法签名变更
speech-to-text	新转录模型、新参数、响应架构变更、SDK 方法变更
agents	新 LLM 提供商或模型、新工具类型、新 Agent 配置字段、对话配置架构变更、新 CLI 命令、组件变更、流程端点／字段／类型变更、结构化流程步骤类型和验证规则、草稿保存或发布编译及验证行为、conversational_ai.agents.procedures 或 conversationalAi.agents.procedures 下的 SDK 方法变更
sound-effects	新生成参数、模型变更、SDK 方法变更
music	新端点、新参数、模型变更
voice-isolator	新参数、模型变更、audio_isolation.convert() 的 SDK 方法变更
realtime	Realtime 模型 ID、realtime_model Agent 配置、托管设置、按地区或合规模式划分的 Realtime 可用性、Realtime API（/v1/convai/realtime）或 client_secrets 变更、conversational_ai.realtime 或 conversationalAi.realtime 的 SDK 方法变更
speech-engine	Speech Engine WebSocket API 变更、对话令牌变更、实时语音对话的 SDK 方法变更
voice-changer	新语音转语音参数、模型变更、speech_to_speech.convert() 或 speechToSpeech.convert() 的 SDK 方法变更
setup-api-key	身份验证流程变更、API 密钥控制面板变更、环境变量指南变更
onboarding	elevenlabs onboard CLI 变更、审批页面或注册流程变更、CLI 安装渠道、SDK 软件包名称

如果变更影响技能文档中的模型表、代码示例、参数说明、配置表或 CLI 命令，则视为相关。

如果变更仅影响内部／管理员 API、不影响实际使用的可选字段、向后兼容的重命名，或与 API 密钥设置流程无关的定价／控制面板 UI，则视为不相关。

如果没有技能受到影响，则成功结束，无需创建拉取请求。报告 No skills-relevant changes for CHANGELOG_DATE。

对每项相关变更，注明受影响的技能和受影响的部分，例如模型表、代码示例、LLM 提供商表、工具部分、CLI 部分、参数说明或配置表。

第 3 步：阅读当前技能文件

对于每项受影响的技能，请阅读：

• {skill}/SKILL.md
• {skill}/references/ 中的所有文件

技能目录：

• text-to-speech/（SKILL.md 以及 references/installation.md、references/streaming.md、references/voice-settings.md）
• speech-to-text/（SKILL.md 以及 references/installation.md、references/transcription-options.md、references/realtime-server-side.md、references/realtime-client-side.md、references/realtime-commit-strategies.md、references/realtime-events.md）
• agents/（SKILL.md 以及 references/installation.md、references/agent-configuration.md、references/client-tools.md、references/widget-embedding.md、references/outbound-calls.md、references/using-procedure-api.md、references/writing-procedures.md）
• sound-effects/（SKILL.md 以及 references/installation.md）
• music/（SKILL.md 以及 references/installation.md、references/api_reference.md）
• voice-isolator/（SKILL.md 以及 references/installation.md）
• realtime/（SKILL.md 以及 references/session-config.md、references/browser-audio.md）
• speech-engine/（SKILL.md 以及 references/installation.md、references/javascript-sdk-reference.md、references/python-sdk-reference.md）
• voice-changer/（SKILL.md 以及 references/installation.md）
• setup-api-key/（仅 SKILL.md）
• onboarding/（仅 SKILL.md）

第 4 步：核实源文档

编辑前，请获取并阅读实际源材料。变更日志会说明发生了哪些变化；API／参考文档则说明当前行为应如何记录。

对于常见领域，请从以下文档入手：

• Agents：https://elevenlabs.io/docs/api-reference/agents/create、https://elevenlabs.io/docs/api-reference/agents/update
• TTS：https://elevenlabs.io/docs/api-reference/text-to-speech/convert
• STT：https://elevenlabs.io/docs/api-reference/speech-to-text/convert

对于每个文档涉及的字段、参数、架构、枚举、端点、模型 ID 或 SDK 方法：

• 在源文档中核实准确的字段名、类型、嵌套结构、允许值和方法签名。
• 切勿根据变更日志的措辞推断架构。
• 如果变更日志提到了某项功能，但源文档未提供足够的架构细节，则不要为其编写字段表或代码示例。请在报告的 Needs Manual Authoring 下列出该项。

第 5 步：判断每项内容是否适合纳入

编辑每项变更日志内容前，先按以下适配标准判断：

1. 将内容对应到现有章节、表格、列表或示例中的自然位置。
2. 仅纳入核心能力、常见工作流或重要的顶层配置概念。
3. 跳过次要细节：边缘情况、优先级规则、持久性细节、回退顺序、实现细节、狭义例外或弃用说明。
4. 优先不做改动，而不是强行寻找结构。如果没有自然的位置，则保持技能文件不变，并在 No Skill Change Needed 下报告。
5. 仅当概念重要、可复用、面向用户、属于高层内容且当前结构中明显缺失时，才新增章节。
6. 优先采用当前路径。如果某字段、端点、模型、软件包或模式替代了其他内容，则记录当前受支持的方式，并在报告中保留已弃用内容的说明。

适合纳入的内容：

• 在现有模型表中添加新的受支持模型行。
• 在现有参数表中添加新的顶层参数。
• 方法签名变更时，更新现有 Python、JavaScript 和 CLI 示例。

不适合纳入的内容：

• 只为提及某项变更日志内容，就在无关章节之间插入独立句子。
• 添加已弃用字段、已移除的枚举值、旧软件包名称或迁移警告；除非技能已有明确的迁移／故障排查章节，且确有必要在其中说明此项变更。
• 记录内部优先级、本地持久化行为、回退链或罕见的例外情况。

步骤 6：进行针对性编辑

对正确的文件和章节做出最小且有效的修改。保持现有的标题级别、表格格式、代码块语言、缩进和命名风格。

更新模式：

• 模型表格： 在相关 SKILL.md 模型表格中添加、删除或修改行。验证模型 ID 和描述。
• 代码示例： 更新方法签名、导入项和重要参数。若 Python、JavaScript 和 CLI 示例均存在，请确保它们保持一致。
• LLM 提供商表格： 更新 agents/SKILL.md 或 agents/references/agent-configuration.md。
• 工具部分： 按照现有风格，在 agents/SKILL.md 中更新工具类型。
• CLI 部分： 更新 agents/ 文件中的现有 CLI 示例。
• 参数文档： 在相关参数列表或表格中添加已验证的参数。
• 配置表格： 更新参考文件（例如 agent-configuration.md 或 voice-settings.md）中的字段表格。
• 输出格式表格： 更新 text-to-speech/SKILL.md 中的输出格式表格。

硬性规则：

• 切勿臆造字段名、类型、架构、模型 ID、配置名、端点路径或示例值。
• 未验证确切的 API 结构前，切勿为新功能编写代码示例。
• 将变更日志视为发现信息，而非技能文件文案。
• 技能文件必须保持长期有效。切勿在 SKILL.md 或 references/*.md 中提及变更日志、问题、PR、发布日期、“新增于”、“引入于”、“截至”或“现在支持”。
• 记录当前可行的工作流，而非负面历史。
• 切勿仅因变更日志中的一条内容而新建章节。
• 切勿插入无归属内容。
• 表格仅保留当前支持的字段。
• 如果 SDK 版本升级未导致方法签名变化，仅在已有此类注释时更新特定版本的注释。

步骤 7：提交前自查

审查每项修改并验证：

1. 每个已编辑字段名都出现在步骤 4 中阅读的源文档里。
2. 每个代码示例使用的参数名称和嵌套结构均已验证。
3. 没有仅根据变更日志措辞推断内容。
4. 没有遗留任何虚构值。
5. 没有已编辑的技能文件引用变更日志、问题、PR、发布日期或发布历史表述。
6. 每个新增标题或章节都有步骤 5 的依据。
7. 没有无归属的句子或牵强的一次性章节。
8. 没有已编辑内容仅以负面说明的形式记录已弃用、移除或替换的字段。
9. 每项相关的变更日志内容都已归入以下其中一类：文档更新、合理的新章节、No Skill Change Needed 或 Needs Manual Authoring。

如果有任何修改未通过此项检查，请撤销该修改，并将该条目移至 Needs Manual Authoring 或 No Skill Change Needed。

步骤 8：创建分支、提交并发起拉取请求

使用分支名称 skills-update/YYYY-MM-DD。

创建分支前，检查是否已有未关闭的 PR；如果有，则停止：

gh pr list --repo elevenlabs/skills --head "skills-update/${CHANGELOG_DATE}" --state open --json number --jq 'length == 0'

从当前的 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}"

将报告写入 /tmp/skills-update-report.md，然后发起 PR：

gh pr create --repo elevenlabs/skills \
  --base main \
  --head "skills-update/${CHANGELOG_DATE}" \
  --title "Update skills from changelog ${CHANGELOG_DATE}" \
  --body-file /tmp/skills-update-report.md

如果分析后没有文件更改，则不要推送或发起 PR。报告 No skill file changes needed for CHANGELOG_DATE，并在 No Skill Change Needed 下列出相关条目。

报告和 PR 正文要求

编写此报告，并将其用作 PR 正文：

# Skills Update Report

## Outcome

- Changelog: `YYYY-MM-DD`
- Branch: `skills-update/YYYY-MM-DD`
- Commit: `<commit sha or "No commit created">`
- Pull request: `<PR URL or "No PR created">`
- Result: `<updated skills | no skill changes needed | partial update>`

## Summary

Updates skills based on the merged weekly changelog.

If the changelog describes breaking API or SDK changes, add a short warning here describing which examples or docs may need migration guidance.

### Changes

- **skill-name**: Brief description of what changed.

### Verification

- `field_or_area` in `file.md` - verified against [API reference page](url)

### Needs Manual Authoring

List changelog items that were not applied because the schema could not be verified. Include what the changelog said, why it could not be verified, and the source link to check later.

If no items apply, write "None."

### No Skill Change Needed

List verified changelog items intentionally not added to skill files because they have no natural home or are too low-level for skills. Include what changed, why no edit was appropriate, and the source link.

If no items apply, write "None."

### Open Questions

List blockers, ambiguous source material, or follow-up items.

If no items apply, write "None."

### Source

[Changelog YYYY-MM-DD](https://elevenlabs.io/docs/changelog#YYYY-MM-DDT00:00:00.000Z)
[Changelog file on GitHub](https://github.com/elevenlabs/elevenlabs-dx/blob/main/fern/docs/pages/changelog/YYYY-MM-DD.md)

在具有仓库写入权限的自动化／无头 Agent 环境中运行时，除非技能文件没有更改，否则必须发起拉取请求。最终回复中仅返回完成的 Markdown 报告，除非调用用户明确要求提供额外说明。

重要说明

• 除非变更日志有明确要求，否则不要更改技能文件中的 YAML frontmatter。
• 仅在报告/PR 上下文中保留变更日志日期和发布历史措辞。
• 如果变更日志条目没有合适的归属位置，宁可不做更改，也不要强行安排结构。
• 错误的代码示例比缺少代码示例更糟。
• 如果变更日志内容仅包含功能名称和高层描述，没有源文档或架构详情，请将这些条目归入 Needs Manual Authoring。