AI 助手介绍与使用
Larktun iPhone/iPad App 提供两种 AI 助手：全局助手帮助你查找设备、打开服务和处理 App 内的任务；SSH 助手在终端会话中提供可检查、可编辑的命令建议。
两个助手共用 AI 来源和网络配置，开关独立，默认关闭。使用时可以选择 Apple 私有云计算（PCC），也可以接入云端或自建的兼容 API。
能做什么
| 助手 | 主要能力 | 操作边界 |
|---|---|---|
| 全局 AI 助手 | 查找设备、收藏、服务；打开 Web、SSH、RDP 入口；切换会话 | SSH/RDP 打开连接页面，认证和发起连接由你完成 |
| 全局 AI 助手 | 扫描服务、查询扫描进展、探测延迟与连接路径 | 使用当前账户与网络中的资源；扫描遵循范围确认规则 |
| 全局 AI 助手 | 整理收藏、预览和处理收到的文件、按需阅读网页与文件 | 内容读取需单独开启；部分修改可撤销，发送文件不可撤回 |
| SSH AI 助手 | 根据目标生成命令，解释终端文本，修改命令建议 | 默认只提供建议；插入命令不会自动回车 |
自动操作取决于所选模型的工具能力。仅建议模式仍可回答问题和提供页面入口，但不会替你执行全局助手的操作。
进入 AI 设置
- 使用包含 AI 助手功能的 Larktun iOS App，登录自己的账户。
- 在“我的”页面找到“SSH AI 助手”入口，进入配置页。全局助手面板中的“AI 设置”也可以打开同一页面。
- 在“AI 来源”中选择“Apple 私有云计算”或“自定义 API”。
- 按下文完成对应配置，阅读数据披露，再分别开启“全局 AI 助手”和“SSH AI 助手”。
配置页入口沿用“SSH AI 助手”名称，页内同时管理两个助手。更改 AI 来源或网络配置会取消正在进行的 AI 请求，请在完成当前回答后再切换。
配置 Apple 私有云计算（PCC）
PCC 使用 Apple 提供的私有云计算服务处理问题，无需填写 Base URL、模型或 API Key。问题与相关上下文会发送到 Apple 私有云计算，并非全部在本机完成。
开启步骤
- 在“AI 来源”中选择“Apple 私有云计算”。
- 点击“检查可用性”，查看设备状态和额度信息。
- 状态显示可用后，开启需要的助手，阅读并同意 PCC 数据披露。
- 全局助手可先运行“测试工具能力”，了解当前来源能否执行 App 操作。
- 打开助手，发送一个简单问题，例如“有几台设备在线？”或在 SSH 中询问“如何查看磁盘使用情况？”。
当前 App 的 PCC 入口要求 iOS/iPadOS 27 或更高版本，并会检查设备资格和系统服务状态。满足系统版本要求不代表一定可用。看到“此设备不支持 Apple 智能”或“当前不可用”时，可以稍后重新检查，或手动选择自定义 API。
额度与切换
PCC 额度由 Apple 管理。App 会展示“今日额度可用”“即将用尽”或“已用尽”等状态；系统提供恢复时间或额度选项时，页面会显示相应入口。额度状态暂不可用时，不代表额度无限或已经用尽。
额度用尽后，可以等待恢复，也可以手动切换到自定义 API 并重试。切换前检查新服务的请求目标、数据处理方式与费用；App 不会因为 PCC 不可用而自行把问题改发到另一个来源。
配置自定义 API
自定义 API 适合使用自己的模型服务、兼容网关或组网内自建模型。服务需要支持 App 所选的接口协议；普通聊天网页地址不能作为 API 地址使用。
1. 选择协议并填写地址
在“AI 来源”中选择“自定义 API”，然后填写 Provider 配置：
| 字段 | 填写方式 |
|---|---|
| 类型 | 根据服务选择 OpenAI-Compatible 或 Anthropic-Compatible |
| Base URL | 服务提供的 API 基础地址，包含它要求的版本路径，如 /v1 |
| 模型 | 服务实际支持的模型标识，按服务说明填写 |
| API Key | 需要鉴权时填写，并点击“保存 API Key”；无需鉴权的自建服务可留空 |
App 的请求路径如下：
| 类型 | Base URL 示例 | 最终请求地址 |
|---|---|---|
| OpenAI-Compatible | https://api.example.com/v1 | https://api.example.com/v1/chat/completions |
| Anthropic-Compatible | https://api.example.com/v1 | https://api.example.com/v1/messages |
这些是地址格式示例，请替换成服务实际提供的地址。App 不会自动补上 /v1；不同网关可能使用其他前缀。已填写完整且匹配的接口路径时，不会重复追加相同后缀。
API Key 仅保存在本机 Keychain，按 Larktun 账户和 Provider 隔离。退出登录会清除内存副本，但保留隔离存储的密钥；需要移除时，请在配置页点击“删除 API Key”。留空时不发送认证请求头；如果已有保存的 Key，要先删除才能改用无 Key 请求。
2. 选择请求网络
| 路由 | 适用场景 |
|---|---|
| 自动 | 根据服务主机判断路径；100.64.0.0/10、MagicDNS 和识别到的 tailnet 名称使用 Tailnet Proxy |
| 系统直连 | 使用设备系统网络访问模型服务 |
| Tailnet Proxy | 通过 App 的专用组网代理访问模型服务 |
使用组网内服务前，先确认 Larktun 已连接、模型主机可达，端口和访问权限正确。自动模式对普通局域网地址或自定义域名的判断可能不符合实际部署，应检查“实际路由”，必要时手动选择。
优先使用 HTTPS。HTTP 地址会触发额外风险提示，只有确认是可信私有自建服务后才继续。组网链路不会改变 API 服务自身的鉴权要求。
3. 测试后开启
- 检查“实际发送至”和“实际路由”。
- 点击“测试连接”。测试会发送最小请求，不携带终端内容，无需先开启助手；按提示审阅数据披露和 HTTP 风险。
- 显示“连接成功”后，点击“测试工具能力”。该测试使用固定探测请求，不携带设备、收藏、服务或终端内容。
- 查看结果：原生工具调用、结构化动作或仅建议模式。前两类可以支持全局助手操作；仅建议模式需要换用兼容的模型或服务才能执行操作。
- 按需要开启两个助手的独立开关。
测试请求也会调用所选服务，可能消耗该服务的额度。连接测试成功只说明本次 API 请求可用；不代表设备、SSH/RDP 认证或所有工具操作已验证。
使用全局 AI 助手
连接云雀通网络并开启全局助手后，从 App 中的助手入口开始对话。iPad 提供可拖动的悬浮按钮和侧边面板。
| 目标 | 示例提问 | 预期结果 |
|---|---|---|
| 查看设备 | “有几台设备在线？” | 查询资源后列出在线情况 |
| 打开服务 | “打开家庭 NAS 的管理页面” | 找到已知 Web 地址并打开；多个目标时请你选择 |
| 准备 SSH | “打开开发机的 SSH” | 打开连接页面，由你认证并连接 |
| 发现服务 | “扫描这台设备上的服务” | 启动扫描并显示任务进展 |
| 检查连接 | “检查 NAS 延迟，看看走直连还是中继” | 实际探测后解释延迟、丢包和路径 |
| 整理收藏 | “把这个页面保存为收藏” | 保存当前入口并提供撤销 |
| 查看文件 | “我最近收到了哪些文件？” | 列出 Taildrop 接收和浏览器下载的文件 |
面板可以显示执行步骤、任务状态、确认卡和撤销入口。可撤销操作通常在约半小时内有效；关闭 SSH/RDP 会话会断开连接，已发送文件也无法撤回。
如果已有收藏或服务无法被助手找到，可以在 AI 设置中使用“关联已有资源…”检查它们与当前账户的关联。
阅读网页与文件
- 在 AI 设置中单独开启“允许读取网页和文件内容”。
- 在内置浏览器打开目标页面，使用“问 AI 助手”，例如“总结这个页面的告警”。也可以在助手中明确指出目标文件。
- 查看回答，必要时继续询问某一段或某个问题。
- 不再需要内容读取时，可关闭该开关；查找与打开资源等其他功能仍可使用。
支持可见网页文字、文本文件、PDF 文字和图片 OCR。图片文字识别在本机进行，识别出的文字再发送到所选 AI 来源；这项能力不等于通用图片理解。音视频和压缩包等格式不支持直接读取内容。
全局助手可以控制浏览器前进、后退、刷新和停止加载；网页点击、填表、提交和修改配置仍由你操作。收到的文件操作也不等于访问服务器上的任意 SFTP 文件。
使用 SSH AI 助手
- 先建立 SSH 连接，再打开会话中的
Copilot面板。 - 描述目标，例如“查看磁盘使用情况”“给出查看最近 100 行服务日志的命令”。
- 检查回答中的命令和风险提示，按需直接编辑或让 AI 修改。
- 点击“复制”，或点击“插入”放入终端输入区，确认无误后自行回车。
选中的终端文本只在点击“问 AI”时发送，可以在面板中查看或移除。自动携带可见终端内容、主机名、用户名和地址默认关闭，可在设置中按需开启。
实验性“发送并回车”
启用“显示‘发送并回车’”后，可以选择直接发送、仅高风险确认或每次确认。直接发送模式下，点击按钮即写入命令并回车，不再逐次确认。
发送前确认终端处于空白 Shell 提示符，而非密码输入、vim、交互程序或已有半行输入。风险提示是辅助判断，不能保证命令安全；涉及生产配置、删除和覆盖时应逐条审核。
数据与权限
- 主动提问会发送问题与当前 AI 对话；全局助手还会发送为回答所查询到的设备名称、IP/MagicDNS、系统、状态及收藏和服务地址等信息。
- 网页和文件正文需单独开启读取后才会发送；SSH 上下文由你控制。内容会做凭据清洗，但发送前仍应检查敏感信息。
- 自定义 API 的计费、日志保留和数据处理由服务提供方决定；PCC 按设置页的 Apple 数据披露处理。
- 全局助手使用当前账户与网络范围中的资源，不会替你增加访问权限。
- 明确要求的日常操作可直接执行。模型推测的目标地址，或读取外部内容后发起会改变状态的操作，会按规则要求确认。
- 可在设置中关闭助手或“清除所有 AI 会话”。清除本机对话不会删除服务提供方可能保留的数据，也不会自动删除 API Key。
常见问题
| 现象 | 处理方式 |
|---|---|
| 开关无法开启 | 按提示补全 Base URL 和模型，审阅数据披露；PCC 检查可用状态 |
| PCC 不可用 | 查看系统版本、设备资格和服务状态，重新检查，或手动配置自定义 API |
| PCC 额度用尽 | 查看恢复时间或额度选项，等待恢复，或手动切换来源后重试 |
| API 返回 401/403 | 检查已保存的 Key、模型权限和服务自身的鉴权规则 |
| API 返回 404 或协议错误 | 检查 Provider 类型、版本路径及最终请求地址是否与服务一致 |
| 连接超时或组网代理不可用 | 检查服务地址、Larktun 连接、主机端口、访问规则及实际路由 |
| 能聊天，不能操作 App | 运行“测试工具能力”，确认是否为仅建议模式；更换兼容模型或服务 |
| 流式回答不正常 | 尝试关闭“流式输出”，再次检查服务兼容性 |
| 无法读取网页或文件 | 检查内容读取开关、网页是否已加载、文件是否下载完成及格式是否支持 |
| 找不到设备或收藏 | 确认当前账户与网络、资源关联和实际列表，明确目标名称后重试 |