explain-with-code-walkthrough

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explain with Code Walkthrough

使用代码逐步讲解进行说明

Short steps on the left scroll past a sticky code panel on the right, held in the vertical centre of the viewport. For each step the panel shows the right file and highlights the lines that step is about. The reader watches today's code become the proposed code.

左侧的简短步骤滚动时，右侧的 sticky 代码面板保持在视口的垂直中央。对于每个步骤，面板会显示正确的文件，并高亮该步骤涉及的行。读者可以看着当前代码逐步变成建议代码。

Use this skill when

使用此 skill 的场景

The user asks for a visual explanation of changes with a code walkthrough.
Used by an orchestrator to explain changes visually with a code walkthrough.

用户要求通过代码逐步讲解对变更进行可视化说明。
orchestrator 使用此 skill，通过代码逐步讲解对变更进行可视化说明。

Steps

步骤

4–8 steps, in the order a reader should understand them (usually: today's code → where the change goes → the new code → who uses it).
Each step: one bold sentence saying what this step shows, then at most 1–2 short lines.
The current step gets a mild marker (the kit's
```
ev-step.is-active
```
: accent edge and a faint tint). Never dim the other steps.
Deeper explanation, tables and traces go in one
```
ev-more
```
toggle per step whose summary names what's inside (e.g. "Why 5 rows are enough · Tick trace"). The reader should know what they'd get without clicking.
Make toggle content visual: highlighted code, groups, status chips, compact tables. No walls of text.

按读者应理解的顺序设置 4–8 个步骤（通常是：当前代码 → 变更位置 → 新代码 → 使用者）。
每个步骤：一句粗体的话说明此步骤展示的内容，随后最多补充 1–2 行短文。
当前步骤会显示轻微标记（kit 的
```
ev-step.is-active
```
：强调色边缘和淡色背景）。绝不淡化其他步骤。
更深入的说明、表格和跟踪信息应放在每个步骤的一个
```
ev-more
```
切换器中，其摘要需说明其中包含的内容（例如，“为什么 5 行就足够 · Tick 跟踪”）。读者无需点击即可知道会看到什么。
让切换器内容可视化：高亮代码、分组、状态 chips、紧凑表格。不要出现大段文字。

The code panel

代码面板

Show real code from the codebase (or the proposed code), with the file path in the panel header. 3–4 snippets of ≤ 15 lines each are plenty.
Animate with highlights, not content shifts: dim unfocused lines, glide a focus band to the new range, cross-fade when the file changes. Don't grow or collapse lines while the reader is looking.
The panel's first state (file and highlighted lines) belongs to step 1 and must not change while step 1 is current. The first change happens when step 2 becomes current.
Scrolling back up restores the earlier step's file and highlight exactly: set the panel from the step number alone, never from the previous state.
Mark new lines with a green
```
+
```
gutter and removed lines with
```
−
```
.
Select lines by stable ids (tag lines in the code data), not by hand-counted line numbers, which drift.
Keep snippets to the relevant lines plus a little context; mark skipped parts ("⋯ 12 lines hidden") instead of showing whole files. Avoid lines that need sideways scrolling where possible.

显示代码库中的真实代码（或建议代码），并在面板标题中标注文件路径。3–4 个代码片段即可，每个不超过 15 行。
动画应采用高亮，而不是内容位移：淡化未聚焦的行，让焦点带平滑移动到新范围，文件切换时使用交叉淡入淡出。读者查看时，不要让行内容扩展或折叠。
面板的首个状态（文件和高亮行）属于步骤 1，并且在步骤 1 为当前步骤时不得改变。第一次变化只能在步骤 2 成为当前步骤时发生。
向上滚回时，精确恢复之前步骤的文件和高亮：仅根据步骤编号设置面板，绝不要根据上一个状态推断。
使用绿色
```
+
```
gutter 标记新增行，使用
```
−
```
标记删除行。
使用稳定的 id 选择行（在代码数据中为行添加标签），不要使用手动计数的行号，因为这些行号会发生偏移。
代码片段仅保留相关行及少量上下文；标记被省略的部分（“⋯ 12 行已隐藏”），而不是显示完整文件。尽量避免出现需要横向滚动的代码行。

Phones

手机端

Add
```
ev-side--pin
```
to pin the code panel above the steps on phones; keep lines short (≤ 70 characters) so nothing scrolls sideways.

在手机上添加
```
ev-side--pin
```
，将代码面板固定在步骤上方；保持代码行较短（≤ 70 个字符），避免横向滚动。

Building it

构建方式

Build it as a fragment with the
```
explainer-kit
```
skill (its
```
SCRIPTS-AND-TABS.md
```
covers
```
EV.steps
```
). Use the kit's code block (
```
ev-code
```
with
```
data-add
```
,
```
data-hl
```
,
```
data-groups
```
,
```
data-marks
```
) for inline and toggle code.
Lay it out with the kit's
```
ev-side
```
(steps left) +
```
ev-stick
```
(code panel right, sticky and vertically centred below the top bar). The first step starts at the top of its column, level with the code panel (no top padding or spacer); add bottom padding so the last step can reach the middle. Make steps
```
ev-step
```
boxes and drive the panel with
```
EV.steps(steps, function (i) { … })
```
(not an
```
IntersectionObserver
```
, which gets the reverse scroll wrong). Initialise in
```
EV.onShow
```
and re-measure the focus band on resize.
Give each step
```
id
```
+
```
data-toc
```
so it appears in the chapter list.

使用
```
explainer-kit
```
skill 将其构建为 fragment（其
```
SCRIPTS-AND-TABS.md
```
介绍了
```
EV.steps
```
）。使用 kit 的代码块（
```
ev-code
```
，包含
```
data-add
```
、
```
data-hl
```
、
```
data-groups
```
、
```
data-marks
```
）来展示行内代码和切换代码。
使用 kit 的
```
ev-side
```
（步骤位于左侧）+
```
ev-stick
```
（代码面板位于右侧，保持 sticky 并在顶部栏下方垂直居中）进行布局。第一个步骤从其栏顶部开始，与代码面板齐平（不要顶部内边距或占位元素）；添加底部内边距，让最后一个步骤能够滚动到中部。将步骤制作成
```
ev-step
```
框，并通过
```
EV.steps(steps, function (i) { … })
```
驱动面板（不要使用
```
IntersectionObserver
```
，它会错误处理反向滚动）。在
```
EV.onShow
```
中初始化，并在 resize 时重新测量焦点带。
为每个步骤设置
```
id
```
+
```
data-toc
```
，使其出现在章节列表中。