Elevator14B/vscode-dsh-sidebar

DSH 侧边栏

ci
release
license

将 DeepSeek Harness（DSH）Web 代理嵌入 VS Code
侧边栏 webview 中，并固定到当前工作区文件夹。它驱动的是你自己安装的开源 dsh CLI。

- 维护者： @Elevator14B
- 环境要求：VS Code 1.96+、DSH 0.1.5-rc.1 或更高版本（已用 0.1.5-rc.2 测试）、宿主机 PATH 中的 Node.js 22+。这些 CLI 版本属于文档说明，而非硬性门槛：扩展会直接启动所配置的命令，并报告其行为。

该扩展会启动一个 DSH Web 运行时（dsh web），以第一个 VS Code 工作区文件夹作为其工作目录，将经过身份验证的页面代理到侧边栏 webview 中，并在两端之间建立桥接：页面自带的侧边栏被替换为 VS Code 文件夹，而文件/差异导航、引用芯片、会话树和主题都原生地运行在 VS Code 中。

功能

- 工作区 = VS Code 文件夹。 没有工作区选择器：DSH 工作区固定为你当前打开的文件夹，会话切换在原生 VS Code 树中进行。
- 原生会话树。 以与 Web 侧边栏相同的顺序和相同的标题列出固定工作区的会话，并提供“新建会话”和刷新操作。将一行拖到另一行上可移动它，或使用其上下文菜单中的 上移会话 / 下移会话 / 归档会话；两者都通过 Web 侧边栏自身的 Workspace RPC 进行，因此顺序和归档状态在两个界面之间保持共享。
- 原生文件和差异导航。 对话中的 read / write 工具路径会在 VS Code 中打开文件；edit 工具路径会打开一个 工具变更差异（old_string → new_string，独立于 git）。收尾轮次生成的文件芯片和交付卡片也会在编辑器中打开，卡片的折叠箭头提供 在编辑器中打开、在侧边打开 和 在资源管理器中显示 —— 宿主机的桌面应用程序永远不会成为目标，这正是这些卡片在 Remote-SSH 上可用的原因。
- 链接在 VS Code 内部打开。 对话中的 URL 会在内置的 Simple Browser webview 中打开，并以操作系统浏览器作为回退。
- 拖拽引用。 将编辑器标签页、资源管理器行或兼容的原生拖拽项拖到侧边栏中，即可插入一个 @path#Lx-Ly 引用芯片。当被拖拽的文件是活动编辑器且具有非空选区时，该芯片引用该确切范围；否则引用整个文件。每次拖放都会报告
- 发生了什么：芯片已插入、拖拽的文本已放入编辑器，或有一条警告说明失败原因。
- 从键盘引用。 ctrl+alt+d / cmd+alt+d 引用当前选区，或在没有选区时引用光标所在的代码块。
- 右键引用。 从编辑器和资源管理器上下文菜单中的 Reference Selection in DSH、Reference Code Block in DSH 和 Reference File in DSH。
- 复制在页面内可用。 页面的复制按钮和复制快捷键通过扩展宿主的剪贴板写入，而不是嵌套框架的 navigator.clipboard，后者会被浏览器拒绝。
- 主题跟随 VS Code。 浅色/深色跟随 workbench.colorScheme，实时生效，且不会触碰共享的 DSH 设置文档。
- 仅本地运行时。 每个窗口都有自己的回环代理；浏览器会话认证 cookie 在扩展宿主中生成并保存，永远不会到达客户端浏览器。

要求

- VS Code 1.96+
- 托管该文件夹的机器 PATH 上需要有 Node.js 22+（支持 Remote-SSH 和容器）：dsh 是一个 Node CLI，会在那里找到的任意 node 下运行，而不是 VS Code 自带的 Node。
- 扩展宿主的 PATH 上需要有 DeepSeek Harness：

npm install -g @deepseek-ai/dsh

扩展会直接启动配置的命令——没有预检版本检查。无法提供 dsh web 服务的 CLI 会在 Agent 视图的启动页面以及 DSH Sidebar 输出通道中以其自身的消息失败。参见兼容性。

安装

目前还没有 Marketplace 上架——请从 Releases 安装 VSIX：

code --install-extension dsh-sidebar-.vsix

对于 Remote-SSH，请在服务器上安装（扩展运行在文件夹所在的位置）：

~/.vscode-server/bin//bin/code-server \
--install-extension dsh-sidebar-.vsix \
--force --extensions-dir "$HOME/.vscode-server/extensions" \
--server-data-dir "$HOME/.vscode-server/data"

然后打开活动栏中的 DSH Sidebar 图标（或运行 DSH Sidebar: Open Agent）。

从源码构建

npm ci
npm run typecheck  # extension host types
npm test           # unit tests (node --test, no extension host needed)
npm run smoke      # contract test against a real dsh on PATH
npm run build      # bundles dist/extension.js and dist/bridge.js with esbuild
npm run package    # builds and produces dsh-sidebar-.vsix

在 VS Code 中按 F5 启动扩展开发宿主。

兼容性

DeepSeek Harness 处于开发者预览阶段，确实会发布破坏兼容性的变更。0.1.5-rc.2 是经过测试的 CLI，0.1.5-rc.1 是文档中记录的最低版本；两者都未被强制执行。该扩展不再探测 dsh --version（没有 src/dsh-version.ts），也绝不会在启动 CLI 之前拒绝它。
| dsh-sidebar | DeepSeek Harness | 备注 |
| --- | --- | --- |
| 0.4.0 | 0.1.5-rc.2 已测试，0.1.5-rc.1 已记录文档 | 直接 CLI 启动，无版本门控；单一 Extension Host 连接阶梯，在全新的转发授权上重建页面。 |
| 0.3.14 | 0.1.5-rc.2 已测试，0.1.5-rc.1 为最低要求 | Extension Host 所有权、页面连接恢复以及历史超时反馈。 |
| 0.3.12 | 0.1.5-rc.2 已测试，0.1.5-rc.1 为最低要求 | 较新的 CLI 会在输出通道中给出警告后启动；较旧的则会被拒绝。 |
| 0.3.11 | 0.1.5-rc.2 已测试，0.1.5-rc.1 为最低要求 | 在 GitHub 上的首个公开发布版本。 |

此构建所使用的协议——启动 URL 及其一次性令牌、session/list 客户端请求
信封、workspace/ 顺序与归档变更、启动图以及侧边栏插件标识——并非
冻结的公共 API。当 DSH 版本
更改它时，npm run smoke 和 CI 契约任务会最先捕获到。

设置

| 设置 | 默认值 | 用途 |
| --- | --- | --- |
| dsh.embed.command | （空）* | 覆盖用于启动运行时的可执行文件；为空则使用 PATH 中的 dsh。 |
| dsh.embed.args | [] | 覆盖传递给运行时的完整参数列表。 |
| dsh.embed.workspaceFolder | （空） | 要固定的工作区文件夹路径；默认为第一个文件夹。 |

命令

- DSH Sidebar: Open Agent
- DSH Sidebar: Recover Connection（Agent 标题栏图标；立即运行连接阶梯）
- DSH Sidebar: Restart Agent Runtime (Interrupts Running Tasks)（命令面板）
- New Session / Refresh Sessions（Sessions 树标题栏）
- Move Session Up / Move Session Down / Archive Session（会话行上下文菜单；将一行
拖到另一行上可直接重新排序）
- Reference Selection in DSH / Reference Code Block in DSH（编辑器上下文菜单）以及
Reference File in DSH（资源管理器上下文菜单）

架构

- src/runtime.ts — 拥有一个可取消的后端代际与窗口代理，在 Extension Host 内用一次性
启动令牌换取浏览器会话 cookie，并按需将代理重新绑定到全新的
回环授权（rotateOrigin）。
- src/runtime-guardian.ts — 在独立进程中启动并监督配置的命令，不进行
dsh --version 探测，监视所属 Host 的 IPC 连接，并在该 Host 退出时回收 DSH，
包括异常终止的情况。
- src/runtime-ownership.ts / src/process-tree.ts — 在清理完成前保留工作区，并
终止私有进程组以及观察到的 Linux 后代进程。
- src/proxy.ts — 回环反向代理（HTTP + WebSocket），注入认证 cookie，将
启动主题重写为 VS Code 主题，提供注入的桥接脚本，并在页面
必须重建时绑定新端口（relisten）。
- src/bridge.js — 注入到页面中：从启动图中提取 DSH 侧边栏，固定工作区，
拦截工具路径链接、投递卡片和拖放引用，通过页面自身的 ThemeRuntime 驱动主题，并为原生树中继工作区顺序和归档集。
- src/connection-recovery.js — 注入到页面中：报告 DSH 自身的 connection.state 并响应宿主的 reconnect-page 请求；它不拥有任何定时器或阈值。
- src/recovery-shell.js — 本地 webview 外壳：每三秒报告一次 shell-alive，中继消息，并渲染宿主的本地化状态横幅。
- src/session-panel.ts — 原生 TreeDataProvider，通过代理读取 session/list，按照页面发布的手动顺序且不包含已归档的行。
- src/session-actions.ts — 树的重排序和归档操作背后的 Workspace RPC，以及拖放控制器使用的纯顺序规划辅助函数。
- src/extension.ts — webview 外壳、消息中继、文件/差异提供程序、命令界面以及单一连接维护阶梯。

运行时生命周期

SSH 断开连接时，只要其 Extension Host 仍然存活，DSH 就会继续运行。重新连接到该 Host 会复用后端。替换或退出 Host 会停止其 DSH；新的 Host 会启动新的后端，并且可以恢复已持久化的对话，但不会继承正在进行的执行。生命周期更长的 VS Code Server 并非所有者。隐藏侧边栏对后端没有影响。

在同一网络命名空间中，每个操作系统用户只能有一个 Sidebar 运行时拥有规范工作区。替换者会等待旧进程清理完成；该工作区上的另一个活动窗口会收到所有权错误，而不是启动一个竞争的写入者。请使用拥有所有权的窗口，或在重试前将其关闭。

从 0.3.12 首次升级时，请先完成或取消工作，并在重新加载前停止旧运行时。现有的未受保护进程无法被自动接管。后端端口被占用时会报告，而不是静默选择随机端口。不要删除 session.lock 文件来解决所有权问题。

有关关闭保证、平台限制和测试，请参阅运行时生命周期。

故障排除

如果启动失败，Agent 视图会显示一段简短、可选择的诊断信息。它没有按钮：扩展会自动重试启动，DSH Sidebar 输出通道会携带完整的运行时输出，包括 CLI 自身的失败消息。

- 启动页面指明 CLI 失败 — 扩展会直接启动配置的命令，因此无法提供 dsh web 服务的 CLI 会报告自己的消息。使用 dsh.embed.command / dsh.embed.args 指定自定义启动器，或通过 npm install -g @deepseek-ai/dsh 升级 dsh。
- “failed to start dsh” — dsh 不在扩展主机的 PATH 中。使用 dsh.embed.command 指定显式路径，或在托管该文件夹的机器上全局安装它。
- 连接断开后历史记录停留在“Loading history…” — Agent 视图横幅会渲染
扩展宿主的连接状态（重连、重建页面、启动运行时、等待远程连接），同时连接阶梯会自动修复页面；横幅上没有按钮。运行 DSH Sidebar: Recover Connection 可立即重建页面。修复过程绝不会重发消息，且只有在多次重建均无法连接后才会重启正在运行的 agent，因此在重发未确认的提交之前请先检查历史记录。
- 诊断 — 每个窗口都会向 ~/.dsh/vscode-embed/telemetry.jsonl 写入一条 JSONL 追踪记录，并在其旁边发布 current.json（最近激活的窗口）；追踪行包含宿主 PID、工作区和运行时标识，而页面事件则携带其页面标识。该文件中的端口在回环地址上响应 /status、/logs、/ping 和 /restart。

/status 响应还包含最新的 shell 心跳和最近追踪的事件。周期性心跳保留在内存中；只有状态变化才会进入追踪记录。有关时序和验证，请参阅页面恢复。

隐私

该扩展不上传任何内容。它将自己的 JSONL 追踪记录写入 ~/.dsh/vscode-embed/ 下，仅将其代理和诊断服务器绑定到 127.0.0.1，并且从不向任何其他主机发送自己的请求：它唯一通信的网络对端是它启动的 DSH 进程。点击对话中的链接会打开 VS Code 的 Simple Browser，后者随后会像任何浏览器一样加载该 URL。它运行的外部进程只有你安装的 dsh CLI 和 git，后者用于在对话请求与 HEAD 进行差异比较时读取文件的 HEAD 内容。

许可证

MIT © 2026 Huanqi Cao。这是一个为 DeepSeek Harness 开发的社区扩展，该项目由 DeepSeek AI 维护。