用GitHub Release触发SDK文档自动更新

前言

SDK 发版后，文档仓库经常还停留在旧版本。靠人在 Release 之后记得去另一个仓库看 diff、补文档、跑构建和提 PR，次数少时没问题，次数多了早晚会漏。

最近梳理并验证了一条自动化链路：SDK 发布稳定版 GitHub Release 后，由 Webhook 触发脚本，创建独立 worktree，让 Codex 审计两个 tag 之间的改动并更新文档，最后自动提交分支和创建 PR。

完整链路是：

GitHub Release published
  → Webhook
  → Trigger规则匹配
  → dispatcher校验事件和tag
  → 从Docs最新origin/main创建worktree
  → 启动独立Codex会话
  → 审计SDK tag diff并更新文档
  → npm run build
  → commit / push / PR

这篇主要记录这条流水线中几个比“调用一下 Agent”更重要的工程细节。

Release事件规则

Trigger 中可以写：

repository: ["SwanHubX/Trio"]
event: "release"
action: ["published"]

dispatcher

脚本在启动 Codex 前先完成：

• 仓库、事件和 action 白名单校验
• 只接受稳定版本
• tag 格式检查
• 查找前一个稳定 tag
• fetch 源码和文档仓库
• 同一 tag 的幂等检查
• 启动锁
• 分支是否已存在检查

只有这些条件全部满足，才创建会话。

这样重复投递 Webhook 不会生成两个 PR，草稿版或不合法 tag 也不会浪费一次 Agent 运行。

使用独立worktree

git -C "$docs_repo_dir" fetch --quiet origin main
git -C "$docs_repo_dir" worktree add \
  -b "$branch" \
  "$worktree" \
  origin/main

这样有几个好处：

• 每次都从最新 origin/main 开始。
• 不修改主 checkout 当前所在分支。
• 不会把已有未提交文件带进自动化任务。
• 多个 Release 可以拥有独立目录和会话。
• 出错后可以保留现场排查。

Agent 只在这个 worktree 中修改文档，也只会推送新分支和创建 PR，不会直接推 main。

提示词

脚本已经知道源仓库、前后 tag、目标仓库、目标分支和构建命令，这些都应该明确传给 Agent。

Agent 真正需要判断的是：

• 两个版本之间哪些变化会影响用户使用 SDK。
• 哪些文档页面已经过期。
• 新功能应该放在哪个已有章节，而不是另建一套重复结构。
• 代码示例和 API 描述是否与新版本一致。

提交、推送、创建 PR 也是明确的完成条件。这样会话不是“帮我看看文档”，而是一个有输入范围、有验证命令、有交付物的任务。

后台进程PATH

测试中 Webhook 和规则第一次就匹配成功，脚本却立刻报：

missing required command: jq

在交互终端里明明可以使用 jq。修好后又遇到：

missing required command: codex

原因是 Trigger 作为后台进程启动时，不会自动加载用户交互 shell 中的 nvm 和 PATH。人的终端里能执行，不代表 daemon 也能找到。

最后把运行时需要的路径显式写进服务环境，并提供 CODEX_BIN 的绝对路径，而不是依赖 .bashrc：

PATH=/用户级node目录:/jq所在目录:...
CODEX_BIN=/用户级node目录/codex

这件事看起来很基础，却是这类自动化最常见的故障之一。测试脚本时应该尽量使用和后台服务相同的环境，而不是只在自己的 shell 里手动跑通。