eve Terminal UI 终端开发指南:从本地调试到远程部署的交互式 Agent 工作台
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 会提供以下选项:
- Vercel Account
- Vercel AI Gateway API Key
- ChatGPT Subscription
- OpenAI API Key
- 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 按顺序引导你完成模型 → 速度 → 推理等级的选择:
- 选择模型:输入文字过滤列表;
- 选择 Standard 或 Fast 速度(模型支持时);
- 选择推理等级(模型支持推理设置时);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-pricesubagent)或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 设置中配置访问权限。
下一步阅读
- Instrumentation:trace、OpenTelemetry 与诊断;
- CLI 参考:全部命令与标志位;
- Agent Client Protocol (ACP):用 Zed 等 ACP 客户端驱动同一个 Agent,而不使用 TUI。