@yoooclaw/phone-notifications 1.4.16

package/README.md

@@ -0,0 +1,344 @@
+# @openclaw/phone-notifications
+
+OpenClaw 手机通知同步插件：接收手机通知并写入本地 JSON 文件系统，供 Agent 查询和消费。
+
+## 工作方式
+
+插件支持两种接入模式：
+
+1. Gateway Native（默认）
+- 手机端通过 gateway 已有连接调用 `notifications.push`
+- 插件通过 `registerGatewayMethod` 接收 `params.items`
+
+2. HTTP 备选模式
+- 开启 `httpEnabled=true` 后，注册 `POST /notifications`
+- 通过 `Authorization: Bearer <apiKey>` 鉴权
+
+## 存储设计
+
+通知按以下目录结构写入（JSON）：
+
+```text
+<workspace>/notifications/
+├── 2026-03-02.json
+├── 2026-03-03.json
+└── 2026-03-04.json
+```
+
+补充规则：
+- `workspaceDir` 可用时，根目录是 `<workspace>/notifications`
+- `workspaceDir` 不可用或不可写时，回退到 `<stateDir>/plugins/phone-notifications/notifications`
+- 通知写入 `YYYY-MM-DD.json` 的 JSON 数组（append-only）
+- 通知条目字段为 `appName`、`title`、`content`、`timestamp`（ISO 8601 含时区）
+- 同一天内按 `notification-id` 去重（使用内部索引文件）
+- `retentionDays`（默认 30）会清理过期日期文件
+
+## 前置要求
+
+- **Node.js >= 22.12.0**（含 npm）
+- **curl**（用于下载安装包）
+- **tar**
+
+## 安装
+
+推荐使用一键安装脚本，脚本会自动从 CDN 获取最新版本、下载、解压、注册插件并写入配置。
+
+### 最简安装（自动获取最新版本）
+
+```bash
+curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash
+```
+
+### 指定版本安装
+
+```bash
+curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash -s -- --version 1.2.3
+```
+
+### 带 Token 安装
+
+安装时同时写入灯控鉴权 Token（写入 `~/.openclaw/credentials.json`）：
+
+```bash
+curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash -s -- --token eyJhbGciOi...
+```
+
+### 使用本地包安装
+
+如果已有 `.tgz` 文件，可跳过下载直接安装：
+
+```bash
+bash install.sh --tgz-url ./yoooclaw-phone-notifications-1.2.3.tgz
+```
+
+### 全部安装选项
+
+| 选项 | 说明 | 默认值 |
+|---|---|---|
+| `--version <ver>` | 指定版本号 | 自动获取最新版本 |
+| `--tgz-url <url\|path>` | 直接指定插件包地址（跳过版本检测） | - |
+| `--target-dir <path>` | 安装目录 | `~/.openclaw/extensions/phone-notifications` |
+| `--token <token>` | 灯控鉴权 Token | - |
+| `--retention-days <n>` | 通知数据保留天数 | 30 |
+
+### 安装脚本做了什么
+
+1. 从 CDN 下载最新版本的插件 tgz 包（或使用你指定的版本/地址）
+2. 解压并验证包完整性（检查 `package.json`、入口文件可加载）
+3. 备份旧版本（如有），原子替换到 `~/.openclaw/extensions/phone-notifications`
+4. 写入 `~/.openclaw/openclaw.json` 配置：
+   - `plugins.allow` — 将插件加入白名单
+   - `plugins.entries` — 启用插件，合并用户配置
+   - `plugins.installs` — 记录安装来源和版本
+   - 清理该插件旧的 `plugins.load.paths` / 旧安装记录，避免继续命中之前通过 `openclaw plugins install` 或 `--link` 保留的副本
+5. 如传入 `--token`，写入 `~/.openclaw/credentials.json`
+6. 安装失败时自动回滚到旧版本
+
+### 升级
+
+升级方式与安装相同，重新运行安装脚本即可。脚本会自动备份旧版本并替换。
+
+```bash
+curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash
+```
+
+### 验证安装
+
+```bash
+openclaw ntf --help
+```
+
+```bash
+openclaw ntf --version
+```
+
+如果环境里已有其他插件占用了 `ntf`，可改用不冲突的别名：
+
+```bash
+openclaw phone-notifications --help
+```
+
+```bash
+openclaw phone-notifications -v
+```
+
+## 配置
+
+安装脚本会自动写入必要的插件注册配置。如需手动调整：
+
+```bash
+# 可选：数据保留天数（默认 30）
+openclaw config set plugins.entries.phone-notifications.config.retentionDays 30
+
+# 可选：忽略特定 app
+openclaw config set plugins.entries.phone-notifications.config.ignoredApps '["com.android.systemui"]'
+```
+
+配置项说明：
+- `retentionDays?: number`（默认 30）
+- `ignoredApps?: string[]`
+
+## 数据协议
+
+### Gateway Native：`notifications.push`
+
+```json
+{
+  "type": "req",
+  "id": "n_abc",
+  "method": "notifications.push",
+  "params": {
+    "items": [
+      {
+        "id": "n_001",
+        "app": "WeChat",
+        "title": "张三",
+        "body": "在吗？",
+        "timestamp": "2026-03-02T08:30:00+08:00",
+        "category": "message",
+        "metadata": { "chatId": "c1" }
+      }
+    ]
+  }
+}
+```
+
+说明：
+- `id` 用于同一天内去重（写入 `.ids` 索引），不会作为通知正文字段落盘。
+- `app` 是手机端上报字段；插件落盘时会标准化为 `appName`。
+
+### HTTP 备选：`POST /notifications`
+
+```http
+POST /notifications
+Authorization: Bearer ntf-xxxxxxxxxxxx
+Content-Type: application/json
+```
+
+```json
+{
+  "notifications": [
+    {
+      "id": "n_001",
+      "app": "SMS",
+      "title": "京东快递",
+      "body": "包裹已发出",
+      "timestamp": "2026-03-02T08:30:00+08:00"
+    }
+  ]
+}
+```
+
+响应示例：
+
+```json
+{ "ok": true, "ingested": 1 }
+```
+
+## CLI 命令
+
+插件注册了 `openclaw ntf` 命令组，并提供 `openclaw phone-notifications` 作为无冲突别名，供 Agent 直接消费。所有命令输出 JSON。
+
+### 认证管理
+
+```bash
+# 设置用户 Token（灯效下发等接口需要）
+openclaw ntf auth set-token "eyJhbGciOi..."
+
+# 查看当前认证状态
+openclaw ntf auth show
+
+# 清除认证信息
+openclaw ntf auth clear
+```
+
+### 通知查询
+
+```bash
+# 查询最近 7 天通知
+openclaw ntf search
+
+# 查询指定应用的通知
+openclaw ntf search --app wechat --from 2026-03-01 --to 2026-03-09
+
+# 按关键词搜索
+openclaw ntf search --keyword "开会" --limit 20
+
+# 按发送人过滤
+openclaw ntf search --sender "张三" --from 2026-03-01
+```
+
+### 通知统计
+
+```bash
+# 全维度统计
+openclaw ntf stats
+
+# 按应用维度统计
+openclaw ntf stats --dim app --from 2026-03-01
+
+# 按时段维度统计
+openclaw ntf stats --dim hour --from 2026-03-01 --to 2026-03-09
+```
+
+### 通知同步（记忆系统）
+
+```bash
+# 扫描未同步通知
+openclaw ntf sync scan
+
+# 获取指定日期未处理通知
+openclaw ntf sync fetch --date 2026-03-09
+
+# 标记同步完成
+openclaw ntf sync commit --date 2026-03-09
+```
+
+### 通知监控任务
+
+```bash
+# 创建监控任务
+openclaw ntf monitor create boss-alert \
+  --description "监控老板微信消息" \
+  --match-rules '{"appName":"wechat","senderKeywords":["张总"]}' \
+  --schedule "*/30 * * * *"
+
+# 列出监控任务
+openclaw ntf monitor list
+
+# 查看监控任务详情
+openclaw ntf monitor show boss-alert
+
+# 启用/暂停监控任务
+openclaw ntf monitor enable boss-alert
+openclaw ntf monitor disable boss-alert
+
+# 删除监控任务
+openclaw ntf monitor delete boss-alert --yes
+```
+
+### 灯效控制
+
+```bash
+# 直接发送灯效指令到硬件设备（需要先 set-token）
+openclaw ntf light send \
+  --segments '[{"mode":"wave","duration_s":4,"brightness":192,"color":{"r":255,"g":0,"b":0}}]'
+
+# 呼吸灯效
+openclaw ntf light send \
+  --segments '[{"mode":"breath","duration_s":6,"brightness":128,"color":{"r":0,"g":255,"b":0}}]'
+```
+
+### 灯效规则管理
+
+```bash
+# 添加灯效规则
+openclaw ntf light rules add "老板消息提醒" \
+  --trigger "收到老板的微信消息" \
+  --segments '[{"mode":"wave","duration_s":4,"brightness":192,"color":{"r":255,"g":0,"b":0}}]'
+
+# 列出灯效规则
+openclaw ntf light rules list
+
+# 查看灯效规则详情
+openclaw ntf light rules show "老板消息提醒"
+
+# 校验灯效参数（不写入）
+openclaw ntf light rules validate \
+  --segments '[{"mode":"breath","duration_s":6,"brightness":128,"color":{"r":0,"g":255,"b":0}}]'
+
+# 移除灯效规则
+openclaw ntf light rules remove "老板消息提醒" --yes
+```
+
+## 开发
+
+```bash
+pnpm install
+pnpm run build    # tsc 编译
+pnpm test         # vitest 测试
+```
+
+## 目录结构
+
+```text
+src/
+├── types.ts            # 类型定义
+├── index.ts            # 插件入口：service + gateway method + http route + tool + cli
+├── storage.ts          # 文件系统 JSON 存储引擎
+├── light-protocol.ts   # 灯效 ANCS 协议编码
+└── cli/
+    ├── index.ts        # CLI 注册汇总入口
+    ├── helpers.ts      # 共享工具（路径解析、日期处理、JSON 输出）
+    ├── auth.ts         # openclaw ntf auth
+    ├── ntf-search.ts   # openclaw ntf search
+    ├── ntf-stats.ts    # openclaw ntf stats
+    ├── ntf-sync.ts     # openclaw ntf sync
+    ├── ntf-monitor.ts  # openclaw ntf monitor
+    ├── light-rules.ts  # openclaw ntf light rules
+    └── light-send.ts   # openclaw ntf light send
+```
+
+## License
+
+GPL-3.0

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+interface PluginApi {
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+    pluginConfig?: Record<string, unknown>;
+    runtime: {
+        state: {
+            resolveStateDir: () => string;
+        };
+    };
+    registerService: (service: {
+        id: string;
+        start: (ctx: {
+            stateDir: string;
+            workspaceDir?: string;
+        }) => void | Promise<void>;
+        stop?: () => void | Promise<void>;
+    }) => void;
+    registerGatewayMethod: (method: string, handler: (opts: {
+        params: Record<string, unknown>;
+        /** 发起本次请求的 WSS 客户端（operator 节点为 null） */
+        client: {
+            connId?: string;
+        } | null;
+        context: {
+            /** 向所有已连接的 operator 客户端广播 event 帧 */
+            broadcast: (event: string, payload: unknown) => void;
+            /** 向指定 connId 集合广播 event 帧 */
+            broadcastToConnIds: (event: string, payload: unknown, connIds: ReadonlySet<string>) => void;
+        };
+        respond: (ok: boolean, payload?: unknown, error?: {
+            code: string;
+            message: string;
+        }) => void;
+    }) => void | Promise<void>) => void;
+    /** 注册供 AI Agent 调用的 tool，声明即实现 */
+    registerTool: (tool: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        execute: (toolCallId: string, params: unknown) => unknown | Promise<unknown>;
+    }) => void;
+    registerHttpRoute: (params: {
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+        auth?: "gateway" | "plugin";
+    }) => void;
+    registerCli: (registrar: (ctx: {
+        program: any;
+        stateDir?: string;
+        workspaceDir?: string;
+        logger: PluginApi["logger"];
+    }) => void | Promise<void>, opts?: {
+        commands?: string[];
+    }) => void;
+}
+declare const _default: {
+    id: string;
+    name: string;
+    register(api: PluginApi): void;
+};
+
+export { _default as default };