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

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

import { CompactedMemory, CompactedMessage } from './memory';

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

/**
 * 运行模式类型
 * - plan: 只读模式，只能查询分析
 * - ask: 逐个确认，每个写操作需确认
 * - agent: 智能体自主（默认）
 * - auto: 完全自动
 */
export type RunMode = 'plan' | 'ask' | 'agent' | 'auto';

/**
 * 对话请求
 * POST /api/dialog/stream
 */
export interface DialogRequest {
  /** 任务ID（用于记忆隔离） */
  taskId: string;
  /** 用户消息 */
  message: string;
  /** 用户ID */
  userId: string;
  /** 运行模式 */
  mode: RunMode;
  /** 压缩后的记忆数据（用于后端重启后恢复） */
  compactedData?: CompactedMemory;
  /** 压缩后产生的新消息 */
  newMessages?: CompactedMessage[];
  /** 知识图谱数据（JSON 字符串，用于恢复知识图谱） */
  knowledgeData?: string;
}

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

/** SSE 事件类型枚举 */
export type SSEEventType =
  | 'text_delta'      // 文本增量
  | 'tool_call'       // 客户端工具调用请求
  | 'tool_confirm'    // 工具确认请求（Ask 模式）
  | 'plan_confirm'    // 计划确认请求（Plan 模式）
  | 'tool_start'      // 工具开始执行
  | 'tool_complete'   // 工具执行完成
  | 'tool_error'      // 工具执行错误
  | 'ask_user'        // 向用户提问
  | 'agent_start'     // 子智能体启动
  | 'agent_progress'  // 子智能体进度
  | 'agent_complete'  // 子智能体完成
  | 'agent_error'     // 子智能体错误
  | 'memory_compacted' // 记忆压缩完成
  | 'context_usage'   // 上下文使用量
  | '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;
}

/** tool_confirm 事件数据（Ask 模式确认请求） */
export interface ToolConfirmEvent {
  /** 确认ID，用于匹配响应 */
  confirmId: number;
  /** 工具名称 */
  toolName: string;
  /** 工具输入参数 */
  toolInput: Record<string, unknown>;
  /** 时间戳 */
  timestamp: number;
}

/** plan_confirm 事件数据（Plan 模式计划确认） */
export interface PlanConfirmEvent {
  /** 确认ID */
  confirmId: number;
  /** 计划标题 */
  title: string;
  /** 执行步骤列表 */
  steps: string[];
  /** 计划摘要 */
  summary: string;
  /** 时间戳 */
  timestamp: number;
}

/** 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;
}

// ============== 智能体事件类型 ==============

/** agent_start 事件数据 */
export interface AgentStartEvent {
  agentId: string;
  agentType: string;
  agentName: string;
  instruction: string;
  timestamp: number;
}

/** agent_progress 事件数据 */
export interface AgentProgressEvent {
  agentId: string;
  step: number;
  toolName: string;
  toolInput?: unknown;
  toolResult?: string;
  status: 'running' | 'completed' | 'error';
  timestamp: number;
}

/** agent_complete 事件数据 */
export interface AgentCompleteEvent {
  agentId: string;
  agentType: string;
  summary: string;
  stats: Record<string, unknown>;
  timestamp: number;
}

/** agent_error 事件数据 */
export interface AgentErrorEvent {
  agentId: string;
  agentType: string;
  error: string;
  timestamp: number;
}

/** context_usage 事件数据 */
export interface ContextUsageEvent {
  currentTokens: number;
  maxTokens: number;
  percentage: 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;
}

// ============== 工具确认响应 ==============

/**
 * 工具确认响应请求
 * POST /api/tool/confirm
 */
export interface ToolConfirmResponse {
  /** 确认ID，与 ToolConfirmEvent.confirmId 对应 */
  confirmId: number;
  /** 任务ID */
  taskId: string;
  /** 是否批准执行 */
  approved: boolean;
}

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

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

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

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

/** file_delete 工具参数 */
export interface FileDeleteArgs {
  /** 要删除的文件路径 */
  path: 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;
}

/** waveform_trace 工具参数 */
export interface WaveformTraceArgs {
  /** Verilog 源文件路径（相对于项目根目录） */
  verilogPath: string;
  /** VCD 波形文件路径（相对于项目根目录） */
  vcdPath: string;
  /** 仿真工具的输出字符串（包含 mismatch 信息） */
  simOutput: string;
  /** BFS 回溯层数，默认 2 */
  traceLevel?: number;
}

/** knowledge_save 工具参数 */
export interface KnowledgeSaveArgs {
  /** 知识图谱 JSON 数据 */
  data: string;
}

/** knowledge_load 工具参数 */
export interface KnowledgeLoadArgs {
  // 无参数，直接读取 .iccoder/knowledge.json
}

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