feat(kit): enhance FsSkillStorage with entry existence check and resource summary listing

Author: gene9831

packages/kit/src/skills/storage/fs.ts

@@ -13,7 +13,7 @@ import {
 } from '../loader/utils'
 import type { SkillDefinition, SkillResourceDescriptor } from '../types'
 import { createImportSkill } from './importSkill'
-import type { SkillStorage } from './types'
+import type { SkillStorage, SkillSummary } from './types'
 
 /** 一个标准 skill 目录集合的文件系统 storage。 */
 export interface FsSkillStorageOptions {
@@ -97,7 +97,17 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
   }
 
   async has(name: string) {
-    return Boolean(await this.get(name))
+    const entryPath = join(this.getSkillDirectory(name), entryFile)
+
+    try {
+      return (await stat(entryPath)).isFile()
+    } catch (error) {
+      if (isFileNotFoundError(error)) {
+        return false
+      }
+
+      throw error
+    }
   }
 
   async delete(name: string) {
@@ -130,17 +140,33 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
     const summaries = await Promise.all(
       entries
         .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
-        .map(async (entry) => this.get(entry.name)),
+        .map(async (entry): Promise<SkillSummary | undefined> => {
+          const directory = this.getSkillDirectory(entry.name)
+          const skill = await this.readSkillEntry(directory).catch((error: unknown) => {
+            if (isFileNotFoundError(error)) {
+              return undefined
+            }
+
+            throw error
+          })
+
+          if (!skill) {
+            return undefined
+          }
+
+          const resourceCount = (await this.readResourceFiles(directory)).length
+
+          return {
+            name: skill.name,
+            description: skill.description,
+            resourceCount,
+            metadata: skill.metadata,
+          }
+        }),
     )
 
     return summaries
-      .filter((skill): skill is SkillDefinition => Boolean(skill))
-      .map((skill) => ({
-        name: skill.name,
-        description: skill.description,
-        resourceCount: skill.resources?.length ?? 0,
-        metadata: skill.metadata,
-      }))
+      .filter((summary): summary is SkillSummary => Boolean(summary))
       .sort((a, b) => a.name.localeCompare(b.name))
   }
 
@@ -162,6 +188,16 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
   }
 
   private async readSkillDirectory(directory: string): Promise<SkillDefinition> {
+    const skill = await this.readSkillEntry(directory)
+    const resources = await this.readResourceDescriptors(directory)
+
+    return {
+      ...skill,
+      resources: resources.length ? resources : undefined,
+    }
+  }
+
+  private async readSkillEntry(directory: string) {
     const entryPath = join(directory, entryFile)
     const entryContent = await readFile(entryPath, 'utf8')
     const { frontmatter, body } = parseMarkdownFrontmatter(entryContent)
@@ -171,13 +207,10 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
       throw new Error(`Skill entry file "${entryFile}" must contain instructions.`)
     }
 
-    const resources = await this.readResourceDescriptors(directory)
-
     return {
       name: getString(frontmatter.name) || directory.split(/[\\/]/).at(-1) || '',
       description: getString(frontmatter.description) || '',
       instructions,
-      resources: resources.length ? resources : undefined,
       metadata: {
         ...getRecord(frontmatter.metadata),
         ...(getString(frontmatter.homepage) ? { homepage: getString(frontmatter.homepage) } : {}),
@@ -188,6 +221,40 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
   private async readResourceDescriptors(directory: string) {
     const resources: SkillResourceDescriptor[] = []
 
+    for (const { fullPath, path } of await this.readResourceFiles(directory)) {
+      const fileStat = await stat(fullPath)
+      const kind = isTextSkillFilePath(path) ? 'text' : 'binary'
+      const base = {
+        path,
+        kind,
+        resourceId: path,
+        size: fileStat.size,
+        lastModified: fileStat.mtimeMs,
+      }
+
+      resources.push(
+        kind === 'text'
+          ? {
+              ...base,
+              kind,
+              readText: async () => readFile(fullPath, 'utf8'),
+              readBinary: async () => new Uint8Array(await readFile(fullPath)),
+            }
+          : {
+              ...base,
+              kind,
+              readBinary: async () => new Uint8Array(await readFile(fullPath)),
+              readText: async () => new TextDecoder().decode(await readFile(fullPath)),
+            },
+      )
+    }
+
+    return resources
+  }
+
+  private async readResourceFiles(directory: string) {
+    const files: Array<{ fullPath: string; path: string }> = []
+
     const walk = async (currentDirectory: string) => {
       const entries = await readdir(currentDirectory, {
         withFileTypes: true,
@@ -214,36 +281,12 @@ export class FsSkillStorage implements SkillStorage<SkillLoadOptions> {
           continue
         }
 
-        const fileStat = await stat(fullPath)
-        const kind = isTextSkillFilePath(path) ? 'text' : 'binary'
-        const base = {
-          path,
-          kind,
-          resourceId: path,
-          size: fileStat.size,
-          lastModified: fileStat.mtimeMs,
-        }
-
-        resources.push(
-          kind === 'text'
-            ? {
-                ...base,
-                kind,
-                readText: async () => readFile(fullPath, 'utf8'),
-                readBinary: async () => new Uint8Array(await readFile(fullPath)),
-              }
-            : {
-                ...base,
-                kind,
-                readBinary: async () => new Uint8Array(await readFile(fullPath)),
-                readText: async () => new TextDecoder().decode(await readFile(fullPath)),
-              },
-        )
+        files.push({ fullPath, path })
       }
     }
 
     await walk(directory)
-    return resources.sort((a, b) => a.path.localeCompare(b.path))
+    return files.sort((a, b) => a.path.localeCompare(b.path))
   }
 
   private async writeResource(directory: string, resource: SkillResourceDescriptor) {

packages/kit/src/skills/storage/types.ts

@@ -20,6 +20,7 @@ export interface SkillSummary {
 export interface SkillStorage<TImportOptions> {
   add(skill: SkillDefinition): Promise<SkillDefinition>
   get(name: string): Promise<SkillDefinition | undefined>
+  /** 判断 storage entry 是否存在，不验证内容是否可被完整读取。 */
   has(name: string): Promise<boolean>
   delete(name: string): Promise<boolean>
   list(): Promise<SkillSummary[]>

packages/kit/src/skills/test/fsStorage.test.ts

@@ -1,4 +1,4 @@
-import { cp, mkdtemp, readFile, rename, writeFile } from 'node:fs/promises'
+import { cp, mkdir, mkdtemp, readFile, rename, stat, writeFile } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
@@ -11,15 +11,18 @@ vi.mock('node:fs/promises', async (importOriginal) => {
   return {
     ...fs,
     rename: vi.fn(fs.rename),
+    stat: vi.fn(fs.stat),
   }
 })
 
-const { rename: actualRename } = await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
+const { rename: actualRename, stat: actualStat } =
+  await vi.importActual<typeof import('node:fs/promises')>('node:fs/promises')
 const createTempRoot = () => mkdtemp(join(tmpdir(), 'tiny-robot-skill-storage-'))
 
 describe('FsSkillStorage', () => {
   afterEach(() => {
     vi.mocked(rename).mockReset().mockImplementation(actualRename)
+    vi.mocked(stat).mockReset().mockImplementation(actualStat)
   })
 
   it.each(['.', '.hidden'])('rejects invalid skill name %s', async (name) => {
@@ -242,6 +245,60 @@ describe('FsSkillStorage', () => {
     ).toThrow(readonlyError)
   })
 
+  it('checks entry existence without parsing and deletes a corrupt skill', async () => {
+    const root = await createTempRoot()
+    const directory = join(root, 'broken')
+    const storage = createFsSkillStorage({ root })
+    await mkdir(directory)
+    await writeFile(
+      join(directory, 'SKILL.md'),
+      ['---', 'name: broken', 'description: Broken skill', '---', ''].join('\n'),
+      'utf8',
+    )
+
+    await expect(storage.has('broken')).resolves.toBe(true)
+    await expect(storage.get('broken')).rejects.toThrow('must contain instructions')
+    await expect(storage.list()).rejects.toThrow('must contain instructions')
+    await expect(storage.delete('broken')).resolves.toBe(true)
+    await expect(storage.has('broken')).resolves.toBe(false)
+  })
+
+  it('lists summaries with exact resource counts without statting each resource', async () => {
+    const root = await createTempRoot()
+    const storage = createFsSkillStorage({ root })
+    await storage.add({
+      name: 'demo',
+      description: 'Demo skill',
+      instructions: '# Demo',
+      resources: [
+        {
+          path: 'guide.md',
+          kind: 'text',
+          resourceId: 'guide.md',
+          text: '# Guide',
+        },
+        {
+          path: 'references/nested.md',
+          kind: 'text',
+          resourceId: 'references/nested.md',
+          text: '# Nested',
+        },
+      ],
+    })
+    await mkdir(join(root, 'unrelated'))
+    vi.mocked(stat).mockClear()
+
+    await expect(storage.list()).resolves.toEqual([
+      {
+        name: 'demo',
+        description: 'Demo skill',
+        resourceCount: 2,
+        metadata: {},
+      },
+    ])
+    expect(stat).not.toHaveBeenCalled()
+  })
+
   it('lists existing skill directories, imports another skill, and deletes skills', async () => {
     const root = await createTempRoot()
     const weatherRoot = fileURLToPath(new URL('./.cache/weather', import.meta.url))