503 lines
8.3 KiB
Markdown
503 lines
8.3 KiB
Markdown
# 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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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 状态机
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
allowed
|
||
reason
|
||
policy_version
|
||
```
|
||
|
||
约束：
|
||
|
||
- Policy 默认拒绝。
|
||
- Runtime 不得覆盖 PolicyDecision。
|
||
- 拒绝必须审计。
|
||
- 高风险动作必须经过 Approval。
|
||
|
||
## 6. Audit Contract
|
||
|
||
### 6.1 AuditEvent
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
command_id
|
||
tenant_id
|
||
task_id
|
||
trace_id
|
||
state
|
||
output
|
||
error
|
||
started_at
|
||
finished_at
|
||
runtime_id
|
||
attempts
|
||
```
|
||
|
||
状态：
|
||
|
||
```text
|
||
ACCEPTED
|
||
RUNNING
|
||
COMPLETED
|
||
FAILED
|
||
CANCELLED
|
||
TIMED_OUT
|
||
REJECTED
|
||
```
|
||
|
||
约束：
|
||
|
||
- Adapter 对外只接受终态结果用于 reconcile。
|
||
- 身份字段不匹配时拒绝回写。
|
||
- 结果通过 Orchestrator 更新 AIOS Task。
|
||
|
||
### 7.3 RuntimeHealth
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
状态机：
|
||
|
||
```text
|
||
QUEUED -> CLAIMED -> RUNNING -> COMPLETED
|
||
| | |
|
||
+---------+----------+-> CANCELLED
|
||
+-> FAILED
|
||
```
|
||
|
||
约束：
|
||
|
||
- `tenant_id + cell_id + profile_id` 形成执行分区。
|
||
- claim 只能领取同分区 Job。
|
||
- Worker ID 不得跨分区复用。
|
||
- Lease 到期 Job 回到 QUEUED。
|
||
- revision 冲突不得覆盖。
|
||
|
||
### 8.2 HermesResult
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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
|
||
```
|
||
|
||
状态建议：
|
||
|
||
```text
|
||
claimed
|
||
running
|
||
blocked
|
||
complete
|
||
failed
|
||
cancelled
|
||
```
|
||
|
||
约束：
|
||
|
||
- 按租户存储和查询。
|
||
- 每个阻塞必须记录原因、责任方和解除条件。
|
||
- 每次结果必须记录 branch、commit、测试命令和状态。
|
||
- 不得包含 Secret 或完整敏感 payload。
|
||
|
||
## 10. GitOps Status Contract
|
||
|
||
```text
|
||
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 身份头
|
||
|
||
可信代理注入：
|
||
|
||
```text
|
||
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
|
||
|
||
```text
|
||
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 和版本号，不得静默修改。
|