nuwax AGENTS.md

AI Agent System Documentation

系统概述

本项目集成了先进的 AI Agent 系统，为用户提供智能化的代码开发辅助功能。系统通过 SSE (Server-Sent Events) 实现实时通信，支持流式对话和工具调用。

AI Agent 架构

核心组件

1. SSE 连接管理器 (utils/sseManager.ts)

负责管理与服务器的实时连接：

• 自动重连机制
• 连接状态监控
• 消息分发和处理
• 错误恢复策略

2. AppDev Web IDE 系统

文件管理 Hook (hooks/useAppDevFileManagement.ts)

• 项目文件树管理
• 文件内容缓存和同步
• 文件修改状态跟踪
• 自动保存机制

开发服务器 Hook (hooks/useAppDevServer.ts)

• 开发环境自动启动
• 服务器状态监控
• 保活机制
• 端口自动分配

聊天系统 Hook (hooks/useAppDevChat.ts)

• SSE 实时连接管理
• 消息流式处理
• AI 思考过程展示
• 工具调用状态管理

3. 消息处理器 (pages/AppDev/index.tsx)

处理不同类型的 AI 消息：

• agent_thought_chunk: AI 思考过程
• agent_message_chunk: AI 回复内容
• tool_call: 工具调用通知
• prompt_end: 会话结束

4. 会话管理

• 会话 ID 生成和管理
• 多会话并发支持
• 会话状态持久化

AI 功能特性

1. 智能对话

interface ChatMessage {
  id: string;
  type: 'ai' | 'user' | 'button' | 'section' | 'thinking' | 'tool_call';
  content?: string;
  sessionId?: string;
  isStreaming?: boolean;
}

2. 思考过程可视化

• 实时显示 AI 思考过程
• 上下文理解展示
• 推理路径可视化

3. 工具调用支持

• 自动执行开发任务
• 文件操作自动化
• 代码生成和修改

4. 流式响应

• 实时文本流显示
• 打字机效果
• 增量内容更新

AppDev Web IDE 功能

1. 文件管理系统

文件树组件 (pages/AppDev/components/FileTree/index.tsx)

• 支持文件夹展开/折叠
• 文件选择和编辑
• 文件创建、删除操作
• 拖拽操作支持
• 右键菜单功能

文件内容管理

• 文件内容缓存机制
• 修改状态实时跟踪
• 自动保存功能
• 文件类型识别

2. 代码编辑器

Monaco Editor 集成 (pages/AppDev/components/MonacoEditor/index.tsx)

• 支持多种编程语言语法高亮
• TypeScript/JavaScript 智能提示
• 自定义主题配置
• 实时内容同步
• 代码折叠和格式化

3. 实时预览系统

预览组件 (pages/AppDev/components/Preview/index.tsx)

• iframe 嵌入式预览
• 自动刷新功能
• 全屏预览支持
• 错误状态处理
• 加载状态显示

4. 开发服务器管理

服务器生命周期管理

• 自动启动开发环境
• 自动端口分配 (3000-4000 范围)
• 服务器状态实时监控
• 保活机制防止服务中断
• 错误恢复和重试机制

5. 错误恢复机制

开发环境错误处理

• 后端服务不可用时的前端开发支持
• URL 参数控制 (?mock=true/false)
• localStorage 持久化配置
• 模拟网络延迟 (300ms)
• 完整的 API 端点模拟

集成接口

核心服务接口

发送聊天消息

const response = await sendChatMessage({
  user_id: 'app-dev-user',
  prompt: userInput,
  project_id: workspace.projectId,
  session_id: sessionId,
  request_id: generateRequestId(),
});