Skip to content

功能规格说明:桌面端内嵌终端 ​

本规格描述右侧面板里的「终端」这个实例。面板槽位(tab 栏、开合、宽度)见 desktop-right-panel.md。

用户场景与测试 ​

用户故事:内嵌终端面板(优先级:P2) ​

作为用户,我希望在对话旁打开一个真正的终端,直接在该对话工作目录里运行命令(包括 vim、top 等交互式程序),以便我无需离开应用即可验证 agent 的改动或执行辅助操作。

为什么是这个优先级:终端是 desktop 对标编辑器内建终端的关键能力;真 PTY 方案(node-pty)才能承载交互式程序,是该能力的可用性底线。

独立测试:打开终端面板,运行 ls、启动 top 后按 q 退出、Ctrl+C 中断一个长命令;调整面板宽度验证终端换行自适应;折叠面板再展开验证会话与输出保留;关闭终端 tab 再重新打开验证宿主 PTY 重挂接(同一会话 + 滚动缓冲回放)。

验收场景:

  1. 假设用户打开终端面板(空态入口/「+」菜单/菜单栏「面板 → 终端」),当面板首次打开,则必须以该对话工作目录(worktree 会话为 worktree 路径)为 cwd 启动用户默认 shell 的登录交互会话(macOS/Linux 取 $SHELL,Windows 取 PowerShell),渲染完整提示符与环境变量。
  2. 假设终端已打开,当用户输入命令、运行交互式 TUI 程序(如 vim/top)、按 Ctrl+C,则行为必须与系统终端一致:按键全量透传、程序输出(含 ANSI 颜色)正确渲染、Ctrl+C 中断前台程序。
  3. 假设用户调整面板宽度或窗口大小,当终端可视尺寸变化,则必须同步 PTY 行列数,输出按新宽度重排。
  4. 假设终端面板已打开,当用户折叠面板(头部按钮)再展开,则槽位仅 display:none 隐藏,终端 tab 保持挂载、shell 会话与滚动输出原样保留(隐藏不终止);关闭 terminal tab 仅移除该视图——宿主 PTY 不销毁(键 term-<paneId>,见「面板关闭销毁」边界),再次打开终端面板时重挂接同一 shell 并回放滚动缓冲;面板工具栏必须提供「重启终端」操作(终止并重建会话)。
  5. 假设用户关闭分屏、删除会话或退出应用,当对应终端存在,则必须终止其 PTY 进程,不得残留孤儿进程。
  6. 假设终端面板可见时该分屏切换到另一条会话,则原会话的终端随会话切换终止 PTY(跨会话切换不保留滚动输出);目标会话记忆有终端 tab 时按目标会话工作目录新建终端会话,切回原会话重新显示终端时同样按原会话工作目录重建。
  7. 假设终端已打开,当用户选中文本复制或使用系统粘贴快捷键,则必须与系统剪贴板互通。
  8. 假设 node-pty 原生模块加载失败,当用户打开终端面板,则面板内必须显示可操作的错误提示,不得崩溃或影响其他面板。
  9. 假设终端输出中包含 http(s) 链接(如 http://localhost:5173),当用户点击该链接,则行为必须与消息中的链接一致:localhost 链接(localhost、127.0.0.1、[::1],任意端口)在右侧预览面板打开并加载该 URL(新增/激活 preview tab 的实例语义见「一级 Tab 栏与实例语义」场景 1-2,预览未打开时自动展开面板);非 localhost 链接用系统默认浏览器打开。

边界情况 ​

  • 删除 worktree 会话时其终端仍在运行:删除/清理流程必须先终止该分屏的终端 PTY,再执行 worktree 清理,避免进程占用目录导致清理失败。

  • 终端内进程正在运行:退出应用或删除会话时强制终止 PTY(含其子进程),不等待前台命令结束。

  • 各分屏/会话的终端 tab 相互独立:终端 tab 按分屏(pane)寻址(term-<paneId>),输入输出互不串台;同一会话切换分屏展示时终端按新 pane 独立。

非目标(明确排除) ​

  • 终端多标签与终端内分屏:首版每会话至多一个终端 tab(唯一实例),终端面板内不再分屏。

  • 终端内搜索:首版不做。