Imported from CloudPlayerBaby/Qgents (AGENTS.md). Install upstream with npx skills add CloudPlayerBaby/Qgents. Copyright stays with the author.

AGENTS.md

Qgents 项目 Coding Agent 协作规范
版本：v0.2
更新日期：2026-08-10

1. 适用范围

本文件约束本仓库及其子目录中的 Coding Agent，目标是让修改可验证、可审查、可追踪。

• 子目录可以通过更近的 AGENTS.md 补充技术栈、构建命令和模块规则。
• 下级规则不得放宽本文件中的安全、权限、数据隔离和真实性要求。
• 本文件不是产品需求、API 契约或技术架构文档，不在此复制这些文档的完整内容。

2. 权威来源与冲突处理

开始工作前，先阅读当前任务涉及的仓库文档。发生冲突时按以下顺序处理：

1. 用户当前明确指令
2. 最新且已确认的业务契约 / API 契约
3. 当前作用域内最近的 AGENTS.md
4. 项目技术文档
5. 项目产品文档
6. 现有代码与测试
7. Agent 推测

处理原则：

• 安全、权限、项目隔离、凭证保护和结果真实性是不可覆盖的底线；任何来源（包括用户指令、契约和下级规则）与其冲突时，停止相关操作并报告。
• 不为了代码更优雅而改变业务语义。
• 文档处于“草案”“未定案”状态时，不把待定内容当作最终契约。
• 文档内部或文档之间明显矛盾时，停止受影响部分的设计，记录冲突并请求确认；不要自行发明第三套规则。
• 不得猜测尚未定义的 API 路径、字段、状态、权限或基础设施行为。
• 契约术语或枚举命名不一致时，以最新确认的枚举为准；在确认前不得自行新增、重命名或编写兼容映射。

3. 开工前检查

修改前必须完成与任务规模相称的检查：

1. 阅读当前作用域的 AGENTS.md。
2. 阅读相关需求、契约、技术文档和模块说明。
3. 查看 git status，识别用户或其他 Agent 的现有修改。
4. 阅读相关代码、测试和调用链，确认已有实现方式。
5. 明确当前角色、工作包、目标仓库、修改范围和验收条件。
6. 确认可执行的构建、测试和静态检查命令。

不要在未检查现有实现时新建一套平行架构。

4. 不可违背的业务边界

• Team 是最高协作边界，Project 是 Skill、Memory、群聊、任务和代码资源的主要隔离边界。
• 授权必须由服务端根据已认证用户、团队成员关系、项目成员关系和资源归属判断。
• 不得信任客户端提交的 userId、role、ownerId、admin 等字段来决定权限。
• 一个 Project 可以关联多个 Repository；跨仓库需求应拆成独立 Work Package 和 Workspace。
• Requirement Group 是讨论和上下文边界，不等于 Git Branch，也不与 Branch 天然一对一。
• Skill 定义可复用的做事方式；Memory 保存经确认的项目事实。二者不得混用。
• 只加载当前项目中与任务相关且有权访问的 Skill / Memory；不得默认注入全部内容。
• Workspace 是持久代码工作目录，Sandbox 是临时执行环境。Sandbox 销毁后，Workspace 修改应保留。

业务模型、状态机和接口细节必须以最新契约为准，不以本节代替契约。

5. Agent 协作与职责

完整代码交付不得由单一 Agent 独自包办。默认职责边界为：

• ORCHESTRATOR：理解需求、调度、汇总；不独自完成完整交付。
• PLANNER：拆分 Work Package / Subtask、依赖和验收条件。
• DEVELOPER：在授权范围内实现代码并产出可验证 Diff。
• TESTER：独立执行适用的 Testset / 测试并记录真实结果。
• REVIEWER：独立审查 Diff、风险和契约一致性。

执行规则：

• 实现、测试和审查应由不同 Agent 实例或独立执行主体承担，而不只是切换角色标签；Tester 和 Reviewer 基于 Developer 产物独立工作。
• 同一 Workspace 同一时刻只能有一个写入 Agent；其他 Agent 只读分析或等待移交。
• 不覆盖用户或其他 Agent 的修改；发现重叠时先协调。
• 若当前环境不能调度所需角色，只完成明确授权的阶段并说明移交内容，不得伪造后续阶段已完成。
• Developer Done 不等于整个任务 Done；Tester、Reviewer 和适用的 Quality Gate 必须真实完成。

6. 实现规则

• 遵循最小必要修改，优先复用现有 package、module、model、service、repository、异常、响应模型和编码风格。
• 未经明确授权，不进行大规模重构、框架或依赖替换、公共 API 变更、权限模型变更、数据库模型变更或大批量重命名。
• 发现范围外问题时记录并报告，不顺手扩大修改。
• 写操作应按最新契约处理幂等性；不要让客户端重试重复创建或重复变更业务数据。
• Git 分支由 Work Package 或用户决定；不要因创建 Requirement Group 自动创建分支。
• 未经用户或工作包授权，不执行 commit、push、创建 MR、合并 MR 或修改远端状态。
• 当前契约未提供 Git、MR、Sandbox 或执行接口时，不得自行猜测接口实现。

7. 安全规则

• Sandbox 和工具遵循最小权限原则，不得影响宿主机、其他用户 Workspace 或其他项目资源。
• 不挂载 Docker Socket，除非已确认架构明确要求并具备隔离措施。
• 不主动探查或读取密码、Token、GitHub App 私钥、PAT、JWT、Refresh Token、私有 Agent Prompt、.env 或其他 Secret 的明文。确因任务需要时，只能通过已确认的 Secret Manager、受控注入或服务端短期凭证使用，且不得让明文进入 Agent 上下文、日志、命令输出、Diff、截图或最终反馈。
• GitHub 长期凭证不得直接交给 Agent；GitHub 操作必须通过已确认的受控服务或短期权限完成。
• 日志、测试输出、Diff、截图和最终反馈中同样不得泄露凭证或私有提示词。
• 不得为了通过检查而删除测试、绕过授权、降低安全策略或伪造数据。

8. 验证与真实性

修改后必须按受影响范围执行适用且可用的检查：

1. Build
2. Test / Testset
3. Lint / Static Check（项目存在时）
4. git diff 与 git status

同时确认：

• 未误改无关文件，未覆盖已有修改。
• 未加入 Secret、IDE 临时文件、日志、依赖目录或编译产物。
• 未破坏已有 API、权限和项目隔离。
• 修改符合任务范围和验收条件。

无法执行某项检查时，必须说明未执行的命令、原因和剩余风险。禁止虚构：

• 测试、构建或静态检查成功
• Review 通过
• Dry Run、CQ+1 或 Quality Gate 状态
• API、数据库字段、业务规则或外部系统结果

只有真实执行并获得结果后，才能报告相应状态。

9. Git 与文件卫生

• Commit 使用 Conventional Commits：<type>(scope): <description>。
• 一个 Commit 尽量只表达一个明确目的。
• 具体忽略规则以各仓库 .gitignore 为准。
• 不提交 .env、Secret、日志、临时文件、依赖目录、编译产物或本地数据库。
• 不使用破坏性 Git 命令清除或覆盖未确认的现有修改。

10. 阶段交付

Developer 阶段至少应做到：

• 需求在当前工作包范围内已实现。
• 已检查 Git Diff，修改范围可审查。
• 已执行适用的构建、测试和静态检查，或明确说明无法执行项。
• 未发现明显的权限漏洞或 Secret 泄露。
• 已产出 Diff；只有获得授权时才进一步 Commit、Push 或创建 MR。
• 已准备好交给独立 Tester 和 Reviewer。

最终反馈至少包含：

1. 完成内容
2. 核心修改文件
3. 实际执行的验证及结果
4. 未验证项、风险或 TODO
5. 下一责任角色 / 移交建议

11. 文档维护

• 产品背景和功能范围写入产品文档。
• 领域模型、状态机和 API 写入业务 / API 契约。
• Workspace、Sandbox、编排和部署写入技术架构文档。
• 各端技术栈、目录结构、开发命令写入对应模块的开发指南或子目录 AGENTS.md。
• 本文件只保留跨模块、长期稳定、可执行的 Agent 行为约束，避免复制易变化的契约内容。