eli5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

eli5

Explain like I'm someone who knows nothing about this code: one sentence, then one part at a time, until the whole picture is on screen and the reader already knows every part of it.

A reader who knows nothing cannot take in a diagram. They can take in two boxes and an arrow. So the canvas starts with two boxes and grows. The whole picture is the last thing they see, not the first, and by then it holds nothing new.

You write one graph document. Its views are the growing pictures, its walkthrough plays them in order, and PR Lens draws them. The reader opens a link and presses play. There is no page, no list, no paragraph.

面向完全不了解代码的受众进行解释：先给出一句话说明，再逐步拆解每个部分，直到最终呈现完整图景时，读者已经理解了所有组成部分。

完全不了解相关内容的读者无法一下子理解一张完整的示意图。他们能看懂两个方框加一个箭头的简单结构。因此画布从两个方框开始，逐步扩展内容。完整图景是最后才展示的内容，而非一开始就呈现，到展示完整图时，里面已经没有读者陌生的内容了。

你需要编写一份graph文档。它的视图是逐步扩展的图景，引导式讲解（walkthrough）会按顺序播放这些视图，由PR Lens负责绘制。读者打开链接后点击播放即可。整个过程没有传统页面、没有列表、也没有大段文字。

What you need

前置要求

The PR Lens skill, installed beside this one. If

pr-lens/SKILL.md

is not there:

npx skills add coldteadotai/pr-lens --skill pr-lens

. Read its SKILL.md and

references/graph-document.md

before your first document. Its rules hold here except where this page marks an Override.

需要安装PR Lens技能，与本技能放在同一目录下。如果不存在

pr-lens/SKILL.md

文件，执行：

npx skills add coldteadotai/pr-lens --skill pr-lens

。在编写第一份文档前，请先阅读PR Lens的SKILL.md和

references/graph-document.md

文档。除本页面标注**Override（覆盖规则）**的地方外，PR Lens的规则均适用。

Operating manual

操作手册

Write the answer first. Read the code until you can say what it does for a person, in under 48 characters, because the sentence is also a walkthrough heading and a heading stops at 48. Count them.
- For a feature or a command: "When you ___, this code ___." Example: "When you hit send, it emails everyone."
- For a whole codebase: what the product is for. Example: "BestRegards sends newsletters for you." The sentence is about the product, not one path through it. Override, summary. The sentence is also the document
```
summary
```
  . The reference wants a paragraph about a change; eli5 wants this sentence.
Cut to the path. For a feature, trace the one path input takes to output. For a whole codebase, first list the 3 to 5 things a person does with the product, then trace the path of the main one: the thing the product is named after or sold on, or the one with the most code on it. The parts on that path are the diagram: 4 to 10 nodes, 2 to 5 lanes. Helpers, config, types and tests stay out. When two entry points converge on the same code, draw the point where they meet and name both in its body; do not drop one.
Write
.pr-lens/graph.json
. Follow
```
references/graph-document.md
```
, plus these rules:
- Override, provenance. The schema requires it. Take the remote from
```
git remote get-url origin
```
  .
```
https://github.com/acme/mail.git
```
  and
```
git@github.com:acme/mail.git
```
  both become
```
{ "owner": "acme", "name": "mail", "host": "github.com" }
```
  . Put the current
```
HEAD
```
  sha in both
```
base.sha
```
  and
```
head.sha
```
  . The parser rule about "a patch whose two commits are the same" is about
```
patch
```
  , not
```
provenance
```
  , so this validates.
- Lanes are places the reader can picture, left to right in the order the path runs: "your browser", "the website", "the mail company", "your reader". Not the folder tree. Set
```
order
```
  . A database or queue the path touches more than once is not a place on the path; put it in the lane of the code that owns it.
- The first node is the reader, or the thing the reader touches: "You write the email". The reader must find themself on the first picture. Use
```
kind: "external"
```
  for a person; the schema has no person kind.
- Node
```
label
```
  is what the part does, in three words or fewer. The real name goes in
```
subtitle
```
  , the file in
```
files
```
  .
- Override, deltas. Every
```
delta
```
  is
```
unchanged
```
  unless the thing is a pull request.
- No
```
stats
```
  . There is no diff to count.
- Exactly one edge with
```
emphasis: "hero"
```
  : the hand-off the answer sentence is about, the one edge that, if removed, would make the sentence false. Set
```
animated: true
```
  on every edge along the path.
- One flow when the path is a sequence, which it nearly always is. Flow step labels are what is passed, in plain words.
Write the growing views. Override, views. This replaces the C4 decision tree in the pr-lens skill. eli5 views are the same picture growing, not a drill-down.
- View 1 holds 2 nodes: the reader and the first part they touch, with the edge between them. Scope:
```
{ "kind": "selection", "nodes": [...], "edges": [...] }
```
  .
- Each next view holds everything the last one held plus 1 to 3 new nodes along the path, and the edges among them. Never more than 3 new parts in one view. The one exception is the codebase view below.
- The last architecture view is the whole thing:
```
"scope": { "kind": "all" }
```
  . It is the only one with
```
"defaultOpen": true
```
  . The growing view before it must still be missing at least 1 node, so the two are not the same picture; the pr-lens rule against two views with the same nodes holds. Override, views. Growing views share most of their nodes on purpose; only the last two must differ.
- For a whole codebase, view 2 is the reader plus the 3 to 5 things the product does, as nodes in the product's lane. This view may add up to 5 parts; they are a list, not a path. Views 3 onward grow the main path. The other things stay on the picture so the reader knows they exist.
- One data-flow root scoped to the flow:
```
"scope": { "kind": "selection", "flows": ["<flow id>"] }
```
  . It is needed or the flow is never drawn.
- All views are roots. Do not nest.
- Name views by what is on them:
```
you-and-the-editor
```
  ,
```
plus-the-queue
```
  ,
```
the-whole-thing
```
  .
Write the walkthrough. One step per growing view, then the flow, then the whole. Count first: growing views plus 1 to 2 flow steps plus 1 closing step, at most 9. With 10 nodes that means 3 to 5 growing views, so grow by 2 or 3 at a time, not 1.
- Override, headings. A heading says what happens, not what changed: "The website packs your email". No step numbers; the canvas counts.
- ```
body
```
  : one line, up to 140 characters, that a smart twelve-year-old reads once. What happens, then what it means. Numbers as digits.
- Step 1 stages view 1, focus left out, heading is the answer sentence, body introduces the two parts: "This is you, and the screen you write in. Everything starts here."
- Each next step stages the next growing view and focuses only the new nodes with
```
{ "kind": "selection", "nodes": [...] }
```
  . The body says what the new part does, and only that.
- After the last growing view, stage the flow with
```
{ "kind": "flow", "flow": "<id>" }
```
  for 1 to 2 steps that follow the sequence, focusing
```
messages
```
  . Where things go wrong is one of these steps, in matter-of-fact words; focus the message that comes right before the failure, since a happy-path flow has no failure message of its own. Do not invent a message for it.
- The whole-thing view carries two steps: one that introduces the nodes it adds, with focus, and the closing step. The closing step stages the whole-thing view, focus left out, heading is the answer sentence again, body adds one number the reader now understands: "1 email in, 2,000 emails out, 1 request to Postmark."

Validate, render, push.

bash

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

Fix every failure and validate again. Do not delete the element a failure names; fix the reference.

canvas push

prints the view link,

https://prlens.dev/c/{id}

, and an embed link. The view link is the deliverable.

Open it and stop. If this harness can open a browser, open the view link. Reply with the answer sentence and the link, on two lines. Nothing else: no step list, no file list, no summary of what you did. If the person who asked wants a report or a comparison, that is a second request, answered after this one.

先写核心说明句。通读代码，直到你能用不超过48个字符的一句话说明代码对用户的作用，因为这句话同时也是引导式讲解的标题，标题长度限制为48字符。请务必计数确认。
- 对于功能或命令：使用「当你___时，这段代码会___」的句式。例如：「当你点击发送时，它会给所有人发邮件。」
- 对于完整代码库：说明产品的用途。例如：「BestRegards帮你发送新闻通讯。」这句话是关于产品整体的，而非其中的某条执行路径。 覆盖规则：摘要（summary）。这句话同时也是文档的
```
summary
```
  字段内容。参考文档要求用一段文字描述变更，但eli5模式只需要这句话。
梳理核心路径。对于功能，梳理出从输入到输出的一条核心路径。对于完整代码库，先列出用户使用产品的3-5个核心操作，然后梳理最核心操作的执行路径：也就是产品名称对应的功能、主打功能，或是代码量最多的功能。这条路径上的组成部分就是示意图的内容：4-10个节点，2-5条泳道（lanes）。辅助工具、配置、类型定义和测试代码不需要包含在内。如果两个入口点最终执行同一段代码，要画出它们的交汇点，并在节点内容中注明两个入口，不要省略任何一个。
编写
.pr-lens/graph.json
文件。遵循
```
references/graph-document.md
```
的规范，同时遵守以下规则：
- 覆盖规则：来源（provenance）。schema要求必须填写该字段。从
```
git remote get-url origin
```
  命令获取远程仓库地址。
```
https://github.com/acme/mail.git
```
  和
```
git@github.com:acme/mail.git
```
  格式的地址都要转换为
```
{ "owner": "acme", "name": "mail", "host": "github.com" }
```
  的格式。将当前
```
HEAD
```
  的sha值同时填入
```
base.sha
```
  和
```
head.sha
```
  。解析器中关于「两个提交相同的补丁」的规则是针对
```
patch
```
  字段的，而非
```
provenance
```
  ，因此这样填写是合法的。
- 泳道是读者可以具象化理解的场景，按照路径执行顺序从左到右排列，例如：「你的浏览器」、「网站」、「邮件服务商」、「你的读者」。不要用文件夹结构作为泳道。请设置
```
order
```
  字段。如果路径多次访问同一个数据库或队列，它不属于路径上的一个独立场景，应该将其归属于对应代码所在的泳道。
- 第一个节点是读者，或是读者直接接触的对象：比如「你编写邮件」。读者必须能在第一张图里找到自己的位置。表示人物的节点使用
```
kind: "external"
```
  ，因为schema中没有专门的人物类型。
- 节点的
```
label
```
  字段用不超过三个词说明该部分的作用。真实名称放在
```
subtitle
```
  字段，对应文件路径放在
```
files
```
  字段。
- 覆盖规则：差异（deltas）。除非解释的对象是pull request，否则所有
```
delta
```
  字段都设为
```
unchanged
```
  。
- 不要填写
```
stats
```
  字段。因为没有差异需要统计。
- 必须恰好有一条边设置
```
emphasis: "hero"
```
  ：也就是核心说明句所描述的关键交互环节，这条边如果被移除，核心说明句就不成立了。路径上的所有边都要设置
```
animated: true
```
  。
- 如果路径是顺序执行的（绝大多数情况都是如此），则定义一个流程（flow）。流程步骤的标签用平实的语言说明传递的内容。
编写逐步扩展的视图。覆盖规则：视图（views）。本条规则替代pr-lens技能中的C4决策树。eli5模式的视图是同一张图的逐步扩展，而非逐层下钻。
- 视图1包含2个节点：读者和他们接触的第一个组件，以及两者之间的边。范围（scope）设置为：
```
{ "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
```
  （完整图景）。
编写引导式讲解（walkthrough）。每个扩展视图对应一个步骤，然后是流程步骤，最后是完整图景步骤。先计算总步骤数：扩展视图数 + 1-2个流程步骤 + 1个收尾步骤，最多不超过9步。如果有10个节点，意味着需要3-5个扩展视图，因此每次新增2-3个部分，而不是1个。
- 覆盖规则：标题（headings）。标题要描述发生了什么，而非变化了什么：例如「网站打包你的邮件」。不要添加步骤编号，画布会自动计数。
- ```
body
```
  字段：一行文字，不超过140字符，要让聪明的12岁孩子读一遍就能懂。先说明发生了什么，再说明其意义。数字用阿拉伯数字。
- 第1步展示视图1，不设置聚焦（focus），标题为核心说明句，正文介绍两个组成部分：「这是你，还有你用来编写内容的屏幕。一切从这里开始。」
- 后续每一步展示下一个扩展视图，并用
```
{ "kind": "selection", "nodes": [...] }
```
  只聚焦新增的节点。正文只说明新增部分的作用，不要多讲。
- 在最后一个扩展视图之后，用
```
{ "kind": "flow", "flow": "<id>" }
```
  展示流程，设置1-2个跟随流程顺序的步骤，聚焦
```
messages
```
  。出错场景可以放在其中一个步骤里，用平实的语言描述；聚焦失败前的最后一条消息，因为正常路径的流程本身没有失败消息。不要凭空编造消息内容。
- 完整图景视图对应两个步骤：一个步骤介绍新增的节点（带聚焦），另一个是收尾步骤。收尾步骤展示完整图景视图，不设置聚焦，标题再次使用核心说明句，正文补充一个读者此时已经能理解的数字：「1封邮件输入，2000封邮件输出，向Postmark发送1次请求。」

验证、渲染、推送。

bash

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

修复所有报错后再次验证。不要删除报错提到的元素，而是修正对应的引用。

canvas push

命令会输出视图链接

https://prlens.dev/c/{id}

和嵌入链接。视图链接就是最终交付物。

打开链接，结束操作。如果当前运行环境可以打开浏览器，就打开视图链接。回复时只需要两行：核心说明句和链接。不要添加其他内容：不要步骤列表，不要文件列表，也不要总结你做了什么。如果提问的人需要报告或对比，那是另一个请求，等本次完成后再处理。

Words

用词规范

Plain words only. Not: leverages, orchestrates, pipeline, abstraction, handler, wrapper, layer, utility, invoke, instantiate. Say what it does. Real names appear once each, in subtitles, so a curious reader can find the code.

An analogy is allowed when the reader is not an engineer and one everyday thing matches the path beat for beat. Use it in bodies, never in labels, and drop it in the last step so the reader leaves with the real thing.

只使用平实的语言。避免使用以下词汇：leverages、orchestrates、pipeline、abstraction、handler、wrapper、layer、utility、invoke、instantiate。直接说明它的作用。真实名称只在副标题里出现一次，方便好奇的读者找到对应代码。

如果读者不是工程师，而且能找到一个日常事物完全对应路径的每一步，可以使用类比。类比只能用在正文中，绝对不能用在标签里，并且在最后一步要去掉类比，让读者最终记住真实的概念。

What this is not

不属于本工具的用途

Not a review, not a file list, not a tutorial, not an architecture document. There is no field for a bug, a risk or an opinion, and there is no paragraph anywhere. And it is never one big diagram shown all at once.

它不是代码评审，不是文件列表，不是教程，也不是架构文档。没有地方填写bug、风险或主观意见，全程没有大段文字。并且它绝对不是一开始就展示一张完整的大示意图。