@cnbcool/cnb-api-generate 2.13.0 → 2.14.0

package/client/lib/execute-action.ts

@@ -6,6 +6,7 @@ import { analyzeBuildTiming } from './build-timing';
 import { formatParams } from './format-params';
 import { formatOutput } from './format-output';
 import { buildToolParams } from './build-tool-params';
+import { skillsList } from './skills-list';
 // @ts-ignore
 import {getLoader} from '../../loader';
 /**
@@ -113,6 +114,17 @@ export async function executeAction(
     return;
   }
 
+  if (shortcut?.tool === '__skills-list__') {
+    const result = skillsList({
+      global: !!opts.global,
+      project: !!opts.project,
+      agent: (opts.agent as string) || undefined,
+      json: !!opts.json,
+    });
+    console.log(result);
+    return;
+  }
+
   const formattedParams = formatParams(params);
 
   const toolFunction = loadToolFunction(formattedParams.module, formattedParams.tool);

package/client/lib/register-modules.ts

@@ -3,7 +3,7 @@ import { trimSummary } from './trim-summary';
 import { helpData } from './help-data';
 import { flatOptionsData } from './flat-options-data';
 import { executeAction } from './execute-action';
-import { ISSUE_SHORTCUTS, PR_SHORTCUTS, type ShortcutDefinition } from '../shortcuts';
+import { ISSUE_SHORTCUTS, PR_SHORTCUTS, SKILLS_SHORTCUTS, type ShortcutDefinition } from '../shortcuts';
 
 interface FlatOption {
   optKey: string;
@@ -94,6 +94,7 @@ function registerToolOptions(toolCmd: Command, moduleName: string, toolName: str
 function getShortcutsForModule(moduleName: string): ShortcutDefinition[] {
   if (moduleName === 'issues') return ISSUE_SHORTCUTS;
   if (moduleName === 'pulls') return PR_SHORTCUTS;
+  if (moduleName === 'skills') return SKILLS_SHORTCUTS;
   return [];
 }
 
@@ -186,4 +187,45 @@ export function registerModuleCommands(program: Command): void {
         sub.help();
       });
   }
+
+  // ============================================================
+  // skills 模块：非 swagger 生成的独立 custom 模块，单独注册
+  // ============================================================
+  // 命令：cnb skills list [--json] [-g|--global] [-p|--project] [-a|--agent <agent>]
+  // 对应 quick-commands.json 中 realTool 为 __skills-list__ 的 custom 命令。
+  const skillShortcuts = SKILLS_SHORTCUTS;
+  if (skillShortcuts.length) {
+    const skillsSub = program
+      .command('skills')
+      .description(`skills 模块 (${skillShortcuts.length} tools)`)
+      .helpOption('-h, --help', '显示帮助文档')
+      .allowUnknownOption()
+      .allowExcessArguments();
+
+    for (const shortcut of skillShortcuts) {
+      const skillCmd = skillsSub
+        .command(shortcut.shortName)
+        .description(`[快捷] ${shortcut.description}`)
+        .option('-v, --verbose', '输出完整原始响应')
+        .helpOption('-h, --help', '显示帮助文档')
+        .showHelpAfterError(true)
+        .action(async (opts: Record<string, any>) => {
+          await executeAction('skills', shortcut.shortName, opts, skillsSub);
+        });
+
+      if (shortcut.realTool === '__skills-list__') {
+        skillCmd
+          .option('--json', '输出 JSON 格式')
+          .option('-g, --global', '仅列出全局 scope 的 skills')
+          .option('-p, --project', '仅列出项目 scope 的 skills')
+          .option('-a, --agent <agent>', '按 agent 过滤');
+      }
+    }
+
+    skillsSub
+      .argument('[tool]', '工具名称（支持快捷命令）')
+      .action(async (toolArg: string | undefined, _opts: Record<string, any>) => {
+        skillsSub.help();
+      });
+  }
 }

package/client/lib/skills-list.ts

@@ -0,0 +1,178 @@
+/**
+ * `cnb skills list` 自定义命令实现（方案 A）
+ *
+ * 背景：`skills list --json` 命令输出的 JSON 可能缺少 `description` 字段，
+ * 下游（如 NPC）无法直接把 skill 目录喂给 LLM。此前依赖在 default-npc
+ * 的 Dockerfile 中打补丁（`patches/skills-list-json-add-description.patch`）
+ * 给 `skills list --json` 补上 description，但该补丁强耦合 `skills` npm 包
+ * 的 `dist/cli.mjs` 内部结构，属于易碎件。
+ *
+ * 本命令不依赖补丁：内部调用原始 `skills list [scope] --json` 拿到 JSON，
+ * 对缺失 `description` 的条目，从各 `path` 指向的 SKILL.md frontmatter 解析
+ * description 回填，再输出——保证每个条目都包含 description，下游可无缝切换。
+ */
+
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+
+/** `skills list --json` 输出的单个条目结构（与 skills npm 包对齐） */
+export interface SkillEntry {
+  name: string;
+  /** 可能缺失，需回填 */
+  description?: string;
+  path: string;
+  scope: string;
+  agents?: string[];
+  source?: string | null;
+  sourceUrl?: string | null;
+  sourceType?: string | null;
+}
+
+/**
+ * 提取 SKILL.md 开头的 frontmatter 块（不含首尾 "---" 定界符）。
+ * 未找到（非 frontmatter 开头）时返回 null。
+ */
+function extractFrontmatter(content: string): string | null {
+  // 仅匹配开头为 "---" 的 frontmatter 块
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return match ? match[1] : null;
+}
+
+/**
+ * 从 SKILL.md frontmatter 中解析 description 字段。
+ *
+ * frontmatter 形如：
+ *   ---
+ *   name: cnb-api
+ *   description: CNB 平台交互命令...
+ *   ---
+ *
+ * 使用正规 YAML 解析，因此支持多行写法（块标量 / 折行 / 续行）：
+ *   description: |
+ *     CNB 平台交互命令...
+ *     支持代码仓库、Issue、PR、CI 读写
+ *
+ * 解析失败（文件不存在 / 无 frontmatter / 无 description / 非法 YAML）返回空串。
+ */
+export function parseDescriptionFromSkillMd(skillPath: string): string {
+  const mdPath = path.join(skillPath, 'SKILL.md');
+  let content: string;
+  try {
+    content = fs.readFileSync(mdPath, 'utf8');
+  } catch {
+    return '';
+  }
+
+  const fm = extractFrontmatter(content);
+  if (fm === null) return '';
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fm);
+  } catch {
+    return '';
+  }
+
+  // YAML 解析结果若不是对象或没有 description 字段，返回空串
+  const desc =
+    parsed && typeof parsed === 'object'
+      ? (parsed as Record<string, unknown>).description
+      : undefined;
+  if (typeof desc !== 'string') return '';
+
+  return desc.trim();
+}
+
+export interface SkillsListOptions {
+  /** 仅列出全局 scope（对应 skills list -g） */
+  global?: boolean;
+  /** 仅列出项目 scope（对应 skills list -p） */
+  project?: boolean;
+  /** 按 agent 过滤：仅保留 agents 中包含指定 agent 的条目 */
+  agent?: string;
+}
+
+/**
+ * 运行原始 `skills list [scope] --json` 并返回解析后的 JSON 数组。
+ *
+ * scope 参数规则与 `skills list` 一致：
+ * - 指定 `-g` → `-g`
+ * - 指定 `-p` → `-p`
+ * - 都不指定 → 不传 scope（由 skills 默认：项目优先，否则全局）
+ */
+export function runSkillsListJson(opts: SkillsListOptions): SkillEntry[] {
+  const args = ['list'];
+  if (opts.global) args.push('-g');
+  if (opts.project) args.push('-p');
+  args.push('--json');
+
+  let stdout: string;
+  try {
+    stdout = execFileSync('skills', args, {
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e: any) {
+    const stderr = e?.stderr?.toString?.() || '';
+    throw new Error(
+      `执行 skills list 失败：${e?.message || String(e)}${stderr ? `\n${stderr}` : ''}`,
+    );
+  }
+
+  try {
+    const parsed = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch (e: any) {
+    throw new Error(`解析 skills list --json 输出失败：${e?.message || String(e)}`);
+  }
+}
+
+/**
+ * 对 `skills list --json` 输出做后处理：
+ * 1. 从 SKILL.md frontmatter 回填缺失的 description；
+ * 2. 按 agent 过滤（若指定 -a）。
+ *
+ * 返回的是全新数组/对象，不修改原始输入。
+ */
+export function decorateSkillEntries(
+  entries: SkillEntry[],
+  opts: SkillsListOptions,
+): SkillEntry[] {
+  const result: SkillEntry[] = [];
+
+  for (const entry of entries) {
+    // agent 过滤：保留 agents 中包含指定 agent 的条目
+    if (opts.agent) {
+      const agents = Array.isArray(entry.agents) ? entry.agents : [];
+      if (!agents.includes(opts.agent)) continue;
+    }
+
+    const decorated: SkillEntry = { ...entry };
+
+    // 回填 description：缺失或为空时从 path 下的 SKILL.md frontmatter 解析
+    if (!decorated.description || !decorated.description.trim()) {
+      decorated.description = parseDescriptionFromSkillMd(entry.path) || undefined;
+    }
+
+    result.push(decorated);
+  }
+
+  return result;
+}
+
+/**
+ * `cnb skills list` 主入口。
+ *
+ * 参数对齐 `skills list --json`：`-g/-p/-a/--json`。
+ * 无论原始 `skills list` 是否被打补丁，输出都保证每条含 description。
+ */
+export function skillsList(opts: SkillsListOptions & { json?: boolean }): string {
+  const raw = runSkillsListJson(opts);
+  const decorated = decorateSkillEntries(raw, opts);
+
+  // 与 `skills list --json` 保持一致的 JSON 输出（默认即 JSON，字段结构不变）
+  return JSON.stringify(decorated, null, 2);
+}

package/client/shortcuts.ts

@@ -107,6 +107,9 @@ export const ISSUE_SHORTCUTS: ShortcutDefinition[] =
 
 export const PR_SHORTCUTS: ShortcutDefinition[] = SHORTCUTS_CONFIG.pulls || [];
 
+export const SKILLS_SHORTCUTS: ShortcutDefinition[] =
+  SHORTCUTS_CONFIG.skills || [];
+
 // ============================================================
 // --short 帮助输出
 // ============================================================
@@ -220,6 +223,8 @@ ${prList}
 // ============================================================
 
 function buildAutoPath(moduleName: string, repoOnly: boolean): Record<string, string> {
+  // skills 模块不依赖 repo/number，无自动注入的 path 参数
+  if (moduleName === 'skills') return {};
   const repo = process.env.CNB_REPO_SLUG || '';
   if (repoOnly) return { repo };
   const number = moduleName === 'issues'
@@ -243,7 +248,9 @@ export function resolveShortcut(
     ? ISSUE_SHORTCUTS
     : moduleName === 'pulls'
       ? PR_SHORTCUTS
-      : null;
+      : moduleName === 'skills'
+        ? SKILLS_SHORTCUTS
+        : null;
   if (!shortcuts) return null;
 
   const matched = shortcuts.find((s) => s.shortName === toolName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
@@ -49,7 +49,8 @@
     "prettier": "3.4.2",
     "rimraf": "6.0.1",
     "slashes": "^3.0.12",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@reduxjs/toolkit": "^1.9.5",

package/quick-commands.json

@@ -33,5 +33,8 @@
     { "shortName": "get-ci-timing",  "realTool": "__get-ci-timing__",         "description": "分析 CI 耗时瓶颈", "repoOnly": true, "custom": true, "dataTip": "--sn 构建号（可选）" },
     { "shortName": "get-imgs",       "realTool": "get-pr-imgs",               "description": "获取 PR 图片",     "repoOnly": true, "dataTip": "--img-path 图片路径" },
     { "shortName": "get-files",      "realTool": "get-pr-files",              "description": "获取 PR 附件",     "repoOnly": true, "dataTip": "--file-path 附件路径" }
+  ],
+  "skills": [
+    { "shortName": "list", "realTool": "__skills-list__", "description": "列出本地 skills", "custom": true, "dataTip": "--json -g -p -a agent" }
   ]
 }

package/skills-template/SKILL.md

@@ -5,19 +5,40 @@ description: CNB 平台交互命令，支持代码仓库、Issue、PR、CI、制
 
 # cnb-api
 
-操作 CNB 平台资源的 CLI 工具。
-
 ## 快捷命令
 
 <$QUICK_COMMANDS$>
 
 注意事项：
 
-- **参数自动识别**：快捷命令中的 Issue/PR 编号自动从环境变量识别，无需额外传递。
-- **默认仅需摘要**：默认精简响应输出，加 `--verbose` 输出完整数据。
-- **多行文本传参**：bash 参数为多行文本时用单引号，可降低命令注入风险。
-- **快捷命令适用范围**：快捷命令只能操作当前仓库的当前 Issue/PR，跨仓库或跨编号操作请参考 `更多 API`。
-- **关于提及和召唤**：评论中直接 @npc 会召唤 npc 干活；只提及不召唤时，用反引号包裹 `@npc`。
+- **参数自动识别**：Issue/PR 编号自动从环境变量识别，无需额外传递。
+- **默认仅需摘要**：默认精简输出，加 `--verbose` 输出完整数据。
+- **多行文本传参**：bash 参数为多行文本时用单引号，降低命令注入风险。
+- **适用范围**：快捷命令仅限当前仓库的当前 Issue/PR，跨仓库或跨编号请参考 `更多 API`。
+- **提及与召唤**：评论中直接 @npc 会召唤 npc；仅提及不召唤时，用反引号包裹 `@npc`。
+
+## PR 相关规范
+
+> 本节 PR 规范为默认约定，若项目另有规定，以项目规定为准。
+
+### 标题
+
+- **一行表达**：采用语义化提交格式。
+- **只保留核心问题**：标题要简洁、可读、语义清晰。
+- **可读性**：影响可读性的信息禁止写入标题。
+- **禁止括号**：标题禁止出现括号，补充说明写描述区。
+
+### 描述
+
+- **关联引用**：需包含 `Ref: #<ISSUE_ID>`。
+- **关联信息**：关联信息和补充说明应该写进描述区，比如 `Ref #xxx`、`cherry-pick #xxx`、版本号、日期、作者等。
+- **cherry-pick**：目标版本写入 body 末尾。
+
+### 提交流程
+
+- **提交后立即结束**：创建/推送 PR 后马上结束，不做其他操作。
+- **禁止轮询 CI 与评审**：不等待 CI 与评审状态；失败会自动唤起 NPC。
+- **禁止合并/关闭**：AI 不执行合并/关闭操作，合并交由人工完成。
 
 ## 常用链接