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";

/**
 * 服务等级类型
 * - lite: 轻量级
 * - syntaxic: 语法级
 * - max: 最大性能
 * - auto: 自动选择
 */
export type ServiceTier = "lite" | "syntaxic" | "max" | "auto";

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

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

/** SSE 事件类型枚举 */
export type SSEEventType =
  | "text_delta" // 文本增量
  | "tool_call" // 客户端工具调用请求
  | "tool_confirm" // 工具确认请求（Ask 模式）
  | "plan_confirm" // 计划确认请求（Plan 模式）
  | "phase_progress" // 阶段进度更新
  | "plan_step_add" // 添加计划步骤
  | "plan_step_remove" // 删除计划步骤
  | "plan_step_update" // 更新计划步骤
  | "plan_summary_update" // 更新计划摘要
  | "tool_start" // 工具开始执行
  | "tool_complete" // 工具执行完成
  | "tool_error" // 工具执行错误
  | "ask_user" // 向用户提问
  | "agent_start" // 子智能体启动
  | "agent_progress" // 子智能体进度
  | "agent_complete" // 子智能体完成
  | "agent_error" // 子智能体错误
  | "memory_compacted" // 记忆压缩完成
  | "context_usage" // 上下文使用量
  | "credit_update" // 资源点余额更新
  | "complete" // 对话完成
  | "error" // 错误
  | "warning" // 警告
  | "notification" // 通知
  | "depth_update" // 深度更新
  | "heartbeat"; // 心跳

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

/** 计划步骤 */
export interface PlanStep {
  /** 步骤名称 */
  name: string;
  /** 步骤描述 */
  description?: string;
}

/** 计划阶段 */
export interface PlanPhase {
  /** 阶段ID: spec/design/sim/done */
  id: string;
  /** 阶段名称 */
  name: string;
  /** 阶段状态: skipped/completed/current/pending */
  status: string;
  /** 跳过原因 */
  reason?: string;
  /** 阶段内的步骤 */
  steps: PlanStep[];
}

/** plan_confirm 事件数据（Plan 模式计划确认） */
export interface PlanConfirmEvent {
  /** 确认ID */
  confirmId: number;
  /** 计划标题 */
  title: string;
  /** 四阶段计划列表（新格式） */
  phases?: PlanPhase[];
  /** 执行步骤列表（旧格式，兼容） */
  steps?: string[];
  /** 计划摘要 */
  summary: string;
  /** 时间戳 */
  timestamp: number;
}

/** phase_progress 事件数据（阶段进度更新） */
export interface PhaseProgressEvent {
  /** 阶段ID: spec/design/sim/done */
  phaseId: string;
  /** 状态: current/completed */
  status: string;
  /** 时间戳 */
  timestamp: number;
}

/** plan_step_add 事件数据（添加计划步骤） */
export interface PlanStepAddEvent {
  phaseId: string;
  step: PlanStep;
  index: number;
  timestamp: number;
}

/** plan_step_remove 事件数据（删除计划步骤） */
export interface PlanStepRemoveEvent {
  phaseId: string;
  stepIndex: number;
  timestamp: number;
}

/** plan_step_update 事件数据（更新计划步骤） */
export interface PlanStepUpdateEvent {
  phaseId: string;
  stepIndex: number;
  step: PlanStep;
  timestamp: number;
}

/** plan_summary_update 事件数据（更新计划摘要） */
export interface PlanSummaryUpdateEvent {
  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;
}

/** credit_update 事件数据 */
export interface CreditUpdateEvent {
  deductedCredits: number;
  remainingCredits: 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;
  /** 要dump的模块列表，格式：name:path,name:path */
  dumpModules?: string;
  /** VCD输出目录，默认'vcd' */
  vcdDir?: 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;