@qipenglin/dsh-plugin-manager

Readme

# @qipenglin/dsh-plugin-manager

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

面向 DeepSeek Harness `0.1.1-rc.2` 的可选 Profile 插件管理器。安装后可在“设置 → 插件 → 插件管理”中安装、单包更新、卸载和取消当前 Profile 的插件操作。

## 安装

```sh
dsh plugin --profile web add github:qipenglin/dsh-plugin-manager
dsh web
```

该命令直接从 GitHub 仓库的默认分支安装插件。仓库已包含经过验证的 `lib` 产物，安装过程无需执行构建脚本。安装完成后请重启当前 Profile，使 Host 与浏览器端扩展同时加载。

管理器只操作加载它的当前 Profile。`dsh web` 对应 `web`；`dsh --profile work` 对应 `work`；桌面宿主提供 `desktopProfiles.current` 时，以桌面宿主声明的名称和绝对目录为准。无法可靠识别当前 Profile 时，插件拒绝启动，不会回退到 `web`。

## 功能

- 安装 npm registry、npm alias、Git、GitHub、远程 tarball、绝对本地目录以及绝对 `file:`/`link:` 来源。
- 通过文件选择器上传并保留 `.tgz`、`.tar.gz` 和 `.tar` 安装包。
- 安装区和更新弹窗均提供默认关闭的“跳过新版本等待期”选项。用户明确勾选后，仅为本次操作追加 `--config.minimumReleaseAge=0`，其他供应链检查保持不变。pnpm 因新版本等待期拒绝操作时，界面会提示 `勾选“跳过新版本等待期”可解决`，但不会自动放行或重试。
- 更新或卸载一个直接依赖。点击“更新”会打开统一弹窗，可重新选择 npm、Git/GitHub、远程 tarball、绝对本地目录或本地压缩包来源；更新始终写回原直接依赖键。远程 tarball 必须填写新 URL，本地压缩包必须重新选择文件，相同内容会在执行前拒绝。
- 管理器区域提供专用的自身“更新”按钮，复用同一弹窗和“跳过新版本等待期”选项。自身更新后会校验直接依赖仍然存在、已安装包名仍为 `@qipenglin/dsh-plugin-manager` 且没有新增管理器别名；成功后标记“已更新，重启后生效”，并在重启前禁用该操作。GUI 仍禁止卸载、重复安装或通过 npm alias 安装第二份管理器。若未知 Git/压缩包最终替换了管理器，操作会报告失败，但磁盘状态可能已经改变；此时应先用外部 DSH CLI 检查或恢复，再重启。
- 卸载现有直接依赖时会自动为该次 `remove` 关闭发布时间等待期，避免锁文件中已经安装的较新版本阻塞删除操作；完整性、来源和其他供应链检查保持启用。卸载不提供或接受新的包来源。
- 每次成功修改直接依赖后，当前 Host 都会显示明确状态：“已安装，重启后生效”“已更新，重启后生效”或“已卸载，重启后生效”，并在重启前禁用该条目的更新和卸载按钮。已卸载条目会保留到重启；新安装和更新的条目显示新的磁盘元数据，但不表示其运行时代码已经生效。
- 同时只执行一个修改操作；可取消运行中的操作。
- 操作成功后写入重启标记并提示手动重启；下次 Host 加载会消费标记并清除提示，不热加载也不自动重启。
- 诊断日志有界保存，并删除 Authorization、Cookie、token、密码和 URL 用户信息。

## WebAccess 是可选增强

本包不依赖 `@qipenglin/dsh-web-access`。若 Host 提供结构化 `webAccess.authorize(request)` 服务，上传接口会在读取正文前严格认证；服务稍后加载或卸载时，下一次请求会立即采用新的状态。

没有 WebAccess 时，管理功能仍完整可用，但只允许 WebServer 绑定 `127.0.0.1`。任何能访问本机回环端口的本地进程都可能调用管理接口，页面会明确显示该状态。如果 WebServer 绑定 `0.0.0.0` 且没有 WebAccess，插件会拒绝启动。

## 桌面宿主

桌面宿主可选提供：

```ts
desktopProfiles.current = { name: string, dir: string }
desktopPnpm.runPlugin(args, invokingDirectory, signal)
```

两项构成原子的桌面集成：必须同时有效或同时缺失，只出现一项时插件会拒绝启动。两项均可用时，操作固定到 `desktopProfiles.current` 并通过 `desktopPnpm` 执行；两项均缺失时，使用当前 Node 与 DSH CLI 入口，以 argv 数组调用 `plugin --profile <当前名称>`，不拼接 shell 命令。

CLI Provider 会从子进程环境中删除 API Key、Base URL、token、密码、secret、Authorization/Cookie、`NODE_OPTIONS` 和 `NODE_PATH`，同时保留普通的 `PATH`、`HOME`、代理和包管理器配置。因此当前明确不支持通过 Host 环境变量传递私有 registry token；请在 Host secret 之外配置 registry 访问。`desktopPnpm` 实现拥有其子进程环境，必须执行同等过滤，因为本包只向它传递结构化参数、目录和取消信号。

## 本地开发

需要 Node `^22.19.0 || >=24.0.0` 与 pnpm `11.7.0`：

```sh
pnpm install --frozen-lockfile
pnpm run typecheck
pnpm run lint
pnpm test
pnpm run pack:check
pnpm run test:installed
```

`pnpm run pack:check` 会清空并重建 `dist/`，其中只保留已校验的 `dist/qipenglin-dsh-plugin-manager-0.3.7.tgz`。

`test:installed` 会把真实安装归档放入隔离的官方 DSH `0.1.1-rc.2` Web Profile，并通过真实 Loader 调用 Remote API。

## 许可证

[MIT](LICENSE)