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 总闸。

安全模型摘要

token 仅存 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