AgentMeshOS 总体架构设计

版本：v1.8.0

更新：2026-08-18

阶段：通用 AI Runtime MVP、重新开启后的阶段四智能编排、通用成果与验收闭环、阶段五至阶段八均已完成并归档；当前阶段 P9 隔离 Tailnet 临时远程协助节点（实施中）

总体结构

用户通过 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 本地持久化存储。101 与用户既有 Project 根的全目录双向同步是后续目标，目前因 DD compose/SQLite 锁冲突和 RR 残留清理尚未部署或验收；该路径不属于 Runtime StorageAdapter。

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["官方 OmniRoute 3.8.49"]
    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["主节点 root Operation Bridge"]
    Nomad --> W101["101 Docker Worker"]
    Nomad --> W103["103 Docker Worker"]
    Runtime --> SQLite["Runtime SQLite"]
    Runtime --> WebDAV["Cloudreve WebDAV"]
    WebDAV --> DD["dd 本地持久化"]
    ControlProject["101：/root/project 全目录"] <-->|"rclone bisync 双向同步"| ProjectWebDAV["Cloudreve Project 根"]
    ProjectWebDAV --> DD

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

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 私有控制网络；不传输任何业务文件。文件经 cloud.yohan.fun 公网 HTTPS 数据面直达 Cloudreve
Scheduler	Nomad 是唯一节点放置与任务运行调度器，不理解业务语义或选择逻辑 Worker
Compute	Docker 与 101/103 承担可替换的无状态计算任务
Storage	Cloudreve 提供系统云盘与 WebDAV；最大 1 MiB 的 Worker JSON 回调证据进入 Runtime SQLite，较大/长期 Artifact 只由主节点 Runtime 以 root-only WebDAV Adapter 写入长期目录；101 全目录 Project bisync 仅为待验收目标
AI BOSS	目标理解、结构化规划、逻辑能力和执行位置建议、依赖与并行、成果契约、语义审核、返工和汇总
AI Runtime	Benson 会话、计划契约验证、能力目录、安全与预算、任务图、成果/证据/检查/验收持久化、Adapter、恢复和告警
Verifier	Runtime 轻量检查器和无凭据 Nomad 验证 Worker；只按登记契约产生结构化检查结果
API Gateway	Console/Status 的状态、节点、Nomad、服务与告警只读聚合；接收内部 HMAC 脱敏事件
主节点认证回源代理	认证后的 Console 请求按固定路径回源到 AI Runtime 等受控服务；不复制业务状态或执行逻辑
System Operations	Runtime 只提交固定动作 ID；主节点 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 为官方 npm omniroute@3.8.49 与系统 Node 22.23.0 的 root 原生 systemd 安装，数据使用官方默认目录 /root/.omniroute，监听 127.0.0.1:39180，Live WS 监听 127.0.0.1:39182。2026-08-04 当前运行基线为 52 条连接、51 个已配置 Provider、2 个 Combo、2 个 API Key、SQLite quick_check=ok；其中 51 条连接、50 个 Provider 处于 active。2026-08-03 的原生迁移验收基线 53/52/2/1 作为历史恢复证据保留，不与当前运行基线混写。Docker 版本和兼容数据目录已退役并清理。

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/103 不获得 OmniRoute 或 Provider 凭据。

AI Boss 的主机操作采用 Runtime -> SystemOperationsAdapter -> 172.30.70.1:39184 -> 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 节点间路径及 RR 不参与 Project 文件数据面。101 与 Project 根全目录双向同步是待验收目标，当前未运行任何 bisync/resync 或 timer；本地回退历史仍应写入 101 独立备份盘。RR 的生产容器、Nomad、Runtime、Console、Docs、OmniRoute 与公网回源不依赖该工作区，且旧 Project 挂载/同步链路已清理并禁止启动。Worker 需要输入文件时从同一公网入口直接下载并在任务结束后删除临时副本。Cloudreve 当前为 dd 单节点服务；这不是高可用设计，后续扩展必须采用 Cloudreve 官方能力并以实际上传、下载、校验和故障恢复验证。

当前阶段：P9（阶段九）隔离 Tailnet 临时远程协助节点（实施中）

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

阶段五已上线 Runtime 内部持久主动循环与 Console 主动工作区；阶段六应用中心、阶段七本地应用 MVP 和阶段八应用平台与成果交付均已完成归档。P9 只复用隔离 Support Tailnet 和 SSH，不新增 WSS Gateway、第二控制面或调度器。