notifications

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Notifications Skill

## 设计哲学

**Channel 是 transport，notification 是 fact，topic 是 consumer-defined 的事件分类**。三层分离：

1. **持久化独立于 push 出口**：SQLite 表永久保留
2. **跨 chat 可见**：任何 web chat 用 `notification_recent` 都能查所有历史
3. **Topic 由 consumer 定义**：producer 不能自创 topic，只能从订阅过的 topic 里选。channel 通过 `channel_subscribe` 创建/加入 topic
4. **Topic 是全局 first-class entity**：同一字符串 = 同一 topic。无 namespace 前缀（用 `ccxt` 不用 `mail:ccxt`），任何 channel 引用即指同一个

**纯时序日志，不维护 read/unread 状态**。曾经尝试过 read_at + mark_read 工具，但实际用户行为不会触发"明确 ack"。删掉这层状态机后，"我错过了什么"靠 LLM 看 created_at 时间戳自行判断。

## Push 路由模型（关键不变量）

`notification_create` 不传 `push_channels` 时（推荐路径）：

```
有 topic：
  1. 查 channel_subscriptions WHERE topic_name = <topic>  → 拿订阅 channels
  2. 始终 union 一份 'telegram:private'                    → 全量通知出口（unconditional）
  3. fan-out push 到 union 后的列表

无 topic（producer 不知道事件主题归属）：
  → 直接只推 'telegram:private'，跳过订阅查询
```

**topic 是可选的**。Producer 知道事件主题时填写（如 `ccxt` / `etf-premium`），订阅了该 topic 的 channel 被 fan-out；不知道分类时省略——事件作为"无主题路由"事件只进流水账。⚠️ **不要为"杂项/未知"造 magic topic**（如 `misc` / `mail-uncategorized`）——topic 是主题路由 key，不是来源标签。来源信息放 `source` 字段。

**push 出口支持 `web:*` / `telegram:*`**。其中 `web:<session>` 会通过 WebChannel.send 写入对应 web session 的 `web_messages` 并广播到在线 WS 连接；离线时下次打开也能看到。`telegram:*` 走 Telegram notification backend，仅用于通知，不进入 agent 对话。找不到或未初始化的 channel 会 warn 后跳过，不污染 failed 语义。

推送显示前缀由 `source` 决定：`source` 以 `cron:` 开头显示 `[CRON]`，其他来源显示 `[NOTIFICATION]`。前缀只影响 push 文本，不改变 DB 中的 title/body。

## 工具

### notification_create

写入一条通知到 SQLite + 按订阅 fan-out push。

参数：
- `topic` — **可选** consumer-defined 事件分类，如 `ccxt` / `etf-premium` / `credit-card`。不知道主题归属时省略——事件只进流水账。⚠️ 建议先 `topic_list` 看是否已有相似命名
- `severity` — `info` / `alert` / `critical`
- `title` — 一行摘要（≤120 字符，推送时显示这条）
- `body` — 完整 markdown 内容（推送时取前 800 字符 preview）
- `source` — 来源标识，如 `cron:402de9ee` / `mail-daemon` / `manual` / `sub-agent:portfolio-backtest-v2`
- `metadata` — 可选额外 JSON 数据
- `push_channels` — **应急 override**：显式指定推送 channels（绕过订阅 fan-out + 流水账）。正常 pub-sub 路径**不传**

返回 `{ ok, id, pushed: string[], failed: string[] }`。

### notification_recent

查询历史通知，按 `created_at` DESC 排序。参数：`topic` / `severity` / `limit`（默认 10，最大 100）。

### channel_subscribe

当前 channel 订阅某 topic。Topic 不存在时由本工具创建（强烈推荐填 `description`——给 mail daemon LLM 分类作 context）。

参数：
- `topic` — topic 名，建议 lowercase 短串
- `description` — topic 已存在时忽略
- `channel_key` — **必填**。订阅者 channel key，agent 必须显式从 session 起点的 channel 标识中取值

返回 `{ ok, createdTopic: boolean, warning?: string }`。

**Fuzzy match warning**：服务器端做大小写归一化检查。命中类似 topic 时返回 warning（不阻塞），agent 自行决定是否撤回 + 改订已有 topic。

### channel_unsubscribe

退订某 topic。当该 channel 是最后订阅者时 topic 被 application-layer GC，返回 `deleted_orphan_topic=true`。

### channel_subscriptions_list

列出订阅关系。可按 `channel_key` 或 `topic` 过滤；都不传则全列。

### topic_list

列出所有 topic（名称、描述、订阅者数量）。⚠️ `channel_subscribe` 创建新 topic 前应先 call 一下避免重复命名。`filter` 是 substring case-insensitive 模糊匹配。

### topic_get

查看单个 topic 详情：description、订阅者列表、最近 30 天 notification 数量。

## v1 限制

- 无 update / delete notification 工具——通知是不可变事实
- Topic 命名无 hard normalize（存原值）；fuzzy 检查只在 subscribe 时给 warning
- `push_channels` 是应急 override：显式传入时会绕过 topic 订阅 fan-out；如果仍需要全量通知出口，调用方必须把 `telegram:private` 一并放入列表。

## 内部 Ingest API（外部 source 接入点）

MaxClaw 主进程暴露 HTTP endpoint 给外部 producer（launchd daemon / webhook / 其他独立脚本）。**源代码：`src/server/internal-api.ts`**。

**鉴权**：bearer token，复用 `CLAW_WEBHOOK_SECRET`（与 webhook / internal API 同一个 token）。daemon 端从 `secrets/keys.env` 加载，不要发明新 token。

### POST `/api/mail/ingest` — mail daemon 专用

Daemon 投递原始邮件元数据，handler 内部完成：拉 topics → LLM 分类（`palette:light` via taskType `intent`）→ 对每个 matched topic 调一次 `notification_create`；0 match 时调一次无 topic 的 `notification_create` 走流水账。

请求体：
```json
{
  "from":       "string (required)",
  "subject":    "string",
  "preview":    "string (前 1500 字 plain text)",
  "uid":        "string (required, IMAP UID)",
  "message_id": "string (optional, Message-ID header)",
  "date":       "string (optional, Date header)"
}
```

响应：`{ ok, matched: [topic_names], reasoning, notification_ids: [ids] }`。

### POST `/api/notifications/create` — 通用兜底

无 LLM、无分类，参数与 `notification_create` 工具签名一致。给 daemon 在主链路出错时落 alert 用，避免"邮件分类挂了 → 连 alert 都发不出"的死锁。

### 如何接入新 source

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss