pi-agent-desktop是一款跨平台 AI 编程 Agent 桌面应用：它把pi-web的 Web 界面与 Pi SDK 的 Agent 能力打包成签名桌面安装包，覆盖 macOS、Windows 与 Linux，无需配置环境即可直接使用。对维护者而言，这个项目最大的难题不是开发功能，而是如何持续从上游同步代码而不把本地的桌面定制冲掉。本文带你拆解它的答案：一条机器可读的 Fork 边界规则、一个"宁可大声失败"的合并策略，以及一条"全平台齐了才发布"的签名发布流水线。

为什么 Fork 同步如此棘手：三层架构与文件归属边界

pi-agent-desktop的整个维护成本集中在一个地方：上游也拥有、而 Fork 也修改过的那批文件。为此，项目先明确"谁拥有哪些文件"。三层来源、三种集成方式：

边界不是靠口头约定，而是写进了一份机器可读的清单 fork-ownership.json：

• driftedUpstreamFiles：列出"上游拥有、但 Fork 也改过"的每个文件，并标注结构漂移行数与风险等级（high/medium/low），例如 SessionSidebar.tsx 约 2969 行结构漂移被标为high；
• forkOwnedPaths：Fork 独占、上游永远不会碰的路径，如src-tauri/、components/desktop/、native-theme.css，可自由修改；
• decisionLog：每一次边界变更的日期化决策记录，防止后人重复争论。

关键认知：冲突是安全的，"干净但语义错误"的合并才危险

这是整套规则的灵魂。git merge出现文本冲突时，同步工作流在set -euo pipefail下直接失败，什么都不发布——大声失败是安全失败。

真正危险的是"静默语义冲突"：上游改了某块代码，Fork 也改过同一区域，但两边改的行不重叠，Git 合并得干干净净，测试、tsc --noEmit、eslint全绿，结果却变成了同一行为的两份实现。典型场景是跨文件搬移代码——Git 不跟踪这种搬移：

约 500 行代码从SessionSidebar.tsx搬进了上游不存在的 ProjectPicker.tsx 和 path-ui.tsx。此后上游若再改"项目选择器"那块逻辑，会干净地合并回SessionSidebar.tsx，复活一份已经搬走的代码副本。

另一个坑是样式漂移被误判：上游组件大量使用内联style={{ … }}，样式表无法覆盖它，所以改样式必须编辑上游文件（删内联样式、换className），这会产生巨大 diff——但没关系，上游若再改同一行就会文本冲突、同步失败，属于"安全的响"。真正要防的是重写 JSX 树、跨文件移动逻辑这类结构漂移，它们合并时悄无声息。

哨兵测试：把"干净但错误"变成红灯

边界清单负责事前拦截，哨兵测试负责事后兜底。fork-extractions.test.mjs 覆盖"干净但错误"的两个方向：

• 复活（Resurrection）：Fork 搬走的代码重新出现在原文件里，例如displayCwd在SessionSidebar.tsx和path-ui.tsx中同时被定义；
• 侵蚀（Erosion）：Fork 的修改在合并中悄悄丢失，文件退回上游形态，例如AppShell.tsx丢掉data-tauri-drag-region，或 layout.tsx 丢掉native-theme.css导入（一丢整个换肤就没了）；
• 禁止项（forbiddenMarkers）：Fork 明确删掉、但上游仍在提供的功能，断言其标记字符串必须不存在——上游若"干净地"带回来，测试失败。

项目要求每条断言都经过变异验证（人为注入故障确认真的会失败）。哨兵报警时的默认动作是重新应用 Fork 修改，而不是删掉断言。

配套的漂移度量命令npm run drift会把每个共享文件拆成"外观漂移 vs 结构漂移"两类，并在风险等级与清单不符时报警。

手动同步上游：完整命令清单与冲突处理原则

以下流程适用于定制已提交、工作区干净的场景，完整操作说明见 fork-sync.zh-CN.md。

第一步：取回两边主干，从最新 Fork 建立同步分支

git fetch --no-tags origin main git fetch --no-tags upstream main git switch -c codex/sync-desktop-next origin/main

第二步：查看上游带来了什么

git log --oneline HEAD..upstream/main git diff --name-only $(git merge-base HEAD upstream/main) upstream/main

第三步：合并上游，并逐文件处理冲突

git merge --no-commit upstream/main

处理冲突的原则（比命令更重要）：

• 保留上游的运行时和拆分结构，把定制重接到实际的新入口上，不要把旧 JSX 整块搬回去；
• 重点检查ChatInput、AppShell、侧栏、拆出的菜单、主题、依赖锁和测试——不要批量选 ours / theirs；
• 新加入的文件同样要人工检查，Git 只标出冲突，不标出"该看的新文件"；
• 依赖升级保留锁定版本，合并 Radix 依赖后运行npm install；不要通过重新解析全部 caret 版本来解决锁文件冲突。

第四步：完整门禁验证

npm ci npm test npx tsc --noEmit npm run lint node scripts/upstream-css-baseline.mjs update 6fcd7d4 npm run drift PI_WEB_DESKTOP_BUILD=1 npm run build

其中6fcd7d4是 pi-web 的样式基线引用：upstream-css-baseline.mjs 保证 globals.css 和 settings.css 与上游字节级一致，所有 Fork 样式只允许放进 native-theme.css（在 layout.tsx 中最后导入，同优先级规则才能胜出）。最后提交、推送并发起 PR；PR 中写明测试结果与深浅主题、窄窗口、多行输入框等人工核对项。PR 合并后，再把本地主分支快进到origin/main。

每日自动同步：component-updates.yml 的七步流水线

手动流程之上，还有 .github/workflows/component-updates.yml 承担日常同步，顺序设计非常讲究：

1. 解析pi与pi-web的最新稳定发布，两者都没动就停；
2. 若该上游 tag 已有审查 PR 挂着，直接跳过，避免每晚重复做同一件事；
3. 在合并之前就把上游变更集与fork-ownership.json边界求交分类——合并提交一旦生成，原始变更集就无法再用普通 diff 还原了；
4. 执行git merge合入上游 tag、更新 Pi 依赖与组件清单；
5. 门禁全跑：npm test（含组件测试）、tsc --noEmit、npm run lint，以及一次真实的 standalone Next 构建；
6. 无交集→ 直接推main并派发签名发布；命中中/高风险文件→ 推sync/pi-web-<tag>分支并开出带边界报告的 PR，由人工合并后才触发发布；
7. 任何一步失败 → 创建或更新component-sync-failureissue，绝不静默堆积。

package-lock.json在此过程中还有一条隐藏规则：tauri 插件版本必须与src-tauri/Cargo.lock配对锁定，先恢复 HEAD 的锁再做npm install --package-lock-only，否则 caret 重新解析会令发布工作流测试失败。

签名发布流程：全部平台就绪，才允许出 Draft

同步成功后，release.yml 被显式触发，串行构建三平台工件：Apple Silicon DMG、Linux x64.deb、Windows x64 NSIS 安装包。这套发布流程有几个"防翻车"设计：

• Draft 兜底：Release 在整个构建矩阵和manifest任务都完成之前保持草稿状态；manifest任务依赖全部构建任务，任何一平台失败，发布就停在草稿，绝不带着残缺工件发布；
• 组件版本清单：安装后应用记录三个组件（pi-agent-desktop、pi、pi-web）的确切版本于src-tauri/resources/component-versions.json，更新器永远安装包含三组件最新版本的完整签名包，从不热替换已装应用里的单个 JS 包；
• 签名密钥：Tauri updater 签名密钥只存在于 CI Secrets，本地构建刻意不注册 updater 插件，防止调试构建接受更新载荷。

用户侧的体验因此很简单：设置页每至多一周检查一次最新稳定 Release，只有当本地版本更旧时，单个"升级"按钮才会点亮。完整规则见 desktop-updates.md。

给维护者的 5 条边界守则

1. 只改样式？把规则放进app/native-theme.css，上游文件里只把内联样式换成className，JSX 结构一律不动；
2. 通用改进？优先提交回上游 pi-web，结构漂移随之彻底消失；
3. 纯桌面功能？放进 components/desktop/，由上游文件用"一个 import + 一个挂载点"接入，绝不重构上游 JSX 来迁就桌面代码；
4. 新增漂移时：跑npm run drift，更新清单、给出disposition（reduce或accepted）、补哨兵断言、在decisionLog追加一行日期记录；
5. 哨兵报警时：先恢复行为，再谈其他——删断言是最坏的选择。

这套规则的效果是诚实地定价：大多数上游发布会开审查 PR 而不是无人值守发布。这正是维护一个 UI Fork 的真实运行成本——而护栏的目标，是让每一次同步成为一次审查，而不是一次静默事故。

延伸阅读

• Fork 同步操作手册：docs/fork-sync.zh-CN.md
• 归属边界与风险模型：docs/ownership-boundaries.md
• 每次上游合并的采纳/拒绝记录：docs/merge-history.md
• 桌面更新与签名发布：docs/desktop-updates.md
• 样式基线规范：docs/native-theme.md