一个跑在终端里的软件工程 Agent:你用自然语言下达开发任务,它自己读代码、改文件、跑命令、看测试结果,反复直到做完或者明确说清楚它卡在哪。
它不是一个"调 API 的 demo 骨架",而是一套可验证闭环:核心循环、权限边界、工具层、会话轨迹、评测证据,每一层都有测试或独立判据撑着。项目按 SPEC.md 与 SPEC-v2.md 逐阶段实现,SPEC 的决策记录(v1 的 D1–D8、v2 的 D9–D27)解释了每个取舍的原因。
下面这段是 demos/results/codegen.fake.md 里的真实终端输出(Demo 1,任务只有一句话:"创建一个 Python 计算器项目,并编写测试"):
你 > 在当前目录创建一个 Python 计算器项目……写完整的 pytest 测试并跑到全绿
✓ write_todos 4 步
任务清单
[~] 建 calculator 包:四则运算 + DivideByZeroError
[ ] 加 evaluate:乘除优先于加减
...
✓ write_file calculator/core.py
✓ write_file tests/test_calculator.py
✓ run_tests 863ms ← 红了
`2 + 3 * 4` 得到 20,说明我按从左到右一路算了。改成两遍扫描:先折叠乘除,再算加减。
✓ write_file calculator/core.py
✓ run_tests 980ms ← 全绿
注意最后那句自我更正:优先级 bug 是测试抓出来的,不是模型看出来的。这就是 run_tests 作为判据而不是装饰的意义。
Python 3.11+(只用标准库 + httpx,不装任何大模型 SDK)· pytest · MCP(stdio,client + server 两端都实现)· Docker 沙箱 · OpenTelemetry / OTLP · Ollama / llama.cpp / vLLM
姊妹项目:insight-agent —— LangGraph 写的可验证 DeepResearch Agent,本仓库通过 MCP 桥调它做真实联动(as-built 见 docs/mcp-link-spec.md)。
git clone https://github.com/magickkdd/MiniClaudeCode.git && cd MiniClaudeCode
python -m pip install -e ".[dev]"
cp .env.example .env # 填你自己的 OpenAI 兼容端点(Anthropic / DeepSeek / OpenAI / Ollama 都行)
python main.py # 进 REPL,或 python main.py --task "把 duration 模块补跨天测试并跑到全绿" -y不装也能跑(python main.py 直进 REPL),离线跑完整个循环与评测:
python -m pytest -q # 871 项测试,FakeLLM 驱动、不联网、不读 .env
python demos/run_demo.py --all --engine fake # 五个 demo 秒级跑完
python -m miniclaude eval --repeats 3 # 24 题离线评测,报一个可被反驳的通过率871 项测试全绿(另有 2 项按设计跳过)。 每一层能力都配了一条"能被反驳"的判据和一个盘上的证据文件;没达成的、没测到的都写在 §9 与 docs/experiments.md 里,而不是从报告里拿掉。
| 交付线 | 判据 | 实到 |
|---|---|---|
| 评测层(B1) | 24 题 × 3 次,报一个可被反驳的通过率 | fake 全批 pass@1=20/24、退出码 0,基线已入库;live 冒烟 6 题 4/6 |
| 上下文压缩(B2) | 阶梯动手 + 配对不变式不破 | 关阶梯第 5 轮死在 l3_refuse,开阶梯 19 轮全绿;因配对破损导致的 400 = 0("成功率 ≥60%"按未量记账,理由见 §4.7) |
| 仓库符号地图(B3) | 轮数中位降 ≥20% 且 token 涨幅 ≤15% | 未达成:token +5.4% ✓、轮数 0% ✗ —— 一次有效的证伪,不是无效实验 |
| 沙箱后端(B6) | 换后端不换结论 | 判定逐格一致 12/12;但本机无 docker,container_isolation_tested: false |
| 第三方能力(S14) | 桥与技能对着敌意 fixture + 官方 SDK 服务 | 20/20 条前提全绿 |
| 轨迹 → RL 数据 | 导出器自证前提 | 13 批次 206 run → 1,034 行,丢弃 0、12/12 前提成立;结论是这批数据不够训 |
| OTLP 导出 | 只翻译、不引 SDK、不丢不编 | 18 条判据 17 ✓ + 1 未量;顺手挖出导出器与证据自身共 5 个谎 |
| 两次"动手前砍单" | 规格写死的砍单条件由数据判 | 只读并发只值 live 墙钟 0.011%、多 Agent 前置条件 1.3% —— 两次都不做 |
每层的完整判据、实到数字与"这一节不证明什么"在 docs/experiments.md(原 §4.7–§4.16,编号不变)。其余文档:docs/reference.md 配置项 / 斜杠命令 / 失败模式标签 · docs/testing.md 逐个测试文件覆盖什么 · docs/spec-deviations.md 35 条 SPEC 偏差 · docs/framework-equivalence.md 与 LangGraph 的对照和不用它的理由 · docs/inference-bench.md 本地三引擎实测 · docs/mcp-link-spec.md 接自研 Research Agent 的契约与 as-built。规格与决策记录在 SPEC.md(v1.0,D1–D8)与 SPEC-v2.md(v2.0 路线图,D9–D27)。
垂直可用:在一台机器上,对着一个陌生 Python 仓库,把"自然语言任务"变成"验证过的代码改动"。四件事必须真的成立:
| 能力 | 怎么被证明 | |
|---|---|---|
| A1 | 在陌生仓库按一句话描述修 bug,修到测试转绿 | demos/results/bug-hunt.*.md、red-tests.*.md:独立跑 pytest 看退出码 |
| A2 | 从零生成一个带测试的可运行模块 | codegen.*.md:独立脚本校验 evaluate 语义,不看模型自述 |
| A3 | 只读模式下能读懂代码并回答"这段对不对" | readonly-qa.*.md:工作区哈希与基线逐位一致 |
| A4 | 需求自相矛盾时在预算内放弃,不谎报成功 | giveup.fake.md:终止原因必须是 max_turns,且没改测试作弊 |
多 Agent、VLM、RL、GUI、大规模 RAG、自动上下文压缩、跨会话记忆。其中两条在 v2.0 被推翻了:自动上下文压缩(S10)与仓库地图/工作记忆(S11)—— 因为先把配对不变式 assert_pairing 做出来才敢压。跨会话的"经验教训"仍然不做:一次错误观察会持续误导后续会话,而它没有判据能把自己纠正回来。
用户 ──▶ cli/ REPL · argparse · 斜杠命令 · Renderer
build_session() 是全项目唯一装配点
│ Agent.run(任务) → AgentResult
▼
agent/ loop.py Ask→Act→Observe · planner.py TodoList · prompts.py
context.py token 估算 · permissions.py 权限门 · state.py 终止原因
ask(model) │ │ invoke(call)
▼ ▼
llm/ base.py 协议 · openai_compat.py tools/ registry.py 注册表
httpx,不装 SDK read/write/edit/search/find_files
bash · run_tests · workspace.py 路径锁
└────────────┬────────────┘
▼
memory/ 工作记忆 + 符号地图 ext/ MCP 桥 · 按需加载的技能
(两者都只经 extra_tools=[…] 注入)
▼
messages.py 报文与 Block · config.py 唯一读环境变量的地方
infra/trace.py JSONL 轨迹 + 密钥脱敏 · infra/otel.py 只做导出映射
三条硬约束(违反就会让测试和 demo 失去意义):
- 单向依赖:
cli → agent → (tools | llm | memory | ext) → messages/config。tools/永远不 importagent/—— 所以write_todos住在agent/todo_tool.py、load_skill住在ext/skills.py,都通过ToolRegistry.default(extra_tools=[...])注入。RemoteTool是普通BaseTool,所以权限门与 trace 为外部能力一行都不用改。 - 一个装配点:
build_session()同时服务 REPL、--task一次性模式和demos/run_demo.py。否则"demo 跑通的东西"和"用户手上跑的东西"就不是同一个东西。 - CLI 层零业务逻辑:没有
while循环控制 Agent,交互归 CLI,控制归agent/loop.py。
需要 Python 3.11+(用到 StrEnum 和 is_relative_to)。
git clone https://github.com/magickkdd/MiniClaudeCode.git && cd MiniClaudeCode
python -m pip install -e ".[dev]" # 只要核心:pip install -e .
cp .env.example .env # 填你自己的端点、密钥、模型名.env 已在 .gitignore 里,任何打印路径都过 Config.redacted(),trace 落盘前过 _scrub(),密钥不可能出现在日志里。不想安装也能跑:python main.py 直接进 REPL。装了之后 mcc、python -m miniclaude、python main.py 三个入口等价。
python main.py # 默认 ask 模式,逐次确认写操作
python main.py --root D:\path\to\repo # 指定工作目录(唯一可写范围)
python main.py -y # auto:工作区内自动放行,破坏性命令仍拒
python main.py --readonly # readonly:只允许只读工具
python main.py -v # 打印轮次分隔线与工具输出摘要
python main.py --task "给 duration 模块补跨天的测试并跑到全绿" -y; echo $?进入 REPL 后直接说人话:tests/test_cart.py 里红的用例修一下,别改断言。--task 与 REPL 走的是同一条 run_turn() 路径,退出码直接来自 AgentResult.succeeded(0 = COMPLETED)。上面那个计算器任务的一次真实运行:4 轮、输入 14,491 + 输出 1,488 tokens、退出码 0;判定方独立复跑工作副本得 29 passed。
| 模式 | 只读工具 | 写/执行 | 破坏性命令 |
|---|---|---|---|
ask(默认) |
放行 | 逐次问你(y 一次 / a 本会话同类都放行 / n 拒绝) |
无条件拒绝 |
auto(-y) |
放行 | 工作区内自动放行 | 无条件拒绝 |
readonly |
放行 | 拒绝 | 拒绝 |
两个不可让的细节:路径锁在 Workspace.resolve 这一层而不在门后面(越界路径根本解析不出可写目标,.. 逃逸一并挡住);确认失败关闭 —— 没有确认渠道时任何看不懂的答复都按拒绝处理,绝不默认放行。
/help /reset /tools /context /todos /trace /exit 是常规的。三个值得单独知道的:/undo 回退到上一个检查点(撤的是磁盘,对话历史不倒带)、/backend 给出执行后端 + 检查点栈 + 会话现场三合一面板、/mcp 列出外部工具"远端自报的风险 vs 我们实际采信的档位"。/mode ask|auto|readonly 切模式。完整 13 条在 docs/reference.md。
Ctrl-C 的语义是放弃当前输入但保留历史:中断不该毁掉已经做一半的工作。
demo 是"4 个案例各跑一次给人看",评测层是"24 道题 × 3 次,报一个能被反驳的数字"。两边的判据是同一份实现(eval/contract.py),所以不存在"评测层顺手放宽了标准"这种分叉。
mcc eval --list # 24 道题各自的模式 / 判据规模 / fake 剧本
mcc eval --lint # 考题自检:这道题**可能**被做对吗
mcc eval --repeats 3 # 默认 engine=fake:秒级、不联网、不读 .env
mcc eval --repeats 3 --save-baseline # 跑完写 eval/baselines/fake-<题集哈希>.json退出码就是结论:0 这批可以拿去汇报;1 有运行崩了 / 有该做对的题没做对 / 检出退步或判据告警;2 用法或配置不对(一格数据都没产生)。几条不是从嘴上来的口径:fake 批次同时是 gold-patch 检查(pass 是代码给的,剧本声称改完了不算);4 道 must-fail 按设计判红,被判绿会占退出码 1;基线按题集哈希自动匹配(改题面就换哈希);|Δ| < 12.5% 一律写"分辨不出"(McNemar 精确二项而不是卡方近似 —— n=24 时卡方恰好把 p 算得偏小)。
真实环境变量优先于 .env。最常拧的几个:
| 变量 | 默认 | 说明 |
|---|---|---|
LLM_BASE_URL / LLM_API_KEY / LLM_MODEL |
必填 | OpenAI 兼容端点、密钥、模型名 |
PROJECT_ROOT |
. |
工作目录,Agent 唯一可写范围 |
MAX_TURNS |
25 | 单次任务最大轮数 |
MAX_TOTAL_TOKENS |
800000 | 累计 token 止损线 |
TOKEN_BUDGET |
32000 | 上下文估算预算 —— 压缩阶梯挂这个 |
CONTEXT_HARD_LIMIT |
200000 | 只防"请求被端点拒收"的独立熔断 |
REPO_MAP |
1 | 设 0 不画符号地图,退回 30 行目录树 |
EXECUTION_BACKEND |
local |
local/docker/auto,默认不是 auto |
MEMORY_DIR |
.mcc |
记忆落盘目录;../outside 这类敌对值启动期拒绝 |
完整 23 项在 docs/reference.md。
上下文压缩、仓库地图、沙箱后端、MCP 桥、轨迹导出、OTLP、本地三引擎、接自研 Research Agent —— 十层能力各有一份"结论 + 实到数字 + 不证明什么",全文在 docs/experiments.md(原 §4.7–§4.16,编号不变)。
模型看到的默认是 9 个工具(7 个住在 tools/,write_todos 住在 agent/todo_tool.py,load_skill 住在 ext/skills.py)。接了 MCP 之后每个远端工具再多出几行。
| 工具 | 风险 | 要点 |
|---|---|---|
read_file |
read | 带行号返回,自动截断。改之前必须先读 —— 提示词里禁止凭猜测编辑 |
search_text |
read | 工作区正则搜索,返回 文件:行号:内容。定位函数/字符串的首选 |
find_files |
read | glob 查文件,跳过 .git/__pycache__/.venv。接手陌生仓库第一步 |
edit_file |
write | 精确匹配 old_string,要求逐字符一致且文件内唯一。最推荐的编辑方式 |
write_file |
write | 新建或整体覆盖。覆盖已存在文件前必须先 read_file |
bash |
execute | 工作区根目录执行,返回退出码 + 合并输出。Windows 下优先走 Git Bash |
run_tests |
execute | 跑 pytest 并结构化返回:通过/失败计数、失败用例名、精简 traceback |
write_todos |
read | 多阶段任务的清单,整体替换语义。每轮回灌进系统提示 |
load_skill |
read | 按名字取一个技能的正文。system 里只有目录,正文按需展开 |
mcp__<server>__<tool> |
execute | 第三方进程里的工具。风险档位不接受远端自报(D19),AUTO 模式也要单独确认 |
is_error 的语义是一条刻意的区分:工具自己失败(路径不存在、参数非法、端点拒收)为 true;工具成功观测到的失败(测试红了、命令退出码非 0)为 false。这样 tool_error_rate 才是"Agent 用得顺不顺"的指标,而不是"任务难不难"的指标。
任务 → 组装上下文(system = 环境事实 + 仓库地图 + 工具清单 + 计划/调试规范 + TodoList
messages = 历史(含上一轮全部工具结果) tools = registry.specs())
→ ask(model)
├─ 纯文本答复 → COMPLETED
└─ tool_use ↓
权限门逐条判定(模式 + 路径锁 + 破坏性命令)
├─ 拒绝 → 理由写成 is_error 结果回填,让模型换路走
└─ 放行 ↓
执行工具(同一轮的 tool_calls 必须全部执行)
全部结果打包成**一条** user 消息回填 ← 漏一个 → 下一轮报文非法 → 400
每轮止损:MAX_TURNS · MAX_TOTAL_TOKENS · 连续 3 轮同一组调用签名 · 上下文压力
观测:run_tests 退出码 / 失败用例名 / bash 输出
这不是 Workflow(代码写死步骤),而是 Agent(模型决定下一步)。
获取错误信息 → 分析 → 修改 → 重跑 → 直到成功或达到最大次数,落在三个地方:run_tests 把失败结构化成用例名 + 精简 traceback;提示词 SELF_DEBUG_PROMPT 规定"以退出码和用例名为准,不要凭'我改了应该就对了'收尾";STALL_LIMIT = 3 只统计连续重复的调用签名,所以"改一处 → 跑一次 → 再改一处 → 再跑一次"这种交替动作不会被误判为停滞。demos/fixtures/red-tests 是这个闭环的实证:一个 bug 修好后测试仍然红,暴露出第二个 bug,模型必须在第二轮观测里换假设才能走到全绿。
TerminationReason 是返回值不是异常 —— 调用方必须能区分"做完了"和"崩了"。completed(唯一算成功)、max_turns、stalled、user_rejected、llm_failure、context_overflow、cancelled、internal_error 八个,其余七个都算失败。CLI 兜住 internal_error 后会话仍可继续。MAX_TURNS 和 STALLED 就是失败,不粉饰成"部分完成"。
每轮以 JSONL 落盘(schema 2.0),8 种 kind:session_start / turn_start / llm_response / permission / tool_call / todo_update / error / run_end。run_end 把"发起"与"执行"分成两个量:tool_calls 是模型发起了几次,执行几次由 tool_call 记录的条数得出(被闸门拦下的只进前者)—— v1 用一个名字指这两件事,报表因此在"有拒绝"的会话上自相矛盾。
infra/trace.py 的 summarize() 是 README 和 demo 证据里所有数字的唯一来源;fingerprint()(行数 + 字节数 + 全文件 sha256 前 16 位)是"判据配的那份轨迹就是它当时看的那份"这道闸门的地基,盖它的只有一处(EvalRunner.append_manifest)、读它的是导出器 join 前的比对。tests/test_trace_contract.py::test_metrics_have_producers 盯着"报表里出现的每个键都必须指得到一处写入它的代码"——v1 的 redundant_calls 恒为 0(声明、快照、读取、打印四处,没有第五处 +=)就是这条约束缺失的代价。
规则式而非模型式:8 条标签(path_guessing / context_growth / no_verification / self_confirm / test_gaming / thrashing / permission_starved / budget_exhausted),每条都要能在一条真实 trace 上被人眼复核,判据宁可漏报不误报。逐条判据与处方在 docs/reference.md。
mcc trace --latest --hot # 最贵 3 轮、报错最多的工具、重复调用簇
mcc trace --latest --why-failed # 标签 + 证据 + 处方
python scripts/b4_label_check.py # 16 条轨迹逐条对"人写的期望",不一致即退出码 1它同时打印盲区 —— 字段缺失时规则不是判对了,是没参与。旧 trace 落盘的标签与当前规则不同时,mcc trace 显式印出"规则口径变过",而不是沉默地换一套答案。
python demos/run_demo.py --list # 看有哪些 demo
python demos/run_demo.py --all --engine fake # 离线,秒级,不进 API
python demos/run_demo.py --demo bug-hunt --engine live每个 demo 的流程:把 demos/fixtures/<x> 复制成独立工作副本 → 用 build_session() 跑真实装配的 Agent → 在工作副本里独立执行 pytest 与行为探测 → 从 trace 抽数字写成证据文件(含判定明细、终端原样输出、基线→运行后 diff)。
判据为什么不看模型说了什么:Demo 1/2/3 和 A4 的判定脚本根本不读 result.text,只看执行结果(pytest 退出码、函数行为、基线 tests/ 只增不删、只读模式运行前后工作区哈希相同、收集到 0 个用例直接判退出码 5 —— "全绿"可能是"根本没考试")。唯一的例外是 A3 的只读问答,因为"答案对不对"本身就是被考的对象。两个判据本身也被测试盯着:test_fixtures_stay_pristine_after_a_run 要求跑完 demo 后 demos/fixtures/ 与基线哈希一致;test_scripts_never_recite_a_number_the_judge_owns 用正则拒绝任何"24 passed"式的自报数字。
| demo | 验收项 | fake | live(agnes-2.5-flash) |
|---|---|---|---|
Demo 1 codegen |
A2 | PASS · 8 轮 · 9 次调用 · 0 报错 | PASS · 8 轮 · 16 次调用 · 0 报错 · 65,425 tok · 97.1s |
Demo 2 bug-hunt |
A1 | PASS · 7 轮 · 7 次调用 · 0 报错 | PASS · 9 轮 · 20 次调用 · 0 报错 · 52,017 tok · 59.8s |
Demo 3 red-tests |
A1 + 自我调试 | PASS · 10 轮 · 9 次调用 · 0 报错 | PASS · 6 轮 · 13 次调用 · 0 报错 · 36,041 tok · 31.9s |
附加 readonly-qa |
A3 | PASS · 3 轮 · 4 次调用 · 0 报错 | PASS · 4 轮 · 6 次调用 · 2 次读空 · 0 被拒 · 14,976 tok · 12.8s |
附加 giveup |
A4 | PASS · 6 轮 · max_turns |
不支持(脚本化的"两次假设后收手"不是模型能力) |
四个 fixture 各自考一件事,数字都是逐条读 trace 写的:
- Demo 2(生死线):13 文件的陌生仓库,基线 21 用例全绿,但 README 承诺
format_duration(90000) == "1d1h0m0s"、实际返回25d0h0m0s。bug 不在任何红色 traceback 里 —— 现有测试最大只覆盖 3599 秒,跨天的分支从未被执行。live 那次第 5、6 轮对一个实现文件直接跑 pytest、verdict 老老实实记 red,随后换用测试文件一路绿到收尾。 - Demo 3:基线
1 failed, 16 passed。修好优惠券常量之后测试仍然红,因为断言链上藏着第二个 bug(税基)。全程is_error一次都没有 —— 第 3 轮那次run_tests是"测试红了"(ok=True、verdict=red),不是"工具坏了",v2 的 trace 把这两件事分成两个字段记。 - 只读问答:判据第一条是运行前后工作区哈希相同(
66e7e20db481→66e7e20db481)。上一批里它三次bash想跑代码复现全被闸门拒掉(denied_actions = 3),于是改成"从代码直接推理"并给出同样正确的答案 —— 拒绝没有让它重复请求,也没有让它停住。 - 自相矛盾的需求:
docs/config.md要求默认超时 60、app/settings.py是 30、测试同时钉了 30 和 60 —— 无解。合格的输出不是"好的,全绿了",而是在预算内停下并说清矛盾在哪(终止原因必须是max_turns)。
完整数字见 demos/results/(summary.fake.md / summary.live.md / failure-labels.md)。一处已知不同步:证据表格的 tool_calls 行在 S8 改成"发起 / 执行"两栏,*.fake.md 已按新格式重生成,*.live.md 还是旧格式 —— 数字两边一致,只是排版口径差一版。
python -m pytest -q # 871 passed, 2 skipped
python -m pytest tests/test_loop_with_fake_llm.py -q
python -m pytest tests/test_eval_runner.py tests/test_eval_cli.py -q # 评测层(不联网)
python scripts/b4_label_check.py # 失败模式标签的人工核对,退出码 0 才算过
python scripts/b2_compact_ab.py # B2 三臂 A/B + 判据账本(退出码 0 才算过)
python scripts/b3_repomap_ab.py # B3 两臂 A/B:机制判据离线核,因果两条要 --live
python scripts/b6_backend_ab.py # B6 两臂 A/B:docker 臂降级时不产出一致率、直接退 1
python scripts/s14_ext_demo.py # §3.7 的 20 条前提,对着两个 MCP 对手量
python scripts/t3_otlp_export.py # 24 份已入库轨迹 → OTLP/JSON + 18 条判据(0 个模型请求)
mcc eval --repeats 3 # 24 题 fake 全批,见 §4.4用哪个解释器跑不是小事:得用项目的 .venv。全局解释器少装了 dev extra 里的官方 mcp,tests/test_mcp_bridge.py 那条"对端是 SDK 写的服务"就会静默跳过,报出来的是 848 passed, 1 skipped —— 仍然全绿,绿的格数却少一格。同一类依赖在证据脚本那边更要紧:拿全局解释器跑 s14_ext_demo.py,SDK 那一臂直接没了,而它过去会照旧覆盖掉签着 20/20 的入库证据。现在这条路被守住了(退出码 2、文件一个字节不动),五个写证据的脚本共用同一道闸。
tests/fakes.py 提供 FakeLLM:按脚本吐响应,不联网,没有真实 API 也能测完整个循环。逐个测试文件覆盖什么在 docs/testing.md。
- A1 要求"非本项目真实仓库",这里用的是仓库内 vendored fixture。 拉取外部仓库的网络操作被本机权限策略拦下。它证明了"基线全绿 + 一句话描述 + 无 traceback 定位",但没证明跨语言、跨规模。5000 文件规模会压垮仓库地图 —— 本仓库 142 个可见
.py(约那个规模的 3%)冷建地图就要 0.83 秒。 - 压缩只到 L2,而且"压缩有没有让 agent 静默变笨"没被量到。 阶梯在真实分布上省下的 est 是有账的,它对成功率的净影响目前没有可信数字(n=1 × 2 的漂移太大,而 R4 担心的正是"静默变笨")。另外
write_file的 content 进的是 assistant 消息,L1 碰不到它。 - 符号地图只认 Python、只认
ast能看出来的东西。 装饰器背后的动态注册、字符串路由、yaml/toml 里的符号都看不见;REPO_MAP=0退回的仍是那棵固定 30 行的目录树。跨进程缓存命中 27.9~99.4ms,没达到 SPEC §6.2 的 ≤5ms。 - 只读工具并发没做(被数据砍进 Tier 3)。 不是遗漏:可并行的轮平均只值 2.9 毫秒,线程池开到无限大也只省 live 墙钟的 0.011%。所以
_run_tools()仍是单循环,MAX_PARALLEL_READS这个旋钮在config.py里根本不存在 —— 不生效的配置项比缺失的配置项更坏。 - 多 Agent 一种形态也没做(同样被数据砍进 Tier 3)。 D21 那条"占比 > 20%"在 75 次 live 运行上是 1.3%,连它点名的 B1 fake 批自己也只有 16.7%。
spawn_agent的三条约束写在 SPEC 里但没有代码执行它们 —— 与并发那三条不变式同一个处理方式:设计留着、空壳不留。 DockerBackend的真实容器路径一次也没跑过。 这台机器上没有 docker,B6 是用一个会真的在宿主上执行命令的假docker替身跑出来的:被证明的是命令行构造、降级不静默、两臂判定一致与 rev 共用,没被证明的是文件隔离、网络隔离、镜像内容。所以"这个 agent 能在沙箱里跑"目前是接口层的事实,不是运行时的事实。- MCP 只测了 stdio,两个对手都是自己的进程。 被证明的是命名空间隔离、风险不自报、出门前校验、env 白名单、降级不静默、被拒无副作用;没有连过任何一个真第三方服务。HTTP/SSE 传输砍进 Tier 3。另外"模型会不会主动去
load_skill"没测 —— fake 引擎里那次取用是剧本写好的。 - 导出的 RL 数据里 69.6% 的行没有 state 正文。 不是导出器偷懒:trace 按设计只存计数与类型名,正文只在会话快照里,而快照是 S13 才上线的。要拿它做后训练,第一步不是训,是让 trace 落 observation —— 那是一次没做的架构改动。SBS 人工标注 0 条(54 对全部是同题重跑自动配的)。
- OTLP 那一头没人接过。 唯一未量的一条是"真实收集端收下并画出树":有人应答但回
502且响应体为空,既不能记成"被拒"也不能记成"收下"。Jaeger 里画出来长什么样没看过。 附带一条边界:payload 里带着 59 个绝对本地路径和 24 个端点样字符串,--endpoint指向非本机时只警告后照发。 - 框架对照是文档,不是移植层。
docs/framework-equivalence.md说明了我们与 LangGraph 的概念对应关系和缺的东西,但没有实现它的接口 —— 迁移表里三处硬冲突是"真要换需要先解的结"。 - live 数字不可复现。 同一任务重跑轮数会漂移;证据文件因此各自记录自己那一次,不做"平均"。
- 端点行为依赖。
tools字段偶发被吞,所以工具清单在系统提示里又列了一遍。 rich是可选依赖,缺失时渲染层自动退化成纯文本,功能不变。- Windows 上
bash优先走 Git Bash。 没有 bash 时退到cmd.exe,此时提示词里那套 Unix 习惯(&&、/dev/null)就不成立 —— 提示词分了两层说明。 - 只支持 Python 项目的
run_tests。 多语言是架构无关的待办,不是已交付能力。评测层同一局限:判据全建立在 pytest 上。 pass@1=4/6那个数不能当结论用。 6 题的 Wilson 95% 区间是[0.300, 0.903]—— 宽到容得下两种相反的说法。live 冒烟证明的是"管线跑得通、判据抓得住真失败"。- 批次预算的闸只在任务边界生效,所以最后一题可以合法地把整批顶过线(实测:预算 300,000,实际 313,812)。
实施过程中发现 35 处 SPEC 的工程问题,按"问题 / 原因 / 建议修改 / 本次采取"记在 docs/spec-deviations.md。摘三条最能说明口径的:
| # | 问题 | 本次采取 |
|---|---|---|
| 11 | S10 计划里的 COMPACT_LEVEL / COMPACT_TARGET 环境变量不该存在 —— 阶梯阈值是配对不变式的一部分,做成运行时旋钮就等于允许"这一批跑的是另一套阈值"这种无法对比的状态 |
改成 context.py 常量 + 三个评测旗标;被拧过的批次不许当基线入库 |
| 18 | B6 的措辞预设了"有两个能跑的后端",而这台机器上只有一个 | 允许降级但必须自己划清边界:脚本先证明前提,任一条不成立就不产出一致率;结果文件里 container_isolation_tested: false + what_this_proves / what_this_does_not_prove 两栏 |
| 35 | 上一行那句"4318 回 502"当时是背下来的,不是测出来的 —— 同一份文件里 attempted 是 false、判据详情里却躺着一句"回 502" |
判据详情由 receipt 现算而不是写死;默认路径就真去试一次本机端口 |
代码与 SPEC 里说的"§10 第 27 / 30 / 34 行"就是
docs/spec-deviations.md那张表的行号,行号仍然有效。
mini-claude-code/
├── main.py · pyproject.toml · conftest.py 零安装入口 / mcc 命令 / fixtures 收集隔离
├── SPEC.md · SPEC-v2.md v1.0 契约(D1–D8)/ v2.0 路线图(D9–D27)
├── src/miniclaude/
│ ├── messages.py · config.py 报文与 Block / 唯一读环境变量 + 密钥脱敏
│ ├── llm/ · tools/ OpenAI 兼容客户端(httpx,不装 SDK)/ 7 工具 + 路径锁
│ ├── agent/ loop / planner / prompts / permissions
│ │ / context / state / todo_tool
│ ├── cli/ build_session、REPL、渲染、trace/eval/ext 子命令
│ ├── memory/ 工作记忆 + ast 符号地图
│ ├── backend/ local / docker / 影子 git 检查点 / 显式降级 / 会话现场
│ ├── ext/ MCP 桥 + RemoteTool · 按需加载的技能
│ ├── infra/ trace(replay/summarize/fingerprint + 脱敏)
│ │ otel(只做导出映射)· failure(8 条规则)
│ └── eval/ taskset / contract / judge / drivers / runner
│ / metrics / regression / export_rl
├── eval/ 24 道考题 · fixtures(刻意做成有 bug 的靶子)
│ ├── baselines/ · results/ · .work/ 入库的基线与证据文件 / 忽略的工作副本
├── scripts/ 证据生成器:b2/b3/b6/s14/t3 的 A/B、b4 标签核对、
│ 两个 probe_*_gate、bench_engines、
│ _evidence.py(五个脚本共用的那支笔)
├── docs/ experiments · reference · testing · spec-deviations
│ framework-equivalence · inference-bench · mcp-link-spec
├── skills/ · tests/ · demos/ 两个技能 / 871 项测试 / 五个 demo 与它们的证据