AgentMeshOS 项目整合总计划

总体目标

在不破坏既有 101/RR 剥离边界的前提下，将 101 项目控制面、RR 生产面、GitHub 发布面、Docs 文档面和 Console 节点面统一为可验证的事实来源，并先完成 GitHub Organization 级共享 Self-hosted Runner 的可行性验证与迁移。

当前执行状态（2026-08-31）

• 已完成并实测：多项目 Actions 监控器支持 owner/repository + 完整 40 位 SHA，并逐个核验 Workflow、Job、Step；提交 51ed48a627ad105932a1f2f73437f02df752e0f2 的相关工作流全部成功。
• 已完成并实测：RR 的 Docs、Console、Status、API 四个无状态容器已统一运行 sha-51ed48a627ad105932a1f2f73437f02df752e0f2，容器健康检查和公网端点均通过。
• 已完成并实测：API 节点职责目录、Console 节点字段、101/RR/103/jj 边界、RR Release 资产校验、发布锁和告警闭环。
• 已完成基础门禁证据但未完成 Stateful 全量放行：RR Auth/AI Runtime 数据库 PRAGMA quick_check=ok，环境文件为 root:root 0600，CLI Gateway 为只读根文件系统且丢弃全部 Linux capabilities；真实业务对话、旧数据读取、恢复演练仍待执行，因此 Auth、AI Runtime、CLI Gateway 不接入生产自动升级。
• Organization 共享 Runner 尚未注册：当前 GitHub 主体为个人 User，Organization Runner API 不可用。仓库继续保留 AGENTMESHOS_RUNNER_LABEL 显式选择和 ubuntu-latest 回退；不得将该外部条件伪造为已完成。
• 存储证据：101 /srv/codex-hub-backup 当前由 /dev/sda1 提供；RR /backup 位于 RR 系统盘，只作为已记录的历史备份路径，不视为独立备份盘。
• 2026-08-31 Stateful 快照演练证据：RR /backup/agentmeshos/stateful-gates-20260831T074729Z/auth.db 的 SHA-256 为 97ab6b014568c44dc3cbc14c0322cc86e220425bcf07be226e3bb46e875f1635，runtime.db 的 SHA-256 为 71c3813316391044707b0fd6acdd01b35e6db2fc09f6231dac1bdfc443ea6bf4；两份快照 PRAGMA quick_check=ok。该路径位于 RR 系统盘，仅作恢复演练证据，不替代 101 独立备份盘。
• 2026-08-31 CLI Gateway 实际对话测试证据：AgentRouter/Codex CLI 的 deepseek-v4-flash（managed-1a5e243bcb854e3b872d84ac52d48ee1）和 AgentRouter/Claude CLI 的 deepseek-v4-flash（managed-46404ae625604c90aea8fa3217def1e1）均通过一次最短测试对话，接口返回 status=passed。测试接口仅返回放行状态和 usage，不持久化或输出对话正文；限量模型未以本次偶发结果替代长期可用性结论。

固定边界：

• 101 只负责项目源码、资料、GitHub、CI/CD、共享 Runner 和 RR 发布协调；Runner 是执行资源，不改变 101 的项目控制角色。
• RR 只负责生产 Runtime、Bridge、生产容器、Nomad 和生产数据。
• 103 是标准计算 Worker。
• jj 是受限计算 Worker，不是 Runner 后备节点。
• 101 是长期 Self-hosted Runner。101 暂时不可用时，仅回退到 GitHub-hosted Runner，不切换到其他项目节点。
• Auth、AI Runtime、CLI Gateway 本轮只完成门禁和真实演练，不接入生产自动升级。
• 每次 GitHub 推送后，必须等待目标完整提交 SHA 的所有最新 Actions 工作流完成；failure、cancelled、timed_out 必须定位、修复、重跑，全部成功后才能进入下一项。

第 0 阶段：Organization 级共享 Self-hosted Runner

0.1 可行性验证门槛

在迁移前验证 101 的 CPU、内存、磁盘、Docker、网络、并发、构建缓存和长期运行能力，并用一个最小示例工作流完成依赖安装、源码分析、单元测试、Docker 构建和结果上传。验证结果必须记录真实日志、耗时、资源峰值和失败原因；不可用结论必须经过最小化二次验证。

0.2 Runner 安装和隔离

• 在 GitHub Organization 注册一个共享 Runner，固定标签为 self-hosted、linux、x64、agentmeshos-ci。
• 使用专用 Runner 账户、独立工作目录和最小文件权限，不读取 /root/.codex，不接管 Codex 系统服务。
• Runner 工作目录、缓存、临时产物和清理策略独立于项目源码；多项目执行统一使用 Runner 专用临时目录，项目自身的临时文件仍按各项目规则放在对应项目的 temp/，任务结束后清理。
• 101 的项目控制职责与 Runner 执行职责保持边界：Runner 可以执行授权 Job，但不运行生产 Runtime、System Operations Bridge 或云盘后端。
• RR 发布凭据按既定方案长期放在 101 的 root-only 文件中，由受控发布脚本读取；普通构建 Job、Pull Request（尤其是 fork）和未受保护分支无权读取。只有受保护分支通过审批门禁后，专用发布 Job 才能调用该脚本。

0.3 多项目接入模型

所有获授权且满足 101 执行环境要求的 GitHub Actions Job 默认由该共享 Runner 执行，包括依赖安装、源码分析、单元测试、Docs 构建、Docker 构建、镜像推送、Release、RR 部署协调、公网验收、回滚和 Actions 失败监控。需要 GitHub 托管环境、特殊硬件或无法在 101 执行的 Job 必须显式标注并使用 GitHub-hosted Runner，不得被强行调度到 101。至少纳入当前 /root/project 下的 AgentMeshOS、OwlMonitor_app、ota、pose-radar-ti、owlFront_mock、AWRL6844EVM_J5_link_WT99P4C5-S1_J4 及其他独立仓库。

Organization Runner 按项目授权接入。项目仍独立保留自己的仓库、Workflow、Run ID、日志、镜像、Release 资产和失败记录；共享 Runner 只提供执行资源，不合并项目控制权。每个项目的 Workflow 通过标签选择 Runner，并保留必要的 GitHub-hosted fallback 配置。

0.4 Actions 状态监控和放行

• GitHub 继续负责 Workflow 编排、状态、Job/Step 日志、Secrets、Environment 和审计。
• 状态必须从 GitHub Workflow、Job、Step 和日志 API 获取；101 本地 Runner 日志只补充 Runner 离线、磁盘不足、Docker 异常等执行环境信息。
• 每次推送后用完整 40 位 SHA 查询该提交的全部最新工作流，记录 run URL、run ID、Job、Step、结论和失败日志。
• failure、cancelled、timed_out 或 Runner 离线均不得放行下一阶段。先定位根因，修复后重新推送并再次监控。
• Runner 暂时不可用时，由 Workflow 的显式标签和条件切换到 GitHub-hosted Runner；不得静默改用其他项目节点。恢复后再验证 101 Runner，不将 jj 或其他节点作为后备 Runner。

0.5 Runner 阶段验收

验证共享 Runner 可被多个授权项目选择；符合条件的 Job 默认在 101 执行，例外 Job 和 Runner 不可用时能按显式配置回退 GitHub-hosted；构建产物、镜像、Release 和部署协调的 commit SHA 一致；GitHub 页面仍可直接查看进度和状态；失败工作流可被监控、修复和重跑；101/RR 角色边界、凭据隔离和 Codex 系统服务边界均未被破坏。通过后，边迁移、边执行、边验收后续阶段。

第一阶段：统一 101/RR 角色和文档事实

1. 修正控制台中的旧角色描述

修改 tools/console-site/src/index.html：

• 删除“101 / 103 承载 Batch Worker”的合并描述。
• 101 显示为“项目控制与发布协调节点”。
• 103 显示为“通用计算 Worker”。
• 明确 101 不运行生产 Runtime 或 System Operations Bridge。
• 明确 101 可以执行受控、可替换的 Nomad 无状态任务，但这不是它的主角色。

补充 Console 浏览器契约：101 不得被渲染为普通 Worker；103 可以被渲染为计算 Worker；101 的职责、节点类型和部署限制必须来自 API 返回值，不得在前端重新推断。

2. 修正当前有效架构文档

只修改当前有效文档，不改写历史证据的原始事实：

• docs/architecture/00_项目交接说明.md
• docs/architecture/03_总体架构设计.md
• docs/architecture/04_核心模块设计.md
• docs/architecture/08_AI协作规范.md
• docs/architecture/10_系统总结.md
• docs/architecture/05_存储架构规划.md
• docs/node-role-capability.md

统一术语：

节点	类型	主职责	不承担
101	项目控制节点	代码、资料、GitHub、CI/CD、共享 Runner、RR 发布协调	生产 Runtime、Bridge、云盘后端
RR	生产部署节点	Runtime、Bridge、生产容器和 Nomad	项目源码控制、Project 同步和共享 Runner
103	通用计算 Worker	Nomad Client、无状态计算任务、遥测	生产控制面和云盘
jj	受限计算 Worker	受限 Nomad 任务	自动 Batch、共享 Runner，除非重新验收

旧的 DETACH 历史证据保留原文，但在文件顶部增加“历史证据，不代表当前运行状态”的标识，避免把历史快照当成现状。

3. 更新 Docs 站点导航和文档状态

建立三种文档状态：当前有效规范、已完成归档、历史兼容入口。处理重复或过时的计划入口，特别是“最终重启/清理门未完成”“RR 项目控制链路仍在运行”“101 是普通 Worker”和重复的阶段七、阶段八入口。

验收：Docs 首页、架构入口、节点角色页、部署规范页内容一致；Console 的 Docs iframe 与公网 Docs 页面显示相同版本信息；历史证据不删除，也不继续放在“当前规范”导航下。文档必须补充 101 Runner 角色、Organization 共享 Runner、多项目接入、GitHub-hosted 回退和 101/RR 边界。

第二阶段：建立统一节点角色清单

4. 新增版本化节点角色目录

在 API Gateway 使用单一节点目录作为职责来源，至少包含：

id、mesh_name、host_name、address、platform、system_family、node_type、role、is_worker、batch_allowed、production_node、auto_deploy_allowed、nomad_profile。

固定事实：pcdell-101 为项目控制节点，is_worker=false、batch_allowed=false，不允许普通 Worker 自动部署；pcdell-103 为标准计算 Worker，is_worker=true，允许标准无状态任务；jj 为受限 Worker，batch_allowed=false；main/RR 为生产控制节点，不作为普通计算 Worker；dd 为存储节点；nas-sz 为 NAS；Windows、macOS、Android、iOS 为管理终端或移动客户端。

Nomad、Tailnet inventory 和 metrics 只能补充在线状态、系统信息和遥测，不得覆盖目录中的职责定义。

5. API 输出统一能力字段

扩展 /api/status、/api/public/status 和管理员节点接口。公共接口只输出脱敏后的角色和类型；管理接口额外输出 batch_allowed、auto_deploy_allowed、production_node 和 nomad_profile。所有接口使用同一节点目录计算职责分类，禁止前端仅根据 system_family == Linux 判断可部署性。

6. Console/Status 增加职责筛选

Status 页面保留操作系统筛选，同时新增：全部节点、项目控制节点、计算 Worker、受限 Worker、存储节点、NAS、公网边缘节点、管理终端、移动客户端。Console 节点管理页显示节点类型、节点角色、是否 Worker、是否允许 Batch、是否允许自动部署和当前管理状态。

验收：Linux 分类不会把所有 Linux 节点误当作 Worker；101 不出现在普通计算 Worker 列表；职责统计总数与节点总数一致；全部节点、操作系统筛选和职责筛选数量可交叉验证。

第三阶段：独立 Release bundle 与无状态 CD

7. 把部署脚本从 Docs 网站解耦

GitHub Actions 在镜像构建成功后生成版本化 Release bundle，字段为 service、commit_sha、deploy_script、rollback_script、sha256、created_at。bundle 上传到 GitHub Release 资产或等价版本化发布目录。RR 只接受完整 40 位 SHA，下载对应资产，校验 manifest 和 SHA-256 后执行。Docs 继续提供人工下载入口，但不再是生产 CD 的唯一依赖；资产不可用直接失败，不静默降级。

为 bundle 下载、部署、健康检查和回滚分别设置超时；增加 bundle 不存在、SHA 不匹配、资产版本不一致测试。验收 Docs 暂不可用时 RR 仍能发布，错误 bundle 不执行，Action、Release 资产和 RR 镜像 SHA 一致。

8. 增加发布锁、超时和审计

发布入口增加同一生产环境并发锁、镜像拉取超时、容器启动超时、公网健康检查超时和 rollback 超时。每次发布记录：

service、commit_sha、image、previous_image、deploy_started_at、deploy_finished_at、health_result、rollback_result、failure_stage、failure_reason。

9. 增加完整公网验收

四个无状态服务 CD 完成后验证 Docs /healthz 和首页；Console 首页、认证回源和 Docs iframe；Status /healthz、节点列表和 101 角色；API /health、/api/status、/api/public/status；外部 HTTPS、容器健康状态和实际运行镜像一致。早期失败或取消的工作流保留原因，后续成功运行明确覆盖。

第四阶段：发布失败告警和 Console 闭环

10. 统一发布事件和告警

统一发布事件字段：service、commit_sha、image、previous_image、deploy_started_at、deploy_finished_at、health_result、rollback_result、failure_stage、failure_reason。RR 在部署失败、健康检查失败、回滚成功和回滚失败时发送签名告警。

API Gateway 增加发布事件契约、重复事件去重和恢复事件关联测试。Console 告警中心展示真实失败阶段、失败原因和回滚状态，不再只显示“部署失败”。记录失败工作流 URL、Action run ID 和修复后的成功工作流 URL，形成同一提交的审计链。同一故障重复上报不得产生重复活动事件，真实恢复后告警可正确关闭。

第五阶段：分组接入 Stateful 服务门禁与演练

11. Auth Site

备份认证数据库并保存 SHA-256；检查数据库完整性、凭据文件权限和镜像兼容性；执行登录、登出、密码重置、会话恢复实际对话/请求验证；验证失败时镜像可回滚且认证数据库不回滚。只生成独立 Auth 发布报告，不接入生产自动 CD。所有门禁成功才允许生成“可考虑自动发布”状态。

12. AI Runtime

对 SQLite、WAL、SHM 执行一致性快照，执行 PRAGMA quick_check，对迁移前后表结构和关键计数做差异检查，验证旧任务、旧对话和旧成果可读取，验证 Runtime、OmniRoute、Nomad、Cloudreve 边界，演练镜像和数据库快照恢复，恢复后重新验证公网入口和任务读取。门禁未完成前继续人工发布，不自动升级生产。

13. CLI Agent Gateway

验证凭据不进入镜像、日志和构建产物；三个 CLI 通道分别执行真实对话测试；验证只读根文件系统、能力限制、进程数和网络边界；验证 Gateway 与 Runtime 版本兼容；演练 Gateway 独立回滚，确认不影响 Runtime 主链路。通过后再接入独立 CD，不与 Runtime 共用回滚事务。

共同验收：所有门禁成功才允许生成“可考虑自动发布”状态；本阶段不新增生产自动部署工作流；任一门禁失败必须保留日志、修复后重跑。

第六阶段：最终生产、容量和远端验收

14. RR 单节点限制与恢复演练

自动部署不等于高可用。RR 明确为“单节点生产、可恢复、非高可用”。评估并记录 RR 整机不可用时的接管节点、公网 DNS/入口切换、Runtime 数据恢复、凭据恢复边界、Cloudreve 与生产载荷恢复顺序，以及单节点故障期间 Console、Docs、API 的最低可用性。当前不把 jj 或其他项目节点作为 Runner 后备。

15. RR 磁盘和备份策略

结合最新备份策略核对 /backup 是否仍与 RR 系统盘共用；101 独立备份盘是否持续挂载在 /dev/sda1；RR 历史备份保留周期；生产镜像、rollback 镜像和系统 Codex 数据不可误删；容量告警阈值和归档策略。101 备份写入前用 findmnt 确认 /srv/codex-hub-backup 来源为 /dev/sda1。

16. 全链路远端验收

使用固定 commit SHA 验证 Docs、Console、Status、API 的公网 HTTPS、/healthz 或 /health、首页、认证回源、Docs iframe、API 节点职责字段、实际运行镜像和容器健康状态。验证 RR 四个无状态服务镜像与成功 Action 提交一致，发布日志包含部署、健康、回滚和告警记录，Action 历史失败均有根因说明且后续成功运行明确覆盖，101 /srv/codex-hub-backup 来源为 /dev/sda1，远端 main 可见且工作区干净。

多项目 Actions 统一监控规范

共享 Runner 不改变监控入口。任何授权项目更新后，监控器按 owner/repository + full_commit_sha 查询该提交关联的所有 Workflow Run，再展开 Job、Step 和日志；不得只看最后一个绿色步骤。每个项目独立记录失败 URL、run ID、失败阶段、根因、修复提交和成功覆盖 URL。Runner 本地监控用于补充执行节点健康，不替代 GitHub 的工作流事实来源。

测试和验收命令

本地静态检查：

git diff --check
bash -n scripts/deploy/**/*.sh
node --check tools/console-site/src/app.js
node --check tools/status-site/src/app.js
python3 scripts/ci/agentmeshos-plan-state-check.py

API 测试覆盖 101 角色和类型、103 Worker、batch_allowed、auto_deploy_allowed、节点职责统计、操作系统与职责筛选交叉统计和公共接口脱敏。Console/Status 测试覆盖 101 不显示为普通 Worker 或可自动部署节点、Linux 与 Worker 筛选独立、数量交叉一致、Docs/Status iframe 与 API 版本一致。

每个无状态服务至少执行正常构建、正常 RR 部署、公网健康检查、人工健康失败、自动 rollback、rollback 后健康检查以及发布日志和告警核对。Stateful 门禁必须保留失败日志并修复后重跑。

固定提交和放行规则

每个阶段均按以下顺序执行：

1. 本地静态检查和针对性测试。
2. 提交并推送 GitHub。
3. 使用完整 commit SHA 运行 Actions 监控脚本。
4. 收集并保存失败日志。
5. 失败则定位根因、修复、重新推送和重新监控。
6. 只有全部最新工作流成功，才进入下一阶段。
7. 最终同时确认 GitHub、RR、API、Console、Status、Docs 和共享 Runner 的事实一致。

默认决策和明确不做事项

• 默认使用 GitHub Organization 级共享 Runner，长期运行在 101；101 不可用时按 Workflow 显式配置回退 GitHub-hosted Runner。
• 默认使用 GitHub Release 资产；Stateful 服务只做门禁和真实演练，不自动升级生产。
• 不恢复 RR Project 同步；镜像、安装包、构建产物和业务数据不经 Tailnet 传输。小于 1 MiB 的受控配置、凭据和紧急脚本允许临时经 Tailnet 传输，但必须校验来源、目标、SHA-256、权限并清理临时文件。
• 不把 101 重新定义为普通 Worker，不把 jj 作为 Runner 后备。
• 不引入 Kubernetes、Argo CD、自建 Runner 集群或第二套调度器；本计划中的 Runner 是 GitHub Organization 共享执行节点。
• 不修改历史证据原始事实，只在当前导航和文档中标注其历史状态。

成功标准：当前有效文档、API、Console、Status、RR 生产容器、GitHub 发布记录和 101 共享 Runner 对 101/RR/103/jj 的定义完全一致；授权项目的 Actions 可在 101 执行并被统一监控；无状态服务自动发布可重复、可回滚、可审计；Stateful 服务只有在各自数据和凭据门禁完成后才允许考虑自动发布。