refactor(tools): add ToolDataProvider interface and async handler support

Prepare @openchatlab/tools for unified tool layer:
- ToolDefinition.handler now supports async (ToolResult | Promise<ToolResult>)
- Add ToolDataProvider abstraction interface for platform-agnostic data access
- Add TimeFilter, ToolCategory, TruncationStrategy types
- Update Server consumers (tool-adapter, mcp) to await handler results

packages/server/src/ai/tool-adapter.ts

@@ -102,7 +102,7 @@ export function adaptToolsForAgent(
         locale: ctx.locale,
       }
       try {
-        const result = tool.handler(params, execCtx)
+        const result = await tool.handler(params, execCtx)
 
         if (result.rawMessages && result.rawMessages.length > 0) {
           const textContent = applyPreprocessing(

packages/server/src/mcp.ts

@@ -87,7 +87,7 @@ export async function startMcpServer(): Promise<void> {
           listSessionIds: () => dbManager.listSessionIds(),
           openDb: (id) => dbManager.open(id),
         }
-        const result = tool.handler(params as Record<string, unknown>, context)
+        const result = await tool.handler(params as Record<string, unknown>, context)
         return { content: [{ type: 'text' as const, text: result.content }] }
       })
       continue
@@ -112,7 +112,7 @@ export async function startMcpServer(): Promise<void> {
       const toolParams = { ...params } as Record<string, unknown>
       delete toolParams.session_id
 
-      const result = tool.handler(toolParams, { db, sessionId })
+      const result = await tool.handler(toolParams, { db, sessionId })
       return { content: [{ type: 'text' as const, text: result.content }] }
     })
   }

packages/tools/src/index.ts

@@ -6,4 +6,17 @@
  */
 
 export { TOOL_REGISTRY, getToolByName } from './registry'
-export type { ToolDefinition, ToolExecutionContext, ToolResult, JsonSchema } from './types'
+export type {
+  ToolDefinition,
+  ToolExecutionContext,
+  ToolResult,
+  JsonSchema,
+  RawMessage,
+  ToolDataProvider,
+  SearchMessagesResult,
+  MemberStatItem,
+  SchemaTableInfo,
+  TimeFilter,
+  ToolCategory,
+  TruncationStrategy,
+} from './types'

packages/tools/src/types.ts

@@ -6,6 +6,8 @@
 
 import type { DatabaseAdapter } from '@openchatlab/core'
 
+// ==================== Schema ====================
+
 /**
  * JSON Schema 参数定义（兼容 MCP tool input schema）
  */
@@ -26,15 +28,75 @@ export interface JsonSchema {
   required?: string[]
 }
 
+// ==================== Time Filter ====================
+
+export interface TimeFilter {
+  startTs: number
+  endTs: number
+}
+
+// ==================== Data Provider ====================
+
+export interface SearchMessagesResult {
+  messages: RawMessage[]
+  total: number
+}
+
+export interface MemberStatItem {
+  name: string
+  messageCount: number
+  percentage: number
+}
+
+export interface SchemaTableInfo {
+  name: string
+  sql: string
+}
+
+/**
+ * 工具数据查询抽象接口
+ *
+ * Server 和 Electron 各自实现：
+ * - CoreDataProvider: 通过 @openchatlab/core 查询函数 + DatabaseAdapter
+ * - WorkerDataProvider: 通过 workerManager IPC 调用 Worker 线程
+ */
+export interface ToolDataProvider {
+  searchMessages(
+    keywords: string[],
+    options?: { timeFilter?: TimeFilter; limit?: number; senderId?: number }
+  ): Promise<SearchMessagesResult>
+
+  getRecentMessages(options?: { timeFilter?: TimeFilter; limit?: number }): Promise<SearchMessagesResult>
+
+  getMemberStats(options?: { timeFilter?: TimeFilter; top?: number }): Promise<MemberStatItem[]>
+
+  getTimeStats(type: 'hourly' | 'weekday' | 'daily', options?: { timeFilter?: TimeFilter }): Promise<unknown[]>
+
+  executeSql(sql: string): Promise<unknown>
+
+  getSchema(): Promise<SchemaTableInfo[]>
+}
+
+// ==================== Tool Context ====================
+
 /**
  * 工具执行上下文
+ *
+ * 过渡期：db 保持 required 以兼容现有工具，dataProvider 为 optional。
+ * 迁移完成后 db 降为 optional / 移除。
  */
 export interface ToolExecutionContext {
-  db: DatabaseAdapter
   sessionId: string
   locale?: string
+  timeFilter?: TimeFilter
+  /** 抽象查询接口，迁移后的工具使用此字段获取数据 */
+  dataProvider?: ToolDataProvider
+  /** @deprecated 逐步迁移到 dataProvider 后移除 */
+  db: DatabaseAdapter
 }
 
+// ==================== Raw Message ====================
+
 /**
  * 可预处理的原始消息（与 @openchatlab/node-runtime PreprocessableMessage 兼容）
  */
@@ -47,6 +109,8 @@ export interface RawMessage {
   timestamp: number
 }
 
+// ==================== Tool Result ====================
+
 /**
  * 工具执行结果
  */
@@ -57,12 +121,21 @@ export interface ToolResult {
   rawMessages?: RawMessage[]
 }
 
+// ==================== Tool Definition ====================
+
+export type ToolCategory = 'core' | 'analysis'
+export type TruncationStrategy = 'keep_first' | 'keep_last'
+
 /**
  * 平台无关的工具定义
+ *
+ * handler 支持同步和异步返回，兼容 Server（同步 DB）和 Electron（异步 Worker）。
  */
 export interface ToolDefinition {
   name: string
   description: string
   inputSchema: JsonSchema
-  handler: (params: Record<string, unknown>, context: ToolExecutionContext) => ToolResult
+  handler: (params: Record<string, unknown>, context: ToolExecutionContext) => ToolResult | Promise<ToolResult>
+  category?: ToolCategory
+  truncationStrategy?: TruncationStrategy
 }