docs: organize client integration notes

97645407 · AI-甘富林 · 657746b3 · 97645407 · 97645407 · 97645407
Commit 97645407 authored Apr 29, 2026 by AI-甘富林
6 changed files
--- a/docs/0428问题.md
+++ b/docs/0428问题.md
+排查结论：问题真实存在，根因在 workspace/xhs/workspace_entry.py:859。
+
+  事实链：
+
+  - 第一次确认后，状态是 awaiting_confirmation。
+  - 用户说“采集1条就行”不是“确认”，代码会在 workspace/xhs/workspace_entry.py:859 清掉原来的关键词/业务需求/目标人群，重新分类。
+  - 重新分类时，extract_collect_params("采集1条就行") 实际得到：
+    {"xhs_action":"collect","keywords":["1条就行"],"total_count":1}
+  - 所以它随后提示还缺 business_need、target_audience，再补充后就变成“关键词：1条就行”。
+
+  影响范围：只影响“确认页之后用户补充/修改采集数量”的多轮采集流程；不是采集执行、生成内容、飞书上传本身的问题。
+
+  建议修复点：awaiting_confirmation 状态下，如果用户输入的是“采集1条/改成1条/1条就行”，应合并到原 payload 的 total_count，保留原 keywords/business_need/target_audience，然后重新展示确认页。
+
+
+  ## Summary
+
+  - 目标：用户在确认页后说“采集1条就行 / 改成3条 / 1条”时，只更新采集数量，不丢失已确认的关键词、业务需求、目标人群。
+  - 原则：不靠固定句子硬编码，基于“当前会话状态 + 字段级增量解析 + payload 合并”处理。
+
+  ## Key Changes
+
+  - 在 awaiting_confirmation 状态下，除“确认/取消”外，不直接清空状态。
+  - 对用户新输入做字段级解析：
+      - 若能解析出 total_count，合并进原 payload。
+      - 若解析出关键词、业务需求、目标人群，也只覆盖对应字段。
+      - 未解析出有效字段时，再按现有逻辑结束当前确认状态并重新分类。
+  - 抽出通用增量解析函数，例如 extract_collect_updates(text)：
+      - 支持数量表达：1条、采集1条、改成1条、一条、只要1条。
+      - 返回结构化字段，不返回完整新任务，避免把“1条就行”当关键词。
+  - 调整关键词提取规则：
+      - 采集动词后如果主体是数量/确认/修改语义，不作为关键词。
+      - 关键词仍通过原主题句或显式“关键词是...”提取。
+
+  ## Risks
+
+  - 风险 1：过度合并，把用户的新任务误当成修改旧任务。
+      - 控制方式：只有当前状态是 awaiting_confirmation 且输入解析到明确字段修改时才合并。
+  - 风险 2：数量中文表达解析不全。
+      - 控制方式：复用现有中文数字解析 parse_ref_index 思路，扩展为通用 1-20 数量解析。
+  - 风险 3：影响确认后的重新发起任务。
+      - 控制方式：如果输入包含新的完整采集主题和关键词，则按新任务重新分类，不合并旧 payload。
+  - 风险 4：LLM 与本地正则结果不一致。
+      - 控制方式：确认态下优先使用本地字段级解析；LLM 只用于新任务分类，不用于覆盖完整 payload。
+
+  ## Test Plan
+
+  - 复现原问题：
+      - 帮我采集 推荐上海平价川味火锅的笔记
+      - 种草引流涨粉 给热爱美食的人看
+      - 采集1条就行
+      - 期望确认页关键词仍是“推荐上海平价川味火锅”，采集数量为 1。
+  - 数量修改：
+      - 确认页后输入 改成3条
+      - 期望只更新 total_count=3。
+  - 直接确认：
+      - 确认页后输入 确认
+      - 期望行为不变，进入采集执行。
+  - 新任务覆盖：
+      - 确认页后输入 帮我采集北京烤肉笔记
+      - 期望按新任务重新进入参数确认，不沿用旧关键词。
+  - 回归：
+      - python -m py_compile workspace\xhs\workspace_entry.py
+      - corepack pnpm smoke:xhs-local-project-package
\ No newline at end of file
--- a/docs/2026-04-24-抖音客户端配置接入进度.md
+++ b/docs/2026-04-24-抖音客户端配置接入进度.md
+# 2026-04-24 抖音客户端配置接入进度
+
+## 2026-04-25 当前状态
+截至 2026-04-25，抖音项目这一轮的主结论如下：
+
+- 客户端真实配置注入链路已打通，运行时以客户端配置为主口径
+- `workspace_entry.py` 的 pending intake / continue 主链路已恢复到可验证状态
+- `VectCut` 已从本轮阻断项中移除，不再作为抖音运行时必填
+- 客户端聊天附件入口已从“仅图片”扩展为“图片 + 通用资料文件”
+- PDF 附件已在桌面 smoke 中完成真实落盘验证
+
+当前更准确的表述不是“只差 UI 验收”，而是：
+
+- 配置接入、运行时注入、pending intake 回归、通用附件上传已经完成并有验证
+- 下一阶段仍然是客户端真实聊天验收
+
+## 本轮新增完成项
+
+### 1. 客户端真实配置接入
+- 客户端设置保存后，抖音项目运行时改为从客户端配置注入 `project.env`
+- `QJC_CLIENT_CONFIG_ACTIVE=1` 已在 smoke 中确认
+- 抖音相关模型配置已覆盖：
+  - `VIDEO_LLM_ANALYZER_*`
+  - `REPLICATION_BRIEF_*`
+  - `SEEDANCE_*`
+  - `VOLC_*`
+  - `QINIU_*`
+- `VectCut` 不再是本轮闭环前置阻断项
+
+### 2. Pending Intake 回归修复已稳定
+- `run_intake()` 已恢复为可调用主路径
+- `workspace_entry.py` 的 pending intake / continue 逻辑已重新验证
+- 当前不再继续主动改 `run_from_request.py` / `coordinator.py` 主业务编排
+
+### 3. 客户端通用附件上传已接入
+- 共享类型 `ChatAttachment.kind` 已从仅 `image` 扩展为 `image | file`
+- 桌面端新增统一附件选择接口 `pickAttachments()`
+- 当前聊天附件支持：
+  - 图片：`png/jpg/jpeg/webp/gif/bmp`
+  - 文档资料：`pdf/ppt/pptx/xls/xlsx/csv/tsv/doc/docx/txt/md/json`
+- 图片继续落到 `inputs/images/main`
+- 文档资料落到 `inputs/assets/manual`
+- 聊天输入支持多附件发送
+
+### 4. PDF 真实样本 smoke 已通过
+本轮使用以下真实样本完成验证：
+
+- `C:\Users\EDY\Desktop\douyin-example\2025欧文酵室招商手册(1).pdf`
+
+已确认的事实：
+
+- smoke 中附件类型为 `file`
+- PDF 被真实落盘到项目目录：
+  - `projects/douyin/inputs/assets/manual/...pdf`
+- assistant 回复中已包含 `Project attachments:` 回显
+- 说明附件没有停留在 UI 层，而是实际进入了抖音项目工作区
+
+## 已完成范围
+- 客户端抖音模型配置读写、保存、注入
+- 抖音运行时 `project.env` 注入
+- `workspace_entry.py` 的 pending intake / continue 适配
+- `run_intake()` 回归修复
+- `VectCut` 非阻断化
+- 客户端聊天附件从“仅图片”扩展到“通用资料文件”
+- PDF 资料落盘到 `inputs/assets/manual`
+- smoke 对真实配置和真实 PDF 的验证
+
+## 当前未完成范围
+- Pending Intake UI 手工闭环验收
+- 三条业务链路聊天闭环验收
+- OmniHuman / Seedance 聊天闭环验收
+- 验收过程中暴露问题后的针对性回修
+
+## 下一步顺序
+1. Pending Intake UI 闭环验收
+2. `research_replication + crawler`、`specified_sample + link`、`direct_creation + none` 三条链路聊天闭环验收
+3. OmniHuman / Seedance 聊天闭环验收
+4. 若验收暴露问题，再做最小范围回修
+
+## 边界
+- 不主动重写 `run_from_request.py` 三条主链路逻辑
+- 不主动重写 `coordinator.py` 主业务编排
+- `VectCut` 继续排除在本轮主线通过门槛之外
+
+## 验证记录
+- 2026-04-25：`python workspace/douyin/test_intake_integration.py` 28/28 通过
+- 2026-04-25：`python workspace/douyin/test_pending_intake.py` 68/68 通过
+- 2026-04-25：`corepack pnpm typecheck` 通过
+- 2026-04-25：`corepack pnpm build` 通过
+- 2026-04-25：`build/scripts/douyin-expert-cloud-bundle-smoke.ps1 -SettingsConfigPath "C:\Users\EDY\Desktop\龙虾密钥&模型配置信息.txt" -AttachmentFixturePath "C:\Users\EDY\Desktop\douyin-example\2025欧文酵室招商手册(1).pdf" -SkipMaterializeRuntime`
+  - 真实配置注入通过
+  - PDF 附件落盘通过
+  - assistant `Project attachments:` 回显通过
+  - 首次运行仍偶发 `Gateway connection closed (1012)`，重试后通过
+
+## 2026-04-26 最新进度
+
+### 已验证通过
+- 客户端真实聊天链路中，上传 PDF 并描述需求后，可以走通纯画面 Seedance 视频生成。
+- 已修复 Seedance split 最终视频 0 秒 / 缺音轨问题：
+  - `run_pipeline.py` 在无 `ffprobe` 时改用 `ffmpeg -i` 兜底解析媒体时长。
+  - audio compose 前后增加最终产物校验，避免 0 秒视频被写成 success。
+  - `workspace_entry.py` 已支持读取 `results.video_seedance.manifest` 内的嵌套最终视频字段，并在必要时用 `final_video_concat.mp4 + narration_audio_path` 兜底重新 mux。
+- 已用坏产物目录验证修复：
+  - `E:\testworkspace2\projects\douyin\output\招商\seedance-split-runs\20260426-184026`
+  - 修复后 `final_video.mp4` 时长约 30 秒，包含视频流和音频流。
+  - `latest_seedance_split.mp4` 已同步更新。
+- `D:\qjclaw\workspace\douyin` 已重新打包上传到云端配置。
+- 本地开发版客户端已重启，`5173` 和内置网关 `18889` 正常监听。
+
+### 当前仍有问题
+- 数字人口播链路仍待排查。
+- 上传音频 + 数字人图片生成链路仍待排查。
+- 输入抖音链接并走样本/复刻相关链路仍待排查。
+- Seedance 平台返回 `OutputVideoSensitiveContentDetected` 时，目前按平台拒绝生成处理，只提示用户调整需求，不做自动改写 prompt。
+
+### 下一步建议
+1. 先验证数字人口播：确认音频、数字人图片、模型配置、输出目录和失败日志。
+2. 再验证“传音频 + 数字人图片”链路：区分是附件落盘、参数传递、OmniHuman 调用还是后处理失败。
+3. 最后验证抖音链接链路：重点看 crawler/downloader/analyzer/selected sample continue 是否在客户端聊天里闭环。
\ No newline at end of file
--- a/docs/2026-04-27-小红书客户端接入适配方案.md
+++ b/docs/2026-04-27-小红书客户端接入适配方案.md
+# 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 仍通过。
+
--- a/docs/2026-04-27-小红书自然语言入口优化方案.md
+++ b/docs/2026-04-27-小红书自然语言入口优化方案.md
+# 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 全部通过。
--- a/docs/报错修复方案.md
+++ b/docs/报错修复方案.md
+报错：
+这个是通过上传pdf生成纯画面视频报错：
+[ERROR] Generate Seedance split video failed with exit code 1. See E:\testworkspace2\projects\douyin\output\分析一下这个文件\video_seedance_stderr.txt | split_error=Seedance clip 1 failed. See E:\testworkspace2\projects\douyin\output\分析一下这个文件\seedance-split-runs\20260427-095752\shots\shot-01\stderr.txt
+=== Douyin Master Workflow ===
+Route: 直出创作链
+Source mode: 不走样本调研
+Core keyword: 分析一下这个文件
+Product: 分析一下这个文件
+Audience: 加盟创业人群
+Type: 纯画面视频
+Normalized type: 纯画面视频
+Writer type: 知识干货
+Requested video engine: auto
+Project folder: 分析一下这个文件
+Attempt id: 20260427-095748-052712
+Output dir: E:\testworkspace2\projects\douyin\output\分析一下这个文件
+Direct image Seedance mode: True
+Detected image-driven Seedance request without narration; skip preview copywriting stage.
+[status] preview_packaging | 33%（2/6） | 文案生成 | 正在整理预览文件
+Resolved video engine: seedance
+[status] video_seedance | 67%（4/6） | 视频生成 | Generate Seedance split video
+[video_seedance] Generate Seedance split video
+[status] video_seedance | 67%（4/6） | 视频生成 | Generate Seedance split video 失败
+
+
+这个是给抖音链接数字人口播视频报错：
+
+修复抖音工作流两个失败：抖音下载器 + Seedance PDF 图片格式                                                                                                                                                                                                                                              nage
+ Context
+
+ 用户运行了两个抖音工作流任务，分别在不同阶段失败：
+
+ 1. 宣传一下我家面包店 — 在 "样本准备" 阶段失败，douyin downloader 无法下载抖音视频
+ 2. 分析一下这个文件 — 在 "视频生成" 阶段失败，Seedance API 返回 InvalidParameter.UnsupportedImageFormat，因为 PDF 文件被当作参考图传入了只支持 JPG/PNG/WebP 的 API
+
+ 错误 1：抖音视频下载失败
+
+ - 错误: Error: Unable to parse video detail from page; fallback failed:
+ - 位置: E:\testworkspace2\projects\douyin\skills\douyin-video-downloader\scripts\douyin.js + run_downloader.py
+ - 原因: Node.js 解析器和 Playwright 备用方案都无法从抖音页面提取视频信息。可能是抖音 HTML 结构变化或反爬措施
+
+ 错误 2：Seedance PDF 作为图片传入 API
+
+ - 错误: Seedance create task failed with HTTP 400. InvalidParameter.UnsupportedImageFormat
+ - API 请求中的问题 URL: http://tcwwu6wg4.hd-bkt.clouddn.com/omnihuman/reference-image/...pdf
+ - 根因链:
+   a. 用户上传了 PDF 文件（2025欧文酵室招商手册(1).pdf）
+   b. coordinator.py:5486 — 当 seedance_image 为空时，回退使用 self.config.image（即 PDF 路径）
+   c. coordinator.py:11286 — resolved_seedance_image = self.config.seedance_image or self.config.image
+   d. 该 PDF 被上传到七牛，但保留 .pdf 扩展名
+   e. run_seedance.py:normalize_media_input() — 对远程 URL 不做格式验证，直接传入 API
+   f. Seedance API 拒绝 PDF 格式
+
+ 修复方案
+
+ Fix 1：Seedance 图片格式校验（高优先）
+
+ 文件: E:\testworkspace2\projects\douyin\skills\douyin-master\scripts\coordinator.py
+
+ 在 materialize_project_inputs() 方法中（约 line 5399），当 seedance_image 回退到 self.config.image 时，检查文件是否为 Seedance 支持的图片格式。如果是 PDF，则改用 asset_understanding 提取的图片（已有 extracted_images/ 目录，包含从 PDF
+ 提取的 JPG 页面图）。
+
+ 具体改动：
+ - 在 line 5484-5487（seedance_image 回退逻辑）之前，添加 PDF 检测：
+   - 如果 self.config.image 以 .pdf 结尾，查找 asset_understanding/extracted_images/ 下的 JPG 文件
+   - 使用第一个提取的 JPG 作为 seedance_image
+   - 如果没有提取图片，保持 seedance_image 为空（让 Seedance 用 prompt 生成首帧图）
+
+ 同时在 run_seedance.py 的 normalize_media_input() 中添加远程 URL 格式校验（防御性修复）：
+ - 对 media_kind == "image" 的远程 URL，检查扩展名是否为 .jpg/.jpeg/.png/.webp
+ - 不支持的格式直接跳过（不做 reference），而不是让 API 400 报错
+
+ Fix 2：抖音下载器（低优先，需更多调查）
+
+ 文件: E:\testworkspace2\projects\douyin\skills\douyin-video-downloader\scripts\douyin.js + run_downloader.py
+
+ 抖音下载器失败是外部依赖问题（抖音反爬/HTML结构变化），需要：
+ 1. 手动测试 douyin.js 能否用新 URL 正常工作
+ 2. 检查 Playwright 浏览器是否正确安装（vendor/openclaw-runtime/ 内的 Chromium）
+ 3. 可能需要更新解析器适配抖音新页面结构
+
+ 这个修复比较复杂且涉及第三方网站变化，建议先手动下载视频作为替代方案。
+
+ 关键文件（源码在 D:\qjclaw\workspace\douyin\，运行时副本在 E:\testworkspace2\projects\douyin\）
+
+ - D:\qjclaw\workspace\douyin\skills\douyin-master\scripts\coordinator.py — 主要修复点：PDF→JPG 回退逻辑
+ - D:\qjclaw\workspace\douyin\skills\seedance-2-0-video-generator\scripts\run_seedance.py — 防御性修复：远程 URL 格式校验
+ - D:\qjclaw\workspace\douyin\skills\douyin-asset-understanding\ — PDF 图片提取（已有功能，直接复用）
+
+ 修改源码后，需要重新打包 zip 上传到云端或本地替换，让工作流使用修复后的代码。
+
+ 验证
+
+ 1. 修改 coordinator.py 后，重新提交一个带 PDF 附件的抖音任务，确认 Seedance 使用提取的 JPG 而非 PDF
+ 2. 检查 task_create.json 中的 image_url 不再包含 .pdf 扩展名
+ 3. 确认 Seedance API 返回成功（HTTP 200/201）而非 400
+
--- a/会话卡片样式分析报告.md
+++ b/会话卡片样式分析报告.md
-# 会话卡片 (Sidebar Session Card) 样式分析报告
-
-## 分析日期
-2024年4月24日
-
-## 分析文件
-`D:/qjclaw/apps/ui/src/styles.css`
-
---
-
-## 问题总结
-
-### 1. 重复样式定义
-会话卡片样式被**重复定义了4次**，在不同位置有不同的属性配置：
- 行 495-512：基础样式 + 选中状态（符合设计系统）
- 行 2088-2091：极简样式（仅定义 padding 和 border-radius）
- 行 3160-3170：基础样式 + 选中状态（不符合设计系统，使用绿色系）
- 行 3322-3333：完整布局样式（固定高度、网格布局）
-
-### 2. 颜色系统不一致
-**最严重的问题**是第 3166-3170 行的选中状态样式完全使用了绿色系（青色）：
-
-```css
-/* 错误的样式（行 3166-3170） */
-.sidebar-session-card.active {
-  border-color: rgba(13, 148, 136, 0.18); /* 深青色 - 非主题色 */
-  background: linear-gradient(180deg, rgba(240, 251, 249, 0.98), rgba(236, 247, 245, 0.96)); /* 青绿色渐变 */
-  box-shadow: 0 12px 26px rgba(13, 148, 136, 0.06); /* 青绿色阴影 */
-}
-```
-
-而设计系统的主色调应该是蓝紫色系：
-
-```css
-/* 正确的样式（行 508-512） */
-.sidebar-session-card.active {
-  border-color: rgba(139, 92, 246, 0.2); /* 蓝紫色边框 - 符合设计系统 */
-  background: rgba(139, 92, 246, 0.05); /* 淡紫色背景 */
-  box-shadow: var(--shadow-sm); /* 设计系统阴影变量 */
-}
-```
-
-### 3. 硬编码属性值过多
- **圆角**：使用 `12px`、`16px`、`14px` 等硬编码值，未统一使用 `--radius-md/lg/xl` 变量
- **间距**：使用 `6px`、`8px`、`10px` 等硬编码值，未统一使用 `--space-2/3/4` 变量
- **阴影**：部分使用自定义阴影值，未使用 `--shadow-*` 变量
- **背景**：使用 `rgba(247, 250, 255, 0.92)` 等硬编码值，未使用 `--color-bg-*` 变量
-
-### 4. 缺少响应式设计
-当前没有专门针对 `.sidebar-session-card` 的响应式样式，只对容器级别的组件（如 `.shell`、`.sidebar`）有响应式规则。
-
---
-
-## 修复建议
-
-### 方案一：合并并统一样式（推荐）
-
-#### 统一基础样式
-```css
-.sidebar-session-card {
-  min-height: 40px;
-  height: 60px;
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) auto;
-  gap: var(--space-2);
-  align-items: center;
-  padding: var(--space-2);
-  border-radius: var(--radius-lg);
-  border: 1px solid transparent;
-  background: rgba(247, 250, 255, 0.92);
-  box-shadow: var(--shadow-xs);
-  transition: all 0.2s ease;
-}
-
-.sidebar-session-card.active {
-  border-color: var(--color-border-medium);
-  background: rgba(139, 92, 246, 0.05);
-  box-shadow: var(--shadow-sm);
-}
-```
-
-#### 响应式适配
-```css
-/* 大屏幕 */
-@media (min-width: 1200px) {
-  .sidebar-session-card {
-    padding: var(--space-3);
-    border-radius: var(--radius-xl);
-  }
-}
-
-/* 中等屏幕 */
-@media (max-width: 1200px) {
-  .sidebar-session-card {
-    padding: var(--space-2);
-    border-radius: var(--radius-lg);
-  }
-}
-
-/* 小屏幕 */
-@media (max-width: 720px) {
-  .sidebar-session-card {
-    height: auto;
-    min-height: 56px;
-    padding: var(--space-2);
-    border-radius: var(--radius-md);
-  }
-}
-```
-
-### 方案二：快速修复（仅修正颜色）
-
-至少将第 3166-3170 行的绿色系样式替换为蓝紫色系：
-
-```css
-.sidebar-session-card.active {
-  border-color: var(--color-border-medium); /* 替换 rgba(13, 148, 136, 0.18) */
-  background: rgba(139, 92, 246, 0.05); /* 替换青绿色渐变 */
-  box-shadow: var(--shadow-sm); /* 替换自定义阴影 */
-}
-```
-
---
-
-## 设计系统变量查询表
-
-### 蓝紫色系颜色变量
-```css
-:root {
-  /* 主色系 */
-  --color-primary-50: #F5F3FF;     /* 超浅薰衣草 */
-  --color-primary-100: #EDE9FE;   /* 浅薰衣草 */
-  --color-primary-500: #8B5CF6;   /* 主色 - 薰衣草紫 */
-  --color-primary-600: #7C3AED;   /* 深薰衣草紫 */
-  
-  /* 边框颜色 */
-  --color-border-light: rgba(139, 92, 246, 0.12);
-  --color-border-medium: rgba(139, 92, 246, 0.2);
-  --color-border-strong: rgba(139, 92, 246, 0.3);
-  
-  /* 背景颜色 */
-  --color-bg-primary: var(--color-primary-50);
-  --color-bg-surface: #FFFFFF;
-  --color-bg-overlay: rgba(255, 255, 255, 0.92);
-  
-  /* 阴影 */
-  --shadow-xs: 0 1px 2px rgba(139, 92, 246, 0.05);
-  --shadow-sm: 0 2px 4px rgba(139, 92, 246, 0.08);
-  --shadow-md: 0 4px 8px rgba(139, 92, 246, 0.12);
-  
-  /* 圆角 */
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --radius-xl: 16px;
-  
-  /* 间距 */
-  --space-2: 8px;
-  --space-3: 12px;
-  --space-4: 16px;
-}
-```
-
---
-
-## 风险评估与注意事项
-
-1. **样式覆盖问题**：由于有4处分散的样式定义，合并时需要确保新样式的优先级正确
-2. **布局影响**：修改高度、padding等属性时，需要测试对侧边栏整体布局的影响
-3. **浏览器兼容性**：使用CSS变量需要确保浏览器支持（现代浏览器均支持）
-
---
-
-## 验证步骤
-
-1. 备份原文件 `styles.css`
-2. 实施修复方案
-3. 启动开发服务器，测试会话卡片的显示
-4. 检查选中状态的样式是否符合蓝紫渐变主题
-5. 测试响应式布局是否正常
-6. 确保所有功能按钮和交互效果正常工作
-