@arcships/morula-runtime

Morula 本地智能体运行时的设备端 CLI：登录、守护进程（daemon）启停、本地助手门户、模型清单与本机诊断。通过 npm 全局安装，无需单独下载二进制。

环境要求

• 本机需安装 Node.js >= 20
• 可访问 Morula 服务端（默认生产环境 https://morula.fazhiplus.com）

安装

npm i -g @arcships/morula-runtime

默认安装最新版（latest dist-tag 跟随最新发布）；历史版本可用 @alpha 等 tag 安装。 安装后使用命令：morula-runtime

快速开始

# 0.（可选）先看看本机现状：配置/凭证/daemon/dim 一次看全（只读，不写任何东西）
morula-runtime daemon doctor

# 1. 登录（自动打开浏览器完成 SkyDoor SSO）
morula-runtime auth login

# 2. 启动 daemon（后台运行）
morula-runtime daemon start

# 3. 可选：启动本地助手门户（浏览器访问 http://127.0.0.1:23491，可一键启停 daemon）
morula-runtime daemon portal --autostart on

验证：

morula-runtime --version        # 输出版本号 + 构建标识
morula-runtime daemon status    # daemon 运行状态

常用命令

命令输出为 JSON（stdout）；错误也是 JSON（stderr）。

环境（多环境共存）

一份配置里可以有多个环境并存（contexts），默认环境由 defaultEnv 表达：

morula-runtime --env test auth login   # 登录 test（只写 contexts.test 的 token，不改默认环境）
morula-runtime env use test            # 把默认环境设为 test（此后不带 --env 的命令都打 test）
morula-runtime env list                # 看清单与本次命中的环境
morula-runtime daemon status           # 看这个 daemon 归属哪个环境（daemon run 启动时记录）

顺序：--env > MORULA_ENV > --url 推导 > defaultEnv > 内建默认（prod）。 auth login / auth logout 只动「该环境的凭证」，不会搬走默认环境；旧配置里的 currentContext 不再被读取 （详见 docs/features/cli-env-selection.md）。

portal 多环境路由

一份 portal（固定端口 23491）可服务本机全部环境的 daemon 实例，不再与单一配置目录绑定 （设计契约见 docs/features/portal-multi-env-routing.md，背景见 docs/research/runtime-dev-prod-coexist.md）：

• portal 扫描本机候选配置目录（~/.morula-cli + ~/.morula-cli-*，可用 MORULA_PORTAL_CONFIG_DIRS 逗号分隔追加自定义目录），把每个目录 config.yaml 里 contexts 声明的全部环境建成 「归一化 API base URL → 配置目录」索引；该目录 daemon.env 命中的环境优先（正在跑它的目录优先命中）；
• /portal/status、/portal/start、/portal/stop 支持可选 query server=<服务端 API base URL>： token 校验、pid 读写、spawn 的 MORULA_CONFIG_DIR / MORULA_ENV 全部作用于目标环境实例； 不传 server = 旧行为（portal 自身配置目录，向后兼容）；
• 未索引的目标 → 404 UNKNOWN_ENV（fail closed，不向该地址发任何请求）； 目标环境未 auth login → 409 ENV_NOT_LOGGED_IN（hint 里给出 MORULA_CONFIG_DIR=<目录> morula-runtime auth login）；
• status 响应带 envRouting: true 与自身 context / baseUrl 归属字段，供前端识别。

安全边界不变：只监听回环、只暴露 status/start/stop、token 由目标环境服务端签发并校验。 升级 runtime 后需重启 portal（开机自启场景：morula-runtime daemon portal --autostart off 后重新 --autostart on）才生效。

MCP 接入（Claude Desktop / Cursor / Claude Code 等）

安装本包后，在 MCP 客户端配置里直接粘贴（零前置步骤，无需先跑任何 morula 命令）：

{ "mcpServers": { "morula": { "command": "morula", "args": ["mcp"] } } }

• 工具面 = morula 业务命令面全部工具（读 + 写），由 SPEC 契约机械生成；凭证取自 morula auth login 保存的 context；
• 只想暴露部分资源（控制工具数量）："args": ["mcp", "--resource", "task,repo"]；
• 可选便利：morula mcp setup --client claude-desktop,cursor 自动写入客户端配置（备份原文件、只动 mcpServers.morula）；morula mcp config 打印片段；
• GUI 客户端 PATH 解析不到 morula 时，把 command 改为绝对路径（which morula）。

给智能体 / 脚本使用

本 CLI 按「可被程序可靠调用」设计，几点值得利用：

1. 分层帮助，可按需取用（不必读全量命令面）

morula-runtime --help                    # 顶层人读帮助（dim 风格 + resources 概览）
morula-runtime daemon --help             # 只含 daemon 的 actions（人读，含 write/interactive 标记）
morula-runtime daemon start --help       # 该 action 的完整契约（人读）：args/flags/examples/writes
morula-runtime --help --json             # 机器可读命令面（agent 消费；resource/action 作用域同样支持）

action 级帮助里每个旗标都带 type / required / enum / default，输出字段列在 emits，可直接据此构造调用。

2. writes 与 interactive：不试跑就能判断安全性

• writes: none → 只读，随便调；local → 改本机（配置/进程/开机自启项）；remote → 打服务端写接口。
• interactive: true → 会阻塞等人（当前只有 auth login，最长 MORULA_LOGIN_TIMEOUT_MS，默认 300s），无人值守场景别调。

3. 失败会明确报错，且给出下一步

畸形输入一律 exit 2 并返回可执行提示，不会静默接受：

// morula-runtime daemon start --name   （漏写值）
{ "code": "USAGE", "message": "missing value for --name",
  "hint": "morula-runtime daemon start [--name <name>] ...  (e.g. --name <name>)" }

// morula-runtime daemons               （命令名拼错）
{ "code": "USAGE", "message": "unknown command: daemons",
  "hint": "morula-runtime --help", "didYouMean": "daemon" }

4. 破坏性动作可先预览

morula-runtime daemon start --dry-run              # 打印将执行的命令/路径，不启动任何进程
morula-runtime daemon stop --dry-run               # 打印将停止的 pid，不做任何变更
morula-runtime daemon portal --autostart off --dry-run

5. --json / -h / -v 可用（--json 是 no-op：输出本来就是 JSON）

退出码

排障：先跑 daemon doctor

一条只读命令给出本机全部相关事实（配置路径、连接环境、凭证来源、daemon 与锁状态、dim 定位、影响解析的环境变量名）与检查项：

morula-runtime daemon doctor            # 默认离线：不联网、不写文件、不启动进程
morula-runtime daemon doctor --probe    # 额外联网校验登录态

• 输出的 facts.tokenSource 告诉你凭证是从哪读到的（flag / env:MORULA_TOKEN / config:<context>）， 排「读到的不是我以为的那份配置」很有效；绝不回显 token 本体。
• checks[] 每项带 hint，给出可执行的下一步（如未登录 → morula-runtime auth login）。
• 若设置了 MORULA_CONFIG_DIR / MORULA_CONFIG，会明确提示「配置路径被环境变量覆盖」——多环境隔离时最容易踩。

配置

• 配置文件：~/.morula-cli/config.yaml（登录后自动生成；与业务 CLI morula 共用）
• 默认连接生产环境；切换环境/服务地址：

morula-runtime --env test <命令>
morula-runtime --url https://你的服务地址/api <命令>
morula-runtime --token <token> <命令>   # 仅本次生效，不落盘

• 环境变量：MORULA_ENV（连接环境）、MORULA_CONFIG_DIR（隔离整套配置与 daemon 状态，多环境并行时用）、 MORULA_CONFIG（配置文件路径）、MORULA_API_URL、MORULA_TOKEN（显式凭证，不落盘）、 MORULA_PORTAL_PORT、MORULA_DAEMON_WORKDIR。 同名变量是否已生效可用 morula-runtime daemon doctor 的 facts.envOverrides 确认。

卸载

morula-runtime daemon portal --autostart off   # 如已开启自启
morula-runtime daemon stop
npm rm -g @arcships/morula-runtime

常见问题

• daemon 启动报未登录：morula-runtime daemon doctor 看 auth.token 检查项与 tokenSource； 需要时重新 morula-runtime auth login。
• 任务没人执行：morula-runtime daemon doctor —— daemon.running 为 warn 说明 daemon 没在跑。
• 连接环境不对：用 --env / --url 指定；检查 doctor 的 facts.context / baseUrl 与 envOverrides。
• daemon 已在运行（exit 6）：先 morula-runtime daemon status 确认，需要强制重启再 kill -9 <pid>。

相关

• Morula 平台（服务端 + Web）
• 业务命令 CLI：morula（随智能体插件提供，与 morula-runtime 共用登录态）