Back to Details

ask-user

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Ask User — Choice Gate Pattern

向用户询问——Choice Gate 模式

Contract

规范

  • Present 2-4 options (no more — decision paralysis kicks in past 4).
  • Always include an escape hatch (Skip, Cancel, or "none of these").
  • Stop the turn immediately after presenting choices. No follow-up tool calls, no preemptive action, no default-and-proceed.
  • The user's response triggers the next turn. Acknowledge briefly, then branch.
  • One question per message — never stack multiple choice gates.
  • Self-explanatory option labels: action verb plus brief qualifier, not "Option 1".
  • 展示2-4个选项（最多4个——超过4个会引发决策瘫痪）。
  • 始终提供一个退出选项（跳过、取消或“以上都不是”）。
  • 展示选项后立即终止当前轮次。不进行后续工具调用，不采取预先行动，不默认执行。
  • 用户的响应触发下一轮次。先简要确认，再分支执行。
  • 每条消息仅包含一个问题——切勿堆叠多个选择门。
  • 选项标签需自解释：动作动词加简短限定词，而非“选项1”。

What This Is

模式定义

A formalized pattern for presenting users with 2-4 options and stopping execution until they respond. This is the canonical way to gate on user input in any GBrain-powered agent.
This is NOT a traditional async/await. In an LLM agent, "gating" means:
  1. Present the choices (buttons or numbered options)
  2. Explicitly stop the current turn (do not proceed)
  3. The user's response triggers the next turn
  4. Read the response and branch accordingly
这是一种规范化模式，用于向用户展示2-4个选项并暂停执行，直至用户做出响应。这是在任何基于GBrain的Agent中，通过用户输入控制流程的标准方式。
这并非传统的异步/等待机制。在LLM Agent中，“流程控制（gating）”意味着：
  1. 展示选项（按钮或编号选项）
  2. 明确终止当前轮次（不继续执行）
  3. 用户的响应触发下一轮次
  4. 读取响应并相应分支执行

When To Use

使用场景

  • Ambiguous requests with multiple valid interpretations
  • Destructive operations (bulk deletes, overwrites)
  • Filing/routing decisions ("where should this go?")
  • Priority triage ("which should I do first?")
  • Cold-start phase gates ("ready for the next import source?")
  • Any fork where the wrong default wastes significant work
  • 存在多种合理解读的模糊请求
  • 破坏性操作（批量删除、覆盖）
  • 归档/路由决策（“这个应该放在哪里？”）
  • 优先级排序（“我应该先做哪件事？”）
  • 冷启动阶段的流程控制（“准备好进行下一个数据源导入了吗？”）
  • 任何错误默认选项会导致大量无效工作的分支点

When NOT To Use

不适用场景

  • Clear, unambiguous instructions → just do it
  • Low-stakes decisions → pick the best option and mention it
  • Time-critical operations where delay costs more than a wrong choice
  • When the user has already expressed a preference
  • 清晰明确的指令→直接执行即可
  • 低风险决策→选择最优选项并告知用户
  • 时间敏感型操作，延迟的代价大于错误选择的代价
  • 用户已明确表达偏好的情况

How To Present Choices

选项展示方式

Platform-agnostic format (works everywhere)

平台通用格式（适用于所有平台）

Present choices as a clear question with numbered or labeled options:
🔀 **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
以清晰的问题搭配编号或标签选项的形式展示：
🔀 **我该如何处理这件事？**

[决策相关上下文——最多1-3行]

1. **选项A** — 简短描述
2. **选项B** — 简短描述
3. **选项C** — 简短描述
4. **跳过** — 暂时不做任何操作

With inline buttons (Telegram, Discord, Slack)

内置按钮形式（Telegram、Discord、Slack）

If the platform supports interactive buttons, use them:
json
{
  "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" }
  ]
}
如果平台支持交互式按钮，可使用以下形式：
json
{
  "message": "🔀 **我该如何处理这件事？**\n\n<context>",
  "buttons": [
    { "label": "Option A — description", "value": "option_a" },
    { "label": "Option B — description", "value": "option_b" },
    { "label": "Skip", "value": "skip" }
  ]
}

With the 
clarify
tool (OpenClaw agents)

使用
clarify
工具（OpenClaw Agent）

Some OpenClaw agents have a built-in 
clarify
tool that presents choices natively:
clarify(
  question: "How should I handle this?",
  choices: [
    "Option A — description",
    "Option B — description",
    "Option C — description",
    "Skip for now"
  ]
)
部分OpenClaw Agent内置了
clarify
工具，可原生展示选项：
clarify(
  question: "How should I handle this?",
  choices: [
    "Option A — description",
    "Option B — description",
    "Option C — description",
    "Skip for now"
  ]
)

Constraints

约束条件

  • 2-4 options max. More than 4 creates decision paralysis.
  • Labels must be self-explanatory. The user shouldn't need to re-read context.
  • Always include an escape hatch. At minimum: "Skip" or "Cancel" as the last option.
  • One question per message. Never stack multiple choice gates.
  • 最多2-4个选项。超过4个会引发决策瘫痪。
  • 标签必须自解释。用户无需重新阅读上下文即可理解。
  • 始终提供退出选项。至少包含：“跳过”或“取消”作为最后一个选项。
  • 每条消息仅一个问题。切勿堆叠多个选择门。

How To Gate (CRITICAL)

流程控制方法（至关重要）

After presenting choices, you MUST stop your turn. Do not:
  • ❌ Continue with "while you decide, I'll start on..."
  • ❌ Pick a default and proceed
  • ❌ Send follow-up messages before the user responds
  • ❌ Make assumptions about which option they'll pick
Instead:
  • ✅ End your message with a brief note that you're waiting
  • ✅ Stop. Full stop. No more tool calls.
展示选项后，必须终止当前轮次。禁止：
  • ❌ 继续执行“在您决策期间，我将开始……”
  • ❌ 选择默认选项并继续执行
  • ❌ 在用户响应前发送后续消息
  • ❌ 假设用户会选择哪个选项
正确做法：
  • ✅ 在消息末尾简要说明正在等待用户响应
  • ✅ 终止轮次。完全停止。不再进行任何工具调用。

How To Handle The Response

响应处理方式

When the user responds:
  1. Read the response — button click, number, or text
  2. Acknowledge briefly — "Got it, going with Option A."
  3. Branch and execute the chosen path
  4. If unclear, ask again
当用户做出响应时：
  1. 读取响应——按钮点击、编号或文本
  2. 简要确认——“收到，将执行选项A。”
  3. 分支执行所选路径
  4. 若响应不明确，再次询问

Handling text responses

文本响应处理

Users sometimes type instead of clicking. Handle gracefully:
  • "the first one" / "A" / "1" → map to first option
  • "merge" → fuzzy match against option labels/values
  • "actually, none of those" → present alternatives or ask what they want
  • Unrelated message → the user moved on; drop the gate
用户有时会输入文本而非点击按钮。需灵活处理：
  • “第一个”/“A”/“1”→映射到第一个选项
  • “合并”→模糊匹配选项标签/值
  • “实际上，以上都不是”→展示替代选项或询问用户需求
  • 无关消息→用户已转移注意力，放弃当前选择门

Formatting Guidelines

格式指南

Question line emoji prefix

问题行表情前缀

Signal the decision type:
  • 🔀 Routing/filing decisions
  • ⚠️ Destructive/risky operations
  • 🎯 Priority/triage decisions
  • 💡 Creative/strategic forks
  • 📋 Workflow/process choices
  • 🔐 Credential/security decisions
用表情标识决策类型：
  • 🔀 路由/归档决策
  • ⚠️ 破坏性/高风险操作
  • 🎯 优先级/排序决策
  • 💡 创意/策略分支
  • 📋 工作流/流程选择
  • 🔐 凭证/安全决策

Context block

上下文块

1-3 lines maximum. The user should understand the decision in under 5 seconds.
最多1-3行。用户应在5秒内理解决策内容。

Button/option labels

按钮/选项标签

Format: 
Action verb — brief qualifier
  • ✅ "Merge — combine with existing page"
  • ✅ "Create new — separate meeting page"
  • ❌ "Option 1"
  • ❌ "Click here to merge the content into the existing brain page"
格式：
动作动词 — 简短限定词
  • ✅ “合并 — 与现有页面合并”
  • ✅ “新建 — 创建独立会议页面”
  • ❌ “选项1”
  • ❌ “点击此处将内容合并到现有brain页面”

Examples

示例

Cold-start phase gate

冷启动阶段流程控制

📋 **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
📋 **阶段2：Google联系人**

我可以导入您的Google联系人以填充people/目录。
这将为每个真实联系人创建一个brain页面（约200个页面）。

1. **通过ClawVisor导入** — 安全凭证网关
2. **通过直接OAuth导入** — 更简便，Agent持有令牌
3. **通过Google Takeout导出文件导入** — 离线模式，从文件导入
4. **跳过** — 进入下一阶段

Filing decision

归档决策

🔀 **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
🔀 **这个应该放在哪里？**

与Jane Smith的会议记录。她已有一个页面位于people/jane-smith.md，同时有一个交易页面位于deals/acme-corp.md。

1. **合并到Jane的页面** — 添加到她的时间线
2. **添加到Acme交易页面** — 本次主要是交易讨论
3. **新建会议页面** — 独立存储于meetings/2026-01-15-jane-acme.md
4. **跳过** — 暂不归档

Destructive operation

破坏性操作

⚠️ **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
⚠️ **即将删除847个过期缓存文件（2.3 GB）**

这些文件已90多天未被访问。可重新获取，但耗时约4小时。

1. **删除文件** — 立即释放空间
2. **先归档** — 上传至云存储后再删除
3. **保留文件** — 不做任何更改
4. **查看列表** — 让我先审核再决定

Integration With Other Skills

与其他技能的集成

This pattern is used by:
  • cold-start — phase gates for each import source
  • ingest — routing decisions for ambiguous content
  • enrich — merge vs create decisions for entity pages
  • brain-ops — filing location decisions
  • meeting-ingestion — where to file meeting notes
  • archive-crawler — scan vs full ingestion gate
When building a new skill that needs user input at a decision point, reference this pattern rather than inventing a new one.
该模式被以下技能使用：
  • cold-start — 每个数据源导入阶段的流程控制
  • ingest — 模糊内容的路由决策
  • enrich — 实体页面的合并与创建决策
  • brain-ops — 归档位置决策
  • meeting-ingestion — 会议记录的归档位置决策
  • archive-crawler — 扫描与完整导入的流程控制
当构建需要在决策点获取用户输入的新技能时，请参考此模式，而非自行创建新模式。

Anti-Patterns

反模式

  • Continuing the turn after presenting choices. "While you decide, I'll start on..." defeats the gate. Stop. Wait. The whole point is that the user controls what happens next.
  • Picking a default and proceeding silently. If the question matters enough to ask, it matters enough to wait. Silent defaults erode trust the next time you do ask.
  • More than 4 options. Decision paralysis is real. Group, summarize, or split into staged questions instead.
  • No escape hatch. Every choice gate must let the user decline. "None of these" / "Skip" / "Cancel" is mandatory.
  • Stacking multiple choice gates in one message. The user can only answer one question per turn. Multi-question gates either get half-answered or dropped entirely.
  • Cryptic option labels. "Option 1" forces re-reading the context. "Merge into existing page" is self-explanatory.
  • Asking about low-stakes decisions. If the wrong answer costs nothing, just pick the best option and mention it. Reserve gates for forks where rework is expensive.
  • 展示选项后继续当前轮次。“在您决策期间，我将开始……”会破坏流程控制的作用。终止轮次，等待用户响应。核心在于用户控制后续操作。
  • 静默选择默认选项并执行。如果问题值得询问，就值得等待。静默默认选项会在下次询问时削弱用户信任。
  • 超过4个选项。决策瘫痪是真实存在的。可分组、汇总或拆分为多阶段问题。
  • 无退出选项。每个选择门必须允许用户拒绝。“以上都不是”/“跳过”/“取消”是必填项。
  • 在一条消息中堆叠多个选择门。用户每轮只能回答一个问题。多问题选择门要么只得到部分回答，要么被完全忽略。
  • 模糊的选项标签。“选项1”会迫使用户重新阅读上下文。“合并到现有页面”是自解释的。
  • 询问低风险决策。如果错误答案无任何代价，直接选择最优选项并告知用户。仅在分支点错误选择会导致大量返工的情况下使用选择门。

Output Format

输出格式

The skill's "output" is the choice-gate message itself, structured as:
{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}
After emitting this, the skill stops the turn. No further tool calls, no preemptive action, no follow-up message until the user responds. The user's response triggers the next turn, where the calling skill branches on the chosen option.
技能的“输出”即为选择门消息本身，结构如下：
{表情前缀} **{问题}**

{1-3行上下文}

1. **{选项A标签}** — {简短限定词}
2. **{选项B标签}** — {简短限定词}
3. **{跳过/取消}** — {跳过的含义}
输出该消息后，技能终止当前轮次。不再进行任何工具调用，不采取预先行动，在用户响应前不发送后续消息。用户的响应触发下一轮次，调用该技能的主体将根据所选选项分支执行。