@rc-pm/pm-cli

pm 是极光 PM Tool Runtime 的命令行入口，主要面向 Coding Agent 和自动化脚本，也可供人工排查使用。

CLI 直接调用 Tool Runtime HTTP 协议，并在运行时读取服务端工具目录。它不会在本地复制一套工具名称或参数定义，也不是 MCP 的二次转发层。

最短使用路径

首次使用从 PM Web 的 /workspace/mcp-cli 页面复制完整命令，不需要手工查找服务地址或 Workspace ID：

# 1. 安装 CLI 和全局 Skills
npm install --global @rc-pm/pm-cli
pm skill install --global

# 2. 使用 PM 页面生成的当前部署与工作区上下文完成初始化和授权
pm setup --from "https://pm.example.com/workspace/mcp-cli?workspace=12"

# 3. 后续工作流只需执行授权硬门
pm auth ensure --tool user.me

pm setup --from 会校验 PM 页面 URL，创建并激活 workspace-<id> Profile，启动 OAuth，通过 user.me 确认当前 PM 权威身份，并通过远端 Tool Catalog 验证授权。缺少初始化时 CLI 返回 PM_SETUP_REQUIRED 和 user_setup 动作；Agent 应要求用户从 PM Web 重新复制完整 Setup 命令，不应询问 serverUrl 或 workspaceId。

pm auth ensure 是 Agent 执行后续 PM 工作流前的强制门禁。成功结果同时包含 data.user 权威身份；失败会返回 结构化 error.action，明确告诉 Agent 是执行 Setup、登录、等待授权还是重试原命令，避免靠连续调用业务接口试错。

Coding Agent、容器或远程终端可以使用无需本地回调端口的设备授权：

pm setup --from "https://pm.example.com/workspace/mcp-cli?workspace=12" --auth-mode device
# 打开 error.action.authorizationUrl 并确认后：
pm auth ensure --json

需要在手机上完成设备授权时，可把结构化错误中的 URL 渲染为终端二维码：

pm auth qrcode "<error.action.authorizationUrl>"

不传 --auth-mode 时仍使用旧版 loopback + PKCE 流程；pm auth login 同样默认 loopback，也可显式使用 pm auth login --mode device 或 pm auth login --mode loopback。

从零验证

使用隔离的配置、Skill 和安装状态目录，不影响当前 CLI Profile：

pm_test_root="$(mktemp -d)"
export PM_CLI_CONFIG_PATH="$pm_test_root/config.json"
export PM_SKILLS_HOME="$pm_test_root/skills"
export PM_SKILLS_STATE_PATH="$pm_test_root/state/skills-install.json"

pm auth ensure --json

第一条检查应以退出码 3 返回 PM_SETUP_REQUIRED，且 error.action.kind 为 user_setup。然后从当前 Workspace 的 PM Web MCP/CLI 页面复制命令并执行：

pm skill install --global
pm setup --from "https://当前-PM-地址/workspace/mcp-cli?workspace=当前工作区ID"
pm config profile show
pm auth ensure --json
pm skill doctor --global --format pretty
pm tool list --format table

成功标准：Profile 名为 workspace-<id>；auth ensure 返回 ready: true、data.user 和非负 toolCount；Skill Doctor 返回 healthy: true；Tool List 只包含当前 Grant 和 UAT 时间窗内可用的 Tool。测试结束后可删除 pm_test_root 对应的临时目录；操作系统凭证存储中的 OAuth 凭证仍由 pm auth logout 显式撤销。

安装全局 Skills

CLI 随包发布 PM Skills 和高频工作流。安装默认的 starter 组合：

pm skill install --global
pm skill doctor --global

默认安装到 ~/.agents/skills，因此支持 Skills 的 Coding Agent 可以从全局入口发现 PM 能力。也可以显式指定目标目录：

pm skill install --target /absolute/path/to/skills

可选安装组合：

| Profile | 内容 | | --- | --- | | core | 全局路由、公共规则、需求范围解析、用户解析 | | task | core、任务能力、任务拆解和任务分诊工作流 | | quality | core、缺陷能力、缺陷上报和缺陷分诊工作流 | | starter | task、quality、交付健康度工作流；默认值 |

常用维护命令：

pm skill list
pm skill update --global --dry-run
pm skill update --global
pm skill remove --global --yes

安装器会验证 bundle 内容哈希并记录安装状态。发现同名但不受 CLI 管理的 Skill，或已安装 Skill 存在本地修改时，会停止操作而不会覆盖。安装状态默认保存在 $XDG_STATE_HOME/jiguang-pm/skills-install.json，未配置 XDG 时使用 ~/.local/state/jiguang-pm/skills-install.json。

升级 CLI 与 Workflow Skill Suite

npm 升级只替换 CLI 包，不会通过 postinstall 静默修改 Agent 的全局 Skill 目录。每次发版后使用同一套 Node/npm 环境依次升级 CLI 和受管 Skill Suite：

pm update --dry-run
pm update
pm doctor

skill update 会在写入前预检整套 starter Profile：旧版且未经修改的 jiguang-pm-* Skill 会被新包覆盖，新加入的 Skill 会安装，已从 Bundle 移除的受管 Skill 会清理；任一 Skill 有本地修改或同名冲突时，整套更新会在写入前停止。旧 CLI 不能把已安装的新版本 Skill 降级，同一版本也不能携带不同内容重新覆盖。

Agent 工作流的统一入口 pm auth ensure 和直接业务命令都会经过 CLI 版本门禁，每 12 小时最多访问一次 npm registry，结果缓存在用户缓存目录。发现新版时返回机器可执行的 cli_update 恢复动作；Agent 执行 pm update 后会同时更新 CLI 与受管 Skill，再重试原工作流。help、version、update、退出登录和授权二维码等信息或恢复命令不会被版本门禁阻断。registry 超时、离线或缓存目录只读时检查自动放行，不影响认证和业务调用。隔离环境可设置 PM_CLI_UPDATE_CHECK=off 关闭后台探测。

使用 NVM、fnm、asdf 或多套 Homebrew Node 时，先确认 npm 和 pm 来自预期的 Node 环境。升级后至少核对：

command -v npm
npm prefix --global
command -v pm
pm --version

如果 pm --version 仍是旧版，说明新包安装到了另一套全局 npm prefix；切回 command -v pm 所属的 Node 环境后重新执行安装。不要删除 Skill 安装状态文件来绕过冲突，否则安装器将无法区分受管 Skill 与用户自建内容。

维护者发布新版本时，在 cli/pm-cli 目录执行：

npm version patch
npm run bundle:check
npm publish

npm version 会同步 package.json、skills-manifest.json 的 CLI/Bundle/全部 Skill 版本与内容哈希；prepublishOnly 会再次执行同步检查、类型检查和测试。版本与哈希不一致时禁止发布。

高频工作流

全局入口 jiguang-pm 根据意图路由到原子 Skill 或工作流：

• 需求范围与需求查询：先解析“项目集 → 版本 → 需求”的唯一上下文。
• 用户解析：把姓名、邮箱等自然语言标识解析为唯一用户 ID。
• 任务拆解：在唯一需求上下文中规划任务、负责人和依赖。
• 任务分诊：查询、归类并规划任务状态或负责人调整。
• 缺陷上报：补齐复现信息并绑定项目集、版本和需求。
• 缺陷分诊：规划严重程度、负责人和处理顺序。
• 交付健康度：联合分析需求、任务与缺陷的交付风险。

所有任务和缺陷工作流都必须先完成需求范围解析；涉及人员时必须先完成用户解析。Skill 只负责编排，工具参数以 pm tool describe <tool-name> 返回的服务端契约为准。

写操作只准备待确认变更。Agent 必须展示业务摘要并获得用户明确确认后，才能执行；默认用户回复不展示内部 确认记录或 ID：

pm confirmation confirm <confirmation-id>

命令

pm setup --from <pm-mcp-cli-url> [--auth-mode loopback|device]

pm tool list
pm tool describe <tool-name>
pm tool call <tool-name> [--input <json> | --input-file <path> | --stdin] [--idempotency-key <key>]
pm tool call <list-tool> --page-all [--max-items <count>] [--input <json>]

pm task +search [--query <text>] [--assignee <user-id>]
pm task +create --input <json> --idempotency-key <key>
pm task +assign <task-id|PM-key|PM-url> --assignee <user-id> --idempotency-key <key>
pm bug +search [--query <text>] [--assignee <user-id>]
pm bug +report --input <json> --idempotency-key <key>
pm requirement +find [--query <text>] [--project <id>] [--version <id>]
pm resolve <pm-url|PM-key|id>

pm confirmation show <confirmation-id>
pm confirmation confirm <confirmation-id>

pm config profile list
pm config profile show [profile-name]
pm config profile set <profile-name> --server <url> [--workspace <id>] [--timeout <ms>] [--activate]
pm config profile use <profile-name>

pm auth login [--mode loopback|device]
pm auth status
pm auth ensure [--tool <tool-name> ...]
pm auth qrcode <authorization-url>
pm auth logout

pm skill list
pm skill install [--profile core|task|quality|starter] [--global] [--target <path>]
pm skill update [--profile core|task|quality|starter] [--global] [--target <path>] [--dry-run]
pm skill remove [--profile core|task|quality|starter] [--global] [--target <path>] --yes
pm skill doctor [--global] [--target <path>]

pm update [--dry-run]
pm doctor

常用全局参数：

-h, --help                      查看根命令或当前子命令帮助
-V, -v, --version               查看 CLI 版本
--profile <name>                仅为本次命令选择 CLI Profile
--format <json|pretty|table|ndjson>
--json                          --format json 的别名
-q, --quiet                     成功时不输出，错误仍输出
--verbose                       向 stderr 输出不含凭证的诊断事件
--                              停止解析全局参数

--profile 作为全局参数时必须放在主命令之前，例如 pm --profile local tool list； pm skill install --profile starter 仍表示 Skill 安装组合。所有带值的长参数同时接受 --option=value，例如 --profile=local、--from=https://... 和 --input='{"id":12}'。

帮助支持完整命令层级：pm tool call --help 与 pm help tool call 等价。help 和 version 默认输出简短纯文本；显式指定 --format json 时返回稳定机器信封。

配置

CLI Profile 保存服务地址、默认工作区和 HTTP 超时：

{
  "activeProfile": "production",
  "profiles": {
    "production": {
      "serverUrl": "https://pm.example.com/",
      "defaultWorkspaceId": 12,
      "timeoutMs": 30000
    }
  }
}

配置文件默认位于 $XDG_CONFIG_HOME/jiguang-pm/config.json，未配置 XDG 时使用 ~/.config/jiguang-pm/config.json。PM_CLI_CONFIG_PATH 可以指定其他文件。

以下环境变量可覆盖 Profile，适用于 CI 和非交互式自动化：

PM_BASE_URL          > profile.serverUrl
PM_WORKSPACE_ID      > profile.defaultWorkspaceId
PM_HTTP_TIMEOUT_MS   > profile.timeoutMs > 30000
PM_PROFILE           仅为当前进程选择 Profile
PM_ACCESS_TOKEN      仅为当前进程提供 Token，不写入配置文件
PM_TIMEZONE          仅为当前进程覆盖时区
PM_SKILLS_HOME       覆盖默认 Skills 安装目录
PM_SKILLS_STATE_PATH 覆盖 Skills 安装状态文件

访问凭证、刷新凭证和待完成的设备授权分别保存在操作系统凭证存储中，不会写入 Profile JSON。CLI 会在 PM Grant/UAT 有效窗口内自动刷新过期访问凭证，并对一次未授权请求执行安全重试。

凭证存储按服务地址（去掉末尾 /）与工作区隔离，账户键为 <serverUrl>|workspace:<workspaceId>。同一系统用户、同一服务和工作区重新登录会替换该账户的凭证。

• macOS：使用系统钥匙串（Keychain）的通用密码项。正式 OAuth 凭证的服务名为 com.jiguang.pm-cli.oauth；待完成设备授权的服务名为 com.jiguang.pm-cli.oauth.device。可在“钥匙串访问”中按服务名查找。存储位置由系统默认钥匙串管理（通常为登录钥匙串），不是项目目录或 CLI 配置 JSON。
• Windows：使用系统自带 Windows PowerShell 5.1 调用 DPAPI CurrentUser 加密，保存到 %LOCALAPPDATA%\JiGuang\PM\credentials\<hash>.dpapi。文件名与加密上下文按服务名和账户键隔离；目录 ACL 仅授予当前 Windows 用户权限，文件中没有明文 Token。敏感数据只通过子进程标准输入传递，不放入命令参数。需要可用的 Windows 用户配置文件、PowerShell 和 DPAPI；系统策略或权限阻止调用时明确报错，不降级为明文文件。加密文件不能直接作为跨用户或跨机器的登录备份。
• Linux：继续使用 secret-tool 接入当前桌面会话的 Secret Service。

pm auth logout 会尝试撤销当前 OAuth 会话并删除当前服务/工作区的正式凭证及待完成设备授权。上述适配归 CLI 本地客户端所有；PM MCP 使用远程 HTTP OAuth，其凭证由 Claude、Codex 等 MCP 宿主管理，PM 服务端不会替第三方宿主指定本地存储位置。

授权恢复按稳定错误码区分：PM_TOOL_ACCESS_REQUIRED 会返回已由预检确认缺少的 action.tools； TOOL_WORKSPACE_MEMBERSHIP_REQUIRED 会返回需要恢复的 action.workspaceId。后者表示当前用户已不在 Grant 绑定的工作区中，重新登录不会修复，需由管理员恢复成员关系。没有精确清单的 TOOL_AUTHORIZATION_DENIED 不得被解释为某几个 Tool 缺失。

输出契约

成功结果写入 stdout；诊断信息和结构化错误写入 stderr。除 help、version 外，默认输出为单行、稳定的 JSON 信封，不根据 TTY 自动变化：

{"ok":true,"command":"tool.list","data":{"items":[]},"meta":{"count":0}}

HTTP 传输层信封会由客户端移除，因此结果不会出现意外的 data.data。meta 允许新增字段，调用方应忽略不认识的字段。

所有命令都支持显式输出格式：

pm tool list --format json    # 默认；稳定命令信封
pm tool list --format pretty  # 简短的人类可读文本
pm tool list --format table   # 稳定通用表格
pm tool list --format ndjson  # 列表项逐行输出
pm tool list --json           # --format json 的别名

非 JSON 输出只是同一份规范化结果的命令级视图，不会额外调用 API。

失败时 stderr 默认只输出一个 JSON 错误信封。显式使用 --verbose 时，错误信封前后可能出现 {"diagnostic":true,...} 诊断事件；Agent 应逐行区分 diagnostic 与 ok 字段，并根据稳定字段分支， 不要解析 message 文案：

{"ok":false,"error":{"type":"authentication","subtype":"credentials_missing","code":"AUTHENTICATION_REQUIRED","message":"PM authentication is required","hint":"run `pm auth login` to authenticate this workspace","retryable":false,"action":{"kind":"user_authorization","command":["pm","auth","login"],"requiresUser":true,"after":"retry_previous_command"}}}

稳定错误类型包括 validation、configuration、authentication、authorization、network、conflict、remote、confirmation 和 internal。错误输出不会包含原始异常、响应体、本地路径或凭证。

稳定退出码：

| 退出码 | 含义 | | ---: | --- | | 0 | 成功 | | 2 | 命令或选项用法错误 | | 3 | 本地配置错误 | | 4 | 认证或授权失败 | | 5 | 命令、网络或服务不可用 | | 6 | 远端业务冲突 | | 7 | 本地或远端输入校验失败 | | 8 | CLI 内部错误或远端契约不兼容 | | 10 | 需要用户显式确认 |

OAuth 授权说明

pm auth login 默认保持旧版 loopback 行为：在 stderr 输出授权链接，用户确认后浏览器回调本机 listener，CLI 再完成 OAuth 2.1 + S256 PKCE Token 交换。显式使用 --mode device 时，CLI 返回 PM_AUTHORIZATION_REQUIRED 和 error.action.authorizationUrl 后立即退出，不启动本地端口；用户确认后再次执行 pm auth ensure，CLI 会从操作系统凭证存储恢复待完成授权并换取正式 Token。任何输出都不会包含 Token 或 device_code。

质量附件与正文图片

quality.material.upload 与网页质量素材上传对应，独立要求上传 Action、精确 Tool Grant、工作区允许范围；指定 requirement_id 时还检查需求工作区和项目访问权限。创建权限不会自动获得上传权限。本功能不新增数据库迁移。

先准备上传（只记录文件元数据，不发送或保存文件内容到 ChangeSet），再确认时上传同一个文件：

pm tool call quality.material.upload --file ./proof.png --input '{"requirement_id":123}' --idempotency-key quality-proof-001
pm changeset confirm <返回的ChangeSet-ID> --file ./proof.png

上传结果中的 url 可以用于 quality.bug.create / quality.bug.update 的 reproduction_materials: [{"url":"..."}]；解决材料使用 resolution_materials。正文贴图使用 reproduction_steps 等富文本字段中的 Tiptap JSON 字符串，其 image 节点为 {"type":"image","attrs":{"src":"上传结果的 URL"}}。上传本身不会创建或修改 Bug，创建/更新仍使用独立 ChangeSet 确认。数组更新按完整替换处理，传 [] 清空；不传字段则保留原值。

CLI 通过 multipart 传文件，最大 200 MiB；确认时校验元数据中的大小与 SHA-256，变更文件后需要重新准备。必要时调整 CLI 请求超时。MCP 使用同一上传 Tool 准备元数据，调用 changeset.confirm 时可额外传 file_base64，仅用于本次确认、不持久化，解码后上限 512 KiB；大文件请使用 CLI 完整执行准备与确认，不能跨客户端或 Grant 复用 ChangeSet。

质量状态流转使用 quality.bug.status.update：提交解决为 review，携带 resolution_reason、resolution_note、resolution_materials；重新打开为 reopened，携带 regression_note、regression_materials；通用流转说明为 activity_note。 图片先通过 quality.material.upload 获取 URL，随后与状态在同一次确认内保存。 状态活动记录包含前后状态、说明和材料，重新打开不会覆盖原始复现正文。 指派使用独立 quality.bug.assign，支持 assignment_note、assignment_materials。 普通字段修改才使用 quality.bug.update。执行后同时回读详情及 quality.bug.activity.list。

文档正文写入

创建节点后读取 document.id，使用 document.get 获取 revision、schema_version，再通过 document.content.replace 提交完整 Tiptap JSON 对象。确认后回读正文。协作文档存在连接时拒绝替换，返回 DOCUMENT_EDITING_IN_PROGRESS；版本冲突返回 DOCUMENT_VERSION_CONFLICT。该 Tool 沿用文档正文编辑 Action、对象编辑权限和精确 Grant。