@zhouhao4221/devflow-skills 0.2.0 → 0.3.0

package/install.js

@@ -1,152 +1,442 @@
 #!/usr/bin/env node
 
-const { spawnSync, execSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const https = require('https');
 
 const VERSION = require('./package.json').version;
-const BINARY_NAME = process.platform === 'win32' ? 'devflow-skills.exe' : 'devflow-skills';
-
-function getPlatform() {
-  const platform = os.platform();
-  const arch = os.arch();
-
-  const archMap = { x64: 'amd64', arm64: 'arm64', ia32: '386' };
-  const mappedArch = archMap[arch] || arch;
-
-  let platformName;
-  switch (platform) {
-    case 'linux':
-      platformName = 'linux';
-      break;
-    case 'darwin':
-      platformName = 'darwin';
-      break;
-    case 'win32':
-      platformName = 'windows';
-      break;
-    default:
-      console.error('不支持的平台: ' + platform);
-      process.exit(1);
+
+// ── tool config ─────────────────────────────────────────────────────────
+
+const TOOLS = {
+  opencode:  { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.config/opencode/skills',    flat: true },
+  codex:     { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.config/codex/skills',       flat: true },
+  claude:    { projectSkillsDir: 'plugins',                globalSkillsDir: 'plugins',                    flat: false },
+  cursor:    { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.cursor/skills',             flat: true },
+  copilot:   { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.github/copilot/skills',     flat: true },
+  codebuddy: { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.config/codebuddy/skills',   flat: true },
+  windsurf:  { projectSkillsDir: '.agents/skills',         globalSkillsDir: '.config/windsurf/skills',    flat: true },
+};
+
+const PLUGIN_ORDER = ['req', 'api', 'pm', 'diag', 'uat'];
+
+// ── helpers ─────────────────────────────────────────────────────────────
+
+function usage() {
+  console.log(`devflow-skills v${VERSION} — AI 技能一键安装/管理工具
+
+用法:
+  devflow-skills install   --tool <TOOL> [--skill <NAME>...] [--all] [--plugin <NAME>] [--dir <PATH>] [--global] [--symlink]
+  devflow-skills list      [--plugin <NAME>] [--format text|json] [--filter <STR>]
+  devflow-skills uninstall --tool <TOOL> [--skill <NAME>...] [--all] [--dir <PATH>] [--global]
+  devflow-skills add       <owner/repo> [--tool <TOOL>] [--skill <NAME>...] [--all] [--list] [--dir <PATH>] [--global] [--symlink]
+
+命令:
+  install     安装技能到目标 AI 工具目录
+  list        列出所有可用技能
+  uninstall   从目标 AI 工具目录卸载技能
+  add         从 GitHub 仓库克隆并安装技能
+
+支持的 --tool 值: ${Object.keys(TOOLS).join(', ')}
+
+示例:
+  npx devflow-skills install --tool opencode --all
+  npx devflow-skills install --tool cursor --skill req-dev
+  npx devflow-skills install --tool opencode --all -g
+  npx devflow-skills install --tool cursor --all --symlink
+  npx devflow-skills list --plugin req
+  npx devflow-skills list --filter dev
+  npx devflow-skills uninstall --tool opencode --all
+  npx devflow-skills add zhouhao4221/devflow-skills --tool copilot --all
+  npx devflow-skills add zhouhao4221/devflow-skills --list
+`);
+}
+
+function fail(msg) {
+  console.error('错误:', msg);
+  process.exit(1);
+}
+
+function ensure(cond, msg) {
+  if (!cond) fail(msg);
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-g') {
+      flags.global = true;
+      continue;
+    }
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+
+    const eq = a.indexOf('=');
+    const key = eq > -1 ? a.slice(2, eq) : a.slice(2);
+    let val = true;
+    if (eq > -1) {
+      val = a.slice(eq + 1);
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+      val = argv[++i];
+    }
+
+    if (flags[key] === undefined) {
+      flags[key] = val;
+    } else if (Array.isArray(flags[key])) {
+      flags[key].push(val);
+    } else {
+      flags[key] = [flags[key], val];
+    }
   }
+  // normalize single-element arrays
+  if (flags.skill !== undefined && !Array.isArray(flags.skill)) flags.skill = [flags.skill];
+  return { positional, flags };
+}
 
-  return `${platformName}_${mappedArch}`;
+function requireTool(flags) {
+  ensure(flags.tool, '--tool 是必需参数');
+  const cfg = TOOLS[flags.tool];
+  ensure(cfg, `不支持的 --tool: ${flags.tool} (支持: ${Object.keys(TOOLS).join(', ')})`);
+  return cfg;
 }
 
-function getCacheDir() {
-  const dir = path.join(os.homedir(), '.devflow-skills', VERSION);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+function requireSelection(flags) {
+  const hasAll = !!flags.all;
+  const hasSkill = !!(flags.skill && flags.skill.length > 0);
+  const hasPlugin = !!flags.plugin;
+  ensure(hasAll || hasSkill || hasPlugin, '请指定 --skill、--plugin 或 --all');
+  ensure(!(hasAll && hasSkill), '--skill 与 --all 不能同时使用');
+}
+
+// ── frontmatter ─────────────────────────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') return { name: '', description: '' };
+  const end = lines.indexOf('---', 1);
+  if (end === -1) return { name: '', description: '' };
+
+  const fm = {};
+  let curKey = '';
+  for (const line of lines.slice(1, end)) {
+    const m = line.match(/^(\w[\w-]*):\s*(.*)/);
+    if (m) {
+      curKey = m[1];
+      const after = m[2].trim();
+      fm[curKey] = (after === '|' || after === '>' || after === '|-' || after === '>-') ? '' : after;
+    } else if (curKey) {
+      const trimmed = line.trimStart();
+      if (trimmed && line.length - trimmed.length >= 2) {
+        fm[curKey] = fm[curKey] ? fm[curKey] + ' ' + trimmed : trimmed;
+      }
+    }
   }
-  return dir;
+  return { name: fm.name || '', description: (fm.description || '').replace(/\n/g, ' ').trim() };
 }
 
-function downloadBinary(url, dest) {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(dest, { mode: 0o755 });
-    https
-      .get(url, (response) => {
-        if (response.statusCode === 302 || response.statusCode === 301) {
-          https.get(response.headers.location, (redirectRes) => {
-            redirectRes.pipe(file);
-            file.on('finish', () => {
-              file.close();
-              resolve();
-            });
-          }).on('error', reject);
-          return;
-        }
-        if (response.statusCode !== 200) {
-          reject(new Error(`下载失败 (HTTP ${response.statusCode}): ${url}`));
-          return;
-        }
-        response.pipe(file);
-        file.on('finish', () => {
-          file.close();
-          resolve();
-        });
-      })
-      .on('error', reject);
-  });
+function updateFrontmatterName(content, newName) {
+  return content.replace(/^name:\s*.*/m, 'name: ' + newName);
 }
 
-function getPackageDir() {
-  return path.dirname(require.resolve('./package.json'));
+// ── skill loading ───────────────────────────────────────────────────────
+
+function loadSkills(baseDir) {
+  const skills = [];
+  const pluginsDir = path.join(baseDir, 'plugins');
+  if (!fs.existsSync(pluginsDir)) return skills;
+
+  for (const plugin of fs.readdirSync(pluginsDir)) {
+    const skillsDir = path.join(pluginsDir, plugin, 'skills');
+    if (!fs.existsSync(skillsDir)) continue;
+    for (const name of fs.readdirSync(skillsDir)) {
+      const file = path.join(skillsDir, name, 'SKILL.md');
+      if (!fs.existsSync(file)) continue;
+      const raw = fs.readFileSync(file, 'utf-8');
+      const fm = parseFrontmatter(raw);
+      skills.push({ plugin, name, description: fm.description, file, raw });
+    }
+  }
+  skills.sort((a, b) => a.plugin.localeCompare(b.plugin) || a.name.localeCompare(b.name));
+  return skills;
 }
 
-async function getBinary() {
-  const cacheDir = getCacheDir();
-  const binaryPath = path.join(cacheDir, BINARY_NAME);
+function resolveSkill(spec, allSkills) {
+  const parts = spec.split('-', 2);
+  if (parts.length === 2) {
+    const m = allSkills.find(s => s.plugin === parts[0] && s.name === parts[1]);
+    return m ? [m] : [];
+  }
+  return allSkills.filter(s => s.name === spec);
+}
 
-  if (fs.existsSync(binaryPath)) {
-    return binaryPath;
+function uniqueResolve(spec, allSkills) {
+  const matched = resolveSkill(spec, allSkills);
+  ensure(matched.length > 0, `未找到技能 '${spec}'，使用 'devflow-skills list' 查看所有可用技能`);
+  if (matched.length > 1) {
+    for (const s of matched) console.error(`  ${s.plugin}-${s.name}: ${s.description}`);
+    fail(`技能名 '${spec}' 匹配到多个技能，请使用完整的扁平名 (如 req-dev) 来区分`);
   }
+  return matched[0];
+}
 
-  const pkgDir = getPackageDir();
-  const localBinary = path.join(pkgDir, BINARY_NAME);
-  if (fs.existsSync(localBinary)) {
-    process.stderr.write('使用本地构建的二进制。\n');
-    return localBinary;
+function selectSkills(flags, allSkills) {
+  if (flags.all) return allSkills;
+  if (flags.plugin) {
+    const s = allSkills.filter(s => s.plugin === flags.plugin);
+    ensure(s.length > 0, `未找到插件 '${flags.plugin}' 的技能`);
+    return s;
   }
+  return flags.skill.map(s => uniqueResolve(s, allSkills));
+}
+
+// ── target paths ────────────────────────────────────────────────────────
+
+function targetBase(cfg, dir, global) {
+  return global ? path.join(os.homedir(), cfg.globalSkillsDir) : path.join(dir, cfg.projectSkillsDir);
+}
+
+function targetPath(cfg, dir, global, plugin, name) {
+  const base = targetBase(cfg, dir, global);
+  return cfg.flat ? path.join(base, plugin + '-' + name) : path.join(base, plugin, 'skills', name);
+}
+
+function canonicalBase(dir, global) {
+  return global ? path.join(os.homedir(), '.agents', 'skills') : path.join(dir, '.agents', 'skills');
+}
+
+function canonicalPath(dir, global, plugin, name) {
+  return path.join(canonicalBase(dir, global), plugin + '-' + name);
+}
+
+// ── install ─────────────────────────────────────────────────────────────
+
+function installOne(cfg, dir, global, symlink, { plugin, name, raw }) {
+  if (symlink) return installSymlink(cfg, dir, global, plugin, name, raw);
 
-  const platform = getPlatform();
-  const suffix = process.platform === 'win32' ? '.exe' : '';
-  const url = `https://github.com/zhouhao4221/devflow-skills/releases/download/v${VERSION}/devflow-skills_${platform}${suffix}`;
+  const dest = targetPath(cfg, dir, global, plugin, name);
+  fs.mkdirSync(dest, { recursive: true });
+  const content = cfg.flat ? updateFrontmatterName(raw, plugin + '-' + name) : raw;
+  fs.writeFileSync(path.join(dest, 'SKILL.md'), content);
+}
+
+function installSymlink(cfg, dir, global, plugin, name, raw) {
+  const canonDir = canonicalPath(dir, global, plugin, name);
+  fs.mkdirSync(canonDir, { recursive: true });
+  const flatName = plugin + '-' + name;
+  const updated = cfg.flat ? updateFrontmatterName(raw, flatName) : raw;
+  fs.writeFileSync(path.join(canonDir, 'SKILL.md'), updated);
 
-  process.stderr.write(`首次运行，正在下载 devflow-skills v${VERSION} (${platform})...\n`);
+  const linkDir = targetPath(cfg, dir, global, plugin, name);
+  const linkFile = path.join(linkDir, 'SKILL.md');
+  try { fs.unlinkSync(linkDir); } catch (_) {}
+  try { fs.unlinkSync(linkFile); } catch (_) {}
+  fs.mkdirSync(path.dirname(linkFile), { recursive: true });
 
   try {
-    await downloadBinary(url, binaryPath);
-    process.stderr.write('下载完成。\n');
-  } catch (e) {
-    process.stderr.write('下载失败，尝试本地构建...\n');
+    fs.symlinkSync(path.relative(path.dirname(linkFile), path.join(canonDir, 'SKILL.md')), linkFile);
+  } catch (_) {
+    installOne(cfg, dir, global, false, { plugin, name, raw });
+  }
+}
+
+function installAll(selected, cfg, dir, global, symlink, sourceLabel) {
+  let installed = 0;
+  const quiet = selected.length > 10;
+  for (const s of selected) {
     try {
-      const goBuild = spawnSync('go', ['build', '-o', binaryPath, pkgDir], {
-        cwd: pkgDir,
-        stdio: 'inherit',
-      });
-      if (goBuild.status === 0 && fs.existsSync(binaryPath)) {
-        return binaryPath;
-      }
-    } catch (_) {}
+      installOne(cfg, dir, global, symlink, s);
+      installed++;
+      if (!quiet || installed <= 10) console.log(`  ${s.plugin}-${s.name} (${s.description})`);
+      else if (installed === 11) console.log('  ...');
+    } catch (e) {
+      console.error(`安装 ${s.plugin}-${s.name} 失败:`, e.message);
+    }
+  }
+  const label = sourceLabel ? `从 ${sourceLabel} ` : '';
+  console.log(`\n已${label}安装 ${installed} 个技能到 ${targetBase(cfg, dir, global)}/`);
+  console.log('下一步: 重启 AI 工具或刷新技能列表即可使用。');
+}
+
+function runInstall(flags) {
+  const cfg = requireTool(flags);
+  requireSelection(flags);
+  const selected = selectSkills(flags, loadSkills(__dirname));
+  installAll(selected, cfg, flags.dir || '.', !!flags.global, !!flags.symlink);
+}
+
+// ── list ────────────────────────────────────────────────────────────────
+
+function groupSkills(skills) {
+  const groups = {};
+  for (const s of skills) {
+    if (!groups[s.plugin]) groups[s.plugin] = [];
+    groups[s.plugin].push(s);
+  }
+  return groups;
+}
+
+function sortedPlugins(groups, filterPlugin) {
+  const order = filterPlugin ? [filterPlugin] : [...PLUGIN_ORDER];
+  for (const p of Object.keys(groups).sort()) {
+    if (!order.includes(p)) order.push(p);
+  }
+  return order;
+}
+
+function printSkillTable(plugins, groups, indent) {
+  for (const p of plugins) {
+    if (!groups[p]) continue;
+    console.log(`${indent}${p} (${groups[p].length} 个技能):`);
+    for (const s of groups[p]) console.log(`${indent}  ${s.name.padEnd(20)} ${s.description}`);
+    console.log();
+  }
+}
+
+function runList(flags) {
+  let skills = loadSkills(__dirname);
+  if (flags.plugin) skills = skills.filter(s => s.plugin === flags.plugin);
+  if (flags.filter) {
+    const f = flags.filter.toLowerCase();
+    skills = skills.filter(s => (s.plugin + '-' + s.name).includes(f) || s.name.includes(f));
+  }
+
+  if (flags.format === 'json') {
+    const out = {};
+    for (const p of sortedPlugins(groupSkills(skills), flags.plugin)) {
+      const g = groupSkills(skills)[p];
+      if (!g) continue;
+      out[p] = g.map(s => ({ name: s.name, flatName: s.plugin + '-' + s.name, description: s.description }));
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  const groups = groupSkills(skills);
+  for (const p of sortedPlugins(groups, flags.plugin)) {
+    if (!groups[p]) continue;
+    console.log(`${p} 插件 (${groups[p].length} 个技能):`);
+    for (const s of groups[p]) console.log(`  ${(s.plugin + '-' + s.name).padEnd(22)} ${s.description}`);
+    console.log();
+  }
+}
+
+// ── uninstall ───────────────────────────────────────────────────────────
+
+function runUninstall(flags) {
+  const cfg = requireTool(flags);
+  const dir = flags.dir || '.';
+  const global = !!flags.global;
+
+  if (flags.all) {
+    const base = targetBase(cfg, dir, global);
+    const abs = path.resolve(base);
+    if (!fs.existsSync(abs)) { console.log(`技能目录不存在: ${abs}\n无需卸载。`); return; }
+    fs.rmSync(abs, { recursive: true });
+    console.log(`已卸载所有技能，删除目录: ${abs}`);
+
+    const canon = canonicalBase(dir, global);
+    if (fs.existsSync(canon)) console.error(`注意: 规范目录 ${canon} 仍存在，如使用过 --symlink 模式可能需要手动清理`);
+    return;
+  }
+
+  ensure(flags.skill && flags.skill.length > 0, '请指定 --skill 或 --all');
 
-    process.stderr.write('本地构建失败，尝试使用 go install...\n');
+  const allSkills = loadSkills(__dirname);
+  let removed = 0;
+  for (const spec of flags.skill) {
+    const parts = spec.split('-', 2);
+    let plugin, name;
+    if (parts.length === 2) { plugin = parts[0]; name = parts[1]; }
+    else {
+      const s = uniqueResolve(spec, allSkills);
+      plugin = s.plugin; name = s.name;
+    }
+
+    const tgt = targetPath(cfg, dir, global, plugin, name);
+    if (!fs.existsSync(tgt)) { console.log(`未安装: ${plugin}-${name}`); continue; }
     try {
-      const goInstall = spawnSync('go', ['install', `github.com/zhouhao4221/devflow-skills@v${VERSION}`], {
-        stdio: 'inherit',
-      });
-      if (goInstall.status !== 0) {
-        console.error('go install 失败。请确保已安装 Go 1.21+ 或手动下载二进制。');
-        console.error(`GitHub Releases: https://github.com/zhouhao4221/devflow-skills/releases/tag/v${VERSION}`);
-        process.exit(1);
-      }
-      const goBinPath = path.join(os.homedir(), 'go', 'bin', BINARY_NAME);
-      if (fs.existsSync(goBinPath)) {
-        fs.copyFileSync(goBinPath, binaryPath);
-        fs.chmodSync(binaryPath, 0o755);
-        return binaryPath;
-      }
-    } catch (e2) {
-      console.error('go install 失败:', e2.message);
-      process.exit(1);
+      fs.rmSync(tgt, { recursive: true });
+      console.log(`已卸载: ${plugin}-${name}`);
+      removed++;
+    } catch (e) {
+      console.error(`卸载 ${plugin}-${name} 失败:`, e.message);
     }
   }
 
-  fs.chmodSync(binaryPath, 0o755);
-  return binaryPath;
+  console.log(removed === 0 ? '没有需要卸载的技能。' : `\n已卸载 ${removed} 个技能。`);
 }
 
-async function main() {
-  const binaryPath = await getBinary();
-  const result = spawnSync(binaryPath, process.argv.slice(2), {
-    stdio: 'inherit',
-  });
-  process.exit(result.status || 0);
+// ── add ─────────────────────────────────────────────────────────────────
+
+function fetchRepoSkills(repo) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'devflow-skills-'));
+  const url = `https://github.com/${repo}.git`;
+
+  console.error(`正在克隆 ${url}...`);
+  const r = spawnSync('git', ['clone', '--depth', '1', url, tmpDir], { stdio: 'inherit' });
+  if (r.status !== 0) {
+    try { fs.rmSync(tmpDir, { recursive: true }); } catch (_) {}
+    fail('git clone 失败');
+  }
+
+  const skills = loadSkills(tmpDir);
+  try { fs.rmSync(tmpDir, { recursive: true }); } catch (_) {}
+  return skills;
 }
 
-main().catch((err) => {
-  console.error('运行失败:', err.message);
-  process.exit(1);
-});
+function runAdd(flags, positional) {
+  const repo = positional[0];
+  ensure(repo, '请指定仓库 (格式: owner/repo)\n示例: devflow-skills add zhouhao4221/devflow-skills --list');
+  ensure(repo.includes('/'), '仓库格式无效，请使用 owner/repo 格式');
+
+  if (flags.list) {
+    const skills = fetchRepoSkills(repo);
+    console.log(`${repo} 中的可用技能:\n`);
+    printSkillTable(sortedPlugins(groupSkills(skills)), groupSkills(skills), '  ');
+    console.log(`安装示例:`);
+    console.log(`  devflow-skills add ${repo} --tool opencode --all`);
+    console.log(`  devflow-skills add ${repo} --tool cursor --skill <skill-name>`);
+    return;
+  }
+
+  const cfg = requireTool(flags);
+  requireSelection(flags);
+  const selected = selectSkills(flags, fetchRepoSkills(repo));
+  installAll(selected, cfg, flags.dir || '.', !!flags.global, !!flags.symlink, repo);
+}
+
+// ── version ─────────────────────────────────────────────────────────────
+
+function runVersion() {
+  console.log(`devflow-skills v${VERSION}`);
+}
+
+// ── main ────────────────────────────────────────────────────────────────
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) { usage(); process.exit(1); }
+
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+
+  if (cmd === 'help' || cmd === '-h' || cmd === '--help') { usage(); return; }
+  if (cmd === 'version' || cmd === '--version' || cmd === '-v') { runVersion(); return; }
+
+  const { positional, flags } = parseArgs(rest);
+
+  switch (cmd) {
+    case 'install':   return runInstall(flags);
+    case 'list':      return runList(flags);
+    case 'uninstall': return runUninstall(flags);
+    case 'add':       return runAdd(flags, positional);
+    default:
+      console.error(`未知命令: ${cmd}\n`);
+      usage();
+      process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhouhao4221/devflow-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "一键安装/管理 devflow-skills AI 技能包",
   "license": "Apache-2.0",
   "repository": {
@@ -12,6 +12,7 @@
   },
   "files": [
     "install.js",
+    "plugins/",
     "package.json"
   ]
 }

package/plugins/api/skills/api/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: api
+description: |
+  API 对接工具 - 列出接口概览和子命令帮助
+---
+
+# API 对接工具
+
+前端 API 对接工具主入口，展示接口概览和可用命令。
+
+## 命令格式
+
+```
+/api [--name=服务名] [--tag=分组名]
+```
+
+## 子命令
+
+| 子命令 | 说明 | 示例 |
+|-------|------|------|
+| (空) | 列出接口概览 | `/api` |
+| `config` | 配置管理 | `/api:config init` |
+| `import` | 导入 Swagger | `/api:import` |
+| `search` | 搜索接口 | `/api:search 用户` |
+| `map` | 字段映射 | `/api:map GET /api/v1/users/{id}` |
+| `gen` | 代码生成 | `/api:gen GET /api/v1/users/{id}` |
+
+## 执行流程
+
+### 无配置时
+
+```
+API 对接工具
+
+⚠️ 尚未初始化配置
+
+快速开始：
+  1. /api:config init    — 初始化配置，添加 Swagger 数据源
+  2. /api:import         — 导入并解析接口文档
+  3. /api:search <关键词> — 搜索接口
+  4. /api:map <接口>      — 查看字段映射
+  5. /api:gen <接口>      — 生成类型和请求代码
+```
+
+### 有配置时
+
+1. 读取 `.api-config.json`
+2. 对每个数据源调用 `swagger-parser.py`（`mode=summary`）获取接口总数和分组概览。
+
+3. 展示概览：
+
+   ```
+   API 对接工具
+
+   数据源：
+     1. 主服务 — http://localhost:8080/swagger/doc.json
+        接口数：42  |  分组：用户管理(8) 订单管理(12) 商品管理(10) 系统设置(6) 其他(6)
+
+     2. 支付服务 — ./docs/payment-swagger.json
+        接口数：15  |  分组：支付(8) 退款(4) 对账(3)
+
+   常用命令：
+     /api:search <关键词>              搜索接口
+     /api:map <METHOD> <path>         查看字段映射
+     /api:gen <METHOD> <path>         生成代码
+     /api:gen --tag=<分组名>           批量生成某分组代码
+     /api:config                      查看/修改配置
+   ```
+
+### 按 Tag 过滤
+
+```
+/api --tag=用户管理
+
+用户管理 — 8 个接口
+
+
+#  方法    路径                      描述            
+
+1  GET     /api/v1/users            获取用户列表     
+2  POST    /api/v1/users            创建用户         
+3  GET     /api/v1/users/{id}       获取用户详情     
+4  PUT     /api/v1/users/{id}       更新用户信息     
+5  DELETE  /api/v1/users/{id}       删除用户         
+6  POST    /api/v1/users/{id}/reset 重置密码         
+7  GET     /api/v1/users/export     导出用户数据     
+8  POST    /api/v1/users/import     导入用户数据     
+
+```
+
+### 数据源连接失败
+
+对无法访问的数据源标记状态：
+
+```
+数据源：
+  1. 主服务 — http://localhost:8080/swagger/doc.json
+     ❌ 无法访问，请检查后端服务是否启动
+
+  2. 支付服务 — ./docs/payment-swagger.json
+     接口数：15  |  分组：支付(8) 退款(4) 对账(3)
+```