---
url: /wave-agent/specs/desktop/desktop-terminal-panel.md
description: CodeWave IDE 桌面端内嵌终端面板：以对话工作目录启动真 PTY、交互式程序与 Ctrl+C、尺寸同步、折叠保活与关闭销毁、终端内链接点击
---

# 功能规格说明：桌面端内嵌终端

> 本规格描述右侧面板里的「终端」这个实例。面板槽位（tab 栏、开合、宽度）见 [desktop-right-panel.md](./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（唯一实例），终端面板内不再分屏。

* **终端内搜索**：首版不做。