@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 | ✅ 部分可用 | orion my、orion workload | | task | task | ✅ 已实现 | orion task list/get/... | | ticket | ticket | ✅ 已实现 | orion ticket search/... | | requirement | requirement | ✅ 已实现 | orion req my-tasks/... | | project | project | ✅ 已实现 | orion project list/... | | okr | okr | ✅ 已实现 | orion okr list/... | | report | report | ✅ 已实现 | orion report daily/weekly/workload/inspection |

骨架命令（🔧）：命令已注册并可被发现（orion meta tools 可列出），执行时返回 NOT_IMPLEMENTED 诊断，退出码 2。将在后续版本补齐实现。

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

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 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 "登录功能"

命令速查表

Intent 层命令（高频入口）

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

Domain 层 — workload 域

| 命令 | MCP 等价 | 说明 | | ----------------------------- | ----------------------- | --------------------- | | orion workload | orion_get_my_workload | 工作负载（显式入口） | | orion workload user [--uid] | — | 指定成员负载 [规划中] | | orion workload team | — | 团队负载聚合 [规划中] |

Domain 层 — task 域

| 命令 | MCP 等价 | 说明 | | --------------------------------------------- | ---------------------------------------- | ---------------- | | orion task list | orion_my_workspace_tasks | 当前工程任务列表 | | orion task get <id> | orion_get_task | 任务详情 | | orion task explore <id> | orion_explore_task | 深挖任务上下文 | | orion task create | orion_create_task | 创建任务 ✏️ | | orion task update <id> | orion_update_task | 更新任务 ✏️ | | orion task status <id> <status> | orion_change_task_status | 变更任务状态 ✏️ | | orion task attachments <id> | orion_get_task_attachments | 任务附件列表 | | orion task download-url <id> <attachmentId> | orion_get_task_attachment_download_url | 获取附件下载链接 |

Domain 层 — ticket/req/project/okr 域 [已实现]

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

| 命令 | 说明 | | ---------------------------------------------------------------------- | ------------------------------------ | | orion project list [--keyword] [已实现] | 项目列表 | | orion project get <id> [已实现] | 项目详情 | | orion project overview <id> [已实现] | 项目概览 | | orion req my-tasks [--limit] [已实现] | 我的需求任务 | | orion req owned [--limit] [已实现] | 我负责的需求 | | orion req pool [--pool-id] [--limit] [已实现] | 需求池浏览 | | orion req create [骨架] | 创建需求任务 | | orion ticket search --query <keyword> [已实现] | 工单搜索 | | orion ticket get <id> [已实现] | 工单详情 | | orion ticket my [--limit] [已实现] | 我的工单 | | orion ticket attachments <id> [已实现] | 工单附件列表 | | orion ticket download-url <id> [已实现] | 工单附件下载链接 | | orion okr list [已实现] | OKR 列表 | | orion okr summary <objectiveId> [已实现] | OKR 摘要 | | orion okr kr-tasks <krId> [已实现] | KR 关联任务 | | orion report daily [已实现] | 日报生成 | | orion report weekly [已实现] | 周报生成 | | orion report workload [--team <identifier>] [已实现] | 负载分析报告（支持个人与团队维度） | | orion report inspection [--limit <n>] [--project-ids <ids>] [已实现] | 多项目巡检报告（跨项目治理健康快照） |

Support 层命令（自省与配置）

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

配置管理

| 命令 | 说明 | | --------------------------------------------- | --------------------- | | orion config init --project-id <project-id> | 初始化 workspace 配置 | | orion config show | 显示当前配置 | | orion config check | 检查配置完整性 |

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

全局选项

| 选项 | 默认值 | 说明 | | --------------------- | -------- | ------------------------------------ | | -f, --format <type> | json | 输出格式：json、table、compact | | --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 | — | 禁用终端颜色 |

环境变量

| 变量 | 必需 | 说明 | | ---------------------------- | ---- | ------------------------------- | | ORION_BASE_URL | ✅ | Orion 后端 API 地址 | | ORION_AGENT_TOKEN | ✅ | Agent 访问令牌 | | ORION_CLIENT_NAME | — | 客户端标识（默认 orion-cli） | | ORION_WORKSPACE_FILE | — | 显式指定 workspace 配置文件路径 | | ORION_DISABLE_UPDATE_CHECK | — | 关闭启动时的版本更新提示 |

升级 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": "UNAUTHORIZED_AGENT_TOKEN",
    "message": "认证失败：ORION_AGENT_TOKEN 无效或已过期",
    "resolution": "请在 Orion 设置 > Agent Access 中生成新 token"
  }
}

退出码

| 退出码 | 含义 | | ------ | ------------ | | 0 | 成功 | | 1 | 内部错误 | | 2 | 验证错误 | | 3 | 认证错误 | | 4 | 网络错误 | | 5 | API 业务错误 |

Workspace

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

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

初始化 workspace：

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

Dry-Run 预览

写操作（task update、task status、task create）支持 --dry-run：

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

输出请求预览而非实际执行，包含 method、URL、headers、query、body 信息。

与 MCP Server 的关系

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

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

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

开发

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

# 构建
npm run build

# 开发模式（watch）
npm run dev

# 运行测试
npm test

# 类型检查
npm run lint

许可证

内部项目