AgentMeshOS 技术选型说明
版本：v1.6.0
更新：2026-08-11
现行选型
| 能力 | 当前方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 |
|---|---|---|---|---|---|---|
| 私有控制网络 | Headscale / Tailnet | 已有运维方式稳定 | 中等 | 适合控制与管理 | 已掌握 | 可扩节点 |
| 调度 | Nomad | Worker 接入统一 | 中等 | 适合批处理调度 | 已掌握 | 可扩 Worker |
| 计算 | Docker | 服务隔离清晰 | 低 | 适合现有任务 | 低 | 可替换镜像 |
| 系统云盘 | Cloudreve + WebDAV + dd 本地持久化 | 单一应用边界清楚 | 低 | 公网直达 dd，不经转发 | 低 | 可按官方能力扩展 |
| 项目云盘访问 | 101 /root/project 作为本地项目空间；RR 不挂载、不运行同步 |
RR Project rclone、bisync、挂载和 timer 已退役；同步保持停用 | 低；生产节点不承载 WebDAV 文件同步 | 避免 Cloudreve/SQLite 异常扩散到 RR | 低 | AgentMeshOS 仅是 101 project 下的子项目 |
| 公网入口 | MM BaoTa Nginx | 现有唯一 80/443 入口 | 低 | 直达反代 | 已掌握 | 可增加站点 |
| 模型核心 | 官方 OmniRoute npm + 系统 Node + systemd | 跟随官方 npm 发布，使用官方默认安装与数据目录 | 低 | loopback 原生调用，避免容器功能缺口 | 中等 | 可使用官方 CLI、升级和宿主机集成能力 |
| Runtime 形态 | 薄 Runtime + OmniRouteAdapter | Runtime 只保留业务编排与桥接 | 低于双 Router | 少一套重复路由与凭据读写 | 低 | 可随官方能力扩展 |
| AI Boss CLI 备用通道 | FastAPI + Gateway 加密 SQLite 单模型通道 + Codex/Claude CLI + Docker 隔离 | URL/Key 与 Runtime 分离，命令与审计边界清晰 | 中等；需维护 CLI 版本、主密钥和单独镜像 | 多一跳和进程启动开销，只适合显式选择 | 中等 | 可按真实 Smoke 单独启用单模型通道 |
| AI Boss 系统动作 | Runtime Adapter + Python 标准库 root systemd Bridge | 固定动作集中维护，Runtime 与主机权限分离 | 低；无额外 Python 框架和镜像 | 单机私网一跳，对运维动作可忽略 | 低 | 可逐个增加已验证 Handler，不扩大通用权限 |
| AI BOSS 交互 | FastAPI + SQLite 持久状态 + SSE | 沿用现有栈，状态可审计和恢复 | 低；不新增中间件 | 单向流式和状态推送开销低 | 低 | 后续可扩交互事件，不需要 WebSocket |
| AI BOSS 记忆 | SQLite + FTS5 | 单用户下事务与来源管理集中 | 低；复用 Runtime 数据库 | 适合当前数据量 | 低 | 检索质量不足时再评估向量索引 |
| AI BOSS 附件 | Cloudreve 临时空间 + SQLite 元数据 | 与既有 Storage 边界一致 | 中等；需解析和配额控制 | 原文件不进入 SQLite | 低 | 可按后端能力逐步开放多模态 |
| AI BOSS 智能编排 | OmniRoute 结构化 JSON + Pydantic 契约 + SQLite DAG | 语义判断与硬校验分层，沿用现有模块 | 低；不增加工作流服务 | 当前单用户和最多 20 步计划足够 | 低 | 可按能力目录扩 Worker 与任务类型 |
| 成果与验收 | SQLite 元数据 + Runtime 轻量检查器 + Nomad 验证 Worker | 状态统一，重型依赖与 Runtime 隔离 | 中；需维护版本化检查器镜像 | 轻重检查分流，不阻塞 Runtime | 低至中 | 可按成果类型增加检查器，不修改 SQL 枚举 |
| Console 成果中心 | Vanilla JavaScript + 认证回源 API | 延续现有页面和部署方式 | 低 | 无额外前端运行时 | 低 | 当前规模足够，后续按真实复杂度再评估组件框架 |
| API Gateway 目录 | 显式安全元数据生成的管理员只读目录 | 契约与页面使用同一元数据 | 低 | 只读目录开销可忽略 | 低 | 可随受控接口增加，不暴露原始 OpenAPI |
AI Boss 系统动作选型
P9 临时远程协助选型
| 方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 | 决策 |
|---|---|---|---|---|---|---|
| 自建 HTTPS/WSS Gateway | 需维护协议、连接与撤销服务 | 高 | 多一跳 | 中高 | 高 | 不采用 |
| SSH 反向隧道 | 平台差异与入口管理较多 | 中 | 高 | 中 | 中 | 不采用为统一流程 |
| 现有 Headscale/Tailnet + SSH | 复用已有控制面与 SSH 运维方式 | 低 | 高 | 低 | 足够 | 采用 |
| 生产 Tailnet 全网互访 | 信任边界过大 | 低 | 高 | 低 | 高 | 禁止 |
P9 采用同一 Headscale 控制面下的隔离 tag:temporary-support 和最小 ACL，不把受助设备视为可信 Worker。平台脚本只在可见桌面授权后显式执行，Auth Key 仅在进程内使用；当前 Codex 只在主机侧辅助人工 SSH 操作，AI Boss 不参与直接执行。
未选择把 Docker Socket、SSH Key、主机根目录或任意 Shell 交给 Runtime：这些方案部署看似直接，但会让模型调用面与 root 执行面强耦合，权限和审计不可控。也未为小型固定动作 Bridge 引入 FastAPI/数据库框架；Python 标准库 HTTP、HMAC 和 SQLite 已满足当前吞吐，依赖与升级面更小。
Bridge 原生 systemd 运行是必要的系统级例外，因为它需要执行固定的 root 服务操作；Runtime、Console 和 Docs 仍保留现有 Docker 形态。后续扩展必须新增明确 Action、固定 Handler、前置检查、后置验证、回滚和测试，不能增加通用命令参数。
AI BOSS 交互与记忆选型
AI BOSS 的响应是服务端到浏览器的单向增量，现有 FastAPI 与 Vanilla JavaScript 均可直接支持 SSE。相比 WebSocket，SSE 的连接、鉴权、代理和断线恢复更简单；相比 Celery/Redis，SQLite 持久交互队列不增加常驻服务和运维面，当前单用户吞吐足够。若未来真实并发超过 SQLite 写入边界，再依据压测证据升级，不提前引入分布式队列。
长期记忆首版使用 SQLite/FTS5，并显式保存来源、确认状态、版本和数据等级。OmniRoute Memory 的隔离边界尚未成为 AgentMeshOS 的权威契约，向量数据库也会增加部署与调优成本，因此本阶段均不启用。附件原文件使用 Cloudreve 临时空间，SQLite 只保存元数据和引用；这样既避免 BLOB 膨胀，也能保持浏览器和模型不接触 WebDAV 凭据。
智能编排与成果验收选型
阶段四继续采用 FastAPI、Pydantic、SQLite 和 SSE。AI BOSS 通过现有 OmniRoute Boss Combo 生成严格 JSON 计划与结构化审核，Runtime 使用 Pydantic 和确定性规则验证能力、安全、预算、DAG 与状态。该分层保留 AI 对目标、逻辑能力、依赖和成果语义的判断，同时把权限和真实性边界留在可测试代码中；Runtime 不靠免费模型自行推测业务派工，Nomad 也不承担智能规划。
未选择 Celery/Redis 或 Temporal：它们能提供更完整的分布式队列或工作流能力，但当前单用户、最多 20 个计划步骤和有限并发不需要额外常驻服务，部署、备份、学习和故障恢复成本明显更高。SQLite 事务、持久事件和现有 Runtime 重启恢复已经满足当前规模；只有真实并发和可靠性数据超过边界时再重新选型。
未重写 React/Vue Console：成果中心的列表、详情、筛选和状态控制可以在现有 Vanilla JavaScript 体系内完成，重写会扩大回归和团队学习成本。接口按能力检测，旧 Runtime 不支持时隐藏新区域并展示原因，为以后组件化迁移保留 API 边界。
检查采用“Runtime 轻量检查 + Nomad 验证 Worker”：哈希、MIME、Schema 和小型文件检查留在 Runtime；浏览器链路或 CPU 较重分析进入版本化、无凭据的 Nomad Worker。未把全部重型依赖装入 Runtime 镜像，以免扩大启动、攻击和升级面；验证 Worker 不接受任意 Shell、本地路径、动态依赖或私网访问。成果类型使用可扩展注册 ID，未知类型仍可登记和人工验收，避免 SQL 枚举阻塞扩展。
API Gateway 不承担计划、成果、模型或验收接口。将其升级为统一执行网关会形成第二控制面并增加凭据与状态一致性风险；Console 继续经认证回源代理直达 Runtime。
存储决策
Cloudreve 取代了 KodBox、CSI、JuiceFS、MariaDB Galera 与 MinIO 的组合。原组合层数多、恢复边界复杂，并使用户文件数据面绕经非存储节点；已完整退役。
当前系统云盘访问路径为：客户端到 MM，再到 dd Cloudreve。Tailnet 只服务控制面，不参与文件数据面。Cloudreve 当前为单机 master 与 dd 本地持久化存储，必须明确接受当前单点边界。
Runtime Artifact 不自动复用旧 S3/MinIO：旧后端已删除。Worker 的最大 1 MiB 结构化 JSON 回调证据与任务状态一起写入 Runtime SQLite，具备单机事务、SHA-256 回读校验和现有数据库备份能力；这种方案维护面和部署复杂度最低，适合当前小型回调。较大或长期 Artifact 使用主节点 Runtime 的 Cloudreve WebDAV Adapter，直写 AgentMeshOS-长期/runtime-artifacts；凭据只在 root-only Runtime 环境中，101/103 不保存，长期文件不自动删除。
用户既有 Project 资料与 AgentMeshOS 项目权威分离。当前所有 Project rclone、bisync、挂载和 timer 均停用，RR 永久不作为 Project 文件同步节点；不得因历史脚本、恢复包或 systemd 残留重新启用。若未来恢复同步，必须作为独立变更重新评估 Cloudreve/SQLite 锁、OOM、冲突保护、删除阈值和重启持久化，且不能成为 RR 生产部署依赖。
升级原则
OmniRoute 不进行源码改造，升级遵循官方发布节奏。升级前备份其 Provider 配置和运行状态，按官方文档验证升级与回滚；AgentMeshOS 只维护外部集成边界。
官方镜像与原生 npm 安装均使用上游发布物，不构成源码改造。当前生产以 root 运行官方 omniroute@3.8.49、系统 Node 22.23.0 与外部 systemd：全局包位于 npm 官方默认位置 /usr/lib/node_modules/omniroute，正式数据位于官方默认目录 /root/.omniroute。Provider 数据恢复已在 101 隔离环境和主节点真实生产数据上通过。AgentMeshOS 只维护外部 systemd、loopback 与 Runtime 私有代理，不修改包内容，也不维护专用用户、自定义版本软链接或容器兼容目录。
Runtime 继续使用 Docker，因为其 Python 服务边界、只读根文件系统、固定网络地址和镜像回滚已经成熟。原生 OmniRoute 与 Runtime Docker 之间选择 systemd-socket-proxyd，维护面小、只有 TCP 转发开销且无需额外镜像；不用 sidecar，也不放宽 OmniRoute 的 loopback 监听。该组合比把 Runtime 一并原生化学习成本更低，也比恢复 OmniRoute Docker 网络更符合后续官方升级目标。
AgentRouter 未列入 OmniRoute Provider 时，不把它伪装成 OmniRoute Provider，也不让 Runtime 直接调用其 HTTP。备选方案中，OmniRoute ACP 会引入当前版本尚不成熟的进程/会话完成语义；Runtime 直接启动 CLI 则扩大主进程权限和依赖面。因此选择独立 Docker Gateway：可维护性高于把命令逻辑散入 Runtime，部署复杂度高于直接 HTTP，但能以非 root、只读根文件系统、无宿主机端口和无仓库挂载限制风险。该通道的性能不作为默认路径指标，团队只需维护固定 API 与 CLI 版本；未来扩展必须逐模型完成真实 Smoke，不能开放任意模型或参数。
该模型核心的现行实施计划为 P3-6-2 官方 OmniRoute 模型核心接入。