@liaozhi/dsh-post-gen 0.1.0

package/lib/skills/store.js

@@ -0,0 +1,456 @@
+/**
+ * 海报 skill 库（PosterSkillStore）：以文件夹为单位的本地存储。
+ *
+ * - 存储根目录：`<dshHome>/dsh-post-gen/skills/<name>/`（每个 skill 一个文件夹，
+ *   结构约定见 shared/skill-format.ts 与 docs/poster-skill-format.md）；
+ * - 安装：设置面板上传 zip → 边界校验（体积/条目/路径穿越）→ 解压到暂存目录
+ *   → 按格式校验（SKILL.md frontmatter + 正文生图模板 + 预览图）→ 原子换入；
+ * - 卸载：删除对应文件夹（校验失败的文件夹同样可删）；
+ * - 内置 skill：包内 assets/skills/ 的目录在首启时播种进库（settings 里的
+ *   seededBundled 记录已播种名单，用户删除后不会复活）；
+ * - 变更通知：install/uninstall/seed 后触发 onDidChange，门控据此重估。
+ *
+ * 该 store 是海报 skill 的唯一事实来源；settings 文档不再持有 skill 名单。
+ */
+import { createHash } from 'node:crypto';
+import { cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { unzipSync } from 'fflate';
+import { parse as parseYaml } from 'yaml';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+import { PREVIEWS_DIR_NAME, PREVIEW_EXTENSIONS, SKILL_ZIP_LIMITS, } from '../shared/skill-format.js';
+/** 安装失败的业务错误（code 与 shared/poster-contract.ts 的端点约定一致）。 */
+export class SkillInstallError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SkillInstallError';
+    }
+}
+/** 文件夹名的安全形态（卸载/预览路由共用；故意比 skill name 宽，非法文件夹也要能删）。 */
+const SAFE_FOLDER_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+/** zip 条目中永远跳过的系统噪音。 */
+const NOISE_PATTERNS = [/^__MACOSX\//, /(^|\/)\.DS_Store$/, /(^|\/)Thumbs\.db$/i];
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+export class PosterSkillStore {
+    rootDir;
+    bundledDir;
+    listeners = new Set();
+    /** 内置 skill 名（assets/skills 下的目录名），首次用到时懒加载。 */
+    bundledNamesCache;
+    /**
+     * @param rootDir - skill 库根目录（<dshHome>/dsh-post-gen/skills）。
+     * @param bundledDir - 包内内置 skill 目录（assets/skills）；无则禁用播种。
+     */
+    constructor(rootDir, bundledDir) {
+        this.rootDir = rootDir;
+        this.bundledDir = bundledDir;
+    }
+    /** 订阅库变更（安装/卸载/播种后触发）；返回退订函数。 */
+    onDidChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emitChange() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.warn('[dsh-post-gen] skill store listener failed:', error);
+            }
+        }
+    }
+    /** 扫描整个库：每个子文件夹解析为一个 skill 或一条失败记录。 */
+    async scan() {
+        const bundled = await this.loadBundledNames();
+        const skills = [];
+        const invalid = [];
+        let entries;
+        try {
+            entries = await readdir(this.rootDir);
+        }
+        catch {
+            return { skills, invalid }; // 库目录还没建 = 空库
+        }
+        for (const entry of entries.sort()) {
+            if (entry.startsWith('.'))
+                continue; // 暂存目录等内部文件
+            const dir = join(this.rootDir, entry);
+            try {
+                if (!(await stat(dir)).isDirectory())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            try {
+                skills.push(await this.parseFolder(entry, dir, bundled));
+            }
+            catch (error) {
+                invalid.push({ folder: entry, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return { skills, invalid };
+    }
+    /** 按名取一个已安装 skill；不存在返回 undefined。 */
+    async get(name) {
+        if (!isSkillName(name))
+            return undefined;
+        try {
+            return await this.parseFolder(name, join(this.rootDir, name), await this.loadBundledNames());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** 内置 skill 名单（懒加载 + 缓存；assets/skills 下的每个目录一个）。 */
+    async loadBundledNames() {
+        if (this.bundledNamesCache !== undefined)
+            return this.bundledNamesCache;
+        let names = [];
+        if (this.bundledDir !== undefined) {
+            try {
+                names = (await readdir(this.bundledDir)).filter((entry) => !entry.startsWith('.'));
+            }
+            catch {
+                names = [];
+            }
+        }
+        this.bundledNamesCache = new Set(names);
+        return this.bundledNamesCache;
+    }
+    /**
+     * 从 zip 字节安装（或同名覆盖更新）一个 skill。
+     * @param bytes - zip 文件内容。
+     * @returns 安装结果（含是否覆盖更新）。
+     * @throws SkillInstallError 业务校验失败；其他异常视为 io-failed。
+     */
+    async installZip(bytes) {
+        if (bytes.length > SKILL_ZIP_LIMITS.maxZipBytes) {
+            throw new SkillInstallError('too-large', `压缩包超过 ${Math.round(SKILL_ZIP_LIMITS.maxZipBytes / 1024 / 1024)}MB 上限`);
+        }
+        const relative = stripCommonRoot(extractZipEntries(bytes));
+        if (relative['SKILL.md'] === undefined) {
+            throw new SkillInstallError('invalid-skill', '压缩包结构不符合海报 skill 格式：需要包含 SKILL.md（可直接放在压缩包根目录，或统一包在一层顶层文件夹内）');
+        }
+        // 落盘到暂存目录后再做内容校验，通过才换入正式位置。
+        const staging = join(this.rootDir, `.staging-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
+        try {
+            await mkdir(staging, { recursive: true });
+            for (const [name, data] of Object.entries(relative)) {
+                const target = join(staging, ...name.split('/'));
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, data);
+            }
+            // 落盘到暂存目录后再做内容校验，通过才换入正式位置。
+            // 内容校验失败属于业务校验（invalid-skill），不是 IO 错误。
+            let parsed;
+            try {
+                parsed = await this.parseFolder('(staging)', staging, new Set());
+            }
+            catch (error) {
+                throw new SkillInstallError('invalid-skill', error instanceof Error ? error.message : String(error));
+            }
+            const target = join(this.rootDir, parsed.name);
+            const updated = await exists(target);
+            await rm(target, { recursive: true, force: true });
+            await rename(staging, target);
+            this.emitChange();
+            // 从正式位置重解析一次，拿到正确的 bundled 标记。
+            return { skill: await this.parseFolder(parsed.name, target, await this.loadBundledNames()), updated };
+        }
+        catch (error) {
+            await rm(staging, { recursive: true, force: true }).catch(() => { });
+            if (error instanceof SkillInstallError)
+                throw error;
+            throw new SkillInstallError('io-failed', error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * 卸载一个 skill（按 skill 名或文件夹名；校验失败的文件夹同样可删）。
+     * 内置 skill（包内 assets/skills 播种的）不可删除——bundled 判定按名字，
+     * 文件夹损坏（scan 列入 invalid）的同名条目同样拒绝，避免误删出厂内容。
+     */
+    async uninstall(nameOrFolder) {
+        if (!SAFE_FOLDER_NAME.test(nameOrFolder))
+            return 'bad-name';
+        if ((await this.loadBundledNames()).has(nameOrFolder))
+            return 'bundled';
+        const target = join(this.rootDir, nameOrFolder);
+        if (!(await exists(target)))
+            return 'not-found';
+        await rm(target, { recursive: true, force: true });
+        this.emitChange();
+        return 'ok';
+    }
+    /**
+     * 把包内内置 skill 播种进库，并在插件升级时做**版本迁移**：
+     *
+     * - 新内置 skill：不在 seededNames 里 → 播种（库里已有同名则视为用户版，
+     *   不覆盖，只记账）；
+     * - 已播种的内置 skill：比较库内副本与包内版本的**整文件夹内容哈希**
+     *   （全部文件：SKILL.md/previews/…，路径+字节参与摘要）——
+     *   - 相同 → 只对齐记账；
+     *   - 库内 == 记账哈希 且 包内已更新 → 用户没动过，**镜像为包内版本**
+     *     （rm + cp，上游的修改/新增/删除全部传播）；
+     *   - 库内 != 记账哈希 → 用户改过（含预览图），**不覆盖**；
+     *   - 从未记账（旧版本插件的首次升级）→ 镜像为包内版本（一次性对齐，
+     *     之后进入上面的常规判定）。
+     * @param seededNames - settings.seededBundled（历史已播种名单）。
+     * @param seededHashes - settings.seededHashes（播种时的内容哈希记账）。
+     * @returns 本次播种/刷新结果（调用方负责并入 settings）。
+     */
+    async seedBundled(seededNames, seededHashes) {
+        if (this.bundledDir === undefined)
+            return { seeded: [], refreshed: [], hashes: {} };
+        const seeded = [];
+        const refreshed = [];
+        const hashes = {};
+        let entries;
+        try {
+            entries = await readdir(this.bundledDir);
+        }
+        catch {
+            return { seeded: [], refreshed: [], hashes: {} };
+        }
+        const bundled = await this.loadBundledNames();
+        for (const entry of entries) {
+            const source = join(this.bundledDir, entry);
+            try {
+                if (!(await stat(source)).isDirectory())
+                    continue;
+                // 先按格式自检一遍包内目录，避免把坏的内置 skill 播进库/覆盖好版本。
+                await this.parseFolder(entry, source, bundled);
+                const libraryPath = join(this.rootDir, entry);
+                const libraryExists = await exists(libraryPath);
+                const bundledHash = await hashSkillFolder(source);
+                if (!seededNames.includes(entry)) {
+                    // 新内置 skill：库里没有就播种；库里已有同名（用户版）不覆盖，只记账。
+                    if (!libraryExists) {
+                        await mkdir(this.rootDir, { recursive: true });
+                        await cp(source, libraryPath, { recursive: true });
+                    }
+                    seeded.push(entry);
+                    hashes[entry] = bundledHash;
+                    continue;
+                }
+                // 已播种：用户删过 → 不复活。
+                if (!libraryExists)
+                    continue;
+                const libraryHash = await hashSkillFolder(libraryPath);
+                if (libraryHash === bundledHash) {
+                    hashes[entry] = bundledHash;
+                    continue;
+                }
+                const recorded = seededHashes[entry];
+                if (recorded === undefined || libraryHash === recorded) {
+                    // 未改动且包内更新（或旧版首次迁移）→ 镜像为包内版本：
+                    // rm + cp，修改/新增/删除全部传播（哈希相等保证库内无用户改动）。
+                    await rm(libraryPath, { recursive: true, force: true });
+                    await cp(source, libraryPath, { recursive: true });
+                    refreshed.push(entry);
+                    hashes[entry] = bundledHash;
+                }
+                // else：用户改过（库内 != 记账哈希）→ 保持不动。
+            }
+            catch (error) {
+                console.warn(`[dsh-post-gen] bundled skill "${entry}" seeding skipped:`, error);
+            }
+        }
+        if (seeded.length > 0 || refreshed.length > 0)
+            this.emitChange();
+        return { seeded, refreshed, hashes };
+    }
+    /** 解析并校验一个 skill 文件夹（SKILL.md frontmatter + 正文生图模板 + 预览图）。 */
+    async parseFolder(folder, dir, bundled) {
+        const rawSkill = await readFile(join(dir, 'SKILL.md'), 'utf8').catch(() => {
+            throw new Error('缺少 SKILL.md');
+        });
+        const match = FRONTMATTER_RE.exec(rawSkill);
+        if (!match)
+            throw new Error('SKILL.md 缺少 YAML frontmatter（--- 包裹的头部）');
+        let frontmatter;
+        try {
+            frontmatter = parseYaml(match[1]);
+        }
+        catch (error) {
+            throw new Error(`SKILL.md frontmatter 不是合法 YAML：${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!frontmatter || typeof frontmatter !== 'object')
+            throw new Error('SKILL.md frontmatter 必须是键值对');
+        const meta = frontmatter;
+        const name = typeof meta.name === 'string' ? meta.name.trim() : '';
+        if (!isSkillName(name))
+            throw new Error(`frontmatter 的 name "${name}" 不合法（需要 kebab-case）`);
+        const description = typeof meta.description === 'string' ? meta.description.trim() : '';
+        if (description === '')
+            throw new Error('frontmatter 缺少 description');
+        const content = match[2].trim();
+        if (content === '')
+            throw new Error('SKILL.md 正文为空（frontmatter 之后需要写生图提示词模板）');
+        const styleTags = Array.isArray(meta.styleTags)
+            ? meta.styleTags.filter((tag) => typeof tag === 'string' && tag.trim() !== '').map((tag) => tag.trim())
+            : [];
+        const previews = await this.resolvePreviews(dir, meta.previews);
+        return {
+            name,
+            title: typeof meta.title === 'string' && meta.title.trim() !== '' ? meta.title.trim() : name,
+            description,
+            ...(typeof meta.whenToUse === 'string' && meta.whenToUse.trim() !== '' ? { whenToUse: meta.whenToUse.trim() } : {}),
+            styleTags,
+            previews,
+            content,
+            bundled: bundled.has(folder) || bundled.has(name),
+        };
+    }
+    /** 解析预览图列表：frontmatter.previews 显式指定优先，缺省扫描 previews/ 目录。 */
+    async resolvePreviews(dir, declared) {
+        if (Array.isArray(declared) && declared.length > 0) {
+            const previews = [];
+            for (const entry of declared.slice(0, SKILL_ZIP_LIMITS.maxPreviews)) {
+                if (typeof entry !== 'string')
+                    continue;
+                const rel = entry.replaceAll('\\', '/').replace(/^\.?\//, '');
+                if (!isSafeRelativePath(rel) || !hasPreviewExtension(rel))
+                    continue;
+                if (await exists(join(dir, ...rel.split('/'))))
+                    previews.push(rel);
+            }
+            return previews;
+        }
+        try {
+            const files = await readdir(join(dir, PREVIEWS_DIR_NAME));
+            return files
+                .filter((file) => hasPreviewExtension(file))
+                .sort()
+                .slice(0, SKILL_ZIP_LIMITS.maxPreviews)
+                .map((file) => `${PREVIEWS_DIR_NAME}/${file}`);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+/** 路径存在性。 */
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 是否允许作为预览图的扩展名。 */
+function hasPreviewExtension(path) {
+    const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase();
+    return PREVIEW_EXTENSIONS.includes(ext);
+}
+/** skill 内相对路径的安全性（posix 形态，无穿越）。 */
+function isSafeRelativePath(path) {
+    if (path === '' || path.startsWith('/') || /^[a-zA-Z]:/.test(path))
+        return false;
+    return path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+/**
+ * 解压 zip 为 { 相对路径: 字节 }，全程做安全与体积校验。
+ * @throws SkillInstallError
+ */
+function extractZipEntries(bytes) {
+    let entries;
+    try {
+        entries = unzipSync(bytes);
+    }
+    catch (error) {
+        throw new SkillInstallError('bad-zip', `不是合法的 zip 文件：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const files = {};
+    let total = 0;
+    const names = Object.keys(entries);
+    if (names.length > SKILL_ZIP_LIMITS.maxEntries) {
+        throw new SkillInstallError('too-large', `压缩包条目超过 ${SKILL_ZIP_LIMITS.maxEntries} 个上限`);
+    }
+    for (const rawName of names) {
+        const name = rawName.replaceAll('\\', '/').replace(/^\.\//, '');
+        if (name.endsWith('/'))
+            continue; // 目录条目
+        if (NOISE_PATTERNS.some((pattern) => pattern.test(name)))
+            continue;
+        if (!isSafeRelativePath(name)) {
+            throw new SkillInstallError('bad-zip', `压缩包内有不合法的路径："${rawName}"`);
+        }
+        const data = entries[rawName];
+        if (data.length > SKILL_ZIP_LIMITS.maxFileBytes) {
+            throw new SkillInstallError('too-large', `文件 "${name}" 超过单文件体积上限`);
+        }
+        total += data.length;
+        if (total > SKILL_ZIP_LIMITS.maxTotalBytes) {
+            throw new SkillInstallError('too-large', '解压后总体积超过上限（疑似 zip bomb）');
+        }
+        files[name] = data;
+    }
+    return files;
+}
+/**
+ * 剥离统一的顶层文件夹：所有文件都不在根时，若共享同一个首段目录则去掉它。
+ * （zip 里直接平铺与包一层文件夹两种打法都接受。）
+ */
+function stripCommonRoot(files) {
+    const names = Object.keys(files);
+    if (names.length === 0)
+        return files;
+    if (names.some((name) => !name.includes('/')))
+        return files; // 根目录已有文件
+    const root = names[0].split('/')[0];
+    if (!names.every((name) => name.startsWith(`${root}/`)))
+        return files;
+    const stripped = {};
+    for (const [name, data] of Object.entries(files))
+        stripped[name.slice(root.length + 1)] = data;
+    return stripped;
+}
+/**
+ * 整文件夹内容哈希（内置 skill 版本迁移的"未改动"判定）：全部文件的
+ * 相对路径 + 字节数 + 内容字节参与摘要（覆盖 SKILL.md 与
+ * previews/ 下任何文件的变化）；文件名排序保证确定性，目录结构变化
+ * （增删文件）也体现在摘要里。
+ */
+async function hashSkillFolder(dir) {
+    const hash = createHash('sha256');
+    const walk = async (current, prefix) => {
+        let entries;
+        try {
+            entries = await readdir(current);
+        }
+        catch {
+            return;
+        }
+        entries.sort();
+        for (const name of entries) {
+            const absolute = join(current, name);
+            const relative = prefix === '' ? name : `${prefix}/${name}`;
+            let info;
+            try {
+                info = await stat(absolute);
+            }
+            catch {
+                continue;
+            }
+            if (info.isDirectory()) {
+                await walk(absolute, relative);
+            }
+            else if (info.isFile()) {
+                hash.update(relative);
+                hash.update('\0');
+                hash.update(String(info.size));
+                hash.update('\0');
+                hash.update(await readFile(absolute));
+                hash.update('\0');
+            }
+        }
+    };
+    await walk(dir, '');
+    return hash.digest('hex');
+}

package/lib/spec.js

@@ -0,0 +1,16 @@
+/**
+ * 海报设计的持久化设置（host settings 文档的 `dsh-post-gen` 命名空间，
+ * 落在 settings.yaml）。
+ *
+ * 自 v0.2 起，海报工作流只负责风格库与工作流剧本；实际生图/编辑/多模态分析
+ * 由 dsh-qw-tool 插件提供（其设置里管理千问 API Key）。故本插件设置不再
+ * 包含 apiKey / 模型组合。
+ */
+import Schema from '@deepseek-ai/schemastery';
+/** settings 文档里本插件的命名空间。 */
+export const SETTINGS_NS = 'dsh-post-gen';
+export const PosterSettingsSchema = Schema.object({
+    enabled: Schema.boolean().default(true),
+    seededBundled: Schema.array(Schema.string()).default([]),
+    seededHashes: Schema.dict(Schema.string()).default({}),
+});

package/lib/tools/get-all-skills.js

@@ -0,0 +1,84 @@
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { GATE_CLOSED_MESSAGE, gateOpen } from '../gate.js';
+import { skillPreviewUrl } from '../shared/skill-format.js';
+export function defineGetAllSkillsTool(deps) {
+    // 与二期同款：exec.arguments 在一次调用内是同一对象引用，做 WeakMap 键关联 trace。
+    const traceByArgs = new WeakMap();
+    return defineTool({
+        name: 'poster_gen_get_all_poster_skills',
+        description: '获取海报风格库（skill 库）的轻量目录：每个已安装海报风格的 name/标题/说明/适用场景/风格标签。目录只含 frontmatter 元数据，不含生图提示词模板正文——模板在 poster_gen_pick_poster_skill 选中某风格后才返回。生成海报前先调它取目录；模型无权记忆库内容，需要时随时重新调用。',
+        parameters: {},
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    skills: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                name: { type: 'string', required: true },
+                                title: { type: 'string', required: true },
+                                description: { type: 'string', required: true },
+                                whenToUse: { type: 'string' },
+                                styleTags: { type: 'array', items: { type: 'string' } },
+                                previews: { type: 'array', items: { type: 'string' } },
+                            },
+                        },
+                    },
+                    invalidFolders: { type: 'integer', required: true, description: '校验失败的文件夹数（不在目录里）' },
+                },
+            },
+            presentationMeta: (args, _value) => (traceByArgs.get(args) ?? { kind: 'poster-skills' }),
+            render: (_args, value) => {
+                const lines = [
+                    `海报风格库共 ${value.skills.length} 个风格：`,
+                    ...value.skills.map((skill) => [
+                        `- ${skill.name}（${skill.title}）：${skill.description}`,
+                        skill.whenToUse ? `  适用：${skill.whenToUse}` : '',
+                        skill.styleTags !== undefined && skill.styleTags.length > 0
+                            ? `  标签：${skill.styleTags.join('、')}`
+                            : '',
+                    ]
+                        .filter((line) => line !== '')
+                        .join('\n')),
+                ];
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(_args, exec) {
+            const settings = deps.scope.get();
+            const trace = deps.hub.begin(exec.callId, { kind: 'poster-skills' });
+            traceByArgs.set(_args, trace);
+            try {
+                const started = Date.now();
+                const { skills, invalid } = await deps.store.scan();
+                if (!gateOpen(settings, skills.length))
+                    throw new Error(GATE_CLOSED_MESSAGE);
+                trace.scanned = { count: skills.length, invalid: invalid.length, durationMs: Date.now() - started };
+                trace.catalog = skills.map((skill) => ({
+                    name: skill.name,
+                    title: skill.title,
+                    styleTags: [...skill.styleTags],
+                }));
+                return {
+                    skills: skills.map((skill) => ({
+                        name: skill.name,
+                        title: skill.title,
+                        description: skill.description,
+                        ...(skill.whenToUse !== undefined ? { whenToUse: skill.whenToUse } : {}),
+                        styleTags: [...skill.styleTags],
+                        previews: skill.previews.map((rel) => skillPreviewUrl(skill.name, rel)),
+                    })),
+                    invalidFolders: invalid.length,
+                };
+            }
+            finally {
+                deps.hub.finish(exec.callId);
+            }
+        },
+    });
+}