@winking-r/dsh-uniterminal 0.2.17 → 0.2.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +17 -1
  2. package/README.md +49 -25
  3. package/docs/SECURITY.md +5 -5
  4. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,21 @@
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.2.18] - 2026-10-29
10
+
11
+ 纯文档版本，**代码与 0.2.17 完全相同**。
12
+
13
+ ### 文档
14
+
15
+ - README 新增**截图**（主机列表 / 终端 / 连接表单 / SFTP / 外观）：演示数据为 `demo01`–`demo03` 与 RFC 5737 文档段 `192.0.2.0/24`；
16
+ 图片经绝对 URL 引用，npm 页面同样能显示。
17
+ - 安装说明改为**一条命令**：`dsh plugin --profile <profile 名> add @winking-r/dsh-uniterminal@latest`；
18
+ 手工方式（`pnpm add` + 编辑 `dsh.profile.bundles`）作为备选保留。
19
+ - **已知限制去掉开发日志式条目**：划掉的旧问题、「已解决（M4-x）」、里程碑编号、"已在真实服务器验证"这类记录都不再出现在用户文档里；
20
+ 只保留用户实际会遇到的行为，凭据细节统一链到 [docs/SECURITY.md](docs/SECURITY.md)。
21
+ - [SECURITY.md](docs/SECURITY.md) 同步去掉里程碑编号与历史叙述，改为陈述当前行为。
22
+ - 新增 [CONTRIBUTING.md](CONTRIBUTING.md)：源码断言的约定、DOM 测试模板、CSS 契约。
23
+
9
24
  ## [0.2.17] - 2026-10-29
10
25
 
11
26
  ### 修复
@@ -52,6 +67,7 @@
52
67
  - 64 个测试文件 / 915 个用例（含 jsdom 真实交互用例）；`pnpm audit --prod` 零已知漏洞。
53
68
  - `prepublishOnly` 强制跑 typecheck + test + build，过不了发不出去。
54
69
 
55
- [Unreleased]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.17...HEAD
70
+ [Unreleased]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.18...HEAD
71
+ [0.2.18]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.17...v0.2.18
56
72
  [0.2.17]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.16...v0.2.17
57
73
  [0.2.16]: https://github.com/WinKing-R/dsh-uniterminal/releases/tag/v0.2.16
package/README.md CHANGED
@@ -7,11 +7,24 @@
7
7
  SSH / SFTP / 端口转发，挂在 DSH 右侧栏里。**一个侧边栏标签里装多条会话**（顶部会话栏切换；同一台主机连两次显示 `#2`），
8
8
  每条会话的终端、文件、隧道三视图并列。
9
9
 
10
+ ## 截图
11
+
12
+ | 主机列表：分组 · 搜索 · 行内「测试 / 连接」，行尾 `⋯` 是其余操作 | 终端：一个侧边栏标签装多条会话，顶部会话栏切换（同一主机连两次显示 `#2`） |
13
+ |---|---|
14
+ | <img src="https://raw.githubusercontent.com/WinKing-R/dsh-uniterminal/main/docs/images/hosts.png" width="400"> | <img src="https://raw.githubusercontent.com/WinKing-R/dsh-uniterminal/main/docs/images/terminal.png" width="400"> |
15
+
16
+ | 连接表单：记住的密码交给**操作系统密码箱** | SFTP：目录浏览、上传下载、进度 | 外观：字体、字号、行高、主题模式 |
17
+ |---|---|---|
18
+ | <img src="https://raw.githubusercontent.com/WinKing-R/dsh-uniterminal/main/docs/images/connect-form.png" width="260"> | <img src="https://raw.githubusercontent.com/WinKing-R/dsh-uniterminal/main/docs/images/sftp.png" width="260"> | <img src="https://raw.githubusercontent.com/WinKing-R/dsh-uniterminal/main/docs/images/appearance.png" width="260"> |
19
+
20
+ > 截图使用演示数据（主机名 `demo01`–`demo03`，地址为 [RFC 5737](https://www.rfc-editor.org/rfc/rfc5737) 文档保留段 `192.0.2.0/24`）。
21
+ > 图片用**绝对 URL** 引用：npm 页面不解析相对路径，相对写法在 npmjs.com 上会显示破图。
22
+
10
23
  ## 状态
11
24
 
12
25
  | 项 | 值 |
13
26
  |---|---|
14
- | 版本 | `0.2.17`（`0.x`：API 与配置项仍可能变，按语义化版本升号；变更见 [CHANGELOG](CHANGELOG.md)） |
27
+ | 版本 | `0.2.18`（`0.x`：API 与配置项仍可能变，按语义化版本升号；变更见 [CHANGELOG](CHANGELOG.md)） |
15
28
  | 许可证 | **MIT**（见 [LICENSE](LICENSE)）——可自由使用、修改、商用，保留版权声明即可 |
16
29
  | 环境 | DSH `>=0.2.1-rc.2`、Node `>=20` |
17
30
 
@@ -27,33 +40,33 @@ SSH / SFTP / 端口转发，挂在 DSH 右侧栏里。**一个侧边栏标签里
27
40
  ## 安装
28
41
 
29
42
  前提：DSH `>=0.2.1-rc.2`（见本包 `package.json` 的 `dsh.engines`）、Node `>=20`。
30
- 从源码装还需要 pnpm；用打好的 `tgz` 安装则**不需要**自己构建。
31
43
 
32
- ### 右栏承载：官方 `sidebarRight` 或第三方 `DSH-better-sidebar`
44
+ ### 一条命令（推荐）
33
45
 
34
- 本插件**双注册 + 运行时探测**（`src/client/right-pane.ts`）：
46
+ DSH 自带 CLI 会把「装包 + 登记到 profile」一步做完：
35
47
 
36
- | 你的 DSH 里装了 | 插件注册到 | 结果 |
37
- |---|---|---|
38
- | [`DSH-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) | `ctx.betterSidebar`（**优先**） | 右栏像 IDE 那样多标签并存，本插件占一个标签 |
39
- | 只有官方 `@deepseek-ai/dsh-client-ui-sidebar-right` | `ctx.sidebarRightTabs` | 回落到官方右栏标签 |
48
+ ```bash
49
+ dsh plugin --profile desktop add @winking-r/dsh-uniterminal@latest
50
+ ```
40
51
 
41
- 两种都能用；**没有 better-sidebar 也能跑**（会自动回落）。
42
- 若右栏始终不出现本插件，先确认这两者至少有一个已启用——诊断见
43
- [`docs/acceptance-m0.md`](docs/acceptance-m0.md)（`target=none` 表示两套注册表都不可用）。
52
+ `--profile` 填你的 profile 名 —— `~/.dsh/profiles/` 下有哪些目录就用哪个（常见 `desktop` 或 `web`）。
53
+ 装完重启 DSH，右栏会出现 `UniTerminal` 标签。
54
+
55
+ > 没装 `dsh` 命令，或者要装本地构建（`link:` / `tgz`）时，用下面的手动方式，效果等价。
56
+
57
+ ### 手动方式（等价，两步）
44
58
 
45
59
  ```bash
46
- # 在 DSH 的 desktop profile 目录下执行
47
60
  cd ~/.dsh/profiles/desktop
48
61
 
49
- # 方式一：从 npm 安装（推荐，不需要 Node 工具链）
62
+ # npm 上的正式包
50
63
  pnpm add @winking-r/dsh-uniterminal
51
64
 
52
- # 方式二：从源码链接（改代码即生效，开发用）
53
- pnpm add "link:<你的本仓库绝对路径>"
65
+ # 或者：改代码即生效（开发用）
66
+ pnpm add "link:<本仓库绝对路径>"
54
67
 
55
- # 方式三：从目录安装（用打包好的 tgz）
56
- pnpm add "file:<tgz 的绝对路径>"
68
+ # 或者：装打包好的 tgz（不需要自己构建）
69
+ pnpm add "file:<tgz 绝对路径>"
57
70
  ```
58
71
 
59
72
  然后在 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 数组里追加一行本包名：
@@ -64,6 +77,19 @@ pnpm add "file:<tgz 的绝对路径>"
64
77
 
65
78
  重启 DSH。若右栏没有自动出现本插件，用右栏的 `+` 手动添加一个 `UniTerminal` 标签。
66
79
 
80
+ ### 右栏承载：官方 `sidebarRight` 或第三方 `DSH-better-sidebar`
81
+
82
+ 本插件**双注册 + 运行时探测**（`src/client/right-pane.ts`）：
83
+
84
+ | 你的 DSH 里装了 | 插件注册到 | 结果 |
85
+ |---|---|---|
86
+ | [`DSH-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) | `ctx.betterSidebar`（**优先**） | 右栏像 IDE 那样多标签并存，本插件占一个标签 |
87
+ | 只有官方 `@deepseek-ai/dsh-client-ui-sidebar-right` | `ctx.sidebarRightTabs` | 回落到官方右栏标签 |
88
+
89
+ 两种都能用；**没有 better-sidebar 也能跑**（会自动回落）。
90
+ 若右栏始终不出现本插件，先确认这两者至少有一个已启用 —— 诊断见
91
+ [`docs/acceptance-m0.md`](docs/acceptance-m0.md)（`target=none` 表示两套注册表都不可用）。
92
+
67
93
  > **改动代码后必须重启 DSH**：宿主半边（`lib/index.js`）在启动时加载，硬刷新页面不会生效。
68
94
 
69
95
  ### 卸载
@@ -80,7 +106,7 @@ pnpm remove @winking-r/dsh-uniterminal
80
106
 
81
107
  | 域 | 能力 |
82
108
  |---|---|
83
- | 主机 | 添加 / 编辑 / 删除（二次确认）/ 分组；从 `~/.ssh/config` 导入；连接前「测试」连通性；**孤儿会话可接管或关闭** |
109
+ | 主机 | 添加 / 编辑 / 删除（二次确认）/ 分组；从 `~/.ssh/config` 导入；连接前「测试」连通性；**孤儿会话可接管或关闭**（接管不需要重新输入密码） |
84
110
  | 认证 | 密码、私钥（读本地路径或粘贴内容）、**两者可同时启用**；按主机「记住密码」；跳板链 `ProxyJump` |
85
111
  | 终端 | xterm.js，自适应尺寸，断线重连；面板重挂载与**页面刷新**后会话与输出不丢（存档落 `sessionStorage`） |
86
112
  | 文件 | SFTP 浏览、多选上传（带进度、可取消）、下载、新建目录、删除 |
@@ -124,16 +150,14 @@ pnpm remove @winking-r/dsh-uniterminal
124
150
  - **没有** → 回落明文文件 `credentials.json`，靠 `chmod 0600` 与 Windows 账户目录权限保护；Windows 上 `chmod` 实际无效，真实防护来自 NTFS ACL。**不要在多用户共用的机器上勾选「记住密码」。**
125
151
  - **密码箱这一刻用不了**（被锁 / 服务没起）→ 临时改用本机文件，界面会明说；此前存在密码箱里的条目暂时取不到。
126
152
  界面表单页常驻小字会说明当前用的是哪一种（详见 [docs/SECURITY.md](docs/SECURITY.md)）。
127
- **不再提供插件自管的加密档位**：旧版那套「主密码 + 插件自管加密文件」已整体删除，既不提供也不支持。
128
- 本机若还留着旧版凭据文件，界面会提示「清理旧版凭据」。**清理只会丢弃旧格式文件里那份读不出来的数据——明文库里已记住的密码不受影响**；旧档里的那份密码需要重新输入一次。
153
+ 早期试用版若在本机留下旧格式凭据文件，界面会提示「清理旧版凭据」——**清理只删掉那份读不出来的旧数据，明文库里已记住的密码不受影响**。
129
154
  2. **不提供终端锁屏**（明确不做的决策，不是遗漏）。离开座位时已连接的会话没有保护——需要时请自行锁屏或断开连接。
130
- 3. **`-R` 远程转发**已在真实服务器（OpenSSH 9.9，`AllowTcpForwarding yes`）验证通路成立。仍未解决的是：**停止隧道不会立即释放服务端的远端端口**，要等会话关闭（ssh2 不提供 cancel-tcpip-forward）；在此期间到达的连接会被明确拒绝，不会穿透。
155
+ 3. **`-R` 远程转发**可用，但**停止隧道不会立即释放服务端的远端端口**，要等会话关闭（ssh2 不提供 cancel-tcpip-forward）；在此期间到达的连接会被明确拒绝，不会穿透。
131
156
  4. **跳板链每跳使用同一套凭据**（同一口令或同一私钥）。「跳板机用 A 钥、目标机用 B 钥」尚未支持。
132
157
  5. **覆盖式上传**优先用 OpenSSH 的 `posix-rename@openssh.com` 做原子替换；服务器不支持时会退化为「先删目标再改名」，存在极短窗口（目标暂时不存在）。
133
- 6. ~~没有会话列表 UI：刷新页面会丢失前端会话存档~~ → **已解决（M4-1）**：存档写入 `sessionStorage`，刷新后自动回到终端并重连；列表页会列出「未接管的会话」，可一键接管（无需重新输入密码）或关闭。
134
- 7. **SFTP 路径记忆、`-R` 端口即时释放**在待办中。终端锁屏已明确不做。
135
- 8. **shell 模式拒绝交互式/全屏程序**（vi/vim/nano/less/top/htop/watch/man/tmux/screen/ssh/su）：它们会占满用户终端、提示符回不来。按分段首词判定，sudo vim、xargs vim 之类仍可绕过——真正的防线是审计日志。若将来需要让 AI 驱动 TUI，主流做法是塞进 detached tmux 会话（send-keys + capture-pane），届时需要在服务器安装 tmux。
136
- 9. **AI 命令执行的安全边界**：工具默认开启，但只能操作**你已打开的会话**——AI 无法自行建立连接或提交凭据。每次执行都会写入 `diag.log`（命令预览截断 120 字符并 scrub 口令/私钥）。如不需要，把 `agentExec` 设为 `off`。
158
+ 6. **SFTP 路径记忆、`-R` 端口即时释放**在待办中。
159
+ 7. **shell 模式拒绝交互式/全屏程序**（vi/vim/nano/less/top/htop/watch/man/tmux/screen/ssh/su）：它们会占满用户终端、提示符回不来。按分段首词判定，sudo vim、xargs vim 之类仍可绕过——真正的防线是审计日志。
160
+ 8. **AI 命令执行的安全边界**：工具默认开启，但只能操作**你已打开的会话**——AI 无法自行建立连接或提交凭据。每次执行都会写入 `diag.log`（命令预览截断 120 字符并 scrub 口令/私钥）。如不需要，把 `agentExec` 设为 `off`。
137
161
 
138
162
  ## 结构
139
163
 
package/docs/SECURITY.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # 安全说明（UniTerminal 凭据存储）
2
2
 
3
3
  > 这一份是**凭据存储**的对外说明：威胁模型、边界、密码存在哪、怎么清、已知限制。
4
- > 相关台账：`docs/superpowers/plans/ledger-m0.md` 的 M65（删掉自研密码学）与 M66（接操作系统密码箱）。
4
+ > 设计与取舍的完整记录见 `docs/superpowers/plans/ledger-m0.md`。
5
5
 
6
6
  ## 一、威胁模型
7
7
 
@@ -42,9 +42,9 @@
42
42
  `secret` 的字段一律被路由层拒绝（`CREDENTIAL_FIELDS` 白名单）。
43
43
  3. **密码永远不进日志与诊断。**
44
44
  `diag.log` 与 `reportClient()` 上报里只有 id、状态、类别；写入失败时错误消息里的密码会被 `scrub` 抹掉。
45
- 4. **密码永远不落进插件自己的加密文件。**
46
- 插件**不实现任何加密**：上一批的自研密码学（主密码 + scrypt + AES-256-GCM）已整体删除，
47
- 那是一段"走不到"的攻击面。现在要么交给操作系统密码箱，要么明文文件（并如实说明）。
45
+ 4. **插件不自己实现加密。**
46
+ 密码只有两个去处：**操作系统密码箱**，或**明文文件**（并在界面如实说明当前是哪种）。
47
+ 不存在"插件自建加密、由插件保管密钥"这条路。
48
48
 
49
49
  ## 三、密码存在哪
50
50
 
@@ -109,6 +109,6 @@ Linux 上不显式指定后端时，底层库会"Secret Service → 内核 keyri
109
109
  5. **Linux 上没有 Secret Service**（无 GNOME Keyring / KWallet 的精简桌面）时，
110
110
  插件会走文件后端并明说——**不会**退到内核 keyring（不跨重启）。
111
111
  6. **没有终端锁屏**：离开座位时已建立的会话没有任何保护，需要时请自行锁屏或断开连接。
112
- 7. **插件不提供自研加密**（主密码 / 自建加密文件已整体删除，见台账 M65）。
112
+ 7. **插件不提供自研加密**：没有"插件保管密钥"这条路。
113
113
  需要更强的保护时，请用操作系统的全盘加密与账户隔离。
114
114
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@winking-r/dsh-uniterminal",
3
- "version": "0.2.17",
3
+ "version": "0.2.18",
4
4
  "description": "在 DSH 右侧栏里提供 SSH 终端、SFTP 文件管理与端口转发的插件；密码交给操作系统密码箱保管，插件自身不实现加密。",
5
5
  "keywords": [
6
6
  "dsh",