dsh-auto-model-routing 0.4.0 → 0.4.1

package/docs/feedback-evaluation.md

@@ -12,7 +12,7 @@
 - appropriate/too-high/too-low分别统计；unknown不是满意，null撤销不计有效评价；未评价不能计为合适。多条消息评价冲突也应单独报告。
 - 按策略版本/映射版本/服务模型及depth/实际路由分组；旧缺字段独立unknown组，不混进新策略精确对照。
 - 以requestSeq和消息ID关联实际usage/延迟/返工证据；拿不到价格或token就未知。用户主观反馈不等于正确性oracle，适合率也不能单独证明质量或节省。
-- 本期只提供采集与可追溯性，不做报表、自动阈值调整、自动训练或换模重试。
+- 按需观察报表见包内 skill `auto-model-routing-report`（`lib/usage-report.js`，只读）；仍不做自动阈值调整、自动训练或换模重试。
 
 ## 确定度
 UI称“判定确定度”，Choice公式为`(pmax - 1/n)/(1 - 1/n)`；n为该维候选数。三选一最高概率70%得到55%，不等于选中概率或任务成功率。插件直接展示服务返回值，分布独立保留，不从四舍五入后的百分比反推。官方定义：https://docs.typesafe.ai/confidence.md 。

package/docs/host-capability-report.md

@@ -46,15 +46,15 @@
 
 以下为核验时已安装的官方发布包位置，不是上游改动要求。临时 prefix 可按下方命令重建；其中源码行号仅适用于此 pin。
 
-- [pre-step / request 类型](../../../node_modules/@deepseek-ai/dsh-agent/lib/types/runtime-types.d.ts#L293-L332)：公开事件输入和 waterfall 返回契约。
-- [Loop 请求链](../../../node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L1164-L1220)：实际调用 waterfall 后才 `llm.prepareCall`，记录 resolved request header。
-- [scopeTarget](../../../node_modules/@deepseek-ai/dsh-scope/lib/index.js#L315-L337)：无 Agent 作用域标记的全局 listener 可观察不同子身份。
-- [SubagentStartRequest](../../../node_modules/@deepseek-ai/dsh-subagent/lib/types/types.d.ts#L136-L162)：公开 `agentOptions`，不必通过工具 schema 推断宿主能力。
-- [continuation 创建](../../../node_modules/@deepseek-ai/dsh-subagent/lib/types/continuation.js#L101-L176)、[冷恢复](../../../node_modules/@deepseek-ai/dsh-subagent/lib/types/continuation.js#L354-L374)：descriptor 与恢复选项。
-- [官方 Team 创建转发](/tmp/dsh-official-routing-probe.HImElm/node_modules/@deepseek-ai/dsh-experimental-agent-team/lib/index.js#L573-L582)：只转发 prompt/parent，未传 agentOptions；并不妨碍插件在 child request 入口配置。
-- [默认选择副作用](../../../node_modules/@deepseek-ai/dsh-api-session-controller/lib/index.js#L720-L739)：`selectModel` 还会 `saveSelection`。
-
-`resolveChildAgentOptions` 是 [官方公开导出](../../../node_modules/@deepseek-ai/dsh-subagent/lib/types/index.d.ts#L55)，前期函数级实验使用内部文件路径不意味着函数本身是私有 API。本次整链探针没有导入任何内部 helper。
+- pre-step / request 类型（`node_modules/@deepseek-ai/dsh-agent/lib/types/runtime-types.d.ts#L293-L332`）：公开事件输入和 waterfall 返回契约。
+- Loop 请求链（`node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L1164-L1220`）：实际调用 waterfall 后才 `llm.prepareCall`，记录 resolved request header。
+- scopeTarget（`node_modules/@deepseek-ai/dsh-scope/lib/index.js#L315-L337`）：无 Agent 作用域标记的全局 listener 可观察不同子身份。
+- SubagentStartRequest（`node_modules/@deepseek-ai/dsh-subagent/lib/types/types.d.ts#L136-L162`）：公开 `agentOptions`，不必通过工具 schema 推断宿主能力。
+- continuation 创建（`node_modules/@deepseek-ai/dsh-subagent/lib/types/continuation.js#L101-L176`）、冷恢复（`node_modules/@deepseek-ai/dsh-subagent/lib/types/continuation.js#L354-L374`）：descriptor 与恢复选项。
+- 官方 Team 创建转发（`/tmp/dsh-official-routing-probe.HImElm/node_modules/@deepseek-ai/dsh-experimental-agent-team/lib/index.js#L573-L582`）：只转发 prompt/parent，未传 agentOptions；并不妨碍插件在 child request 入口配置。
+- 默认选择副作用（`node_modules/@deepseek-ai/dsh-api-session-controller/lib/index.js#L720-L739`）：`selectModel` 还会 `saveSelection`。
+
+`resolveChildAgentOptions` 是 官方公开导出（`node_modules/@deepseek-ai/dsh-subagent/lib/types/index.d.ts#L55`），前期函数级实验使用内部文件路径不意味着函数本身是私有 API。本次整链探针没有导入任何内部 helper。
 
 ## 重跑
 

package/docs/routing-intent-and-gaps.md

@@ -12,10 +12,10 @@
 
 ## 当前证据
 
-- 当前规范：../../../openspec/specs/auto-model-routing/spec.md，固定主模型、共享四档 rubric、childRoutes 与派发规则。
+- 当前规范：[主仓规范](https://github.com/prgrmrwy/ohmydsh/blob/main/openspec/specs/auto-model-routing/spec.md)（本节是历史调研快照，不代表当前默认策略），固定主模型、共享四档 rubric、childRoutes 与派发规则。
 - 默认主模型起点与偏移：../src/effort.ts；Claude 子表 Haiku/Sonnet/Opus/Opus；GPT 子表 Luna/Sol/Sol/Sol。
 - 子工具：../src/subagent-tool.ts，单独判断子任务；指定模型时只调 effort；校验目录与允许列表。
-- 包内指导：../skills/subagent-model-routing/SKILL.md，主要约束选模、调用与复用；是否派发的场景主要位于 ../../../instructions/dsh-home.md。历史提交 14d68627（2026-10-22）已明确加入较大编码、独立复核、大量探索、可并行工作的派发规则，以及小修复/讨论不派发；这确认用户记忆中的委派要求确实曾落地，但不是所有简单任务强制派发。
+- 包内指导：../skills/subagent-model-routing/SKILL.md，主要约束选模、调用与复用；是否派发的场景主要位于 [主仓环境指令](https://github.com/prgrmrwy/ohmydsh/blob/main/instructions/dsh-home.md)（可选背景，不是插件加载依赖）。历史提交 14d68627（2026-10-22）已明确加入较大编码、独立复核、大量探索、可并行工作的派发规则，以及小修复/讨论不派发；这确认用户记忆中的委派要求确实曾落地，但不是所有简单任务强制派发。
 - 来源与评估范围：../eval/README.md，现有回归是判档一致性，不是最终任务质量/速度/费用基准。
 
 ## Gap 与建议（待调研校准，不是实施授权）

package/docs/routing-strategy-plan.md

@@ -95,7 +95,7 @@ Jev 的价值不仅是体验和性能；误判会损害质量。但策略质量
 
 - [核心诉求与差距](routing-intent-and-gaps.md)
 - [外部调研](routing-community-research-2026-10-24.md)：历史调研建议，实施优先级以本修订为准。
-- [现行规范](../../../openspec/specs/auto-model-routing/spec.md)：仍描述当前行为，本稿不静默替换它。
+- [现行规范](https://github.com/prgrmrwy/ohmydsh/blob/main/openspec/specs/auto-model-routing/spec.md)：仍描述当前行为，本稿不静默替换它。
 - [Claude Code model configuration](https://code.claude.com/docs/en/model-config.md)：opusplan 是规划阶段 Opus、执行阶段 Sonnet，不等于固定强主监督轻子。
 - [Claude Code subagents](https://code.claude.com/docs/en/sub-agents.md)：主模型根据职责描述委派。
 - [Claude Code Agent Teams](https://code.claude.com/docs/en/agent-teams.md)：Lead 组织共享任务与协作，不天然保证异构模型或低成本。

package/lib/feedback.d.ts

@@ -62,6 +62,32 @@ export declare class FeedbackBook {
         feedback?: "appropriate" | "too-high" | "too-low" | "unknown" | null | undefined;
         feedbackAt?: number | undefined;
     } | undefined;
+    /** All folded bindings in file order (read-only; used by the usage report). */
+    entries(): {
+        sessionId: string;
+        messageId: string;
+        decisionId: number;
+        depth: string;
+        model: string;
+        effort: string;
+        snapshot?: {
+            decidedAt: number;
+            appliedAt: number;
+            policyVersion: string;
+            mappingVersion: string;
+            decisionProvider: string;
+            decisionModel: string;
+            ms: number;
+            provider: string;
+            requestSeq: number;
+            confidence?: number | undefined;
+            probabilities?: Record<string, number> | undefined;
+            requestTurn?: number | undefined;
+        } | undefined;
+        boundAt?: number | undefined;
+        feedback?: "appropriate" | "too-high" | "too-low" | "unknown" | null | undefined;
+        feedbackAt?: number | undefined;
+    }[];
     bind(record: FeedbackRecord): void;
     set(sessionId: string, messageId: string, feedback: typeof allocationFeedback[number] | null): void;
     private append;

package/lib/feedback.js

@@ -51,6 +51,8 @@ export class FeedbackBook {
     }
     key(sessionId, messageId) { return JSON.stringify([sessionId, messageId]); }
     lookup(sessionId, messageId) { const r = this.records.get(this.key(sessionId, messageId)); return r && structuredClone(r); }
+    /** All folded bindings in file order (read-only; used by the usage report). */
+    entries() { return [...this.records.values()].map(r => structuredClone(r)); }
     bind(record) { if (this.lookup(record.sessionId, record.messageId))
         return; const r = schema.parse({ ...record, boundAt: Date.now() }); this.append(r); this.records.set(this.key(r.sessionId, r.messageId), r); }
     set(sessionId, messageId, feedback) {

package/lib/usage-report.d.ts

@@ -0,0 +1,59 @@
+type Failure = 'decode-failed' | 'tail-incomplete' | 'parse-failed' | 'missing-log';
+export declare function buildReport(home: string, options?: {
+    since?: string;
+}): {
+    schema: number;
+    since: string | null;
+    failures: Record<Failure, number>;
+    excluded: {
+        child: number;
+        seeded: number;
+    };
+    coverage: {
+        userTurns: number;
+        turnsWithoutRecord: number;
+        unlinkedBindings: number;
+        autoSessionsWithoutRecord: number;
+    };
+    groups: {
+        version: string;
+        subgroups: {
+            model: string;
+            depth: string;
+            decisions: number;
+            sessions: number;
+            calls: number;
+            callsPerDecision: {
+                median: number;
+                max: number;
+            };
+            tokens: Record<string, {
+                sum: number | null;
+                mean: number | null;
+                present: number;
+                calls: number;
+            }>;
+            byEffort: {
+                [k: string]: {
+                    decisions: number;
+                    calls: number;
+                };
+            };
+            feedback: Record<string, number>;
+            conclusion: string;
+        }[];
+    }[];
+    referenceBeforeAuto: {
+        model: string;
+        calls: number;
+        sessions: number;
+        effort: {
+            [k: string]: number;
+        };
+        autoEffort: {
+            [k: string]: number;
+        };
+    }[];
+    caveats: string[];
+};
+export {};

package/lib/usage-report.js

@@ -0,0 +1,332 @@
+// Read-only, on-demand AUTO usage report (change auto-routing-usage-report).
+// Never writes, spawns, or touches the network; never echoes message text, paths or session ids.
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { zstdDecompressSync } from 'node:zlib';
+import { FeedbackBook } from './feedback.js';
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+const FIELDS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'];
+const FEEDBACK = ['appropriate', 'too-high', 'too-low', 'unknown'];
+const CAVEATS = [
+    'observational-not-controlled',
+    'scope-main-session-assistant-calls-only',
+    'only-applied-decisions-recorded',
+    'token-semantics-differ-by-provider',
+    'reference-before-auto-effort-only-confounded',
+    'mode-history-not-persisted',
+];
+const sorted = (record) => Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+const round = (n) => Math.round(n * 100) / 100;
+const bump = (record, key, by = 1) => { record[key] = (record[key] ?? 0) + by; };
+/** Split concatenated zstd frames; only a failing last segment counts as an unfinished tail. */
+function decode(bytes) {
+    const starts = [];
+    for (let i = bytes.indexOf(MAGIC); i !== -1; i = bytes.indexOf(MAGIC, i + 1))
+        starts.push(i);
+    if (starts[0] !== 0)
+        return undefined;
+    let text = '';
+    for (let i = 0; i < starts.length; i++) {
+        try {
+            text += zstdDecompressSync(bytes.subarray(starts[i], starts[i + 1])).toString('utf8');
+        }
+        catch {
+            if (i === starts.length - 1)
+                return { text, tail: true };
+            return undefined;
+        }
+    }
+    return { text, tail: false };
+}
+function lines(file, failures) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            failures['parse-failed']++;
+        }
+    }
+    return out;
+}
+function logPaths(home) {
+    const paths = new Map();
+    const root = join(home, 'sessions');
+    let dirs = [];
+    try {
+        dirs = readdirSync(root);
+    }
+    catch {
+        return paths;
+    }
+    for (const dir of dirs) {
+        let ids = [];
+        try {
+            ids = readdirSync(join(root, dir));
+        }
+        catch {
+            continue;
+        }
+        for (const id of ids) {
+            const file = join(root, dir, id, 'session.v4.jsonl.zstd');
+            if (existsSync(file))
+                paths.set(id, file);
+        }
+    }
+    return paths;
+}
+/** Calls in one session log, with the user turn each belongs to and the config in effect. */
+function readSession(file, failures) {
+    let decoded;
+    try {
+        decoded = decode(readFileSync(file));
+    }
+    catch {
+        decoded = undefined;
+    }
+    if (!decoded) {
+        failures['decode-failed']++;
+        return undefined;
+    }
+    if (decoded.tail)
+        failures['tail-incomplete']++;
+    const events = [];
+    for (const line of decoded.text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            failures['parse-failed']++;
+        }
+    }
+    const header = events.shift();
+    if (header?.type !== 'session') {
+        failures['decode-failed']++;
+        return undefined;
+    }
+    const calls = [];
+    const seen = new Set();
+    let turn, userTurn;
+    let config = {};
+    for (const event of events) {
+        const data = event.data ?? {};
+        if (event.type === 'turn/start')
+            turn = data.turn;
+        else if (event.type === 'user/message' && data.source?.kind === 'user' && turn !== undefined)
+            userTurn = turn;
+        else if (event.type === 'request/header' && data.header?.config)
+            config = data.header.config;
+        else if (event.type === 'assistant/message') {
+            const op = event.surfaceOp;
+            const append = op === undefined || op === 'append' || (typeof op === 'object' && op?.op === 'append');
+            const id = data.message?.id;
+            if (!append || typeof id !== 'string' || seen.has(id))
+                continue;
+            seen.add(id);
+            const usage = {};
+            for (const field of FIELDS)
+                if (typeof data.usage?.[field] === 'number')
+                    usage[field] = data.usage[field];
+            calls.push({ id, ...(userTurn === undefined ? {} : { userTurn }), time: event.time, usage, ...(config.model ? { model: config.model } : {}), ...(config.reasoningEffort ? { effort: config.reasoningEffort } : {}) });
+        }
+    }
+    return { header, calls };
+}
+function localMidnight(date) {
+    const [y, m, d] = date.split('-').map(Number);
+    const at = new Date(y, m - 1, d);
+    const offset = -at.getTimezoneOffset();
+    const sign = offset >= 0 ? '+' : '-';
+    const hh = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0'), mm = String(Math.abs(offset) % 60).padStart(2, '0');
+    return { ms: at.getTime(), label: `${date}T00:00:00${sign}${hh}:${mm}` };
+}
+function tokens(calls) {
+    const out = {};
+    for (const field of FIELDS) {
+        const values = calls.map(c => c.usage[field]).filter((v) => v !== undefined);
+        const sum = values.reduce((a, b) => a + b, 0);
+        out[field] = values.length ? { sum, mean: round(sum / values.length), present: values.length, calls: calls.length } : { sum: null, mean: null, present: 0, calls: calls.length };
+    }
+    return out;
+}
+function median(values) {
+    const s = [...values].sort((a, b) => a - b), mid = Math.floor(s.length / 2);
+    return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+export function buildReport(home, options = {}) {
+    const failures = { 'decode-failed': 0, 'tail-incomplete': 0, 'parse-failed': 0, 'missing-log': 0 };
+    const state = join(home, 'state/auto-model-routing');
+    const since = options.since ? localMidnight(options.since) : undefined;
+    const after = (time) => !since || time >= since.ms;
+    const feedbackFile = join(state, 'allocation-feedback.jsonl');
+    lines(feedbackFile, failures); // counts unparsable lines; FeedbackBook skips them silently
+    const book = new FeedbackBook(feedbackFile);
+    const bindings = book.entries();
+    const legacyFirst = new Map();
+    for (const line of lines(join(state, 'judgements.jsonl'), failures)) {
+        if (typeof line?.sessionId !== 'string' || !Number.isInteger(line.turn) || typeof line.tier !== 'string')
+            continue;
+        legacyFirst.set(line.sessionId, Math.min(legacyFirst.get(line.sessionId) ?? Infinity, line.turn));
+    }
+    const ledgerSessions = [...new Set([...bindings.map(b => b.sessionId), ...legacyFirst.keys()])].sort();
+    const paths = logPaths(home);
+    const excluded = { child: 0, seeded: 0 };
+    const decisions = new Map();
+    const reference = {};
+    const autoEffort = {};
+    let unlinkedBindings = 0, userTurns = 0, turnsWithoutRecord = 0;
+    for (const session of ledgerSessions) {
+        const path = paths.get(session);
+        if (!path) {
+            failures['missing-log']++;
+            continue;
+        }
+        const log = readSession(path, failures);
+        if (!log)
+            continue;
+        if (log.header.origin) {
+            excluded.child++;
+            continue;
+        }
+        if (log.header.isSeeded === true) {
+            excluded.seeded++;
+            continue;
+        }
+        const linked = new Set();
+        let v2First;
+        for (const call of log.calls) {
+            const b = book.lookup(session, call.id);
+            if (!b)
+                continue;
+            linked.add(call.id);
+            if (call.userTurn !== undefined)
+                v2First = Math.min(v2First ?? Infinity, call.userTurn);
+            const key = JSON.stringify([session, b.decisionId]);
+            let d = decisions.get(key);
+            if (!d) {
+                d = { session, version: b.snapshot ? `${b.snapshot.policyVersion}/${b.snapshot.mappingVersion}` : 'unknown', model: b.model, depth: b.depth, effort: b.effort, calls: [], feedback: new Set() };
+                decisions.set(key, d);
+            }
+            d.calls.push(call);
+            if (b.feedback)
+                d.feedback.add(b.feedback);
+        }
+        unlinkedBindings += bindings.filter(b => b.sessionId === session && !linked.has(b.messageId)).length;
+        // Coverage: user turns from the first v2 record on, with calls in range but none linked.
+        if (v2First !== undefined) {
+            const turns = new Map();
+            for (const call of log.calls) {
+                if (call.userTurn === undefined || call.userTurn < v2First || !after(call.time))
+                    continue;
+                turns.set(call.userTurn, (turns.get(call.userTurn) ?? false) || linked.has(call.id));
+            }
+            userTurns += turns.size;
+            turnsWithoutRecord += [...turns.values()].filter(v => !v).length;
+        }
+        // Reference: calls before the earliest record in either ledger (effort only, never tokens).
+        const first = Math.min(legacyFirst.get(session) ?? Infinity, v2First ?? Infinity);
+        for (const call of log.calls) {
+            if (call.userTurn === undefined || call.userTurn >= first || !after(call.time) || !call.model)
+                continue;
+            const r = (reference[call.model] ??= { calls: 0, sessions: new Set(), effort: {} });
+            r.calls++;
+            r.sessions.add(session);
+            bump(r.effort, call.effort ?? 'unknown');
+        }
+    }
+    const kept = [...decisions.values()].filter(d => after(Math.min(...d.calls.map(c => c.time))));
+    for (const d of kept)
+        bump((autoEffort[d.model] ??= {}), d.effort, d.calls.length);
+    const versions = new Map();
+    for (const d of kept) {
+        const byVersion = versions.get(d.version) ?? new Map();
+        versions.set(d.version, byVersion);
+        const key = JSON.stringify([d.model, d.depth]);
+        byVersion.set(key, [...(byVersion.get(key) ?? []), d]);
+    }
+    const groups = [...versions].sort(([a], [b]) => a.localeCompare(b)).map(([version, subs]) => ({
+        version,
+        subgroups: [...subs].sort(([a], [b]) => a.localeCompare(b)).map(([key, list]) => {
+            const [model, depth] = JSON.parse(key);
+            const calls = list.flatMap(d => d.calls);
+            const sessions = new Set(list.map(d => d.session)).size;
+            const feedback = { ...Object.fromEntries(FEEDBACK.map(f => [f, 0])), conflict: 0, unrated: 0 };
+            for (const d of list)
+                bump(feedback, d.feedback.size === 0 ? 'unrated' : d.feedback.size > 1 ? 'conflict' : [...d.feedback][0]);
+            const byEffort = {};
+            for (const d of list) {
+                const e = (byEffort[d.effort] ??= { decisions: 0, calls: 0 });
+                e.decisions++;
+                e.calls += d.calls.length;
+            }
+            return {
+                model, depth, decisions: list.length, sessions, calls: calls.length,
+                callsPerDecision: { median: median(list.map(d => d.calls.length)), max: Math.max(...list.map(d => d.calls.length)) },
+                tokens: tokens(calls), byEffort: sorted(byEffort), feedback,
+                conclusion: list.length >= 20 && sessions >= 3 ? 'observed' : 'insufficient-sample',
+            };
+        }),
+    }));
+    const recorded = new Set(ledgerSessions.map(s => createHash('sha256').update(s).digest('hex')));
+    let autoSessionsWithoutRecord = 0;
+    let stateFiles = [];
+    try {
+        stateFiles = readdirSync(join(state, 'sessions')).filter(f => f.endsWith('.json')).sort();
+    }
+    catch { /* none */ }
+    for (const file of stateFiles) {
+        let mode;
+        try {
+            mode = JSON.parse(readFileSync(join(state, 'sessions', file), 'utf8'))?.mode;
+        }
+        catch {
+            failures['parse-failed']++;
+            continue;
+        }
+        if (mode === 'AUTO' && !recorded.has(file.slice(0, -5)))
+            autoSessionsWithoutRecord++;
+    }
+    return {
+        schema: 1,
+        since: since?.label ?? null,
+        failures, excluded,
+        coverage: { userTurns, turnsWithoutRecord, unlinkedBindings, autoSessionsWithoutRecord },
+        groups,
+        referenceBeforeAuto: Object.keys(reference).sort().map(model => ({
+            model, calls: reference[model].calls, sessions: reference[model].sessions.size,
+            effort: sorted(reference[model].effort), autoEffort: sorted(autoEffort[model] ?? {}),
+        })),
+        caveats: CAVEATS,
+    };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        const { values } = parseArgs({ options: { since: { type: 'string' } } });
+        if (values.since !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(values.since)) {
+            process.stderr.write('usage-report: --since must be YYYY-MM-DD\n');
+            process.exit(2);
+        }
+        const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+        process.stdout.write(`${JSON.stringify(buildReport(home, values.since ? { since: values.since } : {}), null, 2)}\n`);
+    }
+    catch {
+        process.stderr.write('usage-report: failed\n');
+        process.exit(1);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-auto-model-routing",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "DeepSeek Harness plugin: independent Jev capability and effort decisions, enforced fresh-child routes, decision visibility and allocation feedback",
   "license": "MIT",
   "author": "prgrmrwy",

package/skills/auto-model-routing-report/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: auto-model-routing-report
+description: 仅当用户明确要求评估 AUTO 效果、观察 AUTO 期间的 token 用量或判断分布，或直接点名 auto-model-routing-report 时使用：只读汇总本地 AUTO 决策记录与会话实际用量。不得主动执行或创建定时任务；会话处于 AUTO、普通 token 问题、路由判断或日常任务都不是触发条件。
+---
+
+# AUTO 用量观察报告
+
+**仅当用户明确要求时使用。** 不得主动执行，也不得创建定时任务或后台采集。会话处于 AUTO、用户询问 token 计价、讨论路由策略，都不是使用本 skill 的理由。
+
+## 它能回答什么
+
+- AUTO 期间做了哪些决策，按策略版本、模型和推理深度（depth）分组，以及这些决策实际消耗了多少 token。
+- 数据覆盖情况：哪些回合没有记录，以及有多少会话处于 AUTO 但完全没有记录。
+- 对照首个 AUTO 记录之前的回合，effort 起点发生了什么变化。
+
+**它不能回答“AUTO 省了多少”**：这是观察数据，不是受控对照。
+
+## 步骤
+
+1. 运行（只读：不写文件、不联网、不调用模型）：
+
+   ```bash
+   node "<插件目录>/lib/usage-report.js"                     # 全部数据
+   node "<插件目录>/lib/usage-report.js" --since 2026-11-01  # 从本地时区该日 00:00 起
+   ```
+
+   `<插件目录>` 是 `dsh-auto-model-routing` 包所在的目录。`$DSH_HOME` 未设置时，默认读取 `~/.dsh`。
+
+2. **先检查数据质量，再看数字：**
+   - `failures` 中任一项明显不为 0，或 `coverage.unlinkedBindings` 偏高时，说明日志格式可能已随 DSH 升级而变化。此时停止解读，先告诉用户需要核对。
+   - `failures.tail-incomplete` 为 1 通常是正常的，因为当前会话的日志还在写入。
+
+3. 转述结果时**保留以下含义，不得放大**：
+   - `conclusion: insufficient-sample` → “样本不足，尚不能判断”。门槛是 ≥20 个决策，且来自 ≥3 个会话。
+   - `caveats` 中的每一项都要用一句话说明：
+     - `observational-not-controlled`：观察数据，不是受控对照；判断因果需要专门对照实验。
+     - `scope-main-session-assistant-calls-only`：不含子会话、压缩摘要、标题生成、Jev 判档和失败重试的用量，因此不能推出“节省”。
+     - `only-applied-decisions-recorded`：只记录实际生效的决策，已统计部分可能偏向某类回合；`coverage.turnsWithoutRecord` 显示缺口大小。
+     - `token-semantics-differ-by-provider`：不同 provider 的 token 口径可能不同，不要跨模型比较。
+     - `reference-before-auto-effort-only-confounded`：`referenceBeforeAuto` 只用于看 effort 起点的变化；它受会话阶段、任务类型、模型切换等因素混杂，不能当作对照组。
+     - `mode-history-not-persisted`：会话模式的切换历史没有保存，会话计数只是粗略参考。
+   - 不要自行计算节省百分比，不要说“质量不变”，也不要把“首个记录之前”称为 MANUAL。
+   - token 均值的分母是**出现该字段的调用数**（`present`）；值为 `null` 表示该字段从未出现，不是 0。
+
+4. 如果要把报告原文贴到当前会话之外，例如飞书或 issue，**先请用户确认**。模型名、provider 名可能包含内部信息。
+
+## 前提
+
+- 报告每次都从原始记录和会话日志重新计算，不保存快照。用户删除旧会话后，对应历史无法再统计。
+- 旧版策略（legacy）的判档一致率请用同一插件目录下的 `scripts/label-report.mjs`。