邮件看板 Feizhaiqianqian/dsh-email-board

dsh-email-board

DSH 的邮件看板：把 dsh-email 各账号的未读邮件按账号汇总成卡片列表，展示在 Web 界面右侧栏的「邮件看板」tab 里。卡片显示发件人、主题与时间。

Unread-mail board for DeepSeek Harness.
It collects unread mail from every dsh-email account into a per-account card list
(sender / subject / time) rendered as a custom tab in the DSH right sidebar — read-only, manual refresh, and no model round-trip (it reuses dsh-email's own IMAP pool).

- 只读：不会标记已读、不会删除、不会发信。
- 不经过模型、不调用工具：宿主侧取的就是 email_list 的实现
（EmailPool.list(..., unreadOnly: true)），所以刷新不消耗 token，也不会在会话里留下痕迹。
- 手动刷新：打开 tab 拉一次，之后只有点右上角「刷新」才会重新读邮箱；宿主侧还有一层短路缓存（cacheMs），连点也不会把 IMAP 打爆。

安装

先确认 dsh-email 已启用并配好账号（看板读它的设置）。

克隆本仓库，然后在 DSH 的「插件」页安装这个目录（安装框接受绝对路径）：

<克隆下来的 dsh-email-board 目录绝对路径>

安装器会执行 pnpm add <路径> 并把 dsh-email-board 追加到 profile 的 dsh.profile.bundles。
重启 DSH 之后，右侧栏开始页里就有「邮件看板」入口了。

手动安装等价于：

cd $env:DSH_PROFILE_DIR # 例如 C:\Users\<你>\.dsh\profiles\desktop
pnpm add file:<dsh-email-board 绝对路径>
然后把 "dsh-email-board" 追加到 package.json 的 dsh.profile.bundles 里

开发这个插件时踩过的两个坑（想改源码的话建议先看）

1. file: 是快照，不是活链接。 pnpm add file:<目录> 会把文件拷贝进 node_modules\dsh-email-board（真实目录），之后你在源码目录里的改动永远不会进宿主进程，重启多少次都一样。要在源码目录里持续开发，就把依赖写成 link:<绝对路径>（等价于手工建 junction），让 profile 读活文件：

package.json: "dsh-email-board": "link:C:/.../dsh-email-board"
New-Item -ItemType Junction -Path "$env:DSH_PROFILE_DIR\node_modules\dsh-email-board"
-Target "C:\...\dsh-email-board"

2. 改代码一定要重启 DSH。 宿主进程里的插件模块 import 一次就缓存住了；改 profile 配置（bundle 列表、patch 层）只会重载配置树，不会让宿主重新 import 模块。桌面版 base 组合包以 hmr.root: [] 启用 HMR，等于关掉了模块文件监听，所以也没有代码热重载可指望。

打开看板

1. 打开右侧栏（会话 header 右上角的展开按钮，或快捷键）。
2. 在开始页里点「邮件看板」入口胶囊 —— tab 就此打开，之后跟着会话布局一起保存。

配置

在 profile 的 cordis.patch.yml 里覆盖插件的默认行：

- id: email-board
name: dsh-email-board
config:
accounts: [] # 空数组 = dsh-email 里配置的全部账号
folder: "" # 空 = 各账号自己的 inboxFolder perAccountLimit: 20 # 每个账号最多取多少封未读信封（1-100） cacheMs: 20000 # 宿主侧结果缓存，毫秒（连点刷新时的短路窗口） timeoutMs: 25000 # 单账号 IMAP 超时，毫秒

accounts 里的名字必须和 dsh-email 设置里的账号名一致；填了不存在的名字不会让整块看板失败，只会让那个账号的位置显示一条错误。

实现

| 半侧 | 文件 | 职责 |
| 宿主 | lib/index.js | 读 dsh-email 的设置行 → 用它公开导出的 resolveEmailSettings / toEmailConfig / EmailPool 取每个账号的未读信封 → 挂在同源只读路由 /_dsh/dsh-email-board/state |
| 客户端 | lib/client.js | 注册右侧栏 tab 类型 email-board 与正文槽位 sidebar.right.pane.tab，按需读路由并渲染卡片 |

设计上的两个要点：

- 不复制 dsh-email 的内部实现，只用它 package.json 里公开导出的 API，所以它升级内部结构不会连带打断看板。插件被链接进 profile 时，dsh-email 的解析会退回 profile 的 node_modules （见 profileDirCandidates）。
- 设置行按「显式候选 → 形状识别」两级查找：settings.describe() 的 ns 用的是 profile 条目 id（通常是 tool-email），不一定等于 dsh-email 自己注册的命名空间，写死名字必然踩空。

只读路由带同源判定：Sec-Fetch-Site 不是 same-origin/none 一律 403，非 GET 一律 405 ——未读邮件的标题和发件人是隐私，不该被任意网页一次 GET 读走。

自检

pnpm check # node --check lib/index.js && lib/client.js
pnpm test # 迷你 React 跑一遍客户端注册 + 渲染（用随仓库的虚构样本，零依赖）
pnpm test:host # 真实 IMAP：解析账号 → 取未读 → 路由响应（需要本机 profile 与 dsh-email）
node test/offline-route.mjs --fixture # 把真机响应写到 test/fixture-state.local.json

test/render-board.mjs 优先读 test/fixture-state.local.json，没有就用随仓库发布的 虚构样本 test/fixture-state.json；*.local.json 在 .gitignore 里，真实邮件数据不会被误提交。

已知限制

- 只统计各账号 inboxFolder（或 folder 指定的那一个）里的未读，不遍历全部文件夹。
- 单个账号未读超过 perAccountLimit 时只显示最新若干封，并在分组里标注「只显示最新 N 封」。
- 卡片只读，想看正文仍然用会话里的 email_read。
- 没有定时轮询（刻意留到界面稳定后再加，客户端补一个 setInterval 即可）。

版本

- v0.1.0（2026-10-07）：首个版本 —— 手动刷新的右侧栏看板。完整说明见 CHANGELOG.md。
- 路线：界面稳定后再加自动更新（定时轮询）；卡片交互（标记已读 / 打开正文）待定。

License

MIT