前置条件
- 1macOS 12+ 或 Linux（Ubuntu 22.04+/Debian 12+ 验证通过，Windows 需 WSL2）
- 2已安装 Node.js 20+ 与 npm/pnpm（用于 skills 插件市场）
- 3持有 Meta 账号或 API Key（Contributor 档需同意数据用于训练）
- 4终端基础：会用 cd/ls/编辑器，了解 PATH 概念
腾讯智能体开发平台 ADP
新客首月专属价，最高直降 880 元，构建/分发/治理企业级 Agent
Muse Code 是 Meta 超级智能实验室于 2026 年 8 月 5 日发布的首个专用编码 Agent，和 Muse Spark 1.2 基座模型（1M token 上下文）共同训练。它不是又一个聊天式补全工具，而是一个能跑数小时长任务、可中断恢复、能编排多个持久化 subagent 的终端 Agent。
和 Claude Code、OpenAI Codex 相比，Muse Code 的差异点有三个：append-only 事件日志（session 可重放、重启安全）、多 subagent 持久化编排、Contributor 档 $0.10/MTok 的激进定价。代价是它仍是 beta，且 Contributor 档会用你的数据训练。
本教程走双路径接入：方式 A 给想 5 分钟跑起来的人，方式 B 给要批量部署、CI 集成、细粒度控费的人。
双路径接入对比
| 维度 | 方式 A：应用端交互 | 方式 B：配置文件手动 |
|---|---|---|
| 适合人群 | 首次接入、单机试用 | 团队批量部署、CI/CD 集成 |
| 配置载体 | muse init 引导问答 | 编辑 ~/.muse/config.toml |
| 档位切换 | 每次启动选 | config.toml 锁定默认档 |
| subagent worktree | 交互式开启 | 配置项固化 |
| 事件日志清理 | 手动 prune | max_age_days 自动清 |
| 上手速度 | 5 分钟 | 15 分钟（含模板编写） |
提示
💡 小白提示：第一次用先走方式 A 把流程跑通，看清每一步在问什么；第二次起切方式 B，把答案固化成 config.toml，省掉重复问答。
前置准备
在开始前，确认你的环境满足以下条件，否则会在初始化阶段卡住：
1# 1. 操作系统检查（Muse Code 暂不支持原生 Windows）
2uname -s
3# 期望输出：Darwin（macOS）或 Linux
4
5# 2. Node.js 版本（skills 插件市场依赖）
6node -v
7# 期望输出：v20.x.x 或更高
8
9# 3. 磁盘空间（事件日志 + subagent worktree 会占空间）
10df -h ~
11# 建议至少留 5GB
12
13# 4. git 已配置（worktree 隔离模式依赖）
14git config --global user.name
15git config --global user.email警告
⚠️ 重要警告：Contributor 档位 $0.10/MTok 的定价背后是数据用于训练。如果你的代码仓库含客户数据、生产密钥、未公开业务逻辑，绝对不要用 Contributor 档，请全程使用 Standard 档（$1.25/$4.25 per MTok）或自托管 Spark 1.2 权重。
方式 A：应用端交互接入
方式 A 用 muse init 的引导问答完成首次配置，全程零手写文件，适合第一次接触 Muse Code 的人。
第 1 步：安装 Muse Code CLI
Muse Code 用官方安装脚本分发，不依赖 npm 全局安装（避免权限问题）：
1# macOS / Linux 一键安装
2curl -fsSL https://muse.meta.ai/install.sh | bash
3
4# 安装脚本会把 muse 二进制放到 ~/.muse/bin
5# 自动追加 PATH 到 ~/.zshrc 或 ~/.bashrc
6
7# 验证安装
8muse --version
9# 期望输出：muse code 0.4.x (spark 1.2)
10
11# 如果提示 command not found，手动 source 一下
12source ~/.zshrc # 或 source ~/.bashrc第 2 步：首次初始化与档位选择
在你想接入的项目根目录执行：
1cd ~/projects/my-app
2muse init引导问答会依次问：
- Choose a tier：选
standard（安全默认）或contributor（便宜但数据训练）。⚠️ 选 contributor 前确认此项目无敏感数据。 - API key or Meta account?：API key 适合 CI；Meta account 适合交互式（会打开浏览器登录）。
- Enable subagent worktree isolation?：建议选
yes，多 subagent 改同库不会互相覆盖。 - Events log retention (days)?：填
7，事件日志保留 7 天自动清理。 - Default plan mode?：选
approval-gated，长任务改动前必须你确认。
完成后会生成 .muse/config.toml（项目级）和追加到 ~/.muse/config.toml（全局级）。
提示
💡 小白提示：第 5 步选 approval-gated 是关键。Muse Code 的 /plan 会在执行前生成 plan 文件等你审批，这是防止 Agent 跑偏的最后一道闸门。选 auto 等于把方向盘交出去了。
第 3 步：跑通第一个任务
1# 在项目根目录启动交互 session
2muse
3
4# 进入交互后输入：
5> /plan 把 src/utils/date.ts 里的 moment.js 全部换成 dayjs，先列影响范围再动手
6
7# Muse Code 会：
8# 1. 生成 plan 文件（.muse/plans/xxx.md）列出所有受影响文件
9# 2. 等你输入 approve 才开始改
10# 3. 改动过程实时写入 append-only 事件日志看到 plan 被 approve 并开始执行，说明方式 A 接入成功。
方式 B：配置文件手动接入
方式 B 直接编辑 ~/.muse/config.toml，适合要批量部署到多台机器、或把配置纳入 Git 版本管理的团队。
第 1 步：创建全局配置文件
1mkdir -p ~/.muse
2cat > ~/.muse/config.toml << 'EOF'
3# Muse Code 全局配置
4# 完整字段参考：muse config --print-defaults
5
6[tier]
7# 默认档位：standard（$1.25/$4.25）或 contributor（$0.10/$0.20，数据训练）
8default = "standard"
9
10[auth]
11# 方式一：API Key（CI 友好，从 https://muse.meta.ai/api-keys 获取）
12api_key = "msk-xxxxxxxxxxxxxxxxxxxx"
13# 方式二：Meta account token（交互登录后生成，留空则首次启动触发浏览器登录）
14# account_token = ""
15
16[subagent]
17# 每个 subagent 跑在独立 git worktree，避免文件冲突
18worktree = true
19# 单个 session 最多并发 subagent 数（防止 OOM）
20max_concurrent = 4
21
22[events]
23# 事件日志保留天数，超期自动清理
24max_age_days = 7
25# 事件日志目录（SSD 路径写入更快）
26dir = "~/.muse/events"
27
28[plan]
29# approval-gated：改动前必须 approve；auto：直接执行
30default_mode = "approval-gated"
31# plan 文件保留数（用于 resume 历史）
32keep_plans = 50
33
34[context]
35# Spark 1.2 支持 1M token，但越长越贵，按项目规模调
36max_tokens = 200000
37EOF第 2 步：项目级配置覆盖
在项目根目录建 .muse/config.toml，只写需要覆盖全局的字段：
1mkdir -p .muse
2cat > .muse/config.toml << 'EOF'
3# 项目级配置，覆盖全局同名键
4[context]
5# 这个仓库较大，给到 500K
6max_tokens = 500000
7
8[tier]
9# 此项目无敏感数据，临时用 contributor 省成本
10default = "contributor"
11
12[subagent]
13# 此项目模块边界清晰，关掉 worktree 省磁盘
14worktree = false
15EOF警告
⚠️ 重要警告：项目级 config.toml 里把 tier 设成 contributor 时，务必把 .muse/config.toml 加入 .gitignore，否则同事 clone 后不知不觉用 contributor 档跑了敏感代码。建议在 config.toml 同目录放一个 .gitignore 只排除自身。
第 3 步：非交互式跑任务（CI 友好）
方式 B 的最大价值是能在 CI 里无交互跑任务：
1# 非交互模式：从 plan 文件直接执行，不需要 approve
2muse run --plan .muse/plans/upgrade-dayjs.md --no-interactive
3
4# 或从 stdin 喂任务
5echo "给 src/api/*.ts 补 OpenAPI 注释" | muse run --tier standard场景应用示例
Muse Code 内置三个 skill，覆盖日常 80% 的编码 Agent 场景：
场景 1：/plan —— 大重构前的审批门控
1muse
2> /plan 把整个项目从 CommonJS 迁移到 ESM，分 3 个阶段，每阶段生成可独立验证的 commit/plan 会生成 plan 文件，列出：受影响文件清单、改动顺序、每阶段的验证点。你 approve 后才执行。这是长任务防跑偏的核心 skill。
场景 2：/grill —— 压力测试你的计划
1> /grill .muse/plans/upgrade-dayjs.md/grill 会从 5 个维度拷问 plan：边界条件、回滚路径、性能影响、测试覆盖、依赖冲突。等价于让另一个 Agent 当"魔鬼代言人"挑刺，plan 过了 /grill 才值得 approve。
场景 3：/goal —— 长跑型自主任务
1> /goal 监控 src/ 下所有 .ts 文件，一旦 eslint 报 error 就自动修复并跑测试，持续 8 小时/goal 适合长跑型任务，配合 append-only 事件日志，即使中途 OOM 也能 muse resume <id> 接着跑。
提示
💡 小白提示：/goal 跑长任务前，先 /plan 出一份执行计划，再 /grill 拷问一遍，最后把通过拷问的 plan 喂给 /goal 去长跑。这个"plan → grill → goal"三件套是 Muse Code 的标准长任务工作流。
最佳实践
- 档位隔离：敏感项目全局锁
standard，非敏感项目级覆盖contributor，绝不让 contributor 成为默认。 - plan 优先：任何超过 5 个文件的改动，强制走
/plan审批门控，拒绝/goal裸跑。 - 事件日志巡检：每周
muse events prune --keep 7d一次，别等磁盘满才清。 - worktree 隔离：多 subagent 同库开发必开
subagent.worktree = true，否则文件互相覆盖是迟早的事。 - resume 而非重跑：长任务中断后优先
muse resume <session-id>，append-only 日志保证状态恢复，重跑会丢上下文。
故障排查
| 现象 | 原因 | 解决 |
|---|---|---|
muse: command not found | PATH 未生效 | source ~/.zshrc 或手动 export PATH="$HOME/.muse/bin:$PATH" |
Error: tier contributor requires data consent | 未同意 Contributor 数据条款 | muse consent --contributor 交互式确认，或改用 standard 档 |
Plan approval timeout | /plan 等你 approve 超时 | 默认 10 分钟超时，config.toml 加 [plan] approval_timeout = 3600 延长 |
subagent worktree creation failed | git 仓库未初始化或 worktree 目录权限 | git status 确认是 git 仓库；chmod 755 .git/worktrees |
events log corrupt, cannot resume | 事件日志被手动编辑或截断 | 删除该 session 的 .jsonl 文件，任务只能从头重跑（所以别手编日志） |
OOM killed during /goal | subagent 并发太多撑爆内存 | config.toml 把 subagent.max_concurrent 从 4 降到 2，或 [context] max_tokens 调小 |
Spark 1.2 context length exceeded | 项目超出 1M token 上下文 | 用 /plan 拆成多个子任务；或在 config.toml 限定 max_tokens 让 Agent 主动分批 |
接入完成后，建议先在一个非关键分支跑一次 /plan + /grill + /goal 全流程，验证事件日志、worktree 隔离、resume 都正常，再投入生产任务。Muse Code 仍是 beta，每个版本行为可能微调，升级前看 muse changelog 的 breaking changes 项。
常见问题
QContributor 档 $0.10/MTok 这么便宜，会有什么坑？
Contributor 档的代价是 Meta 会用你的 Prompt 和补全数据做训练。所以敏感代码（含密钥、客户数据、未公开业务逻辑）一律走 Standard 档或本地 Spark 自托管。配置时在 ~/.muse/config.toml 把 tier = 'standard' 设为默认，仅在非敏感项目用 muse --tier contributor 临时切换。
Qappend-only 事件日志占满了磁盘怎么办？
Muse Code 把事件日志存在 ~/.muse/events/，每个 session 一个 .jsonl 文件。用 muse events prune --keep 7d 保留近 7 天，或直接编辑 config.toml 加 events.max_age_days = 7 自动清理。切勿手动删整个 events 目录，会让正在跑的长任务无法 resume。
Q长任务跑到一半 OOM 被杀，重跑会不会从头来？
不会。Muse Code 的 append-only 日志保证重启安全：muse resume <session-id> 会从最后一个 checkpoint 接着跑。前提是任务用了 /plan 审批门控（plan 文件即 checkpoint），裸跑的 /goal 任务只能从最近的工具调用边界恢复。
Qsubagent 之间会互相覆盖文件吗？
默认会，因为 subagent 共享同一工作目录。要隔离就开 worktree 模式：config.toml 里 subagent.worktree = true，每个 subagent 跑在独立 git worktree，最后由主 agent 合并。和 Orca 多 Agent 的 worktree 隔离思路一致。