@liaozhi/dsh-post-gen 0.1.0

package/lib/poster-service.js

@@ -0,0 +1,128 @@
+import { SKILL_ZIP_LIMITS, skillPreviewUrl } from './shared/skill-format.js';
+import { SkillInstallError } from './skills/store.js';
+/** 海报业务后端服务（RPC 面）。 */
+export class PosterBackend {
+    settings;
+    store;
+    hub;
+    /** Gateway 分发要用的结构化绑定（纯数据，跨模块实例安全）。 */
+    typertRemote = Object.freeze({
+        service: this,
+        serviceKey: 'poster',
+        namespace: 'poster',
+    });
+    constructor(settings, store, hub) {
+        this.settings = settings;
+        this.store = store;
+        this.hub = hub;
+    }
+    // -----------------------------------------------------------------------
+    // RPC 端点：配置读写。
+    // -----------------------------------------------------------------------
+    /** 读取当前配置。 */
+    async getConfig() {
+        return { ok: true, config: { enabled: this.settings.get().enabled } };
+    }
+    /** 保存配置（补丁式合并）。 */
+    async saveConfig(request) {
+        const patch = {};
+        if (typeof request?.enabled === 'boolean')
+            patch.enabled = request.enabled;
+        if (Object.keys(patch).length > 0)
+            await this.settings.update(patch);
+        return { ok: true };
+    }
+    // -----------------------------------------------------------------------
+    // RPC 端点：skill 库。
+    // -----------------------------------------------------------------------
+    /** 列出 skill 库（已安装 skill + 校验失败的文件夹）。 */
+    async listSkills() {
+        try {
+            const { skills, invalid } = await this.store.scan();
+            return { ok: true, skills: skills.map((skill) => this.toSummary(skill)), invalid };
+        }
+        catch (error) {
+            return { ok: false, error: { code: 'store-unavailable', message: error instanceof Error ? error.message : String(error) } };
+        }
+    }
+    /** 上传 zip 安装/更新一个海报 skill。 */
+    async installSkill(request) {
+        const base64 = typeof request?.dataBase64 === 'string' ? request.dataBase64 : '';
+        if (base64 === '') {
+            return { ok: false, error: { code: 'bad-zip', message: '请求里没有 zip 数据' } };
+        }
+        // base64 体积 ≈ 原始 × 4/3：先按编码长度挡掉超限包，避免无谓解码。
+        if (base64.length > Math.ceil(SKILL_ZIP_LIMITS.maxZipBytes * (4 / 3)) + 8) {
+            return {
+                ok: false,
+                error: { code: 'too-large', message: `压缩包超过 ${Math.round(SKILL_ZIP_LIMITS.maxZipBytes / 1024 / 1024)}MB 上限` },
+            };
+        }
+        let bytes;
+        try {
+            bytes = new Uint8Array(Buffer.from(base64, 'base64'));
+        }
+        catch {
+            return { ok: false, error: { code: 'bad-zip', message: 'zip 数据不是合法 base64' } };
+        }
+        try {
+            const { skill, updated } = await this.store.installZip(bytes);
+            return { ok: true, skill: this.toSummary(skill), updated };
+        }
+        catch (error) {
+            if (error instanceof SkillInstallError) {
+                return { ok: false, error: { code: error.code, message: error.message } };
+            }
+            return { ok: false, error: { code: 'io-failed', message: error instanceof Error ? error.message : String(error) } };
+        }
+    }
+    /** 卸载（删除）一个海报 skill 文件夹。 */
+    async uninstallSkill(request) {
+        const name = typeof request?.name === 'string' ? request.name : '';
+        try {
+            const outcome = await this.store.uninstall(name);
+            if (outcome === 'bad-name')
+                return { ok: false, error: { code: 'bad-name', message: `不合法的名字 "${name}"` } };
+            if (outcome === 'not-found')
+                return { ok: false, error: { code: 'not-found', message: `skill "${name}" 不存在` } };
+            if (outcome === 'bundled')
+                return { ok: false, error: { code: 'bundled', message: `内置 skill "${name}" 不可删除` } };
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, error: { code: 'io-failed', message: error instanceof Error ? error.message : String(error) } };
+        }
+    }
+    // -----------------------------------------------------------------------
+    // RPC 端点：渲染节点（trace 轮询 + 候选点选）。
+    // -----------------------------------------------------------------------
+    /** 读某次工具调用的实时步骤 trace（渲染节点轮询用；settle 后事实在 meta）。 */
+    async getCallTrace(request) {
+        const callId = typeof request?.callId === 'string' ? request.callId : '';
+        return { ok: true, trace: callId === '' ? null : this.hub.get(callId) };
+    }
+    /** 提交候选卡片上的用户选择；未知/过期 callId → not-found。 */
+    async answerSkill(request) {
+        const callId = typeof request?.callId === 'string' ? request.callId : '';
+        const skill = typeof request?.skill === 'string' ? request.skill : '';
+        const custom = typeof request?.custom === 'string' ? request.custom : undefined;
+        if (callId === '' || skill === '')
+            return { ok: false, error: { code: 'bad-request' } };
+        if (!this.hub.answer(callId, skill, custom)) {
+            return { ok: false, error: { code: 'not-found', message: '该选择已过期（调用已结束或中断）' } };
+        }
+        return { ok: true };
+    }
+    /** 已安装 skill → 面板摘要（预览图相对路径 → 可渲染 URL）。 */
+    toSummary(skill) {
+        return {
+            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)),
+            bundled: skill.bundled,
+        };
+    }
+}

package/lib/previews-route.js

@@ -0,0 +1,72 @@
+/**
+ * skill 预览图的静态 HTTP 路由（常驻注册，不受门控影响——静态文件本身
+ * 不进模型上下文；skill 库面板直接 <img src> 引用这些 URL）。
+ *
+ * 路由：`GET /plugins/dsh-post-gen/skill-previews/<skill>/<path...>`
+ *   → `<store 根目录>/<skill>/<path...>`。
+ * 安全：skill 段必须是合法 skill 名；相对路径必须无穿越；只放行白名单
+ * 图片后缀；最终落点必须仍在该 skill 文件夹内。
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+import { PREVIEW_CONTENT_TYPES, PREVIEW_ROUTE_PREFIX } from './shared/skill-format.js';
+/**
+ * 注册预览图前缀路由；宿主没有 webServer 服务（非 web 部署）时只告警。
+ *
+ * 路由注册必须挂到调用方 fiber（ctx.effect）：webServer.register 只返回
+ * disposer、不会随 fiber 卸载自动清理。若丢弃 disposer，HMR 重载时旧路由
+ * 残留 → 新 apply 撞 "duplicate prefix route" 抛错 → 整个插件重载失败
+ * （已注册的 typert 端点随新 fiber 回滚撤下且无人重注册，网关永久
+ * "strict definition was withdrawn"）。
+ */
+export function registerPreviewRoute(ctx, storeRoot) {
+    const webServer = ctx.get('webServer');
+    if (webServer === undefined) {
+        console.warn('[dsh-post-gen] webServer service unavailable; skill preview images will not be served');
+        return;
+    }
+    ctx.effect(() => ctx.webServer.register({
+        kind: 'prefix',
+        path: PREVIEW_ROUTE_PREFIX,
+        handler: async (req, res) => {
+            const pathname = decodeURIComponent(new URL(req.url ?? '/', 'http://localhost').pathname);
+            const rest = pathname.slice(PREVIEW_ROUTE_PREFIX.length).replace(/^\/+/, '');
+            const segments = rest.split('/').filter((segment) => segment !== '');
+            const skill = segments[0] ?? '';
+            const relParts = segments.slice(1);
+            const ext = (segments[segments.length - 1] ?? '').split('.').pop()?.toLowerCase() ?? '';
+            const mediaType = PREVIEW_CONTENT_TYPES[ext];
+            // skill 名合法 + 至少一段文件名 + 白名单后缀 + 无路径穿越。
+            const valid = isSkillName(skill) &&
+                relParts.length > 0 &&
+                mediaType !== undefined &&
+                relParts.every((segment) => segment !== '.' && segment !== '..' && !segment.includes('\\'));
+            if (!valid) {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            const skillDir = resolve(storeRoot, skill);
+            const target = resolve(skillDir, ...relParts);
+            if (target !== skillDir && !target.startsWith(skillDir + sep)) {
+                res.statusCode = 404;
+                res.end();
+                return;
+            }
+            try {
+                if (!(await stat(target)).isFile())
+                    throw new Error('not a file');
+                const data = await readFile(target);
+                res.statusCode = 200;
+                res.setHeader('Content-Type', mediaType);
+                res.setHeader('Cache-Control', 'public, max-age=60');
+                res.end(data);
+            }
+            catch {
+                res.statusCode = 404;
+                res.end();
+            }
+        },
+    }), 'dsh-post-gen: skill preview route');
+}

package/lib/shared/disabled-flag.js

@@ -0,0 +1,14 @@
+/**
+ * host 半版本门禁软禁用时的跨进程标记（host → client）。
+ *
+ * host 半（index.ts）软禁用时不注册任何业务能力，只经
+ * `webserver/index-inject` 向 index.html 注入一个全局变量（harness 渲染时
+ * `<` 已转义，值纯 JSON）；client 半（client/index.ts）加载时读取该变量，
+ * 存在即改挂"已停用"说明面板，不存在则走正常注册路径。
+ *
+ * 版本判断逻辑只在 host 半（version-gate.ts）有一份，client 不复制——
+ * 此文件只是两侧共享的常量与载荷形状，不得引入任何 Node 依赖（client
+ * bundle 会内联本文件）。
+ */
+/** 注入 index.html 的全局标记名（`globalThis[DISABLED_GLOBAL]`）。 */
+export const DISABLED_GLOBAL = '__DSH_POST_GEN_DISABLED__';

package/lib/shared/poster-contract.js

@@ -0,0 +1,26 @@
+/**
+ * host 与 client 共享的海报业务 RPC 契约。
+ * 浏览器端经 `ctx.connection.rpc.call('/api', <endpoint>, { args })` 调用
+ * host 半的 `poster` 服务（见 src/index.ts）。
+ * 本模块两端共用：只允许类型与不依赖平台的常量/纯函数。
+ *
+ * 自 v0.2 起仅保留海报工作流自身的端点（风格库 + 配置 + trace/点选）；
+ * 千问 API 调用端点已移交 dsh-qw-tool 插件（其服务 wire namespace 为 qwen）。
+ */
+/** RPC 端点（`<namespace>/<method>`）。 */
+export const POSTER_ENDPOINT = {
+    /** 读取服务端保存的海报设计配置（启用开关）。 */
+    getConfig: 'poster/getConfig',
+    /** 保存海报设计配置（补丁式部分字段）。 */
+    saveConfig: 'poster/saveConfig',
+    /** 列出 skill 库（已安装 skill + 校验失败的文件夹）。 */
+    listSkills: 'poster/listSkills',
+    /** 上传 zip 安装/更新一个海报 skill。 */
+    installSkill: 'poster/installSkill',
+    /** 卸载（删除）一个海报 skill 文件夹。 */
+    uninstallSkill: 'poster/uninstallSkill',
+    /** 读某次工具调用的实时步骤 trace（运行中加速器；settle 后用 meta）。 */
+    getCallTrace: 'poster/getCallTrace',
+    /** 提交 poster_gen_pick_poster_skill 候选卡片上的用户选择。 */
+    answerSkill: 'poster/answerSkill',
+};

package/lib/shared/poster-trace.js

@@ -0,0 +1,109 @@
+// ---------------------------------------------------------------------------
+// 宽容解析（client 渲染 meta / RPC 快照用；结构不符降级为 undefined）。
+// ---------------------------------------------------------------------------
+function str(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/** 宽容解析 skill 库扫描 trace。 */
+export function parseSkillsTrace(meta) {
+    if (!meta || typeof meta !== 'object')
+        return undefined;
+    const t = meta;
+    if (t.kind !== 'poster-skills')
+        return undefined;
+    const trace = { kind: 'poster-skills' };
+    if (t.scanned && typeof t.scanned === 'object') {
+        const s = t.scanned;
+        const count = num(s.count);
+        if (count !== undefined) {
+            trace.scanned = {
+                count,
+                invalid: num(s.invalid) ?? 0,
+                ...(num(s.durationMs) !== undefined ? { durationMs: num(s.durationMs) } : {}),
+            };
+        }
+    }
+    if (Array.isArray(t.catalog)) {
+        trace.catalog = t.catalog
+            .map((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return undefined;
+            const e = entry;
+            const name = str(e.name);
+            if (name === undefined)
+                return undefined;
+            return {
+                name,
+                title: str(e.title) ?? name,
+                styleTags: Array.isArray(e.styleTags) ? e.styleTags.filter((tag) => typeof tag === 'string') : [],
+            };
+        })
+            .filter((entry) => entry !== undefined);
+    }
+    return trace;
+}
+/** 宽容解析候选点选 trace。 */
+export function parsePickTrace(meta) {
+    if (!meta || typeof meta !== 'object')
+        return undefined;
+    const t = meta;
+    if (t.kind !== 'poster-pick')
+        return undefined;
+    const params = (t.params ?? {});
+    const candidates = Array.isArray(params.candidates)
+        ? params.candidates
+            .map((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return undefined;
+            const e = entry;
+            const name = str(e.name);
+            if (name === undefined)
+                return undefined;
+            return { name, reason: str(e.reason) ?? '', ...(str(e.title) !== undefined ? { title: str(e.title) } : {}) };
+        })
+            .filter((entry) => entry !== undefined)
+        : [];
+    const trace = {
+        kind: 'poster-pick',
+        params: {
+            candidates,
+            ...(str(params.question) !== undefined ? { question: str(params.question) } : {}),
+        },
+    };
+    if (Array.isArray(t.options)) {
+        trace.options = t.options
+            .map((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return undefined;
+            const e = entry;
+            const name = str(e.name);
+            const title = str(e.title);
+            if (name === undefined || title === undefined)
+                return undefined;
+            return {
+                name,
+                title,
+                reason: str(e.reason) ?? '',
+                previews: Array.isArray(e.previews) ? e.previews.filter((p) => typeof p === 'string') : [],
+                ...(str(e.prompt) !== undefined ? { prompt: str(e.prompt) } : {}),
+            };
+        })
+            .filter((entry) => entry !== undefined);
+    }
+    if (t.answer && typeof t.answer === 'object') {
+        const a = t.answer;
+        const chosenSkill = str(a.chosenSkill);
+        const chosenTitle = str(a.chosenTitle);
+        if (chosenSkill !== undefined && chosenTitle !== undefined) {
+            trace.answer = {
+                chosenSkill,
+                chosenTitle,
+                ...(str(a.custom) !== undefined ? { custom: str(a.custom) } : {}),
+            };
+        }
+    }
+    return trace;
+}

package/lib/shared/skill-format.js

@@ -0,0 +1,69 @@
+/**
+ * 海报 skill 的文件夹格式约定（host 与 client 共用的纯数据模块）。
+ *
+ * 一个海报 skill = 一个文件夹（可打成 zip 在设置面板上传安装）：
+ *
+ * ```
+ * poster-example-skill/          # 文件夹名随意（canonical 名以 SKILL.md 为准）
+ * ├── SKILL.md                    # 必需。YAML frontmatter + 生图提示词模板（正文）
+ * └── previews/                   # 可选但强烈建议。预览图，skill 库里直观展示
+ *     ├── 1.png
+ *     └── 2.png
+ * ```
+ *
+ * SKILL.md frontmatter：
+ * ```yaml
+ * ---
+ * name: poster-example-skill     # 必需，kebab-case，全库唯一
+ * title: 节日促销海报              # 可选，展示名（缺省用 name）
+ * description: 一句话说明          # 必需（推荐筛选 + skill 库展示；目录不返回
+ *                                  #   正文，description 要写准该 skill 生成海报
+ *                                  #   的视觉效果——这是模型路由的主要信号）
+ * whenToUse: 适用场景              # 可选（模型路由提示）
+ * styleTags: [促销, 节日]          # 可选（推荐筛选信号）
+ * previews: [previews/1.png]      # 可选；缺省自动扫描 previews/ 目录
+ * ---
+ * ```
+ *
+ * frontmatter 之后的正文 = 该 skill 的**生图提示词模板**：占位符
+ * `{{styleBrief}}`（用户描述 + 补充 + 选择理由汇总成的风格简报）、
+ * `{{requirements}}`（用户的其他约束），生成时替换后提交给生图模型。目录
+ * 原语只返回 frontmatter 元数据，正文（模板）在点选原语选中该 skill 后才返回。
+ *
+ * zip 要求：文件可以直接位于压缩包根，或统一包在一层顶层文件夹里；
+ * 校验规则与安全上限见下面的常量。完整说明见 docs/poster-skill-format.md。
+ */
+/** skill 预览图的 HTTP 路由前缀（host 半常驻注册，见 src/previews-route.ts）。 */
+export const PREVIEW_ROUTE_PREFIX = '/plugins/dsh-post-gen/skill-previews';
+/** skill 文件夹内的预览图相对路径 → 可渲染的 URL（面板与候选卡片共用）。 */
+export function skillPreviewUrl(skillName, rel) {
+    return `${PREVIEW_ROUTE_PREFIX}/${skillName}/${rel.split('/').map(encodeURIComponent).join('/')}`;
+}
+/** 允许作为预览图/随包图片的扩展名。 */
+export const PREVIEW_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'svg', 'gif'];
+/** 预览图扩展名 → Content-Type。 */
+export const PREVIEW_CONTENT_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    gif: 'image/gif',
+};
+/** 预览图的自动扫描目录（skill 文件夹内）。 */
+export const PREVIEWS_DIR_NAME = 'previews';
+/** 生图提示词模板（SKILL.md 正文）的占位符。 */
+export const CONTENT_PLACEHOLDERS = ['{{styleBrief}}', '{{requirements}}'];
+/** zip 安装的安全上限。 */
+export const SKILL_ZIP_LIMITS = {
+    /** 压缩包体积上限（字节）。 */
+    maxZipBytes: 20 * 1024 * 1024,
+    /** 解压后总体积上限（字节，防 zip bomb）。 */
+    maxTotalBytes: 80 * 1024 * 1024,
+    /** 单文件体积上限。 */
+    maxFileBytes: 20 * 1024 * 1024,
+    /** 条目数上限。 */
+    maxEntries: 200,
+    /** 单个 skill 的预览图数量上限。 */
+    maxPreviews: 8,
+};