面向 AI 漫剧、短片与分镜预演的桌面场景工具。 用可编辑的灰模场景把人物、道具、走位、镜头和时序讲清楚，再把镜头参考交给图生视频、动画或后期流程。
AI Comic Scene 建立在 Blockout 的预演工作方式之上，并进一步加强了本机 MCP 控制、统一场景命令、场景快照、结构化动作意图和中文界面本地化。它的目标不是直接替代视频生成器，而是先把“这一镜到底发生什么”变成可检查、可修改、可复用的数据。
先把空间关系和镜头意图确定下来，再让后续生成工具完成画面风格与细节。
下列界面图展示了 AI Comic Scene 所采用的基础预演工作流：搭场、角色与相机标记、时间线检查以及镜头交付。图片来自 Blockout 的公开文档素材，用于说明本项目所继承和继续扩展的工作台形态；它们不是把基础项目截图伪装成独立新素材。
| Stage：搭建空间与角色 | Shoot：相机跟随与构图 |
|---|---|
 |
 |
| 先放入环境、人物、道具和灯光，再检查空间尺度。 | 为同一段表演安排跟拍、侧拍、反打或俯拍等不同镜头。 |
| 时间线：检查动作断点 | Deliver：导出镜头参考包 |
|---|---|
 |
 |
| 角色和相机在关键时间点都有可编辑标记，便于检查走位和构图。 | 从固定的场景快照输出视频、静帧、控制通道、提示词和元数据。 |
视频生成工具最容易误解的通常不是美术风格，而是动作和空间关系：谁在哪里、什么时候走到哪里、镜头从哪里看、门和桌子是否在正确位置、一个动作结束时人物和道具分别处于什么状态。
本项目用粗模、人物标记和相机标记把这些事情固定下来。灰模不追求精致，而追求明确：
- 角色和道具的相对位置可见、可编辑；
- 人物走位和镜头运动可在同一条时间轴上检查；
- 一个场景的表演可以被多个镜头复用；
- 导出包能同时提供视频、关键静帧、控制通道、提示词和元数据；
- MCP 客户端可以调用与界面一致的场景能力，而不是绕过应用直接修改文件或 Three.js 运行时。
- AI 漫剧分镜：把剧本拆成地点、角色、关键动作和镜头，再准备首帧、尾帧或控制图。
- 短片预演：在动画、实拍或虚拟制作前验证走位、景别、镜头节奏和剪辑连续性。
- 图生视频参考包：把空间关系固定在 clean、depth、normal、顶视图和关键静帧中，再用文字说明相邻状态之间的动作与运镜。
- 跨工种沟通：导演、分镜、动画和后期围绕同一份项目数据讨论，而不是只靠口头描述。
- 自动化编排：让 Codex、Claude Code 或其他 MCP 客户端在本机已运行的应用中搭场、布置标记、调整镜头和检查截图。
从资产库放入环境、人物、动物、载具、家具和道具，调整位置、旋转和比例。先确认门、桌子、沙发、人物和相机的空间尺度，再处理小道具。
可以为实体设置标签、贴地、绑定跟随关系，也可以把当前场景保存为可复用的舞台预设。
场景负责保存角色走位；镜头负责保存相机。一个角色的 Blocking take 可以复用于多个镜头，因此同一段表演能够从不同机位拍摄，而不用为每个镜头重新摆人物。
在时间轴上放置角色标记和相机标记：
- 在
0s放角色起点和建立构图的相机。 - 在动作转折点放后续标记，例如“走到门前”“伸手”“穿过门洞”“坐下”。
- 在相机视图中检查构图、焦距、人物可见性与墙体/门框遮挡。
- 有必要时添加中间标记；这比只修终点更能避免插值路径穿过家具或墙体。
例如一段进门表演可以拆成：
| 时间 | 人物 | 相机 |
|---|---|---|
0–3s |
走向门口 | 背后跟拍 |
3–4s |
减速、看向门、伸手 | 保持近景 |
4–5s |
停在门前，门作为前景 | 维持门框构图 |
5–8s |
穿过门洞 | 缩短跟随距离，穿过门框 |
8–12s |
进入室内 | 移到侧前方 |
导出从版本化 SceneSnapshot 读取数据，而不是读取当前面板、选择状态或正在播放的临时画面。一个镜头交付包可包含：
shot-delivery/
├── motion reference video
├── key stills
├── depth / normal / top-down passes
├── prompt and metadata
├── contact sheet or animatic assets
└── optional GLB scene data
同一份场景快照会先固定帧计划和输出路径，再开始渲染与编码。这样导出过程不会因为你切换了选中对象或拖动播放头而改变内容；取消导出时会关闭相关编码任务并清理未完成产物。
AI Comic Scene 提供一个本机 MCP bridge。它不是把模型直接塞进编辑器，而是把已经存在的场景能力以工具形式开放出来。
MCP client
→ stdio bridge
→ localhost-only control server (bearer token)
→ desktop application
→ SceneApplicationService
→ validated SceneCommand
→ ProjectDoc / CommandResult
当前工具登记表包含 29 项能力，覆盖：
- 读取当前项目和资产目录：
get_state、list_assets； - 搭场：
add_entity、move_entity、delete_entity、snap_to_ground； - 表演：
add_actor_mark、apply_motion_primitives、apply_action_preset、spawn_sequence； - 镜头：
add_camera_mark、apply_framing、apply_camera_move、set_track_subject； - 检查：
set_time、play、stop、screenshot； - 预设和参考：
save_preset、apply_preset、set_reference。
推荐顺序是：先 get_state，再查询资产或目标，执行一项明确修改，最后 set_time + screenshot 检查结果。MCP 不能直接改 Zustand、Three.js 场景或项目文件；所有可共享的项目修改都会经过同一套校验与命令执行边界。
完整配置、示例和故障排查见 MCP 指南。
除了传统的角色标记，本项目提供一层通用动作原语。它记录“想表达什么”，而不是要求调用方直接计算每个关节角度：
move：向坐标或实体移动；face/look：转向或看向目标；posture：站立、放松、警觉、下蹲、坐下；lean：身体向某方向倾斜；reach：左手、右手或双手伸向目标；raiseLimb：抬起指定手臂或腿；hold：在一个节拍保持当前状态。
例如“走到门前，右手伸向门把，停顿”可以通过 move → reach → hold 表达，并被编译为时间线中的角色标记。原始动作意图会和生成的关键状态一起保存，便于后续工具重新检查或调整。
这不是完整的人体动画或物理系统：它不保证避开墙体、自动抓住物体、带动门铰链或解决所有穿模问题。它的作用是为未来自然语言规划和更精确的姿势求解提供稳定的中间层。
git clone https://github.com/Touka404x/ai-comic-scene.git
cd ai-comic-scene
npm ci
npm run dev启动后按这个顺序完成第一个镜头：
- 新建或打开项目，进入 Stage。
- 布置环境、人物、家具与关键道具。
- 进入 Shoot，为角色和相机放置时间标记。
- 播放、拖动时间轴并检查每个动作断点。
- 进入 Deliver，选择输出通道和分辨率，生成镜头交付包。
npm run typecheck
npm run lint
npm test
npm run build
npm run smoke
npm run e2e
npm run verify:assets
npm run verify:builder-configAI Comic Scene 是基于 Blockout 开发的派生项目。Blockout 由 Sam Wasserman 创建，提出了以灰模、角色标记、相机标记和交付包服务 AI 原生影视预演的基础工作流。
本项目在这一基础上强化了：统一场景命令、场景快照、桌面安全边界、MCP 工具合约、结构化动作意图、可审查的自动化执行路径和中文界面本地化。
中文界面本地化由 Touka404x 完成并维护，覆盖编辑器中的核心界面文字、术语和使用说明。
按 Blockout 的署名要求，本项目在文档与任何未来的 About / Credits 界面中保留以下署名：Sam Wasserman (wassermanproductions.com)。
本项目采用 Apache License 2.0。Blockout 同样以 Apache License 2.0 发布；关于基础项目的署名要求，见其 NOTICE。