pdlab-cli 0.1.2 → 0.2.0

package/README.md

@@ -33,6 +33,7 @@ pdlab login --api-url https://your-1836-instance.example.com
 ```bash
 pdlab whoami          # 看看当前是谁
 pdlab project list    # 列出项目
+pdlab schema          # 一次性 JSON 输出全部命令、参数、权限要求、示例和退出码含义——给 agent/脚本用
 ```
 
 ## 命令
@@ -44,20 +45,36 @@ pdlab project list    # 列出项目
 | `pdlab logout` | 清除本地凭证（不撤销服务端的，见下方「撤销凭证」） |
 | `pdlab whoami` | 查看当前登录账号 |
 | `pdlab config get` / `set api-url <url>` | 查看/修改本地配置 |
+| `pdlab schema` | JSON 输出完整命令树 + 权限要求 + 示例 + 退出码含义 |
 | `pdlab project list \| get \| create \| update \| delete` | 项目的增删改查 |
+| `pdlab project join \| leave <id>` | 报名共建 / 撤回申请或退出共建 |
+| `pdlab project member review \| set-role \| remove <projectId> <userId>` | 审核报名、设置协作者角色、移除参与者（仅项目发起人本人） |
+| `pdlab project revenue <id>` | 查看项目的积分分成明细（只读） |
 | `pdlab post list \| get \| create \| update \| delete` | 内容的增删改查 |
+| `pdlab post review <id> --action approve\|reject` | 审核一条待审内容 |
 
-任何命令加 `--help` 看具体参数。
+任何命令加 `--help` 看具体参数——示例已经直接打在 `--help` 末尾，不用等一次报错才能看到。
 
 ### 例子
 
 ```bash
-# 按状态筛选项目
+# 按状态 / 关键词 / 分类标签筛选项目，翻页
 pdlab project list --status active
+pdlab project list --q "钠电"
+pdlab project list --taxonomy tax_1 --taxonomy tax_2   # 可重复传，多个取交集
+pdlab project list --limit 10 --cursor <上一页返回的 nextCursor>
 
 # 创建项目（需要项目创建权限，即「1836发起人」角色）
 pdlab project create --title "钠电储能原型" --description "第一阶段验证"
 
+# 报名共建 / 退出
+pdlab project join proj_123
+pdlab project leave proj_123
+
+# 项目发起人审核报名、提拔协作者
+pdlab project member review proj_123 user_456 --status approved
+pdlab project member set-role proj_123 user_456 --role maintainer
+
 # 往自己参与的项目发布内容（共建者发布后进待审队列）
 pdlab post create \
   --project-id <项目 id> \
@@ -67,8 +84,40 @@ pdlab post create \
 
 # 只看某个项目下的内容
 pdlab post list --project-id <项目 id>
+
+# 审核待审内容（需要 content:review 权限）
+pdlab post review post_123 --action approve
+pdlab post review post_123 --action reject --comment "缺少数据来源，请补充引用"
 ```
 
+### 分页
+
+`project list` / `post list` 默认单页 30 条（上限 100），响应里的 `nextCursor` 非 `null`
+就表示还有下一页，把它传给下一次调用的 `--cursor` 继续翻页；`nextCursor` 为 `null`
+表示已经是最后一页。CLI 不会替你自动拉全量——那样一次调用可能悄悄发出几十次请求。
+
+### 报错与退出码
+
+失败时，一个 JSON 对象会打到 stderr（不是人类可读的长句），方便脚本/agent 解析：
+
+```json
+{ "error": "无权限执行此操作", "code": "forbidden", "status": 403 }
+```
+
+校验类错误还会带上 `fields`（哪个字段、什么问题）和 `hint`（对应命令的示例）。
+退出码和 `code` 一一对应，`pdlab schema` 的 `exitCodes` 字段里也有同一份：
+
+| 退出码 | `code` | 含义 | 建议的处理 |
+|---|---|---|---|
+| 0 | — | 成功 | — |
+| 2 | `validation` | 参数校验失败（本地或服务端） | 按 `fields`/`hint` 改参数重试 |
+| 3 | `unauthenticated` | 未登录或 token 已失效 | 跑 `pdlab login` |
+| 4 | `forbidden` | 无权限 | 不要重试，告知用户 |
+| 5 | `not_found` | 资源不存在 | 检查 id 是否正确 |
+| 6 | `conflict` | 状态冲突（如重复审核） | 不要重试，状态已经变了 |
+| 7 | `network` | 连不上 API 服务器 | 检查 `--api-url`/网络后重试 |
+| 1 | `unknown` / 未分类 | 其他 | 按错误信息人工排查 |
+
 ## 配置
 
 配置存在 `~/.pdlab/config.json`（目录 `0700`、文件 `0600`）：

package/dist/index.js

@@ -35,6 +35,17 @@ var import_open = __toESM(require("open"));
 var import_fs = require("fs");
 var import_os = require("os");
 var import_path = require("path");
+
+// src/cli-error.ts
+var CliError = class extends Error {
+  constructor(message, code = "unauthenticated") {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+
+// src/config.ts
 var CONFIG_DIR = process.env.PDLAB_CONFIG_DIR ?? (0, import_path.join)((0, import_os.homedir)(), ".pdlab");
 var CONFIG_FILE = (0, import_path.join)(CONFIG_DIR, "config.json");
 var DEFAULT_API_URL = "https://1836.online";
@@ -65,28 +76,53 @@ function optionalToken() {
 function requireToken() {
   const token = readConfig().token;
   if (!token) {
-    console.error("\u5C1A\u672A\u767B\u5F55\u3002\u8BF7\u5148\u8FD0\u884C `pdlab login`\u3002");
-    process.exit(1);
+    throw new CliError("\u5C1A\u672A\u767B\u5F55\u3002\u8BF7\u5148\u8FD0\u884C `pdlab login`\u3002");
   }
   return token;
 }
 
 // src/api-client.ts
+function classifyStatus(status) {
+  switch (status) {
+    case 400:
+    case 422:
+      return "validation";
+    case 401:
+      return "unauthenticated";
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 409:
+      return "conflict";
+    case 0:
+      return "network";
+    default:
+      return "unknown";
+  }
+}
 var ApiRequestError = class extends Error {
   constructor(message, status, details) {
     super(message);
     this.status = status;
     this.details = details;
+    this.code = classifyStatus(status);
   }
   status;
   details;
+  code;
 };
 async function apiRequest(path, options = {}) {
   const apiUrl = resolveApiUrl(options.apiUrl);
   const url = new URL(path.replace(/^\/+/, ""), apiUrl + "/");
   if (options.query) {
     for (const [key, value] of Object.entries(options.query)) {
-      if (value !== void 0) url.searchParams.set(key, value);
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        for (const v of value) url.searchParams.append(key, v);
+      } else {
+        url.searchParams.set(key, value);
+      }
     }
   }
   const headers = {};
@@ -304,41 +340,82 @@ var postReviewSchema = import_zod3.z.object({
 
 // src/errors.ts
 var import_zod4 = require("zod");
-function printValidationError(error, examples) {
-  console.error("\u53C2\u6570\u9519\u8BEF\uFF1A");
+var EXIT_CODES = {
+  ok: 0,
+  unhandled: 1,
+  validation: 2,
+  unauthenticated: 3,
+  forbidden: 4,
+  not_found: 5,
+  conflict: 6,
+  network: 7,
+  unknown: 1
+};
+function fieldsFromZod(error) {
+  const fields = {};
   for (const issue of error.issues) {
     const path = issue.path.length > 0 ? issue.path.join(".") : "(\u6839)";
-    console.error(`  - ${path}: ${issue.message}`);
+    (fields[path] ??= []).push(issue.message);
   }
-  printExamples(examples);
+  return fields;
 }
-function printExamples(examples) {
-  if (examples.length === 0) return;
-  console.error("\n\u793A\u4F8B\uFF1A");
-  for (const example of examples) {
-    console.error(`  $ ${example.command}`);
-    if (example.note) console.error(`    ${example.note}`);
-  }
+function fieldsFromApiDetails(details) {
+  if (!details || typeof details !== "object") return void 0;
+  const flat = details;
+  const fields = { ...flat.fieldErrors ?? {} };
+  if (flat.formErrors && flat.formErrors.length > 0) fields["(\u6839)"] = flat.formErrors;
+  return Object.keys(fields).length > 0 ? fields : void 0;
 }
-function printApiError(error) {
-  console.error(`\u9519\u8BEF\uFF1A${error.message}`);
-  if (error.details && typeof error.details === "object") {
-    const flat = error.details;
-    for (const [field, messages] of Object.entries(flat.fieldErrors ?? {})) {
-      for (const message of messages) console.error(`  - ${field}: ${message}`);
-    }
-    for (const message of flat.formErrors ?? []) console.error(`  - ${message}`);
-  }
+function exampleHint(examples) {
+  if (examples.length === 0) return void 0;
+  return examples.map((e) => e.command).join(" | ");
 }
-function handleCommandError(error, examples) {
+function handleCommandError(error, examples = []) {
+  let structured;
   if (error instanceof import_zod4.ZodError) {
-    printValidationError(error, examples);
+    structured = {
+      error: "\u53C2\u6570\u6821\u9A8C\u5931\u8D25",
+      code: "validation",
+      status: null,
+      fields: fieldsFromZod(error),
+      hint: exampleHint(examples)
+    };
   } else if (error instanceof ApiRequestError) {
-    printApiError(error);
+    structured = {
+      error: error.message,
+      code: error.code,
+      status: error.status || null,
+      fields: fieldsFromApiDetails(error.details),
+      hint: exampleHint(examples)
+    };
+  } else if (error instanceof CliError) {
+    structured = { error: error.message, code: error.code, status: null, hint: "pdlab login" };
   } else {
-    console.error(error);
+    structured = {
+      error: error instanceof Error ? error.message : String(error),
+      code: "unhandled",
+      status: null
+    };
   }
-  process.exit(1);
+  console.error(JSON.stringify(structured, null, 2));
+  process.exit(EXIT_CODES[structured.code] ?? 1);
+}
+
+// src/help-meta.ts
+var META = /* @__PURE__ */ new WeakMap();
+function attachMeta(command, meta) {
+  META.set(command, meta);
+  if (meta.examples && meta.examples.length > 0) {
+    command.addHelpText(
+      "after",
+      "\n\u793A\u4F8B\uFF1A\n" + meta.examples.map((e) => `  $ ${e.command}${e.note ? `
+    ${e.note}` : ""}`).join("\n")
+    );
+  }
+  return command;
+}
+function getMeta(command) {
+  return META.get(command) ?? {};
 }
 
 // src/commands/options.ts
@@ -347,15 +424,50 @@ function withApiUrl(cmd) {
 }
 
 // src/commands/project.ts
+var STATUS_LIST = PROJECT_STATUS_VALUES.join(" | ");
 var CREATE_EXAMPLES = [
   {
     command: 'pdlab project create --title "\u94A0\u7535\u56DE\u6536\u5DE5\u827A\u4F18\u5316" --description "..." --status planning --taxonomy-ids tax_1,tax_2',
-    note: "title \u5FC5\u586B\uFF0C\u5176\u4F59\u5B57\u6BB5\u53EF\u7701\u7565"
+    note: "title \u5FC5\u586B\uFF0C\u5176\u4F59\u5B57\u6BB5\u53EF\u7701\u7565\uFF1B\u9700\u8981\u300C1836\u53D1\u8D77\u4EBA\u300D\u89D2\u8272\uFF08project:create \u6743\u9650\uFF09"
   }
 ];
 var UPDATE_EXAMPLES = [
   { command: "pdlab project update proj_123 --progress 60 --status active", note: "\u53EA\u4F20\u8981\u6539\u7684\u5B57\u6BB5" }
 ];
+var LIST_EXAMPLES = [
+  { command: "pdlab project list --status active", note: "\u6309\u72B6\u6001\u7B5B\u9009" },
+  { command: 'pdlab project list --q "\u94A0\u7535"', note: "\u6309\u6807\u9898\u5173\u952E\u8BCD\u641C\u7D22" },
+  { command: "pdlab project list --taxonomy tax_1 --taxonomy tax_2", note: "\u53EF\u91CD\u590D\u4F20\uFF0C\u591A\u4E2A\u6807\u7B7E\u53D6\u4EA4\u96C6" },
+  { command: "pdlab project list --limit 10 --cursor <\u4E0A\u4E00\u9875\u8FD4\u56DE\u7684 nextCursor>", note: "\u7FFB\u9875\uFF1BnextCursor \u4E3A null \u8868\u793A\u6CA1\u6709\u4E0B\u4E00\u9875\u4E86" }
+];
+var GET_EXAMPLES = [{ command: "pdlab project get proj_123" }];
+var DELETE_EXAMPLES = [
+  { command: "pdlab project delete proj_123", note: "\u9700\u8981\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\uFF0C\u4E14\u9879\u76EE\u4E0B\u6CA1\u6709\u5185\u5BB9/\u79EF\u5206\u8BB0\u5F55" }
+];
+var JOIN_EXAMPLES = [
+  { command: "pdlab project join proj_123", note: "\u62A5\u540D\u5171\u5EFA\uFF0C\u8FDB\u5165\u5F85\u5BA1\u6838\uFF1B\u91CD\u590D\u8C03\u7528\u662F\u5E42\u7B49\u7684" }
+];
+var LEAVE_EXAMPLES = [
+  { command: "pdlab project leave proj_123", note: "\u64A4\u56DE\u62A5\u540D\u7533\u8BF7\uFF0C\u6216\u9000\u51FA\u5DF2\u901A\u8FC7\u5BA1\u6838\u7684\u5171\u5EFA" }
+];
+var MEMBER_REVIEW_EXAMPLES = [
+  {
+    command: "pdlab project member review proj_123 user_456 --status approved",
+    note: "\u5BA1\u6838\u4E00\u6761 pending \u7684\u62A5\u540D\u7533\u8BF7\uFF1B\u53EA\u6709\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA\u80FD\u8C03\u7528"
+  }
+];
+var MEMBER_SET_ROLE_EXAMPLES = [
+  {
+    command: "pdlab project member set-role proj_123 user_456 --role maintainer",
+    note: "\u4EC5\u5BF9\u5DF2\u901A\u8FC7\u5BA1\u6838\uFF08approved\uFF09\u7684\u53C2\u4E0E\u8005\u751F\u6548\uFF1B\u53EA\u6709\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA\u80FD\u8C03\u7528"
+  }
+];
+var MEMBER_REMOVE_EXAMPLES = [
+  { command: "pdlab project member remove proj_123 user_456", note: "\u53EA\u6709\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA\u80FD\u8C03\u7528" }
+];
+var REVENUE_EXAMPLES = [
+  { command: "pdlab project revenue proj_123", note: "\u53EA\u8BFB\uFF0C\u9700\u8981 data:view_stats \u6743\u9650" }
+];
 function toBody(opts) {
   const body = {};
   if (opts.title !== void 0) body.title = opts.title;
@@ -370,26 +482,43 @@ function toBody(opts) {
   return body;
 }
 function withProjectFlags(cmd) {
-  return withApiUrl(cmd).option("--title <title>", "\u9879\u76EE\u6807\u9898").option("--description <description>", "\u9879\u76EE\u63CF\u8FF0").option("--cover-image <url>", "\u5C01\u9762\u56FE http/https \u94FE\u63A5").option("--commercial-type <type>", "\u5546\u4E1A\u5C5E\u6027").option("--status <status>", "planning | active | review | completed").option("--progress <percent>", "\u8FDB\u5EA6 0-100").option("--taxonomy-ids <ids>", "\u9017\u53F7\u5206\u9694\u7684\u5206\u7C7B\u6807\u7B7E id \u5217\u8868");
+  return withApiUrl(cmd).option("--title <title>", "\u9879\u76EE\u6807\u9898\uFF08\u5FC5\u586B\uFF0C1-200 \u5B57\uFF09").option("--description <description>", "\u9879\u76EE\u63CF\u8FF0\uFF08\u9009\u586B\uFF0C\u6700\u591A 20000 \u5B57\uFF09").option("--cover-image <url>", "\u5C01\u9762\u56FE http/https \u94FE\u63A5\uFF08\u9009\u586B\uFF09").option("--commercial-type <type>", "\u5546\u4E1A\u5C5E\u6027\uFF08\u9009\u586B\uFF09").option("--status <status>", `\u9879\u76EE\u72B6\u6001\uFF1A${STATUS_LIST}\uFF08\u9009\u586B\uFF09`).option("--progress <percent>", "\u8FDB\u5EA6\uFF0C\u6574\u6570 0-100\uFF08\u9009\u586B\uFF09").option("--taxonomy-ids <ids>", "\u9017\u53F7\u5206\u9694\u7684\u5206\u7C7B\u6807\u7B7E id \u5217\u8868\uFF0C\u5168\u91CF\u66FF\u6362\uFF08\u9009\u586B\uFF09");
+}
+function collect(value, previous) {
+  return previous.concat([value]);
 }
 function registerProjectCommand(program2) {
-  const project = program2.command("project").description("\u9879\u76EE\u7684\u589E\u5220\u6539\u67E5");
-  withApiUrl(project.command("list").description("\u5217\u51FA\u9879\u76EE")).option("--status <status>", "\u6309\u72B6\u6001\u7B5B\u9009\uFF1Aplanning | active | review | completed").action(async (opts) => {
-    const data = await apiRequest("/api/projects", {
-      query: { status: opts.status },
-      token: optionalToken(),
-      apiUrl: opts.apiUrl
-    });
-    console.log(JSON.stringify(data, null, 2));
-  });
-  withApiUrl(project.command("get <id>").description("\u67E5\u770B\u9879\u76EE\u8BE6\u60C5")).action(
-    async (id, opts) => {
-      const data = await apiRequest(`/api/projects/${id}`, { token: optionalToken(), apiUrl: opts.apiUrl });
-      console.log(JSON.stringify(data, null, 2));
-    }
+  const project = program2.command("project").description("\u9879\u76EE\u7684\u589E\u5220\u6539\u67E5\u3001\u62A5\u540D\u5171\u5EFA\u3001\u6210\u5458\u7BA1\u7406\u3001\u6536\u76CA\u67E5\u8BE2");
+  attachMeta(
+    withApiUrl(project.command("list").description("\u5217\u51FA\u9879\u76EE\uFF08\u516C\u5F00\u53EA\u8BFB\uFF0C\u4E0D\u767B\u5F55\u4E5F\u80FD\u7528\uFF09")).option("--status <status>", `\u6309\u72B6\u6001\u7B5B\u9009\uFF1A${STATUS_LIST}`).option("--q <keyword>", "\u6309\u6807\u9898\u5173\u952E\u8BCD\u641C\u7D22").option("--taxonomy <id>", "\u6309\u5206\u7C7B\u6807\u7B7E id \u7B5B\u9009\uFF0C\u53EF\u91CD\u590D\u4F20\uFF0C\u591A\u4E2A\u53D6\u4EA4\u96C6", collect, []).option("--limit <n>", "\u5355\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 30\uFF0C\u4E0A\u9650 100").option("--cursor <token>", "\u7FFB\u9875\u6E38\u6807\uFF0C\u53D6\u4E0A\u4E00\u9875\u54CD\u5E94\u91CC\u7684 nextCursor").action(
+      async (opts) => {
+        const data = await apiRequest("/api/projects", {
+          query: {
+            status: opts.status,
+            q: opts.q,
+            taxonomy: opts.taxonomy.length > 0 ? opts.taxonomy : void 0,
+            limit: opts.limit,
+            cursor: opts.cursor
+          },
+          token: optionalToken(),
+          apiUrl: opts.apiUrl
+        });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { examples: LIST_EXAMPLES }
   );
-  withProjectFlags(project.command("create").description("\u521B\u5EFA\u9879\u76EE\uFF08\u9700\u8981\u9879\u76EE\u521B\u5EFA\u6743\u9650\uFF09")).action(
-    async (opts) => {
+  attachMeta(
+    withApiUrl(project.command("get <id>").description("\u67E5\u770B\u9879\u76EE\u8BE6\u60C5\uFF08\u516C\u5F00\u53EA\u8BFB\uFF0C\u4E0D\u767B\u5F55\u4E5F\u80FD\u7528\uFF09")).action(
+      async (id, opts) => {
+        const data = await apiRequest(`/api/projects/${id}`, { token: optionalToken(), apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { examples: GET_EXAMPLES }
+  );
+  attachMeta(
+    withProjectFlags(project.command("create").description("\u521B\u5EFA\u9879\u76EE")).action(async (opts) => {
       const token = requireToken();
       try {
         const body = projectCreateSchema.parse(toBody(opts));
@@ -398,99 +527,275 @@ function registerProjectCommand(program2) {
       } catch (error) {
         handleCommandError(error, CREATE_EXAMPLES);
       }
+    }),
+    { permission: "project:create\uFF081836\u53D1\u8D77\u4EBA\u89D2\u8272\uFF09", examples: CREATE_EXAMPLES }
+  );
+  attachMeta(
+    withProjectFlags(project.command("update <id>").description("\u66F4\u65B0\u9879\u76EE")).action(
+      async (id, opts) => {
+        const token = requireToken();
+        try {
+          const body = projectUpdateSchema.parse(toBody(opts));
+          const data = await apiRequest(`/api/projects/${id}`, { method: "PATCH", body, token, apiUrl: opts.apiUrl });
+          console.log(JSON.stringify(data, null, 2));
+        } catch (error) {
+          handleCommandError(error, UPDATE_EXAMPLES);
+        }
+      }
+    ),
+    {
+      permission: "project:update_progress\uFF08\u53D1\u8D77\u4EBA\uFF09\u6216 project:join\uFF08\u534F\u4F5C\u8005\uFF0C\u4EC5\u80FD\u6539 progress/status/description\uFF09",
+      examples: UPDATE_EXAMPLES
     }
   );
-  withProjectFlags(project.command("update <id>").description("\u66F4\u65B0\u9879\u76EE")).action(
-    async (id, opts) => {
+  attachMeta(
+    withApiUrl(
+      project.command("delete <id>").description("\u5220\u9664\u9879\u76EE\uFF08\u9700\u8981\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\uFF0C\u4E14\u9879\u76EE\u4E0B\u6CA1\u6709\u5185\u5BB9/\u79EF\u5206\u8BB0\u5F55\uFF09")
+    ).action(async (id, opts) => {
       const token = requireToken();
-      try {
-        const body = projectUpdateSchema.parse(toBody(opts));
-        const data = await apiRequest(`/api/projects/${id}`, { method: "PATCH", body, token, apiUrl: opts.apiUrl });
+      const data = await apiRequest(`/api/projects/${id}`, { method: "DELETE", token, apiUrl: opts.apiUrl });
+      console.log(JSON.stringify(data, null, 2));
+    }),
+    { permission: "project:create\uFF081836\u53D1\u8D77\u4EBA\u89D2\u8272\uFF09\uFF0C\u4E14\u5FC5\u987B\u662F\u8BE5\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA", examples: DELETE_EXAMPLES }
+  );
+  attachMeta(
+    withApiUrl(project.command("join <id>").description("\u62A5\u540D\u5171\u5EFA\u8BE5\u9879\u76EE\uFF0C\u8FDB\u5165\u5F85\u5BA1\u6838")).action(
+      async (id, opts) => {
+        const token = requireToken();
+        const data = await apiRequest(`/api/projects/${id}/join`, { method: "POST", token, apiUrl: opts.apiUrl });
         console.log(JSON.stringify(data, null, 2));
-      } catch (error) {
-        handleCommandError(error, UPDATE_EXAMPLES);
       }
-    }
+    ),
+    { permission: "project:join\uFF081836\u5171\u5EFA\u8005\u7B49\u89D2\u8272\uFF09", examples: JOIN_EXAMPLES }
+  );
+  attachMeta(
+    withApiUrl(project.command("leave <id>").description("\u64A4\u56DE\u62A5\u540D\u7533\u8BF7\uFF0C\u6216\u9000\u51FA\u5DF2\u901A\u8FC7\u5BA1\u6838\u7684\u5171\u5EFA")).action(
+      async (id, opts) => {
+        const token = requireToken();
+        const data = await apiRequest(`/api/projects/${id}/join`, { method: "DELETE", token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { permission: "project:join\uFF081836\u5171\u5EFA\u8005\u7B49\u89D2\u8272\uFF09", examples: LEAVE_EXAMPLES }
+  );
+  const member = project.command("member").description("\u9879\u76EE\u53C2\u4E0E\u8005\u7684\u5BA1\u6838 / \u89D2\u8272 / \u79FB\u9664\uFF08\u4EC5\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA\u53EF\u7528\uFF09");
+  attachMeta(
+    withApiUrl(member.command("review <projectId> <userId>").description("\u5BA1\u6838\u4E00\u6761 pending \u7684\u62A5\u540D\u7533\u8BF7")).requiredOption("--status <status>", "approved | rejected").action(async (projectId, userId, opts) => {
+      const token = requireToken();
+      const data = await apiRequest(`/api/projects/${projectId}/members/${userId}`, {
+        method: "PATCH",
+        body: { status: opts.status },
+        token,
+        apiUrl: opts.apiUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    }),
+    { permission: "project:update_progress\uFF0C\u4E14\u5FC5\u987B\u662F\u8BE5\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA", examples: MEMBER_REVIEW_EXAMPLES }
+  );
+  attachMeta(
+    withApiUrl(member.command("set-role <projectId> <userId>").description("\u8BBE\u7F6E\u5DF2\u901A\u8FC7\u5BA1\u6838\u7684\u53C2\u4E0E\u8005\u7684\u9879\u76EE\u5185\u89D2\u8272")).requiredOption("--role <role>", "member | maintainer").action(async (projectId, userId, opts) => {
+      const token = requireToken();
+      const data = await apiRequest(`/api/projects/${projectId}/members/${userId}`, {
+        method: "PATCH",
+        body: { role: opts.role },
+        token,
+        apiUrl: opts.apiUrl
+      });
+      console.log(JSON.stringify(data, null, 2));
+    }),
+    { permission: "project:update_progress\uFF0C\u4E14\u5FC5\u987B\u662F\u8BE5\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA", examples: MEMBER_SET_ROLE_EXAMPLES }
+  );
+  attachMeta(
+    withApiUrl(member.command("remove <projectId> <userId>").description("\u79FB\u9664\u4E00\u4E2A\u53C2\u4E0E\u8005")).action(
+      async (projectId, userId, opts) => {
+        const token = requireToken();
+        const data = await apiRequest(`/api/projects/${projectId}/members/${userId}`, {
+          method: "DELETE",
+          token,
+          apiUrl: opts.apiUrl
+        });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { permission: "project:update_progress\uFF0C\u4E14\u5FC5\u987B\u662F\u8BE5\u9879\u76EE\u53D1\u8D77\u4EBA\u672C\u4EBA", examples: MEMBER_REMOVE_EXAMPLES }
+  );
+  attachMeta(
+    withApiUrl(project.command("revenue <id>").description("\u67E5\u770B\u9879\u76EE\u7684\u79EF\u5206\u5206\u6210\u660E\u7EC6\uFF08\u53EA\u8BFB\uFF09")).action(
+      async (id, opts) => {
+        const token = requireToken();
+        const data = await apiRequest(`/api/projects/${id}/revenue-breakdown`, { token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { permission: "data:view_stats", examples: REVENUE_EXAMPLES }
   );
-  withApiUrl(
-    project.command("delete <id>").description("\u5220\u9664\u9879\u76EE\uFF08\u9700\u8981\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\uFF0C\u4E14\u9879\u76EE\u4E0B\u6CA1\u6709\u5185\u5BB9/\u79EF\u5206\u8BB0\u5F55\uFF09")
-  ).action(async (id, opts) => {
-    const token = requireToken();
-    const data = await apiRequest(`/api/projects/${id}`, { method: "DELETE", token, apiUrl: opts.apiUrl });
-    console.log(JSON.stringify(data, null, 2));
-  });
 }
 
 // src/commands/post.ts
 var CREATE_EXAMPLES2 = [
   {
     command: 'pdlab post create --title "\u7B2C\u4E00\u5468\u8FDB\u5C55" --body "..." --project-id proj_123 --media-links https://example.com/a.png',
-    note: "title / body / project-id \u5FC5\u586B"
+    note: "title / body / project-id \u5FC5\u586B\uFF1B\u9700\u8981\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\u6216\u5DF2\u62A5\u540D\u5171\u5EFA\u8BE5\u9879\u76EE"
+  }
+];
+var UPDATE_EXAMPLES2 = [
+  { command: 'pdlab post update post_123 --title "..." --body "..."', note: "title \u548C body \u90FD\u5FC5\u987B\u4F20" }
+];
+var LIST_EXAMPLES2 = [
+  { command: "pdlab post list --project-id proj_123", note: "\u53EA\u770B\u67D0\u4E2A\u9879\u76EE\u4E0B\u7684\u5185\u5BB9" },
+  { command: "pdlab post list --status pending", note: "\u67E5\u770B\u5F85\u5BA1\u6838\u5185\u5BB9\uFF0C\u9700\u8981 content:review \u6743\u9650\uFF0C\u5426\u5219 403" },
+  { command: "pdlab post list --limit 10 --cursor <\u4E0A\u4E00\u9875\u8FD4\u56DE\u7684 nextCursor>", note: "\u7FFB\u9875\uFF1BnextCursor \u4E3A null \u8868\u793A\u6CA1\u6709\u4E0B\u4E00\u9875\u4E86" }
+];
+var GET_EXAMPLES2 = [{ command: "pdlab post get post_123" }];
+var DELETE_EXAMPLES2 = [
+  { command: "pdlab post delete post_123", note: "\u4F5C\u8005\u672C\u4EBA\uFF0C\u6216\u6709\u5220\u9664\u4EFB\u610F\u5185\u5BB9\u7684\u6743\u9650" }
+];
+var REVIEW_EXAMPLES = [
+  {
+    command: "pdlab post review post_123 --action approve",
+    note: "\u901A\u8FC7\u5BA1\u6838\uFF1B\u4F5C\u8005\u4E0D\u80FD\u5BA1\u81EA\u5DF1\u53D1\u5E03\u7684\u5185\u5BB9\uFF08403\uFF09\uFF0C\u53EA\u80FD\u5BA1 pending \u72B6\u6001\u7684\u5185\u5BB9\uFF08\u975E pending \u4F1A 409\uFF09"
+  },
+  {
+    command: 'pdlab post review post_123 --action reject --comment "\u7F3A\u5C11\u6570\u636E\u6765\u6E90\uFF0C\u8BF7\u8865\u5145\u5F15\u7528"',
+    note: "\u9A73\u56DE\u65F6\u5FC5\u987B\u586B\u5199 --comment\uFF0C\u5426\u5219 400"
   }
 ];
-var UPDATE_EXAMPLES2 = [{ command: 'pdlab post update post_123 --title "..." --body "..."', note: "title \u548C body \u90FD\u5FC5\u987B\u4F20" }];
 function toMediaLinks(value) {
   if (value === void 0) return void 0;
   return value.split(",").map((url) => url.trim()).filter(Boolean);
 }
 function registerPostCommand(program2) {
-  const post = program2.command("post").description("\u5185\u5BB9\uFF08\u5E16\u5B50\uFF09\u7684\u589E\u5220\u6539\u67E5");
-  withApiUrl(post.command("list").description("\u5217\u51FA\u5185\u5BB9")).option("--project-id <id>", "\u6309\u9879\u76EE\u7B5B\u9009").option("--status <status>", "pending | approved | rejected\uFF08\u67E5\u770B\u975E approved \u9700\u8981\u5BA1\u6838\u6743\u9650\uFF09").action(async (opts) => {
-    const data = await apiRequest("/api/posts", {
-      query: { projectId: opts.projectId, status: opts.status },
-      token: optionalToken(),
-      apiUrl: opts.apiUrl
-    });
-    console.log(JSON.stringify(data, null, 2));
-  });
-  withApiUrl(post.command("get <id>").description("\u67E5\u770B\u5185\u5BB9\u8BE6\u60C5")).action(
-    async (id, opts) => {
-      const data = await apiRequest(`/api/posts/${id}`, { token: optionalToken(), apiUrl: opts.apiUrl });
-      console.log(JSON.stringify(data, null, 2));
-    }
-  );
-  withApiUrl(post.command("create").description("\u53D1\u5E03\u5185\u5BB9\uFF08\u9700\u8981\u5185\u5BB9\u521B\u5EFA\u6743\u9650\uFF0C\u4E14\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\u6216\u5DF2\u62A5\u540D\u5171\u5EFA\uFF09")).option("--title <title>", "\u5185\u5BB9\u6807\u9898").option("--body <body>", "\u5185\u5BB9\u6B63\u6587").option("--project-id <id>", "\u6240\u5C5E\u9879\u76EE id").option("--media-links <urls>", "\u9017\u53F7\u5206\u9694\u7684\u5A92\u4F53\u94FE\u63A5").action(async (opts) => {
-    const token = requireToken();
-    try {
-      const body = postCreateSchema.parse({
-        title: opts.title,
-        body: opts.body,
-        projectId: opts.projectId,
-        mediaLinks: toMediaLinks(opts.mediaLinks)
+  const post = program2.command("post").description("\u5185\u5BB9\uFF08\u5E16\u5B50\uFF09\u7684\u589E\u5220\u6539\u67E5\u4E0E\u5BA1\u6838");
+  attachMeta(
+    withApiUrl(post.command("list").description("\u5217\u51FA\u5185\u5BB9\uFF08approved \u5185\u5BB9\u516C\u5F00\u53EA\u8BFB\uFF0C\u4E0D\u767B\u5F55\u4E5F\u80FD\u7528\uFF09")).option("--project-id <id>", "\u6309\u9879\u76EE\u7B5B\u9009").option("--status <status>", "pending | approved | rejected\uFF08\u67E5\u770B\u975E approved \u9700\u8981\u5BA1\u6838\u6743\u9650\uFF09").option("--limit <n>", "\u5355\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 30\uFF0C\u4E0A\u9650 100").option("--cursor <token>", "\u7FFB\u9875\u6E38\u6807\uFF0C\u53D6\u4E0A\u4E00\u9875\u54CD\u5E94\u91CC\u7684 nextCursor").action(async (opts) => {
+      const data = await apiRequest("/api/posts", {
+        query: { projectId: opts.projectId, status: opts.status, limit: opts.limit, cursor: opts.cursor },
+        token: optionalToken(),
+        apiUrl: opts.apiUrl
       });
-      const data = await apiRequest("/api/posts", { method: "POST", body, token, apiUrl: opts.apiUrl });
       console.log(JSON.stringify(data, null, 2));
-    } catch (error) {
-      handleCommandError(error, CREATE_EXAMPLES2);
-    }
-  });
-  withApiUrl(post.command("update <id>").description("\u7F16\u8F91\u5185\u5BB9\uFF08\u4F5C\u8005\u672C\u4EBA\uFF0C\u6216\u6709\u7F16\u8F91\u4EFB\u610F\u5185\u5BB9\u7684\u6743\u9650\uFF09")).option("--title <title>", "\u5185\u5BB9\u6807\u9898").option("--body <body>", "\u5185\u5BB9\u6B63\u6587").option("--media-links <urls>", "\u9017\u53F7\u5206\u9694\u7684\u5A92\u4F53\u94FE\u63A5").action(async (id, opts) => {
-    const token = requireToken();
-    try {
-      const body = postUpdateSchema.parse({
-        title: opts.title,
-        body: opts.body,
-        mediaLinks: toMediaLinks(opts.mediaLinks)
-      });
-      const data = await apiRequest(`/api/posts/${id}`, { method: "PATCH", body, token, apiUrl: opts.apiUrl });
-      console.log(JSON.stringify(data, null, 2));
-    } catch (error) {
-      handleCommandError(error, UPDATE_EXAMPLES2);
-    }
-  });
-  withApiUrl(post.command("delete <id>").description("\u5220\u9664\u5185\u5BB9\uFF08\u4F5C\u8005\u672C\u4EBA\uFF0C\u6216\u6709\u5220\u9664\u4EFB\u610F\u5185\u5BB9\u7684\u6743\u9650\uFF09")).action(
-    async (id, opts) => {
+    }),
+    { examples: LIST_EXAMPLES2 }
+  );
+  attachMeta(
+    withApiUrl(post.command("get <id>").description("\u67E5\u770B\u5185\u5BB9\u8BE6\u60C5")).action(
+      async (id, opts) => {
+        const data = await apiRequest(`/api/posts/${id}`, { token: optionalToken(), apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { examples: GET_EXAMPLES2 }
+  );
+  attachMeta(
+    withApiUrl(post.command("create").description("\u53D1\u5E03\u5185\u5BB9")).option("--title <title>", "\u5185\u5BB9\u6807\u9898\uFF08\u5FC5\u586B\uFF09").option("--body <body>", "\u5185\u5BB9\u6B63\u6587\uFF08\u5FC5\u586B\uFF09").option("--project-id <id>", "\u6240\u5C5E\u9879\u76EE id\uFF08\u5FC5\u586B\uFF09").option("--media-links <urls>", "\u9017\u53F7\u5206\u9694\u7684\u5A92\u4F53\u94FE\u63A5\uFF08\u9009\u586B\uFF0C\u6700\u591A 20 \u6761\uFF0Chttp/https\uFF09").action(async (opts) => {
       const token = requireToken();
-      const data = await apiRequest(`/api/posts/${id}`, { method: "DELETE", token, apiUrl: opts.apiUrl });
-      console.log(JSON.stringify(data, null, 2));
-    }
+      try {
+        const body = postCreateSchema.parse({
+          title: opts.title,
+          body: opts.body,
+          projectId: opts.projectId,
+          mediaLinks: toMediaLinks(opts.mediaLinks)
+        });
+        const data = await apiRequest("/api/posts", { method: "POST", body, token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      } catch (error) {
+        handleCommandError(error, CREATE_EXAMPLES2);
+      }
+    }),
+    { permission: "content:create\uFF0C\u4E14\u662F\u9879\u76EE\u53D1\u8D77\u4EBA\u6216\u5DF2\u62A5\u540D\u5171\u5EFA\u8BE5\u9879\u76EE", examples: CREATE_EXAMPLES2 }
   );
+  attachMeta(
+    withApiUrl(post.command("update <id>").description("\u7F16\u8F91\u5185\u5BB9\uFF08\u4F5C\u8005\u672C\u4EBA\uFF0C\u6216\u6709\u7F16\u8F91\u4EFB\u610F\u5185\u5BB9\u7684\u6743\u9650\uFF09")).option("--title <title>", "\u5185\u5BB9\u6807\u9898\uFF08\u5FC5\u586B\uFF09").option("--body <body>", "\u5185\u5BB9\u6B63\u6587\uFF08\u5FC5\u586B\uFF09").option("--media-links <urls>", "\u9017\u53F7\u5206\u9694\u7684\u5A92\u4F53\u94FE\u63A5\uFF08\u9009\u586B\uFF0C\u6700\u591A 20 \u6761\uFF0Chttp/https\uFF09").action(async (id, opts) => {
+      const token = requireToken();
+      try {
+        const body = postUpdateSchema.parse({
+          title: opts.title,
+          body: opts.body,
+          mediaLinks: toMediaLinks(opts.mediaLinks)
+        });
+        const data = await apiRequest(`/api/posts/${id}`, { method: "PATCH", body, token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      } catch (error) {
+        handleCommandError(error, UPDATE_EXAMPLES2);
+      }
+    }),
+    { examples: UPDATE_EXAMPLES2 }
+  );
+  attachMeta(
+    withApiUrl(post.command("delete <id>").description("\u5220\u9664\u5185\u5BB9\uFF08\u4F5C\u8005\u672C\u4EBA\uFF0C\u6216\u6709\u5220\u9664\u4EFB\u610F\u5185\u5BB9\u7684\u6743\u9650\uFF09")).action(
+      async (id, opts) => {
+        const token = requireToken();
+        const data = await apiRequest(`/api/posts/${id}`, { method: "DELETE", token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      }
+    ),
+    { examples: DELETE_EXAMPLES2 }
+  );
+  attachMeta(
+    withApiUrl(post.command("review <id>").description("\u5BA1\u6838\u4E00\u6761\u5F85\u5BA1\u5185\u5BB9\uFF08approve / reject\uFF09")).requiredOption("--action <action>", "approve | reject").option("--comment <text>", "\u5BA1\u6838\u610F\u89C1\uFF0C\u6700\u591A 500 \u5B57\uFF08reject \u65F6\u5FC5\u586B\uFF09").action(async (id, opts) => {
+      const token = requireToken();
+      try {
+        const body = postReviewSchema.parse({ action: opts.action, reviewComment: opts.comment });
+        const data = await apiRequest(`/api/posts/${id}/review`, { method: "POST", body, token, apiUrl: opts.apiUrl });
+        console.log(JSON.stringify(data, null, 2));
+      } catch (error) {
+        handleCommandError(error, REVIEW_EXAMPLES);
+      }
+    }),
+    { permission: "content:review\uFF0C\u4E14\u4E0D\u80FD\u5BA1\u6838\u81EA\u5DF1\u53D1\u5E03\u7684\u5185\u5BB9", examples: REVIEW_EXAMPLES }
+  );
+}
+
+// src/commands/schema.ts
+var CODE_DESCRIPTION = {
+  ok: "\u6210\u529F",
+  unhandled: "\u672A\u5206\u7C7B\u9519\u8BEF",
+  validation: "\u53C2\u6570\u6821\u9A8C\u5931\u8D25\uFF08\u672C\u5730\u6216\u670D\u52A1\u7AEF\uFF09",
+  unauthenticated: "\u672A\u767B\u5F55\u6216 token \u5DF2\u5931\u6548\uFF0C\u9700\u8981 pdlab login",
+  forbidden: "\u65E0\u6743\u9650\uFF08\u670D\u52A1\u7AEF 403\uFF09",
+  not_found: "\u8D44\u6E90\u4E0D\u5B58\u5728\uFF08\u670D\u52A1\u7AEF 404\uFF09",
+  conflict: "\u72B6\u6001\u51B2\u7A81\uFF0C\u4F8B\u5982\u91CD\u590D\u5BA1\u6838\uFF08\u670D\u52A1\u7AEF 409\uFF09",
+  network: "\u8FDE\u4E0D\u4E0A API \u670D\u52A1\u5668",
+  unknown: "\u672A\u5206\u7C7B\u7684\u670D\u52A1\u7AEF\u9519\u8BEF"
+};
+function exitCodeTable() {
+  const table = {};
+  for (const [code, exitStatus] of Object.entries(EXIT_CODES)) {
+    if (table[exitStatus] === void 0) table[exitStatus] = CODE_DESCRIPTION[code];
+  }
+  return table;
+}
+function serialize(command) {
+  const meta = getMeta(command);
+  return {
+    name: command.name(),
+    description: command.description(),
+    permission: meta.permission,
+    arguments: command.registeredArguments.map((a) => ({ name: a.name(), required: a.required })),
+    options: command.options.map((o) => ({ flags: o.flags, description: o.description, required: o.mandatory })),
+    examples: meta.examples ?? [],
+    subcommands: command.commands.map(serialize)
+  };
+}
+function registerSchemaCommand(program2) {
+  program2.command("schema").description("\u4EE5 JSON \u8F93\u51FA\u5B8C\u6574\u547D\u4EE4\u6811\uFF08\u542B\u53C2\u6570\u3001\u6743\u9650\u8981\u6C42\u3001\u793A\u4F8B\uFF09\u548C\u9000\u51FA\u7801\u542B\u4E49\uFF0C\u4F9B agent/\u811A\u672C\u4E00\u6B21\u6027\u8BFB\u53D6").action(() => {
+    console.log(
+      JSON.stringify(
+        {
+          exitCodes: exitCodeTable(),
+          commands: program2.commands.map(serialize)
+        },
+        null,
+        2
+      )
+    );
+  });
 }
 
 // src/index.ts
 var pkg = JSON.parse((0, import_fs2.readFileSync)((0, import_path2.join)(__dirname, "../package.json"), "utf8"));
 var program = new import_commander.Command();
-program.name("pdlab").description("1836 \u5F00\u6E90\u5171\u5EFA\u5E73\u53F0\u547D\u4EE4\u884C\u5DE5\u5177\u2014\u2014\u662F\u73B0\u6709 REST API \u7684\u8584\u5C01\u88C5").version(pkg.version);
+program.name("pdlab").description("1836 \u5F00\u6E90\u5171\u5EFA\u5E73\u53F0\u547D\u4EE4\u884C\u5DE5\u5177\u2014\u2014\u662F\u73B0\u6709 REST API \u7684\u8584\u5C01\u88C5\u3002\u7ED9 agent/\u811A\u672C\u7528\uFF1Apdlab schema \u4E00\u6B21\u6027\u5217\u51FA\u5168\u90E8\u547D\u4EE4\u3001\u53C2\u6570\u4E0E\u9000\u51FA\u7801\u542B\u4E49\u3002").version(pkg.version);
 registerLoginCommand(program);
 registerRegisterCommand(program);
 registerLogoutCommand(program);
@@ -498,11 +803,7 @@ registerWhoamiCommand(program);
 registerConfigCommand(program);
 registerProjectCommand(program);
 registerPostCommand(program);
+registerSchemaCommand(program);
 program.parseAsync(process.argv).catch((error) => {
-  if (error instanceof ApiRequestError) {
-    console.error(`\u9519\u8BEF\uFF1A${error.message}`);
-  } else {
-    console.error(error);
-  }
-  process.exit(1);
+  handleCommandError(error);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdlab-cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "description": "1836 开源共建平台（problem-driven-lab）的命令行工具：项目、内容的增删改查，浏览器授权登录",
   "keywords": [