pi-proactive 0.0.0-stage → 0.2.0-beta.2

package/build/src/lineage.js

@@ -0,0 +1,426 @@
+/**
+ * 统一事件流（血缘）：把「为什么触发」（因）与「结果如何」（果）落到**一个**只追加的 JSONL。
+ *
+ * 落盘位置：`<agentDir>/proactive/lineage/<agentSegment(agentId)>.jsonl`（**每 agent 一份**，
+ * 目录约定与既有落盘面一致：邮箱 / 线程 / 任务表都在 `<agentDir>/proactive/` 下）。
+ *
+ * 设计要点：
+ * - **只追加**：`appendFileSync` 单次写（行长 < PIPE_BUF 视为原子追加）→ 没有读-改-写窗口；
+ * - **读方容错**：坏行 / 半截行跳过并计数（沿用 `src/thread.ts` 的既有做法），绝不抛错；
+ * - **不泄露正文**：事件里只有 id / 长度 / 摘要（sha256 前 12 位）——**没有 prompt 全文**；
+ * - **判定可复核**：outcome 只由事件流里已有的机器事实推出（投递事件 + 窗口内的回应事件），
+ *   不引入任何主观标记。
+ *
+ * 事件类型：
+ * - `triggered`：判定通过、决定触发（带 cause 与**判定依据**：阈值 / 档位 / 已空闲时长）；
+ * - `delivered`：投递完成（`result` = delivered / notified / failed）；
+ * - `dropped`：被护栏拦下（`reason` = defer / drop / ...）；
+ * - `answered`：投递后有回应（`responder` = model / user，带耗时）；
+ * - `outcome`：结果记账（`result` = adopted / user-replied / ignored / failed）。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { agentSegment } from "./envelope.js";
+import { PROACTIVE_FILE_MODE, chmodQuiet, ensureDir } from "./config.js";
+/** 判定窗口的默认值：5 分钟。 */
+export const DEFAULT_OUTCOME_WINDOW_MS = 300_000;
+/** 判定窗口的环境变量覆盖（可配）。 */
+export const OUTCOME_WINDOW_ENV = "PI_PROACTIVE_OUTCOME_WINDOW_MS";
+/** 正文摘要（sha256 前 12 位）——**摘要不是正文**：不含任何正文字符。 */
+export function digestOf(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 12);
+}
+/** 判断一行是否为合法事件（坏行 → 跳过，不抛错）。 */
+function isLineageEvent(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const e = value;
+    if (typeof e.ts !== "number" || !Number.isFinite(e.ts))
+        return false;
+    if (typeof e.id !== "string" || e.id === "")
+        return false;
+    if (typeof e.type !== "string")
+        return false;
+    if (e.type !== "triggered" && e.type !== "delivered" && e.type !== "answered" && e.type !== "outcome" && e.type !== "dropped" && e.type !== "decision") {
+        return false;
+    }
+    if (e.cause !== "idle" && e.cause !== "schedule" && e.cause !== "peer-request" && e.cause !== "manual")
+        return false;
+    return true;
+}
+/** 从环境变量读判定窗口（非法值 → 缺省）。 */
+function windowFromEnv() {
+    const raw = process.env[OUTCOME_WINDOW_ENV];
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/**
+ * 统一事件流（血缘）。
+ *
+ * 用法：
+ * - 触发方（`src/trigger.ts`）：`noteTriggered` → `noteDelivery` / `noteDropped`；
+ * - 观察方（扩展入口）：`noteResponse`（模型/用户有回应）→ `sweep`（窗口末结算 ignored）；
+ * - 人侧（`/proactive history`）：`history` + `formatLineageHistory`。
+ */
+export class Lineage {
+    agentDir;
+    agentId;
+    now;
+    windowMsValue;
+    /** 已投递但尚未结算的窗口（按投递时刻升序）。 */
+    openWindows = [];
+    /**
+     * 上一条决策记录的**状态键**（`决策|原因`）。
+     *
+     * 为什么要去重：空闲判定每秒跑一次 → 同一个决策状态会连续命中几百次 →
+     * 每次都落一条会把事件流淹掉（一天 8 万条）。
+     * ⇒ **同一状态只记一条**（状态一变就再记一条）→ 事件流里看到的是「决策变迁」，而不是噪声。
+     */
+    lastDecisionKey;
+    constructor(opts) {
+        this.agentDir = opts.agentDir;
+        this.agentId = opts.agentId;
+        this.now = opts.now ?? Date.now;
+        this.windowMsValue = opts.windowMs ?? windowFromEnv() ?? DEFAULT_OUTCOME_WINDOW_MS;
+    }
+    /** 判定窗口（毫秒）。 */
+    get windowMs() {
+        return this.windowMsValue;
+    }
+    /** 事件流文件绝对路径。 */
+    path() {
+        return path.join(this.agentDir, "proactive", "lineage", `${agentSegment(this.agentId)}.jsonl`);
+    }
+    // ---- 写入 ----
+    /**
+     * 追加一条事件（**只追加**：单次 write，行尾补 `\n`）。
+     *
+     * 追加的半截行由读方跳过（坏行计数），不隔离文件、绝不抛错。
+     */
+    append(input) {
+        const event = {
+            ...input,
+            ts: input.ts ?? this.now(),
+            id: randomUUID(),
+            agentId: this.agentId,
+        };
+        const file = this.path();
+        try {
+            ensureDir(path.dirname(file));
+        }
+        catch {
+            // 目录建不出来时下面写会失败；不抛裸异常，交由宿主兜底
+        }
+        try {
+            fs.appendFileSync(file, `${JSON.stringify(event)}\n`, "utf8");
+            // 事件流属「同机其它进程不该读」的落盘面 → 0600。
+            chmodQuiet(file, PROACTIVE_FILE_MODE);
+        }
+        catch (err) {
+            console.error("[proactive] 事件流追加失败", err);
+        }
+        return event;
+    }
+    /** 记一次「触发」（因）：cause + 判定依据。 */
+    noteTriggered(info) {
+        return this.append({
+            type: "triggered",
+            cause: info.cause,
+            ...(info.envelopeId !== undefined ? { envelopeId: info.envelopeId } : {}),
+            ...(info.taskId !== undefined ? { taskId: info.taskId } : {}),
+            ...(info.peer !== undefined ? { peer: info.peer } : {}),
+            ...(info.basis !== undefined ? { basis: info.basis } : {}),
+            ...(info.bodyLen !== undefined ? { bodyLen: info.bodyLen } : {}),
+            ...(info.bodyDigest !== undefined ? { bodyDigest: info.bodyDigest } : {}),
+        });
+    }
+    /**
+     * 记一次「投递完成」。
+     *
+     * - `result === "delivered"` → **开一个判定窗口**（等回应）；
+     * - `result === "failed"` → **立即**记 `outcome=failed`（不等窗口）；
+     * - 其余（notified / deferred / dropped）→ 只记事实，不开窗口、不记 outcome。
+     */
+    noteDelivery(info) {
+        const event = this.append({
+            type: "delivered",
+            cause: info.cause,
+            result: info.result,
+            ...(info.envelopeId !== undefined ? { envelopeId: info.envelopeId } : {}),
+            ...(info.taskId !== undefined ? { taskId: info.taskId } : {}),
+            ...(info.peer !== undefined ? { peer: info.peer } : {}),
+            ...(info.basis !== undefined ? { basis: info.basis } : {}),
+            ...(info.bodyLen !== undefined ? { bodyLen: info.bodyLen } : {}),
+            ...(info.bodyDigest !== undefined ? { bodyDigest: info.bodyDigest } : {}),
+            ...(info.reason !== undefined ? { reason: info.reason } : {}),
+        });
+        if (info.result === "delivered") {
+            this.openWindows.push({
+                eventId: event.id,
+                envelopeId: info.envelopeId,
+                cause: info.cause,
+                peer: info.peer,
+                taskId: info.taskId,
+                deliveredAt: event.ts,
+            });
+        }
+        else if (info.result === "failed") {
+            this.append({
+                type: "outcome",
+                cause: info.cause,
+                result: "failed",
+                refEventId: event.id,
+                ...(info.envelopeId !== undefined ? { envelopeId: info.envelopeId } : {}),
+                ...(info.peer !== undefined ? { peer: info.peer } : {}),
+                ...(info.reason !== undefined ? { reason: info.reason } : {}),
+            });
+        }
+        return event;
+    }
+    /** 记一次「被拦下」（护栏 / 前置条件）：带原因。 */
+    noteDropped(info) {
+        return this.append({
+            type: "dropped",
+            cause: info.cause,
+            reason: info.reason,
+            ...(info.envelopeId !== undefined ? { envelopeId: info.envelopeId } : {}),
+            ...(info.taskId !== undefined ? { taskId: info.taskId } : {}),
+            ...(info.peer !== undefined ? { peer: info.peer } : {}),
+            ...(info.basis !== undefined ? { basis: info.basis } : {}),
+        });
+    }
+    /**
+     * 记一次**决策**（决策环）：分数 / 三个分量 / 阈值 / 决策 / 归因（为什么现在 · 为什么这个动作 · 代价多少）。
+     *
+     * **不触发也要记账** —— 否则无法回答「为什么它没理我」。
+     *
+     * 去重：**同一决策状态**（`决策|原因`）只落一条（状态变迁才再记）→ 1s tick 不会淹没事件流。
+     *
+     * @returns 落盘的事件；被去重时返回 `undefined`。
+     */
+    noteDecision(info) {
+        const key = `${info.cause}|${info.decision.decision}|${info.decision.reason}`;
+        if (key === this.lastDecisionKey)
+            return undefined;
+        this.lastDecisionKey = key;
+        return this.append({
+            type: "decision",
+            cause: info.cause,
+            decision: info.decision,
+        });
+    }
+    /**
+     * 记一次「回应」（窗口内的事实）。
+     *
+     * 归因规则（**可复核**：只认事件流里的时间戳）：
+     * - 取**最近一次**已投递且窗口未过期的投递（模型回合紧随其后产生的那条注入）；
+     * - 先到者胜（用户先回 → user-replied；模型先动 → adopted）——同一投递只结算一次。
+     *
+     * 窗口外的事实**不得**用来结算（返回 undefined，什么都不记）。
+     */
+    noteResponse(responder, ts) {
+        const at = ts ?? this.now();
+        let idx = -1;
+        for (let i = this.openWindows.length - 1; i >= 0; i -= 1) {
+            const w = this.openWindows[i];
+            if (at >= w.deliveredAt && at - w.deliveredAt <= this.windowMsValue) {
+                idx = i;
+                break;
+            }
+        }
+        if (idx < 0)
+            return undefined;
+        const win = this.openWindows[idx];
+        this.openWindows.splice(idx, 1);
+        const durationMs = at - win.deliveredAt;
+        const answered = this.append({
+            type: "answered",
+            cause: win.cause,
+            responder,
+            durationMs,
+            refEventId: win.eventId,
+            ...(win.envelopeId !== undefined ? { envelopeId: win.envelopeId } : {}),
+            ...(win.peer !== undefined ? { peer: win.peer } : {}),
+            ...(win.taskId !== undefined ? { taskId: win.taskId } : {}),
+        });
+        this.append({
+            type: "outcome",
+            cause: win.cause,
+            result: responder === "model" ? "adopted" : "user-replied",
+            durationMs,
+            refEventId: answered.id,
+            ...(win.envelopeId !== undefined ? { envelopeId: win.envelopeId } : {}),
+            ...(win.peer !== undefined ? { peer: win.peer } : {}),
+            ...(win.taskId !== undefined ? { taskId: win.taskId } : {}),
+        });
+        return answered;
+    }
+    /**
+     * 结算窗口：把**到期且无回应**的投递结算为 `outcome=ignored`。
+     *
+     * 只用**时间**这一机器事实判定（窗口末仍无回应事件）→ 判定可由事件流复核。
+     */
+    sweep(now) {
+        const at = now ?? this.now();
+        const settled = [];
+        for (let i = this.openWindows.length - 1; i >= 0; i -= 1) {
+            const win = this.openWindows[i];
+            if (at - win.deliveredAt < this.windowMsValue)
+                continue;
+            this.openWindows.splice(i, 1);
+            settled.push(this.append({
+                type: "outcome",
+                cause: win.cause,
+                result: "ignored",
+                durationMs: at - win.deliveredAt,
+                refEventId: win.eventId,
+                ...(win.envelopeId !== undefined ? { envelopeId: win.envelopeId } : {}),
+                ...(win.peer !== undefined ? { peer: win.peer } : {}),
+                ...(win.taskId !== undefined ? { taskId: win.taskId } : {}),
+            }));
+        }
+        settled.reverse();
+        return settled;
+    }
+    /** 未结算的窗口数（供自检 / 状态展示）。 */
+    pendingWindows() {
+        return this.openWindows.length;
+    }
+    // ---- 读取 ----
+    /** 读盘并解析；文件缺失/读失败 → 空列表；坏行跳过并计数（绝不抛出）。 */
+    read(limit) {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path(), "utf8");
+        }
+        catch {
+            return { events: [], stale: 0 };
+        }
+        const events = [];
+        let stale = 0;
+        for (const line of raw.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                stale++;
+                continue;
+            }
+            if (!isLineageEvent(parsed)) {
+                stale++;
+                continue;
+            }
+            events.push(parsed);
+        }
+        if (limit !== undefined && limit >= 0 && events.length > limit) {
+            return { events: events.slice(events.length - limit), stale };
+        }
+        return { events, stale };
+    }
+    /** 按条件取事件（时间序；`limit` 取最近 N 条）。 */
+    history(filter = {}) {
+        const all = this.read().events;
+        let events = all;
+        if (filter.scope === "peer") {
+            events = events.filter((e) => e.peer !== undefined || e.cause === "peer-request");
+        }
+        else if (filter.scope === "me") {
+            events = events.filter((e) => e.cause !== "peer-request");
+        }
+        if (filter.peer !== undefined) {
+            events = events.filter((e) => e.peer === filter.peer);
+        }
+        if (filter.limit !== undefined && filter.limit >= 0 && events.length > filter.limit) {
+            return events.slice(events.length - filter.limit);
+        }
+        return events;
+    }
+    /** 坏行计数（供审计）。 */
+    staleLines() {
+        return this.read().stale;
+    }
+}
+/** 毫秒 → `MM-DD HH:mm:ss`（本地时区）。 */
+function formatEventTime(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** 分数 → 最多 3 位小数（展示用；**不改**落盘值）。 */
+function round3(n) {
+    return Math.round(n * 1000) / 1000;
+}
+/** 毫秒 → `1h2m3s`（短格式）。 */
+function formatShortDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m${s % 60}s`;
+    return `${Math.floor(m / 60)}h${m % 60}m`;
+}
+/**
+ * `/proactive history` 的展示文本：每行 = 时间 / 类型 / cause / 关键 id / 结果。
+ */
+export function formatLineageHistory(events) {
+    if (events.length === 0)
+        return "最近事件：暂无记录";
+    const lines = [`最近事件 ${events.length} 条：`];
+    for (const e of events) {
+        const ids = [];
+        if (e.envelopeId !== undefined)
+            ids.push(`env=${e.envelopeId}`);
+        if (e.taskId !== undefined)
+            ids.push(`task=${e.taskId}`);
+        if (e.peer !== undefined)
+            ids.push(`peer=${e.peer}`);
+        ids.push(`ev=${e.id.slice(0, 8)}`);
+        const detail = [];
+        if (e.type === "triggered" && e.basis !== undefined) {
+            const b = e.basis;
+            if (b.idleForMs !== undefined)
+                detail.push(`空闲=${formatShortDuration(b.idleForMs)}`);
+            if (b.thresholdMs !== undefined)
+                detail.push(`阈值=${formatShortDuration(b.thresholdMs)}`);
+            if (b.detect !== undefined)
+                detail.push(`档位=${b.detect}`);
+            if (b.dueAt !== undefined)
+                detail.push(`到期=${formatEventTime(b.dueAt)}`);
+            if (b.intervalMs !== undefined)
+                detail.push(`周期=${formatShortDuration(b.intervalMs)}`);
+        }
+        if (e.type === "decision" && e.decision !== undefined) {
+            const d = e.decision;
+            detail.push(`决策=${d.decision}`);
+            detail.push(`分数=${round3(d.score)}`);
+            detail.push(`价值=${round3(d.value)}`);
+            detail.push(`紧急=${round3(d.urgency)}`);
+            detail.push(`代价=${round3(d.interruptionCost)}`);
+            detail.push(`阈值=${round3(d.threshold)}`);
+            detail.push(`原因=${d.reason}`);
+        }
+        if (e.type === "delivered" && e.result !== undefined)
+            detail.push(`结果=${e.result}`);
+        if (e.type === "dropped" && e.reason !== undefined)
+            detail.push(`原因=${e.reason}`);
+        if (e.type === "answered") {
+            detail.push(`回应=${e.responder ?? "?"}`);
+            if (e.durationMs !== undefined)
+                detail.push(`耗时=${formatShortDuration(e.durationMs)}`);
+        }
+        if (e.type === "outcome") {
+            detail.push(`结果=${e.result ?? "?"}`);
+            if (e.durationMs !== undefined)
+                detail.push(`耗时=${formatShortDuration(e.durationMs)}`);
+        }
+        lines.push(`${formatEventTime(e.ts)}  ${e.type.padEnd(9)}  ${e.cause.padEnd(12)}  ${ids.join(" ")}  ${detail.join(" ")}`.trimEnd());
+    }
+    return lines.join("\n");
+}