@evomap/evolver-core 2.0.0-beta.0

package/dist/personality/schema.d.ts

@@ -0,0 +1,255 @@
+import { z } from 'zod';
+/**
+ * PersonalityState = 可进化人格 (v1 src/gep/personality.js 的 v2 端口).
+ *
+ * 五维行为向量, 各 0..1, 决定进化"风格"而非"内容":
+ *  - rigor          严谨度: 越高越保守/协议优先, 是高危变异的准入前提
+ *  - creativity     创造性: 越高越倾向 innovate/explore, 跳出局部最优
+ *  - verbosity      啰嗦度: 影响产物叙述密度 (纯 prompt 提示, 不改逻辑)
+ *  - risk_tolerance 风险容忍: 越高越敢冒险, 但会被风险闸压制
+ *  - obedience      服从度: 越高越贴合协议/用户指令
+ *
+ * 三条用途 (v2 必须保留语义, 见 riskGate.ts / prompt.ts / (PR-2) selection):
+ *  1. 注入每轮 GEP prompt, 决定进化风格 (prompt.ts)
+ *  2. 变异风险闸: high-risk/innovate 变异只在 rigor≥0.6 且 risk_tolerance≤0.5 放行 (riskGate.ts)
+ *  3. 自然选择 + 小步变异自调参, 成功强化/失败淘汰, 全程进事件流可审计 (PR-2)
+ */
+/** 五维行为轴 (顺序固定 — personalityKey / 遍历依赖它). */
+export declare const PERSONALITY_AXES: readonly ["rigor", "creativity", "verbosity", "risk_tolerance", "obedience"];
+export type PersonalityAxis = (typeof PERSONALITY_AXES)[number];
+/** 保守默认: 协议优先、安全、低风险 (v1 defaultPersonalityState 原值). */
+export declare const DEFAULT_PERSONALITY: Readonly<{
+    rigor: 0.7;
+    creativity: 0.35;
+    verbosity: 0.25;
+    risk_tolerance: 0.4;
+    obedience: 0.85;
+}>;
+/** 五维人格状态. type 判别标签保留 (v1/事件流互认). */
+export declare const personalityState: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"PersonalityState">>;
+    rigor: z.ZodDefault<z.ZodNumber>;
+    creativity: z.ZodDefault<z.ZodNumber>;
+    verbosity: z.ZodDefault<z.ZodNumber>;
+    risk_tolerance: z.ZodDefault<z.ZodNumber>;
+    obedience: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "PersonalityState";
+    rigor: number;
+    creativity: number;
+    verbosity: number;
+    risk_tolerance: number;
+    obedience: number;
+}, {
+    type?: "PersonalityState" | undefined;
+    rigor?: number | undefined;
+    creativity?: number | undefined;
+    verbosity?: number | undefined;
+    risk_tolerance?: number | undefined;
+    obedience?: number | undefined;
+}>;
+export type PersonalityState = z.infer<typeof personalityState>;
+/**
+ * 宽松输入形状: 允许省略 type、缺轴、越界值 —— 凡是会经 normalizePersonalityState 的公共入口都收这个,
+ * 由 normalize 夹成合法 PersonalityState. 这样调用方可以直接传 DEFAULT_PERSONALITY 或部分覆盖对象.
+ */
+export type PersonalityStateInput = Partial<Record<PersonalityAxis, number>> & {
+    type?: string;
+};
+/** 一个人格键的运行统计 (自然选择的适应度原料; PR-2 回写). */
+export declare const personalityStats: z.ZodObject<{
+    success: z.ZodDefault<z.ZodNumber>;
+    fail: z.ZodDefault<z.ZodNumber>;
+    /** 增量均值; n 为纳入均值的样本数. */
+    avgScore: z.ZodDefault<z.ZodNumber>;
+    n: z.ZodDefault<z.ZodNumber>;
+    updatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    success: number;
+    n: number;
+    updatedAt: string | null;
+    avgScore: number;
+    fail: number;
+}, {
+    success?: number | undefined;
+    n?: number | undefined;
+    updatedAt?: string | null | undefined;
+    avgScore?: number | undefined;
+    fail?: number | undefined;
+}>;
+export type PersonalityStats = z.infer<typeof personalityStats>;
+/** 单条人格变更历史 (可审计; 也镜像进事件流). */
+export declare const personalityHistoryEntry: z.ZodObject<{
+    at: z.ZodString;
+    key: z.ZodString;
+    outcome: z.ZodString;
+    score: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    score: number | null;
+    outcome: string;
+    key: string;
+    notes: string | null;
+}, {
+    at: string;
+    outcome: string;
+    key: string;
+    score?: number | null | undefined;
+    notes?: string | null | undefined;
+}>;
+export type PersonalityHistoryEntry = z.infer<typeof personalityHistoryEntry>;
+/** 持久化模型: 当前人格 + 各键统计 + 变更历史 (v1 loadPersonalityModel 的 v2 形状). */
+export declare const personalityModel: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    current: z.ZodDefault<z.ZodObject<{
+        type: z.ZodDefault<z.ZodLiteral<"PersonalityState">>;
+        rigor: z.ZodDefault<z.ZodNumber>;
+        creativity: z.ZodDefault<z.ZodNumber>;
+        verbosity: z.ZodDefault<z.ZodNumber>;
+        risk_tolerance: z.ZodDefault<z.ZodNumber>;
+        obedience: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        type: "PersonalityState";
+        rigor: number;
+        creativity: number;
+        verbosity: number;
+        risk_tolerance: number;
+        obedience: number;
+    }, {
+        type?: "PersonalityState" | undefined;
+        rigor?: number | undefined;
+        creativity?: number | undefined;
+        verbosity?: number | undefined;
+        risk_tolerance?: number | undefined;
+        obedience?: number | undefined;
+    }>>;
+    stats: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        success: z.ZodDefault<z.ZodNumber>;
+        fail: z.ZodDefault<z.ZodNumber>;
+        /** 增量均值; n 为纳入均值的样本数. */
+        avgScore: z.ZodDefault<z.ZodNumber>;
+        n: z.ZodDefault<z.ZodNumber>;
+        updatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        success: number;
+        n: number;
+        updatedAt: string | null;
+        avgScore: number;
+        fail: number;
+    }, {
+        success?: number | undefined;
+        n?: number | undefined;
+        updatedAt?: string | null | undefined;
+        avgScore?: number | undefined;
+        fail?: number | undefined;
+    }>>>;
+    history: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        key: z.ZodString;
+        outcome: z.ZodString;
+        score: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        notes: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        score: number | null;
+        outcome: string;
+        key: string;
+        notes: string | null;
+    }, {
+        at: string;
+        outcome: string;
+        key: string;
+        score?: number | null | undefined;
+        notes?: string | null | undefined;
+    }>, "many">>;
+    updatedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    extensions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    extensions: Record<string, unknown>;
+    updatedAt: string | null;
+    version: 1;
+    current: {
+        type: "PersonalityState";
+        rigor: number;
+        creativity: number;
+        verbosity: number;
+        risk_tolerance: number;
+        obedience: number;
+    };
+    stats: Record<string, {
+        success: number;
+        n: number;
+        updatedAt: string | null;
+        avgScore: number;
+        fail: number;
+    }>;
+    history: {
+        at: string;
+        score: number | null;
+        outcome: string;
+        key: string;
+        notes: string | null;
+    }[];
+}, {
+    extensions?: Record<string, unknown> | undefined;
+    updatedAt?: string | null | undefined;
+    version?: 1 | undefined;
+    current?: {
+        type?: "PersonalityState" | undefined;
+        rigor?: number | undefined;
+        creativity?: number | undefined;
+        verbosity?: number | undefined;
+        risk_tolerance?: number | undefined;
+        obedience?: number | undefined;
+    } | undefined;
+    stats?: Record<string, {
+        success?: number | undefined;
+        n?: number | undefined;
+        updatedAt?: string | null | undefined;
+        avgScore?: number | undefined;
+        fail?: number | undefined;
+    }> | undefined;
+    history?: {
+        at: string;
+        outcome: string;
+        key: string;
+        score?: number | null | undefined;
+        notes?: string | null | undefined;
+    }[] | undefined;
+}>;
+export type PersonalityModel = z.infer<typeof personalityModel>;
+/** 单个变异提案 (作用于一个轴, delta 会被 applyMutations 夹取). */
+export declare const personalityMutation: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"PersonalityMutation">>;
+    param: z.ZodEnum<["rigor", "creativity", "verbosity", "risk_tolerance", "obedience"]>;
+    delta: z.ZodNumber;
+    reason: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "PersonalityMutation";
+    reason: string;
+    param: "rigor" | "creativity" | "verbosity" | "risk_tolerance" | "obedience";
+    delta: number;
+}, {
+    param: "rigor" | "creativity" | "verbosity" | "risk_tolerance" | "obedience";
+    delta: number;
+    type?: "PersonalityMutation" | undefined;
+    reason?: string | undefined;
+}>;
+export type PersonalityMutation = z.infer<typeof personalityMutation>;
+declare const clamp01: (x: unknown) => number;
+/**
+ * 把任意输入夹成合法 PersonalityState (缺失/越界/非数 → 夹到 [0,1]).
+ * 注意: 与 v1 一致, 非有限值夹为 0 而非默认值 — 显式坏输入不静默"复活"成保守默认.
+ */
+export declare function normalizePersonalityState(state: unknown): PersonalityState;
+/** 严格校验: type 标签对且五轴都是 [0,1] 有限数 (不做夹取, 用于信任边界). */
+export declare function isValidPersonalityState(obj: unknown): obj is PersonalityState;
+/**
+ * 稳定桶键: 五轴各按 0.1 步长量化后拼串. 相近人格落同一桶, 统计才能积累 (v1 personalityKey).
+ * 例: "rigor=0.7|creativity=0.4|verbosity=0.2|risk_tolerance=0.4|obedience=0.9"
+ */
+export declare function personalityKey(state: unknown): string;
+/** 由 personalityKey 反解回 PersonalityState (未识别轴回落默认; 自然选择需要). */
+export declare function parseKeyToState(key: string): PersonalityState;
+export { clamp01 };

package/dist/personality/schema.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { extensions } from '../schema/common.js';
+/**
+ * PersonalityState = 可进化人格 (v1 src/gep/personality.js 的 v2 端口).
+ *
+ * 五维行为向量, 各 0..1, 决定进化"风格"而非"内容":
+ *  - rigor          严谨度: 越高越保守/协议优先, 是高危变异的准入前提
+ *  - creativity     创造性: 越高越倾向 innovate/explore, 跳出局部最优
+ *  - verbosity      啰嗦度: 影响产物叙述密度 (纯 prompt 提示, 不改逻辑)
+ *  - risk_tolerance 风险容忍: 越高越敢冒险, 但会被风险闸压制
+ *  - obedience      服从度: 越高越贴合协议/用户指令
+ *
+ * 三条用途 (v2 必须保留语义, 见 riskGate.ts / prompt.ts / (PR-2) selection):
+ *  1. 注入每轮 GEP prompt, 决定进化风格 (prompt.ts)
+ *  2. 变异风险闸: high-risk/innovate 变异只在 rigor≥0.6 且 risk_tolerance≤0.5 放行 (riskGate.ts)
+ *  3. 自然选择 + 小步变异自调参, 成功强化/失败淘汰, 全程进事件流可审计 (PR-2)
+ */
+/** 五维行为轴 (顺序固定 — personalityKey / 遍历依赖它). */
+export const PERSONALITY_AXES = ['rigor', 'creativity', 'verbosity', 'risk_tolerance', 'obedience'];
+/** 保守默认: 协议优先、安全、低风险 (v1 defaultPersonalityState 原值). */
+export const DEFAULT_PERSONALITY = Object.freeze({
+    rigor: 0.7,
+    creativity: 0.35,
+    verbosity: 0.25,
+    risk_tolerance: 0.4,
+    obedience: 0.85,
+});
+const axis01 = z.number().min(0).max(1);
+/** 五维人格状态. type 判别标签保留 (v1/事件流互认). */
+export const personalityState = z.object({
+    type: z.literal('PersonalityState').default('PersonalityState'),
+    rigor: axis01.default(DEFAULT_PERSONALITY.rigor),
+    creativity: axis01.default(DEFAULT_PERSONALITY.creativity),
+    verbosity: axis01.default(DEFAULT_PERSONALITY.verbosity),
+    risk_tolerance: axis01.default(DEFAULT_PERSONALITY.risk_tolerance),
+    obedience: axis01.default(DEFAULT_PERSONALITY.obedience),
+});
+/** 一个人格键的运行统计 (自然选择的适应度原料; PR-2 回写). */
+export const personalityStats = z.object({
+    success: z.number().int().nonnegative().default(0),
+    fail: z.number().int().nonnegative().default(0),
+    /** 增量均值; n 为纳入均值的样本数. */
+    avgScore: z.number().min(0).max(1).default(0.5),
+    n: z.number().int().nonnegative().default(0),
+    updatedAt: z.string().datetime().nullable().default(null),
+});
+/** 单条人格变更历史 (可审计; 也镜像进事件流). */
+export const personalityHistoryEntry = z.object({
+    at: z.string().datetime(),
+    key: z.string(),
+    outcome: z.string(),
+    score: z.number().min(0).max(1).nullable().default(null),
+    notes: z.string().nullable().default(null),
+});
+/** 持久化模型: 当前人格 + 各键统计 + 变更历史 (v1 loadPersonalityModel 的 v2 形状). */
+export const personalityModel = z.object({
+    version: z.literal(1).default(1),
+    current: personalityState.default(() => personalityState.parse({})),
+    stats: z.record(z.string(), personalityStats).default({}),
+    history: z.array(personalityHistoryEntry).default([]),
+    updatedAt: z.string().datetime().nullable().default(null),
+    extensions,
+});
+/** 单个变异提案 (作用于一个轴, delta 会被 applyMutations 夹取). */
+export const personalityMutation = z.object({
+    type: z.literal('PersonalityMutation').default('PersonalityMutation'),
+    param: z.enum(PERSONALITY_AXES),
+    delta: z.number(),
+    reason: z.string().default(''),
+});
+const clamp01 = (x) => {
+    const n = Number(x);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(1, n));
+};
+/**
+ * 把任意输入夹成合法 PersonalityState (缺失/越界/非数 → 夹到 [0,1]).
+ * 注意: 与 v1 一致, 非有限值夹为 0 而非默认值 — 显式坏输入不静默"复活"成保守默认.
+ */
+export function normalizePersonalityState(state) {
+    const s = (state && typeof state === 'object' ? state : {});
+    return {
+        type: 'PersonalityState',
+        rigor: clamp01(s['rigor']),
+        creativity: clamp01(s['creativity']),
+        verbosity: clamp01(s['verbosity']),
+        risk_tolerance: clamp01(s['risk_tolerance']),
+        obedience: clamp01(s['obedience']),
+    };
+}
+/** 严格校验: type 标签对且五轴都是 [0,1] 有限数 (不做夹取, 用于信任边界). */
+export function isValidPersonalityState(obj) {
+    return personalityState.safeParse(obj).success && obj.type === 'PersonalityState';
+}
+function roundToStep(x, step) {
+    if (!Number.isFinite(step) || step <= 0)
+        return x;
+    return Math.round(x / step) * step;
+}
+/**
+ * 稳定桶键: 五轴各按 0.1 步长量化后拼串. 相近人格落同一桶, 统计才能积累 (v1 personalityKey).
+ * 例: "rigor=0.7|creativity=0.4|verbosity=0.2|risk_tolerance=0.4|obedience=0.9"
+ */
+export function personalityKey(state) {
+    const s = normalizePersonalityState(state);
+    return PERSONALITY_AXES.map((k) => `${k}=${roundToStep(s[k], 0.1).toFixed(1)}`).join('|');
+}
+/** 由 personalityKey 反解回 PersonalityState (未识别轴回落默认; 自然选择需要). */
+export function parseKeyToState(key) {
+    const out = { ...DEFAULT_PERSONALITY };
+    for (const part of String(key ?? '').split('|')) {
+        const [k, v] = part.split('=').map((x) => x.trim());
+        if (k && PERSONALITY_AXES.includes(k))
+            out[k] = clamp01(v);
+    }
+    return normalizePersonalityState(out);
+}
+export { clamp01 };

package/dist/personality/select.d.ts

@@ -0,0 +1,46 @@
+import { type AppliedMutation } from './mutate.js';
+import { type TriggerCycleEvent } from './drift.js';
+import { type PersonalityAxis, type PersonalityModel, type PersonalityState } from './schema.js';
+/**
+ * 每轮人格选择 (v1 selectPersonalityForRun 端口): 自然选择微调 + 规则触发变异, 全在人格向量上小步演化.
+ * 说明: v1 还消费 reflection.suggested_mutations, 那是独立子系统, 不在 evolver-core personality 范围内 —— 本端口不含.
+ */
+/** 单周期最多落地几条变异 (v1: 防漂移, 总量封顶 4). */
+export declare const MAX_MUTATIONS_PER_CYCLE = 4;
+/** 自然选择只对差异 ≥ 此阈值的轴动手 (v1). */
+export declare const NATURAL_SELECTION_MIN_DIFF = 0.05;
+/** 自然选择每条 nudge 的夹取幅度 (v1: ±0.1). */
+export declare const NATURAL_SELECTION_CLIP = 0.1;
+export interface ParamDelta {
+    param: PersonalityAxis;
+    delta: number;
+}
+/** 两状态间各轴差 (b-a), 按 |delta| 降序 (v1 getParamDeltas). */
+export declare function getParamDeltas(from: PersonalityState, to: PersonalityState): ParamDelta[];
+export interface SelectInput {
+    driftEnabled?: boolean;
+    signals?: readonly string[];
+    recentEvents?: readonly TriggerCycleEvent[];
+}
+export interface SelectResult {
+    model: PersonalityModel;
+    state: PersonalityState;
+    key: string;
+    known: boolean;
+    mutations: AppliedMutation[];
+    meta: {
+        bestKnownKey: string | null;
+        bestKnownScore: number | null;
+        triggered: {
+            reason: string;
+        } | null;
+    };
+}
+/**
+ * 纯函数: 给定 model + 上下文, 算出本轮人格 (含微调), 返回新 model + 选择结果.
+ * 不落盘 —— store-backed 包装在 applySelectForRun (见 evolveOps.ts) 里持久化.
+ * 顺序 (与 v1 一致):
+ *  1. 自然选择: 朝 best-known 桶靠拢 (最多 2 轴, 差≥0.05, 每条夹 ±0.1)
+ *  2. 触发式变异: shouldTrigger → proposeMutations → apply (总量与①合并封顶 4)
+ */
+export declare function selectPersonalityForRun(model: PersonalityModel, input?: SelectInput): SelectResult;

package/dist/personality/select.js

@@ -0,0 +1,71 @@
+import { applyPersonalityMutations } from './mutate.js';
+import { chooseBestKnownPersonality } from './stats.js';
+import { proposeMutations, shouldTriggerPersonalityMutation } from './drift.js';
+import { normalizePersonalityState, parseKeyToState, personalityKey, PERSONALITY_AXES, } from './schema.js';
+/**
+ * 每轮人格选择 (v1 selectPersonalityForRun 端口): 自然选择微调 + 规则触发变异, 全在人格向量上小步演化.
+ * 说明: v1 还消费 reflection.suggested_mutations, 那是独立子系统, 不在 evolver-core personality 范围内 —— 本端口不含.
+ */
+/** 单周期最多落地几条变异 (v1: 防漂移, 总量封顶 4). */
+export const MAX_MUTATIONS_PER_CYCLE = 4;
+/** 自然选择只对差异 ≥ 此阈值的轴动手 (v1). */
+export const NATURAL_SELECTION_MIN_DIFF = 0.05;
+/** 自然选择每条 nudge 的夹取幅度 (v1: ±0.1). */
+export const NATURAL_SELECTION_CLIP = 0.1;
+/** 两状态间各轴差 (b-a), 按 |delta| 降序 (v1 getParamDeltas). */
+export function getParamDeltas(from, to) {
+    const a = normalizePersonalityState(from);
+    const b = normalizePersonalityState(to);
+    return PERSONALITY_AXES
+        .map((param) => ({ param, delta: b[param] - a[param] }))
+        .sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+}
+/**
+ * 纯函数: 给定 model + 上下文, 算出本轮人格 (含微调), 返回新 model + 选择结果.
+ * 不落盘 —— store-backed 包装在 applySelectForRun (见 evolveOps.ts) 里持久化.
+ * 顺序 (与 v1 一致):
+ *  1. 自然选择: 朝 best-known 桶靠拢 (最多 2 轴, 差≥0.05, 每条夹 ±0.1)
+ *  2. 触发式变异: shouldTrigger → proposeMutations → apply (总量与①合并封顶 4)
+ */
+export function selectPersonalityForRun(model, input = {}) {
+    let current = normalizePersonalityState(model.current);
+    const applied = [];
+    // ① 自然选择
+    const best = chooseBestKnownPersonality(model.stats);
+    if (best) {
+        const bestState = parseKeyToState(best.key);
+        const diffs = getParamDeltas(current, bestState).filter((d) => Math.abs(d.delta) >= NATURAL_SELECTION_MIN_DIFF);
+        const muts = diffs.slice(0, 2).map((d) => ({
+            type: 'PersonalityMutation',
+            param: d.param,
+            delta: Math.max(-NATURAL_SELECTION_CLIP, Math.min(NATURAL_SELECTION_CLIP, d.delta)),
+            reason: 'natural_selection',
+        }));
+        const res = applyPersonalityMutations(current, muts);
+        current = res.state;
+        applied.push(...res.applied);
+    }
+    // ② 触发式变异 (受剩余额度约束)
+    const trig = shouldTriggerPersonalityMutation({ driftEnabled: !!input.driftEnabled, recentEvents: input.recentEvents });
+    if (trig.ok && applied.length < MAX_MUTATIONS_PER_CYCLE) {
+        const proposals = proposeMutations({ baseState: current, reason: trig.reason, driftEnabled: !!input.driftEnabled, signals: input.signals });
+        const res = applyPersonalityMutations(current, proposals);
+        current = res.state;
+        applied.push(...res.applied);
+    }
+    const key = personalityKey(current);
+    const known = Boolean(model.stats[key]);
+    const nextModel = { ...model, current };
+    return {
+        model: nextModel,
+        state: current,
+        key,
+        known,
+        mutations: applied,
+        meta: {
+            bestKnownKey: best?.key ?? null,
+            bestKnownScore: best ? best.score : null,
+            triggered: trig.ok ? { reason: trig.reason } : null,
+        },
+    };
+}

package/dist/personality/stats.d.ts

@@ -0,0 +1,46 @@
+import { type PersonalityModel, type PersonalityStateInput, type PersonalityStats } from './schema.js';
+/**
+ * 人格适应度 + 统计回写 (v1 personalityScore / chooseBestKnownPersonality / updatePersonalityStats 端口).
+ * 自然选择的"适者"由这里的分数决定; 每轮结果回写到对应人格桶, 供下一轮选择.
+ */
+/** 一个桶要参与"最佳已知"竞争的最小样本数 (v1: total<3 不计). */
+export declare const MIN_SAMPLES_FOR_BEST = 3;
+/** 样本权重饱和点 (v1: min(1, total/8)). */
+export declare const SAMPLE_WEIGHT_FULL_AT = 8;
+/**
+ * 桶适应度分数 (v1 personalityScore):
+ *  - Laplace 平滑成功率 p = (succ+1)/(total+2)  → 主导 (权重 0.75)
+ *  - 质量代理 q = avgScore, 但乘 sampleWeight 惩罚小样本过度自信 (权重 0.25)
+ */
+export declare function personalityScore(entry: Partial<PersonalityStats> | undefined): number;
+export interface BestKnown {
+    key: string;
+    score: number;
+    entry: PersonalityStats;
+}
+/**
+ * 选出"最佳已知"人格桶 (v1 chooseBestKnownPersonality): 只在样本≥MIN_SAMPLES_FOR_BEST 的桶里比 personalityScore.
+ * 没有够样本的桶 ⇒ null (选择阶段就不做自然选择微调).
+ */
+export declare function chooseBestKnownPersonality(stats: Record<string, PersonalityStats> | undefined): BestKnown | null;
+export interface UpdateStatsInput {
+    /** 本轮所用人格 (缺省用 model.current). */
+    personality?: PersonalityStateInput;
+    outcome: 'success' | 'failed' | string;
+    /** 0..1 质量分 (可选). */
+    score?: number | null;
+    notes?: string | null;
+}
+export interface UpdateStatsResult {
+    model: PersonalityModel;
+    key: string;
+    entry: PersonalityStats;
+}
+/**
+ * 把一轮结果回写到对应人格桶 (v1 updatePersonalityStats 的纯函数版):
+ *  - success/fail 计数 +1
+ *  - avgScore 增量更新 (仅当给了 score): avg += (s-avg)/n
+ *  - history 追加一条 (含 outcome/score/notes)
+ * 返回新 model (不落盘 —— 调用方用 store.save 持久化, 或 applyStatsUpdate 一步到位).
+ */
+export declare function updatePersonalityStats(model: PersonalityModel, input: UpdateStatsInput, at: string): UpdateStatsResult;

package/dist/personality/stats.js

@@ -0,0 +1,82 @@
+import { clamp01, normalizePersonalityState, personalityKey, } from './schema.js';
+/**
+ * 人格适应度 + 统计回写 (v1 personalityScore / chooseBestKnownPersonality / updatePersonalityStats 端口).
+ * 自然选择的"适者"由这里的分数决定; 每轮结果回写到对应人格桶, 供下一轮选择.
+ */
+/** 一个桶要参与"最佳已知"竞争的最小样本数 (v1: total<3 不计). */
+export const MIN_SAMPLES_FOR_BEST = 3;
+/** 样本权重饱和点 (v1: min(1, total/8)). */
+export const SAMPLE_WEIGHT_FULL_AT = 8;
+/**
+ * 桶适应度分数 (v1 personalityScore):
+ *  - Laplace 平滑成功率 p = (succ+1)/(total+2)  → 主导 (权重 0.75)
+ *  - 质量代理 q = avgScore, 但乘 sampleWeight 惩罚小样本过度自信 (权重 0.25)
+ */
+export function personalityScore(entry) {
+    const succ = Number(entry?.success) || 0;
+    const fail = Number(entry?.fail) || 0;
+    const total = succ + fail;
+    const p = (succ + 1) / (total + 2);
+    const sampleWeight = Math.min(1, total / SAMPLE_WEIGHT_FULL_AT);
+    const avg = entry?.avgScore;
+    const q = Number.isFinite(Number(avg)) ? clamp01(Number(avg)) : 0.5;
+    return p * 0.75 + q * 0.25 * sampleWeight;
+}
+/**
+ * 选出"最佳已知"人格桶 (v1 chooseBestKnownPersonality): 只在样本≥MIN_SAMPLES_FOR_BEST 的桶里比 personalityScore.
+ * 没有够样本的桶 ⇒ null (选择阶段就不做自然选择微调).
+ */
+export function chooseBestKnownPersonality(stats) {
+    let best = null;
+    for (const [key, entry] of Object.entries(stats ?? {})) {
+        const total = (Number(entry?.success) || 0) + (Number(entry?.fail) || 0);
+        if (total < MIN_SAMPLES_FOR_BEST)
+            continue;
+        const score = personalityScore(entry);
+        if (!best || score > best.score)
+            best = { key, score, entry };
+    }
+    return best;
+}
+/**
+ * 把一轮结果回写到对应人格桶 (v1 updatePersonalityStats 的纯函数版):
+ *  - success/fail 计数 +1
+ *  - avgScore 增量更新 (仅当给了 score): avg += (s-avg)/n
+ *  - history 追加一条 (含 outcome/score/notes)
+ * 返回新 model (不落盘 —— 调用方用 store.save 持久化, 或 applyStatsUpdate 一步到位).
+ */
+export function updatePersonalityStats(model, input, at) {
+    const st = normalizePersonalityState(input.personality ?? model.current);
+    const key = personalityKey(st);
+    const prev = model.stats[key];
+    const entry = prev
+        ? { ...prev }
+        : { success: 0, fail: 0, avgScore: 0.5, n: 0, updatedAt: null };
+    const outcome = String(input.outcome ?? '').toLowerCase();
+    if (outcome === 'success')
+        entry.success += 1;
+    else if (outcome === 'failed')
+        entry.fail += 1;
+    const sc = input.score == null ? null : (Number.isFinite(Number(input.score)) ? clamp01(Number(input.score)) : null);
+    if (sc != null) {
+        const n = entry.n + 1;
+        entry.avgScore = entry.avgScore + (sc - entry.avgScore) / n;
+        entry.n = n;
+    }
+    entry.updatedAt = at;
+    const nextStats = { ...model.stats, [key]: entry };
+    const historyEntry = {
+        at,
+        key,
+        outcome: outcome === 'success' || outcome === 'failed' ? outcome : 'unknown',
+        score: sc,
+        notes: input.notes ? String(input.notes).slice(0, 220) : null,
+    };
+    // v1 parity: 回写只动 stats + history, 不改 model.current —— current 由 select/pivot 决定, 记账不该挪它.
+    const nextModel = {
+        ...model,
+        stats: nextStats,
+        history: [...model.history, historyEntry],
+    };
+    return { model: nextModel, key, entry };
+}

package/dist/personality/store.d.ts

@@ -0,0 +1,35 @@
+import { personalityStatePath } from '../events/paths.js';
+import { type PersonalityModel, type PersonalityState } from './schema.js';
+/** history 上限 (v1 slice(-120) 同值; 防文件无界增长). */
+export declare const HISTORY_LIMIT = 120;
+/** 全新默认模型 (无持久文件时的种子). */
+export declare function defaultPersonalityModel(now?: () => number): PersonalityModel;
+export interface PersonalityStoreOptions {
+    /** 覆盖持久化路径 (测试注入; 缺省走 personalityStatePath()). */
+    path?: string;
+    /** 可注入时钟 (确定性测试). */
+    now?: () => number;
+}
+/**
+ * 可进化人格模型的持久化 (v1 loadPersonalityModel / savePersonalityModel 端口).
+ * - load: 缺失/空/损坏文件 → 回落默认模型 (绝不抛; 人格是软状态, 读坏不该崩进化循环)
+ * - save: tmp+rename 原子替换, 跨进程 O_EXCL 锁串行化 (对齐 EventStore / localJsonl 的写法)
+ * current 恒被 normalize 到合法五维, stats/history 恒是合法形状.
+ */
+export declare class PersonalityStore {
+    readonly path: string;
+    private readonly lockPath;
+    private readonly now;
+    constructor(opts?: PersonalityStoreOptions);
+    /** 读模型; 任何 I/O 或校验失败都回落默认 (不抛). */
+    load(): PersonalityModel;
+    /** 原子落盘 (规范化 + history 截断 + 刷 updatedAt). 返回实际写入的模型. */
+    save(model: PersonalityModel): PersonalityModel;
+    /** 读当前人格 (便捷). */
+    currentState(): PersonalityState;
+    /** 桶键 (便捷). */
+    currentKey(): string;
+    /** 当前时间的 ISO 串 (走注入时钟) —— 供进化算子给 stats/history/事件打时间戳. */
+    nowIso(): string;
+}
+export { personalityStatePath };