多智能体引擎

它们现在叫"数字员工"了。 后台所有出现"智能体"的地方都改了。底层运行时还是 Agent，但 UI 上、概念上、模板上——它们是你团队里的同事。命名变了，世界观也跟着变了：你给一个员工角色（Role）、目标（Goal）、背景故事（Backstory），他知道自己是谁、为什么存在；你不用再写一段冷冰冰的 system prompt 让"agent"理解任务。

一个数字员工就是一个带工具的人格。多个员工组成一支团队。

短版本是这个。长一点的版本：一个员工是一个名字，一段定义它怎么思考的 system prompt（包含角色 / 目标 / 背景故事），一个真正在思考的模型，一组它被允许调用的工具，可选的知识库，可选的技能包，它自己的一份记忆，以及它处理难题的方式——一步一步反应式（ReAct）还是先写计划再执行（Plan-and-Execute）。

你可以有很多个员工。每一个都专门做一类事。你把不同的活交给不同的员工。

一个数字员工有什么

部分	是什么
名字	你和你的团队找它用的
图标	像素艺术风格、按角色配色，一眼认出
角色 (Role)	一句话——"我是产品研究员" / "我是客户支持"
目标 (Goal)	一句话——"我帮你看清楚市场怎么动"
背景故事 (Backstory)	它来自哪、为什么存在、它在意什么；这些会自动拼到最终 system prompt
员工卡片标语 (Tagline)	卡片上展示的一句"自我介绍"
System Prompt	它的人格、规则、风格、优先级（角色/目标/背景故事会自动注入）
类型	`react` 或 `plan_execute`
工具	它被允许调用的工具（来自内置工具、MCP、技能包、ACP 桥接）
知识库	它可以读的 LLM Wiki（KB 热点会自动注入到 system prompt）
工作空间记忆	它自己那一份 `PROFILE.md`、`MEMORY.md`、`SOUL.md`、`AGENTS.md`，以及每日笔记
最大迭代次数	强制收敛前允许走多少轮推理循环
启用开关	关掉它

注意一个没有的东西：模型。整个 MateClaw 部署里只有一个全局默认模型（在 设置 → 模型 里设置），所有 Agent 在运行时用的都是它。Agent 行上那个 model_name 字段是历史遗留——被忽略。这是刻意的：换模型是整个部署一次点击的事，不是三十次。

模板：从一个已经会工作的同事开始

你不是从一张白纸开始。数字员工 → 新建 打开一个模板选择器。里面有两层：

5 个职业模板（推荐）

每一个都自带角色、目标、背景故事、合适的工具集、像素艺术头像、专属配色——打开就能用：

产品研究员——竞品调研、市场动态追踪、用户访谈整理
客户支持——接住客户问的事、查知识库、把不能解决的升级出去
知识管理员——把零散材料整理进 LLM Wiki、维护双向链接、定期归纳
数据分析师——查数据源、跑 SQL、出图表、写结论
行政助理——日程、邮件草稿、跨工具协调

通用模板（白纸或半成品）

通用助手——默认的聊天员工
研究 / 代码 / 写作 / 知识策展 / 数据分析——按用途分类的半成品
自定义——彻底白纸一张，知道自己要什么就选这个

选一个，给它起名字、调一下角色和目标，保存。一分钟以内就有一个能上岗的同事。 创建之后每一项都能改。

两种思考方式

ReAct —— 思考、行动、观察、继续

默认模式。ReAct 模式下的 Agent 跑一个循环：推理下一步该做什么，行动（可能调一个工具），观察结果，决定是再循环一次还是回答。

适合：

简单问答，需要一两次工具调用
对话式交互，每一轮用户输入都不大
需要 Agent "边学边反应"的任务

例子："北京今天什么天气？" → 推理（需要实时数据）→ 行动（调 web search）→ 观察（15–26°C，晴）→ 回答。

Plan-and-Execute —— 先计划、再执行

适合更大的任务。Agent 先生成一个计划——一个由 2 到 6 个步骤组成的有序列表，然后一步一步执行。完成之后，总结一下所有做过的事。

适合：

多步研究（"调查 X，对比 Y，写一个简报"）
步骤在一开始就能想清楚的任务
你想看着进度跑的任务——计划和每一步的状态会出现在对话旁边的持久任务清单里

例子："研究一下 Spring AI 框架，对比前三个，给我写个简报。" → 计划（4 步）→ 按顺序执行 → 最终汇总。

怎么选

情境	用哪个	为什么
简单问答、单工具调用	ReAct	没有计划开销
信息检索	ReAct	一般 2–3 轮就结束
多步有序任务	Plan-and-Execute	显式计划更好看、更好 debug
研究 + 对比 + 写作	Plan-and-Execute	每一步的结果喂给下一步
"读这份文件然后告诉我 X"	ReAct	一个工具，一个答案
"给我写一份关于 X 的结构化报告"	Plan-and-Execute	多轮收集 + 综合

类型可以随时改。同一份 system prompt 在两种模式下都能工作得不错。

多 Agent 并行委派

一个 Agent 不是孤军作战。一个 Agent 可以把任务委派给另一个——或者同时委派给三个。

单点委派 —— 把一个子任务交给指定 Agent，在独立会话中执行，结果流式回传
并行委派 —— 同时委派给多个 Agent，每个在自己的隔离会话里跑
子会话实时可见 —— 你在 ChatConsole 里能看到每个子任务的推理、工具调用和进度
路由提示 —— 系统 prompt 里内置，Agent 知道什么时候该自己做、什么时候该委派

例子：让代码 Agent 处理 Jira 工单，同时让研究 Agent 拉竞品数据，同时让写作 Agent 起草 Slack 回复。三路并行，结果汇总给编排者。

多级子员工委派树

1.4.0 新增

委派不再只有一层。一个父员工可以委派给子员工，子员工还能再往下委派——递归最深 3 级。一支临时团队可以为某个具体任务自己长出层级。

三个委派工具，覆盖三种节奏：

delegateToAgent —— 同步委派。把一个子任务交给指定员工，等它跑完、拿到最终结果再返回。可选 inheritParentContext：把父会话最近的上下文一起带给子员工，省去重复交代背景。
delegateParallel —— 扇出委派。同时派给多个子员工，各自在隔离会话里跑，结果统一收集回来。
delegateAsync —— 后台委派。立刻返回一个 task_id，子员工在后台跑；之后用 taskOutput 取结果。taskOutput 带归属闸门——只有最初发起委派的同一个会话 + 同一个用户才能读到结果，防止跨会话/跨用户泄露。

子员工默认被拒绝一组工具，保证树不失控：

delegateToAgent / delegateParallel（递归护栏——子员工不能再发起同步/并行委派，避免委派风暴）
setGoal 系列 + remember 系列（目标与记忆的所有权留在父员工手里）
create_employee（子员工不能凭空造新员工）

这组默认拒绝列表可通过 mateclaw.delegation.child-denied-tools 调整。

委派和目标系统配合使用——父员工定目标、拆任务、把子任务委派下去，子员工专注执行。

UI —— 嵌套子员工时间线 + 常驻计划面板

ChatConsole 把整棵委派树画出来，不是一串扁平日志：

委派开始事件清晰标出
每个子员工显示名字 / 层级深度 / 任务摘要
完成徽标：成功 / 超时 / 错误，外加耗时、内容长度
每个子员工有稳定的 id + parentId + depth，所以嵌套关系在时间线里一眼能看清谁派给了谁
计划面板常驻——不再只有 Plan-and-Execute 模式才显示，委派树的进度也并入同一个面板

一句话造一支团队：数字员工搭建技能

1.4.0 新增

不想一个一个手动建员工？给一句话，让"数字员工搭建"技能替你把整支团队搭出来。

这个技能从你的一句话出发，走完整条链路：

澄清需求——先把模糊的一句话问清楚，确认你真正要解决的问题
设计角色——拆成 2 到 6 个互补的角色
逐个创建——对每个角色调用 create_employee 建出真实可用的员工
串成工作流草稿——把这几个员工链接成一条工作流草稿，开箱即可调整

配套工具 list_capability_catalog 让技能先看清当前部署里有哪些工具 / 技能 / 知识库可用，再据此分配角色能力。创建出来的员工默认即启用，不用再手动开开关。

深度思考

不是所有问题都值得深度推理，但有些问题需要。MateClaw 支持按 Agent、按对话打开深度思考模式：

thinkingLevel：off / low / medium / high / max
支持 Anthropic extended thinking、DashScope qwq 推理、OpenAI o1 reasoning_effort=high
思考块流式进入 UI，做成可折叠面板——你看得见模型怎么想，token 不会浪费在不需要推理的闲聊上

雇佣一个数字员工

数字员工 → 新建：

选一个模板（5 个职业模板之一，或通用模板，或 Custom）
起名字，挑头像（像素艺术风格的库可选，或自己上传）
写角色 (Role)——一句话；目标 (Goal)——一句话；背景故事 (Backstory)——几句话
写一句员工卡片标语 (Tagline)——卡片上展示的"自我介绍"
选类型（react 或 plan_execute）
写或改 system prompt（角色 / 目标 / 背景故事会自动拼接进来，不用重复写）
勾选它能用的工具，绑定它该读的知识库
设置 max_iterations（默认 10）
保存

立刻生效。从聊天 UI 或 API 开始用。

工具绑定（per-agent tool picker）

1.3.0 新增

在 v1.2.0 时，员工的工具绑定是平铺的"勾哪个就能用哪个"列表。v1.3.0 把这块重做成分组 + 状态感知 + 命名空间感知的 picker，专门处理 MCP 工具的脏状态。

打开数字员工编辑器的"工具"标签页：

按来源分组：内置工具 / 技能注入工具 / MCP 工具（按 server 名再分组） / ACP 工具
状态徽标：每个工具有一个标签——
- connected —— 当前可用
- stale —— 这个 MCP server 现在连不上，但绑定还保留（恢复连接后立即可用）
- unavailable —— server / skill 已被禁用，绑定保留但运行时不会下发给员工
- orphan —— 不存在的工具引用（server 删了或 tool 改名了）；保存时会拒绝保留这种引用，强制清理
命名空间冲突：两个不同 MCP server 提供同名工具时（比如两个都有 read_file），picker 显示完整 prefixed name（server-a__read_file / server-b__read_file）；员工的 system prompt 里把它们映射回原始名以避免混淆
保存时校验：勾选的每个工具会跑 AgentBindingService.validate(...)——任何 orphan 引用直接报错，必须先去掉
MCP server 重命名：原来挂在某 server 上的绑定自动跟随到新名字（按持久化的 tool cache 匹配），不需要手动重新勾

UI 入口：Agents → 选员工 → 工具。

技术细节见 MCP。

知识库绑定（per-agent 主知识库）

1.5.0 新增

员工编辑器新增"知识库"标签页，可以为每个员工指定一个主知识库。知识库本身仍是工作空间共享资源，绑定只是声明"我默认查哪一个"——不影响其他员工的访问。

简单版本：每个员工可以指定一个"主知识库"作为它默认查的 KB。可以不指定。

要点（这是设计模型，看完省得困惑）：

知识库是工作空间共享的。 一个 KB 创出来就归属当前 workspace，workspace 里所有员工都看得见。给员工"绑"一个 KB 不会把它变成专属——其他员工照样能调
"主知识库"只是一个默认值。 它告诉 wiki 工具（wiki_search / wiki_read / wiki_backlinks ...）："不显式说 kbName / kbId 时，默认去这个 KB"
多个员工可以选同一个 KB 作主库。 互不影响，谁切谁的，KB 本身不动
不绑也行。 没指定主库时，运行时按 workspace 里最近更新的 KB 兜底

UI 入口：员工 → 选员工 → 编辑 → 知识库。

选项	行为
🚫 未指定主库	清空绑定；下次员工的 wiki 工具不带 `kbName` 时，按 workspace 最近活跃 KB 回退
📚 <KB 名>	设这个 KB 为主库；之后 wiki 工具默认查它，列表上同时显示页面数

每个 KB 行展示：图标、名字、描述、页面数。列表内容就是当前 workspace 里所有 KB 的完整集合（包括已被其他员工选作主库的）。

运行时怎么解析"该读哪个 KB"

员工调 wiki 工具时，解析顺序如下：

工具调用显式带了 kbName / kbId——直接用那个
没显式说 → 看员工的 primaryKbId，命中则用它
primaryKbId 也没有 → 在 workspace 可见 KB 集合里取最近更新的那个
workspace 一个 KB 都没有 → 工具返回空，员工 LLM 自己判断要不要换思路

迁移备注：早期版本的"绑定"是写在 mate_wiki_knowledge_base.agent_id 上的（一对一独占语义）。从 V130 迁移开始，所有老的 kb.agent_id 都被回填到 agent.primary_kb_id，老字段保留作 fallback 读取，但新的写入只走 agent.primary_kb_id。如果你之前依赖"KB 只给某个 agent 看"的隔离，请到员工管理面板重新审视一遍——KB 现在对 workspace 内全员可见。

System Prompt 最佳实践

System prompt 是数字员工的声音、优先级、约束的来源。角色 / 目标 / 背景故事和技能指令、工作空间记忆系统会自动拼接到最终 prompt 里——这些部分你不用自己写。

你自己的 prompt 应该包含：

它该怎么说话——语气、风格、措辞偏好（"专业但不死板" / "面向客户保持谨慎"）
它被允许做什么、被期望做什么——任务边界
不确定时怎么办——"先搜，不要编造" / "跑危险命令前问我"
输出格式——需要结构就明说

不要写的东西：

工具描述——会自动注入
工作空间记忆的使用说明——从 AGENTS.md 来
框架层的行为（工具调用格式、ReAct 结构）——别跟运行时对着干

示例：

你是一个专业的技术文档助手。你的职责：
根据用户需求搜索并整理技术资料
用清晰、结构化的方式回答问题
确保代码示例语法正确
不确定的时候先搜索，不要捏造
原则：
引用外部信息时注明来源
涉及时效性问题，先获取当前日期再搜索

给开发者：Agent 内部是怎么转的

只是用 Agent 的话，这一节可以跳。在它上面写代码（加节点、改路由、做扩展）的话，请直接看架构说明——StateGraph 拓扑、节点列表、共享状态 key、扩展点都在那一页。

生命周期状态

状态	含义
`IDLE`	等待输入
`PLANNING`	正在生成计划（Plan-and-Execute 模式）
`EXECUTING`	正在执行工具调用或子任务
`RUNNING`	活跃的 ReAct 循环或 Plan-Execute 图执行中
`WAITING_USER_INPUT`	暂停，等用户响应
`DONE`	完成
`FAILED`	执行失败
`ERROR`	错误状态

回合的结束原因：

值	含义
`NORMAL`	LLM 给出了直接的最终答案
`SUMMARIZED`	上下文压缩之后正常完成
`MAX_ITERATIONS_REACHED`	到达迭代上限被强制收敛
`ERROR_FALLBACK`	出错后降级的答案

可靠性机制

这些是运行时自己在做的事，目的是让 Agent 在你不想去 debug 的那种地方不脆弱：

上下文修剪——上下文窗口快满时，早期轮次由 LLM 总结、摘要替换原文。缓存 30 分钟。摘要以用户消息形式注入，不是系统消息——防止历史内容被提升成系统级指令的注入风险。
结构化压缩（prompt 过长时）——当模型返回"prompt 过长"时，运行时走一条四级递进的结构化压缩链：软裁剪 → 硬清理 → 预修剪 → LLM 结构化摘要。无论走到哪一级，都永远保留前缀——system prompt + 目标锚点不动；最终摘要以 UserMessage 形式注入。委派工具的返回结果永远不会被压缩（它们是子员工的成果，丢了就找不回来）。某次摘要失败后有 10 分钟冷却，避免在同一个超限回合里反复硬调 LLM。
思考恢复——流式中途断了，已经写出的思考和内容会持久化，会话重载时还在。
迭代上限处理——到达 max_iterations 不会崩溃，而是强制让 LLM 用现有信息生成一个尽力而为的总结答案。
僵尸流清理——后台跟踪每一个打开的 SSE 流，被遗弃的会被自动回收。
429 重试——LLM 限流错误会触发带退避的自动重试。
重复检测——抓住那些反复在同一个工具调用上打转的 Agent，强行把它拉出循环。
工具超时可配置——一个慢工具不会冻结整个回合。
渠道健康监控——失败的渠道适配器走指数退避重启。

这些没有一个是用户面的按钮。它们就自己在发生。

Agent 管理 API

创建

bash

curl -X POST http://localhost:18088/api/v1/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "技术助手",
    "description": "专业的技术文档助手",
    "agentType": "react",
    "systemPrompt": "你是一个专业的技术文档助手...",
    "maxIterations": 10
  }'

列表 / 获取 / 更新 / 删除

bash

curl http://localhost:18088/api/v1/agents -H "Authorization: Bearer YOUR_JWT_TOKEN"
curl http://localhost:18088/api/v1/agents/1 -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X PUT http://localhost:18088/api/v1/agents/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"name":"技术助手 v2","maxIterations":15}'

curl -X DELETE http://localhost:18088/api/v1/agents/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

流式对话

bash

curl -N "http://localhost:18088/api/v1/agents/1/chat/stream?message=你好&conversationId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

调试

在 application.yml 里打开 DEBUG 日志：

yaml

logging:
  level:
    vip.mate.agent: DEBUG
    vip.mate.agent.graph: DEBUG

你会看到节点一节点的执行过程：状态切换、dispatcher 路由决策、迭代数、工具调用参数和结果摘要、Tool Guard 检查结果。

常见问题

症状	可能原因
Agent 不响应或超时	模型配置错、API Key 无效、额度用光
Agent 卡在循环里出不来	`max_iterations` 太低，或者某个工具反复报错
`MAX_ITERATIONS_REACHED` 经常触发	调 system prompt 或者把上限调高
工具调用悄悄失败	Tool Guard 在拦——看 `mate_tool_guard_audit_log`
等审批的图恢复不了	`chatWithReplay` 里 `toolCallPayload` 格式对不上

下一步

工具系统——Agent 能调用什么
技能系统——怎么扩展 Agent 能做的事
LLM Wiki——知识怎么被 Agent 读到
记忆系统——Agent 怎么跨会话记住东西
工作流（1.3.0+）——把多个数字员工 + 系统动作编排成一条业务流程
触发器（1.3.0+）——让事件自动启动工作流或员工对话
架构说明——StateGraph 运行时深入

多智能体引擎 ​

一个数字员工有什么 ​

模板：从一个已经会工作的同事开始 ​

5 个职业模板（推荐） ​

通用模板（白纸或半成品） ​

两种思考方式 ​

ReAct —— 思考、行动、观察、继续 ​

Plan-and-Execute —— 先计划、再执行 ​

怎么选 ​

多 Agent 并行委派 ​

多级子员工委派树 ​

UI —— 嵌套子员工时间线 + 常驻计划面板 ​

一句话造一支团队：数字员工搭建技能 ​

深度思考 ​

雇佣一个数字员工 ​

工具绑定（per-agent tool picker） ​

知识库绑定（per-agent 主知识库） ​

运行时怎么解析"该读哪个 KB" ​

System Prompt 最佳实践 ​

给开发者：Agent 内部是怎么转的 ​

生命周期状态 ​

可靠性机制 ​

Agent 管理 API ​

创建 ​

列表 / 获取 / 更新 / 删除 ​

流式对话 ​

调试 ​

常见问题 ​

下一步 ​

多智能体引擎

一个数字员工有什么

模板：从一个已经会工作的同事开始

5 个职业模板（推荐）

通用模板（白纸或半成品）

两种思考方式

ReAct —— 思考、行动、观察、继续

Plan-and-Execute —— 先计划、再执行

怎么选

多 Agent 并行委派

多级子员工委派树

UI —— 嵌套子员工时间线 + 常驻计划面板

一句话造一支团队：数字员工搭建技能

深度思考

雇佣一个数字员工

工具绑定（per-agent tool picker）

知识库绑定（per-agent 主知识库）

运行时怎么解析"该读哪个 KB"

System Prompt 最佳实践

给开发者：Agent 内部是怎么转的

生命周期状态

可靠性机制

Agent 管理 API

创建

列表 / 获取 / 更新 / 删除

流式对话

调试

常见问题

下一步