@lemonppt/cli 0.1.8 → 0.2.1

package/agents/openai.yaml

@@ -0,0 +1,176 @@
+# lemonPPT - AI-powered presentation generation
+# Copyright (c) 2026 lemonforme
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+name: lemonppt
+description: |
+  lemonPPT 是一个结构化 goal.json → 视觉 PPT 的渲染与导出引擎。
+  支持自然语言生成 PPT、按角色自动选版式、导出 PPTX/PDF，以及程序化选页与字段校验。
+
+functions:
+  - name: generate_goal
+    description: 根据一句话需求生成完整的 goal.json（端到端入口）
+    parameters:
+      type: object
+      properties:
+        input:
+          type: string
+          description: 用户的 PPT 需求描述
+        pageCount:
+          type: integer
+          description: 期望页数，默认 8
+          default: 8
+        theme:
+          type: string
+          description: 主题 ID，如 theme01、theme06
+          default: theme01
+        language:
+          type: string
+          enum: [zh, en]
+          description: 输出语言
+          default: zh
+      required: [input]
+
+  - name: render_goal
+    description: 将 goal.json 渲染为离线可打开的 HTML deck
+    parameters:
+      type: object
+      properties:
+        goal:
+          type: object
+          description: 符合 lemonPPT 规范的 DeckGoal 对象
+        editable:
+          type: boolean
+          description: 是否生成浏览器端可编辑版本
+          default: false
+      required: [goal]
+
+  - name: export_pptx
+    description: 将 goal.json 导出为可编辑 PPTX
+    parameters:
+      type: object
+      properties:
+        goal:
+          type: object
+          description: 符合 lemonPPT 规范的 DeckGoal 对象
+      required: [goal]
+
+  - name: export_pdf
+    description: 将 goal.json 导出为截图 PDF
+    parameters:
+      type: object
+      properties:
+        goal:
+          type: object
+          description: 符合 lemonPPT 规范的 DeckGoal 对象
+      required: [goal]
+
+  - name: list_themes
+    description: 列出所有可用主题
+    parameters:
+      type: object
+      properties: {}
+
+  - name: layout_query
+    description: 按主题与角色查询候选版式，供 Agent 程序化选页
+    parameters:
+      type: object
+      properties:
+        theme:
+          type: string
+          description: 主题 ID
+        role:
+          type: string
+          description: 页面角色，如 cover、metric、chart、process
+        keyword:
+          type: string
+          description: 关键词过滤
+        needsMedia:
+          type: boolean
+          description: 是否只返回需要媒体的版式
+        limit:
+          type: integer
+          description: 返回数量上限
+          default: 8
+      required: [theme, role]
+
+  - name: inspect_layout
+    description: 查看指定版式的字段契约、默认值与媒体槽位
+    parameters:
+      type: object
+      properties:
+        layoutId:
+          type: string
+          description: 完整版式 ID，如 theme06_metric_hero_v1
+      required: [layoutId]
+
+  - name: goal_scaffold
+    description: 生成只含 role 的 goal.json 骨架，由外层 Agent 填充内容
+    parameters:
+      type: object
+      properties:
+        title:
+          type: string
+          description: PPT 标题
+        goal:
+          type: string
+          description: PPT 目标/核心信息
+        audience:
+          type: string
+          description: 目标受众
+        owner:
+          type: string
+          description: 作者或团队
+        theme:
+          type: string
+          description: 主题 ID
+          default: theme01
+        pages:
+          type: integer
+          description: 页数
+          default: 8
+        language:
+          type: string
+          enum: [zh, en]
+          description: 语言
+          default: zh
+      required: [title, goal]
+
+  - name: write_safe_props
+    description: 规范化 goal.json 的 props，填充默认值并校验未知字段
+    parameters:
+      type: object
+      properties:
+        goal:
+          type: object
+          description: DeckGoal 对象
+      required: [goal]
+
+  - name: validate_goal_spec
+    description: 独立校验 goal.json 是否符合规范
+    parameters:
+      type: object
+      properties:
+        goal:
+          type: object
+          description: DeckGoal 对象
+        strict:
+          type: boolean
+          description: 是否将内容警告视为错误
+          default: false
+      required: [goal]
+
+usage:
+  - |
+    端到端生成：
+    1. generate_goal(input="面向企业客户的 AI 助手产品发布会...", pageCount=8, theme="theme01")
+    2. export_pptx(goal=result.goal)
+  - |
+    精细编排：
+    1. list_themes()
+    2. layout_query(theme="theme06", role="metric", limit=3)
+    3. inspect_layout(layoutId="theme06_metric_hero_v1")
+    4. goal_scaffold(title="...", goal="...", theme="theme06", pages=10)
+    5. write_safe_props(goal=...)
+    6. validate_goal_spec(goal=...)
+    7. export_pptx(goal=...)

package/dist/cli.js

@@ -2,14 +2,32 @@
 // lemonPPT - AI-powered presentation generation
 // Copyright (c) 2026 lemonforme
 // SPDX-License-Identifier: AGPL-3.0-or-later
-import { exportGoalToPdf, exportGoalToPptx, generateGoalToFile, readGoalFromFile, renderGoalToDir, } from './index.js';
+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, 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 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]
+  lemonppt inspect-layout <layoutId> [--compact]
+  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) {
@@ -34,6 +52,96 @@ 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 = {
+        '.html': 'text/html; charset=utf-8',
+        '.js': 'text/javascript; charset=utf-8',
+        '.css': 'text/css; charset=utf-8',
+        '.json': 'application/json; charset=utf-8',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+        '.woff': 'font/woff',
+        '.woff2': 'font/woff2',
+        '.ttf': 'font/ttf',
+        '.otf': 'font/otf',
+        '.eot': 'application/vnd.ms-fontobject',
+    };
+    const server = createHttpServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host}`);
+        let pathname = decodeURIComponent(url.pathname);
+        if (pathname === '/') {
+            // 优先 editable 输出（editor.html），回退到非 editable 输出（index.html）
+            for (const fallback of ['editor.html', 'index.html']) {
+                try {
+                    const s = await stat(join(root, fallback));
+                    if (s.isFile()) {
+                        pathname = '/' + fallback;
+                        break;
+                    }
+                }
+                catch { }
+            }
+        }
+        const filePath = join(root, pathname);
+        if (!filePath.startsWith(root + '/') && filePath !== root) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+        }
+        try {
+            const s = await stat(filePath);
+            if (!s.isFile()) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const ext = extname(filePath).toLowerCase();
+            const contentType = mimeTypes[ext] || 'application/octet-stream';
+            const data = await readFile(filePath);
+            res.writeHead(200, { 'Content-Type': contentType });
+            res.end(data);
+        }
+        catch {
+            res.writeHead(404);
+            res.end('Not found');
+        }
+    });
+    return new Promise((resolve) => {
+        server.listen(port, () => {
+            console.log(`Serving ${root} at http://localhost:${port}`);
+            resolve();
+        });
+    });
+}
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0) {
@@ -99,7 +207,182 @@ async function main() {
                 }
                 break;
             }
+            case 'serve':
+            case 'server': {
+                const dir = positional[0] || './output';
+                const port = args.options.port ? Number(args.options.port) : 3456;
+                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': {
+                const themes = listThemes();
+                console.log(JSON.stringify(themes, null, 2));
+                break;
+            }
+            case 'layout-query': {
+                const theme = args.options.theme;
+                const role = args.options.role;
+                if (!theme || !role) {
+                    console.error('Error: layout-query requires --theme and --role.');
+                    process.exit(1);
+                }
+                const result = queryLayouts({
+                    theme,
+                    role,
+                    keyword: args.options.keyword,
+                    needsMedia: args.options['needs-media'] === true,
+                    limit: args.options.limit ? Number(args.options.limit) : 8,
+                    seed: args.options.seed,
+                });
+                console.log(JSON.stringify(result, null, 2));
+                break;
+            }
+            case 'inspect-layout': {
+                const layoutId = positional[0];
+                if (!layoutId) {
+                    console.error('Error: inspect-layout requires a layoutId.');
+                    process.exit(1);
+                }
+                const info = inspectLayout(layoutId);
+                if (!info) {
+                    console.error(`Error: layout "${layoutId}" not found.`);
+                    process.exit(1);
+                }
+                if (args.options.compact === true) {
+                    console.log(JSON.stringify({
+                        layout: info.layout,
+                        displayName: info.displayName,
+                        role: info.role,
+                        description: info.description,
+                        needsMedia: info.needsMedia,
+                        mediaSlots: info.mediaSlots,
+                        tags: info.tags,
+                        contentShape: info.contentShape,
+                        fields: info.fields,
+                    }, null, 2));
+                }
+                else {
+                    console.log(JSON.stringify(info, null, 2));
+                }
+                break;
+            }
+            case 'goal-scaffold': {
+                const title = args.options.title;
+                const goal = args.options.goal;
+                if (!title || !goal) {
+                    console.error('Error: goal-scaffold requires --title and --goal.');
+                    process.exit(1);
+                }
+                const result = await scaffoldGoalToFile({
+                    title,
+                    goal,
+                    audience: args.options.audience,
+                    owner: args.options.owner,
+                    theme: args.options.theme,
+                    pages: args.options.pages ? Number(args.options.pages) : 8,
+                    language: args.options.language,
+                    seed: args.options.seed,
+                    outFile: args.options.out || './goal.json',
+                });
+                console.log(`Scaffolded goal: ${result.title} (${result.slides.length} slides)`);
+                break;
+            }
+            case 'write-safe-props': {
+                const goalPath = positional[0];
+                if (!goalPath) {
+                    console.error('Error: write-safe-props requires a goal.json path.');
+                    process.exit(1);
+                }
+                const result = await writeSafePropsToFile({
+                    goalPath,
+                    write: args.options.write === true,
+                });
+                if (args.options.write !== true) {
+                    console.log(JSON.stringify({
+                        valid: result.valid,
+                        layoutChanges: result.layoutChanges,
+                        unknownFields: result.unknownFields,
+                    }, null, 2));
+                }
+                else {
+                    console.log(`Safe props written to ${goalPath}`);
+                    if (result.layoutChanges.length > 0) {
+                        console.warn(`Layout changes: ${result.layoutChanges.length}`);
+                    }
+                    if (result.unknownFields.length > 0) {
+                        console.warn(`Unknown fields: ${result.unknownFields.length}`);
+                    }
+                }
+                break;
+            }
+            case 'validate-goal-spec': {
+                const goalPath = positional[0];
+                if (!goalPath) {
+                    console.error('Error: validate-goal-spec requires a goal.json path.');
+                    process.exit(1);
+                }
+                const result = await validateGoalSpec(goalPath, args.options.strict === true);
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.valid) {
+                    process.exit(1);
+                }
+                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

@@ -5,7 +5,7 @@ export interface GenerateCliOptions {
     input: string;
     /** 页数，默认 8 */
     pageCount?: number;
-    /** 主题 ID，默认 base */
+    /** 主题 ID，默认 theme01 */
     theme?: string;
     /** 语言，默认 zh */
     language?: 'zh' | 'en';
@@ -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;
@@ -53,3 +74,130 @@ export declare function exportGoalToPptx(goal: DeckGoal, options: ExportCliOptio
  * 导出 goal 为 PDF。
  */
 export declare function exportGoalToPdf(goal: DeckGoal, options: ExportCliOptions): Promise<void>;
+/**
+ * 列出所有可用主题。
+ */
+export declare function listThemes(): {
+    id: string;
+    name: string;
+}[];
+/**
+ * 按主题与角色查询候选版式。
+ */
+export declare function queryLayouts(options: {
+    theme: string;
+    role: string;
+    keyword?: string;
+    needsMedia?: boolean;
+    limit?: number;
+    seed?: string;
+}): {
+    theme: string;
+    role: string;
+    count: number;
+    layouts: {
+        layout: string;
+        displayName: string;
+        description: string;
+        needsMedia: boolean;
+    }[];
+};
+/**
+ * 查看指定版式的字段契约。
+ */
+export declare function inspectLayout(layoutId: string): {
+    layout: string;
+    displayName: string;
+    theme: string;
+    role: string;
+    description: string;
+    needsMedia: boolean;
+    mediaSlots: {
+        name: string;
+        fieldPath: string;
+        canPresetMedia: boolean;
+    }[];
+    tags: string[];
+    contentShape: string;
+    fields: {
+        key: string;
+        label: string;
+        type: string;
+        defaultValue?: unknown;
+    }[];
+} | null;
+/**
+ * 生成只含 role 的 goal.json 骨架。
+ */
+export declare function scaffoldGoalToFile(options: {
+    title: string;
+    goal: string;
+    audience?: string;
+    owner?: string;
+    theme?: string;
+    pages?: number;
+    language?: 'zh' | 'en';
+    seed?: string;
+    outFile?: string;
+}): Promise<DeckGoal>;
+/**
+ * 规范化 goal.json 的 props。
+ */
+export declare function writeSafePropsToFile(options: {
+    goalPath: string;
+    write?: boolean;
+}): Promise<{
+    valid: boolean;
+    layoutChanges: {
+        index: number;
+        from: string;
+        to: string;
+    }[];
+    unknownFields: {
+        index: number;
+        layout: string;
+        keys: string[];
+    }[];
+    goal: DeckGoal;
+}>;
+/**
+ * 校验 goal.json 规范。
+ */
+export declare function validateGoalSpec(goalPath: string, strict?: boolean): Promise<{
+    valid: boolean;
+    errors: {
+        type: string;
+        detail: unknown;
+    }[];
+    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>;