explain-with-anim

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

explain-with-anim

The user asked a question. Answer it with a picture and the words that walk the picture — not a picture instead of an answer, and not a paragraph with a decorative diagram after it. The figure is drawn from the code (or the facts) by

vlmkit-anim

, checked, and delivered as a file; the prose follows the figure beat by beat and names the things in it by their ids.

Read

explanatory-animation

for how to write and check a scene. This skill is about what to draw, from what, and how to explain with it.

用户提出了一个问题。用一幅图和沿着图逐步讲解的文字来回答——不能用图片代替答案，也不能写完一段话后再附上一张纯装饰性的示意图。图由

vlmkit-anim

根据代码（或事实）绘制，经过校验，并作为文件交付；正文逐拍跟随图，并使用图中的 id 指称其中的对象。

阅读

explanatory-animation

，了解如何编写和校验场景。这个 skill 关注的是画什么、依据什么，以及如何借助它进行解释。

First: does a picture help?

首先：图片有帮助吗？

Draw when the answer has things and relations — four or more modules, states, participants, steps — or an order in time, or a before and after. Do not draw for a one-line answer, a single function's body, or a question about a value. If in doubt, write the answer first; if it needs a list of more than four named things that point at each other, draw them.

当答案包含对象及其关系——四个或更多模块、状态、参与者、步骤——或者包含时间顺序，或者需要展示前后变化时，就绘图。不要为一行答案、单个函数体或有关某个值的问题绘图。如果拿不准，先写答案；如果答案需要一个包含四个以上彼此指向的命名对象列表，就绘图。

Choose the picture from the question

根据问题选择图形

The user asks…	Draw	From
"How is this repo / package / directory structured?"	`kind: modules` — a module map, containers per area	`vlmkit-anim facts <dir> --depth 1 --out f.expect.json` (the import graph), then the map, then `check --expect f.expect.json` ; for the whole workspace `vlmkit-anim repo --out <dir>` draws it and writes its own sheet
"How does a request / event / message flow through it?"	`modules` with a `sequence` that walks the path ( `highlight` , `flow` ), or `kind: sequence` when the participants and their calls are the point	the code path you read; the map from `facts` ; each hop a beat with a caption saying why
"How does this algorithm / data structure work?"	the kind that owns it: `sort` , `array` , `tree` , `heap` , `stack` , `queue` , `list` , `matrix` , `graph`	the function's own steps; small concrete values (five to eight) so every beat is readable
"What states can this be in? What happens on X?"	`kind: state-machine` with a `trace` of the events that matter	the enum / reducer / status field and its transitions
"How do these services talk? What if one is slow / lost?"	`kind: distributed` (nodes, messages, a lost one) or `kind: sequence` (frames for retry / alt)	the protocol as implemented; the failure the user asked about as the trace
"Why does it go this way here?" (a decision)	`kind: flowchart` with the walked path	the branch conditions, as their labels
"What does this branch / PR change?"	`vlmkit-anim pr --base origin/main --out .vlmkit-anim/pr` — one beat per commit; or `vlmkit-anim diff before.json after.json` for two maps	git; `<name>.md` is paste-ready
"What is the schedule / what slipped?"	`kind: gantt`	the plan, the slips as `slip` ops
"The docs already have a mermaid diagram"	`vlmkit-anim import mermaid page.md --out scene.json` , then finish it	the diagram; read its `dropped / changed:` list
"Give me a D2 file" / "something I can paste in the README as ASCII" / the repo keeps `.d2` diagrams	`d2-diagram` — D2 text laid out by TALA, rendered in the terminal	the same `facts` sheet, drawn by hand into D2; say in the prose that nothing checks the D2 against the code

One picture per question. Two aspects that both matter (structure and a walk) are one

modules

scene with a

sequence

, or

kind: compose

— not two files.

用户询问……	绘制	依据
“这个仓库／package／directory 的结构是怎样的？”	`kind: modules` ——模块图，按区域划分容器	`vlmkit-anim facts <dir> --depth 1 --out f.expect.json` （导入图），然后生成模块图，再运行 `check --expect f.expect.json` ；对于整个 workspace， `vlmkit-anim repo --out <dir>` 会绘制图形并写出自己的 sheet
“一个请求／事件／消息如何在其中流转？”	`modules` ，并用 `sequence` 沿路径逐步走查（ `highlight` 、 `flow` ）；当参与者及其调用关系本身是重点时，使用 `kind: sequence`	所阅读的代码路径；来自 `facts` 的模块图；每一跳都是一拍，并附有说明原因的 caption
“这个算法／数据结构如何工作？”	使用适合它的 kind： `sort` 、 `array` 、 `tree` 、 `heap` 、 `stack` 、 `queue` 、 `list` 、 `matrix` 、 `graph`	函数自身的步骤；使用五到八个较小且具体的值，确保每一拍都清晰可读
“它可能处于哪些状态？X 时会发生什么？”	`kind: state-machine` ，并用 `trace` 呈现重要事件	enum／reducer／status 字段及其状态转换
“这些服务如何通信？如果某个服务变慢／消息丢失会怎样？”	`kind: distributed` （节点、消息以及一条丢失的消息），或 `kind: sequence` （展示 retry／alt 的帧）	实际实现的协议；将用户询问的故障作为 trace
“它为什么会在这里走这条路？”（某个决策）	`kind: flowchart` ，并走查其中的路径	分支条件及其标签
“这个 branch／PR 改了什么？”	`vlmkit-anim pr --base origin/main --out .vlmkit-anim/pr` ——每个 commit 对应一拍；或使用 `vlmkit-anim diff before.json after.json` 比较两个映射	git； `<name>.md` 可直接粘贴使用
“日程是什么？哪些事项延期了？”	`kind: gantt`	计划，以及以 `slip` ops 表示的延期
“文档中已经有 Mermaid 图”	`vlmkit-anim import mermaid page.md --out scene.json` ，然后补全	该图；读取其中的 `dropped / changed:` 列表
“给我一个 D2 文件”／“给我一段能粘贴到 README 的 ASCII”／“仓库中已有 `.d2` 图”	`d2-diagram` ——D2 文本由 TALA 布局，并在终端中渲染	同一份 `facts` sheet，再手工将其绘制为 D2；在正文中说明没有任何机制会根据代码校验 D2

每个问题只生成一幅图。如果两个方面都很重要（结构和走查），将它们合并为一个带

sequence

的

modules

场景，或使用

kind: compose

，不要生成两个文件。

Ground it in the source, not in memory

以源码为依据，而不是凭记忆

A map of code is drawn from the code:
```
facts
```
for a directory,
```
repo
```
for the workspace, the import list or
```
package.json
```
files by hand when neither fits. Then
```
check --expect
```
. A map drawn from memory and not checked is a guess with a border round it.
A walk is drawn from the path you read: cite the file and function each beat corresponds to in the caption or in the prose ("
```
handle()
```
in
```
router.ts
```
→
```
dispatch
```
").
Anything you could not verify goes in the prose as "not drawn: …", never in the picture.

代码映射必须根据代码绘制：目录使用
```
facts
```
，workspace 使用
```
repo
```
；如果两者都不适合，则手工使用导入列表或
```
package.json
```
文件。然后执行
```
check --expect
```
。仅凭记忆绘制且未经校验的映射，只是加边框的猜测。
走查必须根据你实际阅读的路径绘制：在 caption 或正文中注明每一拍对应的文件和函数（“
```
router.ts
```
中的
```
handle()
```
→
```
dispatch
```
”）。
任何无法验证的内容都应在正文中标为“not drawn: …”，绝不能放进图片。

Produce

产出

1. write <name>.scene.json            in the repo's docs/ or .vlmkit-anim/, or the scratch dir if it is not to be kept
2. vlmkit-anim check <name>.scene.json [--expect <name>.expect.json]
3. vlmkit-anim layout <name>.scene.json               must report no issue; `why` when the canvas warning names a pair
4. vlmkit-anim still <name>.scene.json --out <name>.svg      a still (structure, a map, a state diagram)
   vlmkit-anim video <name>.scene.json --out <name>.gif --width 640   a walk (a request, an algorithm, a trace)
5. vlmkit-anim explain <name>.scene.json              the beats — this is the skeleton of your prose

Five rounds of edit →

check

at most. If it is not clean by then, deliver the explanation in words, say the figure did not converge and which line stopped it, and keep the scene file for the reader.

按以下步骤产出：

1. write <name>.scene.json            in the repo's docs/ or .vlmkit-anim/, or the scratch dir if it is not to be kept
2. vlmkit-anim check <name>.scene.json [--expect <name>.expect.json]
3. vlmkit-anim layout <name>.scene.json               must report no issue; `why` when the canvas warning names a pair
4. vlmkit-anim still <name>.scene.json --out <name>.svg      a still (structure, a map, a state diagram)
   vlmkit-anim video <name>.scene.json --out <name>.gif --width 640   a walk (a request, an algorithm, a trace)
5. vlmkit-anim explain <name>.scene.json              the beats — this is the skeleton of your prose

最多进行五轮“编辑 →

check

”。如果届时仍未通过，则用文字交付解释，说明图未能收敛以及具体是哪一行导致停滞，并保留场景文件供读者查看。

Write the explanation

编写解释

One sentence of what the picture is and what it was drawn from ("the packages under
```
packages/
```
, from their imports, 12 modules, 19 dependencies").
The beats, in order, one short paragraph or bullet each, reworded from
```
explain
```
— say why at each step, not what moved. Name things by the ids in the picture so the reader can find them.
What the picture leaves out and where to read it (a file, a function, a config).
The files: the SVG / GIF path, the scene, the fact sheet.

Do not describe the picture's geometry ("on the left", "the blue box") — layout is the compiler's and may move on the next edit. Say the id.

用一句话说明图片是什么，以及它依据什么绘制（“
```
packages/
```
下的各个包，依据它们的导入关系绘制，共 12 个模块、19 条依赖关系”）。
按顺序讲解各个节拍，每拍一个简短段落或要点，基于
```
explain
```
的结果改写——说明每一步的原因，而不只是描述发生了什么。使用图片中的 id 称呼对象，让读者能够找到它们。
图片省略了什么，以及到哪里阅读相关内容（文件、函数、配置）。
文件：SVG／GIF 路径、场景文件、事实表。

不要描述图片的几何布局（“左侧”“蓝色方框”）——布局由编译器决定，下次编辑时可能移动。请直接说出 id。

Deliver

交付

In a chat: the prose, then the figure as a file the user can open (
```
SendUserFile
```
when available; otherwise the path). A GIF for a walk, an SVG for a structure.
In a PR or issue: paste the
```
<name>.md
```
that
```
pr
```
/
```
repo
```
write, or the figure with the beats under it. If the repository already posts
```
vlmkit-anim pr --mermaid
```
on every PR (vlmkit's
```
pr-visual
```
workflow does), do not post a second one.
In docs: a
```
```vlm-anim
```
fence (the animation) or
```
```vlm-anim still
```
(the figure) with the scene inline, so the page stays checkable; or the SVG committed next to the page.

在聊天中：先给出正文，再给出用户可以打开的图片文件（可用时使用
```
SendUserFile
```
；否则给出路径）。走查使用 GIF，结构图使用 SVG。
在 PR 或 issue 中：粘贴
```
pr
```
／
```
repo
```
生成的
```
<name>.md
```
，或者放置图片并在其下方附上节拍说明。如果仓库已经通过 vlmkit 的
```
pr-visual
```
workflow 在每个 PR 上发布
```
vlmkit-anim pr --mermaid
```
，不要再次发布。
在文档中：使用
```
```vlm-anim
```
围栏（动画）或
```
```vlm-anim still
```
围栏（静态图），并内嵌场景，使页面保持可校验；也可以把 SVG 提交在页面旁边。

Done condition

完成条件

```
check
```
green (and
```
--expect
```
green when a sheet exists),
```
layout
```
clean.
Every id named in the prose is in the picture, and every beat in the prose is a step in
```
explain
```
.
The user can answer their own question from the figure alone; the prose says why each step is there.

```
check
```
通过（存在事实表时，
```
--expect
```
也必须通过），
```
layout
```
无问题。
正文提到的每个 id 都出现在图片中，正文的每一拍都是
```
explain
```
中的一个步骤。
用户仅凭图片就能回答自己的问题；正文说明每个步骤为何存在。

Anti-patterns

反模式

A figure after the answer, unreferenced. If the prose never names an id from the picture, the picture is decoration; drop it or rewrite.
Drawing what you believe the structure is. Run
```
facts
```
first. Two of five green module maps in one evaluation round were wrong about a real dependency.
Coordinates. A scene with x / y is a drawing, not an explanation, and cannot be re-edited by the next reader. Use the kind that owns the things.
Twelve beats where four would do. Pick the values and the trace that show the one mechanism the question is about.
Skipping
layout
because
check
was green. Lines through labels are what a reader sees first.

答案之后才放图，且正文未引用它。 如果正文从未提到图片中的任何 id，这张图就是装饰；删除它或重写正文。
绘制你相信的结构。 先运行
```
facts
```
。在某轮评估中，五张显示为绿色的模块图里，有两张对真实依赖关系的描述是错误的。
坐标。 带 x／y 的场景只是一幅绘图，不是解释，而且下一位读者无法重新编辑。请使用适合这些对象的 kind。
十二拍才够，而四拍即可。 只选择能够展示问题所指核心机制的值和 trace。
因为
check
已通过就跳过
layout
。穿过标签的线是读者第一眼就会看到的问题。