开发链路治理栈（agent-governance-toolkit + code-review-graph + herdr） 已实测

场景

你在用 Agent 写代码，但越来越担心三件事：Agent 会不会执行了不该执行的操作（比如乱删文件、乱改配置）？改动的影响面到底有多大、有没有波及到不该碰的模块？Agent 的会话和工作区状态有没有失控？这三个担心对应三条不同的能力，单装一个都管不全。

本组合包把「写码前挡违规 → 写码后建图 → 跑起来管会话」串成一条治理链路：agent-governance-toolkit（agt） 做策略门禁（违规操作先挡下）、code-review-graph（crg） 建代码关联图（审查时看清影响面）、herdr 监督会话与工作区。三件套已实测共装兼容（3/3 对子 verified），装完即得一条带门禁的 Agent 开发流水线。

组合成员 （3）

pip install agent-governance-toolkit --index-url https://pypi.tuna.tsinghua.edu.cn/simple
agt --version   # 预期输出: agt, version 4.1.0

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph==2.3.8
code-review-graph --version   # 预期输出: code-review-graph 2.3.8

curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr && ./herdr --version   # 预期输出: herdr 0.8.2

方案总览

备选方案：只要「管住 Agent 别乱来」→ 只装 agt 就够；只看影响面 → 只装 crg；只监督会话 → 只装 herdr。三件一起装不打架（CLI 面写面互不重叠，实测）。

安装顺序逻辑：先门禁（agt，纯 CLI 先就位）→ 再图谱（crg，同 venv 共装实测兼容）→ 最后重件（herdr 独立二进制，放最后避免后台干扰前面安装）。

快速开始

一键脚本由本文档自动生成（渲染后位于 pages/combos/combo-governance-stack.sh），逐条执行：

bash pages/combos/combo-governance-stack.sh

• 装完你会得到：agt / crg / herdr 三个命令全部可用，开发链路的「门禁 + 图谱 + 监督」三件套就位。
• 预计耗时：5-10 分钟（pip 两件 + herdr 二进制下载，herdr 下载是国内网络最容易卡的一步，脚本已内置 gh-proxy）。
• 前置条件：Python >= 3.10（agt/crg）；Linux x86_64（herdr 二进制，macOS/Windows 资产见 release 页）。

想弄明白每一步在干什么、装错了怎么恢复 → 看「逐步教学」。一键脚本出问题 → 按逐步教学手动执行定位。

逐步教学

第 1 步：装 agent-governance-toolkit（策略门禁，最先就位）

agt 是这条链路的「门」。它做策略与合规检查：在 Agent 执行动作前用 agt lint-policy 一类命令校验策略是否被遵守，违规先挡下。它是个纯 CLI 的 meta 包，安装只往 Python 环境里装包，不碰系统配置、不起后台进程——所以放第一步，装完后续每一步都在门禁视野内。

pip install agent-governance-toolkit --index-url https://pypi.tuna.tsinghua.edu.cn/simple
agt --version   # 预期输出: agt, version 4.1.0

预期输出: agt, version 4.1.0

装好确认：

• agt --version 输出版本号 4.1.0；
• 裸跑 agt --help 能看到子命令列表（lint-policy 等）。

卡住怎么办：

• pip 超时（直连 PyPI 慢）→ 命令已带清华镜像参数；仍失败可换 -i https://mirrors.aliyun.com/pypi/simple。
• 命令找不到（装进了别的 Python 环境）→ 确认 pip 与 python 同环境：python3 -m pip install ... 后用 python3 -m agt --version。

第 2 步：装 code-review-graph（代码关联图谱）

crg 把代码库构建成关联图：crg build 在工作区生成 .code-review-graph/ 图数据，审查时能看清一个改动影响哪些文件。它与 agt 同 venv 共装已实测兼容。关键提醒：不要执行 crg install 子命令——它会向 Claude/Codex/Cursor 注册 MCP/hooks（写 ~/.claude.json 等），本组合只用 CLI 面（build/status），避免注册面写入。

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph==2.3.8
code-review-graph --version   # 预期输出: code-review-graph 2.3.8

预期输出: code-review-graph 2.3.8

装好确认：

• code-review-graph --version 输出版本号 2.3.8；
• 在工作区跑 code-review-graph build（首次建图，成功会在 .code-review-graph/ 下生成数据）。

卡住怎么办：

• pip 装不上（依赖多）→ 建议用隔离 venv：python3 -m venv ~/.venvs/dev && source ~/.venvs/dev/bin/activate 再装。
• build 报错（非 git 仓库/无语言配置）→ crg 建图依赖仓库结构，先确认在 git 仓库根目录跑。

第 3 步：装 herdr（会话与工作区监督）

herdr 管「运行时」：查看会话状态、检查工作区配置。它是单二进制（Linux x86_64），下载即用，无运行时依赖。herdr status / herdr config check 只读不拉起后台 server（实测）。国内网络这一步最容易卡——GitHub 直连慢，命令已内置 gh-proxy 前缀。

curl -sL -o herdr https://gh-proxy.com/https://github.com/herdrdev/herdr/releases/download/v0.8.2/herdr-linux-x86_64
chmod +x herdr && ./herdr --version   # 预期输出: herdr 0.8.2

预期输出: herdr 0.8.2

装好确认：

• ./herdr --version 输出版本号 0.8.2；
• ./herdr status exit 0（只读检查，不拉起 server）。

卡住怎么办：

• 下载超时（gh-proxy 也不通）→ 换网络窗口（代理/流量）重试，或手动浏览器下载同 URL 再放到本地。
• Permission denied → 确认 chmod +x herdr 已执行；二进制路径建议移入 ~/.local/bin/ 并加入 PATH。

装完验收（一步到位）

作用：装完跑下面一条命令块，全绿 = 本组合包就绪；某条失败 → 回「逐步教学」对应步骤定位。

agt --version
code-review-graph --version
herdr --version

预期输出: agt, version 4.1.0；code-review-graph 2.3.8；herdr 0.8.2。三件套全绿 = 治理栈命令面就位

注：成员级命令已实测；组合包级串跑待补验。

日常使用

启动与入口

• agt：无服务无后台，直接命令行 agt <子命令>（如 agt lint-policy <策略文件>）。
• crg：code-review-graph build（建图）→ code-review-graph status（看图状态）。
• herdr：./herdr status（会话状态）/ ./herdr config check（配置检查）；完整客户端模式会拉起 server（按需使用）。

常用操作

1. 写码前把关：agt lint-policy <策略> 校验 Agent 要执行的动作是否符合策略。
2. 审查前建图：code-review-graph build 更新关联图，status 看最近构建。
3. 会话监督：./herdr status 查看当前会话/工作区状态。
4. 组合冒烟（装完跑一遍确认三件共存正常）：agt --version && code-review-graph --version && ./herdr --version。

数据与目录

• crg：工作区 .code-review-graph/（图数据，建议加入 .gitignore）。
• herdr：完整客户端写 ~/.config/herdr/ + ~/.local/state/herdr/（CLI 只读面不写）。
• agt：CLI 面无配置目录写入。

卸载与清理

按安装相反顺序卸载：

# 1. herdr（二进制 + 配置）
rm -f ~/.local/bin/herdr herdr
rm -rf ~/.config/herdr ~/.local/state/herdr
# 2. crg + agt（同 venv 卸载）
pip uninstall -y code-review-graph agent-governance-toolkit
# 3. 清理工作区图数据
rm -rf .code-review-graph

提示：.code-review-graph/ 是图数据，删了下次 build 重建即可，不影响源码。

安装顺序

1. 先 agt（pip，纯 CLI，无后台进程）——策略门禁最先就位，后续安装动作都在门禁视野内。
2. 再 crg（pip，纯 CLI）——与 agt 同 venv 共装实测兼容；不要执行 crg install 注册子命令（避免写 ~/.claude.json 等注册面）。
3. 最后 herdr（独立二进制）——重件放最后，避免前面安装被其后台 server 干扰；status/config check 不拉起 server（实测）。

依赖警告

• 冲突：agt×crg compatible（verified 2026-08-28，组合包实测 001，CLI 面）；agt×herdr compatible（verified）；crg×herdr compatible（verified）——3/3 对子 verified，出处：站内文档 + 实测记录（本地留存）。未实测面：三者的 Claude Code 插件/MCP 注册形态（本机 Claude 未登录），保持矩阵 possible-conflict/possible-compatible 推断态。
• 版本：agt [4.1.0,4.1.0]；crg [2.3.8,2.3.8]（Python >= 3.10）；herdr [0.8.2,0.8.2]（Linux x86_64）。
• 环境：crg build 写工作区 .code-review-graph/；herdr 完整客户端写 ~/.config/herdr/ + ~/.local/state/herdr/ 且可能拉起后台 server（端口按需，与其它条目无固定端口冲突，推断）；agt CLI 面无配置目录写入。
• 国内网络：pip 两件走清华镜像（PyPI 直连超时）；herdr 二进制走 gh-proxy（GitHub 直连慢）。最容易卡的一步 = herdr 二进制下载，命令已内置 gh-proxy。

FAQ

1. 三个都装会不会打架？ → 不会。CLI 面写面互不重叠，3/3 对子已实测 verified（隔离 HOME + 独立 venv 共装冒烟全过，证据 实测记录（本地留存））。
2. herdr 会不会偷偷起后台进程？ → herdr status / config check 只读不拉起 server（实测）；完整客户端模式才按需起 server。
3. 要不要执行 crg install 注册到 Claude Code？ → 本组合不需要。install 子命令会写 ~/.claude.json 等注册面，只用 CLI 面（build/status）即可，避免与其它工具注册面冲突。
4. herdr 下载不下来怎么办？ → 命令已内置 gh-proxy；还不行就换网络窗口，或手动下载同 URL 后放到 ~/.local/bin/。

验证证据

每份组合包在隔离环境实测（冒烟 + 写面检查），未实测项在文中如实标注；实测日期见下方验证证据。

验证于 2026-08-29 · TTL 到期 2027-02-25（180 天）

本站实测记录（2026-08-28）

• 实测记录（本地留存）（含混用日志）；矩阵对子状态见 站内文档。
• 未实测（如实标注）：Claude Code 插件/MCP 注册形态共装（本机未登录）；herdr 完整客户端 server 模式。

关联问题

• agent-toolchain-coexist
• function-calling-guard
• execpolicy-restricted