adapt-DUO / fwc-duo-skill-review
SKILL 调研 · 2026-09-23

FloWritesCode 的 swiftui-iphone-duo
能给我们的 ios27-adaptation 带来什么

对 GitHub 开源 Skill 仓库 fwc-swiftui-skills 中 iPhone Duo 适配规则库的深度拆解: 它是一份 25 条规则的「设计哲学清单」,我们的是一条「扫描 → 改造 → 回归」的工程流水线。 两者定位互补,其中有 7 个规则层的点值得吸收进我们的 skill。

📦 FloWritesCode/fwc-swiftui-skills 📁 skills/swiftui-iphone-duo 📄 SKILL.md 268 行 + reference.md 878 行 🎯 对照对象:本地 ios27-adaptation skill
01 · 仓库解剖

它是什么:一份写给 Agent 的 Duo 适配规则书

整个 skill 只有两个文件,但结构非常规整:SKILL.md 是入口与摘要,reference.md 是完整规则库。所有内容围绕一条核心哲学展开。

不要为 Duo 做一个单独的「Duo 版」App。先做出在每个尺寸下都优秀的自适应界面,只在折叠、铰链、第二块屏能创造额外价值时才引入 Duo 专属 API。
"Make this app excellent at every size, then use Duo's unique hardware where it creates additional value."
25
条 Agent 硬规则(reference.md)
9
步代码审查决策树
3
层 API 递进分级(Tier)
12
类 Code-Review 红旗模式

📐空间优先于设备身份(Rule 1-2)

禁用 UIDevice / UIScreen.main / idiom / 方向 / isDuo / isFolded 做布局分支。同一台 Duo 会以外屏、内屏全屏、分屏、不同折叠态出现——布局只能跟随「可用容器空间」。

🧭解决顺序有严格约定(Rule 2)

遇到自适应问题按序尝试:系统导航容器 → 自适应 Grid → ViewThatFits → size class → 精确几何计算(最后手段)。禁止跳级直接用 GeometryReader。

📖折痕是书脊,不是断点(Rule 9/16)

背景与滚动内容可以跨过折痕;按钮、文字、人脸、二维码、拖拽手柄不行。折痕干扰某个元素时局部挪移该元素,不要因为出现折痕就重构整个页面。

🎸布局跟空间走,交互跟铰链走(Rule 17)

全书最严格的一条:hinge.angle 只许驱动物理交互(弯音、游戏、特效),不许用它决定 sidebar、列数、导航折叠——那些永远由可用宽度决定。

🖥️第二块屏走 Scene Accessory(Rule 18)

不要把内外屏当两块独立画布手动管理。外屏只放「有意为之的附属内容」(提词器、被拍者预览、倒计时),主体验永远挂在主 scene 上。

🧪测不到就不写(Rule 25)

Duo 模拟器可用之前:可以做通用自适应、去除设备假设、预留 API 边界;不许硬编码猜测的铰链坐标、不许加未验证的 Duo 专属分支。准备优先于投机实现。

三层 API 递进:改代码前先分级

FWC 最有操作价值的设计——强制要求 Tier 1 全部完成后才允许提 Tier 2/3

TIER 1 · 先做

通用自适应改造

  • NavigationSplitView
  • adaptive TabView
  • GridItem(.adaptive)
  • ViewThatFits / AnyLayout
  • size classes
  • containerRelativeFrame
  • 系统 toolbar
  • safe-area 正确性
不写任何 Duo 专属 API,所有 Apple 平台与窗口尺寸都受益。大部分适配收益在这一层就能拿到。
TIER 2 · 按需

Duo 感知布局

  • Reserved Regions
  • ArrangementView
  • 竖向栏行为适配
  • Duo 专属 safe-area 处理
仅当 Tier 1 的空间自适应不够用、且确实涉及折痕/竖栏硬件特性时引入。
TIER 3 · 产品驱动

Duo 独有体验

  • onHingeChange
  • hinge angle
  • scene accessories
  • 多屏交互
  • 多 scene 工作流
仅当产品真的因铰链/双屏而变好时才做——这是体验加分项,不是适配必选项。
02 · 与 ios27-adaptation 的对比

定位不同,高度互补

FWC 面向 SwiftUI 新代码的设计与重构,是一份纯规则书;我们的 skill 面向 存量 UIKit/OC 工程,是一条带扫描器的工程流水线。事实准确性抽查:25 条规则与 Apple 官方 Tech Talks 结论全部一致。

维度FWC swiftui-iphone-duo我们的 ios27-adaptation
定位 SwiftUI 设计哲学:新代码/重构时「应该怎么设计才对」 存量工程改造流水线:扫描 → 分级 → 方案 → 改造 → 回归,A 线保命(UIScene/Xcode27)+ B 线增值(Duo)
覆盖栈 纯 SwiftUI;不提 UIKit/OC、UIScene 迁移、keyWindow、二进制组件 UIKit / ObjC / SwiftUI 混合全栈,含组件升级策略(amaze + GitLab + otool 二进制验证)
事实深度 较薄:无 SDK 分层行为表、无相机/多屏深度内容、无实测坑 很厚:6 部官方视频字幕 + REDoc 内部文档 + iOS 27.2 beta SDK 头文件核对 + halo/campus/Outrline 实测坑
规则形态 :25 条编号 Agent rule,每条附「错误写法 → 推荐写法」对照 分散:规则嵌在 references 的改造模板与坑位记录里,无统一编号
代码审查 9 问决策树 + 12 类红旗清单(含「只测两个宽度」「双份状态」等语义级问题) 正则级扫描器(P0/P1/P2 + P1-B/P2-B 标记),抓得到 API 误用,抓不到语义问题
进度约束 Tier 1/2/3 强制递进:通用自适应没做完,不许提 Duo 专属 API A 线优先于 B 线有约束;但 B 线内部没有「先通用后专属」的递进约束 ⚠️
工程配套 无扫描器、无回归清单、无灰度策略、无组件管理 :scan_ios27.py + test-checklist.md + 组件版本三步确认法 + 工时估算基准
宽屏设计观 4 条专规:宽屏要更有意义(非更宽)、文本限宽、暴露层级、保持触达性 缺失:只讲「怎么不 crash、怎么避让」,没讲「展开后怎么算好」 ⚠️
状态连续性 Rule 19 独立成规:布局切换 ≠ 应用状态切换,state 上提到布局层之上 仅有反面案例(缓存布局常量),无正面原则 ⚠️

⚠️ 标记的三行,正是 FWC 能补给我们的部分。

03 · 值得借鉴的 7 个点

按价值排序的吸收清单

全部是规则层/流程层的吸收,不涉及推翻现有工程流水线。

1

三层递进分级(Tier 1/2/3)FWC · Progressive API tiers

所有改动强制分类,Tier 1 通用自适应未完成前禁止提 Tier 2/3。我们 B 线缺这层约束,agent 容易上来就给业务代码塞 reservedRegions / onHingeChange,而这些大多可以用普通自适应解决。
直接收益:防止过度使用 Duo 专属 API,让大部分改造落在所有平台都受益的通用自适应上。
→ SKILL.md B线段
→ iphone-duo.md 开头
2

状态连续性独立成规FWC · Rule 19

「布局切换不得变成应用状态切换」:折叠/展开/跨屏时导航、滚动位置、编辑器、播放、选中态、表单、未保存内容全部不能丢。要求 state 上提,反对为 folded/unfolded 建两套独立 view 层级。这正是 REDoc 研发篇「cell 缓存布局」「一次性刷新守卫」坑的根因。
直接收益:把已有坑位记录上升为正面设计原则,改造时从源头避免。
→ iphone-duo.md 新增一节
3

宽屏设计三规则FWC · Rule 4 / 21 / 22 / 23

① 宽布局要更有意义而非更宽(List→List+Detail,Editor→Editor+Inspector);② 可读内容限宽 .frame(maxWidth: 700);③ 额外宽度优先暴露层级而非加空白;④ 大屏保持触达性,主操作不许甩到远处角落。
直接收益:补上「展开后怎么算好」的评价标准——REDoc 里个人页/图文笔记适配那几篇空文档迟早要用这套标准填。
→ iphone-duo.md 新增一节
4

9 问审查决策树FWC · Agent decision tree

固定顺序的语义级 review:连续宽度可用?→ 手写导航分支?→ 固定宽度?→ 宽屏只拉伸?→ 内容跨折痕?→ 两视图手工重排?→ 自建 bar?→ 真需要铰链?→ 外屏有价值?
直接收益:我们的扫描器是正则级的,这棵树补语义级 review,接在扫描器输出后作为逐屏 checklist。
→ test-checklist.md B线段
5

红旗模式清单FWC · Code-review red flags

isDuo / isFolded / idiom / orientation 分支、固定大 frame、硬编码 sidebar 宽度、固定列数、自建 bar、内容居中跨折痕、compact/expanded 双份状态、只在两个宽度测过。后两项正则抓不到,只能 review 时查。
直接收益:比 P1-B 正则更宽,合并后扫描 + review 双保险。
→ test-checklist.md B线段
6

排坑决策顺序FWC · Rule 2 preferred order

解决自适应布局问题时严格按序:系统容器 → 自适应 grid → ViewThatFits → size class → 精确几何(最后手段)。我们模板里隐含了这个偏好但没写成显式规则,agent 容易跳级直接上 GeometryReader。
直接收益:把隐含偏好变成可检查的硬规则。
→ SKILL.md 工作流
7

测不到就不写FWC · Rule 25

模拟器不可用前:可做通用自适应、去设备假设、预留 API 边界;不许硬编码猜测铰链坐标、不许加未验证的 Duo 分支。与我们的调试纪律精神一致,但写成了正面行为准则。
直接收益:给「没环境时 agent 该做什么/不该做什么」一个明确边界。
→ SKILL.md 代码纪律段
04 · 不建议借鉴的部分

明确不搬的三块

05 · 落地计划

吸收进 ios27-adaptation 的四个动作

references/iphone-duo.md 新增三节

开头加「三层递进(Tier 1/2/3)」总则;新增「宽屏设计规则」(有意义 > 更宽、文本限宽、暴露层级、保持触达);新增「状态连续性」(布局切换 ≠ 状态切换,state 上提,反对双份 view 层级)。

SKILL.md B 线任务表前加总则

扫描器命中 P1-B/P2-B 时先问一句:「这个问题能否用通用自适应(Tier 1)解决?」能就不碰 Duo 专属 API。同时把排坑决策顺序(系统容器→grid→ViewThatFits→size class→几何)写成显式规则。

references/test-checklist.md B 线段扩充

合并 FWC 红旗清单中扫描器覆盖不到的语义项:双份状态、只测两个宽度、宽屏只拉伸;并把 9 问决策树翻译后接为逐屏 review checklist。

SKILL.md 代码纪律段补一条

「Duo 模拟器不可验证时,准备优先于投机实现」:允许去设备假设与预留边界,禁止硬编码猜测坐标与未验证的 Duo 分支。