@lemonppt/cli 0.2.0 → 0.2.1

package/SKILL.md

@@ -72,14 +72,23 @@ lemonppt export ./goal.json --pptx ./deck.pptx
 
 ### 方式三：HTTP API 服务
 
+先确保已构建：`corepack pnpm -r build`（若系统未全局安装 pnpm，corepack 会自动提供）。
+
 ```bash
+# 启动真正的 lemonPPT API 服务（默认 3456 端口）
 lemonppt serve --port 3456
+
+# 等价的 server 别名
+lemonppt server --port 3456
 ```
 
+底层启动 `apps/server/dist/index.js`，输出目录默认 `./output`。
+
 接口：
 
 - `POST /api/generate-goal`：自然语言 → `goal.json`
 - `POST /api/render`：`goal.json` → HTML
+- `POST /api/render-editor`：`goal.json` → 单页编辑器渲染数据（`EditorData` JSON），不再生成静态文件
 - `POST /api/export/pptx`：`goal.json` → PPTX
 - `POST /api/export/pdf`：`goal.json` → PDF
 - `POST /api/layout-query`：候选版式查询
@@ -87,6 +96,31 @@ lemonppt serve --port 3456
 - `POST /api/goal-scaffold`：生成骨架
 - `POST /api/write-safe-props`：规范化 props
 - `POST /api/validate-goal-spec`：校验 goal.json
+- `POST /api/stage-media`：上传 base64 图片到服务目录，返回可在 `goal.json` 中引用的 URL
+- `GET /editor`：打开单页编辑器（所有主题共享同一页面，通过 `?theme=theme01` 切换主题）
+- `GET /api/render-editor?theme=theme01`：基于示例 goal 返回指定主题的 `EditorData`
+
+调用示例：
+
+```bash
+curl -X POST http://localhost:3456/api/render \
+  -H "Content-Type: application/json" \
+  -d @goal.json
+
+curl -X POST http://localhost:3456/api/export/pptx \
+  -H "Content-Type: application/json" \
+  -d @goal.json \
+  --output deck.pptx
+
+curl -X POST "http://localhost:3456/api/render-editor?theme=theme02" \
+  -H "Content-Type: application/json" \
+  -d @goal.json
+
+# 上传本地图片（base64）
+curl -X POST http://localhost:3456/api/stage-media \
+  -H "Content-Type: application/json" \
+  -d '{"filename":"logo.png","data":"iVBORw0KGgoAAAANSUhEUg..."}'
+```
 
 ---
 
@@ -100,6 +134,10 @@ lemonppt serve --port 3456
 | `theme04` | 玻璃糖果风 | green / yellow / blue / pink + light / dark |
 | `theme05` | 光谱报告风 | coral / amber / teal / indigo / violet + light / dark |
 | `theme06` | 深色图谱风 | volt / magma / nebula / nova + light / dark |
+| `theme07` | 冷白金融投资风 | cold-white / warm-gray / ink / navy + light / dark |
+| `theme08` | 曜金黑金机构风 | obsidian-gold / midnight-silver / graphite-rose / forest-gold |
+| `theme09` | 墨韵杂志印刷风 | paper / ink 双基底 + primary / muted |
+| `theme10` | 金指数据指数风 | gold-index / blue-index / green-index |
 
 默认主题：`theme01`。
 
@@ -140,11 +178,11 @@ lemonppt serve --port 3456
 | `goal` | 是 | 演示目标/背景 |
 | `audience` | 是 | 受众描述 |
 | `owner` | 否 | 汇报人 |
-| `theme` | 是 | 主题 ID |
+| `theme` | 是 | 主题 ID；也兼容 `themePack` 作为别名 |
 | `colorScheme` | 否 | 主题专用配色方案，见「可用主题」 |
 | `appearance` | 否 | `light` / `dark`，部分主题支持 |
 | `language` | 否 | `zh` 或 `en`，默认 `zh` |
-| `pageCount` | 是 | 总页数，必须等于 `slides.length` |
+| `pageCount` | 否 | 总页数；留空时自动等于 `slides.length` |
 | `randomSeed` | 否 | 随机种子，保证选页可复现 |
 | `slides` | 是 | 幻灯片数组 |
 
@@ -152,10 +190,12 @@ lemonppt serve --port 3456
 
 | 字段 | 必填 | 说明 |
 |---|---|---|
-| `role` | 是 | 页面角色，见下方「页面角色」 |
+| `role` | 否 | 页面角色，见下方「页面角色」；留空时尝试从 `layout` 推断 |
 | `layout` | 否 | 具体版式 ID；留空时系统按 role 自动选择 |
 | `props` | 是 | 该版式所需数据 |
 
+> **外部 Agent 友好**：HTTP API 与 CLI 均支持 `themePack` 替代 `theme`、`pageCount` 省略、`role` 省略（系统从 `layout` ID 推断），方便被其他 Agent 调用。未提供的必填字段将自动补全。
+
 ---
 
 ## 页面角色
@@ -220,8 +260,9 @@ lemonppt render <goal.json> [--out ./output] [--editable]
 # 导出
 lemonppt export <goal.json> --pptx out.pptx [--pdf out.pdf]
 
-# 本地服务
+# 本地服务（优先启动 API 服务；未构建时回退到静态预览）
 lemonppt serve [<dir>] [--port N]
+lemonppt server [<dir>] [--port N]
 
 # 主题/版式查询
 lemonppt list-themes
@@ -235,10 +276,39 @@ lemonppt validate-goal-spec <goal.json>
 
 # 安装到 Agent 技能目录
 lemonppt install-skill [--claude] [--codex] [--cursor] [--all]
+lemonppt install-skill --target ./my-agent/skills/lemonppt
 ```
 
 ---
 
+## Skill 包内 npm scripts（Dashi 风格）
+
+将 `skills/lemonppt/` 复制到 Agent 技能目录后，也可以直接进入 skill 目录调用 npm scripts：
+
+```bash
+cd ~/.claude/skills/lemonppt
+
+npm run layout:query -- --theme theme01 --role cover --limit 5
+npm run inspect:layout -- theme01_cover_v1
+npm run goal:scaffold -- --title "AI 报告" --goal "..." --theme theme01 --pages 8 --out ./goal.json
+npm run props:safe -- ./goal.json --write
+npm run validate:goal-spec -- ./goal.json
+npm run render:goal -- ./goal.json --out ./output
+npm run validate:deck -- ./output --goal ./goal.json
+npm run validate:goal-copy -- ./goal.json ./output
+npm run export:pptx -- ./goal.json ./deck.pptx
+npm run export:pdf -- ./goal.json ./deck.pdf
+npm run preview:start -- ./output --port 3456
+npm run media:stage -- ./image.png --out ./output/assets
+```
+
+这些脚本本质上是调用 `lemonppt` CLI 的薄包装，因此首次使用前需要：
+
+- 源码模式：确保项目已构建（`corepack pnpm -r build`），skill 包会被写入本地 CLI 路径；
+- 发布模式：执行过 `npm install -g @lemonppt/cli`，或脚本自动通过 `npx @lemonppt/cli` 调用。
+
+---
+
 ## 常见错误处理
 
 1. **没有 API Key**：`lemonppt generate` 会 fallback 到内置示例内容，仍可生成完整文件。如需更贴合主题的文案，提供 `--api-key`。

package/dist/cli.js

@@ -2,18 +2,22 @@
 // lemonPPT - AI-powered presentation generation
 // Copyright (c) 2026 lemonforme
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { createServer } from 'node:http';
+import { createServer as createHttpServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import { stat, readFile } from 'node:fs/promises';
-import { extname, join, resolve } from 'node:path';
-import { exportGoalToPdf, exportGoalToPptx, generateGoalToFile, inspectLayout, listThemes, queryLayouts, readGoalFromFile, renderGoalToDir, scaffoldGoalToFile, validateGoalSpec, writeSafePropsToFile, } from './index.js';
+import { extname, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { exportGoalToPdf, exportGoalToPptx, generateGoalToFile, inspectLayout, listThemes, queryLayouts, readGoalFromFile, renderGoalToDir, scaffoldGoalToFile, stageMediaToFile, validateDeck, validateGoalCopy, validateGoalSpec, writeSafePropsToFile, } from './index.js';
 import { installSkill } from './install-skill.js';
 function printUsage() {
     console.log(`Usage:
   lemonppt generate "<input>" [--pages N] [--theme <id>] [--language zh|en] [--out goal.json] [--api-key KEY]
   lemonppt render <goal.json> [--out ./output] [--editable]
   lemonppt export <goal.json> --pptx out.pptx [--pdf out.pdf]
-  lemonppt serve [<dir>] [--port N]
-  lemonppt install-skill [--claude] [--codex] [--cursor] [--all]
+  lemonppt serve [<dir>] [--port N]   # start API server if built, else static preview
+  lemonppt server [<dir>] [--port N]  # alias for serve
+  lemonppt install-skill [--claude] [--codex] [--cursor] [--all] [--target <dir>]
 
   lemonppt list-themes
   lemonppt layout-query --theme <id> --role <role> [--keyword K] [--needs-media] [--limit N] [--seed S]
@@ -21,6 +25,9 @@ function printUsage() {
   lemonppt goal-scaffold --title T --goal G --theme <id> --pages N [--out goal.json]
   lemonppt write-safe-props <goal.json> [--write]
   lemonppt validate-goal-spec <goal.json> [--strict]
+  lemonppt validate-deck <deckDir> [--goal goal.json]
+  lemonppt validate-copy <goal.json> <deckDir>
+  lemonppt stage-media <file> [--out ./output]
 `);
 }
 function parseArgs(argv) {
@@ -45,6 +52,31 @@ function parseArgs(argv) {
     }
     return { positional, options };
 }
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, '../../..');
+const apiServerPath = join(projectRoot, 'apps/server/dist/index.js');
+async function startApiServer(dir, port) {
+    if (!existsSync(apiServerPath)) {
+        throw new Error(`API server not found at ${apiServerPath}. Run 'pnpm -r build' first.`);
+    }
+    const child = spawn('node', [apiServerPath], {
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            LEMONPPT_PORT: String(port),
+            LEMONPPT_OUTPUT_DIR: resolve(dir),
+        },
+    });
+    return new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('exit', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`API server exited with code ${code}`));
+        });
+    });
+}
 async function serveDir(dir, port) {
     const root = resolve(dir);
     const mimeTypes = {
@@ -63,7 +95,7 @@ async function serveDir(dir, port) {
         '.otf': 'font/otf',
         '.eot': 'application/vnd.ms-fontobject',
     };
-    const server = createServer(async (req, res) => {
+    const server = createHttpServer(async (req, res) => {
         const url = new URL(req.url || '/', `http://${req.headers.host}`);
         let pathname = decodeURIComponent(url.pathname);
         if (pathname === '/') {
@@ -175,12 +207,20 @@ async function main() {
                 }
                 break;
             }
-            case 'serve': {
+            case 'serve':
+            case 'server': {
                 const dir = positional[0] || './output';
                 const port = args.options.port ? Number(args.options.port) : 3456;
-                await serveDir(dir, port);
-                // 保持进程运行
-                await new Promise(() => { });
+                if (existsSync(apiServerPath)) {
+                    console.log(`Starting API server on port ${port}...`);
+                    await startApiServer(dir, port);
+                }
+                else {
+                    console.log(`API server not built, falling back to static preview.`);
+                    await serveDir(dir, port);
+                    // 保持进程运行
+                    await new Promise(() => { });
+                }
                 break;
             }
             case 'list-themes': {
@@ -297,7 +337,52 @@ async function main() {
                 }
                 break;
             }
+            case 'stage-media': {
+                const filePath = positional[0];
+                if (!filePath) {
+                    console.error('Error: stage-media requires a file path.');
+                    process.exit(1);
+                }
+                const result = await stageMediaToFile({
+                    filePath,
+                    outDir: args.options.out || './output',
+                });
+                console.log(JSON.stringify({ success: true, ...result }, null, 2));
+                break;
+            }
+            case 'validate-deck': {
+                const deckDir = positional[0];
+                if (!deckDir) {
+                    console.error('Error: validate-deck requires a deck directory path.');
+                    process.exit(1);
+                }
+                const result = await validateDeck({
+                    deckDir,
+                    goalPath: args.options.goal,
+                });
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.valid)
+                    process.exit(1);
+                break;
+            }
+            case 'validate-copy': {
+                const goalPath = positional[0];
+                const deckDir = positional[1];
+                if (!goalPath || !deckDir) {
+                    console.error('Error: validate-copy requires <goal.json> <deckDir>.');
+                    process.exit(1);
+                }
+                const result = await validateGoalCopy({ goalPath, deckDir });
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.valid)
+                    process.exit(1);
+                break;
+            }
             case 'install-skill': {
+                if (args.options.target) {
+                    await installSkill({ target: args.options.target });
+                    break;
+                }
                 const agents = [];
                 if (args.options.claude)
                     agents.push('claude');

package/dist/index.d.ts

@@ -28,6 +28,25 @@ export interface ExportCliOptions {
     /** 输出文件路径 */
     outFile: string;
 }
+export declare function copyThemeAssets(themeId: string, assetsDir: string): Promise<void>;
+export interface StageMediaOptions {
+    /** 源文件路径 */
+    filePath: string;
+    /** 输出目录，默认 ./output */
+    outDir?: string;
+}
+export interface StageMediaResult {
+    /** 安全化后的文件名 */
+    filename: string;
+    /** 本地绝对路径 */
+    localPath: string;
+    /** 相对于输出目录的引用路径 */
+    relativePath: string;
+}
+/**
+ * 把本地媒体文件复制到输出目录的 media/ 下，供 goal.json 引用。
+ */
+export declare function stageMediaToFile(options: StageMediaOptions): Promise<StageMediaResult>;
 /**
  * 生成 goal.json 并可选写入文件。
  */
@@ -38,6 +57,8 @@ export declare function generateGoalToFile(options: GenerateCliOptions): Promise
 export declare function readGoalFromFile(filePath: string): Promise<DeckGoal>;
 /**
  * 渲染 deck 到输出目录。
+ * editable 模式下使用单页编辑器架构：复制 server 的 editor.html/editor.js，
+ * 内嵌 renderEditorData 生成的 EditorData，资源路径使用相对路径。
  */
 export declare function renderGoalToDir(goal: DeckGoal, options?: RenderCliOptions): Promise<{
     html: string;
@@ -150,3 +171,33 @@ export declare function validateGoalSpec(goalPath: string, strict?: boolean): Pr
     }[];
     warnings: string[];
 }>;
+export interface ValidateDeckOptions {
+    /** 渲染输出目录（应包含 index.html） */
+    deckDir: string;
+    /** 可选的 goal.json 路径，用于比对页数 */
+    goalPath?: string;
+}
+export interface ValidateDeckResult {
+    valid: boolean;
+    slides: number;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * 校验渲染后的 HTML deck 结构是否完整。
+ */
+export declare function validateDeck(options: ValidateDeckOptions): Promise<ValidateDeckResult>;
+export interface ValidateCopyOptions {
+    goalPath: string;
+    deckDir: string;
+}
+export interface ValidateCopyResult {
+    valid: boolean;
+    missing: string[];
+    checked: number;
+    errors: string[];
+}
+/**
+ * 校验 goal.json 中的文案是否都出现在渲染后的 HTML 中。
+ */
+export declare function validateGoalCopy(options: ValidateCopyOptions): Promise<ValidateCopyResult>;

package/dist/index.js

@@ -2,18 +2,19 @@
 // Copyright (c) 2026 lemonforme
 // SPDX-License-Identifier: AGPL-3.0-or-later
 import { generateGoal } from '@lemonppt/agent-prompts';
-import { normalizeDeckGoal, validateDeckGoal, validateDeckGoalContent, validateSlideCount } from '@lemonppt/core';
-import { exportDeckToPdf, exportDeckToPptx, renderDeck, } from '@lemonppt/renderer';
+import { normalizeDeckGoal, preprocessAgentGoal, validateDeckGoal, validateDeckGoalContent, validateSlideCount } from '@lemonppt/core';
+import { exportDeckToPdf, exportDeckToPptx, renderDeck, renderEditorData, } from '@lemonppt/renderer';
 import { getTheme, themes } from '@lemonppt/themes';
 import { getLayout, getLayoutSchema, listLayoutsByRoleAndTheme } from '@lemonppt/templates';
 import { copyFile, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 function resolveTheme(themeId) {
     const id = themeId || 'theme01';
     return getTheme(id) ? id : 'theme01';
 }
-async function copyThemeAssets(themeId, assetsDir) {
+export async function copyThemeAssets(themeId, assetsDir) {
     const theme = resolveTheme(themeId);
     await mkdir(assetsDir, { recursive: true });
     const cssSource = resolvePackagePath('@lemonppt/themes', 'src', theme, 'styles.css');
@@ -23,14 +24,39 @@ async function copyThemeAssets(themeId, assetsDir) {
     const fontsSource = resolvePackagePath('@lemonppt/renderer', 'assets', 'fonts');
     const fontsDest = path.join(assetsDir, 'fonts');
     await cp(fontsSource, fontsDest, { recursive: true, force: true });
-    // 复制客户端离线渲染脚本，支持静态文件模式下结构编辑
-    const clientRenderSource = resolvePackagePath('@lemonppt/renderer', 'dist', 'client-render.js');
+    // 复制浏览器可执行 bundle（IIFE 格式），支持静态文件模式下结构编辑
+    const clientRenderSource = resolvePackagePath('@lemonppt/renderer', 'dist', 'client', 'client-render.js');
     const clientRenderDest = path.join(assetsDir, 'client-render.js');
     await copyFile(clientRenderSource, clientRenderDest);
+    // 复制 ECharts 主题脚本
+    const themeEChartsSource = resolvePackagePath('@lemonppt/renderer', 'dist', 'client', 'theme-echarts.js');
+    const themeEChartsDest = path.join(assetsDir, 'theme-echarts.js');
+    await copyFile(themeEChartsSource, themeEChartsDest);
     // 复制 jQuery，供编辑器初始化自定义滚动条样式类
     const jquerySource = resolvePackagePath('jquery', 'dist', 'jquery.min.js');
     const jqueryDest = path.join(assetsDir, 'jquery.min.js');
     await copyFile(jquerySource, jqueryDest);
+    // 复制编辑器交互脚本，供单页编辑器动态初始化
+    const editorScriptSource = resolvePackagePath('@lemonppt/renderer', 'dist', 'client', 'editor-script.js');
+    const editorScriptDest = path.join(assetsDir, 'editor-script.js');
+    await copyFile(editorScriptSource, editorScriptDest);
+}
+/**
+ * 把本地媒体文件复制到输出目录的 media/ 下，供 goal.json 引用。
+ */
+export async function stageMediaToFile(options) {
+    const outDir = options.outDir || './output';
+    const originalName = path.basename(options.filePath);
+    const safeName = originalName.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const mediaDir = path.join(outDir, 'media');
+    await mkdir(mediaDir, { recursive: true });
+    const localPath = path.resolve(path.join(mediaDir, safeName));
+    await copyFile(options.filePath, localPath);
+    return {
+        filename: safeName,
+        localPath,
+        relativePath: path.join('media', safeName),
+    };
 }
 function resolvePackagePath(pkg, ...segments) {
     // 优先通过 package.json 定位包根（第三方 npm 包）
@@ -73,22 +99,50 @@ export async function generateGoalToFile(options) {
  */
 export async function readGoalFromFile(filePath) {
     const raw = await readFile(path.resolve(filePath), 'utf-8');
-    const parsed = JSON.parse(raw);
+    const parsed = preprocessAgentGoal(JSON.parse(raw));
     parsed.theme = resolveTheme(parsed.theme);
     return normalizeDeckGoal(parsed);
 }
 /**
  * 渲染 deck 到输出目录。
+ * editable 模式下使用单页编辑器架构：复制 server 的 editor.html/editor.js，
+ * 内嵌 renderEditorData 生成的 EditorData，资源路径使用相对路径。
  */
 export async function renderGoalToDir(goal, options = {}) {
     const { outDir = './output', editable = false, width, height } = options;
     const outputDir = path.resolve(outDir);
     const assetsDir = path.join(outputDir, 'assets');
-    const result = renderDeck(goal, { width, height, editable });
     await copyThemeAssets(goal.theme, assetsDir);
-    const indexName = editable ? 'editor.html' : 'index.html';
-    const indexPath = path.join(outputDir, indexName);
     await mkdir(outputDir, { recursive: true });
+    if (editable) {
+        const data = renderEditorData(goal, { width: width ?? 1280, height: height ?? 720 });
+        const rendererTemplatesDir = resolvePackagePath('@lemonppt/renderer', 'templates');
+        let editorHtml = await readFile(path.join(rendererTemplatesDir, 'editor.html'), 'utf-8');
+        let editorJs = await readFile(path.join(rendererTemplatesDir, 'editor.js'), 'utf-8');
+        // 静态文件模式下使用相对资源路径
+        editorHtml = editorHtml.replace(/\/deck\/assets\//g, './assets/');
+        editorHtml = editorHtml.replace(/src="\/editor\.js"/g, 'src="./editor.js"');
+        // 内嵌 EditorData，让 editor.js 在静态模式下无需请求 API
+        const embeddedData = `<script>
+window.__lemonPPT_assetsBase = './assets/';
+window.__lemonPPT_editorData = ${JSON.stringify(data)};
+</script>`;
+        editorHtml = editorHtml.replace('</head>', `${embeddedData}\n</head>`);
+        const indexPath = path.join(outputDir, 'editor.html');
+        await writeFile(indexPath, editorHtml, 'utf-8');
+        await writeFile(path.join(outputDir, 'editor.js'), editorJs, 'utf-8');
+        const assets = [
+            './assets/fonts/fonts.css',
+            `./assets/${data.theme}.css`,
+            './assets/jquery.min.js',
+            './assets/editor-script.js',
+            './assets/client-render.js',
+            './assets/theme-echarts.js',
+        ];
+        return { html: editorHtml, indexPath, assetsDir, assets };
+    }
+    const result = renderDeck(goal, { width, height });
+    const indexPath = path.join(outputDir, 'index.html');
     await writeFile(indexPath, result.html, 'utf-8');
     return { html: result.html, indexPath, assetsDir, assets: result.assets };
 }
@@ -319,25 +373,25 @@ function normalizePropsWithSchema(props, fields) {
  */
 export async function writeSafePropsToFile(options) {
     const { goalPath, write } = options;
-    const raw = JSON.parse(await readFile(path.resolve(goalPath), 'utf-8'));
+    const preprocessed = preprocessAgentGoal(JSON.parse(await readFile(path.resolve(goalPath), 'utf-8')));
     const { composeDeckFromRaw: compose } = await import('@lemonppt/composer');
     const composed = compose({
-        title: raw.title,
-        goal: raw.goal,
-        audience: raw.audience,
-        owner: raw.owner,
-        theme: raw.theme,
-        language: raw.language,
-        colorScheme: raw.colorScheme,
-        appearance: raw.appearance,
-        pageCount: raw.pageCount,
-        randomSeed: raw.randomSeed,
-        slides: raw.slides.map((s) => ({ role: s.role, layout: s.layout, props: s.props })),
+        title: preprocessed.title,
+        goal: preprocessed.goal,
+        audience: preprocessed.audience,
+        owner: preprocessed.owner,
+        theme: preprocessed.theme,
+        language: preprocessed.language,
+        colorScheme: preprocessed.colorScheme,
+        appearance: preprocessed.appearance,
+        pageCount: preprocessed.pageCount,
+        randomSeed: preprocessed.randomSeed,
+        slides: preprocessed.slides.map((s) => ({ role: s.role, layout: s.layout, props: s.props })),
     });
     const layoutChanges = [];
     const unknownFields = [];
     const safeSlides = composed.slides.map((slide, index) => {
-        const originalLayout = raw.slides[index]?.layout;
+        const originalLayout = preprocessed.slides[index]?.layout;
         const registered = getLayout(slide.layout);
         const schema = registered ? getLayoutSchema(slide.layout) : undefined;
         if (originalLayout && originalLayout !== slide.layout) {
@@ -366,7 +420,7 @@ export async function writeSafePropsToFile(options) {
  * 校验 goal.json 规范。
  */
 export async function validateGoalSpec(goalPath, strict) {
-    const raw = JSON.parse(await readFile(path.resolve(goalPath), 'utf-8'));
+    const raw = preprocessAgentGoal(JSON.parse(await readFile(path.resolve(goalPath), 'utf-8')));
     const result = {
         valid: false,
         errors: [],
@@ -402,3 +456,96 @@ export async function validateGoalSpec(goalPath, strict) {
     }
     return result;
 }
+/**
+ * 校验渲染后的 HTML deck 结构是否完整。
+ */
+export async function validateDeck(options) {
+    const result = { valid: false, slides: 0, errors: [], warnings: [] };
+    const indexPath = path.resolve(options.deckDir, 'index.html');
+    if (!existsSync(indexPath)) {
+        result.errors.push(`deck index.html not found: ${indexPath}`);
+        return result;
+    }
+    const html = await readFile(indexPath, 'utf-8');
+    if (html.length < 100) {
+        result.errors.push('index.html is too short, render may have failed');
+        return result;
+    }
+    // 估算 slide 数量：通过 lp-slide-wrapper 容器
+    const wrapperMatches = html.match(/class="[^"]*\blp-slide-wrapper\b[^"]*"/g) ?? [];
+    const indexMatches = html.match(/data-slide-index="\d+"/g) ?? [];
+    result.slides = Math.max(wrapperMatches.length, indexMatches.length);
+    if (result.slides === 0) {
+        result.errors.push('no slides found in index.html');
+    }
+    if (options.goalPath) {
+        const goal = JSON.parse(await readFile(path.resolve(options.goalPath), 'utf-8'));
+        const expected = goal.slides.length;
+        if (result.slides !== expected) {
+            result.errors.push(`slide count mismatch: deck=${result.slides}, goal=${expected}`);
+        }
+    }
+    if (!html.includes('</html>')) {
+        result.warnings.push('index.html may be truncated (missing closing </html>)');
+    }
+    if (result.errors.length === 0) {
+        result.valid = true;
+    }
+    return result;
+}
+function collectTextStrings(value) {
+    const results = [];
+    function walk(v) {
+        if (typeof v === 'string') {
+            const trimmed = v.trim();
+            if (trimmed.length >= 4)
+                results.push(trimmed);
+        }
+        else if (Array.isArray(v)) {
+            v.forEach(walk);
+        }
+        else if (v && typeof v === 'object') {
+            Object.values(v).forEach(walk);
+        }
+    }
+    walk(value);
+    return [...new Set(results)];
+}
+/**
+ * 校验 goal.json 中的文案是否都出现在渲染后的 HTML 中。
+ */
+export async function validateGoalCopy(options) {
+    const result = { valid: false, missing: [], checked: 0, errors: [] };
+    const indexPath = path.resolve(options.deckDir, 'index.html');
+    if (!existsSync(indexPath)) {
+        result.errors.push(`deck index.html not found: ${indexPath}`);
+        return result;
+    }
+    const goal = JSON.parse(await readFile(path.resolve(options.goalPath), 'utf-8'));
+    const html = await readFile(indexPath, 'utf-8');
+    const texts = collectTextStrings(goal.slides.map((s) => s.props));
+    result.checked = texts.length;
+    const normalizedHtml = html
+        .replace(/&amp;/g, '&')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/\s+/g, ' ');
+    for (const text of texts) {
+        const normalizedText = text.replace(/\s+/g, ' ');
+        if (!normalizedHtml.includes(normalizedText)) {
+            result.missing.push(text.slice(0, 80));
+        }
+    }
+    if (result.missing.length > 0) {
+        result.errors.push(`${result.missing.length} / ${result.checked} text snippets missing in rendered HTML`);
+    }
+    else if (result.checked === 0) {
+        result.errors.push('no text found in goal.json to validate');
+    }
+    else {
+        result.valid = true;
+    }
+    return result;
+}

package/dist/install-skill.d.ts

@@ -1,6 +1,8 @@
 export interface InstallSkillOptions {
     /** 指定安装的 Agent，默认全部 */
     agents?: string[];
+    /** 自定义目标目录（直接复制整个 skill 包） */
+    target?: string;
 }
 /**
  * 将 lemonPPT skill 安装到常见 AI Agent 的技能目录。

package/dist/install-skill.js

@@ -1,51 +1,100 @@
 // lemonPPT - AI-powered presentation generation
 // Copyright (c) 2026 lemonforme
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { copyFile, cp, mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 const DEFAULT_AGENTS = ['claude', 'codex', 'cursor'];
 function resolveSkillMdPath() {
-    // Published package: SKILL.md lives next to the package root (one level above dist/)
     const mainUrl = import.meta.resolve('@lemonppt/cli');
     const pkgRoot = path.resolve(path.dirname(fileURLToPath(mainUrl)), '..');
+    // Local monorepo dev: repo root is two levels above the package root
+    const local = path.resolve(pkgRoot, '..', '..', 'SKILL.md');
+    if (existsSync(local) && existsSync(path.resolve(pkgRoot, '..', '..', 'apps', 'server'))) {
+        return local;
+    }
+    // Published package: SKILL.md lives next to the package root (one level above dist/)
     const published = path.join(pkgRoot, 'SKILL.md');
     if (existsSync(published)) {
         return published;
     }
-    // Local monorepo dev: fallback to repo root SKILL.md
-    const local = path.resolve(pkgRoot, '..', '..', 'SKILL.md');
-    if (existsSync(local)) {
-        return local;
-    }
     throw new Error('SKILL.md not found. It should be bundled with @lemonppt/cli or exist at the repo root.');
 }
+function resolveRepoRoot(skillMdPath) {
+    return path.dirname(skillMdPath);
+}
+function resolveSkillBundlePath(skillMdPath) {
+    const repoRoot = resolveRepoRoot(skillMdPath);
+    const bundlePath = path.join(repoRoot, 'skills', 'lemonppt');
+    if (existsSync(bundlePath)) {
+        return bundlePath;
+    }
+    throw new Error('Skill bundle not found at skills/lemonppt. Did you run the build script?');
+}
+function isSourceRepo(repoRoot) {
+    return existsSync(path.join(repoRoot, 'apps', 'server'));
+}
+function resolveCliWrapper(repoRoot) {
+    if (isSourceRepo(repoRoot)) {
+        const cliPath = path.join(repoRoot, 'packages', 'cli', 'dist', 'cli.js');
+        return {
+            type: 'source',
+            cli: cliPath,
+            sh: `#!/bin/bash\nset -e\nexec "${cliPath}" "$@"\n`,
+            ps1: `#Requires -Version 5.1\n& node "${cliPath}" @args\n`,
+        };
+    }
+    return {
+        type: 'published',
+        sh: `#!/bin/bash\nset -e\nexec npx @lemonppt/cli "$@"\n`,
+        ps1: `#Requires -Version 5.1\n& npx @lemonppt/cli @args\n`,
+    };
+}
+function resolveCliMarker(wrapper) {
+    return JSON.stringify(wrapper.type === 'source' && wrapper.cli
+        ? { type: wrapper.type, cli: wrapper.cli }
+        : { type: wrapper.type }, null, 2);
+}
 async function installAgent(agent) {
     const homeDir = os.homedir();
     const skillDir = path.join(homeDir, `.${agent}/skills/lemonppt`);
     await mkdir(skillDir, { recursive: true });
     const skillMdSource = resolveSkillMdPath();
-    await copyFile(skillMdSource, path.join(skillDir, 'SKILL.md'));
-    await copyFile(skillMdSource, path.join(skillDir, 'README.md'));
+    const bundlePath = resolveSkillBundlePath(skillMdSource);
+    await cp(bundlePath, skillDir, { recursive: true, force: true });
+    // 兼容 OpenAI/Codex 等同时读取根目录 openai.yaml 的框架
+    const agentYamlSource = path.join(bundlePath, 'agents', 'openai.yaml');
+    if (existsSync(agentYamlSource)) {
+        await copyFile(agentYamlSource, path.join(skillDir, 'openai.yaml'));
+    }
+    const repoRoot = resolveRepoRoot(skillMdSource);
+    const wrapper = resolveCliWrapper(repoRoot);
     const scriptsDir = path.join(skillDir, 'scripts');
-    await mkdir(scriptsDir, { recursive: true });
-    const wrapperSh = `#!/bin/bash
-set -e
-exec npx @lemonppt/cli "$@"
-`;
-    await writeFile(path.join(scriptsDir, 'lemonppt.sh'), wrapperSh, { mode: 0o755 });
-    const wrapperPs1 = `#Requires -Version 5.1
-& npx @lemonppt/cli @args
-`;
-    await writeFile(path.join(scriptsDir, 'lemonppt.ps1'), wrapperPs1, { mode: 0o755 });
-    console.log(`✓ Installed lemonPPT skill for ${agent} at ${skillDir}`);
+    await writeFile(path.join(scriptsDir, 'lemonppt.sh'), wrapper.sh, { mode: 0o755 });
+    await writeFile(path.join(scriptsDir, 'lemonppt.ps1'), wrapper.ps1, { mode: 0o755 });
+    await writeFile(path.join(scriptsDir, '.cli-path.json'), resolveCliMarker(wrapper));
+    console.log(`✓ Installed lemonPPT skill for ${agent} at ${skillDir} (${wrapper.type} mode)`);
 }
 /**
  * 将 lemonPPT skill 安装到常见 AI Agent 的技能目录。
  */
 export async function installSkill(options = {}) {
+    if (options.target) {
+        const skillMdSource = resolveSkillMdPath();
+        const bundlePath = resolveSkillBundlePath(skillMdSource);
+        await mkdir(options.target, { recursive: true });
+        await cp(bundlePath, options.target, { recursive: true, force: true });
+        const repoRoot = resolveRepoRoot(skillMdSource);
+        const wrapper = resolveCliWrapper(repoRoot);
+        const scriptsDir = path.join(options.target, 'scripts');
+        await writeFile(path.join(scriptsDir, 'lemonppt.sh'), wrapper.sh, { mode: 0o755 });
+        await writeFile(path.join(scriptsDir, 'lemonppt.ps1'), wrapper.ps1, { mode: 0o755 });
+        await writeFile(path.join(scriptsDir, '.cli-path.json'), resolveCliMarker(wrapper));
+        console.log(`✓ Copied skill bundle to ${options.target} (${wrapper.type} mode)`);
+        return;
+    }
     const agents = options.agents?.length ? options.agents : DEFAULT_AGENTS;
     for (const agent of agents) {
         await installAgent(agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lemonppt/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,10 +31,10 @@
   },
   "homepage": "https://github.com/lemonforme/lemonPPT#readme",
   "dependencies": {
-    "@lemonppt/agent-prompts": "0.2.0",
-    "@lemonppt/renderer": "0.2.0",
-    "@lemonppt/core": "0.2.0",
-    "@lemonppt/themes": "0.2.0"
+    "@lemonppt/agent-prompts": "0.2.1",
+    "@lemonppt/core": "0.2.1",
+    "@lemonppt/renderer": "0.2.1",
+    "@lemonppt/themes": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",