22 KiB
架构说明
MateClaw 是怎么拼起来的，一页讲完。
用 MateClaw 的人看 项目介绍。在 MateClaw 上面建东西的人——加工具、新渠道、自定义记忆 provider、新的 Agent 图节点——看这一页。
一张图的产品
┌─────────────────────────────────────────────────────────────────┐
│ MateClaw │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐ │
│ │ Web 控制台 │ │ 桌面端 │ │ IM 渠道 │ │
│ │ Vue 3 SPA │ │ Electron │ │ 钉钉 / 飞书 / │ │
│ │ (src/static) │ │ + 内置 │ │ 企业微信 / Telegram/ │ │
│ │ │ │ JRE 21 │ │ Discord / QQ / ... │ │
│ └──────┬──────┘ └──────┬───────┘ └──────────┬──────────┘ │
│ │ HTTP/SSE │ HTTP/SSE │ SPI │
│ └────────┬────────┴───────────────────────┘ │
│ │ │
│ ┌───────────────▼──────────────────────────────────────────┐ │
│ │ Spring Boot 后端（vip.mate.*） │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │ │
│ │ │ auth │ │ channel │ │ agent │ │ │
│ │ │ (JWT) │ │ adapters │ │ (AgentScope │ │ │
│ │ └────────────┘ └─────┬──────┘ │ runtime) │ │ │
│ │ │ │ │ │ │
│ │ ┌────────────┐ │ │ ┌──────────────┐ │ │ │
│ │ │ workspace │ │ │ │ ReasoningN │ │ │ │
│ │ │ isolation │ │ │ │ ActionN │ │ │ │
│ │ └────────────┘ │ │ │ Observation │ │ │ │
│ │ │ │ │ PlanGenN │ │ │ │
│ │ ▼ │ │ StepExecN │ │ │ │
│ │ ┌──────────────┐ │ │ FinalAnsN │ │ │ │
│ │ │ Message │ │ └──────────────┘ │ │ │
│ │ │ Router ├──▶ │ │ │ │
│ │ └──────────────┘ └──────┼─────────────┘ │ │
│ │ │ │ │
│ │ ┌─────────────────────────────────────▼────────────────┐ │ │
│ │ │ Tool Registry │ │ │
│ │ │ │ │ │
│ │ │ 内置 @Tool + MCP client + 技能脚本 │ │ │
│ │ └─────────┬───────────────────────────────────────────┬──┘ │ │
│ │ │ │ │ │
│ │ ▼ ▼ │ │
│ │ ┌──────────────┐ ┌─────────────┐ ┌───────────────────┐ │ │
│ │ │ Tool Guard │ │ 审批 │ │ 审计日志 │ │ │
│ │ │ （规则） │ │ 工作流 │ │ 管道 │ │ │
│ │ └──────────────┘ └─────────────┘ └───────────────────┘ │ │
│ │ │ │
│ │ ┌────────────┐ ┌────────────┐ ┌────────────────────┐ │ │
│ │ │ memory │ │ wiki │ │ skill │ │ │
│ │ │ 多层 │ │ （分层） │ │ (SKILL.md 运行时) │ │ │
│ │ │ SPI │ │ digester │ │ │ │ │
│ │ └────────────┘ └────────────┘ └────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ MyBatis Plus / H2 或 MySQL │ │ │
│ │ │ │ │ │
│ │ │ mate_agent / mate_message / mate_wiki_* / │ │ │
│ │ │ mate_tool_guard_* / mate_workspace / ... │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
一个 JAR。一个进程。The whole widget。
仓库布局
mateclaw/
├── mateclaw-server/ # Spring Boot 后端（心脏）
│ └── src/main/java/vip/mate/
│ ├── MateClawApplication.java
│ ├── agent/ # 原生 ReAct、计划策略与状态
│ ├── planning/ # Plan 和 SubPlan 持久化
│ ├── workflow/ # 工作流引擎（1.3.0+）：DSL 编译、线性 runtime、payload spill
│ ├── trigger/ # 触发器引擎（1.3.0+）：6 种 pattern、事件治理、CronDelegationPort
│ ├── tool/ # ToolRegistry、@Tool bean、MCP（per-agent 绑定）、guard
│ ├── approval/ # 审批工作流（兼任 workflow 的 await_approval 暂停/恢复桥接）
│ ├── skill/ # 动态技能包
│ ├── wiki/ # LLM Wiki + Transformations 引擎（1.3.0+）
│ ├── memory/ # 记忆层 + SPI
│ ├── workspace/ # 工作空间实体 + 会话 + 文档
│ ├── channel/ # 渠道 SPI + 适配器（1.3.0+: WeCom v2、reply queue、leader lease）
│ ├── llm/ # LLM provider 配置（1.3.0+: 多模态 sidecar 路由）
│ ├── auth/ # Spring Security + JWT
│ ├── audit/ # 审计事件管道
│ ├── cron/ # 定时任务引擎（trigger.cron 通过 CronDelegationPort 复用）
│ ├── task/ # 异步任务运行时
│ ├── dashboard/ # 指标聚合
│ ├── datasource/ # 外部 DB 连接
│ ├── stt/ # 语音转文字
│ ├── tts/ # 文字转语音
│ ├── system/ # 系统设置、bootstrap、引导
│ ├── config/ # Spring 配置
│ ├── common/ # 共享工具
│ └── exception/ # 全局异常处理器
│ └── src/main/resources/
│ ├── application.yml
│ ├── db/migration/ # Flyway 迁移脚本（h2/ + mysql/）
│ ├── db/data.sql # 种子数据
│ ├── prompts/ # LLM prompt 模板
│ ├── skills/ # 捆绑的技能包
│ └── static/ # 前端构建产物
├── mateclaw-ui/ # Vue 3 管理控制台
├── mateclaw-desktop/ # Electron 桌面壳
├── mateclaw-webchat/ # 可嵌入的聊天小部件
├── matevip-sites/ # 营销和文档站点（pnpm workspace）
├── docs/ # 这份文档（VitePress）
├── deploy/ # 生产部署配置
├── docker-compose.yml
└── .env.example
后端是一个模块化的单体。其他项目是不和后端共享代码的独立包。
原生 ReAct 与显式计划阶段
后端使用 Java 21、Spring Boot 4.1.1、Spring AI 2.0.1 和 AgentScope Java 2.0.4。NativePolicyDriver 为每次调用创建独立的原生 ReActAgent，由 SDK 管理推理/行动循环。应用策略继续管理提示词、审批、观察、总结与目标预算。
请求与预算归属
AgentScope 2.0.4 管理循环编排，Spring AI/provider 适配器负责实际模型请求准备。PromptBudget 在推理预检与压缩模型调用之间共享生效选项的预算估算，不替代供应商请求序列化。工具审批、工作空间保护、Goal 预算和完成验收门仍由应用负责。预算说明
关键文件
agent/runtime/agentscope/NativePolicyDriver.java——原生循环与应用策略回调agent/runtime/agentscope/ApplicationGuardedToolkit.java——受保护的整批执行入口；SDK 回调只提供 schemaagent/runtime/plan/ExplicitPlanRuntime.java——计划生成、步骤推进、总结与目标阶段agent/graph/plan/node/StepExecutionNode.java——每个计划步骤的内部工具循环使用原生 ReActagent/graph/executor/ToolExecutionExecutor.java——已有工具保护、审批、执行归因与结果agent/runtime/state/RunState.java+RunStep.java——独立状态与带版本的调用内快照agent/AgentGraphBuilder.java——按 Agent 配置装配运行时agent/graph/StateGraphReActAgent.java+agent/graph/plan/StateGraphPlanExecuteAgent.java——保留名称的应用封装类；这些名称不代表 Alibaba 图框架依赖
历史与扩展边界
应用会话消息仍是提示词的权威来源和持久化产品记录。SDK 临时历史只用于编排，不单独持久化。原生 pending-tool recovery 已关闭；内部快照成功不代表外部副作用可以安全重放。
业务行为通过已有节点、dispatcher 与 MateClawStateKeys 修改，并由 AgentGraphBuilder 接入。ReasoningNode 每次只执行一轮模型策略；ActionNode.executeBatch / completeBatch 分离受保护执行与完成策略。GraphEventPublisher 与 NodeStreamingChatHelper 继续维持应用 SSE 契约。
Spring AI 接口仍是模型/工具插件边界。原生 DashScope 对话和 embedding 适配器替代 Alibaba AI starter，独立的 DashScope SDK 继续支持语音集成。
目标评估节点（1.4.0+）
图（ReAct 和 Plan-Execute 都有）现在在 FinalAnswerNode 把最终答案流式输出之后再跑一个 GoalEvaluationNode：1.5.0 起它逐条裁决目标的 checklist 准则（bootstrap / verdict 两模式），全部准则通过才算完成，并可选地注入一条针对剩余准则的自动跟进消息，把没达成的目标继续推进。
其他 1.4.0 运行时变化
- 渐进式工具/技能披露——工具披露层把工具分成核心层（core）和扩展层（extension）两档；
enable_tool/load_skill让员工按需激活扩展工具、按需加载技能，从而把系统提示保持得足够小。 - 多级子员工委派树——父员工到子员工的委派是递归的、有深度上限的，构成一棵树；子图的事件实时回流到根会话。
- ChannelToolProvider SPI——渠道（比如飞书）可以把平台能力直接作为员工工具暴露出来，不需要单独的 MCP 服务器。
- 工作空间 RBAC——能力（capability）由后端的「角色 → 能力」映射解析，同时门禁 REST 接口和前端路由/菜单。
共享 state key
| Key | 用途 |
|---|---|
USER_MESSAGE |
当前用户输入 |
MESSAGES |
从 mate_message 加载的会话消息 |
OBSERVATION_HISTORY |
本回合的工具调用结果 |
CURRENT_ITERATION |
已经循环过多少次 |
MAX_ITERATIONS |
上限 |
TOOL_CALLS |
当前工具调用列表 |
AWAITING_APPROVAL |
有调用需要人工审批时置 true |
FINAL_ANSWER |
Agent 的响应 |
FINISH_REASON |
图为什么结束 |
数据流 —— 单次回合
1. POST /api/v1/chat?agentId={id} （或 POST /api/v1/chat/stream，agentId 在 body 里）
↓
2. ChatController.sendMessage()
↓
3. ConversationManager.loadOrCreate(conversationId)
↓
4. AgentGraphBuilder.build(agentEntity) ← 解析运行时
↓
5. runtime.stream(initialState) ← 原生循环 / 应用阶段开始
↓
ReasoningNode → Dispatcher → ActionNode → ObservationNode →（循环或结束）
↓
6. 工具调用走：
ToolRegistry.resolve() →
Tool Guard 规则评估 →
（需要审批时）mate_tool_approval 行 + SSE 事件 + AWAITING_APPROVAL=true
（内联允许时）ToolExecutionExecutor.execute() → observation
↓
7. Segment 通过以下方式流到客户端：
GraphEventPublisher → NodeStreamingChatHelper → SSE 流
↓
8. 结束时：
FinalAnswerNode 聚合结果
ConversationManager 把 segment 持久化到 mate_message
ConversationCompletedEvent 发出（异步记忆提取启动）
↓
9. 响应关闭
扩展点
这些是你可以在上面建东西的 SPI 和插件点：
@Tool 标注的 Spring bean
写一个带 @Tool 方法的 @Component。启动时被 ToolRegistry 捡起来。每个 @Tool 方法都成为一个可调用工具。
@Component
public class MyCustomTool {
@Tool(description = "LLM 看到的描述")
public String doThing(@ToolParam(description = "...") String input) {
return "result";
}
}
ChannelAdapter SPI
实现 vip.mate.channel.ChannelAdapter（或支持流式的 StreamingChannelAdapter）。注册成 Spring bean。通过 ChannelWebhookController 加 webhook 端点。见 多渠道接入。
public interface ChannelAdapter {
void onMessage(ChannelMessage message);
void sendMessage(String channelId, String content);
String getChannelType();
}
MemoryProvider SPI
实现 vip.mate.memory.spi.MemoryProvider 来插入自定义记忆后端（向量、图、外部服务）。多个 provider 可以在 Agent 上堆叠。见 记忆系统。
MCP 服务
通过 stdio、streamable_http、sse 连接外部工具服务。它们的工具自动出现在工具注册表里——Agent 代码不知道它们是外部的。见 MCP 协议。
技能包
把指令 + 工具 + 可选脚本打包进一个 SKILL.md。通过 UI 或 API 上传。Agent 在运行时可以调用它们。见 技能系统。
Agent 图节点和边
更深的定制——在 agent/graph/node/ 加新节点或在 agent/graph/edge/ 加新 dispatcher。在配置 flag 后面接进 AgentGraphBuilder。State 访问走 MateClawStateAccessor。
持久化 —— 一份 schema，两种数据库
MateClaw 用 MyBatis Plus（不是 JPA）做数据库访问。约定：
- 所有表前缀
mate_ snake_case列、camelCaseJava 字段、自动映射- 每张表有
create_time、update_time、deleted（逻辑删除） - Flyway 管理 schema 迁移——
db/migration/h2/和db/migration/mysql/各有一套方言脚本，启动时自动选择 FlywayRepairConfig默认执行开启校验的migrate()；修复历史记录必须显式开启，操作前参阅数据库恢复说明- 种子数据由
DatabaseBootstrapRunner从db/data-*.sql加载，幂等执行
表分组
身份和配置——mate_user、mate_system_setting、mate_model_config、mate_model_provider、mate_datasource、mate_mcp_server
Agent 和计划——mate_agent、mate_agent_skill、mate_agent_tool、mate_plan、mate_sub_plan
会话——mate_conversation、mate_message、mate_channel、mate_channel_session
工具和审批——mate_tool、mate_tool_approval、mate_tool_guard_rule、mate_tool_guard_config、mate_tool_guard_audit_log
技能和工作空间——mate_skill、mate_workspace、mate_workspace_member、mate_workspace_file
知识和记忆——mate_wiki_knowledge_base、mate_wiki_raw_material、mate_wiki_page、mate_wiki_transformation、mate_wiki_transformation_run（1.3.0+）、mate_memory_recall
工作流和触发器（1.3.0+）——mate_workflow、mate_workflow_revision、mate_workflow_run、mate_workflow_step_run、mate_workflow_payload、mate_trigger、mate_trigger_event
运维——mate_cron_job、mate_cron_job_run、mate_async_task、mate_usage_daily、mate_audit_event、mate_doctor_check
流式 —— 为什么用 SSE 不用 WebFlux
MateClaw 用 Spring MVC，不是 Spring WebFlux。WebFlux 在依赖图里被明确排除。
为什么：Spring MVC + SSE 足以把 LLM 响应流式到前端。它更容易推理、更容易调试、不强迫整个栈变成响应式。
::: tip 虚拟线程（JDK 21）
spring.threads.virtual.enabled=true 已开启。Tomcat 请求线程、@Scheduled 任务和 @Async 方法全部运行在虚拟线程上。SSE 长连接不再占用平台线程——并发连接数不再受线程池大小约束。
:::
流式流程：
- 客户端
POST /api/v1/chat/stream，body 里带agentId/message/conversationId，请求头加Accept: text/event-stream - Controller 返回
SseEmitter - Agent 图在工作线程上运行；节点执行把事件发给
GraphEventPublisher - 事件序列化成 SSE 格式写进 emitter
ChatStreamTracker监视被遗弃的流并清理它们
同样的 SSE 模式被支持流式的渠道适配器复用（钉钉 AI Card、Web）。
前端架构
Vue 3 + TypeScript + Composition API + <script setup> 到处都是。关键部件：
src/views/——页面组件src/stores/——Pinia store，领域驱动（每个 store 独占自己的切片）src/composables/——Composition API 辅助（聊天流式住在这里，不在全局 store 里）src/api/——Axios 实例 + 端点定义src/router/——带认证守卫和基于角色隐藏的 Vue Routersrc/i18n/——zh-CN.ts和en-US.ts翻译src/assets/main.css——--mc-*CSS 设计 token（主题化的单一事实源）
三个交付面
同一份后端 JAR，三种发布方式：
- Web——直接跑 JAR，浏览器打开
http://localhost:18088。前端嵌入 JAR 的static/。 - 桌面——
mateclaw-desktop/里的 Electron 壳捆绑 JRE 21 和 JAR。用户永远不装 Java。通过 electron-updater 自动更新。 - Docker——
docker-compose.yml带 MySQL。生产部署。
mateclaw-webchat/ 里的 webchat widget 是第四条路——一个你可以丢进任何网站的可嵌入聊天 UI。它和同样的后端 API 对话。
请求分层
HTTP 请求
│
▼
Spring Security Filter ── JWT 校验、滑动窗口续签
│
▼
基于角色的访问 Filter ── 工作空间权限
│
▼
Controller ── @RestController
│
▼
Service ── 业务逻辑
│
▼
Mapper（MyBatis Plus） ── SQL
│
▼
数据库（H2 / MySQL）
每一层单一职责。跨层的关注点（审计日志、指标）用 AOP 切面或 Spring Boot Actuator 端点实现。
::: tip Spring AI 可观测性
Spring AI 内置的 Micrometer Observation 已开启——每次 LLM 调用自动记录 gen_ai.client.operation（延迟）和 gen_ai.client.token.usage（input/output token）。通过 /actuator/metrics/gen_ai.* 端点查看。prompt 内容不会泄露到 span 中（log-prompt=false）。
:::