Agent系列二：项目架构设计

1.1 项目整体架构设计

1.1.1 为什么需要工程架构设计

AI Agent 项目很容易从一个简单 Demo 开始：

txt 复制代码

一个页面
  -> 一个接口
  -> 调一次模型
  -> 返回文本

这种结构适合快速验证模型能力，但不适合支撑生产级 Agent。

随着功能演进，系统会逐渐包含：

用户登录
会话管理
消息存储
流式输出
工具调用
文件上传
文档解析
向量检索
Agent 运行状态
审批系统
审计日志
成本统计
多 Agent 协作
MCP 工具接入
异步任务
部署与监控

如果一开始没有清晰的工程边界，后续会出现：

前端直接处理过多业务逻辑
后端 Controller 中混入模型调用、工具调用和状态管理
Agent 执行过程无法追踪
工具权限和审批难以补上
文件、消息、日志和任务数据混乱
多人协作时目录结构不清晰
部署时无法独立扩展服务

1.1.2 主线架构选择

本系列主线采用：

txt 复制代码

Next.js 前端
+ FastAPI 后端 API
+ 独立 Agent 服务
+ PostgreSQL
+ Redis
+ MinIO / S3 兼容对象存储
+ Docker Compose

整体架构：

flowchart TD User[用户] --> Web[apps/web\nNext.js 前端] Web --> API[services/api\nFastAPI 后端 API] API --> DB[(PostgreSQL)] API --> Redis[(Redis)] API --> ObjectStorage[MinIO / S3 对象存储] API --> Agent[services/agent\nAgent Runtime] Agent --> Model[大模型 Provider] Agent --> Tools[工具系统] Agent --> Redis Agent --> DB Agent --> ObjectStorage Tools --> MCP[MCP Servers]

其中：

apps/web 负责用户界面。
services/api 负责业务 API 和数据边界。
services/agent 负责 Agent 的推理、工具调用和运行状态。
packages/shared 负责共享类型、协议、事件格式和工具 Schema。
infra 负责本地基础设施、Docker Compose、Nginx、初始化脚本等。

1.1.3 为什么使用 Monorepo

Monorepo 是把多个相关项目放在同一个代码仓库中统一管理。

本项目中的 Monorepo 包含：

txt 复制代码

前端应用
后端 API 服务
Agent 服务
共享类型包
基础设施配置

使用 Monorepo 的价值：

统一上下文

前端、后端、Agent 服务围绕同一个产品演进，放在同一仓库中更容易理解整体系统。

共享类型和协议

例如消息事件、工具调用事件、审批状态、Agent Run 状态，可以放在 packages/shared 中，避免前后端各写一套。

方便本地开发

通过一套 Docker Compose 和启动脚本即可启动所需服务。

方便版本管理

同一次功能变更可能同时涉及前端、后端和 Agent 服务，在同一仓库中提交更容易保持一致性。

1.1.4 Monorepo 的风险

Monorepo 也有风险：

目录可能越来越大
不同服务依赖可能互相污染
构建和测试可能变慢
权限边界容易模糊
没有规范时容易变成"大杂烩"

因此需要从一开始约定边界：

前端不能直接访问数据库
前端不能直接持有后端密钥
后端 API 不直接写复杂 Agent 编排逻辑
Agent 服务不直接处理登录注册页面逻辑
共享包只放协议、类型、常量，不放复杂业务实现
基础设施配置放入 infra

1.2 前端、后端、Agent 服务如何拆分

1.2.1 前端 Web 的职责

apps/web 是用户直接接触的界面层。

它负责：

登录页
Agent 工作台页面
会话列表页面
设置页面
知识库页面
聊天输入框
流式输出展示
Markdown 和代码高亮展示
Tool Call Timeline
Agent 运行状态展示
审批弹窗
文件上传入口
错误提示和重试按钮

它不应该负责：

直接调用大模型 API
直接访问数据库
保存敏感密钥
绕过后端执行工具
判断用户是否有数据库级权限
执行高风险工具

前端可以做交互层校验，但最终权限和安全判断必须在后端完成。

1.2.2 后端 API 的职责

services/api 是业务系统边界。

它负责：

用户注册与登录
JWT 鉴权
用户权限和租户隔离
会话管理
消息管理
文件上传与文档元数据
Agent Run 创建和查询
工具调用记录查询
审批请求创建和处理
审计日志写入
OpenAPI 文档
与 Agent 服务通信

后端 API 是用户数据的守门人。

它不应该变成：

大量 Prompt 拼接逻辑堆积的地方
所有工具执行逻辑堆积的地方
所有 Agent 状态机逻辑堆积的地方

这些逻辑应放入 Agent 服务或专门的工具模块中。

1.2.3 Agent 服务的职责

services/agent 是 Agent Runtime 所在位置。

它负责：

ModelClient 封装
Prompt 模板管理
Agent Loop
工具选择
工具调用
工具参数校验
工具执行状态
Agent Run 状态更新
长任务执行
LangGraph 编排
MCP Client 集成
RAG 检索调用
中断与恢复
审批后继续执行
Tracing Span 上报

Agent 服务不应该负责：

用户注册登录页面
前端 UI 状态
直接暴露无鉴权 API 给用户
绕过 API 服务访问任意用户数据

Agent 服务可以访问数据库和 Redis，但必须遵守后端传递的用户上下文和权限边界。

1.2.4 API 服务与 Agent 服务的边界

API 服务和 Agent 服务的关系可以理解为：

txt 复制代码

API 服务：负责业务入口和权限边界
Agent 服务：负责智能执行和运行过程

对比表：

能力	API 服务	Agent 服务
用户登录	负责	不负责
JWT 校验	负责	接收校验后的用户上下文
会话和消息 API	负责	可写入运行结果
文件上传入口	负责	可读取已授权文件内容
Agent Run 创建	负责入口	负责执行过程
Tool Call 执行	可做权限前置	负责具体调用
高风险审批	负责审批记录和用户操作	负责触发和等待审批结果
Prompt 管理	可查询版本	负责使用 Prompt
模型调用	不直接处理复杂编排	负责
Tracing	查询和展示	生成和上报
OpenAPI 文档	负责	可提供内部 API 文档

一个典型请求流程：

txt 复制代码

用户发送消息
  -> Web 调用 API
  -> API 校验用户身份
  -> API 保存用户消息
  -> API 创建 Agent Run
  -> API 调用 Agent 服务执行
  -> Agent 服务进行模型调用和工具调用
  -> Agent 服务写入运行状态和工具记录
  -> API 将流式事件转发给 Web
  -> Web 展示回答和执行轨迹

1.2.5 为什么不把 Agent 全放在前端

有些简单 AI 应用会直接在 Next.js API Route 或前端 Server Action 中调用模型。

这适合简单聊天应用，但不适合作为生产级 Agent 主线。

原因：

Agent 需要长任务和状态恢复
Agent 需要访问数据库、Redis、对象存储
Agent 需要工具权限和审批
Agent 需要审计日志和 Tracing
Agent 需要与后台 Worker 或任务队列结合
Agent 后续可能需要独立扩缩容

因此把 Agent Runtime 作为独立服务，为后续 Workflow Agent、MCP Agent、Production Agent 留出空间。

1.3 目录结构设计

1.3.1 基础目录结构

我这里主线项目命名为：

txt 复制代码

ai-agent-platform/

基础结构：

txt 复制代码

ai-agent-platform/
  apps/
    web/                    # Next.js 前端
  services/
    api/                    # FastAPI 后端 API
    agent/                  # Agent Runtime 服务
  packages/
    shared/                 # 共享类型、协议、工具 Schema
  infra/
    docker-compose.yml      # 本地开发环境
    nginx/                  # 反向代理配置，后续部署使用
    scripts/                # 初始化脚本、迁移脚本、启动脚本
  docs/                     # 项目文档
  .env.example              # 环境变量示例
  .gitignore
  README.md

说明：

.env 不应提交到 Git。
.env.example 可以提交，用于说明需要哪些配置。

1.3.2 前端目录

apps/web 后续可演进为：

txt 复制代码

apps/web/
  app/
    layout.tsx
    page.tsx
    login/
      page.tsx
    workspace/
      page.tsx
    conversations/
      page.tsx
    knowledge/
      page.tsx
    settings/
      page.tsx
  components/
    chat/
    layout/
    tool-call/
    approval/
    common/
  lib/
    api-client.ts
    auth.ts
    stream.ts
  styles/
    globals.css
  package.json
  tsconfig.json
  next.config.ts

1.3.3 后端 API 目录

services/api 后续可演进为：

txt 复制代码

services/api/
  app/
    main.py
    core/
      config.py
      security.py
      logging.py
    api/
      routes/
        health.py
        auth.py
        users.py
        conversations.py
        messages.py
        agent_runs.py
        documents.py
        approvals.py
    domain/
      models/
    schemas/
    services/
    repositories/
    db/
      session.py
      migrations/
    integrations/
      agent_client.py
  tests/
  pyproject.toml

分层说明：

api/routes：处理 HTTP 请求和响应。
schemas：请求与响应结构。
services：业务逻辑。
repositories：数据库读写。
domain：领域模型和业务对象。
core：配置、安全、日志。
integrations：与 Agent 服务、对象存储、第三方服务集成。
db：数据库连接和迁移。

1.3.4 Agent 服务目录

services/agent 后续可演进为：

txt 复制代码

services/agent/
  app/
    main.py
    core/
      config.py
      logging.py
    runtime/
      loop.py
      state.py
      events.py
    models/
      client.py
      providers/
        openai.py
        anthropic.py
        mock.py
    prompts/
      system.md
      tools.md
    tools/
      registry.py
      base.py
      builtin/
        current_time.py
        calculator.py
        document_search.py
    rag/
      retriever.py
      embeddings.py
    mcp/
      client.py
    workflows/
      graph.py
    tracing/
      spans.py
  tests/
  pyproject.toml

1.3.5 共享包目录

packages/shared 用于存放跨服务共享的协议和类型。

如果前后端都使用 TypeScript，可以直接共享 TS 类型；但本系列后端和 Agent 服务采用 Python，因此共享包更适合存放：

JSON Schema
OpenAPI 生成类型
事件协议说明
常量定义
消息类型规范
Tool Call 事件格式
Agent Run 状态枚举

结构：

txt 复制代码

packages/shared/
  schemas/
    message.schema.json
    tool-call.schema.json
    agent-run.schema.json
    approval.schema.json
  protocols/
    stream-events.md
    tool-events.md
  constants/
    agent-status.json
    tool-risk-level.json

也可以在项目成熟后再引入代码生成流程，例如：

txt 复制代码

OpenAPI -> 前端 TypeScript Client
JSON Schema -> Python / TypeScript 类型

1.4 技术栈选择

1.4.1 前端：Next.js / React / TypeScript / Tailwind CSS

选择原因：

Next.js 适合构建全栈 React 应用。
App Router 支持现代路由和布局组织。
React 适合构建复杂交互组件，例如 Chat UI、Tool Timeline、审批弹窗。
TypeScript 有助于管理消息、工具调用、流式事件等复杂类型。
Tailwind CSS 适合快速构建统一风格的界面。
与 Vercel AI SDK、流式输出、Server Components 生态结合较好。

在本系列中，前端重点不是只做聊天框，而是要实现：

消息流
工具调用可视化
运行轨迹
审批交互
错误和重试
引用来源展示
任务状态展示

1.4.2 后端：FastAPI

选择原因：

Python 生态适合 AI、RAG、LangGraph、Embedding 和数据处理。
FastAPI 支持类型声明和自动 OpenAPI 文档。
Pydantic 适合请求校验和结构化数据定义。
异步能力适合流式输出和服务间通信。
学习成本相对清晰。

后端 API 在本项目中承担：

鉴权
数据边界
会话和消息管理
文件管理
审批系统
审计日志
Agent Run 查询

1.4.4 数据库：PostgreSQL

PostgreSQL 用于保存核心业务数据：

users
conversations
messages
agent_runs
tool_calls
documents
document_chunks
approvals
audit_logs

后续如果使用 pgvector，也可以直接在 PostgreSQL 中保存向量数据。

选择 PostgreSQL 的原因：

关系型数据表达能力强
适合用户、会话、消息、审批、审计等结构化数据
生态成熟
可扩展 pgvector
适合从 Demo 过渡到真实产品

1.4.5 缓存与队列：Redis

Redis 在本项目中可承担：

缓存
任务队列
Agent 运行中的临时状态
流式事件缓冲
限流计数
分布式锁
会话辅助状态

1.4.6 对象存储：MinIO / S3 兼容存储

对象存储用于保存用户上传的文件，例如：

PDF
Markdown
TXT
DOCX
图片
解析后的中间文件

本地开发建议使用 MinIO。

生产环境可以替换为：

AWS S3
阿里云 OSS
腾讯云 COS
Cloudflare R2
其他 S3 兼容服务

对象存储不要直接暴露给用户绕过权限访问，文件访问应经过后端授权。

1.4.7 Docker Compose

Docker Compose 用于统一本地开发环境。

前期包含：

PostgreSQL
Redis
MinIO

后续可逐步加入：

API 服务
Agent 服务
Web 服务
向量数据库
OpenTelemetry Collector
Phoenix / LangSmith 相关服务
Nginx

Docker Compose 的目标是让项目具备可复现的本地环境。

1.5 环境变量与密钥管理

1.5.1 为什么环境变量很重要

AI Agent 项目会涉及大量配置和密钥：

数据库连接信息
Redis 地址
对象存储账号
JWT 密钥
大模型 API Key
Embedding 模型配置
MCP Server 地址
Tracing Endpoint
外部搜索 API Key

这些信息不能硬编码在代码中，也不能提交到 Git。

正确做法：

.env 保存本地真实配置，不提交
.env.example 保存变量名称和示例值，可以提交
生产环境通过平台 Secret 管理
前端只能读取允许暴露的变量
后端和 Agent 服务保存敏感密钥

1.5.2 环境变量分层

按服务分层：

txt 复制代码

根目录 .env
apps/web/.env.local
services/api/.env
services/agent/.env
infra/.env

初期也可以先使用根目录 .env 简化管理，后续再拆分。

1.5.3 根目录 `.env.example` 示例

示例：

env 复制代码

# Application
APP_ENV=development
APP_NAME=ai-agent-platform

# Web
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_APP_NAME=AI Agent Platform

# API
API_HOST=0.0.0.0
API_PORT=8000
JWT_SECRET=change-me-in-local-env
JWT_EXPIRES_IN=3600

# Agent
AGENT_HOST=0.0.0.0
AGENT_PORT=8001
AGENT_INTERNAL_TOKEN=change-me-in-local-env

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=ai_agent_platform
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_agent_platform

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_URL=redis://localhost:6379/0

# Object Storage / MinIO
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=agent-files

# LLM Providers
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
DEFAULT_MODEL_PROVIDER=mock
DEFAULT_MODEL_NAME=mock-model

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT=
TRACING_ENABLED=false

注意：

.env.example 中不要写真实密钥。
JWT_SECRET、OPENAI_API_KEY、ANTHROPIC_API_KEY 这类变量必须在真实 .env 中配置。
前端环境变量如果以 NEXT_PUBLIC_ 开头，会暴露给浏览器，因此不能放密钥。

1.5.4 前端环境变量

前端可使用：

env 复制代码

NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_APP_NAME=AI Agent Platform

前端不能使用：

env 复制代码

OPENAI_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
DATABASE_URL=xxx
JWT_SECRET=xxx

原因：

浏览器端变量可能被用户看到。
前端不应持有模型 API Key。
前端不应直接连接数据库。

1.5.5 后端 API 环境变量

后端 API 需要：

env 复制代码

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_agent_platform
REDIS_URL=redis://localhost:6379/0
JWT_SECRET=change-me
AGENT_SERVICE_URL=http://localhost:8001
AGENT_INTERNAL_TOKEN=change-me
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=agent-files

后端 API 可以知道：

数据库地址
Redis 地址
对象存储密钥
JWT 密钥
Agent 服务内部访问凭证

但后端 API 不应把这些密钥返回给前端。

1.5.6 Agent 服务环境变量

Agent 服务需要：

env 复制代码

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_agent_platform
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
DEFAULT_MODEL_PROVIDER=mock
DEFAULT_MODEL_NAME=mock-model
AGENT_INTERNAL_TOKEN=change-me
TRACING_ENABLED=false

Agent 服务保存模型相关配置。

开发早期建议默认使用：

env 复制代码

DEFAULT_MODEL_PROVIDER=mock

这样可以在没有真实模型 API Key 的情况下先完成系统骨架。

1.5.7 API Key 管理原则

必须遵守：

不把真实 API Key 写入代码
不把真实 API Key 提交到 Git
不在日志中打印完整密钥
不把后端密钥暴露给前端
不在错误信息中返回密钥
不让模型看到不必要的系统密钥
不把用户上传文档中的内容当作系统指令执行

密钥泄露是 AI 应用中非常常见的安全问题，从项目第一天就要避免。

1.6 Docker Compose 本地环境

1.6.1 本地环境目标

本地开发环境至少需要：

txt 复制代码

PostgreSQL
Redis
MinIO

后续可以把 Web、API、Agent 也加入 Docker Compose。

初期建议：

基础设施用 Docker Compose 启动
Web、API、Agent 可以先在本机开发模式启动

这样便于调试。

1.6.2 Docker Compose 基础示例

infra/docker-compose.yml 示例：

yaml 复制代码

services:
  postgres:
    image: postgres:16
    container_name: ai-agent-postgres
    environment:
      POSTGRES_DB: ai_agent_platform
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d ai_agent_platform"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    container_name: ai-agent-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio:latest
    container_name: ai-agent-minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

volumes:
  postgres_data:
  redis_data:
  minio_data:

说明：

PostgreSQL 端口：5432
Redis 端口：6379
MinIO API 端口：9000
MinIO 控制台端口：9001

1.6.3 后续加入应用服务的 Compose 思路

后续可以扩展为：

yaml 复制代码

services:
  web:
    build:
      context: ../apps/web
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_BASE_URL: http://localhost:8000
    depends_on:
      - api

  api:
    build:
      context: ../services/api
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/ai_agent_platform
      REDIS_URL: redis://redis:6379/0
      AGENT_SERVICE_URL: http://agent:8001
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  agent:
    build:
      context: ../services/agent
    ports:
      - "8001:8001"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/ai_agent_platform
      REDIS_URL: redis://redis:6379/0
      DEFAULT_MODEL_PROVIDER: mock
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

1.6.4 数据库初始化策略

数据库初始化分为三个层次：

层次 1：容器启动

Docker Compose 启动 PostgreSQL 容器，并创建初始数据库。

层次 2：迁移工具建表

后续引入数据库迁移工具，例如 Alembic。

用于创建：

users
conversations
messages
agent_runs
tool_calls
documents
approvals
audit_logs

层次 3：Seed 数据

可选，用于插入开发环境测试数据：

测试用户
示例会话
示例文档
示例工具配置

1.6.5 Redis 初始化策略

Redis 不需要像 PostgreSQL 一样建表，但需要规划用途。

后续可能使用的 key 设计：

txt 复制代码

agent:run:{run_id}:state
agent:run:{run_id}:events
rate_limit:user:{user_id}
task:queue:agent
approval:{approval_id}:status

注意：

Redis 中的数据默认可过期，不应作为唯一长期存储。
关键业务数据仍应写入 PostgreSQL。
Redis 适合缓存、队列、临时状态和限流。

1.6.6 MinIO 初始化策略

MinIO 用于模拟 S3。

后续需要：

创建 bucket，例如 agent-files
上传用户文件
保存文件对象 key
在 PostgreSQL 中保存文件元数据
解析文件后保存 chunks 和 embeddings

对象存储中保存文件内容。数据库中保存文件记录和权限信息。

1.7 本地开发环境与生产环境差异

1.7.1 本地开发环境

本地开发环境关注：

容易启动
容易调试
日志清晰
允许使用 Mock Provider
可以使用简单密钥
可以使用本地 MinIO
可以暴露数据库端口给开发者工具

典型配置：

txt 复制代码

APP_ENV=development
DEFAULT_MODEL_PROVIDER=mock
TRACING_ENABLED=false
POSTGRES_HOST=localhost
REDIS_HOST=localhost

1.7.2 测试环境

测试环境关注：

自动化测试
数据可重置
使用独立数据库
使用 Mock 模型或测试模型
不连接真实生产资源
能运行 API 测试、工具测试、Prompt 回归测试

典型配置：

txt 复制代码

APP_ENV=test
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_agent_test
DEFAULT_MODEL_PROVIDER=mock

1.7.3 生产环境

生产环境关注：

安全
稳定
数据备份
日志和监控
密钥托管
服务健康检查
资源隔离
成本控制

生产环境要求：

使用强随机 JWT_SECRET
使用平台 Secret 管理 API Key
数据库不直接暴露公网
Redis 不直接暴露公网
对象存储启用权限控制
启用 HTTPS
启用日志、Tracing 和告警
对高风险工具启用审批
对模型调用设置限流和成本配额

1.7.4 环境差异对比

项目	本地开发	测试环境	生产环境
模型 Provider	mock 或真实测试 Key	mock 优先	真实 Provider
数据库	本地 Docker	独立测试库	托管或高可用数据库
Redis	本地 Docker	独立测试 Redis	托管或集群 Redis
对象存储	MinIO	测试 Bucket	S3/OSS/COS/R2
密钥管理	`.env`	CI Secret	云平台 Secret
日志	控制台	测试日志	集中日志
Tracing	可关闭	可选开启	应开启
数据隔离	开发数据	测试数据	真实用户数据

1.7.5 `.gitignore` 建议

必须忽略：

gitignore 复制代码

# env
.env
.env.local
.env.*.local

# dependencies
node_modules/
.venv/
__pycache__/
*.pyc

# build
.next/
dist/
build/

# logs
*.log
logs/

# local data
.data/
.minio/
postgres_data/
redis_data/

# OS / editor
.DS_Store
.vscode/
.idea/

不要提交：

真实 .env
API Key
用户上传文件
数据库数据目录
日志中的敏感信息
私有证书

1.9 搭建项目骨架

1.9.1 创建项目目录

目标结构：

txt 复制代码

ai-agent-platform/
  apps/
  services/
  packages/
  infra/

建议建立：

txt 复制代码

apps/web
services/api
services/agent
packages/shared
infra

1.9.2 初始化前端项目

建议使用 Next.js 初始化 apps/web。

关键选项：

TypeScript：启用
Tailwind CSS：启用
App Router：启用
ESLint：启用
src 目录：可按团队习惯选择

前端验收目标：

能打开首页
能显示项目名称
能读取 NEXT_PUBLIC_API_BASE_URL
不需要实现完整聊天界面

示例首页内容可以是：

txt 复制代码

AI Agent Platform
个人智能助理 Agent 平台

1.9.3 初始化后端 API 项目

services/api 中建立 FastAPI 基础结构。

最小健康检查接口：

python 复制代码

from fastapi import FastAPI

app = FastAPI(title="AI Agent Platform API")

@app.get("/health")
def health_check():
    return {"status": "ok", "service": "api"}

后端验收目标：

API 服务能启动
/health 返回正常
OpenAPI 文档可以访问
配置结构预留 DATABASE_URL、REDIS_URL、AGENT_SERVICE_URL

1.9.4 初始化 Agent 服务

services/agent 中建立 FastAPI 或轻量 HTTP 服务入口。

最小健康检查接口：

python 复制代码

from fastapi import FastAPI

app = FastAPI(title="AI Agent Runtime")

@app.get("/health")
def health_check():
    return {"status": "ok", "service": "agent"}

Agent 服务验收目标：

Agent 服务能启动
/health 返回正常
预留 ModelClient、tools、runtime 目录
不需要实现真正模型调用

1.9.5 初始化 Docker Compose

在 infra/docker-compose.yml 中定义：

PostgreSQL
Redis
MinIO

启动后验证：

PostgreSQL 端口可访问
Redis PING 正常
MinIO 控制台可打开

1.9.6 建立环境变量示例文件

根目录创建 .env.example，但不要创建或提交真实 .env。

至少包含：

NEXT_PUBLIC_API_BASE_URL
DATABASE_URL
REDIS_URL
JWT_SECRET
AGENT_SERVICE_URL
OPENAI_API_KEY
ANTHROPIC_API_KEY
DEFAULT_MODEL_PROVIDER

1.9.7 建立共享协议目录

在 packages/shared 中预留：

txt 复制代码

schemas/
protocols/
constants/

可以先创建协议草案，例如流式事件类型：

txt 复制代码

message.delta
message.done
tool.started
tool.completed
tool.failed
approval.required
run.completed
run.failed

这些协议会在后续逐步落地。

2. 常见误区

1.1 误区一：所有代码放在一个服务里更简单

短期看更简单，长期会导致权限、状态、工具、模型调用和 UI 混乱。生产级 Agent 需要清晰边界。

2.2 误区二：前端可以直接调用模型 API

前端直接调用模型 API 会泄露密钥，也绕过了后端权限、审计、成本控制和审批系统。

2.3 误区三：Agent 服务和 API 服务没有必要拆分

简单 Demo 可以不拆，但工程目标包括长任务、工具调用、LangGraph、MCP、多 Agent 和可观测性，独立 Agent 服务更适合演进。

2.4 误区四：`.env.example` 可以写真实密钥

.env.example 只能写变量名和示例值，不能出现真实 API Key、JWT Secret、数据库密码。

2.5 误区五：Redis 可以保存所有业务数据

Redis 适合缓存、队列、临时状态。长期业务数据仍应保存到 PostgreSQL。

2.6 误区六：对象存储只保存文件，不需要数据库记录

对象存储保存文件内容，数据库保存文件元数据、用户归属、解析状态、权限和引用关系。

2.7 误区七：前期开发不需要考虑安全

Agent 后续会调用工具和访问用户数据。权限、密钥、审计、审批必须从架构初期预留。

3. 关键术语表

术语	含义
Monorepo	多个相关项目放在同一个代码仓库统一管理
apps/web	前端应用目录，负责用户界面和交互
services/api	后端 API 服务目录，负责业务接口、权限和数据边界
services/agent	Agent Runtime 服务目录，负责模型调用、工具调用和 Agent 编排
packages/shared	共享协议、类型、Schema、常量目录
infra	基础设施配置目录，如 Docker Compose、Nginx、脚本
Docker Compose	用于定义和启动多容器本地环境的工具
PostgreSQL	关系型数据库，保存用户、会话、消息、工具调用、审计等数据
Redis	缓存、队列、临时状态和限流组件
MinIO	本地 S3 兼容对象存储，用于保存上传文件
`.env`	本地真实环境变量文件，不应提交
`.env.example`	环境变量示例文件，可提交
JWT Secret	用于签名和校验 JWT 的敏感密钥
API Service	业务 API 边界，负责用户请求和权限控制
Agent Runtime	Agent 运行时，负责规划、工具调用、模型调用和状态更新
Health Check	健康检查接口，用于判断服务是否正常运行
Conventional Commits	一种规范化提交信息格式
Secret	密钥或敏感配置，例如模型 API Key、数据库密码

Agent系列二：项目架构设计

1.1 项目整体架构设计

1.1.1 为什么需要工程架构设计

1.1.2 主线架构选择

1.1.3 为什么使用 Monorepo

统一上下文

共享类型和协议

方便本地开发

方便版本管理

1.1.4 Monorepo 的风险

1.2 前端、后端、Agent 服务如何拆分

1.2.1 前端 Web 的职责

1.2.2 后端 API 的职责

1.2.3 Agent 服务的职责

1.2.4 API 服务与 Agent 服务的边界

1.2.5 为什么不把 Agent 全放在前端

1.3 目录结构设计

1.3.1 基础目录结构

1.3.2 前端目录

1.3.3 后端 API 目录

1.3.4 Agent 服务目录

1.3.5 共享包目录

1.4 技术栈选择

1.4.1 前端：Next.js / React / TypeScript / Tailwind CSS

1.4.2 后端：FastAPI

1.4.4 数据库：PostgreSQL

1.4.5 缓存与队列：Redis

1.4.6 对象存储：MinIO / S3 兼容存储

1.4.7 Docker Compose

1.5 环境变量与密钥管理

1.5.1 为什么环境变量很重要

1.5.2 环境变量分层

1.5.3 根目录 .env.example 示例

1.5.4 前端环境变量

1.5.5 后端 API 环境变量

1.5.6 Agent 服务环境变量

1.5.7 API Key 管理原则

1.6 Docker Compose 本地环境

1.6.1 本地环境目标

1.6.2 Docker Compose 基础示例

1.6.3 后续加入应用服务的 Compose 思路

1.6.4 数据库初始化策略

层次 1：容器启动

层次 2：迁移工具建表

层次 3：Seed 数据

1.6.5 Redis 初始化策略

1.6.6 MinIO 初始化策略

1.7 本地开发环境与生产环境差异

1.7.1 本地开发环境

1.7.2 测试环境

1.7.3 生产环境

1.7.4 环境差异对比

1.7.5 .gitignore 建议

1.9 搭建项目骨架

1.9.1 创建项目目录

1.9.2 初始化前端项目

1.9.3 初始化后端 API 项目

1.9.4 初始化 Agent 服务

1.9.5 初始化 Docker Compose

1.9.6 建立环境变量示例文件

1.9.7 建立共享协议目录

2. 常见误区

1.1 误区一：所有代码放在一个服务里更简单

2.2 误区二：前端可以直接调用模型 API

2.3 误区三：Agent 服务和 API 服务没有必要拆分

2.4 误区四：.env.example 可以写真实密钥

2.5 误区五：Redis 可以保存所有业务数据

2.6 误区六：对象存储只保存文件，不需要数据库记录

2.7 误区七：前期开发不需要考虑安全

3. 关键术语表

1.5.3 根目录 `.env.example` 示例

1.7.5 `.gitignore` 建议

2.4 误区四：`.env.example` 可以写真实密钥