session-story

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Session story

会话故事

The agent reads its own history with its user, finds their routine, and turns one typical session into a 40 to 70 s film, in the order it happened:

Story: the user's verbatim words arriving as objects, and the agent's own replies going back. The window and the wall clock follow the session's real time.
Room: decorated from what the agent knows about its user.
Score: composed by the agent against the film's own timeline.

Write

story.json

and the engine does the choreography. Nothing on screen is invented: every line is a quote, and the user approves every line before a frame is rendered.

Agent 阅读自己与用户的历史记录，识别用户的工作模式，并将一次典型会话按实际发生顺序制作成一部 40 至 70 秒的影片：

故事： 用户的原话以物件形式到来，Agent 自己的回复则被送回。窗户和挂钟遵循会话的真实时间。
房间： 根据 Agent 对用户的了解进行布置。
配乐： Agent 按照影片自身的时间线创作。

编写

story.json

，动画引擎便负责动作编排。屏幕上不会出现任何虚构内容：每一句都是原话，并且在渲染任何一帧之前，用户都会逐句审核并批准。

When to use / when not

何时使用／何时不使用

Use when a user asks their agent for a film of their work together, and the agent has real history with that user: local transcripts, or messages the user pastes in.
Do not use for someone else's history, a team's shared logs, marketing with made-up quotes, or anything the user won't review. With no history at all, ask the user for a session's messages. Never invent quotes.

使用： 当用户要求自己的 Agent 制作一部双方共同工作的影片，并且 Agent 拥有与该用户的真实历史记录时：例如本地会话记录，或用户粘贴进来的消息。
不要使用： 不要用于他人的历史记录、团队共享日志、使用编造引文进行的营销，或任何用户不会审阅的内容。如果完全没有历史记录，请用户提供某次会话的消息。绝不编造引文。

Requirements and side effects (complete list)

需求与副作用（完整列表）

Tools: Node 22+, Python 3.9+ (standard library only),
```
ffmpeg
```
on PATH, and the HyperFrames CLI pinned to
```
npx --yes hyperframes@0.8.71
```
(downloaded from the npm registry on first use).
Setup (once, manually):
```
sh scripts/setup.sh
```
runs
```
npm ci
```
from the committed lockfile: p5 2.3.3 (LGPL-2.1), p5.brush 2.2.3 (MIT), @fontsource/permanent-marker 5.3.0 (Apache-2.0). Read-only downloads from npm.
Score renderer: on macOS,
```
swift
```
(Xcode Command Line Tools) plays the score through Apple's built-in General MIDI bank. Elsewhere,
```
fluidsynth
```
with a General MIDI soundfont you set as
```
SOUNDFONT
```
. Neither downloads anything.
Reads (local only, after the user says yes): the agent's own transcripts,
```
~/.claude/projects/<project>/*.jsonl
```
(Claude Code) and
```
~/.codex/sessions
```
(Codex), for the current project unless the user allows
```
--all-projects
```
. Also the agent's memory and instruction files for the room. Nothing is uploaded.
Writes:
```
session-story-candidates.json
```
(harvest) and everything inside the project folder you create. Both hold the user's words: never commit or share them.
Network at build time: none. Pass
```
--describe false
```
to every
```
snapshot
```
, as shown below: with
```
GEMINI_API_KEY
```
set,
```
snapshot
```
otherwise sends frames (the user's words) to Gemini. Render locally: the page paints with WebGL.
No credentials, no paid calls.

工具： Node 22+、Python 3.9+（仅使用标准库）、位于
```
PATH
```
中的
```
ffmpeg
```
，以及固定为
```
npx --yes hyperframes@0.8.71
```
的 HyperFrames CLI（首次使用时从 npm registry 下载）。
一次性手动设置：
```
sh scripts/setup.sh
```
根据已提交的 lockfile 运行
```
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
```
，并需将 General MIDI soundfont 设置为
```
SOUNDFONT
```
。两者均不会下载任何内容。
读取（仅限本地，且须在用户同意后）： Agent 自己的会话记录，即
```
~/.claude/projects/<project>/*.jsonl
```
（Claude Code）和
```
~/.codex/sessions
```
（Codex）；默认仅限当前项目，除非用户允许使用
```
--all-projects
```
。此外，还会读取 Agent 的 memory 和 instruction 文件，用于布置房间。不会上传任何内容。
写入：
```
session-story-candidates.json
```
（采集结果），以及你创建的项目文件夹内的所有内容。两者都包含用户的原话：切勿 commit 或分享。
构建时网络访问： 无。按下方所示，对每个
```
snapshot
```
都传入
```
--describe false
```
：如果设置了
```
GEMINI_API_KEY
```
，未传入此参数时，
```
snapshot
```
会将帧（用户的原话）发送到 Gemini。在本地渲染：页面通过 WebGL 绘制。
不需要凭据，也不会产生付费调用。

Workflow

工作流

Setup:
```
sh scripts/setup.sh
```
(once).
Ask first. Tell the user you'll read your local history with them to find the session, and wait for a yes.
Harvest:
```
python3 scripts/harvest.py --project <their project folder> --out <scratch>/candidates.json
```
prints the routine and lists sessions, most typical first.
```
--session <id>
```
(with the same
```
--project
```
) prints one in order, with local times and your replies. Per references/sources.md.
Scaffold:
```
node scripts/new-project.mjs <dir>
```
. Everything you write from here lives in
```
<dir>
```
.
Story: take a typical session and write
```
<dir>/story.json
```
beat by beat, in the order it happened, with each beat's real time, per references/story.md. The user's lines are verbatim spans; your replies are your own words from that session. Set
```
screen
```
to what their work looks like, and pick the ending their sessions have.
```
node scripts/schedule.mjs <dir>
```
checks it: run it after every edit.
Room: fill the slots from what you know about the user, per references/room.md. Draw a custom prop in
```
<dir>/scenes/props-custom.js
```
when the library has nothing true to them. If you are not Claude, draw yourself: references/cast.md.
Privacy gate: show the user one table of every on-screen line (hook, nameplate, each quote, each reply, each prop and why), each with its source. Take their edits, get an explicit yes, then set
```
"approved": true
```
. Until then every frame carries a DRAFT stamp.
Design pass: run the
```
snapshot
```
command
```
schedule.mjs
```
prints. Look at every frame: quotes legible, props where they belong, nothing covering a message. Show the user the contact sheet.
Score: write
```
<dir>/score/score.py
```
with your own theme, key and palette, per references/score.md. Then
```
sh <dir>/score/build.sh
```
. It fails on dead air.

Render: from

<dir>

npx --yes hyperframes@0.8.71 check

, then

npx --yes hyperframes@0.8.71 render --fps 24 --crf 12 -o renders/session-story.mp4

Check the render: its length must match
```
schedule.mjs
```
. Pull a frame at each key moment (
```
ffmpeg -ss <t> -i renders/session-story.mp4 -frames:v 1 renders/check-<t>.png
```
) and look at them. Then hand it to the user to watch with sound.

The example (

node scripts/new-project.mjs <dir> --example

, then

schedule.mjs <dir> --example

) is the reference film: a real session between Claude and the skill's author, who makes videos. It shows the format, not the shape of your film.

schedule.mjs

refuses it without

--example

, so it can't stand in for your user's story.

设置：
```
sh scripts/setup.sh
```
（仅一次）。
先征得同意。 告诉用户你将读取双方的本地历史记录以查找会话，并等待用户明确同意。
采集：
```
python3 scripts/harvest.py --project <their project folder> --out <scratch>/candidates.json
```
会打印工作模式并列出会话，最典型的会话排在最前。
```
--session <id>
```
（与
```
--project
```
搭配使用）会按顺序打印一次会话，其中包含本地时间和 Agent 的回复。参见 references/sources.md。
搭建项目：
```
node scripts/new-project.mjs <dir>
```
。从此处开始写入的一切内容都位于
```
<dir>
```
中。
故事： 选取一次典型会话，按实际发生顺序逐个叙事节拍（beat）编写
```
<dir>/story.json
```
，并记录每个 beat 的真实时间，参见 references/story.md。用户台词是逐字引用片段；Agent 的回复则使用该次会话中自己的原话。设置
```
screen
```
，让其呈现用户的工作内容，并选择用户会话惯常采用的结尾。
```
node scripts/schedule.mjs <dir>
```
会进行检查：每次编辑后都要运行。
房间： 根据你对用户的了解填充各个槽位，参见 references/room.md。当素材库中没有真正符合用户特点的道具时，在
```
<dir>/scenes/props-custom.js
```
中绘制自定义道具。如果使用的不是 Claude，就绘制你自己的形象：references/cast.md。
隐私检查： 向用户展示一张表，列出屏幕上的每一处内容（开场钩子、姓名牌、每条引文、每条回复、每个道具及其设置原因），并标注每项内容的来源。根据用户的修改意见进行调整，获得明确同意后，将
```
"approved": true
```
设置为
```
true
```
。在此之前，每一帧都会带有 DRAFT 印章。
设计检查： 运行
```
schedule.mjs
```
输出的
```
snapshot
```
命令。检查每一帧：引文是否清晰可读、道具是否位于恰当位置，以及是否有内容遮挡消息。向用户展示帧汇总图（contact sheet）。
配乐： 按照 references/score.md 编写
```
<dir>/score/score.py
```
，确定自己的主题、调性和配器方案。然后运行
```
sh <dir>/score/build.sh
```
。如果存在音频空白，该命令会失败。

渲染： 在

<dir>

中运行

npx --yes hyperframes@0.8.71 check

，然后运行

npx --yes hyperframes@0.8.71 render --fps 24 --crf 12 -o renders/session-story.mp4

。

检查渲染结果： 其长度必须与
```
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 与该 skill 作者之间的一次真实会话，这位作者从事视频创作。示例只展示格式，不规定你的影片形态。如果没有

--example

，

schedule.mjs

会拒绝运行，因此无法拿它代替用户的会话故事。

Verify success

验证成功标准

```
schedule.mjs
```
exits 0 and prints no warnings.
```
hyperframes check
```
passes. p5.brush logs WebGL
```
uniform
```
warnings, which are harmless.
The design-pass frames show every quote legible, and match the beat table.
```
score/build.sh
```
ends with
```
ok: no dead air
```
, and the score's length matches the film's.
The render is the length
```
schedule.mjs
```
printed, has an audio track, and its frames at the key moments match the design pass.
Failure path to test: a story that opens on a reply, or has a quote over the limit, makes
```
schedule.mjs
```
exit 1 and name the beat.

```
schedule.mjs
```
以状态码 0 退出，且不打印任何警告。
```
hyperframes check
```
通过。p5.brush 会记录 WebGL
```
uniform
```
警告，这些警告无害。
设计检查阶段的帧中，每条引文都清晰可读，并且与 beat 表一致。
```
score/build.sh
```
最终输出
```
ok: no dead air
```
，且配乐长度与影片一致。
渲染结果的长度与
```
schedule.mjs
```
打印的时长一致，包含音轨，并且关键时刻的帧与设计检查阶段一致。
要测试的失败路径：以回复开场或引文超出长度限制的故事，都会使
```
schedule.mjs
```
以状态码 1 退出，并指出具体的 beat。

What the engine owns

引擎负责的内容

The motion is physical and already tuned: glide paths, the fold, the throw, the swing, the bonk and the wingbeats. Change the story, the room, the cast and the score. Leave the choreography in

scenes/director.js

and

scenes/compile.js

alone unless you are fixing a bug. The motion rules are in references/motion.md.

动作具有物理感，且已完成调校：滑行路径、折叠、投掷、挥动、敲击和振翅。只需更换故事、房间、角色和配乐。除非是在修复 bug，否则不要修改

scenes/director.js

和

scenes/compile.js

中的动作编排。动作规则见 references/motion.md。