# dsh-messager 插件安装指南

> 面向**使用方**：把 `dsh-messager` 装进你自己的 DeepSeek Harness（DSH）Web 环境，
> 从而在会话需要交互、任务完成、任务出错时收到**系统通知 / 浏览器通知 / 飞书 / 企业微信 / Discord / 钉钉 / Telegram** 提醒。
>
> 本指南覆盖两类安装方式，按你的偏好二选一即可：
>
> - **源码方式** —— Clone 仓库 → 本地构建 → 安装（`src/` 由你自己掌控，可改可追，推荐给开发者）；
> - **pnpm 方式** —— 直接安装构建好的包（本地 checkout / 本地 tarball / git host，未来发布到 npm 后一行装上）。

---

## 0. 前置条件

| 依赖 | 要求 | 说明 |
| --- | --- | --- |
| Node.js | `>= 20` | 见插件 `package.json` 的 `engines` |
| pnpm | `>= 10`（推荐） | DSH 的 `dsh plugin` 命令会转发给 pnpm，请你本机已装 pnpm |
| DSH CLI | `dsh` 可用 | 发行版直接是 `dsh`；用源码运行 DSH 时是 `pnpm dsh`（见下文「源码运行 DSH 时的命令差异」） |
| 浏览器 | 最新版 Chrome / Edge / Firefox | 浏览器通知需站点授权 |

> **Windows 用户提示**：插件仓库路径若含空格或特殊字符，建议用绝对路径；命令中的路径写法见各节示例。

### profile 与 `$DSH_HOME` 说明

`dsh plugin` 会把插件装进某个 **profile**（一个独立的配置组合）。
本插件面向 Web，推荐装在 `web` profile —— 即启动命令 `dsh web` 对应的那个（`dsh web` 就是 `dsh --profile web` 的别名）。

- 默认 DSH 家目录 `$DSH_HOME`：`~/.dsh`（Windows 为 `%USERPROFILE%\.dsh`），可用环境变量 `DSH_HOME` 覆盖。
- Web profile 目录：`$DSH_HOME/profiles/web/`。
- 第一次 `dsh plugin --profile web ...` 会自动初始化该 profile（首次包含 `@deepseek-ai/dsh-base`），无需手写 manifest。

---

## 1. 源码方式（推荐给开发者）

源码方式适合你**希望自己保有源码、可以改代码**的场景。DSH 通过 `dsh.bundle` + `dsh.client`
双声明识别本插件，并提供 `plug` 构建产物。

### 第 1 步：克隆仓库

```sh
git clone https://github.com/<你的用户名>/dsh-messager.git
cd dsh-messager
```

> 仓库地址向仓库维护者索取；托管到公开/内部平台后按对应 URL 替换。

### 第 2 步：安装依赖并构建

```sh
# 在插件仓库内
pnpm install
pnpm build
```

`pnpm build` 会产出 `lib/`（host 端 TypeScript 编译 + client 端 Web bundle `lib/client.js`）。
产物已包含在 `lib/`，构建成功后即可安装。

> 若安装后要改 client 端代码，改完在自己的仓库里重新 `pnpm run build:client`，然后刷新页面即可
> （Web bundle 带 rev hash 会自动重新拉取）。详见下文「开发调试」小节。

### 第 3 步：安装到 Web profile

```sh
# <插件路径> 替换为你 clone 并构建好的本插件目录（绝对或相对路径均可，见第 2 节）
dsh plugin --profile web add <插件路径>
```

- 首次执行会自动初始化 `web` profile；
- pnpm 在 profile 目录里把该 checkout 链接为依赖，`dsh` 检测到它声明了 `dsh.bundle`，
  自动追加进 `web` profile 的 `bundles` 层列表；
- 装完后**必须重启** `dsh web`（clientModules 只在启动时扫描，运行中的实例不会热加入新 bundle）。

### 第 4 步：启动并验证

```sh
dsh web          # 或 dsh --profile web
```

打开 http://127.0.0.1:3080 ，设置 → 左侧菜单出现「通知&信使」分区即安装成功
（排在「Agent预设」下方）。
首次加载时会请求浏览器通知权限（若权限为 `default` 会自动请求一次）；拒绝只会静默降级浏览器通道，不影响另两条。

---

## 2. pnpm 方式

`dsh plugin` 本质是**在 profile 目录内转发给 pnpm**，所以它支持所有 pnpm 的安装 spec。
你想用哪种交付形态，就选哪种安装命令：

### 2.1 安装本地构建好的 checkout（推荐，最自包含）

其它用户已 clone 并构建好本仓库（`lib/` 存在）后，从含该 checkout 的目录执行：

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

- 相对路径以你**执行命令的工作目录**为锚定（`dsh` 会重写相对路径 spec），可放心从任意目录调用；
- 想用绝对路径也行：`dsh plugin --profile web add D:/somewhere/dsh-messager`。

### 2.2 安装 tarball / 本地产物

维护者用 `pnpm pack` 打包后交付，用户安装 tar 包：

```sh
dsh plugin --profile web add ./dsh-messager-0.1.0.tgz
```

> `pnpm pack` 默认只打包 `files` 字段列出的内容（本插件为 `lib/`、`assets/`、`cordis.patch.yml`、`README.md`），
> 无需任何构建授权即可安装。

### 2.3 直接从 git 安装（需构建授权）

```sh
dsh plugin --profile web add github:<你的用户名>/dsh-messager
```

> 将 `<你的用户名>/*/dsh-messager` 换成实际托管路径（GitHub 或其他 git 平台的 spec 都行）。
> 锁定到某个 commit 更稳妥：`dsh plugin --profile web add github:<你的用户名>/dsh-messager#<commit-sha>`。

> **重要**：git 安装拉取的是**源码而非构建产物**，DSH 不会自动跑 `build` 脚本。
> 本插件在 git checkout 后通过 pnpm 的 `prepare` 脚本（= `pnpm run build`）构建出 `lib/`。
> pnpm ≥ 10 出于安全默认**拒绝运行** git 依赖的 `prepare` 脚本，所以第一次 `add` 会失败，
> 并提示你把 pnpm 打印的确切包键加入该 profile 的 `pnpm-workspace.yaml`：

```yaml
allowBuilds:
  dsh-messager: true
```

然后**重新执行 `add`**。
> 请如实看待这项授权：它允许该包的构建代码在你的机器上执行。只对源码可信的包做此授权，
> 并尽量锁定 commit（见上文的 `#<commit-sha>` 写法）。

### 2.4 发布到 npm 后（未来）

把包发布到 npm（发布时已含构建好的 `lib/`），用户一行安装，无需任何构建授权：

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

---

## 3. 安装后配置

安装即默认生效（schema 自带默认值：交互/完成/出错三类触发全开，系统与浏览器通道开，飞书/企业微信/Discord/钉钉/Telegram 通道关）。
要改配置，任选一处，**同源不冲突、任一变更实时生效**：

1. **设置页分区「通知&信使」**：设置 → 左侧菜单「通知&信使」（排在 Agent预设下方）——
   完整字段表单，**发行版（npx 安装）开箱即用**：分区数据走插件自身的 webServer 路由
   （`/dsh-messager/config`），不受 DSH 设置白名单限制，无需任何补丁。
2. **设置文档**：编辑 `$DSH_HOME/settings.yaml` 的 `messager:` 段（含完整字段）。
3. **profile 补丁层**：`$DSH_HOME/profiles/web/cordis.patch.yml` 里按 `id: messager` 覆盖该行的 `config:`。

> 三处入口同源（同一 settings 命名空间），任一处保存后其余入口立即反映最新值。

常见配置示例（打开飞书与 Telegram 通道、加标题前缀）：

```yaml
# $DSH_HOME/profiles/web/cordis.patch.yml 中按 id 覆盖
- id: messager
  name: dsh-messager
  config:
    feishu:
      enabled: true
      webhookUrl: 'https://open.feishu.cn/open-apis/bot/v2/hook/<token>'
      secret: '<你的签名密钥>'
    telegram:
      enabled: true
      botToken: '<@BotFather 获取的 token>'
      chatId: '<数字 ID 或 @频道用户名>'
    message:
      titlePrefix: '[DSH]'
```

其他第三方通道（企业微信 / Discord / 钉钉）配置同理：在 `config:` 下启用对应分组并填
`webhookUrl`（钉钉/企业微信可选 `secret` 加签，Discord 无签名）。

完整字段表与「内容繁复度（minimal/normal/detailed）」说明见仓库根目录 `README.md` 的「配置」一节。

---

## 4. 源码运行 DSH 时的命令差异

若你自己是用**源码方式运行 DSH**（从 deepseek-harness 仓库根目录跑，而不是用发行版 `dsh`），
只需把上面所有 `dsh` 换成 `pnpm dsh`，命令与行为完全一致：

```sh
pnpm dsh plugin --profile web add <插件路径>
pnpm dsh web
```

- profile 目录仍为 `$DSH_HOME/profiles/web`；
- 在插件仓库里构建仍用普通 `pnpm install && pnpm build`（无需 `pnpm dsh` 前缀）。

---

## 5. 卸载 / 重装

```sh
# 卸载：同时移除依赖与对应的层
dsh plugin --profile web remove dsh-messager

# 若用源码/pnpm 重装，重新 add 并重启即可
dsh plugin --profile web add <插件路径>
dsh web
```

---

## 6. 常见问题（FAQ）

**Q1：设置页没有「通知&信使」分区？**
分区注册在 `settings.section` 槽位（纯客户端能力），与 DSH 设置白名单无关；
先确认插件 client 端已随 Web bundle 加载（装完需**重启** `dsh web`，`--patch` 只加载
host 端、不会出现分区）。若分区出现但提示「配置通道不可用」，说明 host 端配置路由
未挂载（webServer 服务缺失或 host 插件未加载）。

**Q2：浏览器不弹通知？**
检查站点权限是否被拒；`browser.onlyWhenHidden` 默认 `true` 只在页面隐藏/未聚焦时弹，看着界面时不打扰。
在浏览器站点设置中重新授权即可。

**Q3：装完没生效？**
先确认是否执行了 `dsh web`（装完要**重启启动**）；再确认 `lib/` 已构建（git 安装时要放行 `prepare` 构建脚本）。

**Q4：`--patch` 是干嘛的？**
`--patch` **不是安装步骤**，而是可选的**开发调试**手段（`dsh web --patch <插件目录>/cordis.yml`）：
它只加载 host 端、不写 profile、仅对本次启动生效。装了 bundle 之后请勿再同时带 `--patch` 启动同一插件
（host 端会加载两份，`messager` 命名空间重复注册报错）。

---

## 7. 本地开发调试（写给改代码的场景）

- **host 端（快速）**：从 DSH 源码仓库根目录运行
  `pnpm dsh web --patch <插件路径>/cordis.yml`，直接加载 TS 源码（HMR 生效）。
- **完整双运行端**：client 端要求插件以**包身份**进入 Loader 才会被 clientModules 扫描编入 Web bundle，
  因此完整开发请走安装流程（见第 1/2 节），改 client 端代码后在自己仓库 `pnpm run build:client` 并刷新页面。

> 更多开发细节见仓库根目录 `README.md` 的「本地开发」一节。