dsh-lookout

dsh-lookout（瞭望哨）

一个 DSH（DeepSeek Harness）插件。它把原来三个独立插件合并成一份：

• dsh-icon-custom：换浏览器标签页图标 / 系统应用图标角标
• dsh-notify-p：会话有动静时发邮件通知
• dsh-session-info：显示当前会话 ID

一句话：瞭望哨：盯着你的每个会话——谁跑完了、谁出错了、谁卡住了、谁在等你审批，用浏览器图标角标、红点/黄点和邮件通知你；顺带显示当前会话 ID。

功能

1. 换图标与角标

在设置页上传 SVG / PNG / ICO 作为标签页图标，上传后立刻写入并持久保存；自动适配安卓 / iOS / 平板的 PWA 图标。未读会话显示红点、正在进行的会话显示黄点，工作区数字、会话行、左上角、标签页图标都会显示；点数字可打开清单，点条目可定位到侧栏对应会话。还可以把未读数投到系统应用图标角标上（Windows 任务栏 / macOS Dock，需要授予通知权限）。

2. 邮件通知

会话跑完 / 出错 / 卡住 / 等你审批时发一封邮件。正文写清是哪个会话：事件、会话标题、工作区、时间、用时、轮次、会话 ID。SMTP 配置与收件人在设置页填写。

改完要点保存：邮件通知这一页是显式保存——改字段只是改草稿，点「保存」才写进配置，点「放弃改动」退回上次保存的值。保存组吸在页头，往下滚到哪儿都看得见；页面底部还压着一条吸底保存条，只有「保存 / 放弃改动」，两处都能点。有没存的改动时状态行写着「有 N 项改动未保存」；授权码粘贴了还没存时，它单独写「有未保存的授权码」，不会假装已经存好；保存成功后读数会随时间退化——刚刚、N 秒前、N 分钟前、N 小时前、N 天前；保存失败会保留草稿并写明原因，可以直接重试；如果是别处先改过配置（revision 冲突），页面会自动重读最新一份、你的草稿原样留着，再点一次保存即可。

保存只写配置与授权码。「发送测试邮件」和「恢复全部默认」不归保存按钮管：前者随时能点、用当前已经保存的配置真发一封，按钮旁会写明这一点——草稿里没保存的改动不参与；后者点下去就清空本插件的全部覆盖并立即生效。

发信人就是 SMTP 账号本身（邮件抬头用固定默认名）：插件不保存多份发件身份，不能另挑一个发件人，也不能代发别的地址。

邮件里不含链接：纯文本版和 HTML 版都没有任何可点的链接，也不带会话地址。想回到那个会话，只能在 DSH 侧栏里自己找——正文里那行会话 ID 就是用来对照的。

发送行为（已经固化在代码里，不需要也不提供调参）：

• 总开关压在所有开关上面：设置页那个「邮件通知」总开关一关，一封都不发；8 个事件开关只是变灰，不会被藏起来，总开关重新打开就照原样继续用。
• 能触发的事件共 8 类：完成、出错、卡住、等审批、主动停止、系统中断、命中长度上限、子代理；每类一个开关，默认只开前四类（子代理默认关）。
• 重复事件只发一封：同一会话、同一回合、同一种结局只投递一次；重放、重订阅、刷新都不会再发。
• 同一会话的新回合会顶掉上一封待发邮件：上一封还在等发时这个会话又动了，就取消旧的那封、只留最新结论——一个会话在同一时刻只有一封待发的信。（回合结束后先等约 1.5 秒，确认没有新回合才发。）
• 太短的活儿不打扰：完成事件要求这段任务至少跑了 2 秒。
• 队列只负责三件事：串行发送、限流（每分钟最多 10 封）、失败退避重试（间隔 1s / 5s / 15s，最多 3 次）。它不做「把多次事件合并成一封」，也不会跨会话攒信。

发信失败怎么查：插件不再保留任何投递记录，失败会在 DSH 日志里留一行 warn（含邮件标签与错误原文；重试过程中另有「第 N/3 次」的记录）；想立刻确认配置能不能发，点设置页顶部判决条上的「发送测试邮件」，它当场返回成败和原始报错。它发的是已保存的那套配置；页面上还有没保存的改动时，判决条会直接提示「未保存的改动不参与判定」，先把改动存了再测才是你在草稿里看到的那个结果。

3. 显示当前会话 ID

会话 ID 现在显示在侧栏会话行的悬停卡片里：鼠标停在侧栏某个会话上，弹出的卡片（标题 / 时间 / 空闲等状态）会多一行等宽字，就是这个会话的完整 ID（session-…），点一下就复制，成功后底部有提示。

这一行挂的是宿主官方插槽 sidebar.session.row.hover，不是贴着界面画上去的，所以宿主升级移动卡片时它会跟着走。开启时顶部原先那串会话 ID 会隐藏（由插件自己的一条 CSS 规则隐藏，不改宿主代码），让 ID 只出现一处；到设置页「会话 ID」分区取消勾选，顶部恢复显示、卡片里那行也不再出现——即完全回到未装本插件时的样子。

4. 文件行 ⋯ 菜单

文件面板里每个文件 / 文件夹行的右侧多出一个「⋯」按钮，点开可以：

• 复制路径：把这一行的绝对路径原样放进剪贴板（不是屏幕上显示的短名）。
• 下载：下载单个文件，上限 20 MB；超过会提示「文件超过 20MB，暂不支持下载」。
• 文件夹：菜单仍可打开，但「下载」是灰的，并标注「文件夹暂不支持」。

设置页里有「文件行 ⋯ 菜单」开关，可以整体关掉。这个菜单是贴着宿主文件树画上去的：DSH 升级换了文件面板结构时，它可能不再出现，但文件树本身不受影响；连续 3 次注入失败会自动停止，并且只提示一次（可点「不再提示」）。

5. 工作区标签 / 隐藏 / 置顶

在设置页「工作区管理」的表格里，可以给每个工作区挂一个标签：灰色胶囊（灰底填充 + 彩色圆点 + 灰白文字），最多 6 个字，显示在侧栏工作区行右侧（悬停出现「⋯」时在它左边）；颜色 8 选 1（红 / 橙 / 黄 / 绿 / 青 / 蓝 / 紫 / 灰），颜色只作用于圆点。还可以隐藏整个工作区（连同它下面的会话），当前会话所在的工作区永远不会被隐藏，表格里取消勾选即可恢复。置顶的工作区排在侧栏最前；新建工作区默认插到最前，插件会自动把置顶项重新排上去，取消置顶则回到置顶前的位置——只支持根工作区，子工作区的「置顶」是灰的。表格下方的「清理失效项」用来清掉已不存在的工作区留下的偏好。

标签和隐藏是贴着侧栏画上去的（工作区行没有官方插槽）：DSH 升级换了结构时可能不再显示，但侧栏本身不受影响；连续 3 次注入失败会自动停止，并且只提示一次。置顶走 DSH 官方开放接口（insertBefore），不改宿主代码。

怎么用

打开 DSH 设置页（Web GUI 的设置 / Settings），找到 瞭望哨（Lookout） 这一项，里面有：

• 图标上传与 PWA / 角标开关
• 未读规则、进行中规则的阈值
• 邮件通知（页面从上到下）：
  • 吸顶保存组：状态行（「有 N 项改动未保存」/「有未保存的授权码」/「已保存 · 刚刚 / N 秒前 / N 分钟前 / N 小时前 / N 天前」/「保存失败：…」）加上「保存」「放弃改动」，这一页唯一的写盘入口；改字段不会立刻生效。它吸在页头，滚动时始终可见
  • 判决条：页面顶部那条唯一的填充色横条，一句话判定已保存的这套配置能不能发信以及不能的原因，另有一行人话摘要（例：「QQ 邮箱 · smtp.qq.com → you@qq.com · 出错、等审批时通知」）；总开关关着时写「已关闭，不会发任何通知」，8 个事件全关时写「通知已全部关闭」；旁边给补配置的入口和「发送测试邮件」（随时可点，用已保存的配置；有未保存改动时读数提示「未保存的改动不参与判定」）
  • 总开关「邮件通知」：关掉之后不再发任何邮件，8 个事件开关跟着变灰但不隐藏
  • 收件人：一个单行输入框，可以直接粘贴多个地址——逗号、分号、换行分隔都认；格式不对就地标红
  • 发信方式：SMTP 主机 / 端口 / 加密方式 / 账号 + 授权码（不是邮箱登录密码）都并排常显；6 家常见邮箱预设点一下就填好；每行说明文字直接显示
  • 通知时机：8 个事件开关一律常显，默认关掉的 3 类也在里面，和其他开关排在一起；「完成」下面标着固定门槛（不足 2 秒不打扰）；每行说明文字直接显示
  • 吸底保存条：页面底部那条，只有「保存 / 放弃改动」
  • 视觉上进一步对齐宿主：说明文字用与宿主同级的小字号，每个区块是带底色的卡片，输入框底色也与宿主一致
• 会话 ID 显示开关
• 文件行 ⋯ 菜单开关
• 工作区管理（标签 / 颜色 / 置顶 / 隐藏，以及「清理失效项」）

数据存在哪

内容	位置
图标、未读规则	$DSH_HOME/custom-favicon/
工作区偏好	$DSH_HOME/custom-favicon/workspace-prefs.json
邮件配置	当前 profile 的 cordis.patch.yml（$DSH_HOME/profiles/<profile>/）里入口 lookout 的 config；授权码走凭据库，配置里只存引用名

（$DSH_HOME 未设置时回退到 ~/.dsh。）邮件通知不落盘投递记录：发信成败只看日志。

设置页按配置指纹认领命名空间：打开页面时读 settings.describe()，value 里同时有 smtpHost 与 smtpPasswordRef 的那一项就是本插件，认领到的 ns 就是 profile 的入口 id（本机是 lookout），不再写死 dsh-notify-p，换 profile、改入口 id 都不会失联。之所以不按 schema 认领，是因为 describe() 给的 schema 只是 schema.toJSON() 快照（只有 uid / refs），看不到字段名与类型。已知限制：指纹只认配置、匹配时取第一个命中，同一 profile 里并排装两份同源插件会被认成同一份，页面只对着第一条读写。旧的 $DSH_HOME/settings.yaml 已由 DSH 导入后改名为 settings.yaml.imported，只作历史证据，插件不再读它。

开发提示

包内 lib/icon/**、lib/notify/**、lib/session/** 原本是三份原插件代码的逐字节副本，用于保证合并前后行为一致。现在 lib/notify/ 已经不是逐字节副本：本次修 Settings 集成（导出 Config、字段标 .volatile()）改过 lib/notify/config.js 与 lib/notify/index.js；lib/icon/**、lib/session/** 仍是副本。

要改功能逻辑，请改这三个目录；根部的 lib/index.js 只是把三者组装起来的胶水层。

test/fixtures/*.client.js 也是原插件浏览器半边的副本，只供测试做包含断言，原则上不要改。例外：本次为保证合并契约同步改过 test/fixtures/notify.client.js；改夹具后必须同步重建 client/client.js，否则夹具与产物对不上，断言会假通过。

测试

node --test "test/*.test.mjs"