@talex-touch/utils 1.0.21 → 1.0.23

package/common/utils/index.ts

@@ -166,6 +166,8 @@ export function structuredStrictStringify(value: unknown): string {
   return JSON.stringify(serialize(value, 'root'));
 }
 
+export * from './timing'
+
 export { runAdaptiveTaskQueue, type AdaptiveTaskQueueOptions } from './task-queue'
 
 export * from './time'

package/common/utils/timing.ts

@@ -0,0 +1,250 @@
+export type TimingMeta = Record<string, unknown>
+
+export interface TimingRecord {
+  label: string
+  durationMs: number
+  startedAt: number
+  endedAt: number
+  iteration?: number
+  meta?: TimingMeta
+  error?: unknown
+}
+
+export interface TimingStats {
+  label: string
+  count: number
+  totalMs: number
+  avgMs: number
+  maxMs: number
+  minMs: number
+  lastMs: number
+  lastStartedAt?: number
+  lastEndedAt?: number
+  errorCount: number
+  lastError?: unknown
+}
+
+export interface TimingSummary extends TimingStats {
+  history: TimingRecord[]
+}
+
+export interface TimingManagerConfig {
+  autoLog?: boolean
+  historyLimit?: number
+  logger?: (message: string, entry: TimingRecord, stats: TimingStats) => void
+  formatter?: (entry: TimingRecord, stats: TimingStats) => string
+}
+
+export interface TimingOptions {
+  autoLog?: boolean
+  storeHistory?: boolean
+  logger?: (message: string, entry: TimingRecord, stats: TimingStats) => void
+  formatter?: (entry: TimingRecord, stats: TimingStats) => string
+  historyLimit?: number
+}
+
+export class TimingManager {
+  private readonly stats = new Map<string, TimingStats>()
+  private readonly history = new Map<string, TimingRecord[]>()
+  private readonly moduleStats = new Map<string, TimingStats>()
+
+  constructor(private readonly config: TimingManagerConfig = {}) {}
+
+  createTiming(label: string, options: TimingOptions = {}): TimingScope {
+    return new TimingScope(this, label, options)
+  }
+
+  record(label: string, record: TimingRecord, options: TimingOptions = {}): void {
+    const stats = this.updateStats(this.stats, label, record)
+    const moduleKey = this.extractModuleKey(label)
+    this.updateStats(this.moduleStats, moduleKey, { ...record, label: moduleKey })
+
+    if (options.storeHistory ?? true) {
+      const limit = options.historyLimit ?? this.config.historyLimit ?? 50
+      const list = this.history.get(label) ?? []
+      list.push(record)
+      if (list.length > limit) {
+        list.splice(0, list.length - limit)
+      }
+      this.history.set(label, list)
+    }
+
+    const shouldLog = options.autoLog ?? this.config.autoLog ?? true
+    if (shouldLog) {
+      const formatter = options.formatter ?? this.config.formatter ?? defaultFormatter
+      const logger = options.logger ?? this.config.logger ?? defaultLogger
+      logger(formatter(record, stats), record, stats)
+    }
+  }
+
+  getStats(label: string): TimingStats | undefined {
+    const stats = this.stats.get(label)
+    if (!stats) return undefined
+    return { ...stats }
+  }
+
+  getAllStats(): TimingStats[] {
+    return Array.from(this.stats.values()).map((s) => ({ ...s }))
+  }
+
+  getHistory(label: string): TimingRecord[] {
+    return [...(this.history.get(label) ?? [])]
+  }
+
+  getModuleStats(moduleKey?: string): TimingStats[] | TimingStats | undefined {
+    if (moduleKey) {
+      const stats = this.moduleStats.get(moduleKey)
+      return stats ? { ...stats } : undefined
+    }
+    return Array.from(this.moduleStats.values()).map((s) => ({ ...s }))
+  }
+
+  reset(label?: string): void {
+    if (!label) {
+      this.stats.clear()
+      this.history.clear()
+      this.moduleStats.clear()
+      return
+    }
+    this.stats.delete(label)
+    this.history.delete(label)
+  }
+
+  private updateStats(target: Map<string, TimingStats>, label: string, record: TimingRecord): TimingStats {
+    const { durationMs, error } = record
+    const next = target.get(label) ?? {
+      label,
+      count: 0,
+      totalMs: 0,
+      avgMs: 0,
+      maxMs: Number.NEGATIVE_INFINITY,
+      minMs: Number.POSITIVE_INFINITY,
+      lastMs: 0,
+      errorCount: 0
+    }
+
+    next.count += 1
+    next.totalMs += durationMs
+    next.avgMs = next.totalMs / next.count
+    next.maxMs = Math.max(next.maxMs, durationMs)
+    next.minMs = Math.min(next.minMs, durationMs)
+    next.lastMs = durationMs
+    next.lastStartedAt = record.startedAt
+    next.lastEndedAt = record.endedAt
+
+    if (error) {
+      next.errorCount += 1
+      next.lastError = error
+    }
+
+    target.set(label, next)
+    return next
+  }
+
+  private extractModuleKey(label: string): string {
+    const [moduleKey] = label.split(':')
+    return moduleKey || label
+  }
+}
+
+export class TimingScope {
+  constructor(
+    private readonly manager: TimingManager,
+    private readonly label: string,
+    private readonly options: TimingOptions
+  ) {}
+
+  async cost<T>(fn: () => Promise<T> | T, meta: TimingMeta = {}, overrides: TimingOptions = {}): Promise<T> {
+    const startedAt = now()
+    try {
+      const result = await fn()
+      this.finish(startedAt, meta, undefined, overrides)
+      return result
+    } catch (error) {
+      this.finish(startedAt, meta, error, overrides)
+      throw error
+    }
+  }
+
+  async count<T>(iterations: number, fn: (iteration: number) => Promise<T> | T, meta: TimingMeta | ((iteration: number) => TimingMeta) = {}, overrides: TimingOptions = {}): Promise<T[]> {
+    const results: T[] = []
+    for (let index = 0; index < iterations; index++) {
+      const iterationMeta = typeof meta === 'function' ? meta(index) : meta
+      const startedAt = now()
+      try {
+        const value = await fn(index)
+        this.finish(startedAt, { ...iterationMeta, iteration: index }, undefined, overrides)
+        results.push(value)
+      } catch (error) {
+        this.finish(startedAt, { ...iterationMeta, iteration: index }, error, overrides)
+        throw error
+      }
+    }
+    return results
+  }
+
+  mark(durationMs: number, meta: TimingMeta = {}, overrides: TimingOptions = {}): void {
+    const endedAt = now()
+    const startedAt = endedAt - durationMs
+    this.manager.record(
+      this.label,
+      {
+        label: this.label,
+        durationMs,
+        startedAt,
+        endedAt,
+        meta
+      },
+      { ...this.options, ...overrides }
+    )
+  }
+
+  getStats(): TimingStats | undefined {
+    return this.manager.getStats(this.label)
+  }
+
+  getHistory(): TimingRecord[] {
+    return this.manager.getHistory(this.label)
+  }
+
+  private finish(startedAt: number, meta: TimingMeta, error: unknown, overrides: TimingOptions): void {
+    const endedAt = now()
+    const record: TimingRecord = {
+      label: this.label,
+      durationMs: endedAt - startedAt,
+      startedAt,
+      endedAt,
+      meta,
+      error
+    }
+
+    this.manager.record(this.label, record, { ...this.options, ...overrides })
+  }
+}
+
+function defaultFormatter(record: TimingRecord, stats: TimingStats): string {
+  const duration = record.durationMs.toFixed(2)
+  return `⏱  [${record.label}] ${duration} ms (avg: ${stats.avgMs.toFixed(2)} ms, max: ${stats.maxMs.toFixed(2)} ms, count: ${stats.count})`
+}
+
+function defaultLogger(message: string): void {
+  console.log(message)
+}
+
+const now = (() => {
+  if (typeof globalThis !== 'undefined') {
+    const perf = (globalThis as typeof globalThis & { performance?: { now?: () => number } }).performance
+    if (perf?.now) {
+      return () => perf.now()
+    }
+  }
+  return () => Date.now()
+})()
+
+const timingManagerInstance = new TimingManager()
+
+export const timingManager = timingManagerInstance
+
+export function createTiming(label: string, options: TimingOptions = {}): TimingScope {
+  return timingManagerInstance.createTiming(label, options)
+}

package/package.json

@@ -5,7 +5,7 @@
   "module": "./index.ts",
   "license": "MPL-2.0",
   "private": false,
-  "version": "1.0.21",
+  "version": "1.0.23",
   "scripts": {
     "publish": "npm publish --access public"
   },

package/plugin/index.ts

@@ -377,4 +377,5 @@ export interface IManifest {
 export type { LogLevel, LogItem, LogDataType, IPluginLogger } from './log/types'
 export * from './sdk/index'
 export * from './providers'
+export * from './install'
 export * from './risk'

package/plugin/install.ts

@@ -0,0 +1,43 @@
+export type PluginInstallTaskStage =
+  | 'queued'
+  | 'downloading'
+  | 'awaiting-confirmation'
+  | 'installing'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export interface PluginInstallProgressEvent {
+  taskId: string
+  stage: PluginInstallTaskStage
+  progress?: number
+  message?: string
+  error?: string
+  /** 安装源标识，例如下载 URL。 */
+  source?: string
+  /** 官方插件标记。 */
+  official?: boolean
+  /** 插件唯一标识或名称（由客户端提供）。 */
+  pluginId?: string
+  pluginName?: string
+  /** 队列中的剩余任务数量（包含当前任务）。 */
+  remaining?: number
+  /** 当前任务在队列中的位置（0 表示正在处理）。 */
+  position?: number
+}
+
+export interface PluginInstallConfirmRequest {
+  taskId: string
+  pluginName?: string
+  pluginId?: string
+  source?: string
+  official?: boolean
+}
+
+export type PluginInstallConfirmDecision = 'accept' | 'reject'
+
+export interface PluginInstallConfirmResponse {
+  taskId: string
+  decision: PluginInstallConfirmDecision
+  reason?: string
+}

package/plugin/node/logger-manager.ts

@@ -12,6 +12,7 @@ export class PluginLoggerManager {
   private readonly pluginLogDir: string
   private readonly sessionLogPath: string
   private readonly pluginInfoPath: string
+  private readonly sessionStart: string
   private buffer: LogItem[] = []
   private flushInterval: NodeJS.Timeout
   private onLogAppend?: (log: LogItem) => void
@@ -25,15 +26,15 @@ export class PluginLoggerManager {
   constructor(baseDir: string, pluginInfo: ITouchPlugin, onLogAppend?: (log: LogItem) => void) {
     this.pluginInfo = pluginInfo
     this.onLogAppend = onLogAppend
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+    this.sessionStart = new Date().toISOString()
+    const timestamp = this.sessionStart.replace(/[:.]/g, '-')
     const sessionFolder = `${timestamp}_${pluginInfo.name.replace(/[^a-zA-Z0-9-_]/g, '_')}`
 
     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.ensureDirectory()
-    this.createPluginInfoFile()
+    this.ensureLogEnvironment(true)
     this.flushInterval = setInterval(() => this.flush(), 5000)
   }
 
@@ -52,8 +53,17 @@ export class PluginLoggerManager {
   flush(): void {
     if (this.buffer.length === 0) return
     const lines = this.buffer.map((item) => structuredStrictStringify(item)).join('\n') + '\n'
-    fs.appendFileSync(this.sessionLogPath, lines)
-    this.buffer = []
+    try {
+      this.ensureLogEnvironment()
+      fs.appendFileSync(this.sessionLogPath, lines)
+      this.buffer = []
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error
+      // Directory or file was removed; rebuild and retry once.
+      this.ensureLogEnvironment(true)
+      fs.appendFileSync(this.sessionLogPath, lines)
+      this.buffer = []
+    }
   }
 
   /**
@@ -83,12 +93,12 @@ export class PluginLoggerManager {
   /**
    * Creates the touch-plugin.info file with plugin information.
    */
-  private createPluginInfoFile(): void {
+  private writePluginInfoFile(): void {
     const pluginInfo = {
       name: this.pluginInfo.name,
       version: this.pluginInfo.version,
       description: this.pluginInfo.desc,
-      sessionStart: new Date().toISOString(),
+      sessionStart: this.sessionStart,
       icon: this.pluginInfo.icon,
       platforms: this.pluginInfo.platforms,
       status: this.pluginInfo.status,
@@ -103,11 +113,19 @@ export class PluginLoggerManager {
   }
 
   /**
-   * Ensures the log directory exists.
+   * Ensures the log directory and related files exist.
    */
-  private ensureDirectory(): void {
+  private ensureLogEnvironment(forceInfo = false): void {
     if (!fs.existsSync(this.pluginLogDir)) {
       fs.mkdirSync(this.pluginLogDir, { recursive: true })
     }
+
+    if (!fs.existsSync(this.sessionLogPath)) {
+      fs.writeFileSync(this.sessionLogPath, '')
+    }
+
+    if (forceInfo || !fs.existsSync(this.pluginInfoPath)) {
+      this.writePluginInfoFile()
+    }
   }
 }

package/plugin/providers/types.ts

@@ -17,6 +17,8 @@ export interface PluginInstallRequest {
   hintType?: PluginProviderType
   /** 可选元数据，在调用链中透传。 */
   metadata?: Record<string, unknown>
+  /** 客户端附加信息，仅用于 UI 状态同步。 */
+  clientMetadata?: Record<string, unknown>
 }
 
 export interface PluginProviderContext {

package/plugin/sdk/channel.ts

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

package/plugin/sdk/clipboard.ts

@@ -0,0 +1,99 @@
+import type { PluginClipboardHistoryResponse, PluginClipboardItem } from './types'
+
+const ensurePluginChannel = () => {
+  const channel = (window as any)?.$channel
+  if (!channel) {
+    throw new Error('[Plugin SDK] Clipboard channel requires plugin renderer context with $channel available.')
+  }
+  return channel
+}
+
+const 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 {
+      return { ...item, meta: null }
+    }
+  }
+  return item
+}
+
+export interface ClipboardHistoryOptions {
+  page?: number
+}
+
+export interface ClipboardFavoriteOptions {
+  id: number
+  isFavorite: boolean
+}
+
+export interface ClipboardDeleteOptions {
+  id: number
+}
+
+export interface ClipboardApplyOptions {
+  item?: PluginClipboardItem
+  text?: string
+  html?: string | null
+  files?: string[]
+  delayMs?: number
+  hideCoreBox?: boolean
+  type?: PluginClipboardItem['type']
+}
+
+export function useClipboardHistory() {
+  const channel = ensurePluginChannel()
+
+  return {
+    async getLatest(): Promise<PluginClipboardItem | null> {
+      const result = await channel.send('clipboard:get-latest')
+      return normalizeItem(result)
+    },
+
+    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)
+        ? response.history.map((item: PluginClipboardItem) => normalizeItem(item) ?? item)
+        : []
+      return {
+        ...response,
+        history
+      }
+    },
+
+    async setFavorite(options: ClipboardFavoriteOptions): Promise<void> {
+      await channel.send('clipboard:set-favorite', options)
+    },
+
+    async deleteItem(options: ClipboardDeleteOptions): Promise<void> {
+      await channel.send('clipboard:delete-item', options)
+    },
+
+    async clearHistory(): Promise<void> {
+      await channel.send('clipboard:clear-history')
+    },
+
+    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
+        callback(normalizeItem(item) ?? item)
+      })
+    },
+
+    /**
+     * Writes the provided clipboard payload to the system clipboard and issues a paste command
+     * to the foreground application.
+     */
+    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 true
+    }
+  }
+}

package/plugin/sdk/hooks/bridge.ts

@@ -10,6 +10,7 @@ export type BridgeHook<T = any> = (data: T) => void
 
 const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
   [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: [],
+  [BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE]: []
 }
 
 /**
@@ -66,3 +67,5 @@ export const createBridgeHook = <T>(type: BridgeEvent) => (hook: BridgeHook<T>)
  * @param data The input change data (string).
  */
 export const onCoreBoxInputChange = createBridgeHook<{ query: string }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
+
+export const onCoreBoxClipboardChange = createBridgeHook<{ item: any }>(BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE)

package/plugin/sdk/index.ts

@@ -17,4 +17,7 @@ export * from './window/index'
 export * from './hooks/index'
 export * from './service/index'
 
-export * from './storage'
+export * from './channel'
+export * from './clipboard'
+export * from './storage'
+export * from './system'

package/plugin/sdk/system.ts

@@ -0,0 +1,14 @@
+import type { ActiveAppSnapshot } from './types'
+
+const ensurePluginChannel = () => {
+  const channel = (window as any)?.$channel
+  if (!channel) {
+    throw new Error('[Plugin SDK] System channel requires plugin renderer context with $channel available.')
+  }
+  return channel
+}
+
+export async function getActiveAppSnapshot(options: { forceRefresh?: boolean } = {}): Promise<ActiveAppSnapshot | null> {
+  const channel = ensurePluginChannel()
+  return channel.send('system:get-active-app', options)
+}

package/plugin/sdk/types.ts

@@ -4,6 +4,124 @@
  * @version 1.0.0
  */
 
+import type { ITouchChannel, ITouchClientChannel, StandardChannelData } from '@talex-touch/utils/channel';
+
+/**
+ * Handler signature for plugin channel events.
+ */
+export type PluginChannelHandler = (event: StandardChannelData) => any;
+
+/**
+ * Bridge exposed to plugin backends for channel-based communication.
+ */
+export interface IPluginChannelBridge {
+  /**
+   * Sends a payload to the main renderer process.
+   * @param eventName - Channel event name.
+   * @param payload - Optional data payload.
+   */
+  sendToMain<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Sends a payload to this plugin's renderer view.
+   * @param eventName - Channel event name.
+   * @param payload - Optional data payload.
+   */
+  sendToRenderer<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Registers a handler for main renderer messages.
+   * @param eventName - Channel event name to listen for.
+   * @param handler - Handler invoked with the raw channel event.
+   * @returns Unsubscribe function.
+   */
+  onMain(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Registers a handler for renderer-originated messages scoped to this plugin.
+   * @param eventName - Channel event name to listen for.
+   * @param handler - Handler invoked with the raw channel event.
+   * @returns Unsubscribe function.
+   */
+  onRenderer(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Access to the underlying channel implementation for advanced scenarios.
+   */
+  readonly raw: ITouchChannel;
+}
+
+/**
+ * Renderer-side helper for plugin webviews to interact with the bridge channel.
+ */
+export interface IPluginRendererChannel {
+  /**
+   * Sends a message asynchronously and resolves with the reply payload.
+   */
+  send<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Sends a message synchronously and returns the reply payload.
+   */
+  sendSync<T = any>(eventName: string, payload?: any): T;
+
+  /**
+   * Registers a handler for renderer channel events.
+   * @returns Unsubscribe function.
+   */
+  on(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Registers a one-off handler for a renderer channel event.
+   * @returns Unsubscribe function (no-op after invocation).
+   */
+  once(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Provides access to the raw client channel.
+   */
+  readonly raw: ITouchClientChannel;
+}
+
+/**
+ * Clipboard history item shared with plugin renderers.
+ */
+export interface PluginClipboardItem {
+  id?: number
+  type: 'text' | 'image' | 'files'
+  content: string
+  thumbnail?: string | null
+  rawContent?: string | null
+  sourceApp?: string | null
+  timestamp?: string | number | Date | null
+  isFavorite?: boolean | null
+  metadata?: string | null
+  meta?: Record<string, unknown> | null
+}
+
+/**
+ * Clipboard history pagination response structure.
+ */
+export interface PluginClipboardHistoryResponse {
+  history: PluginClipboardItem[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+export interface ActiveAppSnapshot {
+  identifier: string | null
+  displayName: string | null
+  bundleId: string | null
+  processId: number | null
+  executablePath: string | null
+  platform: 'macos' | 'windows' | 'linux' | null
+  windowTitle: string | null
+  url?: string | null
+  icon?: string | null
+  lastUpdated: number
+}
+
 /**
  * Plugin utilities interface providing core functionality for plugin development
  *
@@ -28,6 +146,12 @@ export interface IPluginUtils {
    */
   clipboard: IClipboardManager;
 
+  /**
+   * Channel bridge for communicating with renderer and main processes
+   * @see {@link IPluginChannelBridge}
+   */
+  channel: IPluginChannelBridge;
+
   /**
    * Search result manager for handling search operations
    * @see {@link ISearchManager}