@akairos/pipeline 0.18.1 → 0.18.5

package/ARTICLE-THEMES.md

@@ -24,6 +24,8 @@ zzp publish --state ./workflow-state.json --article-theme ./my-template
 
 账号默认使用 `wx.accounts.<account>.articleTheme`，相对路径以配置文件所在目录为基准。显式 `--article-theme` 优先，路径相对当前目录；handoff 支持同义的可选 `article_theme` 字段。没有选择正文模板时保持既有配置。封面仍使用 `--cover-theme`。
 
+WeChat Visual Studio 的「导出配置」下载独立 `wechat-style.json`，同样通过 `--article-theme` 选择。文件含内嵌 `css`、`editorVars`、`exportTheme`、`syntaxPresets` 和 `structure`；页首图片以内嵌 Data URL 保存。不含账号凭据，不需要附带目录包文件。独立 JSON 使用自身样式，不叠加账号 `theme/customCss`，显式 `wechat-export --custom-css` 仍可覆盖。可用 `article-theme --path` 校验或安装；默认配置引用后由现有 `typeset-assets-sync` 收集部署，详见 [Studio 配置指南](docs/visual-studio-and-config-sync.md)。
+
 模板样式叠加在现有基础样式上，既有账号 `theme` 覆盖和 `customCss` 最后生效。新版正文模板默认不附带内置账号署名，用户自己配置的 footerText 仍保留。旧 Markdown 插件接收可选 `articleThemePath`，可以继续忽略该字段；要支持付费模板预览，应使用内置渲染器或实现该可选参数。桌面端预览同样调用当前已配置的渲染插件。
 
 发布前冻结模板版本、CSS 和资源到工作区 `.zzhub-media/article-themes`；渲染结果记录 `article_theme_hash`。同一篇文章更改模板、版本或声明素材后会重新导出。旧状态不含该字段时仍可使用。

package/README.md

@@ -56,7 +56,7 @@ Pipeline 需要 [Bun](https://bun.sh/) 运行。npm 可以安装包，但命令
 npm install -g @akairos/pipeline
 
 # 或从源码运行
-git clone https://github.com/aatrooox/zzhub-pipeline.git
+git clone https://github.com/k7airos/zzhub-pipeline.git
 cd zzhub-pipeline
 bun install
 bun run src/cli.ts --help
@@ -212,6 +212,8 @@ zzp typeset-assets-sync --output ./pipeline-runtime --account-map '{"default":"W
 
 配置包只包含插件入口、Studio 容器路径和账号主题/CSS/文章模板路径，不包含微信凭据、COS PAT 或 Worker token。账号的 `customCss`、`articleTheme` 为 null 时会清除服务器旧引用。服务器用 `nezus-infra` 的 `sync pipeline-runtime` 命令校验文件清单、合并排版白名单并备份切换；镜像与 npm 依赖继续固定版本部署。
 
+WeChat Visual Studio 可通过「导出配置」下载不绑定账号的独立排版 JSON。CLI 用 `--article-theme ./wechat-style.json` 选择；在默认配置的账号 `articleTheme` 中引用后，也会由上述运行时包收集部署。文件内嵌 CSS 与页首图片，无需附带模板目录。详见 [Studio 独立配置与部署](docs/visual-studio-and-config-sync.md)。
+
 ### 推进一个发布任务
 
 Pipeline 每次只推进一个动作。创建任务后，反复执行 `status`，按照返回的 `next_action` 继续；不要直接修改 `workflow-state.json`。
@@ -245,7 +247,7 @@ zzp publish --state <state_path>
 
 实际顺序以 `status --view agent` 为准。需要发布贴图时，把 `--content-form` 改为 `newspic`；多页图片可以在渲染前附加 `newspic` 规格。
 
-如果正文由 Agent 生成或审核，可以直接使用仓库里的 [`zzhub-publish` Skill](skills/zzhub-publish/SKILL.md)。Skill 只负责编排 Agent，文章正文仍由调用方提供。
+如果正文由 Agent 生成或审核，可以使用配套的 [kairos-skills](https://github.com/k7airos/kairos-skills) 仓库中的 [`zzhub-publish` Skill](https://github.com/k7airos/kairos-skills/tree/main/skills/zzhub-publish/SKILL.md)。Skill 负责编排 Agent 状态机，文章正文仍由调用方提供。
 
 ## 云端 Worker
 
@@ -375,7 +377,7 @@ zzp monitor stop
 - [云端 Worker API、部署与更新](services/cloud-worker/README.md)
 - [封面主题和图片排版](docs/render-themes.md)
 - [离线正文模板](ARTICLE-THEMES.md)
-- [Agent 发布 Skill](skills/zzhub-publish/SKILL.md)
+- [Kairos Agent Skills 仓库](https://github.com/k7airos/kairos-skills)：配套的 Agent 技能集合（包含 `zzhub-publish` 状态机编排、`milkdown-writing` 写作排版规范、`auto-ai-daily` 自动化发文）
 - [第三方声明](THIRD-PARTY-NOTICES.md)
 
 ## 开发与验证

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/pipeline",
-  "version": "0.18.1",
+  "version": "0.18.5",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -27,8 +27,8 @@
     "release:major": "changelogen --release --major --push"
   },
   "dependencies": {
-    "@akairos/milkdown-article-plugins": "^0.1.3",
-    "@akairos/milkdown-article-style": "^0.1.1",
+    "@akairos/milkdown-article-plugins": "^0.1.6",
+    "@akairos/milkdown-article-style": "^0.1.2",
     "@akairos/typeset-studio": "0.2.5",
     "@chenglou/pretext": "0.0.8",
     "image-size": "^2.0.2",
@@ -40,7 +40,8 @@
     "cos-nodejs-sdk-v5": "^2.15.4"
   },
   "devDependencies": {
-    "@milkdown/kit": "^7.18.0",
+    "@milkdown/crepe": "^7.21.2",
+    "@milkdown/kit": "^7.21.2",
     "@types/bun": "latest",
     "@types/pngjs": "^6.0.5",
     "changelogen": "^0.6.2",

package/src/article-theme.test.ts

@@ -4,6 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { readArticleTheme, snapshotArticleTheme } from "./article-theme";
 import { filterIdempotent } from "./providers/publish-core";
+import { resolveWechatArticleTheme } from "./wechat-preview";
+import { prepareMarkdownRuntime, RUNTIME_ROOT } from "./runtime-package";
+import { PipelineConfigSchema } from "./schema/config";
 
 const roots: string[] = [];
 afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); });
@@ -53,6 +56,58 @@ test("越界、符号链接、网络样式与不兼容版本不能导入", async
   }
 });
 
+test("Studio 单文件配置可跨账号复用、冻结及沿用运行时配置包部署", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zzp-studio-config-"));
+  roots.push(root);
+  const path = join(root, "my-style.json");
+  const profile = {
+    schemaVersion: 1, engineVersion: 1, id: "wechat-style", name: "独立排版", version: "1.0.0",
+    editorVars: { "--brand": "#123456" },
+    exportTheme: { bodyFontSize: "18px", footerText: "", primaryColor: "#123456" },
+    syntaxPresets: { h2: "contrast-green" },
+    structure: { numberedHeadings: true, headingLabel: "章节", calloutPresets: { tip: { title: "建议" } }, headerImageUrl: "data:image/png;base64,aW1hZ2U=" },
+    css: "p { color: #123456; }",
+  };
+  await writeFile(path, JSON.stringify(profile));
+  const theme = await readArticleTheme(path);
+  expect(theme.files.size).toBe(1);
+  expect(theme.css).toBe(profile.css);
+  const accountOverrides = { editorVars: { "--brand": "#ff0000" }, exportTheme: { bodyFontSize: "14px" }, syntaxPresets: { h2: "pillar" } };
+  const first = resolveWechatArticleTheme("default", accountOverrides, theme);
+  const other = resolveWechatArticleTheme("ancientone", accountOverrides, theme);
+  expect(first).toEqual(other);
+  expect(first.theme.exportTheme.bodyFontSize).toBe("18px");
+  expect(first.syntaxPresets).toEqual(profile.syntaxPresets);
+  expect(first.structure?.headerImageUrl).toBe(profile.structure.headerImageUrl);
+  expect(first.structure?.calloutPresets).toEqual(profile.structure.calloutPresets);
+  const frozen = await snapshotArticleTheme(theme, join(root, "frozen"));
+  expect((await readArticleTheme(frozen.path)).hash).toBe(theme.hash);
+
+  const config = PipelineConfigSchema.parse({ wx: { accounts: { default: { articleTheme: path, customCss: join(root, "missing.css"), pat: "secret" } } } });
+  const deployed = await prepareMarkdownRuntime(config);
+  const manifest = "markdown/article-themes/default/manifest.json";
+  expect(deployed.accounts.default).toMatchObject({ articleTheme: `${RUNTIME_ROOT}/${manifest}`, customCss: null });
+  expect(JSON.stringify(deployed.accounts)).not.toContain("secret");
+  expect(JSON.parse(new TextDecoder().decode(deployed.files.get(manifest))).css).toBe(profile.css);
+  await writeFile(path, JSON.stringify({ ...profile, css: "p { color: blue; }" }));
+  expect((await readArticleTheme(path)).hash).not.toBe(theme.hash);
+});
+
+test("独立配置拒绝凭据、外部素材与不安全 CSS", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zzp-studio-invalid-"));
+  roots.push(root);
+  const path = join(root, "style.json");
+  const profile = { schemaVersion: 1, engineVersion: 1, id: "style", name: "Style", version: "1.0.0", css: "" };
+  for (const patch of [
+    { account: "default" }, { pat: "secret" }, { assets: ["asset.png"] },
+    { css: "p { background: url(file:///secret); }" },
+    { structure: { headerImageUrl: "file:///secret" } },
+  ]) {
+    await writeFile(path, JSON.stringify({ ...profile, ...patch }));
+    await expect(readArticleTheme(path)).rejects.toThrow();
+  }
+});
+
 test("结果未知阻止普通重发，明确重置才建立新发布尝试", async () => {
   const { root } = await fixture();
   const { defaultState, readState, writeState } = await import("./state");

package/src/article-theme.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
+import { WechatStructureOverridesSchema } from "./schema/config";
 
 /** 模板只包含声明、CSS 与素材，不执行客户包中的脚本。 */
 export const ArticleThemeSchema = z.object({
@@ -18,11 +19,16 @@ export const ArticleThemeSchema = z.object({
   assets: z.array(z.string()).max(100).default([]),
   editorVars: z.record(z.string(), z.string()).default({}),
   exportTheme: z.record(z.string(), z.string()).default({}),
+  /** Studio 独立配置内嵌 CSS，无需附带模板目录。 */
+  css: z.string().max(256_000).optional(),
+  syntaxPresets: z.record(z.string(), z.string()).optional(),
   structure: z.object({
     numberedHeadings: z.boolean().default(false),
     headingLabel: z.string().max(30).default(""),
     quoteLabel: z.string().max(30).default(""),
     headerImage: z.string().nullable().default(null),
+    headerImageUrl: z.string().regex(/^data:image\/(?:png|jpeg|gif|webp);base64,[A-Za-z0-9+/]+={0,2}$/).nullable().optional(),
+    calloutPresets: WechatStructureOverridesSchema.shape.calloutPresets,
   }).default({ numberedHeadings: false, headingLabel: "", quoteLabel: "", headerImage: null }),
 }).strict();
 
@@ -64,10 +70,12 @@ export async function readArticleTheme(inputPath: string): Promise<ArticleThemeP
   }
   const manifestName = basename(manifestPath);
   const manifest = ArticleThemeSchema.parse(JSON.parse(new TextDecoder().decode(await read(manifestName))));
-  const paths = [manifest.stylesheet, manifest.sample, manifest.preview, manifest.license, ...manifest.assets];
+  const standalone = manifest.css !== undefined;
+  if (standalone && (manifest.assets.length || manifest.structure.headerImage)) throw new Error("独立排版配置必须内嵌素材，不能引用模板目录文件");
+  const paths = standalone ? [] : [manifest.stylesheet, manifest.sample, manifest.preview, manifest.license, ...manifest.assets];
   if (manifest.structure.headerImage) paths.push(manifest.structure.headerImage);
   for (const name of new Set(paths)) await read(name);
-  const css = new TextDecoder().decode(files.get(manifest.stylesheet));
+  const css = manifest.css ?? new TextDecoder().decode(files.get(manifest.stylesheet));
   // 模板无需 CSS 转义；拒绝用转义或注释隐藏的网络/文件资源。
   const unsafeCss = (value: string) => /\\|@import\b|url\s*\(|expression\s*\(/i.test(value.replace(/\/\*[\s\S]*?\*\//g, ""));
   if (Object.keys(manifest.editorVars).some(key => !/^--[a-zA-Z0-9_-]+$/.test(key))) throw new Error("模板变量名无效");

package/src/commands/article-theme.ts

@@ -6,7 +6,7 @@ import { printResult } from "../output";
 export async function articleTheme(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
   if (parsed.help) {
-    console.log("Usage: zzp article-theme --path <模板目录或 manifest.json> [--install <本地模板库>]\n只校验或复制模板，不联网、不发布。");
+    console.log("Usage: zzp article-theme --path <Studio 独立 JSON、模板目录或 manifest.json> [--install <本地模板库>]\n只校验或复制模板，不联网、不发布。");
     return;
   }
   let theme = await readArticleTheme(requireArg(parsed, "path", "template path"));

package/src/commands/init.ts

@@ -64,6 +64,7 @@ Options:
   --newspic-render-spec-file  JSON file for newspic pagination / page-image intent (optional)
   --style-hint       e.g. fact_report (optional)
   --cover-theme      Cover theme ID (optional)
+  --article-theme    Standalone Studio JSON or local article theme package (optional)
   --requires-research  Flag
   --requires-style     Flag
   --requires-render    Flag
@@ -140,6 +141,7 @@ Options:
     explicit_constraints: [],
     style_hint: styleHint,
     cover_theme: coverTheme,
+    article_theme: optionalArg(parsed, "article-theme") ? resolve(optionalArg(parsed, "article-theme")!) : null,
     newspic_render: newspicRender,
     ...(newspicFile ? { newspic_file: resolve(newspicFile) } : {}),
     requires: {

package/src/commands/publish.ts

@@ -47,7 +47,7 @@ Usage: zzhub-pipeline publish [options]
 Options:
   --state      Path to state JSON (required)
   --route      Only publish this route (optional; default: all targets)
-  --article-theme    Local article theme package (optional)
+  --article-theme    Standalone Studio JSON or local article theme package (optional)
   --dry-run    Print commands without executing (optional)
 `.trim());
     return;

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

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { PNG } from "pngjs";
 import { createTypesetAssetsSyncCommand } from "./typeset-assets-sync";
 import type { uploadFileToCos } from "../providers/cos";
+import { readArticleTheme } from "../article-theme";
 
 let root: string;
 let previousConfig: string | undefined;
@@ -60,6 +61,12 @@ test("dry-run reads only referenced images and never uploads, verifies URLs, or
 
 test("deduplicates shared images, rewrites only sources, and exports styles without credentials", async () => {
   await writeFile(join(root, "templates/shared.json"), JSON.stringify({ ...template, id: "shared" }));
+  const style = { schemaVersion: 1, engineVersion: 1, id: "style", name: "Style", version: "1.0.0", css: "p { color: #123456; }", exportTheme: { bodyFontSize: "18px" } };
+  await writeFile(join(root, "style.json"), JSON.stringify(style));
+  const configPath = join(root, "config.json");
+  const config = await result(configPath);
+  config.wx.accounts.default.articleTheme = "style.json";
+  await writeFile(configPath, JSON.stringify(config));
   let uploads = 0;
   const command = createTypesetAssetsSyncCommand({ upload: uploader(async () => { uploads++; }), verifyUrl });
   const destination = join(root, "runtime");
@@ -67,7 +74,8 @@ 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.wx.accounts.default).toMatchObject({ customCss: "/data/pipeline-runtime/markdown/custom-css-default.css", articleTheme: null });
+  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(root, "uploads/jinx.png"))).equals(image)).toBe(true);

package/src/commands/wechat-export.ts

@@ -8,6 +8,7 @@ import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
 import { WechatExportError } from "../wechat-preview";
 import { registerPreviewEntry } from "../wechat-preview/server";
+import { readArticleTheme } from "../article-theme";
 
 const CSS_DEMO = `
 Custom CSS is cascaded after the built-in theme and converted to conservative
@@ -69,7 +70,7 @@ Options:
   --account            Account/theme key (optional; default: default)
   --title              Page title for the render shell (optional)
   --preview-shell-out  Path to exact final-HTML preview (optional)
-  --article-theme      Local article theme package (optional)
+  --article-theme      Standalone Studio JSON or local article theme package (optional)
   --summary-only       Omit HTML from stdout; still write the complete output file
   --custom-css         CSS override path; replaces account customCss (optional)
   --timeout-ms         Real browser wait limit in ms (default: 15000)
@@ -108,9 +109,13 @@ ${CSS_DEMO}
 
   const config = loadConfig();
   const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
+  const articleThemeArg = optionalArg(parsed, "article-theme");
+  const articleThemePath = articleThemeArg ? resolve(articleThemeArg) : resolveConfigRelativePath(wxAccount?.articleTheme);
+  // 独立配置替代账号样式；显式 CSS 参数仍可覆盖本次导出。
+  const standalone = articleThemePath ? (await readArticleTheme(articleThemePath)).manifest.css !== undefined : false;
   const customCss = resolveWechatExportCustomCss(
     cliCustomCss,
-    wxAccount?.customCss,
+    standalone ? null : wxAccount?.customCss,
   );
   const markdownRenderer = await resolveMarkdownRenderer(config);
 
@@ -125,8 +130,8 @@ ${CSS_DEMO}
       title,
       previewShellOutPath,
       customCss,
-      articleThemePath: optionalArg(parsed, "article-theme") ? resolve(optionalArg(parsed, "article-theme")!) : resolveConfigRelativePath(wxAccount?.articleTheme),
-      themeOverrides: wxAccount?.theme,
+      articleThemePath,
+      themeOverrides: standalone ? undefined : wxAccount?.theme,
       timeoutMs: timeoutMs !== undefined && Number.isFinite(timeoutMs) ? timeoutMs : undefined,
       debugDir: debugDir ? resolve(process.cwd(), debugDir) : undefined,
     });

package/src/providers/index.ts

@@ -84,15 +84,17 @@ async function publishWechatArticleRoute({
   try {
     const markdownRenderer = await resolveMarkdownRenderer(config);
     const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
+    // 独立正文配置与发布账号的凭据、默认 CSS 分离。
+    const standalone = articleTheme?.manifest.css !== undefined;
     const rendered = await markdownRenderer.render({
       onProgress: reportProgress,
       markdownPath: exportPostPath,
       outPath: workspacePaths.zotepadExportHtml,
       account,
       title: state.metadata.title,
-      customCss: resolveConfigRelativePath(wxAccount?.customCss),
+      customCss: standalone ? null : resolveConfigRelativePath(wxAccount?.customCss),
       articleThemePath: articleTheme?.path,
-      themeOverrides: wxAccount?.theme,
+      themeOverrides: standalone ? undefined : wxAccount?.theme,
     });
     const { html } = rendered;
 

package/src/runtime-package.ts

@@ -69,13 +69,14 @@ export async function prepareMarkdownRuntime(config: PipelineConfig, accountMap:
     if (!/^[a-zA-Z0-9_.-]{1,80}$/.test(account) || [".", "..", "__proto__", "constructor", "prototype"].includes(account)) throw new Error(`无效的样式账号标识：${account}`);
     if (Object.hasOwn(accounts, account)) throw new Error(`账号映射重复：${account}`);
     const next: Record<string, unknown> = { theme: value.theme, customCss: null, articleTheme: null };
-    if (value.customCss) {
+    const theme = value.articleTheme ? await readArticleTheme(resolveConfigRelativePath(value.articleTheme)!) : null;
+    // 独立配置已内嵌 CSS，部署时不依赖被替代的账号样式文件。
+    if (value.customCss && theme?.manifest.css === undefined) {
       const name = `markdown/custom-css-${account}.css`;
       files.set(name, await readRuntimeSource(resolveConfigRelativePath(value.customCss)!));
       next.customCss = `${RUNTIME_ROOT}/${name}`;
     }
-    if (value.articleTheme) {
-      const theme = await readArticleTheme(resolveConfigRelativePath(value.articleTheme)!);
+    if (theme) {
       const prefix = `markdown/article-themes/${account}`;
       for (const [name, bytes] of theme.files) files.set(`${prefix}/${name}`, bytes);
       files.set(`${prefix}/manifest.json`, Buffer.from(JSON.stringify(theme.manifest, null, 2)));