session-story

Session story

Agent 会读取自己与用户的对话历史，找出其中的规律，并按实际发生的顺序，将一次典型会话制作成一段 40 至 70 秒的影片：

• Story： 用户原话以物件的形式出现，Agent 的回复则回到用户那里。窗外的景象和墙上时钟都遵循会话发生时的真实时间。
• Room： 根据 Agent 对用户的了解进行装饰。
• Score： Agent 根据影片自身的时间线创作配乐。

编写 story.json，引擎就会完成编排。屏幕上的内容绝非虚构：每句话都是引文，而且每句话都会在渲染画面前由用户审核。

适用场景 / 不适用场景

• 适用：用户让自己的 Agent 制作一段记录双方协作过程的影片，而且 Agent 确实拥有与该用户的历史记录：本地转录内容，或用户粘贴的消息。
• 不适用：他人的历史记录、团队共享日志、包含杜撰引文的营销内容，或用户不愿审核的任何内容。如果完全没有历史记录，请向用户索取某次会话的消息。切勿编造引文。

要求和副作用（完整列表）

• 工具： Node 22+、Python 3.9+（仅标准库）、PATH 中的 ffmpeg，以及固定使用 npx --yes [email protected] 的 HyperFrames CLI（首次使用时从 npm 注册表下载）。
• 设置（手动执行一次）： sh scripts/setup.sh 会根据已提交的锁定文件运行 npm ci：p5 2.3.3 (LGPL-2.1)、p5.brush 2.2.3 (MIT)、@fontsource/permanent-marker 5.3.0 (Apache-2.0)。仅从 npm 下载，不会上传数据。
• 配乐渲染器： 在 macOS 上，swift（Xcode Command Line Tools）通过 Apple 内置的 General MIDI 音色库播放配乐。在其他平台上，使用 fluidsynth 和你设置为 SOUNDFONT 的 General MIDI 音色库。两者都不会下载任何内容。
• 读取内容（仅本地，且须用户同意）： Agent 自己的转录内容、当前项目下的 ~/.claude/projects/<project>/*.jsonl（Claude Code）和 ~/.codex/sessions（Codex），除非用户允许使用 --all-projects。房间布置也会读取 Agent 的记忆和指令文件。不会上传任何内容。
• 写入内容： session-story-candidates.json（收集结果）以及你创建的项目文件夹中的所有内容。这两处都包含用户的话：切勿提交或分享。
• 构建时的网络访问： 无。按照下方示例，为每个 snapshot 传入 --describe false：如果设置了 GEMINI_API_KEY，snapshot 否则会将帧（即用户的话）发送给 Gemini。在本地渲染：页面使用 WebGL 绘制。
• 无需凭据，也不会产生付费调用。

工作流

1. **设置：**运行一次 sh scripts/setup.sh。
2. **先征求同意。**告诉用户，你会和他们一起读取本地历史记录，以找到相应会话，然后等待他们答应。
3. **提取：**运行 python3 scripts/harvest.py --project <their project folder> --out <scratch>/candidates.json，查看例程，并按典型程度从高到低列出会话。添加 --session <id>（使用相同的 --project）即可按顺序查看单个会话，其中包含本地时间和你的回复。参见 references/sources.md。
4. **搭建框架：**运行 node scripts/new-project.mjs <dir>。从这里开始，所有写入内容都放在 <dir> 中。
5. **故事：**选择一个典型会话，按照实际发生的顺序，逐个节拍写入 <dir>/story.json，为每个节拍标注真实时间，参见 references/story.md。用户的话必须是逐字引用；你的回复必须是该会话中你自己的原话。将 screen 设为用户工作内容的画面，并选择与其会话相符的结尾。运行 node scripts/schedule.mjs <dir> 检查；每次编辑后都要运行。
6. **场景：**根据你对用户的了解填写各个位置，参见 references/room.md。如果素材库中没有符合用户实际情况的道具，就在 <dir>/scenes/props-custom.js 中绘制一个。如果你不是 Claude，就绘制你自己：参见 references/cast.md。
7. **隐私关卡：**向用户展示一张表格，列出屏幕上的每一行内容（引子、姓名牌、每条引语、每条回复、每个道具及其用途），并标注各自的来源。根据用户的修改进行调整，取得明确同意后，再设置 "approved": true。在此之前，每一帧都必须带有 DRAFT 印记。
8. **设计检查：**运行 schedule.mjs 打印的 snapshot 命令。检查每一帧：引语清晰可读、道具位置正确、没有任何内容遮挡消息。向用户展示整张缩略图。
9. **配乐：**根据自己的主题、调性和配色方案编写 <dir>/score/score.py，参见 references/score.md。然后运行 sh <dir>/score/build.sh。如果存在冷场，该命令会失败。
10. **渲染：**在 <dir> 中先运行 npx --yes [email protected] check，然后运行 npx --yes [email protected] render --fps 24 --crf 12 -o renders/session-story.mp4。
11. **检查渲染结果：**视频时长必须与 schedule.mjs 的输出一致。在每个关键时刻截取一帧（ffmpeg -ss <t> -i renders/session-story.mp4 -frames:v 1 renders/check-<t>.png）并查看。然后把视频交给用户，让他们带声音观看。

示例（运行 node scripts/new-project.mjs <dir> --example，然后运行 schedule.mjs <dir> --example）是参考影片：Claude 与该技能作者之间的一次真实会话；作者会制作视频。它展示的是格式，而不是你的影片应采用的形式。schedule.mjs 在没有 --example 的情况下会拒绝处理它，因此它不能代替用户的故事。

验证是否成功

• schedule.mjs 以状态码 0 退出且不打印任何警告。hyperframes check 通过。p5.brush 会输出 WebGL uniform 警告，但可以忽略。
• 设计检查的帧中，每条引语都清晰可读，并且与节拍表一致。
• score/build.sh 最后输出 ok: no dead air，且配乐时长与影片时长一致。
• 渲染结果的时长与 schedule.mjs 打印的时长一致，包含音轨，关键时刻的帧与设计检查结果一致。
• 需要测试的失败路径：故事以一条回复开场，或引语超出长度限制时，schedule.mjs 会以状态码 1 退出，并指出相应节拍。

引擎负责的部分

动作已经设置妥当，效果真实：滑行路径、折叠、投掷、摇摆、碰撞和拍翅。修改故事、场景、角色和配乐。除非是在修复错误，否则不要改动 scenes/director.js 和 scenes/compile.js 中的动作编排。动作规则见 references/motion.md。