# Data Flow Animation > 将并行、分布式、算子或流水线源码转为面向初学者的数据流动画，说明各 rank 的初始变量、数组形状、批次命令、传输映射与代码对应关系。用于用户要求数据流动画化、双屏联动演示、逐步观察数组读写，或改进动画的一屏布局与当前步骤高亮时。默认控制解释屏与动画屏各分其职，共享进度，每步读写及对应代码以红色高亮。 - Skill: `kirrito-k423/data-flow-animation` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add kirrito-k423/data-flow-animation` - Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/data-flow-animation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Kirrito-k423 (https://skillmd.com/u/kirrito-k423) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/kirrito-k423/data-flow-animation --- # 数据流动画化 把“每份数据原来在哪里、谁在本步操作它、经过什么命令到哪里、为什么能够并行”做成可暂停、可追踪、与源码对应的动画。优先交付可运行的演示，而不是只给布局建议。 ## 交付原则 - **双页各分其职**：默认一个控制与解释页、一个专注数据流的动画页，能在两个显示器分别全屏，共享唯一进度。用户明确要求单屏时按其要求调整。 - **每阶段一屏完整**：针对实际浏览器可用视口组织内容，减少换页和滚动；不能靠裁掉内容或缩成难读的小字宣称一屏完成。 - **当前操作统一红色**：本步的读取、写入、活动连线、关键结果和实际执行代码一起突出；暂停后仍保留，进入下一步后重点移动。 - **数据与代码可核对**：图中对象使用真实变量名，具体数字由同一模型推导，能追踪来源、去向、索引和源码位置。 - **教学时序有边界**：明确区分源码语义模拟与实机执行追踪，不能把教学批次当成硬件全局同步时刻或性能测量。 - **通信默认至少四个 rank**：四个参与者必须都有真实模型状态，重新推导每个对端的路由、队列、通知和输出；不得只复制装饰面板。用户明确限定更小规模时遵循用户要求。 - **纯白底、无隐含数字、无遮挡**：默认 HTML 页面背景为 `#ffffff`。编号、数据值、字节数、权重、状态值要有字段名与解释；元素不出界不等于元素不重叠。 - **数据对象的内部变化是主线**：先展示对象由哪些字段、结构体或数组组成，再逐步展示元素何时被谁从什么值写成什么值。不能把动画简化成对象名字之间的移动箭头或几个状态数字。 ## 工作流程 ### 1. 固定源码与分析范围 优先利用当前项目和已有实现继续改进。用户指定远端文件时，获取该仓库、分支的真实内容并记录提交标识；不要用另一个分支的同名文件替代。页面读取失败可用 Git 获取。缺少必要源码时先完成可验证部分，再明确缺失的信息。 读取目标函数及必要的调用者、输入生产者、输出消费者、内存分配与同步代码。先解释这个函数实际搬运的是 token、计数、索引还是标志，再决定画什么。源码注释与实现冲突时依实现建模，并指出差异。 整理简短的证据与假设：源码版本、分析入口、示例参数、合法输入约束、尚未实测的硬件行为。示例数值是教学选择，不冒充用户运行配置。 ### 2. 建立变量账本和批次模型 阅读 [数据模型与验证](references/model-and-validation.md)，建立一个独立于页面的计算模型。 每个重要对象至少记录：所属 rank / 核 / 线程、真实变量名、内存层级、dtype、逻辑形状、有效元素数、分配容量、对齐与填充、索引到地址的公式、生命周期。明确字节和元素单位，以及不同变量是否指向同一存储。 先制作“对象目录与剖面”：输入数组、临时结构／UB、打包块、通信描述符、独立标志、接收副本、输出数组分别列出字段名、类型、索引范围和嵌套关系。连续内存的逻辑记录要说明并非真实 C++ struct；padding 未定义时不能随意画成 0。为每个可观察元素记录来源、当前值、上一步值、本步操作、操作者、时刻／教学步骤与源码位置；复制只改变位置、格式化重排、状态清零要分别表达。 默认主视图跟踪一条具体记录穿过对象链，并显示“原值 → 新值”，同时保留至少四个 rank 的概览。较长数组可按有解释的索引区间折叠，但必须能展开完整数组或选择任意元素，查看其逐步值历史；不能只展示首元素却暗示已经解释整个数组。零值必须与“未初始化／未写入”区别展示。当前操作是读还是写不能仅由数值是否变化判断。 每个步骤描述：批次编号、执行主体、函数与命令、读取对象及范围、写入对象及范围、实际数据、完成或等待条件。把跨 rank 并行、核间分工、核内循环顺序和异步提交分别表达清楚。 先用小而有区分度的输入算通全过程，再设计动画。通信任务默认至少四个 rank，并包含多个来源、多个目的、空对端和本机路径；默认数据应包含非零、零和不均匀分布。参数改变后，从模型重算数组、形状、步数和代码分支，包括发送核编号影响的路由或队列选择，不能把两卡专用公式直接复制到四卡面板。 阅读 [教学与视觉验收](references/teaching-and-visual-acceptance.md)。把每个可见数字登记为“索引、载荷、计数、大小、状态、教学参数”之一。就近写字段名、单位、取值含义；计算量给公式，教学数值注明人为选择。禁止使用 `t0 · 1` 这类把记录编号与数据值混在一起的标签。应分别写“token 编号 0”和“首元素值 1”，并解释首元素是 `x[token, 0]`，不是整个 token 或 flag。 ### 3. 分配双屏内容 | 页面 | 主要内容 | 交互职责 | |---|---|---| | 控制与解释屏 | 唯一主进度条、阶段说明、真实源码节选及行号、参数、当前记录的来源与去向 | 播放、暂停、前后步、重置、调速、跳阶段、打开动画窗口 | | 数据流动画屏 | rank / 核泳道、数组与内存区域、活动传输、接收布局、当前阶段结果 | 查看当前数据流，点击对象反向联动控制屏的追踪详情 | 动画屏只保留简短阶段标题、必要状态和图例。长解释、完整变量账本入口、代码详情归控制屏。两页显示一致的步骤标识，用户能够立即核对联动状态。 按阶段切换信息密度：输入阶段展示初始数组；发送阶段展示本批源块、连接与目的布局；汇总阶段展示核间小计与起始偏移；累加阶段展示当前读取和输出。已完成且不再参与本阶段的细节收起，但保留理解当前操作所需的上下文。 每段源码必须显示所属函数的准确名称、定义行、调用者或调用链、固定提交和文件名。展示当前语句前后的连续原始上下文，覆盖必要的条件、循环、变量定义与语句边界；当前执行行红色，上下文灰色。长函数在明确的区间之外用 `⋯` 标示省略，提供含签名的完整函数入口。跨函数步骤用有名称的片段页签，不拼成看似同一函数的无名语句集合。不得用伪代码冒充原文，也不得把内部裁切的代码框当成完整展示。 ### 4. 实现共享进度与语义高亮 实现前阅读 [双屏联动与高亮](references/dual-screen-and-highlighting.md)。推荐 `control.html`、`visual.html` 共用模型、源码索引和状态模块；已有项目可沿用其框架，无须另建技术栈。 同设备、同浏览器配置文件的双窗口可用同源 `BroadcastChannel`；共享一个 session 和权威状态，以共同时间锚点推导播放进度。支持后加入、刷新恢复、反向选择和多个控制窗口不重复推进。页面应说明联动范围，不能暗示可以跨浏览器或跨设备同步。 以模型给出的显式读写集合和源码行集合驱动红色，不能只比较数值差异。零值写入、同值重写、新副本都属于当前操作。未执行分支不高亮。rank 身份色、完成状态和用户选中状态使用独立视觉语义。 新步骤轻闪一次帮助定位；暂停时保留静态红色，心跳、速度变化或选中操作不重复触发步骤闪烁。遵守 `prefers-reduced-motion`，并用边框、读写标签等辅助线索，使颜色不是唯一信息来源。 ### 5. 检查真实一屏布局 使用受视口高度约束的网格，例如 `100dvh`、`minmax(0, 1fr)` 和 `min-height: 0`。检查各面板和数组实际内容，而不只检查页面根节点是否滚动。 默认 `html`、`body` 与页面主容器均为纯白背景，分区用留白、边框、标题区分；局部操作色不能扩展成整页深色或灰色底。用户给出背景约束时，将其纳入实际 computed style 验证。 复杂矩阵优先分成同屏的多个连续分组，重复必要行列标题；保留 rank、来源和目的索引。较大规模若不能全部可读展示，应明确哪些是聚合视图、哪些是可选详情，不能隐藏数据却暗示已经展示全部。 按用户屏幕条件验收；未知时以 1280×720、1440×900、1920×1080 的 **CSS 视口**作为桌面参考。每个页面分别读取实际 `innerWidth / innerHeight`，不能把请求设置的尺寸当成已生效；测试函数显式传入当前标签页句柄，避免闭包引用旧页面。遍历全部阶段与最高密度预设，检查未选中、已选中、读写徽标出现、弹窗和较长文字状态。 同时检查两类缺陷：①容器溢出／裁切；②本应分离的元素发生交叠。对卡片、相邻区块、表头／正文、字段标签／数据值、读写徽标／文字、按钮与源码行做矩形相交和文字边界检查。祖先包含子元素、刻意放在专用轨道内的动画粒子可作为有说明的例外；不能把所有绝对定位元素排除。传输线优先走独立通道，禁止穿过标签或覆盖数值。尺寸脚本通过后，仍须实际查看最拥挤的截图。 ### 6. 验证后交付 先验证算法不变量，再实际操作浏览器，避免“动画流畅但数字错误”。重点验证： - 输入到输出的路由、数量和前缀能核对；零值、集中路由、不均匀分工及合法边界场景符合代码。 - 双页播放、暂停、步进、拖动、重置、调速和参数更新一致；点击记录反向联动；后加入和刷新能够恢复。 - 本步输入、输出与代码同时红；上一步回归普通状态；零值新写入仍红；暂停不丢重点；实际未执行分支不红。 - 所有主要阶段在目标视口可完整阅读；没有隐藏溢出、相互遮挡或未解释数字；函数名称和连续源码上下文可定位；背景实际为纯白；浏览器无相关脚本错误。 交付页面入口、一条启动命令、源码版本与模型边界，以及实际验证结果。没有执行的检查应直接说明。双屏使用方式为：同一浏览器打开两页，将动画窗口拖到第二显示器，分别全屏。弹窗受限时提供可手动打开的链接。 默认使用本地 HTTP 服务和内存状态，不增加数据库或持久化。需要跨设备时再采用必要的服务端同步。遵循当前项目的保存与提交约定；只有用户要求时才发布或推送远端。 用户指出可读性或重叠问题时，先重现其具体截图／步骤，再修复模型或布局；写出“原错误 → 方法原因 → 修复 → 新增验收”。不能用大量通过的无关测试掩盖该问题。将可复用教训更新到本 Skill；用户授权推送时，验证规范源与全局链接后提交到所属 Skill 仓库，并核对远端提交。