# @arcships/morula-runtime 中文文档

规范地址：https://npmcn.com/package/%40arcships/morula-runtime/

版本：0\.1\.3
npm 元数据更新时间：2026-10-30T09:27:52.468Z
中文译文更新时间：2026-11-08T07:46:27.713Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40arcships/morula-runtime
原文对照：https://npmcn.com/package/%40arcships/morula-runtime/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-09-01T10:15:06.017Z
- 最新版本发布：2026-10-30T09:27:52.296Z
- 近 30 天下载量：1863（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

莫鲁拉本地代理运行时间(daemon/portal/models/auth)和莫鲁拉商业CLI(morula)的设备级CLI,通过npm分发

## 安装

```sh
npm install @arcships/morula-runtime
```

也可以使用：`pnpm add @arcships/morula-runtime`、`yarn add @arcships/morula-runtime`、`bun add @arcships/morula-runtime`

## README

# @arcships/morula-runtime

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

## 环境要求

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

## 安装

```bash
npm i -g @arcships/morula-runtime
```

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

## 快速开始

```bash
# 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
```

验证：

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

## 常用命令

| 命令 | 说明 | 写状态 |
| --- | --- | --- |
| `morula-runtime auth login` | 登录（浏览器 SSO；**会阻塞等人**） | 本机 |
| `morula-runtime auth logout` | 退出登录 | 本机 |
| `morula-runtime auth status` | 查看登录状态与当前环境 | 只读 |
| `morula-runtime env list` | 列出本机可用环境（URL / 是否有凭证 / 默认是哪个 / 本次命中哪个） | 只读 |
| `morula-runtime env use <name>` | 切换默认环境（不带 `--env` 的命令都用它） | 本机 |
| `morula-runtime daemon start` | 后台启动 daemon | 本机 |
| `morula-runtime daemon stop` | 停止 daemon | 本机 |
| `morula-runtime daemon status` | daemon 状态（含该 daemon 归属的环境） | 只读 |
| `morula-runtime daemon models` | 本机可用模型清单 | 只读 |
| `morula-runtime daemon portal` | 运行本地助手门户（`--autostart on` 开机自启） | 本机 |
| `morula-runtime daemon doctor` | **本机诊断**：配置/凭证/daemon/dim 事实 + 检查项（默认离线） | 只读 |

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

## 环境（多环境共存）

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

```bash
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 命令）：

```json
{ "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\. 分层帮助，可按需取用**（不必读全量命令面）

```bash
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` 并返回可执行提示，不会静默接受：

```jsonc
// 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\. 破坏性动作可先预览**

```bash
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 定位、影响解析的环境变量名）与检查项：

```bash
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` 共用）
-   默认连接生产环境；切换环境/服务地址：

```bash
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` 确认。

## 卸载

```bash
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` 共用登录态）

## 常见问题

### @arcships/morula-runtime 是什么？

莫鲁拉本地代理运行时间\(daemon/portal/models/auth\)和莫鲁拉商业CLI\(morula\)的设备级CLI,通过npm分发

### 如何安装 @arcships/morula-runtime？

在项目目录运行 npm install @arcships/morula-runtime，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 morula、morula-runtime，可以用 npx morula 直接运行。

### @arcships/morula-runtime 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/arcships\_\_morula-runtime 是否存在。

### @arcships/morula-runtime 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @arcships/morula-runtime 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @arcships/morula-runtime 可以商用吗？

@arcships/morula-runtime 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @arcships/morula-runtime 的下载量有多少？

根据 npm 官方下载统计，@arcships/morula-runtime 在 2026/10/07 – 2026/11/05 这 30 天内被下载 1,863 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @arcships/morula-runtime 还在维护吗？

最新版本 0\.1\.3 发布于 2026/10/30（9 天前）；至今共发布 33 个版本，其中过去 12 个月发布了 33 个；首次发布于 2026/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。