# Capability Registry 与审计 Agent 协议开发规格

适用范围：

- Codex 多机协作系统
- 开放式测试硬件能力接入
- 软件审计、硬件审计、多模态审计、总审计 Agent

目标：

- 定义摄像头、麦克风、扬声器、串口、继电器、拇指机器人等能力如何注册、租约、抢占
- 定义审计 Agent 如何声明需要哪些能力、如何领取任务、如何返回结果
- 为后续数据库表结构、API、消息总线和前端 UI 提供统一协议基础

---

## 1. 总体设计原则

1. 任何真实硬件都不能被 Agent 直接“拿桌面控制权”式使用，必须经过标准化能力层。
2. 所有可调用外设都先注册为 `Capability`，再由租约系统分配使用权。
3. 一个能力可以是独占的，也可以是共享只读的，必须在注册时声明。
4. 抢占必须有优先级、原因、宽限期、证据和审计日志。
5. 审计 Agent 与普通开发线程一样，都只能通过协议调用能力，不能绕过能力层。
6. 视频、音频、大体积流优先在边缘节点做预处理，只上传关键证据和必要片段。

---

## 2. Capability Registry 设计

### 2.1 组件划分

- `Capability Provider`
  运行在具体设备附近，负责暴露本机或本测试台的能力。
- `Capability Registry`
  运行在云端，保存所有能力的元数据、状态、租约和历史。
- `Lease Manager`
  负责发放、续租、释放和过期清理。
- `Preemption Manager`
  负责抢占判定、优先级比较、宽限期通知和安全降级。
- `Capability Gateway`
  对外提供统一 API，屏蔽底层设备差异。
- `Evidence Collector`
  负责把截图、视频片段、串口日志、音频片段等证据统一归档。

### 2.2 核心实体

#### 2.2.1 CapabilityProvider

表示能力提供方，通常是一台 Mac、Windows、Linux 测试台，或一个挂载了外设的专用盒子。

字段：

- `provider_id`
- `node_id`
- `hostname`
- `platform`
- `gateway_version`
- `online_status`
- `last_heartbeat_at`
- `network_zone`
- `owner_type`
- `owner_display_name`
- `auth_mode`
- `labels`

#### 2.2.2 Capability

表示一个可调用能力实例。

字段：

- `capability_id`
- `provider_id`
- `node_id`
- `capability_type`
- `display_name`
- `status`
- `health_status`
- `lease_mode`
  值：
  - `exclusive`
  - `shared_read`
  - `shared_stream`
- `preemptible`
- `default_priority`
- `safety_locked`
- `tags`
- `location_label`
- `metadata_json`
- `constraints_json`
- `supported_actions`
- `evidence_modes`
- `created_at`
- `updated_at`

#### 2.2.3 CapabilityLease

表示一个能力租约。

字段：

- `lease_id`
- `capability_id`
- `holder_type`
  值：
  - `worker_thread`
  - `audit_agent`
  - `human_operator`
  - `system`
- `holder_ref`
  例如：
  - `mac-01:thread-abc`
  - `audit:hardware-auditor-01`
- `project_id`
- `purpose`
- `priority`
- `status`
  值：
  - `requested`
  - `granted`
  - `active`
  - `renew_pending`
  - `preempt_requested`
  - `grace_period`
  - `released`
  - `expired`
  - `revoked`
  - `failed`
- `requested_at`
- `granted_at`
- `expires_at`
- `grace_until`
- `preempt_reason`
- `evidence_required`

#### 2.2.4 CapabilitySession

表示实际执行过程。

字段：

- `session_id`
- `lease_id`
- `action`
- `started_at`
- `ended_at`
- `status`
- `input_summary`
- `result_summary`
- `artifact_refs`
- `error_message`

#### 2.2.5 CapabilityArtifact

表示证据或产物。

字段：

- `artifact_id`
- `session_id`
- `artifact_type`
  值：
  - `image`
  - `video_clip`
  - `audio_clip`
  - `serial_log`
  - `sensor_dump`
  - `ocr_text`
  - `detection_json`
  - `transcript`
- `storage_uri`
- `content_type`
- `captured_at`
- `duration_ms`
- `checksum`
- `metadata_json`

---

## 3. 能力类型定义

### 3.1 Camera

用途：

- 观察设备动作
- 录制关键帧和短视频
- OCR、目标检测、界面识别

关键元数据：

- `device_path`
- `resolution_options`
- `max_fps`
- `supports_snapshot`
- `supports_clip_recording`
- `supports_audio`
- `supports_ptz`
- `field_of_view`

支持动作：

- `snapshot`
- `record_clip`
- `start_stream`
- `stop_stream`
- `set_ptz`

### 3.2 Microphone

关键元数据：

- `sample_rate_options`
- `channels`
- `noise_profile`
- `supports_vad`

支持动作：

- `record_audio`
- `start_audio_stream`
- `stop_audio_stream`

### 3.3 Speaker

关键元数据：

- `output_device_id`
- `supported_formats`
- `max_volume`

支持动作：

- `play_tts`
- `play_audio_file`
- `set_volume`
- `stop_playback`

### 3.4 SerialPort

关键元数据：

- `port_name`
- `baud_rates`
- `parity_modes`
- `supports_binary`

支持动作：

- `open`
- `read`
- `write`
- `expect_pattern`
- `capture_log`

### 3.5 ThumbRobot

关键元数据：

- `robot_model`
- `axis_count`
- `supported_targets`
  例如：
  - `touchscreen`
  - `physical_button`
  - `keyboard`
- `movement_precision_mm`
- `supports_long_press`
- `supports_drag`

支持动作：

- `tap`
- `double_tap`
- `long_press`
- `drag`
- `type_keys`
- `press_hardware_button`

### 3.6 Relay

支持动作：

- `switch_on`
- `switch_off`
- `pulse`

### 3.7 ProgrammablePowerSupply

支持动作：

- `power_on`
- `power_off`
- `set_voltage`
- `set_current_limit`
- `measure_output`

### 3.8 ScreenCapture

支持动作：

- `screenshot`
- `record_screen_clip`
- `ocr`

---

## 4. 注册协议

### 4.1 Provider 注册

`POST /api/v1/capability-providers/register`

请求示例：

```json
{
  "provider_id": "provider-winlab-01",
  "node_id": "win-gpu-02",
  "hostname": "win-gpu-02.local",
  "platform": "windows",
  "gateway_version": "0.1.0",
  "network_zone": "lan",
  "labels": ["lab", "gpu", "hardware-test"]
}
```

返回：

```json
{
  "provider_id": "provider-winlab-01",
  "accepted": true,
  "heartbeat_interval_seconds": 10
}
```

### 4.2 Capability 批量注册

`POST /api/v1/capabilities/register`

请求示例：

```json
{
  "provider_id": "provider-winlab-01",
  "capabilities": [
    {
      "capability_id": "cam-front-01",
      "capability_type": "camera",
      "display_name": "前置观察摄像头",
      "lease_mode": "exclusive",
      "preemptible": true,
      "supported_actions": ["snapshot", "record_clip", "start_stream", "stop_stream"],
      "evidence_modes": ["image", "video_clip", "ocr_text"],
      "metadata_json": {
        "resolution_options": ["1920x1080"],
        "max_fps": 30
      }
    },
    {
      "capability_id": "thumb-robot-01",
      "capability_type": "thumb_robot",
      "display_name": "拇指机器人 1 号",
      "lease_mode": "exclusive",
      "preemptible": false,
      "supported_actions": ["tap", "long_press", "drag"]
    }
  ]
}
```

### 4.3 Heartbeat 与状态更新

`POST /api/v1/capabilities/heartbeat`

用途：

- 更新 provider 在线状态
- 更新能力健康状态
- 上报正在执行的租约
- 上报本地错误或故障

---

## 5. 租约设计

### 5.1 申请租约

`POST /api/v1/capability-leases/request`

请求字段：

- `capability_id` 或 `capability_selector`
- `holder_type`
- `holder_ref`
- `project_id`
- `purpose`
- `priority`
- `requested_duration_seconds`
- `evidence_required`
- `preempt_if_needed`

请求示例：

```json
{
  "capability_id": "cam-front-01",
  "holder_type": "audit_agent",
  "holder_ref": "audit:multimodal-auditor-01",
  "project_id": "proj_device_assistant",
  "purpose": "验证设备 LED 与屏幕切换是否符合交互脚本",
  "priority": 75,
  "requested_duration_seconds": 120,
  "evidence_required": true,
  "preempt_if_needed": true
}
```

### 5.2 续租

`POST /api/v1/capability-leases/{lease_id}/renew`

### 5.3 释放

`POST /api/v1/capability-leases/{lease_id}/release`

### 5.4 过期清理

Lease Manager 负责：

- 定时回收过期租约
- 清理失联 provider 持有的会话
- 把证据未上传完成的 session 标记为 `incomplete_evidence`

---

## 6. 抢占设计

### 6.1 优先级建议

- `100`：安全/紧急停机
- `90`：人工操作员
- `80`：总审计 Agent
- `75`：硬件审计 Agent
- `70`：多模态审计 Agent
- `65`：软件审计 Agent
- `50`：普通 worker 线程
- `20`：后台采样/非关键任务

### 6.2 抢占条件

只有以下条件全部满足时允许抢占：

1. 目标能力 `preemptible=true`
2. 当前租约不是 `safety_locked`
3. 新租约优先级高于当前租约
4. 抢占原因在白名单中
5. 当前 holder 不处于“不可中断动作”窗口

### 6.3 抢占流程

1. 新请求进入 Lease Manager
2. Preemption Manager 评估是否允许抢占
3. 向当前持有者发送 `preempt_requested`
4. 进入 `grace_period`
5. 到期后自动释放或强制收回
6. 新租约转为 `granted`
7. 全过程写事件和审计日志

### 6.4 不可中断动作

以下动作默认不可中断：

- 机器人正在按压或拖拽
- 可编程电源处于切换瞬间
- 固件烧录
- 继电器脉冲动作未完成

---

## 7. Capability 事件流

`GET /api/v1/capability-events/stream`

事件类型：

- `provider_registered`
- `capability_registered`
- `capability_health_changed`
- `lease_requested`
- `lease_granted`
- `lease_renewed`
- `lease_release_requested`
- `lease_released`
- `lease_expired`
- `lease_preempt_requested`
- `lease_preempted`
- `session_started`
- `session_completed`
- `session_failed`
- `artifact_uploaded`

---

## 8. 审计 Agent 任务协议

### 8.1 通用任务请求格式

所有审计任务统一使用 `AuditTaskRequest`。

字段：

- `protocol_version`
- `audit_request_id`
- `project_id`
- `project_name`
- `task_id`
- `source_thread_ref`
- `trigger`
  值：
  - `milestone`
  - `merge_candidate`
  - `failure_escalation`
  - `scheduled_check`
  - `human_request`
- `audit_type`
  值：
  - `software`
  - `hardware`
  - `multimodal`
  - `chief`
- `priority`
- `objective`
- `system_context_summary`
- `acceptance_criteria`
- `risk_focus`
- `evidence_refs`
- `artifact_refs`
- `capability_requirements`
- `time_budget_seconds`
- `response_mode`
- `created_at`
- `metadata_json`

请求示例：

```json
{
  "protocol_version": "1.0",
  "audit_request_id": "auditreq_001",
  "project_id": "proj_device_assistant",
  "task_id": "task_led_validation",
  "source_thread_ref": "mac-01:thread-ui-22",
  "trigger": "milestone",
  "audit_type": "multimodal",
  "priority": 70,
  "objective": "验证设备被唤醒后，屏幕、LED、语音播报与交互脚本是否一致",
  "system_context_summary": "设备端已刷入固件 v0.9.2，等待做端到端唤醒测试",
  "acceptance_criteria": [
    "LED 在 2 秒内变蓝",
    "屏幕切换到 listening 状态",
    "扬声器播报欢迎语",
    "摄像头观测到机械动作完成"
  ],
  "evidence_refs": [],
  "artifact_refs": [],
  "capability_requirements": [
    { "capability_type": "camera", "mode": "exclusive" },
    { "capability_type": "speaker", "mode": "exclusive" },
    { "capability_type": "microphone", "mode": "exclusive" },
    { "capability_type": "thumb_robot", "mode": "exclusive" }
  ],
  "time_budget_seconds": 300,
  "response_mode": "structured_json"
}
```

### 8.2 通用任务响应格式

所有审计任务统一使用 `AuditTaskResult`。

字段：

- `audit_request_id`
- `audit_type`
- `status`
  值：
  - `completed`
  - `failed`
  - `needs_retry`
  - `needs_human_review`
- `decision`
  值：
  - `pass`
  - `fail`
  - `warning`
  - `inconclusive`
- `confidence`
- `summary`
- `findings`
- `required_actions`
- `used_capabilities`
- `artifact_refs`
- `timeline`
- `duration_ms`
- `completed_at`

---

## 9. 软件审计 Agent 协议

### 9.1 输入

在通用格式上追加：

- `repo_ref`
- `base_commit`
- `head_commit`
- `changed_files`
- `diff_refs`
- `build_results`
- `test_results`
- `coverage_summary`
- `runtime_logs`
- `api_contract_refs`
- `release_notes_draft`

### 9.2 输出

- `regression_risk_level`
- `coverage_gap_summary`
- `release_blockers`
- `contract_breaking_changes`
- `log_anomalies`
- `recommended_owner`

### 9.3 findings 格式

每条 finding 至少包含：

- `finding_id`
- `severity`
  值：
  - `critical`
  - `high`
  - `medium`
  - `low`
- `title`
- `description`
- `evidence_ref_ids`
- `suggested_fix`

---

## 10. 硬件审计 Agent 协议

### 10.1 输入

在通用格式上追加：

- `device_topology`
- `firmware_version`
- `hardware_revision`
- `serial_log_refs`
- `sensor_snapshots`
- `power_state`
- `ota_result`
- `expected_state_machine`
- `hardware_test_steps`
- `required_capabilities`

### 10.2 输出

- `device_state_assessment`
- `firmware_mismatch`
- `sensor_anomalies`
- `serial_log_findings`
- `hardware_blockers`
- `recovery_actions`

### 10.3 典型结论

- 固件版本正确但状态机卡死
- 串口日志与预期不一致
- 传感器波动超阈值
- OTA 成功但设备未进入预期模式

---

## 11. 多模态审计 Agent 协议

### 11.1 输入

在通用格式上追加：

- `frame_refs`
- `video_clip_refs`
- `audio_clip_refs`
- `screen_capture_refs`
- `ocr_text_refs`
- `detector_output_refs`
- `interaction_script`
- `expected_visual_states`
- `expected_audio_states`
- `expected_actuator_states`

### 11.2 输出

- `observed_timeline`
- `visual_mismatches`
- `audio_mismatches`
- `interaction_failures`
- `perceptual_verdict`
- `needs_human_review_reason`

### 11.3 典型场景

- 摄像头看设备灯光变化是否正确
- 通过视频确认机械动作是否完成
- 通过音频片段判断 TTS 是否播报了正确内容
- 通过屏幕截图和 OCR 判断 UI 状态是否正确切换

---

## 12. 总审计 Agent 协议

### 12.1 输入

总审计 Agent 不直接看全部原始数据，优先读取：

- `software_audit_result`
- `hardware_audit_result`
- `multimodal_audit_result`
- `rules_audit_summary`
- `human_notes`

### 12.2 输出

- `final_decision`
  值：
  - `approved`
  - `rejected`
  - `needs_human_review`
  - `partial_pass`
- `overall_risk_level`
- `blocking_reasons`
- `recommended_next_step`
- `handoff_target`

---

## 13. 能力需求声明格式

用于审计 Agent 和 worker 线程声明需要哪些外设。

字段：

- `capability_type`
- `mode`
  值：
  - `exclusive`
  - `shared_read`
- `min_duration_seconds`
- `preferred_node_tags`
- `fallback_allowed`
- `preempt_if_needed`
- `purpose`

示例：

```json
[
  {
    "capability_type": "camera",
    "mode": "exclusive",
    "min_duration_seconds": 90,
    "preferred_node_tags": ["lab", "device-station-a"],
    "fallback_allowed": true,
    "preempt_if_needed": true,
    "purpose": "记录设备启动后 30 秒内的状态变化"
  }
]
```

---

## 14. 最小数据库表建议

建议至少有这些表：

- `capability_providers`
- `capabilities`
- `capability_health_snapshots`
- `capability_leases`
- `capability_sessions`
- `capability_artifacts`
- `audit_requests`
- `audit_results`
- `audit_findings`
- `thread_registry`
- `inter_thread_messages`

---

## 15. MVP 实现建议

### V1

- 先做 `camera`、`serial_port`、`thumb_robot`
- 先支持：
  - 注册
  - 独占租约
  - 基础抢占
  - session 留痕
  - artifact 归档
- 先做：
  - 软件审计 Agent
  - 硬件审计 Agent
  - 多模态审计 Agent
  - 总审计 Agent

### V2

- 增加 `microphone`、`speaker`、`screen_capture`
- 增加共享只读租约
- 增加跨设备联合测试流程

### V3

- 增加策略化预调度
- 增加能力热迁移
- 增加自动抢占编排和更细粒度安全策略

---

## 16. 一句话总结

`Capability Registry` 解决“哪些硬件能被谁调用”的问题，  
`Lease / Preemption` 解决“什么时候谁能占用硬件”的问题，  
`Audit Agent Protocol` 解决“审计任务如何标准化下发和回收”的问题。  

这三者合在一起，才能让你的审计 Agent 真正做到可扩展、可监管、可复盘地接管真实世界的测试硬件。