连接 iOS 客户端

Holon 提供面向 iPhone 与 iPad 的原生 SwiftUI 客户端，支持 iOS 18 及更高版本。客户端具备结果优先的会话界面、按身份隔离的离线缓存、快速扫码配对、大文件分页阅读以及系统分享集成。

本指南介绍安装步骤、连接配置、日常导航、文件阅读、系统集成以及 AI 内容举报流程。

前置条件

• 已启动并开启 HTTP 访问的 Holon 守护进程（默认端口 7878）。
• 运行 iOS 18.0 或更高版本的 iPhone/iPad，或兼容的 Xcode 模拟器。
• 可访问守护进程的网络连接（局域网、反向代理或 Tailscale 虚拟网）。

安装

安装官方发布版本

通过 Apple TestFlight 或 App Store 安装官方构建版本。收到邀请后，在设备上打开兑换链接即可下载安装。

从源码构建

使用 Xcode 本地编译并运行 iOS 客户端：

open apps/ios/Holon.xcodeproj

在 Xcode 顶部选择目标设备或模拟器，按 Cmd + R 运行工程。

连接守护进程

方式 A：二维码扫码配对（推荐）

1. 在 Holon Web GUI 中打开 设置 -> 设备配对（或在 macOS 菜单栏中选择 配对设备）。
2. 打开 iOS 上的 Holon 应用。
3. 在首次引导页点击 扫描连接二维码。
4. 使用摄像头对准 Web GUI 或终端中展示的二维码。

应用读取邀请票据（/login#pair=<ticket>），调用 POST /api/auth/pairing/redeem/native 完成兑换，将会话凭据安全保存在 iOS Keychain 中，并直接打开 Agent 列表。

若摄像头不可用或未授予权限，可点击手动输入选项，将配对链接粘贴到票据输入框中完成兑换。

方式 B：手动配置连接

1. 在引导界面点击 手动连接。
2. 输入完整的 API 基础地址（例如 https://holon.example.com/api 或 http://192.168.1.50:7878/api）。
3. 输入 Bearer 令牌或初始化密钥。
4. 确认数据共享说明并点击 连接。

应用请求 POST /api/auth/session/exchange/native，将取得的会话凭据加密存入 Keychain，并从内存中清除原始令牌。

方式 C：组织单点登录（OIDC）

当守护进程已接入 OpenID Connect 身份认证：

1. 输入 API 基础地址。
2. 点击 通过组织登录。
3. 在系统弹出的浏览器窗口中完成身份认证。
4. 浏览器通过自定义 URL 回调返回 Holon 应用，应用自动将颁发的会话凭据存入 Keychain。

网络与安全注意事项

• 优先使用 HTTPS： 生产环境应始终使用 HTTPS 连接。如果连接明文 HTTP 地址，应用会在兑换或登录前弹出二次确认，提示明文传输风险。
• 本地网络权限： 在家庭或办公 Wi-Fi 局域网直连时，需要允许系统弹出的“本地网络（Local Network）”访问权限。
• 回环地址限制： 在真机上，127.0.0.1 和 localhost 指向手机本机，无法访问电脑上的服务。请使用电脑的局域网 IP 或 Tailscale 分配的域名。

移动端界面与交互体验

• 可搜索的 Agent 列表： 首页展示当前可访问的 Agent 及其状态摘要。支持按最近活跃度、回复状态或名称快速检索。
• 结果优先的会话时间线： 对话列表优先呈现最终 Markdown Brief 与交付成果。中间的工具调用和执行活动折叠进轮次中，方便快速审查结果，无需翻阅长日志。
• 后台任务状态卡片： 正在运行的后台任务或子 Agent 调度以轻量卡片形式展示，实时反馈执行进度。
• 模型切换与随时停止： 在输入框旁可查看并切换当前 Agent 绑定的模型路由，遇异常长任务可一键中止当前轮次。

原生文件与成果查看

在 Agent 会话界面点击动作菜单中的文件或文件夹图标，即可浏览该 Agent 关联的工作区文件与生成物：

• 大文件分页阅读： 阅读器采用分块磁盘分页加载，即便是体积庞大的 Markdown 报告、代码 Diff 或日志文件，滚动依然流畅。
• 文本搜索与代码高亮： 支持实时字面匹配高亮，并内置常见编程语言的语法高亮。
• 图片缩放与 PDF 预览： 生成的图像支持手势双指缩放，PDF 文件提供静态分页预览。
• 精准原文复制： 长按富文本区域并选择 选取原文（Select source text），即可直接复制未经格式化渲染的原始 Markdown 片段。

系统分享与分享收件箱

• 系统分享扩展（Share Extension）： 在 Safari 或文件等其他 App 中选中文本、网页链接或照片，调出 iOS 系统分享菜单，选择 Holon 并指定目标 Agent，点击 发送 即可直接投递。
• 离线暂存（Share Inbox）： 无网络连接时分享的内容会自动存入 设置 -> 分享收件箱（Share inbox），网络恢复后再确认发送或放弃。

AI 内容举报（Report AI Content）

若发现模型生成的回复存在事实错误、违法违规或偏离安全规范的内容，可直接在手机端发起举报：

1. 长按问题回复或该轮对话容器。
2. 在弹出菜单中选择 举报 AI 内容（Report AI content）。
3. 选择对应的违规类型（如有害信息、严重不实、版权侵权等）。
4. 可在文本框中补充具体描述。
5. 点击 提交举报。

客户端会向服务端的 POST /api/content-reports 提交认证后的独立回复快照。服务端仅保存该条回复的上下文证据以供管理员审计，不会上传整个会话历史或工作区敏感数据。

连接管理与系统诊断

• 管理多套连接： 在 设置 -> 连接 中查看已保存的服务器列表，左滑即可删除失效节点。
• 导出诊断报告： 在 设置 -> 诊断 中可生成脱敏后的诊断日志（包含网络状态、系统版本和统计计数器），用于排查同步与连接问题。

下一步

• 连接远程 Holon 运行时：了解通过 Tailscale 和反向代理的安全网络配置。
• 配置 OIDC 身份认证：了解企业单点登录与会话令牌管理。
• 连接 Android 客户端：了解原生 Android 客户端的配置与使用。