SuperAPI AI 工具集

ux-paths-native

设计与创作

查看项目

更新于 10-30 07:23

技能介绍

UX Paths (native macOS/iOS) 是一个用于生成原生应用用户旅程故事的技能,隶属于 dennisonbertram/developer-skill-pack。它通过阅读应用源码,整理出一份详尽的真实用户旅程目录,输出供 /ux-walker-native 使用。

用途与定位:该技能是 /ux-paths(Web 版本)的姊妹技能,方法与流程相同,包括发现代理、故事群、合并三个阶段,输出格式与故事字段结构也原样继承。使用时先阅读 ../ux-paths/SKILL.md 并遵循其中流程,再按本文件列出的差异做替换。本文件不重复该技能的各个阶段,只记录针对原生目标发生的变化。

主要能力(针对原生应用的发现面):Web 版发现代理寻找路由,原生应用没有路由器,因此改查以下对应关系:

  • 路由/页面 → WindowGroup、Settings、NavigationStack、NavigationSplitView、.sheet、.popover、.alert、TabView、Storyboard 场景、NSViewController 子类;
  • 导航栏/侧边栏 → 侧栏列中的 List、NavigationLink、侧栏工具栏项、TabView;
  • 按钮与表单 → Button、TextField、Toggle、Picker、Stepper、Slider、Form、@FocusState;
  • 客户端状态 → @State、@Observable、@AppStorage、@SceneStorage、UserDefaults、NSUbiquitousKeyValueStore;
  • API 层 → URLSession 客户端、XPC 服务、内置本地服务器、应用启动的 CLI 子进程;
  • 鉴权 → Keychain 访问、ASWebAuthenticationSession、OAuth 令牌存储、订阅收据;
  • 功能开关 → 构建配置、#if DEBUG、启动参数、应用读取的环境变量。

此外还需枚举 Web 版没有对应物、却是原生应用容易出问题的方面:菜单栏命令(每个 CommandGroup、CommandMenu、.keyboardShortcut,每个菜单项都是用户可达能力,应纳入故事目录)、键盘快捷键(收集完整列表,并写出“仅用键盘完成该流程”的故事)、窗口管理(多窗口、标签页、全屏、尺寸与位置恢复、关闭最后一个窗口后的行为)、启动与首次运行(冷启动、无保存状态、权限提示、引导)、权限(触发系统提示的任何操作,如文件、网络、相机、辅助功能、通知,每项都需要已授权与拒绝两个故事)、系统集成(拖放、分享面板、服务菜单、URL scheme、程序坞菜单、通知、后台活动)、离线与睡眠(无网络时及机器唤醒后的行为)、外观(浅色/深色模式、强调色、增强对比度、减弱动态效果、更大字号)。

故事编写要求:步骤使用原生词汇,例如不写“导航到 /settings”,而写“从侧栏齿轮打开设置,或按 ⌘,”;每个步骤必须命名 walker 能在辅助功能树中找到的内容(可见标签、菜单项或快捷键)。每个故事在继承字段之外还需记录:入口(启动、菜单项、快捷键、点击路径)、键盘路径(无鼠标完成同一旅程,若不可能则写“不可能”)、窗口状态(故事发生在哪个窗口或 sheet 中)。理想路径字段在此处比 Web 版更重要,因为桌面应用若把菜单栏一键可完成的事做成六次点击,正是 /ux-flow-native 要寻找的摩擦点。

故事群主题:沿用继承的主题列表,另加原生专属主题——菜单栏与纯键盘操作、首次启动与权限提示、窗口与多窗口行为、外观与辅助功能设置(深色模式、对比度、更大文字)、系统集成(拖放、分享、通知、URL scheme)、离线、睡眠与长时间后台工作。

应省略的内容:不存在的主题不要生造原生对应物,例如响应式断点(Mac 窗口连续缩放,改为“在小窗口中可用”的故事)、浏览器前进/后退、指向任意状态的深链、SEO、页面加载性能、以及应用并无文档窗口或标签页时的多标签/多会话故事。

输出结构:与 /ux-paths 相同,包括 docs/ux-paths/discovery.md、按主题分文件以及 docs/ux-paths/catalog.md。另需在 discovery.md 中增加“Platform Surface”章节,列出菜单栏命令、键盘快捷键、应用请求的权限和窗口模型,/ux-walker-native 读取该章节来审计快捷键正确性与键盘可达性。

适用场景:需要对原生 macOS/iOS 应用做系统性用户体验路径梳理、键盘可达性审计、菜单栏能力盘点或为后续 UX 走查提供输入时使用。

限制:资料未提供安装方式、运行环境要求、收费模式、性能数据或实际效果验证;该技能本身不执行走查,走查由 /ux-walker-native 承担。