跳转至

🧱 AgentMeshOS 工程规范

版本：v1.1.4

阶段：工程实现规范层

更新：2026-10-04

📌 结论摘要

本文是 AgentMeshOS 工程实现层的强制规范。结论是目录、计划、脚本、Web/App 交互、Docker 生命周期、单用户调度和 SSH 公钥追加都必须使用统一边界与可验证入口；依据是项目宪法、部署规范、现有仓库结构和各脚本元信息。影响是任何实现、文档、部署或自动化变更都必须先满足这些规则，CI 和人工验收才有共同判据。

🧭 1️⃣ 总体原则

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

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

AgentMeshOS/
│
├── docs/
├── deploy/
├── docker/
├── nomad/
├── network/
├── storage/
├── compute/
├── scheduler/
├── control-plane/
├── ai-runtime/
├── applications/
├── scripts/
├── tools/

小项目目录规则（强制）

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

文档与计划目录规则（强制）

docs/ 是项目面向团队和运维的唯一正文目录。架构原始设计继续放在 docs/architecture/；端口、客户端、迁移和脚本等专题文档可保持其既有稳定 URL。

实施计划、执行看板、待办与完成归档必须统一放在 docs/plans/，禁止再创建平行的计划目录、零散 README 或临时进度文件。该目录固定使用以下职责划分：

docs/plans/
├── index.md        # 计划看板与状态入口
├── in-progress.md  # 当前执行计划
├── phase-<n>-*.md  # 各阶段稳定细化页；当前、预备和占位阶段均在此明确工作包
├── state.json      # 当前阶段唯一机器状态源
├── feasibility.md  # 已取消阶段三的历史兼容页，保留旧 URL 与调查证据
├── plan-template.md # 所有实施计划的分布式底座接入声明模板
├── backlog.md      # 后续路线与候选计划
├── completed.md    # 完成归档总览与旧锚点兼容
├── completed-*.md  # 各主题独立归档正文
├── archive-manifest.json # 归档主题、文件和导航清单
└── history.md      # 只追加的阶段和计划状态历史

规则：

  • 计划状态只能在存在真实验收证据或项目负责人明确确认后变更；不得根据推测将任务标记为已完成。
  • 当前阶段编号、标题和状态只在 docs/plans/state.json 中定义；每次状态变化必须同步正文，并通过 python3 scripts/ci/agentmeshos-plan-state-check.py。Docs CI 和发布收尾会自动执行该检查，任何页面仍保留旧状态时禁止构建或宣称发布完成。
  • 当前阶段的 in-progress.md 只保留实时摘要、接入声明和证据；完整工作包、四态状态和阶段出口写入对应 phase-<n>-*.md。后续阶段也必须先有预备或占位页，避免只在实施时临时细化。
  • 无状态生产部署的启用或暂停只由仓库变量 AGENTMESHOS_ENABLE_RR_PRODUCTION_DEPLOY 控制。临时停部署必须把变量设为 false，禁止将 if: ${{ false }} 作为长期状态提交；CI 必须通过 scripts/ci/agentmeshos-production-deploy-gate-check.py 校验四个无状态工作流仍调用统一门禁和受控发布工作流。
  • 活跃脚本、配置和部署源不得提交 MM 公网 IPv4/IPv6；只有明确标注为历史且排除在恢复路径外的迁移记录可以保留旧值。Repository Guardrails 工作流必须执行 scripts/ci/agentmeshos-edge-hardcode-check.py，并通过 scripts/ci/tests/edge-hardcode-check-test.sh 验证旧地址注入会失败、逻辑主机名正常通过。
  • Git 推送完成不等于提交成功。每次 push 后必须在仓库根目录执行 bash scripts/ci/post-push-verify.sh；该入口以远端分支实际 SHA 为准，解析本次提交应触发的 push 工作流，并通过 scripts/ci/monitor-github-actions.sh 检查完整 SHA 对应的最新 Run、Job 和 Step。任一相关 Action 为 failure、cancelled、timed_out、startup_failure、action_required、stale、必需工作流缺失或必需工作流被跳过时，都不得宣称提交成功，必须先修复、重新推送并重新运行该门禁。
  • 已完成事项必须先追加 history.md，再创建一个 completed-*.md 独立归档正文，并更新 archive-manifest.json 与 completed.md 总览；当前执行事项写入 in-progress.md，可调整优先级的后续路线写入 backlog.md。
  • MkDocs 的“实施计划”导航只允许计划看板、当前阶段、持续运行与工程专项、计划规则和后续路线；completed-*.md、已关闭阶段、历史兼容页和完成归档不得混入当前实施计划。CI 必须通过 scripts/ci/agentmeshos-plan-nav-check.py 拒绝归档页混入、重复导航目标和缺少当前阶段摘要/详情入口。
  • 每个实施计划必须使用 docs/plans/plan-template.md，明确接入或不接入分布式底座、使用层、Adapter、主节点与 Worker 执行映射、数据路径、凭据路径、生命周期和验收证据；该声明是计划完整性要求，不是审批门禁。纯文档计划也必须明确“本阶段不接入”及原因。
  • 独立归档正文只允许追加更正记录，不得覆盖既有事实或证据；completed.md 不复制完整正文，只保留主题顺序、链接和旧锚点兼容。
  • 为兼容外部链接而保留的旧计划页必须明确说明归档状态，并链接到 docs/plans/，不得继续维护过期的执行结论。
  • 文档站导航按一级分类、二级主题和具体文档组织；一个二级主题超过 6 篇文档时，才新增三级分组，避免把普通页面堆成顶层菜单。

脚本存放规则（强制）

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

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/。
  • 101 是项目代码、资料和 GitHub 同步权威，并负责 CI/CD 构建、测试、版本摘要、发布记录与回滚协调；GitHub Actions 默认执行构建和发布编排。GitHub 与 101 工作区均不是生产运行环境。
  • RR 只部署 CI/CD 已发布且带版本号和 SHA-256 摘要的产物，不得从工作树直接构建。人工应急发布必须复用同一产物和摘要，记录操作者、原因、发布/回滚结果与健康验收；不得借应急路径复制凭据或建立第二控制面。
  • 公共脚本目录必须继续按用途和小项目名分层，禁止把多个项目脚本直接堆在 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 或冒烟验证后才能提交。

Web、App 与控制台弹窗规范（强制）

  • 所有需要用户确认、补充说明、选择分支、授权或展示可关闭详情的弹窗，必须使用符合当前项目视觉主题的自定义居中弹窗。
  • 禁止调用浏览器系统 alert、prompt、confirm，也不得以系统原生对话框作为临时替代。
  • 自定义弹窗必须包含明确标题、上下文说明、取消/关闭路径、可读的确认动作和键盘焦点管理；移动端应保持居中、无横向溢出。
  • 新界面应复用项目既有弹窗组件或在同一视觉系统内扩展，避免不同页面出现不一致的系统样式。

Docker 镜像生命周期与容量规则（强制）

  • Docker 部署脚本只有在新容器启动成功且本机健康检查通过后，才允许执行默认镜像回收。
  • 项目容器镜像和正式 docker run 入口必须显式使用 TZ=Asia/Shanghai；容器时区属于正式部署契约，不能只靠宿主继承或一次性手工修改。新增容器必须通过 scripts/ci/agentmeshos-container-timezone-check.py。
  • 默认回收范围仅限未被任何容器引用的 dangling 镜像；运行中的 current 镜像必须保留，并为每个可回滚服务保留不超过一个已经验证过的本地 rollback 镜像。清理脚本必须保护所有 running/stopped 容器引用的 image ID 以及带 rollback、latest、current 标签的 image ID；不能把“未被引用”直接等同于“可以删除”。历史 SHA 不作为 RR 本地长期备份，归档与保留由 GHCR 的显式 retention 策略负责；在 retention 数量或期限尚未配置和验证前，不得删除远端历史版本，也不得把它表述为永久可回抓。
  • 默认部署流程禁止自动删除容器、卷、网络、容器日志和 BuildKit 构建缓存。BuildKit 缓存清理只能作为人工确认的容量维护操作，并应先盘点影响和预计释放空间。
  • 部署脚本和维护脚本必须提供镜像、容器、卷和 BuildKit 缓存的容量盘点结果；主机磁盘使用率达到 80% 时进入关注状态，达到 90% 时必须暂停非必要构建和部署并执行人工容量处置。
  • 镜像清理必须保留当前生产版本、已验证回滚版本以及仍被其他容器引用的共享层；清理前后必须记录磁盘使用率、Docker 空间统计、运行容器健康状态和回收结果。
  • 删除带标签的旧镜像、卷、日志或 BuildKit 缓存不属于默认部署动作，必须单独说明目标、保留范围、回滚影响和确认人。

单用户任务调度与目录规则（强制）

  • AgentMeshOS 当前按单用户系统运行。任务提交后由主节点读取当前 Nomad 节点状态和节点标签，按角色、CPU、内存、磁盘和 batch_allowed 直接选择可用节点并提交；不设置审批、准入报告、签入报告、人工维护窗口、Run lease、epoch 或普通状态 TTL。
  • 普通任务不得重新引入批准单、人工申请、多级审批或重复结果报告。只有存在数据破坏风险时，才允许使用写入围栏、只读模式、dry-run/apply、删除前校验、迁移校验或恢复前写入阻断；围栏必须最小化、可审计、可撤销。
  • 密码、Token、Key、一次性外部凭据和临时挂载凭据仍必须使用最小权限、0600 和任务结束撤销/删除；除此之外的任务状态、节点能力快照、运行日志和长期配置不设置过期时间。
  • 统一任务日志是唯一运行追踪入口。失败、重试和异常通过日志查询，不另建审批报告、准入报告、租约报告或结果报告。
  • 告警中心接收 C2/C3、Cloudreve 健康探针和 AI Runtime 的脱敏事件。Cloudreve 探针只负责发现和通知，不作为普通任务门禁；恢复事件必须关联关闭同一组件上下文的活动告警，历史事件不得重复交给 AI Boss。
  • 系统云盘是底座必需服务。健康检查应覆盖 Cloudreve 公网 HTTPS、受限 WebDAV 目录和 dd 资源状态；不得引入 Nomad 对账器、CSI、JuiceFS、MariaDB 或旧云盘恢复机制。管理员 Console 的角标仅表示已打开会话内的可见告警，不得伪称已发送外部通知。
  • 企业网盘中的 Runtime 与任务自动化仅维护 AgentMeshOS-临时 和 AgentMeshOS-长期 两个系统根目录。用户既有 Project 是独立项目库；RR 不挂载或同步它。101 工作区和 GitHub 是 AgentMeshOS 项目代码权威，101 仅可使用经正式验收的单实例、单向、限流 Project 控制器写入 Cloudreve；禁止双向同步、挂载和远端回写。
  • AgentMeshOS 系统自动化 WebDAV 凭据统一为 File-Hub 凭据；RR 生产 Runtime 只从本机 /root/.codex/credentials/file-hub.env 读取，101 本机自动化只读取自己的同路径文件，两个文件均必须为 root:root 0600，节点之间不得复制或互相注入。旧 /etc/agentmeshos/cloudreve-system-webdav.env 只保留为迁移回退材料，不进入正式部署链路；103 不保存 WebDAV 凭据。
  • Project 专用 WebDAV 凭据不在 RR 保留，只在 101 的独立 root-only 配置中使用；AgentMeshOS 系统自动化 WebDAV 凭据只服务 AgentMeshOS-* 自动化目录，不得删除、复用或误称为 Project 凭据。
  • 临时目录 允许自动任务读写和清理；长期目录 默认只允许自动任务读写和创建，不自动删除已有长期内容。该限制属于 AgentMeshOS 自动化策略，不能依赖 WebDAV 的目录级删除 ACL。
  • 业务文件传输继续强制走 Cloudreve 公网 HTTPS 数据面：镜像、安装包、构建产物、测试夹具、附件、成果、归档和恢复包不得经 SSH、Tailnet、Nomad 节点间网络、主节点代理、Worker 间复制或共享主机路径传送。另允许小于 1 MiB 的受控配置、凭据和紧急脚本经 Tailnet 临时传输；传输前后必须核验来源、目标、SHA-256 和文件权限（凭据 0600，脚本 0755），使用临时文件并在完成后清理。Worker 必须使用登记的 cloud.yohan.fun 公网下载地址，写入任务临时目录，完成后删除；Worker 不保存 WebDAV 凭据。101 Project 同步是经公网 HTTPS 执行的专用例外，业务字节不经 Tailnet 转运。唯一非文件化例外是最大 1 MiB 的结构化 JSON 回调证据直接写入 Runtime SQLite。
  • 101 的 /srv/codex-hub-backup 是全局独立自动备份边界；任何备份任务开始前必须确认 findmnt 来源为 /dev/sda1，并对备份内容保存 SHA-256。备份用于恢复，不得阻止已经确定的 Project 删除同步；备份脚本必须先执行自身保留策略和过期对象清理，再按最低安全线判断是否继续写入，备份盘故障不得静默降级到 /backup。Codex Hub 本机恢复快照默认最多保留 10 份，写入前必须先清理超额历史并预测本次写入是否会侵占最低剩余空间；temp、.venv、node_modules、build、dist 和缓存目录不得进入该恢复快照。
  • 所有备份异常必须进入 Console 告警中心并保持活动角标，直到同一备份组件产生真实恢复事件。备份脚本可以保留防止写满磁盘、错误设备和凭据泄露的最小门禁，但不得设置与实际备份大小无关的高水位前置门禁，导致可恢复备份长期不运行。

SSH 公钥追加命令规则（强制）

任何需要向 Linux 节点 authorized_keys 追加公钥的说明、脚本或菜单输出，都必须先处理目标文件最后一行缺少换行的情况。禁止直接给用户提供只包含 echo ... >> ~/.ssh/authorized_keys 或 printf '%s\n' ... >> ~/.ssh/authorized_keys 的裸追加命令，因为当原文件最后一个字节不是换行时，新公钥会与上一把公钥粘在同一行，导致 SSH 公钥认证失败。

追加公钥前必须先完成目录权限、文件存在性和尾部换行检查，再追加完整公钥行。推荐模板如下：

install -d -m 700 /root/.ssh
touch /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys

if [ -s /root/.ssh/authorized_keys ] \
  && [ "$(tail -c 1 /root/.ssh/authorized_keys | od -An -t x1 | tr -d ' \n')" != "0a" ]; then
  printf '\n' >> /root/.ssh/authorized_keys
fi

printf '%s\n' 'ssh-ed25519 AAAA... comment' >> /root/.ssh/authorized_keys

系统级 SSH 管理公钥不得绑定 Tailnet 来源地址。系统恢复入口必须同时保留物理/公网和 Tailnet 两条独立路径；RR、101、Home 是三个同级管理来源，禁止用 from= 使任一管理公钥只能从特定 Tailnet 来源登录。若需要限制端口转发或 Agent 转发，限制项仍与公钥保持在同一行，例如：

局域网节点没有独立公网入口时，物理恢复路径可从同一 LAN 上的系统主机建立第二跳 SSH，再直连目标节点的物理地址。该主机只承担系统 SSH 跳板，不得以项目节点、Nomad 任务或 Tailnet 代理替代。

printf '%s\n' 'no-agent-forwarding,no-port-forwarding,no-X11-forwarding ssh-ed25519 AAAA... agentmeshos-main' >> /root/.ssh/authorized_keys

发布或回复这类命令前，必须在 temp/ 中用“原文件末尾无换行”的测试样本复现并验证，确认追加后每把公钥各占一行。验证至少检查：

awk '{print NR, NF, $1, $NF}' temp/authorized_keys_append_test.good
sed -n 'l' temp/authorized_keys_append_test.good

🧩 3️⃣ 模块设计规范

每个模块必须包含：

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

要求：

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

🔌 4️⃣ API 规范

  • 统一 REST / JSON
  • 禁止私有协议
  • 所有模块必须提供 API 文档
  • 未来可扩展 gRPC（但不作为 v0.1 标准）
  • AI Runtime 服务进程可通过内部适配器直接调用 Nomad 和 Storage API；模型上下文、普通 Agent 和 MCP 工具不得读取底层凭据或访问 Worker、Docker Socket 和任意主机命令

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

Agent 定义：

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

结构：

Agent {
    input: Task
    plan: Steps
    execute: Runtime Adapter Calls
    output: Result
}

原则：

  • Agent 不能直接控制 Node
  • Agent 只能提交任务给 Scheduler
  • Agent 必须无状态设计（Stateless）
  • Agent 的 execute 指“调用受控接口提交动作”，不表示直接在节点上执行命令
  • AI BOSS 是语义总控：负责目标理解、结构化规划、选择已登记逻辑能力、依赖与并行、成果契约、语义审核、返工和汇总。
  • Runtime 只验证契约、能力、安全、预算、资源、状态与幂等，不得静默替换 AI BOSS 选择或代替其进行业务语义派工。
  • Nomad 只在 Runtime 已验证任务包中选择具体节点；Worker 不得自行扩大目标、权限、输入来源或预算。

P3-6-2 OmniRoute 与 AI 免费策略规范

  • Agent 角色、任务类型、数据敏感度、质量和业务预算只用于选择 OmniRoute 模型/Combo；Provider、额度、健康、冷却和回退由 OmniRoute 负责。
  • AI 免费策略只能选择 OmniRoute 中合法、可审计的免费 Combo；禁止抓取共享 Token、绕过限额、批量注册账号或违反服务条款。
  • Runtime 不维护 Free AI Source Registry、免费 Provider 目录同步、健康检查或价格表；候选发现历史只保留非敏感归档，正式 Provider、模型、额度、用量和价格事实以 OmniRoute 为唯一权威。
  • OmniRoute 只使用官方 npm 包、官方 Node、官方 CLI/API、官方控制台和官方正式发布。禁止修改上游源码、添加补丁、维护私有 Fork/私有分支/私有镜像、重新编译、手工替换已安装包文件或改写构建产物；官方能力不足时只能调整官方配置、选用官方已支持的其他 Provider/模型或提交上游。
  • 宿主层 systemd、网络代理、防火墙和出口路由可以作为外部适配保留，但不得改变 OmniRoute 包内容；每个适配必须记录用途、文件路径、版本适用范围、回滚点和真实验证结果。生产以 root 使用官方默认 npm 安装位置和 /root/.omniroute 数据目录；每次升级必须记录官方版本与发布物 SHA-256，完成备份、隔离恢复、数量核对、协议 Smoke、入口回归和数据快照回滚验证。
  • Provider 明文密钥、OAuth 和连接凭据只能存在于 OmniRoute 的 root-only 环境和数据边界；禁止写入 Runtime SQLite、Git、文档示例、浏览器响应、普通日志、任务输出或 Worker 环境。
  • 外部 CLI 单模型通道的 Key 例外地只可保存在 CLI Agent Gateway 持久卷的 Fernet 加密 SQLite 中；Fernet 主密钥只能在 Gateway root-only 环境。Console 提交后立即清空输入，Runtime 不读取 URL/Key，Gateway API 不回显明文或密文。通道 URL/Key/provider/model 变更必须重新 Smoke，不能自动启用。
  • Console 只展示 OmniRoute 非敏感健康、连接/Provider 数量、模型策略和 Runtime 业务成本，并提供官方 Dashboard 入口；禁止提供 Provider CRUD、密钥预览、模型刷新或免费来源启停。
  • 每个新任务只保存非敏感 OmniRoute 模型策略快照；运行中任务不得被后续策略变更重写。
  • Runtime 的模型目录只允许调用 OmniRoute 官方 /v1/models，不得按 Provider Base URL 建立第二套目录探针。
  • Runtime 使用单一高权限 OmniRoute Key 时，该 Key 只能写入主节点 root-only 配置；Agent、Worker、浏览器、Console 响应、普通日志和 Git 均不得取得。工具调用仍须经过 Runtime 白名单，不能因 Key 具备 admin/manage 而开放修改 Provider、Combo、路由、预算或缓存的工具。
  • 模型级 PII/凭据遮蔽、Prompt Injection Guardrails、模型/Combo Evals、MCP 工具目录/执行/原始审计和通过质量门槛的 Compression 由官方 OmniRoute 承担，Runtime 不维护第二套实现。
  • Memory、A2A、Cloud Agent、Context Sources 及容器/Shell/文件类 Skills 默认关闭；只有独立数据隔离和权限验收通过后才能另行启用。
  • 必须分别记录调用配额、模型成本、基础设施成本、任务质量、失败、真实收入和净收益；自动化完成不等于盈利完成。

🧠 5.5️⃣ 状态模型规范

  • 系统云盘文件统一通过 cloud.yohan.fun 公网 HTTPS 的 Cloudreve WebDAV/API；最大 1 MiB 的 Worker JSON 回调证据只进入 Runtime SQLite，较大/长期 Runtime Artifact 只允许由主节点 root-only Cloudreve WebDAV Adapter 写入 AgentMeshOS-长期/runtime-artifacts，禁止给 Worker、模型或 MCP 凭据，禁止自动删除长期内容
  • 控制面元数据必须进入 Metadata Store：任务记录、节点注册、心跳、Token、审计日志、项目状态、AI 索引
  • 模块不得跨层直连 Metadata Store，统一通过 Storage Module 或 Control API 访问

P4 计划、成果与验收规范

  • 新计划必须持久化 plan_id、幂等请求 ID、会话/交互引用、目标、意图、状态、风险、数据等级、预算快照、能力快照、规划调用引用、版本和替代关系。
  • 结构化规划必须使用 Pydantic 严格契约。单计划最多 20 个任务、50 条依赖边、8 层深度，默认最多 4 个并行任务；解析修复最多一次，第二次失败后停止，不执行部分结果。
  • 所有写接口必须使用幂等键并校验当前状态；列表必须分页；SSE 必须支持最后事件 ID 恢复。响应不得包含凭据、主机路径、Job HCL、完整 Prompt 或隐藏思维链。
  • 能力目录必须登记版本、角色、输入输出契约、允许数据等级、执行方式、任务包、资源上下限、成果类型、检查器、可用状态和原因。未登记能力必须明确不可用，模型自述不能形成能力。
  • 成果类型使用可扩展字符串 ID，不使用封闭 SQL 枚举。任何未知成果允许登记为 other，但不能自动验收。
  • 成果必须保存计划/任务关联、版本、数据等级、来源运行、安全位置引用、MIME、大小、SHA-256、正式访问方式、限制、风险、回滚引用和被替代关系；长期成果不得自动删除。
  • 验收标准必须可判断并区分必需/可选以及 deterministic、boss_review、benson、mixed 检查方式；“质量好”“基本完成”等空泛标准必须改写或提出澄清。
  • 证据必须关联成果和验收标准，并保存来源、摘要、安全引用、哈希、可访问状态和数据等级。文件名、URL 字符串或模型声明本身不构成通过证据。
  • AI BOSS 审核只允许 accept、rework、insufficient_evidence，且必须引用真实存在的标准和证据。模型调用成功不等于审核通过，必需确定性检查失败不可被模型覆盖。
  • completed 只表示最终验收完成。执行结束后必须依次完成成果登记、必需检查、AI BOSS 审核以及适用的 Benson 决定；前置任务未最终验收时不得释放依赖。
  • 删除、付款、外部发信/提交/注册、权限与安全策略、网络/SSH、不可恢复生产变更、证据不足、检查器不支持、风险未知和检查冲突必须进入 Benson 决定；Runtime 保留最低风险等级，模型不能降低。
  • 所有计划、检查、审核、人工决定、返工、重开、发布和回滚写入追加式审计；旧任务标记兼容策略，不伪造 Benson 决定。

AI 任务计划模板必填项

所有未来 AI 任务计划必须明确：目标、Worker 能力、预期成果、成果存储位置、验收标准、自动检查器、证据、AI 审核、Benson 决定条件、风险、回滚、Token 预算和生命周期。缺少任一项时必须明确“不适用”及原因，不能以省略代替设计。

⚙️ 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 Application → AI Runtime Adapters → Scheduler → Compute → Storage

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

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

🚀 下一步

部署规范由 07_部署规范.md 维护；AI 平台架构由 11_AI平台与应用架构.md 维护。 - Tailscale 网络部署 - Docker 执行部署

⚠️ 未决项 / 需要决策

当前无新增用户决策项。后续若调整目录、发布门禁、脚本版本、权限模型或节点职责，必须先修改对应的架构原文，再按该原文更新实现、测试和部署证据。