Desktop 窗口贡献 seam：让插件注册独立窗口（桌面伙伴 / 悬浮球 / 状态 HUD）

[DoodleBears]

背景

DSH 的插件模型已经能把 Host 能力（Service / Event / Registry）和浏览器 UI（Slots）都交给社区插件；桌面端也已经有 Electron 壳（apps/desktop + apps/desktop-host）。我们想做一个"桌面伙伴"插件：作为 Service 被其他插件调用、监听 session/event 等事件做出动作反馈，最终形态是一个独立窗口（置顶、透明、点击穿透、不被截屏）。初期可以渲染在主窗口的 Slot 里，但"始终漂浮在桌面上"必须由独立窗口承载。

现状限制

• 浏览器插件只能通过 Slots 组合进 Web 文档内部，无法表达"应用窗口之外的桌面 UI"；
• Host 插件运行在 Electron RunAsNode 模式下，拿不到 BrowserWindow 等窗口 API；
• Desktop 的安全姿态（renderer 无文件系统、无原始 Electron IPC、无 shell）决定了不能直接向插件开放 Electron 窗口 API；
• 目前做独立窗口只能改 apps/desktop 外壳，社区先例是整仓 fork（mini-yifan/deepseek-harness-orb 的 floating-window.ts / observation-frame-window.ts / selection-toolbar-window.ts / macos-sck-napi），小需求承担了长期合并成本。

用例

1. 桌面伙伴 / 桌宠（透明、置顶、点击穿透、可拖动；后续形态为 Live2D）；
2. 悬浮球类助手；
3. 任务状态 HUD、通知气泡、语音条；
4. 上述窗口需要"从截屏中排除自己"（与 Computer Use 共存）。

提案：window contribution seam

核心思路：窗口由 shell 创建并持有，插件只做注册；复用 DSH 现有 seam 模式，而不是开放 Electron API。

规范对齐（Cordis seam 映射）

实现遵循 DSH/Cordis 现有 seam 规范：贡献插件是 Consumer，Desktop Host 是 Provider（Service Definition 为 DesktopWindowsService）；每个窗口是 shell 拥有的 Window Registry 里的一条 Registration，生命周期挂在贡献方 Fiber 的 effect 上（插件卸载 / 移除 bundle 即关窗）；窗口状态变化用 Cordis Event 广播，不写入 SessionEvent；Host ↔ Client 走 TypertRemoteService + API Gateway（不新增 /api interceptor）；窗口内容作为 Slots 之外的第二类 UI surface 挂载，复用 dsh.client 浏览器 roster 机制；分发仍走 Bundle / Patch，不新增 manifest 格式。

挂载方式（二选一或并存，想听维护者意见）

• A. 程序化 Registry（推荐 v1）：apps/desktop-host 提供 application 服务 ctx.desktopWindows，插件 inject 后 register() 并返回 disposer；bundle 契约不变，无需新 manifest 格式。
• B. 声明式行：bundle 的 cordis.patch.yml 插入窗口声明行，Loader 直接生效，不需要插件写代码；适合纯展示型窗口，但无法表达运行期条件。

内容承载（想听维护者意见）

• a. Client 插件 surface（倾向）：窗口挂载该插件声明的 client 半部；复用现有 dsh.client 浏览器 roster 机制（packages/bundle/web-app/cordis.patch.yml 里已有 Host 行与浏览器 roster 行同 bundle 的先例），只是多一个 window surface 挂载点。插件得到正常的浏览器插件环境，Slots 的认知可以直接迁移。
• b. 受限文档：窗口加载插件提供的文档，采用与 apps/desktop/src/platform-view.ts（持久 partition + preload + 导航阻断）同级的隔离。适合非 DSH UI 的独立视图，但插件需要自带完整前端。

能力位（v1 最小集，全部默认关闭）

alwaysOnTop / transparent / clickThrough（none、all、dynamic）/ excludeFromCapture / skipTaskbar / focusable / 尺寸与锚点 / rememberPosition / 多显示器策略。

安全与边界

• 只有桌面 profile 里已安装的 bundle 能贡献窗口（插件代码本就在 Host 进程运行，"安装即同意"模型不变）；新增风险集中在窗口权限与渲染隔离；
• shell 创建窗口与 preload/partition，插件接触不到 BrowserWindow / webContents；renderer 依旧无 Node、无原始 IPC；
• 数据通道走 Host Service → TypertRemoteService → API Gateway；
• excludeFromCapture 与现有 Computer Use overlay exclusion 机制（ScreenCaptureKit exclude window id / Windows display affinity）对齐而不是另造一条路径，window id 只暴露给 shell 与显式授权的服务；
• 不改变 release identity：窗口是运行期产物，shell/dsh 版本、签名与更新单元不受影响。

接口草案

// Service Definition（application-defined，Desktop Host 提供）
interface DesktopWindowsService {
  register(contribution: DesktopWindowContribution): Promise<() => Promise<void>>
  list(): readonly DesktopWindowSummary[]
  // Cordis Events: desktop-window/created | closed | focus | bounds-changed
}

interface DesktopWindowContribution {
  id: string                                   // profile 内唯一
  surface: string                              // client 插件 surface id（内容模式 a）
  type: 'overlay' | 'panel' | 'notification'
  size: { width: number; height: number }
  anchor?: { corner: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'; margin: [number, number] }
  monitor?: 'primary' | 'all'
  rememberPosition?: boolean
  capabilities?: {
    alwaysOnTop?: boolean
    transparent?: boolean
    clickThrough?: 'none' | 'all' | 'dynamic'
    excludeFromCapture?: boolean
    skipTaskbar?: boolean
    focusable?: boolean
  }
}

// 插件侧用法
export const inject = ['desktopWindows']

export function apply(ctx: Context) {
  ctx.effect(() =>
    ctx.desktopWindows.register({
      id: 'desktop-companion',
      surface: '@example/dsh-desktop-companion/ui',
      type: 'overlay',
      size: { width: 320, height: 480 },
      anchor: { corner: 'bottom-right', margin: [24, 24] },
      rememberPosition: true,
      capabilities: { alwaysOnTop: true, transparent: true, clickThrough: 'dynamic', excludeFromCapture: true, focusable: false, skipTaskbar: true },
    }),
  )
}

# 可选：声明式形态（挂载方式 B），放在 bundle 的 cordis.patch.yml
- insert:
    - id: desktop-companion-window
      name: '@deepseek-ai/dsh-desktop-window'   # 名义行，实际由 shell 消费
      config:
        id: desktop-companion
        surface: '@example/dsh-desktop-companion/ui'
        type: overlay
        size: { width: 320, height: 480 }
        capabilities: { alwaysOnTop: true, transparent: true, excludeFromCapture: true }

需要维护者拍板

1. seam 归谁：apps/desktop-host 的 application 服务（A）还是 Loader 声明行（B）？两者并存是否合理？
2. 内容模式倾向 a（client surface）还是 b（受限文档）？窗口 surface 是否作为 Slots 之后的第二类 UI 挂载点？
3. v1 支持哪些窗口类型与能力位？点击穿透的命中测试由 shell 还是窗口内容协议负责？
4. excludeFromCapture 与 Computer Use overlay exclusion 的关系：复用同一套 window id 注册还是分开？
5. 多显示器 / 混合 DPI 的期望；Linux（无桌面端窗口）时声明如何降级？
6. 命名与词汇：window contribution / desktop window / shell surface，请给一个官方术语。

为什么独立 client 不够（预期讨论点）

独立进程完全可以做桌宠（我们也评估过），但满足不了：与桌面端同一 TCC 身份与权限链、同一单实例与应用生命周期、开箱即用（而不是"再装一个 App"）、以及截屏排除需要同进程持有 window id（Computer Use 场景）。这也是我们倾向 shell seam 而不是外部 client 的原因。相关问题见 #19（原生 App）、#60（外部 GUI / 稳定 runtime 边界）与 #5180（App Plugin：App identity / standalone window 约定，首发于 #3328）——本提案是它们的补充：外部 client 解决"另一个 GUI 接 DSH"，本提案解决"同一个桌面端内的插件窗口能力"。

我们愿意做什么

• 先用纯现有插件 API 做一个主窗口 Slot 形态的最简示例（Host Service + 事件监听 + client Slot 挂件，不含 Live2D），作为需求证据：https://github.com/BotHarness/dsh-companion-example ；
• 已在 BotHarness 组织下 fork DSH（https://github.com/BotHarness/deepseek-harness ），准备实现上述 seam：apps/desktop 最小改动 + apps/desktop-host 服务 + docs + 最小示例窗口 + 单测，保持默认关闭、可选、声明式；
• PR 只含 seam 与最小示例；我们的桌面伙伴产品作为独立 bundle 仓库当第一个真实 consumer，不混入 PR。

参考先例：上游 apps/desktop/src/platform-view.ts、update-overlay.ts、tray.ts、packages/bundle/web-app/cordis.patch.yml；社区 mini-yifan/deepseek-harness-orb 的 apps/desktop/src/floating-window.ts。

[DoodleBears]

进展同步：按这条讨论的提案，seam 已经实现并本地验证完成。

不过我们发现仓库目前不接受外部 PR（CONTRIBUTING），GitHub 也返回 "An owner of this repository has disabled the ability to open pull requests"，所以先在这里同步实现，等官方给出接收方式（开放 PR / patch / 其他）再提交。

实现分支：BotHarness/deepseek-harness → feat/desktop-window-contribution（commit aa43257）
https://github.com/BotHarness/deepseek-harness/tree/feat/desktop-window-contribution

包含：

• Host 侧：ctx.desktopWindows 服务（open(spec) / close(id) / desktop-window/closed Cordis 事件），经私有 IPC 与 Electron 主进程通信；host protocol 代际 4 → 5。
• Shell 侧：window-contributions 按 spec 建窗并持有 —— 无边框、透明、置顶（floating）、可选点击穿透、锚点/边距、最多 8 个，每个字段进入 Electron 前校验；专用 surface preload；贡献窗口加入 WebSocket 握手放行；退出时统一清理；surface 启动失败只记录日志。
• Client 侧：URL 带 ?dsh-surface=<package> 时，把注入的 boot graph 裁剪到该包的包名依赖闭包（保留 bootstrap），surface 窗口只激活自己的 surface 而不是整套 UI（示例从 66 个条目降到 10 个）；surface 插件通过 shadow root slot 渲染。
• 测试/文档：3 个 spec / 13 个用例；apps/desktop/tests + apps/desktop-host/tests + apps/web/tests 1306 passed；oxlint 0 errors；apps/desktop/README(.zh).md 新增 "Contributed windows" 一节。

第一个真实 consumer（纯插件 API，含截图）：https://github.com/BotHarness/dsh-companion-example

演示形态：主窗口右下角 Slot 徽章 + 一个独立、透明、置顶的窗口，窗口 URL 为 dsh-app://app/?dsh-surface=dsh-companion-example。

如果后续开放 PR，或希望以其他形式接收这个 seam，我可以随时配合调整。