# deepseek-harness-desktop

> 为 DSH Web GUI 复刻 AionUi 右侧面板：Explorer 文件树与 Git 变更、Preview 多格式预览、按项目隔离的面板宽度持久化。

## Metadata

- Author: [@ningbainb](https://github.com/ningbainb)
- Repo: <https://github.com/ningbainb/deepseek-harness-desktop.git>
- GitHub: [ningbainb/deepseek-harness-desktop](https://github.com/ningbainb/deepseek-harness-desktop)
- Stars: 156
- Language: TypeScript
- License: [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
- Homepage: <https://ningbainb.github.io/deepseek-harness-desktop/>
- Topics: `ai-agent`, `ai-coding-assistant`, `codex`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `electron-app`, `gui`, `open-source`, `plugin-system`, `plugins`, `remote-access`, `skills`, `ssh-client`, `windows`, `windows-desktop`
- Forks: 5
- Open Issues: 6
- Last push: 2026-08-20T05:29:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-aionui-panel
```

## Wiki

## 一句话定位
dsh-aionui-panel 是 DSH Web GUI 聊天区右侧的两块面板：Explorer 提供文件树、按文件名搜索、Git 变更的 stage / unstage / discard；Preview 提供 markdown / 代码 / 文档 / 图片 / PDF 等 10+ 格式的多 tab 预览，并支持面板宽度按项目隔离持久化。它把 AionUi 的右侧面板（Apache-2.0 参考实现）按官方 SDK 重新实现，数据源走宿主进程托管的真实文件系统与真实 git 仓库。

## 核心能力
- Explorer 文件树：点击文件在 Preview 打开，整行点击展开/折叠文件夹，顶部按文件名搜索（150ms 防抖、跳过 .git 与 node_modules、命中上限 200 条、扫描上限 20,000 项）。
- 拖拽文件到聊天输入框：文件树行可拖到输入框松手，相对路径插入当前草稿光标处；拖拽过程中输入框上方出现高亮提示条。
- Git 变更面板：读取真实 git status（porcelain v1 -z）并支持 stage / unstage / discard；untracked 走删除、tracked 走 restore、批量放弃弹确认。
- Preview 多 tab 预览：markdown / html / code / diff / csv / pdf / word / excel / ppt / 图片 / 文本 / url；支持源码/预览切换、分屏编辑（比例持久化）、保存（mtime 冲突检测）、下载、刷新、dirty 点、中键关闭、右键批量关闭（dirty 确认）、tab 溢出渐变指示器。
- 面板宽度可拖拽调整（rAF 帧合并）：Explorer 默认 260px / 范围 220~500px；Preview 默认 480px / 范围 340~1200px；双击把手复位默认宽度；两级钳位保证聊天区 >= 360px；折叠 = 宽度缩 0 但组件保持挂载，树展开态与预览 tab 不丢失。
- 偏好按项目隔离持久化：localStorage 键名沿用 AionUi（`chat-workspace-width-px`、`chat-preview-width-px`、`preview-panel-split-ratio`、`project-panel-collapse:<root>`、`explorer-ui:<root>`、`scm-ui:<root>`、`preview-ui:<root>`），LRU 上限 12 个 scope，非法值范围校验后回退默认。

## 技术实现
- **语言**: TypeScript（ESM；host 与 browser 半区分层编译）
- **关键依赖**: `@deepseek-ai/cordis`（host 半区插件运行时）、`@deepseek-ai/dsh-client-runtime` / `@deepseek-ai/dsh-client-locale` / `@deepseek-ai/dsh-client-ui-conversation`（browser 半区注入）、`@linxin666/dsh-desktop-client`（仅在 Desktop 运行时提供"在系统应用中打开"动作，可选依赖）、`react ^18.2.0`（UI 渲染）
- **架构模式**: Cordis 双半区插件 — `src/index.ts` 是 host 半区（Node 进程：fs/git 服务 + /aionui-panel/* 路由 + systemPrompt 公告），`src/client/index.ts` 是 browser 半区（Web GUI 侧：状态核心 + 拖拽引擎 + DOM 布局控制器 + React 组件），`src/core/types.ts` 是两侧共享的纯类型；`cordis.patch.yml` 把插件行插入 web profile 名单，`package.json#dsh.client` 声明浏览器注入与 `platform: "web"`
- **入口文件**: `src/index.ts`（host 半区入口）、`src/client/index.ts`（browser 半区入口）、`src/host/routes.ts`（/aionui-panel/* 路由层，含 loopback fence 与 SSE）、`src/host/gate.ts`（workspace gate）、`src/host/fs-service.ts` / `src/host/git-service.ts`（fs / git 数据服务）

## 适用场景
在 DSH Web GUI 里开项目会话、想让 LLM 直接看到/改真实仓库文件的用户：聊天时让 agent 读 `.ts` 看 `.yaml`，或人工点开几个文件对照草稿。如果你已经在 `dsh web` 上跑 DSH、但觉得"只能打字给 agent"不够直观、希望有 VS Code 那种右侧项目浏览器感，这一插件就是补这一块的。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 运行时 | >=0.1.0-rc.7 <0.2.0 | package.json#dsh.compatibility.runtime.range 显式声明（packages/dsh-aionui-panel/package.json:29-31） |
| DSH Desktop | >=2.7.0 <3.0.0 | package.json#dsh.compatibility.desktop.range；"在系统应用中打开"动作依赖 Desktop 运行时（packages/dsh-aionui-panel/package.json:24-28） |
| Node.js | ^22.19 \|\| >=24 | 包级 package.json 未独立声明 engines；根 package.json#engines 全仓统一为 `^22.19 \|\| >=24`（仓库根 package.json） |
| 平台 | 跨平台（macOS / Windows / Linux） | browser 半区 + loopback-only HTTP 路由，浏览器加载使用 `platform: "web"`；host 半区 path 处理在 win32 上做大小写无关、分隔符无关的规范化（packages/dsh-aionui-panel/package.json:46-53、src/host/gate.ts:28-46） |
| 原生模块 | 无 | 仅依赖 Node 标准库（`node:fs`、`node:http`、`node:path`、`node:fs/promises`）与官方 SDK；没有 koffi / node-pty / node:sqlite 等原生绑定 |

## 安装方式
```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-aionui-panel
```

安装后重启 `dsh web`，打开一个有工作目录的项目会话即可看到聊天区右侧的"预览"与"文件/变更"面板。

## 配置项
本插件无需 DSH 侧配置（无 cordis Schema 或 ctx.config 暴露项）。浏览器侧的"用户偏好"——面板宽度、折叠态、Preview 分屏比例、tab 顺序——由本插件自己写到 localStorage，按 project root 隔离，无需用户手工配置。

## 常见问题

**Q: 这个插件装上后能看到什么？**

A: 在 `dsh web` 打开的项目会话中，聊天区右侧会多出两块面板：Explorer（文件树 + Git 变更 tab）与 Preview（多 tab 文件预览）。文件树拖到聊天输入框即可把相对路径插入草稿光标处，无需手敲路径。

**Q: 文件预览支持哪些格式？**

A: markdown / html / code / diff / csv / pdf / word / excel / ppt / 图片 / 文本 / url 共 10+ 种格式，支持源码/预览切换、分屏编辑、保存（含 mtime 冲突检测）、下载、刷新、dirty 点、中键关闭、右键批量关闭。

**Q: 必须用 DSH Web GUI（profile=web）才能看到这个插件吗？**

A: 是。`cordis.patch.yml` 把插件行插入 web profile 名单，`package.json#dsh.client.platform` 字段也是 `web`；CLI 模式（headless profile）下浏览器半区不会加载。

**Q: 数据是真的文件系统还是 mock？**

A: 真实。宿主进程经 /aionui-panel/* HTTP 路由提供目录列举、文件读、写、文件名搜索、git status / diff / stage / unstage / discard；递归 fs.watch + 每 30s 一次的 git 轮询组成 SSE 变更流。

**Q: 我能在另一台机器上访问 dsh web 来用这个插件吗？**

A: 不能。所有 /aionui-panel 路由都强制仅 loopback：非 127.0.0.1/::1 客户端立刻收到 `403 forbidden: loopback-only`，与 dsh-ssh 同款 fence。LAN 暴露的 dsh web 不会向未配对设备泄露任何 fs/git 操作。

**Q: 工作区路径不在已注册 workspace 里会被怎么处理？**

A: 直接拒绝。所有请求的 project root 都过 workspace gate：realpath 规范化后必须落在 `ctx.workspaceRegistry.list()` 返回的某个 workspace 内或其子目录；越界返回 `workspace-unknown`，路径穿越返回 `path-outside-root`。

**Q: 我没装 git 二进制能用吗？**

A: 文件树和预览完全可用。git 轮询探测一次后判定不可用即打日志并下发 `gitUnavailable` 事件，SCM tab 进入友好的"未安装 git"状态而不再每 2 秒重试 spawn。

**Q: 面板宽度、折叠状态会保存吗？**

A: 按项目隔离保存到 localStorage，键名沿用 AionUi 命名；LRU 上限 12 个 scope，超出最久未用被淘汰；读取一律范围校验，非法值回退默认。

## 上手难度
入门 — 安装 + 重启 `dsh web` + 打开项目会话即用；面板宽度、折叠、Preview 行为都是所见即所得，无需阅读文档。

## 已知问题与限制
- 所有 /aionui-panel/* 路由（含 JSON 操作、raw 读取与 SSE 事件流）都强制仅 loopback，LAN 客户端会被立刻拒绝（src/host/routes.ts:70-96）。
- 工作区 gate 要求请求路径必须在 ctx.workspaceRegistry 注册的 workspace 内；未注册或路径穿越一律拒绝（src/host/gate.ts:55-74、src/host/fs-service.ts:51-80）。
- 文本读取上限 80k 字符、图片读取上限 8MB（src/host/fs-service.ts:29-33）；文件名搜索命中上限 200 条、扫描上限 20,000 项，跳过 `.git` 与 `node_modules`（src/host/fs-service.ts:35-38）。
- Preview 拖文件到输入框仅作用于文件行；目录行不可拖（README.md:30）。
- localStorage 偏好持久化 LRU 上限 12 个 project root scope，超出最久未用被淘汰（README.md:39）。
- git 轮询探测一次后判定机器无 git 二进制即标记不可用，后续仅 fs.watch 触发刷新；SCM tab 进入友好态但不再每 30s 重试（src/host/routes.ts:172-185）。
- 仅当宿主为 DSH Desktop 时，Preview 工具栏"在系统应用中打开"按钮才可用；普通 `dsh web` 浏览器侧点击该按钮会提示"无法在系统应用中打开此文件"（src/client/preview/open-external.ts:14-31）。
- package.json#dsh.compatibility.runtime 锁在 `>=0.1.0-rc.7 <0.2.0`，与上游 `@deepseek-ai/*` SDK 的 rc 版本强绑定；DSH 升级到非兼容版本时需等待插件同步发版（packages/dsh-aionui-panel/package.json:29-31）。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-desktop](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-aionui-panel)
Wiki generated by AI (model: `MiniMax-M3`)