ITADN
simonmysun/ell
代码 动态 Issues24 合并请求18 版本4
simonmysun/ell · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

ell

一个用 Bash 编写的 LLM 命令行界面。

功能

ell 的基本用法（webm，1.6MiB）

  • 从终端向 LLM 提问
  • 支持管道
  • 将终端上下文提供给 LLM 并提问
  • 在终端中与 LLM 聊天
  • 通过模板支持函数调用及其他功能
  • 敏感信息脱敏（#14)

要求

要使用 ell，您需要以下环境：

  • bash-4.1 或更高版本
  • coreutils / OS X 工具以及 awk 和 sed
  • curl（用于发送 HTTPS 请求）
  • util-linux（如果不使用记录模式则不需要。用于 script 命令以记录终端输入和输出）

安装

git clone --depth 1 https://github.com/simonmysun/ell.git \
  "${XDG_DATA_HOME:-$HOME/.local/share}/ell"
echo 'export PATH="${XDG_DATA_HOME:-$HOME/.local/share}/ell:$PATH"' >> ~/.bashrc

这会将仓库克隆到 ${XDG_DATA_HOME:-$HOME/.local/share}/ell （遵循 XDG Base Directory Specification） 并将其添加到你的 PATH。你可以将其克隆到任何位置；只有 你 PATH 上的目录才重要。

或者，如果 ~/.local/bin 已经在你的 PATH 上（在许多 现代发行版中都是如此），你可以将仓库目录从你的 PATH 中移除， 并将启动器符号链接到其中：

mkdir -p ~/.local/bin
ln -s "${XDG_DATA_HOME:-$HOME/.local/share}/ell/ell" ~/.local/bin/ell

链接 ell 启动器（而非 ell.sh）：它会解析符号链接回到克隆目录，从而确保始终能找到捆绑的辅助工具、模板和插件。

从旧版本安装升级？ 之前的布局 （git clone ... ~/.ellrc.d 且配置位于 ~/.ellrc）仍然有效： ~/.ellrc 仍会被读取，且 ~/.ellrc.d 下的模板和插件 仍会被加载。无需迁移。

Windows

ell 是一个 Bash 程序，因此请从 Git Bash、 MSYS2、Cygwin 或 WSL 等 Bash 环境中运行它。

ell 命令是一个普通的包装脚本（而非符号链接），因此即使 git 在检出时未创建符号链接（在 Windows 上，除非启用了开发者模式或拥有管理员权限，否则默认不创建），它也能正常工作。无需额外设置；克隆仓库并将其目录添加到你的 PATH 中，如上文所示。你以相同的方式调用它，例如 ell "your prompt"。

环境差异与限制。 这些 Bash 环境在模拟 POSIX 系统的忠实程度上有所不同，因此某些功能会相应降级：

  • WSL 的行为类似于 Linux；一切功能均可正常工作。
  • MSYS2 和 Cygwin 提供了相当完整的 POSIX 层（基于 ACL 的 文件权限、真正的符号链接、script(1)），因此整套功能集 均可正常工作。
  • Git Bash 是刻意保持极简的。在 NTFS 上它无法创建真正 允许组/其他用户写入的文件，因此 load_config 中的配置文件权限检查 （该检查会拒绝加载允许其他用户写入的 .ellrc）以及针对临时认证头文件的 chmod 600 无法被强制执行；它还 缺少 script(1)（记录模式）以及默认情况下的真实符号链接。它仍然 可以运行，但在多用户机器上应将这些视为安全限制 — 请参阅 Configuration → Windows 以获取详细信息 及更安全的替代方案（MSYS2 / WSL）。

为了在 Windows 上获得最完整的体验，请优先选择 WSL 或 MSYS2 而非 Git Bash。

Configuration

请参阅 Configuration。

以下是一个使用 Google 的 gemini-1.5-flash 的示例配置。您需要在配置文件 ${XDG_CONFIG_HOME:-$HOME/.config}/ell/config 中设置这些变量（旧版的 ~/.ellrc 仍然有效）：

ELL_API_STYLE=gemini
ELL_LLM_MODEL=gemini-1.5-flash
ELL_TEMPLATE=default-gemini
ELL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELL_API_URL=https://generativelanguage.googleapis.com/v1beta/models/

以下是一个使用 OpenAI 的 gpt-4o-mini 的示例配置。

ELL_API_STYLE=openai
ELL_LLM_MODEL=gpt-4o-mini
ELL_TEMPLATE=default-openai
ELL_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELL_API_URL=https://api.openai.com/v1/chat/completions

使用示例

请确保您已正确配置。

提问：

ell "What is the capital of France?"

指定一个模型并使用文件作为输入：

ell -m gpt-4o -f user_prompt.txt

从标准输入读取也是支持的：

cat somecode.py | ell -f -

如果您更喜欢立即添加另一段提示，而不是将其添加到模板中：

(cat somecode.py; echo "Explain this code") | ell -f -

记录终端输入和输出并用作上下文：

ell -r
# do random stuff
ell What does the error code mean?
ell How to fix it?

以交互模式运行：

ell -i

在交互模式下，记录模式会自动启用，以便您结合上下文进行聊天。

指定一个模板，并启动记录模式和交互模式：

ell -r -i -t ctf-gemini

或

ell -r -i -t ctf-openai

取决于您使用的是哪个 API。

夺旗游戏的示例应用 (webm, 2.6MiB)

编写模板

参见 模板。

请注意，ell 中 LLM 提供商的插件支持是通过模板实现的。

样式

参见 样式。

插件

参见 插件。

此处的术语 "Plugin" 指可被 ell 调用的脚本。它可以用于扩展 ell 的功能。LLM 提供商支持的插件不包含在此处。请参阅 模板。

后端

参见 后端。

后端将 ell 适配到 LLM API "风格"（通过 --api-style / ELL_API_STYLE 选择）。OpenAI 和 Gemini 开箱即用，并且您可以 添加自己的后端。

架构

参见 架构 了解 ell 的组成方式： 启动序列、配置优先级、请求管道及其四个 钩子阶段、后端以及记录模式。

需要考虑的风险

参见 风险考量。

Q&A

  • Q: 为什么叫 "ell"？

  • A: "ell" 是 shell 和 LLM 的组合。它是一个用于使用 LLM 后端的 shell 脚本。曾考虑过 "shellm"，但因可能被误解为 "she llm" 而被弃用。"ell" 更短，易于输入且易于记忆。它与任何活跃软件都不冲突。请注意，shell 脚本中 "shell" 这一名称是因为它是操作系统暴露给用户的 outer layer。它并不表示它是 CLI 或 GUI。不幸的是，它无法缩短为发音相同的 "L"，因为那会与太多事物冲突。

  • Q: 为什么用 Bash 编写？

  • A: 因为 Bash 是类 Unix 系统上最常见的 shell，而且对于此用途来说，完全没有必要使用更复杂的语言。

  • Q: ell 与其他类似项目有什么区别？

  • A: ell 几乎完全用 Bash 编写，这使其非常轻量且易于安装。它也非常易于扩展和修改。它对管道友好，这意味着它被设计为与其他工具结合使用。

Similar Projects

Testing

使用 bash tests/entry.sh 在您的主机上运行整个测试套件，或使用 bash tests/docker.sh 在 Docker 中跨受支持的 Bash 版本运行。测试是自检查且无依赖的（LLM 后端通过 ell_echo 后端和 file:// 测试数据离线运行，因此无需网络或 API 密钥）。有关布局和如何添加测试，请参阅 CONTRIBUTING.md。

贡献

欢迎贡献！请提交 issue 或 pull request。有关编码规范和测试套件，请参阅 CONTRIBUTING.md。

变更日志

有关重要变更，请参阅 CHANGELOG.md。

许可证

本项目采用 MIT 许可证。有关更多详细信息，请参阅 LICENSE 文件。