OpenClaude AGENTS.md 深度解读：面向 AI 编码 Agent 的仓库协作与校验契约

OpenClaude AGENTS.md 深度解读：面向 AI 编码 Agent 的仓库协作与校验契约

【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude

本篇技术指南以 OpenClaude 仓库根目录的 AGENTS.md 为骨架，系统拆解这个"runs anywhere, uses anything"的 coding-agent CLI 项目如何为 AI 编码 Agent 定义工作方式、技术栈约定、仓库地图、本地校验命令与 Provider 变更规范。读完本文，你将掌握在 OpenClaude 仓库中安全提交 PR 的完整流程、各校验命令的真实含义与源码级依据，以及一份可直接复用的 Agent 协作规则模板。

项目快照：OpenClaude 是什么

从 AGENTS.md 的 Project Snapshot 出发，OpenClaude 是一个面向云端与本地模型提供商的 coding-agent CLI，核心能力覆盖：

• 兼容 OpenAI 协议的 API，以及 Anthropic、Gemini、DeepSeek、Ollama 等多家提供商；
• MCP（Model Context Protocol）接入与本地后端；
• Slash 命令、工具（tools）、Agent（agents）体系；
• 基于 React + Ink 的终端 UI。

运行时约束在仓库根 package.json 中写得很明确：安装后的 CLI 运行于 Node.js>=22.0.0，而源码构建、脚本、依赖管理与测试统一使用 Bun。这一"Bun 开发、Node 运行"的双轨结构是整个仓库校验体系的前提。

Work Style：Agent 修改代码的行为准则

AGENTS.md 对 AI Agent 提出的工作风格要求，本质上是一套降低 review 摩擦的守则：

• 变更聚焦单一问题：避免无关格式化、重命名、依赖变更或大范围重写；
• 沿用既有模式：优先复用所在文件或邻近模块中已有的写法，而不是引入新的抽象；
• 行为变更必须补测试：任何影响行为的变化都要新增或更新测试；
• 面向用户的变化必须更新文档：setup、命令、Provider 行为或用户可见行为变化时同步更新文档；
• 大改动先提 issue：新功能、大重构、依赖与运行时变更遵循 CONTRIBUTING.md 中的 issue-first 指引；
• 分支保持与 main 同步：恢复工作或推送补充修复前先 rebase，但禁止用无保护的 force-push 覆盖远端 PR head 更新。

值得注意的是，CONTRIBUTING.md 的 AI Agent Guidelines 章节与 AGENTS.md 形成了互相引用的闭环：贡献指南要求 Agent 先读 AGENTS.md，而 AGENTS.md 又要求 Agent 遵循贡献指南。这说明该仓库已将"AI 参与协作"作为一等公民，两份文档共同构成协作契约。

Stack And Conventions：技术栈与通用模式

AGENTS.md 明确的技术栈约定为：

• TypeScript，开启 strict 模式，使用 ESM 导入（仓库 tsconfig.json 与"type": "module"的 package.json 可印证）；
• React + Ink构建终端 UI（对应src/ink/下的自研 Ink 分支与src/components/的 UI 组件）；
• Bunlockfile 与 Bun scripts 作为开发工作流；
• Node作为构建后 CLI 的运行环境。

常用依赖模式也给出了明确指引：

同时强调"现有 service、provider、settings、permission、UI 模式优先于新抽象"，这解释了为何仓库中src/services/、src/integrations/、src/tools/等目录会积累大量遵循统一模式的文件。

Repository Map：仓库地图速览

AGENTS.md 提供了一份极简的仓库地图，与根目录的 docs/repo-map.md 形成互补。核心目录职责如下：

值得强调的源码佐证：descriptor 时代的集成体系在 docs/integrations/overview.md 中有完整说明——注册由 src/integrations/index.ts 统一负责，descriptor 文件通过defineVendor、defineGateway、defineCatalog、defineModel等助手导出，注册与描述分离，这正是 AGENTS.md "Repository Map" 与 "Provider Changes" 章节背后的架构逻辑。

Validation：本地预推送校验契约

这是 AGENTS.md 篇幅最重、也最实战化的部分。核心结论是：权威的本地预推送校验契约定义在 CONTRIBUTING.md § Validation，每次向 PR 推送（含 review 期间的补充推送）都必须完整执行；CI 则提供干净 runner、受支持的 Node 版本矩阵等本地难以复现的覆盖（见 .github/workflows/pr-checks.yml，主任务在 Node 22 与 24.11.x 双版本矩阵上运行）。

核心校验命令

bun install bun run build bun run smoke bun run check bun run typecheck bun run typecheck:type-tests

对照 package.json 的 scripts 字段，可还原每条命令的真实含义：

• bun run build→bun run scripts/build.ts，产出dist/cli.mjs；
• bun run smoke→ 先 build，再执行node dist/cli.mjs --version验证产物可启动；
• bun run check→ 依次执行 smoke、deadcode（knip --include files,dependencies）与test:full（完整单测套件）——因此 CONTRIBUTING.md 明确提醒不要重复单独跑 smoke/deadcode/test，避免重复劳动；
• bun run typecheck→tsc --noEmit；
• bun run typecheck:type-tests→bun run scripts/typecheck-type-tests.ts，专门校验类型级测试。

聚焦校验命令

迭代开发阶段可缩小范围：

bun test ./path/to/test-file.test.ts bun run test:provider bun run test:provider-recommendation

其中test:provider覆盖src/services/api/*.test.ts、src/services/api/openaiShim/*.test.ts与src/utils/context.test.ts三条路径，与 Provider 变更直接相关。

Web 校验

当改动可能影响文档网站（涉及web/、根或 web 依赖与 lock 文件、共享站点资源或构建工具链）时，额外执行：

bun run web:typecheck bun run web:build

web/是独立的 Astro 站点（见 web/package.json 与 web/astro.config.mjs），其 CI 任务保持无条件运行，作为集成兜底。

诊断与 PR 卫生

bun run doctor:runtime

该命令实际执行 scripts/system-check.ts（bun run scripts/system-check.ts），它会系统性地探测 Node 版本支持（checkSupportedNodeVersion）、provider 凭证环境变量状态、Ollama 就绪度、WebSearch provider 链、沙箱适配器、内存治理配置等，并支持--json与--out reports/doctor-runtime.json两种输出模式，是提交前诊断运行环境的重要工具。

PR intent 扫描的显式引用

AGENTS.md 特别强调：PR intent 扫描必须使用规范的 upstream fetch 与显式 ref 调用，因为扫描器默认的origin/main基准在 fork checkout 下不可移植。CONTRIBUTING.md 给出的完整命令为：

git fetch https://github.com/Gitlawb/openclaude.git main bun run security:pr-scan -- --base FETCH_HEAD --head HEAD

这避免了假设 fork 的origin指向上游仓库的问题——FETCH_HEAD是被抓取的上游 tip，而HEAD保证把尚未推送的本地提交也纳入扫描。

Provider Changes：修改 Provider 行为的规范路径

当修改 Provider 行为时，AGENTS.md 给出了严格的分步流程：

1. 从 docs/integrations/overview.md 开始，理解集成系统的边界；
2. 使用 docs/integrations/how-to/ 下对应的 how-to 指南（add-vendor.md、add-gateway.md、add-model.md、add-anthropic-proxy.md、add-usage-support.md）；
3. 先检查既有 Provider 实现，再决定是否新增模式；
4. 尽可能测试你所修改的确切 provider/model 路径；
5. 修复第一方行为时避免破坏第三方 Provider。

从源码结构看，这套流程背后是 descriptor 时代的集成架构：src/integrations/下的 144 个.ts文件承载 vendor、gateway、model 描述，元数据、路由、传输三层关注点分离（详见 docs/architecture/integrations.md）。AGENTS.md 的"Provider Changes"与 CONTRIBUTING.md 的 Provider Changes 章节要求 PR 中明确说明受影响的 provider、不擅自分配 provider 标签（标签由维护者在 review 时控制），这些都在源码的 ProviderManager.tsx 等 UI 层有对应的硬编码规避设计。

Things To Avoid：红线清单

AGENTS.md 用一整节列出协作红线，对 AI Agent 尤其重要：

• 不得擅自变更 Node 运行时或 Bun 开发工作流，除非事先获得维护者同意；
• 不得新增 Python 代码、Python provider 路径或 Python 依赖；
• 不得引入无明确项目收益的依赖；
• 行为变更不得跳过测试；
• 不得静默修改 provider 标签；
• 不得忽视 CodeRabbit 或维护者反馈：采纳自动化 review 建议前，先确认其不会把 PR 拉离既定 scope 与意图——越界的建议可以带理由拒绝，或不确定时询问维护者，但绝不能静默忽略；
• 不得推送带有失败/不完整/未运行本地检查的提交，除非 CONTRIBUTING.md § Validation 的例外适用；遇到疑似 pre-existing 失败，要在 PR 中记录复现证据与基准提交；
• 不得提交仍含模板占位符的 PR 描述，每个字段都要为实际变更填写；
• 不得表面修补反复出现的 review 发现：反复的修复请求通常指向核心设计问题，应调查根因而非报告的症状——CONTRIBUTING.md 甚至建议此时重新审视驱动工作的 AI prompt 是否过于模糊；
• 不得向静态站点添加手工维护的 release-notes 数据源，应链接 GitHub Releases。

这份清单不仅是规则，更是一种防御性工程实践：它把"可 review 性"作为代码质量的先决条件，与仓库当前"stability and performance"的聚焦方向一致。

结语：把 AGENTS.md 当作协作接口而非流程负担

对 AI 编码 Agent 而言，AGENTS.md 的价值在于把隐性知识显性化：技术栈约束、目录语义、校验命令、Provider 变更路径与红线清单，全部浓缩在一份可被 Agent 读取的机器友好文档中。对开发者而言，它示范了如何为 AI 协作编写"一次性讲清规则"的仓库指南——配合 CONTRIBUTING.md 的验证契约与 .github/workflows/pr-checks.yml 的 CI 兜底，形成"本地自检 + 自动化评审 + 维护者把关"的三层质量闭环。在 OpenClaude 这样的多 Provider、多入口（CLI/MCP/SDK）大型 TypeScript 仓库中，这套契约正是其保持可维护性的关键。

【免费下载链接】openclauderuns anywhere. uses anything项目地址: https://gitcode.com/GitHub_Trending/op/openclaude