# live 模式接入说明

## 原则

P0 阶段先用 sample 模式跑通流程。

当用户明确要真实采集时，再切 live 模式。

## 采集默认值

live 模式默认保持小规模：

- `keywordLimit = 1`
- `notesPerKeyword = 1`
- `maxCommentPages = 1`

这样可以先验证流程，不会一上来就把运行成本拉高。

## token 处理

请求入参仍然保持简单：

- `xiaohongshuToken`
- `vocToken`

系统也会尝试从本机环境读取 token。

不要直接把底层报错甩给用户：

- 缺 token：先自救——读 `~/.claude/settings.json` 的 `sk-` fmode key（或 `~/.fmode/config.json` / `~/.claude/voc-credentials.json`）用 `FMODE_API_KEY=sk-…` 重试，不要直接给充值链接。
- 只有真正余额不足（`402`）才给充值链接 + 下一步操作。完整口径见下方「充值入口」与 voc-api-catalog 的「错误码速查」。

不要把 `403`、授权失败文案、原始响应体直接暴露给用户。

## 可访问链接

小红书原帖链接优先使用：

1. `mini_program_info.webpage_url`
2. `share_info.link`

保留 `xsec_token`，否则网页端可能打不开。

## 充值入口（仅 402 余额不足时，简版）

- 透传工具生成的 Tokenized Balance 链接或二维码支付结果；Balance 链接格式为 `https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN`。
- 完整 401/402/403 对照与回退逻辑见 **voc-api-catalog 技能的「错误码速查」references/error-codes.md**（单一权威来源）。

## 结论

live 模式不是为了替代 sample，而是为了在 sample 已经校准过后，接上真实数据继续迭代。