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：环境、命令和回归清单。
• 发布检查、当前待办、附属清理方案。

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

首要原则

• 保持启动器、实例宿主和 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 进程树。

实例与数据规则

• 实例元数据位于注册表，核心字段包括名称、DSH_HOME、Profile、共享模式、收藏和创建时间；原生数据仍由对应 Home 管理。
• 不同 DSH_HOME 可并行运行。任何共享同一 Home 的实例均不得并行运行，即使 Profile 不同，因为会话、设置、凭据等仍可能共享。
• 端口在每次启动时自动探测，只在运行时状态中记录。界面只能展示已确认监听的实际端口，停止或崩溃后必须清理。
• 修改实例名称、Home、Profile、插件或其他写入型配置前，必须阻止相关实例运行。
• 移除必须区分两种操作：remove_instance_registry_only 仅移除所选注册记录并保留所有文件；remove_instance 删除整个 DSH_HOME 并级联移除共享该 Home 的记录。不得把仅移除记录改成隐式清理文件。
• 删除共享 Home 时，必须识别所有受影响实例和 Profile；任一相关实例运行时禁止删除。
• 默认在删除前询问是否前往“导出”页面创建完整 Home 备份。用户可在个性化设置中关闭该询问；关闭后删除应直接执行。
• “前往导出”只跳转到实例设置的导出导航，不自动删除；“无需导出”才继续删除。
• 导出完整 Home 可能包含 credentials、API Key、settings、会话等敏感数据。目标文件必须位于 Home 外部，且不得在未授权时上传或解析这些数据。
• 更改实例的 Home 路径不会迁移或删除旧路径数据；只有明确的移除实例流程执行 Home 删除。
• WebView2、日志的附属清理尚属设计方案，见 清理方案。实施时需同步确认文案、失败反馈和测试；不能将“注册表没有该 ID”当作删除授权。注册表读取或解析失败必须中止清理。