User Manual · v1.0.4

光谱AI 操作手册

覆盖账号、会话、多 Agent 协同、Provider 接入、远程控制、设置与故障排查。本手册仅面向桌面端(Windows / macOS);Web、移动端、小程序、官网展示站不在本册范围。

CH09

第 9 章 · SpectrAI 桌面端 v1.0.4设置与快捷键

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

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

---

9.1 概述

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

层级存储位置生效范围
应用设置SQLite app_settings 表全局(所有会话共享)
会话级设置每个会话独立保存仅当前会话(如 Provider、权限模式、Mode)
本地设置文件~/.claude/settings.json全局;由 update-config Skill 管理

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

---

9.2 打开设置面板

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

设置面板 8 大分类:

分类子 Tab
常规基本 · 外观 · 语音唤醒与播报 · 快捷键 · 内置浏览器 · 录音助手
网络与连接网络与语音 · 局域网访问 · Cloud Relay
账号账号管理 · 升级方案 · 推广者计划
AI 模型模型管理 · 模型分配 · 模型商店 · 子 Agent 调度池 · 生图 · 生视频
扩展与工具工作区 · 技能 · 内置技能 · MCP 服务器 · 快捷操作 · 自定义提示词
自动化定时任务 · Event Hooks · AI 管家 · 记忆管理
远程控制机器人配置(Telegram / 飞书 / 企微)
系统数据存储 · 日志 · 反馈

自动化 → 记忆管理里的「热记忆硬注入」默认开启(仅 user + 已确认 feedback,最多 8 条 / 2000 字);关闭后新会话不再硬注入。同页的「自动召回记忆」默认关闭,开启后在命中偏好/规则词或上下文压缩后把少量相关记忆作为 hint 注入当前轮。

💡 提示

新用户默认进入简洁模式,仅显示常规、账号、AI 模型、扩展与工具四个分类;切换到专业模式(或点击页面顶部「完整设置」)可查看全部分类,该偏好独立持久化。

设置项轻重分档

每个子 Tab 内的设置项按三档呈现,越靠下越少动:

  • 常用项:直接平铺在页面上,开箱可调。
  • 高级设置区:默认折叠,放需要理解概念或极少变动的项,点击展开后仍是标准设置行。
  • 危险操作区:不可逆或涉及数据/账号的操作(如迁移数据目录、清理),用警示色单独分区,执行前统一弹出二次确认。

---

9.3 设置项分组详表

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

9.3.1 常规

字段名类型默认值作用入口位置
autoLaunchbooleanfalse开机时自动启动 SpectrAI常规 → 基本 → 开机自启
autoWorktreebooleanfalse任务看板新建任务时默认启用 Git Worktree 隔离常规 → 基本 → Git Worktree 隔离
alwaysReplyInChinesebooleanfalseAI 默认使用中文回复(不影响代码、命令、路径等系统输出)常规 → 基本 → 回复语言
promptFollowUiLanguagebooleanfalse注入的系统提示词跟随界面语言(默认关,一律用中文原版);同时决定 AI 重命名标题的语言与翻译按钮显示常规 → 基本 → 注入提示词语言
useCtrlEnterbooleanfalse使用 Ctrl+Enter 发送消息(关闭时 Enter 直接发送,Shift+Enter 换行)常规 → 基本 → 输入
notificationEnabledbooleantrue主会话任务完成时发送操作系统通知(子 Agent 不触发)常规 → 基本 → 系统通知
dailyReportPushEnabledbooleanfalse每日 18:00 推送 AI 工作日报常规 → 基本 → 系统通知
showStatusHintsbooleantrue显示 AI 状态提示(心跳提示、自动恢复提示等)常规 → 基本 → 显示
collapseProcessMessagesbooleantrue每轮完成后自动折叠中间思考和工具调用过程,只显示最终总结常规 → 基本 → 显示
showLiveToolPreviewbooleanfalse折叠态工具组显示一行「实时输出」弱预览常规 → 基本 → 显示
showAssistantAvatarbooleanfalse对话区显示 AI 头像(仅在本轮最终回复旁显示一次)常规 → 基本 → 显示
showAssistantBubblebooleanfalse主对话 AI 正文显示灰色气泡框(默认无框 Codex 式时间线)常规 → 基本 → 显示 AI 回复气泡
showMessageNavRailbooleantrue对话区左侧显示用户消息刻度,悬停预览、点击跳转常规 → 基本 → 消息快速跳转轨
quickReplyEnabledbooleanfalseAI 提问时自动生成「需要您的选择」快捷选项按钮(桌面端与手机端同步)常规 → 基本 → 推荐选项
askUserQuestionEnabledbooleantrue允许模型弹出 AskUserQuestion 选项卡片并等待选择;关闭后改用普通文字提问、不阻塞本轮(仅作用于自建 OpenAI 通道)常规 → 基本 → 弹卡片提问
showAutoCompactNotificationbooleanfalse显示上下文自动压缩提示常规 → 基本 → 显示
obsidianVaultPathstring''(空)Obsidian Vault 目录路径,用于导出会话笔记常规 → 基本 → Obsidian 集成

9.3.2 外观

字段名类型默认值作用入口位置
fontSizenumber14会话对话区字体大小(px),范围 10–24外观 → 字体大小
fileIconThemestring'material'文件图标主题,可选 minimal / material / seti外观 → 文件图标
新的分屏布局booleantrue左侧入口在主区以标签方式打开,可拖拽标签分屏;关闭则回到整屏切换工作区的老行为,详见 第 2 章常规 → 外观 → 新的分屏布局
颜色主题(Theme)通过 uiStore'light'整体配色方案,参见下表外观 → 主题选择

内置颜色主题(12 款):

主题 ID名称类型
darkGitHub Dark深色
lightGitHub Light浅色
solarized-darkSolarized Dark深色
solarized-lightSolarized Light浅色
nordNord深色
one-dark-proOne Dark Pro深色
draculaDracula深色
monokaiMonokai深色
tokyo-nightTokyo Night深色
catppuccinCatppuccin Mocha深色
ayu-lightAyu Light浅色
gruvboxGruvbox Dark深色

9.3.3 AI Provider(简版)

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

字段名类型默认值作用入口位置
summaryProviderId / summaryModelIdstring''(空)上下文摘要压缩使用的全局 HTTP Provider 与具体模型;留空使用当前会话 ProviderAI 模型 → 模型分配
remoteControlProviderId / remoteControlModelIdstring''(空)机器人 / 远程控制专用的全局 HTTP Provider 与模型AI 模型 → 模型分配
voiceTranscriptionProviderIdstring''(空)语音转文字专用 Provider ID;为空时自动选择AI 模型 → 模型分配
voicePolishProviderId / voicePolishModelIdstring''(空)语音转写后 LLM 智能整理所用的 Provider 与模型;留空只输出 ASR 原文AI 模型 → 模型分配
translateProviderId / translateModelIdstring''(空)快捷翻译(AI 模型引擎)使用的 Provider 与模型;留空复用远程控制模型AI 模型 → 模型分配
aiInlineCompletionEnabledbooleanfalse代码预览编辑器的 Copilot 式灰字行内补全;关闭时零 LLM 请求AI 模型 → 模型分配
aiInlineCompletionProviderId / aiInlineCompletionModelIdstring''(空)行内补全使用的 Provider 与模型;为空时不发请求AI 模型 → 模型分配
backgroundAiAnalysisEnabledbooleantrue后台 AI 自动分析(目标锚点抽取 / 会话记忆摘要 / 漂移检测 / 压缩摘要);关闭可省下后台 LLM 费用AI 模型 → 模型分配

9.3.4 语音转写

字段名类型默认值作用入口位置
voiceTranscriptionModeVoiceTranscriptionMode'openai'转写服务类型:openai / volcengine(火山引擎)/ minimax / dashscope(通义)/ local-whisper常规 → 语音
voiceTranscriptionConfig.modestring'openai'独立转写配置的服务类型(与 AI Provider 解耦)常规 → 语音
voiceTranscriptionConfig.apiKeystring''(空)转写服务的 API Key 或凭证(火山引擎格式:AppID:AccessToken)常规 → 语音
voiceTranscriptionConfig.apiBaseUrlstring''(空)API Base URL(OpenAI 兼容 / DashScope 可配;其他使用固定端点)常规 → 语音
voiceTranscriptionConfig.modelstring''(空)模型名称,留空使用默认值常规 → 语音

9.3.5 语音唤醒与播报(小光)

⚠️ 注意

语音唤醒默认关闭,需在此页显式开启后才会常驻监听麦克风。

字段名类型默认值作用入口位置
voice.wakeWord.enabledbooleanfalse是否开启唤醒词常驻监听(说出唤醒词唤起小光)常规 → 语音唤醒与播报
voice.wakeWord.keywordsarray['小光']自定义唤醒词常规 → 语音唤醒与播报
voice.wakeWord.sensitivitynumber0.5唤醒灵敏度(0–1,越高越易触发)常规 → 语音唤醒与播报
voice.wakeWord.inAppShortcutstring'Ctrl+Shift+.'应用内手动唤起小光的快捷键(不注册系统全局热键)常规 → 语音唤醒与播报
voice.wakeWord.releaseMicWhileListeningbooleanfalse聆听期间释放麦克风占用常规 → 语音唤醒与播报
voice.tts.enabledbooleantrue是否开启语音播报(TTS)常规 → 语音唤醒与播报
voice.tts.speednumber1.0播报语速倍率常规 → 语音唤醒与播报
voice.hub.ackSoundbooleantrue唤醒时播放提示音常规 → 语音唤醒与播报
voice.hub.speakSummaryOnlybooleantrue只播报最终总结,不逐句念中间过程常规 → 语音唤醒与播报
assistant.desktop.providerIdstring''(空)桌面助手(小光 / 小黑)对话所用的 Provider ID常规 → 语音唤醒与播报

9.3.6 内置浏览器

字段名类型默认值作用入口位置
网页链接打开方式enum: 内置 / 系统默认内置浏览器点击软件内网页链接时用内置浏览器还是系统默认浏览器(切换即时生效)常规 → 内置浏览器
CDP(AI 可操作)通道boolean由 SPECTRAI_BROWSER_CDP 环境变量控制允许 SpectrAI Claw 等 AI 通过本机调试端口操作内置浏览器;修改后需重启生效常规 → 内置浏览器
会话隔离浏览器上下文booleanfalse(关,所有标签共享登录态)开启后各 AI 会话打开的标签使用独立 cookie / 存储分区常规 → 内置浏览器
💡 提示

内置浏览器可从左侧活动栏的「浏览器」入口或命令面板打开;调试端口每次启动随机挑选,避免被其他程序误连。

9.3.7 其他章节维护的设置项

下列设置项的完整说明写在对应功能章节,这里只列字段、默认值与入口,便于统一查找。

字段名类型默认值作用入口位置
autoWorktreebooleanfalse新建会话默认开启 Git Worktree 隔离,见 第 2 章常规 → 基本 → Git Worktree 隔离
directoryAccessModeenum: workspace/extended/full"extended"会话可访问的目录范围(仅工作区 / 用户目录 / 完全访问),新建时的选择会成为下次默认,见 第 3 章新建会话底栏 → 目录权限
injectMemoriesToSessionsbooleantrue热记忆硬注入到新会话,见 第 5 章自动化 → 记忆管理
autoRecallMemoriesEnabledbooleanfalse按当前消息自动召回相关记忆作为提示,见 第 5 章自动化 → 记忆管理
remote.portnumber9800局域网远程访问端口,见 第 7 章网络与连接 → 局域网访问
子 Agent 调度池object空(不限制)Supervisor / 组队任务派发子 Agent 时可用的 Provider 与模型白名单,见 第 4 章AI 模型 → 子 Agent 调度池

9.3.8 MCP 与扩展

字段名类型默认值作用入口位置
mcpNodeVersionstring''(空)MCP 服务器使用的 Node.js 版本(nvm 版本号如 '22.12.0');留空使用系统默认扩展 → MCP
smitheryApiKeystring''(空)Smithery API Key,用于 MCP 市场中安装和管理服务器扩展 → MCP
imagePromptLibrary.mode`'off' \'on-demand'`'on-demand'GPT 生图提示词库工具模式:关闭 / 按需调用
imageGeneration.apiBaseUrlstring''(空)对话生图独立通道 URL;留空回退会话中转AI 模型 → 生图
imageGeneration.apiKeystring''(空)对话生图独立通道 KeyAI 模型 → 生图
imageGeneration.modelstring''(空,运行时默认 gpt-image-2)对话生图模型AI 模型 → 生图
videoGeneration.apiBaseUrlstring''(空)对话生视频独立通道 URL(异步视频任务 API);留空回退会话中转AI 模型 → 生视频
videoGeneration.apiKeystring''(空)对话生视频独立通道 KeyAI 模型 → 生视频
videoGeneration.modelstring''(空,运行时默认 sora-2)对话生视频模型AI 模型 → 生视频
videoGeneration.protocol`'auto' \'openai' \'seedance' \'veo' \

9.3.9 网络与代理

字段名类型默认值作用入口位置
proxyType`'none' \'http' \'socks5'`'none'
proxyHoststring''(空)代理主机地址(如 127.0.0.1)网络 → 代理主机
proxyPortstring''(空)代理端口(如 7890)网络 → 代理端口
proxyUsernamestring''(空)代理认证用户名(可选)网络 → 代理认证
proxyPasswordstring''(空)代理认证密码(可选)网络 → 代理认证

---

9.4 快捷键全表(全书 SoT)

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

9.4.1 窗口级快捷键

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

快捷键 (Win/Linux)快捷键 (macOS)功能说明
Ctrl+NCmd+N新建会话创建一个新的 AI 会话
Ctrl+Shift+NCmd+Shift+N新建任务会话创建带任务面板的新会话
Ctrl+WCmd+W关闭会话确认后关闭当前选中的活动会话
Ctrl+TabCmd+Tab切换终端循环切换到下一个终端
Ctrl+BCmd+B切换侧边栏显示或隐藏侧边栏
Ctrl+`Cmd+`切换 Shell 面板显示或隐藏内置终端面板
Ctrl+KCmd+K命令面板全局命令面板:会话 / Skill / MCP / 模型 / 工作区 / 设置
Ctrl+FCmd+F搜索打开搜索框
Ctrl+PCmd+P快速打开快速打开文件或命令(可选功能,需启用)
Ctrl+Shift+FCmd+Shift+F文件内搜索在工作区文件中搜索内容(可选功能)
Ctrl+Shift+HCmd+Shift+H文件内替换在工作区文件中搜索并替换(可选功能)
Ctrl+Shift+.Cmd+Shift+.唤起小光手动唤起语音助手小光(仅主窗口生效,不注册系统全局热键)

9.4.2 全局快捷键

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

快捷键 (Win/Linux)快捷键 (macOS)功能说明
Ctrl+Shift+SCmd+Shift+S截图标注框选截图并标注(微信风格),截图自动复制到剪贴板
Ctrl+Alt+SCmd+Alt+S窗口截图截取应用窗口并保存到剪贴板

9.4.3 输入框快捷键

快捷键功能条件
Enter发送消息useCtrlEnter 为 false(默认)
Ctrl+Enter / Cmd+Enter发送消息useCtrlEnter 为 true
Shift+Enter换行始终生效
Esc关闭命令面板/弹窗弹窗或面板处于打开状态时
↑ / ↓导航选项命令面板打开时

---

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 个分组排列展示:
分组说明示例
工作区切换到不同工作区视图分析、项目、对话、设计、Teams、工作流
会话切换到已有会话按会话名称搜索
模型 / Provider切换当前 Provider 或模型Claude、GPT、Gemini 等
Skill调用已安装的 Skill按 Skill 名称搜索
MCP 工具调用已连接的 MCP 工具按工具名称搜索
设置直达设置子页面常规、外观、网络代理、AI Providers 等
  1. 使用 ↑ / ↓ 键盘导航,Enter 执行选中命令。
  2. 按 Esc 或点击背景关闭面板。

---

9.7 网络代理配置

配置步骤

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

典型配置示例

场景代理类型主机端口
Clash 默认配置http127.0.0.17890
V2Ray 默认配置socks5127.0.0.110808
公司 HTTP 代理httpproxy.corp.com8080

代理影响范围

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

---

9.8 数据存储与迁移

默认数据目录

平台路径
Windows%APPDATA%\spectrai\
macOS~/Library/Application Support/spectrai/

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

数据内容

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

导出会话

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

基础配置加密导出 / 导入

用于跨机器迁移「基础配置」,导出文件后缀为 .spectrai-config.json。入口:系统 → 数据存储。导出时必须设置密码,文件用 AES-256-GCM 加密(密码经 scrypt 派生密钥),导入时输入同一密码解密。

导出覆盖以下 7 类配置(均剔除内置项):

  • 自定义 AI Provider(含 API Key、Base URL、模型等运行时字段)
  • 自定义 MCP 服务器
  • 自定义 Skill
  • Hooks
  • 快捷操作(Quick Actions)
  • 自定义系统提示词
  • 提示词插入模板
⚠️ 注意

会话 / 消息 / 团队 / 管家 / 任务执行等数据以及应用设置(app_settings)不在导出范围;导入按主键 ID 覆盖同名条目。加密文件解密失败会统一提示「密码错误或文件损坏」。

数据安全

  • 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"

应用更新与新版本就绪浮层

入口:常规 → 基本 → 应用更新,可查看当前版本、检查更新、下载更新或前往官网下载。新版本下载完成后,界面底部会出现「新版本就绪」浮层,提示 v{版本号} 已下载,重启后生效,其中可点击「更新日志」查看更新说明,或点击「重启升级」一键重启并安装;也可点击「关闭本次提示」暂时忽略。

---

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:更多设置相关的常见问题汇总。