@2en/clawly-plugins 1.33.1 → 1.34.0-beta.1

package/clawly-config-defaults.json5

@@ -39,7 +39,7 @@
             input: ["text", "image"],
             contextWindow: 1000000,
             maxTokens: 128000,
-            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+            api: "anthropic-messages",
           },
           {
             id: "anthropic/claude-opus-4.6",
@@ -47,7 +47,7 @@
             input: ["text", "image"],
             contextWindow: 1000000,
             maxTokens: 128000,
-            // api: 'anthropic-messages', // TODO: uncomment once model gateway Anthropic Messages API support is out of testing
+            api: "anthropic-messages",
           },
           {
             id: "openai/gpt-5.4",

package/config-setup.ts

@@ -237,7 +237,7 @@ export function patchBrowser(config: OpenClawConfig): boolean {
 // patchHeartbeat — migrated to clawly-config-defaults.json5
 
 /** Fields enforced by patchModelDefinitions on every gateway restart. */
-const MODEL_ENFORCED_KEYS = ['contextWindow', 'maxTokens', 'input'] as const
+const MODEL_ENFORCED_KEYS = ['contextWindow', 'maxTokens', 'input', 'api'] as const
 
 /** Shallow equality — only supports primitives and arrays of primitives. */
 function valuesEqual(a: unknown, b: unknown): boolean {
@@ -593,6 +593,43 @@ export function patchPluginsAllow(config: OpenClawConfig): boolean {
   return true
 }
 
+/**
+ * Ensure the bootstrap-extra-files internal hook is configured so the agent
+ * loads system-managed workspace files from .clawly/ alongside user files.
+ */
+export function patchBootstrapExtraFiles(config: OpenClawConfig): boolean {
+  const hooks = (config.hooks ?? {}) as Record<string, unknown>
+  const internal = asObj(hooks.internal)
+  const entries = asObj(internal.entries)
+
+  // Must match systemWorkspacePaths from @clawly/workspace-files.
+  // Hardcoded because this plugin runs on sprites without access to that package.
+  const EXPECTED_PATHS = ['.clawly/AGENTS.md', '.clawly/TOOLS.md']
+
+  const existing = entries['bootstrap-extra-files'] as
+    | {enabled?: boolean; paths?: string[]}
+    | undefined
+  if (
+    internal.enabled === true &&
+    existing?.enabled === true &&
+    Array.isArray(existing.paths) &&
+    existing.paths.length === EXPECTED_PATHS.length &&
+    EXPECTED_PATHS.every((p) => existing.paths!.includes(p))
+  ) {
+    return false
+  }
+
+  entries['bootstrap-extra-files'] = {
+    enabled: true,
+    paths: EXPECTED_PATHS,
+  }
+  internal.enabled = true
+  internal.entries = entries
+  hooks.internal = internal
+  config.hooks = hooks as OpenClawConfig['hooks']
+  return true
+}
+
 function reconcileRuntimeConfig(
   api: PluginApi,
   config: OpenClawConfig,
@@ -618,6 +655,7 @@ function reconcileRuntimeConfig(
   dirty = patchGateway(config) || dirty
   dirty = patchBrowser(config) || dirty
   dirty = patchSession(config) || dirty
+  dirty = patchBootstrapExtraFiles(config) || dirty
 
   const defaults = loadDefaults(stateDir)
   if (defaults) {

package/cron-history.ts

@@ -0,0 +1,151 @@
+/**
+ * Cron history injection — before_agent_start hook that prepends past run
+ * summaries to cron job prompts, preventing the LLM from repeating the same
+ * output across isolated sessions.
+ *
+ * Feature-flagged via agents.defaults.cronHistoryInjection in openclaw.json
+ * (default: off). Toggled from the mobile app's system settings.
+ *
+ * Data source: the existing cron run log JSONL at
+ * {cronStoreDir}/runs/{jobId}.jsonl — populated by OpenClaw after each run
+ * with a `summary` field (last agent output, truncated to 2000 chars).
+ */
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {autoUpdateJobId} from './internal/hooks/auto-update'
+import type {PluginApi} from './types'
+import type {OpenClawConfig} from './types/openclaw'
+
+const HISTORY_DEPTH = 10
+const SUMMARY_MAX_CHARS = 200
+
+/** Extract the first sentence or first line, truncated to maxChars. */
+function truncateSummary(summary: string, maxChars: number): string {
+  // Take first line
+  const firstLine = summary.split('\n')[0]?.trim() ?? summary.trim()
+  if (firstLine.length <= maxChars) return firstLine
+  return `${firstLine.slice(0, maxChars)}…`
+}
+
+/** Parse job ID from the cron prompt prefix: [cron:{jobId} {jobName}] */
+function parseJobIdFromPrompt(prompt: string): string | null {
+  const match = prompt.match(/\[cron:([0-9a-f-]+)\s/)
+  return match?.[1] ?? null
+}
+
+/** Resolve the cron run log path for a job. */
+function resolveRunLogPath(cronStore: string | undefined, jobId: string): string {
+  const storePath =
+    cronStore || path.join(process.env.HOME || '/home/claw', '.openclaw', 'cron', 'cron.json')
+  return path.join(path.dirname(storePath), 'runs', `${jobId}.jsonl`)
+}
+
+interface RunLogEntry {
+  ts: number
+  status?: string
+  summary?: string
+}
+
+/** Read last N successful run summaries from the JSONL run log. */
+async function readRecentSummaries(
+  logPath: string,
+  limit: number,
+): Promise<Array<{ts: number; summary: string}>> {
+  let raw: string
+  try {
+    raw = await fs.readFile(logPath, 'utf-8')
+  } catch {
+    return []
+  }
+  if (!raw.trim()) return []
+
+  const lines = raw.split('\n')
+  const results: Array<{ts: number; summary: string}> = []
+
+  // Read from the end (most recent first)
+  for (let i = lines.length - 1; i >= 0 && results.length < limit; i--) {
+    const line = lines[i]?.trim()
+    if (!line) continue
+    try {
+      const entry = JSON.parse(line) as Partial<RunLogEntry>
+      if (entry.status !== 'ok') continue
+      const summary = entry.summary?.trim()
+      if (!summary) continue
+      if (typeof entry.ts !== 'number') continue
+      results.push({ts: entry.ts, summary})
+    } catch {
+      // skip malformed lines
+    }
+  }
+
+  return results.reverse()
+}
+
+function formatDate(ts: number): string {
+  const d = new Date(ts)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+export function registerCronHistory(api: PluginApi) {
+  api.on(
+    'before_agent_start',
+    async (
+      event: {prompt: string; messages?: unknown[]},
+      ctx?: {agentId?: string; sessionKey?: string; sessionId?: string},
+    ) => {
+      // Feature flag check — read fresh config each time (loadConfig has ~200ms cache)
+      try {
+        const config = api.runtime.config.loadConfig() as OpenClawConfig
+        const defaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+          | Record<string, unknown>
+          | undefined
+        if (defaults?.cronHistoryInjection !== true) return
+      } catch {
+        return
+      }
+
+      // Only fire for cron sessions
+      const sessionKey = ctx?.sessionKey
+      if (!sessionKey?.includes(':cron:')) return
+
+      // Extract job ID from the prompt prefix
+      const jobId = parseJobIdFromPrompt(event.prompt)
+      if (!jobId) return
+
+      // Skip auto-update job
+      if (autoUpdateJobId && jobId === autoUpdateJobId) return
+
+      try {
+        const logPath = resolveRunLogPath(
+          (api.config.cron as Record<string, unknown> | undefined)?.store as string | undefined,
+          jobId,
+        )
+        const summaries = await readRecentSummaries(logPath, HISTORY_DEPTH)
+        if (summaries.length === 0) return
+
+        const lines = summaries.map(
+          (s, i) =>
+            `${i + 1}. (${formatDate(s.ts)}) ${truncateSummary(s.summary, SUMMARY_MAX_CHARS)}`,
+        )
+        const prependContext = [
+          `[For context: summaries of your previous ${summaries.length} ${summaries.length === 1 ? 'output' : 'outputs'} for this task. Use this to avoid repetition where appropriate.]`,
+          ...lines,
+        ].join('\n')
+
+        api.logger.info(`cron-history: injected ${summaries.length} summaries for job ${jobId}`)
+
+        return {prependContext}
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        api.logger.warn(`cron-history: failed to read history for job ${jobId} — ${msg}`)
+      }
+    },
+  )
+
+  api.logger.info('cron-history: registered before_agent_start hook')
+}

package/gateway/config-cron-history.ts

@@ -0,0 +1,57 @@
+/**
+ * Cron history injection toggle RPC: writes agents.defaults.cronHistoryInjection
+ * to openclaw.json without triggering a gateway restart.
+ *
+ * When enabled, the before_agent_start hook in cron-history.ts injects past run
+ * summaries into every cron job's prompt to prevent repeated outputs.
+ *
+ * Methods:
+ * - clawly.config.setCronHistory({ enabled }) → { changed, enabled }
+ */
+
+import type {PluginApi} from '../types'
+import type {OpenClawConfig} from '../types/openclaw'
+
+export function registerConfigCronHistory(api: PluginApi) {
+  api.registerGatewayMethod('clawly.config.setCronHistory', async ({params, respond}) => {
+    const enabled = params.enabled === true
+
+    let config: OpenClawConfig
+    try {
+      config = {...(api.runtime.config.loadConfig() as OpenClawConfig)}
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      respond(true, {changed: false, enabled, error: `Load failed: ${msg}`})
+      return
+    }
+
+    const currentDefaults = (config.agents as Record<string, unknown> | undefined)?.defaults as
+      | Record<string, unknown>
+      | undefined
+
+    if (currentDefaults?.cronHistoryInjection === enabled) {
+      respond(true, {changed: false, enabled})
+      return
+    }
+
+    // Shallow-copy nested objects to avoid polluting the loadConfig() cache
+    // if writeConfigFile fails below.
+    const agents = {...((config.agents ?? {}) as Record<string, unknown>)}
+    const defaults = {...((agents.defaults ?? {}) as Record<string, unknown>)}
+    defaults.cronHistoryInjection = enabled
+    agents.defaults = defaults
+    config.agents = agents
+
+    try {
+      await api.runtime.config.writeConfigFile(config)
+      api.logger.info(`config-cron-history: set cronHistoryInjection to ${enabled}`)
+      respond(true, {changed: true, enabled})
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      api.logger.error(`config-cron-history: write failed — ${msg}`)
+      respond(true, {changed: false, enabled, error: `Write failed: ${msg}`})
+    }
+  })
+
+  api.logger.info('config-cron-history: registered clawly.config.setCronHistory')
+}

package/gateway/index.ts

@@ -4,6 +4,7 @@ import {registerCalendarNative} from './calendar-native'
 import {registerAnalytics} from './analytics'
 import {registerAudit} from './audit'
 import {registerClawhub2gateway} from './clawhub2gateway'
+import {registerConfigCronHistory} from './config-cron-history'
 import {registerConfigModel} from './config-model'
 import {registerConfigRepair} from './config-repair'
 import {registerConfigTimezone} from './config-timezone'
@@ -63,6 +64,7 @@ export function registerGateway(api: PluginApi) {
   registerCronTelemetry(api)
   registerMessageLog(api)
   registerAnalytics(api)
+  registerConfigCronHistory(api)
   registerConfigModel(api)
   registerConfigRepair(api)
   registerConfigTimezone(api)

package/gateway/info.ts

@@ -11,8 +11,12 @@ import type {PluginApi} from '../types'
 // @ts-expect-error — JSON import
 import pkg from '../package.json'
 
+export function getInfoPayload(): {version: string} {
+  return {version: pkg.version}
+}
+
 export function registerInfo(api: PluginApi) {
   api.registerGatewayMethod('clawly.info', async ({respond}) => {
-    respond(true, {version: pkg.version})
+    respond(true, getInfoPayload())
   })
 }

package/http/info.ts

@@ -0,0 +1,28 @@
+/**
+ * HTTP route for plugin package info.
+ *
+ * Route: GET /clawly/info → { version: string }
+ * Auth: plugin (HMAC access token or gateway Bearer token)
+ */
+
+import type {IncomingMessage, ServerResponse} from 'node:http'
+
+import {getInfoPayload} from '../gateway/info'
+import {guardHttpAuth, handleCors, sendJson} from '../lib/httpAuth'
+import type {PluginApi} from '../types'
+
+export function registerInfoHttpRoute(api: PluginApi) {
+  api.registerHttpRoute({
+    path: '/clawly/info',
+    auth: 'plugin',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`)
+      if (handleCors(req, res)) return
+      if (!guardHttpAuth(api, req, res, url)) return
+
+      sendJson(res, 200, getInfoPayload())
+    },
+  })
+
+  api.logger.info('http: registered /clawly/info route')
+}

package/http/version.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP route for OpenClaw server version.
+ *
+ * Route: GET /clawly/version → { version: string }
+ * Auth: plugin (HMAC access token or gateway Bearer token)
+ */
+
+import type {IncomingMessage, ServerResponse} from 'node:http'
+
+import {getOpenClawEnvPromise} from '../lib/resolveOpenClawEnv'
+import {guardHttpAuth, handleCors, sendJson} from '../lib/httpAuth'
+import type {PluginApi} from '../types'
+
+export function registerVersionHttpRoute(api: PluginApi) {
+  api.registerHttpRoute({
+    path: '/clawly/version',
+    auth: 'plugin',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`)
+      if (handleCors(req, res)) return
+      if (!guardHttpAuth(api, req, res, url)) return
+
+      const env = await getOpenClawEnvPromise()
+      sendJson(res, 200, {version: env.version})
+    },
+  })
+
+  api.logger.info('http: registered /clawly/version route')
+}

package/index.ts

@@ -26,6 +26,8 @@
  *
  * HTTP routes:
  * - GET /clawly/file/outbound — serve files (hash lookup first, then direct path with allowlist)
+ * - GET /clawly/version        — OpenClaw server version
+ * - GET /clawly/info            — plugin package version
  *
  * Hooks:
  * - before_message_write — restores original /skill command in user messages (undoes gateway rewrite)
@@ -46,6 +48,7 @@ import {registerAutoUpdate} from './internal/hooks/auto-update'
 import {registerCalendar} from './calendar'
 import {registerCommands} from './command'
 import {setupConfig} from './config-setup'
+import {registerCronHistory} from './cron-history'
 import {registerCronHook} from './cron-hook'
 import {registerEmail} from './email'
 import {registerGateway} from './gateway'
@@ -55,6 +58,8 @@ import {
   registerOutboundHttpRoute,
   registerOutboundMethods,
 } from './http/file/outbound'
+import {registerInfoHttpRoute} from './http/info'
+import {registerVersionHttpRoute} from './http/version'
 import {registerMediaUnderstanding} from './media-understanding'
 import {registerSkillCommandRestore} from './skill-command-restore'
 import {registerTools} from './tools'
@@ -77,9 +82,12 @@ export default {
     registerOutboundHook(api)
     registerOutboundMethods(api)
     registerOutboundHttpRoute(api)
+    registerVersionHttpRoute(api)
+    registerInfoHttpRoute(api)
     registerCommands(api)
     registerTools(api)
     registerCronHook(api)
+    registerCronHistory(api)
     setupConfig(api)
     registerGateway(api)
     registerAutoPair(api)

package/media-understanding.ts

@@ -1,44 +1,97 @@
 import {PROVIDER_NAME} from './model-gateway-setup'
+import {resolveGatewayCredentials, type GatewayCredentials} from './resolve-gateway-credentials'
 import type {PluginApi} from './types'
 
-type MediaSdk = {
-  describeImageWithModel: (...args: unknown[]) => Promise<unknown>
-  describeImagesWithModel: (...args: unknown[]) => Promise<unknown>
-}
+async function chatCompletion(
+  creds: GatewayCredentials,
+  content: Array<Record<string, unknown>>,
+  opts: {model: string; timeoutMs: number; maxTokens: number},
+): Promise<{text: string; model?: string}> {
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), opts.timeoutMs)
 
-let sdkPromise: Promise<MediaSdk | null> | null = null
-
-function loadSdk(logger: PluginApi['logger']): Promise<MediaSdk | null> {
-  if (!sdkPromise) {
-    sdkPromise = import('openclaw/plugin-sdk/media-understanding').catch((err: unknown) => {
-      const code = (err as NodeJS.ErrnoException)?.code
-      if (code === 'ERR_MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
-        logger.warn(
-          'media-understanding: openclaw/plugin-sdk/media-understanding not available, skipping',
-        )
-        return null
-      }
-      throw err
+  try {
+    const res = await fetch(`${creds.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${creds.token}`,
+      },
+      body: JSON.stringify({
+        model: opts.model,
+        messages: [{role: 'user', content}],
+        max_tokens: opts.maxTokens,
+      }),
+      signal: controller.signal,
     })
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '')
+      throw new Error(`Model gateway returned ${res.status}: ${errText}`)
+    }
+
+    const data = (await res.json()) as {
+      choices?: {message?: {content?: string}}[]
+      model?: string
+    }
+    const text = data.choices?.[0]?.message?.content ?? ''
+    return {text, model: data.model ?? opts.model}
+  } finally {
+    clearTimeout(timeout)
   }
-  return sdkPromise
+}
+
+function imageToContentPart(buffer: Buffer, mime?: string): Record<string, unknown> {
+  const base64 = buffer.toString('base64')
+  return {type: 'image_url', image_url: {url: `data:${mime || 'image/jpeg'};base64,${base64}`}}
+}
+
+async function describeImageViaGateway(
+  creds: GatewayCredentials,
+  params: Record<string, unknown>,
+): Promise<{text: string; model?: string}> {
+  const content = [
+    {type: 'text', text: (params.prompt as string) || 'Describe the image.'},
+    imageToContentPart(params.buffer as Buffer, params.mime as string | undefined),
+  ]
+  return chatCompletion(creds, content, {
+    model: params.model as string,
+    timeoutMs: (params.timeoutMs as number) || 30_000,
+    maxTokens: (params.maxTokens as number) || 512,
+  })
+}
+
+async function describeImagesViaGateway(
+  creds: GatewayCredentials,
+  params: Record<string, unknown>,
+): Promise<{text: string; model?: string}> {
+  const images = params.images as Array<{buffer: Buffer; fileName?: string; mime?: string}>
+  const content: Array<Record<string, unknown>> = [
+    {type: 'text', text: (params.prompt as string) || 'Describe the images.'},
+    ...images.map((img) => imageToContentPart(img.buffer, img.mime)),
+  ]
+  return chatCompletion(creds, content, {
+    model: params.model as string,
+    timeoutMs: (params.timeoutMs as number) || 30_000,
+    maxTokens: (params.maxTokens as number) || 512,
+  })
 }
 
 export function registerMediaUnderstanding(api: PluginApi): void {
   if (!api.registerMediaUnderstandingProvider) return
 
+  const creds = resolveGatewayCredentials(api)
+  if (!creds) {
+    api.logger.warn('media-understanding: model gateway credentials not available, skipping')
+    return
+  }
+
   api.registerMediaUnderstandingProvider({
     id: PROVIDER_NAME,
     capabilities: ['image'],
-    describeImage: async (...args: unknown[]) => {
-      const sdk = await loadSdk(api.logger)
-      if (!sdk) return undefined
-      return sdk.describeImageWithModel(...args)
-    },
-    describeImages: async (...args: unknown[]) => {
-      const sdk = await loadSdk(api.logger)
-      if (!sdk) return undefined
-      return sdk.describeImagesWithModel(...args)
-    },
+    describeImage: (...args: unknown[]) =>
+      describeImageViaGateway(creds, args[0] as Record<string, unknown>),
+    describeImages: (...args: unknown[]) =>
+      describeImagesViaGateway(creds, args[0] as Record<string, unknown>),
   })
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.33.1",
+  "version": "1.34.0-beta.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -30,6 +30,7 @@
     "auto-pair.ts",
     "calendar.ts",
     "config-setup.ts",
+    "cron-history.ts",
     "cron-hook.ts",
     "email.ts",
     "gateway-fetch.ts",

package/gateway/memory-browser.md

@@ -1,55 +0,0 @@
-# memory-browser
-
-OpenClaw plugin that exposes the **memory directory** (all `.md` files) as **Gateway WebSocket RPC methods**.
-
-## What you get
-
-Gateway methods (call via WS RPC):
-
-- **`memory-browser.list`** — List all `.md` files in the memory directory (recursive). Returns `{ files: string[] }` (relative paths).
-- **`memory-browser.get`** — Return the content of a single `.md` file. Params: `{ path: string }` (relative path, e.g. `"notes/foo.md"`). Returns `{ path: string, content: string }`.
-
-## Memory directory
-
-The memory directory is resolved in this order:
-
-1. Plugin config `memoryDir` (absolute path)
-2. `<OPENCLAW_STATE_DIR>/memory` (or `<CLAWDBOT_STATE_DIR>/memory`)
-3. `<process.cwd()>/memory`
-
-## Install on a gateway host
-
-1. Put this plugin on the gateway host and make it discoverable, e.g.:
-   - Workspace: `<workspace>/.openclaw/extensions/memory-browser/` with `index.ts` + `openclaw.plugin.json`
-   - Or set `plugins.load.paths` to the plugin folder
-
-2. Enable the plugin in `openclaw.json`:
-
-```json5
-{
-  "plugins": {
-    "enabled": true,
-    "entries": {
-      "memory-browser": { "enabled": true, "config": {} }
-    }
-  }
-}
-```
-
-Optional config: `config.memoryDir` to override the memory directory path.
-
-## Call examples (RPC params)
-
-List all `.md` files:
-
-```json
-{ "method": "memory-browser.list", "params": {} }
-```
-
-Get one file:
-
-```json
-{ "method": "memory-browser.get", "params": { "path": "notes/meeting-2024.md" } }
-```
-
-`path` must be a relative path to a `.md` file inside the memory directory; directory traversal (`..`) is rejected.

package/gateway/plugin-version-management.md

@@ -1,190 +0,0 @@
-# 插件版本管理
-
-## 产品需求
-
-### 背景
-
-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）。
-- 自动定时检查更新。
-- 版本回滚历史记录。