使用指南

1 创建工作区

启动应用后，首次使用需要创建或导入工作区：

• 新建工作区：选择一个空目录，应用会自动初始化
• 导入现有项目：选择包含 Git 项目的目录

2 添加项目

在工作区中添加 Git 项目，支持三种方式：

3 创建 Worktree

点击侧边栏的 + 按钮，按照向导创建：

1. 输入分支名称（如 feature/login）
2. 选择基于哪个分支创建（默认 main）
3. 选择要包含的项目
4. 配置需要链接的文件夹（如 node_modules）
5. 点击"创建"，等待完成

4 开始开发

在 Worktree 列表中：

• 点击打开 IDE：用 VS Code / Cursor / IDEA 打开
• 点击终端：在内置终端中运行命令
• 点击文件夹图标：在文件管理器中打开

多窗口工作模式

每个 Workspace 可以在独立的窗口中打开，让你同时操作多个工作区，互不干扰。

• 在侧边栏的 Workspace 列表中，点击 Workspace 名称旁边的外部链接图标（↗️），即可在新窗口中打开该工作区
• 每个窗口独立运行，可以同时查看和操作不同的 Workspace
• 主窗口关闭时，子窗口也会随之关闭

窗口标题

窗口标题会动态显示当前的工作区和分支信息，格式为：

这样在多窗口场景下，你可以通过窗口标题快速区分不同的工作区。

Worktree 锁定机制

当一个 Worktree 已经在某个窗口中打开时，在其他窗口中该 Worktree 会显示为"已占用"状态。

• 已占用的 Worktree 不能在另一个窗口中同时操作，避免冲突
• 切换到其他 Worktree 时，当前 Worktree 的锁会自动释放
• 关闭窗口时，该窗口持有的所有锁也会自动释放

内置终端

每个 Worktree 都有独立的内置终端，工作目录自动设置为 Worktree 的根目录。无需手动 cd 到对应路径。

• 终端面板位于应用底部，可以通过拖拽调整高度
• 切换 Worktree 时，终端会自动切换到对应的会话
• 终端会话在 Worktree 生命周期内保持，不会因为切换而丢失

多标签页

每个 Worktree 可以拥有多个终端标签页：

• 点击终端面板的 + 按钮创建新的终端标签页
• 点击标签页切换不同的终端会话
• 点击标签页上的 x 按钮关闭终端
• 每个标签页都是独立的终端进程

全屏模式

终端支持全屏模式，适合需要更大终端空间的场景：

• 点击终端面板右上角的最大化图标进入全屏模式
• 按 Escape 键退出全屏模式
• 全屏模式下终端会占满整个应用窗口

外部终端

如果你更习惯使用系统自带的终端应用，可以点击终端面板的"在外部终端中打开"按钮，它会自动打开系统默认终端并切换到 Worktree 目录。

功能说明

语音输入功能基于阿里云 Dashscope Paraformer 实时语音识别，允许你对着麦克风说话，语音实时转写为文字并注入到当前终端中。适合双手不方便打字或需要快速输入命令的场景。

支持两种操作方式：

• 按住说话：按住 Alt+V 说话，松开即停止录音并转写
• 点击切换：点击终端面板的麦克风图标进入待命状态，之后按住 Alt+V 说话

配置 Dashscope

使用语音输入前，需要先配置 Dashscope API Key：

1. 打开设置页面（齿轮图标）
2. 滚动到"语音识别 (Dashscope)"区域
3. 前往 Dashscope 控制台 获取 API Key
4. 将 API Key 粘贴到输入框中，点击"保存"
5. 点击"测试连接"按钮验证配置是否正确

麦克风设置

在设置页的语音识别区域，可以管理麦克风设备：

• 选择麦克风：下拉框列出所有可用的音频输入设备，可选择特定麦克风（如外接麦克风、耳机麦克风等），默认使用系统默认设备
• 麦克风测试：点击"测试"按钮，会显示实时音量条，对着麦克风说话可确认设备是否正常工作。测试 10 秒后自动停止
• 连接测试：点击"测试连接"按钮，验证 API Key 和 WebSocket 地址是否配置正确，成功时显示绿色"连接成功"提示

使用流程

1. 点击终端面板右上角的麦克风图标，进入待命状态（图标变为蓝色，麦克风已打开）
2. 按住 Alt+V 开始说话，此时连接 Dashscope 并实时发送音频
3. 松开 Alt+V，停止录音，识别结果自动输入到终端
4. 可以反复按住/松开进行多次语音输入，麦克风始终保持待命
5. 再次点击麦克风图标，退出待命状态并释放麦克风

语音命令

除了普通文字转写外，还支持以下语音命令关键词，说出即可触发对应终端操作：

例如：按住 Alt+V 说 git status，松开后再按住说 回车，等同于在终端中输入 git status 并按回车执行。

AI 语音精炼

语音转写的结果往往包含口语化的填充词（"嗯"、"那个"、"就是说"等）和语法错误。AI 语音精炼功能集成了 Qwen 大语言模型，自动优化转写文本：

• 去除填充词：自动识别并移除"嗯"、"啊"、"那个"等无意义词汇
• 语法修正：修正口语化表达为规范的命令格式
• 语义保持：优化过程保持原始意图不变，不会改变命令含义

移动端语音输入

在浏览器远程模式下（手机/平板访问），终端面板提供专门的按住说话按钮：

• 长按说话：在终端底部长按麦克风按钮开始录音，松开即停止
• 触屏优化：按钮尺寸和交互针对触摸屏优化，单手即可操作
• 同样支持 AI 精炼：移动端的语音输入同样经过 AI 精炼处理

支持的 IDE

Worktree Manager 支持多种主流 IDE 和编辑器：

切换默认 IDE

在 Worktree 详情页中，点击 IDE 按钮旁边的下拉箭头，即可看到 IDE 选择列表：

• 选择一个 IDE 后，它会成为当前项目的默认 IDE
• 下次点击 IDE 按钮时，会直接使用上次选择的 IDE 打开
• 不同项目可以设置不同的默认 IDE

快速打开

在 IDE 下拉菜单中，每个 IDE 选项右侧都有一个快速打开图标（↗️）：

• 点击图标可以直接用该 IDE 打开项目，而不会改变默认 IDE 设置
• 适合偶尔用其他 IDE 打开的场景

在文件夹中打开

IDE 下拉菜单底部还有"在文件夹中打开"选项，点击后会在系统文件管理器（Finder / 文件资源管理器）中打开 Worktree 的项目目录。

功能说明

智能文件夹扫描可以自动检测项目中适合被链接的大文件夹，帮助你快速配置 linked_folders。

链接这些文件夹后，新创建的 Worktree 会自动从主仓库创建软链接，无需重复安装依赖或重新构建，节省大量磁盘空间和时间。

如何使用

1. 进入工作区设置页面
2. 找到项目的 Linked Folders 配置项
3. 点击扫描按钮（放大镜图标）
4. 系统会自动扫描项目目录，列出所有可链接的文件夹
5. 勾选你需要链接的文件夹，点击确认

自动检测的文件夹类型

扫描功能会自动识别以下常见的大文件夹：

功能概述

远程分享功能允许你将当前工作区通过浏览器分享给同事，对方无需安装任何软件，只需打开链接即可查看你的 Worktree、使用终端，甚至进行协作开发。

分享功能支持三种模式：局域网直连（同一 Wi-Fi / 内网）、WMS 内置隧道（无需安装额外工具）和ngrok 穿透（使用 ngrok 服务）。

开启分享

在桌面端应用中，按照以下步骤开启分享：

1. 在侧边栏底部找到"分享"按钮，点击打开分享面板
2. 设置端口号（默认推荐 49152-65535 范围，也支持 3000-9999 开发端口）
3. 设置访问密码（必填，用于保护你的工作区）
4. 点击"开启分享"，系统会启动一个内置 HTTP 服务器
5. 分享成功后会显示一个局域网访问地址（如 http://192.168.1.100:49152）

浏览器模式访问

协作者打开分享链接后：

1. 浏览器会显示一个密码输入页面，输入你设置的密码即可进入
2. 进入后看到与桌面端相同的界面，包括 Worktree 列表、分支状态等
3. 可以使用内置终端（通过 WebSocket 实时传输）
4. 可以加入协作，与桌面端用户共享终端会话
5. 所有操作通过 WebSocket 实时同步，延迟极低

ngrok 外网穿透

如果协作者不在同一局域网，可以使用 ngrok 进行外网穿透，通过公网 URL 访问：

第一步：安装 ngrok 并获取 Token

1. 前往 ngrok.com 注册账号（免费）
2. 在 ngrok Dashboard 复制你的 Authtoken

第二步：在应用中配置 Token

1. 打开设置页面（齿轮图标）
2. 滚动到底部找到 "外网分享 (ngrok)" 区域
3. 将 Authtoken 粘贴到输入框中，点击"保存"

第三步：启用外网隧道

1. 先按上述步骤开启局域网分享
2. 在分享面板中点击"开启外网"按钮
3. 等待 ngrok 隧道建立成功（通常几秒内完成）
4. 生成的公网地址（如 https://xxxx.ngrok-free.app）即可分享给任何人

WMS 内置隧道

除了 ngrok，Worktree Manager 还内置了 WMS 隧道服务，无需安装任何额外工具即可实现公网访问：

1. 先按上述步骤开启局域网分享
2. 在分享面板中点击"WMS 隧道"按钮
3. 系统会自动连接 tunnel.kirov-opensource.com 并分配唯一子域名
4. 生成的公网地址（如 https://your-name.tunnel.kirov-opensource.com）即可分享给任何人

QR 码分享

开启分享后，分享面板会自动生成当前分享地址的二维码：

• 扫码访问：用手机/平板扫描二维码，直接在移动浏览器中打开工作区
• 密码内嵌：二维码链接中可以内嵌访问密码（通过 URL fragment），扫码后自动完成认证，无需手动输入密码
• 多种模式：局域网、WMS 隧道和 ngrok 三种模式均支持 QR 码

客户端管理

在分享面板中可以实时查看和管理所有连接的客户端：

• 连接列表：显示所有已连接的浏览器客户端，包括 IP 地址、连接时间等信息
• 踢出会话：可以单独踢出指定的客户端会话，被踢出的用户需要重新输入密码
• 密码更新：修改密码后，所有已连接的客户端会被自动踢出

安全注意事项

分享问题排查

# 查看端口占用情况（macOS/Linux）
lsof -i :49152

全局配置

位置：~/.config/worktree-manager/global.json

{
  "workspaces": [
    { "name": "我的项目", "path": "/path/to/workspace" }
  ],
  "current_workspace": "/path/to/workspace",
  "ngrok_token": "2abc...xyz",
  "last_share_port": 49152
}

工作区配置

位置：{workspace}/.worktree-manager.json

{
  "name": "我的项目",
  "worktrees_dir": "worktrees",
  "linked_workspace_items": [".claude", "CLAUDE.md"],
  "projects": [
    {
      "name": "frontend",
      "base_branch": "main",
      "test_branch": "test",
      "merge_strategy": "merge",
      "linked_folders": ["node_modules", ".next"]
    }
  ]
}