@mu-cabin/coding-cli 0.1.0

package/skills/coding/references/test.md

@@ -0,0 +1,143 @@
+# coding-test
+
+A curated playbook for the **测试管理 (15)** category — the 29 test-management actions.
+
+## 1. The entities and how they connect
+
+**`ProjectName` (the project *slug*, a string) is the universal required key on every one of the 29
+actions.** There is **no `ProjectId`** anywhere in this category — every other identifier is numeric
+(mostly `uint64`, a few `int64`, and some are integer *arrays* like `Cases`/`RunIds`).
+
+| Entity (中文) | What it is | Its id param | Linked by |
+|---|---|---|---|
+| **测试计划 / TestRun** | a *plan/run* — a container of cases to execute | `RunId` | built from `Cases[]` (case ids) or `IncludeAll`; optionally tied to a git release (`GitReleaseId`) |
+| **测试用例 / TestCase** | a reusable case *definition* (the "what to test") | `CaseId` | lives in a 分组 `SectionId`; linkable to a requirement `IssueId` |
+| **测试任务 / Test** | an *instance* of a case inside a plan (the execution row) | `TestId` | has `CaseId` (source case) under a `RunId`; **this is what you record results on** |
+| **分组 / Section** | a folder tree for cases | `SectionId` | self-nests via `ParentId`; optional `CaseDepotId` (用例库) |
+| **测试报告 / Report** | aggregates one or more plans | `ReportId` | built from `RunIds[]` |
+| **缺陷 / Defect** | an issue/defect | `DefectId` | attached to a `TestId` |
+
+**Lifecycle:** define a `Case` → add it to a `Run` → it becomes a `Test` instance → record a result on
+that `TestId` → aggregate `Runs` into a `Report`.
+
+> ⚠️ **Every list/detail payload nests under `Data`** (e.g. `Data.Runs[]`, `Data.Case`). Nothing in
+> this category returns a top-level array — match your `--select` accordingly.
+
+## 2. Test plans (测试计划 / TestRun)
+
+```bash
+# list plans (filters are mutually exclusive: pick at most one of IterationId / IterationStatus /
+# GitReleaseState / SectionId). State: 0 未开始 · 1 进行中 · 2 已测完.
+coding call DescribeTestRunList --param ProjectName=demo --param Keyword=regression \
+  --select 'Data.Runs[].Id,Data.Runs[].Name,Data.Runs[].State,Data.Runs[].PassedCount,Data.Runs[].FailedCount,Data.Runs[].UntestedCount' --json
+
+coding call DescribeTestRun --param ProjectName=demo --param RunId=88 --json   # detail → Data.Run
+
+# create a plan. IncludeAll=true takes every case; otherwise Cases is an Array of case ids (required).
+coding call CreateTestRun --data '{"ProjectName":"demo","Name":"Release 2.0 regression",
+  "IncludeAll":false,"Cases":[1001,1002,1003],"ExecuteType":1}' --json   # ExecuteType 1 手动 · 2 自动化流水线
+# → Data.Run.Id is the new RunId
+
+coding call ModifyTestRun --data '{"ProjectName":"demo","RunId":88,"Name":"Release 2.0 (rev b)"}' --json
+```
+
+## 3. Test cases (测试用例) & sections (分组)
+
+```bash
+# sections form a tree (ParentId nests them). CaseDepotId scopes to a 用例库 if you have multiple.
+coding call DescribeTestCaseSectionList --param ProjectName=demo --select 'Data.Sections[].Id,Data.Sections[].Name,Data.Sections[].ParentId' --json
+coding call CreateTestCaseSection --data '{"ProjectName":"demo","Name":"Login flows","ParentId":0}' --json   # → Data.Section
+
+# list / read cases (paginated list carries Data.{Page,PageSize,Total}; detail adds Attachments[])
+coding call DescribeTestCaseList --param ProjectName=demo --param SectionId=12 --param PageSize=50 \
+  --select 'Data.Cases[].Id,Data.Cases[].Title,Data.Cases[].Priority,Data.Cases[].TemplateType' --json
+coding call DescribeTestCase --param ProjectName=demo --param CaseId=1001 --json   # → Data.Case
+
+# create a STEPS case: CustomSteps is an Array of {Content,Expected}. For a TEXT case use Steps/Expected strings.
+coding call CreateTestCase --data '{"ProjectName":"demo","SectionId":12,"TemplateType":"STEPS","Title":"Login with valid creds",
+  "Priority":1,"CustomSteps":[{"Content":"Open /login","Expected":"Form shown"},{"Content":"Submit valid creds","Expected":"Dashboard"}]}' --json
+
+# cases linked to a requirement (需求): IssueId is the requirement's id
+coding call DescribeRequirementTestCaseList --param ProjectName=demo --param IssueId=42 --select 'Data.Cases[].Id,Data.Cases[].Title' --json
+```
+
+> ⚠️ **Test-case `Priority` is the *inverse* of issue priority.** Here `0`=紧急 · `1`=高 · `2`=中 (default)
+> · `3`=低 — opposite to the issue/`CreateIssue` scale in SKILL.md (`0`低…`3`紧急). Don't carry
+> the issue mapping over. `TemplateType` ∈ `STEPS` (步骤用例) | `TEXT` (文本用例).
+
+## 4. Recording results — three different keys, read carefully
+
+The result endpoints look similar but key off **different** ids. Getting this wrong is the #1 trap.
+Result `Status` ∈ `UNTESTED` | `PASSED` | `BLOCKED` | `RETEST` | `FAILED`.
+
+```bash
+# (a) by Test-task instance — the normal path. TestId comes from DescribeTestList (its `Id`).
+coding call DescribeTestList --param ProjectName=demo --param RunId=88 --select 'Data.Tests[].Id,Data.Tests[].CaseId,Data.Tests[].Title,Data.Tests[].Status' --json
+coding call CreateTestResult --data '{"ProjectName":"demo","TestId":5001,"Status":"PASSED"}' --json
+
+# (b) step-level result on a STEPS test task (StepIndex starts at 1; StepStatus ∈ PASSED|FAILED only)
+coding call CreateTestStepResult --data '{"ProjectName":"demo","TestId":5001,"StepIndex":1,"StepStatus":"PASSED","Actual":"Dashboard loaded"}' --json
+
+# (c) CreateCaseResult — ⚠️ its `CaseId` param is actually the 测试任务 ID (a TestId), NOT a test-case
+#     id, and it also needs RunId. Despite the name, it behaves like (a) plus the plan context.
+coding call CreateCaseResult --data '{"ProjectName":"demo","RunId":88,"CaseId":5001,"Status":"FAILED"}' --json
+
+# (d) bulk status update across a plan — here CaseIds[] ARE real test-case ids, plus RunId.
+coding call CreateTestResults --data '{"ProjectName":"demo","RunId":88,"CaseIds":[1001,1002],"Status":"PASSED"}' --json
+```
+
+| Action | Keys off | `CaseId`/`CaseIds` means |
+|---|---|---|
+| `CreateTestResult` | `TestId` | — |
+| `CreateTestStepResult` | `TestId` + `StepIndex` | — |
+| `CreateCaseResult` | `RunId` + `CaseId` | **`CaseId` = a TestId** (测试任务 id) |
+| `CreateTestResults` (bulk) | `RunId` + `CaseIds[]` | real test-**case** ids |
+
+## 5. Defects & reports
+
+```bash
+# attach an existing defect (DefectId) to a test task (TestId), then list a task's defects
+coding call CreateTestDefect --data '{"ProjectName":"demo","TestId":5001,"DefectId":7788}' --json
+coding call DescribeTestDefectList --param ProjectName=demo --param TestId=5001 --select 'Data.Defects[].Id,Data.Defects[].Name,Data.Defects[].StatusName,Data.Defects[].AssignedTo' --json
+
+# reports aggregate plans: RunIds is an Array of plan ids (required). Status ∈ CREATING|AVAILABLE|UNAVAILABLE.
+coding call DescribeReportList --param ProjectName=demo --select 'Data.Reports[].Id,Data.Reports[].Name,Data.Reports[].Status' --json
+coding call CreateReport --data '{"ProjectName":"demo","Name":"Release 2.0 report","RunIds":[88,89]}' --json   # → Data.Report
+coding call DescribeReport --param ProjectName=demo --param ReportId=301 --json   # full detail incl. Data.Report.ReportOverview stats
+```
+
+## 6. Attachments (for cases & reports)
+
+`AttachmentIds[]` on `CreateTestCase`/`ModifyTestCase`/`CreateReport` reference pre-uploaded files. The
+upload is a two-step out-of-band flow:
+
+```bash
+coding call CreateAttachmentPrepareSignUrl --param ProjectName=demo --param FileName=evidence.png --json
+# → Data.AttachmentPrepare.{AttachmentId, PrepareSignUrl}. PUT the file bytes to PrepareSignUrl yourself
+#   (the CLI won't upload for you), then pass the returned AttachmentId in AttachmentIds:[…].
+```
+
+## 7. Destructive actions (exit-10 gated)
+
+Five actions need `--yes` (preview with `--dry-run`, get explicit user approval, re-run the **same argv
+with `--yes`** — see SKILL.md's exit-10 protocol):
+
+- **`DeleteTestRun`** (`ProjectName`,`RunId`) — delete a plan.
+- **`ArchiveTestRun`** (`ProjectName`,`RunId`) — archive/finalize a plan; gated even though it returns the
+  Run object, because the gate keys off the `Archive` verb.
+- **`DeleteTestCase`** (`ProjectName`,`CaseId`), **`DeleteTestCaseSection`** (`ProjectName`,`SectionId`),
+  **`DeleteReport`** (`ProjectName`,`ReportId`).
+
+## 8. Gotchas
+
+- **`ProjectName` (slug), never `ProjectId`** — this whole category keys off the project *name*.
+- **The three "Test/Case/Run" ids are distinct.** `RunId` = a plan, `CaseId` = a case definition,
+  `TestId` = an execution instance inside a plan. `DescribeTestList.Data.Tests[].Id` is the `TestId`;
+  its `CaseId` field points back to the source case.
+- **`CreateCaseResult.CaseId` is a TestId, not a case id** (§4). The bulk `CreateTestResults.CaseIds[]`
+  *are* real case ids. Don't swap them.
+- **`Priority` is inverted vs issues** (§3): `0`紧急 … `3`低 here.
+- **Array params**: `Cases`/`CaseIds`/`RunIds`/`AttachmentIds`/`CustomStepStatus` are all arrays even
+  when sending one element; `CustomSteps` is an array of `{Content,Expected}` objects.
+- **Everything wraps under `Data`** — `Data.Runs[]`, `Data.Cases[]`, `Data.Sections[]`, `Data.Tests[]`,
+  `Data.Defects[]`, `Data.Reports[]`; singletons at `Data.Run`/`Data.Case`/`Data.Report`.

package/skills/coding/references/wiki.md

@@ -0,0 +1,118 @@
+# coding-wiki
+
+A curated playbook for the **Wiki (13)** category — the 12 wiki actions.
+
+## 1. Identifiers
+
+- **`ProjectName`** (the project *slug*, a string) is required on **every** action — there is **no
+  `ProjectId`** in this category.
+- **`Iid`** (int64, "wiki 编号") is the **per-project page handle** — what every *page-scoped* action
+  takes (`DescribeWiki`, `ModifyWiki`, `ModifyWikiTitle`, `ModifyWikiOrder`, `DeleteWiki`). The
+  exceptions are `DescribeWikiList` (`ProjectName` only) and the job-status reads (`ProjectName` +
+  `JobId`). Responses also carry a global **`Id`**; **never feed `Id` back as `Iid`.**
+- **`ParentIid`** (int64) places a page in the tree; **`0` = top level / root**.
+
+> ⚠️ **Response wrapping is uneven.** `DescribeWikiList` → `Data` is an **array** (the page tree);
+> `DescribeWiki` / job-status → `Data` is an **object**; but `CreateUploadToken` returns top-level
+> **`Token`** and the ZIP imports return top-level **`JobId`** — neither is under `Data`. Match
+> `--select` to the right wrapper per call.
+
+## 2. Browse & read
+
+```bash
+# the page tree (whole thing; no pagination). Tree linkage: ParentIid (0=root), ordering: Order (a float).
+coding call DescribeWikiList --param ProjectName=demo \
+  --select 'Data[].Iid,Data[].Title,Data[].ParentIid,Data[].Order,Data[].Children[].Iid,Data[].Children[].Title' --json
+
+# read one page — ⚠️ VersionId is REQUIRED with no "latest" sentinel, yet DescribeWikiList does NOT
+#   expose a version. In practice you need a known version number — from the wiki UI, or a prior
+#   DescribeWiki response's CurrentVersion/LastVersion. Content = raw source; Html = rendered.
+coding call DescribeWiki --param ProjectName=demo --param Iid=12 --param VersionId=5 \
+  --select 'Data.Title,Data.Content,Data.CurrentVersion,Data.LastVersion' --json
+```
+
+## 3. Create & edit
+
+```bash
+# create — Title, Content, AND ParentIid are all required (use ParentIid:0 for a root page). Msg = commit note.
+coding call CreateWiki --data '{"ProjectName":"demo","Title":"Onboarding","Content":"# Onboarding\n…","ParentIid":0,"Msg":"initial"}' --json
+# → Data.Iid / Data.Id of the new page
+
+# full edit — ⚠️ ModifyWiki requires BOTH Title and Content (you can't update body alone). Identified by Iid.
+coding call ModifyWiki --data '{"ProjectName":"demo","Iid":12,"Title":"Onboarding","Content":"# Onboarding (v2)\n…","Msg":"revise"}' --json
+
+# rename only — use this instead of ModifyWiki when you don't want to resupply Content
+coding call ModifyWikiTitle --data '{"ProjectName":"demo","Iid":12,"Title":"Onboarding Guide"}' --json
+```
+
+Content is passed inline as the `Content` string (markdown-style source rendered server-side; the read
+response gives you both `Content` and rendered `Html`). There is no markdown-vs-HTML selector param.
+
+## 4. Move & reorder
+
+```bash
+# "Wiki 父级修改" — reparent and/or reorder a page. Iid = the page to move; ParentIid = its new parent
+#   (0 = root). Position among the new siblings via Before/After (sibling anchors, both optional ints) —
+#   ⚠️ there is NO numeric Order input here despite the action name. Forced (bool,
+#   default false) = 是否检查权限 (whether to enforce the permission check).
+coding call ModifyWikiOrder --data '{"ProjectName":"demo","Iid":12,"ParentIid":3,"After":7}' --json
+```
+
+## 5. ZIP import / update (async, multi-step)
+
+A 4-step pipeline. The values that thread through it: `CreateUploadToken` yields **`AuthToken` + `Time`**
+(carried into the ByZip call) and COS upload credentials; the upload yields a **`Key`** (the stored
+object name); the ByZip call yields a **`JobId`** you then poll.
+
+```bash
+# 1. get an upload token + COS credentials for the file
+coding call CreateUploadToken --param ProjectName=demo --param FileName=wiki-export.zip \
+  --select 'Token.UploadLink,Token.UpToken,Token.AuthToken,Token.Time,Token.SecretId,Token.SecretKey,Token.Provider' --json
+
+# 2. upload the zip to Token.UploadLink (Tencent COS) using UpToken/SecretId/SecretKey — OUT OF BAND
+#    (the CLI does not upload bytes). The upload produces the stored object name `Key` (a uuid .zip).
+
+# 3a. import as NEW pages under ParentIid — carries FileName, Key, AuthToken, Time from above
+coding call CreateWikiByZip --data '{"ProjectName":"demo","FileName":"wiki-export.zip","Key":"<uuid>.zip",
+  "AuthToken":"<AuthToken>","Time":<Time>,"ParentIid":0}' --json   # → top-level JobId
+
+# 3b. OR update an EXISTING page from the zip — same body but `Iid` (the page) instead of `ParentIid`
+coding call ModifyWikiByZip --data '{"ProjectName":"demo","FileName":"wiki-export.zip","Key":"<uuid>.zip",
+  "AuthToken":"<AuthToken>","Time":<Time>,"Iid":12}' --json   # → top-level JobId
+
+# 4. poll the matching status action (NOT interchangeable): Import↔Create, Update↔Modify.
+coding call DescribeImportJobStatus --param ProjectName=demo --param JobId=<JobId> --select 'Data.JobId,Data.Status' --json
+coding call DescribeUpdateJobStatus --param ProjectName=demo --param JobId=<JobId> --select 'Data.JobId,Data.Status' --json
+```
+
+- **`UpToken` vs `AuthToken` are different tokens** — `UpToken` (with `SecretId`/`SecretKey`) authorizes
+  the COS upload in step 2; only **`AuthToken` + `Time`** feed the CODING ByZip call in step 3.
+- **Create→`ParentIid`, Modify→`Iid`** is the one param difference between the two ByZip calls, and they
+  have **separate** status pollers (`DescribeImportJobStatus` for create, `DescribeUpdateJobStatus` for
+  modify). `Status` is a string enum (e.g. `WAIT_PROCESS` while pending) — poll until it leaves the
+  pending state.
+
+## 6. Destructive actions (exit-10 gated)
+
+One action needs `--yes`:
+
+- **`DeleteWiki`** (`ProjectName`, `Iid`) — **moves the page to the recycle bin (reversible)**, not a
+  hard delete. Still gated: preview with `--dry-run`, get explicit approval, re-run the **same argv with
+  `--yes`** (see SKILL.md's exit-10 protocol).
+
+## 7. Gotchas
+
+- **`ProjectName` (slug), never `ProjectId`** for this whole category.
+- **`Iid` is the input handle; `Id` is a different (global) id in responses** — never round-trip `Id`
+  as `Iid`. `ParentIid:0` = root, and `ParentIid` is **required** on `CreateWiki` and `CreateWikiByZip`.
+- **`DescribeWiki` requires `VersionId`** with no "latest" sentinel — and `DescribeWikiList` does **not**
+  return a version, so you can't bootstrap one from the tree. You need a version number from elsewhere
+  (the UI, or a prior read's `CurrentVersion`/`LastVersion`); surface this to the user if you can't
+  determine one.
+- **`ModifyWiki` requires both `Title` and `Content`** — for a rename use `ModifyWikiTitle`.
+- **`ModifyWikiOrder` positions via `Before`/`After` sibling anchors, not a numeric order**; `ParentIid`
+  is required; `Forced` (default false) toggles the 是否检查权限 permission check.
+- **Response wrapping is uneven**: list → `Data[]` (array), single read / job status → `Data` (object),
+  ByZip → top-level `JobId`. Field types also drift (`Order` is a float in the list but an int in the
+  single read; timestamps are epoch-ms in the list but datetime strings in the single read) — don't
+  assume one shape across calls.