Language
English 简体中文

Sage Terminal TUI 使用指南

sage tui 是 Sage 的终端 UI 入口。它通过 Sage Python CLI launcher 启动 Rust Terminal TUI。

本文档说明面向用户的启动命令，以及开发时从源码运行的方式。

它依赖什么

TUI 不是另一套独立智能体实现，而是现有 Sage runtime 的终端前端：

  • Rust 负责终端渲染和交互
  • 本仓库里的 Sage Python CLI/backend 负责真正运行
  • 会话数据与普通 Sage CLI 共用 ~/.sage/
  • runtime workspace 默认也沿用普通 Sage CLI 的 ~/.sage/...

所以更准确地说，它是 Sage 的另一个本地使用入口，不是单独一套 agent。

前置条件

先在仓库根目录让本地 Python CLI 可用：

pip install -e .

再准备最小运行配置：

export SAGE_DEFAULT_LLM_API_KEY="your-api-key"
export SAGE_DEFAULT_LLM_API_BASE_URL="https://api.deepseek.com/v1"
export SAGE_DEFAULT_LLM_MODEL_NAME="deepseek-chat"
export SAGE_DB_TYPE="file"

如果普通 CLI 还没准备好，先检查它：

sage doctor

安装后运行

当 Sage 安装包包含 Terminal TUI 二进制时，用户不需要安装 Rust：

sage tui
sage tui coding --workspace /path/to/repo

Python CLI 在这里是 launcher：它找到包内 Terminal TUI 二进制，并把后续参数转交给它。

从源码运行

在仓库根目录执行：

cargo run --quiet --offline --manifest-path app/terminal/Cargo.toml

或者进入 crate 目录执行：

cd app/terminal
cargo run --quiet --offline

开发时构建并运行二进制 

cd app/terminal
cargo build --release
./target/release/sage-terminal

编译后的二进制位置是：

  • app/terminal/target/release/sage-terminal

这个二进制是开发和打包实现细节。面向用户的入口仍然是 sage tui。

当前支持的启动方式

目前支持这些启动形式：

sage tui
sage tui --display compact
sage tui --display verbose
sage tui --sandbox-type local
sage tui --agent-id agent_demo
sage tui coding --workspace /path/to/project
sage tui coding --sandbox-type local --workspace /path/to/project
sage tui --agent-config coding --workspace /path/to/project
sage tui --agent-id agent_demo --agent-mode fibre
sage tui --workspace /path/to/project
sage tui run "inspect this repo"
sage tui --workspace /path/to/project run "inspect this repo"
sage tui chat "hello"
sage tui config init
sage tui config init /tmp/.sage_env --force
sage tui doctor
sage tui doctor probe-provider
sage tui provider verify
sage tui provider verify model=deepseek-chat base=https://api.deepseek.com/v1
sage tui sessions
sage tui sessions 25
sage tui sessions inspect latest
sage tui sessions inspect <session_id>
sage tui resume
sage tui resume latest
sage tui resume <session_id>
sage tui --help

如果通过 cargo run 传参数，记得在中间加 --：

cargo run --quiet --offline -- resume

TUI 内置命令

当前这版预览主要包含这些命令：

  • /help
  • /agent
  • /mode
  • /display
  • /workspace
  • /sandbox
  • /goal
  • /interrupt
  • /retry
  • /new
  • /sessions
  • /resume
  • /skills
  • /skill
  • /config
  • /doctor
  • /providers
  • /provider
  • /model
  • /status
  • /transcript
  • /welcome
  • /exit

Session 行为

Terminal 现在不会在启动瞬间就立刻占用一个本地 local-000xxx session。

  • welcome 卡片初始显示的是 session: new
  • 只有真正提交第一条任务时，才会 materialize 一个本地 session id
  • 执行 /new 后，也会回到这个待创建的 new 状态，直到下一条任务真正提交

这样会更接近 Sage 的 workspace-first 行为，而不是一启动就抢占一个本地 session 编号。

Agent 选择

TUI 现在可以覆盖运行时使用的 agent，但不会自己接管 agent 配置管理。

目前支持：

  • 启动参数：
    • --agent-id <id>
    • --agent-config <path|coding>
    • --agent-mode <simple|multi|fibre>
    • --display <compact|verbose>
  • TUI 内命令：
    • /agent
    • /agent set <agent_id>
    • /agent config <path|coding>
    • /agent clear
    • /mode
    • /mode set <simple|multi|fibre>
    • /display
    • /display set <compact|verbose>

/agent set <agent_id> 和 /agent config <path|coding> 在当前 TUI 会话里互斥。设置其中一个会清掉另一个，保证下一次后端请求只使用一个 Agent 配置来源。启动时如果同时传 --agent-config 和 --agent-id，TUI 也会优先使用 --agent-config。Agent config 路径只在当前会话生效，不会被保存成持久默认值。

当 agent config 生效时，TUI 会直接显示 agent_config: coding 或 agent: config coding。由 config 接管的 mode 和 loop 设置显示为 config default。如果启动时显式传 --agent-mode，或在会话里执行 /mode set <simple|multi|fibre>，本次会话仍会用这个显式 mode 覆盖 config 里的 mode。

真正的 agent 定义、工具、skills 和行为仍然来自 Sage runtime 已保存的 agent 配置，或本次会话显式传入的 --agent-config JSON。

Coding Agent 预设

仓库提供了一个可导入的 coding 场景 Agent 配置：

  • examples/coding_agent_config.json

这个预设默认启用代码搜索、文件读写、shell、lint、todo、记忆搜索和网页抓取等工具。

TUI 可以直接从这个预设启动本次会话，不需要先去 Web 或桌面端导入。内置 JSON 可以用 coding 短别名：

sage tui coding --workspace /path/to/repo
sage tui --agent-config coding --workspace /path/to/repo

sage tui coding --workspace /path/to/repo 是直接的 TUI 快捷入口，等价于传入 --agent-config coding。

内置 coding 预设要求显式指定 workspace。如果你在 TUI 里用 /agent config coding 设置它，也要先用 /workspace set /path/to/repo 指定仓库，再发送 coding 任务。

这个预设会启用 workspaceGuidance。如果 workspace 根目录存在 AGENT.md 或 AGENTS.md，Sage 会把这些指令注入到使用该 configured agent 的请求上下文里。普通 Agent 不会因为 TUI 启动而默认加载 workspace guidance，除非它自己的 JSON config 显式启用。 其中 maxBytes 是所有已加载 workspace guidance 文件共享的总字节预算。

同一个预设也可以直接用于普通 CLI：

sage chat --agent-config coding --workspace /path/to/repo
sage run --agent-config coding --workspace /path/to/repo "inspect this repo"

如果要复制并自定义 JSON，仍然可以使用完整路径：--agent-config examples/coding_agent_config.json。

如果已经把配置保存成 Agent，也可以继续用 --agent-id <agent_id> 选择已保存的 Agent。

持久化默认值

Terminal 现在会跨启动记住这些本地默认值：

  • 当前选择的 agent_id
  • 当前选择的 agent_mode
  • 当前选择的 display 模式
  • 当前选择的 workspace override

像 /agent set、/mode set、/display set、/workspace set 这类运行时命令，会同时更新保存下来的默认值。

启动参数仍然优先于已保存默认值。比如你已经保存了 verbose，但这次执行：

sage tui --display compact

则只会在当前这次启动里使用 compact。

Display 模式

Terminal transcript 现在支持两种展示模式：

  • compact：默认模式。隐藏内部工具噪音、压缩摘要，并把 phase 名映射成更短的用户视角标签。
  • verbose：用于排查问题。会恢复内部工具步骤、step 编号和原始 phase 名。

你可以在启动时指定，也可以在 TUI 内切换：

sage tui --display verbose

/display set compact
/display set verbose

Workspace 控制

你现在可以直接在 TUI 内查看或切换当前 workspace：

/workspace
/workspace show
/workspace set /path/to/project
/workspace clear

Goal 控制

Terminal 现在可以携带共享 Sage runtime 的 session goal contract。

/goal
/goal <objective>
/goal show
/goal set <objective>
/goal clear
/goal done

/goal <objective> 会设置当前本地目标，并立即把同一句 objective 作为下一条任务提交。

/goal set 仍然只会把本地目标排入下一次请求，本身不会立刻开始执行。

输入历史与 Slash Popup

Terminal 输入框现在支持类似 shell 的历史回溯：

  • Up：回看上一条已提交输入
  • Down：向前移动，或者恢复当前草稿

Slash 命令 popup 的回车行为也做了收紧：

  • 如果 popup 可见，且当前输入还只是命令前缀，Enter 会先补全当前选中的命令
  • 如果当前输入已经是完整命令，例如 /interrupt，Enter 会直接执行，而不是再次补全

运行控制

现在 terminal 已经支持基础的会话内运行控制：

  • /interrupt：中断当前正在运行的请求，但不退出 TUI
  • /retry：在当前 session 里重新执行上一次提交的任务
  • 请求运行过程中按 Ctrl+C：中断当前请求，而不是直接退出程序

发生中断时，transcript 会尽量保留已经收到的部分输出，并附带 retry 提示，方便继续当前轮次。

Workspace 行为

默认情况下，sage tui 不会强制把当前仓库目录透传成 --workspace。

这意味着：

  • 普通终端会话继续使用 ~/.sage/... 下的默认 Sage workspace
  • AGENT.md、MEMORY.md、.sage-docs 这类文件，只有在你显式传入 --workspace <path> 时才会写进仓库目录

只有当你明确需要 repo-local 文件访问或 workspace-local skill 发现时，才建议传 --workspace。

当前定位

这版 TUI 当前主要用于：

  • 本地开发
  • 预览试用
  • 验证终端工作流

目前还不包含打包安装和二进制分发说明。

Sage documentation for the current repository layout. Source available under the MIT license.

This site uses Just the Docs, a documentation theme for Jekyll.