@vocmarket/voc-skill 0.3.24 → 0.3.26

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

package/bin/claude-voc.js

@@ -124,6 +124,40 @@ function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
+// Remove an existing install dir, resilient to Windows locks.
+// A normal recursive remove fails with EPERM/EBUSY when the directory is held
+// by a running process — most commonly a Claude Code session / VSCode terminal
+// whose current working directory is inside the plugin dir. Such a directory
+// can still be *renamed* even though it cannot be deleted, so on failure we move
+// it aside and install fresh, then best-effort delete the moved-aside copy.
+function removeDirResilient(targetDir) {
+  try {
+    fs.rmSync(targetDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+    return;
+  } catch (err) {
+    if (!['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY'].includes(err.code)) throw err;
+    const asidePath = `${targetDir}.held-${Date.now()}`;
+    try {
+      fs.renameSync(targetDir, asidePath);
+    } catch (renameErr) {
+      const e = new Error(
+        `无法更新技能目录（被占用）：${targetDir}\n` +
+        `原因：该目录正被一个运行中的进程占用（常见是该工作区里仍开着的 Claude Code 会话或 VSCode 终端，其当前目录在该插件目录内）。\n` +
+        `请关闭占用该目录的 Claude Code 会话/终端后重试安装。\n` +
+        `(${err.code}: ${err.message}; rename fallback failed: ${renameErr.code || renameErr.message})`
+      );
+      e.code = err.code;
+      throw e;
+    }
+    console.log(`Existing skill directory was in use; moved aside to: ${asidePath}`);
+    try {
+      fs.rmSync(asidePath, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    } catch (cleanupErr) {
+      console.log(`Note: moved-aside copy is still in use and was not deleted. Remove it later: ${asidePath}`);
+    }
+  }
+}
+
 function isInside(parentDir, childDir) {
   const relative = path.relative(path.resolve(parentDir), path.resolve(childDir));
   return relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative));
@@ -264,8 +298,8 @@ function workspaceTrendSkillText(options) {
     '',
     `- 用户要求${options.platform}趋势情报、内容趋势、评论分析、真实采集、live采集或社媒 VOC 时，必须运行本技能包的工具或 MCP，不要只凭经验回答。`,
     '- 用户说“live / 真实采集 / 进入 live / 实时采集 / 抓真实数据”时，必须运行 live 模式工具。不要回复“我不能实时抓取外部数据”。本技能包已经提供本地 VOC 采集入口。',
-    '- live 模式返回 `needs_token`、`needs_recharge` 或 `needs_valid_token` 时，必须把工具输出里的 `assistantMessage` 原样转述给用户，尤其不能省略充值/开通链接。',
-    '- 如果工具输出里有 `nextActions`，至少转述其中带 `apig-pay` 的充值链接。',
+    '- live 模式返回 `needs_token`、`needs_recharge` 或 `needs_valid_token` 时，必须把工具输出里的 `assistantMessage` 原样转述给用户。`needs_token` 是缺 token、不是没钱：先引导自救（读 `~/.claude/settings.json` 的 `sk-` token），不要劝充值。',
+    '- 如果工具输出里有 `nextActions`，转述其中的自救/充值链接（以工具实际返回为准，不要写死某个链接）。',
     '- 第一轮只说“初步判断 / 机会假设 / 待校准”，不要说成最终结论。',
     '- 后续用户说“保留、不要、更偏、这个不准”等反馈时，运行偏好更新命令沉淀记忆。',
     '',
@@ -273,8 +307,8 @@ function workspaceTrendSkillText(options) {
     '',
     '- If the user asks for live collection, real collection, or entering live mode, run the local VOC tool in live mode.',
     '- Do not answer that you cannot fetch external data. The local VOC tool is the approved collection entry.',
-    '- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user and keep the payment URL visible.',
-    '- The payment URL must be shown when there is no token or insufficient balance: `https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF`',
+    '- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user verbatim.',
+    '- `needs_token` is recoverable: an `sk-` fmode key (Claude Code `ANTHROPIC_AUTH_TOKEN`) lets collection run — guide self-rescue first, do not push recharge. Only a real `402` needs recharge. 完整口径见下方「充值 / 计费口径」。',
     '',
     '## sample 命令',
     '',
@@ -296,19 +330,11 @@ function workspaceTrendSkillText(options) {
     `node ${quotedPath(preferenceUpdater)} --message "<用户反馈原文>" --memory ${quotedPath(defaultMemoryPath)} --result-prefix ${options.resultPrefix}`,
     '```',
     '',
-    '## 充值链接口径',
-    '',
-    '没有 token 或余额不足时，用户必须看到：',
-    '',
-    '```text',
-    'https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF',
-    '```',
+    '## 充值 / 计费口径（简版；完整对照见 voc-api-catalog 技能的「错误码速查」references/error-codes.md）',
     '',
-    '套餐入口可作为补充：',
-    '',
-    '```text',
-    'https://app.fmode.cn/dev/apig-pay/#/workshop/99',
-    '```',
+    '- 缺 token（`needs_token`）= 可恢复、不是没钱：先自救读 `~/.claude/settings.json` 的 `sk-` fmode key（或 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`），用 `FMODE_API_KEY=sk-…` 重试，不要劝充值。',
+    '- 只有真 `402 余额不足` 才充值，入口 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`（NewAPI/fmode-api 计费）；`401`=token、`403`=权限，都不充值。`apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF` 仅限 `r:` 会话 token 余额补充。',
+    '- 实际充值/自救链接以工具返回的 `assistantMessage` / `nextActions` 为准，不要写死。',
     ''
   ].join('\n');
 }
@@ -328,53 +354,6 @@ function workspaceSkillText(targetDir) {
     liveOutput: 'outputs/claude-code-xhs-live',
     resultPrefix: 'XHS_PREF_RESULT'
   });
-  const trendRunner = path.join(targetDir, 'mcp', 'src', 'tools', 'xiaohongshu-trend-run.js');
-  const preferenceUpdater = path.join(targetDir, 'mcp', 'src', 'tools', 'xiaohongshu-preference-update.js');
-  const profilePath = path.join(targetDir, 'memory-templates', 'xiaohongshu-trend-profile.json');
-  const defaultMemoryPath = path.join(WORKSPACE_ROOT, 'outputs', 'claude-code-xhs-memory', 'xiaohongshu-trend-memory.json');
-
-  return [
-    '---',
-    'name: xiaohongshu-trend-intelligence',
-    'description: Build Xiaohongshu trend intelligence reports from industry direction, audience, keywords, notes, and comments. Use when the user asks for 小红书趋势情报、行业趋势、女性客户消费决策、设计元素洞察、家装全屋定制趋势、内容选题 or social VOC analysis.',
-    'allowed-tools: Read Write Bash(node *)',
-    '---',
-    '',
-    '# 小红书趋势情报官',
-    '',
-    '你是面向业务用户的“小红书趋势情报官”。用户要的是第一轮样本观察、机会假设和待确认问题，不是技术日志。',
-    '',
-    '## 必须执行',
-    '',
-    '- 当用户要求做小红书趋势情报、行业趋势、女性客户消费决策、家装全屋定制趋势、设计元素洞察或内容选题时，优先运行下面的 sample 工具命令。',
-    '- 不要只凭经验回答，也不要只返回文件路径。',
-    '- 工具输出里会有 `assistantMessage`，请把它的正文直接发给用户。',
-    '- 第一轮只能说“初步判断 / 机会假设 / 待校准”，不要说成最终结论。',
-    '- 后续用户说“保留、不要、更偏、这个不准”等反馈时，运行偏好更新命令沉淀记忆。',
-    '',
-    '## sample 趋势情报命令',
-    '',
-    '```bash',
-    `node ${quotedPath(trendRunner)} --collection-mode sample --profile ${quotedPath(profilePath)} --output "outputs/claude-code-xhs-sample" --assistant-message-only`,
-    '```',
-    '',
-    '运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。',
-    '',
-    '## 偏好更新命令',
-    '',
-    '```bash',
-    `node ${quotedPath(preferenceUpdater)} --message "<用户反馈原文>" --memory ${quotedPath(defaultMemoryPath)} --result-prefix XHS_PREF_RESULT`,
-    '```',
-    '',
-    '## 推荐用户启动话术',
-    '',
-    '```text',
-    '帮我做一份家装全屋定制行业的小红书趋势情报。',
-    '先用演示样例跑通流程，不要真实采集。',
-    '在聊天里给我第一轮样本观察和待确认问题。',
-    '```',
-    ''
-  ].join('\n');
 }
 
 function workspaceDouyinSkillText(targetDir) {
@@ -392,53 +371,6 @@ function workspaceDouyinSkillText(targetDir) {
     liveOutput: 'outputs/claude-code-douyin-live',
     resultPrefix: 'DOUYIN_PREF_RESULT'
   });
-  const trendRunner = path.join(targetDir, 'mcp', 'src', 'tools', 'douyin-trend-run.js');
-  const preferenceUpdater = path.join(targetDir, 'mcp', 'src', 'tools', 'douyin-preference-update.js');
-  const profilePath = path.join(targetDir, 'memory-templates', 'douyin-trend-profile.json');
-  const defaultMemoryPath = path.join(WORKSPACE_ROOT, 'outputs', 'claude-code-douyin-memory', 'douyin-trend-memory.json');
-
-  return [
-    '---',
-    'name: douyin-trend-intelligence',
-    'description: Build Douyin trend intelligence reports from industry direction, audience, keywords, videos, and comments. Use when the user asks for 抖音趋势情报、视频评论、口播选题、短视频开头、内容趋势 or social VOC analysis.',
-    'allowed-tools: Read Write Bash(node *)',
-    '---',
-    '',
-    '# 抖音趋势情报官',
-    '',
-    '你是面向业务用户的“抖音趋势情报官”。用户要的是第一轮样本观察、机会假设和待确认问题，不是技术日志。',
-    '',
-    '## 必须执行',
-    '',
-    '- 当用户要求做抖音趋势情报、视频评论、口播选题、短视频开头或内容趋势时，优先运行下面的 sample 工具命令。',
-    '- 不要只凭经验回答，也不要只返回文件路径。',
-    '- 工具输出里会有 `assistantMessage`，请把它的正文直接发给用户。',
-    '- 第一轮只能说“初步判断 / 机会假设 / 待校准”，不要说成最终结论。',
-    '- 后续用户说“保留、不要、更偏、这个不准”等反馈时，运行偏好更新命令沉淀记忆。',
-    '',
-    '## sample 趋势情报命令',
-    '',
-    '```bash',
-    `node ${quotedPath(trendRunner)} --collection-mode sample --profile ${quotedPath(profilePath)} --output "outputs/claude-code-douyin-sample" --assistant-message-only`,
-    '```',
-    '',
-    '运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。',
-    '',
-    '## 偏好更新命令',
-    '',
-    '```bash',
-    `node ${quotedPath(preferenceUpdater)} --message "<用户反馈原文>" --memory ${quotedPath(defaultMemoryPath)} --result-prefix DOUYIN_PREF_RESULT`,
-    '```',
-    '',
-    '## 推荐用户启动话术',
-    '',
-    '```text',
-    '帮我做一份家装全屋定制行业的抖音趋势情报。',
-    '先用演示样例跑通流程，不要真实采集。',
-    '在聊天里给我第一轮样本观察和待确认问题。',
-    '```',
-    ''
-  ].join('\n');
 }
 
 function workspaceProblemDeepDiveSkillText(targetDir) {
@@ -468,19 +400,19 @@ function workspaceProblemDeepDiveSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --assistant-message-only`,
+    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --assistant-message-only`,
     '```',
     '',
     '## 带记忆的多轮迭代',
     '',
     '```bash',
-    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --memory "outputs/voc-problem-memory.json" --feedback "老板不想做直播带看，更想先改评论区回复和方案说明" --blocked-actions "直播带看" --preferred-actions "评论区回复,方案说明" --assistant-message-only`,
+    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --memory "outputs/voc-problem-memory.json" --feedback "老板不想做直播带看，更想先改评论区回复和方案说明" --blocked-actions "直播带看" --preferred-actions "评论区回复,方案说明" --assistant-message-only`,
     '```',
     '',
     '自然语言反馈也可以直接传入 `feedback`，工具会尝试自动提取偏好和屏蔽动作：',
     '',
     '```bash',
-    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --project "示例品牌A" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --feedback "这个品牌不想做直播带看，更想先改评论区回复和方案说明" --assistant-message-only`,
+    `node ${quotedPath(deepDiveRunner)} --issue "怎么选" --project "示例品牌A" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --feedback "这个品牌不想做直播带看，更想先改评论区回复和方案说明" --assistant-message-only`,
     '```',
     '',
     '运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。',
@@ -513,13 +445,13 @@ function workspaceIssuePoolSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(issuePoolRunner)} --project "示例品牌A" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --evidence "第一次买不知道怎么选，怕踩雷。,价格有点高，不确定值不值。,咨询的时候没人理。" --assistant-message-only`,
+    `node ${quotedPath(issuePoolRunner)} --project "示例品牌A" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --evidence "第一次买不知道怎么选，怕踩雷。,价格有点高，不确定值不值。,咨询的时候没人理。" --assistant-message-only`,
     '```',
     '',
     '带报告文件：',
     '',
     '```bash',
-    `node ${quotedPath(issuePoolRunner)} --project "示例品牌A" --industry "家居定制" --report "outputs/douyin-trend-report.md" --assistant-message-only`,
+    `node ${quotedPath(issuePoolRunner)} --project "示例品牌A" --industry "<你的行业>" --report "outputs/douyin-trend-report.md" --assistant-message-only`,
     '```',
     '',
     '运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。',
@@ -545,7 +477,7 @@ function workspaceContentPlanSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "家居定制" --issues "第一次买怕踩雷;觉得价格贵;怕质量不稳定" --assistant-message-only`,
+    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "<你的行业>" --issues "第一次买怕踩雷;觉得价格贵;怕质量不稳定" --assistant-message-only`,
     '```',
     '',
     '运行后把正文直接发给用户，不要展示 JSON。',
@@ -571,7 +503,7 @@ function workspaceSpeakingScriptSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "家居定制" --topic "第一次买怎么选不踩雷" --user-issue "第一次买怕选错" --evidence "第一次买不知道怎么选，怕踩雷" --assistant-message-only`,
+    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "<你的行业>" --topic "第一次买怎么选不踩雷" --user-issue "第一次买怕选错" --evidence "第一次买不知道怎么选，怕踩雷" --assistant-message-only`,
     '```',
     '',
     '改稿：',
@@ -603,7 +535,7 @@ function workspaceCompetitorMapSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(runner)} --brand "示例品牌A" --city "本地" --category "家居定制" --assistant-message-only`,
+    `node ${quotedPath(runner)} --brand "示例品牌A" --city "本地" --category "<你的品类>" --assistant-message-only`,
     '```',
     '',
     '运行后把正文直接发给用户，不要展示 JSON。',
@@ -627,7 +559,7 @@ function workspaceBusinessWorkflowSkillText(targetDir) {
     '## 命令',
     '',
     '```bash',
-    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "家居定制" --platform douyin --collection-mode sample --keywords "家居定制怎么选,第一次买怎么对比,售后" --assistant-message-only`,
+    `node ${quotedPath(runner)} --brand "示例品牌A" --industry "<你的行业>" --platform douyin --collection-mode sample --keywords "<你的品类>怎么选,第一次买怎么对比,售后" --assistant-message-only`,
     '```',
     '',
     '真实采集时把 `--collection-mode sample` 换成 `--collection-mode live`。如果工具提示没有 token、余额不足或没有样本，直接把工具正文发给用户，并保留充值/降级建议。',
@@ -717,15 +649,15 @@ function printNextSteps(targetDir) {
   }
   console.log('');
   console.log('Try this prompt in Claude Code:');
-  console.log('  帮我看一下家装全屋定制最近用户在关心什么，并告诉我先改哪里、下周发什么。');
+  console.log('  帮我看一下 {你的行业/品类} 最近用户在关心什么，并告诉我先改哪里、下周发什么。');
   console.log('');
   console.log('Or try:');
-  console.log('  帮我做一份家装全屋定制行业的小红书趋势情报。');
+  console.log('  帮我做一份 {你的行业/品类} 的小红书趋势情报。');
   console.log('  先用演示样例跑通流程，不要真实采集。');
   console.log('  在聊天里给我第一轮样本观察和待确认问题。');
   console.log('');
   console.log('Or try:');
-  console.log('  帮我做一份家装全屋定制行业的抖音趋势情报。');
+  console.log('  帮我做一份 {你的行业/品类} 的抖音趋势情报。');
   console.log('  先用演示样例跑通流程，不要真实采集。');
   console.log('  在聊天里给我第一轮样本观察和待确认问题。');
   console.log('');
@@ -739,7 +671,7 @@ function install(opts) {
       if (!canOverwriteTarget(opts.target, opts)) {
         throw new Error(`Target already exists. Use --force to overwrite custom target: ${opts.target}`);
       }
-      fs.rmSync(opts.target, { recursive: true, force: true });
+      removeDirResilient(opts.target);
     }
     ensureDir(opts.target);
     const copied = copyDirRecursive(SOURCE_ROOT, opts.target);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocmarket/voc-skill",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "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/skill-package-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-voc-intelligence",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "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/douyin-trend-intelligence/SKILL.md

@@ -13,7 +13,7 @@ allowed-tools: Read Write Bash(node *)
 - 用户要求抖音趋势情报、视频评论、口播选题、短视频开头、内容趋势或社媒 VOC 时，必须运行本技能包的工具或 MCP，不要只凭经验回答。
 - 用户说“live / 真实采集 / 进入 live / 实时采集 / 抓真实数据”时，必须运行 live 模式工具。不要回复“我不能实时抓取外部数据”。本技能包已经提供本地 VOC 采集入口。
 - live 模式返回 `needs_token`、`needs_recharge` 或 `needs_valid_token` 时，必须把工具输出里的 `assistantMessage` 原样转述给用户，尤其不能省略充值/开通链接。
-- 如果工具输出里有 `nextActions`，至少转述其中带 `apig-pay` 的充值链接。
+- 如果工具输出里有 `nextActions`，转述其中的自救/充值链接（以工具实际返回为准，不要写死某个链接）。
 - 第一轮只说“初步判断 / 机会假设 / 待校准”，不要说成最终结论。
 - 后续用户说“保留、不要、更偏、这个不准”等反馈时，运行偏好更新命令沉淀记忆。
 
@@ -21,8 +21,8 @@ allowed-tools: Read Write Bash(node *)
 
 - If the user asks for live collection, real collection, or entering live mode, run the local VOC tool in live mode.
 - Do not answer that you cannot fetch external data. The local VOC tool is the approved collection entry.
-- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user and keep the payment URL visible.
-- The payment URL must be shown when there is no token or insufficient balance: `https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF`
+- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user verbatim, including whatever self-rescue/recharge link the tool returns.
+- `needs_token` is recoverable: an `sk-` fmode newapi key (Claude Code's `ANTHROPIC_AUTH_TOKEN` in `~/.claude/settings.json`, or `~/.fmode/config.json` / `~/.claude/voc-credentials.json`) lets collection run — guide self-rescue first, do not push recharge. Only a real `402` needs recharge. 完整口径见下方「充值 / 计费口径」。
 
 ## 禁止事项（Hard Guardrails）
 
@@ -30,14 +30,14 @@ live 采集失败时，严禁做以下任何一件事：
 
 - 严禁退回/降级到联网搜索（web search）、`yt-dlp`、`ffmpeg`、手动让用户上传 mp4，或任何“绕过 VOC 接口”的抓取方式。本技能包的 VOC 本地采集是唯一批准的真实数据入口。
 - 严禁输出“VOC 只支持某些类目”“律师/某赛道不可用”“系统设计上有类目限制”这类结论。这是错误结论：任何关键词（律师、法律、医美、教育、专业服务等）都能采集，与类目无关。
-- live 失败的真正原因只可能是这几类：token 无效或类型不对（需要 `r:` 开头的会话 token，而不是 `sk-` 开头的 AIGate API Key）、未开通或额度不足、上游接口抖动（5xx，需重试）。必须如实把工具返回的 `assistantMessage` 转述给用户，不要自行编造原因。
+- live 失败的真正原因只可能是这几类：缺 token 或 token 无效（**`sk-` 开头的 fmode newapi key 即可采集**——它就是 `~/.claude/settings.json` 的 `ANTHROPIC_AUTH_TOKEN`，也可来自 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`；缺 token 先按提示自救读取，不要劝充值）、额度不足（真 402 才充值）、上游接口抖动（5xx，需重试）。必须如实把工具返回的 `assistantMessage` 转述给用户，不要自行编造原因。
 - 只有在工具明确返回 `needs_keyword_fix` 时才允许调整关键词；返回 `needs_valid_token` / `needs_token` / `needs_recharge` 时不要换关键词，要转述充值/开通链接。
 
 English (same rules):
 
 - On live failure, NEVER fall back to web search, `yt-dlp`, `ffmpeg`, or asking the user to upload an mp4. The local VOC tool is the only approved real-data path.
 - NEVER conclude that VOC is limited to certain categories or that a vertical (e.g. lawyers) is unsupported. Any keyword works; this is never a category problem.
-- The only real causes are: invalid/wrong-type token (need an `r:` session token, not an `sk-` AIGate key), not activated / no balance, or upstream 5xx jitter (retry). Relay the tool's `assistantMessage` verbatim instead of inventing a reason.
+- The only real causes are: missing/invalid token (an `sk-` fmode newapi key — Claude Code's `ANTHROPIC_AUTH_TOKEN` — is valid for collection; self-rescue by reading it first, don't push recharge), insufficient balance (only a real 402 needs recharge), or upstream 5xx jitter (retry). Relay the tool's `assistantMessage` verbatim instead of inventing a reason.
 - Only adjust keywords when the tool returns `needs_keyword_fix`. For `needs_valid_token` / `needs_token` / `needs_recharge`, do not change keywords — surface the payment/activation link.
 
 ## Douyin Live Quick Repair
@@ -71,24 +71,18 @@ node "<插件目录>/mcp/src/tools/douyin-trend-run.js" --collection-mode live -
 
 运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。
 
-## 充值链接口径
+## 充值 / 计费口径（简版；完整对照见 voc-api-catalog 技能的「错误码速查」references/error-codes.md）
 
-没有 token 或余额不足时，用户必须看到：
-
-```text
-https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
-```
-
-套餐入口可作为补充：
-
-```text
-https://app.fmode.cn/dev/apig-pay/#/workshop/99
-```
+- 缺 token（`needs_token`）= 可恢复、不是没钱：先自救读 `~/.claude/settings.json` 的 `sk-` fmode key（或 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`），用 `FMODE_API_KEY=sk-…` 重试，不要劝充值。
+- 只有真 `402 余额不足` 才充值，入口 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`（NewAPI/fmode-api 计费）；`401`=token、`403`=权限，都不充值。`apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF` 仅限 `r:` 会话 token 余额补充。
+- 实际充值/自救链接以工具返回的 `assistantMessage` / `nextActions` 为准，不要写死。
 
 ## 推荐用户启动话术
 
+> 通用模板：把 `{你的行业/品类}` 替换成用户真实所在的行业或品类，不要内置任何特定行业。
+
 ```text
-帮我做一份家装全屋定制行业的抖音趋势情报。
+帮我做一份 {你的行业/品类} 的抖音趋势情报。
 先用演示样例跑通流程，不要真实采集。
 在聊天里给我第一轮样本观察和待确认问题。
 ```

package/skills/douyin-trend-intelligence/references/live-mode.md

@@ -2,10 +2,8 @@
 
 ## 默认规则
 
-- 先检查 token
 - 样本量保持小
-- 没 token 时给充值链接，不要暴露 403
-- 余额不足时也给充值链接，不要暴露底层错误
+- 计费/充值口径走简版：缺 token 先自救（读 `~/.claude/settings.json` 的 `sk-` fmode key 重试），不要直接甩充值链接、不要暴露 401/403；只有真 `402` 才给充值链接 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`。**完整口径（401/402/403 对照、回退、apig-pay `r:` 补充链）见 voc-api-catalog 技能的「错误码速查」references/error-codes.md**
 - 用户只需要看到“怎么继续”
 
 ## 推荐默认参数

package/skills/fmode-image-analysis/SKILL.md

@@ -5,6 +5,8 @@ description: Analyze images, screenshots, posters, UI captures, charts, product
 
 # Fmode Image Analysis
 
+> 图像/视频分析**推荐改用 `fmode-vision` 技能包**（功能更完整：单轮/多轮聚焦分析、视频帧分析、批量处理）。本技能是 Claude Code 内置 MCP 工具 `fmode_image_analysis` 的轻量图片识别入口/回退，适合“当前对话里已有图片、需要快速识图”的场景；需要更精细或视频/批量处理时，引导用户/Agent 改用 `fmode-vision`。
+
 ## Core Rule
 
 Use MCP tool `fmode_image_analysis` for image understanding. Do not ask the user to install a VS Code image-recognition plugin when this installed Fmode tool can handle the image.
@@ -15,7 +17,7 @@ Default to:
 
 - `baseUrl`: `https://api.fmode.cn`
 - `path`: `v1/chat/completions`
-- `model`: `doubao-seed-2-0-pro-260215`
+- `model`: `doubao-seed-2-0-pro-260215`（默认/推荐，**不强制使用单一模型**——可按可用权限改用其他多模态模型，如 `gpt-4o` 等；通过工具入参 `model` 覆盖即可）
 
 Auth and billing should use the configured platform user token. Never hardcode or echo tokens.
 
@@ -84,11 +86,11 @@ Environment variables:
 - `DOUBAO_VISION_TOKEN`
 - `VIDEO_ANALYSIS_TOKEN`
 
-Friendly states:
+Friendly states (aligned with the fmode-api billing 口径 — self-rescue first, recharge only on a real 402):
 
-- Missing token: return `needs_token` with the platform open/recharge link and `errors=[]`.
+- Missing token (`needs_token`): this is not a balance problem — guide self-rescue first. Read the `sk-` fmode key from `~/.claude/settings.json` (`env.ANTHROPIC_AUTH_TOKEN`), `~/.fmode/config.json`, or `~/.claude/voc-credentials.json`. Do NOT push a recharge link here.
 - Invalid token: return `needs_valid_token` and ask for a valid platform token.
-- Not opened or quota exhausted: return `needs_recharge` with the open/recharge link and `errors=[]`.
+- Quota exhausted / real 402: return `needs_recharge` with the fmode-api recharge link `https://app.fmode.cn/dev/studio/?balance=fmodeapi` and `errors=[]`.
 - Success: return `ok` with the analysis in chat.
 
 Do not expose raw upstream errors, `Authorization`, bearer tokens, session tokens, stack traces, or model keys.

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

@@ -4,7 +4,7 @@
 > **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>`）。
+适用范围：`voc_api_call` / `voc_api_doc`，**两条通道同源**——社媒网关 `https://server.fmode.cn/api/voc-social/<proxyPath>`（`channel=social`，默认）与创作者数据网关 `https://server.fmode.cn/api/voc-e-commerce/<proxyPath>`（`channel=ecommerce`）的鉴权、计费、错误码语义完全一致，下表对两者通用。本速查也是各 trend / 采集技能充值计费口径的**单一权威来源**，技能里只放简版摘要并指回这里。
 
 ## 一、总览表（HTTP 状态 → 含义 → 工具返回 → 给客户的话术 → Agent 动作）
 
@@ -55,6 +55,12 @@ HTTP 403  {"code":403,"mess":"用户禁用或无权限"}
    - 若工具报 `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（无权限）不回退**——它们是终态，按上表处理。
+
+> **充值入口分两条链（按实际走哪条计费而定）**：
+> - `sk-` NewAPI / fmode-api 计费链（默认，绝大多数缺额场景）→ `https://app.fmode.cn/dev/studio/?balance=fmodeapi`
+> - `r:` 会话 token 链（仅当走 `r:` sessionToken 回退路径、该 token 余额不足时）→ `https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF`
+>
+> 运行时以工具返回的 `assistantMessage` / `nextActions` 链接为准转述，不要在话术里写死某一条。
 4. 底层「未入仓」/鉴权原始报错**不甩给用户**，对外只给上表的友好提示。
 
 ## 四、判定规则摘要（`classifyApiError`）

package/skills/voc-business-workflow/SKILL.md

@@ -40,7 +40,7 @@ description: Run the full VOC business workflow from natural boss language: coll
 ## 用户可说的话
 
 ```text
-帮我看一下家居定制最近用户在关心什么，并告诉我先改哪里、下周发什么。
+帮我看一下 {你的行业/品类} 最近用户在关心什么，并告诉我先改哪里、下周发什么。
 ```
 
 ```text

package/skills/voc-competitor-map/SKILL.md

@@ -21,13 +21,13 @@ allowed-tools: Read Write Bash(node *)
 ## CLI 命令
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-competitor-map-run.js" --brand "示例品牌A" --city "本地" --category "家居定制" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-competitor-map-run.js" --brand "示例品牌A" --city "本地" --category "<你的品类>" --assistant-message-only
 ```
 
 带竞品名单：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-competitor-map-run.js" --brand "示例品牌A" --city "本地" --category "家居定制" --competitors "竞品A,竞品B,竞品C" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-competitor-map-run.js" --brand "示例品牌A" --city "本地" --category "<你的品类>" --competitors "竞品A,竞品B,竞品C" --assistant-message-only
 ```
 
 ## 输出结构
@@ -48,7 +48,7 @@ node "<插件目录>/mcp/src/tools/voc-competitor-map-run.js" --brand "示例品
 ## 典型用户话术
 
 ```text
-我是做家居定制的，不知道竞品是谁，帮我先做一份竞品图谱。
+我是做 {你的行业/品类} 的，不知道竞品是谁，帮我先做一份竞品图谱。
 ```
 
 ```text

package/skills/voc-content-plan/SKILL.md

@@ -22,7 +22,7 @@ allowed-tools: Read Write Bash(node *)
 ## CLI 命令
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-content-plan-run.js" --brand "示例品牌A" --industry "家居定制" --issues "第一次买怕踩雷;觉得价格贵;怕质量不稳定" --evidence-text "用户评论：第一次买不知道怎么选，怕踩雷；价格有点高，不知道方案值不值。" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-content-plan-run.js" --brand "示例品牌A" --industry "<你的行业>" --issues "第一次买怕踩雷;觉得价格贵;怕质量不稳定" --evidence-text "用户评论：第一次买不知道怎么选，怕踩雷；价格有点高，不知道方案值不值。" --assistant-message-only
 ```
 
 带报告文件：
@@ -34,7 +34,7 @@ node "<插件目录>/mcp/src/tools/voc-content-plan-run.js" --brand "示例品
 多问题示例：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-content-plan-run.js" --brand "示例品牌A" --industry "家居定制" --issues "第一次买怎么选最稳;贵在哪/值在哪;怎么对比才不踩雷;质量怎么判断;哪几种方案更适合;售后怎么兜底;优惠规则怎么讲清楚" --evidence-text "用户评论：第一次买不知道怎么选，怕踩雷；价格有点高，不确定值不值；担心质量和售后。" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-content-plan-run.js" --brand "示例品牌A" --industry "<你的行业>" --issues "第一次买怎么选最稳;贵在哪/值在哪;怎么对比才不踩雷;质量怎么判断;哪几种方案更适合;售后怎么兜底;优惠规则怎么讲清楚" --evidence-text "用户评论：第一次买不知道怎么选，怕踩雷；价格有点高，不确定值不值；担心质量和售后。" --assistant-message-only
 ```
 
 ## 输出结构

package/skills/voc-issue-pool/SKILL.md

@@ -27,19 +27,19 @@ allowed-tools: Read Write Bash(node *)
 - When the user asks for a VOC report around business pain points, first build or request a clean evidence set, then run `voc_issue_pool_run`; only after that should a single top issue be sent to `voc_problem_deep_dive_run`.
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --evidence "第一次买不知道怎么选，怕踩雷。,价格有点高，不确定值不值。,咨询忙起来没人理。" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --evidence "第一次买不知道怎么选，怕踩雷。,价格有点高，不确定值不值。,咨询忙起来没人理。" --assistant-message-only
 ```
 
 带报告文件：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "家居定制" --report "outputs/douyin-trend-report.md" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "<你的行业>" --report "outputs/douyin-trend-report.md" --assistant-message-only
 ```
 
 更新状态：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "家居定制" --resolved-issues "选择门槛/决策" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-issue-pool-run.js" --project "示例品牌A" --industry "<你的行业>" --resolved-issues "选择门槛/决策" --assistant-message-only
 ```
 
 ## 输出结构

package/skills/voc-problem-deep-dive/SKILL.md

@@ -38,19 +38,19 @@ allowed-tools: Read Write Bash(node *)
 - If live collection returns `needs_token`, `needs_recharge`, or `needs_valid_token`, repeat the tool's user-facing `assistantMessage` and do not replace it with a generic strategy suggestion.
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --assistant-message-only
 ```
 
 带记忆的多轮迭代：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --memory "outputs/voc-problem-memory.json" --feedback "老板不想做试用体验，更想先改评论区回复和案例展示" --blocked-actions "试用体验" --preferred-actions "评论区回复,案例展示" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --memory "outputs/voc-problem-memory.json" --feedback "老板不想做试用体验，更想先改评论区回复和案例展示" --blocked-actions "试用体验" --preferred-actions "评论区回复,案例展示" --assistant-message-only
 ```
 
 自然语言反馈也可以直接传入 `feedback`，工具会尝试自动提取偏好和屏蔽动作：
 
 ```bash
-node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --project "示例品牌A" --industry "家居定制" --scenario "线上获客" --audience "意向用户" --feedback "这个品牌不想做试用体验，更想先改评论区回复和案例展示" --assistant-message-only
+node "<插件目录>/mcp/src/tools/voc-problem-deep-dive-run.js" --issue "怎么选" --project "示例品牌A" --industry "<你的行业>" --scenario "线上获客" --audience "意向用户" --feedback "这个品牌不想做试用体验，更想先改评论区回复和案例展示" --assistant-message-only
 ```
 
 如果用户反馈“这个有效”“这个无效”“跑了 7 天有效果/没效果”，要把对应动作传入 `validatedActions` 或 `rejectedActions`，也可以直接放进 `feedback`。工具会沉淀动作验证次数，后续排序会自动提高有效动作、降低无效动作，并说明“为什么优先推荐这些动作”。

package/skills/voc-speaking-script/SKILL.md

@@ -28,7 +28,7 @@ VOC 问题 -> 7 天内容计划 -> 选择一条选题 -> 口播脚本共创 ->
 ```bash
 node "<插件目录>/mcp/src/tools/voc-speaking-script-run.js" \
   --brand "示例品牌A" \
-  --industry "家居定制" \
+  --industry "<你的行业>" \
   --topic "第一次买怎么选不踩雷" \
   --user-issue "第一次买怕选错" \
   --evidence "第一次买不知道怎么选，怕踩雷" \

package/skills/xiaohongshu-trend-intelligence/SKILL.md

@@ -13,7 +13,7 @@ allowed-tools: Read Write Bash(node *)
 - 用户要求小红书趋势情报、行业趋势、内容选题、销售话术或社媒 VOC 时，必须运行本技能包的工具或 MCP，不要只凭经验回答。
 - 用户说“live / 真实采集 / 进入 live / 实时采集 / 抓真实数据”时，必须运行 live 模式工具。不要回复“我不能实时抓取外部数据”。本技能包已经提供本地 VOC 采集入口。
 - live 模式返回 `needs_token`、`needs_recharge` 或 `needs_valid_token` 时，必须把工具输出里的 `assistantMessage` 原样转述给用户，尤其不能省略充值/开通链接。
-- 如果工具输出里有 `nextActions`，至少转述其中带 `apig-pay` 的充值链接。
+- 如果工具输出里有 `nextActions`，转述其中的自救/充值链接（以工具实际返回为准，不要写死某个链接）。
 - 第一轮只说“初步判断 / 机会假设 / 待校准”，不要说成最终结论。
 - 后续用户说“保留、不要、更偏、这个不准”等反馈时，运行偏好更新命令沉淀记忆。
 
@@ -21,8 +21,8 @@ allowed-tools: Read Write Bash(node *)
 
 - If the user asks for live collection, real collection, or entering live mode, run the local VOC tool in live mode.
 - Do not answer that you cannot fetch external data. The local VOC tool is the approved collection entry.
-- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user and keep the payment URL visible.
-- The payment URL must be shown when there is no token or insufficient balance: `https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF`
+- If the tool returns `needs_token`, `needs_recharge`, or `needs_valid_token`, paste its `assistantMessage` to the user verbatim, including whatever self-rescue/recharge link the tool returns.
+- `needs_token` is recoverable: an `sk-` fmode newapi key (Claude Code's `ANTHROPIC_AUTH_TOKEN` in `~/.claude/settings.json`, or `~/.fmode/config.json` / `~/.claude/voc-credentials.json`) lets collection run — guide self-rescue first, do not push recharge. Only a real `402` needs recharge. 完整口径见下方「充值 / 计费口径」。
 
 ## 禁止事项（Hard Guardrails）
 
@@ -30,14 +30,14 @@ live 采集失败时，严禁做以下任何一件事：
 
 - 严禁退回/降级到联网搜索（web search）、`yt-dlp`、`ffmpeg`、手动让用户上传图片/视频，或任何“绕过 VOC 接口”的抓取方式。本技能包的 VOC 本地采集是唯一批准的真实数据入口。
 - 严禁输出“VOC 只支持某些类目”“律师/某赛道不可用”“系统设计上有类目限制”这类结论。这是错误结论：任何关键词（律师、法律、医美、教育、专业服务等）都能采集，与类目无关。
-- live 失败的真正原因只可能是这几类：token 无效或类型不对（需要 `r:` 开头的会话 token，而不是 `sk-` 开头的 AIGate API Key）、未开通或额度不足、上游接口抖动（5xx，需重试）。必须如实把工具返回的 `assistantMessage` 转述给用户，不要自行编造原因。
+- live 失败的真正原因只可能是这几类：缺 token 或 token 无效（**`sk-` 开头的 fmode newapi key 即可采集**——它就是 `~/.claude/settings.json` 的 `ANTHROPIC_AUTH_TOKEN`，也可来自 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`；缺 token 先按提示自救读取，不要劝充值）、额度不足（真 402 才充值）、上游接口抖动（5xx，需重试）。必须如实把工具返回的 `assistantMessage` 转述给用户，不要自行编造原因。
 - 只有在工具明确返回 `needs_keyword_fix` 时才允许调整关键词；返回 `needs_valid_token` / `needs_token` / `needs_recharge` 时不要换关键词，要转述充值/开通链接。
 
 English (same rules):
 
 - On live failure, NEVER fall back to web search, `yt-dlp`, `ffmpeg`, or asking the user to upload media. The local VOC tool is the only approved real-data path.
 - NEVER conclude that VOC is limited to certain categories or that a vertical (e.g. lawyers) is unsupported. Any keyword works; this is never a category problem.
-- The only real causes are: invalid/wrong-type token (need an `r:` session token, not an `sk-` AIGate key), not activated / no balance, or upstream 5xx jitter (retry). Relay the tool's `assistantMessage` verbatim instead of inventing a reason.
+- The only real causes are: missing/invalid token (an `sk-` fmode newapi key — Claude Code's `ANTHROPIC_AUTH_TOKEN` — is valid for collection; self-rescue by reading it first, don't push recharge), insufficient balance (only a real 402 needs recharge), or upstream 5xx jitter (retry). Relay the tool's `assistantMessage` verbatim instead of inventing a reason.
 - Only adjust keywords when the tool returns `needs_keyword_fix`. For `needs_valid_token` / `needs_token` / `needs_recharge`, do not change keywords — surface the payment/activation link.
 
 ## sample 命令
@@ -54,24 +54,18 @@ node "<插件目录>/mcp/src/tools/xiaohongshu-trend-run.js" --collection-mode l
 
 运行后把命令输出正文直接发给用户。不要展示 JSON、summary、data、files 或调试日志。
 
-## 充值链接口径
+## 充值 / 计费口径（简版；完整对照见 voc-api-catalog 技能的「错误码速查」references/error-codes.md）
 
-没有 token 或余额不足时，用户必须看到：
-
-```text
-https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
-```
-
-套餐入口可作为补充：
-
-```text
-https://app.fmode.cn/dev/apig-pay/#/workshop/99
-```
+- 缺 token（`needs_token`）= 可恢复、不是没钱：先自救读 `~/.claude/settings.json` 的 `sk-` fmode key（或 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`），用 `FMODE_API_KEY=sk-…` 重试，不要劝充值。
+- 只有真 `402 余额不足` 才充值，入口 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`（NewAPI/fmode-api 计费）；`401`=token、`403`=权限，都不充值。`apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF` 仅限 `r:` 会话 token 余额补充。
+- 实际充值/自救链接以工具返回的 `assistantMessage` / `nextActions` 为准，不要写死。
 
 ## 推荐用户启动话术
 
+> 通用模板：把 `{你的行业/品类}` 替换成用户真实所在的行业或品类，不要内置任何特定行业。
+
 ```text
-帮我做一份家装全屋定制行业的小红书趋势情报。
+帮我做一份 {你的行业/品类} 的小红书趋势情报。
 先用演示样例跑通流程，不要真实采集。
 在聊天里给我第一轮样本观察和待确认问题。
 ```

package/skills/xiaohongshu-trend-intelligence/references/live-mode.md

@@ -25,10 +25,10 @@ live 模式默认保持小规模：
 
 系统也会尝试从本机环境读取 token。
 
-如果没有 token，或者余额不足，不要直接把底层报错甩给用户，应该返回：
+不要直接把底层报错甩给用户：
 
-- 充值链接
-- 下一步操作
+- 缺 token：先自救——读 `~/.claude/settings.json` 的 `sk-` fmode key（或 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`）用 `FMODE_API_KEY=sk-…` 重试，不要直接给充值链接。
+- 只有真正余额不足（`402`）才给充值链接 + 下一步操作。完整口径见下方「充值入口」与 voc-api-catalog 的「错误码速查」。
 
 不要把 `403`、授权失败文案、原始响应体直接暴露给用户。
 
@@ -41,23 +41,11 @@ live 模式默认保持小规模：
 
 保留 `xsec_token`，否则网页端可能打不开。
 
-## 充值入口
+## 充值入口（仅 402 余额不足时，简版）
 
-常见充值入口示例：
-
-```text
-https://app.fmode.cn/dev/apig-pay/#/workshop
-https://app.fmode.cn/dev/apig-pay/#/workshop/19-9
-https://app.fmode.cn/dev/apig-pay/#/workshop/99
-https://app.fmode.cn/dev/apig-pay/#/workshop/299
-https://app.fmode.cn/dev/apig-pay/#/workshop/699
-```
-
-如果只是 VOC 数据服务余额，也可以用：
-
-```text
-https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
-```
+- `sk-` NewAPI/fmode-api 计费链（默认）：`https://app.fmode.cn/dev/studio/?balance=fmodeapi`
+- `apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF` 仅限 `r:` 会话 token 余额补充。
+- 完整 401/402/403 对照与回退逻辑见 **voc-api-catalog 技能的「错误码速查」references/error-codes.md**（单一权威来源）。
 
 ## 结论