Ask User Questions MCP

AUQ Demo

AUQ-向用户提问

_AskUserQuestion 推到最大_

](https://www.npmjs.com/package/auq-mcp-server)  

一个完整的工具集，可以在任何长时间运行的多代理AI工作流（如Ralph loop！）上实现最大程度的人类（意图）循环。

单选/多选题、自定义选项、多智能体互操作性、问题排队、带解释的问题拒绝、细化请求、快速推荐自动选择、主题、本地操作系统通知、终端进度条、多语言支持、智能体技能支持。..以及更多。你也可以自定义它们！

可以通过MCP服务器/OpenCode插件/Agent Skills使用。

设置 • 用法

🤔 我在CC/OC/Cursor中已经有了提问工具。为什么要用这个？

______________________________________________________________________

它有什么作用？

AUQ让你的AI助手 提出澄清性问题 在编码或工作时，由多项选择题/单选题组成（带有“其他”选项用于自定义输入/拒绝/要求详细说明），以及 等待您的答复 通过一个 单独的CLI窗口 而不会打乱你的工作流程。

这可以让你注射你的 意图 进入长时间运行的自主人工智能任务——不再切换窗口或照看人工智能。打开CLI 随时，甚至 通过SSH远程!

A no no fun background story

在人工智能辅助编码中，指导LLM提问 澄清性问题 已被广泛认为是一种强大的快速工程技术，可以克服LLM幻觉并生成更符合上下文的代码\[1\]。

10月18日，克劳德代码2.0.21引入了内部 AskUserQuestion 工具。受到启发，我决定构建一个类似的工具，它是：

• 集成灵活 -与MCP客户端（Claude Desktop、Cursor等）配合使用，并具有官方的OpenCode插件支持
• 非侵入性 -不与您的编码CLI工作流深度集成，也不占用UI空间
• 多代理友好 -支持在并行工作流中同时接收来自多个代理的问题

______________________________________________________________________

✨ 演示

______________________________________________________________________

安装说明

🚀 安装CLI工具

首先，安装 AUQ-CLI:

全局安装（推荐）

Bun（推荐使用——默认OpenTUI渲染器需要）

bun add -g auq-mcp-server

npm

npm install -g auq-mcp-server

pnpm

pnpm add -g auq-mcp-server

纱线

yarn global add auq-mcp-server

注： 建议将Bun用于默认的OpenTUI渲染器。当通过npm/pnpm/yarn安装时，shell包装器会在运行时自动检测Bun。如果Bun不可用，它将使用旧版Ink渲染器回退到Node.js。

Local (Project-specific) Installation

# Install in your project
bun add auq-mcp-server

会话已存储 全球范围内 无论安装方法如何。看 故障排除 对于会议地点。

______________________________________________________________________

🔌 与您的AI集成

AUQ支持多种AI环境。选择 OpenCode插件 和 MCP服务器.

选项A:MCP服务器

_注意：由于某些MCP客户端的实现方式存在差异，在不允许延长全局MCP超时的工具中，AUQ可能会被强制取消。如果是这样的话，考虑使用 代理技能.使用 OpenCode插件 如果你使用OpenCode。_

Cursor


Claude Code

方法1：使用CLI （推荐）

claude mcp add --transport stdio ask-user-questions -- bunx -y auq-mcp-server server

注： npx 如果你更喜欢npm，也可以。

方法2：手动配置

添加 .mcp.json 在项目根目录中（用于全团队共享）：

{
  "mcpServers": {
    "ask-user-questions": {
      "type": "stdio",
      "command": "bunx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

或添加到 ~/.claude.json 用于所有项目的全球访问。

_注： 替换 bunx 如果你不使用包子。_

验证设置： 类型 /mcp 在Claude Code中检查服务器状态。

Codex CLI

添加 ~/.codex/config.toml:

[mcp_servers.ask-user-questions]
command = "bunx"
args = ["-y", "auq-mcp-server", "server"]
tool_timeout_sec = 99999  // Extend timeout for long sessions

Claude Desktop

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "ask-user-questions": {
      "command": "bunx",
      "args": ["-y", "auq-mcp-server", "server"]
    }
  }
}

_替换 bunx 如果你不使用包子。_

重新启动克劳德桌面 保存后。

选项B：OpenCode插件

直接集成 对于OpenCode用户。专门添加工作目录可见性功能。

配置

添加 opencode.json:

{
  "plugin": ["@paulp-o/opencode-auq@latest"]
}

选项C：代理技能（实验）

与技能兼容的代理一起使用

复制 skills/ask-user-questions/ 文件夹到代理的技能目录。

Limitations

该技能指导AI使用AUQ CLI的隐藏命令， auq ask 使用原始JSON作为参数。与MCP或 _适当的_ 本机不支持工具线束系统、格式错误的JSON修复/模式强制；因此，能力较弱的模型可能很难正确调用。

______________________________________________________________________

💻 用法

启动CLI工具

auq       # if installed globally (bun add -g)
# bunx auq
# npx auq

首先，定义您的工作流程，使用AUQ工具澄清问题 AGENTS.md （或 CLAUDE.md)，例如：

Whenever you need clarification on what you are working on, never guess, and call AUQ(ask-user-questions).

当AI问问题时，你会看到它们出现在AUQ TUI中。回答他们 在您方便的时候.

渲染器选择

AUQ支持两个终端渲染引擎：

OpenTUI是默认渲染器，需要 包子 运行时。当Bun不可用时，AUQ会自动回退到Ink渲染器。

强制使用特定渲染器，设置以下选项之一（按优先级顺序）：

1. 环境变量 （最高优先级）：

   AUQ_RENDERER=ink auq    # force ink
   AUQ_RENDERER=opentui auq  # force opentui

1. 配置文件 (.auqrc.json):

   {
     "renderer": "ink"
   }

1. CLI命令:

   auq config set renderer ink

注： OpenTUI提供原生CJK字符支持、内置带语法高亮显示的markdown渲染和鼠标支持。外壳包装(bin/auq)自动在运行时检测Bun。

Markdown渲染问题提示

问题提示现在支持 Markdown 格式 在 prompt 文本。

• 支持： 大胆, _斜体_，~~删除线~~， inline code、链接和围栏代码块（带语法突出显示）
• 链接呈现为 text (url) 用于广泛的终端兼容性
• 代码块使用主题感知颜色（背景/文本/边框）
• 始终启用（无需配置）
• 纯文本提示传递不变
• 优雅的回退：如果Markdown解析失败，则显示原始文本

_注意：AUQ是一个未经验证的工具，不包括以下提示 如何 人工智能应该利用它。预计你会做自己的快速工程，以便在自己的工作流程中充分利用它。_ _我个人喜欢在行动前反复提示它至少问30个问题！_

推荐设置

建议 禁用 您工具中的内置提问工具（如 question OpenCode中的工具或 AskUserQuestion 在Claude Code中），以避免AI将它们混淆。

有用的键盘快捷键

鼠标支持（仅限OpenTUI渲染器）：

⌨️ All Keyboard Shortcuts

More Commands (advanced)

# you won't likely need these at all
auq server       # Start MCP server
auq --version    # Show version
auq update       # Check for and install updates
auq --help       # Show help

______________________________________________________________________

📋 Full CLI Reference

命令行命令

AUQ提供无头CLI命令，用于在没有TUI的情况下管理会话和配置。 跑 auq --help 以供完整参考。

答疑环节

auq answer  --answers '{"0": {"selectedOption": "option1"}}'
auq answer  --answers '{"0": {"selectedOptions": ["A", "B"]}}'  # multi-select
auq answer  --answers '{"0": {"customText": "free text"}}'  # custom text
auq answer  --reject --reason "Not applicable"
auq answer  --answers '...' --force  # abandoned session
auq answer  --answers '...' --json

管理会话

auq sessions list                    # pending sessions (default)
auq sessions list --stale             # stale sessions only
auq sessions list --all               # all sessions
auq sessions show          # session details
auq sessions dismiss       # dismiss stale session
auq sessions dismiss  --force
auq sessions list --limit 10 --page 2 # pagination
auq sessions list --json

会话历史记录

auq history                           # list session history
auq history --all                     # include abandoned
auq history --unread                  # unread only
auq history --search "deploy"          # search
auq history --limit 10 --page 2       # pagination
auq history show           # full Q&A detail
auq history --json

获取答案（程序化）

auq fetch-answers --unread            # list unread answered sessions
auq fetch-answers          # fetch specific session
auq fetch-answers  --blocking  # wait until answered
auq fetch-answers --limit 10 --page 2
auq fetch-answers --json

配置

auq config get                        # view all
auq config get staleThreshold         # view specific
auq config set staleThreshold 3600000 # set local
auq config set staleThreshold 3600000 --global  # set global

更新

auq update        # interactive update check
auq update -y     # skip confirmation

分页

列出命令(sessions list, history, fetch-answers)支持：

• --limit --每页最大项目数（默认值：20）
• --page --页码（默认值：1）

🌍 Environment Variables

停滞会话检测

未应答的会话超过配置的阈值将被标记为“过时”（可能是孤立的）。这有助于识别AI可能已断开连接或超时的会话。

• 视觉指示器：陈旧的会话显示⚠ TUI中的警告图标和黄色突出显示
• 吐司通知：当会话过时时会出现通知（可配置）
• 宽限期：与过时的会话交互提供30分钟的宽限期
• 可配置阈值：默认值为2小时（7200000毫秒）

______________________________________________________________________

放弃会话处理

当AI客户端断开连接时，相关会话将标记为“放弃”。这些会议：

• 通过红色指示灯在TUI中保持可见
• Show a confirmation dialog before answering（“AI已断开连接”）
• 仍然可以通过CLI回答 --force 旗帜
• 可通过以下方式检测 auq sessions list --all

______________________________________________________________________

自动更新

AUQ会自动检查更新并保持最新状态。

运作原理

• 所有更新 （补丁、次要、主要）：全屏覆盖显示更改日志和更新、跳过或推迟的选项。
• 更新检查：每次TUI启动时运行（无延迟/缓存）。
• CLI通知：运行非TUI命令时，如果有新版本可用，则会显示一行更新通知。

手动更新

跑 auq update 要手动检查并安装更新，请执行以下操作：

auq update        # Interactive update check
auq update -y     # Skip confirmation prompt

禁用更新检查

通过配置禁用自动更新检查：

auq config set updateCheck false

或者设置环境变量：

NO_UPDATE_NOTIFIER=1 auq ask "question"

CI环境中会自动禁用更新检查(CI=true).

这 auq update 无论这些设置如何，命令始终有效。

主题系统

AUQ支持 16个内置颜色主题 具有自动持久性。按 Ctrl+T 循环浏览主题。

渲染器主题差异

两个渲染器都支持所有16个内置主题和自定义主题。颜色一致；只有实现细节不同。

Built-in Themes

您选择的主题是 自动保存 到 ~/.config/auq/config.json 并在下次发射时恢复。

Custom Themes

通过放置来创建自定义主题 .theme.json 文件位于：

• macOS/Linux: ~/.config/auq/themes/

自定义主题示例(~/.config/auq/themes/my-theme.theme.json):

{
  "name": "my-theme",
  "colors": {
    "primary": "#ff6b6b",
    "success": "#51cf66",
    "text": "#f8f9fa"
  }
}

自定义主题继承自默认的深色主题，仅覆盖您想要更改的颜色。请参阅 JSON 模式 对于所有可用的房产。

______________________________________________________________________

手动会话清理

会话在保留期后自动清理。但是，如果你愿意，你可以手动清理它们。

rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
rm -rf ~/.local/share/auq/sessions/*                  # Linux

______________________________________________________________________

Local Development & Testing

要在开发过程中本地测试MCP服务器和CLI：

1.启动MCP服务器（终端1）

# Option A: Run with tsx (recommended for development)
bun run start

# Option B: Run with fastmcp dev mode (includes web inspector at http://localhost:6274)
bun run dev

# Option C: Run the built version
bun run build && bun run server

2.创建测试会话（终端2）

使用 auq ask 创建会话并等待答案的命令：

# Run directly with bun during development
bun run bin/auq.tsx ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript"}, {"label": "Python"}], "multiSelect": false}]}'

# Or pipe JSON to stdin
echo '{"questions": [{"prompt": "Which database?", "title": "DB", "options": [{"label": "PostgreSQL"}, {"label": "MongoDB"}], "multiSelect": false}]}' | bun run bin/auq.tsx ask

这将创建一个会话，并等待TUI提供答案。

3.通过TUI（终端3）进行回答

# Run the TUI to answer pending questions
bun run bin/auq.tsx

为TUI测试创建模拟会话

要使用多个挂起的会话测试TUI：

# Create 3 mock sessions (default)
bun run scripts/create-mock-session.ts

# Create a specific number of sessions
bun run scripts/create-mock-session.ts 5

然后运行TUI查看并回答这些问题：

bun run bin/auq.tsx

验证MCP和CLI使用相同的会话目录

两个组件应报告相同的会话目录路径。检查日志：

• MCP服务器在启动时记录会话目录
• auq ask 打印 `[AUQ] Session directory:

` 到stderr

在macOS上，两者都应该使用： ~/Library/Application Support/auq/sessions

开发命令

# Regenerate the skill from source
bun run generate:skill

# Validate skill structure and content
bun run validate:skill

Troubleshooting

会话存储

会话存储在特定于平台的全局位置：

• macOS: ~/Library/Application Support/auq/sessions
• Linux: ~/.local/share/auq/sessions （或 $XDG_DATA_HOME/auq/sessions)
• 视窗: %APPDATA%\auq\sessions

_可定制 AUQ_SESSION_DIR 环境变量。_

Configuration

AUQ可以通过以下方式配置 .auqrc.json 文件。设置从以下位置加载（按优先级顺序）：

1. 本地: ./.auqrc.json （项目目录）
2. 全球: ~/.config/auq/.auqrc.json （或 $XDG_CONFIG_HOME/auq/.auqrc.json)
3. 默认值：内置价值

_本地配置中的设置会覆盖全局配置，而全局配置会覆盖默认值。_

默认配置

{
  "renderer": "opentui",
  "maxOptions": 5,
  "maxQuestions": 5,
  "recommendedOptions": 4,
  "recommendedQuestions": 4,
  "sessionTimeout": 0,
  "retentionPeriod": 604800000,
  "language": "auto",
  "theme": "system",
  "autoSelectRecommended": true,
  "updateCheck": true,
  "notifications": {
    "enabled": true,
    "sound": true
  }
}

Available Settings

语言支持

AUQ支持TUI接口的多种语言：

• 英语 (en)-默认值
• 韩语 (ko）-韩语

从系统区域设置中自动检测语言(LANG, LC_ALL, LC_MESSAGES 环境变量）设置为 "auto".

桌面提醒

AUQ使用本机桌面通知在新问题到达时提醒您。

平台要求

如果需要，可以在配置中禁用通知。

特征：

• 批量通知：快速会话到达被批量处理为单个通知
• 进度条：在终端停靠图标中显示问题完成进度（支持iTerm2和WezTerm等终端）
• 原生集成：使用系统本机通知中心

配置：

{
  "notifications": {
    "enabled": true,
    "sound": true
  }
}

• notifications.enabled （默认值： true)：启用桌面通知
• notifications.sound （默认值： true)：播放带有通知的声音

集 notifications.enabled 到 false 禁用所有通知。

______________________________________________________________________

🤔 为什么AUQ与内置提问工具相比？

一个干净的决策收件箱，让你和AI保持流畅。

你是一个AI高级用户，在多个实例上运行多个代理。高度并行化，人工智能在多个线程上同时向你提问——分散在不同的窗口中。AUQ使他们能够提问 随时，收集所有内容 一个收件箱，并允许您进行响应 根据你自己的条件--然后优雅地将答案路由回每个代理。

       Claude Code    Cursor    OpenCode
            │           │           │
            ▼           ▼           ▼
          ┌─────────────────────────────┐
          │        📥 AUQ Inbox         │
          └─────────────────────────────┘
                        │
                        ▼
                      🖥️ TUI
                        │
                        ▼
          ┌─────────────────────────────┐
          │       Your Answers          │
          └─────────────────────────────┘
            │           │           │
            ▼           ▼           ▼
       Claude Code    Cursor    OpenCode

📥 所有代理的一个收件箱 --多名特工在一个地方询问。一个队列，一个真相来源。

🧠 教AI --拒绝不好的问题，并告诉它为什么。把“不”变成更好的跟进。

❓ 先解决问题 --无法回答，因为它很模糊？请求 阐述 在你猜之前。

⚡ 通过显而易见的爆炸 — Ctrl+R 接受所有 推荐 选项。专注于艰难的决定。

🔔 重要时发出Pinged --本地通知， 分批的 所以你没有收到垃圾邮件。

🌐 在你工作的地方工作 --SSH连接到远程服务器？AUQ也在那里运行。

Nice Extras

• 🎨 16个内置主题+自定义主题支持
• 🌍 i18n（英语、韩语），带自动检测功能
• 📊 Dock进度条（iTerm2、WezTerm、Ghostty）
• 🔤 完全支持CJK字符

强力动作

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

\[1\] arXiv:2308.13507