opensource/mateclaw
2
0
Fork 0
mirror of https://gitee.com/mateos/mateclaw.git synced 2026-09-13 19:23:42 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
1,421 Commits 2 Branches 16 Tags 34 MiB
ed7f6f5c19
Commit Graph

100 Commits

Author SHA1 Message Date
matevip
ed7f6f5c19 feat(chat): add reasoning retention controls and a linear trajectory export 2026-08-06 05:48:28 -04:00
mateaix
2cbe00a1e7 feat(team): plan-execute leads orchestrate through the task board — hand-off bridge, resume gate and step dependencies 2026-07-25 22:22:38 +08:00
mateaix
251a3288dd feat(team): execution hardening, task deliverables and run transcript visibility 2026-07-25 14:32:49 +08:00
matevip
8fa10e3769 feat(team): team_tasks tool with role gating and team context injection into agent prompts 2026-07-24 17:38:02 +08:00
matevip
728ed53062 feat(skill): scope agent runtime skill resolution to the conversation workspace 2026-07-24 14:12:08 +08:00
倪程伟
fc3d84d6c2
fix(wiki): budget the system-prompt KB page listing to the model window 
buildWikiContext enumerated an agent's bound knowledge-base pages into
the system prompt capped only by maxContextChars (default 10000, sized
for large cloud models). On a small-context model a large KB therefore
consumed a big fixed slice of the window on every turn — the "tool token
estimate fills the context" report in #521 (the growth lands in the
system-prompt bucket, not the tool-schema bucket; wiki tool schemas are
fixed-size and do not scale with file count).

Add a budgeted buildWikiContext(agentId, budgetTokens) overload mirroring
buildRelevantContext: the page enumeration also stops once the estimated
token total exceeds the budget, appending the existing
'... and more (use wiki_list_pages)' hint. AgentGraphBuilder passes the
same prefix budget it already applies to the memory block; the legacy
Integer.MAX_VALUE path keeps chars-only behavior for large models.

Tests cover null-budget (all pages), token-budget truncation, and
zero-budget skip.
 2026-07-15 14:52:43 +08:00
MIST
e35c07f742
feat(mcp): progress notifications for long-running MCP tools 
Wire MCP standard notifications/progress into the existing SSE stream so long-running MCP tool calls surface live progress instead of a bare spinner. A per-call progressToken maps back to (conversationId, toolCallId); ProgressAwareMcpToolCallback injects it into tools/call _meta and calls McpSyncClient directly (falling back to the delegate on error, and applying identity forwarding first). Progress events skip the ring buffer and are replayed from a latest-value snapshot on SSE reconnect. Frontend renders a gradient progress bar in ToolCallSegment when a running tool reports progress.
 2026-07-09 18:05:14 +08:00
matevip
cc444f4c06 feat(agent): tool-call loop guard, post-mutation verify reminder, warning chips 2026-07-08 18:18:34 +08:00
MIST
e4dd08b5f4
feat(agent): 注意力锚定与环境感知——MCP 工具溯源 + skill 约束固定 + 事件通知 (#490) 
* feat(agent): 注意力锚定与环境感知——MCP 工具溯源 + skill 约束固定 + 事件通知

## 背景

1. **MCP 工具跨服务器混淆**：MCP 工具名是 `mcp_<serverId>_<slug>_<hash6>`，serverId 是 19 位不可读 Snowflake。LLM 在多服务器任务中常把 slug 拼到错误 serverId 上重构出不存在的工具名，反复重试到 max iterations。
2. **长对话中 skill 约束丢失**：`load_skill` 返回的 SKILL.md 正文存在 messages 历史窗口里，被压缩管线（Soft Trim / Hard Clear / Pre-Prune / LLM Summary）销毁，约束彻底消失，agent 后续步骤违反约束。
3. **运行时环境变更对 agent 不可见**：MCP 服务器断连 / skill 更新发生在 agent 推理中途时，工具列表是 turn-start 快照，LLM 无法感知，继续调用已失效的工具。
4. **ledger 条目可被 LLM 反向覆盖**：Java 用 `auto_`/`pin_` 前缀让位给 LLM，但 LLM 没有反向保护——`progress_update(stepKey="auto_read_file")` 会覆盖 Java 写入的条目，保护是单向的。
5. **SkillManifestParser 从未填充 constraints 字段**：`KNOWN_KEYS` 未列入 `"constraints"`，导致约束被静默路由到 `extras`，所有依赖 `manifest.getConstraints()` 的代码都是死代码。

## 改动内容

### 文件改动

**新增文件（生产代码 4 个）**
- **`mateclaw-server/.../agent/runtime/EnvironmentNotification.java`** — 环境变更通知 record（type / message / timestamp）。
- **`mateclaw-server/.../agent/runtime/RunningConversationRegistry.java`** — 跟踪活跃会话 + 每会话有界通知队列（上限 10）+ TTL 定时清理（30 分钟未活跃的 handle 自动回收）。
- **`mateclaw-server/.../agent/runtime/EnvironmentEventRouter.java`** — 5 个 `@EventListener` 把 MCP/skill 事件翻译成中文 LLM 通知并广播。
- **`mateclaw-server/.../skill/event/SkillUpdatedEvent.java`** — skill 更新/启用/禁用/重扫描事件。

**新增文件（测试 5 个）**
- **`mateclaw-server/.../skill/manifest/SkillManifestConstraintsParsingTest.java`** — constraints 解析白盒测试（5 用例）。
- **`mateclaw-server/.../agent/progress/ProgressLedgerPrefixGuardTest.java`** — 前缀守卫 + 三类条目 + 并发 + 批量 auto-record 白盒（22 用例）。
- **`mateclaw-server/.../agent/runtime/RunningConversationRegistryTest.java`** — registry + router 生命周期 + TTL 清理白盒（24 用例）。
- **`mateclaw-server/.../agent/context/ContextCompressionLedgerSurvivalTest.java`** — 三类条目压缩存活黑盒（5 用例）。
- **`mateclaw-server/.../agent/graph/node/EnvironmentNotificationRenderingTest.java`** — 事件→通知→LLM 可见黑盒（14 用例）。

**修改文件（生产代码 14 个）**
- **`mateclaw-server/.../agent/progress/ProgressLedger.java`** — 增加 `pinned` map + `AUTO_RECORDED_PREFIX` 常量 + 三类条目区分；`mostRecentUpdate` 只看 regular 条目；`renderStaleReminder` 补 pending 计数。
- **`mateclaw-server/.../agent/progress/ProgressLedgerService.java`** — JSON 格式升级为 wrapper `{entries, pinned}`（向后兼容旧 flat-map）；`upsert` 加 `auto_`/`pin_` 前缀守卫；`upsertPinned` / `upsertAutoRecorded` / `clearPinnedByPrefix` / `upsertAutoRecordedBatch`（批量版，一次 lock+load+save 处理 N 个工具响应）；auto-recorded 4 参签名避免跨服务器键碰撞，有界=5。
- **`mateclaw-server/.../agent/graph/node/ActionNode.java`** — `load_skill` 后 `pinSkillConstraints` 把约束写入 pinned；工具调用后 `autoRecordToolCalls` 收集批量后一次 `upsertAutoRecordedBatch`（避免 N 次 lock+save 串行化）；setter 注入保持测试构造器兼容。
- **`mateclaw-server/.../agent/graph/node/ReasoningNode.java`** — C4 注入：drain 通知 → `renderEnvironmentNotifications` → SystemMessage 加入 nonHistoryPrefix；helper 改 package-private 供黑盒测试。
- **`mateclaw-server/.../agent/AgentGraphBuilder.java`** — 系统提示增加 ProgressLedger Discipline 段（agent-3）+ Environment Change Notifications 段（agent-1）；SkillCatalog 渲染器扫描约束加 🔒 锚点（agent-4）；wire ActionNode setter + ReasoningNode registry。
- **`mateclaw-server/.../agent/AgentService.java`** — `withLifecycleSync` / `withLifecycleFlux` 入口 `safeRegister`、出口 `safeUnregister`，覆盖 Flux 抛错路径。
- **`mateclaw-server/.../skill/manifest/SkillManifest.java`** — 增加 `constraints` 字段（List<String>）。
- **`mateclaw-server/.../skill/manifest/SkillManifestParser.java`** — `KNOWN_KEYS` 加 `"constraints"`；builder 链加 `.constraints(stringList(fm.get("constraints")))`。
- **`mateclaw-server/.../skill/service/SkillService.java`** — 4 个改动点发布 `SkillUpdatedEvent`（rescan / update builtin / update non-builtin / toggle enable-disable）。
- **`mateclaw-server/.../tool/builtin/ProgressLedgerTool.java`** — `@Tool` 描述声明 `auto_`/`pin_` 前缀保留；`@ToolParam stepKey` 同步警告。
- **`mateclaw-server/.../tool/mcp/runtime/PrefixedNameToolCallback.java`** — 新增 3 参构造器，serverName 非空时描述前缀 `[MCP server: <name>]`，让 LLM 区分跨服务器同名工具。
- **`mateclaw-server/.../tool/mcp/runtime/McpClientManager.java`** — `wrapServerCallbacks` 透传 serverName 到 PrefixedNameToolCallback。
- **`mateclaw-server/.../agent/context/ConversationWindowManager.java`** — `PRUNE_EXEMPT_TOOLS` 加入 `load_skill`（A1）。
- **`mateclaw-server/.../agent/graph/executor/ToolExecutionExecutor.java`** — 工具不存在时 `buildMcpAwareNotFoundMessage` 跨服务器搜索同 slug/hash 候选，给出 ≤5 个建议名。

**修改文件（测试 1 个）**
- **`mateclaw-server/.../agent/progress/ProgressLedgerStaleReminderTest.java`** — 回归适配：reminder 文本现在包含 `pending` 计数。

### 测试

- `mvn -pl mateclaw-server -am test -Dtest='SkillManifestConstraintsParsingTest,ProgressLedgerPrefixGuardTest,RunningConversationRegistryTest,ContextCompressionLedgerSurvivalTest,EnvironmentNotificationRenderingTest,ProgressLedgerStaleReminderTest'`：70/70 通过
- `mvn -pl mateclaw-server -am test`（全量回归，含上面 6 个 + 12 个深挖影响类）：0 失败 0 错误

### 安全性

- **前缀保留**：`ProgressLedgerService.upsert` 拒绝 `auto_`/`pin_` 前缀，LLM 无法覆盖 Java 管理的条目；`@Tool` 描述显式声明保留前缀。
- **事件路由异常隔离**：`EnvironmentEventRouter.broadcast` 全 try/catch，路由失败永不冒泡到 Spring 事件总线。
- **并发安全**：registry 用 `ConcurrentHashMap` + `ConcurrentLinkedQueue`；ledger upsert 用 per-conversation `ReentrantLock`；批量 auto-record 在单次 lock 内完成；`ProgressLedgerPrefixGuardTest.concurrentUpsertAndAutoRecordAreSafe` 锁定。
- **内存有界**：通知队列每会话上限 10（LRU 驱逐最老）；auto-recorded 条目每会话上限 5（驱逐最老）；registry 后台 TTL 清理（30 分钟未活跃的 handle 自动回收）。
- **绑定机制不受影响**：MCP/skill 的 agent 绑定（`mate_agent_tool` / `mate_agent_skill` 表）完全未被触碰；C3 通知广播是有意全量（非按 agentId 过滤），最坏情况是无关 agent 多收一条 SystemMessage（LLM 被告知"如无关可忽略"）。

## 逐项验证

### 改动 1：SkillManifestParser 真正解析 constraints（深挖修复）

**文件**：`mateclaw-server/src/main/java/vip/mate/skill/manifest/SkillManifestParser.java:33-47,108`

| 项 | 内容 |
|---|---|
| 改了什么 | `KNOWN_KEYS` 集合加入 `"constraints"`；builder 链加入 `.constraints(stringList(fm.get("constraints")))`。 |
| 为什么 | 之前 `KNOWN_KEYS` 没列入 `"constraints"`，导致该键被静默路由到 `extras`，`manifest.getConstraints()` 永远返回空 list，下游 B2 pinSkillConstraints 和 agent-4 catalog 锚点全是死代码。 |
| 验证步骤 | 1. `cat test-fixtures/skill-with-constraints/SKILL.md`（如有）确认 frontmatter 有 `constraints: [...]`；2. 运行 `SkillManifestConstraintsParsingTest`。 |
| 预期结果 | `manifest.getConstraints()` 返回非空 list；test 5/5 通过。 |

### 改动 2：ProgressLedgerService 前缀守卫（深挖修复）

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/progress/ProgressLedgerService.java:132-137`

| 项 | 内容 |
|---|---|
| 改了什么 | `upsert()` 入口检查 key 是否以 `auto_` 或 `pin_` 开头，是则抛 `IllegalArgumentException`。 |
| 为什么 | 之前保护是单向的：Java 让位 LLM（auto 不覆盖 LLM 已有 entry），但 LLM 可以用 `progress_update(stepKey="auto_read_file")` 覆盖 Java 写入的条目，导致 auto-recorded 工具记录被改写。 |
| 验证步骤 | 1. `ProgressLedgerPrefixGuardTest.upsertRejectsAutoPrefix`；2. `ProgressLedgerPrefixGuardTest.upsertRejectsPinPrefix`。 |
| 预期结果 | 两个测试均抛 `IllegalArgumentException`；`ProgressLedgerTool` 的 `@Tool` 描述包含前缀保留声明。 |

### 改动 3：upsertAutoRecorded 4 参签名 + 批量化（深挖修复 + 性能优化）

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/progress/ProgressLedgerService.java:227-296`、`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java`（`autoRecordToolCalls`）

| 项 | 内容 |
|---|---|
| 改了什么 | `upsertAutoRecorded` 升级为 4 参签名 `(conversationId, toolName, displayName, resultSummary)`；新增 `upsertAutoRecordedBatch` 批量方法，一次 lock+load+save 处理 N 个工具响应；ActionNode 改为先收集 `List<AutoRecordEntry>` 再一次批量调用。 |
| 为什么 | 1. 跨服务器键碰撞：两个 MCP 服务器都暴露 `search` 工具 → `auto_search` 互相覆盖；2. 并行工具串行化：每个 ToolResponse 单独 lock+load+save 抵消并行收益。 |
| 验证步骤 | 1. `ProgressLedgerPrefixGuardTest.autoRecordedDifferentServersNoCollision`：两个服务器同名工具共存；2. `ProgressLedgerPrefixGuardTest.batchInsertProducesSameResultAsSequential`：批量与逐条结果一致；3. `ProgressLedgerPrefixGuardTest.batchInsertBoundedToMaxFiveEvenWithLargeBatch`：10 条批量插入后有界=5。 |
| 预期结果 | ledger 中同时存在 `auto_mcp_4_search_xxx` 和 `auto_mcp_7_search_yyy`；5 个并行工具调用从 5 次 lock+save 降为 1 次。 |

### 改动 4：B2 pinSkillConstraints——load_skill 后约束写入 pinned

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java`（`pinSkillConstraints`）

| 项 | 内容 |
|---|---|
| 改了什么 | `load_skill` 工具调用成功后，读取 `manifest.getConstraints()`，对每条约束调用 `progressLedgerService.upsertPinned(convId, "pin_<skillName>_<i>", constraintText, note)`。 |
| 为什么 | 把约束从 messages（会被压缩销毁）抽到 DB ledger.pinned（压缩免疫），解决"长对话中 skill 约束丢失"问题。 |
| 验证步骤 | 1. `ContextCompressionLedgerSurvivalTest.loadSkillBodyDestroyedByCompressionButConstraintsSurviveInLedger`；2. `ContextCompressionLedgerSurvivalTest.allThreeLedgerEntryTypesSurviveCompression`。 |
| 预期结果 | 压缩后 messages 中 load_skill 正文消失，但 `ledger.renderSnapshot()` 仍包含 `🔒 固定约束` 段，约束文本字节级保留。 |

### 改动 5：B5 autoRecordToolCalls——工具调用后批量自动记录

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java`（`autoRecordToolCalls`）

| 项 | 内容 |
|---|---|
| 改了什么 | ActionNode 处理 ToolResponse 后，收集所有有效条目到 `List<AutoRecordEntry>`，一次调用 `upsertAutoRecordedBatch`。 |
| 为什么 | 让 LLM 在长对话中即使忘记自己刚调用过什么工具，也能从 ledger 快照看到最近 5 次工具调用记录；批量调用避免 N 次 lock+save 串行化。 |
| 验证步骤 | `ProgressLedgerPrefixGuardTest.autoRecordedBoundedToMaxFive`：模拟 10 次工具调用，验证 auto 条目数等于 5。 |
| 预期结果 | ledger 中 auto 条目始终 ≤ 5，最老的被驱逐；5 个并行工具调用只需 1 次 DB roundtrip。 |

### 改动 6：C4 环境通知注入 nonHistoryPrefix

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java:755-765,1201-1215`

| 项 | 内容 |
|---|---|
| 改了什么 | ReasoningNode 每轮推理前 `registry.drain(conversationId)`，非空则 `renderEnvironmentNotifications` 渲染成 markdown 块，作为 SystemMessage 加入 nonHistoryPrefix。 |
| 为什么 | 让运行时环境变更（MCP 断连 / skill 更新）在下一轮推理立即可见，LLM 主动改路而不是反复重试失效工具。 |
| 验证步骤 | `EnvironmentNotificationRenderingTest.mcpConnectionLostEventEndToEnd_producesActionableLLMText`：注册会话 → 触发 `McpConnectionLostEvent(serverId=7)` → drain → render。 |
| 预期结果 | 渲染块包含 "📢 环境变更通知"、`mcp_7_` 前缀、"不要反复重试" 指令。 |

### 改动 7：A1 PRUNE_EXEMPT_TOOLS 加入 load_skill

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java:96-120`

| 项 | 内容 |
|---|---|
| 改了什么 | `PRUNE_EXEMPT_TOOLS` 集合从 `{delegateToAgent, delegateParallel}` 扩展为 `{delegateToAgent, delegateParallel, load_skill}`。 |
| 为什么 | `load_skill` 返回的 SKILL.md 是 load-time 快照，skill 作者可能在执行期间更新，重载不保证恢复相同指令；且 50KB+ skill 重载昂贵。 |
| 验证步骤 | `ConversationWindowManagerToolPruningTest`（已有测试套件）。 |
| 预期结果 | load_skill 的 ToolResponseMessage 在 `pruneOldToolResultsForModelInput` / `compactAgedToolResponses` 阶段不被修剪。 |

### 改动 8：agent-2 PrefixedNameToolCallback 描述加 serverName 标签

**文件**：`mateclaw-server/src/main/java/vip/mate/tool/mcp/runtime/PrefixedNameToolCallback.java:55-80`、`mateclaw-server/src/main/java/vip/mate/tool/mcp/runtime/McpClientManager.java:201-300`

| 项 | 内容 |
|---|---|
| 改了什么 | 新增 3 参构造器 `(prefixedName, delegate, serverName)`，serverName 非空时描述前缀 `[MCP server: <name>]`；McpClientManager `wrapServerCallbacks` 透传 serverName。 |
| 为什么 | LLM 看到 `mcp_4_search_a1b2c3` 时无法知道这是哪个服务器的工具；多个 MCP 服务器都暴露 `search` 时，LLM 会混淆。加 `[MCP server: fetch-server]` 标签让 LLM 区分。 |
| 验证步骤 | 启动一个 MCP 服务器，在 agent 工具列表中观察工具描述是否包含 `[MCP server: <name>]` 前缀。 |
| 预期结果 | 每个 MCP 工具描述开头包含 `[MCP server: <serverName>]`；2 参构造器（无 serverName）保持向后兼容，描述不加前缀。 |

### 改动 9：ToolExecutionExecutor 工具不存在时跨服务器候选建议

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java:1264-1340`

| 项 | 内容 |
|---|---|
| 改了什么 | "Tool not found" 错误信息升级：若请求名是 MCP 格式，搜索 `toolCallbackMap` 中 slug 或 hash6 匹配但 serverId 不同的候选，返回 ≤5 个建议。 |
| 为什么 | LLM 常把 slug 拼到错误 serverId 上重构出不存在工具名，反复重试到 max iterations。给候选建议后 LLM 可以直接复制正确名字。 |
| 验证步骤 | 1. 启动两个 MCP 服务器都暴露 `fetch` 工具；2. 让 LLM 调用 `mcp_<serverA>_fetch_xxx`（实际 fetch 在 serverB）；3. 观察错误信息。 |
| 预期结果 | 错误信息包含 "Did you mean one of these?" + 正确的 `mcp_<serverB>_fetch_yyy` 候选名。 |

### 改动 10：Registry TTL 定时清理（防泄漏）

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/runtime/RunningConversationRegistry.java:155-211`

| 项 | 内容 |
|---|---|
| 改了什么 | 新增 `cleanupStale(Duration maxAge)` 方法 + `@Scheduled scheduledCleanup()`（每 5 分钟扫一次，清理 30 分钟未活跃的 handle）。用 `remove(key, value)` 保证不误删被并发 `register` 刷新的 handle。 |
| 为什么 | 兜底防御异常路径泄漏的 handle——即使 `safeUnregister` 因异常路径未执行（如 Reactor cancel 信号不触发 doFinally），后台线程也能回收。 |
| 验证步骤 | `RunningConversationRegistryTest.cleanupStaleRemovesOldHandles`：注册 → 反射 backdate lastActiveAt → 清理 → 验证被移除；`cleanupStaleDoesNotRemoveRefreshedHandle`：backdate 后 re-register → 清理 → 验证存活。 |
| 预期结果 | 30 分钟未活跃的 handle 被清理；被 `register` 刷新的 handle 不被误删。 |

### 改动 11：JSON 格式向后兼容迁移

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/progress/ProgressLedgerService.java:79-85,284-292`

| 项 | 内容 |
|---|---|
| 改了什么 | JSON 从 flat-map `{"step1":{...}}` 升级为 wrapper `{"entries":{...},"pinned":{...}}`；`parseWrapper` 通过 peek `"entries"` 键区分新旧格式，旧格式自动迁移为 wrapper（pinned 为空）。 |
| 为什么 | 老 conversation 的 ledger 列存的是 flat-map，新代码上线后必须能加载老数据。 |
| 验证步骤 | `ContextCompressionLedgerSurvivalTest.oldFlatMapLedgerMigratesToWrapperFormatWithEmptyPinned`：写入旧 JSON → load → 验证 pinned 为空 → upsert → 验证新 JSON 包含 `entries` 和 `pinned` 键。 |
| 预期结果 | 旧 conversation 无需迁移脚本，第一次 load 即兼容；写入时自动转为新格式。 |

## 新增测试验证

**文件**：
- `mateclaw-server/src/test/java/vip/mate/skill/manifest/SkillManifestConstraintsParsingTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/progress/ProgressLedgerPrefixGuardTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/runtime/RunningConversationRegistryTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/context/ContextCompressionLedgerSurvivalTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/graph/node/EnvironmentNotificationRenderingTest.java`

| 命令 | 预期 |
|------|------|
| `mvn -pl mateclaw-server -am test -Dtest='SkillManifestConstraintsParsingTest'` | Tests run: 5, Failures: 0 |
| `mvn -pl mateclaw-server -am test -Dtest='ProgressLedgerPrefixGuardTest'` | Tests run: 22, Failures: 0 |
| `mvn -pl mateclaw-server -am test -Dtest='RunningConversationRegistryTest'` | Tests run: 24, Failures: 0 |
| `mvn -pl mateclaw-server -am test -Dtest='ContextCompressionLedgerSurvivalTest'` | Tests run: 5, Failures: 0 |
| `mvn -pl mateclaw-server -am test -Dtest='EnvironmentNotificationRenderingTest'` | Tests run: 14, Failures: 0 |

## 回归检查清单

- [ ] 全量 `mvn -pl mateclaw-server -am test` 通过（已验证 0 失败 0 错误）
- [ ] 老 conversation（flat-map ledger JSON）首次 load 不报错，pinned 字段为空
- [ ] 多 MCP 服务器场景：LLM 工具列表中每个工具描述包含 `[MCP server: <name>]` 标签
- [ ] MCP 服务器中途断连：agent 下一轮推理看到 `📢 环境变更通知` 块，主动改路
- [ ] 长 conversation（>100 轮）经多次 PTL 压缩后，`ledger.renderSnapshot()` 仍包含 pinned 约束
- [ ] `progress_update(stepKey="auto_xxx")` 被拒绝，返回 `IllegalArgumentException` 错误信息
- [ ] auto-recorded 条目数始终 ≤ 5（10 次工具调用后仍为 5）
- [ ] 5 个并行工具调用只产生 1 次 DB roundtrip（批量 auto-record）
- [ ] Registry 中 30 分钟未活跃的 handle 被后台定时清理
- [ ] MCP/skill 绑定机制（`mate_agent_tool` / `mate_agent_skill` 表）不受影响
- [ ] Plan-Execute 路径（StepExecutionNode）目前**不**接收环境通知——只有 ReAct 路径生效（已知未覆盖项，不阻塞本 PR）

* feat(agent): 六招减法重构——修复压缩销毁 skill 约束与 MCP 按需暴露

## 背景

- 压缩三阶段（softTrim / hardClear / prePruneForSummary）只检查 `isSpillMarker`，不检查 `PRUNE_EXEMPT_TOOLS`，导致 `load_skill` 返回的 SKILL.md 约束、`delegateToAgent` 子智能体转录在压缩中被裁掉，模型在长对话中"忘记"任务规则，根因是"压缩导致注意力失效"。
- skillCatalog 表只列 Skill / Status / Description 三列，bound skill 的 constraints 与 allowedTools 没有任何可见入口，模型加载 skill 后约束仍可能被忽略。
- MCP 工具默认 CORE tier，20+ MCP 工具的 schema 涌入核心列表，挤占 builtin 工具的注意力，且 `DisclosureTier.fromToken(null)` 返回 CORE 导致 `getOrDefault` 的默认值永远不生效。
- 构建期工具过滤分 4 次 pass，重复遍历且无明确 deny/allow 边界。
- skillCatalog 在每次推理步都按当前 loadedSkills 动态渲染，破坏 Anthropic SYSTEM_AND_TOOLS cache 前缀稳定性。
- 进度账本（ProgressLedger）约束条目前缀无保护，跨 MCP server 键碰撞，环境事件无统一路由入口。

## 改动内容

### 文件改动

**主代码（21 个文件）**

- **`mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java`** — Move 4：三阶段新增 `isExemptTool` 检查跳过 `load_skill`/`delegateToAgent`/`delegateParallel`；新增 Phase 2.7 无损 spill evict 在调用 LLM 摘要前把超大工具结果落盘
- **`mateclaw-server/src/main/java/vip/mate/skill/runtime/SkillRuntimeService.java`** — Move 2 & 3：catalog 表新增 Constraints 列（仅 bound skill 显示）；新增 `### Bound skill allowed tools` 块
- **`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java`** — Move 1：skillCatalog 用 `render(Set.of())` 静态渲染进 nonHistoryPrefix；loadedThisRun hint 作为 volatile 后缀注入
- **`mateclaw-server/src/main/java/vip/mate/tool/disclosure/DefaultToolDisclosureService.java`** — Move 5：MCP 工具默认 tier 从 CORE 改 EXTENSION；`buildSnapshot` 跳过 null/blank tier 修复 `fromToken(null)→CORE` 陷阱
- **`mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java`** — Move 6：构建期权限过滤从 4 次 pass 合并为 2 次（deny 集 + allow 集）
- **`mateclaw-server/src/main/java/vip/mate/agent/AgentService.java`** — 接入 EnvironmentEventRouter 与 RunningConversationRegistry
- **`mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java`** — 工具调用后自动回填 ProgressLedger
- **`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ActionNode.java`** — 渲染 ledger 三段式快照
- **`mateclaw-server/src/main/java/vip/mate/agent/progress/ProgressLedger.java`** — constraints 前缀保护，跨 MCP server 键命名空间隔离
- **`mateclaw-server/src/main/java/vip/mate/agent/progress/ProgressLedgerService.java`** — 写入 constraints 到 pinned 条目
- **`mateclaw-server/src/main/java/vip/mate/skill/manifest/SkillManifest.java`** — 新增 constraints 字段
- **`mateclaw-server/src/main/java/vip/mate/skill/manifest/SkillManifestParser.java`** — 解析 SKILL.md frontmatter 中的 constraints
- **`mateclaw-server/src/main/java/vip/mate/skill/service/SkillService.java`** — skill 更新事件发布
- **`mateclaw-server/src/main/java/vip/mate/tool/builtin/ProgressLedgerTool.java`** — 三段式渲染
- **`mateclaw-server/src/main/java/vip/mate/tool/mcp/runtime/McpClientManager.java`** — MCP 命名透明化
- **`mateclaw-server/src/main/java/vip/mate/tool/mcp/runtime/PrefixedNameToolCallback.java`** — 透明命名映射
- **`mateclaw-server/src/main/java/vip/mate/agent/runtime/EnvironmentEventRouter.java`** — 新增：5 个环境事件监听器
- **`mateclaw-server/src/main/java/vip/mate/agent/runtime/EnvironmentNotification.java`** — 新增：环境通知数据模型
- **`mateclaw-server/src/main/java/vip/mate/agent/runtime/RunningConversationRegistry.java`** — 新增：运行中会话注册表 + TTL 清理
- **`mateclaw-server/src/main/java/vip/mate/skill/event/SkillUpdatedEvent.java`** — 新增：skill 更新事件
- **`mateclaw-server/Dockerfile`** — 构建配置微调

**测试代码（11 个文件）**

- **`ConversationWindowManagerExemptAndSpillTest.java`** — 新增 15 个行为测试，证明 Move 4 生效
- **`SkillRuntimeServiceConstraintsAndToolsTest.java`** — 新增 8 个测试覆盖 Constraints 列与 allowedTools 块
- **`ReasoningNodeLoadedSkillsHintTest.java`** — 新增 8 个测试覆盖 loadedThisRun hint 渲染
- **`CompactionSurvivalComparisonTest.java`** — 新增 4 个场景的新旧代码对比测试（100 轮极限压缩）
- **`ContextCompressionLedgerSurvivalTest.java`** — 压缩后 ledger 存活测试
- **`EnvironmentNotificationRenderingTest.java`** — 环境通知渲染测试
- **`ProgressLedgerPrefixGuardTest.java`** — ledger 前缀保护测试
- **`RunningConversationRegistryTest.java`** — 会话注册表测试
- **`SkillManifestConstraintsParsingTest.java`** — constraints 解析测试
- **`ProgressLedgerStaleReminderTest.java`** — 修复回归
- **`ToolDisclosureServiceTest.java`** — 断言从 CORE 改为 EXTENSION

### 测试

**回归测试**

- `mvn test`（mateclaw-server 全量）：**199 通过 / 1 跳过 / 0 失败**

**行为测试（证明改动生效，旧代码上失败）**

- `CompactionSurvivalComparisonTest`（4 个场景）：在新代码上全部通过
- 用 `git stash` 还原旧代码后，16 个行为测试编译失败或断言失败 → 证明测试确实覆盖了新行为

**新旧代码对比测试（同一份测试源码，两套代码库运行）**

| 场景 | 旧代码 | 新代码 |
|---|---|---|
| A: 50 load_skill + 50 delegate + 50 read_file 单轮压缩 | load_skill 0/50, delegate 0/50 | **load_skill 50/50, delegate 50/50** |
| B: 100 轮极限压缩 + 头部 pinned load_skill | root_constraint_survived=**false**, 113ms | root_constraint_survived=**true**, 60ms |
| C: 20 个不同大小 load_skill 单轮压缩 | 0/20 存活, tokens 8694→754 | **20/20 存活**, tokens 8694→8694 |
| D: 30 轮稳态压缩 + pinned skill | pinned_survived=**false** | pinned_survived=**true** |

### 安全性

- `DisclosureTier.fromToken(null)` 陷阱修复：旧代码 `serverTierById.put(id, CORE)` 导致 `getOrDefault` 默认值永不生效；新代码跳过 null tier，未配置的 MCP server 才走 EXTENSION 默认值
- `PRUNE_EXEMPT_TOOLS` 保护范围从 2 处扩展到 5 处，避免 `load_skill` 约束被压缩销毁后模型在无约束下执行敏感操作

## 逐项验证

### 改动 1：nonHistoryPrefix 分层稳定化

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java:701-714, 776-788, 1246-1257`

| 项 | 内容 |
|---|---|
| 改了什么 | skillCatalog 用 `render(Set.of())` 静态渲染进 nonHistoryPrefix；loadedThisRun hint 作为 volatile 后缀注入 |
| 为什么 | 每次推理步都按 loadedSkills 动态渲染会破坏 Anthropic SYSTEM_AND_TOOLS cache 前缀，导致 cache 失效增加 token 成本 |
| 验证步骤 | 1. 打开 ReasoningNode.java:701；2. 确认 `skillCatalogRenderer.render(java.util.Set.of())` 调用；3. 跑 `ReasoningNodeLoadedSkillsHintTest` |
| 预期结果 | 8 个测试通过，loadedThisRun hint 作为后缀注入，不破坏前缀缓存 |

### 改动 2：skillCatalog 增加 Constraints 列

**文件**：`mateclaw-server/src/main/java/vip/mate/skill/runtime/SkillRuntimeService.java:502-561, 634-641`

| 项 | 内容 |
|---|---|
| 改了什么 | catalog 表从 3 列扩为 4 列，新增 Constraints 列（仅 bound skill 显示，长约束截断，pipe 转义）；新增 `### Bound skill allowed tools` 块 |
| 为什么 | bound skill 的 constraints 没有任何可见入口，模型加载后仍可能忽略 |
| 验证步骤 | 1. 跑 `SkillRuntimeServiceConstraintsAndToolsTest`；2. 检查 catalog 渲染包含 Constraints 列 |
| 预期结果 | 8 个测试通过，bound skill 显示 constraints，非 bound skill 省略 |
- **边界验证**：长约束截断为单行；pipe 字符被转义不破坏表格

### 改动 3：修复 PRUNE_EXEMPT_TOOLS 在三阶段的绕过

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java:990-994, 1030-1090, 1160-1210`

| 项 | 内容 |
|---|---|
| 改了什么 | `softTrimToolResults`、`hardClearToolResults`、`prePruneForSummary` 三处新增 `isExemptTool` 检查，跳过 `load_skill`/`delegateToAgent`/`delegateParallel` |
| 为什么 | 旧代码只在 `pruneOldToolResultsForModelInput` 和 `compactAgedToolResponses` 检查 exempt，三阶段不检查，导致 skill 约束在压缩中被裁掉 |
| 验证步骤 | 1. 跑 `ConversationWindowManagerExemptAndSpillTest`；2. 跑 `CompactionSurvivalComparisonTest` |
| 预期结果 | 15 个行为测试通过；100 轮压缩后 load_skill body 存活率 100% |
- **反例对照**：在新代码上跑对比测试，旧代码存活率 0%，新代码 100%

### 改动 4：Phase 2.7 无损 spill evict

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java:440-468, 1263-1300`

| 项 | 内容 |
|---|---|
| 改了什么 | 在 Phase 2 hardClear 之后、LLM 摘要之前新增 Phase 2.7，把超大工具结果落盘替换为 spill marker |
| 为什么 | 旧代码超出预算直接走 LLM 摘要（有损+耗时+费 token），其实大部分场景落盘就够 |
| 验证步骤 | 1. 检查 `spillEvictToolResults` 方法；2. 跑 `ConversationWindowManagerExemptAndSpillTest.spillEvictReducesTokenCount` |
| 预期结果 | spill 后 token 数低于预算时跳过 LLM 摘要，strategy=lossless_spill_evict |

### 改动 5：MCP 工具默认 EXTENSION

**文件**：`mateclaw-server/src/main/java/vip/mate/tool/disclosure/DefaultToolDisclosureService.java:78-105, 276-336`

| 项 | 内容 |
|---|---|
| 改了什么 | `resolveTierByName` 默认返回 EXTENSION；`buildSnapshot` 跳过 null/blank tier 的 server 不放入 map |
| 为什么 | MCP schema 是 prompt 最重部分，默认 CORE 挤占 builtin 工具注意力；`fromToken(null)` 返回 CORE 导致默认值失效 |
| 验证步骤 | 1. 跑 `ToolDisclosureServiceTest.mcpDefaultsExtensionWhenServerTierUnset`；2. 检查未配置 tier 的 MCP server 工具不在 active 列表 |
| 预期结果 | 未配置 tier 的 MCP 工具进入 extensionCatalog，需 `enable_tool` 激活 |
- **边界验证**：显式 `disclosure_tier=core` 的 server 仍保持 CORE

### 改动 6：构建期权限过滤合并

**文件**：`mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java:258-310`

| 项 | 内容 |
|---|---|
| 改了什么 | 4 次 pass 合并为 2 次：先 `withDeniedToolsFiltered(deniedSet)`，再 `withAllowedToolsOnly(boundTools)` |
| 为什么 | 重复遍历浪费构建时间，且 deny/allow 边界不清晰 |
| 验证步骤 | 1. 检查 AgentGraphBuilder.java:258-310；2. 跑全量回归测试确认工具过滤行为不变 |
| 预期结果 | 工具列表与改动前一致，构建步骤减少 |

## 新增测试验证

**文件**：

- `mateclaw-server/src/test/java/vip/mate/agent/context/ConversationWindowManagerExemptAndSpillTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/context/CompactionSurvivalComparisonTest.java`
- `mateclaw-server/src/test/java/vip/mate/skill/runtime/SkillRuntimeServiceConstraintsAndToolsTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/graph/node/ReasoningNodeLoadedSkillsHintTest.java`
- `mateclaw-server/src/test/java/vip/mate/skill/manifest/SkillManifestConstraintsParsingTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/progress/ProgressLedgerPrefixGuardTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/runtime/RunningConversationRegistryTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/graph/node/EnvironmentNotificationRenderingTest.java`
- `mateclaw-server/src/test/java/vip/mate/agent/context/ContextCompressionLedgerSurvivalTest.java`

| 命令 | 预期 |
|------|------|
| `mvn -Dtest=ConversationWindowManagerExemptAndSpillTest test` | 15 个测试通过 |
| `mvn -Dtest=CompactionSurvivalComparisonTest test` | 4 个场景通过，新代码 load_skill 存活率 100% |
| `mvn -Dtest=SkillRuntimeServiceConstraintsAndToolsTest test` | 8 个测试通过 |
| `mvn -Dtest=ReasoningNodeLoadedSkillsHintTest test` | 8 个测试通过 |
| `mvn test`（全量） | 199 通过 / 1 跳过 / 0 失败 |

**新旧对比测试运行命令**：

```bash
# 新代码
cd /data/mateclaw/mateclaw-server && mvn -Dtest=CompactionSurvivalComparisonTest -Dsurefire.useFile=false test

# 旧代码（需把测试复制到 mateclaw-old）
cd /data/mateclaw/mateclaw-old/mateclaw-server && mvn -Dtest=CompactionSurvivalComparisonTest -Dsurefire.useFile=false test
```

## 回归检查清单

- [ ] `mvn test` 全量通过（199/1skip/0fail）
- [ ] 对比测试在新代码上 load_skill 存活率 100%
- [ ] 对比测试在旧代码上 load_skill 存活率 0%（证明测试有效）
- [ ] MCP 工具默认进入 extensionCatalog，`enable_tool` 可激活
- [ ] 显式 `disclosure_tier=core` 的 MCP server 仍保持 CORE
- [ ] 100 轮压缩后 root_constraint 仍存活
- [ ] Phase 2.7 spill evict 在预算内时跳过 LLM 摘要
- [ ] skillCatalog 静态渲染不依赖 loadedSkills，前缀缓存稳定
 2026-07-06 11:50:41 +08:00
matevip
35142508db fix(agent): 推理节点尊重模型配置的 maxTokens 输出上限,并按真实窗口钳制,修复严格本地服务端的 max_tokens 预检拒绝 2026-07-03 19:11:37 +08:00
matevip
bf0d64e46a feat(tool): 工具 schema 预算阈值门——超出窗口预算时按使用频度自动降级到扩展目录,enable_tool 可找回 2026-07-03 18:52:45 +08:00
matevip
56737e197f feat(agent): prefix 注入块统一 token 预算——记忆/Wiki 注入随模型有效窗口缩放,身份 prompt 超大告警 2026-07-03 18:51:32 +08:00
matevip
67fd74f7fb feat(llm): 本地模型上下文窗口探测——Ollama/vLLM 真实窗口接入会话预算,超限报错自动反解窗口值 2026-07-03 18:51:08 +08:00
matevip
25737495e5 feat(chat): per-turn token usage breakdown with cache hit/miss/write and reasoning split (#474) 2026-07-03 11:28:00 +08:00
MIST
dcc8c9aed3
修复同一 Agent 多并发会话记忆混乱问题 (#458) 
### 问题现象
同一 agent 开多个并发会话时（如 A1=查南京天气、A2=查北京天气），A2 在多轮 ReAct 执行中会"突然去查南京天气"，表现为 A1 会话的上下文泄漏到 A2 会话。

### 根因4：Agent 实例共享 + state 覆盖（确认，仅状态显示问题）
确认点：
- AgentService.java:83-90 agentInstances 按 (agentId, modelKey) 缓存，不含 conversationId
- AgentService.java:598-624 getOrBuildAgentForConversation 只按 (agentId, provider, model) 解析，不按 conversationId
- AgentService.java:530-545 withLifecycleFlux 无锁 ，A/B/C 完全并发
影响： A 完成设 IDLE → B 仍在运行但显示 IDLE → 状态显示错乱。 不会直接导致记忆串台 ，但对用户可见。

## 二、根因与症状匹配度总结
根因 匹配度 触发条件 串台通道 1. SessionSearchTool ★★★★★ LLM 多轮遇到困难时主动调用 session_search 返回并发兄弟会话消息 2. 审批重放无过滤 ★★★☆☆ Plan-Execute + 审批 + 并发 awaiting_approval 误取兄弟会话计划 3. 结构化记忆共享 ★★★☆☆ A 会话 LLM 主动 remember_structured 写入 prefetch 注入到 B 会话 4. Agent 实例共享 ★★☆☆☆ 任意并发 state 显示错乱（非记忆串台）

用户描述的"B突然去查南京天气"最可能是根因1 ——因为 system prompt 明确引导 LLM 在遇到困难时用 session_search 回忆历史，而 SQL 会返回并发兄弟会话的"南京天气"内容。

## 三、修复方案（按优先级排序）
### 方案1：修复 SessionSearchTool（最优先，直接命中症状）
改动点 A — SessionSearchTool 增加 ToolContext 参数，强制读取真实 conversationId：

SessionSearchTool.java:37-44

改动点 B — SessionSearchService 增加运行状态过滤，排除并发兄弟会话：

SessionSearchService.java:60-73 SQL 增加：

或更保守：只返回 status = 'completed' 的会话，排除 running / awaiting_approval 的并发会话。

风险评估： 改动 SQL 查询条件，不影响写入逻辑。 completed 会话才是真正的"历史对话"， running 会话是"正在进行"不应被搜索。功能上合理。

### 方案2：修复审批重放跨会话取计划（确凿 bug，必须修）
改动点 A — PlanningService.findAwaitingApprovalContext 增加 conversationId 参数：

PlanningService.java:228-232

改动点 B — 调用方传入 conversationId：

StateGraphPlanExecuteAgent.java:100

风险评估： 需确认 PlanEntity 有 conversationId 字段（从之前排查看应存在）。改动最小，仅加查询过滤，不影响其他逻辑。

### 方案3：结构化记忆引入会话级隔离（改动较大，需评估）
问题： 当前 ownerKey = user:<requesterId> ，3 会话共享。如果改为 conversation:<conversationId> ，会破坏"用户长期记忆跨会话共享"的设计意图（用户画像、偏好等应跨会话）。

建议方案： 不改 ownerKey 机制，而是在 StructuredMemoryTool.remember_structured 的 system prompt 说明中 明确限制 只记住"长期有效的事实"，临时任务结果（如天气查询）不应写入。或在 type 枚举中新增 transient 类型，该类型按 conversationId 隔离，会话结束自动清除。

风险评估： 改动较大，涉及记忆分层设计。建议作为中长期优化，本次先修方案1和2。

### 方案4：Agent 实例 state 按 conversationId 隔离（可选）
改动点： BaseAgent.java:33 AtomicReference<AgentState> state 改为 Map<String, AtomicReference<AgentState>> （按 conversationId）。

风险评估： 影响所有 getState() / setState() 调用点，改动面广。且这只是状态显示问题，不影响记忆串台。建议暂不修，或在前端按 conversationId 单独查询状态。

--------------------------------------------
本次完成bug1、2修复；3、4未动
 2026-06-30 09:23:26 +08:00
倪程伟
7be8f81353
feat(agent): per-employee model-chain preference (provider + model, repeatable provider) 
Lets an employee pin an ordered fallback chain of (provider, model) entries; the same provider may appear multiple times with different models. Build-time dedup keys on exact (provider, model).
 2026-06-28 13:05:48 +08:00
matevip
26dd8a37d5 fix(workspace): harden chat-upload base-path containment + cleanup guard 
- resolveAgentBasePath: the relative-override branch now normalizes the
  resolved path and rejects values that escape the workspace root via "../"
  (the absolute branch already did this), keeping attachment/media/tool I/O
  contained when an agent's workspaceBasePath is a relative override.
- cleanAttachmentFiles: return early on a null/blank conversationId so a bare
  upload root can never be walked and deleted wholesale.
- Translate the chat-upload Javadoc/comments to English (cleanAttachmentFiles,
  BaseAgent image-path resolver) per code style.
- Add a resolver test for the relative-override escape fallback.
 2026-06-26 14:25:56 +08:00
倪程伟
fcb488c567
feat(workspace): chat-uploads 上传目录工作空间/Agent 感知化 (#422) 
* feat(workspace): chat-uploads 上传目录工作空间/Agent 感知化 (#421)

把硬编码的 data/chat-uploads/{conversationId}/ 改为按工作空间/Agent 解析，
解析优先级：Agent workspaceBasePath → Workspace basePath → 可配置默认目录
（新配置 mateclaw.chat.upload.base-dir，默认 data/chat-uploads，保持现网零行为变化）。

- 新增 ChatUploadLocationResolver 中央解析器：写路径返回唯一根，读/清理
  路径返回候选根列表（工作空间根 + 默认根）做双重查找，保证迁移前旧附件
  仍可解析/清理；conversationId→ConversationEntity 查询带 5min 缓存。
- 新增 ChatUploadProperties + ChatUploadAutoConfiguration（启动建目录）。
- 复用 AgentGraphBuilder.resolveAgentBasePath（提升为 public）的优先级与
  安全规则（相对路径在 workspace 根下解析，绝对路径逃逸被拒）。
- 所有写入/读取点改为走 resolver；读取点走双重查找。
- 解决 Spring 循环依赖（resolver → agentService → ... → conversationService
  → resolver）：resolver 的 AgentService 注入加 @Lazy。

向后兼容：默认目录不变；双重查找覆盖历史消息里的相对路径；
服务端点 URL 契约不变，前端无需改动。

测试：新增 ChatUploadLocationResolverTest（8 用例）；修复受影响的现有测试构造。

* refactor(workspace): address review findings on chat-uploads resolver (#421)

应用 code review 的 4 项修复：

1. (correctness) ChatUploadLocationResolver 缓存新增 ConversationDeletedEvent
   监听器，删除会话时立即失效 conversationId→ConversationEntity 映射。
   否则备份恢复后用相同 id 重建会话，会继承最长 5 分钟的过期 workspace/agent
   映射，导致 cleanAttachmentFiles 走错（过期的）上传目录。复用既有
   @EventListener-on-bean 模式（与 AsyncTaskService / WorkspaceLookupCache 一致）。

2. 收紧 resolveWorkspaceScopedRoot 里 3 个过宽的 catch(Exception) →
   MateClawException + warn，让真正的 bug（NPE / DataAccessException）暴露
   而非被静默降级为 debug 日志。

3. 更新 ChatController.upload 过期注释：会话尚未创建时附件暂存默认目录，
   会话创建后读取走双重查找仍能命中。

4. 移除不可达分支（agentWorkspaceId != workspaceId）—— 会话的 agent 必然
   归属会话的 workspace（创建时强约束），直接用会话 workspace 即可，
   少一次冗余 DB 查询与一层推测性逻辑。

测试：ChatUploadLocationResolverTest (8) + ConversationServiceCleanAttachmentFilesTest (2) 全绿。
 2026-06-26 14:20:54 +08:00
matevip
eca4229751 feat(plans): per-step agent delegation + fix kanban pending column (issue #385) 2026-06-21 21:20:58 +08:00
matevip
1affbd7b82 feat(agent): loop-engineering robustness — goal continuation, plan re-plan, stall detection 
- goal: continue (not skip) on max-iterations and evidence-insufficient turns.
  A max-iterations turn grants a fresh iteration budget ("hard continuation"),
  bounded per run and sized into the graph recursion ceiling, so a task too big
  for one budget keeps going instead of stalling until the next user message.
- plan-execute: re-plan the remaining work on a step exception, and on a
  signature-based stall (repeated failures / identical results / no usable
  result) instead of advancing dependent steps with junk; bounded by a per-run
  re-plan cap, with a graduated change-strategy nudge before the hard stop.
- plan-execute: auto-derive a goal from a genuine multi-step plan, seeding the
  acceptance criteria from the plan steps, so the goal subsystem engages without
  the model calling setGoal; broadcast goal_created so the UI hydrates.
- react: refund the iteration for setup-only rounds (load_skill / enable_tool)
  so a tight budget is not eaten by the load-then-use two-step.
- ui: re-fetch the active goal when a turn finishes so a goal created or mutated
  mid-conversation surfaces without depending on an SSE event.
- streaming: make retry backoff / total-time budget instance fields with a
  test-only seam; clarify that the wall-clock budget (not max-retries) bounds a
  sustained SERVER_ERROR loop to ~8 attempts, fixing the slow/flaky retry test.
 2026-06-17 06:37:08 +08:00
倪程伟
cd3ae0c001 feat(agent): append static About You identity block to system prompt 2026-06-08 20:53:39 +08:00
matevip
46f3d425e0 feat(agent): add kill-switch for final-answer Markdown normalization 
Gate MarkdownNormalizer behind mate.agent.markdown-normalize-enabled (default
true) so operators can disable the rewrite verbatim if a normalization edge
case ever mangles a legitimate answer.
 2026-06-07 19:15:14 +08:00
倪程伟
5746bcf8cc
feat(agent): 偏好提供商作为主模型选择依据 (#223) 
偏好提供商从「仅 capability 触发」改为两轮筛选，使 Agent 偏好提供商能决定主模型选择；并在 Agent 显式配置 modelName 时优先 honour，不被偏好提供商覆盖。

Closes #222
 2026-06-03 23:33:14 +08:00
matevip
7e9f2ee54c fix(memory): prefer recalled personal memory over knowledge base for user/project questions 2026-05-29 18:03:13 +08:00
matevip
b7e923fac4 feat(approval): grant-based auto-approve with safety floor and resolution log 2026-05-27 14:07:39 +08:00
matevip
c8b25e1bfb fix(agent): deny skill-discovery tools when skillsDisabled (#184 follow-up) 2026-05-26 22:16:51 +08:00
matevip
3ae4498f38 fix(channel,agent,chat): unify channel binding / conversation agent / model pin state sources 2026-05-26 09:40:49 +08:00
matevip
a37074a9a6 fix(tool): close three sandbox follow-up gaps surfaced by review 
1. Relative parent traversal in shell commands (HIGH)

   validateShellCommand only scanned absolute path tokens, so commands
   like `cat ../mateclaw/CLAUDE.md`, `cd .. && cat foo`, or
   `ln -sf ../bar breakout` had no absolute path to trip the check.
   From a workspace cwd that's a real escape — `..` segments resolve
   against the JVM cwd at file-tool time and reach anywhere the user
   can read.

   Add a second pass: any token containing `..` as a path segment is
   resolved against the workspace root via root.resolve(token).
   normalize(); reject when the result falls outside. In-workspace
   traversal like `subdir/../sibling` normalizes back inside and
   passes. Identifiers without slashes (e.g. version strings with
   `1.2..3`) are not treated as paths.

2. Shell validation and process working directory used different
   context sources (MEDIUM)

   execute_shell_command validated with the explicit ToolContext, but
   buildShellProcess called WorkspacePathGuard.getWorkingDirectory()
   (no-arg), which only sees the ThreadLocal fallback. Today the
   ToolExecutionExecutor sets both so the discrepancy is latent, but
   a future direct Spring AI invocation passing only ToolContext would
   validate against one basePath and exec against another. Thread ctx
   through buildShellProcess and call getWorkingDirectory(ctx) so
   validation and execution agree on a single source of truth.

3. Absolute agent override could disable workspace scoping (MEDIUM)

   resolveAgentBasePath accepted an absolute override verbatim, even
   when it pointed outside the workspace root. An admin (or any
   account with agent-edit permission) could set workspaceBasePath="/"
   or another team's repo and bypass workspace boundaries entirely.

   When a workspace has its own basePath, require absolute overrides
   to sit underneath it. The caller in build() catches the rejection,
   logs WARN, and falls back to the workspace basePath so chat stays
   available rather than crashing agent construction. When the
   workspace has no basePath there's no boundary to enforce, so legacy
   behavior is preserved.

Test coverage: WorkspacePathGuardShellTest grows from 17 to 23 (six
new cases for `cd ..`, relative parent traversal, relative symlink
escape, deeper traversal, in-workspace normalization, and the
identifier false-positive guard). AgentGraphBuilderBasePathResolutionTest
grows from 7 to 10 (three new cases for in-workspace absolute,
outside-workspace absolute rejection, and no-workspace legacy
behavior). All 45 sandbox-area tests pass with no regressions.
 2026-05-25 17:55:56 +08:00
matevip
9e9a96f674 fix(agent): resolve relative workspaceBasePath under workspace root 2026-05-25 15:58:05 +08:00
倪程伟
cbdd70379b
feat(agent): optional agent-level workspace basePath override (#212) 
* feat(agent): optional agent-level workspace basePath override

Add workspaceBasePath field to AgentEntity that optionally overrides
the workspace-level basePath. When set, the agent uses its own directory;
when null, it inherits the workspace's basePath (existing behavior).

- AgentEntity: new workspaceBasePath field with ALWAYS update strategy
- AgentGraphBuilder: agent-level override takes priority over workspace
- Flyway migration V121 for H2 and MySQL
- UI: form input in basic tab with i18n (zh-CN, en-US)

* fix(agent): rename migration V121→V125 to avoid Flyway conflict with upstream

Upstream already has V121__tool_disclosure_tier.sql. Rename our
migration to V125 (next available after V124).

* fix(agent): make MySQL V125 migration idempotent

Use INFORMATION_SCHEMA check before ADD COLUMN to avoid
"Duplicate column name" error on re-deploy.
 2026-05-25 15:42:01 +08:00
matevip
7f45b95432 feat(agent): include progress-ledger snapshot in limit-exceeded wrap-up 2026-05-24 23:00:49 +08:00
matevip
05289e6bdb feat(agent): per-conversation progress ledger to survive context trims 2026-05-24 23:00:03 +08:00
matevip
a9c2d45790 Harden goal approval and workspace flows 2026-05-23 22:55:16 +08:00
matevip
cef1730e6e feat(tool,skill,ui): progressive tool/skill disclosure (load_skill + enable_tool + tier UI) 2026-05-23 09:07:45 +08:00
matevip
9e93c52d9a fix(goal): real evaluator, retry refactor, hardened node + extra edges 2026-05-21 22:27:00 +08:00
matevip
ce74a0ae48 feat(goal): graph topology + evaluation node wired into ReAct + Plan-Execute 2026-05-21 14:43:13 +08:00
matevip
d53d66abe3 feat(chat): per-conversation model selection (#150) 2026-05-18 16:27:27 +08:00
matevip
75107ac815 feat(llm): native Gemini chat builder, Nano Banana image gen, xAI/Grok provider 2026-05-18 10:00:55 +08:00
matevip
a88edbdd07 refactor(llm): decouple model construction from the agent graph layer (#147) 2026-05-18 07:47:49 +08:00
matevip
3b9b4d79d5 feat(skill): scope skill catalog and runtime by workspace (#135) 2026-05-15 20:01:25 +08:00
matevip
f0f97232a8 fix(agent): pre-tool no-claim system rule + correct write/edit approval docs 2026-05-14 14:59:32 +08:00
matevip
9fd5843dda fix(llm): pin OpenAI-compatible HTTP client to HTTP/1.1 (#89) 2026-05-11 11:22:23 +08:00
matevip
00098fe5f1 feat(agent,channel): scrub fake generated-file URLs + paste-body hint for public-account articles 2026-05-10 19:15:44 +08:00
matevip
c2aecf18ef feat(agent,llm): multimodal sidecar routing for unsupported attachments (#87) 2026-05-09 16:41:26 +08:00
matevip
80cb3c84eb fix(agent): decouple framework recursion limit from per-agent max_iterations 2026-05-05 13:06:40 +08:00
matevip
be1fc86836 feat(agents): pixelart icons, per-role colors, runtime identity merge, locale templates 2026-05-04 15:26:02 +08:00
matevip
42d406ffc8 fix(agent): drop brittle output policing, add evidence-grounded long-task safeguards 2026-05-04 11:55:44 +08:00
matevip
3d50b9c132 feat(skill): catalog sort + usage stats 2026-05-04 11:55:35 +08:00
matevip
66f09a968a feat(chat-stream): streaming UX overhaul + multi-agent stability layer 2026-05-03 17:15:02 +08:00
matevip
bc417d00ef chore: neutralize internal references in code comments and migrations 2026-05-02 15:42:10 +08:00