@talex-touch/utils 1.0.40 → 1.0.44

package/plugin/sdk/hooks/bridge.ts

@@ -1,13 +1,26 @@
-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
 
-/**
- * Defines the shape of a bridge hook function.
- * @template T The type of data the hook will receive.
- */
-export type BridgeHook<T = any> = (data: T) => void
+export interface BridgeEventMeta {
+  timestamp: number
+  fromCache: boolean
+}
+
+export interface BridgeEventPayload<T = any> {
+  data: T
+  meta: BridgeEventMeta
+}
+
+/** @template T The type of data the hook will receive. */
+export type BridgeHook<T = any> = (payload: BridgeEventPayload<T>) => void
+
+interface CachedEvent<T = any> {
+  data: T
+  timestamp: number
+}
 
 const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
   [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: [],
@@ -15,42 +28,91 @@ const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
   [BridgeEventForCoreBox.CORE_BOX_KEY_EVENT]: [],
 }
 
-/**
- * Injects a hook for a given bridge event.
- * @param type The bridge event type.
- * @param hook The hook function to inject.
- * @returns The wrapped hook function.
- * @internal
- * @template T The type of data the hook will receive.
- */
-export function injectBridgeEvent<T>(type: BridgeEvent, hook: BridgeHook<T>) {
-  const hooks: Array<BridgeHook<T>> = __hooks[type] || (__hooks[type] = [])
+const __eventCache: Map<BridgeEvent, CachedEvent[]> = new Map()
+const __channelRegistered = new Set<BridgeEvent>()
+
+const CACHE_MAX_SIZE: Record<BridgeEvent, number> = {
+  [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: 1,
+  [BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE]: 1,
+  [BridgeEventForCoreBox.CORE_BOX_KEY_EVENT]: 10,
+}
+
+const bridgeLog = getLogger('plugin-sdk')
 
-  // Only register the channel listener once per event type
-  if (hooks.length === 0) {
-    const channel = ensureRendererChannel('[TouchSDK] Bridge channel not available. Make sure hooks run in plugin renderer context.')
+function invokeHook<T>(hook: BridgeHook<T>, data: T, fromCache: boolean, timestamp: number): void {
+  try {
+    hook({ data, meta: { timestamp, fromCache } })
+  }
+  catch (e) {
+    bridgeLog.error('[TouchSDK] Bridge hook error', { error: e })
+  }
+}
+
+function registerEarlyListener(type: BridgeEvent): void {
+  if (__channelRegistered.has(type))
+    return
+
+  try {
+    const channel = ensureRendererChannel()
     channel.regChannel(type, ({ data }) => {
-      console.debug(`[TouchSDK] ${type} event received: `, data)
-      // When the event is received, call all registered hooks for this type
-      const registeredHooks = __hooks[type]
-      if (registeredHooks) {
-        registeredHooks.forEach(h => h(data))
+      const timestamp = Date.now()
+      const hooks = __hooks[type]
+
+      if (hooks && hooks.length > 0) {
+        hooks.forEach(h => invokeHook(h, data, false, timestamp))
+      }
+      else {
+        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()
+        bridgeLog.debug(`[TouchSDK] ${type} cached, size: ${cache.length}`)
       }
     })
+    __channelRegistered.add(type)
+  }
+  catch {
+    // Channel not ready yet
   }
+}
 
-  const wrappedHook = (data: T) => {
-    try {
-      hook(data)
-    }
-    catch (e) {
-      console.error(`[TouchSDK] ${type} hook error: `, e)
-    }
+/** Clears the event cache for a specific event type or all types. */
+export function clearBridgeEventCache(type?: BridgeEvent): void {
+  if (type) {
+    __eventCache.delete(type)
+  }
+  else {
+    __eventCache.clear()
   }
+}
+
+// Auto-init on module load
+;(function initBridgeEventCache() {
+  setTimeout(() => {
+    Object.values(BridgeEventForCoreBox).forEach(e => registerEarlyListener(e as BridgeEvent))
+  }, 0)
+})()
+
+/**
+ * @internal
+ */
+export function injectBridgeEvent<T>(type: BridgeEvent, hook: BridgeHook<T>) {
+  const hooks: Array<BridgeHook<T>> = __hooks[type] || (__hooks[type] = [])
+
+  // Ensure channel listener is registered
+  registerEarlyListener(type)
 
-  hooks.push(wrappedHook)
+  // Replay cached events to this new hook
+  const cached = __eventCache.get(type)
+  if (cached && cached.length > 0) {
+    cached.forEach(({ data, timestamp }) => invokeHook(hook, data as T, true, timestamp))
+    __eventCache.delete(type)
+  }
 
-  return wrappedHook
+  hooks.push(hook)
+  return hook
 }
 
 /**
@@ -61,22 +123,11 @@ export function injectBridgeEvent<T>(type: BridgeEvent, hook: BridgeHook<T>) {
  */
 export const createBridgeHook = <T>(type: BridgeEvent) => (hook: BridgeHook<T>) => injectBridgeEvent<T>(type, hook)
 
-/**
- * Hook for when the core box input changes.
- * The hook receives the new input value as a string.
- * @param data The input change data (string).
- */
-export const onCoreBoxInputChange = createBridgeHook<{ query: { inputs: Array<any>, text: string } }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
-
-export const onCoreBoxClipboardChange = createBridgeHook<{ item: any }>(BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE)
+export interface CoreBoxInputData {
+  query: { inputs: Array<any>, text: string }
+}
 
-/**
- * Hook for when a keyboard event is forwarded from CoreBox.
- * This is triggered when the plugin's UI view is attached and the user
- * presses certain keys (Enter, Arrow keys, Meta+key combinations).
- * @param data The forwarded keyboard event data.
- */
-export const onCoreBoxKeyEvent = createBridgeHook<{
+export interface CoreBoxKeyEventData {
   key: string
   code: string
   metaKey: boolean
@@ -84,4 +135,17 @@ export const onCoreBoxKeyEvent = createBridgeHook<{
   altKey: boolean
   shiftKey: boolean
   repeat: boolean
-}>(BridgeEventForCoreBox.CORE_BOX_KEY_EVENT)
+}
+
+export interface CoreBoxClipboardData {
+  item: any
+}
+
+/** Hook for CoreBox input changes. Payload includes `data` and `meta` (timestamp, fromCache). */
+export const onCoreBoxInputChange = createBridgeHook<CoreBoxInputData>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
+
+/** Hook for CoreBox clipboard changes. Payload includes `data` and `meta` (timestamp, fromCache). */
+export const onCoreBoxClipboardChange = createBridgeHook<CoreBoxClipboardData>(BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE)
+
+/** Hook for keyboard events forwarded from CoreBox. Payload includes `data` and `meta` (timestamp, fromCache). */
+export const onCoreBoxKeyEvent = createBridgeHook<CoreBoxKeyEventData>(BridgeEventForCoreBox.CORE_BOX_KEY_EVENT)

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 打开时有效
+