@akairos/pipeline 0.18.5 → 0.19.0

package/README.md

@@ -160,7 +160,7 @@ Pipeline 在创建和更新草稿时，会自动读取封面图真实尺寸，
 | **`@akairos/milkdown-article-plugins`** | Remark / Milkdown 全语法自定义解析与渲染插件 |
 | **`@akairos/typeset-studio`** | 微信大图头图、多比例排版与卡片视觉合成引擎 |
 
-配置在 `plugins.imageRenderer` / `plugins.markdownRenderer` 的外部插件在独立 Bun 子进程中加载和执行。加载与 doctor 默认上限为 10 秒，渲染为 120 秒；Markdown 渲染显式传入 `timeoutMs` 时，子进程上限额外预留 10 秒。可通过 `ZZHUB_PIPELINE_PLUGIN_TIMEOUT_MS` 覆盖调用上限。同步死循环、超时和异常退出会终止插件进程，非法返回值会给出 `PLUGIN_*` 错误，命令不会自动重试或静默切换模板。
+配置在 `plugins.imageRenderer` / `plugins.markdownRenderer` 的外部插件在独立 Bun 子进程中加载，插件的 `render`、`doctor`、`browser` 和 `studio` 方法也在子进程调用。加载、资源入口查询与 doctor 默认上限为 10 秒，`render` 为 120 秒；Markdown 渲染显式传入 `timeoutMs` 时，子进程上限额外预留 10 秒。可通过 `ZZHUB_PIPELINE_PLUGIN_TIMEOUT_MS` 覆盖子进程调用上限。同步死循环、超时和异常退出会终止插件进程，非法返回值会给出 `PLUGIN_*` 错误，命令不会自动重试或静默切换模板。浏览器型插件返回入口后，由 pipeline 现有 Chrome 运行时加载页面，并按渲染 `timeoutMs` 管理浏览器生命周期。
 
 图片渲染失败后任务进入失败状态，保留正文与审核结果。修复插件后执行 `zzp reset --state <state_path> --mode render`，再继续任务；也可以将对应的 `plugins.*Renderer` 配置设为 `null` 使用内置渲染器。外部插件通过 `onProgress` 回传进度，不应依赖修改输入对象或跨调用保存内存状态。子进程继承当前环境和文件权限，这一机制负责故障隔离，不是权限沙箱。
 
@@ -170,6 +170,27 @@ Pipeline 在创建和更新草稿时，会自动读取封面图真实尺寸，
 
 旧的字符串入口继续有效，等同于没有配置专属参数；`null` 使用内置渲染器。`zzp config --import` 中的渲染器条目整体替换原条目，只改一个参数时使用 `--key plugins.imageRenderer.options.<参数名>`。
 
+### myno 排版插件
+
+myno 通过可选的 Markdown 渲染插件接入。从 pipeline 0.19.0 起可选依赖固定为 `@akairos/myno@0.3.0`，仍需在配置中显式启用；使用 `--omit optional` 安装时需自行提供插件。npm 配置示例：
+
+```json
+{
+  "plugins": {
+    "markdownRenderer": {
+      "module": "@akairos/myno/adapter",
+      "options": {}
+    }
+  }
+}
+```
+
+本地开发时可先在 myno 仓库执行 `bun run build`，将 `module` 指向构建后的 `dist/adapter.js` 绝对路径。运行时部署包只接受 npm 入口和空 `options`，不会复制本机插件路径。
+
+插件可以实现原有的 `render(input, options)`，也可以像 myno 一样只实现 `browser(options)`，返回浏览器排版入口的绝对路径 `{ scriptPath }`。`wechat-export` 和公众号文章发布通过同一个插件加载器调度；浏览器型插件复用 pipeline 现有的 Chrome、超时清理、离线模板校验和文件输出，仅页面排版实现来自插件。myno 不增加浏览器自动化依赖，调样式和导出 config 也不需要启动无头浏览器。独立样式仍与发布账号分离。
+
+Markdown 插件可选提供 `studio(options)`，返回绝对资源目录 `root` 和该目录内的 HTML 相对路径 `entry`。`zzp wechat-preview studio` 将插件页面挂到 `/studio`，脚本和样式挂到 `/studio-assets/`；`/api/studio/config`、`/api/studio/save-config` 和历史记录继续由 pipeline 提供。插件不支持 Studio 时返回明确提示；配置为 `null` 保留内置工作台。切换插件后需重启已运行的预览服务。
+
 ### Typeset Studio 插件配置
 
 Pipeline 已通过 npm 依赖 `@akairos/typeset-studio`。在本地配置文件启用适配器，并指定与 Studio 编辑器共用的数据目录：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/pipeline",
-  "version": "0.18.5",
+  "version": "0.19.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -29,13 +29,14 @@
   "dependencies": {
     "@akairos/milkdown-article-plugins": "^0.1.6",
     "@akairos/milkdown-article-style": "^0.1.2",
-    "@akairos/typeset-studio": "0.2.5",
+    "@akairos/typeset-studio": "0.2.6",
     "@chenglou/pretext": "0.0.8",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",
     "zod": "^4.4.2"
   },
   "optionalDependencies": {
+    "@akairos/myno": "0.3.0",
     "@napi-rs/canvas": "^0.1.97",
     "cos-nodejs-sdk-v5": "^2.15.4"
   },

package/src/adapter-loader.ts

@@ -15,7 +15,10 @@ import type {
 } from "./adapter-types";
 import { builtinImageRenderer } from "./adapters/builtin-image-renderer";
 import { builtinMarkdownRenderer } from "./adapters/builtin-markdown-renderer";
-import { PluginDoctorSchema, PluginImageOutputSchema, PluginMarkdownOutputSchema, PluginMetadataSchema, runExternalPlugin } from "./plugin-runtime";
+import { PluginBrowserSchema, PluginDoctorSchema, PluginImageOutputSchema, PluginMarkdownOutputSchema, PluginMetadataSchema, PluginStudioSchema, runExternalPlugin } from "./plugin-runtime";
+import { exportMarkdownToWechatHtml } from "./wechat-preview";
+import { notifyProgress } from "./monitor/recorder";
+import { findChrome } from "./imgx/runtime";
 
 // ── Public API ───────────────────────────────────────────────────
 
@@ -75,9 +78,26 @@ export async function resolveMarkdownRenderer(
     return {
       name: metadata.name,
       version: metadata.version,
-      ...(metadata.hasDoctor ? { doctor: () => runExternalPlugin(pluginPath, "doctor", PluginDoctorSchema, undefined, { options }) } : {}),
-      render: ({ onProgress, ...input }) => runExternalPlugin(pluginPath, "render", PluginMarkdownOutputSchema, input, { options }, onProgress,
-        input.timeoutMs && Number.isFinite(input.timeoutMs) && input.timeoutMs > 0 ? input.timeoutMs + 10_000 : 120_000),
+      ...(metadata.hasDoctor || metadata.hasBrowser ? { doctor: async () => {
+        const checks = metadata.hasDoctor ? await runExternalPlugin(pluginPath, "doctor", PluginDoctorSchema, undefined, { options }) : [];
+        if (metadata.hasBrowser) {
+          const chrome = findChrome();
+          checks.push({ name: "chrome", ok: Boolean(chrome), message: chrome ?? "Chrome/Chromium not found" });
+        }
+        return checks;
+      } } : {}),
+      ...(metadata.hasStudio ? { studio: () => runExternalPlugin(pluginPath, "studio", PluginStudioSchema, undefined, { options }) } : {}),
+      render: async ({ onProgress, ...input }) => {
+        if (metadata.hasBrowser) {
+          const browser = await runExternalPlugin(pluginPath, "browser", PluginBrowserSchema, undefined, { options });
+          notifyProgress(onProgress, { stage: "render.html", message: "正在导出微信 HTML" });
+          const result = await exportMarkdownToWechatHtml({ ...input, browserScriptPath: browser.scriptPath });
+          notifyProgress(onProgress, { stage: "render.html", message: "微信 HTML 导出完成", current: 1, total: 1, unit: "files" });
+          return result;
+        }
+        return runExternalPlugin(pluginPath, "render", PluginMarkdownOutputSchema, input, { options }, onProgress,
+          input.timeoutMs && Number.isFinite(input.timeoutMs) && input.timeoutMs > 0 ? input.timeoutMs + 10_000 : 120_000);
+      },
     };
   }
 

package/src/adapter-types.ts

@@ -207,7 +207,21 @@ export interface MarkdownRenderPlugin {
   /** Environment checks */
   doctor?: (options?: Record<string, unknown>) => Promise<PipelinePluginDoctorCheck[]>;
 
+  /** 工作台静态资源由插件分发，配置读写仍由宿主提供。 */
+  studio?: (options?: Record<string, unknown>) => Promise<MarkdownStudioAssets>;
+
   /** Render markdown to WeChat-compatible HTML */
   /** 专属配置作为第二个参数传入，旧插件可忽略。 */
   render: (input: MarkdownRenderInput, options?: Record<string, unknown>) => Promise<MarkdownRenderOutput>;
 }
+
+/** root 是插件资源目录，entry 是该目录内的 HTML 相对路径。 */
+export interface MarkdownStudioAssets {
+  root: string;
+  entry: string;
+}
+
+/** 仅提供浏览器排版资源的插件，Chrome 生命周期由 pipeline 管理。 */
+export interface BrowserMarkdownRenderPlugin extends Omit<MarkdownRenderPlugin, "render"> {
+  browser: (options?: Record<string, unknown>) => Promise<{ scriptPath: string }>;
+}

package/src/commands/typeset-assets-sync.test.ts

@@ -66,6 +66,7 @@ test("deduplicates shared images, rewrites only sources, and exports styles with
   const configPath = join(root, "config.json");
   const config = await result(configPath);
   config.wx.accounts.default.articleTheme = "style.json";
+  config.plugins.markdownRenderer = { module: "@akairos/myno/adapter", options: {} };
   await writeFile(configPath, JSON.stringify(config));
   let uploads = 0;
   const command = createTypesetAssetsSyncCommand({ upload: uploader(async () => { uploads++; }), verifyUrl });
@@ -74,10 +75,12 @@ test("deduplicates shared images, rewrites only sources, and exports styles with
   expect(uploads).toBe(1);
   expect((await result(join(root, "templates/jinx.json"))).images[0]).toEqual({ ...template.images[0], src: "https://cdn.example/jinx.png" });
   const patch = await result(join(destination, "pipeline.patch.json"));
+  expect(patch.plugins.markdownRenderer).toEqual({ module: "@akairos/myno/adapter", options: {} });
   expect(patch.wx.accounts.default).toMatchObject({ customCss: null, articleTheme: "/data/pipeline-runtime/markdown/article-themes/default/manifest.json" });
   expect((await readArticleTheme(join(destination, "markdown/article-themes/default/manifest.json"))).css).toBe(style.css);
   for (const secret of ["secret-cos-token", "private-secret", "private-app-id", "private-pat"]) expect(JSON.stringify(patch)).not.toContain(secret);
   expect((await result(join(destination, "manifest.json"))).typesetTemplates).toBe(2);
+  expect(await readFile(join(destination, "typeset-studio/templates/.canvas-presets-v1"), "utf8")).toBe("1");
   expect((await readFile(join(root, "uploads/jinx.png"))).equals(image)).toBe(true);
   await command(["--output", destination]);
   expect(uploads).toBe(1);

package/src/plugin-runner.ts

@@ -1,13 +1,15 @@
 import type { MonitorProgress } from "./monitor/types";
 
 /** 子进程只执行一次插件调用，进度与结果通过 IPC 返回。 */
-process.on("message", async (request: { specifier: string; action: "describe" | "doctor" | "render"; input?: Record<string, unknown>; options?: Record<string, unknown> }) => {
+process.on("message", async (request: { specifier: string; action: "describe" | "doctor" | "render" | "studio" | "browser"; input?: Record<string, unknown>; options?: Record<string, unknown> }) => {
   try {
     const module = await import(request.specifier);
     const plugin = module.default ?? module.plugin ?? module;
     if (!plugin || typeof plugin !== "object" || typeof plugin.name !== "string" || !plugin.name.trim() ||
-        typeof plugin.render !== "function" || (plugin.doctor !== undefined && typeof plugin.doctor !== "function")) {
-      throw new Error("插件必须导出 name、render，以及可选的 doctor 函数");
+        (typeof plugin.render !== "function" && typeof plugin.browser !== "function") ||
+        (plugin.browser !== undefined && typeof plugin.browser !== "function") || (plugin.doctor !== undefined && typeof plugin.doctor !== "function") ||
+        (plugin.studio !== undefined && typeof plugin.studio !== "function")) {
+      throw new Error("插件必须导出 name、render 或 browser，以及可选的 doctor 函数和 studio 函数");
     }
     // 故障插件频繁报告进度时，限制 IPC 消息数量。
     let lastProgressAt = 0;
@@ -18,9 +20,13 @@ process.on("message", async (request: { specifier: string; action: "describe" |
       process.send?.({ type: "progress", value: progress });
     };
     const value = request.action === "describe"
-      ? { name: plugin.name, version: plugin.version, hasDoctor: typeof plugin.doctor === "function" }
+      ? { name: plugin.name, version: plugin.version, hasDoctor: typeof plugin.doctor === "function", hasStudio: typeof plugin.studio === "function", hasBrowser: typeof plugin.browser === "function" }
       : request.action === "doctor"
         ? await plugin.doctor(request.options)
+        : request.action === "studio"
+          ? await plugin.studio(request.options)
+        : request.action === "browser"
+          ? await plugin.browser(request.options)
         : await plugin.render({ ...request.input, onProgress }, request.options);
     process.send?.({ type: "result", value });
   } catch (error) {

package/src/plugin-runtime.test.ts

@@ -115,6 +115,25 @@ test("markdown plugins receive their own options in doctor and render", async ()
   expect((await plugin.render({ markdownPath: join(directory, "post.md"), outPath: join(directory, "post.html"), account: "default" })).html).toBe(options.html);
 });
 
+test("browser-only markdown plugins validate their entry and receive their own options", async () => {
+  const pluginPath = join(directory, "browser-plugin.mjs");
+  await writeFile(pluginPath, `export default {name:'browser-test',browser(options){return {scriptPath:options.scriptPath}}}`);
+  const plugin = await resolveMarkdownRenderer(PipelineConfigSchema.parse({ plugins: { markdownRenderer: { module: pluginPath, options: { scriptPath: "relative.js" } } } }));
+  await expect(plugin.render({ markdownPath: "unused.md", outPath: "out.html", account: "default" })).rejects.toMatchObject({ code: "PLUGIN_INVALID_RESULT" });
+  expect((await plugin.doctor!()).some(check => check.name === "chrome")).toBe(true);
+});
+
+test("Studio capability is optional, isolated and validates asset directory paths", async () => {
+  const pluginPath = await fixture("return null", `async studio(options){return {root:${JSON.stringify(directory)},entry:options.entry}},`);
+  const config = (entry: string) => PipelineConfigSchema.parse({ plugins: { markdownRenderer: { module: pluginPath, options: { entry } } } });
+  const plugin = await resolveMarkdownRenderer(config("studio.html"));
+  expect(await plugin.studio!()).toEqual({ root: directory, entry: "studio.html" });
+  const invalid = await resolveMarkdownRenderer(config("../outside.html"));
+  await expect(invalid.studio!()).rejects.toMatchObject({ code: "PLUGIN_INVALID_RESULT" });
+  const plain = await resolveMarkdownRenderer(PipelineConfigSchema.parse({ plugins: { markdownRenderer: await fixture("return null") } }));
+  expect(plain.studio).toBeUndefined();
+});
+
 test("reports thrown errors, process exits, and invalid image results without escaping the parent", async () => {
   for (const [body, code] of [
     ['throw new Error("bad template")', "PLUGIN_EXECUTION_FAILED"],

package/src/plugin-runtime.ts

@@ -10,7 +10,7 @@ import { resolveBunBinary } from "./spawn";
 /** 插件错误保留阶段和错误码，终端与调用方使用同一提示。 */
 export class PluginExecutionError extends Error {
   constructor(readonly code: string, specifier: string, action: string, detail: string) {
-    const stage = action === "describe" ? "加载" : action === "doctor" ? "检查" : "渲染";
+    const stage = action === "describe" || action === "browser" ? "加载" : action === "doctor" ? "检查" : action === "studio" ? "工作台加载" : "渲染";
     super(`[${code}] 插件「${specifier}」${stage}失败：${detail}。请检查插件配置、运行 zzp doctor 或切换内置渲染器，修复后再重试；本次未自动重试。`);
     this.name = "PluginExecutionError";
   }
@@ -20,6 +20,15 @@ export const PluginMetadataSchema = z.object({
   name: z.string().trim().min(1),
   version: z.string().optional(),
   hasDoctor: z.boolean(),
+  hasStudio: z.boolean().default(false),
+  hasBrowser: z.boolean().default(false),
+});
+export const PluginBrowserSchema = z.object({
+  scriptPath: z.string().refine(isAbsolute, "浏览器入口必须是绝对路径"),
+});
+export const PluginStudioSchema = z.object({
+  root: z.string().refine(isAbsolute, "Studio root 必须是绝对路径"),
+  entry: z.string().min(1).refine(value => !isAbsolute(value) && !value.split(/[\\/]/).includes(".."), "Studio entry 必须位于资源目录内"),
 });
 export const PluginDoctorSchema = z.array(z.object({
   name: z.string().min(1), ok: z.boolean(), message: z.string().optional(), detail: z.unknown().optional(),
@@ -48,7 +57,7 @@ const ProgressSchema = z.object({
 /** 外部插件独立执行；父进程可终止同步死循环、异常退出和永不结束的 Promise。 */
 export async function runExternalPlugin<T>(
   specifier: string,
-  action: "describe" | "doctor" | "render",
+  action: "describe" | "doctor" | "render" | "studio" | "browser",
   schema: z.ZodType<T>,
   input?: Record<string, unknown>,
   configuration: { options?: Record<string, unknown>; environment?: Record<string, string> } = {},

package/src/runtime-package.ts

@@ -61,7 +61,7 @@ export function validateStudioDefaults(text: string, templateIds: Set<string>):
 }
 
 /** 准备账号主题文件，只导出样式白名单，不复制凭据或本机插件入口。 */
-export async function prepareMarkdownRuntime(config: PipelineConfig, accountMap: Record<string, string> = {}): Promise<{ files: Map<string, Uint8Array>; accounts: Record<string, unknown> }> {
+export async function prepareMarkdownRuntime(config: PipelineConfig, accountMap: Record<string, string> = {}): Promise<{ files: Map<string, Uint8Array>; accounts: Record<string, unknown>; markdownRenderer: PipelineConfig["plugins"]["markdownRenderer"] }> {
   const files = new Map<string, Uint8Array>();
   const accounts: Record<string, unknown> = {};
   for (const [localAccount, value] of Object.entries(config.wx.accounts)) {
@@ -84,7 +84,12 @@ export async function prepareMarkdownRuntime(config: PipelineConfig, accountMap:
     }
     accounts[account] = next;
   }
-  return { files, accounts };
+  const entry = config.plugins.markdownRenderer;
+  const module = typeof entry === "string" ? entry : entry?.module;
+  // 部署只接受可复现的 npm 入口，禁止把本机绝对路径带到服务器。
+  if (module && module !== "@akairos/myno/adapter") throw new Error("运行时同步仅支持 @akairos/myno/adapter 或内置 Markdown 渲染器");
+  if (typeof entry === "object" && entry && Object.keys(entry.options).length) throw new Error("myno 运行时同步暂不接受专属参数");
+  return { files, accounts, markdownRenderer: module ? { module, options: {} } : null };
 }
 
 /** 写入带文件哈希的独立配置包，调用者在全部成功后切换目录。 */
@@ -101,8 +106,9 @@ export async function writeRuntimePackage(destination: string, templates: Map<st
   files.set("typeset-studio/default-template.json", Buffer.from(defaults));
   // 防止渲染时重新播种内置模板，使部署目录与文件清单保持一致。
   files.set("typeset-studio/templates/.initialized", Buffer.from("1"));
+  files.set("typeset-studio/templates/.canvas-presets-v1", Buffer.from("1"));
   const patch = {
-    plugins: { imageRenderer: { module: "@akairos/typeset-studio/adapter", options: { dataDir: `${RUNTIME_ROOT}/typeset-studio` } }, markdownRenderer: null },
+    plugins: { imageRenderer: { module: "@akairos/typeset-studio/adapter", options: { dataDir: `${RUNTIME_ROOT}/typeset-studio` } }, markdownRenderer: markdown.markdownRenderer },
     wx: { accounts: markdown.accounts },
   };
   files.set("pipeline.patch.json", Buffer.from(JSON.stringify(patch, null, 2) + "\n"));

package/src/wechat-preview/index.ts

@@ -100,6 +100,8 @@ export interface ExportMarkdownToWechatHtmlInput {
   timeoutMs?: number;
   /** Write intermediate artifacts for debugging. */
   debugDir?: string;
+  /** 外部插件提供的已构建入口；浏览器和文件输出继续由宿主管理。 */
+  browserScriptPath?: string;
 }
 
 export interface ExportMarkdownToWechatHtmlResult {
@@ -405,7 +407,9 @@ export async function exportMarkdownToWechatHtml(
 
     let bundle: BundleAssets;
     try {
-      bundle = ensureBundle();
+      bundle = input.browserScriptPath
+        ? { scriptPath: input.browserScriptPath, rebuilt: false, stale: false }
+        : ensureBundle();
       bundleRebuilt = bundle.rebuilt;
       bundleStale = bundle.stale;
     } catch (error) {
@@ -432,6 +436,7 @@ export async function exportMarkdownToWechatHtml(
         assetBaseUrl: pathToFileURL(`${dirname(resolve(input.markdownPath))}/`).href,
         editorVars: theme.editorVars,
         exportTheme: theme.exportTheme,
+        syntaxPresets,
         customCss,
         structure,
       }),

package/src/wechat-preview/server/http.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, join } from "path";
+import { realpath, stat } from "fs/promises";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "path";
 import { z } from "zod";
 import {
   previewBaseUrl,
@@ -32,6 +33,8 @@ import { readArticleTheme } from "../../article-theme";
 import { PipelineConfigSchema, WechatExportThemeOverridesSchema, WechatStructureOverridesSchema } from "../../schema/config";
 import { loadConfig, saveConfig, getPipelineConfigPath, resolveConfigRelativePath } from "../../config";
 import { DIST_DIR, WECHAT_PREVIEW_DIR } from "../../runtime-paths";
+import { resolveMarkdownRenderer } from "../../adapter-loader";
+import type { MarkdownStudioAssets } from "../../adapter-types";
 import type { PreviewRegisterInput } from "./types";
 
 /** 保存入口先校验完整请求，避免写入 CLI 无法加载的配置。 */
@@ -105,6 +108,32 @@ export async function startPreviewServer(
     clearServerLock();
   }
 
+  // 工作台与导出使用同一个插件；没有工作台能力时给出明确提示。
+  const pluginConfig = loadConfig();
+  const externalMarkdown = Boolean(pluginConfig.plugins.markdownRenderer);
+  let studioAssets: Promise<MarkdownStudioAssets | undefined> | undefined;
+  /** 按需加载工作台，故障插件不影响预览登记和历史页面。 */
+  function getStudio() {
+    return studioAssets ??= resolveMarkdownRenderer(pluginConfig).then(async renderer => {
+      const studio = await renderer.studio?.();
+      return studio ? { ...studio, root: await realpath(studio.root) } : undefined;
+    });
+  }
+
+  /** 插件静态资源独立挂载，真实路径也必须留在插件资源目录内。 */
+  async function studioFile(name: string): Promise<string | null> {
+    try {
+      if (!externalMarkdown) return null;
+      const studioRoot = (await getStudio())?.root;
+      if (!studioRoot) return null;
+      const target = await realpath(resolve(studioRoot, name));
+      const rel = relative(studioRoot, target);
+      return rel && !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`) && (await stat(target)).isFile() ? target : null;
+    } catch {
+      return null;
+    }
+  }
+
   let server: ReturnType<typeof Bun.serve>;
   server = Bun.serve({
     hostname: host,
@@ -317,6 +346,21 @@ export async function startPreviewServer(
       }
 
       if (pathname === "/studio" || pathname === "/studio/" || pathname === "/studio/index.html") {
+        if (externalMarkdown) {
+          let studio: MarkdownStudioAssets | undefined;
+          try { studio = await getStudio(); }
+          catch (error) { return json({ error: error instanceof Error ? error.message : String(error) }, 500); }
+          if (!studio) return html("<h1>当前 Markdown 渲染插件未提供 Studio 工作台。</h1>", 404);
+          const entry = await studioFile(studio.entry);
+          if (!entry) return html("<h1>插件 Studio 入口不存在或超出资源目录。</h1>", 500);
+          // 相对资源按插件入口解析，统一放入命名空间且保留页面导航链接。
+          return html(readFileSync(entry, "utf8").replace(/<(?:script|link)\b[^>]*>/g,
+            tag => tag.replace(/\b(src|href)=(["'])([^"']+)\2/g, (attribute, name, quote, value: string) => {
+              if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(value)) return attribute;
+              const asset = new URL(value, `http://studio/${studio.entry}`);
+              return `${name}=${quote}/studio-assets${asset.pathname}${asset.search}${quote}`;
+            })));
+        }
         const studioHtmlPath = join(DIST_DIR, "src/wechat-preview/browser/studio/studio.html");
         const fallbackPath = join(DIST_DIR, "studio.html");
         const targetHtmlPath = existsSync(studioHtmlPath) ? studioHtmlPath : fallbackPath;
@@ -326,6 +370,17 @@ export async function startPreviewServer(
         return html("<h1>Studio not built. Run bun run build:wechat-preview first.</h1>", 500);
       }
 
+      if (pathname.startsWith("/studio-assets/")) {
+        let name: string;
+        try { name = decodeURIComponent(pathname.slice("/studio-assets/".length)); }
+        catch { return json({ error: "invalid asset path" }, 400); }
+        const target = await studioFile(name);
+        if (!target) return json({ error: "Studio asset not found" }, 404);
+        return new Response(new Uint8Array(readFileSync(target)), {
+          headers: { "content-type": guessContentType(target), "cache-control": "no-cache" },
+        });
+      }
+
       if (pathname === "/studio.js" || pathname === "/editor-export.js") {
         const filePath = join(DIST_DIR, pathname.slice(1));
         if (existsSync(filePath)) {

package/src/wechat-preview/server/studio.test.ts

@@ -2,7 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 
 import { tmpdir } from "os";
 import { join } from "path";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "fs";
 import { startPreviewServer, type StartPreviewServerResult } from "./http";
 import { loadConfig, saveConfig } from "../../config";
 
@@ -192,4 +192,38 @@ describe("wechat-preview studio server APIs", () => {
     expect(html).toContain("studio.js");
     expect(html).toContain('id="btn-export-config"');
   });
+
+  test("external Studio serves plugin resources without exposing files outside its root", async () => {
+    const root = join(testDir, "plugin-assets");
+    mkdirSync(root);
+    writeFileSync(join(root, "studio.html"), '<script src="/studio.js"></script><link href="/style.css"><a href="/">History</a>');
+    writeFileSync(join(root, "studio.js"), "/* plugin studio */");
+    writeFileSync(join(testDir, "private.txt"), "private");
+    symlinkSync(join(testDir, "private.txt"), join(root, "outside.txt"));
+    const pluginPath = join(testDir, "studio-plugin.mjs");
+    writeFileSync(pluginPath, `export default {name:'studio-test',render(){},studio(){return {root:${JSON.stringify(root)},entry:'studio.html'}}}`);
+    const config = loadConfig();
+    const original = config.plugins.markdownRenderer;
+    config.plugins.markdownRenderer = pluginPath;
+    saveConfig(config);
+    let external: StartPreviewServerResult | undefined;
+    const originalServerDir = process.env.ZZHUB_WECHAT_PREVIEW_DIR;
+    process.env.ZZHUB_WECHAT_PREVIEW_DIR = join(testDir, "external-server");
+    try {
+      external = await startPreviewServer({ host: "127.0.0.1", port: 0, reuseExisting: false });
+      const page = await (await fetch(`${external.url}/studio`)).text();
+      expect(page).toContain('src="/studio-assets/studio.js"');
+      expect(page).toContain('href="/studio-assets/style.css"');
+      expect(page).toContain('<a href="/">History</a>');
+      expect(await (await fetch(`${external.url}/studio-assets/studio.js`)).text()).toBe("/* plugin studio */");
+      expect((await fetch(`${external.url}/studio-assets/outside.txt`)).status).toBe(404);
+      expect((await fetch(`${external.url}/studio-assets/..%2fprivate.txt`)).status).toBe(404);
+      expect((await fetch(`${external.url}/api/studio/config`)).status).toBe(200);
+    } finally {
+      external?.stop?.();
+      process.env.ZZHUB_WECHAT_PREVIEW_DIR = originalServerDir;
+      config.plugins.markdownRenderer = original;
+      saveConfig(config);
+    }
+  });
 });