光谱AI 操作手册

SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 2 章

本章讲清楚 SpectrAI 的主界面布局、项目目录与工作区的组织方式，以及 Git 与 Worktree 隔离的用户侧操作。SpectrAI 用项目目录承载代码与会话，用「工作格」把主区拆成可并排的标签视角，用 Git Worktree 把 AI 改动隔离到独立分支目录，避免多个任务互相污染。

#2.1 概述

一个「项目」通常就是一个本地目录：里面有代码、Git 仓库、会话历史引用和本地配置。新建会话时把目录绑定到会话，文件树、Git 面板、终端都围绕它工作。多仓库项目可以在「工作区（Workspace）」里把若干 Git 仓库组合成一个命名集合，适合前端、后端、API、文档分仓的场景。

主界面从左到右分三层：最左是活动栏（一级工作区入口），中间是可分屏的主区（工作格），会话、文件、终端、浏览器、资料库等都以标签视角开在这里。

#2.2 核心概念

• 项目 / 工作区（Workspace）：最常见形态是一个工作目录；「工作区」则是一组命名的 Git 仓库集合。
• 工作目录：新建会话时绑定的目录。会话、文件树、Git 面板都基于它工作。
• 工作格：主区的分屏容器。左侧入口以标签视角打开到主区，标签可拖拽分屏并排、换格、拖出成独立窗口。
• 视角（Surface）：会话、终端、浏览器、资料库、文件等都能作为一个「视角」标签开在工作格里。
• 目录权限：会话对文件系统的可操作范围，分三档（项目目录 / 用户目录 / 完全访问）。
• Worktree 隔离：SpectrAI 调用 Git worktree 创建独立目录和分支，AI 在隔离目录改代码，主仓库保持干净。

#2.3 主区工作格与视角

⚠️ 注意

工作格（新分屏布局）自 v1.0.1 转正并默认开启。如需退回旧版「整屏切换工作区」，在 设置 → 常规 → 外观 → 新的分屏布局 关闭开关（该设置项请参见 第 9 章 设置与快捷键）。

主区顶部有统一的标签条，每个标签是一个视角（一个会话、终端、浏览器页、资料库文档等）。可用操作：

• 拖拽标签分屏：把标签拖到主区边缘，主区分成两格并排显示；分屏比例会被记住，也支持垂直分屏。
• 换格 / 拖入主区：把左侧活动栏入口拖入主区，即以视角形式打开；拖到栏外空白处则弹出为独立窗口。
• 在独立窗口打开：右键会话或标签，选择 在独立窗口打开，把它分离成一个独立窗口（微信风格独立会话聊天窗）。
• Tab 面板收起 / 展开：标签过多时可抽屉式折叠 Tab 面板，展开后恢复折叠前的尺寸。
• 未绑定格空状态：没有绑定会话的分屏格显示空状态，不再跟随全局选中的会话变动。

#2.4 一级工作区入口（活动栏）

最左侧活动栏是一级入口，默认只钉「会话 / 终端」，其余收进底部 更多 菜单。可用操作：

1. 点击入口图标切换到对应工作区，或（在项目工作区内）以视角打开到工作格。
2. 在 更多 面板点入口右侧的图钉 固定到侧栏，或选 全部固定到侧栏。
3. 右键栏上入口选 从侧栏收起；拖拽可调整顺序。
4. 选 恢复默认（会话 / 终端） 回到默认钉选。

常用入口对应的中文标签：项目会话（会话列表 / 文件目录 / Git 视图）、资料库、任务看板、Agent Teams、专家、工作流、定时任务、小黑、终端、浏览器、设置。其中专家、工作流、任务看板等按套餐门控，锁定时图标带锁标。

💡 提示

任务看板（Project Board）承载任务执行编排、执行面板与 worktree review / merge，属于任务执行闭环，详见 第 13 章 工作流、原型与定时任务。

资料库

资料库提供本地「通用库 / 项目库」，可作为主区视角打开，用于浏览与编辑文档；库目录也能被外部工具打开。用户侧在这里管理文档条目；AI 侧的只读检索工具见 第 5 章 工具与 MCP。入口：活动栏 更多 → 资料库，或直接钉到侧栏。

#2.5 内置浏览器

软件内点击的网页链接默认在内置浏览器打开。入口：活动栏 更多 → 浏览器，或命令面板搜索「浏览器」；在项目工作区内会作为视角开进工作格。特性：

• 按站点记忆缩放：每个站点的网页缩放比例单独记住，下次访问自动恢复。
• 标签横向滚动：标签过多时标签条可横向滚动。
• 标签右键菜单：新建 / 刷新 / 复制标签 / 关闭 / 关闭其他 / 关闭右侧 / 重新打开关闭的标签 / 关闭窗口。
• 多会话隔离（可选）：默认所有标签共享登录态；开启会话隔离后，AI 会话打开的标签使用独立 cookie / 存储分区（该会话需单独登录）。

浏览器相关开关（打开方式、CDP 通道、会话隔离）在 设置 → 内置浏览器，详见 第 9 章 设置与快捷键。

#2.6 新建会话与选择目录

当前版本没有独立的「打开项目」向导，项目在「新建会话」时绑定。本节侧重项目与目录选择；会话模式（Normal / Supervisor / Mission）的区别见 第 3 章 AI 会话基础。

入口：左侧会话区点击 新建会话，或按 Ctrl/Cmd+N。新建会话也可从主区标签条里挂起的「新会话」tab 进入。

1. 在 工作配置 栏填写会话名称。
2. 选择工作目录：默认为 目录 模式；有命名工作区时可切到 工作区 模式选择仓库集合。
   • 点右侧文件夹图标浏览选择本地目录，或直接粘贴路径。
   • 顶部的 临时会话 选项不绑定项目、按会话分配独立子目录，适合临时提问。
3. 从 常用目录 快速选择：点目录卡片即填入；点右上 添加 选目录并收藏；悬停卡片可点星标 收藏 / 取消收藏 或点 × 移除；点 展开更多 显示未收藏目录。
4. 设置 目录权限：右上三档 chip 切换 项目目录 / 用户目录 / 完全访问，改完即落为下次新建默认（不点创建也不会丢）。
5. 按需打开 Worktree 隔离 开关（全局已开启时显示「全局默认开启」）。
6. 在 AI 配置 栏按分类（全部 / 内置 CLI / API 中转 / 自定义）选择 Provider，必要时点 管理提供者 跳转设置。
7. 点 立即创建。

⚠️ 注意

目录权限默认档为 用户目录（扩展），允许在用户主目录内操作；项目目录 最严格（仅当前项目 / 工作区），完全访问 可超出工作区（仍保护系统目录，有风险）。

💡 提示

会话创建后仍可在会话顶部工具栏切换目录权限，无需重启会话；「完整配置…」弹窗里的修改同样会落为下次新建默认。

#2.7 会话列表与项目分组

左侧会话区列出全部会话，支持紧凑密度与按最近活跃时间排序。可用能力：

• 搜索会话：顶部搜索框按会话名、路径或内容检索。
• 项目分组：按目录或工作区分组；在分组卡片上点 在该项目快速新建会话 一键新建；点 切换到该项目的会话 聚焦该项目。
• 待你处理提示：需要你回答 / 审批 / 确认的会话会显示分级提示徽标（如「待回答 N」）。
• 多会话工作集（workset）：右键会话选 固定到工作集 打上标签，便于成批聚焦。
• 收藏置顶：右键会话相关入口置顶重要会话。
• 批量删除与撤销：点 批量选择 进入多选，可全选可见（自动排除运行中）、按状态选、反选，然后 删除选中；删除后短时间内可撤销恢复。
• 监控关系：会话可展示监控绑定，支持用当前会话 监控此会话 并订阅其正文。

• 右键菜单：在会话上右键可 在副栏打开 / 在独立窗口打开、重命名 / AI 重命名、移到 / 移出工作区、复制会话名称 / 复制工作目录、分享会话、在终端 / 文件管理器中打开、恢复 / 终止会话 等。

#2.8 导入或克隆 Git 仓库

当前桌面端未内置 git clone 入口。请先用系统终端、GitHub Desktop、VS Code 等把仓库克隆到本地，再在 SpectrAI 中选择该目录。

已有本地多仓库项目时，进入 设置 → 工作区，点击 新建工作区，弹窗支持三种方式：

1. 手动添加：点 添加仓库，逐个选择仓库目录，可点星标设为「主仓库」。
2. 扫描目录：选择父目录，点 扫描，勾选发现的 Git 仓库，再点导入。
3. 导入 VS Code：填写 .code-workspace 文件路径，点 解析 后导入选中仓库。

#2.9 启用 Worktree 隔离

全局开关

入口：设置 → 常规 → 基本 → Git Worktree 隔离。打开后新建任务默认在独立分支目录工作。

新建会话时单独选择

入口：新建会话 → Worktree 隔离 开关。打开后此会话继承隔离策略；全局已打开时显示「全局默认开启」。

生命周期

1. 创建任务或会话并开启 Worktree 隔离。
2. 对任务看板任务或子 Agent，SpectrAI 会创建 .spectrai-worktrees/<任务ID>/；普通会话则在 AI 判断需要改代码时进入 Worktree。
3. 分支通常命名为 worktree/<任务ID>，.spectrai-worktrees/ 会自动加入 .gitignore。
4. 在 项目 → Git 分支 → Worktree 展开分支，查看「Worktree 当前改动（Live）」与文件差异。
5. 合并时，可直接让当前会话检查冲突、squash 合并到主分支并清理目录；AI 会用内置工具执行检查、合并和可选清理。
6. 也可手动执行 git merge / git worktree remove / git branch -D，合并前先检查差异。

⚠️ 注意

SpectrAI 每次启动时会兜底清理平台创建的 Worktree：分支已合并的直接回收；未合并但超过 14 天没有新提交的分支，会先打包归档到数据目录的 worktree-archive 再删除。仍需保留的改动请及时合并或手动备份。

#2.10 Git 集成

入口：切到 项目 工作区，选择 Git 分支 Tab。可用能力：

• 查看当前仓库、当前分支、同步状态（已同步 / 未推送 / 落后）。
• 点 Pull / Push 与远端同步。
• 在 变动 Tab 查看已暂存 / 未暂存 / 未跟踪；对文件点 差异，或右键 查看差异、暂存、取消暂存、还原文件。
• 输入提交信息，按 Ctrl+Enter 或点 提交 提交已暂存文件。
• 在 历史 Tab 展开提交查看涉及文件和 diff，可点 发给 AI 分析。
• 在 Worktree Tab 查看隔离分支、关联会话和差异文件。

需要切换主仓库分支时，请使用内置终端或系统 Git 工具。

#2.11 关闭项目或会话

SpectrAI 没有独立的「关闭项目」按钮，也没有项目级「保存 / 不保存」对话框；文件是否保存由文件编辑器处理，详见 第 6 章 终端与文件。

• 关闭运行中的会话：选中会话后按 Ctrl+W，确认关闭；提示会说明正在运行的任务将被终止。
• 删除会话：会话列表右键相关入口删除，或批量删除；短时间内可撤销恢复。同时清理 Worktree 时，Worktree 目录和分支不可恢复。
• 从常用目录移除项目：新建会话 → 常用目录，悬停卡片点 × 移除。

#2.12 详细配置

#2.13 高级用法

• 多项目并行：可同时保留多个不同目录的会话，也可创建多仓库工作区；主区一次聚焦一个项目视图，通过会话分组、工作格分屏或命令面板切换。
• 视角并排对照：把一个会话开在主区、另一个开在副栏，或把终端 / 浏览器视角拖到分屏格里，边看代码边跑命令。
• Worktree 与远端分支：Worktree 分支默认是本地分支。需要推送时在 Git 面板点 Push，或命令行设置 upstream。
• 两种合并方式：其一，让 AI 检查并 squash 合并 Worktree；其二，在终端手动 git checkout main、git merge --squash worktree/xxx、git commit，确认后再 git worktree remove 清理目录。

#2.14 常见问题

Worktree 合并冲突怎么办

先不要清理目录。在 Git 面板查看 Worktree 差异，或让 AI「只检查冲突并列出文件」。确认后按 Git 的冲突标记解决，再重新合并。

.spectrai-worktrees/ 占磁盘怎么办

会话结束后平台会自动清理其创建的 Worktree。已合并且不再需要的分支，可让 AI 清理或手动 git worktree remove <path>。任务看板创建的 Worktree 在删除任务时会尝试清理对应目录和分支。

内置浏览器打开的网页登录态混乱怎么办

默认所有标签共享登录态。如果希望某些 AI 会话彼此隔离，去 设置 → 内置浏览器 打开「会话隔离浏览器上下文」，代价是该会话的标签需要单独登录。

文件变化监听卡顿怎么办

优先把大型生成目录（如 node_modules、dist、build、.next）加入 .gitignore 或避免在文件树中展开。文件搜索已跳过多类大目录，但文件树仍会列出当前目录内容。

#2.15 相关章节

• 第 3 章 AI 会话基础 — 会话模式与新建会话的模式选择
• 第 6 章 终端与文件 — 文件树、Diff、搜索与替换、内置浏览器视角
• 第 9 章 设置与快捷键 — autoWorktree、分屏布局、内置浏览器、图标主题等设置项
• 第 13 章 工作流、原型与定时任务 — 任务看板与任务执行闭环