@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 运行状态

常用命令

| 命令 | 说明 | 写状态 | |---|---|---| | morula-runtime auth login | 登录（浏览器 SSO；会阻塞等人） | 本机 | | morula-runtime auth logout | 退出登录 | 本机 | | morula-runtime auth status | 查看登录状态与当前环境 | 只读 | | morula-runtime daemon start | 后台启动 daemon | 本机 | | morula-runtime daemon stop | 停止 daemon | 本机 | | morula-runtime daemon status | daemon 状态 | 只读 | | morula-runtime daemon models | 本机可用模型清单 | 只读 | | morula-runtime daemon portal | 运行本地助手门户（--autostart on 开机自启） | 本机 | | morula-runtime daemon doctor | 本机诊断：配置/凭证/daemon/dim 事实 + 检查项（默认离线） | 只读 |

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

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 的 currentContext 建「归一化 API base URL → 配置目录」索引；
• /portal/status、/portal/start、/portal/stop 支持可选 query server=<服务端 API base URL>： token 校验、pid 读写、spawn 的 MORULA_CONFIG_DIR 全部作用于目标环境实例； 不传 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（launchd 场景：morula-runtime daemon portal --autostart off 后重新 --autostart on）才生效。

给智能体 / 脚本使用

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

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

morula-runtime --help                    # 顶层菜单 + resources 概览
morula-runtime daemon --help             # 只含 daemon 的 actions（含 writes/interactive）
morula-runtime daemon start --help       # 该 action 的完整契约：args/flags/examples/writes/emits

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

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

• writes: none → 只读，随便调；local → 改本机（配置/进程/LaunchAgent）；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）

退出码

| 码 | 含义 | |---|---| | 0 | 成功（daemon doctor：全部检查通过，含 warn） | | 1 | 其他错误（daemon doctor：检查发现问题——注意这不是「命令失败」，详情看 checks[]） | | 2 | 用法错误（缺值 / 未知旗标 / 未知命令 / 枚举非法 / 多余位置参数） | | 3 | 未找到 | | 4 | 未登录 | | 5 | 无权限 | | 6 | 冲突（如 daemon 已在运行） | | 7 | 上游/网络错误 |

排障：先跑 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 共用登录态）