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 载波方案不变。

官方网站：https://lansi-ai.github.io/dsh-forge/ —— 源在 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 的可插拔能力层：

1. 锻造，而非套壳：桌面能力不是给网页套个外置浏览器，而是像冶炼锻造一样，把托盘、全局热键、系统通知、多窗口等原生能力逐一铸成 host 插件，与官方装配进同一个 Cordis Host 插件树。
2. 可插拔、可卸载、可审查：每个桌面能力都是一个可被 dsh plugin 列出、可被 patch 增删的插件；Forge 的心智在于「组合与再加工」——没有写死的外壳，只有一套可持续锻造的能力层。
3. 经得起锤炼的出厂标准：锻造意味着每处都要经受检查——桌面动作进会话轨迹、敏感操作过 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 自测驾驶器（提议）

关键结论速览

1. 官方已为桌面预留架构插槽：GUI 分层说明明确「未来 Electron 应用复用同一套 web client 包，仅换 IPC fetch 载波」； webserver 文档明确「只服务浏览器：Electron 用 file:// 加载 dist，fetch 走 IPC 桥」。
2. 社区桌面（sdkwork-ai/deepseek-harness-desktop 等）已实现「Electron + IPC + 官方 Web profile + 打包分发」—— 它们解决的是分发与桌面体验，未深入宿主内嵌与能力插件化。本项目的差异化在第二层深度。
3. 推荐方案（底座）：Electron 主进程内嵌 Host（dsh-app-boot.boot() 装配 desktop profile）， 传输用官方预留的 IPC 载波；桌面能力全部做成 host 插件。renderer 自 M6 起为自绘 UI 逐槽位替换官方 dist（D-20，见 docs/plugin-inventory.md）。
4. 旧插件不丢弃：dsh-terminal / dsh-rule-manager / dsh-restart 的 host 半经 desktopRoutes 等价面零改动可用， client 半经零端口 bundle 兼容面保留（ADR-007）。
5. 红线：默认零 HTTP 端口；一切与官方 API 的耦合点（AbstractApiClient.doFetch、BootSeams.loadBundle、 webServer 路由、bundle patch）都收敛在少数可替换文件，随上游 rc 版本钉死。
6. 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 -- <version> [--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 官方无附属关系； 所有官方商标/名称的使用遵循其品牌指引。