@arcships/morula-runtime 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -1,11 +1,11 @@
 # @arcships/morula-runtime
 
-Morula 本地智能体运行时的设备端 CLI：登录、守护进程（daemon）启停、本地助手门户与模型清单。通过 npm 全局安装，无需单独下载二进制。
+Morula 本地智能体运行时的设备端 CLI：登录、守护进程（daemon）启停、本地助手门户、模型清单与**本机诊断**。通过 npm 全局安装，无需单独下载二进制。
 
 ## 环境要求
 
 - 本机需安装 **Node.js >= 20**
-- 可访问 Morula 服务端（默认测试环境 `https://morula.basecastle.com`）
+- 可访问 Morula 服务端（默认生产环境 `https://morula.fazhiplus.com`）
 
 ## 安装
 
@@ -19,6 +19,9 @@ npm i -g @arcships/morula-runtime
 ## 快速开始
 
 ```bash
+# 0.（可选）先看看本机现状：配置/凭证/daemon/dim 一次看全（只读，不写任何东西）
+morula-runtime daemon doctor
+
 # 1. 登录（自动打开浏览器完成 SkyDoor SSO）
 morula-runtime auth login
 
@@ -32,36 +35,130 @@ morula-runtime daemon portal --autostart on
 验证：
 
 ```bash
-morula-runtime --version        # 输出版本号
+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. 分层帮助，可按需取用**（不必读全量命令面）
+
+```bash
+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` 并返回可执行提示，不会静默接受：
+
+```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）
+
+## 退出码
+
+| 码 | 含义 |
 |---|---|
-| `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` 开机自启） |
+| 0 | 成功（`daemon doctor`：全部检查通过，含 `warn`） |
+| 1 | 其他错误（**`daemon doctor`：检查发现问题**——注意这不是「命令失败」，详情看 `checks[]`） |
+| 2 | 用法错误（缺值 / 未知旗标 / 未知命令 / 枚举非法 / 多余位置参数） |
+| 3 | 未找到 |
+| 4 | 未登录 |
+| 5 | 无权限 |
+| 6 | 冲突（如 daemon 已在运行） |
+| 7 | 上游/网络错误 |
+
+## 排障：先跑 `daemon doctor`
+
+一条只读命令给出本机全部相关事实（配置路径、连接环境、凭证来源、daemon 与锁状态、dim 定位、影响解析的环境变量名）与检查项：
 
-命令输出为 JSON；错误也会以 JSON 输出到 stderr。
+```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 prod <命令>
+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
@@ -72,11 +169,13 @@ npm rm -g @arcships/morula-runtime
 
 ## 常见问题
 
-- **登录失败或已失效**：重新执行 `morula-runtime auth login`。
-- **daemon 启动报未登录**：先完成登录再 `morula-runtime daemon start`。
-- **连接环境不对**：用 `--env` / `--url` 指定，或检查 `~/.morula-cli/config.yaml`。
+- **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` 共用登录态）
+- 业务命令 CLI：`morula`（随智能体插件提供，与 `morula-runtime` 共用登录态）

package/bin/morula.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * 业务命令面发布入口：`morula` = Morula 业务 CLI（task / repo / comment / review / space / attachment / report）。
+ *
+ * 与 `morula-runtime` 同属 `@arcships/morula-runtime` 单包（docs/features/single-package-cli-distribution.md）：
+ * bin 指向本文件，本文件 import 构建产物 dist/morula.js（由 @morula/morula-cli 入口 bundle 而来）。
+ * 本地开发走 `pnpm dev:morula`（tsx 直接跑源码），不经过本文件。
+ */
+import '../dist/morula.js'