skill-context-manager

技能上下文管理器（SCM） > **面向 AI 代理的上下文感知技能选择 — 解决“技能过多”问题。** > > 减少技能上下文令牌 **85-98%**，提高技能选择准确性，并从反馈中学习。 [](https://www.python.org/) [](https://sqlites5.html) [](https://modelcontextprotocol.io) [ [![https://img.shields.io/badge/tests-186%2%9C%94%EF%B8%8F-brightgreen)]() --- ## 问题 | 问题 | 影响 | 根源 | |---------|--------|------------| | 用户安装 50-100+ 个技能 | 30K-60K 令牌消耗 | 静态工具注入无法扩展 | | 代理失去方向 | 准确率从 95% 下降到 **<50%** | “迷失在中间” + 元数据过载 | | 20 条忘记技能 | 每次回合重新读取所有内容 | 没有会话内存 | | 相似技能无法区分 | 无法选择使用哪个技能 | 关键词搜索不足 | | 选择错误的技能 | 浪费令牌和重试成本 | 没有反馈循环 | ### 研究引用 SkillRouter（Z人6 年）**.7% 的跨编码器注意力集中在 **技能主体**，只有 1.0% 集中在描述上 — 单纯依靠元数据是不够的。 ([arXiv:26022455](https.org/abs/26022455)) -thropic 工具搜索基于 BM25 的延迟加载，令牌减少 85%。 ([Engineeringhttps://www.anthropic.com/engineering/advanced-tool-use)) - **ropic 评估数据**（通过 Hermes Agent）： 4 准确率 ~49%（无工具搜索）；工具搜索恢复到 ~74%。 ## 解决方案 SCM 是技能目录之间的 ****。它所有技能到上下文中，而是执行： 1两阶段检索（ 架构）** — 检索 → 重新2. **会话内存** — 记录已使用的技能，并在相关时提升它们 3. **反馈循环** — 基于成功/失败数据的贝叶斯权重更新 4. **单个共享数据库** — 消除跨数据库错误 5. **优雅降级** — 在每个依赖级别上都有效 ### 令牌节省 | 场景 | 之前 | 之后 | 节省 | |----------|--------|-------|---------| | 加载 100 个技能元数据 | ~30K 令牌 | **~300 令牌** | **99%** | | 加载 50 个 MCP 工具 | ~72K 令牌 | **~8.7K 令牌** | **88%** | | 会话跟踪（50 条消息） | 技能被遗忘 | **100% 召回** | N/A | | 查询延迟（77 个技能） | — | **~7ms (BM25)** | 即时 | ## 安装 ### 要求 - **Python 3.11+** - **uv**（Astral）— 如果缺少则自动安装 ### 安装 **前提条件：** Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)（如果缺少则自动安装）。 三个安装级别 — 选择一个： ```bash # 级别 1：仅 BM25（快速，无 AI 依赖，在所有地方都有效） uv tool install git+https://github.com/Mavis2103/skill-context-manager # 级别 2：+ 嵌入式搜索，带 all-MiniLM-L6-v2（推荐） uv tool install 'git+https://github.com/Mavis2103/skill-context-manager[light]' # 级别 3：+ 完整重新排序器（跨编码器），以获得最佳准确性 uv tool install 'git+https://github.com/Mavis2103/skill-context-manager[full]' ``` > **注意：** 如果使用 zsh，请引用 URL（`'...'`)以防止 `[light]` 被解释为全局模式。 然后验证并设置： ```bash scm --version scm mcp setup --all # 为所有 13 个代理平台配置 MCP scm index # 自动检测技能目录 # 或指向特定目录： scm index --dir ~/.hermes/skills/ ``` ### 更新 ```bash # 从 GitHub 重新安装以获取最新版本（保留相同的额外：light/full，如果有） uv tool install --reinstall 'git+https://github.com/Mavis2103/skill-context-manager[light]' ``` ### 卸载 ```bash scm mcp setup --force-all --uninstall # 首先清理 MCP 配置 uv tool uninstall scm # 删除工具 + 虚拟环境 rm -rf ~/.scm # 删除数据库 ``` ### 开发安装（适用于贡献者） ```bash git clone https://github.com/Mavis2103/skill-context-manager.git cd skill-context-manager uv venv && source .venv/bin/activate uv pip install -e . # 级别 1：仅 BM25 # 或：uv pip install -e ".[light]" # 级别 2：+ 嵌入式（推荐） # 或：uv pip install -e ".[full]" # 级别 3：+ 重新排序器 ``` ## 功能 ### 0. 技能索引 索引您的技能文件，以便 SCM 可以搜索它们。**默认情况下是安全的** — 永远不会意外扫描噪声目录。 ```bash # 自动检测 — 查找此系统上安装的所有代理技能目录 # (~/.agents/skills/, ~/.hermes/skills/, ~/.claude/skills/, ...) scm index # 📂 扫描 ~/.hermes/skills/ 中的技能... 已索引 个技能文件 # 或指向任何目录 — 跳过 .git, node_modules, .venv, __pycache__, # dist, 所有隐藏目录等） scm index --dir ~/my-skills/ # 安全扫描整个主目录 — 仍然跳过相同的噪声目录 scm index --dir# 大型扫描时显示进度： # ... 已扫描 100/150 # ✅ 已索引 150 个技能文件 ``` ### 1. 语义技能检索 使用**混合 BM25 + 嵌入式**、零依赖项备用查找技能。 ```bash # BM25（FTS5）— 标准库，仅限，关键词快速精确 scm query "kubernetes deploy helm" --method bm# 嵌入式语义搜索 sentence-transformers） scm query "orchestrate container cluster management" --method embedding # 混合（默认）— 两者兼而有之 scm query "deploy app to production" --method hybrid ``` ### 2. 会话跟踪 记住在会话中使用过的技能 — 不再遗忘： ```bash scm session start --id "chat-abc-123" scm session use --skill k8s-deploy --query "deploy" scm session use --skill docker-build --query "build image" # 导出代理的上下文 — 仅 ~30 令牌 scm session context --id "chat-abc-123" # 输出： # { # "active_skills": ["k8s-deploy", "docker-build"], # "context_size_tokens": 42, # "matching_skills": [...] # } ``` ### 3. 反馈循环 — 自我学习 SCM 随着时间的推移而改进： # 记录反馈 scm feedback record --query "deploy app" --skill k8s-deploy --success true --rating 5 scm feedback record --query "deploy app" --skill helm --success false # 查看统计信息 scm feedback stats # 📊 反馈统计 # 总反馈： 47 # 成功率： 87% # 查询模式： 12 # 具有数据的技能： 8 # 按成功率排名的技能： #8s-deploy：15/16（94%） # • docker-build：8/10（80%） ``` ### 4. 元数据优化 压缩描述以节省令牌： ```bash # 预览 scm optimize --dir ~/.hermes/skills/ --dry-run # 📊 潜在节省： # 之前：1,847 元数据令牌 # 之后： 1,240 元数据令牌 # 节省： 607 令牌每负载（33%） # 应用 scm optimize --dir ~/.hermes/skills/ --no-dry-run ``` ### 5. 使用分析 ```bash scm insights # 📈 使用洞察（最近 30 天） # 总查询： 142 # 节省令牌： ~28,400 # 检索方法：bm25：89，hybrid：42，embedding：11 # 最常使用的技能： # • k8s-deploy：23 次 # • pytest-run：18 次 # • docker-build：15 次 scm stats # 📊 技能索引统计 # 总技能： 24 # 类别： 5 # 元数据令牌： 1,847 # 正文令牌： 12,430 ``` ## 架构 ``` 用户请求 │ ▼ ┌─────────────────────────────────────────────────┐ │ 1. 查询分析 │ │ - 提取关键术语 │ │ - 嵌入查询（如果启用嵌入式） │ └─┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ 2. 阶段 1：检索（前 20 名） │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ BM25 │ + │嵌入式 │ = │ 混合 │ │ │ │ （FTS5） │（余弦） │ │ （0.3+0.7）│ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ 3. 上下文注入 │ │ + 会话提升（最近使用 +0.5） │ │ + 反馈权重（贝叶斯先验） │ └─────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ 4. 2：重新排序（前 5 名） │ │ 跨编码器：查询 × 技能主体 │ │ "cross-encoder/ms-marco-MiniLM-L6-v2" │ │ CPU 上约 50ms（20 个候选者） │ └─────────────────────┬───────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ 5. 输出 │ │ - 前 5 个技能名称 + 描述（~300 t） │ │ - 会话上下文（~30 令牌） │ │ - 代理仅加载它需要的 1 个技能主体 │ └─────────────────────────────────────────────────┘ ``` ### 令牌流 ``` 无 SCM： 会话开始：加载 50 个技能元数据 = 50 × 60 令牌 = 3,000 令牌 代理选择 1，但50 个仍在上下文中 会话增长 → 代理忘记 → 重新加载所有：+3,000 令牌 总浪费：~6,000+ 令牌每会话 使用 SCM： 会话开始：仅活动技能 = 3 × 15 令牌 = 45 令牌 查询 → 前 5 个元数据 = 5 × 40 令牌200 令牌 会话跟踪器：~30 令牌 总计：~275 令牌每查询 节省-98% ``` ## MCP 服务器 SCM 作为 **MCP 服务器** 运行，带有 **11 种工具**，兼容 兼容的代理。 ### 多代理设置注册表 SCM v0.5.0 配备了 **一键设置功能，适用于 13 个代理平台**。无需手动配置每个代理的 MCP 设置，只需运行： ```bash # 为所有支持的代理配置（幂等） scm mcp setup --all # 或选择特定代理 scm mcp setup --claude-code --cursor --windsurf --es # 从所有代理中删除 SCM 配置 scm mcp setup --all --uninstall # 列出所有支持及其配置路径 mcp setup --list ``` **支持的平台：** | 代理 | 标志 | 配置路径 | |-------|------|-------------| | Claude Code | `--claude-code` | `~/.claude | | Claude 桌面版 | `--claude-desktop` | `~/.config/Claude_desktop_config.json` | | Cursor | `--cursor` | `~/.cursor/mcp.json` | | Windsurf | `--windsurf` | `codeium/windsurf/mcp_config.json` | | Cline | `--cline` | VS Code globalStorage/cline_mcp_settings.json | | Gemini CLI | `--gemini` | `~/.gemini/settings.json` | | VS Code（Copilot） | `--vscode` | VS Code User/mcp.json | | Zed | `--zed` | `~/.config/zed/settings.json` | | Codex CLI | `--codex` | `~/.codex/config.toml` | | Goose | `--goose` | `~/.config/goose/config.yaml` | | Continue.dev | `--continue` | `~/.continue/config.yaml` | | OpenCode | `--` | `~/.config/opencode/opencode.json` | | Hermes 代理 | `--hermes` | `~/.hermes/config.yaml` | 每个平台自动获取正确的配置格式： - **mcpServers`** — Claude Code, Desktop, Cursor, Windsurf, Cline, Gemini - **JSON `servers` (type: stdio)** — VS Code - **JSON `context_servers`** — Zed - **JSON `mcp` (type: local)** — OpenCode - **YAML `mcp_servers`** — Hermes - **YAML `extensions`** — Goose - **YAML `mcpServers` (list)** — Continue.dev - **TOML `[mcp_servers.scm]`** — Codex CLI ### 验证配置 ```bash # 检查哪些代理已配置 SCM scm mcp status # 输出（示例）： # SCM MCP 状态 # ✅ Claude Code: 已配置 # ✅ Cursor: 已配置 # ○ Windsurf: 配置存在，但未配置 # · Zed: 未找到配置 ``` ### 快速入门 ```bash # 为所有代理自动配置（幂等） scm mcp setup --all # 检查配置状态 scm mcp status # 在 stdio 模式下启动服务器（默认） python3 -m scm.mcp_server # 在 HTTP/SSE 模式下启动服务器 python3 -m scm.mcp_server --http --port 8321 ``` ### 可用工具 | 工具 | 层 | 描述 | |------|-------|-------------| | `skill_query` | 检索 | 查找最相关的技能以完成任务 | | `skill_index` | 索引 | 获取数据库统计信息 | | `skill_session_start` | 会话 | 开始跟踪会话 | | `skill_session_use` | 会话 | 记录技能使用情况 | | `skill_session_context` | 会话 | 导出会话上下文（~30 令牌） | | `skill_session_end` | 会话 | 结束会话 | | `skill_optimize` | 优化 | 压缩元数据以节省令牌 | | `skill_feedback` | 反馈 | 记录使用反馈 | | `skill_feedback_stats` | 反馈 | 查看反馈统计信息 | | `skill_insights` | 分析 | 使用分析仪表盘 | ``` ### 每个代理的配置格式（参考） 每个代理都使用独特的配置格式。`scm mcp setup` 命令会自动处理所有 13 个平台 — 这些示例说明了正在使用的各种格式： **Hermes 代理** (`~/.hermes/config.yaml`)： ```yml mcp_servers: scm: command: python3 args: ["-m", "scm.mcp_server"] allowed_tools: - skill_query -_start - skill_session_use - skill_session_context - skill_session_end - skill_feedback - skill_feedback_stats - skill_stats - skill_insights ``` 测试连接： ```bash hermes mcp test scm # ✓ 已连接（738ms） # ✓ 已发现工具：11 ``` 之后，Hermes 代理自动发现并可以调用 MCP 工具。 **OpenCode** (`~/.config/opencode/opencode.json`)： ```jsonc { "mcp": { "scm": { "type": "local", "command": ["python3", "-m", "scm.mcp_server"], "enabled": true } } } ``` **Claude Code** (`~/.claude.json`)： ```json { "mcpServers": { "scm": { "command": "python3", "args": ["-m", "scm.mcp_server"] } } } ``` **VS Code（Copilot）** (`~/.config/Code/User/mcp.json`)： ```json { "servers": { "scm": { "type": "stdio", "command": "python3", "args": ["-m", "scm.mcp_server"] } } } ``` **Codex CLI** (`~/.codex/config.toml`)： ```toml [mcp_servers.scm] command = "python3" args = ["-m", "scm.mcp_server"] ``` ### 远程模式（HTTP/SSE） ```bash # 启动服务器 python3 -m scm.mcp_server --http --port 8321 # { "mcpServers": { "scm": { url": "http://localhost:/sse" } } } ``` ### 代理技能模板（适用于 Hermes 代理技能） 创建 `/SKILL.md`： ```markdown --- name: skill-router description: 使用语义搜索选择并加载最相关的代理技能 --- 当需要为任务选择技能时，请使用： scm query "<user_task>" --top 3 --format json 然后加载排名最高的技能的 SKILL.md 正文。 ``` ## 优雅降级 | 依赖 | 可用功能 | |-------------|-------------------| | **轻量级 (`mcp` + `PyYAML`) | BM25（FTS5）+ 会话跟踪 + 反馈 + MCP 服务器 | | + `sentence-transformers` | 语义嵌入式搜索 | | + `transformers` + `torch` | 跨编码器重新排序 | | + 反馈数据 | 自我改进的贝叶斯权重 | 核心 **没有重型/ML 依赖项** — `mcp`（MCP SDK）和 `PyYAML`。检索在 Python 的 `` FTS5 上运行，因此 搜索，会话跟踪和无需任何 AI 模型。嵌入跨编码器模型完全可选 与替代方案比较 | 解决方案 | 渐进式发现 |义搜索 | 会话内存 |循环 | 令牌成本 | 轻量级核心 | |----------|---------------------|-----------------|----------------|---------------|------------|------------| | **Claude Code Skills** | ✅ 按需加载 | ❌ 关键词 | ❌ 否 | ❌ 否 | ~500 令牌 | ❌ | | **MCP 工具搜索** | ✅ 延迟加载 | ✅ BM25 | ❌ 否 | ❌ 否 | ~500 令牌 | ❌ | | **SkillRouter（arXiv）** | ❌ 一次全部 | ✅ 跨编码器 | ❌ 否 | ✅ 是 | 需要训练 | ❌ GPU | | **Hermes 技能** | ✅ 仅元数据 | ❌ 关键词 | ❌ 否 | ❌ 否 | ~3K 令牌 | ✅ | | **Lunar MCPX** | ✅ 工具组 | ✅ 自定义 | ❌ 否 | ❌ 否 | ~8.7K 令牌 | ❌ | | **✨ SCM）** | ✅ 仅元数据 | ✅ BM25 + 嵌入式 + 跨编码器 | ✅ 完整会话跟踪 | ✅ 贝叶斯 | **~275 令牌** | ✅ | ## 项目结构 ``` skill-context-manager/ ├── src/scm/ │ ├── __init__.py # 版本 + 模式初始化 │ ├── cli.py # 命令行接口（argparse，9个子命令） │ ├── db.py # 共享数据库连接（单个数据库，WAL） │ ├── indexer.py # 技能索引引擎（FTS5） │ ├── retriever.py # BM25 + 嵌入式检索 │ ├── reranker.py # 交叉编码器重新排序 │ ├── session.py # 会话状态跟踪器 │ ├── optimizer.py # 技能元数据优化器 │ ├── feedback.py # 反馈收集 + 贝叶斯学习 │ ├── tracker.py # 使用情况分析 │ ├── models.py # 数据模型（技能、查询结果、会话状态、反馈记录） │ └── mcp_server.py # MCP 服务器（11个工具） │ └── mcp_setup.py # 多代理MCP设置注册表（13个平台） ├── tests/ │ ├── test_models.py # 14个测试 — 数据模型 + YAML解析 + 无引号冒号 │ ├── test_indexer.py # 19个测试 — 索引/重新索引/跳过/检测/进度/WAL │ ├── test_retriever.py # 10个测试 — BM25/嵌入式/RRF/混合/会话/图增强/空 │ ├── test_adaptive.py # 20个测试 — 肘部检测/DBSCAN聚类/多样性/自适应查询 │ ├── test_graph.py # 7个测试 — 图边/PPR/图增强 │ ├── test_session_feedback.py # 21个测试 — 会话生命周期 + 反馈 │ ├── test_optimizer.py # 9个测试 — 压缩/扩展/信息泄露 │ ├── test_tracker.py # 8个测试 — 记录/洞察/每日趋势 │ ├── test_reranker.py # 6个测试 — 回退/空/前k/自定义模型 │ ├── test_mcp_setup.py # 26个测试 — 多代理注册表（13个平台） │ └── test_regression.py # 24个测试 — 错误回归覆盖 ├── scripts/ │ ├── benchmark.sh # 性能基准测试 │ └── demo.sh # 交互式演示 ├── configs/ │ └── default.yaml # 默认配置 ├── docs/ │ ├── ARCHITECTURE.md # 详细架构文档 │ └── MCP-INTEGRATION.md # MCP集成指南 ├── pyproject.toml ├── LICENSE └── README.md ``` ### 存储 单个SQLite数据库（`~/.scm/db/scm.db`）采用WAL模式： | 表 | 目的 | |-------|---------| | `skills` + `skills_fts` (FTS5) | 技能索引 + 全文搜索 | | `sessions` + `session_skills` | 会话跟踪 | | `feedback` + `skill_weights` + `query_patterns` | 反馈与学习 | | `usage_events` + `daily_stats` | 使用情况分析 | ## 工作流程示例 ### 1. 代理接收新任务 ``` 用户： "部署应用程序到生产环境" 代理内部调用： → skill_query(query="部署应用程序到生产环境", top_k=3) → 返回： [kubernetes-deploy (0.92), docker-build (0.78), monitoring (0.45)] → 代理加载kubernetes-deploy SKILL.md，执行部署步骤 → skill_session_use(session_id="...", skill_name="kubernetes-deploy", success=true) ``` ### 2. 代理需要上下文注入 ``` 代理生成系统提示块： "活动技能： [kubernetes-deploy] 相关技能： [docker-build, helm-chart] 估计上下文： 15个标记" ``` ### 3. 代理稍后遇到类似任务 ```bash # 此查询无需再次扫描所有技能。 # 会话跟踪器知道kubernetes-deploy已被使用并提升它。 # 每次查询节省50-200个标记。 scm session context --id "..." --query "扩展部署" ``` ## 开发 ### 运行测试 ```bash # 所有168个测试 uv run pytest -v # 特定模块 uv run pytest tests/test_indexer.py -v # 仅回归测试 uv run pytest tests/test_regression.py -v # 覆盖率（可选） uv run pytest --cov=src/scm/ tests/ ``` ### 支持的技能格式 - 带有YAML前置信息的SKILL.md（Hermes Agent，Claude Code） - 明文文件（目录名称 = 技能名称） ### 数据库迁移 ```bash # SCM在版本更改时自动迁移模式（CREATE TABLE IF NOT EXISTS） # 无需手动迁移 ``` ## 路线图 - [x] 研究与架构（SkillRouter，Anthropic，MCP可扩展性） - [x] 核心索引引擎（FTS5 + BM25） - [x] 语义检索（嵌入式 + 混合） - [x] 带有持久性的会话跟踪器 - [x] 元数据优化器（压缩 + 扩展） - [ ] 交叉编码器重新排序（已评估，跳过 — RAM 1.2GB/1.5GB 需要） - [x] 带有贝叶斯权重的反馈环 - [x] 使用情况分析和洞察 - [x] **MCP服务器**（11个工具） - [x] **多代理MCP设置**（13个平台：Claude Code，Claude Desktop，Cursor，Windsurf，Cline，Gemini，VS Code，Zed，Codex CLI，Goose，Continue.dev，OpenCode，Hermes Agent） - [x] **单个共享数据库**（消除跨数据库错误） - [x] **所有模块的77个测试** - [x] **101个测试 + 16个错误修复**（v0.2.1） - [x] **代理自动检测**（v0.4.0 — `--all` = 仅检测， `--force-all` = 所有13个） - [x] **包重命名 + 安装目录**（v0.5.0 — 包 → `scm`，目录 → `~/.scm/`） - [x] **索引安全性 + 自动检测**（v0.6.0 — 跳过隐藏/噪声目录，`scm index` 自动检测代理技能目录，进度指示器） - [ ] GUI仪表盘 - [ ] 多代理会话共享 ## 参考 1. **SkillRouter：用于大规模LLM代理的检索和重新排序技能选择** — Zheng 等，2026（arXiv预印本）。 [arXiv:2603.22455](https://arxiv.org/abs/2603.22455) 2. **高级工具使用和工具搜索** — Anthropic工程博客。 [链接](https://www.anthropic.com/engineering/advanced-tool-use) 3. **MCP工具可扩展性问题** — Jenova AI。 [链接](https://www.jenova.ai/en/resources/mcp-tool-scalability-problem) 4. **技能优于MCP：上下文高效代理能力** — Agentic Engineer。 [链接](https://www.agentic-engineer.com/blog/2025-12-04-skills-over-mcps-context-efficiency) 5. **超越提示：代理技能作为动态上下文管理** — Dev.to。 [链接](https://dev.to/peng_r_8a73c977039dac3b9c/beyond-the-prompt-understanding-agent-skills-as-dynamic-context-management-e5o) ## 许可证 MIT — Copyright (c) 2026 Mavis2103 ## 变更日志 参见 [CHANGELOG.md](CHANGELOG.md) 获取版本历史记录。当前： **v0.6.2**。