GSD 桌面通知配置指南：让 Auto Mode 无人值守期间的事件可见-育师

人工智能
AI Agent
代码智能体
Agent 编排
CLI
AI 应用

【免费下载链接】gsd-2

A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture

项目地址：https://gitcode.com/gh_mirrors/gs/gsd-2

点击查看免费下载

GSD（Get Shit Done）是一款面向长时自主运行的 meta-prompting 与 spec-driven 开发系统，其 Auto Mode 可以在无人盯守的情况下持续推进 Milestone、Slice 与 Task。本文围绕 GSD 的桌面通知（Notifications）功能展开：如何通过 YAML 配置启用/关闭五类通知事件，如何在 macOS 上正确安装terminal-notifier以保障通知稳定送达，以及在通知不出现时如何系统化排查。读完本文，你将掌握 GSD 通知配置的完整参数语义、跨平台发送原理（macOS / Linux / Windows），并理解通知在预算告警、上下文窗口暂停、里程碑完成等关键节点上的实际触发路径。

通知机制概述：Auto Mode 的"远程仪表盘"

GSD 的 Auto Mode 允许 Agent 长时间自主运行，但用户不可能一直盯着终端。桌面通知正是为此设计：当 Agent 完成单元、遇到错误、触及预算阈值、完成里程碑或需要人工介入时，系统会弹出系统级通知，让你无需盯着屏幕也能掌握进度。

从源码结构看，这一能力由 GSD 扩展的通知助手模块统一提供。其入口函数sendDesktopNotification的设计目标是"非阻塞、非致命"（non-blocking, non-fatal）：即使通知发送失败，也绝不会影响 Auto Mode 主流程的执行。它支持五种通知事件类型，源码中以NotificationKind联合类型定义（notifications.ts）：

export type NotifyLevel = "info" | "success" | "warning" | "error"; export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";

这五个kind与配置项一一对应，构成了通知系统的开关矩阵。

配置参数与完整示例

在 GSD 的项目配置文件中，通知通过notifications块控制。原文档给出的完整配置如下：

notifications: enabled: true on_complete: true # notify on unit completion on_error: true # notify on errors on_budget: true # notify on budget thresholds on_milestone: true # notify when milestone finishes on_attention: true # notify when manual attention needed

各参数语义与源码默认值（types.ts 中NotificationPreferences接口定义）汇总如下：

参数	含义	源码默认值
`enabled`	总开关，设为`false`时所有类别全部静默	`true`
`on_complete`	每个单元（Task/Slice）完成时通知	`true`
`on_error`	运行出错时通知	`true`
`on_budget`	触发预算阈值时通知	`true`
`on_milestone`	里程碑（Milestone）完成时通知	`true`
`on_attention`	需要人工介入（如被阻塞恢复、上下文窗口暂停）时通知	`true`

值得注意的是，各开关的生效逻辑并非简单"非黑即白"。在 notifications.ts 的shouldSendDesktopNotification中，判断顺序是：

若enabled === false，直接返回false，所有类别一律不发送；
否则按kind分别读取对应开关，未显式配置的类别默认视为开启（?? true）。

这意味着你可以只关闭个别不关心的类别，例如在长跑预算类任务时仅保留错误通知：

notifications: enabled: true on_complete: false on_budget: false on_milestone: false

配置的合并逻辑位于 preferences.ts：notifications采用浅合并（shallow merge），base 与 override 逐字段覆盖，因此全局偏好与项目级偏好可以分层组合，未覆盖的字段自动继承。

跨平台支持：macOS / Linux / Windows

虽然原文档聚焦 macOS，但 GSD 的通知实现是跨平台的。从 notifications.ts 的buildDesktopNotificationCommand可以看到按process.platform分发的三条路径：

平台	发送命令	说明
macOS (`darwin`)	优先`terminal-notifier`，缺失时回退`osascript`	声音按级别区分：`error`用`Basso`，其余用`Glass`
Linux	`notify-send`	urgency 按级别映射：`error`→`critical`，`warning`→`normal`，其余 →`low`
Windows (`win32`)	无	直接返回`null`，桌面通知被跳过（不报错、不影响流程）

此外，通知文本在发送前会经过规范化处理：换行符被替换为空格（保证系统通知单行显示），AppleScript 路径还会对反斜杠与双引号做转义，避免脚本注入或语法错误。测试用例也验证了这一点：Linux 下"line 1\nline 2"会被规范化为"line 1 line 2"，且$PATH等字面字符被原样保留（notifications.test.ts）。

macOS 设置详解：为什么推荐 terminal-notifier

GSD 在 macOS 上优先使用terminal-notifier，找不到时才回退到系统自带的osascript。

推荐做法：安装 terminal-notifier

brew install terminal-notifier

为什么？这是原文档与源码注释共同强调的关键点：osascript的通知归属于调用它的终端应用（Ghostty、iTerm2、Terminal.app 等）。如果该终端应用本身没有在"系统设置 → 通知"中获取通知权限，osascript的通知会被系统静默吞掉——而且进程仍以退出码 0 结束，不会有任何报错，排查起来非常隐蔽。源码注释明确记载了这一场景（notifications.ts）。

而terminal-notifier会以独立的 App 身份注册到通知中心，首次使用时系统会弹出权限请求，授予后即可稳定送达，不依赖终端应用的权限状态。

安装后的自测命令（原文档提供）：

terminal-notifier -title "GSD" -message "working!" -sound Glass

执行后若能在屏幕右上角看到通知并听到提示音，说明链路正常。

通知不出现？三步排查法

原文档给出了系统的排查顺序：

检查系统设置：打开"系统设置 → 通知"，确认你的终端应用（或已安装的terminal-notifier）在列表中且允许通知；
安装 terminal-notifier：如上所述，这是最可靠的一步，可绕开终端应用的权限黑洞；
命令行自测：运行terminal-notifier -title "GSD" -message "working!" -sound Glass，确认工具本身可用。

若终端应用未出现在"通知"列表中，可能是它尚未发送过任何通知、未完成注册——让它先主动发送一次通知即可触发注册。更完整的疑难排查可参考 Troubleshooting（其中亦指引回看本文的 Notifications 配置说明）。

源码纵深：通知发送链路与触发节点

sendDesktopNotification的完整链路（notifications.ts）远比"弹一个系统通知"复杂，按优先级依次为：

标题项目化：当调用方传入projectName且默认标题为"GSD"时，标题会被改写为"GSD — <项目名>"（formatNotificationTitle），在多项目并行工作区中一眼区分通知来自哪个项目；
远程通知：sendRemoteNotification独立触发，且不受桌面通知偏好的约束——它处理"未配置"场景时优雅返回，也就是说远程推送与桌面通知是两条并行通道（notifications.ts）；
cmux 通道：若启用了 cmux 集成（cmux.notifications），优先经CmuxClient.notify投递；投递失败则回退到 OSC 777 终端通知（notifications.ts）；
桌面通知：仅当 cmux 未投递成功时，才构造系统命令（terminal-notifier / osascript / notify-send）执行，带 3 秒超时，任何异常都静默吞掉（notifications.ts）。

在 Auto Mode 的调用端，各kind的典型触发节点清晰可查：

milestone（里程碑完成）：在里程碑推进逻辑中，"Milestone <id> complete!"以success级别、milestone类型发送（auto/phases.ts）；
budget（预算阈值）：预算阈值采用数据驱动定义（auto/types.ts），四档阈值依次为100%（error / 强制处理）、90%（warning）、80%（warning）、75%（info）。其中 100% 阈值根据enforcement策略（halt / pause / warn）分别触发"停止 Auto Mode""暂停待用户/gsd auto继续""仅警告继续运行"三种行为，且都会伴随桌面通知（auto/phases.ts）；
attention（人工介入）：包括被阻塞后的恢复提示（blocked resume，warning级别）以及上下文窗口达到context_pause_threshold而自动暂停的场景——"Context <percent>% — paused"（auto/phases.ts）；
complete（单元完成）：例如执行/gsd undo撤销单元后发送"Undone: <unitType> (<unitId>)"（undo.ts）。

测试保障：偏好开关与命令构造均被覆盖

通知模块有专门的单元测试 notifications.test.ts，验证了以下关键行为：

细粒度开关：enabled: true时，on_complete: false关闭完成通知、on_error: true保留错误通知，各 kind 互不干扰（L11-L26）；
总开关：enabled: false时，即使个别类别为true也全部静默（L28-L33）；
macOS 回退：无terminal-notifier时回退osascript，并对Bob's "Milestone"、C:\temp等特殊字符做正确转义（L35-L61）；
声音分级：非 error 级别使用Glass（L63-L71）；
平台边界：win32返回null，不做无谓报错（L88-L90）；
项目标题：formatNotificationTitle对空值、空白、真实项目名的处理，以及 macOS / Linux 命令中均携带"GSD — <项目名>"标题（L94-L134）。

小结与最佳实践

GSD 的桌面通知是 Auto Mode 无人值守体验的关键一环，配置轻量、实现稳健。实践建议：

macOS 用户务必安装terminal-notifier，这是规避终端应用通知权限问题的根本手段；
按工作负载裁剪通知类别：预算敏感的里程碑跑批可只保留on_error与on_attention，减少打扰；
首次接入时用terminal-notifier -title "GSD" -message "working!" -sound Glass自测，再进入真实任务；
若通知仍不出现，按"系统设置 → 安装工具 → 命令行自测"的顺序排查，并留意通知中心对终端应用的注册状态。

整体来看，通知系统将"Agent 自主推进"与"人类保持感知"无缝衔接——你只管离开终端，GSD 会在需要你的时候叫醒你。

人工智能
AI Agent
代码智能体
Agent 编排
CLI
AI 应用

【免费下载链接】gsd-2

A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture

项目地址：https://gitcode.com/gh_mirrors/gs/gsd-2

点击查看免费下载