# 2026-04-27 小红书自然语言入口优化方案

## 背景结论

当前小红书专家让用户输入 JSON 指令是不合适的。JSON 只应作为内部自动化或调试兼容入口，客户端用户侧应直接输入自然语言需求。

现状问题集中在 `workspace\xhs\workspace_entry.py`：

- 完整执行路径目前主要依赖 `xhs_action` JSON 指令。
- 普通自然语言无法补齐参数时，会兜底返回“请使用 JSON 指令”。
- 入口曾使用 `prepared-prompt` 做自然语言关键词判断；该字段包含系统上下文，容易误触发“发布”等动作。

优化目标：

- 用户自然语言输入需求。
- 入口脚本负责解析、追问、确认、执行。
- 长流程必须确认后才启动。
- 继续只读取客户端注入的模型、Cookie、飞书环境变量。

## 需要修改的文件范围

核心修改：

- `workspace\xhs\workspace_entry.py`
  - 自然语言意图解析。
  - QWEN 参数抽取。
  - 多轮补参状态。
  - 参数确认后执行。
  - 风险控制和环境校验。

可能需要小改：

- `workspace\xhs\project.json`
  - 一般不需要改；如需可补充入口能力描述。

需要更新 smoke：

- `build\scripts\local-project-package-smoke.ps1`
  - 补自然语言入口、追问、确认流程断言。
- `build\scripts\xhs-expert-cloud-bundle-smoke.ps1`
  - 云端 bundle 入口断言改为自然语言完成/追问，不再依赖 JSON 示例。

不应修改：

- `apps\ui` 渲染层。
- 共享 IPC 类型。
- `workspace\douyin` 业务逻辑。
- 小红书原始包 `workspace\xiaohongshu-client-package`。

## 交互与执行设计

入口参数使用策略：

- `--prompt`：唯一用户原文来源。
- `--prepared-prompt`：只作为模型解析上下文，不参与关键词或动作判断。
- `--session-id`：用于隔离多轮补参状态。

自然语言解析策略：

- 优先调用客户端注入的 QWEN：
  - `QWEN_BASE_URL`
  - `QWEN_API_KEY`
  - `QWEN_MODEL`
- QWEN 输出必须校验 schema。
- 只允许白名单动作：
  - `collect`
  - `generate_from_link`
  - `generate_from_collected`
  - `preview_latest`
  - `check_config`
  - `locate_latest`
  - `publish_latest`
- QWEN 不可用或解析失败时，降级为规则解析和自然语言追问。

多轮补参：

- pending state 存到 `memory\xhs_workspace_sessions\`。
- 文件按 `session-id` 隔离。
- 状态 TTL：24 小时。
- 完成、取消、切换动作后清理。

采集动作必填字段：

- `keywords`
- `business_need`
- `target_audience`
- `theme`

生成动作必填字段：

- `generate_from_link`：`ref_url`、`topic`
- `generate_from_collected`：`ref_index`、`brand`、`location`

确认机制：

- `collect`、`generate_from_link`、`generate_from_collected` 必须先输出确认摘要。
- 用户明确回复“确认 / 开始 / 执行”后才调用 CLI。
- 用户回复“取消 / 重来”时清理 pending state。
- `check_config`、`preview_latest`、`locate_latest` 可直接执行。
- `publish_latest` 只在用户明确输入“发布 / 现在发布 / 立即发布”时触发。

数量保护：

- `total_count` 默认 5。
- `total_count` 最大 20。
- `top_n` 不超过 `total_count`。

## 风险点与处理

误启动采集：

- 不能忽视。
- 所有长流程强制确认后执行。
- 未确认时只返回参数摘要。

`prepared-prompt` 误判：

- 必须修。
- 自然语言判断只读取 `--prompt`。
- `prepared-prompt` 不再用于动作关键词匹配。

模型解析失败：

- 不能忽视。
- QWEN 失败时返回自然语言追问。
- 不再要求用户输入 JSON。
- 模型输出必须做 action 白名单和字段校验。

会话状态污染：

- 不能忽视。
- 按 session 隔离。
- 完成、取消、切换动作后清理。
- 加 24 小时 TTL。

旧 smoke 兼容：

- 可以低风险处理。
- 不保留“要求 JSON”的用户体验。
- 更新 smoke 到自然语言追问/确认断言。

## 测试计划

脚本级验证：

```powershell
python -m py_compile workspace\xhs\workspace_entry.py
```

自然语言用例：

- 输入“帮我采集防晒霜赛道，面向通勤女性，先抓 5 条”。
  - 预期：缺字段时追问，字段完整时返回确认摘要。
- 输入“确认”。
  - 预期：开始执行；若缺 `COOKIES`、`QWEN_API_KEY`、飞书配置，则明确 error。
- 输入“取消”。
  - 预期：清理 pending state。
- 输入“小红书链接 + 生成内容需求”。
  - 预期：进入链接生成补参/确认流程。
- 输入“最新结果 / 预览结果”。
  - 预期：直接预览。
- 输入“现在发布”。
  - 预期：只做发布条件校验，不误触发其他自然语言。

回归验证：

```powershell
corepack pnpm typecheck
corepack pnpm build
corepack pnpm smoke:xhs-local-project-package
corepack pnpm smoke:xhs-expert-cloud-bundle
corepack pnpm smoke:douyin-local-project-package
corepack pnpm smoke:douyin-expert-cloud-bundle
```

通过标准：

- 小红书专家自然语言入口不再提示用户输入 JSON。
- 长流程不会在未确认时启动。
- 缺环境变量时给出明确错误。
- qjclaw 自动执行不触发扫码登录。
- `prepared-prompt` 中的系统上下文不影响动作判断。
- xhs 本地包、云端 bundle、抖音回归 smoke 全部通过。
