MateClaw

中文

English

中文

English

Appearance

v2.2.0 ​

稳定版 · 2026-08-29 · 上一个稳定版 v2.1.0

这个版本的主线 ​

2.1.0 把一次团队协作收拢成可治理的 Team Run；2.2.0 继续向下重构它赖以运行的底座：员工不再等同于某一套内置推理循环，长任务也不再等同于一条不能中断的请求。

本版围绕 Runtime 主线演进：

  • 员工运行时成为正式扩展点。 统一的 runtime contract、provider registry、session factory、能力声明和生命周期接口，让员工可以选择 native 或外部运行时，同时继续复用 MateClaw 的会话、权限、工作空间、消息持久化与 UI 投影。
  • DeepSeek Harness（DSH）进入主线。 DSH 以受管理的外部 Agent runtime 接入，通过认证 JSON-RPC 子进程桥接思考、文本、工具调用和生命周期事件；控制台提供安装、配置、校验、连接测试和启停入口。
  • 长任务变成可恢复的持久执行。 目标被拆成有界 segment，由数据库队列和 supervisor 调度；队列、冷却、重试、执行 attempt、输入排队与租约在后端重启后仍可恢复。
  • Agent 之间可以跨系统互联。 新增 A2A 入站 JSON-RPC / SSE 接口、Agent Card 和 call_a2a_agent 出站工具，MateClaw 员工可以被外部 Agent 调用，也能在边界约束下调用对端。
  • 运行时边界继续收紧。 DSH 工具仍由宿主 Tool Guard 和工作空间策略裁决；实时管理视图、共享会话、生成文件、文件写入和 Wiki 故障记录都补齐工作空间归属校验。
  • 长协作与交付链加固。 Team checkpoint、任务板恢复、交付物完成门、worker 附件传递、重试和最终汇总进一步收口；长文本、审批、停止和恢复期间的输入不会再轻易丢失。

另外还有：可选 OfficeCLI 高级文档引擎、ACP prompt 超时配置、插件工具在员工选择器中可见、微信渠道执行轨迹开关、自定义模型 provider 恢复，以及 Live 状态加载提速。

1. Runtime Contract：员工与推理引擎解耦 ​

2.2.0 引入 AgentRuntimeProvider 扩展层。运行时负责启动一轮员工执行并输出统一事件；MateClaw 仍负责：

  • 员工身份、模型绑定、会话和消息持久化；
  • 工作空间解析、工具清单、Tool Guard 与审批；
  • 流式事件到 Chat / Agents Live 的统一投影；
  • 停止、取消、完成和异常等生命周期语义。

provider 通过 registry 按类型选择，session 在启动前验证工作空间、配置与能力，未知或不可用的 runtime 会在启动前失败，而不是运行到一半才静默降级。员工编辑器会显示 runtime 选择，消息和用量记录也保留实际 runtime provider，便于排查同一模型在不同执行引擎中的差异。

当前内置两条路径：

Runtime适合场景治理归属
NativeMateClaw 内置 ReAct / Plan-Execute、Goal 与 Team Run全部在 MateClaw 进程内
DSH使用 DeepSeek Harness Agent loop 和 Cordis compositionDSH 执行循环；MateClaw 管会话、权限、工具与投影

2. DeepSeek Harness：外部循环，宿主治理 ​

DSH 不是 MCP 工具，也不是一个模型 provider。它是员工级运行时：MateClaw 通过 stdin/stdout 上的认证 JSON-RPC 启动并管理 dsh-jsonrpc-agent，再把 runtime 事件适配为现有聊天流。

本版完成：

  • DSH process/session 管理、单会话隔离、取消和完整 stream 生命周期；
  • 认证 bridge protocol，以及 text / thinking / tool / lifecycle 事件映射；
  • 宿主工具描述投影，工具调用回到 MateClaw 执行并经过工作空间策略与 Tool Guard；
  • DeepSeek provider 凭证注入，密钥不进入员工 runtimeConfig；
  • 管理页安装、配置、校验、连接测试、启用/停用与脱敏诊断；
  • 子进程环境隔离，只传递运行时所需的受控环境变量。

完整接入步骤见 DeepSeek Harness 接入。

3. Persistent Goal：从“本轮继续”到“重启后继续” ​

新目标默认开启 persistentExecution。一次长任务被拆成有界执行片段；片段结束不再意味着目标结束，supervisor 会根据持久化状态安排下一段。

运行时新增：

  • 数据库-backed continuation queue、冷却时间、重试与过期 lease 回收；
  • goal attempt 记录、单目标运行协调与启动恢复；
  • 会话级持久输入队列：运行中到达的新输入先排队，审批完成或当前片段结束后再按序消费；
  • 对 provider 临时故障的退避和实例级节流，避免恢复时形成请求风暴；
  • Stop、缺少必要输入、审批拒绝、预算耗尽等显式暂停，只有明确 resume 才继续；
  • 完成前重新读取持久化 checklist，所有准则都通过且证据非空才可结束。

GET /api/v1/goals/{id}/execution 可读取最近调度状态、原因和到期时间；SSE 使用 goal_continuation 广播变化。当前实现面向单后端实例的 native runtime，外部工具副作用不承诺 exactly-once；恢复逻辑会先检查已有产物与异步句柄。

详见 持久化目标。

4. A2A：让 MateClaw 成为 Agent 网络中的节点 ​

2.2.0 同时提供 A2A 入站与出站能力：

  • 入站支持 message/send、message/stream、tasks/get、tasks/cancel；
  • SSE 推送任务状态和 artifact，并带 heartbeat；
  • Agent Card 匿名只暴露最小信息，启用员工的技能明细仍要求 Bearer 认证；
  • 请求 idempotency snapshot、重复 task 拒绝、终态 TTL 清理和容量上限防止任务表无界增长；
  • call_a2a_agent 负责发现对端 Agent Card、发送任务、轮询或解析 SSE；
  • 默认拒绝重定向与私网出站，并限制超时和响应体大小，降低 SSRF 与资源耗尽风险。

A2A 默认关闭。部署参数与端点见 A2A 协议。

5. Team Run 与交付可靠性 ​

Runtime 底座变化也反向加固了团队执行：

  • checkpoint loop 和任务板恢复变为幂等，避免长协作重复提交证据；
  • 只有所有必需交付物都登记完成，任务和整轮运行才能越过完成门；
  • Lead 附件会传给 worker，worker 回复中的生成文件会自动登记为交付物；
  • 澄清式 worker 回复不会被误判为最终成果，失败任务重试会保留必要上下文；
  • 管理员可读取已完成 worker run，但普通会话和工作空间边界保持隔离；
  • 工具 returnDirect、长篇最终回答和 Team Run 投影的收尾逻辑更可靠。

详见 Team Run 与团队协作。

6. 工具、文档和运行时细节 ​

  • OfficeCLI（可选）：新增 .docx / .xlsx / .pptx 的 inspect、validate、batch edit、merge 与 preview 适配。输入先复制到隔离临时目录，输出受 20 MB 交付上限约束；未安装时不会影响内置文档工具。
  • ACP prompt timeout：自定义端点可配置 prompt 等待时间，适配需要更长初始化或人工确认的 coding runtime。
  • 工具发现与执行：插件工具会出现在员工工具选择器；重复加载 plan skill 被抑制；工具输入校验、returnDirect 和失败降级更一致。
  • 渠道与 UI：微信渠道可控制执行轨迹展示；恢复会话时重建聊天状态，运行/停止状态文案更明确；Live 查询按工作空间过滤并减少不必要的加载。

升级须知 ​

2.1.0 数据保持兼容。 Flyway 会按数据库方言应用 V185–V189：OfficeCLI 注册、员工 runtime provider、ACP prompt timeout、goal continuation，以及 goal attempt / conversation input queue。

升级前请注意：

  • 新目标默认持久执行。 省略 turnBudget / llmCallBudget 时，0 表示不设置累计上限；建议生产环境显式设置预算、并发数与 provider failure backoff。旧目标保留原模式，不会在升级后自动启动。
  • DSH 是可选运行时。 未安装 DSH 不影响 native 员工。启用前应使用专用工作目录、最小工具集并通过管理页 verify / test connection。
  • A2A 默认关闭。 对外开放前设置稳定的 public base URL、Bearer 认证和出站网络策略；除非明确需要，不要打开私网出站。
  • 恢复不是 exactly-once。 服务重启后会恢复未完成执行，但外部 API、Shell 和第三方工具的副作用仍需要幂等键、产物检查或人工确认。
  • OfficeCLI 可选。 数据迁移只注册能力；服务器 PATH 中没有 officecli 时会返回明确的不可用信息，不会替换现有 JVM 文档工具。

这个版本对你意味着什么 ​

如果你在经营不同类型的数字员工，2.2.0 让“员工”和“推理引擎”第一次真正分开：你可以选择 native 或 DSH，同时保留同一套治理、工具、消息和观察面。

如果你在跑长任务，目标不会因为一个请求结束、用户临时插话或服务重启就失去主线；它会带着 checklist、attempt、输入队列和恢复状态继续。

如果你需要跨系统协作，A2A 让 MateClaw 既能对外提供员工能力，也能把外部 Agent 纳入一轮受控执行。

2.1 让协作成为一份运行；2.2 让运行本身可替换、可恢复、可互联。