فهرست منبع

发布 v0.4.62:统一桌面登录并支持子账号注册开通

Samien 1 ماه پیش
والد
کامیت
e6a2af792e
62فایلهای تغییر یافته به همراه2098 افزوده شده و 310 حذف شده
  1. 6 6
      README.md
  2. 56 0
      design-qa.md
  3. 1 0
      desktop/boot-icons.svg
  4. 588 1
      desktop/boot.css
  5. 65 4
      desktop/boot.html
  6. 172 23
      desktop/boot.js
  7. 2 1
      desktop/core-lifecycle.test.mjs
  8. 3 1
      desktop/lifecycle.test.mjs
  9. 136 136
      desktop/main.mjs
  10. 16 12
      desktop/mode-switch.test.mjs
  11. 131 0
      desktop/onboarding-flow.test.mjs
  12. 116 0
      desktop/onboarding.mjs
  13. 85 0
      desktop/onboarding.test.mjs
  14. 4 0
      desktop/preload.cjs
  15. 0 5
      desktop/remote-login-preload.cjs
  16. 0 21
      desktop/remote-login.css
  17. 0 17
      desktop/remote-login.html
  18. 0 23
      desktop/remote-login.js
  19. 65 10
      desktop/remote-login.mjs
  20. 37 0
      desktop/remote-login.test.mjs
  21. 4 3
      desktop/service-manager.mjs
  22. 3 1
      desktop/service-sync.test.mjs
  23. 4 1
      desktop/startup-feedback.test.mjs
  24. 8 0
      desktop/test-support/onboarding.mjs
  25. 1 0
      desktop/update-entry.test.mjs
  26. 1 1
      docker.env.example
  27. 23 0
      docs/design/desktop-onboarding/README.md
  28. BIN
      docs/design/desktop-onboarding/approved-design.png
  29. BIN
      docs/design/desktop-onboarding/preview-local-account.png
  30. BIN
      docs/design/desktop-onboarding/preview-local-install.png
  31. BIN
      docs/design/desktop-onboarding/preview-narrow.png
  32. BIN
      docs/design/desktop-onboarding/preview-remote.png
  33. BIN
      docs/design/desktop-onboarding/remote-dark.png
  34. BIN
      docs/design/desktop-onboarding/remote-login.png
  35. BIN
      docs/design/desktop-onboarding/remote-narrow.png
  36. 7 7
      docs/docker-install.md
  37. 44 0
      docs/releases/v0.4.62.md
  38. 15 2
      docs/subaccount-permissions.md
  39. 62 0
      docs/verification/2026-09-21-subaccount-bot.md
  40. 2 2
      package-lock.json
  41. 1 1
      package.json
  42. 3 3
      release.json
  43. 1 1
      scripts/build-desktop.mjs
  44. 42 0
      scripts/preview-desktop-onboarding.mjs
  45. 1 1
      src/client/App.vue
  46. 5 0
      src/client/api/admin.ts
  47. 6 0
      src/client/api/auth.ts
  48. 3 3
      src/client/components/app/DesktopModePanel.vue
  49. 9 3
      src/client/components/app/SystemManagementPanel.vue
  50. 1 0
      src/client/env.d.ts
  51. 5 1
      src/client/stores/auth.ts
  52. 25 2
      src/client/views/ConversationsView.vue
  53. 36 10
      src/client/views/LoginView.vue
  54. 3 1
      src/server/app.ts
  55. 37 4
      src/server/localAuth.ts
  56. 30 0
      src/server/routes.ts
  57. 23 0
      src/server/subaccountAccess.ts
  58. 1 2
      src/server/workspaceRoutes.ts
  59. 1 0
      src/shared/types.ts
  60. 2 1
      tests/client/settingsCenterDialog.test.ts
  61. 61 0
      tests/e2e/workspace-chat.spec.ts
  62. 145 0
      tests/server/subaccountRegistration.test.ts

+ 6 - 6
README.md

@@ -1,6 +1,6 @@
 # 夭夭 AI
 
-当前 Web 与 macOS 桌面发布版本:**v0.4.61**。桌面版提供 Apple Silicon(arm64)DMG,详见 [发布说明](docs/releases/v0.4.61.md)。
+当前 Web 与 macOS 桌面发布版本:**v0.4.62**。桌面版提供 Apple Silicon(arm64)DMG,详见 [发布说明](docs/releases/v0.4.62.md)。
 
 夭夭 AI 为网页、iOS 和安卓提供统一的 Agent、群聊、文件库及语音配置服务。Hermes 通过标准 9119 HTTP/WebSocket 接口执行任务。
 
@@ -40,7 +40,7 @@ Web 数据默认保存在 `~/.yaoyao`,可用 `YAOYAO_HOME` 指定(兼容 `HE
 
 ## macOS 桌面版
 
-在 [v0.4.61 发布页](https://github.com/Lsamien/yaoyao/releases/tag/v0.4.61) 下载 `Yaoyao-0.4.61-arm64.dmg`,将“夭夭”拖到应用程序后打开。首次启动会核对并同步配套本机 Web 服务;普通退出保留后台运行,“停止后台服务并退出”可完整停止本应用管理的后台。详细说明见 [macOS App](docs/macos-app.md)。
+在 [v0.4.62 发布页](https://github.com/Lsamien/yaoyao/releases/tag/v0.4.62) 下载 `Yaoyao-0.4.62-arm64.dmg`,将“夭夭”拖到应用程序后打开。首次启动会核对并同步配套本机 Web 服务;普通退出保留后台运行,“停止后台服务并退出”可完整停止本应用管理的后台。详细说明见 [macOS App](docs/macos-app.md)。
 
 此 DMG 使用 Apple Development 开发签名,未做 Apple 公证。
 
@@ -50,11 +50,11 @@ Web 数据默认保存在 `~/.yaoyao`,可用 `YAOYAO_HOME` 指定(兼容 `HE
 
 | 镜像 | 架构 |
 | --- | --- |
-| `samienluo/yaoyao:v0.4.61-amd` | AMD64 |
-| `samienluo/yaoyao:v0.4.61` | 自动匹配 AMD64 / ARM64 |
-| `samienluo/yaoyao:latest` | 最新稳定版通用镜像,当前与 `v0.4.61` 相同 |
+| `samienluo/yaoyao:v0.4.62-amd` | AMD64 |
+| `samienluo/yaoyao:v0.4.62` | 自动匹配 AMD64 / ARM64 |
+| `samienluo/yaoyao:latest` | 最新稳定版通用镜像,当前与 `v0.4.62` 相同 |
 
-准备好 Docker Engine/Compose 和容器可访问的 Hermes 9119 服务,在仓库目录将 `docker.env.example` 复制为 `docker.env`。配置上游地址,并设置 `HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.61`(或 `samienluo/yaoyao:latest`),即可使用远程镜像:
+准备好 Docker Engine/Compose 和容器可访问的 Hermes 9119 服务,在仓库目录将 `docker.env.example` 复制为 `docker.env`。配置上游地址,并设置 `HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.62`(或 `samienluo/yaoyao:latest`),即可使用远程镜像:
 
 ```sh
 docker compose --env-file docker.env pull web

+ 56 - 0
design-qa.md

@@ -1,3 +1,59 @@
+# 桌面单页安装与登录设计核对
+
+final result: passed
+
+## 设计与证据
+
+- 视觉依据:`docs/design/desktop-onboarding/approved-design.png`,1672 × 941 px,包含同一设计的本机安装、远程登录两个状态。它是展示画板,不是两个运行窗口。
+- 浏览器实现:`preview-local-install.png`、`preview-local-account.png`、`preview-remote.png`,均在 `docs/design/desktop-onboarding/`。使用生产 `boot.html`、CSS、JS 和状态控制器,服务行为由预览适配器模拟。
+- Electron 实现:同目录 `remote-login.png`、`remote-dark.png`、`remote-narrow.png`;真实主窗口、IPC、模拟 HTTP 服务器完成认证。
+- 默认核对视口:1280 × 832 CSS px;Electron 原生标题栏下内容区约 1280 × 828 px。截图密度为 1;使用完整页面截图时高度可能比视口略长。
+- 窄窗口:720 × 560(Electron),390 × 844(浏览器补充响应式检查),均无横向溢出,内容可纵向滚动。
+- 归一化:分别比较设计画板中两个白色应用区域与实现的页面内容区域,排除画板标题、外围留白和说明。保留原始截图,未将不同屏幕宽度的比较称为逐像素复刻。宽窗口采用 820 px 内容列,延续参考的单列步骤、并排服务器选择和全宽主按钮。
+- 全视图对照:在同一次视觉检查输入中打开设计画板、安装中截图与远程登录截图;另检查创建管理员、深色及窄窗口截图。
+- 重点区域:对照服务器选项、连接反馈、表单标签与主按钮。全尺寸截图中这些文字清晰可读,不需要再放大裁剪。
+
+## 核对结果
+
+- 字体与层级:沿用系统中文字体及现有品牌图;26 px 页面标题、17 px 区块标题、13–14 px 表单文字。修复“确认密码”标签换行,中文产品名使用准确的“夭夭”。
+- 间距与布局:服务器选择始终可见;准备与账号步骤由分隔线分组,当前步骤突出。默认桌面窗口下远程登录和本机创建账号的主按钮及页底控件完整可见。
+- 颜色:沿用白色画布、黑色主按钮、灰色次级面和绿色成功提示;深色模式对应既有色值,错误不会仅靠颜色表达。
+- 资产:复用项目品牌图片;图标来自已安装的 `@vicons/tabler`,未绘制近似图标或引入额外字体、图片服务。
+- 文案与内容:本机准备绑定真实服务状态;没有可测量百分比时使用不定进度。首次初始化与已有账号由服务响应决定。准备完成后收起详情,保留成功摘要与展开入口。
+- 交互:本机/远程选择、安装详情、帮助、密码显示、必填与确认密码、重新检测、地址修改后的凭据清空均有实现。登录完成后只导航原主窗口。
+- 可访问性:明确标签、原生单选框、键盘焦点、44 px 输入/按钮、页内 alert/status 与减少动画设置。
+
+## 迭代记录
+
+1. P2:初版默认窗口的远程登录页底控件略超出视口,主按钮与服务器选择左边缘不齐。
+   修复:调整步骤与区块间距,主按钮移出缩进的字段区域。重新截图 `preview-remote.png`,Electron 测试断言 footer 位于窗口内。
+2. P2:本机创建管理员的“确认密码”标签换行,已完成安装列表占用过多高度。
+   修复:增加标签列宽、禁止标签断行,准备完成后收起进度列表并保留详情摘要。重新截图 `preview-local-account.png`;浏览器检查 footer 底部为 809.89 px,视口高 832 px。
+3. 最终检查:远程登录、本机安装中、本机账号、深色、窄窗口均无待修复的 P0/P1/P2 问题。浏览器控制台无 warning/error。
+
+## 有意保留的差异与验证边界
+
+- 设计图的示例百分比替换为真实阶段进度;“安装组件”改为“准备服务组件”,覆盖安装和已有环境复用。
+- 当前服务器尚未检测完成时,不预先承诺创建管理员;检测后才切换为“创建管理员”或“登录账号”。
+- 安装与登录使用现有真实服务逻辑;浏览器预览仅演示交互。未连接用户的真实远程服务器执行登录。
+- 本次生成了桌面运行资源并验证;没有发布版本或替换用户已安装的 App。
+
+## 实现检查清单
+
+- [x] 单主窗口内完成服务器选择、安装准备及登录。
+- [x] 登录错误、安装重试、电脑授权异常保持在页内。
+- [x] 凭据绑定已检测服务器,IPC 限制在本地可信主页面。
+- [x] 默认窗口、窄窗口和深色模式核对。
+- [x] 服务管理、认证、生命周期集成验证与类型检查。
+
+## 自动化验证结果
+
+- 桌面完整测试:51 项通过,0 项失败。
+- 前端认证与设置相关测试:23 项通过。
+- 完整构建、类型检查与桌面资源打包通过。
+
+---
+
 # 聊天气泡外观 · 三端设计验收(2026-09-21)
 
 ## Findings

تفاوت فایلی نمایش داده نمی شود زیرا این فایل بسیار بزرگ است
+ 1 - 0
desktop/boot-icons.svg


+ 588 - 1
desktop/boot.css

@@ -1 +1,588 @@
-:root{color-scheme:light dark;font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#f7f7f7;color:#202020}body{margin:0;min-height:100vh;display:grid;place-items:center}main{max-width:420px;padding:32px;text-align:center}img{border-radius:18px}h1{font-size:24px;margin:24px 0 12px}p{font-size:15px;line-height:1.7;white-space:pre-line}button{font:inherit;min-height:44px;padding:10px 20px;border:1px solid #aaa;border-radius:10px;background:transparent;color:inherit;cursor:pointer;margin:8px}button:focus-visible{outline:2px solid currentColor;outline-offset:3px}button:disabled{opacity:.5;cursor:default}@media(prefers-color-scheme:dark){:root{background:#151515;color:#eee}button{border-color:#777}}
+:root {
+  color-scheme:light dark;
+  --canvas:#fff;
+  --soft:#f2f2ef;
+  --text:#1f1f1d;
+  --muted:#656560;
+  --line:#ddddda;
+  --solid:#20201e;
+  --on-solid:#fff;
+  --success:#377a54;
+  --danger:#b33d33;
+  --focus:rgba(31,31,29,.16);
+  font:14px/1.5 -apple-system,BlinkMacSystemFont,"PingFang SC","Microsoft YaHei",sans-serif;
+  color:var(--text);
+  background:var(--canvas)
+}
+* {
+  box-sizing:border-box
+}
+body {
+  margin:0
+}
+button,input {
+  font:inherit;
+  color:inherit
+}
+button {
+  cursor:pointer
+}
+button:disabled {
+  cursor:default;
+  opacity:.52
+}
+input[type=radio],input[type=checkbox] {
+  accent-color:var(--solid);
+  width:16px;
+  height:16px;
+  margin:0;
+  flex:none
+}
+button:focus-visible,input:focus-visible,summary:focus-visible {
+  outline:2px solid var(--solid);
+  outline-offset:3px
+}
+[hidden] {
+  display:none!important
+}
+.sr-only {
+  position:absolute;
+  width:1px;
+  height:1px;
+  overflow:hidden;
+  clip-path:inset(50%);
+  white-space:nowrap
+}
+svg {
+  width:20px;
+  height:20px;
+  flex:none
+}
+h1,h2,p {
+  margin:0
+}
+.page {
+  width:min(820px,calc(100% - 80px));
+  margin:20px auto 20px
+}
+.brand {
+  display:flex;
+  align-items:center;
+  justify-content:space-between
+}
+.brand>div {
+  display:flex;
+  align-items:center;
+  gap:10px
+}
+.brand img {
+  object-fit:contain
+}
+.brand strong {
+  font-size:24px;
+  font-weight:650
+}
+.brand>span {
+  font-size:12px;
+  color:var(--muted)
+}
+.intro {
+  margin-top:16px
+}
+.intro h1 {
+  font-size:26px;
+  line-height:1.4;
+  letter-spacing:-.035em;
+  font-weight:650
+}
+.intro p {
+  margin-top:4px;
+  color:var(--muted)
+}
+.steps {
+  display:flex;
+  align-items:center;
+  justify-content:center;
+  gap:0;
+  list-style:none;
+  margin:20px 0 18px;
+  padding:0;
+  font-size:13px
+}
+.steps li {
+  display:flex;
+  align-items:center;
+  gap:10px;
+  color:var(--muted)
+}
+.steps li+li:before {
+  content:"";
+  width:72px;
+  height:1px;
+  background:var(--line);
+  margin:0 20px 0 10px
+}
+.step-dot {
+  width:28px;
+  height:28px;
+  border-radius:50%;
+  display:grid;
+  place-items:center;
+  background:var(--soft);
+  color:var(--muted)
+}
+.step-dot b {
+  font-weight:500
+}
+.step-dot svg {
+  display:none;
+  width:18px;
+  height:18px
+}
+.steps [aria-current=step] {
+  color:var(--text)
+}
+.steps [aria-current=step] .step-dot {
+  color:var(--on-solid);
+  background:var(--solid)
+}
+.steps .complete .step-dot {
+  background:var(--success);
+  color:#fff
+}
+.steps .complete b {
+  display:none
+}
+.steps .complete svg {
+  display:block
+}
+.section {
+  padding:14px 0;
+  border-top:1px solid var(--line)
+}
+.choice-section {
+  border-top:0;
+  padding-top:0
+}
+h2 {
+  display:flex;
+  gap:20px;
+  align-items:baseline;
+  font-size:17px;
+  font-weight:630;
+  line-height:1.5
+}
+h2>span:first-child {
+  font-variant-numeric:tabular-nums
+}
+.inset {
+  margin-left:42px
+}
+.muted {
+  color:var(--muted);
+  font-size:13px;
+  margin-top:4px
+}
+.pending h2 {
+  color:var(--muted)
+}
+.mode-options {
+  display:grid;
+  grid-template-columns:1fr 1fr;
+  gap:14px;
+  border:0;
+  margin:12px 0 0;
+  padding:0;
+  min-width:0
+}
+.mode-option {
+  display:flex;
+  align-items:center;
+  gap:16px;
+  min-height:74px;
+  padding:15px 18px;
+  border:1px solid var(--line);
+  border-radius:10px;
+  cursor:pointer
+}
+.mode-option:has(:checked) {
+  border-color:var(--solid);
+  background:var(--soft);
+  box-shadow:inset 0 0 0 .5px var(--solid)
+}
+.mode-option:has(:focus-visible) {
+  outline:2px solid var(--solid);
+  outline-offset:3px
+}
+.mode-option:has(:disabled) {
+  cursor:default
+}
+.mode-option span {
+  min-width:0
+}
+.mode-option strong {
+  display:block;
+  font-size:14px;
+  font-weight:600
+}
+.mode-option small {
+  display:block;
+  color:var(--muted);
+  font-size:12px;
+  margin-top:4px
+}
+.mode-icon {
+  width:27px;
+  height:27px
+}
+.installation {
+  background:var(--soft);
+  border-radius:10px;
+  padding:4px 20px;
+  margin-top:12px
+}
+.install-steps {
+  list-style:none;
+  margin:0;
+  padding:0
+}
+.install-steps li {
+  display:flex;
+  align-items:center;
+  gap:14px;
+  padding:8px 0;
+  font-size:14px
+}
+.install-steps li+li {
+  border-top:1px solid var(--line)
+}
+.install-steps small {
+  margin-left:auto;
+  color:var(--muted);
+  font-size:12px
+}
+.install-steps svg {
+  width:18px;
+  height:18px;
+  color:var(--muted)
+}
+.install-steps .complete svg,.install-steps .complete small {
+  color:var(--success)
+}
+.install-steps .active svg {
+  color:var(--text);
+  animation:spin 1.2s linear infinite
+}
+.install-steps .active small {
+  color:var(--text)
+}
+progress {
+  display:block;
+  width:100%;
+  height:7px;
+  margin:10px 0 12px;
+  accent-color:var(--solid)
+}
+summary {
+  display:flex;
+  align-items:center;
+  gap:7px;
+  list-style:none;
+  cursor:pointer;
+  color:var(--muted);
+  font-size:12px;
+  min-height:32px
+}
+summary::-webkit-details-marker {
+  display:none
+}
+summary svg {
+  width:16px;
+  height:16px
+}
+details[open] summary svg {
+  transform:rotate(90deg)
+}
+pre {
+  font:12px/1.65 ui-monospace,monospace;
+  white-space:pre-wrap;
+  overflow-wrap:anywhere;
+  max-height:130px;
+  overflow:auto;
+  color:var(--muted);
+  margin:2px 0 10px
+}
+label[for] {
+  font-size:13px
+}
+.connection-row {
+  display:flex;
+  gap:10px;
+  margin-top:6px
+}
+.connection-row input {
+  flex:1;
+  min-width:0
+}
+#connection-form {
+  margin-top:8px
+}
+input:not([type=checkbox],[type=radio]) {
+  width:100%;
+  height:44px;
+  padding:0 13px;
+  border:1px solid var(--line);
+  border-radius:9px;
+  background:var(--canvas);
+  min-width:0
+}
+input::placeholder {
+  color:var(--muted);
+  opacity:.85
+}
+input:not([type=checkbox],[type=radio]):focus {
+  border-color:var(--solid);
+  box-shadow:0 0 0 3px var(--focus);
+  outline:0
+}
+input[aria-invalid=true] {
+  border-color:var(--danger)
+}
+.secondary {
+  min-height:44px;
+  padding:9px 16px;
+  border:1px solid var(--line);
+  border-radius:9px;
+  background:var(--canvas);
+  white-space:nowrap
+}
+.secondary:hover {
+  background:var(--soft)
+}
+.primary {
+  display:flex;
+  align-items:center;
+  justify-content:center;
+  position:relative;
+  width:100%;
+  min-height:46px;
+  padding:10px 40px;
+  background:var(--solid);
+  color:var(--on-solid);
+  border:1px solid var(--solid);
+  border-radius:10px;
+  font-weight:550
+}
+.primary svg {
+  position:absolute;
+  right:18px
+}
+.primary:hover:not(:disabled) {
+  opacity:.9
+}
+#prepare-local {
+  margin-top:14px
+}
+#login-form {
+  margin-top:12px
+}
+#credentials {
+  display:grid;
+  gap:12px
+}
+.field {
+  display:grid;
+  grid-template-columns:60px minmax(0,1fr);
+  align-items:center;
+  gap:12px
+}
+.password-input {
+  position:relative
+}
+.password-input input {
+  padding-right:48px
+}
+.eye-button {
+  position:absolute;
+  right:0;
+  top:0;
+  display:grid;
+  place-items:center;
+  width:44px;
+  height:44px;
+  background:transparent;
+  border:0;
+  color:var(--muted);
+  border-radius:9px
+}
+#submit {
+  margin-top:14px
+}
+#waiting {
+  margin-top:14px;
+  background:var(--soft);
+  color:var(--muted);
+  border-color:var(--soft);
+  opacity:1
+}
+.status {
+  font-size:13px;
+  margin-top:10px;
+  overflow-wrap:anywhere
+}
+.status:empty {
+  display:none
+}
+.status.success {
+  color:var(--success)
+}
+.status[role=alert],.error {
+  color:var(--danger)
+}
+.error {
+  font-size:13px;
+  margin:12px 0;
+  overflow-wrap:anywhere
+}
+.actions {
+  display:flex;
+  gap:10px;
+  margin-top:12px;
+  flex-wrap:wrap
+}
+footer {
+  display:flex;
+  align-items:center;
+  justify-content:space-between;
+  margin-top:0;
+  font-size:13px;
+  color:var(--muted)
+}
+.remember {
+  display:flex;
+  align-items:center;
+  gap:8px;
+  min-height:44px;
+  cursor:pointer
+}
+.text-button {
+  background:transparent;
+  border:0;
+  padding:8px 0;
+  min-height:44px;
+  color:var(--muted);
+  text-decoration:underline;
+  text-underline-offset:3px;
+  font-size:13px
+}
+.help {
+  margin-top:8px;
+  border-top:1px solid var(--line);
+  padding-top:16px;
+  color:var(--muted);
+  font-size:13px
+}
+.help p+p {
+  margin-top:8px
+}
+@keyframes spin {
+  to {
+    transform:rotate(360deg)
+  }
+}
+@media(prefers-reduced-motion:reduce) {
+  .install-steps .active svg {
+    animation:none
+  }
+}
+@media(max-width:760px) {
+  .page {
+    width:calc(100% - 48px);
+    margin-top:20px
+  }
+  .mode-option {
+    gap:10px;
+    padding:12px
+  }
+  .mode-icon {
+    width:22px;
+    height:22px
+  }
+  .steps li+li:before {
+    width:30px;
+    margin:0 10px
+  }
+  .inset {
+    margin-left:0
+  }
+  .intro {
+    margin-top:20px
+  }
+}
+@media(max-width:540px) {
+  .page {
+    width:calc(100% - 36px)
+  }
+  .mode-options {
+    grid-template-columns:1fr
+  }
+  .steps {
+    font-size:12px
+  }
+  .steps li {
+    gap:5px
+  }
+  .steps li+li:before {
+    width:14px;
+    margin:0 6px
+  }
+  .step-dot {
+    width:24px;
+    height:24px
+  }
+  .field {
+    grid-template-columns:1fr;
+    gap:6px
+  }
+  .connection-row {
+    flex-wrap:wrap
+  }
+  .connection-row input {
+    flex-basis:100%
+  }
+  .intro h1 {
+    font-size:24px
+  }
+  h2 {
+    gap:14px
+  }
+}
+@media(prefers-color-scheme:dark) {
+  :root {
+    --canvas:#181817;
+    --soft:#282827;
+    --text:#efefec;
+    --muted:#b2b2ad;
+    --line:#41413e;
+    --solid:#efefec;
+    --on-solid:#151514;
+    --success:#77b88e;
+    --danger:#ed786f;
+    --focus:rgba(255,255,255,.12)
+  }
+  .brand img {
+    filter:invert(1)
+  }
+  .steps .complete .step-dot {
+    color:#151514
+  }
+}
+.field label {
+  white-space:nowrap
+}
+.local-ready #local-panel>.muted {
+  display:none
+}
+.local-ready .installation {
+  margin-top:6px
+}

+ 65 - 4
desktop/boot.html

@@ -1,5 +1,66 @@
 <!doctype html>
-<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'self'; script-src 'self'; img-src 'self'">
-<title>夭夭</title><link rel="stylesheet" href="boot.css"></head>
-<body><main><img src="icon.png" alt="" width="72" height="72"><h1>夭夭</h1><p id="status" role="status" aria-live="polite">正在启动本地服务…</p><div id="actions" hidden><button id="force-sync" hidden>使用当前 App 覆盖同版本 Web</button><button id="retry">重试</button><button id="logs">查看日志</button></div></main><script src="boot.js"></script></body></html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'self'; script-src 'self'; img-src 'self'">
+  <title>开始使用夭夭</title><link rel="stylesheet" href="boot.css">
+</head>
+<body>
+<main class="page">
+  <header class="brand"><div><img src="icon.png" alt="" width="40" height="40"><strong>夭夭</strong></div><span>服务器与账号</span></header>
+  <div class="intro"><h1>开始使用夭夭</h1><p>选择服务器,完成准备后即可开始使用。</p></div>
+  <ol class="steps" aria-label="设置进度">
+    <li id="step-choice" aria-current="step"><span class="step-dot"><b>1</b><svg><use href="boot-icons.svg#check"/></svg></span>选择服务器</li>
+    <li id="step-prepare"><span class="step-dot"><b>2</b><svg><use href="boot-icons.svg#check"/></svg></span>准备服务</li>
+    <li id="step-account"><span class="step-dot"><b>3</b><svg><use href="boot-icons.svg#check"/></svg></span><span id="account-step-title">登录账号</span></li>
+  </ol>
+  <section class="section choice-section" aria-labelledby="choice-title">
+    <h2 id="choice-title"><span>01</span>选择服务器</h2>
+    <fieldset id="mode-options" class="mode-options"><legend class="sr-only">服务器运行方式</legend>
+      <label class="mode-option"><input type="radio" name="mode" value="local"><svg class="mode-icon"><use href="boot-icons.svg#monitor"/></svg><span><strong>本机运行</strong><small>在这台电脑准备并运行服务</small></span></label>
+      <label class="mode-option"><input type="radio" name="mode" value="remote"><svg class="mode-icon"><use href="boot-icons.svg#link"/></svg><span><strong>连接远程服务器</strong><small>使用已有服务器,本机无需安装</small></span></label>
+    </fieldset>
+  </section>
+  <section id="prepare-section" class="section pending" aria-labelledby="prepare-title">
+    <h2 id="prepare-title"><span>02</span><span id="prepare-heading">准备服务</span></h2>
+    <p id="choose-hint" class="muted inset">请先选择本机运行或连接远程服务器。</p>
+    <div id="local-panel" hidden>
+      <p class="muted inset">检测已有环境,按顺序准备缺少的组件。</p>
+      <div class="installation">
+        <ol class="install-steps">
+          <li data-stage="checking"><svg><use href="boot-icons.svg#circle"/></svg><span>检查运行环境</span><small>等待中</small></li>
+          <li data-stage="installing"><svg><use href="boot-icons.svg#circle"/></svg><span>准备服务组件</span><small>等待中</small></li>
+          <li data-stage="starting"><svg><use href="boot-icons.svg#circle"/></svg><span>启动并检查服务</span><small>等待中</small></li>
+        </ol>
+        <progress id="install-progress" aria-label="正在准备本机服务" hidden></progress>
+        <details id="install-details"><summary>查看安装详情<svg><use href="boot-icons.svg#chevron"/></svg></summary><pre id="install-log">准备开始</pre><button id="logs" class="text-button" type="button">查看日志</button></details>
+      </div>
+    </div>
+    <form id="connection-form" class="inset" hidden>
+      <label for="server">服务器地址</label>
+      <div class="connection-row"><input id="server" name="server" type="text" inputmode="url" autocomplete="url" spellcheck="false" placeholder="192.168.1.10:15300" required><button id="detect" class="secondary" type="submit">检测连接</button></div>
+    </form>
+    <p id="status" class="status inset" role="status" aria-live="polite"></p>
+    <div id="actions" class="actions inset" hidden><button id="retry" class="secondary" type="button">重试</button><button id="force-sync" class="secondary" type="button" hidden>使用当前 App 覆盖同版本 Web</button></div>
+    <button id="prepare-local" class="primary" type="button" hidden><span>检测并准备本机服务</span><svg><use href="boot-icons.svg#arrow"/></svg></button>
+  </section>
+  <section id="account-section" class="section pending" aria-labelledby="account-title">
+    <h2 id="account-title"><span>03</span><span id="account-heading">登录账号</span></h2>
+    <p id="account-hint" class="muted inset">服务准备完成后,在此登录账号。</p>
+    <form id="login-form" hidden>
+      <div id="credentials" class="inset">
+        <div class="field"><label for="username">账号</label><input id="username" name="username" autocomplete="username" spellcheck="false" placeholder="输入用户名" required maxlength="320"></div>
+        <div class="field"><label for="password">密码</label><div class="password-input"><input id="password" name="password" type="password" autocomplete="current-password" placeholder="输入密码" required maxlength="4096"><button id="toggle-password" class="eye-button" type="button" aria-label="显示密码" aria-pressed="false"><svg><use href="boot-icons.svg#eye"/></svg></button></div></div>
+        <div id="confirmation-field" class="field" hidden><label for="confirmation">确认密码</label><input id="confirmation" name="confirmation" type="password" autocomplete="new-password" placeholder="再次输入密码" maxlength="4096"></div>
+      </div>
+      <p id="registration-notice" class="muted inset" role="status" hidden></p>
+      <p id="login-error" class="error inset" role="alert" hidden></p>
+      <button id="submit" class="primary" type="submit"><span>登录并进入夭夭</span><svg><use href="boot-icons.svg#arrow"/></svg></button>
+    </form>
+    <button id="waiting" class="primary" type="button" disabled hidden>正在准备服务,请稍候</button>
+  </section>
+  <footer><label class="remember"><input id="remember" type="checkbox">记住本次选择</label><button id="register-toggle" class="text-button" type="button" hidden>没有账号?注册子账号</button><button id="help-button" class="text-button" type="button" aria-expanded="false" aria-controls="help">帮助</button></footer>
+  <div id="help" class="help" hidden><p><strong>本机运行:</strong>复用已有服务,或准备本机服务后创建管理员。机器人运行还需要本机的 Hermes 环境。</p><p><strong>远程连接:</strong>填写夭夭服务器地址,检测成功后使用该服务器的账号登录。管理员登录后会尝试将本机注册为可控制的电脑。</p><p>更换服务器不会迁移原服务器上的数据。遇到安装问题,可展开安装详情查看日志。</p></div>
+</main>
+<script src="boot.js"></script>
+</body></html>

+ 172 - 23
desktop/boot.js

@@ -1,27 +1,176 @@
-function display(state) {
-  document.getElementById('status').textContent = state.message
-  document.getElementById('actions').hidden = !['error','stopped','disconnected'].includes(state.phase)
-  document.getElementById('retry').textContent = state.phase === 'disconnected' ? '重新连接' : state.phase === 'stopped' ? '启动后台服务' : '重试'
-  document.getElementById('status').setAttribute('role', state.phase === 'error' ? 'alert' : 'status')
-  document.getElementById('force-sync').hidden = state.phase !== 'error' || state.canForceSync !== true
-  document.querySelector('main').setAttribute('aria-busy', String(['starting','restarting','stopping'].includes(state.phase)))
+const api = window.yaoyaoDesktop
+const $ = id => document.getElementById(id)
+let registering = false
+let state, initialized = false, pending = false, serverDirty = false, generation = 0, actionError = ''
+
+function display(next) {
+  state = next
+  if (!initialized) {
+    $('server').value = state.serverURL || ''
+    $('remember').checked = state.remember
+    initialized = true
+  }
+  const busy = pending || state.busy
+  const local = state.mode === 'local'
+  const ready = ['ready', 'authenticating', 'entering'].includes(state.phase) && !serverDirty
+  const setup = ready && state.setupRequired
+  const confirm = setup || registering
+  const accountTitle = setup ? '创建管理员' : registering ? '注册子账号' : '登录账号'
+  $('register-toggle').hidden = !ready || setup || state.authenticated
+  $('register-toggle').disabled = busy
+  $('register-toggle').textContent = registering ? '已有账号?返回登录' : '没有账号?注册子账号'
+  $('registration-notice').textContent = state.registrationNotice || ''
+  $('registration-notice').hidden = !ready || !state.registrationNotice
+  $('mode-options').disabled = busy
+  for (const input of document.querySelectorAll('[name=mode]')) input.checked = input.value === state.mode
+  $('remember').disabled = busy
+  $('prepare-section').classList.toggle('pending', !state.mode)
+  $('prepare-section').classList.toggle('local-ready', local && ready)
+  $('prepare-heading').textContent = local ? '准备本机服务' : state.mode ? '连接服务器' : '准备服务'
+  $('choose-hint').hidden = !!state.mode
+  $('local-panel').hidden = !local
+  $('connection-form').hidden = state.mode !== 'remote'
+  $('server').disabled = busy
+  $('detect').disabled = busy || !$('server').value.trim()
+  $('detect').textContent = busy && !ready ? '正在检测…' : ready ? '重新检测' : '检测连接'
+  $('prepare-local').hidden = !local || state.phase !== 'idle'
+  $('prepare-local').disabled = busy
+  $('actions').hidden = !local || state.phase !== 'error'
+  $('retry').disabled = busy
+  $('force-sync').hidden = !state.canForceSync
+  $('force-sync').disabled = busy
+  const preparationError = !ready && !serverDirty && (actionError || state.error)
+  $('status').textContent = preparationError || (serverDirty ? '服务器地址已更改,请重新检测。' : state.message)
+  $('status').setAttribute('role', preparationError ? 'alert' : 'status')
+  $('status').classList.toggle('success', ready && !preparationError)
+  $('prepare-section').setAttribute('aria-busy', String(busy && !ready))
+  $('account-heading').textContent = accountTitle
+  $('account-step-title').textContent = accountTitle
+  $('account-section').classList.toggle('pending', !ready)
+  $('account-section').setAttribute('aria-busy', String(busy && ready))
+  $('account-hint').textContent = !ready ? '服务准备完成后,在此创建账号或登录。'
+    : state.authenticated ? `已登录${state.username ? `:${state.username}` : ''},可以继续进入夭夭。`
+    : setup ? '首次使用,请设置管理员账号和密码。密码至少 8 个字符。' : registering ? '子账号仅可使用 Bot 模式,注册后需管理员分配机器人并开通。' : '登录所选服务器的夭夭账号。'
+  $('login-form').hidden = !ready
+  $('credentials').hidden = state.authenticated
+  $('confirmation-field').hidden = !confirm
+  $('username').disabled = busy || state.authenticated || !ready
+  $('password').disabled = busy || state.authenticated || !ready
+  $('confirmation').disabled = busy || !confirm || state.authenticated
+  $('confirmation').required = confirm && !state.authenticated
+  $('password').minLength = confirm ? 8 : 1
+  $('password').autocomplete = confirm ? 'new-password' : 'current-password'
+  $('toggle-password').disabled = busy
+  $('submit').disabled = busy
+  $('submit').querySelector('span').textContent = state.phase === 'authenticating' ? (confirm ? '正在提交…' : '正在登录…')
+    : state.phase === 'entering' ? '正在进入…' : state.authenticated ? '进入夭夭' : setup ? '创建并进入夭夭' : registering ? '注册子账号' : '登录并进入夭夭'
+  $('login-error').textContent = ready ? actionError || state.error : ''
+  $('login-error').hidden = !$('login-error').textContent
+  $('waiting').hidden = !busy || ready
+  $('waiting').textContent = local ? '正在准备服务,请稍候' : '正在检测连接,请稍候'
+  const activeStep = ready ? 2 : state.mode ? 1 : 0
+  for (const [index, id] of ['step-choice', 'step-prepare', 'step-account'].entries()) {
+    $(id).classList.toggle('complete', index < activeStep)
+    if (index === activeStep) $(id).setAttribute('aria-current', 'step')
+    else $(id).removeAttribute('aria-current')
+  }
+  const stages = ['checking', 'installing', 'starting']
+  const current = stages.indexOf(state.stage)
+  for (const [index, row] of [...document.querySelectorAll('[data-stage]')].entries()) {
+    const complete = ready || (state.phase !== 'idle' && index < current)
+    const active = !complete && state.phase === 'preparing' && index === current
+    row.classList.toggle('complete', complete)
+    row.classList.toggle('active', active)
+    row.querySelector('use').setAttribute('href', `boot-icons.svg#${complete ? 'check' : active ? 'loader' : 'circle'}`)
+    row.querySelector('small').textContent = complete ? '已完成' : active ? '进行中' : state.phase === 'error' && index === current ? '未完成' : '等待中'
+  }
+  $('install-progress').hidden = !local || state.phase !== 'preparing'
+  document.querySelector('.install-steps').hidden = local && ready
+  const history = state.history?.join('\n') || '准备开始'
+  if ($('install-log').textContent !== history) $('install-log').textContent = history
 }
-document.getElementById('force-sync').onclick = async () => {
-  const controls = [...document.querySelectorAll('#actions button')]
-  for (const button of controls) button.disabled = true
-  try { await window.yaoyaoDesktop.forceSync(); await render() }
-  catch { display({ phase: 'error', message: '覆盖未完成,请重试或查看服务日志。' }) }
-  finally { for (const button of controls) button.disabled = false }
+
+async function action(run, { resetServer = false, focusAccount = false } = {}) {
+  if (pending) return
+  pending = true; actionError = ''; generation++
+  if (state) display(state)
+  try {
+    const next = await run()
+    if (resetServer) {
+      if (next.phase === 'ready') $('server').value = next.serverURL || ''
+      serverDirty = false
+    }
+    display(next)
+  } catch (error) {
+    actionError = error.message || '操作未完成,请重试。'
+  } finally {
+    pending = false
+    if (state) display(state)
+    if (focusAccount && state?.phase === 'ready' && !state.authenticated) $('username').focus()
+  }
 }
-async function render() {
-  try { display(await window.yaoyaoDesktop.status()) }
-  catch { display({ phase: 'error', message: '无法读取启动状态,请重试或查看服务日志。' }) }
+for (const input of document.querySelectorAll('[name=mode]')) input.addEventListener('change', () => {
+  $('login-form').reset(); $('password').type = 'password'
+  $('toggle-password').setAttribute('aria-pressed', 'false'); $('toggle-password').setAttribute('aria-label', '显示密码')
+  $('password').removeAttribute('aria-invalid'); $('confirmation').removeAttribute('aria-invalid')
+  serverDirty = false; registering = false
+  void action(() => api.selectServer(input.value))
+})
+$('server').addEventListener('input', () => {
+  serverDirty = true; registering = false; actionError = ''
+  // Credentials belong to the checked server, never carry them to a new address.
+  $('login-form').reset(); $('password').type = 'password'
+  $('toggle-password').setAttribute('aria-pressed', 'false'); $('toggle-password').setAttribute('aria-label', '显示密码')
+  if (state) display(state)
+})
+$('connection-form').addEventListener('submit', event => {
+  event.preventDefault()
+  void action(() => api.prepareServer({ serverURL: $('server').value, remember: $('remember').checked }), { resetServer: true, focusAccount: true })
+})
+$('prepare-local').onclick = () => action(() => api.prepareServer({ remember: $('remember').checked }), { focusAccount: true })
+$('retry').onclick = () => action(() => api.prepareServer({ remember: $('remember').checked }), { focusAccount: true })
+$('force-sync').onclick = () => action(() => api.forceSync(), { focusAccount: true })
+$('logs').onclick = async () => { try { await api.logs() } catch (error) { actionError = error.message; display(state) } }
+$('toggle-password').onclick = () => {
+  const show = $('password').type === 'password'
+  $('password').type = show ? 'text' : 'password'
+  $('toggle-password').setAttribute('aria-label', show ? '隐藏密码' : '显示密码')
+  $('toggle-password').setAttribute('aria-pressed', String(show))
+}
+$('confirmation').addEventListener('blur', () => {
+  const mismatch = $('confirmation').value && $('confirmation').value !== $('password').value
+  $('confirmation').setAttribute('aria-invalid', String(!!mismatch))
+  actionError = mismatch ? '两次输入的密码不一致' : ''
+  display(state)
+})
+$('login-form').addEventListener('submit', event => {
+  event.preventDefault()
+  if (serverDirty || pending) return
+  if ((state.setupRequired || registering) && !state.authenticated && $('confirmation').value !== $('password').value) {
+    actionError = '两次输入的密码不一致'; $('confirmation').setAttribute('aria-invalid', 'true'); display(state); $('confirmation').focus(); return
+  }
+  void action(async () => {
+    const next = await api.login({ username: $('username').value, password: $('password').value,
+      confirmation: $('confirmation').value, register: registering, remember: $('remember').checked })
+    $('password').value = ''; $('confirmation').value = ''
+    if (registering && !next.error) registering = false
+    return next
+  })
+})
+$('register-toggle').onclick = () => {
+  if (!state.registrationAvailable) { actionError = '当前服务器尚不支持子账号注册,请联系管理员升级。'; display(state); return }
+  registering = !registering; actionError = ''; state.error = ''; state.registrationNotice = ''
+  $('password').value = ''; $('confirmation').value = ''; display(state); $('username').focus()
 }
-document.getElementById('retry').onclick = async () => {
-  document.getElementById('retry').disabled = true
-  try { await window.yaoyaoDesktop.retry(); await render() }
-  catch { display({ phase: 'error', message: '启动未完成,请重试或查看服务日志。' }) }
-  finally { document.getElementById('retry').disabled = false }
+$('help-button').onclick = () => {
+  $('help').hidden = !$('help').hidden
+  $('help-button').setAttribute('aria-expanded', String(!$('help').hidden))
+}
+async function render() {
+  const request = generation
+  try { const next = await window.yaoyaoDesktop.status(); if (request === generation) display(next) }
+  catch { if (!state) { $('status').textContent = '无法读取启动状态,请重新打开应用。'; $('status').setAttribute('role', 'alert') } }
 }
-document.getElementById('logs').onclick = () => window.yaoyaoDesktop.logs()
-void render();setInterval(() => { void render() }, 500)
+void render()
+const poll = setInterval(() => { void render() }, 500)
+window.addEventListener('pagehide', () => clearInterval(poll), { once: true })

+ 2 - 1
desktop/core-lifecycle.test.mjs

@@ -1,3 +1,4 @@
+import { enterLocal } from './test-support/onboarding.mjs'
 import {test} from 'node:test'
 import assert from 'node:assert/strict'
 import {mkdtemp,readFile,rm,mkdir} from 'node:fs/promises'
@@ -18,7 +19,7 @@ test('packaged core service starts, preserves window-close work, recovers, and s
   try{
     await until(()=>localJSON(`http://127.0.0.1:${upstreamPort}/api/status`),Boolean)
     app=await electron.launch({...(process.env.DESKTOP_TEST_EXECUTABLE?{executablePath:process.env.DESKTOP_TEST_EXECUTABLE}:{}),args:process.env.DESKTOP_TEST_EXECUTABLE?[]:[root],cwd:root,env:{...process.env,HERMES_YAOYAO_DESKTOP_TEST_HOME:home,HERMES_YAOYAO_DESKTOP_PORT:String(port),HERMES_YAOYAO_UPSTREAM:`http://127.0.0.1:${upstreamPort}`},timeout:30000})
-    const page=await app.firstWindow();await page.waitForURL(`http://127.0.0.1:${port}/**`)
+    const page=await app.firstWindow();await enterLocal(page);await page.waitForURL(`http://127.0.0.1:${port}/**`)
     const initial=JSON.parse(await readFile(join(home,'service-instance.json'),'utf8'));pid=initial.pid
     const identity=await localJSON(`http://127.0.0.1:${port}/desktop/service`,{'x-yaoyao-desktop-token':initial.token})
     assert.equal(identity.desktopOwned,true);assert.equal(identity.pid,pid);assert.equal(identity.version,release.webVersion)

+ 3 - 1
desktop/lifecycle.test.mjs

@@ -1,3 +1,4 @@
+import { enterLocal } from './test-support/onboarding.mjs'
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { mkdtemp, readFile, writeFile, stat, rm, mkdir, realpath } from 'node:fs/promises'
@@ -40,6 +41,7 @@ test('real desktop launches its bundled service, survives window close and recov
       HERMES_YAOYAO_UPSTREAM: `http://127.0.0.1:${upstreamPort}` }, timeout: 30000 })
     desktop.process().stderr.on('data', b => { if (process.env.DESKTOP_TEST_LOGS) process.stderr.write(b) })
     const page = await desktop.firstWindow()
+    await enterLocal(page)
     await page.waitForURL(`http://127.0.0.1:${port}/**`, { timeout: 30000 })
     const owner = await until(async () => JSON.parse(await readFile(join(home, 'service-instance.json'), 'utf8')), r => r.url)
     servicePID = owner.pid
@@ -54,7 +56,7 @@ test('real desktop launches its bundled service, survives window close and recov
     const registration=await page.evaluate(async()=>{
       const bootstrap=await (await fetch('/api/app/bootstrap')).json()
       const headers={'Content-Type':'application/json','X-CSRF-Token':bootstrap.csrfToken}
-      const setup=await fetch('/api/app/setup',{method:'POST',headers,body:JSON.stringify({username:'desktop-fixture',password:'desktop-fixture-password'})})
+      const setup=await fetch('/api/app/login',{method:'POST',headers,body:JSON.stringify({username:'desktop-fixture',password:'desktop-fixture-password'})})
       if(!setup.ok)throw new Error('fixture setup failed')
       headers['X-CSRF-Token']=(await (await fetch('/api/app/bootstrap')).json()).csrfToken
       const response=await fetch('/api/app/admin/runners',{method:'POST',headers,body:JSON.stringify({name:'桌面验收节点',allowedProfiles:['default']})})

+ 136 - 136
desktop/main.mjs

@@ -11,7 +11,8 @@ import { synchronizeLocalService, stopLocalService, migrateLocalData } from './s
 import { resolveDataHome } from './data-home.mjs'
 import { DesktopEnvironmentHost, DesktopHostCore } from './environment-host.mjs'
 import { DesktopHostManager } from './host-manager.mjs'
-import { remoteSession, enrollDesktopHost, normalizeServerURL } from './remote-login.mjs'
+import { remoteRegistration, remoteSession, enrollDesktopHost, inspectServer } from './remote-login.mjs'
+import { DesktopOnboarding } from './onboarding.mjs'
 import { DesktopUpdateManager } from './update-manager.mjs'
 import { installComputerViewer } from './computer-viewer.mjs'
 
@@ -23,8 +24,9 @@ app.setName('夭夭')
 if (!app.requestSingleInstanceLock()) { app.quit() }
 else {
   let window, tray, manager, runnerManager, quitting = false, closing = false, timer
-  let updateWindow, updater, environmentHost, hostManager, loginWindow
+  let updateWindow, updater, environmentHost, hostManager, onboarding
   let remoteMode = false, remoteURL = '', serverModeActive = false, switchingMode = false
+  let recoveringService = false
   const serviceURL = () => remoteMode ? remoteURL : manager?.state.url
   const serviceOrigins = () => {
     try { return remoteMode && remoteURL ? [new URL(remoteURL).origin] : manager?.state.url ? [new URL(manager.state.url).origin] : [] }
@@ -46,15 +48,16 @@ else {
   const port = Number(process.env.HERMES_YAOYAO_DESKTOP_PORT || 15300)
   if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('桌面服务端口无效')
 
-  const trustedBoot = event => event.sender === window?.webContents && event.senderFrame?.url === bootURL
+  const trustedBoot = event => !closing && !quitting && event.sender === window?.webContents
+    && event.senderFrame === window.webContents.mainFrame && event.senderFrame.url === bootURL
   ipcMain.handle('desktop:status', event => {
     if (!trustedBoot(event)) throw new Error('不允许此页面访问桌面服务')
-    return { phase: manager?.state.phase || 'starting', message: manager?.state.message || '正在启动…', canForceSync: manager?.state.canForceSync === true }
+    return onboarding.snapshot()
   })
   ipcMain.handle('desktop:retry', async event => {
     if (!trustedBoot(event)) throw new Error('不允许此页面启动桌面服务')
     manager.restarts = []
-    try { await manager.start(); return true } catch { return false }
+    return onboarding.prepare()
   })
   ipcMain.handle('desktop:logs', event => {
     if (!trustedBoot(event)) throw new Error('不允许此页面读取日志')
@@ -63,9 +66,14 @@ else {
   ipcMain.handle('desktop:force-sync', async event => {
     if (!trustedBoot(event) || event.senderFrame !== window.webContents.mainFrame || closing || quitting || !manager?.canForceSynchronization)
       throw new Error('不允许此页面覆盖本机 Web')
-    try { await manager.retrySynchronization({ force: true }); return true }
-    catch (error) { log(error.message); return false }
+    return onboarding.prepare({ force: true })
   })
+  for (const action of ['select', 'prepare', 'submit']) {
+    ipcMain.handle(`desktop:onboarding-${action}`, (event, input) => {
+      if (!trustedBoot(event)) throw new Error('不允许此页面操作安装与登录')
+      return onboarding[action](input)
+    })
+  }
   const trustedUpdate = event => event.sender === updateWindow?.webContents
     && event.senderFrame === updateWindow.webContents.mainFrame && event.senderFrame.url === updateURL
   ipcMain.handle('desktop:updates', async event => {
@@ -152,12 +160,14 @@ else {
     })
     window.on('close', event => { if (!quitting) { event.preventDefault(); window.hide() } })
     window.once('ready-to-show', () => { if (!startHidden) window.show() })
-    if (remoteMode && remoteURL) void window.loadURL(remoteURL)
-    else if (manager?.state.phase === 'ready') void window.loadURL(manager.state.url)
-    else void window.loadFile(join(desktopRoot, 'boot.html'))
+    if (onboarding?.state.active) return window.loadURL(bootURL)
+    if (remoteMode && remoteURL) return window.loadURL(remoteURL)
+    if (manager?.state.phase === 'ready') return window.loadURL(manager.state.url)
+    return window.loadFile(join(desktopRoot, 'boot.html'))
   }
   function stateChanged(state) {
     log(`${state.phase}: ${state.message}`)
+    onboarding?.serviceChanged(state)
     // Quit owns the window from this point on. A detached connection is not a
     // stopped server and must never navigate the closing window to boot.html.
     if (closing || quitting || remoteMode) return
@@ -173,10 +183,22 @@ else {
     if (forceSync) forceSync.enabled = !closing && !quitting && manager?.canForceSynchronization === true
     tray?.setToolTip(`夭夭 · ${state.message}`)
     if (!window || window.isDestroyed()) return
+    if (onboarding?.state.active) {
+      if (recoveringService && state.phase === 'ready') {
+        recoveringService = false
+        if (!onboarding.busy) void onboarding.prepare({ autoEnter: true }).catch(error => log(error.message))
+      }
+      return
+    }
     if (state.phase === 'ready') {
       const current = window.webContents.getURL()
       if (!current.startsWith(`${state.url}/`) && current !== state.url) void window.loadURL(state.url)
-    } else if (window.webContents.getURL() !== bootURL) void window.loadFile(join(desktopRoot, 'boot.html'))
+    } else if (window.webContents.getURL() !== bootURL) {
+      recoveringService = true
+      onboarding.open({ mode: 'local', remember: preferences.value.startupChoice === 'local' })
+      onboarding.serviceChanged(state)
+      void window.loadURL(bootURL)
+    }
   }
   app.on('second-instance', show)
   app.on('activate', show)
@@ -184,7 +206,7 @@ else {
   function requestQuit(stopBackground = false) {
     if (closing || quitting) return
     closing = true; clearInterval(timer)
-    updater?.cancel(); updateWindow?.close(); loginWindow?.close()
+    updater?.cancel(); updateWindow?.close()
     window?.hide()
     // Native Cmd+Q can enter before-quit from Cocoa's termination callback.
     // Both cleanup and the final quit must run after that callback unwinds.
@@ -303,12 +325,12 @@ else {
     ipcMain.handle('desktop:mode-switch',async(event,mode)=>{
       requireModePage(event)
       if(mode!=='client'&&mode!=='server')throw new Error('运行模式无效')
-      return switchMode(mode==='client'?'remote':'local',false)
+      return switchMode(mode==='client'?'remote':'local')
     })
     ipcMain.handle('desktop:remote-login',event=>{
       requireModePage(event)
       if(switchingMode)throw new Error('正在切换运行模式,请稍候')
-      openRemoteLogin()
+      return openRemoteLogin()
     })
     ipcMain.handle('desktop:computer-authorize',async(event,csrfToken)=>{
       requireModePage(event)
@@ -322,7 +344,6 @@ else {
       }catch(error){
         const message=error instanceof Error?error.message:'电脑授权恢复失败'
         hostManager.publish(`电脑授权未恢复:${message}`)
-        await appDialog({type:'warning',message:'账号已登录,但电脑授权未恢复',detail:`${message}\n\n请在“电脑”菜单中选择“重新授权…”。`})
         return {registered:false}
       }
     })
@@ -332,44 +353,82 @@ else {
         :await dialog.showOpenDialog({title:'导入电脑配置',properties:['openFile'],filters:[{name:'电脑配置',extensions:['json']}]})
       if(!selection.canceled&&selection.filePaths[0]&&!closing)await hostAction(()=>hostManager.importFile(selection.filePaths[0]))
     }
-    function openRemoteLogin(){
-      if(closing||quitting)return
-      if(loginWindow&&!loginWindow.isDestroyed()){loginWindow.show();loginWindow.focus();return}
-      loginWindow=new BrowserWindow({width:420,height:580,minWidth:360,minHeight:440,show:false,title:'登录远程',backgroundColor:'#f7f7f7',
-        webPreferences:{contextIsolation:true,nodeIntegration:false,sandbox:true,webSecurity:true,preload:join(desktopRoot,'remote-login-preload.cjs')}})
-      loginWindow.once('ready-to-show',()=>{if(loginWindow)loginWindow.show()})
-      loginWindow.on('closed',()=>{loginWindow=undefined})
-      const stored=preferences.value.remoteServer
-      void loginWindow.loadFile(join(desktopRoot,'remote-login.html'),stored?{query:{server:stored}}:undefined)
+    if (!preferences.value.remoteServer) {
+      const enrolled = await hostManager.read().catch(() => undefined)
+      if (enrolled?.serverURL) await preferences.setRemoteServer(enrolled.serverURL)
     }
-    async function enterRemoteMode(){
-      const enrolled=await hostManager.read().catch(error=>{log(error.message);return undefined})
-      let server=''
-      const candidate=preferences.value.remoteServer||enrolled?.serverURL
-      if(candidate){try{server=normalizeServerURL(candidate)}catch(error){log(error.message)}}
-      if(!server){openRemoteLogin();return false}
-      serverModeActive=false
-      await environmentHost?.close().catch(error=>log(error.message))
-      await runnerManager?.stop().catch(error=>log(error.message))
-      await manager?.stop().catch(error=>log(error.message))
-      remoteMode=true;remoteURL=server
-      await preferences.setRemoteServer(server).catch(error=>log(error.message))
-      await preferences.setStartupChoice('remote').catch(error=>log(error.message))
-      if(enrolled&&new URL(enrolled.serverURL).origin===new URL(server).origin)await hostManager.start().catch(error=>{hostManager.publish(error.message)})
-      const status=Menu.getApplicationMenu()?.getMenuItemById('desktop-service-status')
-      if(status)status.label=`已登录远程 · ${new URL(server).host}`
-      tray?.setToolTip(`夭夭 · 远程 ${new URL(server).host}`)
-      syncModeMenu()
-      log(`远程模式:${server}`)
-      if(!fixtureHome){
-        try{
-          const probe=await net.fetch(new URL('/api/app/bootstrap',server),{headers:{accept:'application/json'},redirect:'error'})
-          const info=await probe.json().catch(()=>undefined)
-          if(info?.authenticated!==true)openRemoteLogin()
-        }catch{openRemoteLogin()}
-      }
-      return true
+    onboarding = new DesktopOnboarding({
+      remoteServer: () => preferences.value.remoteServer,
+      inspect: server => inspectServer(server, (...args) => net.fetch(...args)),
+      prepareLocal: async ({ force }) => {
+        serverModeActive = true; remoteMode = false; remoteURL = ''
+        await hostManager.stop()
+        manager.restarts = []
+        if (force) await manager.retrySynchronization({ force: true })
+        else await manager.start()
+        if (manager.state.phase !== 'ready') throw new Error(manager.state.message)
+        if (!closing) environmentHost.start()
+        await runnerManager.start().catch(error => runnerManager.publish(error.message))
+        return manager.state.url
+      },
+      register: ({ serverURL, username, password }) => remoteRegistration(serverURL, { username, password }),
+      authenticate: async ({ mode, serverURL, setup, username, password }) => {
+        const auth = await remoteSession(serverURL, { setup, username, password })
+        for (const cookie of auth.cookieDetails) {
+          await electronSession.defaultSession.cookies.set({ url: serverURL, ...cookie,
+            httpOnly: true, secure: cookie.secure || serverURL.startsWith('https://') })
+        }
+        await electronSession.defaultSession.cookies.flushStore()
+        let warning
+        if (mode === 'remote' && auth.user.role === 'admin') {
+          try { await authorizeComputer(serverURL, auth) }
+          catch (error) { warning = `账号已登录,但电脑授权未恢复:${error.message}。可先进入夭夭,稍后在“电脑”菜单重新授权。` }
+        }
+        return { username: auth.user.username, warning }
+      },
+      activate: async ({ mode, serverURL, remember }) => {
+        if (closing || quitting) throw new Error('App 正在退出')
+        if (mode === 'remote') {
+          // Detach only; an independently installed local service keeps running.
+          serverModeActive = false
+          await environmentHost.close()
+          await runnerManager.stop()
+          await manager.stop()
+          remoteMode = true; remoteURL = serverURL
+          await preferences.setRemoteServer(serverURL)
+          const enrolled = await hostManager.read().catch(error => { log(error.message); return undefined })
+          if (enrolled && new URL(enrolled.serverURL).origin === new URL(serverURL).origin)
+            await hostManager.start().catch(error => hostManager.publish(error.message))
+        }
+        await preferences.setStartupChoice(remember ? mode : 'ask')
+        syncModeMenu()
+        const status = Menu.getApplicationMenu()?.getMenuItemById('desktop-service-status')
+        if (status) status.label = mode === 'remote' ? `已登录远程 · ${new URL(serverURL).host}` : '后台服务运行中'
+        tray?.setToolTip(mode === 'remote' ? `夭夭 · 远程 ${new URL(serverURL).host}` : '夭夭 · 本机运行')
+      },
+      navigate: url => {
+        if (closing || quitting) throw new Error('App 正在退出')
+        return window.loadURL(url)
+      },
+    })
+    async function openOnboarding(mode, { autoPrepare = false, remember = preferences.value.startupChoice !== 'ask', forceLogin = false } = {}) {
+      if (closing || quitting) throw new Error('App 正在退出')
+      onboarding.open({ mode, serverURL: preferences.value.remoteServer, remember, forceLogin })
+      if (!window || window.isDestroyed()) await createWindow()
+      else if (window.webContents.getURL() !== bootURL) await window.loadURL(bootURL)
+      window.show(); window.focus()
+      if (autoPrepare && (mode === 'local' || preferences.value.remoteServer))
+        await onboarding.prepare({ autoEnter: true })
+      return onboarding.snapshot()
+    }
+    function openRemoteLogin() {
+      return openOnboarding('remote', { forceLogin: true })
     }
+    ipcMain.handle('desktop:open-login', event => {
+      requireModePage(event)
+      // A session expiry returns to the same main-page flow for the active server.
+      return openOnboarding(remoteMode ? 'remote' : 'local', { autoPrepare: true })
+    })
     function syncModeMenu(){
       const menu=Menu.getApplicationMenu()
       const useRemote=menu?.getMenuItemById('desktop-host-use-remote'),useLocal=menu?.getMenuItemById('desktop-host-use-local'),ask=menu?.getMenuItemById('desktop-host-ask')
@@ -379,72 +438,16 @@ else {
       if(status)status.label=switchingMode?'正在切换运行模式…':remoteMode?'当前:客户端模式':serverModeActive?'当前:服务器模式':'请选择运行模式'
       if(ask)ask.checked=preferences.value.startupChoice==='ask'
     }
-    async function switchMode(mode,notify=true){
-      if(closing||quitting)return {ok:false,error:'App 正在退出'}
-      if(switchingMode)return {ok:false,error:'正在切换运行模式,请稍候'}
-      if(mode==='remote'&&remoteMode||mode==='local'&&serverModeActive)return {ok:true}
-      switchingMode=true;syncModeMenu()
-      try{
-        if(mode==='remote'){
-          if(await enterRemoteMode()){
-            if(window&&!window.isDestroyed())void window.loadURL(remoteURL)
-          }else return {ok:true,pendingLogin:true}
-        }else{
-          loginWindow?.close()
-          serverModeActive=true;remoteMode=false;remoteURL=''
-          await hostManager?.stop().catch(error=>log(error.message))
-          await preferences.setStartupChoice('local').catch(error=>log(error.message))
-          if(window&&!window.isDestroyed())void window.loadFile(join(desktopRoot,'boot.html'))
-          await manager?.start().catch(error=>log(error.message))
-          if(!closing)environmentHost?.start()
-        }
-        return {ok:true}
-      }catch(error){
-        if(notify)await appDialog({type:'error',message:'切换使用方式未完成',detail:error.message})
-        return {ok:false,error:error.message}
-      }finally{switchingMode=false;syncModeMenu()}
-    }
-    ipcMain.handle('desktop-remote-login:submit',async(_event,value)=>{
-      if(closing||quitting)return {ok:false,error:'App 正在退出'}
-      try{
-        const server=normalizeServerURL(value?.serverURL)
-        const auth=await remoteSession(server,{username:value?.username,password:value?.password})
-        let registered=false
-        if(auth.user?.role==='admin'){
-          await authorizeComputer(server,auth)
-          registered=true
-        }
-        try{
-          for(const [name,cookie] of auth.cookies)
-            await electronSession.defaultSession.cookies.set({url:server,name,value:cookie,httpOnly:true,secure:server.startsWith('https://')})
-        }catch(error){log(`远程会话 Cookie 写入失败:${error.message}`)}
-        await preferences.setRemoteServer(server)
-        await enterRemoteMode()
-        if(!window||window.isDestroyed())createWindow()
-        else void window.loadURL(server)
-        loginWindow?.close()
-        if(!registered)await appDialog({type:'info',message:'已登录远程服务器',detail:'当前账号不是管理员:窗口将使用远程夭夭。要把这台 Mac 注册为可远程控制的电脑,请使用管理员账号重新登录。'})
-        return {ok:true,hostRegistered:registered,user:{username:auth.user.username,role:auth.user.role}}
-      }catch(error){return {ok:false,error:error instanceof Error?error.message:'登录失败'}}
-    })
-    ipcMain.handle('desktop-remote-login:use-local',async()=>{
-      loginWindow?.close()
-      if(!serverModeActive){
-        if(!window||window.isDestroyed())createWindow()
-        await switchMode('local')
-      }
-      return {ok:true}
-    })
-    async function chooseStartupMode(){
-      if(fixtureHome)return 'local'
-      const stored=preferences.value.startupChoice
-      if(stored==='local'||stored==='remote')return stored
-      const choice=await dialog.showMessageBox({type:'question',title:'夭夭',message:'这台 Mac 如何使用夭夭?',
-        detail:'「登录远程」用夭夭服务器的地址和账号密码登录另一台电脑上的夭夭:本机不运行 Web 服务,窗口直接使用远程夭夭;管理员账号还会把这台 Mac 注册为可远程控制的电脑。只有「作为服务器运行」会启动这台 Mac 的服务,并使用服务器上的 Hermes。客户端不需要安装 Hermes。',
-        buttons:['连接服务器(客户端)','作为服务器运行'],defaultId:0,cancelId:0,checkboxLabel:'记住选择,之后启动不再询问',checkboxChecked:false,noLink:true})
-      const mode=choice.response===0?'remote':'local'
-      if(choice.checkboxChecked)await preferences.setStartupChoice(mode).catch(error=>log(error.message))
-      return mode
+    async function switchMode(mode) {
+      if (closing || quitting) return { ok: false, error: 'App 正在退出' }
+      if (switchingMode || onboarding.busy) return { ok: false, error: '当前步骤尚未完成,请稍候' }
+      switchingMode = true; syncModeMenu()
+      try {
+        const state = await openOnboarding(mode, { autoPrepare: true, remember: true })
+        return { ok: true, pendingLogin: state.active }
+      } catch (error) {
+        return { ok: false, error: error.message }
+      } finally { switchingMode = false; syncModeMenu() }
     }
     async function importRunner(){
       const selection=await dialog.showOpenDialog(window,{title:'导入执行节点配置',properties:['openFile'],filters:[{name:'Runner 配置',extensions:['json']}]})
@@ -480,11 +483,11 @@ else {
       {label:'运行模式',submenu:[{id:'desktop-mode-status',label:'请选择运行模式',enabled:false},{type:'separator'},
         {id:'desktop-host-use-remote',label:'客户端模式(连接服务器)',enabled:!remoteMode,click:()=>void switchMode('remote')},
         {id:'desktop-host-use-local',label:'服务器模式(本机运行)',enabled:!serverModeActive,click:()=>void switchMode('local')},
-        {label:'更换服务器…',click:openRemoteLogin},{type:'separator'},
+        {label:'更换服务器…',click:()=>{void openRemoteLogin().catch(error=>log(error.message))}},{type:'separator'},
         {id:'desktop-host-ask',label:'启动时询问运行模式',type:'checkbox',checked:preferences.value.startupChoice==='ask',
           click:item=>{void preferences.setStartupChoice(item.checked?'ask':remoteMode?'remote':'local').catch(async error=>{item.checked=preferences.value.startupChoice==='ask';await appDialog({type:'error',message:'无法保存启动偏好',detail:error.message})})}}]},
       {label:'电脑',submenu:[{id:'desktop-host-status',label:'未配置电脑',enabled:false},{type:'separator'},
-        {id:'desktop-host-authorize',label:'重新授权…',click:openRemoteLogin},
+        {id:'desktop-host-authorize',label:'重新授权…',click:()=>{void openRemoteLogin().catch(error=>log(error.message))}},
         {id:'desktop-host-import',label:'导入电脑配置…',click:importDesktopHost},
         {id:'desktop-host-reconnect',label:'重新连接',click:()=>hostAction(()=>hostManager.start())},
         {id:'desktop-host-forget',label:'断开并忘记配置',click:()=>hostAction(()=>hostManager.forget())}]},
@@ -496,22 +499,19 @@ else {
     tray.setToolTip('夭夭')
     tray.setContextMenu(Menu.buildFromTemplate([{ label: '打开夭夭', click: show }, { label: '查看日志', click: () => shell.showItemInFolder(logFile) }, { type: 'separator' }, { label: '退出夭夭(后台继续运行)', click: () => requestQuit() }, { label: '停止后台服务并退出', click: () => requestQuit(true) }]))
     tray.on('click', show)
-    let startupRemote=false,startupLogin=false
-    serverModeActive=(await chooseStartupMode())==='local'
-    if(!serverModeActive){
-      const enrolled=await hostManager.read().catch(()=>undefined)
-      if(preferences.value.remoteServer||enrolled)startupRemote=await enterRemoteMode()
-      startupLogin=!startupRemote
-    }
-    if(!startupLogin)createWindow()
-    powerMonitor.on('resume', () => { if(!closing&&!quitting&&serverModeActive)void manager.check() })
-    timer = setInterval(() => { if(serverModeActive)void manager.check() }, 10_000); timer.unref()
-    if(startupLogin)openRemoteLogin()
-    else if(serverModeActive){
-      syncModeMenu()
-      await manager.start().catch(error => log(error.message))
-      if(!closing)environmentHost.start()
-    }
-    if(!startupLogin&&!startupRemote&&manager.state.phase==='ready')await runnerManager.start().catch(error=>{runnerManager.publish(error.message)})
+    // First launch stays in the main window. Remembered choices prepare in place
+    // and enter immediately only when that server already has a valid session.
+    const startupMode = preferences.value.startupChoice === 'ask'
+      ? (fixtureHome && process.env.HERMES_YAOYAO_DESKTOP_TEST_MODE !== 'ask' ? 'local' : null)
+      : preferences.value.startupChoice
+    onboarding.open({ mode: startupMode, serverURL: preferences.value.remoteServer,
+      remember: preferences.value.startupChoice !== 'ask' })
+    // Finish the initial navigation before a remembered session enters its server.
+    await createWindow()
+    powerMonitor.on('resume', () => { if (!closing && !quitting && serverModeActive) void manager.check() })
+    timer = setInterval(() => { if (serverModeActive) void manager.check() }, 10_000); timer.unref()
+    syncModeMenu()
+    if (startupMode && (startupMode === 'local' || preferences.value.remoteServer))
+      await onboarding.prepare({ autoEnter: true })
   }).catch(error => { log(error.stack || error.message); quitting = true; app.quit() })
 }

+ 16 - 12
desktop/mode-switch.test.mjs

@@ -15,9 +15,10 @@ test('signed-in desktop pages can switch both ways; other windows cannot control
   const identityReady=new Promise(resolve=>{releaseIdentity=resolve})
   const local=createServer(async(req,res)=>{
     if(req.url==='/desktop/service'){await identityReady;res.setHeader('Content-Type','application/json');res.end(JSON.stringify(identity))}
+    else if(req.url==='/api/app/bootstrap'){res.setHeader('Content-Type','application/json');res.end(JSON.stringify({authenticated:true,csrfToken:'fixture'}))}
     else {res.setHeader('Content-Type','text/html; charset=utf-8');res.end('<title>已登录的本机页面</title>')}
   })
-  const remote=createServer((_req,res)=>{res.setHeader('Content-Type','text/html; charset=utf-8');res.end('<title>已登录的服务器页面</title>')})
+  const remote=createServer((_req,res)=>{if(_req.url==='/api/app/bootstrap'){res.setHeader('Content-Type','application/json');res.end(JSON.stringify({authenticated:true,csrfToken:'fixture'}));return}res.setHeader('Content-Type','text/html; charset=utf-8');res.end('<title>已登录的服务器页面</title>')})
   await new Promise(done=>local.listen(0,'127.0.0.1',done))
   await new Promise(done=>remote.listen(0,'127.0.0.1',done))
   const origin=`http://127.0.0.1:${local.address().port}`,remoteURL=`http://127.0.0.1:${remote.address().port}`
@@ -53,19 +54,22 @@ test('signed-in desktop pages can switch both ways; other windows cannot control
     assert.equal(JSON.parse(await readFile(join(home,'desktop-preferences.json'),'utf8')).startupChoice,'local')
     assert.equal(local.listening,true,'switching must leave an independent service running')
     assert.equal(remote.listening,true)
-    // The server picker remains available after either login/mode selection.
-    const opened=app.waitForEvent('window');await page.evaluate(()=>window.yaoyaoDesktop.openRemoteLogin())
-    const login=await opened;await login.waitForLoadState()
-    assert.equal(app.windows().length,2)
-    await page.evaluate(()=>window.yaoyaoDesktop.openRemoteLogin())
-    assert.equal(app.windows().length,2)
-    await login.evaluate(()=>{void window.yaoyaoRemoteLogin.useLocal()})
-    await expect.poll(()=>app.windows().length).toBe(1)
+    // Changing servers reuses the main page, including when opened repeatedly.
+    await page.evaluate(()=>{void window.yaoyaoDesktop.openRemoteLogin()})
+    await page.waitForURL('**/boot.html')
+    assert.equal(app.windows().length,1)
+    await page.getByRole('radio',{name:/本机运行/}).check()
+    await page.locator('#prepare-local').click()
+    await page.locator('#submit').click()
+    await page.waitForURL(origin+'/**')
     await page.evaluate(()=>{void window.yaoyaoDesktop.switchMode('client')})
     await page.waitForURL(remoteURL+'/**')
-    const pickerOpened=app.waitForEvent('window');await page.evaluate(()=>window.yaoyaoDesktop.openRemoteLogin())
-    const picker=await pickerOpened;await picker.waitForLoadState()
-    await picker.evaluate(()=>{void window.yaoyaoRemoteLogin.useLocal()})
+    await page.evaluate(()=>{void window.yaoyaoDesktop.openRemoteLogin()})
+    await page.waitForURL('**/boot.html')
+    assert.equal(app.windows().length,1)
+    await page.getByRole('radio',{name:/本机运行/}).check()
+    await page.locator('#prepare-local').click()
+    await page.locator('#submit').click()
     await page.waitForURL(origin+'/**')
     await expect.poll(()=>page.evaluate(()=>window.yaoyaoDesktop.modeState())).toEqual({mode:'server',serverURL:origin,switching:false})
   }finally{

+ 131 - 0
desktop/onboarding-flow.test.mjs

@@ -0,0 +1,131 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer } from 'node:http'
+import { mkdtemp, realpath, rm, readFile, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { _electron as electron, expect } from '@playwright/test'
+
+const root = resolve(import.meta.dirname, '..')
+test('first launch, failed connection and remote login all stay in the only main window', { timeout: 60000 }, async () => {
+  const home = await realpath(await mkdtemp(join(tmpdir(), 'yaoyao-onboarding-')))
+  let loginCount = 0
+  let registrationCount = 0
+  const server = createServer((req, res) => {
+    const json = (value, status = 200) => { res.statusCode = status; res.setHeader('content-type', 'application/json'); res.end(JSON.stringify(value)) }
+    if (req.url === '/api/app/bootstrap') {
+      res.setHeader('set-cookie', 'csrf=fixture; Path=/; HttpOnly')
+      return json({ authenticated: String(req.headers.cookie).includes('session=fixture'), setupRequired: false, registrationAvailable: true, csrfToken: 'fixture', serverKind: 'yaoyao-web' })
+    }
+    if (req.url === '/api/app/register') {
+      let raw = ''; req.on('data', chunk => { raw += chunk }); req.on('end', () => {
+        registrationCount++
+        assert.deepEqual(JSON.parse(raw), { username: 'new-child', password: 'child-password' })
+        assert.equal(req.headers['x-csrf-token'], 'fixture')
+        assert.ok(String(req.headers.cookie).includes('csrf=fixture'))
+        assert.ok(!String(req.headers.cookie).includes('session=fixture'))
+        json({ registrationStatus: 'pending', message: '注册成功,请等待管理员开通' }, 201)
+      }); return
+    }
+    if (req.url === '/api/app/login') {
+      let raw = ''; req.on('data', chunk => { raw += chunk }); req.on('end', () => {
+        loginCount++
+        const body = JSON.parse(raw)
+        if (body.username !== 'user' || body.password !== 'correct-password') return json({ error: 'wrong' }, 401)
+        if (req.headers['x-csrf-token'] !== 'fixture' || !String(req.headers.cookie).includes('csrf=fixture')) return json({ error: 'csrf' }, 403)
+        res.setHeader('set-cookie', 'session=fixture; Path=/; HttpOnly; Max-Age=3600; SameSite=Strict')
+        json({ user: { id: 'fixture-user', username: 'user', role: 'user' }, csrfToken: 'fixture' })
+      }); return
+    }
+    res.setHeader('content-type', 'text/html; charset=utf-8'); res.end('<title>已登录远程夭夭</title><h1>远程工作区</h1>')
+  })
+  await new Promise(done => server.listen(0, '127.0.0.1', done))
+  const url = `http://127.0.0.1:${server.address().port}`
+  let app
+  try {
+    app = await electron.launch({ args: [root], cwd: root, env: { ...process.env,
+      HERMES_YAOYAO_DESKTOP_TEST_HOME: home, HERMES_YAOYAO_DESKTOP_TEST_MODE: 'ask', HERMES_YAOYAO_DESKTOP_TEST_SYNC: '0' } })
+    const page = await app.firstWindow()
+    const errors = []; page.on('pageerror', error => errors.push(error.message))
+    await expect(page.getByRole('heading', { name: '开始使用夭夭' })).toBeVisible()
+    assert.equal(app.windows().length, 1)
+    assert.equal((await page.evaluate(() => window.yaoyaoDesktop.status())).mode, null)
+    await page.getByRole('radio', { name: /连接远程服务器/ }).check()
+    await page.locator('#server').fill('http://127.0.0.1:1')
+    await page.locator('#detect').click()
+    await expect(page.locator('#status[role=alert]')).toBeVisible()
+    await expect(page.locator('#login-form')).toBeHidden()
+    await page.locator('#server').fill(url)
+    await page.locator('#detect').click()
+    await expect(page.locator('#status')).toHaveText('连接成功,服务器已就绪')
+    await expect(page.locator('#login-form')).toBeVisible()
+    assert.match(page.url(), /boot.html$/)
+    await page.locator('#register-toggle').click()
+    await page.locator('#username').fill('new-child')
+    await page.locator('#password').fill('child-password')
+    await page.locator('#confirmation').fill('child-password')
+    await page.locator('#submit').click()
+    await expect(page.locator('#registration-notice')).toContainText('注册成功,请等待管理员开通')
+    await expect(page.locator('#confirmation-field')).toBeHidden()
+    assert.equal(registrationCount, 1)
+    assert.equal(loginCount, 0, 'registration never signs in or authorizes this computer')
+    assert.match(page.url(), /boot.html$/)
+    await page.locator('#username').fill('user')
+    await page.locator('#password').fill('wrong-password')
+    await page.locator('#submit').click()
+    await expect(page.locator('#login-error')).toContainText('用户名或密码不正确')
+    assert.equal(await page.locator('#password').inputValue(), '')
+    // Editing the address invalidates the checked target and hides credentials.
+    await page.locator('#server').fill('http://another-server.test')
+    await expect(page.locator('#login-form')).toBeHidden()
+    await page.locator('#server').fill(url); await page.locator('#detect').click()
+    assert.equal(await page.locator('#username').inputValue(), '')
+    await page.locator('#username').fill('user')
+    await page.locator('#password').fill('correct-password')
+    await page.locator('#toggle-password').click()
+    assert.equal(await page.locator('#password').getAttribute('type'), 'text')
+    await page.locator('#toggle-password').click()
+    await page.locator('#remember').check()
+    await mkdir(join(root, 'docs/design/desktop-onboarding'), { recursive: true })
+    await page.emulateMedia({ colorScheme: 'light' })
+    assert.equal(await page.evaluate(() => document.querySelector('footer').getBoundingClientRect().bottom <= innerHeight), true, 'default window shows its footer without scrolling')
+    await page.screenshot({ path: join(root, 'docs/design/desktop-onboarding/remote-login.png') })
+    await page.emulateMedia({ colorScheme: 'dark' })
+    await page.screenshot({ path: join(root, 'docs/design/desktop-onboarding/remote-dark.png') })
+    await page.setViewportSize({ width: 720, height: 560 })
+    assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), true)
+    await page.screenshot({ path: join(root, 'docs/design/desktop-onboarding/remote-narrow.png'), fullPage: true })
+    await page.setViewportSize({ width: 1280, height: 832 })
+    await page.emulateMedia({ colorScheme: 'light' })
+    await page.locator('#submit').click()
+    await page.waitForURL(url + '/**')
+    await expect(page.getByRole('heading', { name: '远程工作区' })).toBeVisible()
+    assert.equal(app.windows().length, 1); assert.equal(loginCount, 2)
+    const preferences = JSON.parse(await readFile(join(home, 'desktop-preferences.json'), 'utf8'))
+    assert.equal(preferences.startupChoice, 'remote'); assert.equal(preferences.remoteServer, url)
+    assert.deepEqual(errors, [])
+    // The HTTP renderer cannot invoke privileged native setup/authentication.
+    assert.deepEqual(await page.evaluate(() => Promise.all([
+      window.yaoyaoDesktop.status(), window.yaoyaoDesktop.selectServer('local'),
+      window.yaoyaoDesktop.prepareServer({}), window.yaoyaoDesktop.login({ username: 'x', password: 'y' }),
+    ].map(promise => promise.then(() => false, () => true)))), [true, true, true, true])
+    const firstProcess = app.process()
+    const firstExit = firstProcess.exitCode === null ? new Promise(done => firstProcess.once('exit', done)) : Promise.resolve()
+    await app.close(); await firstExit; app = undefined
+    app = await electron.launch({ args: [root], cwd: root, env: { ...process.env,
+      HERMES_YAOYAO_DESKTOP_TEST_HOME: home, HERMES_YAOYAO_DESKTOP_TEST_MODE: 'ask', HERMES_YAOYAO_DESKTOP_TEST_SYNC: '0' } })
+    const reopened = await app.firstWindow()
+    try { await reopened.waitForURL(url + '/**', { timeout: 8000 }) }
+    catch (error) {
+      console.log('Reopened fixture URL:', reopened.url())
+      console.log('Reopened fixture state:', await reopened.evaluate(() => window.yaoyaoDesktop.status().catch(error => ({ error: error.message }))))
+      console.log('Fixture cookie metadata:', await app.evaluate(async ({ session }, url) => (await session.defaultSession.cookies.get({ url })).map(({ name, expirationDate, sameSite, session }) => ({ name, expirationDate, sameSite, session })), url))
+      throw error
+    }
+    assert.equal(loginCount, 2, 'a remembered session keeps the server-provided cookie expiry and is reused')
+  } finally {
+    await app?.close().catch(() => {})
+    await new Promise(done => { server.close(done); server.closeAllConnections() })
+    await rm(home, { recursive: true, force: true })
+  }
+})

+ 116 - 0
desktop/onboarding.mjs

@@ -0,0 +1,116 @@
+import { normalizeServerURL } from './remote-login.mjs'
+
+/** The native onboarding page owns one selected server and one in-flight action.
+ * Credentials and CSRF/session tokens never appear in renderer snapshots. */
+export class DesktopOnboarding {
+  constructor(options) {
+    this.options = options
+    this.open()
+  }
+  get busy() { return ['preparing', 'authenticating', 'entering'].includes(this.state.phase) }
+  snapshot() { return { ...this.state, history: [...this.state.history], busy: this.busy } }
+  open({ mode = null, serverURL = '', remember = false, forceLogin = false } = {}) {
+    if (this.state && this.busy) throw new Error('当前步骤尚未完成,请稍候')
+    this.state = { active: true, mode, serverURL, remember, forceLogin, phase: 'idle', stage: 'checking',
+      setupRequired: false, registrationAvailable: false, registrationNotice: '', authenticated: false, username: '', message: '', error: '',
+      canForceSync: false, history: [] }
+    return this.snapshot()
+  }
+  select(mode) {
+    if (!['local', 'remote'].includes(mode)) throw new Error('请选择运行方式')
+    return this.open({ mode, serverURL: this.options.remoteServer(), remember: this.state.remember })
+  }
+  serviceChanged(service) {
+    if (!this.state.active || this.state.mode !== 'local') return
+    this.state.stage = service.stage || this.state.stage
+    this.state.message = service.message
+    this.state.canForceSync = service.canForceSync === true
+    if (this.state.history.at(-1) !== service.message) {
+      this.state.history.push(service.message)
+      this.state.history = this.state.history.slice(-30)
+    }
+    if (service.phase === 'error') {
+      this.state.error = service.message
+      // Keep the action locked until the outstanding prepare operation settles.
+      if (!this.busy) this.state.phase = 'error'
+    }
+    if (['error', 'restarting', 'stopped', 'disconnected'].includes(service.phase)) {
+      this.state.authenticated = false
+      if (this.state.phase === 'ready') this.state.phase = 'error'
+    }
+  }
+  async prepare({ serverURL = this.state.serverURL, remember = this.state.remember, force = false, autoEnter = false } = {}) {
+    if (this.busy) throw new Error('当前步骤尚未完成,请稍候')
+    const mode = this.state.mode
+    if (!mode) throw new Error('请先选择服务器')
+    Object.assign(this.state, { phase: 'preparing', error: '', authenticated: false,
+      setupRequired: false, registrationAvailable: false, registrationNotice: '', remember: remember === true, stage: 'checking', canForceSync: false,
+      message: mode === 'local' ? '正在检查本机环境…' : '正在检测服务器连接…' })
+    try {
+      const target = mode === 'local' ? await this.options.prepareLocal({ force }) : normalizeServerURL(serverURL)
+      this.state.serverURL = target
+      const info = await this.options.inspect(target)
+      if (mode === 'remote' && info.setupRequired) throw new Error('远程服务器尚未初始化,请先在服务器本机创建管理员,再重新检测。')
+      Object.assign(this.state, { phase: 'ready', stage: 'ready', setupRequired: info.setupRequired === true, registrationAvailable: info.registrationAvailable === true,
+        authenticated: info.authenticated === true && !this.state.forceLogin, username: info.user?.username || '',
+        message: mode === 'local' ? '本机服务已就绪' : '连接成功,服务器已就绪' })
+      if (autoEnter && this.state.authenticated) await this.enter()
+    } catch (error) {
+      this.state.phase = 'error'
+      this.state.error = error.message || '准备未完成,请重试'
+    }
+    return this.snapshot()
+  }
+  async submit({ username, password, confirmation, register = false, remember = this.state.remember } = {}) {
+    if (this.state.phase !== 'ready') throw new Error('请先完成服务器检测')
+    this.state.remember = remember === true
+    this.state.error = ''
+    if (register) return this.register({ username, password, confirmation })
+    if (this.state.authenticated) return this.enter()
+    if (!String(username || '').trim() || !password) throw new Error('请填写用户名和密码')
+    if (this.state.setupRequired && (password.length < 8 || password !== confirmation))
+      throw new Error(password.length < 8 ? '密码至少需要 8 个字符' : '两次输入的密码不一致')
+    this.state.phase = 'authenticating'
+    try {
+      const result = await this.options.authenticate({ mode: this.state.mode, serverURL: this.state.serverURL,
+        setup: this.state.mode === 'local' && this.state.setupRequired, username, password })
+      this.state.authenticated = true
+      this.state.username = result.username
+      this.state.phase = 'ready'
+      if (result.warning) {
+        this.state.error = result.warning
+        this.state.message = '账号已登录,可以继续进入夭夭'
+      } else await this.enter()
+    } catch (error) {
+      this.state.phase = 'ready'
+      this.state.error = error.message || '登录未完成,请重试'
+    }
+    return this.snapshot()
+  }
+  async register({ username, password, confirmation }) {
+    if (!this.state.registrationAvailable || this.state.setupRequired || this.state.authenticated) throw new Error('当前服务器尚不支持子账号注册,请联系管理员初始化或升级。')
+    if (!String(username || '').trim() || !password || password.length < 8 || password !== confirmation) throw new Error('请填写用户名及至少 8 位密码,并确认两次密码一致。')
+    this.state.phase = 'authenticating'
+    this.state.registrationNotice = ''
+    try {
+      await this.options.register({ serverURL: this.state.serverURL, username, password })
+      this.state.registrationNotice = '注册成功,请等待管理员开通。开通后使用此账号登录。'
+    } catch (error) { this.state.error = error.message || '注册失败,请重试。' }
+    finally { this.state.phase = 'ready' }
+    return this.snapshot()
+  }
+  async enter() {
+    this.state.phase = 'entering'
+    try {
+      await this.options.activate(this.snapshot())
+      this.state.active = false
+      this.state.phase = 'complete'
+      await this.options.navigate(this.state.serverURL)
+    } catch (error) {
+      this.state.active = true
+      this.state.phase = 'ready'
+      this.state.error = error.message || '打开服务未完成,请重试'
+    }
+    return this.snapshot()
+  }
+}

+ 85 - 0
desktop/onboarding.test.mjs

@@ -0,0 +1,85 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { DesktopOnboarding } from './onboarding.mjs'
+
+function fixture(overrides = {}) {
+  const calls = []
+  const flow = new DesktopOnboarding({
+    remoteServer: () => 'http://remote.test:15300',
+    prepareLocal: async () => { calls.push('prepare'); return 'http://127.0.0.1:15300' },
+    inspect: async () => ({ authenticated: false, setupRequired: true }),
+    authenticate: async value => { calls.push(value); return { username: value.username } },
+    activate: async value => { calls.push({ mode: value.mode, remember: value.remember }) },
+    navigate: async url => { calls.push(url) }, ...overrides,
+  })
+  return { flow, calls }
+}
+test('selection, local preparation and account creation run in order; snapshots contain no credentials', async () => {
+  const { flow, calls } = fixture()
+  await assert.rejects(() => flow.submit({ username: 'admin', password: 'password' }), /检测/)
+  flow.select('local')
+  await flow.prepare()
+  assert.equal(flow.snapshot().setupRequired, true)
+  await assert.rejects(() => flow.submit({ username: 'admin', password: 'password', confirmation: 'different' }), /不一致/)
+  await flow.submit({ username: 'admin', password: 'password', confirmation: 'password', remember: true })
+  assert.deepEqual(calls, ['prepare', { mode: 'local', serverURL: 'http://127.0.0.1:15300', setup: true, username: 'admin', password: 'password' }, { mode: 'local', remember: true }, 'http://127.0.0.1:15300'])
+  assert.equal(flow.snapshot().active, false)
+  assert.equal(JSON.stringify(flow.snapshot()).includes('password'), false)
+  assert.doesNotThrow(() => flow.open({ mode: 'remote' }), 'completed flows can reopen in the same window')
+})
+test('an in-flight server check cannot be switched underneath credentials', async () => {
+  let release
+  const { flow, calls } = fixture({ inspect: () => new Promise(resolve => { release = resolve }) })
+  flow.select('remote')
+  const checking = flow.prepare()
+  assert.throws(() => flow.select('local'), /尚未完成/)
+  await assert.rejects(() => flow.submit({ username: 'admin', password: 'password' }), /检测/)
+  release({ authenticated: false }); await checking
+  assert.equal(flow.snapshot().serverURL, 'http://remote.test:15300')
+  assert.deepEqual(calls, [])
+})
+test('remote setup is blocked; failed checks and wrong passwords stay inline and can be retried', async () => {
+  let checks = 0, logins = 0
+  const { flow } = fixture({
+    inspect: async () => ++checks === 1 ? { setupRequired: true, authenticated: false } : { authenticated: false },
+    authenticate: async () => { if (++logins === 1) throw new Error('密码错误'); return { username: 'user' } },
+  })
+  flow.select('remote'); await flow.prepare()
+  assert.match(flow.snapshot().error, /本机创建管理员/)
+  assert.equal(flow.snapshot().phase, 'error')
+  await flow.prepare()
+  await flow.submit({ username: 'user', password: 'bad' })
+  assert.equal(flow.snapshot().phase, 'ready'); assert.equal(flow.snapshot().error, '密码错误')
+  await flow.submit({ username: 'user', password: 'good' })
+  assert.equal(flow.snapshot().active, false)
+})
+test('valid remembered sessions skip credentials, but reauthorization requests a fresh login', async () => {
+  const { flow, calls } = fixture({ inspect: async () => ({ authenticated: true, user: { username: 'user' } }) })
+  flow.open({ mode: 'remote', serverURL: 'http://remote.test', remember: true })
+  await flow.prepare({ autoEnter: true })
+  assert.equal(flow.snapshot().active, false)
+  flow.open({ mode: 'remote', serverURL: 'http://remote.test', forceLogin: true })
+  await flow.prepare({ autoEnter: true })
+  assert.equal(flow.snapshot().active, true); assert.equal(flow.snapshot().authenticated, false)
+  assert.equal(calls.length, 2)
+})
+test('failed computer enrollment preserves login and offers inline continuation', async () => {
+  const { flow, calls } = fixture({ inspect: async () => ({ authenticated: false }), authenticate: async () => ({ username: 'admin', warning: '电脑授权未恢复' }) })
+  flow.select('remote'); await flow.prepare(); await flow.submit({ username: 'admin', password: 'password' })
+  assert.equal(flow.snapshot().phase, 'ready'); assert.equal(flow.snapshot().authenticated, true)
+  assert.match(flow.snapshot().error, /授权未恢复/); assert.deepEqual(calls, [])
+  await flow.submit(); assert.equal(flow.snapshot().active, false)
+})
+
+test('registration stays anonymous and does not enter or enroll a computer', async () => {
+  const calls = []
+  const flow = new DesktopOnboarding({ remoteServer: () => 'http://127.0.0.1:15300', inspect: async () => ({ registrationAvailable: true }), register: async input => { calls.push(input) }, authenticate: async () => { throw new Error('must not log in') }, activate: async () => { throw new Error('must not activate') } })
+  flow.select('remote'); await flow.prepare()
+  const next = await flow.submit({ register: true, username: 'child', password: 'password', confirmation: 'password' })
+  assert.equal(next.authenticated, false)
+  assert.match(next.registrationNotice, /等待管理员开通/)
+  assert.equal(calls.length, 1)
+  assert.equal(JSON.stringify(next).includes('password'), false)
+  await flow.prepare({ serverURL: 'http://another-server.test' })
+  assert.equal(flow.snapshot().registrationNotice, '', 'registration belongs to the checked server')
+})

+ 4 - 0
desktop/preload.cjs

@@ -1,6 +1,10 @@
 const { contextBridge, ipcRenderer } = require('electron')
 contextBridge.exposeInMainWorld('yaoyaoDesktop', Object.freeze({
   status: () => ipcRenderer.invoke('desktop:status'),
+  selectServer: mode => ipcRenderer.invoke('desktop:onboarding-select', mode),
+  prepareServer: input => ipcRenderer.invoke('desktop:onboarding-prepare', input),
+  login: input => ipcRenderer.invoke('desktop:onboarding-submit', input),
+  openLogin: () => ipcRenderer.invoke('desktop:open-login'),
   retry: () => ipcRenderer.invoke('desktop:retry'),
   forceSync: () => ipcRenderer.invoke('desktop:force-sync'),
   logs: () => ipcRenderer.invoke('desktop:logs'),

+ 0 - 5
desktop/remote-login-preload.cjs

@@ -1,5 +0,0 @@
-const { contextBridge, ipcRenderer } = require('electron')
-contextBridge.exposeInMainWorld('yaoyaoRemoteLogin', Object.freeze({
-  submit: value => ipcRenderer.invoke('desktop-remote-login:submit', value),
-  useLocal: () => ipcRenderer.invoke('desktop-remote-login:use-local'),
-}))

+ 0 - 21
desktop/remote-login.css

@@ -1,21 +0,0 @@
-:root { color-scheme: light dark; }
-* { box-sizing: border-box; }
-body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 28px;
-  font: 14px/1.6 -apple-system, "PingFang SC", "Helvetica Neue", sans-serif;
-  background: #f7f7f7; color: #1d2129; }
-@media (prefers-color-scheme: dark) { body { background: #14181e; color: #dce1e7; } }
-main { width: min(360px, 100%); display: grid; gap: 22px; }
-header { display: grid; justify-items: center; text-align: center; gap: 10px; }
-h1 { margin: 0; font-size: 19px; }
-header p { margin: 0; font-size: 12.5px; opacity: .75; }
-form { display: grid; gap: 14px; padding: 20px; border: 1px solid rgba(128,128,138,.35); border-radius: 14px; background: rgba(127,127,127,.06); }
-label { display: grid; gap: 6px; font-size: 13px; }
-input { font: inherit; padding: 9px 11px; border: 1px solid rgba(128,128,138,.5); border-radius: 8px; background: transparent; color: inherit; min-width: 0; }
-input:focus-visible, button:focus-visible { outline: 2px solid #3b82f6; outline-offset: 1px; }
-button { font: inherit; min-height: 38px; padding: 8px 14px; border: 1px solid rgba(128,128,138,.5); border-radius: 8px; background: transparent; color: inherit; cursor: pointer; }
-button.primary { background: #2f6fed; border-color: #2f6fed; color: #fff; }
-button.primary:disabled { opacity: .55; cursor: default; }
-footer { display: grid; justify-items: center; }
-footer button { border: 0; font-size: 12.5px; opacity: .8; }
-#error { margin: 0; font-size: 12.5px; color: #d5443c; }
-#status { margin: 0; font-size: 12.5px; opacity: .75; }

+ 0 - 17
desktop/remote-login.html

@@ -1,17 +0,0 @@
-<!doctype html>
-<html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self'">
-<title>登录远程 · 夭夭</title><link rel="stylesheet" href="remote-login.css"></head>
-<body><main>
-  <header><img src="icon.png" alt="" width="56" height="56"><h1>登录远程夭夭</h1>
-    <p>连接另一台电脑上的夭夭服务器。登录后本机无需 Hermes,也不运行 Web 服务,窗口直接使用远程夭夭;管理员账号同时会把这台 Mac 注册为可远程控制的电脑。</p></header>
-  <form id="login-form" aria-label="远程登录">
-    <label>服务器地址<input id="server" name="server" required autocomplete="off" spellcheck="false" placeholder="192.168.1.10:15300" inputmode="url"></label>
-    <label>用户名<input id="username" name="username" required autocomplete="username" autocapitalize="none" spellcheck="false"></label>
-    <label>密码<input id="password" name="password" type="password" required autocomplete="current-password"></label>
-    <button type="submit" id="submit" class="primary">登录</button>
-    <p id="error" role="alert" hidden></p>
-    <p id="status" role="status" aria-live="polite" hidden></p>
-  </form>
-  <footer><button type="button" id="use-local">改为作为服务器运行</button></footer>
-</main><script src="remote-login.js"></script></body></html>

+ 0 - 23
desktop/remote-login.js

@@ -1,23 +0,0 @@
-const byId = id => document.getElementById(id)
-const form = byId('login-form')
-const preset = new URLSearchParams(location.search).get('server')
-if (preset) byId('server').value = preset
-form.addEventListener('submit', async event => {
-  event.preventDefault()
-  const error = byId('error'), status = byId('status'), submit = byId('submit')
-  error.hidden = true; status.hidden = false; status.textContent = '正在登录…'; submit.disabled = true
-  try {
-    const result = await window.yaoyaoRemoteLogin.submit({
-      serverURL: byId('server').value,
-      username: byId('username').value,
-      password: byId('password').value,
-    })
-    if (!result.ok) throw new Error(result.error || '登录失败')
-    status.textContent = result.hostRegistered ? '登录成功,已注册本机为电脑…' : '登录成功…'
-  } catch (cause) {
-    status.hidden = true; error.hidden = false
-    error.textContent = cause instanceof Error ? cause.message : '登录失败'
-    submit.disabled = false
-  }
-})
-byId('use-local').addEventListener('click', () => { void window.yaoyaoRemoteLogin.useLocal() })

+ 65 - 10
desktop/remote-login.mjs

@@ -12,45 +12,83 @@ export function normalizeServerURL(input){
   return url.origin
 }
 
+async function requestServer(fetchImpl,url,options){
+  try{return await fetchImpl(url,options)}
+  catch(error){
+    if(['TimeoutError','AbortError'].includes(error.name))throw new Error('连接超时,请检查服务器地址和网络后重试。')
+    throw new Error('无法连接服务器,请检查服务器地址和网络后重试。')
+  }
+}
+
 /** Minimal cookie jar across the bootstrap → login dance. */
 class CookieJar{
-  constructor(){this.cookies=new Map()}
+  constructor(){this.cookies=new Map();this.details=new Map()}
   absorb(response){
     for(const line of response.headers.getSetCookie?.()??[]){
       const pair=line.split(';')[0],eq=pair.indexOf('=')
-      if(eq>0)this.cookies.set(pair.slice(0,eq).trim(),pair.slice(eq+1).trim())
+      if(eq<=0)continue
+      const name=pair.slice(0,eq).trim(),value=pair.slice(eq+1).trim()
+      this.cookies.set(name,value)
+      const attributes=new Map(line.split(';').slice(1).map(part=>{
+        const index=part.indexOf('=')
+        return index<0?[part.trim().toLowerCase(),'']:[part.slice(0,index).trim().toLowerCase(),part.slice(index+1).trim()]
+      }))
+      const detail={name,value,path:attributes.get('path')||'/',httpOnly:attributes.has('httponly'),secure:attributes.has('secure')}
+      const sameSite={strict:'strict',lax:'lax',none:'no_restriction'}[attributes.get('samesite')?.toLowerCase()]
+      if(sameSite)detail.sameSite=sameSite
+      const maxAge=attributes.get('max-age'),expires=Date.parse(attributes.get('expires'))
+      if(maxAge!==undefined&&/^-?\d+$/.test(maxAge))detail.expirationDate=Date.now()/1000+Number(maxAge)
+      else if(Number.isFinite(expires))detail.expirationDate=expires/1000
+      this.details.set(name,detail)
     }
   }
   header(){return [...this.cookies.entries()].map(([name,value])=>`${name}=${value}`).join('; ')}
 }
 
-export async function remoteSession(serverURL,{username,password},fetchImpl=globalThis.fetch){
+export async function inspectServer(serverURL,fetchImpl=globalThis.fetch){
+  const base=normalizeServerURL(serverURL)
+  const response=await requestServer(fetchImpl,new URL('/api/app/bootstrap',base),{
+    headers:{accept:'application/json'},redirect:'error',signal:AbortSignal.timeout(10000),
+  })
+  if(!response.ok)throw new Error(`无法连接服务器(HTTP ${response.status})`)
+  const info=await response.json().catch(()=>{throw new Error('服务器响应无效,请确认这是夭夭服务器地址')})
+  if(typeof info?.csrfToken!=='string'||typeof info?.authenticated!=='boolean'||(info.serverKind&&info.serverKind!=='yaoyao-web'))
+    throw new Error('服务器响应无效,请确认这是夭夭服务器地址')
+  return info
+}
+
+export async function remoteSession(serverURL,{username,password,setup=false},fetchImpl=globalThis.fetch){
   const base=normalizeServerURL(serverURL)
   const user=String(username??'').trim(),pass=String(password??'')
   if(!user||!pass)throw new Error('请填写用户名和密码')
   const jar=new CookieJar()
-  const bootstrap=await fetchImpl(new URL('/api/app/bootstrap',base),{headers:{accept:'application/json'},redirect:'error'})
+  const bootstrap=await requestServer(fetchImpl,new URL('/api/app/bootstrap',base),{headers:{accept:'application/json'},redirect:'error',signal:AbortSignal.timeout(10000)})
   jar.absorb(bootstrap)
   if(!bootstrap.ok)throw new Error(`无法连接服务器(HTTP ${bootstrap.status})`)
   const info=await bootstrap.json().catch(()=>{throw new Error('服务器响应无效,请确认这是夭夭 Web 地址')})
   if(typeof info?.csrfToken!=='string')throw new Error('服务器响应无效,请确认这是夭夭 Web 地址')
-  const response=await fetchImpl(new URL('/api/app/login',base),{
-    method:'POST',redirect:'error',
+  const response=await requestServer(fetchImpl,new URL(setup?'/api/app/setup':'/api/app/login',base),{
+    method:'POST',redirect:'error',signal:AbortSignal.timeout(15000),
     headers:{accept:'application/json','content-type':'application/json',cookie:jar.header(),'x-csrf-token':info.csrfToken,origin:base},
     body:JSON.stringify({username:user,password:pass}),
   })
   jar.absorb(response)
-  if(response.status===401||response.status===403)throw new Error('用户名或密码不正确')
+  if(!setup&&(response.status===401||response.status===403)) {
+    const body=await response.json().catch(()=>({}))
+    if(body.code==='account_pending_approval')throw new Error(body.error || '账号尚未开通,请等待管理员开通。')
+    throw new Error('用户名或密码不正确')
+  }
+  if(setup&&!response.ok){const body=await response.json().catch(()=>({}));throw new Error(body.error?.message||body.error||`创建管理员失败(HTTP ${response.status})`)}
   if(!response.ok)throw new Error(`登录失败(HTTP ${response.status})`)
   const result=await response.json().catch(()=>{throw new Error('登录响应无效')})
   if(!result?.user?.id)throw new Error('登录响应无效')
-  return {origin:base,user:result.user,csrfToken:String(result.csrfToken??info.csrfToken),cookies:[...jar.cookies.entries()]}
+  return {origin:base,user:result.user,csrfToken:String(result.csrfToken??info.csrfToken),cookies:[...jar.cookies.entries()],cookieDetails:[...jar.details.values()]}
 }
 
 export async function enrollDesktopHost(session,{name,installId,previousHostId},fetchImpl=globalThis.fetch){
   const cookie=session.cookies.map(([key,value])=>`${key}=${value}`).join('; ')
-  const response=await fetchImpl(new URL('/api/app/admin/desktop-hosts',session.origin),{
-    method:'POST',redirect:'error',
+  const response=await requestServer(fetchImpl,new URL('/api/app/admin/desktop-hosts',session.origin),{
+    method:'POST',redirect:'error',signal:AbortSignal.timeout(15000),
     headers:{accept:'application/json','content-type':'application/json',cookie,'x-csrf-token':session.csrfToken,origin:session.origin},
     body:JSON.stringify({name:String(name).slice(0,100),...(installId?{installId}:{}),...(previousHostId?{previousHostId}:{})}),
   })
@@ -60,3 +98,20 @@ export async function enrollDesktopHost(session,{name,installId,previousHostId},
   if(typeof result?.token!=='string'||!result?.host?.id)throw new Error('注册电脑响应无效')
   return result
 }
+
+/** Registration owns a temporary cookie jar and never activates a desktop session. */
+export async function remoteRegistration(serverURL,{username,password},fetchImpl=globalThis.fetch){
+  const base=normalizeServerURL(serverURL),jar=new CookieJar()
+  const bootstrap=await requestServer(fetchImpl,new URL('/api/app/bootstrap',base),{redirect:'error',signal:AbortSignal.timeout(10000)})
+  jar.absorb(bootstrap)
+  const info=await bootstrap.json().catch(()=>({}))
+  if(!bootstrap.ok||info.registrationAvailable!==true||info.setupRequired||typeof info.csrfToken!=='string')throw new Error('当前服务器尚不支持子账号注册,请联系管理员初始化或升级。')
+  const response=await requestServer(fetchImpl,new URL('/api/app/register',base),{
+    method:'POST',redirect:'error',signal:AbortSignal.timeout(15000),
+    headers:{'content-type':'application/json',cookie:jar.header(),'x-csrf-token':info.csrfToken,origin:base},
+    body:JSON.stringify({username:String(username).trim(),password}),
+  })
+  const result=await response.json().catch(()=>({}))
+  if(!response.ok)throw new Error(result.error || `注册失败(HTTP ${response.status})`)
+  if(result.registrationStatus!=='pending')throw new Error('注册响应无效,请联系管理员确认账号状态。')
+}

+ 37 - 0
desktop/remote-login.test.mjs

@@ -75,3 +75,40 @@ test('wrong credentials and non-admin accounts surface clear errors',async()=>{
     fake.server.close();fake.server.closeAllConnections?.()
   }
 })
+
+test('native login preserves cookie expiry, scope and same-site policy', async () => {
+  let request = 0
+  const before = Date.now() / 1000
+  const auth = await remoteSession('https://server.test', { username: 'admin', password: 'password' }, async () => {
+    if (++request === 1) return new Response(JSON.stringify({ csrfToken: 'fixture' }), { headers: { 'set-cookie': 'csrf=one; Path=/; HttpOnly; Secure; SameSite=Strict' } })
+    return new Response(JSON.stringify({ user: { id: 'admin', role: 'admin' } }), { headers: { 'set-cookie': 'session=two; Path=/; Max-Age=3600; HttpOnly; Secure; SameSite=Strict' } })
+  })
+  const session = auth.cookieDetails.find(cookie => cookie.name === 'session')
+  assert.equal(session.secure, true); assert.equal(session.httpOnly, true); assert.equal(session.sameSite, 'strict')
+  assert.equal(session.path, '/')
+  assert.ok(session.expirationDate >= before + 3600 && session.expirationDate <= Date.now() / 1000 + 3600)
+  assert.equal(auth.cookieDetails.find(cookie => cookie.name === 'csrf').expirationDate, undefined)
+})
+
+test('pending approval is not mislabeled as a bad password', async () => {
+  let calls = 0
+  await assert.rejects(() => remoteSession('https://server.test', { username: 'child', password: 'password' }, async () => {
+    if (++calls === 1) return Response.json({ csrfToken: 'csrf' })
+    return Response.json({ code: 'account_pending_approval', error: '账号尚未开通,请等待管理员开通。' }, { status: 403 })
+  }), /等待管理员开通/)
+})
+
+test('registration uses only anonymous bootstrap and does not return a session', async () => {
+  const { remoteRegistration } = await import('./remote-login.mjs')
+  const calls = []
+  await remoteRegistration('https://server.test', { username: ' child ', password: 'password' }, async (url, options) => {
+    calls.push(url.pathname)
+    if (url.pathname.endsWith('bootstrap')) return Response.json({ registrationAvailable: true, csrfToken: 'csrf' }, { headers: { 'set-cookie': 'csrf-cookie=value; Path=/; HttpOnly' } })
+    assert.equal(options.headers.origin, 'https://server.test')
+    assert.equal(options.headers['x-csrf-token'], 'csrf')
+    assert.match(options.headers.cookie, /csrf-cookie=value/)
+    assert.deepEqual(JSON.parse(options.body), { username: 'child', password: 'password' })
+    return Response.json({ registrationStatus: 'pending' }, { status: 201 })
+  })
+  assert.deepEqual(calls, ['/api/app/bootstrap', '/api/app/register'])
+})

+ 4 - 3
desktop/service-manager.mjs

@@ -115,14 +115,14 @@ export class DesktopServiceManager {
   }
   async boot({ force = false } = {}) {
     const generation = ++this.generation
-    this.publish({ phase: 'starting', message: '正在启动本地服务…' })
+    this.publish({ phase: 'starting', stage: 'checking', message: '正在检查本地服务…' })
     try {
-      await this.options.prepareHome?.(message => this.publish({ phase: 'starting', message }))
+      await this.options.prepareHome?.(message => this.publish({ phase: 'starting', stage: 'checking', message }))
       await mkdir(this.options.home, { recursive: true, mode: 0o700 })
       this.root = await realpath(this.options.home)
       this.updateNotice = undefined
       if (this.options.synchronize) {
-        try { await this.options.synchronize(message => this.publish({ phase: 'starting', message }), { force }) }
+        try { await this.options.synchronize(message => this.publish({ phase: 'starting', stage: 'installing', message }), { force }) }
         catch (error) {
           // Busy is reported before stopping or switching. Other failures still
           // fail closed; the existing service must pass the usual identity checks.
@@ -131,6 +131,7 @@ export class DesktopServiceManager {
         }
         if (generation !== this.generation || this.stopping) return
       }
+      this.publish({ phase: 'starting', stage: 'starting', message: '正在启动并检查服务…' })
       let record = await this.readRecord()
       if (generation !== this.generation || this.stopping) return
       if (record?.url) {

+ 3 - 1
desktop/service-sync.test.mjs

@@ -1,3 +1,4 @@
+import { enterLocal } from './test-support/onboarding.mjs'
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
 import { mkdtemp, readFile, writeFile, rm, cp, realpath } from 'node:fs/promises'
@@ -75,6 +76,7 @@ test('App first launch installs an independent Web; Web remains up after quit an
     }
     app = await launch()
     const page = await app.firstWindow()
+    await enterLocal(page, { username: 'sync-fixture', password: 'sync-fixture-password' })
     await page.waitForURL(`http://127.0.0.1:${port}/**`, { timeout: 90000 })
     const record = JSON.parse(await readFile(join(home, 'service-instance.json'), 'utf8'))
     assert.equal(record.desktopOwned, false)
@@ -88,7 +90,7 @@ test('App first launch installs an independent Web; Web remains up after quit an
     }
     const support = await page.evaluate(async () => {
       const bootstrap = await (await fetch('/api/app/bootstrap')).json()
-      const setup = await fetch('/api/app/setup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': bootstrap.csrfToken },
+      const setup = await fetch('/api/app/login', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': bootstrap.csrfToken },
         body: JSON.stringify({ username: 'sync-fixture', password: 'sync-fixture-password' }) })
       if (!setup.ok) throw new Error('验收账号创建失败')
       return (await fetch('/api/app/system/update/status')).json()

+ 4 - 1
desktop/startup-feedback.test.mjs

@@ -1,3 +1,4 @@
+import { enterLocal } from './test-support/onboarding.mjs'
 import {test} from 'node:test'
 import assert from 'node:assert/strict'
 import {mkdtemp,realpath,readFile,rm,mkdir,cp,writeFile,readdir} from 'node:fs/promises'
@@ -29,11 +30,13 @@ test('built startup page shows a real helper error and Retry recovers into the W
     await page.locator('#status[role="alert"]').waitFor({timeout:30000})
     assert.match(await page.locator('#status').textContent(),/已有服务未注册/)
     assert.equal(await page.getByRole('button',{name:'重试',exact:true}).isVisible(),true)
+    await page.locator('#install-details summary').click()
     assert.equal(await page.getByRole('button',{name:'查看日志',exact:true}).isVisible(),true)
     await mkdir(join(root,'test-results/desktop'),{recursive:true})
     await page.screenshot({path:join(root,'test-results/desktop/startup-error-retry.png')})
     await new Promise(done=>blocker.close(done))
     await page.getByRole('button',{name:'重试',exact:true}).click()
+    await enterLocal(page)
     await page.waitForURL(`http://127.0.0.1:${port}/**`,{timeout:45000})
     assert.equal((await localRequest(`http://127.0.0.1:${port}/healthz`)).body.ok,true)
     await page.screenshot({path:join(root,'test-results/desktop/startup-recovered.png')})
@@ -65,7 +68,7 @@ test('same-version unknown ancestry offers an explicit overwrite and preserves e
   assert.match(await page.locator('#status').textContent(),/构建先后关系无法确定/)
   assert.equal(verifyRuntimePackage(driver.snapshot().root).commit,'f'.repeat(40))
   await mkdir(join(root,'test-results/desktop'),{recursive:true});await page.screenshot({path:join(root,'test-results/desktop/same-version-force.png')})
-  await button.click();await page.waitForURL(`http://127.0.0.1:${port}/**`,{timeout:45000})
+  await button.click();await enterLocal(page);await page.waitForURL(`http://127.0.0.1:${port}/**`,{timeout:45000})
   const record=JSON.parse(await readFile(join(home,'service-instance.json'),'utf8'))
   const identity=await localRequest(`http://127.0.0.1:${port}/desktop/service`,record.token)
   assert.equal(identity.body.build.artifactDigest,original.artifactDigest)

+ 8 - 0
desktop/test-support/onboarding.mjs

@@ -0,0 +1,8 @@
+/** Complete the real native first-run form; never bypass authentication. */
+export async function enterLocal(page, { username = 'desktop-fixture', password = 'desktop-fixture-password' } = {}) {
+  await page.locator('#login-form').waitFor({ timeout: 90000 })
+  await page.locator('#username').fill(username)
+  await page.locator('#password').fill(password)
+  if (await page.locator('#confirmation-field').isVisible()) await page.locator('#confirmation').fill(password)
+  await page.locator('#submit').click()
+}

+ 1 - 0
desktop/update-entry.test.mjs

@@ -17,6 +17,7 @@ test('only the main local app can open the native updater and repeated requests
   const identityReady = new Promise(resolve => { releaseIdentity = resolve })
   const server = createServer(async (req, res) => {
     if (req.url === '/desktop/service') { await identityReady; res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify(identity)) }
+    else if(req.url==='/api/app/bootstrap'){res.setHeader('Content-Type','application/json');res.end(JSON.stringify({authenticated:true,csrfToken:'fixture'}))}
     else { res.setHeader('Content-Type', 'text/html; charset=utf-8'); res.end('<title>Update entry fixture</title><button onclick="window.yaoyaoDesktop.openUpdates()">检测更新</button>') }
   })
   await new Promise(done => server.listen(0, '127.0.0.1', done))

+ 1 - 1
docker.env.example

@@ -3,7 +3,7 @@ HERMES_YAOYAO_BIND_ADDRESS=127.0.0.1
 HERMES_YAOYAO_PUBLISHED_PORT=15300
 # 远程通用镜像支持 AMD64 / ARM64;每次发布更新 latest 并保留旧版本标签。
 # HERMES_YAOYAO_IMAGE=samienluo/yaoyao:latest
-# 固定版本:samienluo/yaoyao:v0.4.61;仅 AMD64:samienluo/yaoyao:v0.4.61-amd。
+# 固定版本:samienluo/yaoyao:v0.4.62;仅 AMD64:samienluo/yaoyao:v0.4.62-amd。
 # 留空时使用本地构建名称 yaoyao:local。
 # YAOYAO_DESKTOP_IMAGE=hermes-yaoyao-desktop:0.4.0
 # Cursor Universal 兼容桌面的本地构建名称;基础镜像在 deploy/computer/Dockerfile.cursor 中固定。

+ 23 - 0
docs/design/desktop-onboarding/README.md

@@ -0,0 +1,23 @@
+# 单页安装与登录
+
+已确认的设计见 `approved-design.png`。桌面 App 的服务器选择、服务准备、创建管理员和登录在主窗口同一个 `boot.html` 页面中完成。
+
+- 首次启动选择本机运行或远程连接;记住选择后再次启动自动检测。
+- 本机复用服务管理器的环境检查、组件准备、服务启动流程。只有服务器要求初始化时才创建管理员;否则登录已有账号。
+- 安装阶段显示后台实际步骤与消息,不显示未经测量的百分比。已完成的准备步骤收起为摘要,详情仍可在页内展开。
+- 远程服务器检测成功后才接受账号密码。更改服务器地址会清空凭据并要求重新检测。
+- 连接失败、登录失败、电脑授权失败均在页面内说明。账号登录成功但电脑授权失败时,可以继续进入工作区。
+- 登录会话保留服务器提供的有效期和 SameSite 设置;“记住本次选择”保存服务器与运行方式,不保存密码。
+- 设置中的模式切换、更换服务器、会话过期和重新授权复用主页面。原生登录弹窗及其四个资源文件已移除。
+
+`preview-*.png` 由 Codex 内置浏览器打开实际页面样式与控制器、使用模拟服务后截图。`remote-*.png` 来自 Electron 集成测试;后者验证真实 IPC、HTTP 认证、Cookie 和窗口数量。
+
+运行交互预览:
+
+```sh
+node scripts/preview-desktop-onboarding.mjs
+```
+
+打开 `http://127.0.0.1:4388`。预览会明确标注模拟服务,不会安装组件或连接输入的服务器。
+
+验证覆盖首次启动、本机初始化、已有服务复用、错误重试、同版本覆盖恢复、远程登录、会话重启恢复、权限隔离、窗口内切换、服务崩溃恢复及后台生命周期。设计核对记录位于仓库根目录 `design-qa.md`。

BIN
docs/design/desktop-onboarding/approved-design.png


BIN
docs/design/desktop-onboarding/preview-local-account.png


BIN
docs/design/desktop-onboarding/preview-local-install.png


BIN
docs/design/desktop-onboarding/preview-narrow.png


BIN
docs/design/desktop-onboarding/preview-remote.png


BIN
docs/design/desktop-onboarding/remote-dark.png


BIN
docs/design/desktop-onboarding/remote-login.png


BIN
docs/design/desktop-onboarding/remote-narrow.png


+ 7 - 7
docs/docker-install.md

@@ -12,14 +12,14 @@
 
 | 标签 | 架构 |
 | --- | --- |
-| `v0.4.61-amd` | `linux/amd64` |
-| `v0.4.61` | `linux/amd64`、`linux/arm64`,拉取时自动匹配 |
-| `latest` | 最新稳定通用镜像,当前指向与 `v0.4.61` 相同的镜像 |
+| `v0.4.62-amd` | `linux/amd64` |
+| `v0.4.62` | `linux/amd64`、`linux/arm64`,拉取时自动匹配 |
+| `latest` | 最新稳定通用镜像,当前指向与 `v0.4.62` 相同的镜像 |
 
 ```sh
-docker pull samienluo/yaoyao:v0.4.61
+docker pull samienluo/yaoyao:v0.4.62
 # 需要固定 AMD64 时:
-docker pull samienluo/yaoyao:v0.4.61-amd
+docker pull samienluo/yaoyao:v0.4.62-amd
 ```
 
 每次新版本发布都会更新 `latest`,旧版本标签继续保留。需要固定部署版本时使用具体版本标签。
@@ -34,7 +34,7 @@ cp docker.env.example docker.env
 
 | 配置 | 用途 |
 | --- | --- |
-| `HERMES_YAOYAO_IMAGE` | 远程镜像可设为 `samienluo/yaoyao:v0.4.61` 或 `samienluo/yaoyao:latest`;未设置时使用本地构建名称 |
+| `HERMES_YAOYAO_IMAGE` | 远程镜像可设为 `samienluo/yaoyao:v0.4.62` 或 `samienluo/yaoyao:latest`;未设置时使用本地构建名称 |
 | `HERMES_YAOYAO_UPSTREAM` | Hermes 上游地址,默认 `http://host.docker.internal:9119` |
 | `HERMES_YAOYAO_BIND_ADDRESS` | Web 的宿主机发布地址,默认 `127.0.0.1`;局域网访问可设为 `0.0.0.0` |
 | `HERMES_YAOYAO_PUBLISHED_PORT` | 宿主机 Web 端口,默认 `15300` |
@@ -191,7 +191,7 @@ curl --fail http://127.0.0.1:15300/healthz
 使用 Docker Hub 发布镜像时,在 `docker.env` 设置:
 
 ```dotenv
-HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.61
+HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.62
 YAOYAO_CURSOR_DESKTOP_IMAGE=samienluo/yaoyao-desktop:v0.4.12-cursor-amd
 ```
 

+ 44 - 0
docs/releases/v0.4.62.md

@@ -0,0 +1,44 @@
+# 夭夭 AI v0.4.62
+
+本次发布 Web、macOS Apple Silicon 桌面版和 Docker 双架构镜像,不提供 APK。
+
+## 更新内容
+
+- 桌面端将服务器选择、环境检查、服务准备、创建管理员与登录整合到主窗口的同一个页面。安装阶段显示实际步骤,支持展开详情和失败重试。
+- 远程连接先检测服务器,再填写账号;修改地址后清空旧凭据并重新检测。登录失败、会话过期和电脑授权失败均在页面内说明,模式切换与更换服务器复用此流程。
+- “记住本次选择”保存服务器和运行方式,不保存密码;保留服务器设置的登录有效期,并修复恢复登录时的初始导航竞态。
+- Web 与 macOS 登录页新增子账号注册。注册成功后等待管理员分配可用基础机器人并开通,不会自动登录或创建 Bot。
+- 修复子账号 Bot 初始化快照被拦截的问题,补齐本人项目、记忆和协作入口;继续保留来源授权、跨账号隔离、撤权停止及管理员权限边界。
+- 补充登录失效、权限撤回、来源不可用和离线恢复提示;保留合法 Bot 会话深链接,换账号时清理草稿与旧事件连接。
+
+## 升级说明
+
+- 升级前备份完整 `.yaoyao` 数据目录。旧账号保留原启用状态、密码、来源分配及首次改密要求,不会自动获得额外授权。
+- 请先更新服务端,再更新桌面客户端。注册仅作用于当前连接的服务器;管理员尚未初始化或服务器版本不支持时,不开放注册。
+- 注册账号默认待开通;管理员需分配至少一个可用基础机器人后开通,普通“启用”操作不能绕过审核。
+- 本次不构建、不上传 APK,旧版本标签和附件继续保留。
+- 主项目采用 Apache-2.0,第三方组件保留各自许可与署名。
+
+## 下载
+
+- `Yaoyao-0.4.62-arm64.dmg`:macOS Apple Silicon,Apple Development 开发签名,未公证。
+- `Yaoyao-0.4.62-source.tar.gz`:Web/桌面源码及部署配置。
+- `SHA256SUMS.txt`:上述两个附件的 SHA-256 校验值。
+
+## Docker Hub
+
+| 镜像 | 架构 |
+| --- | --- |
+| `samienluo/yaoyao:v0.4.62-amd` | `linux/amd64` |
+| `samienluo/yaoyao:v0.4.62` | `linux/amd64`、`linux/arm64` |
+| `samienluo/yaoyao:latest` | 验证后更新为同一通用镜像 |
+
+```sh
+docker pull samienluo/yaoyao:v0.4.62
+docker compose --env-file docker.env pull web
+docker compose --env-file docker.env up -d --no-build web
+```
+
+Compose 中设置 `HERMES_YAOYAO_IMAGE=samienluo/yaoyao:v0.4.62`。镜像发布到 Docker Hub,GitHub 仅提供安装包、源码及校验文件。
+
+附件摘要、镜像摘要与实际验证结果见 [GitHub 发布页](https://github.com/Lsamien/yaoyao/releases/tag/v0.4.62)。

+ 15 - 2
docs/subaccount-permissions.md

@@ -9,8 +9,19 @@
 - 账号 ID 从登录会话取得。Agent、聊天、任务、运行、交互、文件和事件继续按 owner 隔离,管理员也不会通过自己的 Bot 列表读取子账号会话。
 - 创建群、加入成员、发送消息、启动/恢复执行、建立上游会话、提交 prompt 和审批答复都会校验来源权限。异步读取基础目录之后再次校验,避免撤权竞态。
 - 修改分配、重置密码、禁用或删除账号会让旧会话失效,并请求停止该账号已存在的运行。撤销后的 Agent 配置和本人历史保留,但不能继续调用、编辑或加入新群。上游已经执行完成的工具副作用无法撤销。
-- 子账号采用允许列表访问应用接口;原生 REST、HTTP/SSE 实时接口、原生 Bot 中继、全局语音密钥、原生媒体路径(`/Users/...`、`/attachments/...`)均拒绝。自己的附件使用 owner 隔离的 `/api/app/files/:id/...`。
-- Web 在渲染路由前强制进入 `/conversations`。iOS 按当前服务身份强制 Bot 模式;服务器仍是最终权限边界,旧客户端也无法绕过。
+- 子账号采用允许列表访问应用接口;Bot 初始化快照,以及项目、记忆、协作接口按方法和路径放行,内部继续检查 owner 和来源分配。原生 REST、HTTP/SSE 实时接口、原生 Bot 中继、全局语音密钥、原生媒体路径(`/Users/...`、`/attachments/...`)均拒绝。自己的附件使用 owner 隔离的 `/api/app/files/:id/...`。
+- Web 等待路由初始化后检查账号模式,保留合法的 Bot 会话深链接。四端子账号均使用 Bot 模式;服务器仍是最终权限边界,旧客户端也无法绕过。能力声明不向子账号提供全局语音、原生上下文和节点入口。
+
+## 注册与开通
+
+- Web、macOS 独立启动页、iOS、Android 的登录界面提供“没有账号?注册子账号”。注册仅作用于当前连接的服务器;成功后不登录、不创建 Bot。
+- 匿名 `GET /api/app/bootstrap` 提供 CSRF 和 `registrationAvailable`。管理员尚未初始化时为 false;旧服务器未提供标记时,新客户端提示不支持注册。
+- `POST /api/app/register` 仅接收 `username`、`password`,沿用用户名规则和至少 8 位密码要求。创建 `role=user`、`enabled=false`、`assignedProfiles=[]`、`mustChangePassword=false`、`registrationStatus=pending`,返回 201,不签发业务会话。
+- 注册复用 Origin/Cookie/CSRF 校验,额外按直连 IP 限制每 15 分钟 10 次请求,超限返回 429 和 `Retry-After`。不信任转发 IP 请求头;多用户共享反向代理出口时共享该限额。
+- 正确密码登录待开通账号返回 403 / `account_pending_approval`,错误密码仍为原有 401。兼容登录入口同样生效。
+- 管理员在现有“用户与权限”中选择基础机器人并点击“分配并开通”。`POST /api/app/admin/users/:userID/approve` 接收 `assignedProfiles`,核对实时本机 Profile 目录,要求至少一个可用来源,在同次保存中写入分配、已开通、启用状态。
+- 普通启用接口不能开通 pending 账号。管理员原有创建、分配、启停、重置密码、删除操作继续保留。旧账号缺失 `registrationStatus` 时按 approved 处理,不改变其启用状态、密码、分配或首次改密要求。
+- 先更新服务端,再更新客户端。旧客户端保持现有登录协议,管理员开通后即可登录;原有账号不会获得默认机器人分配。
 
 本实现是 Web/iOS 账号与服务 API 的授权隔离,不创建 Hermes 工具执行的操作系统沙箱。分配的 Profile 仍按 Hermes 自身的工具权限运行,工具可访问的磁盘和外部服务范围需要在 Hermes 执行环境中约束。
 
@@ -19,3 +30,5 @@
 - `tests/server/subaccountPermissions.test.ts` 使用真实账号、Cookie 和 CSRF,覆盖默认拒绝、Profile/节点伪造、REST/实时/媒体/密钥入口、跨 owner 资源和撤权。
 - `tests/e2e/workspace-chat.spec.ts` 的 subaccount 用例验证管理员分配、首次改密、限制后的创建列表、隐藏模式菜单和手输旧路由重定向。
 - iOS `WorkspaceChatTests` 和 `AuthAndRESTTests` 覆盖服务权限解析、能力撤回和保留的原生模式设置被纠正。
+- `tests/server/subaccountRegistration.test.ts` 通过完整应用中间件覆盖注册、审核、知识与附件隔离、SSE 鉴权和禁用后的旧连接关闭;不替换认证。
+- 四端具体结果和未完成的真实环境验收见 [2026-09-21 验证记录](verification/2026-09-21-subaccount-bot.md)。

+ 62 - 0
docs/verification/2026-09-21-subaccount-bot.md

@@ -0,0 +1,62 @@
+# 子账号 Bot 与注册开通验证记录
+
+日期:2026-09-21。范围:yaoyao(服务端、Web、macOS)、yaoyao-mobile、yaoyao-android。官网和云端目录未修改。
+
+## 实现
+
+修复四端共用的 Bot 快照被子账号允许列表拦截的问题,并补齐按方法限定的项目、记忆、协作入口。来源授权、owner 隔离、撤权停止和管理员权限边界继续由服务端控制。子账号能力声明去除管理员专属入口。
+
+四端增加应用内子账号注册,macOS 包含独立启动页。注册不创建会话;管理员在现有用户页面分配至少一个可用本机基础机器人后开通。旧账号按已开通兼容,保留原状态和权限;普通启用不能绕过审核。
+
+补充登录失效、权限撤回和来源不可用提示,停止权限错误后的重连;Web 明确处理离线与恢复、清理换账号时的草稿和事件连接。修复 Web 初始化丢失会话深链接和 Electron 记住登录时初始页面导航竞态。管理员登录、原生模式和电脑授权协议未变。
+
+## 已执行验证
+
+| 范围 | 结果 | 说明 |
+| --- | --- | --- |
+| 服务端 / Web Vitest 全量 | 1543 通过,27 跳过 | 192 个测试文件通过;16 个带环境条件的文件跳过。Node 26 使用 `NODE_OPTIONS=--no-experimental-webstorage`,避免其全局 localStorage 与 jsdom 冲突 |
+| 新增完整中间件注册与权限测试 | 4 通过(包含于上项) | 真实账号、Cookie、Origin、CSRF;初始化限制、严格字段、用户名重复、密码校验、限流、pending 登录拒绝、禁止直接启用、可用来源审核、快照、项目、记忆读写/导出/删除、附件与跨账号访问、SSE 及禁用后旧流关闭 |
+| Web 子账号端到端 | 2 通过 | 分配、首次改密、注册、等待开通、管理员审核、创建 Bot、实际应用运行器收到回复、正文呈现、离线恢复、刷新保留会话、管理员列表隔离、没有误请求管理员接口 |
+| Electron 全量 | 54 通过 | 独立窗口注册、登录失败、记住登录、原有管理员电脑授权、安装/同步/重试、升级与退出流程;后续注册提示清理改动另复测 13 项登录相关测试通过 |
+| iOS | 212 通过,1 跳过 | AuthAndRESTTests、WorkspaceChatTests、LaunchSmokeTests;包含匿名注册 CSRF、旧服务器提示、登录页切换、来源诊断、403 停止重连、Bot 与账号切换回归 |
+| Android JVM | 65 通过 | core:network 52 项、app 13 项;包含注册 Cookie/CSRF/Origin、旧服务器拒绝、SSE 401/403、来源诊断 |
+| Android 相关仪器测试 | 4 通过 | LoginScreenTest、WorkspacePermissionsTest;注册确认密码与原登录入口、Bot 权限显示和记忆配置 |
+| 构建 | 通过 | Web/服务端、Electron `desktop:build`、iOS Simulator 构建及测试、Android `assembleDebug`。未生成新的签名发行包 |
+
+Web 回复测试使用真实夭夭认证、中间件和 WorkspaceRuntime,Hermes 上游为仓库确定性协议测试服务;没有关闭 Bot 执行或替换认证来证明聊天成功。移动端协议测试使用本地 HTTP/URLProtocol 测试服务,不能视作四端真实 Hermes 联调。
+
+## 全量界面回归的已有失败
+
+为区分本次变化与已有问题,分别使用独立 Git worktree 复测了修改前版本,未改动用户工作区:
+
+- Web 基线 `8470ebd`:原有 12 项 workspace 浏览器测试中 5 通过、7 失败。本次全量运行重现同样 7 项失败;涉及旧思考计时断言、身份造型入口、4 项旧流式 Markdown DOM 选择器、旧附件卡片选择器。新增子账号用例及原有子账号用例单独均通过。这里没有把全量浏览器回归标为通过。
+- Android 基线 `780407c`:WorkspaceParityFlowsTest 的 7 项中 3 通过、4 失败,与修改后相同。失败项为群聊任务切换、创建空白任务、电脑说明可见性、归档恢复;测试服务响应与界面断言需要后续对齐。未改动管理员业务行为来迁就这些断言。
+
+## 未完成的真实环境验收
+
+本机测试 Hermes `127.0.0.1:9119` 状态接口可达,但工具桥能力接口 `/api/plugins/yaoyao-bot-bridge/capabilities?profile=default` 返回 401 Unauthorized;未取得该测试服务的有效登录会话,状态还报告 gateway stopped。
+
+因此四端分别连接真实 Hermes 的完整消息往返、真实上游断线恢复,以及真实工具审批/停止、协作、记忆提炼、定时任务执行,仍未完成现场验收。原生三端从注册到管理员开通再到真实模型回复的完整闭环也未完成;不能用上述模拟上游或协议测试结果代替。需要可登录且工具桥已启用的测试 Hermes 环境后补验。
+
+服务端新增兼容接口应先发布,再交付客户端更新;当前仅完成本地实现、构建与上述验证,未修改正在运行的 Hermes 配置或部署服务。
+
+## 复现命令
+
+```sh
+# yaoyao
+NODE_OPTIONS=--no-experimental-webstorage npm test
+npx playwright test -c playwright.workspace.config.ts -g subaccount
+npm run desktop:test
+npm run desktop:build
+
+# yaoyao-mobile:XcodeBuildMCP / Xcode
+# scheme YaoYaoAI,模拟器 Yaoyao Workspace QA
+# only-testing: YaoYaoAITests/AuthAndRESTTests、YaoYaoAITests/WorkspaceChatTests、YaoYaoAIUITests/LaunchSmokeTests
+
+# yaoyao-android:配置 JDK 17 与 Android SDK 后
+./gradlew :core:network:test :app:testDebugUnitTest :app:assembleDebug
+python3 scripts/parity-fixture-server.py --port 18777
+./gradlew :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=cn.samien.yaoyao.hermes.LoginScreenTest,cn.samien.yaoyao.hermes.WorkspacePermissionsTest
+```
+
+保留工作区原有的 `.zcode/`、iOS 工程/版本配置与 IPA、Android `.DS_Store`,不纳入本次提交。

+ 2 - 2
package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "yaoyao",
-  "version": "0.4.61",
+  "version": "0.4.62",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "yaoyao",
-      "version": "0.4.61",
+      "version": "0.4.62",
       "license": "Apache-2.0",
       "dependencies": {
         "@koa/bodyparser": "^5.0.0",

+ 1 - 1
package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaoyao",
-  "version": "0.4.61",
+  "version": "0.4.62",
   "private": true,
   "license": "Apache-2.0",
   "description": "夭夭 AI:聊天、多 Agent 团队、文件库与电脑工作空间",

+ 3 - 3
release.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "releaseVersion": "0.4.61",
-  "webVersion": "0.4.61",
-  "gitTag": "v0.4.61"
+  "releaseVersion": "0.4.62",
+  "webVersion": "0.4.62",
+  "gitTag": "v0.4.62"
 }

+ 1 - 1
scripts/build-desktop.mjs

@@ -31,7 +31,7 @@ const shell = resolve(out, 'shell')
 await mkdir(shell)
 await cp(resolve(root, 'bin/lib/data-home.mjs'), resolve(shell, 'data-home.mjs'))
 for (const file of await readdir(resolve(root, 'desktop'))) {
-  if (file === 'data-home.mjs' || file.endsWith('.test.mjs') || !/\.(js|mjs|cjs|html|css|png)$/.test(file)) continue
+  if (file === 'data-home.mjs' || file.endsWith('.test.mjs') || !/\.(js|mjs|cjs|html|css|png|svg)$/.test(file)) continue
   if(file==='file-transfer.mjs'){await build({entryPoints:[resolve(root,'desktop',file)],outfile:resolve(shell,file),bundle:true,platform:'node',format:'esm',target:'node24'});continue}
   if(/\.(js|mjs|cjs)$/.test(file))execFileSync(process.execPath,['--check',resolve(root,'desktop',file)],{stdio:'inherit'})
   await cp(resolve(root, 'desktop', file), resolve(shell, file))

+ 42 - 0
scripts/preview-desktop-onboarding.mjs

@@ -0,0 +1,42 @@
+/** Browser preview of the actual desktop HTML/CSS and controller, using fixture
+ * services only. Run: node scripts/preview-desktop-onboarding.mjs */
+import { createServer } from 'node:http'
+import { readFile } from 'node:fs/promises'
+import { resolve, extname } from 'node:path'
+const root = resolve(import.meta.dirname, '..')
+const bridge = `
+const flowReady = import('/desktop/onboarding.mjs').then(({DesktopOnboarding}) => {
+  const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+  const flow = new DesktopOnboarding({
+    remoteServer: () => 'http://192.168.1.10:15300',
+    inspect: async () => { await delay(400); return {authenticated:false,setupRequired:flow.state.mode==='local'}; },
+    prepareLocal: async () => {
+      for (const [stage,message] of [['checking','正在检查运行环境…'],['installing','正在准备服务组件…'],['starting','正在启动并检查服务…']]) {
+        flow.serviceChanged({phase:'starting',stage,message}); await delay(stage==='installing'?3000:1000);
+      }
+      return 'http://127.0.0.1:15300';
+    },
+    authenticate: async ({username,password}) => { await delay(600); if(password==='error')throw new Error('用户名或密码不正确'); return {username}; },
+    activate: async () => {},
+    navigate: async () => { document.querySelector('.intro h1').textContent='设置完成'; document.querySelector('.intro p').textContent='交互预览已完成,正式应用将在这里进入工作区。'; },
+  });
+  flow.open({mode:'remote',serverURL:'http://192.168.1.10:15300'});
+  return flow;
+});
+window.yaoyaoDesktop={status:()=>flowReady.then(f=>f.snapshot()),selectServer:mode=>flowReady.then(f=>f.select(mode)),prepareServer:input=>flowReady.then(f=>f.prepare(input)),login:input=>flowReady.then(f=>f.submit(input)),forceSync:()=>flowReady.then(f=>f.prepare()),logs:async()=>{document.getElementById('install-log').textContent+='\\n交互预览使用模拟服务,无本机安装日志。';}};
+window.addEventListener('DOMContentLoaded',()=>{document.querySelector('.brand>span').textContent='交互预览 · 模拟服务';});
+`
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.png': 'image/png', '.svg': 'image/svg+xml' }
+const server = createServer(async (req, res) => {
+  const path = new URL(req.url, 'http://localhost').pathname
+  if (path === '/preview-bridge.js') { res.setHeader('content-type', 'text/javascript'); res.end(bridge); return }
+  if (path === '/') { res.writeHead(302, { location: '/desktop/boot.html' }); res.end(); return }
+  const allowed = ['boot.html', 'boot.css', 'boot.js', 'boot-icons.svg', 'icon.png', 'onboarding.mjs', 'remote-login.mjs']
+  if (!allowed.some(file => path === '/desktop/' + file)) { res.writeHead(404); res.end(); return }
+  try {
+    let data = await readFile(resolve(root, '.' + path))
+    if (path.endsWith('boot.html')) data = data.toString().replace('<script src="boot.js">', '<script src="/preview-bridge.js"></script><script src="boot.js">')
+    res.setHeader('content-type', types[extname(path)]); res.end(data)
+  } catch { res.writeHead(404); res.end() }
+})
+server.listen(Number(process.env.PORT || 4388), '127.0.0.1', () => console.log(`Desktop onboarding preview: http://127.0.0.1:${server.address().port}`))

+ 1 - 1
src/client/App.vue

@@ -45,7 +45,7 @@ watch(() => theme.resolvedTheme, value => {
 watch(pageTitle, value => { document.title = value }, { immediate: true })
 
 onMounted(() => {
-  if (!agentIdentityFixture) void auth.bootstrap()
+  if (!agentIdentityFixture) void router.isReady().then(() => auth.bootstrap())
 })
 </script>
 

+ 5 - 0
src/client/api/admin.ts

@@ -5,6 +5,7 @@ export interface ManagedUser {
   id: string
   username: string
   role: 'admin' | 'user'
+  registrationStatus?: 'pending' | 'approved'
   assignedProfiles?: string[]
   enabled: boolean
   mustChangePassword: boolean
@@ -88,3 +89,7 @@ export function getOpenVikingSettings(): Promise<OpenVikingSettings> {
 export function saveOpenVikingSettings(input: Omit<OpenVikingSettings, 'keyConfigured' | 'source' | 'status' | 'error'> & { adminKey?: string }): Promise<OpenVikingSettings> {
   return apiRequest('/api/app/admin/openviking', { method: 'PUT', body: input as unknown as JsonValue })
 }
+
+export function approveUser(id: string, assignedProfiles: string[]): Promise<ManagedUser> {
+  return apiRequest(`/api/app/admin/users/${encodeURIComponent(id)}/approve`, { method: 'POST', body: { assignedProfiles } })
+}

+ 6 - 0
src/client/api/auth.ts

@@ -14,6 +14,7 @@ function normalizeBootstrap(payload: unknown): BootstrapResponse {
   const response: BootstrapResponse = {
     status: string(status.state ?? root.state) || undefined,
     authRequired,
+    registrationAvailable: bool(root.registrationAvailable),
     setupRequired: bool(root.setupRequired ?? root.setup_required),
     profiles,
     csrfToken,
@@ -94,3 +95,8 @@ export async function updateAccountAvatar(avatar: string | null): Promise<Curren
   })))
   return normalizeUser(payload.user ?? payload)
 }
+
+export async function register(input: LoginInput): Promise<void> {
+  await bootstrap()
+  await apiRequest('/api/app/register', { method: 'POST', body: { username: input.username, password: input.password }, notifyUnauthorized: false })
+}

+ 3 - 3
src/client/components/app/DesktopModePanel.vue

@@ -28,15 +28,15 @@ async function switchMode() {
   try {
     const result = await desktop!.switchMode!(selected.value)
     if (!result.ok) throw new Error(result.error || '切换运行模式未完成,请重试。')
-    if (result.pendingLogin) notice.value = '请在弹出的窗口中登录服务器。'
+    if (result.pendingLogin) notice.value = '请在当前页面完成服务器连接与登录。'
     else await load()
   } catch (e) { error.value = e instanceof Error ? e.message : '切换运行模式未完成,请重试。' }
   finally { busy.value = false }
 }
 async function changeServer() {
   busy.value = true; error.value = ''; notice.value = ''
-  try { await desktop!.openRemoteLogin!(); notice.value = '请在弹出的窗口中填写服务器地址并登录。' }
-  catch (e) { error.value = e instanceof Error ? e.message : '无法打开服务器登录窗口。' }
+  try { await desktop!.openRemoteLogin!() }
+  catch (e) { error.value = e instanceof Error ? e.message : '无法打开服务器登录页面。' }
   finally { busy.value = false }
 }
 onMounted(load)

+ 9 - 3
src/client/components/app/SystemManagementPanel.vue

@@ -7,6 +7,7 @@ import AppIcon from '@/components/common/AppIcon.vue'
 import DesktopHostSettingsPanel from './DesktopHostSettingsPanel.vue'
 import RunnerSettingsPanel from './RunnerSettingsPanel.vue'
 import {
+  approveUser,
   createUser,
   deleteUser,
   getAllowedHostsSettings,
@@ -310,6 +311,10 @@ function saveAssignments(user: ManagedUser) {
   void run(async () => { await updateUser(user.id, { assignedProfiles: userAssignments.value[user.id] ?? [] }) })
 }
 
+function approve(user: ManagedUser) {
+  void run(async () => { await approveUser(user.id, userAssignments.value[user.id] ?? []) })
+}
+
 function toggle(user: ManagedUser) {
   void run(async () => { await updateUser(user.id, { enabled: !user.enabled }) })
 }
@@ -471,7 +476,7 @@ watch(() => [props.active, props.section] as const, ([active, section]) => {
       <div v-for="user in users" :key="user.id" class="user">
         <span>
           <b>{{ user.username }}</b>
-          <small>{{ user.role === 'admin' ? '管理员' : user.enabled ? (user.mustChangePassword ? '等待修改临时密码' : '普通用户') : '已禁用' }}</small>
+          <small>{{ user.role === 'admin' ? '管理员' : user.registrationStatus === 'pending' ? '待管理员开通' : user.enabled ? (user.mustChangePassword ? '等待修改临时密码' : '普通用户') : '已禁用' }}</small>
         </span>
         <template v-if="user.role !== 'admin'">
           <label class="user-assignment">基础机器人
@@ -479,9 +484,10 @@ watch(() => [props.active, props.section] as const, ([active, section]) => {
               <option v-for="profile in profiles" :key="profile.name" :value="profile.name">{{ profile.agentName || profile.displayName || profile.name }}</option>
             </select>
           </label>
-          <button type="button" :disabled="busy" @click="saveAssignments(user)">保存分配</button>
+          <button v-if="user.registrationStatus !== 'pending'" type="button" :disabled="busy" @click="saveAssignments(user)">保存分配</button>
           <button type="button" :aria-label="`为用户 ${user.username} 重置密码`" :disabled="busy" @click="reset(user)">重置密码</button>
-          <button type="button" :aria-label="`${user.enabled ? '禁用' : '启用'}用户 ${user.username}`" :disabled="busy" @click="toggle(user)">{{ user.enabled ? '禁用' : '启用' }}</button>
+          <button v-if="user.registrationStatus === 'pending'" type="button" :disabled="busy || !userAssignments[user.id]?.length" @click="approve(user)">分配并开通</button>
+          <button v-else type="button" :aria-label="`${user.enabled ? '禁用' : '启用'}用户 ${user.username}`" :disabled="busy" @click="toggle(user)">{{ user.enabled ? '禁用' : '启用' }}</button>
           <button class="danger" type="button" :aria-label="`删除用户 ${user.username}`" :disabled="busy" @click="remove(user)">删除</button>
         </template>
       </div>

+ 1 - 0
src/client/env.d.ts

@@ -11,6 +11,7 @@ interface ImportMeta {
 
 interface Window {
   yaoyaoDesktop?: {
+    openLogin?(): Promise<unknown>
     openUpdates?(): Promise<void>
     modeState?(): Promise<{ mode: 'client' | 'server'; serverURL: string; switching: boolean }>
     switchMode?(mode: 'client' | 'server'): Promise<{ ok: boolean; error?: string; pendingLogin?: boolean }>

+ 5 - 1
src/client/stores/auth.ts

@@ -21,6 +21,7 @@ export const useAuthStore = defineStore('auth', () => {
   const error = ref<string>()
   const authRequired = ref(true)
   const setupRequired = ref(false)
+  const registrationAvailable = ref(false)
   const insecureLan = ref(false)
   const groupUploadsEnabled = ref(false)
   const upstreamReady = ref(false)
@@ -54,6 +55,7 @@ export const useAuthStore = defineStore('auth', () => {
     if (response.serverIdentity) acceptServerIdentity(response.serverIdentity)
     authRequired.value = response.authRequired
     setupRequired.value = Boolean(response.setupRequired)
+    registrationAvailable.value = response.registrationAvailable === true
     csrfToken.value = response.csrfToken
     insecureLan.value = Boolean(response.insecureLan)
     groupUploadsEnabled.value = Boolean(response.groupUploadsEnabled)
@@ -150,6 +152,7 @@ export const useAuthStore = defineStore('auth', () => {
   }
 
   async function refreshProfiles(): Promise<void> {
+    if (isBotOnly.value) return
     const nextProfiles = await authApi.fetchProfiles()
     profiles.value = nextProfiles
     if (!nextProfiles.some(profile => profile.name === activeProfileName.value)) {
@@ -158,6 +161,7 @@ export const useAuthStore = defineStore('auth', () => {
   }
 
   async function refreshProfileAvatars(): Promise<void> {
+    if (isBotOnly.value) return
     const identities = await authApi.fetchProfileIdentities(profiles.value)
     profiles.value = profiles.value.map(profile => ({
       ...profile,
@@ -178,7 +182,7 @@ export const useAuthStore = defineStore('auth', () => {
 
   return {
     serverIdentity, acceptServerIdentity, refreshServerIdentity,
-    status, user, profiles, activeProfileName, activeProfile, csrfToken, error, authRequired, setupRequired, insecureLan, groupUploadsEnabled,
+    registrationAvailable, status, user, profiles, activeProfileName, activeProfile, csrfToken, error, authRequired, setupRequired, insecureLan, groupUploadsEnabled,
     upstreamReady, upstreamError, isAuthenticated, isBotOnly, bootstrap, login, setup, logout, selectProfile, refreshProfiles, refreshProfileAvatars,
     changeCredentials, updateAccountAvatar, expire,
   }

+ 25 - 2
src/client/views/ConversationsView.vue

@@ -521,6 +521,7 @@ async function hydrateWorkspace() {
 function connectEvents() {
   eventSource?.close()
   if (disposed) return
+  if (!navigator.onLine) { suspendEvents(); return }
   const source = new EventSource(`/api/app/events/stream?after=${cursor}${patchEvents ? '&format=patch-v1' : ''}`)
   eventSource = source
   source.addEventListener('workspace', event => {
@@ -540,11 +541,23 @@ function connectEvents() {
     if (disposed || eventSource !== source) return
     error.value = '连接中断,正在重连'
     void apiRequest('/api/app/capabilities').catch(cause => {
-      if (cause instanceof ApiError && cause.status === 401) source.close()
+      if (cause instanceof ApiError && [401, 403].includes(cause.status)) {
+        source.close()
+        error.value = cause.message
+      }
     })
   }
 }
+function suspendEvents() {
+  eventSource?.close(); eventSource = undefined
+  if (timer) clearTimeout(timer)
+  error.value = '网络已断开,恢复连接后将自动同步'
+}
+function resumeEvents() {
+  if (!disposed && auth.user?.id) void recoverEvents()
+}
 async function recoverEvents() {
+  if (!navigator.onLine) { suspendEvents(); return }
   eventSource?.close(); eventSource = undefined; eventQueue = []
   if (eventFrame !== undefined) cancelAnimationFrame(eventFrame)
   eventFrame = undefined
@@ -559,7 +572,9 @@ async function recoverEvents() {
   }
   catch (cause) {
     if (disposed) return
+    if (!navigator.onLine) { suspendEvents(); return }
     error.value = cause instanceof Error ? cause.message : '连接中断'
+    if (cause instanceof ApiError && [401, 403].includes(cause.status)) return
     timer = setTimeout(() => void recoverEvents(), 1500)
   }
 }
@@ -603,7 +618,8 @@ async function openDialog(kind: NonNullable<typeof dialog.value>, conversation =
   })
   try {
     if (kind === 'agent' || kind === 'editAgent') {
-      const s = await apiRequest<{ sources: Source[] }>('/api/app/agents/sources')
+      const s = await apiRequest<{ sources: Source[]; errors?: string[] }>('/api/app/agents/sources')
+      if (!s.sources.length && s.errors?.length) throw new Error('基础机器人服务暂不可用,请联系管理员检查 Hermes 连接后重试。')
       sources.value = s.sources
       form.source = s.sources[0] ? JSON.stringify([s.sources[0].nodeId, s.sources[0].profile]) : ''
     }
@@ -913,6 +929,9 @@ watch(() => auth.user?.id, (owner, previous) => {
   knowledgePanel.value?.close(); knowledgeEnabled.value = false; projects.value = []; knowledgeRevision.value++
   accountEpoch++; busy.value = false
   generation++
+  if (timer) clearTimeout(timer)
+  text.value = ''; files.value = []; mentions.value = []; quoted.value = null
+  pendingRequestId = undefined; pendingFingerprint = ''; uploadedSources = []; uploadedReferences = []
   eventSource?.close(); eventSource = undefined; eventQueue = []
   if (eventFrame !== undefined) cancelAnimationFrame(eventFrame)
   eventFrame = undefined; cursor = 0
@@ -924,6 +943,8 @@ watch(() => auth.user?.id, (owner, previous) => {
   if (owner) void recoverEvents()
 })
 onMounted(async () => {
+  window.addEventListener('offline', suspendEvents)
+  window.addEventListener('online', resumeEvents)
   void auth.refreshProfileAvatars().catch(() => undefined)
   try {
     await hydrateWorkspace()
@@ -934,6 +955,8 @@ onMounted(async () => {
   }
 })
 onBeforeUnmount(() => {
+  window.removeEventListener('offline', suspendEvents)
+  window.removeEventListener('online', resumeEvents)
   for (const timer of sendRefreshes.values()) clearTimeout(timer)
   sendRefreshes.clear()
   disposed = true

+ 36 - 10
src/client/views/LoginView.vue

@@ -1,7 +1,8 @@
 <script setup lang="ts">
-import { computed, nextTick, ref } from 'vue'
+import { computed, nextTick, onMounted, ref } from 'vue'
 import BrandMark from '@/components/common/BrandMark.vue'
 import AppIcon from '@/components/common/AppIcon.vue'
+import { register } from '@/api/auth'
 import { useAuthStore } from '@/stores/auth'
 import { useThemeStore } from '@/stores/theme'
 
@@ -11,25 +12,46 @@ const username = ref('')
 const password = ref('')
 const passwordConfirmation = ref('')
 const localError = ref('')
-const submitting = computed(() => auth.status === 'authenticating')
+const registering = ref(false)
+const registrationBusy = ref(false)
+const notice = ref('')
+const submitting = computed(() => auth.status === 'authenticating' || registrationBusy.value)
+const needsConfirmation = computed(() => auth.setupRequired || registering.value)
+function toggleRegistration() {
+  registering.value = !registering.value
+  password.value = ''; passwordConfirmation.value = ''; localError.value = ''; notice.value = ''; auth.error = undefined
+}
+
+
+onMounted(() => {
+  if (window.yaoyaoDesktop?.openLogin) {
+    void window.yaoyaoDesktop.openLogin().catch(() => { localError.value = '无法打开服务器登录页面,请重新打开应用。' })
+  }
+})
 
 async function login() {
   if (!username.value.trim() || !password.value) return
-  if (auth.setupRequired && password.value !== passwordConfirmation.value) {
+  if (needsConfirmation.value && password.value !== passwordConfirmation.value) {
     localError.value = '两次输入的密码不一致'
     return
   }
   localError.value = ''
   try {
     const input = { username: username.value.trim(), password: password.value }
-    if (auth.setupRequired) await auth.setup(input)
+    if (registering.value) {
+      registrationBusy.value = true
+      await register(input)
+      registering.value = false
+      password.value = ''; passwordConfirmation.value = ''
+      notice.value = '注册成功,请等待管理员开通。开通后使用此账号登录。'
+    } else if (auth.setupRequired) await auth.setup(input)
     else await auth.login(input)
   } catch (error) {
     localError.value = error instanceof Error ? error.message : '登录失败,请检查账号和密码'
     password.value = ''
     await nextTick()
     document.querySelector<HTMLInputElement>('#password')?.focus()
-  }
+  } finally { registrationBusy.value = false }
 }
 </script>
 
@@ -42,23 +64,27 @@ async function login() {
     <section class="login-panel" aria-labelledby="login-title">
       <BrandMark :size="72" />
       <div class="login-copy">
-        <h1 id="login-title">{{ auth.setupRequired ? '创建管理员' : '登录夭夭' }}</h1>
+        <h1 id="login-title">{{ auth.setupRequired ? '创建管理员' : registering ? '注册子账号' : '登录夭夭' }}</h1>
         <p v-if="auth.setupRequired">首次启动请设置 15300 管理账号,不会创建固定默认密码。</p>
       </div>
+      <p v-if="notice" role="status" class="registration-note">{{ notice }}</p>
+      <p v-if="registering" class="registration-note">子账号仅可使用 Bot 模式,注册后需要本服务器管理员分配机器人并开通。</p>
       <form @submit.prevent="login">
         <label><span>账号</span><input v-model="username" name="username" autocomplete="username" autofocus required placeholder="用户名" /></label>
-        <label><span>密码</span><input id="password" v-model="password" name="password" type="password" autocomplete="current-password" required placeholder="密码" /></label>
-        <label v-if="auth.setupRequired"><span>确认密码</span><input v-model="passwordConfirmation" name="password-confirmation" type="password" autocomplete="new-password" minlength="8" required placeholder="再次输入密码" /></label>
+        <label><span>密码</span><input id="password" v-model="password" name="password" type="password" :autocomplete="needsConfirmation ? 'new-password' : 'current-password'" required placeholder="密码" /></label>
+        <label v-if="needsConfirmation"><span>确认密码</span><input v-model="passwordConfirmation" name="password-confirmation" type="password" autocomplete="new-password" minlength="8" required placeholder="再次输入密码" /></label>
         <p v-if="localError || auth.error" class="login-error" role="alert"><AppIcon name="alert" :size="14" />{{ localError || auth.error }}</p>
-        <button class="login-submit solid-button" type="submit" :disabled="submitting || !username.trim() || password.length < (auth.setupRequired ? 8 : 1) || (auth.setupRequired && password !== passwordConfirmation)">
-          <span>{{ submitting ? '正在提交…' : auth.setupRequired ? '创建并登录' : '登录' }}</span><AppIcon v-if="!submitting" name="arrow-up" :size="15" />
+        <button class="login-submit solid-button" type="submit" :disabled="submitting || !username.trim() || password.length < (needsConfirmation ? 8 : 1) || (needsConfirmation && password !== passwordConfirmation)">
+          <span>{{ submitting ? '正在提交…' : auth.setupRequired ? '创建并登录' : registering ? '注册子账号' : '登录' }}</span><AppIcon v-if="!submitting" name="arrow-up" :size="15" />
         </button>
       </form>
+      <button v-if="!auth.setupRequired" class="registration-link" type="button" :disabled="submitting" @click="auth.registrationAvailable ? toggleRegistration() : localError = '当前服务器尚不支持子账号注册,请联系管理员升级。'">{{ registering ? '已有账号?返回登录' : '没有账号?注册子账号' }}</button>
     </section>
   </main>
 </template>
 
 <style scoped>
+.registration-link{width:100%;min-height:44px;margin-top:12px;border:0;background:transparent;color:var(--text-secondary);cursor:pointer}.registration-link:focus-visible{outline:2px solid var(--accent)}.registration-note{font-size:13px;line-height:1.6;color:var(--text-secondary);margin:12px 0}
 .login-view { position: relative; display: grid; width: 100%; height: 100%; place-items: center; overflow: hidden; padding: 24px; background: var(--canvas); }
 .theme-button { position: absolute; z-index: 3; top: max(15px, env(safe-area-inset-top)); right: 16px; }
 .login-atmosphere { position: absolute; inset: 0; pointer-events: none; opacity: .75; }.login-atmosphere i { position: absolute; display: block; border: 1px solid var(--line); border-radius: 50%; }.login-atmosphere i:nth-child(1) { width: 520px; height: 520px; top: -360px; left: -180px; }.login-atmosphere i:nth-child(2) { width: 310px; height: 310px; right: -190px; bottom: -170px; }.login-atmosphere i:nth-child(3) { width: 3px; height: 3px; top: 22%; right: 18%; border: 0; background: var(--text-muted); box-shadow: -80px 160px 0 var(--line-strong), 90px 270px 0 var(--line-strong), -900px 340px 0 var(--line-strong); }

+ 3 - 1
src/server/app.ts

@@ -1,3 +1,4 @@
+import { isWorkspaceAccountPath } from './subaccountAccess.js'
 import { chatTranscriptRouter } from './chatTranscriptApi.js'
 import {DesktopEnvironments} from './desktopEnvironments.js'
 import {DesktopHostHub} from './desktopHosts.js'
@@ -403,7 +404,7 @@ export function createApplication(options: ApplicationOptions = {}): Application
         && path !== '/api/app/agents/remote'
       const pushPath = /^\/api\/(?:app\/)?push\/v1\//.test(path)
       const identityRead = path === '/api/app/server-identity' && ['GET', 'HEAD'].includes(ctx.method)
-      if (!publicPath && !accountPath && !workspacePath && !pushPath && !identityRead)
+      if (!publicPath && !accountPath && !workspacePath && !isWorkspaceAccountPath(ctx.method, path) && !pushPath && !identityRead)
         throw new HttpError(403, '子账号只能使用 Bot 模式', 'bot_mode_required')
     }
     await next()
@@ -428,6 +429,7 @@ export function createApplication(options: ApplicationOptions = {}): Application
     const anonymous = ctx.path === '/api/app/bootstrap'
       || ctx.path === '/api/app/setup'
       || ctx.path === '/api/app/login'
+      || ctx.path === '/api/app/register'
       || ctx.path === '/api/status'
       || ctx.path === '/api/auth/providers'
       || ctx.path === '/auth/password-login'

+ 37 - 4
src/server/localAuth.ts

@@ -28,8 +28,10 @@ const SESSION_TTL_SECONDS = 60 * 60 * 24 * 30
 const USERNAME_PATTERN = /^[^\u0000-\u001f\u007f\s/@\\]{1,100}$/u
 
 export type LocalRole = 'admin' | 'user'
+export type RegistrationStatus = 'pending' | 'approved'
 
 interface StoredUser {
+  registrationStatus?: RegistrationStatus
   id: string
   username: string
   avatar?: string
@@ -55,6 +57,7 @@ interface SessionRecord {
 interface StoredSessions { version: 1; sessions: Array<SessionRecord & { tokenHash: string }> }
 
 export interface LocalUser {
+  registrationStatus?: RegistrationStatus
   id: string
   username: string
   avatar?: string
@@ -95,6 +98,7 @@ function publicUser(user: StoredUser): LocalUser {
     username: user.username,
     ...(validAvatarImage(user.avatar) ? { avatar: user.avatar } : {}),
     role: user.role,
+    registrationStatus: user.registrationStatus ?? 'approved',
     assignedProfiles: [...(user.assignedProfiles ?? [])],
     enabled: user.enabled,
     mustChangePassword: user.mustChangePassword,
@@ -151,15 +155,17 @@ export class LocalAuthStore {
   login(ctx: Koa.Context, usernameValue: string, password: string): LocalUser {
     const normalized = usernameValue.trim().toLocaleLowerCase('en-US')
     const user = this.#users.find(candidate => candidate.normalizedUsername === normalized)
-    if (!user || !user.enabled || !this.#passwordMatches(user, password)) {
+    if (!user || !this.#passwordMatches(user, password)) {
       throw new HttpError(401, '用户名或密码错误', 'login_failed')
     }
+    if (user.registrationStatus === 'pending') throw new HttpError(403, '账号尚未开通,请等待管理员分配机器人并开通。', 'account_pending_approval')
+    if (!user.enabled) throw new HttpError(401, '用户名或密码错误', 'login_failed')
     return this.#issueSession(ctx, user)
   }
 
   issueSession(ctx: Koa.Context, userID: string): LocalUser {
     const user = this.#users.find(candidate => candidate.id === userID)
-    if (!user || !user.enabled) {
+    if (!user || !user.enabled || user.registrationStatus === 'pending') {
       throw new HttpError(401, '用户已失效', 'account_pairing_user_unavailable')
     }
     return this.#issueSession(ctx, user)
@@ -212,7 +218,7 @@ export class LocalAuthStore {
       return undefined
     }
     const user = this.#users.find(candidate => candidate.id === session.userID)
-    if (!user || !user.enabled || user.authVersion !== session.authVersion) {
+    if (!user || !user.enabled || user.registrationStatus === 'pending' || user.authVersion !== session.authVersion) {
       this.#sessions.delete(key)
       this.#saveSessions()
       return undefined
@@ -243,7 +249,7 @@ export class LocalAuthStore {
   }
 
   canUseSource(userID: string, nodeId: string, profile: string): boolean {
-    const user = this.#users.find(candidate => candidate.id === userID && candidate.enabled)
+    const user = this.#users.find(candidate => candidate.id === userID && candidate.enabled && candidate.registrationStatus !== 'pending')
     return Boolean(user && (user.role === 'admin' || (nodeId === 'local' && user.assignedProfiles?.includes(profile))))
   }
 
@@ -279,11 +285,38 @@ export class LocalAuthStore {
     return publicUser(user)
   }
 
+  register(usernameValue: string, passwordValue: string): void {
+    if (this.setupRequired) throw new HttpError(409, '服务器尚未初始化,请联系管理员。', 'registration_unavailable')
+    const username = canonicalUsername(usernameValue)
+    if (this.#users.some(user => user.normalizedUsername === username.toLocaleLowerCase('en-US'))) {
+      throw new HttpError(409, '用户名已存在', 'username_exists')
+    }
+    const user = this.#newUser(username, validatePassword(passwordValue), 'user', false, Date.now())
+    user.registrationStatus = 'pending'
+    user.enabled = false
+    user.assignedProfiles = []
+    this.#users.push(user)
+    this.#saveUsers()
+  }
+
+  approve(admin: LocalUser, userID: string, profiles: string[]): LocalUser {
+    if (admin.role !== 'admin') throw new HttpError(403, '需要管理员权限', 'admin_required')
+    const user = this.#users.find(candidate => candidate.id === userID)
+    if (!user) throw new HttpError(404, '用户不存在', 'user_not_found')
+    if (user.role !== 'user' || user.registrationStatus !== 'pending') throw new HttpError(409, '该账号不在待开通状态,请刷新列表。', 'approval_not_pending')
+    const assigned = this.validateAssignedProfiles(profiles)
+    if (!assigned.length) throw new HttpError(400, '开通时必须分配至少一个基础机器人', 'assignment_required')
+    Object.assign(user, { assignedProfiles: assigned, registrationStatus: 'approved', enabled: true, updatedAt: Date.now(), authVersion: user.authVersion + 1 })
+    this.#saveUsers()
+    return publicUser(user)
+  }
+
   updateUser(admin: LocalUser, userID: string, input: { enabled?: boolean; password?: string; assignedProfiles?: unknown }): LocalUser {
     if (admin.role !== 'admin') throw new HttpError(403, '需要管理员权限', 'admin_required')
     const user = this.#users.find(candidate => candidate.id === userID)
     if (!user) throw new HttpError(404, '用户不存在', 'user_not_found')
     if (user.role === 'admin') throw new HttpError(409, '管理员账号请在账号设置中修改', 'admin_account_protected')
+    if (user.registrationStatus === 'pending' && input.enabled === true) throw new HttpError(409, '请使用“分配并开通”审核此账号', 'approval_required')
     const assigned = input.assignedProfiles === undefined ? undefined : this.validateAssignedProfiles(input.assignedProfiles)
     if (input.password !== undefined) validatePassword(input.password)
     if (assigned !== undefined) user.assignedProfiles = assigned

+ 30 - 0
src/server/routes.ts

@@ -1,3 +1,4 @@
+import { RegistrationLimiter } from './subaccountAccess.js'
 import { readServerIdentity, updateServerIdentity } from './serverIdentity.js'
 import { authorizeFileRead, fileAccessWorkingDirectory, readFileAccess, saveFileAccess } from './fileAccess.js'
 import { readHostTools, saveHostTools } from './hostToolSettings.js'
@@ -809,6 +810,7 @@ async function bootstrap(
       authRequired: true,
       authenticated: false,
       setupRequired: dependencies.auth.setupRequired,
+      registrationAvailable: !dependencies.auth.setupRequired,
       profiles: [],
       csrfToken,
       insecureLan: dependencies.config.insecureLan,
@@ -856,6 +858,7 @@ async function bootstrap(
     status,
     authRequired: true,
     authenticated: true,
+    registrationAvailable: true,
     serverIdentity: readServerIdentity(dependencies.workspace),
     user,
     profiles,
@@ -1152,6 +1155,7 @@ function pairedLocalMediaPath(config: ServerConfig, rawPath: string): string {
 
 export function createApiRouter(dependencies: RouteDependencies): Router {
   const router = new Router()
+  const registrations = new RegistrationLimiter()
   const fileReadRequest = (ctx: Koa.Context, path: string) => ['GET', 'HEAD'].includes(ctx.method)
     && /^\/api\/(?:files(?:\/[^/]+)?|fs\/[^/]+|media|hermes\/download)$/.test(path)
   const authorizeFileQuery = async (ctx: Koa.Context, route: string, host: Pick<UpstreamServiceSession, 'request'> = dependencies.upstreamSession) => {
@@ -1709,6 +1713,18 @@ export function createApiRouter(dependencies: RouteDependencies): Router {
   router.post('/api/app/login', async (ctx) => {
     await login(ctx, dependencies)
   })
+  router.post('/api/app/register', ctx => {
+    const retry = registrations.take(ctx.req.socket.remoteAddress ?? 'unknown')
+    if (retry) {
+      ctx.set('Retry-After', String(retry))
+      throw new HttpError(429, '注册请求过于频繁,请稍后重试。', 'registration_rate_limited')
+    }
+    const request = body(ctx)
+    if (Object.keys(request).some(key => !['username', 'password'].includes(key)) || typeof request.username !== 'string' || typeof request.password !== 'string')
+      throw new HttpError(400, '请填写用户名和密码', 'invalid_registration')
+    dependencies.auth.register(request.username, request.password)
+    json(ctx, 201, { registrationStatus: 'pending', message: '注册成功,请等待管理员开通。' })
+  })
   router.post('/api/app/logout', async (ctx) => {
     dependencies.auth.logout(ctx)
     json(ctx, 200, { ok: true, csrfToken: dependencies.csrf.issue(ctx, true) })
@@ -1737,6 +1753,20 @@ export function createApiRouter(dependencies: RouteDependencies): Router {
     const password = typeof request.password === 'string' ? request.password : ''
     json(ctx, 201, dependencies.auth.create(admin, username, password, request.assignedProfiles))
   })
+  router.post('/api/app/admin/users/:userID/approve', async ctx => {
+    dependencies.auth.requireAdmin(ctx)
+    const userID = canonicalUUID(ctx.params.userID, 'user ID'), request = body(ctx)
+    if (Object.keys(request).some(key => key !== 'assignedProfiles')) throw new HttpError(400, '开通参数无效', 'invalid_approval')
+    const profiles = dependencies.auth.validateAssignedProfiles(request.assignedProfiles)
+    if (!profiles.length) throw new HttpError(400, '开通时必须分配至少一个基础机器人', 'assignment_required')
+    const response = await dependencies.upstreamSession.request('/api/profiles', { cache: 'reload' })
+    const available = new Set(normalizedProfiles(requireSuccess(response)).map(value => typeof value === 'string' ? value : (value as JsonObject).name))
+    if (profiles.some(profile => !available.has(profile))) throw new HttpError(409, '所选基础机器人当前不可用,请刷新后重新选择。', 'source_unavailable')
+    // Revalidate the administrator after the asynchronous catalogue lookup.
+    delete ctx.state.localUser
+    const admin = dependencies.auth.requireAdmin(ctx)
+    json(ctx, 200, dependencies.auth.approve(admin, userID, profiles))
+  })
   router.patch('/api/app/admin/users/:userID', async (ctx) => {
     const admin = dependencies.auth.requireAdmin(ctx)
     const request = body(ctx)

+ 23 - 0
src/server/subaccountAccess.ts

@@ -0,0 +1,23 @@
+/** Owner-scoped Bot endpoints. Keep native and administrative surfaces denied. */
+export function isWorkspaceAccountPath(method: string, path: string): boolean {
+  const read = method === 'GET' || method === 'HEAD'
+  if (read && /^\/api\/app\/workspace\/(snapshot|projects|memories|memory-export|memory-jobs|collaboration)$/.test(path)) return true
+  if (read && /^\/api\/app\/workspace\/memories\/[^/]+\/revisions$/.test(path)) return true
+  return method === 'POST' && /^\/api\/app\/workspace\/(projects|memories|memories\/forget|memory-jobs\/[^/]+\/retry|collaboration\/[^/]+\/stop)$/.test(path)
+}
+
+/** Bound memory as well as request frequency; untrusted forwarded IPs are not used. */
+export class RegistrationLimiter {
+  private readonly attempts = new Map<string, { count: number; expires: number }>()
+  take(address: string, now = Date.now()): number {
+    for (const [key, value] of this.attempts) if (value.expires <= now) this.attempts.delete(key)
+    let entry = this.attempts.get(address)
+    if (!entry) {
+      if (this.attempts.size >= 10_000) return 60
+      entry = { count: 0, expires: now + 15 * 60_000 }
+      this.attempts.set(address, entry)
+    }
+    if (++entry.count > 10) return Math.ceil((entry.expires - now) / 1000)
+    return 0
+  }
+}

+ 1 - 2
src/server/workspaceRoutes.ts

@@ -83,8 +83,7 @@ export function workspaceRouter(
         'agentTeamManagement',
         'computerControl','sharedComputers','computerManagement',
         'files',
-        'voice',
-        'context',
+        ...(auth.require(ctx).role === 'admin' ? ['voice', 'context'] : []),
         ...(auth.require(ctx).role === 'admin' ? ['nodes', 'pairedNodes', 'editableNodeAddress'] : []),
         'events', 'workspace-stream-v1',
         ...(store.messagePatchesEnabled ? [WORKSPACE_PATCH_CAPABILITY] : []),

+ 1 - 0
src/shared/types.ts

@@ -47,6 +47,7 @@ export interface BootstrapResponse {
   serverIdentity?: import('./serverIdentity.js').ServerIdentity
   status?: string
   authRequired: boolean
+  registrationAvailable?: boolean
   setupRequired?: boolean
   user?: CurrentUser
   profiles: Profile[]

+ 2 - 1
tests/client/settingsCenterDialog.test.ts

@@ -126,7 +126,8 @@ describe('Settings center dialog', () => {
     await wrapper.findAll('.mode-actions button').find(button => button.text() === '更换服务器…')!.trigger('click')
     await flushPromises()
     expect(openRemoteLogin).toHaveBeenCalledOnce()
-    expect(wrapper.get('[role="status"]').text()).toContain('服务器地址并登录')
+    expect(wrapper.text()).not.toContain('弹出的窗口')
+    expect(wrapper.find('[role="alert"]').exists()).toBe(false)
     wrapper.unmount()
   })
   it.each(['agent-identity', 'agent-models'])('keeps %s and the Profile selector out of Bot-mode personal settings', initialPage => {

+ 61 - 0
tests/e2e/workspace-chat.spec.ts

@@ -777,3 +777,64 @@ test('account update checks show loading, available versions and retry on deskto
     await expect(account).toBeFocused()
   }
 })
+
+test('self-registered subaccount approval supports Bot replies, reload and isolation', async ({ page, browser }, testInfo) => {
+  const childContext = await browser.newContext({ viewport: { width: 1280, height: 800 } })
+  const child = await childContext.newPage()
+  const username = `registered-${Date.now()}`
+  const denied: string[] = []
+  child.on('response', response => { if (response.status() === 403 && response.url().includes('/api/app/')) denied.push(new URL(response.url()).pathname) })
+  try {
+    await child.goto('/conversations')
+    await child.getByRole('button', { name: '没有账号?注册子账号' }).click()
+    await child.getByRole('textbox', { name: '账号', exact: true }).fill(username)
+    await child.getByLabel('密码', { exact: true }).fill('child-password')
+    await child.getByLabel('确认密码', { exact: true }).fill('child-password')
+    await child.getByRole('button', { name: '注册子账号', exact: true }).click()
+    await expect(child.getByRole('status')).toContainText('注册成功')
+    await child.getByLabel('密码', { exact: true }).fill('child-password')
+    await child.getByRole('button', { name: '登录', exact: true }).click()
+    await expect(child.getByRole('alert')).toContainText('尚未开通')
+    await login(page)
+    await page.locator('.desktop-sidebar .sidebar-account-switcher__main').click()
+    await page.getByRole('menuitem', { name: '我的设置', exact: true }).click()
+    const settings = page.getByRole('dialog', { name: '我的设置', exact: true })
+    await settings.getByRole('button', { name: '用户与权限', exact: true }).click()
+    const row = settings.locator('.user').filter({ hasText: username })
+    await expect(row).toContainText('待管理员开通')
+    await expect(row.getByRole('button', { name: '分配并开通' })).toBeDisabled()
+    await row.getByRole('listbox').selectOption('default')
+    await row.getByRole('button', { name: '分配并开通' }).click()
+    await expect(row).toContainText('普通用户')
+    await child.getByLabel('密码', { exact: true }).fill('child-password')
+    await child.getByRole('button', { name: '登录', exact: true }).click()
+    await expect(child.getByRole('heading', { name: '还没有聊天' })).toBeVisible()
+    denied.length = 0
+    await openCreate(child, '新建 Bot')
+    const dialog = child.getByRole('dialog')
+    await expect(dialog.getByLabel('基础机器人').locator('option')).toHaveCount(1)
+    await dialog.getByRole('textbox', { name: '名称', exact: true }).fill('注册验收助手')
+    await dialog.getByRole('button', { name: '保存', exact: true }).click()
+    await expect(child.getByRole('heading', { name: '注册验收助手', exact: true })).toBeVisible()
+    const composer = child.getByRole('textbox', { name: '输入消息,Enter 发送,Shift + Enter 换行' })
+    await composer.fill('注册后验证 Bot 回复')
+    await composer.press('Enter')
+    await expect.poll(async () => {
+      const id = new URL(child.url()).pathname.split('/').at(-1)
+      const response = await child.request.get(`/api/app/conversations/${id}/messages`)
+      const value = await response.json()
+      return value.messages?.some((m: any) => m.role === 'assistant' && m.status === 'complete' && m.content)
+    }).toBe(true)
+    await expect(child.getByText('会话独立保存', { exact: true })).toBeVisible()
+    await childContext.setOffline(true)
+    await expect(child.getByText('网络已断开,恢复连接后将自动同步', { exact: true })).toBeVisible()
+    await childContext.setOffline(false)
+    await expect(child.getByText('网络已断开,恢复连接后将自动同步', { exact: true })).toBeHidden({ timeout: 15_000 })
+    await child.reload()
+    await expect(child.getByRole('heading', { name: '注册验收助手', exact: true })).toBeVisible()
+    await expect(child.getByText('注册后验证 Bot 回复', { exact: true }).first()).toBeVisible()
+    expect((await (await page.request.get('/api/app/agents')).json()).agents.some((a: any) => a.name === '注册验收助手')).toBe(false)
+    expect(denied).toEqual([])
+    await child.screenshot({ path: testInfo.outputPath('registered-subaccount-bot.png'), fullPage: true })
+  } finally { await childContext.close() }
+})

+ 145 - 0
tests/server/subaccountRegistration.test.ts

@@ -0,0 +1,145 @@
+// @vitest-environment node
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { createServer } from 'node:http'
+import { beforeEach, afterEach, describe, expect, it } from 'vitest'
+import request from 'supertest'
+import { createApplication, type ApplicationRuntime } from '../../src/server/app'
+import { loadServerConfig } from '../../src/server/config'
+import { LocalAuthStore } from '../../src/server/localAuth'
+import { RegistrationLimiter } from '../../src/server/subaccountAccess'
+let runtime: ApplicationRuntime, home: string, csrf: string
+let admin: ReturnType<typeof request.agent>, child: ReturnType<typeof request.agent>
+const host = '127.0.0.1:15300'
+const call = (agent: typeof admin, method: 'get'|'post'|'patch'|'head', path: string, token = '') => agent[method](path).set('Host', host).set('Origin', `http://${host}`).set('X-CSRF-Token', token)
+beforeEach(async () => {
+  home = mkdtempSync(join(tmpdir(), 'yaoyao-registration-'))
+  runtime = createApplication({ config: loadServerConfig({ HERMES_YAOYAO_HOME: home, HERMES_YAOYAO_UPSTREAM: 'http://127.0.0.1:1', HERMES_YAOYAO_ALLOWED_HOSTS: '127.0.0.1' }), fetchImpl: (async input => {
+    const path = new URL(String(input)).pathname
+    return Response.json(path === '/api/profiles' ? { profiles: [{ name: 'allowed' }] } : path === '/api/status' ? { auth_required: true } : { user_id: 'service' })
+  }) as typeof fetch })
+  admin = request.agent(runtime.app.callback()); child = request.agent(runtime.app.callback())
+})
+afterEach(() => { runtime.close(); rmSync(home, { recursive: true, force: true }) })
+async function setup() {
+  const boot = await call(admin, 'get', '/api/app/bootstrap')
+  csrf = (await call(admin, 'post', '/api/app/setup', boot.body.csrfToken).send({ username: 'admin', password: 'admin-password' }).expect(200)).body.csrfToken
+}
+async function register(username = 'new-child') {
+  const boot = await call(child, 'get', '/api/app/bootstrap')
+  const result = await call(child, 'post', '/api/app/register', boot.body.csrfToken).send({ username, password: 'child-password' }).expect(201)
+  expect(result.body.registrationStatus).toBe('pending')
+  expect(result.headers['set-cookie']).toBeUndefined()
+  return boot.body.csrfToken as string
+}
+describe('subaccount registration and approval through real middleware', () => {
+  it('keeps initial setup exclusive and validates CSRF, role injection and credentials', async () => {
+    const boot = await call(child, 'get', '/api/app/bootstrap')
+    expect(boot.body.registrationAvailable).toBe(false)
+    await call(child, 'post', '/api/app/register', boot.body.csrfToken).send({ username: 'early', password: 'child-password' }).expect(409)
+    await setup()
+    expect((await call(child, 'get', '/api/app/bootstrap')).body.registrationAvailable).toBe(true)
+    await call(child, 'post', '/api/app/register').send({ username: 'bad', password: 'child-password' }).expect(403)
+    await call(child, 'post', '/api/app/register', boot.body.csrfToken).send({ username: 'bad', password: 'child-password', role: 'admin', enabled: true }).expect(400)
+    await call(child, 'post', '/api/app/register', boot.body.csrfToken).send({ username: 'bad', password: 'short' }).expect(400)
+    await register()
+    await call(child, 'post', '/api/app/register', boot.body.csrfToken).send({ username: 'NEW-CHILD', password: 'child-password' }).expect(409)
+  })
+  it('requires valid assigned profiles to approve; preserves pending status across restart and blocks enable bypass', async () => {
+    await setup(); const token = await register()
+    await call(child, 'post', '/api/app/login', token).send({ username: 'new-child', password: 'wrong' }).expect(401)
+    expect((await call(child, 'post', '/api/app/login', token).send({ username: 'new-child', password: 'child-password' }).expect(403)).body.code).toBe('account_pending_approval')
+    expect((await call(child, 'post', '/auth/password-login').send({ username: 'new-child', password: 'child-password' }).expect(403)).body.code).toBe('account_pending_approval')
+    await call(child, 'get', '/api/app/workspace/snapshot').expect(401)
+    const user = (await call(admin, 'get', '/api/app/admin/users')).body.items.find((u: any) => u.username === 'new-child')
+    expect(user).toMatchObject({ registrationStatus: 'pending', role: 'user', enabled: false, assignedProfiles: [], mustChangePassword: false })
+    expect(new LocalAuthStore(home).isUserActive(user.id)).toBe(false)
+    await call(admin, 'patch', `/api/app/admin/users/${user.id}`, csrf).send({ enabled: true, assignedProfiles: ['allowed'] }).expect(409)
+    await call(admin, 'post', `/api/app/admin/users/${user.id}/approve`, csrf).send({ assignedProfiles: [] }).expect(400)
+    await call(admin, 'post', `/api/app/admin/users/${user.id}/approve`, csrf).send({ assignedProfiles: ['missing'] }).expect(409)
+    await call(child, 'post', `/api/app/admin/users/${user.id}/approve`, token).send({ assignedProfiles: ['allowed'] }).expect(401)
+    const approved = await call(admin, 'post', `/api/app/admin/users/${user.id}/approve`, csrf).send({ assignedProfiles: ['allowed'] }).expect(200)
+    expect(approved.body).toMatchObject({ enabled: true, registrationStatus: 'approved', assignedProfiles: ['allowed'], mustChangePassword: false })
+    await call(admin, 'post', `/api/app/admin/users/${user.id}/approve`, csrf).send({ assignedProfiles: ['allowed'] }).expect(409)
+    const login = await call(child, 'post', '/api/app/login', token).send({ username: 'new-child', password: 'child-password' }).expect(200)
+    const create = await call(child, 'post', '/api/app/agents', login.body.csrfToken).send({ name: '我的 Bot', profile: 'allowed' }).expect(201)
+    const snapshot = (await call(child, 'get', '/api/app/workspace/snapshot').expect(200)).body
+    expect(snapshot.agents.map((a: any) => a.id)).toEqual([create.body.agent.id])
+    expect(snapshot.conversations).toHaveLength(1)
+    expect((await call(admin, 'get', '/api/app/workspace/snapshot')).body.agents).toEqual([])
+    await call(child, 'get', '/api/app/workspace/projects').expect(200)
+    await call(child, 'get', '/api/app/workspace/collaboration').expect(200)
+    await call(child, 'get', '/api/app/workspace/memory-jobs').expect(200)
+    await call(child, 'post', '/api/app/workspace/snapshot', login.body.csrfToken).send({}).expect(403)
+    await call(child, 'get', '/api/app/workspace/admin').expect(403)
+    await call(child, 'get', '/api/app/admin/users').expect(403)
+    await call(admin, 'patch', `/api/app/admin/users/${user.id}`, csrf).send({ enabled: false }).expect(200)
+    await call(child, 'get', '/api/app/workspace/snapshot').expect(401)
+  })
+  it('bounds registration attempts without changing login or administrator creation', async () => {
+    await setup()
+    const token = (await call(child, 'get', '/api/app/bootstrap')).body.csrfToken
+    for (let i = 0; i < 10; i++) await call(child, 'post', '/api/app/register', token).send({}).expect(400)
+    const limited = await call(child, 'post', '/api/app/register', token).send({}).expect(429)
+    expect(Number(limited.headers['retry-after'])).toBeGreaterThan(0)
+    await call(admin, 'post', '/api/app/admin/users', csrf).send({ username: 'managed', password: 'temporary-password' }).expect(201)
+    const login = await call(child, 'post', '/api/app/login', token).send({ username: 'managed', password: 'temporary-password' }).expect(200)
+    expect(login.body.user.mustChangePassword).toBe(true)
+    const limiter = new RegistrationLimiter()
+    for (let i = 0; i < 10; i++) expect(limiter.take('ip', 0)).toBe(0)
+    expect(limiter.take('ip', 1)).toBe(900)
+    expect(limiter.take('ip', 900_000)).toBe(0)
+  })
+  it('authorizes owner-scoped projects, memory, attachments and event replay through the complete middleware', async () => {
+    await setup(); const token = await register()
+    const user = (await call(admin, 'get', '/api/app/admin/users')).body.items.find((u: any) => u.username === 'new-child')
+    await call(admin, 'post', `/api/app/admin/users/${user.id}/approve`, csrf).send({ assignedProfiles: ['allowed'] }).expect(200)
+    const login = await call(child, 'post', '/api/app/login', token).send({ username: 'new-child', password: 'child-password' }).expect(200)
+    const childCSRF = login.body.csrfToken
+    const agent = (await call(child, 'post', '/api/app/agents', childCSRF).send({ name: '知识助手', profile: 'allowed' }).expect(201)).body.agent
+    await call(child, 'head', '/api/app/workspace/snapshot').expect(200)
+    const project = (await call(child, 'post', '/api/app/workspace/projects', childCSRF).send({ requestId: randomUUID(), name: '私人项目', memberIds: [agent.id] }).expect(200)).body.project
+    expect((await call(admin, 'get', '/api/app/workspace/projects')).body.projects).toEqual([])
+    const scope = { scope: 'project', agentId: agent.id, projectId: project.id }
+    const memory = (await call(child, 'post', '/api/app/workspace/memories', childCSRF).send({ ...scope, requestId: randomUUID(), content: '只属于此账号的记忆' }).expect(200)).body.memory
+    const query = new URLSearchParams(scope).toString()
+    expect((await call(child, 'get', `/api/app/workspace/memories?${query}`).expect(200)).body.memories.map((m: any) => m.id)).toContain(memory.id)
+    await call(child, 'get', `/api/app/workspace/memories/${memory.id}/revisions?${query}`).expect(200)
+    expect((await call(child, 'get', `/api/app/workspace/memory-export?${query}`).expect(200)).text).toContain('只属于此账号的记忆')
+    expect((await call(admin, 'get', `/api/app/workspace/memories?${query}`).expect(200)).body.memories).toEqual([])
+    await call(admin, 'get', `/api/app/workspace/memories/${memory.id}/revisions?${query}`).expect(404)
+    await call(child, 'post', '/api/app/workspace/memories/forget', childCSRF).send({ ...scope, id: memory.id, expectedRevision: memory.revision, requestId: randomUUID() }).expect(200)
+    const file = (await call(child, 'post', '/api/app/uploads', childCSRF).attach('files', Buffer.from('子账号附件'), { filename: 'child.txt', contentType: 'text/plain' }).expect(201)).body.files[0]
+    await call(child, 'get', `/api/app/files/${file.id}/download`).expect(200)
+    await call(admin, 'get', `/api/app/files/${file.id}/download`).expect(404)
+    // Unknown resources reach owner-scoped handlers, rather than the Bot-only gate.
+    await call(child, 'post', `/api/app/workspace/memory-jobs/${randomUUID()}/retry`, childCSRF).send({}).expect(404)
+    await call(child, 'post', `/api/app/workspace/collaboration/${randomUUID()}/stop`, childCSRF).send({}).expect(404)
+    const events = await call(child, 'get', '/api/app/events?after=0').expect(200)
+    expect(events.body.events.some((e: any) => e.type === 'project.changed')).toBe(true)
+    const caps = (await call(child, 'get', '/api/app/capabilities')).body.features
+    for (const feature of ['voice', 'context', 'nodes']) expect(caps).not.toContain(feature)
+    expect((await call(admin, 'get', '/api/app/capabilities')).body.features).toEqual(expect.arrayContaining(['voice', 'context', 'nodes']))
+    const server = createServer(runtime.app.callback())
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+    const address = server.address() as { port: number }
+    const cookie = (login.headers['set-cookie'] as unknown as string[]).map(value => value.split(';')[0]).join('; ')
+    const abort = new AbortController()
+    try {
+      const response = await fetch(`http://127.0.0.1:${address.port}/api/app/events/stream?after=${events.body.cursor}`, { headers: { host, cookie }, signal: AbortSignal.any([abort.signal, AbortSignal.timeout(20_000)]) })
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/event-stream')
+      const reader = response.body!.getReader(), decoder = new TextDecoder()
+      let text = ''
+      while (!text.includes('event: ready')) text += decoder.decode((await reader.read()).value)
+      await call(admin, 'patch', `/api/app/admin/users/${user.id}`, csrf).send({ enabled: false }).expect(200)
+      while (!(await reader.read()).done) { /* Revocation closes the old stream no later than its heartbeat. */ }
+      await call(child, 'get', '/api/app/workspace/snapshot').expect(401)
+    } finally {
+      abort.abort(); server.closeAllConnections()
+      await new Promise<void>(resolve => server.close(() => resolve()))
+    }
+  }, 25_000)
+})

برخی فایل ها در این مقایسه diff نمایش داده نمی شوند زیرا تعداد فایل ها بسیار زیاد است