agentic_huge_data_base / wiki
页面 Onyx · 13.2 CLI (onyx-cli)·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 13.2

13.2 · CLI (onyx-cli)

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节13.2 状态全文译文 模块安装与启动、界面与交互、配置治理、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节CLI (onyx-cli) 上一章13.1 下一章13.3
源码线索
  • cli/cmd/chat.go
  • cli/cmd/experiments.go
  • cli/cmd/root.go
  • cli/internal/config/config.go
  • cli/internal/config/config_test.go
  • cli/internal/config/experiments.go
  • cli/internal/starprompt/starprompt.go
  • cli/internal/tui/app.go
  • cli/internal/tui/commands.go
  • cli/internal/tui/experiments.go
模块标签
  • 安装与启动
  • 界面与交互
  • 配置治理
  • 测试、发布与运维
  • 接口与服务契约

章节正文

CLI (onyx-cli)

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/13.2-cli-onyx-cli

CLI (onyx-cli)

相关源文件

本章引用的主要源码文件：

  • cli/cmd/chat.go
  • cli/cmd/experiments.go
  • cli/cmd/root.go
  • cli/internal/config/config.go
  • cli/internal/config/config_test.go
  • cli/internal/config/experiments.go
  • cli/internal/starprompt/starprompt.go
  • cli/internal/tui/app.go
  • cli/internal/tui/commands.go
  • cli/internal/tui/experiments.go
  • cli/internal/tui/help.go
  • cli/internal/tui/input.go
  • cli/internal/tui/viewport.go
  • cli/internal/tui/viewport_test.go
  • deployment/docker_compose/docker-compose.onyx-lite.yml
  • deployment/docker_compose/install.ps1
  • deployment/docker_compose/install.sh
  • deployment/helm/charts/onyx/values-lite.yaml

Onyx CLI（onyx-cli）是一个基于 Go 语言的终端界面，提供了一种轻量级、高性能的方式来与 Onyx 服务器交互。它既支持交互式终端用户界面（TUI）聊天会话，也支持一次性命令行查询，使开发者和高级用户无需离开终端环境即可访问 Onyx 知识库。

安装与分发

该 CLI 使用 Go 语言编写，并打包为 Python wheel 格式，通过 pip 或 uv 进行分发。这使其能够在 Linux、macOS 和 Windows 平台上跨平台安装。

  • Pip/UV 安装： 用户可以使用 pip install onyx-cli 或 uv tool install onyx-cli 安装 CLI。
  • 构建系统： 项目使用 hatchling 作为构建后端，并带有自定义构建钩子（hatch_build.py），在 wheel 创建过程中编译 Go 二进制文件。
  • 精简部署： 对于资源受限的环境，Onyx 提供了"精简"模式（通过 install.sh --lite 或 docker-compose.onyx-lite.yml），该模式会禁用 Vespa 和模型服务器等重型服务，同时仍允许通过 PostgreSQL 后端实现 CLI 聊天和文件上传功能 deployment/docker_compose/install.sh:33-36，deployment/docker_compose/docker-compose.onyx-lite.yml:4-8。
自动化发布管线

CLI 发布流程由匹配 cli/v*.*.* 模式的 Git 标签触发。GitHub Action 会为 linux、windows 和 darwin 平台构建 amd64 和 arm64 架构的 wheel 包。

配置

CLI 通过配置文件或环境变量来识别目标 Onyx 服务器并进行认证。

配置文件

设置存储在一个 JSON 文件中，路径为： ~/.config/onyx-cli/config.json cli/internal/config/config.go:71-73。目录由 ConfigDir() 确定，该函数会遵循 XDG_CONFIG_HOME 环境变量 cli/internal/config/config.go:59-68。

环境变量

环境变量优先于配置文件 cli/internal/config/config.go:101-120：

  • ONYX_SERVER_URL：Onyx API 的基础 URL（例如 https://cloud.onyx.app）。cli/internal/config/config.go:12
  • ONYX_API_KEY：用于认证的个人访问令牌（PAT）或 API 密钥。cli/internal/config/config.go:13
  • ONYX_PERSONA_ID：要使用的默认代理 ID。cli/internal/config/config.go:14
  • ONYX_STREAM_MARKDOWN：控制流式传输期间是否进行渐进式 Markdown 渲染（true/false）。cli/internal/config/config.go:16

config.Load() 函数负责从文件加载配置并应用环境变量覆盖 cli/internal/config/config.go:98-122。

命令与功能

CLI 使用 cobra 库进行命令路由 cli/cmd/root.go:70-113，并使用 bubbletea 进行 TUI 渲染 cli/cmd/chat.go:44-45。

一次性查询（ask）

ask 命令允许用户执行单次检索增强生成（RAG）查询。CLI 与后端 API 通信，检索相关文档并基于默认或指定的 Persona 生成响应。

交互式 TUI 聊天

交互模式提供完整的基于终端的聊天体验。当未指定子命令时，这是默认命令 cli/cmd/root.go:104-110。首次运行时，交互式设置向导（onboarding.Run）会引导用户完成配置 cli/cmd/chat.go:27-33。

  • 斜杠命令： 通过 handleSlashCommand 分发 cli/internal/tui/commands.go:17。
    • /help：显示可用命令和快捷键 cli/internal/tui/help.go:3-15。
    • /clear / /new：重置会话并重新添加启动画面 cli/internal/tui/commands.go:83-101。
    • /agent：列出可用代理并允许切换 cli/internal/tui/commands.go:103-110。
    • /attach <path>：通过 client.UploadFile 上传文件到后端 cli/internal/tui/commands.go:143-160。
    • /sessions：使用 client.ListChatSessions 浏览之前的会话 cli/internal/tui/commands.go:162-169。
    • /configure：指示用户运行 onyx-cli configure cli/internal/tui/commands.go:45-47。
    • /connectors：在浏览器中打开服务器的索引状态页面 cli/internal/tui/commands.go:52-59。
    • /experiments：列出实验性功能及其状态 cli/internal/tui/commands.go:70-72。
    • /quit：退出 CLI cli/internal/tui/commands.go:74-75。
  • 键盘快捷键：
    • Enter：发送消息。
    • Escape：取消当前生成。
    • Ctrl+O：切换来源引用显示 cli/internal/tui/help.go:20。
    • Ctrl+D：退出（按两次）cli/internal/tui/help.go:21。
  • 视口管理： viewport 结构体管理消息历史 cli/internal/tui/viewport.go:52-70。它使用 glamour 进行 Markdown 渲染 cli/internal/tui/viewport.go:73-82。如果启用了 streamMarkdown，它会每 100 毫秒渐进式渲染一次 cli/internal/tui/viewport.go:49-50，cli/internal/tui/viewport.go:129-143。
SSH 服务模式

CLI 可以通过 serve 命令充当 SSH 服务器 cli/cmd/root.go:99，允许用户通过 SSH 连接到特定端口并立即进入 Onyx 聊天会话。此模式利用了 charmbracelet/ssh 和 charmbracelet/wish。

数据流：CLI 到后端

下图展示了 CLI 如何与核心 Onyx 基础设施交互。

CLI 请求编排

Onyx · 数据流：CLI 到后端 · 图 1
Onyx · 数据流：CLI 到后端 · 图 1

来源：cli/cmd/root.go:65-113，cli/cmd/chat.go:24-45，cli/internal/config/config.go:98-122，cli/internal/tui/commands.go:17-81，deployment/docker_compose/docker-compose.onyx-lite.yml:55-59

实现细节：TUI 视口

viewport 是用于渲染对话的核心组件。它跟踪 chatEntry 对象，这些对象区分用户消息、代理响应和引用来源。

视口实体关联

Onyx · 实现细节：TUI 视口 · 图 2
Onyx · 实现细节：TUI 视口 · 图 2

来源：cli/internal/tui/viewport.go:18-32，cli/internal/tui/viewport.go:52-70，cli/internal/tui/viewport.go:110-117，cli/internal/tui/viewport.go:168-180，cli/internal/tui/viewport.go:220-243

关键函数和类
  • newChatCmd()：初始化 chat 命令，这是默认的交互式 TUI 模式 cli/cmd/chat.go:12-53。
  • Execute()：Cobra CLI 的主入口点，负责解析参数和分发命令 cli/cmd/root.go:65-113。
  • config.OnyxCliConfig：定义 CLI 配置参数的结构体，包括 ServerURL、APIKey 和 DefaultAgentID cli/internal/config/config.go:28-32。
  • tui.Model：交互式聊天 TUI 的中央 bubbletea 模型，管理状态、输入和渲染。
  • tui.viewport：管理 TUI 中聊天消息、代理响应和引用来源的显示 cli/internal/tui/viewport.go:52-70。
  • starprompt.MaybePrompt()：一次性提示，鼓励用户给 GitHub 项目加星，在 TUI 启动前显示 cli/internal/starprompt/starprompt.go:46-83。

来源：cli/cmd/root.go:65-113，cli/cmd/chat.go:12-53，cli/internal/config/config.go:28-32，cli/internal/config/config.go:98-122，cli/internal/tui/viewport.go:18-70，cli/internal/tui/commands.go:17-81，cli/internal/starprompt/starprompt.go:46-83，deployment/docker_compose/docker-compose.onyx-lite.yml:1-33