向外部开源项目提 PR 与应对审查（Upstream PR）

给外部开源仓库贡献代码时，维护者不共享你的本地上下文：任何违背历史契约、只修半边入口、日志污染或充满模板腔的回复，都会在第一轮审查被拦下。按下面四步把问题消灭在推送前。

1. 开工与工作树卫生

• 复用现有克隆开 git worktree：在本地已有的仓库克隆上用 git worktree add <临时路径> -b <分支> 隔离开发，直接继承仓库已配好的作者身份（对外统一使用 GitHub noreply 邮箱，避免新 clone 漏配身份或泄露私人邮箱）。
• 摸清目标分支与门禁：先确认上游真实合入分支（如 main 或 dev），读 package.json、Makefile 或 .github/workflows/ 列全维护者会跑的每一条检查（类型检查、格式化、架构/清单校验、单测、E2E）。非本 PR 引入的锁文件变动（package-lock.json / pnpm-lock.yaml）不要提交。
• 日志与产物不落地父目录：构建、单测、Playwright/Electron E2E 的重定向日志与临时截图一律写进会话临时目录（scratchpad 或系统临时目录），禁止写 > ../xxx.log 把构建垃圾留在上级目录。收尾时清掉未跟踪的 test-results/、debug.log 及用完的临时 worktree。

完成标准：独立工作树干净、作者邮箱合规、上游门禁命令清单已列全。

2. 提交 PR 前：维护者视角七项自审

全部自动门禁跑绿后、发起 PR 前，逐项核查以下七类高频首轮打回原因：

1. 不违背历史契约：检索所改模块关联的旧 Issue、PR 与既有测试，弄清当初为什么这样设计。修当前 bug 不能破坏已有承诺（例如严分数据出处：模型预填默认值不等于用户显式确认，不要把一个错误换成另一个错误）。
2. 集中点修全入口：列出触发同一状态变化的所有入口（如桌面 UI、Web 端、Webhook/机器人、定时自动化；或资源清理的多条销毁路径），在底层单一汇合点处理，不在单个调用方打补丁。
3. 不靠外层守卫掩盖内层 bug：检查新增逻辑在去掉配额上限、防抖或外层兜底后自身是否依然正确（避免重复触发的底层缺陷只是恰好被额度上限压住）。
4. 流式与快照事件按状态机处理：快照和通知可能重复到达或跨回合迟到——同一回合副作用只触发一次、统计严格限定在本回合数据、下游执行失败退还预扣配额、用户显式意图与派生运行状态分开存储。
5. 测最坏边界并与旧版做回归对比：核心承诺必须覆盖极端输入与临界值（例如普通高度下余量正常、超高内容下余量归零恰恰违背设计目的）；与改前界面/行为逐项对比，确保没遮挡既有控件、没漏掉同类组件统一的视觉样式（如毛玻璃、过渡、焦点态）。
6. 断言必须真能泛红：把修复代码临时还原或改坏一次，亲眼确认新写的单测/E2E 会失败（淘汰 not.toBeNull() 放过 {0, 0} 这类假绿断言）；代码改了，紧邻的注释和旧断言同步改。
7. 评估旧版磁盘数据兼容：推演已安装旧版本的用户升级后读到新配置或新消息字段时的表现，把向后兼容处理写进 PR 描述。

完成标准：自动门禁全绿，七项自审无遗留阻塞点。

3. 处理审查意见与去 AI 味回复

改代码纪律

• 按维护者意见逐条修复，每条缺陷配一个先红后绿的回归用例。
• 推送采用追加新提交（不 rebase / --force 改写已审提交），让维护者能直接按增量 commit 审阅。
• 涉及产品语义或交互取舍（例如某种边界状态算不算用户已作答）时，先停下交本人拍板；对外发布 PR 评论需经本人当次授权。

回复口吻（代本人起草评论时）

读起来必须像工程师本人手写，零模板腔：

• 直奔编号：开头至多一句简短致谢（如"谢谢，看得很细"），紧接着按维护者的编号逐条写清：改了什么（附 commit SHA）+ 用哪条用例或命令验证的。
• 删掉套话与排版噪音：不复述维护者刚说过的话，不写拔高奉承，不堆 Markdown 二三级小标题、大表格或逐文件行号清单。
• 验证压成自然一段：简短交代跑过了哪些门禁与测试；若某条失败用例在基线分支原本就挂，如实点明基线同挂。
• 留口子直说：有意暂留的边界直说原因，再自然问一句对方要不要顺手补上。
• 分清对方否的是「方向」还是「实现」：对方认可方向、只指出实现缺陷时，修完正常收尾，不要写"不合适直接关掉也行"这类示弱话；对方确实否了整体方向时，清楚说明一次背景理由即可，不反复争辩，交维护者定夺。
• 主线程把关：若派子代理搜集材料或起草回复，主线程必须把草稿压短（通常删去三分之二冗余）、改成自然口吻后再发；发出后在对话里把每条回复的要点（或原文）和链接交代给本人。

完成标准：增量提交已推送、回归测试全绿、发出的评论自然简练且已向本人回报链接与要点。

4. 解 PR 冲突（先排假冲突）

看到 GitHub 显示 PR CONFLICTING / DIRTY 时，按顺序排查：

1. 拉取真实目标分支：跑 git fetch <upstream>。注意部分本地克隆的 remote.<name>.fetch 只配了默认分支（如只抓 main 不抓 dev），先用 gh api repos/<owner>/<repo>/branches/<base> --jq .commit.sha 核对远端目标分支最新 SHA，必要时显式 git fetch <upstream> <base>。
2. 验是否已被手动合入：跑 git merge-base --is-ancestor <PR_HEAD> <upstream>/<base>。退出码为 0 说明维护者已在本地手动合并推送（常顺手重跑了清单或文案生成脚本），GitHub 页面只是刷新延迟——无需任何操作。
3. 解真冲突：确认未合入且确有冲突时，将 <upstream>/<base> merge 进当前 PR 分支追加合并提交（不 rebase 强推）；自动生成的清单或国际化字典冲突时，用仓库自带生成脚本重跑并检查无多余脏 diff，跑通门禁后推送。

完成标准：确认已合入上游，或合并提交推送后全套门禁通过。