EAH — Embodiment Adaptation Harness

EAH 是一套 Clean-room、跨平台的具身智能可信执行系统:自研 Capability-Grounded Agent(CGA) 负责按当前具身能力规划,EAH Harness 负责准入、执行生命周期、证据验证、恢复、安全和硬件适配。

执行器结束不等于任务成功。只有来源明确、新鲜且满足验证策略的证据,才能形成已验证事实。

当前状态

  • 已有 P0 Mock/Replay 软件闭环:CGA、Gateway、能力/技能契约、Orchestrator、Verifier、Recovery、Safety、Runtime、Trace、资格和回滚;
  • 自动测试覆盖 unit、replay、fault injection 和 Eval 契约;
  • 9 场景 P0 Trust Eval 覆盖成功、五类故障、UNKNOWN、恢复收敛、风险/统计指标和对象替换关系;
  • 事件具有稳定 ID/顺序并支持 SSE 续传;失败可生成可解释 Timeline、脱敏 Debug Bundle,并与同一 Eval 基线做回归比较;
  • Gateway 自带本地开发控制台,支持开放式多轮对话(LLM 或规则解析),并查看能力锚定任务图、执行 Trace、根因和 Debug Bundle;控制台锁定 Mock;
  • RDK 是首个参考 Platform Pack,但真实 RDK 相机 HIL 尚未完成;
  • 当前连接的 S100P 没有相机;仓库提供零传感器、零技能的保守 headless Manifest,控制面可运行但不能做真实观察;
  • P0 只承诺观察型能力,P2 目录中的抓取/放置 Manifest 是草案,不代表真机资格;
  • 项目不复用 RoboClaw 或其他相关 Robo Agent 项目的代码、Prompt、Skill、Schema、配置、模型或数据制品。

项目范围见 PROJECT.md,当前任务见 TASKS.md,完整文档导航见 docs/README.md。

系统闭环

用户目标
  → CGA:意图解析、能力锚定、任务图、已验证事实记忆
  → Agent Gateway:鉴权、结构校验、幂等、HTTP/SSE
  → EAH Core:准入、生命周期、验证、恢复、安全、事件与资格
  → Skill Executor:mock / replay / HTTP policy / ROS 2 action
  → Device / Embodiment / Platform Pack:RDK、Linux Reference、未来平台

关键规则:

  • 自由文本不能穿透到控制层;
  • ExecutionTermination、TaskOutcome 和 Verifier Verdict 分开建模;
  • 执行后强制进入 VERIFYING,progress 永远不是成功证据;
  • UNKNOWN 是一等结果,过期、冲突、低质量或失准证据不能补成成功;
  • 资格绑定技能、执行器、机器人、标定、Verifier、Recovery Graph、ODD 和制品版本;
  • 安全优先级为硬件急停/实时控制器 > Safety > Orchestrator > CGA;
  • 人工移动、复位、授权或接管单独记录,不计入自主成功;
  • 换硬件需要显式适配和重新资格,不承诺“任意设备零配置即插即用”。

快速开始

要求 Python 3.9+:

python3 -m pip install --user pyyaml jsonschema pytest

python3 -m eah.tools.cli validate-manifests
python3 -m pytest eah/tests -q

# 可执行 AI Eval;默认只用 Mock,输出逐样本和统计报告
python3 -m eah.tools.cli eval --output /absolute/path/to/p0_eval_report.json

运行 Mock 闭环:

# 验证成功
python3 -m eah.tools.cli run-demo --scenario success

# 执行器完成但状态未变化:必须是 STATE_NOT_CHANGED
python3 -m eah.tools.cli run-demo --scenario no_change

# 遮挡后重观察恢复
python3 -m eah.tools.cli run-demo --scenario occluded

# 自然语言目标 → 结构化任务图 → 验证事实记忆
python3 -m eah.tools.cli agent --goal "把red_cup移到tray"

优先使用的调试—迭代闭环:

# 1. 记录一个失败(非零退出是预期)
python3 -m eah.tools.cli run-demo --scenario no_change \
  --event-log /absolute/path/to/events.jsonl

# 2. 用上一步状态中的 request_id 解释并打包
python3 -m eah.tools.cli trace \
  --event-log /absolute/path/to/events.jsonl --request-id req-...
python3 -m eah.tools.cli debug-bundle \
  --event-log /absolute/path/to/events.jsonl --request-id req-... \
  --output /absolute/path/to/debug-bundle.json

# 3. 修改后运行同一 Eval,再与冻结基线比较
python3 -m eah.tools.cli eval-compare \
  --baseline /absolute/path/to/baseline.json \
  --candidate /absolute/path/to/candidate.json

设计和当前缺口见 docs/OBSERVABILITY.md。

启动本地 Gateway:

python3 -m eah.tools.cli serve --host 127.0.0.1 --port 8080 --token secret

# 在另一终端
python3 -m eah.tools.cli submit --token secret \
  --skill simulate_transfer \
  --arg object_id=red_cup --arg target_id=tray

curl -H "Authorization: Bearer secret" http://127.0.0.1:8080/v1/health

启动后浏览器打开 http://127.0.0.1:8080/,在“连接设置”输入启动时使用的 token,即可进行多轮对话:开放式目标由 LLM 生成候选计划(配置 EAH_LLM_API_KEY 启用,见 docs/RUNBOOK.md),未配置时以确定性规则解析并显示"规则解析"徽标。计划始终经过服务端技能白名单、能力锚定与安全准入;控制台只允许 Mock,自由文本不会直接进入执行器或硬件。

无相机 S100P 的安全控制面配置:

python3 -m eah.tools.cli serve --host 127.0.0.1 --port 8080 \
  --token secret \
  --robot-manifest eah/manifests/robots/rdk_s100p_headless_01.yaml

该配置不会声明或执行任何观察/运动技能;Mock 学习继续使用默认参考 Manifest。 控制台仍可打开,但输入“观察场景”会在执行前显示能力拒绝,不会访问相机或其他端口。

独立 Agent Host 进程(只经公开协议与 Gateway 通信,无机器人也可启动):

python3 -m eah.tools.cli agent-host --profile single-host --port 8080 --token secret
# 连接机器人侧 Gateway:
python3 -m eah.tools.cli agent-host --profile local-pc \
  --gateway-url http://192.168.1.20:8080 --token secret

更多运行、事故与回滚步骤见 docs/RUNBOOK.md。

当前 P0 技能和故障

观察技能:observe_scene、locate_object、inspect_state、verify_relation、reobserve。simulate_transfer 只用于 Mock/Replay 的状态变化测试。

基准故障:OBJECT_NOT_FOUND、VIEW_OCCLUDED、STATE_NOT_CHANGED、EXECUTION_TIMEOUT、SENSOR_UNCERTAIN。

目录

eah/
├── agent/                 CGA:意图、锚定、任务图、记忆、监督、改进分析
├── core/                  公共模型、枚举和错误
├── agent_host/            Agent Plane(ADR-0005):AgentRuntime SPI、Kernel、Native Runtime、协议、后端、目录视图、Profile、AgentHost
├── gateway/               HTTP API、SSE、客户端、Goal/Chat/Proposal Admission
├── console/               本地自然语言、任务图和 Trace 控制台
├── capability_manager/    Robot Manifest、ODD、能力与资格绑定
├── skill_registry/        Skill Manifest 和资格状态
├── orchestrator/          执行生命周期和验证门禁
├── verifier/              证据融合、新鲜度和状态变化
├── recovery/              分层 Recovery Graph
├── safety/                急停、授权、资源和工作区门禁
├── runtime_supervisor/    健康、时钟、资源和预定义降级
├── tracing/ event_store/  Trace Context 与追加事件/证据
├── adapters/ devices/     技能执行与设备抽象
├── platforms/             Platform API、Linux Reference、RDK
├── qualification/         候选检查、发布和回滚
├── evals/                 Suite、Runner、Oracle、指标和报告
├── debugging/             时间线、调试包和失败归因入口
├── improvement_loops/     失败归因与四类改进入口
├── manifests/ schemas/    机器可校验契约
├── compliance/            依赖、许可、SBOM、贡献声明
├── tests/                 unit / replay / fault injection / HIL
└── deploy/ tools/         部署样例与 CLI/指标

文档

需要了解 文档
项目目标、范围、非目标、成功标准 PROJECT.md
必须实现的行为和验收条件 docs/SPEC.md
模块边界、依赖和流程 docs/ARCHITECTURE.md
状态、字段、Manifest 和 HTTP API docs/CONTRACTS.md
测试、HIL 和指标 docs/TESTING.md
AI Eval、数据集、Oracle、泛化和持续资格 docs/EVALUATION.md
可观测、调试、复现与版本迭代闭环 docs/OBSERVABILITY.md
物理/网络/供应链安全 docs/SECURITY.md
当前开发队列 TASKS.md

许可证与来源边界

项目元数据声明 Apache-2.0。所有外部依赖和材料必须遵守 eah/compliance/ 中的清单与政策;贡献内容默认受贡献者声明约束。

Description
No description provided
Readme Apache-2.0 918 KiB
Languages
Python 93.8%
CSS 2.8%
JavaScript 2.2%
HTML 1.1%