# dsh-notifier 使用指南（从零到日常）

> 给**你自己**的指南：电脑跑 DSH，手机 IM 收通知、远程审批、随时和 agent 聊。
> 推荐路径是浏览器里的 Web 管理台；YAML 只作为高级/自动化入口，不是另一套控制台。
>
> 三个地方：**电脑**（跑 DSH）、**手机**（IM 软件）、**浏览器**（配置用）。

## 快速四步上手（Dashboard 首屏同款）

打开管理台后，Dashboard 首屏会显示个人模式引导卡片，对应这四步：

| 步骤 | 做什么 | 在哪做 |
|---|---|---|
| ① 配置通知通道 | 挑一个手机上有的 App 填凭证，测试发送能收到就通了 | 管理台 → 「通道」页 |
| ② 配对你的 IM 身份 | 告诉插件「这个 IM 账号就是我」（扫码通道会登记身份，其他用配对码） | 管理台 → 「成员」页 |
| ③ 测试通知 | 在通道卡片点击「测试发送」，失败时按页面给出的原因修复并重试 | 管理台 → 「通道」页 |
| ④ 开始使用 | agent 发消息 → 通知推到手机 → 审批按提示回复编号或点按钮 | 日常聊天即可 |

> **第一步「完成」= 通道已配置且已启用**（填了凭证但没启用 / 通道还没连的不算完成，通知发不出去）。
> 配完通道 + 配对完成，引导卡片会自动隐藏；想手动隐藏点「我已熟悉」即可
> （存在浏览器 localStorage，不影响服务端；浏览器隐私/受限模式下不记也不影响功能）。

下面是完整的分步详解：

---

## 第一步：装插件

```bash
dsh plugin add dsh-notifier --profile <你的profile名>
```

## 第二步：打开 Web 管理台（唯一控制台）

在 `cordis.patch.yml` 里给插件加 3 行，把网页控制台打开：

```yaml
insert:
  - id: dsh-notifier
    config:
      admin:
        enabled: true
        token: "自己起一个长随机串"   # 登录控制台用；不写则启动日志里自动生成一个
```

重启 DSH 后，直接打开启动日志中 **「Web 管理台已就绪」** 这一行给出的完整 URL（包含实际端口，端口为 0 或被占用时也不会猜错），用 token 进入。管理台只监听本机 `127.0.0.1`。
之后所有日常配置都在这个网页里做，这份 YAML 不用再动；需要脚本化或高级字段时才回到 YAML。

## 第三步：在网页里配通道

进入 **「通道」** 页：27 个出站渠道 + 6 个入站渠道全是卡片，点开填表单即可，
每个字段旁边都写着去哪拿值，填完有 **「测试发送」** 按钮当场验证连通性。首次打开默认是「个人模式」，绑定矩阵和会话等高级设置需点击「打开高级设置」后才显示。

### 先让它能推给你（出站，2 分钟）

挑你手机上有的：Bark（iPhone）/ Telegram / 钉钉 / 飞书 / 企微 / 桌面通知……
找到对应卡片，按表单提示填凭证，点「测试发送」——手机收到，就通了。

### 再让它听你说话（入站，挑一个）

| 你常用 | 怎么配 | 在哪配 |
|---|---|---|
| 飞书 / QQ / 钉钉 | 卡片上点 **「扫码授权」**，**网页里直接出二维码**，手机扫一下，网页每 2 秒自动轮询到「完成」 | 全网页 |
| 微信个人号 | 卡片上点 **「扫码授权」**，网页出二维码，**用你自己的微信**扫并确认——机器人会出现在你的微信好友里，**扫码那一刻就配对好了** | 全网页 |
| Telegram | Telegram 里找 @BotFather 发 `/newbot` 拿 token，贴进卡片表单 | 全网页 |
| WxPusher | 仅当你有公网可回调（六通道唯一）才考虑 | 全网页 |

**微信个人号**（想要微信双向对话的可以选这个）：

1. 「通道」页找到 **wechat（入站）** 卡片，点 **「扫码授权」**；
2. 网页出现二维码，**用你自己的微信**扫码并在手机上点确认；
3. 网页轮询到「完成」即配好。

这个机器人是**你的专属好友**：只和你一对一聊天，别人加不了也聊不了。
扫码后身份通常会自动登记，你可以在「成员」页看是否已经是 owner——如果出现在「待确认绑定」里，点一下「确认转正」即可。

QQ、微信 iLink、钉钉的图片消息归一代码已接线并通过契约测试；真实平台消息形状和设备行为仍待验证，文件收发不要当作已支持能力。

### 保存后

网页保存的凭证重启一次 DSH 生效（连接在启动时拉起）。重启完在「通道」页能看到各通道变绿。

> **出站配置「视图热、投递冷」**（G-14，W12）：管理台保存**出站**渠道配置后，UI 会**立即回显**，通道卡片角标同时标记 **「重启后生效」**——投递层（出站路由/通道实例）只在插件**下次启动**时并入运行时（YAML ⊕ store 合并），重启前不影响已运行的出站链路；入站凭证同理下次启动启用/重连。也就是说：保存 ≠ 立即生效，看到「重启后生效」角标就去重启一次 DSH。

## 第四步：配对（把你的 IM 账号连上，也在网页里）

配对 = 告诉插件「这个 IM 账号就是我」。做一次，后续不用再配。

> **用微信的可以跳过这一步**——微信扫码授权后身份会自动登记，通常就配对好了（专属好友，天然只有你）。如果没出现，也可以在「成员」页手动确认。

1. 控制台进 **「成员」** 页 → **铸造配对码**（默认 10 分钟有效，码面只在弹窗显示一次，当场复制）；
2. 手机私聊你的机器人，发送：

   ```
   /pair 刚才复制的码
   ```

3. 收到 **「配对成功！你是首位成员（owner），已可使用全部功能。」** —— 完成。

三条细则：码只在**私聊**发（群里发会被拒但码不作废）；输错 5 次锁 10 分钟；
换号时旧号发 `/unpair`、新号去「成员」页再铸一枚新码。

> 全新安装时也会自动铸一枚「引导码」，码面写在 `<stateDir>/bootstrap-paircode.txt`（仅本机你自己可读，
> 终端只提示路径不打码面）；`cat` 一下即可，效果等同——但用网页铸码就不用碰文件了。
> WxPusher 订阅你的应用后，「成员」页会出现待确认身份，点「转正」等同配对。

## 第五步：日常使用

### 收通知（全自动）

任务结束/出错、agent 等审批、长任务心跳（默认 15 分钟）与卡住提醒（10 分钟无动静）。
某条会话吵：`/quiet <会话>` 闭嘴，`/unquiet <会话>` 恢复。

### 远程审批

- Telegram / 飞书：卡片上直接点 **批准 / 拒绝** 按钮；
- QQ 单聊：优先使用原生按钮；QQ 群聊控制目标 fail-closed 并回退为文本；
- 微信 iLink / WxPusher / 钉钉：按提示**回复 `1`（同意）或 `2`（拒绝）**；
- 不回 = 不同意，永远不会因沉默误批准。

### 远程会话（手机当键盘）

直接发文字就是给 agent 的输入；任务中途发 `! 改成方案B` 可以纠偏；
连续几条碎片会自动合并成一句。

### 远程提问（agent 反过来问你）

agent 遇到需要你拍板的选择（走哪个方案、删不删文件），会在手机上直接出**选择题**：

- 飞书 / Telegram / QQ 单聊：**选项卡片点一下即答**（一选项一按钮）；
- QQ 群聊 / 微信 / 钉钉 / WxPusher：按提示**回复编号**（如 `2`；多选用逗号隔开，如 `1,3`）。

答错了会收到提示并重发选项，问题不作废，再答就行；
一直不答就超时交回电脑端处理——**永远不会替你猜答案**（与审批同一原则：沉默不作数）。目前 DSH 宿主没有安全的 desktop `ask_user` 接口；电脑端只能接收 fail-closed 的回退结果，不能把桌面当作可用的提问结算入口。需要手动裁决时，可在本机 Web 管理台的脱敏问题列表中 choose/reject，结算仍经 Control Core。

### 命令速查（私聊机器人发）

| 命令 | 干什么 |
|---|---|
| `/help` | 列出全部可用命令 |
| `/whoami` | 看我是谁、绑定状态 |
| `/status` | 任务/会话跑得怎么样 |
| `/agent` | 列 agent 与会话名（`/quiet` 要用） |
| `/stop` | 停掉当前任务 |
| `/quiet`·`/unquiet <会话>` | 静默/恢复会话推送 |
| `/route …` | 多 agent 路由 |
| `/unpair` | 解绑（换号用） |

控制台另外还有：总览（实时事件流）、通知（手动发测试）、绑定/会话（路由矩阵）、通道（凭证/测试/扫码）。

---

## 高级入口：YAML / CLI

全部配置也可以纯 YAML + 命令行完成：出站渠道写在 `cordis.patch.yml` 的 `channels` 下，
入站用 `node scripts/channel-login.mjs <qq|dingtalk|feishu|wechat>` 扫码。字段清单见
[README](../README.zh-CN.md#配置项)——这是高级/自动化入口；没特殊理由的话，网页点选快得多。

## 出问题了

| 现象 | 处理 |
|---|---|
| 控制台进不去 | 确认 YAML `admin.enabled: true` 已重启；忘了 token 就删 `state.json` 里 `admin:token-hash` 再重启 |
| 网页配完没生效 | 重启一次 DSH（连接启动时拉起）；「通道」页看是否变绿 |
| Telegram 409 冲突 | 之前设过 webhook，去 @BotFather 删掉 |
| 飞书/钉钉里搜不到机器人 | 应用可用范围/机器人可见范围没开给自己，平台后台加 |
| QQ 群里发消息没反应 | QQ 群消息只有 @机器人才送达；配对必须在单聊 |
| 微信机器人不应答 | iLink 会话过期，「通道」页 wechat 卡片重新点「扫码授权」（CLI 党重跑 `node scripts/wechat-login.mjs`） |
| 配对码已过期/被用 | 「成员」页再铸一枚（微信不需要配对码） |
| 手机远程控制/会话命令被拒（日志报 `missing_accountId`） | v0.8.x 起 accountId 来源规则：**绝不拿 channel 兜底**——来源必须真实存在，accountId 缺失一律 fail-closed 拒绝。单账号不配也行（通道会注入默认）；**同渠道跑多机器人/多应用（多账号）时必须在每个入站通道显式配置 accountId**（如 wxpusher 的 `accountId` 字段：本地账号标识，不要填 APP_TOKEN），否则消息无法归属到具体账号、远程控制/审批回执会被拒 |
| `你不在白名单中` | 该 IM 账号没配对——回第四步（微信用户检查是不是换了微信扫的码，重扫即自动换绑） |
| 其他 | 控制台「总览」页看实时事件流 |