accounts/XCode-Agent-Framework-design.md at e0915541a7b2b66df22ae8325703bc671e086680

Haitao Pan 9e1112758a feat(dashboard-fresh): migrate and integrate dashboard source

- Add fresh app structure (auth, tenant, mail, insight, docs, panel)
- Include CMS content, API routes, scripts, and config
- Migrate UI components, themes, and extensions to fresh runtime

2025-11-04 18:06:21 +08:00

6.5 KiB

Raw Blame History

Agent Framework 设计文档

版本：v1.0 项目代号：Project Codexium 作者：svc.plus 架构组（Pan Haitao）目标：统一代码智能、运维智能与模型桥接能力的开发者工作台

一、系统愿景

“让 AI 不只是写代码，而是理解系统。”

Codexium 的目标是构建一个统一的智能代理层，使得开发者在编程、测试、运维的整个生命周期中，都能通过 /api/agent/* 接口访问具备上下文记忆与验证能力的 LLM 工具链。

系统分为三大支柱：

模块名称职责 /api/agent/code CodeSmith 编码智能：分析、重构、生成、解释代码 /api/agent/ops OpsMind 运维智能：测试验证、性能剖析、异常诊断 /api/agent/bridge LLM-Bridge 桥接智能：与国内外大模型生态互联二、系统架构概览 flowchart TB subgraph UI["🖥️ Web IDE / Dashboard"] C1[任务列表] --> C2[任务详情与日志] C2 --> C3[运行面板（Playwright / DevTools / LLM）] end

subgraph API["🧠 Agent Gateway (Node/Deno)"] A1[/api/agent/code/]:::code --> A3 A2[/api/agent/ops/]:::ops --> A3 A4[/api/agent/bridge/]:::bridge --> A3 A3[(Runs Registry + Storage)] end

subgraph Runtime["⚙️ Runners / Services"] R1[Codex-CLI / Claude-CLI / Gemini-CLI] R2[Playwright MCP Server] R3[DevTools MCP Server] R4[LLM-Bridge Adapter] end

subgraph Infra["💾 Backend Infra"] D1[(PostgreSQL / SQLite)] D2[(S3 / Local Storage)] end

UI --> API API --> Runtime API --> Infra Runtime --> D2 classDef code fill=#C6E2FF,stroke=#4582EC; classDef ops fill=#FFF2CC,stroke=#D6B656; classDef bridge fill=#D9EAD3,stroke=#6AA84F;

三、API 模块划分与命名语义模块路径名称职责描述核心子接口 /api/agent/code CodeSmith 面向代码智能任务 analyze, refactor, generate, explain, review /api/agent/ops OpsMind 面向运维与测试任务 playwright, devtools, profile, report /api/agent/bridge LLM-Bridge 模型桥接与分发层 invoke, list-models, proxy 四、功能说明

CodeSmith（编码智能）

目标：让 LLM 理解项目上下文并参与重构。功能示例：

功能说明 CLI 或工具 analyze 分析文件结构与依赖 codex-cli analyze refactor 自动重构、删除死代码 codex-cli refactor generate 根据提示生成新代码 claude-cli generate explain 对复杂逻辑生成自然语言解释 gemini-cli explain

运行模式：通过 child_process.spawn 调用 CLI，并以 SSE 流式推送执行日志。每次执行结果存储为 run 记录，并关联到任务。

OpsMind（运维智能）

目标：自动化验证与性能剖析。

MCP 接口：

功能 MCP Server 说明 playwright mcp-playwright 执行端到端测试、截图、trace devtools mcp-devtools 运行 CPU/Heap Profiler profile mcp-devtools 生成 trace.json 与指标摘要 report 内部汇总生成性能分析报告（HTML/PDF）

示例工作流：

POST /api/agent/ops/playwright → 启动 Playwright MCP → trace.zip → 存储为附件 → 任务run状态更新

LLM-Bridge（模型桥接层）

目标：在不暴露私钥的前提下，统一访问国内外大模型生态。

功能说明适配对象 invoke 通用调用接口（支持 OpenAI 格式） ChatGPT / Claude / Qwen / Yi / Baichuan / Moonshot list-models 返回所有可用模型及状态从注册表动态读取 proxy 将 REST 调用转为相应 API 代理可接入 WebSocket 流式返回

配置结构示例：

llm_bridge: providers: openai: endpoint: https://api.openai.com/v1 api_key: $OPENAI_API_KEY qwen: endpoint: https://dashscope.aliyuncs.com/api/v1 api_key: $DASHSCOPE_API_KEY moonshot: endpoint: https://api.moonshot.cn/v1 api_key: $MOONSHOT_API_KEY

作用：

对上：所有 /api/agent/code、/api/agent/ops 请求可指定 provider 参数；

对下：桥接各类 LLM API，兼容 JSON Schema 响应；

提供统一上下文缓存机制（如 KV/Redis session）。

五、数据库模型 CREATE TABLE tasks ( id TEXT PRIMARY KEY, title TEXT, summary TEXT, status TEXT CHECK (status IN ('todo','doing','done','archived')), tags TEXT[], created_at TIMESTAMP DEFAULT now(), updated_at TIMESTAMP DEFAULT now() );

CREATE TABLE runs ( id TEXT PRIMARY KEY, task_id TEXT REFERENCES tasks(id), runner TEXT, input JSONB, output JSONB, status TEXT CHECK (status IN ('queued','running','passed','failed')), artifacts TEXT[], started_at TIMESTAMP, finished_at TIMESTAMP );

CREATE TABLE attachments ( id TEXT PRIMARY KEY, task_id TEXT REFERENCES tasks(id), name TEXT, kind TEXT, mime TEXT, url TEXT, size INT, created_at TIMESTAMP DEFAULT now() );

六、前端设计（Web 工作台）

结构：

区域功能技术栈左栏任务列表（搜索、筛选、状态切换） Zustand + SWR 右栏任务详情、运行面板、上传区 Tailwind + shadcn/ui 底部实时日志控制台 WebSocket/SSE 顶部模型选择（LLM-Bridge 模式切换） Select + Context Provider 七、安全与隔离设计

Runner 容器隔离：所有 Playwright/DevTools Runner 运行于独立容器，带文件系统隔离。

命令白名单： /api/agent/code 仅能执行 codex-cli 等注册命令。

模型访问控制： LLM-Bridge 支持：

统一 API Key 管理；

访问审计；

模型路由黑白名单（例如禁止访问海外模型）。

上传验证：图片/trace 文件 MIME 检查 + 大小上限（默认 50MB）。

八、部署与扩展

推荐部署模式：

服务类型部署建议 API Gateway Node 18+ Docker 容器，内网访问 MCP Playwright MCP Sidecar mcr.microsoft.com/playwright 镜像 DevTools MCP Sidecar chrome-launcher 环境 LLM-Bridge 统一服务可独立部署，实现模型代理 Storage S3 或 MinIO 附件与 trace 存储 DB PostgreSQL 任务、运行、模型状态持久化九、未来路线图（v1 → v3）阶段特性说明 v1.0 CodeSmith + OpsMind 基础实现完成 CLI/MCP 集成、运行记录体系 v1.1 LLM-Bridge 接入国内模型 Qwen、Yi、Baichuan、Moonshot v2.0 会话上下文与任务记忆 Redis + Vector Store v2.1 Web 工作流可视化（Flow View）支持多步骤组合任务 v3.0 多代理协作模式让 CodeSmith 与 OpsMind 自动协作验证十、总结与命名哲学

CodeSmith → “写得比人快一点”

OpsMind → “想得比机器深一点”

LLM-Bridge → “连接的不是模型，而是生态”

三者共同组成一个统一的“Agent Infra”，能运行在开发机、CI/CD 管道、甚至本地容器中，为 Cloud-Neutral 工程体系提供智能层。

6.5 KiB Raw Blame History Unescape Escape

6.5 KiB

Raw Blame History