> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 平台架构

> 袋袋系统架构总览：五大服务、三层环境、数据流全景

袋袋采用微服务架构，将 AI Agent 的创造、运行、交互三个核心能力拆分为独立可扩展的服务集群。整个平台运行在腾讯云 TKE（Kubernetes）之上，通过三套环境（测试 / UAT / 生产）实现安全的渐进式发布。

## 架构全景

```mermaid theme={null}
graph TB
    subgraph 用户层
        Browser[浏览器/客户端]
        IDE[IDE 插件]
        IM[IM 平台<br/>飞书/钉钉/企微]
    end

    subgraph 接入层
        Nginx[Nginx 网关<br/>路由 + TLS + 限流]
    end

    subgraph 应用服务
        Web[Web 前端<br/>Next.js SSR]
        Core[Core API<br/>业务中枢]
        Runtime[智能体运行时<br/>AI 推理引擎]
        Marketing[官网<br/>SSR/ISR]
        Platform[开发者平台<br/>API 管理]
    end

    subgraph AI 执行层
        Sandbox[云端沙盒<br/>隔离容器]
        LLM[大模型服务<br/>多 Provider 路由]
    end

    subgraph 数据层
        PG[(PostgreSQL<br/>业务数据)]
        Redis[(Redis<br/>缓存/队列)]
        COS[(对象存储<br/>文件/媒体)]
    end

    Browser --> Nginx
    IDE --> Nginx
    IM --> Nginx
    Nginx --> Web
    Nginx --> Core
    Nginx --> Marketing
    Nginx --> Platform
    Web --> Core
    Platform --> Core
    Core --> Runtime
    Runtime --> Sandbox
    Runtime --> LLM
    Core --> PG
    Core --> Redis
    Core --> COS
    Runtime --> Redis
```

## 五大核心服务

<CardGroup cols={2}>
  <Card title="Web 前端" icon="browser">
    基于 Next.js 构建的全栈 Web 应用，承载用户交互界面、服务端渲染、BFF 代理层。多副本水平扩展，支持 Canary 发布。
  </Card>

  <Card title="Core API" icon="server">
    业务逻辑中枢，基于 Hono 框架提供 REST + tRPC 双轨 API。负责认证、计费、专家管理、审核流水线、订阅系统等所有业务编排。
  </Card>

  <Card title="智能体运行时" icon="brain">
    Python 构建的 AI 推理引擎，基于 LangGraph 实现 Agent Loop。负责上下文构建、工具调度、流式输出、自进化等 AI 核心能力。
  </Card>

  <Card title="云端沙盒" icon="cube">
    为每次 AI 对话提供隔离的云容器环境，预装开发工具链。支持文件持久化、网络访问、进程隔离，亚秒级热启动。
  </Card>

  <Card title="官网 & 开发者平台" icon="globe">
    官网采用 SSR/ISR 模式部署，支持博客实时发布。开发者平台提供 API Key 管理、调用日志、用量统计。
  </Card>
</CardGroup>

## 数据流：从用户到 AI

一次典型的专家对话经过以下路径：

<Steps>
  <Step title="用户发送消息">
    用户在浏览器/IM/IDE 中发送消息，经 Nginx 路由到 Web 前端。
  </Step>

  <Step title="Core 编排请求">
    Web 将请求转发到 Core API。Core 完成身份认证、积分校验、专家配置加载、沙盒准备，然后将完整的运行时负载发送给智能体运行时。
  </Step>

  <Step title="Agent 推理循环">
    Runtime 构建上下文（历史消息 + 记忆 + 技能 + 工具声明），调用大模型进行推理。如果模型决定使用工具，Runtime 将在沙盒中执行操作，并将结果送回模型继续推理。
  </Step>

  <Step title="流式响应">
    整个过程通过 Server-Sent Events (SSE) 实时流式输出到客户端——用户看到 AI 一边思考一边回复，工具执行结果实时展现。
  </Step>
</Steps>

## Monorepo 结构

整个代码库采用 Monorepo 组织，共享类型和基础设施：

```
profy/
├── apps/              # 前端应用
│   ├── web/           # 主站（Next.js）
│   ├── platform/      # 开发者平台
│   ├── marketing/     # 官网
│   └── desktop/       # 桌面客户端
├── services/          # 后端服务
│   ├── core/          # 业务 API
│   ├── agent-runtime/ # AI 推理引擎
│   └── sandbox/ # 沙盒镜像工程
├── packages/          # 共享包
│   ├── types/         # TypeScript 类型定义
│   ├── db/            # 数据库 Schema（唯一真相源）
│   ├── auth/          # 认证共享配置
│   └── ui/            # UI 组件库
└── deploy/            # 部署配置（K8s manifests）
```

<Tip>
  所有数据库表结构定义在 `packages/db` 中，是整个系统的「唯一真相源」——任何服务需要数据模型，都从这里导入，绝不重复定义。
</Tip>

## 三层环境与发布策略

| 环境             | 用途    | 特点                       |
| -------------- | ----- | ------------------------ |
| **Test**       | 开发联调  | 快速迭代，允许不稳定               |
| **UAT**        | 预发布验证 | 与生产同配置，最后一道闸门            |
| **Production** | 线上服务  | SemVer 标签触发，支持 Canary 灰度 |

每个环境独立的 Kubernetes namespace，共享负载均衡入口但完全隔离数据。关键服务（Web、Core、Runtime）支持 Canary 副本，新版本先在小流量中验证再全量切换。

## 多 Provider 模型路由

袋袋不绑定单一大模型供应商。Core 内置统一的 Provider 管理系统，支持：

* **多供应商接入**：同时对接 DashScope、火山引擎、Anthropic、OpenAI 等
* **智能路由**：根据 RPM/TPM 配额、余额、健康状态自动选择最优 Key
* **Token 感知调度**：滑动窗口限流，避免单 Key 被打满
* **差异化参数**：不同模型按各自能力声明传参（如 temperature 兼容性）

```mermaid theme={null}
graph LR
    Request[推理请求] --> Router[Key Router]
    Router --> |RPM 最优| Key1[供应商 A - Key 1]
    Router --> |余额充足| Key2[供应商 B - Key 2]
    Router --> |健康检测| Key3[供应商 C - Key 3]
    Key1 --> LLM1[模型 A]
    Key2 --> LLM2[模型 B]
    Key3 --> LLM3[模型 C]
```

## 支撑基础设施

<Accordion title="PostgreSQL — 业务数据持久化">
  所有业务数据的持久化存储，采用 Drizzle ORM 管理 Schema 迁移。支持乐观锁并发控制、Advisory Lock 分布式互斥、分区索引优化查询性能。
</Accordion>

<Accordion title="Redis — 缓存与实时通信">
  承载会话缓存、限流计数器、分布式锁、Worker 任务队列、实时状态同步等。采用多 Key 命名空间隔离不同业务域。
</Accordion>

<Accordion title="COS 对象存储 — 文件与媒体">
  所有用户上传文件、AI 生成的媒体资源、静态资产均存储在腾讯云 COS 中。按环境隔离 Bucket，支持预签名 URL 直传和 CDN 加速。
</Accordion>

<Accordion title="IM 网关 — 多平台消息桥接">
  统一接入飞书、钉钉、企业微信等 IM 平台，将消息协议转换为标准的 Agent 调用，让专家可以「活在」用户日常使用的通信工具中。
</Accordion>

## 设计哲学

袋袋的架构遵循几个核心原则：

1. **关注点分离**：每个服务只做一件事——Core 不做推理，Runtime 不管计费，Sandbox 不碰业务逻辑
2. **声明式优于命令式**：专家的能力通过声明（技能 Manifest、工具配置）组合，而非硬编码
3. **渐进式降级**：任何外部依赖不可用时，核心对话能力不应中断——沙盒挂了走无沙盒模式，Redis 挂了走数据库兜底
4. **可观测性优先**：每个请求携带完整链路追踪，Agent 的每一步决策都有审计日志

<Note>
  这是一个活跃演进中的架构。我们持续在三个方向投入：降低 AI 推理延迟、提升沙盒冷启动速度、增强多租户隔离安全性。
</Note>