Proqi 是一款为同时运行多个编码代理（如 Codex、Claude Code）的资深用户设计的终端原生提示词编辑器。它能让你独立地捕获、编辑、排序和复用每条指令、截图和备选方案，而无需中断当前代理的工作。本教程将指导你完成安装、配置和基础使用。

📋 部署前准备

  • 操作系统：macOS 或 x86-64 GNU/Linux。
  • Rust 工具链：如果选择从源码编译，需要 Rust 1.88 或更高版本。
  • Homebrew (macOS/Linux)：推荐使用此方式安装，方便快捷。

🚀 第一步：安装

Proqi 提供了多种安装方式，推荐使用 Homebrew。

方式一：使用 Homebrew 安装 (推荐)

1
2
3
4
5
# 添加 tap 并安装
brew install oborchers/tap/proqi

# （可选）信任此 formula，以避免未来操作时的提示
brew trust --formula oborchers/tap/proqi

方式二：使用 Cargo 编译安装

如果你已安装 Rust 工具链，也可以通过 crates.io 安装：

1
cargo install proqi --locked

方式三：直接下载预编译二进制

你可以从项目的 GitHub Releases 页面 下载适用于你系统的预编译二进制文件（如 macOS/Linux 压缩包或 Debian 包），将其解压并放入 PATH 环境变量包含的目录即可。

验证安装：在终端运行 proqi --version，应正确显示版本号。

⚙️ 第二步：首次启动与基础配置

Proqi 遵循“零配置，即可用”的理念，但你可以通过配置文件进行自定义。

1. 启动 Proqi

在终端中输入 proqi 并回车，即可创建一个新的编辑板 (Board)。

1
proqi         # 打开一个新的空 Board

会看到一个类似文本编辑器的界面，光标位于 + Start typing 处，你可以立即开始输入文本以创建第一个“想法 (Thought)”。

2. 基础操作速览

  • 创建想法：直接输入文本，按 Enter 或点击 + New thought 行。
  • 编辑想法：选中一个想法后按 e 或 Enter 进入编辑模式。
  • 返回看板：在编辑模式下按 Esc 键。
  • 导航：使用 j / k 或上下箭头在想法间移动。
  • 提交/复制：
    • Primary+C / y：复制选中的想法到系统剪贴板。
    • Primary+Enter / s：提交并发送（需配合 Herdr），发送后删除该想法。
    • Primary+Shift+Enter / S：提交并保留该想法。

关于 Primary 键：在 macOS 上指 Cmd 键，在 Linux/Windows 上指 Ctrl 键。

3. 配置文件 (可选)

Proqi 使用平台原生的 config.toml 进行配置。你可以在配置文件中调整主题、快捷键、合并分隔符等。运行 proqi --help 可以查看默认配置文件的路径。

1
2
3
4
5
6
7
8
# 示例配置片段
theme = "auto"                # 主题: auto, light, dark
density = "comfortable"       # 显示密度: comfortable, compact
check_for_updates = true      # 是否检查更新

[keybindings]
# 自定义快捷键，例如将删除键映射为 'x'
delete = "x"

🖥️ 第三步：核心工作流与高级功能

Proqi 的真正威力在于它改变了与编码代理交互的流程。

核心工作流：从“实时输入”到“独立编辑”

  1. 你在 Proqi 中起草：当代理正在执行任务时，你在 Proqi 里起草下一条指令、记录一个想法或粘贴一段代码。
  2. 编辑与组织：你可以安全地编辑、复制、重排、合并这些“想法”，甚至保存多个备选方案。
  3. 提交给代理：当你准备好后，可以通过 Herdr（推荐）一键将整理好的内容发送给指定的代理，或简单地复制粘贴到代理的终端输入框中。

截图收件箱 (Screenshot Inbox) - macOS 专属

  • 在 Proqi 的 Board 界面按 i 键，即可激活 macOS 截图监听功能。
  • 之后，你使用 Cmd+Shift+4 等快捷键截取的新截图，会自动作为新的“图像想法”出现在 Proqi 中，方便你添加注释并发送给代理。

原生提交：与 Herdr 集成

Proqi 可以与 Herdr 深度集成，实现安全、可靠的提交。

  • 在 Board 或编辑模式下，使用 s/S 或 Primary+Enter/Primary+Shift+Enter 提交时，如果检测到有多个已验证的相邻代理，Proqi 会弹出方向选择器，你只需按 h/j/k/l 选择目标代理，即可完成提交。

命令行接口 (CLI) 与技能 (Skill)

对于自动化场景，Proqi 提供了 JSON 输出能力的 CLI：

1
2
3
4
5
# 查看 Proqi 的能力
proqi --json capabilities

# 使用技能添加 (需安装 npx)
npx skills add oborchers/proqi --skill proqi -g --agent codex --agent claude-code

这会为 Codex 和 Claude Code 代理安装 Proqi 的技能，让它们能够以更结构化的方式与 Proqi 交互。

🛠️ 排障与诊断

  • 终端快捷键被拦截：某些终端（如 Ghostty）可能会拦截系统快捷键。例如，要让 Cmd+Shift+V 在 Proqi 中执行“粘贴并重排”功能，可能需要在 Ghostty 的配置文件中添加 keybind = super+shift+v=csi:118;10u 来转发按键。
  • 环境自检：运行 proqi doctor 可以快速检查 Proqi 的运行环境。
  • 收集诊断信息：如果遇到问题，运行 proqi diagnostics collect --output proqi-diagnostics.json 生成一个本地、已脱敏的诊断文件。在寻求社区帮助时，请先自行审查该文件内容。
  • 数据持久化：Proqi 的所有想法、附件和设置都存储在本地。如果程序异常退出，下次启动时会自动恢复。

📝 快速上手指南

  1. 安装：使用 brew install oborchers/tap/proqi。
  2. 启动：在终端输入 proqi。
  3. 创建内容：在 + Start typing 处输入你的第一条指令或想法，按 Enter 确认。
  4. 编辑与整理：使用 j/k 导航，按 e 编辑想法，使用 d 删除，使用 Primary+D 复制。
  5. 提交：
    • 无 Herdr：使用 Primary+C 复制整个 Board 或选中的想法，然后粘贴到你的代理终端中。
    • 有 Herdr：确保代理已连接，在 Proqi 中按 Primary+Enter 直接提交。
  6. 退出：按 Primary+Q 或 q 退出。退出时会自动保存，并打印出恢复该 Board 的命令（proqi -r <session-id>）。

通过以上步骤，你已经成功部署并初步掌握了 Proqi 的使用。它的核心价值在于为你的思考过程提供了一个独立、持久、可组织的空间，让你在与多个 AI 代理协作时更加从容和高效。