@fecommunity/reactpress 4.0.0-beta.15 → 4.0.0-beta.17

package/plugins/hello-world/README.md

@@ -0,0 +1,104 @@
+# hello-world (Auto Summary)
+
+Official example plugin — **auto-fill article summary on publish** when empty. Template for custom ReactPress plugins.
+
+> Part of the ReactPress publishing platform · [plugin system docs](../README.md)
+
+- **Plugin id**: `hello-world` (historical id, unchanged)
+- **Display name**: Auto Summary
+- **Version**: see [`plugin.json`](./plugin.json)
+
+## Features
+
+| Scenario | Behavior |
+| :--- | :--- |
+| Summary already set on publish | No change |
+| Summary empty, body has content | Strip Markdown, truncate, write `summary` |
+| Summary and body both empty | Use title if `fallbackToTitle` is enabled |
+
+## Hooks
+
+Subscribes to a single hook with a focused responsibility:
+
+| Hook | Type | Description |
+| :--- | :--- | :--- |
+| `article.beforePublish` | filter | Fill in `summary` before publish |
+
+## Configuration
+
+Declared via `plugin.json` → `settings.schema`, stored in `globalSetting.plugins.entries.hello-world.config`.
+
+Admin UI strings (plugin name, descriptions, field labels) live in [`locales/`](./locales/) (`locales/{locale}.json`), following the same convention as themes; Chinese strings in `plugin.json` serve as fallback.
+
+| Field | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `enabled` | boolean | `true` | Enable auto summary |
+| `maxLength` | number | `160` | Max length (40–500) |
+| `suffix` | string | `…` | Suffix when truncated |
+| `fallbackToTitle` | boolean | `true` | Use title when body is empty |
+
+Update config (admin login required):
+
+```bash
+curl -X PUT http://localhost:3002/api/extension/plugins/hello-world/config \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"config":{"enabled":true,"maxLength":120}}'
+```
+
+Config save triggers an automatic plugin reload — no server restart needed.
+
+## Usage
+
+1. `pnpm dev` (plugins are compiled automatically)
+2. Admin → **Plugins** → install **hello-world** → **Enable**
+3. Click **Settings** on the plugin row (or visit `/admin/plugins/hello-world/settings`)
+4. Leave summary empty when writing → publish → summary field should be auto-filled
+
+Example server logs:
+
+```text
+[PluginService] [hello-world] registered (enabled=true, maxLength=160)
+[PluginLoaderService] Loaded plugin "hello-world" v1.2.0
+```
+
+## Directory structure
+
+```
+hello-world/
+├── plugin.json
+├── package.json
+├── tsconfig.json
+├── README.md
+└── src/
+    ├── index.ts      # register() entry
+    ├── config.ts     # defaults and merge
+    ├── summary.ts    # Markdown strip + truncate
+    └── types.ts
+        ↓ tsc
+    dist/
+    └── index.js      # runtime loads this file
+```
+
+## Development
+
+```bash
+# from monorepo root
+pnpm --filter @reactpress/plugin-hello-world run build
+pnpm --filter @reactpress/plugin-hello-world run typecheck
+
+# after editing src, rebuild and deactivate → reactivate in admin
+```
+
+Dependencies:
+
+- `@fecommunity/reactpress-toolkit/plugin/server` — `HookService`, `PluginContext` types
+
+## Use as a new plugin template
+
+1. Copy this directory to `plugins/my-plugin/`
+2. Update `plugin.json` `id`, `name`, `hooks.subscribe`
+3. Rewrite `src/index.ts` and business modules
+4. Add the id to [`plugins/package.json`](../package.json) → `local` list
+
+See [`../README.md`](../README.md) for the plugin system overview.

package/plugins/hello-world/dist/config.d.ts

@@ -0,0 +1,4 @@
+import type { PluginContext } from '@fecommunity/reactpress-toolkit/plugin/server';
+import type { SummaryPluginConfig } from './types';
+export declare const DEFAULT_CONFIG: SummaryPluginConfig;
+export declare function resolveConfig(ctx: PluginContext): SummaryPluginConfig;

package/plugins/hello-world/dist/config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIG = void 0;
+exports.resolveConfig = resolveConfig;
+exports.DEFAULT_CONFIG = {
+    enabled: true,
+    maxLength: 160,
+    suffix: '…',
+    fallbackToTitle: true,
+};
+function resolveConfig(ctx) {
+    const patch = ctx.config;
+    return {
+        ...exports.DEFAULT_CONFIG,
+        ...patch,
+    };
+}

package/plugins/hello-world/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { HookService, PluginContext } from '@fecommunity/reactpress-toolkit/plugin/server';
+/**
+ * hello-world：自动摘要插件。
+ * 发布前若 summary 为空，从 Markdown 正文（或标题）生成摘要。
+ */
+export declare function register(hooks: HookService, ctx: PluginContext): void;
+declare const _default: {
+    register: typeof register;
+};
+export default _default;

package/plugins/hello-world/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const config_1 = require("./config");
+const summary_1 = require("./summary");
+/**
+ * hello-world：自动摘要插件。
+ * 发布前若 summary 为空，从 Markdown 正文（或标题）生成摘要。
+ */
+function register(hooks, ctx) {
+    const config = () => (0, config_1.resolveConfig)(ctx);
+    hooks.addFilter('article.beforePublish', async (article) => (0, summary_1.applyAutoSummary)(article, config()), { priority: 10, pluginId: ctx.id });
+    ctx.logger.log(`registered (enabled=${config().enabled}, maxLength=${config().maxLength})`);
+}
+exports.default = { register };

package/plugins/hello-world/dist/summary.d.ts

@@ -0,0 +1,3 @@
+import type { ArticleDraft, SummaryPluginConfig } from './types';
+/** 摘要为空时从正文（或标题）生成 summary。 */
+export declare function applyAutoSummary(article: ArticleDraft, config: SummaryPluginConfig): ArticleDraft;

package/plugins/hello-world/dist/summary.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyAutoSummary = applyAutoSummary;
+function stripMarkdown(text) {
+    return String(text || '')
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/`[^`]+`/g, ' ')
+        .replace(/!\[[^\]]*]\([^)]+\)/g, ' ')
+        .replace(/\[([^\]]*)]\([^)]+\)/g, '$1')
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/^>\s?/gm, '')
+        .replace(/[*_~`]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** 摘要为空时从正文（或标题）生成 summary。 */
+function applyAutoSummary(article, config) {
+    if (!config.enabled)
+        return article;
+    const existing = String(article.summary ?? '').trim();
+    if (existing)
+        return article;
+    const content = stripMarkdown(String(article.content ?? article.html ?? ''));
+    const title = String(article.title ?? '').trim();
+    const source = content || (config.fallbackToTitle ? title : '');
+    if (!source)
+        return article;
+    const max = Math.max(40, config.maxLength);
+    let summary = source.slice(0, max);
+    if (source.length > max)
+        summary += config.suffix;
+    return { ...article, summary };
+}

package/plugins/hello-world/dist/types.d.ts

@@ -0,0 +1,16 @@
+/** 插件 Hook 使用的文章字段子集。 */
+export interface ArticleDraft {
+    title?: string;
+    summary?: string | null;
+    content?: string | null;
+    html?: string | null;
+    [key: string]: unknown;
+}
+export interface SummaryPluginConfig {
+    /** 发布时摘要为空则自动生成 */
+    enabled: boolean;
+    maxLength: number;
+    suffix: string;
+    /** 正文为空时是否回退到标题 */
+    fallbackToTitle: boolean;
+}

package/plugins/hello-world/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/plugins/hello-world/locales/en.json

@@ -0,0 +1,24 @@
+{
+  "meta": {
+    "name": "Auto Summary",
+    "description": "When publishing, if the summary is empty, generate one from the body or title."
+  },
+  "settings": {
+    "enabled": {
+      "title": "Enable auto summary",
+      "description": "When disabled, summary is not auto-filled on publish."
+    },
+    "maxLength": {
+      "title": "Maximum length",
+      "description": "Max characters taken from the body (40–500)."
+    },
+    "suffix": {
+      "title": "Truncation suffix",
+      "description": "Appended when content exceeds max length, e.g. …"
+    },
+    "fallbackToTitle": {
+      "title": "Use title when body is empty",
+      "description": "When stripped Markdown body is empty, use the article title as summary."
+    }
+  }
+}

package/plugins/hello-world/locales/zh.json

@@ -0,0 +1,24 @@
+{
+  "meta": {
+    "name": "自动摘要",
+    "description": "发布文章时，若摘要为空，从正文或标题自动生成 summary。"
+  },
+  "settings": {
+    "enabled": {
+      "title": "启用自动摘要",
+      "description": "关闭后，发布时不再自动写入 summary。"
+    },
+    "maxLength": {
+      "title": "摘要最大长度",
+      "description": "从正文截取的最大字符数（40–500）。"
+    },
+    "suffix": {
+      "title": "截断后缀",
+      "description": "超出最大长度时追加在末尾，例如 …"
+    },
+    "fallbackToTitle": {
+      "title": "正文为空时使用标题",
+      "description": "Markdown 正文去格式后为空时，用文章标题作为摘要。"
+    }
+  }
+}

package/plugins/hello-world/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@fecommunity/reactpress-plugin-hello-world",
+  "version": "1.2.0",
+  "private": true,
+  "description": "Auto summary plugin for ReactPress",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@fecommunity/reactpress-toolkit": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  }
+}

package/plugins/hello-world/plugin.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "../plugin.manifest.schema.json",
+  "id": "hello-world",
+  "name": "自动摘要",
+  "version": "1.2.0",
+  "description": "发布文章时，若摘要为空，从正文或标题自动生成 summary。",
+  "author": "ReactPress",
+  "requires": ">=3.5.0",
+  "server": {
+    "module": "./dist/index.js",
+    "hooks": {
+      "subscribe": ["article.beforePublish"]
+    }
+  },
+  "admin": {
+    "menu": {
+      "title": "自动摘要",
+      "path": "/plugins/hello-world/settings",
+      "permission": "extension:manage",
+      "sort": 10
+    }
+  },
+  "settings": {
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "title": "启用自动摘要",
+          "description": "关闭后，发布时不再自动写入 summary。",
+          "default": true
+        },
+        "maxLength": {
+          "type": "integer",
+          "title": "摘要最大长度",
+          "description": "从正文截取的最大字符数（40–500）。",
+          "minimum": 40,
+          "maximum": 500,
+          "default": 160
+        },
+        "suffix": {
+          "type": "string",
+          "title": "截断后缀",
+          "description": "超出最大长度时追加在末尾，例如 …",
+          "default": "…"
+        },
+        "fallbackToTitle": {
+          "type": "boolean",
+          "title": "正文为空时使用标题",
+          "description": "Markdown 正文去格式后为空时，用文章标题作为摘要。",
+          "default": true
+        }
+      }
+    }
+  },
+  "permissions": ["article:read"],
+  "capabilities": {
+    "headless": true
+  }
+}

package/plugins/hello-world/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/plugins/image-optimizer/README.md

@@ -0,0 +1,43 @@
+# image-optimizer (Image Asset Optimization)
+
+Official plugin — **analyze legacy uploads and batch-compress to WebP multi-size variants**, with optional content URL rewrite.
+
+> Improve Lighthouse and page weight without leaving Admin
+
+- **Plugin id**: `image-optimizer`
+- **Version**: see [`plugin.json`](./plugin.json)
+
+## Features
+
+| Capability | Description |
+| :--- | :--- |
+| Batch optimization | Process historical uploads via Core `FileOptimizationService` |
+| WebP variants | Generate compressed multi-size WebP outputs |
+| URL rewrite | Optionally replace old image URLs in article/page content after batch run |
+| Admin dashboard | Full UI at **Plugins → Image Optimization** |
+
+Batch compression is executed by the core file optimization service; this plugin registers configuration and exposes the admin dashboard (`admin/OptimizeDashboard`).
+
+## Configuration
+
+| Field | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `batchSize` | integer | `50` | Max images per batch (1–200) |
+| `skipGif` | boolean | `true` | Skip GIF (WebP conversion loses animation) |
+| `rewriteContent` | boolean | `false` | Rewrite article/page image URLs after optimization |
+| `cleanupOriginals` | boolean | `false` | Delete original files after optimization (irreversible) |
+
+## Usage
+
+1. `pnpm dev` (plugins are compiled automatically)
+2. Admin → **Plugins** → install **Image Optimization** → **Enable**
+3. Open **Plugins → Image Optimization** to run batch jobs and review results
+
+## Development
+
+```bash
+pnpm --filter @fecommunity/reactpress-plugin-image-optimizer run build
+pnpm --filter @fecommunity/reactpress-plugin-image-optimizer run typecheck
+```
+
+See [`../README.md`](../README.md) for the plugin system overview.

package/plugins/image-optimizer/admin/OptimizeDashboard.tsx

@@ -0,0 +1,249 @@
+import type { PluginSettingsPanelProps } from "@fecommunity/reactpress-toolkit/plugin/admin";
+import { App, Button, Progress, Spin } from "antd";
+import { useEffect, useRef, useState } from "react";
+
+import {
+  fetchOptimizeJob,
+  fetchOptimizeReport,
+  readApiErrorMessage,
+  startOptimizeJob,
+  type ImageOptimizeReport,
+  type OptimizeJob,
+} from "./api";
+import { usePluginDashboardText } from "./locale";
+
+import styles from "./optimize-dashboard.module.css";
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+function resolveConfig(config: Record<string, unknown>) {
+  const batchSize = Number(config.batchSize);
+  return {
+    batchSize: Number.isFinite(batchSize) ? Math.min(Math.max(batchSize, 1), 200) : 50,
+    skipGif: config.skipGif !== false,
+    rewriteContent: config.rewriteContent === true,
+    cleanupOriginals: config.cleanupOriginals === true,
+  };
+}
+
+export function OptimizeDashboard({ pluginId, pluginActive, config }: PluginSettingsPanelProps) {
+  const { message } = App.useApp();
+  const t = usePluginDashboardText(pluginId);
+
+  const [report, setReport] = useState<ImageOptimizeReport | null>(null);
+  const [job, setJob] = useState<OptimizeJob | null>(null);
+  const [loadingReport, setLoadingReport] = useState(false);
+  const [startingJob, setStartingJob] = useState(false);
+  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  const stopPolling = useCallback(() => {
+    if (pollRef.current) {
+      clearInterval(pollRef.current);
+      pollRef.current = null;
+    }
+  }, []);
+
+  const loadReport = useCallback(async () => {
+    setLoadingReport(true);
+    try {
+      const data = await fetchOptimizeReport();
+      setReport(data);
+    } catch (err) {
+      message.error(readApiErrorMessage(err, t("analyzeFailed", "分析失败")));
+    } finally {
+      setLoadingReport(false);
+    }
+  }, [message, t]);
+
+  const pollJob = useCallback(
+    (jobId: string) => {
+      stopPolling();
+
+      const refresh = () => {
+        void fetchOptimizeJob(jobId)
+          .then((next) => {
+            setJob(next);
+            if (next.status === "completed" || next.status === "failed") {
+              stopPolling();
+              void loadReport();
+            }
+          })
+          .catch((err) => {
+            stopPolling();
+            message.error(readApiErrorMessage(err, t("jobPollFailed", "获取任务进度失败")));
+          });
+      };
+
+      refresh();
+      pollRef.current = setInterval(refresh, 800);
+    },
+    [loadReport, message, stopPolling, t],
+  );
+
+  useEffect(() => {
+    if (pluginActive) {
+      void loadReport();
+    }
+  }, [loadReport, pluginActive]);
+
+  useEffect(() => () => stopPolling(), [stopPolling]);
+
+  const runJob = async (dryRun: boolean) => {
+    if (!pluginActive) return;
+    const opts = resolveConfig(config);
+    setStartingJob(true);
+    try {
+      const started = await startOptimizeJob({
+        dryRun,
+        batchSize: opts.batchSize,
+        limit: opts.batchSize,
+        skipGif: opts.skipGif,
+        rewriteContent: opts.rewriteContent,
+        cleanupOriginals: opts.cleanupOriginals,
+      });
+      setJob(started);
+      if (started.status === "completed" || started.status === "failed") {
+        void loadReport();
+        if (started.total === 0) {
+          message.info(t("jobEmpty", "没有待优化的图片（可能已全部优化，或原文件已不存在）。"));
+        } else if (dryRun) {
+          message.success(t("dryRunDone", "试运行完成（未写入数据库）。"));
+        }
+      } else {
+        pollJob(started.id);
+        if (dryRun) {
+          message.info(t("dryRun", "试运行（不写入）"));
+        }
+      }
+    } catch (err) {
+      message.error(readApiErrorMessage(err, t("runFailed", "启动任务失败")));
+    } finally {
+      setStartingJob(false);
+    }
+  };
+
+  if (!pluginActive) {
+    return (
+      <div className={styles.warn} data-testid="image-optimizer-inactive">
+        {t("inactiveHint", "请先在插件列表中启用本插件，才能执行分析与优化。")}
+      </div>
+    );
+  }
+
+  const jobRunning = job?.status === "pending" || job?.status === "running";
+  const jobDone = job?.status === "completed" || job?.status === "failed";
+  const jobPercent =
+    job && job.total > 0 ? Math.round((job.processed / job.total) * 100) : undefined;
+  const failedItems = job?.items.filter((item) => item.status === "failed").slice(0, 5) ?? [];
+
+  return (
+    <div className={styles.optimizeDashboard} data-testid="image-optimizer-dashboard">
+      <h2 className={styles.sectionTitle}>{t("title", "资源分析")}</h2>
+
+      <div className={styles.actions}>
+        <Button loading={loadingReport} onClick={() => void loadReport()}>
+          {t("analyze", "分析现状")}
+        </Button>
+        <Button loading={startingJob} onClick={() => void runJob(true)}>
+          {t("dryRun", "试运行（不写入）")}
+        </Button>
+        <Button type="primary" loading={startingJob || jobRunning} onClick={() => void runJob(false)}>
+          {t("run", "开始批量优化")}
+        </Button>
+      </div>
+
+      {loadingReport && !report ? (
+        <Spin />
+      ) : report ? (
+        <div className={styles.statsGrid}>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("total", "素材总数")}</p>
+            <p className={styles.statValue}>{report.total}</p>
+          </div>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("optimized", "已优化")}</p>
+            <p className={styles.statValue}>{report.alreadyOptimized}</p>
+          </div>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("pending", "待优化")}</p>
+            <p className={styles.statValue}>{report.needsOptimization}</p>
+          </div>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("estimatedSaved", "预估可节省")}</p>
+            <p className={styles.statValue}>{formatBytes(report.storageBytes.estimatedSaved)}</p>
+          </div>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("contentRefs", "内容引用")}</p>
+            <p className={styles.statValue}>
+              {report.contentRefs.articles} {t("articles", "文章")} / {report.contentRefs.pages}{" "}
+              {t("pages", "页面")}
+            </p>
+          </div>
+          <div className={styles.statCard}>
+            <p className={styles.statLabel}>{t("skipped", "已跳过")}</p>
+            <p className={styles.statValue}>
+              {report.skipped.nonImage + report.skipped.svg + report.skipped.gif + report.skipped.missing}
+            </p>
+          </div>
+        </div>
+      ) : null}
+
+      {job ? (
+        <div className={styles.progressBlock}>
+          <Progress
+            percent={jobPercent}
+            status={
+              job.status === "failed"
+                ? "exception"
+                : jobRunning
+                  ? "active"
+                  : job.total === 0
+                    ? "normal"
+                    : "success"
+            }
+            showInfo={job.total > 0}
+          />
+          <p className={styles.hint}>
+            {job.status === "failed"
+              ? `${t("jobFailed", "任务失败")}: ${job.error ?? ""}`
+              : jobRunning
+                ? job.total === 0
+                  ? t("jobScanning", "正在扫描待优化素材…")
+                  : t("jobRunning", "优化任务进行中…")
+                : t("jobDone", "任务已完成")}
+            {" · "}
+            {t("processed", "已处理")} {job.processed}/{job.total} · {t("succeeded", "成功")}{" "}
+            {job.succeeded} · {t("failed", "失败")} {job.failed}
+            {job.savedBytes > 0 ? ` · ${t("savedBytes", "已节省空间")} ${formatBytes(job.savedBytes)}` : ""}
+          </p>
+          {jobDone && job.total === 0 ? (
+            <p className={styles.emptyJob}>
+              {t("jobEmpty", "没有待优化的图片（可能已全部优化，或原文件已不存在）。")}
+            </p>
+          ) : null}
+          {job.contentRewrite ? (
+            <p className={styles.hint}>
+              URL 回写：{job.contentRewrite.articles} {t("articles", "文章")}、{job.contentRewrite.pages}{" "}
+              {t("pages", "页面")}、{job.contentRewrite.revisions} 修订
+            </p>
+          ) : null}
+          {failedItems.length > 0 ? (
+            <ul className={styles.errorList}>
+              {failedItems.map((item) => (
+                <li key={item.fileId}>
+                  {item.originalname}: {item.error}
+                </li>
+              ))}
+            </ul>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export { OptimizeDashboard as SettingsPanel };