deepseek-harness-desktop/packages/dsh-aionui-panel

一句话定位

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 等原生绑定

安装方式

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）。

Install