qm 仓库的 AGENTS.md 工程协作规范解读AI 编码时代的多智能体 Agent 项目开发纪律【免费下载链接】qmMultiplayer agent harness for work.项目地址: https://gitcode.com/gh_mirrors/qm6/qm本文以 qm 仓库根目录下的 AGENTS.md 为骨架结合仓库源码、CLI 命令与部署文档系统解读这套面向 AI 编码时代的多智能体 Agent 项目Multiplayer agent harness for work运行于 Slack 与 Web所沉淀的开发纪律从提交归因、零注释标准、公共 helper 收敛到 fresh-context 强制评审、真实环境验证、Postgres 持久化原则与源码 fork 管理。读完本文你将掌握在一个由多种编码 Agent 协同维护、且自身就是 Agent 编排平台的仓库中如何写出不破坏系统整体性的代码变更。一、AGENTS.md 是什么一份给所有编码 Agent 看的仓库宪法qm 仓库根目录的 AGENTS.md 是一份面向代码协作者的工程规范文件其开篇直接点明运行与测试方法见 README.md正文聚焦于 Working on the code代码开发习惯这一核心议题。这份文件有一个非常特殊的工程细节值得注意CLAUDE.md是指向AGENTS.md的符号链接symlink文件末尾对此有明确说明——CLAUDE.mdis a symlink toAGENTS.md, so every tool (Claude Code, Codex, Cursor, …) reads the same guidance from this one file.也就是说无论你使用 Claude Code、Codex 还是 Cursor 打开该仓库读取到的都是同一份指导内容避免了多份规范文件漂移失同步。规范还预留了演进路径只有当某个工具确实需要差异化指引时才在引入该差异的提交中把 symlink 替换成真实文件。qm 项目本身是一个多人协作的 Agent 工作平台每位员工拥有独立隔离的 workspace同时可以在频道、群组消息和项目中与 Agent 协作每个 scope 都有自己独立的内存、文件、keychain、权限、cron、Web 应用和持久化沙箱。正因如此这份 AGENTS.md 的规范不是普通的团队章程而是一个持续被多个 AI 编码 Agent 消费、并且约束这些 Agent 产出质量的机器可读契约。文章后续章节将逐条拆解其核心条款并给出仓库内的源码与命令佐证。二、提交纪律拒绝 AI 署名尾注但保留真实人工合著AGENTS.md 提出的第一条硬性习惯是不要在提交或 PR 中附加 AI 作者归属省略针对 Codex、Claude 或其他 AI 工具的Co-authored-bytrailer省略工具生成的署名页脚如Generated with Codex但必须保留合法的人类合著者CI 会在新 PR 的 commit 上拒绝 AI coauthor trailer不要重写既有仓库历史来移除归属。这条规则背后的动机很实际AI 生成的 attribution 会污染提交历史元数据使其难以区分真实人工贡献与工具生成内容。qm 采取CI 拒绝新提交 不回溯改写历史的组合策略既守住了门槛又不破坏历史完整性。三、修复模式修复每一个实例而不是仅修复被报告的那一个规范第二条强调When you find a bug or a pattern worth changing, grep the whole repo (src/,plugins/,test/,scripts/) for the same pattern and fix all of it in the same change.一个被自动纠正的调用点旁边往往还有五个未处理的孪生兄弟——那是一次等待被重新发现的回归。因此修复必须按模式pattern在整个仓库范围内进行src/、plugins/、test/、scripts/四个目录都要用 grep 排查同款模式在同一变更中全部修复。这一条与第三条修复应当让系统更简单形成配套修复是删除或合并代码的机会而不是新增一层 flag 或特例的机会。如果某个修复扩大了系统的表面积就应该寻找一个能缩小它的版本。四、在所有路径都流经的层解决问题公共 helper 的收敛地这是 AGENTS.md 中技术含量最高的一条。规范要求在打补丁前先问自己修复是否属于共享 helper、store 接口或基础模块先查找现有 helper再决定是否新写一行。文档明确给出了 helper 的家helper homesHelper 位置职责src/util/errors.tserrMessage/swallow等错误处理工具src/util/async.tssleep、createKeyedQueue等异步工具src/util/sweeper.tsperiodic loops周期性清扫循环src/sandbox/process-poll.ts进程轮询 / 存活检测src/memory/notebook.ts内存行语法memory line grammar以 src/util/errors.ts 为例源码开篇即实现了errMessage(e)它会沿着cause链深度上限CAUSE_DEPTH 5逐层展开错误信息并去重同时引入reportBackendError来自 plugins/chassis/src/error-reporting.ts做后端错误上报——这正是所有路径都流经的共享层的典型实现任何调用点都不应重复发明错误展平逻辑。src/util/async.ts 中的createKeyedQueue()用MapK, Promisevoid为每个 key 串行化异步任务sleep(ms, { unref })支持unref避免阻塞进程退出src/util/sweeper.ts 的createSweeper(fn, defaultIntervalMs, opts)封装了setInterval周期循环并用pending集合跟踪在途任务、reportFailureAs统一上报失败。插件体系方面AGENTS.md 明确插件是独立包保留各自的本地副本而不是 import 核心代码唯一例外是共享的plugins/chassis包——它是插件 ↔ 核心管道的指定居所承载 source-auth 签名器、signed core-client、node:http 帮助函数、错误帮助函数以及CORE_*环境变量以相对路径被 import且绝不反向 import 核心。规范同时给出了反方向的约束不要为只有一个调用者的模式强行制造抽象。五、零注释标准以名称、结构与测试表达意图AGENTS.md 确立了一条相当激进的标准——仓库内零注释no explanatory comments or docblocks, TODO/FIXME notes, lint/type suppression directives, or commented-out code.意图通过命名、结构和测试来表达理由写入 commit message 或 PR 描述。解释器 shebang 被视为可执行指令而非注释不在此列。对 AI Agent 而言这条规则的深层含义是与其写注释解释这段代码在做什么不如把代码重构得让名称和结构自己说话并用测试固定行为。六、fresh-context 强制评审禁止自我评审评审者有最终发言权AGENTS.md 用大量篇幅定义了一套评审文化核心主张是禁止在产生 diff 的上下文中自我评审the context that produced a diff already believes it is correct, and that belief is the bias review exists to defeat.具体规则包括每次合并到main前必须由没有看你写这个变更的独立评审者/code-review或独立评审 Agent做一次 fresh-context pass任务是尝试破坏这个变更——寻找 bug、遗漏的边界情况、未言明的假设、会回归的东西绿色 CI 通过 ≠ 评审按 blast radius爆炸半径决定评审深度影响面窄的变更一次适度评审即可而核心控制流、认证与凭据、数据丢失或迁移、并发与重试逻辑、花费spend、公共 API 契约、所有路径都流经的共享 helper、或大到无法在脑中容纳的 diff则必须高强度评审并由多个不同视角的评审者参与判断 blast radius 要看调用者而不是数文件数——对拥有五十个 import 者的 helper 做一行修改绝不是小变更评审者而非作者对深度有最终发言权适度评审若发现超出其 scope 的风险应主动升级而不是守在自己的车道里评审发现的问题必须在合并前解决。这套设计的精髓在于把作者偏见视为系统性的评审盲区并用独立上下文 按风险缩放深度的机制对抗它。七、本地验证只跑受影响测试配合 typecheck 与 lintAGENTS.md 对验证策略的要求是本地只跑受影响的测试把全量套件交给 CI运行覆盖你改动内容的测试外加 typecheck 和 lint然后 push 让 CI 成为完整闸门理由CI 将测试套件分片shard到并行 runner 上本地串行复现全量套件需要数倍墙钟时间却提供相同信号受影响同样以调用者而非 diff 大小判断当无法判断一个变更触及什么时就在本地跑全部仓库根目录的 eslint.config.mjs 与 tsconfig.json 分别定义了 lint 与类型检查入口配合 package.json 中的脚本即可完成本地前置检查。八、真实环境验证dev-instance 与 Firefox 里的 Slack QA当单元测试不足以证明端到端行为时——例如新的或变更的 Agent 行为或任何触及 Slack/Web 界面、orchestrator、directory、cron 流程的改动——规范要求在打开 PR 前用/dev-instanceskill 启动本 worktree 的开发实例通过浏览器在配置好的 Slack 开发 workspace 上实际演练Slack QA 必须在Firefox中完成绝不使用 Slack Mac 应用不要先请求许可——自己动手不要等被要求纯重构、文档、配置、已被测试覆盖的纯逻辑变更可以跳过此步。仓库在 package.json 中提供了完整的 dev-instance 脚本矩阵npm run dev-instance:web # web/admin 界面 npm run dev-instance:slack # Slack 界面 npm run dev-instance:both # 同时测试两个界面 npm run dev-instance:no-slack # 不带 Slack npm run dev-instance:status # 查看实例状态 npm run dev-instance:down # 关闭实例 npm run dev-instance:doctor # 环境诊断README.md 补充说明裸npm run dev-instance默认面向 web对真实模型和真实 Postgres 演练分支还应设置DATABASE_URL与SESSION_STOREpostgres——否则会话只存在于进程内存中重启即消失详见后文持久化默认一节。scripts/dev-instance.sh 是这一切的入口脚本。九、前端改动必须演示live demo 优先截图兜底规范要求每个前端变更都在 PR 中提供可演示性凡操作者或用户能看到渲染效果的内容——admin/web/portal UI、Slack 界面、邮件——都必须随 PR 附带评审者无需启动环境即可查看结果的方式优先提供 live demo app 的链接例如内网发布的、对接小型 mock API 的已构建 UI让评审者可以点击真实界面并在 PR 中注明 mock 了什么仅在 live demo 不可行时如 Slack 界面、邮件退回到截图且必须展示变更后的状态对既有物件的改动需前后对照并基于真实数据渲染。十、部署仓库与源码 fork先git remote -v再决定行动AGENTS.md 专门开辟一节讲解 qm 的两种下游形态并要求动手前先跑git remote -v检查检出物origin指向yc-software/qm即表示 upstream仅凭另一个 origin 不能判定是源码 fork**包部署package deployment**拥有自己的qm.config.jsonc与固定的yc-software/qm依赖**源码 forksource fork**则携带 QM 源码树与 upstream 祖先历史。两种形态的差异决定了完全不同的定制与升级路径维度包部署源码 fork定制内容配置、工具、skills、服务不复制核心可自由修改核心运行时、插件、CLI、文档、CI上游贡献通过依赖升级可选私有部署材料部署仓库私有源码 fork 的deploy/layers/org/或独立私有仓库更新方式升级yc-software/qm依赖与 lockfile用update-qm合并上游变更源码 fork 的创建规范相当具体私有源码 fork 应创建为GitHub fork 网络之外的独立仓库只播种main分支并显式设置默认分支绝不用git push --mirror它会复制无关的上游分支与标签、让默认分支选择隐式化、并可能在后续推送时删除目标端专属引用用update-qm合并源码更新不 rebase 已发布历史、不丢弃有意的本地修改合并源码同步 PR 时保留其上游祖先不 squash、不 rebase包部署则直接更新依赖。README.md 给出了创建私有源码 fork 的完整命令序列gh repo create、git clone --single-branch --branch main --no-tags、remote 重命名为upstream等可作为实操模板。在下游仓库中操作时还有两条安全习惯每个gh命令都传--repo防止上游 remote 重定向操作从私有工作区贡献时使用upstream-pr准备干净分支并清理外发内容与历史。绝不在私有仓库的 PR、issue、评论或 commit message 中按编号引用上游 issue/PR——GitHub 的交叉引用会向上游泄露其存在与标题应改用纯文字描述。deploy/layers/README.md 进一步细化了组织层的创建方式node cli/bin/qm.ts init deploy/layers/org --org slug --target fly-or-awsqm init会生成部署配置、密钥名示例、沙箱与 provider 脚手架、运维 runbook以及一个把.env值与 Terraform state 挡在 Git 之外的按目录.gitignore根.gitignore作为兜底。层目录结构包含qm.config.jsonc提交、无密钥值、.env.example只含计算出的密钥名、sandbox/、plugins/name/、infra/、slack-app-manifest.yml与deployment.md完整契约见 docs/deploy-directory.md。铁律是deploy/layers/下的一切都不得进入上游 qm密钥在任何目录都不进入 Git——它们属于 provider 的加密密钥存储本地值只存在于被 gitignore 的.env。十一、持久化默认RAM 只配做缓存可读回的状态必须进 PostgresAGENTS.md 点明了一个反复出现的错误模式——把系统后续依赖的状态暂存在进程内存里The core runs blue-green and multi-instance — an in-memoryMapor ring buffer is per-instance and wiped by every deploy.qm 核心以蓝绿blue-green方式多实例运行内存中的Map或环形缓冲区是每个实例私有的每次部署都会被清空。因此任何操作者或系统稍后要读回的东西审计、日志、已解析配置、排队中或进行中的工作都必须落在持久化存储中绝不能只放在 RAM 里。RAM-only 只有在两种情况下可接受作为持久化存储前面的缓存真正的可丢弃、可重新推导的状态。规范给出的具体指令是如果新增日志、审计、队列或已解析配置用 Postgres 承载spec 的 contenteditable="false">【免费下载链接】qmMultiplayer agent harness for work.项目地址: https://gitcode.com/gh_mirrors/qm6/qm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考