SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pr-lens

pr-lens

编程与开发

查看项目

更新于 10-16 18:08

技能介绍

PR Lens 是一个用于把代码变更和系统结构绘制成动画架构图、数据流图的技能。它的定位是理解层，而不是代码审查机器人：文档中没有用于记录缺陷、风险或安全提示的字段，若文档自行发明这类字段会被拒绝。

用途 当你被要求用图解释或可视化一次代码变更或一个系统时使用；也适用于希望为某个 pull request 附带架构图或数据流图的场景。关键词包括 PR Lens、diagram、architecture、data flow、visualise、pull request。

主要能力 PR Lens 将 diff、架构和数据流绘制为视觉丰富的动画图。你用一个 JSON 文档描述泳道（lanes）、节点（nodes）、边（edges）和有序流程（flows），CLI 将其渲染为动画 SVG。文档遵循 references/graph-document.md 的规范，references/example.graph.json 是一个有效参考，包含三条泳道、全部四种 delta 状态、一条 hero 边、一个七步流程、一棵嵌套下钻树和一个六步 walkthrough。

使用方式 所有命令在仓库根目录通过终端工具运行。

  1. 读取 diff：表示代码变更时使用 git diff --find-renames <base>...<head>，其中 base 是合并基（merge base），不是基分支的顶端。若不表示 diff，则阅读要可视化的代码。
  2. 将文档写入 .pr-lens/graph.json。
  3. 校验并修复：npx @coldtea/pr-lens-cli@latest validate .pr-lens/graph.json。修复每一处失败并重新运行；不要渲染无效文档，也不要通过删除报错所指元素来绕过失败。
  4. 渲染：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 和 view 列出它们。 4b. 画布推送（可选、需明确同意）：仅当用户明确要求可分享链接时，将 .pr-lens/drawn.graph.json 发布到第三方服务 prlens.dev：npx @coldtea/pr-lens-cli@latest canvas push。它会打印三个链接。给用户视图链接（https://prlens.dev/c/{id}）：全屏图、所有视图在一页、无需登录。编辑链接（以 #w= 结尾）允许持有者覆盖画布，属于机密：除非被要求，否则不要放进回复，也绝不要粘贴到任何公开位置。嵌入链接以 SVG 形式提供顶部视图，用于 README。再次推送同一文件会更新同一画布，因此“重命名那个节点”的流程是：编辑、校验、渲染、推送，链接保持不变。若推送失败，说明失败并告知用户本地 SVG 的位置以及哪个是顶部视图。
  5. 附加到 PR（当存在 PR 时）：上游文档记录了 gh pr create/edit/comment --attach <path>，但 --attach 在 GitHub CLI 2.99 才出现，先检查 gh --version（例如 gh 2.97 没有该功能）。使用 gh ≥ 2.99 时：用 Markdown 图片 写正文（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 原始 URL；或经用户同意通过画布链接（步骤 4b）发布并链接视图 URL；或在 PR 正文中注明本地 .pr-lens/ 路径，让审查者自行重建。发布到持久位置后，可让 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，发布由你自行处理。只附加审查者需要的视图，其余留在 .pr-lens/：先顶部架构视图，若变更包含值得跟随的序列再加数据流。两张图通常胜过四张。 可选自动化：npx @coldtea/pr-lens-cli@latest analyze --base <ref> 通过向提供方（Gemini、OpenAI 或任意 /chat/completions 端点）请求并使用你自己的密钥来完成步骤 1–2。这是唯一需要密钥的路径；通常你自行撰写文档。

让文档值得阅读的要点 包含未变更的内容：变更触及的未变更邻居是上下文，将其标记为 delta: "unchanged"。泳道是读者的心智模型（运行时、层级、边界），不是文件夹树。一条 hero 边，最多两条：即变更真正关乎的连接。仅当存在值得动画化的序列时才添加流程，一条好流程胜过三条单薄流程。附加文件引用，它们会成为审查者点击的永久链接。架构视图是受 C4 启发的决策树：系统上下文 → 容器 → 组件，每个子级明显更窄；跳过空或重复的层级；数据流视图保持为独立根；在最高层有用架构视图上设置 defaultOpen: true。Walkthrough（2–12 步，目标 3–7 步）：任何非平凡内容都写一个。每步 = 一个变更（新增/删除/移动），标题变更在前，概览最后。标题 ≤48 字符，由变更词构成；正文 ≤140 字符，描述行为，必填。写给聪明的十二岁孩子看，不要用 "leverages"/"orchestrates"。连续步骤保持在同一阶段。walkthrough 字段需要 CLI ≥ 0.4.0（contract 0.1.1）。

修正错误的地图 绝不要编辑生成的文档——把修正写入 .github/pr-lens.yml（见 references/config.md），然后校验它：npx @coldtea/pr-lens-cli@latest validate .github/pr-lens.yml。优先使用路径 glob 而非 id: 匹配。

快速参考

  • validate .pr-lens/graph.json：校验文档（也校验 .github/pr-lens.yml）
  • render .pr-lens/graph.json --theme light：渲染 SVG + manifest 到 .pr-lens/
  • canvas push：可选，发布到 prlens.dev（仅限主动选择）
  • comment --graph … --manifest … --asset-base-url …：生成 PR 评论 Markdown 到 stdout
  • analyze --base <ref>：通过 LLM 提供方自动撰写文档（需要 API 密钥）

校验器失败代码

  • BROKEN_REFERENCE：边、流程步骤、视图或 walkthrough 步骤引用了你从未声明的 id
  • INVALID_DOCUMENT：发明了字段；schema 严格，未知键会被拒绝
  • DUPLICATE_ID：两个节点、边或视图共享同一 id
  • UNSUPPORTED_SCHEMA_VERSION：schemaVersion 不是已安装的 contract 版本

限制与注意事项 有六条规则仅由解析器检查，不在 JSON Schema 中（引用完整性、反转的行范围、自相矛盾的自身端点、相同的补丁提交、manifest 视图过多、流程步骤聚焦于错误阶段），因此务必运行 validate，仅靠结构化输出不够。不要提交 .pr-lens/ 中的任何内容，它会被重新生成并由 CLI 加入 gitignore。--attach gh 标志需要 gh ≥ 2.99，旧版 gh 会静默缺失该功能，写正文前先检查。画布编辑链接（#w=…）是写凭证，绝不要未经提示分享或公开粘贴。存储的地图从不携带 walkthrough；walkthrough 讲述一次变更的故事。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。

本技能改编自 coldteadotai/pr-lens（packages/agent-skill，固定于 0993b4d），MIT 许可证，Copyright (c) 2026 Coldtea AI。详见 LICENSE.txt。