@zzclub/pipeline 0.4.0 → 0.9.0

package/README.md

@@ -43,7 +43,7 @@ bun install --global .
 - `wechat-article` — 公众号文章草稿（HTML）
 - `wechat-newspic` — 公众号图片消息（PNG 卡片/图集）
 
-`blog` 只做事后同步（`sync-blog`），不参与主工作流分支。
+`blog` 只做事后同步（`sync-blog`），不参与主工作流分支，但同步结果会写回 `workflow-state.json` 的 `publish.results`。
 
 状态文件分两类：
 
@@ -409,17 +409,21 @@ src/
 | `review` | Update content review status |
 | `abandon` | Mark one or more tasks as abandoned |
 
-`ops` 组，7 个命令：
+`ops` 组，11 个命令：
 
 | 命令 | 说明 |
 | --- | --- |
-| `sync-blog` | Copy canonical markdown to the blog repo and publish there |
+| `sync-blog` | Copy post.md to blog repo, publish, and record result in state JSON |
 | `imgx` | Run bundled imgx renderer subcommands |
 | `wechat-export` | Render markdown to WeChat HTML with bundled preview styles |
 | `cos-upload` | Upload a local image to configured COS CDN |
 | `config` | Read or update pipeline config |
 | `doctor` | Inspect resolved paths and provider health |
 | `hermes-metrics` | Show Hermes execution metrics per task |
+| `wx-drafts` | List or get drafts from WeChat draft box |
+| `wx-draft-delete` | Delete a draft from WeChat draft box |
+| `topic` | 选题管理（添加、列表、更新、排期、复盘、放弃） |
+| `analytics` | 发布数据录入和分析 |
 
 ## 常用命令
 
@@ -514,6 +518,75 @@ bun run src/cli.ts reset --state {state_path} --mode full         # 完全放弃
 
 每种模式均会设置 `redo_hint`，确保 Agent 恢复时知道从哪个子步骤开始。
 
+### 选题管理
+
+使用 `topic` 命令管理内容选题的完整生命周期：
+
+```bash
+# 添加选题
+bun run src/cli.ts topic add \
+  --workspace {workspace} \
+  --title "AI 工具推荐" \
+  --priority high \
+  --tags "AI,工具"
+
+# 列出选题
+bun run src/cli.ts topic list --workspace {workspace}
+bun run src/cli.ts topic list --workspace {workspace} --status backlog --priority high
+
+# 更新选题（AI 评估）
+bun run src/cli.ts topic update \
+  --workspace {workspace} \
+  --topic {topic_id} \
+  --ai-score 85 \
+  --ai-reason "基于热点趋势和受众匹配度"
+
+# 排期
+bun run src/cli.ts topic schedule \
+  --workspace {workspace} \
+  --topic {topic_id} \
+  --scheduled-date 2026-06-15 \
+  --target-account default
+
+# 复盘（发布后）
+bun run src/cli.ts topic retro \
+  --workspace {workspace} \
+  --topic {topic_id} \
+  --performance good \
+  --lessons "标题悬念效果好" \
+  --metrics-snapshot '{"reads": 1500, "likes": 45}'
+
+# 放弃选题
+bun run src/cli.ts topic abandon \
+  --workspace {workspace} \
+  --topic {topic_id} \
+  --reason "话题过时"
+```
+
+选题状态流转：`backlog` → `evaluating` → `scheduled` → `in_progress` → `published`（或 `abandoned`）
+
+### 数据分析
+
+使用 `analytics` 命令录入和分析发布后的数据：
+
+```bash
+# 录入发布数据
+bun run src/cli.ts analytics record \
+  --state {workspace}/posts/{date-slug}/workflow-state.json \
+  --reads 1500 \
+  --likes 45 \
+  --favorites 23 \
+  --shares 12 \
+  --comments 8 \
+  --notes "标题效果好，转化率高"
+
+# 列出历史数据
+bun run src/cli.ts analytics list --workspace {workspace}
+bun run src/cli.ts analytics list --workspace {workspace} --days 30 --sort reads
+```
+
+数据存储在 `{workspace}/zzhub.db`（SQLite 数据库），支持复杂查询和统计分析。
+
 ### Blog 同步
 
 ```bash
@@ -525,6 +598,7 @@ bun run src/cli.ts sync-blog --state {workspace}/posts/{date-slug}/workflow-stat
 - 读取 canonical `post.md`
 - 复制到博客仓库 `content/posts/<slug>.md`
 - 执行博客发布命令
+- 将 blog publish result 写回 `workflow-state.json`，方便筛查是否遗漏同步
 
 ### 配置管理
 
@@ -553,6 +627,31 @@ bun run src/cli.ts wechat-export --body /abs/path/body.md --account default
 bun run src/cli.ts cos-upload --file /abs/path/image.png --folder notes/note-id --alt image
 ```
 
+### 草稿箱管理
+
+```bash
+# 列出草稿（账号不传时使用 wx.defaultAccount）
+bun run src/cli.ts wx-drafts --limit 10
+
+# 获取某篇草稿的完整内容（含 HTML）
+bun run src/cli.ts wx-drafts --media-id MEDIA_ID
+
+# 删除一篇草稿
+bun run src/cli.ts wx-draft-delete --media-id MEDIA_ID
+```
+
+`--account` 参数可选，默认使用配置中的 `wx.defaultAccount`。
+
+### init 可选参数
+
+```bash
+# 更新已有草稿而非新建（配合 --existing-draft-media-id）
+bun run src/cli.ts init ... --existing-draft-media-id MEDIA_ID
+
+# 关联 Nezus note 用于发布结果回调
+bun run src/cli.ts init ... --note-id NOTE_ID
+```
+
 ## 状态文件
 
 最重要的字段是：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.4.0",
+  "version": "0.9.0",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",

package/src/adapter-types.ts

@@ -137,6 +137,12 @@ export interface MarkdownRenderInput {
 
   /** Workflow state for context */
   state?: WorkflowState;
+
+  /** Per-account theme overrides from config. Deep-merged onto hardcoded defaults. */
+  themeOverrides?: {
+    editorVars?: Record<string, string>;
+    exportTheme?: Record<string, string>;
+  };
 }
 
 /**

package/src/adapters/builtin-image-renderer.ts

@@ -144,6 +144,12 @@ async function renderCover(
 
   if (template === "wechat-cover-split") {
     const cmdParts = ["--template", "wechat-cover-split", "--text", title];
+    if (visualParams) {
+      cmdParts.push("--highlight", visualParams.highlight);
+      cmdParts.push("--bg", visualParams.bg);
+      cmdParts.push("--footer", visualParams.footer);
+      cmdParts.push("--fallback-icon", visualParams.fallback_icon);
+    }
     cmdParts.push("--highlight-words", highlightWords.join(","));
     cmdParts.push("--out", coverOut);
     runRenderCardCli(cmdParts);
@@ -303,7 +309,7 @@ export const builtinImageRenderer: ImageRenderPlugin = {
 
     if (route === "wechat-article") {
       // Article: cover only (wechat-cover-split)
-      const cover = await renderCover("wechat-cover-split", title, outputDir, null, highlightWords);
+      const cover = await renderCover("wechat-cover-split", title, outputDir, vp, highlightWords);
       return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
     }
 

package/src/adapters/builtin-markdown-renderer.ts

@@ -50,6 +50,7 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
       title: input.title,
       previewShellOutPath: input.previewShellOutPath,
       customCss: input.customCss,
+      themeOverrides: input.themeOverrides,
     });
 
     return {

package/src/commands/analytics.test.ts

@@ -0,0 +1,155 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { recordAnalytics, listAnalytics } from "./analytics";
+
+describe("analytics commands", () => {
+  let workspace: string;
+
+  beforeEach(async () => {
+    workspace = await mkdtemp(join(tmpdir(), "zzhub-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(workspace, { recursive: true, force: true });
+  });
+
+  describe("recordAnalytics", () => {
+    test("records analytics from state file", async () => {
+      const statePath = join(workspace, "state.json");
+      await writeFile(statePath, JSON.stringify({
+        run_id: "run_001",
+        metadata: {
+          title: "Test Article",
+          date: "2026-06-11",
+        },
+        route: {
+          primary: "wechat-article",
+        },
+        publish: {
+          results: {
+            wechat: {
+              status: "success",
+              published_at: "2026-06-11T10:00:00Z",
+            },
+          },
+        },
+      }));
+
+      const result = await recordAnalytics({
+        statePath,
+        reads: 1500,
+        likes: 45,
+        favorites: 23,
+        shares: 12,
+        comments: 8,
+        notes: "Good performance",
+      });
+
+      expect(result.run_id).toBe("run_001");
+      expect(result.reads).toBe(1500);
+      expect(result.likes).toBe(45);
+      expect(result.favorites).toBe(23);
+      expect(result.shares).toBe(12);
+      expect(result.comments).toBe(8);
+      expect(result.notes).toBe("Good performance");
+      expect(result.title).toBe("Test Article");
+      expect(result.publish_date).toBe("2026-06-11");
+    });
+
+    test("defaults missing metrics to 0", async () => {
+      const statePath = join(workspace, "state.json");
+      await writeFile(statePath, JSON.stringify({
+        run_id: "run_002",
+        metadata: { title: "Minimal", date: "2026-06-11" },
+        route: { primary: "wechat-article" },
+        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+      }));
+
+      const result = await recordAnalytics({ statePath });
+
+      expect(result.run_id).toBe("run_002");
+      expect(result.reads).toBe(0);
+      expect(result.likes).toBe(0);
+      expect(result.favorites).toBe(0);
+      expect(result.shares).toBe(0);
+      expect(result.comments).toBe(0);
+    });
+
+    test("re-recording replaces previous entry", async () => {
+      const statePath = join(workspace, "state.json");
+      await writeFile(statePath, JSON.stringify({
+        run_id: "run_003",
+        metadata: { title: "Update Me", date: "2026-06-11" },
+        route: { primary: "wechat-article" },
+        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+      }));
+
+      await recordAnalytics({ statePath, reads: 100 });
+      const updated = await recordAnalytics({ statePath, reads: 200 });
+
+      expect(updated.reads).toBe(200);
+
+      const all = await listAnalytics(workspace, {});
+      expect(all.filter(a => a.run_id === "run_003").length).toBe(1);
+    });
+  });
+
+  describe("listAnalytics", () => {
+    test("lists all analytics", async () => {
+      const statePath1 = join(workspace, "state1.json");
+      await writeFile(statePath1, JSON.stringify({
+        run_id: "run_001",
+        metadata: { title: "Article 1", date: "2026-06-11" },
+        route: { primary: "wechat-article" },
+        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+      }));
+
+      const statePath2 = join(workspace, "state2.json");
+      await writeFile(statePath2, JSON.stringify({
+        run_id: "run_002",
+        metadata: { title: "Article 2", date: "2026-06-12" },
+        route: { primary: "wechat-article" },
+        publish: { results: { wechat: { status: "success", published_at: "2026-06-12T10:00:00Z" } } },
+      }));
+
+      await recordAnalytics({ statePath: statePath1, reads: 1000 });
+      await recordAnalytics({ statePath: statePath2, reads: 2000 });
+
+      const analytics = await listAnalytics(workspace, {});
+      expect(analytics.length).toBe(2);
+    });
+
+    test("filters by days", async () => {
+      const statePath = join(workspace, "state.json");
+      await writeFile(statePath, JSON.stringify({
+        run_id: "run_001",
+        metadata: { title: "Article", date: "2026-06-11" },
+        route: { primary: "wechat-article" },
+        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+      }));
+
+      await recordAnalytics({ statePath, reads: 1000 });
+
+      const analytics = await listAnalytics(workspace, { days: 30 });
+      expect(analytics.length).toBe(1);
+    });
+
+    test("limits results", async () => {
+      for (let i = 0; i < 5; i++) {
+        const statePath = join(workspace, `state${i}.json`);
+        await writeFile(statePath, JSON.stringify({
+          run_id: `run_${String(i).padStart(3, "0")}`,
+          metadata: { title: `Article ${i}`, date: "2026-06-11" },
+          route: { primary: "wechat-article" },
+          publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+        }));
+        await recordAnalytics({ statePath, reads: 100 * (i + 1) });
+      }
+
+      const analytics = await listAnalytics(workspace, { limit: 3 });
+      expect(analytics.length).toBe(3);
+    });
+  });
+});

package/src/commands/analytics.ts

@@ -0,0 +1,223 @@
+import { readFile } from "fs/promises";
+import { dirname } from "path";
+import { ensureDb } from "../db";
+import { AnalyticsSchema, type Analytics } from "../schema/analytics";
+import { parseArgs, requireArg, optionalArg } from "../args";
+import { printResult } from "../output";
+
+export interface RecordAnalyticsInput {
+  statePath: string;
+  reads?: number;
+  likes?: number;
+  favorites?: number;
+  shares?: number;
+  comments?: number;
+  notes?: string;
+}
+
+function resolveWorkspace(statePath: string): string {
+  const postsIdx = statePath.lastIndexOf("/posts/");
+  if (postsIdx !== -1) {
+    return statePath.substring(0, postsIdx);
+  }
+  return dirname(statePath);
+}
+
+export async function recordAnalytics(
+  input: RecordAnalyticsInput,
+): Promise<Analytics> {
+  const stateContent = await readFile(input.statePath, "utf-8");
+  const state = JSON.parse(stateContent);
+
+  const workspace = resolveWorkspace(input.statePath);
+  const db = ensureDb(workspace);
+
+  try {
+    const now = new Date().toISOString();
+    const publishDate = state.metadata?.date || now.split("T")[0];
+    const title = state.metadata?.title || "Untitled";
+    const topicId = state.topic_id || null;
+
+    db.prepare(
+      `INSERT OR REPLACE INTO analytics (
+        run_id, topic_id, title, publish_date,
+        reads, likes, favorites, shares, comments,
+        notes, recorded_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      state.run_id,
+      topicId,
+      title,
+      publishDate,
+      input.reads ?? 0,
+      input.likes ?? 0,
+      input.favorites ?? 0,
+      input.shares ?? 0,
+      input.comments ?? 0,
+      input.notes ?? null,
+      now,
+    );
+
+    const row = db
+      .prepare("SELECT * FROM analytics WHERE run_id = ?")
+      .get(state.run_id) as Record<string, unknown>;
+    return AnalyticsSchema.parse(row);
+  } finally {
+    db.close();
+  }
+}
+
+export interface ListAnalyticsFilter {
+  days?: number;
+  sort?: string;
+  limit?: number;
+}
+
+const ALLOWED_SORT_FIELDS = new Set([
+  "publish_date",
+  "reads",
+  "likes",
+  "favorites",
+  "shares",
+  "comments",
+  "recorded_at",
+  "title",
+]);
+
+export async function listAnalytics(
+  workspace: string,
+  filter: ListAnalyticsFilter,
+): Promise<Analytics[]> {
+  const db = ensureDb(workspace);
+
+  try {
+    const conditions: string[] = [];
+    const params: (string | number)[] = [];
+
+    if (filter.days) {
+      conditions.push("publish_date >= date('now', ?)");
+      params.push(`-${filter.days} days`);
+    }
+
+    const where =
+      conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+
+    const sortField = filter.sort || "publish_date";
+    if (!ALLOWED_SORT_FIELDS.has(sortField)) {
+      throw new Error(
+        `Invalid sort field: ${sortField}. Allowed: ${[...ALLOWED_SORT_FIELDS].join(", ")}`,
+      );
+    }
+
+    const limit = filter.limit ?? 50;
+
+    const sql = `SELECT * FROM analytics ${where} ORDER BY ${sortField} DESC LIMIT ?`;
+    params.push(limit);
+
+    const rows = db
+      .prepare(sql)
+      .all(...params) as Record<string, unknown>[];
+    return rows.map((row) => AnalyticsSchema.parse(row));
+  } finally {
+    db.close();
+  }
+}
+
+// CLI handler
+export async function analytics(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help || args.length === 0) {
+    console.log(`
+Usage: zzhub-pipeline analytics <subcommand> [options]
+
+Subcommands:
+  record     Record post-publish metrics
+  list       List analytics history
+
+Run 'zzhub-pipeline analytics <subcommand> --help' for details.
+`.trim());
+    return;
+  }
+
+  const subcommand = args[0];
+  const subArgs = args.slice(1);
+
+  switch (subcommand) {
+    case "record":
+      return analyticsRecord(subArgs);
+    case "list":
+      return analyticsList(subArgs);
+    default:
+      throw new Error(`Unknown analytics subcommand: ${subcommand}`);
+  }
+}
+
+async function analyticsRecord(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline analytics record [options]
+
+Options:
+  --state      State file path (required)
+  --reads      Read count
+  --likes      Like count
+  --favorites  Favorite count
+  --shares     Share count
+  --comments   Comment count
+  --notes      Notes
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "State file path");
+  const readsStr = optionalArg(parsed, "reads");
+  const likesStr = optionalArg(parsed, "likes");
+  const favoritesStr = optionalArg(parsed, "favorites");
+  const sharesStr = optionalArg(parsed, "shares");
+  const commentsStr = optionalArg(parsed, "comments");
+  const notes = optionalArg(parsed, "notes");
+
+  const result = await recordAnalytics({
+    statePath,
+    reads: readsStr ? parseInt(readsStr, 10) : undefined,
+    likes: likesStr ? parseInt(likesStr, 10) : undefined,
+    favorites: favoritesStr ? parseInt(favoritesStr, 10) : undefined,
+    shares: sharesStr ? parseInt(sharesStr, 10) : undefined,
+    comments: commentsStr ? parseInt(commentsStr, 10) : undefined,
+    notes,
+  });
+
+  printResult(result);
+}
+
+async function analyticsList(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline analytics list [options]
+
+Options:
+  --workspace  Workspace path (required)
+  --days       Show last N days (default: all)
+  --sort       Sort field: publish_date/reads/likes (default: publish_date)
+  --limit      Max results (default: 50)
+  --view       Output format: json/markdown/agent (default: json)
+`.trim());
+    return;
+  }
+
+  const workspace = requireArg(parsed, "workspace", "Workspace path");
+  const daysStr = optionalArg(parsed, "days");
+  const days = daysStr ? parseInt(daysStr, 10) : undefined;
+  const sort = optionalArg(parsed, "sort");
+  const limitStr = optionalArg(parsed, "limit");
+  const limit = limitStr ? parseInt(limitStr, 10) : undefined;
+
+  const result = await listAnalytics(workspace, { days, sort, limit });
+
+  printResult(result);
+}

package/src/commands/init.ts

@@ -16,7 +16,8 @@
  *     [--requires-research] \
  *     [--requires-style] \
  *     [--requires-render] \
- *     [--requires-publish]
+ *     [--requires-publish] \
+ *     [--existing-draft-media-id MEDIA_ID]
  *
  * Output: JSON state written to {workspace}/.zzhub-media/runs/{run_id}.json
  *         Prints the state path to stdout.
@@ -35,6 +36,7 @@ import {
   writeState,
   type ContentForm,
   type ContentOrigin,
+  type PublishTarget,
   type Target,
   type TaskKind,
 } from "../state";
@@ -60,6 +62,7 @@ Options:
   --requires-style     Flag
   --requires-render    Flag
   --requires-publish   Flag
+  --existing-draft-media-id  Update existing WeChat draft instead of creating new one (optional)
 `.trim());
     return;
   }
@@ -72,11 +75,37 @@ Options:
   const accountOverride = optionalArg(parsed, "account");
   const styleHint = optionalArg(parsed, "style-hint") ?? null;
   const newspicRenderSpecFile = optionalArg(parsed, "newspic-render-spec-file");
+  const existingDraftMediaId = optionalArg(parsed, "existing-draft-media-id") ?? null;
+  const noteId = optionalArg(parsed, "note-id") ?? null;
   const config = loadConfig();
   const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
 
   const targets = targetsRaw.split(",").map((t) => t.trim()) as Target[];
 
+  // Parse multi-target format: "route@account,route@account,..."
+  // Also supports RoutePrimary values (wechat-article, wechat-newspic, blog)
+  // which need to be mapped to Target enum (wechat, blog) for intent.targets.
+  const publishTargets: PublishTarget[] = [];
+  const targetParts = targetsRaw.split(",").map((t) => t.trim());
+  const defaultAccount = accountOverride || "default";
+  const mappedTargets: Target[] = [];
+
+  for (const part of targetParts) {
+    const atIdx = part.indexOf("@");
+    const route = atIdx !== -1 ? part.slice(0, atIdx).trim() : part;
+    const account = atIdx !== -1 ? part.slice(atIdx + 1).trim() : defaultAccount;
+    publishTargets.push({ route: route as any, account });
+    // Map RoutePrimary to Target enum: wechat-* → "wechat", blog → "blog"
+    mappedTargets.push(route.startsWith("wechat") ? "wechat" : route as Target);
+  }
+
+  // Single target: leave publish_targets empty (backward compat)
+  // Multi-target: populate publish_targets
+  const isMultiTarget = publishTargets.length > 1 || targetsRaw.includes("@");
+
+  // Use mapped targets (Target enum) for intent, not raw RoutePrimary values
+  const intentTargets = mappedTargets.length > 0 ? mappedTargets : targets;
+
   const runId = generateRunId();
   const statePath = getRunStatePath(workspace, runId);
   let newspicRender = null;
@@ -94,13 +123,21 @@ Options:
   state.route = resolveFullRoute(intentText, {
     account: accountOverride,
     contentForm,
-    targets,
+    targets: intentTargets,
   });
 
+  // Set publish_targets if multi-target
+  if (isMultiTarget && publishTargets.length > 0) {
+    state.publish_targets = publishTargets;
+    // First target becomes primary route
+    state.route.primary = publishTargets[0].route as any;
+    state.route.account = publishTargets[0].account;
+  }
+
   state.intent = {
     task_kind: taskKind,
     content_form: contentForm,
-    targets,
+    targets: intentTargets,
     content_origin: contentOrigin,
     intent_text: intentText || null,
     explicit_constraints: [],
@@ -112,6 +149,8 @@ Options:
       render: flagArg(parsed, "requires-render"),
       publish: flagArg(parsed, "requires-publish"),
     },
+    existing_draft_media_id: existingDraftMediaId,
+    note_id: noteId,
   };
 
   await writeState(statePath, state);