{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Pr Lens

把代码变更画成动画架构/数据流 SVG。

Skill 元数据


来源	可选——使用 `hermes skills install official/software-development/pr-lens` 安装
路径	`optional-skills/software-development/pr-lens`
版本	`1.0.0`
作者	Coldtea AI (adapted by Nous Research)
许可证	MIT
平台	linux, macos
标签	`diagrams`, `pull-requests`, `code-review`, `svg`

参考：完整 SKILL.md

INFO

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。

PR Lens Skill

PR Lens 把代码画成视觉丰富的动画图：diff、架构、数据流。你把 diff 或代码库描述成一个 JSON 文档（泳道、节点、边、有序流），CLI 把它渲染成动画 SVG。它没有 findings 视角——PR Lens 是理解层，不是 review bot。没有放 bug、风险或安全备注的字段，编造这些的文档会被拒绝。

使用时机

被要求给代码变更或系统画图、可视化或解释。
一个 pull request 应带一张架构或数据流图。
关键词：PR Lens、diagram、architecture、data flow、visualise、pull request。

前提条件

带 npx 的 Node.js（CLI 通过 npx @coldtea/pr-lens-cli@latest 运行；无安装步骤）。
gh（GitHub CLI）——可选，仅用于把图附到 PR。
可选的 canvas 发布会调用第三方服务 prlens.dev（见第 4b 步）。

运行方式

所有命令用 terminal 工具从仓库根目录运行。

读 diff。 表示代码变更时：git diff --find-renames <base>...<head>。base 是 merge base，不是 base 分支的 tip。不表达 diff 时，读要可视化的代码。
写文档到 .pr-lens/graph.json，遵循 references/graph-document.md。references/example.graph.json 是一个带三条泳道、全部四种 delta 状态、一条 hero 边、一个七步流、一个嵌套钻取树和一个六步走查的合法参考。写第一份文档前先读它——比读 reference 快。
校验并修复。
```
npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json
```
修掉每个失败再跑。不要渲染非法文档；不要通过删掉它点名的元素来"绕过"失败。
渲染。
```
npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light
```
默认渲染浅色，除非用户要别的主题。SVG、manifest 和 drawn.graph.json 落到 .pr-lens/，CLI 会把它加进仓库的 .gitignore。不要提交任何这些——这些文件按需从 diff 重建。每个 SVG 以其视图、主题和内容哈希命名；manifest.json 按 lens 和视图列出它们。

4b. Canvas 推送——可选，需用户选择开启。 仅当用户明确要一个可分享链接时。这把 .pr-lens/drawn.graph.json 发布到第三方服务 prlens.dev：

npx @coldtea/pr-lens-cli@latest canvas push

它打印三个链接。把视图链接（https://prlens.dev/c/{id}）给用户：全屏图，一页上所有视图，免登录。编辑链接（以 #w=… 结尾）让持有者覆盖 canvas——它是机密：除非被问到，否则别放进回复，永远别贴到任何公开处。embed 链接把顶视图作为 SVG 提供给 README。再推同一文件会更新同一个 canvas，所以"改那个节点名"就是：编辑、校验、渲染、推送——链接不变。如果推送失败，照实说，告诉用户本地 SVG 在哪、哪个是顶视图。

有 PR 时附到 PR。 上游文档写的是 gh pr create/edit/comment --attach <path>，但 --attach 是 GitHub CLI 2.99 才来的——先查 gh --version（例如 gh 2.97 没有它）。gh ≥ 2.99 时：用 Markdown 图片写正文 ![alt](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/software-development/pr-lens/.pr-lens/<view>.svg)（HTML <img> 会按你写的保留、文件改附在底部；alt 文本是看不到图的读者拿到的一行说明），然后对每张引用的图重复 --attach <path>：
```
gh pr create --title "…" --body-file .pr-lens/body.md --attach .pr-lens/overview-light-<hash>.svg
```
没有 --attach 时，用免提交路径：
- 把 SVG 上传到 gist：gh gist create .pr-lens/<view>.svg，然后在 PR 正文/评论里引用 gist raw URL，或
- 通过 canvas 链接发布（第 4b 步，经用户同意）并链到视图 URL，或
- 在 PR 正文里注明本地 .pr-lens/ 路径，让 review 者能重建。
一旦发布到某处持久位置，让 CLI 组织评论 markdown：
```
npx @coldtea/pr-lens-cli@latest comment \
  --graph .pr-lens/drawn.graph.json \
  --manifest .pr-lens/manifest.json \
  --asset-base-url <你发布 SVG 的位置>
```
--graph 接 drawn.graph.json，不是你写的文档——CLI 会拒绝一个其 manifest 没描述的文档。漏掉 --asset-base-url，markdown 就指向没人能取到的本地路径。markdown 打到 stdout；发不发是你的事。

附上 review 者需要的视图，其余留在 .pr-lens/：先顶架构视图，如果变更有值得跟的序列再附一张数据流。两张图通常胜过四张。
可选自动化： npx @coldtea/pr-lens-cli@latest analyze --base <ref> 通过你自己 key 的提供商（Gemini、OpenAI 或任何 /chat/completions 端点）做第 1–2 步。这是这里唯一需要 key 的路径；通常你自己写文档。

什么让一份文档值得读

包含没变化的东西。 变更触及的未改动邻居是上下文；标 delta: "unchanged"。
泳道是读者的心智模型（一个运行时、一层、一条边界），不是文件夹树。
一条 hero 边，最多两条：变更真正关乎的那条连接。
仅当有值得动画化的序列时才加流。 一条好流胜过三条单薄的。
附文件引用：它们变成 review 者点击的永久链接。
架构视图是 C4 启发的决策树：系统上下文 → 容器 → 组件，每个子节点实质更窄。跳过空或重复的层级；把数据流视图作为独立根；在最高有用的架构视图上设 defaultOpen: true。
走查（2–12 步，目标 3–7）：对任何非平凡的东西写一个。每步 = 一个变更（增/删/移），头条变更在前，概览在后。标题 ≤48 字符、由变更词构成；正文 ≤140 字符、讲行为，必填。写给聪明的十二岁孩子；不要"leverages"/"orchestrates"。让连续步骤停在同一阶段。走查字段需要 CLI ≥ 0.4.0（契约 0.1.1）。
修错图： 绝不编辑生成的文档——把修正写进 .github/pr-lens.yml（见 references/config.md），然后校验：npx @coldtea/pr-lens-cli@latest validate .github/pr-lens.yml。优先路径 glob 而非 id: 匹配。

快速参考

命令	用途
`npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json`	校验文档（也校验 `.github/pr-lens.yml`）
`npx @coldtea/pr-lens-cli@latest render .pr-lens/graph.json --theme light`	把 SVG + manifest 渲染进 `.pr-lens/`
`npx @coldtea/pr-lens-cli@latest canvas push`	可选：发布到 prlens.dev（仅 opt-in）
`npx @coldtea/pr-lens-cli@latest comment --graph … --manifest … --asset-base-url …`	把 PR 评论 markdown 打到 stdout
`npx @coldtea/pr-lens-cli@latest analyze --base <ref>`	通过 LLM 提供商自动写文档（需 API key）

校验失败码：

码	你做了什么
`BROKEN_REFERENCE`	某条边、流步骤、视图或走查步骤点名了一个你从未声明的 id
`INVALID_DOCUMENT`	编造的字段；schema 是严格的，未知键会被拒
`DUPLICATE_ID`	两个节点、边或视图共享一个 id
`UNSUPPORTED_SCHEMA_VERSION`	`schemaVersion` 不是安装的契约版本

常见陷阱

六条规则只在解析器层、不在 JSON Schema 里（引用完整性、倒置行范围、自相矛盾的 self 端点、相同 patch commit、manifest 视图过多、流步骤聚焦错阶段）——始终跑 validate，光靠结构化输出不够。
不要提交 .pr-lens/ 里的任何东西；它由 CLI 重新生成并 gitignore。
--attach gh 标志需要 gh ≥ 2.99；旧版 gh 静默没有——写正文前先查。
canvas 编辑链接（#w=…）是写入凭据——不要不请自来地分享或公开粘贴。
存储的图从不带走查；走查讲一个变更的故事。
pr-lens render 报 .github/pr-lens.yml 里没匹配到的修正——那是值得修的漂移，不是错误。

验证

冒烟测试（2026-09-12 通过 npx 用 @coldtea/pr-lens-cli 在 Linux node 上实测验证）：

cp references/example.graph.json ~/.hermes/cache/scratch/prlens-smoke/ && cd ~/.hermes/cache/scratch/prlens-smoke
npx -y @coldtea/pr-lens-cli@latest validate example.graph.json
# ✓ example.graph.json — graph document · 3 lanes, 10 nodes, 13 edges, 1 flow · 6 walkthrough steps
npx -y @coldtea/pr-lens-cli@latest render example.graph.json --theme light
# ✓ .pr-lens/manifest.json — 4 SVGs across 4 diagrams

两者都期望退出码 0，.pr-lens/ 里有四个 *-light-<hash>.svg 文件加 manifest.json 和 drawn.graph.json。