pingcode-cli-unofficial 1.7.1

package/skills/pingcode/modules/scm.md

@@ -0,0 +1,432 @@
+# 源码管理 (scm) — `scm`
+
+> 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 scm command surface and the ids it needs.
+
+**What this module is for.** It is the *write-back* API a CI system uses: you tell PingCode
+which hosting platform, git identities, repositories, branches and commits exist, and
+PingCode links them to work items. It does **not** read your git server — nothing here
+clones, pushes or inspects a repository. Every row you create is a record inside PingCode.
+
+**The CI write-back path, in order.** Each step needs the one before it:
+
+```
+platform → repo → branch ─┬→ pr → review
+                          ├→ ref   (commit ↔ branch)
+              commit ──────┘
+```
+
+A commit is created *without* a repository (it is organisation-level), so `scm ref create`
+is what attaches it to a branch. Do not look for a `--repo` on `scm commit`.
+
+A pull request needs its **target branch id** first, and a code review needs its **pull
+request id** — both are ids, not names or numbers, so create the branch and the PR before
+you try to hang anything off them.
+
+**Two group-wide facts.**
+
+- Every scm endpoint is **企业令牌 only** — which is exactly the token this CLI holds, so the
+  whole group works out of the box. Required scopes: `pcp:read:devops:code` and
+  `pcp:write:devops:code`. Without them you get exit 4.
+- An scm **platform** (托管平台) is *not* a ship product, even though both sit under a
+  `products` URL segment. `pingcode product …` is 产品管理; `pingcode scm platform …` is a
+  GitHub/GitLab/SVN server record.
+
+### Hosting platforms — `scm platform`
+
+Everything else in scm is addressed under a platform, so this is always the first call.
+
+```bash
+pingcode scm platform list --json
+pingcode scm platform get Github --json
+pingcode scm platform create --name "Gitea (internal)" --type other --dry-run --json
+pingcode scm platform create --name "Gitea (internal)" --type other --description "self-hosted" --json
+pingcode scm platform update Github --description "github.com" --json
+```
+
+`--type` is a closed enum used to pick an icon:
+`github | gitlab | bitbucket | coding.net | gogs | git | svn | gerrit | other`. A value outside
+it is rejected by the server (exit 7), not by the CLI.
+
+A platform **name is unique per organisation**; creating a duplicate is exit 7 with
+`'product'已经存在`.
+
+### Git identities — `scm platform-user`
+
+```bash
+pingcode scm platform-user list --platform Github --json
+pingcode scm platform-user list --platform Github --name octocat --json
+pingcode scm platform-user get 685c6ca42974f854bb4979ac --platform Github --json
+pingcode scm platform-user create --platform Github --name octocat --display-name "Octo Cat" \
+  --html-url https://github.com/octocat --json
+pingcode scm platform-user update 685c6ca42974f854bb4979ac --platform Github --display-name "Octo" --json
+```
+
+**A platform user is a git author identity, not a PingCode member, and there is no field that
+links it to one.** The resource is exactly `{id, name, display_name, html_url, avatar_url}` —
+no `user`, no `user_id`, no `email`, on read or on write. Attribution is by the **name
+string**: a commit's `committer_name` and a branch's `sender_name` are matched against these
+rows. So do not promise a user that the CLI can "assign a commit to a person"; what it can do
+is make sure the git username exists as an identity with a readable display name and avatar.
+
+⚠️ **Five write fields silently CREATE one of these rows when the name is unknown**, and
+**there is no DELETE for a platform user anywhere in scm**, so every typo is permanent:
+
+| field | flag | upserts? |
+|---|---|---|
+| repository `owner_name` | `scm repo create --owner-name` | **yes** |
+| branch `sender_name` | `scm branch create --sender` | **yes** |
+| pull request `creator_name` | `scm pr create/update --creator` | **yes** |
+| pull request `merged_by_name` | `scm pr create/update --merged-by` | **yes** |
+| code review `reviewer_name` | `scm review create/update --reviewer` | **yes** |
+| commit `committer_name` | `scm commit create --committer` | **no** — that path has no platform to create one in |
+
+All five upserts are verified live. Check the name before a write:
+`scm platform-user list --platform <p> --name <username> --json` returns zero rows if it
+does not exist yet.
+
+`get` and `update` take an **id**, because ids in this API have three shapes and are never
+guessed. Turn a git username into an id with the exact-match filter above
+(`list --name octocat`), which is why no `resolve` kind exists for this resource.
+
+### Repositories — `scm repo`
+
+```bash
+pingcode scm repo list --platform Github --json
+pingcode scm repo list --platform Github --full-name acme/pingcode-cli --json
+pingcode scm repo list --platform Github --all --limit 200 --json
+
+pingcode scm repo get pingcode-cli --platform Github --json
+pingcode scm repo get acme/pingcode-cli --platform Github --json
+
+pingcode scm repo create --platform Github --name pingcode-cli --full-name acme/pingcode-cli \
+  --owner-name octocat --private true \
+  --html-url https://github.com/acme/pingcode-cli \
+  --branches-url 'https://github.com/acme/pingcode-cli/tree/{branch}' \
+  --commits-url 'https://github.com/acme/pingcode-cli/commit/{sha}' --json
+
+pingcode scm repo update acme/pingcode-cli --platform Github --private false --json
+```
+
+Rules that will bite otherwise:
+
+- **`full_name` (`owner/name`) is the unique key, `name` is not.** Two repositories in one
+  platform may share a name (a fork and its upstream); `scm repo get <name>` then exits 2 and
+  lists both ids, and the `full_name` is what disambiguates it.
+- **`--full-name` is the only list filter.** The API ignores a `name` query parameter and
+  returns every repository, so the CLI does not offer one.
+- **`--owner-name` creates the identity if it does not exist.** An unknown git username is not
+  rejected: the server makes a new platform user for it and points `owner` at it. A typo
+  therefore silently produces a ghost identity, and nothing in this API can delete it.
+- **`--private` and `--fork` take `true` / `false`**, not bare switches, so a repository can be
+  made public again. Omit the flag to leave the field untouched.
+- **The `*_url` values are templates stored verbatim** (`{branch}`, `{sha}`,
+  `{base}...{head}`, `{number}`). PingCode substitutes them when it renders a link; the CLI
+  never does. **Quote them** in a shell, or the braces may be eaten.
+
+### Branches — `scm branch`
+
+```bash
+pingcode scm branch list --platform Github --repo acme/pingcode-cli --json
+pingcode scm branch list --platform Github --repo acme/pingcode-cli --name feature/PLM-001 --json
+pingcode scm branch list --platform Github --repo acme/pingcode-cli --work-item-id 5edca524cad2fa112b06105c --json
+
+pingcode scm branch get feature/PLM-001 --platform Github --repo acme/pingcode-cli --json
+
+pingcode scm branch create --platform Github --repo acme/pingcode-cli \
+  --name feature/PLM-001-login --sender octocat --work-item PLM-001 --json
+
+pingcode scm branch update feature/PLM-001-login --platform Github --repo acme/pingcode-cli \
+  --work-item PLM-001 --work-item PLM-002 --json
+pingcode scm branch update feature/PLM-001-login --platform Github --repo acme/pingcode-cli --default --json
+
+pingcode scm branch delete feature/PLM-001-login --platform Github --repo acme/pingcode-cli --yes --json
+```
+
+Rules that will bite otherwise:
+
+- **`--sender` creates the git identity if it does not exist**, exactly like `repo
+  --owner-name`. An unknown username is not rejected — a platform user is made for it, and
+  **nothing in this API can delete a platform user**. Create it deliberately first
+  (`scm platform-user create`) and check the spelling.
+- **`--default` is a switch, and there is no `--default false`.** On a patch the server
+  accepts *only* `true` — the field is really the action "make this the default". It also
+  **clears the flag on whichever branch currently holds it**, so one call changes two
+  branches. (Contrast `scm repo --private true|false`, which is genuinely three-state.)
+- **The first branch in an empty repository becomes the default automatically**, even
+  though you did not ask.
+- **`--work-item` takes an identifier (`PLM-001`), not an id — and an unknown one is
+  silently ignored.** The API returns 200 either way. The CLI compares what came back
+  against what you asked for and prints a `warning:` on stderr naming the identifiers that
+  did not link; the exit code stays 0, and under `--json` the authoritative answer is the
+  `work_items` array on stdout. **Read it.**
+- **`--work-item` REPLACES the link set on update**, it does not add to it. Pass every
+  identifier you want to keep. There is no "clear" flag — repeat the command with the
+  links you want.
+- **`--name` is a real filter here** (exact, case-insensitive), unlike on `repo list`.
+  Branch names are unique per repository, which is also why `scm branch get <name>` works
+  in one request and needs no `resolve` kind.
+
+### Deleting a branch — the one destructive command in scm
+
+```bash
+# refuses without --yes, and names the branch it would delete
+pingcode scm branch delete feature/old --platform Github --repo acme/pingcode-cli
+pingcode scm branch delete feature/old --platform Github --repo acme/pingcode-cli --yes --dry-run --json
+pingcode scm branch delete feature/old --platform Github --repo acme/pingcode-cli --yes --json
+```
+
+**This is the only `DELETE` in the whole scm module** — 代码分支 is the one family shaped with
+a `DELETE` and no `PUT`; the other five are the reverse. Three things to know before you
+run it:
+
+- **`--yes` is mandatory** and the refusal echoes the *resolved branch name*, not just what
+  you typed. There is deliberately **no `--all`**: bulk branch deletion is not offered.
+- **The default branch cannot be deleted at all** (exit 7, `默认分支不能被删除`). Make another
+  branch the default first. A repository whose only branch is the default therefore has no
+  deletable branch.
+- **Deleting a branch orphans its commit refs, permanently.** The refs keep resolving by
+  id, but `scm ref list --branch-id <the deleted branch>` then fails with a server error
+  (HTTP 500), and **refs have no delete**, so the broken state cannot be cleaned up. Delete
+  a branch only when you are sure nothing references it.
+
+### Commits — `scm commit`
+
+```bash
+# by SHA — this is the point of the family: a pipeline has a SHA, not a PingCode id
+pingcode scm commit get 96a024347146ebdc5f481f45e6e6871e0c43af5f --json
+pingcode scm commit get 5e3bb2128cfda459bbafa3fb --json
+
+pingcode scm commit list --sha 96a024347146ebdc5f481f45e6e6871e0c43af5f --json
+pingcode scm commit list --work-item-id 5edca524cad2fa112b06105c --json
+
+pingcode scm commit create --sha 96a024347146ebdc5f481f45e6e6871e0c43af5f \
+  --message "feat(auth): #PLM-001 add login" --committer octocat \
+  --committed-at 2026-08-03T09:00:00Z \
+  --added src/login.ts --modified README.md --removed src/old.ts \
+  --work-item PLM-001 --json
+```
+
+- **These leaves take no `--platform` and no `--repo`.** A commit is an
+  organisation-level record; that is the API's shape, not an omission. Consequently
+  `commit list` with no filter **scans every commit in the organisation** — always pass
+  `--sha` or `--work-item-id`.
+- **`get` accepts a full 40-character SHA or a PingCode id.** An **abbreviated SHA does not
+  work** (the server answers "resource path error", exit 5), even though every git tool
+  accepts one. Pass the full hash.
+- **`--sha` is the one value this API validates for you**: a malformed SHA is exit 7 on
+  create, not a silent acceptance.
+- **`--committer` does NOT create an identity.** This is the opposite of branch `--sender`:
+  the commit stores the name as a plain string and no platform user is made, so a typo
+  leaves the commit attributed to nobody rather than creating a ghost row. Fix it by
+  recreating the commit — but note a duplicate SHA is rejected, so the wrong one persists.
+- **`--added` / `--removed` / `--modified` are repeatable** and all three are sent even when
+  empty. `file_changed_count` is computed by the server.
+- There is **no `update` and no `delete`** for a commit.
+
+### Commit refs — `scm ref`
+
+A ref is the record that says *this commit is on this branch*. Create the commit first.
+
+```bash
+pingcode scm ref create --platform Github --repo acme/pingcode-cli \
+  --sha 96a024347146ebdc5f481f45e6e6871e0c43af5f --branch-id 564587fe700d43b81b080767 --json
+
+pingcode scm ref list --platform Github --repo acme/pingcode-cli --branch-id 564587fe700d43b81b080767 --json
+pingcode scm ref get 5e451b7dd704c212f7de8b4f --platform Github --repo acme/pingcode-cli --json
+```
+
+- **`--branch-id` is required on `list`, and it takes an id, not a name.** The API's list
+  requires the referenced entity, so **there is no way to list every ref in a repository**
+  — you enumerate one branch at a time. Get the id from `scm branch list --json`.
+- **`--sha` must name a commit that already exists** in PingCode, or you get exit 5
+  (`'commit'资源不存在`). Order: `scm commit create` → `scm ref create`.
+- Only branches can be referenced; the CLI sends `meta_type=branch` for you.
+- There is **no `update` and no `delete`**, and a ref outlives the branch it points at (see
+  the branch delete warning above).
+
+### Pull requests — `scm pr`
+
+```bash
+pingcode scm pr list --platform Github --repo acme/pingcode-cli --json
+pingcode scm pr list --platform Github --repo acme/pingcode-cli --number 42 --json
+pingcode scm pr list --platform Github --repo acme/pingcode-cli --work-item-id 5edca524cad2fa112b06105c --json
+pingcode scm pr list --platform Github --repo acme/pingcode-cli --all --limit 200 --json
+
+pingcode scm pr get 594587fe700d43b81b080789 --platform Github --repo acme/pingcode-cli --json
+
+pingcode scm pr create --platform Github --repo acme/pingcode-cli \
+  --title "feat(auth): #PLM-001 add login" --number 42 --creator octocat \
+  --target-branch-id 564587fe700d43b81b080776 --source-branch-id 564587fe700d43b81b080767 \
+  --status open --work-item PLM-001 --json
+
+pingcode scm pr update 594587fe700d43b81b080789 --platform Github --repo acme/pingcode-cli \
+  --status merged --merged-at 2026-08-03T10:00:00Z \
+  --merged-commit-sha 96a024347146ebdc5f481f45e6e6871e0c43af5f --merged-by octocat --json
+```
+
+Rules that will bite otherwise:
+
+- **A pull request is addressed by its id, and *found* by its number.** scm has no
+  `identifier` and no `short_id` anywhere, and the detail path takes the 24-hex id only.
+  So `--number` is a **list filter**, and `pr get|update` take the id: run
+  `pingcode scm pr list --number 42 --json` and read `values[0].id`. The CLI does not
+  guess whether what you typed "looks like a number". `--number` is an **exact filter and
+  it really works** (verified live) — unlike `repo list`'s ignored `?name=`, so this
+  discovery path is reliable; an unused number returns zero rows.
+- **`--status` is required by the API on every patch**, not just when you want to change
+  it. Omit it and the CLI reads the pull request first and re-sends its *current* status,
+  which costs one extra GET; pass `--status` and it does not. There is no way to send a
+  patch without a status (verified live: `100008 'status'是必填字段`). The patch is
+  genuinely partial otherwise — counts and work-item links you do not mention survive it.
+- **Both `--target-branch-id` and `--source-branch-id` are required on create**, and both
+  take **branch ids**, from `scm branch list --json`. They must also **differ** (the
+  server refuses `source == target`). The published API reference marks the source branch
+  optional; the live API rejects a create without it, so the CLI requires it and you get
+  exit 2 naming the flag instead of a server error.
+- **`--merged-at`, `--merged-commit-sha` and `--merged-by` become required when
+  `--status merged`.** The server enforces that, not the CLI, so expect exit 7 rather than
+  exit 2 if you forget one (verified live: `100212`).
+- ⚠️ **`--creator` and `--merged-by` CREATE a 托管平台用户 if the name is unknown.** They are
+  git usernames matched against 托管平台用户 rows by name, and an unrecognised one is
+  **upserted**, exactly as branch `--sender` is. scm has **no user DELETE**, so a typo
+  leaves a permanent ghost identity in the tenant. Create or confirm the identity first
+  with `scm platform-user list --name <username>`. (A commit's `--committer` is the one
+  exception — it creates nothing.)
+- **The six `--*-count` flags are yours to report.** Nothing server-side recomputes them.
+  Note that the server stores `0` for any count you do not send, so unlike `merged_at`
+  (which stays absent) an omitted count is indistinguishable from `0` once written.
+- **`--work-item` takes an identifier (`PLM-001`) and an unknown one is silently
+  ignored**, exactly as on a branch: the response's `work_items` array is the only
+  evidence, the CLI warns on stderr about identifiers that did not link, and the exit code
+  stays 0. On `update` it **REPLACES** the whole link set. `--work-item-id` on `list` is a
+  different thing — a work item **id**, and an unknown one is an error (exit 5), not an
+  empty result.
+- **`number` must be unique in the repository**; a duplicate is a server-side conflict
+  (exit 7), not a silent overwrite.
+- **A missing pull request exits 5**, on `get`, on `update`, and on `review create`.
+
+### Code reviews — `scm review`
+
+⚠️ **`scm review` is not `pingcode api … /v1/reviews`.** Two unrelated resources share
+the word:
+
+| | `scm review` (this section) | `/v1/reviews` (generic layer only) |
+|---|---|---|
+| what | 代码评审: one review event on one pull request | 评审: a polymorphic review object with contents |
+| addressed by | platform + repository + pull request | `principal_type` + `pilot_id` |
+| used by | git / CI write-back | 需求 and 用例 review flows |
+| reachable as | `pingcode scm review …` | `pingcode api GET /v1/reviews …` |
+
+Their ids are not interchangeable. If you are recording "someone approved PR #42", you
+want this section.
+
+```bash
+pingcode scm review list --platform Github --repo acme/pingcode-cli \
+  --pr-id 594587fe700d43b81b080789 --json
+
+pingcode scm review get 524587fe700d43b81b080988 --platform Github --repo acme/pingcode-cli \
+  --pr-id 594587fe700d43b81b080789 --json
+
+pingcode scm review create --platform Github --repo acme/pingcode-cli \
+  --pr-id 594587fe700d43b81b080789 \
+  --status approved --reviewer octocat --submitted-at 2026-08-03T10:00:00Z \
+  --description "Review has approved" \
+  --html-url 'https://github.com/acme/pingcode-cli/pull/42#pullrequestreview-384383294' --json
+
+pingcode scm review update 524587fe700d43b81b080988 --platform Github --repo acme/pingcode-cli \
+  --pr-id 594587fe700d43b81b080789 --status request_changes --json
+```
+
+- **`--pr-id` is required on every leaf, and it takes an id, not a number.** A review is
+  addressed three parents deep, and **there is no repository-wide or organisation-wide
+  review list** — you enumerate one pull request at a time, exactly as with `scm ref` and
+  branches. Get the id from `scm pr list --number <n> --json`.
+- ⚠️ **A wrong `--pr-id` reads as "no reviews", not as an error.** `review list` against a
+  pull request that does not exist returns an **empty list with exit 0** — the pull request
+  is the one scm parent whose absence a child *list* does not report (a bad `--platform` or
+  `--repo` does fail). So an empty result means "either no reviews, or that pull request is
+  not there". Confirm with `scm pr get <id>` if it matters. `review get` and
+  `review create` do fail properly, with exit 5.
+- ⚠️ **`--reviewer` CREATES a 托管平台用户 if the name is unknown**, exactly like
+  `pr create --creator` and `branch create --sender`, and platform users cannot be
+  deleted. Confirm the username first with `scm platform-user list --name <username>`.
+- **A missing review exits 5** — including a real review id passed with the wrong
+  `--pr-id`, because the review genuinely is not at that address.
+- **`--submitted-at` is required on create.** A review carries **no server-assigned
+  timestamp at all** — no `created_at`, no `updated_at` — so the time is yours to supply.
+  On `update` it is optional like everything else: this PATCH has no mandatory field
+  (unlike `scm pr update`).
+- **`--status` is `comment` / `approved` / `request_changes`.** A value outside the enum
+  is rejected by the server (exit 7), not by the CLI.
+- **`--reviewer` is a git username**, attribution by name again.
+- **`--html-url` is optional**; without it PingCode shows no jump link back to the
+  hosting platform. **Quote it** in a shell — review URLs contain a `#`.
+
+### Name → id
+
+```bash
+pingcode resolve scm-platform Github --json
+pingcode resolve scm-repo pingcode-cli --parent 68393e8b47512a5d5d4e5b55 --json
+```
+
+Both are cached for 24 h under `~/.pingcode/cache/`; pass `--no-cache` when a platform was
+reconfigured. `--platform <name|id>` resolves by name; `--platform-id <id>` is sent verbatim
+with no lookup, and the two are mutually exclusive (exit 2).
+
+### What cannot be deleted, and why nothing is `replace`d
+
+**`scm branch delete` is the only delete in this module.** For everything else — platforms,
+git identities, repositories, commits, refs, **pull requests and code reviews** —
+**no DELETE exists upstream**. Nothing you create there can ever be removed through the API, so
+mark test data clearly and check spellings before you write. A mistyped pull request title
+can be patched; a pull request created against the wrong repository or with the wrong
+`--number` **cannot be withdrawn**. `--owner-name` and branch `--sender` are the two flags
+that can create a row by accident.
+
+**`PUT` is deliberately not offered anywhere.** Five scm families document a `PUT` that
+replaces the whole record and blanks every field you did not send, and this API never
+documents what clearing a field does. Use `update` (PATCH). **Full replacement of a pull
+request or a code review therefore goes through `pingcode api PUT`** — and there, omitting
+a field is not "leave it alone", it is a wipe. If you truly want a full replacement, ask
+for it explicitly through the escape hatch:
+
+```bash
+pingcode api PUT /v1/scm/products/68393e8b47512a5d5d4e5b55 \
+  --set name=Github --set type=github
+
+pingcode api PUT /v1/scm/products/<platform>/repositories/<repo>/pull_requests/<pr> \
+  --set title=… --set creator_name=… --set source_branch_id=… --set target_branch_id=… --set status=open
+```
+
+See [`api.md`](api.md).
+
+⚠️ **代码分支 has no `PUT` upstream at all** — its fifth verb is `DELETE`, which is why
+`scm branch delete` exists while its siblings have none. So there is nothing missing to
+"complete": do not add a `scm branch replace`, and do not expect `scm platform delete` to
+appear. All six documented scm families are now refined commands; the only part of
+`/v1/scm/**` that is generic-layer-only is those five `PUT`s.
+
+### Errors you should expect
+
+| Situation | Exit |
+|---|---|
+| `--platform` missing, or given together with `--platform-id` | 2 |
+| a name matches nothing, or matches two repositories | 2 |
+| `update` with no field to change | 2 |
+| `--private maybe` | 2 |
+| the token lacks `pcp:*:devops:code` | 4 |
+| a platform / repository / identity / branch / commit / ref id does not exist | 5 |
+| `scm ref create` names a `--sha` or `--branch-id` that does not exist | 5 |
+| an abbreviated SHA passed to `scm commit get` | 5 |
+| `--branch-id` missing on `scm ref list` | 2 |
+| `scm branch delete` without `--yes` | 2 |
+| deleting the **default** branch | 7 |
+| a `--type` outside the enum, or a duplicate name / SHA / ref | 7 |
+| `scm ref list` for a branch that was deleted (server error) | 7 |
+| `--pr-id` missing on any `scm review` leaf | 2 |
+| a non-numeric `--number`, or a non-date `--merged-at` / `--submitted-at` | 2 |
+| a pull request or code review id that does not exist | 5 |
+| `--status merged` without `--merged-at` / `--merged-commit-sha` / `--merged-by` | 7 |
+| a `--status` outside its enum, or a duplicate pull request `--number` | 7 |

package/skills/pingcode/modules/ship.md

@@ -0,0 +1,197 @@
+# 产品管理 (ship) — `product`
+
+> 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 ship command surface plus the ship-specific traps.
+
+### Products — 产品管理
+
+A **product** (产品) is ship's parent scope, the way a project is pjm's. Resolve it first: every other
+ship id is scoped to it.
+
+```bash
+pingcode product list --json
+pingcode product list --keywords sales --json
+pingcode product get SLC --json          # name, identifier such as SLC, or id
+```
+
+`--keywords` searches the **name only** — the identifier is not searchable server-side, so the CLI
+matches it client-side over the full list. There is no `product create`/`update`/`delete`: ship has no
+product DELETE at all, and `PATCH` only edits three cosmetic fields.
+
+### `product meta` — mandatory before writing an idea or ticket
+
+```bash
+pingcode product meta idea-states       --product SLC --json
+pingcode product meta idea-priorities   --product SLC --json
+pingcode product meta idea-suites       --product SLC --json
+pingcode product meta idea-properties   --product SLC --json
+pingcode product meta idea-plans        --product SLC --json
+pingcode product meta members          --product SLC --json
+pingcode product meta ticket-states     --product SLC --json
+pingcode product meta ticket-priorities --product SLC --json
+pingcode product meta ticket-types      --product SLC --json
+pingcode product meta ticket-channels   --product SLC --json
+pingcode product meta ticket-properties --product SLC --json
+```
+
+`product meta members` is the **only** valid source of `--assignee` values for ideas and tickets —
+the organisation directory is not, because a user who is not a member of the product cannot be
+assigned. `product meta idea-properties` / `product meta ticket-properties` are the only source of `--set` keys and,
+for select-typed properties, of the option ids you must send instead of the display label.
+`product meta idea-plans` is the only source of `plan_id` values — read the 需求排期 section below
+before you use the word "plan" anywhere near this API.
+
+### Requirements 需求 — `product idea`
+
+```bash
+pingcode product idea list --product SLC --json
+pingcode product idea list --product SLC --state 待评审 --assignee zhangsan --json
+pingcode product idea list --product SLC --keywords sso --page-size 20 --page 0 --json
+pingcode product idea list --product SLC --all --limit 200 --json
+
+pingcode product idea get SLC-1 --json                # identifier, id, or a pasted idea URL
+
+pingcode product idea create --product SLC --title "Single sign-on" --dry-run --json
+pingcode product idea create --product SLC --title "Single sign-on" \
+  --assignee zhangsan --priority P1 --suite "客户端 / 登录" --json
+
+pingcode product idea update SLC-1 --title "Single sign-on (v2)" --json
+pingcode product idea update SLC-1 --state 开发中 --json
+pingcode product idea update SLC-1 --set 需求类型=5cb7e763fda1ce4ca0010002 --json
+```
+
+`product idea list` is `POST /v1/ship/ideas/search` — the plain list endpoint cannot filter by assignee, date
+or custom property, so the CLI never uses it. Note there is **no `--type`** anywhere on `idea`: ship
+states are scoped to the product alone, which `--product` (or, on `update`, the idea itself) already
+supplies.
+
+### State history 流转记录 — `product idea history`
+
+```bash
+pingcode product idea history list SLC-1 --json
+pingcode product idea history list SLC-1 --all --json
+pingcode product idea history get SLC-1 6a1cd3670faf359d7447bf37 --json
+```
+
+**State changes only.** A title, assignee, priority or 排期 change is *not* here — that is
+`pingcode product idea activity`, the free-form audit feed. Every requirement has exactly one row
+from creation, printed with `FROM` as `(new)`. Read-only upstream (a POST or DELETE on this path
+answers HTTP 405), and the endpoint accepts `?name=`, `?state_id=` and `?keywords=` while **ignoring
+all three** — which is why the CLI offers no filter flag here. Filter client-side after `--all`.
+
+Unlike some sibling lists in this API, this one validates its parent: an empty result really means
+"this requirement has no rows", and a bad reference exits 5. A history id that belongs to a
+*different* requirement also exits 5 — the (requirement, record) pair is the address, and the CLI
+resolves your `SLC-1` to an id first because the raw endpoint accepts nothing else.
+
+### Requirement schedules 需求排期 — `product plan`
+
+```bash
+pingcode product plan list --product SLC --json
+pingcode product plan list --product SLC --all --limit 200 --json
+pingcode product plan get 6a1c53580faf359d7447b68e --product SLC --json
+```
+
+**Read-only, and permanently so**: `POST`, `PATCH` and `DELETE` on the schedule path all answer
+HTTP 405, so there is nothing to reach through `pingcode api` either — schedules are created in the
+web UI. There is **no filter flag**, for the same reason as above: the endpoint documents none and an
+undeclared `?name=` changed nothing when tried.
+
+`product plan list` returns the full record (name, assignee, start, end); `product meta idea-plans`
+returns the same rows as `{id, name}` only, because ship answers **two structures for one resource**
+depending on the endpoint. Use `plan list` to read a schedule, `meta idea-plans` to pick an id for
+`product idea update --plan-id`.
+
+A schedule id that does not exist exits **7**, not 5 — read the message rather than the code. The
+vendor code is the same one an idea PATCH answers for an unknown `--plan-id`, and whether it can
+additionally mean "exists, but in another product" has not been measurable on any tenant reached so
+far (no tenant has had a single 排期 yet).
+
+### Tickets 工单 — `product ticket`
+
+```bash
+pingcode product ticket list --product SLC --json
+pingcode product ticket list --product SLC --type 故障 --state 待处理 --json
+pingcode product ticket list --product SLC --channel 邮件 --all --limit 200 --json
+
+pingcode product ticket get SLC-7 --json
+
+pingcode product ticket create --product SLC --type 故障 --title "Cannot log in" --dry-run --json
+pingcode product ticket create --product SLC --type 故障 --title "Cannot log in" \
+  --assignee zhangsan --priority P1 --channel 邮件 --json
+
+pingcode product ticket update SLC-7 --title "Cannot log in (iOS)" --json
+pingcode product ticket transition SLC-7 --state 处理中 --json
+```
+
+`--type` is **required** on `product ticket create` — `type_id` is a required body field, which is the one
+place ship demands a lookup (`pingcode product meta ticket-types --product SLC`) before a write can even be
+attempted. `--channel` can only be set at create time; there is no way to change it afterwards.
+
+## 4b. Ship rules that will bite you
+
+These are on top of §4, which still applies. Ship is a different module with the same machinery, and
+almost every difference is a trap.
+
+1. **Resolve the product first, and scope everything to it.** A product is to ship what a project is
+   to pjm. `state_id`, `priority_id`, `suite_id`, `type_id`, `channel_id`, the `properties` keys and
+   the assignable people are **all product-scoped**. They frequently *look* org-global — the same
+   priority id `P0` appears under several products — but the API requires `product_id` on every
+   lookup, so never carry an id from one product to another.
+2. **`--assignee` must be a product member.** `pingcode product meta members --product <p>` is the
+   only valid candidate set; the organisation directory (`settings users`) is not, and a non-member is
+   rejected.
+3. **`--state <name>` needs no companion flag here.** Unlike pjm, ship states hang off the product
+   alone, so there is no `--type` on `idea` at all, and `--type` on `ticket` is a real field being
+   written, not a lookup aid. `--state` and `--state-id` remain mutually exclusive.
+4. **Reads go through `search`.** `product idea list` and `product ticket list` are `POST …/search`. The plain list
+   endpoints exist but cannot filter by assignee, date or custom property, so the CLI never uses
+   them. Search takes **one operator per field and has no `$and`/`$or`**; multiple filters are
+   AND-ed. There is still no sorting anywhere.
+5. **No state change is refused locally — the server decides, and a ticket refusal is explained.**
+   - `pingcode product ticket transition` and `product ticket update --state` send the PATCH. If the server refuses
+     it, the error `message` names the product's configured states, the current state and — when
+     the state plan can be read — **the states reachable from the current one**. Read it from
+     `message`: `--json` errors are `{kind,message,code,exit}` and carry no hint.
+   - Want to know before you write? `product ticket transition <t> --state <s> --dry-run` prints the
+     reachable set on stderr and sends nothing.
+   - `pingcode product idea update --state` gets the configured states on rejection but never a reachable
+     set: ship publishes no idea state-flow endpoint at all.
+   - The CLI does **not** refuse a transition on its own (the one exception: moving a ticket to the
+     state it is already in, which is exit 2). The server refuses atomically with no state change,
+     so a local check saves nothing — and a mis-identified state plan would otherwise block a legal
+     move with no escape hatch. Expect the server's exit code, not exit 2, for an illegal target.
+6. **`--set key=value` sends the value verbatim, and select properties want option ids.** For a
+   `select`-typed property the API expects the option's `_id`, not the label you see in the UI —
+   the docs' own examples only show text properties, which is the trap. Run
+   `pingcode product meta idea-properties --product <p>` (or `ticket-properties`): it prints each key and
+   its `label=option_id` pairs. `properties` **replaces**, it never merges.
+7. **Nothing in ship can be deleted.** There is no DELETE for products, ideas or tickets, and
+   `is_archived` / `is_deleted` are read-only. A test artifact you create is permanent — mark it in
+   the title (for example `[CLI smoke] …`) before you create it, not after.
+8. **An identifier works on the resource, and nowhere below it.** `GET /v1/ship/ideas/<x>` accepts
+   the id, the 8-char `short_id` a pasted URL ends in **and** the human `SLC-1` — all three answered
+   200 live, correcting an earlier note here that said none of them did. But every *sub-collection* —
+   `history`, and the `relation` / `comment` / `attachment` / `activity` families — takes the 24-hex
+   id only and answers HTTP 404 `资源路径错误` for anything else. The CLI therefore resolves your
+   reference to an id first (one extra request when the identifier has a dashed product prefix, or a
+   `search` hop when it does not), so all four forms work at the command layer.
+9. **`--suite` filtering on `product idea list` is undocumented.** The API lists `suite.id` as neither
+   filterable nor unfilterable, so an empty result proves nothing. The CLI warns when you use it.
+10. **"Plan" is three unrelated things, and only one of them is a 排期.** Getting this wrong is the
+    fastest way to hand a valid id to the wrong endpoint and get a not-found you cannot explain:
+    | You mean | Command | What it is |
+    |---|---|---|
+    | 需求排期 requirement schedule | `pingcode product plan list --product <p>` | a named window a requirement is planned into; `idea update --plan-id` takes its id |
+    | 测试计划 test plan | `pingcode testhub plans list --library <l>` | a test cycle in a test library, with its own states and runs |
+    | 配置方案 configuration scheme | `pingcode api GET /v1/ship/ticket_state_plans` | a *scheme* — a reusable bundle of states/properties/transitions bound to products |
+    They share no ids and no vocabulary. The 排期 is the only one that is read-only for the whole
+    surface, and the configuration schemes are the only one with **no leaf you can type**. Note that
+    "no leaf" is not "not wired": `ticket_state_plans` and its `ticket_state_flows` child *are*
+    called, by the resolver cache, so that `ticket transition` can tell you which states are
+    reachable when the server refuses one. So they count towards README's 158 refined endpoints even
+    though no command bears their name — which is why that table is labelled *the refined layer*.
+11. **Tags cannot be set through the API** on ideas or tickets, and `submitter_id` on a ticket is
+    silently ignored under a client-credentials token — the ticket is attributed to the token owner
+    with no error. The CLI exposes neither.