aios/docs/aios-v2/05-TRACEABILITY-MATRIX.md

AIOS V2 需求—架构—代码—测试—部署追踪矩阵

• 文档版本：V2R1C0-candidate
• 目的：确保每项用户需求都能追踪到架构设计、代码实现、自动测试、部署资产和验收命令

1. 追踪规则

每条需求至少具备：

1. 需求编号；
2. 架构章节；
3. 实现路径；
4. 测试路径；
5. 部署/运维资产；
6. 验收状态。

状态定义：

• Implemented：代码已进入 Candidate 分支；
• Test-defined：测试代码已进入 Candidate 分支；
• Test-verified：精确 commit 的测试已运行并保存证据；
• Pre-production verified：预发布部署、健康检查和回滚演练已通过；
• Production released：Owner 批准并完成 merge/tag/deploy。

2. 核心追踪矩阵

需求	设计依据	代码实现	测试	部署/运维	当前状态
UR-001 AIOS 唯一控制面	02-TARGET-ARCHITECTURE.md §3.2/§3.3；ADR-001	aios_v2/control_plane.py、aios_v2/orchestrator.py、aios_v2/app.py	tests/aios_v2_candidate/test_candidate_flow.py	deploy/aios-v2/systemd/aios-v2.service	Implemented / Test-defined
UR-002 复用现有能力	02-TARGET-ARCHITECTURE.md §2；03-MIGRATION-AND-DELIVERY.md §2	aios_openclaw/、aios_hermes/	OpenClaw/Hermes flow tests	Candidate branch + adapter boundaries	Implemented / Test-defined
UR-003 OpenClaw/Hermes 解耦	02-TARGET-ARCHITECTURE.md §3.4/§3.5；ADR-002	aios_openclaw/adapter.py、aios_hermes/adapter.py	runtime boundary tests in candidate flow suite	systemd/Docker runtime configuration	Implemented / Test-defined
UR-004 全面 Web 化	02-TARGET-ARCHITECTURE.md §3.1/§8	aios_v2/console.py、aios_v2/gateway.py、aios_v2/app.py	API/console smoke test pending	Docker/systemd + reverse proxy requirement	Implemented / Test pending
UR-005 多租户隔离	02-TARGET-ARCHITECTURE.md §4；ADR-004	control_plane.py、orchestrator.py、aios_openclaw/*、aios_hermes/*、execution_tracking.py	test_cross_tenant_task_read_is_denied	tenant-scoped state/evidence directories	Implemented / Test-defined
UR-006 权威任务生命周期	04-MODULE-CONTRACTS.md §4	control_plane.py	OpenClaw/Hermes full-flow tests	persisted state + audit	Implemented / Test-defined
UR-007 策略与审批	04-MODULE-CONTRACTS.md §5	control_plane.py、gateway.py	role/policy negative tests需补充	reverse proxy identity + audit	Implemented / Partial test
UR-008 幂等与并发安全	02-TARGET-ARCHITECTURE.md §7	control_plane.py、aios_openclaw/adapter.py、aios_hermes/adapter.py、worker.py	flow + restart tests；并发专项测试需补充	GitOps detached guard + SQLite WAL	Implemented / Partial test
UR-009 执行证据	04-MODULE-CONTRACTS.md §9	execution_tracking.py	test_execution_tracking_persists_claim_heartbeat_and_result	/var/lib/aios-v2/executions	Implemented / Test-defined
UR-010 GitOps 唯一变更流程	03-MIGRATION-AND-DELIVERY.md §4/§5；ADR-003	GitOps Runtime、gitops_status.py	healthcheck 的 detached/clean 检查	deploy/aios-v2/healthcheck/check.sh	Implemented / Runtime verified partially
UR-011 持久化与恢复	02-TARGET-ARCHITECTURE.md §3.6	persistence.py	test_durable_service_recovers_state_after_restart	state dir + backup/rollback	Implemented / Test-defined
UR-012 审计与合规	04-MODULE-CONTRACTS.md §6	control_plane.py、aios_openclaw/callback.py、app.py	flow test + audit assertions需补充	Console audit view	Implemented / Partial test
UR-013 密钥安全	02-TARGET-ARCHITECTURE.md §6；ADR-006	FileSigningMaterialResolver、credential refs、Secret Gate	permission/secret-scan test需补充	env template + external protected file	Implemented / Partial test
UR-014 部署与回滚	03-MIGRATION-AND-DELIVERY.md §7	deployment scripts/assets	acceptance runner + healthcheck	deploy/aios-v2/	Implemented / Pre-prod pending
UR-015 文档与代码同步	03-MIGRATION-AND-DELIVERY.md §9；ADR-005	tools/aios_v2_docs_code_check.py	checker self-test / acceptance runner	CI/Gitea Actions 可调用	Implemented after checker commit

3. API 追踪

API	需求	实现	测试状态
GET /api/v2/health	UR-004, UR-014	gateway.py	healthcheck 定义完成
POST /api/v2/tenants	UR-001, UR-005	gateway.py / control_plane.py	需增加 HTTP 集成测试
POST /api/v2/agents	UR-001, UR-005	gateway.py / control_plane.py	Domain flow 已覆盖
POST /api/v2/tasks	UR-006, UR-008	gateway.py / control_plane.py	Domain flow 已覆盖
POST /api/v2/tasks/{id}/approve	UR-006, UR-007	gateway.py	Domain flow 已覆盖
POST /api/v2/tasks/{id}/dispatch	UR-001, UR-003	app.py / orchestrator.py	OpenClaw/Hermes flow 已覆盖
GET /api/v2/runtime	UR-004, UR-009	app.py	HTTP smoke test待执行
GET /api/v2/executions	UR-009	app.py / execution_tracking.py	Evidence persistence test已定义
GET /api/v2/gitops	UR-010	app.py / gitops_status.py	Runtime/healthcheck验证待执行
POST /api/v2/hermes/results/reconcile	UR-003, UR-006	app.py / orchestrator.py	Hermes flow已覆盖 Domain 路径

4. 运行时契约追踪

契约	设计	代码	测试
OpenClawCommand	04-MODULE-CONTRACTS.md §7.1	aios_openclaw/contract.py	OpenClaw full-flow；签名负向测试需补充
OpenClawResult	§7.2	aios_openclaw/contract.py	OpenClaw full-flow
RuntimeHealth	§7.3	aios_openclaw/contract.py、health.py	health policy测试需补充
HermesJob	§8.1	aios_hermes/contract.py	Hermes full-flow
HermesResult	§8.2	aios_hermes/contract.py	Hermes full-flow
HermesHealth	§8.3	aios_hermes/contract.py、adapter.py	healthcheck/worker test待执行
ExecutionEvidence	§9	execution_tracking.py	evidence persistence test
GitOpsStatus	§10	gitops_status.py	healthcheck detached/clean检查

4.1 核心控制面模型说明

RequestContext 是每次控制面请求的不可缺失上下文。它承载租户、调用主体、追踪标识和请求来源，所有读取、写入、审批与调度都必须先用该上下文完成租户边界和身份检查。适配器不得自行补造租户，也不得把缺失上下文解释为默认管理权限。上下文校验失败时，控制面必须拒绝请求并写入不含密钥值的审计记录。

TaskState 是权威任务生命周期状态，不是前端展示标签。任务从创建、批准、调度、运行到完成、失败或取消，只能沿合同允许的方向迁移；OpenClaw 与 Hermes 回调只能请求迁移，最终状态由唯一控制面持久化。重复回调依靠幂等键收敛，跨租户回调、旧租约回调和非法逆向迁移必须被拒绝。

TenantRecord、AgentRecord 与 TaskRecord 共同定义所有权：租户拥有 Agent 和 Task，Agent 只能处理其租户与授权 Cell/Profile 范围内的任务。任何查询若缺少租户过滤条件，都不能作为正式实现。AuditEvent 记录主体、动作、对象、结果和追踪标识，但不得保存 Token、密码、私钥或签名材料。

OpenClawCommand 与 OpenClawResult 描述短执行路径；前者必须绑定任务、租户、追踪标识、命令期限和签名合同，后者必须回传相同身份域并接受幂等校验。RuntimeHealth 只报告可验证运行事实，不能把本地 Bare Repo 更新误报为 Gitea 完全同步。

HermesJob、HermesResult 与 HermesHealth 描述长任务路径。Job 的领取、心跳和 Lease 续期必须持久化；Result 只有在任务、租户、执行器和租约全部匹配时才能改变权威状态。Worker 崩溃后可重新领取过期 Lease，但不得重复产生业务副作用。

ExecutionEvidence 保存 Claim、Heartbeat、Result 与必要的追踪关系，用于重启恢复和审计闭环。Evidence 的写入必须限定任务分支与固定路径；本轮增加的 Owner-signed Provenance Writer 只允许七个 .agent JSON，并以普通 Commit 与 Push 固化，不授予通用 Shell 或任意仓库写权限。

5. 部署追踪

能力	文件	验收命令
systemd	deploy/aios-v2/systemd/aios-v2.service	systemctl status aios-v2
环境模板	deploy/aios-v2/env/aios-v2.env.example	systemd-analyze verify + 文件权限检查
Docker	deploy/aios-v2/docker/Dockerfile	docker build
Compose	deploy/aios-v2/docker/compose.yaml	docker compose config / up
健康检查	deploy/aios-v2/healthcheck/check.sh	直接执行
回滚	deploy/aios-v2/rollback/rollback.sh	预发布回滚演练
全量验收	deploy/aios-v2/acceptance/run-all.sh	直接执行

6. 文档覆盖追踪

文档	覆盖内容	代码/变更触发条件
README.md	事实源索引、状态语言、实现地图	新模块/目录/版本
01-USER-REQUIREMENTS.md	用户需求、NFR、验收场景	用户行为、功能范围、验收变化
02-TARGET-ARCHITECTURE.md	分层、边界、数据流、安全、租户	架构边界、数据流、运行时变化
03-MIGRATION-AND-DELIVERY.md	迁移、GitOps、Gate、回滚	发布流程、迁移阶段、门禁变化
04-MODULE-CONTRACTS.md	字段、API、状态机、错误语义	Contract/API/模型变化
05-TRACEABILITY-MATRIX.md	需求到代码测试部署映射	代码、测试、部署路径变化
adr/*	关键不可逆或跨模块决策	新架构决策或旧决策替换

7. 当前未完成验证项

以下项目代码或测试定义已存在，但尚不能标记为 Test-verified 或 Pre-production verified：

1. 精确 Candidate commit 的测试执行结果；
2. HTTP API 与 Web Console 冒烟测试；
3. 真实 OpenClaw Runtime 签名、取消、超时和健康联调；
4. Hermes 长任务心跳、Worker 崩溃和 Lease 恢复演练；
5. 多实例 SQLite/并发容量边界；
6. systemd、Docker、Compose、restart 和 rollback 演练；
7. local/Gitea Candidate OID 一致证明；
8. 生产身份代理、防伪 Header、CSRF/CORS/Rate Limit 验证；
9. 文档—代码同步检查器在 CI/Acceptance 中执行通过。

8. 更新要求

任何代码、API、部署或测试路径变化，必须同步更新本矩阵。验收脚本会检查本文档引用的关键路径存在，并检查架构/功能代码变化是否同时包含 docs/aios-v2/ 变化。

OpenClaw 命令签名材料

openclaw-v2r1-candidate-ed25519 使用 Ed25519 私钥对 canonical command bytes 签名，签名以 URL-safe Base64 编码。运行材料只允许是 32 字节 raw private key 或 Ed25519 PEM；FileSigningMaterialResolver 不得对 raw bytes 执行 strip()。签名、篡改拒绝、过期拒绝由候选测试与运行时 sign/verify 探针共同验证。