ai-agent-skills 架构深潜:install-state 索引与 bundled、workspace 两种模式的切换原理
ai-agent-skills 架构深潜:install-state 索引与 bundled、workspace 两种模式的切换原理
ai-agent-skills 是一款面向 AI 编码 Agent 的通用 skill 安装器与包管理器,一条 npx ai-agent-skills 命令即可支持 12+ 运行时。🧩 本文不依赖任何源码基础,拆解它最核心的两块内部机制:install-state 安装状态索引,以及 bundled(内置库)与 workspace(工作区库)两种模式的自动切换原理,帮你理解为什么它在任何目录下运行都能"知道"你在用哪个技能库、哪些 skill 已经装好。
🚀 30 秒理解:ai-agent-skills 的双重身份
ai-agent-skills 同时做两件事(见 README.md):
| 身份 | 说明 | 典型命令 |
|---|---|---|
| 精选技能库 | 内置 120+ 个 skill(17 个 house 本地副本 + 103 个上游目录项) | npx ai-agent-skills install frontend-design |
| 自建库管理器 | 用 CLI/TUI 搭建、维护你自己的技能工作区 | npx ai-agent-skills init-library my-library |
这两种身份,正是后文 bundled 与 workspace 两种模式的由来。安装目录方面,它约定了两个"标准作用域"(lib/paths.cjs):
- global:
~/.claude/skills/ - project:
.agents/skills/
📇 install-state:一份不扫盘的"已安装"快照
两个默认安装路径
所有"我装没装过这个 skill"的判断,起点都是两个固定目录。lib/install-state.cjs 中的 getStandardInstallTargets() 返回:
global -> ~/.claude/skills/
project -> <当前目录>/.agents/skills/
判断一个目录里"装了哪些 skill"的规则很简单:目录下的子文件夹里必须存在 SKILL.md(见 listInstalledSkillNamesInDir,lib/install-state.cjs)。这就是 Agent Skills 规范的最小约定——有 SKILL.md 才算一个 skill。
buildInstallStateIndex:一次构建,处处可用
如果每次显示列表都要去读两个目录,120 个 skill 逐个判断会非常慢。ai-agent-skills 的做法是一次性构建内存索引(lib/install-state.cjs):
- 扫描 global、project 两个目标目录,收集各自的 skill 名单;
- 用一个
Map(bySkill)按 skill 名称聚合,每个条目记录global与project两个布尔值; - 返回
{ cwd, targets, bySkill }这份"安装状态快照"。
bySkill: {
"frontend-design" -> { global: true, project: false }
"pdf" -> { global: false, project: true }
...
}
三态一标签:getInstallState
查询某个 skill 时,getInstallState()(lib/install-state.cjs)把两个布尔值翻译成人类可读的四种状态:
| global | project | 显示标签(label) |
|---|---|---|
| ✅ | ✅ | installed globally + project |
| ✅ | ❌ | installed globally |
| ❌ | ✅ | installed in project |
| ❌ | ❌ | 未安装(label: null) |
CLI 的 list、collections、TUI 浏览界面全都复用这同一份索引,保证"列表里显示的已安装状态"与磁盘真实状态一致。TUI 构建目录时也先建索引再逐个标注(tui/catalog.cjs)。
💡 细节:这份索引是只读的磁盘快照,不写任何文件。真正写入磁盘的"安装凭证"是每个 skill 目录旁的
.skill-meta.json(由 lib/install-metadata.cjs 写入),记录来源仓库、安装时间、作用域等元数据,供sync刷新和check体检使用。
🗂️ 模式切换:bundled 与 workspace 的自动判定
模式一:bundled(内置库)
npm 包自带一个"官方货架":包根目录下的 skills/ 目录存放 house 本地副本,skills.json 存放全部 120 个 skill 的目录元数据(货架、分支、来源、收录理由等)。
bundled 模式的上下文在 lib/library-context.cjs 中由 createLibraryContext(rootDir, 'bundled') 生成,其关键路径:
<包根目录>/skills.json ← 目录数据
<包根目录>/skills/<name>/ ← 本地 skill 文件
<包根目录>/README.md ← 文档
模式二:workspace(工作区库)
用 init-library 创建的管理工作区(cli.js)会落地三样东西:
skills.json:你的专属目录数据(由createStarterLibraryData生成);.ai-agent-skills/config.json:记录libraryName、librarySlug、mode: "workspace";skills/:存放你的本地 skill 副本。
两张"门票"与向上查找:切换原理
workspace 模式的识别靠两个文件同时存在(isManagedWorkspaceRoot,lib/library-context.cjs):
skills.json + .ai-agent-skills/config.json => 这是一个受管工作区
而自动切换发生在每次 CLI 启动的瞬间(cli.js 的 main()):
setActiveLibraryContext(resolveLibraryContext(process.cwd()))
resolveLibraryContext()(lib/library-context.cjs)的判定流程,可以理解为"从脚下往头顶找":
- 从当前工作目录开始,逐层向上检查父目录;
- 哪一层同时有
skills.json和.ai-agent-skills/config.json,就以它作为 workspace 根,模式 = workspace; - 一路找到文件系统顶部都没找到,则回落到包自带目录,模式 = bundled。
这意味着:你在 my-library/ 目录里随便哪个子文件夹执行 npx ai-agent-skills list,它都会自动操作你自己的库;在任意其他目录执行,则操作内置库。整个过程零配置、无感知——这就是"切换原理"的全部核心。
特殊分支:swift / mktg 快捷命令强制 bundled
swift 和 mktg 是快捷安装命令,它们始终针对内置库的精选集安装。因此在执行前会临时切回 bundled 上下文,结束后再还原(cli.js):
npx ai-agent-skills swift # 等价于安装 swift-agent-skills 集合
🔍 目录数据从哪来:skills.json 与 tier 推导
无论哪种模式,目录数据的读取都走 loadCatalogData(context)(lib/catalog-data.cjs),它按 context.skillsJsonPath 选择文件——这就是"同一个函数,两种模式各读各的 json"的实现方式。
每条 skill 会被 normalizeSkill() 归一化(lib/catalog-data.cjs),关键推导规则:
| 字段 | 推导逻辑 | 含义 |
|---|---|---|
tier: house |
vendored !== false |
本地副本,随包发布,离线可装 |
tier: upstream |
vendored === false |
仅元数据,安装时从源仓库拉取 |
distribution |
house→bundled,upstream→live |
分发方式 |
安装来源路径再由 inferInstallSourceFromCatalogSkill() 拼接为 owner/repo/路径 形式(cli.js)。TUI 中还会用 shouldTreatCatalogSkillAsHouse() 做二次校验:本地文件真实存在则按 house 处理(lib/catalog-paths.cjs),防止元数据与实际文件不一致。
📥 workspace 的另一半:导入与自动分类
进入 workspace 模式后,import --auto-classify 会扫描目录里的 skill 并自动上架。发现逻辑在 lib/workspace-import.cjs:
- 兼容 flat(根目录下直接放 skill)与 nested(
skills/子目录下)两种布局,重名时优先保留 nested 版本; classifyImportedSkill()用"词法打分"给 skill 分配货架(workArea):名称完全匹配 +120 分、别名命中 +100 分,正文关键词逐个计分;- 领先第二名 3 分以上才自动归类,否则落入
workflow兜底并打上needs-curation标签,等待curate命令人工修正。
📚 关键文件速查
| 模块 | 职责 |
|---|---|
| lib/install-state.cjs | 安装状态索引:buildInstallStateIndex / getInstallState |
| lib/library-context.cjs | bundled/workspace 模式上下文与自动判定 |
| lib/paths.cjs | 标准作用域、12 个旧版 agent 目标路径 |
| lib/catalog-data.cjs | skills.json 归一化、tier 推导、校验 |
| lib/install-metadata.cjs | .skill-meta.json 安装凭证读写 |
| lib/workspace-import.cjs | 工作区导入发现与自动分类 |
| tui/catalog.cjs | TUI 目录构建(索引 + 依赖图 + 集合) |
| cli.js | CLI 入口:每次启动先解析库上下文 |
✅ 小结
- install-state 索引:一次扫描 global/project 两个目录,构建内存
Map,把"装没装"变成 O(1) 查询,并统一输出四种状态标签; - bundled 模式:npm 包根目录即货架,
skills.json+skills/随包分发,离线可用; - workspace 模式:以
skills.json+.ai-agent-skills/config.json为双门票,CLI 每次启动从 cwd 向上查找、未命中则回落 bundled——零配置自动切换; - 两种模式共用同一套目录读取与安装状态逻辑,只是"根目录不同",这正是 ai-agent-skills 既能开箱即装、又能管理自建库的架构关键。
掌握这些机制后,再配合 CURATION.md 的策展规范与 FOR_YOUR_AGENT.md 的 Agent 协议,你就可以放心地让 AI 帮你搭建和维护自己的技能库了。