qqqa

快速、无状态的基于大语言模型的命令行助手：qq 回答问题；qa 执行命令

什么是 qqqa

qqqa 是一款二合一的无状态命令行工具，无需繁琐步骤即可为命令行带来大语言模型的辅助支持。

该工具包含两个可执行文件：

• qq - 提出一个简单的问题，例如：“qq 如何递归列出当前目录下的所有文件”（qq 代表“quick question”，即快速提问）
• qa - 一个单步代理，可以选择性地使用工具来完成任务：读取文件、写入文件或在确认后执行命令（qa 代表“quick agent”，即快速代理）

qqqa 支持 macOS、Linux 和 Windows 系统。

默认情况下，仓库中包含了针对 OpenRouter（默认）、OpenAI、Groq、本地 Ollama 运行时、Codex CLI（基于 ChatGPT）以及 Claude Code CLI（复用你的 Claude 订阅）的配置文件。此外，还存在一个用于 Anthropic 的配置文件模板，但目前尚未启用。

https://github.com/user-attachments/assets/91e888ad-0279-4d84-924b-ba96c0fe43a0

名称与打字速度

qq 意为快速提问。qa 意为快速代理。两者在 QWERTY 键盘上都易于快速输入，且手指移动幅度小。这使得在实际工作中与大语言模型的交互更加迅速和自然。

哲学理念

qqqa 被刻意设计为无状态。它没有长时间运行的会话，也不会存储任何隐藏的对话历史。每次运行几乎都是独立且可重复的。若希望保持低调的连续性，可以在 config.json 中设置 "include_history": true（或者在 qq --init 过程中选择使用历史记录）。

为什么无状态很棒：

• 简单而专注——将 Unix 哲学应用于大语言模型工具。
• 对 Shell 友好——通过管道和文件进行组合，而非交互式聊天。
• 默认安全——qq 仅读取数据，不访问任何工具。qa 在设计时充分考虑了安全性，执行工具前需要用户确认。

工具可能会包含你选择提供的临时上下文：

• qq 可以将最近几条终端命令作为提示，并在有输入时接收管道输入。
• qa 可以读取文件或执行特定命令，但每次调用仅限一次，并带有安全检查。

为什么我推荐默认使用 OpenRouter

OpenRouter 镜像了 OpenAI 的 Chat Completions API，同时增加了大量社区托管的模型，并且使 openai/gpt-4.1-nano 保持快速且经济实惠。qqqa 默认与 https://openrouter.ai/api/v1 通信，并从 OPENROUTER_API_KEY 环境变量中读取 API 密钥，因此只需提供密钥，首次运行即可正常工作。

如果你需要更高的吞吐量，捆绑的 groq 配置文件仍然可用，它针对的是 openai/gpt-oss-20b 和 openai/gpt-oss-120b 模型。你也可以通过编辑 ~/.qq/config.json 或创建新的配置文件来添加任何兼容 OpenAI 的提供商。

Codex CLI 配置文件（自带 ChatGPT 订阅）

已经支付了 ChatGPT 费用吗？选择 codex 配置文件（在 qq --init 期间、通过 qq --profile codex 或编辑 ~/.qq/config.json），qqqa 将调用 Codex CLI 而不是向 HTTP 端点发送请求。这样你就可以几乎零额外成本地复用现有的 ChatGPT 订阅。

需要注意的是：

• 通过 ChatGPT 桌面应用（设置 → 实验室 → Codex）或使用 pip install codex-cli 安装 Codex CLI，然后确保 codex 已添加到你的 PATH 中。
• 流式传输不可用；即使未使用 --no-stream 参数，qqqa 也会缓冲 Codex 的响应并一次性打印出来。
• qa 仍然期望 JSON 格式的工具调用。当你需要 read_file、write_file 或 execute_command 时，仍需按照 OpenRouter 的方式返回 { "tool": string, "arguments": object }。
• 如果二进制文件缺失或运行时出现错误，qqqa 会输出标准错误/标准输出信息，以便你快速修复环境。

以下是一个将 Codex 设置为默认配置文件的 ~/.qq/config.json 示例片段：

{
  "default_profile": "codex",
  "profiles": {
    "codex": {
      "model_provider": "codex",
      "model": "gpt-5",
      "reasoning_effort": "minimal"
    }
  }
}

Claude Code CLI 配置文件（自带 Claude Desktop 订阅）

拥有 Claude 订阅吗？选择 claude_cli 配置文件，qqqa 将使用 claude 二进制文件。这样，如果你已经为 Claude for Desktop 付费，使用成本实际上可以保持为零。

需要注意的是：

• 安装 Claude Code，确保 claude 二进制文件位于你的 PATH 中，然后运行一次 claude login。
• Claude Code 以与基于 API 的大语言模型相同的方式流式传输响应。
• 如果需要指定不同的 Claude Desktop 模型，可以在 ~/.qq/config.json 中的 model_providers.claude_cli.cli 下添加 "model_override": "claude-haiku-4-5"。此覆盖仅适用于 Claude CLI；每轮运行时，qq -m/--model 仍将优先于配置文件中的设置。

以下是一个极简的配置示例：

{
  "default_profile": "claude_cli",
  "profiles": {
    "claude_cli": {
      "model_provider": "claude_cli",
      "model": "claude-haiku-4-5"
    }
  },
  "model_providers": {
    "claude_cli": {
      "cli": {
        "model_override": "claude-haiku-4-5"
      }
    }
  }
}

功能特性

• 兼容 OpenAI 的 API 客户端，支持流式和非流式调用。
• 无状态、单次执行的工作流程，与管道和脚本配合良好。
• 使用类似 XML 的标签渲染 ANSI 颜色，格式丰富但简单。
• 基于配置的提供商和配置文件，支持每个配置文件单独覆盖模型。
• 文件访问和命令执行的安全机制。
• 如果你喜欢老派风格且认真严肃？还可以通过 --no-fun 参数启用无表情符号模式 🥸

安装

Homebrew（macOS/Linux）

brew install qqqa

Linux

从 GitHub Releases 页面下载预编译的压缩包，解压后将 qq 和 qa 放置到你的 PATH 中的任意位置（例如 /usr/local/bin）。

Windows

从 Releases 页面下载适用于 Windows 的压缩包（选择与你的机器架构匹配的版本），解压 qq.exe 和 qa.exe，并将它们添加到你的 %PATH% 中。

配置

首次运行时，qqqa 会创建权限安全的 ~/.qq/config.json 文件。为了获得顺畅的初次体验，建议运行初始化流程：

# 交互式设置（选择提供商并设置密钥）
qq --init

# 或者
qa --init

如果 ~/.qq/config.json 已经存在，初始化命令会保持该文件不变，并说明在移动或删除该文件后如何重新运行。

初始化程序允许你选择默认的提供商：

• OpenRouter + openai/gpt-4.1-nano（默认，快速且便宜）
• Groq + openai/gpt-oss-20b（更快，付费层级更便宜）
• OpenAI + gpt-5-mini（较慢，稍微更智能）
• Anthropic + claude-3-5-sonnet-20241022（占位符，直到其 Messages API 完成）
• Ollama（本地运行，必要时调整端口）
• Codex CLI + gpt-5（封装了 codex exec 二进制文件，以便你可以复用 ChatGPT 订阅；无需 API 密钥，仅支持缓冲输出）
• Claude Code CLI + claude-haiku-4-5（封装了 claude 二进制文件；qq 实时流式输出，qa 则使用缓冲区以便解析工具调用）
  • 如果需要强制使用不同的桌面模型？可以在提供商的 cli 块下添加 "model_override"（Codex 和 Claude 都支持）。该覆盖会优先于配置文件中的默认设置，但仍然会低于每次运行时的 --model 标志。

它还提供将 API 密钥存储在配置中（可选）的功能。如果你更倾向于使用环境变量，可以将其留空，并设置以下其中之一：

• 对于 OpenRouter：OPENROUTER_API_KEY（默认）
• 对于 Groq：GROQ_API_KEY
• 对于 OpenAI：OPENAI_API_KEY
• 对于 Ollama：OLLAMA_API_KEY（可选；任何非空字符串均可——甚至可以是 local——因为 Authorization 头不能为空）
• 对于 Codex 或 Claude CLI 配置，则无需 API 密钥——它们的二进制文件会自行处理身份验证（codex login / claude login）。

写入 ~/.qq/config.json 的默认设置如下：

• 提供商
  • openrouter → 基础 URL https://openrouter.ai/api/v1，环境变量为 OPENROUTER_API_KEY，默认头信息为 HTTP-Referer=https://github.com/iagooar/qqqa 和 X-Title=qqqa
  • openai → 基础 URL https://api.openai.com/v1，环境变量为 OPENAI_API_KEY
  • groq → 基础 URL https://api.groq.com/openai/v1，环境变量为 GROQ_API_KEY
  • ollama → 基础 URL http://127.0.0.1:11434/v1，环境变量为 OLLAMA_API_KEY（如果未设置，qqqa 会自动注入一个非空占位符）
  • anthropic → 基础 URL https://api.anthropic.com/v1，环境变量为 ANTHROPIC_API_KEY（目前存在于配置架构中，以备未来支持；暂不可用）
  • codex → 模式为 cli，二进制文件为 codex，基础参数为 exec（需安装 Codex CLI；身份验证由 codex login 处理）。cli 块中可选的 "model_override" 可在 OpenAI 停止支持默认模型时强制使用备用的 ChatGPT 模型。
  • claude_cli → 模式为 cli，二进制文件为 claude（需安装 @anthropic-ai/claude-code；身份验证由 claude login 处理）。可选的 "model_override" 可以固定 Claude Code 的 --model 标志，而不会影响你的配置文件中的模型设置。
  • codex → CLI 提供商，二进制文件为 codex——如果缺少该二进制文件则会失败
• 配置文件
  • openrouter → 模型为 openai/gpt-4.1-nano（默认）
  • openai → 模型为 gpt-5-mini
  • groq → 模型为 openai/gpt-oss-20b
  • ollama → 模型为 llama3.1
  • anthropic → 模型为 claude-3-5-sonnet-20241022（处于非激活状态的占位符，直到 Anthropic 集成完成）
  • codex → 模型标签为 gpt-5（仅用于显示；Codex CLI 会选择背后的 ChatGPT 模型）
• GPT-5 系列模型的可选每配置文件 reasoning_effort。如果你未设置，qqqa 会对任何 gpt-5* 模型发送 "reasoning_effort": "minimal"，以保持响应速度。当你需要更深入的推理时，可以将其设置为 "low"、"medium" 或 "high"。
• （不推荐）每配置文件的可选 temperature。大多数模型默认为 0.15，除非你在 ~/.qq/config.json 中设置，或在单次运行时通过 --temperature <value> 指定。GPT-5 模型会忽略自定义温度，qqqa 会强制将其设为 1.0。
• （不推荐）：你可以更改超时时间，例如在 ~/.qq/config.json 中的某个模型配置文件下设置 "timeout": "240"，以提高每次请求的限制（qq + qa 默认为 180 秒——这太慢了；使用更快的模型才是更好的解决办法）。

~/.qq/config.json 中的示例覆盖：

{
  "profiles": {
    "openai": {
      "model_provider": "openai",
      "model": "gpt-5-mini",
      "reasoning_effort": "medium"
    }
  }
}

• 可选标志：no_emoji（默认未设置）。可通过 qq --no-fun 或 qa --no-fun 设置。
• 可选自动复制功能：copy_first_command（默认未设置/假）。可在 qq --init 时启用，或通过运行 qq --enable-auto-copy、或编辑 ~/.qq/config.json 来让 qq 将第一个 <cmd> 块复制到剪贴板。可通过 qq --disable-auto-copy 关闭。也可以在每次运行时通过 --copy-command/--cc 或 --no-copy-command/--ncc（也可简写为 -ncc）进行覆盖。
• 每次运行的控制选项：--no-stream 会强制 qq 等待完整响应后再打印；默认为流式输出。

终端历史记录

终端历史记录默认关闭。在执行 qq --init 或 qa --init 时，你可以选择在每次请求中发送最近的 10 条 qq/qa 命令。你仍然可以在每次运行时通过 --history（强制开启）或 -n/--no-history（强制关闭）来覆盖这一设置。只有以 qq 或 qa 作为首个标记的命令才会被共享。

使用方法

qq - 提问

qq 默认以流式方式输出响应，因此你可以立即看到每个令牌的到来。如果你更喜欢传统的缓冲输出——例如当你要将其管道传递给其他工具，或者希望一次性复制完整的答案时——可以使用 --no-stream 标志，等待响应完全结束后再进行打印。

# 最简单
qq "将 mp4 转换为 mp3"

# 默认流式输出（格式化后的结果）
qq "在 macOS 上如何根据名称杀死进程"

# 禁用流式输出，等待完整的格式化响应
qq --no-stream "总结今天的 git 状态"

# 在单次运行中为非 GPT-5 模型提高温度
qq --temperature 0.4 "起草一条有趣的 git 提交信息"

# 包含管道传递的上下文
git status | qq "总结接下来我应该做什么"

# 管道传递额外上下文并保留 CLI 问题
printf '%s\n' "这是一个示例上下文。我的代码是 4242" | qq "我的代码是多少"

# 管道传递问题本身
printf '%s\n' "给我看看这个目录的全部内容" | qq

# 原始文本（无 ANSI 格式）
qq -r "解释 sed 和 awk 的区别"

# 包含本次运行的终端历史记录
qq --history "查找过去一天内的大文件"

# 禁用响应中的表情符号（持久生效）
qq --no-fun "总结这段内容"

# 自动复制第一个 <cmd> 块以便快速粘贴（别名：--cc）
qq --copy-command "列出 docker 镜像"

# 即使在配置中已启用自动复制，仍临时禁用自动复制（别名：--ncc / -ncc）
qq --no-copy-command "打印当前工作目录"

# 为所有未来的 qq 运行启用自动复制
qq --enable-auto-copy

# 永久禁用自动复制
qq --disable-auto-copy

注意：你也可以不加引号直接运行 qq，大多数情况下效果与加引号时相同。

# 最简单
qq convert mp4 to mp3

示例：忘记了 ffmpeg 的用法

你想从 YouTube 视频中提取音频，但却记不清具体的参数。

可以用 qq 提问：

qq "如何使用 ffmpeg 将 YouTube 视频中的音频提取为 mp3"

典型的回答可能会建议先安装相关工具，然后使用 yt-dlp 获取音频，再用 ffmpeg 进行转换：

# macOS
brew install yt-dlp ffmpeg

# Debian 或 Ubuntu
sudo apt-get update && sudo apt-get install -y yt-dlp ffmpeg

# 使用 ffmpeg 在后台将音频下载并提取为 MP3 格式
yt-dlp -x --audio-format mp3 "https://www.youtube.com/watch?v=VIDEO_ID"

为我用 qa 来执行：

qa "从 https://www.youtube.com/watch?v=VIDEO_ID 下载音频为 MP3 格式"

代理会提出一个安全的命令，例如 yt-dlp -x --audio-format mp3 URL，显示出来供确认，然后执行。你可以传递 -y 参数来自动批准。

qa - 使用工具执行单步操作

qa 可以用纯文本回答，也可以请求一次 JSON 格式的工具调用。支持的工具包括：

• read_file，参数为 { "path": string }
• write_file，参数为 { "path": string, "content": string }
• execute_command，参数为 { "command": string, "cwd?": string }

示例：

# 安全地读取文件
qa "读取 src/bin/qq.rs 文件，并告诉我 main 函数的作用"

# 写入文件
qa "在 notes/intro.md 创建一段简短的 README 摘要"

# 运行命令并等待确认
qa "列出 src 目录下的 Rust 文件，并按文件大小排序"

# 将任务直接通过管道传递
printf '%s\n' "给我看看这个目录的全部内容" | qa

# 自动批准非交互式脚本中的工具执行
qa -y "统计所有 *.rs 文件中的行数"

# 仅针对本次运行包含最近的 qq/qa 命令
qa --history "追踪我最近执行了哪些 git 命令"

# 提高本次运行的温度（仅限非 GPT-5 模型）
qa --temperature 0.3 "头脑风暴一些有趣的 git 别名"

# 禁用回复中的表情符号（永久生效）
qa --no-fun "格式化并 lint 整个代码库"

# 非交互式运行 qa，已预先批准确认
qa -y "统计所有 *.rs 文件中的行数"

当 qa 在终端中运行命令时，输出流会实时显示；之后仍会打印结构化的 [tool:execute_command] 总结信息，方便复制。

execute_command 会打印建议的命令并请求确认。如果工作目录不在你的主目录内，它会发出警告。使用 -y 参数可以在受信任的工作流程中自动批准。

运行器会强制执行默认的允许列表（如 ls、grep、find、rg、awk 等），并拒绝管道、重定向和其他高风险操作。当某个命令被阻止时，qa 会提示你将其添加到 ~/.qq/config.json 中的 command_allowlist；一旦批准，该选择就会被保存下来，并应用于未来的运行。在 Windows 上，它会自动适应当前环境，因此像 dir 或 Get-ChildItem 这样的内置命令无需额外标志即可正常工作。

高级功能和配置

自定义 TLS 证书（自签名代理）

一些兼容 OpenAI 的网关（LiteLLM、本地企业代理等）会使用自签名 CA 终止 TLS。你可以为每个提供商添加一个 tls 块，使 qqqa 除了默认的 Rustls 证书包外，也信任该 CA：

{
  "model_providers": {
    "litellm": {
      "name": "LiteLLM",
      "base_url": "https://proxy.local/v1",
      "env_key": "LITELLM_API_KEY",
      "tls": {
        "ca_bundle_path": "certs/litellm-ca.pem",
        "ca_bundle_env": "SSL_CERTFILE_PATH"
      }
    }
  }
}

• ca_bundle_path 接受 PEM 或 DER 格式的文件。相对路径会相对于 ~/.qq/ 解析，因此你可以将证书与配置文件放在一起。
• ca_bundle_env 是可选的；如果设置，qqqa 会从该环境变量中读取证书路径，当其未设置时则回退到 ca_bundle_path。这与那些暴露 SSL_CERTFILE_PATH 或类似选项的代理行为一致。
• 多个证书可以放在同一个文件中（只需将 PEM 条目拼接起来）。qqqa 会将它们追加到现有的 Rustls 受信存储中，因此标准的公共 CA 仍然有效。

通过这种配置，任何提供商——LiteLLM、Ollama over HTTPS、公司网关或其他代理——都可以使用自定义 CA 进行身份验证，而无需禁用 TLS 验证。

本地模型与自定义端口

选择内置的 ollama 配置文件（或创建自己的配置文件）来与本地运行时通信。当你在不同的主机/端口上公开服务时，可以覆盖 API 基础地址：

qq --profile ollama --api-base http://127.0.0.1:11435/v1 "总结构建失败的原因"
qa --profile ollama --api-base http://192.168.1.50:9000/v1 "应用补丁" -y

qa --init 会提供 Ollama 作为选项，并跳过 API 密钥警告；qqqa 仍会发送一个占位符令牌，以便兼容 OpenAI 的中间件继续工作。如果你绕过初始化流程并手动编辑 config.json，可以在 ollama 提供商下设置 "api_key": "local"，或者导出 OLLAMA_API_KEY=local，以确保 Authorization 头不为空。

本地设置示例：在 macOS 上使用 LM Studio 调用 ollama run meta-llama-3.1-8b-instruct-hf（Q4_K_M），在 MacBook Air M4/32 GB 上运行效果良好，只是速度比托管的 OpenRouter/Groq 配置稍慢。请相应调整 ollama 配置文件中的模型标签。

你仍然可以在运行时进行覆盖：

# 选择配置文件
qq -p groq "什么是 ripgrep"

# 为单次调用覆盖模型
qq -m openai/gpt-oss-20b "解释这段 awk 单行代码"

安全模型

• 文件工具要求路径必须位于你的主目录或当前目录内。读取限制为 1 MiB，且会阻止遍历和符号链接逃逸。
• 命令执行使用默认的允许列表（如 ls、grep、rg、find 等），再加上你自定义的 command_allowlist 条目。破坏性模式（如 rm -rf /、sudo、mkfs 等）始终被禁止，而管道/重定向/换行符即使使用 --yes 参数也会要求确认。
• 命令执行有 120 秒的超时限制，且代理最多只能执行一步工具操作——不会出现循环。
• 配置文件以安全权限创建。API 密钥来自环境变量，除非你明确将密钥添加到配置中。

环境变量

• OPENROUTER_API_KEY 用于 OpenRouter 提供商（默认）
• GROQ_API_KEY 用于 Groq 提供商
• OPENAI_API_KEY 用于 OpenAI 提供商

开发

项目布局：

• 入口文件位于 src/bin/qq.rs 和 src/bin/qa.rs
• 核心模块位于 src/：ai.rs、config.rs、prompt.rs、history.rs、perms.rs、formatting.rs
• 工具模块位于 src/tools/：read_file.rs、write_file.rs、execute_command.rs
• 集成测试位于 tests/

贡献

请参阅 CONTRIBUTING.md，了解报告问题和提交拉取请求的指南、从源码构建以及发布流程。

故障排除

• API 错误提示缺少密钥：运行 qq --init 来进行设置，或导出相应的环境变量，例如 export OPENROUTER_API_KEY=...。
• 流式传输时无输出：尝试使用 -d 查看调试日志，或使用 --no-stream 重新运行，以切换到缓冲输出（在某些边缘情况下可能效果更好）。
• 管道输入未被检测：确保你是将输入直接管道到 qq，而不是在一个吞咽 stdin 的子 shell 中运行。

许可证

采用 MIT 许可证。

qqqa 快速上手指南

qqqa 是一个无状态（stateless）、基于大语言模型（LLM）的命令行助手工具。它包含两个核心二进制文件：

• qq (Quick Question)：用于快速提问，获取解释或建议。
• qa (Quick Agent)：单步智能体，可读取文件、写入文件或执行命令（需确认），适合自动化任务。

该工具设计理念遵循 Unix 哲学，无长期会话记忆，每次运行独立且可复现，非常适合通过管道组合使用。

环境准备

系统要求

• 操作系统：macOS, Linux, Windows
• 网络环境：需要能够访问外部 LLM API（如 OpenRouter, OpenAI, Groq）或本地运行 Ollama。
• 依赖项：
  • 若使用云端模型：需具备对应服务的 API Key。
  • 若使用本地模型：需安装并运行 Ollama。
  • 若复用现有订阅：需安装 codex-cli (ChatGPT) 或 claude-code (Claude Desktop) 并确保其二进制文件在 PATH 中。

前置配置

默认推荐使用 OpenRouter，因为它兼容 OpenAI 接口且提供多种高性价比模型。你需要准备一个 API Key。

安装步骤

macOS / Linux (推荐 Homebrew)

brew install qqqa

Linux / Windows (手动安装)

1. 访问 GitHub Releases 下载对应系统的压缩包。
2. 解压文件，将 qq 和 qa (Windows 下为 qq.exe, qa.exe) 移动到系统 PATH 目录中（例如 /usr/local/bin 或添加到 %PATH%）。

基本使用

1. 初始化配置

首次使用前，运行初始化向导以选择提供商并配置 API Key。

# 交互式设置（选择提供商如 OpenRouter, OpenAI, Ollama 等，并输入 Key）
qq --init

注：也可以直接设置环境变量（如 export OPENROUTER_API_KEY=your_key），然后在初始化时留空 Key 输入。

2. 使用 qq 快速提问

qq 默认以流式输出回答，支持管道传入上下文。

简单提问：

qq "如何递归列出当前目录下所有文件"

结合管道使用（推荐）： 将命令输出作为上下文传递给 AI 进行分析：

git status | qq "总结接下来我该做什么"

禁用流式输出（适用于脚本处理）：

qq --no-stream "总结今天的 git 提交记录"

纯文本输出（无 ANSI 颜色格式）：

qq -r "解释 sed 和 awk 的区别"

3. 使用 qa 执行任务

qa 可以调用工具（读/写文件、执行命令），但在执行操作前会要求用户确认，确保安全。

示例：让 AI 分析文件并给出修改建议（需确认后执行）：

qa "检查 package.json 是否有未使用的依赖，并生成清理脚本"

4. 高级技巧

• 使用终端历史：在初始化时开启，或单次运行添加 --history 参数，让 AI 了解你之前的操作。

  qq --history "查找昨天创建的大文件"
  

• 关闭表情符号：如果你偏好严肃的输出风格。

  qq --no-fun "解释这段代码"
  

• 切换模型配置文件： 配置文件位于 ~/.qq/config.json。你可以编辑该文件切换默认的 Provider（如从 OpenRouter 切换到本地 Ollama）或调整模型参数。