skill-market-cli 1.1.3 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-market-cli",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "CLI tool for managing skills on Skill Market",
   "main": "src/index.js",
   "bin": {

package/src/api/client.js

@@ -126,6 +126,32 @@ class ApiClient {
     return response.data;
   }
 
+  // SkillTag API
+  async searchSkillTags(keyword) {
+    const response = await this.client.get('/skill/tags/search', {
+      params: { keyword }
+    });
+    return response.data;
+  }
+
+  async createSkillTag(nameZh, nameEn) {
+    const response = await this.client.post('/skill/tags/create', {
+      nameZh,
+      nameEn
+    });
+    return response.data;
+  }
+
+  async getAllSkillTags() {
+    const response = await this.client.get('/skill/tags');
+    return response.data;
+  }
+
+  async resolveSkillTags(tags) {
+    const response = await this.client.post('/skill/tags/resolve', { tags });
+    return response.data;
+  }
+
   // OAuth API
   async getUserInfo() {
     const serverConfig = getServerConfig();

package/src/commands/update.js

@@ -88,7 +88,7 @@ async function update(skillId, options) {
         ? tags.map((t) => String(t).trim()).filter(Boolean)
         : ['general'];
     const modelFinal =
-      model && String(model).trim() ? String(model).trim() : 'deepseek-chat';
+      model && String(model).trim() ? String(model).trim() : '';
     const rootUrlFinal =
       existingSkill.rootUrl && String(existingSkill.rootUrl).trim()
         ? String(existingSkill.rootUrl).trim()

package/src/commands/upload.js

@@ -11,6 +11,84 @@ const {
   promptOnlyExamples
 } = require('../lib/skill-upload-helpers');
 
+/**
+ * normalizeTagsForUpload 规范化用户/AI 提交的原始标签：
+ * 1. 拆分连字符复合标签（如 "email-ses-smtp" → ["SES", "SMTP"]），滤除过于泛化的片段
+ * 2. 拆分中文复合标签（按常见分隔符）
+ * 3. 去重 + 去空
+ *
+ * 约束原则（抽象级别，不绑定具体案例）：
+ * - 原子性：每个 tag 只表示一个明确的技术/平台/概念，不组合多个语义单元
+ * - 抽象层级：优先使用技术名词本身而非其应用场景；能用协议/标准名就不用产品名
+ * - 避免泛化词：过于宽泛的片段（如 "email", "service", "kit", "tool"）不作为独立 tag，
+ *   除非它本身就是该 Skill 的核心主题且无更具体的替代词
+ */
+function normalizeTagsForUpload(tags) {
+  // 过于泛化的词（与具体技术无关或涵盖面过广），复合 tag 拆分后自动滤除
+  const genericWords = new Set([
+    'email', 'service', 'kit', 'tool', 'api', 'app', 'lib', 'utils',
+    'helper', 'core', 'base', 'common', 'demo', 'example', 'test',
+    'simple', 'basic', 'advanced', 'pro', 'lite', 'plus'
+  ]);
+
+  const result = [];
+  for (const raw of tags) {
+    const trimmed = String(raw).trim();
+    if (!trimmed) continue;
+
+    // 1. 拆分连字符复合词
+    if (trimmed.includes('-') && !trimmed.startsWith('file-') && !trimmed.startsWith('os-')) {
+      const parts = trimmed.split('-').map(p => p.trim()).filter(Boolean);
+      const meaningful = parts.filter(p => !genericWords.has(p.toLowerCase()));
+      if (meaningful.length > 0) {
+        for (const p of meaningful) result.push(p);
+        continue;
+      }
+    }
+
+    // 2. 拆分中文复合词（含空格）
+    if (/[一-鿿]/.test(trimmed) && /\s/.test(trimmed)) {
+      const parts = trimmed.split(/\s+/).filter(Boolean);
+      for (const p of parts) result.push(p);
+      continue;
+    }
+
+    // 3. 尝试检测中文连写复合词（无空格、多概念粘连）
+    // 常见技术后缀可作为拆分边界：云、服务、平台、协议、框架、工具、系统
+    const cnSplitHints = ['云', '服务', '平台', '协议', '框架', '工具', '系统', '邮件', '推送', '验证'];
+    let didSplit = false;
+    for (const hint of cnSplitHints) {
+      const idx = trimmed.indexOf(hint);
+      if (idx > 0 && idx + hint.length < trimmed.length) {
+        // hint 在中间，拆分
+        const before = trimmed.substring(0, idx + hint.length);
+        const after = trimmed.substring(idx + hint.length);
+        result.push(before, after);
+        didSplit = true;
+        break;
+      }
+    }
+    if (didSplit) continue;
+
+    result.push(trimmed);
+  }
+
+  // 常见缩写/协议名规范化：纯字母 2-4 字符全大写
+  const normalized = result.map(t => {
+    if (/^[a-zA-Z]{2,4}$/.test(t)) return t.toUpperCase();
+    return t;
+  });
+
+  // 去重（大小写不敏感）
+  const seen = new Set();
+  return normalized.filter(t => {
+    const key = t.toLowerCase();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 /**
  * 交互补全：名称、描述、标签、模型、rootUrl、用户案例 + 可选运行采集轨迹
  */
@@ -95,11 +173,15 @@ async function upload(skillPath, options = {}) {
       {
         type: 'input',
         name: 'm',
-        message: '推荐模型（用于案例采集与提交，建议与线上一致）：',
-        default: 'deepseek-chat'
+        message: '推荐模型（必填，如 claude-sonnet-4-6 / gpt-4o / deepseek-chat，请填写实际使用的模型）：',
+        validate: (input) => (input && String(input).trim() ? true : '模型名不能为空，请填写你当前使用的模型名称')
       }
     ]);
-    model = m || 'deepseek-chat';
+    model = String(m || '').trim();
+    if (!model) {
+      console.error(chalk.red('模型名不能为空，上传已取消。'));
+      process.exit(1);
+    }
   }
 
   const modelFinal = String(model).trim();
@@ -186,12 +268,189 @@ async function upload(skillPath, options = {}) {
   try {
     console.log(chalk.gray('\n正在上传…\n'));
 
-    const tagsFinal = tags.map((t) => String(t).trim()).filter(Boolean);
+    const tagsRaw = tags.map((t) => String(t).trim()).filter(Boolean);
+    const tagsFinal = normalizeTagsForUpload(tagsRaw);
+
+    if (tagsFinal.length !== tagsRaw.length) {
+      console.log(chalk.yellow(`标签规范化：${tagsRaw.length} → ${tagsFinal.length}（拆分复合词/去重）`));
+      console.log(chalk.gray(`  原始: [${tagsRaw.join(', ')}]`));
+      console.log(chalk.gray(`  规范: [${tagsFinal.join(', ')}]`));
+    }
+
+    // Resolve tags against SkillTag vocabulary (batch)
+    console.log(chalk.gray('\nResolving tags...'));
+    const resolvedTags = [];
+    try {
+      const resolveResult = await apiClient.resolveSkillTags(tagsFinal);
+      if (resolveResult.code === 200 && resolveResult.data) {
+        const unmatchedTags = [];
+
+        for (const [rawTag, result] of Object.entries(resolveResult.data)) {
+          if (result.status === 'matched' && result.tag) {
+            resolvedTags.push(result.tag.nameEn);
+            console.log(chalk.gray(`  ${rawTag} -> ${result.tag.nameZh} (${result.tag.nameEn})`));
+          } else {
+            // unmatched: collect for later decision
+            const suggestions = result.suggestions || [];
+            unmatchedTags.push({ rawTag, suggestions });
+          }
+        }
+
+        // Handle unmatched tags interactively
+        if (unmatchedTags.length > 0) {
+          console.log(chalk.yellow(`\n以下 ${unmatchedTags.length} 个标签在数据库中未找到：`));
+          for (const { rawTag, suggestions } of unmatchedTags) {
+            console.log(chalk.yellow(`\n  ✗ "${rawTag}" 不存在`));
+            if (suggestions.length > 0) {
+              console.log(chalk.gray(`    数据库中可能相关的标签：`));
+              for (const s of suggestions) {
+                console.log(chalk.gray(`      - ${s.nameZh} (${s.nameEn}) [id=${s.id}]`));
+              }
+            } else {
+              console.log(chalk.gray(`    未找到相似标签`));
+            }
+          }
+
+          // Let user/AI decide for each unmatched tag
+          for (const { rawTag, suggestions } of unmatchedTags) {
+            const choices = [
+              { name: `创建新标签 "${rawTag}"`, value: 'create' },
+              ...suggestions.map(s => ({
+                name: `复用 "${s.nameZh}" (${s.nameEn})`,
+                value: s.nameEn
+              })),
+              { name: '跳过此标签', value: 'skip' }
+            ];
+
+            // In non-interactive mode, auto-create if no suggestions, otherwise ask
+            if (options.yes) {
+              // Auto mode: 仅在建议足够匹配时才复用，否则创建新 tag
+              // 匹配条件：建议的 nameEn 与原始 tag 完全相同（大小写不敏感），
+              // 或原始 tag 作为独立单词出现在建议中（如 "AI" 匹配 "AI Agent"）
+              const strongMatch = suggestions.find(s => {
+                const sLower = s.nameEn.toLowerCase();
+                const tLower = rawTag.toLowerCase();
+                if (sLower === tLower) return true;
+                // 原始 tag 作为独立单词出现在建议中，且建议不超过 2 个单词
+                // （避免 "SES" 匹配到 "email-ses-smtp" 这类长复合词）
+                const parts = sLower.split(/[-_\s]+/);
+                if (parts.length <= 2 && parts.includes(tLower)) return true;
+                return false;
+              });
+              if (strongMatch) {
+                resolvedTags.push(strongMatch.nameEn);
+                console.log(chalk.gray(`  [auto] ${rawTag} -> ${strongMatch.nameEn} (匹配: ${strongMatch.nameZh})`));
+              } else if (suggestions.length > 0) {
+                // 有建议但不够强 → 仍然创建新 tag（更保守，避免错误合并）
+                const nameEn = rawTag.replace(/\s+/g, '-').toLowerCase();
+                try {
+                  const createResult = await apiClient.createSkillTag(rawTag, nameEn);
+                  if (createResult.code === 200 && createResult.data) {
+                    resolvedTags.push(createResult.data.nameEn);
+                    console.log(chalk.green(`  [auto] 已创建标签: ${rawTag} (${createResult.data.nameEn})`));
+                  } else {
+                    resolvedTags.push(rawTag);
+                  }
+                } catch {
+                  resolvedTags.push(rawTag);
+                }
+              } else {
+                const nameEn = rawTag.replace(/\s+/g, '-').toLowerCase();
+                try {
+                  const createResult = await apiClient.createSkillTag(rawTag, nameEn);
+                  if (createResult.code === 200 && createResult.data) {
+                    resolvedTags.push(createResult.data.nameEn);
+                    console.log(chalk.green(`  [auto] 已创建标签: ${rawTag} (${createResult.data.nameEn})`));
+                  } else {
+                    console.log(chalk.yellow(`  [auto] 跳过: ${rawTag}`));
+                  }
+                } catch {
+                  console.log(chalk.yellow(`  [auto] 创建失败，跳过: ${rawTag}`));
+                }
+              }
+              continue;
+            }
+
+            const { action } = await inquirer.prompt([
+              {
+                type: 'list',
+                name: 'action',
+                message: `如何处理标签 "${rawTag}"？`,
+                choices
+              }
+            ]);
+
+            if (action === 'create') {
+              const nameEn = rawTag.replace(/\s+/g, '-').toLowerCase();
+              try {
+                const createResult = await apiClient.createSkillTag(rawTag, nameEn);
+                if (createResult.code === 200 && createResult.data) {
+                  resolvedTags.push(createResult.data.nameEn);
+                  console.log(chalk.green(`  已创建: ${rawTag} -> ${createResult.data.nameEn}`));
+                } else {
+                  console.log(chalk.yellow(`  创建失败，跳过: ${rawTag}`));
+                }
+              } catch (createErr) {
+                // Retry search (another process may have created it concurrently)
+                try {
+                  const retryResult = await apiClient.searchSkillTags(rawTag);
+                  if (retryResult.code === 200 && Array.isArray(retryResult.data) && retryResult.data.length > 0) {
+                    resolvedTags.push(retryResult.data[0].nameEn);
+                    console.log(chalk.gray(`  已存在（重试命中）: ${rawTag} -> ${retryResult.data[0].nameEn}`));
+                  } else {
+                    console.log(chalk.yellow(`  创建失败，跳过: ${rawTag}`));
+                  }
+                } catch {
+                  console.log(chalk.yellow(`  创建失败，跳过: ${rawTag}`));
+                }
+              }
+            } else if (action === 'skip') {
+              console.log(chalk.gray(`  已跳过: ${rawTag}`));
+            } else {
+              // Reuse existing tag
+              resolvedTags.push(action);
+              console.log(chalk.gray(`  复用: ${rawTag} -> ${action}`));
+            }
+          }
+        }
+      } else {
+        // Fallback to original behavior
+        console.log(chalk.yellow('批量解析失败，回退到逐个解析...'));
+        for (const tag of tagsFinal) {
+          try {
+            const searchResult = await apiClient.searchSkillTags(tag);
+            if (searchResult.code === 200 && Array.isArray(searchResult.data) && searchResult.data.length > 0) {
+              resolvedTags.push(searchResult.data[0].nameEn);
+            } else {
+              resolvedTags.push(tag);
+            }
+          } catch {
+            resolvedTags.push(tag);
+          }
+        }
+      }
+    } catch (err) {
+      // Fallback: network error or endpoint not available
+      console.log(chalk.yellow('批量解析接口不可用，回退到逐个解析...'));
+      for (const tag of tagsFinal) {
+        try {
+          const searchResult = await apiClient.searchSkillTags(tag);
+          if (searchResult.code === 200 && Array.isArray(searchResult.data) && searchResult.data.length > 0) {
+            resolvedTags.push(searchResult.data[0].nameEn);
+          } else {
+            resolvedTags.push(tag);
+          }
+        } catch {
+          resolvedTags.push(tag);
+        }
+      }
+    }
+
     const data = {
       name: String(name).trim(),
       purpose: String(description).trim(),
       rootUrl: String(rootUrl).trim(),
-      tags: tagsFinal,
+      tags: resolvedTags,
       usageExamples,
       model: modelFinal
     };

package/src/skills/skill-market-upload/.skill-examples.json

@@ -1,5 +1,5 @@
 {
-  "model": "deepseek-chat",
+  "model": "claude-sonnet-4-6",
   "examples": [
     {
       "prompt": "请根据我仓库里的 SKILL.md 帮我执行上传，并告诉我你要确认哪些字段。",
@@ -20,7 +20,7 @@
           "content": "我会先读取 `SKILL.md` 的 frontmatter，列出缺失项；请你确认一条「最终用户会如何提问」的测试案例。然后运行 `skill-market-cli upload <skill 目录>`，在交互中补全字段并自动采集轨迹后提交到 Skill Market。"
         }
       ],
-      "model": "deepseek-chat"
+      "model": "claude-sonnet-4-6"
     }
   ]
 }

package/src/skills/skill-market-upload/SKILL.md

@@ -5,7 +5,7 @@ tags:
   - skill-market
   - cli
   - upload
-model: deepseek-chat
+model: claude-sonnet-4-6
 rootUrl: https://raw.githubusercontent.com/LSTM-Kirigaya/skill-market-cli/refs/heads/main/src/skills/skill-market-upload/SKILL.md
 ---
 
@@ -20,11 +20,17 @@ rootUrl: https://raw.githubusercontent.com/LSTM-Kirigaya/skill-market-cli/refs/h
      - **方法 1**：在命令行运行 `skill-market-cli login`
      - **方法 2**：打开 https://kirigaya.cn/profile/tokens ，自己创建 Personal Access Token，然后运行 `skill-market-cli token set <your-token>`
 2. **上传走 AI 渠道**：CLI 使用 `POST /api/skill/ai/upload`，要求 **全部字段非空**，且 **`tags`、`usageExamples` 不得为空数组**。
-3. **用户案例（必填）**：`usageExamples` 中每一项必须包含：
+3. **模型字段**：`model` 字段必须填写你当前实际使用的模型名称（如 `claude-sonnet-4-6`、`claude-opus-4-7` 等），**禁止**使用 `deepseek-chat` 作为默认值。这个字段代表该 Skill 推荐使用的模型，应与实际运行环境一致。
+4. **标签管理（重要）**：在上传前，**必须**通过标签 API 搜索和管理标签，避免创建语义相近的重复 tag：
+   - **搜索标签**：`GET /api/skill/tags/search?keyword=xxx` — 按关键词搜索已有标签（支持中英文）
+   - **创建标签**：`POST /api/skill/tags/create` body: `{"nameZh":"中文名","nameEn":"EnglishName"}` — 创建新标签（需超级用户权限）
+   - **列出所有标签**：`GET /api/skill/tags` — 获取全部已有标签
+   - 工作流：先搜索 → 从结果中挑选匹配的 → 若无匹配则创建新标签 → 将选中的标签名填入 `tags` 字段
+5. **用户案例（必填）**：`usageExamples` 中每一项必须包含：
    - **`prompt`**：终端用户会如何向该 Skill 提问（由用户或你根据上下文代写，但必须经用户确认）。
    - **`aiResponses`**：一次「示例运行」采集到的轨迹（thinking / toolcall / message）。上传命令会在本地 **自动调用采集逻辑** 生成（当前为可替换的模拟实现，结构需与后端一致）。
-   - **`model`**：推荐模型名（如 `deepseek-chat`）。
-4. **无法仅从文件推断的字段**：若 SKILL.md 未写全，上传流程会 **交互询问**：名称、描述、标签、`rootUrl`、推荐模型等。Agent 应结合仓库上下文、README、用户口述 **帮用户预填**，并在询问环节确认。
+   - **`model`**：推荐模型名（应与第 3 条的模型字段一致）。
+6. **无法仅从文件推断的字段**：若 SKILL.md 未写全，上传流程会 **交互询问**：名称、描述、标签、`rootUrl`、推荐模型等。Agent 应结合仓库上下文、README、用户口述 **帮用户预填**，并在询问环节确认。
 
 ## 推荐工作流（Agent）
 
@@ -33,13 +39,20 @@ rootUrl: https://raw.githubusercontent.com/LSTM-Kirigaya/skill-market-cli/refs/h
    - 若未登录，向用户说明两种登录方式（`skill-market-cli login` 或前往 https://kirigaya.cn/profile/tokens 创建 token），并在用户完成登录后继续。
 2. 确认仓库中存在 **`SKILL.md`**（目录则路径指向该目录）。
 3. 读取 frontmatter，整理候选：`name`、`purpose`/`description`、`tags`、`model`、`rootUrl`。
-4. 与用户确认 **至少一条「用户会如何提问」的测试案例**（可多轮补充）。案例文本即 `prompt`。
-5. 在终端执行上传（勿省略路径）：
+4. **管理标签**：
+   - 根据 Skill 的用途提取 2–5 个关键词。
+   - 对每个关键词，调用 `GET /api/skill/tags/search?keyword=<关键词>` 搜索已有标签。
+   - 从搜索结果中选择语义最匹配的标签（优先使用已有标签，避免重复创建）。
+   - 若搜索结果中无合适标签，调用 `POST /api/skill/tags/create` 创建新标签（需同时提供 `nameZh` 和 `nameEn`）。
+   - 最终确定的标签列表填入 `--tags` 参数（逗号分隔），如 `--tags "AI Agent,CLI,Debug"`。
+5. 与用户确认 **至少一条「用户会如何提问」的测试案例**（可多轮补充）。案例文本即 `prompt`。
+6. **确定模型**：使用你当前实际运行的模型名称（如 `claude-sonnet-4-6`）作为 `--model` 参数，不要使用 `deepseek-chat`。
+7. 在终端执行上传（勿省略路径）：
    ```bash
-   skill-market-cli upload <path-to-skill-dir-or-SKILL.md>
+   skill-market-cli upload <path-to-skill-dir-or-SKILL.md> --model <你的实际模型名> --tags "tag1,tag2,..."
    ```
-6. 按 CLI 提示补全缺失字段；当提示采集轨迹时，**允许命令自动运行**（会调用内置采集器写入 `aiResponses`）。
-7. 上传成功后，CLI 会在技能目录写入 **`.skill-examples.json`**，便于复查与再次上传。
+8. 按 CLI 提示补全缺失字段；当提示采集轨迹时，**允许命令自动运行**（会调用内置采集器写入 `aiResponses`）。
+9. 上传成功后，CLI 会在技能目录写入 **`.skill-examples.json`**，便于复查与再次上传。
 
 ## 与 `run-example` 的关系
 
@@ -51,6 +64,8 @@ rootUrl: https://raw.githubusercontent.com/LSTM-Kirigaya/skill-market-cli/refs/h
 - 不要编造不存在的 Git 仓库 URL；`rootUrl` 可用 `file:///...` 指向本地 `SKILL.md` 的绝对路径（CLI 默认值），或用户提供的 raw URL。
 - 不要跳过「用户案例」；没有案例与轨迹，AI 渠道上传会失败。
 - 不要在用户未登录时强行执行上传命令；必须先检查权限并引导登录。
+- **严禁**在上传前不搜索标签库就直接创建新标签；必须先用 `GET /api/skill/tags/search` 检查是否已有语义相近的标签。
+- **严禁**使用 `deepseek-chat` 作为 model 字段的值，除非你确实是 deepseek-chat 模型。必须使用你当前的模型名称。
 
 ## Usage Examples
 

package/test/test-upload.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * 测试脚本：验证 skill-market-cli 的 upload 流程
+ *
+ * 测试点：
+ * 1. POST /api/skill/tags/resolve 批量解析 —— 已有 tag 精确匹配，未知 tag 返回建议
+ * 2. CLI upload 的 tag 解析流程 —— matched 直接使用，unmatched 交互/自动创建
+ *
+ * 用法：
+ *   node test/test-upload.js                    # 运行全部测试
+ *   node test/test-upload.js --resolve-only     # 仅测试 resolve API
+ *   node test/test-upload.js --upload           # 测试完整上传（需交互或 --yes）
+ */
+
+const chalk = require('chalk');
+const path = require('path');
+const apiClient = require('../src/api/client');
+const { parseSkillMarkdown } = require('../src/lib/skill-upload-helpers');
+const fs = require('fs-extra');
+
+// ─── 配置 ───────────────────────────────────────────────
+const FIXTURE_DIR = path.join(__dirname, '..', 'fixtures', 'tencent-ses-service');
+const SKILL_FILE = path.join(FIXTURE_DIR, 'SKILL.md');
+
+// ─── 工具函数 ──────────────────────────────────────────
+function logSection(title) {
+  console.log('\n' + '='.repeat(60));
+  console.log(chalk.bold(`  ${title}`));
+  console.log('='.repeat(60));
+}
+
+function logOK(msg) {
+  console.log(chalk.green(`  ✓ ${msg}`));
+}
+
+function logFAIL(msg) {
+  console.log(chalk.red(`  ✗ ${msg}`));
+}
+
+function logInfo(msg) {
+  console.log(chalk.gray(`  ℹ ${msg}`));
+}
+
+// ─── 测试 1：Tag 解析 API ──────────────────────────────
+async function testResolveAPI() {
+  logSection('测试 1：POST /api/skill/tags/resolve 批量标签解析');
+
+  // 从 fixture 读取实际 tags
+  const content = fs.readFileSync(SKILL_FILE, 'utf-8');
+  const { frontmatter } = parseSkillMarkdown(content);
+  const testTags = (frontmatter && frontmatter.tags) ? frontmatter.tags : [];
+
+  // 额外加入一个确定不存在且无建议的 tag
+  const uniqueTag = 'zzz-unique-test-' + Date.now();
+  testTags.push(uniqueTag);
+
+  console.log(chalk.gray(`  输入标签: ${testTags.join(', ')}`));
+
+  let result;
+  try {
+    result = await apiClient.resolveSkillTags(testTags);
+  } catch (err) {
+    logFAIL(`API 调用失败: ${err.message}`);
+    return { passed: 0, failed: 1 };
+  }
+
+  if (result.code !== 200) {
+    logFAIL(`API 返回非 200: ${JSON.stringify(result)}`);
+    return { passed: 0, failed: 1 };
+  }
+
+  const data = result.data;
+  let passed = 0;
+  let failed = 0;
+  let matchedCount = 0;
+  let unmatchedCount = 0;
+
+  // 遍历所有返回结果，验证数据结构
+  for (const [rawTag, info] of Object.entries(data)) {
+    if (info.status === 'matched') {
+      if (info.tag && info.tag.nameEn && info.tag.nameZh) {
+        logOK(`"${rawTag}" → matched: ${info.tag.nameZh} (${info.tag.nameEn})`);
+        matchedCount++;
+      } else {
+        logFAIL(`"${rawTag}" status=matched 但缺少 tag 详情`);
+        failed++;
+      }
+    } else if (info.status === 'unmatched') {
+      const suggestions = info.suggestions || [];
+      if (suggestions.length > 0) {
+        logOK(`"${rawTag}" → unmatched，${suggestions.length} 条建议: ${suggestions.map(s => s.nameZh).join(', ')}`);
+      } else {
+        logOK(`"${rawTag}" → unmatched，无相似建议`);
+      }
+      unmatchedCount++;
+    } else {
+      logFAIL(`"${rawTag}" 未知状态: ${info.status}`);
+      failed++;
+    }
+  }
+
+  // 验证唯一 tag 必然是 unmatched
+  const uniqueKey = Object.keys(data).find(k => k === uniqueTag);
+  if (uniqueKey && data[uniqueKey].status === 'unmatched') {
+    logOK(`唯一测试 tag "${uniqueTag}" 正确返回 unmatched`);
+    passed++;
+  } else {
+    logFAIL(`唯一测试 tag "${uniqueTag}" 应 unmatched`);
+    failed++;
+  }
+
+  passed += matchedCount + unmatchedCount; // 每个返回都算通过
+  logInfo(`统计: ${matchedCount} 匹配, ${unmatchedCount} 未匹配`);
+
+  console.log(chalk.bold(`\n  结果: ${chalk.green(passed + ' 通过')} / ${chalk.red(failed + ' 失败')}`));
+  return { passed, failed, data };
+}
+
+// ─── 测试 2：SKILL.md 解析 ─────────────────────────────
+async function testParseSkillMD() {
+  logSection('测试 2：SKILL.md 解析（frontmatter + Usage Examples）');
+
+  if (!fs.existsSync(SKILL_FILE)) {
+    logFAIL(`SKILL.md 不存在: ${SKILL_FILE}`);
+    return { passed: 0, failed: 1 };
+  }
+
+  const content = fs.readFileSync(SKILL_FILE, 'utf-8');
+  const { frontmatter, examples } = parseSkillMarkdown(content);
+
+  let passed = 0;
+  let failed = 0;
+
+  if (frontmatter) {
+    logOK(`frontmatter 解析成功`);
+    logInfo(`  name: ${frontmatter.name}`);
+    logInfo(`  purpose: ${(frontmatter.purpose || '').substring(0, 50)}...`);
+    logInfo(`  tags: [${(frontmatter.tags || []).join(', ')}]`);
+    logInfo(`  model: ${frontmatter.model}`);
+    logInfo(`  rootUrl: ${frontmatter.rootUrl}`);
+    passed++;
+  } else {
+    logFAIL('frontmatter 解析失败');
+    failed++;
+  }
+
+  if (examples.length > 0) {
+    logOK(`解析到 ${examples.length} 条 Usage Example`);
+    passed++;
+  } else {
+    logFAIL('未解析到 Usage Example');
+    failed++;
+  }
+
+  console.log(chalk.bold(`\n  结果: ${chalk.green(passed + ' 通过')} / ${chalk.red(failed + ' 失败')}`));
+  return { passed, failed, frontmatter, examples };
+}
+
+// ─── 测试 3：模拟 CLI upload 的 tag 解析流程 ─────────────
+async function testTagResolutionFlow() {
+  logSection('测试 3：模拟 CLI upload 中的 tag 解析流程');
+
+  const content = fs.readFileSync(SKILL_FILE, 'utf-8');
+  const { frontmatter } = parseSkillMarkdown(content);
+  const tagsFromMD = frontmatter.tags || [];
+
+  console.log(chalk.gray(`  从 SKILL.md 解析到的 tags: [${tagsFromMD.join(', ')}]`));
+
+  // Step 1: 批量 resolve
+  let resolveResult;
+  try {
+    resolveResult = await apiClient.resolveSkillTags(tagsFromMD);
+  } catch (err) {
+    logFAIL(`批量解析失败: ${err.message}`);
+    return { passed: 0, failed: 1 };
+  }
+
+  if (resolveResult.code !== 200) {
+    logFAIL(`批量解析返回非 200`);
+    return { passed: 0, failed: 1 };
+  }
+
+  const data = resolveResult.data;
+  const matched = [];
+  const unmatched = [];
+  let passed = 0;
+  let failed = 0;
+
+  for (const [rawTag, result] of Object.entries(data)) {
+    if (result.status === 'matched' && result.tag) {
+      matched.push({ raw: rawTag, nameEn: result.tag.nameEn, nameZh: result.tag.nameZh });
+      logOK(`"${rawTag}" → 匹配到 "${result.tag.nameZh}" (${result.tag.nameEn})`);
+    } else {
+      const suggestions = result.suggestions || [];
+      unmatched.push({ raw: rawTag, suggestions });
+      if (suggestions.length > 0) {
+        logInfo(`"${rawTag}" → 未匹配，有 ${suggestions.length} 条建议`);
+      } else {
+        logInfo(`"${rawTag}" → 未匹配，无建议`);
+      }
+    }
+  }
+
+  // 验证：所有返回的 tag 状态均合法
+  for (const [rawTag, info] of Object.entries(data)) {
+    if (info.status === 'matched' && info.tag) {
+      passed++;
+    } else if (info.status === 'unmatched') {
+      passed++;
+    } else {
+      logFAIL(`"${rawTag}" 状态异常: ${info.status}`);
+      failed++;
+    }
+  }
+
+  logInfo(`resolve 结果: ${matched.length} 匹配, ${unmatched.length} 未匹配`);
+
+  // 模拟 --yes 自动模式：matched 直接用，unmatched 自动创建
+  logInfo('\n  模拟 --yes 自动模式:');
+  const resolvedTags = matched.map(m => m.nameEn);
+
+  for (const u of unmatched) {
+    if (u.suggestions.length > 0) {
+      // 有建议则取第一个
+      const pick = u.suggestions[0].nameEn;
+      resolvedTags.push(pick);
+      logInfo(`  [auto] "${u.raw}" → 复用建议: ${pick}`);
+    } else {
+      // 无建议则尝试创建
+      const nameEn = u.raw.replace(/\s+/g, '-').toLowerCase();
+      try {
+        const createResult = await apiClient.createSkillTag(u.raw, nameEn);
+        if (createResult.code === 200 && createResult.data) {
+          resolvedTags.push(createResult.data.nameEn);
+          logOK(`  [auto] "${u.raw}" → 已创建: ${createResult.data.nameEn}`);
+          passed++;
+        } else {
+          logFAIL(`  [auto] "${u.raw}" → 创建失败: ${JSON.stringify(createResult)}`);
+          failed++;
+        }
+      } catch (err) {
+        logFAIL(`  [auto] "${u.raw}" → 创建异常: ${err.message}`);
+        failed++;
+      }
+    }
+  }
+
+  console.log(chalk.gray(`\n  最终提交的 tags: [${resolvedTags.join(', ')}]`));
+
+  console.log(chalk.bold(`\n  结果: ${chalk.green(passed + ' 通过')} / ${chalk.red(failed + ' 失败')}`));
+  return { passed, failed, matched, unmatched, resolvedTags };
+}
+
+// ─── 主入口 ─────────────────────────────────────────────
+async function main() {
+  const args = process.argv.slice(2);
+  const resolveOnly = args.includes('--resolve-only');
+  const upload = args.includes('--upload');
+
+  console.log(chalk.bold.cyan('╔══════════════════════════════════════════════════════╗'));
+  console.log(chalk.bold.cyan('║   Skill Market CLI — Upload 流程测试                  ║'));
+  console.log(chalk.bold.cyan('╚══════════════════════════════════════════════════════╝'));
+  console.log(chalk.gray(`  测试 fixture: ${SKILL_FILE}`));
+
+  let totalPassed = 0;
+  let totalFailed = 0;
+
+  // 测试 1: Resolve API
+  if (!upload) {
+    const r1 = await testResolveAPI();
+    totalPassed += r1.passed;
+    totalFailed += r1.failed;
+  }
+
+  // 测试 2: SKILL.md 解析
+  if (!upload) {
+    const r2 = await testParseSkillMD();
+    totalPassed += r2.passed;
+    totalFailed += r2.failed;
+  }
+
+  // 测试 3: Tag 解析流程模拟
+  const r3 = await testTagResolutionFlow();
+  totalPassed += r3.passed;
+  totalFailed += r3.failed;
+
+  // 如果有 --upload，实际执行 CLI upload
+  if (upload) {
+    logSection('测试 4：实际 CLI Upload（--yes 非交互模式）');
+    const { execSync } = require('child_process');
+    try {
+      const cmd = `node bin/skill-market-cli.js upload "${FIXTURE_DIR}" --yes`;
+      logInfo(`执行: ${cmd}`);
+      const output = execSync(cmd, { cwd: path.join(__dirname, '..'), encoding: 'utf-8', timeout: 60000 });
+      console.log(output);
+      logOK('Upload 命令执行成功');
+      totalPassed++;
+    } catch (err) {
+      logFAIL(`Upload 命令执行失败: ${err.message}`);
+      if (err.stdout) console.log(chalk.gray(err.stdout.toString()));
+      if (err.stderr) console.log(chalk.red(err.stderr.toString()));
+      totalFailed++;
+    }
+  }
+
+  // ─── 总结 ──────────────────────────────────────────
+  logSection('测试总结');
+  const total = totalPassed + totalFailed;
+  if (totalFailed === 0) {
+    console.log(chalk.green.bold(`  ✓ 全部 ${total} 项测试通过`));
+  } else {
+    console.log(chalk.yellow.bold(`  ${totalPassed}/${total} 通过, ${totalFailed} 失败`));
+  }
+
+  process.exit(totalFailed > 0 ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error(chalk.red('测试脚本异常:'), err);
+  process.exit(1);
+});