企业官网建设流程全解析

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体

在 Warp 的代码审查（Code Review）面板中，推送到远端是高频操作，但历史上它缺少一个"确认前先看清要推送什么"的界面：用户点击 Push / Publish 后，操作直接执行，既看不到目标分支，也看不到将包含哪些提交。本文围绕仓库中 APP-3920 产品文档 讲解 Warp 如何为代码审查面板补齐 Push / Publish 确认对话框：从打开入口、界面布局、提交与文件级统计的展示，到确认后的加载 / 成功 / 失败 / 取消完整状态机，再到"Commit and push" 链式流程，并结合 push.rs、git_dialog/mod.rs、git_actions.rs、git.rs 等源码说明底层实现。读完本文，你将能准确描述该功能的交互契约、核心数据结构、底层 git 命令调用链，以及文档设计与实际实现的差异。

一、背景：为什么需要专门的 Push / Publish 对话框

在 Warp 代码审查 2.0 的交互链路中，git 操作被拆成了三个有明确边界的对话框：

Push / Publish 在 APP-3920 之前没有任何确认流程：点击 "Push" 或 "Publish" 会直接运行操作，没有"将要推送什么"的预览，也没有加载 / 错误状态反馈。APP-3920 的目标是在不离开 diff 视图的前提下，为用户提供一个集中式的确认对话框。

从源码结构看，这个对话框并非独立实现，而是统一 git 对话框GitDialog的一个模式。在 git_dialog/mod.rs 的模块注释中可以看到设计意图：

GitDialogis a single view with multiple modes — each mode owns its own state, body renderer, and async op in its own submodule.

GitDialogMode枚举定义了三种模式（git_dialog/mod.rs）：Commit(CommitState)、Push(PushState)、CreatePr(PrState)。外层视图（GitDialog）统一持有所有共享内容：标题与关闭按钮、底部 Cancel / Confirm 按钮、模糊背景遮罩、加载生命周期、ESC 键绑定与动作分发。Push 模式只负责自己的PushState、正文渲染器与异步操作。

明确的非目标

产品文档同时划定了边界（PRODUCT.md）：

• 不支持选择 / 取消选择单个提交再推送——所有未推送提交总是全部包含；
• 不支持 force push 等高级推送选项；
• Create PR 对话框由其他流程单独负责。

这保证了对话框的第一版保持简单：它的核心职责是"展示并确认一次完整的 push"。

二、对话框的打开入口与单对话框不变量

三种打开方式

Push 对话框在以下场景打开（PRODUCT.md）：

1. 点击代码审查头部的 "Push" 主操作按钮（当前处于 Push 模式时）；
2. 从 git 操作下拉菜单选择 "Push"；
3. 点击 "Publish" 主操作按钮（当前分支没有 upstream 跟踪分支时）。

这三个入口最终都汇聚到代码审查主视图的open_git_dialog方法。在 code_review_view.rs 中，GitDialogKind::Push { publish }分支会先读取diff_state_model.unpushed_commits(ctx)，再调用GitDialog::new_for_push构造对话框；publish布尔值决定了这是"推送已有分支"还是"发布新分支（设置 upstream）"。

单对话框不变量

文档明确规定"同一时间只允许打开一个 push/publish 对话框；若已有对话框打开，动作被忽略"。这个不变量在源码中有两层保障：

• 在 code_review_view.rs，open_git_dialog开头即判断if self.git_dialog.is_some() { return; }——只要存在任何一个 git 对话框（Commit / Push / CreatePr），新的打开请求都会被忽略；
• 在 git_dialog/mod.rs 中，GitDialogEvent::Completed与Cancelled事件会清空git_dialog并（仅在 Completed 时）刷新 PR 信息，保证对话框关闭后才能再次打开。

此外，open_git_dialog还会检查is_git_operation_blocked与仓库 / 分支是否存在，避免在 git 操作被锁定（例如合并或索引锁进行中）时打开对话框。

主按钮如何决定 Push 还是 Publish

头部主按钮的模式由primary_git_action_mode计算得出（code_review_view.rs）：

1. 有未提交更改 →Commit；
2. 无 upstream 且有本地提交 →Publish；
3. 有本地提交（且有 upstream）→Push；
4. 已有 PR →ViewPr；
5. 满足条件（有 upstream、不在主分支、upstream 与主分支不同）→CreatePr；
6. 否则回退到Commit（禁用状态）。

这正是"Publish 模式即没有 upstream 跟踪分支"的判定来源：has_upstream = diff_state.upstream_ref(app).is_some()。值得注意的是，代码还处理了一个边界：upstream == main（例如git checkout -b feature origin/master之后）意味着分支还没有推送到自己的远端 ref，此时按钮会呈现 Publish 而非 Push。

三、对话框布局：460px 居中模态下的三个信息区

按 PRODUCT.md 与 git_dialog/mod.rs 的实现，对话框是一个 460px 宽、带模糊背景的居中模态遮罩（width: Some(460.)，背景色使用appearance.theme().blurred_background_overlay().into()），结构自顶向下为：

1. 头部：标题 + 图标 + 关闭按钮

标题由GitDialog::title()根据模式动态生成（git_dialog/mod.rs）：

• Push模式："Push changes"；
• Publish模式："Publish branch"。

标题左侧的图标同样区分两种模式（git_dialog/mod.rs）：Push 使用Icon::ArrowUp，Publish 使用Icon::UploadCloud；头部右侧是关闭按钮（X），带 "ESC" 提示 tooltip。

2. Branch 区：git branch 图标 + 当前分支名

由共享渲染辅助函数render_branch_section生成（git_dialog/mod.rs）：一个 "Branch" 标签，下面一行是 16×16 的Icon::GitBranch图标 + 分支名文本。该函数同时被 Commit、Push、CreatePr 三种模式复用。

3. Commits 区："Included commits" 标签 + 可滚动提交卡片列表

push::render_body（push.rs）在 Branch 区下方渲染提交列表，只有当commits非空时才显示。列表的关键实现参数：

• 最大高度MAX_COMMITS_HEIGHT = 300.（push.rs），超出部分由ClippedScrollable::vertical滚动；
• 每张提交卡片（push.rs）包含：
  • 提交主题（commit.subject），单行不换行（soft_wrap(false)）；
  • 统计行：文件数（N files，1 个时显示1 file）、绿色+additions（add_color）、红色-deletions（remove_color），仅当对应数值大于 0 时显示；
  • 右侧 chevron 图标：收起时Icon::ChevronRight，展开时Icon::ChevronDown（render_chevron_icon）。

整个卡片摘要区是Hoverable+ 手型光标（Cursor::PointingHand），点击后分发GitDialogAction::Push(PushSubAction::ToggleCommit(hash))（push.rs）。

4. 展开后的文件列表：文件名 + 目录 + 每文件 +/- 统计

展开某条提交后，render_file_list逐行渲染该提交的变更文件（git_dialog/mod.rs）。每行通过split_file_path（git_dialog/mod.rs）把路径拆成"文件名（主色）+ 目录前缀（次色）"两部分，右侧显示+additions与-deletions统计。文件列表同样包在带边框（theme.surface_3()）、圆角 6px 的卡片容器中。

5. 底部：Cancel + 主操作按钮

底部行由Dialog组件的with_bottom_row_child组装（git_dialog/mod.rs）：左边是 NakedTheme 的 "Cancel" 按钮，右边是 SecondaryTheme 的主操作按钮。主按钮的初始标签与图标由push::confirm_label/push::confirm_icon决定（push.rs）：Publish+Icon::UploadCloud或Push+Icon::ArrowUp。

四、Push 与 Publish：同一个 UI，两个标签

文档明确要求"Publish 复用同一 UI，仅调整标签与图标"。源码中这一设计由一个publish: bool标志贯穿整个PushState（push.rs），它影响四处可见差异：

而底层的 git 操作完全相同：run_push在 git.rs 中固定执行git push --set-upstream origin <branch>。也就是说，Publish 与 Push 在仓库实现上唯一的差异是--set-upstream是否"首次生效"——对已有 upstream 的分支它只是维持原状，对没有 upstream 的分支则建立跟踪关系。这是文档"首次分支发布（设置 upstream 跟踪）"的底层对应。

从GitDialog::new_for_push（git_dialog/mod.rs）可以看到：构造时把publish与commits一起传入push::new_state，之后start_confirm（push.rs）在确认时读取state.publish，用于决定加载标签，并把branch交给diff_state_model.git_push。

五、未推送提交的数据来源：git log --numstat 与 fork-point 回退

提交与文件统计的抓取

Push 对话框打开时，open_git_dialog通过model.unpushed_commits(ctx)一次性取得所有未推送提交。底层实现在 git.rs 的get_unpushed_commits：

• 有 upstream：执行git log <upstream>..HEAD --format=COMMIT:%H\t%s --numstat，范围是upstream..HEAD；
• 无 upstream：先尝试detect_fork_point找出 fork-point（分支与主干分叉的提交），范围退化为<fork_point>..HEAD；若 fork-point 探测失败，则退化为HEAD（仅当前提交）；
• 日志格式COMMIT:%H\t%s提供提交哈希与主题，--numstat提供每文件+additions\t-deletions\tpath。

parse_commit_log（git.rs）按行解析：遇到COMMIT:行开始一个新提交，后续非空行作为 numstat 累加该提交的files_changed、additions、deletions，并把FileChangeEntry { path, additions, deletions }追加到commit.files。最终每个Commit都携带完整的文件级变更数据。

文档设计与实际实现的差异：从"按需加载"到"预先捕获"

产品文档的 "Commit files loading" 一节描述的是惰性加载方案：Per-commit file lists are fetched lazily via git diff-tree --numstat，首次展开时显示 "Loading…" 占位符，并按提交哈希缓存。但在当前仓库的实际实现中，这一点发生了改变——push.rs 的模块注释明确说明：

Each commit's file list is captured up front onCommit.files, so expansion is a pure toggle (no per-commit fetch).

也就是说，文件列表在对话框打开时通过上述一次git log --numstat全部抓取并挂在Commit.files上；展开 / 收起只是expanded: HashMap<String, bool>的纯状态切换（push.rs），不再有按需请求，也就没有 "Loading…" 占位符和按提交哈希的缓存机制。从代码结构看，这是实现者在"数据体积可接受、交互更简单"与"严格惰性加载"之间做的取舍——对于典型的未推送提交数量，一次抓取带来的额外成本远小于为每次展开维护异步请求的状态机。

撰写或阅读本功能文档时需要注意这一差异：以当前仓库 push.rs 的实现为准。

六、确认操作：加载、成功、失败、取消的完整状态机

加载状态

点击主按钮后，start_confirm调用me.set_loading(loading_label, ctx)（git_dialog/mod.rs）：

• 按钮标签切换为 "Pushing…" 或 "Publishing…"，并set_disabled(true)；
• Cancel 与关闭（X）按钮同时被禁用——文档说"取消按钮仍可见但点击被忽略"，实现上直接禁用了按钮；
• 随后把异步操作交给diff_state_model.git_push(branch, ctx)。

异步操作的通道是统一的DiffStateModelEvent::GitOpCompleted：当handle_diff_state_event收到GitOpResult::PushCompleted且对话框处于loading状态时，进入push::finish_push（push.rs）。注意if !self.loading { return; }的门槛——只有对话框自己发起的操作才会被处理，避免了乱序事件污染状态。

成功：关闭 + toast + 刷新

finish_push在成功时：

1. 弹 toast："Changes successfully pushed." 或 "Branch successfully published."（经ToastStack的DismissibleToast展示，见 git_dialog/mod.rs）；
2. 发送遥测事件GitDialogCompleted { operation: Push | Publish, status: Succeeded }；
3. 发射GitDialogEvent::Completed——父视图据此关闭对话框，并调用refresh_pr_info（code_review_view.rs）。

由于git_push完成后模型会重新计算未推送状态并应用 delta（见下文），头部 git 操作按钮随之更新——例如分支推送完成后按钮从 "Push" 切换到 "Create PR"，这正是成功标准的第 9 条。

失败：对话框保持打开 + 错误 toast + 按钮恢复

失败时finish_push的行为与成功形成对称：

• 对话框不关闭；
• 主按钮恢复原标签并重新启用，Cancel / 关闭按钮恢复可用（父视图在收到Completed前不会清空对话框，而失败路径只发 toast 与 telemetry，不发Completed）；
• 错误经user_facing_git_error映射为可读文案后以 toast 展示。

user_facing_git_error（git_dialog/mod.rs）是错误处理的亮点：它把原始 git 错误字符串映射为人类可读的固定文案，覆盖了常见失败模式：

原始错误仍会通过report_error!单独记录日志，toast 只承担面向用户的简洁文案。

取消：三条路径，均无副作用

用户可通过三种方式取消（PRODUCT.md）：

1. Cancel 按钮；
2. 关闭按钮（X）；
3. 按下 ESC。

三者最终都分发GitDialogAction::Cancel。ESC 通过固定键绑定注册实现（git_dialog/mod.rs）：FixedBinding::new("escape", GitDialogAction::Cancel, warpui::id!("GitDialog"))，作用域限定在GitDialog的 keymap context（ui_name()即 "GitDialog"）。

取消的处理在handle_action（git_dialog/mod.rs）：if !self.loading时才真正执行——推送进行中点击取消被忽略，与文档一致。取消会按当前模式发送GitOperationKind::Push / Publish的Cancelled遥测，再发射GitDialogEvent::Cancelled，父视图仅关闭对话框、不刷新状态。

七、"Commit and push" 链式流程：不打开 Push 对话框

意图选择器

Commit 对话框（APP-3919）内置了三段式意图选择器（commit.rs）：Commit / Commit and push / Commit and create PR。其中 "Commit and push" 的标签与图标还会根据has_upstream切换（commit.rs）：有 upstream 显示 "Commit and push" +Icon::ArrowUp，否则显示 "Commit and publish" +Icon::UploadCloud——与 Push 对话框的标签逻辑一致。

选择意图后点击确认，start_confirm（commit.rs）把整个 Commit 模式置为加载态：主按钮标签统一变为 "Committing…"（静态标签，LOADING_LABEL），提交消息编辑器被锁定（InteractionState::Disabled），随后调用diff_state_model.git_commit_chain。

底层调用链

本地后端的git_commit_chain（diff_state/local.rs）spawn 异步任务调用git_actions::run_commit_chain。编排函数在 git_actions.rs：

1. 先执行git::run_commit（git.rs）——用git diff --cached --name-only检查暂存内容（空暂存且排除未暂存时抛错），再git commit -m <message>；
2. 若意图为CommitAndPush，接着执行git::run_push（即git push --set-upstream origin <branch>）；
3. 若意图为CommitAndCreatePr，push 后再创建 PR；
4. 无论走哪条分支，结束后统一调用compute_unpushed_state重新计算"未推送提交 + upstream ref"作为 delta 返回。

也就是说，Commit and push 在底层就是顺序执行git commit→git push --set-upstream，中间没有任何对话框插入，与文档"链式自动执行、不显示单独 push 对话框"的设计完全一致。

单一成功 toast

成功路径由commit::finish_commit_chain处理（commit.rs）：CommitAndPush成功只弹一条 toast——"Changes committed and pushed."；CommitOnly则是 "Changes successfully committed."。任一步失败（commit 或 push）都会走user_facing_git_error的错误 toast，并且不会弹出误导性的成功提示。操作过程中对话框全程保持打开并显示 "Committing…"，直到收到GitOpCompleted(CommitChainCompleted)才统一关闭。

八、双后端：本地与远端一致的执行语义

代码审查面板同时支持本地仓库与远端（remote server）仓库，Push / Publish 的模型层在 diff_state/local.rs 与 diff_state/remote.rs 中各有一套实现，但对外行为一致：

• 本地后端（DiffStateModel::git_push，local.rs）：spawn 异步任务调用git_actions::run_push，成功后应用apply_git_op_delta(commits, upstream_ref)刷新元数据，再发射GitOpCompleted(PushCompleted)；
• 远端后端（RemoteDiffStateModel::git_push，remote.rs）：通过RemoteServerManager分发到远端 daemon 执行，响应经handle_git_push_response（remote.rs）把GitOpDelta转成领域类型并应用，同样发射GitOpCompleted。

git_actions.rs的模块注释也强调（git_actions.rs）：这些动作函数是刻意与后端无关的——本地对话框与远端 daemon 共用同一套编排，因此 Push / Publish 在本地与远端的行为保持一致。对话框 UI 层只依赖统一的GitOpCompleted事件，无需区分后端类型。

九、验证与验收：如何确认功能符合预期

产品文档给出了两条验证维度，可作为手工测试清单：

验收标准（Success Criteria）：

1. 点击头部 "Push" 打开对话框，正确显示分支名与所有未推送提交及统计；
2. 展开提交显示变更文件与每文件 +/- 统计；
3. 确认推送显示加载状态，完成后关闭对话框并弹出成功 toast；
4. 推送失败时对话框保持打开、错误 toast 出现、按钮恢复可用；
5. 点击 "Publish" 打开同一对话框，标题为 "Publish branch"、按钮为 "Publish"；
6. 成功发布弹出 "Branch successfully published." toast；
7. Commit 对话框选择 "Commit and push" 后链式执行 commit → push，不打开 Push 对话框；
8. 非加载状态下可通过 Cancel、X、ESC 三种方式关闭对话框；
9. 推送 / 发布成功后 git 操作按钮更新为新状态（例如切换为 "Create PR"）。

操作验证（Validation）：

• 打开一个有未推送提交的仓库，点击 "Push"，核对分支与提交列表；
• 展开提交，核对文件列表与统计正确加载；
• 确认推送，核对加载状态、成功 toast 与对话框关闭；
• 模拟推送失败（如网络问题），核对错误 toast 与按钮恢复；
• 在无 upstream 的分支上核对 "Publish" 以发布专用标签打开对话框；
• 从 Commit 对话框使用 "Commit and push"，核对两阶段操作成功且只弹一条 toast；
• 分别用 Cancel、X、ESC 取消，核对未执行任何操作。

从源码角度补充一条可观察的验证途径：成功路径与取消路径都会发送CodeReviewTelemetryEvent::GitDialogCompleted遥测（operation 为Push/Publish，status 为Succeeded/Cancelled/Failed，is_local 根据仓库位置推导），可通过遥测日志确认每次操作的状态流转与预期一致。

十、设计权衡与遗留开放问题

非目标的代价

"所有未推送提交总是全部包含"意味着对话框无法精细化控制推送内容，但换来了简单可靠的交互；配合文档中的开放问题——"Commit and push 是否应该显示单独的推送确认，还是当前链式行为（无中间对话框）正确？"——可以看出当前设计倾向于减少确认打断，让高频的 commit-and-push 一体化完成，而把确认机会留给"内容可预览"的独立 Push 对话框。

实现层面的两个值得注意的决策

1. 文件列表预先捕获而非惰性加载：如第五节所述，当前实现用一次git log --numstat取回全部文件数据，展开为纯状态切换。这简化了状态机，但代价是打开对话框时的一次性开销随提交数量增长；
2. Push 与 Publish 的单一命令：git push --set-upstream origin <branch>对两种模式一视同仁，差异完全体现在 UI 文案与遥测字段上，保证底层行为不会因模式分支产生分叉。

结语

APP-3920 的 Push / Publish 对话框是 Warp 代码审查 git 操作闭环的最后一块拼图：它以统一的多模式GitDialog为骨架，用publish: bool一个标志复用整套 UI，用git log --numstat提供提交与文件级预览，用统一的GitOpCompleted事件驱动加载 / 成功 / 失败 / 取消的状态流转，并通过run_commit_chain把 commit → push 串成无打断的链式流程。本文覆盖了从产品契约、界面布局、数据来源到双后端执行的完整链路；对于希望深入源码的读者，建议从 push.rs 出发，沿 git_dialog/mod.rs → code_review_view.rs → git_actions.rs → git.rs 逐层追读，即可完整还原该功能的调用链。

• 桌面应用
• 开发者工具
• 人工智能
• AI 应用
• AI Agent
• 代码智能体