@talex-touch/utils 1.0.31 → 1.0.33

package/plugin/providers/registry.ts

@@ -1,18 +1,18 @@
-import { defaultRiskPromptHandler } from '../risk'
 import type { PluginInstallRequest, PluginInstallResult, PluginProvider, PluginProviderContext } from './types'
+import { defaultRiskPromptHandler } from '../risk'
 
 class ProviderRegistry {
   private providers: PluginProvider[] = []
 
   register(provider: PluginProvider): void {
-    if (this.providers.some((item) => item.type === provider.type)) {
+    if (this.providers.some(item => item.type === provider.type)) {
       throw new Error(`Plugin provider '${provider.type}' already registered`)
     }
     this.providers.push(provider)
   }
 
   unregister(type: PluginProvider['type']): void {
-    this.providers = this.providers.filter((item) => item.type !== type)
+    this.providers = this.providers.filter(item => item.type !== type)
   }
 
   clear(): void {
@@ -20,19 +20,20 @@ class ProviderRegistry {
   }
 
   resolve(request: PluginInstallRequest): PluginProvider | undefined {
-    return this.providers.find((provider) => provider.canHandle(request))
+    return this.providers.find(provider => provider.canHandle(request))
   }
 
   async install(
     request: PluginInstallRequest,
-    context: PluginProviderContext = {}
+    context: PluginProviderContext = {},
   ): Promise<PluginInstallResult | undefined> {
     const provider = this.resolve(request)
-    if (!provider) return undefined
+    if (!provider)
+      return undefined
 
     const composedContext: PluginProviderContext = {
       riskPrompt: defaultRiskPromptHandler,
-      ...context
+      ...context,
     }
 
     if (!composedContext.riskPrompt) {

package/plugin/providers/types.ts

@@ -1,5 +1,5 @@
-import type { IDownloadOptions, IDownloadResult } from '../plugin-source'
 import type { IManifest } from '..'
+import type { IDownloadOptions, IDownloadResult } from '../plugin-source'
 import type { RiskPromptHandler } from '../risk'
 
 export enum PluginProviderType {
@@ -7,7 +7,7 @@ export enum PluginProviderType {
   NPM = 'npm',
   TPEX = 'tpex',
   FILE = 'file',
-  DEV = 'dev'
+  DEV = 'dev',
 }
 
 export interface PluginInstallRequest {
@@ -43,11 +43,11 @@ export interface PluginInstallResult extends IDownloadResult {
 
 export interface PluginProvider {
   readonly type: PluginProviderType
-  canHandle(request: PluginInstallRequest): boolean
-  install(
+  canHandle: (request: PluginInstallRequest) => boolean
+  install: (
     request: PluginInstallRequest,
-    context?: PluginProviderContext
-  ): Promise<PluginInstallResult>
+    context?: PluginProviderContext,
+  ) => Promise<PluginInstallResult>
 }
 
 export interface PluginInstallSummary {

package/plugin/sdk/README.md

@@ -0,0 +1,216 @@
+# Plugin SDK 重构说明
+
+## 概述
+
+Plugin SDK 已重构为统一的工厂函数模式，参考 `DivisionBoxSDK` 的设计。旧版本 API 已废弃，调用时会抛出错误。
+
+## 新的 SDK 结构
+
+### 1. BoxSDK - CoreBox 窗口控制
+
+控制 CoreBox 窗口的显示、大小和输入框状态。
+
+```typescript
+// 隐藏/显示 CoreBox
+plugin.box.hide()
+plugin.box.show()
+
+// 扩展窗口（显示更多结果）
+plugin.box.expand({ length: 10 })
+plugin.box.expand({ forceMax: true })
+
+// 收缩窗口
+plugin.box.shrink()
+
+// 控制输入框
+plugin.box.hideInput()
+plugin.box.showInput()
+
+// 获取当前输入
+const input = await plugin.box.getInput()
+```
+
+### 2. FeatureSDK - 搜索结果管理
+
+管理插件推送的搜索结果项（TuffItems）。
+
+```typescript
+// 推送多个结果
+plugin.feature.pushItems([
+  { id: 'item-1', title: { text: 'Result 1' }, ... },
+  { id: 'item-2', title: { text: 'Result 2' }, ... }
+])
+
+// 更新单个结果
+plugin.feature.updateItem('item-1', {
+  title: { text: 'Updated Title' }
+})
+
+// 删除单个结果
+plugin.feature.removeItem('item-1')
+
+// 清空所有结果
+plugin.feature.clearItems()
+
+// 获取所有结果
+const items = plugin.feature.getItems()
+
+// 监听输入变化（实时搜索）
+const unsubscribe = plugin.feature.onInputChange((input) => {
+  console.log('User typed:', input)
+  // 执行实时搜索
+  performSearch(input)
+})
+
+// 取消监听
+unsubscribe()
+```
+
+## 废弃的 API
+
+以下 API 已废弃，调用时会抛出错误：
+
+### 旧的 Box API
+```typescript
+// ❌ 废弃
+plugin.$box.hide()
+plugin.$box.show()
+
+// ✅ 使用新 API
+plugin.box.hide()
+plugin.box.show()
+```
+
+### 旧的 Feature API
+```typescript
+// ❌ 废弃
+plugin.pushItems(items)
+plugin.clearItems()
+plugin.getItems()
+
+// ✅ 使用新 API
+plugin.feature.pushItems(items)
+plugin.feature.clearItems()
+plugin.feature.getItems()
+```
+
+## 迁移指南
+
+### 1. 更新 Box 控制代码
+
+**旧代码：**
+```typescript
+plugin.$box.hide()
+plugin.$box.show()
+```
+
+**新代码：**
+```typescript
+plugin.box.hide()
+plugin.box.show()
+plugin.box.expand({ length: 10 })
+plugin.box.shrink()
+```
+
+### 2. 更新搜索结果管理
+
+**旧代码：**
+```typescript
+plugin.pushItems([...])
+plugin.clearItems()
+const items = plugin.getItems()
+```
+
+**新代码：**
+```typescript
+plugin.feature.pushItems([...])
+plugin.feature.updateItem('id', { ... })
+plugin.feature.removeItem('id')
+plugin.feature.clearItems()
+const items = plugin.feature.getItems()
+```
+
+### 3. 添加实时搜索支持
+
+**新功能：**
+```typescript
+// 在插件初始化时注册监听器
+onInit(context) {
+  context.utils.feature.onInputChange((input) => {
+    // 用户输入变化时触发
+    this.performRealTimeSearch(input)
+  })
+}
+```
+
+## 完整示例
+
+```typescript
+export default {
+  onInit(context) {
+    const { feature, box } = context.utils
+    
+    // 监听输入变化
+    feature.onInputChange((input) => {
+      if (input.length > 2) {
+        // 执行搜索
+        const results = performSearch(input)
+        feature.pushItems(results)
+      } else {
+        feature.clearItems()
+      }
+    })
+  },
+  
+  onFeatureTriggered(featureId, query, feature) {
+    const { feature: featureSDK, box } = this.context.utils
+    
+    // 推送结果
+    featureSDK.pushItems([
+      {
+        id: 'result-1',
+        title: { text: 'Search Result' },
+        subtitle: { text: 'Description' },
+        source: { id: this.pluginName, name: this.pluginName }
+      }
+    ])
+    
+    // 扩展窗口显示结果
+    box.expand({ length: 5 })
+    
+    // 3秒后隐藏
+    setTimeout(() => {
+      box.hide()
+    }, 3000)
+  }
+}
+```
+
+## 技术细节
+
+### SDK 工厂函数
+
+所有 SDK 都通过工厂函数创建：
+
+- `createBoxSDK(channel)` - 创建 Box SDK 实例
+- `createFeatureSDK(boxItems, channel)` - 创建 Feature SDK 实例
+- `createDivisionBoxSDK(channel)` - 创建 DivisionBox SDK 实例
+
+### IPC 通道
+
+新增的 IPC 通道：
+
+- `core-box:hide-input` - 隐藏输入框
+- `core-box:show-input` - 显示输入框
+- `core-box:get-input` - 获取当前输入值
+- `core-box:input-changed` - 输入变化广播（主进程 → 插件）
+- `core-box:set-input-visibility` - 设置输入框可见性（主进程 → 渲染进程）
+- `core-box:request-input-value` - 请求输入值（主进程 → 渲染进程）
+
+### 架构优势
+
+1. **统一的 API 风格** - 所有 SDK 使用相同的工厂函数模式
+2. **更好的类型安全** - TypeScript 类型定义完整
+3. **功能分离** - Box 控制和 Feature 管理职责清晰
+4. **扩展性强** - 易于添加新功能
+5. **向后不兼容** - 强制迁移到新 API，避免技术债务

package/plugin/sdk/box-sdk.ts

@@ -0,0 +1,219 @@
+/**
+ * Box SDK for Plugin Development
+ * 
+ * Provides a unified API for plugins to control the CoreBox window behavior,
+ * including visibility, size, input field control, and input value access.
+ */
+
+/**
+ * Expand options for CoreBox window
+ */
+export interface BoxExpandOptions {
+  /** Number of items to show (affects window height) */
+  length?: number
+  /** Force maximum expansion */
+  forceMax?: boolean
+}
+
+/**
+ * Box SDK interface for plugins
+ * 
+ * @example
+ * ```typescript
+ * // Hide CoreBox
+ * plugin.box.hide()
+ * 
+ * // Show CoreBox
+ * plugin.box.show()
+ * 
+ * // Expand to show 10 items
+ * plugin.box.expand({ length: 10 })
+ * 
+ * // Get current input
+ * const input = plugin.box.getInput()
+ * ```
+ */
+export interface BoxSDK {
+  /**
+   * Hides the CoreBox window
+   * 
+   * @example
+   * ```typescript
+   * plugin.box.hide()
+   * ```
+   */
+  hide(): void
+
+  /**
+   * Shows the CoreBox window
+   * 
+   * @example
+   * ```typescript
+   * plugin.box.show()
+   * ```
+   */
+  show(): void
+
+  /**
+   * Expands the CoreBox window
+   * 
+   * @param options - Optional expansion configuration
+   * 
+   * @example
+   * ```typescript
+   * // Expand to show 10 items
+   * plugin.box.expand({ length: 10 })
+   * 
+   * // Force maximum expansion
+   * plugin.box.expand({ forceMax: true })
+   * 
+   * // Default expansion
+   * plugin.box.expand()
+   * ```
+   */
+  expand(options?: BoxExpandOptions): Promise<void>
+
+  /**
+   * Shrinks the CoreBox window to compact size
+   * 
+   * @example
+   * ```typescript
+   * plugin.box.shrink()
+   * ```
+   */
+  shrink(): Promise<void>
+
+  /**
+   * Hides the input field in CoreBox
+   * 
+   * @example
+   * ```typescript
+   * plugin.box.hideInput()
+   * ```
+   */
+  hideInput(): Promise<void>
+
+  /**
+   * Shows the input field in CoreBox
+   * 
+   * @example
+   * ```typescript
+   * plugin.box.showInput()
+   * ```
+   */
+  showInput(): Promise<void>
+
+  /**
+   * Gets the current input value from CoreBox search field
+   * 
+   * @returns Promise resolving to the current input string
+   * 
+   * @example
+   * ```typescript
+   * const input = await plugin.box.getInput()
+   * console.log('Current input:', input)
+   * ```
+   */
+  getInput(): Promise<string>
+}
+
+/**
+ * Creates a Box SDK instance for plugin use
+ * 
+ * @param channel - The plugin channel bridge for IPC communication
+ * @returns Configured Box SDK instance
+ * 
+ * @internal
+ */
+export function createBoxSDK(channel: any): BoxSDK {
+  const sendFn = channel.sendToMain || channel.send
+
+  if (!sendFn) {
+    throw new Error('[Box SDK] Channel send function not available')
+  }
+
+  return {
+    hide(): void {
+      sendFn('core-box:hide').catch((error: any) => {
+        console.error('[Box SDK] Failed to hide CoreBox:', error)
+      })
+    },
+
+    show(): void {
+      sendFn('core-box:show').catch((error: any) => {
+        console.error('[Box SDK] Failed to show CoreBox:', error)
+      })
+    },
+
+    async expand(options?: BoxExpandOptions): Promise<void> {
+      try {
+        await sendFn('core-box:expand', options || {})
+      } catch (error) {
+        console.error('[Box SDK] Failed to expand CoreBox:', error)
+        throw error
+      }
+    },
+
+    async shrink(): Promise<void> {
+      try {
+        await sendFn('core-box:expand', { mode: 'collapse' })
+      } catch (error) {
+        console.error('[Box SDK] Failed to shrink CoreBox:', error)
+        throw error
+      }
+    },
+
+    async hideInput(): Promise<void> {
+      try {
+        await sendFn('core-box:hide-input')
+      } catch (error) {
+        console.error('[Box SDK] Failed to hide input:', error)
+        throw error
+      }
+    },
+
+    async showInput(): Promise<void> {
+      try {
+        await sendFn('core-box:show-input')
+      } catch (error) {
+        console.error('[Box SDK] Failed to show input:', error)
+        throw error
+      }
+    },
+
+    async getInput(): Promise<string> {
+      try {
+        const result = await sendFn('core-box:get-input')
+        return result?.data?.input || result?.input || ''
+      } catch (error) {
+        console.error('[Box SDK] Failed to get input:', error)
+        throw error
+      }
+    }
+  }
+}
+
+/**
+ * Hook for using Box SDK in plugin context
+ * 
+ * @returns Box SDK instance
+ * 
+ * @example
+ * ```typescript
+ * const box = useBox()
+ * 
+ * box.hide()
+ * box.expand({ length: 10 })
+ * const input = await box.getInput()
+ * ```
+ */
+export function useBox(): BoxSDK {
+  // @ts-ignore - window.$channel is injected by the plugin system
+  const channel = window.$channel
+  
+  if (!channel) {
+    throw new Error('[Box SDK] Channel not available. Make sure this is called in a plugin context.')
+  }
+  
+  return createBoxSDK(channel)
+}

package/plugin/sdk/channel.ts

@@ -1,48 +1,48 @@
-import type { ITouchClientChannel } from '@talex-touch/utils/channel';
-import { genChannel } from '../channel';
-import type { IPluginRendererChannel, PluginChannelHandler } from './types';
+import type { ITouchClientChannel } from '@talex-touch/utils/channel'
+import type { IPluginRendererChannel, PluginChannelHandler } from './types'
+import { genChannel } from '../channel'
 
-const ensureClientChannel = (): ITouchClientChannel => genChannel();
+const ensureClientChannel = (): ITouchClientChannel => genChannel()
 
 export function createPluginRendererChannel(): IPluginRendererChannel {
-  const client = ensureClientChannel();
+  const client = ensureClientChannel()
 
   return {
     send(eventName, payload) {
-      return client.send(eventName, payload);
+      return client.send(eventName, payload)
     },
 
     sendSync(eventName, payload) {
-      return client.sendSync(eventName, payload);
+      return client.sendSync(eventName, payload)
     },
 
     on(eventName, handler) {
-      return client.regChannel(eventName, handler);
+      return client.regChannel(eventName, handler)
     },
 
     once(eventName, handler) {
-      let dispose: () => void = () => void 0;
+      let dispose: () => void = () => void 0
       const wrapped: PluginChannelHandler = (event) => {
-        dispose();
-        handler(event);
-      };
+        dispose()
+        handler(event)
+      }
 
-      dispose = client.regChannel(eventName, wrapped);
-      return dispose;
+      dispose = client.regChannel(eventName, wrapped)
+      return dispose
     },
 
     get raw() {
-      return client;
-    }
-  };
+      return client
+    },
+  }
 }
 
-let cachedRendererChannel: IPluginRendererChannel | null = null;
+let cachedRendererChannel: IPluginRendererChannel | null = null
 
 export function usePluginRendererChannel(): IPluginRendererChannel {
   if (!cachedRendererChannel) {
-    cachedRendererChannel = createPluginRendererChannel();
+    cachedRendererChannel = createPluginRendererChannel()
   }
 
-  return cachedRendererChannel;
+  return cachedRendererChannel
 }

package/plugin/sdk/clipboard.ts

@@ -1,6 +1,6 @@
 import type { PluginClipboardHistoryResponse, PluginClipboardItem } from './types'
 
-const ensurePluginChannel = () => {
+function ensurePluginChannel() {
   const channel = (window as any)?.$channel
   if (!channel) {
     throw new Error('[Plugin SDK] Clipboard channel requires plugin renderer context with $channel available.')
@@ -8,13 +8,15 @@ const ensurePluginChannel = () => {
   return channel
 }
 
-const normalizeItem = (item: PluginClipboardItem | null): PluginClipboardItem | null => {
-  if (!item) return item
+function normalizeItem(item: PluginClipboardItem | null): PluginClipboardItem | null {
+  if (!item)
+    return item
   if (!item.meta && typeof item.metadata === 'string') {
     try {
       const parsed = JSON.parse(item.metadata)
       return { ...item, meta: parsed }
-    } catch {
+    }
+    catch {
       return { ...item, meta: null }
     }
   }
@@ -61,7 +63,7 @@ export function useClipboardHistory() {
         : []
       return {
         ...response,
-        history
+        history,
       }
     },
 
@@ -94,6 +96,6 @@ export function useClipboardHistory() {
         return Boolean((response as any).success)
       }
       return true
-    }
+    },
   }
 }

package/plugin/sdk/common.ts

@@ -17,8 +17,10 @@ export function regShortcut(key: string, func: Function): boolean {
   const channel = genChannel()
 
   const res = channel.sendSync('shortcon:reg', { key })
-  if (res instanceof String) throw new Error(String(res))
-  if (res === false) return false
+  if (res instanceof String)
+    throw new Error(String(res))
+  if (res === false)
+    return false
 
   channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
 
@@ -33,16 +35,17 @@ export function regShortcut(key: string, func: Function): boolean {
  */
 export async function communicateWithPlugin(
   key: string,
-  info: any = {}
+  info: any = {},
 ): Promise<any> {
   const channel = genChannel()
 
   try {
     return await channel.send('index:communicate', {
       key,
-      info
+      info,
     })
-  } catch (error) {
+  }
+  catch (error) {
     console.error(`[Plugin SDK] Failed to communicate`, error)
     throw error
   }
@@ -59,7 +62,8 @@ export async function sendMessage(message: string, data: any = {}): Promise<any>
 
   try {
     return await channel.send(`plugin:${message}`, data)
-  } catch (error) {
+  }
+  catch (error) {
     console.error(`[Plugin SDK] Failed to send message: ${message}`, error)
     throw error
   }

package/plugin/sdk/core-box.ts

@@ -1,6 +1,6 @@
 import type { IPluginRendererChannel } from './types'
 
-const ensurePluginContext = (): { channel: IPluginRendererChannel; pluginName: string } => {
+function ensurePluginContext(): { channel: IPluginRendererChannel, pluginName: string } {
   const plugin = (window as any)?.$plugin
   if (!plugin?.name) {
     throw new Error('[TouchSDK] Unable to resolve plugin name inside renderer context.')
@@ -13,7 +13,7 @@ const ensurePluginContext = (): { channel: IPluginRendererChannel; pluginName: s
 
   return {
     channel,
-    pluginName: plugin.name as string
+    pluginName: plugin.name as string,
   }
 }
 
@@ -24,4 +24,3 @@ export async function clearCoreBoxItems(): Promise<void> {
   const { channel, pluginName } = ensurePluginContext()
   await channel.send('core-box:clear-items', { pluginName })
 }
-