@talex-touch/utils 1.0.23 → 1.0.25

package/common/utils/timing.ts

@@ -8,8 +8,44 @@ export interface TimingRecord {
   iteration?: number
   meta?: TimingMeta
   error?: unknown
+  logLevel?: TimingLogLevel
 }
 
+export type TimingLogLevel = 'none' | 'info' | 'warn' | 'error'
+
+export type TimingLogThresholdOverrides = Partial<Record<Exclude<TimingLogLevel, 'error'>, number>>
+
+type ResolvedTimingLogThresholds = Record<Exclude<TimingLogLevel, 'error'>, number>
+
+const DEFAULT_AUTO_LOG = true
+const DEFAULT_STORE_HISTORY = true
+const DEFAULT_HISTORY_LIMIT = 50
+
+export const DEFAULT_TIMING_LOG_THRESHOLDS: Readonly<ResolvedTimingLogThresholds> = Object.freeze({
+  none: 16.7,
+  info: 200,
+  warn: 500
+})
+
+export const DEFAULT_TIMING_OPTIONS: Readonly<Required<Pick<TimingOptions, 'autoLog' | 'storeHistory'>> & {
+  logThresholds: Readonly<ResolvedTimingLogThresholds>
+}> = Object.freeze({
+  autoLog: DEFAULT_AUTO_LOG,
+  storeHistory: DEFAULT_STORE_HISTORY,
+  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS
+})
+
+export const DEFAULT_TIMING_MANAGER_CONFIG: Readonly<
+  Required<Pick<TimingManagerConfig, 'autoLog' | 'storeHistory' | 'historyLimit'>> & {
+    logThresholds: Readonly<ResolvedTimingLogThresholds>
+  }
+> = Object.freeze({
+  autoLog: DEFAULT_AUTO_LOG,
+  storeHistory: DEFAULT_STORE_HISTORY,
+  historyLimit: DEFAULT_HISTORY_LIMIT,
+  logThresholds: DEFAULT_TIMING_LOG_THRESHOLDS
+})
+
 export interface TimingStats {
   label: string
   count: number
@@ -22,6 +58,7 @@ export interface TimingStats {
   lastEndedAt?: number
   errorCount: number
   lastError?: unknown
+  lastLogLevel?: TimingLogLevel
 }
 
 export interface TimingSummary extends TimingStats {
@@ -30,9 +67,11 @@ export interface TimingSummary extends TimingStats {
 
 export interface TimingManagerConfig {
   autoLog?: boolean
+  storeHistory?: boolean
   historyLimit?: number
   logger?: (message: string, entry: TimingRecord, stats: TimingStats) => void
   formatter?: (entry: TimingRecord, stats: TimingStats) => string
+  logThresholds?: TimingLogThresholdOverrides
 }
 
 export interface TimingOptions {
@@ -41,39 +80,63 @@ export interface TimingOptions {
   logger?: (message: string, entry: TimingRecord, stats: TimingStats) => void
   formatter?: (entry: TimingRecord, stats: TimingStats) => string
   historyLimit?: number
+  logThresholds?: TimingLogThresholdOverrides
+}
+
+type ResolvedTimingOptions = {
+  autoLog: boolean
+  storeHistory: boolean
+  historyLimit: number
+  logThresholds: ResolvedTimingLogThresholds
+  formatter: (entry: TimingRecord, stats: TimingStats) => string
+  logger: (message: string, entry: TimingRecord, stats: TimingStats) => void
 }
 
 export class TimingManager {
   private readonly stats = new Map<string, TimingStats>()
   private readonly history = new Map<string, TimingRecord[]>()
   private readonly moduleStats = new Map<string, TimingStats>()
+  private readonly config: TimingManagerConfig
+
+  constructor(config: TimingManagerConfig = {}) {
+    const mergedThresholds: ResolvedTimingLogThresholds = {
+      ...DEFAULT_TIMING_LOG_THRESHOLDS,
+      ...(config.logThresholds ?? {})
+    }
 
-  constructor(private readonly config: TimingManagerConfig = {}) {}
+    this.config = {
+      ...DEFAULT_TIMING_MANAGER_CONFIG,
+      ...config,
+      logThresholds: mergedThresholds
+    }
+  }
 
   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 resolved = this.resolveOptions(options)
+    const logLevel = determineLogLevel(record.durationMs, resolved.logThresholds)
+    const recordWithLevel: TimingRecord = { ...record, logLevel }
+
+    const stats = this.updateStats(this.stats, label, recordWithLevel)
     const moduleKey = this.extractModuleKey(label)
-    this.updateStats(this.moduleStats, moduleKey, { ...record, label: moduleKey })
+    this.updateStats(this.moduleStats, moduleKey, { ...recordWithLevel, label: moduleKey })
 
-    if (options.storeHistory ?? true) {
-      const limit = options.historyLimit ?? this.config.historyLimit ?? 50
+    if (resolved.storeHistory) {
+      const limit = resolved.historyLimit
       const list = this.history.get(label) ?? []
-      list.push(record)
+      list.push(recordWithLevel)
       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)
+    if (resolved.autoLog && logLevel !== 'none') {
+      const message = resolved.formatter(recordWithLevel, stats)
+      resolved.logger(message, recordWithLevel, stats)
     }
   }
 
@@ -131,6 +194,7 @@ export class TimingManager {
     next.lastMs = durationMs
     next.lastStartedAt = record.startedAt
     next.lastEndedAt = record.endedAt
+    next.lastLogLevel = record.logLevel
 
     if (error) {
       next.errorCount += 1
@@ -145,6 +209,23 @@ export class TimingManager {
     const [moduleKey] = label.split(':')
     return moduleKey || label
   }
+
+  private resolveOptions(options: TimingOptions = {}): ResolvedTimingOptions {
+    const logThresholds: ResolvedTimingLogThresholds = {
+      ...DEFAULT_TIMING_LOG_THRESHOLDS,
+      ...(this.config.logThresholds ?? {}),
+      ...(options.logThresholds ?? {})
+    }
+
+    return {
+      autoLog: options.autoLog ?? this.config.autoLog ?? DEFAULT_AUTO_LOG,
+      storeHistory: options.storeHistory ?? this.config.storeHistory ?? DEFAULT_STORE_HISTORY,
+      historyLimit: options.historyLimit ?? this.config.historyLimit ?? DEFAULT_HISTORY_LIMIT,
+      logThresholds,
+      formatter: options.formatter ?? this.config.formatter ?? defaultFormatter,
+      logger: options.logger ?? this.config.logger ?? defaultLogger
+    }
+  }
 }
 
 export class TimingScope {
@@ -224,13 +305,49 @@ export class TimingScope {
 
 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})`
+  const levelTag =
+    record.logLevel && record.logLevel !== 'info' ? ` [${record.logLevel.toUpperCase()}]` : ''
+  return `⏱  [${record.label}] ${duration} ms${levelTag} (avg: ${stats.avgMs.toFixed(
+    2
+  )} ms, max: ${stats.maxMs.toFixed(2)} ms, count: ${stats.count})`
 }
 
-function defaultLogger(message: string): void {
+function defaultLogger(message: string, entry: TimingRecord, _stats: TimingStats): void {
+  if (entry.logLevel === 'none') {
+    return
+  }
+
+  if (entry.logLevel === 'warn') {
+    console.warn(message)
+    return
+  }
+
+  if (entry.logLevel === 'error') {
+    console.error(message)
+    return
+  }
+
+  if (typeof console.info === 'function') {
+    console.info(message)
+    return
+  }
+
   console.log(message)
 }
 
+function determineLogLevel(durationMs: number, thresholds: ResolvedTimingLogThresholds): TimingLogLevel {
+  if (durationMs <= thresholds.none) {
+    return 'none'
+  }
+  if (durationMs <= thresholds.info) {
+    return 'info'
+  }
+  if (durationMs <= thresholds.warn) {
+    return 'warn'
+  }
+  return 'error'
+}
+
 const now = (() => {
   if (typeof globalThis !== 'undefined') {
     const perf = (globalThis as typeof globalThis & { performance?: { now?: () => number } }).performance
@@ -245,6 +362,133 @@ const timingManagerInstance = new TimingManager()
 
 export const timingManager = timingManagerInstance
 
+export function startTiming(): number {
+  return now()
+}
+
+export function completeTiming(
+  label: string,
+  startedAt: number,
+  meta: TimingMeta = {},
+  options: TimingOptions = {}
+): number {
+  const endedAt = now()
+  const durationMs = endedAt - startedAt
+  timingManagerInstance.record(
+    label,
+    {
+      label,
+      durationMs,
+      startedAt,
+      endedAt,
+      meta
+    },
+    options
+  )
+  return durationMs
+}
+
+export function logTiming(
+  label: string,
+  durationMs: number,
+  meta: TimingMeta = {},
+  options: TimingOptions = {}
+): void {
+  const endedAt = now()
+  const startedAt = endedAt - durationMs
+  timingManagerInstance.record(
+    label,
+    {
+      label,
+      durationMs,
+      startedAt,
+      endedAt,
+      meta
+    },
+    options
+  )
+}
+
+export interface TimingLoggerToken {
+  label: string
+  startedAt: number
+  meta: TimingMeta
+  options: TimingOptions
+}
+
+export const timingLogger = {
+  start(label: string, meta: TimingMeta = {}, options: TimingOptions = {}): TimingLoggerToken {
+    return {
+      label,
+      startedAt: startTiming(),
+      meta,
+      options
+    }
+  },
+
+  finish(
+    token: TimingLoggerToken,
+    meta: TimingMeta = {},
+    overrides: TimingOptions = {}
+  ): number {
+    const mergedMeta = { ...token.meta, ...meta }
+    const mergedOptions = mergeTimingOptions(token.options, overrides)
+    return completeTiming(token.label, token.startedAt, mergedMeta, mergedOptions)
+  },
+
+  print(
+    label: string,
+    durationMs: number,
+    meta: TimingMeta = {},
+    options: TimingOptions = {}
+  ): number {
+    logTiming(label, durationMs, meta, options)
+    return durationMs
+  },
+
+  async cost<T>(
+    label: string,
+    fn: () => Promise<T> | T,
+    meta: TimingMeta = {},
+    options: TimingOptions = {}
+  ): Promise<T> {
+    const scope = createTiming(label, options)
+    return scope.cost(fn, meta)
+  },
+
+  mark(
+    label: string,
+    durationMs: number,
+    meta: TimingMeta = {},
+    options: TimingOptions = {}
+  ): number {
+    logTiming(label, durationMs, meta, options)
+    return durationMs
+  }
+}
+
 export function createTiming(label: string, options: TimingOptions = {}): TimingScope {
   return timingManagerInstance.createTiming(label, options)
 }
+
+function mergeTimingOptions(
+  base: TimingOptions = {},
+  override: TimingOptions = {}
+): TimingOptions {
+  if (!base && !override) return {}
+  if (!override || Object.keys(override).length === 0) {
+    return { ...base }
+  }
+  if (!base || Object.keys(base).length === 0) {
+    return { ...override }
+  }
+
+  return {
+    ...base,
+    ...override,
+    logThresholds: {
+      ...(base.logThresholds ?? {}),
+      ...(override.logThresholds ?? {})
+    }
+  }
+}

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

@@ -863,12 +863,29 @@ export interface TuffMeta {
    * @description The ID of the feature.
    */
   featureId?: string
+
+  /**
+   * For plugin feature items, this holds the interaction configuration.
+   * @description Defines how the feature should be rendered (widget, webcontent, or index).
+   */
+  interaction?: {
+    type: 'webcontent' | 'widget' | 'index'
+    path?: string
+  }
+
   /**
    * Defines the default action to be taken when the item is executed (e.g., by pressing Enter).
    * This is used to distinguish simple actions (like 'copy') from feature activations.
    * @description The default action type.
    */
   defaultAction?: string;
+
+  /**
+   * Priority of the item for sorting in search results
+   * Higher numbers have higher priority (displayed first)
+   * @description Priority value for search result ordering
+   */
+  priority?: number;
   /**
    * 原始数据
    * @description 项目的原始数据对象，用于特殊处理

package/package.json

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

package/plugin/index.ts

@@ -59,7 +59,7 @@ export interface IPluginBaseInfo {
 export interface IPluginDev {
   enable: boolean
   address: string
-  source?: string // 修改此处，允许 source 为字符串或 undefined
+  source?: boolean
 }
 
 export interface ITouchPlugin extends IPluginBaseInfo {
@@ -81,6 +81,47 @@ export interface ITouchPlugin extends IPluginBaseInfo {
 
   enable(): Promise<boolean>
   disable(): Promise<boolean>
+
+  /**
+   * Get the plugin file.
+   * @param fileName The name of the file.
+   * @returns The content of the file.
+   */
+  getPluginFile(fileName: string): object
+
+  /**
+   * Save the plugin file.
+   * @param fileName The name of the file.
+   * @param content The content of the file.
+   * @returns The result of the save operation.
+   */
+  savePluginFile(fileName: string, content: object): { 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 }
+
+  /**
+   * List all files in the plugin.
+   * @returns The list of files.
+   */
+  listPluginFiles(): string[]
+
+  /**
+   * Get the plugin configuration.
+   * @returns The configuration content.
+   */
+  getPluginConfig(): object
+
+  /**
+   * Save the plugin configuration.
+   * @param content The configuration content.
+   * @returns The result of the save operation.
+   */
+  savePluginConfig(content: object): { success: boolean; error?: string }
 }
 
 export interface IFeatureCommand {
@@ -98,6 +139,12 @@ export interface IPluginFeature {
   platform: IPlatform
   commands: IFeatureCommand[]
   interaction?: IFeatureInteraction
+  /**
+   * Priority of the feature for sorting in search results
+   * Higher numbers have higher priority (displayed first)
+   * Default is 0
+   */
+  priority?: number
 }
 
 export type IFeatureInteraction = {
@@ -113,6 +160,18 @@ export type IFeatureInteraction = {
  * These hooks are triggered based on real user interaction and system events.
  */
 export interface IFeatureLifeCycle {
+  /**
+   * onInit is called when the feature is initialized.
+   * Can be used to prepare data or UI specific to this session.
+   */
+  onInit?(): void
+
+  /**
+   * Called when a message is received from the main application.
+   * @param key - The key of the message
+   * @param info - The information of the message
+   */
+  onMessage?(key: string, info: any): void
   /**
    * Called when a feature is actively launched from the launcher.
    * Can be used to prepare data or UI specific to this session.
@@ -156,8 +215,16 @@ export interface IFeatureLifeCycle {
    * This is used for handling actions on the items themselves,
    * rather than triggering a new feature.
    * @param item The TuffItem that was executed.
+   * @returns Object indicating whether to activate the feature and any activation data
    */
-  onItemAction?(item: any): Promise<any>
+  onItemAction?(item: any): Promise<{
+    /** Whether the action executed an external operation (e.g., opened browser) */
+    externalAction?: boolean
+    /** Whether the feature should be activated after this action */
+    shouldActivate?: boolean
+    /** Activation data if shouldActivate is true */
+    activation?: any
+  } | void>
 }
 
 /**
@@ -206,8 +273,16 @@ export interface ITargetFeatureLifeCycle {
    * This is used for handling actions on the items themselves,
    * rather than triggering a new feature.
    * @param item The TuffItem that was executed.
+   * @returns Object indicating whether to activate the feature and any activation data
    */
-  onItemAction?(item: any): Promise<any>
+  onItemAction?(item: any): Promise<{
+    /** Whether the action executed an external operation (e.g., opened browser) */
+    externalAction?: boolean
+    /** Whether the feature should be activated after this action */
+    shouldActivate?: boolean
+    /** Activation data if shouldActivate is true */
+    activation?: any
+  } | void>
 }
 
 /**

package/plugin/sdk/common.ts

@@ -1,28 +1,77 @@
-import { genChannel } from '../channel';
-import { IPluginFeature } from '../index'
+/**
+ * Plugin SDK Common Utilities
+ *
+ * @description
+ * 提供插件SDK的通用功能，包括通信、快捷键等
+ */
 
-export function regShortcut(key: string, func: Function) {
-    const channel = genChannel()
+import { genChannel } from '../channel'
 
-    const res = channel.sendSync('shortcon:reg', { key })
-    if ( res instanceof String ) throw new Error(String(res))
-    if ( res === false ) return false;
+/**
+ * Register a shortcut
+ * @param key - The shortcut combination
+ * @param func - The trigger function
+ * @returns Whether the shortcut is registered successfully
+ */
+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
 
-    channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
+  channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
 
-    return true;
+  return true
 }
 
-export function regFeature(feature: IPluginFeature): boolean {
+/**
+ * Communicate with other plugins via the index:communicate channel
+ * @param key - The message key
+ * @param info - The message data
+ * @returns Promise<any> The communication result
+ */
+export async function communicateWithPlugin(
+  key: string,
+  info: any = {}
+): Promise<any> {
   const channel = genChannel()
 
-  return channel.sendSync('feature:reg', { feature })
+  try {
+    return await channel.send('index:communicate', {
+      key,
+      info
+    })
+  } catch (error) {
+    console.error(`[Plugin SDK] Failed to communicate`, error)
+    throw error
+  }
 }
 
-export function unRegFeature(id: string): boolean {
+/**
+ * Send a message to the main application
+ * @param message - The message type
+ * @param data - The message data
+ * @returns Promise<any> The message result
+ */
+export async function sendMessage(message: string, data: any = {}): Promise<any> {
   const channel = genChannel()
 
-  return channel.sendSync('feature:unreg', { feature: id })
+  try {
+    return await channel.send(`plugin:${message}`, data)
+  } catch (error) {
+    console.error(`[Plugin SDK] Failed to send message: ${message}`, error)
+    throw error
+  }
+}
+
+/**
+ * Get the channel object for the plugin
+ * Attention: Using this function make sure you know what you are doing.
+ * @returns The channel object for the plugin
+ */
+export function getChannel() {
+  return genChannel()
 }
 
-export * from './window';
+export * from './window'

package/plugin/sdk/core-box.ts

@@ -0,0 +1,27 @@
+import type { IPluginRendererChannel } from './types'
+
+const 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.')
+  }
+
+  const channel = (window as any)?.$channel as IPluginRendererChannel | undefined
+  if (!channel) {
+    throw new Error('[TouchSDK] Channel bridge is not available for the current plugin renderer.')
+  }
+
+  return {
+    channel,
+    pluginName: plugin.name as string
+  }
+}
+
+/**
+ * Clears all CoreBox items associated with the current plugin.
+ */
+export async function clearCoreBoxItems(): Promise<void> {
+  const { channel, pluginName } = ensurePluginContext()
+  await channel.send('core-box:clear-items', { pluginName })
+}
+