# HoloLake iOS 原生知识湖与 TestFlight 收口记录

> 开发车道：`DEV-20260802-001`
>
> 产品仓：`REPO-014 / bingshuo/hololake-system-architecture`
>
> 源码分支：`feat/ios-native-knowledge`
>
> 记录时间：2026-08-04（Asia/Shanghai）
>
> 最终产品验收：`0 / NOT_EXISTS / FAIL`

## 1. 为什么这条线存在

桌面端 HoloLake 仍继承了 Tolaria 的文件夹型 Vault、桌面文件选择器、桌面 Git 和本机
配置目录假设。把同一套页面直接打包到 iPhone 后，先后暴露出移动端文件选择器未实现、
iOS 沙箱目录无权写入、原生知识库无法挂载，以及 Agent 配置只存在电脑本机等问题。

本线的目标不是给旧页面换皮，而是把移动端知识入口改成 HoloLake 自己的运行边界：

1. App 沙箱中存在只读基础世界与用户个人知识湖；
2. 普通知识页可由 Agent 读取、创建和修改；
3. 可同步知识页与设备密钥严格分流；
4. 服务器写入只接受登录会话并返回原子 Git 回执；
5. TestFlight 只负责交付，不能代替真机功能验收。

## 2. 实现结果

### 2.1 移动端知识湖

- 新增 App 自有的 `mobile_vault`，不再调用 iOS 不支持的文件夹选择器。
- 基础世界与个人知识湖使用不同标记和稳定目录。
- 首次创建时写入最小世界结构、说明页和 Git 忽略边界。
- 移动端入口通过原生命令解析 App 数据目录，不使用桌面路径。

### 2.2 账号、Agent 与设备密钥

- 增加邮箱验证码会话接口、知识快照、模型目录与服务器代理客户端。
- API 密钥进入 Apple Keychain 的设备本地、不可同步存储，不写 Markdown、Git、安装包或
  服务器回执。
- `本地密钥/**`、`.hololake-*`、`.git/**` 不进入知识仓库同步。
- 移动端 Agent 使用服务器代理或设备本地模型配置；CLI Agent 在移动端明确失败关闭。

### 2.3 服务器知识页写入

- `REPO-012` 提供受会话约束的知识页写入口。
- 服务器受限执行器完成临时文件、校验、原子替换、Git commit 和结构化回执。
- 未登录公开请求返回 `401 session_required`，没有为测试放宽身份边界。
- 服务器执行器曾真实推进知识库提交并通过 `git fsck`；这证明服务器写入链存在，不证明
  iPhone 已成功完成同一链路。

## 3. 验证证据

| 验证层 | 结果 | 证据含义 |
|---|---|---|
| 移动端前端定向测试 | `66 / 66 PASS` | 组件和状态逻辑在测试环境成立 |
| 服务端测试 | `76 / 76 PASS` | 登录、知识和原子写协议成立 |
| Rust 测试 | `1148 PASS / 0 FAIL / 2 ignored` | 原生模块与边界测试成立 |
| TypeScript / Vite | `PASS` | 可生成生产前端 |
| iOS / Desktop Rust check | `PASS` | 两平台可编译检查 |
| Apple 签名与上传 | `PASS` | build 26 被 Apple 接收和处理 |
| TestFlight 内部组 | `PASS` | build 26 状态为“正在测试” |
| iPhone 安装 | `PASS` | App Store Connect 回读为已安装 `0.4.6.26` |
| 真机进入知识湖 | `FAIL` | 冰朔报告仍无法进入 |
| 真机页面滚动 | `FAIL` | 冰朔报告手机页面无法滑动 |
| 真机 Agent 新建知识页 | `NOT_RUN` | 被入口与滚动失败阻断 |

二值结论：TestFlight 交付存在；HoloLake iOS 可用产品不存在。前者不得覆盖后者。

## 4. 问题与因果链

### 4.1 从 Tolaria Vault 到 HoloLake 移动知识湖

```text
桌面文件夹/Vault 假设
→ iOS 没有同等文件夹选择器，桌面配置目录也不具备相同权限
→ “Folder picker is not implemented on mobile” 与 “Operation not permitted”
→ 不能继续给旧入口打补丁
→ 改为 App 沙箱内的基础世界与个人知识湖
```

该结构已经进入源码，但真机仍无法进入，说明“能创建目录”与“完整启动状态能够消费该目录”
是两个验收层。

### 4.2 当前无法进入的已知断点

移动端处理函数先调用原生命令，再以 `verifyAvailability: false` 注册路径，并立即把
onboarding 状态标记为 `ready`。现有测试验证了命令、路径和 React 状态，却没有覆盖真实
WKWebView、真实 iOS 文件系统、后续 Vault 加载器和主工作区渲染的完整设备链。因此：

```text
原生命令或路径注册局部成功
→ React 提前进入 ready
→ 后续 Vault 消费或工作区初始化仍可能失败
→ 单元测试通过，但真机仍停留/回落在不可进入状态
```

本轮没有取得设备端结构化错误回执，所以不得把某一个后续模块写成已确认根因。下一条开发
线必须先增加真机阶段回执，区分 `native_path_created`、`vault_registered`、
`vault_loaded`、`workspace_rendered`，再修复具体失败点。

### 4.3 手机页面无法滑动

当前 `OnboardingShell` 使用 `h-full`、垂直居中和固定内边距；容器没有 `overflow-y-auto`，
欢迎卡也没有基于 `100dvh` / safe-area 的最大高度与内部滚动。欢迎卡包含图标、标题、说明、
两张操作卡、错误信息和帮助链接，内容在窄屏上可以超过可视高度。

```text
固定高度父容器 + 居中布局 + 无纵向 overflow
→ 内容高于 iPhone 可视区
→ 超出部分被视口裁切
→ 手指滑动没有可滚动祖先
```

这是源码能够支持的高置信解释，但仍须在下一条线用真实设备视口和触摸滚动测试确认修复。

## 5. 走过的失败路线与纠正

- 仅修改 Tolaria 名称和 UI 不能解决移动端文件系统与运行边界。
- “Xcode upload complete” 不等于 TestFlight 可安装。
- TestFlight 可安装也不等于 App 可进入、可滚动或 Agent 可写页。
- 服务器原子写成功不等于 iPhone 邮箱会话到服务器的端到端链成功。
- 自动化不得代替账户持有人完成 Apple 出口合规法律声明。
- 桌面源码测试不能替代 WKWebView、safe-area、触摸滚动和 iOS 沙箱真机验收。

## 6. 下一条开发线的最小接续顺序

1. 保留 build 26 作为失败基线，不覆盖或误报通过。
2. 为移动 onboarding 增加四阶段结构化回执并在界面显示精确失败阶段。
3. 把 `OnboardingShell` 改成 `min-h-[100dvh]`、safe-area padding 和可滚动外层；加入
   真实 iPhone 尺寸的触摸滚动自动化。
4. 真机验证基础世界进入、个人知识湖进入、重启后恢复同一知识湖。
5. 完成邮箱验证码登录后，让 Agent 新建知识页；服务器与手机同时回读同一 commit/receipt。
6. 只有上述全部通过，移动端知识湖与 Agent 才能从 `0` 变为 `100`。

## 7. 安全与记录边界

本文保存目标、可见判断、源码依据、动作、测试和回执，不保存模型隐藏思维过程。任何密钥、
验证码、会话令牌、钥匙串内容和服务器秘密都没有进入本文或 Git。