原生桌面工作台Sparrived/DSH-Deeptop

Deeptop

Deeptop 是 DeepSeek Harness（DSH） 的轻量级原生桌面客户端。它使用 Tauri + React 提供桌面工作台，同时把 DSH 的 Agent、Session、Tool、Model、Workspace、Skill、Goal 和 Provider 能力保留在同一棵 Cordis 运行时树中。

Deeptop 不是对 dsh web 的页面包装，也不会在桌面进程中复制一套 Agent 或插件实现。桌面端负责原生窗口、进程管理、JSONL 传输和交互界面；领域语义、持久化、事件、权限和插件服务优先由 DSH Host/Cordis 提供。

项目地址：Sparrived/DSH-Deeptop

文档导航

- 项目说明手册：从安装、运行、目录、数据流到扩展方式的完整说明。
- CI/CD 与发布：GitHub Actions 检查、跨平台安装包、版本同步和自动 Release。
- DSH 原生协调关系：说明 Tauri、Bridge、Cordis Profile、ApiProxy、Remote、Projection 和 React 的边界与调用链。
- 架构说明：说明依赖方向、纯前端模型层和插件化规则。
- 官方插件兼容策略：Host/Cordis 与 WebUI Client 的兼容分层、当前状态和后续工作。
- Cordis/UI Runtime 重构计划：合并 UI Runtime 后的功能归属、会话置顶迁移和后续拆分顺序。
- Cordis/UI Runtime 重构交接文档：新会话接手迁移、测试、风险和工作区保护事项。
- WebUI 对齐清单：当前功能覆盖、缺口和明确排除的 WebUI 基础设施。

- 宠物包开发指南：制作、校验、导入和分享声明式 .deeptop-pet 宠物包。

当前功能

桌面工作台目前覆盖 WebUI 的核心对话面，并提供原生 DSH 运行台。下面区分已支持、部分支持和依赖 Profile 的能力：

| 领域 | 状态 | 说明 |
| --- | --- | --- |
| 会话 | 已支持 | 持久化列表、历史恢复、历史向前分页、实时事件、重命名、搜索、分叉、归档、恢复和删除归档会话。 |
| 对话 | 已支持 | assistant/reasoning 流式拼装、Markdown/GFM、图片附件、排队/steering（引导）提示、队列编辑/移除、停止和消息重试。重试会创建可恢复的前缀分支，不回滚原会话。 |
| 工作区 | 已支持 | 原生目录选择、创建/重命名/删除、会话归属、分组和排序；会话置顶状态由 Deeptop Profile 的 session-pins Host Plugin 持久化。选定路径会作为会话 cwd 传入 DSH。 |
| 系统托盘 | 已支持 | 显示未读、最近与更多会话并可直接跳转；Windows 使用固定宽度的 Deeptop 弹窗，跟随应用的 Light、Dark、System 与自定义 CSS 主题。 |

| 互动宠物 | 已支持 | 独立透明置顶窗口可跨应用和显示器拖动，并响应点击、长按和任务状态；共享养成层保存饱食、心情和亲密度，支持喂食、摸摸和陪玩，换皮不会重置状态且可单独暂停。活动列表按 Deeptop 的“需要输入、阻塞、已完成未读、运行中”顺序显示多个会话，卡片可处理会话并切换到照顾面板。第三方宠物使用不含脚本的 .deeptop-pet 精灵包导入、导出和分享，总开关会直接销毁窗口。需要完全移除源码时执行 npm run pets:remove。 |

| 模型与 Provider | 有边界地支持 | Provider/模型目录、每会话模型选择、思考程度、上下文窗口和输入模态元数据、Provider 发现及自定义连接设置；llm-pi-ai Provider 上未声明思考档位的模型可直接在发送框滑选 Off/Low/Medium/High/Xhigh/Max，首次提交把档位声明写进该路由的本地设置，设置里也能为已配置模型声明或关闭 Max。RC8 的 current/routable 是发送准入依据，groups 仅用于候选展示；Schema 驱动的 Provider 表单尚未完整实现。 |
| File/Session Reference | 已支持 | 使用 DSH RC8 官方 Host 服务提供 @ 文件/目录候选和 canonical session mention；查询通过 Bridge 传递取消信号，React 不读取历史或构造会话快照。 |
| 图片附件限制 | 已支持 | 从 session.history projection 和实时 projection 事件读取 RC8 imageLimits，在本地提前检查媒体类型、字节数、像素/边长、单条消息图片数和总大小；Host 仍是最终校验者。 |
| 工具与交互 | 已支持 | 工具调用/结果、Workflow、Job、Todo、轨迹视图、单选/多选/自定义问题响应，以及审批响应。任务面板点击任务即可展开输出：Bridge 走 DSH 非消费式投影（ctx.jobs.peek），运行中的任务跟随刷新，不占用模型 job_output 的读取游标。 |
| 反馈与导出 | 部分支持 | 消息赞/踩和带版本的备注可用；会话 JSON/ZIP 导出可用，但 ZIP 当前通过 JSONL Bridge 以 Base64 传输，尚未采用原生流式下载。 |
| 诊断与日志 | 支持 | DSH 运行时、Bridge 与前端错误堆栈按时间戳记录，持续写入 $DSH_HOME/logs，并可在 设置 → 日志 中查看、筛选和导出。 |
| DSH 运行台 | 依赖 Profile 的能力 | Profile/插件清单、运行时检查器、Host 设置、Skill 目录、Agent Preset、Subagent 历史/追问/中断和 Goal 生命周期。可选域缺失时保持不可用，不伪造成功。运行时同时携带 RC8 的 desktop-persistent-pwsh 和 desktop-agent-teams 预设；前者为稳定可选能力，后者为私有实验能力，二者都不默认启用。 |
| Skill 安装 | 已支持 | 输入框 /skill 候选，以及受审批保护的 GitHub 安装，支持直接下载和 sparse-git fallback。 |
| Remote 与事件 | 已支持 | Typert Remote loopback 调用和官方 Host 事件转发；原生界面适配契约，不加载 WebUI Client Bundle。 |
| 部分领域 | 开发中 | Permission 全局控制、Plan chip/Review、完整 Session Stats、递归 Subagent、Schema 设置、长会话虚拟化、完整媒体预览和本地化仍未完成。 |

窗口当前为无边框、可调整大小，默认 1360×860，最小 920×620；支持 Light、Dark、System 主题和外观设置。

可选 DSH 插件缺失时，对应面板会保持不可用并显示错误状态；Agent 对话不应因为单个可选域缺失而被桌面端伪造或中断。

首次使用

1. 运行 npm run tauri:dev，等待运行时指示器显示 DSH 已就绪。开发启动会从 vendor/dsh 构建、同步并校验固定提交的内嵌运行时；应用启动不会使用 PATH 中的 dsh、npm 全局安装、DSH_HOME prefix、npm/npx 缓存或 registry。
2. 打开设置/运行台；如果当前 Profile 提供对应域，配置 Provider 和凭据。凭据通过 DSH API 写入，不要把密钥放进仓库或 Profile 补丁。
3. 选择或创建工作区。选定目录会作为新建会话的 cwd，不会自动修改已有会话的工作目录。
4. 创建会话、选择模型并发送提示。回合运行中，发送按钮会显示本次投递方式（排队或插入），右侧箭头的上拉菜单可切换它；待处理消息也会各自标出是排队还是插入。输入 @ 可通过 DSH RC8 File/Session Reference 选择文件、目录或会话；带空格的路径使用引号候选。
5. 在原生交互面板中处理审批和问题响应。问题可以根据 DSH 事件支持单选、多选或自定义文本。
6. 使用 /skill 获取 Skill 候选，通过 Subagent 和 Goal 面板使用对应 DSH 工作流，并用运行时 Inspector 检查 Profile/插件能力。
7. 使用会话操作执行重试、分叉、归档、恢复、导出或删除。刷新运行时会重启 DSH 子进程，等待中的请求可能失败。

仓库已包含 GitHub Actions 发布流水线。src-tauri/tauri.conf.json 已启用 Tauri bundle；推送 v0.2.0 这样的 SemVer Tag 后，会自动构建 Windows（NSIS/MSI）、Linux（DEB/AppImage）和 macOS（DMG）资产，并发布 GitHub Release。完整流程和签名配置见CI/CD 与发布。

与 DSH 的原生协调关系

┌──────────────────────────────────────────────┐
│ Tauri + React 原生桌面界面                    │
│ 会话、输入、设置、运行台、Inspector           │
└──────────────────────┬───────────────────────┘
│ Tauri invoke / events
┌──────────────────────▼───────────────────────┐
│ Rust Bridge Manager                           │
│ 启动 DSH、物化 Profile、JSONL stdin/stdout     │
└──────────────────────┬───────────────────────┘
│ deeptop/1 JSONL
┌──────────────────────▼───────────────────────┐
│ node          │
│ --profile deeptop                             │
│ dsh-base + deeptop-bridge + 用户 Profile      │
└──────────────────────┬───────────────────────┘
│ 同一 Cordis 树
┌──────────────────────▼───────────────────────┐
│ DSH Host/Cordis                               │
│ Session / Agent / Tool / Model / Storage       │
│ Workspace / Skill / Goal / Provider / ApiProxy │
└──────────────────────────────────────────────┘

关键原则：

1. DSH 是领域能力的权威来源，桌面端复用 Host/Cordis 服务、ApiProxy、Remote 契约、Projection、事件和数据语义。
2. 仓库内置 Cordis 插件按职责独立存放在 cordis//；运行时统一物化为兼容 Bundle deeptop-bridge，它不是独立 HTTP 服务，也不是第二套 Agent。
3. Tauri 只维持一个隐藏、长驻的 DSH 子进程，并通过 JSONL 请求/响应和事件流连接原生 UI。
4. 只有桌面传输、目录选择、文件下载和原生交互等边界能力放在 Bridge/Tauri 中；领域逻辑不应在 React 或 Rust 中复制。
5. WebUI 专属的 ModuleLoader、Client Runner、slot registry 和客户端生命周期不属于纯桌面兼容目标。

详细调用链、职责表和插件扩展方式见 DSH 原生协调关系。

运行时与数据目录

桌面端启动时会执行以下准备工作：

1. 读取 DSH_HOME；未设置时，Windows 默认使用 %USERPROFILE%\.dsh，Unix-like 系统默认使用 $HOME/.dsh。
2. 创建 $DSH_HOME/profiles/deeptop，写入或补齐 Deeptop Profile 清单。
3. 将 cordis/ 下的内置插件按嵌套目录写入 $DSH_HOME/profiles/node_modules/deeptop-bridge，因此无需全局安装该 Bundle。
4. 保留用户已有的 Deeptop Profile Bundle 和 $DSH_HOME/profiles/deeptop/cordis.patch.yml 修改。
5. 从 Tauri 安装包的压缩 dsh-runtime.tar.gz 和清单读取固定版本的 DSH 源码构建产物和完整依赖树。
6. 未发现兼容的系统 Node.js 时，自动从 nodejs.org 下载该平台固定的 Node.js 22.21.1 发行包（Windows 为 ZIP，Linux/macOS 为 tar.gz），用编译期固定的 SHA-256 先校验归档、再校验解压出的可执行文件，然后仅把该可执行文件写入应用本地运行时缓存；不会修改系统 PATH，也不需要 npm。
7. 将归档安全解压到按源码提交、平台、架构和运行时树摘要命名的应用本地数据缓存；首次物化时会重新计算树摘要，缓存使用 .complete 标记并检查清单、入口和完成标记后复用，更新时保留旧版本缓存以便回滚。
8. 通过受支持的系统 Node.js 或应用本地校验后的 Node.js 直接执行缓存中的 @deepseek-ai/dsh/lib/bin.js，不调用 npm、PATH 中的 dsh、全局安装、npm/npx 缓存或 registry。
9. 启动内嵌 DSH 前会检查已经运行的 desktop DSH 进程及其 DSH_HOME；如果确认占用同一目录，应用会暂停启动并显示冲突弹窗。用户可以保持旧进程运行，或仅终止弹窗列出的 DSH 进程后继续启动 Deeptop。
10. 安装包资源只读；Profile、会话、日志和设置仍写入 $DSH_HOME，然后等待 Bridge 返回 deeptop/1 的 ready 帧。

选定工作区后，桌面端会将其作为 session.create({ cwd }) 的工作目录传给 DSH；它不会把桌面项目目录隐式当成所有会话的工作区。Storage、Session Persistence 和 Profile 数据仍由 DSH 按自身配置管理。

开发环境

要求：

- Node.js 22.21+ 或 24+；
- Rust/Cargo，以及 Tauri 所需的 Windows 桌面开发环境；
- Node.js 位于 PATH 中（npm 仅用于开发依赖安装，不参与安装包运行时）；
- 首次构建内嵌 DSH 运行时需要访问 npm registry，或构建机已准备好 DSH 源码依赖缓存；运行中的安装包不访问 registry；
- Windows 运行时需要可用的 WebView2 环境。

安装依赖：

npm install

启动完整桌面应用：

npm run tauri:dev

只预览 React/Vite 前端：

npm run dev

浏览器预览不包含 Tauri Bridge，因此 DSH、会话和原生目录选择不可用；它适合检查布局和组件，不代表完整运行时验证。

构建与测试

从固定 vendor/dsh 提交生成并校验内嵌运行时
npm run dsh:sync
npm run dsh:verify

TypeScript 检查并构建 Vite 前端
npm run build

构建 Tauri 应用
npm run tauri:build

Bridge 路由和 Skill 来源测试
npm run test:bridge

全量 JavaScript 测试
npm test

检查所有应用清单版本一致
npm run version:check

npm run build 实际执行 tsc --noEmit && vite build；npm run tauri:dev 会按 Tauri 配置先启动 Vite，npm run tauri:build 会构建原生应用和已启用的 bundle。准备发布时使用 npm run version:set -- 0.2.0，它会同步更新 npm、Bridge、Tauri 和 Cargo 清单。每次修改至少运行 npm run build 与 npm test；修改 Bridge 或重试逻辑时同时运行对应专项测试。

内嵌 DSH 来自 vendor/dsh 子模块锁定的 DeepSeek Harness 提交；构建脚本会先构建 Host 产物，再按 pnpm-lock.yaml 部署生产依赖，生成无 workspace 链接的压缩 dsh-runtime.tar.gz 资源和配套清单。校验器会比对归档内外清单、重新计算最终归档的运行时树摘要，并真实加载启动必需模块及其原生依赖。升级 DSH 时应更新子模块指针、运行时清单，并重新验证归档、缓存解压、Profile、ApiProxy 方法、Remote 契约和事件投影。

扩展 Deeptop Profile

用户自定义 DSH 能力应优先加入 Deeptop Profile，而不是直接改 Rust 启动器或 React 领域逻辑。Deeptop Profile 的用户补丁位置是：

$DSH_HOME/profiles/deeptop/cordis.patch.yml

示例：加入一个本地 Cordis 插件（路径必须是绝对路径）：

- insert:
- id: my-plugin
name: 'C:/absolute/path/to/my-plugin/src/index.ts'

插件最小形式：

import type { Context } from "@deepseek-ai/cordis";

export const name = "my-plugin";

export function apply(ctx: Context) {
ctx.on("session/event", (event) => {
console.log("session event", event);
});
}

建议的扩展顺序：

1. 先检查 DSH 官方包是否已有 Host/Cordis、ApiProxy、Remote 或 Projection 能力。
2. 有 Host 能力时，把插件加入 Profile 并复用其服务，不在桌面端重新实现领域逻辑。
3. 有 Remote/Projection 时，在 src/lib/desktop.ts 声明最小类型，通过 desktopClientRuntime 接入。
4. 只有 WebUI Client UI 时，用原生 React 实现桌面入口，不直接加载 WebUI Client bundle。
5. 新增 Bridge 路由时，必须加入 cordis/desktop-bridge/routes.mjs 的显式 allowlist，并补充测试。

不要直接编辑运行时生成的 $DSH_HOME/profiles/node_modules/deeptop-bridge 内容；重启时这些文件会由应用重新物化。需要持久化用户扩展时，请改 Deeptop Profile 的 cordis.patch.yml。

兼容边界与已知缺口

Deeptop 的目标是“功能和契约兼容，界面和生命周期原生化”，而不是复制官方 WebUI 的全部实现。当前仍在完善的方向包括：

- Plan chip、结构化 Plan Review 和更完整的 Permission 入口；
- 完整 Session Stats 展示与 ZIP 原生流式下载；
- Provider/插件的 Schema 驱动设置表单；
- 递归 Subagent、GoalBar、Workflow 成员导航和更多领域工具卡片；
- 长会话虚拟化、数学公式、附件画廊、Lightbox 和中英文资源。

明确不安排（除非未来单独引入 WebUI compatibility mode）：

- window.__ModuleLoader__；
- Cordis client runner、WebUI client context 和客户端插件生命周期；
- WebUI slot registry、动态加载官方 Client bundle；
- 为了视觉一致而引入 WebUI layout、primitives、locale 和浏览器专用下载控制器。

完整状态以 PLUGIN_COMPATIBILITY.md 和 WEBUI_PARITY.md 为准。

常见问题

找不到 Node.js

Deeptop 通过系统 PATH 中的 Node.js 直接执行安装包内嵌的 DSH JavaScript；npm 不参与安装包运行时。系统未安装兼容版本时，Deeptop 会自动下载并校验官方 Node.js 22.21.1，只把可执行文件写入应用本地缓存，因此通常无需手动安装。自动配置失败或你希望使用自己的 Node.js 时，请安装 Node.js 22.21+ 或 24+，确认启动 Deeptop 的进程继承了正确的 PATH，然后重试。

DSH 启动失败或停留在“正在启动”

打开运行时 Inspector 查看 DSH 状态和诊断信息，确认 DSH_HOME 可写、安装包的 dsh-runtime.tar.gz 与 dsh-runtime-manifest.json 完整，应用本地数据中的版本缓存已生成且包含 DSH 入口，Deeptop Profile 的 JSON/YAML 没有被破坏。修改 Profile 后可通过应用的刷新运行时操作重新启动 DSH。

浏览器预览没有会话

这是预期行为。只有 npm run tauri:dev 启动的 Tauri 窗口才拥有 Rust Bridge 和 DSH 子进程。

修改了插件但没有生效

确认修改的是 $DSH_HOME/profiles/deeptop/cordis.patch.yml，而不是生成的 profiles/node_modules/deeptop-bridge/cordis.patch.yml；然后刷新 DSH 运行时。插件依赖、Profile 注入顺序和 Host 错误可在 Inspector/诊断信息中检查。

排查崩溃或请求失败

打开 设置 → 日志。运行时、Bridge 与前端错误的堆栈会带时间戳显示；点击「刷新」可从桌面宿主回填历史日志，「打开日志目录」可查看 $DSH_HOME/logs/deeptop.log，「导出日志」可生成带时间戳的日志快照文件用于分享。

项目结构

src/                       React 桌面界面、状态模型和原生运行时适配
src/components/            会话、设置、运行台和交互组件
src/app/                   会话/消息/轨迹/事件等领域状态模型
src/lib/desktop.ts         Tauri Bridge 类型与请求封装
src/lib/desktop-client-runtime.ts
Remote loopback 和 Host 事件订阅
src-tauri/src/main.rs      DSH 子进程、Profile 物化和 JSONL 管理
src-tauri/                 Tauri 配置与 Rust 工程
cordis/                    按插件独立分目录的 Cordis Bundle、路由和测试
docs/                      项目手册与 DSH 原生协调说明
ARCHITECTURE.md            依赖方向与插件化规则
PLUGIN_COMPATIBILITY.md    插件兼容分层与工程清单
WEBUI_PARITY.md            WebUI 对齐状态与缺口

贡献前检查

- 不把 WebUI Client bundle 当作桌面依赖直接加载；
- 不在 React/Rust 中复制 DSH 的会话、权限、Agent 或插件领域逻辑；
- 新 Bridge 方法保持显式 allowlist、参数校验、错误和取消语义；
- 覆盖历史恢复、实时事件、插件缺失、错误、取消和快速切换 Session；
- 运行 npm run build 及相关测试，并同步更新兼容文档。

许可证

Deeptop 以 MIT 许可证 开源发布，版权所有 © 2026 Sparrived。