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和 VerifierVerdict分开建模;- 执行后强制进入
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/ 中的清单与政策;贡献内容默认受贡献者声明约束。