@gobing-ai/knowledge-kit 0.0.11 → 0.0.12

package/plugins/generations/content-gen/src/storm.ts

@@ -1,4 +1,5 @@
 import { type Content, ContentSchema, type Doc } from '@gobing-ai/kk-core';
+import { echoError } from '@gobing-ai/ts-utils';
 import { z } from 'zod';
 import { parseAgentJson } from './agent-json';
 
@@ -21,60 +22,97 @@ export interface StormStageRunner {
     runStage(prompt: string): Promise<AgentRunEnvelope>;
 }
 
-/** Concrete runner invoking the existing `spur agent run` boundary (same call shape as the D2 stand-in). */
-export const spurStageRunner: StormStageRunner = {
-    async runStage(prompt: string): Promise<AgentRunEnvelope> {
-        const proc = Bun.spawn(
-            [
-                process.env.KNOWLEDGE_KIT_SPUR_BIN ?? 'spur',
-                'agent',
-                'run',
-                prompt,
-                '--agent',
-                'auto',
-                '--mode',
-                'text',
-                '--json',
-                '--cwd',
-                process.cwd(),
-            ],
-            { stdout: 'pipe', stderr: 'pipe' },
-        );
-        const [exitCode, stdout, stderr] = await Promise.all([
-            proc.exited,
-            new Response(proc.stdout).text(),
-            new Response(proc.stderr).text(),
-        ]);
-        if (exitCode !== 0) {
-            // CLI-level failure (spawn/argv): no envelope to unwrap; stages prefix the diagnostic.
-            return { exitCode, stdout, stderr };
+interface SpawnOutcome {
+    kind: 'ok' | 'crash' | 'malformed';
+    envelope: AgentRunEnvelope;
+}
+
+/** One `spur agent run` invocation + envelope unwrap. */
+async function spawnAgentOnce(prompt: string): Promise<SpawnOutcome> {
+    const proc = Bun.spawn(
+        [
+            process.env.KNOWLEDGE_KIT_SPUR_BIN ?? 'spur',
+            'agent',
+            'run',
+            prompt,
+            '--agent',
+            'auto',
+            '--mode',
+            'text',
+            '--json',
+            '--cwd',
+            // Anchor the agent's cwd to the project root (set by the executor, whose own
+            // cwd is the invocation root). process.cwd() here is the plugin package dir —
+            // using it makes spur auto-init a stray `.spur/` and drops agent files there.
+            process.env.KNOWLEDGE_KIT_PROJECT_ROOT ?? process.cwd(),
+        ],
+        { stdout: 'pipe', stderr: 'pipe' },
+    );
+    const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+    ]);
+    if (exitCode !== 0) {
+        // CLI-level failure (spawn/argv): no envelope to unwrap; stages prefix the diagnostic.
+        return { kind: 'crash', envelope: { exitCode, stdout, stderr } };
+    }
+    // The CLI writes the agent envelope {exitCode, stdout, stderr, durationMs} to stdout.
+    // Unwrap it so stages consume the agent output.
+    try {
+        const parsed = JSON.parse(stdout) as Partial<AgentRunEnvelope>;
+        if (
+            typeof parsed.exitCode !== 'number' ||
+            typeof parsed.stdout !== 'string' ||
+            typeof parsed.stderr !== 'string'
+        ) {
+            throw new Error('expected envelope {exitCode:number, stdout:string, stderr:string}');
         }
-        // The CLI writes the agent envelope {exitCode, stdout, stderr, durationMs} to stdout.
-        // Unwrap it so stages consume the agent output.
-        let envelope: AgentRunEnvelope;
-        try {
-            const parsed = JSON.parse(stdout) as Partial<AgentRunEnvelope>;
-            if (
-                typeof parsed.exitCode !== 'number' ||
-                typeof parsed.stdout !== 'string' ||
-                typeof parsed.stderr !== 'string'
-            ) {
-                throw new Error('expected envelope {exitCode:number, stdout:string, stderr:string}');
-            }
-            envelope = parsed as AgentRunEnvelope;
-        } catch (error) {
-            // Exit-0 but non-envelope stdout: return a runner-level diagnostic so the calling
-            // stage prefixes it ({Stage} stage failed: …) instead of leaking a raw SyntaxError.
-            return {
+        const envelope = parsed as AgentRunEnvelope;
+        return { kind: envelope.exitCode === 0 ? 'ok' : 'crash', envelope };
+    } catch (error) {
+        // Exit-0 but non-envelope stdout: deterministic contract failure — never retried.
+        return {
+            kind: 'malformed',
+            envelope: {
                 exitCode: 1,
                 stdout: '',
                 stderr: `spur agent run returned malformed output: ${error instanceof Error ? error.message : String(error)}`,
-            };
+            },
+        };
+    }
+}
+
+/** Concrete runner invoking the existing `spur agent run` boundary (same call shape as the D2 stand-in). */
+export const spurStageRunner: StormStageRunner = {
+    async runStage(prompt: string): Promise<AgentRunEnvelope> {
+        // A crashed agent subprocess (e.g. polish stage exit 1, dogfood daily-ai-news-20260903)
+        // must not kill a 90-minute pipeline run — retry once. Malformed envelopes are a
+        // deterministic contract failure and are not retried.
+        let last: AgentRunEnvelope = { exitCode: 1, stdout: '', stderr: 'no attempt executed' };
+        for (let attempt = 1; attempt <= 2; attempt++) {
+            const outcome = await spawnAgentOnce(prompt);
+            if (outcome.kind !== 'crash') return outcome.envelope;
+            last = outcome.envelope;
+            if (attempt === 1) {
+                echoError(
+                    `spurStageRunner: agent run exited ${last.exitCode}; retrying once (${last.stderr.trim().slice(0, 200)})`,
+                );
+            }
         }
-        return { exitCode: envelope.exitCode, stdout: envelope.stdout, stderr: envelope.stderr };
+        return last;
     },
 };
 
+/** Language directive appended to outline/article/polish prompts when CONTENT_LANGUAGE is set. */
+function languageDirective(): string {
+    const lang = process.env.CONTENT_LANGUAGE?.trim();
+    if (!lang) return '';
+    return lang === 'zh'
+        ? 'Write everything in Simplified Chinese (简体中文), including the title and all section headings.'
+        : `Write everything in ${lang}, including the title and all section headings.`;
+}
+
 const PerspectiveSchema = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
@@ -166,7 +204,9 @@ export async function curationStage(runner: StormStageRunner, docs: Doc[], input
         [
             'Develop multiple distinct perspectives (personas or angles) on the source material. For each perspective, list the questions it would ask and cite the supplied document IDs that ground it.',
             'Return only a JSON object matching {"perspectives":[{"id":string,"name":string,"questions":[string],"evidence":[string]}]} where every evidence entry is one of the allowed document IDs.',
-        ].join('\n'),
+        ]
+            .filter(Boolean)
+            .join('\n'),
     );
     const envelope = await runner.runStage(prompt);
     if (envelope.exitCode !== 0) {
@@ -204,8 +244,11 @@ export async function outlineStage(
         [
             `The validated curation result for the article is: ${JSON.stringify(curation)}`,
             'Produce a structured markdown outline for the article derived from that curation result.',
+            languageDirective(),
             'Return only a JSON object matching {"title":string,"outline":string,"references":[string]} where outline is markdown and every references entry is one of the allowed document IDs.',
-        ].join('\n'),
+        ]
+            .filter(Boolean)
+            .join('\n'),
     );
     const envelope = await runner.runStage(prompt);
     if (envelope.exitCode !== 0) {
@@ -242,9 +285,12 @@ export async function articleStage(
             `The validated curation result for the article is: ${JSON.stringify(curation)}`,
             `The validated outline for the article is: ${JSON.stringify(outline)}`,
             'Write the complete article as markdown, one section per outline heading. Every citation must reference one of the allowed document IDs.',
+            languageDirective(),
             'Synthesize: the body must draw findings from across the supplied documents, compare them, and state conclusions. Never list sources one per line or produce an index of references — references are evidence, not the deliverable.',
             'Return only a JSON object matching {"title":string,"body":string,"citations":[string]} where body is the full markdown draft and every citations entry is one of the allowed document IDs.',
-        ].join('\n'),
+        ]
+            .filter(Boolean)
+            .join('\n'),
     );
     const envelope = await runner.runStage(prompt);
     if (envelope.exitCode !== 0) {
@@ -278,8 +324,11 @@ export async function polishStage(
         [
             `The drafted article is: ${JSON.stringify(article)}`,
             'Polish the draft: preserve every heading and citation exactly, remove repetition, and tighten the prose. Do not cite any document outside the allowed IDs.',
+            languageDirective(),
             'Return only a JSON object matching {"title":string,"body":string,"outline":string} where body is the polished markdown (headings and citations preserved) and outline is a markdown outline of the final article.',
-        ].join('\n'),
+        ]
+            .filter(Boolean)
+            .join('\n'),
     );
     const envelope = await runner.runStage(prompt);
     if (envelope.exitCode !== 0) {

package/plugins/generations/core-facts-gen/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/core-facts-gen",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/generations/core-facts-gen/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "core-facts-gen",
+    "kind": "generator",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Renders a merged Doc[] into one dated core-facts markdown Content (mechanical, no LLM) per docs/design/core-facts-template.md"
+}

package/plugins/generations/core-facts-gen/src/index.ts

@@ -0,0 +1,116 @@
+import { basename, dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+
+/**
+ * core-facts-gen (task 0090 contract, docs/design/core-facts-template.md):
+ * render a merged `Doc[]` (from `kk executor fan-in`) into one dated core-facts
+ * markdown `Content`. Mechanical template fill — no LLM.
+ *
+ * Run date: `CORE_FACTS_DATE` env var, else today (UTC).
+ */
+
+/** Narrow a metadata.sources[] entry to its `file` string (provenance shape written by fan-in). */
+function sourceFileOf(entry: unknown): string | null {
+    if (entry && typeof entry === 'object' && 'file' in entry) {
+        const file = entry.file;
+        return typeof file === 'string' ? file : null;
+    }
+    return null;
+}
+
+/** Render the facts markdown for a merged Doc[] (pure — exported for tests). */
+export function renderCoreFacts(docs: Doc[], date: string): string {
+    const sources = new Set<string>();
+    for (const doc of docs) {
+        const entries = doc.metadata?.sources;
+        if (Array.isArray(entries)) {
+            for (const entry of entries) {
+                const file = sourceFileOf(entry);
+                if (file) sources.add(file);
+            }
+        }
+    }
+    const roster = [...sources].map((file) => `  - ${basename(file)} (${file})`).join('\n');
+
+    const labelOf = (d: Doc): string => {
+        const source = d.metadata?.source;
+        if (typeof source === 'string' && source) return source;
+        const entries = d.metadata?.sources;
+        if (Array.isArray(entries)) {
+            const file = entries.length > 0 ? sourceFileOf(entries[0]) : null;
+            if (file) return basename(file);
+        }
+        return '';
+    };
+    const scoreOf = (d: Doc): unknown => d.metadata?.score ?? d.metadata?.relevance_score ?? '';
+    const dateOf = (d: Doc): string => {
+        const published = d.metadata?.published_at;
+        return typeof published === 'string' ? published : '';
+    };
+    const headlines = docs
+        .map(
+            (d) =>
+                `### ${d.title ?? ''}\n` +
+                `**Source:** ${labelOf(d)} · **URI:** ${d.sourceUri ?? ''} · **ID:** \`${d.id}\`\n` +
+                `**Date:** ${dateOf(d)} · **Score:** ${String(scoreOf(d))}\n` +
+                `${d.body}`,
+        )
+        .join('\n\n');
+
+    return (
+        `---\ndate: ${date}\nsources:\n${roster}\ndedup_rule: id\ndoc_count: ${docs.length}\n---\n\n` +
+        `# Core Facts — ${date}\n\n` +
+        '> Daily AI news core-facts digest. Merge: `kk executor fan-in` (id dedupe, first-seen wins).\n' +
+        '> Render: core-facts-gen generator (mechanical; no LLM).\n\n' +
+        `## Headlines\n\n${headlines}\n`
+    );
+}
+
+export function docsToContent(docs: Doc[], date: string): Content {
+    return ContentSchema.parse({
+        title: `Core Facts — ${date}`,
+        body: renderCoreFacts(docs, date),
+        format: 'markdown',
+        references: docs.filter((d) => d.sourceUri).map((d) => ({ url: d.sourceUri, title: d.title, cite: d.id })),
+        metadata: { generator: 'kk:core-facts', date, doc_count: docs.length },
+    });
+}
+
+export async function processGeneratorIO(inputPath: string, outputPath: string): Promise<Content> {
+    const docs = DocListSchema.parse(await readJsonFile(inputPath));
+    const date = process.env.CORE_FACTS_DATE ?? new Date().toISOString().slice(0, 10);
+    const content = docsToContent(docs, date);
+    const fs = createNodeFileSystem();
+    const outDir = dirname(outputPath);
+    if (outDir && outDir !== '.') await fs.ensureDir(outDir);
+    await atomicWriteJson(outputPath, content, fs);
+    return content;
+}
+
+export async function main(): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (err: unknown) {
+        echoError(`core-facts-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('core-facts-gen failed: Missing required arguments: --in <docs.json> --out <content.json>');
+        return 1;
+    }
+    try {
+        await processGeneratorIO(values.in, values.out);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`core-facts-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/generations/core-facts-gen/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/generations/daily-article-gen/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/daily-article-gen",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/generations/daily-article-gen/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "daily-article-gen",
+    "kind": "generator",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Renders a merged Doc[] into a readable daily AI-news article with per-item source links (mechanical template, no LLM) — replaces the heavy STORM flow"
+}

package/plugins/generations/daily-article-gen/src/index.ts

@@ -0,0 +1,91 @@
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Content, ContentSchema, type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+
+/**
+ * daily-article-gen: render a merged `Doc[]` into one readable daily AI-news
+ * article. Mechanical template fill — no LLM, no STORM. Every news item keeps
+ * a human-clickable source link (`[来源](sourceUri)`) so readers can trace
+ * claims to their origin.
+ *
+ * Run date: `ARTICLE_DATE` env var (YYYYMMDD or ISO), else today (UTC).
+ * Language-neutral: the Doc bodies already carry the summary language.
+ */
+
+/** Pretty source label for an item line. */
+function sourceLabelOf(doc: Doc): string {
+    const meta = doc.metadata as Record<string, unknown> | undefined;
+    const name = meta?.sourceName;
+    if (typeof name === 'string' && name.trim().length > 0) return name.trim();
+    try {
+        return new URL(doc.sourceUri ?? '').hostname.replace(/^www\./, '');
+    } catch {
+        return '来源';
+    }
+}
+
+/** Render one news item section: heading, source link, and summary body. */
+function renderDoc(doc: Doc, index: number): string {
+    const heading = doc.title?.trim() || `新闻 ${index + 1}`;
+    const link = doc.sourceUri ? `[来源：${sourceLabelOf(doc)}](${doc.sourceUri})` : '';
+    const meta = doc.metadata as Record<string, unknown> | undefined;
+    const publishedAt = typeof meta?.publishedAt === 'string' ? meta.publishedAt.slice(0, 10) : '';
+    const metaLine = [link, publishedAt].filter(Boolean).join(' · ');
+    return `## ${index + 1}. ${heading}\n\n${metaLine ? `${metaLine}\n\n` : ''}${(doc.body ?? '').trim()}`;
+}
+
+/** Render the article markdown for a merged Doc[] (pure — exported for tests). */
+export function renderDailyArticle(docs: Doc[], date: string): string {
+    const items = docs.map(renderDoc).join('\n\n');
+    return `# 每日 AI 资讯 — ${date}\n\n本期共 ${docs.length} 条新闻，均附可点击来源链接。\n\n${items}\n`;
+}
+
+/** Build the article Content from a merged Doc[]. */
+export function docsToContent(docs: Doc[], date: string): Content {
+    return ContentSchema.parse({
+        title: `每日 AI 资讯 — ${date}`,
+        body: renderDailyArticle(docs, date),
+        format: 'markdown',
+        references: docs.filter((d) => d.sourceUri).map((d) => ({ url: d.sourceUri, title: d.title, cite: d.id })),
+        metadata: { generator: 'kk:daily-article', date, doc_count: docs.length },
+    });
+}
+
+export async function processGeneratorIO(inputPath: string, outputPath: string): Promise<Content> {
+    const docs = DocListSchema.parse(await readJsonFile(inputPath));
+    const raw = process.env.ARTICLE_DATE ?? new Date().toISOString().slice(0, 10);
+    const date = raw.length === 8 ? `${raw.slice(0, 4)}-${raw.slice(4, 6)}-${raw.slice(6, 8)}` : raw;
+    const content = docsToContent(docs, date);
+    const fs = createNodeFileSystem();
+    const outDir = dirname(outputPath);
+    if (outDir && outDir !== '.') await fs.ensureDir(outDir);
+    await atomicWriteJson(outputPath, content, fs);
+    return content;
+}
+
+export async function main(): Promise<number> {
+    let values: { in?: string; out?: string };
+    try {
+        ({ values } = parseArgs({ options: { in: { type: 'string' }, out: { type: 'string' } } }));
+    } catch (err: unknown) {
+        echoError(`daily-article-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!values.in || !values.out) {
+        echoError('daily-article-gen failed: Missing required arguments: --in <docs.json> --out <content.json>');
+        return 1;
+    }
+    try {
+        await processGeneratorIO(values.in, values.out);
+        return 0;
+    } catch (err: unknown) {
+        echoError(`daily-article-gen failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/generations/daily-article-gen/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/generations/dailynews-gen/src/index.ts

@@ -27,6 +27,17 @@ export async function processGeneratorIO(
         throw new Error(`Invalid DocList input: ${err instanceof Error ? err.message : String(err)}`);
     }
 
+    // Optional story cap (daily pipeline: the blend carries 50+ docs; a broadcast needs a bound).
+    // Input order is curated-first (fan-in first-seen), so a head-cap keeps the best items.
+    const maxItemsEnv = process.env.DAILYNEWS_MAX_ITEMS;
+    if (maxItemsEnv) {
+        const maxItems = Number.parseInt(maxItemsEnv, 10);
+        if (Number.isInteger(maxItems) && maxItems > 0 && docs.length > maxItems) {
+            echoError(`dailynews-gen: capping ${docs.length} docs to ${maxItems} (DAILYNEWS_MAX_ITEMS)`);
+            docs = docs.slice(0, maxItems);
+        }
+    }
+
     const script = buildNewsVoiceScript(docs, options);
     const yamlBody = formatVoiceScriptToYaml(script);
 

package/plugins/generations/dailynews-gen/src/script-builder.ts

@@ -269,7 +269,7 @@ export function buildNewsVoiceScript(docs: Doc[], options?: ScriptBuilderOptions
             ? idx === 0
                 ? `首先来聊聊大家非常关注的【${cleanTitle}】。`
                 : isLast
-                  ? `最后，来跟大家分享一条很有温度的幕后故事，【${cleanTitle}】。`
+                  ? `最后，来看看今天的最后一条资讯，【${cleanTitle}】。`
                   : `接着我们把目光转向另一条重要进展，【${cleanTitle}】。`
             : idx === 0
               ? `First up today, let's look at ${cleanTitle}.`

package/plugins/generations/episode-plan-gen/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/episode-plan-gen",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}

package/plugins/generations/episode-plan-gen/plugin.json

@@ -0,0 +1,7 @@
+{
+    "name": "episode-plan-gen",
+    "kind": "generator",
+    "entry": "./src/index.ts",
+    "version": "1.0.0",
+    "description": "Plans the daily episode: scores blended Doc[] (source weight + normalized relevance + log-scaled engagement), dedups by URL and title bigram, selects top N, flags English items, strips rating/heading leftovers (mechanical, no LLM)"
+}