OpenMontage × Codex：安装并启用 /ink-art、/animated-drawing 手绘动画提示词实战指南

本文以仓库中 .codex/prompts/README.md 为骨架展开：先讲清 Codex 自定义提示词（Custom Prompts）的加载机制与安装方法，再深入剖析 OpenMontage 随仓库版本化的三份提示词（/ink-art、/animated-drawing、/backlot）各自的能力边界与背后实现，最后给出自建提示词与向 Codex Skills 迁移的实践建议。读完你可以在自己的 Codex 环境里一键唤起 OpenMontage 的矢量手绘动画、栅格动画与 Backlot 故事板能力。

一、为什么 OpenMontage 要把提示词版本化在仓库里

OpenMontage 是一个面向 AI 编程助手的开源视频生产系统，其思路是"把 AI 编程助手变成完整的视频制作工作室"：仓库内的 skills/ 目录沉淀了 700+ 份 Agent 技能与制作知识文件，而 skills/INDEX.md 描述了一套三层知识架构——工具层（tools/tool_registry.py）声明"有什么工具"、技能层（skills/）规定"OpenMontage 怎么用这些工具"、底层技能层（.agents/skills/）提供"技术本身怎么工作"。

Codex 是这套体系的落点之一：仓库根目录的 CODEX.md 明确要求 Agent 先读 AGENT_GUIDE.md 与 PROJECT_CONTEXT.md。而 .codex/prompts/ 目录则提供了另一种更轻量的接入方式——通过 Codex 的斜杠命令（slash command）快速唤起 OpenMontage 的专项能力。

这里存在一个关键机制差异，正是 .codex/prompts/README.md 开篇强调的事实：

Codex 只扫描 ~/.codex/prompts/（用户主目录）下的自定义提示词，并不会读取项目级的 .codex/prompts/。

因此，仓库中的 .codex/prompts/ 目录承担的是"事实来源（source of truth）"角色：三份提示词文件在这里完成版本管理与评审，而真正生效的副本必须被复制或软链接到用户主目录。这种"仓库版本化 + 主目录生效"的分离，保证了团队协作时提示词的可审计、可追溯，同时不污染用户全局配置。

二、安装：两条命令让 /ink-art 与 /animated-drawing 出现在 Codex 的 / 菜单

在仓库根目录下执行以下命令即可完成安装：

mkdir -p ~/.codex/prompts
cp .codex/prompts/ink-art.md .codex/prompts/animated-drawing.md ~/.codex/prompts/

这是"复制"路线：安装后副本与仓库版本相互独立，仓库后续改动不会自动同步到主目录。

若希望"仓库编辑即生效"，则改用软链接路线（README 中以注释形式给出）：

# symlink so repo edits propagate:
ln -s "$PWD/.codex/prompts/ink-art.md" ~/.codex/prompts/ink-art.md

之后重启 Codex，在输入框键入 / 即可看到 ink-art 与 animated-drawing 出现在菜单中。

原文仅安装了这两个提示词；如果需要 backlot 也进入菜单，可按相同模式处理 .codex/prompts/backlot.md：

cp .codex/prompts/backlot.md ~/.codex/prompts/

注意：~/.codex/prompts/ 是用户主目录下的安装目标，并非仓库路径；若你所在环境对 ~ 展开有特殊约定，请显式写出主目录绝对路径。

三、/ink-art：从零创建"会自己画出来"的矢量墨迹动画

.codex/prompts/ink-art.md 的 frontmatter 声明了它的定位：Hand-drawn ink doodle animation — a character that draws itself then walks/dances/waves, or a contraption explainer (vector → HyperFrames MP4)，并定义参数占位符 argument-hint: [what to animate]。

触发后，提示词要求 Agent 先阅读 skills/creative/ink-theater.md 与 ink-theater/README.md，再按 $ARGUMENTS 指定的内容构建手绘墨迹动画。它的核心是 OpenMontage 自研的 Ink Theater 引擎（ink-theater/ink-theater.js，全局对象 InkTheater），该引擎在 ink-theater/README.md 中被归纳为五大能力：

能力模块	作用	关键 API
ink strokes	可变线宽的毛笔笔触 + 抖动中心线，形成"自信的手绘线条"	inkPath(pts, opt)、inkRibbon(pts, {width, taper, seed})
boil	可安全寻帧（seek-safe）的手绘"线条沸腾"效果，按时间轴驱动 feTurbulence 种子（约 9fps），而非 SMIL	boil(turbEl, tl, {duration, fps})
spring physics	闭式阻尼弹簧缓动（预判/过冲/沉降），是进度 p 的纯函数，天然可寻帧	springEase({stiffness, damping, mass})、ease.{settle, overshoot, bouncy, soft}
rig / IK	2D FABRIK 逆运动学 + 可装配吉祥物，手臂可伸向目标点	fabrik(lengths, origin, target)、mascot({x, y, scale}) → .reachL/.reachR([x, y])
contraption grammar	参数化、可组合的"简陋机械"零件	parts.{crank, gauge, hopper, slot, lever, box}

3.1 角色动作：Ink Puppet + 真实 CMU 动捕，禁止手调

提示词强调："角色走路/跳舞/挥手/跳跃，一律使用 Ink Puppet 动捕系统，绝不手工调动作（Never hand-tune motion）"。标准流程为：

var p = InkPuppet.create(mount, { cx: 960, ground: 902, boil: "boil" });
p.drawIn(tl, { start: 0.4 });   // 铅笔逐肢体画出人物（self-drawing reveal）
InkPuppet.choreograph(tl, p, [   // 按名字播放动捕片段，零手调
  { clip: "walk" }, { clip: "dance_spin" }, { clip: "wave" }
], { start: 3.7 });

动作名称来自动捕目录 ink-theater/mocap/catalog.json，当前内置 12 个全部源自 CMU 的免费动作：locomotion 类（walk、run、climb、march、shuffle）、action 类（jump、kick）、posture 类（sit）、gesture 类（wave）、dance 类（dance_spin、dance_glide、twist）。使用原则是"按节拍挑选合适的动作并变化使用，绝不循环单一片段"。

当目录中没有所需动作时，一条命令即可扩展（工具为 ink-theater/mocap/add-motion.mjs，会自动映射 fair1 / CMU / Mixamo 骨骼并重建目录）：

node ink-theater/mocap/add-motion.mjs backflip 05_20 dance "a backflip"
# 参数：<动作名> <CMU id | url | 本地 .bvh 路径> <分类> "<描述>"

3.2 字幕与对话气球：HTML overlay 而非 SVG text

提示词明确了一条硬规则：字幕必须是 HTML overlay <div>，因为 HyperFrames 不会把 webfont 应用到 SVG <text> 上。配套的对话气球 API 为 InkTheater.balloon(tl, opts)（opts 含 into、overlay、at、dur、text、mouth:[x,y]、center:[x,y]、w、size、boil）。

这与 ink-theater/README.md 记录的"字体陷阱（font gotcha）"一脉相承：此前所有渲染中手写体变衬线体的根因，是抓取了 Google Fonts css2 API 的单一 unicode-range 子集（常缺 basic-latin/ASCII），导致英文静默回退到 serif，而渲染器仍显示 Fonts: 1 loaded。正确做法是内嵌完整字体文件，仓库自带 ink-theater/assets/patrickhand.ttf（SIL Open Font License，许可文件见同目录 assets/OFL.txt 与 ink-theater/THIRD_PARTY_NOTICES.md）：

@font-face { font-family: "InkHand"; src: url("assets/patrickhand.ttf") format("truetype"); font-display: block; }

3.3 渲染前的强制校验

提示词要求渲染前用 npx hyperframes lint + snapshot 校验（lint 指向包含 index.html 的组合目录，例如 ink-theater/examples/mocap-figure，而不是 examples/ 根目录）。同时 Ink Theater 遵守 HyperFrames 的确定性渲染契约：闭式弹簧、由时间轴驱动种子的 boil、经 onUpdate 跟随的 IK、种子化 PRNG、禁止 repeat:-1，且只在 window.__timelines["<id>"] 上挂一条暂停的 gsap.timeline。

四、/animated-drawing：用 Meta AnimatedDrawings 让现有图片跳起舞

.codex/prompts/animated-drawing.md 的能力边界与 /ink-art 严格互补：它只处理"用户已提供的类人形（humanoid）绘画/照片"，输出是栅格（raster）GIF/MP4——原始图画被真实动捕扭曲变形，没有矢量、没有"自绘揭示（draw-on reveal）"效果。frontmatter 的参数为 argument-hint: [path to drawing] [motion: dance|walk|jump|wave]。

提示词要求 Agent 先读 skills/creative/animated-drawing.md，再基于 Meta 开源 AnimatedDrawings（代码 MIT 许可）搭建执行环境。该技能文档提供了两条运行路径：

路径 A · 内置角色 + 预设动作——开箱即用、无需 Docker（在 Windows 上验证过），约 10–12 秒/片段、纯 CPU 即可：

git clone --depth 1 https://github.com/facebookresearch/AnimatedDrawings.git && cd AnimatedDrawings
# 仓库锁定 Python 3.8 + 旧版 wheels；用 uv 装 3.8：
uv python install 3.8 && uv venv --python 3.8 .venv
uv pip install --python .venv -e .
uv pip install --python .venv "setuptools<81"   # 仓库 import pkg_resources 但未声明依赖
.venv/Scripts/python -c "from animated_drawings import render; render.start('./examples/config/mvc/export_gif_example.yaml')"

路径 B · 自动骨骼绑定一张新图——重负载：需要 Docker + 约 670 MB 模型（drawn_humanoid_detector.mar 311 MB + drawn_humanoid_pose_estimator.mar 357 MB），约 16 GB RAM：

python image_to_animation.py drawing.png out_dir   # detect → segment → rig → retarget → render

输入要求（自动骨骼绑定路径）：画面中恰好一个、轮廓清晰的类人形，接近 T/A 姿势（四肢分离、不重叠），纯浅色背景（分割基于阈值 + floodfill）。角色来源需先与用户确认四种选项之一：用户上传自己的涂鸦（效果最佳）、上传照片先"涂鸦化"（img2img 转成儿童蜡笔画）、生成全新角色（推荐默认）、或从 Pixabay/Pexels 图库找素材（命中率低）。内置示例角色仅供演示，不能作为用户成品角色反复使用。

4.1 预设动作与 retarget 配置必须配对，否则崩溃

每个内置 BVH 属于不同骨骼体系，用错 retarget 配置会直接崩溃（ValueError: 'RightArm' is not in list）。技能文档给出了配对表，必须严格对应：

动作	BVH 目录	retarget 配置
dab、wave_hello、jumping、zombie	bvh/fair1/	fair1_ppf
jumping_jacks	bvh/cmu1/	cmu1_pfp
jesse_dance	bvh/rokoko/	mixamo_fff

其他 BVH 需匹配其骨骼或自写 retarget 配置。同时要用 end_frame_idx 截断长片段（如 wave_hello 有 839 帧），否则渲染耗时数分钟；接地类片段（dab、wave_hello）渲染速度慢约 8 倍。

4.2 合成进 HyperFrames 才是成品视频

AnimatedDrawings 只输出"会动的角色"，要成为完整视频（背景、气球、音乐）需在 HyperFrames 中合成，关键约定：

• 透明输出：MVC 配置中设 view.CLEAR_COLOR: [0,0,0,0]；
• GIF 在确定性 HyperFrames 渲染中会冻结，需转成带 alpha 的 VP9 WebM：ffmpeg -i char.gif -c:v libvpx-vp9 -pix_fmt yuva420p char.webm（注意 ffprobe 会误报 yuv420p，alpha 实际完好）；
• 视频契约由 linter 强制（npm run check）：<video> 必须是舞台（stage）的直接子元素且自带 id，不能嵌套在带时间的 <div> 里（嵌套会冻结播放）；每个片段需独立 data-track-index；淡出需要硬性收尾 tl.set(el,{opacity:0})；
• 文字/气球仍走 HTML overlay div + 完整 patrickhand.ttf。

诚实的能力边界：栅格输出（放大可见贴图拉伸）、仅限类人形、无自绘揭示、背景较简陋。它适合做"你的涂鸦活过来"的新奇效果；要白底矢量、可自绘的墨迹动画，应转用 /ink-art。

五、/backlot：打开"活的故事板"观察窗口

.codex/prompts/backlot.md 与前两个创作类提示词不同，它是一个项目观察/调试命令：为指定项目打开 Backlot 看板（浏览器 UI，实时展示流水线阶段、剧本、场景规划与已生成的资产）：

python -m backlot open <project-id>

三条使用约定值得注意：

1. 不传 project id 时打开库视图：python -m backlot open；
2. 幂等：若 Backlot 服务器未启动则先启动，再在浏览器打开该项目看板；
3. 失败不阻塞：若打开失败，报告后继续主流程——看板只是观察者，绝不是阻塞者。

其架构依据在 backlot/ 目录中：server.py（HTTP 服务）、state.py（状态管理）、ui/board.html（看板界面）。提示词强调"看板的所有状态都派生自磁盘上的 projects/<id>/ 目录，绝不手动更新 UI"，并要求检查点与产物遵守 skills/meta/checkpoint-protocol.md。仓库内的测试如 tests/backlot/test_server.py、tests/backlot/test_state.py 可帮助理解其服务与状态的行为契约。

六、自建提示词：frontmatter 结构一览

三份内置提示词展示了 OpenMontage 对 Codex custom prompt 的规范写法，均由 YAML frontmatter + 正文组成：

---
description: <一行能力描述，决定何时出现在/菜单检索中>
argument-hint: [<参数1> <参数2>]
---

<给 Agent 的执行指令，结尾以 Request/ ... + $ARGUMENTS 注入用户输入>

• description：描述能力与适用场景（如 ink-art 强调 "vector → HyperFrames MP4"），是斜杠命令可发现性的关键；
• argument-hint：提示用户应提供什么参数（如 [path to drawing] [motion: dance|walk|jump|wave]）；
• $ARGUMENTS：占位符，运行命令时替换为用户输入；
• 正文中"先读哪些技能文档"的指令，直接指向 skills/ 下对应的能力文件，形成"提示词 → 技能文档 → 引擎/工具"的调用链。

七、演进方向：从 Custom Prompts 到 Codex Skills

.codex/prompts/README.md 在结尾给出明确提醒：OpenAI 正在弃用 Custom Prompts，转向 Codex 的 "skills" 机制，建议在生态稳定后迁移。对 OpenMontage 而言，这一迁移的落点已现成存在——仓库的 skills/ 体系（含 skills/INDEX.md 描述的三层知识架构）正是与 Skills 机制同构的资产层；skills/creative/ink-theater.md、skills/creative/animated-drawing.md 等内容既被 prompt 引用，也可在未来直接作为 skill 描述文件被 Codex 加载。

八、常见问题与最佳实践小结

1. 装了提示词但 / 菜单里没有：检查文件是否真的位于 ~/.codex/prompts/（而非项目内 .codex/prompts/），并确认已完全重启 Codex；
2. 仓库改了提示词，主目录没变：复制模式下需重新 cp；想避免此问题请用 ln -s 软链接，实现"仓库编辑即生效"；
3. /ink-art 与 /animated-drawing 选哪个：从零创建会自绘的矢量墨迹动画选前者；让一张现成的类人形图画跳舞选后者；两者都非 Rule-Zero 流水线，不要求 .yaml manifest；
4. 渲染前的统一校验：Ink Theater 走 npx hyperframes lint + snapshot；AnimatedDrawings 合成路径走 npm run check，二者都强调先校验再渲染，以守住确定性产出。

综上，OpenMontage 通过"仓库版本化 + 主目录生效"的方式，把 Codex 自定义提示词变成了通往其视频生产能力的快捷入口。理解这套安装机制、三份内置提示词的能力边界，以及它们背后的 Ink Theater、AnimatedDrawings 与 Backlot 实现，你就能在自己的 Codex 环境中复现并扩展这套工作流。