# Timelinetohtml
> 将性能时间线、Profiler或DebugClock色块与源码对齐，生成“执行配置／关键代码耗时／阶段汇总与实测对比”横向三列的自包含交互HTML。用户要求解释不同rank、核、线程或流水阶段为何快慢不同，逐组估算代码耗时、核对颜色块、演示等待转移或按三列走读性能时使用。
- Skill: `kirrito-k423/timelinetohtml` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kirrito-k423/timelinetohtml`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/timelinetohtml/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Kirrito-k423 (https://skillmd.com/u/kirrito-k423)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kirrito-k423/timelinetohtml
---
# 时间线三列代码对照
把“我看到哪条时间线”“哪些代码花了时间”“这些时间是否解释观测”放在**同一行的三列**里。先辨清参与者和等待对象，再算时间，最后与数据比较。默认交付分析 HTML；不因需要解释性能而自动修改内核、运行集群实验或发布到外部站点。
## 三列交付契约
| 列 | 每个对照行必须展示的内容 |
|---|---|
| 第一列：执行配置 | 配置标识、rank/device、核或线程编号、角色、输入规模；本执行者发送给谁、接收谁的数据、等待谁的发布；影响路径与串行位置的实际索引。 |
| 第二列：代码耗时 | 按真实计时边界划分、互不重复的代码组；原代码或明确标记的伪代码、文件/提交/行号、循环次数、公式、数值与单位、证据类别；单条 API 未知时明确写未知。 |
| 第三列：汇总对比 | 从第二列直接求出的各阶段耗时；与同配置的实测或截图读数并排画条；列出差值、总耗时、未解释的残差与仍缺少的测量。 |
- 一个对照行对应一个完整配置，三列共享同一个 `case_id`。选择配置或修改假设时同时更新三列。
- 桌面默认横向同时可见；窄屏保留横向滚动和最低可读列宽，不用三个标签页替代主对照。
- 不把本次案例的 64 rank、AIV40–55、七组代码或黄绿红三阶段固定成通用规则。沿用用户实际的阶段、颜色和运行规模。
## 从证据到时间账本
### 1. 固定观测口径
读取用户指定源码、时间数据和决定角色分工的上下文，记录仓库、固定提交、文件、函数与行号。区分分析的源码版本和实际运行二进制的版本；无法确认一致时明示。
优先读取原始 trace/CSV；只有截图时保留原图、刻度、行定位和读图误差。区分四类数值：**实测、截图估读、模型推导、未知**。没有读数的配置不能沿用其他 rank 的测量，也不能填零冒充实测。
先确认计时器输出是时间点还是时间差，采用什么时钟和换算参数，图的横轴是绝对时间还是每行独立归零。不能凭各条柱子左端相齐推断跨卡同步起步。
建立阶段映射：`阶段/颜色 → 起止事件 → 本角色实际执行代码`。同一种颜色在不同角色中可能对应不同函数。排除未激活分支，辨认重复打点、无效槽和采集开销。
### 2. 给每个执行者完整身份
始终写成 `(rank, device, core/thread, role)` 等足以区分的组合；不同卡上的同编号核不是同一个执行者。
分别追踪：
1. **发件路径**：本执行者的目的地址、循环顺序、每轮提交和等待条件。
2. **收件路径**：本执行者需要的输入槽，逐槽解码真正的生产者及其循环位置。
3. **本地汇合**：其他核何时发布自己依赖的结果，以及后续消费者又等待哪些结果。
地址未知时用 `rank:buffer + byte_offset` 表示。区分本 rank、同节点其他 rank、跨节点；物理路径或链路延迟没有证据时仅设可编辑假设。不要用发送目标分工替代接收来源分工，也不要把本地共享内存依赖画成跨卡通信。
### 3. 把代码拆成可相加的组
按实际计时边界拆分，不按固定行数切片。给每组稳定编号，并记录其输入状态、核心语句、操作次数、阻塞条件与输出事件。点击编号或行号可看到对应原代码。
父函数和子函数不能同时作为独立成本相加；同一个等待区间只能计一次。只有阶段总时长时，不得宣称已经测得其中每条 `DataCopy`、同步或归约的独立耗时。可以给合计假设与条件公式，并列出哪些子项仍不可辨识。
把等待时间和操作服务时间分开。使用统一的时间原点推导：
```text
可开始时刻 = max(自身前置完成时刻, 必需输入就绪时刻)
等待时长 = max(0, 必需输入就绪时刻 − 到达等待点的时刻)
本地汇合时刻 = max(所需生产者的结果可观察时刻)
阶段耗时 = 本阶段互不重叠的工作与等待之和
```
明确“发起、流水完成、对端可观察、消费者完成”是否相同；没有硬件保证就不要合并。输入到达时刻不是可直接加进阶段的等待时长；输入早到应得到零额外等待，并保留必要的检查开销。
并行或重叠的工作按依赖关键路径计算，不能把各核时间相加当作墙钟延迟。读 [分析数据与计时约定](references/analysis-contract.md) 获取账本字段、统计口径和校验规则。
### 4. 先解释顺序，再解释快慢
从索引和循环中推出“该消息前面有多少次操作”，再用有效单次成本估算排队量。区分源码保证的局部顺序与硬件实际完成顺序，不把局部四个目标的顺序扩大成所有 rank 单调变慢。
解释快核时同时展示它更早进入了哪个等待点：前段较短，可能让后面的等待栏更长。区分：
- 同一完成门槛下，等待在几个颜色之间转移；
- 最慢必需输入进一步迟到，推迟整个完成时刻；
- 下游还有全量等待，局部提前完成没有转化为整体收益。
通信计数场景可按需读 [64p 案例推导](references/64p-example.md)。其中配置和数值只用于示范推导，不是其他设备的默认性能参数。
### 5. 用一份数据驱动三列
将来源、配置、代码组、阶段、观测和假设保存在同一个数据模型；让计算函数与 HTML 展示分开。第三列只能聚合第二列实际使用的代码组，不能另填一套看起来贴合截图的阶段数字。
提供少量有代表性的对照预设，再允许用户选 rank/核或其他关键配置。默认直接打开最能解释问题的一对案例，不把结论藏在多次点击后。
在不混淆事实的前提下提供可编辑参数；需要检验因果机制时，加入反转发送顺序、消除路径成本差等反事实开关。反事实只修改模型，保留原始观测，并明确标注“未执行的实验假设”。所有说明文字也必须随模式改变。
不同配置和模型/观测使用共同时间尺度、同一颜色图例。缺失阶段保留未知状态；只有确认不发生的阶段才显示零。误差较大的模型要显示残差，不能为每行另加无证据的自由参数以伪装精确拟合。
## 页面内容与阅读顺序
先用两三句话回答用户困惑；用明确的两端身份给出一条可追踪实例，再进入三列表格。把长公式、完整源码、截图取值方法和补充配置放入可展开区域，保持核心对照同时可见。
第二列每个代码组显示：`编号 → 具体代码 → 次数/公式 → 耗时与证据类别`。若显示简化伪代码，明确标记并提供原代码入口；不要把解释性注释伪装成仓库原文。
第三列至少显示：`阶段 → 所含组编号 → 模型值 → 观测值 → 模型−观测`，以及三色或多阶段条形对照。代码组被展开或选择时，让对应阶段可辨识；不要用仅有装饰作用的动画代替数据依赖解释。
生成自包含 HTML，内嵌必要代码、数据、样式和图，不依赖 CDN。可导出模型参数与推导结果，但文件名和内容要表明它们不是原始测量。只引用交付内容需要的源码，不把无关配置、凭据或机器私有路径嵌入页面。
展示源码和第三方文本时转义 HTML；把 JSON 嵌入 `script` 时处理 `` 等终止序列。不要对证据中的公式或文本直接 `eval`。
## 验收与交付
按实际改动做以下检查：
- **映射**：手工核对代表配置的发送者、接收者、循环位置、地址及阶段打点；有必要时用程序检查覆盖、边界和零工作分支。
- **时间**：核对单位、共同时间原点、无重复计数；每个阶段等于其互斥代码组之和；并行总时间按依赖计算；未知值不会变成零。
- **反事实**：改变顺序只改变相关项；取消路径差异后，所有数值与解释一致；保留不随模型变动的原观测。
- **证据**：截图估读不冒充 CSV，假设不冒充 API 实测，模型拟合不冒充唯一因果证明；标明未解释差值。
- **页面**：检查三列确实同时展示、选择和参数联动、源码跳转、共用坐标轴、长代码滚动及窄屏可读性。浏览器验收受限时记录具体限制，完成可行的静态检查，不把静态通过称作视觉通过。
交付 HTML 链接、最关键的因果解释和验证范围。逐行实测仍缺失时，附最小打点计划：分别记录准备、发送批次、输入等待、局部汇合和发布尾部，并说明新增打点本身可能扰动小消息耗时。