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

package/build/src/trust-loop.js

@@ -0,0 +1,321 @@
+/**
+ * 目标驱动与自主推进的**执行环**（卡 D6 / D7）+ 人机分工（卡 D3）。
+ *
+ * 同一套循环，三档自主度（`docs/product/agentic-loop.md` §1）：
+ * ```
+ * 目标 → 候选行动 → 打分(DECIDE1) → 执行 → 结账(带归因) → 回灌目标进度
+ * 自主档位：L-B 托付（条件由用户给） / L-C 目标驱动（条件由 AI 推导）
+ *          / L-D 自主推进（目标由 AI 从账本的未竟事项里发现）
+ * ```
+ *
+ * **六条必要前提**（缺一即不得进入自主推进，`docs/product/agentic-loop.md` §2）：
+ * ```
+ * ① 目标可判定  ② 预算硬上限  ③ 权限阶梯
+ * ④ 可中止可撤销 ⑤ 可追溯      ⑥ 不越界（范围外显式请求授权）
+ * ```
+ *
+ * 红线（§6）：
+ * - 不得替人做**需要担责**的决定 → 不可逆 / 对外 / 价值取舍 → 一律 **human-gated**；
+ * - 不得**假装完成** → 未达成的目标必须显式产出「未达成 / 需人决策」记录，**不得静默结账**；
+ * - 不得在目标外动手 → 范围外 → 产出**显式请求授权**的记录（不是自动执行）。
+ *
+ * @capability: trust-loop
+ * @observable: pi-proactive/src/trust-loop.ts:advanceCandidate
+ * @attribution: pi-proactive/src/trust-loop.ts:advanceCandidate
+ * @outcome: pi-proactive/src/trust-metrics.ts:TrustMetrics
+ * @checked: test:pi-proactive/tests/trust-loop.test.ts#D6-3 执行 → 结账带归因
+ */
+import { scoreDecision } from "./idle.js";
+import { goalGap, goalSatisfied, isDecidable, } from "./trust-registry.js";
+/**
+ * 权限阶梯（护栏③）：**人的经历有效** → 需要担责的决定必须回到人手里。
+ *
+ * - `read` / `write`（可撤销）→ AI 可自主做；
+ * - `external`（对外承诺）/ `irreversible`（不可逆）/ `value-judgment`（取舍与价值排序）
+ *   → **human-gated**：只能生成待人决策的记录，**不得自动执行**。
+ */
+export function resolvePermissionTier(actionType) {
+    switch (actionType) {
+        case "read":
+            return "auto";
+        case "write":
+            return "limited";
+        default:
+            return "human-gated";
+    }
+}
+/** 六条护栏（缺一即不得进入自主推进）。 */
+export const GUARDRAILS = [
+    "goal-decidable",
+    "budget-cap",
+    "permission-ladder",
+    "abortable-revocable",
+    "traceable",
+    "in-scope",
+];
+/**
+ * 六条护栏的判定（纯函数）。
+ *
+ * @param budgetAvailable 预算是否还有余额（由调用方用登记册的预算账本判定）。
+ */
+export function checkGuardrails(goal, candidate, budgetAvailable) {
+    const violations = [];
+    if (!isDecidable(goal))
+        violations.push({ rule: "goal-decidable", detail: "目标缺可判定的完成定义" });
+    if (!budgetAvailable || goal.budget.maxActions <= goal.budget.usedActions) {
+        violations.push({ rule: "budget-cap", detail: `预算已用尽（${goal.budget.usedActions}/${goal.budget.maxActions}）` });
+    }
+    const expected = resolvePermissionTier(candidate.actionType);
+    if (candidate.permission !== expected) {
+        violations.push({ rule: "permission-ladder", detail: `权限档与动作种类不符（${candidate.permission} ≠ ${expected}）` });
+    }
+    if (goal.permission === "human-gated" && candidate.permission !== "human-gated") {
+        violations.push({ rule: "permission-ladder", detail: "目标整体要求 human-gated" });
+    }
+    if (!candidate.reversible && candidate.permission !== "human-gated") {
+        violations.push({ rule: "abortable-revocable", detail: "不可撤销的动作不得自主执行" });
+    }
+    if (candidate.reason.trim() === "" || candidate.goalId === "") {
+        violations.push({ rule: "traceable", detail: "缺归因（为什么做 / 让哪个目标更近）" });
+    }
+    if (goal.scope.length > 0 && !goal.scope.includes(candidate.scope)) {
+        violations.push({ rule: "in-scope", detail: `范围外（${candidate.scope} ∉ ${goal.scope.join("/")}）` });
+    }
+    return { ok: violations.length === 0, violations };
+}
+/**
+ * 由**目标差距**推导候选行动（卡 D6 的「候选」步）。
+ *
+ * - 完成定义缺失 → **没有候选**（不可判定的目标不许推进）；
+ * - 清单型 → 每个未完成项一个候选；指标型 → 一个候选（把指标推向目标值）。
+ */
+export function deriveCandidates(goal, opts = {}) {
+    if (!isDecidable(goal))
+        return [];
+    const threshold = opts.threshold ?? 1;
+    const observeRatio = opts.observeRatio ?? 0.5;
+    const actionType = opts.actionType ?? "write";
+    const gap = goalGap(goal);
+    const scope = goal.scope[0] ?? goal.id;
+    const value = gap.ratio;
+    const urgency = 1;
+    const interruptionCost = 1;
+    const scoring = scoreDecision({
+        value: { score: value, source: "trust-loop: goalGap.ratio" },
+        urgency: { score: urgency, source: "trust-loop: goal.open" },
+        interruptionCost: { score: interruptionCost, source: "trust-loop: default" },
+    }, threshold, observeRatio);
+    const base = {
+        goalId: goal.id,
+        actionType,
+        permission: resolvePermissionTier(actionType),
+        scope,
+        reversible: true,
+        value,
+        valueSource: "trust-loop: goalGap.ratio",
+        urgency,
+        urgencySource: "trust-loop: goal.open",
+        interruptionCost,
+        interruptionCostSource: "trust-loop: default",
+        score: scoring.score,
+        band: scoring.band,
+    };
+    if (goal.doneWhen?.type === "checklist") {
+        return goal.doneWhen.items
+            .filter((i) => !i.done)
+            .map((item) => ({
+            ...base,
+            id: `${goal.id}#${item.id}`,
+            action: item.text,
+            reason: `目标「${goal.title}」尚差：${item.text}（差距 ${gap.remaining}/${gap.total}）`,
+        }));
+    }
+    const metric = goal.doneWhen;
+    return [
+        {
+            ...base,
+            id: `${goal.id}#metric`,
+            action: `${metric.name} → ${metric.op} ${metric.target}`,
+            reason: `目标「${goal.title}」的 ${metric.name} 当前 ${metric.current}，目标 ${metric.op} ${metric.target}`,
+        },
+    ];
+}
+/**
+ * 推进一个候选行动（卡 D6 的「执行 → 结账」，卡 D7 的护栏）。
+ *
+ * 判定顺序（**顺序本身就是语义**）：
+ * 1. 目标不存在 → failed（不静默）；
+ * 2. 六条护栏 → 有违规 → blocked（**显式记录**，不执行）；
+ * 3. 权限档 = human-gated → human-gated（**不执行、不结账**，产出待人决策记录）；
+ * 4. 消耗预算（硬上限）→ 不足 → blocked；
+ * 5. 执行 → 失败 → failed（**不静默结账**）；
+ * 6. 成功 → 结账：写归因（让哪个目标前进了多少）→ 回灌进度；
+ *    目标仍**未达成** → 显式产出「未达成」记录（**不得静默结账**）。
+ */
+export async function advanceCandidate(deps, candidate) {
+    if (candidate.entrustmentId !== undefined) {
+        // 托付路径：自主推进发现的「未闭合待办」→ 走托付的知会/结账流程。
+        const e = deps.registry.getEntrustment(candidate.entrustmentId);
+        if (e === undefined) {
+            deps.lineage?.noteTrust({ stage: "blocked", entrustmentId: candidate.entrustmentId, reason: "entrustment-not-found" });
+            return { result: "failed", candidate, reason: "托付不存在" };
+        }
+        if (e.needsHuman === true) {
+            const reason = e.humanReason ?? "需要人决定";
+            deps.registry.markNeedsHuman(e.id, reason);
+            deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId: e.id, goalId: e.goalId, reason });
+            return { result: "human-gated", candidate, reason };
+        }
+        if (e.status !== "arrived" && e.status !== "notified") {
+            const reason = `托付尚未到达（${e.status}）→ 不结账`;
+            deps.lineage?.noteTrust({ stage: "blocked", entrustmentId: e.id, goalId: e.goalId, reason });
+            return { result: "blocked", candidate, violations: [{ rule: "goal-decidable", detail: reason }] };
+        }
+        const closed = closeEntrustment(deps, e.id);
+        if (closed.result === "human-gated") {
+            return { result: "human-gated", candidate, reason: closed.reason ?? "需人决定" };
+        }
+        return { result: "settled", candidate, attribution: { goalId: e.goalId ?? "", progressDelta: 1 } };
+    }
+    const goal = deps.registry.getGoal(candidate.goalId);
+    if (goal === undefined) {
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: candidate.goalId, reason: "goal-not-found" });
+        return { result: "failed", candidate, reason: "目标不存在" };
+    }
+    const budgetAvailable = goal.budget.usedActions < goal.budget.maxActions;
+    const report = checkGuardrails(goal, candidate, budgetAvailable);
+    if (!report.ok) {
+        const detail = report.violations.map((v) => `${v.rule}:${v.detail}`).join("；");
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason: detail });
+        // 范围外 / 不可判定 → 显式请求授权或人决策（**不是**自动执行）。
+        if (report.violations.some((v) => v.rule === "in-scope" || v.rule === "goal-decidable")) {
+            deps.registry.setGoalStatus(goal.id, "needs-human", `需要人授权或补充定义：${detail}`);
+        }
+        return { result: "blocked", candidate, violations: report.violations };
+    }
+    if (candidate.permission === "human-gated") {
+        const reason = `该动作需人担责（${candidate.actionType}）→ 不自动执行`;
+        deps.registry.setGoalStatus(goal.id, "needs-human", reason);
+        deps.lineage?.noteTrust({ stage: "human-gated", goalId: goal.id, reason });
+        return { result: "human-gated", candidate, reason };
+    }
+    if (!deps.registry.consumeBudget(goal.id)) {
+        const detail = `预算硬上限已到（${goal.budget.usedActions}/${goal.budget.maxActions}）`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason: detail });
+        return { result: "blocked", candidate, violations: [{ rule: "budget-cap", detail }] };
+    }
+    let result;
+    try {
+        result = deps.execute !== undefined ? await deps.execute(candidate) : { ok: true, progressDelta: 1 };
+    }
+    catch (err) {
+        const reason = `执行异常：${err instanceof Error ? err.message : String(err)}`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason });
+        return { result: "failed", candidate, reason };
+    }
+    if (!result.ok) {
+        const reason = `执行未成功：${result.result ?? "未说明"}`;
+        deps.lineage?.noteTrust({ stage: "blocked", goalId: goal.id, reason });
+        return { result: "failed", candidate, reason };
+    }
+    const delta = result.progressDelta ?? 1;
+    deps.registry.recordProgress(goal.id, delta);
+    deps.lineage?.noteTrust({ stage: "progress", goalId: goal.id, progressDelta: delta });
+    const after = deps.registry.getGoal(goal.id);
+    const satisfied = after !== undefined && goalSatisfied(after);
+    if (satisfied && after !== undefined) {
+        deps.registry.setGoalStatus(after.id, "achieved");
+        deps.lineage?.noteTrust({ stage: "progress", goalId: after.id, progressDelta: delta, reason: "goal-achieved" });
+    }
+    else {
+        // **未达成不得静默结账**：显式记一条「仍未达成」。
+        deps.lineage?.noteTrust({ stage: "progress", goalId: goal.id, progressDelta: delta, reason: "goal-not-satisfied" });
+    }
+    return { result: "settled", candidate, attribution: { goalId: goal.id, progressDelta: delta } };
+}
+/**
+ * 登记一条托付并落 `registered` 事件（**登记与账本同一处** → 不会漏段）。
+ */
+export function openEntrustment(deps, input) {
+    const e = deps.registry.registerEntrustment(input);
+    deps.lineage?.noteTrust({ stage: "registered", entrustmentId: e.id, goalId: e.goalId });
+    return e;
+}
+/**
+ * 托付到达（第二段）：状态迁移 + `arrived` 事件（同一处 → 不会漏段）。
+ */
+export function arriveEntrustment(deps, entrustmentId) {
+    const e = deps.registry.markArrived(entrustmentId);
+    if (e === undefined)
+        return undefined;
+    deps.lineage?.noteTrust({ stage: "arrived", entrustmentId: e.id, goalId: e.goalId });
+    return e;
+}
+/** 托付条件的判定（**可判定**：到点 / 状态命中）。 */
+export function evaluateEntrustmentCondition(entrustment, now, state) {
+    const c = entrustment.condition;
+    if (c.type === "at")
+        return now >= c.dueAt;
+    if (state === undefined)
+        return false;
+    return state[c.key] === c.equals;
+}
+/**
+ * 关闭一条托付（**结账**；卡 D3：需要人决定的不得自动结账）。
+ *
+ * - `needsHuman` → 产出 human-gated 记录，**不结账**；
+ * - 否则 → 结账 + 落 `settled` 事件。
+ */
+export function closeEntrustment(deps, entrustmentId) {
+    const e = deps.registry.getEntrustment(entrustmentId);
+    if (e === undefined)
+        return { result: "human-gated", reason: "托付不存在" };
+    if (e.needsHuman === true) {
+        const reason = e.humanReason ?? "需要人决定";
+        deps.registry.markNeedsHuman(entrustmentId, reason);
+        deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId, goalId: e.goalId, reason });
+        return { result: "human-gated", reason };
+    }
+    const settled = deps.registry.settle(entrustmentId);
+    if (settled === undefined) {
+        const reason = `托付当前状态不可结账（${e.status}）`;
+        deps.lineage?.noteTrust({ stage: "blocked", entrustmentId, goalId: e.goalId, reason });
+        return { result: "human-gated", reason };
+    }
+    deps.lineage?.noteTrust({ stage: "settled", entrustmentId, goalId: e.goalId });
+    return { result: "settled" };
+}
+/**
+ * 自主推进的**下一步发现**（卡 D7 的 L-D）。
+ *
+ * 来源：**未竟目标**（登记册里 `open` 的目标）与**未闭合待办**（未闭合的托付）。
+ * 不是凭空生成 —— 每个候选都能指回一条账本记录。
+ */
+export function discoverNextCandidates(deps, opts = {}) {
+    const out = [];
+    for (const goal of deps.registry.listOpenGoals()) {
+        out.push(...deriveCandidates(goal, opts));
+    }
+    for (const e of deps.registry.listUnclosedEntrustments()) {
+        out.push({
+            id: `${e.id}#close`,
+            entrustmentId: e.id,
+            goalId: e.goalId ?? "",
+            action: `处理未闭合托付：${e.target}`,
+            actionType: "write",
+            permission: resolvePermissionTier("write"),
+            scope: e.id,
+            reversible: true,
+            value: 1,
+            valueSource: "trust-loop: unclosed-entrustment",
+            urgency: 1,
+            urgencySource: "trust-loop: unclosed-entrustment",
+            interruptionCost: 1,
+            interruptionCostSource: "trust-loop: default",
+            score: 1,
+            band: "trigger",
+            reason: `账本里有一条未闭合托付：${e.target}（${e.status}）`,
+        });
+    }
+    return out;
+}

package/build/src/trust-metrics.js

@@ -0,0 +1,236 @@
+/**
+ * 信任层的**指标与守恒等式**（卡 D1 的四段闭环 + 卡 D4 的三项指标）。
+ *
+ * 口径唯一源：**只读事件流**（`src/lineage.ts` 的 JSONL）——
+ * 不读登记册、不读内存状态 → 指标可由第三方**独立复算**（同一份账本 → 同一组数）。
+ *
+ * 三项指标（承 `docs/product/assistant-trust-model.md` §4 的口径）：
+ * ```
+ * 回应率      = answered / delivered          （它主动的 → 我回应的）
+ * 托付闭环率  = settled / registered           （托付 → 到达 → 知会 → 结账）
+ * 守候时长    = 平均(知会时刻 − 登记时刻)      （我不用守着的时间）
+ * ```
+ *
+ * 守恒等式（每条托付一条链，**不得跳段、不得重复**）：
+ * ```
+ * registered → arrived → notified → settled
+ * 每条链缺一段 → 记一条违规（少一段 = 红）
+ * 聚合等式：登记数 = 结账数 + 撤销数 + 在途数（重复登记 / 悬空都会破坏它）
+ * ```
+ *
+ * @capability: trust-metrics
+ * @observable: pi-proactive/src/trust-metrics.ts:computeTrustMetrics
+ * @attribution: pi-proactive/src/trust-metrics.ts:computeTrustMetrics
+ * @outcome: pi-proactive/src/trust-metrics.ts:ConservationReport
+ * @checked: test:pi-proactive/tests/trust-metrics.test.ts#D4-1 三项指标可从事件流算出
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** 托付链的阶段顺序（**不得跳段**）。 */
+const CHAIN = ["registered", "arrived", "notified", "settled"];
+/** 只取信任层事件（`type === "trust"`）。 */
+function trustEvents(events) {
+    const out = [];
+    for (const e of events) {
+        if (e.type !== "trust" || e.trust === undefined)
+            continue;
+        const id = e.trust.entrustmentId;
+        if (id === undefined || id === "")
+            continue;
+        out.push({ id, stage: e.trust.stage, ts: e.ts, event: e });
+    }
+    return out;
+}
+/**
+ * 托付四段的守恒等式。
+ *
+ * 判据（可机检、能红）：
+ * - 每条托付的阶段链必须是 `registered → arrived → notified → settled` 的**子序列**；
+ * - **跳段即违规**（例如有 `settled` 却没有 `notified` → 「少一段」→ 红）；
+ * - **重复即违规**（同一阶段两条 → 记一条；聚合等式也会因此失衡）；
+ * - 聚合等式：`登记数 == 结账数 + 撤销数 + 在途数`。
+ */
+export function evaluateEntrustmentConservation(events) {
+    const rows = trustEvents(events);
+    const byEntrustment = new Map();
+    for (const r of rows) {
+        const list = byEntrustment.get(r.id) ?? [];
+        list.push({ stage: r.stage, ts: r.ts });
+        byEntrustment.set(r.id, list);
+    }
+    const violations = [];
+    let registered = 0;
+    let arrived = 0;
+    let notified = 0;
+    let settled = 0;
+    let revoked = 0;
+    let humanGated = 0;
+    let inFlight = 0;
+    for (const [id, list] of byEntrustment) {
+        list.sort((a, b) => a.ts - b.ts);
+        const stages = list.map((l) => l.stage);
+        const countOf = (s) => stages.filter((x) => x === s).length;
+        registered += countOf("registered");
+        arrived += countOf("arrived");
+        notified += countOf("notified");
+        settled += countOf("settled");
+        revoked += countOf("revoked");
+        humanGated += countOf("human-gated");
+        // 重复阶段（去重失效 → 清单里同一件事出现两次）。
+        for (const s of CHAIN) {
+            if (countOf(s) > 1)
+                violations.push(`${id}: 重复阶段 ${s} ×${countOf(s)}`);
+        }
+        // 起始阶段必须是登记。
+        if (countOf("registered") === 0)
+            violations.push(`${id}: 缺阶段 registered`);
+        // 跳段检查：出现了靠后的阶段，就必须有它前面的阶段。
+        for (let i = 1; i < CHAIN.length; i += 1) {
+            const s = CHAIN[i];
+            if (countOf(s) === 0)
+                continue;
+            for (let j = 0; j < i; j += 1) {
+                const prev = CHAIN[j];
+                if (countOf(prev) === 0)
+                    violations.push(`${id}: 缺阶段 ${prev}（但已有 ${s}）`);
+            }
+        }
+        // 顺序检查：阶段必须按链的顺序出现（时间序）。
+        const orderIdx = new Map(CHAIN.map((s, i) => [s, i]));
+        let last = -1;
+        for (const s of stages) {
+            const idx = orderIdx.get(s);
+            if (idx === undefined)
+                continue; // revoked / human-gated 不在主链上
+            if (idx < last)
+                violations.push(`${id}: 阶段乱序 ${s}`);
+            last = Math.max(last, idx);
+        }
+        // 撤销与结账互斥。
+        if (countOf("settled") > 0 && countOf("revoked") > 0)
+            violations.push(`${id}: 同时结账与撤销`);
+        // 终态判定：在途 = 既没结账也没撤销。
+        if (countOf("settled") === 0 && countOf("revoked") === 0)
+            inFlight += 1;
+    }
+    const equationHolds = registered === settled + revoked + inFlight;
+    if (!equationHolds) {
+        violations.push(`聚合等式不成立：登记 ${registered} ≠ 结账 ${settled} + 撤销 ${revoked} + 在途 ${inFlight}`);
+    }
+    return {
+        registered,
+        arrived,
+        notified,
+        settled,
+        revoked,
+        humanGated,
+        inFlight,
+        equationHolds,
+        violations,
+        balanced: violations.length === 0 && equationHolds,
+    };
+}
+/**
+ * 三项指标（回应率 / 托付闭环率 / 守候时长）+ 守恒等式。
+ *
+ * 全部从**事件流**算 → 可由第三方用同一份账本复算。
+ */
+export function computeTrustMetrics(events) {
+    let delivered = 0;
+    let answered = 0;
+    for (const e of events) {
+        if (e.type === "delivered" && e.result === "delivered")
+            delivered += 1;
+        if (e.type === "answered")
+            answered += 1;
+    }
+    const conservation = evaluateEntrustmentConservation(events);
+    // 守候时长：登记 → 知会（同一托付的第一条 registered 与 notified）。
+    const firstRegistered = new Map();
+    const firstNotified = new Map();
+    for (const e of events) {
+        if (e.type !== "trust" || e.trust === undefined)
+            continue;
+        const id = e.trust.entrustmentId;
+        if (id === undefined)
+            continue;
+        if (e.trust.stage === "registered" && !firstRegistered.has(id))
+            firstRegistered.set(id, e.ts);
+        if (e.trust.stage === "notified" && !firstNotified.has(id))
+            firstNotified.set(id, e.ts);
+    }
+    let totalMs = 0;
+    let count = 0;
+    for (const [id, at] of firstNotified) {
+        const from = firstRegistered.get(id);
+        if (from === undefined)
+            continue;
+        totalMs += Math.max(0, at - from);
+        count += 1;
+    }
+    const rate = (n, d) => (d === 0 ? 0 : n / d);
+    return {
+        responseRate: { numerator: answered, denominator: delivered, value: rate(answered, delivered) },
+        entrustmentClosureRate: { numerator: conservation.settled, denominator: conservation.registered, value: rate(conservation.settled, conservation.registered) },
+        watchDuration: { averageMs: count === 0 ? 0 : totalMs / count, totalMs, count },
+        conservation,
+    };
+}
+/**
+ * 读一个目录下的全部事件流文件（`*.jsonl`）→ 事件列表。
+ *
+ * 坏行跳过（不抛错）——与 `src/lineage.ts` 的读方口径一致。
+ */
+export function readLineageEvents(dir) {
+    let files;
+    try {
+        files = fs.readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const f of files) {
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(dir, f), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.ts === "number" && typeof parsed?.type === "string")
+                    events.push(parsed);
+            }
+            catch {
+                // 坏行跳过
+            }
+        }
+    }
+    return events;
+}
+/**
+ * CLI：打印指标 JSON（供 `scripts/team/progress-snapshot.sh` 调用 → **同一份实现算指标**，
+ * 避免「脚本里另写一套口径」导致漂移）。
+ *
+ * 用法：`node --experimental-strip-types pi-proactive/src/trust-metrics.ts --dir <lineageDir>`
+ */
+export function main(argv) {
+    const idx = argv.indexOf("--dir");
+    const dir = idx >= 0 ? argv[idx + 1] : undefined;
+    if (dir === undefined) {
+        console.error("用法：trust-metrics.ts --dir <lineageDir>");
+        return 2;
+    }
+    const metrics = computeTrustMetrics(readLineageEvents(dir));
+    console.log(JSON.stringify(metrics));
+    return 0;
+}
+const invokedDirectly = process.argv[1] !== undefined && process.argv[1].endsWith("trust-metrics.ts");
+if (invokedDirectly) {
+    process.exitCode = main(process.argv.slice(2));
+}

package/build/src/trust-notify.js

@@ -0,0 +1,73 @@
+/**
+ * 通道判定（纯函数）。
+ *
+ * - 空闲 → `wake`（用户不在 → 直接起一轮）；
+ * - 忙 → `queue`（排队，不打断正在做的事）；
+ * - 需人立刻决定（urgent）→ `interrupt`（担责的事不能等）。
+ */
+export function resolveTrustChannels(input) {
+    const session = input.urgent ? "interrupt" : input.idle ? "wake" : "queue";
+    // 设备级通知**一律发**（托付达成 = 用户明确交代过的事 → 值得一条设备通知；
+    // 会话通道决定「什么时候起一轮」，设备通道决定「用户不在电脑前也能收到」）。
+    const channels = [`session-${session}`, "device"];
+    return { session, device: true, channels };
+}
+/**
+ * 托付知会器。
+ *
+ * 幂等：同一条托付**只**知会一次（第二次 → `duplicate`，不再投递、不再落事件）。
+ */
+export class TrustNotifier {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 知会一条**已到达**的托付。
+     *
+     * 顺序：查状态（已知会 → 重复，返回）→ 投递（会话 + 设备）→ 标记知会 → 落 `notified` 事件。
+     * 需要人决定的托付 → **不投递**（只产出 human-gated 记录）：担责的事不代劳。
+     */
+    async notifyEntrustment(entrustmentId, opts = {}) {
+        const e = this.deps.registry.getEntrustment(entrustmentId);
+        if (e === undefined)
+            return { entrustmentId, delivered: false, reason: "not-found", channels: [] };
+        if (e.status === "notified" || e.status === "settled") {
+            return { entrustmentId, delivered: false, reason: "duplicate", channels: [] };
+        }
+        if (e.status !== "arrived") {
+            return { entrustmentId, delivered: false, reason: "not-arrived", channels: [] };
+        }
+        if (e.needsHuman === true) {
+            const reason = e.humanReason ?? "需要人决定";
+            this.deps.registry.markNeedsHuman(entrustmentId, reason);
+            this.deps.lineage?.noteTrust({ stage: "human-gated", entrustmentId, goalId: e.goalId, reason });
+            return { entrustmentId, delivered: false, reason: "needs-human", channels: [] };
+        }
+        const plan = resolveTrustChannels({ idle: opts.idle ?? true, urgent: opts.urgent ?? false });
+        const title = "托付达成";
+        const body = `${e.target} —— 条件已满足。`;
+        const channels = [];
+        if (this.deps.deliverSession !== undefined) {
+            await this.deps.deliverSession({ title, body, intent: plan.session });
+            channels.push(`session-${plan.session}`);
+        }
+        if (plan.device && this.deps.notifyDevice !== undefined) {
+            this.deps.notifyDevice(title, body);
+            channels.push("device");
+        }
+        const marked = this.deps.registry.markNotified(entrustmentId);
+        if (marked === undefined) {
+            return { entrustmentId, delivered: false, reason: "duplicate", channels };
+        }
+        const waitedMs = marked.notifiedAt !== undefined && marked.createdAt !== undefined ? marked.notifiedAt - marked.createdAt : undefined;
+        this.deps.lineage?.noteTrust({
+            stage: "notified",
+            entrustmentId,
+            goalId: e.goalId,
+            channel: channels.join("+"),
+            ...(waitedMs !== undefined ? { waitedMs } : {}),
+        });
+        return { entrustmentId, delivered: true, channels };
+    }
+}