@super-coding/cli 0.2.2 → 0.2.3

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

@@ -0,0 +1,172 @@
+# testhub 命令速查（测试库 / 用例 / 计划 / 执行）
+
+testhub 是 PingCode 的**测试管理**模块。本文件是该模块的完整命令表，通用约定见 `reference.md`。
+
+## 层级与 ID 关系
+
+```
+library（测试库）
+├── library-member / library-suite（用例目录树）
+├── testcase（测试用例）
+│   └── testcase-state / testcase-type / testcase-important-level 按「测试库」维度配置
+├── testplan（测试计划）
+└── testrun（测试执行记录：某计划下某用例的一次执行）
+    └── testrun-status 按「测试库」维度配置
+```
+
+- 典型链路：`library list` → `library-suite list <LIBRARY_ID>` → `testcase list --library-id` →
+  `testplan create` → `testrun list --testplan-id` 看执行情况。
+- **状态字典按库查**：`testcase-state list-for-library --library-id <LID>`、
+  `testrun-status list-for-library --library-id <LID>`。不同库的 ID 不能混用。
+- `testcase list` 的 `--library-id` 是**可选**的：不传会跨库返回，容易误判「用例属于哪个库」，
+  拿不准时先确认库再查。
+- `testrun list` 用 `--testplan-id` / `--testcase-id` / `--suite-id` / `--status-id` 过滤，
+  **没有** `--library-id`；要按库筛就先从计划入手。
+- `testcase histories <ID>` / `testrun histories <ID>` / `testrun get-history <ID> <HISTORY_ID>`
+  是变更历史，只读。
+- `testrun plan-batch --data <JSON> <LIBRARY_ID> <TESTPLAN_ID>` 用于批量把执行记录并入计划。
+- 批量写（`bulk-create` / `bulk-update`）的请求体形态各接口不一致：**先用 1~2 条验证结构再放大**，
+  不要一次性把上百条推进去。
+
+## 命令表
+
+### `testhub library` — 测试库（list / get / create / update）
+
+```bash
+pc testhub library list [--scope-type <SCOPE>] [--scope-id <ID>] [--keywords <KEYWORDS>] \
+    [--member-type <TYPE>] [--member-id <ID>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>] [--include-deleted] [--include-archived]
+pc testhub library get <LIBRARY_ID> [--include-deleted] [--include-archived]
+pc testhub library create --data <JSON>
+pc testhub library update --data <JSON> <LIBRARY_ID>
+```
+
+### `testhub library-member` — 测试库成员（list / get / add / update / remove）
+
+```bash
+pc testhub library-member list <LIBRARY_ID>
+pc testhub library-member get <LIBRARY_ID> <MEMBER_ID>
+pc testhub library-member add --data <JSON> <LIBRARY_ID>
+pc testhub library-member update --data <JSON> <LIBRARY_ID> <MEMBER_ID>
+pc testhub library-member remove <LIBRARY_ID> <MEMBER_ID>
+```
+
+### `testhub library-suite` — 用例目录（list / get / create / update / remove）
+
+```bash
+pc testhub library-suite list <LIBRARY_ID> [--parent-id <PARENT>]
+pc testhub library-suite get <LIBRARY_ID> <SUITE_ID>
+pc testhub library-suite create --data <JSON> <LIBRARY_ID>
+pc testhub library-suite update --data <JSON> <LIBRARY_ID> <SUITE_ID>
+pc testhub library-suite remove <LIBRARY_ID> <SUITE_ID>
+```
+
+### `testhub testcase` — 测试用例（list / get / create / update / delete / search / bulk-create / bulk-update / histories）
+
+```bash
+pc testhub testcase list [--library-id <ID>] [--maintenance-id <ID>] [--state-id <ID>] \
+    [--important-level-id <ID>] [--tag-id <ID>] [--keywords <KEYWORDS>] \
+    [--include-public-image-token <FIELDS>] [--include-deleted]
+pc testhub testcase get <TESTCASE_ID> [--include-public-image-token <FIELDS>] \
+    [--include-deleted]
+pc testhub testcase create --data <JSON>
+pc testhub testcase update --data <JSON> <TESTCASE_ID>
+pc testhub testcase delete <TESTCASE_ID>
+pc testhub testcase search --data <JSON>
+pc testhub testcase bulk-create --data <JSON>
+pc testhub testcase bulk-update --data <JSON>
+pc testhub testcase histories <TESTCASE_ID>
+```
+
+### `testhub testcase-important-level` — 重要程度（list / get）
+
+```bash
+pc testhub testcase-important-level list
+pc testhub testcase-important-level get <IMPORTANT_LEVEL_ID>
+```
+
+### `testhub testcase-property` — 用例属性定义（list / list-for-library / get / create / update）
+
+```bash
+pc testhub testcase-property list
+pc testhub testcase-property list-for-library --library-id <ID>
+pc testhub testcase-property get <PROPERTY_ID>
+pc testhub testcase-property create --data <JSON>
+pc testhub testcase-property update --data <JSON> <PROPERTY_ID>
+```
+
+### `testhub testcase-property-plan` — 用例属性方案（list / get / list-properties / get-property / add-property / remove-property）
+
+```bash
+pc testhub testcase-property-plan list [--library-id <ID>]
+pc testhub testcase-property-plan get <PROPERTY_PLAN_ID>
+pc testhub testcase-property-plan list-properties <PROPERTY_PLAN_ID>
+pc testhub testcase-property-plan get-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+pc testhub testcase-property-plan add-property --data <JSON> <PROPERTY_PLAN_ID>
+pc testhub testcase-property-plan remove-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+```
+
+### `testhub testcase-state` — 用例状态（list / list-for-library / get）
+
+```bash
+pc testhub testcase-state list
+pc testhub testcase-state list-for-library --library-id <ID>
+pc testhub testcase-state get <STATE_ID>
+```
+
+### `testhub testcase-type` — 用例类型（list / list-for-library / get）
+
+```bash
+pc testhub testcase-type list
+pc testhub testcase-type list-for-library --library-id <ID>
+pc testhub testcase-type get <TYPE_ID>
+```
+
+### `testhub testplan` — 测试计划（list / get / create / update）
+
+```bash
+pc testhub testplan list <LIBRARY_ID> [--name <NAME>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>]
+pc testhub testplan get <LIBRARY_ID> <TESTPLAN_ID> [--include-deleted]
+pc testhub testplan create --data <JSON> <LIBRARY_ID>
+pc testhub testplan update --data <JSON> <LIBRARY_ID> <TESTPLAN_ID>
+```
+
+### `testhub testplan-state` — 计划状态（list / get）
+
+```bash
+pc testhub testplan-state list
+pc testhub testplan-state get <STATE_ID>
+```
+
+### `testhub testplan-type` — 计划类型（list / get）
+
+```bash
+pc testhub testplan-type list <LIBRARY_ID>
+pc testhub testplan-type get <LIBRARY_ID> <TESTPLAN_TYPE_ID>
+```
+
+### `testhub testrun` — 测试执行（list / get / create / update / replace / search / bulk-create / bulk-update / histories / get-history / plan-batch）
+
+```bash
+pc testhub testrun list [--testplan-id <ID>] [--testcase-id <ID>] [--suite-id <ID>] \
+    [--status-id <ID>] [--keywords <KEYWORDS>]
+pc testhub testrun get <TESTRUN_ID> [--include-deleted]
+pc testhub testrun create --data <JSON>
+pc testhub testrun update --data <JSON> <TESTRUN_ID>
+pc testhub testrun replace --data <JSON> <TESTRUN_ID>
+pc testhub testrun search --data <JSON>
+pc testhub testrun bulk-create --data <JSON>
+pc testhub testrun bulk-update --data <JSON>
+pc testhub testrun histories <TESTRUN_ID>
+pc testhub testrun get-history <TESTRUN_ID> <HISTORY_ID>
+pc testhub testrun plan-batch --data <JSON> <LIBRARY_ID> <TESTPLAN_ID>
+```
+
+### `testhub testrun-status` — 执行状态（list / list-for-library / get）
+
+```bash
+pc testhub testrun-status list
+pc testhub testrun-status list-for-library --library-id <ID>
+pc testhub testrun-status get <STATUS_ID>
+```

package/dist/pingcode/builtin/reference.md

@@ -1,80 +1,367 @@
-# pc 速查（PingCode Open API CLI）
+# pc 命令速查（PingCode Open API）
 
-本文件随 Super Coding 版本分发，**只读**：运行时的经验不要回写到这里（升级会覆盖）。
-所有参数形态均取自 `pc` 1.2.x 的实际 clap 定义，不是猜的。
+本目录是 `pc` 的**完整**命令参考，覆盖 18 个模块、约 500 条子命令，均取自 `pc` 1.2.x 的实际 clap 定义。
+**不要运行 `pc --help` / `pc <...> -h`**（上游会把凭据当默认值打印），查这里。
 
-## 通用约定
+| 要找什么 | 看哪个文件 |
+|---|---|
+| 项目、工作项、迭代、发布、看板 | **本文件** `reference.md` |
+| 产品、需求（idea）、工单（ticket） | `reference-ship.md` |
+| 测试库、用例、计划、执行 | `reference-testhub.md` |
+| 部门 / 团队 / 成员 / 角色 / 知识库页面 | `reference-org-wiki.md` |
+| 评论、附件、参与人、关联、活动、评审、自定义属性、工时、权限、日志 | `reference-cross.md` |
+
+## 通用约定（所有模块一致）
 
 - 输出：结果一律 pretty JSON 到 **stdout**；`-v` 把每个 HTTP 请求/响应打到 **stderr**（已脱敏）。
 - 写操作的请求体：`--data '<JSON>'`、`--data @/tmp/body.json`、`--data @-`（stdin）。
   必须是 JSON **object**，不是数组。
 - 分页响应：`{ page_index, page_size, total, values[] }`，`page_index` **从 0 开始**。
-- 全局参数（`--dry-run`、`-v`）放在子命令前后都行。
+- 全局参数（`--dry-run`、`-v`）放在子命令前后都行。`--dry-run` 只打印请求，不发网络、不校验凭据。
+- 列表类命令的 `--page-index` / `--page-size` **不是都有**：本文件每条命令都按真实定义列出，没写就是没有。
+- `--include-public-image-token <FIELDS>` 用于让富文本字段里的图片带可访问 token，多个字段用逗号分隔。
+- `--include-deleted` / `--include-archived` 只在支持的命令上有，别套用到所有列表。
+
+## 命令全景（不知道用哪个模块时先看这张表）
+
+| 模块 | 管什么 | 常用入口 |
+|---|---|---|
+| `pjm` | 项目、工作项、迭代、发布、看板、字典 | `workitem get/list/search`、`project list`、`sprint list` |
+| `ship` | 产品、需求（idea）、工单（ticket）、客户 | `idea get/list`、`ticket get/list`、`product list` |
+| `testhub` | 测试库、用例、测试计划、执行记录 | `testcase get/list`、`testplan list`、`testrun list` |
+| `wiki` | 知识空间与页面（含正文、版本） | `page get`、`page get-content` |
+| `organization` | 企业信息、成员、部门、团队、角色、职位 | `user list` |
+| `comments` | 各类对象的评论 | `comments list/create` |
+| `attachments` | 附件（文件 / 代码片段） | `upload-file`、`list` |
+| `participants` | 参与人（关注者） | `list/add/remove` |
+| `relations` | 跨模块关联关系 | `list/create` |
+| `activities` | 操作历史（只读） | `list` |
+| `reviews` | 评审及其被评审对象 | `list/create` |
+| `entity-properties` | 实体的自定义键值属性 | `list/create` |
+| `workload` / `workload-type` | 工时记录与工时类型 | `workload list/create` |
+| `permission` | 权限点与我的权限 | `my-principal`、`check-*` |
+| `security` | 登录日志、审计日志 | `login-log list`、`audit-log list` |
+| `expression` | 表达式语法解析与求值 | `analyse`、`evaluate` |
+| `doctor` | 配置与连通性自检 | `pc doctor` |
 
 ## 项目与工作项（pjm）
 
-| 目的 | 命令 |
-|---|---|
-| 按名称找项目 | `pc pjm project list --keywords "项目名"` → `values[].id`（支持 `--page-index` / `--page-size`） |
-| 项目详情 | `pc pjm project get <PROJECT_ID>`（必须是 24 位 ID；传 `identifier` 如 `SUPER` 会 404 `100002`） |
-| 工作项详情 | `pc pjm workitem get <WORKITEM_ID\|SHORT_ID>`（**位置参数**；接受 24 位 ID，或 8 位 `short_id`（如 `67jL99pN`，= `html_url` 末段）。**不接受** `DEMO-1` 这类 identifier，会报 `100317`） |
-| 工作项列表 | `pc pjm workitem list --project-id <PID> [--parent-id <ID>] [--type-id story] [--assignee-id <UID>] [--state-id <SID>] [--sprint-id <SPID>] [--identifier DEMO-19] [--keywords <关键词>] [--include-archived]` |
-| 工作项搜索 | `pc pjm workitem search --data '{"mode":"query","payload":{"filter":{...}}}'` |
-| 创建工作项 | `pc pjm workitem create --data '{"project_id":"<PID>","type_id":"story","title":"标题"}'` |
-| 更新工作项 | `pc pjm workitem update <WORKITEM_ID> --data '{"state_id":"<SID>"}'`（`title`/`description`/`assignee_id`/`sprint_id`/`priority_id`/`story_points`/`properties` 等可选） |
-| 删除工作项 | `pc pjm workitem delete <WORKITEM_ID>` |
-| 工作项状态字典 | `pc pjm workitem-state list-for-project --project-id <PID> --workitem-type-id <TID>` |
-| 工作项类型字典 | `pc pjm workitem-type list-for-project --project-id <PID>` |
-
-> `pjm workitem list` **没有** `--page-index` / `--page-size`。要全量或翻页，只能用 `workitem search`，
-> 分页/条件写在请求体的 `payload` 里。`workitem create` 的 `type_id` 可直接用系统枚举
-> （`story` / `bug` / `task` / `epic` / `feature` / `phase` / `milestone` / `requirement` / `issue`）。
-
-## 评论（comments）
-
-| 目的 | 命令 |
-|---|---|
-| 列评论 | `pc comments list --principal-type workitem --principal-id <ID> [--page-index 0 --page-size 50]` |
-| 发评论 | `pc comments create --data '{"principal_type":"workitem","principal_id":"<ID>","content":"内容"}'` |
-| 读单条 | `pc comments get <COMMENT_ID> --principal-type workitem --principal-id <ID>` |
+### `pjm board` — 看板（list / get / create / update / delete）
 
-`--principal-type` 取值：`workitem` / `workitem-review` / `testrun` / `testcase` /
-`testcase-review` / `idea` / `idea-review` / `ticket` / `page`。
+```bash
+pc pjm board list <PROJECT_ID>
+pc pjm board get <PROJECT_ID> <BOARD_ID>
+pc pjm board create --data <JSON> <PROJECT_ID>
+pc pjm board update --data <JSON> <PROJECT_ID> <BOARD_ID>
+pc pjm board delete <PROJECT_ID> <BOARD_ID>
+```
 
-## 知识库（wiki）
+### `pjm board-entry` — 看板卡片（list / get / create / update / delete）
 
-| 目的 | 命令 |
-|---|---|
-| 找空间 | `pc wiki space list --keywords "空间名"` |
-| 列页面 | `pc wiki page list --space-id <SID> [--page-index 0 --page-size 50]` |
-| 页面详情 | `pc wiki page get <PAGE_ID>`（**位置参数**） |
-| 页面正文 | `pc wiki page get-content <PAGE_ID> --format-type markdown`（`text` / `markdown` / `html` / `block`） |
+```bash
+pc pjm board-entry list <PROJECT_ID> <BOARD_ID>
+pc pjm board-entry get <PROJECT_ID> <BOARD_ID> <ENTRY_ID>
+pc pjm board-entry create --data <JSON> <PROJECT_ID> <BOARD_ID>
+pc pjm board-entry update --data <JSON> <PROJECT_ID> <BOARD_ID> <ENTRY_ID>
+pc pjm board-entry delete <PROJECT_ID> <BOARD_ID> <ENTRY_ID>
+```
 
-## 组织（organization）
+### `pjm board-swimlane` — 看板泳道（list / get / create / update / delete）
 
-| 目的 | 命令 |
-|---|---|
-| 找人 | `pc organization user list --keywords "姓名"`（也可 `--name` / `--emails` / `--mobiles`） |
-| 部门 / 团队 / 角色 | `pc organization department list`、`pc organization group list`、`pc organization role list` |
+```bash
+pc pjm board-swimlane list <PROJECT_ID> <BOARD_ID>
+pc pjm board-swimlane get <PROJECT_ID> <BOARD_ID> <SWIMLANE_ID>
+pc pjm board-swimlane create --data <JSON> <PROJECT_ID> <BOARD_ID>
+pc pjm board-swimlane update --data <JSON> <PROJECT_ID> <BOARD_ID> <SWIMLANE_ID>
+pc pjm board-swimlane delete <PROJECT_ID> <BOARD_ID> <SWIMLANE_ID>
+```
+
+### `pjm deliverable` — 交付物目标（list / get / create / update / delete）
+
+```bash
+pc pjm deliverable list [--project-id <ID>] [--workitem-id <ID>]
+pc pjm deliverable get <DELIVERABLE_TARGET_ID>
+pc pjm deliverable create --data <JSON>
+pc pjm deliverable update --data <JSON> <DELIVERABLE_TARGET_ID>
+pc pjm deliverable delete <DELIVERABLE_TARGET_ID>
+```
+
+### `pjm project` — 项目（list / get / create / update / clone / enable-local-config / progress）
+
+```bash
+pc pjm project list [--scope-type <SCOPE_TYPE>] [--scope-id <ID>] [--keywords <KEYWORDS>] \
+    [--member-type <TYPE>] [--member-id <ID>] [--type <TYPE>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>] [--include-deleted] [--include-archived] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc pjm project get <PROJECT_ID> [--include-deleted] [--include-archived]
+pc pjm project create --data <JSON>
+pc pjm project update --data <JSON> <PROJECT_ID>
+pc pjm project clone --data <JSON> <PROJECT_ID>
+pc pjm project enable-local-config <PROJECT_ID>
+pc pjm project progress <PROJECT_ID>
+```
+
+### `pjm project-member` — 项目成员（list / get / add / update / remove）
+
+```bash
+pc pjm project-member list <PROJECT_ID>
+pc pjm project-member get <PROJECT_ID> <MEMBER_ID>
+pc pjm project-member add --data <JSON> <PROJECT_ID>
+pc pjm project-member update --data <JSON> <PROJECT_ID> <MEMBER_ID>
+pc pjm project-member remove <PROJECT_ID> <MEMBER_ID>
+```
+
+### `pjm project-process` — 项目流程（list / get）
+
+```bash
+pc pjm project-process list
+pc pjm project-process get <PROCESS_ID>
+```
+
+### `pjm project-property` — 项目属性定义（list / get / create / update / list-for-project / get-in-project / add-to-project / remove-from-project）
+
+```bash
+pc pjm project-property list
+pc pjm project-property get <PROPERTY_ID>
+pc pjm project-property create --data <JSON>
+pc pjm project-property update --data <JSON> <PROPERTY_ID>
+pc pjm project-property list-for-project <PROJECT_ID>
+pc pjm project-property get-in-project <PROJECT_ID> <PROPERTY_ID>
+pc pjm project-property add-to-project --data <JSON> <PROJECT_ID>
+pc pjm project-property remove-from-project <PROJECT_ID> <PROPERTY_ID>
+```
+
+### `pjm project-state` — 项目状态（list / get）
+
+```bash
+pc pjm project-state list --project-id <ID>
+pc pjm project-state get <STATE_ID>
+```
+
+### `pjm release` — 发布（list / get / create / update / delete / bulk-create）
+
+```bash
+pc pjm release list <PROJECT_ID> [--name <NAME>] [--status <STATUS>] \
+    [--created-between <RANGE>] [--updated-between <RANGE>]
+pc pjm release get <PROJECT_ID> <RELEASE_ID>
+pc pjm release create --data <JSON> <PROJECT_ID>
+pc pjm release update --data <JSON> <PROJECT_ID> <RELEASE_ID>
+pc pjm release delete <PROJECT_ID> <RELEASE_ID>
+pc pjm release bulk-create --data <JSON>
+```
+
+### `pjm release-category` — 发布分类（list / get / create / update / delete）
+
+```bash
+pc pjm release-category list <PROJECT_ID>
+pc pjm release-category get <PROJECT_ID> <RELEASE_CATEGORY_ID>
+pc pjm release-category create --data <JSON> <PROJECT_ID>
+pc pjm release-category update --data <JSON> <PROJECT_ID> <RELEASE_CATEGORY_ID>
+pc pjm release-category delete <PROJECT_ID> <RELEASE_CATEGORY_ID>
+```
+
+### `pjm release-section` — 发布分组（list / get / create / update / delete）
+
+```bash
+pc pjm release-section list <PROJECT_ID>
+pc pjm release-section get <PROJECT_ID> <RELEASE_SECTION_ID>
+pc pjm release-section create --data <JSON> <PROJECT_ID>
+pc pjm release-section update --data <JSON> <PROJECT_ID> <RELEASE_SECTION_ID>
+pc pjm release-section delete <PROJECT_ID> <RELEASE_SECTION_ID>
+```
+
+### `pjm release-stage` — 发布阶段（list / get / create / update / delete）
+
+```bash
+pc pjm release-stage list
+pc pjm release-stage get <RELEASE_STAGE_ID>
+pc pjm release-stage create --data <JSON>
+pc pjm release-stage update --data <JSON> <RELEASE_STAGE_ID>
+pc pjm release-stage delete <RELEASE_STAGE_ID> [--data <JSON>]
+```
+
+### `pjm sprint` — 迭代（list / get / create / update / bulk-create）
+
+```bash
+pc pjm sprint list <PROJECT_ID> [--name <NAME>] [--status <STATUS>] \
+    [--created-between <RANGE>] [--updated-between <RANGE>]
+pc pjm sprint get <PROJECT_ID> <SPRINT_ID>
+pc pjm sprint create --data <JSON> <PROJECT_ID>
+pc pjm sprint update --data <JSON> <PROJECT_ID> <SPRINT_ID>
+pc pjm sprint bulk-create --data <JSON>
+```
+
+### `pjm sprint-category` — 迭代分类（list / get / create / update / delete）
+
+```bash
+pc pjm sprint-category list <PROJECT_ID>
+pc pjm sprint-category get <PROJECT_ID> <SPRINT_CATEGORY_ID>
+pc pjm sprint-category create --data <JSON> <PROJECT_ID>
+pc pjm sprint-category update --data <JSON> <PROJECT_ID> <SPRINT_CATEGORY_ID>
+pc pjm sprint-category delete <PROJECT_ID> <SPRINT_CATEGORY_ID>
+```
+
+### `pjm sprint-section` — 迭代分组（list / get / create / update / delete）
+
+```bash
+pc pjm sprint-section list <PROJECT_ID>
+pc pjm sprint-section get <PROJECT_ID> <SECTION_ID>
+pc pjm sprint-section create --data <JSON> <PROJECT_ID>
+pc pjm sprint-section update --data <JSON> <PROJECT_ID> <SECTION_ID>
+pc pjm sprint-section delete <PROJECT_ID> <SECTION_ID>
+```
+
+### `pjm workitem` — 工作项（需求 / 任务 / 缺陷 / 子任务…）（list / get / create / update / delete / search / batch-update / add-tag / get-tag / remove-tag）
+
+```bash
+pc pjm workitem list [--identifier <IDENTIFIER>] [--project-id <ID>] [--type-id <ID>] \
+    [--parent-id <ID>] [--assignee-id <ID>] [--state-id <ID>] [--priority-id <ID>] \
+    [--bug-type-id <ID>] [--tag-id <ID>] [--sprint-id <ID>] [--board-id <ID>] \
+    [--entry-id <ID>] [--swimlane-id <ID>] [--phase-id <ID>] [--release-id <ID>] \
+    [--created-by <ID>] [--participant-id <ID>] [--keywords <KEYWORDS>] \
+    [--include-public-image-token <FIELDS>] [--include-deleted] [--include-archived]
+pc pjm workitem get <WORKITEM_ID> [--include-public-image-token <FIELDS>] \
+    [--include-deleted] [--include-archived]
+pc pjm workitem create --data <JSON>
+pc pjm workitem update --data <JSON> <WORKITEM_ID>
+pc pjm workitem delete <WORKITEM_ID>
+pc pjm workitem search --data <JSON>
+pc pjm workitem batch-update --data <JSON>
+pc pjm workitem add-tag --data <JSON> <WORKITEM_ID>
+pc pjm workitem get-tag <WORKITEM_ID> <TAG_ID>
+pc pjm workitem remove-tag <WORKITEM_ID> <TAG_ID>
+```
+
+### `pjm workitem-priority` — 优先级字典（list / list-for-project / get）
+
+```bash
+pc pjm workitem-priority list
+pc pjm workitem-priority list-for-project --project-id <ID>
+pc pjm workitem-priority get <PRIORITY_ID>
+```
+
+### `pjm workitem-property` — 工作项属性定义（list / list-for-project / get / create / update）
+
+```bash
+pc pjm workitem-property list
+pc pjm workitem-property list-for-project --project-id <ID> --workitem-type-id <ID>
+pc pjm workitem-property get <PROPERTY_ID>
+pc pjm workitem-property create --data <JSON>
+pc pjm workitem-property update --data <JSON> <PROPERTY_ID>
+```
+
+### `pjm workitem-property-plan` — 属性方案（list / get / add-property / list-properties / get-property / remove-property）
+
+```bash
+pc pjm workitem-property-plan list
+pc pjm workitem-property-plan get <PROPERTY_PLAN_ID>
+pc pjm workitem-property-plan add-property --data <JSON> <PROPERTY_PLAN_ID>
+pc pjm workitem-property-plan list-properties <PROPERTY_PLAN_ID>
+pc pjm workitem-property-plan get-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+pc pjm workitem-property-plan remove-property <PROPERTY_PLAN_ID> <PROPERTY_ID>
+```
+
+### `pjm workitem-relation` — 工作项关联（list / get / create / delete）
+
+```bash
+pc pjm workitem-relation list <WORKITEM_ID> [--relation-type <TYPE>]
+pc pjm workitem-relation get <WORKITEM_ID> <RELATION_ID> [--include-deleted]
+pc pjm workitem-relation create --data <JSON> <WORKITEM_ID>
+pc pjm workitem-relation delete <WORKITEM_ID> <RELATION_ID>
+```
 
-## 自检
+### `pjm workitem-relation-type` — 关联类型字典（list / get）
 
-`pc doctor` 输出结构化 JSON：`ok`、`summary`、`checks[]`（每项有稳定 `id` 与
-`status` = pass/fail/warn/info/skipped）。只看 `ok` 和 `status=fail` 的项，
-**不要复述任何凭据相关字段**。退出码：0 全通过 / 1 有检查失败 / 2 命令自身异常。
+```bash
+pc pjm workitem-relation-type list
+pc pjm workitem-relation-type get <RELATION_TYPE_ID>
+```
+
+### `pjm workitem-state` — 状态字典（list-all / list-for-project / get / create / update）
+
+```bash
+pc pjm workitem-state list-all
+pc pjm workitem-state list-for-project --project-id <ID> --workitem-type-id <ID>
+pc pjm workitem-state get <STATE_ID>
+pc pjm workitem-state create --data <JSON>
+pc pjm workitem-state update --data <JSON> <STATE_ID>
+```
 
-## ID 从哪来（实测：三种 ID 别混用）
+### `pjm workitem-state-plan` — 状态方案与流转（list / get / add-state / list-states / get-state / remove-state / add-flow / list-flows / get-flow / remove-flow）
+
+```bash
+pc pjm workitem-state-plan list
+pc pjm workitem-state-plan get <STATE_PLAN_ID>
+pc pjm workitem-state-plan add-state --data <JSON> <STATE_PLAN_ID>
+pc pjm workitem-state-plan list-states <STATE_PLAN_ID>
+pc pjm workitem-state-plan get-state <STATE_PLAN_ID> <STATE_ID>
+pc pjm workitem-state-plan remove-state <STATE_PLAN_ID> <STATE_ID>
+pc pjm workitem-state-plan add-flow --data <JSON> <STATE_PLAN_ID>
+pc pjm workitem-state-plan list-flows <STATE_PLAN_ID>
+pc pjm workitem-state-plan get-flow <STATE_PLAN_ID> <FLOW_ID>
+pc pjm workitem-state-plan remove-flow <STATE_PLAN_ID> <FLOW_ID>
+```
+
+### `pjm workitem-tag` — 标签字典（create / list / list-for-project / get / update / delete）
+
+```bash
+pc pjm workitem-tag create --data <JSON>
+pc pjm workitem-tag list [--name <NAME>]
+pc pjm workitem-tag list-for-project --project-id <ID> [--name <NAME>]
+pc pjm workitem-tag get <TAG_ID>
+pc pjm workitem-tag update --data <JSON> <TAG_ID>
+pc pjm workitem-tag delete <TAG_ID>
+```
+
+### `pjm workitem-transition` — 流转规则（list / get）
+
+```bash
+pc pjm workitem-transition list <WORKITEM_ID>
+pc pjm workitem-transition get <WORKITEM_ID> <TRANSITION_HISTORY_ID>
+```
+
+### `pjm workitem-type` — 类型字典（list / list-for-project / get / create / update / delete）
+
+```bash
+pc pjm workitem-type list
+pc pjm workitem-type list-for-project --project-id <ID>
+pc pjm workitem-type get <WORKITEM_TYPE_ID>
+pc pjm workitem-type create --data <JSON>
+pc pjm workitem-type update --data <JSON> <WORKITEM_TYPE_ID>
+pc pjm workitem-type delete <WORKITEM_TYPE_ID>
+```
+
+### `pjm workitem-type-plan` — 类型方案（list / get / add-type / list-types / get-type / update-type / remove-type）
+
+```bash
+pc pjm workitem-type-plan list [--project-id <ID>]
+pc pjm workitem-type-plan get <TYPE_PLAN_ID>
+pc pjm workitem-type-plan add-type --data <JSON> <TYPE_PLAN_ID>
+pc pjm workitem-type-plan list-types <TYPE_PLAN_ID>
+pc pjm workitem-type-plan get-type <TYPE_PLAN_ID> <WORKITEM_TYPE_ID>
+pc pjm workitem-type-plan update-type --data <JSON> <TYPE_PLAN_ID> <WORKITEM_TYPE_ID>
+pc pjm workitem-type-plan remove-type <TYPE_PLAN_ID> <WORKITEM_TYPE_ID>
+```
+## 分页（最容易踩的坑）
+
+- **`pjm workitem list` 没有 `--page-index` / `--page-size`**（上游只给了一部分列表命令加分页）。
+  要翻页或全量拉取，改用 `pc pjm workitem search --data`，条件与分页写在请求体的 `payload` 里。
+- 其它列表命令若上面命令块里写了这两个参数，才可以用。
+- 拿到 `total` 大于本页条数时，**必须**继续翻页，不要只报第一页就下结论。
+
+## ID 从哪来（三种 ID 别混用）
 
 `get / update / delete` 只认 **24 位十六进制 ID** 或 **8 位 `short_id`**。人类可读的 `SUPER-1` 是 `identifier`，
 单独喂给 `get` 会 `100317`，只能先用 `list --identifier` 反查出 ID：
 
 | 需要 | 先跑 | 取字段 |
 |---|---|---|
-| 项目 ID | `pc pjm project list` | `values[].id` |
-| 工作项 ID | `pc pjm workitem list --project-id <PID>` 或 `pc pjm workitem search ...` | `values[].id` / `values[].short_id` |
+| 项目 ID | `pc pjm project list --keywords "项目名"` | `values[].id` |
+| 工作项 ID | `pc pjm workitem list --project-id <PID>` 或 `workitem search` | `values[].id` / `values[].short_id` |
 | identifier → ID | `pc pjm workitem list --identifier DEMO-19` | `values[0].id` |
 | 子工作项 | `pc pjm workitem list --parent-id <ID>` | `values[]`（无分页参数） |
 | 状态 ID | `pc pjm workitem-state list-for-project --project-id <PID> --workitem-type-id story` | `values[].id` |
+| 类型 ID | `pc pjm workitem-type list-for-project --project-id <PID>` | `values[].id` |
 | 用户 ID | `pc organization user list --keywords "姓名"` | `values[].id` |
 
 ### 手上只有一个工作项 ID 时
@@ -93,6 +380,15 @@ pc pjm workitem get 6aa222c6ae6822749a6e6908   # 直接拿全量
 **子工作项** → `pc pjm workitem list --parent-id <ID>`；**描述里的图片地址** → 加
 `--include-public-image-token description`。
 
+## 写操作的常见坑
+
+- `workitem create` 的 `type_id` 可直接用系统枚举：`story` / `bug` / `task` / `epic` / `feature` /
+  `phase` / `milestone` / `requirement` / `issue`，不必先查字典。
+- `workitem search` 的 body 必须是 `{"mode":"query","payload":{...}}`，少 `mode` 会 `100008`。
+- `workitem update` 是**部分更新**：只传要改的字段即可，别把 `get` 的结果整个回传。
+- `workitem batch-update` 是「把多个工作项的同一个属性改成同一个值」，不是逐条不同值。
+- 删除类命令（`delete`、`remove-tag` 等）**不可撤销**；确认 ID 再执行。
+
 ## 常见错误码
 
 | HTTP / code | 含义 | 处理 |
@@ -102,6 +398,8 @@ pc pjm workitem get 6aa222c6ae6822749a6e6908   # 直接拿全量
 | 400 `100043` | 不支持该过滤条件 | 例如 `search` 的 `filter.parent_ids`。找子工作项改用 `list --parent-id` |
 | 403 `100035` | 当前令牌不适用于此资源 | `client_credentials` 换的是**企业令牌**，不代表具体用户（`/v1/myself` 必然 403）；改查业务资源，或改用用户令牌 |
 | 404 `100002` | 资源路径错误 | 用了 `identifier` 而不是 ID |
+| 404 `100300` | 项目资源不存在 | 项目可能已归档，见下方「字段陷阱」 |
+| 429 | 限流 | 退避几秒后重试一次，仍失败则停下说明 |
 
 ## 字段陷阱
 
@@ -121,3 +419,6 @@ pc pjm workitem get 6aa222c6ae6822749a6e6908   # 直接拿全量
 - 单个资源是**裸对象**（直接取 `.id`）；列表才有 `values[]` 包装。
 - 工作项的富文本字段（`description`）可能含图片 token；需要图片地址时加
   `--include-public-image-token description`。
+- `pc doctor` 输出结构化 JSON：`ok`、`summary`、`checks[]`（每项有稳定 `id` 与
+  `status` = pass/fail/warn/info/skipped）。只看 `ok` 和 `status=fail` 的项，
+  **不要复述任何凭据相关字段**。退出码：0 全通过 / 1 有检查失败 / 2 命令自身异常。

package/dist/pingcode/cli.js

@@ -7,9 +7,10 @@ import { resetTokenCache, resolveToken } from "./token.js";
 /** 不可用原因 → 可直接照做的修复步骤 */
 const REASON_HINT = {
     binary_missing: [
-        "未找到 pc（PingCode CLI）。安装其一后重试：",
+        "未找到 pc（PingCode CLI）。它随 @super-coding/cli 分发，缺失说明安装包不完整：",
+        "  重装或升级：npm i -g @super-coding/cli@latest",
+        "内置版本覆盖 macOS(Apple Silicon) 与 Linux(x64)；其它平台（Intel Mac / Windows）需自行安装：",
         "  brew tap shaunxu/tap && brew install pc",
-        "  curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shaunxu/pingcode-cli-next/releases/latest/download/pc-installer.sh | sh",
         "装在自定义路径时，用 SC_PC_BINARY=/abs/path/pc 指定。",
     ],
     no_credentials: [
@@ -47,14 +48,24 @@ function effectiveCredential(status, inspected) {
     }
     return undefined;
 }
+/** 二进制来源：内置的那份版本与参考文档一一对应，用户自己装的可能对不上 */
+const BINARY_SOURCE_LABEL = {
+    bundled: "随 CLI 分发",
+    system: "系统 PATH",
+    override: "SC_PC_BINARY 指定",
+};
 function printStatusBody(status, inspected = inspectPingcodeConfig()) {
     console.log("PingCode 集成（pc）");
     console.log(`  状态：${status.available ? "可用" : "不可用"}`);
     if (status.reason === "disabled") {
         console.log("  pc 二进制：（SC_PINGCODE=off，已跳过探测）");
     }
+    else if (status.binary) {
+        const source = BINARY_SOURCE_LABEL[status.binary.source] ?? status.binary.source;
+        console.log(`  pc 二进制：${status.binary.path}（${status.binary.version}，${source}）`);
+    }
     else {
-        console.log(`  pc 二进制：${status.binary ? `${status.binary.path}（${status.binary.version}）` : "未找到"}`);
+        console.log("  pc 二进制：未找到");
     }
     console.log(`  凭据来源：${credentialLabel(effectiveCredential(status, inspected))}`);
     if (inspected.state === "ok") {