@winking-r/dsh-uniterminal 0.2.16 → 0.2.18

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# 更新日志
+
+遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+`0.x` 阶段：**次要版本可能包含不兼容变更**（配置项与插件 API 仍可能调整），补丁版本只修缺陷。
+
+## [Unreleased]
+
+## [0.2.18] - 2026-10-29
+
+纯文档版本，**代码与 0.2.17 完全相同**。
+
+### 文档
+
+- README 新增**截图**（主机列表 / 终端 / 连接表单 / SFTP / 外观）：演示数据为 `demo01`–`demo03` 与 RFC 5737 文档段 `192.0.2.0/24`；
+  图片经绝对 URL 引用，npm 页面同样能显示。
+- 安装说明改为**一条命令**：`dsh plugin --profile <profile 名> add @winking-r/dsh-uniterminal@latest`；
+  手工方式（`pnpm add` + 编辑 `dsh.profile.bundles`）作为备选保留。
+- **已知限制去掉开发日志式条目**：划掉的旧问题、「已解决（M4-x）」、里程碑编号、"已在真实服务器验证"这类记录都不再出现在用户文档里；
+  只保留用户实际会遇到的行为，凭据细节统一链到 [docs/SECURITY.md](docs/SECURITY.md)。
+- [SECURITY.md](docs/SECURITY.md) 同步去掉里程碑编号与历史叙述，改为陈述当前行为。
+- 新增 [CONTRIBUTING.md](CONTRIBUTING.md)：源码断言的约定、DOM 测试模板、CSS 契约。
+
+## [0.2.17] - 2026-10-29
+
+### 修复
+
+- **行尾「更多操作」按钮的菜单被面板右边缘裁掉**：锚点靠右时菜单仍向右伸展，伸出面板后被宿主的
+  `overflow` 裁掉，「移入分组…」「测试连接」只显示半截。现在锚点过半宽时改为**右对齐、向左展开**；
+  鼠标右键、`Shift+F10`/菜单键、「⋯」按钮三条入口共用同一套判定（`src/client/menu-anchor.ts`）。
+
+### 文档
+
+- 新增 `CONTRIBUTING.md`：源码断言的约定（改 CSS/文案要同步更新断言、不要删断言）、
+  DOM 测试模板（`// @vitest-environment jsdom` + `afterEach(cleanup)`）、CSS 契约、
+  以及**禁止用固定字符数切源码**这条踩过两次的坑。
+- README 补「右栏承载」一节：装了 `DSH-better-sidebar` 优先注册到 `ctx.betterSidebar`，
+  否则回落官方 `sidebarRightTabs`。
+
+## [0.2.16] - 2026-10-29
+
+首个公开发布版本（MIT）。
+
+### 新增
+
+- SSH 终端（xterm.js）、SFTP 文件管理、端口转发（`-L` / `-R` / `-D`）、跳板链、分组管理、外观设置。
+- 一个侧边栏标签装多条会话，顶部会话栏切换；同一主机连两次显示 `#2`；刷新页面自动接回会话。
+- **凭据交给操作系统密码箱**（Windows 凭据管理器 / macOS 钥匙串 / Linux Secret Service），
+  插件自身不实现任何加密；只有机器没有系统密码箱时才回落明文文件（0600 + 原子写），并在界面如实说明。
+- 失败提示区分 7 类原因（超时 / 拒绝 / DNS / 不可达 / 主机指纹 / 认证 / 未知）并给出下一步动作；
+  内部字段名不再出现在界面上（细节只进 diag）。
+
+### 无障碍
+
+- 右键菜单与确认弹框：打开即聚焦、方向键/Home/End、`Tab` 焦点陷阱、关闭后**把焦点还给触发元素**。
+- 提示条改为常驻 live region（成功 `status/polite`、失败 `alert/assertive`），读屏能听见错误。
+- SFTP 文件行支持键盘选中（`aria-pressed`）；主机行「连接 / 测试」的可访问名带主机名。
+
+### 设计
+
+- 引入 token 层（字号 13/14/16 三级阶梯、圆角 4/6/10/999、灰阶与遮罩、语义色单一来源）。
+- 内联样式收敛 66%（541 → 182 条声明）；重复选择器 4 组 → 0 组。
+
+### 质量
+
+- 严格 TypeScript（`strict` + `noUncheckedIndexedAccess`）：`:any` 与 `@ts-ignore` 均为 0。
+- 64 个测试文件 / 915 个用例（含 jsdom 真实交互用例）；`pnpm audit --prod` 零已知漏洞。
+- `prepublishOnly` 强制跑 typecheck + test + build，过不了发不出去。
+
+[Unreleased]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.18...HEAD
+[0.2.18]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.17...v0.2.18
+[0.2.17]: https://github.com/WinKing-R/dsh-uniterminal/compare/v0.2.16...v0.2.17
+[0.2.16]: https://github.com/WinKing-R/dsh-uniterminal/releases/tag/v0.2.16

package/README.md

@@ -1,13 +1,30 @@
 # UniTerminal · DSH 远程终端插件
 
+[![npm](https://img.shields.io/npm/v/@winking-r/dsh-uniterminal.svg)](https://www.npmjs.com/package/@winking-r/dsh-uniterminal)
+[![license](https://img.shields.io/npm/l/@winking-r/dsh-uniterminal.svg)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-WinKing--R%2Fdsh--uniterminal-blue)](https://github.com/WinKing-R/dsh-uniterminal)
+
 SSH / SFTP / 端口转发，挂在 DSH 右侧栏里。**一个侧边栏标签里装多条会话**（顶部会话栏切换；同一台主机连两次显示 `#2`），
 每条会话的终端、文件、隧道三视图并列。
 
+## 截图
+
+| 主机列表：分组 · 搜索 · 行内「测试 / 连接」，行尾 `⋯` 是其余操作 | 终端：一个侧边栏标签装多条会话，顶部会话栏切换（同一主机连两次显示 `#2`） |
+|---|---|
+| <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"> |
+
+| 连接表单：记住的密码交给**操作系统密码箱** | SFTP：目录浏览、上传下载、进度 | 外观：字体、字号、行高、主题模式 |
+|---|---|---|
+| <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"> |
+
+> 截图使用演示数据（主机名 `demo01`–`demo03`，地址为 [RFC 5737](https://www.rfc-editor.org/rfc/rfc5737) 文档保留段 `192.0.2.0/24`）。
+> 图片用**绝对 URL** 引用：npm 页面不解析相对路径，相对写法在 npmjs.com 上会显示破图。
+
 ## 状态
 
 | 项 | 值 |
 |---|---|
-| 版本 | `0.2.16`（`0.x`：API 与配置项仍可能变，按语义化版本升号） |
+| 版本 | `0.2.18`（`0.x`：API 与配置项仍可能变，按语义化版本升号；变更见 [CHANGELOG](CHANGELOG.md)） |
 | 许可证 | **MIT**（见 [LICENSE](LICENSE)）——可自由使用、修改、商用，保留版权声明即可 |
 | 环境 | DSH `>=0.2.1-rc.2`、Node `>=20` |
 
@@ -23,17 +40,33 @@ SSH / SFTP / 端口转发，挂在 DSH 右侧栏里。**一个侧边栏标签里
 ## 安装
 
 前提：DSH `>=0.2.1-rc.2`（见本包 `package.json` 的 `dsh.engines`）、Node `>=20`。
-从源码装还需要 pnpm；用打好的 `tgz` 安装则**不需要**自己构建。
+
+### 一条命令（推荐）
+
+DSH 自带 CLI 会把「装包 + 登记到 profile」一步做完：
+
+```bash
+dsh plugin --profile desktop add @winking-r/dsh-uniterminal@latest
+```
+
+`--profile` 填你的 profile 名 —— `~/.dsh/profiles/` 下有哪些目录就用哪个（常见 `desktop` 或 `web`）。
+装完重启 DSH，右栏会出现 `UniTerminal` 标签。
+
+> 没装 `dsh` 命令，或者要装本地构建（`link:` / `tgz`）时，用下面的手动方式，效果等价。
+
+### 手动方式（等价，两步）
 
 ```bash
-# 在 DSH 的 desktop profile 目录下执行
 cd ~/.dsh/profiles/desktop
 
-# 方式一：从源码链接（改代码即生效，开发用）
-pnpm add "link:<你的本仓库绝对路径>"
+# npm 上的正式包
+pnpm add @winking-r/dsh-uniterminal
+
+# 或者：改代码即生效（开发用）
+pnpm add "link:<本仓库绝对路径>"
 
-# 方式二：从目录安装（用打包好的 tgz，无需 Node 工具链）
-pnpm add "file:<tgz 的绝对路径>"
+# 或者：装打包好的 tgz（不需要自己构建）
+pnpm add "file:<tgz 绝对路径>"
 ```
 
 然后在 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 数组里追加一行本包名：
@@ -44,6 +77,19 @@ pnpm add "file:<tgz 的绝对路径>"
 
 重启 DSH。若右栏没有自动出现本插件，用右栏的 `+` 手动添加一个 `UniTerminal` 标签。
 
+### 右栏承载：官方 `sidebarRight` 或第三方 `DSH-better-sidebar`
+
+本插件**双注册 + 运行时探测**（`src/client/right-pane.ts`）：
+
+| 你的 DSH 里装了 | 插件注册到 | 结果 |
+|---|---|---|
+| [`DSH-better-sidebar`](https://github.com/omdsh-dev/DSH-better-sidebar) | `ctx.betterSidebar`（**优先**） | 右栏像 IDE 那样多标签并存，本插件占一个标签 |
+| 只有官方 `@deepseek-ai/dsh-client-ui-sidebar-right` | `ctx.sidebarRightTabs` | 回落到官方右栏标签 |
+
+两种都能用；**没有 better-sidebar 也能跑**（会自动回落）。
+若右栏始终不出现本插件，先确认这两者至少有一个已启用 —— 诊断见
+[`docs/acceptance-m0.md`](docs/acceptance-m0.md)（`target=none` 表示两套注册表都不可用）。
+
 > **改动代码后必须重启 DSH**：宿主半边（`lib/index.js`）在启动时加载，硬刷新页面不会生效。
 
 ### 卸载
@@ -60,7 +106,7 @@ pnpm remove @winking-r/dsh-uniterminal
 
 | 域 | 能力 |
 |---|---|
-| 主机 | 添加 / 编辑 / 删除（二次确认）/ 分组；从 `~/.ssh/config` 导入；连接前「测试」连通性；**孤儿会话可接管或关闭** |
+| 主机 | 添加 / 编辑 / 删除（二次确认）/ 分组；从 `~/.ssh/config` 导入；连接前「测试」连通性；**孤儿会话可接管或关闭**（接管不需要重新输入密码） |
 | 认证 | 密码、私钥（读本地路径或粘贴内容）、**两者可同时启用**；按主机「记住密码」；跳板链 `ProxyJump` |
 | 终端 | xterm.js，自适应尺寸，断线重连；面板重挂载与**页面刷新**后会话与输出不丢（存档落 `sessionStorage`） |
 | 文件 | SFTP 浏览、多选上传（带进度、可取消）、下载、新建目录、删除 |
@@ -104,16 +150,14 @@ pnpm remove @winking-r/dsh-uniterminal
    - **没有** → 回落明文文件 `credentials.json`，靠 `chmod 0600` 与 Windows 账户目录权限保护；Windows 上 `chmod` 实际无效，真实防护来自 NTFS ACL。**不要在多用户共用的机器上勾选「记住密码」。**
    - **密码箱这一刻用不了**（被锁 / 服务没起）→ 临时改用本机文件，界面会明说；此前存在密码箱里的条目暂时取不到。
    界面表单页常驻小字会说明当前用的是哪一种（详见 [docs/SECURITY.md](docs/SECURITY.md)）。
-   **不再提供插件自管的加密档位**：旧版那套「主密码 + 插件自管加密文件」已整体删除，既不提供也不支持。
-   本机若还留着旧版凭据文件，界面会提示「清理旧版凭据」。**清理只会丢弃旧格式文件里那份读不出来的数据——明文库里已记住的密码不受影响**；旧档里的那份密码需要重新输入一次。
+   早期试用版若在本机留下旧格式凭据文件，界面会提示「清理旧版凭据」——**清理只删掉那份读不出来的旧数据，明文库里已记住的密码不受影响**。
 2. **不提供终端锁屏**（明确不做的决策，不是遗漏）。离开座位时已连接的会话没有保护——需要时请自行锁屏或断开连接。
-3. **`-R` 远程转发**已在真实服务器（OpenSSH 9.9，`AllowTcpForwarding yes`）验证通路成立。仍未解决的是：**停止隧道不会立即释放服务端的远端端口**，要等会话关闭（ssh2 不提供 cancel-tcpip-forward）；在此期间到达的连接会被明确拒绝，不会穿透。
+3. **`-R` 远程转发**可用，但**停止隧道不会立即释放服务端的远端端口**，要等会话关闭（ssh2 不提供 cancel-tcpip-forward）；在此期间到达的连接会被明确拒绝，不会穿透。
 4. **跳板链每跳使用同一套凭据**（同一口令或同一私钥）。「跳板机用 A 钥、目标机用 B 钥」尚未支持。
 5. **覆盖式上传**优先用 OpenSSH 的 `posix-rename@openssh.com` 做原子替换；服务器不支持时会退化为「先删目标再改名」，存在极短窗口（目标暂时不存在）。
-6. ~~没有会话列表 UI：刷新页面会丢失前端会话存档~~ → **已解决（M4-1）**：存档写入 `sessionStorage`，刷新后自动回到终端并重连；列表页会列出「未接管的会话」，可一键接管（无需重新输入密码）或关闭。
-7. **SFTP 路径记忆、`-R` 端口即时释放**在待办中。终端锁屏已明确不做。
-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。
-9. **AI 命令执行的安全边界**：工具默认开启，但只能操作**你已打开的会话**——AI 无法自行建立连接或提交凭据。每次执行都会写入 `diag.log`（命令预览截断 120 字符并 scrub 口令/私钥）。如不需要，把 `agentExec` 设为 `off`。
+6. **SFTP 路径记忆、`-R` 端口即时释放**在待办中。
+7. **shell 模式拒绝交互式/全屏程序**（vi/vim/nano/less/top/htop/watch/man/tmux/screen/ssh/su）：它们会占满用户终端、提示符回不来。按分段首词判定，sudo vim、xargs vim 之类仍可绕过——真正的防线是审计日志。
+8. **AI 命令执行的安全边界**：工具默认开启，但只能操作**你已打开的会话**——AI 无法自行建立连接或提交凭据。每次执行都会写入 `diag.log`（命令预览截断 120 字符并 scrub 口令/私钥）。如不需要，把 `agentExec` 设为 `off`。
 
 ## 结构
 

package/docs/SECURITY.md

@@ -1,7 +1,7 @@
 # 安全说明（UniTerminal 凭据存储）
 
 > 这一份是**凭据存储**的对外说明：威胁模型、边界、密码存在哪、怎么清、已知限制。
-> 相关台账：`docs/superpowers/plans/ledger-m0.md` 的 M65（删掉自研密码学）与 M66（接操作系统密码箱）。
+> 设计与取舍的完整记录见 `docs/superpowers/plans/ledger-m0.md`。
 
 ## 一、威胁模型
 
@@ -42,9 +42,9 @@
    `secret` 的字段一律被路由层拒绝（`CREDENTIAL_FIELDS` 白名单）。
 3. **密码永远不进日志与诊断。**
    `diag.log` 与 `reportClient()` 上报里只有 id、状态、类别；写入失败时错误消息里的密码会被 `scrub` 抹掉。
-4. **密码永远不落进插件自己的加密文件。**
-   插件**不实现任何加密**：上一批的自研密码学（主密码 + scrypt + AES-256-GCM）已整体删除，
-   那是一段"走不到"的攻击面。现在要么交给操作系统密码箱，要么明文文件（并如实说明）。
+4. **插件不自己实现加密。**
+   密码只有两个去处：**操作系统密码箱**，或**明文文件**（并在界面如实说明当前是哪种）。
+   不存在"插件自建加密、由插件保管密钥"这条路。
 
 ## 三、密码存在哪
 
@@ -109,6 +109,6 @@ Linux 上不显式指定后端时，底层库会"Secret Service → 内核 keyri
 5. **Linux 上没有 Secret Service**（无 GNOME Keyring / KWallet 的精简桌面）时，
    插件会走文件后端并明说——**不会**退到内核 keyring（不跨重启）。
 6. **没有终端锁屏**：离开座位时已建立的会话没有任何保护，需要时请自行锁屏或断开连接。
-7. **插件不提供自研加密**（主密码 / 自建加密文件已整体删除，见台账 M65）。
+7. **插件不提供自研加密**：没有"插件保管密钥"这条路。
    需要更强的保护时，请用操作系统的全盘加密与账户隔离。
 

package/lib/client.js

@@ -1404,6 +1404,7 @@ window.__ModuleLoader__.load({
 				"aria-label": props.label,
 				style: {
 					left: props.left,
+					right: props.right,
 					top: props.top
 				},
 				onMouseDown: (event) => event.stopPropagation(),
@@ -1426,6 +1427,23 @@ window.__ModuleLoader__.load({
 				}, item.label))
 			});
 		}
+		// src/client/menu-anchor.ts
+		/**
+		* @param anchorX 锚点的横向位置（相对面板左边缘，像素）
+		* @param anchorY 锚点的纵向位置（相对面板上边缘，像素）
+		* @param paneWidth 面板宽度；0 或未知时退回左对齐（总比跑到面板外好）
+		*/
+		function menuAnchor(anchorX, anchorY, paneWidth) {
+			const top = Math.max(0, anchorY);
+			if (paneWidth > 0 && anchorX > paneWidth / 2) return {
+				right: Math.max(0, paneWidth - anchorX),
+				top
+			};
+			return {
+				left: Math.max(0, anchorX),
+				top
+			};
+		}
 		// src/client/host-filter.ts
 		/**
 		* 主机/分组搜索。
@@ -2270,11 +2288,9 @@ window.__ModuleLoader__.load({
 			*/
 			function anchorOf(element) {
 				const rect = element.getBoundingClientRect();
-				const pane = paneRef.current?.getBoundingClientRect();
-				return {
-					left: rect.left - (pane?.left ?? 0),
-					top: rect.bottom - (pane?.top ?? 0)
-				};
+				const pane = paneRef.current;
+				const paneRect = pane?.getBoundingClientRect();
+				return menuAnchor(rect.right - (paneRect?.left ?? 0), rect.bottom - (paneRect?.top ?? 0), pane?.clientWidth ?? 0);
 			}
 			/** 打开主机菜单：trigger 既当锚点，也是关闭后焦点要回的元素。 */
 			function openRowMenu(trigger, profileId) {
@@ -2316,10 +2332,10 @@ window.__ModuleLoader__.load({
 						},
 						onContextMenu: (event) => {
 							event.preventDefault();
-							const rect = paneRef.current?.getBoundingClientRect();
+							const pane = paneRef.current;
+							const rect = pane?.getBoundingClientRect();
 							setMenu({
-								left: event.clientX - (rect?.left ?? 0),
-								top: event.clientY - (rect?.top ?? 0),
+								...menuAnchor(event.clientX - (rect?.left ?? 0), event.clientY - (rect?.top ?? 0), pane?.clientWidth ?? 0),
 								profileId: profile.id,
 								trigger: event.currentTarget
 							});
@@ -2754,10 +2770,10 @@ window.__ModuleLoader__.load({
 										},
 										onContextMenu: (event) => {
 											event.preventDefault();
-											const rect = paneRef.current?.getBoundingClientRect();
+											const pane = paneRef.current;
+											const rect = pane?.getBoundingClientRect();
 											setGroupMenu({
-												left: event.clientX - (rect?.left ?? 0),
-												top: event.clientY - (rect?.top ?? 0),
+												...menuAnchor(event.clientX - (rect?.left ?? 0), event.clientY - (rect?.top ?? 0), pane?.clientWidth ?? 0),
 												groupId: node.id,
 												trigger: event.currentTarget
 											});
@@ -2904,6 +2920,7 @@ window.__ModuleLoader__.load({
 						if (target === void 0) return null;
 						return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ContextMenu, {
 							left: menu.left,
+							right: menu.right,
 							top: menu.top,
 							label: "主机 " + target.name + " 的操作",
 							returnFocusTo: menu.trigger,
@@ -2937,6 +2954,7 @@ window.__ModuleLoader__.load({
 						if (node === void 0) return null;
 						return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ContextMenu, {
 							left: groupMenu.left,
+							right: groupMenu.right,
 							top: groupMenu.top,
 							label: "分组 " + node.path.join(" / ") + " 的操作",
 							returnFocusTo: groupMenu.trigger,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@winking-r/dsh-uniterminal",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "在 DSH 右侧栏里提供 SSH 终端、SFTP 文件管理与端口转发的插件；密码交给操作系统密码箱保管，插件自身不实现加密。",
   "keywords": [
     "dsh",
@@ -36,6 +36,7 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
+    "CHANGELOG.md",
     "docs/SECURITY.md"
   ],
   "publishConfig": {