ask-user

询问用户：选择闸门模式

约定

• 提供 2-4 个选项（不要更多，超过 4 个会导致决策瘫痪）。

• 始终包含一个退出选项（跳过、取消或"以上都不是"）。

• 呈现选项后立即结束本轮。不要调用后续工具，不要提前行动，不要默认选项后继续执行。

• 用户的回复会触发下一轮。简要确认，然后分支处理。

• 每条消息只问一个问题，绝不叠加多个选择闸门。

• 选项标签应当自解释：动作动词加简短限定语，而非"选项 1"。

这是什么

这是一种规范化模式，用于向用户呈现 2-4 个选项，并暂停执行直到用户作出回应。这是任何 GBrain 驱动的 Agent 中，获取用户输入闸门的标准方式。

这并非传统的 async/await。在大模型 Agent 中，"闸门"意味着：

1. 呈现选项（按钮或编号选项）
2. 明确结束当前轮次（不再继续）
3. 用户的回复触发下一轮
4. 读取回复并据此分支

适用场景

• 存在多种合理解读的模糊请求
• 破坏性操作（批量删除、覆盖）
• 归档/路由决策（"这应该放在哪里？"）
• 优先级分拣（"我应该先做哪个？"）
• 冷启动阶段闸门（"准备好导入下一个数据源了吗？"）
• 任何错误的默认选择会浪费大量工作的分叉点

不适用场景

• 指令清晰明确 → 直接执行
• 低风险决策 → 选择最佳选项并说明
• 时间紧迫、延迟代价高于错误选择代价的操作
• 用户已表达偏好时

如何呈现选项

平台无关格式（适用于所有场景）

以清晰的问题加编号或带标签的选项形式呈现：

🔀 **How should I handle this?**

[context about the decision — 1-3 lines max]

1. **Option A** — short description
2. **Option B** — short description
3. **Option C** — short description
4. **Skip** — do nothing for now

带内联按钮（Telegram、Discord、Slack）

如果平台支持交互式按钮，则使用按钮：

{
  "message": "🔀 **How should I handle this?**\n\n<context>",
  "buttons": [
    { "label": "Option A — description", "value": "option_a" },
    { "label": "Option B — description", "value": "option_b" },
    { "label": "Skip", "value": "skip" }
  ]
}

使用 clarify 工具（OpenClaw Agent）

部分 OpenClaw Agent 内置了 clarify 工具，可原生呈现选项：

clarify(
  question: "How should I handle this?",
  choices: [
    "Option A — description",
    "Option B — description",
    "Option C — description",
    "Skip for now"
  ]
)

约束

• 最多 2-4 个选项。 超过 4 个会造成决策瘫痪。
• 标签必须自解释。 用户不应需要重读上下文。
• 始终包含退出选项。 至少需要"跳过"或"取消"作为最后一个选项。
• 每条消息一个问题。 绝不叠加多个选择闸门。

如何设置闸门（关键）

呈现选项后，你必须结束本轮。 不要：

• ❌ 继续输出"在你决定期间，我先开始处理……"
• ❌ 选择默认值并继续执行
• ❌ 在用户回复前发送后续消息
• ❌ 猜测用户会选择哪个选项

应当：

• ✅ 在消息末尾简要说明你正在等待
• ✅ 停止。彻底停止。不再调用任何工具。

如何处理回复

用户回复时：

1. 读取回复：按钮点击、数字或文本
2. 简要确认："收到，按选项 A 处理。"
3. 分支并执行所选路径
4. 如果含义不清，再次询问

处理文本回复

用户有时会输入文字而非点击。应妥善处理：

• "第一个" / "A" / "1" → 映射到第一个选项
• "合并" → 与选项标签或值进行模糊匹配
• "其实都不要" → 提出替代方案，或询问用户的真实需求
• 无关消息 → 用户已转移话题，取消该闸门

格式指南

问题行表情前缀

用于标示决策类型：

• 🔀 路由/归档决策
• ⚠️ 破坏性/有风险的操作
• 🎯 优先级/分拣决策
• 💡 创意/战略分叉
• 📋 工作流/流程选择
• 🔐 凭证/安全决策

上下文块

最多 1-3 行。用户应能在 5 秒内理解该决策。

按钮/选项标签

格式：动作动词 — 简短限定语

• ✅ "合并 — 与现有页面合并"
• ✅ "新建 — 单独的会议页面"
• ❌ "选项 1"
• ❌ "点击此处将内容合并到现有 brain 页面中"

示例

冷启动阶段闸门

📋 **Phase 2: Google Contacts**

I can import your Google Contacts to seed the people/ directory.
This creates a brain page for each real contact (~200 pages).

1. **Import via ClawVisor** — secure credential gateway
2. **Import via direct OAuth** — simpler, agent holds tokens
3. **Import from Google Takeout export** — offline, from file
4. **Skip** — move to the next phase

归档决策

🔀 **Where should this go?**

Meeting notes from call with Jane Smith. She already has a page at
people/jane-smith.md and there's a deal page at deals/acme-corp.md.

1. **Merge into Jane's page** — add to her timeline
2. **Add to Acme deal page** — this was primarily a deal discussion
3. **New meeting page** — standalone at meetings/2026-01-15-jane-acme.md
4. **Skip** — don't file this

破坏性操作

⚠️ **About to delete 847 stale cache files (2.3 GB)**

These haven't been accessed in 90+ days. They can be re-fetched
but that takes ~4 hours.

1. **Delete them** — free up space now
2. **Archive first** — upload to cloud storage, then delete
3. **Keep them** — no changes
4. **Show me the list** — let me review before deciding

与其他 Skills 的集成

该模式被以下 Skills 使用：

• cold-start — 每个导入来源的阶段门控
• ingest — 对有歧义内容的路由决策
• enrich — 实体页面的合并与新建决策
• brain-ops — 归档位置决策
• meeting-ingestion — 会议纪要的归档位置
• archive-crawler — 扫描与完整导入的门控

在构建需要用户在决策点输入的新 Skill 时，请引用此模式，而不是另行设计一套。

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循 agent operator protocol。针对本 Skill 的特定说明：

• 如果某次 gbrain 调用以退出码 3（confirmation_required）结束，或其 fix.next 为 ask_user：本 Skill 即为门控。请将 [SHOW USER] 块或 user_message 原样转达给用户作为选项，然后停止，等待用户作答。
• 如果用户回答"否"或未作答：将该步骤报告为已跳过。切勿代替用户传入 --yes 或 --max-usd 以继续推进。

反模式

• 呈现选项后继续执行当前回合。 例如"你决定的同时，我先开始处理……"会让门控失效。应当停止，等待。整个设计的意义在于由用户掌控接下来发生的事。
• 擅自选择默认值并静默继续。 如果某个问题重要到需要询问，就重要到需要等待。静默默认值会在你下次询问时侵蚀用户的信任。
• 选项超过 4 个。 选择困难是真实存在的。应当分组、概括，或拆分为分阶段的问题。
• 没有退路。 每个选择门控都必须允许用户拒绝。必须提供"以上都不是"/"跳过"/"取消"之类的选项。
• 在一条消息中堆叠多个选择门控。 用户每个回合只能回答一个问题。多问题门控要么只被部分回答，要么被完全忽略。
• 模糊的选项标签。 "选项 1"迫使用户回头重读上下文。"合并到现有页面"则一目了然。
• 询问低风险决策。 如果选错的代价很小，就直接选最佳选项并说明即可。门控应保留给返工成本高昂的分叉点。

输出格式

该 Skill 的"输出"就是选择门控消息本身，结构如下：

{emoji-prefix} **{question}**

{1-3 lines of context}

1. **{Option A label}** — {short qualifier}
2. **{Option B label}** — {short qualifier}
3. **{Skip / Cancel}** — {what skipping means}

发出此消息后，Skill 结束当前回合。在用户回应之前，不再进行任何工具调用、不做任何预先操作，也不发送后续消息。用户的回应将触发下一回合，届时调用方 Skill 会根据所选选项进行分支处理。