All your AI agent sessions in one place — browse, search, resume. Rust + GPUI.
Rust
//! 本机 agent skill 的只读总览(issue #62)。skill 是 `<目录>/<名字>/SKILL.md`(YAML
//! frontmatter + Markdown 正文),各家 agent 各收在自己的目录里(`~/.claude/skills`、
//! `~/.codex/skills`……),另有多家共读的 `~/.agents/skills`(vercel-labs 的 `npx skills`
//! 把它当正本、往各家目录里链)。这里只做"看":按名字把各处的安装归拢成一个 skill,看出
//! 哪些是同一份(符号链接到同一个真实目录)、哪些是各自的拷贝、拷贝之间 SKILL.md 有没有
//! 分叉。**只读**(不变量 2):不安装、不拷贝、不链接、不同步、不删除——跨 agent 装 skill
//! 是 `npx skills add` 的事(用户 2026-10-15 定)。
//!
//! 取舍:
//! - 不进索引库、不建 FTS:skill 只有几百份,进页与 Refresh 时现扫,SKILL.md 的解析结果按
//! (mtime, size) 缓存在 `SkillCache`。
//! - **只读每个条目顶层的 SKILL.md,绝不往 skill 目录里递归**:有的 skill 是整个仓库的检出
//! (本机 `~/.claude/skills/gstack` 1.3 GB)。"内容一致"因此只比 SKILL.md 的哈希,有意不比
//! 整个目录;点开头的条目(`.system` 一类)也不看。唯一的下探是 Hermes 的分类目录。
//! - 目录从 roster 派生(不变量 8,不另建名单):各家用户级目录挂在本地实例**确认过的 home**
//! 下(`AgentAdapter::homes`,`CODEX_HOME` / `QODER_CONFIG_DIR` 这类在构造时已解析;直接选了
//! 数据目录的自定义根没有 home,不越界摸父目录),远程实例不看;家目录 / 配置目录下的固定
//! 位置与项目级目录是各家静态的事实,与 roster 无关(该家会话 location 全停用了照样列)。
//! 归属指"文件夹是谁家的",不推算"谁读得到"——十几家都读 `~/.agents/skills`、好几家读
//! `~/.claude/skills`,各家读哪些随版本在变。
//! - "读不出" ≠ "没有":目录或 SKILL.md 不存在(NotFound / 不是目录)就是没有;别的 I/O
//! 错误记进 `SkillScan::errors`,界面照实提示,不当成空。
use crate::adapters::parse_utils::{mtime_ms, project_name_of};
use crate::adapters::{self, AgentAdapter};
use crate::models::AgentId;
use crate::text;
use sha2::{Digest, Sha256};
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::io::ErrorKind;
use std::path::{Path, PathBuf};
use std::sync::Mutex;
/// skill 的入口文件名(Agent Skills 规范)
const SKILL_MD: &str = "SKILL.md";
/// 多家共读的 skill 文件夹:家目录下(`~/.agents/skills`)与每个项目根下同一个相对路径
pub const SHARED_DIR: &str = ".agents/skills";
/// `npx skills` 新版的落点:`$XDG_CONFIG_HOME/agents/skills`
const SHARED_CONFIG_DIR: &str = "agents/skills";
/// 一个 skill 文件夹归谁:共享目录(`.agents/skills`,多家共读),或某一家 agent 自己的
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum SkillOwner {
Shared,
Agent(AgentId),
}
/// 一处安装的层级。派生的 Ord 即展示序:用户级、插件、项目级
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum SkillScope {
/// home 下的(`~/.claude/skills`、`~/.agents/skills`……)
User,
/// Claude Code 插件自带的;`id` 是 `installed_plugins.json` 的键(`<插件>@<市场>`),
/// `enabled` 读自 settings.json 的 `enabledPlugins`(没写的算开着)
Plugin { id: String, enabled: bool },
/// 已索引项目根下的(`<项目>/.claude/skills`……)
Project { root: PathBuf },
}
impl SkillScope {
/// 插件名(`id` 里 `@` 前那段),skill 在 Claude Code 里叫 `<插件>:<名字>`
pub fn plugin_name(&self) -> Option<&str> {
match self {
SkillScope::Plugin { id, .. } => Some(id.split('@').next().unwrap_or(id)),
_ => None,
}
}
}
/// 一处安装:某个 skill 文件夹里的一个条目
#[derive(Debug, Clone)]
pub struct SkillInstall {
pub owner: SkillOwner,
pub scope: SkillScope,
/// 列出来的条目目录 `<skill 文件夹>/<条目名>`
pub path: PathBuf,
/// 解析掉符号链接后的真实目录:"同一份" = 同一个它
pub real_path: PathBuf,
/// 条目本身或它所在的 skill 文件夹是符号链接
pub linked: bool,
/// SKILL.md 的 sha256 前 8 字节:"内容一致" = 它相等(只比 SKILL.md,见模块文档)
pub content_hash: u64,
/// frontmatter 的 `name`,没有就用目录名;插件的加 `<插件>:` 前缀
pub name: String,
/// frontmatter 的 `description`,没有给空串
pub description: String,
/// SKILL.md 的修改时间(epoch ms)
pub updated_at: i64,
}
impl SkillInstall {
pub fn skill_md(&self) -> PathBuf {
self.path.join(SKILL_MD)
}
}
/// 同名的安装归成一个 skill。汇总字段在扫描时算好一次(列表每帧都要读)
#[derive(Debug, Clone)]
pub struct Skill {
pub name: String,
/// 按 (归属, 层级, 路径) 排好
pub installs: Vec<SkillInstall>,
/// 几份真实拷贝(符号链接指向同一处的算一份)
pub copies: usize,
/// 各处 SKILL.md 内容不全一样
pub differs: bool,
/// 有一处是符号链接
pub linked: bool,
/// 有它的各方(去重、按 SkillOwner 序)
pub owners: Vec<SkillOwner>,
/// 有一处是插件自带的(列表行挂 "plugin" 徽章)
pub plugin: bool,
/// 最近改过的那处(`installs` 下标,平局取靠前的);列表的说明与阅读面默认显示它
pub newest: usize,
/// 折叠过大小写的名字与各处说明(`descriptions` 与 `installs` 一一对应):搜索拿它比,
/// 扫描时折一次,不必每次输入把几百份说明再折一遍
folded: FoldedSkill,
}
#[derive(Debug, Clone)]
struct FoldedSkill {
name: String,
descriptions: Vec<String>,
}
impl Skill {
fn new(name: String, mut installs: Vec<SkillInstall>) -> Self {
installs.sort_by(|a, b| (a.owner, &a.scope, &a.path).cmp(&(b.owner, &b.scope, &b.path)));
let mut newest = 0;
for (ix, install) in installs.iter().enumerate() {
if install.updated_at > installs[newest].updated_at {
newest = ix;
}
}
// installs 先按归属排,相邻去重就是各方
let mut owners: Vec<SkillOwner> = installs.iter().map(|i| i.owner).collect();
owners.dedup();
let folded = FoldedSkill {
name: text::fold_case(&name),
descriptions: installs
.iter()
.map(|i| text::fold_case(&i.description))
.collect(),
};
Self {
copies: installs
.iter()
.map(|i| &i.real_path)
.collect::<HashSet<_>>()
.len(),
differs: installs
.iter()
.any(|i| i.content_hash != installs[0].content_hash),
linked: installs.iter().any(|i| i.linked),
plugin: installs
.iter()
.any(|i| matches!(i.scope, SkillScope::Plugin { .. })),
owners,
newest,
folded,
name,
installs,
}
}
pub fn description(&self) -> &str {
&self.installs[self.newest].description
}
pub fn updated_at(&self) -> i64 {
self.installs[self.newest].updated_at
}
}
/// 读不出来的位置(不是"没有"):路径 + 英文错误
#[derive(Debug, Clone)]
pub struct SkillError {
pub path: PathBuf,
pub message: String,
}
impl SkillError {
fn new(path: &Path, e: impl std::fmt::Display) -> Self {
Self {
path: path.to_path_buf(),
message: e.to_string(),
}
}
}
#[derive(Debug, Clone, Default)]
pub struct SkillScan {
/// 按名字排(不分大小写)
pub skills: Vec<Skill>,
pub errors: Vec<SkillError>,
}
/// 侧栏导航的计数(都是 skill 数,不是安装数)
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SkillCounts {
pub total: usize,
/// 有两份及以上真实拷贝的
pub duplicated: usize,
/// 按 SkillOwner 序
pub owners: Vec<(SkillOwner, usize)>,
/// 有项目级 skill 的项目,按项目名排
pub projects: Vec<(PathBuf, usize)>,
}
impl SkillScan {
pub fn counts(&self) -> SkillCounts {
let mut owners: BTreeMap<SkillOwner, usize> = BTreeMap::new();
let mut projects: BTreeMap<&Path, usize> = BTreeMap::new();
for skill in &self.skills {
for &owner in &skill.owners {
*owners.entry(owner).or_default() += 1;
}
let roots: BTreeSet<&Path> = skill
.installs
.iter()
.filter_map(|i| match &i.scope {
SkillScope::Project { root } => Some(root.as_path()),
_ => None,
})
.collect();
for root in roots {
*projects.entry(root).or_default() += 1;
}
}
let mut projects: Vec<(PathBuf, usize)> = projects
.into_iter()
.map(|(root, n)| (root.to_path_buf(), n))
.collect();
projects.sort_by_cached_key(|(root, _)| (project_name(root).to_lowercase(), root.clone()));
SkillCounts {
total: self.skills.len(),
duplicated: self.skills.iter().filter(|s| s.copies > 1).count(),
owners: owners.into_iter().collect(),
projects,
}
}
/// 按名字找回一个 skill:重扫后下标会变,界面记的是名字
pub fn index_of(&self, name: &str) -> Option<usize> {
self.skills.iter().position(|s| s.name == name)
}
/// 按名字与说明找 skill(⌘K 面板的 Skills 栏;SKILL.md 正文不搜):与会话、记忆同一套分词,
/// 每个词都得出现在名字或某一处安装的说明里,大小写折叠与片段的高亮同一个取法。排序:词全在
/// 名字里的在前,其中名字越短越靠前(名字恰好就是查询的排第一);其余按名字里缺几个词;同档
/// 按名字
pub fn search(&self, q: &str) -> Vec<SkillHit> {
let terms = text::fts_terms(q);
if terms.is_empty() {
return Vec::new();
}
let needles: Vec<String> = terms.iter().map(|t| text::fold_case(t)).collect();
let mut ranked: Vec<((usize, usize), SkillHit)> = Vec::new();
for (ix, skill) in self.skills.iter().enumerate() {
let folded = &skill.folded;
let described = |i: usize, needle: &str| folded.descriptions[i].contains(needle);
// 名字里没有的词,都得在某一处的说明里
let unnamed: Vec<&str> = needles
.iter()
.map(String::as_str)
.filter(|needle| !folded.name.contains(needle))
.collect();
if !unnamed
.iter()
.all(|needle| (0..skill.installs.len()).any(|i| described(i, needle)))
{
continue;
}
// 显示、打开哪一处(片段也取自它):名字里没有的那些词,说明里凑得最齐的那一处;一样齐的
// 取最近改过的那份,再按排序在前的。只看"有没有命中",搜 staging cluster 会落到只写着
// staging 的最新那份上(Codex review 2026-10-25)
let covered = |i: usize| unnamed.iter().filter(|needle| described(i, needle)).count();
let (mut install, mut best) = (skill.newest, covered(skill.newest));
for i in 0..skill.installs.len() {
let n = covered(i);
if n > best {
(install, best) = (i, n);
}
}
let length = if unnamed.is_empty() {
skill.name.chars().count()
} else {
0
};
ranked.push((
(unnamed.len(), length),
SkillHit {
skill: ix,
install,
snippet: text::make_snippet(&skill.installs[install].description, &terms),
},
));
}
// 稳定排序:同档保持 skills 的顺序,即按名字
ranked.sort_by_key(|(rank, _)| *rank);
ranked.into_iter().map(|(_, hit)| hit).collect()
}
}
/// skill 搜索的一条命中(`SkillScan::search`)
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SkillHit {
/// `SkillScan::skills` 的下标
pub skill: usize,
/// 片段取自哪一处安装的说明(`Skill::installs` 的下标),打开时显示的也是它
pub install: usize,
/// 说明的片段,带 HL_OPEN / HL_CLOSE 高亮;没有说明是空串
pub snippet: String,
}
/// 项目根的显示名(与会话、记忆的项目名同一个取法)
pub fn project_name(root: &Path) -> String {
project_name_of(&root.to_string_lossy())
}
// ---------------- 位置:各家的 skill 文件夹在哪 ----------------
/// 一家的用户级 skill 文件夹怎么推。依据各家官方文档 / 源码(2026-10-15 核对),只收 Wake
/// 名单里的 agent 自己的文件夹;没核实的(Kimi Code 文档写 `~/.kimi/skills`,而 Wake 读的
/// Kimi Code 数据在 `~/.kimi-code`,对不上;WorkBuddy 只有第三方说法;Grok Bot 没有本地目录)
/// 不猜
enum UserDirs {
/// 本地实例确认过的 home(`AgentAdapter::homes`)下的相对路径;里面的 `*` 段是"每个
/// 子目录"(Craft 的每个工作区)
FromHome(&'static str),
/// 固定位置:该家没有改 home 的开关,或 skill 不随它走(ZCode 的 skill 恒在
/// `homedir()/.zcode/skills`,`ZCODE_STORAGE_DIR` 只挪数据)
Fixed(Base, &'static [&'static str]),
}
#[derive(Clone, Copy)]
enum Base {
Home,
/// `$XDG_CONFIG_HOME`(缺省 `~/.config`)
Config,
/// 应用配置目录:Windows 是 `%APPDATA%`,其余同 Config(Devin)
AppConfig,
}
fn user_dirs(agent: AgentId) -> Option<UserDirs> {
use UserDirs::*;
Some(match agent {
// `$CODEX_HOME/skills` 官方已标弃用(改读 ~/.agents/skills)但仍读;`.system` 是
// Codex 自带的,点开头的条目不看
AgentId::ClaudeCode
| AgentId::Codex
| AgentId::Qoder
| AgentId::Cursor
| AgentId::Codebuddy
| AgentId::Grok
| AgentId::Dsh
| AgentId::Pi
| AgentId::Omp
| AgentId::Kiro
| AgentId::Gemini
| AgentId::Copilot
// HERMES_HOME 与各 profile 各一个
| AgentId::Hermes
| AgentId::Openclaw => FromHome("skills"),
// 每个工作区一个
AgentId::CraftAgents => FromHome("workspaces/*/skills"),
// 新版桌面端 / IDE、CLI,与旧版(本机还有)
AgentId::Antigravity => Fixed(
Base::Home,
&[
".gemini/config/skills",
".gemini/antigravity-cli/skills",
".gemini/antigravity/skills",
],
),
AgentId::Zcode => Fixed(Base::Home, &[".zcode/skills"]),
// 新版与旧版扩展
AgentId::Kilo => Fixed(Base::Home, &[".kilo/skills", ".kilocode/skills"]),
AgentId::Opencode => Fixed(Base::Config, &["opencode/skills"]),
// OpenCode 分支,同一套 xdg-basedir(MIMOCODE_HOME 改道不跟,OpenCode 的 OPENCODE_CONFIG_DIR
// 同样);它还读 `skill/` 单数与 `~/.mimocode`,常用的是这一处
AgentId::MimoCode => Fixed(Base::Config, &["mimocode/skills"]),
AgentId::Devin => Fixed(Base::AppConfig, &["devin/skills"]),
AgentId::Kimi | AgentId::GrokBot | AgentId::Workbuddy => return None,
})
}
/// 一家在项目根下的 skill 文件夹(相对路径)。共享的 `.agents/skills` 单列(`SHARED_DIR`)
fn project_dirs(agent: AgentId) -> &'static [&'static str] {
match agent {
AgentId::ClaudeCode => &[".claude/skills"],
AgentId::Codex => &[".codex/skills"],
AgentId::Qoder => &[".qoder/skills"],
AgentId::Copilot => &[".github/skills"],
AgentId::Cursor => &[".cursor/skills"],
AgentId::Opencode => &[".opencode/skills"],
AgentId::Kiro => &[".kiro/skills"],
AgentId::Gemini => &[".gemini/skills"],
AgentId::Pi => &[".pi/skills"],
AgentId::Omp => &[".omp/skills"],
AgentId::Grok => &[".grok/skills"],
// 旧版;新版读的是共享的 .agents/skills
AgentId::Antigravity => &[".agent/skills"],
AgentId::Dsh => &[".dsh/skills"],
AgentId::Hermes => &[".hermes/skills"],
AgentId::Codebuddy => &[".codebuddy/skills"],
AgentId::Zcode => &[".zcode/skills"],
AgentId::Devin => &[".devin/skills"],
AgentId::Kilo => &[".kilo/skills"],
AgentId::MimoCode => &[".mimocode/skills"],
AgentId::Openclaw
| AgentId::CraftAgents
| AgentId::Kimi
| AgentId::GrokBot
| AgentId::Workbuddy => &[],
}
}
/// 这家的 skill 文件夹是分类目录布局:没有 SKILL.md 的条目是一个分类,往下找(Hermes 的
/// `<分类>/<skill>/SKILL.md`,它自己按 os.walk 发现;mlops 下还有一层)
fn has_categories(owner: SkillOwner) -> bool {
owner == SkillOwner::Agent(AgentId::Hermes)
}
/// 分类目录最多往下找几层(到有 SKILL.md 的目录即停,绝不进 skill 目录里面)
const CATEGORY_DEPTH: usize = 3;
/// 推固定位置用的两个根。`current()` 读进程环境;测试用 `at(假 home)`,不碰环境变量
#[derive(Debug, Clone)]
pub struct SkillHomes {
home: PathBuf,
/// `$XDG_CONFIG_HOME`,缺省 `<home>/.config`
config: PathBuf,
}
impl SkillHomes {
pub fn current() -> Self {
let home = adapters::home_dir().unwrap_or_default();
let config = adapters::env_dir("XDG_CONFIG_HOME").unwrap_or_else(|| home.join(".config"));
Self { home, config }
}
pub fn at(home: &Path) -> Self {
Self {
home: home.to_path_buf(),
config: home.join(".config"),
}
}
fn base(&self, base: Base) -> PathBuf {
match base {
Base::Home => self.home.clone(),
Base::Config => self.config.clone(),
// Windows `%APPDATA%`:与 adapters 同一约定,从 home 派生
Base::AppConfig if cfg!(windows) => self.home.join("AppData").join("Roaming"),
Base::AppConfig => self.config.clone(),
}
}
}
/// `a/b` 形式的相对路径按段拼(Windows 上也对)
fn join_rel(base: &Path, rel: &str) -> PathBuf {
rel.split('/')
.fold(base.to_path_buf(), |p, seg| p.join(seg))
}
/// 读不读得出:不存在(含"中间某段不是目录")是没有,别的是读不出
fn absent(e: &std::io::Error) -> bool {
matches!(e.kind(), ErrorKind::NotFound | ErrorKind::NotADirectory)
}
/// 一个待读的 skill 文件夹
struct Location {
owner: SkillOwner,
scope: SkillScope,
dir: PathBuf,
/// `dir` 的真实路径:里面不是链接的条目,真实路径就是它接上条目名,不必逐个 canonicalize
real: PathBuf,
/// `dir` 本身就是一个 skill(插件清单直接点名的 skill 目录),不是装 skill 的文件夹
single: bool,
/// `dir` 自己是符号链接(里面每一项都算链接)
linked: bool,
}
/// 收集位置:同一归属、同一层级下同一个真实文件夹只读一次(Codex 的 sessions 与 archived 同一个
/// home、一家多个实例);不同归属或不同项目指到同一处(整个文件夹是符号链接)各列各的——那正是
/// "链接"
#[derive(Default)]
struct Plan {
locations: Vec<Location>,
seen: HashSet<(SkillOwner, SkillScope, PathBuf)>,
/// 已列的用户级 / 插件文件夹的**逻辑路径**(父目录解析掉链接、末段原样):项目级展开出
/// 同一个路径时跳过——家目录被索引成项目时,`~/.claude/skills` 不能再当一份项目级来一遍。
/// 按真实路径比会把"项目里的 skills 目录链到 ~/.agents/skills"这种真安装也吞掉(Codex
/// review 2026-10-15)
covered: HashSet<PathBuf>,
errors: Vec<SkillError>,
}
/// 父目录解析掉链接、末段原样:同一个文件夹换个写法(经由链接的家目录)认得出,而一个本身
/// 是链接的 skills 目录仍是它自己
fn logical_path(dir: &Path) -> PathBuf {
match (dir.parent(), dir.file_name()) {
(Some(parent), Some(name)) => std::fs::canonicalize(parent)
.map(|p| p.join(name))
.unwrap_or_else(|_| dir.to_path_buf()),
_ => dir.to_path_buf(),
}
}
impl Plan {
fn add(&mut self, owner: SkillOwner, scope: SkillScope, dir: PathBuf) {
self.add_location(owner, scope, dir, false);
}
fn add_location(&mut self, owner: SkillOwner, scope: SkillScope, dir: PathBuf, single: bool) {
// 先 lstat:项目级展开问的大多是不存在的路径,一次系统调用就够,是不是链接顺带知道;
// canonicalize 只给真有的
let meta = match std::fs::symlink_metadata(&dir) {
Ok(meta) => meta,
Err(e) if absent(&e) => return,
Err(e) => return self.errors.push(SkillError::new(&dir, e)),
};
let linked = meta.file_type().is_symlink();
if !linked && !meta.is_dir() {
return;
}
let real = match std::fs::canonicalize(&dir) {
Ok(real) if real.is_dir() => real,
Ok(_) => return,
Err(e) if absent(&e) => return,
Err(e) => return self.errors.push(SkillError::new(&dir, e)),
};
// 不是链接的文件夹,逻辑路径就是真实路径
let logical = if linked {
logical_path(&dir)
} else {
real.clone()
};
let project = matches!(scope, SkillScope::Project { .. });
if project && self.covered.contains(&logical) {
return;
}
if !self.seen.insert((owner, scope.clone(), real.clone())) {
return;
}
if !project {
self.covered.insert(logical);
}
self.locations.push(Location {
owner,
scope,
dir,
real,
single,
linked,
});
}
/// `rel` 里的 `*` 段展开成每个子目录(不看点开头的)
fn add_under_home(&mut self, owner: SkillOwner, home: &Path, rel: &str) {
let Some((parent, rest)) = rel.split_once("/*/") else {
return self.add(owner, SkillScope::User, join_rel(home, rel));
};
let parent = join_rel(home, parent);
match sorted_entries(&parent) {
Ok(names) => {
for (name, _) in names {
self.add(owner, SkillScope::User, join_rel(&parent.join(name), rest));
}
}
Err(e) if absent(&e) => {}
Err(e) => self.errors.push(SkillError::new(&parent, e)),
}
}
}
/// 目录里不以点开头的条目(名字, 是不是符号链接),按名字排。链接与否取自目录项本身
/// (Unix 的 d_type),不再逐个 lstat
fn sorted_entries(dir: &Path) -> std::io::Result<Vec<(std::ffi::OsString, bool)>> {
let mut names = Vec::new();
for entry in std::fs::read_dir(dir)? {
let entry = entry?;
let name = entry.file_name();
if name.to_string_lossy().starts_with('.') {
continue;
}
names.push((name, entry.file_type()?.is_symlink()));
}
names.sort();
Ok(names)
}
/// Claude Code 插件自带的 skill 文件夹:`<home>/plugins/installed_plugins.json` 里每个插件
/// 的 `installPath` 下的 `skills/`,外加清单(`.claude-plugin/plugin.json`)`skills` 字段
/// 列的路径。**只认 installPath**:插件缓存里堆着几十个旧版本(带 `.orphaned_at`),扫缓存
/// 目录会把它们全算进来
fn add_claude_plugins(plan: &mut Plan, home: &Path) {
let index = home.join("plugins").join("installed_plugins.json");
let text = match std::fs::read_to_string(&index) {
Ok(text) => text,
Err(e) if absent(&e) => return,
Err(e) => return plan.errors.push(SkillError::new(&index, e)),
};
let json: serde_json::Value = match serde_json::from_str(&text) {
Ok(json) => json,
Err(e) => return plan.errors.push(SkillError::new(&index, e)),
};
let Some(plugins) = json.get("plugins").and_then(|p| p.as_object()) else {
return;
};
// 开关在 settings.json 的 enabledPlugins;读不出就当都开着(只是少标一个 disabled)
let enabled: HashMap<String, bool> = std::fs::read_to_string(home.join("settings.json"))
.ok()
.and_then(|t| serde_json::from_str::<serde_json::Value>(&t).ok())
.and_then(|s| {
s.get("enabledPlugins")?.as_object().map(|m| {
m.iter()
.filter_map(|(k, v)| Some((k.clone(), v.as_bool()?)))
.collect()
})
})
.unwrap_or_default();
for (id, entries) in plugins {
let Some(entries) = entries.as_array() else {
continue;
};
let scope = SkillScope::Plugin {
id: id.clone(),
enabled: enabled.get(id).copied().unwrap_or(true),
};
for entry in entries {
let Some(install) = entry.get("installPath").and_then(|p| p.as_str()) else {
continue;
};
for (dir, single) in plugin_skill_dirs(Path::new(install), &mut plan.errors) {
let owner = SkillOwner::Agent(AgentId::ClaudeCode);
plan.add_location(owner, scope.clone(), dir, single);
}
}
}
}
/// (目录, 它本身是不是一个 skill):默认的 `skills/` 与清单里列的,既可以是装 skill 的文件夹,
/// 也可以直接是一个 skill 的目录——里面就有 SKILL.md 的按单个 skill 读(Codex review
/// 2026-10-15;同一个目录先按文件夹登记、再按单个 skill 来就会被去重吞掉,所以一律按内容判)
/// 清单不在就只有默认目录;在却读不出、JSON 坏了要报出来(它列的目录就看不到了),不当成
/// 没有(Codex review 2026-10-15)
fn plugin_skill_dirs(install: &Path, errors: &mut Vec<SkillError>) -> Vec<(PathBuf, bool)> {
let mut dirs = vec![install.join("skills")];
let manifest = install.join(".claude-plugin").join("plugin.json");
let parsed = match std::fs::read_to_string(&manifest) {
Ok(text) => serde_json::from_str::<serde_json::Value>(&text)
.map_err(|e| errors.push(SkillError::new(&manifest, e)))
.ok(),
Err(e) if absent(&e) => None,
Err(e) => {
errors.push(SkillError::new(&manifest, e));
None
}
};
if let Some(listed) = parsed.and_then(|m| m.get("skills").cloned()) {
let rels: Vec<String> = match listed {
serde_json::Value::String(s) => vec![s],
serde_json::Value::Array(a) => a
.into_iter()
.filter_map(|v| v.as_str().map(str::to_string))
.collect(),
_ => Vec::new(),
};
dirs.extend(
rels.iter()
.map(|r| join_rel(install, r.trim_start_matches("./").trim_end_matches('/'))),
);
}
dirs.into_iter()
.map(|dir| {
let single = dir.join(SKILL_MD).is_file();
(dir, single)
})
.collect()
}
/// 各位置的先后:共享目录、各家用户级(按 AgentId 序)、Claude Code 插件、各项目。`roster`
/// 是每个本地实例的 (agent, 确认过的 homes)
fn plan(roster: &[(AgentId, Vec<PathBuf>)], homes: &SkillHomes, projects: &[PathBuf]) -> Plan {
let homes_of = |agent: AgentId| {
roster
.iter()
.filter(move |(a, _)| *a == agent)
.flat_map(|(_, homes)| homes)
};
let mut plan = Plan::default();
plan.add(
SkillOwner::Shared,
SkillScope::User,
join_rel(&homes.home, SHARED_DIR),
);
plan.add(
SkillOwner::Shared,
SkillScope::User,
join_rel(&homes.config, SHARED_CONFIG_DIR),
);
for agent in AgentId::ALL {
let owner = SkillOwner::Agent(agent);
match user_dirs(agent) {
Some(UserDirs::FromHome(rel)) => {
for home in homes_of(agent) {
plan.add_under_home(owner, home, rel);
}
}
Some(UserDirs::Fixed(base, rels)) => {
let base = homes.base(base);
for rel in rels {
plan.add(owner, SkillScope::User, join_rel(&base, rel));
}
}
None => {}
}
}
for home in homes_of(AgentId::ClaudeCode) {
add_claude_plugins(&mut plan, home);
}
let roots: BTreeSet<&PathBuf> = projects.iter().filter(|p| p.is_absolute()).collect();
for root in roots {
let scope = SkillScope::Project { root: root.clone() };
plan.add(
SkillOwner::Shared,
scope.clone(),
join_rel(root, SHARED_DIR),
);
for agent in AgentId::ALL {
for rel in project_dirs(agent) {
plan.add(SkillOwner::Agent(agent), scope.clone(), join_rel(root, rel));
}
}
}
plan
}
// ---------------- 读 ----------------
/// SKILL.md 解析结果的缓存:键是真实路径(多处链到同一份只读一次),戳是 (mtime, size)。
/// 每轮扫描后只留这轮见过的
#[derive(Default)]
pub struct SkillCache(Mutex<HashMap<PathBuf, ParsedSkillMd>>);
#[derive(Clone)]
struct ParsedSkillMd {
stamp: (i64, u64),
name: Option<String>,
description: Option<String>,
hash: u64,
}
impl SkillCache {
pub fn new() -> Self {
Self::default()
}
fn get_or_read(&self, md: &Path, meta: &std::fs::Metadata) -> std::io::Result<ParsedSkillMd> {
let stamp = (mtime_ms(meta), meta.len());
if let Some(hit) = self.0.lock().unwrap().get(md).filter(|p| p.stamp == stamp) {
return Ok(hit.clone());
}
let bytes = std::fs::read(md)?;
let text = String::from_utf8_lossy(&bytes);
let digest = Sha256::digest(&bytes);
let mut prefix = [0u8; 8];
prefix.copy_from_slice(&digest[..8]);
let parsed = ParsedSkillMd {
stamp,
name: adapters::frontmatter_ident(&text, "name"),
description: adapters::frontmatter_field(&text, "description"),
hash: u64::from_be_bytes(prefix),
};
self.0
.lock()
.unwrap()
.insert(md.to_path_buf(), parsed.clone());
Ok(parsed)
}
fn retain(&self, seen: &HashSet<PathBuf>) {
self.0.lock().unwrap().retain(|k, _| seen.contains(k));
}
}
/// 读各个 skill 文件夹:每个条目只 stat / 读它顶层的 SKILL.md
struct Reader<'a> {
cache: &'a SkillCache,
/// 这轮读到的 SKILL.md(真实路径),扫完按它修剪缓存
seen: HashSet<PathBuf>,
/// 已记下的安装 (归属, 层级, 条目路径):插件清单点名的 skill 也在它列的(或默认的)
/// 文件夹里时,两条读法读到同一处,只记一次。在读的时候按实际条目去重,与清单里的先后
/// 无关——/simplify 2026-10-23 曾挪到规划阶段按文件夹判,清单写成
/// `["./extra/deploy", "./extra"]` 就读两遍、`skills/` 本身是 skill 时又漏掉点名的那个
/// (Codex review 同日),改回来
listed: HashSet<(SkillOwner, SkillScope, PathBuf)>,
installs: Vec<SkillInstall>,
errors: Vec<SkillError>,
}
impl Reader<'_> {
/// `dir` 里的每个条目:有 SKILL.md 就是一个 skill;没有、而这家是分类布局就当分类往下找。
/// `real` 是 `dir` 的真实路径,`dir_linked` 是这一路上有没有经过符号链接
fn read_dir(
&mut self,
loc: &Location,
dir: &Path,
real: &Path,
dir_linked: bool,
depth: usize,
) {
let names = match sorted_entries(dir) {
Ok(names) => names,
Err(e) if absent(&e) => return,
Err(e) => return self.errors.push(SkillError::new(dir, e)),
};
for (entry, entry_link) in names {
let path = dir.join(&entry);
// 条目自身是不是链接单独判:文件夹是链接、里面的条目又链到别处时,真实路径得现
// 解析(Codex review 2026-10-15);不是链接的条目,真实路径就是所在文件夹的真实
// 路径接上条目名
let real_path = if entry_link {
match std::fs::canonicalize(&path) {
Ok(real_path) => real_path,
Err(e) if absent(&e) => continue,
Err(e) => {
self.errors.push(SkillError::new(&path, e));
continue;
}
}
} else {
real.join(&entry)
};
let linked = dir_linked || entry_link;
let missing = self.read_entry(loc, &path, &real_path, linked);
if missing && has_categories(loc.owner) && depth + 1 < CATEGORY_DEPTH && path.is_dir() {
self.read_dir(loc, &path, &real_path, linked, depth + 1);
}
}
}
/// 一个条目:有 SKILL.md 就记一处安装。返回"这里没有 SKILL.md"(NotFound;分类目录布局
/// 据此往下找)
fn read_entry(&mut self, loc: &Location, path: &Path, real_path: &Path, linked: bool) -> bool {
let key = (loc.owner, loc.scope.clone(), path.to_path_buf());
if self.listed.contains(&key) {
return false;
}
let md = path.join(SKILL_MD);
let meta = match std::fs::metadata(&md) {
Ok(meta) if meta.is_file() => meta,
Ok(_) => return false,
Err(e) if e.kind() == ErrorKind::NotFound => return true,
Err(e) if absent(&e) => return false,
Err(e) => {
self.errors.push(SkillError::new(&md, e));
return false;
}
};
let real_md = real_path.join(SKILL_MD);
let parsed = match self.cache.get_or_read(&real_md, &meta) {
Ok(parsed) => parsed,
Err(e) if absent(&e) => return false,
Err(e) => {
self.errors.push(SkillError::new(&md, e));
return false;
}
};
self.seen.insert(real_md);
self.listed.insert(key);
let base = parsed.name.unwrap_or_else(|| {
path.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_default()
});
let name = match loc.scope.plugin_name() {
Some(plugin) => format!("{plugin}:{base}"),
None => base,
};
self.installs.push(SkillInstall {
owner: loc.owner,
scope: loc.scope.clone(),
linked,
path: path.to_path_buf(),
real_path: real_path.to_path_buf(),
content_hash: parsed.hash,
name,
description: parsed.description.unwrap_or_default(),
updated_at: mtime_ms(&meta),
});
false
}
}
/// 扫一遍:各家本地实例的 home、固定位置与共享目录、Claude Code 插件,加上各项目的项目级
/// 目录。`projects` 是已索引的本地项目根(`Store::local_project_roots`)
pub fn scan(
adapters: &[Box<dyn AgentAdapter>],
projects: &[PathBuf],
cache: &SkillCache,
) -> SkillScan {
let roster: Vec<(AgentId, Vec<PathBuf>)> = adapters
.iter()
.filter(|a| a.host().is_empty())
.map(|a| (a.agent(), a.homes()))
.collect();
scan_in(&roster, &SkillHomes::current(), projects, cache)
}
/// `scan` 的本体:roster 只要 (agent, 确认过的 homes),homes 显式给——测试在临时目录里搭
/// 假 home,不碰环境变量
pub fn scan_in(
roster: &[(AgentId, Vec<PathBuf>)],
homes: &SkillHomes,
projects: &[PathBuf],
cache: &SkillCache,
) -> SkillScan {
let plan = plan(roster, homes, projects);
let mut reader = Reader {
cache,
seen: HashSet::new(),
listed: HashSet::new(),
installs: Vec::new(),
errors: plan.errors,
};
for loc in &plan.locations {
if loc.single {
reader.read_entry(loc, &loc.dir, &loc.real, loc.linked);
} else {
reader.read_dir(loc, &loc.dir, &loc.real, loc.linked, 0);
}
}
cache.retain(&reader.seen);
let mut groups: BTreeMap<(String, String), Vec<SkillInstall>> = BTreeMap::new();
for install in reader.installs {
groups
.entry((install.name.to_lowercase(), install.name.clone()))
.or_default()
.push(install);
}
SkillScan {
skills: groups
.into_iter()
.map(|((_, name), installs)| Skill::new(name, installs))
.collect(),
errors: reader.errors,
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::models::{HL_CLOSE, HL_OPEN};
fn install(owner: SkillOwner, name: &str, description: &str, updated_at: i64) -> SkillInstall {
let path = PathBuf::from(format!("/skills/{owner:?}/{name}"));
SkillInstall {
owner,
scope: SkillScope::User,
real_path: path.clone(),
path,
linked: false,
content_hash: 0,
name: name.to_string(),
description: description.to_string(),
updated_at,
}
}
/// 与 `scan_in` 收尾一样按名字排
fn scan_of(skills: Vec<Vec<SkillInstall>>) -> SkillScan {
let mut skills: Vec<Skill> = skills
.into_iter()
.map(|installs| Skill::new(installs[0].name.clone(), installs))
.collect();
skills.sort_by_key(|s| s.name.to_lowercase());
SkillScan {
skills,
errors: Vec::new(),
}
}
fn names(scan: &SkillScan, q: &str) -> Vec<String> {
scan.search(q)
.iter()
.map(|h| scan.skills[h.skill].name.clone())
.collect()
}
#[test]
fn search_puts_name_matches_first_and_the_closest_name_on_top() {
let claude = SkillOwner::Agent(AgentId::ClaudeCode);
let scan = scan_of(vec![
vec![install(claude, "writer", "Use to Review drafts", 1)],
vec![install(claude, "plan-eng-review", "Engineering plan", 1)],
vec![install(claude, "review", "Pre-landing review", 1)],
vec![install(claude, "code-review:code-review", "", 1)],
vec![install(claude, "deploy", "Ship it", 1)],
]);
assert_eq!(
names(&scan, "REVIEW"),
[
"review",
"plan-eng-review",
"code-review:code-review",
"writer"
],
"词全在名字里的按名字长短,只在说明里的垫底;大小写不论"
);
// 每个词都得出现在名字或说明里
assert_eq!(names(&scan, "review drafts"), ["writer"]);
assert_eq!(names(&scan, "review plan"), ["plan-eng-review"]);
assert!(scan.search(" ").is_empty());
assert!(scan.search("kubernetes").is_empty());
}
#[test]
fn search_snippets_come_from_the_install_that_matched() {
let codex = SkillOwner::Agent(AgentId::Codex);
let scan = scan_of(vec![vec![
install(
SkillOwner::Shared,
"deploy",
"Ship to the staging cluster",
1,
),
install(codex, "deploy", "Ship it", 2),
]]);
let skill = &scan.skills[0];
// 最近改过的那份(Codex 的)说明里没有这个词:片段取自有命中的那份
let hit = &scan.search("staging")[0];
assert_eq!(skill.installs[hit.install].owner, SkillOwner::Shared);
assert!(hit.snippet.contains(&format!("{HL_OPEN}staging{HL_CLOSE}")));
// 只在名字里命中:片段是最近那份的说明,不标
let hit = &scan.search("deploy")[0];
assert_eq!(hit.install, skill.newest);
assert_eq!(hit.snippet, "Ship it");
// 两处都提到 staging,只有旧的那份还写着 cluster:两个词一起搜,落在旧的那份上
let scan = scan_of(vec![vec![
install(SkillOwner::Shared, "deploy", "Ship to staging cluster", 1),
install(codex, "deploy", "Deploy to staging", 2),
]]);
let hit = &scan.search("staging cluster")[0];
assert_eq!(
scan.skills[0].installs[hit.install].owner,
SkillOwner::Shared
);
assert!(hit.snippet.contains(&format!("{HL_OPEN}cluster{HL_CLOSE}")));
}
#[test]
fn a_star_segment_expands_to_every_subdirectory() {
let tmp = tempfile::tempdir().unwrap();
let home = tmp.path();
for ws in ["alpha", "beta", ".hidden"] {
std::fs::create_dir_all(home.join("workspaces").join(ws).join("skills")).unwrap();
}
let mut plan = Plan::default();
plan.add_under_home(SkillOwner::Shared, home, "workspaces/*/skills");
let dirs: Vec<PathBuf> = plan.locations.iter().map(|l| l.dir.clone()).collect();
assert_eq!(
dirs,
vec![
home.join("workspaces/alpha/skills"),
home.join("workspaces/beta/skills"),
]
);
}
}