fix(skills): move local metadata refresh off the list query (#9316)

- Keep get_installed_skills read-only: return the DB snapshot via run_db_task without scanning SSOT directories
- Add refresh_local_skill_metadata as a separate async command on the blocking pool; scan hashes outside the global skill write lock and re-check installed_at, directory, and previous content_hash before writing back
- Trigger the refresh from a separate frontend query with staleTime Infinity; invalidate the installed list only when metadata changed
- Add backend tests for repo-skill exclusion and concurrent updates, plus hook tests for refresh and invalidation behavior

Refs #7848
This commit is contained in:
wyr-zal
2026-11-11 23:36:54 +08:00
committed by GitHub
parent 1a98613e7b
commit d4647fbbf5
8 changed files with 425 additions and 0 deletions
+15
View File
@@ -29,6 +29,9 @@ fn parse_app_type(app: &str) -> Result<AppType, String> {
// ========== 统一管理命令 ==========
/// 获取所有已安装的 Skills
///
/// 只读数据库,不扫描 SSOT 目录;元数据刷新由
/// [`refresh_local_skill_metadata`] 单独在后台完成(issue #7848)。
#[tauri::command]
pub async fn get_installed_skills(
app_state: State<'_, AppState>,
@@ -39,6 +42,18 @@ pub async fn get_installed_skills(
.await
}
/// 刷新本地 Skill 的过期元数据(手动编辑 SKILL.md 后同步名称/描述/哈希)。
///
/// 全目录哈希可能读入较大的资源文件,放到阻塞线程池执行,避免占用同步命令
/// 线程;返回实际更新的数量,前端仅在大于 0 时刷新列表。
#[tauri::command]
pub async fn refresh_local_skill_metadata(app_state: State<'_, AppState>) -> Result<usize, String> {
run_db_task(&app_state, |state| {
SkillService::refresh_local_skill_metadata(&state.db).map_err(|e| e.to_string())
})
.await
}
#[tauri::command]
pub fn get_skill_backups() -> Result<Vec<SkillBackupEntry>, String> {
SkillService::list_backups().map_err(|e| e.to_string())
+1
View File
@@ -1767,6 +1767,7 @@ pub fn run() {
commands::restore_env_backup,
// Skill management (v3.10.0+ unified)
commands::get_installed_skills,
commands::refresh_local_skill_metadata,
commands::get_skill_backups,
commands::delete_skill_backup,
commands::install_skill_unified,
+269
View File
@@ -573,6 +573,20 @@ fn parse_agents_lock() -> HashMap<String, LockRepoInfo> {
// ========== SkillService ==========
/// 本地 Skill 元数据刷新时扫描到的候选变更。
///
/// 扫描(目录哈希)在全局写锁外完成,写回前用这里记录的安装代次、目录和
/// 旧哈希重新核对,避免覆盖扫描期间发生的并发更新。
struct LocalSkillMetadataCandidate {
id: String,
directory: String,
installed_at: i64,
previous_hash: Option<String>,
name: String,
description: Option<String>,
new_hash: String,
}
pub struct SkillService {
#[cfg(test)]
repo_fixture: Option<PathBuf>,
@@ -1958,6 +1972,121 @@ impl SkillService {
result
}
/// 为本地 Skill(无仓库来源)刷新过期元数据(name/description/content_hash)。
///
/// 手动编辑 SSOT 目录下的 SKILL.md 后,数据库元数据仍是安装时的快照,
/// 技能列表会一直显示旧描述(issue #7848)。按 content_hash 失配检测
/// 本地文件变化并回写重新解析的结果。仓库 Skill 不在此处理:其哈希
/// 语义由 check_updates / update_skill 管理,重算会干扰远端更新比对。
///
/// 目录哈希可能很慢,因此只在快照技能列表时短暂持有读锁,扫描本身不占
/// 全局写锁(否则技能开关等同步命令会一直等扫描结束);写回时再短持写锁,
/// 重新读取并核对安装代次、目录与旧哈希,避免覆盖扫描期间的并发更新。
pub fn refresh_local_skill_metadata(db: &Arc<Database>) -> Result<usize> {
let ssot_dir = Self::get_ssot_dir()?;
let candidates = Self::collect_local_skill_metadata_candidates(&ssot_dir, db)?;
if candidates.is_empty() {
return Ok(0);
}
let _state_guard = skill_state_write_guard();
// 等待写锁期间可能发生了 SSOT 迁移;旧目录上的扫描结果不能写回。
if Self::get_ssot_dir()?.as_path() != ssot_dir {
return Ok(0);
}
Self::apply_local_skill_metadata_candidates(db, candidates)
}
#[cfg(test)]
fn refresh_local_skill_metadata_in(ssot_dir: &Path, db: &Arc<Database>) -> Result<usize> {
let candidates = Self::collect_local_skill_metadata_candidates(ssot_dir, db)?;
if candidates.is_empty() {
return Ok(0);
}
let _state_guard = skill_state_write_guard();
Self::apply_local_skill_metadata_candidates(db, candidates)
}
fn collect_local_skill_metadata_candidates(
ssot_dir: &Path,
db: &Arc<Database>,
) -> Result<Vec<LocalSkillMetadataCandidate>> {
let skills = {
let _state_guard = skill_state_read_guard();
db.get_all_installed_skills()?
};
let mut candidates = Vec::new();
for skill in skills.into_values() {
if skill.repo_owner.is_some() {
continue;
}
let directory = match Self::require_valid_directory(&skill.directory) {
Ok(d) => d,
Err(err) => {
log::warn!("Skill directory 非法,跳过元数据刷新: {err}");
continue;
}
};
let local_dir = ssot_dir.join(&directory);
let skill_md = local_dir.join("SKILL.md");
if !skill_md.is_file() {
continue;
}
let new_hash = match Self::compute_dir_hash(&local_dir) {
Ok(h) => h,
Err(err) => {
log::warn!("计算 Skill {directory} 哈希失败,跳过元数据刷新: {err}");
continue;
}
};
if skill.content_hash.as_deref() == Some(new_hash.as_str()) {
continue;
}
let (new_name, new_description) = Self::read_skill_name_desc(&skill_md, &directory);
candidates.push(LocalSkillMetadataCandidate {
id: skill.id,
directory,
installed_at: skill.installed_at,
previous_hash: skill.content_hash,
name: new_name,
description: new_description,
new_hash,
});
}
Ok(candidates)
}
/// 调用方必须持有 [`skill_state_write_guard`]。
fn apply_local_skill_metadata_candidates(
db: &Arc<Database>,
candidates: Vec<LocalSkillMetadataCandidate>,
) -> Result<usize> {
let mut refreshed = 0;
for candidate in candidates {
let Some(mut skill) = db.get_installed_skill(&candidate.id)? else {
continue;
};
if skill.installed_at != candidate.installed_at
|| skill.directory != candidate.directory
|| skill.repo_owner.is_some()
|| skill.content_hash != candidate.previous_hash
{
continue;
}
skill.name = candidate.name;
skill.description = candidate.description;
skill.content_hash = Some(candidate.new_hash);
skill.updated_at = chrono::Utc::now().timestamp();
if db.update_skill_metadata(&skill)? {
refreshed += 1;
log::info!("已刷新本地 Skill {} 的过期元数据", candidate.directory);
}
}
Ok(refreshed)
}
/// 为缺少 content_hash 的已安装 Skill 补算哈希
pub fn backfill_content_hashes(db: &Arc<Database>) -> Result<usize> {
let _state_guard = skill_state_write_guard();
@@ -5164,6 +5293,146 @@ mod tests {
assert!(skill_state_lock().try_write().is_ok());
}
#[test]
fn refresh_local_skill_metadata_updates_stale_snapshot() {
let db = Arc::new(Database::memory().expect("memory db"));
let ssot = tempdir().expect("ssot tempdir");
let dir_name = "demo-skill";
let skill_dir = ssot.path().join(dir_name);
fs::create_dir_all(&skill_dir).unwrap();
fs::write(
skill_dir.join("SKILL.md"),
"---\nname: demo\ndescription: old snapshot\n---\nbody\n",
)
.unwrap();
let installed = InstalledSkill {
id: format!("local:{dir_name}"),
name: "demo".to_string(),
description: Some("old snapshot".to_string()),
directory: dir_name.to_string(),
repo_owner: None,
repo_name: None,
repo_branch: None,
readme_url: None,
apps: SkillApps::only(&AppType::Claude),
installed_at: 1,
content_hash: Some("stale-hash".to_string()),
updated_at: 0,
};
db.save_skill(&installed).unwrap();
// 缓存哈希失配但文件未再变:回写真实哈希,description 保持原值
let refreshed = SkillService::refresh_local_skill_metadata_in(ssot.path(), &db).unwrap();
assert_eq!(refreshed, 1);
let after = db.get_installed_skill(&installed.id).unwrap().unwrap();
assert_eq!(after.description.as_deref(), Some("old snapshot"));
assert_ne!(after.content_hash.as_deref(), Some("stale-hash"));
let healed_hash = after.content_hash.clone();
// 手动编辑 SKILL.md:description 随哈希一起刷新
fs::write(
skill_dir.join("SKILL.md"),
"---\nname: demo\ndescription: edited externally\n---\nbody\n",
)
.unwrap();
let refreshed = SkillService::refresh_local_skill_metadata_in(ssot.path(), &db).unwrap();
assert_eq!(refreshed, 1);
let after = db.get_installed_skill(&installed.id).unwrap().unwrap();
assert_eq!(after.description.as_deref(), Some("edited externally"));
assert_ne!(after.content_hash, healed_hash);
// 幂等:无变化时不再刷新
let refreshed = SkillService::refresh_local_skill_metadata_in(ssot.path(), &db).unwrap();
assert_eq!(refreshed, 0);
}
#[test]
fn refresh_local_skill_metadata_skips_repo_skills() {
let db = Arc::new(Database::memory().expect("memory db"));
let ssot = tempdir().expect("ssot tempdir");
let dir_name = "repo-skill";
let skill_dir = ssot.path().join(dir_name);
fs::create_dir_all(&skill_dir).unwrap();
fs::write(
skill_dir.join("SKILL.md"),
"---\nname: repo\ndescription: edited externally\n---\nbody\n",
)
.unwrap();
let installed = InstalledSkill {
id: format!("repo:{dir_name}"),
name: "repo".to_string(),
description: Some("old snapshot".to_string()),
directory: dir_name.to_string(),
repo_owner: Some("owner".to_string()),
repo_name: Some("repo".to_string()),
repo_branch: Some("main".to_string()),
readme_url: None,
apps: SkillApps::only(&AppType::Claude),
installed_at: 1,
content_hash: Some("repo-hash".to_string()),
updated_at: 0,
};
db.save_skill(&installed).unwrap();
let refreshed = SkillService::refresh_local_skill_metadata_in(ssot.path(), &db).unwrap();
assert_eq!(refreshed, 0);
let after = db.get_installed_skill(&installed.id).unwrap().unwrap();
assert_eq!(after.description.as_deref(), Some("old snapshot"));
assert_eq!(after.content_hash.as_deref(), Some("repo-hash"));
}
#[test]
fn refresh_local_skill_metadata_discards_candidates_changed_during_scan() {
let db = Arc::new(Database::memory().expect("memory db"));
let ssot = tempdir().expect("ssot tempdir");
let dir_name = "demo-skill";
let skill_dir = ssot.path().join(dir_name);
fs::create_dir_all(&skill_dir).unwrap();
fs::write(
skill_dir.join("SKILL.md"),
"---\nname: demo\ndescription: edited externally\n---\nbody\n",
)
.unwrap();
let installed = InstalledSkill {
id: format!("local:{dir_name}"),
name: "demo".to_string(),
description: Some("old snapshot".to_string()),
directory: dir_name.to_string(),
repo_owner: None,
repo_name: None,
repo_branch: None,
readme_url: None,
apps: SkillApps::only(&AppType::Claude),
installed_at: 1,
content_hash: Some("stale-hash".to_string()),
updated_at: 0,
};
db.save_skill(&installed).unwrap();
let candidates =
SkillService::collect_local_skill_metadata_candidates(ssot.path(), &db).unwrap();
assert_eq!(candidates.len(), 1);
// 扫描完成后、写回之前发生了重装/并发更新:旧快照必须被丢弃。
let mut concurrent = db.get_installed_skill(&installed.id).unwrap().unwrap();
concurrent.description = Some("newer value".to_string());
concurrent.content_hash = Some("newer-hash".to_string());
concurrent.installed_at = 2;
db.save_skill(&concurrent).unwrap();
let _state_guard = skill_state_write_guard();
let refreshed =
SkillService::apply_local_skill_metadata_candidates(&db, candidates).unwrap();
assert_eq!(refreshed, 0);
let after = db.get_installed_skill(&installed.id).unwrap().unwrap();
assert_eq!(after.description.as_deref(), Some("newer value"));
assert_eq!(after.content_hash.as_deref(), Some("newer-hash"));
assert_eq!(after.installed_at, 2);
}
/// 构造一个模拟 GitHub 归档的 ZIP:带一层 `repo-main/` 根目录,
/// 其中掺入用 `../` 逃逸的恶意条目。
///
@@ -41,6 +41,7 @@ import {
useImportSkillsFromApps,
useInstallSkillsFromZip,
useInstalledSkills,
useRefreshLocalSkillMetadata,
useRestoreSkillBackup,
useScanUnmanagedSkills,
useSkillBackups,
@@ -177,6 +178,9 @@ const UnifiedSkillsPanel: React.FC<UnifiedSkillsPanelProps> = ({
error: loadError,
refetch,
} = useInstalledSkills();
// 列表先用数据库快照渲染;本地元数据在后台线程刷新,有新结果时才刷新列表。
// 独立 query 让开关/安装引起的列表失效不再重复扫描 SSOT 目录(issue #7848)。
useRefreshLocalSkillMetadata();
const {
data: skillBackups = [],
refetch: refetchSkillBackups,
+25
View File
@@ -40,6 +40,31 @@ export function useInstalledSkills() {
});
}
/**
* 后台刷新本地 Skill 的过期元数据(手动编辑 SSOT 的 SKILL.md 后同步描述与哈希)。
*
* 与列表查询分离:列表只读数据库并立即渲染,目录哈希在 Tauri 阻塞线程池里
* 计算;切换应用开关、安装等导致的列表失效不会重复触发扫描。进入技能页时
* 自动执行(缓存保持期间不重复扫描),有更新时才刷新列表(issue #7848)。
*/
export function useRefreshLocalSkillMetadata() {
const queryClient = useQueryClient();
return useQuery({
queryKey: ["skills", "localMetadataRefresh"],
queryFn: async () => {
const refreshed = await skillsApi.refreshLocalMetadata();
if (refreshed > 0) {
await queryClient.invalidateQueries({
queryKey: ["skills", "installed"],
});
}
return refreshed;
},
staleTime: Infinity,
retry: false,
});
}
export function useSkillBackups() {
return useQuery({
queryKey: ["skills", "backups"],
+5
View File
@@ -203,6 +203,11 @@ export const skillsApi = {
return await invoke("get_installed_skills");
},
/** 刷新本地 Skill 的过期元数据,返回实际更新的数量 */
async refreshLocalMetadata(): Promise<number> {
return await invoke("refresh_local_skill_metadata");
},
/** 获取可恢复的 Skill 备份列表 */
async getBackups(): Promise<SkillBackupEntry[]> {
return await invoke("get_skill_backups");
@@ -63,6 +63,7 @@ vi.mock("@/hooks/useSkills", () => ({
isError: false,
refetch: vi.fn(),
}),
useRefreshLocalSkillMetadata: () => ({}),
useSkillBackups: () => ({
data: m.backups,
refetch: m.refetchBackups,
@@ -0,0 +1,105 @@
import type { PropsWithChildren } from "react";
import { act, renderHook, waitFor } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { useRefreshLocalSkillMetadata } from "@/hooks/useSkills";
const refreshLocalMetadataMock = vi.hoisted(() => vi.fn());
vi.mock("@/lib/api/skills", () => ({
skillsApi: {
refreshLocalMetadata: refreshLocalMetadataMock,
},
}));
function createWrapper(queryClient: QueryClient) {
return function Wrapper({ children }: PropsWithChildren) {
return (
<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
);
};
}
describe("useRefreshLocalSkillMetadata", () => {
beforeEach(() => {
refreshLocalMetadataMock.mockReset();
});
it("refreshes the installed list only when metadata changed", async () => {
refreshLocalMetadataMock.mockResolvedValue(2);
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
});
const invalidateSpy = vi
.spyOn(queryClient, "invalidateQueries")
.mockResolvedValue(undefined);
const { result } = renderHook(() => useRefreshLocalSkillMetadata(), {
wrapper: createWrapper(queryClient),
});
await waitFor(() => expect(result.current.isSuccess).toBe(true));
expect(refreshLocalMetadataMock).toHaveBeenCalledTimes(1);
expect(invalidateSpy).toHaveBeenCalledWith({
queryKey: ["skills", "installed"],
});
});
it("does not invalidate the list when nothing changed", async () => {
refreshLocalMetadataMock.mockResolvedValue(0);
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
});
const invalidateSpy = vi
.spyOn(queryClient, "invalidateQueries")
.mockResolvedValue(undefined);
const { result } = renderHook(() => useRefreshLocalSkillMetadata(), {
wrapper: createWrapper(queryClient),
});
await waitFor(() => expect(result.current.isSuccess).toBe(true));
expect(invalidateSpy).not.toHaveBeenCalled();
});
it("does not rescan when the installed list is invalidated", async () => {
refreshLocalMetadataMock.mockResolvedValue(1);
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
});
vi.spyOn(queryClient, "invalidateQueries").mockResolvedValue(undefined);
const { result } = renderHook(() => useRefreshLocalSkillMetadata(), {
wrapper: createWrapper(queryClient),
});
await waitFor(() => expect(result.current.isSuccess).toBe(true));
expect(refreshLocalMetadataMock).toHaveBeenCalledTimes(1);
await act(async () => {
await queryClient.invalidateQueries({
queryKey: ["skills", "installed"],
});
});
expect(refreshLocalMetadataMock).toHaveBeenCalledTimes(1);
});
it("keeps the result cached across remounts in the same session", async () => {
refreshLocalMetadataMock.mockResolvedValue(1);
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
});
vi.spyOn(queryClient, "invalidateQueries").mockResolvedValue(undefined);
const first = renderHook(() => useRefreshLocalSkillMetadata(), {
wrapper: createWrapper(queryClient),
});
await waitFor(() => expect(first.result.current.isSuccess).toBe(true));
first.unmount();
const second = renderHook(() => useRefreshLocalSkillMetadata(), {
wrapper: createWrapper(queryClient),
});
await waitFor(() => expect(second.result.current.isSuccess).toBe(true));
expect(refreshLocalMetadataMock).toHaveBeenCalledTimes(1);
});
});