文档中心

Spark Work 快速开始指南：下载适合你系统的安装包、完成首次启动、接入模型服务、创建第一个 Agent 并完成第一个任务。

在 Spark Work 中做真实的代码开发：打开项目、选择分支、用 Git Worktree 隔离、在终端跑验证、逐文件审查 AI 改动并生成 Pull Request。

Spark Work 中 Agent 的工作机制：默认 Agent、Provider/Model/Skill/Rule 配置、全局已启用 MCP 自动挂载、可真实执行的 Workflow Graph、workflow_run、运行快照与 [Runtime Rules] 段。

Spark Work 团队模式（Team Mode）：Host Agent 把子任务分派给多个 Member Agent，每个 Member 有独立模型/工具/Skills，事件流式展示分派、回复与完成。

Spark Work 无限画布（Infinite Canvas）能力全景：项目管理、节点类型、AI 操作、任务队列、生成结果节点、lineage 边、资产中心、媒体任务路由与持久化。

Spark Work 多媒体 Provider 配置：图片生成 / 编辑、语音合成 / 转写、视频生成 / 图生视频 / 视频编辑的统一能力注册表、平台适配器（APIMart / xAI / 火山 / 百炼 / 可灵 / Hailuo 等）。

Spark Work 图片生成 Provider：图片 API 源与 imageApiType 字段、9 个内置图片预设、spark_image MCP 工具与 spark_media 统一栈的双链路判定、产物输出目录与 7 类渠道的参数归一规则。

Spark Work 自动路由（AutoRouter）完整指南：一个 router = 1 个分流器模型 + N 个按强度（high / balanced / low）配置的执行模型，宿主在轮次级把 provider 与 model 换成选中档位的执行模型。覆盖真实落库形态（provider_profiles 的 provider_type = auto-router）、AutoRouterConfig 全字段与默认值、分流决策的强制 JSON schema、强度粘性与最近两轮消息摘要、五类降级阶段（timeout / http / schema / rule / no_executor）、规则兜底分类器的判定顺序、确定性 4xx 不重试与 429 保留一次重试、引擎不匹配回退，以及界面上的路由决策展示与排查表。

Spark Work 内置联网搜索 spark_search：web_search / fetch_url 工具、免密默认链（Bing / DuckDuckGo / 百度）、keyed 后端（博查 / Tavily / Serper）、配置项与降级策略。

Spark Work 浏览器自动化：Playwright managed MCP 负责网页流程，spark_browser 内置 MCP 提供应用内可见窗口、本地 HTML 调试、console/network 和 profile 登录态。

Spark Work 远程连接（Telegram / 飞书）：连接配置、配对流程、本地 webhook（127.0.0.1:32178）、内置命令（/help /sessions /models 等）、启动项集成。

Spark Work 桌面端自动更新：electron-builder + GitHub Release + 官网版本中心、UpdateService 检查/下载/安装状态、应用内更新入口、stable/beta 通道、Windows / macOS 签名构建。

Spark Work MCP / Skills 体系：内置技能（apps/desktop/resources/skills）、可安装技能目录、自建安装源（artifact，默认路径）与 tarball / GitHub 回退三条安装路径、传输类型与字段校验、OAuth 授权、按需加载与运行时注入。

Spark Work 自定义工具完整指南：Tool Studio 的 http / code / provider-vision 三种适配器与真实字段约束，以及 Tool Package 的 spark-tool.json manifest、五个 runtime.adapter、六条安装来源、受管工程 install/build、OS 行为与 Spark Capability 权限模型、密钥与启用卸载规则。附 11 个 custom_tools_* 与 22 个 tool_packages_* 工具清单和常见坑排查表。

Spark Work 连接器完整指南：先分清「连接器」在代码里的三种含义（扩展中心的插件型连接器、平台管理 MCP 的 github_* 工具、远程连接的 IM 机器人），再详述 plugin.json 完整字段与四类 contribution、source/trust 枚举、github / google / notion / obsidian 四个内置运行时的真实工具清单与能力开关、九个权限与「只有聚合闸门、无逐权限强制」的真实强制力、本地目录导入与默认不可用的市场、凭据只进系统 keystore、运行时的工具如何以 mcp__spark_plugins__<runtime>_<tool> 注入 Agent，以及 GitHub 两套实现的差异与 ConnectorsPanel 未被挂载这一界面缺口。附 20 行排查表。

Spark Work 子应用（Sub-App）完整指南：先分清 V1 单 HTML 与 V2 受管多文件的真实差异，再讲清五个展示面里只有 content / panel / overlay 真有宿主、17 个能力名与权限检查的真实位置、draft/published/archived 状态机（重点：归档在代码里不可逆）、发布对 enabled 的反向影响（V1 自动启用、V2 保持禁用）、版本号递增与「当前生效版本不能删」的保护、应用数据 512 KB 上限与 revision CAS、文件空间与 .sparkapp 分享包的十项导入检查、V2 后台服务与 release pinning 的持久任务，以及 39 个 spark_app_* 工具、19 个 developer_guide 查询主题与 17 条静态诊断。附 18 行排查表。

Spark Work 权限治理：会话权限模式与 Profile 规则的两层判定、审批卡四档与超时行为、Rules 作用域、经典 Hooks 与 Hooks V2、用量账本，以及当前真正可查的审计记录入口。

Spark Work 性能监控与保护完整指南：设置 → 系统 → 性能 的两个独立部分——资源监控（2 秒采样、六类判级指标、按宿主机内存与 CPU 核数换算的三档阈值、正常/警告/严重/危急四档与升级快降级慢的滞回、仅危急档打扰你、压力事件保留 7 天）与派发闸门（全局并发预算、宿主封顶、成员槽下限、成员并发硬顶、嵌套池配额与 15 秒逃生阀、主池 FIFO 与 120 秒超时）。讲清两层提示的区别（性能页内的档位提示条 vs 只在危急档出现的右上角消息弹窗 + 系统通知，含 2026-09-30 从顶部横幅改为消息弹窗的原因），并如实记录当前未接线的部分：压力级别已由装配层灌进闸门，但闸门内只记录档位，提示条文案描述的「按压力限流 / 暂停派发」尚不是真实行为，实际防护是固定的并发闸门加上危急档提醒。附性能页截图、两张架构图、可调项清单、五个区块导读、14 行排查表与 8 条常见问题。

Spark Work 会话与消息流完整指南：先讲清「会话 → 轮次 → 事件」三层模型与 turnId 的作用，再展开消息流的真实链路（submit-turn 与 send-turn 的持久性差异、started 的真实语义、排队时消息气泡为何消失）、队列的两层结构与面板操作（含「拖拽排序重启后丢失」这个真实缺口）、出错暂停与两种恢复方式、过程性断连的轮次内自动重试（Spark 引擎 10 次重试 / 共 11 次尝试的退避与「只按次数终止」、Codex 自带 5 次重连、重放安全边界与「重新尝试」的真实语义）、调度并发（单会话 1 / 全局硬编码 6）。目标与计划部分覆盖 /goal 命令族、验收契约门控的解析规则（success_criteria 缺失即整块作废）、契约卡片、spark-goal-status 块的四种状态映射、五项预算熔断及其「计数依赖进度日志」的真实缺口、计划模式审批与闸门解除。会话级操作部分覆盖消息级操作（悬停栏按钮的真实出现条件、右键菜单、多选、乐观气泡状态机）、编辑最后一轮的先删后发语义、删除的按轮扩大与「浅清理」、会话分叉的轮次级锚点与元数据继承坑、参考会话的 10 条上限、代码还原点的 git 实现，以及历史导入的四个来源路径与四步流程。文末附 20 行排查表。

Spark Work 电脑操作（Computer Use）完整指南：Agent 直接操作真实桌面的能力。先讲清两条架构完全不同的使用路径——原子动作（会话模型自己逐步操作，每个会话一个隐式会话、空闲 5 分钟释放）与委派的 start_task（独立决策循环，各自的任务契约预算不同），再展开权限模型：会话权限层里 fail-closed 的 computer_direct_action / computer_unknown 硬闸，与生产路径上更早生效的自动放行名单的关系，以及 Broker 层「策略只做风险分级、不做内容拦截」的真实边界（evaluate 在所有分支返回 allow，唯一 deny 是 focus_mismatch；任务契约里 allowedApps / allowedDomains / forbiddenActions 等字段没有任何读取点）。执行内核部分覆盖 L0–L4 风险计算与哪些升级规则在生产不可达、十个原子工具与 click 的语义改写、坐标按「模型看到的图」换算、type_text 带 into/submit 会拆成最多三个动作、五个控制工具的真实语义（pause 与 takeover 逐行等价、resume 只有 MCP 路径会重启算子、bind_target 必须先暂停）。底层部分覆盖原生宿主为什么必需、双向签名校验与本地信任旁路、5 字节帧头 stdio 协议与「没有请求级取消，超时即 SIGKILL 宿主」、心跳与每会话一次的重启预算、元素树渲染与 treeVersion 的 stale 语义、以及 macOS 与 Windows 的能力不对等。数据部分覆盖三套尺寸的截图、AES-256-GCM 加密快照库与保留策略（只有证据帧有 24 小时 TTL、整体无磁盘配额）、预览令牌的 5 分钟 TTL 与 turn 边界撤销、17 项凭据类应用黑名单的实际覆盖面。最后是界面可达性（设置页只有授权与诊断、那套设置没有界面、全新安装不会武装紧急停止键）与 10 个 V2 开关里哪 4 个没有任何消费者。文末附 30 行排查表。

SparkWork 凭据与密钥管理完整指南：密钥实际有四种落点（共享 keystore 的 macOS 集中 vault、第二个 keytar 实现 TokenStore、SQLite app_settings 明文、CLI 的 credentials.json），逐层讲清各自的读写路径与保护边界。覆盖 keystore 的常量与五个 API、critical 的 legacyChecked 惰性迁移与 deleteSecret 语义、keystore_ref 列清单与 tool_package_config 的 DB 级互斥约束、ref 命名规则总表、两份同名 maskSecret 的差异、Provider 凭据从表单到真实请求的全链路（空串写库的语义坑、provider:get-api-key 的明文回显与受管 Provider 硬拒、导出会把明文 Key 写盘、测试连接会真的发请求）、平台账号与 MCP OAuth 的 TokenStore 细节（含备份文件被两个命名空间共用导致取消 MCP 授权会删掉登录备份）、三处明文落点（IM 机器人凭据还会明文回显到普通输入框、会话与项目环境变量、MCP config_json）、声明与填值分离的三条面（自定义工具 secretRefs 全生命周期、工具包 secret 环境变量与一次性安全输入、子应用连接槽）、脱敏覆盖面、删除与清理边界、备份导出与账号同步各路径的密钥行为，附 24 行排查表与事实边界。

SparkWork 本地数据、备份与账号同步完整指南：先把数据分成三个根讲清——应用数据在 {userData}（开发实例走兄弟目录 @spark/desktop-dev，由 SPARK_DATA_PROFILE 控制）、跨工作区记忆与看板在 ~/.spark-agent、Spark CLI 另用 ~/.spark。再讲唯一权威存储 spark.db（WAL 与 pragma、101 个迁移与 schema_migrations）与升级安全网：迁移前自动恢复点走 SQLite 在线备份产出单文件快照，保留 2 份 / 14 天，自动回滚的唯一门槛是 createdThisStartup === true；同一个 backups/database 目录下还有继承安装版数据时裸拷的 pre-inherit-* 三件套，它不受任何清理约束，且整个 backups/ 不计入存储用量、也没有界面清理入口。最后讲账号同步：7 个类别默认全关、只在点「立即同步」时执行、走同一个 /desktop-sync/execute 端点（预览靠 mode 区分），四重校验（字段白名单、键名黑名单、类型表、值文本扫描）是整条跳过而非裁剪，配保护列表防止云端覆盖本地。含保留期对照、真实限额、本地应用顺序、25 行排查表，并如实记录两处代码与文案不一致。

SparkWork Hooks V2 完整实操手册：先辨析产品里三套同名机制——桌面 Hooks V2（7 个生命周期事件、通知/提示音/调用工具三种动作）、设置页底部的经典通知（V1 四个节点、布尔开关），以及 spark-engine 里那套没有任何界面的 shell 命令 hook（4 个闭集事件，退出码 2 或输出 block 决策可真正拦截，桌面 Spark 执行器同样会加载项目目录下的 .spark/settings.json）。再讲清 Hooks V2 的真实行为：七个事件的发射时机与 payload、确定性事件 ID 与两级去重、条件路径白名单与八个操作符的真实语义（eq 比较 null 恒为 false、contains 不支持数组）、三种值表达式与模板占位符规则、作用域优先级与基于执行哈希的绑定授权、什么改动会让授权失效、事件到执行的四段管线与三个定时器、超时/重试/幂等/并发的准确语义，以及 20 行排查对照。含如实记录的已知缺口：high-write 工具无法开放、条件无法通过界面移除、失败事件不清理、部分协议能力界面配不到。

Spark Work 桌面端架构总览：Electron 主进程 / 渲染进程 / Preload / 类型化 IPC 桥、Agent Runtime 真实服务清单、本地 SQLite 与文件目录、凭据存储（keystore / 加密 vault）与三种执行引擎的载具差异。

Spark Work 可选功能组件完整指南：Codex 本地运行环境、离线 Office 预览、本地深度处理、FFmpeg、Chromium 与语音输入资源六个大体积组件不随安装包分发，而是按需下载。本页先讲清 definitions.ts 里 archive 与 external 两条安装通道的真实差异——四个 external 能力里三个照样从 Spark 自建制品仓库下载，只有 Chromium 走 npm 生态，selectArtifacts 返回空数组只是「不走通用流水线」的意思；接着逐个拆解四个专用完整性服务的探测与安装：FFmpeg 的 managed/system/none 三级降级与从目录名解析版本、Chromium 的四组包解析候选与三级浏览器探测及其 150 MB 固定估值、语音包的三组件与四值平台白名单及单飞保护、Codex 运行时的四段目录与 bundled 开发态旁路。版本协商部分给出协议基线 0.144.5、exact-sdk-match 与 newest-compatible 的取舍、五种失败原因对应的用户提示原文，以及三个环境变量的注入点。archive 部分覆盖七个阶段、包内 manifest 与全量文件 SHA-256、三层路径与符号链接防护、CapabilityPackageHealth 实际只覆盖两个能力的事实，以及激活失败时「原版本已保留」的回滚语义。操作语义部分说明 install/update/repair 是同一个实现（修复必然整包重下）、取消与卸载只对 archive 能力可用、卸载只删状态目录而够不到外部能力的二进制、自动更新默认值与 check 的触发条件、启动提醒的 7 天冷却与按版本静音，以及清单缓存 24 小时内不联网会让 remoteAvailable 为假从而静默跳过提醒的关键坑。协议部分覆盖 capability-asset:// 的五步路径穿越与符号链接防护、四条 host 分支与构建期资源外部化插件的 fail-fast，以及 Codex Runtime 诊断卡片的指标、四个告警阈值与「只回收空闲实例」的重启语义。文末附 11 个 IPC 通道契约、30 行排查表，以及 11 项声明了但当前不起作用的东西。

Spark CLI（包名 @spark/agent，命令 spark）完整参考：18 个子命令与参数解析的真实边界（所有 flag 共用一张解析表，与本命令无关的 flag 会被静默忽略）、三种输出格式的区别（--json 给事件流、--output-format json 才给一行结果对象）、完整退出码表（取消是 130、用法错误是 2、update 有专属 0/1/2/3/4）、会话账本的组织方式与 -c/-r 的差别、TUI 的七个准入条件与 9 条公开斜杠命令、图片附件的格式与限额。桌面联动部分讲清本地回环桥的发现与选主、bridge 描述文件协议、三个真实端点、哪些渠道会被桥接（只有 Anthropic 与显式标记 responses 的 OpenAI 渠道），以及桥的安全模型与凭据链路。最后是 ~/.spark 与项目级 .spark 的数据落点、配置分层合并规则、各子命令的真实行为与 28 行排查对照。

Spark Work 应用内置的全部 17 个 Skill 教程：claude-api / commit / react / frontend-design / skill-creator / multi-search-engine / browser-use / canvas-studio / multimedia-use / spark-web-tool / spark-workflow-generator / video-workflow / echarts / ui-ux-pro-max / spark-debug / find-skills / platform-manager。每条都给出真实技能 ID、触发场景、配套工具与跳过条件。

Spark Work 三层长期记忆完整指南：User / Project / Agent 作用域隔离不串味，后台独立 LLM 抽取（与 OpenAI Memory、Mem0 同款架构）不干扰主对话，五道写入闸门，FTS5 + sqlite-vec 混合检索经 RRF 融合与时间衰减后按 token 预算注入，整合 job 自动合并重复并把零散反馈升华成候选，有效期到期顶替旧事实，旧记忆只标失效不删除。含生命周期状态机、CAS 并发保护、失效与实体图、配置面板逐项说明、速查表与 12 行排查表。

Spark Work AI-Native 知识库（Wiki）完整指南：空间 / 页面 / 双链 / 版本四件套的领域模型与落库表，统一写入原语（expectedVersion CAS 乐观锁 + 正文原子落盘 + FTS 同事务 + 失败回滚），12 个 mcp__spark_wiki__ 工具的只读与审批分组，零预注入下的四层上下文预算（常驻 800 / search top 8 / read 3000 token 每页 / 单轮总闸 8000，均带服务端硬上限），对话沉淀管道的三条人审入口与水位线，抽取的三条硬约束（无来源不入库、不猜内容、敏感内容前置拦截），候选区人工确认晋级，技能提议闭环与 Repo Wiki 扫描重建，五个设置分组逐项说明，以及知识库与长期记忆的分工边界。附速查表、8 条常见问题与 10 行排查表。

Spark Work 工作流（Workflow）完整教程：13 种节点作用与配置、outputKey 状态传递、条件路由、循环体子图可视化编辑、verify 失败语义，以及覆盖审批、并行子代理、Skill / Tool / MCP 审计和双交付物的编码功能任务示例。

Spark Work 任务面板（BoardView）使用教程：6 个状态列（todo / in-progress / bug-fix / done / accepted / closed）、TaskCard 完整字段（id / title / description / status / priority / assignee / project / tags / dueDate / processingAgent / acceptanceCriteria / testAgent / comments / attachments / sortOrder）、内联创建 / 编辑、拖拽改变状态、右键菜单、回收站软删除、多维筛选、通过 platform-manager Skill 让 Agent 自动操作。

Spark Work 会话内定时任务：在单个会话作用域创建持久化任务，到点自动用本会话当时的 Agent/模型/权限/工作区续接一轮对话。支持 interval（固定间隔）/ cron（5 字段表达式）/ once（单次定时），用户工具栏和 Agent MCP 工具两个入口，调度引擎托管重试、并发与下次执行。

Spark Work 画布视频工作台：视频节点的全屏一站式处理台，覆盖深度视频转换（本地 Depth Anything V2，离线不上云）、关键帧提取（scene / iframe / uniform 三策略，超限自动退化，可回填画布）、剪辑处理（转码、切割、音频分离、变速、倒放、画面裁剪）和多段时间线轨道拼接。