krisolo/boss

Fork 0

Files

kris 90cb6b7ff1 feat: ship native boss android console

2026-03-26 23:16:56 +08:00

16 KiB

Raw Blame History

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

适用范围：

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

目标：

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

1. 总体设计原则

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

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

请求示例：

{
  "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"]
}

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

4.2 Capability 批量注册

POST /api/v1/capabilities/register

请求示例：

{
  "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

请求示例：

{
  "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 抢占条件

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

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

6.3 抢占流程

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

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

请求示例：

{
  "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

示例：

[
  {
    "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 真正做到可扩展、可监管、可复盘地接管真实世界的测试硬件。

16 KiB Raw Blame History Unescape Escape

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

1. 总体设计原则

2. Capability Registry 设计

2.1 组件划分

2.2 核心实体

2.2.1 CapabilityProvider

2.2.2 Capability

2.2.3 CapabilityLease

2.2.4 CapabilitySession

2.2.5 CapabilityArtifact

3. 能力类型定义

3.1 Camera

3.2 Microphone

3.3 Speaker

3.4 SerialPort

3.5 ThumbRobot

3.6 Relay

3.7 ProgrammablePowerSupply

3.8 ScreenCapture

4. 注册协议

4.1 Provider 注册

4.2 Capability 批量注册

4.3 Heartbeat 与状态更新

5. 租约设计

5.1 申请租约

5.2 续租

5.3 释放

5.4 过期清理

6. 抢占设计

6.1 优先级建议

6.2 抢占条件

6.3 抢占流程

6.4 不可中断动作

7. Capability 事件流

8. 审计 Agent 任务协议

8.1 通用任务请求格式

8.2 通用任务响应格式

9. 软件审计 Agent 协议

9.1 输入

9.2 输出

9.3 findings 格式

10. 硬件审计 Agent 协议

10.1 输入

10.2 输出

10.3 典型结论

11. 多模态审计 Agent 协议

11.1 输入

11.2 输出

11.3 典型场景

12. 总审计 Agent 协议

12.1 输入

12.2 输出

13. 能力需求声明格式

14. 最小数据库表建议

15. MVP 实现建议

V1

V2

V3

16. 一句话总结

16 KiB

Raw Blame History