deepseek-harness-desktop: Instructions file for Codex

DSH Launcher 开发规范

本仓库是 DSH Launcher（Deepseek Harness Desktop）的启动器开发分支。它管理多个 DSH 实例、DSH 运行时、插件生态、更新和 Windows 桌面集成；实例窗口直接承载 DSH 原生 Web。本文是仓库级开发约束，代码、产品行为与本文冲突时应先核实当前实现和最新用户决策，不得凭旧方案覆盖现状。

文档导航与维护

• README：项目介绍、下载和快速开始；不另建重复的 project-overview。
• 用户指南：面向使用者的操作和故障处理。
• 架构与数据流：进程、运行时、数据归属和协作边界。
• Tauri 接口契约：关键 command、事件载荷、错误码与实例绑定；不重复普通组件 Props。
• 视觉规范：主题、布局、交互状态和视觉回归。
• 开发说明 / English：环境、命令和回归清单。
• 发布检查、当前待办、附属清理方案。
• 服务商与界面升级执行基线：该模块的设计决定、阶段表、逐项落地状态与尚未验证项。改服务商模块前先读它的边界与验收段。
• 已知缺陷清单：master 全量源码通读得到的缺陷台账（P0/P1/P2），每条带位置、证据等级与"已排除"记录。接手、排期或声称"已修"之前先读它，不要凭这份清单以外的记忆判断现状。

本文保留强制约束，详细说明由对应文档维护。行为/协议/数据流变化时同步相关文档；待办标明待实现、待验证与验收条件，不把过程记录或旧交接当作完成证据。

首要原则

• 保持启动器、实例宿主和 DSH 原生 Web 三层解耦。
• 启动器负责管理和适配 DSH 的外部运行契约，不修改 DSH 核心、Web 路由或原生页面业务逻辑。用户明确选择的模型服务商导入可通过已验证的外部配置契约写入设置和凭据；不得借此覆盖无关会话、密钥或 Agent 预设。
• 实例宿主只负责进程、窗口、端口和生命周期，直接加载对应 DSH 本地 Web 地址；不要用启动器页面或 iframe 业务层替代 DSH 原生 Web。
• 只要 DSH 保持可启动的 CLI/Web 外部契约，原生 Web 内部更新不应要求封装层同步改造。若 CLI 参数、启动方式、认证或服务入口变化，由启动器适配层处理。
• 所有实例级操作必须显式绑定 instance_id。不要依赖“当前选中实例”跨异步边界执行写操作；临时切换 Rust 全局活动实例时必须在成功和失败路径恢复。
• 仓库通常包含大量未提交开发改动。禁止重置、回滚、格式化或清理无关文件；修改前先读取重叠代码并与现有改动协作。

进程与窗口模型

• RunMode::Launcher：启动器管理窗口、实例注册表、托盘面板、更新、下载、插件管理和实例宿主进程表。
• RunMode::Instance { id }：通过 --mode instance --instance-id <id> 启动，只运行该实例的 DSH 服务并创建独立窗口。
• 启动器与每个实例是独立 Tauri 进程，并使用独立 Windows AppUserModelID；任务栏应分别显示启动器、实例 1、实例 2 等入口。
• 仅在确认实例服务就绪且实例窗口出现后最小化启动器，不能点击启动或仅创建 PID 后立刻最小化；失败应保留可见错误入口。保留任务栏和系统托盘入口。主窗口关闭按钮只隐藏到托盘；只有明确的“退出启动器”操作才退出应用。
• 托盘面板是独立的 tray-menu WebView（index.html?view=tray），失焦或关闭时隐藏，不应退出主进程。
• 不要用“同一 Tauri 进程多个普通窗口”代替实例宿主进程；进程级 PID、端口和活动配置会因此相互覆盖。
• 实例启动是异步状态机。必须区分宿主已创建、等待端口、DSH 健康检查通过、启动失败和进程退出，不能把 PID 存在等同于服务可用。
• 实例退出不得导致启动器退出；启动器需清理陈旧 PID、端口和宿主记录。启动器退出时应回收自己持有的 DSH 进程树。