agents-gitflow-guard

dsh plugin --profile web add agents-gitflow-guard

agents-gitflow-guard

有没有受够了 agent 跳过你的合入流程?

一个可自由配置分支角色的流程守卫，为主流 AI 编码 agent 平台而生——Claude Code、Codex、OpenCode、Antigravity、CodeBuddy、ZCode、Cursor、DeepSeek Harness (DSH)、Pi。

你自己定义分支——集成分支(feature 经 PR/MR 合入)、预览分支(环境终点)、生产分支、归档分支——每个角色各自配规则。常规流程违规在执行前就被拦截,并给出明确的原因与下一步;敏感合并始终留在你手上。存心的 agent 仍可绕过文本层守卫——见[诚实的边界](#它不能做什么诚实的边界)。

[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [许可证](LICENSE)


 

看它干活——30 秒真机演示

不碰你的项目文件,不留任何东西——一条命令在一次性沙箱仓库里跑三个真实场景(1 放行,2 拦截),退出即删。下面的动画由该命令的真实输出生成——与你 agent hook 调用的是同一守卫核心:

npx agents-gitflow-guard demo

看完之后想把守卫接到你的 agent 面前,继续看[快速开始](#快速开始30-秒用上)。

---

目录

• [看它干活——30 秒真机演示](#看它干活30-秒真机演示)
• [快速开始——30 秒用上](#快速开始30-秒用上)
• [为什么需要它——解决的问题](#为什么需要它解决的问题)
• [适合谁——场景与团队](#适合谁场景与团队)
• [它能做什么](#它能做什么)
• [它不能做什么——诚实的边界](#它不能做什么诚实的边界)
• [与服务器端分支保护的对比](#与服务器端分支保护的对比)
• [工作原理——三句话](#工作原理三句话)
• [配置参考](#配置参考)
• [门禁矩阵——拦什么、放什么](#门禁矩阵拦什么放什么)
• [人保持控制权的地方](#人保持控制权的地方)
• [安装详解](#安装详解)
• [常见疑问(FAQ)](#常见疑问faq)
• [术语表](#术语表)
• [路线图](#路线图)
• [开发](#开发)
• [赞助支持](#赞助支持)
• [许可证](#许可证)

---

快速开始——30 秒用上

第 1 步——安装。九个客户端全部使用同一个 npm 包 agents-gitflow-guard，按你的 agent 类型选择对应方式：

# 模式 A: CLI Hook 客户端 (Claude Code · Codex · OpenCode · Antigravity · CodeBuddy · ZCode · Cursor)
npm i -g agents-gitflow-guard

# 模式 B: DSH 进程内插件 (安装后重启 DSH，插件在进程启动时加载)
dsh plugin --profile web add agents-gitflow-guard

# 模式 C: Pi 进程内扩展
npm i -D agents-gitflow-guard

提示: 默认安装 npm 注册表上的最新版本。若镜像源缓存有延迟或需锁定版本，可指定版本号（如 npm i -g agents-gitflow-guard@<版本>）。DSH 专用 peer 依赖（@deepseek-ai/cordis / @deepseek-ai/dsh-tools）已声明为 optional —— 仅 DSH 进程内插件需要，由 DSH 运行时通过共享模块解析；CLI / Pi / OpenCode 用户不会被强制安装。

CLI Hook 客户端装完后执行一步接线（每个客户端一条命令，见第 2 步）；Pi 复制一个扩展文件；DSH 在插件添加后自动完成挂载。

第 2 步——接线(无需配置文件)。 守卫内置默认配置,开箱即用:默认保护 develop(integration)+ main(archive),零配置。你要做的只是让 AI 客户端去调用守卫——每个 stdin-hook 客户端一条命令(DSH 自动接线;Pi 拷文件,见下):

# Claude Code → 本仓库 .claude/settings.json
gitflow-guard wire --client claude --project --yes

# Codex / OpenCode / Antigravity / CodeBuddy / ZCode / Cursor(各写各的配置文件; --yes 跳过 y/N 确认)
gitflow-guard wire --client codex --project --yes
gitflow-guard wire --client opencode --project --yes
gitflow-guard wire --client antigravity --project --yes
gitflow-guard wire --client codebuddy --project --yes
gitflow-guard wire --client zcode --project --yes
gitflow-guard wire --client cursor --project --yes

# 只预览不写入 / 移除 / 交互向导:
gitflow-guard wire --client claude --dry-run
gitflow-guard wire --client claude --unwire
gitflow-guard setup

wire 对已有配置非破坏性合并(已存在的 hook 不动; 重跑 wire 会把旧版 gitflow-guard 条目原位迁移为当前自锚定形态),默认只写当前工程目录;--global(本机所有仓库)写入前必先确认或需 --yes。各客户端的文件与格式见[安装详解](#安装详解)。

⚠️ main 默认受保护。 trunk / 单分支工作流(所有人直推同一条分支)的用户,装完第一次直推 main 就会被拦——创建 gitflow-guard.config.json 写 { "enabled": false },或自行映射分支(见[配置参考](#配置参考))。gitflow-guard status 在默认配置生效时也会反复提示这一点。

第 3 步——验证。让 agent 执行 git push origin develop,预期工具调用被拒绝:

Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.

文案默认是英文(面向国际化)。要在你的项目里看中文,创建配置并加 "locale": "zh";中文效果是:已拦截: 受保护分支「develop」禁止直推 / 下一步: 集成分支(develop)由 PR/MR 合入 feature……(见[配置参考](#配置参考))。

完成。 守卫已用内置默认配置生效。想要更多关卡(preview / production)或改分支名?写一个 gitflow-guard.config.json,只写你在意的字段,其余保持内置默认。完整判定表见[门禁矩阵](#门禁矩阵拦什么放什么)。

完整实战示例——一个 feature 的端到端旅程

场景:团队开发登录页(feature/login-page);develop 是集成分支,main 是归档分支。每一步 agent 做什么、插件判定什么、你看到什么:

# · agent 执行 · 插件判定 · 你看到

1 · git checkout -b feature/login-page(从 develop 切) · ✅ 放行(feature 自由) · 分支已建

2 · git add . && git commit -m "feat: login" · ✅ 放行 · 已提交

3 · git push -u origin feature/login-page · ✅ 放行(推 feature 没问题) · 已推送

4 · git checkout develop && git merge feature/login-page · 🚫 拦截——集成分支只收 PR/MR · 必须对 develop 开 PR/MR

5 · gh pr create --base develop · ✅ 放行(feature → 集成) · PR 已建,由你审查并合并

6 · git push origin main 或合入 main · 🚫 拦截——归档仅用户亲手 · 发布后由你亲自 develop → main 归档

注意 agent 做不到的事:把 feature 直接合进 develop,或碰 main 一下都不行。每个敏感合并都是你在 PR/MR 页面或自己终端里的有意识动作。

---

为什么需要它——解决的问题

AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智能体指令文件(AGENTS.md、CLAUDE.md、GEMINI.md、.cursorrules 等各家命名)和项目文档被"告知"遵循合入流程:feature 分支开发 → 合入集成分支(以及你有的话各 preview/production 阶段)→ 生产/归档交给你。

这是软规则。 Agent 会跳过、重排、干脆"忘记"它——不是因为恶意,而是因为软指令对模型来说本来就是可选的。

这个插件给软规则配上机械执行的闸门。agent 每次尝试的 git 操作都会对照本地仓库的真实状态检查;常规违规在命令执行前就被拦截,并给出原因和下一步。

没人需要记得规则——守卫机械地把关。文本层本质是尽力而为:存心的 agent 能做什么,见[诚实的边界](#它不能做什么诚实的边界)。

---

适合谁——场景与团队

这些信号说明它适合你

• 你有(或想要)一个明确的分支流程——从单条 develop 式集成分支,一直到多级 preview/production 流水线。
• agent 已经抄过近路:直推受保护分支,或合到不该合的地方。发生过一次就会再发生——这个插件是结构性修正。
• 你想保护集成

…(truncated)