9e1112758a
- 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
214 lines
6.5 KiB
Markdown
214 lines
6.5 KiB
Markdown
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
|
||
四、功能说明
|
||
1. 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 记录，并关联到任务。
|
||
|
||
2. 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状态更新
|
||
|
||
3. 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 工程体系提供智能层。
|