Agent 工作流

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

1. Agent 的真实字段

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

1.1 基本信息与执行器

界面标签	真实字段	取值与说明
名称 / 描述	name/description	名称最长 30 字、描述最长 200 字（AGENT_NAME_MAX= 30 / AGENT_DESC_MAX= 200）。
状态	enabled	停用后 Agent 不出现在选择器里，也不会被工作流或团队派发。
默认 Agent	isDefault	同一时刻只有一个：设为默认时会清掉其他 Agent 的默认标记。
头像	metadata.avatar	没有自定义头像时按 id/名称派生默认头像。
Provider	providerProfileId	下拉里含「跟随会话」空值：留空表示用会话当前 Provider。
默认模型	modelId	可选「Provider 默认」。用的是本地 CLI Provider 时该框只读并显示「跟随本地 CLI」。
执行器 (SDK)	agentAdapter	claude-sdk（推荐）/codex/spark。 新建默认 claude-sdk；切换执行器会把权限模式重置为该执行器的默认值。

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

1.2 权限模式与推理强度

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

执行器	可选权限模式
claude-sdk	claude-ask（请求批准）、claude-plan（计划模式）、claude-auto（自动审批）、claude-bypass（完全访问）
codex	codex-default（按需批准，workspace-write）、codex-auto-review（替我批准）、codex-full-access（danger-full-access）
spark	spark-default（手动审批）、spark-auto（自动审批）、spark-bypass（完全访问）

会话工具栏里还有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（Claude SDK 且存在可派发节点，运行时真实驱动图）、codex_guided（Codex / Spark 路径，不给workflow_run工具， 由模型按拓扑顺序自己推进）、guided（没有托管执行器或这是 @ 提及轮）。 界面上的文案分别是「托管执行」「引导执行」「不执行」。

3. MCP 与工具怎么挂载

Agent 的mcpServerIds是兼容字段，运行时忽略。 平台 MCP 的 agents_create/agents_update工具参数里， 它的描述原文就是「兼容字段，运行时忽略；所有已启用 MCP 会自动对 Agent 可用」。 编辑页的「MCP 服务」区块也只列出当前已启用的服务器并写明「所有已启用的 MCP 对该 Agent 自动可用， 无需单独绑定」。

实际规则：

• 会话、团队成员、agent/subagent/skill/tool/mcp节点的 MCP 服务器集合都来自 「应用级已启用 MCP」这一处开关。
• 唯一例外是只读原子节点：input / route / plan / review / artifact运行时从空能力集起步，不挂任何 MCP，也不注入项目级 Skill 提示词—— 它们只负责解析、计划与复核，不接触外部系统。
• 想缩小能力面，不要去找 Agent 白名单，而是到 MCP 管理页停用服务；在工作流节点上用toolIds收窄内置工具（见工作流编排一篇）。
• 工作流节点上残留的config.mcpServerIds字段旧数据仍会被读取成「该 worker 的 MCP 选择」， 但编辑器已经不提供这个入口，新图不要再依赖它。
• Agent 选中的 Skill 会进入运行时技能目录，模型按需加载；Skill 与 MCP 是两套独立能力来源。

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

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

事件名	界面文案	触发时机
turn.started	Turn 开始	Turn 已建立、准备进入执行管线
permission.requested	权限请求	权限请求进入等待审批
question.requested	Agent 提问	Agent 提问进入等待用户输入
response.committed	回答已提交	最终回答成功落库、正文确定
turn.completed	Turn 完成	Turn 成功终态已持久化
turn.failed	Turn 失败	Turn 进入不可恢复失败终态
turn.cancelled	Turn 已取消	用户或系统明确取消 Turn

• 动作：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 能管理平台自己

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

工具族	能力
skills_*	list / load / search / search_github / install / install_github / uninstall / toggle
mcp_*	list / create / update / delete / status
custom_tools_*	guide / list / get / validate / create_draft / save_draft / test / publish / set_enabled / rollback / delete
tool_packages_*	guide / list / get / inspect / create_project / install_* / set_permission / test / uninstall 等
providers_*	list / get / create / update / delete / health_check / set_default / set_default_model，另有 providers_media_* 渠道校验与诊断
workflows_*	list / get / create / update / delete
agents_*	list / get / create / update / delete
teams_*	list / get / create / update / delete
board_*	list / get / create / update / delete / batch_create / batch_update / batch_delete / restore / permanent_delete
settings_*	get / set / get_category / get_all
sessions_*	get / switch_model / switch_provider / switch_mode / switch_permission / switch_reasoning_effort
session_schedule_*	list / get / create / update / delete（仅当前会话）
session_history_*	list / read / search（本会话压缩前的完整历史）
referenced_sessions_list/referenced_session_*	列出并读取已授权的参考会话
artifacts_*	list / resolve（自建安装源里的运行时与依赖包）
github_*	status / 仓库读取 / 建分支 / 写文件 / Issue 与 PR 读写
codex_runtime_*	diagnostics / restart_idle

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

6. 常见坑

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

速查表

项目	内容
默认 Agent	Spark助手（platform-manager-agent，内置、不可删除）
编辑入口	左侧「助手」→ Agents 标签
执行器	claude-sdk / codex / spark（默认 claude-sdk）
权限模式	claude 四档 / codex 三档 / spark 三档（按执行器分组）
推理强度	minimal / low / medium / high / xhigh / max
MCP	mcpServerIds 为兼容字段被忽略；应用级已启用 MCP 全局自动挂载
Hook 事件	turn.started / permission.requested / question.requested / response.committed / turn.completed / turn.failed / turn.cancelled
平台 MCP	spark_platform（mcp__spark_platform__*）
工作目录	不在 Agent 上，来自会话绑定的项目或临时会话目录

上手清单：创建一个能跑真实任务的专属 Agent

在「助手 → Agents」里配置模型、权限、技能与工作流绑定

1. 打开左侧「助手」，切到 Agents 标签，点「新建 Agent」
2. 填名称与描述，设好状态与「默认 Agent」开关
3. 在「执行配置」里选 Provider 与默认模型；默认模型可留空表示用 Provider 默认
4. 选「执行器 (SDK)」：Claude SDK / Codex / Spark；选完权限模式会自动重置为该执行器的默认档
5. 按需调整权限、推理强度；只有 Claude SDK 需要时再填推理 Token 预算（1024~128000）
6. 在右栏「Skills / 规则」里勾选能力与约束；MCP 不需要在这里绑定
7. 可选：在「工作流」下拉里绑定一个工作流，让这个 Agent 走托管执行
8. 可选：在「Hook」区块启用或覆盖该 Agent 的 Hook 绑定
9. 保存后回到会话，在输入栏的 Agent 选择器里就能选到它

常见问题

Agent 和会话（Session）是什么关系？

Agent 是配置模板（模型、执行器、权限、Skills、Rules、Hook、工作流绑定），会话是一次具体的对话。一个 Agent 可以被多个会话复用；工作目录、团队配置这类运行期状态挂在会话上，不在 Agent 上。

我改了全局 MCP，为什么所有 Agent 都变了？

因为 Agent 的 mcpServerIds 是兼容字段、运行时忽略。所有已启用的 MCP 会自动挂载到会话、团队成员和工作流节点，停用一个 MCP 服务是全局生效的；要按节点收窄能力，用工作流节点的 toolIds。

Agent 里能单独给我配的模型设权限模式吗？

权限模式是 Agent 级字段（permissionMode），按执行器分组：claude-sdk 有 claude-ask/claude-plan/claude-auto/claude-bypass，codex 有 codex-default/codex-auto-review/codex-full-access，spark 有 spark-default/spark-auto/spark-bypass。切执行器时表单会自动把权限模式重置为对应默认值。

Workflow 是必填的吗？绑定后会怎样？

不是必填。workflowId 留空时 Agent 按普通流程跑。绑定后系统提示词里会多出 [Workflow Execution Plan]，并且 Claude SDK 路径在有可派发节点时会变成「托管执行」，由 workflow_run 真实驱动整张图。

Hook 写在哪里？和 Rule 有什么区别？

Hook 定义在「设置 → Hooks」创建，再绑定到 application/workspace/agent/session 作用域并授权；Agent 编辑页的 Hook 区块管的是本 Agent 的绑定状态。Rule 是注入提示词的策略，Hook 是事件发生后的动作（通知、提示音、调用工具），两者不要互相替代。

为什么 Agent 的推理强度设置了却没感觉？

先确认执行器。推理强度对三种执行器都生效，但「推理 Token 预算」（reasoningBudgetTokens）只对 Claude SDK 的显式 extended thinking 有效，其他执行器上输入框是禁用的。