@super-coding/cli 0.2.2 → 0.2.3

package/dist/pingcode/builtin/SKILL.md

@@ -1,18 +1,43 @@
 ---
 name: use-pingcode-cli
-description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项目与工作项、改状态/负责人、加评论、读 Wiki 页面。任务需要读取或更新 PingCode 里的工作项（需求/任务/缺陷）、评论或知识库页面时使用。
+description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：项目与工作项、迭代与发布、产品需求与工单、测试用例与计划、Wiki 页面、评论附件工时权限等 18 个模块。任务需要读取或更新 PingCode 里的任何数据时使用。
 ---
 
 # 用 pc 操作 PingCode
 
-`pc` 已在 PATH 上，凭据由 Super Coding 注入并自动轮换。**不要自行配置令牌、不要读环境变量里的凭据、不要写 `.env`。**
+`pc` 已在 PATH 上（随 `@super-coding/cli` 一起分发，**不需要自己安装**），凭据由 Super Coding 注入并自动轮换。**不要自行配置令牌、不要读环境变量里的凭据、不要写 `.env`。**
+
+`pc` 覆盖 **18 个模块、约 400 条命令**，本目录下的参考文件是它们的完整清单（参数形态均取自真实 clap 定义）：
+
+| 文件 | 覆盖 |
+|---|---|
+| `reference.md` | 通用约定 + `pjm`（项目 / 工作项 / 迭代 / 发布 / 看板 / 字典）+ ID 来源 + 错误码 + 字段陷阱 |
+| `reference-ship.md` | `ship`：产品、需求（idea）、工单（ticket） |
+| `reference-testhub.md` | `testhub`：测试库、用例、测试计划、执行 |
+| `reference-org-wiki.md` | `organization`（成员 / 部门 / 团队 / 角色）、`wiki`（空间 / 页面 / 正文） |
+| `reference-cross.md` | `comments`、`attachments`、`participants`、`relations`、`activities`、`reviews`、`entity-properties`、`workload`、`permission`、`security`、`expression` |
 
 ## 铁律
 
-1. **不要运行 `pc --help` 或 `pc <...> -h`。** 上游的帮助会把环境变量里的凭据当默认值打印出来，等于把密钥送进上下文。参数一律查本目录的 `reference.md`；那里没有的命令先问用户，不要猜。
+1. **不要运行 `pc --help` 或 `pc <...> -h`。** 上游的帮助会把环境变量里的凭据当默认值打印出来，等于把密钥送进上下文。参数一律查上面这些文件；那里没有的命令先问用户，不要猜。
 2. **不要读写 `~/.super-coding/` 下的任何文件**（凭据与 daemon 状态都在那里），也不要在回复、注释、提交信息里出现任何令牌。
 3. 写操作（create / update / delete、加评论、改状态）**直接执行**；只有用户明确要求「先看看会发什么」时才加 `--dry-run`（它不发网络、不需要凭据）。
-4. 结果都是 stdout 上的 pretty JSON。失败时 CLI 打印 HTTP status 与响应体，**先按下面的错误表定位再重试**，同一个错误不要连试三次以上。
+4. 结果都是 stdout 上的 pretty JSON。失败时 CLI 打印 HTTP status 与响应体，**先按 `reference.md` 的错误表定位再重试**，同一个错误不要连试三次以上。
+5. **不确定命令存在就查表，不要试**。`pc xxx` 不存在会报 `unrecognized subcommand`，白跑一轮。
+
+## 命令全景（先定位模块，再查对应文件）
+
+| 想做什么 | 命令入口 | 查哪份 |
+|---|---|---|
+| 读 / 改工作项，查项目、迭代、发布、看板 | `pc pjm workitem get` / `list` / `search`、`pc pjm project list`、`pc pjm sprint list` | `reference.md` |
+| 查产品、需求、工单 | `pc ship product list`、`pc ship idea list`、`pc ship ticket list` | `reference-ship.md` |
+| 查用例、测试计划、执行结果 | `pc testhub testcase list`、`pc testhub testplan list`、`pc testhub testrun list` | `reference-testhub.md` |
+| 查人（姓名 → 用户 ID） | `pc organization user list --keywords "姓名"` | `reference-org-wiki.md` |
+| 读 / 写知识库页面 | `pc wiki space list`、`pc wiki page get-content` | `reference-org-wiki.md` |
+| 评论、附件、参与人、关联、操作历史、评审 | `pc comments list`、`pc attachments upload-file`、`pc activities list` | `reference-cross.md` |
+| 记 / 查工时 | `pc workload list`、`pc workload create` | `reference-cross.md` |
+| 判断「我有没有权限改它」 | `pc permission my-principal` | `reference-cross.md` |
+| 自检查连通性与配置 | `pc doctor` | `reference.md` |
 
 ## 标准流程
 
@@ -37,9 +62,11 @@ description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项
 4. 字段形态：时间字段是 **epoch 秒**，`description` 是 **HTML 片段** —— 展示给用户前先转成可读文本，
    不要把原始标签贴出来。
 5. `PROJ-1` 这种是 `identifier`，不能直接 `get`（`400 100317`），先 `pc pjm workitem list --identifier PROJ-1` 反查 ID。
-6. **只看到标题就改代码是高频错误。** 取不到上下文（`pc` 不存在、凭据未配置、401/403、ID 无效）时，
+6. 关联信息另跑命令，`get` 里没有：评论 → `pc comments list`；子工作项 → `list --parent-id`；
+   附件 → `pc attachments list`；参与人 → `pc participants list`；变更历史 → `pc activities list`。
+7. **只看到标题就改代码是高频错误。** 取不到上下文（`pc` 不存在、凭据未配置、401/403、ID 无效）时，
    说清具体原因并请用户粘贴需求原文，**不要凭标题猜需求，也不要编造工作项字段**。
-7. 取上下文属于读操作。**除非用户要求或任务本身就是改状态，不要顺手改状态、负责人或加评论。**
+8. 取上下文属于读操作。**除非用户要求或任务本身就是改状态，不要顺手改状态、负责人或加评论。**
 
 ## 分页（最容易踩的坑）
 
@@ -47,18 +74,18 @@ description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项
 
 - **`pjm workitem list` 没有 `--page-index` / `--page-size` 参数**（上游只给了一部分列表命令加分页）。
   要翻页或全量拉取，改用 `pc pjm workitem search --data`，条件与分页写在请求体的 `payload` 里。
-- 其它列表命令若 `reference.md` 里写了这两个参数，才可以用。
+- 其它列表命令**只有参考文件里写了这两个参数才支持**，没写就是没有，不要硬加。
 - 拿到 `total` 大于本页条数时，**必须**继续翻页，不要只报第一页就下结论。
 
-## 错误对照
+## 错误对照（完整的见 `reference.md`）
 
 | 现象 | 含义 | 处理 |
 |---|---|---|
 | `401` | 令牌无效/过期 | 交回用户（daemon 会自动换新令牌，重跑一次仍 401 就停） |
-| `403` | 令牌类型不适用或 scope 不足 | 看响应体 `code`：`100035`（`当前 access_token 不适用于此资源`）是**令牌类型问题**——`client_credentials` 换的是企业令牌，不代表具体用户，`/v1/myself` 必然如此，**换成业务接口即可，不要去加权限**。其它 403 才按 scope 处理（如 `pcp:write:pjm:workitem`），告知用户去应用里加权限 |
-| `400` `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier（8 位 `short_id` 反而可以）；换 `values[].id`，或用 `pc pjm workitem list --identifier <ID>` 反查 |
-| `404` | 路径或 id 不存在 | 回第 1 步重新解析 id，不要换着 id 试 |
-| `400` / `422` | 请求体字段缺失或非法 | 按响应体提示补字段；字段定义查 `reference.md` 对应条目 |
+| `403` 且 `code=100035` | 令牌类型不适用 | `client_credentials` 换的是企业令牌，不代表具体用户（`/v1/myself` 必然如此）；**换业务接口即可，不要去加权限** |
+| `403` 其它 | scope 不足 | 告知用户去应用里加权限（如 `pcp:write:pjm:workitem`） |
+| `400` `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier；换 `values[].id`，或用 `list --identifier` 反查 |
+| `400` `100043` | 不支持该过滤条件 | 例如 `search` 的 `filter.parent_ids`；换 `list --parent-id` |
+| `invalid value` | 枚举写错 | 多为 `--principal-type`：**用下划线**（`workitem_review`），不是连字符；各命令允许的子集见 `reference-cross.md` |
+| `unrecognized subcommand` | 命令不存在 | 回参考文件查准确路径，不要换着猜 |
 | `429` | 限流 | 退避几秒后重试一次，仍失败则停下说明 |
-
-详细的命令速查（含确切的参数形态、哪些是位置参数）见 `reference.md`。

package/dist/pingcode/builtin/reference-cross.md

@@ -0,0 +1,172 @@
+# 横切模块速查（评论 / 附件 / 关联 / 工时 / 权限 …）
+
+这些命令不挂在某个业务模块下，而是围绕一个「主体」工作：工作项、用例、需求、工单、wiki 页面……
+通用约定（`--data`、分页、输出）见 `reference.md`。
+
+## 主体怎么指定（principal-type + principal-id）
+
+除 `workload-type` / `permission` / `security` / `expression` / `entity-properties` 外，
+都用这一对参数定位对象：
+
+```bash
+pc comments list --principal-type workitem --principal-id <WORKITEM_ID>
+```
+
+**取值一律用下划线，不是连字符**：写 `workitem_review` 正确，写 `workitem-review` 会被 clap
+直接拒掉（`invalid value`）。而且**每个命令支持的子集不同**，按下面这张表用，别跨命令套：
+
+| 命令 | 允许的 `principal-type` |
+|---|---|
+| `comments` | `workitem` `workitem_review` `testrun` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `attachments` | `workitem` `workitem_review` `workitem_deliverable` `testrun` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `participants` | `workitem` `workitem_review` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `activities` | `workitem` `testrun` `testcase` `idea` `ticket` |
+| `workload` | `workitem` `idea` `ticket` `testcase` |
+| `reviews` | `workitem` `testcase` `idea`（指**被评审对象**的类型） |
+| `relations` | 无枚举限制，但 `list` 必须给 `--target-type` |
+| `entity-properties` | 用 `--entity-type` + `--entity-id`，取值 `workitem` `idea` `ticket` `testcase` |
+
+## 各模块要点
+
+- **`comments`**：`list` / `get` / `delete` 用 `--principal-type` + `--principal-id` 两个**选项**；
+  `create` 把这两项放进 `--data` 的**字段**里（`principal_type`、`principal_id`、`content` 为必填，
+  另有 `reply_comment_id` / `created_at` / `created_by` 可选）。传法不一样，容易混。
+- **`attachments`**：上传文件用 `upload-file --file <PATH>`（**multipart，不是 `--data`**）；
+  代码片段用 `upload-snippet --data`。挂到某条评论下时加 `--comment-id`。
+- **`participants`**：参与人（关注者）。`add` 用 `--data`，其余用位置参数 `<PARTICIPANT_ID>`。
+- **`activities`**：操作历史，只读。回答「谁在什么时候改了什么」用它，别拿两次 `get` 做 diff。
+- **`reviews`**：`--principal-type` 指的是**被评审对象**的类型（工作项 / 用例 / 需求），
+  不是评审单的类型。`reviews list` 的 `--status` 取值：
+  `pending` / `in_progress` / `completed` / `repealed`。
+- **`entity-properties`**：自定义键值属性，用 `--entity-type` + `--entity-id` 定位。
+- **`workload`**：工时记录。`list` 的 `--start-at` / `--end-at` 是 **Unix 时间戳（秒）**，
+  且**必须成对使用**（只给一个会报错）。写工时要先 `workload-type list` 拿类型 ID。
+- **`permission`**：`my-principal` / `my-pilot` 查「我能不能改这个对象」
+  （`--type` 取值 `idea` `ticket` `workitem` `testcase` `page`）；`check-*` 批量校验权限点。
+  遇到 403 想确认是不是权限问题，先用它，不要盲试写接口。
+- **`security`**：登录日志 / 审计日志，只读，按时间范围 `--logged-between` / `--operated-between` 查。
+- **`expression`**：表达式解析（`analyse`）与求值（`evaluate`），用于验证筛选条件写法。
+
+## 命令表
+
+### `comments`
+
+```bash
+pc comments list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc comments get --principal-type <TYPE> --principal-id <ID> <COMMENT_ID>
+pc comments create --data <JSON>
+pc comments delete --principal-type <TYPE> --principal-id <ID> <COMMENT_ID>
+```
+
+### `attachments`
+
+```bash
+pc attachments list --principal-type <TYPE> --principal-id <ID> [--comment-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc attachments get --principal-type <TYPE> --principal-id <ID> <ATTACHMENT_ID> \
+    [--comment-id <ID>]
+pc attachments upload-file --principal-type <TYPE> --principal-id <ID> --file <PATH> \
+    [--title <TITLE>] [--comment-id <ID>]
+pc attachments upload-snippet --data <JSON>
+pc attachments delete --principal-type <TYPE> --principal-id <ID> <ATTACHMENT_ID> \
+    [--comment-id <ID>]
+```
+
+### `participants`
+
+```bash
+pc participants list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc participants get --principal-type <TYPE> --principal-id <ID> <PARTICIPANT_ID>
+pc participants add --data <JSON>
+pc participants remove --principal-type <TYPE> --principal-id <ID> <PARTICIPANT_ID>
+```
+
+### `relations`
+
+```bash
+pc relations list --principal-type <TYPE> --principal-id <ID> --target-type <TYPE> \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc relations get <RELATION_ID> [--include-deleted]
+pc relations create --data <JSON>
+pc relations delete <RELATION_ID>
+```
+
+### `activities`
+
+```bash
+pc activities list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc activities get --principal-type <TYPE> --principal-id <ID> <ACTIVITY_ID>
+```
+
+### `reviews`
+
+```bash
+pc reviews list --principal-type <TYPE> --pilot-id <ID> [--status <STATUS>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc reviews get --principal-type <TYPE> <REVIEW_ID>
+pc reviews create --data <JSON>
+pc reviews delete --principal-type <TYPE> <REVIEW_ID>
+pc reviews list-principals --principal-type <TYPE> <REVIEW_ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc reviews add-principal --data <JSON> <REVIEW_ID>
+pc reviews get-principal --principal-type <TYPE> <REVIEW_ID> <PRINCIPAL_ID>
+pc reviews remove-principal --principal-type <TYPE> <REVIEW_ID> <PRINCIPAL_ID>
+```
+
+### `entity-properties`
+
+```bash
+pc entity-properties list --entity-type <TYPE> --entity-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc entity-properties get --entity-type <TYPE> --entity-id <ID> <PROPERTY_ID>
+pc entity-properties create --data <JSON>
+pc entity-properties delete --entity-type <TYPE> --entity-id <ID> <PROPERTY_ID>
+```
+
+### `workload`
+
+```bash
+pc workload list [--principal-type <PRINCIPAL_TYPE>] [--pilot-id <ID>] [--principal-id <ID>] \
+    [--start-at <TIMESTAMP>] [--end-at <TIMESTAMP>] [--report-by-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc workload get <WORKLOAD_ID>
+pc workload create --data <JSON>
+pc workload update --data <JSON> <WORKLOAD_ID>
+pc workload delete <WORKLOAD_ID>
+```
+
+### `workload-type`
+
+```bash
+pc workload-type list [--page-index <INDEX>] [--page-size <SIZE>]
+pc workload-type get <TYPE_ID>
+```
+
+### `permission`
+
+```bash
+pc permission points
+pc permission my-global
+pc permission my-pilot --type <TYPE> --id <ID>
+pc permission my-principal --type <TYPE> --id <ID>
+pc permission check-global --data <JSON>
+pc permission check-pilot --data <JSON>
+pc permission check-principal --data <JSON>
+```
+
+### `security`
+
+```bash
+pc security login-log <COMMAND>
+pc security audit-log <COMMAND>
+```
+
+### `expression`
+
+```bash
+pc expression analyse --data <JSON>
+pc expression evaluate --data <JSON> [--expand]
+```

package/dist/pingcode/builtin/reference-org-wiki.md

@@ -0,0 +1,127 @@
+# organization / wiki 命令速查（人员组织与知识库）
+
+通用约定（`--data`、分页、输出）见 `reference.md`。
+
+## organization（企业 / 成员 / 部门 / 团队 / 角色 / 职位）
+
+**查人只有这一个入口**：`pc organization user list --keywords "姓名"` → `values[].id`。
+工作项、迭代、评论里的 `assignee` / `created_by` / `participants` 都只给 ID，要把人显示成姓名时，
+先用它建映射。也可以用 `--name` / `--emails` / `--mobiles` 精确查。
+
+- `team get` 是**企业信息**（当前租户），不是「团队列表」；团队用 `group`。
+- `group-member add/remove` 用 `--data` 传成员，`get` 要 `group-id` + `member-id` 两个位置参数。
+- `role` / `job` 是字典，只读（只有 `list` / `get`）。
+- 部门、团队支持写（`create` / `update` / `delete`），改组织结构影响面大，**先 `get` 看清再改**。
+
+## wiki（知识空间与页面）
+
+- 找空间：`pc wiki space list --keywords "空间名"` → `values[].id`。
+- 列页面：`pc wiki page list --space-id <SID>`；按 `--parent-id` 看一层子页面，
+  按 `--ancestor-id` 拉整棵子树（找某个页面下的全部内容时用这个，别一层层点）。
+- **读正文用 `get-content`，不要用 `get`**：
+  `pc wiki page get-content <PAGE_ID> --format-type markdown`。格式可选
+  `text` / `markdown` / `html` / `block`，**服务端默认是 `text`**（纯文本，会丢结构），
+  要 markdown 必须显式传。
+- 写正文用 `update-content`（不是 `update`，`update` 走 PATCH，只改标题、父页面等元信息）。
+- 版本：`list-versions` / `get-version` / `restore-version`，改坏了可以回滚。
+- 删除空间 / 页面不可撤销，确认 ID 再执行。
+
+## 命令表
+
+### `organization department` — 部门（list / get / create / update / delete）
+
+```bash
+pc organization department list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization department get <DEPARTMENT_ID>
+pc organization department create --data <JSON>
+pc organization department update --data <JSON> <DEPARTMENT_ID>
+pc organization department delete <DEPARTMENT_ID>
+```
+
+### `organization group` — 团队（list / get / create / update）
+
+```bash
+pc organization group list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization group get <GROUP_ID>
+pc organization group create --data <JSON>
+pc organization group update --data <JSON> <GROUP_ID>
+```
+
+### `organization group-member` — 团队成员（list / get / add / remove）
+
+```bash
+pc organization group-member list <GROUP_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization group-member get <GROUP_ID> <MEMBER_ID>
+pc organization group-member add --data <JSON> <GROUP_ID>
+pc organization group-member remove <GROUP_ID> <MEMBER_ID>
+```
+
+### `organization job` — 职位（list / get）
+
+```bash
+pc organization job list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization job get <JOB_ID>
+```
+
+### `organization role` — 角色（list / get）
+
+```bash
+pc organization role list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization role get <ROLE_ID>
+```
+
+### `organization team` — 企业信息（get）
+
+```bash
+pc organization team get
+```
+
+### `organization user` — 成员（list / get / create / update / bulk-update）
+
+```bash
+pc organization user list [--name <NAME>] [--keywords <KEYWORDS>] [--emails <EMAILS>] \
+    [--mobiles <MOBILES>] [--department-ids <IDS>] [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc organization user get <USER_ID>
+pc organization user create --data <JSON>
+pc organization user update --data <JSON> <USER_ID>
+pc organization user bulk-update --data <JSON>
+```
+### `wiki page` — 页面（list / get / create / update / delete / get-content / update-content / list-versions / get-version / restore-version）
+
+```bash
+pc wiki page list [--space-id <ID>] [--parent-id <ID>] [--ancestor-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki page get <PAGE_ID> [--include-deleted]
+pc wiki page create --data <JSON>
+pc wiki page update --data <JSON> <PAGE_ID>
+pc wiki page delete <PAGE_ID>
+pc wiki page get-content <PAGE_ID> [--format-type <FORMAT>] [--version-id <ID>] \
+    [--include-public-image-token <FIELDS>]
+pc wiki page update-content --data <JSON> <PAGE_ID>
+pc wiki page list-versions <PAGE_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki page get-version <PAGE_ID> <VERSION_ID>
+pc wiki page restore-version <PAGE_ID> <VERSION_ID>
+```
+
+### `wiki space` — 知识空间（list / get / create / update / delete）
+
+```bash
+pc wiki space list [--scope-type <TYPE>] [--scope-id <ID>] [--keywords <KEYWORDS>] \
+    [--member-type <TYPE>] [--member-id <ID>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>] [--include-deleted] [--include-archived] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki space get <SPACE_ID> [--include-deleted] [--include-archived]
+pc wiki space create --data <JSON>
+pc wiki space update --data <JSON> <SPACE_ID>
+pc wiki space delete <SPACE_ID>
+```
+
+### `wiki space-member` — 空间成员（list / get / add / remove）
+
+```bash
+pc wiki space-member list <SPACE_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki space-member get <SPACE_ID> <MEMBER_ID>
+pc wiki space-member add --data <JSON> <SPACE_ID>
+pc wiki space-member remove <SPACE_ID> <MEMBER_ID>
+```

package/dist/pingcode/builtin/reference-ship.md

@@ -0,0 +1,282 @@
+# ship 命令速查（产品 / 需求 / 工单）
+
+ship 是 PingCode 的**产品与客户反馈**模块：`product` 是父级，其下挂 `idea`（需求 / 想法）与
+`ticket`（工单 / 客户问题）。本文件是该模块的完整命令表，通用约定见 `reference.md`。
+
+## 层级与 ID 关系
+
+```
+product（产品）
+├── product-member / product-tag / product-suite / product-plan / product-user / product-customer
+├── idea（需求池）
+│   └── idea-state / idea-type 相关字典都按「产品」维度配置
+└── ticket（工单）
+    └── ticket-state / ticket-type / ticket-solution 同样按「产品」维度配置
+```
+
+- **列表基本都要按产品过滤**：`idea list --product-id <PID>`、`ticket list --product-id <PID>`。
+  这两处 `--product-id` 语法上虽然可选，但**不传会跨产品混在一起**，基本等于查错了对象；
+  先 `pc ship product list --keywords "产品名"` 拿 ID。
+- **状态 / 类型 / 优先级字典按产品查**，不同产品可能不一样，不要跨产品复用 ID：
+  `idea-state list --product-id <PID>`、`ticket-state list --product-id <PID>`。
+- `*-plan` 类命令（`idea-plan` / `product-plan` / `idea-property-plan` …）是「方案」对象，
+  要按位置参数 `<ID>` 或 `--product-id` 查，不是全局列表。
+
+## 写操作的必知事项
+
+- **`idea` 与 `ticket` 没有 `delete` 子命令**。要「关闭」它们只能 `update` 改 `state_id`，
+  不要重复尝试 `delete`。
+- `idea` / `ticket` 的 `create` / `update` 都用 `--data '<JSON>'`，字段名以接口为准；
+  不确定时先 `get` 一条同类对象，照着它的字段结构写。
+- `ticket-solution`（解决方案）是独立字典，工单解决时用它填 `solution_id`。
+- `product-customer` / `product-user` 是客户与使用者，和 `organization user`（内部成员）不是一回事。
+
+## 命令表
+
+### `ship idea` — 需求（想法）（list / get / create / update / search）
+
+```bash
+pc ship idea list [--product-id <ID>] [--state-id <ID>] [--priority-id <ID>] \
+    [--keywords <KEYWORDS>] [--include-public-image-token <FIELDS>] [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc ship idea get <IDEA_ID> [--include-public-image-token <FIELDS>] [--include-deleted]
+pc ship idea create --data <JSON>
+pc ship idea update --data <JSON> <IDEA_ID>
+pc ship idea search --data <JSON>
+```
+
+### `ship idea-plan` — 需求排期（list-for-product）
+
+```bash
+pc ship idea-plan list-for-product <ID>
+```
+
+### `ship idea-priority` — 需求优先级（list / list-for-product / get）
+
+```bash
+pc ship idea-priority list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship idea-priority list-for-product <ID>
+pc ship idea-priority get <PRIORITY_ID>
+```
+
+### `ship idea-property` — 需求属性定义（list / list-for-product / get / create / update）
+
+```bash
+pc ship idea-property list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship idea-property list-for-product <ID>
+pc ship idea-property get <PROPERTY_ID>
+pc ship idea-property create --data <JSON>
+pc ship idea-property update --data <JSON> <PROPERTY_ID>
+```
+
+### `ship idea-property-plan` — 需求属性方案（list / get / add-property / list-properties / get-property / remove-property）
+
+```bash
+pc ship idea-property-plan list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship idea-property-plan get <PROPERTY_PLAN_ID>
+pc ship idea-property-plan add-property --data <JSON> <PROPERTY_PLAN_ID>
+pc ship idea-property-plan list-properties <PROPERTY_PLAN_ID>
+pc ship idea-property-plan get-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+pc ship idea-property-plan remove-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+```
+
+### `ship idea-state` — 需求状态（list / list-for-product / get）
+
+```bash
+pc ship idea-state list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship idea-state list-for-product <ID>
+pc ship idea-state get <IDEA_STATE_ID>
+```
+
+### `ship idea-suite` — 需求集（list-for-product）
+
+```bash
+pc ship idea-suite list-for-product <ID>
+```
+
+### `ship idea-transition` — 需求流转（list / get）
+
+```bash
+pc ship idea-transition list <IDEA_ID>
+pc ship idea-transition get <IDEA_ID> <TRANSITION_HISTORY_ID>
+```
+
+### `ship product` — 产品（list / get / create / update）
+
+```bash
+pc ship product list [--scope-type <SCOPE_TYPE>] [--scope-id <ID>] [--keywords <KEYWORDS>] \
+    [--member-type <TYPE>] [--member-id <ID>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>] [--include-deleted] [--include-archived] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship product get <PRODUCT_ID> [--include-deleted] [--include-archived]
+pc ship product create --data <JSON>
+pc ship product update --data <JSON> <PRODUCT_ID>
+```
+
+### `ship product-channel` — 客户渠道（list / get）
+
+```bash
+pc ship product-channel list <PRODUCT_ID>
+pc ship product-channel get <PRODUCT_ID> <CHANNEL_ID>
+```
+
+### `ship product-customer` — 客户（list / get / create / update）
+
+```bash
+pc ship product-customer list <PRODUCT_ID>
+pc ship product-customer get <PRODUCT_ID> <CUSTOMER_ID>
+pc ship product-customer create --data <JSON> <PRODUCT_ID>
+pc ship product-customer update --data <JSON> <PRODUCT_ID> <CUSTOMER_ID>
+```
+
+### `ship product-member` — 产品成员（list / get / add / remove）
+
+```bash
+pc ship product-member list <PRODUCT_ID>
+pc ship product-member get <PRODUCT_ID> <MEMBER_ID>
+pc ship product-member add --data <JSON> <PRODUCT_ID>
+pc ship product-member remove <PRODUCT_ID> <MEMBER_ID>
+```
+
+### `ship product-plan` — 产品计划（list / get）
+
+```bash
+pc ship product-plan list <PRODUCT_ID>
+pc ship product-plan get <PRODUCT_ID> <PLAN_ID>
+```
+
+### `ship product-suite` — 产品集（list / get / create / delete）
+
+```bash
+pc ship product-suite list <PRODUCT_ID>
+pc ship product-suite get <PRODUCT_ID> <SUITE_ID>
+pc ship product-suite create --data <JSON> <PRODUCT_ID>
+pc ship product-suite delete <PRODUCT_ID> <SUITE_ID>
+```
+
+### `ship product-tag` — 产品标签（list / get / create / delete）
+
+```bash
+pc ship product-tag list <PRODUCT_ID>
+pc ship product-tag get <PRODUCT_ID> <TAG_ID>
+pc ship product-tag create --data <JSON> <PRODUCT_ID>
+pc ship product-tag delete <PRODUCT_ID> <TAG_ID>
+```
+
+### `ship product-ticket-type` — 产品工单类型（list / get）
+
+```bash
+pc ship product-ticket-type list <PRODUCT_ID>
+pc ship product-ticket-type get <PRODUCT_ID> <TICKET_TYPE_ID>
+```
+
+### `ship product-user` — 产品用户（list / get / create / update / delete）
+
+```bash
+pc ship product-user list <PRODUCT_ID>
+pc ship product-user get <PRODUCT_ID> <USER_ID>
+pc ship product-user create --data <JSON> <PRODUCT_ID>
+pc ship product-user update --data <JSON> <PRODUCT_ID> <USER_ID>
+pc ship product-user delete <PRODUCT_ID> <USER_ID>
+```
+
+### `ship ticket` — 工单（list / get / create / update / search）
+
+```bash
+pc ship ticket list [--product-id <ID>] [--type-id <ID>] [--state-id <ID>] \
+    [--priority-id <ID>] [--keywords <KEYWORDS>] [--include-public-image-token <FIELDS>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket get <TICKET_ID> [--include-public-image-token <FIELDS>] [--include-deleted]
+pc ship ticket create --data <JSON>
+pc ship ticket update --data <JSON> <TICKET_ID>
+pc ship ticket search --data <JSON>
+```
+
+### `ship ticket-channel` — 工单渠道（list-for-product）
+
+```bash
+pc ship ticket-channel list-for-product <ID>
+```
+
+### `ship ticket-priority` — 工单优先级（list / list-for-product / get）
+
+```bash
+pc ship ticket-priority list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-priority list-for-product <ID>
+pc ship ticket-priority get <PRIORITY_ID>
+```
+
+### `ship ticket-property` — 工单属性定义（list / list-for-product / get / create / update）
+
+```bash
+pc ship ticket-property list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-property list-for-product <ID>
+pc ship ticket-property get <PROPERTY_ID>
+pc ship ticket-property create --data <JSON>
+pc ship ticket-property update --data <JSON> <PROPERTY_ID>
+```
+
+### `ship ticket-property-plan` — 工单属性方案（list / get / add-property / list-properties / get-property / remove-property）
+
+```bash
+pc ship ticket-property-plan list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-property-plan get <PROPERTY_PLAN_ID>
+pc ship ticket-property-plan add-property --data <JSON> <PROPERTY_PLAN_ID>
+pc ship ticket-property-plan list-properties <PROPERTY_PLAN_ID>
+pc ship ticket-property-plan get-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+pc ship ticket-property-plan remove-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+```
+
+### `ship ticket-solution` — 工单解决方案（list / list-for-product / get）
+
+```bash
+pc ship ticket-solution list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-solution list-for-product <ID>
+pc ship ticket-solution get <TICKET_SOLUTION_ID>
+```
+
+### `ship ticket-state` — 工单状态（list / list-for-product / get / create / update）
+
+```bash
+pc ship ticket-state list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-state list-for-product <ID>
+pc ship ticket-state get <TICKET_STATE_ID>
+pc ship ticket-state create --data <JSON>
+pc ship ticket-state update --data <JSON> <TICKET_STATE_ID>
+```
+
+### `ship ticket-state-plan` — 工单状态方案与流转（list / get / add-state / list-states / get-state / remove-state / add-flow / list-flows / get-flow / remove-flow）
+
+```bash
+pc ship ticket-state-plan list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-state-plan get <STATE_PLAN_ID>
+pc ship ticket-state-plan add-state --data <JSON> <STATE_PLAN_ID>
+pc ship ticket-state-plan list-states <STATE_PLAN_ID>
+pc ship ticket-state-plan get-state <STATE_PLAN_ID> <STATE_ID>
+pc ship ticket-state-plan remove-state <STATE_PLAN_ID> <STATE_ID>
+pc ship ticket-state-plan add-flow --data <JSON> <STATE_PLAN_ID>
+pc ship ticket-state-plan list-flows <STATE_PLAN_ID>
+pc ship ticket-state-plan get-flow <STATE_PLAN_ID> <STATE_FLOW_ID>
+pc ship ticket-state-plan remove-flow <STATE_PLAN_ID> <STATE_FLOW_ID>
+```
+
+### `ship ticket-tag` — 工单标签（list-for-product）
+
+```bash
+pc ship ticket-tag list-for-product <ID>
+```
+
+### `ship ticket-transition` — 工单流转（list / get）
+
+```bash
+pc ship ticket-transition list <TICKET_ID>
+pc ship ticket-transition get <TICKET_ID> <TRANSITION_HISTORY_ID>
+```
+
+### `ship ticket-type` — 工单类型（list / list-for-product / get）
+
+```bash
+pc ship ticket-type list [--page-index <INDEX>] [--page-size <SIZE>]
+pc ship ticket-type list-for-product <ID>
+pc ship ticket-type get <TICKET_TYPE_ID>
+```