Skill-driven Pre-filtering for Optimal Tooling
解决"Agent 工具过多导致 Token 浪费"的通用问题。 平台无关，可适配任何支持 function calling 的 Agent 框架。
⚠️ 独立社区项目，与任何 Agent 平台无官方关联。文中提及的具体平台名称仅用于适配指南的案例说明。
当 Agent 平台注册了 50-200+ 个工具时，每轮 API 请求会将全部工具的 JSON Schema 注入上下文。但模型每轮实际只调用其中 1-5 个。
74 个工具 × ~650 chars/工具 = ~48K chars/轮（纯 Schema 开销）
50 轮对话 = ~2,400K chars（其中 90%+ 是浪费）
核心矛盾：模型每轮都看到全部工具，但只用到不到 15%。
SPOT 在 API 调用之前，根据当前激活的 Skill（技能）和用户意图，将工具集从 N 个裁剪为 Top-K 个（通常 10-25 个）。主模型完全无感知，调用模式不变。
用户消息
│
▼
Skill 路由（已有组件）→ 命中 Skill（0-5 个）
│
▼
┌─────────────────────────────────────────┐
│ SPOT Filter（预筛选层） │
│ │
│ ① Skill 声明的 required tools → 强制纳入 │
│ ② 用户意图 → 语义匹配 → 补充 Top-K │
│ ③ Conditional tools → 注入提示语 │
│ ④ 故障 → 静默回退全量 │
└─────────────────────────────────────────┘
│
▼
主模型 API 调用（只看到 Top-K 工具）
│
├── 正常路径（95%+）：直接调用
└── 兜底路径（<5%）：mcp_fallback → 二次筛选
核心原则：筛选层只做确定性高的事，不确定性留给主模型。筛选层的价值不在于"替模型做决策"，而在于"缩小模型的决策空间"。
以 N=74 为例（实际节省率与工具总数成正比）
| 场景 | 工具数 | Schema 开销 | 节省率 |
|---|---|---|---|
| 全量打包（现状） | 74 | ~48K/轮 | — |
| SPOT（0 技能激活） | 17 | ~11K/轮 | 77% |
| SPOT（1 技能激活） | 19 | ~12K/轮 | 74% |
| SPOT（5 技能全激活，最坏） | 53 | ~34K/轮 | 29% |
实测数据（OpenSquilla 平台，88 工具 → 54 可见，34 工具 deny）：
| 指标 | 全量打包 | SPOT-E 静态裁剪 | 节省 |
|---|---|---|---|
| 工具 Schema | 48,861 chars | 34,188 chars | -30% |
| 可见工具 | 74 | 48 | -26 |
- 零额外 API 往返（筛选在本地完成）
- 主模型调用模式完全不变
- 任何故障静默回退全量，不影响可用性
阅读 knowledge/ 目录下的现有文件：
| 文件 | 内容 |
|---|---|
red-lines.md |
6 条红线经验教训（含来源事件） |
acceptance-checklist.md |
5 类验收清单 |
spot-tool-registry.yaml |
工具分类模板（待建） |
spot-description-norm.md |
工具描述规范（待建） |
spot-tool-descriptions.json |
描述映射表（待建） |
更多方法论文档（三级分类法、动态 K 值策略、兜底策略等）将在后续版本补充。请关注 Release 更新。
模板目录
templates/为规划中，待社区贡献。以下为目录结构示意：
# 复制模板到你的项目（目录就绪后执行）
cp templates/tool-registry.yaml your-project/
cp templates/skill-frontmatter.yaml your-project/skills/
cp templates/config-template.yaml your-project/ # YAML 格式
cp templates/config-template.toml your-project/ # 或 TOML 格式
cp templates/config-template.json your-project/ # 或 JSON 格式按模板中的注释填写你的工具清单和技能声明。配置文件提供三种格式，选你平台兼容的即可。
参考实现目录
examples/为规划中，待社区贡献。以下为 API 设计示意：
# 示例代码（目录就绪后可用）
# from examples.spot_filter import spot_filter_with_fallback
# 每轮 API 调用前
top_k_tools, conditional_hints = spot_filter_with_fallback(
user_message="帮我审查这段代码的安全性",
active_skills=[code_review_skill],
tool_registry=all_74_tools,
K=13, # 10 + 1×3
)
# 只将 top_k_tools 的 Schema 注入 API 请求
response = call_llm_api(messages, tools=top_k_tools)阅读 adapters/ 中对应你平台的适配指南。
在 Agent 框架内部实现预筛选层。需要修改框架的 engine/runtime/dispatch 层。
- 适用：你是框架开发者，或框架支持插件/中间件机制
- 效果：动态预筛选，每轮按意图选不同 Top-K
- 详见：
docs/architecture.md（规划中，待社区贡献）
通过平台原生的工具裁剪机制（deny/禁用）+ 路由技能实现静态裁剪。
- 适用：你无法修改框架源码，但能修改配置和技能
- 效果：静态裁剪，按类别 deny 低频工具
- 详见：
docs/spot-e-externalized.md（规划中，待社区贡献）
SPOT-E 是 SPOT 的"阶段零"——它的所有数据产物（工具注册表、描述数据库、分类清单）在升级到 SPOT 原版时可以直接复用，零浪费。
| 原则 | 实现方式 |
|---|---|
| 透明性 | 主模型不知道筛选层的存在，调用模式不变 |
| 可降级 | 筛选层任何故障 → 静默回退全量打包 |
| 轻状态 | 核心计算无状态；追加工具列表为会话级辅助状态 |
| 边界清晰 | 确定性（required + 语义匹配）归筛选层；不确定性（conditional when）归主模型 |
| 零额外往返 | 筛选在 API 调用之前完成，不引入新的 API 往返 |
spot-framework/
├── knowledge/ 知识层（方法论、规范、红线、验收清单）✅
├── adapters/ 平台适配指南 + 案例实录 ✅
├── docs/ 架构方法论（规划中，待社区贡献）
├── methodology/ 核心方法论 6 份（规划中，待社区贡献）
├── templates/ 通用模板（规划中，待社区贡献）
└── examples/ Python 参考实现（规划中，待社区贡献）
SPOT 已在两个不同架构的 Agent 平台上验证了跨平台通用性：
| 维度 | OpenSquilla | Hermes |
|---|---|---|
| 平台类型 | 桌面应用，Python 运行时 | 技能驱动，MCP 协议 + 原生函数 |
| 工具数 | 88 | 96（清理后） |
| 裁剪方式 | [tools] deny 配置列表 |
关闭 MCP Server / 删技能文件 |
| 路由方式 | spot-router 技能（SKILL.md） | 技能文件清理 |
| 代理服务 | 不需要（deny 工具无使用需求） | 不需要（MCP 按需加载） |
| 执行层工作量 | 34 行 TOML | 删几个文件 |
| 实测节省 | 30% 工具 Schema | ~25%（技能列表压缩） |
两个案例展示了 SPOT 的适应性：无论平台是 Python 原生的 function calling 还是 MCP 协议 + 原生函数，方法论统一，实现方式因地制宜。
| 工具数量 | 推荐方案 |
|---|---|
| < 50 | 全量打包即可，无需 SPOT |
| 50 - 200 | SPOT / SPOT-E（本项目的核心适用区间） |
| > 200 | SPOT 演进为 MCP Router（语义路由 + 连接池） |
SPOT 架构经过四轮多方交锋迭代：
| 轮次 | 焦点 | 产出 |
|---|---|---|
| 第一轮 | 三方案 Token 对比（全量 / Meta-MCP / 预筛选） | 确定预筛选在 50-200 工具规模下最优 |
| 第二轮 | Skill 融合 | 引入 frontmatter.tools.required 硬约束 |
| 第三轮 | 条件工具的运行时触发 | 确定条件判断归主模型，筛选层只注入提示 |
| 第四轮 | 工程治理 | 确定漂移检测、降级策略、落地路线图 |
完整设计决策记录见 docs/design-decisions.md（规划中，待社区贡献）。
- 方法论改进、模板优化、参考实现 bug 修复：欢迎 PR
- 新平台适配指南：欢迎 PR 到
adapters/目录 - 讨论：请开 Issue
- 代码（
examples/）：MIT - 文档（
docs/、methodology/、templates/、adapters/）：CC BY-SA 4.0
本项目为独立社区项目，与任何 Agent 平台无官方关联。 文中提及的平台名称仅用于适配指南的示例说明。