smartcat (sc)

为 cat 赋予大脑！Unix 生态系统中的 CLI 界面，让终端高级用户充分利用 llms 并保持完全控制。

它的特殊之处

• 专为高级用户设计，可以根据最频繁的操作进行定制；
• 遵循 Unix 哲学，具有简洁的设计，考虑到终端和编辑器的集成；
• 良好的 I/O 处理能力，可以在提示中插入用户输入并在 CLI 工作流程中使用结果；
• 内置部分提示，使模型作为 CLI 工具运行得更好；
• 完全可配置，可以选择使用的 API、LLM 版本和温度；
• 可以编写和保存自己的提示模板，以快速重复任务（简化、优化、测试等）；
• 支持会话；
• 支持通配符表达式以包含上下文文件。

当前支持以下 API

• 本地运行 Ollama 或任何符合其格式的服务器，请参阅 Ollama 设置 部分以获取免费且最简单的方法入门！
  根据您的设置，答案可能会较慢，您可能想尝试第三方 API 以获得最佳工作流程。
• OpenAi，Mistral AI，Anthropic，Groq。

目录

• 安装
• 用法
• 一些入门示例 🐈‍⬛
  • 与编辑器集成
    • 示例工作流程
• 配置 ← 请仔细阅读
  • Ollama 安装 ← 免费运行的简单方法
• 语音
• 如何帮助？

安装

第一次运行时（sc），它会要求您生成一些默认配置文件，并提供如何完成安装的说明（见配置部分）。

最低配置要求是调用设置 API 的 default 提示（无论是远程的 API 密钥还是本地的 ollama）。

现在来说说如何获取它。

要使用语音输入

目前仅支持 Linux 测试。 非常感谢其他平台用户提供的任何帮助。

• 在 Linux 上，请确保已安装 arecord，并运行 arecord --quiet audio.wav 记录您的音频，直到您按 Ctrl+C 并无输出到标准输出。
• 在 Mac 上，请确保已安装 sox，并运行 sox -t waveaudio 0 audio.wav 记录您的音频，直到您按 Ctrl+C 并无输出到标准输出。
• 在 Windows 上，请确保已安装 sox，并运行 sox -t waveaudio 0 audio.wav 记录您的音频，直到您按 Ctrl+C 并无输出到标准输出。

如果不起作用，请提交一个问题。

使用 Cargo

使用最新的 rust 和 cargo 设置（您可以考虑运行 rustup update）

cargo install smartcat

再次运行此命令以更新 smartcat。

通过下载二进制文件

在发布页面上选择为您的平台编译的二进制文件。

用法

Usage: sc [OPTIONS] [INPUT_OR_TEMPLATE_REF] [INPUT_IF_TEMPLATE_REF]

Arguments:
  [INPUT_OR_TEMPLATE_REF]  ref to a prompt template from config or straight input (will use `default` prompt template if input)
  [INPUT_IF_TEMPLATE_REF]  if the first arg matches a config template, the second will be used as input

Options:
  -e, --extend-conversation        whether to extend the previous conversation or start a new one
  -r, --repeat-input               whether to repeat the input before the output, useful to extend instead of replacing
  -v, --voice                      whether to use voice for input
      --api <API>                  overrides which api to hit [possible values: another-api-for-tests, ollama, anthropic, groq, mistral, openai]
  -m, --model <MODEL>              overrides which model (of the api) to use
  -t, --temperature <TEMPERATURE>  temperature higher means answer further from the average
  -l, --char-limit <CHAR_LIMIT>    max number of chars to include, ask for user approval if more, 0 = no limit
  -c, --context <CONTEXT>...       glob patterns or list of files to use the content as context
                                   make sure it's the last arg.
  -h, --help                       Print help
  -V, --version                    Print version

您可以使用它来完成 CLI 中的任务，也可以在您的编辑器中使用它（如果它们是好的 Unix 用户，即使用 shell 命令和文本流工作）来完成、重构、编写测试……任何任务！

使这一切无缝运行的关键是一个好的默认提示，它告诉模型表现得像 CLI 工具，而不是写入任何不需要的文本，如 markdown 格式化或说明。

一些入门示例 🐈‍⬛

sc "say hi"  # just ask (uses default prompt template)

sc -v  # use your voice to ask (then press <space> to stop the recording)

sc test                         # use templated prompts
sc test "and parametrize them"  # extend them on the fly

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

git diff | sc "summarize the changes"  # pipe data in

cat en.md | sc "translate in french" >> fr.md   # write data out
sc -e "use a more informal tone" -t 2 >> fr.md  # extend the conversation and raise the temprature

与编辑器集成

在编辑器中实现良好集成的关键是好的默认提示（或一组提示）以及用于精确指定任务的 -p 标志。可以使用 -r 标志来决定是否替换或扩展选择。

Vim

首先选择一些文本，然后按 :。然后，您可以将选择的内容管道到 smartcat。

:'<,'>!sc "replace the versions with wildcards"

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

将用语言模型转换的同文本覆盖当前选择。

:'<,'>!sc -r test

将重复输入，实际上将语言模型的输出附加到当前选择的末尾。

请将以下重映射添加到您的 vimrc 中以便轻松访问

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

Helix 和 Kakoune

概念相同，但快捷键不同，只需按管道键即可将选择重定向到 smarcat。

pipe:sc test -r

通过一些重映射，您可以将最常用的操作绑定到几个按键上，例如 <leader>wt！

示例工作流程

对于快速问题

sc "my quick question"

这可能是你获取答案最快的途径：快速打开终端（如果你还没有在终端中），输入 sc 即可。无需查找标签页、无需登录、无需重定向等。

为了提升编码效率

选择一个结构体

:'<,'>!sc "implement the traits FromStr and ToString for this struct"

选择生成的实现块

:'<,'>!sc -e "can you make it more concise?"

将光标置于文件底部，并给出示例用法作为输入

:'<,'>!sc -e "now write tests for it knowing it's used like this" -c src/main.rs

...

从Markdown文件与llm进行完整对话

vim problem_solving.md

> write your question as comment in the markdown file then select your question
> and send it to smartcat using the aforementioned trick, use `-r` to repeat the input.

If you wan to continue the conversation, write your new question as a comment and repeat
the previous step with `-e -r`.

> This allows you to keep track of your questions and make a nice reusable document.

配置

• 默认情况下位于 $HOME/.config/smartcat
• 可以使用 SMARTCAT_CONFIG_PATH 环境变量设置目录
• 在编写提示时，使用 #[<input>] 作为输入的占位符，如果没有提供，它将自动添加到上一条用户消息的末尾
• 默认模型是本地 phi3，使用 ollama 运行，但我推荐尝试最新的版本，看看哪个最适合你；
• 名为 default 的提示将是默认使用的提示。
• 你可以调整温度，并为每个提示设置默认值，具体取决于其使用场景；

使用三个文件

• .api_configs.toml 存储你的凭据，你需要至少一个带有密钥的API提供者或本地ollama设置；
• prompts.toml 存储你的提示模板，你需要至少一个 default 提示；
• conversation.toml 存储最新的聊天，如果你需要继续它，它是自动管理的，但如果你想，你也可以进行备份。

.api_configs.toml

[ollama]  # local API, no key required
url = "https://127.0.0.1:11434/api/chat"
default_model = "phi3"
timeout_seconds = 180  # default timeout if not specified

[openai]  # each supported api has their own config section with api and url
api_key = "<your_api_key>"
default_model = "gpt-4-turbo-preview"
url = "https://api.openai.com/v1/chat/completions"

[mistral]
api_key_command = "pass mistral/api_key"  # you can use a command to grab the key
default_model = "mistral-medium"
url = "https://api.mistral.ai/v1/chat/completions"

[groq]
api_key_command = "pass 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"

prompts.toml

[default]  # a prompt is a section
api = "ollama"  # must refer to an entry in the `.api_configs.toml` file
model = "phi3"  # each prompt may define its own model

[[default.messages]]  # then you can list messages
role = "system"
content = """\
You are an extremely skilled programmer with a keen eye for detail and an emphasis on readable code. \
You have been tasked with acting as a smart version of the cat unix program. You take text and a prompt in and write text out. \
For that reason, it is of crucial importance to just write the desired output. Do not under any circumstance write any comment or thought \
as you output will be piped into other programs. Do not write the markdown delimiters for code as well. \
Sometimes you will be asked to implement or extend some input code. Same thing goes here, write only what was asked because what you write will \
be directly added to the user's editor. \
Never ever write ``` around the code. \
"""

[empty]  # always nice to have an empty prompt available
api = "openai"
# not mentioning the model will use the default from the api config
messages = []

[test]
api = "anthropic"
temperature = 0.0

[[test.messages]]
role = "system"
content = """\
You are an extremely skilled programmer with a keen eye for detail and an emphasis on readable code. \
You have been tasked with acting as a smart version of the cat unix program. You take text and a prompt in and write text out. \
For that reason, it is of crucial importance to just write the desired output. Do not under any circumstance write any comment or thought \
as you output will be piped into other programs. Do not write the markdown delimiters for code as well. \
Sometimes you will be asked to implement or extend some input code. Same thing goes here, write only what was asked because what you write will \
be directly added to the user's editor. \
Never ever write ``` around the code. \
"""

[[test.messages]]
role = "user"
# the following placeholder string #[<input>] will be replaced by the input
# each message seeks it and replaces it
content ='''Write tests using pytest for the following code. Parametrize it if appropriate.

#[<input>]
'''

url = "https://api.openai.com/v1/audio/transcriptions"
# make sure this command fit you OS and works on its own
recording_command = "arecord -f S16_LE --quiet <audio_file_path_placeholder>"
model = "whisper-1"
api = "openai"

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

Ollama设置

1. 安装Ollama
2. 拉取你打算使用的模型 ollama pull phi3
3. 测试模型 ollama run phi3 "say hi"
4. 确保服务可用 curl https://127.0.0.1:11434 应该显示 "Ollama is running"，否则你可能需要运行 ollama serve
5. smartcat 现在可以访问你的本地ollama了，享受吧！

⚠️ 根据你的设置，答案可能会有点慢，你可能想尝试第三方API以获得最佳工作流程。超时是可配置的，默认设置为30秒。

语音

⚠️ 正在测试中 我只有Linux系统，无法测试其他操作系统的录音命令。好消息是你可以创建自己的命令并插入到配置中。

使用 -v 标志请求语音输入，然后按空格结束。它将替换提示定制参数。

• 使用openai whisper
• 确保你的 recording_command 字段在你的终端命令中正常工作，它应该创建一个wav文件
• 需要你拥有一个位于 .api_keys.toml 的openai密钥
• 你仍然可以使用任何提示模板或文本模型来获取输出

sc -v

sc test -v

sc test -v -c src/**/*

它是如何工作的？

smartcat 调用一个外部程序来处理语音录制，并指示它将结果保存为wav文件。然后它监听键盘输入，当按下空格键时停止录制。

然后将录音发送到语音转文字模型，生成的转录文本最终添加到提示中，并发送到文本模型以获取答案。

在Linux上：待办事项 在Mac上：待办事项 在Windows上：待办事项

要调试，您可以检查 conversation.toml 文件或在智能配置主目录中收听 audio.wav，以了解模型听到的内容和转录的内容。

此功能最终应作为附加功能提供，安装时完全可选。欢迎提交PR！

如何帮助？

请参阅 CONTRIBUTING.md。