aios/aios

Fork 0

Files

T

Codex 4e8ab051a0 docs(aios-v2): add module contracts

2026-07-20 11:41:39 +08:00

8.3 KiB

Raw Blame History

AIOS V2 模块契约

文档版本：V2R1C0-candidate
状态：候选实现契约基线
原则：Control Plane 权威、Runtime 执行、全链路租户隔离、所有状态可审计

1. 通用上下文契约

所有控制与执行请求必须携带以下上下文：

字段	必填	说明
`tenant_id`	是	权威租户标识
`principal_id`	控制请求是	已认证主体
`trace_id`	是	全链路追踪
`task_id`	执行阶段是	AIOS 权威任务
`session_id`	Web/交互请求建议	用户会话
`policy_version`	控制请求是	策略版本
`idempotency_key`	创建/执行是	幂等键

规则：

缺少必填字段时 fail closed。
客户端不得覆盖由可信代理或 AIOS 生成的 tenant_id。
Runtime 返回的 tenant/task/trace 必须与请求完全匹配。
所有持久化键、缓存键和队列分区必须包含租户命名空间。

2. Tenant Contract

2.1 TenantRecord

tenant_id
display_name
status
metadata
created_at
updated_at

约束：

tenant_id 不可为空且不可变。
status 至少支持 active 和受控停用状态。
Tenant 只由 AIOS Control Plane 创建和维护。
Runtime 不得创建租户。

实现：active-runtime/app/aios_v2/control_plane.py

3. Agent Contract

3.1 AgentRecord

agent_id
tenant_id
display_name
runtime
capabilities
enabled
metadata
created_at
updated_at

约束：

Agent 属于唯一租户。
runtime 由 Registry 决定，可取 openclaw、hermes 或后续注册 Runtime。
capabilities 是允许调度的动作集合。
metadata 可存 cell_id、profile_id、priority 等非敏感引用。
不得在 Agent metadata 中保存明文凭据。

4. Task Contract

4.1 TaskRecord

task_id
tenant_id
agent_id
action
payload
state
revision
idempotency_key
request_digest
result
error
created_by
approved_by
created_at
updated_at

4.2 状态机

CREATED -> APPROVED -> RUNNING -> COMPLETED
    |          |          |
    +----------+----------+-> CANCELLED
                           +-> FAILED

允许转换：

当前	允许目标
CREATED	APPROVED, CANCELLED
APPROVED	RUNNING, CANCELLED
RUNNING	COMPLETED, FAILED, CANCELLED
COMPLETED	无
FAILED	无
CANCELLED	无

约束：

每次转换必须校验 revision。
COMPLETED 必须带 result。
FAILED 必须带 error。
每次转换生成 AuditEvent。
Runtime 不得直接写 Task Store，只能通过 Orchestrator reconcile。

5. Policy Contract

5.1 PolicyDecision

allowed
reason
policy_version

约束：

Policy 默认拒绝。
Runtime 不得覆盖 PolicyDecision。
拒绝必须审计。
高风险动作必须经过 Approval。

6. Audit Contract

6.1 AuditEvent

event_id
tenant_id
principal_id
trace_id
action
resource_type
resource_id
outcome
policy_version
details
created_at

约束：

按租户查询。
details 不得包含明文凭据。
OpenClaw/Hermes 生命周期事件必须映射到统一 AuditEvent。
生产版需增加不可变外部固化和完整性验证。

7. OpenClaw Contract

7.1 OpenClawCommand

contract_version
command_id
tenant_id
task_id
trace_id
action
payload
idempotency_key
created_at
expires_at
key_id
signature

签名覆盖：

command_id
tenant_id
task_id
trace_id
action
payload
idempotency_key
created_at / expires_at
contract_version / key_id

约束：

使用规范化 JSON 和 HMAC-SHA256。
只接受已批准任务生成的命令。
过期、未来时间超差、签名错误命令必须拒绝。
key_id 只引用运行时材料，不包含材料本身。

7.2 OpenClawResult

command_id
tenant_id
task_id
trace_id
state
output
error
started_at
finished_at
runtime_id
attempts

状态：

ACCEPTED
RUNNING
COMPLETED
FAILED
CANCELLED
TIMED_OUT
REJECTED

约束：

Adapter 对外只接受终态结果用于 reconcile。
身份字段不匹配时拒绝回写。
结果通过 Orchestrator 更新 AIOS Task。

7.3 RuntimeHealth

runtime
runtime_id
status
version
heartbeat_at
active_tasks
workspace_isolated
credential_ref_configured
details

健康策略：

heartbeat 不得超时。
workspace isolation 与 credential reference 必须符合策略。
不安全 Runtime 应 quarantine，不得继续接收新任务。

实现：active-runtime/app/aios_openclaw/

8. Hermes Contract

8.1 HermesJob

job_id
tenant_id
cell_id
profile_id
task_id
trace_id
action
payload
idempotency_key
priority
state
revision
assigned_worker_id
lease_expires_at
created_at
updated_at

状态机：

QUEUED -> CLAIMED -> RUNNING -> COMPLETED
   |         |          |
   +---------+----------+-> CANCELLED
                        +-> FAILED

约束：

tenant_id + cell_id + profile_id 形成执行分区。
claim 只能领取同分区 Job。
Worker ID 不得跨分区复用。
Lease 到期 Job 回到 QUEUED。
revision 冲突不得覆盖。

8.2 HermesResult

job_id
tenant_id
task_id
trace_id
state
worker_id
output
error
started_at
finished_at

约束：

COMPLETED 必须有 output。
FAILED 必须有 error。
只允许 AIOS Orchestrator reconcile。

8.3 HermesHealth

runtime_id
status
version
heartbeat_at
active_workers
active_jobs
queued_jobs
tenant_partitions
profile_isolation_enforced
details

实现：active-runtime/app/aios_hermes/

9. Execution Evidence Contract

9.1 ExecutionEvidence

execution_id
tenant_id
task_id
agent_id
executor
branch
status
progress_completed
progress_total
current_step
last_commit
test_status
test_summary
result_summary
claimed_at
heartbeat_at
completed_at

状态建议：

claimed
running
blocked
complete
failed
cancelled

约束：

按租户存储和查询。
每个阻塞必须记录原因、责任方和解除条件。
每次结果必须记录 branch、commit、测试命令和状态。
不得包含 Secret 或完整敏感 payload。

10. GitOps Status Contract

available
service_status
workspace_mode
workspace_branch
workspace_ref
workspace_dirty
candidate_branch
release_channel
release_version
sync_status
details

约束：

Web 响应不得包含 remote URL、凭据或 stderr。
Controller 必须 detached + clean。
sync_status 必须区分 local 和 Gitea 镜像状态。

11. Web/API Contract

11.1 身份头

可信代理注入：

X-AIOS-Authenticated
X-AIOS-Tenant-ID
X-AIOS-Principal-ID
X-AIOS-Roles
X-AIOS-Trace-ID
X-AIOS-Session-ID
X-AIOS-Policy-Version

生产约束：

代理必须删除客户端同名头后重新注入。
应用不得直接暴露公网端口。

11.2 核心 API

GET  /api/v2/health
POST /api/v2/tenants
GET  /api/v2/tenants/current
POST /api/v2/agents
GET  /api/v2/agents
POST /api/v2/tasks
GET  /api/v2/tasks
GET  /api/v2/tasks/{id}
POST /api/v2/tasks/{id}/approve
POST /api/v2/tasks/{id}/start
POST /api/v2/tasks/{id}/complete
POST /api/v2/tasks/{id}/fail
POST /api/v2/tasks/{id}/cancel
POST /api/v2/tasks/{id}/dispatch
GET  /api/v2/audit
GET  /api/v2/runtime
GET  /api/v2/executions
GET  /api/v2/gitops
POST /api/v2/hermes/results/reconcile

12. Persistence Contract

候选版：

SQLite WAL
BEGIN IMMEDIATE
原子 snapshot
schema version
restart restore

持久化范围：

tenants
agents
tasks
audit
idempotency

生产替换要求：

不改变 Domain/API Contract。
提供 migration、backup、restore、HA、RLS/隔离和容量测试。

13. Deployment Contract

systemd

非 root aios 用户。
状态目录 /var/lib/aios-v2。
最小权限和文件系统保护。

Docker

非 root UID/GID。
read-only root filesystem。
drop all capabilities。
独立状态 volume。

Rollback

回滚前备份状态。
默认只回滚代码。
状态恢复需显式授权。
回滚后必须执行 healthcheck。

14. 契约变更规则

任何以下变化必须在同一提交或同一分支更新本文档：

字段、状态、Header、API、错误语义；
租户或安全约束；
OpenClaw/Hermes 边界；
Persistence 或 Deployment Contract；
Evidence/Audit 格式。

不兼容变化必须新增 ADR 和版本号，不得静默修改。

8.3 KiB Raw Blame History Unescape Escape