From d4647fbbf5d68f8a246db87b96937ea29ac62a4d Mon Sep 17 00:00:00 2001 From: wyr-zal <1270446073@qq.com> Date: Wed, 11 Nov 2026 23:36:54 +0800 Subject: [PATCH] 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 --- src-tauri/src/commands/skill.rs | 15 + src-tauri/src/lib.rs | 1 + src-tauri/src/services/skill.rs | 269 ++++++++++++++++++ src/components/skills/UnifiedSkillsPanel.tsx | 4 + src/hooks/useSkills.ts | 25 ++ src/lib/api/skills.ts | 5 + tests/components/UnifiedSkillsPanel.test.tsx | 1 + .../useRefreshLocalSkillMetadata.test.tsx | 105 +++++++ 8 files changed, 425 insertions(+) create mode 100644 tests/hooks/useRefreshLocalSkillMetadata.test.tsx diff --git a/src-tauri/src/commands/skill.rs b/src-tauri/src/commands/skill.rs index bcee579a0..8f315b7c3 100644 --- a/src-tauri/src/commands/skill.rs +++ b/src-tauri/src/commands/skill.rs @@ -29,6 +29,9 @@ fn parse_app_type(app: &str) -> Result { // ========== 统一管理命令 ========== /// 获取所有已安装的 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 { + 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, String> { SkillService::list_backups().map_err(|e| e.to_string()) diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index 186738cb1..cc7518024 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -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, diff --git a/src-tauri/src/services/skill.rs b/src-tauri/src/services/skill.rs index 520a11e02..5731cb2aa 100644 --- a/src-tauri/src/services/skill.rs +++ b/src-tauri/src/services/skill.rs @@ -573,6 +573,20 @@ fn parse_agents_lock() -> HashMap { // ========== SkillService ========== +/// 本地 Skill 元数据刷新时扫描到的候选变更。 +/// +/// 扫描(目录哈希)在全局写锁外完成,写回前用这里记录的安装代次、目录和 +/// 旧哈希重新核对,避免覆盖扫描期间发生的并发更新。 +struct LocalSkillMetadataCandidate { + id: String, + directory: String, + installed_at: i64, + previous_hash: Option, + name: String, + description: Option, + new_hash: String, +} + pub struct SkillService { #[cfg(test)] repo_fixture: Option, @@ -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) -> Result { + 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) -> Result { + 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, + ) -> Result> { + 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, + candidates: Vec, + ) -> Result { + 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) -> Result { 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/` 根目录, /// 其中掺入用 `../` 逃逸的恶意条目。 /// diff --git a/src/components/skills/UnifiedSkillsPanel.tsx b/src/components/skills/UnifiedSkillsPanel.tsx index c776497ec..d6836a8b5 100644 --- a/src/components/skills/UnifiedSkillsPanel.tsx +++ b/src/components/skills/UnifiedSkillsPanel.tsx @@ -41,6 +41,7 @@ import { useImportSkillsFromApps, useInstallSkillsFromZip, useInstalledSkills, + useRefreshLocalSkillMetadata, useRestoreSkillBackup, useScanUnmanagedSkills, useSkillBackups, @@ -177,6 +178,9 @@ const UnifiedSkillsPanel: React.FC = ({ error: loadError, refetch, } = useInstalledSkills(); + // 列表先用数据库快照渲染;本地元数据在后台线程刷新,有新结果时才刷新列表。 + // 独立 query 让开关/安装引起的列表失效不再重复扫描 SSOT 目录(issue #7848)。 + useRefreshLocalSkillMetadata(); const { data: skillBackups = [], refetch: refetchSkillBackups, diff --git a/src/hooks/useSkills.ts b/src/hooks/useSkills.ts index 6abdfb970..aba31e983 100644 --- a/src/hooks/useSkills.ts +++ b/src/hooks/useSkills.ts @@ -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"], diff --git a/src/lib/api/skills.ts b/src/lib/api/skills.ts index 497839853..0939a90de 100644 --- a/src/lib/api/skills.ts +++ b/src/lib/api/skills.ts @@ -203,6 +203,11 @@ export const skillsApi = { return await invoke("get_installed_skills"); }, + /** 刷新本地 Skill 的过期元数据,返回实际更新的数量 */ + async refreshLocalMetadata(): Promise { + return await invoke("refresh_local_skill_metadata"); + }, + /** 获取可恢复的 Skill 备份列表 */ async getBackups(): Promise { return await invoke("get_skill_backups"); diff --git a/tests/components/UnifiedSkillsPanel.test.tsx b/tests/components/UnifiedSkillsPanel.test.tsx index 4365557b5..59f03627f 100644 --- a/tests/components/UnifiedSkillsPanel.test.tsx +++ b/tests/components/UnifiedSkillsPanel.test.tsx @@ -63,6 +63,7 @@ vi.mock("@/hooks/useSkills", () => ({ isError: false, refetch: vi.fn(), }), + useRefreshLocalSkillMetadata: () => ({}), useSkillBackups: () => ({ data: m.backups, refetch: m.refetchBackups, diff --git a/tests/hooks/useRefreshLocalSkillMetadata.test.tsx b/tests/hooks/useRefreshLocalSkillMetadata.test.tsx new file mode 100644 index 000000000..ccdf46f43 --- /dev/null +++ b/tests/hooks/useRefreshLocalSkillMetadata.test.tsx @@ -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 ( + {children} + ); + }; +} + +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); + }); +});