内容
# 治理者
治理者是一款**旨在为人类用户和AI代理简化Go项目开发的工具**。
它为验证、分析和审计Go代码提供了一个统一的结构化入口。治理者可以用作独立的命令行界面，类似于`go test`，也可以用作**MCP服务器以支持AI辅助开发**。
治理者按照预定的声明式顺序执行测试、代码检查、静态分析和代码健康检查。它返回类型化、可机器读取的结果，而不是非结构化的日志。
这种方法使AI代理能够编写和修改Go代码，并具有可证明的正确性，从而消除了创建自定义工作流、省略验证步骤或误解工具输出的需要。
## 为什么需要治理者
AI代理可以编写Go代码。
但是，这些代理在确保代码正确性方面经常遇到挑战。
**主要挑战不在于模型能力，而在于缺乏结构化执行**。
当代理依赖于临时shell命令时，经常会出现几个问题：
* 从日志中推断成功与否，而不是根据事实
* 跳过或不一致地重新运行验证步骤
* 失去更改与其影响之间的联系
* 用冗长、低信号输出污染上下文窗口
因此，生成的代码可能看起来正确，但缺乏可靠的测试、分析和审计能力。
治理者通过作为代码生成和验证之间的语义执行边界来解决这些问题。
### 治理者提供什么
**确定性验证**
每次执行都遵循一致的、有序的管道，确保每个步骤都透明地完成或省略。
**结构化结果**
治理者提供类型化的、有界限的结果，如通过、失败或不可用，从而消除了对日志解析的需要。
**强制工作流完整性**
测试、代码检查、静态分析和审计是首要步骤，而不是可选命令。
**统一执行和代码智能**
通过一个接口公开执行和`gopls`支持的代码智能。
**提高代理效率**
高级语义工具最小化冗余工具调用、重新执行和上下文窗口混乱。这使代理能够保留更多相关信息并更高效地实现正确代码。*
* 尚未收集有关令牌使用、墙上时钟时间和收敛率的实证基准。
## 安装
像`gopls`一样，在全局范围内安装治理者：
```bash
go install github.com/deixis/governor/cmd/governor@latest
```
需要Go 1.25或更高版本。
建议但不是必须安装`gopls`。当`gopls`可用时，治理者将其代理为`gov_*`MCP工具。如果`gopls`不存在，这些工具将返回错误和安装说明。
## 命令行界面用法
治理者提供以下命令：
```
governor check [标志] [包...]
governor audit [标志] [包...]
governor mcp [标志]
governor version
```
包参数遵循`go test`约定（`./...`、子树或导入路径）。省略时，默认为`./...`。
### governor check
运行正确性管道：测试、代码检查、静态检查。在第一次失败时停止。
```bash
governor check ./...
governor check -fix ./pkg/api/...
governor check -json ./...
```
| 标志 | 默认值 | 描述 |
|---|---|---|
| `-fix` | 关闭 | 在检查之前运行gofumpt和golangci-lint --fix |
| `-json` | 关闭 | 输出完整的RunResult为JSON |
| `-v` | 关闭 | 在失败时显示详细输出 |
| `-timeout` | 配置 | 覆盖每一步的超时 |
### governor audit
运行代码健康和安全检查。不会因失败而停止。
```bash
governor audit ./...
governor audit -json ./...
```
| 标志 | 默认值 | 描述 |
|---|---|---|
| `-json` | 关闭 | 输出完整的RunResult为JSON |
| `-v` | 关闭 | 详细输出 |
| `-timeout` | 配置 | 覆盖每一步的超时 |
### governor mcp
为AI代理启动MCP服务器：
```bash
governor mcp
governor mcp -http :9090
governor mcp -instructions
```
## MCP设置（Cursor）
将治理者添加到全局MCP配置（`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"governor": {
"command": "governor",
"args": ["mcp"]
}
}
}
```
工作目录自动设置为工作区根目录。
## MCP工具
### 原生工具
| 工具 | 描述 |
|---|---|
| `gov_check` | 运行完整的正确性管道 |
| `gov_audit` | 运行审计检查，不会因失败而停止 |
| `gov_inspect` | 检查以前运行的结果 |
| `gov_workspace` | 总结Go工作区 |
### 代码智能（通过gopls）
| 工具 | 描述 |
|---|---|
| `gov_diagnostics` | 工作区诊断 |
| `gov_package_api` | 包的公共API |
| `gov_search` | 模糊符号搜索 |
| `gov_file_context` | 包内依赖 |
| `gov_symbol_references` | 查找符号引用 |
| `gov_rename_symbol` | 重命名符号并返回差异 |
## 配置
治理者可以从存储库根目录的`.governor` YAML文件中读取可选的配置设置。
```yaml
version: 1
timeout: 5m
max_output: 1048576
test:
args: ["-race", "-count=1"]
lint:
config: .golangci.yml
staticcheck:
checks: ["all", "-ST1000"]
check:
steps: ["test", "lint", "staticcheck"]
audit:
steps: ["coverage", "complexity", "deadcode", "dupl", "vulncheck"]
```
治理者**不是**CI系统、任务运行器或shell包装器。
它是一个**执行治理者**：代码生成保持灵活，但**正确性、结构和审计能力得到强制执行**。
