openclaw-voc-skill/claude-code/claude-code-voc-intelligence/docs/claude-code-troubleshooting-playbook.md

Claude Code VOC Troubleshooting Playbook

This playbook helps Claude Code and maintainers quickly map live VOC collection symptoms to the right fix path. Use it when a real user conversation gets stuck, a platform collector reports the wrong state, or Claude Code does not know whether to retry, recharge, or switch tools.

Fast Triage

Symptom in Claude Code	Likely Cause	User-Facing State	First Fix Path	Do Not Do
Douyin live says balance is insufficient, but the account has balance	Search API or keyword request failed and was classified as billing	needs_keyword_fix	Check Douyin API error classification and keyword repair	Do not show recharge link unless status is really needs_recharge
Douyin returns 社交平台接口请求错误 or HTTP 5xx	Upstream search or input issue	needs_keyword_fix, or auto-repair then ok	Normalize keyword, retry with a shorter natural keyword	Do not expose raw 5xx body to user
User passes 家居定制18元22元 and search is unstable	Compact keyword lacks natural search spacing	Usually auto-repaired	Normalize to 家居定制 18元 22元	Do not require user to learn CLI flags
User passes empty --keywords ""	CLI parser receives an explicit empty value	needs_keyword_fix	Keep explicit empty as empty; do not fall back to default keywords	Do not silently search generic defaults
User asks “进入真实采集 live 模式” but workflow keeps deep-diving	Skill handoff rules are too weak	Should call platform live collector	Update deep-dive/business workflow skill instructions and nextActions	Do not keep asking 7-day validation questions
MCP output validation fails because warnings contain objects	Structured output schema expects strings	Tool call error	Normalize warnings at MCP server boundary	Do not remove evidence warnings entirely
Live collection says no token even after user configured one	Wrong working directory or unsupported credential source	needs_token	Check .env.local search path and ~/.claude/voc-credentials.json	Do not print token
First report sounds final or overconfident	Report layer ignored evidence quality	ok, but poor UX	Enforce “初步判断 / 机会假设 / 待校准” and evidence quality	Do not write final business conclusions from first sample

Douyin Search Error Fix Pattern

When Douyin search fails, fix in this order:

1. Classify provider errors before building user messages.
2. Treat billing only as billing when the provider clearly says balance, quota, payment, or recharge.
3. Treat HTTP 400/422 and generic search 5xx as search/input repair.
4. Normalize keywords before calling the API.
5. Retry once with a shorter natural keyword.
6. If retry fails, return needs_keyword_fix with 2-3 concrete keyword examples.

Current key files:

Concern	File
Provider error classification	mcp/src/providers/douyin-api.js
Keyword normalization and auto repair	mcp/src/features/douyin-trend/live-collector.js
User-facing status selection	mcp/src/tools/douyin-trend-run.js
MCP structured output normalization	mcp/src/server.js
Douyin skill behavior rules	skills/douyin-trend-intelligence/SKILL.md
Live mode reference	skills/douyin-trend-intelligence/references/live-mode.md
Manual live acceptance checks	docs/live-manual-acceptance-checklist.md
Regression smoke tests	scripts/smoke-package.js

Status Decision Rules

Use these states consistently:

Condition	Status	Message Strategy
No token configured	needs_token	Show payment/open link and token config path
Token invalid	needs_valid_token	Ask user to reconfigure token; show payment/open link only as support path
Clear balance/quota/payment issue	needs_recharge	Show recharge/payment link
Search input, empty keyword, overlong keyword, generic search 5xx	needs_keyword_fix	Give corrected keyword examples; no payment link
Token valid but no usable samples	no_live_samples	Suggest broader/narrower keywords; no payment link
Some samples collected but later billing blocked	partial_needs_recharge	Preserve partial report and show recharge link
Normal collection	ok	Return report body and evidence quality

Keyword Repair Recipes

Claude Code should prefer short, natural platform search phrases:

品类 + 价格/问题 + 人群/场景

Examples:

家居定制 18元 22元
家居定制 性价比 新客
全屋定制 方案 怎么选 避坑
家居定制 价格 怎么选
家居定制 对比 值不值

Repair rules:

• Insert spacing around Chinese and numbers: 家居定制18元22元 -> 家居定制 18元 22元.
• Keep keywords under 60 characters.
• If price-specific search fails, try intent-specific search: 家居定制 性价比 新客.
• If intent search fails, try behavior-specific search: 全屋定制 方案 怎么选 避坑.
• If all fail, return needs_keyword_fix and tell the user what was tried.

Implementation Checklist For Similar Bugs

When a new misclassification appears:

1. Reproduce with a small command or mocked provider response.
2. Add an error kind at provider boundary, for example billing, auth, request, upstream_search, permission.
3. Make the CLI/tool status choose from kind, not raw text only.
4. Normalize user input before API calls.
5. Add one automatic repair if it is safe and low-cost.
6. Add smoke coverage for both the bad path and the repaired path.
7. Update the skill instructions so Claude Code knows what to do in conversation.
8. Update manual acceptance docs with one command a trainer can run.
9. Run package smoke and build.

Divergent Debugging Ideas

If the obvious fix does not work, branch into these checks:

• Credential source: is Claude Code running from the workspace that contains .env.local?
• MCP schema: did the tool return object warnings where the schema expects strings?
• CLI parsing: did --keywords "" become boolean true or an empty string?
• Encoding: did Chinese error text become mojibake or ????, breaking regex matching?
• Upstream semantics: does provider return business error codes inside HTTP 200?
• Partial success: did videos collect but comments fail, requiring partial report instead of total failure?
• Report quality: did auto-repair succeed but report still say the original keyword?
• Skill routing: did the user ask for live collection, but a deep-dive skill kept control?
• Safety: does any output accidentally echo VOC_TOKEN, Bearer, or r:...?

Verification Commands

Run these after changing collector behavior:

node --check claude-code-voc-intelligence\mcp\src\providers\douyin-api.js
node --check claude-code-voc-intelligence\mcp\src\features\douyin-trend\live-collector.js
node --check claude-code-voc-intelligence\mcp\src\tools\douyin-trend-run.js
node --check claude-code-voc-intelligence\scripts\smoke-package.js
npm --prefix claude-code-voc-intelligence run mcp:smoke
npm --prefix claude-code-voc-intelligence run smoke:package
npm run claude-voc:build

Live manual check, only when a real token is configured:

node .claude\plugins\voc-intelligence\mcp\src\tools\douyin-trend-run.js --collection-mode live --industry "家居定制" --business-type "全屋定制品牌" --target-audience "新客" --keywords "家居定制18元22元" --keyword-limit 1 --videos-per-keyword 1 --max-comment-pages 0 --cache-assets false --output "outputs/live-acceptance-douyin-keyword"

Expected:

• Compact keyword is normalized to 家居定制 18元 22元.
• Search 5xx is auto-repaired or returned as needs_keyword_fix.
• Recharge URL appears only for token, valid-token, or real balance states.
• No token value appears in output.