Skill Shelf: 给 agent 的 skill 仓库，兼做服务的配置中心
内容提要
Skill Shelf 是一个用 Rust 和 React 构建的服务，兼具 AI agent 技能仓库和配置中心功能。它采用类似 Git 的版本管理，通过 BM25 和 LLM 重排进行技能路由，支持反馈驱动改进，并提供 MCP 接口供 agent 使用。配置中心支持命名空间隔离、草稿发布和版本回退，设计强调优雅降级和安全性。
延伸解读
版本模型复用 Git 对象模型
Skill Shelf 直接采用 Git 的对象模型（Blob、Tree、Commit、Branch），并用内容寻址存储。这意味着相同内容只存一份，未改动的文件在多次提交间自动共享，无需额外去重逻辑。这种设计不仅简化了实现，还让 skill 的版本管理天然具备 Git 的灵活性和可靠性。对于需要频繁迭代 skill 的开发者，这种模型能有效降低存储开销，并保证历史版本的可追溯性。
路由取舍：BM25 召回 + LLM 重排
作者刻意不上向量检索，理由是 BM25 在短描述场景下已足够好，且 LLM 重排能弥补语义匹配的不足，同时避免了向量库的运维成本。但代价是零词法重叠时无法召回。为缓解此问题，当 skill 总数不超过 15 时，直接全量重排，保证 100% 召回率。这一设计体现了对实际使用场景的考量，也提醒读者在类似系统中，技术选型需权衡成本与效果。
反馈闭环与安全设计
反馈系统要求反馈直接驱动下一版 skill，草稿落在 refine/* 分支，经人工审核后才合并，确保可执行内容不被 AI 直接修改。配置中心采用快照-落盘-提交三步写操作，磁盘写失败则运行态不变并返回 500；加载时解析失败直接 panic，拒绝启动，避免用默认值覆盖用户数据。这些设计强调了安全性和可靠性，值得在类似系统中借鉴。
Q&A
Skill Shelf 是什么？它主要解决什么问题？
Skill Shelf 是一个用 Rust 和 React 构建的服务，兼具 AI agent 技能仓库和配置中心功能。它统一管理 agent 的 skill 和服务的配置，因为两者本质都是运行时才取的行为定义。它提供版本管理、路由、反馈闭环和配置管理，旨在解决 skill 分散、版本混乱和配置管理繁琐的问题。
Skill Shelf 如何管理 skill 的版本？
Skill Shelf 采用类似 Git 的对象模型，使用内容寻址存储（CAS），包括 Blob、Tree、Commit 和 Branch。每个文件按内容哈希存储，相同内容只存一次，提交时只新增变更的部分。SKILL.md 是唯一真相，frontmatter 作为权威源，提交后缓存到数据库。支持分支、回退和 diff 查看。
Skill Shelf 的路由机制是怎样的？为什么不用向量检索？
路由采用 BM25 召回 + LLM 重排的两阶段方案。BM25 基于 SQLite FTS5 实现，召回候选后，可选 LLM 重排以处理语义相似但用词不同的情况。不上向量的原因：BM25 已足够好，LLM 重排能补足语义短板，且向量库运维成本高。但 LLM 无法处理零词法重叠的情况，因此小规模（≤15）时全量重排，大规模时取 Top-20。
Skill Shelf 的反馈闭环是如何工作的？
反馈闭环要求反馈能直接驱动下一版 skill。用户或 agent 提交反馈（rating、content、source、query），系统通过 POST /skill/{id}/refine 调用 LLM 生成改进草稿，草稿落在 refine/* 分支，人工审核合并后才生效。合并后重建路由索引并标记反馈为已应用，从而改进路由质量。
Skill Shelf 如何作为 MCP 服务器供 agent 使用？
Skill Shelf 提供 MCP server（stdio），将 REST API 封装成工具，包括 route、list_skills、load_skill、read_skill_file、feedback 和 get_config。agent 可以通过这些工具路由需求、加载 skill、读取文件、提交反馈和获取配置。load_skill 和 read_skill_file 分开实现渐进披露，避免一次性加载整个包。
Skill Shelf 的配置中心有哪些核心功能？
配置中心支持 namespace 隔离、草稿/发布版本化、service token 授权、.env 一键导入。每个 namespace 有 draft 和 versions，编辑草稿不影响已发布配置，发布后版本号递增，支持回退（需复核）。支持 _global 层共享默认值，消费方通过 resolve 接口获取合并后的配置。
Skill Shelf 如何处理配置持久化的失败？
写操作采用快照-落盘-提交内存三步，磁盘写失败则运行态完全不变并返回 500，避免内存和文件不一致。加载时区分两种失败：文件不存在用默认值（首次启动），解析失败直接 panic 拒绝启动，防止用空配置覆盖已有数据。
Skill Shelf 的桌面端和 Web 端是如何统一的？
前端只通过 HTTP 访问后端，桌面和 Web 走完全相同的代码路径。Tauri 层不内嵌 core，只负责窗口、托盘和启动 server 二进制作为 sidecar。前端使用 axios，base URL 运行期可配，支持本地和远程服务器。这样避免了双代码路径，降低了维护成本。
Skill Shelf 目前有哪些未实现的功能？
未实现的功能包括：skill 安全扫描（当前最大缺口）、skill 自检、语义版本与发布通道、使用分析、从 GitHub 仓库直接拉 skill、CLI。此外，Postgres 后端虽然跑通 e2e，但 CAS 仍在本地文件系统，多实例部署需换成共享对象存储。
