用途:当用户要求以信息图方式讲解某个问题、issue、PR 或功能时使用。它规定的是仓库统一的视觉与叙述风格,并不授权去实现修复或发布 PR;实际执行需遵循 AGENTS.md 中的工作流。为个人解释用用户语言,PR 描述默认用仓库语言。
主要能力与要求:先明确讲解对象,阅读 issue/请求、源码/API 文档及复现或验证证据;对 PR 要识别 base 与 head 并检查行为变化的两版内容,区分已报告症状、确认原因、提议方案与实际实现结果。若只是提议的修复,全程标注为提议,不把预测当结果。全程使用一个代表性示例,并说明省略的环境配置。
叙述结构:问题优先于解决方案。在首个代码片段前说明谁遇到、触发条件、期望行为与实际结果;从用户代码或操作出发给出带语法高亮的小片段,再逐步连接内部机制、失败点和可观察后果,每节只讲一个因果步骤;随后用独立标题标记向解决方案的过渡,让同一示例走一遍改动后的步骤。功能类用“先前限制/新行为”,重构类说明可观察行为不变。结果需给出有单位、负载、环境和条件的证据,区分分配、CPU 时间与 GPU 吞吐、模拟与原生结果,限制应写在正文。
视觉与输出:采用克制的技术布局,蓝色表示资源、青色表示被复用/修正路径、红色表示缺陷,颜色必须配合文字标签。每张图只解释一种关系,放在对应段落旁。需要图像时优先使用自包含 SVG(含 viewBox、尺寸、title/description、alt),避免脚本、foreignObject、外部字体和栅格嵌入。代码保持文本形式,不用截图。
输出模式:遵守用户指定格式;用户为自身理解要信息图且未指定格式时,默认生成教育性 PDF,并按内容分页,保留可选文本与矢量图,输出前逐页检查裁切、重叠和标签过小,并存放到 .context/work/<topic>/visual-explainer/ 与 output/pdf/。PR 描述默认用原生 Markdown(段落、标题、编号步骤、表格、可复制代码围栏),不把测量、清单、比较、片段做成 PNG/SVG 卡片;仅当 Markdown 无法同样清晰表达复杂关系(如带共享所有权的分支依赖图、缓冲区范围与生命周期、空间映射)时才加图,优先 Mermaid,其次聚焦的 SVG,并在提交前说明为何散文、列表、表格或 Mermaid 不够。PR 不设图片配额,无图是正常结果。
验证与限制:交付前通读开头到首个片段,检查读者能否识别问题及示例代表的是旧/当前行为、绕行方案还是解决方案;只扫标题检查前后过渡是否清楚;核对每步、图和片段与证据一致,标注不确定处,不得编造测量值。PDF 或必要的图像要在预期阅读尺寸下实际渲染并目视检查,XML 解析不等于视觉验证。最终返回产物路径、相关源修订与任何限制。资料未说明具体工具版本、收费或平台支持。