# 使用手册

**用 QQ 遥控你的电脑。** 手机上发消息，电脑上的 DSH 干活。

---

# 一、它能帮你做什么

## A. 出门在外，电脑替你干活

### 场景 1：不在电脑前，也能让电脑干活

出门前电脑上跑着 DSH。地铁上想起来一份文件要改，发条 QQ：

```
把 报告.md 里第三节的日期改成今天，然后发给我
```

**电脑上改好，文件作为附件发回你的 QQ。** 你不用打开电脑。

### 场景 2：让它查完东西直接告诉你

```
帮我查一下这个项目依赖里有没有安全漏洞，有的话列出来
```

DSH 在电脑上执行，结果发到 QQ。手机上读结论即可，不用看终端。

### 场景 3：跑长任务，跑完通知你

```
跑一遍测试，跑完了把结果告诉我
```

你可以去做别的事。DSH 跑完把结果发到 QQ。

### 场景 4：把电脑上的东西发到手机

```
把桌面上的 截图.png 发给我
把 D:\项目\报告.docx 发我
```

**不用先复制到哪儿**，直接说路径就行。图片出现在 QQ 里能看能存，视频能直接播放，其他文件是附件。

---

## B. 锁定电脑后离开，手机全程控制 ⭐

**这是最实用的一个用法。**

你准备出门，但不想让电脑一直亮着屏幕（也不安全）。**按 Win+L 锁屏，然后走人。**

```
（锁屏前，电话或提前在 QQ 里说）
帮我把这个项目重构一下，需要我决定的地方问我

（你锁屏出门，路上手机里回它的问题、看它的结果）
```

**锁定屏幕不影响 agent**：DSH 和 agent 都在后台继续跑，网络也照常。**你手机上完全控制它。**

### ⚠️ 但有一条必须分清

| 你做的 | agent 还能干活吗 |
|---|---|
| **锁定屏幕**（Win+L） | ✅ **照常工作** |
| **睡眠** | ❌ **停止**——CPU 被挂起，agent 也跟着停 |
| **休眠 / 关机** | ❌ **停止** |
| **合上笔记本盖子** | ⚠️ **看你设置**——默认常是"睡眠"，那就停了 |

**所以**：出门前**锁定屏幕**，**别让它睡眠**。

**检查一下**：设置 → 系统 → 电源，把「接通电源时」的睡眠设为**从不**（笔记本插电时）。合盖动作也检查一下是不是设成了"不采取任何操作"。

> **为什么要锁屏**：agent 在你电脑上有相当高的权限。锁屏不影响它工作，但能防止**路过的人**看到或操作你的桌面。

---

## C. 在电脑上干活，结果发到手机 ⭐

**你在电脑前跟一个对话干活，中途要出门，让它把结果发你 QQ。**

```
你（在电脑上的某个对话里）：这个构建跑完通知我，我先出去一趟

（你走了）

DSH → 你的 QQ：构建完成了，3 个警告，没有错误。
```

**注意**：这个对话**不是** QQ 绑定的那个，但**它照样能推到你手机**（默认开启）。

**这正是这个插件的价值**：不是"只能在 QQ 对话里用"，而是**电脑上任何对话都能给你发消息**。

> **⚠️ 但有个前提**：电脑上别的对话**遇到要问你的地方，问题只弹在屏幕上**——你不在就卡住。
>
> **所以要么**先把这个对话设成「完全访问」（它就不问了），**要么**把这种活放到 QQ 里交代。详见第五节。

---

## D. 手机上处理需要你决定的事

### 场景 5：权限询问，手机上回一句就行

DSH 干活时如果需要许可，**问题直接发到你 QQ**：

```
DSH：🔐 需要你确认：Bash
npm test

回复 允许 或 拒绝

你：允许

DSH：好的，继续。
```

**多个选项的提问也一样**，回个编号——它发出来的样子（第一条就是问题本身，后面是选项）：

```
要发布到哪个环境？
1. 测试环境
2. 正式环境

回复编号，或直接回复你的答案
```

你回 `2` 就行。

> 默认情况下 QQ 来的对话是「完全访问」，它**不会**问你。想让它问，在设置里改。

### 场景 6：让它先问你，再动手

```
你：把 uploads 目录里三个月前的文件都删掉——先跟我说要删哪些

DSH：我要删这 12 个文件：
     ...

你：可以

DSH：删完了。
```

---

## E. 一个 QQ，管好几摊事

### 场景 7：同时推进多个任务

QQ 里只有一个聊天窗口，但**背后可以是好几个互不干扰的对话**：

```
你：/list

DSH：【QQ 会话】会话（1/1）

     1. 改登录 bug · 2 分钟前 ← 当前  e716f0
     2. 写周报 · 1 小时前  9d4e7b
     3. 整理资料 · 昨天  1c2d5a

     回复编号或行尾 6 位 id 切换。
     引用这条消息再回编号，可以避免编号过期。

你：2

DSH：已切换到「写周报」。
     9d4e7b
```

**每个对话有自己的上下文**，互不污染。出门路上可以挨个推进。

**列表就在眼前时直接回编号就行**（回 `2`，不必打 `/switch 2`），也可以回名字或行尾那个短 id。**每屏最多 10 条，编号跨屏连续**，回「查看其余」看下十个。

**编号会过期**——你读列表的时候别的对话还在跑。所以每行末尾都有个**最多 6 个字符的短 id**，直接用它就不会过期；或者**引用那条列表消息**再回「2」，编号就按那条消息印的算。

---

## F. 定时和提醒

### 场景 8：让它定时叫你

```
每小时给我发一次当前时间
每天早上 9 点提醒我今天要做什么
10 分钟后叫我
```

**管理**：

```
看看我设了哪些定时任务
删掉那个每小时的提醒
```

> **提醒**：定时任务会**真的跑一轮 AI**，有 token 消耗，而且每次内容可能不同。想省钱就说清"只回一句话"。

详见**第五节「让它主动通知你」**。

---

## G. 各种输入方式

### 场景 9：拍张照片让它看

手机拍一张报错截图发过去，然后：

```
这个错误怎么解决
```

**图片和文字可以一起发**——先发图，紧接着发文字，会**合并成同一条任务**处理（默认等 10 秒）。

**也可以**：拍白板、拍纸质文件、拍实物，让它读。

### 场景 10：用语音交代

```
（按住说话）帮我把这个季度的数据整理成一个表格
```

**说比打字快**，特别是走路或开车停靠时。

**QQ 会把语音转成文字一起给它**，所以它读的是转写，不是音频。

### 场景 11：引用某条消息继续问

QQ 里**长按它发过的某条消息 → 引用**，然后问：

```
这条里的第二个方案为什么不行？
```

**QQ 直接把被引用的那段文字给它**，所以它知道你在说哪一条，不用你重复粘贴。

### 场景 12：让它主动读电脑上的东西

```
看一下 logs 目录里今天最大的那个日志，前 50 行有什么问题
把那个 Excel 的第二个 sheet 读出来，列成 markdown 发我
```

---

## 和别的方案比，它有什么不一样

| | |
|---|---|
| **不用第三方协议客户端** | 直接对接腾讯官方的 QQ 机器人服务 |
| **不需要公网 IP** | 你的电脑主动往外连，所以路由器、公司网络、4G 热点都不影响 |
| **不需要服务器** | 就在你自己的电脑上跑 |
| **不需要事先注册机器人** | 扫码那一刻当场创建，不用去开放平台准备 AppID / AppSecret |
| **扫码一次，长期有效** | 电脑重启也不用重新扫 |
| **锁屏也能用** | 锁屏不影响 agent，出门前锁一下更安全 |
| **任何对话都能找你** | 不只是 QQ 那个对话，电脑上任何对话都能推到你手机 |
| **只有你自己能用** | 未认证的机器人仅管理员可用——这是平台的规则，不是本插件的白名单 |

---

# 二、安装

## ⚠️ 先记住这个名字

**要装的名字是：**

```
dsh-qq-group-plugin
```

**注意最后有个 `-plugin`，别漏。**

> **最保险的做法**：**复制上面那行**，不要凭记忆手打。

---

## 前提

- 电脑上装了 **DSH 桌面端**——本插件**针对 `0.2.0-rc.2` 开发和实测**
- 这台电脑**保持开机**，而且**不要让它睡眠**（**锁屏没关系**，见第一节 B）
- 手机上有 **QQ**
- **不需要事先注册机器人**：机器人应用是扫码那一刻当场创建的，不用提前准备 AppID / AppSecret
- 机器人**不用认证**：未认证的机器人**仅管理员可用**——也就是只有你自己能用，这正是私人遥控器要的

## 步骤

**1.** 打开 DSH，点侧栏的 **「插件」**，再点 **「添加插件」**

**2.** 在输入框里**粘贴**（不是手打）：

```
dsh-qq-group-plugin
```

**3.** 点安装。装完点 **「立即启用」**

**4.** **重启 DSH**（关掉再打开）

> **为什么必须重启**：插件在 DSH 启动时加载，装了不重启不会生效。

---

# 三、第一次使用：扫码绑定

**1.** 打开 **设置 → QQ**（DSH 设置里的「QQ」那一项）

**2.** 点 **「开始扫码」**，屏幕上会出现一个二维码

**3.** 用**手机 QQ** 扫这个二维码

**4.** 手机上会提示确认，点确认

**5.** 页面上显示 **「已连接 QQ」** 就好了

> 二维码过期它会自己换一张，不用你重新点。

## 试试看

在 QQ 里找到那个机器人，发一条：

```
你好
```

**几秒内应该收到回复。** 收到就说明全部配好了。

> **发的第一条消息会成为这个对话的名字。** 比如你发「修一下登录」，这个对话就叫「修一下登录」。

> **凭据存在哪里**：AppSecret 写进 **DSH 的凭据存储**，插件自己的状态文件里**只有 AppID**。所以别去 `state.json` 里找密钥，那里没有。

---

# 四、能发什么

## 先看你发出去之后会发生什么

**你一发消息，QQ 顶部就会出现「对方正在输入」。**

```
你：帮我把那份报告整理一下

（QQ 顶部显示：对方正在输入…）   ← 它收到了，正在干活

DSH：整理好了，三个问题列在下面…
```

**这个提示很重要**，它告诉你三件事：

| 你看到 | 说明 |
|---|---|
| **「对方正在输入」出现了** | ✅ **消息收到了**，agent 已经开始处理 |
| **它一直显示** | 活还在干——**任务越长，显示越久**（最长 30 分钟） |
| **它消失了，回复到了** | 处理完了 |
| **出现了又消失，但没有回复** | 可能是命令类操作（比如 `/list`），或者出错了——看设置页的「最近错误」 |

> **为什么值得留意**：任务跑起来之后，你可能不知道它到底收没收到。**这个提示就是"我收到了，正在干"的确认。**
>
> **它是插件每 5 秒给 QQ 发一次的**（单次有效期 8 秒）。**到 30 分钟就不再刷新了**——那时候"还在输入"和"已经卡死"看起来一样，所以我们不装作它还在想。
>
> ⚠️ 如果你的 QQ 版本没显示这个提示，不影响任何功能，只是少了一个进度信号。

---

## 文字

直接发。DSH 会当成任务来做。

```
看看今天的日志里有没有报错
```

## 图片

**直接发照片**，DSH 会收到这张图。

手机上拍一张报错截图，发过去，然后：

```
这个错误怎么解决
```

**图片和文字可以一起发**——先发图，紧接着发文字，它们会**合并成同一条任务**处理（默认等 10 秒）。

> **为什么这样设计**：你常常先发个图、再补一句说明。如果第一条图立刻处理，你补的那句就变成了第二次不相关的问题。

## 文件

**发任意文件**（文档、压缩包、代码），DSH 收到并保存在电脑上。

```
帮我看看这个 Excel 有什么问题
```

## 语音

**发语音也可以。** QQ 服务端会把语音转成文字一起给它，所以**就算电脑上没装任何音频组件也能用**——它读的是转写。

> 语音文件本身也会存到电脑上（腾讯转好的 WAV），需要的话它知道那个文件在哪。

## 视频

发视频，DSH 收到并保存。

> **附件存在哪**：会话工作区下的 **`媒体`** 目录，默认是 `C:\Users\<你的用户名>\.dsh\dsh_qq_groups\媒体`。

---

## ✅ 群聊：支持（@ 它就行）

**在群里 @ 它，它就会回。** 本 fork 相对上游加的就是这一条。

| | |
|---|---|
| 怎么触发 | 群里 **@ 它** 再说话。不 @ 的消息不会处理 |
| 会话 | **每个群友独立**。同一个群里你和别人各聊各的，互不串台 |
| 私聊与群聊 | 同一台电脑、同一个 agent，但**是不同的会话**，上下文不共享 |

**两条平台限制，不是插件的毛病：**

- **被动回复窗口：群里 5 分钟、最多 5 次**（私聊是 60 分钟）。超时再回会报
  `msgid已经过期,不能回复`。
- **主动推送要群主开权限**：需要在**手机 QQ 里**把机器人移除再加入，添加时点「设置权限」，
  开「主动推送消息能力」。没开时 `notify_qq` 会报 `40034105 无权限`。
  **两条路会同时断掉，表现是群里彻底静默。**

> ### ⚠️ 群聊比私聊危险得多
>
> 私聊只有你能跟它说话。**群聊是群里每个人 @ 一下都能驱动这台电脑上的 agent**——
> 当前实现不区分发言人，也不检查群 id。默认权限还是 `danger-full-access`（不弹审批）。
>
> 把机器人拉进群之前想清楚：这个群里的人都可信吗？
> 收紧办法见仓库 README 的「安全」一节（群 id 白名单、发言人白名单）。

---

# 五、让它把东西发回来

**直接要求就行**：

```
把结果发给我
把那张图发过来
生成一个表格文件发我
```

| 它发什么 | 你在 QQ 里看到什么 |
|---|---|
| 图片 | 一张照片，能点开看 |
| 视频 | 能直接播放的视频 |
| 其他文件 | 文件附件，能点开或保存 |

**回复太长时会自动变成文件**：超过 4000 字，会发一个 `.md` 文件给你，**不会截断**。

> QQ 一条消息本身能装大约 5000 字，超过就会被切成好几条刷屏。所以这个 4000 字的门槛是故意的：**宁可给你一个文件，也不要在手机上连划三屏读一段断掉的回复。**

## 文件在别的地方，也能直接发

**不用复制、不用挪位置。** 直接说文件在哪就行：

```
把桌面上的 报告.docx 发给我
把 D:\项目\手册.md 发我
```

DSH 会直接发过来。**桌面、项目文件夹、任何位置都行。**

> **一个安全提醒**：也正因为这样，**agent 能读到什么文件，就能发出什么文件**。能给它发消息的只有你（见第十节），所以真正要守住的是**你的 QQ 本身**——手机别丢、别让旁人拿去用。

---

## 让它主动通知你（重要）

**不用等你问，它可以主动发消息到你 QQ。这条路径实测可用**：实测连发十条消息全部成功，其中后六条就是主动推送。

腾讯的规则时有调整，插件不假设额度——万一没送出去，它会排队、等你下次说话时补发（见本节末尾）。

### 例子：你在这边干活，然后出门

```
你：这个构建跑完通知我，我先出去一趟

DSH：好，跑完我发你 QQ。
```

构建结束时，消息就到你手机上了。

### 例子：定时提醒

**可以定时。** 直接说：

```
每小时给我发一次现在几点
```

或者更有用的：

```
每天早上 9 点提醒我今天要做什么
```

支持这些频率（说大白话即可，DSH 会自己选）：

| 你说 | 它做 |
|---|---|
| "10 分钟后叫我" | 一次 |
| "每小时" / "每 30 分钟" | 重复 |
| "每天早上 9 点" | 每天 |
| "每周一早上" | 每周 |

### 要精确的间隔，就用"定时任务"

**想准，就用"每 N 秒/分钟/小时"这种说法**——那会建一个真正的定时任务，由 DSH 自己按时间叫醒，不受别的工作影响。

**管理定时任务**：

```
看看我设了哪些定时任务
删掉那个每小时的提醒
```

### ⚠️ 两个要知道的点

**① 定时任务会真的跑一轮 AI**，不是固定发一句话。所以**有 token 消耗**，而且**每次内容可能不同**。

想省钱就说清楚：

```
每小时发一次当前时间，只回一句话，别的都别做
```

**② 定时任务建在哪个对话，就在哪个对话里执行。**

所以**在 QQ 里建的就发到 QQ；在电脑上的对话里建的就发到电脑**。要发到手机，就在 QQ 里说这句话，或者在电脑上的对话里说（见下）。

### 电脑上的对话也能发到你 QQ

**默认开启。** 所以你在电脑上让我干活，我可以直接推到你手机：

```
你：改完这个文件告诉我

（你继续做别的事）

DSH → 你的 QQ：改完了，改的是第 3 节的日期。
```

**想关掉**：设置 → QQ → 把 **「允许其他会话推送到 QQ」** 关掉。关掉后只有 QQ 对话自己那个会话能发。

> **代价**：开着的话，**这台电脑上任何会话都能给你发消息**。这是有意的设计（否则"做完了通知我"就没法实现），但你该知道。

### 离开电脑前，务必看这一节

**有一件事会毁掉上面所有便利：权限询问。**

| 你在哪个对话干活 | 权限询问出现在哪 | 你不在电脑旁会怎样 |
|---|---|---|
| **QQ 绑定的那个对话** | ✅ **发到你 QQ**，手机上回「允许」就行 | 正常 |
| **电脑上的别的对话** | ❌ **只弹在电脑屏幕上** | ⛔ **卡死**——它等你点，而你不在 |

**为什么不一样**：权限询问只由**绑定到 QQ 的那个对话**认领并转发。别的会话的询问留在桌面，谁都看不到。

> 日志里就是这样：`非本频道会话 -> 委托`（不是我管的会话 → 交给桌面）。

---

## 所以，离开电脑前按这两条做

### ① 要在电脑上的对话里干活，并让它做完通知你 → **先把那个对话设成「完全访问」**

**因为推送能到手机，但"要不要允许"这个问题到不了。**

设成完全访问后，它就不再问，能一路做完并主动通知你。

```
（在电脑上那个对话里）
把当前对话的权限设为完全访问，然后改完这个文件发我 QQ
```

> **注意**：设置页里那个「QQ 对话的权限预设」**只对之后新建或采纳的会话生效**。电脑上已有的对话要在 DSH 自己的权限设置里改，或者直接这样跟它说。

### ② 如果你预计它会**中途问你**（选方案、要不要删、走哪条路）→ **先在 QQ 里说这件事，再离开**

**别在电脑上的对话里交代这种活。** 因为你一走，它问到一半就没人答。

**正确做法**：在 **QQ** 里给机器人下这个任务。这样：

- 它问的时候，**问题发到你 QQ**，你手机上直接答
- 做完的结果也**自动发到你 QQ**

```
（在 QQ 里）
帮我把 report 目录整理一下，需要我决定的地方就问我
```

**它问 → 你答 → 它继续 → 结果发你**，全程在手机上闭环。

---

## 一句话记法

| 你的活是… | 在哪说 |
|---|---|
| **做完就行**，不需要你中途决定 | 电脑上哪个对话都行（**但要设成完全访问**） |
| **可能要你拿主意** | **QQ 里说**（或者先把那个对话绑到 QQ） |

**分不清就一律在 QQ 里说**——多打几个字，胜过回来发现它卡了一小时。

---

## ⚠️ 主动推送的规则会变 —— 发不出去的消息会排队等你

**这是 QQ 和微信最大的一个不同，值得知道。**

机器人**能主动给你发消息**（这就是"做完了通知我"能成立的原因），而且**实测可用**：插件在被动回复用满之后会转主动推送，实测连发十条消息**全部成功**，其中**后六条走的正是主动推送这条路**。

但腾讯对主动推送的规则**有过调整**，官方文档自己也互相矛盾：同一页的横幅写着"主动推送能力于 2025 年 4 月 21 日起不再提供"，正文却写着"单聊主动消息每月 4 条"——**这两种说法都与上面那次实测不符**。

所以**插件不假设额度**：不管没送达是网络、平台拒绝，还是平台规则变了，它都会进队列，等你下次说话时先补发。

### 好消息：没送出去的消息会**排队等你**

**任何原因导致这条消息没能送达——网络、平台拒绝、规则变化——它都不会被丢掉**，而是排队保存起来：

```
（你不在，这条主动推送没送出去）
DSH：构建完成了  → 没送达 → 自动排队

（你回来，在 QQ 里发一句"在吗"）
你：在吗

DSH：构建完成了          ← 排队的消息先补发给你

DSH：在的，有什么需要？   ← 然后才回你刚才那句
```

**所以这是"延迟"，不是"丢失"。** 你下次拿起手机发一句话，积压的通知就到了。

**队列的用途只有一件事：把没发出去的消息补发给你。** 它**不是"额度兜底"**——不管没送达是网络、平台拒绝，还是平台规则变了，只要这条没送出去，它就会排队。

**排队规则**：

| 项 | 规则 |
|---|---|
| **补发时机** | 你下次在这个 QQ 对话里发消息时，**先补发，再回你** |
| **最多存** | 50 条（超了丢最旧的） |
| **存多久** | 6 小时（超了自动丢弃） |
| **只补发给谁** | 只补发给**当时仍然绑定着**的那个对话；中途换了绑定就不补发（发错人比发不出去更糟） |
| **文件丢了怎么办** | ⚠️ **会被丢掉，而且你手机上不会收到说明**——只在日志里留一行「待发：文件已不存在，丢弃 …」 |
| **其他失败** | 还会再试；实在发不出去就一直留着，等下次 |

> ⚠️ **文件是"记住路径"而不是"存一份"**。所以排队期间如果你**删了那个文件或改了它的位置**，补发时这一条就没了——而且**手机上不会收到任何说明**，只有日志里那一行。所以**别把文件放进排队里等**：能现在发就现在发。

---

### ⚠️ 你一条消息，它最多"被动回复" 4 次

**这是插件用的限流值，不是平台的硬规则**：插件用的是腾讯 SDK 自带的限流默认值——你发一条消息，机器人在这条消息上**最多被动回复 4 次、1 小时内**。

> 官方平台规则是**60 分钟内最多 5 次**；SDK 的默认更保守，**插件没有改它**。

超过之后，回复会**改走主动推送**——也就是上面那条路（同样不承诺额度）。

**什么时候会碰到**：让 agent「每隔 3 秒发一条」「倒计时提醒我」这类**连发**的活儿。

**碰到也不丢**：第 5 条起走主动推送；主动那条也没送出去，就进排队，你下次说话时补发。

---

### 那还需要注意什么

**① 排队不是万能的**：消息要等你**发一条 QQ**才会到。所以"出门两小时，两小时后自动收到通知"**仍然做不到**——除非你在这期间碰过 QQ。

**② 想更主动，用定时任务**：

```
每小时给我发一次当前时间
```

**但如果那条主动推送没能送达，定时任务那次的推送也会进队列**——所以还是等你回来。

**③ 最稳的做法**：需要长时间离开时，**把要做的事在 QQ 里交代**。你在 QQ 里的每条消息都是一次新的机会。

---

# 六、多个对话怎么管

**一个 QQ 对话，可以对应电脑上多个不同的 DSH 对话。**

比如：一个对话在做项目 A，另一个在做项目 B。QQ 里只有一条聊天，用指令切换。

## 指令

在 QQ 里**直接发**这些：

| 指令 | 作用 |
|---|---|
| `/new 修复登录` | 新建一个对话，名字叫「修复登录」 |
| `/list` | 列出**QQ 会话**（当前工作区，带编号，每屏最多 10 条） |
| `/list all` | 列出**会话夹**（本机的每个工作区），回复编号或名字进入 |
| `/switch 3` | 切到编号 3 那个 |
| `/switch e716f0` | 按行尾的短 id 切——**永远不会过期** |
| `/model` | 看有哪些模型和它们的**推理等级**（当前在用的会标出来） |
| `/model 2` | 换到编号 2 的模型，写模型名字也行（用那个模型自己的默认等级） |
| `/model 等级 high` | 只换当前模型的推理等级，等级名字就是列表里印的那些 |
| `/model 2 等级 high` | 换模型的同时指定等级 |
| `/current` | 我现在在哪个对话 |
| `/cancel` | 停下正在跑的任务 |
| `/help` | 显示这份列表 |

**空格可以省**：`/switch3`、`/switch 3`、`/switch:3` 都一样。

**列表就在眼前时，连 `/switch` 都可以省**：回编号、名字或行尾 id 就行（`2`、`写周报`、`9d4e7b` 都可以）。

**每屏最多 10 条，编号跨屏连续**（第一屏 1–10，第二屏 11–20），回复「**查看其余**」看下十个，可以一直翻到底。翻到底了它会说明。

**一个例子**：

```
你：/list

DSH：【QQ 会话】会话（1/1）

     1. 修复登录 · 2 分钟前 ← 当前  e716f0
     2. 写周报 · 1 小时前  9d4e7b

     回复编号或行尾 6 位 id 切换。
     引用这条消息再回编号，可以避免编号过期。

你：2

DSH：已切换到「写周报」。
     9d4e7b
```

**那个 6 位 id 是干什么的**：每一行末尾都印着一个（上面例子里是 `e716f0`、`9d4e7b`），**它就是另一种写法**——回 `e716f0`、回 `2`、`/switch e716f0` 都能切到同一个对话。列表末尾会明说是「行尾 6 位 id」，就是怕它看起来像装饰。

**想要别的工作区的对话**：发 `/list all`。它列的是**会话夹**——每个工作区一行，带会话数：

```
会话夹（1/1）

1. QQ 会话  4 个会话
2. workplace  12 个会话
3. dsh_orb  5 个会话

回复编号或名字进入；回复「查看其余」看下十个。
```

回 `2` 或 `workplace` 就**进那个会话夹**，看到它自己的会话列表（编号同样从 1 开始，每屏 10 条，回「查看其余」继续翻）。**进去只改浏览位置，不改绑定**——真要切过去，还得在里面再选一个会话。

> 同名的工作区（两个目录都叫 `workplace`）回名字时**不会猜**，会列出编号让你回编号。

**为什么每行末尾有那个短 id**：编号是**那一屏**里的位置，而列表拍的是一个还在动的机器——你回「2」的时候第 2 行可能已经换人了。短 id 是**会话自己的**，跟列表无关，所以永远指同一个对话。

**引用那条列表消息**再回「2」，编号就固定在那条消息上：它印的第 2 个，就切第 2 个。

> **关于推理等级**：等级名字来自电脑上的模型适配器。本机自带的 DeepSeek 适配器发布的是 `off` / `low` / `high` / `max`（清单里印成 `Off` / `Low` / `High` / `Max`），**大小写不敏感**。中文的「高」「低」不在取值里——**等级名字就是列表里印的那些**。

## 说大白话也行

**记不住指令没关系**，直接说：

```
换个对话
看下有哪些对话
换个模型
把推理等级调到高
停一下
新建一个对话
```

DSH 会先告诉你它要做什么，你回复确认，它再执行。

> 想省掉这道确认：设置页里把 **「会话操作先确认」** 关掉。

---

# 七、手机上看不到权限弹窗？（重要）

## 以前的问题

DSH 执行命令前有时要问你"允许吗"。**那个询问原本只出现在电脑屏幕上**——你在手机上，就永远卡住。

## 现在

**权限询问会发到你的 QQ**，回一句就行：

```
DSH：🔐 需要你确认：Bash
npm test

回复 允许 或 拒绝

你：允许
```

**有多个选项的提问也一样**，回编号；**允许多选时还可以一次回几个**，比如 `1,3`。

**它能认出的回答**（大写小写都行）：

| 你想说的 | 可以回 |
|---|---|
| 同意 | `允许` `同意` `可以` `好` `行` `yes` `ok` |
| 不同意 | `拒绝` `不允许` `不可以` `不同意` `不用` `不行` `不要` `否` `no` `cancel` |

**认不出的回复不会被当成拒绝**（安全方向是对的）：它会**把提示再发一遍**，同时你那句话照常交给 agent 处理。所以你可以边答边聊，不会因为回错一个字就把权限给出去。

## 但默认情况下它不会问你

**QQ 来的对话默认是「完全访问」**——DSH 执行命令前不询问，直接做。

**为什么这样定**：权限询问会发到 QQ，然后任务就**停在那里等你回答**。你在手机上，本来就是为了不守着电脑——**一条卡在对话里等你回复的命令，等于没发过**。

**想让它问**：设置页里改 **「QQ 对话的权限预设」**（见下一节）。

> ⚠️ **这个设置只影响之后新建或采纳的对话。** DSH 在对话开始后**锁定权限**，改不了已有的。想用新设置，`/new` 建一个新的。

---

# 八、设置页怎么用

打开 **设置 → QQ**。一共六组：**帮助**、**连接**、**权限**、**行为设置**、**指令**、**诊断**。

## 帮助

最上面那个「打开使用手册」按钮——就是这份手册的网页版，手机上也能看。

## 连接

| 项目 | 作用 |
|---|---|
| **通道状态** | 总开关。「启用通道」关掉后不再接收 QQ 消息，但**凭据保留**——再打开不用重新扫码 |
| **已绑定账号** | 显示绑定了哪个机器人（AppID，以及扫码那个 QQ 的 openid），每行有个「断开连接」 |
| **扫码绑定** | 扫码（第一次绑定、换机器人、或凭据失效时用） |
| **最近错误** | 出问题时看这里（在「诊断」那一组里） |

**通道状态**会显示三种：

| 显示 | 意思 |
|---|---|
| 已连接 | 正常工作中 |
| 已停止 | 通道被关了 |
| 凭据已失效，需要重新扫码 | 需要重新扫一次 |

> **「断开连接」和「启用通道」不是一回事**：关掉通道只是不再监听，凭据还在；**断开连接会把凭据删掉**，要重新扫码才能连上。DSH 里的对话都保留。

## 权限

### QQ 对话的权限预设 ← 最重要的一项

**默认：完全访问。**

| 选项（页面上的原文） | 效果 |
|---|---|
| **完全访问：不询问，直接执行** | DSH 干活前不问 |
| **自动审核：电脑上判断** | 让电脑上的自动审核决定，不确定时才问你 |
| **跟随 DSH 设置：和桌面端一样** | 用你给桌面端设的那套把关 |

> ⚠️ **只影响之后新建或采纳的对话。**

> **如果这个部署没装权限预设服务**，下拉框会是灰的，并显示一句说明——那不是坏了，是这台机器上确实没有可选项。

## 行为设置

**改完点「保存设置」。这里所有设置都立即生效，不用重启。**

> 包括「会话文件夹路径」也是**当场生效**（换个文件夹，之后新建的对话就用新的），不用重启。

页面底部有三个按钮/提示要知道：

- **「保存设置」**——填完了必须点它，改字不算保存
- **「恢复默认」**——把所有项一次性恢复成出厂值（不改磁盘上的东西，直到你再点保存）
- **「有改动还没保存。」**——看到这句就是**还没存**；保存成功后它会变成「已保存」

**保存出问题时**，页面会在按钮旁明说，不会假装成功：

| 页面显示 | 意思 |
|---|---|
| **保存失败：…** | 请求没送到主机，后面是原因 |
| **这些值没有被主机接受，已改回实际生效的值：X** | 主机拒了某一项（比如数字越界），并把页面改回真实值 |

### 1. 会话操作先确认

**默认开启。** 说「换个对话」这类要求时，DSH 会先说要做什么，等你同意。

**关掉**：你说了就直接做，不追问。

### 2. 允许其他会话推送到 QQ

**默认开启。** 这是「干完了告诉我」能成立的原因：干活的那个对话通常不是你 QQ 绑定的那个。

**关掉**：只有 QQ 对话自己那个会话能发。

### 3. 附件合并窗口（毫秒）

**默认 10000（= 10 秒）。** 收到图片/文件后等这么久，看你有没有补充文字。

- 等了 10 秒你没说话 → 单独处理附件
- 你在 10 秒内发了文字 → 合并成一条处理

**填 0 表示不等待**（来了就立刻处理）。

### 4. 等不到文字就自动处理附件

**默认开启。** 关掉后，附件会**一直等你发文字**，不会自动处理——注意这**不是"忽略附件"**，批次还记着，你之后任何一句话都会把它带上。

### 5. 单条回复字数上限

**默认 4000。** 超过就改发 `.md` 文件，**不截断**。**填 0 表示不限制。**

### 6. 回复聚合静默窗口（毫秒）

**默认 1200。** DSH 的输出如果间隔小于这个值，合并成一条 QQ 消息。

调大 → 更长更完整，但更慢；调小 → 更快，但可能拆成好几条。

### 7. 渠道上下文说明

**每条消息前自动附上的一段说明**，告诉 DSH「你在和手机上的用户说话」。默认内容建议不要清空——没有它，DSH 会以为你坐在电脑前，让你"打开某个路径"。

### 8. 会话文件夹路径

**agent 读写文件的地方。** 可以点「**选择…**」从系统对话框里选，也可以直接把路径**粘进输入框**。

- **留空再保存** = 回到默认位置（`C:\Users\<你的用户名>\.dsh\dsh_qq_groups`）
- **必须是绝对路径**，例如 `D:\QQ会话`
- 输入框旁边那一行「**当前生效：**」显示的是**真正在用**的目录——它和输入框里的值可以不一样（填了个用不了的路径时，它会回落到默认位置，而输入框里保留你填的原文让你改）

> ⚠️ **改路径不搬动已有的对话。** 它们留在原来的文件夹，只有之后新建的用新路径。这是唯一安全的做法——宿主认的是对话所在的那个目录，搬走它就再也接不回来了。

> ⚠️ **填错的路径不会让插件起不来**，只会"没生效"（回落到默认位置）。所以放心试。

## 指令

设置页里还列出了**斜杠指令和它们的作用**，忘了可以直接去那儿看：

`/help`、`/new [标题]`、`/list`、`/switch <编号>`、`/current`、`/cancel`

它也会提醒你：分隔符可以用「：」或直接省略（`/switch1`），以及**说大白话也可以**。

## 诊断

| 这一行 | 是什么 |
|---|---|
| **日志文件** | 日志在哪（默认 `C:\Users\<你的用户名>\.dsh\qq\boot.log`） |
| **会话工作目录** | **实际生效**的目录 |
| **对话数** | 有几个 QQ 对话绑在这台电脑上（通常只有 1 个） |
| **待回答交互** | 有几个权限询问/提问还在等你回答 |
| **被动回复限流** | 插件用的限流值：SDK 默认 `4 次 / 1 小时`（平台规则是 60 分钟内 5 次） |
| **日志末尾** | 最后 60 行，出问题时先看这里 |
| **最近错误** | 通道遇到的失败（最多显示 6 条） |

## 这些项目对应的设置名

设置存在状态文件里，用的是下面这些名字。找问题、或者在 issue 里描述现象时用得上：

| 设置名 | 默认值 | 页面上的标签 |
|---|---|---|
| `permissionPreset` | `danger-full-access` | QQ 对话的权限预设 |
| `requireConfirmation` | 开 | 会话操作先确认 |
| `allowCrossSessionNotify` | 开 | 允许其他会话推送到 QQ |
| `settleMs` | `1200` | 回复聚合静默窗口（毫秒） |
| `presenceNote` | 一段中文说明 | 渠道上下文说明 |
| `mergeWindowMs` | `10000` | 附件合并窗口（毫秒） |
| `autoReplyAttachments` | 开 | 等不到文字就自动处理附件 |
| `maxReplyChars` | `4000` | 单条回复字数上限 |
| `workspacePath` | 空（= 默认位置） | 会话文件夹路径 |

> 状态文件在 `C:\Users\<你的用户名>\.dsh\qq\state.json`，日志在同目录的 `boot.log`。

---

# 九、常见问题

## 收不到回复

| 先看 | 怎么办 |
|---|---|
| 设置页「通道状态」 | 显示"已停止" → 把「启用通道」打开 |
| 同上 | 显示"凭据已失效" → 重新扫码 |
| 都正常 | 发任意消息试试；还不行就重启 DSH |

## 装了插件但设置页没有「QQ」

- **重启过 DSH 了吗？** 装了不重启不生效
- 侧栏「插件」里能看到它吗？看不到说明没装成功
- 能看到但没启用 → 点「立即启用」

## 装完重启，DSH 起不来了

打开这个文件看原因（里面有完整错误，重点是 **renderer console** 那一段）：

```
%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log
```

## 手机上一直收不到权限询问

**这是正常的**——默认「完全访问」，它不问。想让它问，去设置页改「QQ 对话的权限预设」。

## 通知没到我手机

**先看设置页诊断里的「日志末尾」**，找这几行：

| 日志里看到 | 意思 | 怎么办 |
|---|---|---|
| `待发已入队` | 这条主动推送没送达，已经排队 | 在 QQ 里随便发一句话，积压的会先补发 |
| `主动推送也失败` | 主动那条也没送出去 | 看后面跟的原因；网络问题居多 |
| `待发：文件已不存在，丢弃 …` | 排队里的那个文件不在了 | 没了（下次别把文件留在队列里等） |
| `待发：当前绑定是 …，与 … 不同，跳过补发` | 本机绑了不止一个 QQ 对话，积压只补发给**最近使用**的那一个 | 在同一个对话里**再发一条**消息（这一条之后它就成了最近使用的），积压就会补发 |

## 想换一个 QQ 机器人 / 重新绑定

设置 → QQ → 先点那一行的 **「断开连接」**（它会删掉本机凭据），再 **「开始扫码」**。

> **扫码会当场创建一个新的机器人应用**，旧的那个还在腾讯那边，只是本机不再用它。

## 在群里 @ 它，没反应

按顺序查这三样：

1. **是不是忘了 @**——群消息必须 @ 它才会被处理。
2. **是不是超过 5 分钟了**——群聊的被动回复窗口是 5 分钟、最多 5 次，超时的那条回不出去
   （日志里 `msgid已经过期,不能回复`）。
3. **有没有开主动推送权限**——没开时主动消息会报 `无权限`，见上一节。

## 桌面上把对话归档或删掉了，会怎样

**你在 QQ 里的下一条消息会告诉你**：它会新建一个对话接上，并说明原来那个「已经被归档」还是「在电脑上已经不存在了」。

```
DSH：原对话「修一下登录」已经被归档，我已新建「修一下登录」并接到这里。
     你刚发的这条会发到新对话里，之前那个的上下文不在新对话里。
```

**注意上下文不会跟过去**——旧对话的历史留在旧对话里。

## 电脑关机或休眠了，还能用吗

**不能。** 链路是"你的电脑主动连出去"，电脑关机或 DSH 没运行，QQ 这边就没有响应。

## 会不会很耗流量

**几乎不耗。** 只是收发文本和文件本身；图片、视频走的是腾讯自己的通道。

## 发大文件发不出去

QQ 对上传有大小限制，超了会直接拒。**设置页「日志末尾」里会有一行 ERROR 说明原因**——里面通常带着服务端给的原话。

---

# 十、安全性

## 只有你自己能碰到它

**这一点是平台规则保证的，不是靠设置。**

机器人是一个**独立的 QQ 应用**，**管理员就是你的 QQ 账号**——而且是你自己扫码创建的那一个。腾讯的规则是：**未认证的机器人仅管理员可用**。也就是说，**只有你能给它发消息**。

而且**它不是一个能发出去的 QQ 名片**：

| 它不是 | 所以 |
|---|---|
| 不是好友 | 别人**加不到**它 |
| 没有名片 | 别人**转发不了**它 |
| 搜不到 | 别人**找不到**它 |

**所以不存在"陌生人给机器人发条消息就能操作你电脑"这回事**——**那种路径压根不存在**。

**也因此不需要白名单**：**平台自己的规则就是一道白名单**，只有你一个能进来。

## 密钥是怎么存的

**AppSecret 是长期密钥，就按长期密钥对待。**

它以 **`grant` 记录写进 DSH 的凭据存储**，**不是**写进插件的明文状态文件（那里只有 AppID）。要轮换就回设置页重新绑定一次——重新扫码会当场创建一个新的机器人应用，本机从此用新的那个（旧的那个还在腾讯那边，只是不再被使用）。

## 而且还很干净

| | |
|---|---|
| **只连官方服务** | 腾讯官方的 QQ 机器人服务（`api.bot.qq.com`），扫码页在 `q.qq.com`，别的什么都不连 |
| **没有第三方** | 不存在"某个协议客户端在中间转一手" |
| **没有自建中转** | 消息不经过任何人的服务器，包括我们自己的 |
| **扫码一次长期有效** | 凭据存在你自己的电脑上，电脑重启也不用重扫 |

## 但有三件事你该知道

### ① agent 以你的身份运行

它能执行命令、读写文件，**用的就是你用户的权限**。

**这是它的用途**——它要能帮你干活，就必须能做你能做的事。但也意味着：

- **交代任务前扫一眼**，确认你要的就是你写的
- 别让它跑你没看懂的东西（**和你在 DSH 桌面端用它是同一套信任**）

### ② 默认任意会话都能推送到你的 QQ

**这是有意的。** 干活的那个对话通常不是你 QQ 对话绑定的那个，不放开这一条，它就报不了自己的结果。

**想收紧**：设置 → QQ → 关掉 **「允许其他会话推送到 QQ」**。关掉后只有绑定的那个会话能发。

### ③ 离开时锁屏

**锁屏不影响 agent 干活**（第一节 B 讲过），但能挡住**路过的人**动你的桌面。

```
按 Win+L → 走人 → 手机上看进度、收结果
```

**这是最省事的一条安全习惯**：不花任何代价，解决的是唯一真实存在的风险——**别人碰你的电脑**，而不是别人给机器人发消息。

## 想让它先问你

如果你希望它动手前确认，把设置页的**QQ 对话的权限预设**改成 **「自动审核：电脑上判断」** 或 **「跟随 DSH 设置：和桌面端一样」**，它就会像桌面端一样先问。

> ⚠️ 代价是**任务会停在手机上等你回**。所以只在你真的会在手机旁边的时候这么设。

---

# 十一、一页速查

```
安装        插件 → 添加插件 → 填 dsh-qq-group-plugin → 立即启用 → 重启 DSH
绑定        设置 → QQ → 开始扫码 → 手机 QQ 扫码确认（机器人当场创建，不用事先注册）

发消息      直接发（文字、图、文件、语音、视频都行）——私聊直接发，群里要 @ 它
            群里每个群友一个独立会话；群聊被动回复窗口 5 分钟 / 5 次
            发出去后 QQ 顶部显示「对方正在输入」= 它收到了、正在干活（最长 30 分钟）
要东西      「把结果发给我」「把那张图发过来」
合并附件    先发图，10 秒内补文字，会一起处理

/new 名字   新建对话
/list       列出 QQ 会话（每屏最多 10 条）
/list all   列出会话夹（工作区），回编号或名字进入
/switch 3   切到第 3 个
/switch e716f0 按行尾那个 6 位短 id 切（不会过期）
            引用列表消息再回编号也一样，编号冻结在那条消息那一屏
查看其余     往下翻十条（列表就在眼前时，直接回编号/名字/行尾 id 就能切）
/model      看有哪些模型和推理等级、换模型
/model 等级 high  只换推理等级（等级名字就是列表里印的那些）
/current    我在哪
/cancel     停下
/help       帮助

说大白话    「换个对话」「看下有哪些对话」「换个模型」「把推理等级调到高」「停一下」也行

权限提示    🔐 需要你确认：… → 回「允许」或「拒绝」（多个选项就回编号）
设置        设置 → QQ
  权限      默认「完全访问：不询问，直接执行」；想让它问就改「自动审核：电脑上判断」
  确认      默认开（说大白话换对话前先问你一次）
  推送      默认开（关掉后只有 QQ 对话自己能发）
  文件夹    留空 = C:\Users\<你的用户名>\.dsh\dsh_qq_groups；改完点「保存设置」，立即生效
  保存      改完必须点「保存设置」；看到「有改动还没保存。」就是还没存

主动推送    实测可用（连发十条全部送达）；规则可能变，插件不假设额度
            没送达就排队（最多 50 条 / 6 小时），你下次说话时先补发
            你一条消息它最多被动回 4 次（SDK 默认值；平台规则是 60 分钟内 5 次），之后走主动推送
            排队里的文件要是没了，会被丢掉，手机上不会另外告诉你

出问题      设置 → QQ → 「最近错误」和「日志末尾」
            日志文件：C:\Users\<你的用户名>\.dsh\qq\boot.log
            起不来：%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log

安全        只有你自己能给它发消息（未认证机器人仅管理员可用）
            AppSecret 存在 DSH 凭据存储里，不在明文状态文件里
            离开时按 Win+L 锁屏——不影响它干活，但挡住路过的人
```