agentstudio 0.2.9 → 0.3.1

package/backend/src/services/askUserQuestion/askUserQuestionMcp.ts

@@ -0,0 +1,173 @@
+/**
+ * AskUserQuestion SDK MCP Server
+ *
+ * 实现一个进程内 MCP server，使 agent 能够向用户提问并等待回答
+ * 
+ * 新架构（事件驱动）：
+ * 1. MCP 工具调用 userInputRegistry.waitForUserInput()
+ * 2. UserInputRegistry 发出 'awaiting_input' 事件
+ * 3. NotificationChannelManager 监听事件，通过活跃渠道发送通知
+ * 4. 用户提交答案后，通过 HTTP API 触发 Promise resolve
+ * 5. MCP 工具返回用户的答案，Claude 继续执行
+ * 
+ * 优势：
+ * - MCP 工具不需要知道通知渠道
+ * - 支持多种通知渠道（SSE、Slack、企业微信等）
+ * - 连接断开重连不会影响等待中的请求
+ */
+
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { userInputRegistry } from './userInputRegistry.js';
+
+export type AskUserQuestionInput = {
+  questions: Array<{
+    question: string;
+    header: string;
+    options: Array<{
+      label: string;
+      description: string;
+    }>;
+    multiSelect: boolean;
+  }>;
+};
+
+/**
+ * Tool description for AskUserQuestion
+ */
+const TOOL_DESCRIPTION = `Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- The tool will pause execution until the user provides their answers
+- This tool supports multiple notification channels (Web, Slack, WeChat, etc.)
+
+IMPORTANT: This tool will block until the user responds. Do not call it in situations where immediate response is needed.`;
+
+/**
+ * Session reference object - allows dynamic session ID updates
+ */
+export interface SessionRef {
+  current: string;
+}
+
+/**
+ * Create SDK MCP server for AskUserQuestion tool
+ *
+ * @param sessionRef - 可更新的会话 ID 引用，用于路由用户通知
+ * @param agentId - Agent ID
+ * @returns SDK MCP server instance and session reference
+ */
+export async function createAskUserQuestionMcpServer(sessionRef: SessionRef, agentId: string) {
+  // Define the tool with session context
+  const askUserQuestionTool = tool(
+    'ask_user_question',
+    TOOL_DESCRIPTION,
+    {
+      questions: z
+        .array(
+          z.object({
+            question: z.string().describe(
+              'The complete question to ask the user. Should be clear, specific, and end with a question mark.'
+            ),
+            header: z.string().max(12).describe(
+              'Very short label displayed as a chip/tag (max 12 chars). Examples: "Auth method", "Library", "Approach".'
+            ),
+            options: z
+              .array(
+                z.object({
+                  label: z.string().describe('The display text for this option.'),
+                  description: z.string().describe('Explanation of what this option means.'),
+                })
+              )
+              .min(2)
+              .max(4)
+              .describe('The available choices (2-4 options). No need for "Other" option, it will be added automatically.'),
+            multiSelect: z.boolean().describe(
+              'Set to true to allow multiple options to be selected.'
+            ),
+          })
+        )
+        .min(1)
+        .max(4)
+        .describe('Questions to ask the user (1-4 questions)'),
+    },
+    async (args, context) => {
+      // 获取工具调用 ID（从 context 或生成一个）
+      const toolUseId = (context as any)?.toolUseId || `ask_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      
+      // 使用动态 session ID（可能已从临时 ID 更新为真实 ID）
+      const currentSessionId = sessionRef.current;
+      console.log(`🎤 [AskUserQuestion MCP] Tool called with ${args.questions.length} questions`);
+      console.log(`🎤 [AskUserQuestion MCP] Session: ${currentSessionId}, Agent: ${agentId}, ToolUseId: ${toolUseId}`);
+      
+      try {
+        // 注册等待用户输入（无超时限制，允许一直等待）
+        // UserInputRegistry 会发出事件，NotificationChannelManager 会处理通知
+        const userResponse = await userInputRegistry.waitForUserInput(
+          currentSessionId,
+          agentId,
+          toolUseId,
+          args.questions
+        );
+        
+        console.log(`✅ [AskUserQuestion MCP] Received user response for tool: ${toolUseId}`);
+        
+        // 返回用户的回答
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `User response:\n\n${userResponse}`,
+            },
+          ],
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`❌ [AskUserQuestion MCP] Error:`, error);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to get user input: ${errorMessage}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Create SDK MCP server with the tool
+  const server = createSdkMcpServer({
+    name: 'ask-user-question',
+    version: '1.0.0',
+    tools: [askUserQuestionTool],
+  });
+
+  return {
+    server,
+    tool: askUserQuestionTool,
+    sessionRef, // 返回 session 引用，供外部更新
+  };
+}
+
+/**
+ * Get tool name as it appears to Claude
+ */
+export function getAskUserQuestionToolName(): string {
+  return 'mcp__ask-user-question__ask_user_question';
+}
+
+/**
+ * Check if a tool name is the AskUserQuestion tool
+ */
+export function isAskUserQuestionTool(toolName: string): boolean {
+  return toolName === getAskUserQuestionToolName() || toolName === 'ask_user_question';
+}

package/backend/src/services/askUserQuestion/index.ts

@@ -0,0 +1,48 @@
+/**
+ * AskUserQuestion Module
+ * 
+ * 提供 MCP 实现的用户问题功能，支持多种通知渠道
+ */
+
+// MCP 工具
+export { 
+    createAskUserQuestionMcpServer, 
+    getAskUserQuestionToolName,
+    isAskUserQuestionTool,
+    type AskUserQuestionInput 
+} from './askUserQuestionMcp.js';
+
+// 集成函数
+export { integrateAskUserQuestionMcpServer } from './askUserQuestionIntegration.js';
+
+// 用户输入注册表
+export { 
+    userInputRegistry,
+    type UserInputRequest,
+    type PendingUserInput 
+} from './userInputRegistry.js';
+
+// 通知渠道管理
+export { 
+    notificationChannelManager,
+    type NotificationChannel,
+    type ChannelType
+} from './notificationChannel.js';
+
+// SSE 通知渠道
+export { 
+    SSENotificationChannel,
+    generateSSEChannelId 
+} from './sseNotificationChannel.js';
+
+// Slack 通知渠道
+export { 
+    SlackNotificationChannel,
+    generateSlackChannelId 
+} from './slackNotificationChannel.js';
+
+// 模块初始化
+export { 
+    initAskUserQuestionModule,
+    isAskUserQuestionModuleInitialized 
+} from './init.js';

package/backend/src/services/askUserQuestion/init.ts

@@ -0,0 +1,53 @@
+/**
+ * AskUserQuestion Module Initialization
+ * 
+ * 设置 UserInputRegistry 和 NotificationChannelManager 之间的事件连接
+ * 这是事件驱动架构的关键：MCP 工具不直接发送通知，而是通过事件系统
+ */
+
+import { userInputRegistry } from './userInputRegistry.js';
+import { notificationChannelManager, type UserInputRequest } from './notificationChannel.js';
+
+let initialized = false;
+
+/**
+ * 初始化 AskUserQuestion 模块
+ * 建立 UserInputRegistry 和 NotificationChannelManager 之间的事件连接
+ * 启动定期清理任务
+ */
+export function initAskUserQuestionModule(): void {
+  if (initialized) {
+    console.log('⚠️ [AskUserQuestion] Module already initialized');
+    return;
+  }
+  
+  // 监听 awaiting_input 事件，通过 NotificationChannelManager 发送通知
+  userInputRegistry.on('awaiting_input', async (request: UserInputRequest) => {
+    console.log(`📡 [AskUserQuestion] Received awaiting_input event for tool: ${request.toolUseId}`);
+    
+    const sent = await notificationChannelManager.sendAwaitingInput(request);
+    
+    if (!sent) {
+      console.warn(`⚠️ [AskUserQuestion] Failed to send notification for tool: ${request.toolUseId}`);
+      // 注意：这里不取消 Promise，因为：
+      // 1. 用户可能稍后重新连接
+      // 2. 可能有其他渠道（如 Slack）可以通知用户
+    }
+  });
+  
+  // 启动定期清理任务，清理超过 24 小时的过期请求
+  // 清理间隔：1 小时，最大存活时间：24 小时
+  userInputRegistry.startCleanupJob();
+  
+  initialized = true;
+  console.log('✅ [AskUserQuestion] Module initialized - event connection established, cleanup job started');
+}
+
+/**
+ * 检查模块是否已初始化
+ */
+export function isAskUserQuestionModuleInitialized(): boolean {
+  return initialized;
+}
+
+

package/backend/src/services/askUserQuestion/notificationChannel.ts

@@ -0,0 +1,218 @@
+/**
+ * Notification Channel Abstraction
+ * 
+ * 定义用户通知渠道的接口，支持多种通知方式：
+ * - SSE (Web 浏览器)
+ * - Slack
+ * - 企业微信
+ * - 邮件
+ * - etc.
+ */
+
+import { EventEmitter } from 'events';
+
+/**
+ * 用户输入请求
+ */
+export interface UserInputRequest {
+  toolUseId: string;
+  sessionId: string;
+  agentId: string;
+  questions: Array<{
+    question: string;
+    header: string;
+    options: Array<{
+      label: string;
+      description: string;
+    }>;
+    multiSelect: boolean;
+  }>;
+  createdAt: number;
+}
+
+/**
+ * 通知渠道类型
+ */
+export type ChannelType = 'sse' | 'slack' | 'wechat' | 'email';
+
+/**
+ * 通知渠道接口
+ */
+export interface NotificationChannel {
+  /** 渠道类型 */
+  type: ChannelType;
+  
+  /** 渠道标识符（如 SSE connectionId、Slack channel ID 等） */
+  channelId: string;
+  
+  /** 关联的 session ID */
+  sessionId: string;
+  
+  /** 关联的 agent ID */
+  agentId: string;
+  
+  /** 创建时间 */
+  createdAt: number;
+  
+  /** 检查渠道是否仍然活跃 */
+  isActive(): boolean;
+  
+  /** 发送等待用户输入的通知 */
+  sendAwaitingInput(request: UserInputRequest): Promise<boolean>;
+  
+  /** 关闭渠道 */
+  close(): void;
+}
+
+/**
+ * 通知渠道管理器
+ * 
+ * 管理所有活跃的通知渠道，根据 sessionId 路由通知
+ */
+class NotificationChannelManager extends EventEmitter {
+  // sessionId -> NotificationChannel[]
+  // 一个 session 可以有多个活跃渠道（如浏览器 + Slack 同时在线）
+  private channels: Map<string, NotificationChannel[]> = new Map();
+  
+  /**
+   * 注册一个通知渠道
+   */
+  registerChannel(channel: NotificationChannel): void {
+    const { sessionId } = channel;
+    
+    if (!this.channels.has(sessionId)) {
+      this.channels.set(sessionId, []);
+    }
+    
+    const sessionChannels = this.channels.get(sessionId)!;
+    
+    // 避免重复注册
+    const existing = sessionChannels.find(c => c.channelId === channel.channelId);
+    if (!existing) {
+      sessionChannels.push(channel);
+      console.log(`📡 [NotificationManager] Registered ${channel.type} channel for session: ${sessionId}`);
+    }
+  }
+  
+  /**
+   * 注销一个通知渠道
+   */
+  unregisterChannel(channelId: string): void {
+    for (const [sessionId, channels] of this.channels.entries()) {
+      const index = channels.findIndex(c => c.channelId === channelId);
+      if (index !== -1) {
+        channels.splice(index, 1);
+        console.log(`📡 [NotificationManager] Unregistered channel: ${channelId} from session: ${sessionId}`);
+        
+        // 如果 session 没有活跃渠道了，清理
+        if (channels.length === 0) {
+          this.channels.delete(sessionId);
+        }
+        return;
+      }
+    }
+  }
+  
+  /**
+   * 更新渠道的 sessionId（当 Claude SDK 返回真实 sessionId 时）
+   */
+  updateChannelSession(channelId: string, newSessionId: string): void {
+    for (const [sessionId, channels] of this.channels.entries()) {
+      const channel = channels.find(c => c.channelId === channelId);
+      if (channel) {
+        // 从旧 session 移除
+        const index = channels.indexOf(channel);
+        channels.splice(index, 1);
+        if (channels.length === 0) {
+          this.channels.delete(sessionId);
+        }
+        
+        // 更新 channel 的 sessionId
+        (channel as any).sessionId = newSessionId;
+        
+        // 添加到新 session
+        if (!this.channels.has(newSessionId)) {
+          this.channels.set(newSessionId, []);
+        }
+        this.channels.get(newSessionId)!.push(channel);
+        
+        console.log(`📡 [NotificationManager] Moved channel ${channelId} from session ${sessionId} to ${newSessionId}`);
+        return;
+      }
+    }
+  }
+  
+  /**
+   * 发送等待用户输入的通知
+   * 会尝试通过所有活跃渠道发送
+   */
+  async sendAwaitingInput(request: UserInputRequest): Promise<boolean> {
+    const { sessionId } = request;
+    const channels = this.channels.get(sessionId);
+    
+    if (!channels || channels.length === 0) {
+      console.warn(`⚠️ [NotificationManager] No active channels for session: ${sessionId}`);
+      return false;
+    }
+    
+    // 清理不活跃的渠道
+    const activeChannels = channels.filter(c => c.isActive());
+    if (activeChannels.length !== channels.length) {
+      this.channels.set(sessionId, activeChannels);
+    }
+    
+    if (activeChannels.length === 0) {
+      console.warn(`⚠️ [NotificationManager] All channels inactive for session: ${sessionId}`);
+      return false;
+    }
+    
+    // 尝试通过所有活跃渠道发送
+    let anySuccess = false;
+    for (const channel of activeChannels) {
+      try {
+        const success = await channel.sendAwaitingInput(request);
+        if (success) {
+          anySuccess = true;
+          console.log(`✅ [NotificationManager] Sent notification via ${channel.type} for session: ${sessionId}`);
+        }
+      } catch (error) {
+        console.error(`❌ [NotificationManager] Failed to send via ${channel.type}:`, error);
+      }
+    }
+    
+    return anySuccess;
+  }
+  
+  /**
+   * 获取 session 的所有活跃渠道
+   */
+  getChannelsForSession(sessionId: string): NotificationChannel[] {
+    return this.channels.get(sessionId) || [];
+  }
+  
+  /**
+   * 检查 session 是否有活跃渠道
+   */
+  hasActiveChannel(sessionId: string): boolean {
+    const channels = this.channels.get(sessionId);
+    return !!channels && channels.some(c => c.isActive());
+  }
+  
+  /**
+   * 获取统计信息
+   */
+  getStats(): { totalSessions: number; totalChannels: number } {
+    let totalChannels = 0;
+    for (const channels of this.channels.values()) {
+      totalChannels += channels.length;
+    }
+    return {
+      totalSessions: this.channels.size,
+      totalChannels
+    };
+  }
+}
+
+// 单例实例
+export const notificationChannelManager = new NotificationChannelManager();
+

package/backend/src/services/askUserQuestion/slackNotificationChannel.ts

@@ -0,0 +1,150 @@
+/**
+ * Slack Notification Channel
+ * 
+ * 实现通过 Slack 消息向用户发送通知
+ * 使用 Slack Block Kit 创建交互式消息
+ */
+
+import type { NotificationChannel, UserInputRequest, ChannelType } from './notificationChannel.js';
+import { SlackClient } from '../slackClient.js';
+
+/**
+ * Slack 通知渠道实现
+ */
+export class SlackNotificationChannel implements NotificationChannel {
+  type: ChannelType = 'slack';
+  channelId: string;  // 格式: channel_id:thread_ts
+  sessionId: string;
+  agentId: string;
+  createdAt: number;
+  
+  private slackClient: SlackClient;
+  private slackChannelId: string;
+  private threadTs: string;
+  private active: boolean = true;
+  
+  constructor(
+    slackClient: SlackClient,
+    slackChannelId: string,
+    threadTs: string,
+    sessionId: string,
+    agentId: string
+  ) {
+    this.slackClient = slackClient;
+    this.slackChannelId = slackChannelId;
+    this.threadTs = threadTs;
+    this.channelId = `slack_${slackChannelId}_${threadTs}`;
+    this.sessionId = sessionId;
+    this.agentId = agentId;
+    this.createdAt = Date.now();
+  }
+  
+  isActive(): boolean {
+    return this.active;
+  }
+  
+  async sendAwaitingInput(request: UserInputRequest): Promise<boolean> {
+    if (!this.isActive()) {
+      return false;
+    }
+    
+    try {
+      // 构建 Slack Block Kit 消息
+      const blocks = this.buildQuestionBlocks(request);
+      
+      await this.slackClient.postMessage({
+        channel: this.slackChannelId,
+        thread_ts: this.threadTs,
+        text: '🎤 AI 需要您的反馈来继续',
+        blocks,
+      });
+      
+      console.log(`📤 [SlackChannel] Sent awaiting_user_input to channel: ${this.channelId}`);
+      return true;
+    } catch (error) {
+      console.error(`❌ [SlackChannel] Failed to send message:`, error);
+      return false;
+    }
+  }
+  
+  close(): void {
+    this.active = false;
+  }
+  
+  /**
+   * 构建 Slack Block Kit 格式的问题消息
+   */
+  private buildQuestionBlocks(request: UserInputRequest): any[] {
+    const blocks: any[] = [
+      {
+        type: 'header',
+        text: {
+          type: 'plain_text',
+          text: '🎤 AI 需要您的反馈',
+          emoji: true
+        }
+      },
+      {
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: `请回答以下问题以继续。\n\n*提示*: 回复时请在消息开头加上问题编号，如 \`Q1: 选项A\``
+        }
+      },
+      {
+        type: 'divider'
+      }
+    ];
+    
+    // 添加每个问题
+    request.questions.forEach((question, index) => {
+      // 问题标题
+      blocks.push({
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: `*Q${index + 1}. ${question.question}*${question.multiSelect ? ' _(可多选)_' : ''}`
+        }
+      });
+      
+      // 选项列表
+      const optionText = question.options
+        .map((opt, i) => `• *${opt.label}*: ${opt.description}`)
+        .join('\n');
+      
+      blocks.push({
+        type: 'section',
+        text: {
+          type: 'mrkdwn',
+          text: optionText
+        }
+      });
+      
+      blocks.push({
+        type: 'divider'
+      });
+    });
+    
+    // 添加提示
+    blocks.push({
+      type: 'context',
+      elements: [
+        {
+          type: 'mrkdwn',
+          text: `📝 请直接回复此消息来提交您的答案 | Tool ID: \`${request.toolUseId}\``
+        }
+      ]
+    });
+    
+    return blocks;
+  }
+}
+
+/**
+ * 生成 Slack channel ID
+ */
+export function generateSlackChannelId(slackChannelId: string, threadTs: string): string {
+  return `slack_${slackChannelId}_${threadTs}`;
+}
+
+