CUA 风险检测使用指南

概念速览

每个 GUI 动作执行前做风险分级：L0 只读放行 · L1 可逆写放行+记录 · L2 挂起等人裁决（网页/手机确认） · L3 硬阻断。

零安装：登录后把动作轨迹发上来，服务端用与运行时 Gate 同一套规则分级。适合「我想知道我的 Agent 哪些动作会被拦」。可直接在 /cua 页面 粘贴检测，或调 API：

curl -X POST https://aihcc.cloud/api/cua/classify \
  -H "Authorization: Bearer sk-..." \
  -H 'Content-Type: application/json' \
  -d '{"actions": [
    {"action": "screenshot"},
    {"action": "click", "target_element": "发送", "target_app": "mail"},
    {"action": "type", "text": "rm -rf ~", "target_app": "terminal"}
  ]}'

宽松输入：action 可省略——给 {x,y} 坐标推断为 click；给 text/action_input 推断为 type；pyautogui 风格动作名自动归一化。注意：路径 A 只做分级裁决，不真的拦截；要拦截用路径 B。

在你的 harness 每个动作执行前调 ActionGate：L2 挂起等人在网页裁决、L3 直接阻断；审计逐动作上报，可在 审计回放 与 确认裁决 页面查看。需 Pro 增强版或 CUA 版套餐。

B1. 安装

下载安装包后本地 pip 安装：

pip install ./hallucc_cua-0.1.0-py3-none-any.whl
# 接远程审计上报 / L2 确认回调需 httpx：
pip install httpx

# 必填：设 API Key 环境变量（https://aihcc.cloud/keys 获取，需 Pro 增强版或 CUA 版）
export HALLUCC_API_KEY=hc_xxx
# 可选：内网/自建部署指向你的服务端，默认 https://aihcc.cloud
export HALLUCC_BASE_URL=https://aihcc.cloud

• 缺 HALLUCC_API_KEY → /keys 获取后 export
• 401 → API Key 无效或已失效
• 402 → 套餐不含 CUA 运行时拦截，升级 Pro 增强版/CUA 版
• 网络不可达 → 检查 HALLUCC_BASE_URL 与连通性

B2. 接入 harness

import os
from cua import ActionGate, ActionRecord, Policy   # import 即触发在线激活（凭 HALLUCC_API_KEY）
from cua.remote import make_http_audit_sink, make_remote_confirm_callback

API_KEY = os.environ["HALLUCC_API_KEY"]   # 与激活同一个 key；运行时确认/审计也用它

gate = ActionGate(
    policy=Policy(),                        # 默认含纯编辑器白名单降噪
    confirm_callback=make_remote_confirm_callback(
        "https://aihcc.cloud", API_KEY, timeout_s=120),   # L2 → 网页裁决
    audit_sink=make_http_audit_sink(
        "https://aihcc.cloud", API_KEY, session_id="my-session-001",
        fallback_path="cua_audit_fallback.jsonl"),        # 上报失败落本地不阻塞
)

decision, result = gate.execute(
    ActionRecord(action="click", target_element="发送", target_app="mail"),
    fn=lambda: pyautogui.click(x, y),       # 仅 verdict != block 时执行
)

• 不传 confirm_callback 时 L2 默认拒绝——宁可误拦不可漏拦。
• remember_ttl=秒数 开启「记住决定」：批准的 L2 在 TTL 内对完全相同动作免重复确认；L3 永不进缓存。
• approve_plan(recs, plan_callback) 批量计划确认：L2 一批裁决，L3 不参与批量。
• 无 a11y 标签的图标按钮可注入 icon_labeler（VLM 兜底）——标注只升不降。

B3. 注入防护（屏幕内容进上下文之前）

from cua import screen_filter

report = screen_filter(ocr_text, task=user_task)   # 模式层，0 LLM
if report.verdict == "injection":
    ...  # 拦截或清洗后再喂给 agent