@nacocx/dsh-ui-context-menu

Readme

# @nacocx/dsh-ui-context-menu

中文 | [English](README.en.md)

这是一个可独立安装的 DeepSeek Harness 树外组合包，用应用自身的右键策略替代浏览器 `contextmenu` 手势。真实 Workspace 行获得完全由插件持有的菜单（在文件管理器中打开 / 重命名 / 删除），非空白 Session 行获得重命名 / 分叉会话 / 归档会话，空白处打开创建新会话 / 创建新工作区 / 设置，指针下的文本选区获得复制 / 剪切 / 搜索 / 浏览器搜索，可编辑文本框获得粘贴优先的编辑菜单。每个区域都可以在 设置 → 插件 中独立开关，关闭某区域即为该区域恢复浏览器原生右键菜单，效果等同于插件不在场。

## 行为

- **工作区行。** 真实 Workspace 行打开完全由插件持有的菜单：在文件管理器中打开、重命名、删除工作区。在文件管理器中打开经 `workspace.list` 解析该行规范目录，再通过 Harness 宿主机原生打开器在系统默认文件管理器中打开；重命名与删除打开插件自有的对话框（规则与文案和默认菜单一致：未修改的草稿禁用、重名拒绝、删除说明保留内容），并通过宿主公开 `/api`（`workspace.rename` / `workspace.delete`）提交。行自带的省略号菜单仍然存在且不变，只是不再是右键入口。Ungrouped 保持原生右键菜单。
- **会话行。** 非空白 Session 行打开完全由插件持有的菜单：重命名、分叉会话、归档会话。重命名打开插件自有对话框（默认规则：空草稿禁用、未修改允许——确认当前自动标题即为固定标题的手势），经 `session.rename` 提交；分叉复刻默认的持久标题递增（`session.fork` + `session.rename`）并尽力打开子会话行；归档经 `workspace.archiveSession` 直接提交。显示标题无法唯一解析到某个会话的行会回退到该行自己的操作菜单。空白「新会话」和搜索结果行保持浏览器原生右键菜单。
- **空白处。** 在没有文本、没有选区、没有交互控件的空白处右键会打开应用菜单：创建新会话（当前会话所在分组的「新建会话」按钮，否则第一个工作区分组的，再否则侧边栏的全局按钮）、创建新工作区（工作区标题栏的添加按钮）、设置（侧边栏设置触发器）。触发器缺失的条目显示为禁用。
- **选中文本。** 在覆盖指针的非折叠文本选区上右键打开复制 / 剪切 / 搜索 / 浏览器搜索。搜索会把选中文本填入工作区会话搜索框（侧边栏折叠时先展开），没有搜索界面时退回页面内查找；浏览器搜索会在系统默认浏览器中打开针对选中文本的 Bing 搜索——浏览器中走 `window.open`，打包应用暴露 Tauri opener 插件或 Electron shell 时走对应桥接，否则走 Harness 宿主机自带的原生打开器（`POST /api/host.openPath`，与 GUI 打开文件同一条路由），因此官方 Tauri 桌面端无需任何改动即可工作。
- **文本框。** 在文本输入框、textarea 或 `contenteditable` 内右键打开粘贴 / 复制 / 剪切 / 全选。文本条目使用浏览器编辑命令，复制、剪切、粘贴带剪贴板 API 回退。
- **其他区域。** 其余交互控件与文本内容保持浏览器原生右键菜单。

卸载本组合包会恢复全部原生右键菜单，但不会移除省略号入口。

## 配置

设置 → 插件 → 可配置插件页中的「右键菜单」卡片为每个区域提供一个开关（工作区行、会话行、空白处、文本框、选中文本），另有「恢复默认设置」。关闭某区域会为该区域恢复浏览器原生右键菜单，效果等同于插件不在场——其余区域不受影响。策略保存在浏览器本地存储中，因此跟随浏览器或 WebView，而非宿主机设置文件。

## 兼容性

本插件适配 `@deepseek-ai/dsh-client-ui-workspace`（`>=0.1.0-rc.5 <0.2.0`）已经发布的无障碍 Workspace 树结构，以及侧边栏外壳的「新建会话」与设置触发器。它不依赖未发布的 Harness 服务，也不要求修改内置包，因此同一份 bundle 可以同时用于浏览器和打包后的 Tauri WebView。

应用触发器发现固定了两套已发布词典（简体中文与英文）的文案。未来新增语言或 `ui-workspace`、`ui-sidebar` 修改文案时，本插件可能需要兼容性更新。

### 安全模型

插件对 Harness 宿主的访问不超出 GUI 自身已有的调用：菜单动作全部走 Web GUI 同源的 `/api` RPC 网关（`workspace.list`、`host.openPath`、`workspace.rename`、`workspace.delete`、`session.list`、`session.rename`、`session.fork`、`workspace.archiveSession`）。特权方法（`host.openPath`）受宿主自身信任栅栏的回环限制，服务给非回环客户端的 GUI 会静默降级到回退路径。插件不读写任何密钥、凭据或模型输入；策略只存在于浏览器本地存储。

## 从 registry 安装

```sh
dsh plugin --profile web add @nacocx/dsh-ui-context-menu
dsh --profile web
```

该包声明了 `dsh.bundle`，所以安装时会把自身的 `cordis.patch.yml` 层加入 profile。从 registry 安装的包已包含构建好的 `lib/`，不需要安装期构建授权。更新到新版本只需再次运行同一条 `add` 命令。卸载命令：

```sh
dsh plugin --profile web remove @nacocx/dsh-ui-context-menu
```

## 从本地检出安装

先构建并验证仓库：

```sh
pnpm install
pnpm run check
```

在本仓库目录中把检出安装到 Web profile：

```sh
dsh plugin --profile web add .
dsh --profile web
```

该包声明了 `dsh.bundle`，所以安装时会把自身的 `cordis.patch.yml` 层加入 profile。卸载命令：

```sh
dsh plugin --profile web remove @nacocx/dsh-ui-context-menu
```

## 从 Git 安装

Git 安装会运行包内自包含的 `prepare` 脚本。pnpm 10 及更高版本要求 profile 显式允许该构建；请固定已审查的提交，并按 `dsh plugin` 打印的准确 `allowBuilds` 诊断设置后重试。

```sh
dsh plugin --profile web add github:<owner>/dsh-ui-context-menu#<commit>
```

从 registry 安装的包或 `pnpm pack` 生成的 tarball 已包含构建好的 `lib/`，不需要安装期构建授权。

## 常见问题

- **安装后右键行为没有变化。** Harness 在服务启动时解析 bundle 列表：重启 `dsh --profile web`（仅刷新页面不会重新装载 bundle 清单）。
- **浏览器搜索或「在文件管理器中打开」没有反应。** 这两项复用 Harness 宿主受回环限制的原生打开器；服务给非回环客户端的 GUI 会保留回退路径（浏览器走锚点点击，文件管理器则无操作），限制剪贴板的 WebView 也可能拒绝粘贴。
- **配置被重置。** 策略保存在浏览器本地存储中；清除浏览器配置后所有开关恢复默认开启。

## 开发

```sh
pnpm run typecheck
pnpm run test
pnpm run build
pnpm run pack:check
```

浏览器产物使用 DeepSeek Harness 模块加载器闭包，且没有运行时 import（React 是加载器的 shell 自有模块，不打进 bundle）。一个文档级捕获监听器对指针表面分类——工作区行、会话行、可编辑字段、指针下的选区、交互控件或空白处——然后打开插件自有的覆盖层（菜单，以及重命名/删除对话框）或复用该表面已有的触发器。每个菜单都是按表面组织的声明式条目表，每个宿主动作都走同一个共享 `/api` RPC 助手，因此未来新增条目只需加一行表项加一行调用。监听器、覆盖层、对话框、待执行的搜索重试、注入的样式表全部通过 `ctx.effect()` 注册并在卸载时移除；peer dependency 固定了已验证的 `ui-workspace` 范围，jsdom 测试套件覆盖所有分支与卸载行为。

架构说明、新增条目的扩展指南与发布流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 模型体验

无。本插件只添加浏览器输入手势，不注册 prompt、工具、消息或 provider 输入。

## 已知限制

- 行菜单仍锚定在其省略号按钮，而不是精确的指针坐标；只有插件自有的覆盖层锚定在指针处。
- 粘贴与剪贴板回退依赖浏览器或 WebView 授予剪贴板访问；访问被拒绝时条目仍在，但操作可能无效。
- 浏览器搜索与「在文件管理器中打开」只有在页面由 Harness 宿主机本身提供时才会回退到宿主原生打开器（`/api/host.openPath`，目录经 `workspace.list` 解析）；服务给非回环客户端的 GUI 会保留锚点回退，因为回环信任栅栏会在那里拒绝特权方法。
- 覆盖层文案跟随可见工作区树的本地化 `aria-label`，树未挂载（折叠的 rail）时回退为中文。
- 固定文案的触发器发现是与已验证的 `ui-workspace`、侧边栏范围之间的兼容性边界；未来大版本可能需要更新。
- 配置策略保存在浏览器本地存储中；不会跨浏览器同步，浏览器配置清空后会重置。

## 许可证

[MIT](LICENSE) — 版权所有 (c) 2026 Nacocx