pr-report

PR 报告技能

对 PR、分支或大型贡献进行维护者级别的评审。

默认立场：

• 先理解改动，再做判断
• 解释系统的实际构成，而不只是差异
• 将架构问题与产品范围方面的异议区分开来
• 给出具体建议，而不是含糊的印象

适用场景

用户提出以下请求时，使用此技能：

• “深入评审这个 PR”
• “给我讲讲这项贡献”
• “为这个 PR 做一份报告或网页”
• “将这个设计与类似系统进行比较”
• “我应该合并这个吗？”

输出

常见输出：

• tmp/reports/... 中的独立 HTML 报告
• report/ 或其他指定文件夹中的 Markdown 报告
• 聊天中的简短维护者摘要

如果用户要求制作网页，请构建一份精致的独立 HTML 文档，包含清晰的章节和易读的视觉层次。

此技能附带的资源：

• references/style-guide.md，用于指导视觉风格和报告呈现规则
• assets/html-report-starter.html，可复用的独立 HTML/CSS 起始模板

工作流程

1. 获取目标并明确范围

尽可能基于本地代码开展工作，而不只是查看 GitHub PR 页面。

收集：

• 目标分支或工作树
• 差异规模和变更涉及的子系统
• 相关的仓库文档、规范和不变量
• 如果 PR 文本或设计文档中有记录，了解贡献者的意图

首先回答：这项改动试图实现什么？

2. 建立系统的整体认知

不要止步于逐个文件的记录。要还原整体设计：

• 新增了什么运行时或契约
• 哪些层发生了变化：数据库、共享类型、服务端、UI、CLI、文档
• 生命周期：安装、启动、执行、UI、故障、停用
• 信任边界：哪些代码在何处、以何种权限运行

对于大型贡献，请加入教程式章节，从基本原理讲解系统。

3. 以维护者的视角评审

优先列出发现的问题，并按严重程度排序。

重点关注：

• 行为回归
• 信任或安全漏洞
• 误导性的抽象
• 生命周期和运维风险
• 难以解除的耦合
• 缺失的测试或无法验证的说法

尽可能引用具体文件位置。

4. 区分异议类型

明确指出问题属于：

• 产品方向
• 架构
• 实现质量
• 推出策略
• 文档准确性

不要把架构方面的异议藏在范围方面的异议中。

5. 必要时与外部先例进行比较

如果这项贡献引入了框架或平台概念，请将其与类似的开源系统进行比较。

比较时：

• 优先参考官方文档或源代码
• 关注扩展边界、上下文传递、信任模型和 UI 归属
• 提炼经验，而不只是指出相似之处

有价值的比较问题：

• 谁负责生命周期？
• 谁负责 UI 组合？
• 上下文是显式传递的还是隐式可用的？
• 插件是受信任代码还是沙盒化代码？
• 扩展点是否有明确的名称和类型？

6. 给出可执行的建议

不要只给出“合并”或“不合并”的结论。

选择一项：

• 按当前状态合并
• 完成具体的重新设计后合并
• 保留特定部分
• 作为设计研究继续推进

如果拒绝或缩小范围，请说明哪些内容值得保留。

建议方向示例：

• 保留协议/类型模型
• 重新设计 UI 边界
• 缩小初始范围
• 延后第三方代码执行
• 先推出由宿主负责的扩展点模型

7. 构建产物

建议的报告结构：

1. 执行摘要
2. PR 实际新增的内容
3. 教程：系统的工作原理
4. 优势
5. 主要发现
6. 对比
7. 建议

对于 HTML 报告：

• 使用经过精心设计的字体排印和配色
• 为较长的报告提供便捷的导航
• 使用醒目的章节标题和简短的参考标签
• 避免采用千篇一律的仪表板样式

从头开始构建之前，请先阅读 references/style-guide.md。 如果需要快速制作精致的初稿，可以从 assets/html-report-starter.html 开始，并将占位内容替换为实际报告。

8. 交付前验证

请检查：

• 产物路径是否存在
• 发现的问题是否仍与实际代码相符
• 生成的输出中是否不含任何指定的禁用字符串
• 如果未运行测试，请明确说明

审查启发式

插件和平台工作

重点关注：

• 文档声称使用沙箱隔离，但运行时却执行受信任的主机进程
• 使用模块全局状态来传递 React 上下文
• 暗中依赖渲染顺序
• 插件访问主机内部实现，而非使用显式 API
• 实际上只是在完全受信任的代码上贴上策略标签的“能力”

良好迹象

• 各层共享类型化契约
• 明确的扩展点
• 由主机管理生命周期
• 真实可信的信任模型
• 首次推出的范围较小，同时留有扩展空间

最终回复

在聊天中总结：

• 报告所在位置
• 总体判断
• 最重要的一到两个原因
• 是否跳过了验证或测试

聊天摘要应短于报告本身。