docs(projects): add douyin xhs working notes

docs/douyin-xhs-插入/2026-04-10-客户端抖音专家附件打通计划.md

+# 客户端抖音专家附件打通计划
+
+Status: proposed
+
+Date: 2026-04-10
+
+## 1. 背景
+
+当前客户端到 Douyin expert 的主链路，已经基本具备：
+
+1. 专家页选择 `douyin` 项目
+2. 会话绑定到 `project:douyin:*`
+3. 默认命中项目 `workspace-entry`
+4. 启动项目级执行链路
+
+但这条链路目前仍然基本是“纯文本对话链路”。
+
+对 Douyin 项目来说，这会直接卡住数字人能力，也会限制纯画面路线里的引用素材输入。
+
+## 2. 当前代码事实
+
+### 2.1 已打通部分
+
+- 专家页可以命中项目级 `workspace-entry`
+- Douyin 本地纯画面工作流已经有真实成功样例
+- Douyin 主流程已支持：
+  - `--image`
+  - `--audio`
+  - `--seedance-reference-image`
+  - `--seedance-reference-video`
+  - `--seedance-reference-audio`
+
+### 2.2 当前明确缺口
+
+- 客户端专家页输入框目前只有文本输入，没有图片上传入口
+- `DesktopApi.chat.sendPrompt()` / `streamPrompt()` 当前只有：
+  - `sessionId`
+  - `prompt`
+  - `skillId`
+- IPC 层当前也只透传纯文本 prompt
+- `project-workspace-executor` / `project-workspace-agent-runner` 当前只有文本 prompt 输入，没有附件协议
+- Douyin 数字人链路当前明确要求必须有图片
+
+### 2.3 对 Douyin 的直接影响
+
+- 数字人路线：当前客户端无法把图片传给 expert，因此无法从客户端直接跑通数字人
+- 纯画面路线：无图纯文案可以跑，但参考图 / 参考视频 / 参考音频能力当前无法从客户端输入
+
+## 3. 目标
+
+本次目标不是一次性做完整多模态聊天，而是先补齐最小闭环：
+
+1. 客户端专家页支持选择并发送 1 张本地图片
+2. 图片在 main 进程被复制到当前项目目录下的稳定路径
+3. `workspace-entry` 能收到这张图的结构化输入
+4. Douyin expert 能把这张图用于数字人主图输入
+5. smoke 不再只验证 `workspace-entry launch`，至少验证“附件已进入项目执行层”
+
+## 4. 方案范围
+
+### 4.1 本次纳入
+
+- 图片附件协议
+- 专家页单图上传
+- main 进程项目内落盘
+- `workspace-entry` 附件透传
+- Douyin expert 单图数字人最小闭环
+- smoke 验证升级
+
+### 4.2 本次不纳入
+
+- 多图上传
+- 音频上传
+- 剪贴板图片
+- URL 素材粘贴
+- 通用多模态聊天体系重构
+- 去修改 Douyin 项目“数字人必须传图”的业务约束
+
+## 5. 实施方案
+
+### 5.1 聊天协议与 IPC
+
+扩展以下调用签名，新增可选 `attachments`：
+
+- `DesktopApi.chat.sendPrompt`
+- `DesktopApi.chat.streamPrompt`
+
+新增最小附件结构，v1 先只支持图片：
+
+- `kind: "image"`
+- `name`
+- `mimeType`
+- `localPath`
+
+要求：
+
+- 与当前纯文本调用兼容
+- 无附件时行为保持不变
+- renderer -> preload -> ipc -> main 全链路统一使用同一份附件结构
+
+### 5.2 专家页 UI
+
+在现有 composer 上补一个最小上传入口：
+
+- 支持选择 1 张本地图片
+- 已选择图片可见
+- 重选时以最后一次选择覆盖
+- 发送成功后清空附件
+- 发送失败时保留附件，便于重试
+
+本阶段不引入复杂交互：
+
+- 不做多图排序
+- 不做拖拽上传
+- 不做素材管理器
+
+### 5.3 Main 进程项目内落盘
+
+main 进程收到图片后，不直接把临时路径传给项目，而是先复制到当前项目目录：
+
+- 目标目录：`inputs/images/main/`
+
+要求：
+
+- 生成稳定文件名
+- 绑定当前 `projectId` / `sessionId`
+- 禁止跨项目复用错误路径
+- 会话未绑定项目时直接返回明确错误
+
+### 5.4 Workspace-entry 执行层
+
+扩展：
+
+- `ProjectExecutionRequest`
+- `ProjectWorkspaceExecutionInput`
+- `project-workspace-agent-runner` 的输入结构
+
+执行策略：
+
+- 保留原始 `prompt`
+- 同时透传 `attachments`
+- 如果当前 bundled agent 暂时不能直接吃结构化图片输入，则在 runner 层集中做一次降级，把图片路径转换成稳定提示注入
+
+约束：
+
+- 不在 renderer 层拼接图片说明
+- 不在多个中间层重复组装 prompt
+- 所有附件降级策略集中在执行层单点处理
+
+### 5.5 Douyin expert 约定
+
+v1 统一约定：
+
+- 客户端上传的单张图片，默认视为“数字人主图 / main image”
+
+这样可以先解当前最刚需的场景：
+
+- 从客户端对话 Douyin expert
+- 上传人物图
+- 继续生成数字人口播视频
+
+纯画面路线后续可以复用同一套附件协议，再细分为：
+
+- `seedance_image`
+- `reference_image`
+- `reference_video`
+- `reference_audio`
+
+但这些不作为本次第一阶段的强验收项。
+
+## 6. 验收标准
+
+### 6.1 功能验收
+
+满足以下结果即视为本阶段完成：
+
+1. 专家页可选择并发送 1 张图片
+2. 图片能落到当前项目 `inputs/images/main/`
+3. Douyin expert 在项目执行层能读取到该图片路径
+4. 数字人路线不再因为“客户端无法传图”而阻断
+
+### 6.2 回归要求
+
+以下行为不能被破坏：
+
+1. 无附件的纯文本专家对话行为不变
+2. 当前已打通的 `workspace-entry` 路由不回退为 skill fallback
+3. 现有 Douyin 纯画面文本生成链路不回归
+
+### 6.3 smoke 验收
+
+至少新增或升级以下验证：
+
+1. 专家页上传图片后，附件成功透传到项目执行层
+2. `douyin expert cloud-bundle smoke` 不再只接受 `workspace-entry launch`
+3. 保留现有纯文本 smoke，确保兼容旧行为
+
+如果环境允许，再补一条本地真实验证：
+
+1. 上传人物图
+2. 用文案 + TTS 走数字人
+3. 输出 `video_omnihuman.json` 或等效成功产物
+
+## 7. 实施顺序
+
+建议按以下顺序推进，避免前后返工：
+
+1. 先补 shared types / preload / ipc 的附件协议
+2. 再补专家页单图上传 UI
+3. 再补 main 进程项目内落盘
+4. 再补 workspace-entry executor / runner 附件透传
+5. 最后补 Douyin smoke 和真实验证
+
+## 8. 默认假设
+
+- v1 只支持单张图片
+- v1 只支持本地文件
+- v1 不支持音频上传
+- v1 不改 Douyin 数字人必须传图的既有约束
+- 结构化多模态能力如果当前 runtime 未直接支持，允许 runner 层先做集中降级适配

docs/douyin-xhs-插入/2026-04-10-新电脑初始化真实自动化一周计划.md

+# 新电脑初始化真实自动化一周计划
+
+Status: proposed
+
+Date Range: 2026-04-10 to 2026-04-16
+
+## 1. 目标
+
+本周目标不是“开发机可以跑”，而是把下面这条链路做成可验收的稳定闭环：
+
+1. 新电脑安装客户端
+2. 用户输入 employee key
+3. 客户端调用 `https://spb-bp1wv2oe0hvfvi98.supabase.opentrust.net/functions/v1/openclaw-employee-config`
+4. 从返回的 `skills[].skill.download_url` 识别抖音 / 小红书 zip 项目包
+5. 客户端自动下载并解压到本地工作区
+6. 专家页出现对应项目
+7. 用户发送一句自然语言
+8. 客户端命中项目 `workspace-entry`
+9. 本地真实启动 Python / Playwright 自动化链路
+
+## 2. 本周验收标准
+
+本周结束时，至少满足以下结果：
+
+1. 空白用户目录下首次安装，保存 employee key 后可自动完成 `init` 拉取和项目同步
+2. `workspaceSummary` 中能看到非 home 项目，且 `currentProjectId`、`projectReady` 为真
+3. 专家页发一句话时，默认走 `workspace-entry`，而不是 skill fallback
+4. bundled runtime 不再因 `_greenlet` 或 `async_playwright` 导入失败而阻断真实自动化
+5. 项目运行态在 bundle 更新后不会因为目录替换而丢失
+6. 小红书项目在 fresh install 路径下完成至少一次真实自动化启动验证
+
+## 3. 范围
+
+本周纳入：
+
+- `openclaw-employee-config` 返回契约与客户端解析契约对齐
+- project bundle 标准化
+- bundled runtime 依赖与探测硬化
+- installer / experts 真实链路 smoke
+- 小红书项目运行态迁移到 `memory/`
+- 项目级 skill 展示与校验收口
+
+本周不纳入：
+
+- “扫描 `skills/*/SKILL.md` 自动反推项目”的重构
+- 项目 skills 的彻底物理隔离重构
+- 超出当前 bundled runtime 能力的大规模新依赖体系设计
+
+## 4. 关键事实基线
+
+- 当前客户端已经有 `employee-key -> runtime cloud fetch -> zip bundle sync -> project inventory -> experts page -> workspace-entry` 主链路
+- 当前最大 fresh install 风险在 bundled runtime 的 Python 依赖校验过浅，尤其是 `greenlet` / `async_playwright`
+- 当前 project bundle 缺失 `project.json` 时仍会被客户端降级猜测，不适合正式交付
+- 当前项目运行态只保留 `sessions.json`、`session-messages/`、`memory/`，所以所有可变状态必须迁入 `memory/`
+- 当前 `listProjectSkills()` 仍会混入 curated generic skills，不满足“进入项目后只看该项目能力”
+
+## 5. 每日计划
+
+### Day 1: 2026-04-10
+
+目标：冻结契约，避免后续实现反复返工。
+
+任务：
+
+- 明确 `openclaw-employee-config` 返回字段的最小必需项
+- 明确 zip 项目包的标准交付契约
+- 明确 `project.json` 最低要求必须包含：
+  - `id`
+  - `name`
+  - `platform`
+  - `projectType`
+  - `workspaceAutomation`
+  - `defaultEntry`
+  - `entries`
+- 明确本周验收以小红书链路为主，抖音按同一标准补齐
+
+交付物：
+
+- 本文档
+- 项目包契约确认结论
+
+### Day 2: 2026-04-11
+
+目标：先堵住 fresh install 最容易失败的 bundled runtime 问题。
+
+任务：
+
+- 在 `build/runtime/python/requirements.in` 和锁文件中显式纳入 `greenlet`
+- 调整 `packages/runtime-manager/src/index.ts`
+- 把 Python payload 探测从 `find_spec` 提升为真实关键导入探测
+- 至少覆盖：
+  - `import greenlet`
+  - `from playwright.async_api import async_playwright`
+- 调整 installer smoke，同步校验上述关键导入
+
+交付物：
+
+- runtime 依赖更新
+- runtime 探测更新
+- installer smoke 更新
+
+验收点：
+
+- 打包 Python 环境可真实导入 `greenlet`
+- `pythonReady` 只在关键依赖通过时才为真
+
+### Day 3: 2026-04-12
+
+目标：把 bundle 接入从“能猜”改成“强契约”。
+
+任务：
+
+- 修改 `project-bundle.ts`
+- 安装后要求项目根必须存在标准 `project.json`
+- 缺失时 bundle sync 明确报错，不写入 ready project
+- 保留现有 rollback / replace / preserve local state 逻辑
+- 校验项目根结构兼容：
+  - zip 根就是项目根
+  - zip 根下 `projects/<projectId>`
+
+交付物：
+
+- bundle 解析与报错硬化
+- 缺失 `project.json` 的明确诊断
+
+验收点：
+
+- 非标准 zip 无法被静默安装成 ready project
+
+### Day 4: 2026-04-13
+
+目标：收口项目隔离表现，避免专家页误混全局能力。
+
+任务：
+
+- 修改 `project-store.ts`
+- `boundSkillIds` 与实际 `workspace/skills/<skillId>` 做交叉校验
+- 对缺失 skill 做诊断日志和降级处理
+- 专家项目视图下不再自动混入 curated generic skills
+- 保持 session 继续按 `project:<projectId>:<uuid>` 隔离
+
+交付物：
+
+- 项目 skills 列表收口
+- `boundSkillIds` 诊断
+
+验收点：
+
+- 进入 `xhs` 后只显示 `xhs` 绑定技能
+- 进入 `douyin` 后只显示 `douyin` 绑定技能
+
+### Day 5: 2026-04-14
+
+目标：把小红书项目调整到真正适合 bundle 替换的状态。
+
+任务：
+
+- 以 `workspace/xhs` 为模板，梳理真实自动化入口
+- 确保 `project.json` 包含 `workspaceAutomation`
+- 确保 `workspace_entry.py` 能处理自然语言 prompt
+- 把运行态迁移到 `memory/`
+- 重点清理这些项目根运行态：
+  - `xhs_profile`
+  - `generated_images`
+  - `openclaw_runs`
+  - `openclaw_debug`
+  - 其他浏览器态 / 草稿态 / 调试态文件
+
+交付物：
+
+- 可交付的小红书标准 bundle 源
+
+验收点：
+
+- bundle 替换后，小红书登录态和会话态仍保留
+
+### Day 6: 2026-04-15
+
+目标：让抖音项目按同一套标准补齐，而不是做特殊兼容。
+
+任务：
+
+- 给抖音项目补标准 `project.json`
+- 补 `workspaceAutomation` 与 `workspace_entry.py`
+- 校对 `boundSkillIds`
+- 确认抖音项目依赖不超出本周 bundled runtime 能力
+- 如超出，单独列出 runtime 扩容项，不在 bundle 内偷偷引入
+
+交付物：
+
+- 可交付的抖音标准 bundle 源
+
+验收点：
+
+- 抖音和小红书都能以“一包一项目”方式被客户端识别
+
+### Day 7: 2026-04-16
+
+目标：做真正的 fresh install 验收，而不是开发机自测。
+
+任务：
+
+- 用空白用户目录执行 installer smoke
+- 用空白用户目录执行 experts 页真实链路 smoke
+- 重点验证：
+  - employee key 初始化
+  - zip 下载与项目同步
+  - 专家页项目出现
+  - `workspace-entry` 命中
+  - 小红书真实自动化成功启动
+  - bundle 替换后 `memory/` 保留
+- 输出遗留问题清单和是否可以进入下周收尾
+
+交付物：
+
+- fresh install 验收结果
+- 遗留问题清单
+
+## 6. 文件级实施清单
+
+本周高优先级涉及的代码文件：
+
+- `apps/desktop/src/main/services/cloud-api.ts`
+- `apps/desktop/src/main/services/project-bundle.ts`
+- `apps/desktop/src/main/services/project-store.ts`
+- `apps/desktop/src/main/services/project-workspace-executor.ts`
+- `packages/runtime-manager/src/index.ts`
+- `build/runtime/python/requirements.in`
+- `build/runtime/python/runtime-requirements.lock.txt`
+- `build/scripts/installer-smoke.ps1`
+- `build/scripts/xhs-expert-cloud-bundle-smoke.ps1`
+- `build/scripts/xhs-expert-live-run.ps1`
+
+项目包侧高优先级文件：
+
+- `workspace/xhs/project.json`
+- `workspace/xhs/workspace_entry.py`
+- `workspace/douyin/project.json`
+- `workspace/douyin/workspace_entry.py`
+
+如果真实项目源不在仓库内，则需要同步维护一份与仓库规范一致的交付模板。
+
+## 7. 风险
+
+1. 若抖音或小红书项目依赖超出当前 bundled runtime，单靠 zip 交付无法解决
+2. 若真实自动化代码继续把运行态写在项目根，bundle 替换时仍会丢状态
+3. 当前项目 skills 仍是共享物化到 `workspace/skills`，若未来两个项目出现同名 skill，仍存在覆盖风险
+4. 如果服务端返回契约字段不稳定，fresh install 的初始化链路会出现非代码层问题
+
+## 8. 周末结论口径
+
+只有同时满足以下条件，本周工作才算达标：
+
+1. 新电脑或空白用户目录下首次安装可完成初始化
+2. employee key 触发的 `openclaw-employee-config` 可稳定下发 zip 项目包
+3. 客户端可自动把 zip 物化为 ready project
+4. 专家页可以直接选择项目并命中 `workspace-entry`
+5. 小红书真实自动化在 fresh install 环境下成功启动
+6. installer smoke 和 experts 真实链路 smoke 均通过
+
+如果只做到“项目能出现”或“开发机能跑”，但 fresh install 不稳定，则本周目标不算完成。