Skip to content

FunctionAndDataStructureDescription.md

Latest commit

 

History

History
153 lines (145 loc) · 17.5 KB

FunctionAndDataStructureDescription.md

File metadata and controls

153 lines (145 loc) · 17.5 KB

技术说明渐进式生效披露关闭手电筒轻量虚拟列表，仅监听滚动并按需复用可视项，用于侧栏大规模头像/流程列表。

闭眼检测补充

  • AispectBlinkDetector：基于 ARKit 人脸跟踪获取闭眼状态，满足 200ms 阈值后触发回调，并输出首帧延迟用于评估启动耗时。
  • AispectBlinkDetector.Config：修正闭眼持续时长参数命名为 blinkHoldDuration，与检测逻辑字段保持一致，恢复构建可用性。
  • AispectImpactTestView：测试面板新增闭眼检测延迟、状态与结果显示。
  • Localizable.strings：新增闭眼检测状态与延迟格式的中文资源文案。

触摸结束偏移补充

  • AispectTouchEvent.liftOffset：记录触摸结束时的抬起偏移距离，用于在未命中冲击时辅助判定 heavyTap，并在测试面板展示。
  • AispectImpactDetector：impact delta window 记录每帧 delta 与 x/y/z/magnitude，便于观察冲击细节。
  • AispectImpactTestView：测试面板新增 copy log 按钮，可直接复制 delta window 文本。
  • MessageListLayoutSnapshot / VirtualListLayoutSnapshot：用于根据滚动偏移与固定度量计算元素位置，供连线系统使用。
  • FloatingHomeContainerView：悬浮式主页容器，支持 iOS 风格圆角、边框与毛玻璃材质；当作为全屏根容器使用时可切换到 edgeToEdge 样式，关闭圆角、边框与阴影，避免根层视觉缩边。
  • RootViewController / safeContentGuide：主页主容器铺满整个屏幕，根控制器底色统一为黑色；主内容依赖独立的安全区布局 guide，而不是依赖装饰性容器自身的安全区，符合 iPhone 全屏背景与内容避让分层的常见做法。
  • zhifaIOSApp：SwiftUI 入口使用全屏黑色底板包裹 ContentView，用于兜住 UIKit 宿主层尚未完成布局时的背景色，避免安全区先露出白底。
  • GlassMaterialView：统一玻璃材质背景，使用系统语义化模糊、细边框与轻阴影，避免手动透明度渲染。
  • MeshGradientBackgroundView：SwiftUI 承载 MeshGradient 的背景视图；当前背景层已统一改为纯黑底，低版本兜底层与 iOS 18+ 的 MeshGradient 颜色均收敛为黑色，便于作为全屏暗色背景基底。
  • MeshGradientDriver：MeshGradient 驱动对象，接收触摸位置与压力并联动网格顶点。
  • AispectHoldProgressView：长按进度条视图，轻量渲染用于提示长按触发进度。
  • AispectHoldControlView：重触长按的控制视图，支持旋钮位置更新与回弹重置。
  • AispectHeavyIndicatorView：重触命中提示视图，用高亮环与文字提示当前重触状态。

CNN 冲击分类补充

  • AispectImpactCNNClassifier：内置轻量一维卷积推理器，读取打包到 App Bundle 的权重与 scaler，对 -5...+15 的 21 帧冲击窗口执行二分类，输出 heavy/light 概率。
  • AispectImpactFrame：统一冲击窗口单帧输入结构，包含 delta/x/y/z 四个特征，便于日志缓冲与模型推理复用。
  • AispectImpactPrediction：封装 CNN 输出的 heavy/light 概率，并提供当前主类别判断。
  • AispectImpactDetector.Config：新增 usesCNNClassifier 与 cnnHeavyProbabilityThreshold，用于控制阈值候选后是否启用 CNN 二次判定以及命中门槛。
  • AispectImpactDetector：保留原有 delta 阈值作为候选触发器，补齐后 15 帧后再执行 CNN 判定；若触摸结束过早，则在 stop() 时零填充尾帧完成一次兜底分类。
  • AispectImpactCNNWeights.json / AispectImpactCNNScaler.json：保存从现有 .pth 权重提取后的参数与全局归一化统计，用于手机端直接推理，不依赖 PyTorch 或 Core ML 运行时。

训练数据采集补充

  • AispectImpactDatasetCollector：日常采集模块，支持手动选择 handheld_static/placed_static/walking 与 light/heavy 组合标签，并在每次触摸结束后自动补齐 -5...+15 的 21 帧训练窗口。
  • AispectImpactMotionState / AispectImpactTouchStrength / AispectImpactDatasetLabel：用于表达训练样本的运动状态与触摸强度标签，当前将“手持静止”和“放置静止”显式拆分，避免旧 static 标签混杂两类场景；同时保留对历史 static 样本的兼容解码并映射到 handheld_static。
  • AispectImpactSystemActivityEvidence：封装 CMMotionActivityManager 给出的系统侧活动证据，记录 walking/stationary/running 等状态布尔值、置信度与授权状态，用于和人工标签一起落盘，便于后续清洗错标样本。
  • AispectImpactDatasetCollector.Status：新增结构化状态回调，包含任务标签、有效/无效计数、任务目标数与最近一次采集结果，便于 UI 做任务式反馈。
  • AispectImpactDatasetCollector：内部改为串行状态队列，避免主线程标签切换与 Core Motion 采样并发写入导致错标签。
  • AispectImpactDatasetCollector：在采集开关开启时同步启动 CMMotionActivityManager，将最新系统活动证据、采集 session 标识、App 版本号与 build 号写入每条样本 JSON。
  • AispectImpactDatasetCollector：历史样本统计改为启动后在后台串行队列异步扫描，避免当本地 JSON 数量较大时阻塞主线程并造成 App 打开卡死。
  • AispectImpactDetector：新增采集器透传接口，在现有加速度采样链路中直接写入训练数据，避免单独再开一套传感器监听；同时将有效采集与拖动/取消样本的丢弃显式分流。
  • RootViewController：仅在 lightTap / heavyTap 时接受样本，dragEnd / cancel 直接记为无效并丢弃；触摸结束后延迟约 80ms 再停止冲击采样，以便补到真实后置帧。
  • AispectImpactTestView：测试面板升级为任务式采集交互，采集中锁定标签，显示中文引导、任务进度、最近一次采样结果、系统活动证据摘要与采集目录复制按钮；运动状态标签扩展为“手持静止 / 放置静止 / 走路”三档。
  • AispectImpactTestView：测试面板新增滚动容器与折叠按钮，内容过长时可纵向滚动查看，并可收起为右上角小按钮，避免在 iPhone 上遮挡主交互区域。
  • RootViewController / AispectImpactTestView：测试面板展开态最大高度会按当前安全区动态限制，防止整块面板超出屏幕导致回弹异常，保证滚动只发生在面板内部。
  • Localizable.strings：补充冲击测试面板与采集器的中文资源，完成手机端展示汉化。
  • zhifaIOS.xcodeproj：补充 NSMotionUsageDescription，允许真机上请求系统运动与健身权限，采集 walking/static 的系统侧证据。
  • 采集数据目录：默认写入 App 沙盒 Documents/AispectImpactDataset，每条样本单独保存为 JSON，便于后续批量导出到训练脚本。

Impact Dashboard GitHub Pages 部署补充

  • docs/impact_dashboard/index.html：作为 GitHub Pages 发布副本，复用本地 tools/impact_dashboard/dashboard.html 的静态内容，并将下载链接改为相对路径，确保项目站点子路径下可正常访问 latest_samples.csv。
  • docs/impact_dashboard/data：保存发布用 latest_samples.json 与 latest_samples.csv 静态数据副本，避免 GitHub Pages 直接暴露工具目录，便于后续独立替换数据文件。
  • docs/index.html：仓库 Pages 根入口，自动跳转到 impact_dashboard 子目录，降低访问路径记忆成本。

后续扩展建议

  • Aispect 事件路由与模块绑定建议单独抽出 InteractionRouter，避免与 UI 组件耦合。
  • 消息列表与侧栏建议加入虚拟化计算与滚动监听，满足大规模会话与消息量的性能目标。
  • 模块化接口已预留 Live Activity、PiP、Todo、知识库等能力的最小入口，可按模块逐步填充。

修改日志：

  • 2026-01-23：初始化 UIKit 主容器、核心数据模型、Aispect 触摸骨架与基础 UI 组件结构。
  • 2026-01-23：加入虚拟列表组件与 Aispect 采样平滑策略，侧栏列表改为滚动驱动的可视化复用。
  • 2026-01-23：补充虚拟列表在滚动与布局变化时的可见项位置刷新。
  • 2026-01-23：连线系统改为基于虚拟布局快照计算锚点坐标。
  • 2026-01-23：输入框增加浮标模式切换与建议文本展示接口，并接入 Aispect 示例路由。
  • 2026-01-23：新增悬浮式主页容器组件并接入主界面布局。
  • 2026-01-23：悬浮容器补充内容裁剪与连续圆角一致性配置。
  • 2026-01-23：新增详细气泡与气泡菜单占位，实现未回消息页与顶部按钮切换。
  • 2026-01-23：气泡菜单条加入玻璃材质与点击淡入淡出动画。
  • 2026-01-23：未回消息页加入布局快照与可见索引计算，连线可基于该页生成。
  • 2026-01-23：未回消息页使用详细气泡样式，右侧工具列加入滚动驱动的高度联动与自动回弹。
  • 2026-01-23：虚拟列表增加滚动回调，用于侧栏联动控制。
  • 2026-01-23：右侧流程列加入滚动挤压联动，气泡菜单按钮加入图标化样式。
  • 2026-01-23：右侧账号列加入滚动挤压联动，三列高度按比例切换。
  • 2026-01-23：左侧会话头像支持滚动边界固定展示，避免当前会话丢失。
  • 2026-01-23：Aispect 手势允许与系统手势同时识别，避免阻断点击与滚动。
  • 2026-01-23：Aispect 手势改为不拦截触摸，避免阻断 UI 点击。
  • 2026-01-23：左侧会话头像增加停留插入按钮的占位挤压逻辑，并与滚动联动重置。
  • 2026-01-23：新增玻璃材质背景组件与 MeshGradient 背景层，顶部/底部/侧栏与气泡改用语义化材质渲染。
  • 2026-01-23：Aispect 增加触摸采样事件，MeshGradient 背景与悬浮容器支持触摸压力联动形变。
  • 2026-01-23：补充 Aispect 事件路由与热区绑定，长按进度条与重触控制占位视图落地。
  • 2026-01-23：项目最低系统版本调整为 iOS 18.6。
  • 2026-01-23：补充默认开发团队配置，修复命令行构建签名失败。
  • 2026-01-23：开发团队 ID 与本机签名证书一致化，便于自动签名。
  • 2026-01-23：开发团队 ID 与本机配置文件一致化，便于自动签名。
  • 2026-01-23：修复 MeshGradient 背景编译依赖，补充 Combine 引用与辅助函数整理。
  • 2026-01-23：关闭预览构建以避免设备构建的调试动态库签名失败。
  • 2026-01-23：长按进度完成触发回调接入，补齐轻触长按触发入口。
  • 2026-01-23：重触长按控制视图接入拖拽更新与回弹重置逻辑。
  • 2026-01-23：边缘拖拽热区识别与动作回调接入，作为可复用触发入口。
  • 2026-01-23：新增触摸半径可视化叠层，用于验证 majorRadius 采样与重触阈值。
  • 2026-01-23：下调重触默认倍率与最小基线值，降低重触阈值门槛。
  • 2026-01-23：Aispect 采样支持 coalesced touches 与 estimated updates，提升半径变化捕获率。
  • 2026-01-23：重触阈值首次命中时立即派发事件，降低延迟感。
  • 2026-01-23：加入重触显眼提示视图，并进一步下调默认阈值参数。
  • 2026-01-23：新增触摸半径日志记录器，便于统计 majorRadius 变化与阈值分布。
  • 2026-01-23：日志记录改为不做额外节流，避免遗漏系统已节流后的样本。
  • 2026-01-23：日志写盘频率提高，并在前后台切换时强制 flush。
  • 2026-01-23：新增 majorRadius 最小测试面板，便于快速验证数值变化。
  • 2026-01-23：测试面板改为使用 intrinsicContentSize，避免约束循环导致卡顿。
  • 2026-01-23：Aispect 事件补充 majorRadiusTolerance，并在日志与调试视图中可视化输出。
  • 2026-01-23：Aispect 事件补充 force/maxForce，并在调试面板与日志中输出显示。
  • 2026-01-23：移除 TouchVisualizer 调试模块，避免引入全局 swizzle 依赖。
  • 2026-01-23：majorRadius 调试面板显示原始精度数值，避免被 UI 侧截断影响判断。
  • 2026-01-23：调试面板新增 moved-only 的 majorRadius 展示，用于排除 Began 采样误导。
  • 2026-01-23：调试阶段将半径平滑关闭并提升采样频率，确保 raw/moved 更接近系统原始值。
  • 2026-01-23：重触阈值默认调整为 12.0852，便于观察重触触发行为。
  • 2026-01-23：引入半径变化率判定，用于捕捉重触的瞬时增长。
  • 2026-01-23：测试面板加入 rate 阈值滑条，可实时调节变化率触发门槛。
  • 2026-01-23：变化率显示精度提升，便于观察微小波动。
  • 2026-01-23：新增 coalescedTouches 数量展示与日志记录，用于验证采样密度变化。
  • 2026-01-23：加入基于加速度计的冲击检测，用于在触摸窗口内补偿重触触发。
  • 2026-01-23：冲击检测补充 QuartzCore 依赖以使用高精度时间戳。
  • 2026-01-23：测试面板新增冲击阈值滑条，便于快速调整加速度触发灵敏度。
  • 2026-01-23：测试面板新增触觉反馈样式选择，并在重触触发时使用选定手感反馈。
  • 2026-01-23：冲击采样率统计并显示在测试面板，便于验证实际采样频率。
  • 2026-01-23：冲击采样间隔提升至 240Hz 目标值，用于测试系统上限。
  • 2026-01-23：测试面板新增冲击 delta 窗口日志显示（前 5 帧、后 15 帧）。
  • 2026-01-23：冲击日志改为延迟收集，确保完整显示前 5 帧与后 15 帧。
  • 2026-01-23：冲击日志补充基线采样与零填充，避免前置帧为空白。
  • 2026-01-23：冲击日志改为增量更新，显示 post remaining 以便观察收集进度。
  • 2026-01-23：冲击检测引入轴向权重，默认 X 权重为 0.01、Y 权重为 1.0、Z 权重为 6.5 以增强按压判定。
  • 2026-01-23：冲击窗口日志改为输出带正负号的 delta，便于观察方向变化。
  • 2026-01-24：移除 majorRadius 全链路与调试可视化/日志，重触判定统一切到加速度冲击检测，测试面板精简为 impact 参数与日志。
  • 2026-01-24：删除 AispectRadiusDebugView 与 AispectRadiusLogger 文件，清理旧半径调试残留。
  • 2026-01-24：新增 liftOffset 结束偏移与 heavyTap 辅助判定，测试面板展示抬起偏移。
  • 2026-01-24：heavyTap 触发时若已发生 heavyPress 则跳过重复触觉反馈。
  • 2026-01-24：补充 AispectTouchEvent 显式初始化器，确保 liftOffset 传参与编译一致。
  • 2026-01-24：移除 liftOffset 的默认值，修正只读属性重复初始化报错。
  • 2026-01-24：impact delta window 输出每帧 delta 与 x/y/z/magnitude，并在测试面板增加 copy log 按钮。
  • 2026-01-24：为冲击检测与 liftOffset 判定补充注释，说明触发窗口与重复触觉防护。
  • 2026-01-24：更新 AGENTS 规则并将新增注释统一为中文注释。
  • 2026-01-24：补充 Aispect 冲击采样、触摸事件流、测试面板与路由关键代码的中文注释。
  • 2026-01-24：新增 ARKit 闭眼检测模块与测试面板延迟/状态显示，并补充相机权限说明。
  • 2026-01-24：补充入口、连线层与测试面板的中文注释，统一注释规范。
  • 2026-01-24：轻点触发闭眼检测时重置面板延迟与状态显示。
  • 2026-01-24：闭眼状态文案改为中文资源，面板显示“检测到闭眼/未检测到闭眼”等清晰状态。
  • 2026-01-24：测试面板新增闭眼结果行，用于明确是否检测到闭眼。
  • 2026-02-14：修复 AispectBlinkDetector 配置字段拼写错误（blinkHoldDurantion -> blinkHoldDuration），消除编译报错。
  • 2026-04-04：接入基于 CNN 的冲击二次分类器，保留 delta 阈值候选触发并在手机端使用本地权重/归一化参数完成重触识别。
  • 2026-04-04：新增四类真值标签的数据采集模块与测试面板控件，支持日常采集 static/walking × light/heavy 训练样本并写入本地 JSON 数据集目录。
  • 2026-04-05：将采集模块改为任务式交互，采集中锁定标签、丢弃拖动与取消事件、按真实触摸时间对齐窗口，并补齐冲击测试面板中文文案。
  • 2026-04-05：采集模块新增系统侧活动证据记录，接入 CMMotionActivityManager 并把 activity/confidence、采集 session ID、App 版本信息写入样本，同时在面板显示系统活动摘要并补充运动权限说明。
  • 2026-04-05：修复采集器启动阶段同步扫描历史数据导致的界面卡死问题，改为后台异步汇总本地样本统计。
  • 2026-04-05：修复测试面板在 iPhone 上不可见且无法滚动的问题，新增面板滚动查看与收起为小按钮的交互。
  • 2026-04-05：修复测试面板整体超出屏幕导致滚动回弹异常的问题，按安全区限制展开态最大高度。
  • 2026-04-05：修复主页背景未占满全屏、上下安全区出现空白的问题，主容器改为全屏铺满并由内部内容自行遵守安全区。
  • 2026-04-05：将主页布局改为“全屏视觉层 + 独立安全区内容 guide”，并为全屏容器切换到 edgeToEdge 样式，避免装饰性容器承担安全区职责导致的边缘留白与缩边问题。
  • 2026-04-05：将背景层统一改为纯黑底，关闭彩色 MeshGradient 底色，确保全屏背景视觉一致。
  • 2026-04-05：将根控制器与 SwiftUI 入口宿主层同步改为黑底，修复安全区仍然暴露白色背景的问题。
  • 2026-04-05：训练数据采集的运动标签扩展为“手持静止 / 放置静止 / 走路”，并兼容历史 static 标签映射到手持静止。
  • 2026-04-07：新增 docs/impact_dashboard GitHub Pages 发布目录与根入口跳转页，并修正发布副本里的数据下载相对路径。