misterdev

misterdev

自主大模型构建编排器：将目标规划为任务，使用锚定式 SEARCH/REPLACE 编辑代码，并在报告完成前通过构建/测试/lint/类型检查关卡验证每项更改。可作为 CLI 或 MCP 服务运行。

将代码仓库和目标交给 misterdev。它会将代码库读取为符号图，将目标拆解为具体任务，并通过“尝试编辑—验证”循环逐一处理：生成锚定式 SEARCH/REPLACE 编辑，在磁盘上的文件中应用更改，然后依次通过一系列正确性关卡——构建、测试、lint、类型检查，以及你启用的任何可选关卡。关卡失败并标为 RED 时会阻止更改；没有可检查内容的关卡则会 SKIP，且不会阻止更改。如果更改导致测试套件退化，misterdev 会通过 git 回退更改。只有持续通过所有关卡的更改才会合并。

$ misterdev build . "add rate limiting to the public API"

  planning   goal → 3 tasks  (model: anthropic/claude-sonnet-4-6, budget $100.00)
  task 1/3   middleware: token-bucket limiter          api/limiter.py
    edit     1 hunk applied · syntax ok
    gates    build GREEN · tests GREEN (142 passed) · lint GREEN · typecheck GREEN
  task 2/3   wire limiter into request pipeline         api/app.py
    edit     2 hunks applied
    gates    build GREEN · tests RED (1 failed) → rolling back, regenerating
    edit     2 hunks applied (attempt 2)
    gates    build GREEN · tests GREEN (145 passed) · lint GREEN · typecheck GREEN
  task 3/3   docs + config surface                      README.md, config.py
    gates    all GREEN

  done       3/3 tasks · 145 tests green · $0.38 over 11 calls

misterdev 只信任其关卡，因此这个循环是可靠的：“模型说已经完成”永远不是终点——真正的标准是构建、测试和差异。

安装

pip install misterdev
# or
uv pip install misterdev

支持 Python 3.10 – 3.13。可选扩展能增加功能，同时避免核心安装臃肿：

pip install 'misterdev[local-embeddings]'   # offline semantic context ranking (fastembed, no API key)
pip install 'misterdev[lsp]'                 # LSP semantic-diagnostics gate
pip install 'misterdev[web]'                 # headless-browser web verification gate (+ playwright install chromium)
pip install 'misterdev[mcp]'                 # Model Context Protocol tool-host substrate

所有扩展均为可选启用，并设有超时限制。如果扩展所需的运行时依赖不存在，它支持的关卡会 SKIP，而不会失败。

功能

自主构建循环

为 misterdev 提供目标，它便会驱动整个周期：分析项目、规划任务、编辑并验证——不断重复，直到达成目标或预算耗尽。编辑采用锚定式 SEARCH/REPLACE代码块：模型只生成发生更改的区域，并在磁盘上的文件中应用，因此无需重新输出一个 5,000 行的模块，也不会触及输出 Token 上限。匹配时会先尝试精确匹配，然后容忍空格和缩进差异，同时始终要求锚点唯一，确保不会写入不完整的文件。

多语言符号图上下文

基于 tree-sitter 的符号图让 misterdev 能够理解 Python、Rust、TypeScript/JavaScript、Go、Java、C/C++、C#、Swift 和 Kotlin 的代码结构。每个文件的概要和整个项目的结构图会为规划和编辑提供上下文；对于大型文件，则会提供符号概要和与任务相关符号的原文窗口——因此上下文和成本取决于编辑内容，而非文件大小。

正确性关卡

每项更改都会依次通过一系列关卡：构建 → lint → 测试 → 类型检查，还可叠加可选关卡——对抗式评审器（在应用每个差异之前，由一个独立的第二个模型进行审查）、目标检查、声明验证器、变异评分、运行时冒烟测试、Web 和 视觉验证。关卡失败并标为 RED 时会阻止更改；没有可检查内容的关卡则会 SKIP，且不会阻止更改。退化会通过 git 回退，因此工作树只会向前推进。

动态模型选择

misterdev 为每个模型维护一份性能账本，并将其与成本感知型选择器配合使用，从 OpenRouter 的全部模型中挑选性价比最高的模型——将每项任务沿着能力阶梯逐级路由（收集到的免费 / 低价模型 → 强大的中端模型 → 前沿模型），并且只有在较便宜的模型无法通过门槛时，才升级到更强的模型。最强的模型层级仅用于最后一次尝试，因此前沿模型的支出是罕见的安全保障，而非默认选择；中端模型无法解决的困难任务会交由前沿模型完成，而简单任务则由免费 / 低价模型处理。质量绝不会下降，因为表现不佳、写出糟糕代码的弱模型无法通过门槛，策略便会升级。它通过自动故障转移运行于 OpenRouter 或 Anthropic，会缓存响应以避免重复付费，并通过令牌预算确保支出不超出你设定的上限。

并行工作树

彼此独立的任务会并发运行，每项任务都拥有自己的隔离 Git 工作树，因此互不依赖的工作不会争用同一棵工作树。集成门槛会针对完整测试套件重新检查每一波任务，并回退任何导致回归的任务——实现并行处理，同时避免相互影响。

自我改进

misterdev 会持久记录自身真实故障的指纹化流，并在自身源码上运行 AlphaEvolve 式的「保留更优版本」循环：它会分析故障原因，将原因归类为 测试框架产物、观察盲区或能力不足，提出有针对性的结构性自我修改，并且只有当修改在从未用于优化的留出任务集上胜过当前最佳版本，且没有任何回归时，才会晋升该修改。防止奖励欺骗的防护措施会隔离测试和基准。最终，这个循环能随着时间推移消除整类故障，同时避免对任何单一基准过拟合。参见 docs/path-to-100.md。

使用 misterdev evolve --benchmark <polyglot-benchmark checkout> --workdir <scratch dir> 运行（默认是试运行；添加 --live 可实际应用、门控并晋升，添加 --from-failures 可针对真实构建故障流，而不是基准中表现最差的细分领域）。在 project.yaml 中设置 evolution.benchmark_dir/evolution.noise_band 可指定默认值，这样调用方就能省略对应的标志；两者都是可选项，默认均未设置。evolve_async MCP 工具可在后台运行同一流程（使用 job_status 轮询）。配置仓库密钥 OPENROUTER_API_KEY 后，.github/workflows/evolve.yml 也会运行每晚一次的 --scheduled --live --from-failures 流程——它受同一排他锁和熔断器保护，因此重叠或反复失败的触发都会直接无操作退出。

在正确性方面，misterdev 采用复现优先的方式：对于由问题驱动的任务，它会根据验收标准生成失败测试，验证该测试在干净的代码树上确实会失败（无法复现任何问题的测试会被丢弃，而不是被信任），然后推动修复，直到测试通过——这样模型会朝着具体且经过验证的目标修改，而不是只依据描述行事。

双时间尺度演进（已构建；通过 orchestrator.runtime_tooling opt-in；参见 docs/two-timescale-evolution.md）将自我改进能力拓展到无记忆运行时 Agent 无法达到的程度。在运行时，模型可以编写小型的任务专用辅助工具，并在沙箱中运行（采用经过强化且无网络连接的容器；不可信代码绝不会接触主机或仓库；若没有容器引擎，此项能力会自动停用）；工具的输出会用于指导修改。之后，每个新编写的工具都会连同任务结果一起存入工具语料库——这是正常运行自然产生的副产品；再通过专门的晋升流程，将那些在留出任务拆分上取得的成功具有泛化性的工具（基线取自复现语料库）纳入持久化的能力最佳工具库，供后续运行一开始就使用。快速循环负责发明；慢速循环只保留优胜者；保护框架自我修改的同一留出集门控机制，也能确保工具库具有通用性，而非对基准过拟合。能力会在多次运行中持续累积，而不是每个任务都从头发明——这是当前主流开源框架所缺少的记忆。使用 python -m misterdev.core.evolution.tool_promotion <project> 运行晋升流程。

可扩展性

工具、门控和目标通过 Python 入口点自动注册。pip install misterdev-plugin-x 即可添加功能，无需修改核心代码——misterdev 会在运行时发现入口点并接入。可在 examples/misterdev-plugin-hello 查看可运行示例。参见 扩展 misterdev。

Agentic MCP

misterdev 可以连接 Model Context Protocol 服务，让模型在构建过程中调用发现的工具——功能有界、需显式启用，并受工具允许列表约束。传输方式包括 stdio 和带身份验证的远程 streamable-http，因此你可以将其指向像 Glama 这样的托管 MCP 网关，让构建流程使用整套工具目录，而无需在本地运行任何工具。

基准测试

在 Aider 的多语言基准测试 上通过 Gate 验证的 pass@1（Exercism 练习，带隐藏测试套件），使用 anthropic/claude-sonnet-4-6：

语言	已解决	比率
JavaScript	9 / 10	90%
Python	8 / 10	80%
Rust	7 / 10	70%

持续压力测试运行中，三个语言的练习已全部解决，达到 20/20 且零失败，包括通常被认为较难的练习（保龄球、forth、任意精度十进制）。每个解答都由练习自身的隐藏测试进行评判，而非由模型自行判定。完整数据、方法和复现方式：docs/benchmark-results.md。测试套件：1,941 项通过 — docs/TESTING.md。

CLI 参考

不想记住各种标志？ 只需描述你想做什么——无需设置项目 或 devplan。misterdev 会顺畅地为你处理：

$ misterdev "add rate limiting to the public API"
  ⠸ Building…

动作词（add、fix、implement、write、create 等）会直接进入 构建流程——不调用 LLM 进行路由、不要求确认，也没有繁琐步骤。查询和 管理词（list、status、what、how、check、run 等）会通过模型调用 进行映射，显示预览，并在执行任何会修改内容的操作前征求确认：

$ misterdev "check what's broken and fix it cheaply, run in parallel"
  → I'll run: misterdev build . fix broken tests --budget 5 --parallel
    proceed? [Y/n]

以下基于标志的命令仍可用于脚本和高级用户。 misterdev 命令可驱动所有操作：

命令	功能
misterdev scan <dir>	发现目录下的项目并注册。
misterdev list	列出所有已注册的项目。
misterdev status [path]	显示项目的任务及其状态。
misterdev report [path]	汇总最近一次构建的成本/令牌数、各模型的账本表现以及审计跟踪。只读——不会重新运行任何操作。
misterdev run [path]	运行待处理的任务；如果提供的是目标而非路径，则重定向到 build。--dry-run、--force、--status。
misterdev plan [path]	分析项目、推荐工作并以交互方式编制计划。--budget、--no-rollback。
misterdev build [path] [goal]	自主构建/调试/完成工作流。如果直接给出目标，path 默认为 .。请参阅下方标志。

不带子命令运行 misterdev 会启动交互式规划。

misterdev build 标志

标志	效果
--budget <float>	本次运行的最高美元预算（默认值为 100）。
--commit	每完成一项任务后提交。
--parallel	在隔离的工作树中并发执行独立任务。
--dry-run	仅规划；显示任务但不执行。
--interactive、-i	在任务之间等待确认。
--no-verify	跳过最终验证阶段。
--no-suggest	跳过 suggest 扫描。
--no-rollback	禁用对导致性能退化的任务自动二分定位/回退。
--focus <area>	将工作限制在特定领域。
--allow-dirty	允许在存在未提交更改的情况下构建。
--max-tasks <n>	限制本次运行规划/执行的任务数（控制成本）。

prompt 可以是自由文本或模式词——debug、complete、review 或 new <description>。

## 通过 AI 客户端驱动（MCP 服务）

misterdev 还以 MCP 服务（misterdev-mcp）的形式提供，因此你可以通过 Claude Desktop、Claude Code、Cursor 或任何 MCP 客户端用自然语言驱动它——无需记住任何标志。客户端只需调用工具（build、scan、status、list_projects、run）；整个编排都在 misterdev 自己的进程中运行，使用它自己的模型和上下文预算，只有简短摘要会返回给客户端——你的代码库绝不会进入客户端的上下文窗口。

// Claude Desktop config (claude_desktop_config.json)
{
  "mcpServers": {
    "misterdev": {
      "command": "misterdev-mcp",
      "env": { "OPENROUTER_API_KEY": "sk-..." }
    }
  }
}

然后只需提出要求：“让 misterdev 为 API 添加速率限制，费用控制在 $5 以内。” 修改类工具（build、run）会拒绝在工作树不干净时运行，并采用保守的默认预算。

Claude Code 集成。 build 工具接受 spec_text 参数。传入由 Claude 编写的完整规格说明后，misterdev 会跳过自身的分析和规格生成阶段，直接使用你代码库自己的门禁套件执行分解 → 执行 → 验证。Claude 负责设计；misterdev 负责执行、正确性门禁和回滚：

# In Claude Code / MCP client
misterdev.build("/path/to/repo", spec_text="""
Feature: add a token-bucket rate limiter to /api/v1/*
...full spec...
""")

需要 mcp extra：pip install 'misterdev[mcp]'。

扩展 misterdev

插件是普通的 Python 包，在 misterdev.* 组中声明入口点。安装后，misterdev 就会自动加载，无需修改核心代码。

工具是一个类；门禁是一个返回 GateOutcome 的可调用对象：

# misterdev_plugin_hello.py
from misterdev.core.execution.outcomes import GateOutcome, GREEN, RED


class HelloTool:
    gather_safe = True  # opt into the agentic gathering loop
    gather_description = "Return a friendly greeting for a name."

    def __init__(self, config: dict):
        self.name = config.get("name", "hello")

    def execute(self, project, name: str = "world", **_ignored):
        return True, f"Hello, {name}!"


def no_shouting_gate(ctx) -> GateOutcome:
    build = (ctx.commands or {}).get("build_command") or ""
    if build and build.isupper():
        return GateOutcome(RED, "build_command is ALL CAPS; please calm down")
    return GateOutcome(GREEN)

# pyproject.toml — the entry points are the whole contract
[project.entry-points."misterdev.tools"]
hello = "misterdev_plugin_hello:HelloTool"

[project.entry-points."misterdev.gates"]
no_shouting = "misterdev_plugin_hello:no_shouting_gate"

目标也通过 misterdev.targets 组以相同方式注册。完整且可运行的示例（包括工具、门禁、pyproject.toml 和说明）位于 examples/misterdev-plugin-hello。

配置

在目录中首次运行 misterdev 时，会自动创建 project.yaml，无需任何设置即可开始使用。在仓库根目录中放入自定义配置，即可指定构建、测试和 lint 命令、模型、预算及门禁。

name: "My App"
language: "python"
build_command: "python -m compileall -q ."
test_command: "pytest -q"
lint_command: "ruff check ."
llm:
  provider: "openrouter"            # openrouter | anthropic
  model: "anthropic/claude-sonnet-4-6"
  api_key_env_var: "OPENROUTER_API_KEY"

关键配置项：

• 模型与预算 — llm.model、提供商/故障转移设置，以及运行的美元费用上限（也可通过 --budget 设置）。
• 门禁 — 可选门禁（对抗式评审、变异、运行时冒烟测试、Web、视觉、目标检查）默认关闭，可在 orchestrator.* 配置项下启用。
• MCP — 在 mcp.servers 下声明服务，并通过 orchestrator.mcp_enabled / orchestrator.mcp_tool_use 启用工具使用；连接到远程网关以获取托管工具目录。
• 目标 — targets: 块可为多语言单体仓库指定各语言的构建、测试和 lint 配置，并按任务路由。

指南：入门 · 配置 · 插件 · MCP。project.yaml.example 介绍了每个配置项。

要求

• Python 3.10 – 3.13
• git（每个任务分支、工作树和回滚都通过它执行）
• OpenRouter 或 Anthropic 的 API 密钥
• 各门禁所需的可选工具链——Web 门禁需要 Playwright 浏览器，LSP 门禁需要语言服务器，工具托管基底需要 MCP SDK（均通过对应的 extra 安装）

开发

git clone https://github.com/dcondrey/misterdev
cd misterdev
uv sync
uv run ruff check .
uv run pytest -q

欢迎贡献——请参阅 CONTRIBUTING.md，并在 GitHub 上提交 issue 或拉取请求。

许可证

misterdev 采用双许可证：

• AGPL-3.0-or-later — 根据 GNU Affero 通用公共许可证的条款，可免费用于开源项目。
• 商业许可证 — 可用于闭源或专有产品，无需遵守 AGPL 的义务。

请选择适合你项目的许可证。

---

由 David Condrey 构建 · github.com/dcondrey/misterdev
_{静态标志文件位于 assets/logo.svg。}