dsh-vsceditor
v0.5.3
Published
VS Code panel for DeepSeek Harness sessions — embedded code-server or your local desktop VS Code — with ACP-style edit sync, red/green diff follow mode and file locking via the bundled dsh-bridge VS Code extension.
Maintainers
Readme
dsh-vsceditor
English | 简体中文
DeepSeek Harness 内嵌 VSCode 编辑器插件 —— 在 DSH Web 界面里嵌入一个完整的 code-server(完整版 VSCode),agent 每次写文件/改文件时自动在编辑器里弹出红绿 diff 并定位到改动行,所见即所得地"看着 AI 干活"。
1. 特性
- 三态互斥后端:内嵌 / 本机 / 关闭 —— 默认内嵌 code-server;也可切换为「本机 VS Code」,跟随、diff、锁定全部搬进你自己的桌面编辑器;或切到「关闭」彻底断开(看门狗级联关闭整棵 code-server 进程树、本机扩展断链、常驻 iframe 的渲染进程内存一并释放)。编辑器工具栏的电源按钮操作的是同一个配置位,也是一键重新打开的入口
- 完整 VSCode,不是玩具编辑器 —— 内嵌的是 code-server 4.x(完整 VSCode 内核),扩展、主题、快捷键、Git 面板全部可用
- 跟随模式(follow),diff 轮次级累计 —— agent 调用
write/edit工具改文件时,编辑器自动打开该文件的红绿 diff 视图并滚动到首个改动行;DSH 侧还同时内置一个只读 diff 标签页,两边都能看。diff 按对话轮次累计:整轮改动跨标签页并存,关标签、刷新编辑器都不丢,下一轮对话开始编辑时才清场(见 5.3) - 文件锁定 —— agent 正在写某个文件期间,编辑器里该文件被锁定(防止你和 AI 同时改一个文件互相覆盖),写完自动解锁
- 不留孤儿进程 —— code-server 由看门狗进程托管:心跳发现 DSH 宿主死亡(崩溃/强杀/升级重启)后杀掉整棵编辑器进程树陪葬;启动时和每 30 分钟还会巡检收割历史残留。你自己的桌面 VS Code 和自装的 code-server 绝不会被误伤
- 工作区自动跟随会话 —— 一个 DSH 进程只跑一个 code-server;当前活跃会话的工作区变化时,编辑器自动切换到对应目录(必要时自动重启 code-server)
- iframe 常驻不重建 —— 编辑器页面固定在
<body>上、切换标签页只是隐藏/显示,不会每次点进去都新开一个 VSCode 会话 - 设置页集成 —— 「设置 → 插件 → 插件配置」里有本插件的折叠卡片:跟随开关、自动启动、端口、code-server 目录,全部即时生效并持久化(
~/.dsh/settings.yaml) - 零依赖 —— host/client 两端都是手写原生 JS,不依赖任何 npm 包;settings schema 用手写的 schemastery 兼容外形,不需要
@deepseek-ai/schemastery
2. 工作原理
┌─ DSH 进程 ─────────────────────────────────────────────┐
│ host.js(host 层 cordis 插件,进程级单例) │
│ · 监听所有会话的 tools/pre-execute、tools/result 事件 │
│ · 捕获 write/edit 的目标路径,读出改前/改后文本 │
│ · 经看门狗进程管理 code-server(心跳陪葬 + 孤儿收割, │
│ DSH 崩溃/升级后不再残留 code-server 进程) │
│ · 通过 webServer 暴露: │
│ /__dsh-vsceditor/state|action (控制面,页面用) │
│ /__dsh-vsceditor-<rand>/events (SSE → 扩展) │
│ /__dsh-vsceditor-<rand>/rpc (扩展 → host) │
└───────┬──────────────────────────────▲─────────────────┘
│ SSE: hello/follow/edit/lock/unlock/reveal
│ POST: ready/ack/log
┌───────▼──────────────────────────────┴─────────────────┐
│ code-server(独立进程,--auth none,仅 127.0.0.1) │
│ └─ dsh-bridge 扩展(vscode-ext/dsh-bridge) │
│ 收到 edit 消息 → 打开红绿 diff 并定位改动行 │
│ 收到 lock → 对应文件只读;unlock → 恢复 │
└────────────────────────────────────────────────────────┘
▲ iframe(client.js 注册到 conversation.view,
标签页「编辑器」,常驻 body 不随切换销毁)消息语义参考 ACP session/update:edit {path, oldText, newText, firstLine} 由 host 计算 diff 统计后推送,扩展负责呈现。host 以 unscoped 方式挂载,因此能看到所有会话的工具事件(scoped 事件会沿 scope 链向上流动)。
3. 前置要求
- DeepSeek Harness(dsh)web profile(本插件是 profile bundle,挂在 host 层)
- macOS 或 Linux(Windows 未测试;code-server 官方不支持 Windows 直装)
- 内嵌模式:需要一个 code-server 安装(见 4.2);本机 VS Code 模式:需要桌面版 VS Code。两者至少满足其一——不装 code-server 也能用插件,只是只能用本机 VS Code 模式
4. 安装
4.1 安装插件
方式 A:从 GitHub 安装(推荐)
dsh plugin --profile web add github:k-ying/dsh-vsceditordsh plugin add 会把包加进 ~/.dsh/profiles/web/package.json 的依赖并自动登记到 dsh.profile.bundles(本插件通过 cordis.patch.yml 自挂载,无需手工编辑组合文件)。
方式 B:本地目录安装
git clone https://github.com/k-ying/dsh-vsceditor.git
dsh plugin --profile web add /path/to/dsh-vsceditor4.2 安装 code-server(内嵌模式必需)
⚠️ 想用默认的内嵌编辑器,这一步不可跳过。 插件本体不带 code-server 运行时(约 100MB)。不装的话内嵌模式不可用——「编辑器」标签页会提示"未找到 code-server"并引导你切换到本机 VS Code 模式(功能等价,见 5.1)。
方式一:一键安装(推荐)。打开「编辑器」标签页(或 设置 → 插件配置 → 内嵌 VSCode 编辑器),点击 「⬇ 一键安装 code-server」,弹窗会显示下载地址、实时进度百分比和安装/启动进度,可随时取消,完成后自动进入编辑器。安装到 ~/.dsh-editor,所有工作区共用一份。
方式二:命令行全局安装(与一键安装等效,适合无法打开面板时):
sh ~/.dsh/profiles/web/node_modules/dsh-vsceditor/scripts/install-code-server.sh ~/.dsh-editor如果想让某个工作区用独立的 code-server,不传参数即可(默认装到当前目录的 .dsh-editor,优先级高于全局):
cd <你的 DSH 工作区> # 例如 ~/Documents/AI
sh ~/.dsh/profiles/web/node_modules/dsh-vsceditor/scripts/install-code-server.sh脚本按平台(macOS arm64/x64、Linux x64/arm64/armhf)从 code-server 官方 release 下载并解压。版本固定为 4.133.0,可用 DSH_VSCEDITOR_VERSION 环境变量覆盖。
手动安装也可以:把 code-server 解压到以下任一位置(按查找优先级):
- 设置卡片里填写的
code-server 目录(优先级最高) - 环境变量
$DSH_VSCEDITOR_HOME <工作区>/.dsh-editor(工作区级)~/.dsh-editor(全局,推荐)
目录下需存在 code-server/bin/code-server。
📁 编辑器的运行数据(user-data、配置、日志)不放在工作区里,统一存放在全局
~/.dsh-editor/workspaces/<哈希>-<工作区名>/下按工作区隔离(与 VS Code 的用户级数据目录同一范式),你的工作区目录不会被污染。旧版本曾存放在<工作区>/.dsh-editor,已存在该目录的工作区会继续沿用以保留数据。
Windows(实验性)
code-server 官方不发布 Windows 构建,且直接 npm install -g code-server 在 Windows 上是坏的(postinstall 脚本与 argon2 原生编译都会失败)。本插件提供 scripts/install-code-server.ps1 绕过这两个坑,手法参考 naspenang/code-server-windows(MIT):跳过 postinstall、手动补装依赖、从本机已安装的桌面版 VS Code 借用原生模块。
前置条件:
- Windows 10/11 + PowerShell
- 已安装桌面版 VS Code,且版本与 code-server 内置的 VS Code 完全一致(脚本会校验并报出期望版本,可用
-CodeServerVersion换 code-server 版本来对齐,或加-SkipVSCodeVersionCheck强行尝试)
cd <你的 DSH 工作区>
Set-ExecutionPolicy -Scope Process Bypass
& "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-vsceditor\scripts\install-code-server.ps1"产物布局(host 端在 Windows 下按此约定查找):
<工作区>\.dsh-editor\code-server\node\node.exe
<工作区>\.dsh-editor\code-server\runtime\node_modules\code-server\out\node\entry.js注意:此路径未经大规模验证,仅保证 127.0.0.1 本机使用。若遇到问题,WSL2 里是官方维护的 Linux 流程,体验与 macOS/Linux 完全一致,是更稳妥的选择。
4.3 启动
dsh web启动后顶栏出现「编辑器」标签页,点进去等待 code-server 就绪(首次约几秒)。标签文字旁有状态点:灰=加载中或后端已「关闭」,绿=扩展已连接,黄=等待扩展连接,红=未运行/未安装 code-server/桥接未挂载。
5. 使用
5.1 本机 VS Code 模式
在「设置 → 插件 → 插件配置」里把「编辑器后端」切到 本机 VS Code(与内嵌 code-server 互斥,切换即时生效),或直接点「编辑器」标签页状态卡片里的「连接向导」:
- 插件自动探测本机 VS Code(macOS
.app与 Spotlight、Windows 标准安装目录与where、Linux/usr/bin与which),探测不到可在设置里手动指定路径 - 未装桥扩展时,「编辑器」标签页的状态卡片会出现「安装扩展到本机 VS Code」按钮——点击后自动拷贝到
~/.vscode/extensions/(家目录,无需提权);失败时给出手动拷贝的源/目标路径 - 在桌面 VS Code 里 Reload Window,并打开与 DSH 会话相同的工作区——扩展只在工作区匹配的窗口接单,多窗口不会串台
- 之后跟随 diff、文件锁定与内嵌模式体验一致;扩展随插件版本自动更新(提示 Reload Window 即可)
原理:桌面 VS Code 无法注入环境变量,插件改为把桥接坐标(端口/token/工作区)写入 ~/.dsh-editor/bridge.json,扩展轮询该文件自动握手。同一份扩展代码两种模式自动分流,内嵌模式不受影响。
工作区信任(Workspace Trust)
桌面 VS Code 默认对新打开的文件夹启用受限模式,本插件做了完整适配:
- 桥扩展声明了
untrustedWorkspaces: limited支持——未信任的窗口也能激活并保持握手,但不会执行任何 edit/reveal 同步指令 - 此时 DSH 侧状态点显示黄色「等待信任工作区」,编辑器标签页与连接向导都会提示;扩展侧会在 VS Code 里弹一次「管理工作区信任」的引导通知
- 在 VS Code 的信任弹窗里点「信任」(或命令面板 →
Workspaces: Manage Workspace Trust)后自动恢复,无需 Reload(扩展监听onDidGrantWorkspaceTrust自动重连) - 内嵌 code-server 以
--disable-workspace-trust启动,不存在此问题
建议:DSH 工作区是你自己的目录,直接信任即可;如果会话工作区都在某个父目录下(如 ~/Documents/AI),信任父文件夹可一劳永逸。
5.2 关闭模式(断开编辑器后端)
在设置卡片把「编辑器后端」切到 关闭,或点编辑器工具栏的电源按钮(⏻,在重启按钮右边——内嵌模式显示「关闭 code-server」,本机模式显示「断开连接」)。两处操作的是同一个配置位:
- 内嵌模式:看门狗停止并 SIGTERM 整棵 code-server 进程树,零孤儿;常驻 iframe 同步销毁,释放渲染进程内存
- 本机模式:摘除
bridge.json,桌面扩展下一轮轮询自动断开 - 关闭态下任何路径都拉不起编辑器:自动启动、崩溃重试、重启定时器、安装完成拉起、工作区切换重拉全部被
startServer顶部的守卫拦截;主动关闭也不会被误记为崩溃(不弹错误、不消耗重试额度) autoStart只管 DSH 启动时的行为:关闭态即使autoStart=true也不会拉起;从关闭态切回时无论 autoStart 如何都立即启动- 关闭状态持久化到
~/.dsh/settings.yaml,DSH 重启后保持关闭 - 关闭页提供一键回开:「启动内嵌 code-server」/「连接本机 VS Code →」(自动弹出连接向导);工具栏电源按钮变为「打开 code-server」
5.3 跟随模式
默认开启。agent 每次 write/edit 落地后:
- 编辑器自动切到该文件的 diff 视图(左旧右新),并滚动到首个改动行
- DSH 标签页工具栏的「跟随」勾选框可随时开关;关掉后仍会记录最近改动(recent 列表),只是不主动弹窗
- 编辑器内也能切换:点击 VS Code 状态栏的
DSH · 跟随/编辑按钮弹出菜单(切换跟随 / 重新连接),或命令面板 →DSH Bridge: Toggle Follow Mode;扩展会把请求发回 DSH,所有端同步生效 - 只想看工作区内的改动:设置卡片勾选「仅跟随工作区内文件」,工作区外的写入只进 recent 列表,不弹 diff
- diff 是轮次级的:一轮对话内的所有改动按文件累计成 diff 标签页;关掉 diff 标签不丢状态——再编辑该文件、从资源管理器点开它、或刷新重开编辑器,都会带原基线恢复。直到下一轮对话产生首次编辑,上一轮的 diff 才整体清场
5.4 文件锁定
agent 开始写某文件时该文件在编辑器里变为只读(状态栏有提示),写完自动解锁。这是防冲突提示,不是安全边界。
5.5 设置卡片
「设置 → 插件 → 插件配置 → 内嵌 VSCode 编辑器」(默认折叠,点标题展开):
| 配置项 | 类型 | 默认 | 说明 |
|---|---|---|---|
| editorBackend | string | embedded | 编辑器后端(互斥):embedded = 内嵌 code-server;local = 本机桌面版 VS Code;off = 全部断开(见 5.2)。工具栏电源按钮操作同一配置项 |
| follow | boolean | true | 跟随 DSH 编辑:改文件时自动弹出红绿 diff 并定位改动行 |
| followWorkspaceOnly | boolean | false | 仅跟随工作区内文件:开启后工作区外的改动只记录、不弹 diff |
| autoStart | boolean | true | DSH 启动后自动拉起 code-server;关闭后需在「编辑器」标签页手动启动。只管 DSH 启动时:后端为「关闭」时不拉起,但从关闭切回时必定立即启动 |
| port | number | 0 | code-server 监听端口;0 = 随机(10000–65000);改动会自动重启编辑器 |
| codeServerHome | string | "" | 手动指定 code-server 安装目录;留空按上面的优先级自动查找 |
| vscodePath | string | "" | 手动指定本机 VS Code 路径(code CLI 或 .app/Code.exe);留空自动探测 |
| language | string | auto | 界面语言:auto = 跟随 DSH 界面语言(兜底浏览器语言);pt-BR/es 不会被自动选中(DSH 本身只有中英界面),需要时请在这里显式指定 |
| trustedHosts | string | "" | 信任的主机(逗号分隔的裸 host 或 host:port):除回环外允许访问控制接口的主机名。经反向代理/自定义域名访问 DSH 时必须声明;留空 = 仅回环。见第 8 节 |
| bridgeDebug | boolean | false | 把扩展「打开 diff」的过程写入 /tmp/dsh-bridge-debug.log。经 SSE 即时下发,无需重启 DSH 或编辑器;排查「没弹 diff」时用 |
写入即持久化到 ~/.dsh/settings.yaml 的 dsh-vsceditor 节,重启后保留。也可以在 ~/.dsh/profiles/web/cordis.patch.yml 的插件行加 config: 作为组合层 base(用户层覆盖 base 层)。
5.6 快捷键/命令
VS Code 命令面板(Cmd/Ctrl+Shift+P):
DSH Bridge: Toggle Follow Mode—— 切换跟随模式(也可以直接点状态栏的DSH按钮,菜单里有开关)DSH Bridge: Reconnect—— 手动重连桥接(一般不需要,扩展会自动重连)
6. 故障排查
「编辑器」标签页显示"未安装 code-server" / "未找到 code-server"
没装 code-server 或不在查找路径上。三个选择:⓪ 点页面上的「⬇ 一键安装 code-server」(推荐);① 运行 4.2 的安装脚本(或在设置卡片填 code-server 目录);② 不想装就点页面上的「改用本机 VS Code →」按钮,插件会切到本机模式并弹出连接向导。
本机模式一直"等待信任工作区"(黄点)
VS Code 受限模式拦截了编辑同步。在 VS Code 里信任该工作区(命令面板 → Workspaces: Manage Workspace Trust),信任后自动恢复,不用 Reload。详见 5.1 的「工作区信任」小节。
一直"等待扩展连接"(黄点) 扩展只在 code-server 窗口打开时才会启动扩展宿主。点进「编辑器」标签页等几秒;如果页面是旧的(code-server 重启过),刷新整个 DSH 页面。
改动不弹 diff
① 看标签页状态点是否绿色;② 看工具栏「跟随」是否勾选;③ 扩展日志:DSH_BRIDGE_DEBUG=1 重启 DSH 后看 /tmp/dsh-bridge-debug.log(本机模式看 ~/.dsh-editor/bridge-ext.log)。
端口被占用/想换端口 设置卡片改端口,保存后编辑器自动重启到新端口。
编辑器标签页显示「桥接未挂载」/ 设置卡片按钮点了没反应(403)
说明你访问 DSH 用的主机不在控制接口的信任范围内——反向代理、自定义域名、Tailscale MagicDNS、ngrok 等。请把该主机名声明到信任的主机(设置 → 插件配置),或 ~/.dsh/settings.yaml 的 dsh-vsceditor 节。被围栏挡住时设置卡片本身也存不了,所以这种情况请直接改文件(或插件行的 config:)。回环访问(http://127.0.0.1:<端口>)、localhost、以及本机自己的局域网地址无需任何配置即可用——详见第 8 节。
code-server 进程残留
0.5.0 起不应再出现:code-server 由看门狗(lib/cs-supervisor.js)托管,宿主死亡即陪葬;收割器在启动时、30 秒后、每 30 分钟巡检回收 PPID=1 的历史孤儿(只匹配本插件自己的安装签名)。若仍看到残留请提 issue。手动清理:pkill -f 'code-server.*--auth none'。
编辑器自己重启了 / 报错里有 cs-supervisor: host unreachable
看门狗约 60 秒连不上 DSH 宿主(比如宿主事件循环被长时间卡死),按保护逻辑关掉了 code-server。宿主发现子进程退出后会在约 2 秒内自动拉起编辑器,属于自愈;若频繁出现请提 issue。
设置 → 插件 → 插件配置 整页空白
这是本插件 0.1.x 时代踩过的坑:settings schema 缺 toJSON 会把整页拖挂。0.2.0 已修复;若仍出现请提 issue 并附 ~/.dsh/settings.yaml 的 dsh-vsceditor 节。
7. 卸载
dsh plugin --profile web remove dsh-vsceditor再删掉运行数据(可选):~/.dsh-editor(含 workspaces/ 下按工作区隔离的运行数据;旧版可能还有 <工作区>/.dsh-editor)、~/.vscode/extensions/dsh.dsh-bridge、~/.dsh/settings.yaml 里的 dsh-vsceditor 节。
8. 安全说明
- 控制接口有信任围栏(
/state、/action):Host 必须是回环、请求实际到达的本机地址、或你在信任的主机里声明过的主机;sec-fetch-site: cross-site拒绝;带Origin时必须与Host一致;写操作 POST 必须带Origin(浏览器必带,本地盲脚本不带)。set-config另外只接受已知配置键 - 非回环 socket 只能代表已声明的信任主机:浏览器之外
Host和Origin都可以伪造,socket 地址是唯一可信信号——没有这条规则,本机任意进程(或 DSH 绑到局域网时的任意局域网主机)只要声称Host: 127.0.0.1就能驱动控制面。同机通过本机局域网地址/主机名访问仍然放行,因为回环 socket 已经证明客户端就在本机 - 经反向代理 / 自定义域名 / Tailscale MagicDNS / ngrok 访问 DSH? 请把该主机名声明到信任的主机(设置 → 插件配置)、插件行的
config:,或直接写进~/.dsh/settings.yaml的dsh-vsceditor节。未声明前控制接口返回 403、编辑器标签页显示桥接未挂载——且此时设置卡片本身也存不了,只能改文件。插件同时会继承 DSH 部署层自己的trustedHosts(connection服务),部署层已声明过的主机不必重复声明 - 设置卡片保存了没反应 / 工具栏按钮点了没动静? 受围栏保护的写操作此前是静默失败。现在失败会在面板里显示一行红字(HTTP 403 会点名围栏并指向信任的主机);扩展最近一次 ack(
kind、opened、timeout、error)可从GET /__dsh-vsceditor/state的lastAck读到。opened: false, timeout: true表示 VS Code 6 秒内没确认弹出 diff;edit-error表示它抛错了,此时面板也会显示原因。需要更深排查时打开bridgeDebug,扩展会写/tmp/dsh-bridge-debug.log - code-server 以
--auth none启动,但只监听 127.0.0.1,随机端口覆盖完整的 10000–65000 段;请勿改绑到 0.0.0.0。单用户开发机上这与 DSH 自身的本地 HTTP 面威胁级相当;多用户机器上本机其它用户仍可通过回环端口扫描访问,建议改用local后端 - 桥接端点(SSE/RPC)带每次启动随机生成的 token,扩展通过环境变量拿到;
~/.dsh-editor/bridge.json保存该 token,权限为0600 - 插件不收集、不上传任何数据;code-server 启动参数带
--disable-telemetry --disable-update-check
9. 目录结构
dsh-vsceditor/
├── cordis.patch.yml # profile bundle 自挂载补丁(host 层插件行)
├── package.json # dsh.bundle.patch / dsh.client 声明
├── lib/
│ ├── host.js # host 半:进程管理、事件桥、settings 命名空间
│ ├── cs-supervisor.js # 看门狗:拉起 code-server,DSH 死亡时心跳判死并带整棵进程树陪葬
│ └── client.js # client 半:标签页 iframe、设置卡片(手写 bundle 格式)
├── scripts/
│ ├── install-code-server.sh # code-server 下载安装脚本(macOS/Linux)
│ └── install-code-server.ps1 # code-server 安装脚本(Windows 实验性)
└── vscode-ext/
└── dsh-bridge/ # 随 --extensions-dir 注入 code-server 的桥接扩展
├── package.json
├── paths.js # Windows 安全的路径处理(比较 / 解析 / 切分),平台可注入以便测试
└── extension.jsvscode-ext/extensions.json 与 vscode-ext/.obsolete 是 code-server 启动时按本机路径自动生成的运行态文件,已 gitignore。
10. 开发
改 lib/host.js / lib/cs-supervisor.js 后需要重启 DSH 生效;改 lib/client.js 只需刷新页面(bundle 路由按请求读盘);改 vscode-ext/dsh-bridge/extension.js / paths.js 后重开编辑器标签页即可(每次打开都会拉起新的扩展宿主,加载磁盘上的最新文件)。校验组合是否仍能被 profile 正确装配:
dsh --profile web --dump-config跑测试(零依赖,直接跑源码;CI 也会跑):
npm test两个用例:test/control-trust-smoke.mjs(控制面围栏 + ack + 配置不变量)、test/windows-sim.mjs(Windows 桌面模式的路径行为)。后者强制 win32 语义 + 桩化 vscode + 加载未修改的真实 extension.js,因此在 macOS/Linux 上也能复现 Windows 报告;边界与真机验证清单位于 docs/windows-path-issues.md。
版本号规范
插件(根 package.json)与桥扩展(vscode-ext/dsh-bridge/package.json)的版本号保持 major.minor 一致——例如插件 0.3.x 配套扩展 0.3.x;两者的 patch 位可独立递增。host 端会把扩展版本与插件内置版本(vscode-ext/dsh-bridge/package.json 的 version)比对,不一致时自动重新拷贝到 ~/.vscode/extensions/ 并提示 Reload Window,所以升级插件后无需手动重装扩展。
注意这条只在版本变化时才触发重拷:本地开发改了 vscode-ext/dsh-bridge/ 想在桌面 VS Code 里试,必须先把扩展 version 提一档(或手动删掉 ~/.vscode/extensions/dsh.dsh-bridge 再触发安装),否则拿到的还是旧扩展。
