SpectrAI User Manual

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

#概述

会话（Session）是 SpectrAI 的核心交互单元，每个会话对应一个独立的 AI 上下文，持久化存储在本地 SQLite 数据库中。每次对话、每条工具调用记录都附属于一个会话，关闭应用后重新打开仍可继续。会话运行时可以随时切换 Provider、切换模型与推理强度、开关 Plan 模式，普通与 Supervisor 模式之间也能就地切换，让用户完全掌控 AI 的工作方式与执行范围。本章面向所有使用 SpectrAI 对话的用户，讲清一个会话从新建、发送消息到管理上下文的完整链路。

#核心概念

会话（Session）：用户与 AI 的单次对话上下文，包含所有消息和工具调用记录，持久化到本地 SQLite，可随时恢复。

模式（Mode）：决定会话行为的配置维度。源码共有 5 种：Normal（通用）/ Supervisor / Mission（组队任务）/ Prototype（原型设计）/ 工作流构建器。前三种在会话底栏的「模式」chip 中呈现，普通会话与 Supervisor 之间可就地切换（重启会话后完全生效）；原型设计与工作流构建器是独立工作区入口，不在会话内切换。各模式的套餐门槛与能力差异详见第 11 章 套餐与模式。

Provider：底层 AI 引擎，如 Claude Code、Codex CLI 等；切换时自动生成上下文摘要弥合格式差异（详见第 8 章 Provider 与 API）。

上下文（Context）：会话累积的对话历史，占用模型上下文窗口；输入框旁的光环按钮实时展示用量，支持手动压缩释放空间。

Plan 模式：会话级开关，开启后 AI 仅做分析与规划、把方案写入 plan.md，经用户批准后才进入执行，适合在大规模修改前先审阅方案。

目标模式（Goal Runtime）：给会话设定一个最终目标与交付清单，AI 自动续跑直到完成或达到续跑上限，与第 11 章的 Goal Anchor 护栏配套。

#操作步骤：新建会话

1. 按下 Ctrl/Cmd+N，或点击标签条上固定的「新会话」按钮，打开挂起的「新会话」标签（新建入口已提级到主选择区）。
2. 在首屏选择 Provider 与模型（下拉列表显示当前已启用的 AI 引擎）。
3. 在底栏「模式」chip 中选择会话模式（通用 / Supervisor / 组队任务），首次创建默认为通用。
4. 按需在底栏调整「目录权限」chip 与「项目 / 工作区」，工作目录与 Worktree 隔离的详细设置见第 2 章 项目与工作区。
5. 在输入框中输入初始 prompt，点击发送按钮或按 Enter 完成新建并发送第一条消息。

💡 提示

需要一个不占标签条的浮窗时，可用「在独立窗口打开」把会话拆到独立聊天窗，用法见第 2 章 项目与工作区。

#操作步骤：了解会话模式

会话底栏常显一个「模式」chip，点击展开可在三档之间切换；原型设计与工作流构建器通过左侧工作区菜单进入，不在此 chip 内。

通用（Normal）

一个 AI 与你对话，可按需自主派生子 Agent。适合即时问答、代码解释、轻量改动和单文件探索，是多数日常使用的首选。所有套餐（含未登录）均可用。

Supervisor

专职编排：AI 专注调度子 Agent、自身不亲自改代码。适合多模块并行、复杂重构等大型工程任务。需要 Pro 及以上套餐。详见第 4 章 多 Agent 协同。

组队任务（Mission）

先出分析报告，你确认后再组建团队执行；AI 会在关键节点暂停、等待审批后再继续。适合端到端功能交付等大目标。需要 Pro 及以上套餐。详见第 4 章 多 Agent 协同。

⚠️ 注意

组队任务会话不支持在会话内改模式；点击 chip 中的「组队任务」会跳转到新建入口创建新的组队会话。

原型设计（Prototype）与工作流构建器

原型设计专为 UI/UX 原型，会话区内联实时预览画布，AI 权限请求自动通过、只读工具做硬限制；工作流构建器用自然语言搭建可复用的 DAG 流水线。两者需要 Ultra 套餐，分别从左侧工作区的「设计」与「流程」菜单进入，不在会话底栏的模式 chip 中切换。原型设计详见第 13 章 工作流、原型与定时任务。

5 种模式对比

💡 提示

在通用与 Supervisor 之间切换会保存并在重启会话后完全生效，界面会给出「已保存；重启会话后完全生效」的提示。

#操作步骤：发送消息

1. 点击界面底部的消息输入框，或直接开始打字聚焦输入区域。
2. 输入 prompt 文本；支持 Markdown 语法，AI 回复同样以 Markdown 渲染。
   • 粘贴图片（Ctrl/Cmd+V）或将图片文件拖放到输入框，即可附加图片到消息；已添加的图片缩略图可右键「复制图片」。
   • 粘贴或拖入非图片文件、文件路径文本，会自动生成文件引用卡片。
   • 输入 / 唤出命令菜单（见下方「输入框工具与命令」）。
   • 输入 @ 唤出引用菜单，按分类引用项目文件、专家角色、其他会话、子 Agent 输出和 MCP 工具。
   • 下滑至 @ 引用菜单详解，查看说明
3. 需要语音输入时，点击输入框右下角的麦克风按钮，说话结束后自动将语音转写为文字填入输入框。
4. 按 Enter 发送（默认）。若在设置中开启了 useCtrlEnter，则需按 Ctrl/Cmd+Enter 发送，此时 Enter 仅为换行。

💡 提示

Shift+Enter 始终插入换行，与 useCtrlEnter 设置无关；在空输入框按 ↑/↓ 可像终端一样翻阅并调出本会话最近发送过的消息。

@ 引用菜单详解

输入 @ 后弹出引用面板，包含以下标签页：

输入框工具与命令

输入 / 唤出命令菜单，除已安装 Skill 的斜杠命令外，顶部还有一组系统命令：

底栏工具条把次要功能收纳到「+」菜单，包含：邀请专家、提示词优化与撤销、引用对话、引用原型、深度思考、推理强度、权限模式、字号、系统提示词查看、目标模式与子 Agent 调度池等。

• 推理强度：Claude / Codex / Grok / OpenAI API 适配器支持在「+」菜单里选择 默认 / Low / Med / High 及更高档（Codex 为 XHigh，部分模型另有 Max）。Claude 会话运行中修改会提示「已保存，新建会话生效」。
• 提示词优化：对当前输入内容做一键润色，可随后撤销回原文。
• 提示词模板：输入框旁的「提示词模板 / AI 优化」按钮打开提示词选择器（见下文）。

#操作步骤：使用对话气泡功能

复制消息内容

1. 右键点击任意 AI 或用户消息气泡，弹出操作菜单。
2. 选择「复制消息内容」复制消息全文；或先拖选气泡内的文字，再选「复制选中文本」仅复制选区。
3. 对于 AI 消息，可选「复制为纯文本」或「复制为 Markdown 原文」，按需选取格式。
4. 若 AI 消息包含思考过程，选「复制思考过程」可单独提取推理链文本。

编辑用户消息并重发

1. 右键点击目标用户消息气泡，选择「编辑消息」；或将鼠标悬停在气泡上，点击右上角出现的铅笔图标。
2. 气泡内联展开编辑文本框，显示原始消息内容，可直接修改文字。
3. 修改完成后，点击「保存并重新发送」。SpectrAI 会清除该消息之后的回复、工具调用和系统记录，以修改后内容重新发送，截断点以前的上下文完整保留。
4. 点击「取消」退出编辑状态，消息内容不变。

⚠️ 注意

编辑后重发会删除该消息之后的所有 AI 回复和工具调用记录，此操作不可撤销。

折叠 / 展开 AI 过程消息

collapseProcessMessages 开启（默认）时，每轮完成后思考过程和工具调用自动折叠，只显示最终回答。

1. 点击每轮 AI 回复顶部的折叠标题行（显示本轮「已处理」耗时），展开或收起该轮中间过程。
2. 同一轮内的多个工具调用会合并为一条展示，思考过程默认收起，展开后可见「思考了 X」的推理链。

工具调用卡片

AI 使用工具时会显示工具卡片；点击卡片标题行展开，查看完整调用参数和返回结果。文件类结果支持「在编辑器中打开」「复制文件路径」等快捷操作。

从这里派生新会话

在 AI 回复气泡的悬停操作栏点击「从这里派生新会话」，即可以当前对话为起点开一个新会话。派生会话继承原会话的 Provider、模型、Worktree、子 Agent 白名单、MCP 与权限模式；新会话顶部有一条分割线 pill，点击可一键跳回原会话。

AI 快捷回复建议

在设置中开启「AI 提问时推荐选项」（quickReplyEnabled，默认关闭）后，当 AI 向你提问时会附一组「需要您的选择」快捷选项按钮，点击即可快速回复，也可在下方输入框自定义答案。开关入口见第 9 章 设置与快捷键。

💡 提示

对 AI 给出的建议，可用回复气泡上的「从这条建议生成任务」把它直接落成一条任务（在专家/团队场景中可用）。

跳转到最新与轮次耗时

• 当你向上滚动离开底部较远时，对话区右下角出现「跳转到最新内容」浮动按钮，点击回到最新消息。
• 每轮 AI 回复顶部显示本轮「已处理」耗时 chip；对话区左侧的消息跳转轨（默认开启）可快速跳到历史中的某条提问。

#操作步骤：时光机回滚

时光机让你把整个会话回退到任意一条历史消息之前的状态，适用于所有 Provider 的会话。

1. 右键点击要回退到的那条消息气泡。
2. 选择「回滚到此处」，会话状态回退到该消息之前，其后的对话与改动被撤下。

⚠️ 注意

回滚会撤下该消息之后的对话记录，操作前请确认无需保留后续内容。

#操作步骤：设定目标模式

1. 在输入框输入 /goal，或从底栏「+」菜单选择「目标模式」，输入框切换到目标编写态。
2. 填写最终目标（必填），可选填交付清单（每行一项）与最大续跑轮数，发送即开启。
3. 开启后会话顶部出现「🎯 目标模式」状态条，显示状态（进行中 / 已暂停 / 已阻塞 / 已完成等）、清单完成进度与续跑计数，并提供暂停 / 继续 / 清除 / 编辑按钮。

💡 提示

目标模式让 AI 自动续跑直到目标达成或触及续跑上限；配套的目标护栏与漂移检测见第 11 章 套餐与模式。

#操作步骤：开关 Plan 模式

1. 在输入框「+」菜单点「PLAN 模式」，或输入 /plan 切换；开启后会话列表 / 标签上出现紫色「PLAN」徽标，点击徽标即可关闭 Plan、回到普通 Agent。
   [ 截图 ]

   会话列表中的紫色 PLAN 徽标

   截图待补素材
2. Plan 开启后发送消息，AI 只做分析与规划，并把方案写入 plan.md；改动从下一轮生效，当前正在流式输出的回复不受影响。
3. 规划完成后弹出审批面板，点「批准计划」进入执行，或「拒绝计划」退回。
   [ 截图 ]

   计划审批面板，含批准计划与拒绝计划按钮

   截图待补素材
4. 需要跨 Provider 接力时，可在「Plan 阶段路由配置」里分别指定 Plan 阶段与 Execute 阶段使用的 Provider / 模型，并设置 Execute 失败备选链。

💡 提示

plan.md 可通过计划文档预览抽屉随时查看，并在会话间持久化；尚未生成时会提示「在 Plan 模式下发送消息，AI 会自动生成规划文档」。

#操作步骤：管理上下文

查看上下文用量

1. 观察输入框旁的上下文光环按钮，圆环颜色随占用率变化：低于 60% 蓝紫（安全），60%–85% 黄色（注意），高于 85% 红色（危险，带强化辉光）。
2. 点击或悬停光环按钮，弹出「上下文使用」详情卡片：展示已用百分比与剩余、已用 Token / 窗口上限、会话累计 Token，以及最近几次 compact 的前后对比。

手动压缩上下文

1. 点击上下文光环按钮，在弹出详情卡片底部点击「手动压缩」按钮（部分 Provider 才支持）。
2. SpectrAI 调用 summaryProviderId 指定的 Provider（留空则使用当前 Provider）将历史对话摘要为一条系统消息，后续对话在此摘要基础上继续。

💡 提示

上下文使用率接近 80% 时建议手动压缩，避免超出模型限制导致会话中断；开启 showAutoCompactNotification 后，SpectrAI 自动压缩时会弹出提示。

#操作步骤：切换会话内目录权限

目录权限决定 AI 能读写的路径范围，底栏「目录权限」chip 常显当前档位，会话内切换立即生效、无需重启。

1. 点击底栏「目录权限」chip，弹出三档选项。
2. 选择目标档位：
   • 项目目录：仅当前项目 / 工作区可操作。
   • 用户目录：允许在用户目录内操作，适合处理文档 / 桌面文件（新建会话默认）。
   • 完全访问：读写均可超出工作区，仍保护系统目录。
3. 切换成功即提示「目录权限已热更新」，同一选择会落为下次新建会话的默认。

⚠️ 注意

选择「完全访问」意味着 AI 可读写工作区以外的路径，chip 会显示红色小圆点并给出风险提示，仅在信任任务来源时使用。

#操作步骤：分享会话

1. 在会话上找到分享入口，打开「分享会话」对话框。
2. 选择链接过期时间（24 小时 / 7 天 / 30 天，默认 24 小时、最长 30 天），点击「确认分享」生成公开链接。
3. 生成后可「复制链接」或「浏览器打开」查看公开页；链接过期或后台清理后，分享内容会被删除。

⚠️ 注意

分享会把当前会话文本快照上传到 SpectrAI 服务器生成公开链接，任何拿到链接的人都可查看。对话文本可能包含账号、代码、路径、密钥等敏感信息（工具调用细节不展示），分享前请确认无泄密风险。

#操作步骤：在对话中生图与生视频

1. 在设置中配置好独立的「生图」/「生视频」中转通道（入口 设置 → AI 模型 → 生图 / 生视频，详见第 9 章 设置与快捷键）。
2. 在对话里直接描述你想要的画面或视频，AI 通过对应通道生成，结果以图片 / 视频形式内联显示在回复中。
3. 开启按需生图提示词库后，输入框会多一个图片按钮，点击可从提示词库挑选并插入生图提示词。

#操作步骤：使用提示词选择器

1. 点击输入框旁的「提示词模板 / AI 优化」按钮，打开提示词选择器。
2. 在面板顶部切换分类标签，含「⭐ 常用」（收藏）、「📝 我的」（自定义）及内置分类；用搜索框按关键词过滤模板。
3. 点击模板右侧的星标可加入 / 移出收藏；含【变量】的模板会先进入填空表单，填好后再插入输入框。

#操作步骤：导出与会话管理

导出到 Obsidian

1. 在左侧边栏右键点击目标会话，在上下文菜单中选择「导出到 Obsidian」。
2. 若 obsidianVaultPath 尚未设置，SpectrAI 弹出目录选择对话框，选择 Obsidian Vault 文件夹后保存配置。
3. 导出成功后弹出提示，显示生成的 Markdown 文件路径。

🔧 高级

批量导出多个会话到 Obsidian：在侧边栏右键任意会话选择「批量选择」，勾选目标会话后选择「导出到 Obsidian」。

收藏与置顶会话

1. 在侧边栏右键点击会话，选择「收藏置顶」；被收藏的会话移至列表顶部并显示星标。
2. 再次右键选择「取消收藏」可解除置顶状态。

重命名会话

1. 在侧边栏右键点击会话，选择「重命名」，会话名称变为内联可编辑输入框，输入新名称后按 Enter 确认。
2. 也可选择「AI 重命名」，让 AI 根据对话内容自动生成简洁标题，生成期间显示「AI 命名中…」状态。

终止与删除会话

1. 对正在运行的会话，右键选择「终止会话」立即停止 AI 当前执行。
2. 右键选择「删除任务」，确认弹窗后永久删除该会话及其全部消息记录。

❌ 不要

对正在运行的会话直接选「删除任务」；请先终止会话，再执行删除，否则可能残留未完成的后台进程。

在终端 / 文件管理器中打开工作目录

1. 右键会话选择「在终端中打开」，以会话工作目录为起点打开系统终端。
2. 选择「在文件管理器中打开」可用系统文件资源管理器定位工作目录。

#操作步骤：切换与搜索会话

1. 在顶部标签页直接点击目标会话标签切换；或在左侧侧边栏会话列表中点击任意条目跳转。
2. 按 Ctrl/Cmd+K 唤出命令面板，输入关键词快速定位并跳转到目标会话、Skill、MCP、模型或工作区。
3. 在对话区按 Ctrl/Cmd+F，在当前会话的消息内容中搜索关键词并高亮匹配结果。

#高级用法

运行中插队发送与底部队列

会话运行时输入框仍可继续输入并发送。运行中发送的消息不会打断当前回合，而是排队并在当前回合的安全边界注入，底部的进度摘要会显示「队列 N」「运行中插入 N」等状态，让你随时了解还有多少消息在等待处理。

向当前会话定时注入消息

会话级定时提醒 / 向当前会话注入定时消息由定时任务向导承载，可让计划在指定时间把一条消息投递进当前会话。调度器的完整用法见第 13 章 工作流、原型与定时任务。

#详细配置

以下设置项均可通过 Ctrl/Cmd+, 打开设置面板后进行修改。

#常见问题

编辑用户消息后 AI 像是忘记了之前的对话

编辑重发会清除该消息之后的历史，但截断点之前的对话会完整保留并注入新线程。若仍表现出遗忘，尝试手动压缩一次再继续；若问题持续，关闭并重新打开该会话。

切换 Provider 时上下文如何处理

SpectrAI 调用 summaryProviderId 指定的 Provider（默认当前 Provider）将历史压缩为摘要，新 Provider 以摘要为起点继续。若摘要精度不足，可在「设置 → 常规 → 上下文管理」中指定专门的摘要 Provider。

建会话时选错了模式还能改吗

通用与 Supervisor 之间可在底栏「模式」chip 里就地切换，保存后重启会话完全生效；组队任务、原型设计、工作流构建器不支持会话内切换，需要按 Ctrl/Cmd+N 新建会话并选择目标模式（组队任务点 chip 也会跳到新建入口）。

开了 Plan 模式后 AI 不动手改代码

这是预期行为：Plan 模式下 AI 只分析规划并写 plan.md。在审批面板点「批准计划」进入执行，或点会话列表上的紫色「PLAN」徽标关闭 Plan 回到普通 Agent。

会话卡死或 AI 无响应怎么处理

在侧边栏右键该会话，选择「终止会话」强制停止。终止后可选「继续任务」重新发起；若仍无响应，重启 SpectrAI 桌面端。

导出到 Obsidian 后能否重新导入回 SpectrAI

暂不支持将 Obsidian Markdown 导入为可继续的 SpectrAI 会话，导出仅用于归档阅读。

#相关章节

• 第 2 章 项目与工作区 — Worktree 隔离的创建与管理、工作目录配置，以及独立会话窗口
• 第 4 章 多 Agent 协同 — Supervisor 和组队任务模式下的 Agent 团队调度与任务看板
• 第 8 章 Provider 与 API — AI Provider 配置、API Key 填写和上下文摘要 Provider 的设置
• 第 9 章 设置与快捷键 — 完整快捷键速查表、生图 / 生视频通道与所有设置项的详细说明
• 第 11 章 套餐与模式 — 五种会话模式的套餐门槛、能力差异与目标护栏
• 第 13 章 工作流、原型与定时任务 — 原型设计、工作流构建器与定时任务向导（含向当前会话注入消息）