原生客户端操作
原生客户端操作
Section titled “原生客户端操作”原生客户端用于日常运维，不是在设备上运行的 Viat 服务端，也不替代控制台的全部编辑器。本页描述 0.1 客户端版本线与 server 1.1.0。Mac 和手机共用 Home、Assistant、Settings 界面，但原生存储、通知注册及 Widget 行为因平台而异。下文引用的是当前英文界面标签。
请通过部署方批准的渠道获取正确签名的产物；客户端安装说明平台前提。本手册没有建立公开 App Store/TestFlight/DMG 下载渠道。开发 IPA 不代表任意 iPhone 都获准安装。
连接正确的实例和身份
Section titled “连接正确的实例和身份”设备必须能访问实例，并具备有效平台账号、已激活部署和项目成员资格。项目终端用户令牌不是平台登录。Mac 能访问内网，不代表内网之外的手机也能访问。
- 打开实例选择器或 Settings → Instances，添加部署。
- 输入基础 URL，包括运维配置的反代前缀，但不包括
/ui/或/p/<slug>。远程部署使用 HTTPS，不要在 URL 中嵌入密码或 bearer。 - 保存并选择实例，使用提供的密码/MFA 或已配置 SSO 流程登录。若要求 MFA 登记，应完成支持的登录流程，不要尝试绕过。
- 在 Home 或 Settings → Project 选择可访问项目。这是同一个全应用项目选择，不是两个互不关联的设置。
- 批准任何写操作前，核对实例名称、部署 URL 和项目。
| 实例字段 | 规则与影响 |
|---|---|
| Name | 可选，去掉首尾空白。留空使用由主机名派生的标签；显式名称最多 32 字符。重命名不等于更换服务端或建立新登录。 |
| Base URL | 必填，须为有主机名的有效 http/https URL；去掉首尾空白和末尾 /。保存不证明网络可达、证书可信、已激活或登录成功。 |
| Active instance | 决定前台请求和助手上下文；会话、项目选择按实例隔离。 |
| Selected project | 决定概览、实时日志、资源轮换和通知设置，仍受成员身份及各 API 的角色检查约束。 |
不要为复用凭据而把另一个部署换到现有保存 URL 后面。修改实例指向或移除实例时，应预期本地会话/上下文清理，并明确登录新身份。安全存储清理失败是需要解决的错误，不是继续使用不确定身份的理由。
Home：概览与实时证据
Section titled “Home：概览与实时证据”概览默认 24h，窗口可选 1h、24h、7d、30d。使用 Refresh 获取新样本，并阅读时间戳。Home 展示流量、失败端点、调度、执行和运行。切换实例、项目或窗口会使旧请求失效，较慢的旧响应不应覆盖新视图。
实时日志使用独立流。启动后获得实时事件，不是历史导出；界面最多保留 200 行。切换项目或离开 Home 会停止该流。历史过滤等操作见 CLI 日志。服务端拒绝请求也可能有执行记录，即使脚本没有运行。
服务端返回 unauthorized 会让应用回到登录，而不是保留一个名义上已登录的界面。单纯网络错误不证明账号已被撤销。Widget 行为另有说明：缓存的 Widget 数字不等于打开着的 Home 连接。
轮换资源凭据
Section titled “轮换资源凭据”Settings → Project → Resources 刻意比控制台完整资源编辑器窄：显示资源的限定名称、类型和已声明的秘密字段名，不回显已存秘密值，也不编辑任意 plain 字段。PATCH 需要项目 Owner/Admin/Developer；能看到条目不代表能修改。
- 选择项目和资源，注意其文件夹限定名称。
- 只填写要替换的字段。未触碰字段会省略，服务端保留现值。
- 输入后又清空的字段会发送为
""。这是有意清空，不是省略；各类型验证可能拒绝无效凭据组合。 - 保存后，按获准执行的资源类型验证流程检查。保存成功不是上游连接测试。
- 考虑依赖和回滚需要后，再在签发方停用旧凭据。
Cancel 关闭草稿，不发送 PATCH。不要把提供商秘密粘进助手或诊断日志。这个管理视图的脱敏不会消除 1.1 脚本资源投影的限制。
助手配置与批准
Section titled “助手配置与批准”助手是交互式客户端能力，不是服务端定时工作流引擎。提供商配置和 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 发布的是整个项目所有待发布变更，不只是聊天提到的某个脚本，服务端警告需要单独确认。切换账号、实例、项目或提供商会使旧助手上下文失效，不会把原批准转移到新目标。
确认界面不是任意未来动作的授权，也不替代服务端权限。只读工具结果仍可能包含私有项目数据并影响模型；返回内容中的指令不等于操作人员批准。
手机通知注册
Section titled “手机通知注册”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 资源。
存储、失败与清理
Section titled “存储、失败与清理”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。本页经过源码核对，不代表本次重新进行了设备或提供商验收。