@yoooclaw/phone-notifications 1.6.1 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @yoooclaw/phone-notifications
 
-OpenClaw 手机通知同步插件：接收手机通知并写入本地 JSON 文件系统，供 Agent 查询和消费。
+OpenClaw / QClaw 手机通知同步插件：接收手机通知并写入本地 JSON 文件系统，供 Agent 查询和消费。
 
 ## 工作方式
 
@@ -36,11 +36,18 @@ OpenClaw 手机通知同步插件：接收手机通知并写入本地 JSON 文
 ## 前置要求
 
 - **Node.js >= 22.12.0**
-- **OpenClaw >= 2026.0.0**
+- **OpenClaw >= 2026.0.0**，或兼容其插件 ABI 的 QClaw 宿主
+
+## 宿主兼容性
+
+- **OpenClaw**：可直接使用全局 `openclaw` CLI 安装、更新、验证和执行插件命令。
+- **QClaw**：插件 ABI 与 OpenClaw 兼容，但宿主目录、配置入口和 CLI 管理方式不同。QClaw 桌面应用通常不提供全局 `openclaw` 命令，而是由应用内置 wrapper 调用 OpenClaw runtime。
+- 一键安装脚本会自动探测宿主状态目录，优先读取 `~/.qclaw/qclaw.json`；如果你的变体产品使用 `~/.qclow/qclaw.json`，脚本和插件也会兼容。
+- QClaw 下**不支持**本脚本自动执行 `gateway restart` / Tailscale 配置。安装完成后如插件未自动生效，请重启 QClaw 桌面应用。
 
 ## 安装
 
-### 通过 OpenClaw 安装（推荐）
+### 通过 OpenClaw CLI 安装（OpenClaw）
 
 ```bash
 openclaw plugin install @yoooclaw/phone-notifications
@@ -52,14 +59,20 @@ openclaw plugin install @yoooclaw/phone-notifications
 openclaw plugin update @yoooclaw/phone-notifications
 ```
 
-### 通过一键脚本安装（备选）
+### 通过一键脚本安装（推荐给 QClaw，备选给 OpenClaw）
 
-适用于无法使用 npm 源的环境，脚本从 CDN 获取插件包并自动注册。
+适用于无法使用 npm 源的环境，或宿主不是标准 OpenClaw CLI 的场景。脚本从 CDN 获取插件包并自动注册。
 
 ```bash
 curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash
 ```
 
+脚本会自动探测宿主：
+
+- OpenClaw：默认使用 `~/.openclaw`
+- QClaw：优先读取 `~/.qclaw/qclaw.json`
+- 兼容变体：如存在 `~/.qclow/qclaw.json` 也会识别
+
 <details>
 <summary>脚本安装选项</summary>
 
@@ -69,12 +82,12 @@ curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash
 curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash -s -- --version 1.2.3
 ```
 
-#### 带 Token 安装
+#### 带 API Key 安装
 
-安装时同时写入灯控鉴权 Token（写入 `~/.openclaw/credentials.json`）：
+安装时同时写入灯控鉴权 API Key（写入 `<stateDir>/credentials.json`）：
 
 ```bash
-curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash -s -- --token eyJhbGciOi...
+curl -fsSL https://cdn.yoootek.com/openclaw-plugin/install.sh | bash -s -- --api-key ock_xxx
 ```
 
 #### 使用本地包安装
@@ -89,27 +102,37 @@ 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 | - |
+| `--target-dir <path>` | 安装目录 | `<stateDir>/extensions/phone-notifications` |
+| `--state-dir <path>` | 宿主状态目录 | 自动探测 |
+| `--config-path <path>` | 宿主配置文件路径 | `<stateDir>/openclaw.json` |
+| `--host-cli <cmd>` | 宿主 CLI 命令名 | `openclaw` |
+| `--api-key <apiKey>` | 灯控鉴权 API Key | - |
+| `--token <token>` | 兼容旧参数，等价于 `--api-key` | - |
 | `--retention-days <n>` | 通知数据保留天数 | 30 |
 
 #### 脚本做了什么
 
 1. 从 CDN 下载最新版本的插件 tgz 包（或使用你指定的版本/地址）
 2. 解压并验证包完整性（检查 `package.json`、入口文件可加载）
-3. 备份旧版本（如有），原子替换到 `~/.openclaw/extensions/phone-notifications`
-4. 写入 `~/.openclaw/openclaw.json` 配置：
+3. 自动探测宿主状态目录和配置文件路径
+4. 备份旧版本（如有），原子替换到 `<stateDir>/extensions/phone-notifications`
+5. 写入 `<configPath>` 配置：
    - `plugins.allow` — 将插件加入白名单
    - `plugins.entries` — 启用插件，合并用户配置
    - `plugins.installs` — 记录安装来源和版本
    - 清理该插件旧的 `plugins.load.paths` / 旧安装记录，避免继续命中之前通过 `openclaw plugins install` 或 `--link` 保留的副本
-5. 如传入 `--token`，写入 `~/.openclaw/credentials.json`
-6. 安装失败时自动回滚到旧版本
+6. 如传入 `--api-key` / `--token`，写入 `<stateDir>/credentials.json`
+7. OpenClaw 下尝试执行 `gateway restart`；QClaw 下不会主动重启宿主进程
+8. 安装失败时自动回滚到旧版本
 
 </details>
 
 ### 验证安装
 
+#### OpenClaw
+
+以下命令适用于带全局 `openclaw` CLI 的标准 OpenClaw 宿主：
+
 ```bash
 openclaw ntf --help
 ```
@@ -128,8 +151,16 @@ openclaw phone-notifications --help
 openclaw phone-notifications -v
 ```
 
+#### QClaw
+
+- QClaw 通常**没有**全局 `openclaw` 命令。
+- 插件安装完成后，如未自动生效，请先重启 QClaw 桌面应用。
+- 如需执行 OpenClaw CLI 子命令，请使用 QClaw 自带的 wrapper；命令语义与本文档中的 `openclaw ...` 子命令保持一致，但入口由 QClaw 提供。
+
 ## 配置
 
+以下命令以 OpenClaw 为例。QClaw 下请通过其自带 wrapper 执行同样的 OpenClaw 子命令。
+
 安装脚本会自动写入必要的插件注册配置。如需手动调整：
 
 ```bash
@@ -203,13 +234,15 @@ Content-Type: application/json
 
 ## CLI 命令
 
+以下示例均以 OpenClaw 全局 CLI 为例。QClaw 下请将 `openclaw` 替换为 QClaw 提供的 OpenClaw wrapper。
+
 插件注册了 `openclaw ntf` 命令组，并提供 `openclaw phone-notifications` 作为无冲突别名，供 Agent 直接消费。所有命令输出 JSON。
 
 ### 认证管理
 
 ```bash
-# 设置用户 Token（灯效下发等接口需要）
-openclaw ntf auth set-token "eyJhbGciOi..."
+# 设置用户 API Key（灯效下发等接口需要）
+openclaw ntf auth set-api-key "ock_xxx"
 
 # 查看当前认证状态
 openclaw ntf auth show
@@ -218,6 +251,8 @@ openclaw ntf auth show
 openclaw ntf auth clear
 ```
 
+兼容旧命令：`openclaw ntf auth set-token <token>`，效果等同于 `set-api-key`。
+
 ### 通知查询
 
 ```bash
@@ -286,7 +321,7 @@ openclaw ntf monitor delete boss-alert --yes
 ### 灯效控制
 
 ```bash
-# 直接发送灯效指令到硬件设备（需要先 set-token）
+# 直接发送灯效指令到硬件设备（需要先 set-api-key）
 openclaw ntf light send \
   --segments '[{"mode":"wave","duration_s":4,"brightness":192,"color":{"r":255,"g":0,"b":0}}]'
 
@@ -336,13 +371,13 @@ src/
 └── 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
+    ├── auth.ts         # auth 子命令
+    ├── ntf-search.ts   # search 子命令
+    ├── ntf-stats.ts    # stats 子命令
+    ├── ntf-sync.ts     # sync 子命令
+    ├── ntf-monitor.ts  # monitor 子命令
+    ├── light-rules.ts  # light rules 子命令
+    └── light-send.ts   # light send 子命令
 ```
 
 ## License