光谱AI 操作手册

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 0 章

#概述

3 步让 SpectrAI 跑起第一个 AI 会话：下载安装 → 登录并领用内置 Provider → 新建第一个会话。本章面向首次使用 SpectrAI 的新用户，预期耗时 5 分钟。读完本章你将能在桌面端完成一次完整对话；想深入了解多 Agent 协同、Provider 自接 API、远程控制等能力，按章末「下一步去哪」继续。

#前置条件

💡 提示

本章只覆盖"开箱即用"路径，不要求你提前准备 Claude / OpenAI 等第三方 API Key。系统赠送的「内置 Provider」额度足以完成本章演示。第三方 Provider 接入见 第 8 章 Provider 与 API。

#操作步骤：下载与安装

1. 用浏览器访问官方下载页 https://claudeops.wbdao.cn/download.php。
   [ 截图 ]

   官网下载页面

   截图待补素材
2. 按操作系统选择安装包：
   • Windows：点击「Windows 安装包」下载 SpectrAI-Setup.exe。
   • macOS Apple Silicon（M1/M2/M3 等）：点击「macOS arm64」下载 SpectrAI-arm64-mac.dmg。
   • macOS Intel x64：点击「macOS x64」下载 SpectrAI-x64-mac.dmg。
3. 运行安装包：
   [ 截图 ]

   Windows 安装向导步骤

   截图待补素材
   • Windows：双击 .exe，按 NSIS 向导提示选择安装目录，等待安装完成；首次启动允许 Windows Defender 或杀软放行。
   • macOS：双击 .dmg 挂载，把 SpectrAI.app 拖到 Applications；若首次启动提示「应用已损坏」，参见 第 10 章 FAQ 与故障排查 中的 macOS Gatekeeper 解锁说明。
4. 安装完成后启动 SpectrAI：
   • Windows：开始菜单找到「SpectrAI」并启动，或双击桌面图标。
   • macOS：在 Launchpad 或 Applications 中点击 SpectrAI 启动。
5. 首次启动进入初始化向导：
   [ 截图 ]

   首次启动初始化向导

   截图待补素材
   • 选择界面语言（默认随系统）。
   • 选择界面主题（浅色 / 深色 / 跟随系统）。
   • 阅读并同意服务条款与隐私协议。
6. 初始化完成后进入主控制台。左侧是会话列表（暂为空），中央是欢迎页，右上角是账号区域。

⚠️ 注意

开发模式（npm run dev）与已安装的生产版本数据完全隔离，普通用户不会触达。如果你既装了生产版又跑了源码，会话数据不会互相污染。

#操作步骤：登录并开通内置 Provider

1. 在主界面左上角点击账号区域（默认显示为「未登录」头像）。
   ![截图占位:右上角账号入口]()
2. 在弹出的登录面板中任选一种方式：
   [ 截图 ]

   登录面板的多种登录方式

   截图待补素材
   • 邮箱：输入邮箱与密码，点击「登录」；未注册的邮箱会自动引导注册。
   • 手机号：输入手机号，点击「获取验证码」，填入 6 位短信验证码后登录。
   • 微信扫码：用手机微信扫码确认即可。
3. 登录成功后头像右下角出现绿色在线指示点，并显示当前订阅档位（默认 Free）。
4. 自动进入「订阅与额度」页面查看 SpectrAI 团队赠送的内置 Provider 初始额度。
   [ 截图 ]

   订阅与额度页

   截图待补素材
5. 内置 Provider 已默认启用，无需任何配置即可在新建会话时选用。

💡 提示

内置 Provider 是 SpectrAI 团队提供的 OpenAI API 兼容服务，登录即可使用，适合快速体验。完整的额度规则、续费与发票流程见 第 1 章 账号与激活。

⚠️ 注意

登录态保存在 Electron 的 userData 目录下；切换账号或清除浏览器数据不影响 SpectrAI。如需注销，在右上角账号菜单中点击「退出登录」。

#操作步骤：新建第一个会话

1. 在主界面按 Ctrl/Cmd+N，或点击左侧栏的「+」按钮，打开新建会话对话框。
   [ 截图 ]

   新建会话对话框

   截图待补素材
2. 填写会话基础信息：
   • 会话名称：留空使用默认（当前时间），或自定义如「我的第一个会话」。
   • 工作目录：点击「浏览」选择一个本地项目目录；本次演示可以选择任意空目录或 Demo 目录。AI 后续读写文件、执行命令都局限在这里。
   • 初始指令：留空进入交互模式，或填一个简单 prompt（例如 用一句话介绍你自己）。
3. 选择 Provider：在下拉列表中选择 SpectrAI（内置 Provider，零配置）；首次使用强烈推荐此项。
   [ 截图 ]

   Provider 下拉选择内置 SpectrAI

   截图待补素材
4. 选择 Mode（会话模式）：选择 Normal 模式（普通会话）。其余 3 种模式见 第 3 章 AI 会话基础，本章不展开。
5. 其余选项保持默认：
   • 自动接受权限请求：保持关闭（首次演示建议手动审批）。
   • 终端类型：保持默认。
   • Worktree 隔离：保持开启（默认 true，会自动为本次会话创建 Git Worktree，互不打架）。
6. 点击右下角「创建」按钮，等待几秒钟 Provider 启动完毕，进入会话主界面。
   [ 截图 ]

   会话创建后的对话主界面

   截图待补素材
7. 在底部输入框敲入你的问题或指令，按 Enter 发送。
8. 等待 AI 输出：
   [ 截图 ]

   AI 回答结构化气泡 + 工具卡片

   截图待补素材
   • 上方对话区会以结构化消息气泡渲染 AI 回答。
   • 工具调用（如读文件、执行命令、搜索）以内联工具卡片展示。
   • 右上角显示「AI 正在思考…」与已用 Token 实时更新。
9. 在 AI 输出的气泡上悬停或右键可看到 3 个常用操作：
   • 复制：复制气泡全文到剪贴板。
   • 引用：把该段作为下一条 prompt 的引用上下文。
   • 收藏：把这条回答标记为收藏，方便后续在会话搜索中检索。
10. 想继续追问，在底部输入框输入下一条 prompt 即可，会话上下文会自动续接。

💡 提示

粘贴图片用 Ctrl/Cmd+V，SpectrAI 会自动把剪贴板里的图片附加到对话；不支持图像理解的 Provider 会给出警告。

❌ 不要

在「工作目录」里选系统盘根目录（C:\ 或 /），AI 拿到根目录权限后操作风险极大。建议每个会话用一个独立项目目录。

#详细配置

本章不涉及独立设置项，新建会话对话框的所有字段、默认值与依赖关系详见 第 9 章 设置与快捷键 与 第 3 章 AI 会话基础。

#常见问题

启动后看不到任何窗口怎么办？

Windows 端偶发出现窗口被推到屏幕外的情况：右键任务栏 SpectrAI 图标，选择「最大化」即可恢复显示。macOS 端先点 Dock 图标激活，再按 Cmd+Tab 切回前台。仍不可见时退出并重新启动。

登录时一直卡在「正在加载」？

检查网络是否能访问 https://claudeops.wbdao.cn/。如使用了系统代理，确认 SpectrAI 已读取代理（设置 → 网络与代理）；公司网络可能拦截 WebSocket，换个网络重试。详细排查见 第 10 章 FAQ 与故障排查。

内置 Provider 额度耗尽后还能继续用吗？

可以。两条路径：升级订阅档位（第 1 章 账号与激活），或自接第三方 Provider（第 8 章 Provider 与 API）。两种方式并行不冲突。

新建会话时找不到「SpectrAI」这个 Provider？

确认右上角已登录、且订阅页显示内置 Provider 已启用。如果仍未出现，进入「设置 → AI Provider」，检查 SpectrAI 卡片是否被禁用；如已被禁用，点击「启用」并刷新。

#相关章节

• 第 1 章 账号与激活 — 登录方式、订阅档位、额度查询的完整流程
• 第 3 章 AI 会话基础 — 4 种会话模式、对话气泡的全部交互
• 第 4 章 多 Agent 协同 — 想让 AI 自动分工时下一步去这里
• 第 7 章 远程控制 — 想在手机上看会话进度时下一步去这里
• 第 8 章 Provider 与 API — 想接入自己的 Claude / OpenAI / Gemini API 时下一步去这里
• 第 9 章 设置与快捷键 — 想改默认快捷键或调整设置项时下一步去这里
• 第 10 章 FAQ 与故障排查 — 安装或登录遇到问题时的兜底排查

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 1 章

#概述

本章面向首次安装 SpectrAI 的新用户，以及希望了解订阅与额度管理的老用户。SpectrAI 账号体系提供身份识别、订阅权益管理和内置 AI 额度三项核心能力。注册账号完全免费，免费套餐（Free）已覆盖基础使用需求；升级至付费套餐可解锁更高并发、更大附件上限、Bot 通知、远程控制等高级能力。

未登录时，应用以「游客模式」运行，最多可创建 3 个会话；登录后免费套餐最多可创建 5 个会话，并可参与每日签到领取 AI 额度。

---

#核心概念

账号 vs 订阅：账号是你的身份凭证（邮箱 + 密码），订阅是附加在账号上的消费档位（Free / Pro / Ultra / Team / Enterprise）。账号不收费，订阅按档位和周期收费。

内置 Provider：SpectrAI 官方代付的 AI 引擎服务，登录账号后即可通过每日签到领取可用额度，消耗在内置 Provider 会话上。内置 Provider 的配置与 API Key 接入方式不同，详见 第 8 章 Provider 与 API。

远程控制 Token：账号登录后会生成与账号绑定的设备凭证，用于手机端、Telegram Bot、小程序等远程通道的绑定鉴权，详见 第 7 章 远程控制。

套餐档位（由低到高）：

---

#操作步骤：注册账号

SpectrAI 目前支持邮箱注册，注册完全免费。注册成功后即获得 Free 套餐权益。

1. 启动 SpectrAI 桌面端，如弹出登录覆盖层，直接进入下一步；若未弹出，点击左侧边栏底部的头像图标，再点击登录入口。

1. 在弹出的登录对话框中，点击右下角「去注册」切换到注册模式。

1. 依次填写以下字段：
   • 邮箱地址：输入有效邮箱，后续验证码和找回密码都需要用到
   • 设置密码：至少 6 位
   • 确认密码：与上方一致
   • 邀请码（可选）：如有邀请码或通过邀请链接打开，此处会自动带入，可修改

1. 点击「注册并发送验证码」按钮，系统发送 6 位数字验证码到注册邮箱，验证码 60 秒内有效。
2. 页面自动跳转到验证码输入界面，在 6 个方格中依次输入邮箱收到的数字；也可直接粘贴完整 6 位码，系统会自动填入并提交。

1. 验证通过后，系统自动登录，对话框关闭，左侧边栏底部显示你的头像或姓名首字母。

⚠️ 注意

验证码每发送一次均有 60 秒冷却倒计时，60 秒后可点击「重新发送」。若长时间未收到邮件，请检查垃圾邮件文件夹。

💡 提示

注册时勾选「保存密码」后，SpectrAI 会将登录凭证加密存储在本地，下次启动时自动填充，无需重复输入。

---

#操作步骤：登录账号

首次登录

1. 启动 SpectrAI，若弹出登录覆盖层，直接输入邮箱和密码；若未弹出，点击左侧边栏底部的头像图标（显示为登录图标）打开登录对话框。

1. 填写邮箱地址和密码，可勾选「保存密码」。

1. 点击「登录」按钮，登录成功后对话框关闭，可开始使用完整功能。

已登录后的会话同步

登录成功后，应用会在后台每 5 分钟自动刷新一次套餐状态和额度，无需手动操作。若需立即同步，可通过头像菜单中的「刷新套餐状态」手动触发。

跳过登录

若不想立即登录，可点击登录对话框外部区域或关闭按钮，以游客模式继续使用（最多 3 个会话）。再次打开应用时覆盖层会再次弹出；若始终以游客模式使用，可在对话框中选择「跳过」。

---

#操作步骤：忘记密码与重置

1. 在登录对话框中，点击密码输入框右下方的「忘记密码？」链接。
2. 在「忘记密码」页面输入注册邮箱，点击「发送重置验证码」。
3. 系统发送 6 位重置验证码到邮箱，页面跳转到「重置密码」模式。
4. 在验证码方格中输入 6 位码，再输入新密码（至少 6 位）和确认新密码。

1. 点击「确认重置密码」，重置成功后页面返回登录模式，使用新密码登录即可。

⚠️ 注意

重置密码后，其他设备上的登录状态会失效，需重新登录。

---

#操作步骤：查看账号状态与额度

通过头像悬浮菜单（快捷查看）

将鼠标悬停在左侧边栏底部头像上，弹出悬浮菜单，菜单顶部可直接看到：

• 当前套餐名称（Free / Pro / Ultra / Team / Enterprise）标签
• 登录方式（邮箱账号 / GitHub）
• 可用额度（内置 Provider 的 USD 余额）
• 积分余额（社区积分）

菜单中还包含以下快捷入口：

• 「账号设置」→ 跳转至完整账号页
• 「升级方案」→ 跳转至订阅升级页
• 「刷新套餐状态」→ 手动从服务器同步套餐
• 「退出登录」
• 切换「简洁模式 / 专业模式」

通过「设置 → 账号」页面（完整查看）

1. 在菜单中点击「账号设置」，或通过「设置 → 账号与隐私」进入。
2. 账号信息卡片展示以下内容：
   • 头像、昵称（邮箱）
   • 套餐名称标签和登录方式标签
   • 套餐到期时间（Free 套餐显示「长期有效」）
   • 「查看升级方案」快捷按钮

1. 「社区积分摘要」区块显示：
   • 积分余额：当前可用社区积分
   • Token 额度：内置 Provider 可用的 USD 余额
2. 点击「刷新账号状态」按钮可立即从服务器拉取最新套餐和额度信息。

---

#操作步骤：升级订阅

1. 通过以下任意方式进入订阅页：
   • 头像悬浮菜单 → 「升级方案」
   • 设置 → 账号卡片 → 「查看升级方案」
2. 订阅页列出所有套餐（Free / Pro / Ultra / Team / Enterprise）及其功能对比。

1. 选择目标套餐，选择付款周期（月付 / 季付 / 年付）。
2. 选择支付方式：
   • 支付宝（扫码支付）
   • 微信支付（扫码支付）
3. 点击「立即购买」或对应按钮，页面生成支付二维码。

1. 使用对应 App 扫描二维码完成支付，支付成功后系统自动升级套餐，刷新账号状态后生效。

💡 提示

订单生成后有约 30 分钟有效期；超时后可重新发起订单。

⚠️ 注意

支付完成后若套餐未立即更新，点击头像菜单中的「刷新套餐状态」手动同步；若仍未更新，请等待 1–2 分钟后再试。

---

#操作步骤：开通/使用内置 Provider

内置 Provider 是 SpectrAI 官方代付的 AI 引擎，账号登录后可通过每日签到领取免费 AI 使用额度（USD 计）。

通过签到领取额度

1. 进入「设置 → 账号与隐私」，向下滚动找到「每日签到奖励」卡片。

1. 卡片展示 6 个解锁阶梯：
   • 阶段 1：打开 App → $5
   • 阶段 2：累计活跃 1 小时 → +$5
   • 阶段 3：累计活跃 3 小时 → +$8
   • 阶段 4：累计活跃 5 小时 → +$10
   • 阶段 5：累计活跃 8 小时 → +$10
   • 阶段 6：累计活跃 12 小时 → +$12
2. 启动应用当日，打开 App 阶梯自动解锁；随着使用时长增加，后续阶梯陆续解锁，额度自动入账。
3. 点击「立即签到」按钮可手动触发当日第一次签到（打开 App 阶梯），已签到当日此按钮变为「今日已签到」。
4. 连续签到天数越多，可在里程碑天数（如 7 天、30 天）获得额外连签奖励，奖励信息在卡片右上角展示。

⚠️ 注意

签到额度为限时推广福利，通过第三方接口提供，可能因上游服务波动暂时不可用；不建议作为生产环境的核心依赖。

查看额度余额

• 头像悬浮菜单 → 可用额度 区块（USD）
• 设置 → 账号 → 社区积分摘要 → Token 额度

将内置 Provider 设为会话 Provider

内置 Provider 配置方式见 第 8 章 Provider 与 API；本章仅介绍额度领取流程。

---

#操作步骤：多设备登录与登出

SpectrAI 账号支持在桌面端、手机端（App）、微信小程序等多端同时登录同一账号，各端会话独立。

登出当前设备

1. 将鼠标悬停在左侧边栏底部头像上，打开悬浮菜单。
2. 点击「退出登录」，当前设备登录态立即清除，覆盖层弹出。

登出所有设备

若账号疑似被盗或需要强制下线所有端，可通过以下方式：

1. 进入「设置 → 账号与隐私」，点击「退出登录」。服务端收到退出请求后，所有设备的刷新令牌将同步失效。
2. 或直接修改密码（操作步骤见下节），密码变更后其他设备旧令牌自动失效。

💡 提示

修改密码是强制下线其他设备最彻底的方式，当前设备会自动更新令牌无需重新登录。

注销账号

当前版本暂无一键注销账号的入口，如需注销请联系官方支持（反馈页见 官网反馈页面）。

---

#操作步骤：修改密码

仅适用于邮箱注册账号，GitHub 登录账号不支持此功能。

1. 进入「设置 → 账号与隐私」，向下找到「修改密码」区块。

1. 填写以下字段：
   • 当前密码：当前登录密码
   • 新密码：至少 6 位，且不能与当前密码相同
   • 确认新密码：与新密码一致
2. 点击「保存新密码」，保存成功后提示「密码修改成功，当前设备的登录状态已自动更新」，其他设备需重新登录。

---

#详细配置

以下字段来自账号状态与套餐系统，部分字段在 UI 中可见，部分为内部状态。

---

#常见问题

注册后收不到验证码邮件？

• 检查垃圾邮件或「促销」文件夹
• 确认填写的邮箱地址无拼写错误
• 60 秒冷却结束后，在验证码输入界面点击「重新发送」
• 若多次未收到，尝试更换邮箱重新注册，或通过 官网反馈 联系我们

登录时提示「登录失败」？

• 确认邮箱和密码填写正确（注意大小写）
• 账号是否已完成邮箱验证（注册时 6 位码验证步骤）
• 若忘记密码，使用登录页的「忘记密码？」流程重置
• 检查网络连接是否正常

内置 Provider 额度为 $0，无法使用？

• 确认已登录账号，游客模式无法使用内置 Provider
• 进入「设置 → 账号 → 每日签到奖励」完成当日签到
• 签到额度到账可能有 1–2 分钟延迟，刷新账号状态后再试
• 若长期为 $0，该服务可能因上游波动暂时不可用，请关注官方公告

支付成功但套餐未升级？

1. 等待 1–2 分钟，支付回调可能有延迟
2. 点击头像菜单「刷新套餐状态」手动同步
3. 若仍未生效，记录订单号（支付 App 中可查），通过 官网反馈 提供截图联系支持

换电脑后找不到历史会话？

会话数据默认存储在本机本地数据库，换设备后历史会话不会自动迁移。远程控制功能（第 7 章）可让新设备访问旧设备上的实时会话，但不是数据迁移。会话跨设备同步为规划中功能，目前暂未上线。

---

#相关章节

• 第 7 章 远程控制 — 账号绑定是远程控制的前提，Token 与设备绑定码均需登录账号
• 第 8 章 Provider 与 API — 内置 Provider 配置与 API Key 接入方式对比
• 第 9 章 设置与快捷键 — 账号相关设置项的完整参数列表

SpectrAI 的功能很多，入口也比较密。本章只讲和“项目目录、工作区、Git、Worktree 隔离”有关的操作，并把能点到的按钮、菜单和快捷键写清楚。先记住一句话：SpectrAI 用项目目录承载代码和会话，用 Git Worktree 把 AI 修改隔离到独立分支目录，避免多个任务互相污染。

#2.1 概述

在日常使用里，一个“项目”通常就是一个本地目录：里面有代码、Git 仓库、会话历史引用和本地配置。专业模式里还有“工作区（Workspace）”管理页，可以把多个相关 Git 仓库组合成一个命名工作区，适合前端、后端、API、文档分仓的项目。

Worktree 隔离是本章重点。启用后，任务或 AI 子会话会在仓库根目录下创建 .spectrai-worktrees/<任务ID>/，并使用 worktree/<任务ID> 这样的独立分支。AI 在隔离目录改代码，主仓库目录保持干净；完成后你再检查差异、合并或清理。

#2.2 核心概念

• 项目（Project / Workspace）：最常见形态是一个工作目录；在设置页中，“工作区”也可以表示一组 Git 仓库。
• 工作目录：新建会话时填写的目录。普通会话、文件树、Git 面板都围绕它工作。
• Worktree 隔离：SpectrAI 调用 Git worktree 创建独立目录和分支。任务看板和子 Agent 可自动创建；普通会话会在需要改代码时由 AI 工具进入 Worktree。
• 常用目录 / 最近目录：新建会话窗口中的“常用目录”区，支持添加、收藏、取消收藏和移除。
• 会话收藏置顶：在会话列表右键会话，点击“收藏置顶”，用于快速回到重要会话。

#2.3 打开项目

当前版本没有独立的“打开项目”主页向导，项目通常在“新建会话”时绑定。

方式 1：新建会话选择文件夹（推荐）

入口：左侧会话区点击 新建会话，或按 Ctrl+N（macOS 对应 Cmd+N）。在弹窗中选择“目录”模式，找到“选择工作目录”输入框，点击右侧文件夹图标，选择本地项目目录，然后继续选择 Provider 并点击创建。

注意：代码中没有发现应用菜单“文件 → 打开文件夹”的实现；若你习惯 IDE 的菜单打开方式，请以这里的“新建会话 → 选择工作目录”为准。

方式 2：拖拽文件夹到主界面

当前版本未发现“把文件夹拖到主界面即打开项目”的实现。可替代操作是：按 Ctrl+N 打开新建会话，再点文件夹图标选择目录。

方式 3：从“常用目录”打开

入口：新建会话 → 目录 → 常用目录。点击目录卡片即可填入工作目录；点击右上角 添加 可选择一个目录并收藏；悬停目录卡片可点星标“收藏/取消收藏”，也可点 移除 从列表删除。

方式 4：命令面板

入口：Ctrl+K 打开命令面板。当前命令面板支持“跳转到 项目”“切换会话”“打开设置项”等，但没有 Open Folder 命令。若要切换到项目视图，搜索“项目”；若要换目录，仍需新建会话或选择常用目录。

#2.4 导入或克隆 Git 仓库

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

如果你已经有本地多仓库项目，可以进入 设置 → 扩展与工具 → 工作区，点击 新建工作区。弹窗支持三种方式：

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

#2.5 启用 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. 需要合并时，可直接对当前会话说：“请检查 Worktree 合并冲突，并将该 Worktree squash 合并到主分支，合并后清理目录。”AI 会使用内置工具执行检查、合并和可选清理。
6. 如果你更习惯命令行，也可以手动执行 git merge / git worktree remove / git branch -D。合并前务必先检查差异。

当前命令面板没有专门的 Worktree 命令；手动管理请使用 Git 面板、AI 指令或系统终端。

#2.6 Git 集成

入口：切到 项目 工作区，左侧上方选择 Git 分支 Tab。

可用能力包括：

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

当前 Git 面板未发现“切换分支”按钮；需要切换主仓库分支时，请使用内置终端或系统 Git 工具。

#2.7 收藏、最近与切换项目

• 收藏目录：新建会话弹窗的 常用目录 → 添加，或悬停目录卡片点星标。
• 最近目录：创建会话后会记录使用次数和最近使用时间；默认列表取 8 个，收藏目录优先显示。
• 会话置顶：会话列表右键会话 → 收藏置顶。
• 按目录/工作区看会话：会话侧栏支持按目录或工作区分组，便于跨项目查找。
• 快速跳转：按 Ctrl+K，搜索会话名可切换会话；搜索“项目”可回到项目工作区。

#2.8 关闭项目或会话

SpectrAI 没有独立的“关闭项目”按钮，也没有项目级“保存 / 不保存”对话框；项目文件是否保存由文件编辑器自身处理，详见第 6 章。会话归档也不是一个可点击的项目入口，当前用户侧主要通过关闭、删除或继续保留会话来管理历史。

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

#2.9 详细配置

#2.10 高级用法

• 多项目并行：可以同时保留多个不同目录的会话，也可以创建多仓库工作区；主界面一次聚焦一个项目视图，通过会话分组或 Ctrl+K 切换。
• Worktree 与远端分支：Worktree 分支默认是本地分支，不等于远端分支。需要推送时，在 Git 面板点 Push，或命令行设置 upstream。
• 两种合并方式：方式一，告诉 AI 检查并合并 Worktree，它会先检查冲突再执行合并；方式二，在终端手动 git checkout main、git merge --squash worktree/xxx、git commit，确认后再 git worktree remove 清理目录。

#2.11 常见问题

Q：Worktree 合并冲突怎么办？

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

**Q：.spectrai-worktrees/ 占磁盘怎么办？**

已合并且不再需要的分支，可让 AI 使用清理选项，或手动执行 git worktree remove <path>。如果是任务看板创建的 Worktree，删除任务时会尝试清理对应目录和分支。

Q：子模块项目支持吗？

没有发现对子模块的专门 UI。它本质上仍依赖 Git，建议先在系统终端确认 git submodule update --init --recursive 正常，再让 SpectrAI 打开主仓库目录。

Q：文件变化监听卡顿怎么办？

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

#2.12 相关章节

• 第 3 章：会话——每个会话如何绑定工作目录或工作区。
• 第 6 章：终端与文件——文件树、Diff、搜索与替换。
• 第 9 章：设置——autoWorktree、图标主题、发送快捷键等设置项。

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 3 章

#概述

会话（Session）是 SpectrAI 的核心交互单元，每个会话对应一个独立的 AI 上下文，持久化存储在本地 SQLite 数据库中。每次对话、每条工具调用记录都附属于一个会话，关闭应用后重新打开仍可继续。SpectrAI 提供四种模式（Mode）满足从即时问答到大型工程任务的不同场景，并支持在会话过程中切换 Provider 或开启 Plan 模式，让用户完全掌控 AI 的工作方式与执行范围。

#核心概念

会话（Session）：用户与 AI 的单次对话上下文，包含所有消息和工具调用记录，持久化到本地 SQLite，可随时恢复。模式（Mode）：决定会话行为的配置维度，在新建时选定，共 4 种：Normal / Mission / Supervisor / Prototype；会话建立后不可更改。

Provider：底层 AI 引擎，如 Claude Code、Codex CLI 等；切换时自动生成上下文摘要弥合格式差异（详见第 8 章 Provider 与 API）。上下文（Context）：会话累积的对话历史，占用模型上下文窗口；光环按钮实时展示用量，支持手动压缩释放空间。

Plan 模式：跨模式全局开关，开启后 AI 仅做分析与方案说明，不执行文件写入或命令，适合在大规模修改前先审阅方案。

#操作步骤：新建会话

1. 按下 Ctrl/Cmd+N，或点击左侧边栏顶部的「+」按钮，打开新建会话对话框。

1. 在对话框中选择 AI配置（下拉列表显示当前已启用的 AI 引擎）。

1. 选择 Mode 卡片（Normal / Mission / Supervisor / Prototype），首次创建默认为 Normal。

1. 如需代码隔离，勾选「启用 Worktree 隔离」（详见第 2 章 项目与工作区）。

1. 在输入框中输入初始 prompt，点击「创建」或按 Enter 完成新建并发送第一条消息。

#操作步骤：了解 4 种 Mode

Normal 模式（普通会话）

单实例互动对话，一问一答，不自动创建子 Agent。适合即时问答、代码解释、轻量改动和单文件探索。是多数日常使用的首选。

Mission 模式（引导式任务）

先澄清目标与阶段约束，确认后分阶段推进并按需组队执行。AI 会在关键节点暂停、等待用户审批后再继续。适合长期任务、完整功能交付等大目标。详见第 4 章 多 Agent 协同。

⚠️ 注意

Mission 模式会在关键节点暂停，不会无限自动推进，请留意界面中的审批提示卡。

Supervisor 模式（监督模式）

主 Agent 自动拆解并派发多个子 Agent 并行执行；创建时可限定允许使用的 Agent Provider 范围。适合多模块并行、复杂重构等大型工程任务。详见第 4 章 多 Agent 协同。

Prototype 模式（原型设计）

专为 UI/UX 原型设计，会话区内联实时预览的 Prototype Canvas；AI 权限请求自动通过、只读工具做硬限制。适合界面设计、交互原型和移动端页面场景。

4 种 Mode 对比

💡 提示

Mode 建立后无法更改；若需切换，按 Ctrl/Cmd+N 新建会话并选择目标 Mode。

#操作步骤：发送消息

1. 点击界面底部的消息输入框，或直接开始打字聚焦输入区域。

1. 输入 prompt 文本；支持 Markdown 语法，AI 回复同样以 Markdown 渲染。
   • 粘贴图片（Ctrl/Cmd+V）或将图片文件拖放到输入框，即可附加图片到消息。
   • 输入 / 唤出 Slash 命令菜单，选择已安装 Skill 的快捷命令。
   • 输入 @ 唤出引用菜单，按分类引用项目文件、专家角色、其他会话、子 Agent 输出和 MCP 工具。
   • 下滑至 @ 引用菜单详解，查看说明

1. 点击输入框右下角的麦克风按钮，启用语音输入；说话结束后自动将语音转写为文字填入输入框。

1. 按 Enter 发送（默认）。若在设置中开启了 useCtrlEnter，则需按 Ctrl/Cmd+Enter 发送，此时 Enter 仅为换行。

💡 提示

Shift+Enter 始终插入换行，与 useCtrlEnter 设置无关。

@ 引用菜单详解

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

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

复制消息内容

1. 右键点击任意 AI 或用户消息气泡，弹出操作菜单。

1. 选择「复制内容」复制消息全文；或先拖选气泡内的文字，再选「复制选中内容」仅复制选区。
2. 对于 AI 消息，可选「复制为纯文本」或「复制为 Markdown」，按需选取格式。
3. 若 AI 消息包含思考过程，选「复制思考内容」可单独提取推理链文本。

编辑用户消息并重发

1. 右键点击目标用户消息气泡，选择「编辑消息」；或将鼠标悬停在气泡上，点击右上角出现的铅笔图标。

1. 气泡内联展开编辑文本框，显示原始消息内容，可直接修改文字。

1. 修改完成后，点击「保存并重发」按钮。SpectrAI 截断该消息之后的所有历史，以修改后内容重新向 AI 发送，截断点以前的对话上下文完整保留。

1. 点击「取消」按钮退出编辑状态，消息内容不变。

⚠️ 注意

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

折叠 / 展开 AI 过程消息

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

1. 点击每轮 AI 回复顶部的折叠标题行（显示本轮耗时），展开或收起该轮中间过程。

工具调用卡片

1. AI 使用工具时会显示工具卡片；点击卡片标题行展开，查看完整调用参数和返回结果。

#操作步骤：管理上下文

查看上下文用量

1. 观察输入框旁的上下文光环按钮，颜色随使用率变化（蓝→黄→橙→红）。

1. 点击光环按钮，弹出详情卡片：展示已用 Token 数、模型上下文窗口大小、使用百分比，以及最近几次 compact 的 Token 前后对比。

手动压缩上下文

1. 点击上下文光环按钮，在弹出详情卡片底部点击「手动压缩」按钮。

1. SpectrAI 调用 summaryProviderId 指定的 Provider（留空则使用当前 Provider）将历史对话摘要为一条系统消息，后续对话在此摘要基础上继续。

💡 提示

上下文使用率接近 80% 时建议手动压缩，避免超出模型限制导致会话中断。

开关 Plan 模式

1. 在消息输入框区域找到 Plan 模式切换按钮（显示「已开启」或「已关闭」状态文字）。

1. 点击切换；改动从下一轮对话生效，当前正在流式输出的回复不受影响。
2. 开启状态下，AI 仅做分析、方案说明与风险评估，不执行任何文件写入或命令。

⚠️ 注意

Plan 模式是会话级开关，仅影响当前会话；切换 Provider 或新建会话后需重新开启。

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

导出到 Obsidian

1. 在左侧边栏右键点击目标会话，在上下文菜单中选择「导出到 Obsidian」。

1. 若 obsidianVaultPath 尚未设置，SpectrAI 弹出目录选择对话框，选择 Obsidian Vault 文件夹后保存配置。

1. 导出成功后弹出提示，显示生成的 Markdown 文件路径。

🔧 高级

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

收藏与置顶会话

1. 在侧边栏右键点击会话，选择「收藏置顶」；被收藏的会话移至列表顶部并显示星标。

1. 再次右键选择「取消收藏」可解除置顶状态。

重命名会话

1. 在侧边栏右键点击会话，选择「重命名」，会话名称变为内联可编辑输入框，输入新名称后按 Enter 确认。

1. 也可选择「AI 重命名」，让 AI 根据对话内容自动生成简洁标题，生成期间显示「AI 命名中…」状态。

终止与删除会话

1. 对正在运行的会话，右键选择「终止会话」立即停止 AI 当前执行。

1. 右键选择「删除任务」，确认弹窗后永久删除该会话及其全部消息记录。

❌ 不要

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

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

1. 右键会话选择「在终端中打开」，以会话工作目录为起点打开系统终端。

1. 选择「在文件管理器中打开」可用系统文件资源管理器定位工作目录。

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

1. 在顶部标签页直接点击目标会话标签切换；或在左侧侧边栏会话列表中点击任意条目跳转。

1. 按 Ctrl/Cmd+K 唤出命令面板，输入关键词快速定位并跳转到目标会话。

1. 在对话区按 Ctrl/Cmd+F，在当前会话的消息内容中搜索关键词并高亮匹配结果。

#详细配置

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

#常见问题

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

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

切换 Provider 时上下文如何处理

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

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

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

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

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

#相关章节

• 第 2 章 项目与工作区 — Worktree 隔离的创建与管理，以及工作目录的配置方式
• 第 4 章 多 Agent 协同 — Supervisor 和 Mission 模式下的 Agent 团队调度与任务看板
• 第 8 章 Provider 与 API — AI Provider 配置、API Key 填写和上下文摘要 Provider 的设置
• 第 9 章 设置与快捷键 — 完整快捷键速查表与所有设置项的详细说明

SpectrAI 的差异化在于让多个 AI 同时为你工作，且能分工、复盘、互相纠偏。本章覆盖 Supervisor、Mission、Teams、Butler 四套机制，请按顺序阅读。

#4.1 概述

单个 AI 面对「实现完整 Todo 应用」往往会跑偏：上下文爆掉、前端做完忘后端、代码没人审。SpectrAI 把会话变成 多智能体编队——主 Agent 拆任务，子 Agent 并行执行，角色复审，Butler 监督。四套机制：

四套机制可叠加：Mission 任务某阶段交给 Teams，整个会话由 Butler 巡检。

[ 截图 ]

四种协同模式对比卡片

截图待补素材

#4.2 核心概念

• 主 Agent / 子 Agent：主 Agent 是用户直接对话的会话；主 Agent 调用 spawn_agent 派发出来的独立子会话就是子 Agent，带独立 Worktree 与 Provider。
• 角色 / 团队：角色是一份预设（系统提示词 + 默认 Provider + 适用阶段）；团队是一组角色的组合。SpectrAI 内置 18 个角色、8 个团队模板。
• Mission 阶段：Mission v2 把任务拆成 4 个阶段（头脑风暴 → 团队设计 → 阶段规划 → 准备就绪），每阶段都有确认门。
• 5 维度评分：completeness（完整性）、accuracy（准确性）、codeQuality（代码质量）、adherence（规范遵循）、innovation（创新性），合格线 7.0/10。
• 漂移检测：评估器比对产物与原始目标，输出 7 类漂移标签（详见 §4.5.5）。
• Butler 巡检：Butler 周期扫描所有会话，识别卡死/需确认/错误并按策略干预。

#4.3 在 Supervisor 模式下让 AI 自动分工

Supervisor 模式适合「我有一个大目标，希望主 Agent 自己想清楚怎么拆」的场景。主 Agent 会在每一轮自行决定要不要派发子 Agent，每个子 Agent 都跑在自己的 Worktree 上，结果通过系统事件回流。

4.3.1 操作步骤

1. 新建会话。点左侧栏「+ 新建对话」（详见第 3 章 §3.2）。

1. 勾选 Supervisor 模式。开关右侧说明：「主 Agent 可调用 spawn_agent 自动派发子任务」。

1. 选 Provider 与 Worktree。建议至少 2 个 Provider 以便轮询，保持「启用 Worktree」开启。
2. 输入大目标，点「开始」。例如：「实现一个支持本地存储和导入导出的 Todo 应用」。

1. 观察子 Agent 状态条。会话输入栏上方出现「专家派发」状态条，每行一个子 Agent：状态点 + 子 Agent 名 + 状态徽章 + 「进入子对话」按钮。状态文案六种：派发中（紫，闪烁）、已启动（黄）、运行中（绿，闪烁）、完成（蓝）、失败（红）、已取消（灰）。

1. 等待事件驱动回报。子 Agent 完成后主对话自动收到系统消息 [SYSTEM][AGENT_COMPLETED] 附带产物摘要，主 Agent 据此推进，用户此期间无需操作。
2. 审阅并合并 Worktree。所有子 Agent 完成后，主 Agent 列出每个子 Worktree 分支名请求合并，具体见第 2 章 §2.5。

4.3.2 中途追加约束的正确做法

这是 SpectrAI 的一条硬规则：

**禁止在子 Agent 处于 running / pending / waiting_input 时，调用 send_to_agent 追加指令。**

如果你在子 Agent 跑到一半时想新增约束（例如「前端要用 Tailwind」），正确做法是：

1. 等子 Agent 进入终态（完成 / 失败 / 已取消）。
2. 把完整修订需求告诉主 Agent，由主 Agent 重新派发新的子 Agent。

主 Agent 的系统提示里对此做了硬约束：拒绝运行期下发 send_to_agent，并回报错误码 supervisor_follow_up_forbidden。

4.3.3 并行调度规则

子 Agent 的 running / pending / waiting_input 状态 不构成调度锁。只要写入范围不冲突，主 Agent 可同时派发多个子 Agent，各自跑在独立 Worktree。默认并行上限 3，可在「设置 → 多 Agent → 并行上限」调整。

#4.4 用 Mission v2 完成四阶段规划

Mission 模式适合复杂、长链路、希望「先看完方案再启动」的任务。它把整个交付过程切成 4 个阶段，每个阶段都是一道用户确认门。

4.4.1 四个阶段

v2 把「执行」「评估」合并到「准备就绪」之后的运行期，所以 wizard 上是 4 步。

4.4.2 操作步骤

1. 新建会话，切到 Mission 模式。在「新建对话」弹窗的模式选择区勾选「Mission 模式」。

1. 填写目标和约束。目标（goal）：至少 1 句话；约束（constraints）：可选，每条一行，如「必须用 React」。
2. 选择自动模式：manual（每阶段确认）、supervised（AI 自审但仍弹窗）、full（仅阶段失败才弹）。
3. 阶段 1 头脑风暴。AI 输出方案后，stepper 第一个圆点变实心，下方列出方案要点、假设、风险。底部「打回重做」/「确认并进入团队设计」。

1. 阶段 2 团队设计。AI 推荐角色组（如产品经理 + 架构师 + 前端 + 后端 + QA）。卡片显示中文名、推荐 Provider（colored 徽章：claude-code 琥珀、codex 翠绿、gemini-cli 蓝、opencode 紫）、能力标签。内置 18 角色覆盖分析/设计/实现/验证/文档五大类，点笔形图标可改 Provider。

1. 阶段 3 阶段规划。AI 拆 DAG（React Flow 渲染），节点标注名称、复杂度、工作量、分配角色；箭头表依赖；无依赖节点自动并行。颜色：紫=头脑风暴、青=规划、淡黄=待确认、青柠=执行中、翠绿=完成。

1. 阶段 4 准备就绪。点「启动 Mission」，所有节点进入执行池。底部「Mission 控制台」显示进度条与暂停 / 恢复 / 跳过 / 终止。

1. 运行期评估。节点完成后自动触发 5 维度评分（§4.5.4）和漂移检测（§4.5.5）。低于阈值（默认 7.0）的进入「待人工复核」。

4.4.3 关于「返工」与「跳过」

• 打回（仅阶段 1～3）：在确认门点「打回重做」，AI 基于反馈重新跑当前阶段，先前阶段产物保留。
• 跳过当前阶段（运行期）：把该阶段标为 skipped，但不回退已完成的阶段。跳过的阶段留下 (用户跳过此阶段) 占位记录，依赖它的下游节点可能因上游缺失而失败。

没有「整段回退」按钮。若在阶段 3 后才发现阶段 1 有问题，建议终止并新开 Mission——先前产物保存在 docs/missions/<missionId>/ 可复用。

#4.5 组建 Agent Teams 让多 AI 协作

Teams 适合「反复做同一类任务」的场景（如每周一次代码审查）。配置好团队后，每次只需提交任务到队列，Agent 自动认领、协作、互评。

4.5.1 进入 Teams 看板

1. 最左侧 Activity Bar 点「Agent Teams」图标（第三栏）。
2. 主区域切换为 Teams 看板，顶部 Tab：成员 / 任务 / 消息 / 模板 / 复审池 / 驾驶舱。

4.5.2 新建团队

1. 右上角点「+ 新建团队」。
2. 选择模板（内置 8 个）：

1. 进入编辑视图后，每个角色可单独修改 Provider / 模型 / 系统提示词 / 工具范围。

4.5.3 提交任务并观察协作

1. 「任务」Tab 点「+ 新任务」，填写标题、描述、目标锚点（用于漂移检测）。
2. 任务进「待领取」队列，Agent 按角色自动认领，无冲突时多角色并行。
3. 「消息」Tab 显示 Agent 间消息流（基于 InterventionDispatcher 总线，含发送方、接收方、ACK 状态、合并标记）。
4. 任务流转：待领取 → 进行中 → 待复审 → 已完成 / 已驳回。

4.5.4 5 维度评分雷达

任务完成后复审池自动打分，结果在「评估详情」抽屉里：

各维度评分 0～10，加权得综合分，默认合格线 7.0。低于阈值的任务进入「驳回 / 重做」，可自动重试最多 2 轮。

4.5.5 漂移检测

评估器比对目标锚点与产物，输出最多 7 类漂移标签：

漂移标签以彩色徽章显示在评估抽屉顶部。critical（goal_changed）强制打回，不能自动放行。

#4.6 让 Butler 守护你的会话

Butler 2.0 是 SpectrAI 的「AI 管家」——不直接参与任务，在外围巡检所有活跃会话，发现异常按策略干预。

4.6.1 启用 Butler

1. 「设置 → Butler」勾选「启用管家」总开关。
2. 桌面右下角出现圆形头像（默认 🤖）即 Butler 浮窗，位置可拖动，记忆在 butler-float-position。

4.6.2 Butler 检测什么

Butler 周期巡检（默认 3 秒一轮）检测 8 类事件（ButlerDetectionReason 枚举）：

卡死阈值是 stuckThresholdSeconds，默认 300 秒，不在 UI 暴露，需改设置文件。

4.6.3 Butler 的干预动作

干预分三档（ButlerDecisionLevel）：

• auto：直接帮你做。支持 auto_confirm / send_enter / auto_approve / auto_continue 四种动作。
• notify：浮窗变 alert（红色脉冲 0.8 秒一次），右下角弹 Toast。
• escalate：弹窗强制用户介入，Butler 不再自动决策。

4.6.4 查看 Butler 决策历史

左键点 Butler 头像 → 浮窗里点「活动日志」Tab。显示最近 50 条决策，按时间倒序，颜色编码：绿=auto、黄=notify、红=escalate。

4.6.5 灵敏度与人格化

「设置 → Butler」面板可调：

人格化：头像支持多种 emoji（🤖/🐱/🦊 等），动画对应 6 种情绪 idle / watching / alert / working / happy / sleeping。浮窗右键菜单切换。

#4.7 详细配置一览

本章涉及的全部设置，路径从「设置」根菜单开始。

#4.8 常见问题

Q1：子 Agent 跑了 10 分钟没动静，怎么办？ 看派发状态条。若还停在「运行中」，打开 Butler 活动日志查 session_stuck；未启用 Butler 则手动点「进入子对话」查看输出，必要时终止。不要 追加 prompt 试图唤醒（§4.3.2）。

Q2：能不能给运行中的子 Agent 追加新约束？ 不能。主 Agent 会拒绝并返回 supervisor_follow_up_forbidden。等子 Agent 进入终态后，把完整修订需求告诉主 Agent，由它重新派发。

Q3：Mission 返工后，之前阶段的产物会丢吗？ 不会。阶段 1～3 的「打回重做」只重跑当前阶段，先前产物保留并喂回 AI；运行期的「跳过当前阶段」也不回退已完成节点，但被跳过的阶段留下占位，依赖它的下游可能因上游缺失而失败。

Q4：Teams 的任务谁来认领？ 任务挂「适用阶段」标签，所有 applicablePhases 命中的角色进候选池，按 Provider 可用性、当前负载、最近完成时间排序，由最空闲角色认领，同一任务不会被两角色同时认领。

Q5：Butler 误判怎么办？ 两种降权：（1）关掉对应检测项的自动动作，降级为「只通知不动手」；（2）调高巡检间隔（最高 10 秒）。AI 辅助误判则关「AI 辅助决策」。误判记录留在活动日志，作为调优依据。

Q6：四种模式可叠加吗？ 常见组合：Mission + Butler（Mission 跑任务，Butler 兜底）、Supervisor + Teams（主 Agent 把任务塞 Teams 队列）。不建议同会话同时勾 Supervisor 和 Mission——两者都改写主 Agent 系统提示，当前 Mission 会覆盖 Supervisor 的并行调度策略。

#4.9 相关章节

• 第 2 章 Worktree 隔离：所有子 Agent / Mission 节点 / Teams 任务都跑在独立 Worktree。
• 第 3 章 会话基础：「新建会话」「切换模式」的基础流程。
• 第 5 章 工具与 MCP：子 Agent 工具权限范围由 §5.4 权限矩阵决定。
• 第 8 章 Provider 管理：多 Agent Provider 轮换策略与白名单。

适用版本：SpectrAI 桌面端（校对日期：2026-05-20）

#5.1 概述

SpectrAI 通过 MCP（Model Context Protocol）网关，把大量外部能力统一暴露给 AI：例如数据库查询、SSH 远程部署、浏览器自动化、知识检索、设计与媒体处理等。你也可以通过 Skill 市场安装可复用的“提示词 + 工具调用”组合，快速把常见任务标准化。

本章重点回答四件事：

1. 怎么管理 MCP 服务器（安装、启停、测试、排障）；
2. 怎么使用 Skill 市场（安装、触发、卸载）；
3. 怎么做自定义扩展（自定义 MCP / Hooks / 脚本）；
4. 怎么在会话里追踪 AI 实际调用了哪些工具。

重要：Provider（底层模型）与 MCP 工具是两回事。Provider 决定“谁来思考”，MCP 决定“能做什么操作”。

---

#5.2 核心概念

• MCP：Model Context Protocol，AI 调用工具的标准协议。
• MCP 服务器：提供具体能力的服务端（如 database、ssh、chrome 自动化）。
• MCP 网关：SpectrAI 内置聚合层，统一管理多个 MCP Server、预扫描工具、按需启动与空闲回收。
• Skill：可复用任务包，核心是 Prompt 模板，可声明依赖工具并通过 /slash 触发。
• 内置工具：出厂可用基础工具（如 Read / Write / Edit / Glob / Grep / Bash / spawn_agent / wait_agent 等）。

---

#5.3 操作步骤：浏览与安装 MCP 服务器

步骤 1：打开 MCP 管理面板

入口 A：设置 → 扩展 → MCP。 入口 B：Ctrl+K 打开命令面板，搜索“设置/MCP 服务器”直达。

步骤 2：查看已安装服务器并启停

在列表中可看到名称、分类、传输协议（stdio/http/sse）、安装状态、全局启用开关；支持按状态/协议/安装状态筛选。

步骤 3：浏览市场（含 Smithery 集成）

切到“市场”分类，可选择数据源：推荐 / Official / Smithery / MCP Hub / 全部。Smithery 需要先配置 API Key。

步骤 4：搜索并一键安装

输入关键词（如 ssh、database、obsidian），点击“安装”。若该 MCP 需要环境变量，会先弹出变量填写对话框。

步骤 5：配置环境变量与 API Key

在“添加/编辑 MCP”弹窗填写 KEY=VALUE（每行一个），用于注入 API Key、Token、连接串等。

步骤 6：启动并测试连接

点击“测试连接”：

• stdio 会做完整协议检查（启动 → initialize → listTools）；
• http/sse 会先做可达性与握手验证。

通过后开启全局开关即可进入会话可用状态。 成功 失败（测试失败，可以优先让AI去调用一下是否可以调用到）

步骤 7：查看暴露工具列表

可在会话输入框输入 @，切到 @tool 查看 MCP 工具候选；也可在会话里用 list_mcp_servers / search_mcp_tools 查看工具目录。

---

#5.4 操作步骤：调用 Skill 市场

步骤 1：进入 Skill 入口

• 会话中直接输入 /<skill-name>；
• 或 设置 → 扩展 → 技能。

步骤 2：浏览市场

技能库含“我的技能”和“技能市场”，市场内含官方与社区（skills.sh）子页，可按分类/关键词筛选。

步骤 3：安装 Skill

支持一键安装；也支持从 URL/GitHub、本地目录、npm、Skill 包导入。安装后会落盘到本地 skills 目录，并写入索引。

步骤 4：在会话触发 Skill

在输入框使用 /skill 触发；命令面板也可把 slash 命令插入输入框。已安装 Skill 可按 Provider 兼容性启用/禁用。

步骤 5：Skill 失效 / 卸载

• 先检查是否被禁用；
• 包类型 Skill 可“卸载包”；
• 单技能可删除并重新安装。

[截图占位-5-12：Skill 启停与卸载]

---

#5.5 操作步骤：编写自定义工具

当前版本可行路径：

1. 自定义 MCP 服务器（推荐）：设置 → MCP → +添加 MCP，填写 command/args 或 URL；
2. 通过 Hooks 做脚本自动化：设置 → 自动化 → Hooks，动作可选 shell/agent/team/workflow/skill/webhook；
3. 本地脚本注入：在 MCP server 的 command/args 中挂接本地脚本或可执行文件。

[截图占位-5-13：添加自定义 MCP 表单] [截图占位-5-14：Hooks 动作类型与 Shell 配置]

说明：代码中未发现统一“settings.json 自定义工具中心”UI；自定义能力以 MCP 管理页与 Hooks 面板为主。

---

#5.6 操作步骤：配置工具凭证

1. 在 MCP 安装/编辑弹窗配置 envVars（API Key、Token、连接串）；
2. Smithery 市场依赖 smitheryApiKey 设置项；
3. 凭证撤销：删除对应 env 变量并禁用/删除 MCP，随后到服务商侧轮换密钥；
4. 跨设备策略：当前代码未见 MCP 凭证自动云同步闭环，建议手工迁移并先脱敏。

[截图占位-5-15：MCP 凭证编辑] [截图占位-5-16：禁用/删除 MCP 撤销凭证]

---

#5.7 在会话中查看 AI 使用了哪些工具

• 工具卡片：对话气泡展示 tool_use/tool_result，可折叠参数与结果，支持复制；
• 工具分组：连续调用会聚合显示总数、成功/失败数、耗时；
• 命令执行日志面板：Ctrl+Shift+X 打开底部面板，按状态与会话筛选；
• 失败重试：当前未见“同卡片一键重试”统一入口，建议在日志面板定位失败命令后重发，或回 MCP 管理页再次“测试连接”。

[截图占位-5-17：工具卡片参数/结果折叠] [截图占位-5-18：工具分组汇总] [截图占位-5-19：命令执行日志面板]

---

#5.8 详细配置（重点参数）

---

#5.9 高级用法（可选）

1. 非 UI 路径 MCP 注入：不同 Provider 会由系统生成临时 MCP 配置（如 mcp-config-*.json、临时 CODEX_HOME、GEMINI_CLI_HOME/.gemini/settings.json）。
2. 把 SpectrAI 暴露为 MCP：代码中存在内部 spectrai-agent 机制，主要用于会话内桥接；暂无稳定的“一键对外服务”界面流程。

---

#5.10 常见问题

Q1：MCP 启动失败

先看三类错误：

• 命令不存在（npx/uvx/python/pip 未安装）；
• Node 版本不匹配（切换 mcpNodeVersion 再测）；
• 协议握手失败（server 能启动但 initialize/listTools 失败）。

Q2：工具调用超时

长任务（视频、转码、大模型推理）请提高 call_mcp_tool.timeout，并确认远端服务本身可达。

Q3：Skill 安装后对话里不出现

依次检查：是否启用、slash 名是否正确、Provider 是否兼容、是否被同名目录技能覆盖。

Q4：凭证泄漏怎么办

立刻在服务商侧吊销/轮换 Key；在 SpectrAI 中清空 envVars 并禁用/删除相关 MCP；重建最小权限凭证。

---

#5.11 相关章节

• 第 4 章：Agent 调用工具
• 第 8 章：Provider vs MCP 工具的区别
• 第 9 章：settings.json、工具与 hooks 配置

---

#5.12 自检清单（10 项）

• [x] 术语统一（Provider 与 MCP 区分）
• [x] 覆盖内置工具 / MCP / Skill / 自定义扩展
• [x] 含 UI 入口路径
• [x] 每个关键流程有步骤编号
• [x] MCP 安装 7 步完整
• [x] Skill 使用 5 步完整
• [x] 截图占位已补齐
• [x] 含配置表与默认值说明
• [x] 含 FAQ 与排障建议
• [x] 相关章节交叉引用完整

SpectrAI 内置了真实的 Shell 终端和文件管理器，让你无需离开应用就能查看 AI 的所有改动、运行命令、对比文件差异和搜索代码。本章详细介绍终端面板、文件树、改动追踪、Diff 视图和全文搜索的使用方法。

---

#6.1 概述

SpectrAI 的终端基于 node-pty 实现，在 Windows 上使用 ConPTY、macOS/Linux 上使用原生伪终端，提供真实交互式 Shell。文件管理器以树形结构展示项目目录，支持右键菜单、内联重命名、新建文件和拖拽引用。

AI 修改文件时，SpectrAI 自动追踪变更——你可以在「会话改动」面板中查看 Diff，或直接打开内置终端跑命令。

---

#6.2 核心概念

PTY 终端

SpectrAI 的终端是真正的伪终端（PTY），交互式命令（如 vim、top、python REPL）可正常使用，支持 ANSI 颜色和 256 色调色板。Windows 上默认启用 ConPTY 兼容模式。

文件变更追踪

AI 每次通过工具修改文件时，SpectrAI 自动记录：

• 修改（蓝色圆点）：文件内容被 AI 改动
• 新增（绿色图标）：AI 创建了新文件
• 删除（红色图标）：AI 删除了文件

标记同时出现在文件树节点和「会话改动」面板中。

Diff 视图

点击「会话改动」面板中的文件，展开内联 Diff 查看器。Diff 视图以类 git diff 格式展示：左侧旧行号、右侧新行号，新增行绿色高亮、删除行红色高亮，上下文行正常显示。

全文搜索

SpectrAI 集成跨文件搜索，支持正则表达式、大小写敏感匹配和 glob 文件过滤，结果可直接跳转。

---

#6.3 打开和切换终端面板

6.3.1 唤出终端

终端面板位于应用底部，以标签页形式管理多个 Shell 实例。

6.3.2 新建标签页

点击终端面板右上角的 + 按钮新建 Shell 标签页。如果系统检测到多个可用 Shell，点击 + 右侧的 ▼ 下拉箭头可指定 Shell。

• 最多支持 8 个并发终端标签
• 新标签默认继承当前 AI 会话的工作目录
• 标签标题自动显示 Shell 名称

6.3.3 切换标签

6.3.4 重命名标签

右键点击标签页 → 重命名，输入自定义名称（最长 40 字符），方便在多个终端间快速识别。

6.3.5 关闭面板

点击终端面板右上角的 折叠 按钮（向下箭头图标），或再次按 Ctrl+` 即可隐藏终端面板。面板状态会记住你的选择，下次打开应用时恢复。

---

#6.4 使用文件树

6.4.1 文件树位置

文件树位于界面左侧边栏。打开或创建一个会话后，文件树会自动显示该会话的工作目录结构。

6.4.2 展开与折叠

• 单击目录：展开或折叠该目录
• 单击文件：在右侧代码查看器中打开该文件
• 双击文件：使用系统默认程序打开该文件

6.4.3 文件筛选

文件树顶部有一个筛选输入框，输入关键词即可实时过滤文件名。匹配的文件名会高亮显示，再次点击 × 按钮清除筛选。

6.4.4 右键菜单

在文件树中右键点击任意文件或目录，可以打开上下文菜单：

6.4.5 拖拽引用

将文件树中的文件拖拽到对话输入框，会自动生成文件引用卡片，AI 可以直接读取该文件内容。

6.4.6 工作区模式

如果当前会话属于工作区（Workspace），文件树会显示工作区下所有仓库的目录树，主仓库标记 ★ 号。

---

#6.5 追踪 AI 文件变更

6.5.1 会话改动面板

在文件树顶部，SpectrAI 会显示一个「会话改动」面板，折叠状态下显示改动的文件数量。点击展开后，可以看到当前会话 AI 改动过的所有文件列表。

6.5.2 改动标识

文件树中对应的节点右侧也会显示一个 蓝色圆点，表示该文件已被当前会话的 AI 改动。

6.5.3 多会话改动归因

当多个会话同时运行时，SpectrAI 会根据工作目录深度和最近活动时间将文件改动归因到对应会话。如果多个会话修改了同一文件，改动列表会显示黄色 ⚠ 警告图标，提示你注意潜在的冲突。

---

#6.6 文件搜索

6.6.1 全项目搜索

搜索面板位于文件树区域，与文件树共享侧边栏空间。输入关键词后按 Enter 开始搜索，结果按文件分组显示。

6.6.2 搜索选项

搜索框右侧提供四个切换按钮：

6.6.3 查看与跳转

搜索结果按文件分组，点击文件名可展开查看具体匹配行。每行显示匹配内容，点击匹配行即可跳转到代码查看器的对应位置。

6.6.4 替换功能

替换功能支持：

• 逐文件替换：点击文件右侧的替换按钮，仅替换该文件中的匹配项
• 全局替换：替换所有文件中的所有匹配项（需确认）
• 替换预览：开启替换模式后，每个匹配行下方会显示替换后的预览效果

6.6.5 快速打开文件

快速打开对话框以模糊搜索方式列出项目中的所有文件，输入文件名关键词即可实时过滤。使用 ↑↓ 导航，Enter 打开选中文件，Esc 关闭对话框。

---

#6.7 在终端中运行命令

6.7.1 切换 Shell

新建终端标签时，点击 + 按钮右侧的 ▼ 下拉菜单可以选择 Shell：

SpectrAI 会自动检测系统中已安装的 Shell 并显示在列表中。如果未检测到可用 Shell，会显示「未检测到可用 Shell」提示。

6.7.2 复制与粘贴

终端支持标准复制粘贴：

• 复制：选中文本后按 Ctrl+C（未选中时 Ctrl+C 发送中断信号）
• 粘贴：右键菜单或 Ctrl+V
• 清屏：输入 clear（Unix）或 cls（Windows）

6.7.3 终端工作目录

新建终端标签时，默认工作目录为当前选中 AI 会话的工作目录。如果未选中任何会话，则回退到用户主目录。

6.7.4 AI 驱动终端

AI 在会话中可通过 bash / shell 类工具自动执行命令，输出实时显示在对话视图中。终端面板是供用户手动交互使用的独立环境，AI 不会直接操作它。

---

#6.8 配置项

SpectrAI 的文件与终端相关配置集成在应用设置中：

提示：终端字体大小、颜色主题等高级配置目前使用默认值，后续版本可能在设置界面提供独立选项。

---

#6.9 常见问题

终端启动失败，提示「未检测到可用 Shell」

原因：SpectrAI 无法在系统路径中找到任何可用的 Shell 可执行文件。

解决方法：

1. 确认系统中已安装至少一种 Shell（PowerShell、CMD、Git Bash 等）
2. 检查环境变量 PATH 是否包含 Shell 所在目录
3. Windows 用户可尝试安装 Git for Windows，它自带 Git Bash
4. 重启 SpectrAI 应用

AI 修改的文件没有显示蓝色圆点

原因：文件改动追踪依赖 AI 通过 SpectrAI 工具接口修改文件。如果 AI 通过系统命令直接修改文件，可能无法被追踪。

解决方法：

1. 确认 AI 会话使用 SpectrAI 内置工具链
2. 点击文件树顶部的 刷新 按钮手动刷新
3. 检查「会话改动」面板是否处于折叠状态

Diff 视图加载缓慢或显示空白

原因：大文件的 Diff 计算可能耗时较长；如果文件已被删除，Diff 无法生成对比。

解决方法：

1. 等待几秒让 Diff 计算完成（加载态会显示旋转图标）
2. 如果是新建或删除的文件，Diff 视图会显示相应的空状态提示，这是正常行为
3. 如果持续报错，尝试刷新文件树后重新点击该文件

文件树过大时卡顿

原因：包含数千个文件的大型项目可能导致文件树渲染变慢。

解决方法：

1. 使用文件树顶部的筛选输入框缩小可见范围
2. 折叠不需要查看的子目录
3. 避免展开包含大量子目录的根节点

终端输出中文字符乱码

原因：终端编码设置与 Shell 输出编码不一致。

解决方法：

1. Windows 上使用 PowerShell 7 或 Git Bash 通常能正确显示中文
2. 如果使用 CMD，尝试在终端中输入 chcp 65001 切换到 UTF-8 编码
3. 确保 TERM 环境变量设置为 xterm-256color（SpectrAI 默认已设置）

---

#6.10 相关章节

• 第 2 章：Worktree 隔离 — 了解 Git Worktree 如何隔离多会话改动
• 第 4 章：多 Agent 协作 — 多 Agent 并行时的终端与文件管理
• 第 9 章：设置 — 终端与文件相关的设置项详解
• 文件管理与改动追踪（教程） — 更详细的改动追踪使用指南

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 7 章

#概述

SpectrAI 支持从多个端控制桌面端，包括 Web 浏览器、手机 App（Android/iOS）、以及 Telegram、飞书、企业微信等 Bot。远程控制允许你从任何地点向桌面端的会话发送指令、查询状态、接收推送通知，是协作和监控的重要工具。本章讲解如何在桌面端开通各类远程通道、配置 Bot 账号、设置推送偏好。

#核心概念

远程控制：从 Web 浏览器、手机 App、小程序或聊天 Bot 远程发起会话任务、获取结果反馈的能力。桌面端必须保持运行才能接收远程指令。

Relay 中转：如果桌面端位于内网（无公网 IP），可启用 Relay 中转服务将事件转发至公网，使移动端和 Web 端能穿透内网访问。Relay 是可选的；若你有公网 IP 或仅在局域网内使用，可跳过。

专用 Provider：远程控制可指定独立的 AI Provider（设置 remoteControlProviderId），与主会话 Provider 分离。这样做可避免远程命令占用主会话的 API 额度，或使用更低成本的模型回复 Bot 消息。

推送通道：Bot（Telegram、飞书、企微）可配置推送偏好，例如仅当会话完成时推送、推送失败消息、设置静默时段。

💡 提示

如果你主要在局域网内使用，仅需配置 Web 端；若要在公网随时远控，则需启用 Relay 或使用 Bot 通道。

#操作步骤：启用 Web 端远程控制

Web 端远程控制允许你在浏览器或其他桌面设备上访问桌面端的会话。

1. 在桌面端打开「设置 → 远程控制 → Web 端远程」
2. 点击「启用 Web 接入」开关
3. 点击「生成二维码」或「复制链接」
4. 在 PC 浏览器或手机浏览器中打开链接，或扫描二维码
5. 如需 Relay 中转（内网穿透），在同一设置页点击「启用 Relay 中转」，然后点击「连接」验证连接状态
6. 验证连接后，Web 端可看到所有桌面端的会话列表

⚠️ 注意

Web 端为了安全，建议在同局域网内使用，或启用 Relay 后走 HTTPS 加密隧道；请勿在公共 WiFi 上直接访问 Web 端（unless over Relay）。

#操作步骤：绑定移动端 App

移动端 App（iOS 和 Android）可通过扫码绑定到桌面端，并接收推送通知。

1. 在移动设备的应用商店（Google Play / App Store）下载「SpectrAI 远控客户端」
   • 详细下载指引见 官网移动端页面
2. 在桌面端打开「设置 → 远程控制 → 移动端」
3. 点击「生成绑定二维码」
4. 打开 App，进入「设备绑定」，点击摄像头图标扫描二维码
5. App 显示绑定成功后，在桌面端确认「设备已连接」
6. 测试推送：在桌面端运行会话，App 应收到完成通知
7. 若要解绑设备，在「已绑定设备」列表点击「移除」

#操作步骤：配置 Telegram Bot

Telegram Bot 可发送和接收远程指令、查询会话状态、配置推送偏好。

1. 在 Telegram 中搜索官方 Bot 账号 @SpectrAIRemoteBot，或使用 Bot 链接 https://t.me/SpectrAIRemoteBot
2. 点击「START」或输入 /start，Bot 会返回一个 6 位绑定码
3. 复制绑定码，回到桌面端打开「设置 → 远程控制 → Telegram」
4. 在「Telegram 绑定码」字段粘贴 6 位码，点击「验证并绑定」
   [ 截图 ]

   Telegram 绑定码输入与验证

   截图待补素材
5. 验证成功后，在 Telegram 中发送 /status 命令，Bot 应回复当前桌面端的连接状态
6. 可在 Telegram 中发送常见 Bot 命令：
   • /status — 查询桌面端在线状态
   • /latest — 查询最近 3 个会话的进度
   • /help — 列出所有可用命令
7. 配置推送偏好：在桌面端「设置 → 远程控制 → Telegram → 推送设置」勾选接收的事件类型

#操作步骤：配置飞书机器人

飞书机器人可发送会话完成提醒、失败告警、状态查询。

1. 打开飞书，进入你的工作群或私聊
2. 在消息栏右侧点击「+」，选择「添加机器人」
3. 搜索官方应用「SpectrAI 监控」并点击「添加」，或创建自定义机器人
4. 若使用自定义机器人，从机器人设置页复制 Webhook URL
5. 在桌面端打开「设置 → 远程控制 → 飞书」
6. 将 Webhook URL 粘贴到「飞书 Webhook」字段，点击「测试连接」
   [ 截图 ]

   飞书 Webhook 粘贴与测试

   截图待补素材
7. 如使用官方应用，复制应用 ID，粘贴到「飞书 App ID」字段，点击「授权」
8. 配置推送：勾选「接收完成通知」、「接收失败告警」、「接收状态查询回复」
9. 返回飞书群，当桌面端会话完成时，机器人会自动发送结果卡片

#操作步骤：指定远程控制专用 Provider

默认情况下，远程控制使用主 Provider。你可指定独立 Provider，避免占用主会话额度或节省成本。

1. 在桌面端打开「设置 → 远程控制 → Provider 设置」
2. 在「远程控制专用 Provider」下拉框中选择一个 Provider
3. 推荐组合：
   • 主会话：Claude（功能全面、准确度高）
   • 远程 Bot：DeepSeek / 国产大模型（响应快、成本低）
4. 点击「保存」完成配置
5. 如要恢复默认，将下拉框设置为「使用主 Provider」

🔧 高级

独立指定 Provider 的好处是减轻主 Provider 的并发压力，或在 Bot 命令频繁时使用更廉价的模型回复。若远程命令需要高质量回复，建议选择与主会话相同的 Provider。

#详细配置

#高级用法

Relay 中转服务器自建

若不想依赖官方 Relay，可自建一套。Relay 服务器代码在 packages/relay-server/ 目录。

• 修改 Relay 服务器地址：在「设置 → 远程控制 → Relay 配置」的「Relay 服务器地址」字段填入自建服务器 URL，格式为 https://your-relay-domain.com
• 重启 Relay 连接使新配置生效

多设备同账号推送策略

若多个设备（多个手机、Web 端）绑定同一账号：

• 推送将发送至所有已绑定设备
• 若需要仅推送至特定设备，在「已绑定设备」列表中选择性地禁用其他设备
• Telegram / 飞书 / 企微同时工作，彼此独立配置

Bot 命令快捷入口

可在快捷键设置中配置快速触发 Bot 命令。例如：

• 绑定 Ctrl+Shift+T 到 Telegram 的 /latest 命令
• 详见 第 9 章 设置与快捷键

#常见问题

Web 端扫码后无反应？

检查以下项：

• 桌面端的「设置 → 远程控制 → Web 端远程」确实启用了
• 如在公网访问，确保 Relay 已连接，状态显示「已连接」
• 检查防火墙是否放通了 Web 服务端口（默认 9800）
• 尝试点击「重新启动服务」重启 Web 服务
• 如仅局域网使用，在链接中将 localhost 改为桌面端的局域网 IP 地址

Telegram Bot 收不到推送？

• 验证 Telegram 账户已与 Bot 绑定，在 Telegram 中发送 /status 有回复
• 检查「Telegram 推送设置」是否勾选了推送类型（完成 / 失败）
• 若你的网络无法访问 Telegram 服务，尝试配置代理或使用飞书 / 企微作为备用
• 查看桌面端日志：文件 → 打开日志文件夹 → telegram.log

飞书机器人 Webhook 验签失败？

• 确认复制的 Webhook URL 完整无误（不要去掉末尾参数）
• 飞书 Webhook 可能有时间窗口限制，确保桌面端系统时间准确
• 若使用自定义机器人，检查 Secret 是否已在桌面端配置（如机器人设置了 Secret）
• 点击「测试连接」按钮，查看弹出的错误提示，复制错误信息在 官方反馈 提交

移动端推送有延迟，或某些通知未送达？

• 确保 Relay 连接状态良好，在「设置 → 远程控制 → Web 端远程」查看连接状态
• 移动设备检查是否启用了应用通知权限（Settings → Notifications → SpectrAI）
• 网络较差时，推送可能延迟 10–30 秒，这是正常的
• 若是 iOS 端，检查是否开启了"允许离线时通知"

同账号多设备，如何区分推送来自哪个桌面端？

在「设置 → 远程控制 → 设备标识」为当前桌面端取一个名称（如"办公室工作站"），推送消息会带上此标识，便于区分。

#相关章节

• 第 1 章 账号与激活 — 账号绑定是远程控制的前提
• 第 8 章 Provider 与 API — Provider 配置与 remoteControlProviderId 设置
• 第 9 章 设置与快捷键 — 快捷键配置与远程控制集成
• 第 10 章 FAQ 与故障排查 — 网络、权限、推送延迟问题排查

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 8 章

#概述

SpectrAI 通过 Provider 适配层统一接入不同的 AI 后端，无论是在本地启动 CLI 工具，还是通过 HTTP API 调用云端模型，上层业务逻辑完全无感。每个 Provider 代表一套 AI 接入配置，包含连接方式、鉴权参数和默认模型。本章覆盖所有内置 Provider 的完整接入指南、OpenAI 兼容接口的添加方法，以及上下文摘要、远程控制等场景的 Provider 分配策略，是配置 SpectrAI 最重要的一章。

#核心概念

Provider：SpectrAI 中连接一个 AI 后端的配置单元。每个 Provider 记录接入方式（CLI 命令或 HTTP URL）、API Key、默认模型等信息，可在会话顶部选择器中切换。

内置 Provider：SpectrAI 预设的 Provider，含 SpectrAI 托管、Claude Code、Codex CLI、Gemini CLI、GitHub Copilot、OpenCode、Cursor、iFlow CLI 共 8 个。内置 Provider 不可删除，但可禁用或修改参数。

自定义 Provider：用户手动添加的 OpenAI 兼容 API 接入，覆盖 OpenAI、DeepSeek、Kimi、智谱、SiliconFlow、OpenRouter、Ollama 等任意兼容接口。

OpenAI 兼容：遵循 OpenAI Chat Completions 或 Responses API 格式的接口标准，SpectrAI 的 openai-api 适配器可接入任意兼容该格式的服务，无需修改代码。

CLI 类 Provider：以本地命令行进程方式运行的 Provider（Claude Code、Codex CLI、Gemini CLI、Copilot、OpenCode、Cursor、iFlow CLI），SpectrAI 通过 PTY 或 stdio 与进程通信，需要用户在本机安装对应 CLI 工具。

上下文摘要 Provider（summaryProviderId）：专门用于执行会话上下文压缩摘要的 Provider，与主会话 Provider 解耦。留空时使用当前会话的 Provider，建议指向低成本模型以节省摘要费用。

模型：每个 Provider 可配置一组可用模型，在会话顶部的模型选择器中切换；同 Provider 内切换不重建会话，跨适配器类型切换则需重建。

---

#操作步骤：添加自定义 Provider

将任意 OpenAI 兼容 API 接入 SpectrAI。

1. 在主界面左侧导航点击底部「设置」图标，进入「设置 → AI Provider」

1. 点击右上角「+ 添加 Provider」按钮

1. 在弹出的「新建 Provider」面板中选择 Provider 模板分组：「官方」/「国产中转」/「海外中转」/「自定义」

1. 点击目标模板卡片（如「DeepSeek」），Base URL 和默认模型自动填入；选「自定义」则手动填写

1. 在「Provider 名称」字段输入易识别的名称（如 DeepSeek 生产），该名称显示在会话切换列表

1. 在「API Key」栏粘贴密钥，点击眼睛图标可预览密钥

1. 在「默认模型」栏确认或修改模型名称

1. 点击「测试连接」按钮，等待连接验证结果

1. 显示「✓ 连接成功」后，点击「保存」完成添加

⚠️ 注意

API Key 以加密形式存储在本地 SQLite 数据库，切勿将 Key 粘贴到会话内容或截图中分享。

---

#操作步骤：会话内切换 Provider

在已有会话中临时更换 AI Provider，无需创建新会话。

1. 在会话底部工具栏找到当前 Provider 名称（如「Claude Code」），点击它

1. 在弹出的 Provider 列表中选择目标 Provider

1. 若目标 Provider 属于同一适配器类型（如从 Claude Sonnet 切到 Claude Opus），切换即时生效，对话历史完整保留

1. 若目标 Provider 类型不同（如从 Claude Code 切到 DeepSeek），系统弹窗提示「切换将重建会话」，点击「确认」继续

💡 提示

在 Supervisor 模式下，子 Agent 可单独分配 Provider，不必与主 Agent 相同；详见第 4 章 多 Agent 协同。

---

#各 Provider 接入指南

SpectrAI（内置托管）

能力简介

SpectrAI 内置托管 Provider（ID: claudeops-builtin）是 SpectrAI 平台自有 AI 接入通道，由 SpectrAI 后端代理转发请求，用户无需自备 API Key、无需科学上网，订阅后开箱即用。适合快速体验 SpectrAI 全功能或不希望管理多个 API Key 的用户。

API Key 获取

托管 Provider 无需用户提供 API Key，额度绑定至 SpectrAI 订阅账号。在「设置 → 账号 → 订阅详情」可查看当前 Token 余量和重置周期。

填写步骤

SpectrAI 托管 Provider 为系统内置，无需手动创建：

1. 进入「设置 → AI Provider」，找到「SpectrAI」卡片（带紫色星形图标）

1. 确认卡片状态显示「已启用」；若显示「余量不足」，点击「去续费」前往订阅页

测试连接

点击「SpectrAI」卡片右侧「...」菜单，选择「测试连接」。显示「✓ 连接成功」表明托管通道正常。若提示「401 未授权」，说明账号 Token 已失效，重新登录即可恢复。

---

Claude Code

能力简介

Claude Code 是 Anthropic 官方 AI 编程 CLI，擅长代码生成、多文件重构、代码审查和复杂任务拆解。支持 Claude Sonnet 4.6（速度与质量平衡）和 Claude Opus 4.6（深度推理）两种模型，上下文窗口 200K token。

API Key 获取地址

有两种接入方式：

• OAuth 订阅：已订阅 Claude Pro/Team 的用户，无需 API Key，执行 claude login 完成 OAuth 授权即可。
• Anthropic 官方 API Key：前往 https://console.anthropic.com/settings/keys 创建密钥（需先在 https://console.anthropic.com/signup 注册账号，访问需科学上网）。

⚠️ 注意

中转站或第三方 OpenAI 兼容 Key 请勿填到 Claude Code 内置配置，应通过「添加 Provider」新建自定义 OpenAI 兼容 Provider。

填写步骤

Claude Code 是系统内置 Provider，无需新建记录：

1. 打开 SpectrAI 内置终端，执行 npm install -g @anthropic-ai/claude-code 安装 CLI

1. 安装完成后执行 claude --version 验证版本

1. 在终端执行 claude login，在弹出的浏览器页面完成 Anthropic 账号 OAuth 授权（订阅用户推荐此方式）

1. 若使用官方 API Key：进入「设置 → AI Provider → Claude Code」，点击「编辑」，在「API Key」栏粘贴 sk-ant-... 格式密钥

1. 若 claude 命令不在系统 PATH，在「可执行文件路径」字段填写完整路径：
   • Windows 示例：C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\cli.js

1. Windows 用户：确认「Git Bash 路径」字段可用（通常自动探测；若探测失败，手动填写 C:\Program Files\Git\bin\bash.exe）

1. 在「默认模型」中选择 claude-sonnet-4-6 或 claude-opus-4-6，点击「保存」

测试连接

点击「设置 → AI Provider → Claude Code」的「测试连接」。CLI 进程成功启动后显示「✓ 连接成功」。

常见失败原因：

• claude: command not found：CLI 未安装或不在 PATH，重新执行安装命令或填写 executablePath
• 401 Unauthorized：OAuth Token 过期，执行 claude login 重新授权；或 API Key 填写有误
• Windows 上「bash.exe 不可用」：Git 未安装或安装在非标准路径，手动设置 gitBashPath

---

Codex CLI

能力简介

Codex CLI 是 OpenAI 官方 AI 编程 CLI，使用 GPT-5 Codex 系列模型，面向代码实现、Bug 修复和大型代码库分析场景，内置代码全自动模式（--full-auto），无需人工确认即可完成复杂改造。上下文窗口 128K token。

API Key 获取地址

• OAuth 登录：已订阅 ChatGPT Plus/Pro 的用户，执行 codex login 完成 OAuth 授权。
• OpenAI 官方 API Key：前往 https://platform.openai.com/api-keys 创建密钥（需先在 https://platform.openai.com/signup 注册，访问需科学上网）。

⚠️ 注意

中转站 Key 不适用于此内置配置，请通过「添加 Provider」新增自定义 OpenAI 兼容 Provider。

填写步骤

1. 在终端执行 npm install -g @openai/codex 安装 CLI，完成后执行 codex --version 验证

1. 在终端执行 codex login，在浏览器授权页完成 OpenAI 账号授权（订阅用户推荐此方式）

1. 若使用 API Key：进入「设置 → AI Provider → Codex CLI」，点击「编辑」，在「API Key」栏粘贴 sk-... 格式密钥

1. 在「默认模型」中选择 gpt-5-codex（编码优化）或 gpt-5（通用），点击「保存」

测试连接

点击「设置 → AI Provider → Codex CLI」的「测试连接」，验证 Codex 进程可正常启动并响应。

常见失败原因：

• codex: command not found：CLI 未安装，重新执行 npm install -g @openai/codex
• 401 Unauthorized：API Key 无效或 OAuth Token 过期，重新执行 codex login
• 429 Too Many Requests：请求频率超限，稍等片刻后重试

---

Gemini CLI

能力简介

Gemini CLI 是 Google 官方 AI 编程 CLI，使用 Gemini 2.5 Pro / Flash 系列模型，上下文窗口 128K token，适合多模态任务（含图片分析）、超长文档处理和代码协作场景。Gemini CLI 要求 Node.js v24+，SpectrAI 通过 nvm 自动切换至正确版本（配置值 24.11.0），无需手动干预。

API Key 获取地址

前往 https://aistudio.google.com/apikey 创建 Gemini API Key（需 Google 账号，访问需科学上网；免费额度较充足，适合个人开发者试用）。

填写步骤

1. 在终端执行 npm install -g @google/gemini-cli，完成后执行 gemini --version 验证

1. 进入「设置 → AI Provider → Gemini CLI」，点击「编辑」

1. 在「API Key」字段粘贴 Google AI Studio 的密钥

1. 确认「Node.js 版本」字段显示 24.11.0（SpectrAI 自动填入，无需修改）
2. 在「默认模型」中选择 gemini-2.5-pro（高质量）或 gemini-2.5-flash（高速），点击「保存」

测试连接

点击「测试连接」，等待 Gemini CLI 进程启动（首次启动约需 10–30 秒，nvm 切换版本需要额外时间）。

常见失败原因：

• gemini: command not found：CLI 未安装，重新执行安装命令
• 403 Permission Denied：API Key 未在 Google Cloud Console 启用 Generative Language API
• 启动超时（超过 30 秒无响应）：nvm 未安装或 Node.js v24 版本未拉取，先在终端执行 nvm install 24.11.0

---

GitHub Copilot

能力简介

GitHub Copilot 通过 copilot-sdk 适配器接入，适合已持有 GitHub Copilot 订阅（Individual / Business / Enterprise）的用户，直接复用 Copilot 订阅额度，无需额外 API 费用。

API Key 获取地址

需要有效的 GitHub Copilot 订阅（https://github.com/features/copilot）。接入无需单独 API Key，通过 GitHub OAuth 授权鉴权。

填写步骤

1. 按照 GitHub Copilot 官方文档完成 CLI 代理程序安装，并执行 GitHub OAuth 授权
   [ 截图 ]

   GitHub Copilot CLI 授权完成确认

   截图待补素材
2. 进入「设置 → AI Provider → GitHub Copilot」，确认卡片状态显示「已启用」
   [ 截图 ]

   GitHub Copilot 内置 Provider 卡片

   截图待补素材
3. 若 Copilot 命令不在系统 PATH，点击「编辑」手动填写 copilot 的可执行路径
   [ 截图 ]

   Copilot 可执行路径字段

   截图待补素材

测试连接

点击「测试连接」，系统启动 Copilot 进程并验证授权状态。

常见失败原因：

• copilot: command not found：CLI 代理程序未安装，参考 GitHub 官方文档完成安装
• 401 Unauthorized：GitHub OAuth 授权过期，重新执行 Copilot CLI 登录流程
• 订阅已到期：前往 github.com/settings/copilot 续费

---

OpenCode

能力简介

OpenCode 是 HTTP-first 的 AI 编码助手，通过 opencode-sdk 适配器以 HTTP 协议与本地 OpenCode 服务通信。OpenCode 内部可对接多家 AI 服务商（在 OpenCode 自身配置中设置），适合偏好轻量 HTTP 通信方式的用户。

API Key 获取地址

OpenCode 项目主页：https://github.com/opencode-ai/opencode。目标 AI 服务的 API Key 配置在 OpenCode 自身的配置文件中，与 SpectrAI 的 Provider 配置分开管理。

填写步骤

1. 按照 OpenCode 官方文档安装并启动本地 OpenCode 服务，执行 opencode --version 验证

1. 进入「设置 → AI Provider → OpenCode」，确认卡片显示「已启用」

1. 如本地服务端口非默认，点击「编辑」修改连接参数，保存

测试连接

点击「测试连接」，SpectrAI 连接本地 OpenCode 服务。服务未运行时显示「连接失败」，先在终端启动 OpenCode 服务再重试。

---

Cursor

能力简介

Cursor 通过 cursor-acp 适配器接入，使用 Cursor Agent Protocol（ACP over JSON-RPC 2.0 on stdio）通信。适合已购买 Cursor 订阅、希望在 SpectrAI 中统一调度 Cursor Agent 的用户。

API Key 获取地址

Cursor 订阅页：https://cursor.sh/pricing。接入无需单独 API Key，Cursor 代理程序通过本地授权文件鉴权。

填写步骤

1. 确认 Cursor 已安装，且 cursor-agent 命令可用（通过 Cursor 应用自带的 CLI 组件提供）

1. 进入「设置 → AI Provider → Cursor」，确认卡片显示「已启用」

测试连接

点击「测试连接」，验证 cursor-agent acp 进程可正常启动。失败时确认 Cursor 应用已登录且版本支持 ACP 协议（Cursor v0.40+ 起支持）。

---

iFlow CLI

能力简介

iFlow CLI 通过 iflow-acp 适配器接入，采用 ACP over JSON-RPC 2.0 on stdio 通信协议。适合企业内网部署 iFlow AI 工作流平台的团队，由企业管理员统一下发配置。

API Key 获取地址

iFlow 为企业私有部署产品，API Key 和服务地址由企业管理员提供，无公开注册入口。

填写步骤

1. 由企业管理员提供 iFlow CLI 安装包，完成安装后执行 iflow --version 验证

1. 进入「设置 → AI Provider → iFlow CLI」，点击「编辑」

1. 填写企业管理员提供的连接参数，点击「保存」

测试连接

点击「测试连接」，验证 iFlow CLI 进程可正常启动并接收请求。连接失败时联系企业管理员确认服务地址和授权配置。

---

#OpenAI 兼容 Provider 接入指南

SpectrAI 的 openai-api 适配器兼容任意符合 OpenAI Chat Completions 格式的接口。下列模板已预置 Base URL 和默认模型，选择模板后仅需填写 API Key 即可。

OpenAI（官方）

能力简介

OpenAI 官方 API，接入 GPT-5 系列模型，适合需要最新 OpenAI 模型能力的场景，支持 Function Calling、Vision、Responses API 等高级特性，可通过 reasoningEffort 参数控制推理强度。

API Key 获取地址

前往 https://platform.openai.com/api-keys 创建密钥（需 OpenAI Platform 账号，注册地址 https://platform.openai.com/signup，访问需科学上网）。

填写步骤

1. 进入「设置 → AI Provider → 添加 Provider」，在「官方」分组点击「OpenAI」模板

1. Base URL 自动填入 https://api.openai.com/v1（无需修改）
2. 在「API Key」字段粘贴 sk-... 格式密钥

1. 默认模型填写 gpt-5.4 或按需调整，点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。返回「✓ 连接成功」表示鉴权有效。若提示 401，检查 Key 格式；若提示「网络不可达」，需配置代理（见详细配置中的代理设置）。

---

DeepSeek

能力简介

DeepSeek 是国内低成本通用推理模型，deepseek-chat 综合性价比高，适合高频调用、代码生成和文档处理场景；deepseek-reasoner 为深度推理版本。无需科学上网，国内直连速度快。

API Key 获取地址

前往 https://platform.deepseek.com/api_keys 创建密钥（需 DeepSeek 平台账号，支持国内手机号注册）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「DeepSeek」模板

1. Base URL 自动填入 https://api.deepseek.com/v1
2. 在「API Key」字段粘贴密钥，默认模型填写 deepseek-chat

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。401 表示 Key 无效；402 表示账户余额不足，前往 DeepSeek 控制台充值。

---

硅基流动 SiliconFlow

能力简介

硅基流动是国内模型聚合平台，可统一接入 DeepSeek-V3、Qwen、Yi、Llama 等多种开源和国产模型，按实际 Token 用量计费，适合需要在不同模型间快速测试的场景。

API Key 获取地址

前往 https://cloud.siliconflow.cn/account/ak 创建密钥（需手机号注册，新注册用户有免费 Token 额度）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「硅基流动 SiliconFlow」模板

1. Base URL 自动填入 https://api.siliconflow.cn/v1
2. 粘贴 API Key，默认模型填写 deepseek-ai/DeepSeek-V3 或其他模型全名

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。硅基流动模型名称为 <机构>/<模型> 格式（如 deepseek-ai/DeepSeek-V3），若模型名填写错误会返回 404，需核对 SiliconFlow 控制台的模型列表确认正确名称。

---

智谱 GLM

能力简介

智谱 GLM 系列（GLM-4.5 等）是国内代表性大语言模型，适合中文问答、文档总结和代码辅助场景，提供完整的国内合规保证，无需科学上网。

API Key 获取地址

前往 https://open.bigmodel.cn/usercenter/apikeys 创建密钥（需智谱开放平台账号）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「智谱 GLM」模板

1. Base URL 自动填入 https://open.bigmodel.cn/api/paas/v4
2. 粘贴 API Key，默认模型填写 glm-4.5

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。智谱 API Key 创建后有时需数分钟生效，若首次测试失败，稍等后重试。

---

月之暗面 Kimi

能力简介

Moonshot Kimi 适合中文长文处理和通用助手场景，提供 8K / 32K / 128K 多种上下文规格，适合需要超大上下文窗口的阅读分析和长对话任务，无需科学上网。

API Key 获取地址

前往 https://platform.moonshot.cn/console/api-keys 创建密钥（需月之暗面平台账号）。

填写步骤

1. 进入「添加 Provider」，在「国产中转」分组点击「月之暗面 Kimi」模板

1. Base URL 自动填入 https://api.moonshot.cn/v1
2. 粘贴 API Key，默认模型填写 moonshot-v1-8k（或 moonshot-v1-128k 以获得 128K 上下文）

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。注意选择正确的模型规格，8K / 32K / 128K 计费单价不同；模型名称错误会返回 404。

---

OpenRouter

能力简介

OpenRouter 是海外聚合平台，一个 Key 可访问 OpenAI、Anthropic、Mistral、Meta Llama 等数百个模型，适合需要对比不同模型效果或试用小众模型的场景，所有请求通过 OpenRouter 统一计费。

API Key 获取地址

前往 https://openrouter.ai/keys 创建密钥（需 OpenRouter 账号，访问需科学上网）。

填写步骤

1. 进入「添加 Provider」，在「海外中转」分组点击「OpenRouter」模板

1. Base URL 自动填入 https://openrouter.ai/api/v1
2. 粘贴 OpenRouter API Key（sk-or-... 格式）
3. 默认模型填写目标模型的 OpenRouter 标识，如 openai/gpt-4o-mini 或 anthropic/claude-3-haiku

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。OpenRouter 模型名格式为 <provider>/<model-slug>，填错会返回 404；连接失败时检查是否需要配置代理。

---

Google Gemini API（HTTP 直连）

能力简介

除 Gemini CLI 外，还可通过 OpenAI 兼容入口直接调用 Gemini API，无需本地安装任何 CLI，适合只需 HTTP API 的轻量接入方式。支持 Gemini 2.5 Pro / Flash 系列。

API Key 获取地址

前往 https://aistudio.google.com/apikey 创建密钥（需 Google 账号，访问需科学上网）。

填写步骤

1. 进入「添加 Provider」，在「官方」分组点击「Google Gemini」模板

1. Base URL 自动填入 https://generativelanguage.googleapis.com/v1beta/openai
2. 粘贴 Google API Key，默认模型填写 gemini-2.5-pro 或 gemini-2.5-flash

1. 点击「测试连接」，确认成功后点击「保存」

测试连接

点击「测试连接」。若提示「403 Permission Denied」，需前往 Google Cloud Console 启用 Generative Language API；访问失败时检查代理设置。

---

#内置 Provider 与自定义 Provider 对比

---

#详细配置

下表列出 Provider 相关的全部持久化设置项。

全局 Provider 设置（影响所有会话）：

单个 Provider 设置（在各 Provider 的「编辑」面板中配置）：

---

#高级用法

Ollama 本地模型接入

Ollama 在本地运行开源大模型（如 Llama 3、Qwen2.5、DeepSeek-R1 等），完全离线，无 API 费用，适合隐私敏感或无外网环境。

1. 从 https://ollama.com 下载安装 Ollama
2. 在终端执行 ollama pull qwen2.5-coder:7b 拉取目标模型（可按需替换模型名）
3. 执行 ollama serve 启动本地服务（默认监听 http://localhost:11434）
4. 在「添加 Provider」中选择「自定义」，Base URL 填写 http://localhost:11434/v1
5. API Key 填写任意非空字符串（Ollama 本地不鉴权，但 SpectrAI 表单要求 Key 非空）
6. 默认模型填写已拉取的模型名，如 qwen2.5-coder:7b

🔧 高级

Ollama 支持 GPU 加速；安装 NVIDIA/AMD 驱动后拉取模型即自动启用。显存不足时自动降级 CPU 推理，速度较慢。

Cloudflare Workers 反向代理

若 OpenAI 或 Anthropic 官方 API 在大陆无法直连，可通过 Cloudflare Workers 搭建免费反代，在 SpectrAI 中将 Base URL 替换为 Workers 自定义域名，其余配置不变。搭建流程参考社区文档，关键词：「Cloudflare Workers OpenAI Proxy」。

🔧 高级

Cloudflare Workers 每日有免费请求配额（10 万次），超限后需付费升级 Workers Paid 计划。

摘要专用低成本 Provider

会话上下文压缩默认使用当前会话的 Provider 执行摘要，消耗该 Provider 的额度。若希望将摘要任务路由到低成本 Provider（如 DeepSeek），在「设置 → AI Provider → 高级 → 摘要 Provider」中设置 summaryProviderId 指向目标 Provider 的 ID。

多 Key 管理与负载分发

SpectrAI 不内置多 Key 轮询，但可通过以下方式实现：

• 方案一：创建多个同 Base URL 不同名称的 Provider（如 DeepSeek-Key1、DeepSeek-Key2），手动在会话中切换
• 方案二：在自建的 OneAPI / LiteLLM 等代理服务中配置多 Key 池，SpectrAI 侧只填写代理地址和代理的统一访问 Key

---

#常见问题

测试连接一直显示「连接中…」无反馈

对 HTTP API（OpenAI 兼容），优先检查 Base URL 是否可达：在浏览器地址栏访问 <base-url>/models，若超时则说明网络不通，需配置代理或使用其他 Base URL。对 CLI 类 Provider（如 Claude Code、Gemini CLI），检查 CLI 是否正确安装；Windows 用户同时确认 Git Bash 路径正确。若 CLI 首次启动较慢（超过 30 秒），考虑调大「状态配置」中的 startupStuckMs 阈值。

添加 Provider 保存后，会话切换列表里看不到

进入「设置 → AI Provider」找到对应条目，确认右侧启用开关处于打开状态（enabled: true）。若 Provider 被设置为禁用，切换列表会将其过滤；重新打开开关后刷新会话列表即可显示。

提示 402 余量不足或账户欠费

对 SpectrAI 内置托管 Provider，表示当前订阅 Token 已用完，前往「设置 → 账号 → 订阅」续费或升级套餐。对第三方 API Provider，表示对应账号余额不足，前往对应控制台充值。

大陆能否直接使用 OpenAI 或 Anthropic 官方 API

OpenAI 和 Anthropic 官方 API 接入点在大陆通常无法直连，需要科学上网或使用反向代理。DeepSeek、SiliconFlow、智谱、Kimi 等国产服务无需科学上网，可在国内直接访问。

切换 Provider 后，历史对话消息变少

跨适配器类型切换（如从 Claude Code 切到 DeepSeek）会触发会话重建，原 CLI 会话中的消息历史无法直接迁移。SpectrAI 会生成一段摘要作为新会话的上下文背景，但无法完整还原所有历史细节。建议在会话开始前规划好 Provider 选择，减少跨类型切换。

Gemini CLI 报「Node.js 版本不兼容」

Gemini CLI 要求 Node.js v24+。SpectrAI 会通过 nvm 自动切换至 24.11.0，但前提是系统已安装 nvm。若系统未安装 nvm，先从 https://github.com/nvm-sh/nvm 安装，再执行 nvm install 24.11.0 拉取版本，重新测试连接即可。

---

#相关章节

• 第 1 章 账号与激活 — SpectrAI 订阅与内置 Provider 额度管理
• 第 3 章 AI 会话基础 — 会话内切换模型和 Provider 的完整操作流程
• 第 7 章 远程控制 — 远程控制专用 Provider 配置（remoteControlProviderId）
• 第 9 章 设置与快捷键 — 全局设置项与快捷键 SoT（单一事实源）

本章是 SpectrAI 桌面端的「设置百科」与全书快捷键的唯一事实源（SoT）。所有可配置项均从源码 settingsStore.ts / shortcuts.ts 逐字段提取，字段名与代码完全一致。

---

#9.1 概述

SpectrAI 的行为可通过三层设置体系进行定制：

命令面板（Ctrl+K / Cmd+K）是跨设置导航的核心入口，可模糊搜索并直达任意设置子页。

---

#9.2 打开设置面板

1. 点击主界面左侧导航栏底部 设置 图标；或通过命令面板搜索「设置」。
2. 左侧展示 8 个分类按钮，点击可切换到对应区域。
3. 右侧顶部为子 Tab 栏，点击可在同一分类内快速跳转。
4. 如需查找某项设置，直接使用命令面板（Ctrl+K）输入关键词即可定位。

设置面板 8 大分类：

提示：简洁模式（小白模式）下仅显示常规、账号、AI 模型、扩展四个分类，切换到专家模式可查看全部。

---

#9.3 设置项分组详表

以下每组对应设置面板的一个子 Tab。表格 5 列固定：字段名 | 类型 | 默认值 | 作用 | 入口位置。

9.3.1 常规

9.3.2 外观

内置颜色主题（12 款）：

9.3.3 AI Provider（简版）

Provider 的完整配置参见第 8 章。本节仅列出与「设置面板」直接相关的全局字段。

9.3.4 语音转写

9.3.5 MCP 与扩展

9.3.6 网络与代理

---

#9.4 快捷键全表（全书 SoT）

本表是 SpectrAI 全书快捷键的唯一事实源。其他章节引用快捷键时统一指向本节对应条目。

9.4.1 窗口级快捷键

窗口级快捷键仅在 SpectrAI 窗口获得焦点时生效。

9.4.2 全局快捷键

全局快捷键注册到操作系统层，即使 SpectrAI 不在前台也能响应。

9.4.3 输入框快捷键

---

#9.5 自定义快捷键

1. 打开设置面板 → 常规分类 → 快捷键 子 Tab。
2. 所有可配置的快捷键以列表形式展示，每行显示当前绑定值和功能描述。
3. 点击某行后进入录入模式，按下新的组合键即可修改绑定。
4. 如果新组合与已有绑定冲突，界面会显示冲突提示，需先解决冲突才能保存。
5. 点击行尾的重置按钮可恢复单条快捷键的默认值；点击底部「重置全部」恢复所有默认值。

注意事项：

• 快捷键持久化在 SQLite app_settings 表（key = keybindings）。
• 全局快捷键（截图类）修改后立即重新注册到操作系统，无需重启。
• 如果全局快捷键注册失败（被其他应用占用），设置面板会显示警告。

---

#9.6 使用命令面板

命令面板是 SpectrAI 的快速导航中枢，通过 Ctrl+K（macOS 为 Cmd+K）唤起。

1. 按下快捷键，弹出命令面板浮层。
2. 在搜索框输入关键词，支持模糊匹配（如输入「xjh」可匹配「新建会话」）。
3. 命令按 6 个分组排列展示：

1. 使用 ↑ / ↓ 键盘导航，Enter 执行选中命令。
2. 按 Esc 或点击背景关闭面板。

---

#9.7 网络代理配置

配置步骤

1. 打开设置面板 → 网络 分类 → 网络代理 子 Tab。
2. 选择代理类型：none（直连）、http、socks5。
3. 填写代理主机和端口。如需认证，展开填写用户名和密码。
4. 点击保存，代理立即生效。

典型配置示例

代理影响范围

• OpenAI 兼容 / HTTP 类 Provider：走应用层 HTTP 代理设置。
• CLI 类 Provider（Claude Code 等）：继承系统环境变量 HTTP_PROXY / HTTPS_PROXY，不受应用代理设置影响。
• MCP 服务器连接：由各 MCP 服务器自身决定，通常继承系统环境变量。

---

#9.8 数据存储与迁移

默认数据目录

开发模式下数据存储在 <userData>/dev/ 子目录，与生产数据隔离。

数据内容

• spectrai.db：SQLite 数据库，存储会话、设置、Provider 配置、会话历史等所有核心数据。
• skills/：已安装的 Skill 文件。
• attachments/：会话附件。
• logs/：应用日志。

导出会话

在会话列表中右键会话 → 导出，支持 Markdown 和 JSON 两种格式。如已配置 obsidianVaultPath，还可一键导出到 Obsidian Vault。

数据安全

• SpectrAI 使用本地 SQLite 存储，所有数据保留在用户本机，不自动上传云端。
• API Key 使用加密存储。
• 卸载应用时数据目录不会自动删除，如需清理需手动删除上述目录。

---

#9.9 高级用法

直接编辑 settings.json

通过 update-config Skill 可以直接修改 ~/.claude/settings.json，适用于：

• 配置权限白名单（如允许特定 npm 命令）
• 设置环境变量
• 配置 Hooks（事件驱动的自动化命令）

Hooks 系统

Hooks 是在特定事件（如工具调用前后、会话开始/结束）自动执行的 Shell 命令。配置入口：设置 → 自动化 → Hooks。Hooks 由 SpectrAI 运行时执行，不依赖 AI 记忆。

命令行参数

SpectrAI 支持从命令行启动并传递参数：

spectrai.exe --open-dir="C:\projects\myapp"

---

#9.10 常见问题

Q：设置修改后没有生效？ A：大部分设置修改后即时生效。少数设置（如 autoLaunch、全局快捷键）需要重新注册，通常也是自动完成的。如果仍不生效，尝试重启应用。

Q：快捷键与其他应用冲突怎么办？ A：打开设置 → 快捷键，修改冲突的组合键。全局快捷键（截图类）如果被其他应用占用，注册会失败并显示警告，此时需要更换为不冲突的组合。

Q：代理设置后 Claude Code 仍无法连接？ A：CLI 类 Provider 不走应用代理设置，而是继承系统环境变量 HTTP_PROXY / HTTPS_PROXY。请在系统层设置代理，或在终端中手动 export HTTP_PROXY=http://127.0.0.1:7890 后重启 SpectrAI。

Q：命令面板搜不到某个命令？ A：命令面板的命令列表是动态生成的。确认：① 对应 Skill / MCP 服务器已安装并启用；② 未处于简洁模式（简洁模式会隐藏部分高级功能）。

Q：数据目录占用空间过大？ A：主要占用来源是会话历史和附件。可在会话列表中删除不需要的历史会话，或手动清理 attachments/ 目录。

---

#9.11 相关章节

• 第 7 章 远程控制：远程控制相关设置（绑定设备、推送偏好、Bot 凭证）详见第 7 章。
• 第 8 章 AI Provider：Provider 的添加、配置、模型路由策略详见第 8 章。
• 第 10 章 FAQ：更多设置相关的常见问题汇总。

SpectrAI 操作手册 v0.8.15 · 桌面端 · 第 10 章

#概述

本章汇总官网 FAQ、已知 Bug 页、反馈页与社区高频问题，优先解决“能不能继续用”和“该去哪里报错”这两件事。排查顺序建议是：先看现象，再核对设置，最后决定是本地修复、降级处理还是提交 Bug。

官网原始 FAQ 以安装、登录、会话、Provider、远程控制、性能、数据、升级 8 组为主。本章额外拆出“MCP 与工具”和“多 Agent 协同”，方便定位桌面端特有问题。

⚠️ 注意

遇到无法启动、数据库异常或疑似数据丢失时，先备份数据目录与日志，再做清理或回退。

#核心概念

诊断信息至少包含三项：版本号、报错码、日志。版本号看“设置 → 关于”，报错码优先记录 401、404、429 或启动错误文案，日志优先提供 main.log 片段。

降级处理遵循“先轻后重”：先清理缓存文件并重启，再回退旧版本，最后才备份并重建数据库。

联系支持适用于可稳定复现、升级后新增、或已影响数据安全的问题。提交时附“环境 + 重现步骤 + 期望 vs 实际 + 日志片段”。

#操作步骤：定位日志与上报 Bug

1. 打开主界面菜单“帮助 → 打开日志目录”，优先使用应用内入口定位日志。

1. 找到日志文件 main.log。
   • Windows：默认先检查 %APPDATA%\SpectrAI\logs\。
   • macOS：默认先检查 ~/Library/Logs/SpectrAI/。
   • 如果已经在 第 9 章 设置与快捷键 改过数据目录，以应用内实际打开的位置为准。

1. 打开“设置 → 关于”，记录完整版本号，并截取报错弹窗或异常界面。

1. 打开反馈页 https://claudeops.wbdao.cn/feedback.php，把问题类型、版本号和联系方式填写完整。

1. 按“环境 + 重现步骤 + 期望 vs 实际 + 日志片段”的模板提交；日志只贴关键片段。

#详细配置

本章不涉及独立设置项，相关配置见 第 9 章 设置与快捷键。

#常见问题

以下问答按安装、登录、会话、Provider 与 API、MCP 与工具、多 Agent 协同、远程控制、性能与稳定、数据与升级分组排列。

安装：为什么 macOS 提示“无法打开应用”？

如果应用来自官方安装包，“已损坏”通常是 macOS 的安全拦截，不一定真是文件坏了。

按这个顺序处理：

1. 先确认来源。
   只处理官方安装包。
2. 移除隔离属性。
   打开终端执行：

sudo xattr -rd com.apple.quarantine /Applications/SpectrAI.app

如果应用不在这个路径，把命令里的路径换成实际路径。

1. 再试一次”右键打开”。
   先不要反复双击，右键应用选择”打开”；如果系统弹出确认，再允许一次。
2. 还被拦截时，到系统设置放行。
   打开”系统设置 → 隐私与安全性”，找到刚才被拦截的应用并点”仍要打开”。
3. 还提示损坏，再重新下载。
   这时再怀疑安装包不完整会更合理。

安装：为什么 Windows 会弹出 SmartScreen 警告？

先点“更多信息”核对发布者和版本，再决定是否继续。来源不是官网时不要放行。

安装：安装目录权限不足或卸载后仍有残留怎么办？

改用当前用户可写目录，或以管理员身份运行安装器。彻底清理前先备份用户数据目录。

登录：为什么收不到邮箱验证码或重置码失效？

先查垃圾邮件和邮箱拦截，再等 1 到 3 分钟后重发。重置流程以最后一次验证码为准，旧码会失效。

登录：如何退出登录或申请注销？

退出登录走“设置 → 账号”。需要停用或注销时，通过反馈页提交申请并附注册邮箱。

会话：会话长时间无响应怎么办？

先看顶部状态、终端输出和 Butler 提示；等待权限或人工确认不算卡死。几分钟无新增输出时结束当前轮并重试。

会话：编辑消息后上下文丢失或恢复后紊乱怎么办？

这是旧版本高频问题，v0.8.15 已修复主要场景。先升级并重启，再避免在同一轮未结束时连续改历史消息。

会话：为什么搜索不到旧会话，或长会话越来越卡？

先清空关键词、标签和收藏筛选。旧版本检索与收藏分页有修复项；长会话建议整理结论后新开会话继续。

Provider：为什么会报 401 API Key 验证失败？

401 多半是 Key 无效、过期，或 Base URL 与 Key 不匹配。回到“设置 → Provider 与 API”重新粘贴并检查接口地址。

Provider：为什么会报 404 模型不存在？

模型名写错、区域未开通或当前接口不提供该模型都会触发 404。用模型列表或 Test 按钮先验证一次。

Provider：为什么会报 429 限额或频率超限？

先减少并发、超大附件和重复重试，再去服务商控制台看额度。内置 Provider 用量看“设置 → 账号”。

Provider：中国大陆访问外部 Provider 被屏蔽怎么办？

先配置代理再测试连接。代理入口和系统代理联动见 第 9 章 设置与快捷键。

Provider：CLI Provider 为什么启动失败？

先确认 CLI 已安装、已登录，且 node -v 满足要求；部分 CLI Provider 需要 Node.js v20+。多版本 Node.js 并存时优先修正 PATH。

Provider：内置 Provider 用完了怎么办？

查看“设置 → 账号”中的订阅与额度，再选择等待重置、升级订阅或切到自备 API 的 Provider。

Provider：为什么 Test 按钮一直转圈？

先保存配置并重新打开设置页测试。若最近改过 Provider，升级到 v0.8.15 后重启，可避开旧缓存问题。

MCP：为什么 MCP 服务器启动失败？

v0.8.15 起内置 MCP 通常不再依赖系统 Node.js。第三方 npx/npm MCP 仍可能受拉包慢、参数错或代理缺失影响。

工具：为什么工具调用超时或结果不显示？

先区分是“没启动”还是“执行慢”。前者看 MCP 状态，后者增加超时、减少大输入；恢复旧会话后异常时先升级到 v0.8.15。

Skill：为什么 Skill 安装失败？

先核对 GitHub 地址、子目录或 npm 包名，再看安装日志是否卡在下载依赖。国内网络下代理没配好时最常见。

多 Agent：Mission 为什么卡在某个阶段？

先看阶段条是否停在“头脑风暴”“任务拆解”或等待审批。Mission 模式部分阶段本来就要求人工确认。

多 Agent：子 Agent 失败后如何重试？

在 Team 或 Mission 面板里直接重试失败的子任务，不要整段重复发提示词。重试前先补齐缺失的权限、文件或 Provider 配置。

多 Agent：为什么不能追加指令，或 Teams 评分看起来异常？

当前轮执行、等工具权限或等子 Agent 返回时，Supervisor 模式会临时禁用追加输入。评分用于同轮相对比较；显示异常先升级并重新打开会话。

远程控制：手机扫码后为什么没有反应？

先确认“设置 → Cloud Relay”已连接，且二维码对应机器在线。管理员刚开通权限时，先到“设置 → 账号 → 账号管理”刷新状态。

远程控制：为什么 Telegram 推送收不到？

先主动给 Bot 发一条消息，再检查 Token、授权用户、事件开关和代理。国内网络未配代理时常会直接失败。

远程控制：为什么飞书验签或回调一直失败？

当前桌面端优先使用飞书机器人长连接模式，重点核对 App ID、App Secret、Encrypt Key 和 open_id 白名单。按旧 webhook 文档配置时请整套重配。

远程控制：为什么移动端推送会延迟？

保持桌面端在线，并检查 Cloud Relay 和手机网络。大量并发通知、弱网或系统省电都会放大延迟。

性能：应用启动很慢怎么办？

升级后的首次启动可能在做迁移、索引恢复或 Provider 初始化。若每次都慢，查看 main.log 是否在持续重试。

性能：内存占用高或文件树卡顿怎么办？

常见原因是超长会话、多个 Agent 并发、超大仓库或生成目录过多。结束空闲任务，并尽量只打开当前模块目录。

性能：GPU 占用异常或终端打字延迟怎么办？

先区分是整应用掉帧还是只有终端变慢。前者重启并更新显卡驱动，后者先关高频日志、实时预览和空闲远程面板。

数据：怀疑数据丢失时先查哪里？

先不要继续新建空会话。优先检查当前数据目录、旧 ClaudeOps 数据目录、claudeops.db 是否还在，以及日志里的迁移或数据库错误。

升级：升级后旧会话为什么不见了？

SpectrAI 会自动迁移旧 ClaudeOps 数据。看到空白列表时，先确认是否切到了新的自定义数据目录，或启动异常后误建了空数据库。

数据：如何跨设备同步，或卸载前保留数据？

当前桌面端以本地数据为主，跨设备请整体备份并迁移数据目录。卸载前至少保留 claudeops.db、attachments、logs 和 skills。

升级：如何退回旧版本或做最小重置？

先备份数据目录再回退版本。若只是启动异常，先删 claudeops.db-wal 和 claudeops.db-shm 重启；仍失败时再备份并移走 claudeops.db 验证。

#联系研发

提交前先准备版本号、截图、重现步骤和 main.log 关键片段，再选择入口：

• 反馈页：https://claudeops.wbdao.cn/feedback.php
• 已知 Bug 列表：https://claudeops.wbdao.cn/bugs.php
• 官方 FAQ：https://claudeops.wbdao.cn/faq.php
• 社区交流：以官网发布页公布的微信交流群为准
• 紧急通道：应用内“问题反馈”按钮

反馈模板建议固定为：“环境、重现步骤、期望结果、实际结果、日志片段、是否可稳定复现”。

#相关章节

• 第 4 章 多 Agent 协同：Butler 自动干预、Mission 模式和 Agent Teams 的基础行为说明。
• 第 5 章 工具与 MCP：MCP、Skill 与工具权限的安装和接入入口。
• 第 8 章 Provider 与 API：Provider 接入、API Key、Test 按钮与常见状态码排查。
• 第 9 章 设置与快捷键：代理、日志、数据目录、账号与远程控制设置的统一入口。