sroberts/plumbline
GitHub: sroberts/plumbline
基于 AI 代码库成熟度模型（ACMM），通过确定性扫描评估代码仓库的 AI 辅助开发就绪程度并给出分级评级。
Stars: 3 | Forks: 0
# plumbline
仓库级别的 AI 编码就绪度评估工具，使用 Go 编写。
Plumbline 会扫描代码仓库，寻找使 AI 驱动的开发变得可靠的反馈循环（指令文件、覆盖率关卡、夜间测试套件、自动分拣、issue 到 PR 的流水线），并报告该仓库处于 **AI 代码库成熟度模型 (ACMM)** 的哪个级别。检测是确定性的——没有 LLM 调用，没有网络请求。
基于 Andy Anderson 的论文 [*The AI Codebase Maturity Model: From Assisted Coding to Self-Sustaining Systems*](https://arxiv.org/abs/2604.09388v1)（该论文的 `.md` 文件作为 `the_ai_codebase_maturity_model.md` 包含在内，通过 Microsoft MarkItDown 从 PDF 转换而来）。有关此实现故意偏离的地方，请参阅下面的 **[与源论文的差异](#deviations-from-the-source-paper)**。
## 安装
```
go install github.com/sroberts/plumbline/cmd/plumbline@latest
```
一旦标记了版本，预构建的二进制文件 (darwin / linux × amd64 / arm64) 将发布在 [Releases](https://github.com/sroberts/plumbline/releases) 页面上。
## 快速开始
```
# 裸调用：在终端上打开 Bubble Tea TUI。
plumbline
# Pipeline / CI：简要文本摘要。
plumbline | tee maturity.txt
# 供 LLM tool harness 使用的机器可读判定。
plumbline --json
# 在 scan 运行时将进度事件流式传输到 stderr。
plumbline --json --events ndjson 2>events.log >verdict.json
# CI gate：未达到 level 3 则失败。
plumbline --fail-below 3 --quiet
# 深入查看单个 signal 的状态、证据和修复配方。
plumbline inspect l2.agent-instructions
# Scaffold 缺失的 artifact（dry-run；使用 --apply 实际写入）。
plumbline fix l2.agent-instructions
plumbline fix l2.agent-instructions --apply
# 安装 Claude Code skill，以便你 repo 中的 AI agent 知道如何驱动 plumbline。
plumbline install-skill --apply
```
## ACMM 级别
该模型通过**反馈循环拓扑**分配级别，而不是通过 AI 自主性。级别是顺序的——级别 *N* 需要级别 *N−1* 的产物。
| 级别 | 名称 | 循环拓扑 | Plumbline 寻找的内容 |
|------|------|---------------|--------------------------|
| 1 | Assisted (辅助) | 开环 | (隐含的起点——不需要检查) |
| 2 | Instructed (受指导) | 人 → AI | 一个代理指令文件 (CLAUDE.md / AGENTS.md / copilot-instructions / .cursorrules / .windsurfrules)，CONTRIBUTING.md，PR 模板，提交规则 |
| 3 | Measured (可度量) | AI → 指标 → 人 | 构建/lint 关卡，覆盖率关卡，计划的合规性/a11y/性能/安全性检查，不稳定测试分析，错误监控，NPS，验收跟踪 |
| 4 | Adaptive (自适应) | 循环自我闭合 | 自修改配置，亚日频次（每日多次）自动分拣，阈值驱动的阻断，工作树代理，错误恢复 |
| 5 | Self-Sustaining (自我维持) | 代码库*即*策略 | issue 到 PR 的流水线，自我改进，从 PR 生成文档，多仓库编排 |
一个拥有出色 L3 但缺少 L2 的仓库只能评为 L1——你不能跳过级别。
运行 `plumbline signals` 查看 21 个信号的目录，或运行 `plumbline help levels` 查看详细说明。
## 与源论文的差异
Plumbline 大致遵循论文中的表 2，但有些信号被有意重构。**完整的理由请参见 [SPEC.md §6 → "与源论文的差异"](SPEC.md#deviations-from-the-source-paper)。** 主要差异如下：
- **L2 代理指令是一个单一信号，而不是多个。** 论文将 `CLAUDE.md` 和 `Copilot instructions` 列为单独的 L2 反馈循环（参考部署同时运行了两者）。Plumbline 将它们以及 `AGENTS.md`、`.cursorrules` 和 `.windsurfrules` 折叠成一个单一的 `l2.agent-instructions` 信号，只要存在**任何一个**就会触发。大多数团队使用一个代理；因为团队没有为没人使用的工具编码指令而惩罚一个项目是错误的决定。
- **PR 模板位于 L2**，而不是 L3——论文表述模糊；“通过检查清单编码的判断”是 L2 的定义。
- **L3+ 的工作流信号在 MVP 版本中仅支持 GitHub Actions。** GitLab CI / Buildkite / CircleCI / Jenkins 被推迟到 `--ci-system` 之后实现；这不是哲学上的分歧，只是范围上的裁剪。
## 输出格式
| 模式 | 用例 |
|---|---|
| TUI（在终端中默认） | 交互式探索；深入查看信号；应用修复 |
| `--json` | 机器可读的判定结果；LLM 工具线束 |
| `--report markdown --out maturity.md` | 可提交的报告 |
| `--report sarif --out plumbline.sarif` | GitHub 代码扫描 |
| `--events ndjson` 在 stderr 上 | 扫描时每个信号的进度事件 |
Schema 通过 `plumbline schema {verdict, signal-result, event, config}` 发布 (draft 2020-12)。
## TUI 快捷键
| 键 | 动作 |
|---|---|
| `↑` / `↓` (或 `j` / `k`) | 在信号列表中移动选择 |
| `enter` | 打开所选信号的详情屏幕 |
| `a` | 应用信号的修复（仅在标记为 `✚` 的信号上） |
| `r` | 原地重新运行扫描 |
| `esc` | 返回 |
| `q` / `ctrl-c` | 退出 |
在修复流程中：在输入字段之间使用 `tab`/`shift+tab`，`enter` 前进，`y`/`n` 确认或取消预览。
## 应用修复 (安全性)
`plumbline fix` 是 plumbline 在目标仓库内部进行写入的**唯一**途径。默认设置是保守的：
- 默认为试运行；需要 `--apply` 才能实际写入。
- `create-file` 拒绝覆盖现有文件。
- `append-file` 要求目标已经存在。
- 路径必须是相对路径，并在仓库根目录内解析；`..` 和绝对路径将被拒绝。
- 未知的 `FixOpKind` 将被拒绝。
其他所有内容（`assess`、`inspect`、`signals`、`explain`、`schema`、`help`、`version`）都是只读的。
## CI 关卡 (GitHub Actions)
```
# .github/workflows/maturity.yml
name: ACMM gate
on: pull_request
jobs:
plumbline:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with: { go-version: stable }
- run: go install github.com/sroberts/plumbline/cmd/plumbline@latest
- run: plumbline --fail-below 3 --quiet --signal-set v1
```
`--signal-set v1` 锁定规则集版本，这样关卡就不会在 plumbline 升级时悄然改变。`plumbline help compatibility` 记录了每个版本包含的内容。
## 通过编码代理使用 plumbline
将 plumbline 使用指南安装到你的工具预期的位置。传递 `--target ` 进行选择：
| 目标 | 路径 | 备注 |
|---|---|---|
| `claude` (默认) | `.claude/skills/plumbline/SKILL.md` | 专用 |
| `cursor` | `.cursor/rules/plumbline.mdc` | 专用 |
| `gemini` | `GEMINI.md` | 共享 |
| `codex` | `AGENTS.md` | 共享 (也可被其他 AGENTS.md 工具读取) |
| `opencode` | `AGENTS.md` | 共享 |
| `windsurf` | `.windsurfrules` | 共享 |
| `cline` | `.clinerules` | 共享 |
| `copilot` | `.github/copilot-instructions.md` | 共享 |
```
# 此 repo（默认 = claude）。
plumbline install-skill --apply
# 此 repo 中的 Cursor。
plumbline install-skill --target cursor --apply
# 全局（在 $HOME 下）的 Gemini。
plumbline install-skill --target gemini --global --apply
# 列出所有 targets。
plumbline install-skill --list
```
`--global` 在用户范围内安装 (例如，`~/.claude/skills/plumbline/SKILL.md`，`~/.gemini/GEMINI.md`)，适用于具有记录的全局位置的工具。运行 `--list` 查看完整集合；如果没有全局位置，在传递 `--global` 时将会报错。
TUI 提供了相同的选择器：在终端上裸跑 `plumbline` → 按下 **`i`** → 使用 `↑/↓` 选择目标 → 切换 `[g]` 以在全局 ↔ 项目范围之间选择 → enter 预览 → `y` 安装。
正文是为 AI 代理量身定制的——何时调用 plumbline、推荐的调用顺序、稳定的信号 ID/schemas/退出代码，以及何事**不应**调用它。前置数据是根据工具量身定制的 (Claude SKILL.md 前置数据、Cursor `.mdc` 前置数据、AGENTS.md / .windsurfrules 等的纯 markdown)。
## 对于 LLM 工具调用者 (没有该技能)
推荐的调用顺序：
1. `plumbline schema verdict` — 获取输出契约。
2. `plumbline signals --json` — 发现信号目录。
3. `plumbline assess --json --events ndjson 2>events.log >verdict.json` — 运行扫描。
4. 对于 `verdict.next_gap` 中的每个 id：`plumbline inspect --json` 获取证据 + 修复配方。
5. 进行脚手架搭建：`plumbline fix --apply --input KEY=VALUE …` (或使用 `--json` 获取结构化计划)。
稳定的 ID，稳定的 JSON-Schema `$id`，稳定的退出代码 (0 ok / 1 gate-failed / 2 cannot-run / 3 config-error)。`plumbline help agents` 包含完整的指南。
## 文档
- [SPEC.md](SPEC.md) — 完整规范：信号目录、评分数学、schema、偏差、里程碑
- [CLAUDE.md](CLAUDE.md) — 为向 plumbline 本身贡献的 AI 代理提供的指南
- `the_ai_codebase_maturity_model.md` — 源论文
- `plumbline help` — 专题指南 (`levels`、`signals`、`scoring`、`output`、`config`、`ci`、`agents`、`profiles`、`compatibility`、`fix`)
## 状态
v0.1.0 — 首次发布。单人开发者项目；目录涵盖了 L2–L5 之间的 21 个信号。修复脚手架涵盖了 L2 的目录；L3+ 的修复脚手架被有意推迟（“合并到现有工作流”的情况需要更多设计）。
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
标签：ACMM, AI编程, AI驱动开发, Bubble Tea, CI/CD门禁, EVTX分析, Go语言, LLM开发辅助, TUI, 云安全监控, 仓库扫描, 代码成熟度评估, 反馈循环, 成熟度模型, 日志审计, 程序破解, 自动修复, 软件开发工程, 静态分析