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

# 架构概览

> Myrm 平台高层架构。

# 架构概览

Myrm 由五个独立仓库组成，各承担平台中的不同角色。

## 仓库结构

| 仓库                    | 说明                 | 许可 |
| --------------------- | ------------------ | -- |
| `myrm-agent-harness`  | Python Agent 运行时引擎 | 闭源 |
| `myrm-agent-server`   | 后端 API 服务（FastAPI） | 开源 |
| `myrm-agent-frontend` | Next.js Web 应用     | 开源 |
| `myrm-agent-desktop`  | Tauri 桌面客户端        | 开源 |
| `myrm-control-plane`  | SaaS 多租户编排         | 闭源 |

### 职责分离

```
┌────────────────────────────────┐
│     myrm-control-plane         │  仅 SaaS：沙箱分配、租户路由
├────────────────────────────────┤
│     myrm-agent-server          │  业务逻辑、API、单机部署
├────────────────────────────────┤
│     myrm-agent-harness         │  Agent 运行时引擎（模型无关）
└────────────────────────────────┘
```

* **Harness** 为框架层 — 模型管理、中间件链、上下文流水线、安全、工具
* **Server** 为业务层 — 用户管理、会话持久化、API 端点、单机部署
* **Control Plane** 为编排层 — 沙箱供给、计费、多租户路由（仅 SaaS）

## 前端架构

Next.js App Router：

* **Tailwind CSS v4** 样式，支持明暗双主题
* **next-intl** 中英文国际化
* **Zustand** 客户端状态
* **WebSocket + SSE** 实时流式
* **响应式** 兼容手机与桌面

## 后端架构

Python 异步服务：

* **FastAPI** REST API
* **LiteLLM** 统一多模型访问（100+ 模型）
* **LangGraph** Agent 编排与状态管理
* **SQLite** 主数据存储（单机，无需分布式 DB）
* **Qdrant** 向量检索（记忆、技能、Wiki）
* **38+ 中间件** 链：安全、日志、审批、行为控制

## 关键架构决策

### PPAF（感知、规划、行动、反馈）循环

Myrm 核心执行循环采用 PPAF：

* **感知（Perception）**：从多模态输入提取意图，读取记忆上下文
* **规划（Planning）**：通过 Planner 中间件或 `sequentialthinking` 子 Agent 拆解复杂指令
* **行动（Action）**：通过工具执行器运行隔离沙箱内的工具与脚本
* **反馈（Feedback）**：分析工具结果，动态重规划或错误恢复

### R.E.S.T. 工程标准

Harness 层围绕 R.E.S.T.：

* **可靠性（Reliability）**：14 种动态自愈、指数退避、熔断
* **高效性（Efficiency）**：上下文压缩、缓存优化、提示词前缀保护
* **安全性（Security）**：6 层纵深防御、零信任沙箱、严格策略网关
* **可追溯性（Traceability）**：指标、结构化审计日志、细粒度会话调试

### 模块化中间件 vs 单体 Agent

Myrm 用中间件链架构，各关注点（安全、审批、循环检测、完成检查等）为独立可测模块，而非全部塞进一个大类。

### 异步优先

所有 I/O 使用 `asyncio` 协程，对 I/O 密集负载（LLM API、文件、网络）优于线程池。

### 框架与业务分离

Harness 引擎零业务逻辑，提供通用 Agent 能力（工具、记忆、安全、流式）；Server 层在其上叠加用户管理、会话与 API 契约。

### 分形自文档（开源产品层）

开源 `myrm-agent` 采用 **四层文档栈**，让贡献者与 LLM 按目录定位职责，而不是通读源码猜边界：

| 层级 | 文档                             | 作用            |
| -- | ------------------------------ | ------------- |
| L1 | `ARCHITECTURE.md`              | 系统总览          |
| L2 | `*_SYSTEM.md`                  | 跨模块方案（记忆、技能等） |
| L3 | 各目录 `_ARCH.md`                 | 模块职责 + 文件表    |
| L4 | 文件头 `INPUT` / `OUTPUT` / `POS` | 单文件定位         |

**规模（2026-06-09 实测）**：server、frontend、desktop、shared 合计 **521** 份 `_ARCH.md`。CI 运行 `check_fractal_docs.py`（目录覆盖、严格文件头、`api/` 与 `channels/providers/` 禁 stub）及 **296** 项架构 pytest。典型 Agent 竞品仅有集中式 `docs/`，**无**模块级 `_ARCH` 地图。

**你能得到什么**：自托管与二开 onboarding 更快；文档与代码脱节在合并前被 CI 拦住，而不是线上才发现。

## 安全模型

6 层纵深防御。完整模型见[安全架构](/zh/core-concepts/security-architecture)。

## 部署模式

| 模式            | 组件                                | 场景      |
| ------------- | --------------------------------- | ------- |
| **本地 WebUI**  | Server + Frontend                 | 个人使用、开发 |
| **Tauri 桌面端** | Desktop + 内嵌 Server               | 原生应用体验  |
| **SaaS 云端**   | Control Plane + Server + Frontend | 托管、团队   |