@gobing-ai/knowledge-kit 0.0.37 → 0.1.0

package/plugins/kk/references/smart-seo-attribution.md

@@ -0,0 +1,85 @@
+# Smart SEO Attribution & Upstream Review Notice
+
+## Upstream Project and License
+
+Knowledge Kit Smart SEO (`kk-smart-seo`) adapts and grounds the methodology and rules from the upstream `jev-seo` project.
+
+- **Upstream Project:** `jev-seo` (version 0.1.1)
+- **Upstream Commit Snapshot:** `55a184a3b0d09565a4c84268f725a47784e62528`
+- **Upstream Author:** Agrici Daniel
+- **License:** MIT License
+
+```text
+MIT License
+
+Copyright (c) 2026 Agrici Daniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## Architectural & SECUA Audit Linkage
+
+The upstream vendor snapshot was fully reviewed in `docs/plans/2026-10-14-smart-seo-vendor-review.md`.
+
+Key architectural and security adaptations include:
+1. **Network Trust Boundary (V01, V02):** Replaced unpinned ambient requests with connection-pinned public HTTP(S) transport, DNS resolution validation against private/reserved/multicast ranges, peer address verification, and scoped redirect validation. No browser or Chromium runtime path is imported.
+2. **Resource Boundaries (V03, V04):** Streamed response limit of 2 MiB per response, 40 MiB crawl total, shared request quotas (default 200, max 500) and shared deadline (default 600s, max 1800s).
+3. **Robots & Sitemap Integrity (V04, V05, V06):** Robots.txt fetched first and respects full `Crawl-delay` or marks budget exhaustion; distinguishes absent (404/410), blocked (401/403), and unavailable (429/5xx). Strictly bounded non-expanding XML subset reader rejecting DOCTYPE/entities/compression.
+4. **Distinct URL & Identity Preservation (V06):** Preserves pathname, query parameters, and trailing slashes (`/a` and `/a/` remain distinct resources); fragments stripped.
+5. **Clean Runtime Seam:** Knowledge Kit Smart SEO is implemented as native TypeScript stages on Bun 1.4.3 (`plugins/kk/scripts/seo-*.ts`), importing no vendor Python files or bundled font assets.
+
+## Rule Dispositions (52 Rules)
+
+All 52 deterministic rules from the vendor snapshot have explicit dispositions:
+- **Native (24 rules):** `redirect_chains`, `links_to_redirects`, `host_temporary_redirect`, `deep_pages`, `title_missing`, `title_duplicate`, `title_length`, `multiple_titles`, `meta_missing`, `meta_duplicate`, `h1_missing`, `h1_multiple`, `heading_skips`, `lang_missing`, `viewport_missing`, `thin_content`, `duplicate_content`, `images_alt`, `images_dimensions`, `jsonld_errors`, `og_missing`, `mixed_content`, `heavy_html`, `generic_anchors`.
+- **Adapted (15 rules):** `robots_blocks_site`, `sitemap_errors`, `sitemap_bad_urls`, `http_errors`, `broken_internal_links`, `noindex`, `canonical_elsewhere`, `canonical_broken`, `soft_404`, `host_variant`, `no_https`, `orphan_pages`, `faq_rich_result_limited`, `hreflang_issues`, `slow_ttfb`.
+- **Informational (11 rules):** `robots_missing`, `sitemap_missing`, `not_in_sitemap`, `canonical_missing`, `js_dependent`, `no_structured_data`, `ai_bots_blocked`, `llms_txt_missing`, `hsts_missing`, `security_headers`, `favicon_missing`.
+- **Deferred (2 rules):** `schema_required`, `broken_external_links`.
+
+## Adapted Rubric & Source Attribution (task 0286)
+
+The `smart-seo` skill and its references restate **KK-authored** adaptations of the upstream
+methodology. They are not copies of vendor prose, and the following must stay explicit whenever the
+rubric is described or reused:
+
+1. **Decision catalogs** (`plugins/kk/decisions/kk-seo-{site,page,pair,keyword}.yaml`, 22 decisions)
+adapt the vendor's decision *descriptions and vocabularies* (business model, page type, search
+intent, page action, 0–3 editorial scores, noul questions). KK additions: an `unclear` choice in
+every choice vocabulary, `keep-or-improve|rewrite|review-consolidation|unclear` instead of
+automatic removal, `defaults.minConfidence: 0` so a served low-confidence observation is recorded
+rather than silently replaced, and 0–3 score levels with an explicit `uncertain → review` band in
+the consumer. The vendor's weighted overall grade and relative 100-point impact scale are
+**rejected** — this method publishes per-category pass ratios with their coverage denominators and
+no blended SEO/GEO grade.
+2. **Rule identities** (`plugins/kk/scripts/seo-rules.ts` `VENDOR_RULES`) retain the 52 upstream
+rule ids for traceability, each carrying `disposition` (`native|adapted|informational|deferred`),
+KK-chosen `severity`, an `effort` band 1–4, a `heuristic` flag and the primary source with the date
+it was checked. Neither severity nor effort is the vendor's.
+3. **Source registry**: rule rows cite the primary source itself — RFC 9309 for robots matching,
+Google Search Central (canonicalization, robots meta, sitemaps, AI optimization, common crawlers),
+OpenAI's crawler documentation, web.dev Web Vitals. The dated registry, the per-source limits and
+the refresh procedure are `plugins/kk/skills/smart-seo/references/seo-geo-sources.md`; the rubric,
+scoring and action-priority interpretation is
+`plugins/kk/skills/smart-seo/references/method.md`; the strict report-narrative contract is
+`plugins/kk/skills/smart-seo/references/narrative.md`.
+4. **Narrative rendering** uses KK-owned fixed templates over the audit artifact. Agents select and
+order recorded references and cannot introduce prose, measurements, diagnoses or predictions.
+5. **Vendor code, Python paths, browser/rendering stacks and bundled font assets are not shipped**;
+the audit is native Bun/TypeScript over the existing stage runner (ADR-018) and `vendors/` stays
+excluded from runtime and install resolution (ADR-036).

package/plugins/kk/scripts/daily-stages.ts

@@ -467,6 +467,38 @@ export function dailyCoverNormalize(args: string[]): void {
  * no-content with the measured vs estimated minutes recorded. Over-max still fails loud — trimming
  * is a different problem.
  */
+/**
+ * Advisory speaker-consistency audit of a finished episode.
+ *
+ * Exists because an unanchored voice profile (voxcpm's `instruct` mode pins no speaker) shipped 59
+ * different speakers in the 20261015 episode and nothing but a human listening caught it. This runs
+ * the plugin's F0 audit and reports; it NEVER fails the run — a regression, a missing venv or a
+ * broken script must not stop publishing. A non-zero audit exit prints one WARNING line instead.
+ */
+export function dailyVoiceAudit(args: string[]): void {
+    const [workDir = '', runDate = '', pluginsPath = ''] = args;
+    if (!workDir) fail('missing work_dir');
+    if (!runDate) fail('missing run_date');
+    const contentPath = join(workDir, '30-audio', `${runDate}_11_generate_content.json`);
+    if (!isFile(contentPath)) {
+        console.log(`voice-audit: no episode content at ${contentPath}; skipping`);
+        return;
+    }
+    const plugin = join(pluginsPath || 'plugins', 'generations', 'voxcpm-tts');
+    const python = join(plugin, '.venv', 'bin', 'python');
+    const script = join(plugin, 'scripts', 'audit-speaker-consistency.py');
+    if (!isFile(python) || !isFile(script)) {
+        console.log(`voice-audit: skipping (needs ${python} and ${script})`);
+        return;
+    }
+    const audit = spawnSync(python, [script, contentPath], { encoding: 'utf-8' });
+    const out = `${audit.stdout ?? ''}${audit.stderr ?? ''}`.trim();
+    if (out) console.log(out);
+    if (audit.status !== 0) {
+        console.log('voice-audit: WARNING — the speaker-consistency audit flagged this episode (advisory)');
+    }
+}
+
 export function dailyEpisodeDuration(args: string[]): void {
     const [workDir = '', runDate = '', minArg = '', maxArg = '', vdriver = ''] = args;
     if (!workDir) fail('missing work_dir');
@@ -1989,9 +2021,17 @@ function voicescriptToBlockYaml(script: Record<string, unknown>): string {
     return lines.join('\n');
 }
 
-/** Measured driver rates from dailyGenerate. Unknown drivers (incl. voxcpm, provisionally) use the voicebox rate. */
+/** Measured driver rates from dailyGenerate. Unknown drivers reuse the voicebox rate. */
 function spokenCharRate(vdriver: string): number {
-    return vdriver === 'gemini' ? 5.4 : 5.6;
+    // Recalibrated 2026-10-15: episode measured 7,395 spoken chars / 1,490.9 s across 12 sections
+    // (4.96 字/秒) — the effective gemini rate dropped ~8% below the 5.33-5.62 band calibrated
+    // 2026-10-04/07, which consumed the fit's 2-min margin and tripped the 25-min gate at 25.2 min.
+    if (vdriver === 'gemini') return 4.95;
+    // voxcpm measured the same day on a 12-section zh+en episode: 6,772 chars / 1,297.7 s speech
+    // (5.19 字/秒). The provisional 5.6 borrowed from voicebox let the fit budget reach 7,683 chars
+    // — 24.6 min of audio, 18 s inside the 25-min gate. 5.2 puts a full-budget script at ~22.9 min.
+    if (vdriver === 'voxcpm') return 5.2;
+    return 5.6;
 }
 
 /**

package/plugins/kk/scripts/itc-stages.ts

@@ -232,69 +232,9 @@ export function itcReport(args: string[]): void {
 }
 
 // ---------------------------------------------------------------------------
-// 0150: publish-tail seams — TARGET_PROFILES, itc-materialize, itc-publish-plan
+// 0150 / 0298: publish-tail seams — itc-materialize, itc-publish-plan
 // ---------------------------------------------------------------------------
 
-/** One row of the docs/design/kk-itc-end-to-end.md §5 target profile table. */
-export interface TargetProfile {
-    transport: 'fanout' | 'browser';
-    /** `source` = the draft's own source_locale; anything else is fixed. */
-    locale: 'en' | 'zh' | 'ja' | 'source';
-    format: string;
-    cover: boolean;
-    /**
-     * V3 draft/live switch itc-publish-fanout writes into the variant Content metadata at send
-     * time. Returning null means the target has no switch for this run's mode and is rejected by
-     * name: x-pub's `operation: post` has no draft mode; wechatmp-pub refuses every live operation.
-     */
-    switch: (live: boolean) => Record<string, unknown> | null;
-}
-
-// Draft/live key per row, verified against each plugin's src/ (0150 R3):
-//   medium-pub    metadata.publishStatus 'draft'|'public' (plugins/publishings/medium-pub/src/index.ts:49)
-//   emdash-pub    metadata.published (plugins/publishings/emdash-pub/src/index.ts:254)
-//   surfdash-pub  metadata.published (plugins/publishings/surfdash-pub/src/index.ts:93)
-//   zenn-pub      metadata.published — defaults to LIVE when absent, so never omit (plugins/publishings/zenn-pub/src/index.ts:92)
-//   qiita-pub     metadata.published, private is its inverse (plugins/publishings/qiita-pub/src/index.ts:70)
-//   wechatmp-pub  metadata.operation, draft default; live refused (plugins/publishings/wechatmp-pub/src/index.ts:162,171)
-//   x-pub         metadata.operation 'post' — no draft mode exists (plugins/publishings/x-pub/src/index.ts:64)
-//   substack/juejin/infoq/xhs always return a draft Result (plugins/publishings/substack-pub/src/index.ts:26);
-//   their live path is 0151's `kk:publish --live` agent flag, so the switch is documentation-only.
-const publishedSwitch = (live: boolean) => ({ published: live });
-const browserSwitch = (live: boolean): Record<string, unknown> => (live ? {} : { publishStatus: 'draft' });
-
-export const TARGET_PROFILES: Record<string, TargetProfile> = {
-    'medium-pub': {
-        transport: 'fanout',
-        locale: 'en',
-        format: 'article',
-        cover: false,
-        switch: (live) => ({ publishStatus: live ? 'public' : 'draft' }),
-    },
-    'substack-pub': { transport: 'browser', locale: 'en', format: 'article', cover: false, switch: browserSwitch },
-    'emdash-pub': { transport: 'fanout', locale: 'source', format: 'article', cover: false, switch: publishedSwitch },
-    'surfdash-pub': { transport: 'fanout', locale: 'source', format: 'article', cover: false, switch: publishedSwitch },
-    'zenn-pub': { transport: 'fanout', locale: 'ja', format: 'article', cover: false, switch: publishedSwitch },
-    'qiita-pub': { transport: 'fanout', locale: 'ja', format: 'article', cover: false, switch: publishedSwitch },
-    'wechatmp-pub': {
-        transport: 'fanout',
-        locale: 'zh',
-        format: 'wechat-article',
-        cover: true,
-        switch: (live) => (live ? null : { operation: 'draft' }),
-    },
-    'juejin-pub': { transport: 'browser', locale: 'zh', format: 'article', cover: false, switch: browserSwitch },
-    'infoq-pub': { transport: 'browser', locale: 'zh', format: 'article', cover: false, switch: browserSwitch },
-    'xhs-pub': { transport: 'browser', locale: 'zh', format: 'short-note', cover: true, switch: browserSwitch },
-    'x-pub': {
-        transport: 'fanout',
-        locale: 'en',
-        format: 'short-post',
-        cover: false,
-        switch: (live) => (live ? { operation: 'post' } : null),
-    },
-};
-
 const DRAFT_FILE = '3-draft-draft-article.md';
 
 /** First `cover.*` in 4-illustrations as a workspace-relative path, or undefined. */
@@ -383,65 +323,32 @@ export interface PublishPlan {
 }
 
 export function itcPublishPlan(args: string[]): void {
-    const [workDir = '', targetsArg = '', sourceLocale = '', liveArg = ''] = args;
-    if (!workDir || !targetsArg || !sourceLocale) {
-        fail('usage: itc-publish-plan <work_dir> <targets> <source_locale> <publish_live>');
+    if (process.env._KK_ITC_STAGE_NATIVE === '1') {
+        return;
     }
-    const live = liveArg === 'true';
-    const targets = [
-        ...new Set(
-            targetsArg
-                .split(',')
-                .map((t) => t.trim())
-                .filter(Boolean),
-        ),
-    ];
-    const hasCover = findCover(workDir) !== undefined;
-    const variants: PublishPlan['variants'] = {};
-    const fanout = new Map<string, string[]>();
-    const browser: PublishPlan['browser'] = [];
-    for (const target of targets) {
-        const profile = TARGET_PROFILES[target];
-        if (!profile) fail(`unsupported publish target: ${target} (unknown or not an article target)`);
-        const switchValue = profile.switch(live);
-        if (!switchValue) {
-            fail(
-                live
-                    ? `target ${target} refuses a live publish`
-                    : `target ${target} has no draft mode; it needs publish_live=true`,
-            );
-        }
-        if (profile.cover && !hasCover) {
-            fail(`target ${target} needs a cover image at 4-illustrations/cover.* in ${workDir}`);
-        }
-        const variant = `${profile.locale === 'source' ? sourceLocale : profile.locale}-${profile.format}`;
-        const sharesSourceArticle = variant === `${sourceLocale}-article`;
-        const entry = variants[variant] ?? {
-            file: sharesSourceArticle ? 'content.json' : `content.${variant}.json`,
-            adapt: !sharesSourceArticle,
-            limits: sharesSourceArticle ? undefined : {},
-            switches: {} as Record<string, unknown>,
-        };
-        Object.assign(entry.switches, switchValue);
-        variants[variant] = entry;
-        if (profile.transport === 'browser') browser.push({ target, variant });
-        else {
-            const group = fanout.get(variant);
-            if (group) group.push(target);
-            else fanout.set(variant, [target]);
-        }
+    const cliEntry = join(__dirname, '../../../apps/cli/src/index.ts');
+    let res: ReturnType<typeof spawnSync>;
+    if (existsSync(cliEntry)) {
+        res = spawnSync(process.execPath, [cliEntry, 'stage', 'run', 'itc-publish-plan', ...args], {
+            stdio: ['inherit', 'pipe', 'pipe'],
+            env: { ...process.env, _KK_ITC_STAGE_NATIVE: '1' },
+        });
+    } else {
+        res = spawnSync('kk', ['stage', 'run', 'itc-publish-plan', ...args], {
+            stdio: ['inherit', 'pipe', 'pipe'],
+            env: { ...process.env, _KK_ITC_STAGE_NATIVE: '1' },
+        });
+    }
+    if (res.stdout && res.stdout.length > 0) {
+        process.stdout.write(res.stdout);
+    }
+    if (res.stderr && res.stderr.length > 0) {
+        const errText = res.stderr.toString('utf-8');
+        console.error(errText.endsWith('\n') ? errText.slice(0, -1) : errText);
+    }
+    if (res.error || (res.status !== null && res.status !== 0)) {
+        process.exit(res.status ?? 1);
     }
-    const plan: PublishPlan = {
-        live,
-        sourceLocale,
-        variants,
-        // canonical group order: the plan file must not depend on target argument order
-        fanout: [...fanout]
-            .sort(([a], [b]) => (a < b ? -1 : 1))
-            .map(([variant, groupTargets]) => ({ variant, targets: groupTargets })),
-        browser,
-    };
-    writeJson(join(workDir, '4-publish', 'publish-plan.json'), plan);
 }
 
 /** R3 — the adapt state's follow-up check: every adapt:true variant file exists with title/body. */

package/plugins/kk/scripts/kk-workflow-stages.ts

@@ -128,6 +128,21 @@ async function loadItcStages(): Promise<typeof import('./itc-stages.ts')> {
     }
 }
 
+/**
+ * Load the seo-* helper sibling lazily (task 0281): this runner is resolved — and copied
+ * alone — from installs where the sibling may be absent, so the seo-* stages fail loud with a
+ * remediation path instead of breaking every stage at load.
+ */
+async function loadSeoStages(): Promise<typeof import('./seo-stages.ts')> {
+    try {
+        return await import('./seo-stages.ts');
+    } catch {
+        return fail(
+            'seo-stages.ts not found next to kk-workflow-stages.ts — install or refresh the kk package (bun link in a checkout)',
+        );
+    }
+}
+
 /** coreutils-style reason for the errno codes the staged file operations can hit. */
 
 /**
@@ -1639,6 +1654,11 @@ if (import.meta.main)
             dailyIntro(rest);
             break;
         }
+        case 'daily-voice-audit': {
+            const { dailyVoiceAudit } = await loadDailyStages();
+            dailyVoiceAudit(rest);
+            break;
+        }
         case 'daily-episode-duration': {
             const { dailyEpisodeDuration } = await loadDailyStages();
             dailyEpisodeDuration(rest);
@@ -1739,8 +1759,25 @@ if (import.meta.main)
             itcAdaptVerify(rest);
             break;
         }
+        case 'seo-preflight':
+        case 'seo-collect':
+        case 'seo-check':
+        case 'seo-enrich':
+        case 'seo-judge':
+        case 'seo-score':
+        case 'seo-report': {
+            // The seo helper owns its dispatch: cancellation installation, the cancellation marker
+            // and the conventional signal exit status must apply however the stage was reached.
+            const { runSeoStage } = await loadSeoStages();
+            try {
+                await runSeoStage(stage, rest);
+            } catch (err: unknown) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+            break;
+        }
         default:
             fail(
-                `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|itc-*|daily-*)`,
+                `unknown stage: ${stage ?? '(none)'} (expected prepare-itc|prepare-solo|prepare-storm|validate|wrap|duration|render-storm|itc-*|daily-*|seo-*)`,
             );
     }