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

300 Commits

Author SHA1 Message Date
matevip
071fff76ab fix(agent): enforce tool-backed action completion 2026-08-11 05:31:44 -04:00
倪程伟
ddb6a837ea
fix(llm): add stream body idle timeout 
Apply a Reactor inter-frame idle timeout at the streaming chat chokepoint so half-open provider body streams surface through the normal retry/failover path. Also keep the HTTP timeout documentation accurate and cover the behavior with focused tests.
 2026-08-11 03:38:46 -04:00
matevip
ce7f0847fb fix(agent): preserve tool use after compaction 2026-08-10 05:39:08 -04:00
mateaix
8dc6c64683 perf(agent): add progressive tool bridge 2026-08-09 19:39:45 +08:00
mateaix
a204e8eec8 fix(self-evolution): harden lifecycle and plan loops 2026-08-09 18:13:24 +08:00
matevip
c72c8b48e4 fix(skill,agent): curation observation anchor, per-skill adoption, and empty plan-summary fallback 2026-08-07 05:12:33 -04:00
matevip
99c18b968a fix(chat): persist planning reasoning, dedupe the plan summary, normalize metadata reads 2026-08-06 07:09:32 -04:00
matevip
ed7f6f5c19 feat(chat): add reasoning retention controls and a linear trajectory export 2026-08-06 05:48:28 -04:00
matevip
22c49f3a07 fix(chat): keep every iteration reasoning and render the timeline in emission order 2026-08-06 05:13:09 -04:00
matevip
30560eb7cf fix(chat): classify pre-tool narration by observation count, not iteration budget 2026-08-06 02:39:03 -04:00
matevip
e22173a476 feat(skill): close the self-evolution loop — auto-bind, routine mining, curation provenance and restore points 2026-08-06 01:51:22 -04:00
matevip
fefb3b25b8 feat(chat): live pre-tool narration collapse via segment_kind SSE event 2026-08-04 22:51:12 -04:00
matevip
547adb30ee feat(agent): producer-assigned content-kind tag on stream deltas 2026-08-04 22:49:34 -04:00
matevip
77dd866243 feat(agent): stale-status guard appended to every reasoning system prompt 2026-08-04 03:47:05 -04:00
matevip
046080d6aa feat: thinking display overhaul — live think-tag extraction, real durations, default visibility, reconnect and team-note fixes 2026-08-03 05:56:16 -04:00
matevip
91c9565f1f fix(agent): stop stale ledger entries from suppressing repeated status queries 2026-07-31 02:37:27 -04:00
matevip
fcf5f3960b fix(agent): stop lossy-truncating retrieval tool results that must arrive whole 
load_skill returns SKILL.md in full by design — it is the model's behavioral
contract, and pagination by default would let the model silently miss later
mandatory sections. read_file / readSkillFile / load_skill are therefore on
the spill-exclusion list so their output is never replaced by a disk pointer.

The exclusion only covered half the path. In spillRawOrTruncate, an excluded
tool's result came back from persistIfOversized unchanged (no spill), failed
the SPILL_MARKER_PREFIX check, and fell through to truncateToolResult(8000) —
so an 8261-char SKILL.md was hard-cut through the middle and stamped with a
'[TRUNCATED: ... middle omitted]' marker. Weaker models ignore the attached
fidelity note and fabricate the removed span, inventing tool calls against
endpoints the skill never described.

- spillRawOrTruncate now returns retrieval-excluded results raw; the per-turn
  aggregate budget stays the backstop.
- Outsized SKILL.md degrades to resumable pagination instead of an unbounded
  inline dump. Never a lossy middle-cut.
 2026-07-28 05:06:24 -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
matevip
49f7a74386 fix(approval): persist the real pendingId on guard audit rows 2026-07-23 11:46:22 +08:00
matevip
1bb81234d0 feat(approval): classify auto-approve misses and persist the outcome on guard audit rows 2026-07-23 11:44:21 +08:00
matevip
d999608b2c fix(agent): exclude skill readers from tool-result spill so SKILL.md reaches the model intact 2026-07-22 17:48:45 +08:00
matevip
3781275e59 feat(llm): smarter failover — overload-aware retries, provider retry windows, provider pool auto-recovery 2026-07-22 11:12:47 +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
matevip
e6c35ecfc7 fix(channel): sanitize conversationId as a filesystem path segment — fixes wecom/dingtalk/feishu attachment upload on Windows (#507) 2026-07-10 16:54:05 +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
matevip
6802fc1c6a feat(chat): context occupancy panel with per-source breakdown (#492) 2026-07-06 16:44:59 +08:00
matevip
15f134a35e docs(agent): fix stale ledger-guard comment and translate ActionNode javadoc 
- ProgressLedgerService.upsert: the reserved-prefix guard rejects the write; the
  comment said 'strip the prefix and continue', which no longer matches. Rewrite
  it to describe the actual reject behavior.
- ActionNode: translate the class javadoc (including the B2 pinned-constraints and
  B5 auto-backfill notes) to English per code style.
 2026-07-06 11:53:00 +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
727adcd24b feat(agent): 压缩清理占位符信息化——保留工具名/原始大小/首行要点,便于模型判断是否需要重跑 2026-07-03 18:53:27 +08:00
matevip
36d1f1027d feat(agent): 小上下文降级档——紧凑/底线档收紧注入、压缩触发比自适应、prefix 分块统计与预超限快速失败 2026-07-03 18:53:05 +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
bb946685b3 fix(chat): render generated-file download links with the file name, not the raw id URL (#466) 2026-07-03 14:34:35 +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
倪程伟
a1221ac02d feat(mcp): type on-behalf-of identity by channel/trust (#459) 
The identity forwarded to opt-in MCP servers was a one-dimensional string
(ChatOrigin.requesterId): a MateClaw username for web logins, but a webchat
visitorId for visitors and an IM sender id for IM — indistinguishable to the
REST backend. The signed-token mode (d204b702) made this worse: an RS256
signature over an unauthenticated visitorId reads as "MateClaw authenticated
this user" to any backend that trusts the signature.

Introduce an identity-typing dimension at McpIdentityForwardService:

- classify() branches on ChatOrigin: authenticated (web login, sub=immutable
  userId), anonymous (webchat visitor, trust=anonymous), external (IM sender,
  trust=external), or none (cron/system → nothing injected, fail-closed).
- mint() adds `trust` and `channel_type` claims; plaintext value is prefixed
  `trust:subject` so backends can tell the kinds apart without a JWT.

The immutable userId reaches resolve() without coupling it to the user store:
JwtAuthFilter stamps user.id into auth.setDetails() (both JWT and PAT paths),
and ChatController.memoryOrigin carries it on a new ChatOrigin.requesterUserId
field (only-add, per the record's evolution rule).

Resolves the webchat semantic mismatch raised in #459 and the "sub should be
an immutable user id" follow-up. 82 tests green (4 identity classes covered
with claim assertions + full ChatOrigin/MCP regression).

(cherry picked from commit b5d2cfbf98b39848d7139c743a0b81fea71e8ffe)
 2026-07-01 19:02:49 +08:00
matevip
fa4e7018a0 feat(delegation): 本轮 token 总量页脚 + 子 Agent 用量向上滚加 
- 新增 DelegatedUsageAccumulator：按根会话累加每个完成子 Agent 用量，根 Agent
  在 _usage_final 处一次性 drain 整棵子树、中间层得 0，每个子只计一次、无重复计数
- runSingleChild 增 accumulateToParent：同步/并行/计划步骤委派计入父轮，游离异步不计
- ReAct / Plan-Execute 在 _usage_final 处 drain 并加进 token + 附委派分解字段，
  doFinally 清理防泄漏；该事件同时驱动实时 SSE 与 mate_message 落库，实时/刷新一致
- 前端消息底部新增 Σ<total> tok 徽标（tooltip 含委派分解），总量仅取 message 用量
- 测试：补 DelegatedUsageAccumulator 接线，委派全套 59 绿
 2026-06-30 17:21:10 +08:00
matevip
d390935763 feat(delegation): 子 Agent 成本透出 + 单任务/计划步骤委派结构化 
- 子执行改走 chatWithUsage，捕获并透出每个子 Agent 的 prompt/completion token
  （单任务回复、并行机读头+逐行、delegation_end/child_complete/单路 broadcastEnd 事件）
- 新增 delegateByAgentIdStructured 返回结构化 ChildResult；计划步骤委派改按
  success()/isBlank() 判定成败，替掉脆弱的错误前缀匹配
- 前端委派段与嵌套节点显示紧凑成本后缀/徽标
- 测试：子执行 stub 迁移到 chatWithUsage + 新增 token 回归用例
 2026-06-30 11:06:19 +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
matevip
181e81a236 fix(mcp): cascade-delete agent-tool bindings when an MCP server is removed 2026-06-29 15:03:09 +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
7705778903 fix(agent): normalize replayed tool-call arguments to valid JSON (#410) 
Strict OpenAI-compatible providers reject the /chat/completions request
with HTTP 400 when an assistant message in history carries a tool call
whose function.arguments is not parseable JSON. Normalize blank or
non-JSON arguments to "{}" at the send chokepoint so streaming,
history-replay, and older-persisted tool calls all stay well-formed.
 2026-06-26 11:19:19 +08:00
matevip
14ee45a30d feat(agent): introduce SubagentRunContext value object for delegation runtime identity 2026-06-23 18:21:59 +08:00