eli5

eli5

像是向一个对这段代码一无所知的人解释：先用一句话说明，然后一次讲一部分，直到全貌呈现在眼前，而读者此时已经了解其中的每一部分。

一无所知的读者看不懂图表，但能看懂两个方框和一支箭头。因此，画布从两个方框开始，逐步扩展。全貌是读者最后看到的内容，而不是最先看到的；到那时，它不会再包含任何新信息。

你只需编写一个图文档。它的视图是逐步扩展的图，演示会按顺序播放这些图，而 PR Lens 会绘制它们。读者打开链接并按下播放键即可。没有页面、没有列表、没有段落。

你需要准备什么

PR Lens 手册及其参考页面。PR Lens CLI 会打印这两者。运行 npx @coldtea/pr-lens-cli@latest skill，然后运行 npx @coldtea/pr-lens-cli@latest skill references，并在编写第一份文档前阅读两者。除非本页标注了覆盖规则，否则手册中的规则在这里同样适用。

操作手册

1. 先写答案。 阅读代码，直到你能用不超过 48 个字符说清它对用户有什么作用，因为这句话也会作为演示标题，而标题最多只能有 48 个字符。请数清字符数。

   • 对于功能或命令：“当你 ___ 时，这段代码会 ___。”例如：“当你点击发送时，它会给所有人发邮件。”
   • 对于整个代码库：说明产品的用途。例如：“BestRegards 会帮你发送新闻邮件。”这句话说的是产品，而不是它的某一条执行路径。 覆盖规则，摘要。 这句话也会作为文档的 summary。参考文档要求写一段关于变更的介绍；eli5 要的是这句话。

2. 聚焦执行路径。 对于某项功能，追踪输入到达输出的唯一一条路径。对于整个代码库，先列出用户会用产品完成的 3 到 5 件事，再追踪其中最主要的一件：也就是产品名称或卖点所指的功能，或者代码量最多的功能。路径上的部分构成图表：4 到 10 个节点、2 到 5 个泳道。辅助代码、配置、类型和测试都不要放进去。如果两个入口最终汇合到同一段代码，画出它们汇合的位置，并在其内容中写明两个入口的名称；不要漏掉任何一个入口。

3. 编写 .pr-lens/graph.json。 遵循 references/graph-document.md，并遵守以下规则：

   • 覆盖规则，来源信息。 模式要求提供此信息。使用 git remote get-url origin 获取远程仓库地址。https://github.com/acme/mail.git 和 [email protected]:acme/mail.git 都应转换为 { "owner": "acme", "name": "mail", "host": "github.com" }。将当前的 HEAD sha 同时填入 base.sha 和 head.sha。关于“两个提交相同的补丁”的解析规则针对的是 patch，不是 provenance，因此此处通过验证。
   • 泳道应是读者能想象出的地点，按路径运行的先后顺序从左到右排列，例如：“你的浏览器”“网站”“邮件公司”“你的邮件阅读器”。不要按文件夹树排列。设置 order。路径中多次接触的数据库或队列不算路径上的地点；应将它放入拥有它的代码所在泳道。
   • 第一个节点应是读者，或读者接触的对象，例如：“你写邮件”。读者必须出现在第一幅图中。对于人物，使用 kind: "external"；模式中没有 person 类型。
   • 节点的 label 应用不超过三个词说明该部分的作用。真实名称放在 subtitle 中，文件放在 files 中。
   • 覆盖规则，差异。 除非对象是拉取请求，否则每个 delta 都设为 unchanged。
   • 不要添加 stats。没有差异可供统计。
   • 恰好设置一条 emphasis: "hero" 的边：它表示答案句所描述的交接；如果移除这条边，答案句就会变成错误。路径上的每条边都设置 animated: true。
   • 如果路径是一连串步骤（几乎总是如此），就使用一个 flow。Flow 步骤标签应以通俗的词语说明传递的内容。

4. 编写逐步扩展的视图。 覆盖视图规则。 这会取代 pr-lens 技能中的 C4 决策树。eli5 视图是同一张图逐步扩展，而不是逐层深入。

   • 视图 1 包含 2 个节点：读者和他们首先接触的部分，以及两者之间的边。范围：{ "kind": "selection", "nodes": [...], "edges": [...] }。
   • 每个后续视图都包含上一个视图中的全部内容，再沿路径新增 1 到 3 个节点，以及它们之间的边。每个视图新增的部分不得超过 3 个。唯一例外是下方的代码库视图。
   • 最后一个架构视图展示整个系统："scope": { "kind": "all" }。只有它设置 "defaultOpen": true。它之前的逐步扩展视图仍须至少缺少 1 个节点，这样两张图才不相同；pr-lens 禁止两个视图包含相同节点的规则仍然适用。覆盖视图规则。 逐步扩展的视图本来就会有大部分节点相同；只有最后两个视图必须不同。
   • 对于整个代码库，视图 2 包含读者，以及产品所做的 3 到 5 件事，作为产品泳道中的节点。此视图最多可新增 5 个部分；它们是列表，不是路径。从视图 3 开始，沿主路径逐步扩展。其他事项留在图中，让读者知道它们的存在。
   • 一个数据流根节点，范围限定为该流程："scope": { "kind": "selection", "flows": ["<flow id>"] }。必须有它，否则流程永远不会绘制出来。
   • 所有视图都是根视图。不要嵌套。
   • 按视图中展示的内容命名：you-and-the-editor、plus-the-queue、the-whole-thing。

5. 编写讲解步骤。每个逐步扩展视图对应一步，然后是流程，最后是整体。 先计算数量：逐步扩展视图，加上 1 到 2 个流程步骤，再加上 1 个收尾步骤，最多 9 步。若有 10 个节点，就需要 3 到 5 个逐步扩展视图，因此每次扩展 2 或 3 个节点，而不是 1 个。

   • 覆盖标题规则。 标题描述发生了什么，而非发生了什么变化：“网站打包了你的邮件”。不要给步骤编号；画布会计数。
   • body：一行，不超过 140 个字符，让聪明的 12 岁孩子读一遍就能理解。先说发生了什么，再说这意味着什么。数字用阿拉伯数字。
   • 步骤 1 展示视图 1，不设置焦点；标题是答案句，正文介绍这两个部分：“这是你，以及你写作时使用的屏幕。一切都从这里开始。”
   • 每个后续步骤都展示下一个逐步扩展的视图，并且只聚焦新增节点，使用 { "kind": "selection", "nodes": [...] }。正文只说明新增部分的作用。
   • 最后一个逐步扩展视图之后，使用 { "kind": "flow", "flow": "<id>" } 展示流程，用 1 到 2 个步骤按顺序讲解，并聚焦 messages。出错的地方要用客观的措辞放在其中一个步骤里；聚焦紧邻故障之前的消息，因为成功路径的流程本身没有故障消息。不要为它编造消息。
   • 整体视图对应两个步骤：一个介绍它新增的节点，并设置焦点；另一个是收尾步骤。收尾步骤展示整体视图，不设置焦点，标题再次使用答案句，正文补充一个读者现在能理解的数字：“收到 1 封邮件，发出 2,000 封邮件，向 Postmark 发送 1 个请求。”

6. 验证、渲染、推送。

   npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json
   npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light
   npx @coldtea/pr-lens-cli@latest canvas push .pr-lens/<drawing>/drawn.graph.json
   

   render 会输出它绘制到的文件夹，该文件夹以文档标题命名。推送该文件夹中的 drawn.graph.json。如果 .pr-lens/ 中有多张图，直接运行 canvas push 会停止。

   修复所有错误并重新验证。不要删除错误所指的元素；应修复引用。canvas push 会输出视图链接 https://prlens.dev/c/{id} 和嵌入链接。视图链接就是交付内容。

7. 打开后停止。 如果此运行环境可以打开浏览器，就打开视图链接。分两行回复答案句和链接。除此之外什么都不要写：不要列步骤，不要列文件，也不要总结做了什么。如果提问者还需要报告或比较，那是第二个请求，应在完成这次请求后再回答。 关于画布的后续问题会在画布上回答：先运行一次 npx @coldtea/pr-lens-cli@latest canvas open .pr-lens/<drawing>/drawn.graph.json，然后使用 --drawing 和相同路径运行 canvas answer，就像 pr-lens 技能中的“在打开的画布旁回答”所说的那样。这里也保持使用相同的普通词语。

用词

只用普通词语。不要用：leverages、orchestrates、pipeline、abstraction、handler、wrapper、layer、utility、invoke、instantiate。说清楚它的作用。每个真实名称只出现一次，放在副标题中，让好奇的读者能找到代码。

当读者不是工程师，且某个日常事物能与整个过程一一对应时，可以打比方。比喻放在正文中，不要放在标签中，并在最后一步去掉比喻，让读者回到真实事物。

这不是什么

这不是代码审查、文件列表、教程或架构文档。没有用于描述 bug、风险或观点的字段，也不能有任何段落。并且绝不会一次性展示一张完整的大图。