@2en/clawly-plugins 1.7.0 → 1.7.2

package/channel.ts

@@ -1,42 +1,12 @@
 /**
- * Clawly cron delivery channel — registers a minimal channel plugin so that
- * cron jobs using `delivery: { channel: "clawly-cron" }` have a valid target.
+ * Clawly cron delivery channel — minimal no-op channel registration.
  *
- * 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.
+ * With delivery.mode = "none", OpenClaw does not call sendText. This
+ * registration exists so that any existing cron jobs referencing
+ * channel "clawly-cron" still have a valid target and don't error out.
  */
 
-import {$} from 'zx'
 import type {PluginApi} from './index'
-import {sendPushNotification} from './gateway/notification'
-import {isClientOnline} from './gateway/presence'
-
-$.verbose = false
-
-async function injectAndNotify(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}`)
-
-    // Push notification if client is offline
-    const online = await isClientOnline()
-    if (!online) {
-      const pushSent = await sendPushNotification({body: text}, api)
-      api.logger.info(`clawly-cron: push notification sent=${pushSent}`)
-    }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err)
-    api.logger.error(`clawly-cron: failed to inject message — ${msg}`)
-  }
-}
 
 export function registerClawlyCronChannel(api: PluginApi) {
   const channelRegistration = {
@@ -47,7 +17,7 @@ export function registerClawlyCronChannel(api: PluginApi) {
         label: 'Clawly Cron',
         selectionLabel: 'Clawly Cron (webchat)',
         docsPath: '',
-        blurb: 'Webchat-only cron delivery channel',
+        blurb: 'No-op cron delivery channel (delivery.mode = none)',
       },
       capabilities: {chatTypes: ['dm'] as const},
       config: {
@@ -71,18 +41,10 @@ export function registerClawlyCronChannel(api: PluginApi) {
       },
       outbound: {
         deliveryMode: 'direct' as const,
-        sendText: async (...args: unknown[]) => {
-          const firstArg = args[0] as Record<string, unknown> | undefined
-          const text = typeof firstArg?.text === 'string' ? firstArg.text : ''
-          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(() => {})
-          }
+        sendText: async () => {
           return {channel: 'clawly-cron', messageId: crypto.randomUUID()}
         },
-        sendMedia: async (...args: unknown[]) => {
-          api.logger.info(`clawly-cron sendMedia: ${JSON.stringify(args)}`)
+        sendMedia: async () => {
           return {channel: 'clawly-cron', messageId: crypto.randomUUID()}
         },
       },
@@ -90,5 +52,5 @@ export function registerClawlyCronChannel(api: PluginApi) {
   }
 
   api.registerChannel(channelRegistration)
-  api.logger.info('channel: registered clawly-cron delivery channel')
+  api.logger.info('channel: registered clawly-cron delivery channel (no-op)')
 }

package/cron-hook.ts

@@ -2,7 +2,7 @@
  * before_tool_call hook for cron (action=add) — ensures delivery fields are
  * always set correctly, even when the LLM omits them.
  *
- * Forces: delivery.channel = "clawly-cron", delivery.to = "self", delivery.mode = "announce"
+ * Forces: delivery.mode = "none" (agent uses message/push tools explicitly)
  * Patches: payload.kind "systemEvent" → "agentTurn"
  *
  * The cron tool name is "cron" (not "cron.create"). The LLM passes
@@ -21,14 +21,8 @@ function isRecord(v: unknown): v is UnknownRecord {
 function patchJob(job: UnknownRecord): UnknownRecord {
   const patched: UnknownRecord = {...job}
 
-  // Force delivery fields
-  const delivery = isRecord(job.delivery) ? job.delivery : {}
-  patched.delivery = {
-    ...delivery,
-    mode: 'announce',
-    channel: 'clawly-cron',
-    to: 'self',
-  }
+  // Force delivery.mode = "none" — agent reports via message/push tools explicitly
+  patched.delivery = {mode: 'none'}
 
   // Patch payload.kind: systemEvent → agentTurn
   if (isRecord(job.payload) && job.payload.kind === 'systemEvent') {

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.2",
   "module": "index.ts",
   "type": "module",
   "repository": {