root/geo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9ec9314aea8af9706b787266a367f086aa6ea711
geo/docs/superpowers/specs/2026-04-18-electron-desktop-client-design.md
T
root 9ec9314aea docs(desktop-client): add Electron 桌面客户端 replacement design spec 
Captures the full plan for replacing apps/browser-extension with an
Electron tray client: single main process with multi-session isolation,
embedded web-view login with OS-encrypted local cookie vault, CDP-based
LLM monitoring (no official APIs, cost-driven), unified PublishAdapter
and MonitorAdapter interfaces with dual-track updates (per-adapter patch
channel + full release channel), Playwright-grade tracing, new
/api/desktop/* protocol with SSE + 60s pull, and 5-arch multi-OS
packaging strategy.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-18 20:28:42 +08:00

26 KiB
Raw Blame History

Electron 桌面客户端设计（全面替换 WXT 浏览器插件）

状态：Draft · 待实施 作者：@liangxu + Claude 日期：2026-04-18 范围：新增 apps/desktop-client/、/api/desktop/* 服务端路由、相关 DB schema；删除 apps/browser-extension/ 与 /api/plugin/* 路由及相关代码。

1. 背景与动机

现有 apps/browser-extension/（WXT MV3 Chrome 扩展，"GEO Publisher"）同时承担两类工作：

  1. 向 13 家中国媒体平台做内容分发（微信公众号、头条号、百家号、搜狐号、网易号、ZOL、懂车帝、知乎、企鹅号、简书、掘金、B 站、什么值得买）。
  2. 监控主流 LLM（豆包、千问、DeepSeek）在给定查询下的输出，判定品牌/KOL 是否被引用。

当前问题：

  • LLM 抓取不稳定。监控模块依赖 DOM 选择器与 webRequest.onBeforeRequest 在 MV3 下受限，无法可靠拿到 SSE 响应 Body；平台 UI 一变就挂。
  • 适配器受 MV3 约束。后台 service worker 频繁休眠，长任务难以保证完成；跨平台复杂登录（QR、滑块、SMS）在扩展内体验差。
  • 不可扩展到真正的系统级自动化。系统托盘、开机自启、多账号并发 session 隔离、进程级 CDP 调试，这些 MV3 都做不到。

因此：全面替换为一个 Electron 桌面客户端，承担上述全部职责。浏览器扩展停止维护并下线。

2. 设计硬约束（已确认）

  1. 全面替换，不做"先 monitoring 后 publishing"的分阶段替换。
  2. 不做向后兼容。因为是开发版本阶段，服务端协议、DB schema、认证字段按桌面客户端的最佳形态重新设计，不为插件保留旧字段或旧路由。
  3. 登录走嵌入式 Web View。用户在 Electron 真实平台登录页里自己完成扫码/密码/短信/滑块；我们只保存 cookie，不保存账号密码。
  4. Cookie 本地存储 + OS 级加密（Electron safeStorage，macOS Keychain / Windows DPAPI / Linux libsecret）。服务端永不存储 Cookie 或任何平台凭据。
  5. LLM 监控一律走网页 + CDP 拦截，不调用任何 LLM 官方 API（成本导向；多账号 = 多配额，线性成本比 token 计费友好）。后端 llm.api_key 是后端自用管线，与客户端监控完全解耦。
  6. 不打包 Playwright。复用 Electron 自带 Chromium，通过 webContents.debugger 直接用 CDP。包体越小越好。
  7. 支持 5 目标：Windows x64/arm64、macOS Intel+Apple Silicon、Linux x64/arm64。
  8. 一个微信号只给一个 workspace——不支持跨租户共享账号。

3. 架构总览

3.1 进程拓扑

单 Electron 进程树（方案 A）。

  • Main 进程（Node）：任务调度器、Session 注册表、加密凭据仓库、CDP debugger 管理、与后端 REST/SSE 通信、Tray & autoUpdater。
  • Renderer 进程（托盘窗口 / 发布预览窗口）：Vue UI，复用 apps/admin-web 的组件库与 i18n。禁用 nodeIntegration，通过 contextBridge 暴露窄接口。
  • 工作 BrowserView：每个登录账号一个 persist:<account-id> session + 一个隐藏 BrowserView，挂在离屏 BrowserWindow 上。常驻但不可见；需要操作时 webContents.debugger.attach()。
  • 只有当实测 CDP 流式抓取会让 UI 卡顿时，才把 debugger 交互迁到 utilityProcess，其他模块保持不动。

3.2 模块分层

新增 apps/desktop-client/，作为 pnpm workspace 的新包：

apps/desktop-client/
  main/
    bootstrap.ts          # app ready, single-instance-lock, tray, autoUpdater
    session-registry.ts   # account-id → BrowserView + session
    vault.ts              # safeStorage 包 cookie/token，SQLite 持久化
    scheduler.ts          # 本地 cron + 服务端 task lease 合流
    circuit-breaker.ts    # 平台级熔断
    keep-alive.ts         # 探活 / 保活调度
    crash-recovery.ts     # 启动时扫描 in-flight 任务
    tracing/
      recorder.ts         # 启停；订阅 CDP Page/Network/Fetch/Runtime；采样截屏
      trace-writer.ts     # 流式写入 .trace zip
      redactor.ts         # Cookie / Authorization / password 字段自动脱敏
      viewer-assets/      # 内置 trace viewer（Vue 单页，离线）
    transport/
      api-client.ts       # 复用 packages/http-client，注入 client_token
      sse-client.ts       # /api/desktop/events SSE 长连接 + pull 兜底
    adapters/
      _shared/
        debugger-helper.ts
        dom-helper.ts
        upload-helper.ts
        captcha-pause.ts
        selectors.json    # 可热更的选择器表
      base.ts             # PublishAdapter / MonitorAdapter 接口
      wechat.ts ... smzdm.ts  # 13 个发布适配器
      doubao.ts qwen.ts deepseek.ts  # 3 个 LLM 监控适配器
      index.ts            # 注册表
  preload/
    bridge.ts             # 暴露给 renderer 的受控 API
  renderer/               # 复用 apps/admin-web，打 Electron 专属 build

3.3 关键复用

  • packages/shared-types：平台枚举、任务类型、DTO。
  • packages/http-client：HTTP 基座。
  • apps/admin-web 的 Vue 组件与路由：删掉 SaaS 专属页面后作为 renderer 的基座。
  • apps/browser-extension/src/adapters/* 的选择器和工作流：批量搬进来，套一层 runInSession(accountId, fn) 即可复用。

4. 账号 & 会话模型

4.1 数据结构

type Account = {
  id: string                 // uuid，本地生成
  platform: PlatformKind     // 'wechat' | 'toutiao' | ... | 'doubao' | 'qwen' | 'deepseek'
  purpose: 'publish' | 'monitor'
  displayName: string
  partitionKey: string       // 'persist:acc-<id>'，Electron session 隔离
  createdAt: Date
  lastSeenAt: Date
  health: 'live' | 'expired' | 'captcha' | 'risk'
  tenantId: string
  workspaceId: string
  keepAlive: {
    mode: 'probe-only' | 'heartbeat' | 'disabled'
    probeIntervalMs: number      // 默认 30 min
    heartbeatIntervalMs?: number // 默认 8 min，仅 heartbeat 模式
    lastProbeAt?: Date
    lastHeartbeatAt?: Date
    failureStreak: number
  }
  quota: {
    hourlyBudget: number
    usedThisHour: number
    resetAt: Date
  }
}

4.2 登录流程

  1. 用户在 UI 点「新增账号 → 选平台」。
  2. 主进程 session-registry.create(platform) 分配新 partition，打开一个可见 BrowserWindow（登录专用），加载该平台登录页。
  3. 用户自己用扫码 / 密码 / 短信 / 滑块登录。
  4. 登录探针（preload 脚本 + URL 规则）检测到已登录态后关闭窗口。
  5. Electron 自动把 cookies 持久化到 userData/Partitions/<key>/；同时主进程读取 cookies 用 safeStorage 加密写本地 SQLite 作为元数据 + 加密快照（用于迁机器、备份、健康检查）。
  6. 账号进入"常驻池"，分配隐藏 BrowserView 挂在离屏窗口；按需激活 CDP。

4.3 多账号并存

同一平台多账号完全隔离——partition 不同、cookies 不同、UA 不同、可通过 session 级 proxy 走不同 IP。调度器按账号维度限流（默认同一账号并发 1、同一平台并发 3，可配置）。

4.4 Cookie/Session 保活策略

三个档位：

档位 动作 频率 代价
探活 加载主页，检查 DOM 登录标志 30 min 低
保活 访问平台私有 API 触发 Set-Cookie/token 刷新 8 min（豆包/千问） 中
按需激活 任务到来前 pre-check 任务驱动 低
平台类型 账号示例 保活方式 节奏
媒体发布 微信/头条/B 站/知乎 等 13 家 只探活 30 min
豆包 Doubao 主动保活 8 min + 30 min 探活
千问 Qwen 主动保活 8 min + 30 min 探活
DeepSeek DeepSeek 只探活 30 min

实施细节：

  • 错峰：同一平台 N 个账号按 hash(accountId) mod period 分布时间槽 + ±30s 抖动。
  • 优先级：业务任务 > 保活 > 探活。
  • 失败升级：保活失败 1 次立即重试；连 2 次失败降级为探活一次确认状态；探活失败则 health: expired，托盘红点 + OS 通知 → 用户点击弹登录窗（partition 复用，不需要重建账号）。
  • 静音时段：默认 0:00–7:00 不保活（可配置关闭）。
  • 休眠感知：powerMonitor.on('suspend'|'resume')，休眠暂停全部保活，唤醒后补一次探活再恢复。
  • 配额池：同一 LLM 多账号时，调度器按"最近使用 + 剩余配额"挑账号。
  • 风控回避：每账号"本小时平台请求数"超阈值就停保活。

4.5 凭据粒度

  • 不保存账号密码。
  • 只保存 Cookie + 平台侧必要 token（如 Doubao 的 ms_token、fp）。
  • 重装客户端 → 从本地加密备份恢复，或重登一次。

5. 适配器模型

5.1 接口定义

interface AdapterContext {
  accountId: string
  session: Session
  view: WebContentsView
  debugger: DebuggerClient
  logger: ScopedLogger
  signal: AbortSignal
}

interface PublishAdapter {
  platform: PlatformKind
  capabilities: { images: boolean; video: boolean; markdown: boolean; /* ... */ }
  probe(ctx: AdapterContext): Promise<HealthState>
  keepAlive(ctx: AdapterContext): Promise<void>   // 默认 no-op
  publish(ctx: AdapterContext, task: PublishTask): Promise<PublishResult>
}

interface MonitorAdapter {
  provider: LLMProvider
  probe(ctx: AdapterContext): Promise<HealthState>
  keepAlive(ctx: AdapterContext): Promise<void>
  query(ctx: AdapterContext, task: MonitorQueryTask): Promise<MonitorResult>
}

5.2 监控适配器标准套路

1. ensureLoggedIn(ctx)     → probe / 必要时触发保活
2. openChat(ctx)           → 在 BrowserView 里导航或复用 tab
3. attach CDP Fetch+Network domain
4. submit query            → 触发网页发出请求
5. collect SSE via CDP.Network.responseReceivedExtraInfo + getResponseBody
6. parse provider-specific payload → normalized MonitorResult
7. detach CDP（finally）

核心价值：步骤 5 抓拦截后的原始 API 响应 JSON/SSE，不依赖渲染后 DOM 文本。UI 改变不影响，只有 API schema 变更才需要更新 parser。

5.3 发布适配器模式

每个发布任务或每个账号带 PublishMode：

type PublishMode =
  | { kind: 'manual'; requireUserReview: true }   // 填好表单后暂停，等用户点"发布"
  | { kind: 'auto' }                              // 一口气跑到底

状态机：filling → readyToReview → submitting → done。manual 在 readyToReview 挂一个用户 gate，auto 不挂。同一份 adapter 代码两种模式共用。

文件上传：protocol.handle('file') + CDP Input.dispatchDragEvent 或直接喂 <input type=file>，不经服务端中转。

5.4 公共能力

adapters/_shared/：

  • debugger-helper.ts：封装 CDP attach/detach、SSE stream 收集、超时。
  • dom-helper.ts：语义化选择器（"找到登录头像"）、重试、容错。
  • upload-helper.ts：文件上传统一入口。
  • captcha-pause.ts：遇滑块/点击验证时把 BrowserView 转前台让用户过，通过后继续。

5.5 双轨更新：局部热更 + 全量

通道 内容 节奏 形式
Patch 通道 单个适配器的 selectors.json、parsers.ts（纯声明 / 纯函数） 分钟级按需 服务端签名补丁包，存 userData/adapter-patches/<platform>/<version>/，下次该适配器的任务开始时动态 import 加载（不重启客户端）
Release 通道 二进制、主进程、UI、适配器宿主框架 周/双周 electron-updater 差分包

Patch 通道硬约束：

  • 只允许替换声明式数据和纯函数模块。静态检查拒绝 fs/child_process/Buffer/require/import.meta.url 等导入。
  • 服务端签名 + 客户端 Ed25519 验签。
  • 每个 patch 带 {platform, version, minClientVersion}；客户端版本不够忽略。
  • UI 每个适配器显示两行版本号：client 1.2.0 · doubao patch #47。

5.6 Trace 基础设施（Playwright Trace Viewer 等级）

记录内容：

类别 内容
CDP 事件流 Network/DOM/Page/Fetch/Runtime 事件时间线
关键截屏 2 fps JPG 或手动截屏
DOM 快照 关键节点 outerHTML
Network 请求+响应，包括 SSE 原始 chunks
日志 console + 结构化

触发策略：

  • 平时：只结构化日志，不录 trace。
  • Rolling buffer：每个适配器保留最近 30 秒内存缓冲；任务失败自动 flush 成 trace，成功则丢弃。
  • 强制录制：UI 开关或启动参数 --trace=always。
  • 日志等级：debug/info/warn/error，按适配器独立调（DEBUG_ADAPTERS=doubao,qwen）。

存储：

  • 位置：userData/traces/<accountId>/<taskId>.trace.zip。
  • 配额：默认保留 50 份 或 500 MB（先到先清）。
  • 脱敏：Cookie / Set-Cookie / Authorization / x-xsrf-token / password / 手机号 / email 自动 <redacted>。
  • 默认不上传服务端；用户手动点"发送诊断包"时才上传。
  • 文件格式兼容 Playwright Trace Viewer（npx playwright show-trace 可直接打开）。

6. 服务端协议

6.1 命名（全部重命名）

老 plugin_installations / /api/plugin/* / installation_token → 新 desktop_clients / /api/desktop/* / client_token。因为是开发版本、无生产流量，DB 迁移直接 drop 旧表、create 新表，不做导入或双写。

6.2 认证

Token 代表 发放 用途
User JWT 人类用户 /api/auth/login 用户在 Electron 内的交互（新增账号、创建监控计划、看报表）
Client Token 一台 Electron 安装 登录后 /api/desktop/clients/register 换取 后台任务回调、任务拉取、心跳

Client Token 绑定 tenant_id + workspace_id + client_id + os + cpu_arch + client_version，SHA-256 后入库。重装/迁机器 = 重新 register。

6.3 任务分发：SSE + 60s pull 兜底

  • 客户端启动后对 /api/desktop/events 建立 SSE 长连接，server 推 {type:'task', payload}。
  • 网络抖/代理不稳时退化为每 60 秒 pull /api/desktop/tasks/lease。
  • 两渠道幂等；任务带 task_id + deduplication_key。
  • 为什么不用 WebSocket：SSE 单向推已足够，穿透 Nginx/Cloudflare 更稳，代码更简单。
  • 为什么不纯 pull：用户在 Web 上点"立即跑一次"需要秒级响应。

6.4 路由表

# 配对
POST /api/auth/login
POST /api/desktop/clients/register          # body: {device_name, os, cpu_arch, client_version}
POST /api/desktop/clients/heartbeat         # client_token, 上报活跃度
POST /api/desktop/clients/metrics           # 轻量非敏感聚合指标

# 事件 & 任务
GET  /api/desktop/events                    # SSE, client_token
GET  /api/desktop/tasks/lease?kind=publish|monitor  # pull 兜底
POST /api/desktop/tasks/{id}/ack
POST /api/desktop/tasks/{id}/result
POST /api/desktop/tasks/{id}/trace          # 用户主动上传诊断包

# 账号元数据（不传 cookie）
POST   /api/desktop/accounts
PATCH  /api/desktop/accounts/{id}
DELETE /api/desktop/accounts/{id}

# 管理 UI（Web / Electron UI 共用）
GET  /api/tenant/monitoring-plans
POST /api/tenant/publish-jobs
# ...

6.5 服务端边界

服务端只存任务意图（"账号 A 去豆包问 Q"）与结果（"答案文本 + 品牌是否出现"）。永不存 Cookie、永不直连平台帮客户端跑。客户端失联 = 任务排队；长时间拿不到 = 超时失败。硬边界，防止 Cookie 从客户端外泄。

6.6 DB Schema（关键表）

  • desktop_clients: id, tenant_id, workspace_id, user_id, token_hash, device_name, os, cpu_arch, client_version, created_at, last_seen_at, revoked_at
  • platform_accounts: id, tenant_id, workspace_id, client_id(FK), platform, display_name, health, created_at, last_seen_at（无 cookie / token 列）
  • desktop_tasks: id, kind, payload(jsonb), status, client_id, lease_expires_at, created_at, result(jsonb), error(jsonb), dedup_key
  • desktop_task_traces: task_id(FK), size, uploaded_at, object_key

6.7 任务生命周期

Web UI 创建 MonitoringPlan("brand=X on doubao,qwen daily 9am")
      ↓
Scheduler (server cron) 展开成 N 条 desktop_tasks (queued)
      ↓
SSE push → 任意在线的、有对应账号的 desktop_client
      ↓
Client ack → lease_expires_at=+10min → 执行 → result
      ↓
POST /result → server 存结果 → Web UI 可视化

7. 错误处理与可观测性

7.1 错误分层

层 例子 处理
适配器内部（可重试） 选择器暂未命中、SSE 断流、CDP 瞬时断开 适配器内部指数退避重试，最多 3 次，不升级
账号级 Cookie 过期、风控滑块、封号 health=expired/risk；托盘红点 + OS 通知；任务返回 ACCOUNT_UNAVAILABLE；服务端不对该账号 retry，派给池里其它账号
平台级 全账号连续失败 N 次、Cloudflare 5xx 熔断 15 分钟；新任务返回 PLATFORM_CIRCUIT_OPEN；到时半开探活
客户端级 主进程 uncaughtException、渲染进程崩溃 落本地 crash log → 可选上报 → 优雅重启

7.2 结构化日志

pino JSON，字段约定：ts, level, module, accountId, taskId, stage, event, durationMs, bytes。本地 rolling file（10 MB × 20 份）。不默认上传。

7.3 指标上报

5 min 一次上报 /api/desktop/clients/metrics，只含非敏感聚合：CPU/内存/事件循环延迟、每平台每账号的任务成功率 + 平均耗时、SSE 连接状态、pull 回退次数。不含查询内容、回答内容、Cookie。

7.4 用户可见反馈

  • 托盘图标三色（绿/黄/红）表示账号健康。
  • OS 通知只在需要用户动作时弹（登录失效、捕获到验证码）。
  • UI "事件中心"：列最近 50 次失败，点进去直接"重新运行"或"启用录屏再跑"。
  • "发送诊断包"按钮：最近 1 小时日志 + trace 打包脱敏上传，返回 diagnostic_id。

7.5 崩溃恢复（幂等）

启动时扫描 desktop_tasks 里 lease 属于我但 result 为空 的任务：

  • 未进入 submit 阶段：重新 ack 再跑。
  • 已进入 submit 阶段（已确认）：放弃任务，标 UNKNOWN，由人判断。UI 提示"上次崩溃时尚不确定是否发布成功，请去平台确认后手动标注"，避免重复发布。

8. 打包、自动更新、签名

8.1 工具链

  • electron-builder 多平台打包 + 差分更新 + 签名。
  • electron-updater 跑在 Main 进程，latest-*.yml + blockmap 差分下发。
  • 渠道：stable/beta/dev，用户可切。Patch 热更通道独立，不走 electron-updater。

8.2 目标矩阵

OS Arch 产物 签名
macOS universal（Intel + Apple Silicon） .dmg + .zip Apple Developer ID + notarytool 公证（已有 Apple Dev 账号，CI 直接接入）
Windows x64 .exe (nsis) 暂无，后期购买（正式发布前阻塞项）
Windows arm64 .exe (nsis) 同上
Linux x64 .AppImage + .deb GPG 可选
Linux arm64 .AppImage + .deb GPG 可选

产物大小目标：单平台 ≤ 120 MB。

8.3 CI

GitHub Actions，runner 矩阵：macos-14 (arm64) + macos-13 (x64) 合并 universal；windows-latest 出 x64 与 arm64；ubuntu-latest 出 x64；ubuntu-22.04-arm 出 arm64（或 cross-build）。发布 tag v1.2.3 → 打包 → 上传对象存储 + 生成 latest-*.yml → autoUpdater.checkForUpdates() 看到。

8.4 更新 UX

  • 默认"自动下载 + 手动安装"。下好后 Tray 角标提示"新版本可用，点击重启安装"。不打断正在跑的任务。
  • 强制更新：服务端下发 minClientVersion；低于该版本拒绝启动，引导升级。
  • 降级：服务端可下发"建议版本号"，客户端比建议版本新时允许一键回滚（electron-updater downgrade: true）。

8.5 应用标识

  • app.requestSingleInstanceLock()：禁止同用户开两个副本。
  • Protocol handler：georankly://，用于 Web 端深链接到客户端。
  • macOS 关闭窗口 ≠ 退出；Windows/Linux 最小化到托盘；退出必须从 Tray 菜单。

8.6 安全加固

  • contextIsolation: true、nodeIntegration: false、sandbox: true for renderer。
  • CSP 严格模式；renderer 不允许加载远程 JS。
  • webContents.setWindowOpenHandler 拦截所有 window.open → 系统浏览器。
  • 禁用 <webview> tag，第三方平台一律用 BrowserView。

9. 测试策略

9.1 金字塔

┌──────────────┐  手工 + 冒烟 Playbook（每 release）
│  E2E 烟雾      │
├──────────────┤  Playwright @ Electron + fake server + fake platforms（每 PR）
│  集成 / 行为    │
├──────────────┤  Vitest（每 commit）
│  单元（adapter）│
├──────────────┤  tsc --noEmit + eslint + typecheck（每保存）
│  类型 / 静态     │
└──────────────┘

9.2 单元

  • 对象：适配器的 SSE parser（纯函数）与 发布状态机。
  • Fixtures：tests/fixtures/sse/doubao-2026-04.txt（脱敏后真实抓的 SSE）。
  • 平台 payload 变动 → 补 fixture → 测试跟着更新。

9.3 集成

用 Playwright _electron.launch 驱动 Electron，对 本地 fake server + 本地 fake 平台（HTTP server 喂 fixture SSE）。13+3 适配器全跑一遍，并行约 3–5 分钟。

9.4 集成 · 协议

客户端 + 真实 server + fake 平台：验证任务分发 / 幂等 / 熔断 / 断线重连。

9.5 人工冒烟 Playbook

每次 release 用测试账号：

  • 每发布平台跑一个 draft/private publish → 立即删。
  • 每 LLM 跑 3 条标准查询，对比上版本抓取结构一致性。

记成 md 文档由 QA 跟着跑，半小时完成。

9.6 Trace 回归套件

工具 pnpm dev:replay <trace.zip>：把真实 trace 里的 network responses 重放到 fake 平台，跑 adapter。历史错过的输入永远不再破解析器。

9.7 不做的

  • 不对 electron-builder 打包产物在 CI 跑 E2E（矩阵太贵）。
  • 不对 autoUpdater 真实升级做 CI（单独写 tests/updater-smoke.md 手动脚本）。
  • 不测真平台滑块 captcha——它是概率事件，只测 gate 机制。

9.8 门禁

  • PR：单元 + 集成（fake）全过。
  • Release tag：+ 冒烟 Playbook 签字。
  • 每周：trace 诊断报告 review。

10. 上线节奏与回滚

10.1 阶段

阶段 受众 签名 退出门槛
Alpha（内部） 开发 + QA（≤5 人） Mac 公证 / Win 无签名 / Linux 裸 AppImage 13+3 适配器 fake + 真实账号成功率 ≥ 90%
Beta（邀请制） 公司内部 + 合作客户（≤30 人） 同上 连续 7 天无 P0；保活命中率 > 95%；patch 通道应急修复跑通 ≥ 1 次
GA 候选 放开注册 Win 签名必须到位 安装成功率 > 99%；crash rate < 0.1%/session

客户端和服务端同加 channel（alpha/beta/stable），更新按 channel 拉不同 latest-*.yml。"关于"里可切。

10.2 硬切换落地顺序（开发版本无生产用户）

因为当前还是开发版本，没有真实生产用户在跑旧 /api/plugin/*，不需要过渡期：

  1. 同一个 PR 里：新增 /api/desktop/* 路由 + 新 DB 迁移 + 删除 /api/plugin/* 路由与相关 handler。
  2. 同一个 PR 里：删除 apps/browser-extension/ 整个目录。
  3. 废弃文档 docs/media-publisher-extension-runtime-v1.md，新写桌面客户端运行时文档。
  4. 发 Alpha 客户端；内部账号全部用 Electron 重登。

如果未来发现有内部测试账号遗留在老表里：手动导出账号元数据后 drop 老表，不写自动迁移。

10.3 三层回滚

情景 动作
某 patch 导致单平台适配器坏 服务端把该平台 patch 版本号回滚到上一稳定版；客户端下次任务自动用旧 patch（秒级）
某 release 中等问题 下发"建议版本 ≤ X"；electron-updater 帮用户降级（分钟级）
某 release 严重安全问题 下发 minClientVersion = Y；低于 Y 拒绝启动，UI 引导升级

所有回滚只在服务端配置，不动客户端代码。

10.4 运营指标

  • 每平台适配器每日成功率（target：发布 > 95%、监控 > 90%）
  • 每次 crash 的 top 堆栈
  • SSE 长连接平均保持时长（target > 30 min）
  • patch 推送后"多久 80% 客户端加载新 patch"（target < 30 min）

11. 已知风险

  1. Win 无签名期间（Alpha/Beta），用户首次安装会遇 SmartScreen 警告，转化率会掉。已接受。
  2. 豆包/千问网页结构变，最坏情况紧急手搓 patch，SLA 按小时算。
  3. 用户跨 OS 切换（Mac → Win 再回来）不迁移登录态（local-only cookies），需全部重登。
  4. 账号被平台风控无法自动恢复；UI 引导用户换号。
  5. 开机自启 + 托盘常驻可能被企业 EDR 误报恶意软件；需准备白名单说明材料。
  6. Electron 基础 RAM 占用~300 MB + 每 BrowserView ~50 MB。10 账号场景约 800 MB，这是 Chromium 本质开销，无法显著优化。

12. 术语表

  • Patch 通道：仅下发适配器的声明式数据和纯函数，分钟级生效，不重启。
  • Release 通道：完整二进制 + 差分升级，通过 electron-updater。
  • 探活（probe）：加载主页 DOM 判断登录态，低代价。
  • 保活（keep-alive / heartbeat）：主动访问平台私有 API 触发 token 刷新。
  • Client Token：一台 Electron 安装的后台身份，与 User JWT 并列。
  • Partition：Electron session.fromPartition('persist:<id>')，每个账号一个隔离的 cookie/storage 容器。
Reference in New Issue View Git Blame Copy Permalink