【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载导读本文围绕 Plannotator 代码评审应用的since-basediff 类型展开它把「如果我现在提交并推送GitHub PR 会显示什么」这一意图固化为零配置的默认评审视图并用 Committed / Changes / Untracked 三段式文件面板同时回答「git status 会告诉我什么」。读完本文你将掌握since-base的 git 命令组合与退化保护、sections 分组 sidecar 的计算规则、客户端三段面板与渐进式披露设计以及基线滞后检测与一键 Fetch 的完整链路。1. 背景两种最常见诉求与 DiffTypePicker 的失效用户对评审应用的两条高频反馈是「我只想看到 GitHub 上会显示什么」和「我只想看到 git status 会显示什么」(决策文档)。旧默认体验让这两者都落空DiffTypePicker强制用户在渲染前把意图翻译成 git 机制staged / unstaged / merge-base / allmerge-base类型虽然提示语写着「与 GitHub PR 视图相同」却排除了工作区改动而默认的unstaged对刚提交完的用户显示为空。无论默认选哪个都会背叛其中一种心智。注since-base相关设计文档与决策位于 intent 文档、规格文档、SPIKE 验证、综合论证本文同时对照了当前仓库源码实现。2. 方案核心溶解选择而不是换一个默认决策不是换一个「更好的默认」而是溶解选择本身让一个复合比较同时服务两种心智。merge-base(origin/default, HEAD) → 工作区 未跟踪文件 「如果我现在推送GitHub PR 会显示什么」diff 内容回答 GitHub 问题屏幕上每个 diff 都意味着同一件事——「自 main 以来的变更」没有例外没有按文件切换模式。分组回答 git status 问题Committed弱化、Changes修改新增合并带暂存点、Untracked 三个分区正是三段式面板。「只看上一次提交」的诉求不作为本视图的开关——它本来就是高级菜单里的last-commitdiff 类型决策文档。3. 服务端一个since-basecase 走通所有既有接缝SPIKE 验证的核心结论是三段式面板不需要三个并行 diff服务器整台状态机currentPatch 单个currentDiffType 单个 fingerprint只容纳一个活跃 patch而一个复合比较正好契合SPIKE 文档。3.1 计算命令实现位于 packages/shared/review-core.tssince-basecase 在 runGitDiff 的 switch 中git rev-parse --verify HEAD # hasHead 守卫无 HEAD全新仓库时退化 git merge-base --end-of-options base HEAD # 与 merge-base 模式同源 git diff --no-ext-diff [-w] --src-prefixa/ --dst-prefixb/ --end-of-options mb # mb 后不带 ..HEAD → 对比的是工作区 # 再加上 getUntrackedFileDiffs()/dev/null --no-index 合成 diff要点merge-base 查找失败如仓库没有 main/master/origin、默认分支为trunk且无远端时退化到 HEAD用户仍能看到工作区改动而不是裸 git 报错无 HEAD 时则降级为仅未跟踪文件的 patch——与uncommitted的hasHead守卫同模式review-core.ts#L1671-L1695。3.2 伴随 case每个既有接缝加一个分支SPIKE 逐行验证的触点清单当前源码全部落位文件新增内容review-core.tsDiffType联合since-base加入类型联合约 L29review-core.tsgetGitDiffFingerprintsince-basecaseHEAD sha hashDiffOutput([mb])hashUntracked() base tip约 L2063-2076getFileContentsForDiffold git show mb:pathnew 工作区读取getGitContextdiffOptions存在默认分支时第一个发出选项labelAll changes since base经既有resolveInitialDiffType成为初始类型约 L724vcs-core.tsGIT_DIFF_TYPES加入since-basegit 专属canStageFiles返回 true工作区文件可暂存config.tsresolveDefaultDiffType白名单加入新 id默认从unstaged翻转为since-baseconfig.ts#L617-L623WORKTREE_SUB_TYPES加入since-base使worktree:path:since-base可解析、切换工作区时保留模式review-core.ts#L1517-L1527compareTarget.diffTypes变为[since-base, branch, merge-base]是「vs origin/main」基准选择器的门控来源约 L772agent-review-message.tsgetLocalDiffInstructiontarget 自与 的 merge-base 以来的全部变更含已提交与未提交加未跟踪文件——GitHub PR 会显示的完整集合inspect mb 查找 git diff mb命令3.3 默认值翻转与显式配置resolveDefaultDiffType的当前实现packages/shared/config.ts#L620-L623export function resolveDefaultDiffType(cfg?: PlannotatorConfig): DefaultDiffType { const v cfg?.diffOptions?.defaultDiffType as string | undefined; return v since-base || v local-vs-remote || v uncommitted || v unstaged || v staged || v merge-base || v all ? v : since-base; }即所有用户默认翻转为since-base但显式配置defaultDiffType的用户保留自己的选择旧配置中的branch到merge-base的映射继续保留intent 文档明确。3.4 客户端配套STAGEABLE_DIFF_TYPESuseGitAdd.ts加入since-base——行内暂存按钮与暂存点依赖它。OPTION_HINTSDiffTypePicker.tsx为新选项提供提示文案。App.tsx 的 worktree 子类型解析与WORKTREE_SUB_TYPES保持同步源码注释明确警告该副本若不同步会静默破坏 guide/tour 任务的上下文匹配。Pi 扩展vendor.sh构建期自动 vendorpackages/shared/与agent-review-message.ts到generated/共享层改动自动传播只需手工镜像sectionspayload 字段与POST /api/fetch-baseapps/pi-extension/server/serverReview.ts。4. Sections sidecar分组不是 diff是状态旁路三个分组加总恰好等于复合 patch 的文件清单因为分区只是同一数据集的三种视图。服务器在/api/diff与/api/diff/switch响应中、当diffType since-base时附带review.ts#L805 起有buildSectionsSidecarsections: { base: string; // 已解析的基准 ref如 origin/main mergeBase: string; // sha用于展示/调试 files: Recordstring, { group: committed | changes | untracked; status: A | M | D | R; // 相对 merge-base取自 patch 本身 staged: boolean; // porcelain 第一列 }; }数据来源是两条已有命令review-core.ts#L2346-L2381git status --porcelain # 工作区状态指纹计算本就在跑 git diff --name-only mb..HEAD # 「分支上改过」的文件集合分区规则Committed在 mb..HEAD 集合内、且 status 干净Changes被跟踪且工作区脏M/A 合流暂存位取 status 第一列Untracked??行。已在分支提交又本地编辑的文件只出现一次、落在 Changes其 diff 展示完整的「自 base 以来」故事——这是确认过的决策不做按文件覆盖。暂存但工作区已回退的文件会从 patch 中消失而 status 仍显示已暂存属于可接受的外观瑕疵SPIKE 边缘用例。5. 客户端三段式 Sections 面板新组件 SectionsPanel.tsx 与FileTree平级、共用左面板槽位是since-base的默认视图advanced 模式只渲染 Tree。逐行结构来自 mockup 原型Header「Review」 分支 chip下方安静的「vs origin/main」入口 → 打开既有BaseBranchPicker。三个可折叠分区带计数Committed约 55% 透明度弱化、Changes、Untracked。Committed 尺寸视口自适应已确认决策Changes 与 Untracked 永远完整渲染——每个可操作文件无需滚动即可见Committed 填满剩余垂直空间空间紧张时仍有「最少几行」的下限随后是「N more files」展开行展开态在面板内滚动实现见 SectionsPanel.tsx#L267-L330 的committedExpanded状态与高度计算。行解剖已阅复选框主操作沿用viewedFiles设施含v键与暂存自动标记已阅· 文件名 · 暂存点紫色· 安静 stage/ 按钮/api/git-add· 状态字母M 琥珀 / A 绿 / U 灰D 红未装饰的 modified 沿用树视图惯例。客户端在暂存后即时修正分组untracked且staged移入changes反之移回SectionsPanel.tsx#L282-L298。Sections | Tree 切换在面板头部选择以 cookie 持久化与其他设置一致第三个槽位 Commits 预留给 backlog 中的 git-graph 工作SPIKE-git-graph-view-20260618-220909.mdPhase 1 扁平提交列表 每提交 diff视图层零改动即可接入。渐进式披露默认屏零选择器。「vs origin/main」→ 基准选择器第 1 层。「Advanced」安静页脚行与既有复制 diff 页脚相邻→ 今天的DiffTypePicker完整模式列表staged/unstaged/last-commit/merge-base/all/worktrees选 advanced 模式自动切到 Tree 视图。DiffTypeSetupDialog新增「GitHub view (recommended)」为默认项进阶用户仍可选经典默认。6. 基线滞后让「这是 GitHub 视图」可信的一个横幅「我们对比的是 origin/main 上次 fetch 时的 GitHub」——诚实性是整套设计的信任前提。方案完全复用启动期ls-remote已有却丢弃的远端 tip SHA扩展detectRemoteDefaultBranch或同级函数从同一次git ls-remote --symref origin HEAD输出中保留sha\tHEAD行与本地git rev-parse origin/branch比对不同则 payload / fresh-probe 携带baseBehindRemote: true当前实现见 review.ts#L636-L711 的computeBaseBehindRemoteUI安静横幅「Baseline is behind GitHub · Fetch」→专用端点POST /api/fetch-base执行git fetch origin branch成功后客户端重跑/api/diff/switchpreserveFile。决策明确独立端点而非重载/api/diff/switch因为 fetch 是带自身失败模式的网络变更review.ts#L2279节奏启动时 约每 60s 检查一次网络调用不走 5s 指纹轮询。7. 范围边界与验收要点仅 Git。jj 保持jj-current默认与现 UIPerforce 与 workspace 模式不变since-base经GIT_DIFF_TYPES归 git 所有PR 模式不变——它本身就是 GitHub 视图。没有任何既有 diff 类型、端点或控件被删除。验收草图规格文档第 6 节特性分支 提交 编辑 新文件三段齐全、计数正确、每个文件 diff 都是「自 main」默认分支 本地编辑Committed 空Changes/Untracked 等同今天的 uncommitted 视图行内暂存按钮出现暂存点、文件自动标记已阅、文件留在 ChangesSections ↔ Tree 切换同一批文件、无重新拉取origin/main 过期横幅出现Fetch 刷新并重新分区Advanced →「Staged changes」经典行为、Tree 视图、无分区jj 仓库行为零变化。8. 实现代价与影响面源码结构视角从当前源码结构看这是一次「沿既有接缝的增量」服务端/共享层 6 个左右小 casediff 执行、指纹、文件内容、暂存门控、agent 上下文、配置默认加上一个 payload sidecar 与一个 fetch 端点客户端新增 Sections 面板组件、Sections/Tree 切换、页脚 Advanced 入口与滞后横幅。注释、反馈导出、已阅同步、新鲜度轮询与 diff 查看器全部零改动——它们本就作用于单一 patch 与扁平文件列表sections分组只影响左面板呈现diff 查看器依然消费扁平DiffFile[]SPIKE 与 git-graph spike 的共同发现。潜在影响默认体验对既有用户全员改变但旧行为离页脚一次点击之遥显式配置默认被尊重。baseBehindRemote会随每个 diff payload 与新鲜度探针携带客户端据此点亮/熄灭横幅review.ts#L2228-L2231保证 Fetch 后横幅即时收敛。赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐ChatGPT桌面应用窗口还原默认大小恢复窗口的默认尺寸ChatGPT桌面应用窗口还原默认大小恢复窗口的默认尺寸 你是否曾不小心将ChatGPT桌面应用窗口调整到不合适的大小导致操作不便本文将详细介绍如何快速恢桌面应用AI 应用BambooAI重新定义对话式数据发现与分析的终极Python库BambooAI重新定义对话式数据发现与分析的终极Python库 BambooAI是一款由语言模型LLMs驱动的Python库专为对话式数据发现与分析设Watchman的since命令详解高效追踪文件变更Watchman的since命令详解高效追踪文件变更 什么是Watchman的since命令 Watchman是一个由Facebook开发的文件监控服务它的后端开发工具上一篇GHelper全面重构华硕笔记本的智能轻量级控制革命下一篇5分钟完全指南用ModAssistant轻松管理Beat Saber模组创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考