从模块化计划到安全本地 Agent：MAOS 项目阶段总结

一句话概括

MAOS 是一个面向机械工程场景的模块化 Agent 项目。它试图把大模型对话、权限、安全隔离、MCP 工具、WPS、CAD、有限元分析和工程知识库放进同一套可审计的运行框架中。

这次阶段工作的结果不是“做出了一个什么都能干的机械机器人”，而是完成了更重要的底座：核心模块有清晰边界，关键行为可测试，本地聊天入口可运行，并且在安全审计后能够以独立桌面应用的形式稳定启动和退出。

为什么要从模块化开始

机械类 Agent 和普通聊天机器人最大的区别，是它最终会接触真实文件、工程参数和外部软件。CAD 建模、WPS 文档、FEA 求解、材料与公差查询，任何一步出错都可能比“回答错一句话”严重得多。

因此 MAOS 没有把所有功能直接塞进一个大脚本，而是先把系统拆成若干层：

1. Core 负责事件、协议、任务路由和稳定的数据契约；
2. Security 负责权限、审计、凭证租约和沙箱策略；
3. Adapter 负责模型、MCP、WPS、CAD 和求解器的边界适配；
4. Skill 负责把底层能力组织成用户能理解的机械任务；
5. Runtime 负责会话、规划、工具调用和生命周期；
6. CLI 与桌面 App 负责本地交互。

这种拆分的价值是：一个模块“存在”，不等于它已经被允许执行；一个测试通过，也不等于真实机械软件已经完成端到端验收。系统会尽量把这些状态说清楚。

M1–M8：机械 Agent 的核心积木

计划书中的 M1–M8 已形成可测试的 Core 和契约实现，主要覆盖：

• 任务路由、事件总线、协议和确定性输出；
• 权限管理、审计、Token Broker 与 Docker Sandbox 策略；
• MCP 连接、WPS Word/Excel/PPT/PDF 适配契约；
• CAD 与机械 Skill，包括齿轮、轴承、ISO 286 公差、材料候选和 DFM 规则；
• 线性静力 FEA 计划、网格质量、求解证据和报告计划；
• 工程知识检索、分层记忆、标签索引和参考资料库；
• Code、UI、Document、Changelog 等辅助 Skill；
• Dashboard、Plugin 和 Multi-Agent 的核心接口与能力边界。

这里刻意使用“Core”“计划”“契约”这些词。当前项目已经能验证输入、输出、权限和失败语义，但没有把 SolidWorks、CalculiX、WPS 等真实外部运行环境冒充成已经完成。

从核心模块走到可启动产品

在 M1–M8 之后，项目进入产品化阶段，补齐了三条最重要的链路。

第一条是 Agent Runtime。它负责会话生命周期、规划器调用、逐工具授权、审计记录和失败收敛，避免模型绕过权限直接触发工具。

第二条是模型适配。项目实现了 OpenAI Chat Completions 兼容入口，以及 DeepSeek Anthropic Messages 兼容入口；服务商、模型和 API 地址可以在本地切换，密钥只保留在当前进程内存中。

第三条是用户入口。现在既可以通过 CLI 对话，也可以双击快捷方式启动独立桌面窗口。桌面层复用同一套聊天核心，并在应用关闭后结束它自己启动的本地服务，不占用普通浏览器配置。

一次真正有价值的安全测试

把 Web 界面包成“本地 App”并不意味着天然安全。本轮审计发现，早期本地接口对请求来源、配置更新和 API 地址的约束不够严格，理论上可能被其他网页滥用。

修复没有停留在补一个判断，而是收紧了整条本地链路：

• 服务固定绑定回环地址，并校验 Host；
• 页面启动时获得随机会话令牌，API 请求必须携带它；
• 写请求校验 Origin 和 Content-Type；
• 内置服务商不允许被改写到任意接口；
• 切换服务商、协议或接口时清除旧密钥和旧会话；
• 对并发请求、请求体和流式响应设置上限；
• 增加 CSP、禁止嵌入和最小化浏览器权限；
• 公网 Serverless 聊天接口默认关闭，避免在没有身份系统时误部署。

随后使用真实浏览器、模拟模型服务和攻击回归脚本重新验证。被拒绝的请求不能修改配置，合法重新配置会清除旧凭证，桌面窗口关闭后端口也会释放。

目前的验证结果

截至 2026 年 7 月 18 日，最终质量基线为：

• 121 个测试文件、929 项单元测试全部通过；
• TypeScript 类型检查、ESLint、生产构建和依赖边界检查通过；
• Prettier 全项目格式检查通过；
• CLI 离线启动与退出通过；
• 本地 Web 界面的配置、模型切换、清空会话通过；
• 模拟 OpenAI 兼容服务的端到端消息转发通过；
• 桌面启动、独立进程校验、关闭清理和端口释放通过；
• 本地接口安全回归通过。

由于依赖镜像站没有实现 npm audit 接口，本轮没有把在线依赖审计标记为“已通过”；它被单独记录为尚未获得的外部证据。

现在它能做什么，不能做什么

当前桌面 App 已经是一个可用的本地多模型聊天客户端，CLI 也可以独立使用。项目内部的机械、CAD、WPS、FEA、知识库和安全运行时模块都经过了各自的单元测试。

但必须说明一个重要边界：桌面 App 当前连接的是直接聊天会话，还没有把完整的 Agent Runtime、权限确认和机械工具链装配进界面。因此它暂时不能在聊天窗口里直接替用户操作 CAD、生成真实 WPS 文件、运行有限元求解，也没有“操控电脑”的 CLI。

这不是被忽略的缺陷，而是下一阶段最明确的集成任务。只有完成 Runtime 装配、逐工具确认、真实外部软件适配和端到端证据后，MAOS 才适合被称为完整的机械执行 Agent。

这次项目最重要的收获

第一，Agent 的能力清单必须和真实可达能力分开。模块存在、接口存在、单元测试通过、真实外部执行成功，是四个不同层级。

第二，本地应用同样需要 Web 安全模型。只监听本机并不能替代来源校验、会话令牌、凭证隔离和安全响应头。

第三，诚实的“不支持”比模糊的“应该可以”更有价值。机械工程需要可追溯的输入、明确的单位和来源、失败关闭，以及不能伪造的执行证据。

下一阶段

接下来的重点不是继续堆更多模块，而是把已经存在的能力接成一条用户真正能走通的路径：

1. 将安全 Agent Runtime 接入 CLI 和桌面 App；
2. 增加逐工具权限确认和可读审计记录；
3. 先接入一个低风险只读工具，完成真实端到端验收；
4. 再接入 WPS 和机械/CAD 任务，并建立外部软件执行证据；
5. 最后评估会话持久化、安装包和受认证的远程访问。

MAOS 已经跨过了“只有计划书”的阶段，也还没有走到“机械工作全自动化”的终点。现在它处在一个更扎实的位置：底座已经成形，边界已经看清，下一步可以围绕真实任务逐条打通。