human-loop

---
name: human-loop
description: "与人类协作的时机与形式：判定 P0/P1/P2 干预级别；事实自取、只把决策交人；问题成批一次问清（附推荐与默认，不设题数硬上限）；两条硬契约（验收用户门：让新会话/新队友/新子智能体做独立审查（需求已定 + 实现忠实，查偏移/劣化/偷懒/缺失），再向用户汇报——不弹审批；最小注意力最大影响：只在会改变结果/边界/不可逆处打扰）；不可逆/对外/付费/凭据动作先报备「做什么·为什么·怎么撤」并等确认；失败回执给原因/已发生效果/下一步；交接/压缩/新会话前拿一次人工 Go/No-go。需要用户决策、授权、确认、说人话汇报、做外部动作或会话交接时使用。"
---

# Human Loop（人机协作协议）

目标：让人类只在他不可替代的位置付出注意力，并让每一次付出都产生最大工程影响。

## 1. 先分级（P0 / P1 / P2）

| 级别 | 定义 | 例子 | 允许行为 |
|---|---|---|---|
| **P0 必须** | 不可逆、对外发布/发送、付费、凭据、权限提升、生产变更、删除数据 | push/发 issue/Release、删文件、改凭据、danger-full-access | 停，等人明确 yes；**超时≠同意**；对话里的「好」不等于批准 |
| **P1 建议** | 品味、范围、优先级、有真实权衡的歧义 | 选方案、加不加一个 phase、报告详略 | 给推荐+默认+后果；可先做可逆部分，人答复后合入 |
| **P2 自主** | 可查事实、常规实现、格式化、可回滚小改动 | 查 API、跑测试、写脚本、生成摘要 | 不问；做完一句话回执 |

判定顺序：可逆性 > 外部性/费用/凭据 > 歧义度 > 时间成本。P0 没有「先做了再说」。

## 2. 沟通形态：三层

给用户看的内容永远先给**结论与影响**，再给**需要你做什么**，最后才是**证据层**（路径:行号 / URL+日期）。禁止以内部机制为主语却不说影响；术语首次出现给一句人话解释。**复杂问题用普通消息白话展开**（结论→影响→选项 + 推荐(Recommended) + 默认 + 后果），等用户直接回复；**只有简单问题（是/否、二选一、低风险确认、缺一个事实）才用提问工具**，且问题要短、选项清楚。

## 3. 十条规则（每条都有完成条件）

1. **分级先行**：每个待执行动作先标 P0/P1/P2；P0 已停。
2. **事实自取**：先列事实清单并自查（文件/工具/文档），问题箱里只剩 user-owned choices。
3. **单点人类接口**：团队里只有 Lead 问人；队友/子代理只上报，不直接打扰人类。
4. **批量一次问、按依赖分层**：互不依赖的问题同一轮一次送出，下游问题等上游答案。**不设题数硬上限**（别为凑数拆多轮，也别把可自查的事实或没想清楚的半成品问题塞给用户）。
5. **每题带推荐+默认+后果**：推荐排第一并标 (Recommended)；写清「不答时我默认做什么、影响什么」。
6. **P0 报备「做什么·为什么·怎么撤」**并等到明确确认；P1 的默认只作用于可逆、不对外路径。
7. **P2 不打扰**，但最终交付必须可追溯（回执：做了什么/影响/下一步）。
8. **不重复确认**：已获授权的一次性批准不反复问；但不得把一次批准扩成永久授权。
9. **置信度显式**：事实（已核验：路径:行 / URL+日期）/ 推断（依据+置信度）/ 不确定（缺什么才能确定）。禁止用肯定语气包装猜测。
10. **交接/压缩/新会话前一次 Go/No-go**：brief 含目标/已定/未决/风险/资产/DoD/丢弃上下文；压缩与接力都不得静默发生。
11. **问题形态分明**：简单问题走提问工具（短、选项清楚、同批一次问完）；复杂问题/决策/边界变化用普通消息白话展开，不塞进提问工具；提问超时返回 pending 只代表没答，**不是跳过、不是同意**。

## 3.5 两条硬契约（2026-11-01，与 relay 插件协议同源）

### 验收用户门：新上下文独立审查 + 一次汇报（不靠机械）

- 声明完成/验收前：**把实现交给一个新上下文的模型做独立审查，然后把审查结论用大白话汇报给用户**。实现者自己说「没问题」不算数——自己写的实现自己看，偏移/偷懒最容易被自己合理化。不依赖工具校验——工具只能校验「写了没有」，校验不了「查没查、诚不诚实」；对不对由用户判断。
- 审查者用**新会话 / 新队友 / 新子智能体**（subagent，fresh context）。**Lead 必须给全上下文索引**：① 用户原话需求 + 最终需求/边界（逐字）；② 实现索引（file:line）+ 验证证据（测试名/命令与结果）；③ 文档/设计决策入口；④ 已知边界与未验证项。
- **审查范围 = 只做「需求 ↔ 实现」对齐**：逐条对照需求，专门找偏移/劣化/偷懒/缺失，只报事实与证据、不改代码；**不重跑技术验证、不重读第三方源码**——技术验证是实施者的责任、证据随附；上下文不够就让 Lead 补，不自己挖。
- **最多 1 轮**：P0/P1 修完只看 diff 复核；P2/P3 记录不阻塞，不开第二轮 full review；审查预算 ≤10 个工具调用 / ≤5 分钟。
- 审查结论与汇报：把审查者身份 + 发现写进 `user_gate.review`；汇报用大白话：**用户原话需求 → 实际实现 + 证据 → 独立审查结论 → 边界问题/取舍/没做到的**；发现偏差就修，或报给用户决定，不许静默写成「无」。
- relay 模式：`relay_phase({phase:'ship', user_gate:{review, report, questions?}})`——宿主只要求 `review` / `report` 非空，**不机械校验内容，也不弹审批弹窗**；审查者不是验收人（验收是用户），它只提供独立证据；`handoff` 不是验收。

### 最小人类注意力 × 最大影响

- 只在三类点打扰：**会改变用户可见结果/边界的决策**、**不可逆/P0**、**验收用户门**。
- 可查事实先自查；给用户先给结论与影响；问题批量一次问清、附推荐+默认+后果、一次一轮（不设题数上限）。
- 每 phase 最多一次非 P0 同步；同一问题不重复问；答案落盘（brief/handoff），下一会话不再问。
- 能面板点选的不出问答题；不要每 phase 问「继续吗」；P0/不可逆随时停下确认。
- **工作时自检（relay 模式硬性）**：每次 `relay_phase` 切 phase 必须写 `contract_check{requirement, fidelity, attention}`——① 需求是否已定（本阶段对应用户哪条需求、语义/边界定了没、还差什么歧义）；② 实现是否忠实（偏移/劣化/偷懒/缺失，无写「无」）；③ 注意力最小高影响（是否需要打扰用户、为何是那一次）；答不出就别切 phase。

## 4. 问题卡模板

```markdown
❓ Q1 · <一句话问题>（P0/P1，为什么现在必须问）
背景：<最多 2 句，用户缺少的上下文>
选项：
  A. <推荐> (Recommended) —— 后果：<…>
  B. <备选> —— 后果：<…>
➡️ 我的推荐：A。若你不答，我将默认 <做/不做>，影响 <…>。
```

## 5. 报备模板（P0）

```
做什么：<精确动作 + 作用对象>
为什么：<目标 + 不做的代价>
怎么撤：<回滚路径；不可撤销就明说>
附带影响：<费用/对外可见/权限/时长>
```

执行后回执：`已执行 <动作>；效果 <…>；如需撤销：<命令/步骤>`。

## 6. 反例（看见即停）

- 问用户可自查的事实（代码在哪、用量多少、接口长啥样）。
- 把可自查的事实或没想清楚的半成品问题抛给用户；问题无推荐、无默认。
- 以内部术语为主语，用户读不出「这对我意味着什么」。
- 把对话里的「好/可以」当批准；timed 超时后把 P0 动作做了。
- 每个 phase 都问「继续吗」（过度确认）。
- 子代理替人类编一个偏好当决定。
- 报备只说「已完成」，不说副作用与撤销方式。
- 用「应该/大概/众所周知」包装未查证事实。

## 7. 交付前检查清单

- [ ] 我能一句话说清「做了什么 / 影响 / 需要你什么」吗？
- [ ] 结论标了事实/推断/不确定吗？
- [ ] 要问的是决策还是可查事实？事实查过了吗？
- [ ] 要问的都是用户决策、同批一次问完？每题有推荐+默认+后果？
- [ ] 动作分级了吗？P0 停了吗？不可逆动作报备「做什么·为什么·怎么撤」并确认了吗？
- [ ] 失败回执有「原因/已发生效果/下一步」吗？
- [ ] 交接/压缩前拿到一次 Go/No-go？brief 七字段齐全吗？
- [ ] 团队场景：未决决策已结构化上收 Lead，没有队友直接问人？