跳转至

AgentMeshOS 总体架构设计

版本：v2.0.1

更新：2026-10-04

阶段：通用 AI Runtime MVP、重新开启后的阶段四智能编排、通用成果与验收闭环、阶段五至阶段八、P10 至 P16 均已完成并归档；P9 已关闭且不再实施；当前阶段 P17“代理网络控制面统一入口与真实客户端验收”进行中

📌 结论摘要

系统继续采用“薄 Runtime + 官方 OmniRoute + Nomad 单一调度器”的总体结构。P16 已完成 102 只读备用控制面、认证与拓扑快照和 Edge 本地回退，未新增第二调度器、第二 Runtime 或第二套拓扑数据源；102 3.8.51 仍是唯一生产 OmniRoute 权威。P17 正在执行代理控制面独立入口、节点面板和客户端验收，不改变 Runtime 边界。依据是 P16 完成归档、P17 计划与 docs/plans/state.json。

🧱 总体结构

用户通过 Console 与 AI 应用进入 AI Runtime。AI BOSS 请求经主节点认证回源代理直达 Runtime，不经过 API Gateway；API Gateway 只向 Console 和 Status 提供状态、告警与只读运维聚合。AI BOSS 是语义总控，负责理解目标、形成结构化计划、选择已登记逻辑能力、决定主节点或 Nomad 执行建议、审核成果与汇总；Runtime 验证并冻结计划、能力、安全、预算和状态，不代替 AI BOSS 做业务语义派工。Nomad 只在 Runtime 已验证的任务包中选择具体节点，Worker 只执行版本化无状态任务包。

Runtime 默认通过 OmniRouteAdapter 调用官方 OmniRoute；AI BOSS 对话也可选择已登记、已 Smoke 的 CLI Agent Codex/Claude 单模型通道，但它不是第二套通用 Provider Router。外部通道 URL/Key 只由 Gateway 加密保存，Runtime 仅代理安全元数据与固定 backend_id。模型选择不拥有会话记忆：消息、摘要和确认记忆只由 Runtime 保存和组装。Console 不再要求 Benson 手动选择“公开/私有”；Runtime 保留原始会话，并在每次模型外发前生成受控脱敏上下文，因而模型切换不删除历史或改变记忆权威。Codex 通道不可用时不自动回退。重新开启后的阶段四新增 Plan、Deliverable、Evidence、Verification 和 Acceptance 持久对象，使任务执行、成果检查、AI BOSS 审核和最终验收成为一条可恢复链路。

系统云盘数据面独立为：客户端到 MM BaoTa Nginx，再到 dd Cloudreve 与 dd 本地持久化存储。用户既有 Project 项目库与 AgentMeshOS 代码工作区均不属于 Runtime StorageAdapter；RR 上的历史挂载/同步链路已退役。

项目控制与生产发布边界

101 是 AgentMeshOS 项目代码、资料和 GitHub 同步的权威节点，承担 CI/CD 构建、测试、版本签名/摘要、发布记录、回滚协调和项目级运维入口。GitHub Actions 是默认的构建与发布协调平台，但 GitHub 和 101 工作区都不是生产运行环境。CI/CD 产出版本化、可校验的镜像或部署载荷后，RR 才执行生产部署；RR 不从项目工作树直接构建。

RR 是生产部署与运行节点，继续承载生产 Runtime、System Operations Bridge、Docker、Nomad、Console、Auth、Docs、API 和其他生产载荷。Bridge 由 RR 本机 Runtime 调用，101 不建立第二套生产 Runtime/Bridge，也不复制 RR 的 Provider、Runtime 或 AgentMeshOS 系统级凭据。P16 的 102 只承载 Console、Auth 和 API Gateway 的只读备用投影；它不是第二控制面，不能提交任务、修改密码、撤销 Key、管理 Nomad 或覆盖 RR 的权威数据。人工发布只作为 CI/CD 不可用时的受控应急路径，必须复用同一版本产物和 SHA-256 摘要，并保留发布、回滚和健康验收审计。

flowchart LR
    Benson["Benson"] --> MM["MM / BaoTa HTTPS"]
    MM --> Console["Console"]
    Console --> Proxy["主节点认证回源代理"]
    Proxy --> Runtime["主节点薄 Runtime"]
    Console --> Gateway["API Gateway：状态 / 告警 / 只读聚合"]
    Runtime -. "HMAC 脱敏故障事件" .-> Gateway
    Runtime --> OR["102 官方 OmniRoute 3.8.51"]
    Runtime -. "AI Boss 显式选择；runtime_redacted" .-> CLIGW["隔离 CLI Agent Gateway"]
    CLIGW --> AgentRouter["AgentRouter / 官方 CLI 客户端"]
    OR --> Providers["Provider / Combo / Models"]
    Runtime --> Nomad["Nomad Server"]
    Runtime --> Ops["固定 System Operations Adapter"]
    Ops --> Bridge["RR root Operation Bridge"]
    Nomad --> W101["101 项目控制与发布协调节点"]
    Nomad --> W103["103 通用计算 Worker"]
    Runtime --> SQLite["Runtime SQLite"]
    Runtime --> WebDAV["Cloudreve WebDAV"]
    WebDAV --> DD["dd 本地持久化"]
    Project101["101：代码/资料/GitHub/CI-CD"] -. "版本化产物与发布请求；不作为生产运行面" .-> Main["RR：生产部署与运行"]

🎯 阶段四智能编排与验收控制链

flowchart LR
    Benson["Benson / Console"] --> Boss["AI BOSS：理解、规划、派工、审核、汇总"]
    Boss --> Plan["结构化 Plan 契约"]
    Plan --> Validate["Runtime：能力、安全、预算、状态与幂等验证"]
    Validate --> Graph["SQLite 持久 Task Graph"]
    Graph --> Main["主节点固定 Adapter"]
    Graph --> NomadPlace["Nomad 节点放置"]
    NomadPlace --> Worker["无状态 Worker"]
    Main --> Deliverable["Deliverable / Evidence"]
    Worker --> Deliverable
    Deliverable --> Verify["确定性检查器"]
    Verify --> BossReview["AI BOSS 结构化审核"]
    BossReview --> Auto["低风险自动验收"]
    BossReview --> BensonGate["高风险 / 未知 / 证据不足"]
    Auto --> Completed["completed：最终验收完成"]
    BensonGate --> Completed

计划、任务、成果、检查和验收必须分别持久化。前置任务只有进入最终 completed 后才释放依赖；Worker 执行结束、Nomad Allocation 完成、文件上传成功或模型调用成功均不能单独代表最终交付。模型审核结论必须真实参与决定，必需确定性检查失败时模型不能覆盖通过；检查器不支持、证据不可访问或风险未知时必须进入 Benson 决定。

🧩 分层职责

层 职责
Network Headscale/Tailnet 私有控制网络；业务文件不经节点中转；小于 1 MiB 的受控脚本、配置、凭据和紧急交换文件可临时经控制链路传输并校验清理。业务文件经 cloud.yohan.fun 公网 HTTPS 数据面直达 Cloudreve
Scheduler Nomad 是唯一节点放置与任务运行调度器，不理解业务语义或选择逻辑 Worker
Compute Docker 与 103（必要时 101 受控、可替换任务）承担无状态计算任务；101 不属于普通 Worker
Storage Cloudreve 提供系统云盘与 WebDAV；最大 1 MiB 的 Worker JSON 回调证据进入 Runtime SQLite，较大/长期 Artifact 只由主节点 Runtime 以 root-only WebDAV Adapter 写入长期目录；RR 不承载 Project 挂载、同步或 Project 凭据
AI BOSS 目标理解、结构化规划、逻辑能力和执行位置建议、依赖与并行、成果契约、语义审核、返工和汇总
AI Runtime Benson 会话、计划契约验证、能力目录、安全与预算、任务图、成果/证据/检查/验收持久化、Adapter、恢复和告警
Verifier Runtime 轻量检查器和无凭据 Nomad 验证 Worker；只按登记契约产生结构化检查结果
API Gateway Console/Status 的状态、节点、Nomad、服务与告警只读聚合；接收内部 HMAC 脱敏事件
主节点认证回源代理 认证后的 Console 请求按固定路径回源到 AI Runtime 等受控服务；不复制业务状态或执行逻辑
System Operations 生产 RR Runtime 只提交固定动作 ID；RR root Bridge 执行白名单诊断、固定服务重启和 Docs 部署/回滚，并持久化审计
OmniRoute Provider、连接凭据、模型目录、协议、Combo、健康、冷却、额度、回退、调用日志和官方 Dashboard
CLI Agent Gateway 仅为 AI Boss 提供显式备用的固定 Codex/Claude CLI 调用；只接收 Runtime 脱敏上下文，不接受任意参数、工具、工作目录或原始敏感数据，不执行自动回退
Application Center 应用注册、入口、版本、状态、独立工作区和人类可读结果；不得复制 Runtime 状态机或反向改变底座边界

🔁 薄 Runtime 与官方 OmniRoute

本节源于已完成的 P3-6，现已成为阶段三所有后续工作包的生效架构边界。

采用“薄 Runtime + 官方 OmniRoute”唯一模型调用架构。AgentMeshOS 不修改 OmniRoute 源码、不添加补丁、不维护 Fork 或私有分支、不构建私有镜像、不重新编译，也不直接改写已安装包或构建产物。Runtime 不再维护 ProviderRouter、Provider CRUD/凭据、模型目录、健康/冷却、通用回退或 Provider 原始成本账本。

OmniRouteAdapter 只调用官方 POST /v1/chat/completions、GET /v1/models 和 GET /api/monitoring/health。Runtime 只记录官方响应中实际存在的 Provider、模型、用量、延迟和错误；缺失事实写为 unknown，不得自行推断。

当前生产 OmniRoute 为 102 上的官方 npm omniroute@3.8.51 与系统 Node 22.23.0 的 root 原生 systemd 安装，数据使用官方默认目录 /root/.omniroute，监听 127.0.0.1:39180，Live WS 监听 127.0.0.1:39182，另由只对 RR 与 MM 放行的私有入口 100.64.0.4:39200 承接生产。2026-10-01 P13-4 生产基线为 70 条连接、19 个 Combo、4 个 API Key、迁移 193、SQLite quick_check=ok。RR omni 数据、包、service、回退备份和 vhost 已在 P13-C 删除。2026-08-03 的原生迁移验收基线 53/52/2/1 继续作为历史恢复证据保留，不与当前运行基线混写。

Runtime 只做角色级 Combo 选择：Boss 使用 agentmeshos-free-quality-first 的 fill-first，按质量顺序优先使用 GPT/Codex、Claude 和 O3；Worker 使用 agentmeshos-free-capacity-pool 的 least-used，按每个模型和账号的实际调用次数均衡免费容量。同等使用量时保持质量顺序，Provider 额度、健康、冷却和回退仍由 OmniRoute 决定。

Runtime 容器不加入 OmniRoute Docker 网络。主机 systemd-socket-proxyd 在 172.30.70.1:39181 提供受限转发到 127.0.0.1:39180，UFW 只允许固定 Runtime 容器 172.30.70.2 访问；101/102/103 不获得 OmniRoute 或 Provider 凭据。

AI Boss 的生产主机操作采用 RR Runtime -> SystemOperationsAdapter -> 172.30.70.1:39184 -> RR root systemd Operation Bridge。Bridge 只识别固定 action_id，拒绝命令文本、任意路径、任意服务/镜像、Provider/凭据、网络/SSH/防火墙和数据删除操作。Runtime 仍不挂载 Docker Socket、主机目录或 SSH Key；浏览器、Worker、模型和 MCP 不能直接访问 Bridge。Nomad 重试与清理由 Runtime 现有 NomadAdapter 处理，并且只接受 Runtime SQLite 已登记的任务 ID。

AgentRouter 不进入 OmniRoute Provider 列表，也不由 Runtime 直接请求其 HTTP API。固定链路为 Runtime -> CLI Agent Gateway -> Codex CLI / Claude Code CLI -> AgentRouter。Console 可以展示固定候选并随消息发送 backend_id；未完成对应模型真实 Smoke 的候选必须保持禁用。2026-08-05 Codex gpt-5.6-sol、Claude claude-opus-4-8 与 claude-opus-5 均已分别完成生产 Gateway、Runtime、Console 契约全链路并返回精确 OK。CLI 通道共享 Runtime 生成的统一会话上下文；它们不保存独立会话记忆。Runtime 在模型外发前替换可识别的密钥、连接字符串、内部端点与主机路径，Gateway 只接受标记为 runtime_redacted 的调用。未通过图片 Smoke 的后端仍不能接收图片原件。Codex 不可用时不设置自动回退。

💾 当前存储边界

Tailnet、SSH、Nomad 节点间路径、103 及 main 均不参与业务文件数据面。该限制不限于用户云盘文件，覆盖镜像、安装包、构建产物、测试夹具、附件、成果和归档。main 仅以正常 WebDAV 客户端经 cloud.yohan.fun 公网 HTTPS 访问 Cloudreve，不承担回源或节点转发；Worker 需要输入文件时从同一公网入口直接下载并在任务结束后删除临时副本。101 与 Cloudreve Project 当前不实施双向实时同步，历史 Project 凭据、脚本、状态和备份仅作审计/恢复材料保留；AgentMeshOS 代码权威为 101 /root/project/AgentMeshOS 与 GitHub。Cloudreve 当前为 dd 单节点服务；这不是高可用设计，后续扩展必须采用 Cloudreve 官方能力并以实际上传、下载、校验和故障恢复验证。

📊 当前阶段：P17（阶段十七）代理网络控制面统一入口与真实客户端验收

阶段四已完成 AI Runtime 和 Console 的对话、预算、上下文、记忆、附件、多模态、SSE、CLI Gateway、API Gateway 可见性、结构化规划与成果最终验收闭环，最终证据见阶段四归档。系统继续保持 Nomad 的唯一调度地位，不把 API Gateway 升级为统一执行网关。

阶段五已上线 Runtime 内部持久主动循环与 Console 主动工作区；阶段六应用中心、阶段七本地应用 MVP、阶段八应用平台与成果交付、P10 可替换网络边缘、P11 网络治理、P12 节点纳管、P13 OmniRoute 原生迁移和 P14 搜索 MCP 均已完成并归档。P9 已关闭且不再实施。

P15 已完成并归档：Edge 负责 DNS、TLS、Nginx 和回源；DERP 负责 Tailnet 官方中继；Peer Relay 由普通 Tailnet 节点提供中继能力。三者可以同机，但不能合并健康结论，RR 永远排除 Edge、DERP 和 Peer Relay。P15 已证明入口和中继冗余不能替代控制面后端冗余，因为所有 Edge 的 Console/Auth/API 都回源 RR 100.64.0.1:39200。

P16 已完成：Auth SQLite 使用一致性快照单向同步，备用 Auth 使用同一 AUTH_SESSION_SECRET 但拒绝写操作；Console 和 API Gateway 只开放 topology、node inventory、alerts 和 bridge status 等只读投影。活动 Edge 仅在 RR 连接失败、超时或返回 500/502/503/504 时回退 102，页面和 API 显示只读降级、来源和快照年龄。详细事实见 P16 完成归档。

P17 正在执行：RR 继续作为 2S-UI Master 和末位数据面，proxy.yohan.fun 与四个 panel-* 通过 CNAME 跟随逻辑 edge.yohan.fun；健康 Edge 提供公网 TLS，RR 100.64.0.1:39200 按 Host 转发到节点 Tailnet 2095。Console #proxyNetwork 不嵌入 2S-UI，只提供架构展示和五个人工入口。生产 Console 精确镜像、四个面板、DNS、证书、WebSocket、Master 节点在线和公网端口边界已完成回读；五台节点已补齐 VLESS Reality 并完成真实链路验证，Home/OfficeSummer 已刷新订阅，360T7 已切到 MM 主组和四节点后备组。Mihomo 客户端不承诺严格自动回切，Summer、S20、Magic2 和 iOS 真机仍未闭环，因此 P17 保持进行中。

⚠️ 未决项 / 需要决策

事项 当前事实 下一步
P13 归档后观察 P13 已完成并归档，102 承接生产，MM 直连 102，RR omni 物料已退役 长期健康观察独立运行；异常按新运维事件处理
P14 归档 搜索 MCP 双监听、三工具和双通道真实回归已完成 保持稳定能力，不重新打开归档
P15 归档 Edge、DERP、Peer Relay、DNS 切流/回切、RR 冷启动修复均已完成并归档 不再重开 P15；后续漂移按新运维事件处理
P16 控制面 102 只读备用、认证快照、Edge 回退和 RR 重启演练已完成并归档 不再重开 P16；后续异常按新运维事件处理
P17 范围 代理控制面统一入口、四个节点面板、Console 架构页和三端客户端验收 生产实施与真实验收完成后才允许归档
102 生产入口 102 只对 RR 与 MM 放行私有入口，MM 配置未改 保持现有入口，不扩大公网监听