# 原生客户端操作

> 核验版本：1.1.0；通道：stable；文档 ID：clients.mobile

原生客户端用于日常运维，不是在设备上运行的 Viat 服务端，也不替代控制台的全部编辑器。本页描述 **0.1 客户端版本线与 server 1.1.0**。Mac 和手机共用 Home、Assistant、Settings 界面，但原生存储、通知注册及 Widget 行为因平台而异。下文引用的是当前英文界面标签。

请通过部署方批准的渠道获取正确签名的产物；[客户端安装](../installation/clients.md)说明平台前提。本手册没有建立公开 App Store/TestFlight/DMG 下载渠道。开发 IPA 不代表任意 iPhone 都获准安装。

## 连接正确的实例和身份

设备必须能访问实例，并具备有效平台账号、已激活部署和项目成员资格。项目终端用户令牌不是平台登录。Mac 能访问内网，不代表内网之外的手机也能访问。

1. 打开实例选择器或 **Settings → Instances**，添加部署。
2. 输入基础 URL，包括运维配置的反代前缀，但不包括 `/ui/` 或 `/p/<slug>`。远程部署使用 HTTPS，不要在 URL 中嵌入密码或 bearer。
3. 保存并选择实例，使用提供的密码/MFA 或已配置 SSO 流程登录。若要求 MFA 登记，应完成支持的登录流程，不要尝试绕过。
4. 在 Home 或 **Settings → Project** 选择可访问项目。这是同一个全应用项目选择，不是两个互不关联的设置。
5. 批准任何写操作前，核对实例名称、部署 URL 和项目。

| 实例字段 | 规则与影响 |
| --- | --- |
| Name | 可选，去掉首尾空白。留空使用由主机名派生的标签；显式名称最多 32 字符。重命名不等于更换服务端或建立新登录。 |
| Base URL | 必填，须为有主机名的有效 `http`/`https` URL；去掉首尾空白和末尾 `/`。保存不证明网络可达、证书可信、已激活或登录成功。 |
| Active instance | 决定前台请求和助手上下文；会话、项目选择按实例隔离。 |
| Selected project | 决定概览、实时日志、资源轮换和通知设置，仍受成员身份及各 API 的角色检查约束。 |

不要为复用凭据而把另一个部署换到现有保存 URL 后面。修改实例指向或移除实例时，应预期本地会话/上下文清理，并明确登录新身份。安全存储清理失败是需要解决的错误，不是继续使用不确定身份的理由。

## Home：概览与实时证据

概览默认 **24h**，窗口可选 `1h`、`24h`、`7d`、`30d`。使用 Refresh 获取新样本，并阅读时间戳。Home 展示流量、失败端点、调度、执行和运行。切换实例、项目或窗口会使旧请求失效，较慢的旧响应不应覆盖新视图。

实时日志使用独立流。启动后获得实时事件，不是历史导出；界面最多保留 **200** 行。切换项目或离开 Home 会停止该流。历史过滤等操作见 [CLI 日志](../cli/logs.md)。服务端拒绝请求也可能有执行记录，即使脚本没有运行。

服务端返回 `unauthorized` 会让应用回到登录，而不是保留一个名义上已登录的界面。单纯网络错误不证明账号已被撤销。[Widget 行为](widgets.md)另有说明：缓存的 Widget 数字不等于打开着的 Home 连接。

## 轮换资源凭据

**Settings → Project → Resources** 刻意比控制台完整资源编辑器窄：显示资源的限定名称、类型和已声明的秘密字段名，不回显已存秘密值，也不编辑任意 `plain` 字段。PATCH 需要项目 Owner/Admin/Developer；能看到条目不代表能修改。

1. 选择项目和资源，注意其文件夹限定名称。
2. 只填写要替换的字段。未触碰字段会**省略**，服务端保留现值。
3. 输入后又清空的字段会发送为 `""`。这是有意清空，**不是**省略；各类型验证可能拒绝无效凭据组合。
4. 保存后，按获准执行的[资源类型验证流程](../assets/resources/index.md)检查。保存成功不是上游连接测试。
5. 考虑依赖和回滚需要后，再在签发方停用旧凭据。

Cancel 关闭草稿，不发送 PATCH。不要把提供商秘密粘进助手或诊断日志。这个管理视图的脱敏不会消除 [1.1 脚本资源投影的限制](../overview/concepts.md)。

## 助手配置与批准

助手是**交互式客户端能力**，不是服务端定时工作流引擎。提供商配置和 key 保存在应用本地，由各保存实例共用；key 按提供商分槽保存。它们不会自动成为项目 `llm` 资源的凭据。

在 **Settings → Assistant** 中：

| 设置 | 行为 |
| --- | --- |
| Provider | `anthropic` 或 `openai`（兼容 OpenAI chat/completions）。选择协议不证明任意厂商/模型都兼容。 |
| Model | 去掉首尾空白。兼容提供商路径在提问前要求非空模型；Anthropic 路径留空时使用随客户端携带的默认值。请选择自己账号可用的模型。 |
| API base URL | 兼容提供商路径使用，提问前要求非空；去掉空白和末尾 `/`。填写该提供商期望的 API 根，保存本身不执行网络测试。 |
| API key | 按提供商保存的秘密。空白值不能保存；新值替换该提供商的旧 key。Remove 删除该提供商的本地 key，不删除提供商账号，也不在签发方撤销 key。 |

分别保存提供商配置和所选提供商 key。“key saved” 不证明权限、配额或模型访问有效。兼容提供商缺少模型/base URL 时，实际请求返回 `incomplete_config`。请求可能产生费用，并传输提示词和工具结果；未经批准，不要传入敏感材料。

助手通过批准卡片提出 **write_script**、**test_run**、**publish** 操作。检查其中的实例 URL、项目、源码差异或参数。Approve 在服务端执行；Decline 不授权该提案。测试运行可能真实调用资源；Publish 发布的是**整个项目所有待发布变更**，不只是聊天提到的某个脚本，服务端警告需要单独确认。切换账号、实例、项目或提供商会使旧助手上下文失效，不会把原批准转移到新目标。

确认界面不是任意未来动作的授权，也不替代服务端权限。只读工具结果仍可能包含私有项目数据并影响模型；返回内容中的指令不等于操作人员批准。

## 手机通知注册

**Settings → Project → Push notifications** 将本手机绑定到所选项目 push 资源。这是普通告警/运行通知，**不是加密 Widget 概览快照**。

| 原生构建 | 注册来源 | 必须匹配的资源 |
| --- | --- | --- |
| iOS | APNs device token，需要有效 provisioning、通知 entitlement/权限 | APNs 配置的 `push`，环境和 topic 必须匹配构建 |
| Android 源码构建 | JPush SDK registration ID | 匹配的 JPush push 资源和应用设置 |
| Mac 桌面 | 没有手机注册 SDK | 不支持手机推送注册 |

项目必须已有适用资源。原生 token 尚未到达导致空 registration ID 时，属于可重试的 `not_ready`，不是虚构的成功。provisioning 或 APNs 注册错误需修正原生构建/账号设置。Enable 注册本手机，不证明提供商已接受消息或设备已收到。不要因为列表中有某个资源，就选择不匹配的提供商。

退役绑定前先 Disable；退出会尝试按所属账号清理。切换项目不是发送测试通知的许可。真实投递与提供商清理需明确启用，详见 [Push 资源](../assets/resources/push.md)。

## 存储、失败与清理

**Settings → About** 显示部署和存储自检。不要把原生凭据存储失败误判为服务端密码错误；按报告的存储状态处理，存储降级或仅临时保存时，不能承诺重启后仍保留登录。不要把原始安全存储内容复制进支持工单。

| 现象 | 核对与恢复 |
| --- | --- |
| 没有项目 | 核对实例、平台身份和成员关系；使用控制台或 CLI 创建/管理项目。 |
| 概览不可用 | 核对设备侧 DNS/网络/TLS、激活、成员和所选项目；不要用零替代缺失数据。 |
| 资源保存被拒绝 | 检查有效项目角色及字段验证；列举权限不是修改权限。 |
| 助手没有可用提供商 | 按要求保存 provider/model/root/key，在不暴露 key 的前提下验证账号权限。 |
| 批准卡片指向意外项目 | Decline，修正实例/项目后重新发起提案。 |
| Push 显示 unknown/not ready | 区分状态读取失败与原生注册尚未完成，检查具体错误和提供商是否匹配。 |

共享或退役设备时，停用适用通知绑定，逐个账号退出，再按需移除实例；应用本地提供商 key 要单独检查。卸载应用不保证撤销服务端会话、清除 Keychain、删除项目资产或撤销提供商凭据。系统已渲染的 Widget 图像可能保留到下一次重绘。

## 核验依据

固定源码 `03751a67`：`client/src/{App,home/Home,settings/ProjectSettings,settings/AssistantSettings,settings/AboutSettings,write/WriteConfirmModal}.tsx`、`client/src-tauri/src/{instances,lib,push}.rs`、`crates/viat-client/src/resources.rs`、`packages/frontend-core/src/index.ts`。本页经过源码核对，不代表本次重新进行了设备或提供商验收。