agent-governance-toolkit

你会遇到什么

多个 AI 会话（或一个团队的多位协作者）在同一个环境里干活时，谁来约束它们？跑命令前没人检查、提 PR 前没人过合规，出了事才追责。agent-governance-toolkit（CLI 名 agt）就是这道「门」：策略执行、合规验证（OWASP ASI）、零信任身份与执行沙箱，让 Agent 的动作在发生前先过一遍检查。它是个 pip meta 包——装一个主包带一组治理子包，装完用 agt doctor 体检、agt lint-policy 查策略文件格式、agt verify 跑合规。 什么时候用：

• 你有多会话 / 多 Agent 协作，想统一「什么能做什么不能做」的规则；
• 你要在提 PR、跑命令这类动作前加一道合规检查；
• 你想给 Agent 环境做一次体检（agt doctor）和策略文件检查（agt lint-policy）。

什么时候别用：单机、单会话、随手写脚本的场景——治理层本身就是开销，没有多主体协作就不需要门禁。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

agt 是一个 pip meta 包——装一个主包，会带上一组治理子包（agent-os-kernel / agentmesh-platform / agent-runtime / agent-sre 等）。核心是一个 CLI（agt），子命令覆盖：verify（合规验证）、doctor（健康诊断）、lint-policy（策略文件检查）、test、integrity、red-team、cred（零信任身份）。 三种安装形态（能力从少到多）：

• 方式 A：pip 装主包，只用 CLI 面（本环境实测）；
• 方式 B：pip 装 [full] extras 全家桶，能力全开（未实测）；
• 方式 C：Claude Code 插件市场安装，进 IDE 插件面（未实测，依赖 Claude Code 登录）。

装完它动哪里：CLI 形态不写用户配置（实测无 ~/.claude.json 写入）；只有方式 C 插件形态会写 ~/.claude.json 的插件注册面。

一步步来

第 1 步：装主包

讲解：agent-governance-toolkit 在 PyPI 上是个 meta 包，pip 安装会把 CLI 与基础依赖一起装好，不碰系统配置、不起后台进程，所以是最省事、最好卸载的路径。国内网络实测 PyPI 官方约 12.7s、清华镜像约 16s，量级相当；如果你在校园网/代理切换环境，两个分支都试一下，哪个通就用哪个。

pip install agent-governance-toolkit
agt --version

预期输出: agt, version 4.1.0

国内加速分支（与上方二选一，命令等效）：

pip install agent-governance-toolkit --index-url https://pypi.tuna.tsinghua.edu.cn/simple
agt --version

预期输出: agt, version 4.1.0

装好确认：

• agt --version 输出 agt, version 4.1.0；
• agt --help 能看到子命令清单（verify/doctor/lint-policy/test/integrity/red-team/cred）。

卡住怎么办：

• agt 命令找不到 → 检查 Python 版本 ≥ 3.10，并确认 pip 与 python 同环境（venv 场景先激活 venv 再装再用）；
• pip 超时 → 用上面国内分支命令（--index-url https://pypi.tuna.tsinghua.edu.cn/simple）；
• 装完提示缺依赖 → 优先重装主包而不是逐个补（meta 包会声明完整依赖集）。

第 2 步：体检 + 跑通第一个治理动作

讲解：装好先做两件事——agt doctor 看安装是否完整；然后建一个策略目录（项目根下 policies/，放你的策略文件），用 agt lint-policy 检查策略文件格式。这是治理闭环的第一步：先有「检查策略」的能力，后面才能把检查挂进 CI 或提 PR 前的门禁。

agt doctor

预期输出: AGT Doctor 开始，列出已安装包与配置路径

agt lint-policy ./policies

预期输出: No issues found.（有格式问题时逐行报 error）

装好确认：

• doctor 列出已安装包，没有红色缺失项；
• lint-policy 对空策略目录/合法策略文件输出 No issues found.。

卡住怎么办：

• ./policies 不存在 → 先 mkdir -p policies 再跑（lint-policy 检查的是目录下的策略文件）；
• verify 提示策略未配置 → 正常现象：agt verify 在策略未配置时会给出引导提示，先补策略文件再验。

怎么确认修好了

三步，确认 CLI 链路完整：

agt --version

预期输出: agt, version 4.1.0

agt doctor

预期输出: AGT Doctor 开始，列出已安装包与配置路径（无红色缺失项）

agt lint-policy ./policies

预期输出: No issues found.（有格式问题时逐行报 error）

• 版本正常 + doctor 无缺失 + lint-policy 能跑 = 装好且治理链路可用；
• 策略配置好后，agt verify 能出合规结果 = 门禁可挂 CI。

其它环境的表现（常见变体）

• [full] extras 全家桶（方式 B）：能力全开但包多，卸载要逐个卸子包（见卸载段），未实测。
• Claude Code 插件形态（方式 C）：注册面在 ~/.claude.json，需登录环境，未实测。
• 与 oh-my-claudecode 共装：CLI 形态实测共存（实测记录（本地留存））；插件形态注册面未实测 → possible-conflict。
• venv 场景：pip 与 python 必须同环境，先激活 venv 再装再用。

日常使用

启动与入口

agt 没有常驻进程，需要时直接调 CLI。入口是 agt --help，子命令即功能清单。

常用操作

操作一：查看命令清单

agt --help

预期输出: 以 Usage: agt [OPTIONS] COMMAND [ARGS]... 开头，含 verify/doctor/lint-policy/test/integrity/red-team/cred

操作二：安装健康诊断（换环境、升级后先跑）

agt doctor

预期输出: AGT Doctor 开始，列出已安装包与配置路径

操作三：策略文件检查（治理核心，本环境实测）

agt lint-policy ./policies

预期输出: No issues found.（有格式问题时逐行报 error）

操作四：合规验证（OWASP ASI，策略配好后跑）

agt verify

预期输出: 合规检查结果（策略未配置时给出引导提示）

数据与目录

• CLI 形态：无独立数据目录，配置随 pip 环境（venv 场景在 venv 内）；
• 方式 C 插件形态：注册面在 ~/.claude.json。

卸载与清理

note: 与安装一一对应：方式 A/B 用 pip uninstall（方式 B 还要卸各子包）；方式 C 在 Claude Code 内 /plugin remove；最后一行验证零残留

pip uninstall -y agent-governance-toolkit || true
command -v agt >/dev/null 2>&1 && echo "agt 仍存在（方式 C 安装请执行 /plugin remove agent-governance-toolkit）" || echo "agt removed: OK"

预期输出: agt removed: OK

方式 B 残留清理（[full] extras 装的子包）：

pip uninstall -y agent-os-kernel agentmesh-platform agent-runtime agent-sre agentmesh-marketplace agentmesh-lightning agent-hypervisor

依赖警告

• 版本：[4.1.0, 4.1.0] 锁定单版本（meta 包形态，升级需重验子包集）。
• 环境：Python >= 3.10；pip 与 python 必须同环境（venv 场景先激活）。
• 网络：PyPI 官方/清华镜像均可（实测量级相当）；海外直连环境用默认命令即可。
• 共装：与 oh-my-claudecode CLI 形态实测共存（实测记录（本地留存））；插件形态注册面（~/.claude.json）未实测 → possible-conflict。
• 写面：CLI 形态零写面；插件形态写 ~/.claude.json。

FAQ（常见问题）

• 问：安装后 agt 命令找不到？答：检查 Python >= 3.10 与 pip 安装路径（venv 场景需先激活 venv）；国内网络确认使用安装段方式 A 的国内分支命令。
• 问：[full] 装了一堆包，卸载怎么卸？答：pip uninstall 主包后继续卸载各子包（agent-os-kernel / agentmesh-platform / agent-runtime / agent-sre / agentmesh-marketplace / agentmesh-lightning / agent-hypervisor），或直接按上游文档执行。
• 问：和 oh-my-claudecode 能一起装吗？答：CLI 模式实测可共存（互不干扰，见 实测记录（本地留存））；两者 Claude Code 插件形态的注册面（~/.claude.json）未实测，当前判定 possible-conflict。
• 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口（usage-report 模板）；项目自身问题请向作者仓库反馈。