viz 是做什么的？
一个固定渲染器 assets/viz.js 绘制所有视觉元素。代理只需编写符合语法的数据，因此一个视觉元素的 token 成本与它所替代的 ASCII 树相当。作为交换，它获得了步骤回放、节点检查器、边追踪、过滤和路径复制功能。
选择视图
编写数据，而非 HTML：一个 == graph 节（节点、路径和 view:）或一个图表节。根据读者提出的问题来选择，然后仅阅读所需的语法：语法 用于图、树和差异，图表 用于 == timing、gantt、hist、retries、causes、board、stock 和 waits。
它是如何流动的？
- 组件之间的数据移动（分支、回退、异步跳转、故障出口）→
view: flow，默认视图。"带我过一遍"会添加一个叙述尾（见下文）。用移动的内容标记每条边，并按发生顺序声明边；数字会随之生成。 - 谁执行操作、发送什么、什么内容被过滤、结果如何 →
ranks:列，每个触发器一条路径，成功通过则以=> result结束，被过滤掉则以=| result结束。团队或服务作为带状 → 添加lane:。 - 服务之间的请求随时间变化 →
view: seq，当等待时间重要时加上at:时间。当调用的顺序和之间的等待是关键点时选择 seq，当分支是关键点时选择 flow。每个消息后各服务所处的状态 → 在边下添加sets: id=*charging，在节点下添加state:。 - 一个字段或任务的生命周期 →
view: states，每个故事一条路径（!giveup: running > blocked => dead）。面向用户的流程添加起始点（[*] -> form）、色调和group框（视图）。 - 谁调用了谁 →
== tree。某一时刻的调用栈，包含出错的数值 →view: stack和locals:。
何时运行，持续多久？
- 同时运行的内容：竞争、重叠的工作 →
== timing，每个工作线程一条轨道，并在重叠区域加上!window。 - 为什么重试堆积：退避、抖动、放弃点、多个客户端同时 →
== retries，添加policy:。 - 请求的延迟去向以及哪个链限制了它（关键路径、松弛时间）→
== gantt，用after链接条形图；budget:绘制限制线，在变更行上使用was 140ms可在其下绘制旧运行结果。
有多少？
- 流量如何拆分：流量分割、漏斗、请求在哪里掉队 →
view: sankey，每条路径下添加weight:，掉队的路径以=| <exit node>结束。当流量重要时使用 sankey 而非ranks:。 - 它是尾部还是全部（p50 vs p99、延迟回归）→
== hist，使用was:表示旧分布。 - 一个数值随时间变化并对照阈值（队列深度、滞后、池使用量），作为库存-流量图 →
== stock，使用meter:带区。对于重复的模式，绘制一个典型窗口并指明。
为什么中断了，卡在哪里？
- 谁持有哪个锁，谁在等待它，死锁 →
== waits；它会找出循环。 - 事件的可疑原因，已确定或已排除 →
== causes，鱼骨图。 - 跨阶段的工作项（回填中的分片、管道中的任务），包含在制品限制和阻塞项 →
== board，看板。 - 检查读取了哪些输入，哪些触发条件保持每个输入的新鲜度 → 在图形之后添加
== cover；编写器×字段矩阵 →columns: <rank>。
发生了什么变化？
- 对单个布局的更改 → 节点和路径上的
+和-；读者获得一个 "更改前 | 同时显示 | 更改后" 切换开关。 - 更改对调用树的影响 →
== diff，由转换器生成而非手动编写。<viz>是这个技能的目录；前两个参数是基础引用和头引用（PR 的基础分支，然后是HEAD）；<paths>限制扫描范围：
python3 <viz>/scripts/viz.py calldiff main HEAD --max-depth 4 <paths> # 打印 base + == diff，未更改的子树折叠
python3 <viz>/scripts/viz.py calltree --entry submitForm
根据需要添加到任何视图：
- 每一步的原因 → 路径上的
| payload | narration尾；每个都成为一个重放步骤。 - 一个演练场景的设计文档 →
theme drawing，步骤下添加shows: id = text，以及当一个数值决定结果时使用meter:（绘图）。 - 一个将被保存、打印或分享的页面 →
theme paper。它会绘制自己的画布，因此内联 T3 渲染保持默认主题。
所有内容都要有证据支持。每个节点需要 @path:line 以及关于读取、写入和失败行为的详细信息行。每个数字（持续时间、权重、级别）必须来自追踪、日志、查询或代码。任何你尚未读取或测量的内容都要用 ? 标记：在节点、路径、条形图或段落前加上 ? 前缀，并在库存数据点上添加 # estimate 注释。
展示它
T3 Code（工具列表中有 html_render）：直接将页面写入 html_preview，读取其控制台以获取 viz: 解析错误，然后将同一页面传递给 html_render。请勿粘贴 viz.js。
<!doctype html><script src="https://cdn.jsdelivr.net/gh/Yeshwanthyk/agent-skills@efe8911d3765b764d7f0bf775e395d5201e29b16/skills/viz/assets/viz.js"></script>
<script type="text/viz">
…
</script>
如果预览控制台显示脚本加载失败，回退到下面的页面（任何其他地方）并告诉用户它的路径。切勿将 viz.js 内联到 T3 渲染中：每次调用大约 55k token。
任何其他地方：将数据保存到 /tmp/viz/<name>.viz，然后运行 python3 <viz>/scripts/viz.py html /tmp/viz/<name>.viz --open。它会报告解析错误，写入包含内联渲染器的 /tmp/viz/<name>.html，并在浏览器中打开它。在安装了 glimpse 的 pi 上，在那里打开该文件（pi）。报告路径。
在必须保持自包含的已保存页面内部（用户保留或分享的页面）：在视图所在位置编写 text/viz 块，以 <script data-viz></script> 结束 body，然后运行 viz.py inline page.html。更新 viz.js 后重新运行。为故事标题、表格行或术语表条目添加 data-viz-id="<node id or path name>"，悬停时会高亮页面上每个图中的该部分，无需页面脚本。
回复
视觉元素承载了结构。回复仅添加它无法展示的内容：你未验证的内容，以及最先查看的一个要点。
完成
当视觉元素在没有 viz: 错误的情况下渲染，每个节点和数字都有证据支持或标记了 ?，并且你已经在读者将要看到的地方查看过它：T3 内联，或打开页面的截图。无头加载、curl 或干净的控制台不算查看；当你无法查看时，应说明情况，而不是声称已渲染。