内容
# coverctl
**智能代理循环覆盖率治理 — 在提交前检查您的 AI 编程代理调用，而不是在 CI 后阅读仪表盘。**
[开始使用 ↓](#开始使用) · [它是什么样子 ↓](#它是什么样子) · [MCP 工具 ↓](#mcp-工具) · [CLI 参考 ↓](#cli-参考) · [为什么存在 ↓](#为什么存在) · [社区 ↓](#社区)
 
> *"我们的 AI 代理快速编写代码，但在编辑时对覆盖率策略视而不见。我们只能在 CI 中看到故障，而此时上下文已经消失，代理只能猜测修复方式。"*
适用于具有常规布局的标准 Go/Python/JavaScript/Java/Rust 项目。模拟密集型代码或特殊的 monorepos 可能需要 `.coverctl.yaml` 中的显式 `domains:` 块。
## 开始使用
```bash
brew install klarlabs-studio/tap/coverctl
```
将 coverctl 集成到 Claude Code (`~/.config/claude-code/mcp.json`):
```json
{
"mcpServers": {
"coverctl": {
"command": "coverctl",
"args": ["mcp", "serve"]
}
}
}
```
询问代理： *"运行 coverctl 检查并告诉我哪些域发生了回归。"*
对于 Cursor / Cline / Claude Desktop / Aider / Continue / OpenCode 等其他 MCP 客户端，请参阅 [docs/src/content/docs/mcp.mdx](docs/src/content/docs/mcp.mdx)。所有支持 MCP 的客户端都可以使用；`coverctl mcp serve` 默认在代理模式下运行（3 个工具：`check`、`suggest`、`debt`）。使用 `--mode=ci` 以获取完整的九种工具。
验证安装是否成功：
```bash
coverctl mcp doctor # PASS/FAIL per step with remediation
```
## 它是什么样子
*为了清晰起见而渲染 — 您的客户端可能会以不同的方式格式化工具调用。*
```text
您： 为 api 域添加电子邮件验证功能。
Claude: 我将在 internal/api/email 中添加 EmailValidator + 测试。
[编辑： internal/api/email.go, internal/api/email_test.go]
工具调用 → coverctl 检查
结果 → 通过：false；失败：api（78.2%，需要 80%）
未覆盖：internal/api/email.go:42-58（错误路径）
工具调用 → coverctl suggest api
结果 → 未覆盖文件：email.go（16 行），retry.go（4 行）
电子邮件验证器.Validate 中的两个错误分支未被覆盖。
我将添加空输入和畸形域的案例，以便在提交前使 api 达到 80% 的阈值。
```
以前在 CI 中需要 8 分钟才能发现的回归问题在同一个代理调用中得到了修复。
**代理做得很好：** 读取 `check` 输出逐字逐句，调用 `suggest` 查找未覆盖的文件，调用 `debt` 对最小的修复进行排名，然后重新运行 `check` 以确认。
**请注意：** 代理可能会在 `.coverctl.yaml` 中降低阈值以“修复”失败（这不是修复）。代理声称覆盖率上升而没有新的 `check` 调用（幻觉）。代理忽略拒绝 `error_code` 并重试相同的输入。
coverctl 返回确定的结构化信号；代理的 *修复* 仍然需要人类阅读。完整的合约在 [docs/src/content/docs/mcp.mdx](docs/src/content/docs/mcp.mdx) 中。
## 为什么存在
AI 编程代理在编写代码时对覆盖率视而不见。他们编辑，您提交，回归问题在几分钟或几小时后在 CI 中出现 — 太晚了，无法在同一会话中纠正。现有的覆盖率工具（Codecov、Coveralls、本地 `go test -cover`）针对的是阅读仪表盘或 PR 评论的人类，而不是在内联推理的代理。
coverctl 是为代理循环构建的：
- **在提交前捕获回归。** 在代理的编辑回合中提供覆盖率反馈 — 而不是在 CI 失败后几分钟。楔形指标是在提交前捕获的回归。
- **通过 MCP 调用代理。** 说的是 MCP — Anthropic、OpenAI、Google、Microsoft、AWS 监管的多供应商工具标准。适用于今天的每个 MCP 客户端；无需修改即可适用于未来的客户端。
- **多语言治理，一个配置。** 一个 `.coverctl.yaml` 在 15 种语言中强制执行每个域的阈值。代理可以处理任何语言；覆盖率工具也必须如此。
- **本地优先。** 您的源代码永远不会离开机器。代理通过 stdio 调用 coverctl，而不是通过 SaaS API。无需帐户，无需上传，无需代理访问的第三方依赖。
## MCP 工具
代理模式提供三个工具（`check`、`suggest`、`debt`）以实现可靠的代理工具选择。CI 模式（`--mode=ci`）添加其他工具。
| 工具 | 模式 | 目的 |
| --- | --- | --- |
| `check` | 代理 + CI | 运行测试并强制执行策略。返回每个域的通过/失败、文件和警告。 |
| `suggest` | 代理 + CI | 推荐阈值（`current` / `aggressive` / `conservative`）。 |
| `debt` | 代理 + CI | 每个域的覆盖率差距 — 排名以确定哪里需要努力。 |
| `init` | CI | 自动检测项目结构并创建带有域策略的 `.coverctl.yaml`。 |
| `report` | CI | 分析现有的覆盖率配置文件而不运行测试。 |
| `record` | CI | 将当前覆盖率记录到历史记录中以跟踪趋势。 |
| `compare` | CI | 差异两个覆盖率配置文件。返回增量、改进/退化文件和域更改。 |
| `badge` | CI | 生成 SVG 覆盖率徽章。 |
| `pr-comment` | CI | 将覆盖率报告发布到 GitHub / GitLab / Bitbucket PR。 |
### MCP 资源（只读上下文）
| URI | 内容 |
| --- | --- |
| `coverctl://debt` | JSON 格式的覆盖率债务。 |
| `coverctl://trend` | 记录的历史记录趋势。 |
| `coverctl://suggest` | 阈值建议。 |
| `coverctl://config` | 检测到的项目配置。 |
## 安全边界
coverctl 将 MCP 流量视为不信任的双向流量，按照致命三重威胁模型。
- **输入边界。** 来自 MCP 的测试运行器标志，允许任意代码加载（`--rootdir`、`--cov-config`、`-D`、`-I`、`--require`、`--init-script`、`--node-options`，...）在来自 MCP 时被拒绝。拒绝响应使用带有 `error_code` 和代理可操作 `remediation` 的稳定模式。来自人类终端的 CLI 调用不会被净化；人类是那里的信任边界。
- **输出边界。** 流回代理的用户控制字符串（覆盖率配置文件中的文件名、测试名称、配置文件派生的路径、`pr-comment` 中的 PR 描述内容）被规范化后返回。防止通过恶意 PR 或攻击者命名的测试文件的返回行注入。
coverctl 是本地优先的。默认安装不会传输任何内容 — 无遥测、无分析、无源数据。具有 `--mcp-telemetry` 标志的可选加入功能会将结构化的工具调用事件输出到 stderr，供用户自行检测管道（格式在 [docs/design/mcp-metrics-spec.md](docs/design/mcp-metrics-spec.md) 中记录）。对抗性评估（50 多个场景，位于 [internal/eval/](internal/eval/)）在每次发布时都会进行，以确保拒绝模式完整性和防止注入攻击。
完整的威胁模型 + 剩余风险：[docs/security/mcp-threat-model.md](docs/security/mcp-threat-model.md)。
## CLI 参考
CLI 是 MCP 服务器的基础；人类可以直接使用它。
| 命令 | 目的 |
| --- | --- |
| `init` / `i` | 交互式向导，自动检测语言和域。 `--no-interactive` 用于 CI。 |
| `check` / `c` | 运行覆盖率并强制执行策略。 `-o json` 用于机器输出， `--fail-under N`， `--ratchet`， `--from-profile`。 |
| `run` / `r` | 生成覆盖率工件而不进行策略评估。 |
| `watch` / `w` | 在开发过程中文件更改时重新运行覆盖率。 |
| `report` | 评估现有的配置文件。 `-o html`， `--uncovered`， `--diff <ref>`， `--merge <profile>`。 |
| `detect` | 自动检测域并编写配置。 `--dry-run` 预览。 |
| `badge` | SVG 覆盖率徽章。 `--style flat-square`。 |
| `compare` | 差异两个配置文件。 |
| `debt` | 覆盖率债务报告。 |
| `trend` | 来自记录历史的覆盖率趋势。 |
| `record` | 将当前覆盖率追加到历史记录。 `--commit`， `--branch` 用于 CI。 |
| `suggest` | 阈值建议。 `--write-config` 应用。 |
| `pr-comment` | 将覆盖率发布到 GitHub/GitLab/Bitbucket PR。 |
| `ignore` | 显示配置的排除和跟踪的域。 |
| `mcp serve` | 启动 MCP 服务器（stdio）。 `--mode=agent\|ci\|auto`。 |
| `mcp doctor` | 首次运行验证：每个步骤的 PASS/FAIL 带有补救措施。 |
| `survey` | Sean Ellis 40% PMF 提示；追加到 `~/.coverctl/survey.jsonl`。 |
全局标志： `-q/--quiet`， `--no-color`， `--ci` （组合安静 + GitHub Actions 注释）。
### 测试执行标志
`check`、`run`、`record` 接受转发到底层测试运行器的工具链标志：
| 标志 | 示例 |
| --- | --- |
| `--tags` | `--tags integration,e2e` |
| `--race` | （Go race 检测器） |
| `--short` | 跳过长时间运行的测试 |
| `-v` | 詳細的测试输出 |
| `--run` | `--run TestFoo` |
| `--timeout` | `--timeout 30m` |
| `--test-arg` | 可重复： `--test-arg=-count=1 --test-arg=-parallel=4` |
| `--language` / `-l` | 覆盖自动检测： `go`， `python`， `nodejs`， `rust`， `java`， ... |
### 终端流程（无代理）
如果您更喜欢直接运行 coverctl：
```bash
coverctl init # 自动检测语言 + 域，写入 .coverctl.yaml
coverctl check # 强制执行策略；违反时退出 1
coverctl suggest --strategy current
coverctl record
```
如果步骤失败： `coverctl detect --dry-run` 预览 `init` 输出； `coverctl check -o json` 显示结构化故障详细信息； `coverctl record --commit "$(git rev-parse HEAD)" --branch "$(git rev-parse --abbrev-ref HEAD)"` 在 CI 中显式提供元数据。
## 配置
`.coverctl.yaml`（模式： [`schemas/coverctl.schema.json`](schemas/coverctl.schema.json)）：
```yaml
version: 1
policy:
default:
min: 75
domains:
- name: auth
match: ["./internal/auth/..."]
min: 90 # 关键路径 — 更严格
- name: api
match: ["./internal/api/..."]
min: 80
- name: utils
match: ["./internal/utils/..."]
# 默认情况下 fallback 到 min: 75
exclude:
- internal/generated/*
```
每个域的强制执行是重点：整体覆盖率会隐藏关键路径的回归。 coverctl 评估每个域与其自身的最低限度，如果任何域低于限制，则会失败构建。
### 高级
```yaml
files:
- match: ["internal/core/*.go"]
min: 90 # 每文件覆盖率
diff:
enabled: true
base: origin/main # 仅在更改的文件上强制执行
integration:
enabled: true # Go 1.20+ GOCOVERDIR 集成测试
packages: ["./internal/integration/..."]
cover_dir: ".cover/integration"
profile: ".cover/integration.out"
merge:
profiles: [".cover/unit.out", ".cover/integration.out"]
annotations:
enabled: true # // coverctl:ignore, // coverctl:domain=NAME
```
多包 monorepo？ 使用 `extends:` 继承策略。起点：复制 `templates/coverctl.yaml`。
## 支持的语言
| 语言 | 格式 | 检测标记 |
| --- | --- | --- |
| Go | 原生覆盖率配置文件 | `go.mod`， `go.sum` |
| Python | Cobertura， LCOV | `pyproject.toml`， `setup.py`， `requirements.txt` |
| TypeScript / JavaScript | LCOV | `tsconfig.json`， `package.json` |
| Java | JaCoCo， Cobertura | `pom.xml`， `build.gradle` |
| Rust | LCOV (cargo-llvm-cov) | `Cargo.toml` |
| C# / .NET | Cobertura (coverlet) | `*.csproj`， `*.sln` |
| C / C++ | LCOV (gcov/lcov) | `CMakeLists.txt`， `meson.build` |
| PHP | Cobertura (PHPUnit) | `composer.json`， `phpunit.xml` |
| Ruby | LCOV (SimpleCov) | `Gemfile`， `Rakefile` |
| Swift | LCOV (llvm-cov) | `Package.swift` |
| Dart | LCOV (dart test) | `pubspec.yaml` |
| Scala | Cobertura (scoverage) | `build.sbt` |
| Elixir | LCOV (mix test) | `mix.exs` |
| Shell | Cobertura (kcov) | `*.bats` |
## GitHub Action
```yaml
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-go@v6
with:
go-version: "1.25"
- uses: ./.github/actions/coverctl
with:
command: check
config: .coverctl.yaml
output: text
```
## 平台和开发体验团队
在许多多语言仓库中标准化覆盖率策略？ coverctl 提供了安全和采购审查所需的工件：
- [MCP 威胁模型](docs/security/mcp-threat-model.md) — 输入 + 输出边界控制，防止注入攻击，剩余风险。
- [拒绝模式参考](docs/src/content/docs/mcp.mdx) — 稳定的 `error_code` + `remediation` 代理恢复合约。
- [GTM 漏斗指标规格](docs/design/gtm-metrics-spec.md) — 检测内容和遥测保持可选。
考虑在组织范围内使用 coverctl？ 打开一个 GitHub 问题并添加 `platform-evaluation` 标签 — 很乐意一起了解架构和信任边界。
## 社区
- **Claude Code 插件市场** — 直接通过 `/plugin install` 安装 `coverctl`。
- **MCP 注册表** — 在 [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) 上列出。
- **GitHub Discussions** — [go.klarlabs.de/coverctl/discussions](https://github.com/klarlabs-studio/coverctl/discussions)。
- **赞助 coverctl 开发** — [github.com/sponsors/felixgeelhaar](https://github.com/sponsors/felixgeelhaar)。
使用 coverctl 几周了？ 运行 `coverctl survey` 分享 PMF 反馈（默认本地；除非您选择加入，否则不会传输任何内容）。
由 Felix Geelhaar 构建，来自多语言 AI 编码社区的贡献。
## 贡献
- TDD：行为变更前的测试。
- 覆盖率 ≥80% (`go test ./... -cover`)。
- 常规提交 (`feat:`、`fix:`、`chore:`，...) 用于 Relicta 版本升级逻辑。
- `main` 受保护；通过 CI 绿色后通过 PR 合并（`.github/workflows/go.yml` + `.github/workflows/eval.yml`）。
- 在推送前运行 `gofmt -w` 和 `golangci-lint v2`。
贡献者架构详情： [ARCHITECTURE.md](ARCHITECTURE.md)。
## 版本
由 [Relicta](https://github.com/felixgeelhaar/relicta) 管理。不要手动推送 `v*` 标签。
## 安全
参见 [SECURITY.md](SECURITY.md) 以获取披露政策。MCP 输入净化 (`internal/mcp/sanitize.go`) 和输出规范化 (`internal/mcp/sanitize_output.go`) 是防止注入攻击的主要防御措施；请私下报告绕过行为。
