Back to Details

pr-report

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Report Skill

PR 报告技能

Produce a maintainer-grade review of a PR, branch, or large contribution.
Default posture:
  • understand the change before judging it
  • explain the system as built, not just the diff
  • separate architectural problems from product-scope objections
  • make a concrete recommendation, not a vague impression
生成符合维护者标准的PR、分支或大型贡献审查报告。
默认准则：
  • 在评判之前先理解变更内容
  • 讲解已构建完成的系统，而非仅局限于代码差异（diff）
  • 将架构问题与产品范围异议区分开来
  • 给出具体的建议，而非模糊的印象

When to Use

使用场景

Use this skill when the user asks for things like:
  • "review this PR deeply"
  • "explain this contribution to me"
  • "make me a report or webpage for this PR"
  • "compare this design to similar systems"
  • "should I merge this?"
当用户提出以下需求时，可使用该技能：
  • "深度审查这个PR"
  • "给我讲解这个贡献内容"
  • "为这个PR生成一份报告或网页"
  • "将这个设计与同类系统进行对比"
  • "我应该合并这个PR吗？"

Outputs

输出产物

Common outputs:
  • standalone HTML report in 
    tmp/reports/...
  • Markdown report in 
    report/
    or another requested folder
  • short maintainer summary in chat
If the user asks for a webpage, build a polished standalone HTML artifact with clear sections and readable visual hierarchy.
Resources bundled with this skill:
  • references/style-guide.md
    for visual direction and report presentation rules
  • assets/html-report-starter.html
    for a reusable standalone HTML/CSS starter
常见输出：
  • 独立HTML报告，存放于 
    tmp/reports/...
  • Markdown报告，存放于 
    report/
    或其他指定文件夹
  • 聊天窗口中的简短维护者摘要
如果用户要求生成网页，需构建一份精美的独立HTML产物，包含清晰的章节结构和易读的视觉层级。
该技能附带的资源：
  • references/style-guide.md
    ：提供视觉方向和报告呈现规则
  • assets/html-report-starter.html
    ：可复用的独立HTML/CSS模板

Workflow

工作流程

1. Acquire and frame the target

1. 获取并明确目标

Work from local code when possible, not just the GitHub PR page.
Gather:
  • target branch or worktree
  • diff size and changed subsystems
  • relevant repo docs, specs, and invariants
  • contributor intent if it is documented in PR text or design docs
Start by answering: what is this change trying to become?
尽可能基于本地代码开展工作，而非仅依赖GitHub PR页面。
收集以下信息：
  • 目标分支或工作区
  • 代码差异大小及变更的子系统
  • 相关的仓库文档、规范和不变量
  • PR文本或设计文档中记录的贡献者意图
首先明确：这项变更的最终目标是什么？

2. Build a mental model of the system

2. 构建系统的心智模型

Do not stop at file-by-file notes. Reconstruct the design:
  • what new runtime or contract exists
  • which layers changed: db, shared types, server, UI, CLI, docs
  • lifecycle: install, startup, execution, UI, failure, disablement
  • trust boundary: what code runs where, under what authority
For large contributions, include a tutorial-style section that teaches the system from first principles.
不要仅停留在逐文件的注释层面，需重构整体设计：
  • 新增了哪些运行时或契约
  • 哪些层级发生了变更：db、共享类型、服务端、UI、CLI、文档
  • 生命周期：安装、启动、执行、UI交互、故障处理、禁用流程
  • 信任边界：代码在何处运行、拥有何种权限
对于大型贡献内容，需包含教程风格的章节，从基础原理层面讲解系统。

3. Review like a maintainer

3. 以维护者视角审查

Findings come first. Order by severity.
Prioritize:
  • behavioral regressions
  • trust or security gaps
  • misleading abstractions
  • lifecycle and operational risks
  • coupling that will be hard to unwind
  • missing tests or unverifiable claims
Always cite concrete file references when possible.
先列出发现的问题，按严重程度排序。
优先关注：
  • 行为回归问题
  • 信任或安全漏洞
  • 具有误导性的抽象设计
  • 生命周期和运维风险
  • 难以解除的耦合关系
  • 缺失的测试或无法验证的声明
尽可能引用具体的文件路径作为依据。

4. Distinguish the objection type

4. 明确异议类型

Be explicit about whether a concern is:
  • product direction
  • architecture
  • implementation quality
  • rollout strategy
  • documentation honesty
Do not hide an architectural objection inside a scope objection.
需明确说明关注点属于以下哪一类：
  • 产品方向
  • 架构设计
  • 实现质量
  • 发布策略
  • 文档真实性
不要将架构异议隐藏在范围异议中。

5. Compare to external precedents when needed

5. 必要时与外部先例对比

If the contribution introduces a framework or platform concept, compare it to similar open-source systems.
When comparing:
  • prefer official docs or source
  • focus on extension boundaries, context passing, trust model, and UI ownership
  • extract lessons, not just similarities
Good comparison questions:
  • Who owns lifecycle?
  • Who owns UI composition?
  • Is context explicit or ambient?
  • Are plugins trusted code or sandboxed code?
  • Are extension points named and typed?
如果贡献内容引入了框架或平台概念，需与同类开源系统进行对比。
对比时需注意：
  • 优先参考官方文档或源码
  • 聚焦于扩展边界、上下文传递、信任模型和UI归属
  • 提炼经验教训，而非仅罗列相似点
可参考的对比问题：
  • 谁掌控生命周期？
  • 谁负责UI组合？
  • 上下文是显式传递还是隐式存在？
  • 插件是可信代码还是沙箱代码？
  • 扩展点是否有明确的命名和类型定义？

6. Make the recommendation actionable

6. 给出可执行的建议

Do not stop at "merge" or "do not merge."
Choose one:
  • merge as-is
  • merge after specific redesign
  • salvage specific pieces
  • keep as design research
If rejecting or narrowing, say what should be kept.
Useful recommendation buckets:
  • keep the protocol/type model
  • redesign the UI boundary
  • narrow the initial surface area
  • defer third-party execution
  • ship a host-owned extension-point model first
不要仅停留在“合并”或“不合并”的层面。
选择以下其中一项：
  • 直接合并
  • 完成特定重构后合并
  • 保留特定部分
  • 作为设计研究留存
如果拒绝或缩小范围，需说明应保留哪些内容。
实用的建议方向：
  • 保留协议/类型模型
  • 重构UI边界
  • 缩小初始覆盖范围
  • 延迟第三方执行逻辑
  • 先发布宿主掌控的扩展点模型

7. Build the artifact

7. 构建报告产物

Suggested report structure:
  1. Executive summary
  2. What the PR actually adds
  3. Tutorial: how the system works
  4. Strengths
  5. Main findings
  6. Comparisons
  7. Recommendation
For HTML reports:
  • use intentional typography and color
  • make navigation easy for long reports
  • favor strong section headings and small reference labels
  • avoid generic dashboard styling
Before building from scratch, read 
references/style-guide.md
. If a fast polished starter is helpful, begin from 
assets/html-report-starter.html
and replace the placeholder content with the actual report.
建议的报告结构：
  1. 执行摘要
  2. PR实际新增内容
  3. 教程：系统工作原理
  4. 优势
  5. 主要发现
  6. 对比分析
  7. 建议
对于HTML报告：
  • 使用有目的性的排版和配色
  • 长报告需具备便捷的导航功能
  • 突出章节标题，使用小型参考标签
  • 避免通用仪表盘样式
从零构建报告前，请先阅读 
references/style-guide.md
。如果需要快速生成精美的报告，可基于 
assets/html-report-starter.html
模板，替换占位符内容即可。

8. Verify before handoff

8. 交付前验证

Check:
  • artifact path exists
  • findings still match the actual code
  • any requested forbidden strings are absent from generated output
  • if tests were not run, say so explicitly
检查以下内容：
  • 产物路径是否存在
  • 发现的问题是否仍与实际代码匹配
  • 生成的输出中是否不存在用户要求禁止的字符串
  • 如果未运行测试，需明确说明

Review Heuristics

审查启发式规则

Plugin and platform work

插件与平台相关工作

Watch closely for:
  • docs claiming sandboxing while runtime executes trusted host processes
  • module-global state used to smuggle React context
  • hidden dependence on render order
  • plugins reaching into host internals instead of using explicit APIs
  • "capabilities" that are really policy labels on top of fully trusted code
需密切关注：
  • 文档声称支持沙箱隔离，但运行时实际执行可信宿主进程
  • 使用模块全局状态传递React context
  • 对渲染顺序存在隐藏依赖
  • 插件直接访问宿主内部逻辑而非使用显式API
  • “能力”实际上是完全可信代码之上的策略标签

Good signs

积极信号

  • typed contracts shared across layers
  • explicit extension points
  • host-owned lifecycle
  • honest trust model
  • narrow first rollout with room to grow
  • 跨层级共享类型化契约
  • 显式定义的扩展点
  • 宿主掌控生命周期
  • 诚实的信任模型
  • 初始发布范围狭窄，留有扩展空间

Final Response

最终回复

In chat, summarize:
  • where the report is
  • your overall call
  • the top one or two reasons
  • whether verification or tests were skipped
Keep the chat summary shorter than the report itself.
在聊天窗口中，需总结：
  • 报告的存放位置
  • 整体结论
  • 最主要的一两个原因
  • 是否跳过了验证或测试
聊天摘要需比报告本身更简短。