macOS 完成通知 Tania-X/dsh-notify-macos

dsh-notify-macos

DeepSeek Harness（DSH）的 macOS 通知插件：任务一结束，就在屏幕右上角弹出常驻悬浮卡片；点一下，浏览器原地跳到那个会话的完成位置。切去干别的也不怕错过 —— 卡片会一直等你。

┌──────────────────────────────────────────┐
│ ● 我的数据分析会话 ▾ │ ← 标题 = 会话名 │ 已完成 2 次 · 最近 14:32 │ ← 同一会话多次完成会合并 ├──────────────────────────────────────────┤ │ 14:31 任务已完成 │ ← 展开后逐行点：跳各自的位置 │ 14:32 任务失败，点击查看详情 │ └──────────────────────────────────────────┘

三种状态，一眼分辨

| 卡片 | 什么时候出现 | 点击它 |
| 🟢 completed | 任务正常结束 | 跳到这次完成的位置（不是会话底部） |
| 🔴 error | 任务异常结束（报错/中断/超 token） | 同上，去看发生了什么 |
| 🟠 blocked | 需要你处理：等你授权、或等你回答问题 | 跳到等你处理的现场 |

安装

前置：macOS（插件只支持 macOS）+ 已经在用 DSH 的 web profile（dsh web）。

一条命令：装进 web profile 并自动激活（包内声明了 dsh.bundle）
dsh plugin --profile web add github:Tania-X/dsh-notify-macos

然后重启 dsh，让它完成一个小任务试试
dsh web

不需要手工编辑任何 patch 文件：包内自带 cordis.patch.yml，dsh plugin add 会把它并进 profile 的层栈。装完可以这样确认：

dsh --profile web --dump-config | grep -A 3 notify-macos # 应看到 notify-macos 条目

想改配置（换 socket 路径、关掉提示音等）不用动包里的文件，在 profile 自己的 cordis.patch.yml 里按 id 覆盖即可（用户层永远在 bundle 层之后应用）： $DSH_HOME/profiles/web/cordis.patch.yml
- id: notify-macos
config:
socketPath: /tmp/dsh-notify-macos.sock

只写你要改的字段即可，其余走插件自身的默认值；可覆盖的字段见下面的「配置」。

⚠️ 这个文件必须是顶层 YAML 数组：想临时关掉所有覆盖时请保留最后一行的 []，不要留成"只有注释"的空文件 —— 那样解析成 null，dsh 会因为 must be a top-level YAML array of loader patch entries 直接启动失败（实测踩过）。

装好了怎么确认

插件被 GUI 加载了吗（应看到 notify-macos，且是 active）
curl -s -X POST http://127.0.0.1:3080/api/pluginInventory/list \
-H "Content-Type: application/json" \
-d '{"type":"client-request","rpcId":"v1","method":"pluginInventory/list","payload":{"args":{}}}'

守护进程活着吗（注意：请求必须以换行结尾） printf '{"cmd":"ping"}\n' | nc -U "$TMPDIR/dsh-notify-macos.sock" # → {"ok":true} 若你在配置里钉了 socketPath，就换成那个路径（例如 /tmp/dsh-notify-macos.sock）

二进制说明：仓库里预编译的 bin/dsh-notify-server 是 universal（Apple Silicon + Intel），两种 Mac 都能直接用。若它被 Gatekeeper 拦下（从浏览器下载的压缩包会带隔离标记）： xattr -dr com.apple.quarantine /path/to/dsh-notify-macos。

二进制里嵌了源码指纹（Sources/ + Package.swift 的摘要），用来回答"提交的这个产物和源码是同一版吗"。所以改完 Swift 代码请用脚本重建（它会同步指纹）：

scripts/build-universal.sh # 编 universal 双架构 + 更新指纹 scripts/fingerprint-check.sh # 只想核对：提交的产物 vs 当前源码

直接 swift build -c release && cp .build/release/dsh-notify-server bin/ 会让指纹对不上
（CI 会红）。原因与边界见 docs/troubleshooting.md §28。

使用

装着就不用管了。任务结束时卡片自己出现，然后：

| 操作 | 效果 |
| 点某一行 | 浏览器跳到那一行自己的完成位置，并移除该行（一行一行处理） |
| 点卡片标题 | 展开/收起多行明细（单行卡片点了就是跳转） |
| 往右拖拽 | 清掉这张卡（整个会话的通知一起清） |
| 什么都不做 | 卡片常驻，直到你处理；重启 dsh / daemon 崩了也不会丢（有快照恢复） |
| 🟠 琥珀行 | 你在 GUI 里点了同意/拒绝、或回答了提问之后，它自己消失（不用手动清） |

跳转是原地切换：浏览器不刷新、不新开标签页，直接落到该会话的那次完成处；如果那次完成已经滚出可视区，它会自动点「加载更早」翻回去。
首次点击会弹一次系统授权：macOS 会问「终端（或你启动 dsh 的那个 App）想要控制 Safari / 浏览器」→ 允许即可。
这是 macOS 自动化权限，只需一次；它归属于启动 dsh 的那个 App，不是本插件。

配置

都写在 cordis.patch.yml 的 notify-macos.config 里：

| 字段 | 默认 | 说明 |
| enabled | true | 总开关 |
| clickAction | "jump-web" | 点击行为：jump-web 跳会话 / open-web 打开 webUrl / open-folder 打开工作目录 / none 只消除 |
| webUrl | "http://127.0.0.1:3080" | GUI 地址（端口不同就改这里） |
| messageCompleted | "任务已完成" | 🟢 卡片正文 |
| messageError | "任务失败，点击查看详情" | 🔴 卡片正文 |
| messageBlocked | "需要你处理，点击查看详情" | 🟠 卡片正文 |
| sound | false | 弹卡片时是否播提示音 |
| rootOnly | true | 只通知顶层会话；false 时子代理完成也通知 |
| autoDismissSec | 0 | 自动消失秒数（0 = 常驻） |
| title | "DeepSeek Harness" | 拿不到会话名时的兜底标题 |
| socketPath | $TMPDIR/dsh-notify-macos.sock | 与守护进程通信的 socket（示例配置里钉成 /tmp/... 只是为了好敲） |
| serverPath | 包内 bin/dsh-notify-server | 守护进程路径 |

出问题先看这几条

| 症状 | 先检查 |
| 完全不弹卡 | dsh web 是否在跑；cordis.patch.yml 里是否注册了 notify-macos；改完 host 半区要重启 dsh web（不是热更新） |
| 点卡片没反应 | 首次点击的 macOS 自动化授权是否点了「允许」；终端里 log 见 docs/troubleshooting.md §20 |
| 抬起来的浏览器窗口不对 | 宿主窗口在别的桌面/被最小化时的分支行为，见 §20 / §22（§22 的探测机制已按 §23 简化） |
| 琥珀卡片不自动消失 | 该行对应的授权/提问是否真在 GUI 里处理过（§24） |
| 卡片莫名消失 / daemon 不见了 | daemon 会自愈重启；历史上"凭空消失"的根因是 SIGPIPE，见 §21 |
| 想自己查状态 | 见 docs/protocol.md：ping / state / probe / debug |

完整踩坑记录（每一条都有真实现场与修法）：docs/troubleshooting.md。

要给作者反馈问题时，附上这三样最有用：

printf '{"cmd":"state"}\n' | nc -U "$TMPDIR/dsh-notify-macos.sock" # 当前卡片状态 tail -50 /tmp/dsh-notify-macos.log # 守护进程日志（固定路径） sw_vers; uname -m; dsh --version # macOS / 架构 / DSH 版本

它是怎么跑起来的（简略）

DSH host 进程（lib/index.js） │ 监听 turn/end、approval/asked、tool/call，归一成 completed / error / blocked │ Unix socket 推一条 show 指令（带 sessionId、turn 位置锚点、blocked 行的关联键） ▼ dsh-notify-server（Swift/AppKit 守护进程，插件按需拉起） │ 在右上角画卡片；点击时用 AppleScript 把 GUI 标签页指向 │ http://127.0.0.1:3080/#dsh-notify-macos/session=<id>&turn=N ▼ client 半区（lib/client.js，跑在 GUI 页面里）收到 hash → 调前端原生 sessions.open(id) → 滚到那个 turn 的完成处

三个刻意的设计取舍，值得知道的只有这些：

- 跳转不碰 DOM：守护进程只负责把标签页指向一个 hash，页面里的 client 半区用前端原生 API 切会话（无需浏览器「允许 AppleScript 执行 JS」那种授权）；
- 卡片持久化：卡栈原子写进 <socketPath>.cards.json，daemon 重启/崩溃后未处理的卡片自动回来；
- 不猜"你看见没有"：只判定"跳转有没有交给浏览器"，交出去了才消除卡片，否则保留可重试（细节与教训见 §20/§23）。

更多设计文档：docs/l2-swiftpm-split.md（Core/服务端分层）、docs/roadmap.md（后续拓展与同类项目对比）。

开发与测试

swift build -c release # 编译守护进程
cp .build/release/dsh-notify-server bin/ # 产物就位（serverPath 默认指向这里）

npm test # host/client 纯逻辑（vitest，48 条）
./test/socket-smoke.sh # daemon 协议冒烟（24 条，含竞态与 SIGPIPE 断言） ./test/core-local-check.sh # Core 不变量自检（swiftc 直编，无需 XCTest） ./test/typecheck-swift-tests.sh # XCTest 源码类型检查（桩模块，无需 XCTest）bash swift test # 完整 XCTest（需含 XCTest 的 Xcode 工具链）
npm run test:e2e # client 半区 Playwright（自带 harness 页）

CI（.github/workflows/tests.yml）：ubuntu 跑 vitest + Playwright，macos-15 跑 swift test + Core 自检 + 真 socket 集成测试。

兼容性与 DSH 升级

针对版本：本插件针对 DSH 0.1.1-rc.2 开发与验证（peerDependencies 声明了 @deepseek-ai/dsh-agent / dsh-session-title / cordis；它们只是适配声明，运行时由宿主提供）。

DSH 升级有可能改动插件依赖的契约。升级前先跑自检： bash
node test/manual/contract-check.mjs # 检查本机安装（默认 $DSH_HOME）
DSH_HOME=/tmp/try-home node test/manual/contract-check.mjs # 先在建好的隔离 home 里试目标版本

自检只读文件、5 秒出结论，会逐项列出：事件词表、agent/status、ask_user_question、前端锚点（turn-tail / loadOlder）、sessions 服务、profile 接线，以及正在运行的守护进程是不是你安装的那个产物（升级后旧进程还在跑时，你会以为修复生效了其实没有）；退出码 1 = 有核心契约缺失。

降级地图（升级后出问题时按这张表定位）：

| 契约变了 | 症状 | 严重度 |
| 事件名（turn/end、approval/、tool/） | 对应类型的卡片静默不再出现 | 中（不崩） |
| agent/status running→idle | 完成类卡片不再出现 | 中（不崩） |
| ask_user_question 改名 | 提问类琥珀卡不再出现 | 低 |
| 前端锚点（turn-tail、loadOlder） | 位置跳转降级为"钉最新" | 低（有兜底） |
| sessions.open 改名 | 点击不跳转（卡片本身正常） | 低 |
| ctx.on 等加载契约 | 插件安静降级，DSH 照常启动 | 低（已加固：加载与 handler 都有 try/catch） |

先隔离试跑再决定（推荐；不碰现有安装）： bash

1) 把目标版本装进独立的 DSH_HOME（npm 全局布局；npmmirror 在国内更快）

npm install -g --prefix ~/.dsh-try --registry=https://registry.npmmirror.com \
@deepseek-ai/dsh@<目标版本>

npm 会把包放到 ~/.dsh-try/lib/node_modules —— 搬成与现装一致的布局：

mv ~/.dsh-try/lib/node_modules ~/.dsh-try/node_modules && rmdir ~/.dsh-try/lib
ln -sfn ../node_modules/@deepseek-ai/dsh/lib/bin.js ~/.dsh-try/bin/dsh

2) 把状态复制进去（不要动原件），并把插件 socket 改到不冲突的路径

cp -c -R ~/.dsh/{profiles,sessions,storages,settings.yaml,.credentials.yaml} ~/.dsh-try/

~/.dsh-try/profiles/web/cordis.patch.yml 里把 socketPath 换成 /tmp/dsh-notify-try.sock

3) 起在另一个端口，别抢 3080

DSH_HOME=~/.dsh-try ~/.dsh-try/bin/dsh web --port 3081

4) 自检对着隔离 home 跑（结论直接决定要不要升级）

DSH_HOME=~/.dsh-try node test/manual/contract-check.mjs

cp -c 在 APFS 上是秒级克隆，不占额外空间；隔离 home 里会话/存储会被新版本就地迁移，所以务必是副本。实测结论示例（0.1.1-rc.2 → 0.1.5-rc.2）：事件词表、agent/status、ask_user_question、sessions 服务都还在（卡片与点击打开会话不受影响），但新前端移除了 data-chat-anchor-key / turn-tail，所以「跳到那一行」会降级为「跳到会话最新」。细节见 docs/troubleshooting.md §29。

升级流程（社区维护的 升级与回滚 handbook 摘要）：先记录当前坐标并停掉所有写进程 → 备份 profiles/web/{package.json,pnpm-lock.yaml,pnpm-workspace.yaml,cordis.patch.yml}、 $DSH_HOME/cordis.patch.yml 与 session 数据 → 在隔离 home 里试目标版本 → 用上面的自检 + handbook 的门禁清单（干净启动 / 组合图只有已知变化 / session 恢复 / 插件按固定坐标加载 / 关闭时资源释放）→ 通过才提升，失败按备份回滚。

平台与许可

- 仅 macOS。守护进程用 Swift 5.9+ / SwiftPM 编译；仓库内附 universal（Apple Silicon + Intel） 预编译二进制（构建方式见 scripts/build-universal.sh）。
- MIT，见 LICENSE。改动记录见 CHANGELOG.md。