ask-question-mcp

# ask-question-mcp [](https://github.com/DynamicDevices/ask-question-mcp/actions/workflows/ci.yml) [](https://github.com/DynamicDevices/ask-question-mcp/actions/workflows/ci.yml) [](https://github.com/DynamicDevices/ask-question-mcp/actions/workflows/ci.yml) [](https://github.com/DynamicDevices/ask-question-mcp/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](README.md#mcp-client-configuration) **标准输入输出MCP服务器**，显示一个**桌面多选对话框** (`ask_multiple_choice`)，以便编码代理可以向人类提出实际决策，当宿主IDE没有原生AskQuestion UI（或模型缺少该工具）时。Linux使用Gtk4/Adw；Windows第一阶段使用tkinter（仅限文本）。 > **自行承担风险**。该项目**大量使用AI辅助**（设计、实现和文档）。它在您的桌面上运行，访问您的显示屏、选用的麦克风/TTS和本地音频控制。错误可能会导致**意外行为，包括系统或数据中断或损坏**，以及（取决于您如何连接TTS/STT或日志）**意外的数据泄露**。**不提供保修**。话虽如此，我们希望这是一个可靠的项目：**请通过[GitHub问题](https://github.com/DynamicDevices/ask-question-mcp/issues)（或拉取请求）报告问题和平台反馈**，以便我们可以修复它们 - 参见[测试平台](#tested-platforms)和[安全.md](SECURITY.md)。GPLv3也免除了保修 - [LICENSE](LICENSE)。 | | | |--|--| | **演示** | [YouTube — ask-question-mcp 运行中](https://www.youtube.com/watch?v=5wVKCIXAfi4) | | **许可证** | [GPL-3.0-or-later](LICENSE) ([NOTICE](NOTICE)) - 自行承担风险 | | **维护者** | Alex Lennon · Anthony · **Jack Ghafari** (Claude Code 主机) - [MAINTAINERS.md](MAINTAINERS.md) | | **平台** | Linux (Gtk4/Adw) · **Windows 第一阶段** (tkinter 纯文本) - [测试矩阵](#tested-platforms) | | **传输** | 标准输入输出上的MCP (**stdio** (Cursor, Claude Code, Claude Desktop 风格的 `mcpServers` - 不是 GitHub Pages / 不是远程HTTP)) | | **语音** | 可选；除非设置TTS/STT网址 - [文档/语音后端.md](docs/VOICE-BACKENDS.md) | | **自我检查** | MCP `check_setup` / `setup_guide` · 命令行 `python -m ask_question_mcp.doctor` | | **依赖项** | [DEPENDENCIES.md](DEPENDENCIES.md)（层级 A-D + apt 一键安装） | | **安全** | [SECURITY.md](SECURITY.md) · CRA 注释：[文档/CRA合规性.md](docs/CRA-COMPLIANCE.md) | | **语音后端** | [文档/语音后端.md](docs/VOICE-BACKENDS.md) · [安装.md](SETUP.md) | --- ## 适用于人类的快速入门 MCP主机（目前为Cursor；未来支持Claude Desktop / 其他标准输入输出客户端）启动一个**本地**进程 - 需要克隆存储库；网站无法显示对话框。 ### Linux（Gtk - 完整功能） 1. 安装软件包 + 克隆（Debian/Ubuntu）： ```bash sudo apt install -y python3 python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 zenity curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/DynamicDevices/ask-question-mcp.git cd ask-question-mcp && uv sync pwd # ← 此为绝对路径 REPO_ROOT ``` 2. 注册服务器 - 参见 [MCP客户端配置](#mcp-client-configuration)。优先使用 **`uv` 的绝对路径**。 3. 重载主机（Cursor：开发者 → 重载窗口）。 4. 让代理调用 **`check_setup`**，然后进行一次简单的 **`ask_multiple_choice`**。 5. 语音是可选的 - 保留TTS/STT未设置以仅点击/键入。 ### Windows（Cursor - 仅限文本第一阶段）- 适用于Anthony和其他Windows用户 1. 从 [python.org](https://www.python.org/downloads/) 安装 **Python 3.12+**，并启用 **tcl/tk**（不要使用缺少Tk的商店构建）。 2. 安装 [uv](https://docs.astral.sh/uv/) (`winget install astral-sh.uv` 或安装脚本）。注意 `uv.exe` 的绝对路径（`where uv`）。 3. 克隆 + 同步： ```bat git clone https://github.com/DynamicDevices/ask-question-mcp.git cd ask-question-mcp uv sync cd ``` 注意克隆的绝对路径（例如 `C:\Users\YOU\src\ask-question-mcp`）。 4. 确认Tk：`python -c "import tkinter; print('ok')"`. 5. 在 `%USERPROFILE%\.cursor\mcp.json` 中注册（绝对路径 `uv.exe` + 存储库路径）： ```json "ask-question": { "command": "C:\\Users\\YOU\\.local\\bin\\uv.exe", "args": [ "run", "--directory", "C:\\Users\\YOU\\src\\ask-question-mcp", "ask-question-mcp" ] } ``` 6. Cursor → **开发者：重载窗口**。让代理进行 **`check_setup`**，然后进行一次简单的 **`ask_multiple_choice`**。 7. 第一阶段 **仅限点击/键入**（无语音/麦克风/媒体duck）。成功对话框后，请通过平台反馈提示或GitHub问题报告，以便我们可以标记Windows **已验证** 在矩阵中。 演示（Linux语音）：[YouTube](https://www.youtube.com/watch?v=5wVKCIXAfi4)。风险：[免责声明](#ask-question-mcp) 上方。 --- ## 适用于AI助手（先阅读本节） 如果人类向您指出此README，您的任务通常是：**安装存储库，注册MCP，进行自我检查，然后正确调用 `ask_multiple_choice`**。按照此检查清单。 ### 集成检查清单 1. **确认平台：** Linux GUI（`DISPLAY` + Gtk）**或** Windows桌面（tkinter 第一阶段仅限文本）。不要在无头CI或macOS上期待对话框。 2. **安装主机 + UI依赖项**（参见 [DEPENDENCIES.md](DEPENDENCIES.md)）： ```bash # Debian/Ubuntu sudo apt install -y python3 python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 zenity curl -LsSf https://astral.sh/uv/install.sh | sh # 如果需要 git clone https://github.com/DynamicDevices/ask-question-mcp.git cd ask-question-mcp uv sync ``` 在 **Windows** 上：python.org Python 3.12+ with tcl/tk + `uv sync`（无Gtk）。 克隆的绝对路径 = `REPO_ROOT`。 3. **注册MCP** 在客户端的MCP配置中（Cursor：用户/全局 `mcp.json`；Claude Code：`claude mcp add …` 或项目 `.mcp.json`；Claude Desktop / 其他标准输入输出主机：参见 [MCP客户端配置](#mcp-client-configuration)）。使用 **`uv` / `uv.exe` 的绝对路径** 和绝对路径 `REPO_ROOT`。重载IDE / MCP服务器。 4. **自我检查（必需）：** 调用MCP工具 **`check_setup`**。检查 `dependencies.tiers` 和 `dependencies.install_commands`。 - 如果 `ok` 为假或 `ready.ui` / `ready.text_mcq` 为假 → 通过 `ask_multiple_choice` 提供 `offer_walkthrough`，然后进行 **`setup_guide`** 以选择主题（`ui` / `mcp` / `tts` / `stt` / `voice` / `ui_only`）。 - 在每次更改后重新运行 `check_setup`。命令行：`uv run python -m ask_question_mcp.doctor --json` 5. **可选语音（目前仅限Linux）：** 仅在 `ready.ui` 为真时，并且仅当人类想要语音问题/麦克风答案时。使用 `setup_guide` 主题 `tts` / `stt`。Windows 第一阶段保持纯文本。 6. **教导代理：** 在制作决策分支时，优先使用此MCP工具而不是在聊天中编造markdown A/B/C。遵循 [代理如何调用工具](#how-agents-must-call-the-tool)。 ### 自我描述工具 | 工具 | 目的 | |------|---------| | `check_setup` | 诊断DISPLAY / Gtk / TTS / STT / 平台；返回 `ready`, `next_actions`, `offer_walkthrough` | | `setup_guide` | 分步JSON演练（`topic`：`ui`\|`mcp`\|`tts`\|`stt`\|`voice`\|`ui_only`\|`all`） | | `ask_multiple_choice` | 人类决策对话框；配置错误时包含 `setup` 提示块 | | `record_platform_feedback` | 持久化 works/broken/later/dont_ask 在未经验证的平台提示后 | **代理模式：** 在 **首次启用 / 对话失败 / 语音前：** `check_setup` → （如有必要）演练 → `setup_guide` → 重新检查一次。 不要在例行MCQ之前调用 `check_setup` - 直接进行 `ask_multiple_choice`。 ### 代币 / 目录成本（结构） 主机在启用此MCP时，在每个模型回合中注入 **工具描述 + 服务器指令**。这是启用ask-question的主要成本 - 而不是单击本身。下图为 **结构性** （字符 ÷ 4 ≈ 代币），不是账单CSV。**2026-07-27** 在维护者的Cursor堆栈上测量，精简结果 / 短文档字符串后。 | 界面 | 大小 | ≈ 代币 | 备注 | |---------|-----:|---------:|-------| | 服务器指令 | 347 字符 | ~90 | 优先MCQ；仅在需要时 `check_setup` | | 所有工具描述（4个工具） | 457 字符 | ~110 | 软CI预算：指令 ≤600，每个描述 ≤400 | | 游标上的MCP描述符（`user-ask-question`） | ~4.9k 字符 | ~1.2k | 此软件包在精简目录中的份额 | | 空闲成功MCQ结果（默认） | ~57 字符 | ~14 | 仅 `id` / `label` / `cancelled` | | 相同结果附带完整的语音 + 功能回声 | ~485 字符 | ~120 | 避免除非有用；`ASK_QUESTION_RESULT_VERBOSE=1` 强制执行 | | 每个空闲MCQ节省（精简 vs 胖回声） | - | **~100** | 不要在例行选择前调用 `check_setup` | **主机上下文（非此软件包）：** 游标还加载内置函数（`cursor-app-control`，`cursor-ide-browser`）和任何其他启用的服务器（例如MemPalace）。精简的核心目录在此主机上约为 **15k tok** 总MCP磁盘，总共 `ask-question` ≈ **1.2k**。市场插件可以为每个回合添加数万代币 - 保持可选插件关闭除非工作区需要它们。 **保持成本低的代理习惯： 1. 直接调用 **`ask_multiple_choice`** 进行例行分支。 2. 仅在首次启用、对话失败或语音之前调用 **`check_setup`**。 3. 在调试语音/设置时保持 **`ASK_QUESTION_RESULT_VERBOSE`** 未设置。 参见 [SETUP.md](SETUP.md#5-env-cheat-sheet)（`ASK_QUESTION_RESULT_VERBOSE`）。 ### 这是什么 / 不是什么 | 是 | 不是 | |----|--------| | **本地** 标准输入输出MCP主机，如Cursor和Claude Code，阻塞直到人类点击/键入/语音 | 云API，GitHub Pages应用或远程MCP URL | | 决策分支的 **Gtk对话框** （选择一个/多个/自由格式） | 普通聊天UI或通知中心 | | **纯文本** 时TTS/STT未设置（`audio_mode=text_only`，标记） | 没有语音后端损坏 | | 可选TTS/STT运行 **HTTP服务** | 捆绑GPU模型或托管语音SaaS | | Linux 桌面（Gtk）或Windows（tkinter 纯文本） | 可移植到macOS GUI原样 | ### 不可协商的代理行为 - 传递 **`agent=`** （聊天名称/车道ID），以便窗口标题显示 `[agent] …`。 - 编写 **`question`** 为单个简短句子。没有“请仔细选择”，没有关于对话框或语音的元信息。 - 仅在选项标签中放置 **`recommended`** （`Foo （推荐）`），并传递 **`recommended_id`** （或 `recommended_ids`）。永远不要在 `question` 中添加 `推荐：…` 行。 - 优先使用 **`allow_other=true`** （默认），以便人类可以输入其他内容。 - 将 **`dangerous=true`** （和/或每个选项 `dangerous`）用于不可逆转的/高风险分支（发送电子邮件，销毁数据，强制推送main等）。 - 每次决策：调用工具，等待JSON结果，然后继续。 - 在 `cancelled: true` 上停止该操作；不要编造选择。 - 在自由答案上，处理 **`freeform_text`** 作为答案（不仅限于 `id`）。--- ## MCP 客户端配置 所有地方都是相同的 **标准输入输出启动**：`command` + `args`（+ 可选用的 `env`）。 找到 `uv` 一次：`command -v uv` → 例如 `/home/YOU/.local/bin/uv`。 ### 共享服务器块 ```json "ask-question": { "command": "/home/YOU/.local/bin/uv", "args": [ "run", "--directory", "/绝对路径/到/ask-question-mcp", "ask-question-mcp" ] } ``` 可选语音（省略 `env` 表示纯文本）： ```json "env": { "ASK_QUESTION_TTS_URL": "http://127.0.0.1:8200", "ASK_QUESTION_STT_URL": "http://127.0.0.1:8201/transcribe" } ``` ### 游标 | | | |--|--| | **配置** | 用户/全局 `mcp.json`（Linux：`~/.cursor/mcp.json`；Windows： `%USERPROFILE%\.cursor\mcp.json`） | | **形状** | `{ "mcpServers": { "ask-question": { … } } }` | | **重载** | 命令面板 → **开发者：重载窗口**，或切换MCP设置中的服务器 | | **Windows** | 使用绝对 `uv.exe` 和Windows风格的 `--directory` 路径；参见 [Windows 快速入门](#windows-cursor--仅限文本第一阶段--适用于Anthony和其他Windows用户) | ### 克劳德代码 **所有者：** [@jackghx](https://github.com/jackghx) （Jack Ghafari）- 请保持本节准确，并帮助验证测试平台中的Claude Code行。 #### 命令行界面（推荐） 使用 **`uv` 的绝对路径** - 使用 `command -v uv` 查找您的路径（例如 `/home/YOU/.local/bin/uv`）。 ```bash claude mcp add --transport stdio ask-question -- \ /绝对路径/到/uv run --directory /绝对路径/到/ask-question-mcp ask-question-mcp ``` 带语音环境变量： ```bash claude mcp add --transport stdio \ --env ASK_QUESTION_TTS_URL=http://127.0.0.1:8200 \ --env ASK_QUESTION_STT_URL=http://127.0.0.1:8201/transcribe \ ask-question -- \ /绝对路径/到/uv run --directory /绝对路径/到/ask-question-mcp ask-question-mcp ``` #### 项目 `.mcp.json` （与团队共享） ```json { "mcpServers": { "ask-question": { "command": "/绝对路径/到/uv", "args": [ "run", "--directory", "/绝对路径/到/ask-question-mcp", "ask-question-mcp" ] } } } ``` 验证：运行 `/mcp` 进入Claude Code以检查服务器是否已连接。 ### 克劳德桌面（类似） | | | |--|--| | **配置（Linux）** | `~/.config/Claude/claude_desktop_config.json` | | **配置（macOS）** | `~/Library/Application Support/Claude/claude_desktop_config.json` | | **形状** | 与Cursor相同的 `mcpServers` 对象 | | **重载** | 完全退出并重启应用程序 | | **注意** | 官方Claude Desktop在macOS/Windows上最强；Linux可能是社区构建。 | ### 其他标准输入输出主机（未来/相邻） | 主机 | 典型配置 | 备注 | |------|----------------|-------| | VS Code / Copilot MCP | 工作区或用户MCP JSON | 当支持标准输入输出时，使用相同的 `command`/`args`/`env` 模式 | | Continue / Windsurf / Zed | 产品MCP设置 | 使用绝对 `uv` + `REPO_ROOT`；确认DISPLAY继承 | | 自定义代理 | 自己启动标准输入输出 | 不能剥夺 `DISPLAY`；不要在无显示的无头Docker中包装 | **不支持作为运行对话框的方式：** GitHub Pages，原始HTTPS“远程MCP”，或云中的服务器。那些无法打开人机座位上的Gtk。页面/文档适合阅读；执行停留在本地。 编辑后：重载主机。列表通常显示服务器 **`ask-question`**；工具包括 **`ask_multiple_choice`**， **`check_setup`**， **`setup_guide`**， **`record_platform_feedback`**。 ### 环境变量（摘要） | 变量 | 默认值 | 目的 | |----------|---------|---------| | `ASK_QUESTION_TTS_URL` | 空 | TTS HTTP基址（`/tts`, `/tts/stream`）。空 = 无实时TTS | | `ASK_QUESTION_STT_URL` | 空 | 完整的STT URL，以 `/transcribe` 结尾。空 = 无语音答案 | | `ASK_QUESTION_TTS_TOKEN` / `ASK_QUESTION_STT_TOKEN` | 空 | 可选的Bearer令牌 | | `ASK_QUESTION_AUDIO` | 开启 | `0` / `false` = **静音主音**（TTS + STT）；通过对话框音频复选框覆盖 | | `ASK_QUESTION_SPEAK` | 开启 | `0` / `false` = 仅静音问题语音 | | `ASK_QUESTION_VOICE_ANSWER` | 开启 | `0` = 永远不要打开麦克风路径 | | `ASK_QUESTION_DUCK` | 开启 | `0` = 不要降低其他音频（首选项 `duck_enabled`） | | `ASK_QUESTION_ACK` | 开启 | `0` = 仅静音已确认语音 | | `ASK_QUESTION_RESULT_VERBOSE` | 关闭 | `1` = 总是附加完整的 `voice` + `capabilities` 到MCQ结果 | | `ASK_QUESTION_SPEAK_VOLUME` / `ASK_QUESTION_ACK_VOLUME` | `0.60` / `0.55` | 线性播放增益 | | `ASK_QUESTION_ALWAYS_LISTEN` | 开启 | `0` = 仅限“监听”按钮 | | `ASK_QUESTION_AGENT` / `LANE_ID` | 未设置 | 如果省略 `agent=`，则使用默认值 | | `ASK_QUESTION_ARM_MS` | `1000` | 所有MCQ：打开OK/Enter后阻塞此毫秒数（`0` = 关闭） | | `ASK_QUESTION_DANGER_ARM_MS` | `4000` | 危险对话框：更长的阻塞时间（`0` = 关闭用于危险路径） | 完整的旋钮 + 首选项路径： [SETUP.md](SETUP.md)， [DEPENDENCIES.md](DEPENDENCIES.md)。 **永远不要提交令牌。** 可选文件： `~/.config/ask-question-mcp/token` （模式 `600`）。 --- ## 代理如何调用工具 ### 工具名称 `ask_multiple_choice` ### 参数 | 参数 | 类型 | 是否必需 | 备注 | |-----|------|----------|--------| | `question` | 字符串 | 是 | 决策提示，仅限 | | `options` | 对象数组 | 是 | 2–8 项： `{ "id", "label" }` 加可选 `dangerous`, `opens_entry`, `auto_listen` | | `recommended_id` | 字符串 | 否 | 单选首选 ID（列为首选 + 预选） | | `recommended_ids` | 字符串数组 | 否 | 多选首选 ID | | `allow_multiple` | 布尔值 | 否 | 默认 `false`（单选）；`true` = 多选 | | `allow_other` | 布尔值 | 否 | 默认 `true` — 追加 其他 | | `dangerous` | 布尔值 | 否 | 全对话框危险边框；OK/Enter 启用 ~4s (`ASK_QUESTION_DANGER_ARM_MS`)。普通多选题启用 ~1s (`ASK_QUESTION_ARM_MS`)。 | | `speak` | 布尔值 | 否 | 默认 `true`（尊重静音环境 / 缺失 TTS） | | `title` | 字符串 | 否 | 默认 `"Decide"` — 短名词短语 | | `agent` | 字符串 | **强烈要求** | 窗口标题前缀 `[agent]` | | `timeout_sec` | 整数 | 否 | 默认 `300`；`0` = 无超时 | | `entry_seed` | 字符串 | 否 | 预填充 其他 / 条目 | ### 示例调用（单选） ```json { "question": "立即发布 Drive 镜像？", "title": "Drive 镜像", "agent": "docs-agent", "recommended_id": "发布", "options": [ { "id": "发布", "label": "发布（推荐）" }, { "id": "等待", "label": "等待答案" }, { "id": "git_only", "label": "仅 Git" } ] } ``` ### 示例调用（危险） ```json { "question": "强制推送 main 以重写历史记录？", "title": "强制推送", "agent": "release-agent", "dangerous": true, "recommended_id": "中止", "options": [ { "id": "中止", "label": "中止（推荐）" }, { "id": "强制", "label": "强制推送 main", "dangerous": true } ] } ``` OK 和 Enter 在打开后短暂锁定（OK 按钮上的倒计时），以防止 stray Return 确认：**~1s** 在普通多选题 (`ASK_QUESTION_ARM_MS`)，**~4s** 当 `dangerous` 设置时 (`ASK_QUESTION_DANGER_ARM_MS`)。将任一环境变量设置为 `0` 以禁用该路径。取消 / Esc 仍然立即生效。 ### 返回值（JSON 字符串） 工具返回一个 **JSON 字符串**。在分支前请解析它。 **单选：** ```json { "id": "发布", "label": "发布（推荐）", "cancelled": false, "allow_multiple": false, "agent": "docs-agent" } ``` **多选：** `ids` + `labels` 数组代替 `id` / `label`。 **自由输入（其他）：** 相同结构 + `"freeform": true` 和 `"freeform_text": "…"`. 使用 `freeform_text` 作为人类答案。 **已取消：** ```json { "cancelled": true, "reason": "…" } ``` **功能（仅当有用时）：** 在正常成功选择且语音健康时省略。当 `capabilities.notes` 有设置提示时包含（例如 TTS 未设置）。完整转储：`ASK_QUESTION_RESULT_VERBOSE=1`. ```json { "audio_mode": "text_only", "capabilities": { "notes": ["未配置 TTS … — 文本仅限多选题（单击 / 输入）。"], "audio_mode": "text_only" } } ``` `audio_mode` 为 `text_only` | `speak` | `full`. 缺失语音从不成为硬错误 — 如果人类稍后想要语音，请调用 `setup_guide`. **语音诊断：** `voice` 仅在语音被使用或失败时包含（转录 / 匹配 / 错误）。空闲空语音块省略。选择的 `id` / `freeform_text` 仍然是权威的。 --- ## 功能（人类概述） - Gtk4/Adw radiolist / checklist；推荐选项首先 + 预选 - 危险决策的危险边框 - 内联 其他（输入或 Speak→STT，当配置时） - **文本仅限回退** 当 TTS/STT 未设置 — 对话仍然有效；响应在设置提示适用时包含 `capabilities.notes`（否则精简） - 精简空闲多选题 JSON（省略空 `voice` / `capabilities`）；参见 [Token / catalog cost](#token--catalog-cost-structural) - 可选 TTS + 捆绑多声 WAV；可选 STT 短语匹配 - PipeWire 下的媒体 duck - 每对话会话 IPC，因此并行代理不共享语音门 --- ## 需求 ### 最小（UI） - **Linux:** 带有 `DISPLAY` 的桌面环境，Gtk 4 + libadwaita - **Windows:** 桌面环境 + Python 带有 **tkinter**（第 1 阶段文本仅限） - Python ≥ 3.12 和 [`uv`](https://docs.astral.sh/uv/) ### 可选（语音 — Linux） - 用于语音 / duck 的音频栈 — 参见 [音频栈](#audio-stack)（首选 PipeWire） - 您自己的 TTS/STT HTTP 服务 — [SETUP.md](SETUP.md) Windows 语音处于第 2 阶段（此版本中不包含）。参见 [docs/WINDOWS.md](docs/WINDOWS.md). ### 首选项 不需要首选项文件。可选 `~/.config/ask-question-mcp/prefs.json`（参见 `prefs.example.json`). 覆盖顺序：**env → prefs.json → 默认出货**. | 键 | 默认值 | |-----|---------| | `audio_enabled` | `true` — 主 TTS+STT；对话框 **音频** 复选框；env `ASK_QUESTION_AUDIO` | | `duck_enabled` | `true` — 在说话 / 监听时降低其他应用程序；env `ASK_QUESTION_DUCK` | | `ack_enabled` | `true` — OK 后有语音确认；env `ASK_QUESTION_ACK` | | `speak_volume` | `0.60` | | `ack_volume` | `0.55` | | `always_listen` | `true` | ### 确认包 OK 后选择的语音确认由 **结果**（同意 / 分歧 / 中立 / 自由输入 / 危险）选择。取消保持静音。短语列表在代码中提供；可选覆盖：复制 [`acks.example.json`](acks.example.json) → `~/.config/ask-question-mcp/acks.json`. WAV 缓存：`~/.cache/ask-question-mcp/charlize-acks/v2/`. 使用 `scripts/review_acks.py` 生长音频包。 --- ## 音频栈 **Gtk 对话框不需要音频**。语音、确认、媒体 duck 和蓝牙麦克风助手是可选的，并且分层在上面。 | 功能 | 我们使用什么 | PipeWire | PulseAudio | 纯 ALSA | |------------|-------------|----------|------------|-----------| | 文本仅限多选题 | 仅 Gtk | 是 | 是 | 是 | | 播放问题 / 确认 WAV | `pw-play` → `paplay` → `aplay` | 是（`pw-play`） | 是（`paplay`） | 部分（仅 `aplay`；无音量 duck） | | 在说话时 duck 其他应用程序 | `pactl` sink-input 音量 | 是（通过 `pipewire-pulse`） | 是 | **否** | | 蓝牙配置文件 / A2DP 恢复（监听） | `pactl` 卡片 / 接收器 | 是 | 是 | **否** | **摘要** - 我们 **不是** 仅限 PulseAudio。我们与 **Pulse 客户端 API**（`pactl` / `paplay`）通信，该 API 由 **PipeWire**（`pipewire-pulse`) 和经典 **PulseAudio** 提供。维护人员在 **PipeWire** 上进行测试。 - **PipeWire** 是首选路径：安装 `pw-play` + `pactl`（通常为 Debian/Ubuntu 上的 `pipewire`、`pipewire-pulse`、`pipewire-audio-client-libraries`）。 - **经典 PulseAudio**（无 PipeWire）：通过 `paplay` 说话，通过 `pactl` duck 应该有效；如果您验证，请在 [已测试平台](#tested-platforms) 中报告。 - **纯 ALSA**（无 Pulse/PipeWire 会话）：UI 仍然有效；WAV 播放可能通过 `aplay` 作为最后的手段；**媒体 duck 和蓝牙麦克风助手不会**。在桌面上首选 PipeWire/Pulse 以获取语音功能。 - 通过对话框 **音频** 复选框或 `ASK_QUESTION_AUDIO=0` 静音语音 + 监听，或取消设置 TTS。更细致：`ASK_QUESTION_SPEAK=0` / `ASK_QUESTION_VOICE_ANSWER=0`. 详情 / 软件包：[DEPENDENCIES.md](DEPENDENCIES.md) 层级 C. --- ## 已测试平台 社区 / 维护人员反馈关于 **Gtk 多选题**（和可选语音 / duck）实际工作的信息。此信息不是详尽的支持矩阵 — 如果您的设置丢失，请报告它（问题或 PR 更新此表格）。参见 [CONTRIBUTING.md](CONTRIBUTING.md). | 发行版 / 桌面环境 | 音频 | MCP 主机 | UI 对话框 | 说话 / duck | 备注 | 状态 | |------------------|-------|----------|-----------|--------------|-------|--------| | **Ubuntu 24.04** + GNOME（经典） | PipeWire（+ 脉冲兼容） | 光标 | 是 | 是 | x86_64；Gtk4 + Adw GI；维护人员每日驱动器 | **已验证**（2026-07） | | 任意 Linux 桌面环境（如上） | PipeWire | **Claude Code** | 是 | 否（仅限文本） | 标准输入输出传输；Ubuntu 24.04 + GNOME + PipeWire；文本仅限多选题已验证。所有者：[@jackghx](https://github.com/jackghx) | **已验证**（2026-07） | | Debian / Ubuntu（其他） | PipeWire | — | — | — | Apt 软件包匹配 [DEPENDENCIES.md](DEPENDENCIES.md)；可能正常 | **尚未报告** | | Fedora | PipeWire | — | — | — | 参见 DEPENDENCIES 草图（`python3-gobject`、`gtk4`、`libadwaita`） | **尚未报告** | | Arch | PipeWire | — | — | — | 参见 DEPENDENCIES 草图 | **尚未报告** | | KDE Plasma / 其他桌面环境 | PipeWire | — | — | — | 需要 `DISPLAY` + Gtk4/Adw；理论上与桌面环境无关 | **尚未报告** | | 任意 Linux 桌面环境 | 经典 PulseAudio（无 PW） | — | 是（预期） | 说话 + duck 通过 `paplay`/`pactl` 预期 | 维护人员未测试 | **尚未报告** | | 任意 Linux | 纯 ALSA 仅 | — | 是 | 说话部分（`aplay`）；duck **否** | 文本仅限推荐 | **部分 / 不支持 duck** | | **Windows 10/11** | n/a | 光标 | 是（文本） | 否 | tkinter 后端（`win_list_ask.py`）；第 1 阶段 | **尚未报告**（Anthony / 社区） | | 无头 / CI | n/a | GitHub Actions | 否 | 否 | 单元 / 医生仅 — 无交互对话框 | **N/A**（按设计） | | macOS | — | — | 否 | 否 | 尚无原生 UI 后端 | **不支持** | **如何添加一行：** 打开一个 PR 或问题，包含发行版 + 版本、桌面环境、音频栈（PipeWire / Pulse / 其他）、MCP 客户端（例如 Cursor、Claude Code）、您检查的内容（文本仅限多选题 / 说话 / duck / STT）。保持声明诚实 — “对我有效” 就足够了；如果仅 UI 有效，请标记 **部分**. MCP 还检测未经验证的主机：`check_setup.platform` 和一次性 `platform_feedback` 提示在 `ask_multiple_choice` 上询问人类对话框是否有效；代理可以从填充的主机详细信息中起草 GitHub 问题（`record_platform_feedback` 保留“不要再问”）。 --- ## 烟雾测试 在 GUI 会话中： ```bash cd /absolute/path/to/ask-question-mcp uv run python -c " from ask_question_mcp.zenity_ask import ask_zenity print(ask_zenity( 'Smoke?', [{'id':'a','label':'OK (recommended)'},{'id':'b','label':'Other'}], recommended_id='a', agent='smoke', )) " ``` 或注册 MCP 并从代理调用 `ask_multiple_choice`. --- ## 故障排除（适用于代理） | 症状 | 可能的解决方法 | |---------|------------| | 工具丢失 / 服务器无法启动 | 使用 **绝对** `uv` 路径（非裸 `uv`）；检查 REPO_ROOT；重新加载主机；`check_setup` | | 对话框不出现 | `check_setup` → 修复 `display` / `gtk_*`；`echo $DISPLAY`；确保主机继承显示（非无头 / SSH 无显示） | | 挂起 / 超时 | 人类必须单击；或提高 `timeout_sec`；检查对话框是否在屏幕外 | | 说话无 TTS URL | 存在本地 Piper / `notify-voice.sh` — 预期；使用音频复选框 / `ASK_QUESTION_AUDIO=0` / `ASK_QUESTION_SPEAK=0` 静音 | | 无语音 | TTS URL 未设置且无本地语音路径；`setup_guide` 主题 `tts`；或静音环境 | | 麦克风从未监听 | STT URL 未设置 — `setup_guide` 主题 `stt`；或 `ASK_QUESTION_VOICE_ANSWER=0` | | 导入 / Gtk 错误 | 安装 Gtk4/Adw GI 绑定；参见 `check_setup` 失败检查 | | 在 IDE 中有效，在终端中无效 | IDE PATH 比 shell 薄 — 绝对 `uv`；在安装后重启 IDE | --- ## 贡献 / 合规 - [CONTRIBUTING.md](CONTRIBUTING.md) - [SECURITY.md](SECURITY.md) — 向 `security@dynamicdevices.co.uk` 报告漏洞 - [docs/CRA-COMPLIANCE.md](docs/CRA-COMPLIANCE.md) — 工程基线；不是 CE 符合性声明 版权所有 © 2026 Dynamic Devices Ltd.