MateClaw

中文

English

中文

English

Appearance

v1.1.0 ​

发布日期：2026-04-17

让 MateClaw 真的像一个"个人 AI 操作系统" ​

1.0 换了皮肤。1.1 把"跑起来真的像那么回事"这件事做完：聊天回复在每一个渠道里实时流式呈现，长任务切换会话后继续在后台跑完，Wiki 变成真正的语义检索引擎，而且 agent 第一次可以给自己写技能。

这是 1.x 系列最大一次发布：98 个 commit、25 个特性、44 个修复、20 篇文档更新。本页只列最值得讲的；从 1.0.x 升级请看 UPGRADING.md。

重点特性 ​

Agent 自己写技能 — 自动技能合成（RFC-023） ​

当 agent 发现一个好用的套路 —— 一种反复出现的数据库查询方式、一种特定的报表版式、SSH 到你机器的具体命令序列 —— 它会主动提议把这段经验变成一个 skill，走你的审批流程，保存下来下次复用。不用你再一遍遍 "记住我喜欢按这个格式排表格"。Agent 的记忆和你一起长大。

  • skill_manage 工具支持 create / edit / patch / delete
  • 保存前自动安全扫描（阻断危险模式）
  • ChatConsole 里干净的审批确认流
  • 可跨 agent 迁移，可打包 ZIP 分享

多 agent 并行协作（RFC-004） ​

一个 agent 可以把任务委派给另一个 —— 或者同时委派给三个。让代码 agent 处理 Jira 工单，同时让研究 agent 拉竞品数据，同时让写作 agent 起草 Slack 回复。每个在独立会话里跑，结果流式回传给编排者。

  • delegateToAgent 和 delegateParallel 工具
  • 子会话追踪 + 事件 relay，你能实时看到子任务进度
  • 系统 prompt 里内置路由提示

Wiki 变语义 — 两阶段摘要 + 深度调研（RFC-011, RFC-012, RFC-013） ​

你喂给 Wiki 的那些 PDF，以后不再只是个搜索框。它现在是真正的检索引擎：

  • 页面级 + chunk 级语义搜索 —— 问"我们关于 auth 决定了什么？" 直接返回决策，不是一堆包含 "auth" 的页面
  • pgvector 风格的 chunk 嵌入，超出模型上下文的文档自动做 mean-pool 子段切分
  • 两阶段摘要：阶段 A 抽取路由 + 元信息，阶段 B 按页合并 —— 大文档处理速度数量级提升（60+ 页并发）
  • 每条原始素材独立进度条 —— 不再盯着"处理中..."，看到 页数完成 / 总页数
  • 可恢复：中途断，点"重新处理"，只重跑未完成的页
  • 新增 wiki_search_pages（混合检索）、wiki_semantic_search（chunk 级）、wiki_read_page、wiki_trace_source 工具

深度思考（RFC-001） ​

每个 agent、每次对话可以打开 Anthropic extended thinking / DashScope qwq 推理 / OpenAI o1 reasoning_effort=high。thinkingLevel: off / low / medium / high / max。思考块流式进入 UI，做成可折叠面板 —— 你看得见模型在怎么想，也不会把 token 烧在不需要推理的闲聊上。

Anthropic prompt 缓存（RFC-014） ​

系统 prompt、agent 人格、工具定义 —— 自动带上 cache_control: ephemeral，Anthropic 兼容端点上第一次请求热身，之后每次缓存命中。Dashboard 新增 cache_read_tokens / cache_write_tokens 日维度统计。

声明式 Hook 系统（RFC-017） ​

5 个生命周期钩子：before_tool / after_tool / before_llm / after_llm / on_error。Hook 在进程内执行，可以改参数 / 改结果 / 脱敏 / 加审计日志。工具守卫规则现在就是一种 Hook。

插件 SDK（RFC-003） ​

第三方插件不用 fork 就能扩展 MateClaw。ChannelAdapter / Tool / MemoryProvider / Hook 都有 SPI。放个 JAR 到 plugins/ 目录就能发现加载。

所有渠道支持语音（RFC-009） ​

IM 渠道（WeCom / 微信 / 钉钉）现在都支持语音输入。DashScope / OpenAI Whisper 做 ASR，微信加密 CDN 的语音有三路回退。语音回复走 TTS 合成后以音频消息发回。

ChatConsole 重新设计，真正多渠道 ​

"实时看着外部 IM 会话发生"这件事是新的。这也是 MateClaw 从"一个 web 应用"变成"运营控制台"的那条分界线。

  • 外部渠道实时同步 —— WeChat 用户在跟你的 agent 聊，你能在 ChatConsole 侧栏同步看到推理、工具调用、流式回复。不用 F5
  • 运行指示器 —— 正在跑 agent 的会话图标上有琥珀色脉冲
  • 切换不踩死 —— 切到别的会话时，上一个在后台继续跑；切回来，重连到活跃 buffer
  • 不再重复气泡 —— reconcile 层通过 ID 提升把前端流式 placeholder（client-uuid）和后端落库的 assistant 消息匹配为同一条
  • 错误卡可操作 —— Ollama "does not support tools" 现在显示具体的中文指引（"请切换到 qwen3 / qwen2.5:7b+ / llama3.1:8b+"），不再是"未知错误"

微信 / 企业微信稳定性（RFC-024） ​

个人微信长连接机器人是 1.0 最脆弱的渠道。1.1 重建了它：

  • pollLoop 看门狗 —— 再也不会有静默停止重连的 poller
  • 抖动指数退避，处理 token 过期 / 网络抖动
  • 按 adapter 维度 touchActivity 做陈旧检测
  • Token 跨重启持久化
  • 语音 ASR 三路回退覆盖微信 CDN 的多种加密方式
  • 企业微信支持 markdown 表格 + 拒答检测

底层改进 ​

嵌入模型 UI 可配 ​

不用再配 EMBEDDING_API_KEY 环境变量了。嵌入模型现在就是 mate_model_config 里 model_type='embedding' 的普通行。设置 → 模型 里和 chat 模型列在一起。知识库从下拉里选它的嵌入模型。

LLM provider 硬化 ​

  • DashScope "url error" 正确分类为客户端错误（不再对死模型无效重试）
  • DashScope 模型发现做协议感知探测（跳过非 chat 模态，降噪）
  • 不可用 / 带点号版本的 DashScope 模型启动时自动清理
  • Ollama 自动发现会把种子里的 :latest 重写为实际安装的 tag（deepseek-r1:latest → deepseek-r1:7b）—— 不再因 model not found 404
  • Ollama 无工具模型黑名单 —— deepseek-r1、gemma*、phi3/4 等不会被意外 auto-activate 为默认

MySQL 迁移脚本修复 — Gitee #IIYHLJ ​

所有使用 ALTER TABLE ... ADD COLUMN IF NOT EXISTS（MariaDB 语法，MySQL 不支持）的 mysql/V*.sql 都重写成 INFORMATION_SCHEMA + 预处理语句。全新 MySQL 8.x 部署现在能跑通；已有用户通过 FlywayRepairConfig 自愈。

首次连接自动建库 ​

application-mysql.yml 加了 createDatabaseIfNotExist=true。不用再手动 CREATE DATABASE mateclaw。

防御性硬化（RFC-025） ​

外部 CHANGELOG 扫描出来的 5 个快速改进：

  • 日志里工具参数脱敏
  • Stream fallback 定时器 + 幂等清理
  • 审批占位在超时后清理
  • Agent 实例缓存在配置变更时失效
  • 渠道 adapter 陈旧连接驱逐

Docker compose 不再接受默认密码启动 ​

docker-compose.yml 所有 secret 从 .env 读。未设置 DB_PASSWORD / DB_ROOT_PASSWORD / DASHSCOPE_API_KEY → docker compose up 直接退出并提示。原来硬编码的 mateclaw123 没了。模板看 .env.example。

值得单独提的修复 ​

  • 工具守卫 现在也扫描迁移里定义的存储过程
  • Flyway 版本冲突 V8/V9 和 V9/V10 并行 PR merge 造成过冲突，重新排号
  • Skill 重装 SKILL.md 正确覆写、ClawHub fetchBundle 失败重试
  • MCP 自动检测 Node.js PATH 在 macOS/Linux 的 GUI 启动环境下能发现
  • Filesystem MCP 默认关闭，~ 占位显式化
  • Wiki slug 规范化 —— 多个 chunk 里的同一个概念不再重复调 LLM
  • Wiki 失败路由 —— DNS/TLS/连接拒绝 快速失败并把根因展示到 UI
  • ChatConsole —— 自动滚动不再抢鼠标；侧栏显示渠道专属图标
  • TalkMode WebSocket —— 聊天页加载不再报错
  • MessageBubble —— 后端的错误翻译（如"当前模型不支持工具调用"）现在能穿透到失败消息卡

完整列表见 git log v1.0.418..v1.1.0。

从 1.0.x 升级 ​

看 UPGRADING.md。大部分用户：无需手工操作。FlywayRepairConfig 自愈 mysql 迁移 checksum，OllamaAutoDiscoveryRunner 重写坏 :latest 默认，mate_model_config 陈旧行下次启动收敛。

生产部署者必须在 .env 里设置新的必填项：

  • DB_PASSWORD（强密码，不能是 mateclaw123）
  • DB_ROOT_PASSWORD
  • JWT_SECRET（推荐）
  • MATECLAW_CORS_ALLOWED_ORIGINS（推荐）

致谢 ​

所有在 Gitee 上报 bug 的人（#IIYHLJ 及之前），在不稳定家庭网络和各种边角环境下跑 MateClaw 的社区，有耐心重启 Ollama 四次的同学 —— 这个版本是你们塑造的。

下一个版本 v1.2 的路线聚焦于 RFC-026（channel tunnel / 统一队列）和更深的 agent 自主性。关注 RFC 目录。