开源社区 · iPhone Duo Agent Skills

iphone-duo-skills

GitHub 开源项目 mirzaaghazadeh/iphone-duo-skills 的能力拆解。8 个专项 skill + 3 份参考手册，把 Apple 六部 Tech Talks 和 HIG 文档蒸馏成 Agent 可直接执行的结构化指导。

8
个专项 skill
3
份参考手册
65
GitHub Stars
MIT
License
iPhone Duo 折叠屏 双屏 · 铰链 adaptive-layout vertical-bars hinge-and-scenes camera design-review games flutter react-native
← → 键或按钮翻页 · 共 9 页
项目概览

官方资料 → Agent 可执行指导

Apple 的 iPhone Duo 开发者材料只有六部 Tech Talk 视频 + 一页 HIG。这个项目把它们蒸馏成结构化 skill，让 Agent 能直接「按图索骥」。

输入（官方来源）

  • 6 部 Tech Talks：Design / Prepare / Raise the Bar / Strike a Pose / Displays & Scenes / Camera
  • Designing for iPhone Duo HIG 页面
  • iOS 27.1 SDK 头文件核对
  • Apple uikit-app-modernization skill 的 Core Principles

输出（Agent 可用形态）

  • 8 个专项 skill：按场景拆分，每个独立触发
  • 3 份参考手册：device-facts / api-index / sources
  • 每份 skill 含「何时用 + 检查清单 + 代码模板 + 禁忌」
  • 支持 npx skills 一键试用 / 手动 clone 安装
安装方式

两种使用路径

支持 npx 一键试用（不安装）或手动 clone 安装到本地。按需选择。

① 试用（不安装）

npx skills use mirzaaghazadeh/iphone-duo-skills@iphone-duo-readiness

一行命令临时调用入口 skill，不在本地留文件，适合先评估能力。

② 手动安装

git clone https://github.com/mirzaaghazadeh/iphone-duo-skills.git
cp -r iphone-duo-skills/skills/* ~/.claude/skills/

克隆后把 skills 目录复制到 ~/.claude/skills/，即可被 Claude Code 等 Agent 识别加载。

能力矩阵

8 个专项 skill，各管一段

按「框架/场景」切分，互不重叠。入口 skill（readiness）负责路由到正确的专家 skill。

iphone-duo-readiness
入口 · 审计与路由
  • SDK 分层行为判定（<27 / 27 / 27.1）
  • 排查固定假设：idiom / orientation / UIScreen.main / 对称 inset
  • 按 App 类型路由到专家 skill
iphone-duo-adaptive-layout
SwiftUI · UIKit · 折痕布局
  • Reserved Region：division（铰链）vs occlusion（相机）
  • 三个区域的激活条件与行为差异
  • Displacement 位移模式（不移动滚动内容）
  • ArrangementView split / overlay 主-次布局
iphone-duo-vertical-bars
SwiftUI · UIKit · 竖向栏
  • 条目顺序：导航 → 主要动作 → 其余
  • symbol vs text 推断 + AxisBehavior 覆盖
  • Split View / Inspector / Sheet 竖栏特例
iphone-duo-hinge-and-scenes
SwiftUI · UIKit · 铰链与多屏
  • onHingeChange / UIHingeInteraction（只做交互不做布局）
  • Split View 多任务（50/50 分屏）
  • 多 Scene：外屏不能新建窗口
  • Scene Accessories 跨屏 UI（CameraCaptureAccessory）
iphone-duo-camera
AVFoundation · AVKit
  • Virtual Front Camera（自动切换，能力交集）
  • 单独访问内外前摄（4K120 / depth）
  • DirectionCoordinator：position≠朝向
  • RotationCoordinator + 关闭 sensor-orientation 补偿
iphone-duo-design-review
框架无关 · 设计评审
  • 10 问检查清单：折痕避让 / 姿态一致性 / 状态保持
  • 不对称布局三策略：偏移 / 居中 / 混合
  • 内屏三用好法：Split view / 重排多列 / Tab 变 sidebar
iphone-duo-games
Unity · Unreal · Godot · SpriteKit · Metal
  • 方向锁定 ≠ 尺寸锁定：必须全姿态填屏
  • aspect ratio 优先于 letterbox（带 artwork）
  • 世界缩放但 HUD/触控保持物理尺寸
  • 触控锚定边缘，避开 division region
iphone-duo-flutter / react-native
跨端桥接
  • 核心坑：displayFeatures / dual_screen 在 iOS 返回空
  • Tier 1：约束驱动 + per-edge safe area + 宽度断点
  • Tier 2：channel 桥接 reservedRegions / hinge
readiness 是入口
先跑 baseline → 排查固定假设 →
按 App 类型路由到右侧专家 skill
核心洞察 · 折痕布局

Reserved Region 不止铰链：三个区域，三种行为

多数资料只讲「铰链是 division、相机是 occlusion」。这个项目把第三个区域——外屏相机——的行为差异讲清楚了。

区域类型何时存在行为特征
外屏前置摄像头 Occlusion 常驻 位于外屏角落、与侧边竖排控件对齐；有 Live Activity 时扩展为竖排 Dynamic Island。是布局的「永久事实」，一次性处理。
内屏前置摄像头（屏下） Occlusion 仅摄像头激活时 平时不可见，激活时 UI 移开露出。时有时无，要按变化做动画响应，不能只在布局时读一次。
铰链 / 折叠区 Division 仅设备半折时 把内屏分割成两个可用区域，弯折中央不可用。放平时 inactive 且宽度为 0。

Grid 布局的偶数列建议

用 includeInactive 查询到 division region 即判定设备有 fold → 偏好偶数列，半折时内容均分两侧，不被劈开。

Split 的 Duo 专属行为

secondary view dismiss 后，primary view 不会像 iPad 那样横跨全屏重新居中，而是留在 fold 定义的当前区域内，保证控件可达。

核心洞察 · 竖向栏

竖向栏的三个易漏细节

「栏竖起来」只是开始。Split View、Sheet、控件归属这三处最容易踩坑。

1. Split View 与 Inspector 的特例
Split View 中只有 detail 列参与竖排，primary / supplementary 列保持横排。Inspector 展开时没有自己的竖栏——detail 列已有一个，两个会混淆。
2. Sheet 的竖栏行为分屏差异
外屏 sheet：有 toolbar 就竖排。内屏 sheet：居中显示，条目保持横排。用 preferred-placement API 移动 sheet 时：放右侧才有竖栏，放左侧没有。禁用竖栏的 sheet 会停在前摄下方，状态栏自动重排。
3. 控件留在作用区域旁
作用于某个内容 pane 的控件应留在该 pane 附近（如 mail 式布局中作用于 message list 的控件留在 list 上方），不要一律扫进共享竖栏——扫进竖栏的控件会被读作「作用于整个 app」。

Group 替代手动 spacer

flexible spacer 在竖轴上归零，fixed spacer 保持最小尺寸——手动加间距会在姿态切换时失效。改用 ToolbarItemGroup / UIBarButtonItemGroup 表达分组关系，系统自动留白并根据可用空间调整。

核心洞察 · 跨端桥接

Flutter / RN 的「两档策略」与最大坑

跨端框架没有 fold API，但 80% 的适配不需要桥接。RN 侧已内化进 ios27-adaptation（iphone-duo-rn.md + 扫描器 3 条规则），Flutter 侧待有业务场景时补充。

⚠ 最大坑：displayFeatures 在 iOS 上是空的

Flutter 的 MediaQuery.displayFeatures 和 dual_screen 包（TwoPane / hingeAngleEvents）是 Android-only，在 iPhone Duo 上返回空列表。RN 同样没有 fold/hinge API。不要在这里浪费时间。

Tier 1 — 纯 Dart/JS，今天就能做

  • 约束驱动布局（LayoutBuilder / useWindowDimensions）
  • per-edge safe area（paddingOf / useSafeAreaInsets）
  • 宽度断点代替机型/方向判断
  • NavigationRail / drawer 适配大屏

Tier 2 — 需要原生桥接

  • reservedRegions(kind:) → 避开折痕和相机
  • UIHingeInteraction → 连续角度（EventChannel 推送，不轮询）
  • traitCollection size class → 真实信号
  • 非折叠设备必须降级返回「无区域无铰链」，不抛错

RN 特有注意：核心 SafeAreaView 已废弃，必须用 react-native-safe-area-context 的 useSafeAreaInsets()；Dimensions.get() 快照会过期，换 useWindowDimensions() hook。

核心洞察 · 相机与设计

两个「为什么」讲透了概念

好的 skill 不只给 API，更解释「为什么需要这个 API」。这两个例子值得借鉴。

相机：position ≠ 朝向
AVCaptureDevice.position 只表示摄像头在硬件上的安装位置（.front / .back），不表示它当前朝向用户。Duo 双屏可翻转，三个场景打破假设：① 用户看内屏时外屏前摄是背向；② 合盖时同一颗外屏前摄转向面对用户；③ 展开翻转后后置摄像头变成自拍视角。DirectionCoordinator 回答的是「哪颗摄像头当前朝前」，RotationCoordinator 回答的是「输出画面是否正立」——两个 coordinator 解决两个问题，多数相机 App 都需要。
设计评审：10 问清单
不是代码审查，是体验走查：① 可交互元素是否落在折痕或侧栏下？② 功能是否跨姿态一致？③ 有没有固定宽度断点？④ 工具栏条目能否映射到侧边？⑤ 内屏是否只是拉伸？⑥ 内容偏移策略是否明确？⑦ Split View 两侧安全区是否正确？⑧ 自定义组件是否重复实现系统避让？⑨ 控件是否靠近作用内容？⑩ 跨姿态切换时状态是否保持？

游戏：方向锁定 ≠ 尺寸锁定

「可以锁方向，但不能停止填屏」——内屏不遵守 supportedInterfaceOrientations，锁了方向也会 resize。正确做法：锁方向 + 全姿态填屏 + 世界缩放但 HUD/触控保持物理尺寸 + 触控锚定边缘避开折痕。

落地

已内化进 ios27-adaptation

开源社区的能力已拆解、筛选、合并进我们的内部 skill，与小红书工程实践整合。

来源能力已合并到
readiness排查固定假设：idiom / orientation 分支检测scan_ios27.py 新增 3 条 P1-B 规则
adaptive-layout三个保留区域行为差异、Split 不跨屏居中、Grid 偶数列references/iphone-duo.md#折痕布局
vertical-barsSplit View/Inspector 特例、Sheet 分屏行为、Group 替代 spacer、控件归属原则references/iphone-duo.md#竖向栏
cameraDirection vs Rotation 概念区分、position≠朝向的三场景references/iphone-duo.md#相机
design-review10 问设计走查清单references/test-checklist.md#B 线设计走查
react-native两档策略（Tier 1 纯 JS / Tier 2 原生桥接）、displayFeatures 空列表坑位references/iphone-duo-rn.md + scan_ios27.py 3 条 RN 规则
未吸收的部分及原因

Flutter 桥接

小红书主 App 无 Flutter 业务，暂不吸收。如后续有 Flutter 容器场景，两档策略与 RN 版同构，可快速补出。

Games / 多 skill 架构

游戏场景与主 App 无关；多 skill 架构与我们的单 skill + references 选读模式等价，不改架构。

iphone-duo-skills · 开源社区能力拆解
1 / 9