@gobing-ai/knowledge-kit 0.1.8 → 0.1.9

package/plugins/publishings/podcast-pub/src/show-notes.ts

@@ -12,6 +12,14 @@
  */
 
 import type { Doc } from '@gobing-ai/kk-core';
+import {
+    type PlanItem,
+    type PodcastSeoConfig,
+    SEO_DEFAULTS,
+    showNotesSummaryParagraph,
+    type TimelineStyle,
+    warn,
+} from './seo';
 
 /** Escapes text content and attribute values (`&`, `<`, `>`, `"`). */
 function escapeHtml(value: string): string {
@@ -133,7 +141,7 @@ function isGeneratedTimeline(block: string): boolean {
  * input. `ponytail`: no JS — timestamp deep-linking depends on the theme's player
  * API; add when microfeed exposes one.
  */
-function renderTimelineHtml(docs: Doc[], offsets: number[], articleUrl: string): string {
+function renderTimelineHtml(docs: Doc[], offsets: number[], articleUrl: string, style: TimelineStyle): string {
     const rows = docs
         .map((d, i) => {
             const title = escapeHtml(d.title ?? `条目 ${i + 1}`);
@@ -152,11 +160,15 @@ function renderTimelineHtml(docs: Doc[], offsets: number[], articleUrl: string):
     const articleTail = isHttpUrl(articleUrl)
         ? `<p>完整图文版：<a href="${escapeHtml(articleUrl)}" target="_blank" rel="noopener">${escapeHtml('本期完整文章')}</a></p>`
         : `<p>${escapeHtml('本期完整文章')}</p>`;
+    const styleBlock = style === 'omit' ? '' : `${TIMELINE_STYLE}\n`;
+    // `after` (default) keeps the style inside the markers but after the list, so content_text
+    // does not open on CSS. `before` is the pre-D9 position, for a byte-identical legacy render.
+    const before = style === 'before' ? styleBlock : '';
+    const after = style === 'after' ? styleBlock : '';
     return `<!--kk:timeline-->
-${TIMELINE_STYLE}
-<div class="kk-tl">${rows}
+${before}<div class="kk-tl">${rows}
 </div>
-${articleTail}
+${after}${articleTail}
 <!--/kk:timeline-->`;
 }
 
@@ -277,6 +289,22 @@ export interface ShowNotesRenderOptions {
      * matched monotonically against segment transcriptions; otherwise `--:--`.
      */
     audioSegments?: Array<{ duration?: number; transcription?: string }>;
+    /** R4. Omit to keep the default (summary on). `false` reproduces the pre-D9 body. */
+    summaryParagraph?: boolean;
+    /** R4. `after` moves `<style>` below the timeline; `before` is the legacy position; `omit` drops it. */
+    timelineStyle?: TimelineStyle;
+    seriesName?: string;
+    showName?: string;
+    descriptionMin?: number;
+    descriptionMax?: number;
+    descriptionSource?: PodcastSeoConfig['descriptionSource'];
+    descriptionPattern?: string;
+    /** Playback seconds for the `（约 N 分钟）` clause. Segment durations are the fallback. */
+    durationSeconds?: number;
+    /** Link text for the summary cross-link. Falls back to 本期完整文章. */
+    surfingTitle?: string;
+    refinedDescription?: string;
+    summaryClauses?: string[];
 }
 
 /** Per-item 1–2-sentence briefing: `metadata.brief` first, body sentences as fallback. */
@@ -298,7 +326,7 @@ function itemBrief(d: Doc): string {
  * a `[来源：<label>](<sourceUri>)` link per item, and the full-article footer.
  * Downstream HTML rendering stays with {@link renderShowNotesHtml}.
  */
-export function renderShowNotesMarkdown(docs: Doc[], opts: ShowNotesRenderOptions): string {
+export function renderShowNotesMarkdown(docs: Doc[], opts: ShowNotesRenderOptions, warnings?: string[]): string {
     const slugify = (t: string): string => {
         const s = t
             .toLowerCase()
@@ -323,6 +351,9 @@ export function renderShowNotesMarkdown(docs: Doc[], opts: ShowNotesRenderOption
         postSlug.length > 0
             ? `${baseUrl}${localePrefix}/posts/${postSlug}`
             : `${baseUrl}/zh/posts/${opts.runDate}-${slugify(opts.title)}`;
+    if (opts.briefMode === true && postSlug.length === 0) {
+        warn('brief mode requested but ARTICLE_POST_PATH is empty; using legacy layout', warnings);
+    }
     const briefMode = opts.briefMode === true && postSlug.length > 0;
     const sourceLabel = (d: Doc): string => {
         const m = d.metadata ?? {};
@@ -335,10 +366,44 @@ export function renderShowNotesMarkdown(docs: Doc[], opts: ShowNotesRenderOption
     };
     const offsets = computeAudioOffsets(docs, opts.audioSegments);
     const lines: string[] = [`# ${opts.title}`, ''];
+    const summaryOn = opts.summaryParagraph !== false;
+    if (summaryOn) {
+        const segmentSeconds = opts.audioSegments?.reduce((sum, segment) => sum + (segment.duration ?? 0), 0);
+        const durationSeconds =
+            opts.durationSeconds ?? (segmentSeconds && segmentSeconds > 0 ? segmentSeconds : undefined);
+        const plan: PlanItem[] = docs.map((doc) => {
+            const title = doc.title?.trim() ?? '';
+            const brief = itemBrief(doc);
+            return brief.length > 0 ? { title, brief } : { title };
+        });
+        const config: PodcastSeoConfig = {
+            ...SEO_DEFAULTS,
+            ...(opts.seriesName ? { seriesName: opts.seriesName } : {}),
+            ...(opts.showName ? { showName: opts.showName } : {}),
+            ...(opts.descriptionMin !== undefined ? { descriptionMin: opts.descriptionMin } : {}),
+            ...(opts.descriptionMax !== undefined ? { descriptionMax: opts.descriptionMax } : {}),
+            ...(opts.descriptionSource ? { descriptionSource: opts.descriptionSource } : {}),
+            ...(opts.descriptionPattern ? { descriptionPattern: opts.descriptionPattern } : {}),
+            summaryParagraph: true,
+            timelineStyle: opts.timelineStyle ?? 'after',
+        };
+        const summary = showNotesSummaryParagraph({
+            config,
+            runDate: opts.runDate,
+            ...(durationSeconds !== undefined ? { durationSeconds } : {}),
+            plan,
+            ...(opts.refinedDescription ? { refinedDescription: opts.refinedDescription } : {}),
+            ...(opts.summaryClauses ? { summaryClauses: opts.summaryClauses } : {}),
+            articleUrl,
+            linkText: opts.surfingTitle?.trim() || '本期完整文章',
+        });
+        for (const line of summary.warnings) warn(line.replace(/^WARN podcast-pub:\s*/, ''), warnings);
+        lines.push(summary.markdown, '');
+    }
     if (briefMode) {
         // Timeline layout (2026-09-16 feedback): real audio offsets left, title + briefing
         // right, article link last — the whole brief body is one pre-built HTML block.
-        lines.push(renderTimelineHtml(docs, offsets, articleUrl), '');
+        lines.push(renderTimelineHtml(docs, offsets, articleUrl, opts.timelineStyle ?? 'after'), '');
     } else {
         docs.forEach((d, i) => {
             const body = (d.body ?? '').trim();

package/plugins/publishings/surfdash-pub/dist/index.js

@@ -12473,15 +12473,12 @@ function mapContentToSurfingMarkdown(content, options = {}) {
     ...new Set(rawTags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => normalizeTag(t)))
   ].filter((tag) => tag.length > 0);
   const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
-  const firstRefUrl = content.references?.[0]?.url;
-  const canonical = typeof firstRefUrl === "string" ? firstRefUrl : typeof content.metadata?.canonicalUrl === "string" ? content.metadata.canonicalUrl : undefined;
   const draft = typeof content.metadata?.published === "boolean" ? !content.metadata.published : false;
   const frontmatterObj = {
     title,
     description: description ?? "",
     tags,
     publishDate: isoDate,
-    ...canonical ? { canonical } : {},
     draft,
     ...options.image ? { image: options.image, og_image: options.image } : {}
   };
@@ -12568,6 +12565,35 @@ function cliErrorText(spawned) {
 function withEmdashTokenHint(errText) {
   return /INVALID_TOKEN|API error 401/.test(errText) ? `${errText} \u2014 hint: regenerate the EmDash token (surfing.salty.vip admin console) and update EMDASH_API_TOKEN in ~/.config/kk/config.yaml` : errText;
 }
+function readRefinedSnapshot(filePath) {
+  if (!existsSync2(filePath))
+    return;
+  const raw = readFileSync2(filePath, "utf-8");
+  const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const fm = block?.[1] ?? "";
+  if (!fm || !/^refined:\s*true$/m.test(fm))
+    return;
+  const read = (key) => {
+    const m = fm.match(new RegExp(`^${key}:\\s*(?:>-?
+((?:[ \\t]+.*
+?)+)|(.*))$`, "m"));
+    if (!m)
+      return;
+    const value = (m[1] ?? m[2] ?? "").replace(/\n[ \t]+/g, " ").trim();
+    return value.replace(/^["']|["']$/g, "") || undefined;
+  };
+  return {
+    title: read("title"),
+    seoTitle: read("seo_title"),
+    description: read("description"),
+    canonical: read("canonical")
+  };
+}
+function requireRefined(filePath) {
+  if (readRefinedSnapshot(filePath))
+    return;
+  return `surfdash refine step did not run for ${filePath} (no \`refined: true\`): the publishing pipeline is broken \u2014 the post would ship with generator-supplied SEO metadata`;
+}
 async function pushPostGit(surfdashRoot, relPostDir, message) {
   return commitPostPaths(surfdashRoot, [relPostDir], message);
 }
@@ -12584,12 +12610,40 @@ async function assertMainBranch(surfdashRoot) {
   }
   return { ok: true };
 }
+async function fastForwardToOrigin(surfdashRoot) {
+  const fetched = await spawnCli(["git", "fetch", "--quiet", "origin", "main"], surfdashRoot);
+  if (fetched.exitCode !== 0)
+    return { ok: true };
+  const counts = await spawnCli(["git", "rev-list", "--left-right", "--count", "origin/main...HEAD"], surfdashRoot);
+  if (counts.exitCode !== 0)
+    return { ok: true };
+  const [behindRaw = "0", aheadRaw = "0"] = counts.stdout.trim().split(/\s+/);
+  const behind = Number(behindRaw);
+  const ahead = Number(aheadRaw);
+  if (!Number.isFinite(behind) || !Number.isFinite(ahead) || behind === 0)
+    return { ok: true };
+  if (ahead > 0) {
+    return {
+      ok: false,
+      error: `surfdash checkout diverged from origin/main (${ahead} local, ${behind} remote commit(s)): reconcile it by hand before publishing`
+    };
+  }
+  const merged = await spawnCli(["git", "merge", "--ff-only", "--quiet", "origin/main"], surfdashRoot);
+  if (merged.exitCode !== 0) {
+    return { ok: false, error: `surfdash fast-forward to origin/main failed: ${cliErrorText(merged)}` };
+  }
+  echoError(`surfdash: fast-forwarded ${behind} commit(s) to origin/main before writing`);
+  return { ok: true };
+}
 async function commitPostPaths(surfdashRoot, relPaths, message, push = true) {
   if (relPaths.length === 0)
     return { ok: true, hash: "unchanged" };
   const branch = await assertMainBranch(surfdashRoot);
   if (!branch.ok)
     return branch;
+  const base = await fastForwardToOrigin(surfdashRoot);
+  if (!base.ok)
+    return base;
   const add = await spawnCli(["git", "add", "--", ...relPaths], surfdashRoot);
   if (add.exitCode !== 0)
     return { ok: false, error: `surfdash git add failed: ${cliErrorText(add)}` };
@@ -12843,6 +12897,10 @@ async function publishPost(payload) {
     if (spawned.exitCode !== 0) {
       return fail(`postsurfing CLI failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`);
     }
+    const notRefined = requireRefined(filePath);
+    if (notRefined)
+      return fail(notRefined);
+    const refined = readRefinedSnapshot(filePath);
     const baseUrl = (process.env.SURFDASH_URL ?? "https://surfing.salty.vip").replace(/\/$/, "");
     const articleUrl = `${baseUrl}${locale === "en" ? "" : `/${locale}`}/posts/${slug}`;
     if (process.env.SURFDASH_AUTO_PUSH === "0") {
@@ -12851,7 +12909,7 @@ async function publishPost(payload) {
         target: TARGET,
         url: articleUrl,
         message: "Published via postsurfing CLI (auto-push disabled)",
-        metadata: { postPath: filePath }
+        metadata: { postPath: filePath, refinedTitle: refined?.title, refinedCanonical: refined?.canonical }
       });
     }
     const relPostDir = join2("content", "posts", "articles", locale, slug);
@@ -12864,7 +12922,7 @@ async function publishPost(payload) {
       target: TARGET,
       url: articleUrl,
       message: live ? "Published, committed, pushed, and live on the site" : "Published and pushed; URL not live within the verify window \u2014 check the surfdash deploy workflow",
-      metadata: { postPath: filePath, gitCommit: pushed.hash, live }
+      metadata: { postPath: filePath, gitCommit: pushed.hash, live, refinedTitle: refined?.title }
     });
   } catch (err) {
     return fail(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);
@@ -12944,6 +13002,7 @@ export {
   PostsurfingFileCliTransport,
   awaitArticleLive,
   commitPostPaths,
+  fastForwardToOrigin,
   getPublishTransport,
   main2 as main,
   mapContentToSurfingMarkdown,
@@ -12951,6 +13010,8 @@ export {
   normalizeTag,
   processPublishIO,
   pushPostGit,
+  readRefinedSnapshot,
+  requireRefined,
   slugify2 as slugify,
   withEmdashTokenHint
 };

package/plugins/publishings/surfdash-pub/src/index.ts

@@ -120,23 +120,22 @@ export function mapContentToSurfingMarkdown(content: Content, options: MapConten
     ].filter((tag) => tag.length > 0);
 
     const isoDate = options.publishDate ?? new Date().toISOString().slice(0, 10);
-    const firstRefUrl = content.references?.[0]?.url;
-    const canonical =
-        typeof firstRefUrl === 'string'
-            ? firstRefUrl
-            : typeof content.metadata?.canonicalUrl === 'string'
-              ? content.metadata.canonicalUrl
-              : undefined;
     const draft = typeof content.metadata?.published === 'boolean' ? !content.metadata.published : false;
 
     // Strict surfdash PostSchema (surfdash/src/content/schema.ts): publishDate (ISO date) is
     // required; unknown keys (`date`, `canonical_url`, `published`) are rejected.
+    //
+    // `canonical` is deliberately NOT written here. The canonical URL is the site's own route
+    // for this slug, which only the site can compute (locale prefix + collection segment); the
+    // previous `references[0].url` fallback pointed the canonical at an unrelated *external*
+    // source and would have dropped the post out of the sitemap if surfdash's refine step had
+    // not overwritten it. See docs/00_ADR.md ADR-008: the generator supplies content, the site
+    // supplies identity.
     const frontmatterObj: Record<string, unknown> = {
         title,
         description: description ?? '',
         tags,
         publishDate: isoDate,
-        ...(canonical ? { canonical } : {}),
         draft,
         ...(options.image ? { image: options.image, og_image: options.image } : {}),
     };
@@ -273,6 +272,49 @@ export function withEmdashTokenHint(errText: string): string {
         : errText;
 }
 
+/**
+ * Post-conditions the site guarantees after its publishing pipeline ran.
+ *
+ * The publisher does not derive SEO metadata any more (ADR-008): surfdash's refine step owns
+ * `refined`, `seo_title`, `canonical` and the digest title/description. Verifying the marker
+ * here turns a silently-regressed site pipeline into a loud publisher failure instead of a post
+ * that ships with a date-only title — which is exactly how the 2026-10-21 regression went
+ * unnoticed.
+ */
+export interface RefinedSnapshot {
+    title?: string;
+    seoTitle?: string;
+    description?: string;
+    canonical?: string;
+}
+
+/** Reads the frontmatter scalar fields the site owns; undefined when refine never ran. */
+export function readRefinedSnapshot(filePath: string): RefinedSnapshot | undefined {
+    if (!existsSync(filePath)) return undefined;
+    const raw = readFileSync(filePath, 'utf-8');
+    const block = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const fm = block?.[1] ?? '';
+    if (!fm || !/^refined:\s*true$/m.test(fm)) return undefined;
+    const read = (key: string): string | undefined => {
+        const m = fm.match(new RegExp(`^${key}:\\s*(?:>-?\n((?:[ \\t]+.*\n?)+)|(.*))$`, 'm'));
+        if (!m) return undefined;
+        const value = (m[1] ?? m[2] ?? '').replace(/\n[ \t]+/g, ' ').trim();
+        return value.replace(/^["']|["']$/g, '') || undefined;
+    };
+    return {
+        title: read('title'),
+        seoTitle: read('seo_title'),
+        description: read('description'),
+        canonical: read('canonical'),
+    };
+}
+
+/** Error text when the site pipeline did not mark the post refined, else undefined. */
+export function requireRefined(filePath: string): string | undefined {
+    if (readRefinedSnapshot(filePath)) return undefined;
+    return `surfdash refine step did not run for ${filePath} (no \`refined: true\`): the publishing pipeline is broken — the post would ship with generator-supplied SEO metadata`;
+}
+
 /** Outcome of {@link pushPostGit} — the union keeps fail-loud errors typed at the call site. */
 export type GitPushOutcome = { ok: true; hash: string } | { ok: false; error: string };
 
@@ -300,6 +342,41 @@ async function assertMainBranch(surfdashRoot: string): Promise<{ ok: true } | {
     return { ok: true };
 }
 
+/**
+ * Fast-forward the checkout onto `origin/main` before anything is written (2026-10-22).
+ *
+ * Three consecutive publish days failed with `! [rejected] main -> main (fetch first)`: this
+ * checkout sat behind a remote another machine had pushed to, so the publish commit landed on a
+ * stale base and the push was rejected — after the article had already been written and committed,
+ * and after the podcast episode had already published, so the run closed `partial`/`failed` while a
+ * real episode was live. A fast-forward is lossless (HEAD moves only when local carries no commit of
+ * its own), which is exactly the case here; a DIVERGED checkout is the operator's call and fails
+ * loud with both counts. An unreachable remote is not fatal: the fetch error is swallowed so the
+ * push below reports the real reason.
+ */
+export async function fastForwardToOrigin(surfdashRoot: string): Promise<{ ok: true } | { ok: false; error: string }> {
+    const fetched = await spawnCli(['git', 'fetch', '--quiet', 'origin', 'main'], surfdashRoot);
+    if (fetched.exitCode !== 0) return { ok: true };
+    const counts = await spawnCli(['git', 'rev-list', '--left-right', '--count', 'origin/main...HEAD'], surfdashRoot);
+    if (counts.exitCode !== 0) return { ok: true };
+    const [behindRaw = '0', aheadRaw = '0'] = counts.stdout.trim().split(/\s+/);
+    const behind = Number(behindRaw);
+    const ahead = Number(aheadRaw);
+    if (!Number.isFinite(behind) || !Number.isFinite(ahead) || behind === 0) return { ok: true };
+    if (ahead > 0) {
+        return {
+            ok: false,
+            error: `surfdash checkout diverged from origin/main (${ahead} local, ${behind} remote commit(s)): reconcile it by hand before publishing`,
+        };
+    }
+    const merged = await spawnCli(['git', 'merge', '--ff-only', '--quiet', 'origin/main'], surfdashRoot);
+    if (merged.exitCode !== 0) {
+        return { ok: false, error: `surfdash fast-forward to origin/main failed: ${cliErrorText(merged)}` };
+    }
+    echoError(`surfdash: fast-forwarded ${behind} commit(s) to origin/main before writing`);
+    return { ok: true };
+}
+
 /**
  * Commits several paths of the surfdash checkout and pushes them to `main` — the plural form of
  * {@link pushPostGit} the post-patch needs (it writes the posts and any copied cover). Same
@@ -315,6 +392,8 @@ export async function commitPostPaths(
     if (relPaths.length === 0) return { ok: true, hash: 'unchanged' };
     const branch = await assertMainBranch(surfdashRoot);
     if (!branch.ok) return branch;
+    const base = await fastForwardToOrigin(surfdashRoot);
+    if (!base.ok) return base;
     const add = await spawnCli(['git', 'add', '--', ...relPaths], surfdashRoot);
     if (add.exitCode !== 0) return { ok: false, error: `surfdash git add failed: ${cliErrorText(add)}` };
     const staged = await spawnCli(['git', 'diff', '--cached', '--quiet', '--', ...relPaths], surfdashRoot);
@@ -653,6 +732,11 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
             );
         }
 
+        // Contract check (ADR-008): the site, not this plugin, owns SEO metadata.
+        const notRefined = requireRefined(filePath);
+        if (notRefined) return fail(notRefined);
+        const refined = readRefinedSnapshot(filePath);
+
         // Deploy seam: commit + push the post so deploy.yml builds it, then wait for
         // the live URL — downstream show-notes advertise a real page, not a 404.
         // Tests (and offline runs) opt out via SURFDASH_AUTO_PUSH=0.
@@ -669,7 +753,7 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
                 message: 'Published via postsurfing CLI (auto-push disabled)',
                 // Absolute post path lets downstream steps (locale translation + CMS sync)
                 // derive the surfdash checkout root without extra configuration.
-                metadata: { postPath: filePath },
+                metadata: { postPath: filePath, refinedTitle: refined?.title, refinedCanonical: refined?.canonical },
             });
         }
         const relPostDir = join('content', 'posts', 'articles', locale, slug);
@@ -684,7 +768,7 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
             message: live
                 ? 'Published, committed, pushed, and live on the site'
                 : 'Published and pushed; URL not live within the verify window — check the surfdash deploy workflow',
-            metadata: { postPath: filePath, gitCommit: pushed.hash, live },
+            metadata: { postPath: filePath, gitCommit: pushed.hash, live, refinedTitle: refined?.title },
         });
     } catch (err: unknown) {
         return fail(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);