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

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

@@ -0,0 +1,1756 @@
+# 命令参考
+
+> **生成区段**（全局参数 + 各 resource 的命令面）由 CLI SPEC 渲染，不要手改：
+> `pnpm --filter @arcships/morula-runtime gen:cli-skill`。
+> `prompt-cli-consistency` 守卫会把本文件与 SPEC 重渲染结果逐字比对，手改生成区段会红。
+>
+> **手写区段**（`<!-- hand:start <key> -->` … `<!-- hand:end <key> -->`，key = resource 名或 `global`）
+> 放 SPEC 表达不了的补充：风险等级、Flag → API 字段映射、返回结构示例、退出码语义。
+> 生成器逐字保留区段内容；区段外的手写内容会被覆盖。
+
+## 全局参数
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--env <context>` | string | - | - | - | select test or a saved context |
+| `--url <baseUrl>` | string | - | - | - | override API base URL |
+| `--token <token>` | string | - | - | - | override token for this invocation (not persisted) |
+| `--help` | boolean | - | - | - | print this machine-readable command surface |
+| `--version` | boolean | - | - | - | print version JSON |
+| `--json` | boolean | - | - | - | no-op: output is always JSON (accepted for familiarity) |
+
+<!-- hand:start global -->
+### 退出码速查（Agent 行为）
+
+| 退出码 | 含义 | Agent 行为 |
+|---|---|---|
+| 0 | 成功 | 按「结果呈现」规则格式化输出（stdout 为 JSON） |
+| 1 | 未分类错误 | 展示错误信息（stderr JSON 的 `message`） |
+| 2 | 参数错误 | 修正参数后重试（对照本文件与 `--help`） |
+| 3 | 资源不存在 | 确认 ID 是否正确（用对应 `list` 重新查询） |
+| 4 | 未认证 | 执行 `morula auth login --env {{DEFAULT_CONTEXT}}` |
+| 5 | 无权限 | 告知用户权限不足 |
+| 6 | 冲突 | 重新查询最新数据后谨慎重试 |
+| 7 | 网络/服务端错误 | 指数退避重试（1s→2s→4s，最多 3 次）；持续失败告知用户稍后再试 |
+
+退出码语义与 137（SIGKILL）诊断见 SKILL.md「退出码」章节。
+<!-- hand:end global -->
+
+---
+
+## `morula auth`
+
+SkyDoor authentication (shared config with morula-runtime)
+
+### `morula auth login`
+
+**用法**：`morula auth login [--url <baseUrl>]`
+
+browser SkyDoor SSO using PKCE and loopback callback (writes ~/.morula-cli/config.yaml)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--url <baseUrl>` | string | - | - | - | server base URL to log in to |
+
+**示例**
+
+```bash
+morula auth login
+```
+
+> `writes: local` · `interactive: yes` · `idempotent: no` · `emits: loggedIn, context, baseUrl, expiresIn`
+
+### `morula auth logout`
+
+**用法**：`morula auth logout`
+
+remove the current context token
+
+**示例**
+
+```bash
+morula auth logout
+```
+
+> `writes: local` · `interactive: no` · `idempotent: yes` · `emits: loggedIn, context`
+
+### `morula auth status`
+
+**用法**：`morula auth status`
+
+show context, endpoint, and authentication state
+
+**示例**
+
+```bash
+morula auth status
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: loggedIn, context, baseUrl, user, expired`
+
+<!-- hand:start auth -->
+### 手写补充：风险等级与返回示例
+
+**风险等级 / 审批**：`login` / `status` = `read_only`（自动）；`logout` = `write_internal`（**需确认**，会撤销服务端 Token 并清除本地配置）。
+
+**登录细节**：`auth login` 走 OAuth2 PKCE S256 + loopback 回调（本机随机端口），默认超时 5 分钟，可用 `MORULA_LOGIN_TIMEOUT_MS` 覆盖。凭据存于 `~/.morula-cli/config.yaml`（0600），可重复执行——新 Token 覆盖旧 Token。
+
+**返回示例**：
+
+```json
+{"loggedIn": true, "context": "test", "baseUrl": "https://morula.basecastle.com/api", "expiresIn": 15552000}
+```
+
+`auth status` 未登录时：
+
+```json
+{"loggedIn": false, "context": "test", "baseUrl": "https://morula.basecastle.com/api"}
+```
+
+已登录时另含 `user`（`{ "displayName": "张三", "username": "zhangsan" }`）。
+<!-- hand:end auth -->
+
+---
+
+## `morula task`
+
+task (business Object) read/write + AgentTask machine protocol (branch/state/analysis-verdict/inbox)
+
+### `morula task list`
+
+**用法**：`morula task list [--space <id>] [--mine] [--assignee <principalId>] [--principal <id>] [--page <n>] [--page-size <n>] [--search <text>] [--priority <low|medium|high|urgent>] [--state <id>] [--sort <field>] [--order <asc|desc>] [--field key=value[,key=value]]`
+
+list tasks (--mine: 仅我负责的；--field key=value 自定义字段筛选，需 --space)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | space id |
+| `--mine` | boolean | - | - | - | 仅我负责的（与 --assignee 互斥） |
+| `--assignee <principalId>` | string | - | - | - | 按负责人过滤 |
+| `--principal <id>` | string | - | - | - | 按创建人过滤 |
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数 |
+| `--search <text>` | string | - | - | - | 关键词搜索 |
+| `--priority <low\|medium\|high\|urgent>` | string | - | `low` `medium` `high` `urgent` | - | 优先级过滤 |
+| `--state <id>` | string | - | - | - | 状态过滤 |
+| `--sort <field>` | string | - | - | - | 排序字段 |
+| `--order <asc\|desc>` | string | - | `asc` `desc` | - | 排序方向 |
+| `--field key=value[,key=value]` | string | - | - | - | 自定义字段等值筛选（多条件 AND；需 --space 解析字段模板） |
+
+**示例**
+
+```bash
+morula task list --space <id>
+morula task list --mine
+morula task list --space <id> --field priority=p1
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula task create`
+
+**用法**：`morula task create [--space <id>] [--title <text>] [--description <text>] [--priority <low|medium|high|urgent>] [--state <id>] [--owner <principalId>] [--assignee <principalId>] [--visibility <value>] [--estimate-hours <n>] [--schema <id>] [--sort-order <n>] [--field key=value[,key=value]]`
+
+create task (必填 --space/--title；落 backlog 由服务端决定初始状态)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--title <text>` | string | 是 | - | - | 标题（必填） |
+| `--description <text>` | string | - | - | - | 描述（格式自动检测） |
+| `--priority <low\|medium\|high\|urgent>` | string | - | `low` `medium` `high` `urgent` | - | 优先级 |
+| `--state <id>` | string | - | - | - | 初始状态（业务 Object state id） |
+| `--owner <principalId>` | string | - | - | - | 负责人（仅创建时） |
+| `--assignee <principalId>` | string | - | - | - | 经办人 |
+| `--visibility <value>` | string | - | - | - | 可见性 |
+| `--estimate-hours <n>` | number | - | - | - | 预估工时 |
+| `--schema <id>` | string | - | - | - | 字段模板 |
+| `--sort-order <n>` | number | - | - | - | 排序号 |
+| `--field key=value[,key=value]` | string | - | - | - | 自定义字段 upsert（创建后写入） |
+
+**示例**
+
+```bash
+morula task create --space <id> --title <text>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task get`
+
+**用法**：`morula task get [<objectId>]`
+
+get task details. No argument = the current AgentTask (id resolved from MORULA_TASK_ID / .morula/checkout.json). With an id = the business Object (title/description)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<objectId>` | - | 业务任务（Object）ID；省略 = 当前 AgentTask 详情 |
+
+**示例**
+
+```bash
+morula task get
+morula task get <objectId>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula task update`
+
+**用法**：`morula task update <id> [--title <text>] [--description <text>] [--priority <low|medium|high|urgent>] [--state <id>] [--assignee <principalId>] [--visibility <value>] [--estimate-hours <n>] [--schema <id>] [--sort-order <n>] [--field key=value[,key=value]]`
+
+update task (--state here is the business Object state id, NOT the AgentTask state code — see `task state`)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 任务（Object）ID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--title <text>` | string | - | - | - | 标题 |
+| `--description <text>` | string | - | - | - | 描述 |
+| `--priority <low\|medium\|high\|urgent>` | string | - | `low` `medium` `high` `urgent` | - | 优先级 |
+| `--state <id>` | string | - | - | - | 状态（业务 Object state id） |
+| `--assignee <principalId>` | string | - | - | - | 经办人 |
+| `--visibility <value>` | string | - | - | - | 可见性 |
+| `--estimate-hours <n>` | number | - | - | - | 预估工时 |
+| `--schema <id>` | string | - | - | - | 字段模板 |
+| `--sort-order <n>` | number | - | - | - | 排序号 |
+| `--field key=value[,key=value]` | string | - | - | - | 自定义字段 upsert（空 value = 清空） |
+
+**示例**
+
+```bash
+morula task update <id> --title <text>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task delete`
+
+**用法**：`morula task delete <id>`
+
+hard delete task
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 任务（Object）ID |
+
+**示例**
+
+```bash
+morula task delete <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task branch`
+
+**用法**：`morula task branch <taskId> [--name <branch>] [--repo <owner/name>]`
+
+report the final branch name for an agent task (machine protocol; agent naming, runtimeId from env; --repo: secondary repo in a multi-repo task)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID（morula task get 无参返回的 id） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--name <branch>` | string | 是 | - | - | 分支名（必填） |
+| `--repo <owner/name>` | string | - | - | - | 次仓库（多仓库任务的分支逐仓上报） |
+
+**示例**
+
+```bash
+morula task branch <taskId> --name <type>/<slug>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task state`
+
+**用法**：`morula task state <taskId> [--state <in_progress|review>] [--reason <text>]`
+
+self-transition task state (machine protocol; agent drives todo→in_progress→review; review→in_progress = 退回开发，平台自动派修复轮次)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--state <in_progress\|review>` | string | 是 | `in_progress` `review` | - | 目标状态 code（必填）；review→in_progress = 退回开发（自动派修复，不需要再自己 @ 开发执行器） |
+| `--reason <text>` | string | - | - | - | 流转原因（退回开发时写进轮次记账与修复任务 prompt） |
+
+**示例**
+
+```bash
+morula task state <taskId> --state in_progress
+morula task state <taskId> --state in_progress --reason <退回原因>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task assign`
+
+**用法**：`morula task assign <taskId> [--to <principalId>]`
+
+assign the task owner (machine protocol; target = space member or stage executor principal)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--to <principalId>` | string | 是 | - | - | 目标负责人 principal UUID（本空间成员或阶段执行器；不存在/不在本空间会显式报错） |
+
+**示例**
+
+```bash
+morula task assign <taskId> --to <principalId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task analysis-verdict`
+
+**用法**：`morula task analysis-verdict <taskId> [--verdict <ready|blocked>] [--reason <text>]`
+
+report the task-analysis verdict (machine protocol; ready → platform auto-starts development, blocked → task stays in analysis)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--verdict <ready\|blocked>` | string | 是 | `ready` `blocked` | - | 分析结论（必填；仅任务分析任务可上报） |
+| `--reason <text>` | string | - | - | - | blocked 时的阻塞/待澄清原因 |
+
+**示例**
+
+```bash
+morula task analysis-verdict <taskId> --verdict ready
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task inbox`
+
+**用法**：`morula task inbox [--peek] [--after-seq <n>]`
+
+checkpoint: pull this thread's unconsumed messages into the current turn (machine protocol; --peek reads without marking them consumed)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--peek` | boolean | - | - | - | 只读，不标记消费 |
+| `--after-seq <n>` | number | - | - | - | 从该 seq 之后拉取 |
+
+**示例**
+
+```bash
+morula task inbox
+morula task inbox --peek
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task agent-tasks`
+
+**用法**：`morula task agent-tasks [--object <objectId>] [--status <queued|dispatched|running|awaiting_approval|completed|failed|cancelled>] [--page <n>] [--page-size <n>]`
+
+list the AgentTask executions of a business task (Object). AgentTask UUID ≠ 业务任务 id — cancel/rerun 要的是这里的 id
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <objectId>` | string | 是 | - | - | 业务任务（Object）ID（必填） |
+| `--status <queued\|dispatched\|running\|awaiting_approval\|completed\|failed\|cancelled>` | string | - | `queued` `dispatched` `running` `awaiting_approval` `completed` `failed` `cancelled` | - | 按单个状态过滤（缺省 = 全部；服务端不做枚举校验，非法值只返回空） |
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数（服务端缺省 20） |
+
+**示例**
+
+```bash
+morula task agent-tasks --object <objectId>
+morula task agent-tasks --object <objectId> --status failed
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula task cancel`
+
+**用法**：`morula task cancel <taskId>`
+
+cancel a running execution (POST /agent-tasks/:id/cancel). queued/dispatched/running/awaiting_approval/failed 可取消；completed/cancelled 不可（409 CONFLICT）；任务不存在 404 NOT_FOUND。成功返回 { ok: true }——**非零退出即未取消**，不要向用户汇报「已停掉」
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | AgentTask UUID（来自 morula task agent-tasks） |
+
+**示例**
+
+```bash
+morula task cancel <taskId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula task rerun`
+
+**用法**：`morula task rerun <taskId>`
+
+rerun a failed/cancelled execution (POST /agent-tasks/:id/rerun; copies the task and re-queues it → returns a NEW taskId). 仅 failed/cancelled 可重跑，其他状态 ok:false + code CONFLICT；10s 内已有活跃重跑为 ALREADY_QUEUED
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | AgentTask UUID（来自 morula task agent-tasks） |
+
+**示例**
+
+```bash
+morula task rerun <taskId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start task -->
+### 手写补充：风险等级 / Flag → API 字段映射 / 返回结构
+
+**风险等级 / 审批**（机器维度见上方生成区段的 `writes`）：
+
+| Action | 风险 | 审批 |
+|---|---|---|
+| `list` / `get` / `agent-tasks` | `read_only` | 自动 |
+| `create` / `update` | `write_internal` | **需确认**（写前向用户确认 spaceId + title / taskId + 修改内容） |
+| `cancel` / `rerun` | `destructive`（干预正在跑的 agent） | **需确认**（先 `task agent-tasks --object <id>` 展示目标执行；`cancel` 停掉在跑执行、`rerun` 会新建一条执行） |
+| `delete` | `destructive` | **需预演 + 确认**（先 `task get <id>` 展示标题与空间；硬删除，数据不可恢复，不可自动重试） |
+
+**id 口径**：`<id>`（`list` / `get` / `update` / `delete`）= 业务任务（Object）ID；`<taskId>`（`agent-tasks` / `cancel` / `rerun`）= AgentTask UUID。两者**不可互换**——干预执行前先 `morula task agent-tasks --object <objectId>` 拿 UUID。
+
+**`cancel` 的失败语义**（2026-09-20 起）：任务不存在 → **404 `NOT_FOUND`**；状态不允许（已完成/已取消）→ **409 `CONFLICT`**；成功 → 200 `{ ok: true, message: 'Task cancelled' }`。即**非零退出就是没取消成功**（不再有「失败也是 200」的假成功），不要只凭「命令返回了」就汇报已停掉。
+
+**幂等性**：`list` / `get` ✅ 安全重试；`create` ⚠️ 重试可能重复创建（401/5xx 时先 `task list` 检查是否已创建）；`update` ✅ 覆盖更新（至少传一个可选 flag）。
+
+**Flag → API 字段映射**（`list` / `create` / `update`）：
+
+| Flag | API 字段 |
+|---|---|
+| `--space` | `spaceId`（从 `space list` 获取） |
+| `--title` | `title` |
+| `--description` | `description`（rich HTML） |
+| `--priority` | `priority`（`create` 缺省 `medium`） |
+| `--state` | `currentStateId`（状态 ID） |
+| `--assignee` | `assigneePrincipalId`（负责人主体 ID） |
+| `--mine` | 解析为 `assigneePrincipalId`（经 `auth status` 自动解析，与 `--assignee` 互斥） |
+| `--principal` | `principalId`（同时匹配负责人和报告人） |
+| `--owner` | `ownerPrincipalId`（仅 `create`） |
+| `--visibility` | `visibility`（`create` 缺省 `space`） |
+| `--estimate-hours` | `estimateHours` |
+| `--schema` | `schemaId`（字段模板 ID） |
+| `--sort-order` | `sortOrder`（仅 `update`） |
+| `--field` | `list` → `fieldFilters`；`create` / `update` → `POST /object-field-values` upsert（空 value 清空） |
+
+**返回结构**：
+
+- `list`：`{ data: [...], total, page, pageSize }`；列表项含 `id`、`title`、`priority`、`currentStateId`、`assigneePrincipalId`、`spaceId`、`fieldValues`、`schemaFields`。
+- `get`：另含 `description`、`estimateHours`、`visibility`、`schemaId`、`createdAt`、`updatedAt`、`participants`、`comments`。
+- `create`：新任务完整信息，含 `id` + `code`（如 `TASK-042`）。
+- `update`：返回更新后的字段值（确认与输入一致）。
+<!-- hand:end task -->
+
+---
+
+## `morula space`
+
+space (project) read/write
+
+### `morula space list`
+
+**用法**：`morula space list [--page <n>] [--page-size <n>] [--keyword <text>]`
+
+list visible spaces
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数 |
+| `--keyword <text>` | string | - | - | - | 关键词 |
+
+**示例**
+
+```bash
+morula space list
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula space get`
+
+**用法**：`morula space get <id>`
+
+get space details
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 空间 ID |
+
+**示例**
+
+```bash
+morula space get <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula space create`
+
+**用法**：`morula space create [--name <text>] [--description <text>] [--code <code>] [--visibility <private|internal|public>]`
+
+create space (project)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--name <text>` | string | 是 | - | - | 空间名称（必填） |
+| `--description <text>` | string | - | - | - | 描述 |
+| `--code <code>` | string | - | - | - | 空间编号（缺省由服务端生成） |
+| `--visibility <private\|internal\|public>` | string | - | `private` `internal` `public` | - | 可见性 |
+
+**示例**
+
+```bash
+morula space create --name <text>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula space update`
+
+**用法**：`morula space update <id> [--name <text>] [--description <text>] [--visibility <private|internal|public>]`
+
+update space (至少一个字段旗标)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 空间 ID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--name <text>` | string | - | - | - | 空间名称 |
+| `--description <text>` | string | - | - | - | 描述 |
+| `--visibility <private\|internal\|public>` | string | - | `private` `internal` `public` | - | 可见性 |
+
+**示例**
+
+```bash
+morula space update <id> --name <text>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula space delete`
+
+**用法**：`morula space delete <id>`
+
+delete space
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 空间 ID |
+
+**示例**
+
+```bash
+morula space delete <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start space -->
+### 手写补充：风险等级与返回结构
+
+**风险等级 / 审批**：`list` / `get` = `read_only`（自动）；`create` / `update` / `delete` 写平台（见上方生成区段的 `writes`），按 SKILL.md「审批规则」在写前向用户确认。
+
+**返回结构**：
+
+- `list`：`{ data: [{ id, name, description, objectCount, memberCount }], total, page, pageSize }`。
+- `get`：含 `name`、`description`、`visibility`、`ownerPrincipalId`、`members`（含 roleCode）、`workflowId`、`schemaId`、`objectCount`、`createdAt`、`updatedAt`。
+<!-- hand:end space -->
+
+---
+
+## `morula space-member`
+
+space member management (admin operations)
+
+### `morula space-member list`
+
+**用法**：`morula space-member list [--space <id>]`
+
+list space members
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+
+**示例**
+
+```bash
+morula space-member list --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula space-member add`
+
+**用法**：`morula space-member add [--space <id>] [--principal <id>] [--role <admin|member>]`
+
+add member to space
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--principal <id>` | string | 是 | - | - | 成员 principalId（必填） |
+| `--role <admin\|member>` | string | - | `admin` `member` | - | 角色（缺省 member） |
+
+**示例**
+
+```bash
+morula space-member add --space <id> --principal <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula space-member update`
+
+**用法**：`morula space-member update <memberId> [--role <admin|member>]`
+
+update member role
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<memberId>` | 是 | 成员行 ID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--role <admin\|member>` | string | 是 | `admin` `member` | - | 新角色（必填） |
+
+**示例**
+
+```bash
+morula space-member update <memberId> --role admin
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula space-member remove`
+
+**用法**：`morula space-member remove <memberId>`
+
+remove member from space
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<memberId>` | 是 | 成员行 ID |
+
+**示例**
+
+```bash
+morula space-member remove <memberId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start space-member -->
+### 手写补充：风险等级 / 幂等性 / Flag → API 字段映射
+
+**风险等级 / 审批**：`list` = `read_only`（自动）；`add` / `update` / `remove` = `identity_access`（**需确认**）。
+
+**幂等性**：`list` / `update` ✅ 安全重试；`add` ⚠️ 重复添加可能 409；`remove` ⚠️ 404 = 已移除（非错误）。
+
+**Flag → API 字段映射**（`add` / `update`）：`--space` → `spaceId`；`--principal` → `principalId`；`--role` → `roleCode`（缺省 `member`）。
+<!-- hand:end space-member -->
+
+---
+
+## `morula steward`
+
+space steward (project-level agent): read takeover state / dispatch a task with an explicit target state
+
+### `morula steward get`
+
+**用法**：`morula steward get [--space <id>]`
+
+get the steward record of a space (null = 未接管)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间（项目）ID（必填） |
+
+**示例**
+
+```bash
+morula steward get --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula steward dispatch`
+
+**用法**：`morula steward dispatch [--space <id>] [--title <text>] [--description <text>] [--state <backlog|todo|in_progress>] [--assignee <principalId>] [--repo <owner/name>] [--client-message-id <id>]`
+
+dispatch a task: create the task and hand it to the pipeline. --state backlog = 落待规划（不派发执行，服务端不建 AgentTask）；缺省 todo（待分析）
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间（项目）ID（必填） |
+| `--title <text>` | string | 是 | - | - | 任务标题（必填） |
+| `--description <text>` | string | - | - | - | 任务描述 |
+| `--state <backlog\|todo\|in_progress>` | string | - | `backlog` `todo` `in_progress` | - | 目标初始状态（缺省 todo） |
+| `--assignee <principalId>` | string | - | - | - | 指定执行者 |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：指定目标仓库（缺省由服务端解析） |
+| `--client-message-id <id>` | string | - | - | - | 幂等键：同一键重复派单返回原结果 |
+
+**示例**
+
+```bash
+morula steward dispatch --space <id> --title <text>
+morula steward dispatch --space <id> --title <text> --state backlog
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start steward -->
+<!-- hand:end steward -->
+
+---
+
+## `morula autopilot`
+
+agent autopilots (scheduled/webhook-triggered automated runs; list only shows your own)
+
+### `morula autopilot list`
+
+**用法**：`morula autopilot list [--space <id>] [--page <n>] [--page-size <n>]`
+
+list autopilots created by the current user
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | 按空间过滤 |
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数 |
+
+**示例**
+
+```bash
+morula autopilot list
+morula autopilot list --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula autopilot create`
+
+**用法**：`morula autopilot create [--space <id>] [--name <text>] [--runbook <text>] [--executor <key>] [--description <text>] [--cron <expr>] [--vcs-connection <id>]`
+
+create an autopilot (--executor is a runtime key from the built-in catalog or one your tenant has reported)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 归属空间 ID（必填） |
+| `--name <text>` | string | 是 | - | - | 名称（同租户唯一，必填） |
+| `--runbook <text>` | string | 是 | - | - | Runbook：每次触发给运行时的目标/背景/步骤（必填） |
+| `--executor <key>` | string | 是 | - | - | 执行者运行时 key（必填；内置 dim / claude / codex 或本租户已上报的 provider） |
+| `--description <text>` | string | - | - | - | 描述 |
+| `--cron <expr>` | string | - | - | - | cron 表达式（5 字段）；缺省 = 仅 webhook 触发 |
+| `--vcs-connection <id>` | string | - | - | - | 限定仓库连接（缺省不限） |
+
+**示例**
+
+```bash
+morula autopilot create --space <id> --name <text> --runbook <text> --executor dim
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start autopilot -->
+<!-- hand:end autopilot -->
+
+---
+
+## `morula dashboard`
+
+space dashboard / statistics / member workload (read-only aggregates)
+
+### `morula dashboard get`
+
+**用法**：`morula dashboard get [--space <id>]`
+
+get the space dashboard aggregate
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+
+**示例**
+
+```bash
+morula dashboard get --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula dashboard statistics`
+
+**用法**：`morula dashboard statistics [--space <id>]`
+
+get space task statistics
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+
+**示例**
+
+```bash
+morula dashboard statistics --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula dashboard workload`
+
+**用法**：`morula dashboard workload [--space <id>]`
+
+get per-member workload in a space
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+
+**示例**
+
+```bash
+morula dashboard workload --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+<!-- hand:start dashboard -->
+<!-- hand:end dashboard -->
+
+---
+
+## `morula object-meta`
+
+task-level agent metadata (D-06 high-signal keys only)
+
+### `morula object-meta get`
+
+**用法**：`morula object-meta get [--object <id>]`
+
+read all agent metadata of a task
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | 是 | - | - | 任务（Object）ID（必填） |
+
+**示例**
+
+```bash
+morula object-meta get --object <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula object-meta set`
+
+**用法**：`morula object-meta set [--object <id>] [--key <key>] [--value <text>]`
+
+write one agent metadata key. Key must be in the high-signal whitelist: pr_url / pr_number / pipeline_status / deploy_url / waiting_on / blocked_reason / decision
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | 是 | - | - | 任务（Object）ID（必填） |
+| `--key <key>` | string | 是 | - | - | 元数据键（必填，白名单） |
+| `--value <text>` | string | 是 | - | - | 值（必填，非空） |
+
+**示例**
+
+```bash
+morula object-meta set --object <id> --key pr_url --value <url>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start object-meta -->
+<!-- hand:end object-meta -->
+
+---
+
+## `morula document`
+
+document artifacts (ag_artifact; id is a numeric auto-increment id, not a uuid)
+
+### `morula document list`
+
+**用法**：`morula document list [--page <n>] [--page-size <n>]`
+
+list document artifacts
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数 |
+
+**示例**
+
+```bash
+morula document list
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula document get`
+
+**用法**：`morula document get <id>`
+
+get document metadata (不含完整正文)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 文档 ID（数字，来自 document list） |
+
+**示例**
+
+```bash
+morula document get <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula document artifacts`
+
+**用法**：`morula document artifacts <id>`
+
+read the parsed document content (markdown)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 文档 ID（数字，来自 document list） |
+
+**示例**
+
+```bash
+morula document artifacts <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+<!-- hand:start document -->
+<!-- hand:end document -->
+
+---
+
+## `morula comment`
+
+object comments (agent summaries live here)
+
+### `morula comment list`
+
+**用法**：`morula comment list [--object <id>]`
+
+list comments for an object
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | 是 | - | - | 对象 ID（必填） |
+
+**示例**
+
+```bash
+morula comment list --object <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula comment get`
+
+**用法**：`morula comment get <id>`
+
+get comment details
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 评论 ID |
+
+**示例**
+
+```bash
+morula comment get <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula comment add`
+
+**用法**：`morula comment add [--object <id>] [--content <text>] [--parent <id>] [--format <markdown|plain|richtext>] [--mention <principalId[,principalId]>] [--mention-agent <stageExecutorId[,stageExecutorId]>] [--final]`
+
+add comment (format auto-detected; use markdown for agent final summaries). --final 发任务最终总结（同任务只保留一条）；--mention 可 @ 人、--mention-agent 可 @ 阶段运行时（触发派发）
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | 是 | - | - | 对象 ID（必填） |
+| `--content <text>` | string | 是 | - | - | 评论内容（必填） |
+| `--parent <id>` | string | - | - | - | 父评论（回复） |
+| `--format <markdown\|plain\|richtext>` | string | - | `markdown` `plain` `richtext` | - | 内容格式（缺省自动检测） |
+| `--mention <principalId[,principalId]>` | string | - | - | - | @ 人：被提及者的 principalId，可重复传或逗号分隔（合并去重保序） |
+| `--mention-agent <stageExecutorId[,stageExecutorId]>` | string | - | - | - | @ 阶段运行时：空间「阶段 → 运行时」槽位的 stageExecutorId，可重复传或逗号分隔；触发该执行器在任务上干活（评论 @ 派发） |
+| `--final` | boolean | - | - | - | 标记本条为任务最终总结（仅任务级凭证可用；同一任务只保留一条，重复发会被服务端拒绝——收尾时先发 final 再上报结果） |
+
+**示例**
+
+```bash
+morula comment add --object <id> --content <text>
+morula comment add --object <id> --content <text> --final
+morula comment add --object <id> --content <text> --mention-agent <stageExecutorId>
+morula comment add --object <id> --content <text> --mention <principalId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula comment update`
+
+**用法**：`morula comment update <id> [--content <text>]`
+
+update comment
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 评论 ID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--content <text>` | string | 是 | - | - | 新内容（必填） |
+
+**示例**
+
+```bash
+morula comment update <id> --content <text>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula comment delete`
+
+**用法**：`morula comment delete <id>`
+
+hard delete comment
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 评论 ID |
+
+**示例**
+
+```bash
+morula comment delete <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start comment -->
+### 手写补充：风险等级 / 幂等性 / Flag → API 字段映射
+
+**风险等级 / 审批**：`list` / `get` = `read_only`（自动）；`add` / `update` = `write_internal`（**需确认**）；`delete` = `destructive`（先 `comment get <id>` 展示评论内容，确认后执行；硬删除，数据不可恢复）。
+
+**幂等性**：`list` / `get` / `update` ✅ 安全重试；`add` ⚠️ 重试可能重复创建。
+
+**Flag → API 字段映射**：`--object` → `objectId`（任务 ID）；`--content` → `content`；`--parent` → `parentCommentId`；`--format` → 内容格式（缺省自动检测）；`--mention <principalId>[,<principalId>]` → `mentions: [{ type: 'member', principalId }]`（多个逗号分隔、重复去重；服务端按 member 提及发通知——只支持 @ 人，@ 运行时/智能体不支持）。
+<!-- hand:end comment -->
+
+---
+
+## `morula review`
+
+Code Review verdict submission (review task machine protocol)
+
+### `morula review submit`
+
+**用法**：`morula review submit <objectId> [--verdict <approved|changes_requested|commented>] [--details <text>] [--pr-number <n>]`
+
+submit Code Review verdict (machine protocol; review task token)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<objectId>` | 是 | 评审对象 ID（系统提示「评审对象」） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--verdict <approved\|changes_requested\|commented>` | string | 是 | `approved` `changes_requested` `commented` | - | 评审结论（必填） |
+| `--details <text>` | string | - | - | - | 评审意见（changes_requested 必填：文件/行/问题/建议） |
+| `--pr-number <n>` | number | - | - | - | 评审对象的 PR 编号（有则填） |
+
+**示例**
+
+```bash
+morula review submit <objectId> --verdict approved
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start review -->
+<!-- hand:end review -->
+
+---
+
+## `morula report`
+
+autopilot reports (conclusion-heavy output of automated runs)
+
+### `morula report create`
+
+**用法**：`morula report create [--title <text>] [--content <markdown>] [--content-file <path>] [--space <id>] [--autopilot <id>]`
+
+create an autopilot report (正文二选一：--content 短正文 / --content-file 长 Markdown；--autopilot 省略时按当前任务反查所属自动化)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--title <text>` | string | 是 | - | - | 标题（必填） |
+| `--content <markdown>` | string | - | - | - | 短正文（与 --content-file 二选一） |
+| `--content-file <path>` | string | - | - | - | 长 Markdown 报告文件（与 --content 二选一） |
+| `--space <id>` | string | - | - | - | 归属空间 |
+| `--autopilot <id>` | string | - | - | - | 所属自动化（省略时按当前任务反查） |
+
+**示例**
+
+```bash
+morula report create --title <t> --content-file <path>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula report get`
+
+**用法**：`morula report get <id>`
+
+get report details (含 Markdown 正文)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 报告 ID |
+
+**示例**
+
+```bash
+morula report get <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula report list`
+
+**用法**：`morula report list [--autopilot <id>] [--page <n>] [--page-size <n>]`
+
+list reports of an autopilot
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--autopilot <id>` | string | 是 | - | - | 自动化 ID（必填） |
+| `--page <n>` | number | - | - | - | 页码 |
+| `--page-size <n>` | number | - | - | - | 每页条数 |
+
+**示例**
+
+```bash
+morula report list --autopilot <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+<!-- hand:start report -->
+### 手写补充：风险等级 / 何时产出 / 返回结构
+
+**风险等级 / 审批**：`get` / `list` = `read_only`（自动）；`create` = `write_internal`，但审批为**自动**——写平台产出域，不改动用户已有资源，不需要用户确认。
+
+**何时用**（`create`）：一次执行得出的**结论型重内容**——扫描/巡检结果、审查结论、分析摘要、对比清单、需要留档的建议。过程性进度、寒暄、需要人立刻拍板的一句话走评论/收件箱；正文为 Markdown，人从所属自动化卡片的「报告」入口查看——不进任务看板、不占任务编号。详见 SKILL.md「何时产出报告」。
+
+**幂等性**：`get` / `list` ✅ 安全重试；`create` ⚠️ 重试会重复产出（先查再决定是否重试）。
+
+**Flag → API 字段映射**（`create`）：`--title` → `title`（必填）；`--content` / `--content-file` → `content`（二选一，长报告用文件，超长正文不要塞进 `--content`）；`--space` → `spaceId`；`--autopilot` → `autopilotId`（缺省由服务端按当前执行上下文反查 taskId → runId → 自动化并绑定 `runId`）。
+
+**返回结构**：`create` → `{ id, tenantId, autopilotId, runId, spaceId, title, status: "ready", createdBy, createdAt, updatedAt }`；`list` → `{ data, total, page, pageSize }`；`get` 含 Markdown 正文 `content`。
+
+**错误**（`create`）：退出码 2 — `title/content 不能为空`、`报告必须归属于某个自动化：当前执行上下文未关联自动化，请显式传 --autopilot`；退出码 3 — `Autopilot 不存在`（`--autopilot` 值不对）。
+<!-- hand:end report -->
+
+---
+
+## `morula repo`
+
+task-space VCS repos: materialize checkout / MR read & comment (server channel; never approves/merges)
+
+> mr 是多级子命令形态（action=mr、子命令位在 positionals[0]）：契约按子命令拆分声明（mr create / mr list / ...），严格校验只对单级 action 生效
+
+### `morula repo list`
+
+**用法**：`morula repo list [--space <id>]`
+
+list task-space VCS connections (the space repo list — the task prompt does NOT list repos; query this when a task may span multiple repos)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+
+**示例**
+
+```bash
+morula repo list --space <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula repo checkout`
+
+**用法**：`morula repo checkout <taskId> <repoFullName> [--ref <branch|sha>]`
+
+materialize a repo into the task workdir (local daemon endpoint preferred, works same-turn; falls back to server machine protocol which resolves scope + workContext)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+| `<repoFullName>` | 是 | 仓库全名（owner/name） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--ref <branch\|sha>` | string | - | `branch` `sha` | - | 检出引用（缺省 = 绑定分支） |
+
+**示例**
+
+```bash
+morula repo checkout <taskId> <owner/name>
+```
+
+> `writes: local` · `interactive: no` · `idempotent: yes`
+
+### `morula repo prepare`
+
+**用法**：`morula repo prepare <taskId> <repoFullName>`
+
+materialize a secondary repo into the task workdir (same level as the primary repo dir)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+| `<repoFullName>` | 是 | 次仓库全名（owner/name） |
+
+**示例**
+
+```bash
+morula repo prepare <taskId> <owner/name>
+```
+
+> `writes: local` · `interactive: no` · `idempotent: yes`
+
+### `morula repo files`
+
+**用法**：`morula repo files [--space <id>] [--repo <owner/name>] [--path <path>] [--ref <branch|sha>]`
+
+list files in a space repo via the server (read-only, non-task: no local checkout, no AgentTask context)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--repo <owner/name>` | string | - | - | - | 仓库全名（缺省 = 空间主仓库） |
+| `--path <path>` | string | - | - | - | 目录路径（缺省 = 仓库根） |
+| `--ref <branch\|sha>` | string | - | `branch` `sha` | - | 分支 / tag / commit（缺省 = 默认分支） |
+
+**示例**
+
+```bash
+morula repo files --space <id>
+morula repo files --space <id> --path src
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula repo read`
+
+**用法**：`morula repo read [--space <id>] [--path <path>] [--repo <owner/name>] [--ref <branch|sha>]`
+
+read a single file from a space repo via the server (read-only, non-task)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--path <path>` | string | 是 | - | - | 文件路径（必填） |
+| `--repo <owner/name>` | string | - | - | - | 仓库全名（缺省 = 空间主仓库） |
+| `--ref <branch\|sha>` | string | - | `branch` `sha` | - | 分支 / tag / commit（缺省 = 默认分支） |
+
+**示例**
+
+```bash
+morula repo read --space <id> --path src/index.ts
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula repo mr create`
+
+**用法**：`morula repo mr create <repoFullName> [--branch <branch>] [--base <base>] [--task-code <code>]`
+
+create a GitLab MR for the task via the server channel (target project forced to the bound repo, PR linked immediately; push the branch first)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<repoFullName>` | 是 | 仓库全名（owner/name） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--branch <branch>` | string | 是 | - | - | 源分支（必填） |
+| `--base <base>` | string | - | - | - | 目标分支（缺省 MORULA_BASE_BRANCH / main） |
+| `--task-code <code>` | string | - | - | - | 任务编号（MR 标题/正文回链） |
+
+**示例**
+
+```bash
+morula repo mr create <owner/name> --branch <b> --task-code <code>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula repo mr list`
+
+**用法**：`morula repo mr list <taskId> [--state <opened|closed|merged>] [--limit <n>] [--author <username>] [--repo <owner/name>]`
+
+list the task-space repos' merge requests (read-only; includes createdAt/updatedAt/author; never approves/merges)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--state <opened\|closed\|merged>` | string | - | `opened` `closed` `merged` | - | MR 状态过滤（缺省 opened） |
+| `--limit <n>` | number | - | - | - | 条数上限 |
+| `--author <username>` | string | - | - | - | 按作者过滤 |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：目标仓库（缺省主仓库） |
+
+**示例**
+
+```bash
+morula repo mr list <taskId> --state opened
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula repo mr comment`
+
+**用法**：`morula repo mr comment <taskId> [--mr <iid>] [--repo <owner/name>] [--connection <id>] [--content <text>] [--content-file <path>]`
+
+write a review comment on an MR/PR (write-only: never approves or merges). 写之前必须先 `morula repo mr get <taskId> --mr <iid> --notes` 读已有讨论：若本自动化已就同一问题留过结论且结论未变，不要再评论。内容为结论 + 关键问题（文件:行 + 建议），末尾加署名行；长内容写成报告后用摘要引用（morula report create → 评论里给要点）
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--mr <iid>` | number | 是 | - | - | MR 编号（必填） |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：目标仓库（缺省主仓库） |
+| `--connection <id>` | string | - | - | - | 连接 ID（多连接场景） |
+| `--content <text>` | string | - | - | - | 评论正文（与 --content-file 二选一） |
+| `--content-file <path>` | string | - | - | - | 评论正文文件（与 --content 二选一） |
+
+**示例**
+
+```bash
+morula repo mr comment <taskId> --mr <iid> --content-file <path>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula repo mr get`
+
+**用法**：`morula repo mr get <taskId> [--mr <iid>] [--repo <owner/name>] [--ci] [--notes]`
+
+get a single MR detail (read-only; --ci attaches pipeline status where none = no pipeline, not an error; --notes attaches existing comments — read this before writing a comment to avoid duplicates)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--mr <iid>` | number | 是 | - | - | MR 编号（必填） |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：目标仓库（缺省主仓库） |
+| `--ci` | boolean | - | - | - | 附带 pipeline 状态 |
+| `--notes` | boolean | - | - | - | 附带已有评论（写评论前先读，防重复） |
+
+**示例**
+
+```bash
+morula repo mr get <taskId> --mr <iid> --notes
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula repo mr diff`
+
+**用法**：`morula repo mr diff <taskId> [--mr <iid>] [--repo <owner/name>] [--max-files <n>] [--max-chars <n>]`
+
+read an MR diff via the server (read-only; works without a local checkout; truncated flag is set when output was capped)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | 是 | 本任务 AgentTask UUID |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--mr <iid>` | number | 是 | - | - | MR 编号（必填） |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：目标仓库（缺省主仓库） |
+| `--max-files <n>` | number | - | - | - | 文件数上限 |
+| `--max-chars <n>` | number | - | - | - | 字符数上限 |
+
+**示例**
+
+```bash
+morula repo mr diff <taskId> --mr <iid>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+<!-- hand:start repo -->
+<!-- hand:end repo -->
+
+---
+
+## `morula ci`
+
+CI/CD pipeline facts + write operations: pipeline runs / job logs / deployments / failed test cases / trigger pipeline / retry / play manual job. Read faces share one command surface — task face `<taskId>` (AgentTask credential, self-check your MR pipeline) vs space face `--space <spaceId>` (steward/session credential, space-wide inspection); the two are mutually exclusive. Write ops (trigger / retry / play) are ONLY open on the space face (not task face); agent_session tokens are read-only for CI (AgentSessionScopeGuard does not whitelist these endpoints). D2: retry of the newest FAILED run is the default when --run is omitted
+
+> 两个面（任务面 <taskId> / 空间面 --space <spaceId>）互斥：同时给 → usage error(2)，都不给同样 usage error。凭证与作用域不同，猜错会变成静默越权或静默失败
+> D2 写操作（trigger / play / retry）只在空间面开放：agent_session 凭证（管理员）权限只读，不登记 AgentSessionScopeGuard 写面白名单——retry 走管家 elicitation 确认卡，play 仅在 web 人面使用
+> 服务端业务失败是 HTTP 200 + `{ ok:false, code, message }`：CI_JOB_NOT_FOUND / CI_RUN_NOT_FOUND / TASK_NOT_FOUND / OBJECT_NOT_FOUND → exit 3；CAPABILITY_UNSUPPORTED / NO_CONNECTION / 其余 → exit 1
+
+### `morula ci status`
+
+**用法**：`morula ci status [<taskId>] [--space <id>] [--repo <owner/name>] [--ref <branch>] [--failed] [--limit <n>]`
+
+pipeline runs + deployments for a task (or a space); hasCiConfig:false comes with a notice explaining the repo has no CI config (not an error); on the space face repos[] answers per repo (a multi-repo space never answers hasCiConfig for "the space" — it is null there); on the task face --repo filters runs client-side by repoFullName and echoes repoFilter (the server does NOT support repo filtering)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | - | 本任务 AgentTask UUID（与 --space 互斥） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | 空间 ID（管家/空间面；与 <taskId> 互斥） |
+| `--repo <owner/name>` | string | - | - | - | 多仓库空间：只看该仓库的运行（任务面专用，客户端过滤） |
+| `--ref <branch>` | string | - | - | - | 按分支/tag 过滤（空间面专用） |
+| `--failed` | boolean | - | - | - | 只看失败的运行（空间面专用） |
+| `--limit <n>` | number | - | - | - | 运行条数上限（服务端默认 20，上限 100） |
+
+**示例**
+
+```bash
+morula ci status <taskId>
+morula ci status --space <id> --failed
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: ok, taskId, spaceId, runs, deployments, repos, hasCiConfig, notice, repoFilter`
+
+### `morula ci log`
+
+**用法**：`morula ci log [<taskId>] [--space <id>] [--job <jobId>] [--tail <n>]`
+
+job log by job id (the server resolves the owning run; both faces use this same endpoint — the task/space flag only declares which face you are calling from). `truncated:true` means the log was tail-cut, not complete
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | - | 本任务 AgentTask UUID（与 --space 互斥） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | 空间 ID（管家/空间面；与 <taskId> 互斥） |
+| `--job <jobId>` | string | 是 | - | - | job ID（必填；来自 ci status 的 jobs[].id） |
+| `--tail <n>` | number | - | - | - | 保留的日志尾部字节数（服务端默认 64KB） |
+
+**示例**
+
+```bash
+morula ci log <taskId> --job <jobId> --tail 20000
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: ok, runId, jobId, log, truncated`
+
+### `morula ci deployments`
+
+**用法**：`morula ci deployments [<taskId>] [--space <id>]`
+
+deployment records for a task (or a space) — display only: deployments do NOT drive lifecycle state (released is driven solely by a successful production-branch pipeline run)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | - | 本任务 AgentTask UUID（与 --space 互斥） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | 空间 ID（管家/空间面；与 <taskId> 互斥） |
+
+**示例**
+
+```bash
+morula ci deployments <taskId>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: ok, spaceId, deployments`
+
+### `morula ci test-report`
+
+**用法**：`morula ci test-report [<taskId>] [--space <id>] [--run <runId>]`
+
+failed test cases of a run; --run omitted resolves to the newest run in the CI view — no run at all is CI_RUN_NOT_FOUND (exit 3), never an empty report; provider without this capability (GitHub) returns CAPABILITY_UNSUPPORTED
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<taskId>` | - | 本任务 AgentTask UUID（与 --space 互斥） |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | - | - | - | 空间 ID（管家/空间面；与 <taskId> 互斥） |
+| `--run <runId>` | string | - | - | - | 运行 ID（缺省 = CI 视图里最新一条运行） |
+
+**示例**
+
+```bash
+morula ci test-report <taskId>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: ok, runId, report`
+
+### `morula ci trigger`
+
+**用法**：`morula ci trigger [--space <id>] [--ref <ref>]`
+
+trigger a new pipeline on the space's first active connection for the given ref (space face ONLY; ref must be in the connection's integration branch or production branches, or the server rejects with CI_REF_NOT_ALLOWED; NOT idempotent)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--ref <ref>` | string | 是 | - | - | 要触发流水线的分支名（必填） |
+
+**示例**
+
+```bash
+morula ci trigger --space <id> --ref dev
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no` · `emits: ok, action, runId, jobId, externalId, ref, webUrl, acceptedAt`
+
+### `morula ci play`
+
+**用法**：`morula ci play [--job <jobId>]`
+
+trigger a manual job (space face ONLY — job id lookup is stateless; NOT idempotent; only manual jobs — status=manual — can be played, others get CI_JOB_NOT_MANUAL)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--job <jobId>` | string | 是 | - | - | 平台 job ID（必填；来自 ci status 的 jobs[].id，须为手动 job） |
+
+**示例**
+
+```bash
+morula ci play --job <jobId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no` · `emits: ok, action, runId, jobId, externalId, ref, acceptedAt`
+
+### `morula ci retry`
+
+**用法**：`morula ci retry [--space <id>] [--run <runId>] [--job <jobId>]`
+
+re-run a failed pipeline (space face ONLY — a positional <taskId> is a usage error, retry is not open to the task face; person + steward, and a steward must go through an elicitation confirm card). Omit both --run and --job to retry the newest FAILED run of the space (no failed run at all → CI_RUN_NOT_FOUND exit 3). Only failure/cancelled runs or jobs can be retried (CI_RETRY_NOT_ALLOWED exit 6). NOT idempotent: every call starts another platform re-run
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--space <id>` | string | 是 | - | - | 空间 ID（必填） |
+| `--run <runId>` | string | - | - | - | 要重跑的运行 ID（与 --job 互斥；缺省 = 该空间最新一条失败运行） |
+| `--job <jobId>` | string | - | - | - | 要重跑的单个 job ID（与 --run 互斥；来自 ci status 的 jobs[].id） |
+
+**示例**
+
+```bash
+morula ci retry --space <id>
+morula ci retry --space <id> --job <jobId>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no` · `emits: ok, action, runId, jobId, externalId, ref, acceptedAt`
+
+<!-- hand:start ci -->
+<!-- hand:end ci -->
+
+---
+
+## `morula obs`
+
+observability runtime environment ONLY — this is not a query surface. It hands this machine the gateway entry (GRAFANA_SERVER) + a 30-minute, space-scoped, read-only token (GRAFANA_TOKEN) + minimal context (current source + every usable source of the space), so the agent queries line-side facts DIRECTLY with the runtime-managed engine (gcx) through the platform gateway; write paths are refused by the gateway with 403. The platform defines no query command surface: the engine owns the commands and the syntax (gcx --help / gcx commands). Task face by default (task credential, space inferred); --space <spaceId> for the user face
+
+> 只交付运行环境，不是查询命令面：查询由 agent 直接用受管引擎（`gcx`）发起——命令与语法是引擎的运行期资产（`gcx --help` / `gcx commands`），平台不列举、不代理
+> 只读边界在平台网关（写方法一律 403），不在 CLI：本 resource 没有写操作，也没有 raw / 透传子命令
+> **不写任何文件**、无副作用：令牌只打印，不进 argv、不进日志、不落盘
+> 没有可用源（未配置 / 全部停用 / 没有默认源 / 指定源已停用）→ 200 + `server` / `token` 为 null + `notice`：默认输出只给注释（人话 + 可执行下一步），**退出码 3（not found）**
+> 退出码：缺身份面 / 两面同时给 → 2；没有可用运行环境、`--source` 不存在 → 3；换取 401 → 4；换取 403 → 5；网络 / 上游 → 7（都带可执行 hint）
+
+### `morula obs env`
+
+**用法**：`morula obs env [--source <name|id>] [--space <spaceId>] [--json]`
+
+exchange the running environment. Default output is a shell export you can `eval` directly (GRAFANA_SERVER / GRAFANA_TOKEN / GRAFANA_ORG_ID); --json returns the raw response (server / token / expiresAt / context / notice). The env is issued PER SOURCE (server carries the sourceId), so switching sources or renewing the 30-minute token means calling this again with --source <name|id>. Nothing is written to disk (the token never touches a file)
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--source <name\|id>` | string | - | `name` `id` | - | 数据源 name 或 id（缺省用空间默认源；env 按源签发，换源请重新调用） |
+| `--space <spaceId>` | string | - | - | - | 空间 ID（用户身份；缺省走任务面，空间由任务凭证推断；与任务面互斥） |
+| `--json` | boolean | - | - | - | 输出运行环境接口的原始响应 JSON（server / token / expiresAt / context / notice），而不是可 eval 的 shell export |
+
+**示例**
+
+```bash
+eval "$(morula obs env)"
+morula obs env --source staging --json
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes` · `emits: server, token, expiresAt, context, notice`
+
+<!-- hand:start obs -->
+<!-- hand:end obs -->
+
+---
+
+## `morula attachment`
+
+file attachments for objects / comments / chat messages (local file upload)
+
+### `morula attachment upload`
+
+**用法**：`morula attachment upload <file> [--object <id>] [--comment <id>] [--ag-message] [--task <agentTaskId>] [--inline]`
+
+upload a local file and attach it to a task (--object) / comment (--comment) / chat message (--ag-message); for pure chat tasks pass --task <agentTaskId> to attach to the chat session; omit target to auto-merge (object if bound, else chat message)
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<file>` | 是 | 本地文件路径 |
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | - | - | - | 挂到对象 |
+| `--comment <id>` | string | - | - | - | 挂到评论 |
+| `--ag-message` | boolean | - | - | - | 挂到 Chat 会话最新消息 |
+| `--task <agentTaskId>` | string | - | - | - | 纯 Chat 任务归并到会话消息 |
+| `--inline` | boolean | - | - | - | 内联附件 |
+
+**示例**
+
+```bash
+morula attachment upload <file> --object <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+### `morula attachment list`
+
+**用法**：`morula attachment list [--object <id>]`
+
+list attachments for an object
+
+| Flag | 类型 | 必填 | 取值 | 默认 | 说明 |
+|---|---|---|---|---|---|
+| `--object <id>` | string | 是 | - | - | 对象 ID（必填） |
+
+**示例**
+
+```bash
+morula attachment list --object <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula attachment get`
+
+**用法**：`morula attachment get <id>`
+
+get attachment details
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 附件 ID |
+
+**示例**
+
+```bash
+morula attachment get <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula attachment download-url`
+
+**用法**：`morula attachment download-url <id>`
+
+get signed download URL for an attachment
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 附件 ID |
+
+**示例**
+
+```bash
+morula attachment download-url <id>
+```
+
+> `writes: none` · `interactive: no` · `idempotent: yes`
+
+### `morula attachment delete`
+
+**用法**：`morula attachment delete <id>`
+
+delete attachment
+
+| 位置参数 | 必填 | 说明 |
+|---|---|---|
+| `<id>` | 是 | 附件 ID |
+
+**示例**
+
+```bash
+morula attachment delete <id>
+```
+
+> `writes: remote` · `interactive: no` · `idempotent: no`
+
+<!-- hand:start attachment -->
+### 手写补充：风险等级 / 归并语义 / 返回结构
+
+**风险等级 / 审批**：`list` / `get` / `content` / `download-url` = `read_only`（自动）；`upload` = `write_internal`（**需确认**）；`delete` = `destructive`。
+
+**幂等性**：`upload` ⚠️ 重试会重复创建附件；读取类 ✅ 安全重试。
+
+**Flag → API 字段映射**（`upload`）：
+
+| Flag | API 字段 |
+|---|---|
+| `--object` | `resourceId`（`resourceType=object`）——挂到任务对象附件 |
+| `--comment` | `resourceId`（`resourceType=comment`）——挂到评论附件 |
+| `--ag-message` | `resourceType=ag_message`——挂到 Chat 会话最新消息附件 |
+| `--task` | `taskId`（AgentTask 任务 ID，从 task-context.md 读；纯 Chat 任务上传时用于归并到会话消息） |
+| `--inline` | `isInline`（仅正文内嵌，不进附件列表） |
+
+**返回**：`{ 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 作用域要求落在任务绑定对象内。
+<!-- hand:end attachment -->