user-input-protocol

用户输入协议

价值观： 尊重——开发者的判断决定所有重大决策。Agent 不会在应该询问时自行假设。

目的

定义一种结构化格式，让 Agent 在决策节点请求人工输入。避免 Agent 代替开发者做出假设，确保问题包含足够的背景信息，便于做出明智决策，并为无法直接向用户提问的子 Agent 提供暂停和恢复模式。

实践

停下来并呈现问题，绝不自行假设

遇到需要人工判断的决策时，立即停止工作。不要猜测，不要选择“最有可能”的选项。清楚地呈现决策并等待回复。

需要人工输入的决策：

• 业务规则存在歧义（有两种有效的解释）
• 架构权衡（性能与简洁性等）
• 范围问题（此功能是否应包含 X？）
• 破坏性操作（删除文件、强制推送、删除数据）

不需要人工输入的决策：

• 有一个明确正确答案的实现细节
• 项目惯例已涵盖的格式、命名或风格选择
• 需求明确时的测试结构

使用 AWAITING_USER_INPUT 格式

需要输入时，输出以下结构化检查点：

AWAITING_USER_INPUT
---
Context: [Why you are asking -- what you were doing and what you found]
Decision needed: [The specific question, one sentence]
Options:
  A) [Label] -- [What this means and its implications]
  B) [Label] -- [What this means and its implications]
  C) [Label] -- [What this means and its implications]
Recommendation: [Which option you suggest and why, or "No recommendation"]
---

检查点规则：

• 背景信息必须说明问题的由来（不能只说“我需要输入”）
• 提供 2-4 个具体选项。绝不要问开放式问题，例如“我该怎么办？”
• 每个选项都必须说明影响，而不只是标签
• 如果有建议，请说明——开发者可以选择其他方案

示例：

AWAITING_USER_INPUT
---
Context: While implementing the login endpoint, I found two email validation
patterns in the codebase. auth/validate.rs uses strict RFC 5322 parsing.
signup/forms.rs uses a simple regex check. These produce different results
for edge cases like "[email protected]".
Decision needed: Which email validation approach should be the project standard?
Options:
  A) Strict RFC 5322 -- rejects fewer valid addresses, more complex to maintain
  B) Simple regex -- faster, but may accept malformed addresses
  C) Context-dependent -- strict for auth, lenient for forms
Recommendation: A) Strict RFC 5322, applied everywhere for consistency
---

暂停前保存状态（子 Agent）

子 Agent 和后台任务通常无法直接向用户提问。 当子 Agent 需要输入时，必须在暂停前保存进度，以便恢复工作时无需从头开始。

暂停前需要保存的状态：

1. 正在执行的任务
2. 创建或修改的文件
3. 已完成的分析
4. 阻碍工作的具体决策
5. 恢复时能够立即继续所需的背景信息

保存状态的位置取决于所用工具：

• 任务元数据（Claude Code：使用 TaskUpdate 设置元数据）
• 文件系统（将 JSON 检查点写入临时文件）
• 记忆工具（如果可用，则使用 MCP 服务）

保存状态后，输出 AWAITING_USER_INPUT 检查点并停止。 编排器或主对话会检测到暂停，向用户提出问题，并在收到答案后恢复子 Agent。

恢复时无需重做工作

收到用户答复并恢复后：

1. 取回已保存的状态
2. 确认文件和背景信息齐备
3. 应用用户的决定
4. 从暂停处继续

不要重新分析已经分析过的文件。不要重新阅读已经保存的背景信息。保存状态的目的，是让恢复过程立即完成。

应该：

• “你选择了严格遵循 RFC 5322。我现在将其应用于登录端点。”

不应该：

• “让我重新分析代码库，以了解电子邮件验证……”

工厂模式下的批量决策

在流水线或工厂工作流中运行时，避免每次遇到决策都阻塞流水线。对每项决策进行分类并按相应方式处理：

• 门禁可解决： 切勿询问人工。质量门禁会给出答案（测试通过／失败、变异分数、CI 状态）。这些决策完全自动化。
• 需要判断： 汇总到下一轮人工审查。示例：审查期间发现的设计权衡、需要确定优先级的非阻塞审查发现、回顾建议。
• 阻塞： 立即暂停流水线。示例：审查期间提出的安全问题、经过 3 轮返工后仍无法恢复的门禁失败、影响正确性的模糊需求。

门禁可解决的决策绝不会出现在 AWAITING_USER_INPUT 检查点中。需要判断的决策会汇总起来，并在人工审查阶段作为一个检查点统一呈现。阻塞决策会立即使用标准 AWAITING_USER_INPUT 格式。

在工厂模式下发出 AWAITING_USER_INPUT 时，请在分隔符后添加 urgency 字段：

AWAITING_USER_INPUT
---
Urgency: blocking | next-review | informational
Context: ...
Decision needed: ...
Options: ...
Recommendation: ...
---

• blocking —— 流水线已暂停，需要立即处理
• next-review —— 汇总到下一次计划中的人工审查
• informational —— 无需采取行动，仅供知悉

独立使用的用户可以忽略 urgency 字段；检查点格式仍向后兼容。

处理包含多个问题的检查点

需要处理多个相关决策时，请将它们归为一个检查点，而不是反复暂停。为每个问题编号。

AWAITING_USER_INPUT
---
Context: Setting up the test infrastructure for the new auth module.
Decisions needed:

1. Test framework?
   A) Jest -- already used in 3 other modules
   B) Vitest -- faster, but would introduce a second test runner
   Recommendation: A) Jest for consistency

2. Test file location?
   A) Colocated (auth/__tests__/) -- matches signup module pattern
   B) Top-level (tests/auth/) -- matches API module pattern
   Recommendation: A) Colocated, to match the newer module convention
---

执行说明

• 独立模式：仅作建议。Agent 自行遵守暂停规则。
• 流水线模式：结构性要求。AWAITING_USER_INPUT 会将流水线状态写入磁盘，并暂停当前 Agent。

硬性约束：

• 判断决策需要人工输入：[RP]

约束

• “立即停止，不要猜测”：“停止”是指停止当前决策路径，不一定要停止所有工作。如果其他无关工作可以继续，就继续。但不要推进需要该决策的路径——甚至不要“准备”假设某个选项成立的代码。准备本身就是决策。
• “2-4 个具体选项”：选项必须是真正不同的替代方案，而不是同一种方案的不同变体。“使用库 A”“使用带选项 X 的库 A”“使用带选项 Y 的库 A”实际上是一个带有配置选择的选项，而不是三个选项。每个选项都应代表一条有实质区别的路径。

验证

应用此技能后，请验证：

• 每项需要人工判断的决策都使用了 AWAITING_USER_INPUT 格式
• 每个检查点都包含上下文、说明影响的选项以及建议
• 没有提出开放式问题（“我该怎么办？”）
• 子 Agent 在暂停前保存了状态
• 恢复工作时使用已保存的状态，没有重新分析
• 相关决策已归为单个检查点

依赖项

此技能可独立使用。对于增强型工作流，它可与以下内容集成：

• tdd： 测试要求不明确时，暂停并澄清验收标准。在自动化模式下，协调器会检测已暂停的子 Agent，并将问题转达给用户。
• debugging-protocol： 调试发现根本原因不明确时，暂停并询问

缺少依赖项？使用以下命令安装：

npx skills add jwilger/agent-skills --skill tdd