ai-agent-skills 架构深潜:install-state 索引与 bundled、workspace 两种模式的切换原理

原创2026-10-14 09:02:281,464 阅读
文章标签:AI 技能CLI开发工具AI 插件

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):

  1. 扫描 global、project 两个目标目录,收集各自的 skill 名单;
  2. 用一个 Map(bySkill)按 skill 名称聚合,每个条目记录 global 与 project 两个布尔值;
  3. 返回 { 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)的判定流程,可以理解为"从脚下往头顶找":

  1. 从当前工作目录开始,逐层向上检查父目录;
  2. 哪一层同时有 skills.json 和 .ai-agent-skills/config.json,就以它作为 workspace 根,模式 = workspace;
  3. 一路找到文件系统顶部都没找到,则回落到包自带目录,模式 = 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 帮你搭建和维护自己的技能库了。

登录后查看全文
ai-agent-skills