Back to Details

spatial-app-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spatial App Architecture

空间应用架构

Quick Start

快速开始

Use this skill for architecture questions, not API questions.
Use it when:
  • you need to choose the right surface: window, volume, immersive space, or a mixed flow
  • you are deciding which state is app-wide, scene-scoped, immersive-scoped, or view-local
  • a root file owns too many concerns and needs a refactor plan
  • you need a file or module plan before writing or splitting SwiftUI code
使用此技能解决架构相关问题，而非API问题。
适用于以下场景：
  • 需要选择合适的界面载体：窗口、体积空间、沉浸式空间，或是混合流程
  • 确定哪些状态属于应用全局、场景范围、沉浸式范围或是视图本地
  • 根文件承担过多职责，需要重构方案
  • 在编写或拆分SwiftUI代码前，需要制定文件或模块规划

Load References When

何时加载参考资料

ReferenceWhen to Use
references/surface-selection.md
When choosing window vs volume vs immersive space and their lifecycle boundaries.
references/state-ownership.md
When deciding what belongs to the app, scene, feature coordinator, RealityKit owner, or view.
references/file-layouts.md
When proposing a layered or feature-sliced file and module shape.
references/refactor-playbook.md
When the app already exists and the main task is refactoring without breaking behavior.
references/anti-patterns.md
When you need to call out structural smells or explain why an approach is wrong.
参考资料使用场景
references/surface-selection.md
当需要选择窗口、体积空间或沉浸式空间及其生命周期边界时。
references/state-ownership.md
当需要确定哪些内容属于应用、场景、功能协调器、RealityKit所有者或视图时。
references/file-layouts.md
当需要提出分层或按功能划分的文件与模块结构时。
references/refactor-playbook.md
当应用已存在，主要任务是在不破坏现有功能的前提下进行重构时。
references/anti-patterns.md
当需要指出结构缺陷或解释某种方案为何不可行时。

Workflow

工作流程

  1. Classify the feature by user job and current or intended surface.
  2. Choose the owning surface model: window, volume, immersive space, or a combination.
  3. Assign state ownership boundaries: app, scene, immersive, feature, view.
  4. Choose a file/module shape that matches the ownership model.
  5. Define the implementation handoff: SwiftUI, RealityKit, ARKit, SharePlay, or build/debug.
  6. If this is a refactor, sequence the extraction so behavior stays stable.
  7. Verify the structure with 
    build-run-debug
    after the first usable slice.
  1. 根据用户任务以及当前或目标界面载体对功能进行分类。
  2. 选择界面载体模型：窗口、体积空间、沉浸式空间，或是组合模式。
  3. 划分状态归属边界：应用、场景、沉浸式、功能、视图。
  4. 选择与归属模型匹配的文件/模块结构。
  5. 定义实现交接方向：SwiftUI、RealityKit、ARKit、SharePlay，或是构建/调试。
  6. 如果是重构任务，安排代码提取的顺序以保持功能稳定。
  7. 在完成首个可用的架构切片后，通过
    build-run-debug
    验证结构。

When To Switch Skills

何时切换技能

  • Switch to 
    spatial-swiftui-developer
    when the surface and ownership model are already chosen and the next step is implementing SwiftUI APIs.
  • Switch to 
    realitykit-visionos-developer
    when the work is mainly about entities, components, systems, or RealityKit runtime behavior.
  • Switch to 
    arkit-visionos-developer
    when the architecture choice depends on provider constraints, anchors, or tracked-world behavior.
  • Switch to 
    shareplay-developer
    when the app structure is driven by group activity or shared immersive presence.
  • Switch to 
    build-run-debug
    after the first usable architectural slice exists and needs validation.
  • 当界面载体和归属模型已确定，下一步是实现SwiftUI API时，切换至
    spatial-swiftui-developer
    。
  • 当工作内容主要涉及实体、组件、系统或RealityKit运行时行为时，切换至
    realitykit-visionos-developer
    。
  • 当架构选择依赖于提供者约束、锚点或跟踪世界行为时，切换至
    arkit-visionos-developer
    。
  • 当应用结构由群组活动或共享沉浸式体验驱动时，切换至
    shareplay-developer
    。
  • 当首个可用的架构切片已完成，需要验证时，切换至
    build-run-debug
    。

Guardrails

约束规则

  • Do not choose immersion by novelty alone.
  • Do not let transient views own long-lived immersive lifecycle or RealityKit mutation.
  • Preserve strong repo conventions when they are already coherent.
  • 不要仅为了新颖性而选择沉浸式模式。
  • 不要让临时视图拥有长期存在的沉浸式生命周期或RealityKit变更权限。
  • 当已有一致的仓库规范时，需予以保留。

Output Expectations

输出预期

Provide:
  • the chosen surface model and why
  • the ownership map: app, scene, feature model/coordinator, reality owner, view
  • the proposed file/module shape
  • the refactor slices, if this is brownfield work
  • the next implementation handoff: 
    spatial-swiftui-developer
    , 
    realitykit-visionos-developer
    , 
    arkit-visionos-developer
    , 
    shareplay-developer
    , or 
    build-run-debug
需提供：
  • 所选的界面载体模型及其原因
  • 状态归属映射：应用、场景、功能模型/协调器、RealityKit所有者、视图
  • 提议的文件/模块结构
  • 重构切片（如果是遗留项目）
  • 下一步的实现交接方向：
    spatial-swiftui-developer
    、
    realitykit-visionos-developer
    、
    arkit-visionos-developer
    、
    shareplay-developer
    或
    build-run-debug