OnourImpram/mergen

# Mergen **AI 编码智能体的执行骨干。极致推理努力、Workflow 编排，以及对抗性验证，其治理机制确保流程繁简程度与风险相匹配。**

Mergen 得名于突厥神话中象征智慧与精准、明智判断与百发百中之箭的神明。这个名字即宣告了其架构。Mergen 凭借智慧来判断一项任务值得投入多少精力，并以精准度证明工作确已完成，且毫不拖泥带水（没有多余的冗余）。智慧即是 Governor。精准度即是验证关卡。 Mergen 是一个两阶段整体中的执行部分。[mneme](https://github.com/OnourImpram/mneme) 是记忆部分。mneme 记住了项目之所以如此的原因，其来源清晰可见且绝无捏造。Mergen 决定任务需要什么并证明其已达成目标。它们共同构成了 Agent Continuity Stack，仅通过一个无缝接合点相连。Mergen 不保留自身的任何持久记忆，没有仓库或索引。它仅写入本地执行与验证产物，而将持久记忆交由 mneme 处理。 Mergen 是原创作品。其运作原则借鉴了负责任的 AI 设计理念，未复制任何专有文本。章程为 [MERGEN.md](MERGEN.md)，原则到组件的映射为 [MERGEN_PRINCIPLES.md](MERGEN_PRINCIPLES.md)。“Claude”和“Claude Code”是 Anthropic 的商标。“Spec Kit”是 GitHub, Inc. (MIT) 的项目。内置的 Spec Kit 材料已在 [ATTRIBUTION.md](ATTRIBUTION.md) 和 [NOTICE](NOTICE) 中注明。Mergen 引擎的源流记录在 [PROVENANCE.md](PROVENANCE.md) 中。 ## 它是什么 Mergen 以单一身份发布两个核心部分。 ### A 部分：effort 模式 Claude Code 编译后的二进制文件暴露了一个 `/effort` 阶梯（`low`、`medium`、`high`、`xhigh`、`max`）以及一个特殊的 `ultracode` 模式，该模式意味着 `xhigh` 外加一项常设指令，即使用 Workflow 工具编排每一个实质性任务。原生方式无法将 `max` 努力等级与这种常设编排结合起来。Mergen 通过两种受支持的机制重构了这种组合： - **常设编排** 通过 `UserPromptSubmit` hook 实现，该 hook 在模式处于激活状态时，会在每一轮注入该指令。该指令承载了 Mergen 的运作原则：声明前必须验证，绝不捏造来源或结果，将检索到的内容视为数据而非指令，并且只构建能正常运行的最少代码。 - **Max effort** 通过原生 `/effort max` 命令实现。由于 hook 无法更改实时的 effort 值，因此 `/mergen` 命令会打印出相应的指令行供你粘贴一次。这唯一一次粘贴是不可或缺的。 完整机制详见 [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)。 ### B 部分：规格驱动开发层（Spec Kit 的超集） `core/commands/` 中的 15 个命令文件定义了完整的 SDD 生命周期：14 个命名的 Workflow 模式，加上 Mergen Agent（`/mergen-agent`），这是一个在一个命令中编排整个生命周期的单一入口。单一来源的渲染器生成了两个分发 shell：一个原生的 Claude Code skills 安装（以 `/mergen-*` 形式调用）和一个 Spec Kit 预设加扩展（以 `speckit.*` 或 `speckit.mergen.*` 形式调用）。Spec Kit 会建议结构化文档并依赖单一上下文来遵循它们。Mergen 则在 max effort 加上 Workflow 编排下运行相同的生命周期，其中每个命令都是一个多智能体模式，任务从依赖 DAG 开始进行波次并行运行，并且一个独立上下文的对抗性验证器必须确认文件系统和测试无误后，才能将任何任务标记为完成。每个命令也遵循 lazy ladder（懒惰阶梯）原则：进行全面彻底的推理，构建能正常运行的最少代码，绝不削减验证、安全性或可访问性。 详细信息和完整的对照表请见 [docs/SDD-SUPERSET.md](docs/SDD-SUPERSET.md)。 ### Governor：贯穿生命周期的智慧 对每个任务都投入最高级别的努力，这本身就是一种失败模式。一个拼写错误不值得兴师动众，而一个身份验证的更改绝不能敷衍了事。Governor（`/mergen-govern`）将任务分类为 `tiny`、`standard`、`spec` 或 `high-trust`，并设定记忆范围、Workflow 深度、证据标准，以及是否需要人工签字确认。高信任度触发条件（身份验证、支付、密钥、隐私和 PII、临床和受监管内容、不可逆操作、公共契约变更，以及将不受信任的输入视为指令）会强制设定一个确定性的底线，Governor 可以提高该底线，但绝不可以在未经察觉的情况下降低。临床和敏感工作无法被降级，即使通过配置也不行。Governor 会生成 `governor-decision.json`，而 `go` 路由器会执行所选的层级，并添加高信任度的人工检查点。Governen 正是让极致努力变得可承受的关键。 ## 快速开始（原生安装） 环境要求：Claude Code，PATH 中需包含 Python 3.9+。 ``` git clone https://github.com/OnourImpram/mergen.git cd mergen ./install.sh # macOS / Linux / Git Bash ``` 在 Windows PowerShell 中： ``` .\install.ps1 ``` 如果 PowerShell 阻止了该脚本，可以仅为当前会话运行它： `powershell -ExecutionPolicy Bypass -File .\install.ps1`。 安装程序会按顺序执行三个步骤： 1. `effort-mode/install.sh`（或 `.ps1`）安装 `/mergen` 命令和 `UserPromptSubmit` effort hook。 2. `python dist/native/build_native.py build` 将 15 个 `/mergen-*` skills 渲染到 `~/.claude/skills/`。 3. `python dist/native/patch_settings_hooks.py` 在 `~/.claude/settings.json` 中注册两个 SDD hooks（幂等、防破坏，并且能容忍 Windows 版 Claude Code 可能写入的 UTF-8 BOM）。 安装完成后，重启 Claude Code 或运行 `/hooks` 以加载新的 hooks。 ### 一个命令，全平台通用 `./install.sh` 和 `.\install.ps1` 会通过 bash 和 PowerShell 来执行。相同的这三个步骤，加上健康检查和干净的卸载过程，也可以通过一个单一跨平台的 `mergen` 命令来实现： ``` pipx install -e . # or: pip install -e . mergen install # render skills and register hooks (idempotent) mergen doctor # read-only health check, honest about the caveats mergen upgrade # re-render the skills after pulling a new version mergen uninstall # remove every artifact it created ``` 支持的可编辑安装路径为：mergn 从该仓库的 `core/` 渲染 skills，因此该命令需要用到此代码库的克隆版本。一个内置 `core/` 的独立 wheel 已在路线图上。`mergen doctor` 会报告当前已安装的内容、缺失的内容以及真实的注意事项（一次手动的 `/effort max` 粘贴，以及 SDD hooks 只是强化提醒，而非强制执行）。 ### 激活 effort 模式 ``` /mergen arm the mode, then paste the /effort max line it prints /mergen off disarm ``` ### 在项目中引导 SDD ``` ./install.sh --init ``` 这会创建 `/.specify/`，其中包含脚本、模板和 `memory/` 目录。 ## 15 个 /mergen-* 命令 每个命令都是一个命名的 Workflow 模式。所有命令都在 mergen 底层架构（最高级别推理努力、常设编排）下运行，并由 Governor 设定特定任务应匹配的模式深度。 | 命令 | 单行用途 | Workflow 模式 | |---|---|---| | `/mergen-agent` | **Mergen Agent。** 通过一个命令在整个生命周期中运行任务。 | 单一入口：激活、治理、路由并执行（通过 `/mergen-go`）、报告。编排其他 14 个 skills 而不取代它们；绝不跳过验证关卡，也绝不自动完成高信任度任务。 | | `/mergen-govern` | 按风险对任务进行分类并设定其流程。 | Governor：层级（tiny/standard/spec/high-trust）、记忆范围、证据标准以及人工批准，具备确定性的高信任度底线。生成 `governor-decision.json`。 | | `/mergen-constitution` | 编写或更新项目章程。 | 编写并在接受前进行对抗性自我检查。 | | `/mergen-specify` | 编写功能规格。 | 评审团：三个并行草稿（用户、架构师、拒绝视角）加上一个对抗性审查者，然后进行综合。 | | `/mergen-clarify` | 在进行规格说明工作前提出有针对性的问题。 | 有针对性的提问循环，最多 5 个，答案会被编码返回。 | | `/mergen-checklist` | 应用需求质量核对表。 | 在实现之前进行需求质量核对表（“需求的单元测试”）。 | | `/mergen-plan` | 生成实施计划。 | 并行通道的多方法生成，加上带有反驳倾向的架构批评者，然后进行综合。 | | `/mergen-tasks` | 将计划分解为任务和依赖 DAG。 | 循环直到完备的批评者加上 DAG 构建器。输出 `tasks-dag.json`。 | | `/mergen-analyze` | 在编写代码前检查跨产物的一致性。 | 四个并行的对抗性检查通道，去重处理。 | | `/mergen-implement` | 执行任务列表。 | 从 `tasks-dag.json` 开始的波次并行流水线：为每个任务分配孤立的实现者，然后由一个独立上下文、带有反驳倾向的验证器在标记 `[X]` 之前检查文件系统和测试。失败时重新排队。 | | `/mergen-verify` | 将每个 `[X]` 任务作为独立关卡重新检查。 | 对每个任务进行并行的四视角检查（文件存在、匹配规格、测试通过、git 一致）。多数通过或失败。生成 `verification-report.json`（每个任务带有置信度标签）和 `tasks-state.json`。 | | `/mergen-rollup` | 将功能规格综合为规范的项目状态。 | 并行的读取通道加上冲突裁决，写入 `.specify/memory/project-state.md`。 | | `/mergen-go` | 将请求路由至 Governor 选择的层级。 | 执行 Governor 的层级（tiny/standard/spec/high-trust），并添加高信任度的人工检查点。 | | `/mergen-lean` | 审查 diff 或代码库是否存在过度设计。 | 并行的逐文件审查者，去重后形成一个排名的删除列表（`delete`/`stdlib`/`native`/`yagni`/`shrink`）。仅针对复杂性，绝不涉及正确性。 | | `/mergen-debt` | 跟踪被推迟的捷径。 | 按风险带将 `mergen:` 注释提取到 `.specify/memory/debt.md` 中。关卡模式会在任何没有明确上限的捷径上失败。 | ## 是证明，而非断言 实现者勾选的复选框只是假设，而非证据。Mergen 将其视为需要被反驳的事物。`/mergen-verify` 会在单独的上下文中，以相反的目标重新检查每一个 `[X]` 任务，对照真实的文件系统和真实的测试，并生成 `verification-report.json`，以便对结果进行测量和审计。评估证据指标（`eval/evidence_metric.py`）会读取该 JSON 并报告工作完成率和虚假完成计数，在没有数据时会如实弃权。值得记住的决策会通过唯一的接缝，以带有来源记录的形式跨越到 mneme（`scripts/mneme_emit.py`，[docs/MNEME-SEAM.md](docs/MNEME-SEAM.md)），而绝不会作为 Mergen 自身的记忆库。 关于对强制执行的诚实态度：prompt 协议是请求，hook 是提醒，而 CI 卡关是拒绝。在会话内，如果不经过验证器，implement 流水线就不会将任务标记为完成，这是强有力的纪律，但并非绝对的锁。Mergen 自身的 CI 守卫的是这个代码库（其测试、漂移关卡、无引用文本关卡），而不是你项目的任务验证。对于你自己的项目，Mergen 将该 CI 卡关作为一个即插即用的工作流（`eval/ci/verify-gate.yml`）连同证据指标的 `--gate` 模式一起提供。添加到你的 CI 中后，当你提交的验证报告显示存在虚假或未经验证的工作时，它将使构建失败。它读取的是提交的产物，因此手动编辑的报告仍然可能通过，最深的保障仍依赖于生成该报告的验证器。Mergen 从不模糊这三者。 ## Spec Kit 选项 如果你使用 GitHub Spec Kit，`./install.sh --speckit` 会在 `dist/speckit/` 下渲染一个预设和扩展。 **预设**（`dist/speckit/preset/mergen/`）：覆盖 8 个原生的 Spec Kit 命令（`constitution`、`specify`、`clarify`、`checklist`、`plan`、`tasks`、`analyze`、`implement`）。 **扩展**（`dist/speckit/extensions/mergen/`）：添加7 个原生 Spec Kit 中不存在的命令。 | 添加的命令 | 用途 | |---|---| | `speckit.mergen.govern` | Governor（风险层级分类） | | `speckit.mergen.verify` | 并行虚假完成关卡，生成 JSON 证据 | | `speckit.mergen.rollup` | 规范的项目状态综合 | | `speckit.mergen.go` | 层级执行器和路由器 | | `speckit.mergen.lean` | 过度设计审查（删除列表，仅针对复杂性） | | `speckit.mergen.debt` | 延迟捷径的债务账本 | | `speckit.mergen.agent` | Mergen Agent（单入口点生命周期编排器） | 扩展程序使用 `optional: false` 配置了 `hooks.after_implement -> speckit.mergen.verify`，从而使验证成为 Spec Kit implement 流程中的强制性步骤。这就是在会话中得到强化的 hook 契约。针对你的项目进行的 CI 检查将使其成为真正的关卡。Spec Kit 在这些命令接口之外的行为没有被修改或复制。 ## 极简主义（lazy ladder） 最高级别的努力存在一个失败模式：过度构建。一个本应是 `` 的请求最终可能会生成超出任务所需的代码。Mergen 通过借鉴 [`DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail)（MIT，已在 [ATTRIBUTION.md](ATTRIBUTION.md) 中注明）的极简主义原则来解决这个问题。 该原则就是 [`core/lazy-ladder.md`](core/lazy-ladder.md) 中的 lazy ladder。在编写代码之前，请在第一个能站得住脚的阶梯处停下：是否真的需要它，然后是 stdlib，然后是原生平台特性，然后是已安装的依赖项，然后是一行代码，最后是能工作的最简代码。验证、安全性、可访问性、错误处理和测试绝不能被牺牲。一句话概括其核心论点：**穷尽思考，极简构建，验证其有效且极简。** 同样的克制也指导着文档撰写，这就是为什么 Mergen 更喜欢简单的句子和删除列表，而不是重写。 它在生命周期中的 `plan`（倾向于使用 stdlib 和原生特性而非新的抽象）、`implement`（Stage B 验证器会拒绝正确但构建过度的任务）、`lean`（排名的删除列表）和 `debt`（收集延迟的捷径，使得一个上限明确的权宜之计不会因为默许而成为永久存在）阶段发挥作用。该原则，并且只有该原则，可以通过 `python dist/agents/build_agents.py ` 移植到非 Claude 智能体上，该命令将阶梯原则渲染到 `AGENTS.md`、`.cursor/rules/`、`.windsurf/rules/`、`.clinerules/`、`.github/copilot-instructions.md` 和 `.kiro/steering/` 中。Workflow 编排的 SDD 引擎是 Claude Code 专有的，不予移植。 ## 仓库布局 ``` MERGEN.md the charter (what Mergen is and commits to) MERGEN_PRINCIPLES.md principle-to-component map PROVENANCE.md lineage and the identity transform effort-mode/ commands/mergen.md /mergen slash command (arm, disarm, print /effort max) hooks/mergen_prompt_hook.py UserPromptSubmit hook (fail-soft, no-op when disarmed) scripts/patch_settings.py idempotent, BOM-safe settings.json patcher install.sh / install.ps1 effort-mode-only installers core/ commands/ 15 SDD command source files (single source) lazy-ladder.md the minimalism discipline (single source) schemas/ JSON schemas: verification-report, tasks-state, governor-decision templates/ 7 templates (5 vendored MIT, 2 mergen additions) scripts/bash/ powershell/ vendored MIT helper scripts hooks/ verify_gate.py, constitution_inject.py (reinforcement nudges) CONVENTIONS.md single-source / two-renderer contract dist/ native/build_native.py renders core/ to ~/.claude/skills/mergen-*/ native/patch_settings_hooks.py registers the two SDD hooks (BOM-safe) speckit/build_speckit.py renders core/ to spec-kit preset + extension speckit/preset/mergen/ committed preset output (8 command overrides) speckit/extensions/mergen/ committed extension output (7 new commands) agents/build_agents.py renders lazy-ladder.md to non-Claude passive rule files scripts/ check_sync.py drift gate: committed dist/ matches a fresh render of core/ check_no_reference_text.py fails the build if reference-prompt fingerprints appear mneme_emit.py the mneme seam (verification report -> decision record) eval/evidence_metric.py minimal honest metric (work-done rate, phantom count) from verify JSON install.sh / install.ps1 root installers (all three steps) docs/ HOW-IT-WORKS, SDD-SUPERSET, ROADMAP, MNEME-SEAM LICENSE / NOTICE / ATTRIBUTION.md Apache-2.0 and third-party attribution ``` ## 状态 v2.0.0，测试版。首个标记的公开发布（见 `CHANGELOG.md`）。 - 原生 shell：作为 Claude Code skills 安装的 15 个 `/mergen-*` 命令，加上 effort 模式的 hook 和命令。 - Spec Kit shell：一个覆盖 8 个命令的预设，加上添加了 7 个（`verify`、`rollup`、`go`、`lean`、`debt`、`govern`、`agent`）命令的扩展。 - Governor 通过确定性的高信任度底线设定经过风险校准的流程。 - 机器可读的验证（`verification-report.json`、`tasks-state.json`）和一个最小的评估证据指标。 - mneme 接缝是双向且无需网络的。`scripts/mneme_emit.py` 生成并读取决策记录，而 `--write DIR` 将其持久化到你指定的目录中，并带有密钥编辑预检（遇到密钥时安全失败）和重复检测。完整的存储集成（直接 vault 写入还是 MCP）被刻意留有开放余地。 - verify-gate 作为一个即插即用的 CI 工作流（`eval/ci/verify-gate.yml`）附带一个 `--strict` 卡关（合并关卡：工作完成检查加上完整性 lint）一起提供，因此你的项目可以因为虚假、未验证、模棱两可、空白或未签名的高信任度工作而使构建失败。提交报告的工作流检查已提交的报告，而 `eval/ci/verify-gate-live.yml` 首先从实时树重新生成报告，以实现防篡改的关卡。 - 验证测试套件不依赖于特定的智能体。`scripts/verify_core.py` 是纯标准库，可以在任何运行 Python 3.9 或更高版本的地方运行，无需 Claude Code、无需网络、也无需模型。直接运行它或作为 `mergen verify` 运行。一个完整的端到端运行示例在 [`examples/verify-demo/`](examples/verify-demo/README.md) 中，哪些功能需要哪种运行时在 [docs/COMPAT.md](docs/COMPAT.md) 中有详细映射。 - 每份报告都带有来源信息和防篡改的伴随文件。`--out` 会在报告旁边写入一个 `.sha256`，而 `mergen verify --check-manifest ` 会重新检查哈希值以捕获被编辑过的报告。如果加上 `--require-fresh`，它还会拒绝其记录的源提交不再与当前树匹配的报告。 - 一个静态的、离线的仪表板。`mergen dashboard `（或 `python scripts/dashboard.py `）在一个报告目录上渲染出一个自包含的 HTML 页面，显示每个判定、虚假计数和来源信息，所有值都经过了 HTML 转义。没有网络，没有 JavaScript。 - 未声称有任何实况模型基准测试数据。确实在 `eval/` 下附带了一个确定性的虚假检测套件（`eval/benchmark.py --gate`），并包含其方法论和复现步骤。 - `/effort max` 每次会话需要手动粘贴一次。二进制文件没有将此控制权暴露给 hooks。 - Hooks 是强化提醒。强制执行是由 implement 流水线的对抗性验证阶段完成的，并通过 CI 使其成为真正的关卡。 延伸阅读：[MERGEN.md](MERGEN.md)、[docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md)、[docs/SDD-SUPERSET.md](docs/SDD-SUPERSET.md)、[docs/COMPAT.md](docs/COMPAT.md)、[docs/ROADMAP.md](docs/ROADMAP.md)、[docs/MNEME-SEAM.md](docs/MNEME-SEAM.md)。 ## 许可证 Apache License 2.0。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。

标签：AI合规, AI智能体, Blue Team, SOC Prime, 任务执行框架, 工作流编排, 应用安全, 开发工具