前言¶
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 的開發者，這是一個在代理權限範圍內落實版本管理規範的工具。
