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 的评审结论确定。

「非套壳」判定标准（本项目红线）

文档导航

关键结论速览

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