Code To HTML Walkthrough

代码走读 HTML

把源码转换成一个可直接打开、无需网络依赖的单文件 HTML。页面提供两个顶层阅读模式：“代码逻辑”使用 E2E 执行 DAG → 模块函数调用 DAG + 当前函数语义块 → 完整源码；“内存与通信”用大块申请/容量预算 + 空间切片 + 搬运拓扑替换前三个逻辑视图，并与完整源码双向联动。两种模式不要在同一层级抢占空间。

核心纪律

1. 所有结论必须能回到源码行、标识符或调用关系，不要把推测写成事实。
2. HTML 必须嵌入完整源码，不省略、不折叠生成占位符；非当前区域可以弱化但不能消失。
3. 不要向源码行内插入解释性注释。解释放在 DAG 节点、详情抽屉或悬浮提示中。
4. 代码语义强调保持稳定：输入对象用琥珀色，输出对象用蓝色，核心外部 API 用紫色胶囊，内部函数调用用紫色下划线。
5. 明确区分主路径、条件分支和未激活实现。预处理分支、模板特化和未被入口调用的实现不能伪装成主流程。
6. 无法确认的语义先继续调查；仍无法确认时在分析数据中明确标注“待确认”及依据不足之处。
7. 禁止用“语义块 04”“条件守卫 / 路径选择”“继续执行当前函数的数据变换”等可套用到任何代码的占位解释。不能说明具体标识符、状态变化和设计原因的节点视为未分析。
8. 框架分析不是函数分析。完成 E2E 框架后，必须冻结完整函数清单，并让独立子代理逐函数复查；任何未获得 PASS 的函数都不能进入最终 HTML。
9. 通信与数据编排代码不能只画控制流。必须区分 GM、AIV UB、设备控制区和远端 Rank 窗口，逐条记录关键路径搬运的源地址、目标地址、长度、执行引擎和同步条件；没有证据时不得虚构 L1/Local Memory。
10. 内存视图不能只画变量和 copy 箭头。必须向上追踪 allocator/malloc/SHMEM heap 的真实申请点、owner、生命周期、对齐和总容量，区分“用户请求容量”“本次 layout 保留跨度”“底层物理 heap”和“片上 UB”；缺少运行时形状时给符号公式与假设，不得伪造单一数字。
11. 若 layout 同时有 base_offset、total_bytes/span 与 end_offset，必须分别展示，不能把地址末端写成独占跨度；region 同时写“最坏预留容量”和“本次有效/可见 extent”。容量 hint 中未显式计入的结构字节不等于最终净缺口，必须计入末尾大页对齐余量和 hint 自身的形状假设。

工作流

1. 确认输入与输出

• 接受一个或多个本地源码文件，以及可选的入口函数、关注范围和输出路径。
• 未指定输出路径时，在主源码旁生成 <源码文件名>.walkthrough.html。
• 不修改用户源码；分析 JSON 可以作为中间产物保留，也可以在交付后删除。

2. 建立源码事实索引

先完整读取源码并记录：

• 函数、类型、宏、模板特化及其精确行号范围；
• 内部函数调用、外部 API、循环、条件分支、同步点和数据搬运；
• 关键输入、关键输出及其别名传播；
• 编译条件、禁用分支和入口不可达实现。
• GlobalTensor/__gm__、LocalTensor/TBuf/TQue/__ubuf__、共享窗口和设备队列分别对应的实际存储空间；
• 每个关键 DataCopy/DataCopyPad/Copy/URMA WRITE/atomic/MMIO store 的源地址公式、目标地址公式、长度和可见性边界。
• 大块 workspace/heap/arena 的申请调用链、每 Rank 与全通信域容量、alignment、zero-init、复用关系、释放时机；若目标函数只接收指针，继续追踪到上游 owner 和 allocator。
• 区分 allocated_capacity、本次 reserved_span/end_offset 与实际输出 tensor view；最坏预留不能按实际有效 token 数缩小。
• 若底层 allocator 是进程级/设备级全局 runtime，继续追踪引用计数与最终 finalize，而不是把物理 heap 生命周期简化为某一个 wrapper 对象的生命周期。

不要只搜索名字相似的对象。判断“核心对象/API”时，要同时看入口参数、跨函数传递、循环体内频繁访问、最终写回、同步边界和调用结果的消费位置。

3. 先完成全局框架草稿

可以把以下四项交给互不写文件的子代理并行分析；模型与上下文按下节及复查协议分配，不要默认让所有子代理继承主代理的高成本配置：

1. E2E 模块、执行顺序、分支、汇合、握手与全局算法；
2. 函数清单、精确边界、调用者/被调用者和 inactive 状态；
3. 输入/输出/API/内部函数符号索引与代码反向跳转关系。
4. 通信关键路径的 Rank、GM、UB、窗口、SQ/WQE 与 doorbell 空间划分及逐次搬运。

主代理必须用语法工具与文本扫描两种独立手段比对函数清单，解决遗漏、重载合并和边界冲突后冻结 function_inventory。框架阶段只产生 DRAFTED 草稿，不能直接生成最终 HTML。

3.1 分层模型生成函数草稿

• 主代理保留用户选定的模型，负责 E2E、清单冻结、跨函数一致性、疑难裁决与最终合并。
• 普通函数的职责、segments 和 line_notes 默认交给便宜快速模型起草：gpt-5.6-luna / medium；明确的短 wrapper 可用 low。以完整函数为分析单位，不把孤立片段分给缺少函数上下文的代理。
• 普通函数由另一代理用 gpt-5.6-terra / high 独立复查；复杂模板、原子/异步同步、通信协议、allocator/生命周期和内存模型交给强模型（如 gpt-5.6-sol / high，必要时 xhigh）分析与独立复核。具体分级、升级和不可用时的处理见 调度协议。
• 显式指定子代理模型和推理强度，并用 fork_turns="none" 配合自包含任务简报，避免重复继承整个对话；只提供本批函数及必要依赖，但不得省掉完整函数体、关键 caller/callee 或编译条件。
• 草稿和复查按有界批次推进；子代理只写自己负责的中间产物，向主代理返回路径、计数与问题摘要。模型降档不能降低覆盖率、独立性或 PASS 标准，也不保证并行后总 token 一定更少。

4. 强制执行逐函数独立复查

严格遵循 逐函数复查协议：

1. 把冻结清单中的每个函数定义分配给独立子代理复查，包括短函数、helper、模板分支、inactive 和 legacy 实现。

2. 受并行槽限制时分波执行并复用 reviewer；批次只是调度单位，每个函数仍必须返回独立 review record，不能只写批次总结。

3. reviewer 重新读取函数体、关键成员声明、直接 caller/callee 和条件编译上下文，不能只复述框架草稿。

4. 每个函数的 line_notes 必须逐行覆盖签名、语句、注释、空行、花括号和预处理行；每行说明它在当前函数中的具体作用。

5. 每个语义块必须明确写出具体输入状态、机制/公式、输出状态、存在原因和源码标识符证据。

6. reviewer 与该函数草稿作者必须不同；有遗漏、泛化解释或未解决语义时返回 REWORK。

7. 主代理只合并 PASS 记录，并验证：

   冻结清单中的函数定义
   = 最终 functions[]
   = 具有有效独立 PASS 的函数
   

集合不相等时停止渲染，不能通过删除难分析函数绕过门禁。

若存在 memory_model，还必须由不同于内存草稿作者的 reviewer 对照 allocator、owner、layout、copy 和同步源码独立复核，并冻结主仓与相关 allocator/submodule 的 revision；memory_model.review 未获得 PASS 时同样停止正式渲染。

5. 生成分析 JSON

按照 分析数据契约 生成 JSON，并满足：

• modules[].ranges 合并后覆盖每一行源码；
• 使用 primary_path 按真实模块有向边声明一条典型执行路径；前端据此编号模块、居中纵向排布主干，并把并行、辅助和未激活模块放到侧支路；
• E2E 边使用真实函数或模块关系，表达分支、汇合、并行和握手，不要退化成一条线性列表；
• 每个函数的 segments 连续覆盖函数全部行，按完整语义动作切分，每块 1–60 行；优先保持完整公式、循环、条件编译段和同一搬运协议，不要按固定小窗口机械切片；
• function_inventory 与 functions 一一对应，每个函数都有独立 review 和逐行 line_notes；
• 每个语义块包含 input_state、mechanism、output_state、why，且引用本段真实标识符；
• 内部调用必须指向已声明函数，外部 API 必须带精确源码行；
• 输入、输出和符号名称必须是源码中的精确标识符，包含关键别名；
• 只有真正影响理解的算法、协议和硬件约束才写入 tips。
• 通信或数据搬运密集代码使用 memory_model 声明空间、区域、搬运和远端/self-copy/shared/control 路径；每条搬运必须绑定真实函数和源码证据行。
• memory_model.allocations 声明真实大块申请或 kernel 资源预算；memory_model.resource_budget 同时给每 Rank、全通信域、每 AIV 的容量公式、估算假设与高风险缺口。
• memory_model.resource_budget 将 base_offset、total_bytes/span、end_offset 和 allocator 容量门禁分开；每个 workspace region 同时记录 reserved capacity 与 visible/used extent。

6. 校验并渲染

在本 Skill 目录执行：

python3 scripts/render_walkthrough.py \
  --source /绝对路径/source.cc \
  --analysis /绝对路径/source.analysis.json \
  --output /绝对路径/source.walkthrough.html

公开或共享 HTML 时，可用 --source-label 仓库相对路径或源码URL 覆盖页面中展示的本机绝对路径；该选项只改变显示标签，不改变实际读取的源码文件。

渲染器默认运行严格门禁，会拒绝：越界行号、重复 ID、无效连边、函数语义块缺口、逐行解释缺口、泛化占位短语、未复查函数、未独立复核的内存模型、清单/分析/PASS 集合不一致，以及未被任何模块覆盖的源码行。输出 HTML 内嵌样式、脚本、源码和分析数据，不使用 CDN 或远程字体。

只需要检查数据而不生成页面时使用：

python3 scripts/render_walkthrough.py \
  --source /绝对路径/source.cc \
  --analysis /绝对路径/source.analysis.json \
  --validate-only

只有搭建界面骨架时才可显式使用 --allow-unreviewed-draft。草稿页面必须显示“函数复查未完成”，不得作为最终结果交付：

python3 scripts/render_walkthrough.py \
  --source /绝对路径/source.cc \
  --analysis /绝对路径/source.analysis.json \
  --output /绝对路径/source.draft.html \
  --allow-unreviewed-draft

7. 浏览器验收

至少逐项验证：

• 点击 E2E 节点后，中列切到对应函数，代码列滚动并弱化非当前范围；
• 当前 E2E 模块必须使用明显的填充背景色、边框和外发光共同强调，不能只靠细描边区分；侧支路与未激活节点被选中时也不能被自身底色或透明度覆盖；
• E2E 模块与函数调用 DAG 的节点说明即使在紧凑节点内截断，也必须支持悬浮查看全文、单击固定全文说明，并可通过关闭按钮、点击空白处或 Esc 收起；
• E2E 节点显示典型执行编号和源码大致范围；典型路径居中从上到下，分支置于两侧，并提供缩小、放大、适合列宽和 Ctrl/Command + 滚轮缩放；
• 页面三列四块必须可调尺寸：两条竖向分隔条分别调整 E2E/函数列和函数/源码列宽度，中列横向分隔条调整函数调用 DAG 与逐段理解高度；拖拽时遵守各块最小可读尺寸，结束后重新居中当前节点；分隔条支持方向键微调、Shift 加速、双击局部重置，并提供全局“重置布局”按钮；
• 中列上半区根据 segments[].calls 展示当前模块函数的嵌套调用 DAG，同时标出跨模块被调函数；点击任一函数节点后，下半区和源码同步切换；
• 页面顶层支持“代码逻辑 / 内存与通信”切换；内存模式必须同时替换 E2E DAG、函数调用 DAG 和函数逐段理解，横跨原前两列并占满高度，不能继续挤在函数 DAG 的半块空间中；完整源码列始终保留；
• 内存模式先展示 allocator/malloc 大块、每 Rank/全通信域/每 AIV 容量口径、alignment、生命周期、复用与风险，再展示当前 Rank GM、AIV UB、目标 Rank GM 和 URMA 控制面的区域与搬运；
• 内存视图至少提供远端 MoE、self-copy、shared expert 和 URMA 控制面路径；当前路径的搬运箭头应动态显示方向，并明确源/目标所属 Rank；
• 密集搬运图不得把 API 标签堆在拓扑节点上：把当前路径步骤放在独立、可横向滚动的步骤条，画布只保留实心节点和可点击箭头；相同端点的多条边必须自动分配不同轨道，非当前节点也不能因整体透明而让背后连线穿透正文；
• 点击任一搬运后直接显示源地址公式、目标地址公式、长度、引擎、同步条件和证据行，并同步切换 E2E 模块、函数、语义块与源码高亮；
• 同一源码 API 在不同 owner 或不同路径上发生时分别建边，例如远端窗口与本 Rank self-copy 窗口不能合并成一个模糊“GM”；
• 点击函数语义块后，代码准确滚动并高亮对应行；
• 每个语义块直接展示“输入 → 机制 → 输出 → 为什么”，不能只有类型标签；
• 代码文字区域保持原生选择与复制行为，不绑定整行点击事件；通过行首反向定位按钮或显式打开隐藏列时，能查看当前行的具体 line_notes；
• 点击内部子函数后，函数 DAG 和代码同步切换，并把父函数、实际调用行和所在语义块压入函数下钻栈；中列提供“返回上一层”按钮和可点击调用路径面包屑，多层嵌套可逐层返回或直接跳回任意祖先；返回时必须恢复父函数调用现场，而不是只跳到父函数开头；
• 悬浮代码行时在行号左侧出现反向定位按钮，点击后前两列切回对应模块和语义块，并把首列当前模块在可滚动画布中水平、垂直居中；画布四周必须预留足够滚动缓冲，使位于边缘的主路径或侧支模块也能真正居中；
• 页面显示源码覆盖 N / N，且 N 等于真实源码行数；
• 搜索显示“当前匹配 / 全部匹配”和命中行数，支持上下按钮、Enter 下一处、Shift+Enter 上一处、首尾循环；
• 当前搜索命中强高亮，其他命中弱高亮；无结果状态清晰，Esc 可清空；
• 输入、输出、核心 API 和内部函数在初始视图中无需悬浮即可识别；
• 浏览器控制台无错误，浅色主题文字和连线对比度足够。

8. 交付

向用户提供 HTML 的绝对路径链接，并简要报告：

• 覆盖的源码文件、总行数、模块数、函数数和语义块数；
• 独立复查 PASS / 冻结函数总数；两者必须相等；
• 被标记为未激活或条件编译的实现；
• 仍待确认的假设或缺少的构建上下文。
• 若存在 memory_model，报告可视化的空间数、区域数、关键路径数和搬运数，并明确未见显式使用的缓存层级。
• 简述实际用模、升级/返工次数；有运行记录时分别报告输入、缓存输入和输出 token，没有则明确不可得。未经同口径实测，不宣称具体节省比例，也不把 token 或 API 标价直接换算成 Codex 额度。

除非用户明确要求，不要修改源码、提交 Git 或启动长期驻留服务。