dsh-forge — DeepSeek Harness 桌面客户端（非套壳路线）
> 状态：M1–M3 已完成 · M6 全量自绘 UI 主线进行中（Electron 44 + TS strict + ESLint）。
> 最新执行状态以 docs/active-context.md 任务看板为准（本文为项目总纲，非滚动状态源）。
> AI 协作规则入口：docs/PROJECT-RULES.md（权威规则）+ docs/startup-prompts.md（新会话启动咒语，复制即用）。
>
> 目标版本基线：@deepseek-ai/dsh 已升级至 0.1.5-rc.2（2026-09-11 C-7 人工适配，零代码适配；
> 升级历史见 docs/upstream-migrations.md，拴合面速查见 docs/upstream-contracts.md）。
>
> UI 路线（2026-08-27 用户决策 D-20 更新）：主面已由「官方 Web UI 复用（M1–M3 底座）」切换为 M6 全量自绘
> （逐槽位替换官方 ui-*，ADR-006 已启用，进度见 docs/plugin-inventory.md）。
> 下文「定位/判定/路线」中「官方 UI 复用」均为 M1–M3 底座事实；宿主内嵌与 IPC 载波方案不变。
> 官方网站： —— 源在 website/（VitePress），本地预览 npm run docs:dev，构建 npm run docs:build。
名称与含义：DSH Forge
项目的公开产品名是 DSH Forge，工程代号与自研插件命名空间统一为 dsh-forge（应用目录名 dsh-forge、插件 ID @lansi-ai/dsh-forge-*）。Forge 意为「锻炉」，直接回应本项目的一句话定位——把桌面操作系统锻造成 DeepSeek Harness 的可插拔能力层：
- 锻造，而非套壳：桌面能力不是给网页套个外置浏览器，而是像冶炼锻造一样，把托盘、全局热键、系统通知、多窗口等原生能力逐一铸成 host 插件，与官方装配进同一个 Cordis Host 插件树。
- 可插拔、可卸载、可审查：每个桌面能力都是一个可被
dsh plugin列出、可被 patch 增删的插件；Forge 的心智在于「组合与再加工」——没有写死的外壳，只有一套可持续锻造的能力层。 - 经得起锤炼的出厂标准：锻造意味着每处都要经受检查——桌面动作进会话轨迹、敏感操作过 approval 审批、日志统一。可审查是 Forge 的默认品质。
在 DSH（DeepSeek Harness）生态中，「DSH Forge」意为为 DeepSeek Harness 锻造桌面的炉台：上游提供内核，Forge 在其上加装一张可塑性、可组合、可审查的桌面锻床。
一句话定位
把 DeepSeek Harness 做成一个真正的桌面应用：Electron 主进程内嵌 Cordis Host（与官方 Web 版同内核、零移植），
渲染进程加载官方 Web UI 发行物（file:///自定义协议 + IPC 桥接，不开放 HTTP 端口），
所有桌面原生能力（托盘、全局热键、系统通知、剪贴板、开机自启、协议唤起、多窗口）以 host 插件 形态注入运行时，
与官方「一切皆插件」的架构同构——不是给网页套壳，而是把桌面能力变成可装配、可卸载、可审查的插件树。
AI 驱动开发声明
本项目（含 docs/ 设计文档、docs/PROJECT-RULES.md 工程规则、src/ 代码、scripts/ 验证脚本）全程由 AI 驱动编写，
迭代过程基于 docs/PROJECT-RULES.md 的协作 SOP 与 docs/pitfalls.md 的实战踩坑记录进行。
开发中遵循以下原则：
- 契约优先：所有 IPC 契约 / zod Schema / DTO 先定义于
src/types/，作为唯一类型源头，preload / 桥 / 测试类型均由推导获得。 - 规则驱动：
docs/PROJECT-RULES.md（权威规则，由原.trae/rules/精炼合并，历史见docs/rules-archive/）+docs/active-context.md（滚动看板）约束编码、放置、提交与看板同步；新会话用docs/startup-prompts.md的启动咒语激活。 - 可复现排障：开发中遇到的环境/架构问题与解法沉淀于
docs/pitfalls.md，供后续会话与协作者查阅复用。 - 质量自检链：交付前必过 typecheck / lint / build + 自动化验证脚本（
scripts/verify-*.cjs）全绿，并经实机验收。
> 说明：代码为 AI 生成 + 人工决策审阅的产物；架构与技术选型（Electron 内嵌 Host、IPC 载波零端口、官方 UI 复用、插件化桌面能力）基于 docs/ 与 ADR 的评审结论确定。
「非套壳」判定标准（本项目红线）
| 维度 | 套壳（反面教材） | 本项目（目标） |
|---|---|---|
| Host 进程 | 外部子进程 dsh web，壳只是浏览器 |
主进程内嵌 Cordis Host，生命周期与应用合一，可编程启停 |
| 传输 | 直接加载 http://127.0.0.1:3080 |
官方预留的 Electron 载波插槽：file:// dist + AbstractApiClient IPC 桥（doFetch 覆写），零端口 |
| 原生能力 | 无 / 壳层脚本零散处理 | 每个能力一个 host 插件（forge-tray / forge-shortcuts / …），经 cordis.patch.yml 装配 |
| UI | WebView 原样 iframe | M1–M3 复用官方 Web UI 发行物（底座已落地）；M6 全量自绘：逐槽位替换官方 ui-*（ADR-006，进度见 docs/plugin-inventory.md） |
| 旧插件 | 无视 | host 半零改动可用（desktopRoutes 等价面）；client 半经零端口 bundle 兼容面保留（ADR-007） |
| 可审查性 | 壳行为不可见 | 桌面动作进会话轨迹、权限走 approval 服务、日志统一 |
| 分发 | 安装包 + 手动 dsh plugin |
一包涵盖 runtime + 官方 UI dist + 插件 + 皮肤 + 更新，零外部依赖（仅 Electron 运行时） |
文档导航
| 文档 | 内容 |
|---|---|
docs/PROJECT-RULES.md |
AI 协作规则唯一权威入口：硬约束红线 / 目录放置 / 工作流分级 A・B・C / 提交规范 / 字典索引（原 .trae/rules/ 精炼合并，历史见 docs/rules-archive/） |
docs/active-context.md |
当前任务看板（滚动窗口 ≤100 行，开工第一读；"MD+HTML 双落盘"已废弃，仅 MD） |
docs/startup-prompts.md |
新会话启动咒语 Preset：标准 / 轻量 / 续接 / 排障 / 上游升级 五版复制即用 |
docs/01-research.md |
DSH 架构调研：Cordis、Host/Client 分层、四象限 RPC、客户端插件加载、SDK、官方/社区桌面现状 |
docs/02-requirements.md |
产品定位、目标用户、功能需求矩阵（P0/P1/P2）、非功能需求 |
docs/03-routes.md |
技术路线对比：Electron 内嵌 Host + 官方 UI 复用（推荐）/ Tauri 2 / SDK 自研 / PWA / 纯套壳；选择论证 |
docs/04-architecture.md |
总体架构：进程模型、模块划分、数据流、与官方 layering 模型的对齐 |
docs/05-host-plugins.md |
宿主插件设计：desktop bundle、ctx.desktop.* 服务接口、各能力插件规格 |
docs/06-client-plugins.md |
客户端插件设计：官方 UI 槽位注入 + 零端口 bundle 兼容面（含旧插件承接） |
docs/07-forge-shell.md |
桌面外壳设计：主进程装配（boot()）、IPC 桥协议、官方 dist 装载、窗口管理、打包分发、自动更新 |
docs/08-security.md |
安全与信任模型：无端口、renderer 隔离、权限、签名、外链白名单 |
docs/09-roadmap.md |
里程碑 M1–M6 与任务拆解、验收标准 |
docs/10-development.md |
开发环境、构建链路、调试、测试、与上游同步、发版流程（§9） |
docs/11-risks.md |
风险登记与控制措施 |
docs/12-references.md |
全部依据：本地源码路径 + 官方/社区 URL 引用 + 现有插件 API 面盘点 |
docs/plugin-inventory.md |
插件清单与自有化进度：Host/Client 两侧完整插件树、桌面自有插件（@lansi-ai/dsh-*）、互斥排除清单、全量自绘（M6）逐阶段进度 |
docs/13-ui-design.md |
forge-First 自绘 UI 愿景（已启用为 M6 主线 · D-20；实际替换进度见 docs/plugin-inventory.md） |
docs/14-implementation-map.md |
实现地图：程序组成、代码位置、关键链路（与代码同步更新） |
docs/15-computer-use-testing.md |
AI 自测驾驶器：双实例分离 + 零端口管道 + CDP/AX 混合，agent 自主真机测试闭环（设计稿） |
docs/adr/ |
架构决策记录：ADR-001 选 Electron · ADR-002 宿主内嵌 · ADR-003 IPC 载波 · ADR-004 装配模型 · ADR-005 版本钉死 · ADR-006 自绘主面（已启用 · M6 主线） · ADR-007 旧插件兼容 · ADR-008 数据根分层 · ADR-009 AI 自测驾驶器（提议） |
关键结论速览
- 官方已为桌面预留架构插槽：GUI 分层说明明确「未来 Electron 应用复用同一套 web client 包，仅换 IPC fetch 载波」；
webserver 文档明确「只服务浏览器：Electron 用file://加载 dist，fetch 走 IPC 桥」。 - 社区桌面（sdkwork-ai/deepseek-harness-desktop 等）已实现「Electron + IPC + 官方 Web profile + 打包分发」——
它们解决的是分发与桌面体验，未深入宿主内嵌与能力插件化。本项目的差异化在第二层深度。 - 推荐方案（底座）：Electron 主进程内嵌 Host（
dsh-app-boot.boot()装配 desktop profile），
传输用官方预留的 IPC 载波；桌面能力全部做成 host 插件。renderer 自 M6 起为自绘 UI 逐槽位替换官方 dist（D-20，见docs/plugin-inventory.md）。 - 旧插件不丢弃：
dsh-terminal/dsh-rule-manager/dsh-restart的 host 半经desktopRoutes等价面零改动可用，
client 半经零端口 bundle 兼容面保留（ADR-007）。 - 红线：默认零 HTTP 端口；一切与官方 API 的耦合点（
AbstractApiClient.doFetch、BootSeams.loadBundle、
webServer路由、bundle patch）都收敛在少数可替换文件，随上游 rc 版本钉死。 - UI 差异化（M6 主线）：自绘 UI 已启用（2026-08-27 D-20，见
13-ui-design.md与 ADR-006），逐槽位替换官方ui-*的进度见docs/plugin-inventory.md。
发版（维护者）
一条命令完成 门禁 → 版本号 → commit/tag →（可选）本地打包与推送，脚本为 scripts/release.cjs：
npm run release -- [--local] [--push]
完整选项、前置条件与 CI 衔接见 docs/10-development.md §9 发版流程。
目录规划（未来实现期）
dsh-forge/
├─ docs/ # 本文档集（当前阶段唯一内容）
├─ shell/ # Electron 应用（main / preload / IPC 桥 / 协议 / 窗口/托盘）
├─ bundle/ # desktop profile 的 cordis.patch.yml（dsh.bundle 声明）
├─ packages/
│ ├─ forge-host-* # 桌面能力宿主插件（tray/shortcuts/notifications/clipboard/compat/…）
│ ├─ forge-client-* # 官方 UI 槽位注入的客户端插件
│ └─ forge-* # 共享库（IPC 协议类型、桥接、配置 schema）
├─ scripts/ # 构建（dist/shell）/ 打包 / 签名 / 更新产物脚本
└─ tools/ # 与上游 dsh 仓库同步的工具
许可证与归属
设计文档按 MIT 发布（与 DeepSeek Harness 一致）。本项目为独立社区项目，与 DeepSeek 官方无附属关系；
所有官方商标/名称的使用遵循其品牌指引。
