# @dsh-external/dsh-plugin-manager

[English](README.md) | **简体中文**

![version](https://img.shields.io/badge/version-1.0.1-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![dsh](https://img.shields.io/badge/DeepSeek%20Harness-Plugin-4f8cff)

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的全功能插件管理器：**可视化插件管理 · AI 自动翻译 · AI 一键概括 · AI 智能搜索 · 一键分享安装 · 一键更新**，附带应用内插件市场——一个包，开箱即用。

---

## ✨ 核心功能

| | 功能 | 说明 |
|---|---|---|
| 🖥️ | **可视化插件管理** | 已安装插件与预设卡片化展示：启停 / 删除 / 检查更新 / 分类，全部在一个面板里完成，无需命令行 |
| 🌐 | **AI 自动翻译** | 整个面板一键切换中文 / 英文 / 任意自定义语言——用你自己的模型翻译（可以选便宜模型！），译文本地缓存、持久保存 |
| 📝 | **AI 一键概括插件** | 让 AI 为每个已安装插件写一句话简介；**增量 + diff 判定**：版本无实质更新的插件绝不重复消耗 token |
| 🔍 | **AI 智能搜索插件** | 用大白话描述需求，AI 自动生成查询、扫 GitHub（`topic:dsh-plugin` + 宽泛检索）、按相关度与星数挑选最佳候选，一键安装 |
| 🔗 | **一键分享安装** | 把自己或他人的多个插件 / 预设打包成一条 `dshpm://` 链接，发出去；对方粘贴即装，一次装齐 |
| ⬆️ | **一键更新** | 一次点按检查并更新全部插件（npm 源与 GitHub 源）与 GitHub 预设，多版本并存时可选择目标版本 |


## 📸 界面预览

| 插件管理面板 | 插件市场 |
| --- | --- |
| ![插件管理面板](/docs/screenshots/screenshot-1.png) | ![插件市场](/docs/screenshots/screenshot-2.png) |

## 📦 安装

```sh
# 从 GitHub 安装（推荐）
dsh plugin --profile web add github:yunniees/DSH-Plugin-Manager

# 或本地目录装配（开发自用）
dsh plugin --profile web add /path/to/dsh-plugin-manager
```

仓库已包含构建产物（`lib/`），按官方发布规范采用「分发构建产物」路径——**无需 `allowBuilds` 授权、无需 `prepare` 脚本，开箱即用**；锁定版本可用 `github:yunniees/DSH-Plugin-Manager#<commit>`。

安装后**重启 Harness Web**（插件依赖 `webServer` 与 `llm` 服务，需在主 profile 作用域加载）。重启后侧栏底部出现「插件管理」入口（在「设置」旁，视觉与官方对齐）。

## 🚀 使用

1. 点击侧栏底部「插件管理」入口，打开管理面板。
2. 首次使用先在顶部「模型」下拉选择一个 AI 模型（AI 功能都复用 DSH 已配置的 provider，**插件不持有任何 API key**）。
3. **概览页**：AI 自动分类（只分类未分类插件）；AI 生成简介（增量）；每张卡「更多」菜单可检查更新 / 选版本 / 删除 / 分享。
4. **插件市场**：浏览 / 搜索 / **AI 搜索**（直接输入需求描述）；开启「AI 介绍」逐条生成简介（长按按钮可清缓存）；滚动到底自动加载下一页。
5. **预设区**：开关启停、检查更新、选版本更新、分享链接。
6. **分享**：任意卡片「更多」→「分享」生成 `dshpm://` 链接；对方在分享面板粘贴，一次装齐多个插件与预设。

## 🔒 安全

- **无硬编码密钥**——AI 调用全部复用 DSH 已配置的 provider，不持有、不读取任何 API key；
- **仅本机**——HTTP API 只绑定回环地址，不写日志、不外发请求体；
- **输入白名单**——仓库名 / 预设名 / 版本 tag / 文件名均经正则校验，防注入与路径穿越；
- **隐私**——状态文件只存分类 / 简介 / 语言等 UI 数据；`settings.yaml` 仅解析 provider 与模型名。

## 🛠️ 开发

```sh
npm install            # typescript + tsdown（仅构建需要）
npm run typecheck      # host + client 类型检查（必须 0 错误）
npm run build          # typecheck + 编译 host + 打包 client → lib/
```

- host 源码：`src/index.ts`（Cordis bundle 插件，Node）
- client 源码：`src/client/index.ts`（vanilla DOM + CSS 变量，无需框架）

> 改动 client 源码后必须重新 `npm run build`，否则装配的是旧产物。

## ❓ 常见问题

**Q：插件市场加载慢或失败？**
官方源优先（走你的代理节点），失败后自动切换国内镜像（镜像**直连**，不绕代理）。全部失败时网格底部出现「加载失败，点击重试」按钮。注意 GitHub 搜索接口（`api.github.com`）国内直连不稳定，会自动用 gh-proxy.com 兜底。

**Q：为什么必须先选模型？**
所有 AI 能力都复用 DSH 已配置的 provider，本插件不持有任何 API key。未选模型时点 AI 按钮会提示。

**Q：提示「GitHub API 限流」？**
GitHub 匿名搜索约 10 次 / 分钟。AI 搜索一次会并发发起多条查询，连续操作可能触发限流——会给出明确错误并可重试。

**Q：安装时提示 allowBuilds？**
DSH 对 git 源码插件要求构建授权（pnpm ≥10）。本插件的「安装」「AI 安装」会自动放行并提示；而它自身因仓库内已带构建产物，**永远不需要授权**。

**Q：一键更新能更新哪些？**
npm 源插件走 npm registry（显式版本号绕开 lockfile 惰性）；GitHub 源插件更新到最新 HEAD 或所选 tag；本地目录链接的插件会提示手动 `git pull`。

**Q：删除插件会怎样？**
确认后执行 `dsh plugin remove`（从 profile 卸载并移除文件）；删除预设仅移除其目录。

## 📚 文档

深入阅读 [`ARCHITECTURE.md`](ARCHITECTURE.md)：必守规则、统一调用层、翻译架构、防回归模式与发布检查清单。

## 📄 许可证

MIT（见 [LICENSE](LICENSE)）