前言¶
DeepSeek Harness（DSH）采用插件化架构，智能体在后台执行任务时，开发者容易忽略任务进度或异常。zzx-dear/dsh-capybara-notify 插件通过桌面通知中心解决这一问题。它将告警、会话状态和插件推荐集成在一个名为「水豚秘书」的系统中，通过桌面宠物「噜噜」提供可视化的交互反馈。插件本身零配额，所有 API 调用消耗的是 DSH 本身的额度。
核心功能¶
该插件提供以下能力：
- 告警 API：提供
POST /api/secretary/notify接口，任何脚本或任务看板都可以向宠物投递告警，触发气泡提示和提示音。 - 收件箱：告警数据持久化存储在
$DSH_HOME/secretary/inbox.jsonl，可通过/queue接口读取最近 50 条历史记录。 - 会话智能提醒：监听 DSH 会话事件，根据状态弹出提示。任务回合完成显示「任务完成」；等待确认显示「需要你确认：理由」；回合被阻塞显示「等待继续」。
- 桌面宠物：macOS 下提供透明置顶的小窗，支持点击穿透、拖拽定位、位置记忆和开机自启托管。
- 巡检脚本：内置磁盘、HTTP 和进程存活巡检的模板脚本，超阈值时自动通知。
- 每日插件推荐：从社区市场筛选高口碑插件，每天推送 3 款未安装的推荐。
安装与启用¶
- 安装插件本体：使用官方命令添加插件。安装后需要重启 DSH Web 服务（
dsh web）。
dsh plugin --profile <你的profile> add "github:zzx-dear/dsh-capybara-notify"
- 测试功能：使用提供的测试脚本验证宠物是否能正常响应。
bash /path/to/dsh-capybara-notify/checks/notify.sh -t "测试" -b "噜噜在听" -l info
桌面宠物（macOS）¶
桌面宠物功能仅在 macOS 上可用（基于 pywebview/WebKit 透明置顶窗）。Linux 和 Windows 用户仍可使用插件 API，但需配合其他 dsh-pet 兼容前端。
- 安装宠物：运行安装脚本，脚本会创建虚拟环境并注册 launchd 服务（开机自启 + 崩溃自愈）。
bash /path/to/dsh-capybara-notify/pet/install_pet.sh
- 隐藏网页内置宠物：如果网页 GUI 中也显示宠物，可通过 API 隐藏网页端的宠物，只保留桌面端。
curl -X POST http://127.0.0.1:3080/api/pet/set-visible -H 'content-type: application/json' -d '{"visible": false}'
- 自定义宠物形象：宠物素材来自 Codex Pet 生态。将图集和
pet.json放入~/.codex/pets/<id>/，并设置环境变量LULU_PET_ID=<id>。
每日插件推荐（macOS）¶
如果需要自动获取每日插件推荐，可以设置 launchd 定时任务。
- 创建 plist 文件：创建配置文件，设置每天 09:00 执行推荐检查。
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.lulu.plugin-check.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.lulu.plugin-check</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>$(pwd)/checks/check_plugins.sh</string>
</array>
<key>StartCalendarInterval</key>
<dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>
<key>StandardOutPath</key><string>/tmp/lulu-plugin-check.out.log</string>
<key>StandardErrorPath</key><string>/tmp/lulu-plugin-check.err.log</string>
</dict>
</plist>
EOF
- 启动服务：加载配置。
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lulu.plugin-check.plist
API 使用¶
插件提供 REST API 供外部脚本调用。
- 投递告警：
POST /api/secretary/notify
{ "title": "磁盘告警", "body": "根分区已用 92%", "level": "info" }
*限制：标题 ≤ 60 字，正文 ≤ 500 字。气泡显示仅支持标题 ≤ 22 字、正文 ≤ 22 字。*
-
读取收件箱：
GET /api/secretary/queue
返回最近 50 条告警列表。 -
健康检查：
GET /api/secretary/health
返回服务状态和收件箱路径。
巡检脚本示例¶
使用插件自带的巡检脚本模板。
# 投递一条告警
bash /path/to/dsh-capybara-notify/checks/notify.sh -t "标题" -b "正文" -l info
# 支持 stdin 输入正文
echo "hi" | bash /path/to/dsh-capybara-notify/checks/notify.sh -t "来自管道"
# HTTP 站点巡检（不可达才通知）
bash /path/to/dsh-capybara-notify/checks/check_http.sh https://example.com
# 磁盘巡检（超过阈值才通知）
bash /path/to/dsh-capybara-notify/checks/check_disk.sh 90
# 进程巡检（进程不存在才通知）
bash /path/to/dsh-capybara-notify/checks/check_process.sh dsh
会话智能提醒¶
该功能基于 DSH 的会话事件自动触发。
- 任务完成：回合结束时弹出「任务完成」，级别为 info。
- 需要确认：沙箱升级或批准等需要用户介入时，弹出「需要你确认：理由」，级别为 warning。
- 等待继续：回合被阻塞等待输入时，弹出「等待继续」，级别为 warning。
注意：子代理的回合不会触发提醒，只响主会话。关闭提醒可通过环境变量SECRETARY_SESSION_ALERTS=0实现。
任务看板联动¶
在任务看板（如 dsh-task-board）中，可以直接调用巡检脚本。如果脚本检测到异常，会自动向宠物投递告警，无需人工干预。
环境变量¶
| 变量名 | 默认值 | 说明 |
|---|---|---|
SECRETARY_SESSION_ALERTS |
开 | 设为 0 关闭会话智能提醒 |
SECRETARY_PET_FIBERS |
pet |
宠物服务的 fiber 名 |
SECRETARY_API |
http://127.0.0.1:3080/api/secretary/notify |
notify.sh 的投递地址 |
DSH_WEB_URL |
http://127.0.0.1:3080 |
桌面宠物的反代地址 |
LULU_SCALE |
0.40 |
宠物缩放比例 |
LULU_PET_ID |
capybara-ruru |
宠物 ID |
LULU_X / LULU_Y |
右下角 | 初始位置 |
已知限制¶
- 平台限制：桌面宠物仅支持 macOS（pywebview/WebKit 透明置顶窗）。Linux 和 Windows 可使用插件 API，但需要自行集成前端。
- 依赖浏览器：任务看板 cron 需要浏览器标签页处于打开状态，否则任务会被跳过。
- API 额度消耗：每次触发巡检脚本或每日推荐任务都会消耗 API 额度，插件本身不占用额外配额。
总结¶
zzx-dear/dsh-capybara-notify 是一个实用的 DSH 插件，它通过桌面通知和宠物形象，解决了智能体后台运行时的信息反馈问题。适合需要频繁监控任务状态、进行巡检或希望获得每日推荐的开发者。安装前请确认源码与许可证符合需求。
