@super-coding/cli 0.2.2 → 0.2.4

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") {

package/dist/pingcode/detect.js

@@ -1,10 +1,15 @@
-// 探测设备上是否装了 `pc`（PingCode Open API CLI）。
+// 定位 `pc`（PingCode Open API CLI）二进制。
+//
+// 优先级：SC_PC_BINARY（显式指定）> 包内自带的预编译二进制 > PATH。
+// 包内优先于 PATH 是刻意的：内嵌那份的版本与 skill 文档里写的命令一一对应，
+// 用户机器上装的旧版 `pc` 反而会让参考文档和实际行为对不上。
 //
 // 找不到就安静降级：集成是「有则增强」，不是 daemon 的启动前提。
 // 版本探针刻意剥掉 PC_* 环境变量——即便 `--version` 不该读凭据，也不给它接触凭据的机会。
 import { execFile } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, chmodSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
 const BIN_NAME = "pc";
 /** Windows 上 `pc` 可能是 exe/cmd/bat；POSIX 只有同名可执行文件 */
 function candidateNames() {
@@ -21,11 +26,51 @@ function isExecutable(path) {
         return false;
     }
 }
-/** SC_PC_BINARY 可显式指定（自定义安装路径 / 测试注入）；否则按 PATH 顺序找第一个。 */
-export function findPingcodeBinary(env = process.env) {
-    const override = env["SC_PC_BINARY"]?.trim();
-    if (override)
-        return isExecutable(override) ? override : null;
+/**
+ * npm 打包/解包会丢掉执行位，这里兜底补回来（只对自己包内的文件动手）。
+ * 补不上就当不可用，交给下一级回退，不要在这里抛。
+ */
+function ensureExecutable(path) {
+    if (isExecutable(path))
+        return true;
+    if (process.platform === "win32")
+        return false;
+    try {
+        chmodSync(path, 0o755);
+        return isExecutable(path);
+    }
+    catch {
+        return false;
+    }
+}
+/** 上游 release 的资产命名：darwin-arm64 / linux-x64 / win32-x64 */
+export function bundledBinaryName(platform = process.platform, arch = process.arch) {
+    const ext = platform === "win32" ? ".exe" : "";
+    return `pc-${platform}-${arch}${ext}`;
+}
+/**
+ * 包内二进制的候选路径。
+ * - 装好后跑：dist/pingcode/detect.js → dist/bin/
+ * - 用 tsx 跑源码：src/pingcode/detect.ts → 需要多上两级到 dist/bin/
+ * `extraDirs` 供测试注入，避免让用例依赖构建产物是否存在。
+ */
+function bundledCandidates(name, extraDirs = []) {
+    const moduleDir = fileURLToPath(new URL(".", import.meta.url));
+    return [
+        ...extraDirs.map((dir) => join(dir, name)),
+        join(moduleDir, "..", "bin", name),
+        join(moduleDir, "..", "..", "dist", "bin", name),
+    ];
+}
+export function bundledPingcodeBinary(platform = process.platform, arch = process.arch, extraDirs = []) {
+    const name = bundledBinaryName(platform, arch);
+    for (const candidate of bundledCandidates(name, extraDirs)) {
+        if (ensureExecutable(candidate))
+            return candidate;
+    }
+    return null;
+}
+function findOnPath(env) {
     for (const dir of (env["PATH"] ?? "").split(delimiter)) {
         if (!dir)
             continue;
@@ -37,6 +82,21 @@ export function findPingcodeBinary(env = process.env) {
     }
     return null;
 }
+/** SC_PC_BINARY 可显式指定（自定义安装路径 / 测试注入）> 包内 > PATH */
+export function locatePingcodeBinary(env = process.env, platform = process.platform, arch = process.arch, extraBundledDirs = []) {
+    const override = env["SC_PC_BINARY"]?.trim();
+    if (override)
+        return isExecutable(override) ? { path: override, source: "override" } : null;
+    const bundled = bundledPingcodeBinary(platform, arch, extraBundledDirs);
+    if (bundled)
+        return { path: bundled, source: "bundled" };
+    const onPath = findOnPath(env);
+    return onPath ? { path: onPath, source: "system" } : null;
+}
+/** 只要路径的老接口（测试与外部调用用） */
+export function findPingcodeBinary(env = process.env) {
+    return locatePingcodeBinary(env)?.path ?? null;
+}
 /** 探针环境：剥掉 PingCode 凭据，避免任何输出把密钥带出来 */
 function probeEnv(env) {
     const next = { ...env };
@@ -58,12 +118,12 @@ export function probeVersion(path, env = process.env) {
 /** 探测并缓存结果（daemon 生命周期内二进制位置不会变） */
 let cached;
 export async function detectPingcodeBinary(env = process.env) {
-    const path = findPingcodeBinary(env);
-    const key = `${path ?? "(none)"}:${env["SC_PC_BINARY"] ?? ""}`;
+    const found = locatePingcodeBinary(env);
+    const key = `${found?.path ?? "(none)"}:${found?.source ?? ""}:${env["SC_PC_BINARY"] ?? ""}`;
     if (cached?.key === key)
         return cached.value;
-    const version = path ? await probeVersion(path, env) : null;
-    const value = path && version ? { path, version } : null;
+    const version = found ? await probeVersion(found.path, env) : null;
+    const value = found && version ? { path: found.path, version, source: found.source } : null;
     cached = { key, value };
     return value;
 }

package/dist/pingcode/index.js

@@ -1,8 +1,9 @@
 // PingCode（pc）集成的对外入口。
 export { PingcodeBridge, createPingcodeBridge } from "./runtime.js";
 export { loadPingcodeSkill, PINGCODE_SKILL_NAME } from "./skill.js";
-export { DEFAULT_BASE_URL, maskSecret, pingcodeConfigPath, readPingcodeConfig, normalizePingcodeConfig, writePingcodeConfig, removePingcodeConfig, PingcodeConfigError, } from "./config.js";
+export { DEFAULT_BASE_URL, inspectPingcodeConfig, maskSecret, pingcodeConfigPath, readPingcodeConfig, normalizePingcodeConfig, writePingcodeConfig, removePingcodeConfig, PingcodeConfigError, } from "./config.js";
 export { connectPingcode, disconnectPingcode, printPingcodeStatus } from "./cli.js";
 export { findPingcodeBinary, detectPingcodeBinary } from "./detect.js";
 export { resolveToken, resetTokenCache } from "./token.js";
 export { writePingcodeLauncher, clearPingcodeToken, pingcodeTokenFile } from "./launcher.js";
+export { applyRemotePingcodeConfig, isAcceptableRemoteBaseUrl } from "./remote-config.js";