Skill Shelf: 给 agent 的 skill 仓库，兼做服务的配置中心
内容提要
Skill Shelf是一个统一管理AI agent技能（skill）和配置的中心化服务。它采用Git式版本模型管理技能，通过BM25召回和LLM重排实现路由，支持反馈驱动改进，并以MCP server供agent使用。配置中心提供namespace隔离、草稿/发布版本化、token授权和.env导入。后端使用Rust，前端使用React+Tauri，桌面和Web共用同一套代码。
延伸解读
版本模型复用 Git 对象模型
Skill Shelf 直接采用 Git 的对象模型（Blob、Tree、Commit、Branch）来管理 skill 版本，利用内容寻址存储实现文件去重。这种设计使得修改 SKILL.md 而未动 scripts/ 时，仅新增一个 blob 和一个 tree，其余文件自动共享，无需额外去重逻辑。对于需要频繁迭代 skill 的开发者，这种版本管理方式既熟悉又高效，降低了学习成本。
路由取舍：BM25 召回 + LLM 重排
Skill Shelf 选择 BM25 召回加 LLM 重排，而非向量库，主要基于运维成本和实际效果。BM25 在短描述和关键词查询场景下表现良好，且零依赖、离线可用；LLM 重排能弥补语义差异，但只能从召回候选中选择。对于小规模 skill 库（少于 15 个），系统会全量重排，保证 100% 召回率。这一设计权衡了性能与成本，适合个人和小团队使用。
反馈闭环驱动 skill 改进
Skill Shelf 的反馈系统不仅记录评分，还区分来源（human/agent）并保存原始查询，使反馈能同时优化 skill 内容和路由质量。通过 refine 接口，系统利用 LLM 生成改进草稿，但草稿落在独立分支，需人工审核合并，确保可执行内容不被随意修改。这种机制让 skill 能持续进化，同时保持安全性，是 AI 辅助开发中的一种务实实践。
配置中心的安全与版本化设计
配置中心采用 namespace 隔离、草稿/发布版本化，以及 service token 授权（仅存 SHA-256 哈希）。回退操作需经过复核再发布，确保变更可控。此外，关闭认证时配置中心拒绝服务，防止未授权访问。.env 导入功能简化了迁移，但值一律按字符串处理，避免类型猜测错误。这些设计体现了对配置安全性和操作严谨性的重视。
Q&A
Skill Shelf 是什么？它主要解决什么问题？
Skill Shelf 是一个统一管理 AI agent 技能（skill）和配置的中心化服务。它基于“skill 和 config 都是运行时才取的行为定义”这一理念，将两者纳入同一服务管理。它提供类似 Git 的版本管理、基于自然语言的路由、反馈驱动的改进，并通过 MCP server 供 agent 使用；同时提供配置中心功能，支持 namespace 隔离、草稿/发布版本化、token 授权等。
Skill Shelf 如何管理 skill 的版本？
Skill Shelf 直接采用 Git 的对象模型（Blob、Tree、Commit、Branch）进行版本管理，使用内容寻址存储（CAS）实现文件去重。每个文件内容按 SHA-256 哈希存储，相同内容只存一份；提交时只新增变更的文件，未变文件自动共享。分支是唯一可变的指针，指向 head commit。
Skill Shelf 的路由机制是怎样的？为什么不用向量数据库？
路由采用 BM25 召回加 LLM 重排的方式。BM25 基于 SQLite FTS5 实现，负责初步召回；LLM 重排处理语义相似但用词不同的情况。不上向量库的原因：BM25 在短描述场景下已足够好，LLM 重排能补语义短板，而向量库的运维成本高（部署、付费、重算向量等）。代价是零词法重叠时无法召回，但小规模库（≤15个 skill）会全量重排，缓解了该问题。
Skill Shelf 如何利用反馈来改进 skill？
反馈闭环包括：记录反馈（rating、source、query），通过 refine 接口调用 LLM 生成改进草稿，草稿落在 refine/* 分支，人工审核合并后更新路由索引并标记反馈为已应用。反馈的 source 区分 human 和 agent，query 记录路由时的需求原文，可用于优化 skill 内容和路由质量。
Skill Shelf 的配置中心有哪些核心功能？
配置中心支持 namespace 隔离、草稿/发布版本化、service token 授权（SHA-256 哈希）、.env 导入。每个 namespace 有 draft 和 versions，编辑只改草稿，发布后消费方才能读取；支持回退（需复核）和 diff 对比。token 只存哈希，明文仅签发时展示一次。
Skill Shelf 的持久化策略是什么？为什么加载失败时选择 panic？
写操作采用快照-落盘-提交内存三步，磁盘写失败则返回 500 且运行态不变。加载时区分失败类型：文件不存在用默认值（首次启动），解析失败则 panic 拒绝启动。这样做的原因是避免用空配置覆盖已有数据，防止用户配置丢失。
Skill Shelf 的 MCP server 提供哪些工具？
MCP server 以 stdio 运行，提供 route（路由）、list_skills（浏览）、load_skill（加载）、read_skill_file（读取文件）、feedback（反馈）、get_config（获取配置）等工具。load_skill 和 read_skill_file 分开实现渐进披露，避免一次性加载整个 skill 包。
Skill Shelf 的前端架构有什么特点？
前端使用 React 19 + Vite + TanStack + shadcn/ui，桌面端通过 Tauri 封装，但桌面和 Web 共用同一套代码，前端只通过 HTTP 访问后端。Tauri 层只负责窗口、托盘等，不直接调用 core。这样避免了双代码路径，降低了维护成本。
