@cnbcool/cnb-api-generate 1.2.4 → 1.2.6

package/client/index.ts

@@ -5,6 +5,7 @@ import path from 'path';
 import { showModuleHelp } from './modules.help';
 import { showToolHelp } from './tools.help';
 import { showShort, resolveShortcut, summarizeResponse } from './shortcuts';
+import { handleUpload } from './utils/upload';
 
 const helpFileContent = fs.readFileSync(
   path.join(__dirname, 'help.json'),
@@ -401,31 +402,13 @@ async function main() {
     params.tool as string | undefined,
   );
   if (shortcut) {
+    params.module = shortcut.module;
     params.tool = shortcut.tool;
 
-    // 自动注入 path 参数（兼容新旧格式）
-    // 新格式：用户可能直接传了 --repo xxx，检查扁平参数是否已存在
-    const autoPathKeys = Object.keys(shortcut.autoPath);
-    const hasPathAlready = params.path || autoPathKeys.some(k => params[k]);
-
-    if (!hasPathAlready) {
-      if (autoPathKeys.length > 0) {
-        // 新格式：直接注入为扁平参数
-        for (const [key, value] of Object.entries(shortcut.autoPath)) {
-          if (!params[key]) {
-            params[key] = value;
-          }
-        }
-      } else {
-        const envHint =
-          params.module === 'issues'
-            ? 'CNB_REPO_SLUG 和 CNB_ISSUE_IID'
-            : 'CNB_REPO_SLUG 和 CNB_PULL_REQUEST_IID';
-        console.error(
-          `快捷命令需要环境变量 ${envHint}，或手动传参数。\n` +
-            `提示：运行 ${process.env.CNB_CLI_CMD || 'cnb'} --short 查看快捷命令详情。`,
-        );
-        process.exit(1);
+    // 自动注入 path 参数
+    for (const [key, value] of Object.entries(shortcut.autoPath)) {
+      if (!params[key]) {
+        params[key] = value;
       }
     }
 
@@ -512,11 +495,16 @@ async function main() {
     toolsParam.push(pathAndQueryParams);
   }
 
-  if (formattedParams.data) {
-    toolsParam.push(formattedParams.data);
+  // 上传快捷命令：走完整上传流程（获取 URL → PUT 文件 → 返回结果）
+  let data: any;
+  if (shortcut?.upload) {
+    data = await handleUpload(shortcut, formattedParams.data?.file, toolFunction, pathAndQueryParams as { repo: string; number?: string });
+  } else {
+    if (formattedParams.data) {
+      toolsParam.push(formattedParams.data);
+    }
+    data = await toolFunction(...toolsParam);
   }
-
-  const data = await toolFunction(...toolsParam);
   const toolKey = `${formattedParams.module}/${formattedParams.tool}`;
   // 快捷命令默认输出摘要，--verbose 时输出全部信息
   const isVerbose = !!formattedParams.verbose;

package/client/modules.help.ts

@@ -24,11 +24,16 @@ export function showModuleHelp(helpData: any, moduleName: string): void {
 
   const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
 
+  const entries = Object.values(moduleHelpData).map((info: any) => ({
+    name: info.filename as string,
+    summary: trimSummary(info.summary || ''),
+  }));
+  const maxNameLen = Math.max(...entries.map((e) => e.name.length));
+  const pad = maxNameLen + 2;
+
   let toolListMsg = '';
-  for (const [, info] of Object.entries(moduleHelpData)) {
-    const name = (info as any).filename;
-    const summary = (info as any).summary;
-    toolListMsg += `  ${name.padEnd(30)} ${summary}\n`;
+  for (const { name, summary } of entries) {
+    toolListMsg += `  ${name.padEnd(pad)} ${summary}\n`;
   }
 
   const helpMsg = `

package/client/shortcuts.ts

@@ -16,21 +16,29 @@ export interface ShortcutDefinition {
   shortName: string;
   /** 实际对应的 tool 文件名 */
   realTool: string;
+  /** 为 true 时只注入 repo，不注入 number */
+  repoOnly?: boolean;
+  /** 为 true 时表示是上传命令，走完整上传流程 */
+  upload?: boolean;
   /** 显示用的中文说明 */
   description: string;
-  /** 是否需要用户传 --data，如果不为 null 则自动注入 */
+  /** 自动注入的 data 参数（如 close/open 的状态值） */
   autoData?: Record<string, any>;
   /** --data 的使用提示（展示用） */
   dataTip?: string;
 }
 
 export interface ResolvedShortcut {
+  /** 所属模块名 */
+  module: string;
   /** 解析后的实际 tool 名 */
   tool: string;
   /** 自动注入的 path 参数 */
   autoPath: Record<string, string>;
   /** 自动注入的 data 参数（如 close/open） */
   autoData: Record<string, any> | null;
+  /** 是否为上传命令 */
+  upload: boolean;
 }
 
 // ============================================================
@@ -69,6 +77,8 @@ const ISSUE_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'add-labels',     realTool: 'post-issue-labels',    description: '添加标签',        dataTip: "--data '{\"labels\":[\"bug\",\"feature\"]}'" },
   { shortName: 'list-assignees', realTool: 'list-issue-assignees', description: '查看处理人' },
   { shortName: 'add-assignees',  realTool: 'post-issue-assignees', description: '添加处理人',      dataTip: "--data '{\"assignees\":[\"username\"]}'" },
+  { shortName: 'upload-file',    realTool: 'post-issue-file-asset-upload-url',  description: '上传文件', upload: true, dataTip: "--data '{\"file\":\"文件路径\"}'" },
+  { shortName: 'upload-image',   realTool: 'post-issue-image-asset-upload-url', description: '上传图片', upload: true, dataTip: "--data '{\"file\":\"图片路径\"}'" },
 ];
 
 const PR_SHORTCUTS: ShortcutDefinition[] = [
@@ -82,22 +92,60 @@ const PR_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'check-status',   realTool: 'list-pull-commit-statuses', description: '查看 CI 状态' },
   { shortName: 'list-reviews',   realTool: 'list-pull-reviews',       description: '查看评审列表' },
   { shortName: 'list-assignees', realTool: 'list-pull-assignees',     description: '查看处理人' },
+  { shortName: 'upload-file',    realTool: 'upload-files',  description: '上传文件', repoOnly: true, upload: true, dataTip: "--data '{\"file\":\"文件路径\"}'" },
+  { shortName: 'upload-image',   realTool: 'upload-imgs',  description: '上传图片', repoOnly: true, upload: true, dataTip: "--data '{\"file\":\"图片路径\"}'" },
 ];
 
 // ============================================================
 // --short 帮助输出
 // ============================================================
 
+/** 计算字符串的显示宽度（中文/全角占2，英文/半角占1） */
+function displayWidth(str: string): number {
+  let width = 0;
+  for (const ch of str) {
+    const code = ch.codePointAt(0) || 0;
+    // CJK、全角字符占2宽度
+    width += (code >= 0x1100 && (
+      code <= 0x115f || code === 0x2329 || code === 0x232a ||
+      (code >= 0x2e80 && code <= 0x3247) ||
+      (code >= 0x3250 && code <= 0x4dbf) ||
+      (code >= 0x4e00 && code <= 0xa4c6) ||
+      (code >= 0xa960 && code <= 0xa97c) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe10 && code <= 0xfe19) ||
+      (code >= 0xfe30 && code <= 0xfe6b) ||
+      (code >= 0xff01 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) ||
+      (code >= 0x1f000 && code <= 0x1fbff) ||
+      (code >= 0x20000 && code <= 0x2fffd) ||
+      (code >= 0x30000 && code <= 0x3fffd)
+    )) ? 2 : 1;
+  }
+  return width;
+}
+
+/** 用全角空格将字符串补齐到指定显示宽度 */
+function padToWidth(str: string, targetWidth: number): string {
+  const diff = targetWidth - displayWidth(str);
+  if (diff <= 0) return str;
+  // 每个全角空格占2宽度
+  const fullSpaces = Math.floor(diff / 2);
+  const halfSpace = diff % 2 === 1 ? ' ' : '';
+  return str + '　'.repeat(fullSpaces) + halfSpace;
+}
+
 function formatShortcutList(
   shortcuts: ShortcutDefinition[],
   cliCmd: string,
   moduleName: string,
 ): string {
-  const maxDescLen = Math.max(...shortcuts.map((s) => s.description.length));
+  const maxWidth = Math.max(...shortcuts.map((s) => displayWidth(s.description)));
 
   return shortcuts
     .map((s) => {
-      const desc = s.description.padEnd(maxDescLen + 2, '　'); // 全角空格对齐
+      const desc = padToWidth(s.description, maxWidth + 2);
       const cmd = `${cliCmd} ${moduleName} ${s.shortName}`;
       const dataPart = s.dataTip ? ` ${s.dataTip}` : '';
       return `  ${desc} ${cmd}${dataPart}`;
@@ -110,50 +158,46 @@ export function showShort(): void {
   const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
   const repo = getRepo();
 
-  if (ctx === 'issue') {
-    const number = getIssueNumber();
-    const list = formatShortcutList(ISSUE_SHORTCUTS, cliCmd, 'issues');
-    console.log(`
-📋 当前场景: Issue 事件 (Issue #${number})
-   仓库: ${repo}
+  if (ctx === 'issue' || ctx === 'pull_request') {
+    const isIssue = ctx === 'issue';
+    const number = isIssue ? getIssueNumber() : getPRNumber();
+    const emoji = isIssue ? '📋' : '🔀';
+    const label = isIssue ? 'Issue' : 'Pull Request';
+    const tag = isIssue ? 'Issue' : 'PR';
+    const moduleName = isIssue ? 'issues' : 'pulls';
+    const shortcuts = isIssue ? ISSUE_SHORTCUTS : PR_SHORTCUTS;
+    const envVars = isIssue
+      ? 'CNB_REPO_SLUG 和 CNB_ISSUE_IID'
+      : 'CNB_REPO_SLUG 和 CNB_PULL_REQUEST_IID';
+    const list = formatShortcutList(shortcuts, cliCmd, moduleName);
 
-常用快捷命令（path 参数已从环境变量自动获取）：
-${list}
-
-提示: 以上命令自动使用环境变量 CNB_REPO_SLUG 和 CNB_ISSUE_IID，无需手动传 --path
-      默认只输出摘要信息，添加 --verbose 可输出全部信息
-`);
-  } else if (ctx === 'pull_request') {
-    const number = getPRNumber();
-    const list = formatShortcutList(PR_SHORTCUTS, cliCmd, 'pulls');
     console.log(`
-🔀 当前场景: Pull Request 事件 (PR #${number})
+${emoji} 当前场景: ${label} 事件 (${tag} #${number})
    仓库: ${repo}
 
 常用快捷命令（path 参数已从环境变量自动获取）：
 ${list}
 
-提示: 以上命令自动使用环境变量 CNB_REPO_SLUG 和 CNB_PULL_REQUEST_IID，无需手动传 --path
+提示: ${tag} 相关命令会自动使用 ${envVars}
       默认只输出摘要信息，添加 --verbose 可输出全部信息
 `);
   } else {
-    // 未知上下文，两组都显示
     const issueList = formatShortcutList(ISSUE_SHORTCUTS, cliCmd, 'issues');
     const prList = formatShortcutList(PR_SHORTCUTS, cliCmd, 'pulls');
     console.log(`
 ⚠️  未检测到 Issue/PR 事件上下文
    (CNB_ISSUE_IID 和 CNB_PULL_REQUEST_IID 均未设置)
 
-📋 Issue 场景常用命令（需要设置 CNB_ISSUE_IID 环境变量）：
+📋 Issue 场景常用命令：
 ${issueList}
 
-🔀 PR 场景常用命令（需要设置 CNB_PULL_REQUEST_IID 环境变量）：
+🔀 PR 场景常用命令：
 ${prList}
 
-提示: 快捷命令需要以下环境变量:
+提示: 快捷命令可使用以下环境变量:
   CNB_REPO_SLUG          - 仓库路径
-  CNB_ISSUE_IID          - Issue 编号 (Issue 事件)
-  CNB_PULL_REQUEST_IID   - PR 编号 (PR 事件)
+  CNB_ISSUE_IID          - Issue 编号（Issue 相关快捷命令）
+  CNB_PULL_REQUEST_IID   - PR 编号（PR 相关快捷命令）
 
   默认只输出摘要信息，添加 --verbose 可输出全部信息
 `);
@@ -164,12 +208,18 @@ ${prList}
 // 快捷命令解析
 // ============================================================
 
+function buildAutoPath(moduleName: string, repoOnly: boolean): Record<string, string> {
+  const repo = process.env.CNB_REPO_SLUG || '';
+  if (repoOnly) return { repo };
+  const number = moduleName === 'issues'
+    ? (process.env.CNB_ISSUE_IID || '')
+    : (process.env.CNB_PULL_REQUEST_IID || '');
+  return { repo, number };
+}
+
 /**
  * 尝试将用户输入的 module + tool 解析为快捷命令
  *
- * 即使环境变量未设置，也会完成 shortName → realTool 的映射，
- * 只是 autoPath 为 null，调用方需要用户手动传 --path。
- *
  * @returns 解析结果，如果不是快捷命令则返回 null
  */
 export function resolveShortcut(
@@ -178,36 +228,22 @@ export function resolveShortcut(
 ): ResolvedShortcut | null {
   if (!moduleName || !toolName) return null;
 
-  // 根据 module 名确定对应的快捷命令表
-  let shortcuts: ShortcutDefinition[] | null = null;
-  let autoPath: Record<string, string> | null = null;
-
-  if (moduleName === 'issues') {
-    shortcuts = ISSUE_SHORTCUTS;
-    const repo = process.env.CNB_REPO_SLUG;
-    const number = process.env.CNB_ISSUE_IID;
-    if (repo && number) {
-      autoPath = { repo, number };
-    }
-  } else if (moduleName === 'pulls') {
-    shortcuts = PR_SHORTCUTS;
-    const repo = process.env.CNB_REPO_SLUG;
-    const number = process.env.CNB_PULL_REQUEST_IID;
-    if (repo && number) {
-      autoPath = { repo, number };
-    }
-  }
-
+  const shortcuts = moduleName === 'issues'
+    ? ISSUE_SHORTCUTS
+    : moduleName === 'pulls'
+      ? PR_SHORTCUTS
+      : null;
   if (!shortcuts) return null;
 
-  // 在快捷命令表中查找匹配的 shortName
   const matched = shortcuts.find((s) => s.shortName === toolName);
   if (!matched) return null;
 
   return {
+    module: moduleName,
     tool: matched.realTool,
-    autoPath: autoPath || {},
+    autoPath: buildAutoPath(moduleName, !!matched.repoOnly),
     autoData: matched.autoData || null,
+    upload: !!matched.upload,
   };
 }
 
@@ -225,47 +261,164 @@ type SummaryExtractor = (item: any) => any;
  * - 数组响应：对 data 中每个元素应用提取函数
  */
 const SUMMARY_EXTRACTORS: Record<string, SummaryExtractor> = {
-  // Issue 详情摘要：只保留标题和正文
+  // Issue 详情摘要：保留标题、状态、标签和正文
+  // 过滤: number, state_reason, assignees, author, created_at, updated_at 等
   'issues/get-issue': (item) => ({
     title: item.title,
+    state: item.state,
+    labels: item.labels?.map?.((l: any) => l.name).filter(Boolean) || [],
     body: item.body,
   }),
 
   // Issue 更新摘要：只保留状态变更结果
+  // 过滤: title, body, labels, assignees, author, created_at, updated_at 等
   'issues/update-issue': (item) => ({
     number: item.number,
     state: item.state,
     state_reason: item.state_reason,
   }),
 
-  // Issue 添加处理人摘要：只保留处理人列表
+  // Issue 评论列表摘要：只保留作者用户名、内容和创建时间
+  // 过滤: author 完整对象(avatar/email/freeze/is_npc/nickname), reactions, updated_at
+  'issues/list-issue-comments': (item) => ({
+    id: item.id,
+    author: item.author?.username,
+    body: item.body,
+    created_at: item.created_at,
+  }),
+
+  // Issue 发表评论摘要：只保留评论 ID 和创建时间（body 已在请求中传入，无需重复）
+  // 过滤: body(请求已传入), author 完整对象(avatar/email/freeze/is_npc/nickname/username), reactions, updated_at
+  'issues/post-issue-comment': (item) => ({
+    id: item.id,
+    created_at: item.created_at,
+  }),
+
+  // Issue 标签列表摘要：保留名称、颜色和描述
+  // 过滤: id
+  'issues/list-issue-labels': (item) => ({
+    name: item.name,
+    color: item.color,
+    description: item.description,
+  }),
+
+  // Issue 添加标签摘要：只保留 ID 和颜色（name 已在请求中传入，无需重复）
+  // 过滤: name(请求已传入), description
+  'issues/post-issue-labels': (item) => ({
+    id: item.id,
+    color: item.color,
+  }),
+
+  // Issue 处理人列表摘要：保留用户名和昵称
+  // 过滤: avatar, email, freeze, is_npc
+  'issues/list-issue-assignees': (item) => ({
+    username: item.username,
+    nickname: item.nickname,
+  }),
+
+  // Issue 添加处理人摘要：保留处理人用户名和昵称列表
+  // 过滤: assignees 中每个用户的 avatar/email/freeze/is_npc，以及 issue 其他字段
   'issues/post-issue-assignees': (item) => ({
     number: item.number,
-    assignees: item.assignees?.map?.((a: any) => a.username).filter(Boolean) || [],
+    assignees: item.assignees?.map?.((a: any) => ({ username: a.username, nickname: a.nickname })).filter((a: any) => a.username) || [],
   }),
 
-  // PR 详情摘要：只保留标题、状态、正文和分支信息
+  // PR 详情摘要：保留标题、状态、标签、正文和分支信息
+  // 过滤: number, author, assignees, reviewers, created_at, updated_at, base/head 完整对象等
   'pulls/get-pull': (item) => ({
     title: item.title,
     state: item.state,
+    labels: item.labels?.map?.((l: any) => l.name).filter(Boolean) || [],
     base: item.base?.ref,
     head: item.head?.ref,
     body: item.body,
   }),
 
-  // PR 文件列表摘要：只保留文件名、变更状态和增删行数
+  // PR 文件列表摘要：保留文件名、sha、变更状态和增删行数
+  // 过滤: patch, blob_url, raw_url, contents_url, previous_filename
   'pulls/list-pull-files': (item) => ({
     filename: item.filename,
+    sha: item.sha,
     status: item.status,
     additions: item.additions,
     deletions: item.deletions,
   }),
 
   // PR 提交列表摘要：只保留 sha 前 8 位和 commit message
+  // 过滤: sha 完整值, commit 完整对象(author/committer/tree/verification), parents, url 等
   'pulls/list-pull-commits': (item) => ({
     sha: typeof item.sha === 'string' ? item.sha.substring(0, 8) : item.sha,
     message: item.commit?.message,
   }),
+
+  // PR 评论列表摘要：保留作者用户名和昵称、内容和创建时间
+  // 过滤: author 完整对象(avatar/email/freeze/is_npc), reactions, updated_at
+  'pulls/list-pull-comments': (item) => ({
+    id: item.id,
+    author: item.author?.username,
+    nickname: item.author?.nickname,
+    body: item.body,
+    created_at: item.created_at,
+  }),
+
+  // PR 发表评论摘要：只保留评论 ID 和创建时间（body 已在请求中传入，无需重复）
+  // 过滤: body(请求已传入), author 完整对象(avatar/email/freeze/is_npc/nickname/username), reactions, updated_at
+  'pulls/post-pull-comment': (item) => ({
+    id: item.id,
+    created_at: item.created_at,
+  }),
+
+  // PR 标签列表摘要：保留 ID、名称、颜色和描述
+  // 过滤: 无
+  'pulls/list-pull-labels': (item) => ({
+    id: item.id,
+    name: item.name,
+    color: item.color,
+    description: item.description,
+  }),
+
+  // PR 添加标签摘要：只保留 ID 和颜色（name 已在请求中传入，无需重复）
+  // 过滤: name(请求已传入), description
+  'pulls/post-pull-labels': (item) => ({
+    id: item.id,
+    color: item.color,
+  }),
+
+  // PR CI 状态摘要：保留整体状态和各检查项的核心信息（sha 截断为前 8 位）
+  // 过滤: sha 完整值, statuses 中每项的 target_url/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,
+    statuses: item.statuses?.map?.((s: any) => ({
+      context: s.context,
+      state: s.state,
+      description: s.description,
+    })) || [],
+  }),
+
+  // PR 评审列表摘要：保留作者用户名和昵称、状态和内容
+  // 过滤: author 完整对象(avatar/email/freeze/is_npc), created_at, updated_at
+  'pulls/list-pull-reviews': (item) => ({
+    id: item.id,
+    author: item.author?.username,
+    nickname: item.author?.nickname,
+    state: item.state,
+    body: item.body,
+  }),
+
+  // PR 处理人列表摘要：保留用户名和昵称
+  // 过滤: avatar, email, freeze, is_npc
+  'pulls/list-pull-assignees': (item) => ({
+    username: item.username,
+    nickname: item.nickname,
+  }),
+
+  // PR 添加处理人摘要：保留处理人用户名和昵称列表
+  // 过滤: assignees 中每个用户的 avatar/email/freeze/is_npc，以及 PR 其他字段
+  'pulls/post-pull-assignees': (item) => ({
+    number: item.number,
+    assignees: item.assignees?.map?.((a: any) => ({ username: a.username, nickname: a.nickname })).filter((a: any) => a.username) || [],
+  }),
 };
 
 /**

package/client/utils/upload.ts

@@ -0,0 +1,189 @@
+/**
+ * 完整上传流程
+ * 1. 读取本地文件 → 获取 name/size
+ * 2. 调用上传 API → 获取 upload_url
+ * 3. PUT 文件内容到 upload_url（流式上传）
+ * 4. 返回最终结果
+ */
+
+import fs from 'fs';
+import nodePath from 'path';
+import { lookup as mimeLookup } from 'mime-types';
+import type { ResolvedShortcut } from '../shortcuts';
+
+// 上传文件大小上限：100MB
+const MAX_FILE_SIZE = 100 * 1024 * 1024;
+
+/** 上传 API 的 path 参数 */
+interface UploadPathParams {
+  repo: string;
+  number?: string;
+}
+
+/** Issue 上传请求体 */
+interface IssueUploadBody {
+  name: string;
+  size: number;
+  content_type: string;
+}
+
+/** Pull 上传请求体 */
+interface PullUploadBody {
+  name: string;
+  size: number;
+}
+
+/** 上传 API 函数签名 */
+type UploadApiFunction = (
+  params: UploadPathParams,
+  body: IssueUploadBody | PullUploadBody,
+) => Promise<UploadApiResponse>;
+
+/** 上传 API 响应 */
+interface UploadApiResponse {
+  status?: number;
+  data?: {
+    upload_url?: string;
+    asset_link?: string;
+    assets?: { name?: string; path?: string };
+    token?: string;
+  };
+}
+
+/** 上传失败时的 data */
+interface UploadErrorData {
+  error: string;
+  detail?: string;
+}
+
+/** Issue 上传成功时的 data */
+interface IssueUploadData {
+  asset_link?: string;
+  name: string;
+  size: number;
+}
+
+/** Pull 上传成功时的 data */
+interface PullUploadData {
+  name: string;
+  path?: string;
+  size: number;
+  token?: string;
+}
+
+/** handleUpload 的返回值 */
+interface UploadResult {
+  status: number;
+  data: UploadErrorData | IssueUploadData | PullUploadData;
+}
+
+/**
+ * 处理完整上传流程
+ * @param shortcut 解析后的快捷命令
+ * @param filePath 本地文件路径
+ * @param toolFunction 原始上传 API 函数（获取 upload_url）
+ * @param pathParams API 调用的 path 参数（repo 或 {repo, number}）
+ */
+export async function handleUpload(
+  shortcut: ResolvedShortcut,
+  filePath: string | undefined,
+  toolFunction: UploadApiFunction,
+  pathParams: UploadPathParams,
+): Promise<UploadResult> {
+  // 校验 file 参数
+  if (!filePath) {
+    return { status: 400, data: { error: `上传命令需要指定文件路径，如: --data '{"file":"./path/to/file"}'` } };
+  }
+
+  // 1. 读取本地文件信息
+  if (!fs.existsSync(filePath)) {
+    return { status: 400, data: { error: `文件不存在: ${filePath}` } };
+  }
+
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) {
+    return { status: 400, data: { error: `不是文件: ${filePath}` } };
+  }
+
+  const fileName = nodePath.basename(filePath);
+  const fileSize = stat.size;
+
+  if (fileSize === 0) {
+    return { 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 mimeResult = mimeLookup(filePath);
+  const contentType = typeof mimeResult === 'string' ? mimeResult : 'application/octet-stream';
+
+  // 2. 调用上传 API 获取 upload_url
+  const isIssueUpload = shortcut.module === 'issues';
+  const requestBody = isIssueUpload
+    ? { name: fileName, size: fileSize, content_type: contentType }
+    : { name: fileName, size: fileSize };
+
+  const uploadResponse = await toolFunction(pathParams, requestBody);
+
+  // 提取 upload_url
+  const responseData = uploadResponse?.data;
+  const uploadUrl = responseData?.upload_url;
+
+  if (!uploadUrl) {
+    return uploadResponse as unknown as UploadResult; // 获取 URL 失败，直接返回原始错误
+  }
+
+  // 3. PUT 文件内容到 upload_url（流式读取，避免大文件撑爆内存）
+  const fileStream = fs.createReadStream(filePath);
+
+  const putHeaders: Record<string, string> = {
+    'Content-Type': contentType,
+    'Content-Length': String(fileSize),
+  };
+
+  let putResponse: Response;
+  try {
+    putResponse = await fetch(uploadUrl, {
+      method: 'PUT',
+      headers: putHeaders,
+      body: fileStream as any,
+      // @ts-ignore duplex required for streaming body in Node.js fetch
+      duplex: 'half',
+    });
+  } catch (e) {
+    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 },
+    };
+  }
+
+  // 4. 返回最终结果
+  if (isIssueUpload) {
+    return {
+      status: 200,
+      data: {
+        asset_link: responseData.asset_link,
+        name: fileName,
+        size: fileSize,
+      },
+    };
+  }
+
+  return {
+    status: 200,
+    data: {
+      name: responseData.assets?.name || fileName,
+      path: responseData.assets?.path,
+      size: fileSize,
+      token: responseData.token,
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
@@ -40,6 +40,7 @@
     "debug": "4.4.1",
     "glob": "^13.0.1",
     "lodash": "^4.17.23",
+    "mime-types": "^2.1.35",
     "ora": "5.4.1",
     "prettier": "3.4.2",
     "rimraf": "6.0.1",

package/skills-template/SKILL.md

@@ -9,24 +9,25 @@ description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、
 
 ## 快捷命令（优先使用）
 
-快捷命令是对常用 issues/pulls 操作的简写形式，与普通 API 命令有三个区别：
-1. **路径参数自动注入**，无需额外传入
-2. **命令名更短** — 如 `issues get` 替代 `issues get-issue`，`pulls comment` 替代 `pulls post-pull-comment`
-3. **默认只输出摘要** — 自动精简响应，只返回核心字段（如标题、正文）；加 `--verbose` 输出完整数据
+可用快捷命令：
+- `issues`: `get`, `list-comments`, `comment`, `close`, `open`, `list-labels`, `add-labels`, `list-assignees`, `add-assignees`, `upload-file`, `upload-image`
+- `pulls`: `get`, `list-files`, `list-commits`, `list-comments`, `comment`, `list-labels`, `add-labels`, `check-status`, `list-reviews`, `list-assignees`, `upload-file`, `upload-image`
 
-可用的快捷命令：
-- issues: get, list-comments, comment, close, open, list-labels, add-labels, list-assignees, add-assignees
-- pulls: get, list-files, list-commits, list-comments, comment, list-labels, add-labels, check-status, list-reviews, list-assignees
+注意：
+- **路径参数自动注入**：仓库 slug、Issue/PR 编号优先从环境变量自动获取，无需额外传入
+- **默认只输出摘要**：会精简响应输出结果，只返回核心字段。加 `--verbose` 输出完整数据。
+- 快捷命令只能操作当前仓库的当前Issue或PR。跨仓库或跨编号操作请使用其他 API 命令。
 
-用法示例：
+用法: `<$CNB_CLI_CMD$> <module> <command>`
 - ✅ `<$CNB_CLI_CMD$> issues get`
-- ✅ `<$CNB_CLI_CMD$> pulls list-comments`
-- ✅ `<$CNB_CLI_CMD$> issues get --verbose` （需要完整数据时）
+- ✅ `<$CNB_CLI_CMD$> pulls comment --data '{"body":"内容"}'`
 
-需要 --data 的命令（其余快捷命令无需任何参数）：
-- comment: --data '{"body":"内容"}'
-- add-labels: --data '{"labels":["标签"]}
-- add-assignees（仅 Issue）: --data '{"assignees":["用户名"]}'
+需要 `--data` 的快捷命令: 
+- `comment`: `--data '{"body":"内容"}'`
+- `add-labels`: `--data '{"labels":["标签"]}'`
+- `add-assignees`: `--data '{"assignees":["用户名"]}'`
+- `upload-file`: `--data '{"file":"本地文件路径"}'`（自动完成上传全流程）
+- `upload-image`: `--data '{"file":"本地图片路径"}'`（自动完成上传全流程）
 
 ## 其他 API（快捷命令不满足时使用）
 
@@ -37,7 +38,6 @@ description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、
 
 ## 规则
 
-- 优先使用快捷命令，不满足时再通过 --help 逐步查找
-- 必须先 --help 获取参数，禁止猜测参数名
+- 优先使用快捷命令，不满足时再 `--help` 逐步查找
+- 使用非快捷命令时，必须先 `--help` 获取帮助，禁止猜测
 - 直接执行命令，不要询问用户确认
-- 向用户展示结果时：成功响应（status 200-299）只展示 data 部分；失败响应（status ≥300）需附带 status 和 trace