09-troubleshooting.md 4.5 KB
09 常见问题与快速修复
本节目标：让学员遇到错误时知道下一步，而不是卡在报错页面。
问题 1：旧安装命令还能用吗
旧包：
@gangvy/claude-code-voc-intelligence
已迁移到：
@vocmarket/voc-skill
新安装命令：
npx --yes @vocmarket/voc-skill@latest workspace --smoke
如果学员使用旧包，npm 会提示改用新包。
截图位置：
【截图 09-01：新安装命令】
问题 2：Claude Code 没触发 VOC 技能
处理提示词：
请使用当前工作区已安装的 VOC 技能包，不要凭经验回答。
如果可以调用工具，请优先调用 voc_xiaohongshu_trend_run 或 voc_douyin_trend_run。
检查文件：
dir .\.claude\plugins\voc-intelligence
dir .\.claude\skills
dir .\.mcp.json
截图位置：
【截图 09-02：检查 .claude 和 .mcp.json】
下一步：重启 Claude Code。
问题 3：needs_token
含义：没有检测到 token。
处理：
- 在工作区根目录创建
.env.local。 写入：
VOC_TOKEN=你的服务 token重启 Claude Code。
重新运行 live 采集。
截图位置：
【截图 09-03：needs_token 状态，不展示 token 值】
问题 4：needs_recharge
含义：服务未开通或余额不足。
处理：
- 打开工具输出中的充值/开通链接。
- 完成后重新采集。
- 如果课堂现场暂时无法处理，先切 sample 模式继续练习。
截图位置：
【截图 09-04：needs_recharge 状态和充值链接】
问题 5：needs_keyword_fix
含义：关键词或搜索入参不适合平台搜索，不一定是余额问题。
处理 Prompt：
这次 live 采集返回 needs_keyword_fix。
请不要当成余额不足处理。
请根据当前业务目标，帮我把关键词改成 3 个更适合抖音搜索的短关键词，并重新小规模采集。
关键词修复示例：
| 原关键词 | 修复后 |
|---|---|
| 茶饮18元22元 | 茶饮 18元 22元 |
| 茶饮价格性价比新客套餐点单避坑评论区问题很多 | 茶饮 性价比 新客 |
| 奶茶第一次来不知道怎么点怕踩雷 | 奶茶 点单 避坑 |
截图位置：
【截图 09-05：needs_keyword_fix 状态】
【截图 09-06：修复关键词后重新采集】
问题 6：小红书链接 404 或首图不显示
可能原因：
- 平台没有返回可核验原帖链接。
- 原始链接缺少
xsec_token。 - 图片资源需要平台权限或已失效。
处理：
请检查本轮小红书证据样本：
1. 哪些原帖链接可核验
2. 哪些链接可能 404
3. 首图是否有本地缓存
4. 如果首图不可展示，请在报告中明确写“平台未返回可展示首图”
不要把不可核验链接当作原帖证据。
截图位置：
【截图 09-07：链接或首图异常说明】
问题 7：报告输出太像最终结论
修正 Prompt：
请把这份报告改成第一轮 VOC 初步判断。
要求：
1. 明确写“待校准”
2. 不要写成最终结论
3. 每个判断都要回到证据
4. 最后给出下一轮待确认问题
截图位置：
【截图 09-08：把最终结论改成待校准】
问题 8：单点深挖卡住，不推进下一步
修正 Prompt：
请不要继续停留在单点深挖。
现在请把这个问题推进到下一步：
1. 需要补采哪些关键词
2. 是否要进入 live 采集
3. 是否要生成问题池
4. 是否要转成 7 天内容计划
请给出下一步操作，而不是继续重复分析同一个点。
截图位置：
【截图 09-09：从深挖推进下一步】
问题 9：内容计划没有用到 VOC 技能
判断：
- 如果输出重复。
- 如果内容像餐饮通用模板。
- 如果茶饮案例里出现“招牌菜、下饭菜”等不适合词。
修正 Prompt：
请重新生成内容计划。
必须基于茶饮 VOC 背景：
18-22 元、值不值、首单怎么点、茶底、甜度、配料表、外卖到手、团购规则。
不要使用餐饮菜品模板，不要出现“招牌菜、下饭菜”。
每条都要有对应 VOC 问题和验证指标。
截图位置：
【截图 09-10：修正内容计划】
本节验收
- 学员知道 token、余额、关键词错误的区别。
- 学员知道旧包已迁移到新包。
- 学员知道链接 404 时不能强行当证据。
- 学员知道深挖后要推进到采集、问题池、内容计划或报告。