dsh-clawbot

Readme

# dsh-clawbot

在 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）里接入**微信官方 ilink 机器人网关**：扫码绑定后，AI 能主动给自己发微信通知；每次回复后自动推送任务完成摘要；目标完成/阻断时自动通知；需要批准/选择时主动微信提醒。**自带设置界面**（设置 → ClawBot：扫码二维码、微信在线/断线状态、手动发送、三个自动通知开关、监听开关、解除绑定、自定义图标）。

底层走腾讯官方 `ilink` 网关（`https://ilinkai.weixin.qq.com`），无第三方破解、无自建中转，消息只发给绑定的账号自己。

## 安装（GitHub 一键）

把本目录推到 GitHub 仓库，然后：

```bash
dsh plugin --profile web add github:cryjkd/dsh-clawbot
```

安装后**重启 `dsh web`**，刷新页面，设置页会出现「ClawBot」分区。

> 说明：本插件是 **DSH 插件包**（`dsh.bundle` + `dsh.client`），不是 agent preset。它用 `dsh plugin add` 安装，所以能同时挂载 Host 半侧（工具/通知/监听）和浏览器半侧（设置界面）。

## 使用流程（约五分钟）

1. 打开 **设置 → ClawBot**。
2. 点「绑定微信 / 刷新二维码」，用**手机微信**扫面板上的二维码（或点开二维码对应的链接）并确认。
3. 绑定成功后，状态卡显示「已绑定」，但发送凭证未就绪（「微信连接断线」）——这是正常的。
4. **在微信里给新出现的 bot 联系人发任意一条消息**（解锁发送凭证 `context_token`）。
5. 面板状态变为「微信在线」，即可在面板「发送」（支持 markdown），或让 AI 调用 `notify_wechat`。

## 设置界面（设置 → ClawBot）

面板自上而下：

- **状态卡**：状态点（绿 = 微信在线并呼吸 / 红 = 断线 / 灰 = 未绑定）+ 状态文本（`微信在线` / `微信连接断线` / `未绑定`）；已绑定时右侧显示 `bot: <id>`。
- **未绑定**：显示扫码二维码与「绑定微信 / 刷新二维码」按钮（二维码由浏览器端本地渲染）。
- **已绑定**：显示 `user: <id>` 与发送凭证状态——
  - 会话已过期 → 提示重新扫码绑定；
  - 凭证有效 → 「发送凭证已就绪」；
  - 凭证过期 → 「发送凭证已过期：请在微信里给机器人再发一条消息」；
  - 尚未获得 → 「尚未获得发送凭证：请先在微信里给机器人发一条消息」。
  下方是发送框（默认「测试通知」，支持 markdown）与「发送」「解除绑定」按钮。
- **自动通知**（三个开关，默认均开启）：
  - `任务完成后自动微信通知` —— 每次回复后推送任务完成摘要；
  - `任务被阻断时自动微信通知` —— goal 阻断时推送；
  - `等待批准/回答时微信提醒` —— 需要批准的操作 / 需要选择的问题。
- **监听**：`监听微信消息并自动处理` 开关（默认关闭），说明：单独创建一个会话处理微信消息，不影响当前会话；处理完成后自动微信通知「完成」。
- 底部：操作结果提示（✔/✗）与最近错误（`lastError`）。

## 能力

| 能力 | 说明 |
|---|---|
| `notify_wechat` | AI 主动给自己发微信通知（长任务完成、需要拍板等），支持 markdown |
| `wechat_bind` | 绑定微信（返回二维码链接） |
| `wechat_status` | 查询绑定与连接状态、三个自动通知开关与监听开关 |
| （自动） | **每次回复后**自动推送 `✅ 任务完成` + 任务 / 结果 / 耗时 |
| （自动） | 目标（goal）完成 / 阻断时自动通知（`✅ 任务完成` / `⚠️ 任务阻断`） |
| （自动） | **需要用户批准 / 选择时**微信提醒（`🔐 需要你批准` / `❓ 需要你选择`） |
| （监听，默认关闭） | 收到微信消息后自动交给**单独的监听会话**处理，处理完成后微信通知 `✅ 微信消息处理完成` |
| 设置界面 | 二维码、`微信在线` / `微信连接断线` 状态、手动发送、三个自动通知开关、监听开关、解除绑定、自定义图标 |

## 自动通知内容

每次回复完成后自动推送：

```
✅ 任务完成

任务: <你的消息摘要>

结果: <AI 回复摘要>

耗时: X秒 / X分Y秒
```

目标（goal）完成时推送 `✅ 任务完成`（附目标摘要），goal 阻断时推送 `⚠️ 任务阻断`（附目标摘要与阻断原因）。自动通知有约 3 秒节流，避免连续触发时刷屏；未绑定或缺少发送凭证时静默跳过。

## 监听（默认关闭）

在设置界面打开「监听微信消息并自动处理」后：

1. 插件在后台持续轮询网关 `getupdates`（约 1.5 秒一次），只收集**绑定账号本人**发来的文本 / 语音转写 / 图片 / 文件 / 视频消息，跳过 bot 自己发出的消息。
2. 插件**单独创建一个监听会话**（会话 id 形如 `clawbot-listen-*`，复用当前默认模型 + 默认 agent preset），把每条新消息以「【微信】<内容>」的形式转发给它处理，**不影响当前会话**；关闭开关或插件卸载时销毁该会话。
3. 图片/文件/视频/语音会按 ilink 协议从 CDN 下载、AES-128-ECB 解密后保存到 `~/.dsh/clawbot/media/`，并把本地路径附给 AI（AI 可用 `read_image` / `read` 读取查看）；语音无转写时保存为 `.silk`（需自行转码）。
4. 若已开启但会话尚未建立，收到消息时会先自动创建会话；缺少 agents 服务或默认模型（`agentDefaultModel`）时开启失败并返回明确错误。
5. 处理完成后，自动向微信推送：

```
✅ 微信消息处理完成

消息: <收到的消息摘要>

结果: <AI 回复摘要>

耗时: X秒 / X分Y秒
```

开关状态保存在 `~/.dsh/clawbot/state.json`，跨重启保留；**默认关闭**，需手动在设置界面开启。

## 上报（webhook）

在「监听」里可配置把收到的微信消息**原样转发到自己的服务器**。需先开启总「监听」开关，再按需配置上报区块。

> 完整接入说明（如何接收、解析、处理上报数据，含示例代码）见 [`REPORT.md`](./REPORT.md)。

路由顺序（收到绑定账号消息时，逐条判断）：

1. 消息 **完全等于唤醒词** → 打开「启用上报」开关（持久化）；本条为控制指令，不转发、不交给 AI。
2. 消息 **完全等于关闭词** → 关闭「启用上报」开关；同上不处理。
3. 「启用上报」**开启** 且 已填地址 → `POST` 原始消息到服务器，**不交给 AI**；成功后微信通知 `✅ 上报成功`（失败通知 `⚠️ 上报失败`）。
4. 「启用上报」**关闭** 且 已填地址 且 填了前缀词 且 消息以该前缀开头 → 单次 `POST` 到服务器（**正文会去掉该前缀词**），不交给 AI，并通知上报结果。
5. 其它情况 → 交给独立监听会话由 AI 处理（见上文「监听」）。

上报请求：`POST {地址}`，`Content-Type: application/json`，body 为收到消息的**原始 JSON**（与微信官方 ilink `getupdates` 的 `msgs[i]` 结构一致，含 `context_token`），超时 10 秒。

```
{
  "from_user_id": "o9cq...@im.wechat",
  "to_user_id": "739...@im.bot",
  "message_id": "1234567890",
  "create_time_ms": 1720000000000,
  "message_type": 1,
  "item_list": [
    { "type": 1, "text_item": { "text": "消息文本" } }
  ]
}
```

## 需要批准 / 选择时提醒（默认开启）

开启「等待批准/回答时微信提醒」后，当 AI 执行到**需要你介入的阻断性操作**时会主动微信提醒，让你及时回到 DSH 页面操作：

- 需要你**批准**的操作（沙箱提权、越权写文件等）→

```
🔐 需要你批准

操作: <工具名>

原因: <原因摘要>

请在 DSH 页面确认或拒绝
```

- 需要你**选择**的问题（`ask_user_question`）→

```
❓ 需要你选择

问题: <问题摘要>

请在 DSH 页面回答
```

这些提醒走 `approval/request` 与 `tools/execute` 事件（`prepend` 观察者，不改变审批/问答结果本身），未绑定或断线时静默跳过。

## 状态持久化

绑定与开关状态保存在 `~/.dsh/clawbot/state.json`，跨会话、跨重启保留。发送凭证 `context_token` 有有效期：过期时状态会变成「微信连接断线」，只需**在微信里给机器人再发一条消息**即可自动恢复（后台轮询会自动用新凭证刷新状态）。

## 说明与限制

- 网关对主动发送**限流**（每天没几条），这是通知/拍板渠道，不是聊天工具。
- bot 收不到*转发*的文章和文件；请发原始链接或文件本身。
- 网关只允许绑定者账号收到消息；`context_token` 只在绑定者先发过一条消息后下发。
- 图标文件是插件目录里的 `icon.png`；想换图标直接替换该文件（保持 PNG 格式），替换后**重启 `dsh web`** 生效。

## 目录结构

```
dsh-clawbot/
├── index.js           # node 端 cordis 插件（agent 工具 + 自动通知/监听/上报 + /clawbot/* 路由）
├── client.js          # 浏览器端（__ModuleLoader__ + settings.section 设置界面）
├── cordis.patch.yml   # 组合补丁：插入 host 插件行
├── package.json       # dsh.bundle + dsh.client 声明
├── icon.png           # 面板图标
├── README.md
└── REPORT.md          # 上报接入点文档（接收/解析/处理示例）
```

## License

MIT