# permission-popup：DSH 权限审批弹窗

[English](./README.md)

这是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI 的社区插件。当当前会话或后台会话正在等待权限审批时，插件会在页面角落显示审批卡片，让你无需切回原会话就能选择“允许一次”或“拒绝”。

> 本项目是社区插件，不是 DeepSeek 官方插件。

## 功能

- 集中显示多个会话中的待审批请求。
- 展示会话标题、工具名称、申请理由，以及可以解析到的 Shell 命令。
- 通过 DSH 原有审批通道执行“允许一次”或“拒绝”，不绕过权限系统。
- 支持三种触发策略：`background`、`always`、`hidden-only`。
- 可以设置弹窗角落、最大堆栈数量、失焦行为、桌面通知和标签页标题提醒。
- 设置保存在浏览器本地，刷新页面后仍然有效。
- 不增加模型提示词、模型请求、Token 消耗或 KV Cache 内容。

## 环境要求

- 与 `0.1.1-rc.2` 客户端包兼容的较新 DeepSeek Harness 版本。
- DSH 的 `web` Profile，以及其中标准的客户端 runtime、locale 和 UI layout 组合包。
- 从源码运行 DSH 时，需要 Node.js `^22.19.0 || >=24.0.0`。

DeepSeek Harness 目前仍处于预发布阶段，第一次正式发布前，插件 API 和兼容要求可能变化。

## 从 GitHub 安装

安装到 Web Profile：

```sh
dsh plugin --profile web add github:wxjgit/permission-popup
```

如果你从 DeepSeek Harness 源码仓库运行，请使用：

```sh
pnpm dsh plugin --profile web add github:wxjgit/permission-popup
```

安装完成后重启 Web UI：

```sh
dsh web
```

源码运行方式：

```sh
pnpm dsh web
```

启动前也可以检查组合后的配置：

```sh
dsh --profile web --dump-config
```

输出中应当包含 `dsh-plugin-permission-popup` 配置层和 `permission-popup` 加载项。

## 更新

再次执行 GitHub 安装命令即可获取默认分支上的最新版本：

```sh
dsh plugin --profile web add github:wxjgit/permission-popup
```

生产或重要环境建议固定到经过审查的 Commit：

```sh
dsh plugin --profile web add github:wxjgit/permission-popup#<commit-sha>
```

更新后需要重启 `dsh web`。

## 卸载

```sh
dsh plugin --profile web remove dsh-plugin-permission-popup
```

## 使用方法

插件随 Web Profile 自动启动，不需要额外执行命令。当某个审批符合当前触发策略时，页面角落会显示卡片。

- 点击“允许一次”只批准当前这次请求。
- 点击“拒绝”拒绝当前请求。
- 点击卡片顶部的琥珀色区域可以打开对应会话。
- 点击卡片底部齿轮可以设置触发策略、显示角落、最大堆栈数量、桌面通知和标签页标题提醒。

默认策略是 `background`：审批来自非当前会话，或者浏览器标签页处于隐藏状态时显示卡片。

### 浏览器隐藏或最小化

角落卡片属于浏览器页面，浏览器最小化后不可能继续显示在 Windows 桌面上。这不是 CSS 层级问题。如果需要离开浏览器后继续收到提醒，请在插件设置中启用“窗口隐藏时发送桌面通知”，并允许该网站发送通知。

新的审批到来后，Windows 会显示系统通知；点击通知会恢复浏览器并打开对应会话。同一个审批最多提醒一次，反复隐藏窗口不会对同一条待审批请求重复通知。

## 安全与隐私

- 插件不会绕过 DSH 的权限判断，所有决定都通过现有 `PendingWait` 应答通道发送。
- 只有宿主广播 `approval/resolved` 后，卡片才会退出堆栈。
- 系统通知只包含会话标题、申请理由或工具名，不展示完整命令参数。
- 用户偏好保存在浏览器 `localStorage` 的 `dsh-permission-popup.prefs` 键中。

在敏感环境使用第三方插件前，请先审查源码，并固定到可信 Commit。

## 开发

源码在 DeepSeek Harness monorepo 的 `packages/client/ui-permission-popup` 中开发。独立 GitHub 仓库会提交预构建的 `lib/`，因此从 GitHub 安装时不需要授权执行构建脚本。

在 DSH 仓库根目录执行：

```sh
pnpm exec tsc -b packages/client/ui-permission-popup
pnpm --filter dsh-plugin-permission-popup run bundle
pnpm exec vitest run packages/client/ui-permission-popup/tests/popup.client.spec.tsx
```

随后重启源码 Web 宿主：

```sh
pnpm dsh web
```

## 目录结构

```text
src/client/index.ts          浏览器插件注册入口
src/client/model.ts          审批投影和触发策略
src/client/ApprovalPopup.tsx React 卡片堆与系统通知
src/client/store.ts          持久化用户设置
cordis.patch.yml             DSH bundle 配置层
lib/                         预构建安装产物
tests/                       在 DSH monorepo 中运行的单元测试
```

## 许可证

[MIT](./LICENSE)