evcod_all — 本地优先的远程终端辅助工作台

evcod 是一个本地优先（local-first）的远程终端辅助工具，包含三个核心模块：

模块	目录	技术栈	职责
Core	evcod/core/	Go 1.26	HTTP/WebSocket 后台服务，提供鉴权、项目管理、文件操作、Git 操作、终端、会话、Agent 编排等能力
Web UI	evcod/webui/	React 19 + Vite 6 + TypeScript	浏览器端工作台，连接一个或多个 Core 实例，提供终端、对话、文件编辑、Git 面板等 UI
Warp	evcod_warp/	Node.js 22 (ESM)	Agent 桥接层，将 Claude Code、OpenCode、Codex、Gemini、Qwen 等 AI Agent 的事件规范化并回写 Core

---

整体架构

┌──────────────────────────────────────────────────────┐
│                  浏览器 (Web UI)                       │
│  ┌──────┐ ┌──────────┐ ┌────────┐ ┌──────┐ ┌──────┐ │
│  │ 侧栏  │ │ 终端面板  │ │ 对话面板 │ │文件面板│ │Git面板│ │
│  └──┬───┘ └────┬─────┘ └────┬───┘ └──┬───┘ └──┬───┘ │
└─────┼──────────┼────────────┼────────┼────────┼──────┘
      │  REST +  │ WebSocket  │        │        │
      ▼          ▼             ▼        ▼        ▼
┌──────────────────────────────────────────────────────┐
│                evcod Core (Go)                        │
│  ┌──────┐ ┌────────┐ ┌──────┐ ┌──────┐ ┌──────────┐ │
│  │  API  │ │Services│ │ Store │ │Events│ │Platform  │ │
│  │Router │ │        │ │(JSON) │ │  Bus │ │(mac/win) │ │
│  └──────┘ └────────┘ └──────┘ └──────┘ └──────────┘ │
└─────────────────┬────────────────────────────────────┘
                  │ WebSocket Relay
                  ▼
┌──────────────────────────────────────────────────────┐
│              evcod Warp (Node.js)                     │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │CoreBridge│ │AgentCatalog│ │Normalizer│ │Backends  │ │
│  │         │ │          │ │          │ │cli/opencode│ │
│  └─────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────┘

---

快速开始

启动 Core

cd evcod/core
go run ./cmd/evcod-core serve

Core 默认监听 127.0.0.1:4865，首次启动会自动生成 API key。

查看 API key：

go run ./cmd/evcod-core key print

启动 Web UI

cd evcod/webui
npm install
npm run dev -- --port 10066

浏览器打开 http://127.0.0.1:10066，在设置中添加 Core 连接：

• Alias：任意名称（如 Local core）
• Endpoint：http://127.0.0.1:4865（或指定端口）
• API Key：Core 的当前有效 API key

启动 Warp（连接 AI Agent）

cd evcod_warp
npm start -- opencode --core http://127.0.0.1:4865 --api-key <key>

支持的 Agent 类型：claude、opencode、codex、gemini、qwen、fake

---

核心功能

Core 服务端

功能分类	API 端点	说明
系统	/api/system、/api/settings/runtime	系统信息与运行时配置
主机	/api/host/*	主机概览、性能、进程、端口、网络接口
鉴权	/api/tokens	API key 管理与认证
项目	/api/projects	项目 CRUD，绑定本地目录
Worktree	/api/worktrees	Git worktree 管理
工作区 Tab	/api/workspace/tabs	工作区标签页管理（terminal/vcs/editor/diffViewer）
文件	/api/files/*	文件列表、读取、写入、搜索、创建、删除、重命名、目录浏览
Git	/api/git/*	status/diff/log/branches/checkout/branch/stage/unstage/discard/commit/pull/push/stash
终端	/api/terminal/panes	终端 pane 创建、输入、resize、快照
Agent	/api/agent/*	Agent 目录、历史、会话管理
对话	/api/conversations	对话与消息持久化
审计	/api/audit/logs	文件写操作审计日志
WebSocket	/ws/rpc、/ws/relay	实时事件推送与 Agent relay

Web UI 前端

• 桌面工作台布局：左侧侧栏（项目/对话列表）、中间主工作区、右侧面板（文件/Git/事件）
• 终端模式：基于 xterm.js 的远程终端，支持多 pane、自动 resize
• 对话模式：消息流展示、AI Agent 对话、流式输出渲染
• 文件管理：文件树浏览、文本编辑（Monaco Editor）、文件创建/保存
• Git 面板：变更文件列表、diff 查看、stage/unstage/commit
• Core 连接管理：多 Core 配置、本地持久化
• 主机管理：主机概览、性能监控、进程与端口查看

Warp Agent 桥接

• 支持多种 AI Agent 后端的 prompt/response 规范化
• 支持 JSONL 和 JSON-RPC 两种传输协议
• 终端内原生 Agent 界面 + Web Chat 双向镜像
• Agent 事件标准化（text/reasoning/tool_call/tool_result/usage 等）

---

项目结构

evcod_all/
├── evcod/                          # 主项目
│   ├── core/                       # Go 后端服务
│   │   ├── cmd/evcod-core/main.go  # 入口
│   │   ├── internal/
│   │   │   ├── api/                # HTTP/WS 路由与处理器
│   │   │   ├── app/                # 应用初始化与生命周期
│   │   │   ├── config/             # 配置管理
│   │   │   ├── domain/             # 领域模型
│   │   │   ├── events/             # 事件总线
│   │   │   ├── platform/           # 平台抽象 (common/mac/win)
│   │   │   ├── services/           # 业务逻辑层
│   │   │   └── store/              # JSON 文件持久化
│   │   └── go.mod
│   ├── webui/                      # React 前端
│   │   ├── src/
│   │   │   ├── App.tsx             # 主应用组件
│   │   │   ├── api.ts              # Core API 客户端
│   │   │   ├── store.ts            # Zustand 状态管理
│   │   │   ├── components/         # UI 组件
│   │   │   │   ├── TerminalView.tsx
│   │   │   │   ├── ConversationView.tsx
│   │   │   │   ├── FilesPanel.tsx
│   │   │   │   ├── GitPanel.tsx
│   │   │   │   ├── Sidebar.tsx
│   │   │   │   ├── chat/           # 对话子组件
│   │   │   │   └── ...
│   │   │   └── styles.css
│   │   ├── tests/                  # Playwright 端到端测试
│   │   └── package.json
│   ├── docs/                       # 项目文档
│   │   ├── api/                    # API 文档
│   │   └── project-overview.zh-CN.md
│   ├── scripts/                    # 开发辅助脚本
│   └── test_scripts/               # 测试脚本
│
├── evcod_warp/                     # Node.js Agent 桥接层
│   ├── bin/evcod-warp.js           # CLI 入口
│   ├── src/
│   │   ├── cli.js                  # CLI 参数解析与调度
│   │   ├── core-bridge.js          # Core WebSocket 桥接
│   │   ├── session-controller.js   # 会话生命周期控制
│   │   ├── native-agent.js         # 原生 Agent 控制器
│   │   ├── opencode-tui.js         # OpenCode TUI 控制器
│   │   ├── normalizer.js           # Agent 事件标准化
│   │   ├── registry.js             # Agent 注册表
│   │   ├── backends/               # Agent 后端实现
│   │   │   ├── claude.js           # Claude Code
│   │   │   ├── codex.js            # Codex CLI
│   │   │   ├── opencode.js         # OpenCode (ACP)
│   │   │   └── fake.js             # 测试用假后端
│   │   └── transports/             # 传输协议
│   │       ├── factory.js
│   │       ├── jsonl.js            # JSONL 传输
│   │       └── jsonrpc.js          # JSON-RPC 传输
│   ├── test/                       # 单元测试
│   └── package.json
│
├── chat_diff/                      # 架构对齐文档
├── 审查报告/                       # 代码审查报告
├── start-evcod.bat                 # Windows 一键启动
└── AGENTS.md                        # Agent 工作指南

---

技术栈

Core

• 语言：Go 1.26
• HTTP/WebSocket：标准库 net/http + gorilla/websocket
• PTY：go-pty + creack/pty
• 持久化：本地 JSON 状态文件
• 架构：API → App → Services → Store + Platform 分层

Web UI

• 框架：React 19 + TypeScript
• 构建：Vite 6
• 状态管理：Zustand 5
• 终端渲染：xterm.js 5 + addon-fit
• 编辑器：Monaco Editor
• 图标：lucide-react
• 测试：Playwright

Warp

• 运行时：Node.js ≥ 22 (ESM)
• 测试：Node.js 内置 node:test

---

开发命令

Core

gofmt -w core                          # 格式化代码
go -C core test ./...                  # 运行单元测试
go -C core build ./cmd/evcod-core      # 编译构建
go -C core run ./cmd/evcod-core serve  # 启动服务

Web UI

cd evcod/webui
npm run dev                # 启动开发服务器
npm run build              # 类型检查 + 构建
npm run test:smoke         # 浏览器冒烟测试
npm run test:full-flow     # 全流程测试
npm run test:feature-flow  # 功能回归测试

Warp

cd evcod_warp
npm test                   # 运行测试
npm start                  # 启动 CLI

快速验证

evcod/test_scripts/run_full_tests.sh  # Core + WebUI 完整验证脚本

---

当前状态

项目处于 MVP 功能闭环阶段：

• Core 服务端核心 API 完整可用（鉴权、项目、文件、Git、终端、对话、Agent）
• Web UI 桌面工作台布局、终端交互、文件编辑、Git 面板
• Warp Agent 桥接（Claude Code / OpenCode / Codex）
• 跨平台平台抽象（macOS / Windows）
• 端到端浏览器测试
• 真实 LLM Provider 集成与 Agent 循环
• TLS/WSS 安全传输
• 权限粒度控制与高危操作确认策略
• 数据库持久化（当前为 JSON 文件）

---

License

本项目尚未添加开源许可证。