@akemi-mio/creativity 0.2.0 → 0.3.0

package/dist/ConceptMixer.d.ts

@@ -33,10 +33,13 @@ export declare class ConceptMixer {
      * @param strategy 策略约束：stable/explore/signal，默认为 'explore'
      *   策略决定哪些 type 配对被允许、评分权重如何调整。
      * @param feedback 可选：正向反馈有界修正 + 探索预算；缺省 = 行为不变。
+     * @returns 每项含 combo / score / pair。pair 是组合引用的原始来源对象对
+     *   （R2 收敛：CLI 引擎等调用方不再从 combo.sources 字符串反查来源）。
      */
     mix(sources: CreativitySource[], maxCombos?: number, exploredPairs?: string[], strategy?: Strategy, feedback?: FeedbackMixerInput): {
         combo: ConceptCombo;
         score: number;
+        pair: [CreativitySource, CreativitySource];
     }[];
     /**
      * 按策略约束生成配对 — 核心改动：

package/dist/ConceptMixer.js

@@ -27,6 +27,8 @@ class ConceptMixer {
      * @param strategy 策略约束：stable/explore/signal，默认为 'explore'
      *   策略决定哪些 type 配对被允许、评分权重如何调整。
      * @param feedback 可选：正向反馈有界修正 + 探索预算；缺省 = 行为不变。
+     * @returns 每项含 combo / score / pair。pair 是组合引用的原始来源对象对
+     *   （R2 收敛：CLI 引擎等调用方不再从 combo.sources 字符串反查来源）。
      */
     mix(sources, maxCombos = 10, exploredPairs = [], strategy = 'explore', feedback) {
         if (sources.length < 2)
@@ -64,7 +66,7 @@ class ConceptMixer {
             .slice(0, exploreCount);
         return [...main, ...rest]
             .sort((a, b) => (b.adjusted - a.adjusted) || (a.feedbackKey < b.feedbackKey ? -1 : 1))
-            .map((s) => ({ combo: s.combo, score: s.adjusted }));
+            .map((s) => ({ combo: s.combo, score: s.adjusted, pair: s.pair }));
     }
     /**
      * 按策略约束生成配对 — 核心改动：
@@ -147,7 +149,7 @@ class ConceptMixer {
             description,
             createdAt: Date.now(),
         };
-        return { combo, score };
+        return { combo, score, pair: [a, b] };
     }
     contentRelevance(a, b) {
         const contentA = a.fullContent ?? a.content;

package/dist/FeedbackMetrics.d.ts

@@ -0,0 +1,90 @@
+/**
+ * FeedbackMetrics — 正向反馈闭环验证指标（spec §八，P3 收官）
+ *
+ * 把"三类验证指标"里能在本地数据上回答的部分落成纯函数：
+ *   - Pair Precision@K：快照中反馈调整幅度最大的 K 个概念对里，
+ *     已有终局（validated/rejected）假设的对的通过率（无终局样本 → null，
+ *     无样本 ≠ 0；hypothesis_only 键不是概念对，不参与排名）。
+ *   - Novelty@K：top-K 概念对里未被窗口内假设探索过的比例。
+ *   - Validation Pass Rate：窗口内终局假设的通过率。
+ *   - Event Ingestion Completeness：JSONL 原始行 vs 可解析行（损坏行=丢失）。
+ *
+ * 身份规则与快照一致（types.ts sourceConceptId/conceptPairKey）：
+ * 概念对键 = conceptPairKey(sourceConceptId)，hypothesis_only 键带
+ * `hypothesis:` 前缀被排除；无 provenance 的假设回退 sourceLabels 的
+ * `name:` 键（与 sourceConceptId 的无 origin 回退同空间）。
+ *
+ * 纯函数：不读写文件、不碰 DB、不进 checkPromotionGate/checkSubmitGate
+ * 输入（spec §二.2 反馈权限隔离）。
+ */
+import { type FeedbackLearningConfig, type FeedbackSnapshot } from './FeedbackLearning';
+export interface FeedbackMetricsConfig {
+    /** Pair Precision@K / Novelty@K 的 K */
+    precisionK: number;
+    /** 通过率与探索集的回看窗口（天） */
+    windowDays: number;
+}
+export declare const DEFAULT_FEEDBACK_METRICS_CONFIG: FeedbackMetricsConfig;
+/** 解析并校验指标配置；两个字段都缺失返回 null（fail-closed，调用方回退默认）。 */
+export declare function parseFeedbackMetricsConfig(raw: unknown): FeedbackMetricsConfig | null;
+/** 从环境变量解析（MIO_FEEDBACK_PRECISION_K / MIO_FEEDBACK_WINDOW_DAYS，缺省全默认）。 */
+export declare function resolveFeedbackMetricsConfig(env?: Record<string, string | undefined>): FeedbackMetricsConfig;
+/** 结构子集：主进程 Hypothesis 与 CLI store 行都满足（只要求用到的字段）。 */
+export interface FeedbackMetricsHypothesis {
+    id: string;
+    status?: string;
+    createdAt?: number;
+    sourceLabels?: readonly string[];
+    provenance?: {
+        sources?: ReadonlyArray<{
+            name: string;
+            origin?: string;
+        }>;
+    };
+}
+/** 证据事件 JSONL 的行统计（调用方做原始扫描；本模块纯计算）。 */
+export interface FeedbackIngestionCounts {
+    /** 非空行总数 */
+    rawLines: number;
+    /** 可 JSON 解析的行数 */
+    validRows: number;
+}
+export interface FeedbackTopPair {
+    pairKey: string;
+    /** λ clamp 后的调整量（排名依据取绝对值） */
+    adjustment: number;
+    validated: number;
+    rejected: number;
+    /** 无终局样本 → null（无样本 ≠ 0） */
+    precision: number | null;
+    /** 是否未被窗口内假设探索过 */
+    novel: boolean;
+}
+export interface FeedbackGenerationMetrics {
+    precisionK: number;
+    windowDays: number;
+    snapshotVersion: string | null;
+    pairPrecisionAtK: number | null;
+    evaluatedPairs: number;
+    noveltyAtK: number | null;
+    validationPassRate: number | null;
+    /** 窗口内终局假设数（validationPassRate 的分母） */
+    terminalHypotheses: number;
+    ingestion: {
+        rawLines: number;
+        validRows: number;
+        droppedRows: number;
+        completeness: number | null;
+    };
+    topPairs: FeedbackTopPair[];
+}
+export interface ComputeFeedbackGenerationMetricsArgs {
+    snapshot?: FeedbackSnapshot | null;
+    hypotheses?: readonly FeedbackMetricsHypothesis[];
+    ingestion?: FeedbackIngestionCounts;
+    config?: FeedbackMetricsConfig;
+    /** 缺省 Date.now()；测试可注入固定时间 */
+    now?: number;
+    learningConfig?: FeedbackLearningConfig;
+}
+export declare function computeFeedbackGenerationMetrics(args?: ComputeFeedbackGenerationMetricsArgs): FeedbackGenerationMetrics;

package/dist/FeedbackMetrics.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * FeedbackMetrics — 正向反馈闭环验证指标（spec §八，P3 收官）
+ *
+ * 把"三类验证指标"里能在本地数据上回答的部分落成纯函数：
+ *   - Pair Precision@K：快照中反馈调整幅度最大的 K 个概念对里，
+ *     已有终局（validated/rejected）假设的对的通过率（无终局样本 → null，
+ *     无样本 ≠ 0；hypothesis_only 键不是概念对，不参与排名）。
+ *   - Novelty@K：top-K 概念对里未被窗口内假设探索过的比例。
+ *   - Validation Pass Rate：窗口内终局假设的通过率。
+ *   - Event Ingestion Completeness：JSONL 原始行 vs 可解析行（损坏行=丢失）。
+ *
+ * 身份规则与快照一致（types.ts sourceConceptId/conceptPairKey）：
+ * 概念对键 = conceptPairKey(sourceConceptId)，hypothesis_only 键带
+ * `hypothesis:` 前缀被排除；无 provenance 的假设回退 sourceLabels 的
+ * `name:` 键（与 sourceConceptId 的无 origin 回退同空间）。
+ *
+ * 纯函数：不读写文件、不碰 DB、不进 checkPromotionGate/checkSubmitGate
+ * 输入（spec §二.2 反馈权限隔离）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FEEDBACK_METRICS_CONFIG = void 0;
+exports.parseFeedbackMetricsConfig = parseFeedbackMetricsConfig;
+exports.resolveFeedbackMetricsConfig = resolveFeedbackMetricsConfig;
+exports.computeFeedbackGenerationMetrics = computeFeedbackGenerationMetrics;
+const FeedbackLearning_1 = require("./FeedbackLearning");
+const types_1 = require("./types");
+exports.DEFAULT_FEEDBACK_METRICS_CONFIG = {
+    precisionK: 10,
+    windowDays: 30,
+};
+function clampNumber(value, min, max, fallback) {
+    const num = typeof value === 'string' ? Number(value) : value;
+    if (typeof num !== 'number' || !Number.isFinite(num))
+        return fallback;
+    return Math.max(min, Math.min(max, num));
+}
+/** 解析并校验指标配置；两个字段都缺失返回 null（fail-closed，调用方回退默认）。 */
+function parseFeedbackMetricsConfig(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    const hasAny = ['precisionK', 'windowDays'].some((k) => obj[k] !== undefined);
+    if (!hasAny)
+        return null;
+    return {
+        precisionK: Math.floor(clampNumber(obj.precisionK, 1, 1000, exports.DEFAULT_FEEDBACK_METRICS_CONFIG.precisionK)),
+        windowDays: Math.floor(clampNumber(obj.windowDays, 1, 3650, exports.DEFAULT_FEEDBACK_METRICS_CONFIG.windowDays)),
+    };
+}
+/** 从环境变量解析（MIO_FEEDBACK_PRECISION_K / MIO_FEEDBACK_WINDOW_DAYS，缺省全默认）。 */
+function resolveFeedbackMetricsConfig(env = process.env) {
+    return (parseFeedbackMetricsConfig({
+        precisionK: env.MIO_FEEDBACK_PRECISION_K,
+        windowDays: env.MIO_FEEDBACK_WINDOW_DAYS,
+    }) ?? exports.DEFAULT_FEEDBACK_METRICS_CONFIG);
+}
+const TERMINAL_STATUSES = new Set(['validated', 'rejected']);
+const DAY_MS = 86_400_000;
+const HYPOTHESIS_ONLY_PREFIX = 'hypothesis:';
+/** 由 provenance 来源推导概念对键（与 buildFeedbackSnapshot 的归因同一规则）。 */
+function pairKeysFromSources(sources) {
+    const ids = sources.map(types_1.sourceConceptId);
+    const keys = [];
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            if (ids[i] === ids[j])
+                continue;
+            keys.push((0, types_1.conceptPairKey)(ids[i], ids[j]));
+        }
+    }
+    return keys;
+}
+/** 无 provenance 假设的回退：sourceLabels 是原始名，等价于无 origin 的概念身份。 */
+function pairKeysFromLabels(labels) {
+    const ids = labels.map((l) => `name:${l}`);
+    const keys = [];
+    for (let i = 0; i < ids.length; i++) {
+        for (let j = i + 1; j < ids.length; j++) {
+            if (ids[i] === ids[j])
+                continue;
+            keys.push((0, types_1.conceptPairKey)(ids[i], ids[j]));
+        }
+    }
+    return keys;
+}
+function computeFeedbackGenerationMetrics(args = {}) {
+    const config = args.config ?? exports.DEFAULT_FEEDBACK_METRICS_CONFIG;
+    const now = args.now ?? Date.now();
+    const learningConfig = args.learningConfig ?? FeedbackLearning_1.DEFAULT_FEEDBACK_LEARNING_CONFIG;
+    const hypotheses = args.hypotheses ?? [];
+    const snapshot = args.snapshot ?? null;
+    const cutoff = now - config.windowDays * DAY_MS;
+    // ── Validation Pass Rate（窗口内终局假设） ──
+    let validatedTotal = 0;
+    let rejectedTotal = 0;
+    for (const h of hypotheses) {
+        if (!h.status || !TERMINAL_STATUSES.has(h.status))
+            continue;
+        if (typeof h.createdAt !== 'number' || h.createdAt < cutoff)
+            continue;
+        if (h.status === 'validated')
+            validatedTotal++;
+        else
+            rejectedTotal++;
+    }
+    const terminalHypotheses = validatedTotal + rejectedTotal;
+    const validationPassRate = terminalHypotheses > 0 ? validatedTotal / terminalHypotheses : null;
+    // ── 终局假设 → 概念对链接（全量：配对证据来自快照，不受窗口裁剪） ──
+    const pairToTerminal = new Map();
+    for (const h of hypotheses) {
+        if (!h.status || !TERMINAL_STATUSES.has(h.status))
+            continue;
+        const sources = h.provenance?.sources;
+        if (!sources || sources.length < 2)
+            continue;
+        for (const key of pairKeysFromSources(sources)) {
+            let counts = pairToTerminal.get(key);
+            if (!counts) {
+                counts = { validated: 0, rejected: 0 };
+                pairToTerminal.set(key, counts);
+            }
+            if (h.status === 'validated')
+                counts.validated++;
+            else
+                counts.rejected++;
+        }
+    }
+    // ── 窗口内探索集（novelty 判定） ──
+    const explored = new Set();
+    for (const h of hypotheses) {
+        if (typeof h.createdAt !== 'number' || h.createdAt < cutoff)
+            continue;
+        const sources = h.provenance?.sources;
+        if (sources && sources.length >= 2) {
+            for (const key of pairKeysFromSources(sources))
+                explored.add(key);
+        }
+        else if (h.sourceLabels && h.sourceLabels.length >= 2) {
+            for (const key of pairKeysFromLabels(h.sourceLabels))
+                explored.add(key);
+        }
+    }
+    // ── top-K：快照概念对按 |clampedAdjustment| 排名（tie-break pairKey，稳定） ──
+    const conceptPairs = (snapshot?.pairs ?? []).filter((p) => !p.pairKey.startsWith(HYPOTHESIS_ONLY_PREFIX));
+    const topPairs = conceptPairs
+        .map((p) => {
+        const counts = pairToTerminal.get(p.pairKey);
+        const validated = counts?.validated ?? 0;
+        const rejected = counts?.rejected ?? 0;
+        const total = validated + rejected;
+        return {
+            pairKey: p.pairKey,
+            adjustment: (0, FeedbackLearning_1.replayFeedbackAdjustment)(p, learningConfig).clampedAdjustment,
+            validated,
+            rejected,
+            precision: total > 0 ? validated / total : null,
+            novel: !explored.has(p.pairKey),
+        };
+    })
+        .sort((a, b) => Math.abs(b.adjustment) - Math.abs(a.adjustment) || (a.pairKey < b.pairKey ? -1 : 1))
+        .slice(0, config.precisionK);
+    let evaluatedPairs = 0;
+    let precisionSum = 0;
+    let novelCount = 0;
+    for (const p of topPairs) {
+        if (p.precision !== null) {
+            evaluatedPairs++;
+            precisionSum += p.precision;
+        }
+        if (p.novel)
+            novelCount++;
+    }
+    const pairPrecisionAtK = evaluatedPairs > 0 ? precisionSum / evaluatedPairs : null;
+    const noveltyAtK = topPairs.length > 0 ? novelCount / topPairs.length : null;
+    // ── 事件摄取完整度（原始行 vs 可解析行） ──
+    const rawLines = args.ingestion?.rawLines ?? 0;
+    const validRows = args.ingestion?.validRows ?? 0;
+    const droppedRows = Math.max(0, rawLines - validRows);
+    const completeness = rawLines > 0 ? Math.max(0, Math.min(1, validRows / rawLines)) : null;
+    return {
+        precisionK: config.precisionK,
+        windowDays: config.windowDays,
+        snapshotVersion: snapshot?.version ?? null,
+        pairPrecisionAtK,
+        evaluatedPairs,
+        noveltyAtK,
+        validationPassRate,
+        terminalHypotheses,
+        ingestion: { rawLines, validRows, droppedRows, completeness },
+        topPairs,
+    };
+}

package/dist/FeedbackRuntime.d.ts

@@ -33,5 +33,5 @@ export declare function parseFeedbackRuntime(raw: unknown): FeedbackRuntimeConfi
 export declare function resolveFeedbackRuntime(env?: Record<string, string | undefined>): FeedbackRuntimeConfig;
 /** 该模式下是否实际应用反馈到生成（shadow 只观测）。 */
 export declare function isFeedbackApplied(mode: FeedbackMode): boolean;
-/** 该模式下是否观测（计算 delta 并记录）。 */
-export declare function isFeedbackObserved(mode: FeedbackMode): boolean;
+/** 该模式下是否观测（计算 delta 并记录）。谓词形式让调用方在守卫内拿到非 `off` 收窄。 */
+export declare function isFeedbackObserved(mode: FeedbackMode): mode is Exclude<FeedbackMode, 'off'>;

package/dist/FeedbackRuntime.js

@@ -66,7 +66,7 @@ function resolveFeedbackRuntime(env = process.env) {
 function isFeedbackApplied(mode) {
     return mode === 'canary' || mode === 'full';
 }
-/** 该模式下是否观测（计算 delta 并记录）。 */
+/** 该模式下是否观测（计算 delta 并记录）。谓词形式让调用方在守卫内拿到非 `off` 收窄。 */
 function isFeedbackObserved(mode) {
     return mode === 'shadow' || mode === 'canary' || mode === 'full';
 }

package/dist/FeedbackRuntimeRuns.d.ts

@@ -0,0 +1,14 @@
+import type { FeedbackRuntimeRun } from './FeedbackRollout';
+/**
+ * feedback-runtime-runs.jsonl 的唯一读写实现（append-only，供放量报告统计阶段门槛）。
+ *
+ * 双轴共用：CLI/MCP（CreativityEngine）与主进程（CreativityService）都经由本模块落盘，
+ * 因此两个入口写入的行格式与读取口径不可能各自漂移（同 memory-store/policy-store 模式）。
+ * 数据目录由调用方决定：CLI/MCP 是 `<MIO_HOME>/creativity`，主进程是
+ * `MIO_HOME/creativity`（未设置时回退 `WORKSPACE_ROOT/creativity`）。
+ */
+export declare const FEEDBACK_RUNTIME_RUNS_FILE = "feedback-runtime-runs.jsonl";
+/** 追加一条观测运行摘要。落盘失败由调用方 best-effort 兜底（不得阻断生成）。 */
+export declare function recordFeedbackRuntimeRun(dir: string, run: FeedbackRuntimeRun): void;
+/** 读取全部观测运行摘要。损坏行/非对象行/`off` 行跳过（同 JsonlFeedbackEventStore 策略）。 */
+export declare function readFeedbackRuntimeRuns(dir: string): FeedbackRuntimeRun[];

package/dist/FeedbackRuntimeRuns.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEEDBACK_RUNTIME_RUNS_FILE = void 0;
+exports.recordFeedbackRuntimeRun = recordFeedbackRuntimeRun;
+exports.readFeedbackRuntimeRuns = readFeedbackRuntimeRuns;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const FeedbackRuntime_1 = require("./FeedbackRuntime");
+/**
+ * feedback-runtime-runs.jsonl 的唯一读写实现（append-only，供放量报告统计阶段门槛）。
+ *
+ * 双轴共用：CLI/MCP（CreativityEngine）与主进程（CreativityService）都经由本模块落盘，
+ * 因此两个入口写入的行格式与读取口径不可能各自漂移（同 memory-store/policy-store 模式）。
+ * 数据目录由调用方决定：CLI/MCP 是 `<MIO_HOME>/creativity`，主进程是
+ * `MIO_HOME/creativity`（未设置时回退 `WORKSPACE_ROOT/creativity`）。
+ */
+exports.FEEDBACK_RUNTIME_RUNS_FILE = 'feedback-runtime-runs.jsonl';
+/** 追加一条观测运行摘要。落盘失败由调用方 best-effort 兜底（不得阻断生成）。 */
+function recordFeedbackRuntimeRun(dir, run) {
+    if (!(0, fs_1.existsSync)(dir))
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    (0, fs_1.appendFileSync)((0, path_1.join)(dir, exports.FEEDBACK_RUNTIME_RUNS_FILE), JSON.stringify(run) + '\n', 'utf8');
+}
+/** 读取全部观测运行摘要。损坏行/非对象行/`off` 行跳过（同 JsonlFeedbackEventStore 策略）。 */
+function readFeedbackRuntimeRuns(dir) {
+    const file = (0, path_1.join)(dir, exports.FEEDBACK_RUNTIME_RUNS_FILE);
+    if (!(0, fs_1.existsSync)(file))
+        return [];
+    const out = [];
+    for (const line of (0, fs_1.readFileSync)(file, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (row &&
+                typeof row === 'object' &&
+                typeof row.mode === 'string' &&
+                row.mode !== 'off' &&
+                FeedbackRuntime_1.FEEDBACK_MODES.includes(row.mode)) {
+                out.push({
+                    at: Number(row.at) || 0,
+                    mode: row.mode,
+                    snapshotVersion: typeof row.snapshotVersion === 'string' ? row.snapshotVersion : null,
+                    pairCount: Number(row.pairCount) || 0,
+                    applied: !!row.applied,
+                });
+            }
+        }
+        catch (_) {
+            // 损坏行跳过
+        }
+    }
+    return out;
+}

package/dist/HypothesisGenerator.d.ts

@@ -20,6 +20,7 @@ export declare class HypothesisGenerator {
         timeoutMs?: number;
         requestId?: string;
         maxTokens?: number;
+        responseFormat?: 'object' | 'array';
     }) => Promise<{
         data?: any;
         error?: string;

package/dist/HypothesisGenerator.js

@@ -122,6 +122,12 @@ class HypothesisGenerator {
                 timeoutMs: 60000,
                 // 输出无界会顶满超时（M2）：生成上限 1200 tokens
                 maxTokens: 1200,
+                // 提示词要求顶层数组：json_object 模式下部分模型会包成
+                // {"ideas": [...]}，Array.isArray 判空后**静默**降级到模板
+                // （无 provenance.sources → 反馈事件不可归因，attribution
+                // coverage 恒 0）。声明 array 身份让 llm-client 省略
+                // response_format，与 InsightGenerator 同策略。
+                responseFormat: 'array',
             });
             if (result.error) {
                 (0, Logger_1.log)('WARN', 'hypothesis_llm_error', { error: result.error });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akemi-mio/creativity",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Creativity layer: ideas, writing, blog, image, inspiration",
   "main": "./dist/IdeaGenerator.js",
   "types": "./dist/IdeaGenerator.d.ts",
@@ -85,6 +85,16 @@
       "require": "./dist/FeedbackRollout.js",
       "default": "./dist/FeedbackRollout.js"
     },
+    "./FeedbackRuntimeRuns": {
+      "types": "./dist/FeedbackRuntimeRuns.d.ts",
+      "require": "./dist/FeedbackRuntimeRuns.js",
+      "default": "./dist/FeedbackRuntimeRuns.js"
+    },
+    "./FeedbackMetrics": {
+      "types": "./dist/FeedbackMetrics.d.ts",
+      "require": "./dist/FeedbackMetrics.js",
+      "default": "./dist/FeedbackMetrics.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [