@talex-touch/utils 1.0.38 → 1.0.40

package/core-box/tuff/tuff-dsl.ts

@@ -1005,15 +1005,31 @@ export interface TuffMeta {
     permissions?: string[]
   }
 
-  /**
-   * TuffIntelligence
-   */
+  /** TuffIntelligence */
   intelligence?: any
 
+  /** Keep CoreBox open after action execution */
+  keepCoreBoxOpen?: boolean
+
+  /** 固定配置 */
+  pinned?: {
+    isPinned: boolean
+    pinnedAt?: number
+    order?: number
+  }
+
+  /** 推荐来源标记 */
+  recommendation?: {
+    source: 'frequent' | 'recent' | 'time-based' | 'trending' | 'pinned' | 'context'
+    score?: number
+  }
+
   /**
-   * Keep CoreBox open after action execution
+   * 额外关键词
+   * @description 用于搜索索引的额外关键词，会参与关键字索引匹配
+   * @warning 不建议添加太多关键词（建议 <= 10），过多会影响搜索性能
    */
-  keepCoreBoxOpen?: boolean
+  keywords?: string[]
 }
 
 // ==================== 前端展示结构 ====================
@@ -1267,71 +1283,69 @@ export interface SortStat {
   duration: number
 }
 
-/**
- * 搜索结果结构
- *
- * @description
- * 定义搜索返回的结果集合和元数据。
- * 包含匹配项、统计信息和分页数据等。
- */
+/** 容器布局配置 */
+export interface TuffContainerLayout {
+  /** 布局模式 */
+  mode: 'list' | 'grid'
+  /** 宫格配置 */
+  grid?: {
+    /** 列数 */
+    columns: number
+    /** 间距(px) */
+    gap?: number
+    /** 单项尺寸 */
+    itemSize?: 'small' | 'medium' | 'large'
+  }
+  /** 分组配置 */
+  sections?: TuffSection[]
+}
+
+/** 分组元数据 */
+export interface TuffSectionMeta {
+  /** 是否为智能推荐分组 */
+  intelligence?: boolean
+  /** 扩展字段 */
+  [key: string]: unknown
+}
+
+/** 分组定义 */
+export interface TuffSection {
+  id: string
+  title?: string
+  layout: 'list' | 'grid'
+  /** 该分组的 item ids */
+  itemIds: string[]
+  collapsed?: boolean
+  /** 分组元数据 */
+  meta?: TuffSectionMeta
+}
+
+/** 搜索结果结构 */
 export interface TuffSearchResult {
-  /**
-   * A unique identifier for this specific search operation.
-   * This is crucial for the streaming model to associate updates with the correct search instance.
-   */
+  /** 搜索会话 ID */
   sessionId?: string
-
-  /**
-   * 结果项目
-   * @description 匹配的TuffItem列表
-   * @required
-   */
+  /** 结果项目 */
   items: TuffItem[]
 
-  /**
-   * 查询信息
-   * @description 原始查询参数
-   * @required
-   */
+  /** 原始查询参数 */
   query: TuffQuery
-
-  /**
-   * 搜索耗时
-   * @description 搜索执行的毫秒数
-   * @required
-   */
+  /** 搜索耗时(ms) */
   duration: number
-
-  /**
-   * 来源统计
-   * @description 各数据来源的结果统计
-   * @required
-   */
+  /** 来源统计 */
   sources: Array<{
-    /** Provider's unique ID. */
     providerId: string
-    /** Provider's display name. */
     providerName: string
-    /** Search duration in milliseconds. */
     duration: number
-    /** Number of results returned. */
     resultCount: number
-    /** Status of the search operation. */
     status: 'success' | 'timeout' | 'error'
   }>
-
-  /**
-   * AI 推荐
-   * @description AI生成的搜索建议
-   */
+  /** 容器布局配置 */
+  containerLayout?: TuffContainerLayout
+  /** AI 推荐建议 */
   suggestions?: string[]
-
-  /**
-   * The provider(s) to activate after this search result.
-   */
+  /** 激活的 provider */
   activate?: IProviderActivate[]
-
-  /** Optional statistics about the sorting process. */
+  /** 排序统计 */
   sort_stats?: SortStat[]
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talex-touch/utils",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "private": false,
   "description": "Tuff series utils",
   "author": "TalexDreamSoul",

package/plugin/index.ts

@@ -142,10 +142,15 @@ export interface IPluginFeature {
   name: string
   desc: string
   icon: ITuffIcon
+  keywords?: string[]
   push: boolean
   platform: IPlatform
   commands: IFeatureCommand[]
   interaction?: IFeatureInteraction
+  /**
+   * Internal search tokens generated at runtime for better matching
+   */
+  searchTokens?: string[]
   /**
    * Priority of the feature for sorting in search results
    * Higher numbers have higher priority (displayed first)

package/plugin/sdk/README.md

@@ -66,6 +66,53 @@ const unsubscribe = plugin.feature.onInputChange((input) => {
 
 // 取消监听
 unsubscribe()
+
+// 监听键盘事件（UI View 模式下）
+const unsubscribeKey = plugin.feature.onKeyEvent((event) => {
+  if (event.key === 'Enter') {
+    // 处理回车键
+    submitSelection()
+  } else if (event.key === 'ArrowDown') {
+    // 向下导航
+    selectNext()
+  } else if (event.key === 'ArrowUp') {
+    // 向上导航
+    selectPrev()
+  } else if (event.metaKey && event.key === 'k') {
+    // 处理 Cmd+K
+    openSearch()
+  }
+})
+```
+
+### 3. 键盘事件自动处理
+
+当插件的 UI View 附加到 CoreBox 时，系统会自动处理以下行为：
+
+#### ESC 键自动退出
+- 在 UI View 中按下 ESC 键会**自动退出 UI 模式**（deactivate providers）
+- 插件无需手动处理 ESC 键的退出逻辑
+- 这与 CoreBox 主界面的 ESC 行为保持一致
+
+#### 键盘事件转发
+以下按键会从 CoreBox 主输入框转发到插件 UI View：
+- **Enter** - 确认/提交
+- **ArrowUp / ArrowDown** - 上下导航
+- **Meta/Ctrl + 任意键** - 快捷键组合（Cmd+V 除外，用于粘贴）
+
+> **注意**：`ArrowLeft` 和 `ArrowRight` 不会被转发，因为它们用于输入框中的文本编辑。如果需要左右导航，请使用 `Meta/Ctrl + ArrowLeft/ArrowRight`。
+
+```typescript
+// 键盘事件数据结构
+interface ForwardedKeyEvent {
+  key: string       // 按键名称，如 'Enter', 'ArrowDown'
+  code: string      // 按键代码，如 'Enter', 'ArrowDown'
+  metaKey: boolean  // Cmd/Win 键是否按下
+  ctrlKey: boolean  // Ctrl 键是否按下
+  altKey: boolean   // Alt 键是否按下
+  shiftKey: boolean // Shift 键是否按下
+  repeat: boolean   // 是否为重复按键
+}
 ```
 
 ## 废弃的 API
@@ -151,7 +198,7 @@ onInit(context) {
 export default {
   onInit(context) {
     const { feature, box } = context.utils
-    
+
     // 监听输入变化
     feature.onInputChange((input) => {
       if (input.length > 2) {
@@ -163,10 +210,10 @@ export default {
       }
     })
   },
-  
+
   onFeatureTriggered(featureId, query, feature) {
     const { feature: featureSDK, box } = this.context.utils
-    
+
     // 推送结果
     featureSDK.pushItems([
       {
@@ -176,10 +223,10 @@ export default {
         source: { id: this.pluginName, name: this.pluginName }
       }
     ])
-    
+
     // 扩展窗口显示结果
     box.expand({ length: 5 })
-    
+
     // 3秒后隐藏
     setTimeout(() => {
       box.hide()
@@ -207,7 +254,8 @@ export default {
 - `core-box:get-input` - 获取当前输入值
 - `core-box:set-input` - 设置输入框内容
 - `core-box:clear-input` - 清空输入框
-- `core-box:input-changed` - 输入变化广播（主进程 → 插件）
+- `core-box:input-change` - 输入变化广播（主进程 → 插件）
+- `core-box:key-event` - 键盘事件转发（主进程 → 插件 UI View）
 - `core-box:set-input-visibility` - 设置输入框可见性（主进程 → 渲染进程）
 - `core-box:request-input-value` - 请求输入值（主进程 → 渲染进程）
 

package/plugin/sdk/clipboard.ts

@@ -23,7 +23,7 @@ function normalizeItem(item: PluginClipboardItem | null): PluginClipboardItem |
   return item
 }
 
-export type ClipboardHistoryOptions = Omit<PluginClipboardSearchOptions, 'keyword' | 'startTime' | 'endTime' | 'type' | 'isFavorite' | 'sourceApp' | 'sortOrder'> & { page?: number }
+export type ClipboardHistoryOptions = PluginClipboardSearchOptions
 
 export interface ClipboardFavoriteOptions {
   id: number
@@ -44,69 +44,141 @@ export interface ClipboardApplyOptions {
   type?: PluginClipboardItem['type']
 }
 
+export interface ClipboardWriteOptions {
+  text?: string
+  html?: string
+  image?: string
+  files?: string[]
+}
+
+export interface ClipboardReadResult {
+  text: string
+  html: string
+  hasImage: boolean
+  hasFiles: boolean
+  formats: string[]
+}
+
+export interface ClipboardImageResult {
+  dataUrl: string
+  width: number
+  height: number
+}
+
+export interface ClipboardCopyAndPasteOptions {
+  text?: string
+  html?: string
+  image?: string
+  files?: string[]
+  delayMs?: number
+  hideCoreBox?: boolean
+}
+
 export type ClipboardSearchOptions = PluginClipboardSearchOptions
 export type ClipboardSearchResponse = PluginClipboardSearchResponse
 
-
+/**
+ * @deprecated Use `useClipboard()` instead. This function will be removed in a future version.
+ */
 export function useClipboardHistory() {
+  return useClipboard().history
+}
+
+/**
+ * Unified Clipboard SDK for plugin renderer context.
+ *
+ * Provides:
+ * - Basic clipboard operations (read/write) via IPC to main process
+ * - Clipboard history management
+ * - Copy and paste to active application
+ *
+ * All operations go through IPC to avoid WebContents focus issues.
+ *
+ * @example
+ * ```typescript
+ * const clipboard = useClipboard()
+ *
+ * // === Basic Operations ===
+ * await clipboard.writeText('Hello World')
+ * const content = await clipboard.read()
+ *
+ * // === Copy and Paste ===
+ * await clipboard.copyAndPaste({ text: 'Pasted content' })
+ *
+ * // === History Operations ===
+ * const latest = await clipboard.history.getLatest()
+ * const { history } = await clipboard.history.getHistory({ page: 1 })
+ *
+ * // === Listen to Changes ===
+ * // Note: Plugin must call box.allowClipboard(types) first
+ * const unsubscribe = clipboard.history.onDidChange((item) => {
+ *   console.log('Clipboard changed:', item)
+ * })
+ * ```
+ */
+export function useClipboard() {
   const channel = ensurePluginChannel()
 
-  return {
+  const history = {
+    /**
+     * Gets the most recent clipboard item
+     */
     async getLatest(): Promise<PluginClipboardItem | null> {
       const result = await channel.send('clipboard:get-latest')
       return normalizeItem(result)
     },
 
+    /**
+     * Gets clipboard history with pagination
+     */
     async getHistory(options: ClipboardHistoryOptions = {}): Promise<PluginClipboardHistoryResponse> {
-      const { page = 1 } = options
-      const response = await channel.send('clipboard:get-history', { page })
-      const history = Array.isArray(response?.history)
+      const response = await channel.send('clipboard:get-history', options)
+      const items = Array.isArray(response?.history)
         ? response.history.map((item: PluginClipboardItem) => normalizeItem(item) ?? item)
         : []
       return {
         ...response,
-        history,
+        history: items,
       }
     },
 
+    /**
+     * Sets favorite status for a clipboard item
+     */
     async setFavorite(options: ClipboardFavoriteOptions): Promise<void> {
       await channel.send('clipboard:set-favorite', options)
     },
 
+    /**
+     * Deletes a clipboard item from history
+     */
     async deleteItem(options: ClipboardDeleteOptions): Promise<void> {
       await channel.send('clipboard:delete-item', options)
     },
 
+    /**
+     * Clears all clipboard history
+     */
     async clearHistory(): Promise<void> {
       await channel.send('clipboard:clear-history')
     },
 
     /**
-     * Search clipboard history with advanced filtering options.
-     * Supports keyword search, time-based filtering, and combined filters.
-     *
-     * @param options - Search options
-     * @returns Search results with pagination metadata
+     * Search clipboard history with advanced filtering
      *
      * @example
      * ```typescript
      * // Search by keyword
-     * const result = await searchHistory({ keyword: 'hello' })
+     * const result = await clipboard.history.searchHistory({ keyword: 'hello' })
      *
-     * // Search by time range (last 24 hours)
-     * const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000
-     * const recent = await searchHistory({ startTime: oneDayAgo })
-     *
-     * // Combined search: text type, favorite items from a specific app
-     * const filtered = await searchHistory({
+     * // Filter by type and time
+     * const recent = await clipboard.history.searchHistory({
      *   type: 'text',
-     *   isFavorite: true,
-     *   sourceApp: 'com.apple.Safari'
+     *   startTime: Date.now() - 24 * 60 * 60 * 1000
      * })
      * ```
      */
     async searchHistory(options: ClipboardSearchOptions = {}): Promise<ClipboardSearchResponse> {
-      // Use the extended clipboard:get-history interface with search parameters
       const response = await channel.send('clipboard:get-history', options)
       const items = Array.isArray(response?.history)
         ? response.history.map((item: PluginClipboardItem) => normalizeItem(item) ?? item)
@@ -119,21 +191,120 @@ export function useClipboardHistory() {
       }
     },
 
+    /**
+     * Listen to clipboard changes.
+     *
+     * **Important**: Plugin must call `box.allowClipboard(types)` first to enable monitoring.
+     * Only changes matching the allowed types will be received.
+     *
+     * @example
+     * ```typescript
+     * import { ClipboardType } from '@talex-touch/utils/plugin/sdk'
+     *
+     * // Enable monitoring for text and images
+     * await box.allowClipboard(ClipboardType.TEXT | ClipboardType.IMAGE)
+     *
+     * // Listen to changes
+     * const unsubscribe = clipboard.history.onDidChange((item) => {
+     *   console.log('New clipboard item:', item.type, item.content)
+     * })
+     *
+     * // Later: stop listening
+     * unsubscribe()
+     * ```
+     */
     onDidChange(callback: (item: PluginClipboardItem) => void): () => void {
-      return channel.regChannel('core-box:clipboard-change', ({ data }) => {
-        const item = (data && 'item' in data ? data.item : data) as PluginClipboardItem
+      return channel.regChannel('core-box:clipboard-change', ({ data }: { data: unknown }) => {
+        const item = (data && typeof data === 'object' && 'item' in data ? (data as { item: PluginClipboardItem }).item : data) as PluginClipboardItem
         callback(normalizeItem(item) ?? item)
       })
     },
 
     /**
-     * Writes the provided clipboard payload to the system clipboard and issues a paste command
-     * to the foreground application.
+     * Apply a clipboard item to the active application (write + paste)
+     * @deprecated Use `clipboard.copyAndPaste()` instead
      */
     async applyToActiveApp(options: ClipboardApplyOptions = {}): Promise<boolean> {
       const response = await channel.send('clipboard:apply-to-active-app', options)
       if (typeof response === 'object' && response) {
-        return Boolean((response as any).success)
+        return Boolean((response as { success?: boolean }).success)
+      }
+      return true
+    },
+  }
+
+  return {
+    /**
+     * Clipboard history operations
+     */
+    history,
+
+    /**
+     * Writes text to the system clipboard
+     */
+    async writeText(text: string): Promise<void> {
+      await channel.send('clipboard:write-text', { text })
+    },
+
+    /**
+     * Writes content to the system clipboard.
+     * Supports text, HTML, image (data URL), and files.
+     */
+    async write(options: ClipboardWriteOptions): Promise<void> {
+      await channel.send('clipboard:write', options)
+    },
+
+    /**
+     * Reads current clipboard content
+     */
+    async read(): Promise<ClipboardReadResult> {
+      return await channel.send('clipboard:read')
+    },
+
+    /**
+     * Reads image from clipboard as data URL
+     */
+    async readImage(): Promise<ClipboardImageResult | null> {
+      return await channel.send('clipboard:read-image')
+    },
+
+    /**
+     * Reads file paths from clipboard
+     */
+    async readFiles(): Promise<string[]> {
+      return await channel.send('clipboard:read-files')
+    },
+
+    /**
+     * Clears the system clipboard
+     */
+    async clear(): Promise<void> {
+      await channel.send('clipboard:clear')
+    },
+
+    /**
+     * Writes content to clipboard and simulates paste command to the active application.
+     * This is the recommended way to "paste" content from a plugin.
+     *
+     * @example
+     * ```typescript
+     * // Paste text
+     * await clipboard.copyAndPaste({ text: 'Hello' })
+     *
+     * // Paste with HTML formatting
+     * await clipboard.copyAndPaste({ text: 'Hello', html: '<b>Hello</b>' })
+     *
+     * // Paste image
+     * await clipboard.copyAndPaste({ image: 'data:image/png;base64,...' })
+     *
+     * // Paste files
+     * await clipboard.copyAndPaste({ files: ['/path/to/file.txt'] })
+     * ```
+     */
+    async copyAndPaste(options: ClipboardCopyAndPasteOptions): Promise<boolean> {
+      const response = await channel.send('clipboard:copy-and-paste', options)
+      if (typeof response === 'object' && response) {
+        return Boolean((response as { success?: boolean }).success)
       }
       return true
     },

package/plugin/sdk/enum/bridge-event.ts

@@ -1,4 +1,5 @@
 export enum BridgeEventForCoreBox {
   CORE_BOX_INPUT_CHANGE = 'core-box:input-change',
   CORE_BOX_CLIPBOARD_CHANGE = 'core-box:clipboard-change',
+  CORE_BOX_KEY_EVENT = 'core-box:key-event',
 }