@cowwo/dsh-lookout 0.1.2 → 0.5.0

package/README.md

@@ -12,15 +12,35 @@
 
 ### 1. 换图标与角标
 
-在设置页上传 SVG / PNG / ICO 作为标签页图标，立即生效并持久保存；自动适配安卓 / iOS / 平板的 PWA 图标。未读会话显示**红点**、正在进行的会话显示**黄点**，工作区数字、会话行、左上角、标签页图标都会显示；点数字可打开清单，点条目可定位到侧栏对应会话。还可以把未读数投到系统应用图标角标上（Windows 任务栏 / macOS Dock，需要授予通知权限）。
+在设置页上传 SVG / PNG / ICO 作为标签页图标，上传后立刻写入并持久保存；自动适配安卓 / iOS / 平板的 PWA 图标。未读会话显示**红点**、正在进行的会话显示**黄点**，工作区数字、会话行、左上角、标签页图标都会显示；点数字可打开清单，点条目可定位到侧栏对应会话。还可以把未读数投到系统应用图标角标上（Windows 任务栏 / macOS Dock，需要授予通知权限）。
 
 ### 2. 邮件通知
 
-会话**跑完 / 出错 / 卡住 / 等你审批**时发一封邮件。正文写清是哪个会话，并附一条可点击直达该会话的链接。SMTP 配置、收件人等都在设置页填写。短时间内的多次事件会按队列合并发送，避免轰炸邮箱。
+会话**跑完 / 出错 / 卡住 / 等你审批**时发一封邮件。正文写清是哪个会话：事件、会话标题、工作区、时间、用时、轮次、会话 ID。SMTP 配置与收件人在设置页填写。
+
+**改完要点保存**：邮件通知这一页是显式保存——改字段只是改草稿，点右上角「保存」才写进配置，点「放弃改动」退回上次保存的值。有没存的改动时状态行写着「有 N 项改动未保存」；保存成功后变成「已保存 · N 秒前」；保存失败会保留草稿并写明原因，可以直接重试；如果是别处先改过配置（revision 冲突），页面会自动重读最新一份、你的草稿原样留着，再点一次保存即可。
+
+**保存只写配置与授权码**。「发送测试邮件」和「恢复全部默认」不归保存按钮管：前者随时能点、用当前**已经保存**的配置真发一封，按钮旁会写明这一点——草稿里没保存的改动不参与；后者点下去就清空本插件的全部覆盖并立即生效。
+
+**发信人就是 SMTP 账号本身**（邮件抬头用固定默认名）：插件不保存多份发件身份，不能另挑一个发件人，也不能代发别的地址。
+
+**邮件里不含链接**：纯文本版和 HTML 版都没有任何可点的链接，也不带会话地址。想回到那个会话，只能在 DSH 侧栏里自己找——正文里那行会话 ID 就是用来对照的。
+
+发送行为（已经固化在代码里，不需要也不提供调参）：
+
+- **能触发的事件共 8 类**：完成、出错、卡住、等审批、主动停止、系统中断、命中长度上限、子代理；每类一个开关，默认只开前四类（子代理默认关）。
+- **重复事件只发一封**：同一会话、同一回合、同一种结局只投递一次；重放、重订阅、刷新都不会再发。
+- **同一会话的新回合会顶掉上一封待发邮件**：上一封还在等发时这个会话又动了，就取消旧的那封、只留最新结论——一个会话在同一时刻只有一封待发的信。（回合结束后先等约 1.5 秒，确认没有新回合才发。）
+- **太短的活儿不打扰**：完成事件要求这段任务至少跑了 2 秒。
+- **队列只负责三件事**：串行发送、限流（每分钟最多 10 封）、失败退避重试（间隔 1s / 5s / 15s，最多 3 次）。它不做「把多次事件合并成一封」，也不会跨会话攒信。
+
+发信失败怎么查：插件不再保留任何投递记录，失败会在 DSH 日志里留一行 warn（含邮件标签与错误原文；重试过程中另有「第 N/3 次」的记录）；想立刻确认配置能不能发，点设置页顶部判决条上的「发送测试邮件」，它当场返回成败和原始报错。它发的是**已保存**的那套配置；页面上还有没保存的改动时，判决条会直接提示「未保存的改动不参与判定」，先把改动存了再测才是你在草稿里看到的那个结果。
 
 ### 3. 显示当前会话 ID
 
-在会话头部右侧显示当前会话的完整 ID；复制时会净化剪贴板内容，避免选区夹带多余换行。
+会话 ID 现在显示在**侧栏会话行的悬停卡片**里：鼠标停在侧栏某个会话上，弹出的卡片（标题 / 时间 / 空闲等状态）会多一行等宽字，就是这个会话的完整 ID（`session-…`），**点一下就复制**，成功后底部有提示。
+
+这一行挂的是宿主官方插槽 `sidebar.session.row.hover`，不是贴着界面画上去的，所以宿主升级移动卡片时它会跟着走。开启时顶部原先那串会话 ID 会隐藏（由插件自己的一条 CSS 规则隐藏，不改宿主代码），让 ID 只出现一处；到设置页「会话 ID」分区取消勾选，顶部恢复显示、卡片里那行也不再出现——即完全回到未装本插件时的样子。
 
 ### 4. 文件行 ⋯ 菜单
 
@@ -32,31 +52,47 @@
 
 设置页里有「文件行 ⋯ 菜单」开关，可以整体关掉。这个菜单是贴着宿主文件树画上去的：DSH 升级换了文件面板结构时，它可能不再出现，但**文件树本身不受影响**；连续 3 次注入失败会自动停止，并且只提示一次（可点「不再提示」）。
 
+### 5. 工作区标签 / 隐藏 / 置顶
+
+在设置页「工作区管理」的表格里，可以给每个工作区挂一个**标签**：灰色胶囊（灰底填充 + 彩色圆点 + 灰白文字），最多 6 个字，显示在侧栏工作区行右侧（悬停出现「⋯」时在它左边）；颜色 8 选 1（红 / 橙 / 黄 / 绿 / 青 / 蓝 / 紫 / 灰），颜色只作用于圆点。还可以**隐藏**整个工作区（连同它下面的会话），当前会话所在的工作区永远不会被隐藏，表格里取消勾选即可恢复。**置顶**的工作区排在侧栏最前；新建工作区默认插到最前，插件会自动把置顶项重新排上去，取消置顶则回到置顶前的位置——只支持根工作区，子工作区的「置顶」是灰的。表格下方的「清理失效项」用来清掉已不存在的工作区留下的偏好。
+
+标签和隐藏是贴着侧栏画上去的（工作区行没有官方插槽）：DSH 升级换了结构时可能不再显示，但**侧栏本身不受影响**；连续 3 次注入失败会自动停止，并且只提示一次。置顶走 DSH 官方开放接口（`insertBefore`），不改宿主代码。
+
 ## 怎么用
 
 打开 DSH 设置页（Web GUI 的设置 / Settings），找到 **瞭望哨（Lookout）** 这一项，里面有：
 
 - 图标上传与 PWA / 角标开关
 - 未读规则、进行中规则的阈值
-- 邮件通知：SMTP 主机、端口、账号、密码、收件人，以及「发一封测试邮件」按钮
+- 邮件通知（页面从上到下）：
+  - **保存组**：右上角的状态行（「有 N 项改动未保存」/「已保存 · N 秒前」/「保存失败：…」）加上「保存」「放弃改动」，这一页唯一的写盘入口；改字段不会立刻生效
+  - **判决条**：顶部那条唯一的填充色横条，一句话判定**已保存的这套配置**能不能发信以及不能的原因，旁边给补配置的入口和「发送测试邮件」（随时可点，用已保存的配置；有未保存改动时读数提示「未保存的改动不参与判定」）
+  - **收件人**：收件人清单，格式不对就地标红
+  - **怎么发**：SMTP 主机 / 端口 / 加密方式 / 账号 + 授权码（不是邮箱登录密码），顶部 6 家常见邮箱预设点一下就填好
+  - **什么时候发给我**：8 个事件开关；「完成」下面标着固定门槛（不足 2 秒不打扰），默认关掉的 3 类收在「还有 3 种情况」折叠层里
 - 会话 ID 显示开关
 - 文件行 ⋯ 菜单开关
+- 工作区管理（标签 / 颜色 / 置顶 / 隐藏，以及「清理失效项」）
 
 ## 数据存在哪
 
 | 内容 | 位置 |
 | --- | --- |
 | 图标、未读规则 | `$DSH_HOME/custom-favicon/` |
-| 邮件账本（投递记录） | `$DSH_HOME/dsh-notify-p/state.json` |
-| 邮件配置 | `$DSH_HOME/settings.yaml` 的 `dsh-notify-p` 段 |
+| 工作区偏好 | `$DSH_HOME/custom-favicon/workspace-prefs.json` |
+| 邮件配置 | 当前 profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<profile>/`）里入口 `lookout` 的 `config`；授权码走凭据库，配置里只存引用名 |
+
+（`$DSH_HOME` 未设置时回退到 `~/.dsh`。）邮件通知不落盘投递记录：发信成败只看日志。
 
-（`$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/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` 只是把三者组装起来的胶水层。
 
-**要改功能逻辑，请改这三个目录**；根部的 `lib/index.js` 只是把三者组装起来的胶水层。`test/fixtures/*.client.js` 同样是原插件浏览器半边的逐字节副本，只供测试做包含断言，不要改。
+`test/fixtures/*.client.js` 也是原插件浏览器半边的副本，只供测试做包含断言，原则上不要改。**例外**：本次为保证合并契约同步改过 `test/fixtures/notify.client.js`；改夹具后必须同步重建 `client/client.js`，否则夹具与产物对不上，断言会假通过。
 
 ## 测试