@talex-touch/utils 1.0.42 → 1.0.45

package/plugin/sdk/hooks/bridge.ts

@@ -1,5 +1,6 @@
-import { BridgeEventForCoreBox } from '../enum/bridge-event'
+import { getLogger } from '../../../common/logger'
 import { ensureRendererChannel } from '../channel'
+import { BridgeEventForCoreBox } from '../enum/bridge-event'
 
 export type BridgeEvent = BridgeEventForCoreBox
 
@@ -36,17 +37,20 @@ const CACHE_MAX_SIZE: Record<BridgeEvent, number> = {
   [BridgeEventForCoreBox.CORE_BOX_KEY_EVENT]: 10,
 }
 
+const bridgeLog = getLogger('plugin-sdk')
+
 function invokeHook<T>(hook: BridgeHook<T>, data: T, fromCache: boolean, timestamp: number): void {
   try {
     hook({ data, meta: { timestamp, fromCache } })
   }
   catch (e) {
-    console.error('[TouchSDK] Bridge hook error:', e)
+    bridgeLog.error('[TouchSDK] Bridge hook error', { error: e })
   }
 }
 
 function registerEarlyListener(type: BridgeEvent): void {
-  if (__channelRegistered.has(type)) return
+  if (__channelRegistered.has(type))
+    return
 
   try {
     const channel = ensureRendererChannel()
@@ -58,12 +62,13 @@ function registerEarlyListener(type: BridgeEvent): void {
         hooks.forEach(h => invokeHook(h, data, false, timestamp))
       }
       else {
-        if (!__eventCache.has(type)) __eventCache.set(type, [])
+        if (!__eventCache.has(type))
+          __eventCache.set(type, [])
         const cache = __eventCache.get(type)!
         const maxSize = CACHE_MAX_SIZE[type] ?? 1
         cache.push({ data, timestamp })
         while (cache.length > maxSize) cache.shift()
-        console.debug(`[TouchSDK] ${type} cached, size: ${cache.length}`)
+        bridgeLog.debug(`[TouchSDK] ${type} cached, size: ${cache.length}`)
       }
     })
     __channelRegistered.add(type)
@@ -90,7 +95,9 @@ export function clearBridgeEventCache(type?: BridgeEvent): void {
   }, 0)
 })()
 
-/** @internal Injects a hook for a given bridge event with cache replay. */
+/**
+ * @internal
+ */
 export function injectBridgeEvent<T>(type: BridgeEvent, hook: BridgeHook<T>) {
   const hooks: Array<BridgeHook<T>> = __hooks[type] || (__hooks[type] = [])
 

package/plugin/sdk/hooks/life-cycle.ts

@@ -1,4 +1,8 @@
+import { getLogger } from '../../../common/logger'
 import { ensureRendererChannel } from '../channel'
+import { useTouchSDK } from '../touch-sdk'
+
+const sdkLog = getLogger('plugin-sdk')
 
 export enum LifecycleHooks {
   ENABLE = 'en',
@@ -9,27 +13,38 @@ export enum LifecycleHooks {
   CRASH = 'cr',
 }
 
-// @ts-ignore
-export function injectHook(type: LifecycleHooks, hook: Function, processFunc = ({ data, reply }) => {
-  // @ts-ignore
-  const hooks: Array<Function> = window.$touchSDK.__hooks[type]
-  if (hooks) {
-    hooks.forEach(hook => hook(data))
+type LifecycleHook = (data: unknown) => void
+interface HookContext { data: unknown, reply: (result: boolean) => void }
+type HookProcessor = (context: HookContext) => void
+
+export function injectHook(
+  type: LifecycleHooks,
+  hook: LifecycleHook,
+  processFunc: HookProcessor = ({ data, reply }) => {
+    const sdk = useTouchSDK('[Lifecycle Hook] TouchSDK not available. Make sure hooks run in plugin renderer context.')
+    const hooksMap = (sdk.__hooks ?? {}) as Record<LifecycleHooks, LifecycleHook[]>
+    const hooks = hooksMap[type]
+    if (hooks) {
+      hooks.forEach(hookItem => hookItem(data))
+    }
+    reply(true)
+  },
+) {
+  const sdk = useTouchSDK('[Lifecycle Hook] TouchSDK not available. Make sure hooks run in plugin renderer context.')
+  if (!sdk.__hooks || typeof sdk.__hooks !== 'object') {
+    sdk.__hooks = {}
   }
-  reply(true)
-}) {
-  // @ts-ignore
-  const __hooks = window.$touchSDK.__hooks
-  // @ts-ignore
-  const hooks: Array<Function> = __hooks[type] || (__hooks[type] = [])
+  const hooksMap = sdk.__hooks as Record<LifecycleHooks, LifecycleHook[]>
+  const hooks = hooksMap[type] || (hooksMap[type] = [])
 
   if (hooks.length === 0) {
     const channel = ensureRendererChannel('[Lifecycle Hook] Channel not available. Make sure hooks run in plugin renderer context.')
     channel.regChannel(`@lifecycle:${type}`, (obj: any) => {
       processFunc(obj)
 
-      // @ts-ignore
-      delete window.$touchSDK.__hooks[type]
+      if (sdk?.__hooks) {
+        delete sdk.__hooks[type]
+      }
     })
   }
 
@@ -38,7 +53,7 @@ export function injectHook(type: LifecycleHooks, hook: Function, processFunc = (
       hook(data)
     }
     catch (e) {
-      console.error(`[TouchSDK] ${type} hook error: `, e)
+      sdkLog.error(`[TouchSDK] ${type} hook error`, { error: e })
     }
   }
 
@@ -47,7 +62,11 @@ export function injectHook(type: LifecycleHooks, hook: Function, processFunc = (
   return wrappedHook
 }
 
-export const createHook = <T extends Function = (data: any) => any>(type: LifecycleHooks) => (hook: T) => injectHook(type, hook)
+export function createHook<T extends LifecycleHook = (data: any) => void>(type: LifecycleHooks) {
+  return (
+    hook: T,
+  ) => injectHook(type, hook)
+}
 
 /**
  * The plugin is enabled

package/plugin/sdk/index.ts

@@ -2,24 +2,35 @@ import type * as HOOKS from './hooks/index'
 
 export interface ITouchSDK {
   hooks: typeof HOOKS
-  __hooks: {}
+  __hooks: Record<string, unknown>
 }
 
 // Note: Window.$touchSDK is declared in ../preload.ts to avoid duplicate declarations
 
+export * from './box-items'
 export * from './box-sdk'
 export * from './channel'
 export * from './clipboard'
+export * from './cloud-sync'
 export * from './core-box'
 export * from './division-box'
 export * from './feature-sdk'
-export * from './flow'
 export { createFeaturesManager, useFeatures } from './features'
-
+export * from './flow'
 export * from './hooks/index'
+export * from './intelligence'
+
+export * from './meta-sdk'
+export * from './notification'
 export * from './performance'
+export * from './power'
+export * from './plugin-info'
+export * from './recommend'
 export * from './service/index'
+export * from './sqlite'
 export * from './storage'
 export * from './system'
+export * from './temp-files'
+export * from './touch-sdk'
 export * from './types'
 export * from './window/index'

package/plugin/sdk/intelligence.ts

@@ -0,0 +1,87 @@
+import type {
+  IntelligenceInvokeOptions,
+  IntelligenceInvokeResult,
+  IntelligenceMessage,
+} from '../../types/intelligence'
+import { createIntelligenceClient } from '../../intelligence/client'
+import { ensureRendererChannel } from './channel'
+import { tryGetPluginSdkApi } from './plugin-info'
+
+export interface IntelligenceChatOptions {
+  messages: IntelligenceMessage[]
+  providerId?: string
+  model?: string
+  promptTemplate?: string
+  promptVariables?: Record<string, any>
+  stream?: boolean
+  metadata?: Record<string, any>
+}
+
+export interface IntelligenceSDK {
+  invoke: <T = any>(
+    capabilityId: string,
+    payload: any,
+    options?: IntelligenceInvokeOptions,
+  ) => Promise<IntelligenceInvokeResult<T>>
+
+  /**
+   * @deprecated 请优先使用 invoke('text.chat', ...) 或 intelligence client 的 chatLangChain()。
+   */
+  chat: (options: IntelligenceChatOptions) => Promise<IntelligenceInvokeResult<string>>
+}
+
+function resolveSdkApi(): number | undefined {
+  return tryGetPluginSdkApi()
+}
+
+function createPluginIntelligenceClient() {
+  return createIntelligenceClient({
+    send: (eventName, payload) => {
+      const channel = ensureRendererChannel()
+      if (payload && typeof payload === 'object') {
+        return channel.send(eventName, {
+          ...(payload as Record<string, unknown>),
+          _sdkapi: resolveSdkApi(),
+        })
+      }
+      return channel.send(eventName, payload)
+    },
+  })
+}
+
+let cachedClient: ReturnType<typeof createPluginIntelligenceClient> | null = null
+
+function getClient() {
+  if (!cachedClient) {
+    cachedClient = createPluginIntelligenceClient()
+  }
+  return cachedClient
+}
+
+async function invokeCapability<T = any>(
+  capabilityId: string,
+  payload: any,
+  options?: IntelligenceInvokeOptions,
+): Promise<IntelligenceInvokeResult<T>> {
+  return getClient().invoke<T>(capabilityId, payload, options)
+}
+
+/**
+ * @deprecated 请优先使用 invoke('text.chat', ...) 或 intelligence client 的 chatLangChain()。
+ */
+
+async function chat(options: IntelligenceChatOptions): Promise<IntelligenceInvokeResult<string>> {
+  return getClient().chatLangChain({
+    messages: options.messages,
+    providerId: options.providerId,
+    model: options.model,
+    promptTemplate: options.promptTemplate,
+    promptVariables: options.promptVariables,
+    metadata: options.metadata,
+  })
+}
+
+export const intelligence: IntelligenceSDK = {
+  invoke: invokeCapability,
+  chat,
+}

package/plugin/sdk/meta/README.md

@@ -0,0 +1,179 @@
+# MetaSDK 使用文档
+
+MetaSDK 允许插件在 MetaOverlay 中注册全局操作，这些操作会出现在所有 item 的操作面板中。
+
+## 快速开始
+
+```typescript
+export default {
+  onInit(context) {
+    const { meta } = context.utils
+
+    // 注册一个全局操作
+    const unregister = meta.registerAction({
+      id: 'my-plugin-action',
+      render: {
+        basic: {
+          title: '我的操作',
+          subtitle: '执行我的插件功能',
+          icon: { type: 'class', value: 'i-ri-star-line' }
+        },
+        shortcut: '⌘M',
+        group: '插件操作'
+      },
+      priority: 100
+    })
+
+    // 监听操作执行
+    meta.onActionExecute((data) => {
+      if (data.actionId === 'my-plugin-action') {
+        console.log('操作被执行，item:', data.item.id)
+        // 处理操作
+      }
+    })
+
+    // 插件卸载时清理
+    return () => {
+      unregister()
+      meta.unregisterAll()
+    }
+  }
+}
+```
+
+## API 参考
+
+### `registerAction(action: MetaAction): () => void`
+
+注册一个全局操作。
+
+**参数**:
+- `action`: 操作定义
+
+**返回**: 清理函数，调用后取消注册
+
+**示例**:
+```typescript
+const unregister = plugin.meta.registerAction({
+  id: 'custom-action',
+  render: {
+    basic: {
+      title: '自定义操作',
+      subtitle: '操作描述',
+      icon: { type: 'emoji', value: '🚀' }
+    },
+    shortcut: '⌘K',
+    group: '自定义'
+  },
+  priority: 100
+})
+```
+
+### `unregisterAll(): void`
+
+取消注册该插件的所有操作。
+
+**示例**:
+```typescript
+// 插件卸载时
+plugin.meta.unregisterAll()
+```
+
+### `onActionExecute(handler: ActionExecuteHandler): () => void`
+
+注册操作执行监听器。
+
+**参数**:
+- `handler`: 处理函数，接收 `{ actionId: string, item: TuffItem }`
+
+**返回**: 清理函数
+
+**示例**:
+```typescript
+const unsubscribe = plugin.meta.onActionExecute((data) => {
+  console.log(`操作 ${data.actionId} 被执行`)
+  console.log('目标 item:', data.item.id)
+})
+```
+
+## MetaAction 类型
+
+```typescript
+interface MetaAction {
+  id: string                    // 唯一标识
+  render: {
+    basic: {
+      title: string            // 操作标题
+      subtitle?: string        // 操作描述
+      icon?: ITuffIcon         // 图标
+    }
+    shortcut?: string          // 快捷键，如 '⌘C'
+    group?: string             // 分组标题
+    disabled?: boolean         // 是否禁用
+    danger?: boolean           // 危险操作（红色）
+  }
+  priority?: number            // 优先级（默认 100）
+}
+```
+
+## 完整示例
+
+```typescript
+export default {
+  onInit(context) {
+    const { meta } = context.utils
+
+    // 注册多个操作
+    meta.registerAction({
+      id: 'analyze-item',
+      render: {
+        basic: {
+          title: '分析项目',
+          subtitle: '使用 AI 分析当前项目',
+          icon: { type: 'class', value: 'i-ri-brain-line' }
+        },
+        shortcut: '⌘A',
+        group: 'AI 操作'
+      }
+    })
+
+    meta.registerAction({
+      id: 'share-item',
+      render: {
+        basic: {
+          title: '分享项目',
+          subtitle: '分享到其他应用',
+          icon: { type: 'class', value: 'i-ri-share-line' }
+        },
+        shortcut: '⌘S',
+        group: '分享'
+      }
+    })
+
+    // 监听所有操作
+    meta.onActionExecute((data) => {
+      switch (data.actionId) {
+        case 'analyze-item':
+          // 处理分析
+          break
+        case 'share-item':
+          // 处理分享
+          break
+      }
+    })
+  },
+
+  onDestroy() {
+    // 清理所有操作
+    this.context.utils.meta.unregisterAll()
+  }
+}
+```
+
+## 注意事项
+
+1. **优先级**: 插件操作的默认优先级是 100，高于内置操作（0）和 item 操作（50）
+2. **唯一性**: 操作 ID 必须在插件内唯一
+3. **清理**: 插件卸载时应该调用 `unregisterAll()` 清理所有操作
+4. **快捷键**: 快捷键仅在 MetaOverlay 打开时有效
+

package/plugin/sdk/meta-sdk.ts

@@ -0,0 +1,244 @@
+/**
+ * MetaOverlay SDK for Plugin Development
+ *
+ * Provides API for plugins to register global actions in MetaOverlay.
+ * MetaOverlay is a floating action panel that appears above plugin UI.
+ */
+
+import type { TuffItem } from '../../core-box/tuff/tuff-dsl'
+import type { MetaAction } from '../../transport/events/types/meta-overlay'
+import { createPluginTuffTransport } from '../../transport'
+import { defineRawEvent } from '../../transport/event/builder'
+import { MetaOverlayEvents } from '../../transport/events/meta-overlay'
+import { createDisposableBag } from '../../transport/sdk'
+
+/**
+ * Action execution handler
+ */
+export type ActionExecuteHandler = (data: {
+  actionId: string
+  item: TuffItem
+}) => void
+
+const metaOverlayActionExecutedEvent = defineRawEvent<{ pluginId: string, actionId: string, item: TuffItem }, void>('meta-overlay:action-executed')
+
+/**
+ * MetaOverlay SDK interface for plugins
+ *
+ * @example
+ * ```typescript
+ * // Register a global action
+ * const unregister = plugin.meta.registerAction({
+ *   id: 'my-plugin-action',
+ *   render: {
+ *     basic: {
+ *       title: 'My Action',
+ *       subtitle: 'Execute my plugin action',
+ *       icon: { type: 'class', value: 'i-ri-star-line' }
+ *     },
+ *     shortcut: '⌘M',
+ *     group: '插件操作'
+ *   },
+ *   priority: 100
+ * })
+ *
+ * // Listen for action execution
+ * plugin.meta.onActionExecute((data) => {
+ *   if (data.actionId === 'my-plugin-action') {
+ *     // Handle action
+ *   }
+ * })
+ *
+ * // Unregister all actions
+ * plugin.meta.unregisterAll()
+ * ```
+ */
+export interface MetaSDK {
+  /**
+   * Registers a global action that will appear in MetaOverlay
+   *
+   * @param action - Action definition
+   * @returns Cleanup function to unregister this action
+   *
+   * @example
+   * ```typescript
+   * const unregister = plugin.meta.registerAction({
+   *   id: 'custom-action',
+   *   render: {
+   *     basic: {
+   *       title: 'Custom Action',
+   *       subtitle: 'Description',
+   *       icon: { type: 'emoji', value: '🚀' }
+   *     },
+   *     shortcut: '⌘K',
+   *     group: 'Custom'
+   *   },
+   *   priority: 100
+   * })
+   *
+   * // Later: unregister
+   * unregister()
+   * ```
+   */
+  registerAction: (action: MetaAction) => () => void
+
+  /**
+   * Unregisters all actions registered by this plugin
+   *
+   * @example
+   * ```typescript
+   * // Cleanup on plugin unload
+   * plugin.meta.unregisterAll()
+   * ```
+   */
+  unregisterAll: () => void
+
+  /**
+   * Registers a listener for when actions registered by this plugin are executed
+   *
+   * @param handler - Handler function
+   * @returns Cleanup function to remove listener
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = plugin.meta.onActionExecute((data) => {
+   *   console.log(`Action ${data.actionId} executed for item ${data.item.id}`)
+   *   // Handle the action
+   * })
+   *
+   * // Later: unsubscribe
+   * unsubscribe()
+   * ```
+   */
+  onActionExecute: (handler: ActionExecuteHandler) => () => void
+
+  /**
+   * 释放 SDK 内部监听器
+   */
+  dispose: () => void
+}
+
+/**
+ * Creates a MetaSDK instance for plugin use
+ *
+ * @param channel - The plugin channel bridge for IPC communication
+ * @param pluginId - Plugin identifier
+ * @returns Configured MetaSDK instance
+ *
+ * @internal
+ */
+export function createMetaSDK(channel: any, pluginId: string): MetaSDK {
+  const actionExecuteHandlers: Set<ActionExecuteHandler> = new Set()
+  const registeredActionIds: Set<string> = new Set()
+  const transport = createPluginTuffTransport(channel)
+  const disposables = createDisposableBag()
+  let disposed = false
+
+  const emitActionExecute = (data: { pluginId: string, actionId: string, item: TuffItem }) => {
+    if (data.pluginId !== pluginId || !registeredActionIds.has(data.actionId)) {
+      return
+    }
+
+    for (const handler of actionExecuteHandlers) {
+      try {
+        handler({
+          actionId: data.actionId,
+          item: data.item,
+        })
+      }
+      catch (error) {
+        console.error('[MetaSDK] onActionExecute handler error', error)
+      }
+    }
+  }
+
+  const dispose = () => {
+    if (disposed) {
+      return
+    }
+
+    disposed = true
+    actionExecuteHandlers.clear()
+
+    if (registeredActionIds.size > 0) {
+      void transport.send(MetaOverlayEvents.action.unregister, { pluginId }).catch((error) => {
+        console.error('[MetaSDK] Failed to unregister all actions during dispose', error)
+      })
+    }
+
+    registeredActionIds.clear()
+    disposables.dispose()
+    transport.destroy()
+  }
+
+  const ensureActive = (method: string) => {
+    if (disposed) {
+      throw new Error(`[MetaSDK] Cannot call ${method} after dispose`)
+    }
+  }
+
+  disposables.add(
+    transport.on(metaOverlayActionExecutedEvent, (payload) => {
+      emitActionExecute(payload)
+    }),
+  )
+
+  if (typeof window !== 'undefined' && typeof window.addEventListener === 'function') {
+    const onBeforeUnload = () => dispose()
+    window.addEventListener('beforeunload', onBeforeUnload, { once: true })
+    disposables.add(() => window.removeEventListener('beforeunload', onBeforeUnload))
+  }
+
+  return {
+    registerAction(action: MetaAction): () => void {
+      ensureActive('registerAction')
+      registeredActionIds.add(action.id)
+
+      void transport.send(MetaOverlayEvents.action.register, {
+        pluginId,
+        action: {
+          ...action,
+          handler: pluginId,
+          priority: action.priority ?? 100,
+        },
+      }).catch((error) => {
+        console.error('[MetaSDK] Failed to register action', error)
+      })
+
+      return () => {
+        if (!registeredActionIds.has(action.id)) {
+          return
+        }
+
+        registeredActionIds.delete(action.id)
+        void transport.send(MetaOverlayEvents.action.unregister, {
+          pluginId,
+          actionId: action.id,
+        } as any).catch((error) => {
+          console.error('[MetaSDK] Failed to unregister action', error)
+        })
+      }
+    },
+
+    unregisterAll(): void {
+      ensureActive('unregisterAll')
+      registeredActionIds.clear()
+
+      void transport.send(MetaOverlayEvents.action.unregister, {
+        pluginId,
+      }).catch((error) => {
+        console.error('[MetaSDK] Failed to unregister all actions', error)
+      })
+    },
+
+    onActionExecute(handler: ActionExecuteHandler): () => void {
+      ensureActive('onActionExecute')
+      actionExecuteHandlers.add(handler)
+      return () => {
+        actionExecuteHandlers.delete(handler)
+      }
+    },
+
+    dispose,
+  }
+}

package/plugin/sdk/notification.ts

@@ -0,0 +1,9 @@
+import { createNotificationSdk } from '../../transport/sdk/domains/notification'
+import { createPluginTuffTransport } from '../../transport/sdk/plugin-transport'
+import { useChannel } from './channel'
+
+export function useNotificationSdk() {
+  const channel = useChannel()
+  const transport = createPluginTuffTransport(channel)
+  return createNotificationSdk(transport)
+}