@lesliechan721/aw 0.1.0-beta.34 → 0.1.0-beta.36

package/dist/src/tui/plugin-content.js

@@ -1,9 +1,21 @@
 import path from 'node:path';
 import { open } from 'node:fs/promises';
+import { stripVTControlCharacters } from 'node:util';
 import fs from 'fs-extra';
+import YAML from 'yaml';
 import { parseSkillFrontmatter } from '../utils/skill-validation.js';
+import { resolveSupportedPlatforms } from '../utils/platform-support.js';
 const MAX_FRONTMATTER_BYTES = 16 * 1024;
 const TOOL_ORDER = ['Codex', 'Claude Code', 'Agent Skills'];
+function safeSummary(description, short) {
+    const safeDescription = stripVTControlCharacters(description)
+        .replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, ' ')
+        .replace(/\s+/gu, ' ').trim();
+    const sentence = short ? safeDescription
+        : safeDescription.match(/^.*?(?:[。！？]|[.!?](?=\s|$)|$)/u)?.[0] ?? safeDescription;
+    const points = [...sentence];
+    return points.length > 120 ? `${points.slice(0, 119).join('')}…` : sentence || null;
+}
 function sortTools(tools) {
     return [...new Set(tools)].sort((left, right) => TOOL_ORDER.indexOf(left) - TOOL_ORDER.indexOf(right));
 }
@@ -37,35 +49,164 @@ async function regularPathWithin(root, candidate, kind) {
     const real = await fs.realpath(lexical).catch(() => undefined);
     return real && within(root, real) ? real : null;
 }
+async function unconfirmedPathCode(root, candidate) {
+    const lexical = path.resolve(candidate);
+    if (!within(root, lexical))
+        return 'unsafePath';
+    let current = root;
+    for (const segment of path.relative(root, lexical).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = await fs.lstat(current);
+        }
+        catch (error) {
+            return error.code === 'ENOENT'
+                ? 'incompleteList' : 'unreadable';
+        }
+        if (stats.isSymbolicLink() || (!stats.isDirectory() && current !== lexical))
+            return 'unsafePath';
+    }
+    return 'unsafePath';
+}
 async function readFrontmatterDescription(root, skillFile) {
     const safeFile = await regularPathWithin(root, skillFile, 'file');
     if (!safeFile)
         return { exists: false, description: null };
-    const handle = await open(safeFile, 'r');
+    let handle;
+    try {
+        handle = await open(safeFile, 'r');
+    }
+    catch {
+        return { exists: true, description: null, issue: {
+                code: 'unreadable', message: '简介文件无法读取。请检查目录内容后重试。',
+            } };
+    }
     try {
         const chunks = [];
         let total = 0;
         let frontmatterEnd = -1;
+        let reachedEof = false;
         while (total < MAX_FRONTMATTER_BYTES && frontmatterEnd === -1) {
             const buffer = Buffer.alloc(Math.min(512, MAX_FRONTMATTER_BYTES - total));
             const { bytesRead } = await handle.read(buffer, 0, buffer.length, total);
-            if (bytesRead === 0)
+            if (bytesRead === 0) {
+                reachedEof = true;
                 break;
+            }
             chunks.push(buffer.subarray(0, bytesRead));
             total += bytesRead;
             frontmatterEnd = Buffer.concat(chunks).toString('utf8').replace(/\r\n/gu, '\n').indexOf('\n---\n', 4);
         }
-        if (frontmatterEnd === -1)
-            return { exists: true, description: null };
         const normalized = Buffer.concat(chunks).toString('utf8').replace(/\r\n/gu, '\n');
-        const header = normalized.slice(0, frontmatterEnd + '\n---\n'.length);
+        const closingAtEnd = frontmatterEnd === -1 && normalized.endsWith('\n---')
+            && (reachedEof || (await handle.stat()).size === total);
+        if (frontmatterEnd === -1 && !closingAtEnd)
+            return { exists: true, description: null, issue: {
+                    code: 'invalidMetadata', message: '简介元信息无效或超过读取预算。请检查内容文件。',
+                } };
+        const header = closingAtEnd ? normalized : normalized.slice(0, frontmatterEnd + '\n---\n'.length);
         const parsed = parseSkillFrontmatter(header, 'SKILL.md');
-        const description = parsed.frontmatter?.description;
+        if (parsed.errors.length > 0)
+            return { exists: true, description: null, issue: {
+                    code: 'invalidMetadata', message: '简介元信息无法解析。请检查内容文件。',
+                } };
+        const metadata = parsed.frontmatter?.metadata;
+        const short = isRecord(metadata) ? metadata['short-description'] : undefined;
+        if (short !== undefined && (typeof short !== 'string' || !short.trim())) {
+            return { exists: true, description: null, issue: {
+                    code: 'invalidMetadata', message: '简短用途元信息无效。请检查内容文件。',
+                } };
+        }
+        const description = typeof short === 'string' && short.trim()
+            ? short : parsed.frontmatter?.description;
+        if (description !== undefined && typeof description !== 'string') {
+            return { exists: true, description: null, issue: {
+                    code: 'invalidMetadata', message: '简介元信息类型无效。请检查内容文件。',
+                } };
+        }
         return {
             exists: true,
-            description: typeof description === 'string' && description.trim() ? description.trim() : null,
+            description: typeof description === 'string' ? safeSummary(description, Boolean(short)) : null,
         };
     }
+    catch {
+        return { exists: true, description: null, issue: {
+                code: 'unreadable', message: '简介文件无法读取。请检查目录内容后重试。',
+            } };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readCodexCommandDescription(root, skillRoot) {
+    const metadataFile = path.join(skillRoot, 'agents', 'openai.yaml');
+    const safeFile = await regularPathWithin(root, metadataFile, 'file');
+    if (!safeFile) {
+        const code = await unconfirmedPathCode(root, metadataFile);
+        return { description: null, issue: {
+                code, message: 'Slash command 简介文件不可安全确认。请检查内容目录。',
+            } };
+    }
+    let handle;
+    try {
+        handle = await open(safeFile, 'r');
+    }
+    catch {
+        return { description: null, issue: {
+                code: 'unreadable', message: 'Slash command 简介文件无法读取。请检查内容目录。',
+            } };
+    }
+    try {
+        const size = (await handle.stat()).size;
+        if (size > MAX_FRONTMATTER_BYTES)
+            return { description: null, issue: {
+                    code: 'invalidMetadata', message: 'Slash command 简介元信息超过读取预算。请检查内容文件。',
+                } };
+        const buffer = Buffer.alloc(size);
+        let total = 0;
+        while (total < size) {
+            const { bytesRead } = await handle.read(buffer, total, size - total, total);
+            if (bytesRead === 0)
+                return { description: null, issue: {
+                        code: 'unreadable', message: 'Slash command 简介文件无法完整读取。请检查内容目录。',
+                    } };
+            total += bytesRead;
+        }
+        let metadata;
+        try {
+            const document = YAML.parseDocument(buffer.toString('utf8'), { prettyErrors: false });
+            if (document.errors.length > 0)
+                throw new Error('Invalid YAML');
+            metadata = document.toJS({ maxAliasCount: 0 });
+        }
+        catch {
+            return { description: null, issue: {
+                    code: 'invalidMetadata', message: 'Slash command 简介元信息无法解析。请检查内容文件。',
+                } };
+        }
+        if (!isRecord(metadata) || (metadata.interface !== undefined && !isRecord(metadata.interface))) {
+            return { description: null, issue: {
+                    code: 'invalidMetadata', message: 'Slash command 简介元信息无效。请检查内容文件。',
+                } };
+        }
+        const short = isRecord(metadata.interface) ? metadata.interface.short_description : undefined;
+        if (short === undefined)
+            return { description: null };
+        if (typeof short !== 'string' || !short.trim())
+            return { description: null, issue: {
+                    code: 'invalidMetadata', message: 'Slash command 简短用途元信息无效。请检查内容文件。',
+                } };
+        const description = safeSummary(short, true);
+        return description ? { description } : { description: null, issue: {
+                code: 'invalidMetadata', message: 'Slash command 简短用途元信息无效。请检查内容文件。',
+            } };
+    }
+    catch {
+        return { description: null, issue: {
+                code: 'unreadable', message: 'Slash command 简介文件无法读取。请检查内容目录。',
+            } };
+    }
     finally {
         await handle.close();
     }
@@ -80,38 +221,108 @@ function addItem(items, item) {
     current.tools = sortTools([...current.tools, ...item.tools]);
     if (current.description === null && item.description !== null)
         current.description = item.description;
+    if (item.issue) {
+        current.descriptionState = 'issue';
+        current.issue = item.issue;
+    }
+    else if (current.descriptionState !== 'issue' && current.description !== null) {
+        current.descriptionState = 'available';
+    }
+}
+function addCoverageIssue(issues, issue) {
+    issues.push(issue);
 }
 async function addSkillDirectory(options) {
     const directory = await regularPathWithin(options.root, path.join(options.root, options.relativePath), 'directory');
     if (!directory) {
-        options.notices.push(`${options.tool} Skill 清单不可安全读取。`);
+        const code = await unconfirmedPathCode(options.root, path.join(options.root, options.relativePath));
+        addCoverageIssue(options.coverageIssues, {
+            code, message: `${options.tool} Skill 清单无法确认。请检查目录。`,
+        });
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        addCoverageIssue(options.coverageIssues, {
+            code: 'unreadable', message: `${options.tool} Skill 清单无法读取。请检查目录后重试。`,
+        });
         return;
     }
-    const entries = await fs.readdir(directory, { withFileTypes: true });
     for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-        if (!entry.isDirectory() || entry.isSymbolicLink())
+        if (entry.isSymbolicLink()) {
+            addCoverageIssue(options.coverageIssues, {
+                code: 'unsafePath', message: `${options.tool} Skill 清单含不安全路径。请检查目录。`,
+            });
+            continue;
+        }
+        if (!entry.isDirectory())
             continue;
         const skillRoot = await regularPathWithin(options.root, path.join(directory, entry.name), 'directory');
-        if (!skillRoot)
+        if (!skillRoot) {
+            const code = await unconfirmedPathCode(options.root, path.join(directory, entry.name));
+            addCoverageIssue(options.coverageIssues, {
+                code, message: `${options.tool} Skill 清单含无法确认的条目。请检查目录。`,
+            });
             continue;
-        const skill = await readFrontmatterDescription(options.root, path.join(skillRoot, 'SKILL.md'));
-        if (!skill.exists)
+        }
+        if (options.tool === 'Codex'
+            && options.items.get(`command:${entry.name}`)?.tools.includes('Codex'))
             continue;
+        const skillFile = path.join(skillRoot, 'SKILL.md');
+        const hasClaudeCommand = options.items.has(`command:${entry.name}`);
+        const hasClaudeSkill = options.checkClaudeCommand
+            && options.items.get(`skill:${entry.name}`)?.tools.includes('Claude Code')
+            && await regularPathWithin(options.root, path.join(options.root, 'claude', 'skills', entry.name, 'SKILL.md'), 'file');
+        const uncertainSource = options.checkClaudeCommand && !hasClaudeCommand && !hasClaudeSkill;
+        const skill = options.readDescription === false || (uncertainSource && options.type !== 'command')
+            ? { exists: Boolean(await regularPathWithin(options.root, skillFile, 'file')), description: null }
+            : await readFrontmatterDescription(options.root, skillFile);
+        let issue = skill.issue;
+        if (!skill.exists) {
+            const code = await unconfirmedPathCode(options.root, skillFile);
+            if (code === 'incompleteList') {
+                addCoverageIssue(options.coverageIssues, {
+                    code, message: `${options.tool} Skill 清单有无法确认的条目。请检查目录。`,
+                });
+                continue;
+            }
+            issue = { code, message: 'Skill 元信息文件不可安全读取。请检查内容目录后重试。' };
+        }
+        const type = options.type === 'command' && issue?.code === 'unsafePath'
+            ? 'skill' : options.type ?? 'skill';
+        if (uncertainSource) {
+            addCoverageIssue(options.coverageIssues, {
+                code: 'incompleteList',
+                message: options.type === 'command'
+                    ? 'Slash command 的 Claude Code 组件无法确认。请检查内容目录。'
+                    : 'Codex 内容名称已确认，但缺少可安全确认的 Claude Code 对应项，不能区分普通 Skill 与 Slash command。请检查内容目录。',
+            });
+        }
+        const command = type === 'command' && skill.exists
+            ? await readCodexCommandDescription(options.root, skillRoot) : undefined;
+        issue ??= command?.issue;
+        const description = command?.description ?? skill.description;
         addItem(options.items, {
-            id: `skill:${entry.name}`,
+            id: `${type}:${entry.name}`,
             name: entry.name,
-            type: 'skill',
-            description: skill.description,
+            type,
+            description,
             tools: [options.tool],
+            descriptionState: issue ? 'issue' : description ? 'available' : 'absent',
+            ...(issue ? { issue } : {}),
         });
-        if (skill.description === null)
-            options.notices.push(`Skill ${entry.name} 没有安全可读的简短用途。`);
     }
 }
 async function addJsonComponents(options) {
     const file = await regularPathWithin(options.root, path.join(options.root, options.relativePath), 'file');
     if (!file) {
-        options.notices.push(`${options.tool} ${options.type} 清单不可安全读取。`);
+        const code = await unconfirmedPathCode(options.root, path.join(options.root, options.relativePath));
+        addCoverageIssue(options.coverageIssues, {
+            code, message: `${options.tool} ${options.type} 清单无法确认。请检查目录。`,
+        });
         return;
     }
     let value;
@@ -119,14 +330,19 @@ async function addJsonComponents(options) {
         value = await fs.readJson(file);
     }
     catch {
-        options.notices.push(`${options.tool} ${options.type} 清单不可安全读取。`);
+        addCoverageIssue(options.coverageIssues, {
+            code: 'unreadable', message: `${options.tool} ${options.type} 清单无法读取。请检查内容文件。`,
+        });
         return;
     }
     const collection = isRecord(value) ? value[options.property] : undefined;
-    const entries = isRecord(collection) ? Object.keys(collection).sort() : [];
-    if (entries.length === 0) {
-        options.notices.push(`${options.tool} ${options.type} 清单没有可确认的组件名称。`);
+    if (!isRecord(collection)) {
+        addCoverageIssue(options.coverageIssues, {
+            code: 'incompleteList', message: `${options.tool} ${options.type} 清单格式无效。请检查内容文件。`,
+        });
+        return;
     }
+    const entries = Object.keys(collection).sort();
     for (const name of entries) {
         addItem(options.items, {
             id: `${options.type}:${name}`,
@@ -134,35 +350,83 @@ async function addJsonComponents(options) {
             type: options.type,
             description: null,
             tools: [options.tool],
+            descriptionState: 'absent',
         });
     }
 }
 async function addSlashCommands(options) {
     const directory = await regularPathWithin(options.root, path.join(options.root, 'claude', 'commands'), 'directory');
     if (!directory) {
-        options.notices.push('Slash command 清单没有可安全确认的组件名称。');
+        const code = await unconfirmedPathCode(options.root, path.join(options.root, 'claude', 'commands'));
+        addCoverageIssue(options.coverageIssues, {
+            code, message: 'Slash command 清单无法确认。请检查目录。',
+        });
+        return;
+    }
+    let entries;
+    try {
+        entries = await fs.readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        addCoverageIssue(options.coverageIssues, {
+            code: 'unreadable', message: 'Slash command 清单无法读取。请检查目录后重试。',
+        });
         return;
     }
-    const entries = await fs.readdir(directory, { withFileTypes: true });
     for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
-        if (!entry.isFile() || entry.isSymbolicLink() || path.extname(entry.name) !== '.md')
+        if (path.extname(entry.name) !== '.md')
             continue;
+        if (entry.isSymbolicLink() || !entry.isFile()) {
+            addCoverageIssue(options.coverageIssues, {
+                code: 'unsafePath', message: 'Slash command 清单含无法确认的条目。请检查目录。',
+            });
+            continue;
+        }
+        if (!await regularPathWithin(options.root, path.join(directory, entry.name), 'file')) {
+            addCoverageIssue(options.coverageIssues, {
+                code: 'unsafePath', message: 'Slash command 清单含不安全路径。请检查目录。',
+            });
+            continue;
+        }
         const name = path.basename(entry.name, '.md');
         const tools = ['Claude Code'];
         const codexSkillFile = path.join(options.root, 'codex', 'skills', name, 'SKILL.md');
         const codexCommand = options.hasCodex
             && await regularPathWithin(options.root, codexSkillFile, 'file');
+        if (options.hasCodex && !codexCommand) {
+            const code = await unconfirmedPathCode(options.root, codexSkillFile);
+            addCoverageIssue(options.coverageIssues, {
+                code, message: 'Slash command 的 Codex 组件无法安全确认。请检查内容目录。',
+            });
+        }
+        if (options.hasCodex && !codexCommand && await fs.lstat(codexSkillFile).catch(() => undefined)) {
+            if (await regularPathWithin(options.root, path.dirname(codexSkillFile), 'directory')) {
+                addItem(options.items, {
+                    id: `skill:${name}`,
+                    name,
+                    type: 'skill',
+                    description: null,
+                    tools: ['Codex'],
+                    descriptionState: 'issue',
+                    issue: { code: 'unsafePath', message: 'Skill 元信息文件不可安全读取。请检查内容目录后重试。' },
+                });
+            }
+        }
+        const command = await readFrontmatterDescription(options.root, path.join(directory, entry.name));
+        const codexDescription = codexCommand
+            ? await readCodexCommandDescription(options.root, path.dirname(codexSkillFile)) : undefined;
+        const description = codexDescription?.description ?? command.description;
+        const issue = codexDescription?.issue ?? command.issue;
         if (codexCommand)
             tools.unshift('Codex');
-        options.items.delete(`skill:${name}`);
         addItem(options.items, {
             id: `command:${name}`,
             name,
             type: 'command',
-            description: codexCommand
-                ? (await readFrontmatterDescription(options.root, codexSkillFile)).description
-                : null,
+            description,
             tools,
+            descriptionState: issue ? 'issue' : description ? 'available' : 'absent',
+            ...(issue ? { issue } : {}),
         });
     }
 }
@@ -202,35 +466,105 @@ async function projectedPlatforms(root) {
     return tools;
 }
 export async function projectPluginContentOverview(options) {
-    const root = await fs.realpath(options.plugin.rootDir);
+    let root;
+    try {
+        root = await fs.realpath(options.plugin.rootDir);
+    }
+    catch {
+        const message = '当前无法安全读取这个插件的目录内容。请检查来源状态后重试。';
+        return {
+            pluginId: options.pluginId,
+            pluginVersion: options.plugin.manifest.version,
+            catalogVersion: options.catalogVersion,
+            evidence: 'unavailable',
+            items: [],
+            notices: [message],
+            coverage: 'unavailable',
+            coverageIssue: { code: 'unreadable', message },
+        };
+    }
     const items = new Map();
-    const notices = [];
+    const coverageIssues = [];
     const platforms = await projectedPlatforms(root);
+    const supportedPlatforms = resolveSupportedPlatforms(options.plugin.manifest);
+    for (const [platform, tool] of [
+        ['codex', 'Codex'], ['claude', 'Claude Code'],
+    ]) {
+        if (!supportedPlatforms.has(platform) || platforms.includes(tool))
+            continue;
+        const marker = path.join(root, `.${platform}-plugin`, 'plugin.json');
+        const code = await unconfirmedPathCode(root, marker);
+        addCoverageIssue(coverageIssues, {
+            code, message: `${tool} 平台清单无法安全确认。请检查目录。`,
+        });
+    }
+    const codexOnlyCommands = Boolean(options.plugin.manifest.slashCommands)
+        && platforms.includes('Codex') && !platforms.includes('Claude Code');
+    const mixedCodexSkills = Boolean(options.plugin.manifest.slashCommands)
+        && platforms.includes('Codex')
+        && Boolean(options.plugin.manifest.skills || options.plugin.manifest.buildConfig?.fileRules?.codex);
+    if (mixedCodexSkills && codexOnlyCommands) {
+        addCoverageIssue(coverageIssues, {
+            code: 'incompleteList',
+            message: 'Codex 内容名称已确认，但当前目录不能安全区分普通 Skill 与 Slash command。请查看来源定义。',
+        });
+    }
+    if (options.plugin.manifest.slashCommands && platforms.includes('Claude Code')) {
+        await addSlashCommands({
+            root,
+            hasCodex: platforms.includes('Codex'),
+            items,
+            coverageIssues,
+        });
+    }
     if (options.plugin.manifest.skills) {
-        await Promise.all([
-            ...(platforms.includes('Codex') ? [addSkillDirectory({
-                    root, relativePath: 'codex/skills', tool: 'Codex', items, notices,
-                })] : []),
-            ...(platforms.includes('Claude Code') ? [addSkillDirectory({
-                    root, relativePath: 'claude/skills', tool: 'Claude Code', items, notices,
-                })] : []),
-        ]);
+        if (platforms.includes('Claude Code')) {
+            await addSkillDirectory({
+                root, relativePath: 'claude/skills', tool: 'Claude Code', items, coverageIssues,
+            });
+        }
+        if (platforms.includes('Codex')) {
+            await addSkillDirectory({
+                root, relativePath: 'codex/skills', tool: 'Codex', items, coverageIssues,
+                ...(codexOnlyCommands ? { readDescription: false } : {}),
+                checkClaudeCommand: Boolean(options.plugin.manifest.slashCommands)
+                    && platforms.includes('Claude Code'),
+            });
+        }
+    }
+    if (codexOnlyCommands && !options.plugin.manifest.skills) {
+        await addSkillDirectory({
+            root, relativePath: 'codex/skills', tool: 'Codex', items, coverageIssues,
+            type: mixedCodexSkills ? 'skill' : 'command',
+            readDescription: false,
+        });
+    }
+    if (options.plugin.manifest.slashCommands && platforms.includes('Codex')
+        && platforms.includes('Claude Code') && !options.plugin.manifest.skills) {
+        await addSkillDirectory({
+            root, relativePath: 'codex/skills', tool: 'Codex', items, coverageIssues,
+            type: mixedCodexSkills ? 'skill' : 'command',
+            readDescription: false,
+            checkClaudeCommand: true,
+        });
     }
     if (options.plugin.manifest.distributions?.agentSkills?.skills) {
         await addSkillDirectory({
-            root, relativePath: 'agent-skills/skills', tool: 'Agent Skills', items, notices,
+            root, relativePath: 'agent-skills/skills', tool: 'Agent Skills', items, coverageIssues,
         });
     }
     if (options.plugin.manifest.mcpServers) {
-        await Promise.all(platforms.map((tool) => addJsonComponents({
-            root,
-            relativePath: `${tool === 'Codex' ? 'codex' : 'claude'}/${options.plugin.manifest.mcpServers.replace(/^\.\//u, '')}`,
-            property: 'mcpServers',
-            type: 'mcpServer',
-            tool,
-            items,
-            notices,
-        })));
+        for (const tool of platforms) {
+            await addJsonComponents({
+                root,
+                relativePath: `${tool === 'Codex' ? 'codex' : 'claude'}/${options.plugin.manifest.mcpServers.replace(/^\.\//u, '')}`,
+                property: 'mcpServers',
+                type: 'mcpServer',
+                tool,
+                items,
+                coverageIssues,
+            });
+        }
     }
     if (options.plugin.manifest.apps && platforms.includes('Codex')) {
         await addJsonComponents({
@@ -240,15 +574,7 @@ export async function projectPluginContentOverview(options) {
             type: 'app',
             tool: 'Codex',
             items,
-            notices,
-        });
-    }
-    if (options.plugin.manifest.slashCommands) {
-        await addSlashCommands({
-            root,
-            hasCodex: platforms.includes('Codex'),
-            items,
-            notices,
+            coverageIssues,
         });
     }
     for (const agent of options.plugin.manifest.extensions?.agents ?? []) {
@@ -258,6 +584,7 @@ export async function projectPluginContentOverview(options) {
             type: 'agent',
             description: agent.description.trim() || null,
             tools: toolsForOverrides(platforms, agent.agentOverrides),
+            descriptionState: agent.description.trim() ? 'available' : 'absent',
         });
     }
     for (const instruction of options.plugin.manifest.extensions?.instructions ?? []) {
@@ -267,6 +594,7 @@ export async function projectPluginContentOverview(options) {
             type: 'instruction',
             description: null,
             tools: toolsForOverrides(platforms, instruction.agentOverrides),
+            descriptionState: 'absent',
         });
     }
     for (const permission of options.plugin.manifest.extensions?.permissions ?? []) {
@@ -276,6 +604,7 @@ export async function projectPluginContentOverview(options) {
             type: 'permission',
             description: null,
             tools: toolsForOverrides(platforms, permission.agentOverrides),
+            descriptionState: 'absent',
         });
     }
     for (const hook of options.plugin.manifest.extensions?.hooks ?? []) {
@@ -286,6 +615,7 @@ export async function projectPluginContentOverview(options) {
             type: 'hook',
             description: null,
             tools: toolsForOverrides(platforms, hook.agentOverrides),
+            descriptionState: 'absent',
         });
     }
     for (const [platform, hooks] of Object.entries(options.plugin.manifest.extensions?.nativeHooks ?? {})) {
@@ -298,6 +628,7 @@ export async function projectPluginContentOverview(options) {
                 type: 'hook',
                 description: null,
                 tools: [tool],
+                descriptionState: 'absent',
             });
         }
     }
@@ -308,8 +639,18 @@ export async function projectPluginContentOverview(options) {
             continue;
         const name = target.skillKey ?? target.roleKey ?? target.id;
         let description = null;
+        let issue;
         if (type === 'skill' && target.platform) {
-            description = (await readFrontmatterDescription(root, path.join(root, '.agents-plugin', 'artifact-sources', target.platform, target.id, '0', 'SKILL.md'))).description;
+            const skill = await readFrontmatterDescription(root, path.join(root, '.agents-plugin', 'artifact-sources', target.platform, target.id, '0', 'SKILL.md'));
+            description = skill.description;
+            issue = skill.issue;
+            if (!skill.exists) {
+                const code = await unconfirmedPathCode(root, path.join(root, '.agents-plugin', 'artifact-sources', target.platform, target.id, '0', 'SKILL.md'));
+                if (code !== 'incompleteList')
+                    issue = {
+                        code, message: '简介文件不可安全读取。请检查内容目录。',
+                    };
+            }
         }
         addItem(items, {
             id: `artifact:${target.id}`,
@@ -317,20 +658,23 @@ export async function projectPluginContentOverview(options) {
             type,
             description,
             tools: [tool],
+            descriptionState: issue ? 'issue' : description ? 'available' : 'absent',
+            ...(issue ? { issue } : {}),
         });
-        if (description === null)
-            notices.push(`${type} ${name} 没有安全可读的简短用途。`);
     }
     const result = [...items.values()].sort((left, right) => left.type.localeCompare(right.type) || left.name.localeCompare(right.name));
-    if (result.length === 0)
-        notices.push('此目录版本没有可安全确认的内容清单。');
+    const coverage = coverageIssues.length === 0
+        ? 'complete' : result.length > 0 ? 'partial' : 'unavailable';
+    const notices = [...new Set(coverageIssues.map((issue) => issue.message))];
     return {
         pluginId: options.pluginId,
         pluginVersion: options.plugin.manifest.version,
         catalogVersion: options.catalogVersion,
         evidence: 'catalogBundle',
         items: result,
-        notices: [...new Set(notices)],
+        notices,
+        coverage,
+        ...(coverageIssues[0] ? { coverageIssue: coverageIssues[0] } : {}),
     };
 }
 //# sourceMappingURL=plugin-content.js.map