# dsh-localnotify — Agent 使用指南

> 面向 AI agent：`notify_add` 工具怎么用、何时用、注意什么。人类用户请看 [README.md](README.md) / [README.en.md](README.en.md)。

## 工具是什么

`notify_add` 向 DSH 本地通知栏新增一条通知：用户侧边栏会出现 🔔【通知】入口与未读徽标，打开通知中心即可看到（页面打开时约 3 秒自动刷新出新内容）。数据落盘在 `~/.dsh/notify/notifications.json`（`DSH_HOME` 环境变量优先），全程本地、无外部服务。

**这是"异步提醒用户"的通道**，不是对话替代品。

## 何时用（适用场景）

- **长时间任务完成**：转换/构建/批量处理结束，把结果路径或数量告诉用户
- **重要进展需跟进**：值得用户回来后处理/知晓的事项
- **需要用户决策**：给出选项与截止信息，用户回到界面时在通知中心看到
- 用户在别处忙、你这边有异步结论时，很适合发一条

**不适用 / 别滥用**：

- 用户就在对话中等待即时答复 —— 直接在对话回复即可，不要发通知
- 不要为每个普通工具调用都发通知（噪音会稀释重要性）
- 涉及密钥、口令等敏感信息 —— 通知以明文 JSON 存储并展示在通知栏，不要写入

## 怎么调用

```jsonc
// 完成任务后的汇报式通知
notify_add({
  "title": "文档转换完成",
  "body": "23 页扫描件已转为 Markdown，输出于 ./md/contract.md",
  "level": "success"
})
// → { ok: true, id: "n_...", title, level, createdAt, storagePath }

// 出错/失败时
notify_add({ "title": "部署失败：网关超时", "body": "详见日志 xxx", "level": "error" })

// 需要用户决策时
notify_add({ "title": "需要确认：插件安装方式", "body": "选项：A) GitHub 发布后安装 B) 本地目录安装，请选择" })
```

- `title`：必填，≤200 字；**简洁概括，建议 ≤60 字**（通知栏单行展示标题）
- `body`：可选，≤5000 字；放用户需要知道的要点（路径/数量/后续动作/待办选项）
- `level`：可选枚举 `info | success | warn | error`，默认 `info`，用于通知中心**视觉分级**：
  - `success`：任务/操作成功完成
  - `error`：任务失败、出错，需要用户处理
  - `warn`：有风险/需要注意但不一定失败（如重试成功、降级完成、临近截止）
  - `info`：普通信息（默认；普通汇报可不传）
- 失败返回 `{ ok: false, error }`；超长等参数问题会直接报错，修正后重试

## 写作约定

- 标题用**一句话说清结果**（动词开头）：如"备份任务已完成""代码审查已通过"
- 正文写**用户行动所需信息**：产物路径、数量、出错摘要、下一步选项；需要决策时把选项列清楚
- 少而精：只有值得用户停下手里事情看一眼的结论才发；同一任务不要连环刷多条（可合并成一条带关键进展）

## 与其他写入方的关系（了解即可）

- 同一存储还有 **CLI**（`dsh-localnotify add`）与**文件直写**两条路径，三者读写同一 JSON
- 单条上限 500，超出自动裁剪最旧；若用户设置了保留天数（CLI `config --retain-days`），超期通知会被自动清理
- 页面 UI 语言跟随 dsh web（zh/en）自动切换，与通知内容语言无关——通知正文按用户使用的语言写即可