d3group/d3-explainer

D3 Explainer（交互式 HTML，面向作者自身）

<skill-dir> 表示本技能的基础目录，当技能加载时（作为插件安装：${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer；手动复制：~/.claude/skills/d3-explainer），Claude Code 会显示该目录。在每个命令中替换为实际路径。<wording-dir> 表示 <skill-dir>/../d3-scientific-wording，是所有 D3 插件共用的措辞技能目录。

一个离线 HTML 文件，用于向正在撰写研究项目的人员解释该项目：问题是什么、填补了哪个空白、核心思想如何工作、每个推导过程及其原因、代码中各部分的位置、证据显示什么以及还有哪些问题未解决。交互式图表传达直觉；文本贴近来源并注明来源。

读者是作者及其合著者。 这决定了以下几乎所有内容：

• 他们了解该领域。除非他们的笔记显示某处是薄弱环节，否则跳过教科书式的背景介绍。
• 他们想要理解，所以诚实优于完美：假设、论文与代码之间的不一致以及开放性问题各有单独章节，并且解释会标明其性质。
• 他们会对照自己的文件检查断言，因此每个实质性断言都指向其来源，并且构建过程会验证该指针是否存在。
• 详细可以，但不必详尽。只有部分读者想要的深度内容放在可折叠的块中。只有当用户要求时才提供“每个细节”，且仅针对他们指定的部分。

所有 Python 代码通过 uv 运行（uv run、uv run --with <pkg>）；从不使用 pip，从不进行全局安装。

参考文件（按需加载）

文件	加载时机
references/scanning.md	阶段 1：在限定令牌预算内阅读仓库，输入等级，保管库/召回/NotebookLM，先前的解释器
references/content-design.md	阶段 2 和 3：章节骨架、深度预算、如何呈现空白和推导、诚实清单、解释器措辞特有的内容（规则本身：d3-scientific-wording）
references/components.md	阶段 3：HTML 词汇表、来源标签、构建指令、explainer.toml、D3X JavaScript API
references/visualization.md	阶段 2 和 3：设计教授知识的交互式图表；模式目录；陷阱
references/review.md	阶段 4：两个审阅者提示、令牌规则、循环
assets/example/	一个包含已完成解释器的小型仓库。阅读 assets/example/explainer/sections/*.html 一次，以了解每个组件的常用模式。切勿将其复制到用户项目中。

步骤 0：一次性询问

除非用户已经说明，否则在一条消息中询问以下问题，之后不再询问：

范围。 整个项目，还是某个部分（模型、推导、流水线）？ 深度。 focus（一个想法或一个推导：1 到 3 个章节，一个或两个图表，约 5 分钟），overview（4 到 6 个章节，约 10 到 15 分钟阅读），standard（默认：7 到 10 个章节，4 到 8 个交互式图表，1 到 3 个推导，20 到 35 分钟），或 deep（最多 14 个章节）。“深度解释 X”表示标准版加上一个关于 X 的深入章节。 审阅。 light：自动检查加上自己的数字通过，几乎不消耗额外令牌。single：一个审阅代理同时检查保真度和图表，一轮，约 50 到 70k 令牌。standard：两个审阅代理并行运行（保真度对标您的来源；图表和交互性），一轮，合计约 100 到 150k 令牌。审阅者的成本主要是固定下限，几乎不依赖于项目规模，因此我的建议遵循深度：focus 使用 light，overview 使用 single，standard 和 deep 使用双代理审阅。full：两个代理循环直到每个评分达到 9/10，上限为三轮，成本为标准的两到三倍。 措辞。 ste（默认：遵循 ASD-STE100 的简化技术英语，每个句子最多 25 个单词，主动语态，每个单词一个含义；对于英语为第二语言的合著者最容易）或 standard（团队的科技术语，无 STE 限制）。

“快速”、“无需审阅”、“廉价”或“令牌不足”表示 light。“彻底”表示 full。“仅此推导”、“仅解释 X”、“保持简短”表示 focus。“简单”、“STE”或未说明表示措辞 ste；“正常措辞”、“论文风格”或“无 STE”表示 standard。未说明表示深度 standard，并采用该深度推荐的审阅。

当无人能回答时（批处理或代理运行）：采用默认值，决定本技能会询问的每个点，将每个决定记录在 brief.md 的第 0 节中，然后继续。这样 brief 就成为作者可以查看为其决定了什么的地方。

工作流

在每个阶段边界打印一行带时间戳的状态，如同其他 D3 技能：[HH:MM:SS] PHASE: ...。

阶段 1：映射项目（经济地阅读，按正确顺序）

uv run <skill-dir>/scripts/scan.py            # 从仓库根目录运行；添加 --out explainer/scan.md 以保留输出

扫描报告输入等级（A：代码和论文，B：仅论文，C：仅代码，D：仅 PDF，E：仅笔记）、定向文档、论文和每个代码文件夹的最后修改时间（过时的 CLAUDE.md 或废弃的方法会在此处显示）、论文大纲及其公式标签、最大的代码模块及其符号名称和行号、可嵌入的结果文件、包含作者按文件夹分类的笔记的保管库、先前的解释器，以及每个定向文档、论文、章节文件、代码模块和笔记的令牌估计。打印 INPUT TIER: X 并让用户覆盖。

然后按以下顺序阅读，并在可以编写 brief 时停止。详情和预算见 references/scanning.md。

1. 定向文档（CLAUDE.md、README、根目录下的规范或分析笔记）。
2. 论文：摘要、引言、贡献声明，然后是模型和方法部分。浏览结果部分以获取关键数字。
3. 扫描找到的先前解释器：大纲（scan.py --explainer <file>），然后一个完整章节以了解语气（--section N）。它们展示作者已经理解的内容以及他们喜欢的语气。在此基础上构建；不要重复它们。
4. 保管库：概述、概念、空白、决策和开放性问题笔记，按标题选择。不包括文献转储。
5. 代码：仅实现核心思想的模块，通过符号映射找到。对于大型代码库（超过约 40 个文件或 8,000 行），发送一个 Explore 子代理来生成论文到代码的映射，并保留其结论，而不是文件本身。

可选润色，仅在空白或项目历史在仓库中较薄弱时提供：recall 技能（决定了什么，以及何时决定）或 NotebookLM（文献说明了什么）。与 d3-abstract 中的协议相同。当扫描找到文献文件夹、包含导入来源的保管库或 NotebookLM 笔记本时，在同一问题中提供 d3-scientific-wording 的主题概况（步骤 1b）：它显示文献对每个概念使用的术语和拼写，从而为符号表和术语表提供种子。打印 ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile]。

阶段 2：内容概要，在任何 HTML 编写前获得批准

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # 创建 ./explainer：explainer.toml、brief.md、sections/、d3x/
#   仓库中有多篇论文：添加 --paper <folder>         解释器在其他位置：init.py <dir> --repo <repo root>

保存位置：<repo>/explainer/，位于外部仓库的根目录（不在论文子模块内：Overleaf 用不到它）。在与 brief 相同的消息中确认位置。

填写 explainer/brief.md：用两句话描述项目、读者之后应该能够做什么、已阅读和故意未阅读的来源、空白、章节计划、推导、诚实清单、故意省略的内容，以及在 ## Wording 标题下的措辞概要（体裁为解释器，读者为合著者，领域，选择的措辞模式，以及项目结构和符号的术语表）。章节计划每行一个章节，并且对于每个交互式图表，给出其旋钮到洞察的句子：“移动 X 显示 Y”。没有此类句子的图表是装饰性的，会在此处（而不是在构建后）被删除。

在聊天中以紧凑形式显示 brief 并获得批准。这是唯一强制性的检查点：它花费几百个令牌，但可以防止编写错误的 6,000 个单词。在此之前不要编写章节。

阶段 3：逐节编写

在编写第一个章节之前调用 d3-scientific-wording（技能工具：d3-scientific-wording:d3-scientific-wording；当未列出时，读取 <wording-dir>/SKILL.md），并附上来自 brief.md 的概要。在 ste 模式下，还需读取 <wording-dir>/references/ste.md。加载 references/components.md 和 references/visualization.md，并浏览一次示例章节；它们是用 STE 编写的。

• 每个章节一个文件：explainer/sections/NN-slug.html，每个文件恰好包含一个 <section id=... data-nav=... data-kicker=...>。构建过程会对它们进行编号并创建导航。
• 每个章节后立即构建，以便错误保持局部化：uv run explainer/d3x/build.py --draft（TODO 标记和指向尚未编写章节的链接仅发出警告）
• 核心思想章节内的顺序：简单句子、交互式图表、形式化陈述、推导、代码中的位置。直觉优先，代数其次。
• 让仓库说话，而不是重新输入。 <div class="eq" data-label="eq:prob"></div> 从论文的 .tex 文件中提取公式（如果有 .aux 文件，还包括其编号）。<pre class="code" data-src="src/model.py" data-lines="88-104"></pre> 提取实际代码行。两者都比输入更经济，并且不会与源文件产生偏差。
• 使用标签指向来源：[[paper:eq:prob]]、[[code:src/model.py:88 def solve]]、[[vault:Note name]]、[[result:results/table.csv]] 以及 [[reading]] 表示你自己的解释。构建过程会在文件、行、符号、标签或笔记不存在时失败；保管库标签在 explainer.toml 中未配置保管库时仅发出警告。失败的标签表明你的理解存在问题：修复主张，而不是删除标签。
• 交互式图表按优先顺序显示：仓库的结果文件；仓库自己的代码在网格上计算出的数值（一个小的 explainer/data/make_data.py，见 visualization.md）；或者在浏览器中以玩具规模重新实现的真实公式，声明为 toy: true，这会在其上放置一个可见的“说明性玩具”徽章。默认值位于论文的设置处。数值从文件中嵌入，从不凭记忆输入。
• 每个图表标题以 {fig} 开头（构建过程会对图表进行编号；引用为 {fig:figure-id}），并说明要尝试什么以及要注意什么。

阶段 4：验证

uv run explainer/d3x/build.py                  # 不加 --draft：TODO 标记现在会失败；打印每个章节相对于深度预算的单词数
uv run explainer/d3x/check.py --shots          # 无头浏览器：移动每个控件，拖动每个手柄，逐步执行每个推导

check.py 必须以 0 error(s) 结束。然后检查章节的措辞（在 standard 模式下省略 --ste）；修复每个错误并决定每个警告：

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

它捕获阅读源文件无法发现的问题：路径中的 NaN、不改变任何内容的控件、MathJax 无法渲染的公式、在滑块极限处被截断的标签、在手机宽度下页面溢出。在机器上首次运行时可能需要一次浏览器安装：uv run --with playwright playwright install chromium（它会回退到已安装的 Chrome 或 Edge）。

自己查看 explainer/review/shots/ 中的两到三个屏幕截图。然后按所选深度进行审阅；提示和令牌规则见 references/review.md：

• single：一个只读审阅者，使用来自 references/review.md 的合并提示，在一轮中同时阅读两个数据包、check.md 和屏幕截图。然后按以下方式验证并应用。
• light：无审阅代理。自己进行一次数字验证：对照论文或引用的结果文件，验证文本中的每个数字、KPI 磁贴和图表默认值。然后停止。
• standard：两个只读审阅者并行运行，一轮。每次构建将两个数据包写入 explainer/review/：fidelity-packet.md（解释器的文本及其行号、推导步骤及其理由，以及每个标签引用的公式或代码行作为证据）和 figures-packet.md（每个图表的标题和脚本）。保真度审阅者 从第一个数据包检查推导、数字、空白声称和措辞（冷读和 d3-scientific-wording 的规则）；体验审阅者 从第二个数据包检查每个图表是否实现其旋钮到洞察的句子，加上 check.md 和屏幕截图。两者都不需要浏览仓库，这使得审阅成本可承受。在它们运行时不要编辑章节文件。然后亲自验证每个阻塞问题和主要问题，应用它们，重新构建，重新运行 check.py。仅对阻塞问题、由提出该问题的审阅者、仅针对更改过的文件进行第二次查看。
• full：相同的两个审阅者，循环直到每个类别达到 9 或更高，上限为三轮；然后将剩余问题交给用户。

阶段 5：交付

给出路径 explainer/dist/<name>.html（单个文件，可离线工作，可通过电子邮件安全发送）、使用的审阅深度以及包含已修复内容的合并发现表。提及：n 打开符号抽屉，推导通过“下一步”逐步进行，标签链接到构建提交处的 GitHub 永久链接（如果远程仓库在 GitHub 上）。如果仓库有保管库，提议将 HTML 副本放入其中，作者以前的解释器也在那里。一次性询问 d3-scientific-wording（步骤 5）的水印问题；如果同意，清理 explainer/sections/*.html（绝不清理已构建的文件，它嵌入了 MathJax 和字体）并重新构建。提议提交

…

[已截断，以供翻译]