🧱 AgentMeshOS 工程规范¶

版本：v0.1.0

阶段：工程实现规范层

1️⃣ 总体原则¶

模块化优先
所有组件必须可独立运行
禁止强耦合设计
所有服务必须 API 化
所有状态必须可持久化
禁止把任务、节点、权限、审计等关键状态只放在本地内存或本地文件
后续所有文档描述必须使用中文；如需保留英文术语，应只作为技术名词或中英对照出现

2️⃣ 项目目录规范（强制）¶

AgentMeshOS/
│
├── docs/
├── deploy/
├── docker/
├── nomad/
├── network/
├── storage/
├── compute/
├── scheduler/
├── ai-core/
├── gateway/
├── agents/
├── scripts/
├── tools/

小项目目录规则（强制）¶

本仓库后续会包含多个可独立维护的小项目，例如文档站、官网、控制台、状态页、安装器、CLI、MCP、自动化工具或其他辅助服务。凡是不属于 network、storage、compute、scheduler、ai-core、gateway、agents 等核心分层模块，但又需要独立构建、测试、部署或发布的内容，必须放在 tools/ 下，禁止散落在仓库根目录。

小项目统一使用以下目录格式：

tools/
└── project-name/
    ├── README.md
    ├── src/
    ├── config/
    ├── docker/
    ├── tests/
    └── scripts/

目录职责：

README.md：说明该小项目的用途、运行方式、构建方式和维护边界。
src/：该小项目源码、页面、模板或内容入口；如果项目是纯配置型，可说明后省略。
config/：该小项目专属配置，例如 mkdocs.yml、Nginx 模板、应用配置模板。
docker/：该小项目专属 Dockerfile、镜像构建说明、容器启动配置。
tests/：该小项目专属验证脚本、冒烟测试或构建检查。
scripts/：只服务于该小项目内部开发、构建、整理、生成的局部脚本。

示例：

tools/docs-site/
├── README.md
├── src/
├── config/
│   └── mkdocs.yml
├── docker/
│   ├── Dockerfile
│   └── nginx.conf
├── tests/
│   └── smoke.sh
└── scripts/
    └── build-local.sh

规则：

小项目名称必须使用小写英文、数字和连字符，例如 docs-site、status-site、worker-installer。
小项目不得直接占用核心模块目录名，避免与系统分层混淆。
小项目如需新增顶层目录，必须先修改本工程规范；默认不得新增平行目录体系。
小项目内部可以有自己的 README.md、Dockerfile、配置和测试，但不得重复维护全局架构规则。
项目文档正文继续放在 docs/；文档站程序、主题、镜像和发布配置放在 tools/docs-site/。

脚本存放规则（强制）¶

脚本按“使用范围”而不是按个人习惯存放：

scripts/
├── clients/
├── deploy/
│   └── project-name/
├── maintenance/
└── ci/

归属规则：

小项目内部开发、构建、格式化、内容生成脚本，放在 tools/<project-name>/scripts/。
需要用户复制执行、服务器部署执行、运维反复调用或跨项目复用的脚本，放在根目录 scripts/ 下。
Docker 一键部署菜单脚本统一放在 scripts/deploy/<project-name>/，例如：

scripts/deploy/docs-site/agentmeshos-docs-docker-deploy.sh

客户端节点安装、加入网络、清理和维护脚本继续放在 scripts/clients/。
跨项目维护脚本放在 scripts/maintenance/。
CI / GitHub Actions 辅助脚本放在 scripts/ci/。
公共脚本目录必须继续按用途和小项目名分层，禁止把多个项目脚本直接堆在 scripts/ 根部。
所有可执行脚本必须有中文说明、危险操作确认、默认非破坏行为和最小权限原则。

脚本版本迭代规则（强制）¶

所有需要用户复制执行、服务器部署执行、运维反复调用或跨项目复用的脚本，都必须纳入版本迭代管理，禁止长期使用无版本脚本。

脚本头部必须维护以下元信息：

SCRIPT_NAME
SCRIPT_PROJECT
SCRIPT_VERSION
SCRIPT_UPDATED

版本规则：

采用 v主版本.次版本.补丁版本 格式，例如 v0.1.1。
只修正文案、注释、输出提示或非行为变更时，递增补丁版本。
新增菜单项、参数、部署能力、兼容系统或校验逻辑时，递增次版本。
修改默认端口、默认域名、清理/删除行为、权限模型、安装路径或其他可能影响已部署机器的行为时，递增主版本，并在脚本中增加中文风险提示和确认步骤。
每次脚本发布都必须同步更新 docs/脚本库.md 的文件名、归属项目、版本号、更新日期和下载链接。
文档站 Docker 镜像发布脚本时，必须保证镜像内 /scripts/ 下载文件来自仓库 scripts/ 源文件，禁止手工改容器内脚本。
需要通过 curl ... | sudo bash 运行的交互式脚本，必须从 /dev/tty 读取用户输入，禁止直接依赖标准输入读取菜单选项，否则管道执行后会无法交互。
脚本变更必须通过语法检查、必要的 dry-run 或冒烟验证后才能提交。

3️⃣ 模块设计规范¶

每个模块必须包含：¶

/module-name
   ├── src/
   ├── api/
   ├── config/
   ├── tests/
   ├── README.md

要求：¶

必须可独立运行
必须有 API 接口定义
必须有配置文件
必须有测试结构

4️⃣ API 规范¶

统一 REST / JSON
禁止私有协议
所有模块必须提供 API 文档
未来可扩展 gRPC（但不作为 v0.1 标准）
AI 侧只能调用受控公开 API，不能直连内部控制端口

5️⃣ Agent 规范（非常关键）¶

Agent 定义：¶

Agent = 可执行任务的逻辑单元

结构：¶

Agent {
    input: Task
    plan: Steps
    execute: Gateway / Scheduler API Calls
    output: Result
}

原则：¶

Agent 不能直接控制 Node
Agent 只能提交任务给 Scheduler
Agent 必须无状态设计（Stateless）
Agent 的 execute 指“调用受控接口提交动作”，不表示直接在节点上执行命令

5.5️⃣ 状态模型规范¶

对象/文件数据统一走 S3 Compatible API
控制面元数据必须进入 Metadata Store：任务记录、节点注册、心跳、租约、Token、审计日志、AI 索引
模块不得跨层直连 Metadata Store，统一通过 Storage Module 或 Control API 访问

6️⃣ 配置规范¶

统一 YAML / JSON 配置
禁止硬编码节点信息
所有配置必须集中管理（Config Module）

7️⃣ 日志规范¶

统一结构化日志（JSON format）
必须包含 trace_id
必须支持分布式追踪

8️⃣ 错误处理规范¶

所有错误必须标准化
禁止 silent failure
必须记录 error code + context

9️⃣ 安全规范¶

所有 API 必须认证
节点必须 token 验证
禁止无认证内部通信（未来阶段）
v0.1 默认要求：Nomad ACL、控制面 TLS / mTLS、Tailscale Auth Key / Tag 策略、密钥轮换方案

9.5️⃣ Event Bus 规范¶

事件字段最小集合：event_id、trace_id、type、timestamp、producer、payload_version
默认至少一次投递，消费者必须实现幂等处理
必须有失败重试、死信处理、事件保留策略
禁止把需要强一致确认的同步控制流程只放到 Event Bus 上

🔟 编码规范（Codex 重点）¶

单一职责原则
禁止跨模块调用内部实现
必须通过 API 访问模块
禁止直接访问数据库

📌 架构约束总结¶

AI Core → Scheduler → Compute → Storage

所有通信必须通过 API 或 Event Bus

禁止：
直接跨层调用
直接访问底层资源
 直接访问 Metadata Store

🚀 下一步¶

下一份文档：

07_部署规范.md

VPS 部署方式
Worker 部署方式
Nomad 部署结构
Tailscale 网络部署
Docker 执行部署