@twinsearth/dsh-master 3.2.10 → 3.3.1

package/dist-worker/edg.js

@@ -0,0 +1,372 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/**
+ * 3.3.0 · B1 `edg`（可执行决策图，设计 §7）。
+ *
+ * 一条边 = 「精确动作 + 确定性参数来源 + 守卫」，这是 HarnessMM 的核心资产：
+ * 慢模型只需在**作者步骤**写一次，之后由守卫命中直接复用。
+ *
+ * 硬约束（写死在实现里）：
+ *   * `schemaHash` 与当前工具 schema 不一致 ⇒ **整图作废**（不得复用旧决策）；
+ *   * 参数只能来自回执的**确定性提取**（literal / regex / jsonpath）——
+ *     解析不出来就直接判定该边不可用（**禁止模型幻觉参数**）；
+ *   * `destructive: true` 的边**默认不入池**（validate 直接拒）；
+ *   * 生命周期 `draft → validated → active → exhausted → archived`，非法跃迁一律拒绝；
+ *   * 图来源两种：慢模型作者步骤（`parseDraftFromModel`）或人工/AI 预置模板库。
+ *
+ * 作者成本**单独记**：`phase:'authoring'` + `account:'governance'`（由宿主记账，见 cost-optimizer）。
+ */
+import crypto from 'node:crypto';
+/** 当前工具 schema 的稳定哈希（tools 列表变化即整图作废）。 */
+export function schemaHashOf(toolName, parameters, description) {
+    const body = JSON.stringify({ toolName, parameters: parameters ?? {}, description: description ?? '' });
+    return `sha256:${crypto.createHash('sha256').update(body).digest('hex').slice(0, 16)}`;
+}
+const tokensOf = (text) => (text.length > 0 ? Math.ceil(text.length / 4) : 0);
+/* ------------------------------------------------------------------ *
+ * 确定性提取（禁止幻觉参数）
+ * ------------------------------------------------------------------ */
+/** 极简 JSONPath：`$.a.b` / `$.a[0].b`（够用即止，不做完整实现）。 */
+export function jsonPathGet(value, expr) {
+    const path = String(expr ?? '').trim();
+    if (!path.startsWith('$'))
+        return undefined;
+    const segments = [];
+    const body = path.slice(1);
+    const re = /\.([A-Za-z_$][\w$]*)|\[(\d+)\]/gu;
+    let match;
+    let consumed = 0;
+    while ((match = re.exec(body)) !== null) {
+        if (match.index !== consumed)
+            return undefined;
+        consumed = match.index + match[0].length;
+        segments.push(match[2] === undefined ? match[1] : Number(match[2]));
+    }
+    if (consumed !== body.length)
+        return undefined;
+    let current = value;
+    for (const segment of segments) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof segment === 'number') {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[segment];
+        }
+        else {
+            if (typeof current !== 'object')
+                return undefined;
+            current = current[segment];
+        }
+    }
+    return current;
+}
+/** 把回执文本按需解析成 JSON（失败返回 undefined，不猜）。 */
+function asJson(text) {
+    const raw = String(text ?? '');
+    try {
+        return JSON.parse(raw);
+    }
+    catch { /* 继续尝试提取 JSON 片段 */ }
+    // 回执常带前缀（如 shell 的 STDOUT: 或说明行）：在**确定性位置**截取首个 { 到末个 }
+    // 再解析。这仍然是确定性的文本提取，不是猜测。
+    const start = raw.indexOf('{');
+    const end = raw.lastIndexOf('}');
+    if (start < 0 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(raw.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 解析单个 argSource。**失败返回 undefined**（调用方据此判定该边不可用），
+ * 绝不回退到"模型给的参数"或默认值。
+ */
+export function resolveArg(source, receiptText) {
+    const expr = String(source?.expr ?? '');
+    if (source?.from === 'literal') {
+        // literal 就是字面量本身（不做变量替换，避免"看起来像模板"的幻觉空间）
+        return expr;
+    }
+    if (source?.from === 'regex') {
+        // expr 形如 `/(?<v>...)/` 或裸正则；取第一个捕获组，没有捕获组则取整个匹配。
+        const trimmed = expr.trim();
+        const body = trimmed.startsWith('/') && trimmed.lastIndexOf('/') > 0
+            ? trimmed.slice(1, trimmed.lastIndexOf('/'))
+            : trimmed;
+        let re;
+        try {
+            re = new RegExp(body, 'u');
+        }
+        catch {
+            return undefined;
+        }
+        const match = re.exec(receiptText);
+        if (!match)
+            return undefined;
+        return match.groups?.value ?? match[1] ?? match[0];
+    }
+    if (source?.from === 'jsonpath') {
+        const json = asJson(receiptText);
+        if (json === undefined)
+            return undefined;
+        return jsonPathGet(json, expr);
+    }
+    return undefined;
+}
+/** 解析整条边的参数；任一参数解析失败 ⇒ null（该边不可用于本次回执）。 */
+export function resolveEdgeArgs(edge, receiptText) {
+    const args = {};
+    for (const source of edge.argSource) {
+        const value = resolveArg(source, receiptText);
+        if (value === undefined)
+            return null;
+        args[source.arg] = value;
+    }
+    return args;
+}
+/* ------------------------------------------------------------------ *
+ * 守卫
+ * ------------------------------------------------------------------ */
+/** 守卫求值：命中返回 true。表达式非法 ⇒ false（宁可不命中，也不误替换）。 */
+export function evaluateGuard(guard, receiptText) {
+    if (!guard || typeof guard !== 'object')
+        return false;
+    let result = false;
+    if (guard.kind === 'regex') {
+        const trimmed = String(guard.expr ?? '').trim();
+        const body = trimmed.startsWith('/') && trimmed.lastIndexOf('/') > 0
+            ? trimmed.slice(1, trimmed.lastIndexOf('/'))
+            : trimmed;
+        try {
+            result = new RegExp(body, 'u').test(receiptText);
+        }
+        catch {
+            return false;
+        }
+    }
+    else if (guard.kind === 'equals') {
+        result = receiptText.trim() === String(guard.expr ?? '').trim();
+    }
+    else if (guard.kind === 'jsonpath') {
+        const json = asJson(receiptText);
+        if (json === undefined)
+            return false;
+        const value = jsonPathGet(json, String(guard.expr ?? ''));
+        result = value !== undefined && value !== null && value !== false && value !== '' && value !== 0;
+    }
+    else {
+        return false;
+    }
+    return guard.negate === true ? !result : result;
+}
+/* ------------------------------------------------------------------ *
+ * 图 store 与生命周期
+ * ------------------------------------------------------------------ */
+const LEGAL_TRANSITIONS = {
+    draft: ['validated', 'archived'],
+    validated: ['active', 'archived'],
+    active: ['exhausted', 'archived'],
+    exhausted: ['archived', 'active'],
+    archived: ['active'],
+};
+export function createEdgStore(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    let seq = 0;
+    const idFactory = typeof options.idFactory === 'function' ? options.idFactory : () => `edg_${now().toString(36)}_${(seq += 1).toString(36)}`;
+    const graphs = new Map();
+    const clone = (graph) => Object.freeze({ ...graph, edges: graph.edges.map((edge) => Object.freeze({ ...edge, argSource: edge.argSource.map((item) => ({ ...item })) })) });
+    function transition(graph, to, reason) {
+        if (!LEGAL_TRANSITIONS[graph.state].includes(to)) {
+            return { ok: false, state: graph.state, reason: `illegal-transition:${graph.state}->${to}` };
+        }
+        graph.state = to;
+        if (reason !== undefined)
+            graph.reason = reason;
+        return { ok: true, state: graph.state };
+    }
+    function addDraft(input) {
+        const edges = (Array.isArray(input?.edges) ? input.edges : []).map((edge, index) => Object.freeze({
+            id: String(edge?.id ?? `edge_${index + 1}`),
+            toolName: String(edge?.toolName ?? ''),
+            schemaHash: String(edge?.schemaHash ?? ''),
+            argSource: Array.isArray(edge?.argSource) ? edge.argSource.map((item) => Object.freeze({ arg: String(item?.arg ?? ''), from: String(item?.from ?? 'literal'), expr: String(item?.expr ?? '') })) : [],
+            guard: Object.freeze({
+                kind: String(edge?.guard?.kind ?? 'regex'),
+                expr: String(edge?.guard?.expr ?? ''),
+                negate: edge?.guard?.negate === true,
+            }),
+            destructive: edge?.destructive === true,
+            dependsOn: Array.isArray(edge?.dependsOn) ? edge.dependsOn.map((item) => String(item)) : undefined,
+        }));
+        const graph = {
+            id: idFactory(),
+            taskId: String(input?.taskId ?? ''),
+            createdAt: now(),
+            source: input?.source === 'template' ? 'template' : 'author',
+            state: 'draft',
+            model: input?.model === undefined ? undefined : String(input.model),
+            frozen: false,
+            edges,
+            authorTokens: tokensOf(String(input?.authorText ?? '')),
+        };
+        graphs.set(graph.id, graph);
+        return clone(graph);
+    }
+    function validate(graphId, opts) {
+        const graph = graphs.get(String(graphId));
+        if (!graph)
+            return { ok: false, state: 'draft', reason: 'graph-not-found' };
+        const allowed = Array.isArray(opts?.allowedTools) && opts.allowedTools.length > 0 ? new Set(opts.allowedTools) : null;
+        const maxEdges = Math.max(1, Number(opts?.maxEdges ?? 32) || 32);
+        const ids = new Set(graph.edges.map((edge) => edge.id));
+        for (const edge of graph.edges) {
+            if (!edge.toolName)
+                return { ok: false, state: graph.state, reason: 'edge-missing-tool' };
+            if (allowed && !allowed.has(edge.toolName))
+                return { ok: false, state: graph.state, reason: `tool-not-allowed:${edge.toolName}` };
+            // schema 校验：拿不到当前哈希 ⇒ 视为不一致（fail-closed）
+            const current = opts?.schemas?.[edge.toolName];
+            if (!current || current !== edge.schemaHash)
+                return { ok: false, state: graph.state, reason: `schema-mismatch:${edge.toolName}` };
+            for (const source of edge.argSource) {
+                if (!source.arg)
+                    return { ok: false, state: graph.state, reason: 'arg-source-missing-arg' };
+                if (!['literal', 'regex', 'jsonpath'].includes(source.from))
+                    return { ok: false, state: graph.state, reason: `arg-source-invalid:${source.from}` };
+            }
+            if (!['regex', 'jsonpath', 'equals'].includes(edge.guard.kind))
+                return { ok: false, state: graph.state, reason: `guard-kind-invalid:${edge.guard.kind}` };
+            // 破坏性动作默认不入池
+            if (edge.destructive && opts?.allowDestructive !== true)
+                return { ok: false, state: graph.state, reason: `destructive-not-allowed:${edge.toolName}` };
+            for (const dep of edge.dependsOn ?? []) {
+                if (!ids.has(dep))
+                    return { ok: false, state: graph.state, reason: `dependency-missing:${dep}` };
+            }
+        }
+        if (graph.edges.length === 0)
+            return { ok: false, state: graph.state, reason: 'graph-empty' };
+        if (graph.edges.length > maxEdges)
+            return { ok: false, state: graph.state, reason: 'graph-too-large' };
+        return transition(graph, 'validated');
+    }
+    function activate(graphId) {
+        const graph = graphs.get(String(graphId));
+        if (!graph)
+            return { ok: false, state: 'draft', reason: 'graph-not-found' };
+        return transition(graph, 'active');
+    }
+    function exhaust(graphId, reason) {
+        const graph = graphs.get(String(graphId));
+        if (!graph)
+            return { ok: false, state: 'draft' };
+        return transition(graph, 'exhausted', reason);
+    }
+    function archive(graphId) {
+        const graph = graphs.get(String(graphId));
+        if (!graph)
+            return { ok: false, state: 'draft' };
+        return transition(graph, 'archived');
+    }
+    /** schema 变化 ⇒ 整图作废（有边的 schemaHash 与当前不符即整图归档）。 */
+    function invalidateBySchema(schemas) {
+        const invalidated = [];
+        for (const graph of graphs.values()) {
+            if (graph.state === 'archived')
+                continue;
+            const bad = graph.edges.find((edge) => schemas?.[edge.toolName] !== edge.schemaHash);
+            if (!bad)
+                continue;
+            graph.state = 'archived';
+            graph.reason = `schema-drift:${bad.toolName}`;
+            invalidated.push(graph.id);
+        }
+        return invalidated;
+    }
+    function get(graphId) {
+        const graph = graphs.get(String(graphId));
+        return graph ? clone(graph) : null;
+    }
+    function list(state) {
+        return [...graphs.values()].filter((graph) => (state === undefined ? true : graph.state === state)).map((graph) => clone(graph));
+    }
+    function authorCost() {
+        let authorTokens = 0;
+        let count = 0;
+        for (const graph of graphs.values()) {
+            if (graph.source !== 'author')
+                continue;
+            count += 1;
+            authorTokens += graph.authorTokens;
+        }
+        return { graphs: count, authorTokens };
+    }
+    function reset() {
+        graphs.clear();
+    }
+    return Object.freeze({ addDraft, validate, activate, exhaust, archive, get, list, invalidateBySchema, authorCost, reset });
+}
+/* ------------------------------------------------------------------ *
+ * 作者步骤：从慢模型输出里抽候选图（确定性解析，不猜）
+ * ------------------------------------------------------------------ */
+/**
+ * 从模型输出中抽取 `{ "edges": [...] }` JSON 块。
+ * 只接受 `edges` 数组里的合法字段；解析不出来返回 null（**不生成空图、不猜参数**）。
+ */
+export function parseDraftFromModel(text) {
+    const raw = String(text ?? '');
+    if (raw.trim() === '')
+        return null;
+    const blocks = [...raw.matchAll(/```(?:json)?\s*([\s\S]*?)```/gu)].map((match) => match[1]);
+    const candidates = blocks.length > 0 ? blocks : [raw];
+    for (const candidate of candidates) {
+        const start = candidate.indexOf('{');
+        const end = candidate.lastIndexOf('}');
+        if (start < 0 || end <= start)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(candidate.slice(start, end + 1));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== 'object')
+            continue;
+        const edges = parsed.edges;
+        if (!Array.isArray(edges) || edges.length === 0)
+            continue;
+        const cleaned = edges
+            .filter((edge) => Boolean(edge) && typeof edge === 'object')
+            .map((edge) => ({
+            toolName: String(edge.toolName ?? ''),
+            schemaHash: String(edge.schemaHash ?? ''),
+            argSource: Array.isArray(edge.argSource) ? edge.argSource : [],
+            guard: (edge.guard && typeof edge.guard === 'object' ? edge.guard : { kind: 'regex', expr: '' }),
+            destructive: edge.destructive === true,
+            dependsOn: Array.isArray(edge.dependsOn) ? edge.dependsOn.map((item) => String(item)) : undefined,
+        }))
+            .filter((edge) => edge.toolName !== '');
+        if (cleaned.length === 0)
+            continue;
+        return { edges: cleaned, authorText: raw };
+    }
+    return null;
+}
+export function createTemplateLibrary(templates = []) {
+    const items = (Array.isArray(templates) ? templates : []).filter((item) => item && typeof item === 'object' && item.id);
+    return Object.freeze({
+        list: () => items.map((item) => ({ ...item, edges: item.edges.map((edge) => ({ ...edge })) })),
+        find: (id) => {
+            const found = items.find((item) => item.id === String(id));
+            return found ? { ...found, edges: found.edges.map((edge) => ({ ...edge })) } : null;
+        },
+        forTool: (toolName) => items
+            .filter((item) => item.edges.some((edge) => String(edge.toolName ?? '') === String(toolName)))
+            .map((item) => ({ ...item, edges: item.edges.map((edge) => ({ ...edge })) })),
+    });
+}

package/dist-worker/gdr.js

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+import { evaluateGuard, resolveEdgeArgs } from "./edg.js";
+const EMPTY_REASONS = () => ({
+    'no-edge': 0,
+    'tool-mismatch': 0,
+    'schema-drift': 0,
+    'dependency-incomplete': 0,
+    'guard-miss': 0,
+    'arg-unextractable': 0,
+});
+const EMPTY_STAGES = () => ({
+    toolName: 0,
+    schemaHash: 0,
+    dependencies: 0,
+    guard: 0,
+    args: 0,
+});
+export function createGdr(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    let matches = 0;
+    let hits = 0;
+    let lastAt = null;
+    const byReason = EMPTY_REASONS();
+    const byStage = EMPTY_STAGES();
+    const byTool = new Map();
+    function toolRow(toolName) {
+        if (!byTool.has(toolName))
+            byTool.set(toolName, { matches: 0, hits: 0 });
+        return byTool.get(toolName);
+    }
+    function miss(reason, stage, receiptDigest, toolName) {
+        matches += 1;
+        byReason[reason] += 1;
+        byStage[stage] += 1;
+        const row = toolRow(toolName);
+        row.matches += 1;
+        lastAt = now();
+        return { hit: false, reason, stage, receiptDigest, at: lastAt };
+    }
+    /**
+     * 五步匹配。**顺序不可调换**：先便宜的后昂贵的，且 schema 漂移必须早于守卫判定——
+     * 否则旧图可能在新 schema 上"命中"，那是最危险的误替换。
+     */
+    function match(input) {
+        const receipt = input?.receipt ?? { toolName: '', text: '', digest: '' };
+        const graph = input?.graph;
+        const toolName = String(receipt.toolName ?? '');
+        const digest = String(receipt.digest ?? '');
+        const edges = Array.isArray(graph?.edges) ? graph.edges : [];
+        // ① 工具名
+        if (edges.length === 0)
+            return miss('no-edge', 'toolName', digest, toolName);
+        const candidates = edges.filter((edge) => String(edge?.toolName ?? '') === toolName);
+        if (candidates.length === 0)
+            return miss('tool-mismatch', 'toolName', digest, toolName);
+        const completed = input?.completed instanceof Set
+            ? input.completed
+            : new Set(Array.isArray(input?.completed) ? input.completed : []);
+        // 逐条候选走完 ②③④⑤；任一条全过即命中。
+        let firstMiss = null;
+        for (const edge of candidates) {
+            // ② schemaHash：漂移即整图作废（不匹配就直接 miss，绝不继续）
+            const current = typeof input?.schemaHashOf === 'function' ? input.schemaHashOf(edge.toolName) : undefined;
+            if (current !== undefined && current !== edge.schemaHash) {
+                if (!firstMiss)
+                    firstMiss = { reason: 'schema-drift', stage: 'schemaHash' };
+                continue;
+            }
+            // ③ 依赖边完成
+            const deps = Array.isArray(edge.dependsOn) ? edge.dependsOn : [];
+            if (deps.some((dep) => !completed.has(String(dep)))) {
+                if (!firstMiss)
+                    firstMiss = { reason: 'dependency-incomplete', stage: 'dependencies' };
+                continue;
+            }
+            // ④ 守卫表达式
+            if (!evaluateGuard(edge.guard, String(receipt.text ?? ''))) {
+                if (!firstMiss)
+                    firstMiss = { reason: 'guard-miss', stage: 'guard' };
+                continue;
+            }
+            // ⑤ 参数可确定性提取
+            const args = resolveEdgeArgs(edge, String(receipt.text ?? ''));
+            if (args === null) {
+                if (!firstMiss)
+                    firstMiss = { reason: 'arg-unextractable', stage: 'args' };
+                continue;
+            }
+            // 五步全过 ⇒ 命中
+            matches += 1;
+            hits += 1;
+            const row = toolRow(toolName);
+            row.matches += 1;
+            row.hits += 1;
+            lastAt = now();
+            const wouldSaveTokens = typeof input?.estimateSavedTokens === 'function'
+                ? Math.max(0, Number(input.estimateSavedTokens(edge, args)) || 0)
+                : 0;
+            return {
+                hit: true,
+                edgeId: edge.id,
+                stage: null,
+                receiptDigest: digest,
+                args,
+                wouldSaveTokens,
+                at: lastAt,
+            };
+        }
+        const reason = firstMiss ?? { reason: 'guard-miss', stage: 'guard' };
+        return miss(reason.reason, reason.stage, digest, toolName);
+    }
+    function stats() {
+        return {
+            matches,
+            hits,
+            hitRate: matches > 0 ? hits / matches : 0,
+            byReason: { ...byReason },
+            byTool: Object.fromEntries([...byTool.entries()].map(([tool, row]) => [tool, { ...row }])),
+            byStage: { ...byStage },
+            lastAt,
+        };
+    }
+    /** 报表 + 可执行的改进建议（喂给 RSI：哪一环最该优化）。 */
+    function report() {
+        const current = stats();
+        const suggestions = [];
+        if (current.matches === 0)
+            suggestions.push('样本为空：先跑 shadow 累积回执再评估');
+        if (current.byReason['schema-drift'] > 0) {
+            suggestions.push(`schema-drift ${current.byReason['schema-drift']} 次：优先复算 schemaHash 并回收旧图`);
+        }
+        if (current.byReason['guard-miss'] > 0) {
+            suggestions.push(`guard-miss ${current.byReason['guard-miss']} 次：守卫表达式过严或回执形态变化`);
+        }
+        if (current.byReason['arg-unextractable'] > 0) {
+            suggestions.push(`arg-unextractable ${current.byReason['arg-unextractable']} 次：参数来源应改为 jsonpath/regex 可命中的字段`);
+        }
+        if (current.byReason['dependency-incomplete'] > 0) {
+            suggestions.push(`dependency-incomplete ${current.byReason['dependency-incomplete']} 次：依赖链过长，考虑拆分图`);
+        }
+        if (current.byReason['tool-mismatch'] > 0) {
+            suggestions.push(`tool-mismatch ${current.byReason['tool-mismatch']} 次：图里缺少该工具的边`);
+        }
+        if (current.matches >= 20 && current.hitRate < 0.5) {
+            suggestions.push(`命中率 ${(current.hitRate * 100).toFixed(1)}% 偏低：建议先扩充图或放宽守卫`);
+        }
+        return { stats: current, suggestions };
+    }
+    function reset() {
+        matches = 0;
+        hits = 0;
+        lastAt = null;
+        Object.assign(byReason, EMPTY_REASONS());
+        Object.assign(byStage, EMPTY_STAGES());
+        byTool.clear();
+    }
+    return Object.freeze({ match, stats, report, reset });
+}

package/dist-worker/index.js

@@ -98,6 +98,7 @@ export function buildWorkerDeps(options = {}) {
             limits: options.limits,
             model: String(options.model ?? env.WORKER_LLM_MODEL ?? '') || undefined,
             redactValues: secretValuesOf(env),
+            compactMode: String(env.DSH_MASTER_COMPACT_MODE ?? '') || undefined,
         },
     };
 }
@@ -125,6 +126,10 @@ function cordisSink(ctx) {
             ctx.emit?.('superagent:stream', delta);
         }
         catch { /* ignore */ } },
+        cost: (event) => { try {
+            ctx.emit?.('superagent:cost', event);
+        }
+        catch { /* ignore */ } },
     };
 }
 /** 组合 sink：Cordis 事件 + Router HTTP 实时通道（任一失败不影响另一个）。 */
@@ -147,7 +152,7 @@ function composeSink(local, remote) {
             catch { /* ignore */ }
         });
     };
-    return { log: wrap('log'), step: wrap('step'), phase: wrap('phase'), stream: wrap('stream') };
+    return { log: wrap('log'), step: wrap('step'), phase: wrap('phase'), stream: wrap('stream'), cost: wrap('cost') };
 }
 /** 归档真实 token 用量到 fork 内的 HarnessMM observe 服务；无该服务时不影响 Worker。 */
 export function recordWorkerCost(ctx, ticketId, result) {
@@ -156,8 +161,81 @@ export function recordWorkerCost(ctx, ticketId, result) {
         if (!cost || typeof cost.record !== 'function')
             return { ok: false, code: 'cost-service-unavailable' };
         const tokens = Math.max(0, Number(result.tokenUsage ?? 0) || 0);
+        const estimatedTokens = Math.max(0, Number(result.cost?.tokens?.estimated ?? 0) || 0);
         // 尚未接入 EGD/GDR 优化，优化前后相等，绝不虚报节省；只记录真实 token 与成功率。
-        return cost.record({ taskId: ticketId, baselineTokens: tokens, optimizedTokens: tokens, success: result.ok === true });
+        // §5.1：实测与估算分别入账（estimatedTokens 由 Agent Loop 的兜底估算给出）。
+        const recorded = cost.record({
+            taskId: ticketId,
+            baselineTokens: tokens,
+            optimizedTokens: tokens,
+            estimatedTokens,
+            estimated: estimatedTokens > 0 && estimatedTokens >= tokens,
+            success: result.ok === true,
+        });
+        // 3.3.0 M2：A1 紧凑化的归因单独上报（shadow 只记「本可节省」，enforce 才入账）。
+        const compaction = result.cost?.compaction;
+        let attribution = null;
+        if (compaction && compaction.estimatedTokens > 0 && typeof cost.recordAttribution === 'function') {
+            attribution = cost.recordAttribution({
+                taskId: ticketId,
+                module: 'a1-compact',
+                savedTokens: compaction.estimatedTokens,
+                mode: compaction.mode,
+                meta: {
+                    evaluated: compaction.evaluated,
+                    applied: compaction.applied,
+                    originalChars: compaction.originalChars,
+                    compactChars: compaction.compactChars,
+                    savedChars: compaction.savedChars,
+                },
+            });
+        }
+        // 目标 2.1-5：降级必须留痕（审计 + 事件总线），且绝不折算成节省。
+        let degraded = null;
+        const degradedEvents = result.cost?.degraded?.events ?? [];
+        const recordDegraded = cost.recordDegraded;
+        if (degradedEvents.length > 0 && typeof recordDegraded === 'function') {
+            degraded = degradedEvents.map((event) => recordDegraded({
+                taskId: ticketId,
+                module: event.module,
+                phase: event.phase,
+                message: event.message,
+                count: event.count,
+            }));
+        }
+        // §6 A2：工具装载成本记 governance（与 execution 节省分开，报表并列）。
+        let governance = null;
+        const disclosure = result.cost?.disclosure;
+        const recordGovernance = cost.recordGovernance;
+        if (disclosure && disclosure.loadEvents > 0 && disclosure.schemaTokens > 0 && typeof recordGovernance === 'function') {
+            governance = recordGovernance({
+                taskId: ticketId,
+                module: 'a2-disclosure',
+                tokens: disclosure.schemaTokens,
+                kind: 'tools.load',
+                meta: { loadEvents: disclosure.loadEvents, schemaCount: disclosure.schemaCount, loaded: disclosure.loaded },
+            });
+        }
+        // §7 B3：替换证书上报宿主（审计链 + 账本，用同一 taskId+step 关联）。
+        let substitutions = null;
+        const certs = result.cost?.ccs?.substitutions ?? [];
+        const recordSubstitution = cost.recordSubstitution;
+        if (certs.length > 0 && typeof recordSubstitution === 'function') {
+            substitutions = certs.map((cert) => recordSubstitution({
+                edgeId: cert.edgeId,
+                toolName: cert.toolName,
+                schemaHash: cert.schemaHash,
+                guardExpr: cert.guardExpr,
+                receiptDigest: cert.receiptDigest,
+                replacedCallbackId: cert.replacedCallbackId,
+                viaNativeDispatcher: cert.viaNativeDispatcher,
+                taskId: cert.taskId || ticketId,
+                step: cert.step,
+                savedTokens: cert.savedTokens ?? 0,
+                moduleId: cert.moduleId ?? 'b3-ccs',
+            }));
+        }
+        return { recorded, attribution, degraded, governance, substitutions };
     }
     catch (error) {
         return { ok: false, code: 'cost-record-failed', error: String(error instanceof Error ? error.message : error) };

package/dist-worker/llm-http.js

@@ -1,5 +1,21 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 // Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/**
+ * §11：从 provider 的 usage 里读缓存命中量。
+ * 兼容 `prompt_tokens_details.cached_tokens`（OpenAI 风格）与顶层 `cached_tokens`。
+ * **拿不到就返回 undefined**，不写 0 —— 否则报表会把"未知"伪装成"没有缓存命中"。
+ */
+function readCachedTokens(usage) {
+    if (!usage || typeof usage !== 'object')
+        return undefined;
+    const details = usage.prompt_tokens_details;
+    const direct = usage.cached_tokens;
+    const raw = details?.cached_tokens ?? direct;
+    if (raw === undefined || raw === null)
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
 function endpointOf(baseUrl) {
     const trimmed = String(baseUrl ?? '').trim().replace(/\/+$/, '');
     if (!trimmed)
@@ -49,6 +65,8 @@ function fromWireResponse(payload) {
                 promptTokens: Number(payload.usage.prompt_tokens ?? 0),
                 completionTokens: Number(payload.usage.completion_tokens ?? 0),
                 totalTokens: Number(payload.usage.total_tokens ?? 0),
+                // §11：prompt cache 命中量（未返回就省略，不冒充 0 节省）。
+                ...(readCachedTokens(payload.usage) === undefined ? {} : { cachedTokens: readCachedTokens(payload.usage) }),
             }
             : undefined,
         finishReason: choice?.finish_reason,
@@ -111,10 +129,12 @@ function createStreamAccumulator(onDelta) {
             finishReason = choice.finish_reason;
         if (chunk?.usage && typeof chunk.usage === 'object') {
             const raw = chunk.usage;
+            const cached = readCachedTokens(raw);
             usage = {
                 promptTokens: Number(raw.prompt_tokens ?? 0),
                 completionTokens: Number(raw.completion_tokens ?? 0),
                 totalTokens: Number(raw.total_tokens ?? 0),
+                ...(cached === undefined ? {} : { cachedTokens: cached }),
             };
         }
         return Boolean(chunk?.choices || chunk?.usage);