q AI Shell 命令助手

q 是一个跨平台 CLI 工具，可以根据自然语言生成 Shell 命令候选，并让你用方向键选择。默认行为是只回填或输出命令，不自动执行。

安装与开发

npm install
npm run build
npm link

配置模型

执行：

q --model

界面会以类似 Codex / Claude Code 的格式展示当前默认模型、已有模型、配置完整性和快捷键。

当前支持 4 类 provider：

• OpenAI-compatible API
• Claude Code CLI
• Codex CLI
• Gemini CLI

常用快捷键：

• ↑↓：选择模型
• Enter / u：设为默认模型
• a：新增模型
• e：编辑模型
• d：删除模型
• t：测试连接
• Esc / q：退出

新增或编辑模型时填写：

• HTTP provider：
  • 配置名称：例如 deepseek
  • API Key：可以输入，也可以留空后用环境变量 Q_API_KEY
  • Base URL：例如 https://api.openai.com/v1
  • 模型名：例如 gpt-4.1-mini
  • 超时时间：默认 30000
  • 默认候选数量：默认 3
• CLI provider：
  • 配置名称：例如 claude-default
  • 子模型名：可留空；留空时使用对应 CLI 的默认模型
  • 超时时间：默认 30000
  • 默认候选数量：默认 3

CLI provider 的前置条件：

• Claude Code CLI 依赖本机可直接执行 claude
• Codex CLI 依赖本机可直接执行 codex
• Gemini CLI 依赖本机可直接执行 gemini
• 这三类 provider 都要求对应 CLI 已完成登录或本机认证
• 它们不会读取 Q_API_KEY，认证由各自 CLI 自行管理

配置文件位置：

• macOS/Linux：~/.config/q/config.json
• Windows：%APPDATA%/q/config.json

基础用法

q "查找当前目录下最大的 10 个文件"

调试请求和响应报文：

q --trace "停止运行 zerotier 服务"
q --trace explain "ls -la"

候选列表出现后：

• 上下方向键选择
• 回车确认
• e 展开或收起完整说明和风险详情
• Esc 取消

如果没有安装 Shell 集成，q 会把最终选择的命令打印到 stdout。

--trace 会把本次模型请求地址、请求体摘要和响应报文打印到 stderr，便于排查超时、非标准 JSON 返回和兼容性问题；默认关闭，且会对敏感字段脱敏。 对于 CLI provider，--trace 会记录实际命令名、参数摘要、退出码，以及 stdout/stderr 摘要。 在 --trace 模式下，候选成功确认后会保留当前 trace 输出和候选列表，方便继续查看成功返回内容。

Shell 集成

q init <shell> 会输出集成脚本，不会自动修改你的配置文件。

zsh：

q init zsh >> ~/.zshrc
source ~/.zshrc

fish：

q init fish >> ~/.config/fish/config.fish

PowerShell：

q init powershell >> $PROFILE

bash：

q init bash >> ~/.bashrc
source ~/.bashrc

bash 回填需要借助 Readline 绑定：加载脚本后按 Ctrl-G，输入提示词，选择候选后会回填到当前输入行。zsh、fish、PowerShell 可以直接使用 q "提示词" 的函数形式。

说明：普通子进程不能直接修改父 Shell 的输入行，因此回填依赖各 Shell 自身能力。未集成或当前 Shell 不支持回填时，可以使用 stdout 输出作为降级方式。

解释命令

q explain "find . -type f -size +100M"

历史记录

q history

q history 会展示最近确认选择过的命令，并支持再次选择输出。

历史命令列表和普通命令候选列表使用同一套界面格式，也支持上下选择、回车确认、e 查看详情和 Esc 取消。

上下文与隐私

q 会读取轻量上下文帮助模型生成命令：

• 当前目录路径
• 当前平台和 Shell
• 最近最多 50 条历史命令
• 当前目录一级文件列表
• Node、Maven、Gradle、Python、Go、Rust、Docker、Git 项目类型摘要

q 不会递归扫描整个项目，不会上传完整源码。历史命令会过滤包含 password、token、secret、api_key、authorization 等敏感片段的内容。

安全边界

• 默认不执行命令。
• 高风险命令会标记并要求二次确认。
• 风险等级由本地规则重新判断，不完全信任模型返回。

二期计划

• q doctor 检查 Shell 集成、模型配置和网络连通性。
• q fix 读取上一条失败命令和错误输出，生成修复建议。