eve Terminal UI 终端开发指南:从本地调试到远程部署的交互式 Agent 工作台

原创2026-10-16 09:07:521,365 阅读
文章标签:人工智能AI AgentAgent 框架工具调用后端MCP ClientsAI 评测可观测性

eve Terminal UI 终端开发指南:从本地调试到远程部署的交互式 Agent 工作台

eve dev 是 eve 框架内置的交互式开发入口:它启动一个本地开发服务器,并打开一个基于终端的 UI(Terminal UI,TUI),让你在同一块屏幕上完成与 Agent 对话、审批工具调用、回答 Agent 提问、切换模型与速度、安装集成乃至部署到 Vercel 等全部日常开发操作。读完本文,你将掌握 TUI 的全部斜杠命令与快捷键、连接配置与凭据管理原理、模型与推理设置方法、日志与 trace 排查手段,以及用 eve remote connect 直连线上部署的完整流程。

eve dev:本地开发服务器与终端 UI 一体启动

eve dev 会启动一个本地开发服务器,并打开交互式终端 UI。它的典型用途是与你的 Agent 对话、审批工具调用、回答 Agent 的问题,以及配置本地开发环境。当 eve dev 启动本地服务器时,自我修改(Self-Modification)默认可用,相关机制可参考 Self-Modification。

eve dev

从源码看,eve dev 的完整行为由 packages/eve/src/cli/dev/command.ts 注册并驱动:它会先判断当前终端是否为 TTY(process.stdin.isTTY && process.stdout.isTTY)来决定进入 TUI 模式还是 headless 模式,然后通过 local-server-process.ts 启动 DevelopmentServer,最后调用 runInteractiveDevelopmentUi 把本地服务器与终端 UI 绑定。若终端不是 TTY,eve dev 会降级为纯服务器模式并输出 server listening at <url>,提示交互 UI 因终端非 TTY 被禁用。

读懂状态栏:模型、速度与连接一目了然

TUI 的底部状态栏(footer)用点分隔显示当前激活模型、推理等级(已设置时)、速度指示器与连接,例如:

gpt-6-luna · high · ⚡︎
  • 模型标签:省略提供方前缀,并且只移除末尾的 -fast 后缀;
  • ⚡ 速度标记:单个 ⚡︎ 表示模型带 -fast 后缀或显式选择了 Fast 模式;不支持 Unicode 的终端会改用 ASCII 标记;
  • Vercel 账号连接:在解析出团队 slug(team slug)后显示团队名,本地服务器端口号不显示。

退出 TUI 后,完整对话记录(transcript)仍保留在终端滚动缓冲区中,方便随时回溯。在 UI 中运行 /help 可查看当前会话可用的全部命令。

在发送第一条消息之前,空的输入框(composer)可能会提示你让本地 Agent 编辑自身指令、或添加一个工具(tool)或频道(channel)。该提示取决于 Agent 当前具备的能力;直接输入文字即可覆盖提示,不会发送消息,也不会改动任何文件。

斜杠命令总览:TUI 的完整控制面板

TUI 通过斜杠命令提供几乎所有开发控制能力:

命令 说明
/model 选择模型、速度与推理等级。传模型 ID 可直接设置:/model provider/model-id
/new 开启全新会话并清屏。/reset 是其别名
/clear 清空当前会话的模型消息历史,但保留会话本身
/compact 压缩当前会话的上下文
/cancel 取消当前回合(turn),不丢弃已沉淀的上下文
/login 连接 ChatGPT 订阅、Vercel 账号或提供方 API Key
/add 选择并安装频道、MCP 连接、扩展与可观测性集成。传条目地址可直接安装:/add channel/slack
/deploy 将 Agent 部署到 Vercel 生产环境。必要时会自动安装 Vercel CLI、登录并关联目录
/traces 打开本地 trace 查看器。传 trace ID 前缀可打开指定 trace
/loglevel 选择在对话记录中显示哪些服务器与 Agent 日志
/info 展示解析后的应用、编译产物、发现诊断与消息路由
/help 列出可用命令
/exit 退出 UI

这些命令并非硬编码在渲染器里,而是由一份注册表统一管理。在 packages/eve/src/cli/dev/tui/prompt-commands.ts 中,每个命令都声明了别名、参数提示(argumentHint)、是否接收参数、历史策略以及可用目标(targets)。这份注册表同时驱动了 runner 的调度、渲染器的回显抑制与命令发现,保证三处不会漂移。例如:

  • /model、/login、/add、/deploy、/traces、/info 的 targets 只有 ["local"]——它们依赖本地 eve dev 服务器;
  • /new、/clear、/compact、/cancel、/loglevel、/help、/exit 同时支持 local 与 remote;
  • /exit 还有别名 /quit,/reset 是 /new 的别名。

命令解析器只识别斜杠前缀开头的指令,未知的 /text 会被当作普通消息发送。/help 打印的命令表格也由该模块的 formatPromptCommandHelp 生成,列宽自动对齐。

遭遇 stranded session(搁浅会话)时

当一条消息或一次流重连进入 stranded session 时,TUI 会说明原因以及构建它的 eve 版本(若已知)。此时新消息与审批不会被投递,你需要运行 /new 结束该搁浅会话——你的下一条消息会开启一个全新会话。/clear 会被拒绝,因为它会保留这个无法运行的搁浅会话。由同一个 eve 版本构建的、来自上一次 eve dev 进程的会话不算搁浅,参见 Local workflow recovery。升级前已接受的消息不会被重新投递。

从协议层看,stranded session 是 execution-model-and-durability 中的一等公民:eve HTTP 频道对 stranded session 返回 409 session_stranded 并携带构建版本,TypeScript 客户端停止重连并上报 ClientSessionStrandedError,TUI 则负责解释如何恢复。若你希望尝试继续上一次 eve dev 遗留的未完成运行,可以在启动时加 --resume 标志,详见 Local workflow recovery。

另外需要注意:/login、/model、/add、/deploy、/info、/traces 仅在 eve dev 本地运行时可用;当 UI 通过 eve remote connect 连接远程 Agent 时这些命令不可用。prompt-command-handler.ts 中的调度层会先根据 isPromptCommandAvailableFor 校验目标,若在 remote 目标上调用本地命令,会直接返回 "/xxx needs eve dev running the local server..." 的明确提示,而不会静默失效。

新建 Agent:init 到 TUI 的无缝衔接

在交互式 eve init 完成后,TUI 会直接打开。eve 会保留项目已选定的连接(connection);对于新连接,它依次检查:显式的环境凭据 → 本机保存的默认连接 → Vercel CLI 当前的团队。既有的项目 OIDC 连接仍然受支持。自动化的 Vercel 复用会验证账号访问权限,但不会创建或关联新项目。

启动期间,composer 保持可见,进度指示器会显示当前正在检查哪个连接,以及 eve 正在准备聊天。此时直接输入消息并回车,消息会进入队列,待 Agent 就绪后自动发送。当某个选择或 API Key 需要输入时,选择器(picker)会临时接管输入焦点;你的草稿会在选择器关闭后原样返回。若 setup 被取消或失败,已排队的消息会退回草稿。

五种登录方式

如果没有可用连接,/login 会提供以下选项:

  1. Vercel Account
  2. Vercel AI Gateway API Key
  3. ChatGPT Subscription
  4. OpenAI API Key
  5. Anthropic API Key

Vercel 账号登录会打开浏览器完成授权。当存在多个团队时,/login 会显示一个可搜索的团队选择器,并高亮当前项目或 CLI 关联的团队,方便切换;只有一个可用团队时会自动选中。自动启动复用已选连接,不会再次弹出该选择器。账号令牌(account-token)对 Gateway 的访问取决于你的账号与团队是否可用;若不可用,请改用 API Key 或其他连接。

菜单操作统一为:输入文字过滤、Enter 选中、Esc 返回聊天;也支持方向键导航。关闭 setup 菜单不会在对话记录中追加取消消息,但已完成的工作与失败仍会显示。取消登录会保留你的草稿。若连接失败,重试 /login 即可;eve 不会静默切换提供方。

凭据与部署:秘密进 OS 钥匙串,元数据进 .eve/provider.json

eve 通过 just-secrets 将 API Key 与 eve 自有的 OAuth 刷新凭据保存在操作系统密钥库(OS secret store)中。实现见 packages/eve/src/internal/model-auth/store.ts:以 service: "eve" 为命名空间读写秘密,单条秘密大小限制为 2560 字节,密钥库未解锁时会抛出明确错误提示“Unlock it and retry /login”。

同时,eve 会把最后一次成功登录保存为本机默认连接,并把项目的连接与团队作为非秘密元数据记录在 .eve/provider.json 中(路径定义见 packages/eve/src/setup/provider-settings.ts)。要点如下:

  • 新输入的 Key 永远不会写入项目文件;
  • 通过 /login 显式选择的 Key 会优先于 shell 中同名提供方的其他 Key;
  • 通过环境凭据连接的项目会继续使用其环境变量(.env / .env.local);
  • Vercel CLI 保留对自己凭据与刷新令牌的所有权。

本地发现(local discovery)仅限开发环境。部署需要显式配置 AI_GATEWAY_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY 或受支持的项目 OIDC 凭据;ChatGPT 订阅模型仅限本地使用。/login 不会关联部署或认证远程服务器——Vercel CLI 的安装与账号登录由 /deploy 在需要时处理。

模型与设置:/model 三步走

/model 按顺序引导你完成模型 → 速度 → 推理等级的选择:

  1. 选择模型:输入文字过滤列表;
  2. 选择 Standard 或 Fast 速度(模型支持时);
  3. 选择推理等级(模型支持推理设置时);Provider default 表示把推理等级交给提供方决定。

选择器会高亮当前设置中与所选模型兼容的部分,并跳过无法修改的设置项。↑ / ↓ 移动,Enter 进入下一步或应用最终选择;Esc 或 ← 返回上一步,在模型列表处二者都会取消;Ctrl+C 可从任意步骤取消。所有变更在最终选择后一起应用,然后选择器返回聊天;取消则保持原模型与设置不变。

成功的登录或模型变更在下一条 prompt 生效。/model 也支持带参数直接设置,例如:

/model openai/gpt-6-luna-fast
/model provider/model-id high

从 prompt-command-handler.ts 的实现看,/model 的参数解析支持 default | none | minimal | low | medium | high | xhigh 七种推理等级;对于无法通过字符串重写的 SDK 模型表达式,会先执行 modelChangeRefusalForUneditableModel 检查并明确拒绝(这类动态或自定义模型表达式需要直接在 agent.ts 中编辑),而不是静默跳过。

各连接的默认模型:

连接 默认模型
Gateway 连接 openai/gpt-6-luna-fast
OpenAI / ChatGPT gpt-6-luna-fast
Anthropic claude-sonnet-5

显式编写且兼容的模型会被保留;若新默认模型不可用,eve 会提供该连接可用的模型列表。

添加集成:/add 一站式安装

/add 打开一个可搜索的目录(catalog),涵盖频道(channels)、连接(connections)、扩展(extensions)与可观测性集成。输入文字过滤,Enter 安装选中项并运行其必需的 setup,完成后返回聊天。

也可以直接传入条目地址安装:

/add channel/slack
/add extension/agent-browser
/add channel/linear
/add @acme/analytics

必需的授权或部署 setup 仍会为选中项执行。按 Esc 可取消 setup,但已安装到项目中的文件会保留。如果依赖安装失败,可在终端重跑 eve add 命令查看详细报错——原始安装器输出不会被捕获进 TUI。

与 Agent 协作:从发送消息到实时 steering

输入消息并按 Enter 发送。当 Agent 提问或请求工具审批时,在 UI 展示的 prompt 中直接作答,每条回答会立刻发送。多个请求同时打开时,prompt 会显示当前所处位置(如 2 of 5)并给出提问任务的名称(与对话记录行一致)。连接授权可能打开浏览器——请保持本地 eve dev 运行,直到浏览器回到该界面。

活动行:Thinking / Generating / Running

活动行(activity line)反映模型与工具的执行状态:

  • Thinking:模型推理中或等待回复;
  • Generating:模型书写回复或工具输入;
  • Running:工具执行中。

闪烁圆点与已用时间表示进度,有 token 计数时一并显示。当 tasks 在工作时,抽屉头部会替代该行:显示父任务的当前活动、任务数量与回合已用时间(无 token 计数);Waiting 表示父任务在等待子任务;Working 在回合间隙任务仍活跃时出现,且不显示回合计时。

工具调用的命名规则

工具调用显示工具自身的 label;内置工具使用 eve 的文案,如 Read README.md。其他调用显示去掉扩展名或连接前缀后的可读名,例如 linear__list_issues 显示为 List issues。审批 prompt 同样使用该命名,如 Approve Linear: List issues?。

任务抽屉(activity drawer)

一次任务调用(如调用 subagent)在开始时写一行到对话记录,结束时(完成、失败或被停止)再写一行,结束行注明耗时,subagent 还会总结做了什么,如 Read 3 files, Ran 2 commands。任务开始时使用与同步调用相同的工具调用样式。任务执行期间,prompt 上方会打开一个活动抽屉,展示每个任务的名称、当前活动与已用时间,不重复其启动 prompt:

  • subagent 使用可读标签,如 subagent(stock price)(stock-price subagent)或 subagent(worker)(code 扩展的 code__worker),名称旁显示已用时间,最新观察到的工具以手肘线(elbow)形式分组在其下;
  • 工具在两次调用之间保持可见,而非切换为“开始中”占位符;
  • 提问与审批期间,屏幕空间允许时活动信息保持在请求上方,并用共享分隔线隔开;小终端上请求优先;
  • 被跟随的 subagent 启动的后台工作显示在其下方;更深层的工作改用**所有权路径(ownership path)**而非继续缩进;
  • 面板有高度上限,溢出时优先展示需要审批的任务;
  • UI 不显示模型自身的 eve__task_wait 与 eve__task_cancel 调用,其效果体现为 Waiting 头部与已停止任务的记录行。

提示框常驻与实时 steering

Agent 工作时 prompt 始终保持打开,包括从其他入口(如定时任务)启动的回合。回合运行中按 Enter 发送的消息会被立即当作 steering(转向指令)。从 runner.ts 的实现可以看到关键机制:

  • 当回合处于工作状态时,#submitMessage 会以 turnPolicy: "steer" 发送,加入当前回合而不是排队;
  • 空闲时则使用 turnPolicy: "queue" 排队。

在助手输出开始前,runtime 会中断正在进行的模型生成,并在同一个回合中继续处理你的修正;已执行中的工具会安全收尾。输出开始后,steering 会在下一个 workflow 边界生效,并保留已流式输出的文本。

斜杠命令可以立即执行,即使回合正在运行。按 Esc 或 Ctrl+C,或运行 /cancel 可取消运行中的回合。若在回合尚未开始时取消,eve 会等待该回合的 ID 再发送取消,因此请求不会误取消后续回合。若取消迟迟未落定,再次按 Ctrl+C 停止等待:eve 会开启一个新会话,下一次 Ctrl+C 退出。在空闲 prompt 下连按两次 Ctrl+C 退出。

键盘快捷键一览

按键 作用
Enter 发送当前消息或回答
Shift+Enter 插入换行(需要终端支持 modified keys)
Esc 取消运行中的回合
Ctrl+C 取消运行中的回合;再按一次停止等待并开新会话;空闲时连按两次退出
↑ / ↓ 在输入行或已发送消息历史中移动
Ctrl+L 循环切换日志显示模式
Ctrl+R 重绘屏幕

日志与追踪:把每一行输出都变成排查线索

默认情况下,UI 只显示带严重级别标记的错误。使用 /loglevel <none|error|warn|debug|all> 调整显示级别;裸 /loglevel 报告当前设置:

  • warn:增加警告;
  • debug:显示所有带严重级别标记的记录;
  • all:额外显示未分类的 stdout、stderr 与沙箱输出;
  • none:隐藏所有日志。

错误显示为红色,警告为黄色,未分类的 stderr 为中性色。Ctrl+L 循环切换同样的模式。注意:这些模式只是过滤已接收的记录,不会改变 EVE_LOG_LEVEL,也不会开启依赖的 debug 日志。

Workflow SDK 的输出(如标记为 [workflow-sdk] 或 [world-local] 的行)报告内部 runtime 细节,因此对话记录仅在 all 模式下显示它们。

无论显示模式如何,每个 eve dev 进程都会把诊断日志写入 .eve/logs/,可用 eve logs 读取——支持 eve logs show <a href="https://link.gitcode.com/i/37015865d54e801d78bd82a2ebf4926a" target="_blank">logid] 与 eve logs list(含 --json 机器可读输出),日志按进程按最近优先排序。相关实现在 [packages/eve/src/cli/commands/logs.ts。

使用 /traces 可检查本地开发期间记录的 trace,传递 trace ID 前缀可打开指定 trace。trace 的捕获与保留设置参见 Local traces。

显示选项:eve dev 标志位

使用 eve dev 标志位控制工具调用、推理、subagent、连接授权、响应统计、上下文用量与日志的显示:

eve dev --tools full --reasoning collapsed --logs all

常用标志说明:

标志 可选值 / 说明
--tools <mode> full / collapsed / auto-collapsed / hidden,控制工具调用如何渲染
--reasoning <mode> full / collapsed / auto-collapsed / hidden,控制推理如何渲染
--subagents <mode> collapsed(默认)/ full / hidden;full 还会在 subagent 消息与工具调用完成时逐条写入对话记录,hidden 则完全从对话记录与任务面板中移除 subagent 任务
--connection-auth <mode> 连接授权如何渲染:full / collapsed / auto-collapsed / hidden
--assistant-response-stats <mode> 助手头部统计:tokens 或 tokensPerSecond
--context-size <tokens> 模型上下文窗口大小,以用量百分比显示
--logs <mode> 日志严重级别:none / error / warn / debug / all
--host <host> 绑定的主机接口
--port <port> 监听端口(默认取 $PORT,其次为 2000)
--no-ui 只启动服务器,不启动终端 UI
--resume 尝试恢复上一次本地 dev 遗留的运行
--name <name> 终端 UI 中显示的标题(默认为应用目录名)
--input <text> 预填充 prompt 输入

显示选项的默认值定义在 packages/eve/src/cli/dev/ui-options.ts:日志默认 error,推理默认 auto-collapsed(折叠的推理渲染为固定的 thinking 行,--reasoning full 恢复流式对话轨迹),工具调用默认 auto-collapsed。注意:--tools、--reasoning、--connection-auth 与 --subagents 的取值细节一致时,--tools auto-collapsed 与 --tools hidden 的差异在于折叠后是否保留标题行。

另外,设置 EVE_TUI_RENDER_MARKDOWN=0 可让助手与 subagent 回复不做 Markdown 解析与样式渲染(1 为默认,启用 Markdown 渲染),实现见 packages/eve/src/cli/dev/tui/markdown.ts。完整的 eve dev 选项列表、可选值与默认值参见 eve dev CLI 参考。

连接部署:eve remote connect

把终端 UI 接到一个已存在的 eve 服务器(而不是本地启动一个),直接传 URL:

eve remote connect --url https://your-app.vercel.app

需要发送凭据或自定义请求头时,使用带 HTTP Basic 凭据的 URL,或重复 -H, --header:

eve remote connect --url https://user:pass@your-app.example.com
eve remote connect --url https://your-app.example.com -H 'Authorization: Bearer your_token_here'

要点:

  • 远程 Vercel 会话会复用已授权的 CLI 会话,不会打开账号登录流程,也不会修改本地项目的 Vercel 关联或 .env.local;
  • --header 解析为 Name: value 形式且可重复,URL 目标解析与请求头注入逻辑见 command.ts;
  • 远程会话同样接受 --tools、--reasoning、--subagents、--connection-auth、--assistant-response-stats、--context-size、--logs 等显示标志,以及 --name(UI 标题)与 --input(预填充输入);
  • 非交互终端下运行 eve remote connect 会直接报错:eve remote connect requires an interactive terminal.

Deployment Protection(部署保护)

当 Vercel 的 Deployment Protection 阻止启动时,eve 会先验证目标项目,并询问是否添加 Trusted Sources 规则以获得对该部署环境的开发访问权。批准后,eve 应用该规则并再次检查访问权限,通过后才回到聊天。取消会保留你的草稿;重新执行 eve remote connect --url <url> 可重试。如果你无权修改项目策略,可提供 VERCEL_AUTOMATION_BYPASS_SECRET,或请项目管理员在 Deployment Protection 设置中配置访问权限。

下一步阅读

登录后查看全文
eve