<!-- docs-updated: 2026-11-06 -->
# 从安装到第一个成果

本页主要面向 iOS / iPadOS；Android 的差异会单独说明。功能以所选版本的发布说明为准。

## 选择安装方式

先打开[版本中心](https://www.floe-agent.com/releases)，按产品选择 Floe Agent、Mac Bridge 或 iOS Bridge。GitHub iOS IPA 需要自行签名；想使用 TestFlight，可在[官网申请](https://www.floe-agent.com/#beta)，申请不等于立即获得测试资格。App Store 是否可安装以商店实际页面为准。

Android 选择对应公开测试版的签名 APK。可直接下载最新完整包，不必逐版升级；增量包只能用于其标明的精确基础版本。安装提示签名不一致时先保留数据，不要为完成安装而直接卸载。

## 完成一个 AI 任务

**准备：** 一个可用服务商的模型配置与 API Key；需要读图时选择支持图像输入的模型。云端请求由你选择的服务商处理，费用与数据政策也以该服务商为准。

1. 在模型设置中添加服务商、地址、Key 和模型。先进行简单文字对话，确认配置可用。
2. 新建任务并选择工作区；通过文件选择器加入一份不含敏感信息的测试资料。
3. 给出明确成果，例如：“根据这份资料整理一份待办清单，保存到当前工作区。”按需要授权资料与工具。
4. 打开输出文件核对内容、位置与格式；关闭再重开，确认成果已保存。

**遇到问题：** 认证错误先检查 Key 与地址；模型不支持图像时改用识图模型；文件不可访问时重新选择并授权原工作区。不要把工具返回成功当作文件已正确保存。

## 在设备端运行代码

**准备：** 足够的可用存储和设备内存。iOS 当前使用共享 ARM64 Linux 运行环境，任务与项目目录保持各自归属；运行包需适配客体架构。

1. 到执行环境设置下载并校验所需资源，再打开当前工作区的本地终端。
2. 执行 `pwd` 和 `uname -m`，核对目录与实际架构，然后按任务安装 Python、Node.js 或所需软件包。
3. 运行一个小程序，打开生成的文件；网页服务使用“作为网页服务运行”，待实际响应后再预览。
4. 结束时停止对应作业或服务。隐藏终端、关闭预览不等于停止后台任务。

**遇到问题：** 先查看安装、启动和运行输出。Android Alpha29 升级后若终端无法启动，在“设置 → 执行环境 → 本地环境”单独更新运行组件。资源修复前保留项目文件，不随意重置或删除数据。详见[终端与运行环境](USER_GUIDE.zh-CN.md#9-本地终端与-linux-性能配置)。

## 创建并保存一个 3D 模型

**准备：** 已提供原生 3D 工作台的 iOS/iPadOS 版本。导入的网格不自动拥有原生参数化历史；不同格式支持的操作不同。

1. 在创作流程中创建原生 3D 模型，先用简单几何建立可编辑成果。
2. 在同一模型中继续调整尺寸、孔或圆角；使用 AI 时明确当前模型及所需修改。
3. 核对几何、材质和视图，保存 `.floecad`，关闭后重开确认。
4. 按用途导出图片或受支持的 3D 格式，使用接收方工具再核对。

**遇到问题：** 格式只读时保留原文件，不把导入成功当作可编辑证明；几何失败先撤销到可恢复状态。详见[原生 3D 手册](USER_GUIDE.zh-CN.md#3d-模型统一工作台)。

## 区分两种 Bridge

| 产品 | 用途 | 连接前检查 |
| --- | --- | --- |
| Floe Bridge · Mac | 为同一台 Mac 上的 Floe 提供本机终端、文件和 MCP | 两个应用在同一台 Mac，双方确认同一配对码；不是 iPad 到 Mac 的远程桥 |
| Floe iOS Bridge | 独立的 iPhone/iPad 本机自动化桥 | 自行签名所需能力、设备设置与授权；1.0 不接入主 Floe App |

Mac Bridge：从[对应版本](https://www.floe-agent.com/releases?platform=bridge)安装，启动菜单栏应用，再在同一 Mac 的 Floe 中发起连接；双方核对验证码并确认。先检查目录、读取一个测试文件，再开始任务。断开后不自动重放命令。没有图标时重新启动应用；拒绝连接时检查两端版本与配对确认。

iOS Bridge：先阅读[固定版本安装说明](https://github.com/JiangNanGenius/floe-agent/blob/floe-ios-bridge-v1.0.0/FloeIOSBridge/INSTALL.zh-CN.md)。1.0 的签名材料需要 Network Extension 能力，不承诺任意重签方式兼容。按应用向导完成设备准备，在设备上批准客户端配对；默认只访问本机，需要时才开启局域网。操作后重新读屏核对，遇到“结果未确认”不要自动重复点击。

## 保存、恢复与反馈

Office、媒体和 3D 成果应分别在对应编辑器确认保存；另存和导出不会自动替代原件。Android 经外部编辑器或 Linux 修改文件时，等待写回完成再重开；存在冲突时保留恢复副本。重要资料始终保留独立备份。

仍有问题时，在[支持入口](https://github.com/JiangNanGenius/floe-agent/blob/main/SUPPORT.zh-CN.md)描述版本、设备、复现步骤、预期与实际结果；诊断和截图只主动提交必要部分，不附密码、Key 或私人文件。继续阅读[完整手册](USER_GUIDE.zh-CN.md)。