@zzclub/pipeline 0.2.0 → 0.4.0

package/src/plugins.ts

@@ -0,0 +1,101 @@
+import { abandon } from "./commands/abandon";
+import { attachBody } from "./commands/attach-body";
+import { attachBodyImages } from "./commands/attach-body-images";
+import { attachNewspicSpec } from "./commands/attach-newspic-spec";
+import { checkpoint } from "./commands/checkpoint";
+import { configCommand } from "./commands/config";
+import { cosUpload } from "./commands/cos-upload";
+import { doctor } from "./commands/doctor";
+import { findRun } from "./commands/find-run";
+import { hermesMetrics } from "./commands/hermes-metrics";
+import { ingestHandoff } from "./commands/ingest-handoff";
+import { imgxCommand } from "./commands/imgx";
+import { init } from "./commands/init";
+import { prepareFinalize } from "./commands/prepare-finalize";
+import { prepare } from "./commands/prepare";
+import { publish } from "./commands/publish";
+import { reconcile } from "./commands/reconcile";
+import { render } from "./commands/render";
+import { reset } from "./commands/reset";
+import { review } from "./commands/review";
+import { status } from "./commands/status";
+import { syncBlog } from "./commands/sync-blog";
+import { tasks } from "./commands/tasks";
+import { wechatExport } from "./commands/wechat-export";
+
+export interface CommandDefinition {
+  name: string;
+  summary: string;
+  plugin: string;
+  handler: (args: string[]) => Promise<void>;
+}
+
+export interface CommandPlugin {
+  name: string;
+  commands: CommandDefinition[];
+}
+
+export function getCommandPlugins(): CommandPlugin[] {
+  return [
+    {
+      name: "workflow",
+      commands: [
+        { name: "init", summary: "Create run state from intent classification", plugin: "workflow", handler: init },
+        { name: "ingest-handoff", summary: "Create or resume a task from a publish_handoff/workflow_handoff JSON file", plugin: "workflow", handler: ingestHandoff },
+        { name: "attach-body", summary: "Attach a source body file to a managed task", plugin: "workflow", handler: attachBody },
+        { name: "attach-body-images", summary: "Attach body image marker files to a managed task", plugin: "workflow", handler: attachBodyImages },
+        { name: "attach-newspic-spec", summary: "Attach or update newspic render intent", plugin: "workflow", handler: attachNewspicSpec },
+        { name: "prepare", summary: "Route + author + format + metadata", plugin: "workflow", handler: prepare },
+        { name: "prepare-finalize", summary: "Highlight words + asset save", plugin: "workflow", handler: prepareFinalize },
+        { name: "render", summary: "Image plan + imgx render", plugin: "workflow", handler: render },
+        { name: "publish", summary: "Execute publish routes", plugin: "workflow", handler: publish },
+        { name: "reconcile", summary: "Reconcile managed task materials and derived state", plugin: "workflow", handler: reconcile },
+        { name: "checkpoint", summary: "Read task state and validate current phase", plugin: "workflow", handler: checkpoint },
+        { name: "status", summary: "Read a managed task with gaps and next action", plugin: "workflow", handler: status },
+        { name: "find-run", summary: "Find the best matching managed task", plugin: "workflow", handler: findRun },
+        { name: "tasks", summary: "List managed tasks in the workspace", plugin: "workflow", handler: tasks },
+        { name: "reset", summary: "Reset phases for revision", plugin: "workflow", handler: reset },
+        { name: "review", summary: "Update content review status", plugin: "workflow", handler: review },
+        { name: "abandon", summary: "Mark one or more tasks as abandoned", plugin: "workflow", handler: abandon },
+      ],
+    },
+    {
+      name: "ops",
+      commands: [
+        { name: "sync-blog", summary: "Copy canonical markdown to the blog repo and publish there", plugin: "ops", handler: syncBlog },
+        { name: "imgx", summary: "Run bundled imgx renderer subcommands", plugin: "ops", handler: imgxCommand },
+        { name: "wechat-export", summary: "Render markdown to WeChat HTML with bundled preview styles", plugin: "ops", handler: wechatExport },
+        { name: "cos-upload", summary: "Upload a local image to configured COS CDN", plugin: "ops", handler: cosUpload },
+        { name: "config", summary: "Read or update pipeline config", plugin: "ops", handler: configCommand },
+        { name: "doctor", summary: "Inspect resolved paths and provider health", plugin: "ops", handler: doctor },
+        { name: "hermes-metrics", summary: "Show Hermes execution metrics per task", plugin: "ops", handler: hermesMetrics },
+      ],
+    },
+  ];
+}
+
+export function getCommandRegistry(): Record<string, CommandDefinition> {
+  return Object.fromEntries(
+    getCommandPlugins()
+      .flatMap((plugin) => plugin.commands)
+      .map((command) => [command.name, command]),
+  );
+}
+
+export function formatUsage(): string {
+  const sections = getCommandPlugins().map((plugin) => {
+    const lines = plugin.commands.map(
+      (command) => `  ${command.name.padEnd(18)} ${command.summary}`,
+    );
+    return [`${plugin.name}:`, ...lines].join("\n");
+  });
+
+  return [
+    "Usage: zzhub-pipeline <command> [options]",
+    "",
+    "Commands:",
+    ...sections,
+    "",
+    "Run 'zzhub-pipeline <command> --help' for command-specific options.",
+  ].join("\n");
+}

package/src/profiles.ts

@@ -0,0 +1,149 @@
+/**
+ * profiles.ts — Author selection decision tree
+ *
+ * Replaces the older LLM-based author-selection step with deterministic rules.
+ * Deterministic rules for rewrite_allowed and style_mode.
+ */
+
+import type {
+  ContentOrigin,
+  Authoring,
+} from "./state";
+
+// ── Decision tree ─────────────────────────────────────────────────
+
+/**
+ * Resolve authoring rules based on content_origin, style_hint, and user signals.
+ *
+ * Decision table used by prepare/orchestrator:
+ *
+ * | content_origin | user signal            | rewrite_allowed | style_mode    |
+ * |---------------|------------------------|-----------------|---------------|
+ * | user          | 润色/改一下/按我风格    | yes             | polish        |
+ * | user          | no style request       | no              | none          |
+ * | external      | any                    | yes (forced)    | deep_rewrite  |
+ * | user          | style_hint=fact_report | yes             | fact_report   |
+ * | external      | style_hint=fact_report | yes             | fact_report   |
+ * | unknown       | —                      | ERROR           | ERROR         |
+ */
+export function resolveAuthoring(params: {
+  contentOrigin: ContentOrigin;
+  styleHint: string | null;
+  hasStyleRequest: boolean;
+}): Authoring {
+  const { contentOrigin, styleHint, hasStyleRequest } = params;
+
+  // fact_report overrides everything when explicitly requested
+  if (styleHint === "fact_report") {
+    return {
+      rewrite_allowed: true,
+      style_mode: "fact_report",
+    };
+  }
+
+  // external content always requires deep_rewrite
+  if (contentOrigin === "external") {
+    return {
+      rewrite_allowed: true,
+      style_mode: "deep_rewrite",
+    };
+  }
+
+  // user content with explicit style request
+  if (contentOrigin === "user" && hasStyleRequest) {
+    return {
+      rewrite_allowed: true,
+      style_mode: "polish",
+    };
+  }
+
+  // user content without style request
+  if (contentOrigin === "user") {
+    return {
+      rewrite_allowed: false,
+      style_mode: "none",
+    };
+  }
+
+  // unknown content_origin — should not proceed
+  // Caller (orchestrator) must confirm with user first
+  throw new Error(
+    "content_origin is unknown; orchestrator must confirm ownership before prepare",
+  );
+}
+
+// ── Style request detection ───────────────────────────────────────
+
+/**
+ * Check if user text contains a style processing request.
+ * Keywords: 润色, 改一下, 用我的口吻, 按我的风格, etc.
+ */
+const STYLE_KEYWORDS = [
+  "润色",
+  "改一下",
+  "用我的口吻",
+  "按我的风格",
+  "用我的写法",
+  "改写",
+  "重写",
+  "转成我的风格",
+];
+
+export function hasStyleRequest(text: string): boolean {
+  return STYLE_KEYWORDS.some((kw) => text.includes(kw));
+}
+
+// ── Profile path resolution ───────────────────────────────────────
+
+/**
+ * Resolve the rules profile path for a content_profile name.
+ * These are the constraint files loaded by the style skill.
+ */
+const PROFILE_PATHS: Record<string, string> = {
+  user: "zzhub-media-style/references/user-profile.md",
+  storytelling: "zzhub-media-style/references/storytelling-profile.md",
+};
+
+export function getProfilePath(
+  contentProfile: string,
+): string | null {
+  return PROFILE_PATHS[contentProfile] ?? null;
+}
+
+// ── Requires derivation ───────────────────────────────────────────
+
+/**
+ * Derive intent.requires flags from intent fields.
+ *
+ * Rules (from orchestrator prompt):
+ * - research: user asked "先搜/查资料" or material insufficient
+ * - style: content_origin=external OR style_hint=fact_report OR style request
+ * - render: content_form=newspic OR route.primary=wechat-article
+ * - publish: task_kind=publish
+ */
+export function deriveRequires(params: {
+  taskKind: string;
+  contentForm: string;
+  contentOrigin: ContentOrigin;
+  styleHint: string | null;
+  routePrimary: string;
+  hasResearchRequest: boolean;
+  hasStyleRequest: boolean;
+}): {
+  research: boolean;
+  style: boolean;
+  render: boolean;
+  publish: boolean;
+} {
+  return {
+    research: params.hasResearchRequest,
+    style:
+      params.contentOrigin === "external" ||
+      params.styleHint === "fact_report" ||
+      params.hasStyleRequest,
+    render:
+      params.contentForm === "newspic" ||
+      params.routePrimary === "wechat-article",
+    publish: params.taskKind === "publish",
+  };
+}

package/src/providers/blog.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import { join } from "path";
+import { extractLocalImagePaths, replaceLocalImagePaths } from "./blog";
+
+describe("extractLocalImagePaths", () => {
+  test("extracts local image paths from markdown", () => {
+    const content = "![cover](./cover.jpg)\n\nSome text\n\n![other](images/other.png)";
+    const pathMap = extractLocalImagePaths(content, "/workspace/assets");
+    expect(pathMap.get("./cover.jpg")).toBe(join("/workspace/assets", "cover.jpg"));
+    expect(pathMap.get("images/other.png")).toBe(join("/workspace/assets", "images/other.png"));
+  });
+
+  test("skips http/https URLs", () => {
+    const content = "![remote](https://example.com/img.png)\n![local](./local.png)";
+    const pathMap = extractLocalImagePaths(content, "/workspace");
+    expect(pathMap.size).toBe(1);
+    expect(pathMap.has("./local.png")).toBe(true);
+  });
+
+  test("returns empty map for no images", () => {
+    expect(extractLocalImagePaths("just text", "/workspace").size).toBe(0);
+  });
+
+  test("handles multiple images", () => {
+    const content = "![a](a.png) ![b](b.png) ![c](c.png)";
+    const pathMap = extractLocalImagePaths(content, "/base");
+    expect(pathMap.size).toBe(3);
+  });
+});
+
+describe("replaceLocalImagePaths", () => {
+  test("replaces local paths with URLs from the map", () => {
+    const content = "![cover](./cover.jpg)";
+    const urlMap = new Map([["./cover.jpg", "https://cdn.com/cover.jpg"]]);
+    const result = replaceLocalImagePaths(content, urlMap);
+    expect(result).toBe("![cover](https://cdn.com/cover.jpg)");
+  });
+
+  test("leaves unmapped images unchanged", () => {
+    const content = "![a](./a.png) ![b](./b.png)";
+    const urlMap = new Map([["./a.png", "https://cdn.com/a.png"]]);
+    const result = replaceLocalImagePaths(content, urlMap);
+    expect(result).toBe("![a](https://cdn.com/a.png) ![b](./b.png)");
+  });
+
+  test("leaves http URLs untouched", () => {
+    const content = "![remote](https://example.com/img.png)";
+    const urlMap = new Map<string, string>();
+    expect(replaceLocalImagePaths(content, urlMap)).toBe(content);
+  });
+
+  test("preserves alt text", () => {
+    const content = "![my alt text](./img.png)";
+    const urlMap = new Map([["./img.png", "https://cdn.com/img.png"]]);
+    const result = replaceLocalImagePaths(content, urlMap);
+    expect(result).toBe("![my alt text](https://cdn.com/img.png)");
+  });
+});

package/src/providers/blog.ts

@@ -0,0 +1,154 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { PipelineConfig, ResolvedWorkspacePaths } from "../config";
+import { spawnSync } from "../spawn";
+import { PublishResult, WorkflowState } from "../state";
+import { stripFrontmatter } from "../text";
+import { uploadFileToCos } from "./cos";
+
+interface BlogPublishContext {
+  state: WorkflowState;
+  dryRun: boolean;
+  config: PipelineConfig;
+  workspacePaths: ResolvedWorkspacePaths;
+}
+
+// ![alt](path) — skips http(s):// URLs, captures [1]=alt [2]=rawPath
+const LOCAL_IMAGE_RE = /!\[([^\]]*)\]\((?!https?:\/\/)([^)]+)\)/g;
+
+export function extractLocalImagePaths(content: string, assetPath: string): Map<string, string> {
+  const pathMap = new Map<string, string>();
+  for (const match of content.matchAll(LOCAL_IMAGE_RE)) {
+    const rawPath = match[2].trim();
+    pathMap.set(rawPath, resolve(assetPath, rawPath));
+  }
+  return pathMap;
+}
+
+export function replaceLocalImagePaths(content: string, urlMap: Map<string, string>): string {
+  return content.replace(LOCAL_IMAGE_RE, (original, alt: string, rawPath: string) => {
+    const url = urlMap.get(rawPath.trim());
+    return url ? `![${alt}](${url})` : original;
+  });
+}
+
+async function uploadBlogImages(
+  content: string,
+  assetPath: string,
+  slug: string,
+  config: PipelineConfig,
+  dryRun: boolean,
+): Promise<{ content: string; uploadedCount: number }> {
+  const pathMap = extractLocalImagePaths(content, assetPath);
+  if (pathMap.size === 0) {
+    return { content, uploadedCount: 0 };
+  }
+
+  const cosPat = config.cos.pat;
+  if (!cosPat) {
+    throw new Error("No COS PAT configured. Set cos.pat in config.");
+  }
+
+  const folder = `blog/${slug}`;
+  const urlMap = new Map<string, string>();
+
+  for (const [rawPath, absPath] of pathMap) {
+    const filename = absPath.split("/").pop()!;
+    if (dryRun) {
+      console.error(`[dry-run] COS upload: ${absPath} -> ${folder}/${filename}`);
+      urlMap.set(rawPath, `${config.cos.publicBaseUrl}/${folder}/${filename}`);
+      continue;
+    }
+
+    const result = await uploadFileToCos({
+      localPath: absPath,
+      folder,
+      baseUrl: config.cos.baseUrl || config.wx.baseUrl,
+      cosPat,
+      publicBaseUrl: config.cos.publicBaseUrl,
+    });
+    urlMap.set(rawPath, result.url);
+  }
+
+  return {
+    content: replaceLocalImagePaths(content, urlMap),
+    uploadedCount: pathMap.size,
+  };
+}
+
+export async function publishBlogRoute({
+  state,
+  dryRun,
+  config,
+  workspacePaths,
+}: BlogPublishContext): Promise<PublishResult> {
+  const postPath = join(state.asset_path, "post.md");
+  const postContent = await readFile(postPath, "utf-8");
+  const category = "posts";
+  const blogRoot = workspacePaths.blogRoot;
+  const blogPostPath = join(blogRoot, "content", category, `${state.metadata.slug}.md`);
+
+  const lines = ["---"];
+  lines.push(`title: "${state.metadata.title.replace(/"/g, '\\"')}"`);
+  lines.push(`date: ${state.metadata.date}`);
+  if (state.metadata.description) {
+    lines.push(`description: "${state.metadata.description.replace(/"/g, '\\"')}"`);
+  }
+  if (state.metadata.tags.length > 0) {
+    lines.push("tags:");
+    for (const tag of state.metadata.tags) {
+      lines.push(`  - ${tag}`);
+    }
+  }
+  const author = state.route.content_profile || "default";
+  lines.push(`author: ${author}`);
+  lines.push("---");
+
+  const bodyWithFrontmatter = `${lines.join("\n")}\n\n${stripFrontmatter(postContent)}`;
+
+  const { content: blogContent, uploadedCount } = await uploadBlogImages(
+    bodyWithFrontmatter,
+    state.asset_path,
+    state.metadata.slug,
+    config,
+    dryRun,
+  );
+
+  if (dryRun) {
+    console.error(`[dry-run] Blog: ${uploadedCount} image(s) would be uploaded to COS`);
+    console.error(`[dry-run] Blog: write to ${blogPostPath}`);
+    console.error(`[dry-run] Blog: cd ${blogRoot} && ${config.commands.blogPublish.join(" ")}`);
+    return {
+      route: "blog",
+      status: "skipped",
+      detail: "dry-run",
+      published_at: null,
+      content_version: state.artifacts.content_version,
+      render_version: state.artifacts.render_version,
+    };
+  }
+
+  await mkdir(join(blogRoot, "content", category), { recursive: true });
+  await writeFile(blogPostPath, blogContent, "utf-8");
+  const result = spawnSync(config.commands.blogPublish, { cwd: blogRoot });
+
+  if (result.exitCode !== 0) {
+    return {
+      route: "blog",
+      status: "failed",
+      detail: `blog publish command failed: ${config.commands.blogPublish.join(" ")}`,
+      published_at: null,
+      content_version: state.artifacts.content_version,
+      render_version: state.artifacts.render_version,
+    };
+  }
+
+  return {
+    route: "blog",
+    status: "success",
+    detail: null,
+    published_at: new Date().toISOString(),
+    content_version: state.artifacts.content_version,
+    render_version: state.artifacts.render_version,
+  };
+}

package/src/providers/cos.ts

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync } from "fs";
+import { basename } from "path";
+import COS from "cos-nodejs-sdk-v5";
+
+const STS_PATH = "/api/v1/upload/cos";
+const STS_TIMEOUT = 30000;
+const UPLOAD_TIMEOUT = 120000;
+
+const EXTENSION_CONTENT_TYPES = new Map<string, string>([
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".png", "image/png"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"],
+]);
+
+export interface CosUploadResult {
+  localPath: string;
+  key: string;
+  url: string;
+}
+
+interface StsPayload {
+  TmpSecretId: string;
+  TmpSecretKey: string;
+  SessionToken: string;
+  StartTime: number;
+  ExpiredTime: number;
+  Bucket: string;
+  Region: string;
+  Key: string;
+}
+
+interface StsApiResponse {
+  code?: number;
+  message?: string;
+  data?: {
+    TmpSecretId?: string;
+    TmpSecretKey?: string;
+    SessionToken?: string;
+    StartTime?: number;
+    ExpiredTime?: number;
+    Bucket?: string;
+    Region?: string;
+    Key?: string;
+  };
+}
+
+async function requestJson(
+  url: string,
+  options: { method: string; headers: Record<string, string>; body?: unknown },
+  timeout: number,
+): Promise<unknown> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(url, {
+      method: options.method,
+      headers: options.headers,
+      body: options.body ? JSON.stringify(options.body) : undefined,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`COS STS request failed: HTTP ${response.status} — ${text}`);
+    }
+    return text ? JSON.parse(text) : {};
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function requestSts(
+  baseUrl: string,
+  pat: string,
+  filename: string,
+  folder: string,
+): Promise<StsPayload> {
+  const response = (await requestJson(
+    `${baseUrl.replace(/\/$/, "")}${STS_PATH}`,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${pat}`,
+      },
+      body: { filename, folder: { name: folder } },
+    },
+    STS_TIMEOUT,
+  )) as StsApiResponse;
+
+  const d = response?.data;
+  if (
+    !d?.TmpSecretId ||
+    !d?.TmpSecretKey ||
+    !d?.SessionToken ||
+    !d?.Bucket ||
+    !d?.Region ||
+    !d?.Key ||
+    d.StartTime === undefined ||
+    d.ExpiredTime === undefined
+  ) {
+    throw new Error(`COS STS response incomplete: ${JSON.stringify(response)}`);
+  }
+
+  return {
+    TmpSecretId: d.TmpSecretId,
+    TmpSecretKey: d.TmpSecretKey,
+    SessionToken: d.SessionToken,
+    StartTime: d.StartTime,
+    ExpiredTime: d.ExpiredTime,
+    Bucket: d.Bucket,
+    Region: d.Region,
+    Key: d.Key,
+  };
+}
+
+export async function uploadFileToCos(input: {
+  localPath: string;
+  folder: string;
+  baseUrl: string;
+  cosPat: string;
+  publicBaseUrl: string;
+}): Promise<CosUploadResult> {
+  const { localPath, folder, baseUrl, cosPat, publicBaseUrl } = input;
+
+  if (!existsSync(localPath)) {
+    throw new Error(`File not found: ${localPath}`);
+  }
+
+  const filename = basename(localPath);
+  const ext = filename.toLowerCase().match(/\.[^.]+$/)?.[0] ?? "";
+  const contentType = EXTENSION_CONTENT_TYPES.get(ext);
+  if (!contentType) {
+    throw new Error(
+      `Unsupported image type: ${filename}. Supported: ${[...EXTENSION_CONTENT_TYPES.keys()].join(", ")}`,
+    );
+  }
+
+  const sts = await requestSts(baseUrl, cosPat, filename, folder);
+  const buffer = readFileSync(localPath);
+
+  const cos = new COS({
+    SecretId: sts.TmpSecretId,
+    SecretKey: sts.TmpSecretKey,
+    SecurityToken: sts.SessionToken,
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const timeoutId = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`COS upload timed out: ${filename}`));
+    }, UPLOAD_TIMEOUT);
+
+    cos.putObject(
+      {
+        Bucket: sts.Bucket,
+        Region: sts.Region,
+        Key: sts.Key,
+        Body: buffer,
+        ContentType: contentType,
+      },
+      (err) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeoutId);
+        if (err) {
+          reject(new Error(`COS upload failed: ${err.message ?? JSON.stringify(err)}`));
+        } else {
+          resolve();
+        }
+      },
+    );
+  });
+
+  return {
+    localPath,
+    key: sts.Key,
+    url: `${publicBaseUrl}/${sts.Key}`,
+  };
+}

package/src/providers/index.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { getPublishProvider, listPublishProviders } from "./index";
+
+describe("listPublishProviders", () => {
+  test("returns registered routes", () => {
+    const routes = listPublishProviders();
+    expect(routes).toContain("wechat-article");
+    expect(routes).toContain("wechat-newspic");
+  });
+});
+
+describe("getPublishProvider", () => {
+  test("returns a function for wechat-article", () => {
+    const provider = getPublishProvider("wechat-article");
+    expect(typeof provider).toBe("function");
+  });
+
+  test("returns a function for wechat-newspic", () => {
+    const provider = getPublishProvider("wechat-newspic");
+    expect(typeof provider).toBe("function");
+  });
+
+  test("throws for unregistered route", () => {
+    expect(() => getPublishProvider("blog" as never)).toThrow();
+  });
+});