# dsh-editor-link

<div align="center">
  <b>DeepSeek Harness 与你的编辑器之间的那条连接</b><br />
  在 VS Code 里回答审批与提问，并让 agent 看见你的编辑器。<br /><br />
  <a href="https://www.npmjs.com/package/dsh-editor-link"><img alt="npm" src="https://img.shields.io/npm/v/dsh-editor-link.svg"></a>
  <a href="https://www.npmjs.com/package/dsh-editor-link"><img alt="npm downloads" src="https://img.shields.io/npm/dm/dsh-editor-link.svg"></a>
  <a href="https://github.com/ferrisching/dsh-editor-link/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/ferrisching/dsh-editor-link.svg"></a>
  <a href="https://github.com/ferrisching/dsh-editor-link/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</div>

[English](README.md) | 中文

用 DSH 的现状是「两个窗口」：DSH 网页端和 VS Code。生态里已有一些碎片（选区插入、文件跳转、ACP 桥），但没人覆盖最高频的两件事：**在你已经在的地方回答审批**，以及**把编辑器上下文交给 agent**——后者是 Claude Code 用户的日常。

`dsh-editor-link` 是一个产品的两半：一个 DSH 插件 + 一个 VS Code 扩展，二者通过一条带令牌校验的本地回环 JSON-RPC 通道通信。

## 📑 目录

- [✨ 功能](#-功能)
- [🚀 安装](#-安装)
- [⌨️ 使用](#-使用)
- [⚙️ 命令](#-命令)
- [🔌 宿主路由](#-宿主路由)
- [🧩 工作原理](#-工作原理)
- [🛠️ 开发](#-开发)
- [🔐 安全与成本](#-安全与成本)
- [⚠️ 已知限制](#-已知限制)
- [📄 许可](#-许可)

## ✨ 功能

- **在 VS Code 里审批** —— 工具调用需要授权时，弹出原生通知，提供 *Allow once / Reject* 两个按钮，不用切窗口。
- **在侧边栏回答提问** —— 提问以卡片形式出现在侧边栏：单选点选即答、多选勾选后提交、也支持自定义答案；侧边栏之外不再弹 QuickPick。
- **给 agent 编辑器上下文** —— `ide_context` 工具读取当前文件、诊断（`file:line:col`）与选区。
- **选区送进 composer** —— `DSH Link: Send Selection to Composer` 把 `path:lines` 加代码块送进 DSH 输入框。
- **跳到 agent 动过的文件** —— 状态栏项可打开 agent 最近读写的文件并定位到行；网页端文件工具卡片上也有 `↗` 按钮。
- **侧边栏** —— 活动栏视图：实时转录、内联审批、可发送/插话/中断的输入框。
- **跟随工作区的会话列表** —— 按 DSH 工作区分组，并按 VS Code 当前目录限定范围；已归档与空会话隐藏；切换目录列表随之变化。
- **模型 / 思考深度 / 权限** —— 不用打开网页端即可切换会话的这三项。
- **输入联想** —— 回合结束后预测你下一条消息；一打字立即取消，`Tab` 采纳，`↻` 换一条，`Esc` 忽略。
- **标签页里的完整 DSH** —— 用带登录态的 URL 在 VS Code 标签页里打开完整网页端。

两个界面始终同步：审批与提问在网页端也会出现，**谁先回答谁生效**，后到的回答会收到明确的「已处理」错误。

## 🚀 安装

### 1. 安装 DSH 插件（推荐）

插件半运行在 DSH 内部，本包即发布到 npm。

- **图形界面**：插件页 →「添加插件」→ 填 `dsh-editor-link` → 安装。
- **命令行**：`dsh plugin --profile desktop add dsh-editor-link`

> CLI 只安装包，**不会**注册 profile bundle。需要把 `dsh-editor-link` 追加到 `~/.dsh/profiles/<profile>/package.json` 的 `dsh.profile.bundles` 才会真正加载；图形界面的「添加插件」会自动完成这一步。

### 2. 安装 VS Code 扩展

从 VS Code 商店安装：

```bash
code --install-extension ferrisching.dsh-editor-link
```

离线时也可以从 [Releases](https://github.com/ferrisching/dsh-editor-link/releases) 下载 `dsh-editor-link-extension-<version>.vsix`，再执行 `code --install-extension <文件>.vsix --force`。

然后重载 VS Code 窗口，活动栏会出现 `DSH` 视图。

### 3. 从源码构建

```bash
git clone https://github.com/ferrisching/dsh-editor-link
cd dsh-editor-link
npm install                       # 插件测试依赖（linkedom）
cd extension && npm install       # 扩展构建依赖（esbuild、@types/vscode）
```

### 环境要求

| 组件 | 要求 |
|---|---|
| DSH | 已验证 `0.2.0-rc.2`、`0.2.1-rc.1`、`0.2.1-rc.2` |
| VS Code | 1.85 及以上 |
| Node | 20 及以上（插件侧） |

## ⌨️ 使用

1. 启动 DSH，桥会自动连上；状态栏项在 agent 第一次触碰文件后出现。
2. 在活动栏打开 **DSH** 视图，会话按「包含当前 VS Code 目录」的 DSH 工作区加载。
3. 在输入框提问。工具需要授权时直接在通知里回答，网页端对应卡片同时消失。
4. 说「看一下我正在看的文件」即可通过 `ide_context` 拿到上下文；也可以选中代码跑 *Send Selection to Composer* 交出片段。

## ⚙️ 命令

| 命令 | 作用 |
|---|---|
| `DSH Link: Send Selection to Composer` | 把选区以 `path:lines` 加代码块送进 DSH 输入框 |
| `DSH Link: Open Last File Touched by the Agent` | 跳到 agent 最近读写的文件 |
| `DSH Link: Open Active Session in Browser` | 在系统浏览器里打开正在运行的 DSH 网页端 |

侧边栏工具栏另外提供模型、思考深度、权限预设、`+` 菜单（`/goal`、`/plan`、`/feedback`、`/compact`、`/export`，加文件选择与权限/模型切换）以及发送/中断按钮。

## 🔌 宿主路由

| 方法 | 路径 | 用途 |
|---|---|---|
| `GET` | `/editor-link/events` | 推给浏览器半的 SSE（`composer.insert`、`editor/reveal`） |
| `POST` | `/editor-link/open` | 文件工具卡片上 `↗` 按钮的后端：`{ filePath, line }` |

## 🧩 工作原理

- **宿主插件**（`lib/`）在 7410–7419 端口范围监听回环 TCP，并写发现文件（`~/.dsh/editor-link/<pid>.json`，权限 0600），内含端口与令牌。
- **VS Code 扩展**（`extension/`）读取发现文件，**每个 DSH 进程一条** JSON-RPC 2.0 连接并复用多路调用，用原生 UI 回答 `approval/request` 与 `user-questions/request` 瀑布事件。
- **浏览器半**（`client/`）订阅 `/editor-link/events`，给文件工具卡片加按钮；点击时经宿主回调扩展。
- 审批在多端竞争：第一个回答生效，后到的回答返回 `-32002`，不会静默成功。

## 🛠️ 开发

```
.
├── lib/                  宿主插件（桥、转发、面板 RPC、IDE 采集）
├── client/               网页端半（SSE 监听、工具卡片按钮）
├── cordis.patch.yml      bundle 补丁——`dsh plugin add` 的必要条件
├── test/                 node:test 用例（81 条）
├── extension/            VS Code 扩展（TypeScript + esbuild）
│   ├── src/              扩展宿主与侧边栏 webview
│   └── test/             运行时冒烟（vm.Script 解析 + linkedom DOM）
├── scripts/              真实 cordis 集成脚本
└── docs/                 设计、已验证 seam、验证日志
```

```bash
npm test                              # 插件用例
npm run test:extension                # 构建 + 扩展冒烟
DSH_BUNDLE_DIR=/path/to/dsh node scripts/integration-cordis.mjs   # 面向 DSH bundle 的真实 cordis 集成
```

## 🔐 安全与成本

- 桥只监听回环，每个请求都要带发现文件里的令牌，DSH 重启即轮换。
- 无遥测、无对外网络请求；仓库与发现文件里除进程令牌外不存任何凭据。
- 输入联想与会话标题会消耗模型 token：联想固定使用模型支持的最浅推理档，回复上限 80 token。

## ⚠️ 已知限制

- 同一个宿主上同时开多个 VS Code 窗口尚未验证。
- 同时运行多个 DSH 进程时，请求固定发给**最先连上的那个实例**：会话列表、审批与提问
  都归属于它。目前没有按会话在多个宿主间的路由。
- 在 VS Code 里答过的问题，DSH 网页端/桌面端仍会显示一张待答回复卡，需要在那里点关闭。
  答案本身已经记录（tool 结果与会话投影都已结算），只是客户端只在自己提交时才收起卡片。
- Windows 与 WSL 路径未验证；发现与路径逻辑按 POSIX 设计。
- SSE 路由仅限回环且无鉴权；不承载敏感信息，但不应对外暴露。
- 验证目标为 DSH `0.2.0-rc.2`、`0.2.1-rc.1`、`0.2.1-rc.2`，其它版本可能移动本插件依赖的接缝。

## 📄 许可

MIT —— 见 [LICENSE](LICENSE)。