aios/docs/aios-v2/01-USER-REQUIREMENTS.md

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 权威任务生命周期

任务必须遵循统一状态机：

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 和回滚演练实际执行并保存证据。