Agent 工作流

Agent 是 Spark Work 里「会用工具的模型角色」。它是一份可复用配置：绑哪个 Provider 和模型、 用哪个执行器、权限和推理强度多大、带哪些 Skills / Rules / Hook、要不要挂工作流。 会话启动时，运行时把这些配置连同项目上下文一起拼成系统提示词注入模型。

1. Agent 的真实字段

入口：左侧导航「助手」→ 顶部 Agents 标签 → 点开某个 Agent 进入编辑页 （同一个页面还有 Teams 标签，见「团队模式」一篇）。

1.1 基本信息与执行器

数据存在本地 SQLite 的 agents 表（provider_profile_id、model_id、agent_adapter 等列），平台侧 agents_* MCP 工具与编辑页写的是同一份数据。

1.2 权限模式与推理强度

权限模式不是一组通用枚举，而是按执行器分组的：界面只列出当前执行器合法的那几档。

会话工具栏里还有 claude-auto-edits（自动编辑，自动批准文件编辑）；spark-accept-edits 与 spark-plan 是旧版残留值，只对存量会话生效， 新配置里不会出现。

• 推理强度：reasoningEffort，六档minimal / low / medium / high / xhigh / max。新建 Agent 的草稿默认medium；直接经平台 MCP 创建时数据库列默认 max。
• 推理 Token 预算：metadata.reasoningBudgetTokens， 范围 1024 ~ 128000，只对 Claude SDK 的显式 extended thinking 生效； 其他执行器上该输入框禁用，留空表示由 SDK / 模型自行决定。
• 提示词：prompt，编辑页里标题是「提示词 / System Prompt」， 支持全屏编辑。它注入成 [Agent Instructions] 段，与终端里 Claude Code 的CLAUDE.md 不是一回事。

1.3 能力面：Skills、Rules、Hook、Workflow

• Skills：skillIds + disabledSkillIds。 新建 Agent 会预选 builtin:multi-search-engine、builtin:browser-use、builtin:platform-manager、builtin:find-skills；其中builtin:platform-manager 由仓储层强制注入，任何 Agent 都摘不掉。
• 规则：ruleIds。这里勾选的规则会与工作流节点上配置的ruleIds 合并进 [Runtime Rules]。
• Hook：编辑页右栏的「Hook」区块展示的是 Hook 定义的绑定与授权状态 （生效中 / 待重新授权 / 已停用），可以在这里启用、停用或覆盖本 Agent 的绑定。
• 工作流：workflowId，可选。留空时 workflowId 为 null， Agent 按普通单 Agent 流程跑。

1.4 工作目录不由 Agent 决定

Agent 配置里没有「工作目录」字段。Agent 在哪个目录里干活，取决于会话绑定的项目 （workspace）或临时会话目录；这也是同一个 Agent 在不同项目里表现不同的原因。 「助手」页的「快速对话」会先让你选项目，或直接进入临时会话。

2. 会话启动时注入了什么

一次 turn 的系统提示词由多个独立段拼成，下面按实际拼装顺序列出主要段落（不适用于当前会话的段会整段跳过）：

1. 应用基础提示词、工具使用指引。
2. [Managed Agent]：Agent 名称与 id、描述、你的 prompt（写为 [Agent Instructions]）。
3. [Workflow Execution Plan]：仅当该 Agent（或会话覆盖）绑定了工作流时注入， 这是 [Managed Agent] 段内的一部分；节点按拓扑顺序列出，并附边与条件。
4. 团队相关段：[Orchestration Mode]、[Team Roster]、[Team Instructions]（见团队模式一篇）。
5. 工作区与 worktree 状态提示。
6. [Runtime Rules]：应用里启用中的 Rules（按 scope_ref 匹配当前项目） + Agent 的 ruleIds + 工作流节点上的 ruleIds，按优先级排序、 去重后编号列出。
7. 项目上下文：项目里的 AGENTS.md、CLAUDE.md 等规则文件， 按 token 预算裁剪后注入。项目级 Skill 走独立的 skill system prompt 通道，不在这一串段落里。
8. 长期记忆摘要与记忆行为引导。
9. 对话历史之后还有一个 [Current Workflow Binding — Authoritative] 段： 声明本轮唯一生效的工作流身份，覆盖提示词或历史里出现的其他工作流名称。

另外，工作流有两种执行强度，由「是否有可执行节点」决定：workflow_run（存在可派发节点时，三种执行器都通过 workflow_run 工具由运行时真实驱动图：claude-sdk 走进程内 SDK server， codex / spark 走 HTTP MCP 桥）、guided（没有托管执行器或这是 @ 提及轮）。 界面上的文案分别是「托管执行」「引导执行」「不执行」。

3. MCP 与工具怎么挂载

Agent 的 mcpServerIds 支持按需挂载：未选择（默认）= 全部可用，所有已启用 MCP 自动挂载；在 Agent 编辑页 「MCP 服务」区块部分点选后，该 Agent 的会话、团队成员与工作流节点 只挂载所选 MCP。内置服务分两档：文件交付、结果回读、记忆检索、会话服务等会话基础能力始终保留；平台管理（80+ 工具）、浏览器自动化、桌面控制、 多媒体生成、联网搜索等重型服务可按 Agent 摘除——给专业 Agent 瘦身，直接省下每轮提示词里的工具定义 token。注意平台管理服务在 Spark / Codex 引擎下强制挂载（这两类引擎的技能加载依赖它），仅 Claude SDK 引擎可摘。

实际规则：

• 会话、团队成员、agent/subagent/skill/tool/mcp 节点共用同一套语义： Agent 未配置或全选 → 应用级已启用 MCP 全量挂载；部分点选 → 仅挂所选 （自定义 server 按 DB id、内置服务按 builtin:spark_* 合成 id 存储）。
• 只读原子节点（input / route / plan / review / artifact） 仍从空能力集起步，不挂任何 MCP，也不注入项目级 Skill 提示词—— 它们只负责解析、计划与复核，不接触外部系统。
• 工作流节点上残留的 config.mcpServerIds 字段旧数据仍会被读取成 「该 worker 的 MCP 选择」（显式空集 = 空能力集）；编辑器不提供这个入口，新图不要再依赖它。
• Agent 选中的 Skill 会进入运行时技能目录，模型按需加载；Skill 与 MCP 是两套独立能力来源。

4. Hook：生命周期事件与经典通知

Hook 现在是宿主确定性调度的「观察型」机制：事件发生了才执行动作，不改变已经发生的结果。 配置入口有两处：设置 → Hooks（定义、绑定、运行记录），以及Agent 编辑页 → Hook（该 Agent 的绑定与授权状态）。

• 动作：builtin.notification（系统通知）、builtin.sound（提示音）、tool.invoke（调用连接器 / 自定义工具 / 工具包里的某个工具）。
• 条件与取值：支持 eq / notEq / exists / contains / startsWith与 and / or / not 组合；取值表达式只有常量、事件路径、模板字符串三种， 不会执行用户脚本。
• 执行策略：超时默认 15 秒；重试策略 mode 为safe / keyed / unsafe（默认 unsafe）、默认最多 3 次、退避基数 1000ms； 并发策略 serial_per_session 或 parallel。
• 绑定与授权：作用域分 application / workspace / agent / session 四级， 绑定必须带授权（authorizeExecutionHash）才会执行；定义改动后哈希不一致， 绑定会退回「待重新授权」。
• 经典通知：设置 → Hooks 页底部还保留旧的 sound/notification 配置 （节点为 permission_request / ask_user_question / session_end / session_fail）， 它与 V2 并联但不会双发；permission_request 这条仍走旧路径。 Agent 表里的 hook_config 列就是这份旧配置。

5. spark_platform：Agent 能管理平台自己

每个会话都挂载内置 MCP spark_platform，工具全名为mcp__spark_platform__<tool>。按工具族划分：

长期团队定义存在 agent_teams 表，用 teams_* 增删改查；创建团队前先用agents_list 拿到 host / member 的真实 agent id。

6. 常见坑

• 以为 Agent 还是不能限制 MCP：mcpServerIds 未选择（默认）= 全部已启用 MCP 自动挂载；在 Agent 编辑页「MCP 服务」部分点选后仅挂所选。要全局收窄能力 请停用 MCP 服务，或改用工作流节点的工具白名单。
• 权限模式写错执行器：claude-*、codex-*、spark-* 三组互不通用。切执行器后表单会重置权限模式，但通过agents_update 直接写值时不会自动纠正。
• 把 spark-plan / spark-accept-edits 当成现行枚举： 它们是旧值，只在存量会话里被识别。
• 把推理 Token 预算配给非 Claude SDK 的 Agent：不生效。
• 在 Agent 里找「工作目录」：没有这个字段，目录来自会话绑定的项目。
• 把 Hook 当成 Rule 用：Rule 是注入提示词的策略，Hook 是事件回调， 观察型 Hook 无法改变已经发生的结果。