别让 Agent 骗自己

一个 fork 的价值在于它焊了什么

打开仓库第一眼就该注意到的事：唯一的核心包叫 packages/opencode，而根 package.json 的 name 字段至今写着 "opencode"。

这不是命名随意。MiMo Code 是 OpenCode 的深度 fork——本系列第二份分析的对象。上游的 Effect 服务层、SolidJS TUI、SQLite 持久化、provider 抽象，MiMo 全盘继承。LICENSE 里两行版权并列（Copyright 2026 MiMo Code, Xiaomi 与 Copyright 2025 opencode），把这件事写得明明白白。

口号背后的产品主张

README 第一行："MiMo Code: Where Models and Agents Co-Evolve"。这句话不是营销辞令，它对应两件具体的工程事实：

数字化的项目形状

全景架构：Effect 服务层 + 单进程 TUI

flowchart TB
    subgraph UI["① 终端 UI（SolidJS + OpenTUI）"]
        TUI["会话视图 · 输入框 · 任务面板 · 权限弹窗
10 种语言 i18n"]
    end
    subgraph CORE["② Session 引擎（同进程，Effect 服务层）"]
        PROMPT["SessionPrompt 主循环
prompt.ts 4595 行"]
        SYS["SystemPrompt 路由
按模型 ID 选 20 份之一"]
        CKPT["Checkpoint 系统"]
        GOAL["Goal 独立裁判"]
        PERM["Permission 规则集"]
        REG["ToolRegistry
按模型装配工具 ABI"]
    end
    subgraph EXT["③ 扩展面"]
        SKILL["26 个内置技能"]
        WF["Workflow（QuickJS 沙箱）"]
        MCP["MCP 客户端"]
        PLUG["插件 / hooks"]
    end
    subgraph OUT["④ 外部世界"]
        MODEL["任意 provider 模型
MiMo Auto / Codex OAuth / API key"]
        FS["文件系统 · Shell · Git"]
        DB[("SQLite
会话 / 记忆 FTS5 / 任务 / 权限")]
    end
    TUI --> PROMPT
    PROMPT --> SYS
    PROMPT --> GOAL
    PROMPT --> CKPT
    PROMPT --> REG --> PERM
    REG --> SKILL & WF & MCP & PLUG
    PROMPT -->|流式| MODEL
    PERM -->|裁决后| FS
    CKPT --> DB
    SKILL --> DB
    

每个子系统都是一个 Context.Service + Layer，靠依赖注入拼起来。好处在测试和替换上很明显（换一个 Provider.layer 就能把整棵依赖树换掉），代价是阅读门槛陡——yield* 满屏。这是上游的选择，MiMo 全盘继承。

与上游 OpenCode 的差分：一张增量清单

这一章是全文的地图。读 MiMo Code = 读这张表。

心脏地带：Goal 停止条件与独立裁判模型

长任务里最常见的失败不是崩溃，是乐观停止：模型干到一半觉得差不多了，输出一段"我已经完成了 XXX"然后收工。用户回来一看，测试没跑、边界没处理、文件根本没写。

/goal 命令给会话设一个停止条件。之后 session/goal.ts:17-21：

once a goal is set, the main runLoop refuses to stop until an independent judge model decides the condition is satisfied (or genuinely impossible). The judge is a separate model call that only reads the transcript — it does not do the work, so its verdict stays cold relative to the working agent's optimism.

最后半句是设计精髓：裁判不干活，所以它的判断相对于干活者的乐观是"冷"的。

裁判提示词里最关键的一句

四道死循环闸门：空步 / 重复步 / 文本环 / 步数上限

Goal 管的是"该不该停"，这一章管的是"别原地转圈"。四道闸门各抓一种病，而且每道都是软→硬两级。

闸门一最值得学的是它划出的边界

this guard does NOT try to catch "empty terminals" (steps that emit no tool call and no text). An empty terminal is a natural turn end, not a spin… Treating it as a loop caused frequent false positives on legitimate quiet steps (task done, sub-agent returned, reasoning-only steps, provider-executed tool calls). empty-step-detection.ts 文件头

"模型什么都没说"不是死循环，那是回合正常结束。早期版本把它当循环抓，误报到不可用。真正的"模型什么都不产出"由 wall-clock 和 provider 流超时兜底。

闸门二：两个细节是同一个洞察的两面

闸门三：剥掉开场白才能看出复读

export function normalizeForLoopDetection(text: string): string {
  return text.trim().toLowerCase()
    .replace(/\s+/g, " ")
    .replace(/^(let me |i'll |i will |let's )/i, "")   // ← 剥掉开场白
    .slice(0, 200)
}

模型复读时开头常常在 "Let me…" / "I'll…" / "I will…" / "Let's…" 之间随机切换，归一化时把这些开场白剥掉，才能看出后面是同一句话。

闸门四：步数上限不只是"停"，是"交代清楚"

CRITICAL - MAXIMUM STEPS REACHED
Tools are disabled until next user input. Respond with text only.

STRICT REQUIREMENTS:
1. Do NOT make any tool calls …
2. MUST provide a text response summarizing work done so far
3. This constraint overrides ALL other instructions, including any user requests

Response must include:
- Statement that maximum steps for this agent have been reached
- Summary of what has been accomplished so far
- List of any remaining tasks that were not completed
- Recommendations for what should be done next

第 3 条：用户在上下文里说过"必须改完这个文件"也压不住它。而且它要求的不只是停，是让被截断的回合仍然有交付物。

flowchart LR
    subgraph L1["步级（每一步都查）"]
        A["空参数工具调用
软→硬 2 级"]
        B["重复动作签名
连续 3 次"]
        C["文本复读 + n-gram
缓冲 5 / 触发 3"]
    end
    subgraph L2["回合级"]
        D["步数上限
禁工具 + 强制交代"]
    end
    subgraph L3["会话级"]
        E["Goal 独立裁判
MAX_GOAL_REACT=12"]
    end
    A & B & C -->|软提示不管用| D
    D --> E
    E -->|判定未达成| RETRY["继续干"]
    RETRY --> L1
    

Agent 模式与子 Agent：13 个内置 agent 的三种身份

agent/agent.ts:35 定义三种身份：subagent / primary / all。内置 13 个 agent：

Sticky Tab：为什么 compose 进去就出不来

stateDiagram-v2
    [*] --> 未发首条消息
    未发首条消息 --> build: Tab
    未发首条消息 --> plan: Tab
    未发首条消息 --> compose: Tab
    build --> plan: 发消息后仍可互切
    plan --> build: 可互切
    build --> compose: 发首条消息后禁止
    plan --> compose: 禁止
    compose --> compose: 一旦进入即隔离
    

After the first message the mode locks: Build and Plan can still switch between each other, but Compose is isolated once entered — keeping the skill/tool set fixed from session start significantly improves tool-call reliability. README

从 plan 切到 build 时会注入一段状态变更提示（session/prompt/build-switch.txt，仅 233 字节）——模式切换必须显式告知模型，否则它会继续按只读模式的习惯行事。

三个 ReAct 上限的分层

主会话给 12、子 agent 给 3——因为「main-session goals are usually larger」。

停滞看门狗：三个周期互相错开

T40 stall watchdog scan cadence. Sits between the per-step turn heartbeat and the DEFAULT_LIVENESS_STALL_MS (90s) window, and just under the registry's own 60s stuck-scan, so a genuinely stalled child is caught within ~one window without hammering the DB. actor/spawn.ts:42-46

每步心跳 < 看门狗扫描 < 60s 注册表扫描 < 90s 停滞判定窗口。扫太频繁会打爆数据库，扫太慢会漏掉卡死的子进程。

系统 agent 的两处特殊待遇

// agent/config.ts:5
export const SYSTEM_SPAWNED_AGENT_TYPES: ReadonlySet<string> =
  new Set(["checkpoint-writer", "dream", "distill"])

Try-Best 检测器与产物级验证

session/try-best-detector.ts（9 283 字节）抓的是另一类自欺：模型说"我已经尽力了"、"这是目前能做到的最好结果"然后停下——但用户要的是做完，不是尽力。

配套还有 checkpoint-validator.ts 和 checkpoint-retry.ts——checkpoint 写完之后要验证，不合格要重试。同一条主线：让 checkpoint-writer 子 agent 写完快照，不代表快照是对的。

一模型一提示词：20 份 prompt 与路由规则

路由规则：一串 if

export function provider(model: Provider.Model) {
  const prompt = (id: string) => {
    if (id.includes("gpt-4") || id.includes("o1") || id.includes("o3")) return PROMPT_BEAST
    if (id.includes("gpt"))        return id.includes("codex") ? PROMPT_CODEX : PROMPT_GPT
    if (id.includes("gemini-"))    return PROMPT_GEMINI
    if (id.includes("claude"))     return PROMPT_ANTHROPIC
    // …trinity / kimi / deepseek / glm / minimax 小写化后匹配
  }
  return [prompt(model.id) ?? prompt(model.api.id) ?? PROMPT_DEFAULT]
}

环境块里的缓存优化

Anchored to the session's creation time (not request time) so this block stays byte-identical across every turn of a session — including ones that cross midnight — keeping it inside the Anthropic cached system prefix. system.ts:66-84

用请求时间会让跨午夜的会话在某一轮突然缓存失效。锚到会话创建时间就不会。

同一段还有一个诚实的风险标注：视觉模型列表是懒解析的，如果 provider 配置在会话中途变了，这一块会打破缓存前缀——「In practice provider config is stable within a session」。已知、可接受、写下来。

无视觉能力时的降级

You CANNOT see or interpret image content… Never attempt to analyze an image's visual content yourself. If a task needs image understanding, dispatch a vision-capable subagent via the actor tool, passing the image file path so the subagent can Read it. system.ts:105-118

并且列出当前配置里有视觉能力的模型（最多 3 个）供它 --model 调用，还给了示例命令。最后补一句区分：如果你要的是文件的二进制结构而不是视觉内容，用 hexdump -C。

Checkpoint：把上下文当成可重建的快照

传统做法是压缩：上下文快满了，让模型把前面的对话总结成一段替换原文。问题是总结有损且不可逆，而且总结本身也占上下文。

Context reconstruction — when context approaches the limit, rebuilds it from the latest checkpoint, project memory, task progress, and retained recent messages so the agent can continue the current task. README

flowchart TB
    P["上下文接近上限"] --> R["重建，而不是压缩"]
    R --> S1["checkpoint.md
结构化状态快照
（checkpoint-writer 子 agent 维护）"]
    R --> S2["MEMORY.md
项目持久知识
（/dream + 手工）"]
    R --> S3["notes.md
临时草稿区"]
    R --> S4["tasks/<id>/progress.md
每个任务的进度日志"]
    R --> S5["保留的近期消息"]
    S1 & S2 & S3 & S4 & S5 --> B["预算化注入
分节 token 配额 + 重要性排序"]
    B --> N["新的上下文"]
    N --> V["checkpoint-validator
不合格 → checkpoint-retry"]
    

超长用户消息的截断：一个小而完整的工程样本

// 保留头 ~60% + 尾 ~30%，中间放省略标记并指回 messageID
const head = text.slice(0, Math.floor(capTokens * 0.6) * 4).replace(/[\uD800-\uDBFF]$/, "")
const tail = text.slice(-Math.floor(capTokens * 0.3) * 4).replace(/^[\uDC00-\uDFFF]/, "")
return [head,
  `[…elided ${elidedTokens} tokens; messageID=${messageID}; use the history tool with operation=around to fetch full content]`,
  tail].join("\n")

高压提示的去抖：窗口要对齐到"状态真的变了"

Keying off the checkpoint boundary rather than a fixed message count is deliberate: a single sustained high-pressure turn can emit many tool-call steps — each its own message — so a fixed-size tail would let the already-nudged message slide out of the window and re-fire the nudge mid-turn. The boundary only advances when a checkpoint/rebuild actually discards context, which is exactly when a fresh nudge becomes useful again. prompt.ts:216-243

记忆：SQLite FTS5 + BM25 相对地板

四个检索工程细节

懒重建与跨产品索引

每次 search 前先 reconcile 一遍（可配置关闭），理由是「covers off-tool writes」——用户可能直接用编辑器改了 MEMORY.md，没走工具。fingerprint 字段让重建是增量的。

压缩点可调：/context-limit 与成本档位

这是一个纯产品驱动的工程功能。README 给了三条动机，每条都很实在：

{
  "compaction": {
    "max_context": {
      "openai/gpt-5.6": "272K",   // token 数、"300K"、"1M"、或窗口的 "50%"
      "anthropic/*": "300K"        // 允许通配符，最长模式胜出
    }
  }
}

GPT 微内核：给 Codex 一套更小的工具 ABI

docs/architecture/codex-microkernel-runtime.md 开门见山，而且先自我澄清术语：

"Codex 微内核运行时"是本文对当前架构的概括，不是源码中的正式模块名，也不表示操作系统级微内核。

做法是不为 GPT 新建 Agent 引擎，而是在统一 Session runtime 上做三件事：① GPT/Codex 专属 system prompt；② 通过 ToolRegistry 装配更小的工具 ABI；③ 提供 QuickJS exec 在不扩大权限的前提下组合宿主工具。

flowchart TB
    M{"usesGPTToolset(modelID)?
含 gpt- 且不含 oss / gpt-4"}
    M -->|是 · GPT/Codex 家族| G["4 件工具 ABI"]
    M -->|否 · 其他模型| N["完整工具套装"]
    G --> G1["bash —— 用 rg/sed 检查搜索 + 执行命令"]
    G --> G2["apply_patch —— 结构化 patch 改文本"]
    G --> G3["view_image —— 本地图片转附件"]
    G --> G4["exec —— QuickJS 里批量调用聚合宿主工具"]
    N --> N1["read / write / edit / multiedit"]
    N --> N2["grep / glob / notebook_edit"]
    N --> N3["bash / …"]
    G -.对 GPT 隐藏.-> N1 & N2
    

为什么要给 GPT 更少的工具

表面看是"减法"，实际是对齐模型的训练分布。Codex 系模型在 OpenAI 自家的 harness 里就是用 bash + apply_patch 这套 ABI 训练的，给它一套 Claude 风格的 read/write/edit/grep/glob，它反而更容易调错。

exec 与 QuickJS：组合工具但不放大权限

模型提交一段 async function body，通过 tools.<name>() 调用宿主工具，一次 exec 批量调用聚合多个工具。危险显而易见：如果 exec 里能调到外层被禁的工具，权限体系就穿了。

三道防线

"活跃计算"：一个避免误杀的计时器

const hostCallTracker = {
  start: () => { pending++; if (pending === 1) activeAccum += Date.now() - activeStart },
  end:   () => { pending--; if (pending === 0) activeStart = Date.now() },
}
// Active-time accounting: charge the guest only while no host hook promise is pending.

脚本等宿主工具返回的时间不算它的计算预算。否则一个正常脚本调 5 次 bash（每次 20 秒）就会被 60 秒预算误杀。Wall clock（30 分钟）单独兜底真正的卡死。

权限系统：FORCED_ASK 与通配符压不住的那条线

// permission/index.ts:188-195
// Permissions whose "allow" outcome must ALWAYS come from an explicit human ask.
// A wildcard rule like `permissions.allow: ["*"]` … MUST NOT be able to pre-authorize
// these — the whole point of a forced-ask permission is that the intent to
// perform an irreversible action must be recorded in-band, not inherited from
// a broad blanket rule.
const FORCED_ASK = new Set(["bash_delete"])

工具组别名与 findLast

permission/index.ts:591-614 用数组顺序表达优先级：EDIT_TOOLS（edit/write/apply_patch/multiedit）额外按 edit 这个组别名匹配，这样写 edit: "deny" 就能一次禁掉整个编辑家族。

findLast returns the last-merged matching rule, so a tool-specific rule placed after a group rule wins naturally. This preserves the convenience of edit: "deny" covering all edit-family tools while letting an explicit write: "allow" take precedence when present.

用数组顺序表达优先级，用 findLast 让后写的赢——不需要额外的优先级字段，且符合"配置文件里后写的覆盖先写的"这个直觉。

Workflow：确定性 JS 脚本编排多 Agent

Workflows are deterministic JavaScript scripts that orchestrate multiple agents in a sandboxed runtime. Unlike agent conversations, workflows encode fixed phase sequences with bounded retries and automatic parallelization — fire-and-forget execution with no user interaction required.

四个内置流水线

两个防御性细节

放一个 .js 到 .mimocode/workflows/ 或 .claude/workflows/ 就能定义自己的 workflow；用同名文件可以覆盖内置。

Orchestrator 模式：一个窗口管所有任务

默认关闭，由单一 flag MIMOCODE_EXPERIMENTAL_ORCHESTRATOR 门控。它解决的问题是：

真正的负担不是机器算力，而是你的注意力和精力——上下文在窗口之间反复切换，人被"多路复用"拖垮。

flowchart TB
    U["用户目标（自然语言）"] --> O["Orchestrator 会话（全局唯一）"]
    O -->|session create| A["child A · build · dir=repo1 · --isolate"]
    O -->|session create| B["child B · plan · dir=repo2"]
    O -->|session create| C["child C · compose · dir=repo1 · --isolate"]
    A & B & C -->|完成| INBOX["actor_notification → inbox"]
    INBOX -->|主动唤醒| O
    O --> MERGE["git 合并各 child 的 mimocode/* 分支"]
    MERGE --> REPORT["汇报给用户"]
    

后台会话的权限审批路由

问题很实在：后台跑的 child 没有面对用户的面板，碰到需要 ask 的权限门会被直接拒绝（interactive:false → DeniedError），用户看不到也无从批准。

不轮询：create 立即返回，child 完成时消息进 inbox 唤醒 Orchestrator。「派发后就返回…不要循环 list/查状态空耗轮次。」中断 Orchestrator 不会停掉 child。

Dream / Distill / Evolve：让 Agent 改自己

一个有意思的反向关系

26 个内置技能里有 claude-code、codex、grok-build 三个——MiMo 可以把任务委派给这些外部 CLI（且只在对应可执行文件已安装时才暴露）。

Token Efficient 模式：把 bash 输出的噪音洗掉

实验功能，默认关闭，单 flag MIMOCODE_EXPERIMENTAL_TOKEN_EFFICIENCY。bash 的 stdout/stderr 经常被 ANSI 色码、\r 进度条多帧、误打印的密钥、minified JS 超长行撑爆上下文。

flowchart LR
    RAW["bash stdout/stderr"] --> SPLIT{"三路分流"}
    SPLIT -->|落盘归档| DISK["原始字节"]
    SPLIT -->|TUI 预览| TUI2["原始字节"]
    SPLIT -->|inline 给 LLM| P1["① clean_progress
折叠 \\r 进度条"]
    P1 --> P2["② clean_ansi
剥 CSI/OSC/DCS + 控制字节"]
    P2 --> P3["③ clean_redact
PEM/Bearer/JWT/AWS/GH/OpenAI 密钥"]
    P3 --> P4["④ clean_longline
超 500 字符压成 head 160"]
    P4 --> GUARD{"never-worse 守门
字节数变小了吗？"}
    GUARD -->|是| OUT["清理后送 LLM"]
    GUARD -->|否| RAW2["回吐原文"]
    

总结：三个最独特的设计与三处取舍

三个最独特的设计

三处必须知道的取舍

它在本系列里的位置

继续读

逐层差分：MiMo 到底改了 OpenCode 什么，以及为什么

20.1 先看总量：1.75 倍，但不是均匀长胖的

但增长完全不均匀——这才是有信息量的地方：

flowchart LR
    subgraph NEW["🆕 15 个全新子系统（上游完全没有）"]
        N1["workflow · actor · memory
cron · inbox · task · team"]
        N2["history · file · flag · global
metrics · npm · pty · shell"]
    end
    subgraph BIG["↑ 大幅扩张"]
        B1["skill/ 2 → 414 文件（207x）"]
        B2["provider/ 5 → 34（6.8x）"]
        B3["storage/ 2 → 11（5.5x）"]
        B4["cli/ 87 → 230（2.6x）"]
        B5["tool/ 43 → 84（2.0x）"]
        B6["permission/index.ts 3.4x"]
        B7["session/ 39 → 68（1.7x）"]
    end
    subgraph SHRINK["↓ 收缩"]
        S1["server/ 72 → 43"]
        S2["acp/ 12 → 4"]
    end
    subgraph DEL["❌ 删除"]
        D1["background · image
event-manifest · event-v2-bridge"]
    end
    

20.2 主循环：session/prompt.ts 从 65 KB 涨到 208 KB

20.3 提示词：8 → 20 份，但有 5 份一个字节没动

双 ID 兜底为什么重要（session/system.ts:39）：上游只看 model.api.id。但同一个模型经不同 provider 暴露时 ID 不同——OpenRouter 上的 xiaomi/mimo-v2.5、自建网关上的 internal/xiaomi/mimo-v2.5。MiMo 要支持的模型接入路径比上游多得多（MiMo Auto / Xiaomi OAuth / Codex OAuth / 从 Claude Code 导入 / 任意 OpenAI 兼容端点），所以必须两个 ID 都试。

20.4 GPT 工具门控：同一行表达式，作用域扩了一个量级

const usePatch =
  modelID.includes("gpt-") &&
  !modelID.includes("oss") &&
  !modelID.includes("gpt-4")
if (tool.id === ApplyPatch) return usePatch
if (tool.id === Edit || Write) return !usePatch

export function usesGPTToolset(modelID) {
  return modelID.includes("gpt-") &&
    !modelID.includes("oss") &&
    !modelID.includes("gpt-4")
}

判定逻辑一字不差。差别在两处：代码形态（内联局部变量 → 独立文件的命名导出）和作用域（二选一 → 整套 ABI 替换）。

20.5 沙箱：从 3 465 行手写解释器换成 QuickJS

20.6 Shell 执行整个重写 · 20.7 权限 3.4 倍

20.9 收缩的地方也有信息量

20.10 把 15 个新子系统按「为什么加」归类

flowchart TB
    subgraph G1["动机 A：让 Agent 能长时间干活"]
        A1["memory —— 跨会话记忆 FTS5"]
        A2["checkpoint 家族 —— 上下文重建 74 KB"]
        A3["history —— 历史回捞"]
        A4["task —— 树形任务与进度"]
    end
    subgraph G2["动机 B：让 Agent 能多线程干活"]
        B1["actor —— 子 agent 派发与生命周期"]
        B2["workflow —— 确定性 JS 编排"]
        B3["inbox —— 完成通知唤醒"]
        B4["team / worktree —— 多会话隔离"]
    end
    subgraph G3["动机 C：让 Agent 能无人值守"]
        C1["cron —— 定时 + 分布式锁 + 哨兵"]
        C2["flag —— 实验功能门控"]
        C3["metrics —— 可观测"]
    end
    subgraph G4["动机 D：基础设施补齐"]
        D1["file · global · npm · pty · shell"]
    end
    

20.12 这次 fork 给同类项目的三条经验