autosnippet 3.2.8 → 3.2.10

package/lib/service/agent/AgentMessage.js

@@ -0,0 +1,240 @@
+/**
+ * AgentMessage — 统一消息信封
+ *
+ * 核心抽象: Agent 永远不需要知道消息来自哪个渠道。
+ * Transport 适配器负责将渠道特定格式转换为 AgentMessage,
+ * Agent 只处理 AgentMessage, 通过 replyFn 返回结果。
+ *
+ * 这是将"飞书聊天"和"前端聊天"统一为同一概念的关键:
+ *   - HTTP/SSE (Dashboard)  → AgentMessage { channel: 'http', ... }
+ *   - WebSocket (Lark/飞书)  → AgentMessage { channel: 'lark', ... }
+ *   - CLI (终端)             → AgentMessage { channel: 'cli',  ... }
+ *   - MCP (IDE 扩展)         → AgentMessage { channel: 'mcp',  ... }
+ *
+ * @module AgentMessage
+ */
+
+import { randomUUID } from 'node:crypto';
+
+/**
+ * 通信渠道枚举
+ */
+export const Channel = Object.freeze({
+  HTTP: 'http',
+  LARK: 'lark',
+  CLI: 'cli',
+  MCP: 'mcp',
+  INTERNAL: 'internal', // Agent 间通信
+});
+
+/**
+ * @typedef {Object} Sender
+ * @property {string} id — 发送者唯一标识
+ * @property {string} [name] — 显示名
+ * @property {'user'|'system'|'agent'} type — 发送者类型
+ */
+
+/**
+ * @typedef {Object} Session
+ * @property {string} id — 会话 ID
+ * @property {Array<{role: string, content: string}>} [history] — 对话历史
+ */
+
+export class AgentMessage {
+  /** @type {string} 消息唯一 ID */
+  id;
+  /** @type {string} 用户输入内容 */
+  content;
+  /** @type {string} 通信渠道 */
+  channel;
+  /** @type {Session} 会话信息 */
+  session;
+  /** @type {Sender} 发送者 */
+  sender;
+  /** @type {Record<string, any>} 渠道特定元数据 */
+  metadata;
+  /** @type {Function|null} 回复函数 (text: string) => Promise<void> */
+  replyFn;
+  /** @type {number} 时间戳 */
+  timestamp;
+
+  /**
+   * @param {Object} opts
+   * @param {string} opts.content — 用户输入
+   * @param {string} [opts.channel='http'] — 渠道
+   * @param {Session} [opts.session] — 会话
+   * @param {Sender} [opts.sender] — 发送者
+   * @param {Record<string, any>} [opts.metadata] — 元数据
+   * @param {Function} [opts.replyFn] — 回复函数
+   */
+  constructor({ content, channel = Channel.HTTP, session, sender, metadata, replyFn } = {}) {
+    this.id = randomUUID();
+    this.content = content || '';
+    this.channel = channel;
+    this.session = session || { id: randomUUID(), history: [] };
+    this.sender = sender || { id: 'anonymous', type: 'user' };
+    this.metadata = metadata || {};
+    this.replyFn = replyFn || null;
+    this.timestamp = Date.now();
+  }
+
+  /** 对话历史 (快捷访问) */
+  get history() {
+    return this.session.history || [];
+  }
+
+  /**
+   * 向发送方回复
+   * @param {string} text
+   */
+  async reply(text) {
+    if (this.replyFn) await this.replyFn(text);
+  }
+
+  // ─── Transport 工厂方法 ─────────────────────
+
+  /**
+   * 从 HTTP 请求构建
+   * @param {Object} req — Express request
+   * @param {Function} [replyFn] — SSE 或 JSON 回复
+   */
+  static fromHttp(req, replyFn) {
+    const body = req.body || {};
+    return new AgentMessage({
+      content: body.prompt || body.message || body.content || '',
+      channel: Channel.HTTP,
+      session: {
+        id: body.conversationId || body.sessionId || randomUUID(),
+        history: body.history || [],
+      },
+      sender: {
+        id: body.userId || req.ip || 'http-user',
+        name: body.userName,
+        type: 'user',
+      },
+      metadata: {
+        lang: body.lang,
+        mode: body.mode,       // 手动指定 preset
+        context: body.context, // 额外上下文
+        stream: body.stream ?? true,
+      },
+      replyFn,
+    });
+  }
+
+  /**
+   * 从飞书消息构建
+   * @param {Object} larkMsg — 飞书消息对象
+   * @param {Function} replyFn — 飞书回复函数
+   */
+  static fromLark(larkMsg, replyFn) {
+    return new AgentMessage({
+      content: larkMsg.text || larkMsg.content || '',
+      channel: Channel.LARK,
+      session: {
+        id: larkMsg.chatId || randomUUID(),
+        history: [],
+      },
+      sender: {
+        id: larkMsg.senderId || larkMsg.userId || 'lark-user',
+        name: larkMsg.senderName,
+        type: 'user',
+      },
+      metadata: {
+        messageId: larkMsg.messageId,
+        chatId: larkMsg.chatId,
+        messageType: larkMsg.messageType,
+        // 飞书特有字段透传
+        raw: larkMsg,
+      },
+      replyFn,
+    });
+  }
+
+  /**
+   * 从 CLI 输入构建
+   * @param {string} input — 命令行输入
+   * @param {Object} [opts]
+   */
+  static fromCli(input, opts = {}) {
+    return new AgentMessage({
+      content: input,
+      channel: Channel.CLI,
+      session: { id: opts.sessionId || 'cli-session', history: opts.history || [] },
+      sender: { id: 'cli-user', type: 'user' },
+      metadata: {
+        cwd: opts.cwd || process.cwd(),
+        mode: opts.mode,
+        ...opts.metadata,
+      },
+    });
+  }
+
+  /**
+   * Agent 间内部消息
+   * @param {string} content — 消息内容
+   * @param {Object} [opts]
+   */
+  static internal(content, opts = {}) {
+    return new AgentMessage({
+      content,
+      channel: Channel.INTERNAL,
+      session: opts.session || { id: opts.sessionId || randomUUID(), history: opts.history || [] },
+      sender: {
+        id: opts.sourceAgentId || 'system',
+        type: 'agent',
+      },
+      metadata: {
+        parentAgentId: opts.parentAgentId,
+        dimension: opts.dimension,
+        phase: opts.phase,
+        ...opts.metadata,
+      },
+    });
+  }
+
+  /**
+   * 从 MCP 请求构建
+   * @param {Object} mcpReq — MCP tool call request
+   * @param {Function} [replyFn] — 回复函数
+   */
+  static fromMcp(mcpReq, replyFn) {
+    return new AgentMessage({
+      content: mcpReq.prompt || mcpReq.content || mcpReq.arguments?.prompt || '',
+      channel: Channel.MCP,
+      session: {
+        id: mcpReq.sessionId || randomUUID(),
+        history: mcpReq.history || [],
+      },
+      sender: {
+        id: mcpReq.clientId || 'mcp-client',
+        name: mcpReq.clientName,
+        type: 'user',
+      },
+      metadata: {
+        toolName: mcpReq.toolName,
+        arguments: mcpReq.arguments,
+        mode: mcpReq.mode,
+        ...mcpReq.metadata,
+      },
+      replyFn,
+    });
+  }
+
+  /**
+   * 序列化
+   */
+  toJSON() {
+    return {
+      id: this.id,
+      content: this.content,
+      channel: this.channel,
+      session: { id: this.session.id, historyLength: this.history.length },
+      sender: this.sender,
+      metadata: this.metadata,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+export default AgentMessage;

package/lib/service/agent/AgentRouter.js

@@ -0,0 +1,228 @@
+/**
+ * AgentRouter — Intent → Preset 解析器
+ *
+ * 在统一架构下，Router 的职责简化为:
+ *   - 理解用户意图 (intent classification)
+ *   - 映射到正确的 Preset (配置组合)
+ *   - 创建 AgentRuntime 并执行
+ *
+ * 路由策略 (优先级递减):
+ *   1. 手动指定 (API `preset` 参数)
+ *   2. 渠道特征 (如飞书终端命令以 > 开头 → remote-exec)
+ *   3. 关键词匹配 (零延迟正则)
+ *   4. LLM 意图分类 (精确但需 AI 调用)
+ *   5. 默认 → chat
+ *
+ * 关键区别 (vs 旧 AgentRouter):
+ *   - 旧版路由到 AgentMode (chat/bootstrap/scan/lark_bridge) → 4 种 Agent 类型
+ *   - 新版路由到 Preset (chat/insight/remote-exec) → 同一 Runtime 的不同配置
+ *   - 不再存在 "LarkBridge" 模式 — 飞书和前端共享同一 Preset
+ *
+ * @module AgentRouter
+ */
+
+import Logger from '../../infrastructure/logging/Logger.js';
+import { AgentEventBus, AgentEvents } from './AgentEventBus.js';
+import { Channel } from './AgentMessage.js';
+
+/**
+ * Preset 名称枚举
+ */
+export const PresetName = Object.freeze({
+  CHAT: 'chat',
+  INSIGHT: 'insight',
+  LARK: 'lark',
+  REMOTE_EXEC: 'remote-exec',
+});
+
+/**
+ * 关键词 → Preset 映射 (零延迟快速路径)
+ */
+const KEYWORD_ROUTES = [
+  {
+    preset: PresetName.INSIGHT,
+    keywords: [
+      /冷启动|cold[\s-]?start|初始化知识库|bootstrap/i,
+      /重建知识库|rebuild.*knowledge/i,
+      /全项目.*分析|analyze.*entire.*project/i,
+      /扫描|scan|分析.*目录|分析.*文件夹|analyze.*folder/i,
+      /检查.*target|审计.*模块|audit.*module/i,
+      /深度分析.*路径|知识提取/i,
+    ],
+  },
+  {
+    preset: PresetName.REMOTE_EXEC,
+    keywords: [
+      /^[>$]\s*/,  // 以 > 或 $ 开头 = 终端命令
+      /运行命令|执行命令|run.*command|exec.*command/i,
+    ],
+  },
+];
+
+/**
+ * LLM 路由分类 Schema
+ */
+const ROUTE_CLASSIFICATION_SCHEMA = {
+  name: 'classify_intent',
+  description: 'Classify user intent to determine which agent preset to use',
+  parameters: {
+    type: 'object',
+    properties: {
+      preset: {
+        type: 'string',
+        enum: ['chat', 'insight', 'lark', 'remote-exec'],
+        description: 'The preset to route to. chat=conversation, insight=code analysis and knowledge extraction, lark=Lark knowledge management, remote-exec=terminal commands',
+      },
+      confidence: {
+        type: 'number',
+        description: 'Confidence score 0-1',
+      },
+      reasoning: {
+        type: 'string',
+        description: 'Brief reasoning for the classification',
+      },
+    },
+    required: ['preset', 'confidence'],
+  },
+};
+
+export class AgentRouter {
+  #logger;
+  #bus;
+  /** @type {import('../../external/ai/AiProvider.js').AiProvider|null} */
+  #aiProvider = null;
+  /** @type {Function|null} — (presetName, message, opts) => Promise<AgentResult> */
+  #executor = null;
+
+  constructor() {
+    this.#logger = Logger.getInstance();
+    this.#bus = AgentEventBus.getInstance();
+  }
+
+  /**
+   * 设置 AI Provider (用于 LLM 路由)
+   * @param {import('../../external/ai/AiProvider.js').AiProvider} provider
+   */
+  setAiProvider(provider) {
+    this.#aiProvider = provider;
+  }
+
+  /**
+   * 设置执行器 — Factory 提供的 (presetName, message, opts) => AgentResult
+   * @param {Function} executor
+   */
+  setExecutor(executor) {
+    this.#executor = executor;
+  }
+
+  /**
+   * 路由并执行
+   *
+   * @param {import('./AgentMessage.js').AgentMessage} message — 统一消息
+   * @param {Object} [opts]
+   * @param {string} [opts.preset] — 手动指定 Preset (跳过路由)
+   * @param {Object} [opts.strategyOpts] — 策略特定选项 (如 FanOut 的 items)
+   * @returns {Promise<{preset: string, result: Object}>}
+   */
+  async route(message, opts = {}) {
+    // 1. 手动指定
+    let preset = opts.preset || message.metadata?.mode;
+
+    // 2. 渠道特征路由
+    if (!preset) {
+      preset = this.#matchChannel(message);
+      if (preset) this.#logger.info(`[AgentRouter] Channel match → ${preset}`);
+    }
+
+    // 3. 关键词匹配
+    if (!preset) {
+      preset = this.#matchKeyword(message.content);
+      if (preset) this.#logger.info(`[AgentRouter] Keyword match → ${preset}`);
+    }
+
+    // 4. LLM 分类
+    if (!preset && this.#aiProvider) {
+      preset = await this.#classifyWithLLM(message.content);
+      if (preset) this.#logger.info(`[AgentRouter] LLM classification → ${preset}`);
+    }
+
+    // 5. 默认 → chat
+    if (!preset) preset = PresetName.CHAT;
+
+    // 执行
+    if (!this.#executor) {
+      throw new Error('[AgentRouter] No executor set. Call setExecutor() first.');
+    }
+
+    this.#logger.info(`[AgentRouter] Dispatching → preset="${preset}" channel=${message.channel}`);
+
+    const result = await this.#executor(preset, message, opts);
+    return { preset, result };
+  }
+
+  /**
+   * 仅分类意图，不执行
+   * @param {import('./AgentMessage.js').AgentMessage} message
+   * @returns {Promise<string>} preset name
+   */
+  async classify(message) {
+    let preset = message.metadata?.mode;
+    if (!preset) preset = this.#matchChannel(message);
+    if (!preset) preset = this.#matchKeyword(message.content);
+    if (!preset && this.#aiProvider) preset = await this.#classifyWithLLM(message.content);
+    return preset || PresetName.CHAT;
+  }
+
+  // ─── 私有方法 ────────────────────────────────
+
+  /**
+   * 渠道特征路由
+   * 飞书消息默认 → lark preset (知识管理对话)
+   * 飞书终端命令 (> 开头) → remote-exec    
+   */
+  #matchChannel(message) {
+    if (message.channel === Channel.LARK) {
+      const text = message.content.trim();
+      // 飞书消息以 > 或 $ 开头 → 终端命令
+      if (/^[>$]\s*/.test(text)) return PresetName.REMOTE_EXEC;
+      // 默认走 lark preset (知识管理对话)
+      return PresetName.LARK;
+    }
+    return null;
+  }
+
+  #matchKeyword(prompt) {
+    for (const route of KEYWORD_ROUTES) {
+      for (const re of route.keywords) {
+        if (re.test(prompt)) return route.preset;
+      }
+    }
+    return null;
+  }
+
+  async #classifyWithLLM(prompt) {
+    try {
+      const result = await this.#aiProvider.chatWithTools(
+        `Classify this user message into the correct preset: "${prompt.slice(0, 300)}"`,
+        {
+          messages: [],
+          toolSchemas: [ROUTE_CLASSIFICATION_SCHEMA],
+        toolChoice: 'required',
+          systemPrompt: 'You classify user intents for an AI coding assistant. Respond by calling the classify_intent function.',
+          temperature: 0,
+          maxTokens: 200,
+        }
+      );
+
+      if (result.functionCalls?.[0]?.args?.preset) {
+        const classified = result.functionCalls[0].args;
+        if (classified.confidence > 0.6) return classified.preset;
+      }
+    } catch (err) {
+      this.#logger.warn(`[AgentRouter] LLM classification failed: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+export default AgentRouter;