yaoyao/docs/verification/server-name.md

服务器统一名称

2026-09-07。服务器名称由 Web 服务端统一保存，同一服务上的 Agent 共用。Web、iOS 和安卓均可读取；管理员可以修改，普通账号只读。名称留空时统一显示服务端主机名。

入口与同步

• Web：设置 → 登录与安全 → 服务器名称；侧栏账号说明同步显示名称。
• iOS：设置 → 服务器与账号 → 服务器统一名称；同一地址的已保存账号名称随之更新。原本的手机备注作为旧服务的备用备注保留。
• 安卓：设置 → 服务器统一名称；服务器账号列表缓存同步更新。

首次登录、账号切换、返回前台和打开设置时读取最新配置。Bot 模式复用现有事件响应中的名称快照，普通聊天复用 HTTP/SSE 的 server.identity.changed 通知。已有编辑草稿保留；如其他端先保存，当前编辑页提示冲突并提供重新载入。

协议与存储

GET /api/app/server-identity 返回 serverId、name、displayName、revision。PUT 接收 name、expectedRevision、expectedServerId，沿用身份认证、管理员权限、Origin 和 CSRF 校验。

名称去掉首尾空白，最多 100 个 UTF-16 单元，拒绝内部控制字符。客户端提交编辑开始时的版本和服务器 ID；过期版本或更换连接目标返回 409，不覆盖已有值。服务端兼容明确指定当前目标的简单调用，因此两个 expected 字段可省略；三端界面始终发送这两个字段。

数据保存在现有 workspace.sqlite3 的独立 server_identity 表中。首次初始化生成稳定 ID；名称更新在事务中完成，重启后保留。Agent 名称、服务器连接地址和远程节点配对备注沿用原配置。

验证

• 16 项服务端与客户端专项测试通过：持久化、恢复主机名、非法输入、过期版本、目标服务器校验、普通账号只读、编辑草稿及设置回归。
• 认证与工作区回归测试另外 56 项通过。
• Web 双窗口测试通过：一端保存，另一端无需刷新即可收到名称。
• iOS AppModel 账号隔离测试及真实设置页面测试通过：读取 Web 名称、保存 iOS 名称、重启应用后保留。
• 安卓真实设置组件、服务端读写和 Room 缓存验证通过：读取 iOS 名称、保存“家里的 Mac”、账号列表缓存更新，错误账号、地址和旧版本被忽略，普通用户组件只读。
• Web 最终读回安卓保存的“家里的 Mac”。三端构建及 Android Lint 通过。

联动验收顺序：启动 tests/fixtures/workspace-server.ts（18804/19124），运行 playwright.server-name.config.ts 的 two clients 用例，再运行 iOS testUnifiedServerNamePersistsThroughSettings、安卓 ServerIdentitySyncTest，最后运行 SERVER_NAME_NATIVE_ROUNDTRIP=1 npx playwright test -c playwright.server-name.config.ts -g 'saved by Android'。

Web 设置截图。iOS、安卓截图在各自仓库的服务器名称验收目录。均使用隔离服务及模拟器，未进行生产发布或真机安装。