@maidang1/hataraku 0.0.3

package/src/core/internal/integrations/mcp/index.ts

@@ -0,0 +1,197 @@
+import type Anthropic from "@anthropic-ai/sdk";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Tool as McpToolDefinition } from "@modelcontextprotocol/sdk/types.js";
+import { getEffectiveConfig, type McpServerConfig } from "../../config";
+import { Tool } from "../../tools/base";
+import type { ToolExecutionContext } from "../../tools/base";
+import { ConnectionManager } from "./connection-manager";
+import { McpToolCache } from "./tool-cache";
+import { ConnectionState } from "./types";
+import { MCP_CONSTANTS, normalizeError, createTimeoutPromise } from "./utils";
+
+class McpTool extends Tool {
+  name: string;
+  description: string;
+  readonly = false;
+  private client: Client;
+  private toolName: string;
+  private inputSchema: Anthropic.Tool["input_schema"];
+  private config: McpServerConfig;
+
+  constructor(params: {
+    serverName: string;
+    tool: McpToolDefinition;
+    client: Client;
+    config: McpServerConfig;
+  }) {
+    super();
+    const { serverName, tool, client, config } = params;
+    this.name = `${serverName}.${tool.name}`;
+    this.description = tool.description ?? `MCP tool ${tool.name} from ${serverName}`;
+    this.client = client;
+    this.toolName = tool.name;
+    this.config = config;
+    this.inputSchema =
+      (tool.inputSchema as Anthropic.Tool["input_schema"]) ?? {
+        type: "object",
+        properties: {},
+      };
+  }
+
+  getSchema(): Anthropic.Tool {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: this.inputSchema,
+    };
+  }
+
+  async execute(
+    input: Record<string, unknown>,
+    _context: ToolExecutionContext,
+  ): Promise<string> {
+    const timeoutMs = this.config.toolTimeoutSec
+      ? this.config.toolTimeoutSec * 1000
+      : MCP_CONSTANTS.DEFAULT_TOOL_TIMEOUT_SEC * 1000;
+
+    const result = await Promise.race([
+      this.client.callTool({
+        name: this.toolName,
+        arguments: input ?? {},
+      }),
+      createTimeoutPromise(timeoutMs, `Tool execution timeout after ${timeoutMs}ms`),
+    ]);
+
+    return formatToolResult(result);
+  }
+}
+
+function formatToolResult(result: unknown): string {
+  if (!result) return "";
+
+  const resultObj = result as Record<string, unknown>;
+  const content = resultObj.content ?? result;
+
+  if (typeof content === "string") return content;
+
+  if (Array.isArray(content)) {
+    const parts = content.map((part: unknown) => {
+      const partObj = part as Record<string, unknown> | null;
+      if (partObj?.type === "text" && typeof partObj.text === "string") {
+        return partObj.text;
+      }
+      return JSON.stringify(part, null, 2);
+    });
+    return parts.join("\n");
+  }
+
+  return JSON.stringify(content, null, 2);
+}
+
+/**
+ * 过滤工具列表
+ */
+function filterTools(
+  tools: McpToolDefinition[],
+  config: McpServerConfig
+): McpToolDefinition[] {
+  let filtered = tools;
+
+  // 白名单过滤
+  if (config.enabledTools && config.enabledTools.length > 0) {
+    filtered = filtered.filter((tool) =>
+      config.enabledTools!.includes(tool.name)
+    );
+  }
+
+  // 黑名单过滤
+  if (config.disabledTools && config.disabledTools.length > 0) {
+    filtered = filtered.filter((tool) =>
+      !config.disabledTools!.includes(tool.name)
+    );
+  }
+
+  return filtered;
+}
+
+export async function loadMcpTools(
+  mcpServersOverride?: Record<string, McpServerConfig>,
+  hooks?: {
+    onServerConnectStart?: (serverName: string) => void;
+    onServerConnectSuccess?: (serverName: string, toolCount: number) => void;
+    onServerConnectError?: (serverName: string, error: Error) => void;
+    onReconnectAttempt?: (serverName: string, attempt: number, maxRetries: number) => void;
+    onHealthCheck?: (serverName: string, latency: number, healthy: boolean) => void;
+    onCacheHit?: (serverName: string) => void;
+  }
+): Promise<{
+  tools: Tool[];
+  cleanup: () => Promise<void>;
+  connectionManager: ConnectionManager;
+}> {
+  const { mcpServers } = getEffectiveConfig();
+  const mcpServersToUse = mcpServersOverride ?? mcpServers;
+  const tools: Tool[] = [];
+  const connectionManager = new ConnectionManager();
+  const toolCache = new McpToolCache();
+
+  // 设置事件监听
+  connectionManager.on("reconnectAttempt", (serverName, attempt, maxRetries) => {
+    hooks?.onReconnectAttempt?.(serverName, attempt, maxRetries);
+  });
+
+  connectionManager.on("healthCheckCompleted", (serverName, latency, healthy) => {
+    hooks?.onHealthCheck?.(serverName, latency, healthy);
+  });
+
+  const serverEntries = Object.entries(mcpServersToUse);
+  for (const [serverName, config] of serverEntries) {
+    // 检查是否启用
+    if (config.enabled === false) {
+      continue;
+    }
+
+    try {
+      hooks?.onServerConnectStart?.(serverName);
+
+      // 连接到服务器
+      const client = await connectionManager.connect(serverName, config);
+
+      // 尝试从缓存获取工具列表
+      let serverTools = toolCache.get(serverName);
+      if (serverTools) {
+        hooks?.onCacheHit?.(serverName);
+      } else {
+        // 从服务器获取工具列表
+        const result = await client.listTools();
+        serverTools = result.tools ?? [];
+        toolCache.set(serverName, serverTools);
+      }
+
+      // 过滤工具
+      const filteredTools = filterTools(serverTools, config);
+
+      // 创建工具实例
+      for (const tool of filteredTools) {
+        tools.push(new McpTool({ serverName, tool, client, config }));
+      }
+
+      hooks?.onServerConnectSuccess?.(serverName, filteredTools.length);
+    } catch (error) {
+      const err = normalizeError(error);
+      console.warn(`Failed to load MCP server "${serverName}": ${err.message}`);
+      hooks?.onServerConnectError?.(serverName, err);
+    }
+  }
+
+  const cleanup = async () => {
+    toolCache.stopCleanup();
+    await connectionManager.disconnectAll();
+  };
+
+  return { tools, cleanup, connectionManager };
+}
+
+// 导出类型和工具
+export { ConnectionManager, McpToolCache, ConnectionState };
+export type { McpServerConfig };

package/src/core/internal/integrations/mcp/retry-strategy.ts

@@ -0,0 +1,111 @@
+import type { RetryConfig } from "./types";
+import { ErrorType } from "./types";
+import { MCP_CONSTANTS, normalizeError } from "./utils";
+
+/**
+ * 可重试错误的正则模式
+ */
+const RETRYABLE_PATTERNS =
+  /econnrefused|etimedout|enotfound|socket hang up|network error|connection timeout|connection reset/i;
+
+/**
+ * 不可重试错误的正则模式
+ */
+const NON_RETRYABLE_PATTERNS =
+  /unauthorized|forbidden|authentication|invalid config|protocol error/i;
+
+/**
+ * 重试策略 - 使用指数退避算法
+ */
+export class RetryStrategy {
+  private config: RetryConfig;
+
+  constructor(config?: Partial<RetryConfig>) {
+    this.config = {
+      maxRetries: config?.maxRetries ?? MCP_CONSTANTS.DEFAULT_MAX_RETRIES,
+      initialDelay: config?.initialDelay ?? MCP_CONSTANTS.DEFAULT_INITIAL_RETRY_DELAY_MS,
+      maxDelay: config?.maxDelay ?? MCP_CONSTANTS.DEFAULT_MAX_RETRY_DELAY_MS,
+      jitterFactor: config?.jitterFactor ?? MCP_CONSTANTS.DEFAULT_JITTER_FACTOR,
+    };
+  }
+
+  /**
+   * 计算下次重试的延迟时间（毫秒）
+   * 使用指数退避算法：delay = min(initialDelay * 2^attempt, maxDelay) + jitter
+   */
+  getDelay(attempt: number): number {
+    const exponentialDelay = this.config.initialDelay * Math.pow(2, attempt);
+    const cappedDelay = Math.min(exponentialDelay, this.config.maxDelay);
+
+    // 添加抖动避免雷鸣群效应
+    const jitter = cappedDelay * this.config.jitterFactor * Math.random();
+
+    return Math.floor(cappedDelay + jitter);
+  }
+
+  /**
+   * 判断是否应该重试
+   */
+  shouldRetry(attempt: number, error: Error): boolean {
+    if (attempt >= this.config.maxRetries) {
+      return false;
+    }
+
+    return this.classifyError(error) === ErrorType.RETRYABLE;
+  }
+
+  /**
+   * 分类错误类型
+   */
+  private classifyError(error: Error): ErrorType {
+    const message = error.message;
+
+    // 可重试的网络错误
+    if (RETRYABLE_PATTERNS.test(message)) {
+      return ErrorType.RETRYABLE;
+    }
+
+    // 不可重试的错误
+    if (NON_RETRYABLE_PATTERNS.test(message)) {
+      return ErrorType.NON_RETRYABLE;
+    }
+
+    // 默认可重试
+    return ErrorType.RETRYABLE;
+  }
+
+  /**
+   * 执行带重试的操作
+   */
+  async executeWithRetry<T>(
+    operation: () => Promise<T>,
+    onRetry?: (attempt: number, delay: number) => void
+  ): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        const err = normalizeError(error);
+        lastError = err;
+
+        if (!this.shouldRetry(attempt, err)) {
+          throw err;
+        }
+
+        if (attempt < this.config.maxRetries) {
+          const delay = this.getDelay(attempt);
+          onRetry?.(attempt + 1, delay);
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError ?? new Error("Operation failed after retries");
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/core/internal/integrations/mcp/tool-cache.ts

@@ -0,0 +1,103 @@
+import type { Tool as McpToolDefinition } from "@modelcontextprotocol/sdk/types.js";
+import { MCP_CONSTANTS } from "./utils";
+
+/**
+ * MCP 工具缓存项
+ */
+interface CacheEntry {
+  tools: McpToolDefinition[];
+  timestamp: number;
+}
+
+/**
+ * MCP 工具缓存
+ * 缓存 MCP 服务器的工具列表，减少重复的 listTools 调用
+ */
+export class McpToolCache {
+  private cache: Map<string, CacheEntry> = new Map();
+  private ttl: number; // TTL in milliseconds
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor(ttlMinutes: number = MCP_CONSTANTS.DEFAULT_TOOL_CACHE_TTL_MINUTES) {
+    this.ttl = ttlMinutes * 60 * 1000;
+    this.startCleanup();
+  }
+
+  /**
+   * 获取缓存的工具列表
+   */
+  get(serverName: string): McpToolDefinition[] | null {
+    const entry = this.cache.get(serverName);
+    if (!entry) {
+      return null;
+    }
+
+    const now = Date.now();
+    if (now - entry.timestamp > this.ttl) {
+      // 缓存过期
+      this.cache.delete(serverName);
+      return null;
+    }
+
+    return entry.tools;
+  }
+
+  /**
+   * 设置缓存
+   */
+  set(serverName: string, tools: McpToolDefinition[]): void {
+    this.cache.set(serverName, {
+      tools,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * 使缓存失效
+   */
+  invalidate(serverName: string): void {
+    this.cache.delete(serverName);
+  }
+
+  /**
+   * 清空所有缓存
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * 启动自动清理过期缓存
+   */
+  private startCleanup(): void {
+    // 每分钟清理一次过期缓存
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now();
+      for (const [serverName, entry] of this.cache.entries()) {
+        if (now - entry.timestamp > this.ttl) {
+          this.cache.delete(serverName);
+        }
+      }
+    }, MCP_CONSTANTS.CACHE_CLEANUP_INTERVAL_MS);
+  }
+
+  /**
+   * 停止自动清理
+   */
+  stopCleanup(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+
+  /**
+   * 获取缓存统计信息
+   */
+  getStats(): { size: number; entries: string[] } {
+    return {
+      size: this.cache.size,
+      entries: Array.from(this.cache.keys()),
+    };
+  }
+}

package/src/core/internal/integrations/mcp/transport.ts

@@ -0,0 +1,58 @@
+import { URL } from "url";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpServerConfig } from "./types";
+import { MCP_CONSTANTS, createTimeoutPromise } from "./utils";
+
+/**
+ * 创建传输层
+ */
+export function createTransport(config: McpServerConfig): Transport {
+  if (config.command) {
+    return new StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env: config.env,
+      cwd: config.cwd,
+    });
+  }
+
+  if (config.url) {
+    const headers = { ...config.headers };
+
+    // 添加认证 header
+    if (config.auth) {
+      if (config.auth.type === "bearer" && config.auth.token) {
+        headers["Authorization"] = `Bearer ${config.auth.token}`;
+      } else if (config.auth.type === "basic" && config.auth.username && config.auth.password) {
+        const credentials = Buffer.from(
+          `${config.auth.username}:${config.auth.password}`
+        ).toString("base64");
+        headers["Authorization"] = `Basic ${credentials}`;
+      }
+      // OAuth 需要更复杂的实现，暂时不支持
+    }
+
+    return new StreamableHTTPClientTransport(new URL(config.url), {
+      requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+    });
+  }
+
+  throw new Error("MCP server config must include command or url.");
+}
+
+/**
+ * 带超时的连接
+ */
+export async function connectWithTimeout(
+  client: Client,
+  transport: Transport,
+  timeoutSec: number = MCP_CONSTANTS.DEFAULT_STARTUP_TIMEOUT_SEC
+): Promise<void> {
+  await Promise.race([
+    client.connect(transport),
+    createTimeoutPromise(timeoutSec * 1000, `Connection timeout after ${timeoutSec}s`),
+  ]);
+}

package/src/core/internal/integrations/mcp/types.ts

@@ -0,0 +1,95 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+/**
+ * MCP 服务器配置
+ */
+export interface McpServerConfig {
+  // 传输方式配置
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  cwd?: string;
+  url?: string;
+  headers?: Record<string, string>;
+
+  // 启用/禁用控制
+  enabled?: boolean; // 默认 true
+
+  // 超时配置
+  startupTimeoutSec?: number; // 启动超时（默认 30s）
+  toolTimeoutSec?: number; // 工具调用超时（默认 60s）
+
+  // 工具过滤
+  enabledTools?: string[]; // 工具白名单
+  disabledTools?: string[]; // 工具黑名单
+
+  // 重连配置
+  maxRetries?: number; // 最大重试次数（默认 3）
+  retryDelay?: number; // 初始重试延迟（默认 1000ms）
+
+  // 健康检查配置
+  healthCheckInterval?: number; // 健康检查间隔（默认 60000ms）
+
+  // 认证配置
+  auth?: {
+    type: "bearer" | "oauth" | "basic";
+    token?: string;
+    username?: string;
+    password?: string;
+  };
+}
+
+/**
+ * 连接状态
+ */
+export enum ConnectionState {
+  DISCONNECTED = "DISCONNECTED",
+  CONNECTING = "CONNECTING",
+  CONNECTED = "CONNECTED",
+  RECONNECTING = "RECONNECTING",
+  FAILED = "FAILED",
+}
+
+/**
+ * 管理的连接
+ */
+export interface ManagedConnection {
+  serverName: string;
+  client: Client;
+  transport: Transport;
+  config: McpServerConfig;
+  state: ConnectionState;
+  lastError?: Error;
+  retryCount: number;
+  connectedAt?: Date;
+  lastHealthCheck?: Date;
+}
+
+/**
+ * 连接事件
+ */
+export interface ConnectionEvents {
+  connectionStateChanged: (serverName: string, state: ConnectionState) => void;
+  connectionError: (serverName: string, error: Error) => void;
+  reconnectAttempt: (serverName: string, attempt: number, maxRetries: number) => void;
+  healthCheckCompleted: (serverName: string, latency: number, healthy: boolean) => void;
+}
+
+/**
+ * 重试策略配置
+ */
+export interface RetryConfig {
+  maxRetries: number;
+  initialDelay: number;
+  maxDelay: number;
+  jitterFactor: number;
+}
+
+/**
+ * 错误类型
+ */
+export enum ErrorType {
+  RETRYABLE = "RETRYABLE",
+  NON_RETRYABLE = "NON_RETRYABLE",
+}

package/src/core/internal/integrations/mcp/utils.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP 模块共享常量
+ */
+export const MCP_CONSTANTS = {
+  DEFAULT_CLIENT_NAME: "hataraku",
+  DEFAULT_CLIENT_VERSION: "1.0.0",
+  DEFAULT_STARTUP_TIMEOUT_SEC: 30,
+  DEFAULT_TOOL_TIMEOUT_SEC: 60,
+  DEFAULT_MAX_RETRIES: 3,
+  DEFAULT_INITIAL_RETRY_DELAY_MS: 1000,
+  DEFAULT_MAX_RETRY_DELAY_MS: 30000,
+  DEFAULT_JITTER_FACTOR: 0.1,
+  DEFAULT_TOOL_CACHE_TTL_MINUTES: 5,
+  DEFAULT_HEALTH_CHECK_INTERVAL_MS: 60000,
+  CACHE_CLEANUP_INTERVAL_MS: 60000,
+} as const;
+
+/**
+ * 将未知错误规范化为 Error 对象
+ * @param error 未知错误
+ * @param context 可选的上下文信息
+ */
+export function normalizeError(error: unknown, context?: string): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  const message = context
+    ? `${context}: ${String(error)}`
+    : `Unknown error: ${String(error)}`;
+
+  return new Error(message);
+}
+
+/**
+ * 创建超时 Promise
+ * @param ms 超时时间（毫秒）
+ * @param message 超时错误消息
+ */
+export function createTimeoutPromise(ms: number, message: string): Promise<never> {
+  return new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error(message)), ms)
+  );
+}

package/src/core/internal/integrations/skills/cache/index.ts

@@ -0,0 +1,38 @@
+import type { ICache } from "./interface";
+import type { SkillLoadOutcome } from "../core/types";
+import { MemoryCache } from "./memory-cache";
+
+export type { ICache };
+export { MemoryCache };
+
+export class CacheManager {
+  private cache: ICache;
+
+  constructor(ttl: number = 300000, enabled: boolean = true) {
+    this.cache = new MemoryCache(ttl, enabled);
+  }
+
+  public get(key: string): SkillLoadOutcome | null {
+    return this.cache.get(key);
+  }
+
+  public set(key: string, value: SkillLoadOutcome): void {
+    this.cache.set(key, value);
+  }
+
+  public has(key: string): boolean {
+    return this.cache.has(key);
+  }
+
+  public delete(key: string): void {
+    this.cache.delete(key);
+  }
+
+  public clear(): void {
+    this.cache.clear();
+  }
+
+  public setCache(cache: ICache): void {
+    this.cache = cache;
+  }
+}

package/src/core/internal/integrations/skills/cache/interface.ts

@@ -0,0 +1,9 @@
+import type { SkillLoadOutcome } from "../core/types";
+
+export interface ICache {
+  get(key: string): SkillLoadOutcome | null;
+  set(key: string, value: SkillLoadOutcome): void;
+  has(key: string): boolean;
+  delete(key: string): void;
+  clear(): void;
+}