@cnbcool/cnb-api-generate 2.6.0 → 2.6.2

package/client/index.ts

@@ -18,6 +18,7 @@ const program = new Command();
 program
   .name(process.env.CNB_CLI_CMD || 'cnb')
   .description('CNB OpenAPI 命令行工具')
+  .version('<CNB_CLI_VERSION>', '-v, --version', '显示版本号')
   .allowUnknownOption()
   .allowExcessArguments()
   .helpOption('-h, --help', '显示帮助文档')

package/client/lib/execute-action.ts

@@ -1,8 +1,6 @@
-import fs from 'fs';
-import path from 'path';
 import { Command } from 'commander';
-import { showShort, resolveShortcut, type ResolvedShortcut } from '../shortcuts';
-import { handleUpload } from '../utils/upload';
+import { showShort, resolveShortcut } from '../shortcuts';
+import { handleUpload, handleIssueCreateUpload, type UploadPathParams } from '../utils/upload';
 import { diagnoseBuild } from './build-diagnostics';
 import { analyzeBuildTiming } from './build-timing';
 import { formatParams } from './format-params';
@@ -23,18 +21,6 @@ function loadToolFunction(moduleName: string, toolName: string): any {
   return toolFunction;
 }
 
-/**
- * 处理上传命令的独立分支
- * 上传命令只需要 --file 和自动注入的 path 参数，不经过 formatParams
- */
-async function executeUpload(
-  shortcut: ResolvedShortcut,
-  opts: Record<string, any>,
-): Promise<any> {
-  const toolFunction = loadToolFunction(shortcut.module, shortcut.tool);
-  return handleUpload(shortcut, opts.file, toolFunction, shortcut.autoPath as any);
-}
-
 export async function executeAction(
   moduleArg: string | undefined,
   toolArg: string | undefined,
@@ -90,14 +76,22 @@ export async function executeAction(
 
   // 上传命令走独立分支：只需 --file + autoPath，跳过 formatParams 常规流程
   if (shortcut?.upload) {
-    const data = await executeUpload(shortcut, opts);
-    const toolKey = `${shortcut.module}/${shortcut.tool}`;
     const isVerbose = !!opts.verbose;
-    console.log(formatOutput(data, isVerbose, !isVerbose, toolKey));
+    const toolFunction = loadToolFunction(shortcut.module, shortcut.tool);
+    const pathParams = shortcut.autoPath as UploadPathParams;
+    let data: any;
+
+    if (shortcut.tool === 'post-asset-group') {
+      // 创建 issue 时上传：asset-group 流程（携带 image_assets / file_assets）
+      data = await handleIssueCreateUpload(shortcut, opts.file, toolFunction, pathParams);
+    } else {
+      data = await handleUpload(shortcut, opts.file, toolFunction, pathParams);
+    }
+
+    console.log(formatOutput(data, isVerbose, !isVerbose, `${shortcut.module}/${shortcut.tool}`));
     return;
   }
 
-  // 自定义命令走独立分支（不通过 swagger 生成的 tool 函数）
   if (shortcut?.tool === '__get-ci-logs__') {
     const result = await diagnoseBuild({
       repo: process.env.CNB_REPO_SLUG || '',

package/client/lib/register-modules.ts

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

package/client/lib/status.ts

@@ -1,7 +1,13 @@
 import { Command } from 'commander';
-import { getTokenPath } from '../utils/token-path';
-import { loadToken } from '../utils/load-token';
+import { resolveTokenSource } from '../utils/resolve-token-source';
 import { refreshAccessToken } from '../utils/refresh-token';
+import { getTokenPath } from '../utils/token-path';
+
+const SOURCE_LABEL: Record<string, string> = {
+  workbuddy: 'WorkBuddy 远程获取',
+  codebuddy_env: 'CNB_TOKEN_FOR_CODEBUDDY 环境变量',
+  env: 'CNB_TOKEN 环境变量',
+};
 
 export function registerStatusCommand(program: Command): void {
   program
@@ -10,38 +16,46 @@ export function registerStatusCommand(program: Command): void {
     .option('--debug', '打印调试信息', false)
     .helpOption('-h, --help', '显示帮助文档')
     .action(async (opts) => {
-      const tokenPath = getTokenPath();
-      const token = loadToken();
+      const result = await resolveTokenSource();
+
+      if (result.source === 'none') {
+        console.log(result.reason ? `⚠️  ${result.reason}` : '⚠️  未登录，请执行 `cnb login` 进行授权。');
+        return;
+      }
 
-      if (!token) {
-        console.log('⚠️  未登录，请执行 `cnb login` 进行授权。');
+      // 环境变量 / WorkBuddy 来源，无过期概念
+      if (result.source !== 'file') {
+        console.log('✅ 已登录。');
+        if (opts.debug) {
+          console.log(`   Token 来源: ${SOURCE_LABEL[result.source]}`);
+        }
         return;
       }
 
+      // 文件来源 - 检查过期
+      const tokenPath = getTokenPath();
+      const store = result.store;
+
       if (opts.debug) {
         console.log(`Token 文件路径 : ${tokenPath}`);
-        console.log(`Platform URL  : ${token.platform_url || '未知'}`);
-        console.log(`Client ID     : ${token.client_id || '未知'}`);
-        console.log(`Expires At    : ${new Date(token.expires_at * 1000).toLocaleString()}`);
+        console.log(`Platform URL  : ${store.platform_url || '未知'}`);
+        console.log(`Client ID     : ${store.client_id || '未知'}`);
+        console.log(`Expires At    : ${new Date(store.expires_at * 1000).toLocaleString()}`);
       }
 
       const nowSec = Math.floor(Date.now() / 1000);
-      const isExpired = nowSec >= token.expires_at;
+      const isExpired = nowSec >= store.expires_at;
 
       if (isExpired) {
-        // 尝试使用 refresh_token 刷新
-        if (token.refresh_token) {
+        if (store.refresh_token) {
           if (opts.debug) {
             console.log('Token 已过期，尝试使用 refresh_token 刷新...');
           }
           try {
-            await refreshAccessToken(token);
-            const refreshedToken = loadToken();
-            if (refreshedToken) {
-              console.log('✅ 已登录。');
-              if (opts.debug) {
-                console.log('   （Token 已自动刷新）');
-              }
+            await refreshAccessToken(store);
+            console.log('✅ 已登录。');
+            if (opts.debug) {
+              console.log('   （Token 已自动刷新）');
             }
           } catch (err: any) {
             if (opts.debug) {

package/client/utils/resolve-token-source.ts

@@ -0,0 +1,82 @@
+import { getTokenEnvKey } from './get-token-env-key';
+import { isWorkBuddySandbox } from './is-workbuddy-sandbox';
+import { loadToken } from './load-token';
+import type { TokenStore } from './types';
+
+export type TokenSourceResult =
+  | { source: 'workbuddy'; access_token: string }
+  | { source: 'codebuddy_env'; access_token: string }
+  | { source: 'env'; access_token: string }
+  | { source: 'file'; access_token: string; store: TokenStore }
+  | { source: 'none'; reason?: string };
+
+/**
+ * 统一判断 token 来源，不退出进程、不自动刷新。
+ *
+ * 优先级：
+ * 1. WorkBuddy 沙箱环境 → 远程接口获取
+ * 2. CNB_TOKEN_FOR_CODEBUDDY 环境变量
+ * 3. CNB_TOKEN 环境变量
+ * 4. 文件 token（~/.cnb/token）
+ */
+export async function resolveTokenSource(): Promise<TokenSourceResult> {
+  // WorkBuddy 沙箱环境，从远程接口获取 token
+  if (isWorkBuddySandbox()) {
+    const tokenURL = process.env[getTokenEnvKey()];
+    if (!tokenURL) {
+      return {
+        source: 'none',
+        reason: `未找到环境变量 ${getTokenEnvKey()}，无法在 WorkBuddy 沙箱环境中获取 token。`,
+      };
+    }
+
+    try {
+      const resp = await fetch(tokenURL, {
+        method: 'GET',
+        headers: { Accept: 'application/json' },
+      });
+
+      if (!resp.ok) {
+        return {
+          source: 'none',
+          reason: `从 WorkBuddy 获取 token 失败，HTTP 状态码: ${resp.status} ${resp.statusText}`,
+        };
+      }
+
+      const body: any = await resp.json();
+      if (body?.code !== 0 || !body?.data?.access_token) {
+        return {
+          source: 'none',
+          reason: `从 WorkBuddy 获取 token 失败，响应内容异常: ${JSON.stringify(body)}`,
+        };
+      }
+
+      return { source: 'workbuddy', access_token: body.data.access_token as string };
+    } catch (err: any) {
+      return {
+        source: 'none',
+        reason: `从 WorkBuddy 获取 token 失败: ${err?.message || err}`,
+      };
+    }
+  }
+
+  // 环境变量优先 CodeBuddy
+  if (process.env.CNB_TOKEN_FOR_CODEBUDDY) {
+    if (!process.env.CNB_NPC_SLUG && process.env.CNB_NPC_NAME === 'CodeBuddy') {
+      return { source: 'codebuddy_env', access_token: process.env.CNB_TOKEN_FOR_CODEBUDDY };
+    }
+  }
+
+  // 环境变量优先，不做过期判断
+  if (process.env.CNB_TOKEN) {
+    return { source: 'env', access_token: process.env.CNB_TOKEN };
+  }
+
+  // 文件 token
+  const store = loadToken();
+  if (!store || !store.access_token) {
+    return { source: 'none' };
+  }
+
+  return { source: 'file', access_token: store.access_token, store };
+}

package/client/utils/resolve-token.ts

@@ -1,6 +1,4 @@
-import { getTokenEnvKey } from './get-token-env-key';
-import { isWorkBuddySandbox } from './is-workbuddy-sandbox';
-import { loadToken } from './load-token';
+import { resolveTokenSource } from './resolve-token-source';
 import { refreshAccessToken } from './refresh-token';
 
 /**
@@ -11,61 +9,25 @@ import { refreshAccessToken } from './refresh-token';
  * 刷新失败或无 refresh_token 时终止进程并提示用户重新登录。
  */
 export async function resolveToken(): Promise<string> {
-  // WorkBuddy 沙箱环境，从远程接口获取 token
-  if (isWorkBuddySandbox()) {
-    const tokenURL = process.env[getTokenEnvKey()];
-    if (!tokenURL) {
-      console.error(`未找到环境变量 ${getTokenEnvKey()}，无法在 WorkBuddy 沙箱环境中获取 token。`);
-      process.exit(1);
-    }
-
-    try {
-      const resp = await fetch(tokenURL, {
-        method: 'GET',
-        headers: { Accept: 'application/json' },
-      });
-
-      if (!resp.ok) {
-        console.error(`从 WorkBuddy 获取 token 失败，HTTP 状态码: ${resp.status} ${resp.statusText}`);
-        process.exit(1);
-      }
-
-      const body: any = await resp.json();
-      if (body?.code !== 0 || !body?.data?.access_token) {
-        console.error(`从 WorkBuddy 获取 token 失败，响应内容异常: ${JSON.stringify(body)}`);
-        process.exit(1);
-      }
-
-      return body.data.access_token as string;
-    } catch (err: any) {
-      console.error(`从 WorkBuddy 获取 token 失败: ${err?.message || err}`);
-      process.exit(1);
-    }
-  }
-
-  // 环境变量优先 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;
-    }
-  }
+  const result = await resolveTokenSource();
 
-  // 环境变量优先，不做过期判断
-  if (process.env.CNB_TOKEN) {
-    return process.env.CNB_TOKEN;
+  if (result.source === 'none') {
+    console.error(result.reason || '未找到有效的登录凭证，请先执行 `cnb login` 进行授权。');
+    process.exit(1);
   }
 
-  const store = loadToken();
-  if (!store || !store.access_token) {
-    console.error('未找到有效的登录凭证，请先执行 `cnb login` 进行授权。');
-    process.exit(1);
+  // 环境变量来源直接返回，不做过期检查
+  if (result.source === 'workbuddy' || result.source === 'codebuddy_env' || result.source === 'env') {
+    return result.access_token;
   }
 
+  // 文件来源 - 检查过期
+  const store = result.store;
   const nowSec = Math.floor(Date.now() / 1000);
 
   // 未过期，直接返回
   if (nowSec < store.expires_at) {
-    return store.access_token;
+    return result.access_token;
   }
 
   // 已过期，尝试 refresh

package/client/utils/upload.ts

@@ -72,43 +72,34 @@ function mimeLookup(filePath: string): string {
 // 上传文件大小上限：100MB
 const MAX_FILE_SIZE = 100 * 1024 * 1024;
 
-/** 上传 API 的 path 参数（issue 走 asset-group 流程时只需要 repo） */
-interface UploadPathParams {
+/** 上传 API 的 path 参数（issue 走 comment-asset-upload-url 流程需要 repo + number） */
+export interface UploadPathParams {
   repo: string;
   number?: string;
+  /** 兼容 autoPath 的动态字段（如 review_id） */
+  [key: string]: string | undefined;
 }
 
-/** Issue asset-group 单条附件的描述（请求体里的元素） */
-interface AssetItem {
+/** Issue comment-asset-upload-url 接口请求体（单文件，与 swagger PostIssueAssetUploadURLForm 对齐） */
+interface IssueAssetUploadURLBody {
   name: string;
   size: number;
   content_type: string;
 }
 
-/** Issue asset-group 创建请求体 */
-interface IssueAssetGroupBody {
-  file_assets?: AssetItem[];
-  image_assets?: AssetItem[];
-}
-
 /** Pull 上传请求体 */
 interface PullUploadBody {
   name: string;
   size: number;
 }
 
-/** Issue asset-group 接口响应（与 swagger 一致；只列出我们用到的字段） */
-interface AssetUploadEntry {
+/** Issue comment-asset-upload-url 接口响应（与 swagger api.IssueAssetUploadURL 对齐） */
+interface IssueAssetUploadURLResponseData {
   name?: string;
   path?: string;
   asset_link?: string;
   upload_url?: string;
 }
-interface IssueAssetGroupResponseData {
-  asset_group_id?: string;
-  file_upload_urls?: AssetUploadEntry[];
-  image_upload_urls?: AssetUploadEntry[];
-}
 
 /** Pull 上传 API 响应 */
 interface PullUploadResponseData {
@@ -117,11 +108,11 @@ interface PullUploadResponseData {
   token?: string;
 }
 
-/** 上传 API 函数签名（issue 与 pull 分别由对应的 swagger 函数承担，统一为 (firstArg, body)） */
+/** 上传 API 函数签名（issue 与 pull 分别由对应的 swagger 函数承担） */
 type UploadApiFunction = (
   firstArg: UploadPathParams | string,
-  body: IssueAssetGroupBody | PullUploadBody,
-) => Promise<{ status?: number; data?: IssueAssetGroupResponseData | PullUploadResponseData }>;
+  body: IssueAssetUploadURLBody | PullUploadBody,
+) => Promise<{ status?: number; data?: IssueAssetUploadURLResponseData | PullUploadResponseData }>;
 
 /** 上传失败时的 data */
 interface UploadErrorData {
@@ -129,12 +120,13 @@ interface UploadErrorData {
   detail?: string;
 }
 
-/** Issue 上传成功时的 data */
+/** Issue 上传成功时的 data（asset_group_id 仅在创建 issue 流程下返回） */
 interface IssueUploadData {
   asset_link?: string;
-  asset_group_id?: string;
   name: string;
+  path?: string;
   size: number;
+  asset_group_id?: string;
 }
 
 /** Pull 上传成功时的 data */
@@ -145,120 +137,64 @@ interface PullUploadData {
   token?: string;
 }
 
-/** handleUpload 的返回值 */
+/** handleUpload / handleIssueCreateUpload 的返回值 */
 interface UploadResult {
   status: number;
   data: UploadErrorData | IssueUploadData | PullUploadData;
 }
 
-/**
- * 处理完整上传流程
- *
- * Issue 路径（走 asset-group 一次性接口）：
- *   1. POST /{repo}/-/issues/asset-groups 携带 file_assets 或 image_assets
- *      → 服务端创建 asset_group 并返回 upload_url + asset_link
- *   2. PUT 文件流到 upload_url
- *   3. 返回 asset_link 给调用方拼到评论或 issue 描述里
- *
- * Pull 路径（保留原有的 upload-files / upload-imgs 一步上传）：
- *   1. POST /{repo}/upload-files（或 imgs） 拿 upload_url
- *   2. PUT 文件流到 upload_url
- *
- * @param shortcut    解析后的快捷命令；shortcut.kind 决定 issue 上传走 file 还是 image 通道
- * @param filePath    本地文件路径
- * @param toolFunction 原始上传 API 函数
- * @param pathParams  API 调用的 path 参数（issue 只需 repo；pull 也只需 repo）
- */
-export async function handleUpload(
-  shortcut: ResolvedShortcut,
-  filePath: string | undefined,
-  toolFunction: UploadApiFunction,
-  pathParams: UploadPathParams,
-): Promise<UploadResult> {
-  // 校验 file 参数
+/** 文件校验结果 */
+interface FileInfo {
+  filePath: string;
+  fileName: string;
+  fileSize: number;
+  contentType: string;
+}
+type ValidateFileResult = { ok: true; info: FileInfo } | { ok: false; result: UploadResult };
+
+/** 校验本地文件是否可上传，返回文件元信息或错误 */
+function validateFile(filePath: string | undefined): ValidateFileResult {
   if (!filePath) {
-    return { status: 400, data: { error: `上传命令需要指定文件路径，如: --data '{"file":"./path/to/file"}'` } };
+    return { ok: false, result: { status: 400, data: { error: `上传命令需要指定文件路径，如: --data '{"file":"./path/to/file"}'` } } };
   }
-
-  // 1. 读取本地文件信息
   if (!fs.existsSync(filePath)) {
-    return { status: 400, data: { error: `文件不存在: ${filePath}` } };
+    return { ok: false, result: { status: 400, data: { error: `文件不存在: ${filePath}` } } };
   }
-
   const stat = fs.statSync(filePath);
   if (!stat.isFile()) {
-    return { status: 400, data: { error: `不是文件: ${filePath}` } };
+    return { ok: false, result: { status: 400, data: { error: `不是文件: ${filePath}` } } };
   }
-
-  const fileName = nodePath.basename(filePath);
   const fileSize = stat.size;
-
   if (fileSize === 0) {
-    return { status: 400, data: { error: '文件为空' } };
+    return { ok: false, result: { status: 400, data: { error: '文件为空' } } };
   }
   if (fileSize > MAX_FILE_SIZE) {
-    return { status: 400, data: { error: `文件过大 (${(fileSize / 1024 / 1024).toFixed(1)}MB)，上限 ${MAX_FILE_SIZE / 1024 / 1024}MB` } };
-  }
-
-  const contentType = mimeLookup(filePath);
-
-  // 2. 调用上传 API 获取 upload_url
-  const isIssueUpload = shortcut.module === 'issues';
-  const isImageKind = shortcut.kind === 'image';
-
-  let uploadUrl: string | undefined;
-  let issueAssetLink: string | undefined;
-  let issueAssetGroupId: string | undefined;
-  let pullResponseData: PullUploadResponseData | undefined;
-
-  if (isIssueUpload) {
-    // Issue: 调 post-asset-group，一次拿 asset_group_id + upload_url + asset_link
-    // 函数签名：(repo: string, { file_assets | image_assets }, ...)
-    const assetItem: AssetItem = { name: fileName, size: fileSize, content_type: contentType };
-    const requestBody: IssueAssetGroupBody = isImageKind
-      ? { image_assets: [assetItem] }
-      : { file_assets: [assetItem] };
-
-    const apiResponse = await toolFunction(pathParams.repo, requestBody);
-    const data = apiResponse?.data as IssueAssetGroupResponseData | undefined;
-
-    // 服务端可能返回 201/200，从对应数组里取第一条 upload 描述
-    const entries = isImageKind ? data?.image_upload_urls : data?.file_upload_urls;
-    const entry = entries?.[0];
-    uploadUrl = entry?.upload_url;
-    issueAssetLink = entry?.asset_link;
-    issueAssetGroupId = data?.asset_group_id;
-
-    if (!uploadUrl) {
-      // 拿 URL 失败：把原始响应作为错误返回，便于排查
-      return apiResponse as unknown as UploadResult;
-    }
-  } else {
-    // Pull: 沿用原有"一步走"上传接口
-    // 函数签名：(repo: string, { name, size }, ...)
-    const requestBody: PullUploadBody = { name: fileName, size: fileSize };
-    const apiResponse = await toolFunction(pathParams.repo, requestBody);
-    pullResponseData = apiResponse?.data as PullUploadResponseData | undefined;
-    uploadUrl = pullResponseData?.upload_url;
-
-    if (!uploadUrl) {
-      return apiResponse as unknown as UploadResult;
-    }
+    return { ok: false, result: { status: 400, data: { error: `文件过大 (${(fileSize / 1024 / 1024).toFixed(1)}MB)，上限 ${MAX_FILE_SIZE / 1024 / 1024}MB` } } };
   }
-
-  // 3. PUT 文件内容到 upload_url（流式读取，避免大文件撑爆内存）
-  const fileStream = fs.createReadStream(filePath);
-
-  const putHeaders: Record<string, string> = {
-    'Content-Type': contentType,
-    'Content-Length': String(fileSize),
+  return {
+    ok: true,
+    info: {
+      filePath,
+      fileName: nodePath.basename(filePath),
+      fileSize,
+      contentType: mimeLookup(filePath),
+    },
   };
+}
 
+/** PUT 文件流到指定 URL，返回错误结果或 undefined（成功） */
+async function putFileStream(
+  filePath: string,
+  uploadUrl: string,
+  contentType: string,
+  fileSize: number,
+): Promise<UploadResult | undefined> {
+  const fileStream = fs.createReadStream(filePath);
   let putResponse: Response;
   try {
     putResponse = await fetch(uploadUrl, {
       method: 'PUT',
-      headers: putHeaders,
+      headers: { 'Content-Type': contentType, 'Content-Length': String(fileSize) },
       body: fileStream as any,
       // @ts-ignore duplex required for streaming body in Node.js fetch
       duplex: 'half',
@@ -267,36 +203,168 @@ export async function handleUpload(
     fileStream.destroy();
     throw e;
   }
-
   if (!putResponse.ok) {
     fileStream.destroy();
     const errText = await putResponse.text().catch(() => '');
-    return {
-      status: putResponse.status,
-      data: { error: `文件上传失败: ${putResponse.statusText}`, detail: errText },
-    };
+    return { status: putResponse.status, data: { error: `文件上传失败: ${putResponse.statusText}`, detail: errText } };
   }
+  return undefined;
+}
 
-  // 4. 返回最终结果
-  if (isIssueUpload) {
-    return {
-      status: 200,
-      data: {
-        asset_link: issueAssetLink,
-        asset_group_id: issueAssetGroupId,
-        name: fileName,
-        size: fileSize,
-      },
-    };
+/** asset-group 接口请求体 */
+interface PostAssetGroupForm {
+  image_assets?: Array<{ name: string; size: number; content_type: string }>;
+  file_assets?: Array<{ name: string; size: number; content_type: string }>;
+}
+
+/** asset-group 接口响应 */
+interface AssetGroupResponseData {
+  asset_group_id?: string;
+  image_upload_urls?: IssueAssetUploadURLResponseData[];
+  file_upload_urls?: IssueAssetUploadURLResponseData[];
+}
+
+/** 创建 asset-group 的 API 函数签名 */
+type PostAssetGroupFunction = (
+  repo: string,
+  body: PostAssetGroupForm,
+) => Promise<{ status?: number; data?: AssetGroupResponseData }>;
+
+/**
+ * 处理创建 Issue 时的图片/文件上传（asset-group 两步流程）
+ *
+ * 流程：
+ *   1. POST /{repo}/-/issues/asset-groups 携带 { image_assets: [{name, size, content_type}] }
+ *      或 { file_assets: [...] } → 服务端返回 asset_group_id + upload_url + asset_link
+ *   2. PUT 文件流到 upload_url
+ *   3. 返回 asset_link 给调用方拼到创建 issue 的 body 中
+ *
+ * @param shortcut       解析后的快捷命令；shortcut.kind 决定走 image 还是 file 通道
+ * @param filePath       本地文件路径
+ * @param postAssetGroup POST asset-groups 的 API 函数
+ * @param pathParams     API 调用的 path 参数（取 repo）
+ */
+export async function handleIssueCreateUpload(
+  shortcut: ResolvedShortcut,
+  filePath: string | undefined,
+  postAssetGroup: PostAssetGroupFunction,
+  pathParams: UploadPathParams,
+): Promise<UploadResult> {
+  const validated = validateFile(filePath);
+  if (!validated.ok) return validated.result;
+  const { filePath: validPath, fileName, fileSize, contentType } = validated.info;
+
+  const kind: 'image' | 'file' = shortcut.kind === 'image' ? 'image' : 'file';
+  const assetEntry = { name: fileName, size: fileSize, content_type: contentType };
+
+  // 1. 创建 asset-group，同时获取上传 URL
+  const groupBody: PostAssetGroupForm = kind === 'image'
+    ? { image_assets: [assetEntry] }
+    : { file_assets: [assetEntry] };
+
+  const groupResponse = await postAssetGroup(pathParams.repo, groupBody);
+  const groupData = groupResponse?.data as AssetGroupResponseData | undefined;
+
+  const uploadEntries = kind === 'image'
+    ? groupData?.image_upload_urls
+    : groupData?.file_upload_urls;
+
+  const firstEntry = uploadEntries?.[0];
+  const uploadUrl = firstEntry?.upload_url;
+
+  if (!uploadUrl) {
+    return groupResponse as unknown as UploadResult;
   }
 
+  // 2. PUT 文件流到 upload_url
+  const putErr = await putFileStream(validPath, uploadUrl, contentType, fileSize);
+  if (putErr) return putErr;
+
+  // 3. 返回结果（asset_link 拼入创建 issue 的 body，asset_group_id 备用）
   return {
     status: 200,
     data: {
-      name: pullResponseData?.assets?.name || fileName,
-      path: pullResponseData?.assets?.path,
+      asset_link: firstEntry?.asset_link,
+      name: firstEntry?.name || fileName,
+      path: firstEntry?.path,
       size: fileSize,
-      token: pullResponseData?.token,
+      asset_group_id: groupData?.asset_group_id,
     },
   };
 }
+
+/**
+ * 处理完整上传流程
+ *
+ * Issue 评论路径（走 comment-asset-upload-url 接口，按 file/image 分别调用）：
+ *   1. POST /{repo}/-/issues/{number}/comment-file-asset-upload-url
+ *      或 /{repo}/-/issues/{number}/comment-image-asset-upload-url
+ *      携带 { name, size, content_type } → 服务端返回 upload_url + asset_link
+ *   2. PUT 文件流到 upload_url
+ *   3. 返回 asset_link 给调用方拼到评论 body 里
+ *
+ * Pull 路径（保留原有的 upload-files / upload-imgs 一步上传）：
+ *   1. POST /{repo}/upload-files（或 imgs） 拿 upload_url
+ *   2. PUT 文件流到 upload_url
+ *
+ * @param shortcut    解析后的快捷命令；shortcut.kind 决定 issue 上传走 file 还是 image 通道
+ * @param filePath    本地文件路径
+ * @param toolFunction 原始上传 API 函数
+ * @param pathParams  API 调用的 path 参数（issue 需要 repo+number；pull 只需 repo）
+ */
+export async function handleUpload(
+  shortcut: ResolvedShortcut,
+  filePath: string | undefined,
+  toolFunction: UploadApiFunction,
+  pathParams: UploadPathParams,
+): Promise<UploadResult> {
+  // 1. 校验文件
+  const validated = validateFile(filePath);
+  if (!validated.ok) return validated.result;
+  const { filePath: validPath, fileName, fileSize, contentType } = validated.info;
+
+  // 2. 调用上传 API 获取 upload_url，并预先组装好成功时要返回的 data
+  let uploadUrl: string | undefined;
+  let successData: IssueUploadData | PullUploadData;
+
+  if (shortcut.module === 'issues') {
+    // Issue 评论：调 post-issue-comment-{file|image}-asset-upload-url
+    // 函数签名：({ repo, number }, { name, size, content_type })
+    if (!pathParams.number) {
+      return { status: 400, data: { error: '缺少 issue number（请确认 CNB_ISSUE_IID 是否已设置）' } };
+    }
+    const apiResponse = await toolFunction(
+      { repo: pathParams.repo, number: pathParams.number },
+      { name: fileName, size: fileSize, content_type: contentType },
+    );
+    const data = apiResponse?.data as IssueAssetUploadURLResponseData | undefined;
+    uploadUrl = data?.upload_url;
+    if (!uploadUrl) return apiResponse as unknown as UploadResult;
+    successData = {
+      asset_link: data?.asset_link,
+      name: data?.name || fileName,
+      path: data?.path,
+      size: fileSize,
+    };
+  } else {
+    // Pull：沿用 upload-files / upload-imgs 一步走接口
+    // 函数签名：(repo: string, { name, size })
+    const apiResponse = await toolFunction(pathParams.repo, { name: fileName, size: fileSize });
+    const data = apiResponse?.data as PullUploadResponseData | undefined;
+    uploadUrl = data?.upload_url;
+    if (!uploadUrl) return apiResponse as unknown as UploadResult;
+    successData = {
+      name: data?.assets?.name || fileName,
+      path: data?.assets?.path,
+      size: fileSize,
+      token: data?.token,
+    };
+  }
+
+  // 3. PUT 文件流到 upload_url
+  const putErr = await putFileStream(validPath, uploadUrl, contentType, fileSize);
+  if (putErr) return putErr;
+
+  // 4. 返回最终结果
+  return { status: 200, data: successData };
+}

package/package.json

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