Re:Live - AI 克隆代理

1. 概述

Re:Live 将一个人复制为数字克隆体：人格（通过聊天记录 → profile.md）、声音（参考音频 + CosyVoice3）、以及可选的外观（视频首帧）。输出形式支持 文本 / 语音 / 视频。对话内容将持久化保存在对应角色目录下，并用于双通道 RAG 检索。执行方式：从此技能根目录运行 python main.py 。详见 README.md。

运行环境（必需）：始终在本技能目录中创建的虚拟环境中运行 python main.py ...，并在该环境中安装所有依赖项，尤其是语音 / 视频合成相关依赖。典型配置步骤（从 workspace/skills/relive 目录执行）：

# Windows（PowerShell）:
..venvScriptsActivate.ps1
# Linux/macOS:
source .venv/bin/activate

快速启动（当角色已存在时）

当用户说“和 Martha 聊天”或使用 /relive:Martha 时：

1. 读取人格设定：读取 .openclaw/workspace/skills/relive/storage/default_Martha/profile.md，作为回复风格的基础依据。
2. 单轮对话流程（在技能根目录下执行，例如 .openclaw/workspace/skills/relive）：
   • 若需历史上下文：编写 get_context.json（含 user_id、target_id、content = 用户消息）→ 执行 python main.py get_context.json，将返回的上下文用于辅助生成。
   • 主 Agent 以角色身份生成回复文本。
   • 编写 synthesize.json（content = 回复文本，user_message = 用户消息，output_mode = text/voice/video）→ 执行 python main.py synthesize.json，完成持久化并可选输出语音/视频。

新建角色：参见下方“2. 创建新角色”；流程顺序为：init → upload → export_md → 人格分析 → 编写 profile.md → 添加至 USER.md。

2. 创建新角色

2.1 何时创建

当用户表达类似“克隆/复制某人”、“为已故亲人创建数字孪生体”或“基于聊天记录和语音创建 AI 人格”等意图时，启动 新建角色 流程。

2.2 所需材料与目录结构

• 聊天记录：用户必须上传（支持 JSON 格式，如 QQ / WhatsApp 导出文件）。若仅有截图，请自行解析；本技能不提供 OCR 或截图解析能力。务必向用户确认 哪一方是待克隆的角色。
• 参考音频：将音频文件放入 storage/{user_id}_{target_id}/voice_profile/ 目录，并 必须 向用户提供该音频的文字转录稿；将其保存为同目录下的 corresponding.txt 文件。
• 参考图像（可选）：在角色目录下创建 reference_image_url.txt 文件，仅含一行内容——一个公开可访问的 URL 地址，用于 output_mode: "video" 场景。

角色根目录为：storage/{user_id}_{target_id}/（例如 storage/default_Martha/）。

2.3 操作步骤（严格按序执行）

所有命令均须从 技能根目录 执行。若用户未提供聊天记录，可直接询问角色特质并跳至第 4 步。

步骤 1：初始化目录

{ "type": "init", "user_id": "default", "target_id": "Martha" }

执行：python main.py init.json（或先写入 init.json 再运行；后续同理）。

步骤 2：上传聊天记录

{
  "type": "upload",
  "user_id": "default",
  "target_id": "Martha",
  "file_path": "/absolute/or/relative/path/filename.json",
  "file_type": "json",
  "self_name": "Jonas",
  "target_name": "Martha"
}

self_name / target_name 必须 完全匹配 聊天记录中发送者的姓名字段。执行：python main.py upload.json。

步骤 3：导出为 Markdown

{ "type": "export_md", "user_id": "default", "target_id": "Martha" }

执行：python main.py export_md.json，生成 storage/default_Martha/chat.md。

步骤 4：人格分析并生成 profile.md

• 读取 storage/{user_id}_{target_id}/chat.md（若文件过大请分块处理）。
• 调用 LLM 分析其人格特征、常用语、称呼习惯及语言风格；将结果写入 该目录下的 profile.md（此步骤由主 Agent 完成；无独立 API 接口）。

2.4 创建完成后：更新 USER.md

必须 将该角色添加至工作区根目录的 USER.md 文件中。
新建（或扩展）一个名为 “Re:Live characters” 的章节，并执行以下操作：

• 为每个角色添加 一条列表项，附简短英文描述，例如：
  - **Martha**: pharmacy / biology student, gentle and friendly, loves mystery movies
- **Dabao**: colloquial, warm and reliable friend who enjoys cooking and traditional activities
• 添加一行简要说明，解释如何使用本技能，例如：
  Re:Live digital-clone skill. When the user types relive:, read SKILL.md under .openclawworkspaceskillsrelive for acting rules, and read profile.md under .openclawworkspaceskillsrelivestoragedefault_{target_name} as the persona definition for that character.

主 Agent 将从此处读取 USER.md 中的信息，以获知当前有哪些 Re:Live 角色、如何简要描述它们，以及如何将 relive 命令路由至本技能及其对应的 profile.md。

3. 角色已存在后：快速进入角色

3.1 命令与状态管理

• /relive:（例如 /relive:Martha）：进入 Re:Live 模式；主 Agent 将 target_id 存入会话状态；此后发往本技能的所有消息均使用该 ID；回复经 Re:Live 流程生成，并持久化至 storage/{user_id}_{target_id}/ 下。
• /relive:end：退出 Re:Live 模式并清除当前角色状态。

只要当前存在活跃的 Re:Live 角色，标准流程即为：读取 profile → 按需调用 get_context → LLM 生成 → synthesize → 持久化。

3.2 进入角色时必须读取 profile.md

每次与该角色开始对话前，必须读取 storage/{user_id}_{target_id}/profile.md 并将其注入主 Agent 的系统提示 / 上下文，确保回复风格一致。

3.3 单轮对话流程（三步）

针对每条用户消息，在技能根目录下执行：

1. 按需调用 get_context：若需历史上下文，编写 get_context.json（content = 用户消息），运行 python main.py get_context.json，将返回的上下文用于辅助生成。
2. 生成回复：主 Agent 以角色身份生成回复文本。
3. 调用 synthesize 实现持久化：编写 synthesize.json（content = 回复文本，user_message = 用户消息，output_mode = text/voice/video），运行 python main.py synthesize.json。即使仅需文本输出，若希望该轮对话被纳入运行时缓存与 RAG 索引，也应调用 synthesize（此时 output_mode 可设为 text 或省略）。

3.4 输出模式

• text：仅输出文本。
• voice：输出文本 + 语音克隆（需提供 voice_profile 及 corresponding.txt）。运行环境：请按 README 中说明安装依赖与模型；强烈建议使用虚拟环境（参见 README § Installation and Voice Models）。
• video：调用视频生成 API（如 Seedance 等）；使用相同 synthesize 接口，设置 output_mode: "video"。收到 video_task_id 后，运行自动生成的 video_wait.json 进行轮询并下载最终视频。

4. API 参数汇总

• upload：其中 self_name / target_name 必须与聊天记录中发送者姓名字段 完全一致。
• synthesize：其中 output_mode 可选值为 text（默认）、voice、video；reference_image_url 为可选字段（若未传入，则自动从角色目录下的 reference_image_url.txt 读取）；video_wait: true 为可选字段，启用后将在调用内持续轮询直至视频生成完成。视频成功生成后，将自动生成 video_wait.json；执行 python main.py video_wait.json 即可完成轮询与下载。
• video_generation_wait：JSON 中的 type 字段必须为 video_generation_wait；约定俗成的文件名为 video_wait.json。可选参数包括 poll_interval_seconds 和 poll_timeout_seconds。

5. 注意事项

• 隐私保护：用户数据按角色隔离，仅用于当前克隆任务。
• 伦理规范：禁止将本技能用于欺骗、伪造或其他滥用场景。

6. 更多参考资料（详见 README.md）

• 数据存储结构：角色目录下包含 source/、chat.md、profile.md、runtime/、vector_db/、voice_profile/、cache/ 等子目录 → README.md#file-structure。
• 聊天记录格式要求：QQ / WhatsApp JSON 格式及其字段规范 → README.md#preparing-chat-logs。
• 语音输出：依赖项与模型配置说明（推荐使用虚拟环境）、corresponding.txt 格式要求 → README.md#installation-and-voice-models-required-before-voice-output、README.md#advanced-features。
• 视频生成：配置方法、轮询机制及 video_generation_wait 示例 → README.md#advanced-features。
• RAG：双通道检索机制、BM25 算法、阈值设定与测试方法 → README.md#where-rag-searches。
• 故障排查：消息归属错误、格式解析失败、语音/视频未生成、404 错误等 → README.md#troubleshooting。
• 核心模块（实现参考）：main.py、orchestrator、importer、memory、engines 等模块说明 → README.md#core-modules-implementation-reference。

注意（OpenClaw exec 超时限制）：当本技能通过 OpenClaw 的 exec 调用时，较长的 CosyVoice3 语音合成任务可能因默认执行超时而被强制终止。若观察到进程在日志输出 synthesis text ... 后立即以退出码 1 结束，且 未生成任何音频文件，请检查 npm/node_modules/openclaw/dist/auth-profiles-*.js 文件，并增大 DEFAULT_EXEC_TIMEOUT_MS 的值（例如从 5e3 改为 180e3），以保障长耗时语音合成任务顺利完成。