# dsh-plugin-safe-install

![License](https://img.shields.io/github/license/rouyiemei/dsh-plugin-safe-install)
![Stars](https://img.shields.io/github/stars/rouyiemei/dsh-plugin-safe-install)
![Repo size](https://img.shields.io/github/repo-size/rouyiemei/dsh-plugin-safe-install)
![Platform](https://img.shields.io/badge/platform-DeepSeek%20Harness-4f7cff)

> **一个 DeepSeek Harness (DSH) 插件**：把「小白安全安装 DSH 插件」的完整流程打包成内置技能（skill），安装即用，零依赖、零网络、零生命周期脚本。
>
> [English](README.en.md) | 中文

---

## 这个故事是怎么来的（作者自述）

我是一个**完全不懂编程的小白**，第一次折腾 DeepSeek Harness（DSH）插件时，经历堪称灾难：

1. **装插件费劲**：看到插件市场里琳琅满目的插件，照着教程 `dsh plugin add xxx`，装完一个又一个；
2. **装完总是无法正常启动**：每次装完新插件，DSH 就再也起不来了——报错信息全是英文和技术术语，我看不懂；
3. **更绝望的是：无法启动 = 没法解决错误**：想求助、想排查，但 DSH 都启动不了，我连「问 AI」的入口都没有；作为小白什么也不会，只能干瞪眼；
4. **反复尝试，反复失败**：卸载重装、重启电脑、删掉配置重来……每次都在同一个坑里打转，最后把整个 DSH 都搞坏了，只能靠备份目录 `web_bak` 一点点抢救。

在多次尝试之后我终于想明白：**我需要的不只是「怎么装」，而是一套「怎么安全地装、装完怎么验证、坏了怎么回滚」的流程**——而且这套流程必须简单到小白也能跟着走。

于是我把这段血泪经历整理成了本插件的核心技能：**`dsh-plugin-safe-install`（DSH 插件安全安装与测试流程）**。

---

## 这个插件能做什么

安装本插件后，DSH 的 Agent 会自动获得一个内置技能 `dsh-plugin-safe-install`。当你说「帮我安装 XX 插件」时，Agent 会按这套流程执行：

| 阶段 | 做什么 | 对小白的意义 |
|---|---|---|
| 0️⃣ 范围与权限 | 先确认要装什么、需要哪些权限 | 不擅自乱动你的配置 |
| 1️⃣ 基线 | 装之前先检查当前状态、打回滚点（checkpoint） | **装坏了随时能退回原状** |
| 2️⃣ 安全审计 | 检查插件有没有恶意脚本、来源是否可信 | 不给可疑插件开门 |
| 3️⃣ 逐个安装 + 五级验证 | 装一个 → 验证一个 → 再装下一个 | **坏在第一步就能发现**，不会攒一堆一起炸 |
| 4️⃣ 原生依赖处理 | 处理 node-pty / sharp 等构建问题 | 那些装完起不来的坑，流程里都有解法 |
| 5️⃣ 干净卸载/回滚 | 装坏了怎么彻底清干净 | 不会留下残渣继续搞坏 DSH |
| 6️⃣ 收尾检查 | 全部验证 + 提醒重启生效 | 装完心里有底 |

**流程中最重要的一条教训（也是我踩得最深的坑）**：启动验证必须用 `dsh-doctor boot`（它会自己退出），**不要**用 `dsh web --port 0` 做测试——那是常驻服务器，永远不会自己退出，把「超时」误当成「失败」会让人反复重试、无限卡死。这个坑我卡了整整几十轮才爬出来，已经写进技能的规则里，不会再踩。

---

## 安装方法

### 方式一：从 GitHub 安装（推荐）

```bash
dsh plugin --profile web add github:rouyiemei/dsh-plugin-safe-install
```

> 插件通过 `dsh.bundle.patch` 声明自动挂载，无需手动编辑任何配置文件。

### 方式二：本地开发/试用

```bash
# 克隆或下载本仓库后，在项目目录执行：
dsh plugin --profile web add link:./dsh-plugin-safe-install
# 或直接把 skills/ 目录复制到技能目录（不装插件也能用技能）：
#   cp -r skills/dsh-plugin-safe-install ~/.agents/skills/
```

安装完成后**重启 `dsh web`**，技能即出现在 Agent 的技能列表中。

### 卸载

```bash
dsh plugin --profile web remove dsh-plugin-safe-install
```

## 项目结构

```
dsh-plugin-safe-install/
├── package.json          # DSH bundle 插件声明（dsh.bundle.patch）
├── cordis.patch.yml      # 插件挂载层（insert 插件行）
├── index.js              # 插件入口：把 skills/ 目录注册为技能提供者（零依赖）
├── skills/
│   └── dsh-plugin-safe-install/
│       └── SKILL.md      # 技能本体：六阶段安全安装流程 + 验证清单（中英双语）
├── LICENSE               # MIT
├── README.md             # 中文说明
└── README.en.md          # English readme
```

## 安全说明

- 本插件**零运行时依赖**、**无任何生命周期脚本**（安装时不执行任意代码）、**无网络访问**（只在本地读取自己的 `skills/` 目录）。
- 技能内容 100% 可读：安装后可在 `skills/dsh-plugin-safe-install/SKILL.md` 查看全文。

## License

MIT