405 lines
8.7 KiB
TypeScript
405 lines
8.7 KiB
TypeScript
/**
|
||
* 后端 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 模式）
|
||
| "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" // 深度更新
|
||
| "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;
|
||
}
|
||
|
||
/** 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;
|