@vocmarket/voc-skill 0.3.30 → 0.3.32

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "voc-intelligence",
   "description": "VOC intelligence skills for Claude Code: end-to-end VOC business workflows, Xiaohongshu and Douyin trend reports, live social VOC collection, Fmode Doubao image analysis, token/recharge checks, evidence-card outputs, prioritized issue pools, single-problem deep dives, competitor maps, 7-day content plans, VOC-backed speaking script co-creation, boss/operator action plans, and multi-turn memory.",
-  "version": "0.3.30",
+  "version": "0.3.32",
   "author": {
     "name": "nkkj-BrainHack"
   }

package/bin/claude-voc.js

@@ -4,12 +4,17 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { ensureActivated } = require('../mcp/src/core/activation');
+const { readNewApiToken } = require('../mcp/src/core/credentials');
 
 const SOURCE_ROOT = path.resolve(__dirname, '..');
 const WORKSPACE_ROOT = process.cwd();
 const DEFAULT_TARGET = path.join(os.homedir(), '.claude', 'plugins', 'voc-intelligence');
 const WORKSPACE_TARGET = path.join(WORKSPACE_ROOT, '.claude', 'plugins', 'voc-intelligence');
 const WORKSPACE_PLUGINS_ROOT = path.join(WORKSPACE_ROOT, '.claude', 'plugins');
+const CODEX_PROJECT_TARGET = path.join(WORKSPACE_ROOT, '.codex', 'plugins', 'voc-intelligence');
+const CODEX_GLOBAL_TARGET = path.join(os.homedir(), '.codex', 'plugins', 'voc-intelligence');
+const PORTABLE_WORKSPACE_TARGET = path.join(WORKSPACE_ROOT, '.vocmarket', 'plugins', 'voc-intelligence');
+const VOCMARKET_CREDENTIALS = path.join(os.homedir(), '.vocmarket', 'credentials.json');
 const MIN_NODE_MAJOR = 18;
 
 const EXCLUDED_DIRS = new Set([
@@ -35,7 +40,7 @@ function usage() {
     'Usage:',
     '  claude-voc install',
     '  claude-voc workspace',
-    '  claude-voc workspace --activate',
+    '  claude-voc workspace --activate --channel <name>',
     '  claude-voc install --workspace --smoke',
     '  claude-voc check',
     '  claude-voc smoke',
@@ -54,7 +59,8 @@ function usage() {
     '  --skip-install   Skip npm install after copying files',
     '  --smoke          Run sample/preference/MCP smoke checks after install',
     '  --activate       安装后按 token 状态激活：无 token 弹付费/登录页，有 token 直接放行（外部 AI IDE 专用，不影响 --smoke）',
-    '  --channel <name> 付费归因渠道名（claude-code/codex/workbuddy）',
+    '  --channel <name> 安装渠道（claude-code/codex/workbuddy/fmode-studio）',
+    '  --scope <name>   Codex 安装范围（project/global，默认 project）',
     '  --help, -h       Show help'
   ].join('\n');
 }
@@ -72,6 +78,9 @@ function parseArgs(argv) {
     smoke: false,
     activate: false,
     channel: 'external',
+    scope: 'project',
+    targetExplicit: false,
+    workspaceRequested: first === 'workspace' || first === 'install-workspace',
     force: false,
     help: false
   };
@@ -85,10 +94,13 @@ function parseArgs(argv) {
     const token = argv[i];
     if (token === '--target') {
       opts.target = argv[++i];
+      opts.targetExplicit = true;
     } else if (token.startsWith('--target=')) {
       opts.target = token.slice('--target='.length);
+      opts.targetExplicit = true;
     } else if (token === '--workspace') {
       opts.target = WORKSPACE_TARGET;
+      opts.workspaceRequested = true;
     } else if (token === '--force') {
       opts.force = true;
     } else if (token === '--skip-install') {
@@ -101,15 +113,48 @@ function parseArgs(argv) {
       opts.channel = argv[++i];
     } else if (token.startsWith('--channel=')) {
       opts.channel = token.slice('--channel='.length);
+    } else if (token === '--scope') {
+      opts.scope = argv[++i];
+    } else if (token.startsWith('--scope=')) {
+      opts.scope = token.slice('--scope='.length);
     } else if (token === '--help' || token === '-h') {
       opts.help = true;
     }
   }
 
+  opts.channel = normalizeInstallChannel(opts.channel);
+  opts.scope = normalizeInstallScope(opts.channel, opts.scope);
+  if (opts.workspaceRequested && !opts.targetExplicit) {
+    opts.target = defaultTargetFor(opts.channel, opts.scope);
+  }
   opts.target = path.resolve(expandHome(opts.target));
   return opts;
 }
 
+function normalizeInstallChannel(value) {
+  const channel = String(value || 'claude-code').trim().toLowerCase();
+  if (channel === 'external') return 'claude-code';
+  if (!['claude-code', 'codex', 'workbuddy', 'fmode-studio'].includes(channel)) {
+    throw new Error(`Unsupported install channel: ${channel}`);
+  }
+  return channel;
+}
+
+function normalizeInstallScope(channel, value) {
+  if (channel !== 'codex') return 'project';
+  const scope = String(value || 'project').trim().toLowerCase();
+  if (!['project', 'global'].includes(scope)) {
+    throw new Error(`Unsupported Codex install scope: ${scope}`);
+  }
+  return scope;
+}
+
+function defaultTargetFor(channel, scope) {
+  if (channel === 'codex') return scope === 'global' ? CODEX_GLOBAL_TARGET : CODEX_PROJECT_TARGET;
+  if (channel === 'workbuddy') return PORTABLE_WORKSPACE_TARGET;
+  return WORKSPACE_TARGET;
+}
+
 function run(command, args, cwd) {
   const useCmd = process.platform === 'win32' && command === 'npm';
   const executable = useCmd ? 'cmd.exe' : command;
@@ -184,8 +229,13 @@ function isSafeWorkspaceTarget(targetDir) {
   return isInside(WORKSPACE_PLUGINS_ROOT, targetDir);
 }
 
+function isSafeManagedTarget(targetDir) {
+  return [WORKSPACE_TARGET, CODEX_PROJECT_TARGET, CODEX_GLOBAL_TARGET, PORTABLE_WORKSPACE_TARGET]
+    .some(candidate => path.resolve(candidate) === path.resolve(targetDir));
+}
+
 function canOverwriteTarget(targetDir, opts) {
-  return opts.force || isSafeDefaultTarget(targetDir) || isSafeWorkspaceTarget(targetDir);
+  return opts.force || isSafeDefaultTarget(targetDir) || isSafeWorkspaceTarget(targetDir) || isSafeManagedTarget(targetDir);
 }
 
 function shouldCopyEntry(entry) {
@@ -262,9 +312,8 @@ function readJsonIfExists(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
-function writeWorkspaceMcpConfig(targetDir) {
-  const mcpConfigPath = path.join(WORKSPACE_ROOT, '.mcp.json');
-  const existing = readJsonIfExists(mcpConfigPath);
+function writeJsonMcpConfig(configPath, targetDir) {
+  const existing = readJsonIfExists(configPath);
   const mcpConfig = {
     ...existing,
     mcpServers: {
@@ -276,7 +325,99 @@ function writeWorkspaceMcpConfig(targetDir) {
       }
     }
   };
-  fs.writeFileSync(mcpConfigPath, `${JSON.stringify(mcpConfig, null, 2)}\n`, 'utf8');
+  ensureDir(path.dirname(configPath));
+  fs.writeFileSync(configPath, `${JSON.stringify(mcpConfig, null, 2)}\n`, 'utf8');
+}
+
+function writeWorkspaceMcpConfig(targetDir) {
+  const mcpConfigPath = path.join(WORKSPACE_ROOT, '.mcp.json');
+  writeJsonMcpConfig(mcpConfigPath, targetDir);
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function upsertCodexProjectMcp(targetDir, workspaceRoot = WORKSPACE_ROOT) {
+  const configPath = path.join(workspaceRoot, '.codex', 'config.toml');
+  const original = fs.existsSync(configPath) ? fs.readFileSync(configPath, 'utf8') : '';
+  const lines = original.replace(/\r\n/g, '\n').split('\n');
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    const table = line.match(/^\s*\[([^\]]+)]\s*(?:#.*)?$/);
+    if (table) {
+      skipping = table[1] === 'mcp_servers.voc' || table[1].startsWith('mcp_servers.voc.');
+    }
+    if (!skipping) kept.push(line);
+  }
+  while (kept.length && !kept[kept.length - 1].trim()) kept.pop();
+  const serverPath = path.join(targetDir, 'mcp', 'src', 'server.js');
+  const block = [
+    '[mcp_servers.voc]',
+    'command = "node"',
+    `args = [${tomlString(serverPath)}]`,
+    `cwd = ${tomlString(targetDir)}`
+  ];
+  ensureDir(path.dirname(configPath));
+  fs.writeFileSync(configPath, `${kept.concat(kept.length ? [''] : [], block).join('\n')}\n`, 'utf8');
+  return configPath;
+}
+
+function runCapture(command, args, cwd = WORKSPACE_ROOT) {
+  const useCmd = process.platform === 'win32';
+  const executable = useCmd ? 'cmd.exe' : command;
+  const finalArgs = useCmd ? ['/d', '/s', '/c', command, ...args] : args;
+  return spawnSync(executable, finalArgs, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 1024 * 1024 * 10
+  });
+}
+
+function registerCodexGlobalMcp(targetDir) {
+  const getResult = runCapture('codex', ['mcp', 'get', 'voc']);
+  if (!getResult.error && getResult.status === 0) {
+    const removeResult = runCapture('codex', ['mcp', 'remove', 'voc']);
+    if (removeResult.error || removeResult.status !== 0) {
+      throw new Error('Unable to update the existing Codex VOC MCP registration');
+    }
+  }
+  const serverPath = path.join(targetDir, 'mcp', 'src', 'server.js');
+  const addResult = runCapture('codex', ['mcp', 'add', 'voc', '--', 'node', serverPath]);
+  if (addResult.error || addResult.status !== 0) {
+    const detail = String(addResult.stderr || addResult.error?.message || '').trim();
+    throw new Error(`Codex MCP registration failed${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+function copyPackagedSkills(targetDir, destinationRoot) {
+  const sourceRoot = path.join(targetDir, 'skills');
+  ensureDir(destinationRoot);
+  let copied = 0;
+  for (const entry of fs.readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const destination = path.join(destinationRoot, entry.name);
+    removeDirResilient(destination);
+    copied += copyDirRecursive(path.join(sourceRoot, entry.name), destination);
+  }
+  return copied;
+}
+
+function persistNeutralCredential(credentialsPath = VOCMARKET_CREDENTIALS) {
+  const token = readNewApiToken();
+  if (!token) return false;
+  const existing = readJsonIfExists(credentialsPath);
+  ensureDir(path.dirname(credentialsPath));
+  fs.writeFileSync(credentialsPath, `${JSON.stringify({ ...existing, fmodeApiKey: token }, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600
+  });
+  try {
+    fs.chmodSync(credentialsPath, 0o600);
+  } catch {}
+  return true;
 }
 
 function asForwardSlash(filePath) {
@@ -617,11 +758,10 @@ function writeWorkspaceSkillEntries(targetDir) {
   fs.copyFileSync(path.join(targetDir, 'skills', 'voc-api-catalog', 'SKILL.md'), path.join(apiCatalogSkillDir, 'SKILL.md'));
 }
 
-function writeWorkspaceActivation(targetDir) {
-  if (!isSafeWorkspaceTarget(targetDir)) return;
+function writeClaudeWorkspaceActivation(targetDir) {
   writeWorkspaceMcpConfig(targetDir);
   writeWorkspaceSkillEntries(targetDir);
-  console.log('Wrote workspace MCP config: .\\.mcp.json');
+  console.log('Wrote Claude/Fmode workspace MCP config: .\\.mcp.json');
   console.log('Wrote workspace skill entry: .\\.claude\\skills\\xiaohongshu-trend-intelligence\\SKILL.md');
   console.log('Wrote workspace skill entry: .\\.claude\\skills\\douyin-trend-intelligence\\SKILL.md');
   console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-issue-pool\\SKILL.md');
@@ -634,26 +774,71 @@ function writeWorkspaceActivation(targetDir) {
   console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-api-catalog\\SKILL.md');
 }
 
-function printNextSteps(targetDir) {
-  const workspaceMode = isSafeWorkspaceTarget(targetDir);
+function writeWorkspaceActivation(targetDir, opts) {
+  if (!opts.workspaceRequested) return;
+  if (opts.channel === 'codex') {
+    const skillRoot = opts.scope === 'global'
+      ? path.join(os.homedir(), '.codex', 'skills')
+      : path.join(WORKSPACE_ROOT, '.codex', 'skills');
+    copyPackagedSkills(targetDir, skillRoot);
+    if (opts.scope === 'global') {
+      registerCodexGlobalMcp(targetDir);
+      console.log('Registered VOC MCP with Codex user config.');
+      console.log(`Installed Codex user skills: ${skillRoot}`);
+    } else {
+      const configPath = upsertCodexProjectMcp(targetDir);
+      console.log(`Registered VOC MCP with Codex project config: ${configPath}`);
+      console.log(`Installed Codex project skills: ${skillRoot}`);
+    }
+    return;
+  }
+  if (opts.channel === 'workbuddy') {
+    writeWorkspaceMcpConfig(targetDir);
+    const skillRoot = path.join(WORKSPACE_ROOT, '.workbuddy', 'skills');
+    copyPackagedSkills(targetDir, skillRoot);
+    console.log('Wrote portable WorkBuddy MCP registration: .\\.mcp.json');
+    console.log('Installed WorkBuddy workspace skills: .\\.workbuddy\\skills');
+    return;
+  }
+  writeClaudeWorkspaceActivation(targetDir);
+}
+
+async function verifyVocToolDiscovery(targetDir) {
+  const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+  const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+  const { version } = require('../package.json');
+  const client = new Client({ name: 'voc-installer-verification', version });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [path.join(targetDir, 'mcp', 'src', 'server.js')],
+    cwd: targetDir,
+    stderr: 'pipe'
+  });
+  await client.connect(transport);
+  try {
+    const result = await client.listTools();
+    const names = (result.tools || []).map(tool => tool.name);
+    const discovered = names.filter(name => name.startsWith('voc_api_'));
+    if (!discovered.length) {
+      throw new Error('MCP started, but no voc_api_* tool was discovered');
+    }
+    console.log(`Verified MCP tool discovery (no data request): ${discovered.join(', ')}`);
+    return discovered;
+  } finally {
+    await client.close();
+  }
+}
+
+function printNextSteps(targetDir, opts) {
+  const workspaceMode = opts.workspaceRequested;
   console.log('');
   console.log('Install complete.');
   console.log('');
   if (workspaceMode) {
-    console.log('VSCode workspace mode is ready.');
+    console.log(`${opts.channel} ${opts.scope} mode is ready.`);
     console.log('');
     console.log('Generated project files:');
-    console.log('  .\\.mcp.json');
-    console.log('  .\\.claude\\skills\\xiaohongshu-trend-intelligence\\SKILL.md');
-    console.log('  .\\.claude\\skills\\douyin-trend-intelligence\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-issue-pool\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-problem-deep-dive\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-content-plan\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-speaking-script\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-competitor-map\\SKILL.md');
-    console.log('  .\\.claude\\skills\\voc-business-workflow\\SKILL.md');
-    console.log('  .\\.claude\\skills\\fmode-image-analysis\\SKILL.md');
-    console.log('  .\\.claude\\plugins\\voc-intelligence');
+    console.log(`  ${targetDir}`);
     console.log('');
     console.log('Restart the VSCode Claude Code session if it was already open.');
   } else {
@@ -677,7 +862,7 @@ function printNextSteps(targetDir) {
   console.log(`Install target: ${targetDir}`);
 }
 
-function install(opts) {
+async function install(opts) {
   checkNodeVersion();
   if (path.resolve(SOURCE_ROOT) !== path.resolve(opts.target)) {
     if (fs.existsSync(opts.target)) {
@@ -693,7 +878,7 @@ function install(opts) {
 
   assertInstalled(opts.target);
   writeMcpConfig(opts.target);
-  writeWorkspaceActivation(opts.target);
+  writeWorkspaceActivation(opts.target, opts);
 
   if (!opts.skipInstall) {
     console.log('Installing runtime dependencies...');
@@ -707,7 +892,11 @@ function install(opts) {
     run(process.execPath, ['install.js', '--check', '--no-next'], opts.target);
   }
 
-  printNextSteps(opts.target);
+  if (opts.activate) {
+    persistNeutralCredential();
+    await verifyVocToolDiscovery(opts.target);
+  }
+  printNextSteps(opts.target, opts);
 }
 
 function check(opts) {
@@ -742,7 +931,7 @@ async function main() {
     return;
   }
   if (opts.command === 'install') {
-    install(opts);
+    await install(opts);
     if (opts.activate) {
       await ensureActivated({ channel: opts.channel });
     }
@@ -754,10 +943,20 @@ async function main() {
   throw new Error(`Unknown command: ${opts.command}\n\n${usage()}`);
 }
 
-main().catch((error) => {
-  console.error('');
-  console.error(`claude-voc failed: ${error.message}`);
-  process.exit(1);
-});
-
+if (require.main === module) {
+  main().catch((error) => {
+    console.error('');
+    console.error(`claude-voc failed: ${error.message}`);
+    process.exit(1);
+  });
+}
 
+module.exports = {
+  parseArgs,
+  normalizeInstallChannel,
+  normalizeInstallScope,
+  defaultTargetFor,
+  upsertCodexProjectMcp,
+  verifyVocToolDiscovery,
+  persistNeutralCredential
+};

package/mcp/catalog/params/taobao.json

@@ -17,6 +17,15 @@
       "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
     }
   ],
+  "taobao.get_item_detail_v3": [
+    {
+      "name": "itemId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
+    }
+  ],
   "taobao.get_item_detail_v4": [
     {
       "name": "itemId",
@@ -35,6 +44,15 @@
       "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
     }
   ],
+  "taobao.get_item_detail_v6": [
+    {
+      "name": "itemId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "淘宝/天猫上的唯一商品标识符（商品ID）。"
+    }
+  ],
   "taobao.get_item_detail_v9": [
     {
       "name": "itemId",
@@ -167,6 +185,23 @@
       "default": 1
     }
   ],
+  "taobao.get_shop_item_list_v4": [
+    {
+      "name": "sellerId",
+      "in": "query",
+      "type": "string",
+      "required": true,
+      "desc": "用于标识淘宝/天猫店铺的卖家用户ID。"
+    },
+    {
+      "name": "page",
+      "in": "query",
+      "type": "integer",
+      "required": false,
+      "desc": "用于分页的页码。",
+      "default": 1
+    }
+  ],
   "taobao.get_item_sale_v1": [
     {
       "name": "itemId",
@@ -223,4 +258,4 @@
       "default": 1
     }
   ]
-}
+}

package/mcp/catalog/voc-social-endpoints.json

@@ -22542,7 +22542,11 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "summary": "淘宝天猫商品详情兼容版本，可能返回上游快照。查价格与完整详情优先使用 v6，查页面展示销量使用 v3。",
+      "recommendedFor": [
+        "legacy_detail_compatibility"
+      ],
+      "freshness": "recordTime 是上游数据采集时间，不代表本次请求时间；调用方应根据 recordTime 计算滞后时长。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v1",
@@ -22570,7 +22574,8 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品详情",
-      "summary": "通过任务驱动的v2流程获取淘宝和天猫商品详情数据。如果数据在短暂等待后仍未就绪，响应将返回待处理任务状态。",
+      "summary": "商品详情 V2 任务结果读取接口；直接调用不会发起商品数据采集。普通详情查询优先使用 v6。",
+      "recommendationPriority": -100,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v2",
@@ -22593,12 +22598,52 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_item_detail_v3",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·页面展示销量（V3）",
+      "summary": "通过商品 ID 获取淘宝或天猫商品页当前展示的销量，适合核对“已售/付款人数”；金额与 SKU 明细请使用 v6。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-item-detail/v3",
+      "params": [],
+      "requiredParams": [
+        "itemId"
+      ],
+      "recommendationPriority": 90,
+      "recommendedFor": [
+        "page_sales",
+        "displayed_sales",
+        "buyer_count"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；返回前必须与当前时间比较，不把请求时间当作采集时间。",
+      "responseHint": "页面销量读取 data.sellCount；该版本不返回商品价格。",
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "商品",
+        "product",
+        "页面销量",
+        "已售",
+        "付款人数",
+        "sellCount",
+        "page sales"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_detail_v4",
       "platform": "taobao",
       "channel": "ecommerce",
-      "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "title": "淘宝天猫·券后价与商品详情（V4）",
+      "summary": "获取淘宝或天猫商品的标价、SKU 优惠后价格与商品详情；需要券后价/优惠后价口径时优先使用。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v4",
@@ -22606,6 +22651,13 @@
       "requiredParams": [
         "itemId"
       ],
+      "recommendationPriority": 95,
+      "recommendedFor": [
+        "coupon_price",
+        "discount_price"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；优惠后价仍可因账号、SKU、地区、优惠券和活动时间与结算页不同。",
+      "responseHint": "价格单位通常为分：itemPrice 是标价，DiscountPrice 是优惠后价，SKU 读取 sku2info.finalPrice/finalSkuPrice。",
       "tags": [
         "taobao",
         "淘宝天猫",
@@ -22617,7 +22669,13 @@
         "ecommerce",
         "电商",
         "商品",
-        "product"
+        "product",
+        "商品详情",
+        "券后价",
+        "优惠后价",
+        "DiscountPrice",
+        "coupon price",
+        "discount price"
       ],
       "billing": 1
     },
@@ -22649,12 +22707,54 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_item_detail_v6",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·商品详情与价格（V6）",
+      "summary": "通过商品 ID 获取淘宝或天猫商品详情、SKU 价格、促销价、图片和店铺信息；查价格与完整详情时优先使用。页面展示销量请另用 v3 核对。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-item-detail/v6",
+      "params": [],
+      "requiredParams": [
+        "itemId"
+      ],
+      "recommendationPriority": 100,
+      "recommendedFor": [
+        "product_detail",
+        "price",
+        "sku_price",
+        "promotion_price"
+      ],
+      "freshness": "recordTime 是上游数据采集时间；返回前必须与当前时间比较，不把请求时间当作采集时间。",
+      "responseHint": "价格优先读取 itemPrice.price / promotionPrice 及 SKU 价格；页面展示销量以 v3 的 sellCount 为准。",
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "商品",
+        "product",
+        "商品详情",
+        "价格",
+        "促销价",
+        "SKU",
+        "product detail",
+        "price"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_detail_v9",
       "platform": "taobao",
       "channel": "ecommerce",
-      "title": "淘宝天猫·商品详情",
-      "summary": "获取淘宝和天猫商品详情数据，包括价格、图片和店铺详情，用于商品研究、目录监控和电商分析。",
+      "title": "淘宝天猫·商品详情兼容版（V9）",
+      "summary": "淘宝天猫商品详情 V9 兼容数据源。num 是该版本的销售量级信号，totalCount 是评价总量，两者均不等于商品页当前展示付款人数。价格/关键属性优先 v6，页面销量优先 v3。",
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-detail/v9",
@@ -22662,6 +22762,12 @@
       "requiredParams": [
         "itemId"
       ],
+      "recommendationPriority": -50,
+      "recommendedFor": [
+        "legacy_v9_compatibility"
+      ],
+      "freshness": "recordTime 只表示 V9 响应快照的采集时间；嵌套 attribute 可能来自更旧的属性源，不能仅根据 recordTime 判定每个属性都已刷新。",
+      "responseHint": "num=V9 销售量级信号；totalCount=评价总量；attribute=V9 属性快照。不要把 num/totalCount 当作当前页面付款人数，也不要用 V9 attribute 覆盖 V6 的更新关键属性。",
       "tags": [
         "taobao",
         "淘宝天猫",
@@ -22795,7 +22901,8 @@
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·店铺商品列表",
-      "summary": "获取淘宝和天猫店铺商品列表数据，包括商品标题、价格和图片，用于卖家研究和目录跟踪。",
+      "summary": "已弃用的淘宝天猫店铺商品列表 V3；新调用使用 v4，只需 sellerId 并支持分页。",
+      "deprecated": true,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-shop-item-list/v3",
@@ -22819,12 +22926,47 @@
       ],
       "billing": 1
     },
+    {
+      "id": "taobao.get_shop_item_list_v4",
+      "platform": "taobao",
+      "channel": "ecommerce",
+      "title": "淘宝天猫·店铺商品列表（V4）",
+      "summary": "通过 sellerId 分页获取淘宝或天猫店铺商品列表，支持全部淘宝和天猫店铺；新调用优先使用。",
+      "method": "GET",
+      "paramsIn": "query",
+      "proxyPath": "taobao/get-shop-item-list/v4",
+      "params": [],
+      "requiredParams": [
+        "sellerId"
+      ],
+      "recommendationPriority": 100,
+      "recommendedFor": [
+        "shop_product_list",
+        "seller_catalog"
+      ],
+      "tags": [
+        "taobao",
+        "淘宝天猫",
+        "淘宝",
+        "天猫",
+        "tmall",
+        "Taobao and Tmall",
+        "ecommerce",
+        "电商",
+        "店铺商品",
+        "店铺商品列表",
+        "sellerId",
+        "shop product list"
+      ],
+      "billing": 1
+    },
     {
       "id": "taobao.get_item_sale_v1",
       "platform": "taobao",
       "channel": "ecommerce",
       "title": "淘宝天猫·商品销量",
-      "summary": "获取淘宝和天猫商品销量数据，用于销售追踪、商品研究和电商监控。",
+      "summary": "已弃用的 30 天商品销量接口，上游可能返回空数据。核对商品页“已售/付款人数”使用 get_item_detail_v3。",
+      "deprecated": true,
       "method": "GET",
       "paramsIn": "query",
       "proxyPath": "taobao/get-item-sale/v1",
@@ -28379,4 +28521,4 @@
       "billing": 1
     }
   ]
-}
+}

package/mcp/src/core/api-catalog.js

@@ -78,7 +78,8 @@ function searchEndpoints({ query, platform, tag, limit = 20 } = {}) {
   const tagKey = normalize(tag);
   let results = listEndpoints().map(endpoint => ({
     endpoint,
-    score: scoreEndpoint(endpoint, terms)
+    score: scoreEndpoint(endpoint, terms),
+    preference: endpoint.deprecated ? -1000 : Number(endpoint.recommendationPriority || 0)
   }));
   if (platformKey) {
     results = results.filter(item => normalize(item.endpoint.platform) === platformKey);
@@ -87,7 +88,7 @@ function searchEndpoints({ query, platform, tag, limit = 20 } = {}) {
     results = results.filter(item => (item.endpoint.tags || []).some(t => normalize(t) === tagKey));
   }
   results = results.filter(item => item.score > 0);
-  results.sort((a, b) => b.score - a.score);
+  results.sort((a, b) => (b.score - a.score) || (b.preference - a.preference));
   return results.slice(0, Math.max(1, limit)).map(item => item.endpoint);
 }
 
@@ -99,6 +100,9 @@ function summarizeEndpoint(endpoint) {
     summary: endpoint.summary,
     method: endpoint.method,
     proxyPath: endpoint.proxyPath,
+    deprecated: Boolean(endpoint.deprecated),
+    recommendedFor: endpoint.recommendedFor || [],
+    freshness: endpoint.freshness || null,
     requiredParams: (endpoint.params && endpoint.params.length)
       ? endpoint.params.filter(p => p.required).map(p => p.name)
       : (endpoint.requiredParams || []),

package/mcp/src/core/credentials.js

@@ -149,6 +149,7 @@ function readXiaohongshuToken(input = {}) {
 //   → Claude Code env（进程注入 + ~/.claude/settings.json）的 ANTHROPIC_AUTH_TOKEN（sk-、且 base 指向 fmode）。
 function readNewApiToken(input = {}) {
   const workspaceEnv = readEnvLocalFiles();
+  const vocMarketCreds = readJsonMaybe(path.join(os.homedir(), '.vocmarket', 'credentials.json'));
   const claudeCreds = readJsonMaybe(path.join(os.homedir(), '.claude', 'voc-credentials.json'));
   const fmodeConfig = readFmodeConfig();
   const claudeEnv = readClaudeSettingsEnv();
@@ -165,6 +166,9 @@ function readNewApiToken(input = {}) {
     process.env.NEW_API_TOKEN,
     process.env.FMODE_API_KEY,
     process.env.FMODE_API_TOKEN,
+    vocMarketCreds.fmodeApiKey,
+    vocMarketCreds.fmodeApiToken,
+    vocMarketCreds.newApiToken,
     claudeCreds.fmodeApiKey,
     claudeCreds.fmodeApiToken,
     fmodeConfig.newapiToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.30",
+  "version": "0.3.32",
   "description": "Claude Code VOC intelligence skills for Xiaohongshu and Douyin trend reports, live social VOC collection, Fmode image analysis, single-issue deep dives, boss/operator action plans, and multi-turn memory.",
   "type": "commonjs",
   "bin": {
@@ -29,7 +29,8 @@
     "voc:business-workflow": "node mcp/src/tools/voc-business-workflow-run.js --brand 示例品牌A --industry 家居定制 --platform douyin --collection-mode sample --keywords \"家居定制怎么选,第一次买怎么对比,售后\" --assistant-message-only",
     "mcp:start": "node mcp/src/server.js",
     "mcp:smoke": "node scripts/smoke-mcp.js",
-    "acceptance": "node scripts/acceptance.js"
+    "acceptance": "node scripts/acceptance.js",
+    "acceptance:installer": "node scripts/installer-acceptance.js"
   },
   "files": [
     ".claude-plugin/",

package/scripts/acceptance.js

@@ -13,6 +13,7 @@ function main() {
   run('npm', ['run', 'fmode:image:smoke'], ROOT);
   run('npm', ['run', 'smoke:package'], ROOT);
   run('npm', ['run', 'mcp:smoke'], ROOT);
+  run('npm', ['run', 'acceptance:installer'], ROOT);
   run('npm', ['pack', '--dry-run'], ROOT);
 
   const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'voc-workspace-install-'));

package/scripts/installer-acceptance.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  parseArgs,
+  normalizeInstallChannel,
+  normalizeInstallScope,
+  upsertCodexProjectMcp,
+  verifyVocToolDiscovery,
+  persistNeutralCredential
+} = require('../bin/claude-voc');
+
+async function main() {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voc-installer-acceptance-'));
+  const targetDir = path.join(tempRoot, '.codex', 'plugins', 'voc-intelligence');
+  const configDir = path.join(tempRoot, '.codex');
+  const configPath = path.join(configDir, 'config.toml');
+  const credentialsPath = path.join(tempRoot, '.vocmarket', 'credentials.json');
+  const previousToken = process.env.FMODE_API_KEY;
+
+  try {
+    assert.strictEqual(normalizeInstallChannel('CODEX'), 'codex');
+    assert.strictEqual(normalizeInstallScope('codex', 'global'), 'global');
+    assert.strictEqual(normalizeInstallScope('workbuddy', 'global'), 'project');
+
+    const options = parseArgs(['workspace', '--activate', '--channel=codex', '--scope=global']);
+    assert.strictEqual(options.activate, true);
+    assert.strictEqual(options.smoke, false);
+    assert.strictEqual(options.channel, 'codex');
+    assert.strictEqual(options.scope, 'global');
+
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(configPath, [
+      'model = "gpt-test"',
+      '',
+      '[mcp_servers.existing]',
+      'command = "existing-command"',
+      '',
+      '[mcp_servers.voc]',
+      'command = "old-command"',
+      ''
+    ].join('\n'));
+    upsertCodexProjectMcp(targetDir, tempRoot);
+    const config = fs.readFileSync(configPath, 'utf8');
+    assert.match(config, /model = "gpt-test"/);
+    assert.match(config, /\[mcp_servers\.existing]/);
+    assert.strictEqual((config.match(/\[mcp_servers\.voc]/g) || []).length, 1);
+    assert.ok(config.includes('mcp\\\\src\\\\server.js') || config.includes('mcp/src/server.js'));
+
+    process.env.FMODE_API_KEY = 'sk-installer_acceptance-123456789';
+    assert.strictEqual(persistNeutralCredential(credentialsPath), true);
+    const credentials = JSON.parse(fs.readFileSync(credentialsPath, 'utf8'));
+    assert.strictEqual(credentials.fmodeApiKey, process.env.FMODE_API_KEY);
+
+    const tools = await verifyVocToolDiscovery(path.resolve(__dirname, '..'));
+    assert.ok(tools.includes('voc_api_search'));
+    assert.ok(tools.includes('voc_api_doc'));
+    assert.ok(tools.includes('voc_api_call'));
+
+    console.log(JSON.stringify({
+      status: 'ok',
+      checks: ['channels', 'no-smoke activation', 'Codex TOML merge', 'neutral credentials', 'MCP ListTools'],
+      discoveredTools: tools
+    }, null, 2));
+  } finally {
+    if (previousToken === undefined) delete process.env.FMODE_API_KEY;
+    else process.env.FMODE_API_KEY = previousToken;
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+main().catch(error => {
+  console.error(error.message);
+  process.exit(1);
+});

package/scripts/smoke-mcp.js

@@ -291,6 +291,55 @@ async function main() {
       throw new Error(`Expected voc_api_search to list douyin endpoints, got: ${JSON.stringify(apiSearchStructured)}`);
     }
 
+    const taobaoDetailSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 商品详情' }
+    });
+    const taobaoDetailEndpoints = taobaoDetailSearchResult.structuredContent?.data?.endpoints || [];
+    const taobaoDetailIds = taobaoDetailEndpoints.map(endpoint => endpoint.id);
+    if (taobaoDetailIds[0] !== 'taobao.get_item_detail_v6') {
+      throw new Error(`Expected current Taobao endpoints with v6 preferred for product details, got: ${taobaoDetailIds.join(', ')}`);
+    }
+
+    const taobaoCatalogResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao' }
+    });
+    const taobaoCatalogIds = (taobaoCatalogResult.structuredContent?.data?.endpoints || []).map(endpoint => endpoint.id);
+    for (const id of ['taobao.get_item_detail_v3', 'taobao.get_item_detail_v6', 'taobao.get_shop_item_list_v4']) {
+      if (!taobaoCatalogIds.includes(id)) {
+        throw new Error(`Expected current Taobao catalog to include ${id}, got: ${taobaoCatalogIds.join(', ')}`);
+      }
+    }
+
+    const taobaoSalesSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 页面销量' }
+    });
+    const taobaoSalesEndpoints = taobaoSalesSearchResult.structuredContent?.data?.endpoints || [];
+    if (taobaoSalesEndpoints[0]?.id !== 'taobao.get_item_detail_v3' || taobaoSalesEndpoints[0]?.deprecated) {
+      throw new Error(`Expected Taobao v3 to be preferred for page sales, got: ${JSON.stringify(taobaoSalesEndpoints)}`);
+    }
+
+    const taobaoCouponPriceSearchResult = await client.callTool({
+      name: 'voc_api_search',
+      arguments: { platform: 'taobao', query: '淘宝 券后价' }
+    });
+    const taobaoCouponPriceEndpoints = taobaoCouponPriceSearchResult.structuredContent?.data?.endpoints || [];
+    if (taobaoCouponPriceEndpoints[0]?.id !== 'taobao.get_item_detail_v4') {
+      throw new Error(`Expected Taobao v4 to be preferred for coupon prices, got: ${JSON.stringify(taobaoCouponPriceEndpoints)}`);
+    }
+
+    const taobaoV9DocResult = await client.callTool({
+      name: 'voc_api_doc',
+      arguments: { id: 'taobao.get_item_detail_v9' }
+    });
+    const taobaoV9Endpoint = taobaoV9DocResult.structuredContent?.data?.endpoint || {};
+    if (!String(taobaoV9Endpoint.responseHint || '').includes('totalCount=') ||
+      Number(taobaoV9Endpoint.recommendationPriority) >= 0) {
+      throw new Error(`Expected Taobao v9 field semantics and compatibility priority, got: ${JSON.stringify(taobaoV9Endpoint)}`);
+    }
+
     const apiDocResult = await client.callTool({
       name: 'voc_api_doc',
       arguments: { id: 'douyin.search_general' }

package/skill-package-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.30",
+  "version": "0.3.32",
   "capabilities": {
     "summary": "三类情报源同源接入：①社媒内容 ②国内电商+创作者情报 ③海外选品。统一 search→doc→call、鉴权计费一致。",
     "channels": [
@@ -28,7 +28,7 @@
         "key": "ecommerce",
         "label": "国内电商 + 创作者情报",
         "platforms": 32,
-        "apis": 285,
+        "apis": 288,
         "examples": [
           "京东",
           "淘宝天猫",
@@ -53,7 +53,7 @@
     ],
     "totals": {
       "platforms": 51,
-      "apis": 1340
+      "apis": 1343
     }
   },
   "description": "Claude Code native VOC intelligence package for cross-industry social VOC workflows. Includes Xiaohongshu and Douyin trend intelligence, live token checks, evidence-card reports, single-issue VOC deep dives, boss/operator action plans, and scoped multi-turn memory.",
@@ -123,4 +123,4 @@
   "workspaceInstallCommand": "npx @vocmarket/voc-skill workspace --smoke",
   "workspaceInstallTarget": ".claude/plugins/voc-intelligence",
   "installHint": "Supports three delivery modes: unzip and run node install.js, install globally into ~/.claude/plugins/voc-intelligence, or install into the current workspace. Workspace mode writes .mcp.json plus .claude/skills/* entries for trend intelligence, issue pool, deep dive, competitor map, content plan, speaking script, VOC business workflow, and Fmode image analysis so VSCode Claude Code can discover the workflows without relying only on --plugin-dir."
-}
+}

package/skills/voc-api-catalog/SKILL.md

@@ -66,7 +66,18 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
    - 能力与性价比的客观评估：抖音 `douyin.xingtu.cost_performance_analysis` / `conversion_analysis`；小红书 `xiaohongshu.pgy.cost_effectiveness_analysis`。
 3. 把这些创作者侧事实**喂给下游 VOC 技能**（voc-competitor-map 做竞对达人布局、voc-content-plan / voc-speaking-script 做选题与脚本、voc-issue-pool 补充创作者 / 受众视角），形成洞察结论，而非「该投谁」的采买清单。
 
-> 提示：`voc_api_search` 用「星图 创作者」「蒲公英 画像」「受众分布」「性价比」等词即可定位创作者接口，用「京东 商品」「淘宝 评论」「1688 搜索」「亚马逊 选品」「ABA 关键词」等词定位电商/选品接口；`voc_api_doc` 会在请求行标注通道（ecommerce / overseas）并列出参数。当前清单 ecommerce 通道已登记约 285 个接口（电商商品 + 创作者 + 内容平台）、overseas 通道 37 个（亚马逊选品），未登记的可直接用 `voc_api_call` 传 `rawPath` + 对应 `channel` 调用。
+> 提示：`voc_api_search` 用「星图 创作者」「蒲公英 画像」「受众分布」「性价比」等词即可定位创作者接口，用「京东 商品」「淘宝 评论」「1688 搜索」「亚马逊 选品」「ABA 关键词」等词定位电商/选品接口；`voc_api_doc` 会在请求行标注通道（ecommerce / overseas）并列出参数。当前清单 ecommerce 通道已登记约 288 个接口（电商商品 + 创作者 + 内容平台）、overseas 通道 37 个（亚马逊选品），未登记的可直接用 `voc_api_call` 传 `rawPath` + 对应 `channel` 调用。
+
+## 淘宝/天猫版本选择与时效
+
+- 查商品详情、SKU 标价与促销价：优先 `taobao.get_item_detail_v6`；查券后价/优惠后价使用 `taobao.get_item_detail_v4`。价格必须标注是标价、促销价、活动价还是券后价，不要压成单一「真实价格」。
+- 查商品页当前展示的「已售/付款人数」：使用 `taobao.get_item_detail_v3` 的 `data.sellCount`。V3 不返回价格，价格与页面销量需分别调用 V6/V3。
+- `taobao.get_item_detail_v1` 仅用于兼容旧流程；`v2` 直接调用不会发起商品采集。`taobao.get_item_sale_v1` 和 `taobao.get_shop_item_list_v3` 已被上游标记弃用。
+- V9 的 `num` 是该版本销售量级信号，`totalCount` 是评价总量，两者都不是商品页当前展示付款人数。V9 `attribute` 可能是独立旧属性快照；价格和“上市时间”等关键属性优先 V6，页面销量优先 V3。
+- 返回里的 `recordTime` 是上游数据采集时间，不是本次 API 请求时间。每个版本有独立数据源/快照，必须用「当前时间 - recordTime」计算滞后并在结果中明示。
+- 上游文档未给出固定刷新 SLA，不要将返回值表述为「请求时实时数据」，也不要将旧版 `orderPayUV` 与商品页当前展示口径直接等同。需要页面口径时以 V3 `sellCount` 为准。
+- 实际结算价还会受 SKU、账号会员价、地区、店铺券、平台补贴和活动时间影响。API 返回的是对应口径快照，不等于任意账号在结算页的最终应付价。
+- 店铺商品列表的新调用优先 `taobao.get_shop_item_list_v4`，入参为 `sellerId` + 可选 `page`。
 
 ## Token（计费已迁移 NewAPI）