dsh-hyperframes 0.2.0 → 0.3.1

package/README.en.md

@@ -1,14 +1,16 @@
 [中文](README.md)
 
+![npm](https://img.shields.io/npm/v/dsh-hyperframes) ![downloads](https://img.shields.io/npm/dm/dsh-hyperframes) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-hyperframes) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-hyperframes?style=social)
+
 # dsh-hyperframes
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DSH (DeepSeek Harness) video-creation skill plugin: installing it registers the five official HyperFrames by HeyGen skills into DSH (video from HTML: compositions, GSAP animation, captions, voiceovers, audio-reactive visuals, website-to-video).
+DSH (DeepSeek Harness) video-creation skill plugin: installing it registers the twenty official HyperFrames by HeyGen skills into DSH (video from HTML: core workflow, animation, audio, captions, keyframes, creative templates, CLI, registry, website-to-video; synced with official v0.8.20).
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Aligned with the skill registration contract of `@deepseek-ai/dsh@0.1.3-alpha.1` (2026-09-05). Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -31,11 +33,26 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 
 | Skill | Purpose |
 | :-- | :-- |
-| `hyperframes` | HTML video compositions: visual styles/palettes/captions/audio-reactive/transitions |
+| `hyperframes` | Router: HTML video compositions (styles/palettes/captions/audio-reactive/transitions) |
+| `hyperframes-core` | Core concepts and component model |
+| `hyperframes-animation` | Animation: GSAP/Anime.js/Lottie/Three.js/WAAPI adapters |
+| `hyperframes-audio` | Audio: voiceovers, audio-reactive visuals |
+| `hyperframes-keyframes` | Keyframe animation |
+| `hyperframes-creative` | Creative templates and styles |
 | `hyperframes-cli` | `npx hyperframes` CLI (init/lint/inspect/preview/render/transcribe/tts/doctor) |
 | `hyperframes-registry` | `hyperframes add` registry block installation and wiring |
-| `website-to-hyperframes` | Seven-step website-to-video pipeline |
-| `gsap` | GSAP animation API reference (tweens/timelines/easing/performance) |
+| `embedded-captions` | Embedded captions |
+| `faceless-explainer` | Faceless explainer videos |
+| `figma` | Figma asset integration |
+| `general-video` | General video production |
+| `media-use` | Media usage guidelines |
+| `motion-graphics` | Motion graphics |
+| `music-to-video` | Music-driven video |
+| `pr-to-video` | PR-to-video |
+| `product-launch-video` | Product launch videos |
+| `remotion-to-hyperframes` | Remotion project migration |
+| `slideshow` | Slideshow videos |
+| `talking-head-recut` | Talking-head recuts |
 
 ## Requirements
 
@@ -59,6 +76,35 @@ Skills use the open Agent Skills (SKILL.md) format — **not just DSH**. Copy th
 Port once, use everywhere.
 
 
+## Health checks and reloads
+
+`hyperframes_health` rereads every `SKILL.md`, verifies readable files, valid YAML frontmatter, names matching their directories, and nonempty descriptions/bodies, then queries the host's `skills.get`. The effective name, description, body and resource directory must match this plugin instance's loaded snapshot. Existing files alone do not prove successful or still-active registration.
+
+Health checks do not mutate files or registrations. After changing a file or repairing one that failed initial loading, reload the plugin (or restart DSH). The result reports `changed`, `not_registered` or `registration_failed` until then. A previously loaded file that was temporarily missing becomes healthy again if its exact original content is restored and its registration remains active.
+
+Each item retains `name / ok / detail` and adds `code / fileOk / registered / registryChecked / reloadRequired`. `registered` means the registry still matches the loaded version, so a changed file can have `registered: true` and `ok: false`. Missing or failed registry lookup produces `registry_unavailable`; a disposed plugin produces `disposed`. The public `checkBundledSkills()` is disk-only, while the original non-throwing `parseSkillFile()` helper remains available.
+
+## Development and shared implementation
+
+`src/index.ts` declares only package identity, skill names and the resource directory. Parsing, validation, registration and health logic live in `src/skill-bundle.ts`. The canonical source is in `dsh-hyperframes`; Remotion carries an identical version-controlled copy. Each package builds and ships its own `lib/skill-bundle.js`, with no cross-package runtime dependency and no sibling checkout required for building or installation.
+
+With dependencies already installed:
+
+```bash
+node node_modules/typescript/bin/tsc -p tsconfig.json
+node --test "test/*.test.mjs"
+```
+
+When developing the sibling repositories together, edit the shared module and regression tests in HyperFrames, then synchronize:
+
+```bash
+# Run in dsh-hyperframes; updates only three shared files in sibling dsh-remotion
+node scripts/sync-skill-bundle.mjs
+node scripts/sync-skill-bundle.mjs --check
+```
+
+Both suites compare shared source and regression tests to prevent drift. A standalone checkout skips only that cross-repository comparison. Tests cover invalid YAML, unreadable files, empty bodies, rejected/inactive registrations, file changes and repairs, disposal races and cleanup failures, without invoking video or speech services.
+
 ## License
 
-MIT for the porting arrangement; skill content copyright remains with HeyGen.
+MIT for the porting arrangement; skill content copyright remains with HeyGen.

package/README.md

@@ -2,18 +2,18 @@
 
 # dsh-hyperframes
 
-> **在 20+ 个 agent 里写视频**：HyperFrames by HeyGen 五件套，HTML 即视频。
+> **在 20+ 个 agent 里写视频**：HyperFrames by HeyGen 官方 20 技能，HTML 即视频。
 
 ![npm version](https://img.shields.io/npm/v/dsh-hyperframes?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-hyperframes) ![license](https://img.shields.io/npm/l/dsh-hyperframes) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-hyperframes?style=social)
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
 
-DSH（DeepSeek Harness）视频创作技能插件：**安装即把 HyperFrames by HeyGen 官方移植技能五件套注册进 DSH**（HTML 写视频：合成、GSAP 动画、字幕、配音、音频响应、网址转视频）。
+DSH（DeepSeek Harness）视频创作技能插件：**安装即把 HyperFrames by HeyGen 官方 20 个技能注册进 DSH**（HTML 写视频：核心工作流、动画、音频、字幕、关键帧、创意模板、CLI、注册表、网站转视频等，同步官方 v0.8.20）。
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+对齐 `@deepseek-ai/dsh@0.1.3-alpha.1` 的技能注册契约（2026-09-05）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -36,11 +36,26 @@ dsh plugin --profile web remove dsh-hyperframes
 
 | 技能 | 用途 |
 | :-- | :-- |
-| `hyperframes` | HTML 视频合成：视觉风格/调色板/字幕/音频响应/转场 |
+| `hyperframes` | 总纲：HTML 视频合成（视觉风格/调色板/字幕/音频响应/转场）|
+| `hyperframes-core` | 核心概念与组件模型 |
+| `hyperframes-animation` | 动画：GSAP/Anime.js/Lottie/Three.js/WAAPI 适配 |
+| `hyperframes-audio` | 音频：配音、音频响应视觉 |
+| `hyperframes-keyframes` | 关键帧动画 |
+| `hyperframes-creative` | 创意模板与风格 |
 | `hyperframes-cli` | `npx hyperframes` 命令行（init/lint/inspect/preview/render/transcribe/tts/doctor）|
 | `hyperframes-registry` | `hyperframes add` 注册表组件安装与接线 |
-| `website-to-hyperframes` | 网址转视频七步流水线 |
-| `gsap` | GSAP 动画 API 参考（tween/timeline/缓动/性能）|
+| `embedded-captions` | 内嵌字幕 |
+| `faceless-explainer` | 无脸讲解视频 |
+| `figma` | Figma 素材接入 |
+| `general-video` | 通用视频制作 |
+| `media-use` | 媒体素材使用规范 |
+| `motion-graphics` | 动态图形 |
+| `music-to-video` | 音乐驱动视频 |
+| `pr-to-video` | PR 转视频 |
+| `product-launch-video` | 产品发布视频 |
+| `remotion-to-hyperframes` | Remotion 项目迁移 |
+| `slideshow` | 幻灯片视频 |
+| `talking-head-recut` | 口播重剪 |
 
 ## 依赖
 
@@ -48,7 +63,7 @@ Node.js ≥ 22 + FFmpeg（`npx hyperframes`）。
 
 ## 移植说明
 
-技能移植自 OpenAI Codex 官方 HyperFrames by HeyGen 插件缓存：frontmatter 已转换为 DSH 格式，codex 专属 `agents/` 已剔除，全部内部引用校验。
+技能同步自官方仓库 `heygen-com/hyperframes` v0.8.20（2026-08-31）：官方 codex 插件打包的完整 `skills/` 目录；旧版五件套中的 `gsap`、`website-to-hyperframes` 已被上游合并进新技能体系。
 
 ## 跨平台使用
 
@@ -64,6 +79,35 @@ Node.js ≥ 22 + FFmpeg（`npx hyperframes`）。
 一次移植，处处可用。
 
 
+## 技能自检与重载
+
+运行 `hyperframes_health` 会重新读取每个 `SKILL.md`，验证文件可读、YAML frontmatter 合法、名称与目录一致、描述与正文非空，再通过宿主 `skills.get` 确认实际生效的名称、描述、正文和资源目录与本次加载内容相符。文件存在但未注册、注册失败或后来被移除时，自检都会失败。
+
+自检不修改文件或注册表。修改技能文件，或修复加载时损坏的技能后，应重载插件（也可重启 DSH）。它会报告 `changed`、`not_registered` 或 `registration_failed`，不会把磁盘修复直接当成运行时修复。若原先已成功加载，只是文件暂时丢失，恢复与加载时完全相同的内容即可重新通过检查。
+
+每项结果保留 `name / ok / detail`，并增加 `code / fileOk / registered / registryChecked / reloadRequired`：`registered` 表示注册表仍匹配加载时的版本，因此文件变更时它可以为 true 而 `ok` 为 false。缺少或无法查询宿主注册表时返回 `registry_unavailable`；插件卸载后返回 `disposed`。`checkBundledSkills()` 仅检查磁盘文件，不推断运行时状态；原有不抛错的 `parseSkillFile()` 解析入口保持可用。
+
+## 开发与共享实现
+
+`src/index.ts` 只声明包名、技能清单和目录，解析、校验、注册与自检集中在包内 `src/skill-bundle.ts`。规范源位于 `dsh-hyperframes/src/skill-bundle.ts`，Remotion 保存相同的受版本控制副本；两包都编译并分发自己的 `lib/skill-bundle.js`，没有跨包运行时依赖，也不需要另一个仓库即可构建或安装。
+
+依赖预先安装后，可直接离线构建和测试：
+
+```bash
+node node_modules/typescript/bin/tsc -p tsconfig.json
+node --test "test/*.test.mjs"
+```
+
+两个仓库并列开发时，在 HyperFrames 修改公共模块与公共回归测试，再同步：
+
+```bash
+# 在 dsh-hyperframes 中执行；只更新相邻 dsh-remotion 的三个公共文件
+node scripts/sync-skill-bundle.mjs
+node scripts/sync-skill-bundle.mjs --check
+```
+
+两包测试都会检查公共源码与回归测试是否一致，防止副本漂移；单独检出时只跳过跨仓库比对，其余测试正常运行。测试覆盖损坏 YAML、不可读文件、空正文、注册异常/失效、内容变更与修复、卸载及清理异常，全程不调用视频或语音服务。
+
 ## License
 
 MIT（移植编排）；技能内容版权归 HeyGen。

package/lib/index.d.ts

@@ -1,45 +1,12 @@
-/** cordis 服务注入：apply 里要用 ctx.skills，必须显式声明。 */
+import { type SkillsPluginContext } from './skill-bundle.js';
+export { parseSkillFile } from './skill-bundle.js';
+export type { SkillRegistration, SkillsPluginContext } from './skill-bundle.js';
 export declare const name = "hyperframes-skills";
 export declare const inject: string[];
-/** 技能注册定义（最小面）。 */
-export interface SkillRegistration {
-    name: string;
-    description: string;
-    content: string;
-    resourceBase: {
-        kind: 'directory';
-        path: string;
-    };
-    source?: string;
-}
-/** 插件所需的最小 ctx 面。 */
-export interface SkillsPluginContext {
-    skills: {
-        register(definition: SkillRegistration): () => void;
-    };
-    tools?: {
-        register(definition: Record<string, unknown>): () => void;
-    };
-    on?(event: string, listener: () => void): () => void;
-}
-/** 随包分发的技能清单。 */
-export declare const SKILL_NAMES: readonly ["hyperframes", "hyperframes-cli", "hyperframes-registry", "website-to-hyperframes", "gsap"];
-/** 打包技能目录的绝对路径。 */
+export declare const SKILL_NAMES: readonly ["embedded-captions", "faceless-explainer", "figma", "general-video", "hyperframes", "hyperframes-animation", "hyperframes-audio", "hyperframes-cli", "hyperframes-core", "hyperframes-creative", "hyperframes-keyframes", "hyperframes-registry", "media-use", "motion-graphics", "music-to-video", "pr-to-video", "product-launch-video", "remotion-to-hyperframes", "slideshow", "talking-head-recut"];
+/** Absolute resource root shipped in this independently installable package. */
 export declare function bundledSkillsDir(): string;
-/** 检查随包技能资源完整性：每个技能的 SKILL.md 是否存在。 */
-export declare function checkBundledSkills(): Array<{
-    name: string;
-    ok: boolean;
-    detail: string;
-}>;
-/** 拆分 SKILL.md 的 frontmatter 与正文。 */
-export declare function parseSkillFile(text: string): {
-    name: string;
-    description: string;
-    content: string;
-};
-/**
- * 插件入口：把技能注册进技能注册表。
- * 单个技能文件缺失只告警，不影响其余技能与宿主启动。
- */
+/** Re-read and validate disk resources; runtime state is checked by the health tool. */
+export declare function checkBundledSkills(): import("./skill-bundle.js").SkillFileCheck[];
+/** Register this package's skills and its read-only health tool. */
 export declare function apply(ctx: SkillsPluginContext): void;

package/lib/index.js

@@ -1,107 +1,46 @@
 /**
- * dsh-hyperframes —— HyperFrames by HeyGen 视频创作技能插件：加载即把技能注册进 ctx.skills。
- *
- * 技能正文与资源随包分发（skills/ 目录），resourceBase 指向打包目录，
- * 技能正文里的相对引用（rules/、references/ 等）由技能加载器解析。
- *
- * @module dsh-hyperframes
+ * dsh-hyperframes: packaged video skills with disk and registry health checks.
+ * The portable implementation lives in skill-bundle.ts; this entry only
+ * supplies the package identity, skill names and resource directory.
  */
-import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { join } from 'node:path';
-import YAML from 'yaml';
-/** cordis 服务注入：apply 里要用 ctx.skills，必须显式声明。 */
+import { createSkillBundle } from './skill-bundle.js';
+export { parseSkillFile } from './skill-bundle.js';
 export const name = 'hyperframes-skills';
 export const inject = ['skills', 'tools'];
-/** 随包分发的技能清单。 */
-export const SKILL_NAMES = ["hyperframes", "hyperframes-cli", "hyperframes-registry", "website-to-hyperframes", "gsap"];
-/** 打包技能目录的绝对路径。 */
+export const SKILL_NAMES = [
+    "embedded-captions",
+    "faceless-explainer",
+    "figma",
+    "general-video",
+    "hyperframes",
+    "hyperframes-animation",
+    "hyperframes-audio",
+    "hyperframes-cli",
+    "hyperframes-core",
+    "hyperframes-creative",
+    "hyperframes-keyframes",
+    "hyperframes-registry",
+    "media-use",
+    "motion-graphics",
+    "music-to-video",
+    "pr-to-video",
+    "product-launch-video",
+    "remotion-to-hyperframes",
+    "slideshow",
+    "talking-head-recut",
+];
+/** Absolute resource root shipped in this independently installable package. */
 export function bundledSkillsDir() {
     return fileURLToPath(new URL('../skills/', import.meta.url));
 }
-/** 检查随包技能资源完整性：每个技能的 SKILL.md 是否存在。 */
-export function checkBundledSkills() {
-    return SKILL_NAMES.map((skillName) => {
-        const file = join(bundledSkillsDir(), skillName, 'SKILL.md');
-        const ok = existsSync(file);
-        return { name: skillName, ok, detail: ok ? file : 'SKILL.md 缺失：' + file };
-    });
-}
-/** 拆分 SKILL.md 的 frontmatter 与正文。 */
-export function parseSkillFile(text) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
-    if (!match)
-        return { name: '', description: '', content: text };
-    let name = '';
-    let description = '';
-    try {
-        const parsed = YAML.parse(match[1]);
-        if (typeof parsed === 'object' && parsed !== null) {
-            const record = parsed;
-            if (typeof record.name === 'string')
-                name = record.name;
-            if (typeof record.description === 'string')
-                description = record.description;
-        }
-    }
-    catch { /* 保留空值，由调用方处理 */ }
-    return { name, description, content: text.slice(match[0].length).trimStart() };
-}
-/**
- * 插件入口：把技能注册进技能注册表。
- * 单个技能文件缺失只告警，不影响其余技能与宿主启动。
- */
-export function apply(ctx) {
-    const disposers = [];
-    for (const skillName of SKILL_NAMES) {
-        try {
-            const dir = join(bundledSkillsDir(), skillName);
-            const text = readFileSync(join(dir, 'SKILL.md'), 'utf8');
-            const parsed = parseSkillFile(text);
-            if (parsed.name === '' || parsed.description === '' || parsed.content === '') {
-                console.warn('[dsh-hyperframes] 技能 ' + skillName + ' 的 frontmatter 不完整，已跳过。');
-                continue;
-            }
-            disposers.push(ctx.skills.register({
-                name: parsed.name,
-                description: parsed.description,
-                content: parsed.content,
-                resourceBase: { kind: 'directory', path: dir },
-                source: 'runtime',
-            }));
-        }
-        catch (error) {
-            console.warn('[dsh-hyperframes] 技能 ' + skillName + ' 加载失败：' + (error instanceof Error ? error.message : String(error)));
-        }
-    }
-    if (typeof ctx.tools?.register === 'function') {
-        disposers.push(ctx.tools.register({
-            name: 'hyperframes_health',
-            description: 'dsh-hyperframes 自检：检查随包技能资源（SKILL.md）是否完整。遇到问题时先运行本工具定位。',
-            parameters: { type: 'object', properties: {} },
-            output: {
-                schema: { type: 'object', additionalProperties: true },
-                render(_args, value) {
-                    const rec = (value ?? {});
-                    const skills = Array.isArray(rec.skills) ? rec.skills : [];
-                    const lines = ['dsh-hyperframes 自检' + (rec.ok === true ? '：技能资源完整。' : '：发现缺失。')];
-                    for (const item of skills) {
-                        const s = (item ?? {});
-                        lines.push('- ' + String(s.name) + '：' + (s.ok === true ? '✅' : '❌ ' + String(s.detail ?? '')));
-                    }
-                    return [{ type: 'text', text: lines.join('\n') }];
-                },
-            },
-            async execute() {
-                const skills = checkBundledSkills();
-                return { ok: skills.every((s) => s.ok), plugin: 'dsh-hyperframes', skills };
-            },
-        }));
-    }
-    if (typeof ctx.on === 'function') {
-        ctx.on('dispose', () => {
-            for (const dispose of disposers)
-                dispose();
-        });
-    }
-}
+const bundle = createSkillBundle({
+    plugin: 'dsh-hyperframes',
+    healthTool: 'hyperframes_health',
+    names: SKILL_NAMES,
+    directory: bundledSkillsDir,
+});
+/** Re-read and validate disk resources; runtime state is checked by the health tool. */
+export function checkBundledSkills() { return bundle.checkFiles(); }
+/** Register this package's skills and its read-only health tool. */
+export function apply(ctx) { bundle.apply(ctx); }

package/lib/skill-bundle.d.ts

@@ -0,0 +1,56 @@
+export interface SkillRegistration {
+    name: string;
+    description: string;
+    content: string;
+    resourceBase: {
+        kind: 'directory';
+        path: string;
+    };
+    source?: string;
+}
+export interface SkillsPluginContext {
+    skills: {
+        register(definition: SkillRegistration): () => void;
+        get?(name: string): Promise<SkillRegistration | undefined> | SkillRegistration | undefined;
+    };
+    tools?: {
+        register(definition: Record<string, unknown>): () => void;
+    };
+    on?(event: string, listener: () => void): (() => void) | void;
+    logger?: {
+        warn(message: string): void;
+    };
+}
+export interface ParsedSkillFile {
+    name: string;
+    description: string;
+    content: string;
+}
+export interface SkillFileCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+    file: string;
+    code: 'valid' | 'unreadable' | 'invalid';
+}
+export interface SkillHealthCheck extends Omit<SkillFileCheck, 'code'> {
+    code: SkillFileCheck['code'] | 'ready' | 'not_registered' | 'registration_failed' | 'changed' | 'inactive' | 'registry_unavailable' | 'disposed';
+    fileOk: boolean;
+    registered: boolean;
+    registryChecked: boolean;
+    reloadRequired: boolean;
+}
+export interface SkillBundleOptions {
+    plugin: string;
+    healthTool: string;
+    names: readonly string[];
+    directory: () => string;
+}
+/** Preserve the original non-throwing public parsing helper and return shape. */
+export declare function parseSkillFile(text: string): ParsedSkillFile;
+/** File validation is shared by initial loading and every later health call. */
+export declare function createSkillBundle(options: SkillBundleOptions): {
+    /** Disk-only check; does not imply that any plugin instance registered the skills. */
+    checkFiles(): SkillFileCheck[];
+    apply(ctx: SkillsPluginContext): void;
+};

package/lib/skill-bundle.js

@@ -0,0 +1,218 @@
+/**
+ * Portable skill-bundle implementation. Canonical source: dsh-hyperframes.
+ * dsh-remotion vendors this exact file; scripts/sync-skill-bundle.mjs and
+ * test/shared-source.test.mjs prevent drift without a runtime dependency.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import YAML from 'yaml';
+// Matches Harness 0.1.3-alpha.1's public skill-name grammar.
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function message(error) { return error instanceof Error ? error.message : String(error); }
+/** One parser for the public helper, disk validation and runtime registration. */
+function analyze(text) {
+    const match = /^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+    const parsed = { name: '', description: '', content: match ? text.slice(match[0].length).trimStart() : text };
+    if (!match)
+        return { parsed, error: '缺少完整的 YAML frontmatter（--- 分隔行）。' };
+    try {
+        const doc = YAML.parseDocument(match[1], { prettyErrors: false, uniqueKeys: true });
+        if (doc.errors.length || doc.warnings.length)
+            throw new Error([...doc.errors, ...doc.warnings].map((error) => error.message).join('; '));
+        const value = doc.toJS({ maxAliasCount: 100 });
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return { parsed, error: 'frontmatter 必须是 YAML 对象。' };
+        const fields = value;
+        if (typeof fields.name === 'string')
+            parsed.name = fields.name;
+        if (typeof fields.description === 'string')
+            parsed.description = fields.description;
+    }
+    catch (error) {
+        return { parsed, error: 'frontmatter YAML 无效：' + message(error) };
+    }
+    if (!SKILL_NAME.test(parsed.name))
+        return { parsed, error: 'name 必须为非空小写 kebab-case 名称。' };
+    if (!parsed.description.trim())
+        return { parsed, error: 'description 必须为非空字符串。' };
+    if (!parsed.content.trim())
+        return { parsed, error: '技能正文为空。' };
+    return { parsed };
+}
+/** Preserve the original non-throwing public parsing helper and return shape. */
+export function parseSkillFile(text) { return analyze(text).parsed; }
+function inspect(directory, name) {
+    const file = join(directory, name, 'SKILL.md');
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return { check: { name, file, ok: false, code: 'unreadable', detail: 'SKILL.md 不可读取：' + message(error) } };
+    }
+    const result = analyze(text);
+    const error = result.error ?? (result.parsed.name === name ? undefined : 'frontmatter name 与技能目录名称不一致：' + result.parsed.name);
+    if (error)
+        return { check: { name, file, ok: false, code: 'invalid', detail: error } };
+    return {
+        check: { name, file, ok: true, code: 'valid', detail: file },
+        parsed: result.parsed,
+        fingerprint: createHash('sha256').update(text).digest('hex'),
+    };
+}
+function matches(actual, expected) {
+    return actual !== undefined && actual.name === expected.name && actual.description === expected.description
+        && actual.content === expected.content && actual.resourceBase?.kind === 'directory'
+        && resolve(actual.resourceBase.path) === resolve(expected.resourceBase.path);
+}
+/** File validation is shared by initial loading and every later health call. */
+export function createSkillBundle(options) {
+    const names = [...options.names];
+    if (new Set(names).size !== names.length || names.some((name) => !SKILL_NAME.test(name)))
+        throw new Error('Skill bundle requires unique kebab-case directory names');
+    const inspectAll = () => names.map((name) => inspect(resolve(options.directory()), name));
+    return {
+        /** Disk-only check; does not imply that any plugin instance registered the skills. */
+        checkFiles() { return inspectAll().map((result) => result.check); },
+        apply(ctx) {
+            const registrations = new Map();
+            const disposers = [];
+            let disposed = false;
+            const warn = (detail) => {
+                const text = '[' + options.plugin + '] ' + detail;
+                if (ctx.logger?.warn)
+                    ctx.logger.warn(text);
+                else
+                    console.warn(text);
+            };
+            const dispose = () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                for (const remove of disposers.splice(0).reverse()) {
+                    try {
+                        remove();
+                    }
+                    catch (error) {
+                        warn('卸载失败：' + message(error));
+                    }
+                }
+            };
+            ctx.on?.('dispose', dispose);
+            for (const result of inspectAll()) {
+                const registration = {};
+                registrations.set(result.check.name, registration);
+                if (!result.parsed || !result.fingerprint) {
+                    warn(result.check.name + '：' + result.check.detail);
+                    continue;
+                }
+                const definition = {
+                    ...result.parsed,
+                    resourceBase: { kind: 'directory', path: join(resolve(options.directory()), result.check.name) },
+                    source: 'runtime',
+                };
+                try {
+                    const remove = ctx.skills.register(definition);
+                    if (typeof remove !== 'function')
+                        throw new Error('skills.register 未返回卸载函数。');
+                    disposers.push(remove);
+                    registration.definition = definition;
+                    registration.fingerprint = result.fingerprint;
+                }
+                catch (error) {
+                    registration.error = message(error);
+                    warn(result.check.name + ' 注册失败：' + registration.error);
+                }
+            }
+            const health = async () => {
+                const skills = [];
+                for (const result of inspectAll()) {
+                    const registration = registrations.get(result.check.name);
+                    let registered = false;
+                    let registryChecked = false;
+                    let registryError;
+                    if (!disposed && registration.definition) {
+                        if (typeof ctx.skills.get !== 'function')
+                            registryError = '宿主未提供 skills.get，无法确认技能是否实际生效。';
+                        else {
+                            try {
+                                registered = matches(await ctx.skills.get(result.check.name), registration.definition);
+                                registryChecked = true;
+                            }
+                            catch (error) {
+                                registryError = '读取宿主技能注册表失败：' + message(error);
+                            }
+                        }
+                    }
+                    let code = 'ready';
+                    let detail = result.check.file;
+                    let reloadRequired = false;
+                    if (disposed) {
+                        code = 'disposed';
+                        registered = false;
+                        detail = '插件已卸载。';
+                        reloadRequired = true;
+                    }
+                    else if (!result.check.ok) {
+                        code = result.check.code;
+                        detail = result.check.detail;
+                    }
+                    else if (registration.error) {
+                        code = 'registration_failed';
+                        detail = '加载时注册失败：' + registration.error;
+                        reloadRequired = true;
+                    }
+                    else if (!registration.definition) {
+                        code = 'not_registered';
+                        detail = '文件现已有效，但加载时未注册；请重载插件。';
+                        reloadRequired = true;
+                    }
+                    else if (result.fingerprint !== registration.fingerprint) {
+                        code = 'changed';
+                        detail = '文件已变化，当前注册仍是加载时版本；请重载插件。';
+                        reloadRequired = true;
+                    }
+                    else if (registryError) {
+                        code = 'registry_unavailable';
+                        detail = registryError;
+                    }
+                    else if (!registered) {
+                        code = 'inactive';
+                        detail = '宿主注册表中的技能缺失或已被其他内容替代；请重载插件。';
+                        reloadRequired = true;
+                    }
+                    skills.push({ ...result.check, ok: code === 'ready', code, detail, fileOk: result.check.ok, registered, registryChecked, reloadRequired });
+                }
+                return { ok: !disposed && skills.every((skill) => skill.ok), plugin: options.plugin, skills };
+            };
+            if (typeof ctx.tools?.register === 'function') {
+                try {
+                    const remove = ctx.tools.register({
+                        name: options.healthTool,
+                        description: options.plugin + ' 自检：重新验证技能文件、内容与当前宿主注册状态。文件变化或修复后提示重载；自检不修改注册表。',
+                        parameters: { type: 'object', properties: {} },
+                        output: {
+                            schema: { type: 'object', additionalProperties: true },
+                            render(_args, value) {
+                                const result = value;
+                                const lines = [options.plugin + ' 自检' + (result.ok ? '：技能资源完整且已注册。' : '：发现技能文件或注册状态异常。')];
+                                for (const skill of result.skills)
+                                    lines.push('- ' + skill.name + '：' + (skill.ok ? '✅' : '❌ ' + skill.detail));
+                                return [{ type: 'text', text: lines.join('\n') }];
+                            },
+                        },
+                        execute: health,
+                    });
+                    if (typeof remove !== 'function')
+                        throw new Error('tools.register 未返回卸载函数。');
+                    disposers.push(remove);
+                }
+                catch (error) {
+                    dispose();
+                    throw error;
+                }
+            }
+        },
+    };
+}