Agent GUI

一个基于 Electron + React + Vite 的桌面端 GUI Agent 工具，用自然语言驱动本地文件读取、创建和修改，并把 Agent 的执行过程、变更预览和确认写入流程可视化出来。

项目简介

这个项目面向“不想使用 CLI、但希望用 AI 辅助本地文件处理”的用户，核心目标是提供一个透明、可控、低门槛的本地 Agent 工作台。

当前 MVP 聚焦以下闭环：

• 选择本地工作区
• 浏览目录树并查看文本文件
• 通过聊天输入发起读取、创建、修改任务
• 展示 Agent 步骤流和任务状态
• 在写入前展示 diff 或新文件预览
• 用户确认后才执行文件写入
• 限制所有读写都只能发生在当前工作区内

当前实现

当前版本已经包含这些主要模块：

• Electron Main Process
  • 工作区选择
  • 文件系统访问
  • 路径边界校验
  • Agent 任务编排
  • 事件流分发
• Electron Preload
  • 通过 contextBridge 暴露白名单 API
  • 使用 IPC 连接渲染层和主进程
• React Renderer
  • 三栏工作台布局
  • 文件树与文本预览
  • 聊天区与任务状态
  • Agent 时间线
  • Diff 预览与确认写入

技术栈

• Electron
• React
• TypeScript
• Vite
• Zustand
• MUI
• Monaco Editor

目录结构

electron/
  main/
    ipc/
    services/
  preload/
src/
  features/
    workspace/
    chat/
    task/
  shared/

开发启动

安装依赖：

npm install

启动开发环境：

npm run dev

启动注意事项

如果你的终端环境里存在下面这个变量：

ELECTRON_RUN_AS_NODE=1

Electron 会被当作普通 Node 进程启动，导致桌面窗口无法正常拉起。

可以先执行：

unset ELECTRON_RUN_AS_NODE

或者直接这样启动：

env -u ELECTRON_RUN_AS_NODE npm run dev

MVP 范围

当前版本只覆盖基础文件任务，不包含以下能力：

• Shell / Terminal 执行
• Git 操作
• 自动测试或构建
• 多 Agent 协作
• 远程服务器访问
• 图片或二进制文件编辑

设计原则

• 透明：展示 Agent 每一步做了什么
• 可控：所有写入必须确认
• 安全：只能访问当前工作区
• 简单：先聚焦本地文本文件任务