yingzaicc/dsh-editor-selection

dsh-editor-selection

让 DSH 理解“用户此刻在编辑器里看着什么”。当你在编辑器中选中某个文件或行区间，后续对话自动聚焦于它——通过 @path:10-25 的环境知会行注入，而不是把文件内容塞进上下文。

本插件是通用编辑器选区服务：协议与客户端种类无关，VS Code 桥只是第一个接入者（未来可接入 GoLand 等 IDE，见 DESIGN §13）。设计文档见 DESIGN.md（§0 决策记录 → §13 多客户端通用化）。本 README 只讲安装、使用与验证。

它做什么 / 不做什么

| ✅ | ❌ |
| --- | --- |
| 捕获主选区的绝对路径 + 行区间（1-based） | 读取或上传任何文件内容 |
| 在 agent 每步之前注入一行环境知会（agent/pre-step，prepend） | 把选区“附加”进对话历史 |
| DSH 侧边栏 🔔 配对审批 + 设备吊销 | 任何云服务——全部本机回环 |
| 输入框下方环境 chip：[👁] @C:\...\app.ts:10-25，眼睛即隐私开关 | 反向导航（协议帧已保留，未实现） |

架构（30 秒版）

VS Code 扩展 ──WebSocket /editor-selection/ws──▶ 插件 Node 半部
(绝对路径+行区间)     token 配对/认证              │ ManualApprovalPolicy(人审)
│ FocusState(状态机)
浏览器半部 ◀──────── HTTP /editor-selection/api ──┤ FocusState.view(只读投影)
chip + 🔔                                        │
▼
agents: agent/pre-step → createUserMessage(source.kind=plugin)

信任策略与通知呈现是两个可替换接口（ConnectionPolicy / NotificationSink）——未来 DSH UI 嵌入 VS Code 时，“安装即信任”，配对仪式整体退场。

构建

powershell -ExecutionPolicy Bypass -File scripts\link-deps.ps1   # junction harness 依赖(离线)
node node_modules\typescript\lib\tsc.js --noEmit                 # 类型检查
node node_modules\tsdown\dist\run.mjs                            # lib\index.js + lib\client.js(+testkit)

兼容性冒烟:驱动【构建产物】过 5 组共 20 项断言
$env:DSH_EDITORSEL_ROOT = "$env:TEMP\dshe-smoke"; node scripts\compat-smoke.mjs

冒烟覆盖：产物形状（loader banner、双席位注册）、真实 TCP 回环上的 RFC6455 双端帧数学（掩码/126 长度/close 码）、经 registerUpgrade 的完整配对流（坏 token→4401、批准→一次性 token→干净交接、拒绝→4403）、焦点状态机（active/paused/stale/offline + 变更驱动抑制）、注入消息契约（time-context 同形、plugin 归因、deep-frozen）。

安装到本地 DSH

powershell -ExecutionPolicy Bypass -File scripts\install.ps1
重启 dsh web 后生效;卸载用 scripts\uninstall.ps1

脚本做三件事：junction 包目录到 ~/.dsh/profiles/web/node_modules/dsh-editor-selection、写入 profile package.json 依赖、登记 dsh.profile.bundles。

VS Code 侧

见 ../dsh-editor-selection-vscode/README.md。要点：首次连接触发配对请求 → DSH 🔔 里确认 → token 入 SecretStorage，之后静默。

使用

- 眼睛开关（chip 上）：关=暂停共享（向 agent 注入一条一次性“已暂停”知会后保持沉默）；开=恢复。状态持久化。
- 选中即聚焦：有真实选区 → @绝对路径:起-止；光标停放无选择 → @绝对路径（整个文件即焦点）；光标不在任何文件里 → 焦点清空。缓冲区未保存会标注“（缓冲区未保存）”。
- 右键「解释代码」（VS Code 编辑区，先选中代码）：选区发给 DSH，DSH 在最近活跃的会话里自动开始解释该段代码，无需手动输入。
- 多窗口：每窗口一个实例，行尾注明来源实例；30s 心跳，90s 无心跳判离线。
- 路径可读性由 DSH 权限系统裁决：插件不再做工作区映射门槛；工作区外的文件在 agent 实际读取时按 DSH 既有权限流程索权。

兼容性与降级（DSH 早期预览）

| 情形 | 行为 |
| --- | --- |
| agents 服务缺席 | 注入不挂载，chip/通知照常 |
| 注入缝隙签名变化 | pre-step 注册 try/catch，警告后跳过 |
| WS 路由不可用 | API/chip 正常，扩展侧退避重连 |
| 状态文件不可写 | 内存模式运行，提示一条警告 |
| 席位被占用/改名 | 对应贡献跳过，console.warn，不破坏组合 |

逃生舱：DSH_EDITORSEL_ROOT 重定位状态目录；dshEditorSelection.enabled=false 总闸。

安全模型摘要
令牌仅存 SHA-256 哈希；配对请求 60s TTL、同 instanceId 去重；close 语义 4401 未授权 / 4403 配对过期或被拒 / 4408 限流（20 帧/s）；WS 层不做 Origin/sec-fetch 校验（token 即身份），浏览器 API 层沿用 git-plugin 同款 trusted-host 栅栏；focus 帧解析拒绝 .. 段与超长路径；路径可读性交由 DSH 权限系统在读取时裁决（v2）。

目录

src/
protocol.ts        协议常量 + 严格帧校验
focus.ts           renderFocusLine(纯函数) + FocusState(变更驱动状态机)
injector.ts        agent/pre-step 注入器(time-context 同形消息)
trust-policy.ts    ConnectionPolicy 接口 + ManualApprovalPolicy 实现
ws-route.ts        registerUpgrade 路由(hello→admit→会话)
api-http.ts        浏览器 API(state/approve/deny/revoke/share.set)
platform/          ws-server(RFC6455)、tokens、browser-fence、state-file
client/            chip、🔔、store、locales、styles(零依赖 React)
testkit.ts         冒烟专用内面出口
scripts/
link-deps.ps1      junction 离线依赖
compat-smoke.mjs   20 项构建产物冒烟
install.ps1 / uninstall.ps1