写 PR 正文时用：用 Summary、Evidence…

在创建或编辑 Pull Request 正文时，按模板组织变更摘要、前后证据和合并风险。

适用场景

解决思路

1. 使用以下模板编写 PR 正文： ```markdown ## Summary <diagram, diff-sketch, or tree> ## Evidence - **Before:** <screenshot/output/failing test run> **After:** <screenshot/output/passing test run> ## Merge Danger **Door:** <one-way or two-way> <optional: description> **Blast Radius:** <one-word description> <optional: potential ramifications of merge> ```
2. 跳过所有开场白，保持正文简短。
3. 使用 `CONTEXT.md` 中的用户领域语言。
4. 在 Summary 部分：选择能让关键点最清楚的最小视图。
5. 展示逻辑或算法时，用伪代码，例如： ```text on(save) if content is unchanged return cached result write new content return fresh result ```
6. 展示运行时控制流时，用调用树，例如： ```text submitForm createSession persistPrompt launchAgent navigateToSession ```
7. 展示 UI 结构时，用组件树，并包含重要的 state 和模块边界，例如： ```tsx <SessionPage>(apps / example / src / routes / session.tsx); useSessionEvents() < SessionToolbar > <RunSkillButton>(packages / ui); ```
8. 展示文件职责或大范围重构时，用浅层文件树，例如： ```text src/ ├── commands/ # parses user actions ├── sessions/ # owns session state └── transport/ # sends API requests ```
9. 展示组件交互、控制流或数据流时，用 Mermaid，例如： ```mermaid sequenceDiagram participant User participant UI participant Daemon User->>UI: choose command UI->>Daemon: send expanded prompt Daemon-->>UI: stream result ```
10. 当重点是“改了什么”且周围结构已存在时，使用 `diff`。让 diff 形状匹配主题。
11. 对组件变更，使用组件树 diff，例如： ```diff <SessionPage> useSessionEvents() <SessionToolbar> + <RunSkillButton /> <SessionTimeline> + <SkillResultCard /> ```
12. 对文件布局变更，使用文件树 diff，例如： ```diff src/ ├── commands/ +│ └── show-me.ts # expands the slash command ├── sessions/ -└── transport.ts +└── transport/ + ├── client.ts + └── stream.ts ```
13. 对调用树或调用栈变更，使用调用树 diff，例如： ```diff submitForm createSession persistPrompt + expandSkillMention launchAgent - navigateToSession + navigateToSession + subscribeToEvents ```
14. 对状态或控制流变更，使用状态/控制流 diff，例如： ```diff on(save) - write content + if content is unchanged + return cached result + write new content + invalidate cache ```
15. 当大部分内容是新的时候，或省略上下文会隐藏所有权或顺序时，或用户需要可复制的目标形状时，展示完整代码块，例如： ```ts function expandSkill(command: string): string { const skillName = command.slice(1); return `use the ${skillName} skill`; } ```
16. 将每个可视化放在它所支持的短文本旁边。
17. 只保留回答用户当前问题或解决当前讨论点所需的 calls、files、props、states 和 boundaries。
18. 可以使用其中一种或多种视图，但不太可能全部使用；自行判断，不要淹没用户。
19. 在 Evidence 部分：提供变更有效的具体证据。展示 before 和 after。
20. 截图是 S-tier：当环境已配置好且变更是视觉的时使用。
21. 基于执行的证据是 A-tier：使用测试结果、控制台输出。用伪代码展示现在失败和现在通过的准确测试。
22. 在 Merge Danger 部分：描述这是单向门还是双向门。双向门可以走回去，单向门不能。
23. 容易回滚的 PR 风险更低。涉及破坏性操作或难以逆转决定的变更是单向门。
24. 在 Merge Danger 部分：Blast Radius 是此 PR 引入变更的潜在影响或范围。考虑所有可能性。例如布局偏移、对消费者造成破坏、移动端响应式等。