web-terminal/docs/PLAN_IOS_IPAD.md

PLAN_IOS_IPAD.md — iPad 适配（自适应布局，非分叉）

落地方案文档。目标：让已完成的 iPhone 客户端（PLAN_IOS_CLIENT.md，P0+P1+P2 已交付，已合入 develop）原生适配 iPad——大屏分栏、双向布局、指针/硬件键盘，而不分叉出第二套 UI。 拓扑决策：单一代码库 + size-class 自适应——NavigationSplitView 在 regular 宽度（iPad 全屏/大分屏）给 sidebar+detail，在 compact 宽度（iPhone、iPad Slide Over/小分屏）自动退化为现有 stack。iPhone 行为字节级不变。 状态：已交付并合入 develop（T-iPad-1…4 全部落地；T-iPad-5 验收 PASS_WITH_FINDINGS，4/4 findings 已修，真机项 DEFERRED）。 逐任务状态见 §5 各任务标题上的方框；Steps 里的 [ ] 是原始规格清单，不是状态（执行记录在 PROGRESS_LOG.md）。 2026-07-30 由 ios-completion 收尾波按源码核对：Wiring/{AdaptiveRootView,SplitRootView,LayoutMode}.swift、 Components/TerminalContextMenu.swift、Screens/ProjectsLayout.swift 与 LayoutPolicyTests/SidebarSelectionTests/ KeyBarVisibilityTests/TerminalContextMenuTests/ProjectsLayoutTests/ProjectsLayoutUITests 均在树内； project.yml 三个 target 的 TARGETED_DEVICE_FAMILY 均为 "1,2"；ios.yml 有 iPad 单测腿与 iPad UI-test 腿。 本文是 iPhone 计划之上的布局适配层，不改协议/会话模型/纯逻辑包；沿用 PLAN_IOS_CLIENT.md 的 §3 契约、§4 工程标准、§5 安全模型、§6 并行规则。冲突以 iPhone 计划为准。 G1 日志铁律：PROGRESS_LOG.md 由 orchestrator 独写；被派 subagent 不写 LOG，在返回消息末尾附可粘贴条目。

---

0. 目标与范围

做什么

在 iPad（iPadOS 17+）上把「口袋驾驶舱」升级为「桌面级驾驶舱」，利用大屏做手机做不到的事：

• 分栏常驻：左 sidebar = 会话列表（+ Projects 入口），右 detail = 终端 + gate/digest 叠层——不用来回 push/pop，一眼看全 + 直接介入。
• 终端更宽：iPad 全屏能放下接近桌面的列数，直接缓解「宽桌面 + 窄手机同看一个全屏 TUI 折行成竖条」的多设备张力（见 PROGRESS_LOG 该条）——iPad 自己就是宽屏 writer。
• 双向布局：横竖屏、Split View、Slide Over、Stage Manager 尺寸变化全程 size-class 自适应，绝不写死方向。
• 硬件键盘为一等公民：iPad 常接键盘——现有 UIKeyCommand 全键位复用；软键盘 KeyBar（inputAccessoryView）在有硬件键盘时可隐、无则保留。
• 指针/悬停：iPadOS 指针 hover 高亮、右键（次要点击）上下文菜单（kill/新建/在 cwd 开）。

不做（本期范围外）

• 多窗口 / 多场景（UISceneConfiguration 多实例、拖拽会话到新窗口）：iPad 能开两个终端并排是诱人的，但涉及场景生命周期重构 + 每场景独立 SessionEngine，单列一期（见 §7 后续）。本期 = 单场景自适应分栏。
• Stage Manager 外接显示器专属布局：本期只保证 Stage Manager 下尺寸变化不崩、布局自适应；不做外接屏专属多窗排布。
• Apple Pencil、拖放文件进终端、Mac Catalyst：非目标（同 iPhone 计划 §0）。
• 纯逻辑包改动：WireProtocol/SessionCore/HostRegistry/APIClient 与设备无关，一行不改（若发现某常量隐含 iPhone 假设 → 回对应包 owner，不在本计划直改）。
• 服务器 / public/ / src/：零触点（iPad 只是又一个说同一协议的客户端）。

关键约束：iPhone 零回归（硬性）

任何自适应改动必须先满足 compact 宽度 == 现有 iPhone 行为。每个任务的验收都含一条「iPhone 模拟器全套件仍绿 + 目视无变化」。self-check：compact size class 下走的代码路径应与改动前逐帧一致（分栏只在 regular 宽度激活）。

---

1. 整体架构 / 适配策略

                       size class 驱动的单一根视图（AdaptiveRootView）
        ┌─────────────────────────────┴─────────────────────────────┐
   horizontalSizeClass == .compact                 horizontalSizeClass == .regular
   （iPhone / iPad Slide Over / 小分屏）             （iPad 全屏 / 大分屏 / Stage Manager 大窗）
        │                                                  │
   现有 NavigationStack                            NavigationSplitView
   列表 → push 终端（字节级不变）                    ├ sidebar: 会话列表 + Projects section
                                                   └ detail : TerminalContainerView（gate/digest 叠层）
        └───────────────── 共享同一 AppCoordinator / 同一 SessionEngine ─────────────────┘
                    隐私遮罩（ZStack 顶层，!= .active）· scenePhase · deep link 全部设备无关，原样复用

为什么自适应而非 iPad 分叉：horizontalSizeClass 是同一 App 内运行时可变量（iPad 拉出 Slide Over 立刻从 regular 变 compact）——分叉两套 UI 无法应对同一次运行内的尺寸切换，且双倍维护。自适应 = 一套代码、一处 size-class 分支、compact 分支就是现有已测代码。

为什么 detail 复用 TerminalContainerView 不动：终端 + gate + digest 的组装（T-iOS-15/24 的 TerminalContainerView）与它挂在 push destination 还是 split detail 无关——只换外层容器，内容零改。SessionEngine 单活 WS、latest-writer-wins、隐私遮罩、生命周期全部设备无关，直接复用。

列宽收益（自动，非新逻辑）：终端列数由 SwiftTerm 的 sizeChanged 从其视图宽度 + 字号算出（T-iOS-11 已实现），detail 面板越宽 → cols 越多 → 越接近桌面宽度。无新代码，是分栏的自然结果。

依赖方向：iPad 适配全部落在 App 胶水层（ios/App/WebTerm/**）；纯包不动；自适应「决策」抽成纯函数（LayoutMode 之于 size class，仿 PrivacyShadePolicy 先例）以便单测，SwiftUI 布局本身靠模拟器目视 + XCUITest。

---

2. 目录结构（新增/改动）

ios/App/WebTerm/
├── Wiring/
│   ├── RootView.swift              # 改：抽 compact 分支为子视图，加 regular 分支入口（T-iPad-2）
│   ├── AdaptiveRootView.swift      # ★新：size-class 分支 + LayoutMode 决策消费（T-iPad-2）
│   ├── SplitRootView.swift         # ★新：NavigationSplitView（sidebar+detail）（T-iPad-2）
│   ├── LayoutMode.swift            # ★新：纯函数 size class → LayoutMode（.stack/.split）（T-iPad-2）
│   └── AppCoordinator.swift        # 改：sidebar 选中态 ↔ 现有 terminal/projects 路由桥（最小增量）
├── Screens/
│   ├── SessionListScreen.swift     # 改：sidebar 语境下的选中高亮 + Projects section（自适应，compact 不变）
│   └── ProjectsScreen.swift        # 改：regular 宽度下作为 sidebar section / 多列网格（compact 仍是 sheet）
├── Components/
│   ├── KeyBar.swift                # 改：硬件键盘在场时可隐（T-iPad-3）
│   └── TerminalContextMenu.swift   # ★新：指针右键/长按上下文菜单（kill/新建/cwd 开）（T-iPad-3）
├── project.yml                     # 改：TARGETED_DEVICE_FAMILY "1,2" + iPad 方向/plist（T-iPad-1）
└── WebTermTests/ , WebTermUITests/ # 各任务的测试

ios/Packages/** 零改动。

---

3. 契约（自适应决策的可测核）

// LayoutMode.swift — 纯函数，唯一 size-class 决策点（仿 PrivacyShadePolicy）
public enum LayoutMode: Equatable { case stack, split }

public enum LayoutPolicy {
    /// regular 宽度 → split（sidebar+detail）；compact → stack（现有 iPhone 路径）。
    /// 唯一判据，禁止在视图里散落 sizeClass 分支。
    public static func mode(horizontalSizeClass: UserInterfaceSizeClass?) -> LayoutMode
}

// SidebarSelection — split 模式下 sidebar 选中态（与现有 AppCoordinator 路由等价映射）
enum SidebarItem: Hashable { case session(UUID), newSession, projects }

隐私遮罩、scenePhase、deep link、SessionEngine 契约沿用 iPhone 计划 §3，不重定义。

---

4. 工程标准

沿用 PLAN_IOS_CLIENT.md §4 全部（TDD 强制、不可变、文件 ≤400 行、函数 <50 行、早返回、无魔法数字、系统边界验证、显式错误、conventional commits、覆盖率仅计 4 个纯包）。追加两条 iPad 专属：

• size-class 分支只出现在一处（LayoutPolicy）；视图内严禁散落 if sizeClass == …。
• iPhone 零回归是每个任务的验收前置（compact 路径 == 改动前）。

---

5. 任务清单

状态图例 [ ]/[~]/[x]/[!] 同 iPhone 计划。ID 稳定：T-iPad-N。测试框架 Swift Testing；XCUITest 仅 UI happy path。

W0 · 可安装性（串行，先行）

T-iPad-1 · device family + iPad plist/方向 [x] · ~0.5 pd

• Owns: ios/project.yml（device family、iPad 方向、必要 plist）、.github/workflows/ios.yml（加 iPad 模拟器测试腿）
• Depends: 无
• Steps(测试先行):
  • TARGETED_DEVICE_FAMILY 由 "1" 改 "1,2"（project + 各 target level——注意 XcodeGen target 默认覆盖，见 iPhone 计划 W5 finding，逐 target 显式设）
  • iPad 方向键全开（UISupportedInterfaceOrientations~ipad 含 Portrait/Landscape/UpsideDown）；iPhone 方向键不动
  • ATS 五段 CIDR / usage description 原样（设备无关，复核仍在）
  • xcodegen generate → 拆构建产物 plist 断言 UIDeviceFamily [1,2]
  • ios.yml 加一条 xcodebuild test 腿跑 iPad 模拟器（iPad Pro 11" 或 iPad (A16)）
• Accept: iPad 模拟器 xcodebuild build 通过、空跑现有全套件绿（此刻仍是 iPhone 布局放大，不崩）；产物 plist [1,2]
• 安全注: device family 放开后 T-iPad-5 的 ipa 核对须覆盖 iPad 产物（capability↔usage 一一对应不变）

W1 · 自适应导航壳（核心）

T-iPad-2 · AdaptiveRootView + NavigationSplitView + LayoutPolicy [x] · ~2 pd

• Owns: Wiring/{AdaptiveRootView,SplitRootView,LayoutMode}.swift（新）、Wiring/RootView.swift（改：现有 stack 抽成 StackRootView 子视图供 compact 复用）、Wiring/AppCoordinator.swift（改：sidebar 选中 ↔ 路由最小桥）、对应测试
• Depends: T-iPad-1
• Steps(测试先行, RED) — LayoutPolicyTests + SidebarSelectionTests:
  • LayoutPolicy.mode(.compact) == .stack、.mode(.regular) == .split、.mode(nil) == .stack（未知按最保守 = 现有路径）
  • SidebarItem ↔ AppCoordinator 路由等价：选 .session(id) == 现有 open(id)；.newSession == open(nil)；.projects == 现有 projects 呈现——同一 coordinator API，split 只是另一个触发面（断言不新增会话生命周期路径）
  • compact 分支渲染的视图树 == 改动前 RootView（快照/结构断言：隐私遮罩仍 ZStack 顶层、scenePhase/deepLink/sheet 全在）
  • size class 从 regular→compact 切换（iPad 拉 Slide Over）时选中态保持、终端不重建（复用 T-iOS-29 的 .id(controller.id) 稳定性，断言 controller 不换）
• Steps(实现, GREEN):
  • AdaptiveRootView 读 @Environment(\.horizontalSizeClass) → LayoutPolicy.mode → 选 StackRootView（现有）或 SplitRootView
  • SplitRootView = NavigationSplitView { sidebar } detail { TerminalContainerView 或空态 }；sidebar = SessionListScreen（选中绑定）+ Projects section 入口；detail 空 = 「选择或新建会话」占位
  • 隐私遮罩/scenePhase/deepLink/task(bootstrap) 上提到 AdaptiveRootView（两分支共享，绝不重复布线）
• Accept: iPad 模拟器横竖屏 + Split View 拉入拉出全程分栏/退栈自适应无崩；iPhone 模拟器全套件绿 + 目视逐屏无变化；LayoutPolicy 覆盖率 100%
• 安全注: 隐私遮罩必须仍是两分支共同的 ZStack 顶层——split detail 的终端字节同样要被 != .active 遮住（新增一条 iPad 遮罩目视验收：Stage Manager 切走 → detail 终端被遮）

W2 · 逐面适配（并行，文件互斥）

T-iPad-3 · 终端面板：KeyBar 自适应 + 指针上下文菜单 [x] · ~1 pd

• Owns: Components/{KeyBar,TerminalContextMenu}.swift、Screens/TerminalScreen.swift（增量）、测试
• Depends: T-iPad-2 · Parallel-safe: T-iPad-4
• Steps(测试先行):
  • KeyBar 可见性纯谓词：GCKeyboard.coalesced != nil（硬件键盘在场）→ 默认隐；无 → 显；用户可手动切（谓词单测，硬件态注入）
  • 上下文菜单（右键/长按）项 = {在 cwd 开新会话、kill、复制选区}——动作复用现有 OpenRequest/killSession 通道（断言不新增网络路径；kill 仍带 Origin）
  • 指针 hover 高亮不改字节流（纯 UI）
• Accept: iPad 接键盘时 KeyBar 自动隐、去键盘复现；右键菜单在 iPad 生效；iPhone 无硬件键盘时 KeyBar 行为不变
• 安全注: 上下文菜单的 kill/开会话是既有 G/RO 通道的又一触发面——测试名标「复用 APIClient，无绕过」

T-iPad-4 · Projects/Timeline/sheet 大屏化 [x] · ~1 pd

• Owns: Screens/ProjectsScreen.swift（增量）、Projects/Timeline 呈现方式（regular 下 .sheet → 列/.presentationDetents 或 sidebar section）、测试
• Depends: T-iPad-2 · Parallel-safe: T-iPad-3
• Steps(测试先行):
  • Projects 网格列数随宽度自适应纯函数（compact=1 列现状、regular=多列）——列数决策单测
  • regular 宽度下 Projects 作为 sidebar section 或 detail 列（compact 仍走现有 sheet，分组/收藏/prefs 往返逻辑零改——只换容器）
  • Timeline/其它 sheet 在 iPad 用合适 detent/尺寸不占满全屏
• Accept: iPad 上 Projects 多列、Timeline 合理尺寸；iPhone 全部走原有 sheet 路径不变；prefs 未知键往返（T-iOS-38 不变量）回归绿

W3 · 验收（report-only, G4）

T-iPad-5 · iPad 验收 + iPhone 回归 + 安全核对 [~] · ~0.5 pd

• 已执行：模拟器侧 PASS_WITH_FINDINGS（iPhone 16 / iPad Pro 11 双套件绿，iPhone 零回归硬门守住），4 个 findings（2 MED / 2 LOW）由 orchestrator 修完 4/4；iPad 分栏 sidebar+detail 截图确认。
• 缺口：① 真机 iPad（分栏手势 / 硬件键盘全键位 / 指针 hover 右键 / Stage Manager）DEFERRED，手工清单在 PROGRESS_LOG.md；② iPad happy-path XCUITest 接受推迟（split 选中逻辑已由 SidebarSelectionTests 覆盖，单跑 7–11 min 且脆）；③ release ipa 层核对未做（免费个人 team 无分发通道）——与 T-iOS-19 同一缺口，且 P2 新增的麦克风/语音识别 usage description 也应一并核。
• Depends: T-iPad-2/3/4 · Owns: 无源码（report-only，findings 派回 owner）
• Steps:
  • F-iPad 走查（§6 清单）逐条：分栏、横竖屏、Split View/Slide Over/Stage Manager 尺寸切换、硬件键盘/指针、终端更宽列数、遮罩覆盖 detail
  • iPhone 零回归：iPhone 16 全套件绿 + 逐屏目视对比无变化（compact 路径未动）
  • 安全：拆 iPad 产物 ipa 核对（UIDeviceFamily [1,2]、五段 CIDR、usage 一一对应）；分栏后隐私遮罩仍遮 detail 终端；上下文菜单/键盘触发的 G 调用仍走 APIClient 带 Origin
  • 真机项（真 iPad 手势/键盘/指针目视、Stage Manager 实机）→ DEFERRED，附手工清单

---

6. 测试与验收

设备矩阵

层	环境
纯逻辑（LayoutPolicy/谓词）	macOS swift test / 宿主 WebTermTests
App 自适应	iPhone 16（compact 回归）+ iPad Pro 11"（regular）+ iPad Split View（同一次运行内 regular↔compact 切换）
XCUITest	iPad happy path 1 条：sidebar 选会话 → detail attach → 输入 → gate approve（复用 iPhone happy path 骨架，换分栏断言）
真机必测	真 iPad 分栏手势、硬件键盘全键位、指针 hover/右键、Stage Manager（1 台，DEFERRED 至有设备）

验收演示脚本（F-style）

• F-iPad-1 iPad 全屏 → 左 sidebar 会话列表 + 右 detail 终端同屏；选另一会话 → detail 即时切换（回放恢复）。
• F-iPad-2 横竖屏旋转 → 布局自适应、终端 resize 重绘、无错位。
• F-iPad-3 拉出 Slide Over（compact）→ 自动退化为 stack（== iPhone 布局）；推回全屏 → 恢复分栏；全程会话不断、终端不重建。
• F-iPad-4 iPad 接硬件键盘 → KeyBar 自动隐、UIKeyCommand 全键位可用；拔键盘 → KeyBar 回来。
• F-iPad-5 指针右键会话行/终端 → 上下文菜单（kill/新建/cwd 开）生效。
• F-iPad-6 iPad 全屏终端列数明显多于 iPhone（接近桌面），宽 TUI 折行大幅缓解。
• F-iPad-7 Stage Manager/切后台 → detail 终端被隐私遮罩覆盖（快照不泄露）。
• F-iPad-8（回归）iPhone 16 逐屏与适配前目视一致、全套件绿。

---

7. 风险与开放问题

风险 / 问题	影响	缓解 / 待定
NavigationSplitView 在 size-class 频繁切换（Slide Over 反复拉）时状态/选中丢失	中	选中态提升到 AppCoordinator（设备无关单一真值），T-iPad-2 专项测切换保持；终端 .id(controller.id) 稳定性已在 P1 验证
隐私遮罩在 split detail 漏遮	高（安全）	遮罩上提到 AdaptiveRootView 两分支共享 ZStack 顶层；T-iPad-2/5 双重目视
iPhone 回归（compact 分支被无意改动）	高	每任务验收前置 iPhone 全绿 + 目视；compact 分支复用现有 StackRootView 原样
SwiftTerm 在超宽 detail 的性能/选择手感	低	复用 iPhone 已测路径；真机目视
多窗口诱惑导致 scope 膨胀	中	本期明确单场景（§0 非目标）；多窗口另立计划

待你拍板 —— 三项均已落定（2026-07-30 按源码核对）：

1. iPad 最低系统版本 已定：iPadOS 17，与 iPhone 一致（project.yml 单一 deploymentTarget: iOS 17.0，无独立 iPad 下限）。
2. 本期是否要指针右键上下文菜单 已做：Components/TerminalContextMenu.swift（复制选区 / 在 cwd 开新会话 / 结束会话，全部路由既有通道，kill 仍经 APIClient 带 Origin）+ TerminalContextMenuTests。
3. 多窗口 确认推迟：本期单场景（§0 非目标）；拖会话开新窗并排两终端仍未开工，另立计划。

工作量合计：W0 0.5 + W1 2 + W2（3∥4）2 + W3 0.5 ≈ 5 人日（并行后墙钟更短）。

---

8. 与现有文档的关系

• 本文只改 ios/App/WebTerm/** + project.yml/ios.yml；ios/Packages/**、src/、public/ 零改动。
• 是 PLAN_IOS_CLIENT.md 的布局适配层，复用其 §3 契约/§4 标准/§5 安全/§6 并行规则；把该计划 §0 非目标里的「iPad 优化布局」提取为本期。
• 多设备共享 PTY 的尺寸张力（PROGRESS_LOG 记录的「宽桌面+窄手机折行」）：iPad 因自身是宽屏 writer 而天然缓解，非本计划新机制。
• 冲突裁决：iPhone 计划管协议/会话/安全模型；本文只加自适应布局，不改之。