AgentMeshOS 核心模块设计

版本：v1.6.1

更新：2026-10-04

📌 结论摘要

核心模块边界继续冻结为 Network、Compute、Runtime、Storage、Console 和官方 OmniRoute 的唯一职责划分。P16 已完成 102 只读备用控制面边界，未改变 Runtime 调用链、OmniRoute 包、Provider 写权限或 Nomad 的唯一调度地位；P17 正在把代理 Master、节点面板和 Console 架构页纳入现有 Network/Console 边界，不新增 Runtime Adapter、第二调度器或第二控制面。依据是 P16 完成归档、P17 计划与 docs/plans/state.json。

🧩 模块与边界

模块	职责	禁止事项
Network	Headscale、Tailnet、私有 SSH、DERP、Peer Relay 与节点管理	转发系统云盘文件数据；把中继能力当成 Nginx/TLS 高可用替代品
Support Tailnet	为明确授权的临时技术支持设备登记会话、一次性入网引用、`tag:temporary-support` 与最小 SSH 生命周期	加入 Nomad/Worker 池、访问生产服务、保存 Auth Key 明文、成为通用远控 Agent
AI BOSS	理解目标、结构化规划、选择逻辑能力、设计依赖/并行与成果契约、语义审核、返工和汇总	直接选择具体节点、绕过 Runtime 校验、取得基础设施凭据或把模型文本当命令
Compute	Docker Worker 执行受控、版本化、无凭据的无状态任务包	业务规划、全局调度、扩大目标或长期云盘存储
Scheduler	Nomad 在已验证任务包中选择具体节点，执行资源约束和任务生命周期	理解自然语言、选择逻辑 Worker、审核成果或调用模型
Cloudreve Storage	系统云盘、WebDAV 与 dd 本地持久化	由客户端或受控 Runtime 通过公网 HTTPS 数据面直达 Cloudreve；不得经 Worker、RR Bridge 或其他节点中转文件内容
AI Runtime	验证并持久化 Plan/Task、能力和预算快照、Adapter、幂等恢复、Deliverable/Evidence/Verification/Acceptance 和审计	代替 AI BOSS 做业务语义派工；复制 Provider 注册、路由、健康或凭据账本；把凭据交给 Agent 或 Worker
Verification Engine	登记轻量检查器和无凭据 Nomad 验证 Worker，关联真实可访问证据并输出结构化结果	接受任意 Shell/本地路径、访问私网或用检查器成功冒充最终验收
API Gateway	为 Console/Status 聚合节点、Nomad、服务、告警与探针状态；接收内部签名脱敏事件	提交 AI 任务、调用模型、重启服务、管理 Cloudreve 文件或暴露敏感 OpenAPI/配置
主节点认证回源代理	将已认证的固定 Console 路径回源到 Runtime、Gateway 等受控服务	保存业务状态、实现任务编排、绕过上游鉴权或把写请求回退到只读备用节点
OmniRoute	上游 Provider、模型、连接、协议和路由能力的唯一权威	由 AgentMeshOS 修改上游源码或维护私有 Fork
CLI Agent Gateway	AI Boss/Worker 已登记单模型 CLI 通道的执行、Gateway 加密 Key 存储、进程隔离和最小脱敏审计	成为第二套通用 Provider Router；接收任意命令、私有数据、主机目录或基础设施凭据

CLI 通道选择与进程并发必须分开：Codex 和 Claude 是两种独立短生命周期 CLI 执行器；Gateway 可在总并发范围内为任一执行器启动多个独立进程，但每种 CLI 同一时刻只绑定一个持久“当前通道”，同类所有进程均使用该通道。切换当前 Codex 不改变当前 Claude，反之亦然。 | System Operations Bridge | 执行 Runtime 签名的固定系统动作，完成前置检查、后置验证、固定回滚和独立审计 | 接受 Shell、路径、服务名、镜像名、删除目标；向公网、Tailnet、浏览器或 Worker 暴露 | | Console | 业务工作台与受控交互入口；按职责调用 Runtime 或读取 Gateway | 承担云盘数据面、保存服务凭据或复制 Gateway/Runtime 业务逻辑 |

OmniRoute 的当前接入与升级边界以 P3-6-2 官方 OmniRoute 模型核心接入为准。

flowchart TB
    Console["Console 业务工作台"] --> Proxy["主节点认证回源代理"]
    Proxy --> Runtime["AI Runtime"]
    Console --> ApiGateway["API Gateway 只读聚合"]
    Runtime -. "HMAC 脱敏故障事件" .-> ApiGateway
    Runtime --> TaskGraph["Agent Registry / Task Graph"]
    Runtime --> Plans["Plan / Capability Snapshot"]
    Runtime --> NomadAdapter["NomadAdapter"]
    Runtime --> StorageAdapter["StorageAdapter"]
    Runtime --> ToolAdapter["ToolAdapter"]
    Runtime --> FeedbackAdapter["FeedbackAdapter"]
    Runtime --> OmniAdapter["OmniRouteAdapter"]
    Runtime -. "仅 AI Boss 显式备用" .-> CliAdapter["CliAgentGatewayAdapter"]
    NomadAdapter --> Nomad["Nomad / 103（101 仅受控例外任务）"]
    StorageAdapter --> SQLite["Runtime SQLite"]
    StorageAdapter --> Cloudreve["Cloudreve 长期 Artifact"]
    StorageAdapter --> Delivery["Deliverable / Evidence / Verification / Acceptance"]
    OmniAdapter --> OmniRoute["Provider / Model / Combo 权威"]
    CliAdapter --> CliGateway["隔离 CLI Agent Gateway"]
    ToolAdapter -. "仅已注册只读工具" .-> OmniRoute
    Runtime --> OperationsAdapter["SystemOperationsAdapter"]
    OperationsAdapter --> OperationsBridge["root 固定动作 Bridge"]

🔁 Runtime Adapter

NomadAdapter：仅提交、查询、取消与清理已注册的 Nomad Job 模板。
StorageAdapter：校验并在 Runtime SQLite 中事务化保存最大 1 MiB 的 Worker JSON 回调证据。Cloudreve WebDAV Adapter 仅在持有该职责的 Runtime 读取 root-only 凭据，写入长期 Artifact；Worker、模型和 MCP 不获得凭据，也不自动删除长期文件。
OmniRouteAdapter：通过私有内部接口调用官方 OmniRoute，传入任务快照允许的模型/策略，回收官方响应中的 Provider、model、decision、usage、USD 成本、健康和错误事实；未返回的 attempt 写为 unknown。
CliAgentGatewayAdapter：只允许 AI Boss 以固定 backend_id 调用隔离 Gateway；Runtime 保留原始会话，并以 runtime_redacted 标记外发前生成的受控脱敏 Prompt。Gateway 内部固定 Codex/Claude 命令模板，以标准输入传递 Prompt，限制进程组、超时、输出和并发，并只保存哈希化调用记录。它不提供 Worker 通用路由，也不自动回退到 AgentRouter。
FeedbackAdapter：记录任务、结果、失败、成本和审核事件。
SystemOperationsAdapter：使用 HMAC、短时间窗和 nonce 调用固定 Bridge；Runtime SQLite 保存动作、目标、前置检查、结果、回滚、Bridge 引用和耗时。主机诊断/重启/Docs 操作由 Bridge 执行；Nomad 操作继续由现有 NomadAdapter 执行且仅限已登记任务。

🎯 阶段四计划、成果与验收模块

Plan Store：保存目标、意图、风险、数据等级、预算与能力快照、规划调用引用、版本和替代关系；模型只输出 Pydantic 严格契约，Runtime 不执行部分解析结果。
Capability Registry：登记逻辑能力、版本、输入输出契约、允许数据等级、执行方式、任务包、资源上下限、成果类型、检查器和当前不可用原因。模型自述能力不进入目录。
Task Graph：保存计划步骤、依赖、并行组和状态；Runtime 验证无环、能力存在、执行方式匹配、资源/预算合法后才冻结。AI BOSS 选择逻辑能力，Nomad 只选择具体节点。
Deliverable Registry：使用可扩展字符串 ID 登记回答、文档、文件、媒体、代码、软件包、镜像、部署、数据、模型、数据库、系统、外部动作、持续观察及 other，并保存版本、位置、安全访问引用、哈希、回滚和被替代关系。
Evidence Store：保存证据来源、成果与验收标准关联、摘要、安全引用、哈希、可访问状态和数据等级。只有真实读取或访问成功的对象才可作为通过证据。
Verification Engine：执行 Runtime 轻量检查器或登记的 Nomad 验证 Worker；必需检查失败不可被模型覆盖，不支持的成果必须转 Benson。
Acceptance Engine：AI BOSS 只输出 accept、rework 或 insufficient_evidence 及有效的标准/证据引用；普通低风险任务在必需检查和审核都通过后自动验收，高风险、外部动作、未知风险、冲突或证据不足进入 Benson 决定。

面向 Benson 的执行、暂停、恢复、取消、重审、返工、计划处置和成果验收操作统一由所属主题的对话工作摘要触发；任务页与成果页只提供查询、证据、版本、审计和返回原主题的入口。Console 不复制状态机，所有按钮必须调用 Runtime 现有接口和幂等键，并在提交前校验工作摘要的 conversation_id 与当前主题一致。主题切换期间必须立即撤下旧主题操作，不能让旧任务按钮残留到下一次轮询。

系统操作固定动作用于把少量、可审计的主机维护能力暴露给 Runtime，不是通用命令执行器。每项动作必须声明用途、精确范围、风险和预期结果；Console 默认展示人类可读摘要、下一步和审计引用，原始结构化字段只作为折叠技术详情。Bridge 继续拒绝任意 Shell、未登记目标和模型生成命令。

任务状态必须区分计划、执行、成果登记、检查、审核和最终验收。completed 的唯一含义是最终验收完成；旧任务只标记兼容策略和 legacy_recorded 成果，不伪造新的 Benson 决定。

Runtime 不再拥有第二套 Provider Registry、模型目录、Provider 健康/冷却、通用回退、Direct Provider 默认路径或 Provider 凭据存储；这些能力由 OmniRoute 维护。CLI Agent Gateway 只是固定候选的受限执行边界，不改变这一规则。Runtime 只保存业务策略、任务快照、事件引用、官方 USD 调用成本和有明确依据的人民币/业务成本。

🛡️ 安全与可观测性

历史 P9 的临时设备属于 Support Tailnet，不是生产节点；该阶段已关闭，不再实施。如果以后重新决策恢复同类能力，ACL 仍只能允许指定支持操作员或主节点到临时设备的 SSH，临时设备不得访问 main 管理服务、101/102/103、Nomad、Cloudreve、OmniRoute、Headscale 管理 API 或 Codex App Server。

P10、P11 和 P12 已完成的稳定边缘入口、网络治理与节点纳管属于 Network 基础设施边界：活跃配置只保存逻辑身份，公网 IPv4/IPv6 只存在于 root-only 运行时快照和 last-known-good。P13 已完成 OmniRoute latest stable 迁移和 RR 全量退役；P14 已完成搜索 MCP 并归档；P15 已完成 d02、DD、dog-public Edge/DERP/Peer Relay、DNS 切换和 RR 冷启动修复。Headscale relay grant 只能从节点登记表精确生成，禁止恢复 src:["*"] 的中继授权。

P16 已完成控制面只读冗余边界：102 的备用 Auth 是同一认证数据的一致性快照副本，只接受已有会话读取和登录验证；Console 与 API Gateway 只投影 topology、node inventory、alerts 和 bridge status。RR 仍是唯一写权威，备用节点不能覆盖 RR 数据库、创建任务、修改凭据、扩大权限或成为第二套 Runtime/Nomad。

普通 Agent、模型上下文和 MCP 不得读取基础设施凭据、Docker Socket、Worker SSH 或任意主机命令。AI Boss 也不获得底层凭据，只能调用 Runtime 注册的固定动作。事件与日志用于追踪，不能替代真实数据面验证或构成普通任务审批流程。

⚠️ 未决项 / 需要决策

事项	当前事实	下一步
P13 归档后观察	102 `3.8.51` 已承接生产，RR omni 物料已退役	长期健康观察独立运行；异常按新运维事件处理
P14 归档	搜索 MCP 双监听、三工具与双通道回归已完成	保持稳定能力，不重新打开归档
P15 归档	四台候选节点承担 Edge、DERP、Peer Relay，RR 排除；四区 DERP、Peer Relay、真实 DNS 切流和回切均已归档	保持逐区故障隔离和重启恢复；不再重开 P15
P16 控制面	102 只读备用、认证连续性、Edge 回退和 RR 重启演练已完成并归档	不再重开；后续异常按新运维事件处理
P17 范围	代理控制面统一入口、四个节点面板、Console `#proxyNetwork` 架构页和三端客户端验收；当前工作包为 `P17-5`	完成 Android/iOS 真机、最终回退和发布门禁后才允许归档
模块权限边界	Runtime、Bridge、Gateway 和 Worker 权限未改变	任何扩展继续按受控变更和单项验收处理