CLI Reference
根命令：
mushroom-agent <command> [options]
可用命令：
| 命令 | 说明 |
|---|---|
init | 初始化本地配置、secrets、prompts 和 node 设置 |
accesskey | 管理 agent server accesskeys |
start | 启动本地 agent server、接入当前本机 device runtime，并打开浏览器 UI |
serve | 启动 agent 服务与 API 通信入口 |
node | 连接远端服务与运行硬件诊断 |
tools | 查看已注册 tools |
skills | 列出、发现和安装 instruction skills |
memory | 把本地文件加入 agent memory |
eval-live | 对配置化本地 agent 运行 live eval cases |
eval-benchmark | 运行和对比 benchmark suites |
tui | 打开终端 UI |
mushroom-agent init
在 ~/.mushroom_agent/ 下初始化本地环境。命令会启动交互式引导，把文字模式或语音模式所需的模型配置写入 config.yaml。
mushroom-agent init
mushroom-agent init --root /custom/path
mushroom-agent init --force
mushroom-agent init --mode agent
mushroom-agent init --mode agent --run-mode voice
mushroom-agent init --mode node --server-url ws://host:7860 --access-key <accesskey>
默认生成：
config.yaml
node.yaml
<local secrets sidecar>
logs/
skills/
prompts/
SOUL.md
AGENTS.md
IDENTITY.md
APPROACH_GREETING.md
生成的 config.yaml starter 会尽量保持本地路径隐式。日志、默认 skills/ 目录、memory 存储、prompt 文件，以及工具工作目录都会在运行时从本地根目录派生。向导中输入的密钥会写入本地 secrets sidecar，并由 config.yaml 引用。node.yaml 包含 node 身份、远端接入设置和 builtin 设备能力设置，供 start 和 node attach 使用。
prompts/SOUL.md、prompts/AGENTS.md 和 prompts/IDENTITY.md 分别提供人格、规则和身份的 starter 文件。prompts/APPROACH_GREETING.md 用于调整摄像头接近事件的问候风格，只在该事件中读取。
选项：
| 选项 | 说明 |
|---|---|
--root | 指定本地环境根目录（默认：~/.mushroom_agent） |
--force | 覆盖已有生成文件 |
--mode agent|node | agent 写入 agent host 配置；node 只写入远端接入配置 |
--run-mode text|voice | agent 模式档位；跳过 Pure text / Voice 交互选择 |
--server-url | node 模式远端 server URL，例如 ws://host:7860 |
--access-key | node 模式使用的 accesskey，由 agent 主机签发 |
--node-name | node 模式的人类可读节点名 |
--proxy | node WebSocket 接入使用的可选出站代理 |
mushroom-agent accesskey
管理 agent server accesskeys。accesskey 明文只会在创建时打印一次；config.yaml 中保存 hash 和 preview。accesskey 不会自动过期，可用 disable 或 delete 撤销。
mushroom-agent accesskey create --name "Kitchen Pi" --node-id pi-kitchen
mushroom-agent accesskey list
mushroom-agent accesskey disable akid_xxx
mushroom-agent accesskey enable akid_xxx
mushroom-agent accesskey delete akid_xxx
accesskey list 会读取配置旁边的使用记录，并显示每个 accesskey 最近使用它的 node。
mushroom-agent start
启动配置化本地 agent server，并从 node.yaml 接入配置化本机 node runtime。浏览器 UI 默认启用；命令会打印 URL，并在服务就绪后自动打开浏览器。
export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent start
mushroom-agent start --host 127.0.0.1 --port 7860
选项：
| 选项 | 说明 |
|---|---|
--config | 指定配置文件路径 |
--host | UI server host（默认读取 server.host） |
--port | UI server port（默认读取 server.port） |
本地 UI 包含 Local I/O 视图，可查看配置化音频、文本、视频输入，User/Agent 语音文本，最新视频帧，命令摘要和硬件输出事件。
mushroom-agent serve
从 config.yaml 启动 agent 服务。这个命令是 HTTP chat、WebSocket chat、实时语音和函数通信的服务入口。
export MUSHROOM_SKIP_LANGFUSE_AUTH=1
mushroom-agent serve
选项：
| 选项 | 说明 |
|---|---|
--config | 指定配置文件路径 |
--communications | 逗号分隔的通信方式：http、websocket、func |
--port | HTTP 端口（默认：7860） |
浏览器测试页
本地浏览器测试使用 --ui。它会挂载 /web、打印 URL，并默认自动打开浏览器。
mushroom-agent serve --ui
| 选项 | 说明 |
|---|---|
--ui | 在 /web 挂载本地浏览器测试页 |
mushroom-agent node
将配置化设备 runtime 接入远端服务，或运行本地硬件诊断。本地进程内启动由 mushroom-agent start 负责。
node attach
将本设备 runtime 接入 node.yaml 中配置的远端 agent 服务。
# 1. 在 agent 主机上
mushroom-agent serve
# 2. 在每台设备上
mushroom-agent node attach
选项：
| 选项 | 说明 |
|---|---|
--config | 指定本地配置文件路径，并使用同目录下的 node.yaml |
--mode remote|standalone | node attach 的 runtime 模式，默认 remote |
--standalone-entry | --mode standalone 时使用的 Python 入口文件 |
--standalone-config | standalone node app 的可选 YAML 配置 |
node record-audio
采集本地音频，用于降噪 A/B 诊断。
mushroom-agent node record-audio --seconds 10
选项：
| 选项 | 说明 |
|---|---|
--seconds | 录音时长，单位秒 |
--config | 指定配置文件路径 |
mushroom-agent skills
管理已安装的 skills。
mushroom-agent skills list
mushroom-agent skills available
mushroom-agent skills available --source local --from ./skills
mushroom-agent skills available --source git --from https://github.com/org/skills.git
mushroom-agent skills install <name>
mushroom-agent skills install <name> --force
mushroom-agent skills install --source <repo-or-dir> --all --target ~/.mushroom_agent/skills
mushroom-agent tools
查看由 builtin 配置和 MCP discovery 注册出的 tools。
mushroom-agent tools list
mushroom-agent memory
把本地文本或 Markdown 文件加入 agent memory。
mushroom-agent memory add-file ./notes.md
mushroom-agent memory add-file ./notes.md --session sess-123 --modality document
选项：
| 选项 | 说明 |
|---|---|
--config | 指定配置文件路径 |
--session | 可选 session id；省略时写入 agent-wide public memory |
--modality text|document | memory resource modality |
mushroom-agent eval-live
对配置化本地 agent 运行 live eval cases。除非设置 --dry-run，否则会使用真实配置的 LLM。
mushroom-agent eval-live --suite smoke --dry-run
mushroom-agent eval-live --suite all --samples 2 --no-enable-judge
mushroom-agent eval-live --case-id <case-id> --enable-judge
关键选项：
| 选项 | 说明 |
|---|---|
--config | 指定配置文件路径 |
--suite smoke|all | eval suite |
--capability | 按 capability tag 过滤 |
--case-id | 按 id 只运行单个 case |
--samples | 每个 case 的独立 sample 数 |
--enable-judge / --no-enable-judge | 启用或关闭 LLM-as-judge metrics |
--judge-metrics | 逗号分隔的 judge metric ids |
--dry-run | 只加载配置和 cases，不调用 LLM 或 judge |
--case-timeout | 每个 sample 的超时时间，单位秒 |
--write-baseline | 写入 candidate baseline 文件 |
--silence | 静默日志 |
mushroom-agent eval-benchmark
运行 benchmark cases，或对比 benchmark summaries。
mushroom-agent eval-benchmark run --suite smoke --dry-run
mushroom-agent eval-benchmark run --suite all --samples 3 --label candidate
mushroom-agent eval-benchmark compare --against baseline.json --candidate candidate.json
eval-benchmark run 支持大多数 live-eval 过滤参数，并增加 --output-dir、--label 等 benchmark 输出控制。eval-benchmark compare 用延迟和 pass-rate 阈值对比两个 summary JSON 文件。
mushroom-agent tui
打开终端 UI。它可以读取本地配置，也可以接入已有 server。
mushroom-agent tui
mushroom-agent tui --host 127.0.0.1 --port 7860
mushroom-agent tui --attach-url ws://127.0.0.1:7860/ws/v1/chat --accesskey <accesskey>
Local vs Remote
启动服务/API 路径并挂载 /web。
Agent 与配置化设备 runtime 在一个进程内运行，并打开本地 UI。
在主机上启动 agent，再将一台或多台配置化设备接入它。