20260514:增加新内容

concepts/stub-pattern.md

@@ -0,0 +1,35 @@
+---
+title: "Stub Pattern（轻量化桩模式）"
+created: 2026-05-11
+updated: 2026-05-11
+type: concept
+tags: [agent-architecture, tool-design, caching-optimization]
+sources: [[prompt-caching-architecture]]
+---
+
+# Stub Pattern（轻量化桩模式）
+
+## 定义
+
+Stub Pattern 是一种解决 [[prompt-caching|Prompt Caching]] 中工具定义变更导致缓存失效的架构模式。在 System Prompt 中预先定义所有潜在工具的**轻量占位符**（Stubs），仅包含工具名称和最小化接口描述，运行时通过 [[tool-registry|ToolRegistry]] 统一接口间接调用。
+
+## 问题
+
+"按需加载工具"——根据任务动态添加或移除 System Prompt 中的工具定义——是缓存性能的"毒药"。每次工具定义变更都导致整个缓存前缀失效。
+
+## 解决方案
+
+1. System Prompt 中固定所有工具的 Stub：`fetch_factor_data(ticker, time_range)`
+2. 模型不直接调用 Stub，而是调用 `ToolRegistry.invoke(tool_id, params)`
+3. ToolRegistry 后台负责动态加载和执行具体逻辑
+4. 前缀序列始终保持稳定 → [[cache-hit-ratio|缓存命中率]] 维持在 99%+
+
+## 附加收益
+
+降低 Agent 面对复杂任务时的决策压力（无需在大量工具中动态选择）。
+
+## 相关概念
+
+- [[tool-registry|ToolRegistry]]
+- [[prompt-caching|Prompt Caching]]
+- [[cache-hit-ratio|缓存命中率]]