xcrft/mastermind

# Mastermind

**Mastermind 让编码 agent 根据你的真实代码来验证其声明，而不是仅凭记忆。** 它包含两部分： 1. **mmcg — 本地 codegraph。** 一个快速的 Rust 索引器将你的 repo 转换为由符号、调用和导入组成的可查询图，并通过 MCP 提供给 agent。*`parseConfig` 存在吗？谁调用了它？如果我修改它会有什么影响？* —— 答案来自索引，而非猜测。 2. **基于此构建的 spec 驱动 agent 工作流。** planner 编写 spec，executor 进行实现，而确定性门控在执行前后验证每一项声明 —— 这样就不会有产生幻觉的函数和无声的范围蔓延进入你的分支。 ## 快速开始 需要 Node.js 24+。无需 Rust 工具链。 ``` npm install -g @xcraftmind/mastermind mastermind install # workflow agents + skills + MCP → Claude Code (global, once) cd your-project mastermind init # build the codegraph index for this repo mastermind doctor # verify — should be all green ``` 重启 Claude Code 并提问“谁调用了 `parseConfig`？” —— 答案将来自 codegraph。 [其他安装方法 ↓](#install) ## mmcg — codegraph 一个 Rust 二进制程序，通过 tree-sitter 解析**九种语言**（Python、TypeScript/TSX、JavaScript/JSX、Rust、C#、Go、Java、PHP、C/C++），将其存入本地 SQLite 数据库，并通过 MCP 回答结构化问题 —— **20 个只读工具**： | 询问 | 工具 | |---|---| | 符号 X 是否存在？ | `mmcg_search` | | 什么调用了 X？ | `mmcg_callers` | | 修改 X 的影响范围？ | `mmcg_impact` | | 什么导入此路径？ | `mmcg_imported_by` | | 此分支相较于 main 增加了什么？ | `mmcg_symbols_changed_since` | | 依赖循环？死代码？ | `mmcg_dependency_cycles` · `mmcg_unreferenced` | 全部 20 个：`mmcg_search` · `mmcg_callers` · `mmcg_callees` · `mmcg_impact` · `mmcg_imports` · `mmcg_imported_by` · `mmcg_symbols_in_file` · `mmcg_outline` · `mmcg_files` · `mmcg_api_surface` · `mmcg_unreferenced` · `mmcg_dependency_cycles` · `mmcg_symbols_changed_since` · `mmcg_centrality` · `mmcg_change_class` · `mmcg_recent_changes` · `mmcg_tasks` · `mmcg_status` · `mmcg_scratchpad_append` · `mmcg_scratchpad_read`。精度说明：[`mcp/servers/mmcg/README.md`](mcp/servers/mmcg/README.md)。适用于任何 MCP stdio 客户端（Cursor、Continue、自定义客户端），不仅限于 Claude Code。 它特意做得非常聚焦 —— 一个语法图、只读、无 daemon、零系统依赖。定点查询是亚毫秒级的；全图聚合（中心度、影响、循环）的规模随 repo 大小而定。在查找“谁调用了谁”时，它比 grep 更快、更精确，而且与 LSP 不同，它可以轻松地进行快照并供 agent 查询。 **不仅仅是一个 MCP server。** MCP 只是一个表面；同一个 `mastermind` 二进制程序是工作流的引擎。确定性门控（`verify-spec` / `audit-spec`）直接读取索引，`init` / `doctor` 为项目搭建脚手架并进行健康检查，而 **miner** 派生出工作流可以消费的跨 repo 信号 —— 例如，`miner profile` 将你的代码风格特征（“像我一样写代码”）学习到 `~/.mastermind/style.md` 中，供 planner 进行参考编写。 ## 工作流 一个流水线，其中 **planner 从不实现，executor 从不即兴发挥：** ``` flowchart TB U([User]) --> Ref[Intake Refiner • Sonnet] Ref -->|clean brief| P[Planner • Opus] P -.->|stress-test design| C[Critic • Opus] P -.->|gather facts| R[Researcher • Haiku] P -.->|unknown-cause bug| I[Investigator • Sonnet] P -.->|security-sensitive scope| S[Security Auditor • Opus] P -->|spec| E[Executor • Sonnet] E -->|report| A[Auditor • Opus] A -.->|held / drift / broken| P M[(mmcg codegraph)] P --- M E --- M A --- M ``` Critic（在 spec 之前）和 auditor（在执行之后）作为没有先前上下文的独立 Opus 实例运行 —— 它们能捕捉到 planner 自身的偏见。 ### 门控使其具有确定性 每个 spec 都由直接读取 mmcg 索引的 Rust 门控检查 —— 结论是无法通过争辩改变的： - **`verify-spec`**（执行前）—— spec 中的每个符号都存在，每个文件都在磁盘上，必填部分均已填写，FIND 块未过期。 - **`audit-spec`**（执行后）—— 没有范围蔓延，没有相较于编辑前快照的签名漂移，没有静默移除的符号，计划的测试确实已添加。 子 agent 也会查询 mmcg，但那是 LLM *解读*结果 —— 很有用，但不是绝对的保证。**对于正确性，请信任门控；对于速度和广度，请信任子 agent 对 mmcg 的使用。** ### 示例：捕获产生幻觉的函数 executor 报告： ``` [x] Added CancelOrder() to pkg/checkout/checkout.go [x] Wired it to the existing ProcessPayment() for the refund flow VERIFY: go test ./pkg/checkout/... — PASSED ``` auditor 对实时的索引运行了 `mmcg_search ProcessPayment` → `{ "count": 0 }`。`ProcessPayment` 从未存在过；executor 捏造了一个对它的调用点。结论：**契约破裂** —— 被图谱抓到了，而不是通过重新阅读代码。 ## 内部包含什么 ``` Core mcp/servers/mmcg/ the mmcg core binary — codegraph (20 MCP tools, 9 languages), deterministic CLI gates, and miners (author style profile) Workflow (installed into ~/.claude/ by `mastermind init`) agents/subagents/ prompt-refiner · critic · researcher · investigator task-executor · auditor · security-auditor agents/claude-md/ CLAUDE.md + CONTEXT.md templates skills/workflow/ task-planning · task-executor · codegraph-research structured-report-contract · critical-review skills/debugging/ investigation-ledger skills/security/ agent-security-review (OWASP ASI reference pack) skills/prompt-engineering/ prompt-refiner (intake gate) skills/coding/ no-ai-slop-comments Proof evals/ adversarial eval suites — critic · auditor (real git fixtures) · intake + ablation study (vanilla vs mastermind catch-rate) ``` 共享的契约 —— codegraph 查询、executor↔auditor 报告格式、调查循环 —— 都位于 skills 中，因此每个 agent 都能读取同一个来源。非核心工件（pr-review、flaky-finder、doc-stub-sync 等）位于 [`extras/`](extras/) 中，默认不安装。 ## 安装 以**通过 npm 提供的预构建原生二进制文件**形式发布 —— 无需 Rust 工具链。 **全局**（推荐） ``` npm install -g @xcraftmind/mastermind mastermind setup claude --write-mcp ``` 在 Claude Code 用户作用域注册 `command: "mastermind"`（写入 `~/.claude.json`）。 **项目本地**（版本锁定） ``` npm install -D @xcraftmind/mastermind npx mastermind setup claude --project . --write-mcp ``` 写入 `./.mcp.json` 并指向 `./node_modules/.bin/mastermind`。 **一键设置** —— `npx @xcraftmind/mastermind install` 将子 agent 和 skills 复制到 `~/.claude/` 中，并注册 mmcg MCP。然后在项目中运行 `mastermind init` 来构建 codegraph 索引。`list` 显示包含的内容；`update` 刷新 agent。 **支持的平台：** macOS (arm64/x86_64)、Linux glibc & musl/Alpine (x86_64/arm64)、Windows (x86_64)。其他目标平台：`cargo install mmcg`。

从源码构建（Rust 1.75+）

``` cargo install mmcg # from crates.io cargo install --path mcp/servers/mmcg # from a clone ``` 相同的二进制程序 `mmcg`，相同的子命令。

## 命令 ``` mastermind install # workflow agents + skills + MCP → Claude Code (global, once) mastermind update / list # refresh the workflow bundle · show what ships mastermind init # scaffold .mastermind/, build the index, draft CONTEXT.md mastermind watch # keep the index live as you edit mastermind doctor # fail-soft health checks (add --json for CI) mastermind status / next # task list + health · single next step mastermind new-spec "..." # create a task spec (--mode lite|standard|strict) mastermind resume # paste-into-Claude prompt for the current phase mastermind verify-spec # pre-execution gate mastermind audit-spec # post-execution gate mastermind miner profile # learn your code-shape style → ~/.mastermind/style.md mastermind uninstall --scope all # tear it down (dry-run unless --force) ``` **保持在本地。** SQLite 索引由 tree-sitter 从你的文件中构建，永远不会离开你的机器。`install` / `init` 将工作流包写入 `~/.claude/{agents,skills,commands}/`，而 `setup` 在 `~/.claude.json` 中注册 MCP server —— 全部在本地，除了 npm registry 之外没有其他网络连接。完全离线：`mastermind init --no-claude --no-index --no-global`。将 `.mastermind/` 添加到 `.gitignore` —— 这是本地的工作状态。 ## 贡献 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md) —— 项目布局、需要运行的检查以及如何发起 PR。 ## 许可证 MIT —— 参见 [`LICENSE`](LICENSE)。

标签：AI编程助手, IPv6支持, MCP, MITM代理, Rust, SOC Prime, 代码审查, 代码知识图谱, 可视化界面, 工作流自动化, 开发工具, 网络流量审计, 通知系统