@arcships/morula-runtime 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "morula-cli",
+  "version": "0.1.0-alpha.3",
+  "description": "Use Morula CLI task management from DimCode.",
+  "interface": {
+    "displayName": "Morula CLI",
+    "shortDescription": "Operate Morula task management from DimCode."
+  },
+  "skills": "./skills"
+}

package/dist/plugin/skills/morula-cli/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: morula-cli
+description: 使用 Morula CLI 管理任务、空间、成员、评论与自动化报告。当用户要求操作 Morula 任务系统或产出自动化报告时使用。
+---
+
+# Morula CLI
+
+## 能力速查
+
+| 操作 | 命令 | 风险 | 审批 |
+|------|------|------|------|
+| 查任务 | `morula task list [flags]`（`--mine` 仅我负责） | `read_only` | 自动 |
+| 任务详情 | `morula task get <id>` | `read_only` | 自动 |
+| 创建任务 | `morula task create --space <id> --title "标题" [flags]` | `write_internal` | **需确认** |
+| 更新任务 | `morula task update <id> [flags]` | `write_internal` | **需确认** |
+| 删除任务 | `morula task delete <id>` | `destructive` | **需预演+确认** (硬删除) |
+| 查空间 | `morula space list [flags]` | `read_only` | 自动 |
+| 空间详情 | `morula space get <id>` | `read_only` | 自动 |
+| 查成员 | `morula space-member list --space <id>` | `read_only` | 自动 |
+| 添加成员 | `morula space-member add --space <id> --principal <id> [--role <admin|member>]` | `identity_access` | **需确认** |
+| 移除成员 | `morula space-member remove <member-id>` | `identity_access` | **需确认** |
+| 查看评论 | `morula comment list --object <id>` | `read_only` | 自动 |
+| 添加评论 | `morula comment add --object <id> --content "内容"` | `write_internal` | **需确认** |
+| 删除评论 | `morula comment delete <id>` | `destructive` | **需预演+确认** (硬删除) |
+| 产出报告 | `morula report create --title "标题" --content-file <path>` | `write_internal` | 自动（见下方「何时产出报告」） |
+| 查看报告 | `morula report list --autopilot <id>` / `morula report get <id>` | `read_only` | 自动 |
+| 归档报告 | `morula report archive <id>` | `write_internal` | **需确认** |
+| 上传文件 | `morula attachment upload <file> --object <id>`（挂任务）/ `--comment <id>`（挂评论） | `write_internal` | **需确认** |
+
+完整参数见 [commands.md](references/commands.md)。
+
+## 何时产出报告（`morula report create`）
+
+报告是**归属于某个自动化**的产出域（正文为 Markdown），人从该自动化的卡片「报告」入口查看——不进任务看板、不占任务编号、也不写进评论。判据：
+
+- **该产出**：一次执行得出的**结论型重内容**——扫描/巡检结果、审查结论、分析摘要、对比清单、需要留档的建议。产出后可另用 `morula task create` 建任务跟进。
+- **不该产出**：过程性进度、寒暄、需要人立刻拍板的一句话（短信息走评论/收件箱，只有重内容进报告域）；终端输出用户看不到，需要留档的结论必须落到报告或评论。
+- 一次执行可产 0..N 份，份数由 agent 判断；长报告先写进文件再用 `--content-file <path>`（超长正文不要塞进 `--content` 命令行）。
+- `--autopilot` 仅在**没有执行上下文**时才需要显式传：在 agent 任务里省略，服务端按当前任务反查所属自动化并自动绑定 `runId`；若服务端返回「当前执行上下文未关联自动化」，才补 `--autopilot <id>`。
+
+## 审批规则
+
+| 风险等级 | Agent 行为 |
+|---------|-----------|
+| `read_only` | 直接在终端执行，结果格式化展示 |
+| `write_internal` | 向用户确认"即将创建/更新 [资源名]，确认？"，用户同意后执行 |
+| `destructive` | 先 `get <id>` 展示将被删除的资源详情 → 用户确认 → 执行，不可自动重试 |
+
+## 操作前收集
+
+| 操作 | 必需信息 | 获取方式 |
+|------|---------|---------|
+| 创建任务 | `spaceId`, `title` | `space list` 获取 spaceId；用户提供 title |
+| 更新任务 | `taskId` | `task list` 获取目标 taskId |
+| 删除任务 | `taskId` | `task list` 获取 → `task get <id>` 确认标题/空间后删除 |
+| 管理成员 | `spaceId`, `principalId` | `space-member list --space <id>` 获取 |
+| 管理评论 | `objectId`, `content` | `task get <id>` 获取 objectId；用户提供内容 |
+| 产出报告 | `title`, 正文 | 标题与正文来自本次执行的结论；长正文先写文件再 `--content-file <path>` |
+
+## 验证操作成功
+
+| 操作 | 验证方法 |
+|------|---------|
+| create | 返回 JSON 含 `id` + `code`（如 TASK-042） |
+| update | JSON 返回更新后的字段值，确认与输入一致 |
+| delete | 退出码 0；再次 `get <id>` 应返回退出码 3（404） |
+| login | `auth status` 应返回 `"loggedIn": true` |
+
+## 数据量控制
+
+- 列表命令默认 `--page-size 10`（后端 REST 默认值），单次向用户展示不超过 20 条
+- 用户要求"全部"时自动翻页，每页最多 100000 条（后端 REST 上限）
+- 超过 100 条结果 → 摘要展示前 5 条 + "共 X 条，建议缩小筛选范围"
+- 注意：`--page-size` 的"每页最多 50 条"限制仅存在于服务端 Agent 的 `search_objects` 工具（MCP 通道），CLI 走 REST 不受此限
+
+## 幂等性
+
+| 命令 | 重试策略 |
+|------|---------|
+| `list` / `get` / `status` | ✅ 安全重试 |
+| `create` | ⚠️ 重试可能重复创建；401/5xx 时先检查是否已创建成功再决定 |
+| `update` | ✅ 安全重试（覆盖更新） |
+| `delete` | ⚠️ 退出码 3（404）= 已删除，非错误 |
+
+## 操作约束
+
+### 必须遵守
+1. **先 list 再操作** — 不要猜测或编造 UUID，必须从 `list` 结果中获取
+2. **修改前确认** — `write_internal` 操作必须经用户确认
+3. **检查返回值** — 退出码非 0 时读 stderr 的 JSON，按退出码语义处理
+4. **不展示原始 JSON** — 提取关键字段（title/id/priority/state）格式化呈现
+
+### 常见错误
+- ❌ 用 `--priority p0` → 合法值只有 `low medium high urgent`
+- ❌ 同时传 `--mine` 与 `--assignee` → 互斥，二选一
+- ❌ 不检查 auth status 直接 create → 先 `morula auth status`
+- ❌ 对 401 反复重试同一条命令 → 应 `morula auth login` 重新认证
+- ❌ 传无效枚举值 → 先查 [commands.md](references/commands.md) 确认合法值
+- ❌ 在 create 时传 `--sort-order` → 仅 update 支持
+
+## 结果呈现
+
+### 列表结果 → 表格摘要
+提取 `id`、`title`、`priority`、状态名（嵌套 `state.name`）、负责人名（嵌套 `assignee.displayName`）以表格展示。有分页时提示"第 X 页，共 Y 条"。列表响应中没有顶层 `stateName`/`assigneeName` 字段。
+
+### 单条详情 → 字段列表
+提取关键字段以 key: value 对展示。不要展示完整 JSON。
+
+### 错误 → 翻译退出码
+
+Agent 看到非零退出码时，应从 stderr 提取 JSON 中的 `code` 和 `message` 字段，按以下规则处理：
+
+- 退出码 2（`USAGE` / `BAD_REQUEST`）→ 参数格式或值不正确。检查命令语法，对照 [commands.md](references/commands.md) 修正参数后重试。常见原因：传了不支持的枚举值（如 `--priority p0`）、日期格式错误（应 ISO 8601）。
+- 退出码 3（`NOT_FOUND`）→ 请求的资源（空间/任务/成员/评论）不存在。用对应的 `list` 命令重新查询可用 ID，确认 ID 未被删除或拼写错误。
+- 退出码 4（`UNAUTHENTICATED`）→ Token 过期或未登录。执行 `morula auth login --env prod` 重新认证。不要在未认证状态下反复重试业务命令。
+- 退出码 5（`FORBIDDEN`）→ 当前用户对该空间/资源无操作权限。检查用户是否为空间成员、角色权限是否足够（如需要 admin 才能移除成员）。
+- 退出码 6（`CONFLICT`）→ 资源状态冲突（如并发修改、重复创建）。用 `get` 重新查询最新数据，确认当前状态后再决定是否重试。避免盲目重写。
+- 退出码 7（`UPSTREAM` / `NETWORK` / `TIMEOUT` / `RATE_LIMITED`）→ 网络超时、服务端 5xx 错误或频率限制。指数退避重试（1s → 2s → 4s），最多 3 次。如持续失败，告知用户稍后再试。
+- 退出码 137（`CRASH`）→ CLI 进程被操作系统 SIGKILL 强制终止，无 stdout/stderr 输出（包装脚本会尝试注入诊断信息）。详见下方「退出码 137 诊断」章节。
+
+## 退出码 137 诊断
+
+当 morula CLI 返回退出码 137（SIGKILL）时，表明进程被操作系统强制终止，无 stderr 输出。常见于 macOS。
+
+**原因**：macOS arm64 对可执行文件有严格的代码签名验证。如果 CLI 二进制（Bun 单文件产物或旧 SEA）签名无效或被破坏（`EXC_CRASH (Code Signature Invalid)`），内核会在启动时直接 SIGKILL。
+
+**诊断步骤**：
+1. 检查二进制签名状态：
+   ```bash
+   codesign -dvvv "$(dirname $(which morula))/../skills/morula-cli/scripts/morula" 2>&1
+   ```
+2. 检查系统崩溃日志：打开 Console.app → Crash Reports，搜索 `morula`
+3. 确认 macOS 版本：`sw_vers`
+
+**修复方式**（用户侧）：
+```bash
+BIN="$(dirname $(which morula))/../skills/morula-cli/scripts/morula"
+xattr -cr "$BIN"
+codesign --force --deep --sign - "$BIN"
+```
+
+**Agent 回退策略**：如果 CLI 持续返回 137 且无法修复，Agent 应回退到直接调用 Morula REST API（`POST /objects`、`GET /spaces` 等），通过 HTTP 完成操作。注意：API 直调时需显式传递 `descriptionFormat` 字段（通过内容自动检测设置）。
+
+## Step 0: 使用插件命令
+
+插件安装后，宿主会将 `bin/` 加入 `PATH`。始终直接使用：
+
+```bash
+morula --help        # 打印所有命令与参数（JSON）
+morula --version     # 输出版本号 JSON
+```
+
+所有成功结果默认以 JSON 输出到 stdout，错误以 JSON 输出到 stderr。不要添加 `--json`。
+
+## Step 1: 检查认证
+
+```bash
+morula auth status
+```
+
+如未登录或任何命令以退出码 `4` 返回，进入 Step 2。不要要求用户提供、复制或粘贴 Token。
+
+## Step 2: SkyDoor SSO 登录
+
+```bash
+morula auth login --env prod
+```
+
+该命令会打开浏览器，通过 PKCE + loopback 完成登录。浏览器步骤需要用户操作；等待用户完成后再继续。登录凭据存于 `~/.morula-cli/config.yaml`（0600）。
+
+## Step 3: 执行业务命令
+
+先用列表命令发现稳定 ID，再读取或修改资源。修改前确认用户意图，不要猜测空间、任务、状态或负责人 ID。
+
+常用命令：
+
+```bash
+morula space list
+morula space get <space-id>
+morula task list --space <space-id> --page 1 --page-size 20
+morula task get <task-id>
+morula task create --space <space-id> --title "标题" --priority medium
+morula task update <task-id> --state <state-id> --assignee <principal-id>
+```
+
+字段读写（自定义字段）：
+
+```bash
+# 自定义字段（字段模板里的 select 等字段）
+morula task list --space <space-id> --field plane_module=定制服务          # 按自定义字段值筛选（等值）
+morula task get <task-id>                                                 # 详情附带 fieldValues
+morula task create --space <space-id> --title "标题" --field plane_module=定制服务    # 创建后写入自定义字段值
+```
+
+- `--field` 格式为 `key=value`：key 为字段模板里的 fieldKey（也接受字段名），list 筛选需配合 `--space` 解析字段模板。
+- `list` 默认返回字段值（includeFieldValues）。
+
+我的任务（用户问"我有哪些任务"时使用）：
+
+```bash
+morula task list --mine                    # 仅当前用户负责的任务（自动解析，无需传 --assignee）
+```
+
+完整参数见 [commands.md](references/commands.md)，认证和错误处理见 [authentication.md](references/authentication.md)。
+
+## 退出码
+
+| 退出码 | stderr `code` | 含义 | Agent 处理 |
+|--------|--------------|------|-----------|
+| `0` | — | 成功，stdout 为 JSON 结果 | 提取字段格式化展示 |
+| `1` | `ERROR` | 未分类的内部错误 | 读取 `message` 告知用户，记录上下文后重新评估 |
+| `2` | `USAGE` / `BAD_REQUEST` | 参数格式或值不正确 | 检查命令语法和参数值，对照 [commands.md](references/commands.md) 修正后重试 |
+| `3` | `NOT_FOUND` | 资源（空间/任务/成员/评论）不存在 | 用 `list` 重新查询可用 ID，确认 ID 未被删除或输入错误 |
+| `4` | `UNAUTHENTICATED` | Token 过期或未登录 | 执行 `morula auth login --env prod` 重新认证 |
+| `5` | `FORBIDDEN` | 无操作权限 | 检查用户角色和空间权限；如需提权，告知用户联系管理员 |
+| `6` | `CONFLICT` | 资源状态冲突（并发修改/重复创建） | 用 `get` 重新查询最新状态后谨慎重试，避免盲目覆盖 |
+| `7` | `UPSTREAM` / `NETWORK` / `TIMEOUT` / `RATE_LIMITED` | 网络超时、服务端 5xx 或限频 | 指数退避重试（1s→2s→4s），最多 3 次；持续失败则告知用户稍后再试 |
+| `137` | `CRASH` | 进程被 SIGKILL 强制终止（macOS 代码签名验证失败） | 见下方「退出码 137 诊断」章节；无法修复时回退到直接调用 REST API |

package/dist/plugin/skills/morula-cli/references/authentication.md

@@ -0,0 +1,21 @@
+# 认证与配置
+
+> CLI-SPLIT-001：业务 CLI（`morula`）与全局运行时 CLI（`morula-runtime`，`@arcships/morula-runtime`）**共享同一认证配置**（`~/.morula-cli/config.yaml`）。设备首次登录推荐用 `morula-runtime auth login`（引导命令以 morula-runtime 开头）；业务命令登录也可直接用 `morula auth login`。两者任一登录成功后，两个 CLI 均可使用。
+
+`morula auth login` 使用 OAuth2 PKCE S256：CLI 在 `127.0.0.1` 随机端口监听一次性回调，生成 verifier/challenge/state，通过 morula-server 代理 SkyDoor SSO，最后交换 180 天有效的 Morula JWT。
+
+配置路径默认是 `~/.morula-cli/config.yaml`，目录权限 0700、文件权限 0600。支持多个 context：
+
+```yaml
+currentContext: test
+contexts:
+  test:
+    url: https://morula.basecastle.com/api
+    token: <redacted>
+```
+
+地址优先级：`--url` > `MORULA_API_URL` > 保存 context > 内建环境。Token 优先级：`--token` > `MORULA_TOKEN` > 与目标地址绑定的保存 context。
+
+当前构建 target 为 `production`，默认 context 为 `prod`（https://morula.fazhiplus.com/api）。 若覆盖目标地址，保存的 Token 不会自动发送，必须显式传入 Token。
+
+安全规则：不得显示、记录或提交配置中的 token；不得要求用户在聊天中粘贴 token。401 对应退出码 4，应重新运行浏览器登录。

package/dist/plugin/skills/morula-cli/references/commands.md

@@ -0,0 +1,401 @@
+# 命令参考
+
+## 全局参数
+
+| Flag | Type | 说明 |
+|------|------|------|
+| `--env` | string | 选择环境 context |
+| `--url` | URL | 覆盖 API 地址 |
+| `--token` | string | 仅本次调用临时覆盖 Token（不持久化，不记录） |
+
+## 退出码速查
+
+| 退出码 | 含义 | Agent 行为 |
+|--------|------|-----------|
+| 0 | 成功 | 按"结果呈现"规则格式化输出 |
+| 1 | 未分类错误 | 展示错误信息 |
+| 2 | 参数错误 | 修正参数后重试 |
+| 3 | 资源不存在 | 确认 ID 是否正确 |
+| 4 | 未认证 | 执行 `morula auth login --env {{DEFAULT_CONTEXT}}` |
+| 5 | 无权限 | 告知用户权限不足 |
+| 6 | 冲突 | 重新查询最新数据后谨慎重试 |
+| 7 | 网络/服务端错误 | 稍后重试，不要重复调用 |
+
+---
+
+## `morula auth login`
+
+打开浏览器完成 SkyDoor SSO 登录（OAuth2 PKCE S256 + loopback callback）。Token 存于 `~/.morula-cli/config.yaml`（0600）。
+
+**超时**：默认 5 分钟，可通过 `MORULA_LOGIN_TIMEOUT_MS` 环境变量覆盖。
+
+**风险**：`read_only`（仅获取凭据）。
+
+**幂等性**：可以重复执行，新 Token 覆盖旧 Token。
+
+**返回示例**：
+```json
+{"loggedIn": true, "context": "test", "baseUrl": "https://morula.basecastle.com/api", "expiresIn": 15552000}
+```
+
+---
+
+## `morula auth logout`
+
+撤销服务端 Token 并清除本地配置。
+
+**风险**：`write_internal`。
+
+---
+
+## `morula auth status`
+
+展示当前 context、API 地址、登录状态和用户信息。
+
+**风险**：`read_only`。
+
+**返回示例**：
+```json
+{"loggedIn": true, "context": "test", "baseUrl": "https://morula.basecastle.com/api", "user": {"displayName": "张三", "username": "zhangsan"}}
+```
+未登录：
+```json
+{"loggedIn": false, "context": "test", "baseUrl": "https://morula.basecastle.com/api"}
+```
+
+---
+
+## `morula task list`
+
+**风险**：`read_only`。**幂等性**：✅ 安全重试。
+
+| Flag | Type | Enum / Format | Default | API Mapping | 说明 |
+|------|------|---------------|---------|-------------|------|
+| `--space` | UUID | - | - | `spaceId` | 空间 ID，从 `space list` 获取 |
+| `--page` | number | ≥ 1 | 1 | `page` | 页码 |
+| `--page-size` | number | 1–50 | 20 | `pageSize` | 每页条数，后端最大 50 |
+| `--search` | string | - | - | `search` | 模糊匹配标题、描述、编码 |
+| `--priority` | enum | `low` `medium` `high` `urgent` | - | `priority` | |
+| `--state` | UUID | - | - | `currentStateId` | 状态 ID |
+| `--assignee` | UUID | - | - | `assigneePrincipalId` | 负责人主体 ID |
+| `--mine` | boolean | - | `false` | 解析为 `assigneePrincipalId` | 仅查询当前登录用户负责的任务（自动经 `auth profile` 解析，与 `--assignee` 互斥） |
+| `--principal` | UUID | - | - | `principalId` | 关联用户主体 ID（同时匹配负责人和报告人） |
+| `--sort` | enum | `createdAt` `updatedAt` `priority` `sortOrder` `title` | - | `sort` | 排序字段 |
+| `--order` | enum | `asc` `desc` | - | `order` | 排序方向 |
+| `--field` | string | `key=value` | - | `fieldFilters` | 字段筛选：自定义字段（等值匹配，多条件逗号分隔 AND，需配合 `--space` 解析字段模板） |
+
+**返回结构**：
+```json
+{
+  "data": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "title": "UI 设计方案评审",
+      "priority": "high",
+      "currentStateId": "550e8400-...",
+      "assigneePrincipalId": "550e8400-...",
+      "spaceId": "550e8400-...",
+      "fieldValues": [
+        { "schemaFieldId": "…", "valueText": "red" }
+      ],
+      "schemaFields": [
+        { "fieldKey": "field_priority", "fieldName": "自定义字段", "fieldType": "select" }
+      ]
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "pageSize": 20
+}
+```
+
+**示例**：
+```bash
+morula task list --space <space-id> --page 1 --page-size 20
+morula task list --priority high --assignee <principal-id>
+morula task list --mine
+morula task list --search "设计方案"
+```
+
+---
+
+## `morula task get <id>`
+
+| Positional | Type | 说明 |
+|-----------|------|------|
+| `<id>` | UUID | 任务 ID，从 `task list` 获取 |
+
+**风险**：`read_only`。**幂等性**：✅ 安全重试。
+
+**返回结构**：含 `title`、`description`、`priority`、`currentStateId`、`assigneePrincipalId`、`estimateHours`、`visibility`、`schemaId`、`createdAt`、`updatedAt`、`participants`、`comments`。
+
+---
+
+## `morula task create`
+
+**风险**：`write_internal` — 执行前须向用户确认 spaceId + title。
+
+**幂等性**：⚠️ 重试可能重复创建。401/5xx 时先 `task list` 检查是否已被创建，再决定是否重试。
+
+**必填**
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--space` | UUID | `spaceId` | 目标空间 ID，从 `space list` 获取 |
+| `--title` | string | `title` | 任务标题 |
+
+**可选**
+
+| Flag | Type | Enum / Format | Default | Mapping |
+|------|------|---------------|---------|---------|
+| `--description` | string | rich HTML | - | `description` |
+| `--priority` | enum | `low` `medium` `high` `urgent` | `medium` | `priority` |
+| `--state` | UUID | 状态 ID | - | `currentStateId` |
+| `--assignee` | UUID | 负责人主体 ID | - | `assigneePrincipalId` |
+| `--owner` | UUID | 拥有者主体 ID | - | `ownerPrincipalId` |
+| `--visibility` | enum | `private` `space` `restricted` `public` | `space` | `visibility` |
+| `--estimate-hours` | number | 小时数，如 `8` | - | `estimateHours` |
+| `--schema` | UUID | 字段模板 ID | - | `schemaId` |
+| `--field` | string | `key=value` | - | 字段值写入（POST /object-field-values upsert） |
+
+**返回**：新任务完整信息，含 `id` + `code`（如 TASK-042）。
+
+**示例**：
+```bash
+morula task create --space <space-id> --title "完成首页开发"
+morula task create --space <space-id> --title "UI评审" --priority high --assignee <principal-id>
+```
+
+---
+
+## `morula task update <id>`
+
+**风险**：`write_internal` — 执行前须向用户确认 taskId + 修改内容。
+
+**幂等性**：✅ 覆盖更新，安全重试。至少传一个可选 flag。
+
+| Positional | Type | 说明 |
+|-----------|------|------|
+| `<id>` | UUID | 任务 ID，从 `task list` 获取 |
+
+**可选**（至少一个）
+
+| Flag | Type | Enum / Format | Mapping |
+|------|------|---------------|---------|
+| `--title` | string | - | `title` |
+| `--description` | string | rich HTML | `description` |
+| `--priority` | enum | `low` `medium` `high` `urgent` | `priority` |
+| `--state` | UUID | 状态 ID | `currentStateId` |
+| `--assignee` | UUID | 负责人主体 ID | `assigneePrincipalId` |
+| `--visibility` | enum | `private` `space` `restricted` `public` | `visibility` |
+| `--estimate-hours` | number | 小时数 | `estimateHours` |
+| `--schema` | UUID | 字段模板 ID | `schemaId` |
+| `--sort-order` | number | 排序值 | `sortOrder` |
+| `--field` | string | `key=value`（空 value 清空） | 字段值写入（POST/DELETE /object-field-values） |
+
+**示例**：
+```bash
+morula task update <id> --state <state-id>
+morula task update <id> --assignee <principal-id>
+morula task update <id> --title "更新后的标题" --priority urgent
+morula task update <id> --sort-order 10
+```
+
+---
+
+## `morula space list`
+
+**风险**：`read_only`。**幂等性**：✅ 安全重试。
+
+| Flag | Type | Default | Mapping | 说明 |
+|------|------|---------|---------|------|
+| `--page` | number | 1 | `page` | 页码 |
+| `--page-size` | number | 20 | `pageSize` | 每页条数 |
+| `--keyword` | string | - | `keyword` | 模糊匹配空间名称 |
+
+**返回结构**：
+```json
+{
+  "data": [
+    {
+      "id": "550e8400-...",
+      "name": "产品研发",
+      "description": "产品研发项目空间",
+      "objectCount": 42,
+      "memberCount": 8
+    }
+  ],
+  "total": 5,
+  "page": 1,
+  "pageSize": 20
+}
+```
+
+---
+
+## `morula space get <id>`
+
+| Positional | Type | 说明 |
+|-----------|------|------|
+| `<id>` | UUID | 空间 ID，从 `space list` 获取 |
+
+**风险**：`read_only`。**幂等性**：✅ 安全重试。
+
+**返回结构**：含 `name`、`description`、`visibility`、`ownerPrincipalId`、`members`（成员列表，含 roleCode）、`workflowId`、`schemaId`、`objectCount`、`createdAt`、`updatedAt`。
+
+---
+
+## `morula task delete <id>`
+
+| Positional | Type | 说明 |
+|-----------|------|------|
+| `<id>` | UUID | 任务 ID，从 `task list` 获取 |
+
+**风险**：`destructive` — 必须先 `task get <id>` 展示任务标题和空间，经用户确认后执行。⚠️ 此为硬删除，数据不可恢复。
+
+---
+## `morula space-member list`
+
+**风险**：`read_only`。**幂等性**：✅。
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--space` | UUID | `spaceId` | 空间 ID，必填 |
+
+---
+
+## `morula space-member add`
+
+**风险**：`identity_access`。**幂等性**：⚠️ 重复添加可能 409。
+
+| Flag | Type | Enum | Mapping |
+|------|------|------|---------|
+| `--space` | UUID | 必填 | `spaceId` |
+| `--principal` | UUID | 必填 | `principalId` |
+| `--role` | enum | `admin` `member`（默认 `member`） | `roleCode` |
+
+---
+
+## `morula space-member update <member-id>`
+
+**风险**：`identity_access`。`--role` 必填。**幂等性**：✅。
+
+---
+
+## `morula space-member remove <member-id>`
+
+**风险**：`identity_access`。**幂等性**：⚠️ 404 = 已移除。
+
+---
+
+## `morula comment list`
+
+**风险**：`read_only`。**幂等性**：✅。
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--object` | UUID | `objectId` | 任务 ID，必填 |
+
+---
+
+## `morula comment get <id>`
+
+**风险**：`read_only`。**幂等性**：✅。
+
+---
+
+## `morula comment add`
+
+**风险**：`write_internal`。**幂等性**：⚠️。
+
+| Flag | Type | Mapping |
+|------|------|---------|
+| `--object` | UUID | `objectId` |
+| `--content` | string | `content` |
+| `--parent` | UUID | `parentCommentId` |
+
+---
+
+## `morula comment update <id>`
+
+**风险**：`write_internal`。`--content` 必填。**幂等性**：✅。
+
+---
+
+## `morula comment delete <id>`
+
+**风险**：`destructive` — 必须先 `comment get <id>` 展示评论内容，经用户确认后执行。⚠️ 此为硬删除，数据不可恢复。
+
+---
+
+## `morula attachment upload <file>`
+
+上传本机文件并挂接为附件（智能体 → 平台回传）。
+
+**风险**：`write_internal`。**幂等性**：⚠️ 重试会重复创建附件。
+
+**Flag**（`--object`/`--comment`/`--ag-message` 三选一，互斥；全不传则智能归并）：
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--object` | UUID | `resourceId`（type=object） | 挂到任务对象附件 |
+| `--comment` | UUID | `resourceId`（type=comment） | 挂到评论附件 |
+| `--ag-message` | boolean | `resourceType=ag_message` | 挂到 Chat 会话最新消息附件 |
+| `--task` | UUID | `taskId` | AgentTask 任务 ID（从 task-context.md 读）；纯 Chat 任务上传时用于归并到会话消息 |
+| `--inline` | boolean | `isInline` | 仅正文内嵌，不进附件列表 |
+
+**Positional**：`<file>` 本机文件路径（必填）。
+
+**返回**：`{ id, resourceType, resourceId, fileUrl, fileName, fileType, fileSize, downloadUrl }`。`downloadUrl` 为签名下载链接，可写进交付评论供用户访问。
+
+**智能归并**：不传 `--object`/`--comment`/`--ag-message` 时，服务端按任务绑定对象自动决定——有 object 挂 object；**纯对话（无对象）任务必须带 `--task <AgentTaskID>`**，服务端据此挂到该 Chat 会话最新消息（ag_message）。
+
+**注意**：文件类型不限（服务端放开到通用类型），单文件上限 20MB；挂 `object`/`comment` 时 agent_task 作用域要求落在任务绑定对象内。
+
+---
+
+## `morula report create`
+
+产出自动化报告（独立产出域 `agent_reports`，挂在所属自动化下）。
+
+**风险**：`write_internal`（写平台，但不改动用户已有资源 → 审批为**自动**，不需要用户确认）。**幂等性**：⚠️ 重试会重复产出（先查再决定是否重试）。
+
+**何时用**：一次执行得出的**结论型重内容**（扫描/巡检结果、审查结论、分析摘要、对比清单）。过程进度、寒暄、需要人拍板的一句话走评论；正文为 Markdown，人从所属自动化卡片的「报告」入口查看——不进任务看板、不占任务编号。详见 SKILL.md「何时产出报告」。
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--title` | string | `title` | 必填，报告标题 |
+| `--content` | markdown | `content` | 正文（与 `--content-file` 二选一） |
+| `--content-file` | path | `content` | 从本机文件读取正文（长报告用；与 `--content` 互斥） |
+| `--space` | UUID | `spaceId` | 可选，归属空间 |
+| `--autopilot` | UUID | `autopilotId` | 可选；缺省由服务端按当前执行上下文反查（taskId → runId → 自动化）并绑定 `runId`；无执行上下文时必填 |
+
+**返回**：`{ id, tenantId, autopilotId, runId, spaceId, title, status: "ready", createdBy, createdAt, updatedAt }`。
+
+**错误**：退出码 2 — `title/content 不能为空`、`报告必须归属于某个自动化：当前执行上下文未关联自动化，请显式传 --autopilot`；退出码 3 — `Autopilot 不存在`（`--autopilot` 值不对）。
+
+---
+
+## `morula report get <id>`
+
+**风险**：`read_only`。**幂等性**：✅。返回含 Markdown 正文 `content`。
+
+---
+
+## `morula report list`
+
+**风险**：`read_only`。**幂等性**：✅。
+
+| Flag | Type | Mapping | 说明 |
+|------|------|---------|------|
+| `--autopilot` | UUID | 路径 `/agent-autopilots/:id/reports` | 必填，报告的归属自动化 |
+| `--page` / `--page-size` | number | query | 分页 |
+| `--status` | `ready\|archived` | query | 可选；缺省不传（服务端默认过滤已归档），要看归档的报告显式传 `--status archived` |
+
+**返回**：`{ data, total, page, pageSize }`。
+
+---
+
+## `morula report archive <id>`
+
+**风险**：`write_internal`（审批：**需确认**）。**幂等性**：✅（重复归档结果一致）。归档后报告默认列表不再展示，正文仍在（`report get` 可查）。