feat(computer-use): 将 Cindy Computer Use 迁移为官方插件

[nanaco666]

使用场景 / Use case

我们需要把 Desktop Computer Use 从当前的 Desktop Core 内置能力，迁移为可独立设计、分发和更新的官方 .cindy 插件。

这个 issue 作为长期 tracking issue，持续记录产品设计、架构边界、迁移方案和分阶段落地；不要求一次 PR 完成。

核对基线：2026-08-07，origin/main@9bdc1fa1。

当前问题 / Current limitation

当前真实状态

1. 已有“内置插件”配置壳，但不是可分发插件

   • maker-host/plugins/builtin-plugins.ts 注册了 computer，用于名称、开关和 MCP provider 映射。
   • 该体系仍是 Phase 1 metadata：descriptor 的 capabilities.mcps 为空，且 computer 被归类为 machine-wide、默认关闭、从通用「内置工具」列表隐藏。
   • 开关状态写在 builtin-tools-settings.json -> builtinTools.computer，不是 .cindy 插件的安装、批准、启用状态。

2. Agent 能力仍由 Core 直接提供

   • packages/lizi-mcps/src/computer/ 提供 cindy_computer MCP 的 list_tools / call_tool。
   • apps/desktop/src/main/mcp-integrations/computer.ts 直接承载 CuaDriver 探测、安装、更新、权限、daemon、MCP session、光标、Windows fallback 和错误恢复。
   • 每个 Cindy session 会建立独立的 CuaDriver MCP session，并在 session 关闭时清理。

3. 产品 UI 与权限流程深度耦合 Desktop

   • ComputerUseSection.tsx 直接编排安装、更新、macOS 权限预检/引导、轮询、启用和 Codex bridge 刷新。
   • maker-ipc/channels.ts / register.ts 暴露了整组 Computer Use 专用 IPC。
   • macOS 原生权限引导 helper、Electron fallback、System Settings 开关定位与真实 App 拖拽均随 Desktop 打包。

4. 能力路由仍把它视为 Host 能力

   • 当前 capability routing 使用 replacement: { kind: 'cindy-host', id: 'cindy_computer' }。
   • PR fix(agent): 防止下游 harness 能力无感覆盖 Cindy #1215、fix(codex): 屏蔽重复的 Sky Computer Use 能力 #1693 已解决下游 harness / Sky Computer Use 重复暴露，但权威来源仍不是官方 Cindy 插件。

5. 生命周期尚未完全闭环

   • 当前有 session 级 cleanup 和 cleanupAllComputerDriverSessions()，但后者未接入应用退出 disposer。
   • 仓库中的 cua-driver stop 主要用于 macOS fresh permission probe；“退出 Cindy 时 best-effort 停 daemon、保留用户开关偏好”仍需正式接线与验证。

因此，当前状态更准确地说是：Computer Use 已进入内置工具注册表，但真实产品、运行时和权限仍属于 Desktop Core。

期望方案 / Proposed solution

目标边界

• 官方 Computer Use 插件负责

  • 产品身份、描述、图标和版本；
  • Agent tool / Skill 暴露与使用说明；
  • 启用、安装、更新、设置与状态 UI；
  • CuaDriver 版本策略和用户可见引导；
  • 插件分发、独立迭代与回滚。

• Cindy Core 只保留必须由宿主掌握的最小特权原语

  • Electron / OS 权限边界；
  • macOS 签名 native helper、System Settings 协作和 TCC 事实读取；
  • Windows 托盘与 Win32 fallback 等平台桥；
  • CuaDriver 进程/session 的窄 Host service；
  • 应用退出、崩溃恢复和 capability routing 基础设施。

不新增一个泛化的“任意宿主能力”槽。若插件需要调用宿主，应设计 Computer Use 专用、可审计、权限可展示的窄契约。

分阶段计划

M0：设计与迁移契约

• 确定官方插件 id、manifest、版本与分发方式。
• 明确哪些代码进入插件，哪些继续作为 Host primitive。
• 确定 Agent 暴露方式：插件 tool/Skill 为权威来源；迁移期可保留 cindy_computer 兼容 adapter。
• 定义旧状态迁移：
  • 读取 builtinTools.computer；
  • 已启用用户保留等价授权，已关闭用户继续关闭；
  • 等价权限不得要求重新确认，新增权限必须单独确认；
  • fresh install 继续默认关闭；
  • 保留旧 key/旧版本回退的兼容窗口。

M1：收敛 Host runtime

• 将 CuaDriver status/install/update/permission/session/tool/stop 收敛为一个可测试的 Computer Use Host service。
• 为插件定义窄、结构化、带来源校验的请求与事件契约。
• Renderer 不再直接持有整套 CuaDriver 状态机。
• 把全局 cleanup 接入 Cindy 正式退出链；异常退出与更新重启路径也要给出明确结论。

M2：建立官方 .cindy 插件

• 插件拥有身份、设置/面板、tool、Skill 和使用引导。
• 插件调用 Host service，不自行绕过权限边界。
• 保持 CuaDriver 为一期真实 runtime；不重新实现电脑控制引擎。
• 禁用/卸载时不暴露 Computer Use 工具，不自动探测、下载或弹系统权限。
• 插件更新与 CuaDriver runtime 更新在 UI 中分清，不混成一个版本概念。

M3：迁移设置与用户流程

• 将「直接操作电脑」从 ComputerUseSection.tsx 的 Core 专用逻辑迁移到插件详情/设置体验。
• Browser、Android Automation 不被本迁移误伤。
• 启用流程保持：被动检查 → 显式安装 → Accessibility → Screen Recording → 完成后启用。
• macOS 继续使用真实 CuaDriver TCC 身份；一期不引入临时 companion 造成多身份并存。
• 处理设置页卸载、取消、重开、安装/更新在途和 Codex refresh deferred。

M4：运行状态与跨平台生命周期

• macOS：daemon 活跃时保持清晰、可打开、可停止的真实运行状态入口。
• Windows：复用 Cindy 单一托盘，不增加第二个托盘图标。
• 退出 Cindy 时 best-effort 停止 CuaDriver daemon，但保留用户插件启用偏好，供下次启动恢复。
• running session、Codex shared bridge、Claude Code 与后续 Agent 的启停语义一致。
• 本地 / SSH / Device Link / Mobile 的支持范围明确；不支持的场景 fail closed。

M5：能力路由、兼容与清理

• capability routing 的权威 replacement 从“Core 产品能力”收敛到官方插件来源。
• Cindy 插件可用时不重复暴露 Sky / harness Computer Use；不可用时不制造幽灵替代能力。
• @ 窗口候选、session 生命周期、路径边界和快照代际护栏保持有效。
• 完成迁移观察期后，删除旧 builtin metadata、专用 Renderer 编排和不再需要的 IPC。

M6：验证与发布

• 旧 builtinTools.computer 状态升级 fixture。
• 已启用、已关闭、未安装、driver 缺失、权限缺失、权限撤销、更新后 TCC 变化等回归测试。
• macOS / Windows packaged build 验证；native helper、codesign/notarization 和插件发布链闭环。
• Codex / Claude Code 工具可见性、调用、启停和 deferred refresh 验证。
• 插件基座改动遵守存量插件无感升级红线，并经过对应白名单 review gate。

验收标准

• Computer Use 在产品上是一个真实的官方 .cindy 插件，而不只是 builtin registry metadata。
• Core 中只保留通用且必须特权执行的 Host primitive，不再承载完整产品入口。
• 老用户升级后无需重新安装、重新开启或重复授予等价权限。
• 插件关闭/卸载后没有工具暴露、后台探测、driver 自动拉起或权限弹窗。
• 启用、安装、授权、更新、停止和恢复都有确定状态与可测试语义。
• macOS 与 Windows 都有清晰且不重复的运行状态入口。
• 退出 Cindy 会收敛 Computer Use runtime，且不清除用户偏好。
• 下游 harness 不再与 Cindy Computer Use 重复或无感抢路。

已考虑的替代方案 / Alternatives considered

1. 继续维持当前 builtin plugin metadata

   • 只能统一开关，不能获得插件分发、独立更新、权限清单、设置承载和生态边界，不满足目标。

2. 把全部能力直接塞进插件 Node Worker

   • Node Worker 有用户级本机权限，但 macOS TCC、签名 native helper、Electron 生命周期和跨平台托盘仍需要宿主可信代码；全部下放会让权限边界与发布链更难审计。

3. 先做 branded Computer Use.app 再插件化

   • 不是一期前置。第一阶段继续沿用真实 CuaDriver；独立 companion、单一品牌 TCC 身份和内置签名 runtime 可作为后续里程碑单独设计。

相关项与重复项核对

• PR feat(computer-use): 完成 macOS 权限引导流程 #248：macOS 权限引导。
• Issue [产品讨论] feat(computer-use): 完成 macOS 权限引导流程 (#248) #335：feat(computer-use): 完成 macOS 权限引导流程 #248 的产品/UI 讨论，已关闭。
• Issue cua-driver 自动安装失败：tarball 缺少 cua-cursor-theme #574：CuaDriver 安装包兼容问题，已关闭。
• PR fix(agent): 防止下游 harness 能力无感覆盖 Cindy #1215：宿主 capability routing。
• PR fix(codex): 屏蔽重复的 Sky Computer Use 能力 #1693：屏蔽重复 Sky Computer Use。
• Issue bug(desktop): dev 模式退出后残留 adb server 进程——清理只覆盖 bundled/prepared 来源，且未启用 Android 自动化时打开设置面板也会拉起 adb #1806 / PR fix(desktop): Android 自动化禁用时打开电脑使用面板不再拉起 adb server #1829：Android Automation 的 adb 生命周期，范围不同。

已按 Computer Use、computer-use、CuaDriver、cindy_computer、电脑使用 插件 检索现有 Issue/PR，未发现同范围的 Computer Use 插件化 tracking issue。

[nanaco666]

我正在进行中。这个 tracking issue 由我持续负责设计拆分与分阶段落地；在我更新设计结论或明确开放子任务前，请先在这里同步，避免重复实现和冲突执行。

[dash-s-cindy]

判断：Computer Use 具备稳定的用户价值和可运行的产品基础，官方 .cindy 插件化仍值得推进；当前最需要处理的是产品 ownership、生命周期和发布边界，而不是重新实现电脑控制引擎。

进一步检查 origin/main@ea3ea36c13d5b8a1923be1a794d8ea07b1f79686 后，现状与 Issue 的核心判断一致，但需要把“已有能力”和“尚未完成的产品化”分开看：

• apps/desktop/src/main/maker-host/plugins/builtin-plugins.ts 已注册稳定的 computer 内置插件 ID，并将 cindy_computer 映射到该 ID；但 createBuiltinPlugins() 明确把所有 builtin descriptor 的 capabilities.mcps 固定为空，descriptor 只是身份和启用策略 metadata，并不是可安装、批准、更新和回滚的 .cindy 包。
• packages/lizi-mcps/src/computer/server.ts 仍提供名为 cindy_computer 的 MCP server；Desktop 的 apps/desktop/src/main/mcp-integrations/computer.ts 仍集中承载 driver 解析、status、安装/更新、权限探测、daemon、自有 MCP session、工具调用、Windows fallback、错误恢复和窗口上下文增强。源码中可见 session 级 cleanup、损坏连接恢复、权限探测暂停/恢复和大量回归测试，说明运行时已经相当成熟，但它仍是 Core-owned implementation。
• apps/desktop/src/main/maker-host/capability-routing.ts 的 Computer Use replacement 仍是 { kind: 'cindy-host', id: 'cindy_computer' }。因此当前路由可以表达“由 Cindy 接管”，还不能表达“由官方 Computer Use 插件作为产品权威来源”。
• cleanupAllComputerDriverSessions() 已存在且有测试调用，但在当前源码检索到的正式退出链中没有发现它被注册为 onQuit() disposer。apps/desktop/src/main/lifecycle.ts 已提供 sync/async/post-async 三阶段退出编排，所以缺口是正式接线和语义验证，不是需要另造生命周期框架。

建议的推进顺序

1. 先落 M0：迁移契约和产品决策

在写大规模迁移代码前，先形成一个可评审的契约，至少固定：

• 官方插件 ID、manifest、版本、分发源、批准/启用/卸载状态模型；
• 插件负责的产品 UI、工具/Skill、CuaDriver 版本提示与设置；
• Core 保留的 Computer Use 专用 Host service，以及请求/响应/事件 schema、调用来源校验、错误码和权限声明；
• 迁移期 cindy_computer adapter 的生命周期和退出条件；
• builtinTools.computer（Issue 所述旧配置键）到新插件状态的兼容读取、写回/回退策略。已启用、已关闭、fresh install 默认值、等价权限是否免重复确认，应分别写成 fixture 和产品决策，不要由实现细节隐式决定。

建议把“插件启用状态”和“driver runtime 状态”明确拆开：插件关闭应决定工具是否暴露及是否允许主动探测；driver 是否已安装、daemon 是否运行、OS 权限是否授予则是运行时状态，不能当作同一个版本或开关。

2. 再落 M1：收敛窄 Host service

优先从 Desktop main 抽出可测试的 Computer Use Host service，覆盖：

• passive status；
• 显式 install/update；
• macOS/Windows 权限事实和引导协作；
• session create/call/close；
• daemon stop（包含所有权判定）；
• 应用退出、崩溃、更新重启时的 best-effort cleanup。

Renderer 不应继续持有完整 CuaDriver 状态机；插件通过窄契约调用 Host，而不是复用或绕过现有 IPC。原有 ComputerUseSection、专用 IPC 和权限 helper 先保留为兼容入口，等新插件完成观察期后再删除。

3. 用 vertical slice 验证 M2/M3

第一条端到端切片建议只迁移“产品身份 + 设置/状态面板 + tool/Skill 暴露 + Host service 调用”，一期继续使用真实 CuaDriver runtime 和现有 macOS TCC 身份。迁移期保留 adapter，避免一次切换同时改变工具协议、权限身份和用户配置。

必须覆盖：

• 插件关闭/卸载时无工具暴露、无后台探测、无自动下载、无系统权限弹窗；
• 启用后的被动检查、显式安装、Accessibility/Screen Recording 引导；
• driver 缺失、权限撤销、daemon 重启、session 关闭、安装/更新在途和窗口重开；
• 插件版本与 CuaDriver runtime 版本在 UI 中分离；
• Codex、Claude Code 以及共享 bridge 的工具可见性和 deferred refresh。

4. 最后迁移路由并清理

插件真正可用且状态迁移经过验证后，再把 capability routing 的权威 replacement 改为插件来源；插件不可用时要保持 fail-closed，避免出现幽灵替代能力。观察期结束后再删除 builtin metadata、旧 Renderer 编排和不再需要的 IPC。

尚需确认的产品决策

以下事项不能仅凭当前没有保护代码就直接定为实现要求：

1. Cindy 退出时是否停止所有 CuaDriver daemon，还是只停止本次 Cindy 明确启动且归 Cindy 所有的 daemon；用户自行启动、其他客户端共享的 driver 是否保留。这个问题与仓库中 Android ADB 的所有权争议相似，必须先定义 ownership，再实现 cleanup。
2. SSH、Device Link、Mobile 和远程 Codex/Claude 对本机 Computer Use 的支持矩阵，以及不支持时的 fail-closed 表现。
3. 插件禁用后是否仍允许用户手动查看只读 driver 安装状态；建议默认只显示缓存/静态状态，任何会启动 daemon、执行探测或触发权限流程的动作都必须是明确用户操作，但这应在产品契约中确认。

相关记录

• PR #248：已合并的 macOS 权限引导。它证明真实 CuaDriver.app TCC 身份、原生 helper、Electron fallback 和权限流程可以作为 Host 特权原语保留，是插件化时的直接复用基础。
• PR #1215：已合并的宿主能力路由基础设施。它定义了只隔离已登记冲突来源、保留用户/项目 Skill 和普通 MCP 的产品边界；官方插件化应在此模型上扩展，而不是新增泛化 Host 能力槽。
• PR #1693：已合并的 Sky Computer Use 重复能力修复。它将兼容性限制与本地 Cindy replacement 分开，并以实际 bridge 已挂载 cindy_computer 为接管条件；迁移期 adapter 和插件可用性应保持同样的条件性。
• PR #1829：已合并的 Android 禁用态探测修复。它直接证明“禁用态不主动探测/不拉起 runtime”需要 enable gate，并通过回归测试防止迟到 IPC 恢复旧状态；Computer Use 插件迁移应沿用这一行为原则，但不把 Android 的 driver ownership 决策自动套用到 CuaDriver。

结论

建议接受本 Issue 作为长期 tracking issue，先开一个 M0 设计/契约变更，再开一个 M1 Host service + quit disposer 的窄 PR。现阶段不建议直接删除 cindy_computer、builtin metadata、ComputerUseSection 或专用 IPC；也不建议在未定义 ownership 和迁移 fixture 前强制停止 daemon 或要求用户重新安装/授权。