AgentsGitFlowController

September 1, 2026 · View on GitHub

本文件是项目唯一的智能体规范，遵循 AGENTS.md 标准，Codex / OpenCode / Claude Code / Gemini 等工具均可读取。

1. 语言规范

  • 沟通交流：使用中文，专业且简洁。
  • 代码逻辑：
    • 变量名 / 方法名 / 类名 / 包名：英文。
    • 代码注释：中文。
    • 日志 / 异常信息：英文。

2. 常用命令

  • 构建：npm run build(tsdown → lib/; 代码改动后重新构建)
  • 测试：npm test(vitest, 全绿才算完成)
  • 类型检查：npm run typecheck(tsc --noEmit, 0 Error 才算完成)
  • 本地调试与安装：
    • CLI Hook 客户端（Claude Code / Codex / OpenCode / Antigravity / CodeBuddy / ZCode / Cursor）：npm link 后 gitflow-guard wire --client <client> --project --yes
    • DSH 进程内插件：node scripts/install-dsh.mjs [profile]（本机无 DSH 时跳过，装完需重启 DSH）
    • Pi 进程内扩展：npm link 或将 pi/gitflow-guard.ts 复制到目标仓库 .pi/extensions/
  • 发布(全自动化)：bump 叠加在待合并的内容 PR 分支上(npm version patch, 版本提交落在该分支; feature 前缀是必须的——集成 PR 的 head 必须是 feature 角色)→ 用户在 GitHub 合并该 PR(内容+changelog+版本号一次带进 develop)→ CI 自动检测新版本 → 全量矩阵校验 → 自动在 develop 最新 commit 打 annotated tag 并推送 → 自动 npm publish 与创建 GitHub Release —— 零本地命令发布: 无需在本地手动打 tag 或推送, CI 自动闭环发版 —— 仅当内容已合入后的纯补发(如版本同步)才开独立 feature/release-<版本> PR —— 本地 develop 永不直接变更(§4); develop 的一切演进只经 GitHub 的 PR 合并产生 —— CI 自动: 校验 package.json 与 CHANGELOG → 完整矩阵测试 → 自动打 tag → npm publish (--provenance) → GitHub Release (带 CHANGELOG 提取说明) —— 前提: GitHub 仓库 Secrets 已配 NPM_TOKEN(Publish 类型 access token)

3. 目录结构

AgentsGitFlowController/
├── AGENTS.md            # 唯一的智能体规范（本文件）
├── gitflow-guard.config.json # 仓库级 GitFlow 守卫配置（dogfood）
├── patch.yml            # DSH 插件挂载描述
├── .gitignore           # 忽略本机与系统文件
├── .github/workflows/   # CI (ci.yml) 与全自动发布 (release.yml) 工作流
├── .agents/             # Antigravity 智能体扩展（自建 agents / hooks / skills）
│   ├── agents/          # 自建子智能体（architect、unit-testcase、e2e-tester 等 12 个，见 4. 工作流约定）
│   ├── hooks/           # 自建 hook 脚本与参考文档
│   └── skills/          # 自建 skill 工作流（start-work、design-sync、readme-sync 等）
├── .claude/             # Claude Code dogfood 配置（settings.json / agents）
├── .codex/              # Codex dogfood 配置（hooks.json）
├── .codebuddy/          # CodeBuddy dogfood 配置（settings.json）
├── .zcode/              # ZCode dogfood 配置（config.json）
├── .cursor/             # Cursor dogfood 配置（hooks.json）
├── .opencode/           # OpenCode dogfood 配置（plugins/）
├── .pi/                 # Pi dogfood 配置（settings.json / extensions/）

├── src/                 # 核心源码（门禁、命令分类、平台协议、CLI、wire 脚手架、Pi 扩展等）
├── tests/               # 单元测试、集成测试与准确率审计语料
├── scripts/             # 构建、矩阵校验、版本检查、发版与 E2E 脚本
├── bin/                 # CLI 二进制入口（gitflow-guard.mjs）
├── lib/                 # 构建产物（tsdown 输出）
├── docs/                # 设计文档、E2E 测试用例与博客文章
├── pi/                  # 随 npm 包分发的 Pi 扩展入口（pi/gitflow-guard.ts）
└── opencode/            # 随 npm 包分发的 OpenCode 插件入口（opencode/gitflow-guard.ts）

4. 工作流约定

默认开发流水线：

需求拆解 (architect) 
→ 测试用例设计 (unit-testcase / e2e-testcase) 
→ 代码实现 (coder) 
→ 测试执行与绿化 (unit-tester / e2e-tester) 
→ 综合审查门禁 (code-reviewer / security-checker / test-reviewer) 
→ 文档同步 (doc-writer)
  • 开工第零步（基线先行）：任何内容工作动手前，先加载并执行项目技能 .agents/skills/start-work/SKILL.md——git fetch 核对基线、从 origin/develop 派生工作分支后再动文件；发现工作区停在陈旧检出（main 或其他）时，stash 存档后在新分支上重放，禁止就地编辑或携带提交。
  • 细分 TDD 循环迭代：
    1. 用例设计（红）：由 unit-testcase 编写最小可复现失败单测，涉及跨边界/真实平台交互时由 e2e-testcase 定义端到端场景。
    2. 代码实现（绿）：由 coder 编写最小生产代码，由 unit-tester 运行并修复单测直至全绿。
    3. E2E 固证：由 e2e-tester 在隔离沙箱中执行真实 E2E 验证并记录物理证据（docs/e2e/TestResult/）。
  • 合并前审查门禁（三审闭环）：审查环节须按项目技能 .agents/skills/dev-loop/SKILL.md 的 loop 协议执行。收尾前必须由以下审查角色完成审查且均输出无 [問題] 项：
    • code-reviewer：审查代码正确性、规范与架构完整性。
    • security-checker：审查高危命令、Shell 注入、权限控制及安全边界。
    • test-reviewer：审查断言有效性、覆盖率真实性与 Mock 克制性。 任一审查含 [問題] 项须回退对应实现/测试端修复并重审，不得带未解决 [問題] 项进入收尾（bump / CHANGELOG / 开 PR）。
  • 本仓库自身开发也走 GitFlow：feature/<主题> 分支开发 → 测试/矩阵全绿 → PR 到 develop【经用户确认合并】; 禁止直接 commit/push develop。develop 只承载集成、发版 tag 与归档 PR 的源——这与插件对 develop=integration (update=pr) 的约束一致，规矩靠纪律执行，不靠插件兜底。
  • 本地 develop 零变更：禁止对本地 develop 做任何变更操作(commit / amend / reset / cherry-pick / npm version / 打 tag / 拉取合并等一律不做)。develop 的一切演进只经 GitHub 的 PR 合并与用户推送产生; 需要基于 develop 的动作一律从 origin/develop 派生工作分支(如 feature/release-<版本>)。
  • 一分支一 PR, 合并即弃: PR 合并(或关闭)后立即删除分支(远端+本地); 后续任何工作一律从最新 origin/develop 重新切分支。禁止在已合并过的分支上继续追加提交——rebase 式合并会改写 SHA, 复用旧分支会形成两份平行履历, 下一次 PR 必然出现大面积假冲突(0.0.13 第三轮整改实证)。
  • 提交前清单与确认（pre-commit-review）：任何 git add / commit / push / PR 创建前，先执行项目技能 .agents/skills/pre-commit-review/SKILL.md——逐文件列提交清单（新增/修改、公开进 PR 还是私有留本地、纳入/排除原因），经用户明确确认后才可暂存与提交；禁止 git add -A 整体暂存，暂存一律显式列文件路径。
  • 提交规范：Conventional Commits（feat / fix / docs / style / refactor / test / chore）；PR 标题与正文一律英文。
  • CHANGELOG 随功能同一 PR 写入, 标题仅用版本号、不写日期(发布时间由 git tag / GitHub Release 承载), 发布 bump 时一次到位; 禁止发版后再为本次版本单独开修正 PR。
  • 多语言文档绝对对等（多语种平等守卫）：修改或更新任何面向用户的说明、门禁规则、配置项或 CLI 功能时，必须执行 .agents/skills/readme-sync/SKILL.md，确保全部 11 种语言 README（README.md、README.zh.md、README.zh-tw.md、README.ja.md、README.ko.md、README.de.md、README.fr.md、README.es.md、README.it.md、README.pt.md、README.ru.md）保持 100% 结构对称与完整对齐（44 标题、7 表格、24 代码块、17 TOC 锚点），禁止出现摘要与全量不对等的现象；并通过 npm run check:readmes 机械拦截校验。
  • 特定场景智能体：
    • 遇到设计稿 / 报错截图 / 架构图等图片时，插入 vision 识别。
    • 小型改动或无需拆分单测/E2E细分流程时，可选用综合 tester 驱动。

5. 行为准则

  • 不确定性确认：需求有歧义时先提问，不盲目假设。
  • 原子化修改：每次修改集中一个功能点，避免无关的大改动。
  • 最小改动：不做超前设计，不为假想需求添加功能。
  • 客观表达：只陈述事实与判断，不带情感色彩（奉承、感叹、夸张）。
  • 敢于反对：不迎合用户意见，发现方案确实不合适时明确指出并说明理由。
  • 禁止 AI 署名：commit / PR 一律不得出现 Co-Authored-By: Claude、Generated with Claude Code 等 AI 署名或生成声明；提交只署项目用户身份。
  • 禁止删除根目录：rm -rf /、rm -rf /* 等针对根目录的删除绝对禁止，无例外。
  • 主目录删除须确认：rm -rf ~、rm -rf ~/* 等删除主目录内容的操作，须先用明确告警说明影响范围，获用户明确确认后方可执行。

6. 测试规范

  • 断言必须验证行为：禁止只验证「不抛异常」的空转测试。
  • 覆盖率真实：追求行为覆盖而非行数，禁止为凑覆盖率修改生产代码。
  • Mock 克制：领域逻辑用真实输入输出验证，仅外部边界（数据库、网络、文件）用 Mock 隔离。

7. 陷阱记录

  • macOS 下 /tmp 是 /private/tmp 的符号链接;Windows 下临时目录可能是 8.3 短名(RUNNER~1 → runneradmin):测试建临时仓库须以 git rev-parse --show-toplevel 的权威规范化路径为准, 否则断言失败。
  • vitest 会接管 stdout,console.log 不走 process.stdout:测试捕获输出须拦截 console.log。
  • npm 7+ 默认自动安装 peerDependencies; 本仓库仍将 DSH 类型包(@deepseek-ai/dsh-session 等)显式声明为 devDependencies, 保证类型面完整与锁文件可复现。
  • { ...DEFAULT_CONFIG } 浅拷贝会共享嵌套对象,合并时修改会污染模块级默认值:必须深拷贝。
  • DSH 插件包须在 package.json 声明 dsh.bundle.patch(dsh plugin add 才会自动挂载为 profile 层)。
  • 本仓库 dogfood:gitflow-guard.config.json 已启用,develop 为集成分支 / main 为归档分支;合入 develop 须经用户确认;main 仅用户亲手归档。
  • 会话工作区可能停在任意陈旧检出（实证：停在 0.0.6 时代的 main 而 develop 已到 0.0.13）：内容工作动手前必跑 start-work 技能核对基线；旧基线上产生的未提交改动 stash 存档后到新分支重放，禁止就地编辑或携带提交——否则开 PR 轻则大面积真冲突，重则无冲突却静默回退已合入功能。

8. 客户端支持清单(新增 agent 平台时必须逐项同步)

每次给守卫新增一个客户端接入(已有 DSH / Claude Code / Codex / OpenCode / Antigravity / Pi / CodeBuddy / ZCode / Cursor 等),按以下清单逐项同步,最后 npm run verify:matrix 全绿才算完成。漏一项就是隐性半成品。 例外: GitHub Copilot 不在本插件接入范围 —— 其原生 allow/deny/ask 权限 + rules 已覆盖守卫场景; 官方另有 hooks 系统可由用户自行接入(官方文档见 README)。本插件不为它造半个 hook,也不声称支持该平台。 例外: DSH 走进程内插件协议, 不经 stdin-hook 通道 —— 本清单第 1/3/4 条(stdin payload 形状、hook 注册配置、stdin 参考文档)对 DSH 不适用: 其挂载物是 patch.yml + dsh.bundle.patch(package.json "dsh": {"bundle": {"patch": "./patch.yml"}}), 拦截由 src/index.ts 的 apply() 监听 tools/pre-execute、以返回值 {kind:'deny', reason} 表达(stdin payload / exit code 协议对其无意义), 协议记载见 .agents/hooks/references/dsh.md。其余平台按全清单逐项执行。 例外: Pi 走进程内扩展协议, 不经 stdin-hook 通道 —— 清单第 1/2/3/4 条对 Pi 按此形态执行: 协议层= src/pi.ts 的 createPiExtension() + tests/pi.spec.ts(监听官方 tool_call 事件, 拒绝以返回值 {block:true, reason} 表达, 非 stdin/exit code); CLI --platform 透传不适用(守卫 CLI 仅作内部子进程, --platform claude 只是进程间 deny 编码选择); 仓库级 hook 配置= .pi/settings.json + .pi/extensions/gitflow-guard.ts(随包发布 pi/gitflow-guard.ts 供复制); 参考文档= .agents/hooks/references/pi.md(对齐官方 pi.dev/docs/extensions)。第 5/6/7/8 条与其他平台同款执行。

  1. 协议层 src/platform.ts + tests/platform.spec.ts:
    • detectPlatform: 加该平台 payload 判别字段;extractHookPayload: 加 stdin 形状;encodeDeny: 加拦截协议(exit 码 / stdout JSON 形状)。
    • HookPlatform 联合类型加成员;补三者的单测分支。
  2. CLI: gitflow-guard check --platform <name> 可走通(cli.ts 透传 --platform, 无需特判)。
  3. 仓库级 hook 配置(dogfood): 新增与 .claude/settings.json、.codex/hooks.json 同款的项目配置。
  4. 仓库内参考文档: .agents/hooks/references/<tool>.md 存在且与官方协议一致, 缺失则补。
  5. 连续复测矩阵: scripts/verify-matrix.mjs 新增该平台「真实 payload 拦截 + 放行」用例, 断言 wire 格式(exit/JSON 字段)。
  6. README 双语: 安装/使用段补该平台配置示例;开头宣传语 "for AI coding agents — DSH, Claude Code, and Codex" 追加上新客户端名。
  7. package.json: description 的客户端清单追加;keywords 补搜索词。
  8. CHANGELOG: 记一条 feat。
  9. QA 三连: npm run typecheck(0 错) + npm test(全绿) + npm run verify:matrix(全绿)。