@talex-touch/utils 1.0.42 → 1.0.45

package/plugin/channel.ts

@@ -9,25 +9,45 @@ import {
   ChannelType,
   DataCode,
 } from '../channel'
+import { getLogger } from '../common/logger'
+import { findCloneIssue, isCloneError, summarizeClonePayload } from '../common/utils/clone-diagnostics'
+import { formatPayloadPreview } from '../common/utils/payload-preview'
+import { hasWindow } from '../env'
 
-const CHANNEL_DEFAULT_TIMEOUT = 10_000
+const CHANNEL_DEFAULT_TIMEOUT = 60_000
 
 let cachedIpcRenderer: IpcRenderer | null = null
+const channelLog = getLogger('plugin-channel')
+
+type PluginWindow = Window & {
+  $plugin?: { name?: string }
+  $channel?: ITouchClientChannel
+  electron?: { ipcRenderer?: IpcRenderer }
+}
+
+function getPluginWindow(): PluginWindow | undefined {
+  return hasWindow() ? (window as unknown as PluginWindow) : undefined
+}
 
 // 使用惰性解析避免在打包阶段静态引入 electron
 function resolveIpcRenderer(): IpcRenderer | null {
-  if (typeof window !== 'undefined') {
-    const bridge = (window as any)?.electron
-    if (bridge?.ipcRenderer)
-      return bridge.ipcRenderer as IpcRenderer
-  }
+  const globalWindow = getPluginWindow()
+  if (globalWindow?.electron?.ipcRenderer)
+    return globalWindow.electron.ipcRenderer as IpcRenderer
 
   try {
-    const electron = (globalThis as any)?.electron ?? (eval('require') as any)?.('electron')
-    if (electron?.ipcRenderer)
-      return electron.ipcRenderer as IpcRenderer
+    const electronFromGlobal = (globalThis as any)?.electron
+    if (electronFromGlobal?.ipcRenderer)
+      return electronFromGlobal.ipcRenderer as IpcRenderer
+
+    const requireFromGlobal = (globalThis as any)?.require
+    if (typeof requireFromGlobal === 'function') {
+      const electron = requireFromGlobal('electron')
+      if (electron?.ipcRenderer)
+        return electron.ipcRenderer as IpcRenderer
+    }
   }
-  catch (error) {
+  catch {
     // ignore – will throw below if no ipcRenderer is resolved
   }
 
@@ -46,14 +66,17 @@ function ensureIpcRenderer(): IpcRenderer {
   return cachedIpcRenderer
 }
 
+type ChannelListener = (data: StandardChannelData) => unknown
+type PendingCallback = (data: RawStandardChannelData) => void
+
 /**
  * @deprecated This class is deprecated and will be removed in the future.
  * Due to the new secret system, ipc message transmission should unique Key, and will inject when ui view attached.
  */
 class TouchChannel implements ITouchClientChannel {
-  channelMap: Map<string, Function[]> = new Map()
+  channelMap: Map<string, ChannelListener[]> = new Map()
 
-  pendingMap: Map<string, Function> = new Map()
+  pendingMap: Map<string, PendingCallback> = new Map()
 
   plugin: string
 
@@ -66,7 +89,7 @@ class TouchChannel implements ITouchClientChannel {
   }
 
   __parse_raw_data(e: IpcRendererEvent | undefined, arg: any): RawStandardChannelData | null {
-    console.debug('Raw data: ', arg, e)
+    channelLog.debug('Raw data', { meta: { payload: formatPayloadPreview(arg) } })
     if (arg) {
       const { name, header, code, data, sync } = arg
 
@@ -86,7 +109,7 @@ class TouchChannel implements ITouchClientChannel {
       }
     }
 
-    console.error(e, arg)
+    channelLog.error('Invalid message payload', { error: { event: e, payload: arg } })
     return null
     // throw new Error("Invalid message!");
   }
@@ -154,7 +177,7 @@ class TouchChannel implements ITouchClientChannel {
 
   regChannel(
     eventName: string,
-    callback: Function,
+    callback: ChannelListener,
   ): () => void {
     const listeners = this.channelMap.get(eventName) || []
 
@@ -176,7 +199,7 @@ class TouchChannel implements ITouchClientChannel {
     }
   }
 
-  unRegChannel(eventName: string, callback: Function): boolean {
+  unRegChannel(eventName: string, callback: ChannelListener): boolean {
     const listeners = this.channelMap.get(eventName)
 
     if (!listeners) {
@@ -200,16 +223,7 @@ class TouchChannel implements ITouchClientChannel {
   }
 
   private formatPayloadPreview(payload: unknown): string {
-    if (payload === null || payload === undefined)
-      return String(payload)
-    if (typeof payload === 'string')
-      return payload.length > 200 ? `${payload.slice(0, 200)}…` : payload
-    try {
-      return JSON.stringify(payload)
-    }
-    catch {
-      return '[unserializable]'
-    }
+    return formatPayloadPreview(payload)
   }
 
   send(eventName: string, arg: any): Promise<any> {
@@ -239,13 +253,20 @@ class TouchChannel implements ITouchClientChannel {
       }
       catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error)
-        console.error(
-          `[PluginChannel] Failed to send "${eventName}": ${errorMessage}`,
-          { payloadPreview: this.formatPayloadPreview(arg) },
-        )
+        const meta: Record<string, unknown> = {
+          payloadPreview: this.formatPayloadPreview(arg)
+        }
+        if (isCloneError(error)) {
+          meta.cloneIssue = findCloneIssue(arg)
+          meta.payloadSummary = summarizeClonePayload(arg)
+        }
+        channelLog.error(`Failed to send \"${eventName}\": ${errorMessage}`, {
+          meta,
+          error,
+        })
         reject(
           Object.assign(
-            new Error(`Failed to send plugin channel message "${eventName}": ${errorMessage}`),
+            new Error(`Failed to send plugin channel message \"${eventName}\": ${errorMessage}`),
             { code: 'plugin_channel_send_failed' },
           ),
         )
@@ -258,10 +279,10 @@ class TouchChannel implements ITouchClientChannel {
           return
         this.pendingMap.delete(uniqueId)
         const timeoutError = Object.assign(
-          new Error(`Plugin channel request "${eventName}" timed out after ${timeoutMs}ms`),
+          new Error(`Plugin channel request \"${eventName}\" timed out after ${timeoutMs}ms`),
           { code: 'plugin_channel_timeout' },
         )
-        console.warn(timeoutError.message)
+        channelLog.warn(timeoutError.message)
         reject(timeoutError)
       }, timeoutMs)
 
@@ -299,12 +320,19 @@ class TouchChannel implements ITouchClientChannel {
     }
     catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error)
-      console.error('[PluginChannel] Failed to sendSync message', {
+      const meta: Record<string, unknown> = {
         eventName,
-        error: errorMessage,
         payloadPreview: this.formatPayloadPreview(arg),
+      }
+      if (isCloneError(error)) {
+        meta.cloneIssue = findCloneIssue(arg)
+        meta.payloadSummary = summarizeClonePayload(arg)
+      }
+      channelLog.error('Failed to sendSync message', {
+        meta,
+        error,
       })
-      throw new Error(`Failed to sendSync plugin channel message "${eventName}": ${errorMessage}`)
+      throw new Error(`Failed to sendSync plugin channel message \"${eventName}\": ${errorMessage}`)
     }
   }
 }
@@ -313,13 +341,14 @@ let touchChannel: ITouchClientChannel | null = null
 
 export function genChannel(): ITouchClientChannel {
   if (!touchChannel) {
-    if (typeof window === 'undefined' || !(window as any)?.$plugin?.name) {
+    const globalWindow = getPluginWindow()
+    const pluginName = globalWindow?.$plugin?.name
+    if (!globalWindow || !pluginName) {
       throw new Error('TouchChannel cannot be initialized outside plugin renderer context')
     }
 
-    const pluginName = (window as any).$plugin.name as string
     touchChannel = new TouchChannel(pluginName)
-    ;(window as any).$channel = touchChannel
+    globalWindow.$channel = touchChannel
   }
 
   return touchChannel

package/plugin/index.ts

@@ -4,7 +4,7 @@ import type { Arch, SupportOS } from './../base/index'
 
 import type { IPluginLogger } from './log/types'
 
-import type { PluginInstallRequest, PluginInstallSummary } from './providers'
+import type { PluginInstallRequest, PluginInstallSummary } from './providers/types'
 
 export enum PluginStatus {
   DISABLED,
@@ -33,6 +33,14 @@ export interface PluginIssue {
   timestamp?: number
 }
 
+export interface PluginMeta {
+  /**
+   * Internal plugins are created in code (no manifest / scanning).
+   * They should be hidden in UI unless developer mode is enabled.
+   */
+  internal?: boolean
+}
+
 export interface DevServerHealthCheckResult {
   healthy: boolean
   version?: string
@@ -68,13 +76,44 @@ export interface IPluginDev {
   source?: boolean
 }
 
+/**
+ * SDK API version for plugin compatibility checking.
+ * Format: YYMMDD (e.g., 251212 = 2025-12-12)
+ *
+ * Rules:
+ * - Not declared or < PERMISSION_ENFORCEMENT_MIN_VERSION: legacy mode (permissions bypassed)
+ * - >= PERMISSION_ENFORCEMENT_MIN_VERSION: permissions enforced
+ */
+export type SdkApiVersion = number
+
 export interface ITouchPlugin extends IPluginBaseInfo {
   dev: IPluginDev
   pluginPath: string
   logger: IPluginLogger<any>
+  /**
+   * Category id synced with Nexus (e.g., 'utilities', 'productivity').
+   * Used for UI grouping and marketplace filtering.
+   */
+  category?: string
+  meta?: PluginMeta
   features: IPluginFeature[]
   issues: PluginIssue[]
   divisionBoxConfig?: import('../types/division-box').ManifestDivisionBoxConfig
+  /**
+   * SDK API version declared by the plugin.
+   * Used for compatibility checking and permission enforcement.
+   * Format: YYMMDD (e.g., 251212)
+   */
+  sdkapi?: SdkApiVersion
+  /**
+   * Declared permissions from manifest.
+   * Used for permission checking and UI display.
+   */
+  declaredPermissions?: {
+    required: string[]
+    optional: string[]
+    reasons: Record<string, string>
+  }
 
   addFeature: (feature: IPluginFeature) => boolean
   delFeature: (featureId: string) => boolean
@@ -102,14 +141,21 @@ export interface ITouchPlugin extends IPluginBaseInfo {
    * @param content The content of the file.
    * @returns The result of the save operation.
    */
-  savePluginFile: (fileName: string, content: object) => { success: boolean, error?: string }
+  savePluginFile: (
+    fileName: string,
+    content: object,
+    options?: { broadcast?: boolean }
+  ) => { success: boolean, error?: string }
 
   /**
    * Delete the plugin file.
    * @param fileName The name of the file.
    * @returns The result of the delete operation.
    */
-  deletePluginFile: (fileName: string) => { success: boolean, error?: string }
+  deletePluginFile: (
+    fileName: string,
+    options?: { broadcast?: boolean }
+  ) => { success: boolean, error?: string }
 
   /**
    * List all files in the plugin.
@@ -133,11 +179,13 @@ export interface ITouchPlugin extends IPluginBaseInfo {
 
 export interface IFeatureCommand {
   type: 'match' | 'contain' | 'regex' | 'function' | 'over' | 'image' | 'files' | 'directory' | 'window'
-  value: string | string[] | RegExp | Function
+  value: string | string[] | RegExp | FeatureCommandMatcher
   /** Optional trigger callback - not serialized over IPC */
   onTrigger?: () => void
 }
 
+export type FeatureCommandMatcher = (queryText: string) => boolean
+
 export interface IPluginFeature {
   id: string
   name: string
@@ -148,6 +196,10 @@ export interface IPluginFeature {
   platform: IPlatform
   commands: IFeatureCommand[]
   interaction?: IFeatureInteraction
+  /**
+   * Experimental features are hidden unless the plugin runs in dev mode.
+   */
+  experimental?: boolean
   /**
    * Internal search tokens generated at runtime for better matching
    */
@@ -175,6 +227,17 @@ export interface IFeatureInteraction {
    * The relative path to the html file from the plugin root.
    */
   path?: string
+  /**
+   * Whether to show the input field in CoreBox when this feature is active.
+   * Defaults to true for webcontent type.
+   */
+  showInput?: boolean
+  /**
+   * Whether to automatically enable input monitoring for this feature.
+   * If true, plugin will receive input change events without calling allowInput().
+   * Defaults to true for webcontent features.
+   */
+  allowInput?: boolean
 }
 
 /**
@@ -391,6 +454,16 @@ export interface IManifest {
    * Version of the plugin, following semantic versioning (e.g., "1.0.0").
    */
   version: string
+  /**
+   * SDK API version for compatibility checking.
+   * Format: YYMMDD (e.g., 251212 = 2025-12-12)
+   * Plugins without this field or with version < 251212 will bypass permission enforcement.
+   */
+  sdkapi?: SdkApiVersion
+  /**
+   * Category id synced with Nexus (e.g., 'utilities', 'productivity').
+   */
+  category?: string
   /**
    * Short description of the plugin's functionality.
    */
@@ -500,8 +573,8 @@ export interface IManifest {
 }
 
 export * from './install'
-export type { IPluginLogger, LogDataType, LogItem, LogLevel } from './log/types'
-export * from './providers'
+export type { IPluginLogger, LogDataType, LogItem } from './log/types'
 export * from './risk'
-export * from './sdk/index'
+export * from './sdk-version'
+// Plugin runtime SDK should be imported from `@talex-touch/utils/plugin/sdk` to avoid root export collisions.
 export * from './widget'

package/plugin/install.ts

@@ -1,6 +1,7 @@
 export type PluginInstallTaskStage
   = | 'queued'
     | 'downloading'
+    | 'verifying'
     | 'awaiting-confirmation'
     | 'installing'
     | 'completed'
@@ -20,6 +21,8 @@ export interface PluginInstallProgressEvent {
   /** 插件唯一标识或名称（由客户端提供）。 */
   pluginId?: string
   pluginName?: string
+  /** 来源提供者 ID，用于区分不同市场源的同名插件。 */
+  providerId?: string
   /** 队列中的剩余任务数量（包含当前任务）。 */
   remaining?: number
   /** 当前任务在队列中的位置（0 表示正在处理）。 */

package/plugin/log/types.ts

@@ -1,7 +1,24 @@
+import type { LogLevelString as BaseLogLevelString } from '../../base/log-level'
 /**
- * Defines supported logging levels.
+ * Re-export unified LogLevel from base
  */
-export type LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'
+import {
+  LogLevel as BaseLogLevel,
+
+  logLevelToString as baseLogLevelToString,
+  stringToLogLevel as baseStringToLogLevel,
+} from '../../base/log-level'
+
+export const LogLevel = BaseLogLevel
+export type LogLevelString = BaseLogLevelString
+export const logLevelToString = baseLogLevelToString
+export const stringToLogLevel = baseStringToLogLevel
+
+/**
+ * Legacy string-based log level type (for backward compatibility)
+ * @deprecated Use LogLevel enum instead
+ */
+export type LogLevelLegacy = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'
 
 /**
  * Supported data types for logging arguments.
@@ -14,8 +31,8 @@ export type LogDataType = string | number | boolean | object
 export interface LogItem {
   /** ISO timestamp when the log was created */
   timestamp: string
-  /** Logging severity level */
-  level: LogLevel
+  /** Logging severity level (uppercase string for storage compatibility) */
+  level: LogLevelString
   /** Plugin name */
   plugin: string
   /** Main log message */
@@ -27,7 +44,7 @@ export interface LogItem {
 }
 
 /**
- * Minimal contract for plugin loggers so web 端只依赖接口定义
+ * Minimal contract for plugin loggers
  */
 export interface IPluginLogger<TManager = unknown> {
   info: (...args: LogDataType[]) => void

package/plugin/node/logger-manager.ts

@@ -3,6 +3,7 @@ import type { LogItem } from '../log/types'
 import fs from 'node:fs'
 import path from 'node:path'
 import { structuredStrictStringify } from '@talex-touch/utils'
+import { PollingService } from '../../common/utils/polling'
 
 /**
  * PluginLoggerManager is responsible for managing and writing logs for a specific plugin.
@@ -14,7 +15,8 @@ export class PluginLoggerManager {
   private readonly pluginInfoPath: string
   private readonly sessionStart: string
   private buffer: LogItem[] = []
-  private flushInterval: NodeJS.Timeout
+  private readonly pollingService = PollingService.getInstance()
+  private readonly flushTaskId: string
   private onLogAppend?: (log: LogItem) => void
 
   /**
@@ -33,9 +35,15 @@ export class PluginLoggerManager {
     this.pluginLogDir = path.resolve(baseDir, 'logs', sessionFolder)
     this.sessionLogPath = path.resolve(this.pluginLogDir, 'session.log')
     this.pluginInfoPath = path.resolve(this.pluginLogDir, 'touch-plugin.info')
+    this.flushTaskId = `plugin-logger.flush.${pluginInfo.name}.${Date.now()}`
 
     this.ensureLogEnvironment(true)
-    this.flushInterval = setInterval(() => this.flush(), 5000)
+    this.pollingService.register(
+      this.flushTaskId,
+      () => this.flush(),
+      { interval: 5, unit: 'seconds' },
+    )
+    this.pollingService.start()
   }
 
   /**
@@ -89,7 +97,7 @@ export class PluginLoggerManager {
    * Stops the flush interval and ensures remaining logs are written.
    */
   destroy(): void {
-    clearInterval(this.flushInterval)
+    this.pollingService.unregister(this.flushTaskId)
     this.flush()
   }
 

package/plugin/node/logger.ts

@@ -1,7 +1,18 @@
-import type { IPluginLogger, LogDataType, LogItem, LogLevel } from '../log/types'
+import type { IPluginLogger, LogDataType, LogItem, LogLevelString } from '../log/types'
 import type { PluginLoggerManager } from './logger-manager'
+import process from 'node:process'
+import { inspect } from 'node:util'
 import chalk from 'chalk'
 
+const pluginLogStdout =
+  process.env.TALEX_PLUGIN_LOG_STDOUT === '1' || process.env.TALEX_PLUGIN_LOG_STDOUT === 'true'
+const defaultStdoutLevels = new Set<LogLevelString>(['WARN', 'ERROR'])
+
+function shouldWriteToStdout(level: LogLevelString): boolean {
+  if (pluginLogStdout) return true
+  return defaultStdoutLevels.has(level)
+}
+
 /**
  * PluginLogger provides structured logging capabilities for individual plugins.
  */
@@ -61,13 +72,13 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
    * @param level - The severity level of the log.
    * @param args - The log message and optional data payload.
    */
-  private log(level: LogLevel, ...args: LogDataType[]): void {
+  private log(level: LogLevelString, ...args: LogDataType[]): void {
     const [message, ...data] = args
 
     const normalizedLevel = (typeof level === 'string' ? level.toUpperCase() : level) as string
-    const allowedLevels: LogLevel[] = ['INFO', 'WARN', 'ERROR', 'DEBUG']
-    const resolvedLevel = (allowedLevels.includes(normalizedLevel as LogLevel)
-      ? (normalizedLevel as LogLevel)
+    const allowedLevels: LogLevelString[] = ['INFO', 'WARN', 'ERROR', 'DEBUG']
+    const resolvedLevel = (allowedLevels.includes(normalizedLevel as LogLevelString)
+      ? (normalizedLevel as LogLevelString)
       : 'INFO')
     if (resolvedLevel === 'INFO' && normalizedLevel !== 'INFO') {
       console.warn(
@@ -75,11 +86,12 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
       )
     }
 
-    const levelColorMap: Record<LogLevel, (input: string) => string> = {
+    const levelColorMap: Record<LogLevelString, (input: string) => string> = {
       INFO: chalk.bgBlue,
       WARN: chalk.bgYellow,
       ERROR: chalk.bgRed,
       DEBUG: chalk.bgGray,
+      NONE: chalk.bgBlack,
     }
     const colorize = levelColorMap[resolvedLevel] ?? ((input: string) => input)
 
@@ -93,17 +105,12 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
     }
     this.manager.append(log)
 
-    if (resolvedLevel === 'DEBUG') {
-      console.debug(
-        `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`,
-        ...data,
-      )
-    }
-    else {
-      console.log(
-        `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`,
-        ...data,
-      )
+    if (shouldWriteToStdout(resolvedLevel)) {
+      const baseMessage = `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`
+      const extra = data.length
+        ? ` ${data.map(item => (typeof item === 'string' ? item : inspect(item))).join(' ')}`
+        : ''
+      process.stdout.write(`${baseMessage}${extra}\n`)
     }
   }
 }

package/plugin/preload.ts

@@ -1,5 +1,9 @@
 import type { ITouchClientChannel } from '../channel'
+import type { ITuffTransport } from '../transport'
 import type { ITouchSDK } from './sdk/index'
+import { getLogger } from '../common/logger'
+import { createPluginTuffTransport } from '../transport'
+import { defineRawEvent } from '../transport/event/builder'
 // Import SDK for side effects (initializes hooks)
 import './sdk/index'
 
@@ -9,8 +13,11 @@ declare global {
     $plugin: {
       name: string
       path: object
+      version?: string
+      sdkapi?: number
     }
     $channel: ITouchClientChannel
+    $transport?: ITuffTransport
     $crash: (message: string, extraData: any) => void
     $config: {
       themeStyle: any
@@ -19,14 +26,30 @@ declare global {
   }
 }
 
+const preloadLog = getLogger('plugin-preload')
+const crashEvent = defineRawEvent<Record<string, string | number | boolean | undefined>, void>('crash')
+
 export function initTuff(window: Window) {
   const plugin = window.$plugin
   if (!plugin)
     throw new Error('Plugin has a fatal error! Please check your plugin!')
 
+  if (!window.$transport && window.$channel) {
+    window.$transport = createPluginTuffTransport(window.$channel)
+  }
+  if (window.$transport) {
+    window.addEventListener?.('beforeunload', () => {
+      window.$transport?.destroy()
+    }, { once: true })
+  }
+
   window.$crash = function (message, extraData) {
-    window.$channel.send('crash', { message, ...extraData })
+    if (window.$transport) {
+      void window.$transport.send(crashEvent, { message, ...extraData })
+      return
+    }
+    window.$channel?.send?.('crash', { message, ...extraData })
   }
 
-  console.log(`%c[Plugin] ${plugin.name} loaded`, 'color: #42b983')
+  preloadLog.info(`[Plugin] ${plugin.name} loaded`)
 }

package/plugin/providers/index.ts

@@ -1,6 +1,6 @@
+export * from './market-client'
+export * from './npm-provider'
 export * from './registry'
-export * from './types'
-export * from './tpex-types'
 export * from './tpex-provider'
-export * from './npm-provider'
-export * from './market-client'
+export * from './tpex-types'
+export * from './types'

package/plugin/providers/market-client.ts

@@ -133,7 +133,8 @@ export class PluginMarketClient {
     }
 
     const sorted = results.sort((a, b) => {
-      if (a.isOfficial !== b.isOfficial) return a.isOfficial ? -1 : 1
+      if (a.isOfficial !== b.isOfficial)
+        return a.isOfficial ? -1 : 1
       return (b.downloads ?? 0) - (a.downloads ?? 0)
     })
 
@@ -156,7 +157,8 @@ export class PluginMarketClient {
     if (source === 'tpex' || (!source && !identifier.includes('/'))) {
       try {
         const plugin = await this.tpexProvider.getPlugin(identifier)
-        if (plugin) return normalizeTpexPlugin(plugin)
+        if (plugin)
+          return normalizeTpexPlugin(plugin)
       }
       catch {
         // Fall through to npm
@@ -166,7 +168,8 @@ export class PluginMarketClient {
     if (source === 'npm' || !source) {
       try {
         const pkg = await this.npmProvider.getPackageInfo(identifier)
-        if (pkg) return normalizeNpmPlugin(pkg)
+        if (pkg)
+          return normalizeNpmPlugin(pkg)
       }
       catch {
         // Not found