pingcode-cli-unofficial 1.7.1

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pingcode-cli-unofficial",
+  "version": "1.7.1",
+  "description": "Command-line client for the PingCode Open API",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anine09/pingcode-cli-unofficial.git"
+  },
+  "bin": {
+    "pingcode": "dist/bin/pingcode.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "catalog:sync": "node --experimental-strip-types scripts/catalog-sync.ts",
+    "catalog:check": "node --experimental-strip-types scripts/catalog-sync.ts --check",
+    "skill:install": "node --experimental-strip-types scripts/install-skill.ts",
+    "scan:secrets": "node --experimental-strip-types scripts/scan-secrets.ts",
+    "check:commits": "node --experimental-strip-types scripts/check-commits.ts",
+    "package:release": "node --experimental-strip-types scripts/package-release.ts",
+    "hooks:install": "node scripts/install-hooks.mjs",
+    "prepare": "node scripts/install-hooks.mjs",
+    "install:cli": "node scripts/install.mjs"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.9"
+  },
+  "allowScripts": {
+    "esbuild@0.27.7": true,
+    "esbuild@0.21.5": true,
+    "fsevents@2.3.3": true
+  }
+}

package/skills/pingcode/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: pingcode
+description: >-
+  Use the `pingcode` CLI to work with PingCode (研发管理): 敏捷项目管理 (pjm) projects and work items —
+  list and search work items (工作项), read a story/task/bug (需求/任务/缺陷), create one, update fields,
+  move it to another state (状态流转) — 产品管理 (ship) products, requirements (需求 / idea) and
+  tickets (工单): search, read, create, update and transition them — and 测试管理 (testhub) test
+  libraries (测试库), test cases (用例), test plans (测试计划) and runs (执行用例): create a library,
+  search cases, read one, create and update a case, create a plan, record a run result, and bulk
+  add/update/delete the runs of a plan. Also resolves project-, product- and library-scoped ids and
+  organisation members (项目/产品/测试库/迭代/成员). Triggers: pingcode, PingCode 工作项,
+  创建任务, 更新状态, 迭代 sprint,
+  产品 需求 工单, 测试用例 测试计划 执行用例 测试库, SCR-5 or SLC-1 style identifiers, a work-item or
+  idea URL from a PingCode instance. Do NOT use for Wiki pages, customers or external users, the
+  org chart beyond a member lookup, Insight/Goals/Flow, or webhooks — none of those are covered by
+  this CLI, and webhooks cannot be managed through the PingCode API at all (they live in PingCode
+  Flow's UI).
+---
+
+# PingCode CLI
+
+`pingcode` is a command-line client for the PingCode Open API. Its top level mirrors PingCode's own
+GUI modules: **`product`** (产品管理 / ship — products, requirements/需求, tickets/工单),
+**`project`** (项目管理 / pjm — projects, work items, sprints, releases), **`testhub`** (测试管理 —
+test libraries, cases, plans and runs), **`scm`** (源码管理 — code hosting data), **`build`** and
+**`release`** (构建与部署 — CI build and deployment records), **`settings`** (后台设置 — the
+organisation directory) and **`auth`** (the CLI's own local credentials).
+
+`scm`, `build` and `release` are the DevOps **write-back** surface: a CI/CD job tells PingCode what
+happened, and PingCode links it to work items. None of the three reads your git server or your
+pipeline.
+
+**Two layers, and knowing which one you are on saves you a retry loop.** Every one of the **459**
+documented `/v1` endpoints is callable through **`pingcode api`** — same auth, paging, `--dry-run`,
+redaction and exit codes as anything else. **158** of them also have a named command with flags,
+name→id resolution and a table. So: if a named command exists, use it; if it does not, the answer is
+almost never "the CLI cannot do that" — it is `pingcode api list --search <word>` and then
+`pingcode api <METHOD> <path>`. Only 7 endpoints are genuinely out of reach (they need a user token;
+see [`modules/api.md`](modules/api.md)).
+
+Each business module owns its resources *and* its id lookups, so a module's whole surface is one
+`--help` away:
+
+```
+auth      login status logout
+api       GET|POST|PATCH|PUT|DELETE <path> · list · describe
+resolve   list · <kind> <name>
+product   list get · idea … · ticket … · plan … · meta …
+project   list get create update progress · work-item … · sprint … · version … · member … · meta …
+testhub   libraries … · cases … · plans … · runs … · meta …
+scm       platform … · platform-user … · repo … · branch … · commit … · ref … · pr … · review …
+build     list get create update delete
+release   env … · deploy …
+settings  users
+```
+
+Four cross-object families — `relation`, `comment`, `attachment`, `activity` — are mounted under
+five entities (`product idea`, `product ticket`, `project work-item`, `testhub cases`,
+`testhub runs`), so e.g. `pingcode project work-item comment add SCR-5 --text "…"`. See
+[`modules/crosscutting.md`](modules/crosscutting.md).
+
+Everything below assumes `pingcode` is on `PATH` (`npm run build` produces `dist/bin/pingcode.js`).
+
+## 1. Authentication gate — do this first
+
+If any command fails with exit code 3, or `pingcode auth status` reports no token, stop and get
+credentials before retrying.
+
+Credentials come from a PingCode application, not from a user account:
+
+1. In the PingCode enterprise console, open **后台管理 → 凭据管理** (Credential Management) and create an
+   application.
+2. Set 鉴权方式 (grant type) to **Client Credentials**.
+3. Grant these scopes:
+   - `pcp:read:pjm:project` — projects
+   - `pcp:write:pjm:project` — `project create` / `project update` / `project member add`. Grant
+     this one deliberately: **a project can never be deleted or archived** through this API, so
+     `project create` is irreversible
+   - `pcp:read:pjm:workitem` — work items, types, states, priorities, tags, relation types
+   - `pcp:write:pjm:workitem` — create/update/**delete** work items, plus links, tags and
+     `bulk-update`
+   - `pcp:read:global:team` — `pingcode settings users`
+   - `pcp:read:pjm:sprint` / `pcp:write:pjm:sprint` — `pingcode project meta sprints` (the sprint
+     list) and `project sprint get|create|update|bulk-create`. Grant the write half only if you intend to
+     plan sprints: **a sprint cannot be deleted**, by the API or by anyone
+   - `pcp:read:pjm:release` / `pcp:write:pjm:release` — `pingcode project version …` (发布, a
+     project release). Note the mismatch: the scope says *release*, the resource and the command say
+     *version*
+
+   For the ship (产品管理) commands, add:
+   - `pcp:read:ship:product` — `product list` / `product get` / `product meta members` /
+     `product plan list|get`, and every product name lookup, which every other ship command starts
+     with
+   - `pcp:read:ship:idea` — `product idea list` / `get` / `history list|get`, and `product meta idea-states|idea-priorities|idea-suites|idea-properties|idea-plans`
+   - `pcp:write:ship:idea` — `product idea create` / `update`
+   - `pcp:read:ship:ticket` — `product ticket list` / `get`, and `product meta ticket-states|ticket-priorities|ticket-types|ticket-channels|ticket-properties`
+   - `pcp:write:ship:ticket` — `product ticket create` / `update` / `transition`
+   - `pcp:read:ship:configuration` — **optional**, and only for `product ticket transition`: it is what
+     makes the state-plan pre-check possible. Without it the CLI warns on stderr and lets the
+     server judge the transition, so tickets stay movable either way.
+
+   The product-scoped metadata endpoints (`/v1/ship/idea/*`, `/v1/ship/ticket/*`) sit under the
+   ordinary read scopes above, **not** under `configuration` — only the ticket state plans and
+   flows need `configuration`.
+
+   For the testhub (测试管理) commands, add:
+   - `pcp:read:testhub:library` — `pingcode testhub libraries list` / `get`, `testhub meta suites`,
+     and the case-module (模块) tree behind `--suite`. Every other testhub command starts by
+     resolving a library, so this one is not optional
+   - `pcp:write:testhub:library` — `testhub libraries create`, and nothing else. Grant it only if
+     you intend to create libraries: they cannot be deleted afterwards
+   - `pcp:read:testhub:testcase` — `testhub cases list` / `get`, and `testhub meta case-types`
+   - `pcp:write:testhub:testcase` — `testhub cases create` / `update`
+   - `pcp:read:testhub:testplan` — `testhub plans list` / `get`, `testhub meta plan-types`, and
+     `testhub runs list`
+   - `pcp:write:testhub:testplan` — `testhub plans create`, `testhub runs update` / `bulk`
+   - `pcp:read:testhub:configuration` — **not optional, despite the name**: `testhub meta
+     case-states`, `testhub meta run-statuses` and `testhub meta important-levels` all sit behind
+     it, and they are the only source of a `state_id`, a `status_id` and an `important_level_id`.
+     Without it those three return a bare 403 while their sibling `case-types` keeps working, and
+     since `PATCH /runs/{id}` requires `status_id`, a token without this scope **cannot write a
+      run at all**. The CLI adds that explanation to the 403 for all three of those lookups.
+
+   `--executor` on a run and `--assignee` on a plan both resolve through the organisation
+   directory, so they also need `pcp:read:global:team`.
+
+   For the scm (源码管理) commands, add:
+   - `pcp:read:devops:code` — `pingcode scm platform|platform-user|repo list` / `get`, and every
+     platform/repository name lookup
+   - `pcp:write:devops:code` — `scm platform|platform-user|repo create` / `update`
+
+   The whole scm area is **企业令牌 only**, which is what `client_credentials` gives you, so no
+   extra grant type is needed — only the two scopes above.
+
+   For the build and deploy write-back commands, add:
+   - `pcp:read:devops:build` / `pcp:write:devops:build` — `pingcode build list|get` and
+     `build create|update|delete`. **Separate from `devops:code`**: a token that can write
+     commits cannot write builds, and the only symptom is exit 4
+   - `pcp:read:devops:deploy` / `pcp:write:devops:deploy` — `pingcode release env …` **and**
+     `pingcode release deploy …`; one pair covers both subgroups, there is no separate
+     environment scope
+
+   These two areas are 企业令牌 only as well, so again no extra grant type.
+4. Copy the `client_id` and `client_secret`.
+
+Then:
+
+```bash
+pingcode auth login --client-id <id> --client-secret <secret> --save
+pingcode auth status --check
+```
+
+- `--save` writes the client id/secret to `~/.pingcode/config.json` (mode `0600`). Without `--save`
+  only the token is stored, and a new login is needed once it expires.
+- Credentials can also arrive as `PINGCODE_CLIENT_ID` / `PINGCODE_CLIENT_SECRET`, or interactively
+  when a terminal is attached.
+- Self-hosted instances need `--host https://pingcode.example.com` (or `PINGCODE_HOST`); the API is
+  served from `<host>/open` there.
+- `pingcode auth logout` removes the token, the stored credentials and the metadata cache.
+
+**Security:** a Client Credentials token has organisation-wide system-administrator authority and is
+valid for 30 days. It is not tied to a user. Never print it, never copy it into a file in a
+repository, and treat `~/.pingcode/config.json` as a secret. The CLI redacts the secret and the token
+from every URL, log line, dry-run plan and error message it emits.
+
+## 2. Output contract
+
+- `--json` makes **stdout carry JSON only**. Logs, warnings, tables and notes go to stderr.
+- In `--json` mode, timestamps stay raw unix **seconds**. Human mode renders local time.
+- Three list shapes, by command family:
+  - `project list` / `project work-item list` (one page) → `{"page_index":0,"page_size":30,"total":123,"values":[…]}`,
+    and the same for `product`/`testhub` one-page lists
+  - any list with `--all` → `{"values":[…],"count":42,"all":true}`
+  - every `meta` lookup — `pingcode product meta …`, `pingcode project meta …`,
+    `pingcode testhub meta …`, and `pingcode settings users` (which still accepts
+    `--page`/`--page-size`) → `{"values":[…],"count":20}`
+- Single-resource commands (`get`, `create`, `update`, `transition`) print the resource object.
+- **Read keys defensively: an absent key means null or empty.** The CLI normalises `null` and `""`
+  to "not present", so a field the API returned as `null` (an unset `plan_at`, `score`, `solution`)
+  or as an empty string (a blank `description`) is simply missing from the JSON. It does **not**
+  distinguish the two, and a missing key is never evidence that the field does not exist. Use
+  `x?.y ?? fallback`, not `'y' in x`.
+- `--dry-run` on a mutating command prints `{"dry_run":true,"request":{…}}` to stdout and exits 0
+  without sending anything. Read requests still run, so ids are really resolved.
+- Errors in `--json` mode go to **stderr** as `{"error":{"kind":…,"message":…,"code":…,"exit":…}}`.
+- **`pingcode api` is the exception to the shapes above**: stdout is the API's raw JSON, so `--json`
+  is a no-op on its five verbs and no key is normalised away. Its own `api list` / `api describe` are
+  local catalog views and do honour `--json`.
+- Global flags (`--host`, `--json`, `--dry-run`, `--no-cache`, `--verbose`) may appear before or
+  after the subcommand.
+
+### Exit codes
+
+| Exit | Meaning |
+|---|---|
+| 0 | success (including a printed dry-run plan) |
+| 1 | unexpected internal error |
+| 2 | usage error: bad flags, missing input, ambiguous or unresolvable name, empty update |
+| 3 | authentication: no or invalid credentials |
+| 4 | permission: 403, or a scope the app was not granted |
+| 5 | not found: the work item, state or other resource does not exist |
+| 6 | rate limited: 429 (200 requests/minute per token) |
+| 7 | other API error, carrying the API's `{code, message}` |
+| 8 | transport failure: DNS, TCP, TLS, timeout, unparseable body |
+
+The API answers HTTP 400 for both "not found" and "bad credentials", so the CLI maps a few known API
+codes onto exits 5 and 3 rather than trusting the status. Unknown codes stay on exit 7 with the raw
+`code` in the error payload — read it before concluding anything.
+
+## 3. Commands
+
+### Where each module's commands are documented
+
+The per-module surface — every flag, every id lookup, and the traps specific to that module — lives
+one file per module, so a module can be revised without touching this one:
+
+| Module | File | Covers |
+|---|---|---|
+| 项目管理 pjm | [`modules/pjm.md`](modules/pjm.md) | `project list/get/create/update/progress`, `project meta …`, `project work-item …` (incl. `link` / `tag` / `history`), `project sprint …`, `project version …`, `project member …`, and the pjm-only rules |
+| 产品管理 ship | [`modules/ship.md`](modules/ship.md) | `product list/get`, `product meta …`, `product idea …`, `product ticket …`, `product plan …` (需求排期, read-only), and the ship-only traps |
+| 测试管理 testhub | [`modules/testhub.md`](modules/testhub.md) | `testhub libraries/cases/plans/runs/meta …`, and the testhub-only traps |
+| 源码管理 scm | [`modules/scm.md`](modules/scm.md) | `scm platform …`, `platform-user …`, `repo …`, `branch …`, `commit …`, `ref …`, `pr …`, `review …` — the DevOps write-back surface, 企业令牌 only |
+| 构建与部署 | [`modules/cicd.md`](modules/cicd.md) | `build …` (CI build records) and `release env …` / `release deploy …` (deploy targets and deployments), 企业令牌 only |
+| 跨对象资源 | [`modules/crosscutting.md`](modules/crosscutting.md) | `relation` / `comment` / `attachment` / `activity`, mounted under work items, ideas, tickets, cases and runs |
+| 通用逃生舱 | [`modules/api.md`](modules/api.md) | `api GET/POST/PATCH/PUT/DELETE <path>` for every documented endpoint, plus `api list` / `api describe` |
+
+A file marked *reserved* describes commands that **do not exist yet** — there are none at the
+moment, every module document above is real. Do not suggest a command you have not seen in
+`pingcode --help`; run it if you need to know what is actually installed.
+
+`auth` and `settings` are documented here rather than in a module file: they are the CLI's own
+credentials and a single directory lookup, not a business module.
+
+### Auth
+
+```bash
+pingcode auth login --client-id <id> --client-secret <secret> --save
+pingcode auth status
+pingcode auth status --check      # adds one live API call: GET /v1/pjm/projects?page_size=1
+pingcode auth logout
+```
+
+### Settings — 后台设置
+
+```bash
+pingcode settings users --keywords wang --json
+```
+
+The organisation directory (`/v1/directory/users`, scope `pcp:read:global:team`) belongs to no
+business module, which is why it sits here rather than under `product` or `project`. It is the
+candidate set for pjm's `--assignee`; ship's `--assignee` uses `product meta members` instead.
+
+### Name → id resolution
+
+`pingcode api` takes **ids only** — it understands no business names on purpose. `resolve` is the
+missing half: one lookup, one id on stdout, nothing else.
+
+```bash
+pingcode resolve list --json                                   # every kind and the parent it needs
+pingcode resolve project "移动端 App" --json                     # {"kind":"project","id":"5f2a…",…}
+pingcode resolve ship-product SLC --json                       # identifier works as an alias
+pingcode resolve ship-idea-state 已评审 --parent <product_id> --json
+pingcode resolve testhub-library "研发测试库" --json
+```
+
+- stdout under `--json` is the resolution itself, so it composes:
+  `pingcode api GET /v1/ship/idea/states --query product_id=$(pingcode resolve ship-product "智能客服" --json | jq -r .id)`.
+- An **id is passed through** after being verified; a **name must match exactly** (case-insensitively)
+  and exactly once. Zero or several matches is exit 2 listing the candidates — it never picks one.
+- `--parent` takes an **id**, not a name: chain a second `resolve` if you only have the name.
+- Answers are cached for 24 h per (host, `client_id`, parent, kind); `--no-cache` bypasses it.
+- Ticket state plans and their flows are absent from `resolve list`, because no name addresses them.
+
+The refined commands (`project meta …`, `product meta …`, `testhub meta …`) already accept names
+directly, so `resolve` is mainly for feeding the generic layer.
+
+### The two flag shapes, and how to tell which one a leaf uses
+
+Every field that could be given either as a business name or as an id is spelled in **one of two
+ways**, and the split is by module, not by field. It is not documented anywhere upstream, so read
+`--help` rather than guessing — but these are the rules the CLI follows.
+
+| Shape | Modules | Example |
+|---|---|---|
+| **Paired** — `--x <name\|id>` **plus** `--x-id <id>` | `testhub`, `scm`, `release` | `--library` / `--library-id`, `--platform` / `--platform-id`, `--repo` / `--repo-id`, `--env` / `--env-id` |
+| **Single** — one `--x <name\|id>` that accepts both | `pjm` (`project`), `ship` (`product`) | `--project`, `--sprint`, `--release`, `--product` |
+
+Both shapes accept a name or an id. What differs is only whether you can **force** the no-lookup
+path:
+
+- With a **pair**, `--x` triggers a name lookup (one extra GET, cached 24 h) and `--x-id` is sent
+  verbatim with no lookup at all. The two are mutually exclusive — passing both is exit 2. Reach for
+  `--x-id` when you already hold ids (it is faster, and it cannot be tripped by two objects sharing
+  a name).
+- With a **single** flag, the CLI decides: it passes a value through if it looks like an id and
+  looks it up otherwise. There is no way to say "skip the lookup". It never validates an id's shape
+  — ids in this API are 24-hex, 32-hex *or* a bare slug like `task` / `story` / `bug`.
+
+Three deliberate gaps in that scheme, so you do not read them as bugs:
+
+1. **`testhub runs list --case-id` has no `--case` twin**, although `runs create`,
+   `runs bulk-create` and `cases bulk-update` all pair on the same resource. The value goes straight
+   into the search filter, so a `short_id` arrives unresolved and the API answers 400 `100044`
+   (`'property_value'值不合法`). Pass a full case id, or get one from `testhub cases list`.
+2. **`scm branch|commit|pr list --work-item-id` accepts a 24-hex ObjectId only** — *not* an
+   identifier like `PLM-001`, which returns 400 `100003`. Note the asymmetry within one group: the
+   *write* paths' `--work-item` in the same commands **do** take `PLM-001`. Each leaf's `--help`
+   says which.
+3. **`project update --state-id` has no `--state`**, because there is no project-state resolver kind:
+   the lookup lives at `/v1/pjm/project/states`, which no `resolve` kind covers. Read the ids with
+   `pingcode api GET /v1/pjm/project/states --query project_id=<id>`.
+## 4. Rules that will bite you
+
+These hold in **every** module. The rules that apply to one module only — pjm's
+`--state` needs `--type`, ship's product scoping, testhub's library scoping, scm's platform hop —
+live in that module's file, because there is no way to state them once and have them be true.
+
+1. **Resolve ids under the right parent first.** Ids are scoped: to a **project** in pjm, a
+   **product** in ship, a **test library** in testhub, a **hosting platform** in scm. The same state
+   name is a different id under a different parent, so run that module's `meta` lookup (or
+   `pingcode resolve <kind> <name> --parent <id>`) before a write. Never validate an id's shape: they
+   are 24-hex, 32-hex **or** bare slugs (`task`, `story`, `bug`).
+2. **`update` replaces, it does not merge.** Every field you pass overwrites the stored value, and
+   array fields and `properties` objects are replaced wholesale rather than merged. Read the item
+   first if you need to preserve anything.
+3. **There is no way to clear a field.** Only the fields you pass are sent; the CLI has no
+   `--clear-<field>`.
+4. **An update with no fields is exit 2**, not a no-op.
+5. **A 200 is not proof the field landed.** This API accepts unknown body fields, several read-only
+   fields, and whole unsupported properties, with a 200 and no warning. Where the CLI knows about a
+   specific case it refuses or warns on stderr; otherwise read the object back.
+6. **Every `delete` needs `--yes`, and every `PUT` needs `pingcode api`.** No named command issues a
+   `PUT`: it is full replacement and this API never documents what an omitted field does. See
+   [`modules/api.md`](modules/api.md).
+7. **No endpoint supports sorting.** Neither the CLI nor the API can order results. Sort what you
+   collected yourself, and remember that offset paging over unordered, changing data can duplicate or
+   skip rows.
+8. **`--all` is best effort, not a consistent snapshot.** It walks pages, de-duplicates by id, stops
+   at `--limit` (default 500), and gives up if the API stops honouring `page_index`.
+9. **Rate limit is 200 requests per minute per token.** Prefer one `--page-size 100` call over many
+   small ones, let the metadata cache work, and do not loop `--all` over large projects casually.
+10. **Timestamps are unix seconds.** Date flags accept `1730000000` or a calendar date — but read the
+    flag's own `--help`, because the families differ on purpose: `project --start-at` stores the
+    instant verbatim, while `project sprint` / `project version` / `testhub plans` snap `--start` to
+    `00:00:00` and `--end` to `23:59:59` of the date given.
+
+## 5. Agent workflow
+
+0. **Decide which layer you are on.** If the task maps onto a named command, use it. If it does not,
+   do not conclude the CLI cannot help: `pingcode api list --search <word> --json` finds the endpoint,
+   `pingcode api describe <id>` prints its fields, scope and warnings, and `pingcode resolve <kind>
+   <name> --json` turns a name into the id `api` needs. Never invent a command path — if you are
+   unsure it exists, run its `--help`.
+1. `pingcode auth status` — if it reports no token, ask the user for credentials (§1) instead of
+   guessing.
+2. Resolve the parent scope: `pingcode project list --json` for work items,
+   `pingcode product list --json` for ideas and tickets, `pingcode testhub libraries list --json`
+   for cases, plans and runs, or `pingcode scm platform list --json` for anything under `scm`.
+3. Resolve ids — each module's file has the full list; the short version:
+   - pjm: `pingcode project meta types --project <p> --json`, then
+     `project meta states --project <p> --type <t> --json`. Keep the type around: you need it again for
+     `--state <name>` on any write.
+   - ship: `pingcode product meta idea-states --product <p> --json` (or the `ticket-*` equivalents), plus
+     `product meta members --product <p> --json` before setting an assignee, and
+     `product meta ticket-types --product <p> --json` before creating a ticket — `--type` is required there.
+   - testhub: `pingcode testhub meta case-states --library <l> --json`, `case-types`,
+     `run-statuses` (the source of `--status`, needed by every run write), `suites` (the `PATH`
+     column is the spelling `--suite` takes) and the org-wide `important-levels`. Find the plan with
+     `pingcode testhub plans list --library <l> --json`, or create one — `testhub meta plan-types
+     --library <l> --json` first, since `--type` on `plans create` comes from there. If the tenant
+     has no usable library at all, `pingcode testhub libraries create` is the bootstrap; read
+     [`modules/testhub.md`](modules/testhub.md) §4c rule 15 first, because it cannot be undone.
+   - scm / CI: resolve the platform, then the repo (`pingcode scm repo list --platform <p> --json`);
+     branch ids are needed as *ids* by `scm pr create`, and work items are linked by
+     **identifier** (`PLM-1`), never by id.
+4. Read before writing: `pingcode project work-item get <ref> --json`, `pingcode product idea get <ref> --json`,
+   `pingcode product ticket get <ref> --json` or `pingcode testhub cases get <ref> --json` — and for a
+   step-level run edit, read the run's steps first, because `--step` must cover all of them.
+5. For any mutation, run it with `--dry-run --json` first, show the plan, get confirmation, then run
+   it again without `--dry-run`. Say what cannot be undone *before* creating it: **nothing in ship can
+   be deleted**, a project or sprint can never be deleted, a test library cannot be deleted, and
+   `scm` has no DELETE except branches.
+6. Always pass `--json` and parse stdout only; read stderr for warnings. Remember that
+   `pingcode api` prints the API's raw JSON regardless, and that a missing key means null *or* empty.
+7. On exit 2 read the message — it names the flag, the ambiguous name, the states a ticket can
+   actually move to, or the nearest documented paths. On exit 3 re-authenticate. On exit 4 name the
+   scope from `api describe`. On exit 6 wait a minute rather than retrying immediately.
+
+## 6. What has no named command
+
+**Nothing on this list is out of reach** — it has no *refined* command, which means the answer is
+`pingcode api`, not "the CLI cannot". Say that to the user rather than declaring a limitation.
+
+| Area | Named commands | How to reach it |
+|---|---|---|
+| Wiki spaces and pages (19 endpoints) | none | `pingcode api list --module wiki`, then `api GET/POST/PATCH`. **`DELETE /v1/wiki/pages/{id}` has no recovery path** — never run it speculatively |
+| 组织架构 beyond `settings users`: departments, teams, roles, jobs (22) | none | `pingcode api GET /v1/directory/departments` etc. |
+| 工时 worklogs and worklog types (7) | none | `pingcode api GET /v1/workloads` |
+| 评审 reviews (8) and 关注人 participants/followers (4) | none | `pingcode api GET /v1/reviews`, `api GET /v1/participants` — note `scm review` is a *different* resource |
+| 权限 permission views (7) | none | 6 of the 7 need a user token and are refused; `pingcode api GET /v1/permission/points` works |
+| 安全日志 login / audit logs (2) | none | `pingcode api GET /v1/security/audit_logs` |
+| Nexus / CES app storage (5) | none | `pingcode api list --module nexus` |
+| pjm 工作项配置 schemes (42) and 看板 boards (15) | only the project-scoped read lookups, as `project meta …` | `pingcode api list --module pjm --search 工作项配置` |
+| ship customers, external users, product tags, suite and member writes | none | `pingcode api list --module ship` |
+| all 10 `PUT` endpoints | none, on purpose | `pingcode api PUT …` — read the warning in [`modules/api.md`](modules/api.md) first |
+
+Genuinely unavailable, as opposed to merely unrefined:
+
+- **Webhooks.** PingCode has no REST API for them at all; they are configured in PingCode Flow's UI.
+- **Insight / Goals / Flow.** No API surface.
+- **The 7 user-token endpoints** (`/v1/myself`, `/v1/permission/my/*`, `/v1/permission/check/*`) —
+  they need the OAuth2 authorization-code flow, which this CLI does not implement. They are refused
+  before any request, with an explanation.
+- **Uploading a file as an attachment.** Only the JSON code-snippet form of `POST /v1/attachments`
+  exists; the `multipart/form-data` form is not expressible in either layer. See
+  [`modules/crosscutting.md`](modules/crosscutting.md).
+
+A module file also records the omissions *inside* that module and how to reach them — testhub's are a
+section of its own in [`modules/testhub.md`](modules/testhub.md) §5, and every other module states
+them inline next to the family they belong to. If a module document does not mention something, check
+`pingcode api list --module <m>` before telling the user it is impossible.
+
+## 7. Installing this skill elsewhere
+
+From a checkout of the CLI repository:
+
+```bash
+npm run skill:install -- --dry-run    # show the destinations
+npm run skill:install                 # copy to ~/.claude/skills and ./.opencode/skills
+npm run skill:install -- --force      # overwrite existing copies
+```

package/skills/pingcode/modules/api.md

@@ -0,0 +1,116 @@
+# 通用逃生舱 (the generic executor) — `api`
+
+> Part of the `pingcode` skill. Read [`../SKILL.md`](../SKILL.md) first — it carries the
+> authentication gate, the stdout/stderr contract, the exit-code table and the rules that
+> apply to every module. This file is only the generic executor and its discovery commands.
+
+`pingcode api` calls **any** of the 459 documented `/v1` endpoints directly. Use it whenever the
+refined command groups do not cover what you need — that is most of the API, and it is not a
+second-class path: the request goes through the same transport, the same auth, the same
+`--dry-run` gate and the same exit codes as every other command.
+
+What it deliberately does **not** do: no name→id resolution, no response shaping, no
+per-endpoint flags. Ids go in as ids, JSON comes out as JSON.
+
+## 1. The two rules that surprise people
+
+1. **stdout is always the API's raw JSON, so `--json` is a no-op on the five verbs.** There is no
+   table, no localised time, no column clipping — nothing to switch off. (`api list` and
+   `api describe` are local catalog views and *do* honour `--json`.)
+2. **`DELETE` requires `--yes`.** Without it: exit 2, nothing sent, and the message shows what
+   would have been sent. `pingcode api list --method DELETE` enumerates all 49 deletable
+   endpoints; two of them have no recovery path at all — a wiki page and a code branch.
+
+## 2. Find the endpoint first
+
+```bash
+pingcode api list --search commit           # substring over path, title and group
+pingcode api list --module scm              # 36 endpoints
+pingcode api list --token ENT               # 61 endpoints only a machine identity may call
+pingcode api list --method DELETE           # the auditable danger surface, 49 rows
+pingcode api describe scm.commits.get       # every documented field, scope, token, paging
+pingcode api describe GET /v1/scm/commits/{commit_id_or_sha}
+```
+
+Both are **local**: they read a bundled catalog and never make a request. Prefer them over
+guessing a path, and prefer them over the documentation site (which is a client-rendered SPA
+whose per-endpoint anchors are ~200 characters of percent-encoding).
+
+`api describe` also prints the warnings that matter for that one endpoint: that a `PUT` is a
+full replacement, that a `DELETE` is irreversible, that an endpoint needs a user token, or that
+the docs declare no scope for it.
+
+## 3. Call it
+
+```bash
+pingcode api GET    /v1/scm/commits/9f3c1ab
+pingcode api GET    /v1/relations --query principal_type=work_item --query principal_id=<id>
+pingcode api GET    /v1/directory/users --page 2 --page-size 100
+pingcode api GET    /v1/directory/users --all --limit 200
+pingcode api POST   /v1/comments --set principal_type=work_item --set principal_id=<id> --set content="CI #123 failed"
+pingcode api PATCH  /v1/build/builds/<id> --set status=success
+pingcode api POST   /v1/wiki/pages --body-file page.json
+pingcode api POST   /v1/pjm/work_items/search --body '{"mode":"query","payload":{"keywords":"login"}}'
+pingcode api DELETE /v1/pjm/projects/<id>/versions/<id> --yes
+```
+
+- the path carries **substituted ids**, never `{placeholders}` and never a `?query` — a query
+  string in the path is exit 2, because silently dropping it would be worse;
+- `--query k=v` is repeatable; repeating a key sends it as CSV, which is this API's convention;
+- body: `--set k=v` (repeatable, flat, values sent **verbatim**), `--body-file <path>`,
+  `--body '<json>'`, or `--body -` to read stdin. The four are mutually exclusive;
+- `--set` values are never type-guessed: a select-typed field wants the option's `_id`, not its
+  display text;
+- `--set` is **scalar-only**. Its value is sent verbatim as a JSON *string*, so an array or object
+  field needs `--body` / `--body-file`. A few fields are genuinely type-checked upstream —
+  `--set version_ids='["<id>"]'` on a work item is `100006 'version_ids'不是有效的数组`, exit 7 —
+  but do not count on that everywhere: this API's default is to accept a wrong-typed field with 200
+  and store nothing;
+- paging: `--page` / `--page-size` (max 100) are forwarded **only when you pass them**; `--all`
+  walks the pages and prints `{"values":[…],"count":N,"all":true}`. On an endpoint that is not a
+  collection, any paging flag is exit 2 rather than silently ignored.
+
+### The five `POST …/search` endpoints
+
+`pjm/work_items`, `ship/ideas`, `ship/tickets`, `testhub/cases`, `testhub/runs`. They are **reads
+wearing a mutating verb**, so: they execute even under `--dry-run`, their body is
+`{"mode":"query","payload":{…}}` (`mode` has exactly one legal value), and the paging flags are
+written into `payload.page_index` / `payload.page_size` for you. stdout is the page envelope.
+
+### `PUT` — prefer `PATCH`
+
+All 10 `PUT` endpoints are reachable **only** here, on purpose. `PUT` replaces the whole object
+and this API never documents what an omitted field does; one module was measured clearing a
+field that its `PATCH` sibling preserves. Unless you truly mean "replace everything", use
+`PATCH`.
+
+## 4. What fails before anything is sent (all exit 2, zero requests)
+
+| Situation | What you get |
+|---|---|
+| path not in the catalog | the three nearest documented paths ("did you mean …") |
+| method the path does not support | the methods that path *does* support |
+| a required query/body field missing | the field named, by kind |
+| `{placeholder}` or `?query` still in the path | told which one |
+| `DELETE` without `--yes` | the request it refused to send |
+| paging flags on a non-collection | told that the endpoint does not page |
+| `/oauth2/authorize` | told it is the browser authorization page, not a REST endpoint |
+| a **user-token-only** endpoint | told this CLI holds an enterprise token |
+
+The seven user-token endpoints — `/v1/myself`, `/v1/permission/my/*` (3) and
+`/v1/permission/check/*` (3) — are the only part of the API this CLI cannot reach at all: they
+need the OAuth2 authorization-code flow, which is not implemented. Note that
+`GET /v1/permission/points` **does** work. Everything else, including all 61 enterprise-token-only
+DevOps endpoints, is reachable with the credentials from `pingcode auth login`.
+
+## 5. Everything else behaves exactly as it does elsewhere
+
+`--dry-run` halts every write (search reads excepted, above) and prints the full request plan
+with the `Authorization` header and any `client_secret` redacted. A `401` re-acquires the token
+and replays once. A `429` honours `x-pc-retry-after` once. Any `2xx` is success. The exit-code
+table in [`../SKILL.md`](../SKILL.md) applies unchanged; on a `403` the scope the docs declare
+for that endpoint is printed to stderr (or an honest "the docs declare no scope" when they
+declare none).
+
+The rate limit is shared with everything else, so a `--all` sweep over a large collection spends
+the same budget any other command would.