简体中文 | English

workspace-files

DeepSeek Harness (dsh) Web GUI 插件 —— 在会话界面里浏览工作区目录、查看文件内容，并结合 Git 显示行级改动（diff）。

简介

workspace-files 给 dsh 的 Web GUI 会话视图（conversation.view）加了一个「文件」标签页，与「对话」「轨迹」并列。它让你：

• 📂 浏览当前会话工作区（session 的 cwd）的目录树；
• 📄 查看文本文件内容；
• 🔀 若工作区是 Git 仓库，在文件上显示状态角标（M/A/D/R/?），并按行查看 diff。

功能特性

• 目录树浏览 —— 懒加载展开，目录优先排序，隐藏文件（. 开头）弱化显示。
• 文件查看 —— UTF-8 文本内容；二进制文件自动识别并跳过；超大文件截断并提示。
• Git 集成 —— working tree 状态角标；tracked / untracked 文件的行级统一 diff（新文件通过 git diff --no-index 对比空设备，也能显示新增行）。
• 主题自适应 —— 全程使用 DSH 主题 token（无硬编码颜色/边框），与轨迹视图观感一致，明暗主题都协调。
• 安全隔离 —— 所有文件系统访问限制在会话工作区根目录内，路径穿越返回 403。
• 优雅降级 —— 非 Git 目录、缺少 git 可执行文件、二进制/未跟踪文件，都会返回结构良好的响应；前端自动隐藏 diff 入口，退化为纯浏览。

环境要求

• 已安装并可运行 DeepSeek Harness（dsh CLI），且启用了 web profile。
• Node.js —— 具体版本要求以 dsh 为准。
• Git（可选）—— 在 PATH 上时启用 diff 功能；缺失时插件自动降级，仅浏览文件。

安装

从打包好的 tarball 安装（web profile）：

dsh plugin --profile web add ./workspace-files-0.1.0.tgz

也可以直接从 GitHub 安装：

dsh plugin --profile web add github:sqfcyily/dsh-workspace-files

安装后重新打开 dsh Web GUI，会话视图顶部会出现「文件」标签页。

卸载

dsh plugin --profile web remove workspace-files

使用

1. 打开 dsh Web GUI（默认 http://127.0.0.1:3080）。
2. 进入任意会话，在会话视图顶部选择「文件」标签。
3. 左侧目录树：点击目录展开，点击文件查看内容。
4. 若工作区是 Git 仓库：文件名右侧显示状态角标；打开文件后，右上角可在「内容 / 改动」间切换查看 diff。

工作区根目录取自当前会话的 cwd（dsh 记录的 session header），插件通过 sessionId 向宿主解析，无需手动指定路径。

安全性

• 所有文件系统访问都经 confine(root, target) 校验，确保目标落在会话工作区根内，否则返回 403。
• 符号链接按自身类型上报，但不跟随（v1 保持简单、安全）。
• 二进制文件（前 8000 字节含 NUL）不返回内容，仅返回 binary: true 标记。
• 仅暴露 GET 只读路由；不提供写入 / 删除 / 执行接口。

已验证行为

• host /api/workspace-files/session-root：按 sessionId 解析会话工作区根（读 sessionPersistence 的 header cwd）。
• host /api/workspace-files/list|read：目录列举、文件读取、路径穿越返回 403。
• host /api/workspace-git/is-repo|status|diff：仓库探测、status 解析、tracked/untracked 文件的行级 diff。
• 非 git 目录 / git 缺失：is-repo 返回 false，前端自动隐藏 diff 入口。
• 客户端 bundle 经 /plugins/workspace-files/client.js 正确下发，并出现在启动清单中。

限制与已知约束

• 尚未接入语法高亮（当前为纯文本 <pre>）。
• diff 仅统一（inline）视图，暂无并排（split）视图。
• 单层目录最多 2000 条，超大目录会截断（无分页 / 增量懒加载）。
• 符号链接不跟随。

路线图

• 语法高亮。
• diff 并排（split）视图。
• 超大目录的分页 / 增量懒加载。

本地开发

lib/ 即源码：

lib/index.js       宿主（Node）半 —— HTTP 路由
lib/client.js      浏览器（React）半 —— 文件浏览器 UI
cordis.patch.yml   web profile 补丁（插入 dual-face 行）
package.json       包清单 + dsh.bundle / dsh.client 声明

打包成可安装的 tarball：

npm pack

会生成 workspace-files-<version>.tgz，即 dsh plugin add 消费的产物。

相关链接

• DeepSeek Harness 官方仓库：https://github.com/deepseek-ai/deepseek-harness
• 社区插件常用 topic：dsh-plugin

许可证

MIT © 2026 sqfcy