lansi-ai/dsh-forge

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 的可插拔能力层：

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 --  [--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 官方无附属关系；
所有官方商标/名称的使用遵循其品牌指引。