dsh-ppt 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.2（2026-09-11）
+
+- 适配并验证官方 Harness 0.1.5-rc.1：整套同载、工具/技能契约与 Web 鉴权检查通过。
+- Node 要求与宿主统一为 `^22.19.0 || >=24.0.0`；更新中英文兼容性说明。
+
 ## 0.4.0
 
 - **动效（motion，默认开）**：HTML 放映页间淡入 + 要点按序逐条入场（打印自动兜底为静态）；PPTX 每页原生淡入转场，`bullets` 页按段落构建、放映时点击一次出现一条要点（PowerPoint「出现，按段落」标准时序）。

package/README.en.md

@@ -30,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 with official `@deepseek-ai/dsh@0.1.5-rc.1` and Node `24.16.0` on 2026-09-11: all 18 components load alongside Modlens, with passing tool-schema, skill-registration and offline read-only invocation checks. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements match this Harness release: 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
 
 ## Installation
 
@@ -79,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 |
@@ -103,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
 
@@ -120,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.
@@ -147,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

@@ -32,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.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
 
 ## 安装
 
@@ -72,6 +72,8 @@ node <skill-dir>/scripts/build-deck.mjs \
 
 输出三件套：
 
+默认不会覆盖已有同名产物：三件套中任一文件存在时会整组追加 `-1`、`-2`… 后缀；只有显式传 `overwrite: true`（CLI 为 `--overwrite`）才会覆盖。
+
 | 文件 | 用途 |
 | --- | --- |
 | `*.html` | 独立网页放映：方向键/滚轮/触屏翻页，F 全屏，G 总览，P 打印或另存 PDF |
@@ -96,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`。
 
 ## 配置
 
@@ -113,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`，取消的调用不会继续生成文件；生成和写入阶段为同步操作，开始后会完成本次三件套。
+
 
 ## 卸载
 
@@ -149,7 +153,7 @@ pnpm run smoke:cli  # 裸 CLI 冒烟，生成 .smoke-deck
 - PPTX 采用空白版式 + 文本框实现：PowerPoint / WPS 中可正常编辑文字，但暂不生成智能母版占位符。
 - 一句话输入自动生成三页最小结构；更丰富的内容需要先扩写成 Markdown 大纲再调用 `ppt_create`。
 - `bilingual` 只双语化播放器界面，不自动翻译内容。
-- 暂不支持图表、图片、演讲者备注与 PPT 动画；这些在 v0.2+ 规划。
+- 暂不支持图表与图片；演讲者备注及 HTML/PPTX 动效已经支持。
 
 ## 协议
 
@@ -159,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

@@ -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,63 +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.' },
-            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.' },
-        }),
-        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),
-                motion: args.motion,
-                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,
+        },
+    ];
+}

package/lib/types.d.ts

@@ -1,7 +1,7 @@
 /** dsh-ppt 的公共类型。 */
 export type PptThemeId = 'swiss' | 'velvet' | 'data' | 'soft' | 'bold';
 export type PptLanguage = 'zh' | 'en' | 'bilingual';
-export type PptSlideLayout = 'cover' | 'section' | 'bullets' | 'statement' | 'closing';
+export type PptSlideLayout = 'cover' | 'section' | 'bullets' | 'statement' | 'quote' | 'table' | 'closing';
 export interface PptSlideSpec {
     layout?: PptSlideLayout;
     title?: string;
@@ -9,9 +9,13 @@ export interface PptSlideSpec {
     kicker?: string;
     text?: string;
     bullets?: string[];
+    /** 表格页数据；第一行作为表头。 */
+    rows?: Array<Array<string | number>>;
+    /** 演讲者备注；写入 HTML 备注面板与 PPTX 原生备注页。 */
+    notes?: string;
 }
 export interface PptConfig {
-    /** 默认输出目录；调用 ppt_create 时可用 outputDir 覆盖。默认当前工作目录。 */
+    /** 默认输出目录；调用 ppt_create 时可用 outputDir 覆盖。相对路径按会话工作目录解析。 */
     outputDir?: string;
     /** 单次生成幻灯片上限，默认 60（3–120）。 */
     maxSlides?: number;
@@ -32,6 +36,8 @@ export interface PptCreateArgs {
     motion?: 'on' | 'off';
     outputDir?: string;
     fileName?: string;
+    /** 是否覆盖同名三件套；默认 false，同名时自动选择唯一后缀。 */
+    overwrite?: boolean;
 }
 export interface PptThemeInfo {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ppt",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "DSH 演示文稿技能 + 工具插件：一句话或一篇 Markdown 文档 → 完整演示文稿（独立 HTML 网页放映 + 可编辑 PPTX 导出），内置 5 套视觉主题与页间转场/要点入场动画（motion 可关），可配置默认主题/语言，中英双语，SKILL.md 薄路由 + references 按需装载，跨 harness。",
   "type": "module",
   "main": "lib/index.js",
@@ -51,7 +51,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/skills/dsh-ppt/scripts/build-deck.mjs

@@ -30,6 +30,7 @@ const HELP = `dsh-ppt —— 一句话 / 一篇文档 → HTML 放映 + PPTX 导
   --motion <on|off>   页间转场与要点入场动画（默认 on；off 产出纯静态）
   --out <dir>         输出目录（默认当前目录）
   --file <name>       文件名前缀（默认取标题）
+  --overwrite         显式覆盖同名三件套（默认自动追加 -1/-2…）
   --list-themes       列出内置主题
   --help              显示本帮助
 
@@ -40,7 +41,7 @@ const HELP = `dsh-ppt —— 一句话 / 一篇文档 → HTML 放映 + PPTX 导
 `
 
 export function parseArgv(argv) {
-  const args = { content: '', slides: null, lang: 'zh', theme: DEFAULT_THEME, motion: undefined, out: '.', file: '', title: '' }
+  const args = { content: '', slides: null, lang: 'zh', theme: DEFAULT_THEME, motion: undefined, out: '.', file: '', title: '', overwrite: false }
   const positional = []
   for (let i = 0; i < argv.length; i += 1) {
     const raw = String(argv[i])
@@ -55,6 +56,7 @@ export function parseArgv(argv) {
     }
     if (key === '--help' || key === '-h') args.help = true
     else if (key === '--list-themes') args.listThemes = true
+    else if (key === '--overwrite') args.overwrite = true
     else if (key === '--title') args.title = nextValue()
     else if (key === '--content') args.content = nextValue()
     else if (key === '--slides') args.slides = JSON.parse(nextValue())
@@ -110,6 +112,7 @@ export async function main(argv = process.argv.slice(2), io = {}) {
     motion: args.motion,
     outputDir: resolvePath(args.out || '.'),
     fileName: args.file,
+    overwrite: args.overwrite,
   }
   const result = buildDeck(options)
   log('dsh-ppt 已生成 ' + result.slideCount + ' 页演示文稿：')

package/skills/dsh-ppt/scripts/deck-core.mjs

@@ -14,7 +14,7 @@
  * 零运行时依赖，仅使用 node:fs / node:path / node:zlib。
  */
 
-import { mkdirSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { resolve as resolvePath } from 'node:path'
 import { deflateRawSync } from 'node:zlib'
 
@@ -249,6 +249,22 @@ export function sanitizeFileName(input) {
   return cleaned.slice(0, 120) || 'deck'
 }
 
+const DECK_ARTIFACT_EXTENSIONS = ['.html', '.pptx', '.json']
+
+/**
+ * 为三件套选择同一个可用文件名前缀。默认不覆盖：任一产物已存在时，
+ * 整组改用 -1/-2… 后缀，避免新旧 deck 被静默混写。
+ */
+function resolveDeckFileName(outputDir, requestedFileName, overwrite) {
+  const isAvailable = (candidate) => DECK_ARTIFACT_EXTENSIONS.every((ext) => !existsSync(resolvePath(outputDir, candidate + ext)))
+  if (overwrite || isAvailable(requestedFileName)) return requestedFileName
+  for (let index = 1; index < 1000; index += 1) {
+    const candidate = requestedFileName + '-' + index
+    if (isAvailable(candidate)) return candidate
+  }
+  throw new Error('dsh-ppt：找不到可用的输出文件名（同名前缀超过 999 个），请更换 fileName 或显式允许 overwrite。')
+}
+
 export function escapeXml(value) {
   return String(value ?? '')
     .replace(/&/g, '&amp;')
@@ -654,13 +670,15 @@ export function normalizeBuildOptions(options = {}) {
   if (deck.slides.length < 1) throw new Error('dsh-ppt：没有可生成的幻灯片')
   const outputDir = resolvePath(String(options.outputDir ?? '.').trim() || '.')
   const fileName = sanitizeFileName(options.fileName ?? title)
-  return { title, theme, language, motion, deck, outputDir, fileName }
+  const overwrite = options.overwrite === true
+  return { title, theme, language, motion, deck, outputDir, fileName, overwrite }
 }
 
 export function buildDeck(options = {}) {
   const normalized = normalizeBuildOptions(options)
-  const { title, theme, language, motion, deck, outputDir, fileName } = normalized
+  const { title, theme, language, motion, deck, outputDir, overwrite } = normalized
   mkdirSync(outputDir, { recursive: true })
+  const fileName = resolveDeckFileName(outputDir, normalized.fileName, overwrite)
 
   const manifest = {
     version: DECK_VERSION,