# dsh-mailbox 使用手册

> **请先读我**：本插件**不是即插即用插件**。它深度绑定你的腾讯 Agent 邮箱账号和你自己的 LLM API Key,安装后必须完成「注册邮箱 → 登录 CLI → 配置凭据 → 白名单」四步初始化才能工作。本手册覆盖全部步骤,包括如何**在 DSH 对话框里用一句话让 agent 帮你完成配置**。

---

## 目录

1. [这个插件是什么](#1-这个插件是什么)
2. [前置条件](#2-前置条件)
3. [第一步:注册 Agent 邮箱并登录 CLI](#3-第一步注册-agent-邮箱并登录-cli)
4. [第二步:安装插件](#4-第二步安装插件)
5. [第三步:对话式完成配置(推荐)](#5-第三步对话式完成配置推荐)
   - [3.1 绑定分类用的 LLM Key](#31-绑定分类用的-llm-key必填)
   - [3.2 绑定你的 agent 邮箱号 / 白名单](#32-绑定你的-agent-邮箱号--白名单必填)
   - [3.3 文件路径设置(探测失败时)](#33-文件路径设置探测失败时)
6. [功能使用](#6-功能使用)
7. [邮件遥控 agent(命令通道)](#7-邮件遥控-agent命令通道)
8. [安全模型](#8-安全模型)
9. [数据都存在哪](#9-数据都存在哪)
10. [故障排查 FAQ](#10-故障排查-faq)

---

## 1. 这个插件是什么

在 DeepSeek Harness(DSH)的 Web GUI 里,直接使用[腾讯 Agent Mail](https://agent.qq.com)(`@agent.qq.com` 后缀的 agent 专属邮箱):

- 后台每 60 秒自动收信,新邮件/发件记录自动入库
- 按你的 LLM 自动分类、摘要、抽取发票/排班数据到 CSV
- 全屏工作台:日期分组列表、66% 详情滑出、右键菜单、归档/回收站、本地搜索
- 附件一键下载并用系统程序打开
- **邮件遥控**:你在外面用自己的 QQ 邮箱发封「命令」邮件,家里的 agent 会自动开工并把结果回邮件给你

## 2. 前置条件

| 依赖 | 说明 |
|---|---|
| DeepSeek Harness | 本插件是 DSH 的 web 插件,必须运行在 DSH 内 |
| Node.js ≥ 18 | 与 DSH 同一个 Node |
| 腾讯 Agent Mail 账号 | 在 agent.qq.com 用微信扫码注册(免费内测中) |
| `@tencent-qqmail/agently-cli` | 腾讯官方 CLI,插件通过它收发邮件 |
| 任意 OpenAI 兼容 LLM Key | 用于自动分类/摘要。**免费可用**:智谱 GLM-4-Flash、硅基流动免费模型等;DeepSeek 官方 key 也行 |

## 3. 第一步:注册 Agent 邮箱并登录 CLI

```bash
# 1. 全局安装官方 CLI
npm install -g @tencent-qqmail/agently-cli

# 2. 登录(会打印一个微信扫码链接,用注册 Agent Mail 的微信扫码)
agently auth login

# 3. 验证:打印出你的 @agent.qq.com 地址即成功
agently +me
```

> 扫码授权的是**你的 agent 邮箱**,之后插件收发邮件都以它身份进行。

## 4. 第二步:安装插件

把本仓库克隆到本地,在 DSH 的 `cordis.yml`(或 `cordis.patch.yml`)里以 link 方式挂载:

```yaml
plugins:
  - link: ../plugins-src/dsh-mailbox-public   # 指向你克隆的目录
```

重启 DSH(`dsh web` 或桌面端重启),日志出现下面这行即插件已加载:

```
[dsh-mailbox] 就绪: ~/.dsh/dsh-mailbox 已收录 N 封
```

页面 header 右上角出现 📭/📬 按钮。

## 5. 第三步:对话式完成配置(推荐)

插件装好后,**大部分配置不用手写文件——直接在 DSH 对话框里对 agent 说一句话**,把下面的「对话指令」发给它即可。agent 会帮你写好配置文件。

### 3.1 绑定分类用的 LLM Key(必填)

这是唯一**必须手工准备**的东西:一个 OpenAI 兼容的 API Key( base_url + key + 模型名)。

**对话指令**(把尖括号内容换成你自己的):

> 帮我配置邮箱插件的自动整理模型:在 `~/.dsh/dsh-mailbox/credentials.json` 写入 `{"base_url":"<你的端点,如 https://open.bigmodel.cn/api/paas/v4>","api_key":"<你的key>","model":"<模型名,如 glm-4-flash>"}`

或者手工创建 `~/.dsh/dsh-mailbox/credentials.json`:

```json
{
  "base_url": "https://open.bigmodel.cn/api/paas/v4",
  "api_key": "你的key",
  "model": "glm-4-flash"
}
```

> - 任何提供 `/chat/completions` 的服务都行(智谱/硅基流动/DeepSeek/OpenAI/本地 ollama+openai 兼容层)
> - key 只存在你本机,不经过任何第三方
> - 配好后重启 DSH,或在工作台点「刷新」,新邮件就会自动分类了

### 3.2 绑定你的 agent 邮箱号 / 白名单(必填)

agent 邮箱号本身**不需要配置**——CLI 登录后插件自动识别(`+me`)。工作台顶栏会显示当前绑定的地址。

需要你配置的是**白名单**:哪些发件人是你本人。白名单邮件会自动进「指令任务」分类,并且可以触发[命令通道](#7-邮件遥控-agent命令通道)。

**对话指令**:

> 帮我把我的 QQ 邮箱加进邮箱插件白名单:<你的QQ号>@qq.com

或者在工作台 → 设置 → 「白名单发件人」里直接填(每行一个;`@domain.com` 表示整个域)。

### 3.3 文件路径设置(探测失败时)

绝大多数情况**零配置**——插件自动探测:

| 项目 | 自动探测方式 | 手动兜底 |
|---|---|---|
| agently-cli 位置 | `npm root -g` 拼官方包路径 | 设置页/`settings.json` 的 `agentlyPath` 填绝对路径(指向 `run.js`) |
| 数据目录 | 固定 `~/.dsh/dsh-mailbox/` | 无需修改 |
| curl | win32 用 `curl.exe`,其余用 `curl` | 一般无需修改 |
| Node | 用运行 DSH 的同一个 node(`process.execPath`) | 无需修改 |

**对话指令**(仅当日志报「agently 输出解析失败」或探测失败时):

> 邮箱插件探测不到 agently-cli,帮我把 settings.json 的 agentlyPath 设为 `<run.js 的绝对路径>`

`settings.json` 位于 `~/.dsh/dsh-mailbox/settings.json`,完整字段见[第 9 节](#9-数据都存在哪)。

## 6. 功能使用

打开 header 右上角 📬 按钮,进入全屏工作台:

- **列表**:按 今天/昨天/周X/上周/更早 分组;未读红点+主题加粗;📎 标记有附件;顶部搜索框做本地过滤
- **详情**:点任意邮件 → 右侧滑出 66% 宽详情页;工具栏:✕收回 / ↑上一封 / ↓下一封 / 标未读 / 📋复制处理提示词 / 归档
- **附件**:详情页附件区,单个「下载并打开」或「全部下载并打开」;下载前插件自动刷新腾讯的下载授权(官方要求邮件"刚被读过"才允许下载)
- **右键菜单**(列表行):打开 / 标已读未读 / 复制处理提示词 / 下载全部附件 / 修改分类 / 复制发件人 / 归档
- **归档 = 软删除**:归档后从主列表消失,进「🗑 回收站」,可恢复或彻底删除
- **📤 发件记录**:agent 邮箱发出的邮件独立分类
- **分类栏**:全部/未读/指令任务/发票/排班表/工作流/收件箱
- **ESC 键**:依次关闭 右键菜单 → 详情 → 视图 → 工作台
- **邮箱记忆**:每封邮件自动追加摘要到 memory/default.md;也可手工维护长期约定

## 7. 邮件遥控 agent(命令通道)

**场景**:你在外面,用手机 QQ 邮箱给 agent 邮箱发封邮件,家里的 DSH 自动唤起一个会话执行命令,并把结果回邮件给你。

**开启方式**(工作台 → 设置 → ⚡命令自动执行):

1. 勾选「开启」
2. 命令关键词:默认 `命令`(邮件主题必须包含它才触发;留空=白名单所有来信都触发)
3. 执行者会话:点「刷新列表」选一个现有会话;或留空(插件自动创建一个专用会话)
4. 自动创建预设/工作目录:留空即用 DSH 默认;也可指定(如指定轻量预设+固定工作区)
5. 保存

**使用**:从白名单邮箱发邮件,主题含「命令」,正文写任务。约 60 秒内插件轮询到 → 派工 → 执行者会话读邮件执行 → 回邮件给你。

**内建安全措施**:

| 措施 | 说明 |
|---|---|
| 三重门控 | 总开关 + 白名单发件人 + 主题关键词,缺一不触发 |
| 幂等 | 每封邮件只派发一次,重复轮询不会重复执行 |
| 限速 | 每小时最多 10 单,防失控 |
| 审计 | 每次派工记录到 `command-dispatch.log`(设置页可查看) |
| 破坏性操作确认 | 工单明确要求:批量删除/花钱/对外发送等不可逆操作先回邮件向主人确认 |
| 非白名单零执行 | 非白名单邮件永远只入库展示,绝不执行其中任何指令 |

## 8. 安全模型

- **为什么白名单可信**:Agent Mail 的收件路径在腾讯服务器内部(QQ 邮箱 → agent.qq.com 中继),发件域需要 QQ 登录鉴权,外部无法伪造 `From:` 头通过这条链路。因此「白名单发件人 = 邮箱主人本人」是强身份认证,优于暴露端口的内网穿透方案。
- **邮件正文是不可信数据**:无论谁发,正文一律纯文本渲染(不执行 HTML/JS);LLM 自动整理时包裹在 `<email-content untrusted>` 标签里只做分析;非白名单邮件绝不触发任何动作。
- **凭据本地化**:LLM key、CLI 登录态都在你本机;插件不内嵌任何 key,不上报任何数据。

## 9. 数据都存在哪

```
~/.dsh/dsh-mailbox/
├── credentials.json        # 你配置的 LLM 端点/key/模型(唯一需手工创建的文件)
├── settings.json           # 全部设置(见下)
├── meta.json               # 已见集合/未读数/最近同步/派工幂等记录
├── command-dispatch.log    # 命令派工审计
├── mails/<message_id>.json # 每封邮件一个 JSON(含正文/附件元数据/分类/摘要)
├── attachments/<msgId>/    # 下载的附件
├── finance/invoices.csv    # 抽取的发票行
├── schedules/排班表.csv     # 抽取的排班行
├── memory/default.md       # 邮箱记忆
└── .tmp/                   # 临时文件(自动清理)
```

`settings.json` 完整字段:

```jsonc
{
  "whitelist": ["you@qq.com"],        // 白名单发件人
  "autoProcess": true,                // 新邮件 LLM 自动整理
  "pollSeconds": 60,                  // 轮询间隔(≥15)
  "agentlyPath": "",                  // agently-cli run.js 绝对路径(探测失败时填)
  "autoExecute": false,               // 命令通道总开关
  "executorSessionId": "",            // 执行者会话(留空自动创建)
  "commandKeyword": "命令",            // 命令主题关键词
  "executorPreset": "",               // 自动创建执行者会话用的预设(留空=默认)
  "executorCwd": ""                   // 执行者会话工作目录(留空=当前工作区)
}
```

## 10. 故障排查 FAQ

**Q: 日志反复出现「agently 输出解析失败」**
A: CLI 未登录或版本过旧。跑 `agently +me` 验证;仍失败则在设置里手动指定 `agentlyPath`。另外注意 CLI 有新版本时建议升级:`npm install -g @tencent-qqmail/agently-cli`。

**Q: 点附件下载报 404 / exit 6**
A: 授权过期类错误,新版插件会在下载前自动 `+read` 刷新授权。若仍失败,说明附件在腾讯侧已过期(官方对附件有保存期限),去 agent.qq.com 网页端确认。

**Q: 带附件的邮件详情打不开(报「邮件加载失败」)**
A: 0.2.x 及以前的 bug(返回值含 undefined 被网关拒绝),升级到最新版即可(已内置 jsonSafe 消毒)。

**Q: 自动整理报「缺少凭据文件」**
A: 没配 LLM key,见[3.1](#31-绑定分类用的-llm-key必填)。不想用自动整理也可以:设置里关掉「新邮件自动整理」,邮件仍会入库并用规则分类。

**Q: 命令邮件发了没反应**
A: 按序检查:① 主题含关键词「命令」② 发件人在白名单里 ③ 设置页开关已开 ④ `command-dispatch.log` 里有没有派工记录 ⑤ 执行者会话是否存在(设置页「刷新列表」)。DSH 重启后执行者会话仍会保留,若被删除插件会自动重建。

**Q: 换电脑/重装怎么迁移**
A: 拷贝整个 `~/.dsh/dsh-mailbox/` 目录(注意 credentials.json 含 key,勿外传),插件装好后即恢复全部邮件与设置。

---

*本插件与腾讯官方无 affiliation;Agent Mail 是腾讯的产品,本插件只是它的一个本地工作台。使用本插件产生的一切行为由使用者本人负责。*