dsh-remote-vs
VSCode 风格的 DSH 远程开发：SSH 主机管理器（密钥/密码）、带版本检查的助手部署流程，以及 dsh-better-sidebar 中的远程文件浏览器、编辑器和终端。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:xiray-xia/dsh-remote-vs#463dd495d555bc5067720a46fa7ccafe15fe1e48Remote Vs 以 dsh-remote-vs 发布，当前版本为 0.5.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
Host 进程内的 SSH 主机管理 + helper 推送流水线 + VS Code 式远端工作台
（资源管理器 / 搜索 / 源代码管理 / 提交图 / 多标签编辑器 / 并排 Diff / 多终端）。
主机配在 DSH 设置里（“远程主机”项）；装了 dsh-better-sidebar 时另有
独立“远程”tab，没装则退到原生右侧栏“远程”页（同内容，引导页自助开，per-session 实例）。
编辑器还额外挂到会话视图槽，与“对话 / 轨迹”并列成一个远程编辑器标签，
这样代码区是整屏宽的；右侧栏那份是窄屏备用面。
P2 起原生工具在远端工作区里透明跑远端（见下）。
┌─ 本机 DSH Host ─────────────────────────────────┐
│ 本插件 Host 半 │ Client 半（浏览器） │
│ 主机/密钥/推送/路由 │ 设置两节 + 原生入口接管 │
│ /api/dsh-remote/* │ 工作台（右侧栏 + 会话视图）│
└──────────────────────┴──────────────────────────┘
│ ssh2（文件/进程/终端）+ helper RPC（远端 fs）
▼
┌─ 远端 Linux ─────────────────────────────────┐
│ ~/.dsh-helpers/<ver>/<arch>/dsh-ssh-helper │
│ 用户指定的远端工作目录 │
└──────────────────────────────────────────────┘
dsh plugin add github:xiray-xia/dsh-remote-vs
要求 DSH 0.2.1-alpha.4。首次安装按提示在 profile 的 pnpm-workspace.yaml
里放行构建脚本后重跑；装完重启 dsh web，打开设置 → 远程主机开配。
| 能力 | 说明 |
|---|---|
| 资源管理器 | 懒加载目录树 + 展开折叠 + 隐藏文件开关；右键菜单：新建/改名/删除/复制/移动/粘贴/在此文件夹查找/插入 @ 引用；git 状态色与文件夹聚合标记 |
| 搜索 | 两档：文件名（远端 find）与内容（远端 grep）。内容档带范围目录、Aa（大小写）/ab_（全字）/.*（正则）、结果按文件分组、命中高亮，点条目跳到该行 |
| 源代码管理 | 仓库目录选择器（工作区里的 git 在子目录时用：浏览远端目录、一键跳到工作区内发现的仓库、手输相对/绝对路径，并逐目录提示会落在哪个仓库）；变更/暂存/未跟踪/忽略分桶，逐文件与逐 hunk 暂存/还原、丢弃（带确认）、提交；分支/远程/stash 面板；同步（fetch/pull/push） |
| 并排 Diff | 左右严格等分 + 中间 gutter 逐 hunk 按钮 + 顶部横向滚动条（一行很长也不会破坏对称）+ 行号钉在左侧，只渲染视口内的行（3000 行文件从 9000 个行容器降到约 174 个，滚动范围与整篇渲染完全一致）；可切「变更前 / 变更后」，变更后可编辑并保存 |
| 提交图 | SVG 分支/合并图 + 提交详情 + 点击提交展开变更文件 + 进文件看 diff |
| 多标签编辑器 | 打开/保存/重载、脏标记、多文件标签并存；图片预览、Markdown/HTML 预览（源码/预览切换） |
| 语法高亮 | VS Code Dark+ / Light+ 配色；覆盖 java/aidl/smali、c/c++、go、rust、js/ts、json、py、yaml、xml、html/css、md、sh、properties/rc/toml、diff 等；兜底着色器在语法包没命中时自动接管，不会出现整篇无色。诚实说明：kotlin / gradle / smali 用 Java 语法着色（没有专用语法包），效果是关键字/字符串/注释正确、专有语法不细分 |
| 查找 | 编辑器内 Ctrl+F（Aa/ab_/.*、3/17 计数、↑↓、F3/Shift+F3、Esc）；选中文本按 Ctrl+F 直接填入；查找框钉在右上角，滚动不带走 |
| 跳转 | 从搜索结果点进文件 → 跳到该行 + 垂直居中 + 落地行高亮（约 2.6 秒后淡出）；同文件反复跳都生效 |
| 多终端 | 标签式多终端（+ 新建、✕/中键关闭带确认）、可跨主机；刷新页面按 session id 自动重连回原会话，socket 全断开后会话保留 10 分钟（够刷新、够切浏览器标签页接回），超时才关闭远端 shell |
| 工作区 | 绑定列表 + 路由档位下拉 + 新建工作区双模向导（本地 / 远端） |
| 能力 | 说明 |
|---|---|
| 主机管理 | 增删改查、连接测试；证书 / 密码认证；配置存 $DSH_HOME/dsh-remote.json（0600），与 dsh-ssh.json 独立 |
| 密钥 bootstrap | 密码主机一键生成专用密钥对并下发 authorized_keys，之后走密钥 |
| 推送流水线 | 远端 arch/系统探测 → 版本比对 → 一致跳过 / 否则推送；executable 通道推送自编译 helper。失败后不再每次远端文件操作都重试：按 5 秒起步、上限 5 分钟的退避重试，设置页「推送」按钮可强制立即重试 |
| 远端文件 | SFTP 浏览 / 读 / 写 / 新建 / 删除 / 改名。边界已加固：0 字节文件不再卡死，每个 SFTP 操作 60s 超时回收通道；单个目录列表上限 20000 条（按"目录在前、其余按名"排序后取前 20000，宿主日志说明——协议里没有"已截断"字段，界面上没有标记） |
| 远端终端 | ssh2 PTY + WebSocket，xterm 渲染（复制粘贴/主题跟随/刷新重连）；重新挂接只接管、不改尺寸（刷新页面不会把运行中的 shell 缩成 80×24）；输出积压时对远端施加真背压；单帧上限 1 MiB，超过 64 Ki 字符的粘贴在客户端按码点分块发送，不再撑断连接 |
| 并发通道 | 每主机同时最多 6 条远端通道（不再撞远端 sshd 的 MaxSessions）；第 7 个排队最多等 30 秒，超时明确报 remote host <alias> is busy，而不是无限堆连接 |
| 超时与进程清理 | exec 跑在独立会话里（setsid --wait），超时先发 TERM、3 秒后升级 KILL，连同子进程一起收掉；远端没有 setsid --wait 时探测一次即知，退回旧行为并在宿主日志里写明"超时可能没停掉远端命令" |
| Git 图谱 | 远端仓库状态 + 分支 + SVG 提交图 + 提交详情（exec + 前端解析，零 Host 增量） |
| 导入 | 从 ~/.ssh/config、从现有 dsh-ssh.json 一键导入（只读一次，不耦合） |
| 能力 | 说明 |
|---|---|
| Agent 工具 | remote_hosts / remote_exec / remote_read / remote_write / remote_ls |
| P2 透明远端执行 | 远端工作区里原生 read/write/edit/bash/glob/grep/jobs 直接跑在远端 |
| P3 远端 @ 引用 | 远端会话 @ 出远端文件候选（路由 fileReferences，scoped 实时/bare 走远端 rg 索引） |
dsh_remote_vs/
├── cordis.patch.yml # 组合声明：插件行 + 私有本地 realm + 三路由 + preset-remote
├── src/
│ ├── index.ts # 插件入口：store/pool/worlds/路由/工具/预设切换接线
│ ├── protocol.ts # 前后端 wire 契约（路由表 + 纯类型，两边共用）
│ ├── paths.ts # $DSH_HOME 下四件套寻址（库/密钥/构建缓存/别名目录）
│ ├── store.ts # 主机 + 绑定 + 墓碑持久化（0600 JSON，原子写）
│ ├── pool.ts # ssh2 长连接池（exec/shell/sftp/putFile，TOFU 主机键）
│ ├── sftp.ts # 远端文件引擎（SFTP 窗口读写/目录树操作）
│ ├── keygen.ts # 密码机密钥 bootstrap（生成→下发→翻转）
│ ├── deploy.ts # 推送流水线（探测/比对/传包/双验/manifest）
│ ├── importers.ts # ssh_config / dsh-ssh.json 解析导入
│ ├── routes.ts # /api/dsh-remote/* 路由表 + 终端 WebSocket 升级
│ ├── terminal.ts # PTY 会话注册表（刷新重连/断开清理）
│ ├── tools.ts # 5 个 Agent 工具定义
│ ├── http.ts / loopback.ts # JSON 体读写 + 回环信任围栏
│ ├── git-format.ts # git 命令构造 + 纯前端解析（Host 零增量）
│ ├── git-ops.ts # 远端 git 全量动作：status/diff/分支/远程/stash/提交/hunk 补丁构造 + 解析器
│ ├── fs-ops.ts # 远端文件操作命令构造（复制/移动/删除/stat）
│ ├── search-ops.ts # 远端内容搜索（grep 构造 + NUL 分隔解析 + 命中切分）
│ ├── p2/ # ── P2 透明路由 ──
│ │ ├── worlds.ts # 世界判定（cwd 键/别名/墓碑）+ RPC/FS/进程远端上下文
│ │ ├── helper-rpc.ts # ssh2 exec 通道上的 helper wire 协议（握手/心跳）
│ │ ├── router-fs.ts # 透明 fs 路由（目标→世界映射/路径翻译/策略重写）
│ │ ├── router-subprocess.ts # 透明进程路由（argv0 归约/pwsh 门）
│ │ ├── ssh-proc.ts # ssh2 进程运行时（setsid 组杀/marker/stdin/spill）
│ │ ├── shell-bash.ts # 路由 bash 执行器（本地原样/远端去 DSH_*）
│ │ ├── router-spill.ts # 透明 spill 路由（session 世界键/远端目录）
│ │ ├── router-refs.ts # 透明 @ 引用路由（agent 世界键，P3）
│ │ ├── file-refs.ts # 远端 @ 搜索（fs-ssh 实时列/rg 索引/官方评分移植）
│ │ ├── bridge.ts # 私有 realm 本地件发布（localFs 等早期服务）
│ │ └── bridge-refs.ts # refs 独立桥（local-refs 依赖 workingDirectory，必须分离）
│ └── client/ # ── 浏览器半（React，打包进 lib/client.js）──
│ ├── index.tsx # 双面决策（better 优先/settle 加速/原生兜底）+ 设置两节 + directoryFlow 双槽接管
│ ├── store.tsx # 双面共用的模块级状态（useSyncExternalStore；打开的文件/终端/视图都在这）
│ ├── RemoteRoot.tsx # 右侧栏挂载面：VS Code 式活动栏（资源管理器/搜索/SCM/提交图/编辑器/终端/工作区）
│ ├── RemoteEditorView.tsx # 会话视图挂载面（与 对话/轨迹 并列的「远程编辑器」标签，整屏宽）
│ ├── RemoteExplorer.tsx # 资源管理器：树 + 右键菜单 + 文件操作 + @ 引用 + 状态标记
│ ├── SearchView.tsx # 搜索面板：文件名 / 内容 两档 + Aa/ab_/.* + 分组结果 + 跳转
│ ├── EditorPane.tsx # 编辑器面板：多标签 + 信息栏（构建戳/tok 计数）+ 图片/MD/HTML 预览
│ ├── CodeEditor.tsx # CodeMirror 封装：语法包表/主题/查找框/跳转/兜底着色接线
│ ├── scm/ # ── 源代码管理 ──
│ │ ├── ScmPanel.tsx # 变更/暂存/未跟踪 + 逐文件逐 hunk 操作 + 提交框
│ │ ├── DiffView.tsx # 并排 diff（顶部横向滚动条/hunk 按钮/可编辑变更后侧）
│ │ ├── HistoryPanel.tsx # SVG 提交图 + 提交详情 + 展开变更文件
│ │ ├── actions.ts # 远端 git 动作层（exec 通道）
│ │ ├── diff-model.ts # unified diff → 并排行投影（纯函数）
│ │ └── status-map.ts # 状态分桶 + 树标记（纯函数）
│ ├── vsc/ # ── VS Code 皮肤与控件（零新依赖）──
│ │ ├── kit.tsx / vsc.css # 图标/对话框/右键菜单/分段控件 + 全部样式（.rvs-root 作用域）
│ │ ├── editor-palette.ts # Dark+/Light+ 配色 + 固定类名（rvs-ck-*）
│ │ ├── editor-theme.ts # 编辑器容器主题（明暗热切换）
│ │ ├── editor-langs.ts # 扩展名 → CodeMirror 语法包
│ │ ├── fallback-highlight.ts# 语法包没命中时的兜底着色（用 tokenize.ts）
│ │ ├── FindWidget.tsx # Ctrl+F 查找框（固定右上角）
│ │ ├── reveal-line.ts # 跳转 + 落地行高亮
│ │ ├── tokenize.ts / markdown.tsx # 只读面板分词器 / 零依赖 Markdown 渲染
│ ├── NativeExplorer.tsx# 原生页类型定义 + seat 正文（无 sidebar 兜底）
│ ├── composer.ts / use-remote-chat-target.ts / selection-popup.ts # 远端 @引用/选中加对话
│ ├── api.ts # /api/dsh-remote 类型化 fetch 封装
│ ├── HostsView / WorkspacesView / WorkspaceWizard / TerminalView / XTerm / Dialog
│ ├── SettingsHosts.tsx # 设置两节 occupant（主机管理/绑定列表，自取数）
│ ├── DirectoryFlow.tsx # 原生入口 occupant（本地双模/远端向导）
│ ├── RemoteDirectoryPicker.tsx# 远端目录浏览弹窗
│ └── i18n.ts / theme.ts / ui.tsx # 双语词典/主题信号/共享样式
├── vendor/dsh-remote-helpers/ # helper 种子（随包发布，启动铺缓存，见下）
├── docs/ # 本地工作文档（不推送 GitHub）
│ ├── P2-PLAN.md # P2 架构/分期/验收矩阵（含逐项状态）
│ └── MAINTENANCE.md # 本地私有（.gitignore），不入库：DSH 升级影响面 + helper 升级流程
├── locale/ # 插件元信息双语
└── lib/ # 构建产物（gitignored，link 安装后重启即生效）
vendor/dsh-remote-helpers/（入库）是 helper 种子：插件启动时自动铺到
$DSH_HOME/dsh-remote-helpers/（缺啥补啥，永不覆盖），新机器装完即能推送。
新版本 helper 编好后把 4 件套（tarball + sha256 + helper.json + 补丁说明）
换进 vendor 并提交即可（详细步骤在本地维护文档 docs/MAINTENANCE.md §4，该文件被 .gitignore，不随仓库分发）。
.spike/（gitignored）是真机验证脚本 + 本地自检脚本：p2-router.ts 主回归（真远端 + 真
Cordis + 真路由类）+ grep-probe.mjs 等探针（构建见 tsconfig.scratch.json），以及不需要真机的
model-check.mjs / reveal-check.mjs / fallback-check.mjs / client-load-check.mjs /
tool-schema-check.mjs（见下文“开发”）。
两个挂载面共用一份状态（store.tsx）：右侧栏「远程」（装了 better-sidebar 走独立 tab，
否则走原生右栏页）与会话视图「远程编辑器」（与 对话/轨迹 并列，代码区整屏宽）。
tok N 着色 token 数、已保存状态、重载/保存）。
信息栏三个标记是给排障用的：构建戳判定"浏览器跑的是不是刚编的包"，tok 0 判定语法包是否命中。Ctrl+F 查找框固定右上角（position: fixed 锚定编辑器矩形，任何祖先滚动都不带走）；
选中文本按 Ctrl+F 直接填入；从搜索结果跳转会居中 + 落地行高亮。resize 帧）；socket 全断开后
会话保留 10 分钟，超时才关闭远端 shell（以前是永不回收，关掉浏览器后远端 shell 一直占着 sshd 会话槽）。revealEditor()）；dir/），点它只提示不展开（性能取舍）；listing <path> on <alias> shows 20000 of N entries。单 Host 混合路由：原生工具按会话 cwd 落在哪个世界自动分发 —— 远端 alias 走 helper RPC（fs）/ ssh2（进程），本地一切不变；两者同 Host、共 GUI。
$DSH_HOME/remote-ssh/aliases/<id>（空壳，只做路由键），自动注册进原生工作区列表，标题 <server> > <base>- id: remote-vs 下 config.routingMode，volatile，免重启）：
off（默认，直通本地）/ shadow（记日志仍走本地）/ enforce（真路由）Remote 预设（bash 工具集）；enforce 下远端新会话自动切过去（默认预设才切，不践踏显式选择）grep/glob 经路由调远端 rg（两台实测机自带 rg 13；远端无 rg 则查不到）FS_TOO_LARGE（helper 官方上限），用流读/分页；写无上限（46MiB 整包写实测通过）readFrom 返 tail + 路径，全文住文件里，与官方一致）npx tsc -p tsconfig.scratch.json && node .spike/build/.spike/p2-router.js
（真远端 + 真 Cordis + 真路由类，61/61；P0 路由与 GUI 需重启 Host 后冒烟）docs/P2-PLAN.md（§8 验收矩阵逐项状态）官方从未发布 helper 二进制（Release assets 全空），本插件走自编译：
dsh-v0.2.1-alpha.2 tag（构建基线：对齐的是 wire 协议号，不是 Host 版本号 —— 协议号至今仍是 2，故 Host 升到 alpha.4 也无需重编）pnpm exec tsx scripts/build-exe-for-ssh-helper.ts --target=node24-linux-x64DSH_GLIBC_CEILING
环境覆盖（默认仍 2.28），本次以 2.35 构建（见缓存目录 glibc-ceiling.patch）verify-ssh-helper-artifact.ts --sandbox=required 8 项全绿$DSH_HOME/dsh-remote-helpers/（*.tar.gz + .sha256 + .helper.json
含 binarySha256，供 P2 的 helperHash）docs/MAINTENANCE.md §4（.gitignore，不随仓库分发）/api/dsh-remote/* 路由仅限 loopback + 同源访问。dsh-remote.json（0600），与现有 SSH 插件同一信任模型。docs/P2-PLAN.md §4 备注。pnpm install
pnpm run typecheck
pnpm run build
dsh plugin --profile web add link:<本目录绝对路径>
改完必须重启 dsh web（客户端半也一样）：插件包在 Host 启动时被读进内存
（initialBundleSnapshot，URL 带 rev 且响应 immutable 一年），浏览器刷新——包括
Ctrl+Shift+R——只会取回启动时抓下的那批字节。判定方法：
lib/client.js 里会注入构建戳（MMDD-HHmm），编辑器信息栏右侧显示的就是它；dsh web → 刷新页面：戳变了才算生效；tok N：0 = 该扩展名没命中语法包，且兜底着色器也没接管（会给括号里的文件路径）。自检（不需要真机、不需要 DSH，几十秒）：
node .spike/client-load-check.mjs # 真求值客户端模块：加载期错误（模块级 TDZ 之类）tsc、打包、其它 harness 都看不见
node .spike/tool-schema-check.mjs # 5 个 agent 工具：跑一遍 execute，用运行时的同一个校验器核对返回值和声明的输出 schema
node .spike/model-check.mjs # 55 项：真 git 输出 → 解析器、diff 模型、hunk 补丁可应用性、类名↔CSS 契约
node .spike/reveal-check.mjs # 5 项：跳转落点、落地高亮、同文件二次跳转
node .spike/fallback-check.mjs # 12 项：兜底着色器在真 DOM 里给 java/cpp/shell 上色
node .spike/editor-dom-check.mjs # 12 项：真 CodeMirror 在 jsdom 里对 java/shell/cpp 产出着色 span
node .spike/i18n-check.mjs # 中英词典一致性：无缺失键、无孤儿键、占位符形状一致
node .spike/ref-check.mjs # 32 项：assertRef 接受合法修订后缀、拒绝一切注入面
node .spike/status-check.mjs # 真 shell 里跑生成的 git 命令，验证退出码不再被管道掩盖
node .spike/cache-check.mjs # 增量分词缓存 vs 整篇分词，9 种语言 × 8 种编辑形态逐字节比对
node .spike/layout-check.mjs # 高度链与滚动条契约：标签栏固定不被顶走、编辑器滚动条够宽可点
node .spike/viewstate-check.mjs # 滚动+光标跨重挂的往返（有状态 scrollTop，能区分"恢复"与"被重置"）
node .spike/tabswitch-check.mjs # 真 React 驱动三种接线：两种读 ref 的必须失败，上报式必须成功
node .spike/letter-check.mjs # 状态字母：未跟踪 ? 与冲突 U 不再撞车，其它映射与两处渲染点
.spike/layout-fixture.html（由 build-fixture.mjs 生成）是浏览器里量布局用的夹具：
它把宿主真实的插槽 CSS 和线上 vsc.css 机械内联进去，改完 CSS 重跑
node .spike/build-fixture.mjs 即可在真浏览器里量高度链、滚动容器与滚动条宽度——
纯 CSS 的问题 tsc、打包、jsdom 都看不见，这个夹具是唯一能复现它们的地方。
markdown-check.ts 需要先编译（它 import .tsx，Node 不能直跑）：
npx tsc -p tsconfig.scratch.json && node .spike/build/.spike/markdown-check.js。
.spike/被.gitignore排除，这些检查只在本地存在、没有 CI；因此引用任何数字前都要当场跑一遍， 不要照抄任何一处写着的数字（同一个model-check曾在 README / 本地维护文档 / 评审报告之间漂移出 44 / 48 / 55 三种，而它实际打印 55/55 —— 脚本里有 57 处check(调用点，其中 2 处在循环里且只在 失败时才触发，所以「调用点 57」与「跑出来 55」本来就该差 2）。
真机回归仍是 npx tsc -p tsconfig.scratch.json && node .spike/build/.spike/p2-router.js。
DSH 发新版时先读本地维护文档 docs/MAINTENANCE.md（§2 逐项耦合点 + §3 升级清单）再动手；该文件被 .gitignore，克隆仓库的人看不到，改动 host 半后的必做动作是 pnpm run verify:lib + 加载自检。
MIT © 2026 xiray-xia —— 见 LICENSE。
vendor/ 里的 helper 种子由 DeepSeek Harness 源码（MIT）按 dsh-v0.2.1-alpha.2
tag 以官方原脚本构建，具体流程与唯一有记录的偏离见上文"Helper 自编译"节
（种子包里的 glibc-ceiling.patch）。