@cnbcool/cnb-api-generate 2.3.4 → 2.4.0

package/client/core.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import os from 'os';
 import { fetchResponseHandler } from "./fetch-response-handler";
 import { generateUniqueId } from './utils/generate-unique-id';
-
+import { resolveToken } from './utils/resolve-token';
 
 /**
  * 格式化 API 响应
@@ -117,6 +117,7 @@ async function formatResponse(data: any, response: any) {
 }
 
 async function clientFetch(data: any): Promise<any> {
+  const token = await resolveToken();
   const domain = process.env.CNB_API_ENDPOINT || 'https://api.cnb.cool'
   const url = `${domain}${data.url}`
   const urlParse = new URL(url);
@@ -131,7 +132,7 @@ async function clientFetch(data: any): Promise<any> {
     method: data.method.toUpperCase(),
     body: data.data ? JSON.stringify(data.data) : undefined,
     headers: {
-      Authorization: `Bearer ${process.env.CNB_TOKEN}`,
+      Authorization: `Bearer ${token}`,
       Accept: 'application/vnd.cnb.api+json',
       ...(data?.header || {}),
     },

package/client/index.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { getExtraHelpText } from './lib/extra-help';
 import { registerModuleCommands } from './lib/register-modules';
 import { registerFallbackAction } from './lib/register-fallback';
+import { registerLoginCommand } from './lib/login';
 
 // ============================================================
 // Commander 程序定义
@@ -24,6 +25,7 @@ program
 // 注册命令
 // ============================================================
 
+registerLoginCommand(program);
 registerModuleCommands(program);
 registerFallbackAction(program);
 

package/client/lib/build-diagnostics.ts

@@ -0,0 +1,240 @@
+/**
+ * 构建诊断模块
+ *
+ * 查询流水线失败 Stage 的详细日志和错误信息，同时输出耗时数据辅助分析。
+ * 内置降级逻辑：Stage 详情失败时自动尝试全量日志下载（含 base64 解码）。
+ *
+ * sn 获取策略（按优先级）：
+ *   1. 用户通过 --sn 显式传入
+ *   2. 环境变量 CNB_BUILD_ID（当前构建自身的 sn）
+ *   3. 从 PR commit statuses 中提取失败构建的 sn
+ */
+
+import { resolveToken } from '../utils/resolve-token';
+
+async function apiRequest(url: string, headers: Record<string, string>): Promise<any> {
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    throw new Error(`请求失败: ${res.status} ${res.statusText} — ${url}`);
+  }
+  return res.json();
+}
+
+async function apiRequestText(url: string, headers: Record<string, string>): Promise<string> {
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    throw new Error(`请求失败: ${res.status} ${res.statusText} — ${url}`);
+  }
+  return res.text();
+}
+
+/**
+ * 从 PR 的 commit statuses 中提取失败构建的 sn
+ */
+function extractSnFromStatuses(statusData: any): string | null {
+  const statuses = statusData?.statuses || statusData;
+  if (!Array.isArray(statuses) || statuses.length === 0) return null;
+
+  // 优先找 error/failure 状态的构建
+  const failed = statuses.find(
+    (s: any) => s.state === 'error' || s.state === 'failure',
+  );
+  if (!failed) return null;
+
+  // 从 target_url 中解析 sn
+  // 格式通常为: https://cnb.cool/{repo}/-/build/{sn} 或含 /pipelines 路径
+  const url = failed.target_url || '';
+  const match = url.match(/\/-\/build\/([^/?#]+)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * 降级方案：下载全量日志
+ * API 返回可能是 JSON（含 base64 编码的 data.data 字段）或纯文本
+ */
+async function downloadFullLog(baseUrl: string, pipelineId: string, headers: Record<string, string>): Promise<string> {
+  const body = await apiRequestText(`${baseUrl}/-/build/logs/${pipelineId}`, headers);
+
+  try {
+    const json = JSON.parse(body);
+    if (json.data && typeof json.data === 'string') {
+      return Buffer.from(json.data, 'base64').toString('utf-8');
+    }
+    if (json.data?.data && typeof json.data.data === 'string') {
+      return Buffer.from(json.data.data, 'base64').toString('utf-8');
+    }
+    return JSON.stringify(json, null, 2);
+  } catch {
+    return body;
+  }
+}
+
+/**
+ * 获取失败构建的诊断信息
+ */
+export async function diagnoseBuild(options: {
+  repo: string;
+  sn?: string;
+  prNumber?: string;
+}): Promise<string> {
+  const domain = process.env.CNB_API_ENDPOINT || 'https://api.cnb.cool';
+  const { repo } = options;
+  let sn = options.sn;
+
+  // 一次性 resolve token，后续所有请求复用
+  const token = await resolveToken();
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.cnb.api+json',
+    Authorization: `Bearer ${token}`,
+  };
+
+  // 策略 1: 显式传入的 sn（最高优先级，已在外层赋值）
+  // 策略 2: 环境变量 CNB_BUILD_ID
+  if (!sn && process.env.CNB_BUILD_ID) {
+    sn = process.env.CNB_BUILD_ID;
+  }
+
+  // 策略 3: 从 PR commit statuses 中获取失败构建的 sn
+  if (!sn && options.prNumber) {
+    try {
+      const statusesUrl = `${domain}/${repo}/-/pulls/${options.prNumber}/statuses`;
+      const statusData = await apiRequest(statusesUrl, headers);
+      sn = extractSnFromStatuses(statusData);
+      if (!sn) {
+        return '未从 PR CI 状态中找到失败的构建，所有构建均为成功状态。';
+      }
+    } catch (e: any) {
+      return `获取 PR CI 状态失败: ${e.message}`;
+    }
+  }
+
+  if (!sn) {
+    return '缺少构建号(sn)：未传入 --sn、未设置 CNB_BUILD_ID、且未检测到 PR 上下文。';
+  }
+
+  const baseUrl = `${domain}/${repo}`;
+  const lines: string[] = [];
+  lines.push(`查询构建 sn=${sn} 的流水线状态...\n`);
+
+  // 获取构建状态
+  let buildStatus: any;
+  try {
+    buildStatus = await apiRequest(`${baseUrl}/-/build/status/${sn}`, headers);
+  } catch (e: any) {
+    return `获取构建状态失败: ${e.message}`;
+  }
+
+  if (
+    !buildStatus.pipelinesStatus ||
+    typeof buildStatus.pipelinesStatus !== 'object'
+  ) {
+    lines.push('未找到流水线状态信息');
+    lines.push('返回数据:');
+    lines.push(JSON.stringify(buildStatus, null, 2));
+    return lines.join('\n');
+  }
+
+  const pipelines = Object.entries(buildStatus.pipelinesStatus) as [string, any][];
+  if (pipelines.length === 0) {
+    return '该构建没有流水线';
+  }
+
+  let hasFailure = false;
+
+  for (const [pipelineName, pipeline] of pipelines) {
+    const { id: pipelineId, status, stages } = pipeline;
+    if (!Array.isArray(stages)) continue;
+
+    const failedStages = stages.filter((s: any) => s.status === 'error');
+    if (failedStages.length === 0) continue;
+
+    hasFailure = true;
+    lines.push(`━━━ 流水线: ${pipelineName} (status: ${status}) ━━━\n`);
+
+    for (const stage of failedStages) {
+      lines.push(
+        `▸ 失败 Stage: ${stage.name || stage.id} (status: ${stage.status})`,
+      );
+
+      try {
+        const detail = await apiRequest(
+          `${baseUrl}/-/build/logs/stage/${sn}/${pipelineId}/${stage.id}`,
+          headers,
+        );
+
+        if (detail.error) {
+          lines.push(`  错误信息: ${detail.error}`);
+        }
+        if (detail.duration != null) {
+          lines.push(`  耗时: ${detail.duration}ms`);
+        }
+
+        if (Array.isArray(detail.content) && detail.content.length > 0) {
+          lines.push('  ─── 日志 ───');
+          for (const line of detail.content) {
+            lines.push(`  ${line}`);
+          }
+          lines.push('  ─── 日志结束 ───');
+        } else {
+          throw new Error('Stage 详情无日志内容，降级到全量日志');
+        }
+      } catch (e: any) {
+        // 降级：尝试下载全量日志
+        lines.push(
+          `  Stage 详情获取失败（${e.message}），尝试全量日志下载...`,
+        );
+        try {
+          const fullLog = await downloadFullLog(baseUrl, pipelineId, headers);
+          if (fullLog?.trim()) {
+            lines.push('  ─── 全量日志（末尾 100 行）───');
+            const logLines = fullLog.split('\n');
+            const tail = logLines.slice(Math.max(0, logLines.length - 100));
+            for (const l of tail) {
+              lines.push(`  ${l}`);
+            }
+            if (logLines.length > 100) {
+              lines.push(
+                `  ... (省略了前 ${logLines.length - 100} 行，共 ${logLines.length} 行)`,
+              );
+            }
+            lines.push('  ─── 全量日志结束 ───');
+          } else {
+            lines.push('  全量日志也为空');
+          }
+        } catch (e2: any) {
+          lines.push(`  全量日志下载也失败: ${e2.message}`);
+        }
+      }
+
+      lines.push('');
+    }
+  }
+
+  if (!hasFailure) {
+    lines.push('所有流水线均无失败的 Stage');
+    lines.push(`整体构建状态: ${buildStatus.status}`);
+  }
+
+  // 附加：输出所有 Stage 的耗时概览（辅助性能分析）
+  lines.push('\n━━━ 耗时概览（所有 Stage）━━━\n');
+  for (const [pipelineName, pipeline] of pipelines) {
+    const { stages } = pipeline;
+    if (!Array.isArray(stages)) continue;
+    for (const stage of stages) {
+      const name = stage.name || stage.id;
+      const duration =
+        stage.duration != null ? `${stage.duration}ms` : 'N/A';
+      const statusIcon =
+        stage.status === 'success'
+          ? '✅'
+          : stage.status === 'error'
+            ? '❌'
+            : '⏳';
+      lines.push(
+        `  ${statusIcon} ${pipelineName} → ${name}: ${duration} (${stage.status})`,
+      );
+    }
+  }
+
+  return lines.join('\n');
+}

package/client/lib/execute-action.ts

@@ -3,6 +3,7 @@ import path from 'path';
 import { Command } from 'commander';
 import { showShort, resolveShortcut, type ResolvedShortcut } from '../shortcuts';
 import { handleUpload } from '../utils/upload';
+import { diagnoseBuild } from './build-diagnostics';
 import { formatParams } from './format-params';
 import { formatOutput } from './format-output';
 // @ts-ignore
@@ -95,6 +96,17 @@ export async function executeAction(
     return;
   }
 
+  // 自定义命令走独立分支（不通过 swagger 生成的 tool 函数）
+  if (shortcut?.tool === '__get-ci-logs__') {
+    const result = await diagnoseBuild({
+      repo: process.env.CNB_REPO_SLUG || '',
+      sn: (opts.sn as string) || undefined,
+      prNumber: process.env.CNB_PULL_REQUEST_IID || undefined,
+    });
+    console.log(result);
+    return;
+  }
+
   const formattedParams = formatParams(params);
 
   const toolFunction = loadToolFunction(formattedParams.module, formattedParams.tool);

package/client/lib/login.ts

@@ -0,0 +1,98 @@
+import { Command } from 'commander';
+import {
+  requestDeviceCode,
+  pollToken,
+  maskToken,
+  saveToken,
+  getTokenPath,
+  type LoginConfig,
+  type TokenStore,
+} from '../utils/device-auth';
+import { tryOpenBrowser } from '../utils/open-browser';
+
+export function registerLoginCommand(program: Command): void {
+  program
+    .command('login')
+    .description('通过 OAuth2 设备授权流登录 CNB，获取并保存 access_token')
+    .option('--client-id <string>', 'OAuth2 client_id', process.env.OAUTH2_CLIENT_ID || 'cnb_cli')
+    .option('--woa', '使用内网环境 (https://cnb.woa.com)', false)
+    .option('--debug', '打印调试信息', false)
+    .helpOption('-h, --help', '显示帮助文档')
+    .action(async (opts) => {
+      const cfg: LoginConfig = {
+        clientID: opts.clientId,
+        platformURL: opts.woa ? 'https://cnb.woa.com' : 'https://cnb.cool',
+        debug: opts.debug,
+      };
+
+      const ac = new AbortController();
+      process.on('SIGINT', () => ac.abort());
+      process.on('SIGTERM', () => ac.abort());
+
+      if (cfg.debug) {
+        console.log('========== OAuth2 Device Authorization Grant 登录 ==========');
+        console.log(`Platform URL : ${cfg.platformURL}`);
+        console.log(`Client ID    : ${cfg.clientID}`);
+        console.log('-----------------------------------------------------------');
+      }
+
+      try {
+        // 步骤 1：获取 device_code + user_code
+        const devResp = await requestDeviceCode(cfg, ac.signal);
+        const authURL = devResp.verification_uri_complete;
+        console.log(`\n请打开以下链接完成授权：\n  ${authURL}\n`);
+
+        // 尝试自动打开浏览器
+        tryOpenBrowser(authURL);
+        console.log('(已尝试自动打开浏览器，若未打开请手动复制上方链接)');
+
+        if (cfg.debug) {
+          console.log('[Debug] 设备注册详情：');
+          console.log(`  verification_uri          : ${devResp.verification_uri}`);
+          console.log(`  verification_uri_complete : ${devResp.verification_uri_complete}`);
+          console.log(`  user_code                 : ${devResp.user_code}`);
+          console.log(`  device_code               : ${maskToken(devResp.device_code)}`);
+          console.log(`  expires_in                : ${devResp.expires_in}s`);
+          console.log(`  interval                  : ${devResp.interval}s`);
+        }
+
+        console.log('正在等待授权...');
+
+        // 步骤 2：轮询 /oauth2/token
+        const tok = await pollToken(cfg, devResp, ac.signal);
+
+        console.log('\n登录成功 🎉');
+
+        if (cfg.debug) {
+          console.log(`  token_type    : ${tok.token_type}`);
+          console.log(`  expires_in    : ${tok.expires_in}`);
+          console.log(`  scope         : ${tok.scope || ''}`);
+          console.log(`  access_token  : ${maskToken(tok.access_token)}`);
+          if (tok.refresh_token) {
+            console.log(`  refresh_token : ${maskToken(tok.refresh_token)}`);
+          }
+          if (tok.id_token) {
+            console.log(`  id_token      : ${maskToken(tok.id_token)}`);
+          }
+        }
+        // 持久化 token
+        const nowSec = Math.floor(Date.now() / 1000);
+        const store: TokenStore = {
+          access_token: tok.access_token,
+          expires_at: nowSec + tok.expires_in,
+          platform_url: cfg.platformURL,
+          client_id: cfg.clientID,
+        };
+        if (tok.refresh_token) {
+          store.refresh_token = tok.refresh_token;
+        }
+        saveToken(store);
+        if (cfg.debug) {
+          console.log(`Token 已保存到 ${getTokenPath()}`);
+        }
+      } catch (err: any) {
+        console.error(`\n登录失败: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}

package/client/lib/register-modules.ts

@@ -132,7 +132,12 @@ export function registerModuleCommands(program: Command): void {
         });
 
       // 上传命令只需要 --file，不复用真实 tool 的 body 选项（name/size/content_type 由上传流程自动获取）
-      if (!shortcut.upload) {
+      if (shortcut.custom) {
+        // 自定义命令注册自己的选项
+        if (shortcut.realTool === '__get-ci-logs__') {
+          shortcutCmd.option('--sn <string>', '构建号（可选，默认自动从环境变量或 PR 状态获取）');
+        }
+      } else if (!shortcut.upload) {
         registerToolOptions(shortcutCmd, moduleName, shortcut.realTool, true);
       } else {
         shortcutCmd.requiredOption('--file <string>', '本地文件路径。必填。');

package/client/shortcuts.ts

@@ -20,6 +20,8 @@ export interface ShortcutDefinition {
   repoOnly?: boolean;
   /** 为 true 时表示是上传命令，走完整上传流程 */
   upload?: boolean;
+  /** 为 true 时表示是自定义命令，走独立处理分支（不通过 swagger 生成的 tool 函数） */
+  custom?: boolean;
   /** 显示用的中文说明 */
   description: string;
   /** 自动注入的 data 参数（如 close/open 的状态值） */
@@ -94,6 +96,7 @@ export const PR_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'list-assignees', realTool: 'list-pull-assignees',     description: '查看处理人' },
   { shortName: 'upload-file',    realTool: 'upload-files',  description: '上传文件', repoOnly: true, upload: true, dataTip: "--file 文件路径" },
   { shortName: 'upload-image',   realTool: 'upload-imgs',  description: '上传图片', repoOnly: true, upload: true, dataTip: "--file 图片路径" },
+  { shortName: 'get-ci-logs', realTool: '__get-ci-logs__', description: '获取 CI 失败日志', repoOnly: true, custom: true, dataTip: "--sn 构建号（可选）" },
 ];
 
 // ============================================================

package/client/utils/device-auth.ts

@@ -0,0 +1,8 @@
+export type { DeviceAuthResponse, TokenResponse, TokenErrorResponse, LoginConfig, TokenStore } from './types';
+export { getTokenPath } from './token-path';
+export { maskToken } from './mask-token';
+export { saveToken } from './save-token';
+export { loadToken } from './load-token';
+export { requestDeviceCode } from './request-device-code';
+export { pollToken } from './poll-token';
+export { refreshAccessToken } from './refresh-token';

package/client/utils/do-token-request.ts

@@ -0,0 +1,52 @@
+import type { LoginConfig, TokenResponse, TokenErrorResponse } from './types';
+
+const GRANT_TYPE_DEVICE_CODE = 'urn:ietf:params:oauth:grant-type:device_code';
+
+/**
+ * 发起一次 token 轮询请求。
+ */
+export async function doTokenRequest(
+  cfg: LoginConfig,
+  tokenURL: string,
+  deviceCode: string,
+  signal?: AbortSignal,
+): Promise<{ token?: TokenResponse; tokenError?: TokenErrorResponse }> {
+  const form = new URLSearchParams();
+  form.set('grant_type', GRANT_TYPE_DEVICE_CODE);
+  form.set('device_code', deviceCode);
+  form.set('client_id', cfg.clientID);
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+  };
+
+  if (cfg.debug) {
+    console.log(`[DEBUG] POST ${tokenURL} body=${form.toString()}`);
+  }
+
+  const resp = await fetch(tokenURL, {
+    method: 'POST',
+    headers,
+    body: form.toString(),
+    signal,
+  });
+
+  const body = await resp.text();
+  if (cfg.debug) {
+    console.log(`[DEBUG] status=${resp.status} body=${body}`);
+  }
+
+  if (resp.status === 200) {
+    const token: TokenResponse = JSON.parse(body);
+    return { token };
+  }
+
+  try {
+    const errResp: TokenErrorResponse = JSON.parse(body);
+    if (errResp.error) {
+      return { tokenError: errResp };
+    }
+  } catch {}
+
+  throw new Error(`unexpected status=${resp.status} body=${body}`);
+}

package/client/utils/get-token.ts

@@ -0,0 +1,13 @@
+import { loadToken } from './load-token';
+
+/**
+ * 同步获取 token（兼容旧调用，不做过期检查）。
+ * @deprecated 请使用 resolveToken()
+ */
+export function getToken(): string {
+  if (process.env.CNB_TOKEN) {
+    return process.env.CNB_TOKEN;
+  }
+  const store = loadToken();
+  return store?.access_token || '';
+}

package/client/utils/load-token.ts

@@ -0,0 +1,14 @@
+import fs from 'fs';
+import { getTokenPath } from './token-path';
+import type { TokenStore } from './types';
+
+/** 读取已保存的 token */
+export function loadToken(): TokenStore | null {
+  const tokenPath = getTokenPath();
+  if (!fs.existsSync(tokenPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(tokenPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/client/utils/mask-token.ts

@@ -0,0 +1,5 @@
+/** 脱敏展示长 token */
+export function maskToken(tok: string): string {
+  if (tok.length <= 12) return tok;
+  return `${tok.slice(0, 8)}...${tok.slice(-4)}`;
+}

package/client/utils/open-browser.ts

@@ -0,0 +1,22 @@
+import { exec } from 'node:child_process';
+
+/**
+ * 尝试使用系统默认浏览器打开指定 URL。
+ * macOS 使用 open，Linux 使用 xdg-open，Windows 使用 start。
+ * 打开失败时静默忽略，不影响主流程。
+ */
+export function tryOpenBrowser(url: string): void {
+  const cmds: Record<string, string> = {
+    darwin: `open "${url}"`,
+    linux: `xdg-open "${url}"`,
+    win32: `start "" "${url}"`,
+  };
+  const cmd = cmds[process.platform];
+  if (!cmd) return;
+
+  exec(cmd, (err) => {
+    if (err) {
+      // 打开失败时静默忽略，用户仍可手动复制链接
+    }
+  });
+}

package/client/utils/poll-token.ts

@@ -0,0 +1,78 @@
+import type { LoginConfig, DeviceAuthResponse, TokenResponse } from './types';
+import { doTokenRequest } from './do-token-request';
+
+const ERR_AUTHORIZATION_PENDING = 'authorization_pending';
+const ERR_SLOW_DOWN = 'slow_down';
+const ERR_ACCESS_DENIED = 'access_denied';
+const ERR_EXPIRED_TOKEN = 'expired_token';
+
+/**
+ * 根据 RFC 8628 Section 3.4/3.5 轮询 /oauth2/token 端点。
+ */
+export async function pollToken(
+  cfg: LoginConfig,
+  dev: DeviceAuthResponse,
+  signal?: AbortSignal,
+): Promise<TokenResponse> {
+  const POLL_TIMEOUT = 3 * 60 * 1000; // 3 分钟
+  let interval = 1000; // 1 秒轮询一次
+  const now = Date.now();
+  let deadline = now + POLL_TIMEOUT;
+  const devExpire = now + dev.expires_in * 1000;
+  if (devExpire < deadline) {
+    deadline = devExpire;
+  }
+
+  const tokenURL = `${cfg.platformURL.replace(/\/+$/, '')}/oauth2/token`;
+
+  for (let attempt = 1; ; attempt++) {
+    if (Date.now() > deadline) {
+      throw new Error('device code 已过期 / 轮询超时');
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(resolve, interval);
+      if (signal) {
+        signal.addEventListener('abort', () => {
+          clearTimeout(timer);
+          reject(new Error('用户取消'));
+        }, { once: true });
+      }
+    });
+
+    if (signal?.aborted) {
+      throw new Error('用户取消');
+    }
+
+    const result = await doTokenRequest(cfg, tokenURL, dev.device_code, signal);
+
+    if (result.token) {
+      return result.token;
+    }
+
+    if (result.tokenError) {
+      const errCode = result.tokenError;
+      const timeStr = new Date().toLocaleTimeString('zh-CN', { hour12: false });
+
+      switch (errCode.error) {
+        case ERR_AUTHORIZATION_PENDING:
+          if (cfg.debug) {
+            console.log(`  ⏳ [${timeStr}] 第 ${attempt} 次轮询: ${errCode.error}（继续等待用户授权）`);
+          }
+          break;
+        case ERR_SLOW_DOWN:
+          interval += 5000;
+          if (cfg.debug) {
+            console.log(`  🐢 [${timeStr}] 第 ${attempt} 次轮询: ${errCode.error}（轮询间隔增加到 ${interval / 1000}s）`);
+          }
+          break;
+        case ERR_ACCESS_DENIED:
+          throw new Error(`用户拒绝了授权: ${errCode.error_description || ''}`);
+        case ERR_EXPIRED_TOKEN:
+          throw new Error(`device_code 已过期: ${errCode.error_description || ''}`);
+        default:
+          throw new Error(`token 请求失败: ${errCode.error} - ${errCode.error_description || ''}`);
+      }
+    }
+  }
+}

package/client/utils/refresh-token.ts

@@ -0,0 +1,46 @@
+import { saveToken } from './save-token';
+import type { TokenStore, TokenResponse } from './types';
+
+/**
+ * 使用 refresh_token 刷新 access_token。
+ * 成功后自动更新 ~/.cnb/token 文件并返回新的 access_token。
+ */
+export async function refreshAccessToken(store: TokenStore): Promise<string> {
+  if (!store.refresh_token) {
+    throw new Error('no refresh_token');
+  }
+
+  const platformURL = store.platform_url || 'https://cnb-dev.woa.com';
+  const clientID = store.client_id || process.env.OAUTH2_CLIENT_ID || 'cnb_cli';
+  const tokenURL = `${platformURL.replace(/\/+$/, '')}/oauth2/token`;
+
+  const form = new URLSearchParams();
+  form.set('grant_type', 'refresh_token');
+  form.set('refresh_token', store.refresh_token);
+  form.set('client_id', clientID);
+
+  const resp = await fetch(tokenURL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: form.toString(),
+  });
+
+  if (resp.status !== 200) {
+    const body = await resp.text();
+    throw new Error(`refresh token failed: status=${resp.status} body=${body}`);
+  }
+
+  const tok: TokenResponse = await resp.json();
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  const newStore: TokenStore = {
+    access_token: tok.access_token,
+    expires_at: nowSec + tok.expires_in,
+    refresh_token: tok.refresh_token || store.refresh_token,
+    platform_url: store.platform_url,
+    client_id: store.client_id,
+  };
+  saveToken(newStore);
+
+  return tok.access_token;
+}

package/client/utils/request-device-code.ts

@@ -0,0 +1,41 @@
+import type { LoginConfig, DeviceAuthResponse } from './types';
+
+/**
+ * 调用 /oauth2/device/auth 端点获取 device_code / user_code 等。
+ */
+export async function requestDeviceCode(cfg: LoginConfig, signal?: AbortSignal): Promise<DeviceAuthResponse> {
+  const form = new URLSearchParams();
+  form.set('client_id', cfg.clientID);
+
+  const endpoint = `${cfg.platformURL.replace(/\/+$/, '')}/oauth2/device/auth`;
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+  };
+
+  if (cfg.debug) {
+    console.log(`[DEBUG] POST ${endpoint} body=${form.toString()}`);
+  }
+
+  const resp = await fetch(endpoint, {
+    method: 'POST',
+    headers,
+    body: form.toString(),
+    signal,
+  });
+
+  const body = await resp.text();
+  if (cfg.debug) {
+    console.log(`[DEBUG] status=${resp.status} body=${body}`);
+  }
+
+  if (resp.status !== 200) {
+    throw new Error(`status=${resp.status} body=${body}`);
+  }
+
+  const out: DeviceAuthResponse = JSON.parse(body);
+  if (out.interval <= 0) {
+    out.interval = 5; // RFC 8628 默认 5 秒
+  }
+  return out;
+}

package/client/utils/resolve-token.ts

@@ -0,0 +1,50 @@
+import { loadToken } from './load-token';
+import { refreshAccessToken } from './refresh-token';
+
+/**
+ * 获取有效的 access_token。
+ *
+ * 优先使用环境变量 CNB_TOKEN（不检查过期）。
+ * 否则从 ~/.cnb/token 读取，若已过期则尝试用 refresh_token 刷新；
+ * 刷新失败或无 refresh_token 时终止进程并提示用户重新登录。
+ */
+export async function resolveToken(): Promise<string> {
+  // 环境变量优先 CodeBuddy
+  if (process.env.CNB_TOKEN_FOR_CODEBUDDY) {
+    if (!process.env.CNB_NPC_SLUG && process.env.CNB_NPC_NAME === 'CodeBuddy') {
+      return process.env.CNB_TOKEN_FOR_CODEBUDDY;
+    }
+  }
+
+  // 环境变量优先，不做过期判断
+  if (process.env.CNB_TOKEN) {
+    return process.env.CNB_TOKEN;
+  }
+
+  const store = loadToken();
+  if (!store || !store.access_token) {
+    console.error('未找到有效的登录凭证，请先执行 `cnb login` 进行授权。');
+    process.exit(1);
+  }
+
+  const nowSec = Math.floor(Date.now() / 1000);
+
+  // 未过期，直接返回
+  if (nowSec < store.expires_at) {
+    return store.access_token;
+  }
+
+  // 已过期，尝试 refresh
+  if (store.refresh_token) {
+    try {
+      return await refreshAccessToken(store);
+    } catch (err: any) {
+      console.error(`Token 已过期，刷新失败: ${err.message}`);
+      console.error('请重新执行 `cnb login` 进行授权。');
+      process.exit(1);
+    }
+  }
+
+  console.error('Token 已过期且无 refresh_token，请重新执行 `cnb login` 进行授权。');
+  process.exit(1);
+}

package/client/utils/save-token.ts

@@ -0,0 +1,14 @@
+import fs from 'fs';
+import path from 'path';
+import { getTokenPath } from './token-path';
+import type { TokenStore } from './types';
+
+/** 持久化 token 到 ~/.cnb/token */
+export function saveToken(store: TokenStore): void {
+  const tokenPath = getTokenPath();
+  const dir = path.dirname(tokenPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(tokenPath, JSON.stringify(store, null, 2), { mode: 0o600 });
+}

package/client/utils/token-path.ts

@@ -0,0 +1,7 @@
+import path from 'path';
+import os from 'os';
+
+/** CNB token 存储路径 */
+export function getTokenPath(): string {
+  return path.join(os.homedir(), '.cnb', 'token');
+}

package/client/utils/types.ts

@@ -0,0 +1,45 @@
+/** RFC 8628 Section 3.2 设备授权响应 */
+export interface DeviceAuthResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  expires_in: number;
+  interval: number;
+}
+
+/** /oauth2/token 成功响应 */
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token?: string;
+  id_token?: string;
+  scope?: string;
+}
+
+/** /oauth2/token 错误响应 */
+export interface TokenErrorResponse {
+  error: string;
+  error_description?: string;
+  error_hint?: string;
+}
+
+/** 登录配置 */
+export interface LoginConfig {
+  clientID: string;
+  platformURL: string;
+  debug: boolean;
+}
+
+/** 持久化的 token 结构 */
+export interface TokenStore {
+  access_token: string;
+  /** access_token 过期的 Unix 时间戳（秒） */
+  expires_at: number;
+  refresh_token?: string;
+  /** 用于 refresh 时知道 OAuth 端点 */
+  platform_url?: string;
+  /** 用于 refresh 时携带 client_id */
+  client_id?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",

package/skills-template/SKILL.md

@@ -7,63 +7,48 @@ description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、
 
 操作 CNB 平台资源的 CLI 工具。
 
-## 安装CLI
-
-检查是否已安装
-
-```bash
-cnb
-```
-
-如果没有安装，则安装
-
-```bash
-npm install @cnbcool/cnb-cli -g
-```
-
-## 快捷命令（优先使用）
-
-issues 快捷命令：
-- `<$CNB_CLI_CMD$> issues get` — 获取 Issue 详情
-- `<$CNB_CLI_CMD$> issues list-comments` — 列出 Issue 评论
-- `<$CNB_CLI_CMD$> issues comment --body 内容` — 发表 Issue 评论
-- `<$CNB_CLI_CMD$> issues close` — 关闭 Issue
-- `<$CNB_CLI_CMD$> issues open` — 打开 Issue
-- `<$CNB_CLI_CMD$> issues list-labels` — 列出 Issue 标签
-- `<$CNB_CLI_CMD$> issues add-labels --labels bug --labels feature` — 添加 Issue 标签
-- `<$CNB_CLI_CMD$> issues list-assignees` — 查看 Issue 处理人
-- `<$CNB_CLI_CMD$> issues add-assignees --assignees username` — 添加 Issue 处理人
-- `<$CNB_CLI_CMD$> issues upload-file --file 文件路径` — 上传文件到 Issue
-- `<$CNB_CLI_CMD$> issues upload-image --file 图片路径` — 上传图片到 Issue
-
-pulls 快捷命令：
-- `<$CNB_CLI_CMD$> pulls get` — 获取 PR 详情
-- `<$CNB_CLI_CMD$> pulls list-files` — 列出 PR 变更文件
-- `<$CNB_CLI_CMD$> pulls list-commits` — 列出 PR 提交记录
-- `<$CNB_CLI_CMD$> pulls list-comments` — 列出 PR 评论
-- `<$CNB_CLI_CMD$> pulls comment --body 内容` — 发表 PR 评论
-- `<$CNB_CLI_CMD$> pulls list-labels` — 列出 PR 标签
-- `<$CNB_CLI_CMD$> pulls add-labels --labels ready --labels approved` — 添加 PR 标签
-- `<$CNB_CLI_CMD$> pulls check-status` — 查看 CI 状态
-- `<$CNB_CLI_CMD$> pulls list-reviews` — 查看评审列表
-- `<$CNB_CLI_CMD$> pulls list-assignees` — 查看 PR 处理人
-- `<$CNB_CLI_CMD$> pulls upload-file --file 文件路径` — 上传文件到 PR
-- `<$CNB_CLI_CMD$> pulls upload-image --file 图片路径` — 上传图片到 PR
-
-注意：
-- **路径参数自动注入**：仓库 slug、Issue/PR 编号优先从环境变量自动获取，无需额外传入任何其他参数
-- **默认只输出摘要**：会精简响应输出结果，只返回核心字段。加 `--verbose` 输出完整数据。
-- 快捷命令只能操作当前仓库的当前Issue或PR。跨仓库或跨编号操作请使用其他 API 命令。
-
-## 其他 API（快捷命令不满足时使用）
+## 快捷命令
+
+issues:
+- `<$CNB_CLI_CMD$> issues get` — 获取当前 Issue 详情
+- `<$CNB_CLI_CMD$> issues list-comments` — 列出当前 Issue 评论
+- `<$CNB_CLI_CMD$> issues comment --body '内容'` — 发表评论到当前 Issue
+- `<$CNB_CLI_CMD$> issues close` — 关闭当前 Issue
+- `<$CNB_CLI_CMD$> issues open` — 打开当前 Issue
+- `<$CNB_CLI_CMD$> issues list-labels` — 列出当前 Issue 标签
+- `<$CNB_CLI_CMD$> issues add-labels --labels bug --labels feature` — 添加标签到当前 Issue
+- `<$CNB_CLI_CMD$> issues list-assignees` — 查看当前 Issue 处理人
+- `<$CNB_CLI_CMD$> issues add-assignees --assignees username` — 添加处理人到当前 Issue
+- `<$CNB_CLI_CMD$> issues upload-file --file 文件路径` — 上传文件到当前 Issue
+- `<$CNB_CLI_CMD$> issues upload-image --file 图片路径` — 上传图片到当前 Issue
+
+pulls:
+- `<$CNB_CLI_CMD$> pulls get` — 获取当前 PR 详情
+- `<$CNB_CLI_CMD$> pulls list-files` — 列出当前 PR 变更文件
+- `<$CNB_CLI_CMD$> pulls list-commits` — 列出当前 PR 提交记录
+- `<$CNB_CLI_CMD$> pulls list-comments` — 列出当前 PR 评论
+- `<$CNB_CLI_CMD$> pulls comment --body '内容'` — 发表 PR 评论
+- `<$CNB_CLI_CMD$> pulls list-labels` — 列出当前 PR 标签
+- `<$CNB_CLI_CMD$> pulls add-labels --labels ready --labels approved` — 添加标签到当前 PR
+- `<$CNB_CLI_CMD$> pulls check-status` — 获取当前 PR 的 CI 状态
+- `<$CNB_CLI_CMD$> pulls get-ci-logs` — 获取当前 PR 的 CI 构建日志
+- `<$CNB_CLI_CMD$> pulls list-reviews` — 查看当前当前的评审列表
+- `<$CNB_CLI_CMD$> pulls list-assignees` — 查看当前 PR 处理人
+- `<$CNB_CLI_CMD$> pulls upload-file --file 文件路径` — 上传文件到当前 PR
+- `<$CNB_CLI_CMD$> pulls upload-image --file 图片路径` — 上传图片到当前 PR
+
+注意事项：
+- **路径参数自动识别**：快捷命令中的 Issue/PR 编号会自动从环境变量识别，无需额外传递。
+- **默认只输出摘要**：默认会精简响应输出结果，只返回核心字段。添加 `--verbose` 输出完整数据。
+- **多行文本传参使用单引号**：传递多行文本参数时，使用单引号可防止命令注入攻击，并减少不必要的转义。
+- **快捷命令范围** 快捷命令只能操作当前仓库的当前 Issue/PR，跨仓库或跨编号操作请使用其他 API 命令。
+
+## 更多 API
+
+优先使用快捷命令，不满足时才使用以下这些命令
 
 1. `<$CNB_CLI_CMD$> --help` 查看所有模块
 2. `<$CNB_CLI_CMD$> <module> --help` 查看模块下的工具列表
 3. `<$CNB_CLI_CMD$> <module> <tool> --help` 查看工具参数
-4. 按参数说明执行
-
-## 规则
+4. 按帮助文档操作，禁止猜测
 
-- 优先使用快捷命令，不满足时再 `--help` 逐步查找
-- 使用非快捷命令时，必须先 `--help` 获取帮助，禁止猜测
-- 直接执行命令，不要询问用户确认