iroha924/mumei

# mumei [](./LICENSE) [](https://github.com/iroha924/mumei/actions/workflows/ci.yml) [](https://scorecard.dev/viewer/?uri=github.com/iroha924/mumei) [](https://slsa.dev/spec/v1.0/levels#build-l3) [](https://www.sigstore.dev) [](https://github.com/iroha924/mumei/network/updates) **mumei 是一个专为 Claude Code 打造的质量强制执行框架。** 构建成功了。测试通过了。 ……但它们是真的通过了，还是 agent 让它们通过的？CI 无法区分 这些情况。mumei 可以： - 它按照 `HEAD` 的定义重新运行测试，而不是按照你的工作树 - 它冻结了不允许 agent 调整的测试 - 它通过读取 diff 来发现那些用绿灯换取红灯的举动 一个被删除的测试。一个被抑制的类型错误。一个昨天还不存在的 `continue-on-error`。 一个悄无声息地从发布 tarball 中遗漏的文件。 这些检查位于 OS 边界的 Hooks 中，因此 agent 的意图被视为 不受信任的输入：标准是被_强制执行_的，而不是在 prompt 中建议它可以选择 忽略的内容。 然而，强制执行并不是单一的事情，mumei 在表面上就说明了这一点：那些_重新测量_的关卡（从干净的 `HEAD` 重新运行测试、真正的扫描器、真正的 `git archive`）能够抵御想要越过它们的 agent；mumei 记录自身进度的文件是一条审计轨迹，而不是一堵墙。哪个是哪个，以及这对你的部署方式意味着什么，在 [什么能守住，什么守不住](#what-holds-and-what-does-not)中进行了详细说明。 _无名管家：它默默服务，不揽功劳，坚守底线 —— “恐怕那样不行。”_ [日本語版 README](./README.ja.md) ## 为什么是现在 随着 coding agent 接管越来越多的编写工作，瓶颈也随之转移 — 从生成代码转移到审查代码、验证代码，以及判断“完成”的 含义。mumei 就是为这种转变而构建的：它将这些检查固定在 OS 边界上， 因此即使代码到达的速度超过了任何人阅读它的速度，它们也能守住。([当 AI 构建自身时](https://www.anthropic.com/institute/recursive-self-improvement)) 这种转变现在有了一个名字 — _loop engineering_：设计在无人值守的情况下运行 agent 的循环。但无人值守的循环也会导致无人值守的错误，而这正是 mumei 守护的边界。 ## 为什么选择 mumei 一条 `CLAUDE.md` 规则、一个系统 prompt、一句“请先运行测试”——这些都是 建议，而一个在压力下能力强大的 agent 会绕过建议。mumei 将你关心的标准从 prompt 中移出，并放置在 OS 边界上。 在那里，一个 Hook 会检查改变项目状态的工具调用 —— 编辑、提交、推送、 计划转换 —— 并拒绝那些破坏不变量的调用。 确定性检测器、多样化的审查视角、要求提供证据的裁决 — 这些都是目前的筹码，而且有几个优秀的工具做得很好。 **没有其他工具会问构建是否被_制造_为通过的。** 官方的 `/code-review` 在设计上排除了测试覆盖率。这个差距正是 mumei 承担的工作。 它_强制执行_而不是要求去做的四件事： - **是框架，而不是聊天。** Phases、Waves、提交、推送和整个 审查 pipeline 都由 Hooks 确定性地驱动 —— agent 无法 通过 prompt 绕过它们。唯一的逃生舱是一个单一的、显式的 `MUMEI_BYPASS=1` —— 一个你刻意设置的 env var，也是 mumei 唯一不会让 agent 替你设置的东西：将它写入 Claude Code 的设置中会被 拒绝，并且以该变量激活状态开始的会话在打开时会说明这一点。 - **测试无法被 agent 悄悄削弱。** 在提交时，测试会在干净的 `HEAD` 工作树中重新运行，因此在你工作树中的造假手段没有任何影响。 Golden files 在被读取前会从 `HEAD` 恢复。Property tests 是盲写的 — 仅根据 spec 和 signature，而无需查看 implementation — 然后被冻结。并且 diff 本身会被读取，以发现那些用绿灯换取红灯的举动。 - **Spec 驱动开发，如果你需要的话。** 许多工具能_生成_ spec； mumei 让 agent _按照它去构建_ — 需求 → 设计 → 任务（每一个都 独立审查）→ 一次审批关卡 → 逐 Wave 实现。 跳过一个 phase 或提交一个损坏的 Wave 会被物理拦截。它是 三种接入方式之一，而不是过路关卡：`/mumei:review` 运行相同的审查 引擎和相同的检测器来对抗你当前的 diff，**没有 `.mumei`，没有 状态，没有仪式**，并且计划载体包装了 Claude Code 自己的计划模式 。带来你自己的流程；保留强制执行力。 - **有根据的审查，而不是凭感觉。** 确定性检测器（CVE / secret / type / test / SAST）首先运行，并为一项多视角审查_奠定基础_ — 在全新的上下文中进行安全和对抗性审查。然后，针对每个发现问题的验证器会将 没有根据的发现降级为 advisory，因此误报永远不会导致合并被错误拦截。裁决控制着推送，并且它总是会指出人类仍然需要手动检查什么。 ## 安装 从社区市场安装： ``` /plugin marketplace add anthropics/claude-plugins-community /plugin install mumei@claude-community /reload-plugins ``` 或者从自托管市场跟踪最新版本： ``` /plugin marketplace add iroha924/mumei /plugin install mumei@mumei /reload-plugins ``` 安装后，运行一次性的项目内设置： ``` /mumei:kindle ``` 卸载：`/plugin uninstall mumei@claude-community`（如果你是从自托管市场安装的，请使用 `mumei@mumei`；你项目中的 `.mumei/` 目录将保持原样）。 前置条件：用于 review-phase 检测器的 `semgrep` + `osv-scanner`。安装命令请参见 [docs/getting-started.md → 前置条件](./docs/getting-started.md#prerequisites)。 ## 工作流 ## mumei 强制执行的内容 上面提到的三大支柱，详细说明如下： - **是框架，而不是 prompt** — 每一个 phase / Wave / 提交 / 推送关卡都在工具调用边界被强制执行；agent 无法通过 prompt 绕过它。 - **受保护的状态** — `.mumei/` 状态、review verdicts 和 reviewer-execution 轨迹对 agent 是禁止访问的，无论是在 Edit/Write 路由还是在常见的 Bash 路由上（规则 S1/S2，M1/M2）；只有框架能写入它们。关于这实际上能达到多大程度，请参阅 [什么能守住，什么守不住](#what-holds-and-what-does-not)。 - **测试完整性检测** — 一次通过的构建无法告诉你的一件事是，这次构建是否是被动过手脚才通过的。mumei 按照 `HEAD` 的定义重新运行测试，冻结盲写的 property tests，并报告那些删除测试、抑制类型错误或从发布的 tarball 中丢弃文件的 diff。 - **不会错误拦截的关卡** — CVE / secret / type-error / failing-test 将裁决固定为 `MAJOR_ISSUES`；嘈杂的 SAST 会通过一个裁决关卡，仅在确认后才拦截，因此误报永远不会导致合并被错误拦截。缺失的工具会被 warn-skip，而不是致命错误。 - **防篡改验证** — 提交时，测试会在干净的 `HEAD` worktree 中重新运行，因此未提交的造假手段（篡改的 `conftest.py`、被 monkeypatch 的 reporter、被编辑的 bytecode）无法伪造通过。 - **Agent 无法钻空子的测试** — 不变属性是盲写的，仅从 spec 和 signature 而不看 implementation，然后被冻结，因此测试无法通过调整去迎合有缺陷的 implementation。按 AC 选择性启用。 - **多视角审查** — 在全新的上下文中进行独立的需求 / 设计 / 任务审查，然后基于 diff 进行安全和对抗性审查（非对称上下文，而非模型轮换），并且针对每个发现的问题，验证器会将没有根据的发现降级为 advisory。 - **对其能力上限保持诚实** — 每一个裁决都带有盲点免责声明，并准确指出需要人工审查的内容；mumei 从不声称能取代人工审查。 - **基于 Wave 的提交** — 1 Wave = 1 次提交。Hooks 会将 diff 与每个任务的 `_Files:_` 进行交叉检查，以阻止虚假完成。 - **已签名的、可证明的发布** — Sigstore 无密钥签名，SLSA Level 3，CycloneDX SBOM。请参见 [docs/getting-started.md → 安全与供应链](./docs/getting-started.md#security--supply-chain)。 - **无名管家姿态** — mumei 默默服务，不揽功劳：在你主动选择启用之前零副作用（没有 `.mumei/current` → 每个 Hook 都是空操作），没有主动发言，事实形式的裁决，没有 telemetry。 ## 什么能守住，什么守不住 mumei 的关卡有两种强度。它们之间的界限不是本地与 CI 之间的区别。 而在于**关卡是测量了答案本身，还是相信了 mumei 写入的文件**。 ### 重新测量的关卡（强） 这些关卡从不轻信 agent。 - **从 `HEAD` 重新运行测试。** 在提交时，mumei 会构建一个干净的 worktree 并在那里运行测试。篡改过的 `conftest.py` 或存在于你工作树中被 monkeypatch 的 reporter 都不会产生任何影响。Golden files 会首先从 `HEAD` 恢复。 工具关卡和 Stage 0 检测器执行的是真正的二进制文件。 - **tarball 和 diff 是被读取的，而不是被报告的。** `lint-distribution-shape` 运行真正的 `git archive` 并将其内容与真实的文件列表进行比较。 `lint-gate-weakening` 直接读取 diff 本身，寻找被删除的测试或被抑制的类型错误。 - **造假意味着必须提交造假代码。** 要击败上述任何一项，你都必须提交执行此操作的代码，而这会落入 diff 中，被人看到。 ### GitHub 端的关卡（强，但你必须手动开启） 分支保护 —— 要求来自非作者 code owner 的批准、 `enforce_admins`、`require_last_push_approval` —— 是持有你 shell 的 agent 无法触及的唯一控制措施。 它不是深度防御。它是**承重墙**。必需的状态检查 只是运行存储库（`scripts/lint-all.sh`、`tests/`）中的脚本。一个 范围限定为 `Contents: write` 的 token 可以将 lint 重写为 `exit 0`，然后必需的检查 就会变绿。代码树内部的任何东西都无法弥补这个漏洞，因为 代码树内部的所有东西都在树中。只有阅读 diff 的人类才能做到。 ### mumei 记录自身进度的文件（弱） `state.json`、任务复选框、review verdicts、`cost-log.jsonl`。这些不是 测量结果。它们是 **mumei 关于自身进度的自我声明**。 Hooks 拒绝了针对它们所有的 Edit/Write 路由和常见的 Bash 写入路由（规则 S1/S2，M1/M2）。这将伪造文件的行为从意外变成了 一种明显奇怪的举动。它并没有关上大门：Bash 守卫读取的是它接收到 的命令字符串，而一个命令可以隐藏它写入的位置。 因此，请将这些视为**一条记录，而不是一堵墙**。 ### 你无法通过编码绕过的前提条件 mumei 的预防性保证其前提是**agent 运行在某个你的凭证 无法触及的地方**。 在你机器上拥有你已认证的 `gh` 的 agent，并不会绕过 审批关卡。它**满足**了关卡 —— 因为对 GitHub 而言，使用你的凭证 做出的批准就是你的批准。 如果没有这种分离，mumei 就会从预防退化为记录。在 这种退化中存活下来的，是上面那些重新测量的关卡。这就是为什么我们不 会放弃它们。 ## 扎根于研究的设计 mumei 的强制执行模型源于最近关于 agent 可靠性和 审查精度的工作，而不是凭直觉。一些承重的研究结果（给出了 arXiv ID 供你查阅）： - 强大的 agent 会选择性地忽略 prompt 层面的规则，因此强制执行必须存在于一个硬边界上 —— mumei 的 Hooks。("Formal Policy Enforcement for Real-World Agentic Systems", arXiv 2602.16708; "Willful Disobedience", arXiv 2603.23806) - Agent 会漏掉自己大部分的错误，因此 reviewer 必须在全新的上下文中运行，并且永远不能自我审查。("Self-Correction Bench", arXiv 2507.02778) - 原始的 SAST 噪音很大；当 LLM 对_结构化的_检测器发现进行裁决，而不是进行冷时，精准度会急剧上升 —— 这就是 mumei 的 class-aware detector → validator 关卡。("ZeroFalse", arXiv 2510.02534) - 几个不同的审查视角胜过一群相同的 agent，因此 mumei 使用非对称上下文的 reviewer，而不是投票委员会。("Understanding Agent Scaling in LLM-Based Multi-Agent Systems via Diversity", arXiv 2602.03794) 这些为设计提供了依据；mumei 并未声明拥有上述论文的任何结果，而且 —— 正如下一节明确指出的那样 —— 从不声称能取代人工审查。 ## 命令 | Command | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/mumei:kindle` | 一次性项目内设置。创建 `.mumei/`，提议在 `CLAUDE.md` 中添加内容并带有 diff 预览。 | | `/mumei:glean ` | 可选的 pre-spec 问答循环（最多 3 轮 × 5 个问题）。输出保存至 `.mumei/scratch/.md`。 | | `/mumei:compose [feature]` | 针对新功能的载体选择器（用于完整 SDD 的 `spec` 或用于 Claude plan-mode 包装器的 `plan`）；自动恢复现有功能。Spec 载体：clarification → requirements → design → tasks（每个最多自动审查 3 次）→ 单次批准 → Wave-by-Wave → review。 | | `/mumei:peruse` | Plan-vehicle 审查 pipeline。运行 Stage 0 检测器 + security-reviewer + adversarial-reviewer + 每个问题的验证器，对当前的 diff 进行审查（一旦 `pending_review=true` 即开始，当最后一个 `TaskCompleted` 匹配 `task_created_count` 时设置）。 | | `/mumei:review [base] [spec]` | 通过共享引擎（检测器 → reviewers → 裁决关卡 → fail-open 裁决），对 `git diff $(git merge-base HEAD)`（PR-pushed + 未提交的更改）进行独立的一次性审查。在没有 mumei 功能的情况下也能工作；零副作用（无状态、ledger、memory 或提交）。可选的 spec 文件可启用 `spec-compliance-reviewer`。 | | `/mumei:shelve ` | 将一个 `done` 功能移动到 `.mumei/archive///`。自动检测载体（specs/ 或 plans/）并携带 `scratch/.md` 作为 `scratch.md`。 | | `/mumei:muse ` | 生成 `muse.md`，总结 AC 计数、Wave 计数、review iter 模式、fix-spiral 检测、token 成本、cache 命中率和已归档（或即将归档）功能的 hook 触发情况明细。只读；仅限用户调用。 | | `/mumei:attest ` | 详细的可靠性视图 —— 最近 10 次试验的 pass^3 以及来自 `reliability-log.jsonl` 的最后 10 次试验行表格。只读；仅限用户调用。 | | `/mumei:glance [feature]` | 单行可靠性摘要（` \| pass^3: (n=, window=10, k=3)`）。无参数形式会读取 `.mumei/current`。只读；仅限用户调用。 | ## `mumei` 不是什么 - 不是人工审查的替代品。该 pipeline 会浮现出有根据的发现，并指出其盲点；由人类来做决定。它起到关卡的作用；它不保证正确性。 - 不是 CI/CD 工具。Hooks 仅在 Claude Code 内部运行。 - 不是代码审查服务。Reviewers 通过你的 Claude Code 订阅在本地运行。 - 不是 SDD 适配器。mumei 有自己固执的 spec 格式。 - 不是多工具。不支持 Cursor / Codex / Aider。物理强制执行层是 Claude Code Hooks。 - 不是存储系统。状态是纯文件。没有 DB，也没有 MCP server。 ## 配套工具 - **基于框架的审查工作流** — 便携式可重用的 GitHub Actions 工作流，通过四个视角（正确性 / 安全性 / 可操作性 / 可维护性）驱动 Claude reviewer，并以 semgrep + osv-scanner 输出为基础，具备偏见中和和对能力上限的诚实声明。任何存储库都可以用一行 `uses:` 采用它；参见 **[docs/review-adoption.md](./docs/review-adoption.md)**。独立于插件本身。 ## 文档 - **[docs/getting-started.md](./docs/getting-started.md)** — 详细的长篇说明：两种载体、工作流、spec 和 tasks 格式、前置条件、项目布局、hook 规则、故障排除。 - **[ARCHITECTURE.md](./ARCHITECTURE.md)** — runtime 结构、分布情况、完整的强制执行表、reviewer pipeline、基于文件的状态模型。 - **[docs/operations-playbook.md](./docs/operations-playbook.md)** — 运行 mumei 的实用指南（主动执行 `/compact`、subagent 成本、prompt 缓存、字节精确工具、`MUMEI_BYPASS=1` 纪律）。 - **[SECURITY.md](./SECURITY.md)** + **[docs/security-policy.md](./docs/security-policy.md)** + **[docs/threat-model.md](./docs/threat-model.md)** + **[PRIVACY.md](./PRIVACY.md)** — 供应链验证、威胁模型、隐私。 ## License MIT

标签：AI编程助手, Git Hooks, SOC Prime, 开发工具