dsh-over-ssh 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-over-ssh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# dsh-over-ssh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH（DeepSeek Harness）第三方插件：把 VSCode Remote-SSH 式的远程开发做进 DSH —— 连接管理（密钥 / 密码 / ProxyJump / `~/.ssh/config` 导入）、远程文件（**无同步**直读直写）、远程终端、远程工作区、远端 `@` 补全、上传/下载，并支持"本地根 + 远端根"同处一个工作区。
+
+设计依据：`doc/01-product/02-技术设计-SSH远程开发插件.md`（v0.2）。需求依据：`doc/01-product/01-需求分析-多根工作区-远程根-会话管理.md`（v0.4）。文档知识库入口：`doc/README.md`。
+
+## 安装
+
+从 npm（发布后）：
+
+```bash
+dsh plugin --profile web add dsh-over-ssh     # 等价于在该 profile 目录里 pnpm add
+```
+
+从源码（本仓库开发时）：
+
+```bash
+npm i && npm run build
+dsh plugin --profile web add /绝对路径/dsh-over-ssh
+```
+
+**远端终端**要额外配一次 `terminalController.Config.shell`——`Config.shell` 是静态单值，连哪台只能由 wrapper 运行时决定：
+
+| 装法 | 指向 |
+|---|---|
+| npm | `node_modules/dsh-over-ssh/lib/terminal-wrapper.js`（单文件，内部模块已内联） |
+| 源码 | `tools/over-ssh-terminal.ts`（Node 24 直接跑 TS） |
+
+```yaml
+shell:
+  path: node
+  name: SSH / Local
+  args: ['<上面那个路径>', '--name', 'gpu01']
+```
+
+不配也能用，只是 Web 终端永远开在本地（远程文件、远端执行、`@` 补全不受影响）。
+
+## 发布说明
+
+包里带了两个平台的 Tier 2 代理二进制（纯静态，远端零依赖）。源码在配套的 Go 仓库
+`dsh-over-ssh-agent`（暂未公开发布，按下面的 `sourceCommit` 可核对）。这一段由 `npm run release:note` 从
+`agents/agent-manifest.json` 生成，`prepack` 会核对它与清单一致，**不要手改**：
+
+<!-- release-note:begin（由 tools/release-note.mjs 生成，勿手改） -->
+
+| 平台 | 字节 | sha256 |
+|---|---|---|
+| linux-amd64 | 4,907,168 | `08998e6f51bc1a3759a966e96263c380f81f4281f2a50b0257b61f12b1341c3b` |
+| linux-arm64 | 4,653,216 | `0e19b3e77590f233093c09a7adc20487d721407bf805a9f879a756c9f03b9a11` |
+
+- 代理版本：`1.7.0-0ae8c02`
+- 源码提交：`0ae8c02`（Go 仓 `dsh-over-ssh-agent` 的这个提交）
+- 清单原文：包内 `agents/agent-manifest.json`
+- 核对：`sha256sum agents/<平台>/dsh-over-ssh-agent` 与上表比对；按上面的提交检出 Go 仓后
+  `scripts/check.sh` 可重建同样的产物。
+
+<!-- release-note:end -->
+
+## 关键设计取舍（摘要）
+
+- **传输层自研**，不使用核心 `packages/ssh/*` 家族。原因见设计文档 §3.1：官方实现的 `BatchMode=yes` 让密码认证不可能、远端必须预装 Node + helper、`ctx.ssh` 单例、且其 Web 集成需单独实现（preset 的 `isolate` 子树覆盖不到 `agent.ctx`）。
+- **文件按路径路由，进程不路由**：核心 provider 的公开方法收不到 agent/session 身份，因此 fs 用自研路由 provider 支持"本地 + 远端多根"，而 bash/终端保持单一执行世界，远端命令走显式入口。
+- **远端零安装（Tier 1，地板）**：只依赖远端已有的 POSIX 工具（`sh`/`base64`/`stat`/`find`/可选 `git`/`rg`），连上后做一次能力探测并按能力降级。
+- **可选 Go 代理（Tier 2，增强）**：独立仓库 `../dsh-over-ssh-agent`，纯静态单文件（随包产物的体积与摘要以 `agents/agent-manifest.json` 的 `bytes`/`sha256` 为准，交叉编译矩阵见 `../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md`；零第三方依赖），经 ssh stdio 通信（不监听端口），补齐原生监听/索引/长任务/远端 LSP/Landlock 围栏。决策见 `doc/03-decisions/0005-optional-go-remote-agent.md`；代理不可用时一律回退 Tier 1。
+  - **默认尝试部署**（2026-10-13 起，审计 0040）：连接的默认传输是 `agent`，首次连接会把代理装到远端 `$HOME/.cache/dsh-over-ssh/dsh-over-ssh-agent`（约 4.7 MiB / 4,907,168 B，以 `agents/agent-manifest.json` 为准，`0700`），失败自动回退 Tier 1。想避开远端写入就显式写 `transport: alias`。
+  - **密码认证同样可用**：代理经系统 ssh 启动，而系统 ssh 靠 `SSH_ASKPASS` 助手取密码（秘密只经环境变量传递，不落盘）。此前"密码认证无法用代理"的说法是把本插件硬写 `BatchMode=yes` 误当成了 SSH 的限制。
+  - 随包只带 `linux-amd64` 与 `linux-arm64` 两个产物；其它平台的远端会正常降级到 Tier 1。
+- **秘密进 `ctx.credentials`**：`role('secret')` 只保证不上 wire，落盘仍是 profile patch 明文，因此密码/口令绝不进 Config。
+
+## 目录结构
+
+```
+src/
+  host/
+    domain/        # 纯 TS、零框架依赖、100% 单测覆盖
+    app/           # 应用层用例（依赖抽象）
+    infra/         # 传输/后端/缓存/持久化实现
+    integration/   # 与核心对接：fs provider、fileReferences、tools、Remote API、终端 wrapper
+    client/        # web client 半（React + TS + CSS Modules）
+tests/             # 每个模块一个独立测试文件
+```
+
+## 测试
+
+零依赖：使用 Node 内置 test runner + 原生 TypeScript 类型剥离（Node ≥ 22.19 / ≥ 24）。
+
+```sh
+npm test          # node --test "tests/**/*.test.ts"
+npm run typecheck # 需要先安装 devDependencies（typescript）
+```
+
+约定：**一个源文件对应一个 `tests/<同名>.test.ts`**；领域层与基础设施层不依赖核心包，因此测试无需安装 `@deepseek-ai/*`。
+
+当前数字只在 `doc/05-benchmarks/baseline.md` 维护，本文不重复抄录。抄录的副本会与基准不一致，这类不一致在本仓库已经出现过。要现在的数字就跑命令：
+
+```sh
+node --test --test-concurrency=4 "tests/**/*.test.ts"        # 正确性：用例数与失败数
+tsc -b && tsc -p tsconfig.client.json                        # 类型：宿主半与客户端半
+npm run build:host && node tools/build-client.mjs --check     # 产物体积
+npm run agents                                               # 随包代理清单与体积
+```
+
+> 注意：本机跑套件必须限并发。`npm test` 的默认并发会一次拉起 71 个 Node 进程，而本机可用物理内存常年
+> 只有 1–2 GB，会大量假失败（`spawn ENOMEM` / `Fatal process out of memory`，用例总数在 841–1235 之间跳）。
+> 用 `node --test --test-concurrency=4 "tests/**/*.test.ts"`。这是环境容量问题，不是代码缺陷。
+
+## 里程碑
+
+见设计文档 §13：M0 spike（三个未验证假设）→ M1 传输与连接管理 → M2 路由 fs → M3 远端搜索与 `@` → M4 文件树与传输 → M5 远程终端 → M6 会话管理 → M7 性能与内存回归。
+
+当前进度（本仓库内）：只列最近三条，更早的里程碑见 `doc/06-audits/README.md` 的历史记录表。
+
+- [x] **改名 `dsh-over-ssh`**：仓库目录、Go module、二进制、状态目录、两个回收站、HTTP 路由共 11 处名字统一，
+  已有数据走 4 条一次性迁移（远端旧代理目录不删）。见 `0110`（`doc/06-audits/0110-rename-to-dsh-over-ssh.md`）。
+- [x] 阶段 2 的「添加目录」按**会话**隔离。同一工作区开两个会话时，A 加的目录 B 既看不到也用不了；fork 出来的会话继承父会话的目录，老数据（无 `sessions` 字段）保持工作区级不打断。会话身份由 `AsyncLocalStorage` 从工具派发带到 `ctx.fs`（平台只给 fs 传 `cwd`）。GUI 文件面板、`glob`/`grep` 与隐式会话根三处残余面已写明。见 `0108`（`doc/06-audits/0108-per-session-root-isolation.md`）。
+- [ ] 阶段 2 的「一键接管」开关尚不可用。审计 0095 的实现有宿主异步清单、行标识与回滚缺陷，不安全的逐行写入路径已移除，面板只显示状态与手动配置提示。平台的单行管理 API 不能保证四行批量原子切换或精确恢复原有 profile 覆盖，要等可靠的批量事务与还原机制可用并通过真实组合验证后才能启用。见 `0096`（`doc/06-audits/0096-takeover-safety-correction.md`）。
+- [x] 阶段 2 的会话工作目录根。活会话 cwd 自动成为会话作用域、隐藏、纯内存的本地根；`resolve`/`lstat` 失败时同步一次再重试。真机端到端未跑。见 `0094`（`doc/06-audits/0094-session-workspace-root.md`）。
+- [x] 卸载不等于关闭。用时间区分重注册与真关闭：`surfaceDetached()` 推迟一个任务、`surfaceAttached()` 取消，调度可注入，策略离线可测。见 `0091`（`doc/06-audits/0091-unmount-is-not-close.md`）。
+
+并行轨道（独立仓库 `../dsh-over-ssh-agent`）：协议、文件原语、索引与搜索、watch、proc、LSP、Landlock 围栏均已实现，多会话与常驻 daemon 分四阶段完成。当前状态、未做项与实测数字见该仓库的 `README.md`（`../dsh-over-ssh-agent/README.md`） 与 `benchmark`（`../dsh-over-ssh-agent/doc/05-benchmarks/baseline.md`）。

package/agents/agent-manifest.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "generatedAt": "2026-11-02T16:02:32.695Z",
+  "agentVersion": "1.7.0-0ae8c02",
+  "sourceCommit": "0ae8c02",
+  "artifacts": [
+    {
+      "platform": "linux-amd64",
+      "path": "linux-amd64/dsh-over-ssh-agent",
+      "sha256": "08998e6f51bc1a3759a966e96263c380f81f4281f2a50b0257b61f12b1341c3b",
+      "bytes": 4907168
+    },
+    {
+      "platform": "linux-arm64",
+      "path": "linux-arm64/dsh-over-ssh-agent",
+      "sha256": "0e19b3e77590f233093c09a7adc20487d721407bf805a9f879a756c9f03b9a11",
+      "bytes": 4653216
+    }
+  ]
+}

package/cordis.patch.yml

@@ -0,0 +1,84 @@
+# dsh-over-ssh 的组合层（profile bundle patch）。
+#
+# 语义要点（0.2.1-rc.2 已核实）：
+#  - 一条 patch 按 id 定位条目，**整体替换 config**（不做深合并）；`name` 只是断言，不能改包。
+#  - 被更高层 patch 覆盖时，最后一次写入生效。
+#  - `!!js` 只允许出现在 `config` 与 `disabled` 两个字段。
+#  - 本文件随包发布（`package.json` 的 `dsh.bundle.patch`），安装即生效。
+#
+# 组合结构：**下沉 + 路由**。
+#
+#   根作用域：
+#     ctx.fs             ← dsh-over-ssh/fs（多根路由）
+#     ctx.fileReferences ← dsh-over-ssh/file-references（多根 @ 补全）
+#
+#   私有域（isolate: fs / fileReferences）：
+#     ctx.fs             ← @deepseek-ai/dsh-fs-sandbox（**原版**，继续服务本地路径）
+#     ctx.fileReferences ← @deepseek-ai/dsh-file-reference-local（**原版**）
+#     两个 bridge 把域内实例以 localFs / localFileReferences 暴露给根作用域。
+#
+# 为什么是「接管」而不是「共存」：`ctx.fs` 是 Cordis 单例服务，同一隔离作用域只能有一个提供方，
+# 再注册第二个会抛 `service "fs" has been registered`。`isolate` 让原版实现能在私有域里继续跑，
+# 于是本地路径的**写入围栏由平台的沙箱执行**，本插件不再维护第二份（见 PlatformLocalBackend）。
+#
+# 已实测的前提（cordis 0.2.1-rc.2）：域内 `fs` 解析到域内实例；根 `fs` 不受影响；可以同时存在多个域；
+# 根作用域的消费者能注入到域内 bridge 暴露出来的 `localFs`。任何一条不成立这套组合都不成立。
+#
+# 这两组行必须**同时**生效或同时不生效：只禁用核心行而不启用本插件的行，会让 `ctx.fs` /
+# `ctx.fileReferences` 无人提供，所有文件能力一起失效。
+#
+# 还原：禁用整个 bundle。不要只删其中一行。
+#
+# ## 为什么 id 是中文
+#
+# 平台的「插件列表」页**按条目 id 展示**，标题来自各包自己的 `locale/*.json`——而本插件的 7 个条目同属
+# 一个包，共用一个标题，所以**只有 id 能区分它们**（2026-11-01 实测：`locale` 是按包不是按条目）。
+# 之前叫 `remote-workspace-local-fs` 这类名字，用户在列表里看到 7 行猜不出谁是谁。
+# 改成中文是**纯展示层**改动：id 只被 loader 当作键、被 patch 用来定位，实测中文 id 能正常加载
+# （`E2E=1 node --test tests/e2e/host-boot.test.ts` 通过，且启动日志里没有 `localFs` 缺失告警）。
+#
+# 改名的代价（已知并接受）：写自己 profile patch 的人要照抄中文 id；`doc/06-audits/` 里的**历史审计**
+# 仍用旧 id（按"历史审计只追加、不改写"的规定保留原样），换算见 `doc/06-audits/log.md` 2026-11-01 那条。
+#
+# 命名约定：`远程工作区-<角色>`。
+#   平台沙箱副本 / 平台文件引用副本  = 平台原版，在私有域里再实例化一次
+#   桥接fs / 桥接文件引用            = 把私有域里的实例暴露回根作用域
+#   路由fs / 路由文件引用            = 根作用域的提供方，决定一个路径走本地还是远端
+
+- insert:
+    # 主入口：连接 / 根 / 传输 / 索引 / 工具面 / 客户端数据通道 / 终端清单。
+    - id: 远程工作区
+      name: dsh-over-ssh
+
+    # 私有域：把**原版** provider 原封不动地再实例化一遍，隔离在这个 group 的槽位里。
+    # 原版一行代码没改；`isolate` 让它们注册进本域，不与根冲突。
+    - id: 远程工作区-私有域
+      name: cordis:group
+      group: true
+      isolate:
+        fs: true
+        fileReferences: true
+      config:
+        - id: 远程工作区-平台沙箱副本
+          name: '@deepseek-ai/dsh-fs-sandbox'
+        - id: 远程工作区-平台文件引用副本
+          name: '@deepseek-ai/dsh-file-reference-local'
+        # 两个 bridge 分开：file-reference-local 依赖 workingDirectory（在下游），不能和 fs 挤在同一行。
+        - id: 远程工作区-桥接fs
+          name: dsh-over-ssh/local-bridge
+          inject: [fs]
+        - id: 远程工作区-桥接文件引用
+          name: dsh-over-ssh/local-bridge-refs
+          inject: [fileReferences]
+
+    # 根作用域的提供方。两个入口都是「路由型」：本地路径与远端路径由同一套表分发。
+    - id: 远程工作区-路由fs
+      name: dsh-over-ssh/fs
+    - id: 远程工作区-路由文件引用
+      name: dsh-over-ssh/file-references
+
+# 核心行让位给上面的两个提供方。
+- id: fs-sandbox
+  disabled: true
+- id: file-reference-local
+  disabled: true