@mu-cabin/coding-cli 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mu-cabin/coding-cli",
+  "version": "0.1.0",
+  "description": "Agent-first CLI for operating a CODING instance over its OpenAPI surface.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "coding": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "generated/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:spec": "tsx scripts/build-spec.ts",
+    "regen": "pnpm build && pnpm build:spec",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "clean": "rm -rf dist"
+  }
+}

package/skills/coding/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: coding
+version: 0.1.0
+description: "Operate a self-hosted or SaaS CODING DevOps platform via the `coding` CLI — a generic OpenAPI passthrough over all 429 actions / 17 categories, with per-domain playbooks in references/ that load on demand. Use whenever the user mentions CODING, the instance host (e.g. coding.example.com), or any CODING resource — projects/项目, programs/项目集, issues 事项/迭代, merge requests 合并请求, CI 流水线 & CD 部署, 制品/artifacts, test 测试, Wiki, 权限, org/部门/成员, service-hook 服务钩子, file upload/导出 — even without naming the platform."
+metadata:
+  requires:
+    bins: ["coding"]
+  cliHelp: "coding --help"
+---
+
+# coding
+
+Drive a CODING instance over its OpenAPI surface. The CLI is a **generic passthrough**:
+one `coding call <Action>` invokes any of the 429 actions, with a bundled action index for
+discovery, validation, and safety. Always pass `--json` when you need to parse output.
+
+For any task in a specific domain (issues, code/MRs, CI, CD, deploys, artifacts, wiki, permissions,
+…), read the matching playbook in `references/` **before** falling back to the generic
+search→schema→call recipe below — see the router in §9. The playbook front-loads the right action
+names, identifier resolution, enums, and gotchas, so you avoid failed calls and wasted context.
+Each builds on this page (bootstrap, exit codes, the exit-10 gate) and doesn't repeat it, so skim
+this file first, then load only the one playbook your task needs.
+
+## 1. Bootstrap (config + token)
+
+1. **Config** (**required** — the built-in default `coding.example.com` is a non-working placeholder):
+   point the CLI at the real instance with `coding config init --base-url <url>` (writes
+   `~/.coding/config.json`), the `--base-url` flag, or `CODING_API_BASE`. `coding config show` reports
+   the resolved base URL and whether a token is present.
+2. **Token** — CODING uses a static **personal access token** (`Authorization: token <…>`). There is
+   no device-flow login. The token is a secret:
+   - **Never** accept a token pasted into chat, never put it in argv, never echo it.
+   - Hand the user this to run **in their own terminal**: `coding auth login` (hidden prompt), or
+     `coding auth login --token -` to pipe it. `CODING_TOKEN` env var also works and overrides the file.
+3. **Verify**: `coding auth status --json` → current user. Run this first when unsure.
+
+> **Token scope is the #1 source of friction.** A valid token only reaches the actions its scope
+> covers (see §5). `UnauthorizedOperation` means "expand the token's scope", **not** "wrong token".
+
+## 2. Discovery recipe — search → schema → call
+
+Don't guess action names; the index knows 429 of them. The server hides unknown actions behind a
+scope error, so it will **not** tell you a name is mistyped — the CLI's validation will.
+
+```bash
+coding actions --search <keyword> --json        # find by name/summary/description
+coding actions --category "08-项目协同" --json    # filter by category
+coding categories --json                        # the 17 categories
+coding schema <Action> --json                   # params (name/type/required), response, errors, risk
+```
+
+`coding schema <Action>` is the source of truth for an action's params, response shape, and errors —
+read it before calling an action you haven't used.
+
+If an action seems missing or stale, refresh the bundled index from the live spec:
+`coding update` (or `coding update --dry-run` to preview the added/removed diff first).
+
+## 3. Call recipe
+
+```bash
+# canonical: JSON body (handles nested objects & arrays)
+coding call CreateIssue --data '{"ProjectName":"demo","Type":"REQUIREMENT","Name":"…","Priority":"1"}' --json  # Priority "0"低 "1"中 "2"高 "3"紧急
+coding call DescribeIssueList --data @body.json --json
+echo '{…}' | coding call <Action> --data - --json
+
+# convenience: flat params, coerced by index type (Id=1 → number, Foo=true → bool)
+coding call DescribeIssue --param ProjectName=demo --param IssueCode=42 --json
+
+# keep context lean: project just the fields you need, cap arrays
+coding call DescribeIssueList --param ProjectName=demo --param IssueType=ALL \
+  --select 'IssueList[].Code,IssueList[].Name' --limit 20 --json
+```
+
+- `--param` merges on top of `--data`. `--select` paths are relative to the response `data`
+  (dot notation, `[]` to map an array, `[n]` to index). `--limit N` truncates arrays.
+- Validation rejects unknown action / missing-required / unknown-param by default. If your instance
+  has an action the public spec lacks, add `--force` (alias `--no-validate`) to send anyway.
+
+## 4. Output & exit codes
+
+`--json` success: `{ ok:true, action, requestId, data }` (the server `Response` minus `RequestId`).
+Error: `{ ok:false, action?, requestId?, error:{ code?|type?, message, hint?, risk? } }`.
+**Parse the envelope yourself** — don't assume `jq`/`python` exist.
+
+| exit | meaning | what to do |
+|---|---|---|
+| 0 | ok | — |
+| 2 | usage | fix CLI args |
+| 3 | auth (`AuthFailure`) | token missing/invalid → user re-runs `coding auth login` |
+| 4 | not-found | resource (or action not in index for `schema`) |
+| 5 | remote/network | retry later / inspect `error.message` |
+| 7 | config invalid | malformed config file → fix it or re-run `coding config init` (a *missing* config is non-fatal: defaults apply) |
+| 8 | forbidden (`UnauthorizedOperation`/`OperationDenied`) | **expand token scope** for this action |
+| 9 | rate-limit (`RequestLimitExceeded`) | back off & pace — CLI does **not** auto-retry (30 req/s/team/action) |
+| 10 | confirmation required | destructive action — see §6 |
+| 11 | validation | fix params, or `--force` to bypass |
+
+## 5. Error playbook
+
+- **exit 3 `AuthFailure`** — "User not found, authorization invalid": the token is bad/absent. Ask the
+  user to re-run `coding auth login`. Do not retry blindly.
+- **exit 8 `UnauthorizedOperation`** — token valid, scope insufficient. Tell the user which action
+  needs which scope and to mint a token with that scope in their instance's token settings. Do **not**
+  run `auth login` to fix this (the token isn't wrong).
+- **exit 9 `RequestLimitExceeded`** — pause and pace requests; never tight-loop retries.
+- **exit 11 validation** — usually a typo or a missing required param; re-check with `coding schema`.
+
+## 6. Safety — the exit-10 confirmation gate
+
+Destructive actions (`Delete*`, `Remove*`, `Disable*`, `Revoke*`, `Reset*`, `Clear*`, `Stop*`,
+`Terminate*`, `Unbind*`, …) are gated. Calling one without `--yes` exits **10** with
+`error.type == "confirmation_required"` and an `error.risk` block.
+
+**Protocol:**
+1. See exit 10 + `confirmation_required` → do **not** treat it as a normal error.
+2. Show the user `error.risk.action` and the key params; state plainly it's destructive; wait for
+   explicit approval.
+3. Approved → re-run the **same argv with `--yes` appended**.
+4. Declined → stop. Never silently add `--yes`, never rewrite params to dodge the gate.
+
+Preview anything first with `--dry-run` (prints the full request, redacted token, **does not** trip
+the gate and **does not** send). Use it to show the user a destructive call before running it.
+
+> Actions absent from the index with an **unrecognized verb** are gated as destructive (fail-safe),
+> since the CLI has no risk metadata for them. Combine `--force` (to bypass validation) with `--yes`
+> (after user approval) only when you're sure such an action is safe.
+
+## 7. Scope notes for the agent
+
+- Write/delete only after the user's intent is explicit; prefer `--dry-run` to confirm shape.
+- Resolve identifiers before mutating: resolve the **project** first (§8), then the resource key
+  (e.g. the issue code before `ModifyIssue`/`DeleteIssue`).
+- Large lists: always pair list calls with `--select`/`--limit` to protect your context window.
+
+## 8. Resolving a project — the near-universal first step
+
+Almost every domain action needs a project identifier, and there are three — don't mix them up:
+- **`ProjectId`** (numeric) — primary key for most writes/reads (modify, members, labels, delete).
+- **`ProjectName`** (string) — the project's **`Name`** *slug* (as used in URLs, e.g. `demo-project`),
+  **not** its `DisplayName` (the UI label). Used by name-based reads.
+
+Resolve one before mutating, then cache it for the session:
+
+```bash
+# name slug → ProjectId (+ the rest)
+coding call DescribeProjectByName --param ProjectName=demo-project \
+  --select 'Project.Id,Project.Name,Project.DisplayName' --json
+# the current user's projects — UserId from `coding auth status` / DescribeCodingCurrentUser
+coding call DescribeUserProjects --param UserId=254 \
+  --select 'ProjectList[].Id,ProjectList[].Name,ProjectList[].DisplayName' --json
+# team-wide paged list (optional ProjectName filter; QueryArchived to include archived)
+coding call DescribeCodingProjects --param PageNumber=1 --param PageSize=50 \
+  --select 'Data.ProjectList[].Id,Data.ProjectList[].Name,Data.ProjectList[].DisplayName' --json
+```
+
+`references/project.md` covers the rest of this category (create/modify/archive, members & roles,
+labels, announcements).
+
+## 9. Domain playbooks (read the matching one on demand)
+
+Each API category has a curated playbook under `references/` — the identifiers to resolve first, the
+common recipes, condition keys, and gotchas, all ground-truthed against the action index. **For a task
+in any domain below, read that file before improvising with the generic recipe** — it's the curated
+shortcut. Read **just** the one file (not all of them): it assumes everything on this page and adds
+only the domain specifics. Most playbooks need a project identifier first — resolve it via §8.
+
+Each playbook deliberately **omits the param dictionary**: run `coding schema <Action>` for the
+authoritative param/response/error list. The files instead give you what `schema` can't — which
+action to call, runnable examples, value encodings and enums, multi-step sequencing, and the spots
+where the spec itself is misleading.
+
+| Category | Read | Use it for |
+|---|---|---|
+| 项目协同 / Issues (08) | `references/issues.md` | 事项/需求/缺陷/任务, 迭代/sprints, 版本/releases, comments, work-hours |
+| 代码托管 / Code (09) | `references/code.md` | repos, branches, files, commits, tags, merge requests / code review |
+| 持续集成 / CI (10) | `references/ci.md` | 构建计划/build plans, trigger builds, build logs, debug a failed build |
+| 持续部署 / CD (11) | `references/cd.md` | deploy applications, 部署流程, trigger/cancel deploys, host groups, deploy metrics |
+| 制品仓库 / Artifacts (12) | `references/artifacts.md` | Docker/Maven/npm/… packages & versions, download URLs, release/forbid, 授信 |
+| 项目 / Project (04) | `references/project.md` | resolve/create/modify projects, members & roles, labels, announcements (foundational) |
+| 测试管理 / Test (15) | `references/test.md` | 测试计划/runs, 测试用例, record results, link defects, test reports |
+| 权限 / Permissions (03) | `references/permissions.md` | 权限组/policies, 用户组, grant/revoke on a resource, inheritance |
+| 组织和成员 / Org (02) | `references/org.md` | team members, lock/remove, 部门 org tree, department heads, LDAP sync |
+| Wiki (13) | `references/wiki.md` | wiki page tree, read/create/edit, move/rename, recycle bin, ZIP import |
+| Service Hook (06) | `references/servicehook.md` | webhooks/robots (WeCom/DingDing/FeiShu/Jenkins), test/resend deliveries |
+| 项目集 / Program (05) | `references/program.md` | portfolios grouping projects, program membership & permissions |
+| 文件网盘 / Files (14) | `references/files.md` | upload files / issue attachments (presign → upload → register), folders |
+| 导出任务 / Export (17) | `references/export.md` | export wiki/pages to a ZIP of Markdown (async create → start → poll) |
+| 团队·关联资源·其他 (01/07/16) | `references/admin.md` | current user & team info, resource reference graph, 汉字→拼音 |

package/skills/coding/references/admin.md

@@ -0,0 +1,65 @@
+# coding-admin
+
+A curated playbook bundling three tiny categories — **团队 (01)**, **关联资源 (07)**, **其他 (16)** —
+5 actions, **all read-only** (no exit-10 gate).
+
+## 1. Current user & team (团队)
+
+```bash
+# the logged-in user (no params). NOTE: the CLI already wraps this as `coding auth status` / `coding whoami`
+#   — prefer those for an identity check; call the action directly only when you want the raw User object.
+coding call DescribeCodingCurrentUser --select 'User.Id,User.Name,User.GlobalKey,User.Email,User.TeamId' --json
+
+# team / instance info (no params) → wrapped under Data
+coding call DescribeTeam --select 'Data.Id,Data.Name,Data.TeamHost,Data.TeamOwner.Name' --json
+```
+
+`DescribeCodingCurrentUser` → top-level **`User`**; `DescribeTeam` → **`Data`** (a `TeamData` with
+`TeamHost`, `Name`, `Id`, `TeamOwner`). Neither takes parameters.
+
+## 2. Resource reference graph (关联资源)
+
+Both actions take the **same three params** and return `Resource[]` (top-level array of
+`{Scope, Resource}`). They describe the two directions of the link graph for one resource:
+
+- **`DescribeResourceReferencesCiting`** (引用) — resources that the given resource **references**
+  (its outbound links).
+- **`DescribeResourceReferencesCited`** (被引用) — resources that **reference** the given resource
+  (inbound backlinks).
+
+```bash
+# what does resource X reference? (ScopeType: 1=project, 2=team; ScopeId = that project/team id)
+coding call DescribeResourceReferencesCiting --data '{"ScopeType":1,"ScopeId":341,"ResourceCode":"<code>"}' \
+  --select 'Resource[].Resource.Title,Resource[].Resource.ResourceType,Resource[].Resource.ResourceCode,Resource[].Scope.ScopeName' --json
+
+# what references resource X?
+coding call DescribeResourceReferencesCited --data '{"ScopeType":1,"ScopeId":341,"ResourceCode":"<code>"}' \
+  --select 'Resource[].Resource.Title,Resource[].Resource.ResourceType,Resource[].Scope.ScopeName' --json
+```
+
+> The Citing/Cited direction above is the natural reading of 引用/被引用, but since both take identical
+> params, **confirm the direction against the returned data** (each item's `Scope` tells you which side
+> the listed resource sits on) before relying on it.
+
+## 3. Chinese → pinyin (其他)
+
+```bash
+# Heteronym=true returns all readings for polyphonic chars; Style is the output style (e.g. NORMAL).
+coding call DescribePinyin --data '{"Value":"学生","Heteronym":true,"Style":"NORMAL"}' \
+  --select 'Data.Value,Data.Array[].Value' --json
+```
+
+`Data.Value` is the flat pinyin list; `Data.Array[].Value` is the per-character (segmented) readings.
+Useful for computing the `NamePinyin`/sort keys other categories expose as read-only fields.
+
+## 4. Gotchas
+
+- **`DescribeCodingCurrentUser` is what `coding auth status`/`coding whoami` already call** — use the
+  built-in commands for a quick identity/connectivity check; hit the action directly only for the raw
+  `User` fields.
+- **Uneven wrapping**: `DescribeCodingCurrentUser` → top-level `User`; `DescribeTeam` → `Data`;
+  reference reads → top-level `Resource[]`; `DescribePinyin` → `Data`.
+- **`ScopeType` is `1`=project / `2`=team**, and `ScopeId` must be the matching id; `ResourceCode` is
+  the resource's code (not its numeric id). Citing vs Cited is the only difference between the two
+  reference actions — verify the direction against the response.
+- **All read-only** — nothing here mutates, so no `--yes`/exit-10 concerns.

package/skills/coding/references/artifacts.md

@@ -0,0 +1,138 @@
+# coding-artifacts
+
+A curated playbook for the **制品仓库 (12)** category — the 19 artifact-repository actions.
+
+## 1. The identifier hierarchy
+
+Almost every action keys off the same chain — supply the whole path down to the level you're acting on:
+
+- **`ProjectId`** (numeric) + **`Repository`** (the repo *name*, a string) → identify a repository.
+- **`Package`** (name) → a package/image within the repo (e.g. a Docker image name, a Maven artifact).
+- **`PackageVersion`** (name) → one version/tag of that package.
+- **`FileName`** → a specific file inside a version (for download).
+
+**Repository `Type`** is a numeric enum: `1` generic · `2` docker · `3` maven · `4` npm · `5` pypi ·
+`6` helm · `7` composer · `8` nuget · `9` conan · `10` cocoapods · `11` rpm.
+
+> ⚠️ Identifier exceptions:
+> - **`DescribeArtifactRepositoryFileList`** uses **`Project` (the project *name*)** + `Repository`, and
+>   selects artifacts via an **`Artifacts` array** of `{PackageName, VersionName}` objects (passed with
+>   `--data`) — not the flat `ProjectId`/`Package`/`PackageVersion` params.
+> - **`DescribeTeamArtifacts`** and the four **credit (授信)** actions take **no project identifier** at
+>   all. The `ProjectId` chain applies to the per-repo repository/package/version/property actions.
+
+## 2. Discover repositories & packages
+
+```bash
+# repositories in a project (Type optional — filter to e.g. 2 for docker)
+coding call DescribeArtifactRepositoryList --param ProjectId=341 --param PageSize=50 \
+  --select 'Data.InstanceSet[].Id,Data.InstanceSet[].Name,Data.InstanceSet[].Type' --json
+
+# packages / images in a repo (PackagePrefix narrows by name)
+coding call DescribeArtifactPackageList --param ProjectId=341 --param Repository=maven-local --param PageSize=50 \
+  --select 'Data.InstanceSet[].Name,Data.InstanceSet[].LatestVersionName,Data.InstanceSet[].VersionCount' --json
+
+# team-wide artifact search (cross-project); Rule is an optional structured filter
+coding call DescribeTeamArtifacts --param PageSize=50 \
+  --select 'Data.InstanceSet[].Package,Data.InstanceSet[].PackageVersion,Data.InstanceSet[].Repository,Data.InstanceSet[].ProjectName' --json
+```
+
+## 3. Versions, files, downloads, checksums
+
+```bash
+# versions of a package
+coding call DescribeArtifactVersionList --param ProjectId=341 --param Repository=maven-local --param Package=com.demo.app \
+  --select 'Data.InstanceSet[].Version,Data.InstanceSet[].ReleaseStatus,Data.InstanceSet[].Size,Data.InstanceSet[].DownloadCount' --json
+
+# files inside a version (Maven coordinates go in the optional Maven object).
+# NOTE: this action only supports types 1-generic / 3-maven / 4-npm / 5-pypi — NOT docker.
+coding call DescribeArtifactVersionFileList --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --select 'InstanceSet[].Name,InstanceSet[].Size' --json
+
+# temporary signed download URL for one file (Timeout = link TTL in seconds)
+coding call DescribeArtifactFileDownloadUrl --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --param FileName=api-1.2.0.jar --param Timeout=600 --json
+# → response top-level `Url` (a string). Hand the URL to the user; don't try to fetch it through the CLI.
+
+coding call DescribeArtifactChecksums --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --json
+```
+
+## 4. Properties (version metadata)
+
+Properties are name/value pairs attached to a specific `PackageVersion`.
+
+```bash
+coding call DescribeArtifactProperties --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --select 'InstanceSet[].Name,InstanceSet[].Value' --json
+
+# add / modify: PropertySet is an array of {Name,Value} — pass via --data
+coding call CreateArtifactProperties --data '{"ProjectId":341,"Repository":"maven-local","Package":"com.demo.app",
+  "PackageVersion":"1.2.0","PropertySet":[{"Name":"qa-status","Value":"passed"}]}' --json
+coding call ModifyArtifactProperties --data '{"ProjectId":341,"Repository":"maven-local","Package":"com.demo.app",
+  "PackageVersion":"1.2.0","PropertySet":[{"Name":"qa-status","Value":"failed"}]}' --json
+
+# delete: PropertyNameSet is an array of property names (the only exit-10 gated action here — see §6)
+coding call DeleteArtifactProperties --data '{"ProjectId":341,"Repository":"maven-local","Package":"com.demo.app",
+  "PackageVersion":"1.2.0","PropertyNameSet":["qa-status"]}' --yes --json
+```
+
+## 5. Version lifecycle — release & forbid
+
+```bash
+# promote a version to "released"
+coding call ReleaseArtifactVersion --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --json
+
+# block (or unblock) downloading a version — ForbiddenAction ∈ FORBIDDEN | UNFORBIDDEN
+coding call ForbiddenArtifactVersion --param ProjectId=341 --param Repository=maven-local \
+  --param Package=com.demo.app --param PackageVersion=1.2.0 --param ForbiddenAction=FORBIDDEN \
+  --param ForbiddenNote="CVE-2026-1234" --json
+```
+
+> `ForbiddenArtifactVersion FORBIDDEN` instantly stops anyone pulling that version — it's classified
+> `write` (not exit-10 gated), but it's consequential. Confirm the package/version with the user first.
+
+## 6. Repositories & trust (授信) lists
+
+```bash
+coding call CreateArtifactRepository --data '{"ProjectId":341,"RepositoryName":"maven-local","Type":3,
+  "Description":"app jars","AllowProxy":false}' --json   # Type per the §1 enum (3 = maven)
+
+# trust lists (授信清单) — rules for which artifacts are trusted/allowed.
+# DescribeArtifactCreditList enumerates (no params); DescribeArtifactCredit is a DETAIL call (needs an Id).
+coding call DescribeArtifactCreditList --select 'InstanceSet[].Id,InstanceSet[].Name' --json
+coding call DescribeArtifactCredit --param ArtifactCreditId=7 --json
+```
+
+Creating/updating a credit takes **structured `Ranges` and `Rules` arrays** (schema types
+`ArtifactsOpenApiCreateArtifactCreditsRangeData[]` / `ArtifactsOpenApiArtifactCreditsRuleData[]`) — too
+nested to hand-roll blind. Required fields: `CreateArtifactCredit` needs `Name`, `Enabled`, `Ranges`,
+`Rules`; **`ModifyArtifactCredit` additionally requires `Id`**. Get the exact shape from
+`coding schema CreateArtifactCredit` and an existing credit (`DescribeArtifactCredit`), then send via
+`--data @credit.json`. Don't copy the field list as literal JSON — fill in concrete `Ranges`/`Rules`.
+
+## 7. Destructive actions (exit-10 gated)
+
+Only one action in this category is gated: **`DeleteArtifactProperties`** (removes the named properties
+from a version). Follow SKILL.md's protocol — preview with `--dry-run`, get explicit user approval,
+re-run the **same argv with `--yes`**. Note that **deleting/forbidding versions or repos is not exposed
+here**; `ForbiddenArtifactVersion FORBIDDEN` (§5) is the closest to a "remove", and it's reversible via
+`UNFORBIDDEN`.
+
+## 8. Gotchas
+
+- **Supply the full identifier chain.** Most actions need `ProjectId` + `Repository` + `Package` +
+  `PackageVersion` together; a missing level is a validation error (exit 11).
+- **`DescribeArtifactRepositoryFileList` is the odd one out** — `Project` (name) + `Repository`, with an
+  `Artifacts` array of `{PackageName, VersionName}`, not the flat `ProjectId`/`Package`/`PackageVersion`.
+  `DescribeTeamArtifacts` and the credit actions take no project id at all.
+- **`Repository` is the repo name (string), `Type` is the numeric enum** (§1) — don't pass a type string.
+- **List wrappers differ**: the **paged** lists (repository / package / version / team /
+  repository-file) nest the array under `Data.InstanceSet[]`; the **non-paged** lists (properties,
+  credit, version-file, **checksums**)
+  put it at the top level as `InstanceSet[]`. Match your `--select` path accordingly — a wrong wrapper
+  selects nothing. When unsure, run `coding schema <Action>` and check whether the response top level is
+  `Data` or `InstanceSet`.
+- **`DescribeArtifactFileDownloadUrl` returns a `Url` string** — give it to the user; the CLI won't
+  download the bytes for you.

package/skills/coding/references/cd.md

@@ -0,0 +1,103 @@
+# coding-cd
+
+A curated playbook for the **持续部署 (11)** category — the 33 CD actions.
+
+> Note: this is **CODING CD** (deployment). Builds (CI / 构建计划) are a separate category — see `references/ci.md`.
+
+## 1. Identifiers
+
+- **`Application`** — the deployment application **name** (a string); the primary key for most CD ops.
+- **`PipelineName` / `PipelineNameOrId`** — a deploy flow (部署流程) within an application.
+- **`PipelineExecutionId`** — one **execution** of a pipeline; the key to track or cancel a deploy.
+- **`TaskExecutionId`** — one CD task execution (`CreateCdTask` / `DescribeCdTask`).
+
+Flow: find the `Application` → pick a pipeline config → trigger → track the `PipelineExecutionId`.
+
+## 2. Find applications & pipelines
+
+```bash
+coding call DescribeCdApplications --select 'Data.Applications[].Name' --json          # all CD apps (no params)
+coding call DescribeCdApplicationsByProject --param ProjectName=demo \
+  --select 'Data.Applications[].Name' --json                                            # apps bound to a project
+coding call DescribeCdApplication --param Application=payments --json                    # one app's detail
+
+# the deploy flows configured on an application
+coding call DescribeCdPipelineConfigs --param Application=payments \
+  --select 'Data.PipelineConfigs[].Id,Data.PipelineConfigs[].Name' --json
+coding call DescribeCdPipelineConfig --param Application=payments --param PipelineName=deploy-prod --json
+```
+
+`DescribeCdPipelineConfig` returns the flow's full **config** JSON at `Data.PipelineConfig.JsonContent`.
+That is the *pipeline definition*, **not** the trigger payload — don't feed it back into `TriggerJsonContent` (§3).
+
+## 3. Trigger a deploy & track it
+
+```bash
+# TriggerJsonContent is a JSON *string* of trigger PARAMETERS (artifact/version/build params) — distinct
+# from the pipeline config JSON. Get its shape from the UI's "trigger" dialog; an empty object runs defaults.
+coding call TriggerCdPipeline --data '{"Application":"payments","PipelineNameOrId":"deploy-prod",
+  "TriggerJsonContent":"{\"version\":\"1.2.0\"}"}' --json
+# response → Data.PipelineExecutionId  (track / cancel with this)
+
+coding call DescribeCdPipeline --param PipelineExecutionId=<id> \
+  --select 'Data.PipelineName,Data.PipelineExecutionStatus,Data.Application' --json   # poll status
+coding call DescribeCdTask --param TaskExecutionId=<id> --json                          # a single task's record
+```
+
+`CreateCdTask` (param `TaskJsonContent`, a JSON string) and `CreateCdPipeline` (`PipelineJsonContent`)
+take opaque JSON blobs — only use them when you already have the exact config shape.
+
+## 4. Infrastructure (host groups, cloud accounts)
+
+```bash
+coding call DescribeCdHostServerGroups --param PageSize=50 --json     # 主机组 list
+coding call DescribeCdHostServerGroup --param Id=12 --json            # one group (keyed by Id)
+coding call DescribeHostServerInstance --param Account=prod --param ServerGroupName=web --json   # per-host deploy detail
+coding call DescribeCdCloudAccounts --param PageSize=50 --json        # 云账号
+coding call DescribeAgentSecret --json                                # 堡垒机安装 secret (sensitive — don't echo)
+```
+
+Create/modify counterparts: `CreateCdHostServerGroup`/`ModifyCdHostServerGroup`,
+`CreateCdCloudAccount`/`ModifyCdCloudAccount`, `BindCdApplicationToProject`.
+
+## 5. Deploy metrics
+
+```bash
+# by project or by application — frequency / duration / trend. StartAt + EndAt are REQUIRED and must be
+# full timestamps "yyyy-MM-dd HH:mm:ss" (date-only is rejected).
+coding call DescribeCdDeployCountByProject --param ProjectName=demo \
+  --param "StartAt=2026-05-01 00:00:00" --param "EndAt=2026-05-21 23:59:59" --json
+# by-application variants: the key is Application (singular name) but its value is an ARRAY of names,
+# so pass it via --data, not --param:
+coding call DescribeCdDeployCountByApplications --data '{"Application":["payments"],
+  "StartAt":"2026-05-01 00:00:00","EndAt":"2026-05-21 23:59:59"}' --json
+# also: DescribeCdDeployTimeBy* (duration) and DescribeCdDeployTrendBy* (trend over time)
+```
+
+## 6. Destructive actions (exit-10 gated)
+
+- **`CancelCdPipeline`** (`PipelineExecutionId`, optional `Reason`) — aborts a *running* deploy.
+- **`DeleteCdPipeline`** — deletes a deploy-flow config.
+- **`DeleteCdHostServerGroup`** — deletes a host group.
+- **`DeleteCdCloudAccount`** — deletes a cloud account.
+
+Follow SKILL.md's protocol: `--dry-run` to preview, explicit user approval, re-run the **same argv
+with `--yes`**. **Cancelling a deploy mid-run can leave an environment half-deployed** — always confirm
+the execution id and target with the user first.
+
+```bash
+coding call CancelCdPipeline --param PipelineExecutionId=<id> --param Reason="bad build" --dry-run --json
+coding call CancelCdPipeline --param PipelineExecutionId=<id> --param Reason="bad build" --yes --json
+```
+
+## 7. Gotchas
+
+- **`Application` is a name (string), not an id** — it keys most CD reads/writes.
+- **Trigger/task/pipeline JSON is passed as a string field** (`TriggerJsonContent`/`TaskJsonContent`/
+  `PipelineJsonContent`), i.e. **JSON-inside-JSON** — escape it inside `--data`. Note `TriggerJsonContent`
+  is *trigger params* (version/artifact), **not** the pipeline-config JSON from `DescribeCdPipelineConfig`
+  — conflating the two is the #1 mistake.
+- **Track deploys by `PipelineExecutionId`** (returned by `TriggerCdPipeline`), not by application name.
+- **Triggering a deploy is consequential even though it's not exit-10 gated** (`TriggerCdPipeline` is
+  `write`) — confirm the application, pipeline, and target/version with the user before triggering prod.
+- **`DescribeAgentSecret` returns a secret** — never echo it.

package/skills/coding/references/ci.md

@@ -0,0 +1,99 @@
+# coding-ci
+
+A curated playbook for the **持续集成 (10)** category — the 24 CI actions.
+
+> Note: this is **CODING CI** (Jenkins-based 构建计划). Deployment (CD) is a separate category — see
+> `references/cd.md`.
+
+## 1. Two identifiers
+
+- **`JobId`** — a **build plan** (构建计划): the reusable pipeline definition attached to a repo.
+- **`BuildId`** — a single **build run** of a plan. Most inspection actions key off `BuildId`.
+
+Flow: find the `JobId` → trigger or list its builds → drill into a `BuildId` for status/logs/artifacts.
+
+## 2. Find build plans (Jobs)
+
+```bash
+coding call DescribeCodingCIJobs --param ProjectId=341 \
+  --select 'JobList[].Id,JobList[].Name,JobList[].DepotName,JobList[].BranchSelector' --json
+coding call DescribeCodingCIJob --param JobId=88 --json     # one plan's full config
+```
+
+## 3. Trigger a build
+
+```bash
+# minimal: run the plan's default branch
+coding call TriggerCodingCIBuild --param JobId=88 --json
+# pin a revision (branch or commit sha) and pass build env vars
+coding call TriggerCodingCIBuild --data '{"JobId":88,"Revision":"feature/login",
+  "ParamList":[{"Key":"ENV","Value":"staging"}]}' --json
+```
+
+`Reentrant` controls re-trigger behavior; `Revision` defaults to the plan's branch selector. The
+response carries the new build under `Data.Build` (note its `Id` → that's the `BuildId` to track).
+
+## 4. Inspect build runs
+
+```bash
+# builds of a plan (paged), newest first
+coding call DescribeCodingCIBuilds --param JobId=88 --param PageNumber=1 --param PageSize=20 \
+  --select 'Data.BuildList[].Id,Data.BuildList[].Number,Data.BuildList[].Status,Data.BuildList[].Branch,Data.BuildList[].Duration' --json
+
+coding call DescribeCodingCIBuild --param BuildId=9001 --json           # one run's detail (Status, Cause, TestResult…)
+coding call DescribeCodingCIBuildStage --param BuildId=9001 --json      # stages (each has a StageId)
+coding call DescribeCodingCIBuildStep --param BuildId=9001 --param StageId=3 --json  # steps in a stage
+```
+
+`Status` tells you success/failure/running; on failure read `FailedMessage` and the logs (§5).
+
+## 5. Logs, artifacts & reports
+
+```bash
+# logs are paginated by line offset — Start=0 first, then advance by what you got
+coding call DescribeCodingCIBuildLog --param BuildId=9001 --param Start=0 --json
+coding call DescribeCodingCIBuildLogRaw --param BuildId=9001 --param Start=0 --json   # plain raw log
+coding call DescribeCodingCIBuildStepLog --param BuildId=9001 --param StageId=3 --param StepId=1 --param Start=0 --json  # per-step
+
+coding call DescribeCodingCIBuildArtifacts --param BuildId=9001 --json
+coding call DescribeCodingCIBuildHtmlReports --param BuildId=9001 --json
+```
+
+For triage of a failed build: `DescribeCodingCIBuild` (get Status/FailedMessage) → `DescribeCodingCIBuildStage`
+to find the failing stage → its `DescribeCodingCIBuildStep` → step log. Don't dump full logs into context —
+page with `Start` and grep for the error.
+
+## 6. Manage plans (write)
+
+```bash
+coding call ModifyCodingCIJob --data '{...}' --json          # edit an existing plan (read DescribeCodingCIJob first for shape)
+coding call CreateCodingCIJob --data '{...}' --json          # create — many required fields; prefer the UI or a team template
+coding call CreateCodingCIJobByTeamTemplate --data '{...}' --json
+coding call ModifyCodingCIAgentEnable --data '{...}' --json  # enable/disable a self-hosted build node
+```
+
+`CreateCodingCIJob` has ~10 required fields (`DepotId`, `DepotType`, `ExecuteIn`, `HookType`,
+`JenkinsFileFromType`, `JobFromType`, `Name`, `ProjectId`, two `AutoCancelSame*` bools). Inspect
+`coding schema CreateCodingCIJob` and copy an existing plan's config rather than hand-rolling it.
+
+## 7. Destructive actions (exit-10 gated)
+
+- **`StopCodingCIBuild`** (`BuildId`) — aborts a *running* build.
+- **`DeleteCodingCIBuild`** (`BuildId`) — deletes a build record.
+- **`DeleteCodingCIJob`** (`JobId`) — deletes the whole build plan.
+- **`ClearCodingCIJobCache`** — clears a plan's cache; **its param is `Id` (= the JobId)**, not `JobId`.
+
+Follow SKILL.md's protocol: `--dry-run` to preview, get explicit user approval, re-run the **same
+argv with `--yes`**. Stopping a build mid-run can leave a deploy half-done — confirm with the user.
+
+```bash
+coding call StopCodingCIBuild --param BuildId=9001 --dry-run --json   # show user
+coding call StopCodingCIBuild --param BuildId=9001 --yes --json        # after approval
+```
+
+## 8. Gotchas
+
+- **`JobId` (plan) vs `BuildId` (run)** — triggering/listing-plans use `JobId`; everything about a
+  specific run uses `BuildId`. The trigger response gives you the new `BuildId` under `Data.Build.Id`.
+- **`ClearCodingCIJobCache` uses `Id`, not `JobId`** — easy to miss.
+- **Logs paginate by `Start`** (a line offset, required) — fetch incrementally, don't expect the whole log.