qybaihe/mu · 上手攻略

  • 仓库：qybaihe/mu
  • 链接：https://github.com/qybaihe/mu
  • 分类：AI Coding Agent / CLI / Desktop App
  • 作者：spark
  • 更新：2026-09-26

一、它是什么

mu（读作"μ"）是一个把"判断"从大模型里拆出来的工作型 coding agent。它的卖点一句话：让小模型去做那些高频、套路化、yes/no 的"裁判型"决策，把大模型的注意力留给真正需要推理的工作。

具体来说，作者把一个完整 coding 会话里约 35 个决策点显式列了出来——从「这条用户输入是任务还是闲聊」「这条工具输出要不要进上下文」「这条命令是不是危险」「这个测试日志的重复段要不要折叠」「上下文快满了，先丢掉哪几段」「这一轮是不是已经走偏了」一直到「子 agent 这次提交是不是没越界」。每个点都向一个独立的 judge 提问；judge 给一个有概率的回答，这个回答只改变模型下一步做什么，不改变它是否问你（危险命令的拦截仍由规则兜底）。

整个项目还配套了一个桌面应用（基于 AionUi），把 CLI 装进一个原生窗口：左边对话，右边面板是 board / judgments（裁判账本） / hive / lessons / files / preview / source / browser。命令行和桌面应用共享账号、设置和 lessons。

项目自述仍处于早期（"Early development … nothing has been released yet"），作者自用，所以命名、设置和格式都可能再变。

二、它解决什么问题

主流 coding agent（Claude Code、Codex CLI、Gemini CLI、Cursor Agent 等）普遍把"工具调用 + 上下文管理 + 命令风险判断 + 多 agent 协调"全部塞给同一个大模型。结果：

  • tokens 烧在判断上，不是工作上：作者自测，一个 warm 裁判问题 HTTP/2 上约 0.3 秒、一次判断 16 段工具输出 0.44 秒、状态只计费一次；同等事情让大模型做，慢、贵、还经常分心。
  • 上下文被日志挤爆：长 test run 里 51% 的字节是精确重复，mu 把它们按"重复段"折叠一次（lossless）。
  • prompt cache 凉了没人暖：mu 通过一个 cache.warming 决策点预测"你是不是马上回来"，提前刷缓存。
  • 危险命令拦不住/拦太狠：规则做地板（rule-first），judge 只对规则放行的边界情况补一句"你确认要？"
  • 多 agent 互相喂噪音：通过 hive 共享板 + hive.relate 关系判定（supersedes / contradicts / supports）让更正自动追到持有旧结论的那个 bee。

一句话：把"judge"和"worker"两种角色拆开，分别用最合适的模型担任。

三、快速安装

桌面应用最省事——Releases 页下载 macOS（Apple silicon / Intel）/ Windows（x64 / Arm）/ Linux（x64 / Arm）的安装包，由 GitHub Actions 构建，App 内登录 ChatGPT / Claude / Grok / Google（Gemini CLI 或 Antigravity）订阅，或填任何 pi 支持的 provider 的 API key。

命令行方式：

# 前置：Node 22.19 或更新
node -v

# 全局安装
npm i -g mu-agent

# 当前目录开一个交互会话
mu

# 一次性跑一条提示并打印结果
mu -p "重构 src/legacy.js 里所有 forEach 为 reduce，并加单元测试"

# 接续上次会话
mu -c

# 体检：检查安装、judges、provider 连通性
mu doctor

# 查看最近 N 个会话里 judge 做了哪些决定
mu ledger 5

⚠️ 版本/约束提醒：

  • Node 必须 ≥ 22.19（README 写"or newer"，建议先 node -v 验）。
  • npm i 时如果遇到 lifecycle script 警告，按官方 AGENTS.md 推荐：npm install --ignore-scripts，再 npm run check（fmt + lint + types）和 ./test.sh。
  • 桌面应用源码在 desktop/，开发模式要 bun install 后用 KYRN_ROOT="$(cd .. && pwd)" bun run start，前提是仓库根已经 npm install。

四、核心用法

1. 决策点 + 三种 judge

每个决策点（35 个）都可以被设为 active / shadow（问且记录但不改变行为，用于 A/B 比对 judge）/ off 三种模式，并独立指派 judge：

# judge 选项
jev                       # 默认，托管在外的有界问答服务（OpenRouter / Vercel AI Gateway / TypeSafe 任选）
laya                      # 本地 322M 参数 judge，不联网；简单谓词稳，元判断弱，建议先 shadow 跑
llm:<provider>/<model>    # 任意 LLM 当 judge 用
laya,jev                  # 级联：先 laya，不确定再 jev

切 judge 的几种方式：

/mu judge              # 全局列出当前在用的 judge
/mu judge laya,jev    # 全局换成级联
/mu route tool.risk jev          # 单点指定：tool.risk 用 jev
/mu mode context.compact shadow  # 单点切到 shadow 模式（只观察、不影响行为）

⚠️ 实战建议：换 judge 之前先在 shadow 跑一段时间，然后 mu ledger 看 verdict 与概率，确认它在该决策点的稳定度再切 active。

2. 上下文与缓存的"自我管理"

mu 的与众不同在于它把"工具输出要不要进上下文""重复段要不要折叠""stale 的工具结果要不要 tombstone 化""cache 要不要刷"都做成了决策点。意味着：

  • 长 test 日志先经 tool.admission.test-log 折叠重复，lossless；
  • 上下文涨到阈值由 context.forget / context.compact 主动瘦身（不写摘要，直接 tombstone）；
  • 离开超过一个缓存周期时 cache.warming 决定是否提前刷新。

作者实测：上下文再没撑爆过；测试日志 51% 字节被折叠；cache 命中率保持高位。

3. board：把执行流变成可读的一句话

/board 开/关。开之后，每一步（改文件、检查通过/失败、跑命令、读文件）完成后立刻在 board 上落一条人话；agent 说话时由 board.read 判定是不是新闻，是的话用一个专门训练成"讲人话"的模型（/board model 指定）复述给你。两条顶栏数字直接是 context use 和 cache hit rate。

⚠️ 这层抽象的副作用：你的工作模型继续用最适合它自己工作的语言（往往很机器），你看到的 board 总是人话。两者永远不要混着看。

4. hive：2-6 个 bee 的多 agent 协作

/swarm          # 看每个 bee 在干啥
/swarm stop     # 立刻催交报告
/swarm kill     # 终止全部

每个 bee 只读、跑、浏览，不直接改文件——所有改动由主模型做。每当一个 bee 说完，hive.publish 问一次"这条值得登板吗"；新条目上线，hive.deliver 按"是否触及本 bee 的 focus"决定是否推送。后续结论若推翻旧结论，hive.relate 标 supersedes，旧结论变成 correction 自动送达当年持有它的 bee。矛盾未在一分钟内解决，自动派一只"verifier bee"去仲裁。

作者给的一个真实跑：3 bee / 9 分钟 / 117 个候选被判 / 27 条上板 / 16 条送达需要的 bee。完整 verdict 在该次 run 的 log 里。

5. 权限模式与目标模式

/permissions          # full access / jev approves / minimal 三档
/goal <condition>     # 工作直到条件成立；/goal clear 结束
/permissions jev approves
/goal "tests/ 全部通过且无新增 lint 警告"

jev approves 是 mu 特色档：judge 对"这条命令 / 这个项目外改动 / 这个子 agent"做"是否明显需要"判断，只有它确信的才放行，其余一律问你。

6. 复用已有会话

/import-chat                      # 把 Claude Code / Codex CLI 会话导入并续上
mu import --list                  # 命令行方式列出可导入会话
mu import <file>                  # 导入单个文件

CLI 和桌面应用共享账号、设置、lessons，迁回迁无成本。

7. 其它常用命令

/status 看所有 judge 和决策点当前状态；/frame 看 task frame（目标 + 你的约束逐字 + 来源 + 验收标准）；/review + /commit 用 P0-P3 优先级把发现落成 commit；/checkpoints 与 /rewind 回退到上一个 checkpoint；/agents、/jobs、/browse 派子 agent / 后台任务 / 用内置浏览器；/capabilities 看已装技能；/remember、/lessons、/forget 管 lessons；/doctor 体检。

pi 的所有原生命令（/model /thinking /login /resume /tree /fork /compact /export 等）保留。

五、典型适用场景

  • 长跑测试 / CI 日志消化：51% 字节是重复段时，mu 的 tool.admission.test-log 自动折叠，lossless，再喂回模型。
  • 多 agent 并行的代码改动（3-6 个 bee 同时读不同模块）：hive 板 + hive.relate 自动处理结论推翻。
  • 对外设命令的安全审计（rm -rf / git push --force / 越界改 ~/.ssh/）：rule-first + tool.risk 双重保险；jev approves 档只让确信的命令自动放行。
  • 大上下文会话（长任务跑两小时以上）：context.forget / context.compact / cache.warming 三件套让你不必手动 /compact。
  • 想要可读的进度汇报但又不想让大模型分心写汇报：开 /board 让专门讲人话的模型替你写。

⚠️ 不太适合：纯一次性问答（杀鸡用牛刀）、需要 100% 离线无任何网络的环境（即便用 laya，pi 主线仍可能触发网络，桌面应用首发不主动下载 runtime，但用 provider 仍要走网）。

六、坑与注意

  1. 早期项目，命名/设置/格式可能再变——README 自承。生产关键路径别绑死到具体决策点名字上。
  2. Node 版本 ≥ 22.19：低版本装上会直接运行报错而不是温和提示，先 node -v。
  3. npm install lifecycle script 警告：按仓库 AGENTS.md 的 npm install --ignore-scripts + npm run check + ./test.sh 三步走；不要跳过 --ignore-scripts 又跑测试，因为本地测试需要 key，没 key 的部分会自动 skip。
  4. Laya judge 的边界：322M 本地参数，简单谓词稳，"元判断"（例如 turn.drift / hive.relate）偏弱——官方建议先 shadow 跑对比 jev，确认稳定再切。
  5. judge 看见的内容是"被裁过的字段"：每个决策点只把问题所需字段给 judge，不传全量工具输出或会话历史；这是设计但也意味着你不能用 judge 看到完整上下文做诊断。
  6. MU_JUDGE 环境变量只对单次 run 生效（MU_JUDGE=laya,jev mu -p "..."），不要期望它写到 config。
  7. 桌面应用开发模式：必须在仓库根 npm install 后，desktop/ 里 KYRN_ROOT="$(cd .. && pwd)" bun run start，否则跑的是 AionUi 的 demo，不会连到本仓库的 mu。
  8. License 双拼：根目录 LICENSE 覆盖 packages/ 与 kyrn/；desktop/ 自带独立 LICENSE（Apache 2.0，来自 AionUi）；二次分发注意两段 LICENSE 同时附上。
  9. hive 的 verifier bee 一分钟超时：未解决矛盾会再消耗一次算力；如果你的工作流频繁出矛盾，调高决策点的 active 比例或缩短子任务时长。
  10. 小模型 judge ≠ 万能：所有 yes/no 决策都依赖 judge 质量；如果你的领域术语很专有，先在 /mu mode ... shadow 下走几轮，对比人工判断再切。

七、与同类对比

  • vs Claude Code / Codex CLI / Gemini CLI：它们都是"一个工作模型 + 一个会话"范式，mu 的差异是显式列出 35 个决策点并把高频 yes/no 拆给独立 judge。对"长会话上下文管理 + 多 agent 协调 + 安全审计"三件事更结构化。
  • vs Cursor / Windsurf 等 IDE agent：IDE agent 强在编辑器集成，mu 的桌面应用是 AionUi 容器化的"独立窗口 + 内置浏览器"，不绑特定 IDE；CLI + 桌面应用二选一或并存。
  • vs Aider / Continue.dev：这两者更接近"补全 + 对话补丁"；mu 是端到端任务 agent，能跑子 swarm、能 spawn 后台 jobs、能用内置浏览器一步步操作网页。
  • vs LangGraph / AutoGen 这类多 agent 框架：mu 不暴露状态机 DSL，所有协调都由 hive + judge 内部决策；上手门槛低但灵活度低于自己写 graph。
  • vs 本地 Ollama + function calling：mu 也能接本地模型（llm:<provider>/<model>），但加了 35 个决策点的"模型侧护栏"，单独 Ollama + function calling 不会替你做 tool.risk / tool.admission 这种事。

八、一句话推荐

如果你受够了大模型在长 test 日志和命令安全确认上烧 token、又想要一个能跑子 agent swarm 的真·工作型 coding agent，mu 值得先在 shadow 模式跑两周——把决策点逐一比对 jev 与你的判断后再切 active；现在就指望它替代 Claude Code 不现实，毕竟项目还在"作者自用、命名可能再变"的早期。

研究文档（引用来源参考）

(no reference document available)