wkgeo-cli 0.2.0

package/lib/api.mjs

@@ -0,0 +1,178 @@
+/**
+ * 业务 API 封装：`/api/data`（业务面）+ `/api/oauth/*`（授权面）。
+ *
+ * 设计约定：
+ *   1. **只在这里碰 HTTP**。命令层拿到的要么是 `data`，要么是抛出的 CliError。
+ *   2. `data()` 返回的是信封里的 `data` 字段（服务端 `ok(x)` → `{code:0,data:x}`）。
+ *      如果某个 action 的 data 是标量（字符串/数组），也原样返回。
+ *   3. **不做自动重试**。限流(429)自动重试会掩盖问题，也让"写操作"变得不可预测（重试下单=重复下单！）。
+ *      只在错误里给出 retry_after，让人/脚本决定。
+ *   4. token 只在 Authorization 头里出现；**任何日志/错误里都不带 token**。
+ */
+
+import { request, encodeForm } from './http.mjs';
+import { classifyResponse, toCliError, networkError, CliError } from './errors.mjs';
+
+export function createApi({ config, fetchImpl = globalThis.fetch } = {}) {
+  const base = config.base;
+  const timeoutMs = config.httpTimeoutMs;
+
+  async function raw(url, options = {}) {
+    return request(url, { ...options, fetchImpl, timeoutMs: options.timeoutMs ?? timeoutMs });
+  }
+
+  /** 决定成败的唯一依据是 body.code（项目约定 HTTP 恒 200） */
+  function unwrap(res, action) {
+    if (res.networkError) throw networkError(res.networkError, { raw: res });
+    const cls = classifyResponse({
+      httpStatus: res.status,
+      body: res.body,
+      action,
+      retryAfterHeader: res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null,
+      cmdName: config.cmdName || 'wkgeo',
+    });
+    if (!cls.ok) throw toCliError(cls, { action, raw: { status: res.status, body: res.body } });
+    return res.body ? res.body.data : null;
+  }
+
+  return {
+    config,
+
+    /** 业务面：POST /api/data {action, ...payload} */
+    async data(action, payload = {}, { token } = {}) {
+      if (!action) throw new CliError('内部错误：缺少 action');
+      const res = await raw(`${base}/api/data`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ action, ...payload }),
+      });
+      return unwrap(res, action);
+    },
+
+    /** 授权服务器元数据（授权前用它发现 authorization_endpoint / token 有效期策略） */
+    async metadata() {
+      const res = await raw(`${base}/api/oauth/metadata`, { method: 'GET', headers: { Accept: 'application/json' } });
+      if (res.networkError) throw networkError(res.networkError, { raw: res });
+      if (res.status !== 200 || !res.body) {
+        const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'metadata', cmdName: config.cmdName || 'wkgeo' });
+        throw toCliError(cls, { action: 'metadata', raw: { status: res.status, body: res.body } });
+      }
+      return res.body;
+    },
+
+    /**
+     * 用户信息（身份的唯一权威来源）。
+     * ⚠️ 这个端点**不走统一信封**：HTTP 401 + `{error:'invalid_token'}`。
+     */
+    async userinfo(token) {
+      const res = await raw(`${base}/api/oauth/userinfo`, {
+        method: 'GET',
+        headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+      });
+      if (res.networkError) throw networkError(res.networkError, { raw: res });
+      if (res.status === 200 && res.body && res.body.sub) return res.body;
+      const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'userinfo', cmdName: config.cmdName || 'wkgeo' });
+      throw toCliError(cls, { action: 'userinfo', raw: { status: res.status, body: res.body } });
+    },
+
+    /**
+     * 换令牌 / 刷新令牌（OAuth 标准表单）。
+     * ⚠️ 成功响应里**有明文 access_token** —— 返回值只允许写进凭据文件，禁止打印。
+     */
+    async token(form) {
+      const res = await raw(`${base}/api/oauth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: encodeForm(form),
+      });
+      if (res.networkError) throw networkError(res.networkError, { raw: res });
+      if (res.status === 200 && res.body && res.body.access_token) return res.body;
+      const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'token', cmdName: config.cmdName || 'wkgeo' });
+      throw toCliError(cls, { action: 'token', raw: { status: res.status, body: res.body } });
+    },
+
+    /**
+     * 原样发一个 OAuth 表单请求，**不抛异常**（返回 status/body/networkError）。
+     *
+     * 为什么需要它：设备码轮询里 `authorization_pending` / `slow_down` / `expired_token`
+     * 都是**正常预期**的中间态，不是错误 —— 用一个会抛的封装会让轮询逻辑写成一团 try/catch。
+     */
+    async oauthForm(pathname, form) {
+      const res = await raw(`${base}${pathname}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: encodeForm(form),
+      });
+      return res;
+    },
+
+    /** 自省（RFC 7662）：返回 {active,...}，**不是错误**，调用方自己看 active */
+    async introspect(token) {
+      const res = await raw(`${base}/api/oauth/introspect`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body: encodeForm({ token }),
+      });
+      if (res.networkError) throw networkError(res.networkError, { raw: res });
+      if (res.status === 200 && res.body) return res.body;
+      const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'introspect', cmdName: config.cmdName || 'wkgeo' });
+      throw toCliError(cls, { action: 'introspect', raw: { status: res.status, body: res.body } });
+    },
+
+    /**
+     * 吊销（RFC 7009）。
+     * best-effort：未知 token 也回 200；网络失败**不阻塞 logout**（本地删掉才是关键），
+     * 但把失败原因返回给调用方，让 logout 能如实告诉用户"服务端没吊销成功"。
+     */
+    async revoke(token) {
+      try {
+        const res = await raw(`${base}/api/oauth/revoke`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+          body: encodeForm({ token, client_id: config.clientId }),
+        });
+        if (res.networkError) return { ok: false, reason: res.networkError };
+        if (res.status >= 200 && res.status < 300) return { ok: true };
+        return { ok: false, reason: `HTTP ${res.status} ${res.text ? res.text.slice(0, 200) : ''}`.trim() };
+      } catch (e) {
+        return { ok: false, reason: (e && e.message) || String(e) };
+      }
+    },
+  };
+}
+
+/**
+ * 具名动作封装（不用 this，避免解构后 this 丢失 —— 踩过）。
+ * 用法：`const api = createApi({config}); await api.data('listSites', {...}, {token})`
+ */
+export const ACTIONS = {
+  sites: {
+    list: 'listSites',
+    get: 'getSite',
+    create: 'createSite',
+    remove: 'deleteSite',
+    purge: 'purgeSite',
+  },
+  wallet: {
+    get: 'getMyWallet',
+    billing: 'getMyBilling',
+  },
+  orders: {
+    createQuota: 'createQuotaOrder',
+    check: 'checkOrder',
+    list: 'listMyOrders',
+    cancel: 'cancelOrder',
+  },
+  catalog: {
+    products: 'listProducts',
+    entitlements: 'listMyEntitlements',
+  },
+  apps: {
+    list: 'listMyOAuthAuthorizations',
+    revoke: 'revokeMyOAuthAuthorization',
+  },
+};

package/lib/args.mjs

@@ -0,0 +1,196 @@
+/**
+ * 命令行解析（手写，零依赖）。
+ *
+ * 为什么手写而不是 yargs/commander：
+ *   1. 老板要求尽量零第三方依赖（npx 一行跑、审计面小）。
+ *   2. 我们只需要"多词命令 + 少量标志"，手写 100 行就够，而且**能精确控制报错文案**（中文）。
+ *
+ * 支持的写法：
+ *   wkgeo sites create --name "我的站" --customer <id>
+ *   wkgeo orders create --product=storage_mb --units 1
+ *   wkgeo login --no-browser          # --no-xxx → xxx=false
+ *   wkgeo wallet -j                   # 短标志：-h/-v/-y/-j
+ *
+ * ⚠️ 已知取舍：`--name -abc` 这种"值本身以 - 开头"的写法会被当成布尔标志。
+ *    需要时用 `--name=-abc`。这也是大多数 CLI 的行为，不值得为它加复杂度。
+ */
+
+import { UsageError } from './errors.mjs';
+
+/** 全局标志：任何命令都接受（写在 spec 之外，避免每个命令重复声明） */
+export const GLOBAL_FLAGS = {
+  base: { type: 'string', desc: 'API 基址（默认线上网关，可用 WKONGAI_BASE 覆盖）' },
+  'web-base': { type: 'string', desc: '前端基址（授权页兜底地址）' },
+  'client-id': { type: 'string', desc: 'OAuth 客户端 id（默认 wkgeo-cli）' },
+  scope: { type: 'string', desc: '申请的能力范围（空格分隔）' },
+  credentials: { type: 'string', desc: '凭据文件路径（默认 ~/.wkongai/credentials.json）' },
+  'callback-port': { type: 'string', desc: '本地回调端口（默认 53682）' },
+  'callback-host': { type: 'string', desc: '本地回调监听地址（**只允许回环**，默认 127.0.0.1）' },
+  /**
+   * ⚠️ 单位是**秒**（不是毫秒）—— 原来按毫秒解释，`--timeout 600` 变成 600 毫秒、
+   *    0.8 秒就超时，用户按直觉写"600 秒"反而必然失败；`--help` 里当时也没写单位。
+   *    现在：纯数字按秒，也接受显式后缀 `600s` / `500ms`；非法值明确报错。
+   */
+  timeout: { type: 'string', desc: '等待授权回调的超时，**默认单位秒**（--timeout 600 = 600 秒；也支持 600s / 500ms；默认 300 秒）' },
+  'http-timeout': { type: 'string', desc: '单次 HTTP 请求超时毫秒数（默认 30000）' },
+  json: { type: 'boolean', desc: '以 JSON 输出（默认：非 TTY 时自动 JSON）' },
+  text: { type: 'boolean', desc: '强制人类可读输出（管道里默认是 JSON，用它覆盖）' },
+  color: { type: 'boolean', desc: '彩色输出（--no-color 关闭）' },
+  verbose: { type: 'boolean', desc: '额外诊断信息（原始响应会先脱敏）' },
+  help: { type: 'boolean', desc: '显示帮助' },
+  version: { type: 'boolean', desc: '显示版本' },
+};
+
+const SHORT_FLAGS = { h: 'help', v: 'version', j: 'json' };
+
+/** kebab-case → camelCase：`client-id` → `clientId` */
+export function camel(key) {
+  return String(key).replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * 通用解析：只做"切成 positionals + flags"，不校验具体命令。
+ * @returns {{positionals:string[], flags:Record<string, string|boolean>}}
+ */
+export function parseArgv(argv = []) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = String(argv[i]);
+    if (a === '--') {
+      positionals.push(...argv.slice(i + 1).map(String));
+      break;
+    }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      let key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+      let val = eq === -1 ? undefined : a.slice(eq + 1);
+      if (!key) throw new UsageError('参数格式错误：`--` 后面没有标志名');
+      if (val === undefined) {
+        const next = argv[i + 1];
+        // 下一个词不是标志 → 当作本标志的值；否则本标志是布尔
+        if (next !== undefined && !String(next).startsWith('-')) {
+          val = String(next);
+          i++;
+        } else {
+          val = true;
+        }
+      }
+      if (key.startsWith('no-') && key.length > 3) flags[key.slice(3)] = false;
+      else flags[key] = val;
+      continue;
+    }
+    if (/^-[A-Za-z]$/.test(a)) {
+      const long = SHORT_FLAGS[a.slice(1)];
+      if (!long) throw new UsageError(`无法识别的短参数：${a}`);
+      flags[long] = true;
+      continue;
+    }
+    if (a.startsWith('-') && a !== '-') {
+      throw new UsageError(`无法识别的参数：${a}`);
+    }
+    positionals.push(a);
+  }
+  return { positionals, flags };
+}
+
+/**
+ * 按命令 spec 校验/转换标志。
+ * 未知标志直接报错（而不是静默忽略）：拼错 `--nmae` 时静默忽略会让用户以为成功了，
+ * 这是最坑的一类"看起来成功其实没生效"。
+ */
+export function coerceFlags(spec, flags) {
+  const defs = { ...GLOBAL_FLAGS, ...(spec.flags || {}) };
+  /**
+   * ⚠️ 特例：`--no-xxx` 在 `parseArgv` 里被统一当成"把 xxx 关掉"（`--no-color` / `--no-browser`），
+   *    但有的标志**名字本身就以 `no-` 开头**，而且是个**正向开关** —— 例如
+   *    `login --no-wait`（"不要等待，申请完码就退出"）。
+   *
+   *    解析阶段拿不到命令 spec、无法区分这两种情况，所以会把它变成 `wait:false`。
+   *    这里按"注册表"还原：只有当 spec 里**确实定义了** `no-wait`、
+   *    且**没有人**定义 `wait` 时，`wait:false` 才只可能来自用户写的 `--no-wait`。
+   *    （踩过的坑：不加这段的话 `login --no-wait` 会报"不认识的参数：--wait",
+   *      而 `--wait` 在帮助里根本不存在，用户完全看不懂自己写错了什么。）
+   */
+  const restored = { ...flags };
+  for (const key of Object.keys(defs)) {
+    if (!key.startsWith('no-')) continue;
+    const negated = key.slice(3);
+    if (defs[negated] === undefined && restored[key] === undefined && restored[negated] === false) {
+      restored[key] = true;
+      delete restored[negated];
+    }
+  }
+
+  const out = {};
+  const unknown = [];
+  for (const [key, val] of Object.entries(restored)) {
+    const def = defs[key];
+    if (!def) {
+      unknown.push(key);
+      continue;
+    }
+    const name = camel(key);
+    if (def.type === 'boolean') {
+      out[name] = val === false ? false : val === true ? true : !/^(false|0|no)$/i.test(String(val));
+    } else if (def.type === 'number') {
+      const n = Number(val);
+      if (!Number.isFinite(n)) throw new UsageError(`参数 --${key} 需要数字，收到：${val}`);
+      out[name] = n;
+    } else {
+      if (val === true) throw new UsageError(`参数 --${key} 缺少值（写成 --${key}=值 也可以）`);
+      out[name] = String(val);
+    }
+  }
+  if (unknown.length) {
+    const usable = Object.keys(defs).sort().join(' / ');
+    throw new UsageError(`不认识的参数：${unknown.map((u) => '--' + u).join(', ')}\n本命令可用参数：${usable}`);
+  }
+  for (const [key, def] of Object.entries(spec.flags || {})) {
+    if (def.required && out[camel(key)] === undefined) {
+      throw new UsageError(`缺少必填参数 --${key}${def.desc ? `（${def.desc}）` : ''}`);
+    }
+  }
+  return out;
+}
+
+/** 位置参数校验：只支持"按顺序、必填在前"的简单形态 */
+export function checkPositionals(spec, rest) {
+  const wanted = spec.args || [];
+  const max = wanted.length;
+  if (rest.length > max) {
+    throw new UsageError(`参数过多：${rest.slice(max).map((r) => `"${r}"`).join(' ')}\n用法：${spec.usage}`);
+  }
+  for (let i = 0; i < wanted.length; i++) {
+    if (wanted[i].required && (rest[i] === undefined || rest[i] === '')) {
+      throw new UsageError(`缺少参数 <${wanted[i].name}>${wanted[i].desc ? `（${wanted[i].desc}）` : ''}\n用法：${spec.usage}`);
+    }
+  }
+  const out = {};
+  wanted.forEach((w, i) => {
+    if (rest[i] !== undefined) out[w.name] = rest[i];
+  });
+  return out;
+}
+
+/**
+ * 从位置参数里认出命令（支持两词命令）。
+ * @param {Array} commands 命令 spec 数组（必须带 name，如 'sites create'）
+ */
+export function resolveCommand(commands, positionals) {
+  const byName = new Map(commands.map((c) => [c.name, c]));
+  const two = positionals.length >= 2 ? `${positionals[0]} ${positionals[1]}` : null;
+  if (two && byName.has(two)) return { spec: byName.get(two), rest: positionals.slice(2) };
+  if (positionals.length >= 1 && byName.has(positionals[0])) {
+    return { spec: byName.get(positionals[0]), rest: positionals.slice(1) };
+  }
+  // 命令名不完整（比如只打了 `sites`）：给出该分组下的可用命令
+  const group = positionals[0];
+  if (group) {
+    const siblings = commands.filter((c) => c.name.startsWith(`${group} `)).map((c) => c.name);
+    if (siblings.length) {
+      throw new UsageError(`命令不完整："${group}" 需要子命令\n可用：${siblings.join(' / ')}`);
+    }
+  }
+  return null;
+}

package/lib/cli.mjs

@@ -0,0 +1,134 @@
+/**
+ * CLI 入口逻辑（与 `process` 解耦，方便单测直接调 `run(argv, {stdout: 假对象})`）。
+ *
+ * 退出码（写进 README / SKILL.md，AI 端可以据此分支）：
+ *   0 成功 ｜ 1 失败 ｜ 2 用法错误 ｜ 3 需要（重新）授权 ｜ 4 被限流
+ */
+
+import fs from 'node:fs';
+import { parseArgv, resolveCommand } from './args.mjs';
+import { createRuntime, createOutput } from './runtime.mjs';
+import { COMMANDS, renderHelp } from './commands/index.mjs';
+import { CliError, EXIT } from './errors.mjs';
+import { DEFAULT_BASE, DEFAULT_CLIENT_ID } from './config.mjs';
+
+function readVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+export async function run(argv = [], io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const env = io.env || process.env;
+
+  // 先按"最保守"的方式猜输出模式：即使后面解析失败，报错也应该是机器可读的
+  const jsonRequested = argv.includes('--json') || argv.includes('-j');
+  const textForced = argv.includes('--text');
+  let json = jsonRequested || (!textForced && !stdout.isTTY);
+
+  const fallbackOut = (j) =>
+    createOutput({
+      stdout,
+      stderr,
+      json: j,
+      color: false,
+      // 解析都没成功时也要给出"当前会打哪个环境"，否则 AI 端拿到的 meta 是空的
+      meta: () => ({
+        base: env.WKONGAI_BASE || DEFAULT_BASE,
+        client_id: env.WKONGAI_CLIENT_ID || DEFAULT_CLIENT_ID,
+      }),
+    });
+
+  let commandName = null;
+  let runtime = null;
+
+  try {
+    const parsed = parseArgv(argv);
+
+    if (parsed.flags.version === true || parsed.positionals[0] === 'version') {
+      stdout.write(`wkgeo-cli ${readVersion()}\n`);
+      return EXIT.OK;
+    }
+
+    // 帮助：`--help` / `-h` / `help` / `help <命令>` / `<命令> --help`
+    if (parsed.flags.help === true || parsed.positionals[0] === 'help') {
+      let want = null;
+      if (parsed.positionals[0] === 'help') {
+        want = parsed.positionals.slice(1).join(' ') || null;
+      } else {
+        // `wkgeo wallet txns --help` 要能显示 wallet txns 的帮助（不是总帮助）
+        try {
+          const hit = resolveCommand(COMMANDS, parsed.positionals);
+          want = hit ? hit.spec.name : parsed.positionals.join(' ') || null;
+        } catch {
+          want = parsed.positionals.join(' ') || null;
+        }
+      }
+      stdout.write(renderHelp(want) + '\n');
+      return EXIT.OK;
+    }
+
+    commandName = parsed.positionals.join(' ') || null;
+    runtime = createRuntime({
+      argv,
+      commands: COMMANDS,
+      env,
+      stdout,
+      stderr,
+      fetchImpl: io.fetchImpl,
+      now: io.now,
+      openBrowser: io.openBrowser,
+      /** `child_process.spawn` 的注入点（只为单测：验证"AI 场景一次都不 spawn 浏览器"） */
+      spawnImpl: io.spawnImpl,
+      sleep: io.sleep,
+      /**
+       * 「设备码先成功后，本地回调监听再多留多久」的注入点（毫秒；见 lib/login.mjs 的
+       * DEFAULT_POST_DEVICE_GRACE_MS）。生产不传 = 默认 3 秒；单测注入小值即可确定性地
+       * 验证"迟到的回调拿到已完成页"（不必真的等 3 秒）。
+       */
+      postDeviceGraceMs: io.postDeviceGraceMs,
+      /**
+       * 代理检测的注入点（见 lib/proxy.mjs）。生产上不传，走 `process.platform` + 真 `reg/scutil`；
+       * 单测传入才能在任意平台上验证 Windows/macOS 的解析分支，且不去起真子进程。
+       */
+      platform: io.platform,
+      exec: io.exec,
+      /** 同上：`skill` 手册位置的注入点（单测验证"包里没有手册"分支时用，见 lib/commands/skill.mjs） */
+      skillUrl: io.skillUrl,
+    });
+    json = runtime.out.json;
+    commandName = runtime.spec.name;
+
+    await runtime.spec.run(runtime);
+    return EXIT.OK;
+  } catch (err) {
+    const out = runtime ? runtime.out : fallbackOut(json);
+    const e =
+      err instanceof CliError
+        ? err
+        : new CliError((err && err.message) || String(err), {
+            kind: 'internal',
+            hint: '这是 CLI 内部错误；请带上完整命令与输出反馈',
+            cause: err,
+          });
+
+    out.emitErr(commandName, e);
+
+    if (e.showHelp && !json) {
+      stderr.write('\n' + renderHelp() + '\n');
+    }
+    if (e.kind === 'usage' && !e.hint) {
+      // 用法错误给一条"下一步"，人/AI 都不用去猜
+      stderr.write('提示：运行 `wkgeo --help` 看所有命令，或 `wkgeo <命令> --help` 看单个命令。\n');
+    }
+    if (runtime && runtime.flags.verbose && err && err.stack) {
+      stderr.write(err.stack + '\n');
+    }
+    return e.exitCode === undefined ? EXIT.ERROR : e.exitCode;
+  }
+}

package/lib/commands/apps.mjs

@@ -0,0 +1,116 @@
+/**
+ * 应用授权命令：`apps list` / `apps revoke`
+ *
+ * 这两个动作**用户自助**（能力 `billing:self`，所有登录用户都有），
+ * 所以用 OAuth 令牌本身就能调 —— 不需要管理员。
+ *
+ * ⚠️ 线上状态：`listMyOAuthAuthorizations` / `revokeMyOAuthAuthorization` 是**新加的 action**，
+ *    线上是否已部署要看 data 云函数有没有发版。未部署时服务端会返回
+ *    「未知操作: xxx」或「动作 xxx 未在权限表中登记」——这不是用户的错，
+ *    必须把这句话翻译成"服务端还没部署这个功能"，否则会让人以为是自己用错了命令。
+ */
+
+import { CliError } from '../errors.mjs';
+import { formatTime } from '../format.mjs';
+
+/** 判断"这个 action 线上还没部署"（新旧两种 dispatcher 的兜底文案都认） */
+function isActionNotDeployed(err) {
+  const msg = String((err && err.message) || '');
+  return /未知操作|未在权限表中登记|未知的 action|Unknown action/i.test(msg) || (err && err.kind === 'unknown' && /action/i.test(msg));
+}
+
+export const appsListCommand = {
+  name: 'apps list',
+  summary: '我授权过的应用（应用名 / 首次授权时间 / 过期时间 / 最后使用时间 / 能力）',
+  usage: 'wkgeo apps list',
+  async run(ctx) {
+    const { out } = ctx;
+    let res;
+    try {
+      res = await ctx.callData('listMyOAuthAuthorizations', {});
+    } catch (e) {
+      if (isActionNotDeployed(e)) {
+        throw new CliError('服务端尚未部署「我已授权的应用」接口（listMyOAuthAuthorizations）', {
+          kind: 'not_deployed',
+          code: e.code,
+          hint: '这是服务端缺口（data 云函数未发版），不是命令用错了；本地仍可用 `wkgeo logout` 清理登录态',
+          raw: e.raw,
+        });
+      }
+      throw e;
+    }
+    const rows = (res && Array.isArray(res.rows) ? res.rows : []).map((r) => ({
+      client_id: r.client_id,
+      client_name: r.client_name || r.client_id,
+      is_public: r.is_public === undefined ? null : !!r.is_public,
+      scopes: Array.isArray(r.scopes) ? r.scopes : [],
+      first_authorized_at: r.first_authorized_at || null,
+      expires_at: r.expires_at || null,
+      last_used_at: r.last_used_at || null,
+      token_count: Number(r.token_count) || 0,
+      is_current_cli: r.client_id === ctx.config.clientId,
+    }));
+    const data = { rows, total: rows.length, current_cli_client_id: ctx.config.clientId };
+
+    if (!out.json) {
+      out.head(`我已授权的应用（${rows.length} 个）`);
+      out.table(
+        [
+          { title: '应用', key: 'client_name', width: 22 },
+          { title: 'client_id', key: 'client_id', width: 26 },
+          { title: '令牌数', key: 'token_count', width: 8 },
+          { title: '首次授权', key: 'first_authorized_at', format: (v) => formatTime(v), width: 20 },
+          { title: '过期时间', key: 'expires_at', format: (v) => formatTime(v), width: 20 },
+          { title: '最后使用', key: 'last_used_at', format: (v) => formatTime(v), width: 20 },
+        ],
+        rows,
+      );
+      out.info(`  当前 CLI 使用的 client_id：${ctx.config.clientId}`);
+      out.info('  吊销某个应用：wkgeo apps revoke <client_id>');
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+export const appsRevokeCommand = {
+  name: 'apps revoke',
+  summary: '吊销某个应用对我的授权（该应用所有令牌立即失效；之后需要重新授权）',
+  usage: 'wkgeo apps revoke <client_id>',
+  args: [{ name: 'clientId', required: true, desc: '应用的 client_id（见 apps list）' }],
+  async run(ctx) {
+    const { out, config } = ctx;
+    const clientId = ctx.positional.clientId;
+    let res;
+    try {
+      res = await ctx.callData('revokeMyOAuthAuthorization', { client_id: clientId });
+    } catch (e) {
+      if (isActionNotDeployed(e)) {
+        throw new CliError('服务端尚未部署「一键吊销授权」接口（revokeMyOAuthAuthorization）', {
+          kind: 'not_deployed',
+          code: e.code,
+          hint: '这是服务端缺口（data 云函数未发版）；临时止血可调用 POST /api/oauth/revoke 吊销单把令牌',
+          raw: e.raw,
+        });
+      }
+      throw e;
+    }
+    const revoked = Number(res && res.revoked) || 0;
+    const isSelf = clientId === config.clientId;
+    const data = {
+      client_id: clientId,
+      revoked,
+      is_current_cli_client: isSelf,
+      local_credentials_still_present: isSelf ? !!ctx.readCredentials() : null,
+    };
+
+    if (!out.json) {
+      out.ok(`已吊销应用「${clientId}」的授权，作废令牌 ${revoked} 把`);
+      if (isSelf) {
+        out.warn('你吊销的是**当前 CLI 自己**的授权：本地令牌已失效，请重新运行 `wkgeo login`（或 `wkgeo logout` 清掉本地凭据）');
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};