# 09 常见问题与快速修复

本节目标：让学员遇到错误时知道下一步，而不是卡在报错页面。

## 问题 1：旧安装命令还能用吗

旧包：

```text
@gangvy/claude-code-voc-intelligence
```

已迁移到：

```text
@vocmarket/voc-skill
```

新安装命令：

```powershell
npx --yes @vocmarket/voc-skill@latest workspace --smoke
```

如果学员使用旧包，npm 会提示改用新包。

截图位置：

```text
【截图 09-01：新安装命令】
```

## 问题 2：Claude Code 没触发 VOC 技能

处理提示词：

```text
请使用当前工作区已安装的 VOC 技能包，不要凭经验回答。
如果可以调用工具，请优先调用 voc_xiaohongshu_trend_run 或 voc_douyin_trend_run。
```

检查文件：

```powershell
dir .\.claude\plugins\voc-intelligence
dir .\.claude\skills
dir .\.mcp.json
```

截图位置：

```text
【截图 09-02：检查 .claude 和 .mcp.json】
```

下一步：重启 Claude Code。

## 问题 3：needs_token

含义：没有检测到 token。

处理：

1. 在工作区根目录创建 `.env.local`。
2. 写入：

```text
VOC_TOKEN=你的服务 token
```

3. 重启 Claude Code。
4. 重新运行 live 采集。

截图位置：

```text
【截图 09-03：needs_token 状态，不展示 token 值】
```

## 问题 4：needs_recharge

含义：服务未开通或余额不足。

处理：

1. 打开工具输出中的充值/开通链接。
2. 完成后重新采集。
3. 如果课堂现场暂时无法处理，先切 sample 模式继续练习。

截图位置：

```text
【截图 09-04：needs_recharge 状态和充值链接】
```

## 问题 5：needs_keyword_fix

含义：关键词或搜索入参不适合平台搜索，不一定是余额问题。

处理 Prompt：

```text
这次 live 采集返回 needs_keyword_fix。
请不要当成余额不足处理。
请根据当前业务目标，帮我把关键词改成 3 个更适合抖音搜索的短关键词，并重新小规模采集。
```

关键词修复示例：

| 原关键词 | 修复后 |
|---|---|
| 茶饮18元22元 | 茶饮 18元 22元 |
| 茶饮价格性价比新客套餐点单避坑评论区问题很多 | 茶饮 性价比 新客 |
| 奶茶第一次来不知道怎么点怕踩雷 | 奶茶 点单 避坑 |

截图位置：

```text
【截图 09-05：needs_keyword_fix 状态】
【截图 09-06：修复关键词后重新采集】
```

## 问题 6：小红书链接 404 或首图不显示

可能原因：

- 平台没有返回可核验原帖链接。
- 原始链接缺少 `xsec_token`。
- 图片资源需要平台权限或已失效。

处理：

```text
请检查本轮小红书证据样本：
1. 哪些原帖链接可核验
2. 哪些链接可能 404
3. 首图是否有本地缓存
4. 如果首图不可展示，请在报告中明确写“平台未返回可展示首图”
不要把不可核验链接当作原帖证据。
```

截图位置：

```text
【截图 09-07：链接或首图异常说明】
```

## 问题 7：报告输出太像最终结论

修正 Prompt：

```text
请把这份报告改成第一轮 VOC 初步判断。
要求：
1. 明确写“待校准”
2. 不要写成最终结论
3. 每个判断都要回到证据
4. 最后给出下一轮待确认问题
```

截图位置：

```text
【截图 09-08：把最终结论改成待校准】
```

## 问题 8：单点深挖卡住，不推进下一步

修正 Prompt：

```text
请不要继续停留在单点深挖。
现在请把这个问题推进到下一步：
1. 需要补采哪些关键词
2. 是否要进入 live 采集
3. 是否要生成问题池
4. 是否要转成 7 天内容计划
请给出下一步操作，而不是继续重复分析同一个点。
```

截图位置：

```text
【截图 09-09：从深挖推进下一步】
```

## 问题 9：内容计划没有用到 VOC 技能

判断：

- 如果输出重复。
- 如果内容像餐饮通用模板。
- 如果茶饮案例里出现“招牌菜、下饭菜”等不适合词。

修正 Prompt：

```text
请重新生成内容计划。
必须基于茶饮 VOC 背景：
18-22 元、值不值、首单怎么点、茶底、甜度、配料表、外卖到手、团购规则。
不要使用餐饮菜品模板，不要出现“招牌菜、下饭菜”。
每条都要有对应 VOC 问题和验证指标。
```

截图位置：

```text
【截图 09-10：修正内容计划】
```

## 本节验收

- 学员知道 token、余额、关键词错误的区别。
- 学员知道旧包已迁移到新包。
- 学员知道链接 404 时不能强行当证据。
- 学员知道深挖后要推进到采集、问题池、内容计划或报告。