Web UI 实现提案

[Yumiue]

用户场景故事

作为开发者，我希望能够在浏览器或桌面应用中使用图形化界面与 NeoCode AI Coding Agent 交互，而不仅仅是通过终端 TUI。这样可以提供更直观的体验，特别是对于：

• 不熟悉终端操作的用户
• 需要可视化文件树和代码变更的用户
• 希望在桌面环境中无缝集成的用户
• 需要多会话管理和历史记录查看的用户

核心功能实现

1. API 层 (web/src/api/)

   • gateway.ts: Gateway 业务 API 客户端，支持认证、会话管理、工具调用等
   • wsClient.ts: WebSocket 全双工通道客户端
   • protocol.ts: 完整的 Gateway RPC 协议类型定义

2. 状态管理 (web/src/stores/)

   • useChatStore.ts: 聊天消息、权限请求、token 用量、运行状态
   • useSessionStore.ts: 会话列表、项目分组、会话切换
   • useGatewayStore.ts: Gateway 连接状态
   • useUIStore.ts: UI 状态（侧边栏、面板、toast 等）

3. 组件实现 (web/src/components/)

   • chat/: ChatPanel, MessageList, ChatInput, MessageItem, ToolCallCard, ModelSelector, CodeBlock, MarkdownContent
   • layout/: AppLayout, Sidebar
   • panels/: FileTreePanel, FileChangePanel
   • status/: StatusBar
   • permission/: PermissionDialog
   • ui/: ToastContainer

4. 页面实现 (web/src/pages/)

   • ChatPage.tsx: 主聊天页面
   • ConnectPage.tsx: 浏览器端 Gateway 连接配置页

5. 运行时上下文 (web/src/context/)

   • RuntimeProvider.tsx: Gateway 连接管理、WebSocket 事件桥接

6. 双模式支持

   • Electron 模式：桌面应用，内嵌 Gateway
   • 浏览器模式：连接远程 Gateway 或通过 Vite 插件启动本地 Gateway

7. 核心交互

   • 实时消息流式输出
   • 工具调用可视化展示
   • 权限请求处理（拒绝/允许一次/本会话允许）
   • 会话管理（新建、重命名、归档）
   • 文件树展示
   • 文件变更展示
   • 模型选择
   • 错误边界和重试机制

实现目标

阶段一：基础功能完善（当前阶段）

• 核心聊天交互
• 会话管理
• 会话中滚动修正
• 文件树
• 变更展示
• 权限处理
• Gateway 连接
• CLI启动指令
• 测试覆盖率达到 80%
• 基础文档完善

阶段二：功能增强

• 设置页面
• slash
• build/paln
• Skills 管理
• MCP Server 管理
• Provider 管理
• 主题系统
• 快捷键完善

阶段三：发布准备

• Electron 打包验证
• 安装包构建
• 用户文档
• 发布流程

实现的大致描述

架构设计

Web UI 遵循 NeoCode 的主链路架构：

用户输入(Web UI) -> Gateway API -> Runtime -> Tools -> 结果回传 -> UI 展示

分层隔离

• Web UI 作为 Gateway 的客户端，不直接依赖 Runtime 或 Provider
• 通过 WebSocket 全双工通道与 Gateway 通信
• 状态集中管理，不分散到组件

模块边界

• api/: Gateway 协议适配层
• stores/: 状态管理层
• components/: UI 组件层
• pages/: 页面层
• context/: 运行时上下文

技术决策

1. 状态管理选择 Zustand

   • 轻量级、API 简洁
   • 支持 TypeScript
   • 适合中小型应用

2. 样式方案

   • 使用 CSS 变量实现主题系统
   • 内联样式（当前实现）便于快速开发
   • 未来可迁移到 CSS Modules 或 Tailwind CSS

3. 构建工具选择 Vite

   • 快速的开发体验
   • 良好的 TypeScript 支持
   • Electron 插件生态完善

4. 双模式支持

   • Electron 模式：桌面应用，可内嵌 Gateway
   • 浏览器模式：连接远程 Gateway，便于开发和测试

开发流程

1. 开发环境

   cd web
   npm install
   npm run dev              # 浏览器模式
   npm run dev:electron     # Electron 模式

2. 构建

   npm run build            # 浏览器构建
   npm run build:electron   # Electron 构建

3. 测试

   npm run test             # 运行测试
   npm run test:ui          # 测试 UI
   npm run coverage         # 覆盖率报告

验收标准

功能验收

• 用户可以通过 Web UI 发送消息并接收 AI 回复
• 消息支持流式输出
• 工具调用可以正确展示（工具名、参数、结果）
• 权限请求可以正确处理（三种决策方式）
• 会话可以新建、重命名、归档
• 文件树可以正确展示工作目录结构
• 文件变更可以正确展示
• 模型选择器可以正常工作
• Electron 模式和浏览器模式都能正常运行
• Gateway 连接失败时有友好的错误提示和重试机制

质量验收

• 核心组件测试覆盖率 ≥ 80%
• 无控制台错误或警告
• 无内存泄漏（长时间运行测试）
• 响应式布局适配不同屏幕尺寸
• 键盘导航基本可用

文档验收

• Web UI 使用文档（用户指南）
• 开发文档（贡献指南）
• API 文档（组件和 hooks）
• 构建和发布文档

发布验收

• Electron 应用可以在 Windows/macOS/Linux 上打包
• 安装包可以正常安装和卸载
• 应用启动时间 < 3 秒
• 应用内存占用合理（< 500MB 空闲状态）

[Yumiue]

• 供应商选择优化

[phantom5099]

卡点：如何在主线用户场景故事内说明好web端的优势是什么
截至时间：看后端什么时候能完成，预期时间是2026.05.07