Composio 文档站点开发工作流入口文件、构建命令、内容规则与自动化维护指南【免费下载链接】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 仓库中面向文档维护者与 AI Agent 的实战工作流指南聚焦docs/目录下 Fumadocs/Next.js 文档站点的日常开发与自动化流程。读完本文你将掌握文档工作的标准入口文件、九大核心命令的底层实现、八条内容红线以及文档自动化提示词与决策记录ADR的维护规范能够安全、合规地参与 Composio 文档的修改与评审。工作流全景先读入口再动手Composio 的文档站点docs/目录是一个基于 Fumadocs/Next.js 构建的站点。为了保证文档质量、类型安全与内容一致性仓库沉淀了一套标准化的文档工作流其权威定义位于 .agents/skills/docs-decisions/references/docs-workflow.md并由.agents/skills/docs-decisions/SKILL.md技能入口统一调度。这套工作流的核心思想是任何文档改动都必须先阅读入口文件再依据上下文参考与自动化提示词行动最后通过命令矩阵验证。完整的入口文件清单如下入口用途仓库路径文档主指引编辑任何文档前必读的总纲docs/AGENTS.md上下文参考文档站点架构参考资料含 Twoslash 类型检查规范docs/agent-guidance/context/自动化提示词供 GitHub Actions 与人类共同使用的工作流提示词docs/agent-guidance/agents/变更日志指南编写 changelog 的格式与规则docs/agent-guidance/guides/changelog.md决策记录ADR 风格的长期文档计划docs/decisions/其中 docs/agent-guidance/README.md 对这三类资源做了定位说明agents/存放工作流提示词、context/存放站点架构参考、guides/存放任务级写作指导并强调始终以docs/AGENTS.md为总入口。核心命令矩阵九个命令的底层实现与适用场景文档工作流规定了从docs/目录运行的一组命令。结合 docs/package.json 中scripts字段的实际定义可以看清每个命令背后的真实执行链路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构建与类型检查bun run build实际执行next build在此之前会自动触发prebuild钩子即bun run generate:kb bun scripts/build-agent-index.ts先重建知识库索引与 Agent 索引再执行站点构建。这是文档工作流中最重的验证命令。bun run types:check并非简单的tsc而是完整的类型验证流水线generate:kb→build-agent-index.ts→fumadocs-mdx→next typegen→ 基于 TypeScript 7 的tsc --noEmit。它同时覆盖 MDX 转换产物与手写 TS/TSX 代码。bun run lint使用 oxlint 对全目录执行静态检查oxlint .docs 站点的 TS/TSX 由 Oxlint 强制约束例如 docs/AGENTS.md 中提到的 dashboard 外链规范。链接与测试bun run lint:links执行bun scripts/validate-links.ts校验文档内部相对链接另有bun run lint:links:external--external参数可扩展校验外部链接。bun run testbun test tests/static/运行静态测试套件如tests/static/dashboard-links.test.ts这类基于 MDX 内容的断言。bun run test:integrationbun test tests/integration/ --timeout 30000以 30 秒超时运行集成测试覆盖跨模块的联动场景。生成类命令生成数据禁止手改generate:toolkits、generate:meta-tools、generate:api-index分别对应 docs/scripts/generate-toolkits.ts、docs/scripts/generate-meta-tools.ts、docs/scripts/generate-api-index.ts。它们从 OpenAPI 与 toolkit 数据源生成参考页面。工作流明确规定生成的 OpenAPI、toolkit、meta-tool 数据只能通过脚本修改不得手工编辑生成产物这与 docs/AGENTS.md 中API reference 页面与 toolkit/meta-tool 数据均为生成物的规则相互印证。内容规则八条红线保证文档质量工作流将约束凝练为五条核心规则结合 docs/AGENTS.md 可以展开为完整的操作红线分支纪律所有文档工作从next分支切出PR 也一律指向next。这意味着文档改动与 SDK 发布节奏解耦避免主分支被文档噪音污染。Twoslash 类型检查TypeScript 代码块会被构建过程检查修改带类型示例前必须先阅读 docs/agent-guidance/context/twoslash.md。该参考详细说明所有 TS 代码块默认开启构建期校验类型错误会直接导致构建失败并配套// ---cut---隐藏 setup 代码、// noErrors跳过检查、// ^?悬停类型展示等注解以及常见错误的排查表如 2304 需在隐藏段声明变量、2322 应改用 SDK 导出类型。相对链接站内链接一律使用相对站点路径如/docs/...、/reference/...禁止使用绝对文档 URL确保文档在镜像、分叉场景下仍然可解析。生成数据走脚本OpenAPI、toolkit、meta-tool 数据必须通过其专属脚本更新禁止手工改动生成产物。API 示例优先 cURL由于文档同时被人类与 AI 爬虫阅读API 交互示例优先使用 cURL 而非 SDK 代码。此外 docs/AGENTS.md 还补充了三条工程级规则外部数据在边界处用 zod schema 一次性解析并让z.infer类型向下游流动禁止手写结构守卫、as强转或z.custom(() true)假校验changelog 条目必须带title与dateYYYY-MM-DDfrontmatter指向dashboard.composio.dev的链接必须携带utm_sourcedocs、utm_medium、utm_campaign参数且必须使用 go-link 或/login形式。文档自动化Agent 工作流与验证器Composio 的文档维护深度依赖自动化。工作流明确指出修改文档自动化提示词时必须同步更新.github/workflows/下的工作流提示词路径并运行 agent-skill 校验器以捕捉过期的指引引用。仓库根 package.json 中提供了对应脚本validate:agent-skillsnode ts/scripts/validate-agent-skills.mjs用于校验 Agent 技能路由与引用一致性。仓库中已经落地了三套自动化 Agent 工作流可直接作为实践参照docs/agent-guidance/agents/changelog-docs-updater.md当docs/content/changelog/*.mdx推送到next时触发将新 changelog 分类breaking / new feature / deprecation / behavior change / toolkit / bug fix / infra并映射到对应文档动作例如 breaking change 更新受影响指南中的代码示例、deprecation 添加Callout typewarn警告、toolkit 变更则无需改文档页面自动生成。docs/agent-guidance/agents/docs-reviewer.md规定 CI 已覆盖 TS 错误、frontmatter schema、MDX 语法与导入错误人工评审只需关注开发者是否会卡住或被误导的实质问题错误的 API 用法、缺失步骤、过期模式、错误输出描述、CI 场景缺口、遗漏索引条目。Twoslash 的 CI 强制构建期类型校验由.github/workflows/docs-typescript-check.yml在 PR 触及docs/时执行见 docs/agent-guidance/context/twoslash.md。配套实践决策记录与变更日志决策记录ADR长期文档计划与产品决策以 ADR 形式沉淀在 docs/decisions/新增或编辑记录前必须先读 docs/decisions/README.md。.agents/skills/docs-decisions/references/decision-records.md 给出了明确的写作规范先陈述决策结论再给出问题上下文、架构、运营规则与后续步骤偏好持久的产品/文档约束而非聊天记录或实现日记文件名小写且具描述性每条新记录必须登记进docs/decisions/README.md。标准模板包含四个小节——Decision、Context、Consequences、Verification其中 Verification 要求写明能证明未来改动仍遵守该决策的命令、生成产物或评审检查。若内容链接变化用bun run lint:links复验。变更日志changelog 文件命名遵循MM-DD-YY.mdx同日多条追加-suffix必须带title与datefrontmatter正文从###级标题开始且禁止 emoji详见 docs/agent-guidance/guides/changelog.md。Breaking change 需配套Callout typewarn、before/after 代码与迁移指南必要时提供 codemod 自动迁移脚本。结语Composio 文档工作流本质上是人类 Agent 协同的产物人类遵循 docs/AGENTS.md 与命令矩阵完成内容创作与验证Agent 依据agents/下的提示词自动响应 changelog 与评审任务而 Twoslash 与链接校验器在 CI 侧守住类型与链接质量底线。无论是手动改文档还是维护文档自动化本身按 .agents/skills/docs-decisions/references/docs-workflow.md 的顺序——先读入口、再查上下文、跑命令、守规则——即可保证每次改动都符合项目规范。【免费下载链接】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），仅供参考
