v1.7.0
稳定版 · 2026-07-04 · 上一个稳定版 v1.6.0
这个版本的几件大事
v1.6.0 让员工能跑在你的数据库上、长出感官和双手、被你直接塑造。这个版本关心的是把它放进真正的生产协作里之后,那些看不见、收不拢、够不着、装不下、连不通的地方。
一句话:v1.7.0 是一次生产化加固——让长任务的进度和花销看得见、让审批收得拢、让桌面端和局域网服务够得着、让注入随真实模型窗口装得下、让知识库与深度研究能力连得通外部系统。
几件大事:
- 审批体系三条链路彻底打通——工作流审批、WebChat/API-Key 渠道、飞书/企微卡片全部端到端闭环,不再静默挂死。
- 长任务看得见了——常驻「运行总览」侧栏 + 本轮 Token 明细(缓存命中/未命中/写入 + 推理拆分)+ 子 Agent 成本向上滚加 + 生成文件一键下载。
- 装得下真实模型窗口——本地模型上下文窗口探测、prefix 注入统一 Token 预算、小上下文自动降级、工具 schema 超预算按频度降级,不再被"猜个 32K"坑到预检拒绝或悄悄截断。
- 开放出去——知识库与 Deep Research 开放 API(API-Key 鉴权 + 限流 + SSE 流式)、插件化搜索 Provider SPI、MCP 身份透传(把认证用户身份带给 STDIO MCP)。
- 够得着更远——桌面端本地内嵌 / 远程集中部署双模式(v1.7.0 起
mateclaw-desktop源码开放),外加局域网部署模式放开受控的内网服务访问。 - 运营数据一键导出——Dashboard 9 表 Excel + CLI 命令行离线导出。
外加:Wiki 处理失败可视化、按员工模型链偏好、OpenAPI/Swagger 可直接调试、聊天回到底部浮动按钮,以及一批并发记忆隔离、上传路径、模型探测的修复。
就这些。
1. 审批体系打通三条链路
MateClaw 有三条审批链路,此前只有第一条端到端闭环,另外两条存在功能性缺口(其中一处是已知静默失败):
| 链路 | 通知 | resolve 入口 | 执行恢复 |
|---|---|---|---|
| 对话工具审批(Web/IM) | ✅ | ✅ | ✅ |
工作流 await_approval 步骤 | ❌→✅ | ⚠️→✅ | ✅ |
| WebAPI(API-Key / WebChat)渠道 | ❌→✅ | ❌→✅ | ❌→✅ |
工作流审批不再静默失败。 await_approval 步骤声明的 approverChannels(如 feishu:oc_xxx)以前只被序列化进审批行作展示,全仓没有任何代码读回它发通知。现在步骤执行时会逐渠道真的推送审批通知;同时补齐了 resolve→resume 的桥接(激活原本是死代码的恢复路径),审批通过后工作流从暂停步骤继续执行。
WebChat(API-Key)渠道补齐审批交互。 之前 WebChat 绑定的 Agent 命中受 ToolGuard 保护的工具会挂起,但访客无法 resolve,审批挂到 30 分钟 GC 超时,整轮对话白费。现在新增 /sessions/approve、/sessions/deny 端点:复用 visitorToken + 会话归属鉴权(pendingId 严格限定到所属会话,杜绝跨访客越权),批准走工具重放、拒绝返回同步结果,并广播 tool_approval_resolved 让 SDK 实时清理审批横幅。
飞书 / 企业微信卡片点击直接 resolve 工作流审批。 工作流审批被推到飞书/企微群后,点「批准/拒绝」按钮现在真的生效——修复了工作流审批(系统发起、无 userId)的身份校验 fail-closed,以及合成消息 conversationId 与 workflow:run:{runId} 对不上导致查不到 pending 的死路。
2. 长任务看得见 —— 运行总览 + Token 明细 + 子 Agent 成本
长任务(多步骤计划、多智能体协同)以前只能在消息流里上下翻找进度,更看不到它花了多少。这个版本把「进度」和「花销」都摆到台面上。
常驻「运行总览」侧栏。 聊天页右侧新增一个常驻侧栏,把后端本就在流式推送的数据装配到一处:
- 计划进度 —— plan 模式下实时显示各步骤状态(待执行 / 执行中 / 已完成)、进度计数,步骤结果可展开。计划生成前显示「规划中…」占位,不再闪烁。
- 子 Agent 实时状态 —— 委派产生的子 Agent 以树状实时展示(名称、调用的工具、运行 / 完成 / 出错 / 停滞状态),多级委派可逐层展开。
- 生成文件一键下载 ——
execute_code/execute_shell_command写出的文件、以及员工生成的产物,直接在运行总览里以可点击附件呈现(下载名用真实文件名,不再是原始 id URL)。 - 折叠 / 抽屉 —— 可折叠为带角标的竖条;窄屏(< 1280px)自动降级为浮层抽屉,不挤占对话区。
本轮 Token 明细。 每一轮对话新增用量拆解:输入 / 输出 / 推理 token,以及缓存命中 / 未命中 / 写入的分项——一眼看清 Anthropic prompt 缓存到底省了多少、推理占了多少。
子 Agent 成本向上滚加。 委派产生的子 Agent 各自的 token 用量会逐层向上汇总到本轮总量页脚;单任务委派与计划步骤委派都做了结构化透出,一支临时团队跑完花了多少一目了然。
纯前端装配、复用现有 SSE 事件流。详见 对话。
3. 装得下真实模型窗口 —— 上下文与 Token 预算
以前注入(记忆、Wiki、身份 prompt、工具 schema)是按固定假设堆进去的,遇到小窗口的本地模型或严格的本地推理服务,轻则被悄悄截断、重则触发 max_tokens 预检直接拒绝。这个版本让每一块注入都随真实模型窗口伸缩。
- 本地模型上下文窗口探测 —— Ollama / vLLM 的真实上下文窗口接入会话预算;超限报错时自动反解窗口值回填,不再靠"猜个 32K"。
- prefix 注入统一 Token 预算 —— 记忆 / Wiki 等首请求注入块按模型有效窗口统一缩放;身份 prompt 超大时告警,而不是默默挤爆窗口。
- 小上下文自动降级档 —— 紧凑 / 底线两档收紧注入,压缩触发比自适应到 0.85,prefix 分块统计 + 预超限快速失败,窗口小也能稳定跑。
- 工具 schema 预算阈值门 —— 工具太多、schema 超出窗口预算时,按使用频度自动把冷门工具降级到扩展目录;需要时
enable_tool随时找回。 - 推理输出上限尊重模型配置 —— 推理节点按模型配置的
maxTokens和真实窗口双重钳制输出上限,修复严格本地服务端的max_tokens预检拒绝。 - 压缩清理占位符信息化 —— 上下文被压缩清理后留下的占位符保留工具名 / 原始大小 / 首行要点,便于模型判断要不要重跑,而不是一团"[已省略]"。
4. 开放出去 —— 知识库 / Deep Research 开放 API + 插件化搜索 + MCP 身份透传
这个版本第一次把 MateClaw 的能力作为受控开放 API 暴露给外部系统,并让工具生态更可插拔。
知识库与 Deep Research 开放 API。 新增一套面向外部集成的开放 API:知识库检索 / 页面 / 实体等 9 个端点,以及 Deep Research 的 start / SSE / status / cancel 全流程。鉴权走独立的 API-Key(非登录态)、带限流和集中式授权;会话严格绑定到路径里的 kbId,并修复了跨 KB 的越权(IDOR)。外部应用现在可以直接调 MateClaw 的知识库和深度研究,而不必登进管理端。
插件化搜索 Provider。 搜索能力从内置若干实现升级为可插拔 SPI:新增 PluginType.SEARCH 与 PluginSearchProvider 接口,第三方搜索源可以像插件一样装进来;配套新增 search-provider 目录端点、分组化的设置界面和插件配置表单,在设置页就能挑选和配置搜索源。
MCP 身份透传。 STDIO 类型的 MCP server 现在可以按 server 显式开启、把当前认证用户的身份透传下去(on-behalf-of),身份按渠道与信任级别归类;对未知渠道 fail-closed、签名密钥自愈,避免身份被冒用。让本地 MCP 工具也能"知道现在是谁在用"。
5. 够得着更远 —— 桌面端连远程 + 局域网部署模式
桌面端连远程 Server + 源码开源。 适用于「企业多人协作连一台集中部署的 Server」的场景:
- 本地 / 远程双模式 —— 既可用内嵌 JVM 跑本地服务,也可直接连集中部署的远程 Server。
- 首启连接选择器 —— 第一次启动让你选模式并填服务器地址(自动补
https://、规范化校验)。 - 多服务器与切换 —— 记住最近使用的服务器(最多 8 条),菜单「切换服务器」随时换环境。
- 内网自签名证书 —— 对用户显式信任的 host 放行自签名证书(仅限当前连接地址,非通配绕过),适配企业内网。
- 整个
mateclaw-desktop源码开放到开源仓库:Electron 主进程 / 预加载 + Vue 渲染端、打包配置、构建资产、README/CODESIGNING指南;构建产物、内置 JRE、签名二进制按.gitignore不入库。
局域网部署模式。 出站访问守卫默认封锁内网 / 元数据地址以防 SSRF;新增局域网部署模式开关,在你显式启用后放开受控的内网服务访问,适配"MateClaw 与内网服务同处一张局域网"的部署。开关关闭时的默认姿态更硬:每次请求都重新校验 SSRF、重定向目标同样拦截、云元数据地址不可绕过、自签名 TLS 放行仅限局域网模式;守卫允许列表可配置。
6. 运营数据一键导出 —— UI + 命令行
运营数据导出:一份多表运营报告(.xlsx 打包为 .zip),覆盖 9 张数据表——总览 KPI、Token 用量、技能统计、用户统计、用户对话、安全与审计、渠道统计、模型配置、定时任务。
- Dashboard 一键导出 —— 仅全局管理员可见。选时间范围(快捷近 7/30/90 天,最长 90 天)→ 生成(圆形进度环)→ 下载。生成 / 进度 / 下载端点由全局管理员鉴权,单次下载令牌原子单次有效,文件 24 小时或下载后自动清理。
- 命令行导出 —— 新增项目级 CLI 框架与
--cli.command=export命令,可从本地或docker exec直接生成报告并把 ZIP 写入 stdout(> report.zip),无 90 天上限、无超时,适合大范围离线导出。CLI 仅运维侧可达,不经 HTTP。 - Excel 中 19 位雪花 ID 以文本写出,避免被 Excel 数值精度截断。
详见 后台管理。
7. 还有几处变透明、变可控
- Wiki 处理失败可视化 —— 知识库入库失败不再是一片沉默:错误码链路可追、静默子步骤会告警、跨 KB 有统一的失败中心;
wiki_create_page由 agent 写入的页面补齐 raw/chunks/embeddings/citations,界面能正常识别与操作。廉价的入库步骤可路由到可配置的轻量模型省成本,知识图谱新增按名字定位节点的搜索框,内置转换启动包在每个工作空间可见。 - 按员工模型链偏好 —— 每位员工可配置自己的模型链(提供商 + 模型,允许同一提供商重复),覆盖全局默认。
- OpenAPI / Swagger 可直接调试 —— 全局 OpenAPI 配置(标题 / 描述 / 服务器 +
bearerAuth,同时覆盖 JWT 与mc_个人访问令牌,按前缀分发),Swagger UI 的 Authorize 可用,受保护端点可直接 Try it out;配置项全部可经环境变量外置。详见 OpenAPI / Swagger 指南。 - 聊天「回到底部」浮动按钮 —— 上拉阅读历史时出现,15 秒无操作自动吸附到边缘,
End键一键回到底部;用户上拉时不再被自动滚动打断。
还有一些
- 并发会话记忆隔离 —— 修复同一 Agent 多并发会话时记忆串台的问题,
session_search严格按所属会话隔离;mate_memory_recall.filename收敛到VARCHAR(256)。 - 上传与生成文件路径 —— 聊天上传路径以根相对方式存储(不再是绝对服务器路径);生成文件下载链接正则收敛到 http(s) / 相对 URL;重挂载时丢弃 URL 里的过期 workspace agentId。
- 模型与技能细节 —— 设 API Key 前保留模型发现按钮可见;不再默认认为 DeepSeek 具备视觉能力;技能 ZIP 体积上限可配置。
- 出站守卫 —— 出站 HTTP 守卫新增可配置的 SSRF 允许列表。
升级路径
配置完全兼容。 你的 Agent / 技能 / Wiki / 渠道 / 定时任务 / 工作流 / 触发器 / 目标全部原样保留。
如果你已经在生产跑 v1.6.0:
- 工作流审批通知是按
await_approval步骤的approverChannels自动生效的——给步骤声明"feishu:oc_xxx"这类目标即可收到通知;只声明"web"则不主动推送(走管理端 resolve)。 - 上下文与 Token 预算默认生效且向下兼容:云端大窗口模型体感不变;本地小窗口模型现在会探测真实窗口并按预算注入——若你之前手填过窗口值,可复核一下模型配置。
- 开放 API 与 Deep Research API 默认需要独立签发的 API-Key,并受限流约束,不影响既有登录态调用;不签发 Key 即不对外开放。
- 局域网部署模式默认关闭——保持封锁内网 / 元数据地址的硬姿态;只有你显式打开开关后才放开受控的内网访问。
- MCP 身份透传是 per-server opt-in,默认不透传;需要让某个 STDIO MCP 知道调用者身份时再逐个开启。
- 桌面端远程连接是新选项,默认仍是本地内嵌模式;首启选择器引导你选择。
- OpenAPI 元信息走
mateclaw.openapi.*配置项,留空用内置默认。生产环境若要收口 Swagger 公开访问,在SecurityConfig显式加规则。
这个版本对你意味着什么
如果你跑工作流 —— await_approval 步骤的审批通知真的会到飞书/企微群,点卡片就能批,审批通过工作流自动继续,不再静默挂死。
如果你跑长任务 —— 右侧运行总览看进度和子 Agent,本轮 Token 明细和子 Agent 成本一并看清,生成文件一键下载。
如果你用本地 / 小窗口模型 —— 注入随真实窗口伸缩,不再被预检拒绝或悄悄截断;严格本地推理服务也能稳定跑。
如果你做外部集成 —— 知识库和 Deep Research 有了受控开放 API(API-Key + 限流 + SSE),搜索源可插拔,STDIO MCP 能拿到调用者身份。
如果你做运营 / 审计 —— Dashboard 或命令行一键导出 9 表运营报告,Wiki 入库失败有迹可循。
如果你是企业多人协作 —— 桌面端连你集中部署的一台 Server,局域网内可放开受控的内网服务访问;mateclaw-desktop 源码也开放了,可自行构建分发。
还有最后一件事。
看得见,收得拢,够得着,装得下,连得通。
一个审批会静默挂死的系统,你不敢把它放进真正的业务流程。一个长任务跑到哪、花了多少你都看不见的员工,你只能干等。一个注入撑爆窗口、被本地模型预检拒绝的助手,你在本地根本跑不起来。一个只能各跑各本地、能力关在管理端里的产品,撑不起协作,也接不进你的系统。
这个版本把这些都补上:审批端到端闭环、长任务运行与花销可见、注入装得进真实窗口、能力作为受控 API 开放出去、桌面端连上你集中部署的服务并开放源码。
从"能用"到"敢放进生产"。