企业官网建设流程全解析

Plannotator 的 Plan 文档评审与 Code Review 产品原本是桌面优先的多窗格工作区，通过 Tailscale 暴露到 iPhone/iPad 后暴露出「可达性已解决、移动性未解决」的根本矛盾。本篇以adr/research/synthesis-mobile-feedback-triage-20260812.md为核心，结合SPIKE-mobile-web-compatibility研究、Phase 1/2 规格与packages/ui、packages/editor、packages/review-editor源码，系统讲解 Plannotator 如何把物理设备评审反馈转化为可执行的阶段序列（Phase 1C → 2A → 2B → 3），如何在不破坏桌面偏好的前提下落地紧凑触控 Shell（compact touch shell），以及 44 px 触摸目标、可见视口对话框、会话级 diff 样式等关键机制的真实实现。读完本文，你将掌握 Plannotator 移动改造的分诊方法论、各阶段边界与验收门、以及源码级证据对应的实现缝隙（implementation seam），可直接用于二次开发或移植同类 touch-first 改造。

背景：Tailscale 解决了可达性，但没有解决移动性

SPIKE 研究（SPIKE-mobile-web-compatibility-20260812.md）在基线ef49c701c23b867cec2a5d78343813ba89d2a025（v0.27.1）上通过双 Agent 审计得出核心结论：

• Tailscale 只负责把本地同一个单文件 React 应用暴露到 tailnet，不会选择任何移动端渲染路径或路由；
• Plan/文档阅读是「视觉上响应式、但尚未触控优先」——控件高度普遍只有 17–28 px，触屏设备会展开每个工具条标签；
• Code Review 是「被压缩进窄视口的桌面组合」——390 px 宽度下默认 256 px 文件树只给 Pierre diff 留下 134 px，再打开固定 288 px 右侧栏只剩 102 px；
• Guided Review 是现存最强的移动产品原型——它已把变更集变成有序叙事流、隐藏文件树、在手机宽度下堆叠章节并复用真实 Pierre diff。

而最严重的兼容性问题不是视觉：多文件/文件夹注解在lg以下被阻断（MOB-001）。文件夹空状态提示用户「从侧边栏选择文件」，但SidebarTabs与SidebarContainer在该宽度下是hidden lg，评审者根本无法选中文件。

从源码结构看，Plan/文档应用根组件为 packages/editor/App.tsx，Review 应用根组件为 packages/review-editor/App.tsx，两者共用packages/ui的组件与 token，diff 渲染依赖 Dockview 与@pierre/diffs。Vite +vite-plugin-singlefile将 JS/CSS/字体/资源与 Pierre 高亮 worker 全部内联进单个 HTML，由 Bun 服务器常驻内存并按 SPA 返回——Tailscale 不改变这套 API 与渲染契约（见 apps/hook/vite.config.ts、packages/server/index.ts）。

决策与推进顺序：把「共享机制安全」与「信息架构」分开

综合文档给出的核心决策是：物理设备评审已充分，不必让评审者重跑 Phase 1B 的 composer 检查清单。Safari 阶段失败是阻断性缺陷，而最终的 iPhone 通过确认了其修正。后续工作严格按下列顺序推进：

1. Phase 1C —— 共享触摸与对话框契约：在不重排任何产品表面的前提下，完成小规模、能力门控（capability-gated）的基础设施。
2. Phase 2A —— 移动 Code Review Shell 与到达：用「一个主手机表面 + 瞬态次级导航/上下文」替换被压缩的桌面组合。
3. Phase 2B —— 移动 Plan Shell 与导航：削减持久 Plan chrome，恢复被阻断的文件夹/多文件路径，稳定编辑与完成控件。
4. Phase 3 —— 触摸选择与注解语义：把多块 Plan 选择与多行 Pierre 选择作为独立交互原型并验证。

这个顺序并非单纯按产品重要性排序，而是先分离共享机制安全与信息架构，再分离布局与更困难的选择语义——这样每个评审门都清晰可理解，也防止「手机端临时绕过方案」反过来污染桌面偏好（例如在手机上改写了桌面保存的 Split/Tree 偏好）。

已关闭或已在并行的区域：哪些问题不用再改

综合文档维护了一张「处置表」，标明哪些项已经工作、关闭或保留：

Phase 2B 物理反馈：一个紧凑文档-chrome 契约

第一次 2B.1 手机评审揭示：仅恢复文件夹导航不够——选中文件后，Plan 仍暴露整个桌面注解矩阵外加 Wide / Focus / Edit 微链接；评审者还要求 Plan 完成决策遵循 Code Review 模式移入 Options。这些反馈被分配给 2B.2，并以一个紧凑文档-chrome 契约实现：

• 到达时只显示一个Annotate · <method>入口，而不是 Select / Pinpoint 与 Markup / Comment / Redline / Label 并列；
• 紧凑定位始终通过 Markup 语义呈现，Select text 与 Pinpoint 是仅有的两个前置采集选择；
• 紧凑方法选择仅限会话内生效，保护桌面偏好；
• Wide 与 Focus 从紧凑触摸中完全移除；
• Edit 移入 Options，激活时获得常规流程的 Save / Done / Cancel 行；
• 终端决策移入 Options，同时调用完全相同的既有处理器与警告路径。

Phase 2B.2 明确不声明任何 Phase 3 的多块/多行选择语义——Pinpoint 单块定位与原生拖拽选择仍是 2B.2 物理门的已知输入基础。

2B.1 还暴露了一个状态转换缺陷并已修复：文件选择关闭了导航器，随后异步链接文档激活重放了桌面「打开 Files 侧边栏」行为，把紧凑导航器重新唤醒，导致可见闪烁并迫使评审者先按 X 才能看到选中文档。现在紧凑激活抑制该桌面端副作用——选中文件名与文档正常渲染且导航器保持关闭，而细指针桌面保留原有侧边栏激活行为。规格文档 mobile-plan-shell-phase2b-20260813.md 记录了后续的Opening…标记与加载失败重试语义。

分诊矩阵：Now / Next / Later 的归属逻辑

综合文档用一张矩阵把全部 MOB 编号按「修复单元」重新分组，原则是：属于同一失效模式的条目一起做，而不是按面板逐个修补。

严重度定义（来自 SPIKE）：P0 为受支持的移动旅程无法完成；P1 为核心评审/反馈不可用、不可靠或危险易错；P2 为实质摩擦、噪音、无障碍风险或可避免的低效；P3 为打磨/一致性/前瞻性问题。置信度分为 High（渲染证据与源码一致）、Medium（源码支撑的平台风险）、Low（未测试概念）。

Phase 1C 落地：44 px 触摸目标、可见视口对话框与能力门控

Phase 1C 是「下一个立即实施」的检查点，其结果目标是：共享按钮与共享对话框关闭控件在触摸下物理安全；共享对话框保持在可见 Safari 视口内可到达；细指针桌面几何不变。

范围与边界

范围内：

• 引入共享--pn-touch-targettoken 与data-pn-touch-target标记；
• 对两个既有共享按钮原语与共享对话框关闭控件应用粗指针 44×44 最小命中区；
• 将共享对话框原语绑定到 1A/1B 建立的可见视口与安全区契约；
• 在触及的原语中，将仅悬停效果门控到可悬停的细指针；
• 提供即时、克制的按下反馈与 reduced-motion 路径；
• 只转换足以证明契约的代表性共享对话框；
• 验证 iPhone 与 iPad 几何，包括 iPad 混合「触摸 + 指针」。

显式排除：不批量扩大每个手写 Plan/Review 工具条控件；不改 Plan toolstrip、底部操作栏或移动导航；不改 Code Review 面板、Dockview、header、Guide 或 diff 组合；不基于视口写 Split/Unified 偏好；不改 Pierre、DiffViewer、行选择或建议编辑；不引入新 sheet 系统或视觉语言。

源码级实现缝隙

综合文档给出的预期源码边界与实际仓库一致：

• packages/ui/theme.css：定义--pn-touch-target: 2.75rem（即 44 px），以及--pn-safe-top/right/bottom/left四个env(safe-area-inset-*)变量；.pn-app-viewport以var(--pn-viewport-height, 100vh)作为根高度并消费顶部/内联安全区；.pn-viewport-bounded把覆盖层高度限制为「可见视口高度 − 安全区」；html:has([data-pn-compact-touch-layout='true']) [data-pn-touch-target]与图标态[data-pn-touch-target-icon]分别强制最小块/内联尺寸；按下态:active提供即时反馈且不会遗留粘性 hover。
• packages/ui/components/ui/button.tsx 与 packages/ui/components/core/button.tsx：两个既有共享按钮原语默认采纳触摸目标契约。
• packages/ui/components/ui/dialog.tsx：共享对话框关闭控件套用触摸契约，并居中于可见视口 + 安全区舞台内。
• packages/ui/components/ConfirmDialog.tsx：迁移到该共享原语，同时保留不可点透的 backdrop 与 Command/Ctrl+Enter 行为，并有意改善桌面无障碍——包含焦点、优先聚焦安全的 Cancel、恢复打开控件。

「如果正确的 44 px 目标破坏了某行密集的手写控件，就为其所属表面阶段记录问题，而不是引入未文档化的紧凑特例」——这是贯穿整个改造的纪律：不设隐藏逃生舱。

几何验证证据

响应式浏览器预检未发现水平溢出，真实 Plan 确认弹窗在 320×568、390×844、390×500 键盘高度、844×390 手机横屏、768×1024 iPad 竖屏与 1180×820 iPad 横屏下都保持在 16 px 可见舞台内边距中。1280×720 细指针下，既有 Plan header 控件保持 138.17×28 px 与 92.54×28 px，与改前测量一致。文档明确声明：浏览器模拟不暴露粗输入设备，因此 44×44 命中区、按下态与混合 iPad 路径是有意的物理设备验收项，而非声称的浏览器结果。

1C 联合评审门

检查点就绪标准包括：代表性按钮与对话框关闭命中框在粗指针下 ≥44×44 且不重叠；共享对话框在 320×568、390×844 与键盘缩减高度下关闭控件与主操作仍可到达；按下反馈出现在 touch-down 而无粘性 hover 样式；reduced-motion 与硬件键盘关闭仍可用；iPad 横竖屏及触摸+触控板路径可用；桌面截图与计算几何在细指针下无布局变化；生产 Plan/Review 构建、聚焦测试与 typecheck 通过。评审者只应做一个简短物理设备抽查，而非又一次端到端评审。

Phase 2A 预览：让评审产物而非桌面工作区拥有手机视口

Phase 2A 是第一次结构重设计，其任务是把评审产物变成手机视口的主人。

固定原则

• 手机上一次只呈现一个全宽主表面；
• Tree 仍是最佳新用户桌面默认值，移动展示决策永不覆盖它；
• 文件导航、PR 上下文、注解、AI 与 Agent 变为瞬态手机表面，而不是挤压 diff 的 flex 兄弟；
• 空 PR 段落不为宣布「缺席」而渲染结构；
• 手机 header 只暴露位置、导航与一个上下文动作；仅桌面控件移入渐进披露；
• 手机友好的 Unified 呈现可以是会话/设备级覆盖，但不得改写用户保存的桌面 Split 偏好；
• Guide 与 All Files 是两个最强的移动起点观察，入口决策应通过工作原型与物理评审做出，而非响应式截图推断。

2A 评审门与实施检查点

实施前需用同一 GitHub PR 对比至少两个手机组合：artifact-first 的 All Files / Unified 到达，与 Guide-first 到达（含直达原始 diff 的路径）。选中组合必须保留桌面行为、在不收窄产物前提下让文件/PR 上下文可达、保持目的地决策完全可见，并支持完整的单行评论与 approve/send 旅程。

首版实现在codex-mobile-phase-2a-review-shell分支完成，但首次物理 iPhone 评审未通过阶段门：它确认了 artifact-first 方向，却暴露了响应式 Chromium 无法复现的 review chrome 与 Safari-stage 问题。迭代保留了同一 artifact-first 选项，同时让既有 Guided Review takeover 可从紧凑 Options 菜单直达，从而可对比两种阅读组合。

紧凑 Shell 的激活条件是视口宽度 ≤1024 px 且设备暴露粗指针（窄细指针桌面窗口保留桌面工作区），具体行为包括：

• PR 与本地评审以全宽 All Files 到达，而非在 diff 旁打开树或 PR 概览；
• Unified 是初始会话呈现，但手机上更改仅限会话，永不写保存的桌面 Split/Unified 偏好；
• Git status、Tree、Commits、PR 上下文与文件导航共用一个全舞台瞬态导航器，选择目的地后关闭；
• 注解、AI 与 Review Agents 占用独立全舞台瞬态表面，而非固定 flex 兄弟；
• header 是 52 px 三列行：导航、几何居中的评审位置与 Options；目的地、Exit、Send/Post、Approve、Guide 与次级工具移入菜单；
• 33 px dock 条在紧凑触摸下只含标签（此前 44 px 齿轮目标物理溢出到第一个文件头）；
• 紧凑文件头是 44 px 行，只含折叠、路径、状态与变更数；Viewed、Git Add、语义/调用流徽章、实验性 Edit 与 Open-in-app 留在桌面；
• 目的地 coachmark 不在紧凑触摸挂载（目的地决策已直接进入 Options）；
• 平台提交对话框使用共享可见视口 Dialog，到达时不弹软件键盘，作者文本保持 16 px，长恢复详情可滚动，终端操作固定；
• 展开的评审 composer 空闲时上限 28 rem，仅按可见键盘视口需要展开；
• PR overview 用 Summary/Comments 作为互斥紧凑区域，空讨论完全不渲染 Comments 区域（顺带消除了一个空结构面板，改善了桌面）。

滚动架构的两次试错

最值得记录的是page-scroll proxy 的失败：紧凑端页面滚动代理在物理 iPhone 评审中把文档推进而 Pierre 虚拟窗口停住，产生冻结 diff 后跟大片空白，且粘性 review stage 保留了不透明 Safari 顶部扩展；该代理被立即移除以恢复可靠文件滚动。评审者随后评价恢复的 Pierre-owned scroller「much, much better」，连续文件滚动恢复工作，整体应用行为「pretty good」，Safari 顶部 chrome 行为被接受为延后的隔离实验而非再次渲染器迁移的理由。文档明确指示：Phase 2B 不得重开被否决的滚动架构；未来任何 document-native Pierre Virtualizer 实验必须隔离，并凭完整交互对等 + 物理测试赢得晋级。

文件名问题的收尾是：把硬性的 14–32 字符 basename 截断换成 Diffshub 风格的全路径 + 前置省略号处理，这是唯一剩余的微门。

2A 物理评审脚本（可复用验收清单）

通过 Tailscale 在 iPhone（有条件再上 iPad）打开同一 GitHub PR：

1. 确认到达是 All Files、全宽、Unified，树与 PR 面板未预先打开；连续滚动多个文件，不得出现冻结虚拟窗口、大空白尾部、回跳开头或触摸滚动丢失；
2. 确认手机 header 只有 Review 导航、居中评审位置与 Options；在 Options 中验证目的地、Exit、Send/Post（有反馈时）与 Approve 可达；
3. 确认 dock 标签行没有与第一个文件重叠的 cog/折叠簇；紧凑文件头只显示折叠、路径、状态与变更数；
4. 打开 Review 导航，在文件、All Files 与 PR overview 间移动，每次选择都回到全宽主表面；
5. PR overview 中空讨论无 Comments 控件；有讨论时 Summary/Comments 切换不分割屏幕；
6. Options → Guided Review，读一章后返回原始 diff；
7. 从 Options 打开 Annotations（及可用时的 AI/Agents），确认表面替换而非挤压 diff，然后关闭；
8. 选中一行代码打开评论；聚焦 textarea 前展开的 composer 应是合适的卡片高度而非整屏；聚焦后让位键盘、文本保持 16 px、终端操作可达；保存评论后打开 Post Comments 或 Approve；
9. 旋转一次，确认无 rail 或先前瞬态表面重现；桌面刷新后 Tree 与保存的 diff 样式不变。

范围累积与多行触摸选择在本门中仅作观察，仍属 Phase 3。

Phase 2B.1：Plan 阅读优先的紧凑前台状态

Phase 2B.1 在codex/mobile-phase-2b-plan-shell分支实现，保留 Phase 1 的文档滚动主人，引入会话级紧凑前台状态而非复用桌面 rail 布尔量：

• 即使记住的桌面右侧面板已打开，紧凑触摸也先到达产物；注解与 AI 按钮/面板不进入紧凑到达组合，其专属前台状态属于 2B.3；
• 前导Plan披露打开一个全舞台导航器，受观察可见视口与安全区约束，包含 focus/Escape，显式关闭恢复触发器，标签与目的地行使用 44 px 触摸目标；
• 导航器复用SidebarContainer、TableOfContents、FileBrowser、VersionBrowser、MessagesBrowser与ArchiveBrowser——桌面保留粘性/可调呈现，没有第二套浏览器模型；
• Contents、文件、消息、归档与链接文档目的地返回产物；标签切换留在导航器内；文件加载监听紧凑 Files 状态而不写sidebar.activeTab，手机上打开 Files 不改变桌面侧边栏状态；
• 文件夹注解空状态不再指示手机用户找隐藏侧边栏，而是提供触摸安全的Choose a file动作打开 Files；
• 紧凑触摸下 Plan header 保持普通页面流，无固定/粘性移动边缘条、Safari 滚动代理、选择语义、服务器、Tailscale 或 Pierre 代码改动。

聚焦证据覆盖前台 reducer、紧凑到达桌面面板门、header 披露、共享导航器桌面/覆盖层呈现、可见视口与触摸 CSS、焦点与标签行为、文件夹空状态。1440×900 细指针浏览器控制保留了 48 px 粘性 header、240 px 粘性 Contents rail、288 px 右侧面板与零根/主水平溢出。文档再次强调：响应式 Chromium 不暴露粗指针，因此物理 Safari 才是权威紧凑检查点。

2B.1 物理评审脚本

1. iPhone 打开文件夹检查点：到达应显示空产物与Choose a file，而非侧边栏或 Ask AI；
2. 点Choose a file选任意 fixture，确认导航器关闭到所选文档；再点Plan回 Files 选第二个文件，重复同样的关闭行为；
3. Plan→ Contents 选标题，确认回到同一文档该标题处且不改变 Safari 接受的页面滚动；
4. 用关闭按钮关闭导航器、重开并旋转一次，无右 rail、AI 面板或陈旧导航器挤压产物；
5. 单独打开普通文档检查点：文档——而非 Ask AI、注解或导航——必须是第一表面。

本门只评导航与到达；持久注解 chrome、直接编辑控件、辅助表面、完成与多块选择分别属于 2B.2、2B.3 与 Phase 3。

为什么选择语义不能捆绑进布局阶段

用户的 Plan 反馈确立了：Pinpoint 目前是唯一可靠的触摸路径——点按打开其上下文工具栏，Comment 再打开 composer；普通 Select 点按无反应，原生拖拽选择唤起 iOS Copy / Find Selection 菜单，Plan 与 Code Review 都没有可信的多目标累积方式。

综合文档明确这不是命中框 bug，而是未解决的姿势与状态模型。选择阶段必须原型化显式累积、可见范围状态、取消/撤销、滚动共存与辅助技术行为；Review 选择还必须保留 Pierre 的行映射与桌面鼠标范围选择。把它当作布局 PR 内的附带工作，会让两个变更都更难评审、更容易回归。

桌面保留契约：每个阶段的不变量

所有阶段始终维护以下不变量：

• 移动呈现状态是临时的或设备/会话作用域的；
• 桌面 Tree/Split/面板偏好永不因手机宽度被改写；
• 细指针几何与键盘快捷键保持现状，除非阶段明确点名某个桌面缺陷；
• 共享变更是能力门控的，并在严格的@plannotator/uiconsumer 中测试；
• 在物理与桌面对等确认前，不删除任何现有工作表面。

这些不变量在源码中有直接对应：useCompactTouchLayout使用(max-width: 1024px) and (pointer: coarse)媒体查询（packages/ui/hooks/useIsMobile.ts），特意用pointer: coarse而非any-pointer，避免触屏笔记本被误判；useViewportEnvironment通过 CSS 自定义属性发布可见视口几何、以单动画帧合并事件、引用计数消费者并恢复既有属性（packages/ui/hooks/useViewportEnvironment.ts）；packages/review-editor/App.tsx 中的compactDiffStyle是会话级 state，effectiveDiffStyle = isCompactTouchLayout ? compactDiffStyle : diffStyle，从实现上保证了手机上的 Unified 切换不会写回持久化 diff 偏好。

阶段全景与验收方法论要点

综合文档把整个移动改造组织为「先机械安全、再信息架构、再布局、最后选择语义」的四段式，每段都有独立的物理设备门。贯穿始终的方法论（源自 SPIKE）包括：冻结基线并记录 commit/版本；先映射可达性再评判响应式；按完整旅程而非单屏审计；使用设备与输入矩阵（320×568 手机竖屏、390×844 主审计、844×390 横屏、768–1194 iPad、≥1280 桌面控制）；分离「Observed/Measured/Source-confirmed/Platform risk/Design hypothesis」五级证据；以document.scrollingElement让正文滚动收起 Safari 双端控制区；物理设备证据优先于桌面模拟，冲突时修订 brief 再继续。

无论你关注的是 Code Review 的 artifact-first Shell、Plan 的阅读优先前台状态，还是 44 px 触摸契约与 16 px 输入防聚焦缩放，本仓库的packages/ui/theme.css、packages/ui/components/ui/*、packages/editor/App.tsx、packages/review-editor/App.tsx及其配套.mobile.test.tsx测试（如 packages/ui/components/ui/mobile-foundation.test.tsx、packages/ui/components/sidebar/SidebarContainer.mobile.test.tsx、packages/editor/components/AppHeader.mobile.test.tsx）都是可直接追踪的实现与回归证据。物理 Safari 的权威性、「无隐藏紧凑特例」「桌面偏好只读」三条纪律，则是这套阶段推进能被反复验证而不塌方的根本原因。