feat: ship native boss android console

docs/source-material/capability_registry_and_audit_protocol_cn.md

@@ -0,0 +1,843 @@
+# 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 真正做到可扩展、可监管、可复盘地接管真实世界的测试硬件。