dsh-ppt 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0
+
+- **动效（motion，默认开）**：HTML 放映页间淡入 + 要点按序逐条入场（打印自动兜底为静态）；PPTX 每页原生淡入转场，`bullets` 页按段落构建、放映时点击一次出现一条要点（PowerPoint「出现，按段落」标准时序）。
+- **`motion` 开关**：`ppt_create` 新增 `motion: 'on' | 'off'`，CLI 新增 `--motion on|off`；`off` 时产物不含任何动画代码，适合严肃/打印场景。manifest 记录该开关。
+- **技能文件瘦身**：SKILL.md 收敛为触发条件 + 执行纪律 + 六步流水线 + 按需装载索引 + 质量门禁；新增 `references/syntax.md`（Markdown 解析、表格/金句/备注语法、结构化 slides、motion）与 `references/troubleshooting.md`；写作规则去重归口 `references/copywriting.md`，hyperframes 视觉联动并入 `references/themes.md`。
+- 动效相关测试 8 例（转场/时序树/点击节点计数/静态开关/CLI/工具层），全套 42/42 通过。
+
 ## 0.3.0
 
 - **演讲者备注**：结构化 `slides` 的 `notes` 字段与 Markdown `<!-- 备注: ... -->` 注释都会成为该页备注；HTML 放映按 `S` 键（或右下角「备注」按钮）呼出备注面板；PPTX 生成原生 `notesSlide` + `notesMaster` 部件，PowerPoint 演示者视图直接可用。

package/README.en.md

@@ -4,7 +4,7 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-> **One sentence or one document → a complete presentation**: HTML web slideshow + PPTX export, 5 visual themes, bilingual Chinese/English.
+> **One sentence or one document → a complete presentation**: HTML web slideshow + PPTX export, 5 visual themes, slide transitions + bullet entrance animations, bilingual Chinese/English.
 
 DeepSeek Harness (DSH) presentation skill + tool plugin: turns a sentence, a paragraph, or a Markdown document into a ready-to-present **HTML slideshow** and an editable **PPTX**. Pure Node, **zero runtime dependencies**, one codebase for Windows / macOS / Linux.
 
@@ -16,6 +16,7 @@ DeepSeek Harness (DSH) presentation skill + tool plugin: turns a sentence, a par
 | `ppt_themes` tool | Lists the 5 built-in themes and their best use cases |
 | 7 layouts | cover / section / bullets / statement / **quote** / **table** / closing |
 | Speaker notes | `<!-- note: ... -->` comments or the `notes` field: press `S` in the HTML player; native PPTX notes slides (presenter view) |
+| Motion | On by default: HTML slide-in transitions + staggered bullet entrances; native PPTX fade transitions + click-to-reveal bullets. `motion: 'off'` / `--motion off` for a fully static deck |
 | Markdown extras | Tables (`\| ... \|`), blockquotes (`>`), and note comments are auto-detected into matching layouts |
 | `dsh-ppt` skill | A complete six-step SOP registered into DSH |
 | Standalone SKILL.md | Copy `skills/dsh-ppt/` into Claude Code / Cursor / Gemini CLI / Codex for cross-harness use |
@@ -29,7 +30,7 @@ Example:
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.2-alpha.3` on 2026-09-01. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against the tool and skill registration contracts in `@deepseek-ai/dsh@0.1.2-rc.1` on 2026-09-04 (no relevant API or documentation changes from alpha.5). Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -78,6 +79,8 @@ node <skill-dir>/scripts/build-deck.mjs \
 
 Artifacts:
 
+Existing artifacts are not overwritten by default: if any member of the trio already exists, the whole set receives a shared `-1`, `-2`, ... suffix. Replacement requires explicit `overwrite: true` (or `--overwrite` in the CLI).
+
 | File | Purpose |
 | --- | --- |
 | `*.html` | Standalone web slideshow: arrow keys/wheel/touch navigation, F fullscreen, G overview, P print/save as PDF |
@@ -102,7 +105,7 @@ Themes are derived from [dsh-hyperframes](https://github.com/STARDUSTLC666/dsh-h
 - Each `## section` becomes one slide: lists produce `bullets` slides; empty sections produce `section` dividers.
 - Plain text without headings: the first paragraph is the cover, then every 5 sentences become one slide.
 - A single sentence automatically produces a complete 3-slide structure: cover → core idea → closing.
-- For precise control, use structured `slides` (`cover | section | bullets | statement | closing`).
+- For precise control, use structured `slides` (`cover | section | bullets | statement | quote | table | closing`), with `rows` for tables and `notes` for speaker notes.
 
 ## Configuration
 
@@ -119,6 +122,8 @@ No required configuration. Optional:
 
 The `DSH_PPT_OUTPUT_DIR` env var can also set the default output directory; the `ppt_create` `outputDir`/`theme`/`lang` arguments have the highest priority.
 
+Output paths resolve against each tool call's `exec.agent.session.header.cwd`: omitted paths use the session directory, relative paths (including plugin configuration) resolve within it, and absolute paths keep their meaning. Direct calls without a session fall back to the process working directory; concurrent sessions never change process cwd. Tools check `exec.signal` before and after loading the engine, so cancelled calls do not proceed to generation. Rendering and writing are synchronous and finish the artifact trio once started.
+
 ## Bilingual support
 
 - `lang` argument: `zh` (default) / `en` / `bilingual` controls the player UI, page numbers, and closing defaults.
@@ -146,7 +151,7 @@ pnpm run smoke:cli  # bare CLI smoke test, generates .smoke-deck
 - The PPTX uses a blank layout plus text boxes: text is editable in PowerPoint / WPS, but no smart master placeholders yet.
 - A one-sentence input produces a minimal 3-slide structure; for richer decks, expand the content into a Markdown outline first.
 - `bilingual` only localizes the player UI; it does not translate content.
-- Charts, images, speaker notes, and PPT animations are planned for v0.2+.
+- Charts and images are not supported yet; speaker notes and HTML/PPTX motion are already supported.
 
 ## License
 

package/README.md

@@ -2,7 +2,7 @@
 
 # dsh-ppt
 
-> **一句话 / 一篇文档 → 完整演示文稿**：HTML 网页放映 + PPTX 导出，5 套视觉主题，中英双语。
+> **一句话 / 一篇文档 → 完整演示文稿**：HTML 网页放映 + PPTX 导出，5 套视觉主题，页间转场 + 要点入场动画，中英双语。
 
 ![npm version](https://img.shields.io/npm/v/dsh-ppt?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-ppt) ![license](https://img.shields.io/npm/l/dsh-ppt) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-ppt?style=social)
 
@@ -18,6 +18,7 @@ DSH（DeepSeek Harness）演示文稿技能 + 工具插件：把一句话、一
 | `ppt_themes` 工具 | 列出 5 套内置主题与适用场景 |
 | 7 种页型 | 封面 / 章节 / 要点 / 核心观点 / **金句** / **表格** / 结束页 |
 | 演讲者备注 | `<!-- 备注: ... -->` 或 `notes` 字段：HTML 按 `S` 呼出，PPTX 原生备注页（演示者视图） |
+| 动效（motion） | 默认开：HTML 页间淡入 + 要点逐条入场；PPTX 原生转场 + 要点逐条点击显现；`motion: 'off'` / `--motion off` 产出纯静态 |
 | Markdown 进阶 | 表格（`\| ... \|`）、引用金句（`>`）、备注注释自动识别成对应页型 |
 | `dsh-ppt` 技能 | 完整 SOP 注册进 DSH：从一句话到成品 deck 的六步流水线 |
 | 裸 SKILL.md | 把 `skills/dsh-ppt/` 复制到 Claude Code / Cursor / Gemini CLI / Codex 即可跨 harness 使用 |
@@ -31,7 +32,7 @@ DSH（DeepSeek Harness）演示文稿技能 + 工具插件：把一句话、一
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.2-alpha.3` 上验证（2026-09-01 全量冒烟通过）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已按 `@deepseek-ai/dsh@0.1.2-rc.1` 的工具与技能注册契约验证（2026-09-04；相较 alpha.5 无相关 API / 文档变化）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -71,6 +72,8 @@ node <skill-dir>/scripts/build-deck.mjs \
 
 输出三件套：
 
+默认不会覆盖已有同名产物：三件套中任一文件存在时会整组追加 `-1`、`-2`… 后缀；只有显式传 `overwrite: true`（CLI 为 `--overwrite`）才会覆盖。
+
 | 文件 | 用途 |
 | --- | --- |
 | `*.html` | 独立网页放映：方向键/滚轮/触屏翻页，F 全屏，G 总览，P 打印或另存 PDF |
@@ -95,7 +98,7 @@ node <skill-dir>/scripts/build-deck.mjs \
 - 每个 `## 小节` → 一页：有列表生成 `bullets` 页，无内容生成 `section` 过渡页。
 - 没有标题的纯文本 → 第一段作封面，后续每 5 句一页。
 - 只有一句话 → 自动生成「封面 → 核心观点 → 结束页」三页完整结构。
-- 需要精确控制时用结构化 `slides`（`cover | section | bullets | statement | closing`）。
+- 需要精确控制时用结构化 `slides`（`cover | section | bullets | statement | quote | table | closing`），表格使用 `rows`，备注使用 `notes`。
 
 ## 配置
 
@@ -112,6 +115,8 @@ node <skill-dir>/scripts/build-deck.mjs \
 
 也可用环境变量 `DSH_PPT_OUTPUT_DIR` 指定默认输出目录；`ppt_create` 的 `outputDir`/`theme`/`lang` 参数优先级最高。
 
+输出目录按每次工具调用的 `exec.agent.session.header.cwd` 解析：不指定目录时写入当前会话工作目录，相对目录（包括插件配置）相对此目录解析，绝对目录保持原意。直接调用工具而未提供会话时，回退到进程工作目录；并行会话不会修改进程 cwd。工具在加载引擎前和加载完成后检查 `exec.signal`，取消的调用不会继续生成文件；生成和写入阶段为同步操作，开始后会完成本次三件套。
+
 
 ## 卸载
 
@@ -148,7 +153,7 @@ pnpm run smoke:cli  # 裸 CLI 冒烟，生成 .smoke-deck
 - PPTX 采用空白版式 + 文本框实现：PowerPoint / WPS 中可正常编辑文字，但暂不生成智能母版占位符。
 - 一句话输入自动生成三页最小结构；更丰富的内容需要先扩写成 Markdown 大纲再调用 `ppt_create`。
 - `bilingual` 只双语化播放器界面，不自动翻译内容。
-- 暂不支持图表、图片、演讲者备注与 PPT 动画；这些在 v0.2+ 规划。
+- 暂不支持图表与图片；演讲者备注及 HTML/PPTX 动效已经支持。
 
 ## 协议
 
@@ -158,4 +163,4 @@ MIT。社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保
 
 - [dsh-hyperframes](https://github.com/STARDUSTLC666/dsh-hyperframes) — HTML 视频创作技能（本插件视觉风格来源）
 - [dsh-remotion](https://github.com/STARDUSTLC666/dsh-remotion) — React 编程式视频技能
-- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套

package/lib/config.js

@@ -2,17 +2,39 @@ export const PPT_OUTPUT_DIR_ENV = 'DSH_PPT_OUTPUT_DIR';
 export const DEFAULT_MAX_SLIDES = 60;
 /** 解析并校验插件行配置。本插件无必填项，空配置永远可用。 */
 export function resolvePptConfig(config) {
+    if (config !== undefined && config !== null && (typeof config !== 'object' || Array.isArray(config))) {
+        throw new Error('dsh-ppt 配置必须是对象。');
+    }
     const raw = config ?? {};
+    if (raw.outputDir !== undefined && typeof raw.outputDir !== 'string') {
+        throw new Error('outputDir 必须是字符串。');
+    }
+    if (raw.defaultTheme !== undefined && typeof raw.defaultTheme !== 'string') {
+        throw new Error('defaultTheme 必须是字符串。');
+    }
+    if (raw.defaultLang !== undefined && typeof raw.defaultLang !== 'string') {
+        throw new Error('defaultLang 必须是字符串。');
+    }
     const outputDir = (typeof raw.outputDir === 'string' ? raw.outputDir : '').trim()
         || (process.env[PPT_OUTPUT_DIR_ENV] ?? '').trim();
     const defaultTheme = (typeof raw.defaultTheme === 'string' ? raw.defaultTheme : '').trim();
     const defaultLang = (typeof raw.defaultLang === 'string' ? raw.defaultLang : '').trim();
+    if (defaultTheme !== '' && !['swiss', 'velvet', 'data', 'soft', 'bold'].includes(defaultTheme)) {
+        throw new Error('defaultTheme 只支持 swiss / velvet / data / soft / bold。');
+    }
     if (defaultLang !== '' && defaultLang !== 'zh' && defaultLang !== 'en' && defaultLang !== 'bilingual') {
         throw new Error('defaultLang 只支持 zh / en / bilingual。');
     }
+    let maxSlides = DEFAULT_MAX_SLIDES;
+    if (raw.maxSlides !== undefined) {
+        if (typeof raw.maxSlides !== 'number' || !Number.isInteger(raw.maxSlides) || raw.maxSlides < 3 || raw.maxSlides > 120) {
+            throw new Error('maxSlides 必须是 3–120 的整数。');
+        }
+        maxSlides = raw.maxSlides;
+    }
     return {
         outputDir,
-        maxSlides: clampInt(raw.maxSlides, DEFAULT_MAX_SLIDES, 3, 120),
+        maxSlides,
         defaultTheme,
         defaultLang,
     };

package/lib/execution.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedPptConfig } from './config.js';
+import type { DeckEngine, PptThemesResult } from './types.js';
+/** The Harness execution fields used by this plugin; optional for direct callers. */
+export interface PptExecution {
+    readonly signal?: AbortSignal;
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}
+/** Build executors with a shared engine loader; resolve paths separately for each call. */
+export declare function createPptExecutors(config: ResolvedPptConfig, loadEngine?: () => Promise<DeckEngine>): {
+    themes(rawArgs: unknown, exec?: PptExecution): Promise<PptThemesResult>;
+    create(rawArgs: unknown, exec?: PptExecution): Promise<import("./types.js").PptCreateResult>;
+};

package/lib/execution.js

@@ -0,0 +1,56 @@
+import { resolve } from 'node:path';
+let enginePromise = null;
+function getEngine() {
+    if (enginePromise === null) {
+        const engineUrl = new URL('../skills/dsh-ppt/scripts/deck-core.mjs', import.meta.url);
+        enginePromise = import(engineUrl.href).then((module) => module)
+            .catch((error) => {
+            enginePromise = null;
+            throw error;
+        });
+    }
+    return enginePromise;
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+/** Build executors with a shared engine loader; resolve paths separately for each call. */
+export function createPptExecutors(config, loadEngine = getEngine) {
+    return {
+        async themes(rawArgs, exec) {
+            exec?.signal?.throwIfAborted();
+            const args = asRecord(rawArgs);
+            const lang = typeof args.lang === 'string' && args.lang.trim() !== '' ? args.lang.trim() : 'zh';
+            const engine = await loadEngine();
+            exec?.signal?.throwIfAborted();
+            return { ok: true, themes: engine.listThemes(lang) };
+        },
+        async create(rawArgs, exec) {
+            exec?.signal?.throwIfAborted();
+            const args = asRecord(rawArgs);
+            if (typeof args.title !== 'string' || args.title.trim() === '')
+                throw new Error('dsh-ppt：title 不能为空');
+            const hasContent = typeof args.content === 'string' && args.content.trim() !== '';
+            const hasSlides = Array.isArray(args.slides) && args.slides.length > 0;
+            if (!hasContent && !hasSlides)
+                throw new Error('dsh-ppt：content 不能为空（或用 slides 传结构化幻灯片）');
+            const engine = await loadEngine();
+            // Loading can yield to cancellation. Rendering/writing then runs synchronously.
+            exec?.signal?.throwIfAborted();
+            const cwd = exec?.agent?.session.header.cwd ?? process.cwd();
+            const outputDir = typeof args.outputDir === 'string' && args.outputDir.trim() !== '' ? args.outputDir.trim() : config.outputDir;
+            return engine.buildDeck({
+                title: args.title.trim(),
+                content: typeof args.content === 'string' ? args.content : '',
+                slides: hasSlides ? args.slides : undefined,
+                theme: typeof args.theme === 'string' && args.theme.trim() !== '' ? args.theme.trim() : (config.defaultTheme || undefined),
+                lang: typeof args.lang === 'string' && args.lang.trim() !== '' ? args.lang.trim() : (config.defaultLang || undefined),
+                motion: args.motion,
+                outputDir: resolve(cwd, outputDir || '.'),
+                fileName: typeof args.fileName === 'string' && args.fileName.trim() !== '' ? args.fileName.trim() : undefined,
+                overwrite: args.overwrite === true,
+                maxSlides: config.maxSlides,
+            });
+        },
+    };
+}

package/lib/index.d.ts

@@ -1,22 +1,12 @@
 import { type SkillsService } from './skill.js';
 import type { PptConfig } from './types.js';
+import { type ToolDefinition } from './tools.js';
+export type { ToolDefinition } from './tools.js';
+export type { PptExecution } from './execution.js';
 /** cordis 服务注入：apply 里要使用 ctx.tools 与 ctx.skills。 */
 export declare const inject: string[];
 export declare const name = "dsh-ppt";
 export type Config = PptConfig;
-export interface ToolDefinition {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    output: {
-        schema: Record<string, unknown>;
-        render: (args: unknown, value: unknown) => Array<{
-            type: 'text';
-            text: string;
-        }>;
-    };
-    execute: (rawArgs: unknown) => Promise<unknown>;
-}
 export interface PptPluginContext {
     tools: {
         register(definition: ToolDefinition): () => void;
@@ -30,4 +20,4 @@ export interface PptPluginContext {
 export declare function apply(ctx: PptPluginContext, config?: Config): void;
 export { resolvePptConfig, PPT_OUTPUT_DIR_ENV, DEFAULT_MAX_SLIDES, clampInt } from './config.js';
 export { bundledSkillsDir, parseSkillFile, registerPptSkill, SKILL_NAMES } from './skill.js';
-export type { PptConfig, PptCreateArgs, PptCreateResult, PptSlideSpec, PptThemeInfo, PptThemesResult } from './types.js';
+export type { PptConfig, PptCreateArgs, PptCreateResult, PptLanguage, PptSlideLayout, PptSlideSpec, PptThemeId, PptThemeInfo, PptThemesResult, } from './types.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 /**
- * dsh-ppt —— 演示文稿技能 + 工具插件（v0.1.0）。
+ * dsh-ppt —— 演示文稿技能 + 工具插件。
  *
  * 一句话或一篇 Markdown 文档 → 完整演示文稿三件套：
  *   deck.html  独立网页放映（无外链）
@@ -17,112 +17,10 @@
  */
 import { resolvePptConfig } from './config.js';
 import { registerPptSkill } from './skill.js';
+import { buildPptTools } from './tools.js';
 /** cordis 服务注入：apply 里要使用 ctx.tools 与 ctx.skills。 */
 export const inject = ['tools', 'skills'];
 export const name = 'dsh-ppt';
-/**
- * 把作者 DSL 映射编译成原生 JSON Schema 对象，作为 defineTool 的
- * definition.parameters 原样下发。原生 wire 请求会逐字携带该值。
- */
-function compileParameters(spec) {
-    const properties = {};
-    const required = [];
-    for (const [key, prop] of Object.entries(spec)) {
-        if (prop?.required === true)
-            required.push(key);
-        const node = {};
-        if (typeof prop?.type === 'string')
-            node.type = prop.type;
-        if (typeof prop?.description === 'string')
-            node.description = prop.description;
-        if (Array.isArray(prop?.enum))
-            node.enum = prop.enum;
-        if (prop?.type === 'array' && prop.items !== null && typeof prop.items === 'object') {
-            node.items = {
-                type: prop.items.type === 'object' ? 'object' : 'string',
-                ...(prop.items.type === 'object' ? { additionalProperties: true } : {}),
-            };
-        }
-        properties[key] = node;
-    }
-    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
-}
-const themeInfoSchema = {
-    type: 'object',
-    properties: {
-        id: { type: 'string' },
-        name: { type: 'string' },
-        mood: { type: 'string' },
-        bestFor: { type: 'string' },
-        dark: { type: 'boolean' },
-        palette: { type: 'object', additionalProperties: true },
-        fonts: { type: 'object', additionalProperties: true },
-    },
-    additionalProperties: true,
-};
-const themesResultSchema = {
-    type: 'object',
-    properties: {
-        ok: { type: 'boolean' },
-        themes: { type: 'array', items: themeInfoSchema },
-    },
-    additionalProperties: true,
-};
-const createResultSchema = {
-    type: 'object',
-    properties: {
-        ok: { type: 'boolean' },
-        title: { type: 'string' },
-        theme: { type: 'string' },
-        language: { type: 'string' },
-        slideCount: { type: 'integer' },
-        outputDir: { type: 'string' },
-        files: {
-            type: 'object',
-            properties: {
-                html: { type: 'string' },
-                pptx: { type: 'string' },
-                json: { type: 'string' },
-            },
-            additionalProperties: true,
-        },
-        htmlPath: { type: 'string' },
-        pptxPath: { type: 'string' },
-        jsonPath: { type: 'string' },
-    },
-    additionalProperties: true,
-};
-function oneText(text) {
-    return [{ type: 'text', text }];
-}
-function renderThemes(value) {
-    if (value.themes.length === 0)
-        return oneText('dsh-ppt 没有可用主题。');
-    const lines = value.themes.map((theme) => '- ' + theme.id + '：' + theme.name + '（' + theme.mood + '）｜适合：' + theme.bestFor + '｜' + (theme.dark ? '深色' : '浅色'));
-    return oneText('dsh-ppt 内置主题：\n\n' + lines.join('\n') + '\n\nppt_create 的 theme 参数填其中的 id（默认 data）。');
-}
-function renderCreate(value) {
-    return oneText('dsh-ppt 已生成 ' + value.slideCount + ' 页演示文稿（主题 ' + value.theme + '，语言 ' + value.language + '）：\n' +
-        'HTML 网页放映：' + value.htmlPath + '\n' +
-        'PPTX 导出：' + value.pptxPath + '\n' +
-        'Manifest：' + value.jsonPath + '\n' +
-        'HTML 双击即可放映（方向键翻页 / F 全屏 / G 总览 / P 打印）；PPTX 可用 PowerPoint / WPS / Keynote 打开。');
-}
-let enginePromise = null;
-function getEngine() {
-    if (enginePromise === null) {
-        const engineUrl = new URL('../skills/dsh-ppt/scripts/deck-core.mjs', import.meta.url);
-        enginePromise = import(engineUrl.href).then((module) => module)
-            .catch((error) => {
-            enginePromise = null;
-            throw error;
-        });
-    }
-    return enginePromise;
-}
-function isRecord(value) {
-    return value !== null && typeof value === 'object';
-}
 export function apply(ctx, config = {}) {
     const resolved = resolvePptConfig(config);
     const warn = (message) => { ctx.logger?.warn?.(message); };
@@ -134,61 +32,9 @@ export function apply(ctx, config = {}) {
     catch (error) {
         warn('[dsh-ppt] 技能加载失败：' + (error instanceof Error ? error.message : String(error)));
     }
-    disposers.push(ctx.tools.register({
-        name: 'ppt_themes',
-        description: 'List the built-in visual themes of dsh-ppt (id, name, mood, best-for, light/dark palette) before building a deck. Use a theme id as the theme argument of ppt_create. 中文：列出 dsh-ppt 内置视觉主题（id、名称、情绪、适用场景、明暗色板），用于选择 ppt_create 的 theme 参数。',
-        parameters: compileParameters({
-            lang: { type: 'string', description: 'Theme description language: zh (default), en, or bilingual.' },
-        }),
-        output: {
-            schema: themesResultSchema,
-            render: (_args, value) => renderThemes(value),
-        },
-        async execute(rawArgs) {
-            const args = isRecord(rawArgs) ? rawArgs : {};
-            const lang = typeof args.lang === 'string' && args.lang.trim() !== '' ? args.lang.trim() : 'zh';
-            const engine = await getEngine();
-            const themes = engine.listThemes(lang);
-            return { ok: true, themes };
-        },
-    }));
-    disposers.push(ctx.tools.register({
-        name: 'ppt_create',
-        description: 'Build a complete presentation deck from one sentence or a Markdown document and write three artifacts to outputDir: a standalone HTML web slideshow, an editable 16:9 PPTX, and a deck.json manifest. Five built-in visual themes are available (see ppt_themes). content is Markdown text (recommended); advanced callers may pass structured slides instead. 中文：把一句话或一篇 Markdown 文档生成完整演示文稿，写入 outputDir 三个文件：独立 HTML 网页放映、可编辑 16:9 PPTX、deck.json manifest；内置 5 套视觉主题。',
-        parameters: compileParameters({
-            title: { type: 'string', required: true, description: 'Deck title (used for the cover and file names).' },
-            content: { type: 'string', required: true, description: 'Markdown content: one sentence, a paragraph, or a full document. First # heading becomes the cover title; ## headings become slides; -/* lists become bullets; | ... | tables become table slides; > blockquotes become quote slides; <!-- 备注: ... --> comments become speaker notes. Required unless slides is provided.' },
-            theme: { type: 'string', description: 'Visual theme id: swiss / velvet / data / soft / bold. Default data. See ppt_themes.' },
-            lang: { type: 'string', description: 'UI language of the generated player: zh (default), en, or bilingual. Content language is whatever you write.' },
-            slides: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Optional structured slides: [{ layout: cover|section|bullets|statement|quote|table|closing, title, subtitle, kicker, bullets: [], rows: [][] (for table), notes: "speaker notes" }]. Use this for precise control instead of content.' },
-            outputDir: { type: 'string', description: 'Directory to write the files into. Default: session working directory (or the plugin outputDir config).' },
-            fileName: { type: 'string', description: 'Base file name for the three artifacts. Default: sanitized deck title.' },
-        }),
-        output: {
-            schema: createResultSchema,
-            render: (_args, value) => renderCreate(value),
-        },
-        async execute(rawArgs) {
-            const args = (isRecord(rawArgs) ? rawArgs : {});
-            if (typeof args.title !== 'string' || args.title.trim() === '')
-                throw new Error('dsh-ppt：title 不能为空');
-            const hasContent = typeof args.content === 'string' && args.content.trim() !== '';
-            const hasSlides = Array.isArray(args.slides) && args.slides.length > 0;
-            if (!hasContent && !hasSlides)
-                throw new Error('dsh-ppt：content 不能为空（或用 slides 传结构化幻灯片）');
-            const engine = await getEngine();
-            return engine.buildDeck({
-                title: args.title.trim(),
-                content: typeof args.content === 'string' ? args.content : '',
-                slides: hasSlides ? args.slides : undefined,
-                theme: typeof args.theme === 'string' && args.theme.trim() !== '' ? args.theme.trim() : (resolved.defaultTheme || undefined),
-                lang: typeof args.lang === 'string' && args.lang.trim() !== '' ? args.lang.trim() : (resolved.defaultLang || undefined),
-                outputDir: typeof args.outputDir === 'string' && args.outputDir.trim() !== '' ? args.outputDir.trim() : (resolved.outputDir || undefined),
-                fileName: typeof args.fileName === 'string' && args.fileName.trim() !== '' ? args.fileName.trim() : undefined,
-                maxSlides: resolved.maxSlides,
-            });
-        },
-    }));
+    for (const definition of buildPptTools(resolved)) {
+        disposers.push(ctx.tools.register(definition));
+    }
     if (typeof ctx.on === 'function') {
         ctx.on('dispose', () => {
             for (const dispose of disposers)

package/lib/tools.d.ts

@@ -0,0 +1,17 @@
+import type { ResolvedPptConfig } from './config.js';
+import { type PptExecution } from './execution.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    output: {
+        schema: Record<string, unknown>;
+        render: (args: unknown, value: unknown) => Array<{
+            type: 'text';
+            text: string;
+        }>;
+    };
+    execute: (rawArgs: unknown, exec?: PptExecution) => Promise<unknown>;
+}
+/** Assemble presentation schemas, rendering and the session-aware executors. */
+export declare function buildPptTools(config: ResolvedPptConfig): ToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,123 @@
+import { createPptExecutors } from './execution.js';
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        if (Array.isArray(prop?.enum))
+            node.enum = prop.enum;
+        if (prop?.type === 'array' && prop.items !== null && typeof prop.items === 'object') {
+            node.items = {
+                type: prop.items.type === 'object' ? 'object' : 'string',
+                ...(prop.items.type === 'object' ? { additionalProperties: true } : {}),
+            };
+        }
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+const themeInfoSchema = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        mood: { type: 'string' },
+        bestFor: { type: 'string' },
+        dark: { type: 'boolean' },
+        palette: { type: 'object', additionalProperties: true },
+        fonts: { type: 'object', additionalProperties: true },
+    },
+    additionalProperties: true,
+};
+const themesResultSchema = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        themes: { type: 'array', items: themeInfoSchema },
+    },
+    additionalProperties: true,
+};
+const createResultSchema = {
+    type: 'object',
+    properties: {
+        ok: { type: 'boolean' },
+        title: { type: 'string' },
+        theme: { type: 'string' },
+        language: { type: 'string' },
+        slideCount: { type: 'integer' },
+        outputDir: { type: 'string' },
+        files: {
+            type: 'object',
+            properties: {
+                html: { type: 'string' },
+                pptx: { type: 'string' },
+                json: { type: 'string' },
+            },
+            additionalProperties: true,
+        },
+        htmlPath: { type: 'string' },
+        pptxPath: { type: 'string' },
+        jsonPath: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+function oneText(text) {
+    return [{ type: 'text', text }];
+}
+function renderThemes(value) {
+    if (value.themes.length === 0)
+        return oneText('dsh-ppt 没有可用主题。');
+    const lines = value.themes.map((theme) => '- ' + theme.id + '：' + theme.name + '（' + theme.mood + '）｜适合：' + theme.bestFor + '｜' + (theme.dark ? '深色' : '浅色'));
+    return oneText('dsh-ppt 内置主题：\n\n' + lines.join('\n') + '\n\nppt_create 的 theme 参数填其中的 id（默认 data）。');
+}
+function renderCreate(value) {
+    return oneText('dsh-ppt 已生成 ' + value.slideCount + ' 页演示文稿（主题 ' + value.theme + '，语言 ' + value.language + '）：\n' +
+        'HTML 网页放映：' + value.htmlPath + '\n' +
+        'PPTX 导出：' + value.pptxPath + '\n' +
+        'Manifest：' + value.jsonPath + '\n' +
+        'HTML 双击即可放映（方向键翻页 / F 全屏 / G 总览 / P 打印）；PPTX 可用 PowerPoint / WPS / Keynote 打开。');
+}
+/** Assemble presentation schemas, rendering and the session-aware executors. */
+export function buildPptTools(config) {
+    const executors = createPptExecutors(config);
+    return [
+        {
+            name: 'ppt_themes',
+            description: 'List the built-in visual themes of dsh-ppt (id, name, mood, best-for, light/dark palette) before building a deck. Use a theme id as the theme argument of ppt_create. 中文：列出 dsh-ppt 内置视觉主题（id、名称、情绪、适用场景、明暗色板），用于选择 ppt_create 的 theme 参数。',
+            parameters: compileParameters({
+                lang: { type: 'string', description: 'Theme description language: zh (default), en, or bilingual.' },
+            }),
+            output: {
+                schema: themesResultSchema,
+                render: (_args, value) => renderThemes(value),
+            },
+            execute: executors.themes,
+        },
+        {
+            name: 'ppt_create',
+            description: 'Build a complete presentation deck from one sentence or a Markdown document and write three artifacts to outputDir: a standalone HTML web slideshow, an editable 16:9 PPTX, and a deck.json manifest. Five built-in visual themes are available (see ppt_themes). content is Markdown text (recommended); advanced callers may pass structured slides instead. 中文：把一句话或一篇 Markdown 文档生成完整演示文稿，写入 outputDir 三个文件：独立 HTML 网页放映、可编辑 16:9 PPTX、deck.json manifest；内置 5 套视觉主题。',
+            parameters: compileParameters({
+                title: { type: 'string', required: true, description: 'Deck title (used for the cover and file names).' },
+                content: { type: 'string', description: 'Markdown content: one sentence, a paragraph, or a full document. First # heading becomes the cover title; ## headings become slides; -/* lists become bullets; | ... | tables become table slides; > blockquotes become quote slides; <!-- 备注: ... --> comments become speaker notes. Required unless slides is provided.' },
+                theme: { type: 'string', description: 'Visual theme id: swiss / velvet / data / soft / bold. Default data. See ppt_themes.' },
+                lang: { type: 'string', description: 'UI language of the generated player: zh (default), en, or bilingual. Content language is whatever you write.' },
+                motion: { type: 'string', enum: ['on', 'off'], description: 'Slide transitions plus bullet entrance animations: on (default) or off for a fully static deck.' },
+                slides: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Optional structured slides: [{ layout: cover|section|bullets|statement|quote|table|closing, title, subtitle, kicker, bullets: [], rows: [][] (for table), notes: "speaker notes" }]. Use this for precise control instead of content.' },
+                outputDir: { type: 'string', description: 'Directory to write the files into. Default: session working directory (or the plugin outputDir config).' },
+                fileName: { type: 'string', description: 'Base file name for the three artifacts. Default: sanitized deck title.' },
+                overwrite: { type: 'boolean', description: 'Replace an existing same-name HTML/PPTX/JSON trio. Default false: choose a unique numeric suffix instead.' },
+            }),
+            output: {
+                schema: createResultSchema,
+                render: (_args, value) => renderCreate(value),
+            },
+            execute: executors.create,
+        },
+    ];
+}