343 lines
13 KiB
Markdown
343 lines
13 KiB
Markdown
# AIOS V2 用户需求规格
|
|
|
|
- 文档版本：`V2R1-hardening-candidate`
|
|
- 状态：加固候选版本需求基线
|
|
- 适用范围：AIOS Control Plane、Agent Router、OpenClaw Adapter、Hermes Runtime、Web Console、GitOps、Run Provenance、Dispatch、审计、部署与回滚
|
|
|
|
## 1. 背景与目标
|
|
|
|
现有系统已经具备 OpenClaw、Hermes、Agent Router、GitOps、局部 WebUI、审计和多租户候选能力。AIOS V2 的目标不是推倒重写，而是将这些分散能力收敛到统一、可审计、可 Web 化、可多租户隔离的控制面。
|
|
|
|
AIOS V2 必须成为唯一控制面，负责租户、身份、Agent、策略、任务生命周期、审批、审计、Runtime 目录、执行证据、Run Provenance 和 Dispatch。OpenClaw 与 Hermes 只承担执行职责，不得持有第二套控制面状态。
|
|
|
|
## 2. 用户角色
|
|
|
|
| 角色 | 主要诉求 |
|
|
|---|---|
|
|
| 平台管理员 | 管理租户、运行时、发布、GitOps 状态和全局策略 |
|
|
| 租户管理员 | 管理本租户 Agent、任务、审批、审计和成员权限 |
|
|
| 操作员 | 创建任务、发起执行、取消任务、查看运行状态 |
|
|
| 审批人 | 审批高风险任务，查看策略判定依据 |
|
|
| 审计员 | 查询本租户完整审计链和执行证据 |
|
|
| Runtime Worker | 领取已批准任务、心跳、返回执行结果 |
|
|
| 开发与运维人员 | 通过 GitOps 提交、测试、部署、回滚和修复 Bug |
|
|
|
|
## 3. 核心用户需求
|
|
|
|
### UR-001 唯一控制面
|
|
|
|
所有任务创建、审批、取消、状态变化、策略判定和审计必须由 AIOS Control Plane 统一处理。
|
|
|
|
验收：
|
|
|
|
- Web Console、API、Codex、OpenClaw 和 Hermes 均不得绕过 AIOS 创建或修改任务生命周期。
|
|
- OpenClaw/Hermes 的公开接口仅限执行、状态、取消、心跳和结果回传。
|
|
|
|
### UR-002 复用现有能力
|
|
|
|
系统不得重写已经稳定的 OpenClaw 执行能力、Hermes Runtime、Agent Router 或 GitOps 基础设施。
|
|
|
|
验收：
|
|
|
|
- 通过 Adapter/Boundary 接入现有能力。
|
|
- 替换控制逻辑时保留原执行接口和可迁移数据。
|
|
|
|
### UR-003 OpenClaw 与 Hermes 解耦
|
|
|
|
OpenClaw 与 Hermes 必须从策略、租户、审批和任务生命周期中逐步解耦。
|
|
|
|
验收：
|
|
|
|
- OpenClaw 仅接收已签名、已批准、带租户上下文的命令。
|
|
- Hermes 仅接收已批准的租户分区 Job。
|
|
- 二者均不得直接写 Control Plane 权威状态。
|
|
|
|
### UR-004 全面 Web 化
|
|
|
|
所有面向用户和运维的能力必须通过 Web Console 或稳定 API 访问。
|
|
|
|
Web Console 至少展示：
|
|
|
|
- Tenant、Agent、Task、Approval、Runtime、Audit、Execution Evidence、GitOps Status。
|
|
- 所有写操作由 AIOS API 完成，浏览器不得直接调用 OpenClaw/Hermes。
|
|
|
|
### UR-005 多租户隔离
|
|
|
|
所有模块必须支持租户隔离，且默认拒绝跨租户访问。
|
|
|
|
隔离范围：
|
|
|
|
- API 与会话
|
|
- Tenant/Agent/Task 数据
|
|
- OpenClaw 命令
|
|
- Hermes Queue、Cell、Profile、Worker Lease
|
|
- Memory、Cache、Artifact、SecretRef
|
|
- Audit、Execution Evidence、日志和指标
|
|
|
|
验收：
|
|
|
|
- 资源记录的 `tenant_id` 不可为空。
|
|
- 跨租户访问返回拒绝或“资源不存在”，不得泄露存在性。
|
|
- 必须有跨租户负向测试。
|
|
|
|
### UR-006 权威任务生命周期
|
|
|
|
任务必须遵循统一状态机：
|
|
|
|
```text
|
|
CREATED -> APPROVED -> RUNNING -> COMPLETED
|
|
| | |
|
|
+----------+----------+-> CANCELLED
|
|
+-> FAILED
|
|
```
|
|
|
|
验收：
|
|
|
|
- 禁止越级变化，例如 `CREATED -> COMPLETED`。
|
|
- 每次变化包含 revision、principal、trace、时间和审计事件。
|
|
- 公共 API 不允许直接调用 `start`、`complete` 或 `fail` 推进权威状态。
|
|
|
|
### UR-007 策略与审批
|
|
|
|
所有有副作用任务必须经过策略判定；高风险任务必须支持人工审批。
|
|
|
|
验收：
|
|
|
|
- Policy Decision 包含 allow/deny、reason 和 policy version。
|
|
- 拒绝事件进入审计。
|
|
- Runtime 不得自行放宽策略。
|
|
|
|
### UR-008 幂等与并发安全
|
|
|
|
任务和 Runtime 执行必须支持幂等与乐观并发控制。
|
|
|
|
验收：
|
|
|
|
- 相同租户与幂等键、相同内容返回同一任务/执行。
|
|
- 相同幂等键不同内容返回冲突。
|
|
- revision 或 branch lease 冲突不得静默覆盖。
|
|
|
|
### UR-009 可观测与执行证据
|
|
|
|
平台必须能够确认 Codex、OpenClaw、Hermes 等执行器是否领取任务、当前进度、最近提交、测试结果和完成状态。
|
|
|
|
验收：
|
|
|
|
- 存在 claim、heartbeat、progress、result 和 evidence 记录。
|
|
- Web/API 可按租户查询。
|
|
- 执行证据不得包含明文密钥。
|
|
|
|
### UR-010 GitOps 唯一变更流程
|
|
|
|
所有代码、配置、文档和部署资产修改必须进入非 `main` 分支，通过 commit、测试、审查和受控提升。
|
|
|
|
验收：
|
|
|
|
- Controller worktree 必须 detached 且 clean。
|
|
- 本地 bare repo 与 Gitea 目标分支 OID 一致。
|
|
- 不允许直接 push `main`、直接创建生产 Tag 或绕过审批部署。
|
|
|
|
### UR-011 持久化与恢复
|
|
|
|
租户、Agent、Task、Audit、Idempotency、Dispatch、Run Provenance、Grant 使用记录和 Execution Evidence 必须在服务重启后恢复。
|
|
|
|
验收：
|
|
|
|
- 候选版支持 SQLite WAL 或等价原子持久化。
|
|
- 有 Control Plane 与 Dispatch restart recovery 测试。
|
|
- 生产版需进一步提供迁移、备份、恢复、HA 和容量证据。
|
|
|
|
### UR-012 审计与合规
|
|
|
|
所有控制与执行动作必须生成不可混租户的审计事件。
|
|
|
|
至少记录：
|
|
|
|
- tenant、principal、trace、action、resource、outcome、policy version、timestamp。
|
|
- OpenClaw/Hermes Runtime 生命周期。
|
|
- GitOps、部署和回滚动作。
|
|
- Provenance Grant、Scope、Authorization Receipt 和 Dispatch 结果摘要。
|
|
|
|
### UR-013 密钥安全
|
|
|
|
Git、日志、Web、任务 payload 和审计记录中不得出现明文 API Key、密码、Token 或私钥。
|
|
|
|
验收：
|
|
|
|
- Git 只存 `secret_ref`、`credential_ref`、`key_id` 或受保护文件路径。
|
|
- Secret 文件权限为 `0600` 或更严格。
|
|
- Secret Scanner 默认拒绝可疑提交。
|
|
- OpenClaw Command 和 Run Provenance 使用 Ed25519；生产应用只读取公钥。
|
|
|
|
### UR-014 部署与回滚
|
|
|
|
系统必须提供 systemd、Docker/Compose、健康检查和受保护回滚入口。
|
|
|
|
验收：
|
|
|
|
- 服务以非 root 权限运行。
|
|
- 状态目录独立持久化。
|
|
- 回滚前自动备份状态。
|
|
- 默认只回滚代码，状态恢复需要显式授权。
|
|
|
|
### UR-015 文档与代码同步
|
|
|
|
任何影响用户行为、架构边界、API、数据模型、状态机、安全策略、部署或运维方式的变更，必须在同一分支同步更新 `docs/aios-v2/`。
|
|
|
|
验收：
|
|
|
|
- 架构/功能代码变化但无文档变化时，文档同步门禁失败。
|
|
- Traceability Matrix 必须指向当前代码和测试。
|
|
- 新架构决策必须增加或更新 ADR。
|
|
|
|
### UR-016 Workflow Run Provenance
|
|
|
|
每次生产 Run 必须具有一个可验证、可撤销、可过期的 Workflow Provenance，用于绑定 Run、Tenant、Task、Agent 与 Principal，但父 Workflow 本身不得授予操作权限。
|
|
|
|
验收：
|
|
|
|
- Workflow Provenance 使用 Ed25519 签名。
|
|
- `allowed_paths` 与 `allowed_git_operations` 为空。
|
|
- 上下文、签名、TTL、Nonce、Key ID 不合法时默认拒绝。
|
|
- 撤销父 Workflow 后全部子 Grant 失效。
|
|
|
|
### UR-017 最小权限子 Grant
|
|
|
|
所有生产副作用必须通过与单一 ExecutionPath 对应的子 Grant 授权。
|
|
|
|
验收：
|
|
|
|
- Runtime、Evidence、Git、Deployment、Rollback、Audit 和 Code Change 使用独立 Grant。
|
|
- 一个 Grant 只能包含一个路径。
|
|
- Git Grant 必须限定具体 GitOperation。
|
|
- 子 Grant 具有独立 TTL、撤销、状态和重放防护。
|
|
|
|
### UR-018 Runtime Result 信任绑定
|
|
|
|
OpenClaw/Hermes 结果只有在与持久 Dispatch 的身份和执行上下文完全匹配时，才能更新权威 Task。
|
|
|
|
验收：
|
|
|
|
- 至少校验 tenant、task、agent、principal、trace、runtime、runtime execution、provenance 和 run。
|
|
- 不同终态结果摘要不得覆盖已有终态。
|
|
- Hermes 终态结果必须来自持有 Job Lease 的 Worker。
|
|
- Hermes Worker 生命周期验收入口必须是默认关闭的内部接口，仅接受可信
|
|
`runtime` 或 `platform_admin` 身份；普通 Operator、浏览器和公共 API 不得直接调用。
|
|
- 每次 Claim/Start/Heartbeat/Complete/Fail/Cancel 必须绑定
|
|
tenant、task、trace、principal、provenance、run、dispatch、job、cell 和 profile。
|
|
- Complete/Fail/Cancel 必须通过 `ExecutionOrchestrator.reconcile_hermes` 更新权威
|
|
Task/Dispatch，并同步生成 Audit/Event 与 Execution Evidence。
|
|
- Lease 到期必须持久化清除旧 Owner、递增 revision 并允许安全重领；旧 Worker
|
|
后续 Result 必须拒绝。
|
|
- Runtime callback 审计不得绕过 Orchestrator Reconcile。
|
|
|
|
### UR-019 Dispatch 持久化与恢复
|
|
|
|
Runtime 副作用之前必须持久化唯一 Dispatch，重启后能够恢复并继续严格 Reconcile。
|
|
|
|
验收：
|
|
|
|
- 同租户 Task 和 Runtime Execution 各自唯一绑定一个 Dispatch。
|
|
- Dispatch 支持按 ID、Task 与 Runtime Execution 查询。
|
|
- 终态 Dispatch 不得迁移到不同终态。
|
|
- Hermes Job、Result、Lease、幂等键和 Worker heartbeat 必须与 Dispatch 一样在
|
|
服务重启后恢复；不得以只存在于进程内的 Map 作为在线验收依据。
|
|
- 有 SQLite Repository 重启恢复测试。
|
|
|
|
### UR-020 OpenClaw Ed25519 命令合同
|
|
|
|
OpenClaw 生产命令必须使用版本化 Ed25519 合同，不得继续使用 HMAC 作为新命令信任根。
|
|
|
|
验收：
|
|
|
|
- 合同版本为 `aios.openclaw.command.v2`。
|
|
- 签名覆盖 Key ID、算法、公钥 Fingerprint、Tenant、Task、Trace、Payload、Idempotency 与时间字段。
|
|
- Key ID/Fingerprint/签名/过期或时钟偏差不合法时拒绝。
|
|
- Fingerprint 使用恒定时间比较。
|
|
|
|
### UR-021 服务级权限隔离
|
|
|
|
每个生产服务或 Worker 只能加载其职责所需的 Grant，不得加载全部 Grant 备用。
|
|
|
|
验收：
|
|
|
|
- 默认 AIOS Application 仅加载 Runtime、Evidence 与 Audit Grant。
|
|
- Git、Deployment、Rollback 与 Code Change 由独立 Scope 加载。
|
|
- 空 Scope、多余 Grant 映射和未声明路径调用全部拒绝。
|
|
- Authorization Receipt 记录 Grant ID、Writer ID 和 Scope。
|
|
|
|
### UR-022 CLI 单 Grant 授权
|
|
|
|
运维 CLI 的一次授权操作只能加载一个与请求路径一致的 Grant。
|
|
|
|
验收：
|
|
|
|
- `authorize` 使用一个 `--path` 和一个 `--grant-id`。
|
|
- Grant 类型与 Path 不一致时拒绝。
|
|
- CLI 不提供一次加载七个生产 Grant 的授权入口。
|
|
- 旧全权限 `issue` 仅允许候选兼容，不得进入生产流程。
|
|
|
|
## 4. 非功能需求
|
|
|
|
### NFR-001 安全
|
|
|
|
- 默认拒绝、最小权限、租户隔离、身份可信链、SecretRef、审计、可撤销 Provenance 和 Runtime 结果绑定。
|
|
|
|
### NFR-002 可靠性
|
|
|
|
- 幂等、revision、worker lease、heartbeat、重试边界、原子持久化、Dispatch 恢复、健康检查和回滚。
|
|
|
|
### NFR-003 可维护性
|
|
|
|
- 模块边界稳定，Control Plane 与 Runtime 解耦；代码、文档、测试和部署可追踪。
|
|
|
|
### NFR-004 可扩展性
|
|
|
|
- Store、Transport、Policy、EventPublisher、Runtime Adapter、Provenance Verifier 与 Writer 均通过接口扩展。
|
|
|
|
### NFR-005 可运维性
|
|
|
|
- Web/API 状态、systemd/Docker、健康检查、日志、GitOps 状态、候选报告、Grant 状态和 Receipt。
|
|
|
|
### NFR-006 性能候选指标
|
|
|
|
候选版上线前至少验证：
|
|
|
|
- API P95、任务调度延迟、队列等待、Worker 心跳、SQLite 锁等待、审计写入时间、Grant 授权延迟和 Dispatch 恢复时间。
|
|
- 具体 SLO 在预发布基准测试后固化，禁止无证据承诺。
|
|
|
|
## 5. 本候选版本范围
|
|
|
|
### 已纳入代码
|
|
|
|
- Control Plane、持久化、Gateway、Orchestrator、OpenClaw Adapter、Hermes Boundary、Execution Tracking、Web Console、GitOps Status、Run Provenance、Least-Privilege Grant、Scoped Writer、Dispatch Repository、部署和回滚资产。
|
|
|
|
### 已纳入测试代码
|
|
|
|
- Control Plane/Runtime 候选流程。
|
|
- OpenClaw Ed25519 签名与验证。
|
|
- Hermes Worker Lease 与严格 Reconcile。
|
|
- Dispatch SQLite 重启恢复。
|
|
- Workflow/Grant 撤销、过期、重放和服务 Scope 隔离。
|
|
|
|
### 尚需环境验证
|
|
|
|
- 完整 Acceptance 实际执行证据。
|
|
- OpenClaw 真实 Runtime 联调。
|
|
- 生产数据库/队列替换或容量验证。
|
|
- 预发布性能、安全、重启和回滚演练。
|
|
- Owner 对 merge、Tag 和生产部署的批准。
|
|
|
|
## 6. 用户验收场景
|
|
|
|
1. 平台管理员创建租户并注册 OpenClaw/Hermes Agent。
|
|
2. 操作员创建任务，审批人批准。
|
|
3. Owner 或受控签发端签发 Workflow Provenance 与所需最小权限 Grant。
|
|
4. AIOS Orchestrator 持久化 Dispatch，并创建 Ed25519 命令或租户分区 Job。
|
|
5. Runtime 执行并返回与 Dispatch 完全匹配的结果。
|
|
6. AIOS 更新 Task、Audit、Authorization Receipt 和 Execution Evidence。
|
|
7. 租户用户在 Web Console 查看完整链路。
|
|
8. 跨租户、跨 Principal、跨 Grant Path 和重放请求被拒绝。
|
|
9. 服务重启后 Control Plane、Dispatch 和 Provenance 状态恢复。
|
|
10. 候选部署健康检查、Acceptance 和回滚演练实际执行并保存证据。
|