@cnbcool/cnb-api-generate 2.3.5 → 2.4.1

package/client/lib/build-diagnostics.ts

@@ -1,52 +1,19 @@
 /**
- * 构建诊断模块
+ * 构建失败诊断模块
  *
  * 查询流水线失败 Stage 的详细日志和错误信息，同时输出耗时数据辅助分析。
  * 内置降级逻辑：Stage 详情失败时自动尝试全量日志下载（含 base64 解码）。
  *
  * sn 获取策略（按优先级）：
  *   1. 用户通过 --sn 显式传入
- *   2. 环境变量 CNB_BUILD_ID（当前构建自身的 sn）
- *   3. 从 PR commit statuses 中提取失败构建的 sn
+ *   2. 有 PR 上下文时，从 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;
-}
+import {
+  apiRequest,
+  apiRequestText,
+  resolveBuildContext,
+} from './build-helpers';
 
 /**
  * 降级方案：下载全量日志
@@ -77,42 +44,10 @@ export async function diagnoseBuild(options: {
   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 resolved = await resolveBuildContext(options);
+  if (!resolved.ok) return resolved.message;
 
-  const baseUrl = `${domain}/${repo}`;
+  const { sn, baseUrl, headers } = resolved.ctx;
   const lines: string[] = [];
   lines.push(`查询构建 sn=${sn} 的流水线状态...\n`);
 

package/client/lib/build-helpers.ts

@@ -0,0 +1,180 @@
+/**
+ * 构建诊断 / 性能分析的共用 helper
+ *
+ * 两个对外自定义命令共享：
+ *   - cnb pulls get-ci-logs   → build-diagnostics.ts:diagnoseBuild
+ *   - cnb pulls get-ci-timing → build-timing.ts:analyzeBuildTiming
+ */
+
+import { resolveToken } from '../utils/resolve-token';
+
+/** CNB 构建号格式：cnb-xxx-xxxxxxxxx（字母/数字组成的两段） */
+export const SN_PATTERN = /^cnb-[a-z0-9]+-[a-z0-9]+$/i;
+
+export function invalidSnMessage(sn: string): string {
+  return [
+    `参数 --sn 的值不是合法的构建号: "${sn}"`,
+    '',
+    '构建号（sn）格式应为 cnb-xxx-xxxxxxxxx，例如 cnb-9p9-1jnfh8rv5。',
+    '常见错误：把 `cnb pulls check-status` 返回的 context 字段（形如',
+    '"cnb/pull_request/common-lint"）当成 sn 传入，这是 CI 状态的检查项名，',
+    '不是构建号。',
+    '',
+    '请去掉 --sn 参数重试，工具会自动从当前 PR 的 CI 状态中解析失败构建的 sn。',
+  ].join('\n');
+}
+
+export async function apiRequest(url: string, headers: Record<string, string>): Promise<any> {
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    // 注意：错误消息中暴露 URL 是有意的，便于调试。
+    // 本项目所有 API 凭证通过 Authorization header 传递，不走 query string，
+    // 因此 URL 中不含敏感信息。未来如需在 URL 拼接 query 参数，请同步审视这里。
+    throw new Error(`请求失败: ${res.status} ${res.statusText} — ${url}`);
+  }
+  return res.json();
+}
+
+export async function apiRequestText(url: string, headers: Record<string, string>): Promise<string> {
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    // 见 apiRequest 注释
+    throw new Error(`请求失败: ${res.status} ${res.statusText} — ${url}`);
+  }
+  return res.text();
+}
+
+/**
+ * 从 PR 的 commit statuses 中提取失败构建的 sn
+ * 仅选 state=error/failure 的检查项，从 target_url 中解析构建 sn
+ * target_url 通常形如 https://cnb.cool/{repo}/-/build/logs/{sn}
+ */
+export function extractSnFromStatuses(statusData: any): string | null {
+  const statuses = statusData?.statuses || statusData;
+  if (!Array.isArray(statuses) || statuses.length === 0) return null;
+
+  const failed = statuses.find(
+    (s: any) => s.state === 'error' || s.state === 'failure',
+  );
+  if (!failed) return null;
+
+  return extractSnFromUrl(failed.target_url || '');
+}
+
+/**
+ * 从构建链接 URL 中提取 sn
+ * 支持两种格式：
+ *   .../-/build/logs/{sn}  ← check-status 的 target_url
+ *   .../-/build/{sn}       ← 兼容老路径
+ */
+export function extractSnFromUrl(url: string): string | null {
+  if (!url) return null;
+  // 优先匹配 /-/build/logs/{sn}
+  const logsMatch = url.match(/\/-\/build\/logs\/([^/?#]+)/);
+  if (logsMatch && SN_PATTERN.test(logsMatch[1])) {
+    return logsMatch[1];
+  }
+  // 回退匹配 /-/build/{sn}
+  const buildMatch = url.match(/\/-\/build\/([^/?#]+)/);
+  if (buildMatch && SN_PATTERN.test(buildMatch[1])) {
+    return buildMatch[1];
+  }
+  return null;
+}
+
+export interface ResolveSnOptions {
+  repo: string;
+  sn?: string;
+  prNumber?: string;
+  /** 当未找到失败构建、但想回退到"最近一个构建"时使用（例如 timing 分析场景） */
+  fallbackToLatestStatus?: boolean;
+}
+
+export interface ResolvedContext {
+  /** 校验/解析出来的最终 sn；若为空字符串则表示应立即返回 errorMessage */
+  sn: string;
+  domain: string;
+  baseUrl: string;
+  headers: Record<string, string>;
+}
+
+/**
+ * 统一解析 sn + token + baseUrl
+ *
+ * 返回格式：
+ *   - { ok: true, ctx }   成功解析
+ *   - { ok: false, message } 解析失败，调用方应直接把 message 返回给用户
+ */
+export async function resolveBuildContext(
+  options: ResolveSnOptions,
+): Promise<
+  | { ok: true; ctx: ResolvedContext }
+  | { ok: false; message: string }
+> {
+  const domain = process.env.CNB_API_ENDPOINT || 'https://api.cnb.cool';
+  const { repo } = options;
+  let sn = options.sn;
+
+  // 策略 1: 显式传入的 sn — 需先校验格式，尽早失败
+  if (sn && !SN_PATTERN.test(sn)) {
+    return { ok: false, message: invalidSnMessage(sn) };
+  }
+
+  const token = await resolveToken();
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.cnb.api+json',
+    Authorization: `Bearer ${token}`,
+  };
+
+  // 策略 2: 有 PR 上下文时，从 PR commit statuses 中取失败（或最近）构建 sn。
+  if (!sn && options.prNumber) {
+    try {
+      // 对应 swagger: GET /{repo}/-/pulls/{number}/commit-statuses
+      const statusesUrl = `${domain}/${repo}/-/pulls/${options.prNumber}/commit-statuses`;
+      const statusData = await apiRequest(statusesUrl, headers);
+      sn = extractSnFromStatuses(statusData) ?? undefined;
+
+      if (!sn && options.fallbackToLatestStatus) {
+        // timing 场景：没失败也允许分析，回退到第一个能解析出合法 sn 的 status
+        const statuses = statusData?.statuses || statusData;
+        if (Array.isArray(statuses)) {
+          for (const s of statuses) {
+            const parsed = extractSnFromUrl(s?.target_url || '');
+            if (parsed) {
+              sn = parsed;
+              break;
+            }
+          }
+        }
+      }
+    } catch (e: any) {
+      return { ok: false, message: `获取 PR CI 状态失败: ${e.message}` };
+    }
+  }
+
+  if (!sn) {
+    if (options.prNumber) {
+      return {
+        ok: false,
+        message: options.fallbackToLatestStatus
+          ? '未从 PR CI 状态中找到任何可分析的构建。'
+          : '未从 PR CI 状态中找到失败的构建，所有构建均为成功状态。',
+      };
+    }
+    return {
+      ok: false,
+      message:
+        '缺少构建号(sn)：未传入 --sn 且未检测到 PR 上下文（CNB_PULL_REQUEST_IID）。',
+    };
+  }
+
+  return {
+    ok: true,
+    ctx: {
+      sn,
+      domain,
+      baseUrl: `${domain}/${repo}`,
+      headers,
+    },
+  };
+}

package/client/lib/build-timing.ts

@@ -0,0 +1,256 @@
+/**
+ * 构建耗时分析模块
+ *
+ * 查询流水线所有 Stage 的耗时数据，分析瓶颈并给出优化提示。
+ *
+ * sn 获取策略（按优先级）：
+ *   1. 用户通过 --sn 显式传入
+ *   2. 有 PR 上下文时，从 PR commit statuses 中提取失败构建的 sn；
+ *      若无失败则回退到最近一条可解析的构建
+ */
+
+import { apiRequest, resolveBuildContext } from './build-helpers';
+
+function formatDuration(ms: number | null | undefined): string {
+  if (ms == null) return 'N/A';
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainSec = (seconds % 60).toFixed(0);
+  return `${minutes}m${remainSec}s`;
+}
+
+function progressBar(ratio: number, width = 20): string {
+  const filled = Math.round(ratio * width);
+  const empty = width - filled;
+  return '█'.repeat(filled) + '░'.repeat(empty);
+}
+
+interface StageTiming {
+  pipelineName: string;
+  pipelineId: string;
+  stageId: string;
+  stageName: string;
+  status: string;
+  duration: number;
+  needs: string[];
+}
+
+/**
+ * 分析构建耗时瓶颈
+ */
+export async function analyzeBuildTiming(options: {
+  repo: string;
+  sn?: string;
+  prNumber?: string;
+}): Promise<string> {
+  const resolved = await resolveBuildContext({
+    ...options,
+    // 耗时分析场景下，即使没有失败构建也允许分析成功的构建
+    fallbackToLatestStatus: true,
+  });
+  if (!resolved.ok) return resolved.message;
+
+  const { sn, baseUrl, headers } = resolved.ctx;
+  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 '该构建没有流水线';
+  }
+
+  const allStages: StageTiming[] = [];
+  let totalBuildDuration = 0;
+
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('  CI 流水线耗时分析');
+  lines.push('═══════════════════════════════════════════════════════\n');
+
+  for (const [pipelineName, pipeline] of pipelines) {
+    const { id: pipelineId, status, stages } = pipeline;
+    if (!Array.isArray(stages) || stages.length === 0) continue;
+
+    let pipelineDuration = 0;
+    const stageTimings: StageTiming[] = [];
+
+    for (const stage of stages) {
+      const duration = stage.duration || 0;
+      pipelineDuration += duration;
+      stageTimings.push({
+        pipelineName,
+        pipelineId,
+        stageId: stage.id,
+        stageName: stage.name || stage.id,
+        status: stage.status,
+        duration,
+        needs: stage.needs || [],
+      });
+    }
+
+    totalBuildDuration += pipelineDuration;
+
+    lines.push(
+      `━━━ Pipeline: ${pipelineName} (status: ${status}, 总耗时: ${formatDuration(pipelineDuration)}) ━━━\n`,
+    );
+
+    // 按耗时从大到小排序
+    const sorted = [...stageTimings].sort((a, b) => b.duration - a.duration);
+
+    for (const s of sorted) {
+      const ratio = pipelineDuration > 0 ? s.duration / pipelineDuration : 0;
+      const pct = (ratio * 100).toFixed(1);
+      const bar = progressBar(ratio);
+      const statusIcon = s.status === 'success' ? '✅' : s.status === 'error' ? '❌' : '⏳';
+      lines.push(`  ${statusIcon} ${s.stageName}`);
+      lines.push(`     耗时: ${formatDuration(s.duration)}  (${pct}%)  ${bar}`);
+    }
+
+    lines.push('');
+    allStages.push(...stageTimings);
+  }
+
+  // 全局 Stage 耗时排行
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('  全局 Stage 耗时排行 (Top 10)');
+  lines.push('═══════════════════════════════════════════════════════\n');
+
+  const globalSorted = [...allStages].sort((a, b) => b.duration - a.duration);
+  const top10 = globalSorted.slice(0, 10);
+
+  for (let i = 0; i < top10.length; i++) {
+    const s = top10[i];
+    const ratio = totalBuildDuration > 0 ? s.duration / totalBuildDuration : 0;
+    const pct = (ratio * 100).toFixed(1);
+    lines.push(`  #${i + 1}  ${s.pipelineName} → ${s.stageName}`);
+    lines.push(`      耗时: ${formatDuration(s.duration)}  (占总耗时 ${pct}%)`);
+  }
+
+  lines.push(`\n  总耗时: ${formatDuration(totalBuildDuration)} (所有 Stage 耗时之和)`);
+
+  // 获取耗时最长 Stage 的详情日志用于分析
+  lines.push('\n═══════════════════════════════════════════════════════');
+  lines.push('  耗时最长 Stage 的详情日志（用于分析优化点）');
+  lines.push('═══════════════════════════════════════════════════════\n');
+
+  const topStages = globalSorted.slice(0, 3);
+  for (const s of topStages) {
+    lines.push(`▸ ${s.pipelineName} → ${s.stageName} (${formatDuration(s.duration)})`);
+    try {
+      const detail = await apiRequest(
+        `${baseUrl}/-/build/logs/stage/${sn}/${s.pipelineId}/${s.stageId}`,
+        headers,
+      );
+
+      if (detail.duration != null) {
+        lines.push(`  Stage 实际耗时: ${formatDuration(detail.duration)}`);
+      }
+
+      if (Array.isArray(detail.content) && detail.content.length > 0) {
+        lines.push('  ─── 日志（末尾 50 行）───');
+        const logLines = detail.content;
+        const tail = logLines.slice(Math.max(0, logLines.length - 50));
+        for (const line of tail) {
+          lines.push(`  ${line}`);
+        }
+        if (logLines.length > 50) {
+          lines.push(`  ... (省略了前 ${logLines.length - 50} 行，共 ${logLines.length} 行)`);
+        }
+        lines.push('  ─── 日志结束 ───');
+      } else {
+        lines.push('  （无日志内容）');
+      }
+    } catch (e: any) {
+      lines.push(`  查询 Stage 详情失败: ${e.message}`);
+    }
+    lines.push('');
+  }
+
+  // 统计摘要
+  lines.push('═══════════════════════════════════════════════════════');
+  lines.push('  统计摘要');
+  lines.push('═══════════════════════════════════════════════════════\n');
+
+  lines.push(`  Pipeline 数量: ${pipelines.length}`);
+  lines.push(`  Stage 总数: ${allStages.length}`);
+  lines.push(`  成功 Stage: ${allStages.filter((s) => s.status === 'success').length}`);
+  lines.push(`  失败 Stage: ${allStages.filter((s) => s.status === 'error').length}`);
+  lines.push(`  总耗时: ${formatDuration(totalBuildDuration)}`);
+
+  if (globalSorted.length > 0) {
+    const longest = globalSorted[0];
+    lines.push(
+      `  最慢 Stage: ${longest.pipelineName} → ${longest.stageName} (${formatDuration(longest.duration)})`,
+    );
+  }
+
+  // 检测潜在优化点
+  lines.push('\n═══════════════════════════════════════════════════════');
+  lines.push('  潜在优化点提示');
+  lines.push('═══════════════════════════════════════════════════════\n');
+
+  const hints: string[] = [];
+
+  // 检测: 耗时超过 5 分钟的 Stage
+  const slowStages = allStages.filter((s) => s.duration > 300000);
+  if (slowStages.length > 0) {
+    hints.push(`⚠️  有 ${slowStages.length} 个 Stage 耗时超过 5 分钟，建议重点优化`);
+    for (const s of slowStages) {
+      hints.push(`   - ${s.pipelineName} → ${s.stageName}: ${formatDuration(s.duration)}`);
+    }
+  }
+
+  // 检测: 耗时占比超过 50% 的单个 Stage
+  const dominantStages = allStages.filter(
+    (s) => totalBuildDuration > 0 && s.duration / totalBuildDuration > 0.5,
+  );
+  if (dominantStages.length > 0) {
+    for (const s of dominantStages) {
+      const pct = ((s.duration / totalBuildDuration) * 100).toFixed(1);
+      hints.push(`⚠️  Stage "${s.stageName}" 占总耗时 ${pct}%，是主要瓶颈`);
+    }
+  }
+
+  // 检测: 单个 Pipeline 内 Stage 数很多但都串行
+  for (const [pipelineName, pipeline] of pipelines) {
+    if (Array.isArray(pipeline.stages) && pipeline.stages.length > 5) {
+      const noDeps = pipeline.stages.filter(
+        (s: any) => !s.needs || s.needs.length === 0,
+      );
+      if (noDeps.length > 3) {
+        hints.push(
+          `💡 Pipeline "${pipelineName}" 有 ${noDeps.length} 个无依赖的 Stage，可考虑并行执行`,
+        );
+      }
+    }
+  }
+
+  if (hints.length === 0) {
+    lines.push('  ✅ 未检测到明显的耗时异常');
+  } else {
+    for (const hint of hints) {
+      lines.push(`  ${hint}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/client/lib/execute-action.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 import { showShort, resolveShortcut, type ResolvedShortcut } from '../shortcuts';
 import { handleUpload } from '../utils/upload';
 import { diagnoseBuild } from './build-diagnostics';
+import { analyzeBuildTiming } from './build-timing';
 import { formatParams } from './format-params';
 import { formatOutput } from './format-output';
 // @ts-ignore
@@ -107,6 +108,16 @@ export async function executeAction(
     return;
   }
 
+  if (shortcut?.tool === '__get-ci-timing__') {
+    const result = await analyzeBuildTiming({
+      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/register-modules.ts

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

package/client/lib/summary-extractors.ts

@@ -136,7 +136,7 @@ const SUMMARY_EXTRACTORS: Record<string, SummaryExtractor> = {
   }),
 
   // PR CI 状态摘要：保留整体状态和各检查项的核心信息（sha 截断为前 8 位）
-  // 过滤: sha 完整值, statuses 中每项的 target_url/created_at/updated_at
+  // 保留 target_url（用于从中提取构建 sn）；过滤 created_at/updated_at
   'pulls/list-pull-commit-statuses': (item) => ({
     sha: typeof item.sha === 'string' ? item.sha.substring(0, 8) : item.sha,
     state: item.state,
@@ -144,6 +144,7 @@ const SUMMARY_EXTRACTORS: Record<string, SummaryExtractor> = {
       context: s.context,
       state: s.state,
       description: s.description,
+      target_url: s.target_url,
     })) || [],
   }),
 

package/client/shortcuts.ts

@@ -97,6 +97,7 @@ export const PR_SHORTCUTS: ShortcutDefinition[] = [
   { 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 构建号（可选）" },
+  { shortName: 'get-ci-timing', realTool: '__get-ci-timing__', description: '分析 CI 耗时瓶颈', repoOnly: true, custom: true, dataTip: "--sn 构建号（可选）" },
 ];
 
 // ============================================================

package/client/utils/resolve-token.ts

@@ -9,6 +9,13 @@ import { refreshAccessToken } from './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;

package/package.json

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

package/skills-template/SKILL.md

@@ -10,49 +10,44 @@ description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、
 ## 快捷命令
 
 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
+- `<$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 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
-- `<$CNB_CLI_CMD$> pulls get-ci-logs` — 获取 PR 失败构建的 CI 日志和耗时分析（可选 --sn 指定构建号）
+- `<$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
 
 注意事项：
-- **路径参数自动注入**：仓库 slug、Issue/PR 编号优先从环境变量自动获取，无需额外传入任何其他参数
-- **默认只输出摘要**：会精简响应输出结果，只返回核心字段。加 `--verbose` 输出完整数据。
+- **路径参数自动识别**：快捷命令中的 Issue/PR 编号会自动从环境变量识别，无需额外传递。
+- **默认只输出摘要**：默认会精简响应输出结果，只返回核心字段。添加 `--verbose` 输出完整数据。
 - **多行文本传参使用单引号**：传递多行文本参数时，使用单引号可防止命令注入攻击，并减少不必要的转义。
-- **快捷命令范围** 快捷命令只能操作当前仓库的当前Issue或PR，跨仓库或跨编号操作请使用其他 API 命令。
+- **快捷命令范围** 快捷命令只能操作当前仓库的当前 Issue/PR，跨仓库或跨编号操作请使用其他 API 命令。
 
-## 其他 API
+## 更多 API
 
-快捷命令不满足时才使用
+优先使用快捷命令，不满足时才使用以下这些命令
 
 1. `<$CNB_CLI_CMD$> --help` 查看所有模块
 2. `<$CNB_CLI_CMD$> <module> --help` 查看模块下的工具列表
 3. `<$CNB_CLI_CMD$> <module> <tool> --help` 查看工具参数
-4. 按参数说明执行
-
-## 规则
-
-- 优先使用快捷命令，不满足时再 `--help` 逐步查找
-- 使用非快捷命令时，必须先 `--help` 获取帮助，禁止猜测
+4. 按帮助文档操作，禁止猜测