aios/aios

Fork 0

Files

T

Codex 7de1fe80ac docs(hermes): retain key-id and rollback contracts

2026-07-21 13:19:21 +08:00

15 KiB

Raw Blame History

AIOS V2 模块契约

文档版本：V2R1-hardening-candidate
状态：加固候选契约基线
原则：Control Plane 权威、Runtime 仅执行、默认拒绝、服务级最小权限、全链路租户隔离、所有权威状态可审计和恢复

核心模型名称与实现保持逐字同步：RequestContext 承载可信租户、主体、角色、trace、 session 与 policy version；TaskState 是 AIOS 权威 Task 生命周期枚举，Runtime Worker 不得直接写入或复制该状态机。

1. 通用可信上下文契约

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

字段	必填	说明
`tenant_id`	是	权威租户标识
`principal_id`	控制和 Reconcile 是	已认证主体
`trace_id`	是	全链路追踪
`task_id`	执行阶段是	AIOS 权威任务
`agent_id`	执行和 Provenance 是	任务绑定 Agent
`provenance_id`	生产副作用操作是	父 Workflow Provenance
`run_id`	生产副作用操作是	本次执行 Run
`dispatch_id`	Runtime Result 是	持久化 Dispatch 记录
`policy_version`	控制请求是	策略版本
`idempotency_key`	创建/执行是	幂等键

规则：

缺少必填字段时 fail closed。
客户端不得覆盖可信代理或 AIOS 生成的租户、身份和追踪字段。
Runtime 返回的 tenant/task/trace/runtime execution 必须与持久 Dispatch 完全匹配。
Runtime Result 还必须匹配 Principal、Parent Provenance 和 Run。
所有持久化键、缓存键、队列分区、Receipt 和 Evidence 路径必须包含租户命名空间。

2. Tenant Contract

2.1 TenantRecord

tenant_id
display_name
status
metadata
created_at
updated_at

约束：

tenant_id 不可为空且不可变。
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 仅保存非敏感引用，不得保存明文凭据。

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	Control Plane Approval/Cancel
APPROVED	RUNNING, CANCELLED	Orchestrator Dispatch / Control Plane Cancel
RUNNING	COMPLETED, FAILED, CANCELLED	Orchestrator Reconcile / Control Plane Cancel
COMPLETED	无	终态
FAILED	无	终态
CANCELLED	无	终态

约束：

每次转换必须校验 revision。
COMPLETED 必须带 result；FAILED 必须带 error。
每次转换生成 AuditEvent。
Runtime 不得直接写 Task Store。
公共 API 不得直接把任务推进到 RUNNING、COMPLETED 或 FAILED。

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 不得包含明文凭据、私钥或完整敏感 Payload。
Runtime callback 可以生成非权威审计事件，但不得单独触发 Task 状态变化。
Task 状态变化必须经过 Orchestrator 严格 Reconcile。
生产版需增加不可变外部固化和完整性验证。

7. Workflow Provenance Contract

7.1 RunProvenance

父 Workflow Provenance 只绑定身份与 Run，不授予操作权限：

provenance_id
run_id
issuer
tenant_id
task_id
agent_id
principal_id
allowed_paths = []
allowed_git_operations = []
issued_at
expires_at
policy_version
key_id
nonce
signature
schema_version

约束：

使用 Ed25519 签名。
allowed_paths 和 allowed_git_operations 必须为空。
撤销或过期父 Workflow 后，全部子 Grant 自动失效。
私钥只存在签发端，生产应用只读取公钥。

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

8. Provenance Grant Contract

8.1 ProvenanceGrant

grant_id
parent_provenance_id
grant_type
execution_path
run_id
issuer
tenant_id
task_id
agent_id
principal_id
allowed_git_operations
issued_at
expires_at
policy_version
key_id
nonce
signature
schema_version

Grant 类型与唯一允许路径：

GrantType	ExecutionPath
`code_change`	`code_change`
`git`	`git_operation`
`deployment`	`deployment`
`runtime`	`runtime_execute`
`evidence`	`evidence_write`
`rollback`	`rollback`
`audit`	`audit`

约束：

一个 Grant 只允许一个路径。
Git Grant 必须显式声明具体 GitOperation；非 Git Grant 不得包含 Git 操作。
子 Grant 身份字段必须与父 Workflow 完全一致。
子 Grant TTL 不得超过父 Workflow。
(grant_id, path, git_operation, request_digest) 重复使用时拒绝。
Grant 支持独立 issued/verified/used/expired/revoked 生命周期。

实现：

active-runtime/app/aios_v2/provenance_grants.py
active-runtime/app/aios_v2/provenance_scoped.py

9. Service Scoped Writer Contract

生产进程只加载职责所需 Grant：

AIOS Application：runtime_execute、evidence_write、audit。
Git Worker：git_operation，代码提交场景另需独立 code_change Grant。
Deployment Worker：deployment。
Rollback Worker：rollback。
CLI 单次授权：一个 --path + 一个 --grant-id。

约束：

空 Scope 拒绝。
多余 Grant 映射拒绝。
未配置路径的方法调用拒绝。
Receipt 必须记录 grant_id、writer_id 和服务 Scope。

10. Dispatch Contract

10.1 DispatchRecord

dispatch_id
tenant_id
task_id
agent_id
principal_id
runtime
runtime_execution_id
trace_id
provenance_id
run_id
authorization_id
state
expected_worker_id
result_digest
created_at
updated_at
completed_at

状态：

PREPARED
RUNNING
QUEUED
COMPLETED
FAILED
CANCELLED

约束：

Dispatch 必须在 Runtime 副作用之前持久化。
同一租户的 Task 和 Runtime Execution 各只能绑定一个 Dispatch。
终态 Dispatch 不得跳转到不同终态。
相同终态结果允许幂等读取，不同结果摘要拒绝。
SQLite Repository 必须支持按 Task 和 Runtime Execution 恢复。

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

11. OpenClaw Contract

11.1 OpenClawCommand v2

contract_version = aios.openclaw.command.v2
signature_algorithm = Ed25519
command_id
tenant_id
task_id
trace_id
action
payload
idempotency_key
created_at
expires_at
key_id
public_key_fingerprint
signature

签名覆盖全部未签名字段，包括算法、Key ID 和公钥 Fingerprint。

约束：

使用规范化 JSON 与 Ed25519。
HMAC-SHA256 不再是生产命令合同。
只接受由已批准任务和已授权 Dispatch 生成的命令。
过期、未来时间超差、签名错误、Key ID 或 Fingerprint 不匹配时拒绝。
Fingerprint 使用恒定时间比较。
key_id 只引用密钥，不包含密钥材料。
Candidate 组合层必须把 AIOS_OPENCLAW_SIGNING_KEY_ID 原样传入 Orchestrator，不得在已有批准 Key ID 时回落为默认值。

11.2 OpenClawResult

command_id
tenant_id
task_id
trace_id
state
output
error
started_at
finished_at
runtime_id
attempts

终态：COMPLETED、FAILED、CANCELLED、TIMED_OUT、REJECTED。

约束：

Result 必须匹配持久 Dispatch 的 command、tenant、task、trace、principal、provenance 和 run。
只有 Orchestrator 可以更新 AIOS Task。
callback 审计不是权威 Reconcile。

实现：active-runtime/app/aios_openclaw/

12. Hermes Contract

12.0 内部生命周期入口

路径：/api/v2/internal/runtime/hermes/lifecycle/{claim,start,heartbeat,complete,fail,cancel,status}。
AIOS_HERMES_LIFECYCLE_API_ENABLED 默认关闭；关闭时按不存在的路由 fail closed。
仅可信反向代理注入且具备 runtime 或 platform_admin 角色的身份可调用。
所有写请求必须携带并严格匹配 tenant、task、trace、principal、provenance、run、 dispatch、job、cell、profile；Claim 还必须指定精确 job，不能从分区中误领其他 Job。
Worker 不得直接修改 Task Store。Complete、Fail 和 Cancel 产生的 HermesResult 必须经持久 Dispatch 校验并由 ExecutionOrchestrator.reconcile_hermes 终态化。
每次成功生命周期写入同时落盘 Hermes 状态、Audit/Event 和 Execution Evidence。

12.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

约束：

tenant_id + cell_id + profile_id 形成执行分区。
claim 只能领取同分区 Job。
Lease 到期 Job 回到 QUEUED。
Hermes Store 使用 AIOS_V2_STATE_DIR/hermes.sqlite3 保存 Job、Result、Lease、 Idempotency 和 Worker heartbeat；Adapter 仍是唯一 Queue/Lease 状态机。
Lease 到期重排必须清空 assigned_worker_id、清空 lease_expires_at、递增 revision 并持久化。重启后由显式 lifecycle status/claim 或健康检查安全触发重排。
revision 冲突不得覆盖。

12.2 HermesResult

job_id
tenant_id
task_id
trace_id
state
worker_id
output
error
started_at
finished_at

约束：

终态 Result 必须携带 Worker ID。
Worker 必须持有 Job Lease。
Result 必须匹配 Dispatch、Principal、Parent Provenance 和 Run。
相同 Worker、相同终态和相同 output/error 的重复提交返回原 Result；不同终态或不同结果内容返回 Conflict，不得覆盖已持久化终态。
只允许内部入口 POST /api/v2/internal/runtime/hermes/reconcile 处理。
旧入口 POST /api/v2/hermes/results/reconcile 返回 410 Gone。

实现：active-runtime/app/aios_hermes/

13. Execution Evidence Contract

13.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
provenance_id
run_id
last_authorization_id

约束：

按租户存储和查询。
生产 claim/heartbeat/complete 落盘前必须通过 Evidence Grant。
Evidence ID 不得被不同 Task、Agent 或 Provenance Context 复用。
不得包含 Secret 或完整敏感 Payload。

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

14. Git Writer Contract

允许操作：READ_REF、FETCH、CREATE_BRANCH、COMMIT、MERGE、PUSH、UPDATE_EVIDENCE，具体能力由 Git Grant 限定。

约束：

禁止直接操作 main 或 master。
所有命令使用参数数组，禁止 Shell 字符串拼接。
Commit 和 Evidence Commit 必须先计算文件内容摘要并完成 Grant 授权，再执行 git add。
UPDATE_EVIDENCE 只允许 .agent/ 路径。
输出必须脱敏并截断。

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

15. Web/API Contract

15.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
X-AIOS-Provenance-ID
X-AIOS-Run-ID

生产约束：

可信代理必须删除客户端同名头后重新注入。
应用不得直接暴露公网端口。
Header 与 Body 中重复的 Provenance/Run 值必须一致。

15.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}/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/internal/runtime/hermes/reconcile

公共生命周期旁路：

POST /api/v2/tasks/{id}/start    -> 403
POST /api/v2/tasks/{id}/complete -> 403
POST /api/v2/tasks/{id}/fail     -> 403

16. Persistence Contract

候选版：

Control Plane：SQLite Snapshot。
Dispatch：独立 SQLite Repository。
Provenance/Grant/Usage/Event：SQLite WAL。
Evidence/Receipt：租户隔离原子文件写入。
写事务使用原子替换或 BEGIN IMMEDIATE。

生产替换要求：

不改变 Domain/API Contract。
提供 migration、backup、restore、HA、隔离和容量测试。
恢复时保留已使用 Grant 与终态 Dispatch，禁止旧授权重放。

17. Deployment Contract

systemd

非 root aios 用户。
状态目录 /var/lib/aios-v2。
私钥通过受保护 credential 注入，不写入 Git 或普通环境文件。
私钥文件必须是 regular file、禁止 symlink、权限 0600 或更严格。

Docker

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

Rollback

回滚前备份状态。
默认只回滚代码。
状态恢复需独立 Rollback Grant 和显式批准。
回滚后必须执行 Healthcheck 与恢复验证。
Release Archive 必须保留 rollback.sh 与 healthcheck/check.sh 的 executable bit；验收测试必须阻止非执行模式进入候选包。
systemctl start 后的回滚健康检查必须执行有界 readiness 重试，默认最多 30 次、每次间隔 1 秒；不得因服务尚未监听的一次瞬时拒绝误判目标 Release 失败。

18. 契约变更规则

以下变化必须在同一分支更新本文档、追踪矩阵和相关 ADR：

字段、状态、Header、API、错误语义；
租户、安全和 Provenance 约束；
OpenClaw/Hermes 边界；
Dispatch、Persistence、Deployment、Rollback Contract；
Evidence、Audit、Receipt 格式；
服务 Scope 或 Grant 类型。

不兼容变化必须新增 ADR 和版本号，不得静默修改。正式 Gate A 结论必须基于实际执行 Acceptance 和保存的证据，不得仅凭测试文件存在宣布通过。

15 KiB Raw Blame History Unescape Escape