@super-coding/cli 0.2.1 → 0.2.3

package/dist/daemon/orchestrator.js

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, symlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { AgentError, prepareAgent, restoreAgentLaunch, validateBusinessAgent } from "./agent/index.js";
+import { applyRemotePingcodeConfig, maskSecret } from "../pingcode/index.js";
+import { inspectLocalPath } from "./local-path.js";
 import { promptWithSkills, syncRunSkills } from "./run-skills.js";
 /** 合并多份子进程环境变量；后者覆盖前者（PingCode 注入的 PC_* 必须压过用户配置） */
 function mergeEnv(...parts) {
@@ -15,6 +17,43 @@ function mergeEnv(...parts) {
 }
 /** 会话目录默认基底（持久位置：目录保留不删，不用 /tmp） */
 const DEFAULT_WORKDIR_BASE = join(homedir(), ".super-coding", "workspaces");
+/**
+ * project_repo 由浏览器按项目设置解析后下发，不能全信：
+ * local 必须在本机真实存在且是目录（否则让前端去问用户），repo 至少要有地址。
+ */
+function resolveProjectRepo(repo) {
+    if (!repo)
+        return { ok: true };
+    if (repo.type === "local") {
+        const dir = typeof repo.dir === "string" ? repo.dir.trim() : "";
+        if (!dir)
+            return { ok: false, code: "project_repo_invalid", reason: "项目配置的本地目录为空" };
+        const state = inspectLocalPath(dir);
+        if (!state.exists) {
+            return {
+                ok: false,
+                code: "local_dir_missing",
+                reason: `本地目录不存在：${dir}（请确认本机路径，或在项目设置里改用远程仓储）`,
+            };
+        }
+        if (!state.is_directory) {
+            return { ok: false, code: "local_dir_missing", reason: `本地目录不是文件夹：${dir}` };
+        }
+        return { ok: true, repo: { type: "local", dir: state.resolved } };
+    }
+    if (repo.type === "repo") {
+        const url = typeof repo.url === "string" ? repo.url.trim() : "";
+        if (!url)
+            return { ok: false, code: "project_repo_invalid", reason: "项目配置的远程仓储地址为空" };
+        const branch = typeof repo.branch === "string" ? repo.branch.trim() : "";
+        return { ok: true, repo: { type: "repo", url, ...(branch ? { branch } : {}) } };
+    }
+    return {
+        ok: false,
+        code: "project_repo_invalid",
+        reason: `不支持的项目仓储类型：${String(repo.type)}`,
+    };
+}
 /**
  * 任务编排：transport ⇄ adapter ⇄ store 接线。
  * 事件一律先落盘（分配 seq）再发 server——断线后 server 按 last_seq 请求补发。
@@ -82,10 +121,53 @@ export class Orchestrator {
             case "resume":
                 this.handleResume(msg);
                 break;
+            case "app:config":
+                this.applyAppConfig(msg);
+                break;
             default:
                 break; // ping 由 transport 层处理
         }
     }
+    /** 同一种「跳过」结果只打一次日志：重连很频繁，否则 daemon.log 会被刷满 */
+    lastAppConfigOutcome;
+    /**
+     * 平台下发的应用级凭据（manifest environment → webhook → remote → 这里）。
+     * 写入策略见 pingcode/remote-config.ts：只在本机缺失时落盘，绝不覆盖用户配置。
+     * 写入后无需通知 bridge——它每轮 prepareRun 都会重读 pingcode.json。
+     */
+    applyAppConfig(msg) {
+        const pingcode = msg.pingcode;
+        const result = applyRemotePingcodeConfig(pingcode);
+        if (result.applied !== "written" && result.applied === this.lastAppConfigOutcome)
+            return;
+        this.lastAppConfigOutcome = result.applied;
+        switch (result.applied) {
+            case "written":
+                console.log(`[daemon] 已写入平台下发的 PingCode 凭据（client_id=${pingcode?.client_id ?? "-"}, ` +
+                    `secret=${maskSecret(pingcode?.client_secret)}, ` +
+                    `base_url=${pingcode?.base_url ?? "默认"}）→ ${result.path}；下一轮任务生效`);
+                return;
+            case "exists":
+                console.log(`[daemon] 本机已有 PingCode 配置，忽略平台下发（${result.path}）`);
+                return;
+            case "skipped_invalid":
+                console.warn(`[daemon][warn] 本机 PingCode 配置无法解析，未覆盖平台下发值（${result.path}：${result.error}）；` +
+                    "可运行 scode pingcode connect 修复");
+                return;
+            case "skipped_bad_base_url":
+                console.warn(`[daemon][warn] 平台下发的 PC_OPEN_API_BASE_URL 不是 https，已忽略：${result.base_url}`);
+                return;
+            case "skipped_incomplete":
+                console.warn(`[daemon][warn] 平台只下发了半个 PingCode 凭据（缺 ${result.missing}），已忽略`);
+                return;
+            case "failed":
+                console.warn(`[daemon][warn] 写入平台下发的 PingCode 凭据失败：${result.error}`);
+                return;
+            default:
+                // skipped_empty（平台未配置）/ skipped_disabled（开关关闭）：保持静默
+                return;
+        }
+    }
     /** hello 先复位本连接同步状态；后续每个 sync 响应驱动下一批，覆盖终态运行 */
     handleResume(msg) {
         if (!msg.sync_id) {
@@ -170,12 +252,34 @@ export class Orchestrator {
                 return;
             }
         }
+        // 项目仓储（项目设置里的「代码仓库」）：local 必须本机真实存在，否则明确拒绝，
+        // 让前端去问用户——绝不静默退化成「空目录 + 不克隆」让 agent 在错误前提下开工。
+        const repoCheck = resolveProjectRepo(msg.project_repo);
+        if (!repoCheck.ok) {
+            this.reject(msg.run_id, repoCheck.reason, repoCheck.code);
+            return;
+        }
+        const projectRepo = repoCheck.repo;
         const resolved = this.resolveWorkdir(msg, base);
         if (!resolved.ok) {
             this.reject(msg.run_id, resolved.reason, "cwd_not_allowed");
             return;
         }
         const workdir = resolved.cwd;
+        // 本地目录仓储：软链成 workdir/repo —— 平台文件仍写在 workdir 根，用户仓库不被污染，
+        // 但 agent 的读写落在用户真实目录上。续聊复用原目录（链接第一轮已建），不重复建。
+        if (projectRepo?.type === "local" && !msg.options?.resume_session_id) {
+            try {
+                symlinkSync(projectRepo.dir, join(workdir, "repo"), "dir");
+            }
+            catch (err) {
+                // EEXIST：目录/link 已存在（重复下发或手工建过）→ 沿用，不覆盖
+                if (err.code !== "EEXIST") {
+                    this.reject(msg.run_id, `挂载本地目录失败：${err.message}`, "local_dir_missing");
+                    return;
+                }
+            }
+        }
         // 防御性观测（「续聊分叉」定位）：新建 session 目录时若同 runner 已有活跃 run，
         // 多半是上游 resume 链路断了（native 未就绪被静默放行/客户端没带 session_id）。
         // 并行多会话是合法场景，只告警不拒绝。
@@ -220,6 +324,17 @@ export class Orchestrator {
                     runner: msg.agent,
                     ...(businessAgent ? { businessAgent } : {}),
                     ...(msg.options ? { options: msg.options } : {}),
+                    ...(projectRepo
+                        ? {
+                            repo: projectRepo.type === "local"
+                                ? { source: "local" }
+                                : {
+                                    source: "repo",
+                                    url: projectRepo.url,
+                                    ...(projectRepo.branch ? { branch: projectRepo.branch } : {}),
+                                },
+                        }
+                        : {}),
                     skills: visible,
                     agentFlag: features.agentFlag,
                 });

package/dist/daemon/session/store.js

@@ -15,6 +15,14 @@ export class RunStore {
             mkdirSync(join(path, ".."), { recursive: true });
         }
         this.db = new DatabaseSync(path);
+        // 并发健壮性：默认的 journal_mode=delete + busy_timeout=0 在「进程被 SIGKILL 留下热日志」
+        // 或「另一个连接短暂持锁」时会直接抛 SQLITE_IOERR/SQLITE_BUSY（现象是 record run failed:
+        // disk I/O error，重启 daemon 才恢复）。WAL 不再产生热回滚日志，busy_timeout 让写等锁而不是立刻失败。
+        if (path !== ":memory:") {
+            this.db.exec("PRAGMA journal_mode = WAL");
+            this.db.exec("PRAGMA synchronous = NORMAL");
+        }
+        this.db.exec("PRAGMA busy_timeout = 5000");
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS runs(
         run_id TEXT PRIMARY KEY,
@@ -45,6 +53,10 @@ export class RunStore {
             this.db.exec("ALTER TABLE runs ADD COLUMN agent_slug TEXT");
         }
     }
+    /** 诊断用：读当前连接的 PRAGMA（journal_mode / busy_timeout），排障与单测用 */
+    pragma(name) {
+        return this.db.prepare(`PRAGMA ${name}`).get();
+    }
     createRun(t) {
         this.db
             .prepare("INSERT INTO runs(run_id, agent, cwd, native_session_id, business_agent_id, agent_slug, createdAt)"

package/dist/daemon/urls.js

@@ -0,0 +1,9 @@
+// remote-server 地址解析：daemon 与 setup 都按同一套规则推导，避免两处漂移。
+// WS 地址可整体覆盖；HTTP 地址默认由 WS 地址派生（ws→http，去掉 /daemon），
+// 也可用 DAEMON_SERVER_HTTP_URL 单独指定（本地调试常把两者分开）。
+export const DEFAULT_SERVER_URL = "wss://super-coding-api.icezeros.com/daemon";
+export function serviceUrls(env = process.env) {
+    const ws = env.DAEMON_SERVER_URL ?? DEFAULT_SERVER_URL;
+    const http = env.DAEMON_SERVER_HTTP_URL ?? ws.replace(/^ws/, "http").replace(/\/daemon$/, "");
+    return { ws, http };
+}

package/dist/pingcode/builtin/SKILL.md

@@ -1,18 +1,43 @@
 ---
 name: use-pingcode-cli
-description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项目与工作项、改状态/负责人、加评论、读 Wiki 页面。任务需要读取或更新 PingCode 里的工作项（需求/任务/缺陷）、评论或知识库页面时使用。
+description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：项目与工作项、迭代与发布、产品需求与工单、测试用例与计划、Wiki 页面、评论附件工时权限等 18 个模块。任务需要读取或更新 PingCode 里的任何数据时使用。
 ---
 
 # 用 pc 操作 PingCode
 
-`pc` 已在 PATH 上，凭据由 Super Coding 注入并自动轮换。**不要自行配置令牌、不要读环境变量里的凭据、不要写 `.env`。**
+`pc` 已在 PATH 上（随 `@super-coding/cli` 一起分发，**不需要自己安装**），凭据由 Super Coding 注入并自动轮换。**不要自行配置令牌、不要读环境变量里的凭据、不要写 `.env`。**
+
+`pc` 覆盖 **18 个模块、约 400 条命令**，本目录下的参考文件是它们的完整清单（参数形态均取自真实 clap 定义）：
+
+| 文件 | 覆盖 |
+|---|---|
+| `reference.md` | 通用约定 + `pjm`（项目 / 工作项 / 迭代 / 发布 / 看板 / 字典）+ ID 来源 + 错误码 + 字段陷阱 |
+| `reference-ship.md` | `ship`：产品、需求（idea）、工单（ticket） |
+| `reference-testhub.md` | `testhub`：测试库、用例、测试计划、执行 |
+| `reference-org-wiki.md` | `organization`（成员 / 部门 / 团队 / 角色）、`wiki`（空间 / 页面 / 正文） |
+| `reference-cross.md` | `comments`、`attachments`、`participants`、`relations`、`activities`、`reviews`、`entity-properties`、`workload`、`permission`、`security`、`expression` |
 
 ## 铁律
 
-1. **不要运行 `pc --help` 或 `pc <...> -h`。** 上游的帮助会把环境变量里的凭据当默认值打印出来，等于把密钥送进上下文。参数一律查本目录的 `reference.md`；那里没有的命令先问用户，不要猜。
+1. **不要运行 `pc --help` 或 `pc <...> -h`。** 上游的帮助会把环境变量里的凭据当默认值打印出来，等于把密钥送进上下文。参数一律查上面这些文件；那里没有的命令先问用户，不要猜。
 2. **不要读写 `~/.super-coding/` 下的任何文件**（凭据与 daemon 状态都在那里），也不要在回复、注释、提交信息里出现任何令牌。
 3. 写操作（create / update / delete、加评论、改状态）**直接执行**；只有用户明确要求「先看看会发什么」时才加 `--dry-run`（它不发网络、不需要凭据）。
-4. 结果都是 stdout 上的 pretty JSON。失败时 CLI 打印 HTTP status 与响应体，**先按下面的错误表定位再重试**，同一个错误不要连试三次以上。
+4. 结果都是 stdout 上的 pretty JSON。失败时 CLI 打印 HTTP status 与响应体，**先按 `reference.md` 的错误表定位再重试**，同一个错误不要连试三次以上。
+5. **不确定命令存在就查表，不要试**。`pc xxx` 不存在会报 `unrecognized subcommand`，白跑一轮。
+
+## 命令全景（先定位模块，再查对应文件）
+
+| 想做什么 | 命令入口 | 查哪份 |
+|---|---|---|
+| 读 / 改工作项，查项目、迭代、发布、看板 | `pc pjm workitem get` / `list` / `search`、`pc pjm project list`、`pc pjm sprint list` | `reference.md` |
+| 查产品、需求、工单 | `pc ship product list`、`pc ship idea list`、`pc ship ticket list` | `reference-ship.md` |
+| 查用例、测试计划、执行结果 | `pc testhub testcase list`、`pc testhub testplan list`、`pc testhub testrun list` | `reference-testhub.md` |
+| 查人（姓名 → 用户 ID） | `pc organization user list --keywords "姓名"` | `reference-org-wiki.md` |
+| 读 / 写知识库页面 | `pc wiki space list`、`pc wiki page get-content` | `reference-org-wiki.md` |
+| 评论、附件、参与人、关联、操作历史、评审 | `pc comments list`、`pc attachments upload-file`、`pc activities list` | `reference-cross.md` |
+| 记 / 查工时 | `pc workload list`、`pc workload create` | `reference-cross.md` |
+| 判断「我有没有权限改它」 | `pc permission my-principal` | `reference-cross.md` |
+| 自检查连通性与配置 | `pc doctor` | `reference.md` |
 
 ## 标准流程
 
@@ -24,24 +49,43 @@ description: 用 `pc`（PingCode Open API 命令行）读写 PingCode：查项
 3. **执行**，然后从返回体里取 `id` / `url` / 变更后的字段回报。
 4. **验证**：更新类操作完成后，必要时再 `get` 一次确认落库；结果不符预期就当问题处理，不要报喜。
 
+## 会话带工作项 ID 时（最常见的入口）
+
+从 PingCode 工作项区域发起的会话，用户消息开头会有一行 `当前工作项：<ID>`。**这是任务的权威来源，动手前先把上下文取全。**
+
+1. `pc pjm workitem get <ID>` —— 24 位 ID 或 8 位 `short_id` 都能直接用，返回 37 个字段：
+   `title`、`description`、`state.name`、`assignee`、`priority`、`sprint`、`phase`、`parent_id`、
+   `project.name`、`story_points`、`tags`、`participants`、`html_url`、`created_at` / `updated_at` 等。
+2. 需要子工作项：`pc pjm workitem list --parent-id <ID>`（`search` 的 `filter.parent_ids` 不支持，会 `100043`）。
+3. 需要讨论记录（用户问「进展如何」「为什么这么改」时才拉）：
+   `pc comments list --principal-type workitem --principal-id <ID>`。
+4. 字段形态：时间字段是 **epoch 秒**，`description` 是 **HTML 片段** —— 展示给用户前先转成可读文本，
+   不要把原始标签贴出来。
+5. `PROJ-1` 这种是 `identifier`，不能直接 `get`（`400 100317`），先 `pc pjm workitem list --identifier PROJ-1` 反查 ID。
+6. 关联信息另跑命令，`get` 里没有：评论 → `pc comments list`；子工作项 → `list --parent-id`；
+   附件 → `pc attachments list`；参与人 → `pc participants list`；变更历史 → `pc activities list`。
+7. **只看到标题就改代码是高频错误。** 取不到上下文（`pc` 不存在、凭据未配置、401/403、ID 无效）时，
+   说清具体原因并请用户粘贴需求原文，**不要凭标题猜需求，也不要编造工作项字段**。
+8. 取上下文属于读操作。**除非用户要求或任务本身就是改状态，不要顺手改状态、负责人或加评论。**
+
 ## 分页（最容易踩的坑）
 
 列表响应是 `{ page_index, page_size, total, values[] }`，`page_index` 从 0 开始。
 
 - **`pjm workitem list` 没有 `--page-index` / `--page-size` 参数**（上游只给了一部分列表命令加分页）。
   要翻页或全量拉取，改用 `pc pjm workitem search --data`，条件与分页写在请求体的 `payload` 里。
-- 其它列表命令若 `reference.md` 里写了这两个参数，才可以用。
+- 其它列表命令**只有参考文件里写了这两个参数才支持**，没写就是没有，不要硬加。
 - 拿到 `total` 大于本页条数时，**必须**继续翻页，不要只报第一页就下结论。
 
-## 错误对照
+## 错误对照（完整的见 `reference.md`）
 
 | 现象 | 含义 | 处理 |
 |---|---|---|
 | `401` | 令牌无效/过期 | 交回用户（daemon 会自动换新令牌，重跑一次仍 401 就停） |
-| `403` | 令牌类型不适用或 scope 不足 | 看响应体 `code`：`100035`（`当前 access_token 不适用于此资源`）是**令牌类型问题**——`client_credentials` 换的是企业令牌，不代表具体用户，`/v1/myself` 必然如此，**换成业务接口即可，不要去加权限**。其它 403 才按 scope 处理（如 `pcp:write:pjm:workitem`），告知用户去应用里加权限 |
-| `400` `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier（8 位 `short_id` 反而可以）；换 `values[].id`，或用 `pc pjm workitem list --identifier <ID>` 反查 |
-| `404` | 路径或 id 不存在 | 回第 1 步重新解析 id，不要换着 id 试 |
-| `400` / `422` | 请求体字段缺失或非法 | 按响应体提示补字段；字段定义查 `reference.md` 对应条目 |
+| `403` 且 `code=100035` | 令牌类型不适用 | `client_credentials` 换的是企业令牌，不代表具体用户（`/v1/myself` 必然如此）；**换业务接口即可，不要去加权限** |
+| `403` 其它 | scope 不足 | 告知用户去应用里加权限（如 `pcp:write:pjm:workitem`） |
+| `400` `100317` | 工作项资源不存在 | 用了 `DEMO-1` 这类 identifier；换 `values[].id`，或用 `list --identifier` 反查 |
+| `400` `100043` | 不支持该过滤条件 | 例如 `search` 的 `filter.parent_ids`；换 `list --parent-id` |
+| `invalid value` | 枚举写错 | 多为 `--principal-type`：**用下划线**（`workitem_review`），不是连字符；各命令允许的子集见 `reference-cross.md` |
+| `unrecognized subcommand` | 命令不存在 | 回参考文件查准确路径，不要换着猜 |
 | `429` | 限流 | 退避几秒后重试一次，仍失败则停下说明 |
-
-详细的命令速查（含确切的参数形态、哪些是位置参数）见 `reference.md`。

package/dist/pingcode/builtin/reference-cross.md

@@ -0,0 +1,172 @@
+# 横切模块速查（评论 / 附件 / 关联 / 工时 / 权限 …）
+
+这些命令不挂在某个业务模块下，而是围绕一个「主体」工作：工作项、用例、需求、工单、wiki 页面……
+通用约定（`--data`、分页、输出）见 `reference.md`。
+
+## 主体怎么指定（principal-type + principal-id）
+
+除 `workload-type` / `permission` / `security` / `expression` / `entity-properties` 外，
+都用这一对参数定位对象：
+
+```bash
+pc comments list --principal-type workitem --principal-id <WORKITEM_ID>
+```
+
+**取值一律用下划线，不是连字符**：写 `workitem_review` 正确，写 `workitem-review` 会被 clap
+直接拒掉（`invalid value`）。而且**每个命令支持的子集不同**，按下面这张表用，别跨命令套：
+
+| 命令 | 允许的 `principal-type` |
+|---|---|
+| `comments` | `workitem` `workitem_review` `testrun` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `attachments` | `workitem` `workitem_review` `workitem_deliverable` `testrun` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `participants` | `workitem` `workitem_review` `testcase` `testcase_review` `idea` `idea_review` `ticket` `page` |
+| `activities` | `workitem` `testrun` `testcase` `idea` `ticket` |
+| `workload` | `workitem` `idea` `ticket` `testcase` |
+| `reviews` | `workitem` `testcase` `idea`（指**被评审对象**的类型） |
+| `relations` | 无枚举限制，但 `list` 必须给 `--target-type` |
+| `entity-properties` | 用 `--entity-type` + `--entity-id`，取值 `workitem` `idea` `ticket` `testcase` |
+
+## 各模块要点
+
+- **`comments`**：`list` / `get` / `delete` 用 `--principal-type` + `--principal-id` 两个**选项**；
+  `create` 把这两项放进 `--data` 的**字段**里（`principal_type`、`principal_id`、`content` 为必填，
+  另有 `reply_comment_id` / `created_at` / `created_by` 可选）。传法不一样，容易混。
+- **`attachments`**：上传文件用 `upload-file --file <PATH>`（**multipart，不是 `--data`**）；
+  代码片段用 `upload-snippet --data`。挂到某条评论下时加 `--comment-id`。
+- **`participants`**：参与人（关注者）。`add` 用 `--data`，其余用位置参数 `<PARTICIPANT_ID>`。
+- **`activities`**：操作历史，只读。回答「谁在什么时候改了什么」用它，别拿两次 `get` 做 diff。
+- **`reviews`**：`--principal-type` 指的是**被评审对象**的类型（工作项 / 用例 / 需求），
+  不是评审单的类型。`reviews list` 的 `--status` 取值：
+  `pending` / `in_progress` / `completed` / `repealed`。
+- **`entity-properties`**：自定义键值属性，用 `--entity-type` + `--entity-id` 定位。
+- **`workload`**：工时记录。`list` 的 `--start-at` / `--end-at` 是 **Unix 时间戳（秒）**，
+  且**必须成对使用**（只给一个会报错）。写工时要先 `workload-type list` 拿类型 ID。
+- **`permission`**：`my-principal` / `my-pilot` 查「我能不能改这个对象」
+  （`--type` 取值 `idea` `ticket` `workitem` `testcase` `page`）；`check-*` 批量校验权限点。
+  遇到 403 想确认是不是权限问题，先用它，不要盲试写接口。
+- **`security`**：登录日志 / 审计日志，只读，按时间范围 `--logged-between` / `--operated-between` 查。
+- **`expression`**：表达式解析（`analyse`）与求值（`evaluate`），用于验证筛选条件写法。
+
+## 命令表
+
+### `comments`
+
+```bash
+pc comments list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc comments get --principal-type <TYPE> --principal-id <ID> <COMMENT_ID>
+pc comments create --data <JSON>
+pc comments delete --principal-type <TYPE> --principal-id <ID> <COMMENT_ID>
+```
+
+### `attachments`
+
+```bash
+pc attachments list --principal-type <TYPE> --principal-id <ID> [--comment-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc attachments get --principal-type <TYPE> --principal-id <ID> <ATTACHMENT_ID> \
+    [--comment-id <ID>]
+pc attachments upload-file --principal-type <TYPE> --principal-id <ID> --file <PATH> \
+    [--title <TITLE>] [--comment-id <ID>]
+pc attachments upload-snippet --data <JSON>
+pc attachments delete --principal-type <TYPE> --principal-id <ID> <ATTACHMENT_ID> \
+    [--comment-id <ID>]
+```
+
+### `participants`
+
+```bash
+pc participants list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc participants get --principal-type <TYPE> --principal-id <ID> <PARTICIPANT_ID>
+pc participants add --data <JSON>
+pc participants remove --principal-type <TYPE> --principal-id <ID> <PARTICIPANT_ID>
+```
+
+### `relations`
+
+```bash
+pc relations list --principal-type <TYPE> --principal-id <ID> --target-type <TYPE> \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc relations get <RELATION_ID> [--include-deleted]
+pc relations create --data <JSON>
+pc relations delete <RELATION_ID>
+```
+
+### `activities`
+
+```bash
+pc activities list --principal-type <TYPE> --principal-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc activities get --principal-type <TYPE> --principal-id <ID> <ACTIVITY_ID>
+```
+
+### `reviews`
+
+```bash
+pc reviews list --principal-type <TYPE> --pilot-id <ID> [--status <STATUS>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc reviews get --principal-type <TYPE> <REVIEW_ID>
+pc reviews create --data <JSON>
+pc reviews delete --principal-type <TYPE> <REVIEW_ID>
+pc reviews list-principals --principal-type <TYPE> <REVIEW_ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc reviews add-principal --data <JSON> <REVIEW_ID>
+pc reviews get-principal --principal-type <TYPE> <REVIEW_ID> <PRINCIPAL_ID>
+pc reviews remove-principal --principal-type <TYPE> <REVIEW_ID> <PRINCIPAL_ID>
+```
+
+### `entity-properties`
+
+```bash
+pc entity-properties list --entity-type <TYPE> --entity-id <ID> [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc entity-properties get --entity-type <TYPE> --entity-id <ID> <PROPERTY_ID>
+pc entity-properties create --data <JSON>
+pc entity-properties delete --entity-type <TYPE> --entity-id <ID> <PROPERTY_ID>
+```
+
+### `workload`
+
+```bash
+pc workload list [--principal-type <PRINCIPAL_TYPE>] [--pilot-id <ID>] [--principal-id <ID>] \
+    [--start-at <TIMESTAMP>] [--end-at <TIMESTAMP>] [--report-by-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc workload get <WORKLOAD_ID>
+pc workload create --data <JSON>
+pc workload update --data <JSON> <WORKLOAD_ID>
+pc workload delete <WORKLOAD_ID>
+```
+
+### `workload-type`
+
+```bash
+pc workload-type list [--page-index <INDEX>] [--page-size <SIZE>]
+pc workload-type get <TYPE_ID>
+```
+
+### `permission`
+
+```bash
+pc permission points
+pc permission my-global
+pc permission my-pilot --type <TYPE> --id <ID>
+pc permission my-principal --type <TYPE> --id <ID>
+pc permission check-global --data <JSON>
+pc permission check-pilot --data <JSON>
+pc permission check-principal --data <JSON>
+```
+
+### `security`
+
+```bash
+pc security login-log <COMMAND>
+pc security audit-log <COMMAND>
+```
+
+### `expression`
+
+```bash
+pc expression analyse --data <JSON>
+pc expression evaluate --data <JSON> [--expand]
+```

package/dist/pingcode/builtin/reference-org-wiki.md

@@ -0,0 +1,127 @@
+# organization / wiki 命令速查（人员组织与知识库）
+
+通用约定（`--data`、分页、输出）见 `reference.md`。
+
+## organization（企业 / 成员 / 部门 / 团队 / 角色 / 职位）
+
+**查人只有这一个入口**：`pc organization user list --keywords "姓名"` → `values[].id`。
+工作项、迭代、评论里的 `assignee` / `created_by` / `participants` 都只给 ID，要把人显示成姓名时，
+先用它建映射。也可以用 `--name` / `--emails` / `--mobiles` 精确查。
+
+- `team get` 是**企业信息**（当前租户），不是「团队列表」；团队用 `group`。
+- `group-member add/remove` 用 `--data` 传成员，`get` 要 `group-id` + `member-id` 两个位置参数。
+- `role` / `job` 是字典，只读（只有 `list` / `get`）。
+- 部门、团队支持写（`create` / `update` / `delete`），改组织结构影响面大，**先 `get` 看清再改**。
+
+## wiki（知识空间与页面）
+
+- 找空间：`pc wiki space list --keywords "空间名"` → `values[].id`。
+- 列页面：`pc wiki page list --space-id <SID>`；按 `--parent-id` 看一层子页面，
+  按 `--ancestor-id` 拉整棵子树（找某个页面下的全部内容时用这个，别一层层点）。
+- **读正文用 `get-content`，不要用 `get`**：
+  `pc wiki page get-content <PAGE_ID> --format-type markdown`。格式可选
+  `text` / `markdown` / `html` / `block`，**服务端默认是 `text`**（纯文本，会丢结构），
+  要 markdown 必须显式传。
+- 写正文用 `update-content`（不是 `update`，`update` 走 PATCH，只改标题、父页面等元信息）。
+- 版本：`list-versions` / `get-version` / `restore-version`，改坏了可以回滚。
+- 删除空间 / 页面不可撤销，确认 ID 再执行。
+
+## 命令表
+
+### `organization department` — 部门（list / get / create / update / delete）
+
+```bash
+pc organization department list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization department get <DEPARTMENT_ID>
+pc organization department create --data <JSON>
+pc organization department update --data <JSON> <DEPARTMENT_ID>
+pc organization department delete <DEPARTMENT_ID>
+```
+
+### `organization group` — 团队（list / get / create / update）
+
+```bash
+pc organization group list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization group get <GROUP_ID>
+pc organization group create --data <JSON>
+pc organization group update --data <JSON> <GROUP_ID>
+```
+
+### `organization group-member` — 团队成员（list / get / add / remove）
+
+```bash
+pc organization group-member list <GROUP_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization group-member get <GROUP_ID> <MEMBER_ID>
+pc organization group-member add --data <JSON> <GROUP_ID>
+pc organization group-member remove <GROUP_ID> <MEMBER_ID>
+```
+
+### `organization job` — 职位（list / get）
+
+```bash
+pc organization job list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization job get <JOB_ID>
+```
+
+### `organization role` — 角色（list / get）
+
+```bash
+pc organization role list [--page-index <INDEX>] [--page-size <SIZE>]
+pc organization role get <ROLE_ID>
+```
+
+### `organization team` — 企业信息（get）
+
+```bash
+pc organization team get
+```
+
+### `organization user` — 成员（list / get / create / update / bulk-update）
+
+```bash
+pc organization user list [--name <NAME>] [--keywords <KEYWORDS>] [--emails <EMAILS>] \
+    [--mobiles <MOBILES>] [--department-ids <IDS>] [--page-index <INDEX>] \
+    [--page-size <SIZE>]
+pc organization user get <USER_ID>
+pc organization user create --data <JSON>
+pc organization user update --data <JSON> <USER_ID>
+pc organization user bulk-update --data <JSON>
+```
+### `wiki page` — 页面（list / get / create / update / delete / get-content / update-content / list-versions / get-version / restore-version）
+
+```bash
+pc wiki page list [--space-id <ID>] [--parent-id <ID>] [--ancestor-id <ID>] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki page get <PAGE_ID> [--include-deleted]
+pc wiki page create --data <JSON>
+pc wiki page update --data <JSON> <PAGE_ID>
+pc wiki page delete <PAGE_ID>
+pc wiki page get-content <PAGE_ID> [--format-type <FORMAT>] [--version-id <ID>] \
+    [--include-public-image-token <FIELDS>]
+pc wiki page update-content --data <JSON> <PAGE_ID>
+pc wiki page list-versions <PAGE_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki page get-version <PAGE_ID> <VERSION_ID>
+pc wiki page restore-version <PAGE_ID> <VERSION_ID>
+```
+
+### `wiki space` — 知识空间（list / get / create / update / delete）
+
+```bash
+pc wiki space list [--scope-type <TYPE>] [--scope-id <ID>] [--keywords <KEYWORDS>] \
+    [--member-type <TYPE>] [--member-id <ID>] [--created-between <RANGE>] \
+    [--updated-between <RANGE>] [--include-deleted] [--include-archived] \
+    [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki space get <SPACE_ID> [--include-deleted] [--include-archived]
+pc wiki space create --data <JSON>
+pc wiki space update --data <JSON> <SPACE_ID>
+pc wiki space delete <SPACE_ID>
+```
+
+### `wiki space-member` — 空间成员（list / get / add / remove）
+
+```bash
+pc wiki space-member list <SPACE_ID> [--page-index <INDEX>] [--page-size <SIZE>]
+pc wiki space-member get <SPACE_ID> <MEMBER_ID>
+pc wiki space-member add --data <JSON> <SPACE_ID>
+pc wiki space-member remove <SPACE_ID> <MEMBER_ID>
+```