@vocmarket/voc-skill 0.3.21 → 0.3.22

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

@@ -90,9 +90,34 @@ function readXiaohongshuToken(input = {}) {
   return readVocToken(input);
 }
 
+// NewAPI（fmode-api）计费 token，以 sk- 开头。
+// 计费已迁移到 NewAPI：优先用它发请求，鉴权失败再回退平台 sessionToken。
+// 取值优先级：显式入参 → .env.local / 环境变量 → ~/.claude/voc-credentials.json 的 fmodeApiKey。
+function readNewApiToken(input = {}) {
+  const workspaceEnv = readEnvLocalFiles();
+  const claudeCreds = readJsonMaybe(path.join(os.homedir(), '.claude', 'voc-credentials.json'));
+  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,
+  ]);
+}
+
 module.exports = {
   readVocToken,
   readXiaohongshuToken,
+  readNewApiToken,
   readEnvFileMaybe,
   readWorkspaceEnvLocal,
   envLocalCandidates

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,32 @@ function buildWrongTokenTypeMessage(paymentUrl, recharge = {}, options = {}) {
   ].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,
@@ -132,5 +161,8 @@ module.exports = {
   buildVocWorkshopUrl,
   buildMissingTokenMessage,
   buildRechargeRequiredMessage,
-  buildWrongTokenTypeMessage
+  buildWrongTokenTypeMessage,
+  buildFmodeApiRechargeUrl,
+  buildFmodeApiRechargeMessage,
+  buildPermissionDeniedMessage
 };

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,9 @@ const { callSocialGateway, redactSecret } = require('../providers/voc-gateway');
 const {
   buildVocRechargeInfo,
   buildMissingTokenMessage,
-  buildRechargeRequiredMessage,
-  buildWrongTokenTypeMessage
+  buildFmodeApiRechargeUrl,
+  buildFmodeApiRechargeMessage,
+  buildPermissionDeniedMessage
 } = require('../core/payment-links');
 const { okResult, errorResult } = require('../core/result-envelope');
 
@@ -95,7 +96,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,7 +157,17 @@ 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 {
@@ -167,23 +178,7 @@ async function callVocApi(input = {}) {
       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}`
+        '配置 NewAPI 的 fmode-api token（sk-）或以 r: 开头的会话 token 后重新调用'
       ],
       warnings: [],
       errors: []
@@ -228,6 +223,7 @@ async function callVocApi(input = {}) {
       query,
       body,
       token,
+      fallbackToken,
       baseUrl: input.baseUrl,
       retries: Number.isFinite(input.retries) ? input.retries : 3
     });
@@ -248,33 +244,48 @@ 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 无效或类型不对，不是关键词/类目/参数问题：需要从充值/开通页复制的、以 r: 开头的会话 token（不要用 sk- 开头的 AIGate API Key）。',
+          '这是 token 缺失/无效/失效，不是关键词/类目/参数问题：请配置有效的 NewAPI（fmode-api）token（sk-）或以 r: 开头的会话 token。',
           '',
-          `请打开充值/开通链接：${recharge.paymentUrl}`
+          `如需开通/充值，请打开：${recharge.paymentUrl}`
         ].join('\n'),
         summary: { endpoint: endpoint?.id || proxyPath, errorKind: kind, httpStatus },
         data: { recharge },
         files: [],
-        nextActions: [`打开充值/开通链接：${recharge.paymentUrl}`, '配置以 r: 开头的 session token 后重试'],
+        nextActions: [`打开充值/开通链接：${recharge.paymentUrl}`, '配置 NewAPI token（sk-）或以 r: 开头的 session token 后重试'],
         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.22",
   "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,10 +33,16 @@ 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**：
+
+- 取值优先级：入参 `newapiToken`/`fmodeApiKey` → `.env.local` / 环境变量 `FMODE_API_KEY`·`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey`（`sk-` 开头）。
+- `sk-` 鉴权失败（401，含「未入仓」类报错）且存在 `r:` 开头的会话 token 时，工具会**自动回退**用 `r:` sessionToken 重试一次（过渡期：服务端未迁完 / 该号未入仓）。
+- 兼容：若把 `sk-` 直接填进 `VOC_TOKEN`，也会被当作 NewAPI token 使用。
+- token **绝不回显**；底层鉴权/入仓原始报错不甩给用户，只给友好提示。
+
+> 错误码（401/402/403 等）的完整对照、真实报文样例与处理纪律见 **`references/error-codes.md`**。
 
 ## 禁止事项（护栏）
 
@@ -46,10 +52,13 @@ VOC 后端是一个**通用转发网关**（`https://server.fmode.cn/api/voc-soc
 - 禁止输出「某行业不可用 / 系统只支持某类目」这类结论——**任何行业、任何关键词都能采集**，前提只是 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。`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,68 @@
+# VOC 社交数据采集 · 错误码速查
+
+> 给 Agent 按需查阅。**核心纪律：不是所有报错都是「余额不足」。** 只有 **HTTP 402** 才提示充值；
+> **401 = token 问题**（缺失/失效/类型不对），**403 = 账号禁用/无权限**，都**不是没钱**，不要引导充值。
+
+适用范围：`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 缺失/失效/类型不对，**不是没钱、也不是关键词/类目问题**」 | 配置有效的 NewAPI `sk-` token（或回退 `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}`：
+
+1. **优先**用 NewAPI 的 `sk-` token（取值：入参 `newapiToken/fmodeApiKey` → `.env.local` / 环境变量 `FMODE_API_KEY`/`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey`）。
+   - 兼容历史：若 `VOC_TOKEN` 槽里填的就是 `sk-`，也当作 NewAPI 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`，不充值**。