MateClaw

中文

English

中文

English

Appearance

v1.4.0 ​

正式版 · 2026-05-23 · 上一稳定版本 v1.3.0

这一版做了五件事 ​

让我直接说。

v1.3.0 我们把员工组装成业务流程——工作流、触发器，让一组员工按流程协作。但流程是你写死的，员工本身还是"答完一轮就停"。

这一版我们把焦点放回员工自己身上：让单个员工更自主、能组建并带领子团队、工具集随任务伸缩，再让整个系统多人可用、把飞书做成一等公民。

第一，持久化目标（Goal）出来了。 你说一次目标，员工锁住它、每轮自检、自己续命，直到完成或耗尽预算。 第二，子员工委派变成一棵树。 员工能委派员工，递归三层；还能异步委派、用「数字员工构建器」一句话拉起一支团队。 第三，渐进式工具/技能披露。 默认只暴露核心工具，需要时员工自己 enable_tool / load_skill。工具再多，上下文不爆。 第四，工作空间 RBAC。 Owner / Admin / Member / Viewer 四级角色 + 能力门禁，菜单和接口按角色收口。MateClaw 第一次能给团队用。 第五，飞书做成一等公民。 互动卡片、审批卡片、流式卡片、语音转写、文件音视频收发、渠道原生工具——飞书里能干的事，员工都能干。

就这样。

一、持久化目标——员工自己跟，不用你每轮催 ​

之前一次对话里你说"帮我把这个博客部署到 fly.io"，员工答完一轮就停了。下一轮你得再问"DNS 配好没？证书呢？测试跑了吗？"——你在替它记目标。

这一版我们把这件事翻过来。你说一次，员工锁住目标，自己每轮自检：还差什么？要不要自己再做一步？

它不是聊天里的一个新按钮。它是员工的一种状态——assistant 头像周围多了一圈光，光填多少就是离完成多远。完成了，光消失。hover 头像才显示完整 tooltip（标题 + 还差什么）；不 hover 就不打扰你。

怎么定一个目标——三种方式：

  • 让员工自己定——第一次描述任务时让它知道这是个长任务，明确要求"用 setGoal 锁定，turnBudget=8，autoFollowup 开启"，员工识别到信号自动建目标
  • 直接命令工具——告诉它调 setGoal、传什么参数、"不要问前置确认"
  • API 程序化创建——POST /api/v1/goals，给自动化和外部脚本用

4 个内置工具，员工默认就有（agent-wide 系统级，无需手动绑定）：setGoal（创建）、addGoalCriterion（追加准则）、completeGoal（标记完成）、getGoalStatus（查进度）。

自动延续是关键。 开了 autoFollowupEnabled 之后，员工答完一轮，后台跑一个轻量 evaluator 判完成度（0~1）和"还差什么"，如果判"continue"就给对话末尾注入一条 follow-up，让员工自己接着做下一步。你的体感是：员工答完一段 → 停半拍 → 继续往下做，像一个人做完一步想了想再继续。

几条刻意的约束：

  • 评估发生在回答串完之后——不阻塞你看回答，看到回答出现后头像旁的光环才变化
  • 一会话一目标——同一时刻最多一个 active goal，靠生成列 + 唯一索引保证并发安全
  • 子员工看不到 goal 工具——目标是 parent 会话的状态，child 是无状态执行体（见第二节）
  • 预算耗尽即终止——turnsUsed >= turnBudget 或 LLM 调用数用尽，状态翻 exhausted，光环变橙红，你决定加预算还是放手
  • 终态不可复活——completed / exhausted / abandoned 是终点，要继续就开新目标，避免重启带来的预算账目混乱

evaluator 建议指向便宜的小模型（mateclaw.goal.evaluator-model），完成时员工会把目标总结同步进长期记忆。完整说明见 持久化目标。

Goal 不是给员工加一个功能，是改它的状态。以前的员工"答完就忘"，现在它跨多轮记住一件事：在干什么、还差什么、什么时候算完。

二、子员工委派变成一棵树——员工能组建并带领团队 ​

v1.1.0 起员工就能委派别的员工干活。但那是"单层、同步、一次一个"。

这一版我们把它做成一棵树。

递归委派，最深 3 层。 parent 委派 child，child 还能再委派——一个"项目经理"员工可以拉起"前端 / 后端 / 测试"三个员工，每个再各自委派。每个子员工有稳定的 subagentId + parentSubagentId + depth，事件实时回流到根会话。

委派工具分三种：

工具行为
delegateToAgent同步委派一个子员工，拿到最终结果再返回；可选 inheritParentContext 把父对话最近上下文带过去
delegateParallel一次扇出多个子员工并行跑，全部收口后返回
delegateAsync后台异步委派，立刻拿到 task_id，之后用 taskOutput 取结果——长任务不堵住父对话

异步委派有归属门禁（attribution gate）——taskOutput 只允许同一个会话、同一个用户去取自己 spawn 的任务结果，不会被别的对话偷看。

子员工默认禁用一批工具——delegateToAgent / delegateParallel（防递归失控）、setGoal 系列和 remember 系列（目标和记忆的所有权留在 parent）、create_employee（防递归造团队）。可通过 mateclaw.delegation.child-denied-tools 调整。

UI 上你看得见整棵树。 聊天流里嵌套的子员工时间线 + 常驻的计划面板——委派开始、每个子员工的名字 / 深度 / 任务摘要、完成时的结果徽标（成功 / 超时 / 出错 / 耗时 / 内容长度），多级结构一眼看清。

「数字员工构建器」技能——一句话拉起一支团队。 你描述一个需求，这个内建技能会：理清诉求 → 设计 2~6 个角色 → 用 create_employee 逐个创建真实员工 → 把它们串进一个工作流草稿给你审。配套的 list_capability_catalog 让它先查清楚有哪些技能/工具可绑，再动手。员工建好即启用，绑定方式和模板套用一致。

长任务不再因为"prompt 太长"丢上下文。 结构化压缩做了四级策略（软裁剪 → 硬清空 → 预剪枝 → LLM 结构化摘要），始终保住前缀（系统提示 + 目标锚点），摘要以 UserMessage 注入。委派类工具结果永不被压缩（子执行不可复现）。失败后有 10 分钟冷却防级联。

一个员工独立工作是工具。一个员工带着一支自己组建的团队工作，是组织。

三、渐进式工具/技能披露——工具再多，上下文不爆 ​

之前的做法是：把员工能用的所有工具，连同每个工具的描述，一股脑塞进系统提示。工具一多，光是"我能用什么"就吃掉几千 token，模型还没开始干活，上下文先满了一半。

这是工程师在偷懒。

这一版我们改成两层披露：

  • 核心层（CORE）——始终对模型可见，开箱就能调
  • 扩展层（EXTENSION）——默认只在系统提示里列一张压缩目录（名称 + 来源 + 一句描述），不展开完整 schema。员工需要时自己点开

两个新内建工具是开关：

  • enable_tool(toolName)——把一个扩展层工具激活到本次对话剩余轮次。校验它确实在该员工的有效工具集里，激活后当前 ReAct 循环的下一轮就能调（ReasoningNode 每轮动态重算工具集，所以即时生效）
  • load_skill(skillName, filePath?)——按需加载一个技能的 SKILL.md。内容走消息历史注入（不是系统提示），既保住 prompt 缓存稳定，又把加载过的技能在后续轮次置顶，不用反复 load

默认分层：生成类工具（image_generate / music_generate / video_generate / model3d_generate）和 browser_use 默认进扩展层；其余默认核心层。工具页（Tools）有分层 UI——内建工具和渠道工具每行带分层切换按钮，管理员可以把工具在核心 / 扩展之间挪（MCP / ACP 来源的锁定不可改）。

给保守部署留了后路：mateclaw.tools.disclosure.mode=legacy 关掉分层、所有工具回到全量暴露；mateclaw.skill.disclosure.load-skill-tool.enabled=false 退回老的 readSkillFile。

系统提示该随任务伸缩，不是随工具总数伸缩。你给一个员工装 50 个工具，它不该为此每轮多烧几千 token。

四、工作空间 RBAC——MateClaw 第一次能给团队用 ​

之前 MateClaw 是单人系统——一个 admin，看得到一切、改得动一切。你想拉同事进来一起用？没有"只读"，没有"只能管自己负责的那摊"。

这一版我们补完了多人协作的地基。四级角色，能力门禁。

角色能做什么
Viewer只读——能聊天、看 Wiki；看不到管理面、不能创建/修改
Member内容贡献者——在 Viewer 基础上能管 Agent、管 Wiki、看记忆和仪表盘
Admin资源管理者——在 Member 基础上能管技能、渠道、模型、安全、设置
Owner工作空间所有者——能力同 Admin，外加删除工作空间、转移 owner

能力（capability）是后端单一事实源。 后端 RoleCapabilities 定义"角色 → 能力集"的映射，前端从不本地推导——切换工作空间或遇到能力相关的 403 后，前端调 GET /api/v1/workspaces/{id}/access 拿到 effectiveRole + capabilities，按它渲染。

  • 接口按角色收口——模型 / 提供商 / OAuth / 数据源等系统级接口要全局 admin（@RequireGlobalAdmin）；技能 / 工具 / 插件按工作空间角色（读要 member、写要 admin）
  • 前端路由和侧边栏按能力门禁——路由声明 requiredCapability，导航项按 store.can(cap) 过滤，能力没加载完不闪菜单；Viewer 直接落在 /chat
  • 全局 admin vs 工作空间角色——mate_user.role='admin' 是系统级全局管理员（管用户、建工作空间），mate_workspace_member.role 是按工作空间的成员角色；全局 admin 自动跨所有工作空间、对未加入的工作空间拥有 owner 等效权限

成员管理开箱即用。 POST /api/v1/workspaces/{id}/members 加成员——用户不存在就连带建账号（带密码），已存在且带密码就重置密码（处理重复拉人）。改角色、移除成员都要 admin+，owner 不可改/不可移。

Viewer 也能正常聊天——这一版特意放开：Viewer 能读取当前激活模型、能读员工的工作空间文件，否则"只读"会读到连天都聊不了。

完整说明见 安全与审批 和 工作空间。

一个人用 MateClaw，是个人助理。一个团队用 MateClaw、各自只看见自己该看的，是组织的操作系统。

五、飞书做成一等公民 ​

之前飞书只是"能收能发文本"。这一版我们把飞书做深——飞书里能干的事，员工基本都能干。

互动卡片（Interactive Card，Schema 2.0）——员工回的结构化内容（JSON、带表格/标题/列表的 Markdown、超长文本）自动渲染成飞书互动卡片，不再是一坨转义字符串。短的纯文本仍走文本。渠道设置里 card_format（默认 auto）控制；超过飞书 32KB payload 上限自动降级文本。

审批卡片（Approval Card）——工具审批流在飞书里直接发一张「同意 / 拒绝」按钮卡片。你点一下，系统注入合成的 /approve / /deny 消息，员工端到端把审批通过的动作真正跑完，不用你切回 Web。

流式卡片（CardKit Streaming）——员工的回答在飞书卡片里逐字吐出，不再等整段答完才发。500ms 节流，首 token 立即刷。card_streaming_enabled 默认开，建卡/投递失败自动回退累积发送。

语音 / 文件 / 音视频收发：

  • 入站语音转写——飞书语音消息经 SttService 转成文字喂给员工，员工看到的是内容而不是 [音频] 占位
  • 入站文件 / 音频 / 视频下载——不只图片，文件音视频都能下载、本地缓存、经 /api/v1/files/generated/{id} 给会话和 UI 渲染（media_download_enabled 这一版默认改为开，注意磁盘和隐私）
  • 出站生成文件转原生附件——员工回的 /api/v1/files/generated/{id} URL 自动转成飞书原生附件（图 10MB、文件音视频 30MB 上限，音频仅 opus、视频仅 mp4，其余降级为文件）

渠道原生工具（ChannelToolProvider SPI）——飞书的日历、文档等平台能力（feishu_calendar_list_events / feishu_doc_read / feishu_doc_create）直接作为员工工具暴露，不需要单独的 MCP 服务器、不用重复配凭证。读类工具默认开、写类工具默认要审批（DB 种子守卫规则自动给改写类工具挂 NEEDS_APPROVAL）。

还有几件：

  • 发送方上下文注入——员工 prompt 里带上"渠道 / 发送人 /（群聊）会话"信息，能按来源定制回答
  • 完成回执（DONE reaction）——回复成功后给原消息加一个 ✅ 反应（enable_done_reaction 默认开）
  • @提及过滤——require_mention=true 用飞书 SDK 的 mentions 字段过滤群里没 @ 机器人的消息；bot open_id 启动时预取 + 60s 负缓存

QQ 也加了扫码绑定——经 QQ 开放平台 Lite 门户扫码授权，不用手抄 AppID / AppSecret（AES-256-GCM 加密交换，12 分钟 TTL）。

IM 会话也尊重按会话选模型——和 Web 一致，每个会话能单独绑模型（见下文）。

详见 多渠道接入。

还有一些事 ​

模型 / 提供商：

  • 原生 Gemini 接入——Gemini 走原生 generateContent API（而不是 OpenAI 兼容凑合），新增 GeminiChatModel，正确处理 systemInstruction / functionCall / 内联图片，流式解析 SSE，并自动剔除 Gemini 不接受的 JSON Schema 关键字
  • Nano Banana 出图——Google 图像走 Nano Banana Pro（gemini-3-pro-image-preview），出图工具把输入图作为内联 part 传入，支持图像编辑
  • xAI / Grok 提供商——OpenAI 兼容方式接入，Grok 3 / Grok 4，UI 里有 xAI 品牌图标
  • 任意提供商配置嵌入模型（#79）——设置 → 模型 新增嵌入模型区，从任何提供商挑嵌入模型，复用该提供商的 API Key，知识库从下拉选它的嵌入模型；keyless 本地代理用 NoopApiKey
  • 小米 MiMo thinking 模式多轮修复（#189）——reasoning_content 跨轮对话正确保持

聊天体验：

  • 按会话选模型（#150）——聊天头部 ModelSelector 给每个会话单独绑模型，存在 mate_conversation，立即对下一条消息生效；没绑就用工作空间默认
  • 会话列表：置顶 / 多选删除 / 按员工过滤（#144）——⋮ 菜单置顶，进入多选模式批量删，2 个以上员工时出现按员工过滤下拉
  • 全局快捷键 Ctrl+K / Ctrl+N——Ctrl+K 开员工选择器跳转，Ctrl+N 新建会话，输入框内不误触
  • 会话管理页（Sessions）——头部菜单进入，服务端分页（按标题/ID 搜索）、深度卡片布局、行内模型芯片可改

调度 / 控制台：

  • Cron 和触发器合并为统一「调度（Scheduler）」页——三个 tab：定时任务 / 事件触发器 / 运行历史，配可视化 cron 构建器（分段编辑 + 预设 + 人类可读预览）
  • 新增 wiki_process 定时任务类型——给知识库排期跑处理（选 KB + 可选强制重处理），无需绑员工，异步入队
  • 运行时视图并入「员工」页——/backstage 跳到 /agents?view=live，员工页一个分段开关在"花名册 / 实时"间切
  • 侧边栏通知徽标——待审批（红色计数 → 安全页）、卡住的员工（橙色点 → 实时视图）
  • 仪表盘模型配置卡 + 引导式提供商启用——首屏看见已启用提供商、存活状态、激活模型

Wiki：

  • 新增原料格式：HTML / Excel / PowerPoint / CSV——HTML 经 jsoup 清掉 script/style/nav/footer 噪声，Excel/PPT 用 Apache POI，CSV 用 Tika
  • 知识库级联删除——一次事务删 KB → 原料 → 页面 → 引用 → chunk → 处理任务，UI 删除前提示原料和页面数让你看清爆炸半径
  • create_page 工具返回新页 id，KB 失败统计只算每条原料最新一次任务

记忆：

  • 员工记忆快照导出 / 导入——把员工的 AGENTS.md / MEMORY.md / PROFILE.md / SOUL.md / KNOWLEDGE.md + 每日台账打成 ZIP 备份/迁移；导入前有 dry-run 预览（新建 / 更新 / 跳过分类），白名单 + ZIP 炸弹防护（≤500 项、单项 ≤1MB、总 ≤16MB）。在「员工上下文」页右栏导出 / 导入
  • 记忆关键词搜索——员工运行时工具可对自己的工作空间文件按关键词搜索（CJK 2 字窗口 + 拉丁分词，按文件加权打分，返回行号 + 高亮片段）

技能：

  • 技能生命周期 curator——每天定时把闲置的、员工自建的技能按 active → stale → archived 老化（默认 30 天 stale、90 天归档）。设置 → 技能 curator 控制面板可预览 / 暂停 / 启停；内建、置顶、MCP/ACP、sys-/ops- 前缀的技能豁免。mateclaw.skill.curator.* 可配
  • 技能市场生命周期 UI——技能页加"启用 / 闲置 / 归档"分类 tab，卡片显示"上次使用"，详情抽屉可手动归档 / 恢复 / 置顶
  • skill-authoring 内建技能——教员工怎么写 SKILL.md（frontmatter / 校验限制 / 目录放置 / 常见坑），让员工自己写技能不用懂 JVM 内部
  • MCP / ACP 派生技能合成虚拟 SKILL.md（#136）——MCP/ACP 集成也能作为可导航的技能目录被 load_skill
  • 脚本入口的类型化封装工具——SKILL.md 里声明 scripts: 带 JSON Schema，每个脚本入口变成带类型参数的命名工具，模型填字段、运行时序列化传子进程

LLM 可靠性：

  • 限流自动故障转移——主提供商被 429 限流且同模型重试耗尽后，切下一个备份提供商（之前会直接把错返回）
  • 网络连接错误判为可重试——"network connection error" 归为可重试 SERVER_ERROR，最大重试 5 → 10，扛住 Wiki 批量加载时的提供商抖动
  • DashScope max_tokens 钳到 8192——超过会被 DashScope 返 400，之前被误判成"模型不存在"导致静默换提供商；现在钳住，确保你选的模型真的在跑
  • 软删模型不再卡唯一性校验（#173） + 清理 mate_model_config 墓碑行（V118）

部署 / 构建：

  • 服务端打成可执行 JAR——java -jar mateclaw-server-1.4.0.jar 开箱即用（加了 spring-boot repackage goal）
  • 编译带 -parameters——集中化 POM 迁移时丢了这个 flag，导致没显式命名的 @PathVariable / @RequestParam 运行时绑定失败（一批接口 500）；补回
  • OpenPDF 3 迁移——flying-saucer-pdf 升到 10.2 带 OpenPDF 3.0.3（com.lowagie.text → org.openpdf.text），同时升 JDA / ShedLock / Pebble / Tika / jsoup 等
  • Snowflake ID 精度检查进 CI——scripts/check-snowflake-precision.sh 扫 v-model.number、Number(id)、type="number" 等模式，挂进 pnpm lint / pnpm build，杜绝 19 位 ID 被 JS Number 截断

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

升级路径 ​

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

新增表 schema 由 Flyway 自动迁移。 目标（mate_agent_goal*，V120）、工具分层（mate_tool.disclosure_tier / mate_mcp_server.disclosure_tier）、渠道原生工具（mate_tool.channel_id，V119）等表第一次启动自动创建/加列，已有库自动 baseline。

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

  • 目标默认开但不影响旧行为——你不创建目标，对话和过去一样；图节点对无目标的调用 pass-through
  • 渐进式披露默认开——员工默认只看核心工具 + 扩展目录。如果你的自动化依赖"所有工具始终可见"，设 mateclaw.tools.disclosure.mode=legacy 回到旧行为
  • RBAC 默认单人无感——现有单 admin 部署升级后行为不变（全局 admin 拥有一切）；要拉团队，去工作空间加成员、分角色
  • 飞书 media_download_enabled 默认改为开——升级后飞书会下载入站文件/音视频。在意磁盘或隐私的话在渠道设置里关掉
  • 技能 curator 默认开——闲置技能会被老化。保守部署设 mateclaw.skill.curator.enabled=false，或在 UI 里暂停

这一版对你意味着什么 ​

如果你是普通用户——

给员工定一个目标试试。"帮我把这篇文章翻译成英文、发出去、回复评论"——说一次，看头像旁边那圈光替你跟到完成。

如果你管理一个团队——

把同事拉进工作空间，分角色：让运营当 Member 自己管 Agent，让实习生当 Viewer 只读。再用「数字员工构建器」一句话拉起一支专业团队，串成工作流交给系统。

如果你是开发者——

POST /api/v1/goals 程序化建目标、taskOutput 取异步委派结果、GET /workspaces/{id}/access 拿能力集做你自己的门禁。enable_tool / load_skill 让你给员工装一墙工具而不撑爆上下文。

如果你跑生产环境——

升级。限流自动转移 + 网络错误重试让长任务更稳；Snowflake 精度检查进 CI 杜绝一类幽灵 bug；可执行 JAR 让部署更省事。

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

回来试一次。员工现在会自己跟目标、会组建子团队、工具集随任务伸缩，整个系统能给团队用，飞书做成了一等公民。每一处都是因为有真实用户被卡住才做的。

One more thing. ​

目标。子团队。角色。

一个员工答完就停，是 chatbot。一个员工锁住目标自己跟到完成，是助理。一个员工带着自己组建的团队、在一个多人协作的工作空间里干活，是组织的操作系统。

这才是个人 AI 操作系统该长大的方向。