aios/docs/task-plane/README.md

AIOS Task Plane

该模块是与任务发起方、Worker 类型和通知后端解耦的持久化任务控制平面。当前交付仅用于隔离开发与 Shadow 验收；默认 execution_enabled=false，不会修改生产、tag、Baseline 或 Registry。

架构

• TaskPlaneService：统一服务边界和 HTTP 路由。
• TaskPlaneStore：SQLite WAL、revision/CAS、串行事务、租约、hash-chained journal、evidence 和 durable outbox。
• WorkerRegistry / LeaseManager：身份绑定、capability、并发额度、心跳、过期探测后恢复。
• DelegationEngine：父子 DAG、全局深度、capability/risk/approval/budget 单调约束和幂等重放。
• PolicyEngine：默认关闭执行；身份、证据、结果摘要和可插拔签名验签均 fail-closed。
• WorkerAdapter：OpenClaw、Codex、Hermes、A2A 和 systemd Worker 的统一契约。默认实现只返回 SHADOW_VERIFIED，不执行外部命令。
• DurableOutboxDispatcher：Webhook、NATS JetStream、GPT callback、Dashboard 和 WeChat 的回执式通知接口。没有真实回执时始终保留 NOT_DELIVERED。

状态与恢复

正常路径为 CREATED → QUEUED/CLAIMED → RUNNING → VERIFYING/COMPLETED；失败路径使用 FAILED_RECOVERABLE、FAILED_FINAL、CANCELLED 或 MANUAL_REVIEW_REQUIRED。每次状态事件都进入同一事务中的 append-only hash chain。

租约过期不会自动重放副作用。控制平面必须先调用 Worker probe，只有明确确认原执行已停止，才可将 claim 标记为 EXPIRED 并把任务转为 FAILED_RECOVERABLE。结果必须匹配 task、claim、Worker identity、未过期 lease 和 operation digest；重复结果返回冲突。

安全模型

• task/worker/claim/message ID 使用 allowlist pattern，拒绝 URL 编码差异、路径分隔符和控制字符。
• HTTP body 最大 1 MB，非对象 JSON、异常 Content-Length 和非法参数返回 400/413。
• 内部异常响应不回显路径、payload 或凭据；默认 HTTP access log 不记录原始 request target。
• secret-like 字段在 durable task、event、evidence 和 outbox 写入前脱敏。
• 结果签名存在但没有配置验签器时拒绝；摘要、evidence 或 event 被篡改时验收失败。
• SQLite 文件创建为 0600；新建状态目录使用 0700。

验收

PYTHONPATH=active-runtime \
  bash scripts/task-plane/run_task_plane_acceptance.sh

PYTHONPATH=active-runtime \
  python3 scripts/task-plane/create_shadow_tasks.py \
    --database reports/task-plane-shadow.sqlite3 \
    --report reports/task-plane-shadow.json

上述脚本只使用本地 SQLite 和 Shadow adapter，不触发真实 OpenClaw、Codex、Hermes、微信或生产执行。