架构概览
Myrm 由五个独立仓库组成，各承担平台中的不同角色。仓库结构
职责分离
- 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 按目录定位职责，而不是通读源码猜边界：
规模（2026-11-08 实测）：开源仓库共 1,200+ 份
_ARCH.md（harness、server、frontend、desktop、shared 等）。CI 运行 check_fractal_docs.py（server 的 app/ 下每个目录都要有 _ARCH.md、严格文件头、api/ 与 channels/providers/ 禁 stub），校验 markdown 引用的每个路径真实存在，并运行架构 pytest 门禁（run_architecture_gates.sh：每个 PR 与每次推送到 main 运行 1,393 项）。
其他项目怎么做（2026-11-08 读取的仓库）：它们靠手写文档，门禁管的是别的属性。仓库根目录以下的 AGENTS.md / CLAUDE.md，Hermes、OpenClaw、Codex、DeepSeek-Harness、Pi、OpenCode 分别有 14、26、3、32、0、17 份。Hermes 与 OpenClaw 限制 AGENTS.md 的长度，避免智能体的上下文被截断；DeepSeek-Harness 要求每个包导出都写 JSDoc，并给常驻文档设字数预算；OpenCode 把一个 SDK 包的文档与源码对照检查；Codex 与 Pi 我们没有找到针对 AGENTS.md 的检查。Myrm 在此之上多了一层目录级地图，并由 CI 把关。
CI 门禁与跨语言契约一致性
除文档外，开源产品层还强制机器可校验的契约，保证前端与后端永远不会悄然漂移：
这些 parity 门禁经过实战验证：2026-08-13 它们真实抓出并驱动修复了 3 个跨语言契约漂移 bug（
load_timeout reason 未同步进前端 TS union、memory_retrieval_trace 缺失于 ToolEndStreamEvent、i18n 映射遗漏）——失败全部在合并前的 CI 阶段暴露。
Harness 侧还有一道通用能力包纯净门禁（test_toolkits_agent_boundary）：toolkits/ 下任何文件不得导入 agent/、runtime/、backends/（含 importlib 字符串动态导入），保证第三方只引用通用能力包时不被拖入整个运行时；2026-09 实测抓出 7 处越界并修回，门禁现常绿。贡献者新增通用能力时：通用代码放 toolkits/，需会话/运行时上下文的放 agent/meta_tools/，业务技能放 Server 预置技能——放错层 CI 直接红灯。
你能得到什么：自托管与二开 onboarding 更快；文档与代码脱节在合并前被 CI 拦住，而不是线上才发现；前端/后端契约漂移会直接让构建失败，而不是带着「幽灵 bug」上线。