aios/aios

Fork 0

Files

T

Codex b2f90f24a3 docs(aios-v2): add target architecture

2026-07-20 11:32:16 +08:00

10 KiB

Raw Blame History

AIOS V2 目标架构

文档版本：V2R1C0-candidate
架构状态：目标架构已实现为候选代码，待预发布验证
适用范围：Control Plane、Agent Router、OpenClaw、Hermes、Web Console、GitOps、审计、部署与运维

1. 架构目标

AIOS V2 的核心目标是把分散在 OpenClaw、Hermes、Agent Router、局部 WebUI 和 GitOps 中的控制能力收敛为一个权威控制面，同时保留现有执行能力，避免推倒重写。

目标状态：

用户 / Web Console / Public API
                 |
                 v
          AIOS Control Plane
 Tenant | Identity | Agent | Task | Policy | Approval | Audit
                 |
                 v
      Execution Orchestrator / Agent Router
             /                      \
            v                        v
   OpenClaw Adapter            Hermes Boundary
            |                        |
            v                        v
   OpenClaw Runtime            Hermes Workers
             \                      /
              v                    v
       Result Reconciliation + Execution Evidence

设计结论：

AIOS 是唯一控制面。
Agent Router 是调度平面，不是第二控制面。
OpenClaw 是执行适配与 Runtime。
Hermes 是队列、Worker、Profile 与执行 Runtime。
Web Console 只调用 AIOS API。
GitOps 是代码、配置、文档和发布变更的唯一入口。

2. 从现有架构到目标架构

2.1 现有能力

现有系统已经具备：

OpenClaw 执行与 Fleet 能力。
Hermes Worker、Profile、队列和工作区能力。
Agent Router 路由经验和部分调度接口。
GitOps 分支、提交、审批、回滚和审计能力。
Tenant Context、Tenant Router、Memory Scope、SecretRef、Message Ledger 和审计候选实现。
局部 WebUI、Gateway 和自动任务领取能力。

2.2 现有问题

控制逻辑分散，可能存在多个任务事实源。
OpenClaw/Hermes 内部仍可能保存租户、策略或任务状态。
候选能力分散在多个分支，主线缺少权威实现。
WebUI 与 API 入口不统一。
分支名称、代码、测试和部署证据之间缺少映射。
多租户隔离多为逻辑约束，尚缺全链路生产证据。

2.3 演进原则

先加边界和适配器，再迁移控制权。
先复用接口，再替换内部实现。
先在候选分支验证，再受控提升。
不允许同时存在两套权威任务生命周期。
不以“大分支存在”代替验收证据。

3. 逻辑分层

3.1 Web 与 API 层

职责：

提供 Tenant、Agent、Task、Approval、Runtime、Audit、Execution Evidence 和 GitOps 页面/API。
依赖可信身份代理注入 X-AIOS-* 身份头。
不允许浏览器直接访问 OpenClaw 或 Hermes。
不允许客户端自行选择或覆盖 tenant_id。

候选实现：

active-runtime/app/aios_v2/app.py
active-runtime/app/aios_v2/gateway.py
active-runtime/app/aios_v2/console.py

3.2 AIOS Control Plane

权威职责：

Tenant Registry
Agent Registry
Task Lifecycle
Policy Decision
Approval
Audit Event
Runtime Inventory
Execution Evidence
Deployment/GitOps Status

不负责：

OpenClaw 内部执行细节。
Hermes Worker 内部执行细节。
直接持有 Runtime 凭据明文。

候选实现：

active-runtime/app/aios_v2/control_plane.py
active-runtime/app/aios_v2/persistence.py
active-runtime/app/aios_v2/execution_tracking.py
active-runtime/app/aios_v2/gitops_status.py

3.3 Execution Orchestrator / Agent Router

职责：

只接受 APPROVED 任务。
根据 Agent Registry 和 Policy Result 选择 Runtime。
生成 OpenClawCommand 或 HermesJob。
传播 tenant、task、trace、idempotency 和 policy version。
将 Runtime Result 回写 AIOS Task。

不负责：

创建租户。
修改策略。
绕过审批。
保存第二套任务状态机。

候选实现：

active-runtime/app/aios_v2/orchestrator.py

3.4 OpenClaw Adapter

职责：

验证签名命令。
执行、查询、取消、健康检查和回调。
支持幂等、超时和租户隔离。
把 Runtime 生命周期转换为 AIOS 审计事件。

不负责：

Tenant、Policy、Approval、Task Lifecycle。
向浏览器暴露公网控制接口。

候选实现：

active-runtime/app/aios_openclaw/contract.py
active-runtime/app/aios_openclaw/adapter.py
active-runtime/app/aios_openclaw/transport.py
active-runtime/app/aios_openclaw/health.py
active-runtime/app/aios_openclaw/callback.py

3.5 Hermes Runtime Boundary

职责：

Tenant/Cell/Profile 分区队列。
Worker claim、start、heartbeat、complete、fail、cancel。
Lease 超时和自动回队列。
Result 回传和 Runtime Health。

不负责：

Policy、Approval、Tenant Registry、权威 Task Lifecycle。

候选实现：

active-runtime/app/aios_hermes/contract.py
active-runtime/app/aios_hermes/adapter.py
active-runtime/app/aios_hermes/worker.py

3.6 Persistence

候选实现使用 SQLite WAL 原子快照，持久化：

Tenant
Agent
Task
Audit
Idempotency
Execution Evidence 文件

生产演进：

Store 接口保持稳定。
可替换为 PostgreSQL、对象存储或分布式事件存储。
生产替换必须提供迁移、备份、恢复、HA、容量和租户隔离证据。

4. 多租户架构

4.1 权威租户上下文

每次请求和执行至少传播：

tenant_id
principal_id
session_id
trace_id
task_id
policy_version

Runtime 还传播：

command_id / job_id
cell_id
profile_id
idempotency_key
worker_id

4.2 隔离层级

层级	隔离要求
HTTP/API	可信身份头、租户不可由浏览器覆盖
Control Plane	所有资源带 `tenant_id`，跨租户默认拒绝
OpenClaw	签名命令绑定 tenant/task/trace
Hermes	tenant/cell/profile 三层分区
Storage	候选为显式租户字段；生产需 RLS 或物理隔离策略
Evidence/Audit	仅按当前租户查询
Cache/Memory	key 必须包含 tenant namespace
Secret	只保存引用，不保存明文
Logs/Metrics	必须包含 tenant/task/trace 标签，并限制查询范围

4.3 失败行为

跨租户资源访问返回拒绝或“未找到”。
不泄露其他租户资源存在性。
缺少 tenant context 时 fail closed。
Runtime 返回的 tenant/task/trace 不匹配时拒绝回写。

5. 任务与执行数据流

5.1 任务创建与审批

User/API
   |
   v
Trusted Identity
   |
   v
AIOS Gateway
   |
   v
Policy Gate
   |
   v
Task CREATED
   |
   v
Approval
   |
   v
Task APPROVED

5.2 OpenClaw 执行

APPROVED Task
   |
   v
Execution Orchestrator
   |
   v
Signed OpenClawCommand
   |
   v
OpenClaw Adapter
   |
   v
Runtime Result
   |
   v
Task Reconciliation + Audit + Evidence

5.3 Hermes 执行

APPROVED Task
   |
   v
Execution Orchestrator
   |
   v
Tenant/Cell/Profile HermesJob
   |
   v
Worker Claim + Lease + Heartbeat
   |
   v
HermesResult
   |
   v
Task Reconciliation + Audit + Evidence

6. 安全架构

6.1 身份边界

Public API 位于可信反向代理之后。
反向代理完成登录、会话、MFA 和身份头注入。
候选应用拒绝未认证身份断言。
生产不得允许客户端直接伪造 X-AIOS-*。

6.2 Runtime 命令完整性

OpenClawCommand 使用规范化序列化和 HMAC-SHA256：

签名覆盖 tenant、task、trace、action、payload、idempotency 和时间。
支持 key ID、到期时间和时钟偏差。
Runtime 密钥通过受保护文件或外部 Secret Provider 解析。

6.3 Secret 边界

Git 允许：

secret_ref
credential_ref
key_id
受保护文件路径

Git 禁止：

API Key
密码
Token
私钥
签名材料

6.4 Web 安全

候选应用设置：

no-store
nosniff
DENY frame
no-referrer
CSP
请求体大小限制

生产还需验证：

CSRF/CORS
Rate Limit
Session Timeout
CSP Nonce/Hash
WAF 和反向代理访问策略

7. 可靠性架构

7.1 幂等

Control Plane：tenant_id + idempotency_key + request_digest。
OpenClaw：tenant_id + idempotency_key + signature。
Hermes：tenant_id + idempotency_key + job_digest。

7.2 并发

Task 使用 revision。
Hermes 使用 revision + worker lease。
GitOps 使用 detached controller + branch lease。
持久化使用 SQLite BEGIN IMMEDIATE 和原子快照。

7.3 恢复

Controller restart：detached guard。
AIOS restart：SQLite restore。
Worker crash：lease 到期后 Job 回到 QUEUED。
Release failure：健康检查失败自动恢复 previous release。

8. 可观测架构

统一关联键：

tenant_id
principal_id
trace_id
task_id
agent_id
command_id / job_id
worker_id
commit

Web Console 展示：

Tasks
Agents
Runtime Health
Audit
Execution Evidence
GitOps Status

生产还需接入：

结构化日志
Metrics
Distributed Tracing
Alerting
SLO Dashboard

9. 部署架构

支持两种候选部署：

systemd

非 root aios 用户。
ProtectSystem=strict、NoNewPrivileges 等安全选项。
状态目录 /var/lib/aios-v2。

Docker/Compose

非 root UID/GID。
Read-only root filesystem。
Drop all capabilities。
State volume。
HTTP healthcheck。

10. 架构约束

以下行为视为架构违规：

OpenClaw/Hermes 直接创建或批准 AIOS Task。
Web Console 直接调用 Runtime。
新模块不携带 tenant_id。
新增第二套任务状态机或租户事实源。
在 Git 中提交明文凭据。
绕过 GitOps 修改生产代码/配置。
架构或功能变化未同步更新 docs/aios-v2/。
未通过测试和预发布门禁直接提升候选版本。

11. 目标架构完成判定

目标架构只有在以下证据齐全时才视为完成：

文档与代码映射完整。
Candidate tests 对精确 commit 执行通过。
OpenClaw/Hermes 实际 Runtime 联调通过。
多租户负向测试通过。
重启恢复和回滚演练通过。
GitOps 本地/Gitea OID 一致。
Owner 批准 merge、Tag 和生产部署。

10 KiB Raw Blame History Unescape Escape

AIOS V2 目标架构

1. 架构目标

2. 从现有架构到目标架构

2.1 现有能力

2.2 现有问题

2.3 演进原则

3. 逻辑分层

3.1 Web 与 API 层

3.2 AIOS Control Plane

3.3 Execution Orchestrator / Agent Router

3.4 OpenClaw Adapter

3.5 Hermes Runtime Boundary

3.6 Persistence

4. 多租户架构

4.1 权威租户上下文

4.2 隔离层级

4.3 失败行为

5. 任务与执行数据流

5.1 任务创建与审批

5.2 OpenClaw 执行

5.3 Hermes 执行

6. 安全架构

6.1 身份边界

6.2 Runtime 命令完整性

6.3 Secret 边界

6.4 Web 安全

7. 可靠性架构

7.1 幂等

7.2 并发

7.3 恢复

8. 可观测架构

9. 部署架构

systemd

Docker/Compose

10. 架构约束

11. 目标架构完成判定

10 KiB

Raw Blame History