Composio 文档站点的 AI Agent 协作体系agent-guidance 目录全景解析【免费下载链接】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/composioComposio 文档站基于 Fumadocs/Next.js 构建背后并非只有人类编辑还有一套专为 AI Agent 设计的协作基础设施。docs/agent-guidance/目录是该体系的中枢神经它收纳了 GitHub Actions 与人类共用的工作流提示词agents/、文档站架构参考context/、以及任务型文档写作指引guides/。本文将以 docs/agent-guidance/README.md 为骨架完整剖析这套指引体系的设计思路、每份文档的职责与关键规则并对照仓库中的源码与配置验证其实现细节帮助你理解如何让 AI Agent 安全、可预期地维护一个大型开源项目的技术文档。一、目录定位AI Agent 进入文档仓库的第一道门docs/agent-guidance/README.md开宗明义地定义了自身角色面向文档站的中性 Agent 指引Neutral agent guidance。它不偏向任何特定模型或厂商而是提供事实性的操作约束。目录结构划分为三大块agents/GitHub Actions 与人类共用的工作流提示词workflow promptscontext/文档站架构参考docs-site architecture referencesguides/任务型文档写作指引task-specific docs writing guidance该 README 同时强调在加载这些参考之前应先把 docs/AGENTS.md 作为入口。这意味着整套指引有明确的加载顺序——AGENTS.md提供总纲Scope、命令、规则agent-guidance/提供针对具体任务的细化手册。这种总纲 分册的设计让 Agent 既能快速了解全局约束又能在执行特定任务时按需加载深度细节。二、工作流提示词agents/ 下的三份自动化岗位说明书agents/目录包含三份由 GitHub Actions 触发的 Agent 工作流提示词每一份都对应一条自动化流水线。2.1 Changelog → Docs Updater让发布记录自动反哺文档触发时机当docs/content/changelog/*.mdx文件被推送到next分支时触发自动创建包含文档更新建议的 PR。对应 CI 工作流为docs.changelog-to-docs.yml见 docs/agent-guidance/context/pipelines.md 中的Changelog → Docs行。核心流程详见 agents/changelog-docs-updater.md读取每个新增/修改的 changelog 文件将变更分类破坏性变更、新功能、弃用、Bug 修复、行为变更在docs/content/docs/中搜索涉及受影响功能的页面进行有针对性的文档更新关键决策表并非所有变更都需要改文档。该提示词用一张映射表明确什么该改、什么不该改Changelog 类型文档动作破坏性变更新 API 签名、删除参数更新受影响指南中的代码示例以使用新 API新功能新参数、新方法、新选项自然加入相关既有指南弃用Deprecation在弃用用法附近添加Callout typewarn提示行为变更默认值、响应格式变化更新引用旧行为的描述与示例Toolkit 变更新 toolkit、弃用、凭据移除、toolkit 级配置无需改文档toolkit 页面自动生成Bug 修复无 API 变更无需改文档性能改进无需改文档基础设施/内部变更无需改文档这一表格体现了自动化维护的关键哲学避免 Agent 过度修改。只有对用户可感知的 API/行为变化才需要动文档内部变化一律跳过。操作边界Rules只允许修改docs/content/docs/与docs/content/examples/下的文件禁止新建页面只更新既有页面禁止在文档中加入 changelog 风格内容如自 v0.6.0 起……文档应描述当前行为禁止与 changelog 无关的修饰性或风格性改动遵循既有文档模式Python/TypeScript 用 Tabs、警告用CalloutTypeScript 代码块会在构建时被类型检查需在// ---cut---上方补充 import详见context/twoslash.md若无需改文档则不做任何文件改动提示词还列出了最常受影响的文档页面索引Key Docs Pages引导 Agent 优先从这些页面开始搜索Sessions APIconfiguring-sessions.mdx、认证authentication.mdx、Tools toolkits、Triggers webhooks、Connected accounts、Auth configs、White labeling、Migration、SDK quickstart、Providers。2.2 Connect Clients Sync把仪表盘客户端定义同步进文档触发时机通过 dashboard 生产部署发出的repository_dispatch触发也可通过workflow_dispatch手动触发。当客户端定义发生变化时创建 PR。对应 CI 工作流为docs.sync-connect-clients.yml每日 8:00 UTC 定时 手动。数据源Source of Truthdashboard 仓库ComposioHQ/composio_dashboard中的src/app/(connect)/[org]/~/connect/clients/_components/client-definitions.ts文件其中包含ALL_CLIENTS数组记录了每个客户端的id、name、description、icon、category带分步安装说明的authMethods认证类型oauth和/或api-key目标文件docs/content/docs/composio-connect.mdx。同步流程详见 agents/connect-clients-sync.md通过 GitHub API 从 dashboard 仓库main 分支拉取client-definitions.ts读取当前composio-connect.mdx对比客户端列表、分类与安装步骤有差异则更新composio-connect.mdx以匹配 dashboardMDX 结构约束页面使用ConnectFlow与ConnectClientOption组件。示例模板ConnectFlow ConnectClientOption idclient-id nameClient Name description... icon/images/clients/logo.svg categorypopular|ide|other Steps Step StepTitleStep title/StepTitle Step description. /Step /Steps /ConnectClientOption /ConnectFlow分类映射Category Mapping只有 4 个客户端可以标记为categorypopular以标签页形式展示claude-code、codex、openclaw、claude-desktop。其余客户端进入下拉框dashboard 的IDEs分类 →categoryide其余 →categoryother。认证方法选择展示 dashboard 中的全部认证方法。当客户端同时拥有 OAuth 与 API Key 时用Tabs让用户选择当客户端只有单一认证方式时如 Claude Desktop/ChatGPT 仅 OAuthn8n 仅 API Key直接使用Steps而不用Tabs。API Key 方法必须前置一个固定的获取 API Key步骤且标签文本直接采用 dashboard 的authMethods[].label字段如 OAuth (recommended)、API Key。代码块约定占位符统一用YOUR_API_KEY而非 dashboard 的${token}变量MCP URL 统一用https://connect.composio.dev/mcp而非${MCP_URL}变量语言检测CLI 命令用bash、TOML 配置用toml、JSON 配置用json、纯文本/提示词用text客户端 Logo 同步Logo 存放在docs/public/images/clients/每次同步都要检查新增或更新的 Logo——从 dashboard 仓库的public/images/clients/主位置与public/images/logos/回退位置拉取对于需要深色模式的图标若 dashboard 无-dark变体且现有图标在深色背景不可用时需创建深色变体把填充色改为白色在 MDX 中以/images/clients/filename.ext引用有深色变体时使用iconDarkprop。禁止改动清单What NOT to Changefrontmatter除非新增客户端需要加 keywords、intro 文本、底部 Connect your apps 区块、connect-flow.tsx等组件文件、source.ts、mdx-components.tsx。这些约束确保 Agent 只做数据同步绝不触碰渲染逻辑。2.3 Docs Reviewer以开发者会不会卡住为评审准绳触发时机PR 评审评论中 claude 时按需触发对应claude-code-doc-review.yml。评审者视角目标读者是正在把 Composio 集成进 AI 应用的开发者他们需要可直接复制粘贴的可用代码、清晰的概念解释、无缺步骤的完整教程。CI 已覆盖项——不要重复评论TypeScript 错误Twoslash 构建时校验、frontmatter schema日期格式、必填字段自动校验、MDX 语法构建失败、import 错误缺组件构建失败。内容文件.mdx评审标准——只在开发者会卡住或被误导时标记问题示例API 用法错误代码写composio.execute()但实际方法是composio.tools.execute()缺步骤教程说authenticate但没演示怎么做过时模式使用已弃用的getTools()而非tools.get()输出描述错误说返回数组但实际返回对象逻辑错误步骤顺序颠倒或前置条件在需要之后才提到CI/非交互缺口代码本地可跑交互式 auth 提示但在 CI/GitHub Actions 会失败且无说明缺少索引条目新增 cookbook/页面但未列入父索引页或meta.json不要标记风格偏好、不影响理解的措辞微调、格式问题prettier 处理、TypeScript 类型Twoslash 处理。组件文件.tsx仅当 PR 修改组件文件时评审关注可访问性缺 aria labels、无键盘导航、非语义 HTML、移动端适配、与docs/components/既有组件的模式一致性。反馈格式必须具体且可执行给出 Issue Fix 形式的代码对比。该提示词甚至内置了反过度评审约束不要留下模糊评论、不要评论没问题的地方、不要为了显得彻底而编造问题。三、架构参考context/ 下的五份系统说明书context/目录为 Agent 提供文档站的技术架构背景是理解为什么某些规则必须存在的底层依据。3.1 API Reference CustomizationOpenAPI 参考页的定制实现context/api-reference.md 详细记录了 API 参考页如何从public/openapi.jsonv3.1 规范自动抓取与public/openapi-v3.jsonv3.0 规范自动生成以及用 hooks 和 CSS 覆盖定制 fumadocs-openapi 渲染的完整链路public/openapi.json ← v3.1 spec (auto-fetched, dont edit manually) public/openapi-v3.json ← v3.0 spec (auto-fetched, dont edit manually) components/api-page.tsx ← createOpenAPIPage config, schema render hook (use client) components/schema-generator.tsx ← walks OpenAPI schema → SchemaUIGeneratedData components/custom-schema-ui.tsx ← renders schemas with inline expansion lib/openapi.ts ← createOpenAPI instances no_auth sentinel normalization lib/openapi-deref.ts ← inlines in-document $refs for the llms.mdx generator lib/openapi-slice.ts ← narrows the document to one page before it crosses to the client app/global.css ← CSS overrides targeting fumadocs-openapi classes关键设计点包括Stripe 风格内联展开式 schema 渲染替代默认的 popover 方案schema-generator.tsx在客户端遍历 schema 生成SchemaUIGeneratedDatacustom-schema-ui.tsx用 Radix Collapsible 实现展开/收起isResponse标志派生自client.name response而非readOnly因为 GET 参数和请求体也设置readOnly无法区分响应playground: { enabled: true }开启交互式 API Playground请求经/api/proxy代理双版本并置v3.1 默认位于/reference/...v3.0 位于/reference/v3/...通过lib/api-version.ts的detectApiVersion()单一事实源统一识别该文档还给出了一条对 Agent 极其重要的版本身份规则.md、llms.txt、llms-full.txt与 Context7 摄取这些markdown 通道不走浏览器渲染路径因此版本下拉框、base URL、版本徽章等信号会丢失。两条 markdown 渲染器getLLMTextmdxToCleanMarkdown与openapiPageToMarkdown失败方式不同任何新通道都必须遵守组合规则宽通道SESSION_GUARDRAILS、DIRECT_EXECUTION_GUARDRAILS组合 REST 与 TOOL 两类版本指引OpenAPI 操作页始终获得REST_VERSION_GUIDANCE而仅在命中工具路径时附加TOOL_VERSION_GUIDANCE。任何新增的版本相关渲染必须经过detectApiVersion禁止内联/reference/v3/字符串测试。3.2 Fumadocs Framework文档站的框架底座context/fumadocs.md 提供框架层面的速查关键文件source.config.tsMDX 集合与 schema 定义、lib/source.tssource loaders、app/(home)/layout.tsx首页导航、app/docs/layout.tsx带侧边栏的文档布局、app/global.css全部自定义样式与设计 token、mdx-components.tsxMDX 组件注册设计 token--composio-orange: #ea580c品牌强调色、--composio-sidebar: #f7f5f2浅色侧边栏/#252220深色侧边栏、--font-sans: Inter正文、--font-mono: IBM Plex Mono代码块内容结构content/docs/主文档、content/examples/示例指南、content/changelog/发布记录、content/reference/SDK 与 API 参考全局可用 MDX 组件Tabs/Tab、Accordion/Accordions、Callout、Step/Steps、Card/Cards、ProviderCard、FrameworkSelector、IntegrationTabs、ToolTypeFlow、Figure/Video、CapabilityCard、ToolkitsLanding、StepTitle、Glossary以及一组 Lucide 图标部署Vercel项目composio/docs根目录为 monorepo 子文件夹docs构建命令bun installbun run build常见坑CSS 变量必须用var(--composio-orange)而非var(--orange)changelog 日期必须是 YYYY-MM-DDpublic/data/toolkits.json必须存在缺失会抛错而非静默忽略Vercel 根目录设为docs且必须禁用 Include files outside root directoryTwoslash 在bun dev下因堆内存问题被禁用本地需bun run build才能捕获类型错误。3.3 CI/CD Pipelines全部文档相关流水线速查context/pipelines.md 汇总了文档站相关的全部 GitHub Actions 工作流文档工作流工作流触发方式职责Update Datadocs-update-data.ymlCron 每 5 小时 repository_dispatchApollo 部署 手动抓取 toolkits 数据、双版本 OpenAPI 规范v3.1 v3.0、生成双版本 API 索引页与 meta tools 参考通过peter-evans/create-pull-request创建指向next的 PRSync Connect Clientsdocs.sync-connect-clients.ymlCron 每日 8:00 UTC 手动Claude Code action 将 dashboard 的客户端定义同步到composio-connect.mdxAgent 指令即 agents/connect-clients-sync.mdChangelog → Docsdocs.changelog-to-docs.yml推送 changelog 文件到nextCodex action 读取新 changelog 条目并更新文档页Agent 指令即 agents/changelog-docs-updater.mdCheck Linksdocs-check-links.ymlPR 修改docs/运行bun run scripts/validate-links.ts捕获失效内部链接Lint TypeScriptdocs-typescript-check.ymlPR 修改docs/bun run lintoxlintbun run types:checkbun run build校验 Twoslash 代码块Docs Testsdocs-tests.ymlPR 修改docs/运行文档测试套件Health Checkdocs.health-check.ymlCron检查线上文档站是否正常响应Changelog Notificationdocs.changelog-notification.yml推送 changelog 到next新 changelog 条目合并后发送通知Doc Reviewclaude-code-doc-review.ymlPR 评审评论中 claudeClaude Code 按需评审文档 PRAgent 指令即 agents/docs-reviewer.mdSDK/构建工作流generate-sdk-docs.yml生成 SDK 参考文档、ts.build.yml、ts.test.yml、ts.test-e2e.ymlNode/Deno/Cloudflare E2E、ts.typecheck.yml、ts.release.ymlChangesets 发布、ts.audit.ymlnpm 依赖安全审计、build-cli-binaries.yml、cli.test-installation.yml、py.check.yaml、py.test.yml、py.release.yml。其他工作流claude.yml仓库级通用 Claude Code、security.secrets-detection.yml密钥泄露扫描、stale.yml过期 issue/PR 标记。关键模式Key Patterns文档 PR 永远指向next而非master自动 PR 工作流使用peter-evans/create-pull-request或手动gh pr createAI Agent 工作流使用docs/agent-guidance/agents/下的指令文件定时工作流若为next目标 PR 检出代码必须使用ref: next3.4 SDK Reference自动生成的双语言 SDK 文档context/sdk-reference.md 说明 SDK 参考文档完全由源码自动生成项TypeScript SDKPython SDK来源ts/packages/core/src/models/*.tsJSDoc 注释python/composio/**/*.pydocstrings生成器ts/packages/core/scripts/generate-docs.tspython/scripts/generate-docs.pygriffe输出content/reference/sdk-reference/typescript/content/reference/sdk-reference/python/重新生成pnpm --filter composio/core generate:docscd python uv run --with griffe python scripts/generate-docs.pyCI.github/workflows/generate-sdk-docs.yml在ts/packages/core/src/**或python/composio/**变化时自动生成。这解释了 docs/AGENTS.md 中API 参考页与 toolkit/meta-tool 数据均为生成产物不得手改的规则来源——手改会在下次生成时被覆盖。3.5 Twoslash构建期 TypeScript 代码块类型检查context/twoslash.md 定义了一条硬性约束所有 TypeScript 代码块在构建期被类型检查确保文档与 SDK 保持同步。Python 代码块不检查。默认开启无需注释类型错误直接导致构建失败CI 强制执行docs-typescript-check.yml在 PR 涉及docs/时运行bun dev下禁用防堆内存问题仅在bun run build/CI 中运行content/reference/通过集合级mdxOptions排除自动生成内容无需类型检查常用模式// ---cut---隐藏上方编译用代码import、变量声明只展示下方内容SDK 导出类型替代内联注解如TransformToolSchemaModifier另有beforeExecuteModifier、afterExecuteModifier// noErrors跳过类型检查用于部分片段或外部依赖declare const在隐藏区声明外部变量注解表// ---cut---、// noErrors、// errors: 2322预期特定错误码、// ^?悬停显示类型排障表import 失败 → 确保包在devDependencies外部依赖 →// noErrors需要 setup 代码 →// ---cut---错误 2304找不到名字→ 在隐藏区声明变量错误 2322类型不匹配→ 修复类型或使用 SDK 导出类型回调类型 → 优先导入 SDK 类型而非内联{ foo: string }。提交前务必本地运行bun run build验证全部代码块。四、写作指南guides/changelog.md 与版本发布约束guides/changelog.md 是唯一一份任务型写作指引规定了 changelog 条目的硬性规范。文件命名MM-DD-YY.mdx如12-29-25.mdx同日多条用后缀区分如12-10-25-masking.mdx。对照仓库docs/content/changelog/目录可以观察到从09-15-25.mdx到09-04-26-cli-and-sdk-releases.mdx的长序列文件其中大量使用了-suffix命名模式。模板结构frontmatter 必须包含title与datedate 为 YYYY-MM-DD 格式--- title: Your Title Here date: YYYY-MM-DD --- Brief intro paragraph. ### SDK Versions (if applicable) | SDK | Version | |-----|---------| | Python composio | 0.10.2 | | TypeScript composio/core | 0.3.1 | ### Breaking Changes (if applicable) Callout typewarn **Breaking Change** What breaks and why. /Callout **Before:** python old_code()After:new_code()Whats New / Improvements / Bug FixesChange 1Change 2**规则**1) frontmatter 必填 title 与 dateYYYY-MM-DD2) 不使用 # 标题标题由 frontmatter 自动渲染3) 小节用 ### 起始4) 不使用 emoji。 **变更类型格式**Breaking Change 用 Callout typewarn before/after 代码 迁移指南New Feature 用 ### Whats NewImprovement 用 ### ImprovementsBug Fix 用 ### Bug FixesDeprecation 用带时间线的 Callout。 **破坏性变更清单**before/after 代码示例、带分步说明的迁移指南、codemod如适用——自动转换旧代码为新的脚本可参考 jscodeshift/ts-morph 类工具。 该指南还透露了一个与发布流水线的耦合点最终表格列必须使用已发布版本号Python 发布守卫会读取标记为 Python \composio\ 的行。这一点与 [docs/AGENTS.md](https://link.gitcode.com/i/13ec04ffb29a3abfbf06b04db23f72df) 中Changelog 条目需要 title 和 date frontmatter日期用 YYYY-MM-DD的规则相互印证。 ## 五、知识库停用区knowledge-base.md 的内容治理机制 [knowledge-base.md](https://link.gitcode.com/i/2ac2e46f26f1f30b08f12ec6532730b2) 是一个特殊存在它是文档改版期间从发布文档中移除/暂存内容的停靠区dumping ground。这些内容不参与渲染保留是为了不丢失日后可能重新引入的细节例如更深层的指南、FAQ、面向 LLM 的 .md 输出。每条记录包含四个要素**它是什么、来自哪里、为何移除、内容本身**。 当前暂存了一份有代表性的内容**Native Tools vs MCP决策框架**。它原为 content/docs/native-tools-vs-mcp.mdx 整页 quickstart.mdx 中的 native/MCP 标签页拆分因团队决定不再让用户在前端做 native-vs-MCP 抉择、默认全部使用 native tools 而移除。被暂存的对比表保留了有价值的论证 | | Native tools | MCP | |---|---|---| | **Setup** | 为你的框架提供 provider 包 | SDK 或仅一个 URL | | **拦截工具调用** | 可以记录、重试、每次调用前要求审批 | 有限取决于 MCP 客户端支持 | | **上下文窗口** | 你控制加载什么 | 客户端加载服务器暴露的全部工具 | | **延迟** | SDK 直接调用 Composio API | MCP 协议为工具列表发现与每次执行增加开销 | 文件末尾还诚实地标注了一条**事实修正备注**token 成本论述对 Composio sessions 略有失真——session.tools() 返回的是 meta toolssearch/execute而非完整工具列表因此55K tokens 客户端加载一切的论点适用于朴素 MCP未必适用于基于 MCP 的 Composio session。若重新引入需重写得更清晰。这个细节展示了该知识库机制的严谨性即使暂存内容也要保留对已知瑕疵的标注。 ## 六、总纲与分册AGENTS.md 如何串起整套体系 回到入口 [docs/AGENTS.md](https://link.gitcode.com/i/13ec04ffb29a3abfbf06b04db23f72df)可以看到它承担了总纲角色与 agent-guidance/ 形成互补 - **Scope**docs/ 是 Fumadocs/Next.js 站点文档 PR 从 next 分支开出并指向 next - **Read Next 指引**内容类任务先读 docs-decisions skill上下文参考在 docs/agent-guidance/context/编辑带类型的 MDX 示例前必读 twoslash.md工作流提示词在 docs/agent-guidance/agents/changelog 指引在 docs/agent-guidance/guides/changelog.md决策记录在 docs/decisions/先读 README.md - **常用命令**从 docs/ 目录运行bun install、bun run dev、bun run build、bun run types:check、bun run lint、bun run lint:links、bun run test、bun run test:integration、bun run generate:toolkits、bun run generate:meta-tools、bun run generate:api-index - **硬性规则**MDX 中 TypeScript 代码块构建时检查未类型化/外部数据JSON、抓取载荷、框架页面数据必须在边界用 zod schema 解析一次并让 z.infer 类型向下游流动禁止手写结构守卫x in obj/typeof 链、as 强转或 z.custom(() true) 假校验内部文档链接必须为相对站点路径/docs/...、/reference/...、/assets/...生成数据不得手改changelog 条目需 title/date frontmatter 且日期 YYYY-MM-DDAPI 交互优先 cURL文档同时被人类与 AI 爬虫消费链接 dashboard.composio.dev 必须带 utm_sourcedocs、utm_medium、utm_campaign 参数带路径的链接必须是 go-link/~/project/... 或 /~/org/...或 /login绝不链接 app.composio.dev 或 platform.composio.dev 这套规则的校验已落入自动化oxlint 强制 TS/TSX 规则tests/static/dashboard-links.test.ts 强制 MDX 中的 dashboard 链接规范。也就是说Agent 的软约束提示词与硬约束CI 检查相互配合——提示词负责引导行为CI 负责兜底拦截。 ## 七、落地建议如何在你的文档仓库复刻这套体系 从 Composio 的实践中可以提炼出一套可复用的文档站 Agent 治理方法论 1. **分层指引**总纲AGENTS.md 分册agent-guidance/Agent 先读总纲再按任务加载分册避免一次注入过多上下文。 2. **明确的变更边界**每份工作流提示词都列出只允许改哪些文件与绝对禁止改哪些内容frontmatter、intro 文本、组件文件、生成数据把 Agent 的自由度收敛到数据同步层面。 3. **变更分类驱动决策**Changelog → Docs 的映射表说明不是所有变更都值得改文档——给 Agent 一张该改/不该改的判定表能显著降低无意义 PR 率。 4. **双重校验**Twoslash 构建期类型检查 oxlint 链接校验 dashboard 链接专项测试把 Agent 的软性行为约束固化为 CI 硬性拦截。 5. **单一事实源**Connect Clients 同步以 dashboard 仓库为唯一真相OpenAPI 文档以自动抓取的 spec 为真相SDK 文档以源码注释为真相——Agent 只做搬运不做创作从根源上避免文档漂移。 6. **决策留痕**knowledge-base.md 证明被移除的内容也应存档并标注原因与已知瑕疵为日后重新引入保留素材。 如果你希望在自己维护的开源文档仓库中引入 AI Agent 自动维护可以直接参照 docs/agent-guidance/ 的目录结构agents/ context/ guides/并结合 [docs/AGENTS.md](https://link.gitcode.com/i/13ec04ffb29a3abfbf06b04db23f72df) 中的命令与规则清单、[docs/agent-guidance/context/pipelines.md](https://link.gitcode.com/i/80071ed794ea4b3e1debbd1eb67bbc24) 中的工作流矩阵来设计自己的自动化流水线。【免费下载链接】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），仅供参考