# Claude Code VOC Intelligence 能力地图

这份文档给 Claude Code、维护者和交付人员快速定位：这套技能包能做什么、该用哪个入口、出了问题去哪里看。

## 一句话定位

把小红书、抖音等平台的用户真实声音，转成企业能用的趋势情报、问题优先级、经营动作、内容选题和多轮验证记忆。

## 用户任务到入口映射

| 用户想做的事 | 推荐入口 | MCP 工具 | 输出重点 |
| --- | --- | --- | --- |
| 一次跑完整经营闭环 | `voc-business-workflow` | `voc_business_workflow_run` | 市场声音、问题池、Top 问题动作、7 天内容计划、第一条口播稿 |
| 先演示流程，不真实采集 | 小红书/抖音趋势 skill | `voc_xiaohongshu_trend_run` / `voc_douyin_trend_run`，`collectionMode=sample` | 第一轮样本观察、机会假设、待确认问题 |
| 真实采集行业趋势 | 小红书/抖音趋势 skill | `voc_xiaohongshu_trend_run` / `voc_douyin_trend_run`，`collectionMode=live` | 真实笔记/视频、评论证据、趋势假设 |
| 检查 token 是否可用 | 平台趋势 skill | `voc_xiaohongshu_token_check` / `voc_douyin_token_check` | 是否已配置、无 token 时给充值链接 |
| 用户回答校准问题 | 平台趋势 skill | `voc_xiaohongshu_preference_update` / `voc_douyin_preference_update` | 保存偏好、屏蔽方向、下一轮聚焦 |
| 把评论整理成问题池 | `voc-issue-pool` | `voc_issue_pool_run` | 问题优先级、状态、证据、影响环节、建议动作 |
| 判断哪些问题最影响生意 | `voc-issue-pool` | `voc_issue_pool_run` | 本周优先推进的问题和下一步深挖入口 |
| 深挖一个具体问题 | `voc-problem-deep-dive` | `voc_problem_deep_dive_run` | 老板视角影响、动作清单、7 天验证 |
| 用户说某动作不适合 | `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-business-workflow`

适合：

- 用户只想说自然语言，不想选择工具
- 一次串起市场洞察、问题优先级、单点动作、内容计划和口播稿
- 远程给客户先跑一份第一轮经营交付

用户典型话术：

```text
帮我看一下南昌餐饮最近顾客在关心什么，并告诉我先改哪里、下周发什么。
```

### `xiaohongshu-trend-intelligence`

适合：

- 小红书趋势情报
- 行业用户顾虑
- 内容选题
- 销售话术
- 小红书评论证据卡

用户典型话术：

```text
帮我做一份家装全屋定制行业的小红书趋势情报，先用演示样例跑通流程。
```

### `douyin-trend-intelligence`

适合：

- 抖音趋势情报
- 本地生活/餐饮评论洞察
- 短视频内容机会
- 门店转化线索

用户典型话术：

```text
帮我看下南昌餐饮行业抖音上用户最近在吐槽什么，先小规模真实采集。
```

### `voc-problem-deep-dive`

适合：

- 单点 VOC 深挖
- 差评背后问题拆解
- 老板怎么解决
- 门店动作和内容选题
- 多轮记忆优化

用户典型话术：

```text
继续深挖“排队”这个问题，告诉老板今天能改什么，7 天怎么验证。
```

### `voc-issue-pool`

适合：

- 评论问题池
- 用户吐槽归类
- 问题优先级排序
- 问题状态管理
- 从趋势报告进入单点深挖前的中间层

用户典型话术：

```text
把这些评论整理成问题池，告诉我哪些问题最影响生意，先改哪个。
```

## 关键产品原则

- 首轮报告是“初步判断”，不是最终结论。
- 输出必须带证据，不只给抽象观点。
- 老板用户不需要学习提示词，Claude Code 要主动选择技能和工具。
- live 失败时给可执行下一步，不暴露原始接口错误。
- 多轮反馈要进入记忆，让建议越用越贴近客户。
- 不同行业、不同客户的记忆要隔离。

## 记忆规则

趋势情报记忆：

- 记录保留方向、屏蔽方向、聚焦模式、用户备注。
- 适合下一轮趋势报告排序和话术收敛。

单点 VOC 记忆：

- 记录偏好动作、屏蔽动作、偏好内容角度、验证有效动作、验证无效动作。
- 未显式传 `memory` 时，默认按 `project/brand/store + industry + scenario + audience` 分桶。
- 显式传 `memory` 时保持兼容，用指定文件沉淀。

## 文件索引

| 文件 | 用途 |
| --- | --- |
| `README.md` | 面向使用者和 Claude Code 的总入口说明 |
| `skills/*/SKILL.md` | Claude Code 触发规则和操作约束 |
| `mcp/src/server.js` | MCP 工具注册、schema、工具说明 |
| `mcp/src/tools/*` | CLI/MCP 可调用工具入口 |
| `mcp/src/features/*` | 趋势报告、单点深挖、记忆、信号提取 |
| `mcp/src/core/credentials.js` | token 读取口径 |
| `mcp/src/core/payment-links.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/deliverables/trend-insight-report.md` | 行业用户洞察趋势清单模板 |
| `docs/deliverables/competitor-map-report.md` | 竞品图谱与错位机会报告模板 |
| `docs/deliverables/voc-issue-pool-report.md` | VOC 问题清单与优先级模板 |
| `docs/deliverables/single-problem-action-plan.md` | 单点问题 7 天行动计划模板 |
| `docs/deliverables/seven-day-content-plan.md` | 7 天内容选题与口播脚本模板 |
| `scripts/smoke-package.js` | 包级 smoke，覆盖 sample、记忆、token、MCP |
| `scripts/smoke-mcp.js` | MCP 工具发现和基本调用 smoke |

## 工作坊输出口径

面向餐饮老板或线下工作坊时，Claude Code 输出优先按：

1. 你这轮能拿到什么。
2. 我会怎么做。
3. 第一版结果。
4. 你需要确认什么。
5. 下一步建议。

每个小节都必须对应一个交付物。不要在前台讲 MCP、schema、collectionMode、提示词工程。

## 维护检查点

每次发布至少确认：

- `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 run claude-voc:build` 通过。
- npm 发布后 `npm view @gangvy/claude-code-voc-intelligence version` 返回新版本。
- 测试工作区 `npx --yes @gangvy/claude-code-voc-intelligence@latest workspace --smoke` 通过。

## 下一轮优化补充

- `voc-issue-pool` 已支持跨轮问题变化：同一记忆范围下会对比上轮/本轮证据数，并标记新增、变多、变少、持平、本轮未再出现。
- `voc-problem-deep-dive` 已支持动作权重记忆：用户反馈“有效/无效”后，会记录验证次数，后续优先推荐有效动作、降低无效动作。
- 趋势情报输出后的推荐链路应优先进入问题池：先把证据整理成 VOC 问题池，判断先改哪个问题，再进入单点 VOC 深挖。

## 工作坊交付型入口

| 老板说法 | 推荐入口 | MCP 工具 | 交付物 |
| --- | --- | --- | --- |
| 帮我看这个品类最近顾客在关心什么 | 小红书/抖音趋势 skill | `voc_xiaohongshu_trend_run` / `voc_douyin_trend_run` | 行业用户洞察趋势清单 |
| 帮我看顾客关心什么、先改哪里、下周发什么 | `voc-business-workflow` | `voc_business_workflow_run` | VOC 经营闭环报告 |
| 我不知道竞品是谁，帮我看看别人怎么做 | `voc-competitor-map` | `voc_competitor_map_run` | 竞品图谱与错位机会报告 |
| 顾客到底在吐槽什么，先改哪个 | `voc-issue-pool` | `voc_issue_pool_run` | VOC 问题清单与优先级 |
| 这个问题老板怎么解决 | `voc-problem-deep-dive` | `voc_problem_deep_dive_run` | 单点问题 7 天行动计划 |
| 下周账号发什么，帮我写口播 | `voc-content-plan` | `voc_content_plan_run` | 7 天内容选题与口播脚本 |
| 选题 2 进入脚本共创 | `voc-speaking-script` | `voc_speaking_script_run` | 口播稿改稿与定稿记忆 |

边界说明：

- 口播/短视频脚本属于本技能包范围，但必须来自 VOC 用户问题、竞品评论差异、问题池 Top 问题或单点深挖动作。
- 创始人故事、品牌自传、老板个人 IP 长文不属于 `claude-code-voc-intelligence` 主线。
- 现场工作坊前台不要讲 MCP、schema、提示词工程；前台只讲“看市场、看竞品、看问题、找动作、做内容”。