# 3.0.0：执行架构升级

发布日期：**2026-10-26**。本文为 3.0.0 正式版更新说明。源码与发行包版本统一为 `3.0.0`；发行包请从 [GitHub Releases](https://github.com/mateaix/mateclaw/releases) 下载。

## 自 2.3.0 以来的累计更新

3.0.0 同时收录原 2.4.0 开发周期的更新；2.4.0 未单独作为正式发行版发布。以下按能力归类，避免把架构迁移前的功能遗漏。

### 工作空间与会话

- 成员文件隔离为可选严格沙箱模式，开启 `MATECLAW_WORKSPACE_SANDBOX_MEMBER_ISOLATION_ENABLED=true` 后按已认证用户和工作空间划定文件根目录；身份缺失即拒绝访问，不回退到共享目录。当前仅开放六个经审查的内置文件/代码工具；DSH、MCP/plugin 工具、共享技能脚本和未认证渠道身份不可用。它与个人记忆文件的共享回退是不同机制。 (#644).
- 持久渠道会话过期查询上下文清理，避免旧请求影响新任务。上传图片从会话存储解析，目录附件保留目录信息并校验上传边界。
- 员工创建时兼容推理块后的 JSON；显式关闭工具的员工不再因通用能力被重新赋予工具（#648、#655）。

### 结构化决策与目标、计划、团队

- 新增有界、类型化的 Choice / Boolean / Score 决策管线及持久审计，支持 OFF / SHADOW / ACTIVE 和场景覆盖。默认 SHADOW，建议不能绕过领域硬约束。
- Goal 续跑决策、计划员工路由、团队 worker 结果判断共用结构化决策基础；结果与状态在领域事务中提交，延迟结果经身份与 fence 校验。
- 增强路由上下文、worker 输出契约、委派步骤结果校验和有界 Goal 恢复；记录已应用的后续执行抑制，保留原完成验收门。

### 模型与 DeepSeek Harness

- DSH 迁移至 SDK 运行时，新增锁定版本与受控升级；失败健康检查会失效，损坏配置仍可编辑修复（#650）。
- 模型探测检查已完成响应的有效性，不把只有连接或空响应误判为成功（#658）。

### 朗读、聊天与工具展示

- 恢复 Edge 和 DashScope 朗读，支持供应商音色列表、选择与试听（#646）。
- MCP 结构化结果支持专用工具展示，并放在最终回答下方；普通工具结果不再自动混进最终回答正文（#651、#656、#661）。

### 渠道与数据运维

- 飞书 WebSocket readiness 与资源生命周期由应用管理，关闭和重连释放所属资源（#659）。
- 不支持的 webhook 渠道在写入配置前拒绝，避免保存无法运行的配置（#654）。
- Flyway 校验失败默认拒绝启动，历史修复必须显式选择，保留备份与恢复指导（#657）。
- 增加商业版概览与入口；这不意味着开源版包含商业模块。

## 最终答复、团队交付与部署

- 长任务返回最终答复前检查完成情况，未完成工作可在运行时限制内继续；需要用户补充信息时等待回复，不反复启动行动回合（#668）。
- 推理耗尽单次响应的输出预算后，可在运行时限制内重试生成最终答复；DeepSeek Flash 的思考开关一致生效（#672）。
- 团队成员进度保留完整结果证据及运行失败原因；Team Run 在最终汇总完成后再发布完成状态，使成员结果、进度与最终交付一致。
- DSH 保留经审查的默认 SDK 版本，`0.2.1-rc.2` 为可选候选版本；Docker 运行镜像锁定 Node.js 22，并包含 Linux 沙箱执行所需的 bubblewrap（#670）。macOS arm64 的候选验证不代表 Linux 或 Windows 已完成验收，参见 [DSH 配置与限制](./deepseek-harness)。
- 所有后端均要求非空且至少 32 个 UTF-8 字节的 `JWT_SECRET`。桌面本地模式生成并持久化密钥；源码与服务器部署须自行配置并保留密钥。参见[配置说明](./config)。

## 平台与执行核心

Java 21，Spring Boot 4.1.1，Spring AI 2.0.1，AgentScope Java 2.0.4。移除 Spring AI Alibaba starter 和 Graph 依赖。AgentScope 驱动普通 ReAct 和 Plan-Execute 单步内部的推理、工具、观察循环；整体计划调度、Goal 预算与验收、团队协作仍由 MateClaw 管理。

工具批次经 ApplicationGuardedToolkit 转交应用执行器，继续执行审批、工作空间权限、审计与取消策略。模型请求走现有 Spring AI/provider 适配；应用继续负责 SSE、历史记录及持久化。

## 模型、工具与恢复

- 原生 DashScope 聊天与 Embedding 适配替代 Alibaba AI 集成，保留原生语音 SDK。
- OpenAI/Anthropic 适配保留推理、媒体、缓存和用量；取消先终止所属 HTTP 调用，取消后不继续备用模型。
- MCP SDK 0.18.3：保留调用 ID、结构化结果和协议错误，应用内部执行能力不写入网络元数据。
- Goal 工具检查点在副作用前持久化执行身份；结果不确定时阻止盲目重放，保留审批恢复和会话隔离。
- MyBatis Plus 3.5.17 使用 Spring Boot 4 starter；保留 JSON 字符串 ID 与已有会话数据契约。
- 技能包二进制文件处理和内置文档镜像同步加固。

## 升级与验证

升级前停止旧进程并备份数据库、workspace、插件及配置。使用 Java 21 构建，检查第三方插件与新版依赖的兼容性；恢复旧版本时使用升级前备份，不能把升级后的数据库降级兼容视为已验证。

本轮完成 Maven reactor、前端构建、PostgreSQL/MySQL 迁移与事务分页、工具审批/取消、进程崩溃恢复及六小时持续运行验证。Kingbase 实机验证尚未覆盖。前端交互接口保持兼容，本轮没有重写聊天 UI。

## AgentScope 2.0.4 上的上下文预算一致性

原生执行路径继续使用稳定的 AgentScope Java 2.0.4 API，不引入 beta Harness 依赖。通过 Spring AI 原生选项合并，将部分运行时选项与模型默认配置组合。共享请求估算覆盖消息、实际生效的工具回调 schema 与一份输出预留，包括 OpenAI completion 上限；显式空回调列表关闭默认工具，总量使用 long 防止整数溢出。推理准备、压缩重试与摘要模型保护共用估算，同时保留调用预算、权限、审批和 Goal 验收。

这些检查用于估算请求大小，不保证供应商接受请求、精确计费或工具参数正确。参见[模型预算规则](./models#上下文预算与请求准备-3-0-0)。

## 升级检查清单

1. 停止旧后端，将数据库、workspace 文件、插件文件及配置一并备份，保留 JWT 密钥和旧版应用包，以便回滚。
2. 使用 Java 21 构建，检查插件与 Boot 4 / Spring AI 2 接口的兼容性。保留数据库 profile 和路径；源码环境从仓库根目录启动，显式指定根目录 `data/` 数据库和工作空间。`mateclaw-server/data/` 是另一份数据库。
3. 保持 Flyway 校验开启。校验失败时先核对 SQL 和表结构，再考虑显式授权的历史修复，不将自动 repair 作为升级默认值。参见[数据库运维说明](./config)。
4. 启动后检查健康状态和登录，确认原有模型配置，再验证真实模型响应、工具批准/拒绝、取消及已有会话。恢复 Goal 前先检查检查点和验收证据，再继续有副作用的工作。
5. 如需回滚，停止新进程，将升级前数据库、文件及配置与旧应用一起恢复，不假定旧二进制能安全打开升级后的数据库。

## 最新预算回归证据（2026-10-20）

预算改动通过 342 项定向后端测试；完整后端测试共 6,509 项，零失败、零错误、50 项跳过。上述数量对应本次验证，不代表前述每项功能的独立验收。

后端使用已配置的根目录数据库、前端使用 5173 端口重启后，经前端 API 代理完成 DeepSeek V4 Flash 的 20 轮真实模型测试。20 轮数值结果正确，流式输出与落库回答一致。原始严格审计通过 17/20；人工复核第 15 轮的纯关键词误判后，验收为 18/20，原始审计标记保留。

仍有两轮失败：第 6 轮将 `language` 放在工具嵌套参数之外，触发 schema 拒绝；第 20 轮将实际 41 次进度更新写成 15 次。任务层恢复没有证明故意拒绝的原始 `print(1)` 调用已成功重试。因此不能将本次结果表述为 20 轮全部通过，也没有据此宣称效率提升。