Composio 文档站 CI/CD 管线全解析从 GitHub Actions 工作流到自动化文档维护【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文以 Composio 仓库中docs/agent-guidance/context/pipelines.md为骨架结合.github/workflows/下 37 个真实工作流文件系统梳理文档站docs、SDK 构建与仓库治理三套 CI/CD 管线谁在何时触发、执行了什么、产出什么 PR以及沉淀下来的关键工程模式App Token 鉴权、next分支策略、静默失败追踪等。读完本文你既能按图索骥定位任意自动化任务的实现文件也能把这套AI Agent 自动维护文档 数据自动同步 多级质量门禁的管线设计复用到自己的文档型仓库中。1. 管线全景一份工作流速查表Composio 的 CI/CD 可以划分为三组文档工作流Docs Workflows、SDK/构建工作流SDK/Build Workflows与其他治理工作流Other Workflows。原文档给出了完整清单此处逐条保留并补充真实文件路径与触发细节。1.1 文档工作流Docs Workflows工作流文件触发方式职责Update Datadocs-update-data.ymlCron每 5 小时、repository_dispatchApollo/Mercury 生产部署、手动抓取 toolkits 数据、两份 OpenAPI 规范v3.1 v3.0、生成两个版本的 API 索引页与 meta tools 参考文档通过peter-evans/create-pull-request创建指向next的 PRSync Connect Clientsdocs.sync-connect-clients.ymlCron每日 UTC 8:00、手动、repository_dispatchdashboard 生产部署用 Claude Code 动作将ComposioHQ/composio_dashboard的客户端定义同步到composio-connect.mdx创建指向next的 PRChangelog → Docsdocs.changelog-to-docs.ymlPush 到nextchangelog 文件变化用 Codex 动作读取新增 changelog 条目并更新文档页面创建指向next的 PRCheck Linksdocs-check-links.ymlPR 修改docs/运行bun run scripts/validate-links.ts捕获失效的内部链接Lint TypeScriptdocs-typescript-check.ymlPR 修改docs/依次运行bun run lintoxlint、bun run types:check与bun run build校验 Twoslash 代码块Docs Testsdocs-tests.ymlPR 修改docs/运行文档测试套件静态测试 集成测试Health Checkdocs.health-check.ymlCron每小时探测线上文档站是否正常响应Changelog Notificationdocs.changelog-notification.ymlPush 到nextchangelog 文件变化新 changelog 条目合并后发送通知Doc Reviewclaude-code-doc-review.ymlPR 评论中包含claude按需让 Claude Code 审查文档 PR1.2 SDK/构建工作流SDK/Build Workflows工作流文件触发方式职责Generate SDK Docsgenerate-sdk-docs.ymlPush 到nextSDK 源码变化、手动从 TS/ Python 源码生成 SDK 参考文档TS Buildts.build.ymlPR 修改ts/构建 TypeScript 包TS Testts.test.ymlPR 修改ts/运行 TypeScript 测试TS E2Ets.test-e2e.ymlPR 修改ts/运行 E2E 测试Node、Deno、CloudflareTS Typecheckts.typecheck.ymlPR 修改ts/SDK 类型检查TS Releasets.release.ymlPush 到next、手动创建 Changesets 发布 PR 并发布 TypeScript 包TS Auditts.audit.ymlCronnpm 依赖安全审计Build CLI Binariesbuild-cli-binaries.ymlRelease构建 CLI 二进制用于分发CLI Test Installationcli.test-installation.ymlPR 修改 CLI测试 CLI 安装流程Python Checkpy.check.yamlPR 修改python/Python SDK 的 lint 与类型检查Python Testpy.test.ymlPR 修改python/运行 Python 测试Python Releasepy.release.ymlpy*标签、手动构建并发布 Python 包1.3 其他治理工作流Other Workflows工作流文件触发方式职责Claude Codeclaude.ymlIssue/PR 评论包含claude通用 Claude Code 仓库级任务Secrets Detectionsecurity.secrets-detection.ymlPR扫描误提交的密钥Stalestale.ymlCron每日 00:00 UTC标记并关闭陈旧的 issue 与 PR除上述清单外仓库还包含 docs-rebuild-kb-semantic.yml、docs-search-sync.yml、docs-update-kb.yml、docs.sdk-change-sync.yml、docs-agent-eval.yml 等文档相关辅助工作流以及 dead-code.yml、examples-live.yml、issue-triage.yml 等仓库治理工作流共同构成了完整的自动化体系。2. 文档数据自动同步Update Data 工作流深读docs-update-data.yml是整个文档站的数据泵负责把生产环境的后端元数据持续灌入文档仓库。它的完整执行链路值得逐段拆解触发源有三个定时 Cron0 */5 * * *每 5 小时repository_dispatchapollo-production-deploy与mercury-production-deploy两种事件类型即后端生产环境每部署一次就联动刷新一次文档数据workflow_dispatch手动触发。凭证设计关键细节该工作流专门使用COMPOSIO_DOCS_API_KEY而不是共享的COMPOSIO_API_KEY。工作流注释明确解释了原因——共享密钥同时被ts.test-e2e、py.test、py.check、ts.examples-nightly使用且都面向staging环境而本工作流是唯一需要访问production的任务scripts/production-api.mjs 会拒绝任何非生产 base URL两者凭证域不同不能混用。这一点是避免文档意外展示 staging 主机与未发布内容的关键防线。执行步骤链用actions/create-github-app-token生成 GitHub App 短期令牌而非长期 PATcheckout 仓库bun install安装依赖用actions/cache缓存 bun 依赖bun run generate:toolkits—— 刷新 toolkits 目录bun run scripts/fetch-openapi.mjs—— 抓取 OpenAPI 规范bun run generate:api-index—— 生成两个 API 版本的索引页bun run generate:meta-tools—— 生成 meta tools 参考文档KB 新鲜度校验bun scripts/verify-kb.ts --check-links --check-source-pin对比已发布 KB 文章的断言与本次刷新后的目录是否一致发现不匹配会报告但不阻塞数据同步检测文件变化git diff判断docs/public/data/、openapi.json、openapi-v3.json、api-reference/、v3/api-reference/等路径有变化则用peter-evans/create-pull-request创建 PRbase: next分支docs/auto-update-data并自动把触发者添加为 reviewer。静默失败自愈机制值得借鉴的工程实践工作流内置了失败追踪 issue逻辑。注释指出如果同步静默失败docs/public/data/toolkits.json停止刷新文档站仍能基于最后一次好提交继续构建不会 500但新 toolkits 会直接 404——这正是历史上一次凭据故障连续 60 次运行未被发现的根因。因此工作流在失败时用docs-data-sync-failure标签创建追踪 issue不重复创建成功后自动关闭该 issue形成红灯即修、绿灯自愈的闭环。3. AI Agent 驱动的文档维护三个自动化写作/审查工作流这套管线最有特色的是引入了多个 AI Agent 作为文档维护主力且每个 Agent 都有独立的指令文件位于 docs/agent-guidance/agents/3.1 Sync Connect ClientsClaude Code 同步客户端定义docs.sync-connect-clients.yml的工作流程取数repository_dispatch事件携带client_definitionsbase64 编码的客户端定义 TS 文件或手动触发时用gh api从ComposioHQ/composio_dashboard仓库拉取client-definitions.tsAI 同步调用anthropics/claude-code-action授予受限工具集Read,Write,Edit,Glob,Grep,Bash(curl *)prompt 指示它先读 docs/agent-guidance/agents/connect-clients-sync.md 获取完整指令再对比/tmp/client-definitions.ts与现有docs/content/docs/composio-connect.mdx更新新增/变更的客户端步骤、描述并下载新客户端 logo 到docs/public/images/clients/PR 产出若无差异则不改任何文件有差异则由peter-evans/create-pull-request创建指向next的 PR分支docs/auto-sync-connect-clients并把触发者加为 reviewer。工作流注释点明了一个容易被忽视的坑GITHUB_TOKEN无法在此仓库创建 PR仓库关闭了Allow GitHub Actions to create and approve pull requests因此所有开 PR 的工作流都必须铸造 release-bot App token。3.2 Changelog → DocsCodex 依据 changelog 更新文档docs.changelog-to-docs.yml在每次向next推送 changelog 文件docs/content/changelog/**.mdx时触发用git diff --name-only --diff-filterAM在提交区间before..after中找出新增/修改的 changelog 文件并处理首次推送before 全零的边界情况调用openai/codex-action沙箱workspace-writeprompt 要求它先读 docs/agent-guidance/agents/changelog-docs-updater.md 获取指令再逐个分析 changelog 文件搜索docs/content/docs/中受影响的页面并更新若无文档变更则不创建 PR有变更则用git checkout -bgh pr create手工开 PRbasenextreviewer 请求被刻意拆成独立 best-effort 步骤避免因无法指派的 actor 导致整个命令失败、留下孤儿分支。配套的 changelog-docs-updater.md 给出了变更分类→文档动作映射表这是让 Agent 输出稳定质量的核心约束Changelog 类型文档动作破坏性变更新 API 签名、移除参数更新受影响指南中的代码示例新特性新参数/方法/选项融入相关既有指南的合适位置弃用在旧用法附近添加Callout typewarn提示行为变更默认值、响应格式变化更新引用旧行为的描述与示例Toolkit 变化无需改文档toolkit 页面自动生成Bug 修复 / 性能优化 / 基础设施变更无需改文档同时该 Agent 有明确红线只允许修改docs/content/docs/与docs/content/examples/禁止新建页面禁止在文档里写as of v0.6.0...式的 changelog 口吻TS 代码块受构建期类型检查约束必须在// ---cut---上方补全 import详见 docs/agent-guidance/context/twoslash.md。3.3 Doc Reviewclaude 按需代码审查claude-code-doc-review.yml在 PR 修改docs/content/**/*.mdx、docs/components/**/*.tsx、docs/app/**/*.tsx、docs/app/**/*.css时运行prompt 指示 Claude Code 依据 docs-reviewer.md 的审查清单执行git diff origin/${{ github.event.pull_request.base.ref }}...HEAD检查变更发现问题则评论具体修复建议无问题则批准并回复 Looks good。工作流还预置了allowed_bots白名单与可选的按作者定制 prompt 模板。4. 质量门禁链接检查、类型校验与测试文档 PR 在合并前要经过三层质量门禁均为pull_request触发路径过滤docs/**Check Linksdocs-check-links.ymlPR 路径下只跑内部链接校验bun run lint:links即bun scripts/validate-links.ts每日 02:30 的 Cron 额外跑bun run lint:links:external对外部链接做 HEAD/GET 检查——因为逐个检查外部 URL 很慢且依赖第三方可用性所以从不放在 PR 路径上定时任务失败时自动创建docs-external-links-failure标签的追踪 issuePR 失败则不需要因为失败对作者可见。Lint TypeScriptdocs-typescript-check.yml依次执行bun run lintoxlint、bun run types:check、bun run build。其中types:check会执行generate:kb、build-agent-index、fumadocs-mdx、next typegen并使用 TypeScript 7 做--noEmit检查见 docs/package.jsonbuild会真正构建站点从而校验 MDX 中的 Twoslash TypeScript 代码块可编译。Docs Testsdocs-tests.ymlbun run test——bun test tests/static/静态测试bun run check:kb-semantic—— 校验 KB 语义索引产物与最新生成结果一致bun run build后启动服务bun run start 轮询等待localhost:3000就绪30 秒超时再跑bun run test:integrationbun test tests/integration/ --timeout 30000最后无论成败都 kill 掉服务器进程。三个工作流都复用了 .github/actions/setup-node-pnpm-bun 复合动作与actions/cachekey 为docs/bun.lock的哈希保证依赖安装可复现、可缓存。5. 线上巡检与变更通知Health Checkdocs.health-check.yml每小时探测https://docs.composio.dev检查点覆盖三类LLM/Agent 入口/llms.txt、/llms-full.txt、/docs/quickstart.md、/docs/how-composio-works.md的 Markdown 形态核心页面/docs、/docs/quickstart、/toolkits、/toolkits/github期望 200以及/toolkits/__definitely-not-a-toolkit__期望 404验证 404 语义正确KB 搜索 API/api/knowledge-search?qgithub oauthfilterkb需返回 JSON 且满足jq表达式.query github oauth and .filter kb and (.results | type array) and .mode hybridMarkdown 内容协商带Accept: text/markdown头请求多个页面验证服务端 Markdown 渲染能力。每个检查点失败会重试一次间隔 3 秒失败汇总后通过 Slack webhook 推送告警并使工作流最终以非零码退出。Changelog Notificationdocs.changelog-notification.yml检测推送区间内新增/修改的 changelog 文件用 grep 解析 frontmatter 中的title、date构造 changelog URL用git log追溯作者最终用jq构造转义安全的 Slack payload 发送通知。6. SDK 构建、测试与发布管线SDK 侧的工作流与文档管线共享App Token 铸造 指向next的模式但各自承担不同的生命周期职责Generate SDK Docsgenerate-sdk-docs.ymlPush 到next且 SDK 源码变化ts/packages/core/src/**、python/composio/**等路径时触发TS 侧跑pnpm --filter composio/core generate:docs生成docs/content/reference/sdk-reference/typescript/Python 侧用uv run --with griffe python scripts/generate-docs.py生成docs/content/reference/sdk-reference/python/随后各自开 PR。TS Releasets.release.ymlPush 到next或手动触发运行pnpm validate:changesets、lint、build 后交给changesets/action创建版本更新 PR 并执行pnpm changeset:release发布发布成功后在 Slack 中汇总各包old → new版本号用git show HEAD^对比。工作流注释解释了为什么用 App token 而非长期 PATApp token 不会过期且其触发的Release: update version PR 合并后的事件仍能联动下游build-cli-binaries.yml等发布流程。Secrets Detectionsecurity.secrets-detection.ymlPR 打开/同步/重开时调用 GitHub Advanced Security 的 secret scanning API 查询未关闭告警发现则在该 PR 评论警告并推送 Slack404/403 时降级为 warning 提示启用 GHAS。Stalestale.yml每日 00:00 UTC 运行60 天未活动标记stale再过 2 天关闭issue 豁免标签pinned,security,bug,needs-triage,roadmap,enhancement,good first issuePR 豁免标签pinned,security,needs-review,work-in-progress,dependencies。7. 关键模式总结这套管线的四个设计原则原文档在末尾提炼了四条 Key Patterns结合源码可以进一步扩展为可复用的工程原则文档 PR 永远指向next而非master。所有自动开 PR 的工作流Update Data、Sync Connect Clients、Changelog → Docs、Generate SDK Docs的base都是next确保自动化改动先经过主开发分支的完整验证再进入发布线。自动 PR 统一走peter-evans/create-pull-request或手工gh pr create。由于仓库关闭了 Actions 直接创建/批准 PR 的权限所有开 PR 的工作流都必须先用actions/create-github-app-token铸造 release-bot App tokenclient-id 取自vars.RELEASE_BOT_CLIENT_ID私钥取自secrets.RELEASE_BOT_APP_PRIVATE_KEY这是贯穿 docs-update-data.yml、docs.sync-connect-clients.yml、docs.changelog-to-docs.yml、ts.release.yml 的同一模式。AI Agent 工作流把行为准则外置到指令文件docs/agent-guidance/agents/下的 connect-clients-sync.md、changelog-docs-updater.md、docs-reviewer.md 以独立文件形式约束 Claude Code / Codex 的行为边界可改哪些目录、禁止做什么、输出规范prompt 只做读指令 执行的引导既保证可维护性也让 Agent 输出稳定。定时工作流如果要为next目标 PR 检出代码必须显式指定ref: next。例如 docs.sync-connect-clients.yml 的 checkout 步骤使用ref: next和fetch-depth: 1确保基于正确的分支基线做 diff 与 PR。除此之外从源码中还能提炼出两个文档未明说但贯穿始终的隐性原则静默失败必须可见定时任务失败自动开追踪 issue、恢复后自动关闭如 Update Data 的docs-data-sync-failure与 Check Links 的docs-external-links-failure敏感凭据按环境隔离production 专用COMPOSIO_DOCS_API_KEY与 staging 共享的COMPOSIO_API_KEY严格分离避免 staging 数据泄漏进生产文档。8. 如何在本地复现这些检查文档站的质量门禁全部对应 docs/package.json 中的脚本可在本地逐一复现 CI 行为需 Node ≥ 24 与 bun 运行时cd docs bun install # 安装依赖postinstall 自动生成 KB 与 fumadocs-mdx bun run lint # oxlint 静态检查对应 docs-typescript-check.yml bun run types:check # KB 生成 agent 索引 fumadocs-mdx next typegen tsc --noEmit bun run lint:links # 校验内部链接对应 docs-check-links.yml 的 PR 路径 bun run lint:links:external # 追加外部链接检查对应每日 Cron 路径 bun run test # 静态测试 bun test tests/static/ bun run test:integration # 集成测试 bun test tests/integration/ bun run verify:kb # KB 新鲜度校验对应 Update Data 中的 verify-kb 步骤 bun run build # next build校验 Twoslash 代码块数据生成类任务也可以手动运行以预览自动 PR 的产出bun run generate:toolkits、bun run scripts/fetch-openapi.mjs、bun run generate:api-index、bun run generate:meta-tools正是 docs-update-data.yml 中四个生成步骤的本地等价命令注意拉取 OpenAPI 需要访问 production API 的COMPOSIO_DOCS_API_KEY本地无凭据时该步骤会失败属预期行为。9. 小结Composio 文档站的 CI/CD 管线展示了一条成熟的演进路线数据同步自动化Cron 生产部署事件驱动、AI Agent 自动化维护Claude Code 同步客户端、Codex 跟进 changelog、claude 按需审查、多级质量门禁链接/类型/构建/测试/线上巡检与治理兜底密钥扫描、stale 清理、失败追踪 issue。对于任何内容随后端 API 漂移的文档型仓库这份管线清单与其背后的 App Token、next分支、静默失败自愈等模式都值得作为设计蓝本直接参考。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Composio 文档站 CI/CD 管线全解析：从 GitHub Actions 工作流到自动化文档维护
Composio 文档站 CI/CD 管线全解析从 GitHub Actions 工作流到自动化文档维护【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本文以 Composio 仓库中docs/agent-guidance/context/pipelines.md为骨架结合.github/workflows/下 37 个真实工作流文件系统梳理文档站docs、SDK 构建与仓库治理三套 CI/CD 管线谁在何时触发、执行了什么、产出什么 PR以及沉淀下来的关键工程模式App Token 鉴权、next分支策略、静默失败追踪等。读完本文你既能按图索骥定位任意自动化任务的实现文件也能把这套AI Agent 自动维护文档 数据自动同步 多级质量门禁的管线设计复用到自己的文档型仓库中。1. 管线全景一份工作流速查表Composio 的 CI/CD 可以划分为三组文档工作流Docs Workflows、SDK/构建工作流SDK/Build Workflows与其他治理工作流Other Workflows。原文档给出了完整清单此处逐条保留并补充真实文件路径与触发细节。1.1 文档工作流Docs Workflows工作流文件触发方式职责Update Datadocs-update-data.ymlCron每 5 小时、repository_dispatchApollo/Mercury 生产部署、手动抓取 toolkits 数据、两份 OpenAPI 规范v3.1 v3.0、生成两个版本的 API 索引页与 meta tools 参考文档通过peter-evans/create-pull-request创建指向next的 PRSync Connect Clientsdocs.sync-connect-clients.ymlCron每日 UTC 8:00、手动、repository_dispatchdashboard 生产部署用 Claude Code 动作将ComposioHQ/composio_dashboard的客户端定义同步到composio-connect.mdx创建指向next的 PRChangelog → Docsdocs.changelog-to-docs.ymlPush 到nextchangelog 文件变化用 Codex 动作读取新增 changelog 条目并更新文档页面创建指向next的 PRCheck Linksdocs-check-links.ymlPR 修改docs/运行bun run scripts/validate-links.ts捕获失效的内部链接Lint TypeScriptdocs-typescript-check.ymlPR 修改docs/依次运行bun run lintoxlint、bun run types:check与bun run build校验 Twoslash 代码块Docs Testsdocs-tests.ymlPR 修改docs/运行文档测试套件静态测试 集成测试Health Checkdocs.health-check.ymlCron每小时探测线上文档站是否正常响应Changelog Notificationdocs.changelog-notification.ymlPush 到nextchangelog 文件变化新 changelog 条目合并后发送通知Doc Reviewclaude-code-doc-review.ymlPR 评论中包含claude按需让 Claude Code 审查文档 PR1.2 SDK/构建工作流SDK/Build Workflows工作流文件触发方式职责Generate SDK Docsgenerate-sdk-docs.ymlPush 到nextSDK 源码变化、手动从 TS/ Python 源码生成 SDK 参考文档TS Buildts.build.ymlPR 修改ts/构建 TypeScript 包TS Testts.test.ymlPR 修改ts/运行 TypeScript 测试TS E2Ets.test-e2e.ymlPR 修改ts/运行 E2E 测试Node、Deno、CloudflareTS Typecheckts.typecheck.ymlPR 修改ts/SDK 类型检查TS Releasets.release.ymlPush 到next、手动创建 Changesets 发布 PR 并发布 TypeScript 包TS Auditts.audit.ymlCronnpm 依赖安全审计Build CLI Binariesbuild-cli-binaries.ymlRelease构建 CLI 二进制用于分发CLI Test Installationcli.test-installation.ymlPR 修改 CLI测试 CLI 安装流程Python Checkpy.check.yamlPR 修改python/Python SDK 的 lint 与类型检查Python Testpy.test.ymlPR 修改python/运行 Python 测试Python Releasepy.release.ymlpy*标签、手动构建并发布 Python 包1.3 其他治理工作流Other Workflows工作流文件触发方式职责Claude Codeclaude.ymlIssue/PR 评论包含claude通用 Claude Code 仓库级任务Secrets Detectionsecurity.secrets-detection.ymlPR扫描误提交的密钥Stalestale.ymlCron每日 00:00 UTC标记并关闭陈旧的 issue 与 PR除上述清单外仓库还包含 docs-rebuild-kb-semantic.yml、docs-search-sync.yml、docs-update-kb.yml、docs.sdk-change-sync.yml、docs-agent-eval.yml 等文档相关辅助工作流以及 dead-code.yml、examples-live.yml、issue-triage.yml 等仓库治理工作流共同构成了完整的自动化体系。2. 文档数据自动同步Update Data 工作流深读docs-update-data.yml是整个文档站的数据泵负责把生产环境的后端元数据持续灌入文档仓库。它的完整执行链路值得逐段拆解触发源有三个定时 Cron0 */5 * * *每 5 小时repository_dispatchapollo-production-deploy与mercury-production-deploy两种事件类型即后端生产环境每部署一次就联动刷新一次文档数据workflow_dispatch手动触发。凭证设计关键细节该工作流专门使用COMPOSIO_DOCS_API_KEY而不是共享的COMPOSIO_API_KEY。工作流注释明确解释了原因——共享密钥同时被ts.test-e2e、py.test、py.check、ts.examples-nightly使用且都面向staging环境而本工作流是唯一需要访问production的任务scripts/production-api.mjs 会拒绝任何非生产 base URL两者凭证域不同不能混用。这一点是避免文档意外展示 staging 主机与未发布内容的关键防线。执行步骤链用actions/create-github-app-token生成 GitHub App 短期令牌而非长期 PATcheckout 仓库bun install安装依赖用actions/cache缓存 bun 依赖bun run generate:toolkits—— 刷新 toolkits 目录bun run scripts/fetch-openapi.mjs—— 抓取 OpenAPI 规范bun run generate:api-index—— 生成两个 API 版本的索引页bun run generate:meta-tools—— 生成 meta tools 参考文档KB 新鲜度校验bun scripts/verify-kb.ts --check-links --check-source-pin对比已发布 KB 文章的断言与本次刷新后的目录是否一致发现不匹配会报告但不阻塞数据同步检测文件变化git diff判断docs/public/data/、openapi.json、openapi-v3.json、api-reference/、v3/api-reference/等路径有变化则用peter-evans/create-pull-request创建 PRbase: next分支docs/auto-update-data并自动把触发者添加为 reviewer。静默失败自愈机制值得借鉴的工程实践工作流内置了失败追踪 issue逻辑。注释指出如果同步静默失败docs/public/data/toolkits.json停止刷新文档站仍能基于最后一次好提交继续构建不会 500但新 toolkits 会直接 404——这正是历史上一次凭据故障连续 60 次运行未被发现的根因。因此工作流在失败时用docs-data-sync-failure标签创建追踪 issue不重复创建成功后自动关闭该 issue形成红灯即修、绿灯自愈的闭环。3. AI Agent 驱动的文档维护三个自动化写作/审查工作流这套管线最有特色的是引入了多个 AI Agent 作为文档维护主力且每个 Agent 都有独立的指令文件位于 docs/agent-guidance/agents/3.1 Sync Connect ClientsClaude Code 同步客户端定义docs.sync-connect-clients.yml的工作流程取数repository_dispatch事件携带client_definitionsbase64 编码的客户端定义 TS 文件或手动触发时用gh api从ComposioHQ/composio_dashboard仓库拉取client-definitions.tsAI 同步调用anthropics/claude-code-action授予受限工具集Read,Write,Edit,Glob,Grep,Bash(curl *)prompt 指示它先读 docs/agent-guidance/agents/connect-clients-sync.md 获取完整指令再对比/tmp/client-definitions.ts与现有docs/content/docs/composio-connect.mdx更新新增/变更的客户端步骤、描述并下载新客户端 logo 到docs/public/images/clients/PR 产出若无差异则不改任何文件有差异则由peter-evans/create-pull-request创建指向next的 PR分支docs/auto-sync-connect-clients并把触发者加为 reviewer。工作流注释点明了一个容易被忽视的坑GITHUB_TOKEN无法在此仓库创建 PR仓库关闭了Allow GitHub Actions to create and approve pull requests因此所有开 PR 的工作流都必须铸造 release-bot App token。3.2 Changelog → DocsCodex 依据 changelog 更新文档docs.changelog-to-docs.yml在每次向next推送 changelog 文件docs/content/changelog/**.mdx时触发用git diff --name-only --diff-filterAM在提交区间before..after中找出新增/修改的 changelog 文件并处理首次推送before 全零的边界情况调用openai/codex-action沙箱workspace-writeprompt 要求它先读 docs/agent-guidance/agents/changelog-docs-updater.md 获取指令再逐个分析 changelog 文件搜索docs/content/docs/中受影响的页面并更新若无文档变更则不创建 PR有变更则用git checkout -bgh pr create手工开 PRbasenextreviewer 请求被刻意拆成独立 best-effort 步骤避免因无法指派的 actor 导致整个命令失败、留下孤儿分支。配套的 changelog-docs-updater.md 给出了变更分类→文档动作映射表这是让 Agent 输出稳定质量的核心约束Changelog 类型文档动作破坏性变更新 API 签名、移除参数更新受影响指南中的代码示例新特性新参数/方法/选项融入相关既有指南的合适位置弃用在旧用法附近添加Callout typewarn提示行为变更默认值、响应格式变化更新引用旧行为的描述与示例Toolkit 变化无需改文档toolkit 页面自动生成Bug 修复 / 性能优化 / 基础设施变更无需改文档同时该 Agent 有明确红线只允许修改docs/content/docs/与docs/content/examples/禁止新建页面禁止在文档里写as of v0.6.0...式的 changelog 口吻TS 代码块受构建期类型检查约束必须在// ---cut---上方补全 import详见 docs/agent-guidance/context/twoslash.md。3.3 Doc Reviewclaude 按需代码审查claude-code-doc-review.yml在 PR 修改docs/content/**/*.mdx、docs/components/**/*.tsx、docs/app/**/*.tsx、docs/app/**/*.css时运行prompt 指示 Claude Code 依据 docs-reviewer.md 的审查清单执行git diff origin/${{ github.event.pull_request.base.ref }}...HEAD检查变更发现问题则评论具体修复建议无问题则批准并回复 Looks good。工作流还预置了allowed_bots白名单与可选的按作者定制 prompt 模板。4. 质量门禁链接检查、类型校验与测试文档 PR 在合并前要经过三层质量门禁均为pull_request触发路径过滤docs/**Check Linksdocs-check-links.ymlPR 路径下只跑内部链接校验bun run lint:links即bun scripts/validate-links.ts每日 02:30 的 Cron 额外跑bun run lint:links:external对外部链接做 HEAD/GET 检查——因为逐个检查外部 URL 很慢且依赖第三方可用性所以从不放在 PR 路径上定时任务失败时自动创建docs-external-links-failure标签的追踪 issuePR 失败则不需要因为失败对作者可见。Lint TypeScriptdocs-typescript-check.yml依次执行bun run lintoxlint、bun run types:check、bun run build。其中types:check会执行generate:kb、build-agent-index、fumadocs-mdx、next typegen并使用 TypeScript 7 做--noEmit检查见 docs/package.jsonbuild会真正构建站点从而校验 MDX 中的 Twoslash TypeScript 代码块可编译。Docs Testsdocs-tests.ymlbun run test——bun test tests/static/静态测试bun run check:kb-semantic—— 校验 KB 语义索引产物与最新生成结果一致bun run build后启动服务bun run start 轮询等待localhost:3000就绪30 秒超时再跑bun run test:integrationbun test tests/integration/ --timeout 30000最后无论成败都 kill 掉服务器进程。三个工作流都复用了 .github/actions/setup-node-pnpm-bun 复合动作与actions/cachekey 为docs/bun.lock的哈希保证依赖安装可复现、可缓存。5. 线上巡检与变更通知Health Checkdocs.health-check.yml每小时探测https://docs.composio.dev检查点覆盖三类LLM/Agent 入口/llms.txt、/llms-full.txt、/docs/quickstart.md、/docs/how-composio-works.md的 Markdown 形态核心页面/docs、/docs/quickstart、/toolkits、/toolkits/github期望 200以及/toolkits/__definitely-not-a-toolkit__期望 404验证 404 语义正确KB 搜索 API/api/knowledge-search?qgithub oauthfilterkb需返回 JSON 且满足jq表达式.query github oauth and .filter kb and (.results | type array) and .mode hybridMarkdown 内容协商带Accept: text/markdown头请求多个页面验证服务端 Markdown 渲染能力。每个检查点失败会重试一次间隔 3 秒失败汇总后通过 Slack webhook 推送告警并使工作流最终以非零码退出。Changelog Notificationdocs.changelog-notification.yml检测推送区间内新增/修改的 changelog 文件用 grep 解析 frontmatter 中的title、date构造 changelog URL用git log追溯作者最终用jq构造转义安全的 Slack payload 发送通知。6. SDK 构建、测试与发布管线SDK 侧的工作流与文档管线共享App Token 铸造 指向next的模式但各自承担不同的生命周期职责Generate SDK Docsgenerate-sdk-docs.ymlPush 到next且 SDK 源码变化ts/packages/core/src/**、python/composio/**等路径时触发TS 侧跑pnpm --filter composio/core generate:docs生成docs/content/reference/sdk-reference/typescript/Python 侧用uv run --with griffe python scripts/generate-docs.py生成docs/content/reference/sdk-reference/python/随后各自开 PR。TS Releasets.release.ymlPush 到next或手动触发运行pnpm validate:changesets、lint、build 后交给changesets/action创建版本更新 PR 并执行pnpm changeset:release发布发布成功后在 Slack 中汇总各包old → new版本号用git show HEAD^对比。工作流注释解释了为什么用 App token 而非长期 PATApp token 不会过期且其触发的Release: update version PR 合并后的事件仍能联动下游build-cli-binaries.yml等发布流程。Secrets Detectionsecurity.secrets-detection.ymlPR 打开/同步/重开时调用 GitHub Advanced Security 的 secret scanning API 查询未关闭告警发现则在该 PR 评论警告并推送 Slack404/403 时降级为 warning 提示启用 GHAS。Stalestale.yml每日 00:00 UTC 运行60 天未活动标记stale再过 2 天关闭issue 豁免标签pinned,security,bug,needs-triage,roadmap,enhancement,good first issuePR 豁免标签pinned,security,needs-review,work-in-progress,dependencies。7. 关键模式总结这套管线的四个设计原则原文档在末尾提炼了四条 Key Patterns结合源码可以进一步扩展为可复用的工程原则文档 PR 永远指向next而非master。所有自动开 PR 的工作流Update Data、Sync Connect Clients、Changelog → Docs、Generate SDK Docs的base都是next确保自动化改动先经过主开发分支的完整验证再进入发布线。自动 PR 统一走peter-evans/create-pull-request或手工gh pr create。由于仓库关闭了 Actions 直接创建/批准 PR 的权限所有开 PR 的工作流都必须先用actions/create-github-app-token铸造 release-bot App tokenclient-id 取自vars.RELEASE_BOT_CLIENT_ID私钥取自secrets.RELEASE_BOT_APP_PRIVATE_KEY这是贯穿 docs-update-data.yml、docs.sync-connect-clients.yml、docs.changelog-to-docs.yml、ts.release.yml 的同一模式。AI Agent 工作流把行为准则外置到指令文件docs/agent-guidance/agents/下的 connect-clients-sync.md、changelog-docs-updater.md、docs-reviewer.md 以独立文件形式约束 Claude Code / Codex 的行为边界可改哪些目录、禁止做什么、输出规范prompt 只做读指令 执行的引导既保证可维护性也让 Agent 输出稳定。定时工作流如果要为next目标 PR 检出代码必须显式指定ref: next。例如 docs.sync-connect-clients.yml 的 checkout 步骤使用ref: next和fetch-depth: 1确保基于正确的分支基线做 diff 与 PR。除此之外从源码中还能提炼出两个文档未明说但贯穿始终的隐性原则静默失败必须可见定时任务失败自动开追踪 issue、恢复后自动关闭如 Update Data 的docs-data-sync-failure与 Check Links 的docs-external-links-failure敏感凭据按环境隔离production 专用COMPOSIO_DOCS_API_KEY与 staging 共享的COMPOSIO_API_KEY严格分离避免 staging 数据泄漏进生产文档。8. 如何在本地复现这些检查文档站的质量门禁全部对应 docs/package.json 中的脚本可在本地逐一复现 CI 行为需 Node ≥ 24 与 bun 运行时cd docs bun install # 安装依赖postinstall 自动生成 KB 与 fumadocs-mdx bun run lint # oxlint 静态检查对应 docs-typescript-check.yml bun run types:check # KB 生成 agent 索引 fumadocs-mdx next typegen tsc --noEmit bun run lint:links # 校验内部链接对应 docs-check-links.yml 的 PR 路径 bun run lint:links:external # 追加外部链接检查对应每日 Cron 路径 bun run test # 静态测试 bun test tests/static/ bun run test:integration # 集成测试 bun test tests/integration/ bun run verify:kb # KB 新鲜度校验对应 Update Data 中的 verify-kb 步骤 bun run build # next build校验 Twoslash 代码块数据生成类任务也可以手动运行以预览自动 PR 的产出bun run generate:toolkits、bun run scripts/fetch-openapi.mjs、bun run generate:api-index、bun run generate:meta-tools正是 docs-update-data.yml 中四个生成步骤的本地等价命令注意拉取 OpenAPI 需要访问 production API 的COMPOSIO_DOCS_API_KEY本地无凭据时该步骤会失败属预期行为。9. 小结Composio 文档站的 CI/CD 管线展示了一条成熟的演进路线数据同步自动化Cron 生产部署事件驱动、AI Agent 自动化维护Claude Code 同步客户端、Codex 跟进 changelog、claude 按需审查、多级质量门禁链接/类型/构建/测试/线上巡检与治理兜底密钥扫描、stale 清理、失败追踪 issue。对于任何内容随后端 API 漂移的文档型仓库这份管线清单与其背后的 App Token、next分支、静默失败自愈等模式都值得作为设计蓝本直接参考。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考