快速开始

这份指南带你从零跑通 Spark Work：装好应用、接入一个可用的模型服务、确认助手配置， 然后完成第一个真实任务。全程不需要写代码，但你需要准备下面任意一种模型来源： 第三方模型的 API Key、Spark 账号，或本机已经登录好的 Claude Code / Codex。

1. 下载与安装

从 下载页 取安装包。下载页按当前系统自动推荐版本， 当前提供的产物是三条：

根据你的系统选择对应条目即可：

• macOS：打开 DMG，把应用拖进「应用程序」。应用在 Finder 与程序坞里显示的 名字是 SparkWork（可执行文件与安装包名仍为 Spark Agent，属正常现象）。 首次打开如果被系统拦下，去「系统设置 → 隐私与安全性」点「仍要打开」。
• Windows：运行 .exe。安装向导会让你选择安装位置， 应用文件固定落在所选目录下的 spark-worker 子目录里；卸载项显示为SparkWork <版本号>。安装目录可随时在向导里改，不要手动移动子目录。

首次启动会发生什么：应用会打开「新手引导」，依次问你 「你想先做些什么」→「选择你的 AI 模型」→ 连接测试 → 起一个助手 → 发送第一句任务。 引导页上有「稍后再说」，任何时候都能跳过； 之后想重来，去 设置 → 通用 → 新手引导 点「重新打开」。

可选功能组件：Codex 本地运行时、离线 Office 预览、本地深度处理（深度视频）、 FFmpeg、Chromium、语音输入资源都不在基础安装包里，按需下载。 入口在 设置 → 完整性 → 可选功能组件，未安装时对应功能会给出明确的安装提示， 也可以在功能首次使用时按提示安装。

2. 接入模型服务

有两条路，任选一条：

1. 跟着新手引导走：在「选择你的 AI 模型」页选 「第三方模型」（推荐，仅需 API Key）、「Spark 账号」（登录即用，无需 Key） 或「本机 AI 工具」（复用本机已登录的 Claude Code / Codex）。
2. 手动配置：点侧边栏的 「模型」 页 （不是「设置」里的子项），点「添加 Provider」。

手动添加 Provider 时，抽屉里的字段就是下面这些：

引导页的表单更短，只有服务商、密钥、模型 ID（可点「获取模型」）、API URL 四项， 底部按钮是「测试并保存」——按下就会同时创建 Provider 并跑一次连接测试。

用本地模型：走「自定义 + OpenAI 格式 + BaseURL」这条路。 Ollama 的 OpenAI 兼容入口通常是 http://localhost:11434/v1， 模型 ID 填你本地 ollama list 里的名字（例如 qwen3:14b）。 仓库里保留了 Ollama 模板但当前默认注释掉，因此界面上不会直接出现这个预设。

密钥存在哪：所有 API Key 都走统一的凭据存储（keytar）， macOS 上集中保存为一个由系统加密能力保护的文件credential-vault-v1.enc（权限 0600），Windows 上落到系统凭据管理器。 密钥不会写进数据库明文，也不会出现在项目配置文件里。

3. 认识与创建 Agent

开箱就有两个内置助手，不需要你配置也能用：

• Spark助手（稳定 ID platform-manager-agent）：默认助手， 同时负责平台管理（Skills / MCP / Provider / 工作流 / 看板等）和全栈开发任务。
• 画布助手（canvas-assistant-agent）：只在无限画布的 Agent 面板里用，熟悉节点、分组、影视流水线和多媒体生成。

新手引导里选完模型后，会按你选的用途建一个属于你的助手，名字形如 「我的通用助手 / 我的文档助手 / 我的工作助理 / 我的开发助手」。 想改或新建，去侧边栏的 「助手」 页，点进编辑抽屉。抽屉分六个区：

• 基本信息：名称、状态（启用 / 停用）、描述、是否为默认 Agent。
• 执行配置：Provider（可选「跟随会话」）、执行器（Claude SDK / Codex / Spark）、 默认模型、权限、推理强度、推理 Token 预算（仅 Claude SDK）、工作流， 以及这个 Agent 的系统提示词。
• Skills：按需加载哪些工作说明书。
• MCP 服务：挂在它名下的 MCP 服务器。
• 规则：这个 Agent 必须遵守的项目约束。
• Hook：Agent 专属的事件钩子覆盖。

权限模式不是一个固定列表，它跟着执行器走：

推理强度的可选值是 minimal、low、medium、high、xhigh、max； 新手引导创建的助手统一用 medium。

简单记法：先挑模型和执行器，再决定它能用哪些能力，最后收紧权限。 不确定时保持默认即可——「请求批准」下每个有副作用的工具调用都会先弹审批卡。

4. 跑通第一个任务

能跑通的最小配置只需要两样：一个可用的对话模型 Provider，一个启用的 Agent。

1. 点侧边栏的「新建任务」按钮，或在空会话首页直接输入。
2. 用一句自然语言描述目标，例如「把这个目录里的 README 整理成一份 300 字的产品介绍」。 需要的话把文件、目录、图片拖进输入框或粘贴进来。
3. 发送后，Agent 会在会话里展示执行过程：工具调用卡片（带参数与耗时）、 代码 diff、图表、生成的文件都会内联出现。
4. 涉及写文件、跑命令、访问网络时，输入框上方会弹出审批卡， 显示工具名、参数摘要和风险等级（低 / 中 / 高），四个按钮是 「拒绝」「会话拒绝」「会话允许」「允许」。
5. 想看细节就打开右侧面板：终端、代码、浏览器、审查、计划、侧聊 都可以和对话并排。

几个立刻用得上的输入区快捷键：

• Enter 发送，Shift+Enter 换行。
• Shift+Tab 切换本次会话的权限模式。
• Agent 忙的时候继续输入会自动进入队列，可拖动排序、编辑、单条立即执行。
• / 打开内置命令与自定义命令列表。
• Ctrl+Shift+D（macOS 为 ⌃⇧D）开关语音输入，实时转写追加到草稿。

任务跑歪了不用重来：右侧 会话检查器 里有「代码还原点」区块 （仅 Git 仓库可用），点「打开时间线」后开启记录，之后点「回到这一步」 就能把工作区文件还原到该轮之前。跑通一个真实任务之后， 再读 代码开发、无限画布、Agent 工作流 会顺很多。

5. Spark CLI（可选）

桌面应用已经内置了完整的 spark 引擎（以 SDK 形式在进程内运行）， 日常使用不需要装任何命令行工具。只有你想在终端里用 spark 命令和 TUI 时， 才需要单独装 CLI。

安装前提是 Node.js >=22.14.0 <23。三条等价路径选一条：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/alexanderizh/spark-agent/spark-cli-releases/install.sh | sh

# Windows PowerShell
irm https://raw.githubusercontent.com/alexanderizh/spark-agent/spark-cli-releases/install.ps1 | iex

# 或者用 npm 全局安装
npm install -g @spark/agent

# 已经有一份包（克隆的仓库 / 解压的 tarball）：把启动器链接到 ~/.spark/bin
spark install

装完之后先验环境，再看当前状态：

spark --version          # 版本
spark doctor             # PATH 上的 spark、版本漂移、Node 版本、SparkWork bridge 状态
spark update --check     # 只检查有没有新版本
spark update             # 事务式自更新，失败自动回滚
spark login              # 登录 Spark 账号（logout / whoami 配套）
spark sessions           # 列出当前目录的历史会话
spark --continue         # 继续当前目录最近一次会话

CLI 与桌面应用共用 ~/.spark 数据根，因此两边能看到同一批配置。 桌面应用运行时会在 ~/.spark/hosts/sparkwork/ 下写一份bridge-<实例 id>.json 描述文件（含本机回环地址与一次性 token）， CLI 启动时据此把桌面端已配置的渠道列进模型选择器；桌面退出后这些描述会变成 「陈旧 bridge」并被自动忽略，spark doctor 会同时报告已连接状态与陈旧描述数量。

交互式 TUI 里常用的是这些斜杠命令：

提示：bypass（完全访问）在 TUI 里必须经过选择器并二次回车确认， 单键循环不会碰到它；通过 --permission-mode bypass 启动则是显式选择。

6. 常见问题排查

• 模型调用失败：先去「模型」页点「测试连接」，拿到的是服务商真实响应。 401 / 403 一般是 Key 不对或没有该模型权限，404 多数是 BaseURL 或模型 ID 写错， 429 是限流。测试连接只对对话模型显示。
• 点发送没反应：检查当前会话绑定的 Agent 是否被停用， 以及它绑定的 Provider 是否被禁用——两者任一不可用都不会有可用的模型配置。
• AI 一直卡在审批：审批卡在输入框上方，需要你点「允许」或「会话允许」； 按 Esc 等价于拒绝。长时间无响应会自动拒绝并让 Agent 跳过该操作。
• 提示 FFmpeg / Codex / Office 预览缺失：这些是可选功能组件， 去 设置 → 完整性 安装即可，基础安装包不携带它们。
• 电脑操作无法启动：在 设置 → 电脑操作 里检查 「屏幕录制」和「辅助功能与输入控制」两项授权，再用同一个页面里的诊断功能排查。
• 想回到初始状态重来一遍：设置 → 通用 → 新手引导点「重新打开」。这只会重放引导，不会删除数据。