From 2854e057ae2a9e2f5017b6ccaf572088db6354c5 Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 14:52:23 +0800
Subject: [PATCH 1/9] =?UTF-8?q?docs:=20=E5=8F=AF=E9=85=8D=E7=BD=AE?=
 =?UTF-8?q?=E7=BB=88=E7=AB=AF=E9=80=89=E6=8B=A9=E5=8A=9F=E8=83=BD=E8=AE=BE?=
 =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...2-configurable-terminal-launcher-design.md | 205 ++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-02-configurable-terminal-launcher-design.md

diff --git a/docs/superpowers/specs/2026-07-02-configurable-terminal-launcher-design.md b/docs/superpowers/specs/2026-07-02-configurable-terminal-launcher-design.md
new file mode 100644
index 00000000..08070c27
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-02-configurable-terminal-launcher-design.md
@@ -0,0 +1,205 @@
+# 可配置终端选择功能
+
+- 日期：2026-07-02
+- 状态：已批准（待实现）
+- 关联代码：`src/main/api/renderer/systemCommands.ts`、`src/main/utils/appleScriptHelper.ts`、`internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue`
+
+## 背景与动机
+
+ZTools 的「在终端打开」功能（从 Finder 唤出或插件 IPC 调用）在 macOS 上**硬编码**系统 `Terminal.app`，无法选择其他终端。用户安装了 Ghostty 后希望改用自定义终端，且项目是三平台（macOS/Linux/Windows）的，需要做成可配置功能。
+
+当前终端启动逻辑**散落在两处且重复**：
+
+1. `systemCommands.ts:497-508` `openTerminalOnMac` —— Finder 命令路径（`handleOpenTerminal` 557-621 调用），用 AppleScript `tell application "Terminal"`。
+2. `appleScriptHelper.ts:184-200` `openInTerminal` —— 插件 IPC 路径（`system.ts:76-83` 的 `open-terminal` handler 调用），同样硬编码 `Terminal`，但路径转义方式不同（单引号替换 vs `quoted form of`）。
+
+三平台均**无任何自定义终端配置项**。
+
+## 目标
+
+- 用户可在设置中选择「打开终端」时使用的终端应用，三平台均支持。
+- 支持常见终端预设 + 用户自定义命令模板。
+- 消除两处重复的终端启动逻辑，统一为一个模块。
+- 向后兼容：未配置时行为与现状完全一致。
+
+## 非目标（YAGNI）
+
+- 不做终端自动检测（扫描已安装的终端）。
+- 不为自定义命令做弹窗错误提示（仅记日志 + 回退默认）。
+- 不支持 AppleScript 类型的自定义命令（自定义仅限 CLI 命令模板）。
+- 不新增设置页路由（塞进现有通用设置页）。
+
+## 架构
+
+### 新模块：`src/main/utils/terminalLauncher.ts`
+
+导出单一函数：
+
+```ts
+export async function openInTerminal(folderPath: string): Promise<boolean>
+```
+
+返回 `true` 表示成功启动，`false` 表示失败（调用方据此返回错误信息）。内部自建 `execAsync = promisify(exec)` 与 `spawn`，不依赖调用方传入。
+
+#### 内部分发逻辑
+
+```
+openInTerminal(path)
+  ├─ dbGet('settings-general') 读 terminal / terminalCustomCommand
+  ├─ 据 process.platform 选当前平台预设表
+  ├─ terminal 值无效（不在当前平台预设表且非 'custom'）→ 回退 'default'
+  ├─ 'default' → 调用迁移过来的平台 default 函数
+  ├─ 预设 id → 按预设描述启动
+  └─ 'custom' → 解析 terminalCustomCommand，替换 {path}，spawn
+```
+
+#### 迁入的现有函数
+
+以下三个函数从 `systemCommands.ts` **迁入** `terminalLauncher.ts`，作为 `'default'` 处理器（行为不变，去掉 `execAsync` 参数，改用模块内自建的 `execAsync`）：
+
+- `openTerminalOnMac(folderPath)`（原 497-508）
+- `openTerminalOnLinux(folderPath)`（原 514-536）
+- `tryLaunchWindowsTerminal(folderPath)`（原 65-88，含 `escapePowerShellPath` / `escapeCmdPath` 两个转义辅助函数 50-63 一并迁入）
+
+`getMacFinderPath`（541-555）属于**路径获取**，不属于终端启动，**保留在 `systemCommands.ts`** 不动。
+
+### 调用点改造
+
+| 调用点 | 现状 | 改造后 |
+|---|---|---|
+| `systemCommands.ts:handleOpenTerminal`（597-611） | 按平台调 `openTerminalOnMac` / `openTerminalOnLinux` / `tryLaunchWindowsTerminal` | 改为 `await terminalLauncher.openInTerminal(targetPath)`，据返回布尔值决定 `{success, error}`。路径获取段（572-590）保留不动。 |
+| `appleScriptHelper.ts:openInTerminal`（184-200） | 自实现 AppleScript `tell application "Terminal"` | 改为委托 `return await terminalLauncher.openInTerminal(path)`，删除内部 AppleScript 脚本。保留 `Promise<boolean>` 签名，不动调用方 `system.ts:openTerminal`（76-83）。 |
+
+## 数据模型
+
+`settings-general` 文档（LMDB key `ZTOOLS/settings-general`）新增两字段，沿用项目「合并写」约定（`{...existing, terminal, terminalCustomCommand}`）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `terminal` | `string` | `'default'` | `'default'` ｜预设 id（如 `'ghostty'`）｜`'custom'` |
+| `terminalCustomCommand` | `string` | `''` | CLI 命令模板，含 `{path}` 占位符，仅 `terminal === 'custom'` 时使用 |
+
+枚举类型定义于 `internal-plugins/setting/src/constants.ts`：
+
+```ts
+export type TerminalType = 'default' | 'custom'  // 预设 id 为字符串字面量，运行时校验
+```
+
+> 预设 id 不做成联合字面量类型，因为各平台预设不同且可能扩展；运行时用「当前平台预设表」校验 id 有效性，无效则回退 `'default'`。
+
+## 预设注册表（按平台）
+
+预设用**声明式数据**描述，尽量不做 per-preset 函数。两种预设类型：
+
+- **CLI 型**：`{ type: 'cli', command: string, args: string[] }`，`args` 中可含 `{path}` 占位符，启动前替换。用 `spawn` detached。
+- **AppleScript 型**：`{ type: 'applescript', script: string }`，`script` 中可含 `{path}`，用 `osascript -e` 执行。用 `execAsync`。
+
+### macOS
+
+| id | 类型 | 启动方式 |
+|---|---|---|
+| `default` | applescript | 现有 `tell application "Terminal" / activate / do script "cd " & quoted form of "{path}"` |
+| `ghostty` | cli | `open -na Ghostty.app --args --working-directory={path}` |
+| `iterm2` | applescript | `tell application "iTerm" / create window with default profile / write session "cd {path}"` |
+| `warp` | cli | `open -na Warp.app`（Warp 自行处理目录；实现时确认是否需 `--args`） |
+
+> macOS 上 `ghostty` CLI 不能直接启动终端（已验证 `ghostty --help`），必须用 `open -na Ghostty.app --args ...`。`--working-directory` 是 Ghostty 有效配置项（已验证 `ghostty +show-config`）。
+
+### Linux
+
+| id | 类型 | 启动方式 |
+|---|---|---|
+| `default` | 函数 | 现有回退链 `exo-open → gnome-terminal → xterm` |
+| `gnome-terminal` | cli | `gnome-terminal --working-directory={path}` |
+| `konsole` | cli | `konsole --workdir {path}` |
+| `xterm` | cli | `xterm -cd {path}` |
+
+### Windows
+
+| id | 类型 | 启动方式 |
+|---|---|---|
+| `default` | 函数 | 现有回退链 `wt → powershell → cmd`（含路径转义） |
+| `wt` | cli | `wt.exe -d {path}` |
+| `powershell` | cli | `powershell.exe -NoExit -Command "Set-Location -Path '{path}'"`（用 `escapePowerShellPath`） |
+| `cmd` | cli | `cmd.exe /K cd /d "{path}"`（用 `escapeCmdPath`） |
+
+三平台均有 `custom`（走自定义命令模板）。
+
+> Linux/Windows 的 `default` 是回退链函数，不适用声明式数据描述，保留为函数形态。
+
+## 数据流
+
+```
+[设置页] 用户选终端 + 填自定义命令
+    → GeneralSetting.saveSettings()
+    → dbPut('settings-general', {...existing, terminal, terminalCustomCommand})  // 合并写
+
+[打开终端时] handleOpenTerminal / appleScriptHelper.openInTerminal
+    → terminalLauncher.openInTerminal(path)
+        → dbGet('settings-general') 读 terminal / terminalCustomCommand
+        → 按 process.platform 选预设表，校验 id
+        → 分发：default | 预设(cli/applescript) | custom(解析命令模板，替换 {path}，spawn)
+```
+
+**无新增 IPC、无内存缓存、无启动回放**：配置仅在打开终端时由主进程直接 `dbGet` 读取一次。
+
+## 自定义命令处理
+
+- 用户在 `terminalCustomCommand` 填写完整命令，如 `alacritty --working-directory={path}`。
+- 处理步骤：
+  1. 用项目现有的 `parseCommandString`（`src/main/core/commandLauncher/linuxLauncher.ts:11`，签名 `(cmd: string) => [string, string[]]`，处理引号）拆分命令为 `command + args`。该函数当前**未导出**，实现时需将其改为 `export function`（一词改动）并在 terminalLauncher 中导入复用，避免重复造轮子。
+  2. 将每个 arg 中的 `{path}` 替换为目标路径。
+  3. `spawn(command, args, { detached: true, stdio: 'ignore' })` + `child.unref()`。
+- macOS 提示：若终端不支持 CLI 直接启动（如 Ghostty），需写 `open -na AppName.app --args --working-directory={path}`。
+
+## 设置 UI
+
+塞进 `internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue`，新增一个 `.setting-group`「终端打开」：
+
+- **Dropdown**：选项 = 当前平台预设列表 + `系统默认`（`default`）+ `自定义`（`custom`）。
+  - 平台判断：复用 `GeneralSetting.vue` 已有的 `platform` ref（102 行，由 `getPlatformInfo()` 1148-1157 通过 `window.ztools.internal.getPlatform()` 填充），据 `platform.value` 返回对应预设数组。
+- **条件文本输入框**：仅当 Dropdown 选中 `custom` 时显示，绑定 `terminalCustomCommand`，占位符示例 `alacritty --working-directory={path}`。macOS 下附一句小字提示「若终端不支持 CLI 直接启动，可用 `open -na AppName.app --args ...`」。
+- 控件 `@change` 调 `saveSettings()`（与同页其他设置一致）。
+
+### GeneralSetting.vue 具体改动点
+
+| 位置 | 改动 |
+|---|---|
+| `<script>` ref 声明区（~165 行附近） | 加 `const terminal = ref<TerminalType>('default')`、`const terminalCustomCommand = ref('')` |
+| 选项数据区（20-99 行附近） | 加当前平台预设选项数组（动态，按平台返回） |
+| `loadSettings()`（1162-1247） | 加 `terminal.value = data.terminal ?? 'default'`、`terminalCustomCommand.value = data.terminalCustomCommand ?? ''` |
+| `saveSettings()`（1250-1306） | dbPut 对象加 `terminal: terminal.value`、`terminalCustomCommand: terminalCustomCommand.value` |
+| 模板 | 新增 `.setting-group` 含 Dropdown + 条件输入框 |
+
+## 错误处理
+
+- 自定义命令解析失败 / 终端二进制不存在（spawn `error` 事件）→ catch，`console.error` 记日志，返回 `false`（`handleOpenTerminal` 据此返回 `{success: false, error}`）。
+- 存的 `terminal` id 在当前平台无效 → 回退 `'default'`，记一条 warn 日志。
+- 不做弹窗提示（YAGNI）。
+
+## 验证标准
+
+因启动终端难以单元测试，采用手动验证：
+
+1. **macOS Ghostty**：Finder 唤出 → 设置选 Ghostty → 在目标目录打开 Ghostty 窗口。
+2. **默认无回归**：设置选「系统默认」→ macOS 行为与改动前一致（Terminal.app 打开并 cd）。
+3. **自定义命令**：选「自定义」填 `open -na Ghostty.app --args --working-directory={path}` → 同样打开 Ghostty。
+4. **插件 IPC 路径**：通过 `open-terminal` IPC（appleScriptHelper 路径）打开 → 与 Finder 路径行为一致。
+5. **Linux/Windows 无回归**：default 回退链行为不变。
+6. **合并写安全**：修改终端设置后，通用设置页其他字段（如 theme、wakeupBlacklist）未被覆盖。
+
+## 改动文件清单
+
+| 文件 | 改动 |
+|---|---|
+| `src/main/utils/terminalLauncher.ts` | **新建**。迁入三个 default 函数 + 预设表 + 配置读取 + custom 命令处理 + `openInTerminal` 导出。 |
+| `src/main/api/renderer/systemCommands.ts` | 删除迁出的三个函数及两个转义辅助函数；`handleOpenTerminal` 的 597-611 段改为调 `terminalLauncher.openInTerminal`。 |
+| `src/main/utils/appleScriptHelper.ts` | `openInTerminal`（184-200）改为委托 `terminalLauncher.openInTerminal`，删除内部 AppleScript。 |
+| `internal-plugins/setting/src/constants.ts` | 加 `TerminalType` 类型。 |
+| `internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue` | 加终端设置 ref / 选项 / loadSettings / saveSettings / UI 模板。 |
+
+## 待实现时确认的细节
+
+- `parseCommandString` 位于 `src/main/core/commandLauncher/linuxLauncher.ts:11`，当前未导出，需改为 `export`（签名 `(cmd: string) => [string, string[]]`）。
+- `databaseAPI` 在 `terminalLauncher.ts` 的相对导入路径（参考 `systemCommands.ts` 的导入）。
+- Warp 在 macOS 的最佳启动方式（是否需 `--args` 传目录）。

From b251204311915502c7520a9f32d35a509fd83812 Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 15:12:41 +0800
Subject: [PATCH 2/9] =?UTF-8?q?docs:=20=E5=8F=AF=E9=85=8D=E7=BD=AE?=
 =?UTF-8?q?=E7=BB=88=E7=AB=AF=E9=80=89=E6=8B=A9=E5=8A=9F=E8=83=BD=E5=AE=9E?=
 =?UTF-8?q?=E7=8E=B0=E8=AE=A1=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...26-07-02-configurable-terminal-launcher.md | 947 ++++++++++++++++++
 1 file changed, 947 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-02-configurable-terminal-launcher.md

diff --git a/docs/superpowers/plans/2026-07-02-configurable-terminal-launcher.md b/docs/superpowers/plans/2026-07-02-configurable-terminal-launcher.md
new file mode 100644
index 00000000..159a4a17
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-02-configurable-terminal-launcher.md
@@ -0,0 +1,947 @@
+# 可配置终端选择功能 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让「在终端打开」支持用户在三平台选择终端应用（预设 + 自定义命令），并消除两处重复的终端启动逻辑。
+
+**Architecture:** 新建 `src/main/utils/terminalLauncher.ts` 统一终端启动：预设注册表（声明式 cli/applescript + handler）+ 纯函数（选项/解析/路径替换，可单测）+ 编排函数 `openInTerminal`（读 settings-general 配置分发）。两个调用点（`systemCommands.handleOpenTerminal` 与 `appleScriptHelper.openInTerminal`）改为委托它。
+
+**Tech Stack:** Electron 41 + Vue 3 + TypeScript；vitest 单测；child_process 的 spawn/exec；LMDB（databaseAPI，主进程同步读写）。
+
+**关键已核实事实：**
+- `databaseAPI.dbGet(key): any` 是**同步**（`src/main/api/shared/database.ts:416`），主进程直接 `databaseAPI.dbGet('settings-general')` 无需 await。
+- 待移动的 `openTerminalOnMac` / `openTerminalOnLinux` / `tryLaunchWindowsTerminal` / `escapePowerShellPath` / `escapeCmdPath` **无任何外部引用**（仅在 `systemCommands.ts` 内部），删除安全。
+- 设置插件（`internal-plugins/setting`）是独立 Vite 应用，**不能 import 主进程代码**。因此预设下拉选项的 label/value 列表在 `GeneralSetting.vue` 内按平台重复一份（仅 UI 标签，启动逻辑仍以 terminalLauncher 为唯一源）。
+- `GeneralSetting.vue` 已有 `platform` ref（102 行）由 `getPlatformInfo()`（1148 行）填充；已有 `saveSettings` 合并写（1258）、`loadSettings`（1162）模式可复用。
+
+**与 spec 的两处偏离（及理由）：**
+1. **内联命令解析器**，不导出复用 `linuxLauncher.ts` 的 `parseCommandString`。理由：`linuxLauncher.ts` 顶部 import 了 `dialog`/`WindowManager`/`fs`，从它导入会把这些重依赖传染进 terminalLauncher；内联 15 行解析器可保持 terminalLauncher 为干净叶子模块。
+2. **暂不含 Warp 预设**。理由：Warp 在 macOS 的「打开并 cd 到目录」启动方式未经验证（`open -na Warp.app` 无法保证 cd），先不发布一个可能无效的预设；待确认后再补。
+
+---
+
+## 文件结构
+
+| 文件 | 职责 | 动作 |
+|---|---|---|
+| `src/main/utils/terminalLauncher.ts` | 统一终端启动：类型/转义/解析原语/默认处理器/预设注册表/纯函数/编排 `openInTerminal` | 新建 |
+| `tests/main/terminalLauncher.test.ts` | 纯函数 + 编排分发单测 | 新建 |
+| `src/main/api/renderer/systemCommands.ts` | 删除迁出的 3 函数 + 2 转义辅助；`handleOpenTerminal` 改为调 terminalLauncher | 修改 |
+| `src/main/utils/appleScriptHelper.ts` | `openInTerminal` 改为委托 terminalLauncher | 修改 |
+| `internal-plugins/setting/src/constants.ts` | 加 `TerminalType` 类型 | 修改 |
+| `internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue` | 加终端设置 ref/选项/load/save/UI | 修改 |
+
+---
+
+### Task 1: 创建 terminalLauncher.ts（纯逻辑 + 预设 + 执行原语，TDD）
+
+**Files:**
+- Create: `src/main/utils/terminalLauncher.ts`
+- Test: `tests/main/terminalLauncher.test.ts`
+
+- [ ] **Step 1: 写纯函数的失败测试**
+
+创建 `tests/main/terminalLauncher.test.ts`：
+
+```ts
+import { describe, it, expect } from 'vitest'
+import {
+  getPresetOptions,
+  resolvePreset,
+  applyPathToArgs,
+  parseCustomCommand
+} from '../../src/main/utils/terminalLauncher'
+
+// ========== getPresetOptions ==========
+
+describe('getPresetOptions', () => {
+  it('macOS 含 系统默认/Ghostty/iTerm2/自定义', () => {
+    const opts = getPresetOptions('darwin')
+    expect(opts.map((o) => o.value)).toEqual(['default', 'ghostty', 'iterm2', 'custom'])
+  })
+
+  it('Linux 含 系统默认/gnome-terminal/konsole/xterm/自定义', () => {
+    const opts = getPresetOptions('linux')
+    expect(opts.map((o) => o.value)).toEqual([
+      'default',
+      'gnome-terminal',
+      'konsole',
+      'xterm',
+      'custom'
+    ])
+  })
+
+  it('Windows 含 系统默认/wt/powershell/cmd/自定义', () => {
+    const opts = getPresetOptions('win32')
+    expect(opts.map((o) => o.value)).toEqual([
+      'default',
+      'wt',
+      'powershell',
+      'cmd',
+      'custom'
+    ])
+  })
+
+  it('未知平台返回空数组', () => {
+    expect(getPresetOptions('freebsd')).toEqual([])
+  })
+})
+
+// ========== resolvePreset ==========
+
+describe('resolvePreset', () => {
+  it('空值返回默认预设', () => {
+    expect(resolvePreset(undefined, 'darwin')?.id).toBe('default')
+  })
+
+  it('custom 返回 null', () => {
+    expect(resolvePreset('custom', 'darwin')).toBeNull()
+  })
+
+  it('有效 id 返回对应预设', () => {
+    expect(resolvePreset('ghostty', 'darwin')?.id).toBe('ghostty')
+  })
+
+  it('无效 id 回退默认', () => {
+    expect(resolvePreset('nonexistent', 'darwin')?.id).toBe('default')
+  })
+
+  it('id 在当前平台不存在时回退默认', () => {
+    expect(resolvePreset('ghostty', 'win32')?.id).toBe('default')
+  })
+})
+
+// ========== applyPathToArgs ==========
+
+describe('applyPathToArgs', () => {
+  it('替换 {path} 占位符', () => {
+    expect(applyPathToArgs(['--working-directory={path}'], '/Users/x')).toEqual([
+      '--working-directory=/Users/x'
+    ])
+  })
+
+  it('多个占位符都替换', () => {
+    expect(applyPathToArgs(['{path}', 'cd {path}'], '/p')).toEqual(['/p', 'cd /p'])
+  })
+
+  it('无占位符保持不变', () => {
+    expect(applyPathToArgs(['-la'], '/p')).toEqual(['-la'])
+  })
+})
+
+// ========== parseCustomCommand ==========
+
+describe('parseCustomCommand', () => {
+  it('解析命令与参数', () => {
+    expect(parseCustomCommand('alacritty --working-directory={path}')).toEqual({
+      command: 'alacritty',
+      args: ['--working-directory={path}']
+    })
+  })
+
+  it('处理引号包裹的参数（去除引号）', () => {
+    expect(parseCustomCommand('open -na "Ghostty.app"')).toEqual({
+      command: 'open',
+      args: ['-na', 'Ghostty.app']
+    })
+  })
+
+  it('空字符串/纯空白返回 null', () => {
+    expect(parseCustomCommand('')).toBeNull()
+    expect(parseCustomCommand('   ')).toBeNull()
+  })
+})
+```
+
+- [ ] **Step 2: 运行测试确认失败**
+
+Run: `pnpm test tests/main/terminalLauncher.test.ts`
+Expected: FAIL — 模块 `../../src/main/utils/terminalLauncher` 不存在，导入报错。
+
+- [ ] **Step 3: 创建 terminalLauncher.ts（本步不含编排函数与 database 导入）**
+
+创建 `src/main/utils/terminalLauncher.ts`：
+
+```ts
+import { exec, spawn } from 'child_process'
+import { promisify } from 'util'
+
+const execAsync = promisify(exec)
+
+// ==================== 类型 ====================
+
+/** 预设选项（供 UI 下拉使用） */
+export interface PresetOption {
+  label: string
+  value: string
+}
+
+/** 预设的启动方式 */
+type Preset =
+  | { type: 'cli'; command: string; args: string[] } // args 中可含 '{path}' 占位符
+  | { type: 'applescript'; build: (path: string) => string } // 返回完整 AppleScript
+  | { type: 'handler'; run: (path: string) => Promise<boolean> } // 自定义启动（回退链等）
+
+interface PresetEntry {
+  id: string
+  label: string
+  preset: Preset
+}
+
+// ==================== 路径转义（从 systemCommands 迁入，行为不变）====================
+
+function escapePowerShellPath(folderPath: string): string {
+  const escaped = folderPath.replace(/'/g, "''")
+  return `'${escaped}'`
+}
+
+function escapeCmdPath(folderPath: string): string {
+  const escaped = folderPath.replace(/"/g, '^"')
+  return `"${escaped}"`
+}
+
+// ==================== 命令字符串解析（内联，避免耦合 commandLauncher）====================
+
+/** 将命令字符串拆分为 [可执行文件, 参数列表]，处理引号 */
+function parseCommandString(cmd: string): [string, string[]] {
+  const parts: string[] = []
+  let current = ''
+  let inQuote: string | null = null
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i]
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null
+      } else {
+        current += ch
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch
+    } else if (/\s/.test(ch)) {
+      if (current) {
+        parts.push(current)
+        current = ''
+      }
+    } else {
+      current += ch
+    }
+  }
+  if (current) parts.push(current)
+  return [parts[0], parts.slice(1)]
+}
+
+// ==================== 执行原语 ====================
+
+/** 执行 AppleScript（转义单引号，防止 shell 注入） */
+async function runAppleScript(script: string): Promise<void> {
+  const escaped = script.replace(/'/g, "'\\''")
+  await execAsync(`osascript -e '${escaped}'`)
+}
+
+/** detached 启动 CLI 命令，返回是否成功拿到 pid */
+function runCli(command: string, args: string[]): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' })
+    child.on('error', () => resolve(false))
+    if (child.pid) {
+      child.unref()
+      resolve(true)
+    }
+  })
+}
+
+// ==================== 默认处理器（从 systemCommands 迁入，行为不变）====================
+
+async function launchDefaultMac(path: string): Promise<boolean> {
+  const script = `
+    tell application "Terminal"
+      activate
+      do script "cd " & quoted form of "${path}"
+    end tell
+  `
+  await runAppleScript(script)
+  return true
+}
+
+async function launchDefaultLinux(path: string): Promise<boolean> {
+  return (
+    (await runCli('exo-open', ['--launch', 'TerminalEmulator', '--working-directory', path])) ||
+    (await runCli('gnome-terminal', [`--working-directory=${path}`])) ||
+    (await runCli('xterm', ['-cd', path]))
+  )
+}
+
+async function launchDefaultWindows(path: string): Promise<boolean> {
+  return (
+    (await runCli('wt.exe', ['-d', path])) ||
+    (await runCli('powershell.exe', [
+      '-NoExit',
+      '-Command',
+      `Set-Location -Path ${escapePowerShellPath(path)}`
+    ])) ||
+    (await runCli('cmd.exe', ['/K', `cd /d ${escapeCmdPath(path)}`]))
+  )
+}
+
+// ==================== 预设注册表 ====================
+
+const MAC_PRESETS: PresetEntry[] = [
+  {
+    id: 'default',
+    label: '系统默认 (Terminal)',
+    preset: {
+      type: 'applescript',
+      build: (p) => `
+    tell application "Terminal"
+      activate
+      do script "cd " & quoted form of "${p}"
+    end tell
+  `
+    }
+  },
+  {
+    id: 'ghostty',
+    label: 'Ghostty',
+    preset: {
+      type: 'cli',
+      command: 'open',
+      args: ['-na', 'Ghostty.app', '--args', '--working-directory={path}']
+    }
+  },
+  {
+    id: 'iterm2',
+    label: 'iTerm2',
+    preset: {
+      type: 'applescript',
+      build: (p) => `
+    tell application "iTerm"
+      activate
+      tell (create window with default profile)
+        write session "cd " & quoted form of "${p}"
+      end tell
+    end tell
+  `
+    }
+  }
+]
+
+const LINUX_PRESETS: PresetEntry[] = [
+  { id: 'default', label: '系统默认', preset: { type: 'handler', run: launchDefaultLinux } },
+  {
+    id: 'gnome-terminal',
+    label: 'GNOME Terminal',
+    preset: { type: 'cli', command: 'gnome-terminal', args: ['--working-directory={path}'] }
+  },
+  {
+    id: 'konsole',
+    label: 'Konsole',
+    preset: { type: 'cli', command: 'konsole', args: ['--workdir', '{path}'] }
+  },
+  {
+    id: 'xterm',
+    label: 'XTerm',
+    preset: { type: 'cli', command: 'xterm', args: ['-cd', '{path}'] }
+  }
+]
+
+const WINDOWS_PRESETS: PresetEntry[] = [
+  { id: 'default', label: '系统默认', preset: { type: 'handler', run: launchDefaultWindows } },
+  {
+    id: 'wt',
+    label: 'Windows Terminal',
+    preset: { type: 'cli', command: 'wt.exe', args: ['-d', '{path}'] }
+  },
+  {
+    id: 'powershell',
+    label: 'PowerShell',
+    preset: {
+      type: 'handler',
+      run: (p) =>
+        runCli('powershell.exe', [
+          '-NoExit',
+          '-Command',
+          `Set-Location -Path ${escapePowerShellPath(p)}`
+        ])
+    }
+  },
+  {
+    id: 'cmd',
+    label: 'CMD',
+    preset: {
+      type: 'handler',
+      run: (p) => runCli('cmd.exe', ['/K', `cd /d ${escapeCmdPath(p)}`])
+    }
+  }
+]
+
+// ==================== 纯函数（可单测）====================
+
+function getPlatformPresets(platform: string): PresetEntry[] {
+  if (platform === 'darwin') return MAC_PRESETS
+  if (platform === 'linux') return LINUX_PRESETS
+  if (platform === 'win32') return WINDOWS_PRESETS
+  return []
+}
+
+/** 返回当前平台的下拉选项（含「自定义」） */
+export function getPresetOptions(platform: string): PresetOption[] {
+  const options = getPlatformPresets(platform).map((p) => ({ label: p.label, value: p.id }))
+  options.push({ label: '自定义', value: 'custom' })
+  return options
+}
+
+/** 按 terminal 值解析预设；空值/无效值回退默认，'custom' 返回 null（由编排函数处理） */
+export function resolvePreset(
+  terminal: string | undefined,
+  platform: string
+): PresetEntry | null {
+  const presets = getPlatformPresets(platform)
+  if (!terminal) {
+    return presets.find((p) => p.id === 'default') ?? null
+  }
+  if (terminal === 'custom') return null
+  return presets.find((p) => p.id === terminal) ?? presets.find((p) => p.id === 'default') ?? null
+}
+
+/** 将 args 中的 {path} 占位符替换为实际路径 */
+export function applyPathToArgs(args: string[], folderPath: string): string[] {
+  return args.map((a) => a.replaceAll('{path}', folderPath))
+}
+
+/** 解析自定义命令模板；空字符串返回 null */
+export function parseCustomCommand(template: string): { command: string; args: string[] } | null {
+  const trimmed = template.trim()
+  if (!trimmed) return null
+  const [command, ...args] = parseCommandString(trimmed)
+  if (!command) return null
+  return { command, args }
+}
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `pnpm test tests/main/terminalLauncher.test.ts`
+Expected: PASS — 4 个 describe 共 16 个用例全部通过。
+
+- [ ] **Step 5: 类型检查**
+
+Run: `pnpm typecheck:node`
+Expected: 无错误（terminalLauncher 在 `tsconfig.node.json` 的 `src/main/**` include 内）。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/main/utils/terminalLauncher.ts tests/main/terminalLauncher.test.ts
+git commit -m "feat(terminal): 新建 terminalLauncher 统一终端启动纯逻辑与预设"
+```
+
+---
+
+### Task 2: 添加编排函数 openInTerminal（TDD with mocks）
+
+**Files:**
+- Modify: `src/main/utils/terminalLauncher.ts`（追加 database 导入 + executePreset + openInTerminal）
+- Test: `tests/main/terminalLauncher.test.ts`（追加编排分发用例）
+
+- [ ] **Step 1: 追加编排分发的失败测试**
+
+在 `tests/main/terminalLauncher.test.ts` **顶部**添加 mock 与新的 import（原文件顶部的 `import { ... } from '../../src/main/utils/terminalLauncher'` 保留，但需在 mock 声明之后）。将文件顶部改为：
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const mockDbGet = vi.fn()
+const mockSpawn = vi.fn()
+const mockExec = vi.fn((...args: unknown[]) => {
+  const cb = args[args.length - 1]
+  if (typeof cb === 'function') cb(null, { stdout: '', stderr: '' })
+})
+
+vi.mock('child_process', () => ({ spawn: mockSpawn, exec: mockExec }))
+vi.mock('../../src/main/api/shared/database', () => ({
+  default: { dbGet: mockDbGet, dbPut: vi.fn() }
+}))
+
+import {
+  getPresetOptions,
+  resolvePreset,
+  applyPathToArgs,
+  parseCustomCommand,
+  openInTerminal
+} from '../../src/main/utils/terminalLauncher'
+```
+
+在文件末尾追加：
+
+```ts
+// ========== openInTerminal 编排分发 ==========
+
+describe('openInTerminal 编排分发', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSpawn.mockImplementation(() => ({ pid: 12345, unref: vi.fn(), on: vi.fn() }))
+  })
+
+  it('预设 ghostty → spawn open 并替换 {path}', async () => {
+    mockDbGet.mockReturnValue({ terminal: 'ghostty' })
+    const ok = await openInTerminal('/Users/test/proj')
+    expect(ok).toBe(true)
+    expect(mockSpawn).toHaveBeenCalledWith(
+      'open',
+      ['-na', 'Ghostty.app', '--args', '--working-directory=/Users/test/proj'],
+      expect.objectContaining({ detached: true })
+    )
+  })
+
+  it('自定义命令 → 解析并替换 {path}', async () => {
+    mockDbGet.mockReturnValue({
+      terminal: 'custom',
+      terminalCustomCommand: 'alacritty --working-directory={path}'
+    })
+    const ok = await openInTerminal('/my/dir')
+    expect(ok).toBe(true)
+    expect(mockSpawn).toHaveBeenCalledWith(
+      'alacritty',
+      ['--working-directory=/my/dir'],
+      expect.objectContaining({ detached: true })
+    )
+  })
+
+  it('自定义命令为空 → 回退默认（mac 走 applescript，不 spawn）', async () => {
+    mockDbGet.mockReturnValue({ terminal: 'custom', terminalCustomCommand: '' })
+    const ok = await openInTerminal('/x')
+    expect(ok).toBe(true)
+    expect(mockSpawn).not.toHaveBeenCalled()
+    expect(mockExec).toHaveBeenCalled()
+  })
+})
+```
+
+> 注：第 3 个用例依赖测试机为 macOS（`process.platform === 'darwin'`），本仓库开发机即 macOS，可接受。
+
+- [ ] **Step 2: 运行测试确认新增用例失败**
+
+Run: `pnpm test tests/main/terminalLauncher.test.ts`
+Expected: FAIL — `openInTerminal` 未导出（`TypeError: openInTerminal is not a function`）。
+
+- [ ] **Step 3: 在 terminalLauncher.ts 追加 database 导入与编排函数**
+
+在文件**顶部 import 区**追加（在 `import { promisify } from 'util'` 之后）：
+
+```ts
+import databaseAPI from '../api/shared/database'
+```
+
+在文件**末尾**追加：
+
+```ts
+
+// ==================== 编排：读取配置 → 分发 ====================
+
+async function executePreset(entry: PresetEntry | null, folderPath: string): Promise<boolean> {
+  if (!entry) return false
+  const preset = entry.preset
+  if (preset.type === 'cli') {
+    return runCli(preset.command, applyPathToArgs(preset.args, folderPath))
+  }
+  if (preset.type === 'applescript') {
+    await runAppleScript(preset.build(folderPath))
+    return true
+  }
+  return preset.run(folderPath)
+}
+
+export async function openInTerminal(folderPath: string): Promise<boolean> {
+  try {
+    const settings = (databaseAPI.dbGet('settings-general') as Record<string, any>) || {}
+    const terminal: string | undefined = settings.terminal
+    const customCommand: string | undefined = settings.terminalCustomCommand
+
+    // 自定义命令优先
+    if (terminal === 'custom') {
+      const parsed = parseCustomCommand(customCommand ?? '')
+      if (parsed) {
+        return runCli(parsed.command, applyPathToArgs(parsed.args, folderPath))
+      }
+      // 自定义命令为空 → 回退默认
+      return executePreset(resolvePreset('default', process.platform), folderPath)
+    }
+
+    return executePreset(resolvePreset(terminal, process.platform), folderPath)
+  } catch (error) {
+    console.error('[TerminalLauncher] 打开终端失败:', error)
+    return false
+  }
+}
+```
+
+- [ ] **Step 4: 运行测试确认全部通过**
+
+Run: `pnpm test tests/main/terminalLauncher.test.ts`
+Expected: PASS — 全部用例（含 3 个编排分发用例）通过。
+
+- [ ] **Step 5: 类型检查**
+
+Run: `pnpm typecheck:node`
+Expected: 无错误。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/main/utils/terminalLauncher.ts tests/main/terminalLauncher.test.ts
+git commit -m "feat(terminal): 添加 openInTerminal 编排函数读取配置分发"
+```
+
+---
+
+### Task 3: 接入 systemCommands.handleOpenTerminal，删除迁出代码
+
+**Files:**
+- Modify: `src/main/api/renderer/systemCommands.ts`
+
+- [ ] **Step 1: 修改 handleOpenTerminal 的终端启动段**
+
+在 `src/main/api/renderer/systemCommands.ts` 中，将 `handleOpenTerminal` 内 596-611 行的「根据平台打开终端」分支替换为调用 terminalLauncher。把这一段：
+
+```ts
+    // 根据平台打开终端
+    if (process.platform === 'darwin') {
+      await openTerminalOnMac(targetPath, execAsync)
+    } else if (process.platform === 'linux') {
+      const launched = await openTerminalOnLinux(targetPath)
+      if (!launched) {
+        throw new Error('Could not find a supported terminal emulator')
+      }
+    } else if (process.platform === 'win32') {
+      const launched = await tryLaunchWindowsTerminal(targetPath)
+      if (!launched) {
+        return { success: false, error: '无法启动终端' }
+      }
+    } else {
+      return { success: false, error: `不支持的平台: ${process.platform}` }
+    }
+```
+
+替换为：
+
+```ts
+    // 打开终端（统一走 terminalLauncher，按用户配置分发）
+    const launched = await terminalLauncher.openInTerminal(targetPath)
+    if (!launched) {
+      return { success: false, error: '无法启动终端' }
+    }
+```
+
+- [ ] **Step 2: 添加 terminalLauncher 导入**
+
+在 `systemCommands.ts` 顶部 import 区（`import databaseAPI from '../shared/database'` 附近）追加：
+
+```ts
+import * as terminalLauncher from '../../utils/terminalLauncher'
+```
+
+- [ ] **Step 3: 删除迁出的函数与转义辅助**
+
+从 `systemCommands.ts` 中**整段删除**以下五处（它们已被 terminalLauncher 取代，且无外部引用）：
+- `escapePowerShellPath`（原 50-53）
+- `escapeCmdPath`（原 59-63）
+- `tryLaunchWindowsTerminal`（原 65-88，含其内部 `tryLaunch`）
+- `openTerminalOnMac`（原 497-508）
+- `openTerminalOnLinux`（原 514-536，含其内部 `tryLaunch`）
+
+> 注意：`getMacFinderPath`（541-555）**保留不动**，它属于路径获取。
+
+- [ ] **Step 4: 类型检查**
+
+Run: `pnpm typecheck:node`
+Expected: 无错误。若报 `spawn`/`exec` 未使用，确认 `systemCommands.ts` 顶部 `import { exec, spawn } from 'child_process'` 是否还被其他函数使用（如 executeSystemCommand 内的其他命令）；若仍被使用则保留，若不再被使用则一并删除该 import 的未用符号。
+
+- [ ] **Step 5: 运行全量测试确认无回归**
+
+Run: `pnpm test`
+Expected: 全部通过（terminalLauncher 用例通过，其他用例不受影响）。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add src/main/api/renderer/systemCommands.ts
+git commit -m "refactor(terminal): handleOpenTerminal 改用 terminalLauncher 并删除迁出代码"
+```
+
+---
+
+### Task 4: appleScriptHelper.openInTerminal 改为委托 terminalLauncher
+
+**Files:**
+- Modify: `src/main/utils/appleScriptHelper.ts:184-200`
+
+- [ ] **Step 1: 改写 openInTerminal 方法**
+
+将 `src/main/utils/appleScriptHelper.ts` 中 `openInTerminal` 方法（184-200）：
+
+```ts
+  async openInTerminal(path: string): Promise<boolean> {
+    try {
+      // 转义路径中的单引号
+      const escapedPath = path.replace(/'/g, "'\\''")
+      const script = `
+        tell application "Terminal"
+          activate
+          do script "cd '${escapedPath}'"
+        end tell
+      `
+      await this.execute(script)
+      return true
+    } catch (error) {
+      console.error('[AppleScript] 在终端打开路径失败:', error)
+      return false
+    }
+  }
+```
+
+替换为：
+
+```ts
+  async openInTerminal(path: string): Promise<boolean> {
+    try {
+      return await terminalLauncher.openInTerminal(path)
+    } catch (error) {
+      console.error('[AppleScript] 在终端打开路径失败:', error)
+      return false
+    }
+  }
+```
+
+- [ ] **Step 2: 添加 terminalLauncher 导入**
+
+在 `appleScriptHelper.ts` 顶部 import 区追加：
+
+```ts
+import * as terminalLauncher from './terminalLauncher'
+```
+
+> 注意：`appleScriptHelper.ts` 的 `execute` 私有方法仍被其他方法（getFinderPath 等）使用，保留不动。
+
+- [ ] **Step 3: 类型检查**
+
+Run: `pnpm typecheck:node`
+Expected: 无错误。
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add src/main/utils/appleScriptHelper.ts
+git commit -m "refactor(terminal): appleScriptHelper.openInTerminal 委托 terminalLauncher"
+```
+
+---
+
+### Task 5: constants.ts 添加 TerminalType 类型
+
+**Files:**
+- Modify: `internal-plugins/setting/src/constants.ts`
+
+- [ ] **Step 1: 添加类型**
+
+在 `internal-plugins/setting/src/constants.ts` 末尾追加：
+
+```ts
+/** 「在终端打开」使用的终端选择：'default' 系统默认 ｜ 'custom' 自定义命令 ｜ 其他预设 id */
+export type TerminalType = 'default' | 'custom' | string
+```
+
+> 说明：预设 id（ghostty/iterm2/wt 等）是平台相关的字符串，不做成联合字面量；TerminalType 仅约束「至少是字符串」，运行时由 terminalLauncher 校验 id 有效性并回退默认。
+
+- [ ] **Step 2: 提交**
+
+```bash
+git add internal-plugins/setting/src/constants.ts
+git commit -m "feat(terminal): 添加 TerminalType 类型"
+```
+
+---
+
+### Task 6: GeneralSetting.vue 添加终端设置 UI
+
+**Files:**
+- Modify: `internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue`
+
+- [ ] **Step 1: 添加 ref 与选项 computed**
+
+在 `GeneralSetting.vue` 的 `<script setup>` 中，`platform` ref（102 行）之后添加：
+
+```ts
+// 终端打开设置
+const terminal = ref<TerminalType>('default')
+const terminalCustomCommand = ref('')
+
+// 终端预设选项（按平台；仅 UI 标签，启动逻辑在主进程 terminalLauncher）
+const terminalOptions = computed(() => {
+  if (platform.value === 'win32') {
+    return [
+      { label: '系统默认', value: 'default' },
+      { label: 'Windows Terminal', value: 'wt' },
+      { label: 'PowerShell', value: 'powershell' },
+      { label: 'CMD', value: 'cmd' },
+      { label: '自定义', value: 'custom' }
+    ]
+  }
+  if (platform.value === 'linux') {
+    return [
+      { label: '系统默认', value: 'default' },
+      { label: 'GNOME Terminal', value: 'gnome-terminal' },
+      { label: 'Konsole', value: 'konsole' },
+      { label: 'XTerm', value: 'xterm' },
+      { label: '自定义', value: 'custom' }
+    ]
+  }
+  return [
+    { label: '系统默认 (Terminal)', value: 'default' },
+    { label: 'Ghostty', value: 'ghostty' },
+    { label: 'iTerm2', value: 'iterm2' },
+    { label: '自定义', value: 'custom' }
+  ]
+})
+```
+
+并在 import 区引入类型（若 `TerminalType` 尚未导入）：
+
+```ts
+import type { TerminalType } from '@/constants'
+```
+
+> 确认 `@/constants` 别名可用：`internal-plugins/setting/src/views/PluginsSetting/PluginsSetting.vue` 等已用 `@/` 别名引用 constants。若 `computed` 未导入，从 `vue` 补充导入。
+
+- [ ] **Step 2: loadSettings 读取两字段**
+
+在 `loadSettings()`（1162 起）的 `if (data) { ... }` 块内追加（与其他字段同处）：
+
+```ts
+      terminal.value = data.terminal ?? 'default'
+      terminalCustomCommand.value = data.terminalCustomCommand ?? ''
+```
+
+- [ ] **Step 3: saveSettings 合并写两字段**
+
+在 `saveSettings()`（1258）的 `dbPut('settings-general', { ...existing, ... })` 对象内追加（建议放在 `clipboardRetentionDays` 之后）：
+
+```ts
+      terminal: terminal.value,
+      terminalCustomCommand: terminalCustomCommand.value
+```
+
+- [ ] **Step 4: 添加 UI 模板**
+
+在模板中找一个合适位置（建议放在「外观」`setting-group` 之后，或「通用」组末尾），新增一个 `setting-group`：
+
+```html
+    <!-- ==================== 终端打开 ==================== -->
+    <div class="setting-group">
+      <h3 class="setting-group-title">终端打开</h3>
+
+      <div class="setting-item">
+        <div class="setting-label">
+          <span>打开终端应用</span>
+          <span class="setting-desc">从 Finder 唤出「在终端打开」时使用的终端</span>
+        </div>
+        <div class="setting-control">
+          <Dropdown v-model="terminal" :options="terminalOptions" @change="saveSettings" />
+        </div>
+      </div>
+
+      <div v-if="terminal === 'custom'" class="setting-item">
+        <div class="setting-label">
+          <span>自定义命令</span>
+          <span class="setting-desc">用 {path} 代表目标目录，如 ghostty --working-directory={path}</span>
+        </div>
+        <div class="setting-control">
+          <input
+            v-model="terminalCustomCommand"
+            type="text"
+            class="input"
+            placeholder="alacritty --working-directory={path}"
+            @blur="saveSettings"
+            @keyup.enter="saveSettings"
+          />
+        </div>
+      </div>
+    </div>
+```
+
+- [ ] **Step 5: 类型检查**
+
+Run: `cd internal-plugins/setting && pnpm vue-tsc --noEmit -p tsconfig.json` （或仓库根的 `pnpm typecheck:web`）
+Expected: 无错误。
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue
+git commit -m "feat(terminal): 通用设置页新增终端选择与自定义命令 UI"
+```
+
+---
+
+### Task 7: 全量验证
+
+**Files:** 无（验证 only）
+
+- [ ] **Step 1: 全量类型检查 + 测试**
+
+Run: `pnpm typecheck && pnpm test`
+Expected: 全部通过。
+
+- [ ] **Step 2: 构建**
+
+Run: `pnpm build`
+Expected: 构建成功（含 `build:setting`）。
+
+- [ ] **Step 3: 手动验证 — macOS Ghostty（核心用例）**
+
+Run: `pnpm dev`
+1. 打开设置 → 通用设置 → 终端打开 → 选「Ghostty」。
+2. 在 Finder 选中一个文件夹 → 用 ZTools 唤出 →「在终端打开」。
+3. Expected: Ghostty 打开并 cd 到该目录。
+
+- [ ] **Step 4: 手动验证 — 系统默认无回归**
+
+1. 设置 → 终端打开 → 选「系统默认 (Terminal)」。
+2. Finder 唤出「在终端打开」。
+3. Expected: Terminal.app 打开并 cd（与改动前行为一致）。
+
+- [ ] **Step 5: 手动验证 — 自定义命令**
+
+1. 设置 → 终端打开 → 选「自定义」→ 填 `open -na Ghostty.app --args --working-directory={path}`。
+2. Finder 唤出「在终端打开」。
+3. Expected: Ghostty 打开并 cd 到该目录。
+
+- [ ] **Step 6: 手动验证 — 合并写安全**
+
+1. 修改终端设置后，重新打开设置页，确认 theme / 唤醒黑名单等其他字段未被覆盖。
+2. Expected: 其他设置值保持不变。
+
+- [ ] **Step 7: 收尾提交（如有验证中发现的修复）**
+
+```bash
+git add -A
+git commit -m "test(terminal): 验证通过"
+```
+
+---
+
+## Self-Review（计划自检）
+
+**1. Spec 覆盖：**
+- ✅ 新建 terminalLauncher 统一两处 → Task 1+2+3+4
+- ✅ settings-general 加 terminal / terminalCustomCommand → Task 6（save/load）
+- ✅ 三平台预设 → Task 1 注册表
+- ✅ macOS Ghostty `open -na Ghostty.app --args --working-directory={path}` → Task 1 MAC_PRESETS
+- ✅ UI 塞进通用设置页、Dropdown + 条件输入框 → Task 6
+- ✅ 无新增 IPC（主进程直接 dbGet）→ Task 2 openInTerminal
+- ✅ 向后兼容（default 行为不变）→ Task 1 默认处理器迁入原逻辑
+- ⚠️ Warp 预设：spec 列了但标注「待确认」，本计划暂不实现（计划头已说明理由）——如需补，加一个 MAC_PRESETS 条目即可。
+- ⚠️ parseCommandString 复用 → 改为内联（计划头已说明理由）。
+
+**2. 占位符扫描：** 无 TBD/TODO；每步含完整代码或确切命令。
+
+**3. 类型一致性：** `openInTerminal(folderPath: string): Promise<boolean>` 在 Task 2 定义，Task 3/4 调用签名一致；`PresetOption {label, value}` 在 Task 1 定义，Task 6 UI options 与之一致；`TerminalType` Task 5 定义，Task 6 使用。

From 7132bfd8d1e3c926d0b0f5526c371baa4ce7e71f Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 15:25:22 +0800
Subject: [PATCH 3/9] =?UTF-8?q?feat(terminal):=20=E6=96=B0=E5=BB=BA=20term?=
 =?UTF-8?q?inalLauncher=20=E7=BB=9F=E4=B8=80=E7=BB=88=E7=AB=AF=E5=90=AF?=
 =?UTF-8?q?=E5=8A=A8=E7=BA=AF=E9=80=BB=E8=BE=91=E4=B8=8E=E9=A2=84=E8=AE=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/utils/terminalLauncher.ts  | 243 ++++++++++++++++++++++++++++
 tests/main/terminalLauncher.test.ts | 101 ++++++++++++
 2 files changed, 344 insertions(+)
 create mode 100644 src/main/utils/terminalLauncher.ts
 create mode 100644 tests/main/terminalLauncher.test.ts

diff --git a/src/main/utils/terminalLauncher.ts b/src/main/utils/terminalLauncher.ts
new file mode 100644
index 00000000..44bd6b27
--- /dev/null
+++ b/src/main/utils/terminalLauncher.ts
@@ -0,0 +1,243 @@
+import { exec, spawn } from 'child_process'
+import { promisify } from 'util'
+
+const execAsync = promisify(exec)
+
+// ==================== 类型 ====================
+
+/** 预设选项（供 UI 下拉使用） */
+export interface PresetOption {
+  label: string
+  value: string
+}
+
+/** 预设的启动方式 */
+type Preset =
+  | { type: 'cli'; command: string; args: string[] } // args 中可含 '{path}' 占位符
+  | { type: 'applescript'; build: (path: string) => string } // 返回完整 AppleScript
+  | { type: 'handler'; run: (path: string) => Promise<boolean> } // 自定义启动（回退链等）
+
+interface PresetEntry {
+  id: string
+  label: string
+  preset: Preset
+}
+
+// ==================== 路径转义（从 systemCommands 迁入，行为不变）====================
+
+function escapePowerShellPath(folderPath: string): string {
+  const escaped = folderPath.replace(/'/g, "''")
+  return `'${escaped}'`
+}
+
+function escapeCmdPath(folderPath: string): string {
+  const escaped = folderPath.replace(/"/g, '^"')
+  return `"${escaped}"`
+}
+
+// ==================== 命令字符串解析（内联，避免耦合 commandLauncher）====================
+
+/** 将命令字符串拆分为 [可执行文件, 参数列表]，处理引号 */
+function parseCommandString(cmd: string): [string, string[]] {
+  const parts: string[] = []
+  let current = ''
+  let inQuote: string | null = null
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i]
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null
+      } else {
+        current += ch
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch
+    } else if (/\s/.test(ch)) {
+      if (current) {
+        parts.push(current)
+        current = ''
+      }
+    } else {
+      current += ch
+    }
+  }
+  if (current) parts.push(current)
+  return [parts[0], parts.slice(1)]
+}
+
+// ==================== 执行原语 ====================
+
+/** 执行 AppleScript（转义单引号，防止 shell 注入） */
+export async function runAppleScript(script: string): Promise<void> {
+  const escaped = script.replace(/'/g, "'\\''")
+  await execAsync(`osascript -e '${escaped}'`)
+}
+
+/** detached 启动 CLI 命令，返回是否成功拿到 pid */
+function runCli(command: string, args: string[]): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' })
+    child.on('error', () => resolve(false))
+    if (child.pid) {
+      child.unref()
+      resolve(true)
+    }
+  })
+}
+
+// ==================== 默认处理器（从 systemCommands 迁入，行为不变）====================
+// 注：macOS 默认预设直接使用 applescript build（Terminal.app 始终存在，无需回退链），
+// 故此处不再保留 launchDefaultMac；Linux/Windows 需要回退链，保留对应 handler。
+
+async function launchDefaultLinux(path: string): Promise<boolean> {
+  return (
+    (await runCli('exo-open', ['--launch', 'TerminalEmulator', '--working-directory', path])) ||
+    (await runCli('gnome-terminal', [`--working-directory=${path}`])) ||
+    (await runCli('xterm', ['-cd', path]))
+  )
+}
+
+async function launchDefaultWindows(path: string): Promise<boolean> {
+  return (
+    (await runCli('wt.exe', ['-d', path])) ||
+    (await runCli('powershell.exe', [
+      '-NoExit',
+      '-Command',
+      `Set-Location -Path ${escapePowerShellPath(path)}`
+    ])) ||
+    (await runCli('cmd.exe', ['/K', `cd /d ${escapeCmdPath(path)}`]))
+  )
+}
+
+// ==================== 预设注册表 ====================
+
+const MAC_PRESETS: PresetEntry[] = [
+  {
+    id: 'default',
+    label: '系统默认 (Terminal)',
+    preset: {
+      type: 'applescript',
+      build: (p) => `
+    tell application "Terminal"
+      activate
+      do script "cd " & quoted form of "${p}"
+    end tell
+  `
+    }
+  },
+  {
+    id: 'ghostty',
+    label: 'Ghostty',
+    preset: {
+      type: 'cli',
+      command: 'open',
+      args: ['-na', 'Ghostty.app', '--args', '--working-directory={path}']
+    }
+  },
+  {
+    id: 'iterm2',
+    label: 'iTerm2',
+    preset: {
+      type: 'applescript',
+      build: (p) => `
+    tell application "iTerm"
+      activate
+      tell (create window with default profile)
+        write session "cd " & quoted form of "${p}"
+      end tell
+    end tell
+  `
+    }
+  }
+]
+
+const LINUX_PRESETS: PresetEntry[] = [
+  { id: 'default', label: '系统默认', preset: { type: 'handler', run: launchDefaultLinux } },
+  {
+    id: 'gnome-terminal',
+    label: 'GNOME Terminal',
+    preset: { type: 'cli', command: 'gnome-terminal', args: ['--working-directory={path}'] }
+  },
+  {
+    id: 'konsole',
+    label: 'Konsole',
+    preset: { type: 'cli', command: 'konsole', args: ['--workdir', '{path}'] }
+  },
+  {
+    id: 'xterm',
+    label: 'XTerm',
+    preset: { type: 'cli', command: 'xterm', args: ['-cd', '{path}'] }
+  }
+]
+
+const WINDOWS_PRESETS: PresetEntry[] = [
+  { id: 'default', label: '系统默认', preset: { type: 'handler', run: launchDefaultWindows } },
+  {
+    id: 'wt',
+    label: 'Windows Terminal',
+    preset: { type: 'cli', command: 'wt.exe', args: ['-d', '{path}'] }
+  },
+  {
+    id: 'powershell',
+    label: 'PowerShell',
+    preset: {
+      type: 'handler',
+      run: (p) =>
+        runCli('powershell.exe', [
+          '-NoExit',
+          '-Command',
+          `Set-Location -Path ${escapePowerShellPath(p)}`
+        ])
+    }
+  },
+  {
+    id: 'cmd',
+    label: 'CMD',
+    preset: {
+      type: 'handler',
+      run: (p) => runCli('cmd.exe', ['/K', `cd /d ${escapeCmdPath(p)}`])
+    }
+  }
+]
+
+// ==================== 纯函数（可单测）====================
+
+function getPlatformPresets(platform: string): PresetEntry[] {
+  if (platform === 'darwin') return MAC_PRESETS
+  if (platform === 'linux') return LINUX_PRESETS
+  if (platform === 'win32') return WINDOWS_PRESETS
+  return []
+}
+
+/** 返回当前平台的下拉选项（含「自定义」）；未知平台返回空数组 */
+export function getPresetOptions(platform: string): PresetOption[] {
+  const presets = getPlatformPresets(platform)
+  if (presets.length === 0) return []
+  const options = presets.map((p) => ({ label: p.label, value: p.id }))
+  options.push({ label: '自定义', value: 'custom' })
+  return options
+}
+
+/** 按 terminal 值解析预设；空值/无效值回退默认，'custom' 返回 null（由编排函数处理） */
+export function resolvePreset(terminal: string | undefined, platform: string): PresetEntry | null {
+  const presets = getPlatformPresets(platform)
+  if (!terminal) {
+    return presets.find((p) => p.id === 'default') ?? null
+  }
+  if (terminal === 'custom') return null
+  return presets.find((p) => p.id === terminal) ?? presets.find((p) => p.id === 'default') ?? null
+}
+
+/** 将 args 中的 {path} 占位符替换为实际路径 */
+export function applyPathToArgs(args: string[], folderPath: string): string[] {
+  return args.map((a) => a.replaceAll('{path}', folderPath))
+}
+
+/** 解析自定义命令模板；空字符串返回 null */
+export function parseCustomCommand(template: string): { command: string; args: string[] } | null {
+  const trimmed = template.trim()
+  if (!trimmed) return null
+  const [command, args] = parseCommandString(trimmed)
+  if (!command) return null
+  return { command, args }
+}
diff --git a/tests/main/terminalLauncher.test.ts b/tests/main/terminalLauncher.test.ts
new file mode 100644
index 00000000..c114e85c
--- /dev/null
+++ b/tests/main/terminalLauncher.test.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import {
+  getPresetOptions,
+  resolvePreset,
+  applyPathToArgs,
+  parseCustomCommand
+} from '../../src/main/utils/terminalLauncher'
+
+// ========== getPresetOptions ==========
+
+describe('getPresetOptions', () => {
+  it('macOS 含 系统默认/Ghostty/iTerm2/自定义', () => {
+    const opts = getPresetOptions('darwin')
+    expect(opts.map((o) => o.value)).toEqual(['default', 'ghostty', 'iterm2', 'custom'])
+  })
+
+  it('Linux 含 系统默认/gnome-terminal/konsole/xterm/自定义', () => {
+    const opts = getPresetOptions('linux')
+    expect(opts.map((o) => o.value)).toEqual([
+      'default',
+      'gnome-terminal',
+      'konsole',
+      'xterm',
+      'custom'
+    ])
+  })
+
+  it('Windows 含 系统默认/wt/powershell/cmd/自定义', () => {
+    const opts = getPresetOptions('win32')
+    expect(opts.map((o) => o.value)).toEqual(['default', 'wt', 'powershell', 'cmd', 'custom'])
+  })
+
+  it('未知平台返回空数组', () => {
+    expect(getPresetOptions('freebsd')).toEqual([])
+  })
+})
+
+// ========== resolvePreset ==========
+
+describe('resolvePreset', () => {
+  it('空值返回默认预设', () => {
+    expect(resolvePreset(undefined, 'darwin')?.id).toBe('default')
+  })
+
+  it('custom 返回 null', () => {
+    expect(resolvePreset('custom', 'darwin')).toBeNull()
+  })
+
+  it('有效 id 返回对应预设', () => {
+    expect(resolvePreset('ghostty', 'darwin')?.id).toBe('ghostty')
+  })
+
+  it('无效 id 回退默认', () => {
+    expect(resolvePreset('nonexistent', 'darwin')?.id).toBe('default')
+  })
+
+  it('id 在当前平台不存在时回退默认', () => {
+    expect(resolvePreset('ghostty', 'win32')?.id).toBe('default')
+  })
+})
+
+// ========== applyPathToArgs ==========
+
+describe('applyPathToArgs', () => {
+  it('替换 {path} 占位符', () => {
+    expect(applyPathToArgs(['--working-directory={path}'], '/Users/x')).toEqual([
+      '--working-directory=/Users/x'
+    ])
+  })
+
+  it('多个占位符都替换', () => {
+    expect(applyPathToArgs(['{path}', 'cd {path}'], '/p')).toEqual(['/p', 'cd /p'])
+  })
+
+  it('无占位符保持不变', () => {
+    expect(applyPathToArgs(['-la'], '/p')).toEqual(['-la'])
+  })
+})
+
+// ========== parseCustomCommand ==========
+
+describe('parseCustomCommand', () => {
+  it('解析命令与参数', () => {
+    expect(parseCustomCommand('alacritty --working-directory={path}')).toEqual({
+      command: 'alacritty',
+      args: ['--working-directory={path}']
+    })
+  })
+
+  it('处理引号包裹的参数（去除引号）', () => {
+    expect(parseCustomCommand('open -na "Ghostty.app"')).toEqual({
+      command: 'open',
+      args: ['-na', 'Ghostty.app']
+    })
+  })
+
+  it('空字符串/纯空白返回 null', () => {
+    expect(parseCustomCommand('')).toBeNull()
+    expect(parseCustomCommand('   ')).toBeNull()
+  })
+})

From 6de969c894387ee98dfa096979fc7df07b5850cf Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 15:44:41 +0800
Subject: [PATCH 4/9] =?UTF-8?q?feat(terminal):=20=E6=B7=BB=E5=8A=A0=20open?=
 =?UTF-8?q?InTerminal=20=E7=BC=96=E6=8E=92=E5=87=BD=E6=95=B0=E8=AF=BB?=
 =?UTF-8?q?=E5=8F=96=E9=85=8D=E7=BD=AE=E5=88=86=E5=8F=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/utils/terminalLauncher.ts  | 45 ++++++++++++++-
 tests/main/terminalLauncher.test.ts | 88 ++++++++++++++++++++++++++++-
 2 files changed, 128 insertions(+), 5 deletions(-)

diff --git a/src/main/utils/terminalLauncher.ts b/src/main/utils/terminalLauncher.ts
index 44bd6b27..69035d76 100644
--- a/src/main/utils/terminalLauncher.ts
+++ b/src/main/utils/terminalLauncher.ts
@@ -1,5 +1,6 @@
 import { exec, spawn } from 'child_process'
 import { promisify } from 'util'
+import databaseAPI from '../api/shared/database'
 
 const execAsync = promisify(exec)
 
@@ -25,12 +26,12 @@ interface PresetEntry {
 
 // ==================== 路径转义（从 systemCommands 迁入，行为不变）====================
 
-function escapePowerShellPath(folderPath: string): string {
+export function escapePowerShellPath(folderPath: string): string {
   const escaped = folderPath.replace(/'/g, "''")
   return `'${escaped}'`
 }
 
-function escapeCmdPath(folderPath: string): string {
+export function escapeCmdPath(folderPath: string): string {
   const escaped = folderPath.replace(/"/g, '^"')
   return `"${escaped}"`
 }
@@ -68,7 +69,7 @@ function parseCommandString(cmd: string): [string, string[]] {
 // ==================== 执行原语 ====================
 
 /** 执行 AppleScript（转义单引号，防止 shell 注入） */
-export async function runAppleScript(script: string): Promise<void> {
+async function runAppleScript(script: string): Promise<void> {
   const escaped = script.replace(/'/g, "'\\''")
   await execAsync(`osascript -e '${escaped}'`)
 }
@@ -241,3 +242,41 @@ export function parseCustomCommand(template: string): { command: string; args: s
   if (!command) return null
   return { command, args }
 }
+
+// ==================== 编排：读取配置 → 分发 ====================
+
+async function executePreset(entry: PresetEntry | null, folderPath: string): Promise<boolean> {
+  if (!entry) return false
+  const preset = entry.preset
+  if (preset.type === 'cli') {
+    return runCli(preset.command, applyPathToArgs(preset.args, folderPath))
+  }
+  if (preset.type === 'applescript') {
+    await runAppleScript(preset.build(folderPath))
+    return true
+  }
+  return preset.run(folderPath)
+}
+
+export async function openInTerminal(folderPath: string): Promise<boolean> {
+  try {
+    const settings = (databaseAPI.dbGet('settings-general') as Record<string, any>) || {}
+    const terminal: string | undefined = settings.terminal
+    const customCommand: string | undefined = settings.terminalCustomCommand
+
+    // 自定义命令优先
+    if (terminal === 'custom') {
+      const parsed = parseCustomCommand(customCommand ?? '')
+      if (parsed) {
+        return runCli(parsed.command, applyPathToArgs(parsed.args, folderPath))
+      }
+      // 自定义命令为空 → 回退默认
+      return executePreset(resolvePreset('default', process.platform), folderPath)
+    }
+
+    return executePreset(resolvePreset(terminal, process.platform), folderPath)
+  } catch (error) {
+    console.error('[TerminalLauncher] 打开终端失败:', error)
+    return false
+  }
+}
diff --git a/tests/main/terminalLauncher.test.ts b/tests/main/terminalLauncher.test.ts
index c114e85c..7a7bc903 100644
--- a/tests/main/terminalLauncher.test.ts
+++ b/tests/main/terminalLauncher.test.ts
@@ -1,9 +1,27 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const { mockDbGet, mockSpawn, mockExec } = vi.hoisted(() => ({
+  mockDbGet: vi.fn(),
+  mockSpawn: vi.fn(),
+  mockExec: vi.fn((...args: unknown[]) => {
+    const cb = args[args.length - 1]
+    if (typeof cb === 'function') cb(null, { stdout: '', stderr: '' })
+  })
+}))
+
+vi.mock('child_process', () => ({ spawn: mockSpawn, exec: mockExec }))
+vi.mock('../../src/main/api/shared/database', () => ({
+  default: { dbGet: mockDbGet, dbPut: vi.fn() }
+}))
+
 import {
   getPresetOptions,
   resolvePreset,
   applyPathToArgs,
-  parseCustomCommand
+  parseCustomCommand,
+  openInTerminal,
+  escapePowerShellPath,
+  escapeCmdPath
 } from '../../src/main/utils/terminalLauncher'
 
 // ========== getPresetOptions ==========
@@ -57,6 +75,10 @@ describe('resolvePreset', () => {
   it('id 在当前平台不存在时回退默认', () => {
     expect(resolvePreset('ghostty', 'win32')?.id).toBe('default')
   })
+
+  it('未知平台返回 null', () => {
+    expect(resolvePreset(undefined, 'freebsd')).toBeNull()
+  })
 })
 
 // ========== applyPathToArgs ==========
@@ -99,3 +121,65 @@ describe('parseCustomCommand', () => {
     expect(parseCustomCommand('   ')).toBeNull()
   })
 })
+
+// ========== 路径转义（安全关键）==========
+
+describe('escapePowerShellPath', () => {
+  it('单引号包裹并将内部单引号翻倍', () => {
+    expect(escapePowerShellPath("a'b")).toBe("'a''b'")
+  })
+  it('无单引号仅包裹', () => {
+    expect(escapePowerShellPath('/Users/x')).toBe("'/Users/x'")
+  })
+})
+
+describe('escapeCmdPath', () => {
+  it('双引号包裹并转义内部双引号', () => {
+    expect(escapeCmdPath('a"b')).toBe('"a^"b"')
+  })
+  it('无双引号仅包裹', () => {
+    expect(escapeCmdPath('/Users/x')).toBe('"/Users/x"')
+  })
+})
+
+// ========== openInTerminal 编排分发 ==========
+
+describe('openInTerminal 编排分发', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSpawn.mockImplementation(() => ({ pid: 12345, unref: vi.fn(), on: vi.fn() }))
+  })
+
+  it('预设 ghostty → spawn open 并替换 {path}', async () => {
+    mockDbGet.mockReturnValue({ terminal: 'ghostty' })
+    const ok = await openInTerminal('/Users/test/proj')
+    expect(ok).toBe(true)
+    expect(mockSpawn).toHaveBeenCalledWith(
+      'open',
+      ['-na', 'Ghostty.app', '--args', '--working-directory=/Users/test/proj'],
+      expect.objectContaining({ detached: true })
+    )
+  })
+
+  it('自定义命令 → 解析并替换 {path}', async () => {
+    mockDbGet.mockReturnValue({
+      terminal: 'custom',
+      terminalCustomCommand: 'alacritty --working-directory={path}'
+    })
+    const ok = await openInTerminal('/my/dir')
+    expect(ok).toBe(true)
+    expect(mockSpawn).toHaveBeenCalledWith(
+      'alacritty',
+      ['--working-directory=/my/dir'],
+      expect.objectContaining({ detached: true })
+    )
+  })
+
+  it('自定义命令为空 → 回退默认（mac 走 applescript，不 spawn）', async () => {
+    mockDbGet.mockReturnValue({ terminal: 'custom', terminalCustomCommand: '' })
+    const ok = await openInTerminal('/x')
+    expect(ok).toBe(true)
+    expect(mockSpawn).not.toHaveBeenCalled()
+    expect(mockExec).toHaveBeenCalled()
+  })
+})

From bc61bba4c4ec67e0494f21a9bdf86d3fad93fe2f Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 15:54:12 +0800
Subject: [PATCH 5/9] =?UTF-8?q?test(terminal):=20=E7=BC=96=E6=8E=92?=
 =?UTF-8?q?=E5=88=86=E5=8F=91=E6=B5=8B=E8=AF=95=E6=94=B9=E4=B8=BA=E5=B9=B3?=
 =?UTF-8?q?=E5=8F=B0=E5=8F=AF=E7=A7=BB=E6=A4=8D=E5=B9=B6=E9=AA=8C=E8=AF=81?=
 =?UTF-8?q?=20AppleScript=20=E5=86=85=E5=AE=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/main/terminalLauncher.test.ts | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/tests/main/terminalLauncher.test.ts b/tests/main/terminalLauncher.test.ts
index 7a7bc903..c46d7f7d 100644
--- a/tests/main/terminalLauncher.test.ts
+++ b/tests/main/terminalLauncher.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 
 const { mockDbGet, mockSpawn, mockExec } = vi.hoisted(() => ({
   mockDbGet: vi.fn(),
@@ -145,9 +145,16 @@ describe('escapeCmdPath', () => {
 // ========== openInTerminal 编排分发 ==========
 
 describe('openInTerminal 编排分发', () => {
+  let originalPlatform: string
   beforeEach(() => {
     vi.clearAllMocks()
     mockSpawn.mockImplementation(() => ({ pid: 12345, unref: vi.fn(), on: vi.fn() }))
+    // stub 为 darwin：使默认预设确定性走 AppleScript 路径（不 spawn），与宿主 OS 无关
+    originalPlatform = process.platform
+    Object.defineProperty(process, 'platform', { value: 'darwin', configurable: true })
+  })
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true })
   })
 
   it('预设 ghostty → spawn open 并替换 {path}', async () => {
@@ -181,5 +188,7 @@ describe('openInTerminal 编排分发', () => {
     expect(ok).toBe(true)
     expect(mockSpawn).not.toHaveBeenCalled()
     expect(mockExec).toHaveBeenCalled()
+    // execAsync(`osascript -e '${escaped}'`) → exec(cmd, callback)，cmd 内含 folderPath
+    expect(mockExec).toHaveBeenCalledWith(expect.stringContaining('/x'), expect.anything())
   })
 })

From 335b0576a8e5ffc8a38462300dfe9e13fc89d74b Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 16:00:09 +0800
Subject: [PATCH 6/9] =?UTF-8?q?refactor(terminal):=20handleOpenTerminal=20?=
 =?UTF-8?q?=E6=94=B9=E7=94=A8=20terminalLauncher=20=E5=B9=B6=E5=88=A0?=
 =?UTF-8?q?=E9=99=A4=E8=BF=81=E5=87=BA=E4=BB=A3=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/api/renderer/systemCommands.ts | 114 ++----------------------
 1 file changed, 6 insertions(+), 108 deletions(-)

diff --git a/src/main/api/renderer/systemCommands.ts b/src/main/api/renderer/systemCommands.ts
index 608f72d7..5439a760 100644
--- a/src/main/api/renderer/systemCommands.ts
+++ b/src/main/api/renderer/systemCommands.ts
@@ -1,4 +1,4 @@
-import { exec, spawn } from 'child_process'
+import { exec } from 'child_process'
 import os from 'os'
 import type { PluginManager } from '../../managers/pluginManager'
 import { BrowserWindow, clipboard, nativeImage, Notification, shell } from 'electron'
@@ -7,6 +7,7 @@ import { GLOBAL_SCROLLBAR_CSS } from '../../core/globalStyles'
 import { screenCapture } from '../../core/screenCapture'
 import windowManager from '../../managers/windowManager'
 import databaseAPI from '../shared/database'
+import * as terminalLauncher from '../../utils/terminalLauncher'
 import { ColorPicker } from '../../core/native/index.js'
 import { getExplorerFolderPathFromWindow } from '../../utils/common'
 
@@ -39,54 +40,6 @@ export function getWindowsExplorerPath(windowInfo: WindowsWindowInfo): string |
   return getExplorerFolderPathFromWindow(windowInfo, 'SystemCmd')
 }
 
-/**
- * 尝试启动终端（Windows 平台）
- * 回退优先级：Windows Terminal -> PowerShell -> CMD
- */
-/**
- * 安全转义 PowerShell 路径参数
- * 使用单引号包裹，将路径中的单引号替换为两个单引号
- */
-function escapePowerShellPath(folderPath: string): string {
-  const escaped = folderPath.replace(/'/g, "''")
-  return `'${escaped}'`
-}
-
-/**
- * 安全转义 CMD 路径参数
- * 使用双引号包裹，将路径中的双引号转义
- */
-function escapeCmdPath(folderPath: string): string {
-  // CMD 中双引号内的双引号需要用 ^ 转义
-  const escaped = folderPath.replace(/"/g, '^"')
-  return `"${escaped}"`
-}
-
-export async function tryLaunchWindowsTerminal(folderPath: string): Promise<boolean> {
-  const tryLaunch = (cmd: string, args: string[]): Promise<boolean> => {
-    return new Promise<boolean>((resolve) => {
-      const child = spawn(cmd, args, { detached: true, stdio: 'ignore' })
-      child.on('error', () => resolve(false))
-      if (child.pid) {
-        child.unref()
-        resolve(true)
-      }
-    })
-  }
-
-  // Windows Terminal 使用 spawn 参数数组，天然安全
-  // PowerShell 和 CMD 需要转义路径以防止命令注入
-  return (
-    (await tryLaunch('wt.exe', ['-d', folderPath])) ||
-    (await tryLaunch('powershell.exe', [
-      '-NoExit',
-      '-Command',
-      `Set-Location -Path ${escapePowerShellPath(folderPath)}`
-    ])) ||
-    (await tryLaunch('cmd.exe', ['/K', `cd /d ${escapeCmdPath(folderPath)}`]))
-  )
-}
-
 /**
  * 执行系统内置指令
  */
@@ -491,50 +444,6 @@ async function handleCopyPath(
   return { success: false, error: `不支持的平台: ${process.platform}` }
 }
 
-/**
- * 在 macOS 上打开终端并切换到指定目录
- */
-async function openTerminalOnMac(
-  folderPath: string,
-  execAsync: (cmd: string) => Promise<{ stdout: string; stderr: string }>
-): Promise<void> {
-  const script = `
-    tell application "Terminal"
-      activate
-      do script "cd " & quoted form of "${folderPath}"
-    end tell
-  `
-  await execAsync(`osascript -e '${script}'`)
-}
-
-/**
- * 在 Linux 上尝试启动终端并切换到指定目录
- * 回退优先级：exo-open -> gnome-terminal -> xterm
- */
-async function openTerminalOnLinux(folderPath: string): Promise<boolean> {
-  const tryLaunch = (cmd: string, args: string[]): Promise<boolean> => {
-    return new Promise<boolean>((resolve) => {
-      const child = spawn(cmd, args, { detached: true, stdio: 'ignore' })
-      child.on('error', () => resolve(false))
-      if (child.pid) {
-        child.unref()
-        resolve(true)
-      }
-    })
-  }
-
-  return (
-    (await tryLaunch('exo-open', [
-      '--launch',
-      'TerminalEmulator',
-      '--working-directory',
-      folderPath
-    ])) ||
-    (await tryLaunch('gnome-terminal', [`--working-directory=${folderPath}`])) ||
-    (await tryLaunch('xterm', ['-cd', folderPath]))
-  )
-}
-
 /**
  * 从窗口信息获取 macOS 访达当前目录路径
  */
@@ -593,21 +502,10 @@ async function handleOpenTerminal(
       return { success: false, error: '无法确定目标路径' }
     }
 
-    // 根据平台打开终端
-    if (process.platform === 'darwin') {
-      await openTerminalOnMac(targetPath, execAsync)
-    } else if (process.platform === 'linux') {
-      const launched = await openTerminalOnLinux(targetPath)
-      if (!launched) {
-        throw new Error('Could not find a supported terminal emulator')
-      }
-    } else if (process.platform === 'win32') {
-      const launched = await tryLaunchWindowsTerminal(targetPath)
-      if (!launched) {
-        return { success: false, error: '无法启动终端' }
-      }
-    } else {
-      return { success: false, error: `不支持的平台: ${process.platform}` }
+    // 打开终端（统一走 terminalLauncher，按用户配置分发）
+    const launched = await terminalLauncher.openInTerminal(targetPath)
+    if (!launched) {
+      return { success: false, error: '无法启动终端' }
     }
 
     console.log('[SystemCmd] 已在终端打开:', targetPath)

From 170fee90a60fc41002694e823396521e268d3814 Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 16:04:43 +0800
Subject: [PATCH 7/9] =?UTF-8?q?refactor(terminal):=20appleScriptHelper.ope?=
 =?UTF-8?q?nInTerminal=20=E5=A7=94=E6=89=98=20terminalLauncher?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/main/utils/appleScriptHelper.ts | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/src/main/utils/appleScriptHelper.ts b/src/main/utils/appleScriptHelper.ts
index 2a653a92..4079b850 100644
--- a/src/main/utils/appleScriptHelper.ts
+++ b/src/main/utils/appleScriptHelper.ts
@@ -1,5 +1,6 @@
 import { exec } from 'child_process'
 import { promisify } from 'util'
+import * as terminalLauncher from './terminalLauncher'
 
 const execAsync = promisify(exec)
 
@@ -183,16 +184,7 @@ class AppleScriptHelper {
    */
   async openInTerminal(path: string): Promise<boolean> {
     try {
-      // 转义路径中的单引号
-      const escapedPath = path.replace(/'/g, "'\\''")
-      const script = `
-        tell application "Terminal"
-          activate
-          do script "cd '${escapedPath}'"
-        end tell
-      `
-      await this.execute(script)
-      return true
+      return await terminalLauncher.openInTerminal(path)
     } catch (error) {
       console.error('[AppleScript] 在终端打开路径失败:', error)
       return false

From fb07a4cbe2b0c98e0800f04ba539e08a6a86525d Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 16:16:22 +0800
Subject: [PATCH 8/9] =?UTF-8?q?feat(terminal):=20=E9=80=9A=E7=94=A8?=
 =?UTF-8?q?=E8=AE=BE=E7=BD=AE=E9=A1=B5=E6=96=B0=E5=A2=9E=E7=BB=88=E7=AB=AF?=
 =?UTF-8?q?=E9=80=89=E6=8B=A9=E4=B8=8E=E8=87=AA=E5=AE=9A=E4=B9=89=E5=91=BD?=
 =?UTF-8?q?=E4=BB=A4=20UI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 internal-plugins/setting/src/constants.ts     |  3 +
 .../views/GeneralSetting/GeneralSetting.vue   | 75 ++++++++++++++++++-
 2 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/internal-plugins/setting/src/constants.ts b/internal-plugins/setting/src/constants.ts
index 6af30536..24e2fcd0 100644
--- a/internal-plugins/setting/src/constants.ts
+++ b/internal-plugins/setting/src/constants.ts
@@ -21,3 +21,6 @@ export type PrimaryColor = 'blue' | 'purple' | 'green' | 'orange' | 'red' | 'pin
 
 // 超级面板鼠标按键类型
 export type MouseButtonType = 'middle' | 'right' | 'back' | 'forward'
+
+/** 「在终端打开」使用的终端选择：'default' 系统默认 ｜ 'custom' 自定义命令 ｜ 其他预设 id */
+export type TerminalType = 'default' | 'custom' | string
diff --git a/internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue b/internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue
index cd3bbf06..e6c8d175 100644
--- a/internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue
+++ b/internal-plugins/setting/src/views/GeneralSetting/GeneralSetting.vue
@@ -9,6 +9,7 @@ import {
   type AutoPasteOption,
   type MouseButtonType,
   type PrimaryColor,
+  type TerminalType,
   type ThemeType
 } from '@/constants'
 import { Dropdown, HotkeyInput, Slider, useToast } from '@/components'
@@ -101,6 +102,38 @@ const superPanelMouseButtonOptions = [
 // 当前平台（与 window.ztools.getPlatform 返回类型保持一致）
 const platform = ref<'darwin' | 'win32' | 'linux'>('darwin')
 
+// 终端打开设置
+const terminal = ref<TerminalType>('default')
+const terminalCustomCommand = ref('')
+
+// 终端预设选项（按平台；仅 UI 标签，启动逻辑在主进程 terminalLauncher）
+const terminalOptions = computed(() => {
+  if (platform.value === 'win32') {
+    return [
+      { label: '系统默认', value: 'default' },
+      { label: 'Windows Terminal', value: 'wt' },
+      { label: 'PowerShell', value: 'powershell' },
+      { label: 'CMD', value: 'cmd' },
+      { label: '自定义', value: 'custom' }
+    ]
+  }
+  if (platform.value === 'linux') {
+    return [
+      { label: '系统默认', value: 'default' },
+      { label: 'GNOME Terminal', value: 'gnome-terminal' },
+      { label: 'Konsole', value: 'konsole' },
+      { label: 'XTerm', value: 'xterm' },
+      { label: '自定义', value: 'custom' }
+    ]
+  }
+  return [
+    { label: '系统默认 (Terminal)', value: 'default' },
+    { label: 'Ghostty', value: 'ghostty' },
+    { label: 'iTerm2', value: 'iterm2' },
+    { label: '自定义', value: 'custom' }
+  ]
+})
+
 // 默认快捷键（根据平台区分文案）
 const defaultHotkey = computed(() => {
   return platform.value === 'win32' ? 'Alt+Z' : 'Option+Z'
@@ -1224,6 +1257,10 @@ async function loadSettings(): Promise<void> {
       floatingBallEnabled.value = data.floatingBallEnabled ?? false
       floatingBallLetter.value = data.floatingBallLetter || 'Z'
 
+      // 终端打开配置
+      terminal.value = data.terminal ?? 'default'
+      terminalCustomCommand.value = data.terminalCustomCommand ?? ''
+
       // 加载自定义颜色
       if (data.customColor) {
         customColor.value = data.customColor
@@ -1298,7 +1335,9 @@ async function saveSettings(): Promise<void> {
       pluginMarketCustom: pluginMarketCustom.value,
       pluginMarketUrl: pluginMarketUrl.value,
       autoCheckUpdate: autoCheckUpdate.value,
-      clipboardRetentionDays: clipboardRetentionDays.value
+      clipboardRetentionDays: clipboardRetentionDays.value,
+      terminal: terminal.value,
+      terminalCustomCommand: terminalCustomCommand.value
     })
   } catch (error) {
     console.error('保存设置失败:', error)
@@ -1537,6 +1576,40 @@ onUnmounted(() => {
       </div>
     </div>
 
+    <!-- ==================== 终端打开 ==================== -->
+    <div class="setting-group">
+      <h3 class="setting-group-title">终端打开</h3>
+
+      <div class="setting-item">
+        <div class="setting-label">
+          <span>打开终端应用</span>
+          <span class="setting-desc">从 Finder 唤出「在终端打开」时使用的终端</span>
+        </div>
+        <div class="setting-control">
+          <Dropdown v-model="terminal" :options="terminalOptions" @change="saveSettings" />
+        </div>
+      </div>
+
+      <div v-if="terminal === 'custom'" class="setting-item">
+        <div class="setting-label">
+          <span>自定义命令</span>
+          <span class="setting-desc"
+            >用 {path} 代表目标目录，如 ghostty --working-directory={path}</span
+          >
+        </div>
+        <div class="setting-control">
+          <input
+            v-model="terminalCustomCommand"
+            type="text"
+            class="input"
+            placeholder="alacritty --working-directory={path}"
+            @blur="saveSettings"
+            @keyup.enter="saveSettings"
+          />
+        </div>
+      </div>
+    </div>
+
     <!-- ==================== 搜索 ==================== -->
     <div class="setting-group">
       <h3 class="setting-group-title">搜索</h3>

From 9c3453cdaf1706483a41e8b86b27e11883ef8c11 Mon Sep 17 00:00:00 2001
From: thirking <xinhua_huang@roboticplus.com>
Date: Thu, 2 Jul 2026 18:48:30 +0800
Subject: [PATCH 9/9] =?UTF-8?q?fix(terminal):=20=E6=8C=89=20PR=20=E8=AF=84?=
 =?UTF-8?q?=E5=AE=A1=E4=BF=AE=E5=A4=8D=E5=AE=89=E5=85=A8=E4=B8=8E=E7=B1=BB?=
 =?UTF-8?q?=E5=9E=8B=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- runAppleScript 改用 execFileAsync 直调 osascript，不经 shell，杜绝 shell 注入
- Terminal/iTerm2 预设路径经 escapeAppleScriptString 转义反斜杠与双引号，防 AppleScript 注入
- openInTerminal 内 return 改为 await，使 reject 能被 try/catch 捕获返回 false
- parseCommandString 返回类型改为 [string | undefined, string[]] 修正类型安全
- 测试 mock 改 execFile 并断言 osascript 调用，新增 escapeAppleScriptString 测试
---
 src/main/utils/terminalLauncher.ts  | 36 ++++++++++++++++++-----------
 tests/main/terminalLauncher.test.ts | 28 ++++++++++++++++------
 2 files changed, 44 insertions(+), 20 deletions(-)

diff --git a/src/main/utils/terminalLauncher.ts b/src/main/utils/terminalLauncher.ts
index 69035d76..a6c15a61 100644
--- a/src/main/utils/terminalLauncher.ts
+++ b/src/main/utils/terminalLauncher.ts
@@ -1,8 +1,8 @@
-import { exec, spawn } from 'child_process'
+import { spawn, execFile } from 'child_process'
 import { promisify } from 'util'
 import databaseAPI from '../api/shared/database'
 
-const execAsync = promisify(exec)
+const execFileAsync = promisify(execFile)
 
 // ==================== 类型 ====================
 
@@ -36,10 +36,15 @@ export function escapeCmdPath(folderPath: string): string {
   return `"${escaped}"`
 }
 
+/** 转义路径中的反斜杠和双引号，安全嵌入 AppleScript 双引号字符串 */
+export function escapeAppleScriptString(s: string): string {
+  return s.replaceAll('\\', '\\\\').replaceAll('"', '\\"')
+}
+
 // ==================== 命令字符串解析（内联，避免耦合 commandLauncher）====================
 
 /** 将命令字符串拆分为 [可执行文件, 参数列表]，处理引号 */
-function parseCommandString(cmd: string): [string, string[]] {
+function parseCommandString(cmd: string): [string | undefined, string[]] {
   const parts: string[] = []
   let current = ''
   let inQuote: string | null = null
@@ -68,10 +73,9 @@ function parseCommandString(cmd: string): [string, string[]] {
 
 // ==================== 执行原语 ====================
 
-/** 执行 AppleScript（转义单引号，防止 shell 注入） */
+/** 执行 AppleScript：直接调用 osascript（不经 shell），避免 shell 注入 */
 async function runAppleScript(script: string): Promise<void> {
-  const escaped = script.replace(/'/g, "'\\''")
-  await execAsync(`osascript -e '${escaped}'`)
+  await execFileAsync('osascript', ['-e', script])
 }
 
 /** detached 启动 CLI 命令，返回是否成功拿到 pid */
@@ -118,12 +122,15 @@ const MAC_PRESETS: PresetEntry[] = [
     label: '系统默认 (Terminal)',
     preset: {
       type: 'applescript',
-      build: (p) => `
+      build: (p) => {
+        const safePath = escapeAppleScriptString(p)
+        return `
     tell application "Terminal"
       activate
-      do script "cd " & quoted form of "${p}"
+      do script "cd " & quoted form of "${safePath}"
     end tell
   `
+      }
     }
   },
   {
@@ -140,14 +147,17 @@ const MAC_PRESETS: PresetEntry[] = [
     label: 'iTerm2',
     preset: {
       type: 'applescript',
-      build: (p) => `
+      build: (p) => {
+        const safePath = escapeAppleScriptString(p)
+        return `
     tell application "iTerm"
       activate
       tell (create window with default profile)
-        write session "cd " & quoted form of "${p}"
+        write session "cd " & quoted form of "${safePath}"
       end tell
     end tell
   `
+      }
     }
   }
 ]
@@ -268,13 +278,13 @@ export async function openInTerminal(folderPath: string): Promise<boolean> {
     if (terminal === 'custom') {
       const parsed = parseCustomCommand(customCommand ?? '')
       if (parsed) {
-        return runCli(parsed.command, applyPathToArgs(parsed.args, folderPath))
+        return await runCli(parsed.command, applyPathToArgs(parsed.args, folderPath))
       }
       // 自定义命令为空 → 回退默认
-      return executePreset(resolvePreset('default', process.platform), folderPath)
+      return await executePreset(resolvePreset('default', process.platform), folderPath)
     }
 
-    return executePreset(resolvePreset(terminal, process.platform), folderPath)
+    return await executePreset(resolvePreset(terminal, process.platform), folderPath)
   } catch (error) {
     console.error('[TerminalLauncher] 打开终端失败:', error)
     return false
diff --git a/tests/main/terminalLauncher.test.ts b/tests/main/terminalLauncher.test.ts
index c46d7f7d..a283748a 100644
--- a/tests/main/terminalLauncher.test.ts
+++ b/tests/main/terminalLauncher.test.ts
@@ -1,15 +1,15 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 
-const { mockDbGet, mockSpawn, mockExec } = vi.hoisted(() => ({
+const { mockDbGet, mockSpawn, mockExecFile } = vi.hoisted(() => ({
   mockDbGet: vi.fn(),
   mockSpawn: vi.fn(),
-  mockExec: vi.fn((...args: unknown[]) => {
+  mockExecFile: vi.fn((...args: unknown[]) => {
     const cb = args[args.length - 1]
     if (typeof cb === 'function') cb(null, { stdout: '', stderr: '' })
   })
 }))
 
-vi.mock('child_process', () => ({ spawn: mockSpawn, exec: mockExec }))
+vi.mock('child_process', () => ({ spawn: mockSpawn, execFile: mockExecFile }))
 vi.mock('../../src/main/api/shared/database', () => ({
   default: { dbGet: mockDbGet, dbPut: vi.fn() }
 }))
@@ -21,7 +21,8 @@ import {
   parseCustomCommand,
   openInTerminal,
   escapePowerShellPath,
-  escapeCmdPath
+  escapeCmdPath,
+  escapeAppleScriptString
 } from '../../src/main/utils/terminalLauncher'
 
 // ========== getPresetOptions ==========
@@ -142,6 +143,15 @@ describe('escapeCmdPath', () => {
   })
 })
 
+describe('escapeAppleScriptString', () => {
+  it('转义反斜杠和双引号', () => {
+    expect(escapeAppleScriptString('a"b\\c')).toBe('a\\"b\\\\c')
+  })
+  it('无特殊字符保持不变', () => {
+    expect(escapeAppleScriptString('/Users/x')).toBe('/Users/x')
+  })
+})
+
 // ========== openInTerminal 编排分发 ==========
 
 describe('openInTerminal 编排分发', () => {
@@ -187,8 +197,12 @@ describe('openInTerminal 编排分发', () => {
     const ok = await openInTerminal('/x')
     expect(ok).toBe(true)
     expect(mockSpawn).not.toHaveBeenCalled()
-    expect(mockExec).toHaveBeenCalled()
-    // execAsync(`osascript -e '${escaped}'`) → exec(cmd, callback)，cmd 内含 folderPath
-    expect(mockExec).toHaveBeenCalledWith(expect.stringContaining('/x'), expect.anything())
+    expect(mockExecFile).toHaveBeenCalled()
+    // execFileAsync('osascript', ['-e', script]) → execFile(cmd, args, callback)
+    expect(mockExecFile).toHaveBeenCalledWith(
+      'osascript',
+      expect.arrayContaining([expect.stringContaining('/x')]),
+      expect.anything()
+    )
   })
 })