内容
# 头部空间
### 一种用于AI编码代理的人机协作防火墙 — 以及一项关于何时信任人类的衡量研究
*OpenClaw赋予代理以操作能力。Headroom则提供刹车。*
**一个思维实验，在架构之前。**
两名守卫观察同一个代理。
- **守卫A** 每天升级 **5个操作** 交由人类审查员。
- **守卫B** 每天升级 **500个操作**。
大多数人会选择 **B** — 更多监督，更安全。以下是分析：
| | 守卫A（5个/天） | 守卫B（500个/天） |
|---|---|---|
| 审查者审批 #300 | 仔细阅读所有5个 | 疲劳，批量审批 |
| 恶意操作隐藏在流程中 | 被抓住 | 顺利通过，获得疲惫的“是” |
守卫B有更多的监督，但结果更糟。
重新定义：升级并不是免费的。每次升级都会消耗有限的人类注意力资源 — 这是同一个资源池，危险操作也需要它。因此，监督不仅是一个 **分类** 问题（哪个操作有风险？）；它还是一个 **资源分配** 问题（升级策略会花费威胁竞争的预算）。
> *这是一种视角，而不是发现：疲劳审查员模型是已有技术（FALCON，DeCCaF）。该仓库的工作是将它应用于LLM代理守卫并进行曲线拟合。*
AI代理现在 **运行** 代码 — 部署、删除、推送到 `main`。通常的安全答案是人类审批门槛。但暂停按钮很容易，难点在于 **判断** （哪些操作需要停止）以及 **人类审查员的主观性和疲劳性**。Headroom既是一个工作门槛，也是一种 **衡量** 判断的机制，而不是靠猜测。
**同时解决两个问题：**
- 🛠️ **系统** — 工作LLM代理提出操作；守卫（确定性规则 + LLM风险判断）将每个操作分类为 **安全 / 需要审批 / 阻止**；风险操作会在任务中途暂停（LangGraph `interrupt()`）并等待人类；每个决定都会在实时仪表盘上记录审计日志，并带有交互式 **校准拨盘**。
- 📊 **衡量** — 我们将守卫视为 **具有不对称成本、噪声标签和疲劳审查员的选择性分类**，并进行衡量：校准曲线、噪声底线（Fleiss' κ = 0.52）、安全与监督的 **倒置U型曲线**、**攻击** 和模型依赖性 — **4张图表 + 测量的噪声底线**（3个关键自由再生；2个LLM评分的制品需要Anthropic密钥才能再生）。*(范围：应用/衡量项目。机制 — 疲劳感知延迟、洪水攻击 — 是已有技术，我们引用；贡献是开源系统 + 衡量。参见 **[docs/DRAFT.md](docs/DRAFT.md)**.)*
> *任何人都可以停止代理。Headroom衡量 **何时** 停止 — 并显示每次设置的成本。*
**[▶ 直播演示](https://turangenesis.github.io/headroom/)** — 阻止 `rm -rf`，审批部署，拖动校准拨盘。无需安装，无需API密钥。
**或在一分钟内本地运行：** `uvicorn headroom.api:app` → 打开仪表盘 → **运行演示** （观看 `rm -rf` 被阻止，生产部署暂停审批）→ 滚动到 **校准浏览器** 并拖动拨盘。
## 问题（为什么这不仅仅是一个暂停按钮）
当代理获得实际操作能力 — 部署、删除、花费资金、触及生产环境 — 瓶颈不再是 *能否* 停止它们；框架已经可以做到这一点。瓶颈在于 *能否信任* 决定何时停止它们的机制。过度监管，人类会批量审批每个警报，直到守卫变得无用；监管不足，某些事情会出错。目前，这个临界点通常由经验决定。Headroom通过 **数据** 来设定。
## 工作原理
```
worker agent → 提出操作 → guard (rules → LLM) ─┬─ 安全 ▸ 运行
├─ 阻止 ▸ 拒绝
└─ 审批 ▸ 暂停（interrupt）
→ 人工审批 / 拒绝
→ 继续 / 终止
→ 只追加审计日志 + 实时仪表盘
```
门槛是基础；其上层 — 衡量门槛的判断是否良好 — 是贡献。
## 校准评估
守卫发出 **0–100风险评分** 每个操作。扫描自动允许与升级阈值会产生 **安全/效用权衡曲线** — 漏报率 vs 误报率 — 在 **不对称成本矩阵** 下（自动允许危险操作是灾难性的；误报是烦恼）。
```bash
python -m eval.calibrate # 打印扫描 + 成本最小化 & Neyman-Pearson 点 + AURC
python -m eval.calibrate --plot # 还会写入 eval/calibration.png
```
在一个 **125个操作的手动标注集** 中，故意加权为 *困难* 情况 — 模糊中间、混淆/对抗性（base64 `rm -rf`，同形 `maín`，路径遍历，数据泄露），以及令人担忧但无害的陷阱（小，报告为此类 — 不是已发布的基准） — 曲线讲述了故事：针对对抗性/模糊输入，守卫 **无法安全自动决策** — 达到 0% 危险漏报强制要求几乎所有操作升级（成本最小化策略 ≈ “询问人类关于所有事情”）。这是制品 *和* 发现：您从曲线中读取守卫的实际操作限制，并带有数据 — 在困难输入上它无法安全过滤，这就是为什么需要对人类进行高频升级（→ 下面的研究方向）。
**噪声底线 — 为什么单一“地面真相”是一个谎言。** “此操作是否具有风险？”是 **主观的**：即使是谨慎的审查者也不同意，因此守卫不能针对一个客观标签进行评分。 `python -m eval.noise_floor` 有三个LLM-persona审查者（谨慎 /务实 / 严格合规）标记125个操作集，并报告 **Fleiss' κ ≈ 0.52** — 只有 *中等* 一致性，而 **务实** 审查者标记 **87个操作为安全**，而谨慎者标记 **45个** （差距 **是** 风险容忍度轴）。这是 **不可分割** 的不一致，它是衡量标准：一个守卫与审查者意见一致的频率与他们彼此意见一致的频率相同是“人类”级别。 *(角色是 **代理** 人类标注者 — 报告为此类，而不是真正的人类底线。)*
> **精度说明（因此声明是准确的）：** 曲线是 **不对称成本下的运行点分析** （选择性分类） — *不是正式的ECE/reliability意义上的校准*。 “校准”是主题；声明是准确的衡量权衡 + 噪声底线。正式的校准指标（ECE，Brier，可靠性图），对抗性/规避集，已发布的基准（AgentDojo，InjecAgent）和前沿方法（一致预测，轨迹级守卫）是更严格的验证路线图 — 参见 **[Stage 1](ROADMAP.md)**。
> **主线：** *停止代理是一种框架功能。知道何时停止它 — 不对称成本和标签噪声下的选择性分类 — 是问题，以下是显示权衡和使操作点成为衡量选择的曲线。*
## 研究方向 — “监督有容量”
最深层次的论文（完整细节 → **[docs/RESEARCH.md](docs/RESEARCH.md)**）。代理安全性通常被建模为一个 *完美、无限* 的人类检查一个有缺陷的代理对抗一个 *地面真相* 的“安全”。所有这三个都是错误的：标签是 **主观的** （没有地面真相；测量的Fleiss' κ ≈ 0.52），人类是 **内生的** （升级使他们疲劳 — 守卫降低了自己的预言），成本是 **不对称的**。因此，最优的 **何时升级** 策略必须是 **负载感知的**，而实现的安全性是一种 **倒置U型曲线**:
> **更多人类监督可能使系统 *更不* 安全 — 安全最优的守卫在人类容量以下升级。**
这是 **具有噪声标签和内生专家** 的选择性分类下的不对称成本 — 最后一个子句是 **已有技术** （FALCON / DeCCaF），我们在LLM代理设置中通过模拟的倒置U型实验 **演示**。
**范围：** 这在 **只有判断是主观且有延迟结果** 的情况下才有意义（代理监督，内容审核，警报分诊）— **不是** 在有客观地面真相的情况下（例如银行欺诈，使用更好的预测器）。新颖性检查确认核心机制是 **已有技术** — 内生疲劳审查员 + 负载感知延迟是 **FALCON / DeCCaF**，洪水攻击是SOC警报疲劳，轨迹守卫是ShieldAgent等。 **这是一个应用/衡量/系统项目，而不是一个新理论论文** — 贡献是开源防火墙 + 衡量这些想法在LLM代理中的整合。
> 工作文件草稿在 **[docs/DRAFT.md](docs/DRAFT.md)** （从图表 + 真实数字构建）。
## 入门指南
```bash
pip install -r requirements.txt # 或：uv sync
cp .env.example .env # 添加 ANTHROPIC_API_KEY（和可选的LangSmith密钥）
```
## 用法
```bash
uvicorn headroom.api:app # 仪表盘 → http://localhost:8000（运行演示不需要密钥）
```
仪表盘显示实时活动流，待处理审批以及守卫的推理，审批/拒绝，以及每笔运行的成本线。 **运行演示** 按钮驱动一个完整的 安全 → 阻止 → 审批流程 **无需API密钥**。 **校准浏览器** 让您 **拖动** 守卫的激进程度，并实时观察在所有125个操作中误报率与漏报率的权衡 — 曲线可视化，重新演绎保存的分数（无需API调用）。运行 `python -m eval.calibrate` 一次即可填充它。
## 将其插入您自己的代理（MCP）
Headroom也是一个 **MCP服务器**，因此您的代理 — Claude Code，Cursor，或自定义代理 — 可以通过守卫路由其操作。代理不会打开此应用程序；它会调用两个工具（`submit_action_for_review`，`check_review`）在采取行动之前。在MCP客户端配置中添加约4行：
```jsonc
{ "mcpServers": { "headroom": { "command": "python", "args": ["-m", "headroom.mcp_server"] } } }
```
现在，当您的代理想要 `git push` 或 `rm -rf` 时，它会询问Headroom — 返回 **允许** / **阻止**，或 **待处理**（在仪表盘上排队等待人类审批）。无需真实客户端即可查看：
```bash
python scripts/mcp_demo.py # 外部代理通过MCP提交3个操作 → 裁决
python -m headroom.mcp_server # 运行MCP服务器本身（标准输入/输出）
```
> *合作集成（代理配置为询问）。真正的无绕过 — 网关/主机钩子/沙盒 — 是[强制阶梯](ROADMAP.md)在此之上。*
## 开发
```bash
pytest # 单元 + 集成测试（无需API密钥）
python -m eval.run_eval # 守卫混淆矩阵 + 召回率 / 精确率
python -m eval.calibrate --plot # 校准曲线（成本矩阵，扫描，NP点，AURC）+ PNG
python -m eval.noise_floor # 审查者间kappa — 噪声底线（LLM-persona代理）
bash scripts/smoke-check.sh # 密钥文件检查 + pytest
```
评估 **按设计具有成本意识** — 提示缓存，消息批次API，预先录制的worker轨迹和分层采样，并带有内置的裁判成本/缓存计量器（`GET /api → judge_cost`）。方法论和目标 → **[docs/EVAL.md](docs/EVAL.md)**。
## 重现结果
```bash
git clone … && cd Headroom && pip install -r requirements.txt
# 无密钥（重放已提交的分数/纯模拟） — 准确的论文数字：
python -m eval.inverted_u # 倒置U型曲线（图2）[读取已提交的calibration.json]
python -m eval.fatigue_attack # 洪水攻击（图4）
# 需要ANTHROPIC_API_KEY（LLM评分；每个几美分）：
python -m eval.calibrate --plot # 校准曲线 + 每操作分数（图1）
python -m eval.noise_floor # κ噪声底线 [已提交：eval/noise_floor.json]
python -m eval.compare_models # Haiku vs Sonnet（图3）[已提交：eval/model_comparison.json]
python -m eval.nseed --temp 0 --n 3 # 部署环境AURC分布
```
四张图表位于 [`eval/`](eval/) (`calibration.png`, `inverted_u.png`, `model_comparison.png`, `fatigue_attack.png`)；κ噪声底线是一个数字，而不是图表。两个LLM评分的制品（`noise_floor.json`，`model_comparison.json`）是 **已提交的**，因此引用的数字即使没有密钥也会随附。
## 技术栈
Python 3.12 · LangGraph (`interrupt()` HITL + SqliteSaver) · langchain-anthropic (Claude) · FastAPI · SQLite · MCP (FastMCP) · LangSmith · Tailwind-CDN 仪表盘。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
