多智能体协作平台 Zodiac Studio 架构与开发计划

一、项目概述

Zodiac Studio 是一个现代化的 SaaS 级多智能体协作平台，旨在通过 AI Agent 团队（包含产品经理、UI/UX设计师、前端开发、QA等）协同工作，对你在 GitHub 上的 kdytrucking-sudo/Zodiac 项目进行持续迭代和增量式升级。

核心特点：

不使用缓慢的 MCP UI 生成器，回归现代 SaaS 风格的手写前端架构。
强制使用本地 codex CLI 接管所有底层代码编写、文件修改和沙盒执行，严禁 LLM 在平台层直接输出不可靠的大段代码覆盖文件。
支持 全自动全量执行 与 人工步进干预 (Human-in-the-loop) 两种模式。
提供直观的实时 Web 控制台，实时观测每一位 Agent 成员的工作状态与代码产出。

二、系统总体架构

系统采用前后端分离架构，通过 REST API 和 WebSocket 保证各节点通信的高时效性。

[ 浏览器前端 (React / Next.js) ]
  ├─ 主控制台: 项目历史运行记录、文件及需求上传入口、一键执行面板
  ├─ 状态看板: 通过 WebSocket 实时展示每位 Agent (PM/UX/DEV/QA) 的当前思考状态和流式日志
  └─ Agent 独立视图: 每个 Agent 拥有独立的参数配置页 (Prompt、挂载的技能、所用模型等)
       │ (REST API + WebSocket)
       ▼
[ 平台后端 (Python / FastAPI + openai-agents-python) ]
  ├─ API Server: 处理前端指令、管理数据库、配置动态技能与模型 (Doubao / Gemini)
  ├─ 编排引擎 (Orchestration): 维护 Handoffs 逻辑，根据用户选择的模式调度 Agent
  └─ WebSocket Manager: 将底层 openai-agents 的 Hooks 执行状态 (RunResultStreaming) 推送至前端
       │ (Subprocess / Shell Exec)
       ▼
[ 本地基础设施与执行环境 (Ubuntu ARM64) ]
  ├─ Codex CLI (v0.122.0+): [核心引擎] 由平台层调起，使用特定的 Model Version (如 gpt-5.3-codex 或 gpt-5.4) 真实写入和修改文件
  ├─ Git Engine: 自动拉取 (Fresh Clone) kdytrucking-sudo/Zodiac 源码，支持 Diff 展示和 Commit Push
  ├─ Nginx: 将结果映射至 zodiacstudio.laraks.com 提供预览
  └─ PostgreSQL / SQLite: 持久化每次 Agent 运行的 Prompt 历史、配置、执行结果和日志

三、核心工作流与 Agent 职能拆解

平台的核心工作流将严格遵循：PM -> UX/UI -> Coder -> QA 的流转顺序。

1. Project Manager Agent (项目总控)

职责: 接收在“主控制台”输入的总需求（例如：“把首页卡片改成塔罗牌风格”）和任何形式的参考文档（图片、PDF、TXT）。进行需求拆解并分发任务。
界面与功能: 独立面板。可查看其历史分发记录，支持人工干预审批。

2. UI/UX Designer Agent (视觉设计师)

职责: 分析现有页面 HTML，制定纯文本的、包含详细 Tailwind 规范的“设计草图”与“组件修改建议”。
界面与功能: 独立面板。允许用户指定要重新设计的页面；允许挂载 awesome-design-md 等本地文件作为 Skill 提供设计规范指导。
备注: 摒弃 Stitch 等依赖谷歌接口的 MCP，使用快速的大模型上下文读取现有代码，或在必要时由后台启用 Local Canvas 生成快照辅助分析。

3. Frontend Coder Agent (前端程序员 - 核心！)

职责: 它本身不写代码。 它的任务是将 PM 的需求和 UX 的草图整合，转化并拼装成一句精妙的终端命令，然后调用本地的 codex exec。
执行方式: 例如在后台调用子进程 codex exec --model gpt-5.3-codex --full-auto "Replace index.html layout according to this spec..."。
界面与功能: 独立面板。用户可在此为 Coder 指定具体的 --model 版本（例如强制使用针对编程优化的 5.3，而非默认的 5.4）。可设定其是否自动 git commit。

4. QA Engineer Agent (测试与审查)

职责: 在 Coder 完成文件修改后，负责对比 git diff，寻找可能存在的闭合标签缺失或 Tailwind 语法错误。如果发现问题，打回重写。

四、核心数据库表结构 (Schema Outline)

平台推荐使用 SQLite（前期轻量，随时可转 PG）存储状态：

projects:
- id, name, github_repo, local_path, domain, created_at
models:
- id, provider (e.g., openai, volcengine, google), model_id (e.g., gpt-5.3-codex, ep-xxx, gemini-1.5-pro), api_key (加密)
agents:
- id, project_id, role_name, system_prompt, model_id, execution_order
agent_skills:
- id, agent_id, skill_name_or_path (e.g., awesome-design/linear.md), is_active
runs (执行批次):
- id, project_id, run_mode (Auto / Manual), user_prompt, status, started_at, completed_at
agent_logs (单次智能体执行明细):
- id, run_id, agent_id, log_content (Streaming result), diff_output, status

五、 Nginx 与部署配置

平台前后端编译后，将部署在你当前的机器上。
配置 Cloudflare DNS zodiacstudio.laraks.com -> 129.146.165.136。
Nginx 将反向代理 /api 到后端的 FastAPI (例如 127.0.0.1:8000)。
Nginx 将反向代理 /ws 协议提供 WebSocket 支持。
前端 React 静态文件由 Nginx 直接提供访问服务。

六、分阶段实施路线图 (Implementation Roadmap)

Phase 1: 核心引擎与基础设施 (1周)

搭建 FastAPI 后端基础框架与 SQLite 数据库。
实现 openai-agents-python SDK 的后端接入，配置 Doubao 与 Gemini 模型鉴权逻辑。
封装对本地 codex exec 的底层调用函数（Subprocess Wrapper），确保模型指令能安全地在目标代码目录执行。

Phase 2: 后台 API 与 WebSockets 实时流 (1-2周)

定义所有必要的数据接口（Agent 增删改查、Skill 挂载、Model 切换）。
实现 Agentic Workflow 的状态机：处理 Manual (人工单步点击) 与 Full-Auto (自动流水线) 两种模式的 Handoff。
构建 WebSocket 广播通道，能够捕获 Runner 的实时 Stream Event 并推给前端。

Phase 3: 前端控制台 (React/Next.js) 开发 (2周)

Main Dashboard: 实现历史执行列表、带附件上传（TXT/PDF/图像）的全局需求输入框。
Agent Setup View: 开发智能体配置界面，支持系统提示词热编辑，以及下拉选择模型 (如 gpt-5.3-codex / gemini)。
Theater/Chat View: 核心！实现类似 Terminal 的动态日志打印界面，展示 Agent 们的“群聊”和思考过程。

Phase 4: Git 整合与联调 (1周)

引入 Git 模块：每次任务启动前，系统自动 git clone/pull kdytrucking-sudo/Zodiac。
在 Coder 和 QA 执行结束后，在前端展示 git diff 结果面板。
提供前端 "Approve & Push" 按钮，一键将代码提交至 Github。

设计方案由 Zodiac Studio 架构组生成 | 2026-04