@vocmarket/voc-skill 0.3.21 → 0.3.23

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.17",
+  "version": "0.3.22",
   "author": {
     "name": "nkkj-BrainHack"
   }

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

@@ -723,8 +723,8 @@
       "platform": "xiaohongshu",
       "channel": "social",
       "title": "小红书笔记评论",
-      "summary": "按 note_id 拉取小红书笔记的一级评论。VOC 主力接口。",
-      "proxyPath": "xiaohongshu/app/get_note_comments",
+      "summary": "按 note_id 拉取小红书笔记的一级评论（App V2，VOC 口碑主力接口）。",
+      "proxyPath": "xiaohongshu/app_v2/get_note_comments",
       "method": "GET",
       "paramsIn": "query",
       "tags": [
@@ -742,34 +742,34 @@
           "in": "query",
           "type": "string",
           "required": true,
-          "desc": "笔记 id（note_id）。"
+          "desc": "笔记 id（note_id），来自 search_notes 返回的 note.id。"
         },
         {
-          "name": "start",
+          "name": "share_text",
           "in": "query",
           "type": "string",
           "required": false,
           "default": "",
-          "desc": "分页游标，首页留空，翻页用上一次返回的 start。"
+          "desc": "可选：小红书分享文案/链接，与 note_id 二选一。"
         },
         {
-          "name": "sort_strategy",
+          "name": "xsec_token",
           "in": "query",
-          "type": "integer",
+          "type": "string",
           "required": false,
-          "default": 1,
-          "desc": "排序：1 默认。"
+          "default": "",
+          "desc": "可选安全令牌，来自 search_notes 返回的 note.xsec_token；部分笔记风控需要。"
         }
       ],
-      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的 start。"
+      "responseHint": "返回评论列表，含 comment_id、文本、点赞、子评论数；翻页用返回的游标。"
     },
     {
       "id": "xiaohongshu.sub_comments",
       "platform": "xiaohongshu",
       "channel": "social",
       "title": "小红书评论回复（楼中楼）",
-      "summary": "按 note_id + comment_id 拉取某条评论下的回复，用于深挖讨论。",
-      "proxyPath": "xiaohongshu/app/get_sub_comments",
+      "summary": "按 note_id + comment_id 拉取某条评论下的回复（App V2），用于深挖讨论。",
+      "proxyPath": "xiaohongshu/app_v2/get_note_sub_comments",
       "method": "GET",
       "paramsIn": "query",
       "tags": [
@@ -835,7 +835,7 @@
           "in": "query",
           "type": "string",
           "required": true,
-          "desc": "用户 id（user_id），来自笔记/搜索返回。"
+          "desc": "用户 id（24 位 hex），来自 search_notes 返回的 note.user.userid；注意不是数字 red_id。"
         }
       ],
       "responseHint": "返回用户资料对象，含粉丝数、获赞收藏、简介。"

package/mcp/src/core/credentials.js

@@ -64,6 +64,56 @@ function readEnvLocalFiles() {
   }, {});
 }
 
+// 合并读取 Claude Code 的 settings env（用户级 + 项目级，含 .local 覆盖文件）。
+// Claude Code 用户的 fmode newapi SK 默认就放在这里的 env.ANTHROPIC_AUTH_TOKEN。
+function readClaudeSettingsEnv() {
+  const files = [
+    path.join(os.homedir(), '.claude', 'settings.json'),
+    path.join(os.homedir(), '.claude', 'settings.local.json'),
+    path.join(process.cwd(), '.claude', 'settings.json'),
+    path.join(process.cwd(), '.claude', 'settings.local.json'),
+  ];
+  const merged = {};
+  for (const filePath of files) {
+    const json = readJsonMaybe(filePath);
+    const env = json && typeof json.env === 'object' && json.env ? json.env : null;
+    if (!env) continue;
+    for (const [key, value] of Object.entries(env)) {
+      if (merged[key] === undefined && typeof value === 'string' && value.trim()) {
+        merged[key] = value;
+      }
+    }
+  }
+  return merged;
+}
+
+// 读取 ~/.fmode/config.json（及项目级 ./.fmode/config.json）里的 newapi token。
+function readFmodeConfig() {
+  const files = [
+    path.join(os.homedir(), '.fmode', 'config.json'),
+    path.join(process.cwd(), '.fmode', 'config.json'),
+  ];
+  const merged = {};
+  for (const filePath of files) {
+    const json = readJsonMaybe(filePath);
+    for (const [key, value] of Object.entries(json || {})) {
+      if (merged[key] === undefined) merged[key] = value;
+    }
+  }
+  return merged;
+}
+
+// 仅当 ANTHROPIC_AUTH_TOKEN 看起来是 fmode 的 newapi SK 时才采纳：
+// - 必须 sk- 开头，且排除真 Anthropic 官方 key（sk-ant- 开头）；
+// - 若 settings 里设了 ANTHROPIC_BASE_URL，必须指向 fmode（否则这把 token 是发往别处的，不能拿来当 fmode 计费 token）。
+function pickFmodeAnthropicToken(env) {
+  const token = env && typeof env.ANTHROPIC_AUTH_TOKEN === 'string' ? env.ANTHROPIC_AUTH_TOKEN.trim() : '';
+  if (!token || !/^sk-/i.test(token) || /^sk-ant-/i.test(token)) return '';
+  const base = String((env && (env.ANTHROPIC_BASE_URL || env.ANTHROPIC_API_BASE)) || '').toLowerCase();
+  if (base && !base.includes('fmode')) return '';
+  return token;
+}
+
 function readVocToken(input = {}) {
   const workspaceEnv = readEnvLocalFiles();
   const claudeCreds = readJsonMaybe(path.join(os.homedir(), '.claude', 'voc-credentials.json'));
@@ -90,10 +140,55 @@ function readXiaohongshuToken(input = {}) {
   return readVocToken(input);
 }
 
+// NewAPI（fmode-api）计费 token，以 sk- 开头。
+// 计费已迁移到 NewAPI：优先用它发请求，鉴权失败再回退平台 sessionToken（apig，原路径保留）。
+// 关键：这把 sk- 就是 Claude Code 的 env.ANTHROPIC_AUTH_TOKEN（在 ~/.claude/settings.json），
+// 默认装完技能不必再手动配置——这里直接从 settings.json / 进程环境读取它，避免「明明配了 SK 却判缺 token、被甩进老付费框」的死循环。
+// 取值优先级：显式入参 → .env.local / 环境变量 FMODE_API_KEY·NEWAPI_TOKEN
+//   → ~/.claude/voc-credentials.json 的 fmodeApiKey → ~/.fmode/config.json 的 newapiToken/fmodeApiToken
+//   → Claude Code env（进程注入 + ~/.claude/settings.json）的 ANTHROPIC_AUTH_TOKEN（sk-、且 base 指向 fmode）。
+function readNewApiToken(input = {}) {
+  const workspaceEnv = readEnvLocalFiles();
+  const claudeCreds = readJsonMaybe(path.join(os.homedir(), '.claude', 'voc-credentials.json'));
+  const fmodeConfig = readFmodeConfig();
+  const claudeEnv = readClaudeSettingsEnv();
+  return firstNonEmpty([
+    input.newapiToken,
+    input.newApiToken,
+    input.fmodeApiKey,
+    input.fmodeApiToken,
+    workspaceEnv.NEWAPI_TOKEN,
+    workspaceEnv.NEW_API_TOKEN,
+    workspaceEnv.FMODE_API_KEY,
+    workspaceEnv.FMODE_API_TOKEN,
+    process.env.NEWAPI_TOKEN,
+    process.env.NEW_API_TOKEN,
+    process.env.FMODE_API_KEY,
+    process.env.FMODE_API_TOKEN,
+    claudeCreds.fmodeApiKey,
+    claudeCreds.fmodeApiToken,
+    fmodeConfig.newapiToken,
+    fmodeConfig.newApiToken,
+    fmodeConfig.fmodeApiKey,
+    fmodeConfig.fmodeApiToken,
+    // Claude Code 显式写在 settings.json env 里的 fmode key（少见，但优先于自动推断的 ANTHROPIC_AUTH_TOKEN）
+    claudeEnv.FMODE_API_KEY,
+    claudeEnv.NEWAPI_TOKEN,
+    // Claude Code 默认入口：进程注入的 ANTHROPIC_AUTH_TOKEN（Claude Code 会把 settings.env 注入子进程）
+    pickFmodeAnthropicToken(process.env),
+    // 兜底：直接读 ~/.claude/settings.json 里的 env.ANTHROPIC_AUTH_TOKEN（独立运行、未被注入时）
+    pickFmodeAnthropicToken(claudeEnv),
+  ]);
+}
+
 module.exports = {
   readVocToken,
   readXiaohongshuToken,
+  readNewApiToken,
   readEnvFileMaybe,
   readWorkspaceEnvLocal,
-  envLocalCandidates
+  envLocalCandidates,
+  readClaudeSettingsEnv,
+  readFmodeConfig,
+  pickFmodeAnthropicToken
 };

package/mcp/src/core/payment-links.js

@@ -2,6 +2,9 @@ const VOC_SOCIAL_APIG_ID = 'Vo3ROWEvDy';
 const VOC_RECHARGE_FUN_ID = 'HOkkX72PMF';
 const VOC_RECHARGE_BASE_URL = 'https://app.fmode.cn/dev/apig-pay/';
 const PARSE_USERS_ME_URL = 'https://server.fmode.cn/parse/users/me';
+
+// NewAPI（fmode-api）余额充值入口。携带 ?balance=fmodeapi 会自动打开余额充值弹窗。
+const FMODE_API_RECHARGE_URL = 'https://app.fmode.cn/dev/studio/?balance=fmodeapi';
 const DEFAULT_WORKSHOP_PACKAGE_SLUG = '99';
 const VOC_WORKSHOP_PACKAGE_SLUGS = {
   trial199: '19-9',
@@ -123,6 +126,54 @@ function buildWrongTokenTypeMessage(paymentUrl, recharge = {}, options = {}) {
   ].join('\n');
 }
 
+// 没读到 NewAPI（fmode-api）的 sk- 计费 token 时的提示。
+// 关键：这是「没读到 SK」这种**可恢复**状态，不是余额不足、也不是功能用不了——
+// 先引导 agent 从 Claude Code 的 settings.json 取 SK 重试，充值只作为最后兜底（且仅真 402 才需要）。
+function buildMissingNewApiTokenMessage(paymentUrl, recharge = {}, options = {}) {
+  const platformLabel = options.platformLabel || '小红书';
+  const lines = [
+    `还没读到 NewAPI（fmode-api）计费 token，暂时不能进行真实 ${platformLabel} 采集——但这是**配置/读取**问题，不是余额不足，也不代表这个功能用不了。`,
+    '',
+    '这把计费 token 就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`（`sk-` 开头），通常配在用户级 `~/.claude/settings.json` 的 `env` 里。',
+    '',
+    '请按这个顺序自救（优先，不要直接让用户去点充值）：',
+    '1. 读取 `~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`（确认是 `sk-` 开头、`ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`）。',
+    '2. 用 `FMODE_API_KEY=sk-…`（或入参 `newapiToken`）把它传给本工具，重新调用一次。',
+    '3. 仍报缺 token / 鉴权失败时，才考虑回退 `r:` 开头的会话 token，或确认是否真的 `402 余额不足`。'
+  ];
+  if (paymentUrl) {
+    lines.push('', `（仅当确认是余额不足时才充值：${paymentUrl}）`);
+  }
+  lines.push('', '系统只会用 token 发起请求，绝不在报告、日志或聊天输出里回显 token。');
+  return lines.join('\n');
+}
+
+function buildFmodeApiRechargeUrl() {
+  return FMODE_API_RECHARGE_URL;
+}
+
+// NewAPI（fmode-api）余额不足（HTTP 402）时的充值提示。
+function buildFmodeApiRechargeMessage(paymentUrl = FMODE_API_RECHARGE_URL, options = {}) {
+  const platformLabel = options.platformLabel || '小红书';
+  return [
+    `VOC-AI 数据服务余额不足（fmode-api 计费额度已用尽），暂时不能继续真实 ${platformLabel} 采集。`,
+    '',
+    `请打开充值链接补充余额：${paymentUrl}`,
+    '',
+    '链接会自动打开余额充值弹窗；充值后用相同参数重试即可。底层鉴权/上游响应不会展示给用户。'
+  ].join('\n');
+}
+
+// 用户被禁用或无该接口权限（HTTP 403，区别于余额不足）。
+function buildPermissionDeniedMessage(options = {}) {
+  const platformLabel = options.platformLabel || '小红书';
+  return [
+    `当前账号被禁用或没有该 ${platformLabel} 接口的访问权限，暂时不能调用（这不是余额不足、也不是关键词/类目问题）。`,
+    '',
+    '请联系服务方确认账号状态或接口权限后重试。底层鉴权/上游响应不会展示给用户。'
+  ].join('\n');
+}
+
 module.exports = {
   VOC_SOCIAL_APIG_ID,
   VOC_RECHARGE_FUN_ID,
@@ -131,6 +182,10 @@ module.exports = {
   buildVocRechargeUrl,
   buildVocWorkshopUrl,
   buildMissingTokenMessage,
+  buildMissingNewApiTokenMessage,
   buildRechargeRequiredMessage,
-  buildWrongTokenTypeMessage
+  buildWrongTokenTypeMessage,
+  buildFmodeApiRechargeUrl,
+  buildFmodeApiRechargeMessage,
+  buildPermissionDeniedMessage
 };

package/mcp/src/features/fmode-image-analysis/image-analysis.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { readVocToken, readEnvFileMaybe, envLocalCandidates } = require('../../core/credentials');
+const { readVocToken, readNewApiToken, readEnvFileMaybe, envLocalCandidates } = require('../../core/credentials');
 const { buildVocRechargeInfo } = require('../../core/payment-links');
 const { okResult, errorResult } = require('../../core/result-envelope');
 
@@ -30,12 +30,12 @@ async function analyzeFmodeImage(input = {}) {
   if (!token) {
     const recharge = await buildVocRechargeInfo();
     return friendlyResult('needs_token', buildMissingTokenMessage(recharge.paymentUrl, recharge), {
-      summary: { imageCount: images.length, model: provider.model },
+      summary: { imageCount: images.length, model: provider.model, errorKind: 'missing_token', recoverable: true },
       data: { recharge, model: provider.model, imageCount: images.length },
       nextActions: [
-        `打开开通/充值链接：${recharge.paymentUrl}`,
-        '在当前工作区 .env.local 配置 VOC_TOKEN / FMODE_TOKEN / TIHAO_SESSION_TOKEN。',
-        '或在 MCP 工具参数中传入 vocToken / sessionToken / fmodeToken。'
+        '从 ~/.claude/settings.json 取 env.ANTHROPIC_AUTH_TOKEN（sk-，base 指向 api.fmode.cn），用 FMODE_API_KEY=sk-… 或入参 newapiToken/fmodeToken 传入后重试',
+        '或在当前工作区 .env.local 配置 FMODE_API_KEY / VOC_TOKEN / FMODE_TOKEN / TIHAO_SESSION_TOKEN',
+        '仅当确认是 402 余额不足时才打开充值链接，缺 token 不是没钱、也不代表功能用不了'
       ]
     });
   }
@@ -61,8 +61,8 @@ async function analyzeFmodeImage(input = {}) {
   }
 
   if (response.status === 401) {
-    return friendlyResult('needs_valid_token', '当前平台 token 无效或已过期，请换成有效的 vocToken / sessionToken / fmodeToken 后重试。', {
-      summary: { imageCount: images.length, model: provider.model },
+    return friendlyResult('needs_valid_token', 'token 鉴权没过（无效/过期/类型不对），这是**可恢复**问题，不代表功能用不了、也不是没钱。优先从 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`（`sk-`）用 `FMODE_API_KEY=sk-…` 传入重试；仍不行再换有效 vocToken / sessionToken。', {
+      summary: { imageCount: images.length, model: provider.model, errorKind: 'auth', recoverable: true },
       data: { model: provider.model, imageCount: images.length }
     });
   }
@@ -216,7 +216,11 @@ function resolveFmodeToken(input = {}) {
     process.env.DOUBAO_VISION_TOKEN,
     process.env.VIDEO_ANALYSIS_TOKEN,
     process.env.TIHAO_SESSION_TOKEN,
-    readVocToken(input)
+    readVocToken(input),
+    // 兜底：NewAPI（fmode-api）的 sk- 计费 token——它就是 Claude Code 的
+    // ANTHROPIC_AUTH_TOKEN（~/.claude/settings.json 的 env），api.fmode.cn 直接认。
+    // 默认装完技能即用，避免「明明配了 SK 却判缺 token」的死循环。
+    readNewApiToken(input)
   ]);
 }
 
@@ -371,12 +375,12 @@ function buildAssistantMessage({ analysis, provider, images, files }) {
 function buildMissingTokenMessage(paymentUrl, recharge = {}) {
   const packageUrl = recharge.recommendedPackageUrl || recharge.workshopUrl || paymentUrl;
   return [
-    '还没有检测到可用于 Fmode 图片分析的平台 token，暂时不能调用 Doubao vision 模型。',
+    '还没读到可用于 Fmode 图片分析的计费 token，暂时不能调用 vision 模型——这是**配置/读取**问题，不是余额不足，也不代表这个功能用不了。',
     '',
-    `开通/充值链接：${paymentUrl}`,
-    `套餐入口：${packageUrl}`,
+    '这把计费 token 就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`（`sk-` 开头），通常配在用户级 `~/.claude/settings.json` 的 `env` 里（`ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`）。',
+    '请优先取出它，用 `FMODE_API_KEY=sk-…`（或入参 `newapiToken`/`fmodeToken`）传给本工具重试；也可写进当前工作区 `.env.local`。',
     '',
-    '开通后，可把平台 token 配置到当前工作区 `.env.local`，字段可用 `VOC_TOKEN`、`FMODE_TOKEN` 或 `TIHAO_SESSION_TOKEN`；也可以在工具参数中传入 `vocToken` / `sessionToken` / `fmodeToken`。',
+    `（仅当确认是 402 余额不足时才充值：${paymentUrl}，套餐入口：${packageUrl}）`,
     '',
     '系统只会把 token 用作接口鉴权，不会在聊天、报告、日志或输出文件里回显。'
   ].join('\n');

package/mcp/src/providers/voc-gateway.js

@@ -139,15 +139,25 @@ async function requestJson(url, token, { method = 'GET', body, retries = 3 } = {
   throw lastError;
 }
 
-async function callSocialGateway({ proxyPath, method = 'GET', query = {}, body, token, baseUrl, retries = 3 } = {}) {
+// 优先用 newapi 的 sk- token 发请求；若该 token 鉴权失败（kind === 'auth'，例如服务端
+// 尚未迁移 / 该号未入仓 / token 未被接受）且提供了回退 token（平台 sessionToken），自动用
+// 回退 token 重试一次。402（余额不足）/403（无权限）不回退。
+async function callSocialGateway({ proxyPath, method = 'GET', query = {}, body, token, fallbackToken, baseUrl, retries = 3 } = {}) {
   const root = resolveSocialRoot(baseUrl);
   const url = buildGatewayUrl(root, proxyPath, query);
   const upper = String(method || 'GET').toUpperCase();
-  return requestJson(url, token, {
+  const requestOptions = {
     method: upper,
     body: upper === 'GET' ? undefined : body,
     retries
-  });
+  };
+  try {
+    return await requestJson(url, token, requestOptions);
+  } catch (error) {
+    const canFallback = fallbackToken && fallbackToken !== token && error && error.kind === 'auth';
+    if (!canFallback) throw error;
+    return requestJson(url, fallbackToken, requestOptions);
+  }
 }
 
 module.exports = {

package/mcp/src/server.js

@@ -735,7 +735,7 @@ function createServer() {
       description: [
         'Invoke any VOC social forwarding interface and return the upstream data.',
         'Provide a catalog id (preferred) or a rawPath + method for unlisted interfaces, plus a params object assembled from the interface doc.',
-        'Requires an r: session token (not an sk- AIGate key). Input/parameter errors, upstream instability, auth, and billing are reported distinctly and are never disguised as \u201cno data / category unsupported\u201d.'
+        'Prefer the NewAPI (fmode-api) sk- billing token; if it is missing or unauthorized, automatically falls back to an r: session token. Input/parameter errors, upstream instability, auth, and billing are reported distinctly and are never disguised as \u201cno data / category unsupported\u201d.'
       ].join(' '),
       inputSchema: {
         id: z.string().optional().describe('Catalog interface id, e.g. douyin.search_general.'),
@@ -747,6 +747,9 @@ function createServer() {
         body: z.object({}).passthrough().optional().describe('Optional explicit request body.'),
         retries: z.number().int().min(0).max(8).optional(),
         baseUrl: z.string().optional(),
+        newapiToken: z.string().optional().describe('Preferred NewAPI (fmode-api) sk- billing token. Used only for this run and never echoed back.'),
+        newApiToken: z.string().optional().describe('Alias of newapiToken.'),
+        fmodeApiKey: z.string().optional().describe('Alias of newapiToken.'),
         vocToken: z.string().optional().describe('Optional VOC social r: session token. Used only for this run and never echoed back.'),
         token: z.string().optional().describe('Alias of vocToken. Never echoed back.'),
         douyinToken: z.string().optional(),

package/mcp/src/tools/voc-api-catalog-run.js

@@ -1,4 +1,4 @@
-const { readVocToken } = require('../core/credentials');
+const { readVocToken, readNewApiToken } = require('../core/credentials');
 const {
   listEndpoints,
   findEndpoint,
@@ -11,8 +11,10 @@ const { callSocialGateway, redactSecret } = require('../providers/voc-gateway');
 const {
   buildVocRechargeInfo,
   buildMissingTokenMessage,
-  buildRechargeRequiredMessage,
-  buildWrongTokenTypeMessage
+  buildMissingNewApiTokenMessage,
+  buildFmodeApiRechargeUrl,
+  buildFmodeApiRechargeMessage,
+  buildPermissionDeniedMessage
 } = require('../core/payment-links');
 const { okResult, errorResult } = require('../core/result-envelope');
 
@@ -95,7 +97,7 @@ async function getVocApiDoc(input = {}) {
     JSON.stringify(template, null, 2),
     '```',
     '',
-    'token 用从充值/开通页复制的、以 r: 开头的会话 token（不要用 sk- 开头的 AIGate Key）。'
+    'token 优先用 NewAPI（fmode-api）的 sk- token（计费已迁移）；没有 sk- 时回退用充值/开通页复制的、以 r: 开头的会话 token。'
   ].filter(line => line !== '');
   return okResult({
     assistantMessage: lines.join('\n'),
@@ -156,34 +158,28 @@ async function callVocApi(input = {}) {
   }
   if (endpoint) endpoint = hydrateEndpoint(endpoint);
 
-  const token = readVocToken(input);
+  // 计费优先走 NewAPI（fmode-api）的 sk- token；该 token 鉴权失败（含「未入仓」类报错）时
+  // 自动回退平台 sessionToken 重试。注意：以前因为 sk- 直接请求会命中「入仓」错误，这里曾经
+  // 直接拒绝 sk- token；现在改为「优先 sk-、鉴权失败再回退 sessionToken」，并对外只给友好提示。
+  const explicitNewApi = readNewApiToken(input);
+  const vocToken = readVocToken(input);
+  // 兼容用户把 sk- 直接填进 VOC_TOKEN 的情况：该槽里若是 sk-，也当作 newapi token。
+  const skFromVocToken = isSkToken(vocToken) ? vocToken : '';
+  const newapiToken = explicitNewApi || skFromVocToken;
+  const sessionToken = isSkToken(vocToken) ? '' : vocToken;
+  const token = newapiToken || sessionToken;
+  const fallbackToken = (newapiToken && sessionToken && newapiToken !== sessionToken) ? sessionToken : '';
   if (!token) {
     const recharge = await buildVocRechargeInfo();
     return {
       status: 'needs_token',
-      assistantMessage: buildMissingTokenMessage(recharge.paymentUrl, recharge, { platformLabel: '社交平台' }),
-      summary: { endpoint: endpoint?.id || rawPath },
+      assistantMessage: buildMissingNewApiTokenMessage(recharge.paymentUrl, recharge, { platformLabel: '社交平台' }),
+      summary: { endpoint: endpoint?.id || rawPath, errorKind: 'missing_token', recoverable: true },
       data: { recharge },
       files: [],
       nextActions: [
-        `打开充值/开通链接：${recharge.paymentUrl}`,
-        '配置以 r: 开头的会话 token 后重新调用'
-      ],
-      warnings: [],
-      errors: []
-    };
-  }
-  if (isSkToken(token)) {
-    const recharge = await buildVocRechargeInfo();
-    return {
-      status: 'needs_valid_token',
-      assistantMessage: buildWrongTokenTypeMessage(recharge.paymentUrl, recharge, { platformLabel: '社交平台' }),
-      summary: { endpoint: endpoint?.id || rawPath, tokenType: 'sk-' },
-      data: { recharge },
-      files: [],
-      nextActions: [
-        '从充值/开通页复制以 r: 开头的会话 token（不是 sk- 开头的 AIGate API Key）',
-        `打开充值/开通链接：${recharge.paymentUrl}`
+        '从 ~/.claude/settings.json 取 env.ANTHROPIC_AUTH_TOKEN（sk-），用 FMODE_API_KEY=sk-… 或入参 newapiToken 传入后重新调用',
+        '仍不行再回退以 r: 开头的会话 token；仅当确认是 402 余额不足时才打开充值链接'
       ],
       warnings: [],
       errors: []
@@ -228,6 +224,7 @@ async function callVocApi(input = {}) {
       query,
       body,
       token,
+      fallbackToken,
       baseUrl: input.baseUrl,
       retries: Number.isFinite(input.retries) ? input.retries : 3
     });
@@ -248,33 +245,53 @@ async function callVocApi(input = {}) {
     const safeMessage = redactSecret(error && error.message ? error.message : 'request failed');
 
     if (kind === 'auth') {
-      const recharge = await buildVocRechargeInfo({ token });
+      // sk- 与 sessionToken（若有）都未通过校验。不把底层「未入仓」/鉴权报错甩给用户，只给友好提示。
+      const recharge = await buildVocRechargeInfo({ token: sessionToken || token });
       return {
         status: 'needs_valid_token',
         assistantMessage: [
-          '当前 VOC-AI 数据服务 token 没有通过校验，暂时不能调用该接口。',
+          '当前 token 没有通过校验，暂时不能调用该接口——这是 token 缺失/无效/失效的**可恢复**问题，不是关键词/类目/参数问题，也不代表这个功能用不了、更不是余额不足。',
           '',
-          '这是 token 无效或类型不对，不是关键词/类目/参数问题：需要从充值/开通页复制的、以 r: 开头的会话 token（不要用 sk- 开头的 AIGate API Key）。',
+          '优先自救：NewAPI（fmode-api）计费用的 `sk-` 就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`（在 `~/.claude/settings.json` 的 `env` 里）。请取出它（确认 `sk-` 开头、`ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`），用 `FMODE_API_KEY=sk-…` 或入参 `newapiToken` 传入后重试。',
           '',
-          `请打开充值/开通链接：${recharge.paymentUrl}`
+          '若 `sk-` 仍校验不过，再回退以 `r:` 开头的会话 token。',
+          '',
+          `（仅当确认是 402 余额不足时才需充值：${recharge.paymentUrl}）`
         ].join('\n'),
-        summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus },
+        summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus, recoverable: true },
         data: { recharge },
         files: [],
-        nextActions: [`打开充值/开通链接：${recharge.paymentUrl}`, '配置以 r: 开头的 session token 后重试'],
+        nextActions: [
+          '从 ~/.claude/settings.json 取 env.ANTHROPIC_AUTH_TOKEN（sk-），用 FMODE_API_KEY=sk-… 或入参 newapiToken 传入后重试',
+          '仍不行再回退以 r: 开头的 session token；仅当确认是 402 余额不足时才打开充值链接'
+        ],
         warnings: [],
         errors: []
       };
     }
     if (kind === 'billing') {
-      const recharge = await buildVocRechargeInfo({ token });
+      // 402：NewAPI（fmode-api）余额不足，跳转 fmode-api 余额充值弹窗。
+      const fmodeApiRechargeUrl = buildFmodeApiRechargeUrl();
       return {
         status: 'needs_recharge',
-        assistantMessage: buildRechargeRequiredMessage(recharge.paymentUrl, recharge, { platformLabel: '社交平台' }),
+        assistantMessage: buildFmodeApiRechargeMessage(fmodeApiRechargeUrl, { platformLabel: '社交平台' }),
         summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus },
-        data: { recharge },
+        data: { recharge: { paymentUrl: fmodeApiRechargeUrl, kind: 'fmode-api' } },
+        files: [],
+        nextActions: [`打开充值链接补充余额：${fmodeApiRechargeUrl}`],
+        warnings: [],
+        errors: []
+      };
+    }
+    if (kind === 'permission') {
+      // 403：用户被禁用/无权限，区别于余额不足，不引导充值。
+      return {
+        status: 'needs_permission',
+        assistantMessage: buildPermissionDeniedMessage({ platformLabel: '社交平台' }),
+        summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus },
+        data: {},
         files: [],
-        nextActions: [`打开充值链接补充额度：${recharge.paymentUrl}`],
+        nextActions: ['联系服务方确认账号状态或接口权限后重试'],
         warnings: [],
         errors: []
       };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "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": {

package/scripts/smoke-mcp.js

@@ -304,13 +304,13 @@ async function main() {
     const apiCallSentinel = 'sk-SMOKE_WRONG_TOKEN_TYPE';
     const apiCallResult = await client.callTool({
       name: 'voc_api_call',
-      arguments: { id: 'douyin.search_general', params: { keyword: '律师' }, vocToken: apiCallSentinel }
+      arguments: { id: 'douyin.search_general', params: { keyword: '律师' }, newapiToken: apiCallSentinel, vocToken: 'r:SMOKE_INVALID_SESSION_TOKEN' }
     });
     const apiCallStructured = apiCallResult.structuredContent || {};
     if (apiCallStructured.status !== 'needs_valid_token') {
-      throw new Error(`Expected voc_api_call to reject sk- token as needs_valid_token, got: ${JSON.stringify(apiCallStructured)}`);
+      throw new Error(`Expected voc_api_call to map invalid sk-/r: tokens to needs_valid_token (token problem, not 余额不足), got: ${JSON.stringify(apiCallStructured)}`);
     }
-    if (JSON.stringify(apiCallStructured).includes(apiCallSentinel)) {
+    if (JSON.stringify(apiCallStructured).includes(apiCallSentinel) || JSON.stringify(apiCallStructured).includes('r:SMOKE_INVALID_SESSION_TOKEN')) {
       throw new Error('voc_api_call leaked the request-scoped token');
     }
 

package/skill-package-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.17",
+  "version": "0.3.22",
   "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.",
   "plugin": "voc-intelligence",
   "skills": [

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

@@ -33,23 +33,37 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 4. `voc_api_call` 用真实关键词调用；翻页/拉评论时把上一次返回里的 cursor / id 透传进下一次调用。
 5. 用返回数据继续后续分析（可交给 voc-issue-pool、voc-content-plan 等技能）。
 
-## Token
+## Token（计费已迁移 NewAPI）
 
-采集需要从充值/开通页复制的、以 `r:` 开头的会话 token（session token）。
-**不要**用 `~/.claude/voc-credentials.json` 里 `sk-` 开头的 AIGate API Key —— 后端不认它，会被工具直接判为 `needs_valid_token`。
+请求头统一 `Authorization: Bearer ${token}`，**优先用 NewAPI（fmode-api）的 `sk-` token**。
+
+> **这把 `sk-` 计费 token 是什么、从哪来**：它就是 **Claude Code 自己的 `ANTHROPIC_AUTH_TOKEN`**——配在用户级 **`~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`**（`sk-` 开头，且 `ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`）。Claude Code 用户**装完技能即用，无需任何额外配置**：工具会自动从这里（以及进程环境）读到它。所以 newapi（fmode-api）≠ 某个要单独开通的东西，它用的就是你正在用的这把 fmode key。
+
+- 取值优先级：入参 `newapiToken`/`fmodeApiKey` → `.env.local` / 环境变量 `FMODE_API_KEY`·`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey` → `~/.fmode/config.json` 的 `newapiToken`/`fmodeApiToken` → **`~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`（Claude Code 默认入口，`sk-` 开头）**。
+- `sk-` 鉴权失败（401，含「未入仓」类报错）且存在 `r:` 开头的会话 token 时，工具会**自动回退**用 `r:` sessionToken 走原 apig 接口重试一次（过渡期：服务端未迁完 / 该号未入仓）。此回退是**正常**的原始付费路径，不是出故障。
+- 兼容：若把 `sk-` 直接填进 `VOC_TOKEN`，也会被当作 NewAPI token 使用。
+- token **绝不回显**；底层鉴权/入仓原始报错不甩给用户，只给友好提示。
+
+> **缺 token / token 无效时该怎么自救（重要，别进死循环）**：这是**可恢复**状态，不是「技能用不了」。先确认 `~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN` 是否为 `sk-` 开头的 fmode key；若工具仍报缺 token，把它取出来用 `FMODE_API_KEY=sk-…`（或入参 `newapiToken`）传给工具再调一次。**不要**因为提示里出现充值/付费链接就让用户去点充值——**只有真正 `402 余额不足` 才需要充值**，缺 token 只是没读到这把 SK 而已。
+
+> 错误码（401/402/403 等）的完整对照、真实报文样例与处理纪律见 **`references/error-codes.md`**。
 
 ## 禁止事项（护栏）
 
 - 禁止把**入参/参数错误**（`needs_input`）误报成「采集不到数据 / 该关键词没结果 / 类目不支持」。参数错就如实说参数错，并用 `voc_api_doc` 核对后重试。
 - 禁止把**上游不稳定**（`upstream_unstable`，如 5xx / 连接超时 / fetch failed）误报成「关键词问题 / 类目不支持 / 余额不足」。如实说明是上游接口波动，稍后重试。
 - 禁止把 **token 无效/类型不对**（`needs_valid_token`）误报成「余额不足」或「类目不支持」。
+- 禁止把**缺 token / token 无效**（`needs_token` / `needs_valid_token`）误报成「这个技能用不了 / 功能不可用」——它是**可恢复**的：SK 就在 `~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`，取出来用 `FMODE_API_KEY=sk-…` 传入重试即可，别因此放弃或去点充值。
 - 禁止输出「某行业不可用 / 系统只支持某类目」这类结论——**任何行业、任何关键词都能采集**，前提只是 token 类型正确且有额度。
 - 失败时禁止退回 web search / yt-dlp / ffmpeg / 让用户手动传媒体文件来「绕过」采集。
 
-## 状态码含义
+## 状态码含义（详表见 `references/error-codes.md`）
 
 - `ok`：调用成功，`data.result` 是上游返回数据。
-- `needs_token` / `needs_valid_token`：没配置 token，或 token 类型不对（sk-）。提示配置 `r:` token。
-- `needs_recharge`：额度不足，提示充值。
+- `needs_token`：没读到任何 token（**可恢复，不是没钱、不是功能用不了**）——优先去 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`（`sk-`）用 `FMODE_API_KEY=sk-…` 传入重试。`needs_valid_token`：token 缺失/失效/无效（HTTP 401）——**不是没钱**，提示配置有效 `sk-`（或回退 `r:`）token。
+- `needs_recharge`：**仅 HTTP 402（余额不足）**，提示充值，跳 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`。
+- `needs_permission`：**HTTP 403（账号禁用/无权限）**，**≠ 余额不足**，不引导充值，提示联系服务方确认权限。
 - `needs_input`：必填参数缺失或参数错误（不是类目/余额问题）。
-- `upstream_unstable`：上游接口报错或波动，稍后重试。
+- `upstream_unstable`：上游接口报错或波动（5xx / fetch failed），稍后重试。
+
+> ⚠️ 不要把 **403/401** 一律说成「余额不足」。只有 **402** 才是真的没钱要充值；403 是权限、401 是 token 问题。

package/skills/voc-api-catalog/references/error-codes.md

@@ -0,0 +1,73 @@
+# VOC 社交数据采集 · 错误码速查
+
+> 给 Agent 按需查阅。**核心纪律：不是所有报错都是「余额不足」，也不是所有报错都代表「功能用不了」。** 只有 **HTTP 402** 才提示充值；
+> **401 = token 问题**（缺失/失效/类型不对），**403 = 账号禁用/无权限**，都**不是没钱**，不要引导充值。
+> **缺 token / 401 是可恢复的**：NewAPI 计费用的 `sk-` 就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`（在 `~/.claude/settings.json` 的 `env` 里），取出来用 `FMODE_API_KEY=sk-…` 传入重试即可，**别当成「这个技能不能用」而放弃或去点充值**。
+
+适用范围：`voc_api_call` / `voc_api_doc`（voc-social 通用转发网关 `https://server.fmode.cn/api/voc-social/<proxyPath>`）。
+
+## 一、总览表（HTTP 状态 → 含义 → 工具返回 → 给客户的话术 → Agent 动作）
+
+| HTTP | 后端 `mess` 样例 | 判定 kind | 工具 status | 给客户 Agent 的话术 | Agent 该做什么 |
+|------|------------------|-----------|-------------|----------------------|----------------|
+| 200 | —（`{"code":200,"data":{...}}`） | — | `ok` | 正常返回 | 直接用 `data.result` |
+| 401 | `Invalid NewAPI token` / `Missing NewAPI token` / `请输入API_KEY或用户sessionToken` / `当前用户不存在，无使用权限` | `auth` | `needs_valid_token`（无任何 token 时 `needs_token`） | 「token 缺失/失效/类型不对，**不是没钱、也不是关键词/类目问题，更不是功能用不了**」 | **先**从 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`（`sk-`），用 `FMODE_API_KEY=sk-…` 传入重试；不行再回退 `r:` sessionToken |
+| 402 | `余额不足` / `额度不足` | `billing` | `needs_recharge` | 「余额不足，请充值」 | 给充值链接 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`（自动打开余额弹窗） |
+| 403 | `用户禁用` / `无权限` / `permission`（**不含**余额/开通关键词） | `permission` | `needs_permission` | 「账号被禁用或没有该接口权限，**≠ 余额不足**」 | 联系服务方确认账号状态/接口权限，**不要**引导充值 |
+| 403 | 含 `未开通` / `没开通` / `余额` / `额度` / `insufficient` / `balance` | `billing` | `needs_recharge` | 「需开通/充值后使用」 | 给充值/开通链接 |
+| 400 / 422 | `参数` / `入参` / `keyword` / `bad request` | `request` | `needs_input` | 「参数有误，**不是没数据/不是类目不支持**」 | 用 `voc_api_doc` 核对参数后重试 |
+| 5xx / 连接失败 | `fetch failed` / 超时 / `500` | `upstream` | `upstream_unstable` | 「上游接口波动」 | 稍后重试，不要误报成关键词/余额问题 |
+
+## 二、真实报文样例（实打抓取）
+
+```text
+# 有效 sk- token（NewAPI / fmode-api）
+HTTP 200  {"code":200,"data":{"code":0,"data":{...}}}
+
+# sk- token 无效/写错
+HTTP 401  {"code":401,"mess":"Invalid NewAPI token"}
+
+# 发的是旧版 Parse sessionToken（r:），后端已迁 NewAPI 计费
+HTTP 401  {"code":401,"mess":"Missing NewAPI token"}
+
+# 完全没带 Authorization
+HTTP 401  {"code":401,"mess":"请输入API_KEY或用户sessionToken"}
+
+# token 对应的用户不存在
+HTTP 401  {"code":401,"mess":"当前用户不存在，无使用权限"}
+
+# 余额不足（NewAPI 计费额度用尽）—— 仅此情形才引导充值
+HTTP 402  {"code":402,"mess":"余额不足"}
+
+# 用户被禁用 / 无该接口权限（区别于余额不足）
+HTTP 403  {"code":403,"mess":"用户禁用或无权限"}
+```
+
+## 三、Token 优先级与回退（避开「入仓」错误）
+
+计费已迁移到 **NewAPI（fmode-api）**，请求头统一 `Authorization: Bearer ${token}`：
+
+> **这把 `sk-` 是什么**：它就是 **Claude Code 自己的 `ANTHROPIC_AUTH_TOKEN`**（配在 `~/.claude/settings.json` 的 `env`，`sk-` 开头，`ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`）。所以 Claude Code 用户**装完即用、零额外配置**，工具会自动从 settings.json / 进程环境读到它。newapi（fmode-api）不是要单独开通的东西，就是你正在用的这把 fmode key。
+
+1. **优先**用 NewAPI 的 `sk-` token，取值优先级：
+   入参 `newapiToken/fmodeApiKey` → `.env.local` / 环境变量 `FMODE_API_KEY`/`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey` → `~/.fmode/config.json` 的 `newapiToken/fmodeApiToken` → **`~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`（Claude Code 默认入口）**。
+   - 兼容历史：若 `VOC_TOKEN` 槽里填的就是 `sk-`，也当作 NewAPI token 使用。
+   - 若工具报 `needs_token`/`needs_valid_token`：先去 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`，用 `FMODE_API_KEY=sk-…` 传入重试——**这是缺 token 的标准自救，不是去点充值**。
+2. 若 `sk-` token **鉴权失败（kind=auth / 401，含「未入仓」类报错）** 且存在平台 `r:` sessionToken，**自动回退** sessionToken 重试一次。这正是规避「用户拿 token 请求时遇到入仓错误」的方式——不再因为 token 是 `sk-` 就直接拒绝。
+3. **402（余额不足）/ 403（无权限）不回退**——它们是终态，按上表处理。
+4. 底层「未入仓」/鉴权原始报错**不甩给用户**，对外只给上表的友好提示。
+
+## 四、判定规则摘要（`classifyApiError`）
+
+判定顺序（命中即返回）：
+
+1. 文案含「用户/账号信息不存在、未登录、登录失效、请输入…token、sessiontoken」→ `auth`
+2. `status===401` 或文案含「invalid token / 无效token / 未授权 / unauthorized」→ `auth`
+3. `status===402` 或文案含「余额不足 / 额度不足 / 未开通 / 开通…权限 / insufficient / balance / quota / payment / 充值」→ `billing`
+4. `status===403` **且**含余额/开通类关键词 → `billing`
+5. 文案含「参数 / 入参 / keyword / 关键词 / bad request」或 `status∈{400,422}` → `request`
+6. `status>=500` → `upstream`
+7. `status===403` 或文案含「permission / 权限 / 无权限」→ `permission`
+8. 其它 → `upstream`
+
+> 注意第 4 与第 7 条的区别：**带「余额/开通」关键词的 403 才当充值**；**纯权限 403 一律 `permission`，不充值**。