MateClaw

中文

English

中文

English

Appearance

v1.3.0 ​

正式版 · 2026-05-13 · 上一稳定版本 v1.2.0

这一版做了五件事 ​

让我直接说。

v1.2.0 我们把 Agent 改名成"数字员工"。但员工各自能干活只是起点——真正的协作需要编排。

这一版我们补完了那块拼图。

第一，工作流（Workflow）出来了。 把多个员工 + 系统动作按线性 step 编排成一条业务流程。 第二，触发器（Trigger）出来了。 让"系统里发生的事"自动启动工作流或员工对话。 第三，Wiki 不再只是搜索索引——它是处理流水线。 用模板把每份原料和每张页面变成结构化产物。 第四，每个员工可以单独绑定 MCP 工具；多模态旁路自动路由。 不再"一个 MCP 服务器开了所有人都看见"。 第五，从对话直接产出 Office 文件。 Docx / Xlsx / Pptx / PDF 四个文档生成工具开箱即用。

就这样。

一、工作流——MateClaw 从 chatbot 升级为业务流程 OS ​

之前你想让"先让数据分析师整理客户、再让企业销售员工跑 VIP onboarding、同时发飞书和邮件、两边都回了再写记忆"这种流程跑起来——只能自己拼 prompt、自己写 cron、自己处理审批。

这一版我们把这些拼装活做完了。

打开工作流（Workflow）菜单——你看到一份线性 step 数组 + 一个 mode 字段。就这样。不是 30+ 节点的 Dify-style，不是 if/else 拖拉框。刻意保持极简。

7 种 step mode 覆盖你 90% 的业务流：

  • sequential——顺序执行，上一步 output 自动喂给下一步
  • fan_out / collect——并行扇出多个 step，然后收口
  • conditional——Pebble 表达式 true 才执行
  • await_approval——暂停 run，发审批，resume 后继续；服务重启不丢
  • dispatch_channel——把上一步输出多渠道分发
  • write_memory——把结果写进员工的 MEMORY.md（4 种合并策略：append / replace_section / upsert_kv / overwrite）

编辑器有两条路径：

  • JSON 优先（Monaco + JSON schema 校验 + Pebble 静态检查 + 模板下拉）——给会写 DSL 的人。打字时实时标红，发布前编译诊断。
  • @vue-flow/core 画布——给想看清楚结构的人。当前是只读链式渲染（可拖拉编辑下一版本上）。

不会写 DSL 怎么办？——打开自然语言生成草稿（POST /workflows/draft/generate）。用一句话描述你想要的流程，Agent 帮你生成 graph_json + 编译诊断。它不直接发布——给你看，你审，你按"发布"。

还有几个工程细节，看不见但重要：

  • 整数 revision——发布写新行不可变；草稿和已发布版本分离。不会因为别人改了草稿，你正在跑的 run 突然换语义
  • payload 内置存储——大 input/output 走 payload:// URI，不撑数据库
  • 跨 workspace ACL——发布期校验 agent / channel / employeeId 引用都在当前 workspace 内
  • 运行历史——每一步的 input / output / 耗时 / token / 失败链路都被记录，可以打开任意一次 run 重看
  • 异步 dispatch + GC schedulers——一次发布、长跑的工作流不会卡住请求线程

工作流不是 ReAct / Plan-and-Execute 的替代品。单个员工的多轮推理仍然在那两条引擎里。工作流是把员工组装成业务流——把"一次任务"升级为"一条流程"。

二、触发器——让事件驱动工作流 ​

工作流写好了，谁来启动它？

之前的答案是：手动。或者你自己写 cron。或者你自己加 webhook 接口。

这一版我们把这个统一了。触发器（Trigger）——把"系统里发生的事件"和"要执行的动作"连起来。

6 种 pattern type，覆盖你能想到的所有触发场景：

Pattern什么时候触发
cron定时（cron 表达式）—— 复用老 cron 模块的 ShedLock + Spring TaskScheduler
webhook通用事件入口透传 —— POST /api/v1/triggers/events
channel_message渠道收到消息 —— 按 channelType + senderEquals 过滤
agent_lifecycle员工生命周期事件 —— spawned / terminated / crashed
content_match内容 substring 匹配（大小写不敏感）
workflow_completion上游工作流跑完进入终态

**动作两种：**启动一个工作流，或直接给员工发条消息让它处理。

安全治理默认开——这是关键：

  • 事件去重——dedup_key 在默认 60s 时窗内已入过库的事件直接丢弃
  • per-trigger rate limit——每分钟默认上限 10，避免一条 trigger 把队列堵死
  • Bot self-msg 过滤——飞书/钉钉/企微把 bot 自己发的消息回流为事件？默认绑定 SPI 让 channel 适配器侧识别并丢弃
  • 递归循环保护——workflow_completion 触发的工作流又触发另一个 workflow_completion……dispatch 链超过 5 层引擎切断 + 告警
  • 未知 pattern type fail-closed——typo 或将来加的 pattern 不会偷偷把 workspace 内所有 trigger 都点燃

跨实例一致性——多实例部署里，trigger 的 pattern_version 自取消机制 + 周期 syncFromDatabase 让所有节点看见同一份 trigger 状态。cron 类 trigger 经 CronDelegationPort 抢 ShedLock 锁，只跑一次。

Webhook ACK 时序故意设计为 fire-and-forget——入口收到事件 → envelope wrap → dedup check → bot-self check → rate limit check → 立即 ACK 200 → 异步 dispatch。上游网关拿到 200 就不再重投。

UI 上 6 种 pattern 各有专属表单。——不需要手写 patternJson。选 cron 给你 cron 表达式输入框 + 时区下拉 + 试运行下一次触发时间预览；选 content_match 给你 substring 输入框；选 agent_lifecycle 给你 agent 下拉 + phase 下拉。

三、Wiki 不再只是搜索索引——它是处理流水线 ​

之前的 Wiki 是这样工作的——你扔一份文档进去，它切块、向量化、能被语义搜索召回。单向。原料进，召回出。

这一版我们让 Wiki 学会处理。

Transformations 引擎——给每份原料、每张页面套一个"模板"，让它跑一次 LLM，把结构化结果存回 Wiki。

具体来说：

  • 用户自定义模板——你写一段 prompt，配模型、输出格式（markdown / json）、是否自动存为合成页（synthesis page）
  • 每个模板一个模型选择器——分析合同用 Claude Opus，做摘要用便宜的 Flash，不再"一个 LLM 跑所有事"
  • 可以对页面跑模板——不只是处理原料，把一张已有的合成页喂回模板再产出一张新页面
  • 跨材料聚合（map-reduce）——把同一个模板在 KB 里所有原料上的运行结果，map-reduce 成一张 KB 页面。这是真正的合成
  • Reverse-citation extractor——合成页绑定到它引用的源 chunk。点开页面看见它从哪一段话学来的
  • 结构化 JSON 输出 + 可选 JSON Schema——下游程序可以直接消费，不用解析 markdown
  • 取消正在跑的 transformation + 重跑历史 run——长任务跑一半发现 prompt 错了？取消，改 prompt，重跑
  • 每一次 run 的 token 用量被记录——你看得见每个模板烧了多少钱
  • 两次 run 并排比较——改了 prompt 想看效果差异？打开 compare modal

7 个开箱模板——对齐企业典型场景：合同条款抽取、客户情报、风险摘要、KPI 提炼、会议纪要规整、知识页结构化、问答对生成。装好就能用。

合成页本身也进入语义搜索——page-level embedding。这意味着 Wiki 的搜索结果里不再只是"原始文档块"，还有"被你/Agent 处理过的产物"。

Wiki UI 也重做了——library home + workspace split。库首页 = 你这个 workspace 下所有 KB 的入口；进入某个 KB = 原料 / 页面 / 模板 / runs 四个 tab。

这意味着 Wiki 从"被动检索"升级为"主动加工"。原料进去之后不是等着被召回——它被模板转换成更有用的产物，然后那些产物再被检索。

四、MCP per-agent 工具绑定 + 多模态旁路 ​

之前接一个 MCP 服务器，整个 workspace 里所有员工都看到那一堆工具。你给行政助理装了 GitHub MCP，结果客户支持也以为自己能开 PR。

这是工程师在偷懒。

这一版我们改了。

每个员工独立绑定 MCP 工具：

  • 工具选择器里，按 server 分组、按状态分类——connected / stale / unavailable / orphan
  • 保存时校验：你绑定的工具在当前的 MCP server 上真的存在吗？不存在直接报错，不让你发布一个会跑挂的 agent
  • 命名空间冲突自动前缀化——两个 server 都有 search 工具？前缀化为 server-a:search / server-b:search，调用时不歧义
  • Server 改名自动跟随——你重命名了 MCP server，绑定关系不丢
  • 稳定的 prefixed callback 名 + 每个 server 工具列表落库缓存——重启不需要重新探活

MCP 派生的技能/工具也走统一的 agent 选择器接口。——这意味着你看到的"工具市场"和员工"我能用什么"是同一个视图。

多模态旁路路由（sidecar）——issue #87

之前你把一张图片发给只懂文字的主模型（比如 DeepSeek V3.5）——它会直接拒答或者瞎猜。这是工程师的妥协："你应该选个视觉模型。"

这是错的。 用户不该为你的模型选型负责。

这一版做了旁路路由——主模型是纯文本的，遇到图片附件自动调用配置好的视觉模型转描述，再把描述塞进主对话。主对话保持便宜，视觉只在需要时被调起。

  • 设置 → 多模态 里配置 sidecar 视觉模型——挑一个能看图的 provider（GPT-4V / Claude Sonnet / GLM-V / Doubao Vision 都行）
  • 输入框上方的路由徽章——你能看见这条消息是"主模型直答"还是"先走 sidecar"，路径全程可见
  • assistant 气泡上的回答模型署名——这一段是哪个模型答的，写在气泡边上

附带把"硬禁令"拆掉了——之前用户自定义工具会被一段硬编码的"如果用户问 X，必须答 Y"压制。这一版尊重用户配置——你装的工具，你说了算。

五、从对话直接产出 Office 文件 + 图像编辑 ​

员工写完一份合同摘要，你说"给我导出成 Word"——之前要么 Agent 给你 markdown 让你自己复制，要么得装一个 npm 子进程脚本。

这一版四个文档生成工具直接在 JVM 里跑，不 fork 子进程、不依赖 npm、不需要 Office 装机：

  • DocxRenderTool——Markdown → .docx，标题层级 / 列表 / 表格 / 图片直接渲染
  • XlsxRenderTool——Markdown 表格 → .xlsx，多 sheet 支持
  • PptxRenderTool——Markdown 节标题 → 一节一页 .pptx
  • PdfRenderTool——Markdown → .pdf，原生中文支持

和老的 docx 技能并存——分工明确： 老技能负责"改一份已经存在的 Word 文档"（保留样式 + 跟踪修订）；新工具负责"从头生成"。

图像编辑（issue #75）——image_generate 工具新增 image / images 参数，5 种引用形式：

  1. 一张 https:// URL
  2. 一张 data:image/png;base64,... 内联
  3. 一个 attachment://<id> 引用本次消息附件
  4. 一个 msg:<conversationId>:<attachmentIndex> 引用会话里更早的某张图
  5. 多张 URL/路径数组组合（多图融合）

意思是——你对一张已经聊过的图说"把它改成红色背景"，Agent 直接用第 4 种引用回到那张图，调用 image_edit 模型改色，不用让你重新上传。

新模型：

  • DashScope 兼容模式——同一把 sk- key 接通点号版本号系列（qwen3.5-plus / qwen3.6-plus / qwen3-vl-plus 等）
  • 新万相 / qwen-image 系列——14 个新图像模型，3 个新视频模型（含 happyhorse-1.0-t2v）
  • 小米 MiMo provider——MiMo V2.5 Pro / V2.5 / V2 Pro / V2 Omni / V2 Flash
  • 腾讯混元 3D——已经在 v1.2.0 接入；这一版补完图标和路由

render_html_image 工具——员工生成的 HTML 内容直接渲染成图片发到 IM 渠道，免去"图片格式不支持"的尴尬。

上下文工程继续打磨——长任务不再丢记忆 ​

数字员工跑 30 步以上的长任务时，最大的问题不是模型不够聪明，是它会忘。

这一版我们在上下文层做了几件看不见但决定成败的事：

  • 首条用户消息被锚定——压缩历史时不会被踢出窗口。你最初的目标永远在
  • 绝不跨 tool_call ↔ tool_response 边界压缩——之前压缩可能把"调用工具"和"工具回来"切开，模型只看见一半，后面整个 reasoning 失稳。现在绝不切
  • 老 tool 结果保留原文，不再被改写成"有损摘要"。该 spill 到磁盘的 spill，不该改写的不改写
  • spill 标记跨多次压缩持续存在——你跑一个三轮 compaction 的长任务，spill 引用不会突然失效
  • compact_status SSE 事件——前端能感知压缩进度，从最新边界加载历史，不显示"残页"
  • 头部 orphan tool response 修复——分页边界上孤立的 tool 回包（顺序敏感扫描）被回收，不污染下一轮
  • 每个会话的 spill 文件——按 retention 策略定期清理 + 会话删除时一并清掉

还有几件流式上的事：

  • 流式 tool-call 参数实时 sanitize 成合法 JSON——LLM 边吐边修，到对端时一定是合法 JSON
  • 重复检测升级——员工自言自语原地踏步？content-repetition cap 直接打断，不让它把 token 烧光
  • 非瞬时错误的"恢复卡片"——LLM 报了一个不会自愈的错（比如 quota 超）？UI 上一张卡片告诉你怎么办，不再让你盯着旋转的 spinner
  • 瞬时 TLS / socket 错误重试——网络抖动一下，重试就过去，不报红色错误

还有一些事 ​

渠道（企微深度调优）：

  • 企微"审批卡片"——发出去的卡片有 keepalive，长任务不会被对端会话超时杀掉
  • 群聊多人对话——按 sender id 单独归属、按时间窗口去抖；不再因为群里两个人同时说话把对话搞混
  • 粘贴长消息自适应去抖窗口——一段被切成 5 条的长粘贴，自动合并成一条
  • 企微引用消息的上下文解析——员工能读懂你引用的是哪条历史消息
  • 企微文件管道补完——上传大小预检 + 群回复 fallback + 公众号文章 paste-body 提示
  • 异步工具结果回流 IM——长任务跑完后回流到原发起渠道（飞书 / 钉钉 / 企微 / Slack），文件附件按渠道分别上传
  • WS / 长轮询渠道走 leader lease——多实例不再因为重复连接出现两条回应
  • 修掉一批假生成的文件 URL——员工不再编造"https://example.com/file.docx"

企业场景工作台：合同审阅 + 客户情报 + 审批 + 审计在同一个 workbench 里。每个面板支持滚动、步骤垂直居中。这是 v1.4 场景应用的预览。

部署 / 构建：

  • Docker 不再强制 DASHSCOPE_API_KEY——你想用 OpenAI / Ollama / 任意 provider，启动就行
  • 5 个重量级内置技能改为 optional——SKILL frontmatter 的 optional: true 让默认不装，按需开启，省启动时间
  • mateclaw-ui 构建堆调到 6GB + pnpm 锁到 v10 + 白名单 build 脚本——别人 fork 之后第一次构建不再 OOM
  • Spring AI 1.1.5 → 1.1.6 / Spring AI Alibaba 1.1.2.2 → 1.1.2.3

LLM / Provider：

  • OpenAI Whisper STT 现在可以路由到任何 OpenAI-compatible 端点（issue #76）
  • OpenAI 兼容 HTTP 客户端钉到 HTTP/1.1——某些代理对 HTTP/2 不友好导致 TLS 错乱
  • 自定义 OpenAI-compatible provider 可以不要 API Key（issue #89）——本地代理用
  • OAuth 之后自动激活默认模型——登录完不用再手动挑一个

修复（你不会注意到、但会让你少骂一句的）：

  • 对话删除是真删除——级联清理 message / approval / async-task / 取消正在跑的 worker，不留孤儿数据（issue #66 之类的根因）
  • assistant 消息因列截断丢失被堵住——同时 JDBC 字符集修正为 Java 命名 UTF-8
  • tool guard 规则空行守卫——一个空 rule 不再让整个 guard 模块崩溃
  • digital-employee 隔离硬化——创建 / 技能绑定 / prompt 目录全链路加锁
  • agent 模板应用时预绑定技能和工具——template 选完就能用，不用再去翻设置
  • 同名 agent 保存失败时显式提示重名——不再是个糊涂的 toast
  • MCP 虚拟卡（来自 MCP server / ACP）禁止编辑/扫描（issue #83）
  • MCP 服务器名保留中文（issue #65）
  • MCP 工具自动进 effective 白名单（issue #108）——不用每次新增一个 server 都跑去配 allowlist
  • i18n 模板里的 JSON 例子转义——vue-i18n 不再把它当 interpolation 解析
  • clipboard 复制在非 HTTPS 环境降级——本地 IP 跑也能用
  • OCR 在 PDF 文本抽取不可读时自动触发
  • 聊天 LLM popup 按行 ping 探活——每一行都告诉你这个模型是否可用
  • mermaid 流式渲染防闪烁 + 复制/下载按钮——Agent 边吐 mermaid 边渲染不再来回跳

完整清单：git log v1.2.0..HEAD。

升级路径 ​

配置完全兼容。 升级前后你的所有 agent / skill / wiki / channel / cron 都不动。

新增表 schema 由 Flyway 自动迁移。——工作流（mate_workflow*）、触发器（mate_trigger*）、wiki transformations（mate_wiki_transformation*）相关表第一次启动自动创建，已有的库自动 baseline。

已经在生产用 v1.2.0 的用户：

  • 升级即可看到工作流和触发器菜单。先在内部 workspace 跑通一条 demo 流程（比如"每天 9 点跑客户晨报"）再推广
  • MCP per-agent 绑定首次升级会自动迁移——之前 workspace 级的 MCP server 配置不变，每个 agent 默认绑定全量（保留旧行为），再按需收紧
  • 多模态 sidecar 默认不开——你不配视觉模型，主模型遇到图片继续按之前的行为处理。配了才走旁路

这一版对你意味着什么 ​

如果你是普通用户——

去试 5 个开箱工作流模板：晨报、合同审阅、客户情报、审批分发、知识页定期合成。不用学 DSL，用结构化表单点几下就跑得起来。

如果你管理一个团队——

把"每天 9 点把昨天的客户问题汇总成报表发到运营群"这种流程，写一遍工作流，从此交给系统。员工不再因为你发的 prompt 变化而漂移——流程是固定的，每个环节谁负责是固定的。

如果你是开发者——

JSON-first DSL + Monaco + schema 校验。用 POST /workflows/draft/generate 让 Agent 帮你拉草稿，然后自己审。trigger 端的 webhook entry 是 POST /api/v1/triggers/events——直接接你现有系统。

如果你跑生产环境——

升级。新建几条 trigger 试一下默认治理（去重 / rate limit / bot self-msg / 递归保护）。多实例部署的 CronDelegationPort 让 cron 跨节点只跑一次。

如果你之前因为某个东西放弃了——

回来试一次。MCP 工具现在按员工独立绑定，多模态自动旁路，Office 文件直接生成，Wiki 学会了加工。每一处都是因为有真实用户被卡住才修的。

One more thing. ​

数字员工。工作流。触发器。

一个员工独立工作，是工具。多个员工按流程协作，是组织。事件能自动启动这套组织，是操作系统。

这才是个人 AI 操作系统该有的样子。