dsh-workspace-dir

一个 DeepSeek Harness 插件:在会话头部加一个 "📁 目录" 按钮,点一下就能弹出 当前对话工作目录的文件/子目录列表——不用切出 harness,边写代码边看项目结构。

点击后你会看到:一个可拖动的浮动面板,列出当前工作目录下的文件和子目录, 支持点击进入子目录,还能用滑杆调整面板背景透明度(0%–100%,默认 20%);每个 文件夹旁有 "↗" 按钮,一键在系统文件管理器中打开它。面板的位置、透明度、 打开/关闭状态都会自动记忆,重启 harness 也不会丢;所有可点击区域有悬停高亮与 按下缩放反馈(高亮度随面板透明度自适应)。

功能一览

• 会话头部"目录"按钮(Feather 风格文件夹图标 + 中文文本)
• 浮动目录面板:可拖动(拖标题栏)、透明度可调(滑杆 0%–100%,默认 20%)、位置/透明度/打开状态自动记忆(重启不丢)
• 点击反馈:所有可点击区域(目录行/↗ 按钮/关闭按钮)悬停高亮 + 按下缩放;高亮度随面板透明度自适应(≤50% 时 +20%,>50% 时 −20%)
• 显示当前会话工作目录 + 文件/子目录列表,缩进分层、支持下钻
• 在系统文件管理器中打开当前文件夹或任意子文件夹(Windows 资源管理器 / macOS Finder / Linux 文件管理器,自动适配)
• 切换会话自动跟随新会话的工作目录;无工作目录的会话不显示

快速开始(最正规,一条命令装完即激活)

环境要求:本插件要求 源码运行的 harness(官方 README 推荐方式)—— npm 安装版(npx @deepseek-ai/dsh web)的 peer 依赖由源码仓库提供、npm 上不完整, 可能装不上。还需要 pnpm(装完 harness 一般已有)。

源码运行的 harness,dsh 是工作区脚本而非全局命令,需在 harness 源码目录用 pnpm dsh 调用;若你的 dsh 在 PATH 中(全局安装版),直接去掉 pnpm 前缀。

cd /path/to/deepseek-harness    # ← 你的 harness 源码目录(Windows 示例: cd D:\deepseek-harness)
pnpm dsh plugin --profile web add github:DDSG-X/dsh-workspace-dir

装完重启 harness 即生效。生效规则:

• add / remove(装/卸插件) → 必须重启 harness(loader 的 entry 表是启动时快照,只刷新会 failed to load 或 404)
• update(更新插件内容) → 刷新页面即可生效(服务端每次请求都重新读 bundle 文件)

更新 / 卸载 / 验证:

pnpm dsh plugin --profile web update dsh-workspace-dir    # 更新
pnpm dsh plugin --profile web remove dsh-workspace-dir    # 卸载
curl "http://127.0.0.1:3080/dsh-workspace-dir/list?path=<绝对路径>"   # 验证:返回 JSON 文件列表即正常
# Windows PowerShell 里 curl 是别名,请用 curl.exe:
# curl.exe "http://127.0.0.1:3080/dsh-workspace-dir/list?path=D:/your/dir"

⚠️ 本项目未发布到 npm:不要用包名安装(npm install dsh-workspace-dir、 dsh plugin add dsh-workspace-dir 会因 npm 上找不到该包而失败)。github 源直接 拉取本仓库;离线/本地开发才用 file: 指向本地克隆目录。

不想手动敲命令?对 AI 说一句话即可——见下节「安装:让 AI 帮你」。

安装:让 AI 帮你(推荐新手——本项目的安装就是为这个设计的)

本项目面向完全不熟悉它的 DeepSeek Harness 用户。 你不需要懂插件、依赖、 profile——装好它,只需要对你的 AI 说一句话:

请把 https://github.com/DDSG-X/dsh-workspace-dir 克隆到英文路径,读取项目里的 AI-INSTALL.md,按里面的步骤把 dsh-workspace-dir 插件安装到我的 harness, 并验证"目录"按钮能正常弹出面板。

AI 会自己完成:克隆仓库 → 读取安装引导(AI-INSTALL.md)→ 判断你的 harness 是源码运行还是 npm 安装 → 检测/初始化 web profile → 把插件装进 profile → 重启 harness → 验证"目录"按钮。它只会在你批准时修改你的 profile 文件; 遇到环境差异,也会按引导里的故障排查表处理,并把结果汇报给你。

引导文件 AI-INSTALL.md 为中英双语单文件(英文版在文件后半段,从 # English Guide 开始);对英文 AI 说: "Clone https://github.com/DDSG-X/dsh-workspace-dir to an English path, read the English section of AI-INSTALL.md, install the plugin, then verify the Directory button works."

备选:也可以只做 3 步(仍然让 AI 装)

1. 克隆到英文路径(目录名含中文会导致 pnpm 乱码,安装会失败):

   git clone https://github.com/DDSG-X/dsh-workspace-dir.git
   

2. 在 DeepSeek Harness 里,把克隆下来的目录设为当前工作目录(workspace) —— 这样 AI 才能读到克隆下来的 AI-INSTALL.md 并操作这个目录; 不知道怎么设置就问你的 AI,它会带你操作;

3. 对你的 AI 说:

   请读取本项目的 AI-INSTALL.md,按里面的步骤把 dsh-workspace-dir 插件安装到我的 harness,并验证"目录"按钮能正常弹出面板。

本仓库自带构建产物(lib/),克隆后无需构建,可直接安装。只有修改源码的开发者才需要重新构建。

⚠️ 本项目未发布到 npm:请不要用包名安装(如 npm install dsh-workspace-dir、 dsh plugin add dsh-workspace-dir 都会因 npm 上找不到该包而失败)。安装用 github 源(pnpm dsh plugin add github:DDSG-X/dsh-workspace-dir,一条命令装完即激活); 离线/开发场景才用 file: 指向本地克隆目录。

AI 安装效果示例

一个完全不了解插件的用户,实际体验大致是这样(实际输出会因环境和模型而异):

你:请读取本项目的 AI-INSTALL.md,把 dsh-workspace-dir 插件安装到我的
    harness,并验证"目录"按钮能正常弹出面板。

AI:
  ✅ 第 1 步 检测环境
     → 发现 harness 源码 checkout
     → 发现 web profile(已初始化)

  ✅ 第 2 步 安装插件到 web profile
     → dsh plugin add(github 源)完成,依赖已写入 profile package.json
     → reconcile 自动把插件加入 dsh.profile.bundles(无需手动补行)
     → pnpm install 完成

  ✅ 第 3 步 重启 harness 并验证
     → 重启完成,端口 3080 就绪
     → 会话标题旁出现"目录"按钮
     → 点击弹出目录面板,显示当前工作目录的文件列表
     → 拖动/透明度/关闭均正常

  安装成功!使用方式:打开任意会话 → 点标题旁"目录"按钮。
  卸载:告诉我,或按 AI-INSTALL.md 的卸载章节操作。

AI 的语言、命令风格可能不同,但流程一致:检测 → 安装 → 重启验证 → 汇报。 若某一步失败,引导要求 AI 把错误信息带回来,你可以原样转发给维护者。

安装(手动,给想自己动手/了解细节的人)

一般用户不需要看这节——AI 安装(上一节)会自动处理一切。 环境要求与快速开始相同:源码运行的 harness + pnpm(见「快速开始」)。

本插件是 out-of-tree 插件:依赖 profile 的 hoisted linker,缺失的 peer 依赖(@deepseek-ai/*、react 等)在运行时由 harness 安装提供,不需要也不 应该从 npm 单独安装。profile 的 pnpm-workspace.yaml 由 dsh 自动生成,已 含 nodeLinker: hoisted 与 autoInstallPeers: false。

第 1 步:克隆插件仓库

git clone https://github.com/DDSG-X/dsh-workspace-dir.git
cd dsh-workspace-dir

仓库已包含构建产物 lib/(宿主半 lib/index.js + 浏览器半 lib/client.js),无需构建。

第 2 步:安装到你的 web profile

用 harness 的插件管理命令添加依赖(自动写入 profile 的 package.json, 并把插件注册为 profile bundle)。推荐用 github 源,一条命令装完即激活:

# 源码运行 harness:dsh 不在 PATH,需在 harness 源码目录用 pnpm 调用
pnpm dsh plugin --profile web add github:DDSG-X/dsh-workspace-dir

⚠️ 本插件未发布到 npm——不要用包名安装(如 dsh plugin add dsh-workspace-dir 或 npm install dsh-workspace-dir 会失败)。github 源安装直接拉取本仓库; 离线/本地开发场景才改用 file: 指向本地克隆目录: pnpm dsh plugin --profile web add file:D:/path/to/dsh-workspace-dir。

本插件是 bundle 形态:package.json 声明了 dsh.bundle.patch(指向仓库自带的 cordis.patch.yml)。pnpm dsh plugin add 装完依赖后会自动 reconcile,把插件写进 profile 的 dsh.profile.bundles——不需要再手动编辑 cordis.patch.yml。

无法用 pnpm dsh 调用?也可以手动编辑 ~/.dsh/profiles/web/package.json,在 dependencies 里加 "dsh-workspace-dir": "github:DDSG-X/dsh-workspace-dir", 然后在 profile 目录执行 pnpm install,最后执行 pnpm dsh plugin --profile web install 触发 reconcile(或手动把 dsh-workspace-dir 加进 profile package.json 的 dsh.profile.bundles)。

第 3 步:重启 harness

重启 pnpm dsh web(在 harness 源码目录;或双击你的启动器)。重启后:

• 打开任意会话 → 标题旁出现 "目录" 按钮
• 点击弹出目录面板;拖动标题栏移动;滑杆调透明度;✕ 关闭

更新插件

pnpm dsh plugin --profile web update dsh-workspace-dir

github 源安装的依赖,pnpm dsh plugin update 会拉取仓库最新代码并触发 reconcile (仓库自带构建产物 lib/,无需重新构建)。若当初是用 file: 本地路径装的, 则改为在克隆目录 git pull 后重启 harness 生效。

故障排查

现象	原因	解决
按钮/面板不出现	插件未加载	检查 ~/.dsh/profiles/web/package.json 的依赖和 dsh.profile.bundles 是否都配好,然后重启
harness 启动报 duplicate loader entry id: workspace-dir	手动 patch 行与 bundle 层重复插入同一 id	删除 profile cordis.patch.yml 里的手动 workspace-dir 行(bundle 形态会自动注册,手动行会与 bundle 层冲突)
安装时报 peer 依赖版本找不到	harness 是 npm 安装版	改用源码运行的 harness(见手动安装节说明)
展开报 directory browse failed	用了旧版插件	更新到最新代码(pnpm dsh plugin --profile web update dsh-workspace-dir,或本地克隆 git pull + 重启)
面板文字不可见	旧版用错主题变量	更新代码(--dsw-alias-* 已修复)

卸载

1. 从 profile 移除依赖:pnpm dsh plugin --profile web remove dsh-workspace-dir —— 一条命令会同时移除依赖和 dsh.profile.bundles 里的 bundle 层;
2. 重启 harness。

开发

pnpm install   # 只安装构建工具(tsdown、react 类型等),不会拉 @deepseek-ai peer
pnpm build     # 构建 lib/index.js(Host)+ lib/client.js(Client)
pnpm watch     # 监听源码变更并重新构建

类型检查(tsc)需要 @deepseek-ai/* 的类型包,它们只存在于 harness 源码 仓库(部分为 vendored),不发布到 npm;如需类型检查,把本仓库作为 harness workspace 成员(packages/extensions/)并在 harness 根目录 pnpm install 后再跑 tsc --noEmit。

项目结构

src/
  index.ts              # Host 半:webServer JSON 路由 + fs 列目录
  client/
    index.ts            # Client 半:注册"目录"按钮 + 浮动面板插槽
    DirectoryPanel.tsx   # DirectoryToggle(按钮)+ DirectoryPanel(可拖动/透明度/缩进树)
lib/                    # 构建产物(入库,克隆即用)
tsdown.config.ts         # 独立构建配置(不依赖 monorepo)
pnpm-workspace.yaml      # 独立仓库设置:autoInstallPeers: false

原理

• Host 半注册 GET /dsh-workspace-dir/list?path=<abs> JSON 路由,用 fs 服务(resolve + listDir)列出文件与子目录(含类型和大小);
• Client 半从会话快照读 cwd,fetch 该路由渲染目录树;
• 挂载点 conversation.session.header.actions + shell.overlay,均 replaceRisk: none,零侵入;
• 主题用真实 token(--dsw-alias-*),与 harness 界面一致。

License

MIT