@vocmarket/voc-skill 0.3.32 → 0.3.34

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

package/README.md

@@ -12,6 +12,8 @@
 - 单点 VOC 深挖：适合把一个具体问题转成老板能执行的经营动作、内容选题和 7 天验证计划。
 - VOC 内容选题：适合把用户问题转成 7 天短视频选题、口播脚本、镜头建议和验证指标。
 - VOC 口播脚本共创：适合把一条 VOC 选题继续打磨成 60 秒稿、30 秒稿、提词器版，并支持多轮改稿和定稿记忆。
+- VOC 接口目录：适合按平台、关键词和通道查找 1,344 个已登记接口，并读取参数后完成通用调用。
+- VOC 成本控制：适合执行前比较经济版/标准版/完整版，检查余额与预算，执行后查看接口频次和额度消耗。
 
 这套技能包不覆盖创始人故事、品牌自传或老板个人 IP 长文。口播脚本要做，但必须来自 VOC 用户问题、竞品评论差异、问题池 Top 问题或单点深挖动作。
 
@@ -36,6 +38,9 @@
 - “这个有效，后面优先按这个方向来”
 - “帮我看看顾客关心什么，告诉我先改哪里、下周发什么”
 - “跑一遍完整 VOC 经营闭环”
+- “这个复杂任务预计要花多少钱，经济版和完整版差多少”
+- “查一下这份报告每个接口调用了多少次、消耗了多少额度”
+- “查商品详情或评论，先从接口清单里找合适的接口”
 
 ## 能交付什么
 
@@ -111,6 +116,8 @@ npx --yes @vocmarket/voc-skill@latest workspace --smoke
 .claude/skills/voc-competitor-map/SKILL.md
 .claude/skills/voc-business-workflow/SKILL.md
 .claude/skills/fmode-image-analysis/SKILL.md
+.claude/skills/voc-api-catalog/SKILL.md
+.claude/skills/voc-cost-controller/SKILL.md
 .claude/plugins/voc-intelligence
 ```
 
@@ -188,6 +195,8 @@ npx --yes @vocmarket/voc-skill@latest install --smoke
 - `voc-competitor-map`
 - `voc-business-workflow`
 - `fmode-image-analysis`
+- `voc-api-catalog`
+- `voc-cost-controller`
 
 MCP 工具：
 
@@ -204,6 +213,12 @@ MCP 工具：
 - `voc_content_plan_run`
 - `voc_competitor_map_run`
 - `voc_speaking_script_run`
+- `voc_api_search`
+- `voc_api_doc`
+- `voc_api_call`
+- `voc_billing_query`
+- `voc_cost_estimate`
+- `voc_usage_report`
 
 命令行入口：
 
@@ -215,6 +230,7 @@ claude-voc image --image-path E:\workspace\example\screenshot.png --prompt "识
 npm --prefix claude-code-voc-intelligence run voc:issue-pool
 npm --prefix claude-code-voc-intelligence run voc:deep-dive
 npm --prefix claude-code-voc-intelligence run voc:business-workflow
+npm --prefix claude-code-voc-intelligence run audit:index
 npm --prefix claude-code-voc-intelligence run mcp:smoke
 npm --prefix claude-code-voc-intelligence run smoke:package
 ```
@@ -231,6 +247,9 @@ npm --prefix claude-code-voc-intelligence run smoke:package
 - `docs/live-manual-acceptance-checklist.md`
 - `docs/payment-package-links.md`
 - `docs/context-budget-implementation-plan.md`
+- `docs/voc-cost-metering-and-balance-implementation-spec.md`
+- `skills/voc-api-catalog/references/error-codes.md`
+- `skills/voc-cost-controller/references/workflow-cost-models.md`
 - `skills/voc-content-plan/references/content-framework.md`
 - `skills/voc-content-plan/references/speaking-script-patterns.md`
 - `skills/voc-competitor-map/references/competitor-framework.md`
@@ -271,28 +290,22 @@ sample 模式不需要 token。live 模式需要一把可用的 token——**两
 1. **NewAPI（fmode-api）计费 SK**（`sk-` 开头，优先）：就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`，装好技能包后通常**已经具备**，不必手动再配。读取来源：
    - 本次请求参数 `newapiToken` / `fmodeApiKey`
    - `.env.local` / 环境变量 `FMODE_API_KEY`、`NEWAPI_TOKEN`
+   - `~/.fmode/config.json`（FmodeStudio 保存路径）的 `newapiToken` / `fmodeApiToken` / `fmodeApiKey`
    - `~/.claude/voc-credentials.json` 的 `fmodeApiKey`
-   - `~/.fmode/config.json`（FmodeStudio 保存路径）的 `newapiToken` / `fmodeApiKey`
    - `~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`（`sk-` 开头、且 `ANTHROPIC_BASE_URL` 指向 fmode）
-2. **VOC-AI 数据服务会话 token**（`r:` 开头，回退）：读取来源——本次请求参数、`.env.local` / 环境变量 `VOC_TOKEN`·`VOC_SOCIAL_TOKEN`、`~/.claude/voc-credentials.json` 的 `vocToken`·`token`
+2. **VOC-AI 数据服务会话 token**（`r:` 开头，回退）：读取来源——本次请求参数、显式 `FMODE_SESSION_TOKEN` / `TIHAO_SESSION_TOKEN`、`~/.fmode/config.json` 的 `sessionToken`、`~/.claude/voc-credentials.json` 的 `sessionToken`·`vocToken`·`token`，最后回退 `.env.local` / 环境变量 `VOC_TOKEN`·`VOC_SOCIAL_TOKEN`
 
 同一网关 `server.fmode.cn/api/voc-social` 对上述任一有效 token 都接受 `Bearer`，**`sk-` 不是「类型错误」**。`voc_*_token_check` 与实际采集（`voc_api_call` / `voc_*_trend_run`）口径一致，会识别以上**全部**来源；不必在采集前强制先跑检测。
 
 Claude Code 技能包不读取 `~/.openclaw/voc-credentials.json`。
 
-缺 token 多数是**配置/读取**问题，不是余额不足：应先引导自救（从上述来源读 SK、用 `FMODE_API_KEY` 重试），**只有确认确实是 402 余额不足时**才给充值/开通链接，且不要暴露底层接口 403、权限堆栈或上游响应体。两条链对应**两个不同的充值入口**，不要搭错：
+缺 token 多数是**配置/读取**问题，应先恢复凭证；只有确认确实是 402 余额不足时才进入充值流程。充值入口统一使用运行时生成的 Tokenized Balance 链接：
 
-- **NewAPI（fmode-api）计费 SK**（`sk-` 开头，多数缺 token 场景走这条）→ fmode-api 余额充值：
-
-  ```text
-  https://app.fmode.cn/dev/studio/?balance=fmodeapi
-  ```
-
-- **VOC-AI 数据服务会话 token**（`r:` 开头）→ apig-pay 充值：
+```text
+https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN
+```
 
-  ```text
-  https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
-  ```
+链接由工具按当前用户会话生成，不在文档中固定账号、金额或旧 APIG 参数。用户也可以让 Agent 按报价结果调用现有支付码链路直接生成二维码。
 
 ## 记忆能力
 

package/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: voc-intelligence
+description: 面向经营者的 VOC 用户经营洞察工作台。从社交媒体、电商和海外选品数据中提取用户声音，形成趋势情报、问题池、竞品图谱、单点深挖、7 天内容计划、口播脚本、成本预估和用量账单。用户要看顾客关心什么、先改哪里、下周发什么、查商品价格评论、测算任务成本、查询接口用量或进行样例与真实采集时使用。
+---
+
+# VOC 用户经营洞察
+
+这是一个可从自然语言开始的 VOC 经营工作台，包含趋势情报、问题管理、竞品分析、经营动作、内容计划和口播脚本等子技能，并提供统一的 MCP 数据接口清单。
+
+## 使用规则
+
+- 用户只需描述行业、品类、平台和目标，不要求用户了解 MCP 参数。
+- 用户没有明确要求真实采集时，先使用演示样例；用户明确说真实采集或 live 时，再检查凭证和余额。
+- 首轮输出采用“初步判断、机会假设、待校准”口径，并给出证据和下一步动作。
+- 用户要完整经营闭环时，调用 `voc_business_workflow_run`；要单项任务时，调用对应的趋势、问题池、深挖、竞品、内容或脚本工具。
+- 用户要查商品、价格、评论、销量或其他平台接口时，先用 `voc_api_search` 查清单，再用 `voc_api_doc` 读取参数，最后用 `voc_api_call` 调用；需要跨平台或未登记接口时，按返回的 `channel` 选择通道。
+- 用户要预估复杂任务成本、比较经济版/标准版/完整版或判断余额是否足够时，先调用 `voc_cost_estimate`；需要读取当前余额和服务端价目时使用 `voc_billing_query`。
+- 用户要查询已完成任务的实际调用频次、额度消耗、接口拆分或报告成本时，调用 `voc_usage_report`，并区分用户扣费与平台成本。
+- 采集响应中的多媒体统一下载到任务本地 `assets/` 并写入 `media-manifest.json`；报告只引用本地路径，技能包不向线上 Storage 上传。
+
+## 主要能力
+
+- 小红书和抖音趋势情报，支持样例与小规模真实采集。
+- VOC 问题池、单点问题深挖、竞品图谱和 7 天内容计划。
+- 基于用户声音的口播脚本共创、修改和定稿。
+- 淘宝/天猫、京东、1688、抖音电商等电商数据，以及亚马逊海外选品数据。
+- 通用 VOC 接口目录、跨通道接口调用、执行前成本测算、余额预检和执行后用量报告。
+- 图片、截图、海报、图表和商品图片分析。

package/bin/claude-voc.js

@@ -249,7 +249,6 @@ function shouldCopyEntry(entry) {
 }
 
 function copyDirRecursive(srcDir, destDir) {
-  ensureDir(destDir);
   let count = 0;
   for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
     if (!shouldCopyEntry(entry)) continue;
@@ -258,6 +257,7 @@ function copyDirRecursive(srcDir, destDir) {
     if (entry.isDirectory()) {
       count += copyDirRecursive(src, dest);
     } else if (entry.isFile()) {
+      ensureDir(destDir);
       ensureDir(path.dirname(dest));
       fs.copyFileSync(src, dest);
       count++;
@@ -272,21 +272,15 @@ function assertInstalled(targetDir) {
     'install.js',
     '.claude-plugin/plugin.json',
     '.mcp.json',
-    'skills/xiaohongshu-trend-intelligence/SKILL.md',
-    'skills/douyin-trend-intelligence/SKILL.md',
-    'skills/voc-issue-pool/SKILL.md',
-    'skills/voc-problem-deep-dive/SKILL.md',
-    'skills/voc-content-plan/SKILL.md',
-    'skills/voc-speaking-script/SKILL.md',
-    'skills/voc-competitor-map/SKILL.md',
-    'skills/voc-business-workflow/SKILL.md',
-    'skills/fmode-image-analysis/SKILL.md',
-    'skills/voc-api-catalog/SKILL.md',
     'mcp/src/tools/fmode-image-analysis.js',
     'mcp/src/tools/voc-api-catalog-run.js',
     'mcp/catalog/voc-social-endpoints.json',
     'mcp/src/server.js'
   ];
+  const manifest = readJsonIfExists(path.join(targetDir, 'skill-package-manifest.json'));
+  for (const skillName of manifest.skills || []) {
+    required.push(`skills/${skillName}/SKILL.md`);
+  }
   const missing = required.filter(rel => !fs.existsSync(path.join(targetDir, rel)));
   if (missing.length) {
     throw new Error(`Missing required files in install target: ${missing.join(', ')}`);
@@ -394,13 +388,19 @@ function registerCodexGlobalMcp(targetDir) {
 
 function copyPackagedSkills(targetDir, destinationRoot) {
   const sourceRoot = path.join(targetDir, 'skills');
+  const manifest = readJsonIfExists(path.join(targetDir, 'skill-package-manifest.json'));
+  const skillNames = Array.isArray(manifest.skills) ? manifest.skills : [];
+  if (!skillNames.length) throw new Error('skill-package-manifest.json has no skills to install');
   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);
+  for (const skillName of skillNames) {
+    const source = path.join(sourceRoot, skillName);
+    if (!fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
+      throw new Error(`Manifest skill directory is missing: ${skillName}`);
+    }
+    const destination = path.join(destinationRoot, skillName);
     removeDirResilient(destination);
-    copied += copyDirRecursive(path.join(sourceRoot, entry.name), destination);
+    copied += copyDirRecursive(source, destination);
   }
   return copied;
 }
@@ -487,7 +487,7 @@ function workspaceTrendSkillText(options) {
     '## 充值 / 计费口径（简版；完整对照见 voc-api-catalog 技能的「错误码速查」references/error-codes.md）',
     '',
     '- 缺 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 余额补充。',
+    '- 只有真 `402 余额不足` 才充值；充值入口以工具返回的 Tokenized Balance 链接或二维码支付结果为准。链接格式为 `https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN`，不要在话术中写死账号或旧 APIG 参数。',
     '- 实际充值/自救链接以工具返回的 `assistantMessage` / `nextActions` 为准，不要写死。',
     ''
   ].join('\n');
@@ -726,52 +726,38 @@ function workspaceBusinessWorkflowSkillText(targetDir) {
 }
 
 function writeWorkspaceSkillEntries(targetDir) {
-  const xhsSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'xiaohongshu-trend-intelligence');
-  const douyinSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'douyin-trend-intelligence');
-  const issuePoolSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-issue-pool');
-  const deepDiveSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-problem-deep-dive');
-  const contentPlanSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-content-plan');
-  const speakingScriptSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-speaking-script');
-  const competitorMapSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-competitor-map');
-  const businessWorkflowSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-business-workflow');
-  const fmodeImageSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'fmode-image-analysis');
-  const apiCatalogSkillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', 'voc-api-catalog');
-  ensureDir(xhsSkillDir);
-  ensureDir(douyinSkillDir);
-  ensureDir(issuePoolSkillDir);
-  ensureDir(deepDiveSkillDir);
-  ensureDir(contentPlanSkillDir);
-  ensureDir(speakingScriptSkillDir);
-  ensureDir(competitorMapSkillDir);
-  ensureDir(businessWorkflowSkillDir);
-  ensureDir(fmodeImageSkillDir);
-  ensureDir(apiCatalogSkillDir);
-  fs.writeFileSync(path.join(xhsSkillDir, 'SKILL.md'), workspaceSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(douyinSkillDir, 'SKILL.md'), workspaceDouyinSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(issuePoolSkillDir, 'SKILL.md'), workspaceIssuePoolSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(deepDiveSkillDir, 'SKILL.md'), workspaceProblemDeepDiveSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(contentPlanSkillDir, 'SKILL.md'), workspaceContentPlanSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(speakingScriptSkillDir, 'SKILL.md'), workspaceSpeakingScriptSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(competitorMapSkillDir, 'SKILL.md'), workspaceCompetitorMapSkillText(targetDir), 'utf8');
-  fs.writeFileSync(path.join(businessWorkflowSkillDir, 'SKILL.md'), workspaceBusinessWorkflowSkillText(targetDir), 'utf8');
-  fs.copyFileSync(path.join(targetDir, 'skills', 'fmode-image-analysis', 'SKILL.md'), path.join(fmodeImageSkillDir, 'SKILL.md'));
-  fs.copyFileSync(path.join(targetDir, 'skills', 'voc-api-catalog', 'SKILL.md'), path.join(apiCatalogSkillDir, 'SKILL.md'));
+  const manifest = readJsonIfExists(path.join(targetDir, 'skill-package-manifest.json'));
+  const skillNames = Array.isArray(manifest.skills) ? manifest.skills : [];
+  if (!skillNames.length) throw new Error('skill-package-manifest.json has no skills to expose in workspace');
+  const sourceRoot = path.join(targetDir, 'skills');
+  const writers = {
+    'xiaohongshu-trend-intelligence': () => workspaceSkillText(targetDir),
+    'douyin-trend-intelligence': () => workspaceDouyinSkillText(targetDir),
+    'voc-issue-pool': () => workspaceIssuePoolSkillText(targetDir),
+    'voc-problem-deep-dive': () => workspaceProblemDeepDiveSkillText(targetDir),
+    'voc-content-plan': () => workspaceContentPlanSkillText(targetDir),
+    'voc-speaking-script': () => workspaceSpeakingScriptSkillText(targetDir),
+    'voc-competitor-map': () => workspaceCompetitorMapSkillText(targetDir),
+    'voc-business-workflow': () => workspaceBusinessWorkflowSkillText(targetDir)
+  };
+  for (const skillName of skillNames) {
+    const sourceSkill = path.join(sourceRoot, skillName, 'SKILL.md');
+    if (!fs.existsSync(sourceSkill)) throw new Error(`Manifest skill entry is missing: ${skillName}`);
+    const skillDir = path.join(WORKSPACE_ROOT, '.claude', 'skills', skillName);
+    ensureDir(skillDir);
+    const content = writers[skillName] ? writers[skillName]() : fs.readFileSync(sourceSkill, 'utf8');
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+  }
+  return skillNames;
 }
 
 function writeClaudeWorkspaceActivation(targetDir) {
   writeWorkspaceMcpConfig(targetDir);
-  writeWorkspaceSkillEntries(targetDir);
+  const skillNames = writeWorkspaceSkillEntries(targetDir);
   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');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-problem-deep-dive\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-content-plan\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-speaking-script\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-competitor-map\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-business-workflow\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\fmode-image-analysis\\SKILL.md');
-  console.log('Wrote workspace skill entry: .\\.claude\\skills\\voc-api-catalog\\SKILL.md');
+  for (const skillName of skillNames) {
+    console.log(`Wrote workspace skill entry: .\\.claude\\skills\\${skillName}\\SKILL.md`);
+  }
 }
 
 function writeWorkspaceActivation(targetDir, opts) {

package/docs/capability-map.md

@@ -4,7 +4,7 @@
 
 ## 一句话定位
 
-把小红书、抖音等平台的用户真实声音，转成企业能用的趋势情报、问题优先级、经营动作、内容选题和多轮验证记忆。
+把社媒、国内电商/创作者和海外选品接口中的用户与市场数据，转成企业能用的趋势情报、问题优先级、经营动作、内容选题、成本测算和多轮验证记忆。
 
 ## 用户任务到入口映射
 
@@ -21,6 +21,9 @@
 | 用户说某动作不适合 | `voc-problem-deep-dive` | `voc_problem_deep_dive_run`，传 `feedback` | 自动解析为屏蔽动作或偏好动作 |
 | 选中一条内容继续改口播 | `voc-speaking-script` | `voc_speaking_script_run` | 60 秒稿、30 秒稿、提词器版、改稿反馈、定稿记忆 |
 | 下轮继续优化 | 同一 skill | 带同一 `memory`，或带 project/industry/scenario/audience 让工具自动分桶 | 应用历史记忆，避免从零开始 |
+| 查找商品、评论、创作者或选品接口 | `voc-api-catalog` | `voc_api_search` → `voc_api_doc` → `voc_api_call` | 接口、通道、参数、返回数据和本地媒体证据 |
+| 复杂任务执行前做成本和余额测算 | `voc-cost-controller` | `voc_cost_estimate` / `voc_billing_query` | 经济版/标准版/完整版、调用计划、预计额度、差额和建议充值 |
+| 查询已完成任务的真实消耗 | `voc-cost-controller` | `voc_usage_report` | 报告/模块/接口维度的频次、quota、用户扣费和成本拆分 |
 
 ## Fmode Image Analysis Add-on
 
@@ -107,6 +110,31 @@
 把这些评论整理成问题池，告诉我哪些问题最影响生意，先改哪个。
 ```
 
+### `voc-api-catalog`
+
+适合：
+
+- 查找社媒、电商、创作者和海外选品接口。
+- 读取接口参数、通道和版本建议。
+- 调用清单内接口或用 `rawPath` 调用未登记接口。
+
+标准链路：
+
+```text
+voc_api_search -> voc_api_doc -> voc_api_call
+```
+
+### `voc-cost-controller`
+
+适合：
+
+- 大规模账号、商品、关键词任务的执行前报价。
+- 经济版、标准版、完整版的采集范围比较。
+- 当前余额、预算上限和余额不足后的充值入口。
+- 执行完成后的报告、模块、步骤和接口用量账单。
+
+成本价格以服务端 billing query 返回的当前价目为准；接口目录中的 `billing` 只表示调用单位，不作为人民币价格。
+
 ## 关键产品原则
 
 - 首轮报告是“初步判断”，不是最终结论。
@@ -115,6 +143,8 @@
 - live 失败时给可执行下一步，不暴露原始接口错误。
 - 多轮反馈要进入记忆，让建议越用越贴近客户。
 - 不同行业、不同客户的记忆要隔离。
+- 成本预估是执行前计划，实际扣费以 NewAPI 每次成功调用的计费日志为准。
+- 充值只复用现有 Tokenized Balance 链接或支付二维码；充值完成后重新查询余额并从检查点继续。
 
 ## 记忆规则
 
@@ -138,13 +168,19 @@
 | `mcp/src/server.js` | MCP 工具注册、schema、工具说明 |
 | `mcp/src/tools/*` | CLI/MCP 可调用工具入口 |
 | `mcp/src/features/*` | 趋势报告、单点深挖、记忆、信号提取 |
+| `mcp/catalog/voc-social-endpoints.json` | 1,344 个接口的稳定 ID、通道、参数索引和版本建议 |
+| `mcp/catalog/params/*.json` | 按平台懒加载的详细参数文档 |
 | `mcp/src/core/credentials.js` | token 读取口径 |
 | `mcp/src/core/payment-links.js` | 充值/开通提示 |
+| `mcp/src/core/billing-client.js` / `mcp/src/tools/voc-billing-query-run.js` | 按 Agent 操作计划读取服务端价目、余额、quota 差额和建议充值金额 |
+| `mcp/src/tools/voc-cost-estimate-run.js` | 生成执行前的多档采集计划和成本区间 |
+| `mcp/src/tools/voc-usage-report-run.js` | 查询实际计费日志并按报告、模块、接口拆分 |
 | `mcp/src/core/evidence-quality.js` | 证据质量门槛、无样本降级建议 |
 | `docs/live-manual-acceptance-checklist.md` | live 采集人工验收 |
 | `docs/claude-code-troubleshooting-playbook.md` | Claude Code 故障定位、误报修复、关键词修复和发散排查 |
 | `docs/payment-package-links.md` | 支付链接和套餐入口说明 |
 | `docs/context-budget-implementation-plan.md` | 上下文省 token 工作流 |
+| `docs/voc-cost-metering-and-balance-implementation-spec.md` | VOC 用量核算、任务成本预估、计费 API 与余额看板实施方案 |
 | `docs/deliverables/trend-insight-report.md` | 行业用户洞察趋势清单模板 |
 | `docs/deliverables/competitor-map-report.md` | 竞品图谱与错位机会报告模板 |
 | `docs/deliverables/voc-issue-pool-report.md` | VOC 问题清单与优先级模板 |
@@ -152,6 +188,7 @@
 | `docs/deliverables/seven-day-content-plan.md` | 7 天内容选题与口播脚本模板 |
 | `scripts/smoke-package.js` | 包级 smoke，覆盖 sample、记忆、token、MCP |
 | `scripts/smoke-mcp.js` | MCP 工具发现和基本调用 smoke |
+| `scripts/audit-index.js` | 对比 manifest、技能目录、MCP 注册、版本和文档引用 |
 
 ## 工作坊输出口径
 
@@ -172,6 +209,7 @@
 - `package.json`、`package-lock.json`、`skill-package-manifest.json`、`.claude-plugin/plugin.json`、`mcp/src/server.js` 版本一致。
 - `npm --prefix claude-code-voc-intelligence run mcp:smoke` 通过。
 - `npm --prefix claude-code-voc-intelligence run smoke:package` 通过。
+- `npm --prefix claude-code-voc-intelligence run audit:index` 通过。
 - `npm run claude-voc:build` 通过。
 - npm 发布后 `npm view @vocmarket/voc-skill version` 返回新版本。
 - 测试工作区 `npx --yes @vocmarket/voc-skill@latest workspace --smoke` 通过。

package/docs/live-manual-acceptance-checklist.md

@@ -8,7 +8,7 @@
 - 不依赖 `~/.openclaw/voc-credentials.json`。
 - 如果使用全局配置，只允许使用 `~/.claude/voc-credentials.json`。
 - 上游余额充足，且充值入口可打开：
-  `https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF`
+  `https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN`
 
 ## 小红书 live 最小验收
 
@@ -21,7 +21,7 @@ node ".claude/plugins/voc-intelligence/mcp/src/tools/xiaohongshu-trend-run.js" -
 - `status` 为 `ok`，或在无 token/余额不足时返回友好充值提示。
 - 不出现原始 `403`、权限栈、接口响应体。
 - 报告里有证据样本、原帖链接、评论证据。
-- `files` 中包含 Markdown、JSON，若有图片则包含本地 `assets`。
+- `files` 中包含 Markdown、JSON 和 `assets/media-manifest.json`；报告媒体引用均为本地 `assets` 路径，manifest 中 `cloudUrl` 必须为 `null`。
 
 ## 抖音 live 最小验收
 
@@ -35,6 +35,7 @@ node ".claude/plugins/voc-intelligence/mcp/src/tools/douyin-trend-run.js" --coll
 - 不出现原始 `403`、权限栈、接口响应体。
 - 报告里有视频证据、原视频链接、评论证据。
 - 输出内容仍是“第一轮初步判断 / 机会假设 / 待确认问题”，不能把首轮样本写成最终结论。
+- 即使传入 `--cache-assets false`，仍必须生成本地 `assets/media-manifest.json`，并出现兼容参数弃用提示。
 
 ## 抖音搜索错误快速验收
 

package/docs/npm-packaging-notes.md

@@ -117,7 +117,7 @@ npm run claude-voc:npm-pack
 `npm run claude-voc:acceptance` 是更完整的发布前验收，会额外断言 workspace 安装后的：
 
 - `.mcp.json` 已生成
-- 8 个 `.claude/skills/*/SKILL.md` 入口已生成
+- manifest 中列出的全部 `.claude/skills/*/SKILL.md` 入口已生成（当前 11 个）
 - MCP server 路径是安装后插件目录里的绝对路径
 - `npm pack --dry-run` 能看到关键文件
 
@@ -203,7 +203,7 @@ npm view @vocmarket/voc-skill@0.3.15 version --registry=https://registry.npmjs.o
 - 线上 `npm exec --yes --package @vocmarket/voc-skill@latest -- claude-voc workspace --smoke` 已通过。
 - 旧包 `@gangvy/claude-code-voc-intelligence@*` 已标记为 deprecated，安装旧包时会提示改用 `@vocmarket/voc-skill`。
 - 已新增 `npm run claude-voc:acceptance` 一键发布前验收，覆盖包级 smoke、MCP smoke、npm pack dry-run 和 workspace 安装断言。
-- 包内包含 8 个 skill、12 个 MCP tools。
+- 当前包内包含 11 个 skill、19 个 MCP tools；数量以 `skill-package-manifest.json` 和 `npm run audit:index` 为准。
 - smoke 覆盖 sample report、证据卡、图片缓存、xsec URL 规范化、偏好记忆、no-token 充值提示、祖先 `.env.local` token 读取、抖音搜索入参错误保护、跨行业样例和 MCP tool discovery。
 
 ## 后续版本同步

package/docs/payment-package-links.md

@@ -31,15 +31,15 @@ https://app.fmode.cn/dev/apig-pay/#/workshop
 | 情报官实战包 | https://app.fmode.cn/dev/apig-pay/#/workshop/499 | 隐藏直达，适合企业实训 |
 | 情报官团队包 | https://app.fmode.cn/dev/apig-pay/#/workshop/699 | 公开入口，适合团队共用和复盘 |
 
-## 单 APIG 补额度入口
+## 数据余额入口
 
-当前小红书 live 采集走 VOC 社媒数据中台：
+当前小红书 live 采集统一从当前用户 NewAPI 余额扣费。用户自助充值使用带 Session Token 的余额页：
 
 ```text
-https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF
+https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN
 ```
 
-如果用户只是社媒数据中台余额不足，可以使用这个入口补额度。课程和工作坊场景优先引导用户买技能套餐，因为技能套餐会同时给社媒数据中台和电商数据中台分配额度。
+如果 Agent 已经完成成本测算，也可以直接复用现有 `pay_code2` 链路返回支付二维码。课程和工作坊套餐链接仍只用于套餐购买，不作为数据余额不足时的默认入口。
 
 ## 技能包安装入口
 

package/docs/reports/three-account-platform-cost-2026-09-01.md

@@ -0,0 +1,96 @@
+# 三账号平台成本分析
+
+统计时间：2026-08-31 00:00:00 至 2026-09-01 17:53:20（北京时间）
+
+本文件只展示平台侧成本估算，不包含用户扣费、毛利或账户充值金额。用户实际扣费见独立 HTML 报告。
+
+## 1. 成本总览
+
+- 两个计费账户的平台估算成本合计：¥256.06。
+- 林总分身估算成本：¥120.73。
+- 林煌分身与运营 Agent 共享池估算成本：¥135.33。
+- VOC 数据上游成本：约 ¥57.10。
+- 大模型牌价成本：约 ¥198.96。
+
+## 2. 成本口径
+
+| 成本类型 | 计算方式 | 数据质量 |
+| --- | --- | --- |
+| 小红书 / 社媒 | 按实际转发到上游的端点调用和官方端点价目计算 | 较高 |
+| 淘宝 / 天猫 | 官方日账单暂不可用，按当前端点价目估算 | 估算 |
+| 大模型 | 按 NewAPI 日志中的 `group_ratio` 反推牌价成本 | 估算 |
+
+大模型牌价成本不等同于渠道包月、阶梯折扣或最终结算成本。国内电商成本也需要以后续官方账单校准。
+
+## 3. 成本构成
+
+| 成本模块 | 估算成本 | 占总成本 |
+| --- | ---: | ---: |
+| 林煌分身 + 运营共享池大模型 | ¥135.33 | 52.8% |
+| 林总分身大模型 | ¥63.63 | 24.8% |
+| 小红书 / 社媒数据 | ¥50.90 | 19.9% |
+| 淘宝 / 天猫数据 | 约 ¥6.20 | 2.4% |
+| 合计 | ¥256.06 | 100% |
+
+## 4. VOC 上游成本
+
+### 4.1 小红书
+
+| 接口 | 上游调用 | 估算成本 |
+| --- | ---: | ---: |
+| 获取账号已发布笔记 | 343 | ¥24.70 |
+| 搜索账号 | 102 | ¥7.34 |
+| 获取笔记评论 | 81 | ¥5.83 |
+| 搜索笔记 | 66 | ¥4.75 |
+| 图文笔记详情 | 58 | ¥4.18 |
+| 获取账号信息 | 26 | ¥1.87 |
+| 视频笔记详情 | 20 | ¥1.44 |
+| 子评论 | 10 | ¥0.72 |
+| Web 笔记详情 | 1 | ¥0.07 |
+| 合计 | 707 | ¥50.90 |
+
+### 4.2 淘宝 / 天猫
+
+| 接口 | 上游调用 | 估算成本 |
+| --- | ---: | ---: |
+| 商品详情 v4 | 8 | 约 ¥1.60 |
+| 商品评论 v3 | 8 | 约 ¥1.60 |
+| 商品详情 v3 | 7 | 约 ¥1.40 |
+| 店铺商品列表 v4 | 5 | 约 ¥1.00 |
+| 商品详情 v2 | 1 | 约 ¥0.20 |
+| 商品详情 v5 | 1 | 约 ¥0.20 |
+| 商品搜索 v1 | 1 | 约 ¥0.20 |
+| 合计 | 31 | 约 ¥6.20 |
+
+## 5. 大模型牌价成本
+
+### 林总分身
+
+| 模型 | 调用 | 估算牌价成本 |
+| --- | ---: | ---: |
+| Claude Sonnet | 153 | ¥59.81 |
+| DeepSeek Flash | 355 | ¥3.76 |
+| Claude Haiku | 5 | ¥0.06 |
+| 合计 | 513 | ¥63.63 |
+
+### 林煌分身与运营 Agent 共享池
+
+| 模型 | 调用 | 估算牌价成本 |
+| --- | ---: | ---: |
+| GLM Flash | 35 | ¥127.04 |
+| DeepSeek Flash | 305 | ¥8.13 |
+| GPT-4o | 2 | ¥0.15 |
+| 合计 | 342 | ¥135.33 |
+
+## 6. 成本侧结论
+
+1. VOC 上游成本的最大单项是“小红书账号已发布笔记”，估算 ¥24.70。
+2. 大模型成本明显高于 VOC 数据成本，尤其是共享池 GLM Flash，估算 ¥127.04。
+3. 成本优化应优先关注高频接口和高单次上下文请求，并在后续日志中保留可追踪的执行标识。
+4. 后续需要用渠道实际结算账单校准大模型与国内电商估算值，并在日志中记录成本版本。
+
+## 7. 数据边界
+
+1. 共享池当前不能拆分林煌分身与运营 Agent。
+2. 当前没有 `usageTraceId/reportId`，报告场景归因依赖账户、接口与执行时间。
+3. 本文件不包含任何 Session Token、API Key、Bot Secret、密码或支付凭证。