IC-Coder-Plugin/src/types/api.ts

/**
 * 后端 API 类型定义
 * 对应后端 IC Coder Backend 的接口格式
 */

// ============== 对话请求/响应 ==============

/**
 * 对话请求
 * POST /api/dialog/stream
 */
export interface DialogRequest {
  /** 任务ID（用于记忆隔离） */
  taskId: string;
  /** 用户消息 */
  message: string;
  /** 用户ID */
  userId: string;
  /** 工具模式 */
  toolMode: 'ASK' | 'AGENT';
}

// ============== SSE 事件类型 ==============

/** SSE 事件类型枚举 */
export type SSEEventType =
  | 'text_delta'      // 文本增量
  | 'tool_call'       // 客户端工具调用请求
  | 'tool_start'      // 工具开始执行
  | 'tool_complete'   // 工具执行完成
  | 'tool_error'      // 工具执行错误
  | 'ask_user'        // 向用户提问
  | 'complete'        // 对话完成
  | 'error'           // 错误
  | 'warning'         // 警告
  | 'notification'    // 通知
  | 'depth_update';   // 深度更新

/** text_delta 事件数据 */
export interface TextDeltaEvent {
  text: string;
}

/** tool_start 事件数据 */
export interface ToolStartEvent {
  tool_name: string;
  tool_input: unknown;
}

/** tool_complete 事件数据 */
export interface ToolCompleteEvent {
  tool_name: string;
  result: string;
}

/** tool_error 事件数据 */
export interface ToolErrorEvent {
  tool_name: string;
  error: string;
}

/** ask_user 事件数据 */
export interface AskUserEvent {
  askId: string;
  question: string;
  options: string[];
}

/** complete 事件数据 */
export interface CompleteEvent {
  status: string;
  finish_reason: string;
}

/** error 事件数据 */
export interface ErrorEvent {
  message: string;
}

/** warning 事件数据 */
export interface WarningEvent {
  message: string;
}

/** notification 事件数据 */
export interface NotificationEvent {
  message: string;
}

/** depth_update 事件数据 */
export interface DepthUpdateEvent {
  depth: number;
}

// ============== 工具调用协议 (MCP 格式) ==============

/**
 * 工具调用请求（MCP格式）
 * 后端通过 SSE tool_call 事件推送
 */
export interface ToolCallRequest {
  /** JSON-RPC版本，固定为"2.0" */
  jsonrpc: '2.0';
  /** 请求ID，用于匹配响应 */
  id: number;
  /** 方法名，固定为"tools/call" */
  method: 'tools/call';
  /** 调用参数 */
  params: {
    /** 工具名称 */
    name: string;
    /** 工具参数 */
    arguments: Record<string, unknown>;
  };
}

/**
 * 工具执行结果（MCP格式）
 * POST /api/tool/result
 */
export interface ToolCallResult {
  /** JSON-RPC版本 */
  jsonrpc: '2.0';
  /** 请求ID，与ToolCallRequest.id对应 */
  id: number;
  /** 执行结果（与error互斥） */
  result?: ToolResultContent;
  /** 错误信息（与result互斥） */
  error?: ToolResultError;
}

/** 工具执行结果内容 */
export interface ToolResultContent {
  /** 内容列表 */
  content: ContentItem[];
  /** 是否为错误结果（业务错误，如编译失败） */
  isError: boolean;
}

/** 内容项 */
export interface ContentItem {
  /** 内容类型：text, image, resource */
  type: string;
  /** 文本内容 */
  text: string;
}

/** 工具系统错误 */
export interface ToolResultError {
  /** 错误码 */
  code: number;
  /** 错误消息 */
  message: string;
}

// ============== 用户回答 ==============

/**
 * 用户回答请求
 * POST /api/task/answer
 */
export interface AnswerRequest {
  /** 问题ID */
  askId: string;
  /** 任务ID */
  taskId: string;
  /** 选中的选项列表 */
  selected?: string[];
  /** 自定义输入内容 */
  customInput?: string;
}

/** 用户回答响应 */
export interface AnswerResponse {
  success: boolean;
  message?: string;
  error?: string;
}

// ============== 工具结果响应 ==============

/** 工具结果响应 */
export interface ToolResultResponse {
  success: boolean;
  message?: string;
  error?: string;
}

// ============== 辅助类型 ==============

/** 后端工具名称 */
export type ToolName =
  | 'file_read'
  | 'file_write'
  | 'file_list'
  | 'syntax_check'
  | 'simulation'
  | 'waveform_summary';

/** file_read 工具参数 */
export interface FileReadArgs {
  path: string;
}

/** file_write 工具参数 */
export interface FileWriteArgs {
  path: string;
  content: string;
}

/** file_list 工具参数 */
export interface FileListArgs {
  path?: string;
  extension?: string;
}

/** syntax_check 工具参数 */
export interface SyntaxCheckArgs {
  code: string;
}

/** simulation 工具参数 */
export interface SimulationArgs {
  rtlPath: string;
  tbPath: string;
  duration?: string;
}

/** waveform_summary 工具参数 */
export interface WaveformSummaryArgs {
  vcdPath: string;
  signals: string;
  checkpoints?: string;
}

/** 工具参数联合类型 */
export type ToolArgs =
  | FileReadArgs
  | FileWriteArgs
  | FileListArgs
  | SyntaxCheckArgs
  | SimulationArgs
  | WaveformSummaryArgs;