@2en/clawly-plugins 1.7.0 → 1.7.1

package/channel.ts

@@ -2,9 +2,10 @@
  * Clawly cron delivery channel — registers a minimal channel plugin so that
  * cron jobs using `delivery: { channel: "clawly-cron" }` have a valid target.
  *
- * When a cron job delivers text, the channel injects it into the main session
- * transcript via chat.inject (no LLM round-trip) and sends a push notification
- * if the mobile client is offline.
+ * When a cron job delivers text, the channel routes it through the agent via
+ * `openclaw agent --message` (LLM round-trip) so the response appears as a
+ * natural assistant message, then sends a push notification if the mobile
+ * client is offline.
  */
 
 import {$} from 'zx'
@@ -14,17 +15,13 @@ import {isClientOnline} from './gateway/presence'
 
 $.verbose = false
 
-async function injectAndNotify(text: string, api: PluginApi): Promise<void> {
+async function deliverAndNotify(text: string, api: PluginApi): Promise<void> {
   try {
-    // Resolve main session key from config
     const config = api.pluginConfig as Record<string, unknown> | undefined
     const agentId = typeof config?.agentId === 'string' ? config.agentId : 'clawly'
-    const mainKey = typeof config?.mainKey === 'string' ? config.mainKey : 'main'
-    const sessionKey = `agent:${agentId}:${mainKey}`
 
-    const params = JSON.stringify({sessionKey, message: text})
-    await $`openclaw gateway call chat.inject --json --params ${params}`
-    api.logger.info(`clawly-cron: injected message (${text.length} chars) into ${sessionKey}`)
+    await $`openclaw agent --agent ${agentId} --message ${text}`
+    api.logger.info(`clawly-cron: delivered message (${text.length} chars) to agent ${agentId}`)
 
     // Push notification if client is offline
     const online = await isClientOnline()
@@ -34,7 +31,7 @@ async function injectAndNotify(text: string, api: PluginApi): Promise<void> {
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    api.logger.error(`clawly-cron: failed to inject message — ${msg}`)
+    api.logger.error(`clawly-cron: failed to deliver message — ${msg}`)
   }
 }
 
@@ -77,7 +74,7 @@ export function registerClawlyCronChannel(api: PluginApi) {
           api.logger.info(`clawly-cron sendText: text=${text.length} chars`)
           if (text) {
             // Fire-and-forget — delivery system may not await sendText
-            injectAndNotify(text, api).catch(() => {})
+            deliverAndNotify(text, api).catch(() => {})
           }
           return {channel: 'clawly-cron', messageId: crypto.randomUUID()}
         },

package/gateway/plugin-version-management.md

@@ -0,0 +1,190 @@
+# 插件版本管理
+
+## 产品需求
+
+### 背景
+
+OpenClaw 插件以 npm 包形式安装在 gateway 的 `extensions/` 目录下。用户需要一种方式来查询已安装插件的版本、检测是否有更新、并执行更新操作——无需手动 SSH 到服务器执行 CLI 命令。
+
+### 目标
+
+- 通过 Gateway RPC 远程查询任意插件的已安装版本和 npm 最新版本
+- 支持多种更新策略（常规更新、全新安装、强制重装）
+- 更新后可选自动重启 gateway，使新版本立即生效
+
+### 功能需求
+
+1. **版本查询** — 给定 `pluginId` 和 `npmPkgName`，返回已安装版本、npm 最新版本、所有可用版本列表，以及是否有更新。
+2. **插件更新** — 给定 `pluginId`、`npmPkgName` 和更新策略，执行安装或更新操作。支持指定目标版本和更新后自动重启。
+3. **强制重装** — `force` 策略会备份插件配置、删除扩展目录、全新安装、再恢复配置，解决损坏安装或缓存问题。
+
+### 约束
+
+- 仅通过 Gateway WebSocket RPC 调用，不暴露 HTTP 端点。
+- 版本比较仅支持标准 semver，预发布版本（如 `1.0.0-beta.1`）不会被标记为可用更新。
+- npm registry 查询结果缓存 5 分钟（LRU，最多 5 个包），避免频繁请求。
+
+---
+
+## 技术设计
+
+### 概览
+
+插件版本管理通过 `gateway/plugins.ts` 注册两个 Gateway RPC 方法，分别负责版本查询和更新执行。
+
+### 数据流
+
+```
+Mobile / Agent
+  │
+  ├─ clawly.plugins.version({ pluginId, npmPkgName })
+  │    ├─ 读取 extensions/<pluginId>/package.json → 已安装版本
+  │    ├─ npm view <npmPkgName> --json → 最新版本 + 所有版本
+  │    └─ isUpdateAvailable(current, latest) → 是否有更新
+  │
+  └─ clawly.plugins.update({ pluginId, npmPkgName, strategy, targetVersion?, restart? })
+       ├─ strategy=install  → openclaw plugins install <pkg>
+       ├─ strategy=update   → openclaw plugins update <pluginId>
+       └─ strategy=force    → 备份配置 → 删除目录 → 安装 → 恢复配置
+            └─ restart=true  → openclaw gateway restart
+```
+
+### Gateway RPC 方法
+
+| 方法 | 参数 | 返回 |
+|---|---|---|
+| `clawly.plugins.version` | `{ pluginId, npmPkgName }` | `VersionResult` |
+| `clawly.plugins.update` | `{ pluginId, npmPkgName, strategy, targetVersion?, restart? }` | `UpdateResult` |
+
+### 关键类型
+
+```typescript
+// clawly.plugins.version 返回
+interface VersionResult {
+  pluginVersion: string | null     // 已安装版本（来自 package.json）
+  npmPackageVersion: string | null // 同上（兼容字段）
+  latestNpmVersion: string | null  // npm registry 最新稳定版
+  allNpmVersions: string[]         // npm registry 所有已发布版本
+  updateAvailable: boolean         // 是否有可用更新
+  error?: string                   // 查询错误（如 npm 不可达）
+}
+
+// clawly.plugins.update 返回
+interface UpdateResult {
+  ok: boolean        // 操作是否成功
+  strategy: string   // 实际使用的策略
+  output?: string    // CLI 输出
+  restarted?: boolean // 是否已重启 gateway
+  error?: string     // 失败时的错误信息
+}
+```
+
+### 更新策略
+
+| 策略 | 行为 | 适用场景 |
+|---|---|---|
+| `install` | `openclaw plugins install <pkg>[@version]` | 首次安装或指定版本安装 |
+| `update` | `openclaw plugins update <pluginId>` | 常规更新到最新版 |
+| `force` | 备份配置 → 删除扩展目录 → 全新安装 → 恢复配置 | 安装损坏、缓存问题、降级 |
+
+### `force` 策略详细流程
+
+1. 读取 `openclaw.json` 中 `plugins.entries.<pluginId>` 的用户配置并保存
+2. 从 `openclaw.json` 删除该插件条目（确保干净安装）
+3. 删除 `extensions/<pluginId>/` 目录
+4. 执行 `openclaw plugins install <pkg>[@version]`
+5. 将保存的用户配置合并回 `openclaw.json`
+
+### 版本检测逻辑
+
+已安装版本从 `<stateDir>/extensions/<pluginId>/package.json` 读取。npm 最新版本通过 `npm view <pkg> --json` 获取。版本比较使用内置 `isUpdateAvailable(current, latest)`：
+
+- 仅比较标准 semver（`major.minor.patch`）
+- `latest` 为预发布版本时返回 `false`（不推荐更新到预发布版）
+- `latest > current` 时返回 `true`
+
+### 缓存
+
+npm registry 查询结果通过 `LruCache` 缓存：
+
+- **容量**: 5 个包
+- **TTL**: 5 分钟
+- 更新操作成功后自动失效对应包的缓存
+
+### 状态目录解析
+
+`stateDir` 按以下优先级解析：
+
+1. `api.runtime.state.resolveStateDir(process.env)`（插件 API 提供）
+2. `OPENCLAW_STATE_DIR` 环境变量
+3. 空字符串（回退，版本查询将返回 `null`）
+
+### 调用示例
+
+查询版本：
+
+```json
+{
+  "method": "clawly.plugins.version",
+  "params": {
+    "pluginId": "clawly-plugins",
+    "npmPkgName": "@AISomething/clawly-plugins"
+  }
+}
+```
+
+常规更新：
+
+```json
+{
+  "method": "clawly.plugins.update",
+  "params": {
+    "pluginId": "clawly-plugins",
+    "npmPkgName": "@AISomething/clawly-plugins",
+    "strategy": "update"
+  }
+}
+```
+
+强制重装并重启 gateway：
+
+```json
+{
+  "method": "clawly.plugins.update",
+  "params": {
+    "pluginId": "clawly-plugins",
+    "npmPkgName": "@AISomething/clawly-plugins",
+    "strategy": "force",
+    "restart": true
+  }
+}
+```
+
+安装指定版本：
+
+```json
+{
+  "method": "clawly.plugins.update",
+  "params": {
+    "pluginId": "clawly-plugins",
+    "npmPkgName": "@AISomething/clawly-plugins",
+    "strategy": "install",
+    "targetVersion": "1.2.3"
+  }
+}
+```
+
+### 错误处理
+
+- 参数缺失返回 `{ code: "invalid_params" }` 错误。
+- 无效 strategy 返回 `{ code: "invalid_params" }` 错误。
+- npm 查询失败时，版本查询仍返回成功，`error` 字段包含错误信息。
+- 更新操作失败时返回 `{ ok: false, error: "..." }`。
+- `force` 策略在恢复配置失败时仅打印警告日志，不影响整体操作结果。
+
+### 不在范围内
+
+- 批量更新多个插件。
+- 插件安装/卸载（使用 `clawhub2gateway` 或 CLI）。
+- 自动定时检查更新。
+- 版本回滚历史记录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "module": "index.ts",
   "type": "module",
   "repository": {