@yhsp/orion-cli

Orion 协同任务管理平台的 Agent-First CLI。将 MCP Server 的 28+ 工具能力映射为终端命令，支持统一 JSON 输出信封、workspace 发现、dry-run 预览和 Intent / Domain / Support 三层命令结构。

命令结构

Orion CLI 采用三层命令体系，从用户语义出发组织命令：

| 层级 | 英文名 | 作用 | 代表命令 | | ------- | ------------- | ---------------------------------- | ------------------------------- | | intent | Intent Layer | 承接高频自然语言意图，最短路径入口 | my、search、status | | domain | Domain Layer | 按业务对象提供稳定可组合命令 | task *、workload *、req * | | support | Support Layer | 自省、诊断与配置 | meta tools、doctor |

九个业务领域

| 领域 | domain | 成熟度 | 典型命令 | | ----------- | ------------- | ----------------------- | ----------------------------------------------- | | workload | workload | beta / experimental | orion my、orion workload | | task | task | beta | orion task list/get/... | | ticket | ticket | beta | orion ticket search/... | | requirement | requirement | beta / experimental | orion req my-tasks/... | | project | project | beta / trial | orion project list/... | | milestone | milestone | beta | orion milestone list/get/status | | risk | risk | beta | orion risk list/get/status | | okr | okr | beta | orion okr list/get/... | | report | report | beta | orion report daily/weekly/workload/inspection |

命令成熟度说明

Orion CLI 采用五级命令成熟度模型：

| 成熟度 | 含义 | | -------------- | ------------------------------------------------------------------------------------- | | experimental | 已注册，尚未实现。执行时返回 NOT_IMPLEMENTED 诊断，退出码 2。 | | trial | 已实现，受控使用中。功能可用，接口可能在后续版本调整。 | | beta | 已实现并推广使用。接口稳定，欢迎日常使用。 | | ga | 稳定通用可用（General Availability）。接口已锁定，提供长期支持。 | | deprecated | 已废弃。将在未来版本移除，deprecatedSince 记录废弃版本，migratesTo 指向替代命令。 |

使用 orion meta tools 可查看每条命令的成熟度字段。

CLI 与 Skill 的映射边界见 SKILL_MAPPING.md。

Canonical CLI -> Skill Routes

| 用户目标 | Canonical command | Canonical skill | | ------------------- | ------------------------------------------ | ------------------- | | complete-task | orion complete-task <taskRef> | orion-cli-task | | project-inspect | orion project inspect <projectId> | orion-cli-project | | task-create | orion task create | orion-cli-task | | task-get | orion task get <taskRef> | orion-cli-task | | task-status | orion task status <taskRef> <status> | orion-cli-task | | task-list-project | orion task list --project-id <projectId> | orion-cli-task | | report-daily | orion report daily | orion-cli-report |

Explainable fallback

| 输入信号 | 路由结果 | 说明 | | --------------- | --------------------------------------------------- | ---------------------------------------------- | | exact command | 对应命令的 canonicalSkill | 返回 exact-command | | curated intent | 先归一到 canonical command，再命中 canonicalSkill | 返回 curated-intent | | domain fallback | 该 domain 的唯一 CLI skill | 返回 domain-fallback | | unknown command | orion-cli-workspace / orion meta tools | 返回 fallback-discovery + unmapped-command |

orion-cli-task Entry Taxonomy

Workflow Entry

| Command | Intent | Dry-Run | | ------------------------------- | ----------------------------------------------------------------- | ------- | | orion complete-task <taskRef> | 完成指定任务并处理 DONE 前置字段校验 | Yes | | orion triage-task | 判断指定 task 是否值得进入 bug analysis，并给出结构化 triage 结论 | Yes |

CRUD Entry

| Command | Intent | Dry-Run | | ------------------------------------------ | -------------------------------------------------------------------- | ------- | | orion task list --project-id <projectId> | 列出当前工程或指定项目下的任务 | No | | orion task search | 按状态/优先级/负责人/日期范围精确过滤任务，面向 Agent 的精确查询入口 | No | | orion task get <taskRef> | 获取指定任务的详细信息 | No | | orion task update | 更新任务字段（标题、描述、优先级等） | Yes | | orion task status <taskRef> <status> | 变更任务/需求任务的流转状态（不处理工单） | Yes | | orion task attachments | 查看任务的附件列表 | No | | orion task download-url | 获取任务附件的临时下载链接 | No | | orion task explore | 深入探索任务的完整上下文（关联、历史、依赖） | No | | orion task create | 在当前项目上下文下创建新任务 | Yes | | orion task init-upload | 初始化任务附件上传流程 | Yes | | orion task complete-upload | 完成任务附件上传确认 | Yes |

Orion CLI 面向 AI Agent 使用场景时，升级后会检查 bundled skills 是否发生变化；如果发生变化，CLI 会提示执行 orion skills install --all。如果你希望升级后顺手同步 skills，可以直接使用 orion upgrade --with-skills。

安装

# 全局安装
npm install -g @yhsp/orion-cli

# 或直接运行
npx @yhsp/orion-cli

# 或在项目内本地安装
npm install @yhsp/orion-cli

要求: Node.js >= 20.10.0

发布包会同时携带 CLI surface skill 子集，位于 skills/ 目录下，由发布前同步脚本复制到 CLI 包内；这不是运行时“自动发现”，新增或调整命令后仍需执行 npm run skill:generate -- --all、npm run skill:check -- --all 与 npm run sync:cli-skills。CLI skills 使用 orion-cli- 命名前缀，按业务域拆分为 7 个独立领域型 skill（orion-cli-task、orion-cli-report、orion-cli-workspace、orion-cli-project、orion-cli-ticket、orion-cli-req、orion-cli-okr），只包含命令路由和入口引导职责；MCP skills（orion-task-collaboration、pm-report-assistant）由 mcp/orion-task-mcp 包单独分发。

安装 skill 到 AI 工具

# 安装到 Codex 的 skill home
orion skills install --target codex

# 安装到 Claude Code 的 skill home
orion skills install --target claude

# 安装到 OpenClaw 的 skill home
orion skills install --target openclaw

# 校验安装是否一致
orion skills check --all

快速开始

1. 配置环境变量

export ORION_BASE_URL="https://your-orion-instance.example.com"
export ORION_AGENT_TOKEN="your-agent-token"

Token 在 Orion 设置 > Agent Access 中生成。

2. 检查配置

orion doctor

3. 执行第一个命令

# 查看工作区状态
orion status

# 查看我的工作负载
orion my

# 搜索任务
orion search "登录功能"

# 预检完成任务 workflow
orion complete-task TASK-20260313-0281 --dry-run

# 预检单项目巡检 workflow
orion project inspect PROJ-1 --dry-run

命令速查表

Workflow 试用入口（Phase 4）

| 命令 | 成熟度 | 说明 | | ----------------------------------- | ------- | ----------------------------------------------------------------------------------- | | orion complete-task <taskRef> | trial | 完成任务 workflow 入口（复用 task get/status） | | orion triage-task <taskRef> | trial | task bug triage 入口（强判断，复用 workspace/current/task get） | | orion triage-ticket <ticketId> | trial | ticket bug triage 入口（保守判断，复用 workspace/current/ticket get/attachments） | | orion project inspect <projectId> | trial | 单项目巡检 workflow 入口（复用 overview/inspection） |

Intent 层命令（高频入口）

| 命令 | MCP 等价 | 成熟度 | 说明 | | ---------------------- | ----------------------------- | ------- | ---------------------------------- | | orion status | orion_get_workspace_context | beta | 工作区上下文 + 工作摘要 | | orion my | orion_get_my_workload | beta | 我的工作负载聚合（含建议和上下文） | | orion current | — | trial | 当前工程上下文与任务概览 | | orion today | — | trial | 今日工作视图与优先建议 | | orion search <query> | orion_search_tasks | beta | 统一任务搜索 | | orion doctor | — | beta | 诊断配置完整性 |

Domain 层 — workload 域

| 命令 | MCP 等价 | 成熟度 | 说明 | | ------------------------------ | ----------------------- | ------ | --------------------------------------------------------------- | | orion workload | orion_get_my_workload | beta | 工作负载（显式入口） | | orion workload user <userId> | — | beta | 指定成员工作负载（任务列表 + 统计） | | orion workload team | — | beta | 团队工作负载聚合（需 --project-id，客户端聚合，默认最多 20 人） |

Domain 层 — task 域

| 命令 | MCP 等价 | 成熟度 | 说明 | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------- | -------------------------------------------- | | orion task list [--project-id <id>] | orion_my_workspace_tasks | beta | 任务列表（支持 workspace / project 视角） | | orion task search [--keyword] [--status] [--priority] [--assignee-id] [--due-before] [--due-after] | — | beta | 跨项目任务搜索（无需 workspace） | | orion task get <id> | orion_get_task | beta | 任务详情 | | orion task explore <id> | orion_explore_task | beta | 深挖任务上下文 | | orion task create | orion_create_task | beta | 创建任务 ✏️ | | orion task update <id> | orion_update_task | beta | 更新任务 ✏️ | | orion task status <id> <status> | orion_change_task_status | beta | 变更任务状态 ✏️ | | orion task attachments <id> | orion_get_task_attachments | beta | 任务附件列表 | | orion task download-url <id> <attachmentId> | orion_get_task_attachment_download_url | beta | 获取附件下载链接 | | orion task init-upload <id> --filename <name> --content-type <mime> | — | beta | 初始化附件上传（返回 uploadId）✏️ | | orion task complete-upload <id> --upload-id <uploadId> | — | beta | 确认附件上传完成 ✏️ | | orion triage-task <taskRef> | — | trial | bug triage 入口；task 属于当前工程时走强判断 |

Domain 层 — ticket/req/project/milestone/risk/okr 域

这些域的命令已实现，可直接使用。

| 命令 | 成熟度 | 说明 | | ------------------------------------------------------------- | -------------- | -------------------------------------------------------- | | orion project list [--keyword] | beta | 项目列表 | | orion project get <id> | trial | 项目详情 | | orion project overview <id> | trial | 项目概览（含治理入口提示） | | orion project inspect <id> | trial | 单项目巡检（inspect 意图 canonical 入口） | | orion milestone list --project-id <id> | beta | 项目里程碑列表 | | orion milestone get <id> --project-id <id> | beta | 里程碑详情与交付物上下文 | | orion milestone status <id> --project-id <id> --next <st> | beta | 里程碑状态流转 / dry-run 预览 ✏️ | | orion risk list --project-id <id> [--status <st>] | beta | 项目风险列表 | | orion risk get <id> --project-id <id> | beta | 风险详情 | | orion risk status <id> --project-id <id> --next <st> | beta | 风险状态流转 / dry-run 预览 ✏️ | | orion req my-tasks [--limit] | beta | 我的需求任务 | | orion req owned [--limit] | beta | 我负责的需求 | | orion req pool [--pool-id] [--limit] | beta | 需求池浏览 | | orion req create | experimental | 创建需求任务 | | orion ticket create | trial | 创建工单，支持 dry-run、workspace 默认化与阻塞诊断 ✏️ | | orion ticket lookup types | trial | 查询工单创建 type 候选 | | orion ticket lookup systems [--query <keyword>] | trial | 查询工单创建产品线候选 | | orion ticket lookup users [--query <keyword>] | trial | 查询工单创建用户候选 | | orion ticket search --query <keyword> | beta | 工单搜索 | | orion ticket get <id> | beta | 工单详情 | | orion ticket my [--limit] | beta | 我的工单 | | orion ticket attachments <id> | beta | 工单附件列表 | | orion ticket download-url <ticketId> <attachmentId> | beta | 工单附件下载链接 | | orion triage-ticket <ticketId> | trial | bug triage 入口；ticket 只有在显式证据充分时才判定可处理 | | orion okr list | beta | OKR 列表 | | orion okr get <objectiveId> | beta | OKR 详情（canonical detail） | | orion okr summary <objectiveId> | beta | OKR 摘要 | | orion okr kr-tasks <krId> | beta | KR 关联任务 | | orion report daily | beta | 日报生成 | | orion report weekly | beta | 周报生成 | | orion report workload [--team <identifier>] | beta | 负载分析报告（支持个人与团队维度） | | orion report inspection [--limit <n>] [--project-ids <ids>] | beta | 多项目巡检报告（跨项目治理健康快照） |

orion report 在 Phase 3a 只保留 daily、weekly、workload、inspection 四个只读 preview 命令，不支持 --dry-run。

orion project inspect <id> 是单项目 inspect 意图的 canonical 入口；orion project overview <id> 与 orion report inspection 保留为 substrate / follow-up。

orion report inspection 与 orion project overview 在检测到任务逾期/阻塞风险时，会优先保留 orion task list --project-id <id> 作为任务治理入口；里程碑或风险治理动作仍会继续出现在 availableActions 中。

orion ticket search / orion task search 负责枚举候选对象；orion triage-ticket / orion triage-task 才是 bug triage 的 canonical 判断入口。本轮只输出 triage decision 与下一步建议，不做自动修复或通用编排。

Support 层命令（自省与配置）

| 命令 | MCP 等价 | 成熟度 | 说明 | | --------------------- | --------------------------------------- | ------ | ------------------- | | orion meta tools | orion_get_tool_scope_mapping | beta | 能力发现与自省 | | orion meta contract | orion_get_task_query_contract | beta | 查询字段定义 | | orion upgrade | npm install -g @yhsp/orion-cli@latest | beta | 升级 CLI 到最新版本 |

平台控制面（Phase 2）

Auth — 认证诊断

| 命令 | 说明 | | -------------------------- | -------------------------------------------- | | orion auth status | 查看当前认证状态（token 来源、profile 名称） | | orion auth check | 在线探针：检查 token 是否有效，按 scope 映射 | | orion auth whoami | 解码 JWT payload，显示用户信息 | | orion auth token-sources | 列出所有 token 来源及优先级 |

Profile — 多账号配置管理

多 Profile 配置存储在 ~/.orion/config.json（权限 600）。

| 命令 | 说明 | | --------------------------------------------------------- | ---------------------------- | | orion profile list | 列出所有 profile | | orion profile show <name> | 查看指定 profile 详情 | | orion profile add <name> --token <tok> --base-url <url> | 添加 profile（--force 覆盖） | | orion profile use <name> | 切换活跃 profile | | orion profile remove <name> | 删除 profile（不能删活跃） |

Workspace — 工作区管理

| 命令 | 说明 | | --------------------------------------- | ------------------------------------------------- | | orion workspace init --repo-key <key> | ✏️ 初始化工作区绑定（写 .orion/workspace.json） | | orion workspace show | 显示当前工作区绑定信息 | | orion workspace check | 检查工作区状态（冲突检测、--assert-bound） | | orion workspace bind --repo-key <key> | ✏️ 绑定工作区（同 init，可覆盖） | | orion workspace unbind | ✏️ 删除工作区绑定文件 | | orion workspace migrate | ✏️ 迁移旧格式配置（--force 强制覆盖） |

workspace 系列写操作均支持 --dry-run 预览。

Schema — API Schema 查询

| 命令 | 说明 | | ------------------------------------------------ | ----------------------------------------------------- | | orion schema list [--domain <d>] [--layer <l>] | 列出可用 schema，按域或层级过滤 | | orion schema show <command> [--section <s>] | 查看命令 schema（params / filters / body / response） |

Policy — 运行策略管理

全局标志 --read-only、--ci、--strict 可在任意命令中临时覆盖策略。

| 命令 | 说明 | | -------------------------------------- | ------------------------------ | | orion policy show | 查看当前所有维度的策略值 | | orion policy set <dimension> <value> | 设置策略维度（持久化写入配置） | | orion policy reset [<dimension>] | 重置指定维度或全部维度为默认值 |

Doctor — 环境诊断（Phase 2，11 项检查）

| 命令 | 说明 | | ------------------------------- | ---------------------------- | | orion doctor | 运行全部 11 项健康检查 | | orion doctor --check <id> | 仅运行指定 ID 的检查项 | | orion doctor --category <cat> | 按类别运行检查 | | orion doctor --offline | 跳过所有需要网络连接的检查项 |

Completion — Shell 补全

| 命令 | 说明 | | ---------------------------------------- | -------------------------- | | orion completion bash\|zsh\|fish | 输出补全脚本到 stdout | | orion completion install [--shell <s>] | 自动检测并安装到当前 shell |

API 直连（实验性）

| 命令 | 说明 | | ------------------------------------- | ----------------------------------- | | orion api get <path> | 透传 GET 请求 | | orion api post <path> --body <json> | 透传 POST 请求 | | orion api put <path> --body <json> | 透传 PUT 请求 | | orion api delete <path> [--yes] | 透传 DELETE 请求（需 --yes 确认） |

配置管理（legacy 兼容入口）

| 命令 | 说明 | | --------------------------------------------- | -------------------------------------------------------- | | orion config init --project-id <project-id> | 初始化 workspace 配置（legacy，推荐改用 workspace init） | | orion config show | 显示当前配置 | | orion config check | 检查配置完整性 |

✏️ 标记的写操作命令支持 --dry-run 预览。 experimental 命令已可通过 orion meta tools 发现，执行时返回 NOT_IMPLEMENTED，退出码 2。

全局选项

| 选项 | 默认值 | 说明 | | --------------------- | -------- | ---------------------------------------------------- | | -f, --format <type> | json | 输出格式：json、table、compact、ndjson | | --fields <fields> | — | 逗号分隔字段名，过滤 items 中的属性（如 id,title） | | --page-all | false | 自动翻页，合并所有结果后输出 | | --include-raw | false | 包含完整原始数据 | | --dry-run | false | 预览写操作请求（不执行） | | --trace-id <id> | 自动生成 | 审计追踪 ID | | -v, --verbose | false | 输出调试信息到 stderr | | -p, --project <id> | — | 显式项目 ID（覆盖 workspace 推断） | | --page <n> | 1 | 分页页码 | | --page-size <n> | 10 | 分页大小（最大 100） | | --no-color | — | 禁用终端颜色 |

输出格式说明

• json（默认）：标准 CliOutputEnvelope JSON，适合脚本处理
• ndjson：每个 item 单独一行 JSON，适合流式管道（orion task list -f ndjson | jq .）；写操作自动降级为 json 并附加 notice
• table：人类可读表格，额外信息写入 stderr
• compact：紧凑摘要

字段过滤与翻页

# 只输出 id 和 title 字段
orion task list --fields id,title

# 自动翻页获取全量数据
orion task list --page-all

# 组合使用：流式输出所有任务的 id 和标题
orion task list --page-all --fields id,title -f ndjson

环境变量

| 变量 | 必需 | 说明 | | ---------------------------- | ---- | ------------------------------------------------------- | | ORION_BASE_URL | ✅ | Orion 后端 API 地址 | | ORION_AGENT_TOKEN | — | Agent 访问令牌（优先级最高，覆盖 profile 配置） | | ORION_PROFILE | — | 显式指定使用的 profile 名称（次优先级） | | ORION_CLIENT_NAME | — | 客户端标识（默认 orion-cli） | | ORION_WORKSPACE_FILE | — | 显式指定 workspace 配置文件路径 | | ORION_CONFIG_FILE | — | 显式指定全局配置文件路径（默认 ~/.orion/config.json） | | ORION_DISABLE_UPDATE_CHECK | — | 关闭启动时的版本更新提示 |

Token 优先级

CLI 按以下优先级解析认证 token：

1. ORION_AGENT_TOKEN 环境变量（最高）
2. ORION_PROFILE 指定的 profile（次高）
3. ~/.orion/config.json 中 activeProfile 激活的 profile
4. 无 token → 抛出认证错误

全局配置文件安全说明

~/.orion/config.json 包含认证 token，创建时自动设置权限为 600（仅当前用户可读写）。不要将此文件提交到版本控制。

升级 CLI

# 升级到最新版本
orion upgrade

# 升级 CLI 并同步 bundled skills
orion upgrade --with-skills

# 查看当前版本
orion --version

# 关闭启动时更新提示
export ORION_DISABLE_UPDATE_CHECK=1

当 orion upgrade 检测到 bundled skills 发生变化时，它会在升级完成后提示你运行：

orion skills install --all

这条提示适合需要保持 AI Agent 能力一致性的场景；如果你希望由 CLI 直接帮你同步，则使用 orion upgrade --with-skills。

输出格式

所有命令输出统一 JSON 信封结构：

{
  "ok": true,
  "command": "orion task get",
  "traceId": "abc123",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "scope": {
    "workspaceBound": true,
    "sourceType": "PROJECT",
    "workspaceAppliesToSources": ["PROJECT", "PROJECT_OKR"],
    "workspaceIgnoredForSources": ["REQUIREMENT", "TICKET", "WORKLOAD"]
  },
  "summary": { "topMessage": "找到 1 个任务", "total": 1 },
  "items": [ ... ],
  "page": { "current": 1, "size": 10, "total": 1, "hasMore": false },
  "diagnostics": [],
  "actions": { "suggestedNextStep": "orion task explore <id>" }
}

格式模式

• json（默认）：完整 JSON 输出到 stdout，可被 jq 解析
• table：数据表格到 stdout，摘要和诊断到 stderr（适合管道）
• compact：单行 JSON 到 stdout

错误输出

{
  "ok": false,
  "command": "orion task get",
  "traceId": "abc123",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "diagnostics": [],
  "error": {
    "code": "AUTH_MISSING_TOKEN",
    "message": "未设置 ORION_AGENT_TOKEN",
    "resolution": "请在 Orion 设置 > Agent Access 中生成新 token"
  }
}

错误码命名空间

错误码使用 NAMESPACE_SPECIFIC_REASON 格式（大写下划线）。

| 命名空间 | 错误码 | 含义 | | -------------- | ------------------------------ | -------------------------------- | | VALIDATION_* | VALIDATION_MISSING_FIELD | 缺少必填字段 | | | VALIDATION_INVALID_FORMAT | 字段格式非法（如日期、枚举值） | | | VALIDATION_CONFLICT_OPTIONS | 互斥选项同时传入 | | AUTH_* | AUTH_MISSING_BASE_URL | ORION_BASE_URL 未设置 | | | AUTH_MISSING_TOKEN | ORION_AGENT_TOKEN 未设置 | | | AUTH_TOKEN_INVALID | Token 无效（非过期） | | | AUTH_INSUFFICIENT_SCOPE | Token scope 不足以执行操作 | | | AUTH_FORBIDDEN | 已认证但无访问权限 | | POLICY_* | POLICY_BLOCKED | 操作被策略规则阻止（非权限问题） | | WORKSPACE_* | WORKSPACE_UNBOUND | 工作区未绑定 | | | WORKSPACE_CONFLICT | 发现多个冲突的 workspace 配置 | | RESOURCE_* | RESOURCE_NOT_FOUND | 资源不存在 | | | RESOURCE_NOT_FOUND_BY_NUMBER | 按展示编号未找到资源 | | | RESOURCE_AMBIGUOUS_REFERENCE | 标识匹配到多个资源 | | BACKEND_* | BACKEND_CONTRACT_MISMATCH | 后端返回数据结构与预期不符 | | | PARTIAL_DATA | 数据部分返回（操作可能部分成功） | | NETWORK_* | NETWORK_ERROR | 网络连接失败 | | INTERNAL_* | INTERNAL_ERROR | CLI 内部错误 |

退出码

| 退出码 | 含义 | | ------ | -------------------------- | | 0 | 成功 | | 1 | 内部错误 | | 2 | 验证错误 | | 3 | 认证错误 | | 4 | 网络错误 | | 5 | API 业务错误 | | 6 | 策略阻止（POLICY_BLOCKED） |

Workspace

CLI 自动发现 .orion/workspace.json 配置文件：

1. 检查 ORION_WORKSPACE_FILE 环境变量
2. 从当前目录向上查找 .orion/workspace.json
3. 未找到时返回诊断信息（不阻断执行）

初始化 workspace：

orion config init --project-id <project-id>

Dry-Run 预览

写操作与 workflow 预检（task update、task status、task create、complete-task、project inspect）支持 --dry-run：

orion task status TASK-123 IN_PROGRESS --dry-run

输出请求预览或 workflow plan，而非实际执行；其中 complete-task / project inspect 会额外说明底层数据源、状态流转与建议 follow-up。

与 MCP Server 的关系

@yhsp/orion-cli 与 orion-task-mcp MCP Server 共享相同的后端 API，提供一致的语义和输出结构。区别在于：

• MCP Server：面向 AI Agent 集成（通过 MCP 协议通信）
• CLI：面向终端用户和脚本自动化（通过命令行交互）

两者的诊断类型、状态标签、优先级映射和 L1/L2 命令分层保持一致。

Schema 查询

schema 命令用于查询 Orion 平台的 API schema 定义，帮助开发者和 AI Agent 了解可用字段、过滤器与请求/响应结构。

命令语法

orion schema list [--domain <domain>] [--layer <layer>]
orion schema show <command> [--section params|filters|body|response]

选项

| 选项 | 说明 | | --------------------- | ----------------------------------------------------------- | | --domain <domain> | 按业务域过滤（如 task、ticket、req） | | --layer <layer> | 按层级过滤：intent、domain、support | | --section <section> | 仅显示指定 section：params、filters、body、response |

示例

# 列出所有可用 schema
orion schema list

# 按业务域过滤
orion schema list --domain task

# 查看 task list 命令的完整 schema
orion schema show "task list"

# 只查看过滤器定义
orion schema show "task list" --section filters

# 只查看响应结构
orion schema show "task get" --section response

Policy 策略管理

policy 命令用于查看和管理 CLI 的运行策略，控制访问模式、交互模式和严格模式三个维度。写操作被策略阻止时返回错误码 POLICY_BLOCKED（退出码 6）。

策略维度

| 维度 | 可选值 | 默认值 | 说明 | | ----------------- | -------------------- | ------------- | ------------------------------------- | | accessMode | full / read-only | full | 控制写操作是否被允许 | | interactionMode | interactive / ci | interactive | 控制交互提示行为（CI 环境下禁止交互） | | strictMode | true / false | false | 开启后任何警告均视为错误 |

命令语法

orion policy show
orion policy set <dimension> <value>
orion policy reset [<dimension>]

全局策略标志

以下标志可在任意命令中使用，临时覆盖当前已保存的策略（不修改持久化配置）：

| 标志 | 等价策略设置 | | ------------- | ---------------------- | | --read-only | accessMode=read-only | | --ci | interactionMode=ci | | --strict | strictMode=true |

示例

# 查看当前所有维度的策略值
orion policy show

# 设置只读模式（持久化）
orion policy set accessMode read-only

# 设置 CI 模式
orion policy set interactionMode ci

# 开启严格模式
orion policy set strictMode true

# 重置单个维度为默认值
orion policy reset accessMode

# 重置全部维度
orion policy reset

# 临时以只读模式执行单条命令（不修改策略）
orion task list --read-only

# 在 CI 流水线中使用
orion task create --ci --strict

写操作在 accessMode=read-only 策略下会被拒绝，返回 POLICY_BLOCKED（退出码 6）。--read-only、--ci、--strict 三个全局标志对所有命令生效。

Doctor 诊断

doctor 命令在 Phase 2 中重构，共执行 11 项健康检查，覆盖认证、网络连通性、工作区绑定和配置完整性等方面。

命令语法

orion doctor [--check <id>] [--category <category>] [--offline]

选项

| 选项 | 说明 | | ------------------ | --------------------------------------------------- | | --check <id> | 仅运行指定 ID 的单项检查 | | --category <cat> | 按类别运行检查（如 auth、network、workspace） | | --offline | 跳过所有需要网络连接的检查项 |

退出码

| 退出码 | 含义 | | ------ | -------------------------------------- | | 0 | 所有检查通过（pass）或仅有警告（warn） | | 1 | 至少有一项检查失败（fail） |

示例

# 运行全部 11 项检查
orion doctor

# 离线模式（跳过网络检查，适合无网络环境）
orion doctor --offline

# 仅运行认证类检查
orion doctor --category auth

# 运行指定检查项
orion doctor --check workspace.bound

# 在脚本中根据退出码判断环境就绪状态
orion doctor --offline && echo "环境就绪" || echo "请修复上述问题"

orion doctor 的退出码可用于 CI 门禁脚本：退出码 0 表示通过或仅有警告，退出码 1 表示存在失败项。

Shell 补全

completion 命令为 Bash、Zsh 和 Fish shell 生成命令补全脚本，支持子命令、选项和参数的自动补全。

命令语法

orion completion bash|zsh|fish
orion completion install [--shell <shell>]

注意事项

• orion completion bash|zsh|fish 将补全脚本直接输出到 stdout，为纯文本 shell 脚本，不遵循 CLI 的 JSON 输出信封格式，不可用 jq 解析。
• orion completion install 自动检测当前 shell 类型并写入对应配置文件；也可通过 --shell 显式指定目标 shell。

示例

# Bash — 当前会话临时加载
source <(orion completion bash)

# Bash — 持久化写入（推荐）
orion completion bash >> ~/.bashrc

# Zsh — 当前会话临时加载
source <(orion completion zsh)

# Zsh — 持久化写入
orion completion zsh >> ~/.zshrc

# Fish — 写入补全配置目录
orion completion fish > ~/.config/fish/completions/orion.fish

# 自动检测当前 shell 并安装
orion completion install

# 为指定 shell 安装
orion completion install --shell zsh

API 直连（实验性）

⚠️ 实验性功能：api 命令直接透传请求到 Orion 后端 API，绕过 CLI 的数据规范化、类型检查和 schema 验证。如非必要，请优先使用对应的领域命令（如 orion task get）。此功能在未来版本中可能发生破坏性变更，不提供稳定性保证。

api 命令适用于调用 CLI 尚未封装的 API 端点，或需要完全控制请求体的场景。

命令语法

orion api get <path>
orion api post <path> --body <json>
orion api put <path> --body <json>
orion api delete <path> [--yes]

注意事项

• <path> 为相对于 ORION_BASE_URL 的 URL 路径（如 /v1/tasks）。
• api delete 必须附加 --yes 标志作为显式确认，否则命令终止，不发送请求。
• 响应为后端原始返回，不经过 CLI 的 schema 解析和字段规范化。

示例

# 查询资源（GET）
orion api get /v1/tasks?projectId=123

# 创建资源（POST）
orion api post /v1/tasks --body '{"title":"新任务","projectId":"123"}'

# 更新资源（PUT）
orion api put /v1/tasks/TASK-456 --body '{"title":"更新标题"}'

# 删除资源（必须带 --yes）
orion api delete /v1/tasks/TASK-456 --yes

# 配合 jq 解析响应
orion api get /v1/tasks | jq '.items[].title'

如遇到 CLI 命令无法满足的场景，建议先提交 issue 申请对应领域命令支持，再考虑将 api 直连作为临时方案。

开发

# 安装依赖
cd cli/orion-cli && npm install

# 构建
npm run build

# 开发模式（watch）
npm run dev

# 运行测试
npm test

# 类型检查
npm run lint

许可证

内部项目