字符动画导演台 YanKaFei/ascii-h3-director

ASCII H3 Director

中文 · 日本語 · English

把一个念头，逼成一条会变形的字符链。

这是什么

ASCII H3 Director 是给 MiniMax H3 用的导演工具：它把一句自由描述，编译成一条变形链（transformation chain）、一份写给时间而非散文的紧凑提示词，以及一套能在付款前拦下你的质量闸门。同时它自带确定性 ASCII 渲染引擎——不联网、不调用任何图像库，用 5×9 手工点阵字库把同一份 FilmSpec 渲染成逐字节可复现的终端帧、SVG、PNG 和接触印样。它既是 DeepSeek Harness（DSH）插件，也是可移植的 Agent Skill。

v3 新增了什么（对比 v1）

v1 是一份 Markdown 技能包加几个 bash 脚本：generate_h3.sh 转发给 mmx video generate，continue_from_last_frame.sh 用 ffmpeg 抽出上一段视频的最后一帧，make_contact_sheet.sh 用 ffmpeg 的 tile 滤镜拼印样，导演逻辑全部写在 SKILL.md 的散文规则里。它能用，但所有判断都靠模型自觉，所有画面都要先付钱才能看见。

| 能力 | v1 | v3 |
| 形态 | Markdown + bash 包装脚本 | 8 个零依赖 ES 模块 + DSH 插件 + Agent Skill |
| 看到画面 | 必须先花钱生成，再用 ffmpeg 抽帧 | 确定性预览引擎，零 API key 即可看片 |
| 字库 | 无（依赖终端字体） | 手写 5×9 点阵，覆盖可打印 ASCII 全部 95 个字形 |
| 可复现性 | 无保证 | 种子驱动，同一 FilmSpec 两次渲染 SHA-256 完全一致（已实测） |
| 运动逻辑 | 散文规则，靠自觉 | 21 条机制的语法库 + FORM_SUCCESSORS 合法后继表 |
| 衔接 | "保留上一帧的运动" | 连续性契约：exit_state → entry_state 继承 + checkSeam 校验 |
| 质量把关 | 6 条自问自答 | 7 项检查自动打分 /100，不过闸门不生成 |
| 参考片分析 | "提取运动语法"（人工） | reference 子命令：从观测 JSON 反推 STYLE DNA 与链条 |
| 印样 | ffmpeg 必需 | 内置 PNG 编码器 + SVG 接触印样，不需要 ffmpeg |
| 载体 | 只要支持 SKILL.md | DSH Cordis 插件（宿主工具 + Director Console 面板） |
| 文档 | 英文 | 中 / 日 / 英 三语 |

安装

路径 A — DSH 插件

从 npm
dsh plugin --profile web add @yankafei/ascii-h3-director

或从本地路径（开发时）
dsh plugin --profile web add /Users/coffee/Desktop/创造一切可能/ascii-h3-director

装好后插件会向会话注册宿主工具，并在 Web UI 里挂上 Director Console 面板。

路径 B — 通用 Agent Skill

方法一：手动拷贝
mkdir -p ~/.agents/skills
cp -R skill ~/.agents/skills/ascii-h3-director

方法二：跑安装脚本 skill/INSTALL.command

脚本会把 skill/ 复制到 ~/.agents/skills/ascii-h3-director/ 并打印自检命令。两条路径互不冲突：插件给 DSH，Skill 给任何读 SKILL.md 的编码代理。

快速上手

以下全部是真实可复制的终端记录；这个阶段不需要 API key，也不花一分钱。

$ ascii-h3 doctor
ascii-h3-director v3.0.0

[ok] node v24.19.0
[ok] engine modules 8 ramps, 5 palettes
[ok] glyph atlas 5×9 bitmap font, printable ASCII
[ok] mechanisms 21 mechanisms in the grammar
[ok] png encoder built-in, no image library required
[ok] render smoke test N cells in Mms
[ok] quality gate score 100/100
[ok] mmx-cli（付费生成） 未安装 —— 可选；安装命令：npm i -g mmx-cli

所有核心检查已通过

$ ascii-h3 plan "15s ASCII clip about memory collapsing into language"
TITLE 15s / ascii / memory / collapsing
SEED ascii-h3:1wok55r
DURATION 15s @ 21:9
LOOK brutalist-digital / brutalist / high-impact
HERO TEXT —

TRANSFORMATION CHAIN
1. 0–3s Density Dissolve [canonical]
the form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds
exit → form=field camera=forward-punch-through v=1
2. 3–6s Glyph Sphere [strong]
thousands of characters orbit a tiny focal mark, then all orbits converge
exit → form=solid-form camera=forward-punch-through v=1
3. 6–9s Typographic Wall [strong]
the camera punches through each wall without cutting; the wall shatters from the point of impact outward
exit → form=fragments camera=forward-punch-through v=1
4. 9–12s Command Shockwave [canonical]
the release from compression travels outward as a single readable command, dragging microtype in its wake
exit → form=space camera=forward-punch-through v=1
5. 12–15s ASCII Tunnel [strong]
the camera travels forward through the rings while they stretch into long perspective trails
exit → form=space camera=forward-punch-through v=1

QUALITY GATE PASS (100/100)
────────────────────────────────────────────────────────────────
✔ One legible transformation chain
5 beat(s): density-dissolve → glyph-sphere → type-wall → shockwave → tunnel
✔ First shot has a clear source state
opens on "density-dissolve"
✔ Every transition has a physical cause
all links follow the mechanism grammar
✔ At least 2 strong scale/density contrasts
density spans 0.12–0.94 with 9 major swing(s)
✔ Final state is usable as the next clip’s input
ends unresolved: the camera is still inside the tunnel with speed left over
✔ Generic HUD / cyberpunk / random glitch excluded
no rejected vocabulary in the positive prompt
✔ Prompt stays compact (written for time, not prose)
153 words

PROMPT (153 words)
────────────────────────────────────────────────────────────────
15-second ultra-wide ASCII kinetic typography sequence.

0–3s: The form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds.
3–6s: Thousands of characters orbit a tiny focal mark, then all orbits converge.
6–9s: The camera punches through each wall without cutting; the wall shatters from the point of impact outward.
9–12s: The release from compression travels outward as a single readable command, dragging microtype in its wake.
12–15s: The camera travels forward through the rings while they stretch into long perspective trails. The camera is still inside the tunnel with speed left over.
$ ascii-h3 preview "a brutalist ASCII tunnel collapsing into a giant word OPEN" --cols 100 --rows 24
t C C
C C C
C t t C t CC C
C C C C t
t C t C GC t t
C C00CC C 8 C G 0CCC G CCCC C C CCG t C C C 0CC0CtC 0 C
0 C C Ct G CC C 01G08 C Ct 00000 C C0 0C C CCCG C0C C CC C 0 G C 0 C 1G
... (24 行确定性字形)

$ ascii-h3 strip "brutalist ASCII tunnel into giant word OPEN" --frames 6 --out sheet.png
wrote sheet.png (6 frames, 3×2, 1840×592)

把 --cols/--rows 调小，先在终端里构图，再放大出图；--out 换成 .svg 就得到矢量印样。

唯一花钱的一步（必须闸门先 PASS）：

1. 写出提示词 ascii-h3 prompt "15s ASCII clip about memory collapsing into language" --out prompt.txt

2. 生成（H3 是付费服务；仓库里唯一会产生费用的调用）
mmx video generate --model MiniMax-H3 --prompt "$(cat prompt.txt)" \
--duration 15 --ratio 21:9 --download outputs/clip01.mp4

mmx 未安装时，doctor 会把它标为可选而不是失败——引擎本身从不依赖它。

命令参考

| 命令 | 参数 | 作用 |
| plan | "<brief>" [--seed S] [--beats N] [--json] | 完整导演方案：变形链、每拍运动状态、质量闸门 |
| chain | "<brief>" [--beats N] [--json] | 只输出变形链 |
| prompt | "<brief>" [--out FILE] | 只输出紧凑的 H3 提示词 |
| review | ["<brief>"] [--out prompt.txt] [--json] | 单独跑质量闸门；--out 可让闸门审查已有提示词 |
| reference | <obs.json> [--json] | 从参考片观测 JSON 提取 STYLE DNA 与可复现的运动链 |
| continue | <exit-state.json> "<brief>" [--json] | 规划无缝续集：继承上一段出口状态，并报告接缝违规 |
| preview | "<brief>" [--t SEC] [--cols N] [--rows N] | 在终端打印单帧 ASCII |
| svg | "<brief>" --t SEC --out FILE.svg | 导出矢量帧 |
| png | "<brief>" --t SEC --out FILE.png | 导出位图帧（内置编码器） |
| strip | "<brief>" [--frames N] [--cols N] [--rows N] --out FILE.png\|.svg | 接触印样：N 张等距帧拼成一张图，不需要 ffmpeg |
| mechanisms | [--json] | 打印运动语法库（按层级分组） |
| doctor | — | 自检并跑一次渲染冒烟测试 |
| help / version | — | 用法 / 版本 |

通用标志：--seed --beats --duration --ratio --palette --ramp --mode --text "WORD,WORD" --avoid "a,b" --allow --block，另加渲染用的 --t --cols --rows --cellW --cellH。
可选值：--ramp ∈ classic brutalist minimal operators binary data phosphor typographic；--palette ∈ brutalist-digital minimal-signal phosphor paper-terminal monolith；--mode ∈ high-impact minimal-data；--ratio ∈ 21:9 16:9 9:16 4:3 1:1 adaptive。

运动语法

一条片子不是一种「风格」，而是一条变形链：字随时间改变职能——文字变成图案，图案变成粒子，粒子变成几何，几何变成空间，空间再变回文字。语法库共 21 条机制，分四层。

| 层级 | id | 名称 | 留下什么（emits） |
| canonical | assemble | Assemble from Sparse Field | solid-form |
| canonical | density-dissolve | Density Dissolve | field |
| canonical | structural-decay | Structural Decay | fragments |
| canonical | letter-fragmentation | Diegetic Letter-Topology Fragmentation | fragments |
| canonical | implosion | Implosion | void |
| canonical | shockwave | Command Shockwave | space |
| canonical | cursor-vortex | Cursor Vortex | void |
| strong | boot-signal | Boot Signal | letterform |
| strong | contour-migration | Contour Migration | solid-form |
| strong | tunnel | ASCII Tunnel | space |
| strong | type-wall | Typographic Wall | fragments |
| strong | glyph-sphere | Glyph Sphere | solid-form |
| strong | giant-word | Giant Cropped Typography | letterform |
| strong | spatial-fold | Spatial Fold | space |
| support | field | Character Field | field |
| support | mask | Text Mask | letterform |
| reject | reject-hud | Decorative HUD | cliche |
| reject | reject-city | Generic Cyberpunk City | cliche |
| reject | reject-glitch | Meaningless Glitch | cliche |
| reject | reject-particles | Unmotivated Particles | cliche |
| reject | reject-smoke | Smoke / Liquid Wipe | cliche |

reject 层故意留在语法库里——审查器需要能说出失败的名字，而不是只说「不好」。合法后继由 FORM_SUCCESSORS 决定，例如 solid-form → density-dissolve | contour-migration | implosion | type-wall，space → type-wall | tunnel | spatial-fold | glyph-sphere | structural-decay。

连续性契约

续集不是新场景。上一段的 exit_state 会成为下一段的 entry_state——摄影机向量、表观速度、旋转、缩放趋势、密度趋势、调色板、字符集全部继承，只有未完成的动作被移交而不是重新声明。

非法示例（摄影机复位 + 调色板跳变 + 速度归零，checkSeam 会逐条报出）：

// exit_state.json（上一段出口） { "form": "solid-form", "camera": "forward-punch-through",
- "velocity": 1.1, "palette": "brutalist-digital", "ramp": "brutalist",
- "unresolved": "the glyph sphere is still resolving when the clip ends" }
// entry_state（续集开头）——错误
+ { "form": "void", "camera": "orbital-lock",
+ "velocity": 0, "palette": "phosphor", "ramp": "minimal",
+ "unresolved": "the glyph sphere is still resolving when the clip ends" }

修正后（inherit() 的产物，checkSeam 返回空数组）：

{
"form": "solid-form",
"camera": "forward-punch-through",
"velocity": 1.21,
"rotation": 0,
"scaleTrend": -1,
"densityTrend": 1,
"unresolved": "",
"palette": "brutalist-digital",
"ramp": "brutalist"
}

checkSeam 会检查：摄影机向量是否复位；表观速度是否被归零；速度方向是否在接缝处反转；调色板是否改变；主导字符集是否改变；未完成的动作是否被重复而不是收尾。ascii-h3 continue 会把违规逐条打印在 SEAM: BROKEN 之下；SEAM: holds 表示接缝成立。

质量闸门

付款前，7 项检查每一项都要能回答「是」。得分 = 通过数 / 7 × 100，全通过才 PASS。

| id | 检查 | 失败意味着 |
| single-chain | 存在一条可读的变形链（≥3 拍） | 概念太散，先收敛成一条链 |
| source-state | 首镜有明确的起始状态 | 没有起点，观众不知道从哪开始 |
| physical-cause | 每个转场都有物理成因 | 出现了语法上没有合法后继的跳变 |
| contrast | 至少 2 次强烈的尺度/密度对比 | 画面平；加大压缩与释放的摆幅 |
| exit-state | 末态可作为下一段的输入 | 片子完全收尾，无法续接 |
| no-cliche | 正提示词里没有 HUD / 赛博城市 / 随机故障 | 陈词滥调混进了正向描述 |
| compact | 提示词保持紧凑（≤320 词） | 写给时间，而不是写给散文 |

界面

Director Console 把上面这一切放进 DSH Web UI：左栏是 brief 与标志，中栏是失真链条和逐拍状态，右栏是闸门分数与预览。

Director Console 面板：左侧 brief 输入，中间变形链与运动状态，右侧质量闸门与 ASCII 预览

确定性引擎导出的接触印样与预览帧：

接触印样：Assemble from Sparse Field 的六帧等距采样

接触印样：ASCII Tunnel 的六帧等距采样

接触印样：Cursor Vortex 的六帧等距采样

仓库结构

ascii-h3-director/
├── src/
│ ├── cli.js # 命令面：13 个子命令、参数解析、doctor │ ├── core.js # 种子 RNG、缓动、值噪声、8 条 ramp、5 套 palette │ ├── glyph-atlas.js # 手写 5×9 点阵字库（ASCII 32–126，95 字形） │ ├── renderer.js # Grid / Camera / 图元 / planFilm / renderFilmFrame │ ├── motion-grammar.js # 21 条机制、FORM_SUCCESSORS、inherit / checkSeam │ ├── director.js # brief 解析、提示词合成、质量闸门、参考分析、续集 │ ├── raster.js # Grid → 文本 / SVG / RGB │ └── png.js # 内置 PNG 编码器（zlib，无外部依赖） ├── skill/ # 可移植 Agent Skill（SKILL.md + references + scripts） ├── docs/ # 三语文档 ├── assets/ # README 图像与印样 └── test/ # 确定性回归测试

环境要求

- Node 18+（doctor 会显式检查主版本号）
- 引擎零运行时依赖：没有 node_modules 也能跑，PNG 由内置编码器写出
- ffmpeg 可选：strip / preview / svg / png 全部不需要它
- mmx-cli 可选：npm i -g mmx-cli，只用于付费生成

致谢与既有工作

- MiniMax-AI/MiniMax-H3 — H3 模型与官方 prompt-writing 技能
- MiniMax-AI/cli — mmx CLI，付费生成与下载
- mexicat/pdoom-video — style bible、时间轴思维、印样式审查
- mrdoob/three.js — AsciiEffect，早期 ASCII 渲染的参考
- remotion-dev/remotion — 常量优先的时序与可编程渲染流程
- motion-canvas/motion-canvas — 代码驱动矢量/文字动画的备选回退
- deepseek-ai/deepseek-harness — 插件、工具与面板的宿主

许可证

MIT。贡献请保持三语 README 同步，并让 ascii-h3 doctor 通过。

ひとつの想念を、変形しつづける文字の連鎖に絞り上げる。

これは何か

ASCII H3 Director は MiniMax H3 のための演出ツールです。自由な一行のブリーフを変形チェーン、時間のために書かれた簡潔なプロンプト、そして支払いの前に立ちはだかる品質ゲートへとコンパイルします。さらに決定論的な ASCII レンダリングエンジンを内蔵し、5×9 の手書きビットマップ書体だけで、同じ FilmSpec をバイト単位で再現可能な端末フレーム・SVG・PNG・コンタクトシートに描き出します。DeepSeek Harness（DSH）プラグインであり、同時に可搬な Agent Skill でもあります。

v3 で新しくなったこと（v1 との比較）

v1 是一堆 Markdown 技能和 bash 脚本。generate_h3.sh 把活全甩给 mmx video generate，continue_from_last_frame.sh 用 ffmpeg 抽出上一条的最后一帧，make_contact_sheet.sh 用 ffmpeg 的 tile 滤镜拼出图集，所有运镜判断都写在 SKILL.md 的散文规则里。能跑，但判断全靠模型自觉，想看画面得先付钱。

| 能力 | v1 | v3 |
| 形态 | Markdown + bash 包装 | 零依赖的 8 个 ES 模块 + DSH 插件 + Agent Skill |
| 看画面 | 先生成，再用 ffmpeg 抽帧 | 确定性预览。没有 API 密钥也能看 |
| 字体 | 无（依赖终端字体） | 手写 5×9 位图。收录可打印 ASCII 95 个字形 |
| 可复现性 | 无保证 | 种子驱动。同一 FilmSpec 渲染两次，SHA-256 一致（已实测） |
| 运动逻辑 | 散文规则 | 21 种机制的语法库 + FORM_SUCCESSORS 后继表 |
| 衔接 | 「保持上一帧的运动」 | 连续性契约：exit_state → entry_state 继承 + checkSeam 校验 |
| 质量 | 6 个自问 | 7 项自动打分（/100）。不合格就不生成 |
| 参考分析 | 「提取运动语法」（手工） | reference 子命令：从观测 JSON 反推 STYLE DNA 和链条 |
| 图集 | 必须用 ffmpeg | 内置 PNG 编码器 + SVG 图集。不需要 ffmpeg |
| 分发 | 能读 SKILL.md 就行 | DSH Cordis 插件（宿主工具 + Director Console 面板） |
| 文档 | 英文 | 中 / 日 / 英 三语 |

安装

路径 A — DSH 插件

从 npm
dsh plugin --profile web add @yankafei/ascii-h3-director

从本地路径（开发时）
dsh plugin --profile web add /Users/coffee/Desktop/创造一切可能/ascii-h3-director

装好后，插件会往会话里注册宿主工具，并在 Web UI 上挂一个 Director Console 面板。

路径 B — 通用 Agent Skill

手动复制
mkdir -p ~/.agents/skills
cp -R skill ~/.agents/skills/ascii-h3-director

或者用安装器 skill/INSTALL.command

skill/ 会被复制到 ~/.agents/skills/ascii-h3-director/，然后打印自检命令。两条路径不冲突：插件给 DSH 用，Skill 给任何会读 SKILL.md 的编码智能体用。

快速开始

下面全是真实可跑的终端记录。这一步不需要 API 密钥，也不花钱。

$ ascii-h3 doctor
ascii-h3-director v3.0.0

[ok] node v24.19.0
[ok] engine modules 8 ramps, 5 palettes
[ok] glyph atlas 5×9 bitmap font, printable ASCII
[ok] mechanisms 21 mechanisms in the grammar
[ok] png encoder built-in, no image library required
[ok] render smoke test N cells in Mms
[ok] quality gate score 100/100
[ok] mmx-cli (paid generation) not installed — optional; install with: npm i -g mmx-cli

all core checks passed

$ ascii-h3 plan "15s ASCII clip about memory collapsing into language"
TITLE 15s / ascii / memory / collapsing
SEED ascii-h3:1wok55r
DURATION 15s @ 21:9
LOOK brutalist-digital / brutalist / high-impact
HERO TEXT —

TRANSFORMATION CHAIN
1. 0–3s Density Dissolve [canonical]
the form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds
exit → form=field camera=forward-punch-through v=1
2. 3–6s Glyph Sphere [strong]
thousands of characters orbit a tiny focal mark, then all orbits converge
exit → form=solid-form camera=forward-punch-through v=1
3. 6–9s Typographic Wall [strong]
the camera punches through each wall without cutting; the wall shatters from the point of impact outward
exit → form=fragments camera=forward-punch-through v=1
4. 9–12s 命令冲击波 [canonical] 压缩释放后向外传播，成为一条可读的命令，身后拖着微缩字体 exit → form=space camera=forward-punch-through v=1
5. 12–15s ASCII 隧道 [strong] 镜头向前穿过圆环，圆环拉伸成长长的透视拖尾 exit → form=space camera=forward-punch-through v=1

QUALITY GATE PASS (100/100)
────────────────────────────────────────────────────────────────
✔ One legible transformation chain
5 beat(s): density-dissolve → glyph-sphere → type-wall → shockwave → tunnel
✔ First shot has a clear source state
opens on "density-dissolve"
✔ Every transition has a physical cause
all links follow the mechanism grammar
✔ At least 2 strong scale/density contrasts
density spans 0.12–0.94 with 9 major swing(s)
✔ Final state is usable as the next clip’s input
ends unresolved: the camera is still inside the tunnel with speed left over
✔ Generic HUD / cyberpunk / random glitch excluded
no rejected vocabulary in the positive prompt
✔ Prompt stays compact (written for time, not prose)
153 words

PROMPT (153 words)
────────────────────────────────────────────────────────────────
15-second ultra-wide ASCII kinetic typography sequence.

0–3s: The form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds.
3–6s: Thousands of characters orbit a tiny focal mark, then all orbits converge.
6–9s: The camera punches through each wall without cutting; the wall shatters from the point of impact outward.
9–12s: The release from compression travels outward as a single readable command, dragging microtype in its wake.
12–15s: The camera travels forward through the rings while they stretch into long perspective trails. The camera is still inside the tunnel with speed left over.

STYLE: brutalist digital palette; brutalist character set; brutalist computational motion design; extreme perspective and scale contrast; monospaced glyphs as physical matter, not overlay; 21:9 frame.
RULE: no normal cuts; every transformation physically emerges from the previous form; preserve direction, velocity and scale across every transition; avoid generic HUD, cyberpunk city, random glitch, unmotivated particles, smoke wipes, photoreal humans.

$ ascii-h3 preview "a brutalist ASCII tunnel collapsing into a giant word OPEN" --cols 100 --rows 24
t C C
C C C
C t t C t CC C
C C C C t
t C t C GC t t
C C00CC C 8 C G 0CCC G CCCC C C CCG t C C C 0CC0CtC 0 C
0 C C Ct G CC C 01G08 C Ct 00000 C C0 0C C CCCG C0C C CC C 0 G C 0 C 1G
... (24 行の決定論的なグリフ)

$ ascii-h3 strip "brutalist ASCII tunnel into giant word OPEN" --frames 6 --out sheet.png
wrote sheet.png (6 frames, 3×2, 1840×592)

把 --cols/--rows 调小，就能在终端里确认构图；把 --out 改成 .svg，输出的就是矢量图版。

唯一花钱的阶段（前提是质量门已 PASS）：

1. プロンプトを書き出す ascii-h3 prompt "15s ASCII clip about memory collapsing into language" --out prompt.txt

2. 生成（H3 は有償サービス。課金を伴う呼び出しはこの一手順だけ）
mmx video generate --model MiniMax-H3 --prompt "$(cat prompt.txt)" \
--duration 15 --ratio 21:9 --download outputs/clip01.mp4

就算没装 mmx，doctor 也只会报告「可选」，不会判定失败。引擎不依赖它。

命令参考

| 命令 | 参数 | 作用 |
| plan | "<brief>" [--seed S] [--beats N] [--json] | 演出全貌：变形链、每一拍的运动状态、质量门 |
| chain | "<brief>" [--beats N] [--json] | 只输出变形链 |
| prompt | "<brief>" [--out FILE] | 只输出精简的 H3 提示词 |
| review | ["<brief>"] [--out prompt.txt] [--json] | 只跑质量门。用 --out 审查已有提示词 |
| reference | <obs.json> [--json] | 从参照视频的观测 JSON 中提取 STYLE DNA 和运动链 |
| continue | <exit-state.json> "<brief>" [--json] | 设计无缝续作。继承前作出口状态，并报告违规 |
| preview | "<brief>" [--t SEC] [--cols N] [--rows N] | 往终端打印 1 帧 |
| svg | "<brief>" --t SEC --out FILE.svg | 导出矢量 1 帧 |
| png | "<brief>" --t SEC --out FILE.png | 导出栅格 1 帧（内置编码器） |
| strip | "<brief>" [--frames N] [--cols N] [--rows N] --out FILE.png\|.svg | 等间隔 N 帧的接触印相表。不需要 ffmpeg |
| mechanisms | [--json] | 按层级展示运动语法 |
| doctor | — | 自检并跑渲染冒烟测试 |
| help / version | — | 用法 / 版本 |

通用参数：--seed --beats --duration --ratio --palette --ramp --mode --text "WORD,WORD" --avoid "a,b" --allow --block，绘制相关还有 --t --cols --rows --cellW --cellH。

可选值：--ramp ∈ classic brutalist minimal operators binary data phosphor typographic，--palette ∈ brutalist-digital minimal-signal phosphor paper-terminal monolith，--mode ∈ high-impact minimal-data，--ratio ∈ 21:9 16:9 9:16 4:3 1:1 adaptive。

运动语法

作品不是「风格」，而是变形链。字符随时间改变功能。字符变成图案，图案变成粒子，粒子变成几何，几何变成空间，空间又回到字符。语法库把 21 种机制分成 4 个层级。

| 层级 | id | 名称 | 保留什么（emits） |
| canonical | assemble | Assemble from Sparse Field | solid-form |
| canonical | density-dissolve | Density Dissolve | field |
| canonical | structural-decay | Structural Decay | fragments |
| canonical | letter-fragmentation | Diegetic Letter-Topology Fragmentation | fragments |
| canonical | implosion | Implosion | void |
| canonical | shockwave | Command Shockwave | space |
| canonical | cursor-vortex | Cursor Vortex | void |
| strong | boot-signal | Boot Signal | letterform |
| strong | contour-migration | Contour Migration | solid-form |
| strong | tunnel | ASCII Tunnel | space |
| strong | type-wall | Typographic Wall | fragments |
| strong | glyph-sphere | Glyph Sphere | solid-form |
| strong | giant-word | Giant Cropped Typography | letterform |
| strong | spatial-fold | Spatial Fold | space |
| support | field | Character Field | field |
| support | mask | Text Mask | letterform |
| reject | reject-hud | Decorative HUD | cliche |
| reject | reject-city | Generic Cyberpunk City | cliche |
| reject | reject-glitch | Meaningless Glitch | cliche |
| reject | reject-particles | Unmotivated Particles | cliche |
| reject | reject-smoke | Smoke / Liquid Wipe | cliche |

reject 这一层故意留在语法里。因为评审者需要能给失败起个名字。合法的后续由 FORM_SUCCESSORS 决定（例如：solid-form → density-dissolve | contour-migration | implosion | type-wall、space → type-wall | tunnel | spatial-fold | glyph-sphere | structural-decay）。

连续性契约

续作不是新场景。前作的 exit_state 就是下一作的 entry_state。镜头向量、表观速度、旋转、缩放趋势、密度趋势、调色板、字符集全部继承，只有未解决的动作用不着重新声明，直接带过去。

违规示例（镜头重置 + 调色板更换 + 速度归零。checkSeam 会逐项报告）：

// exit_state.json（前作的出口） { "form": "solid-form", "camera": "forward-punch-through",
- "velocity": 1.1, "palette": "brutalist-digital", "ramp": "brutalist",
- "unresolved": "the glyph sphere is still resolving when the clip ends" }
// entry_state（续作的入口）—— 错误
+ { "form": "void", "camera": "orbital-lock",
+ "velocity": 0, "palette": "phosphor", "ramp": "minimal",
+ "unresolved": "the glyph sphere is still resolving when the clip ends" }

修正后（inherit() 的输出。checkSeam 返回空数组）：

{
"form": "solid-form",
"camera": "forward-punch-through",
"velocity": 1.21,
"rotation": 0,
"scaleTrend": -1,
"densityTrend": 1,
"unresolved": "",
"palette": "brutalist-digital",
"ramp": "brutalist"
}

checkSeam 检查的是：镜头向量重置、表观速度掉到零、接缝处速度方向反转、调色板变化、主导字符集变化、未解决动作重复。ascii-h3 continue 会把违规项列在 SEAM: BROKEN 下面，如果是 SEAM: holds，接缝就成立。

质量门

付款之前，7 项必须全部答「是」。得分是通过数 / 7 × 100，全部通过为 PASS。

| id | 检查 | 没通过意味着什么 |
| single-chain | 有一条读得出来的变形链（3 拍以上） | 概念太散。先收敛成一条 |
| source-state | 第一个镜头有明确的初始状态 | 没有起点，观众会迷路 |
| physical-cause | 每次转换都有物理原因 | 有衔接在语法上不是合法后续 |
| contrast | 强烈的尺度/密度对比出现 2 次以上 | 画面太平。加大压缩与释放的幅度 |
| exit-state | 最终状态能作为下一作的输入 | 完全收敛，接不下去 |
| no-cliche | 肯定提示词里没有 HUD / 赛博都市 / 随机故障 | 陈词滥调混进了肯定侧 |
| compact | 提示词简洁（320 词以下） | 要为时间而写，不是写散文 |

界面

Director Console 把这一切都放到 DSH Web UI 上。左边是简报和标记，中间是变形链和每一拍的状态，右边是门的得分和预览。

Director Console 面板：左边是简报输入，中间是变形链和运动状态，右边是质量门和 ASCII 预览

确定性引擎输出的接触表和预览：

接触表：Assemble from Sparse Field 的等间隔 6 帧

接触表：ASCII Tunnel 的等间隔 6 帧

接触表：Cursor Vortex 的等间隔 6 帧

仓库结构

ascii-h3-director/
├── src/
│ ├── cli.js # 命令行界面：13 个子命令、参数解析、doctor │ ├── core.js # 种子 RNG、缓动、值噪声、8 种渐变、5 套调色板 │ ├── glyph-atlas.js # 手写 5×9 位图字体（ASCII 32–126，95 个字形） │ ├── renderer.js # Grid / Camera / 图元 / planFilm / renderFilmFrame │ ├── motion-grammar.js # 21 种机构、FORM_SUCCESSORS、inherit / checkSeam │ ├── director.js # 需求简报解析、提示词合成、质量门禁、参考分析、续作 │ ├── raster.js # Grid → 文本 / SVG / RGB │ └── png.js # 内置 PNG 编码器（仅依赖 zlib，无外部依赖） ├── skill/ # 可移植 Agent Skill（SKILL.md + references + scripts） ├── docs/ # 三语种文档 ├── assets/ # README 图片与联系表 └── test/ # 确定性回归测试

运行要求

- Node 18+（doctor 会显式检查主版本号）
- 引擎零运行时依赖。没有 node_modules 也能跑，PNG 由内置编码器写出
- ffmpeg 可选：strip / preview / svg / png 都不需要它
- mmx-cli 可选：npm i -g mmx-cli，仅用于付费生成

致谢与先行案例

- MiniMax-AI/MiniMax-H3 — H3 模型与官方 prompt-writing 技能
- MiniMax-AI/cli — mmx 命令行（付费生成与下载）
- mexicat/pdoom-video — 风格圣经、时间线思维、分镜评审
- mrdoob/three.js — AsciiEffect。早期 ASCII 渲染的参照
- remotion-dev/remotion — 常量优先的时序与可编程绘制
- motion-canvas/motion-canvas — 代码驱动的矢量/文字动画替代方案
- deepseek-ai/deepseek-harness — 插件、工具、面板的宿主

许可证

MIT。贡献时请同步三语种 README，并通过 ascii-h3 doctor。

Force one idea into a chain of characters that will not stop changing shape.

What it is

ASCII H3 Director is a directing tool for MiniMax H3. It compiles a free-form brief into a transformation chain, a prompt written for time rather than prose, and a quality gate that stands between you and the pay button. It also ships a deterministic ASCII render engine: a 5×9 hand-authored bitmap font that turns the same FilmSpec into byte-reproducible terminal frames, SVGs, PNGs, and contact sheets. It is both a DeepSeek Harness (DSH) plugin and a portable Agent Skill.

What's new in v3 (against v1)

v1 was a Markdown skill plus bash scripts. generate_h3.sh forwarded to mmx video generate, continue_from_last_frame.sh used ffmpeg to pull the last frame of the previous clip, make_contact_sheet.sh tiled frames through an ffmpeg filter, and every directorial rule lived as prose inside SKILL.md. It worked — but the judgement was on the model's honour, and you had to pay before you could see a single frame.

| Capability | v1 | v3 |
| Shape | Markdown + bash wrappers | 8 zero-dependency ES modules + DSH plugin + Agent Skill |
| 看画面 | 先生成，再用 ffmpeg 提取 | 确定性预览引擎——不需要 API key |
| 类型 | 无（终端字体） | 手工绘制的 5×9 位图，覆盖全部 95 个可打印 ASCII 字形 |
| 可复现性 | 未指定 | 带种子；同一份 FilmSpec 渲染两次，SHA-256 一致（实测） |
| 运动逻辑 | 文字规则 | 21 种机制语法库 + FORM_SUCCESSORS 合法性表 |
| 续接 | 「保留上一段运动」 | 连续性契约：exit_state → entry_state + checkSeam |
| 质量 | 6 个自问问题 | 7 项自动检查，按 /100 打分；不 PASS 就不生成 |

| Reference analysis | "extract the motion grammar" (manual) | reference subcommand: STYLE DNA and chain inferred from observations |
| Contact sheet | ffmpeg required | Built-in PNG encoder + SVG sheets, no ffmpeg |
| Delivery | Anything that reads SKILL.md | DSH Cordis plugin with host tools and a Director Console panel |
| Docs | English | Chinese / Japanese / English |

Install

Path A — DSH plugin

from npm
dsh plugin --profile web add @yankafei/ascii-h3-director

or from a local path (development)
dsh plugin --profile web add /Users/coffee/Desktop/创造一切可能/ascii-h3-director

Once installed, the plugin registers its host tools with the session and mounts the Director Console panel in the Web UI.

Path B — generic Agent Skill

copy by hand
mkdir -p ~/.agents/skills
cp -R skill ~/.agents/skills/ascii-h3-director

or run the installer
skill/INSTALL.command

The installer copies skill/ to ~/.agents/skills/ascii-h3-director/ and prints the self-check command. The two paths do not conflict: the plugin serves DSH, the skill serves any coding agent that reads SKILL.md.

Quick start

Everything below is a real, copy-pasteable transcript. No API key, no cost.

$ ascii-h3 doctor
ascii-h3-director v3.0.0

[ok] node v24.19.0
[ok] engine modules 8 ramps, 5 palettes
[ok] glyph atlas 5×9 bitmap font, printable ASCII
[ok] mechanisms 21 mechanisms in the grammar
[ok] png encoder built-in, no image library required
[ok] render smoke test N cells in Mms
[ok] quality gate score 100/100
[ok] mmx-cli (paid generation) not installed — optional; install with: npm i -g mmx-cli

all core checks passed

$ ascii-h3 plan "15s ASCII clip about memory collapsing into language"
TITLE 15s / ascii / memory / collapsing
SEED ascii-h3:1wok55r
DURATION 15s @ 21:9
LOOK brutalist-digital / brutalist / high-impact
HERO TEXT —

TRANSFORMATION CHAIN
1. 0–3s Density Dissolve [canonical]
the form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds
exit → form=field camera=forward-punch-through v=1
2. 3–6s Glyph Sphere [strong]
thousands of characters orbit a tiny focal mark, then all orbits converge
exit → form=solid-form camera=forward-punch-through v=1
3. 6–9s Typographic Wall [strong]
the camera punches through each wall without cutting; the wall shatters from the point of impact outward
exit → form=fragments camera=forward-punch-through v=1
4. 9–12s Command Shockwave [canonical]
the release from compression travels outward as a single readable command, dragging microtype in its wake
exit → form=space camera=forward-punch-through v=1
5. 12–15s ASCII Tunnel [strong]
the camera travels forward through the rings while they stretch into long perspective trails
exit → form=space camera=forward-punch-through v=1

QUALITY GATE PASS (100/100)
────────────────────────────────────────────────────────────────
✔ One legible transformation chain
5 beat(s): density-dissolve → glyph-sphere → type-wall → shockwave → tunnel
✔ First shot has a clear source state
opens on "density-dissolve"
✔ Every transition has a physical cause
all links follow the mechanism grammar
✔ At least 2 strong scale/density contrasts
density spans 0.12–0.94 with 9 major swing(s)
✔ Final state is usable as the next clip’s input
ends unresolved: the camera is still inside the tunnel with speed left over
✔ Generic HUD / cyberpunk / random glitch excluded
no rejected vocabulary in the positive prompt
✔ Prompt stays compact (written for time, not prose)
153 words

PROMPT (153 words)
────────────────────────────────────────────────────────────────
15-second ultra-wide ASCII kinetic typography sequence.

0–3s: The form dematerialises because its glyph ramp slides toward emptiness while its silhouette holds.
3–6s: Thousands of characters orbit a tiny focal mark, then all orbits converge.
6–9s: The camera punches through each wall without cutting; the wall shatters from the point of impact outward.
9–12s: The release from compression travels outward as a single readable command, dragging microtype in its wake.
12–15s: The camera travels forward through the rings while they stretch into long perspective trails. The camera is still inside the tunnel with speed left over.

STYLE: brutalist digital palette; brutalist character set; brutalist computational motion design; extreme perspective and scale contrast; monospaced glyphs as physical matter, not overlay; 21:9 frame.
RULE: no normal cuts; every transformation physically emerges from the previous form; preserve direction, velocity and scale across every transition; avoid generic HUD, cyberpunk city, random glitch, unmotivated particles, smoke wipes, photoreal humans.

$ ascii-h3 preview "a brutalist ASCII tunnel collapsing into a giant word OPEN" --cols 100 --rows 24
t C C
C C C
C t t C t CC C
C C C C t
t C t C GC t t
C C00CC C 8 C G 0CCC G CCCC C C CCG t C C C 0CC0CtC 0 C
0 C C Ct G CC C 01G08 C Ct 00000 C C0 0C C CCCG C0C C CC C 0 G C 0 C 1G
... (24 rows of deterministic glyphs)

$ ascii-h3 strip "brutalist ASCII tunnel into giant word OPEN" --frames 6 --out sheet.png
wrote sheet.png (6 frames, 3×2, 1840×592)

Drop --cols/--rows to compose in the terminal first, then raise them for the final image; point --out at a .svg to get a vector sheet.

The one step that costs money (and it is gated on the quality gate):

1. write the prompt
ascii-h3 prompt "15s ASCII clip about memory collapsing into language" --out prompt.txt

2. generate (H3 is a paid service; this is the only billable call in the repo)
mmx video generate --model MiniMax-H3 --prompt "$(cat prompt.txt)" \
--duration 15 --ratio 21:9 --download outputs/clip01.mp4

With mmx absent, doctor reports it as optional rather than failing — the engine never depends on it.

Command reference

| Command | Arguments | What it does |
| plan | "<brief>" [--seed S] [--beats N] [--json] | Full direction plan: chain, per-beat motion state, quality gate |
| chain | "<brief>" [--beats N] [--json] | Just the transformation chain |
| prompt | "<brief>" [--out FILE] | Only the compact H3 prompt |
| review | ["<brief>"] [--out prompt.txt] [--json] | Run the quality gate alone; --out audits an existing prompt |
| reference | <obs.json> [--json] | Extract STYLE DNA and a reproducible chain from reference observations |
| continue | <exit-state.json> "<brief>" [--json] | Plan a seamless sequel inheriting the previous exit state, reporting seam violations |
| preview | "<brief>" [--t SEC] [--cols N] [--rows N] | Print one ASCII frame to the terminal |
| svg | "<brief>" --t SEC --out FILE.svg | Export one vector frame |
| png | "<brief>" --t SEC --out FILE.png | Export one raster frame via the built-in encoder |
| strip | "<brief>" [--frames N] [--cols N] [--rows N] --out FILE.png\|.svg | Contact sheet of N evenly spaced frames; no ffmpeg |
| mechanisms | [--json] | Print the motion grammar, grouped by tier |
| doctor | — | Self-check plus a real render smoke test |
| help / version | — | Usage / version |

Common flags: --seed --beats --duration --ratio --palette --ramp --mode --text "WORD,WORD" --avoid "a,b" --allow --block, plus --t --cols --rows --cellW --cellH for rendering.

Choices: --ramp ∈ classic brutalist minimal operators binary data phosphor typographic; --palette ∈ brutalist-digital minimal-signal phosphor paper-terminal monolith; --mode ∈ high-impact minimal-data; --ratio ∈ 21:9 16:9 9:16 4:3 1:1 adaptive.

The motion grammar

A clip is not a style; it is a transformation chain. Characters change function over time: text becomes pattern, pattern becomes particles, particles become geometry, geometry becomes space, space becomes typography again. The library holds 21 mechanisms across four tiers.

| Tier | id | Name | Emits |
| canonical | assemble | Assemble from Sparse Field | solid-form |
| canonical | density-dissolve | Density Dissolve | field |
| canonical | structural-decay | Structural Decay | fragments |
| canonical | letter-fragmentation | Diegetic Letter-Topology Fragmentation | fragments |
| canonical | implosion | Implosion | void |
| canonical | shockwave | Command Shockwave | space |
| canonical | cursor-vortex | Cursor Vortex | void |
| strong | boot-signal | Boot Signal | letterform |
| strong | contour-migration | Contour Migration | solid-form |
| strong | tunnel | ASCII Tunnel | space |
| strong | type-wall | Typographic Wall | fragments |
| strong | glyph-sphere | Glyph Sphere | solid-form |
| strong | giant-word | Giant Cropped Typography | letterform |
| strong | spatial-fold | Spatial Fold | space |
| support | field | Character Field | field |
| support | mask | Text Mask | letterform |
| reject | reject-hud | Decorative HUD | cliche |
| reject | reject-city | Generic Cyberpunk City | cliche |
| reject | reject-glitch | Meaningless Glitch | cliche |
| reject | reject-particles | Unmotivated Particles | cliche |
| reject | reject-smoke | Smoke / Liquid Wipe | cliche |

The reject tier stays in the grammar on purpose: the reviewer has to be able to name a failure, not just call it weak. Legal successors come from FORM_SUCCESSORS — for example solid-form → density-dissolve | contour-migration | implosion | type-wall, and space → type-wall | tunnel | spatial-fold | glyph-sphere | structural-decay.

The continuity contract

A sequel is not a new scene. The predecessor's exit_state becomes the successor's entry_state: camera vector, apparent velocity, rotation, scale trend, density trend, palette and charset all inherit, and only the unresolved action is handed over rather than re-declared.

A violating seam (camera reset, palette change, velocity dropped to zero — checkSeam reports each one):

// exit_state.json (previous clip's exit)
{ "form": "solid-form", "camera": "forward-punch-through",
- "velocity": 1.1, "palette": "brutalist-digital", "ramp": "brutalist",
- "unresolved": "the glyph sphere is still resolving when the clip ends" }
// entry_state (the sequel opens) — wrong
+ { "form": "void", "camera": "orbital-lock",
+ "velocity": 0, "palette": "phosphor", "ramp": "minimal",
+ "unresolved": "the glyph sphere is still resolving when the clip ends" }

Corrected (what inherit() produces; checkSeam returns an empty array):

{
"form": "solid-form",
"camera": "forward-punch-through",
"velocity": 1.21,
"rotation": 0,
"scaleTrend": -1,
"densityTrend": 1,
"unresolved": "",
"palette": "brutalist-digital",
"ramp": "brutalist"
}

checkSeam tests for: a camera vector that resets, apparent velocity dropped to zero, velocity reversing direction across the seam, a palette change, a change of dominant charset, and an unresolved action repeated instead of closed. ascii-h3 continue prints every violation under SEAM: BROKEN; SEAM: holds means the seam is intact.

Quality gate

Before you pay, all 7 checks must answer yes. The score is passing checks / 7 × 100, and only a clean sweep returns PASS.

| id | Check | What a failure means |
| single-chain | One legible transformation chain (≥3 beats) | The concept is diffuse; collapse it into one chain |
| source-state | The first shot has a clear source state | No origin, so the audience has nothing to enter from |
| physical-cause | Every transition has a physical cause | A link has no legal successor in the grammar |
| contrast | At least 2 strong scale/density contrasts | The frame is flat; widen the compression and release swing |
| exit-state | The final state is usable as the next clip's input | The clip resolves completely and cannot continue |
| no-cliche | No generic HUD / cyberpunk / random glitch | Rejected vocabulary leaked into the positive prompt |
| compact | Prompt stays compact (≤320 words) | It is written as prose instead of for time |

The interface

The Director Console puts all of this inside the DSH Web UI: the brief and flags on the left, the transformation chain with per-beat motion state in the middle, the gate score and a live preview on the right.

Director Console panel: brief input on the left, transformation chain and motion states in the middle, quality gate score and ASCII preview on the right

Contact sheets and preview frames from the deterministic engine:

Contact sheet: six evenly spaced frames of Assemble from Sparse Field

Contact sheet: six evenly spaced frames of ASCII Tunnel

Contact sheet: six evenly spaced frames of Cursor Vortex

Repository layout

ascii-h3-director/
├── src/
│ ├── cli.js # command surface: 13 subcommands, arg parsing, doctor
│ ├── core.js # seeded RNG, easing, value noise, 8 ramps, 5 palettes
│ ├── glyph-atlas.js # hand-authored 5×9 bitmap font (ASCII 32–126, 95 glyphs)
│ ├── renderer.js # Grid / Camera / primitives / planFilm / renderFilmFrame
│ ├── motion-grammar.js # 21 mechanisms, FORM_SUCCESSORS, inherit / checkSeam
│ ├── director.js # brief parsing, prompt composition, gate, reference, sequel
│ ├── raster.js # Grid → text / SVG / RGB
│ └── png.js # built-in PNG encoder (zlib only, no image library)
├── skill/ # portable Agent Skill (SKILL.md + references + scripts)
├── docs/ # trilingual documentation
├── assets/ # README images and contact sheets
└── test/ # determinism regression tests

Requirements

- Node 18+ (doctor checks the major version explicitly)
- The engine has zero runtime dependencies: it runs without a node_modules, and PNGs are written by the built-in encoder
- ffmpeg is optional: strip, preview, svg and png never need it
- mmx-cli is optional: npm i -g mmx-cli, used only for paid generation

Credits & prior art

- MiniMax-AI/MiniMax-H3 — the H3 model and the official prompt-writing skill
- MiniMax-AI/cli — the mmx CLI for paid generation and downloads
- mexicat/pdoom-video — style bible, timeline thinking, contact-sheet review
- mrdoob/three.js — AsciiEffect, the early reference for ASCII rendering
- remotion-dev/remotion — constants-first timing and programmable render flow
- motion-canvas/motion-canvas — optional code-rendered vector/text fallback
- deepseek-ai/deepseek-harness — the host for the plugin, tools and panel

License

MIT. Contributions: keep the three languages in sync and leave ascii-h3 doctor green.