smartcat (sc)

为 cat 赋予智慧！一个 CLI 界面，将语言模型引入 Unix 生态系统，让终端高手在完全掌控的同时，最大化利用大语言模型的能力。

它的独特之处在于：

• 专为高级用户设计；自定义配置以减少高频任务的开销
• 极简主义风格，遵循 Unix 哲学构建，注重与终端和编辑器的集成
• 优秀的输入输出处理能力，可将用户输入插入提示中，并将结果用于基于 CLI 的工作流
• 内置部分提示功能，使模型更适合作为 CLI 工具使用
• 完全可配置使用的 API、LLM 版本和温度参数
• 可编写并保存自己的提示模板，以加快重复性任务（简化、优化、测试等）
• 支持对话模式
• 使用 glob 表达式引入上下文文件

目前支持以下 API：

• 本地运行：通过 Ollama 或任何兼容其格式的服务器；请参阅 Ollama 设置 部分，了解免费且最简单的入门方式！
  (根据您的配置，回答可能会较慢；您可能希望尝试第三方 API 以获得最佳工作流程。)
• Anthropic、Azure OpenAI、Groq、Mistral AI、OpenAI

目录

• 安装
• 推荐模型
• 使用方法
• 几个入门示例 🐈‍⬛
  • 与编辑器集成
    • 示例工作流
• 配置 ← 请仔细阅读
  • Ollama 设置 ← 免费且最简单的运行方式
• 如何贡献？

安装

首次运行 (sc) 时，它会提示您生成默认配置文件，并指导您完成安装（请参阅 配置 部分）。

最低配置要求是设置一个调用已配置 API 的 default 提示模板（可以是带有 API 密钥的远程 API，也可以是使用 Ollama 的本地运行）。

接下来介绍如何获取它。

使用 Cargo

确保您已安装最新版本的 Rust 和 Cargo（您可以运行 rustup update）：

cargo install smartcat

再次运行此命令即可更新 smartcat。

Arch Linux

如果您使用的是 Arch Linux，可以从 extra 仓库 安装该软件包：

pacman -S smartcat

下载二进制文件

请从 发布页面 选择适合您平台的编译版本。

推荐模型

目前，Anthropic、Mistral 或 OpenAI 的 API 效果最佳。使用这些顶级模型进行常规操作，每月费用约为 2–3 美元。

使用方法

用法：sc [选项] [输入或模板引用] [模板引用时的输入]

参数：
  [输入或模板引用]  指向配置中的提示模板或直接输入（若未指定，则使用 `default` 提示模板）
  [模板引用时的输入]  如果第一个参数匹配配置中的模板，则第二个参数将作为输入

选项：
  -e, --extend-conversation        是否延续之前的对话或开始新对话
  -r, --repeat-input               是否在输出前重复输入，适用于扩展而非替换场景
      --api <API>                  覆盖要调用的 API [可选值：ollama、anthropic、groq、mistral、openai]
  -m, --model <MODEL>              覆盖要使用的模型（针对所选 API）
  -t, --temperature <TEMPERATURE>  温度越高，回答越偏离平均值
  -l, --char-limit <CHAR_LIMIT>    最多包含的字符数；超过时需用户确认，0 表示无限制
  -c, --context <CONTEXT>...       用于提供上下文的 glob 模式或文件列表
                                   必须放在最后。
  -h, --help                       显示帮助信息
  -V, --version                    显示版本号

您可以将其用于 CLI 中的任务，也可以在编辑器中使用（前提是编辑器能够良好地与 Shell 命令和文本流交互），以完成代码补全、重构、编写测试等任何操作！

要让其无缝运行的关键，在于设置一个良好的默认提示模板，告诉模型应像 CLI 工具一样工作，而不是输出不必要的内容，如 Markdown 格式或解释说明。

几个入门示例 🐈‍⬛

sc "say hi"  # 直接提问（使用默认提示模板）

sc test                         # 使用模板化提示
sc test "and parametrize them"  # 动态扩展模板

sc "explain how to use this program" -c **/*.md main.py  # 使用文件作为上下文

git diff | sc "summarize the changes"  # 通过管道传递数据

cat en.md | sc "translate in french" >> fr.md   # 将数据写入文件
sc -e "use a more informal tone" -t 2 >> fr.md  # 延续对话并提高温度

与编辑器集成

在编辑器中实现良好集成的关键在于设置一个合适的默认提示（或一组提示），并结合 -p 标志来指定当前任务。此外，可以使用 -r 标志来决定是替换还是扩展选中的内容。

Vim

首先选择一些文本，然后按下 : 键。接着可以将选中文本通过管道传递给 smartcat。

:'<,'>!sc "用通配符替换版本号"

:'<,'>!sc "修复这个函数"

这会覆盖当前选中的内容，用语言模型转换后的相同文本替换它。

:'<,'>!sc -r test

则会重复输入内容，相当于在当前选中文本的末尾追加语言模型的输出结果。

为了方便使用，可以在你的 vimrc 文件中添加以下映射：

nnoremap <leader>sc :'<,'>!sc

Helix 和 Kakoune

概念相同，但快捷键不同。只需按下管道键即可将选中文本重定向到 smartcat。

pipe:sc test -r

通过一些自定义映射，你可以将最常用的命令绑定到几个按键上，例如 <leader>wt！

示例工作流

用于快速提问：

sc "我的快速问题"

这很可能是你最快得到答案的方式：只需打开终端（如果你还没有在终端中），运行 sc 即可。无需寻找标签页、登录或跳转等操作。

帮助编写代码：

选择一个结构体：

:'<,'>!sc "为这个结构体实现 FromStr 和 ToString 特性"

选择生成的实现块：

:'<,'>!sc -e "能否让它更简洁一些？"

将光标放在文件底部，并提供示例用法作为输入：

:'<,'>!sc -e "现在根据它的使用方式为其编写测试" -c src/main.rs

……

从 Markdown 文件中与 LLM 进行完整对话：

vim problem_solving.md

> 在 Markdown 文件中以注释形式写下你的问题，然后选中该问题，
> 使用上述技巧将其发送到 smartcat，使用 `-r` 选项重复输入。
>
> 如果你想继续对话，可以再写一条新问题作为注释，然后重复之前的步骤，使用 `-e -r`。
>
> 这样可以记录下所有问题，形成一份便于复用的文档。

配置

• 默认情况下，配置文件位于 $HOME/.config/smartcat 或 Windows 上的 %USERPROFILE%\.config\smartcat。
• 可以通过 SMARTCAT_CONFIG_PATH 环境变量来设置配置目录。
• 编写提示时，请使用 #[<input>] 作为输入占位符；如果没有提供输入，系统会自动将其添加到用户最后一条消息的末尾。
• 默认模型是使用 Ollama 运行的本地 phi3 模型，但建议尝试最新的模型，找到最适合你的那一款。
• 默认会使用名为 default 的提示。
• 你可以根据每个提示的具体用途调整温度参数，并为每个提示设置默认值。

配置文件包含三个文件：

• .api_configs.toml 存储你的 API 凭证；至少需要一个支持 API 密钥的服务提供商，或者本地的 Ollama 部署。
• prompts.toml 存储你的提示模板；至少需要一个名为 default 的提示。
• conversation.toml 用于存储最近的对话记录，以便后续继续；该文件会自动管理，但你也可以根据需要进行备份。

.api_configs.toml

[ollama]  # 本地 API，无需密钥
url = "http://localhost:11434/api/chat"
default_model = "phi3"
timeout_seconds = 180  # 如果未指定，默认超时时间为 180 秒

[openai]  # 每个支持的 API 都有独立的配置部分，包含 API 密钥和 URL
api_key = "<your_api_key>"
default_model = "gpt-4-turbo-preview"
url = "https://api.openai.com/v1/chat/completions"

[mistral]
# 可以使用命令获取密钥，需要可用的 `sh` 命令
api_key_command = "pass mistral/api_key"
default_model = "mistral-medium"
url = "https://api.mistral.ai/v1/chat/completions"

[groq]
api_key_command = "echo $MY_GROQ_API_KEY"
default_model = "llama3-70b-8192"
url = "https://api.groq.com/openai/v1/chat/completions"

[anthropic]
api_key = "<yet_another_api_key>"
url = "https://api.anthropic.com/v1/messages"
default_model = "claude-3-opus-20240229"
version = "2023-06-01"  # anthropic API 版本，详见 https://docs.anthropic.com/en/api/versioning

[cerebras]
api_key = "<your_api_key>"
default_model = "llama3.1-70b"
url = "https://api.cerebras.ai/v1/chat/completions"

prompts.toml

[default]  # 每个提示是一个独立的部分
api = "ollama"  # 必须引用 `.api_configs.toml` 中的条目
model = "phi3"  # 每个提示可以单独定义使用的模型

[[default.messages]]  # 接下来可以列出多条消息
role = "system"
content = """\
你是一位精通编程和 Shell 的专家。你始终将代码的效率和清晰度放在首位。 \
你编写的代码会被管道传递到 CLI 程序中，因此除非被明确要求，否则不会做任何解释。 \
请不要在回答中使用 ``` 包围代码，只需直接给出任务的结果。保持输入格式不变。\
"""

[empty]  # 总是有一个空提示可用
api = "openai"
# 如果不指定模型，则使用 API 配置中的默认模型
messages = []

[test]
api = "anthropic"
temperature = 0.0

[[test.messages]]
role = "system"
content = """\
你是一位精通编程和 Shell 的专家。你始终将代码的效率和清晰度放在首位。 \
你编写的代码会被管道传递到 CLI 程序中，因此除非被明确要求，否则不会做任何解释。 \
请不要在回答中使用 ``` 包围代码，只需直接给出任务的结果。保持输入格式不变。\
"""

[[test.messages]]
role = "user"
# 下面的占位符字符串 #[<input>] 将被实际输入替换
# 每条消息都会查找并替换它
content ='''使用 pytest 为以下代码编写测试。如果合适，可以进行参数化。

#[<input>]
'''

更多详细信息请参阅 配置设置文件。

Ollama 设置

1. 安装 Ollama
2. 拉取你计划使用的模型：ollama pull phi3
3. 测试模型：ollama run phi3 "say hi"
4. 确保服务已启动：curl http://localhost:11434，应显示“Ollama is running”，否则可能需要运行 ollama serve。
5. 现在 smartcat 就可以访问你的本地 Ollama 了，尽情使用吧！

⚠️ 根据你的配置，回答可能会比较慢，建议尝试第三方 API 以获得更流畅的工作流程。超时时间可配置，默认为 30 秒。

如何贡献？

请参阅 CONTRIBUTING.md。

Smartcat (sc) 快速上手指南

Smartcat 是一款专为终端高级用户设计的 CLI 工具，旨在将大语言模型（LLM）无缝集成到 Unix 生态系统中。它允许你通过管道、重定向和编辑器集成，完全控制 AI 的输入输出，使其像标准的命令行工具一样工作。

环境准备

• 操作系统: Linux, macOS, Windows (WSL 推荐)。
• 前置依赖:
  • 方案 A (本地运行 - 免费): 需安装 Ollama 并拉取模型（如 phi3）。这是最推荐的起步方式。
  • 方案 B (云端 API): 需拥有 Anthropic, OpenAI, Groq, Mistral 或 Azure OpenAI 的 API Key。
• 构建工具 (仅源码安装需要): Rust 和 Cargo (建议运行 rustup update 确保最新)。

安装步骤

方法一：使用 Cargo 安装（推荐）

如果你已配置好 Rust 环境，这是最通用的安装方式：

cargo install smartcat

更新时再次运行上述命令即可。

方法二：Arch Linux 用户

可以直接从官方仓库安装：

pacman -S smartcat

方法三：下载二进制文件

访问 GitHub Release 页面，下载对应平台的编译好的二进制文件并放入 PATH 中。

初始化配置

首次运行 sc 时，程序会自动引导你生成默认配置文件（位于 $HOME/.config/smartcat）。

• 关键步骤: 你必须配置至少一个可用的 API 提供者（本地 Ollama 或远程 API Key）以及一个名为 default 的提示词模板，工具才能正常工作。

基本使用

Smartcat 的核心在于将 AI 作为命令行过滤器使用。默认的提示词模板已优化为“只输出结果，不包含 Markdown 格式或多余解释”，以便直接用于管道操作。

1. 直接提问

使用默认模板进行快速问答：

sc "say hi"

2. 管道输入与输出

结合 git, cat 等命令处理数据流：

总结代码变更：

git diff | sc "summarize the changes"

翻译文件内容：

cat en.md | sc "translate in french" >> fr.md

3. 使用上下文文件

利用 glob 表达式将多个文件内容作为上下文输入：

sc "explain how to use this program" -c **/*.md main.py

4. 编辑器集成 (Vim/Neovim)

在编辑器中选中文本，进入命令模式，通过 ! 调用 smartcat 处理选中内容：

重构选中的代码（直接替换）：

:'<,'>!sc "fix this function"

为选中代码生成测试（追加到末尾）： 使用 -r 参数保留原始输入，将 AI 生成的内容追加在后面：

:'<,'>!sc -r test

提示: 建议在 .vimrc 中添加映射以简化操作：

nnoremap <leader>sc :'<,'>!sc

5. 对话延续

使用 -e 参数基于上一轮对话继续交互：

sc -e "use a more informal tone" -t 2 >> fr.md

(其中 -t 2 表示提高温度值，使回答更具创造性)