# 2026-04-27 小红书客户端接入适配方案

## 结论

小红书项目当前真实源码目录是 `D:\qjclaw\workspace\xiaohongshu-client-package`，不是 `D:\qiclaw\...`。

该目录目前更接近原始客户端交付包，不是 qjclaw 可直接执行的 workspace 项目。后续接入应新建或迁移到 `D:\qjclaw\workspace\xhs`，并固定项目 ID 为 `xhs`。

## 当前项目事实

- 源项目存在于 `workspace\xiaohongshu-client-package`。
- 当前缺少 qjclaw 必需的 `project.json`。
- 当前缺少 qjclaw 直接执行入口 `workspace_entry.py`。
- 当前没有输出 qjclaw 可识别的 `QJC_WORKSPACE_EVENT\t...` 事件协议。
- 当前没有声明 `boundSkillIds`，客户端无法按项目过滤并展示小红书相关技能。
- 当前没有 qjclaw bundle 排除规则，`.env`、运行数据、缓存、生成物和本地调试产物需要显式排除。

已有入口和能力：

- `agent_server.py`：FastAPI 后端，默认监听 `8888`，暴露 `/status`、`/api/crawler/start`、`/api/checkpoints`、`/api/generate`、`/api/result/latest` 等接口。
- `main.py`：CLI/采集主流程，支持关键词、业务需求、目标人群、主题、数量等参数。
- `regen_v2.py`、`generate_content.py`、`print_latest_result.py`：基于已有采集结果生成内容和读取最新结果。
- `requirements.txt`：声明 Python runtime 依赖。
- `CLIENT_INTEGRATION.md`：说明当前项目可用 FastAPI 或 CLI 集成，但这不是 qjclaw workspace 协议。

## 缺口

小红书项目要进入 qjclaw 客户端执行链，至少需要补齐：

- `project.json`
- `workspace_entry.py`
- `workspaceAutomation`
- `defaultEntry.type = "workspace-entry"`
- `entries` 中的 `workspace-entry`
- `workspaceEntryEnabled: true`
- `ready: true`
- `boundSkillIds`
- `bundlePackaging.excludePaths`
- `QJC_WORKSPACE_EVENT` 事件输出
- 客户端模型/密钥配置到项目环境变量的映射

## 适配目录策略

使用新目录：

```text
D:\qjclaw\workspace\xhs
```

原因：

- 项目 ID 固定为 `xhs`，与已有脚本 `smoke:xhs-local-project-package`、`smoke:xhs-expert-cloud-bundle` 保持一致。
- 保留 `xiaohongshu-client-package` 作为原始交付包，避免在源包上混入 qjclaw 适配层。
- 后续 bundle、客户端项目记录、技能绑定都以 `xhs` 为唯一项目标识。

## project.json 方案

`workspace\xhs\project.json` 使用 qjclaw 已验证字段，不新增未被客户端消费的字段。

建议结构：

```json
{
  "id": "xhs",
  "name": "xiaohongshu-client-package",
  "platform": "xiaohongshu",
  "projectType": "automation-project",
  "description": "Xiaohongshu content collection, analysis, copywriting and publishing project.",
  "version": "2026-04",
  "workspaceAutomation": {
    "runtime": "python",
    "script": "workspace_entry.py",
    "args": [
      "--prompt",
      "{prompt}",
      "--prepared-prompt",
      "{preparedPrompt}",
      "--project-root",
      "{projectRoot}",
      "--session-id",
      "{sessionId}"
    ]
  },
  "bundlePackaging": {
    "excludePaths": [
      ".env",
      "datas/runtime",
      "datas/checkpoints",
      "datas/excel_datas",
      "datas/media_datas",
      "datas/generated",
      "datas/uploads",
      "datas/debug_pages",
      "node_modules",
      "__pycache__",
      "**/__pycache__",
      "**/*.pyc"
    ]
  },
  "defaultEntry": {
    "id": "workspace-entry",
    "type": "workspace-entry",
    "intentAliases": ["xiaohongshu", "xhs", "小红书"],
    "capabilities": ["collection", "analysis", "copywriting", "image-generation", "publish"]
  },
  "entries": [
    {
      "id": "workspace-entry",
      "type": "workspace-entry",
      "intentAliases": ["xiaohongshu", "xhs", "小红书"],
      "capabilities": ["collection", "analysis", "copywriting", "image-generation", "publish"]
    }
  ],
  "boundSkillIds": [
    "xhs-create-note",
    "xhs-pipeline",
    "xhs-publish-note",
    "xhs-research"
  ],
  "workspaceEntryEnabled": true,
  "ready": true
}
```

## workspace_entry.py 方案

`workspace_entry.py` 只作为 qjclaw 适配层，不重写小红书业务主流程。

职责：

- 解析 `--prompt`、`--prepared-prompt`、`--project-root`、`--session-id`。
- 读取客户端注入的附件环境变量，例如 `QJC_PROJECT_ATTACHMENTS_JSON`、`QJC_PROJECT_MAIN_IMAGE`。
- 将用户输入路由到采集、分析、生成、发布等已有脚本或函数。
- 将内部执行状态转换为 `QJC_WORKSPACE_EVENT\t{...}`。
- 输出 `started`、`status`、`completed`、`error`，必要时输出 `delta`。

最小事件格式：

```text
QJC_WORKSPACE_EVENT	{"type":"started","runId":"<session-id>"}
QJC_WORKSPACE_EVENT	{"type":"status","runId":"<session-id>","stage":"xhs","label":"Running XHS workflow"}
QJC_WORKSPACE_EVENT	{"type":"completed","runId":"<session-id>","content":"..."}
QJC_WORKSPACE_EVENT	{"type":"error","runId":"<session-id>","message":"..."}
```

## 模型和环境变量映射

客户端配置应在运行时写入项目环境，不提交 `.env`。

小红书项目当前依赖的关键环境变量：

- 文本/视觉模型：`QWEN_API_KEY`、`QWEN_MODEL`、`QWEN_VISION_MODEL`
- 图片生成：`ARK_API_KEY`、`VOLCENGINE_API_KEY`、`IMAGE_API_KEY`、`IMAGE_MODEL`、`ARK_IMAGE_MODEL`
- 小红书登录：`COOKIES`
- 飞书写入：`FEISHU_APP_ID`、`FEISHU_APP_SECRET`、`FEISHU_APP_TOKEN`、`FEISHU_TABLE_ID`、`FEISHU_TABLE_MAP`
- 采集控制：`XHS_FETCH_COMMENTS`、`XHS_STATUS_FILE`、`XHS_RUN_LOG_FILE`、`XHS_EVENTS_FILE`

接入时由 qjclaw 的项目执行链注入 `project.env`，不要让 renderer 直接读写密钥、cookie、runtime 文件或子进程。

## FastAPI 端口策略

`agent_server.py` 默认端口是 `8888`。接入 qjclaw 时不应把常驻 FastAPI 服务作为唯一入口。

推荐策略：

- 首选 `workspace_entry.py` 直接调用已有 Python 函数或 CLI。
- 若必须复用 FastAPI，则由 `workspace_entry.py` 按需启动本地服务并做端口探测。
- 避免固定占用 `8888` 导致多个项目或多次会话冲突。
- FastAPI 只作为内部适配手段，qjclaw 客户端可见状态仍通过 `QJC_WORKSPACE_EVENT` 返回。

## Python runtime 依赖

按当前 `requirements.txt`，需要纳入 runtime 安装/校验：

- `PyExecJS`
- `requests`
- `loguru`
- `python-dotenv`
- `retry`
- `openpyxl`
- `playwright`
- `openai`
- `fastapi`
- `uvicorn`
- `python-multipart`
- `pdfplumber`
- `python-docx`
- `certifi`

另需确认：

- Playwright Chromium 已安装。
- Windows runtime 可执行 Python 依赖安装。
- Node/npm 仅在确实需要 `plugin` 或 JS 侧辅助能力时保留，否则不要作为 qjclaw 主执行入口。

## Bundle 排除规则

必须排除：

- `.env`
- 小红书 Cookie
- 飞书 Secret
- 模型 API Key
- `datas/runtime`
- `datas/checkpoints`
- `datas/excel_datas`
- `datas/media_datas`
- `datas/generated`
- `datas/uploads`
- `datas/debug_pages`
- `node_modules`
- `__pycache__`
- `**/*.pyc`

应保留：

- Python 源码
- `requirements.txt`
- `project.json`
- `workspace_entry.py`
- 必需的 `apis`、`xhs_utils`、`plugin`、`asset-dropbox-understanding` 等项目能力目录
- 必需的静态 JS 辅助文件

## 抖音隔离

本方案不修改 `workspace\douyin`。

边界：

- 不改抖音项目代码。
- 不改抖音分支。
- 不复用抖音项目 ID、技能 ID 或业务状态文件。
- 只复用 qjclaw 通用执行链、bundle 机制、客户端配置注入机制和 smoke 验证方式。

## 实施顺序

1. 从 `workspace\xiaohongshu-client-package` 迁移或复制出 `workspace\xhs`。
2. 在 `workspace\xhs` 新增 `project.json`。
3. 在 `workspace\xhs` 新增 `workspace_entry.py`。
4. 将客户端模型、飞书、小红书 Cookie 配置映射到运行时环境变量。
5. 配置 `bundlePackaging.excludePaths`，确保密钥和历史运行数据不进入 bundle。
6. 先打通 CLI 直连执行，再决定是否保留 FastAPI 内部调用。
7. 用 smoke 验证 xhs 项目包、云端 bundle、客户端聊天入口。
8. 回归抖音 smoke，确认通用执行链没有被小红书适配破坏。

## 验证清单

适配完成后至少运行：

```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
```

通过标准：

- `xhs` 项目能被项目包 materialize。
- `xhs` 项目记录包含 `workspace-entry` 和 `boundSkillIds`。
- 运行时能收到 `QJC_WORKSPACE_EVENT`。
- 客户端聊天能得到小红书工作流的 `completed` 或明确 `error`。
- bundle 不包含 `.env`、Cookie、API Key、飞书 Secret 或历史运行数据。
- 抖音项目 smoke 仍通过。

