# 内嵌终端模块技术设计文档

> 版本：v1.0 | 日期：2026-06-05 | 状态：设计中

## 1. 需求概述

### 1.1 功能目标

在 Electron 桌面客户端中内置终端模块，替代现有的"打开系统终端"功能，提供类似 VSCode Terminal 的使用体验。

### 1.2 核心需求

| 项目 | 描述 |
|------|------|
| 位置 | 底部面板，挤压上方内容区域 |
| 多终端 | 支持多 Tab，创建、切换、关闭 |
| 默认 cwd | LOCAL 模式跟随任务工作区，CLOUD 模式打开本地 home 目录 |
| Shell | 读取用户 `$SHELL` 环境变量（macOS 默认 zsh，Linux 默认 bash） |
| 审批 | 无审批机制，用户直接操作 |
| 权限 | 所有登录用户可用 |
| 持久化 | 轻量方案，纯内存，关闭/重启后不恢复 |
| 面板高度 | 可拖拽调整，默认收起 |
| 快捷键 | `` Ctrl+` `` 展开/收起终端面板 |

### 1.3 V1 范围

**包含：**
- 底部面板 + 可拖拽高度
- 多终端 Tab（创建、切换、关闭）
- 真实 PTY + xterm.js 渲染
- ANSI 颜色、基本键盘交互
- 自动检测 `$SHELL`
- 默认 cwd 跟随工作区
- 快捷键展开/收起

**不含（V2）：**
- 终端内搜索
- 链接可点击
- 分屏
- 终端字体/主题配置
- cwd 与任务同步
- 终端输出持久化

## 2. 架构设计

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                    Renderer (Vue 3)                      │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  TaskView                                         │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  Chat Area (messages + input)               │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  TerminalPanel (可拖拽高度)                   │  │  │
│  │  │  ┌─────┬─────┬─────┬─────┐                 │  │  │
│  │  │  │Tab 1│Tab 2│Tab 3│  +  │  ← TerminalTabs  │  │  │
│  │  │  └─────┴─────┴─────┴─────┘                 │  │  │
│  │  │  ┌───────────────────────────────────────┐  │  │  │
│  │  │  │  xterm.js Terminal Instance           │  │  │  │
│  │  │  │  (每个 Tab 对应一个 xterm 实例)        │  │  │  │
│  │  │  └───────────────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
│                        │ window.electronAPI.terminal.*   │
│                        ▼ IPC                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Preload Bridge (contextBridge)                   │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                    Main Process                          │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  TerminalManager                                  │  │
│  │  ┌─────────────────────────────────────────────┐  │  │
│  │  │  terminalSessions: Map<id, TerminalSession>  │  │  │
│  │  │  ┌──────────────┐  ┌──────────────┐        │  │  │
│  │  │  │ Session 1    │  │ Session 2    │  ...   │  │  │
│  │  │  │ pty (node-pty)│  │ pty          │        │  │  │
│  │  │  │ shell: zsh   │  │ shell: bash  │        │  │  │
│  │  │  │ cwd: /workspace│ │ cwd: ~      │        │  │  │
│  │  │  └──────────────┘  └──────────────┘        │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 2.2 与现有架构的关系

终端模块是**完全独立的新通道**，不与现有 Agent 工具执行体系耦合：

- **不复用** `shellSessions`（现有 marker 模式 shell 会话）
- **不复用** `handleShellFromWebSocket`（现有工具执行逻辑）
- **不经过** WebSocket 连接后端服务
- **不经过** 工具审批流

IPC 通道完全独立，使用新的 `terminal:*` 命名空间。

## 3. 详细设计

### 3.1 新增依赖

```jsonc
// package.json 新增
{
  "dependencies": {
    "@xterm/xterm": "^5.5.0",           // 终端模拟器 UI
    "@xterm/addon-fit": "^0.10.0",      // 自适应尺寸
    "@xterm/addon-web-links": "^0.11.0" // 链接检测（V2 启用）
  },
  "devDependencies": {
    "node-pty": "^1.0.0"                // 伪终端（原生模块）
  }
}
```

**node-pty 编译配置：**

在 `package.json` 的 `electron-builder` 配置中增加原生模块重建：

```jsonc
{
  "build": {
    "npmRebuild": true,
    "nodeGypRebuild": false,
    // ...
  }
}
```

在 `scripts` 中增加重建命令：

```jsonc
{
  "scripts": {
    "postinstall": "electron-rebuild -f -w node-pty"
  }
}
```

需要额外安装 `electron-rebuild` 作为 devDependency。

### 3.2 Main 进程 — TerminalManager

#### 文件：`desktop/electron/terminalManager.cjs`

独立模块，导出 TerminalManager 类，由 `main.cjs` 引入并初始化。

```javascript
// terminalManager.cjs 核心结构

const pty = require('node-pty');
const os = require('os');
const path = require('path');

class TerminalManager {
  constructor() {
    this.sessions = new Map(); // id -> TerminalSession
    this.nextId = 1;
  }

  /**
   * 创建新的终端会话
   * @param {object} options
   * @param {string} options.cwd - 初始工作目录
   * @param {number} options.cols - 列数
   * @param {number} options.rows - 行数
   * @param {string} [options.shell] - 指定 shell 路径，默认读取 $SHELL
   * @returns {{ id: string }}
   */
  create(options) {
    const id = `term_${this.nextId++}`;
    const shell = options.shell || this._detectShell();
    const cwd = options.cwd || os.homedir();

    const ptyProcess = pty.spawn(shell, [], {
      name: 'xterm-256color',
      cols: options.cols || 80,
      rows: options.rows || 24,
      cwd: cwd,
      env: {
        ...process.env,
        TERM: 'xterm-256color',
        COLORTERM: 'truecolor',
      },
    });

    const session = {
      id,
      pty: ptyProcess,
      shell,
      cwd,
      createdAt: Date.now(),
    };

    this.sessions.set(id, session);
    return { id };
  }

  /**
   * 向终端写入数据（键盘输入）
   */
  write(id, data) {
    const session = this.sessions.get(id);
    if (session) {
      session.pty.write(data);
    }
  }

  /**
   * 调整终端尺寸
   */
  resize(id, cols, rows) {
    const session = this.sessions.get(id);
    if (session) {
      session.pty.resize(cols, rows);
    }
  }

  /**
   * 关闭终端会话
   */
  kill(id) {
    const session = this.sessions.get(id);
    if (session) {
      session.pty.kill();
      this.sessions.delete(id);
    }
  }

  /**
   * 关闭所有终端会话（应用退出时调用）
   */
  killAll() {
    for (const [id, session] of this.sessions) {
      session.pty.kill();
    }
    this.sessions.clear();
  }

  /**
   * 检测用户默认 shell
   */
  _detectShell() {
    if (process.env.SHELL) {
      return process.env.SHELL;
    }
    // macOS 默认 zsh，其他平台默认 bash
    return process.platform === 'darwin' ? '/bin/zsh' : '/bin/bash';
  }

  /**
   * 获取终端会话列表
   */
  list() {
    return Array.from(this.sessions.values()).map(s => ({
      id: s.id,
      shell: s.shell,
      cwd: s.cwd,
      createdAt: s.createdAt,
    }));
  }
}

module.exports = { TerminalManager };
```

#### main.cjs 修改点

```javascript
// 引入 TerminalManager
const { TerminalManager } = require('./terminalManager.cjs');
const terminalManager = new TerminalManager();

// 注册 IPC handlers
ipcMain.handle('terminal:create', (event, options) => {
  const result = terminalManager.create(options);

  // 监听 pty 输出，推送到渲染端
  const session = terminalManager.sessions.get(result.id);
  session.pty.onData((data) => {
    mainWindow.webContents.send('terminal:data', {
      id: result.id,
      data,
    });
  });

  // 监听 pty 退出
  session.pty.onExit(({ exitCode }) => {
    mainWindow.webContents.send('terminal:exit', {
      id: result.id,
      exitCode,
    });
    terminalManager.sessions.delete(result.id);
  });

  return result;
});

ipcMain.on('terminal:data', (event, { id, data }) => {
  terminalManager.write(id, data);
});

ipcMain.on('terminal:resize', (event, { id, cols, rows }) => {
  terminalManager.resize(id, cols, rows);
});

ipcMain.handle('terminal:kill', (event, { id }) => {
  terminalManager.kill(id);
});

ipcMain.handle('terminal:list', () => {
  return terminalManager.list();
});

// 应用退出时清理
app.on('before-quit', () => {
  terminalManager.killAll();
});
```

**IPC 命名规范说明：**

- `terminal:data`（渲染端 → Main）使用 `ipcMain.on`（fire-and-forget，高频键盘输入不需要 Promise）
- `terminal:create`、`terminal:kill`、`terminal:list` 使用 `ipcMain.handle`（需要返回值）
- `terminal:data`、`terminal:exit`（Main → 渲染端）使用 `mainWindow.webContents.send`

### 3.3 Preload Bridge

#### preload.cjs 新增

```javascript
// 在 contextBridge.exposeInMainWorld 的 electronAPI 对象中增加 terminal 命名空间

terminal: {
  // 创建终端，返回 { id }
  create: (options) => ipcRenderer.invoke('terminal:create', options),

  // 向终端写入数据（键盘输入），高频调用用 send 而非 invoke
  write: (id, data) => ipcRenderer.send('terminal:data', { id, data }),

  // 调整终端尺寸
  resize: (id, cols, rows) => ipcRenderer.send('terminal:resize', { id, cols, rows }),

  // 关闭终端
  kill: (id) => ipcRenderer.invoke('terminal:kill', { id }),

  // 获取终端列表
  list: () => ipcRenderer.invoke('terminal:list'),

  // 监听终端输出（Main → Renderer）
  onData: (callback) => {
    const handler = (event, payload) => callback(payload);
    ipcRenderer.on('terminal:data', handler);
    return () => ipcRenderer.removeListener('terminal:data', handler);
  },

  // 监听终端退出（Main → Renderer）
  onExit: (callback) => {
    const handler = (event, payload) => callback(payload);
    ipcRenderer.on('terminal:exit', handler);
    return () => ipcRenderer.removeListener('terminal:exit', handler);
  },
},
```

**类型声明：** 在 `src/types/electron.d.ts` 中补充 `window.electronAPI.terminal` 的 TypeScript 类型。

### 3.4 Renderer — 组件设计

#### 3.4.1 组件结构

```
src/components/terminal/
├── TerminalPanel.vue      # 底部面板容器（高度拖拽 + 展开/收起）
├── TerminalTabs.vue       # Tab 栏（创建、切换、关闭）
├── TerminalView.vue       # 单个终端实例（xterm.js 封装）
└── useTerminal.ts         # Composable（终端状态管理 + IPC 通信）
```

#### 3.4.2 useTerminal.ts — Composable

```typescript
// src/composables/useTerminal.ts

import { ref, shallowRef, onUnmounted } from 'vue';
import { Terminal } from '@xterm/xterm';
import { FitAddon } from '@xterm/addon-fit';
import '@xterm/xterm/css/xterm.css';

export interface TerminalTab {
  id: string;        // 与 Main 进程 session id 对应
  title: string;     // 显示标题（如 "zsh", "bash"）
  cwd: string;       // 当前工作目录
}

// 模块级单例状态
const tabs = ref<TerminalTab[]>([]);
const activeTabId = ref<string | null>(null);
const isOpen = ref(false);

// 终端实例缓存：id -> { terminal, fitAddon, disposers }
const instances = new Map<string, {
  terminal: Terminal;
  fitAddon: FitAddon;
  disposers: Array<() => void>;
}>();

// IPC 事件清理函数
let removeDataListener: (() => void) | null = null;
let removeExitListener: (() => void) | null = null;

export function useTerminal() {
  // 初始化 IPC 监听（仅执行一次）
  function initListeners() {
    if (removeDataListener) return;

    removeDataListener = window.electronAPI.terminal.onData(
      ({ id, data }: { id: string; data: string }) => {
        const inst = instances.get(id);
        if (inst) {
          inst.terminal.write(data);
        }
      }
    );

    removeExitListener = window.electronAPI.terminal.onExit(
      ({ id, exitCode }: { id: string; exitCode: number }) => {
        // 移除 tab 和实例
        removeTab(id);
      }
    );
  }

  /**
   * 创建新终端
   * @param cwd 初始工作目录
   */
  async function createTerminal(cwd?: string): Promise<string> {
    initListeners();

    const cols = 80;
    const rows = 24;
    const result = await window.electronAPI.terminal.create({ cwd, cols, rows });
    const id = result.id;

    // 创建 xterm 实例
    const terminal = new Terminal({
      cursorBlink: true,
      fontSize: 13,
      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
      theme: {
        background: '#1e1e1e',
        foreground: '#cccccc',
        cursor: '#ffffff',
        // 更多颜色跟随主题...
      },
    });
    const fitAddon = new FitAddon();
    terminal.loadAddon(fitAddon);

    instances.set(id, { terminal, fitAddon, disposers: [] });

    // 将键盘输入转发到 Main 进程
    const dataDisposer = terminal.onData((data) => {
      window.electronAPI.terminal.write(id, data);
    });

    // 监听 resize 事件（由外部触发 fit 时产生）
    const resizeDisposer = terminal.onResize(({ cols, rows }) => {
      window.electronAPI.terminal.resize(id, cols, rows);
    });

    instances.get(id)!.disposers.push(
      () => dataDisposer.dispose(),
      () => resizeDisposer.dispose()
    );

    // 添加 tab
    const shellName = detectShellName();
    tabs.value.push({ id, title: shellName, cwd: cwd || '~' });
    activeTabId.value = id;

    return id;
  }

  /**
   * 将 xterm 实例挂载到 DOM 元素
   */
  function mountTerminal(id: string, container: HTMLElement) {
    const inst = instances.get(id);
    if (!inst) return;

    inst.terminal.open(container);
    // 延迟 fit，等待 DOM 渲染完成
    requestAnimationFrame(() => {
      inst.fitAddon.fit();
      // 将实际尺寸同步到 Main 进程
      window.electronAPI.terminal.resize(
        id,
        inst.terminal.cols,
        inst.terminal.rows
      );
    });
  }

  /**
   * 触发 fit（窗口 resize 时调用）
   */
  function fitTerminal(id: string) {
    const inst = instances.get(id);
    if (!inst) return;
    inst.fitAddon.fit();
  }

  /**
   * 切换活跃 Tab
   */
  function switchTab(id: string) {
    activeTabId.value = id;
  }

  /**
   * 关闭终端
   */
  async function closeTerminal(id: string) {
    await window.electronAPI.terminal.kill(id);
    removeTab(id);
  }

  /**
   * 内部：移除 tab 和清理实例
   */
  function removeTab(id: string) {
    const inst = instances.get(id);
    if (inst) {
      inst.disposers.forEach(d => d());
      inst.terminal.dispose();
      instances.delete(id);
    }

    const idx = tabs.value.findIndex(t => t.id === id);
    if (idx !== -1) {
      tabs.value.splice(idx, 1);
    }

    // 如果关闭的是当前活跃 tab，切换到相邻 tab
    if (activeTabId.value === id) {
      if (tabs.value.length > 0) {
        const newIdx = Math.min(idx, tabs.value.length - 1);
        activeTabId.value = tabs.value[newIdx].id;
      } else {
        activeTabId.value = null;
        isOpen.value = false; // 所有 tab 关闭后收起面板
      }
    }
  }

  /**
   * 切换面板展开/收起
   */
  function togglePanel() {
    isOpen.value = !isOpen.value;
    // 展开时如果没有终端，自动创建一个
    if (isOpen.value && tabs.value.length === 0) {
      createTerminal();
    }
  }

  /**
   * 获取活跃终端实例（供外部组件使用）
   */
  function getActiveInstance() {
    if (!activeTabId.value) return null;
    return instances.get(activeTabId.value) || null;
  }

  function detectShellName(): string {
    const shell = import.meta.env.VITE_SHELL || '/bin/zsh';
    return shell.split('/').pop() || 'zsh';
  }

  // 清理
  onUnmounted(() => {
    // 不在这里清理全局监听，因为 useTerminal 是单例模式
    // 清理在应用退出时由 Main 进程的 terminalManager.killAll() 处理
  });

  return {
    // 状态
    tabs,
    activeTabId,
    isOpen,
    // 操作
    createTerminal,
    mountTerminal,
    fitTerminal,
    switchTab,
    closeTerminal,
    togglePanel,
    getActiveInstance,
  };
}
```

#### 3.4.3 TerminalPanel.vue — 底部面板

```vue
<!-- 概念结构，非完整代码 -->
<template>
  <div v-show="isOpen" class="terminal-panel" :style="{ height: panelHeight + 'px' }">
    <!-- 拖拽条 -->
    <div class="terminal-resize-handle" @mousedown="startResize" />

    <!-- Tab 栏 -->
    <TerminalTabs
      :tabs="tabs"
      :active-id="activeTabId"
      @switch="switchTab"
      @close="closeTerminal"
      @create="createTerminal"
    />

    <!-- 终端容器 -->
    <div class="terminal-container">
      <!-- 每个 tab 对应一个容器，通过 v-show 控制显隐 -->
      <div
        v-for="tab in tabs"
        :key="tab.id"
        v-show="tab.id === activeTabId"
        :ref="el => setContainerRef(tab.id, el)"
        class="terminal-instance"
      />
    </div>
  </div>
</template>
```

**关键设计决策：**

- 使用 `v-show` 而非 `v-if` 切换终端实例，避免 xterm 实例被销毁重建
- 每个终端实例挂载到独立的 `<div>` 容器
- 通过 `:ref` 回调收集容器引用，在 Tab 切换时调用 `mountTerminal` / `fitTerminal`

#### 3.4.4 面板高度拖拽

```typescript
// TerminalPanel.vue 中的拖拽逻辑

const panelHeight = ref(300); // 默认高度 300px
const MIN_HEIGHT = 100;
const MAX_HEIGHT_RATIO = 0.7; // 最大不超过视口高度的 70%

function startResize(e: MouseEvent) {
  const startY = e.clientY;
  const startHeight = panelHeight.value;

  function onMove(e: MouseEvent) {
    const delta = startY - e.clientY; // 向上拖拽为正值
    const maxHeight = window.innerHeight * MAX_HEIGHT_RATIO;
    panelHeight.value = Math.max(MIN_HEIGHT, Math.min(maxHeight, startHeight + delta));
    // 触发当前活跃终端的 fit
    if (activeTabId.value) {
      fitTerminal(activeTabId.value);
    }
  }

  function onUp() {
    document.removeEventListener('mousemove', onMove);
    document.removeEventListener('mouseup', onUp);
    document.body.style.cursor = '';
    document.body.style.userSelect = '';
  }

  document.addEventListener('mousemove', onMove);
  document.addEventListener('mouseup', onUp);
  document.body.style.cursor = 'row-resize';
  document.body.style.userSelect = 'none';
}
```

### 3.5 布局集成

#### TaskView.vue 改造

当前 TaskView 的 `.task-container` 结构：

```
.task-container (flex-column)
  ├── .messages (flex: 1, overflow-y: auto)
  ├── QueuePanel (flex-shrink: 0)
  └── ChatInput (flex-shrink: 0)
```

改造后：

```
.task-container (flex-column)
  ├── .chat-area (flex: 1, min-height: 0, flex-column)
  │   ├── .messages (flex: 1, overflow-y: auto)
  │   ├── QueuePanel (flex-shrink: 0)
  │   └── ChatInput (flex-shrink: 0)
  └── TerminalPanel (flex-shrink: 0, 可拖拽高度, v-show)
```

将原来的 `messages + QueuePanel + ChatInput` 包裹在一个新的 `.chat-area` 容器中，TerminalPanel 放在其下方。TerminalPanel 的高度由拖拽控制，`.chat-area` 自动占据剩余空间。

#### CSS 变量新增

```css
:root {
  --aw-terminal-bg: #1e1e1e;
  --aw-terminal-header-height: 36px;  /* Tab 栏高度 */
}
```

### 3.6 快捷键

在 `Layout.vue` 或 `TaskView.vue` 中注册全局快捷键：

```typescript
// TaskView.vue
useEventListener(document, 'keydown', (e: KeyboardEvent) => {
  // Ctrl+` 或 Cmd+` 切换终端面板
  if ((e.ctrlKey || e.metaKey) && e.key === '`') {
    e.preventDefault();
    togglePanel();
  }
});
```

### 3.7 默认 cwd 逻辑

```typescript
// 在 TaskView.vue 中创建终端时传入 cwd

async function getDefaultCwd(): Promise<string | undefined> {
  const session = sessionStore.activeSession;
  if (!session) return undefined;

  // LOCAL 模式：使用任务工作区
  if (session.executionMode === 'LOCAL' && session.workspace) {
    return session.workspace;
  }

  // CLOUD 模式或无工作区：undefined（Main 进程会使用 os.homedir()）
  return undefined;
}
```

切换活跃任务时，不自动切换已有终端的 cwd（避免打断用户操作）。新创建的终端使用当前任务的工作区。

## 4. 文件变更清单

### 4.1 新增文件

| 文件 | 说明 |
|------|------|
| `desktop/electron/terminalManager.cjs` | Main 进程终端管理器 |
| `desktop/src/composables/useTerminal.ts` | 终端 Composable |
| `desktop/src/components/terminal/TerminalPanel.vue` | 底部面板容器 |
| `desktop/src/components/terminal/TerminalTabs.vue` | Tab 栏组件 |
| `desktop/src/components/terminal/TerminalView.vue` | xterm 实例封装（可选，逻辑可内联到 Panel） |
| `desktop/src/types/electron.d.ts` | electronAPI 类型声明（补充 terminal 命名空间） |

### 4.2 修改文件

| 文件 | 变更 |
|------|------|
| `desktop/package.json` | 新增依赖：@xterm/xterm、@xterm/addon-fit、node-pty；新增 postinstall 脚本 |
| `desktop/electron/main.cjs` | 引入 TerminalManager，注册 terminal:* IPC handlers，before-quit 清理 |
| `desktop/electron/preload.cjs` | 暴露 window.electronAPI.terminal.* API |
| `desktop/src/views/task/TaskView.vue` | 集成 TerminalPanel，改造布局结构，注册快捷键 |
| `desktop/src/components/common/Layout.vue` | 可能需要调整布局（如果终端面板需要跨全宽） |
| `desktop/src/style.css` | 新增终端相关 CSS 变量 |

### 4.3 不变文件

- 后端代码无任何变更
- 现有 Shell 会话管理（`handleShellFromWebSocket`）不变
- WebSocket 连接逻辑不变
- Pinia stores 不变（终端状态在 useTerminal composable 内管理）

## 5. 数据流

### 5.1 创建终端

```
用户点击 "+" 按钮
  → TerminalTabs emit "create"
  → useTerminal.createTerminal(cwd)
  → ipcRenderer.invoke('terminal:create', { cwd, cols, rows })
  → Main: terminalManager.create(options)
  → pty.spawn(shell, [], { cwd, cols, rows, ... })
  → 返回 { id }
  → Renderer: 创建 xterm.Terminal 实例
  → 添加 tab 到 tabs[]
  → activeTabId = id
  → TerminalPanel 渲染新 tab 的容器 div
  → mountTerminal(id, container)
  → terminal.open(container)
  → fitAddon.fit()
```

### 5.2 键盘输入

```
用户在 xterm 中按键
  → xterm.onData callback
  → ipcRenderer.send('terminal:data', { id, data })
  → Main: terminalManager.write(id, data)
  → pty.write(data)
  → pty 产生输出
  → pty.onData callback
  → mainWindow.webContents.send('terminal:data', { id, data })
  → Renderer: ipcRenderer 'terminal:data' handler
  → terminal.write(data)
  → xterm 渲染输出
```

### 5.3 窗口 resize

```
用户拖拽窗口边缘
  → TaskView 监听 resize 事件
  → fitTerminal(activeTabId)
  → fitAddon.fit()
  → xterm.onResize callback
  → ipcRenderer.send('terminal:resize', { id, cols, rows })
  → Main: pty.resize(cols, rows)
```

### 5.4 关闭终端

```
用户点击 Tab 的关闭按钮
  → TerminalTabs emit "close" (id)
  → useTerminal.closeTerminal(id)
  → ipcRenderer.invoke('terminal:kill', { id })
  → Main: pty.kill() + sessions.delete(id)
  → Renderer: terminal.dispose() + 移除 tab
  → 如果无剩余 tab，isOpen = false（面板收起）
```

## 6. node-pty 编译与打包

### 6.1 开发环境

```bash
# 安装依赖后自动执行 electron-rebuild
npm install
# 或手动执行
npx electron-rebuild -f -w node-pty
```

### 6.2 生产打包

electron-builder 默认会处理原生模块的 rebuild。需要确认：

```jsonc
// package.json electron-builder 配置
{
  "build": {
    "npmRebuild": true,
    "mac": {
      "target": "dmg"
    }
  }
}
```

### 6.3 潜在风险

| 风险 | 应对 |
|------|------|
| node-pty 编译失败（缺少 C++ 编译工具链） | 文档中说明需要 Xcode Command Line Tools (macOS) 或 build-essential (Linux) |
| Electron 版本升级后 node-pty 不兼容 | 通过 electron-rebuild 重新编译，node-pty 对 Electron 版本一般兼容 |
| macOS ARM64 vs x64 架构差异 | electron-builder 支持 per-arch 构建，node-pty 支持多架构 |

## 7. 样式规范

遵循现有的 Apple 设计风格（`style.css` 中的设计令牌）：

```css
.terminal-panel {
  background: var(--aw-canvas);
  border-top: 1px solid var(--aw-divider-soft);
  display: flex;
  flex-direction: column;
  position: relative;
}

.terminal-resize-handle {
  position: absolute;
  top: -3px;
  left: 0;
  right: 0;
  height: 6px;
  cursor: row-resize;
  z-index: 10;
}

.terminal-resize-handle:hover {
  background: var(--aw-primary);
  opacity: 0.3;
}

.terminal-tabs {
  height: var(--aw-terminal-header-height);
  display: flex;
  align-items: center;
  padding: 0 12px;
  gap: 4px;
  border-bottom: 1px solid var(--aw-divider-soft);
  background: var(--aw-bg-secondary);
  flex-shrink: 0;
}

.terminal-container {
  flex: 1;
  min-height: 0;
  overflow: hidden;
  background: var(--aw-terminal-bg);
}

.terminal-instance {
  width: 100%;
  height: 100%;
}
```

## 8. 测试验证

### 8.1 功能验证项

- [ ] 快捷键 `` Ctrl+` `` 展开/收起终端面板
- [ ] 点击 "+" 创建新终端 Tab
- [ ] Tab 切换，终端实例保持状态
- [ ] Tab 关闭，实例正确清理
- [ ] 最后一个 Tab 关闭后面板自动收起
- [ ] 键盘输入正确传递，命令执行有输出
- [ ] ANSI 颜色正确渲染
- [ ] 交互式程序（如 `vim`、`top`）可正常使用
- [ ] 拖拽调整面板高度，终端自适应
- [ ] 窗口 resize 后终端自适应
- [ ] LOCAL 模式下默认 cwd 为任务工作区
- [ ] CLOUD 模式下默认 cwd 为 home 目录
- [ ] 应用退出时终端进程正确清理（无僵尸进程）
- [ ] 多终端并行运行不互相干扰