前言¶
AI 编码代理（如 Claude Code、DeepSeek Harness、Cursor 等）在自动化开发过程中，有时会绕过团队既定的 GitFlow 工作流，直接将代码合并到集成分支或生产分支，导致版本管理混乱。AgentsGitFlowController 旨在为这些 AI 代理提供一套可配置的分支角色守卫机制，强制其遵循标准流程。
插件介绍¶
名称: AgentsGitFlowController (agents-gitflow-guard)
核心定位: Agents Client Level Git Flow Controller
维护者: FeatureAgents
分类: 工作流
许可: MIT
核心功能¶
该插件提供以下能力：
1. 分支角色守卫：为 AI 编码代理定义不同的分支角色，包括 integration（集成）、preview（预览）、production（生产）和 archive（归档）。
2. 多客户端支持：支持 Claude Code、DeepSeek Harness (DSH)、Cursor、Codex、OpenCode、Antigravity、Pi、CodeBuddy 和 ZCode。
3. 流程强制：防止代理跳过 GitFlow 流程，例如禁止直接合并到集成分支。
4. 敏感操作控制：限制敏感合并操作，确保这些操作必须由人工介入控制。
安装与启用¶
在 DeepSeek Harness 中安装该插件，使用以下命令：
dsh plugin --profile web add agents-gitflow-guard
插件安装后，会自动挂载到 DSH 进程中。DSH 的 peer 依赖（@deepseek-ai/cordis 和 @deepseek-ai/dsh-tools）是可选的，DSH 会在运行时通过共享配置模块提供这些依赖，无需手动安装。
典型用法¶
安装完成后，可以通过配置 hook 来启用守卫。
- 配置 Hook：
使用wire命令将守卫接入客户端。例如，为 Claude Code 配置：
gitflow-guard wire --client claude --project --yes
-
操作拦截示例：
当代理尝试直接推送到受保护的develop分支时，操作会被拦截：- 被拦截的操作：
git push origin develop
*结果：操作被拒绝，提示必须通过 PR/MR 合入集成分支。*
* **允许的操作**：
gh pr create --base develop
*结果：操作被允许，通过 PR 合入流程。*
注意事项¶
- 默认保护：
main分支默认处于受保护状态。对于 Trunk 或单分支开发模式的用户，如果直接推送到main，操作会被拦截。需要通过配置文件（gitflow-guard.config.json）禁用或自定义分支映射。 - 内置配置：插件内置默认配置，保护
develop（集成）和main（归档）分支。 - 依赖说明：对于使用 CLI、Pi 或 OpenCode 的用户，不需要强制安装 peer 依赖，插件会自动处理兼容性。
结语¶
AgentsGitFlowController 通过在客户端层面定义分支规则，有效解决了 AI 代理在开发过程中破坏 GitFlow 规范的问题。对于使用 DeepSeek Harness 的开发者，这是一个在代理权限范围内落实版本管理规范的工具。
