@twinsearth/dsh-master 3.2.9 → 3.3.0

package/worker/index.ts

@@ -138,6 +138,7 @@ export function buildWorkerDeps(options: WorkerEnvOptions = {}): { ticket: Ticke
       limits: options.limits,
       model: String(options.model ?? env.WORKER_LLM_MODEL ?? '') || undefined,
       redactValues: secretValuesOf(env),
+      compactMode: String(env.DSH_MASTER_COMPACT_MODE ?? '') || undefined,
     },
   }
 }
@@ -151,6 +152,7 @@ function cordisSink(ctx: CordisLike): WorkerSink {
     step: (step) => { try { ctx.emit?.('superagent:step', step) } catch { /* ignore */ } },
     phase: (phase) => { try { ctx.emit?.('superagent:phase', { phase, at: Date.now() }) } catch { /* ignore */ } },
     stream: (delta) => { try { ctx.emit?.('superagent:stream', delta) } catch { /* ignore */ } },
+    cost: (event) => { try { ctx.emit?.('superagent:cost', event) } catch { /* ignore */ } },
   }
 }
 
@@ -166,17 +168,96 @@ function composeSink(local: WorkerSink, remote: WorkerSink | null): WorkerSink {
       try { (remoteFn as ((...a: unknown[]) => void) | undefined)?.(...args) } catch { /* ignore */ }
     }) as NonNullable<WorkerSink[K]>
   }
-  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: CordisLike, ticketId: string, result: WorkerResult): unknown {
   try {
-    const cost = ctx.get?.('dshMasterCost') as { record?(input: Record<string, unknown>): unknown } | undefined
+    const cost = ctx.get?.('dshMasterCost') as {
+      record?(input: Record<string, unknown>): unknown
+      recordAttribution?(input: Record<string, unknown>): unknown
+      recordDegraded?(input: Record<string, unknown>): unknown
+      recordGovernance?(input: Record<string, unknown>): unknown
+      recordSubstitution?(input: Record<string, unknown>): unknown
+    } | undefined
     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: unknown = 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: unknown = 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: unknown = 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: unknown = 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/worker/llm-http.ts

@@ -11,6 +11,20 @@
 
 import type { ChatMessage, LLMClient, LLMRequest, LLMResponse, LLMStreamDelta, ToolCall } from './types.ts'
 
+/**
+ * §11：从 provider 的 usage 里读缓存命中量。
+ * 兼容 `prompt_tokens_details.cached_tokens`（OpenAI 风格）与顶层 `cached_tokens`。
+ * **拿不到就返回 undefined**，不写 0 —— 否则报表会把"未知"伪装成"没有缓存命中"。
+ */
+function readCachedTokens(usage: Record<string, unknown> | undefined): number | undefined {
+  if (!usage || typeof usage !== 'object') return undefined
+  const details = (usage as { prompt_tokens_details?: { cached_tokens?: unknown } }).prompt_tokens_details
+  const direct = (usage as { cached_tokens?: unknown }).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
+}
 export interface HttpLlmOptions {
   /** 例如 https://api.deepseek.com/v1；会拼接 /chat/completions。 */
   baseUrl: string
@@ -88,6 +102,8 @@ function fromWireResponse(payload: OpenAiResponse): LLMResponse {
           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,
@@ -147,10 +163,12 @@ function createStreamAccumulator(onDelta: (delta: LLMStreamDelta) => void) {
     if (typeof choice?.finish_reason === 'string') finishReason = choice.finish_reason
     if (chunk?.usage && typeof chunk.usage === 'object') {
       const raw = chunk.usage as Record<string, unknown>
+      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)

package/worker/sink-http.ts

@@ -9,7 +9,7 @@
  * 网络失败不能影响 Agent Loop：队列满或请求失败时静默丢弃并记一条本地错误。
  */
 
-import type { WorkerPhase, WorkerResult, WorkerSink, WorkerStep } from './types.ts'
+import type { CostHookEvent, WorkerPhase, WorkerResult, WorkerSink, WorkerStep } from './types.ts'
 
 export interface HttpSinkOptions {
   url: string
@@ -36,13 +36,15 @@ export interface HttpWorkerSink extends WorkerSink {
   step(step: WorkerStep): void
   stream(delta: { content?: string; toolName?: string }): void
   log(message: string): void
+  /** 3.3.0：成本切点事件，随普通批次发往 Router（与 step 同窗口）。 */
+  cost(event: CostHookEvent): void
   flush(): Promise<void>
   close(): Promise<void>
   done(result: WorkerResult): Promise<void>
 }
 
 interface SinkEvent {
-  type: 'phase' | 'step' | 'stream' | 'log'
+  type: 'phase' | 'step' | 'stream' | 'log' | 'cost'
   payload: unknown
   at: number
 }
@@ -114,6 +116,7 @@ export function createHttpSink(options: HttpSinkOptions): HttpWorkerSink {
     step: (step) => enqueue({ type: 'step', payload: step, at: Date.now() }),
     stream: (delta) => enqueue({ type: 'stream', payload: delta, at: Date.now() }),
     log: (message) => enqueue({ type: 'log', payload: { message }, at: Date.now() }),
+    cost: (event) => enqueue({ type: 'cost', payload: event, at: Date.now() }),
     async flush() {
       while (queue.length > 0) await flush()
     },

package/worker/spill.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · A1 spill 存储（设计 §6「强制约束」）。
+ *
+ * 「一次压缩后原文仍可经 spill 文件回读」——大输出先落盘，模型只看到摘要 + 回读路径，
+ * 避免「省 token 换瞎眼」。
+ *
+ * 安全边界：
+ *   * 只能写在 `<workspace>/.dsh-master/spill/` 之内（路径由本模块生成，不接受外部传入）；
+ *   * 写入前由调用方**脱敏**（Agent Loop 传入已 redact 的文本）；
+ *   * 总量与单文件都有上限，超出后按最旧淘汰（有界，不会把分身磁盘写满）；
+ *   * 文件名只含 `ticketId` 的安全片段 + step + 序号，不反射工具参数。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+export interface SpillFile {
+  /** 相对 workspace 的路径（模型可直接用 fs_read_file 读）。 */
+  relPath: string
+  bytes: number
+  lines: number
+}
+
+export interface SpillStoreOptions {
+  workspace: string
+  /** 目录（相对 workspace）；默认 `.dsh-master/spill`。 */
+  dir?: string
+  /** 单文件上限（字节）；超过则拒绝落盘（避免把超大输出写爆磁盘）。 */
+  maxFileBytes?: number
+  /** 目录总量上限（字节）；超出按最旧淘汰。 */
+  maxTotalBytes?: number
+  /** 保留文件数上限。 */
+  maxFiles?: number
+  clock?: () => number
+}
+
+export interface SpillStore {
+  /** 落盘一份原文；返回相对路径与体积。失败返回 null（调用方退回不落盘）。 */
+  save(input: { ticketId: string; stepIndex: number; toolName: string; text: string }): SpillFile | null
+  /** 读取已落盘的原文（测试/回读用）。 */
+  read(relPath: string): string | null
+  /** 目录统计。 */
+  stats(): { dir: string; files: number; bytes: number }
+  /** 清理本任务/全部（只在任务结束时调用）。 */
+  clear(): void
+}
+
+const safeSegment = (value: string, fallback: string): string => {
+  // 只保留字母数字与 _-：点号也剔除，确保文件名里不可能出现 `..` 片段。
+  const cleaned = String(value ?? '').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 48)
+  return cleaned === '' ? fallback : cleaned
+}
+
+export function createSpillStore(options: SpillStoreOptions): SpillStore {
+  const workspace = path.resolve(String(options.workspace))
+  const relDir = String(options.dir ?? path.join('.dsh-master', 'spill'))
+  const dir = path.resolve(workspace, relDir)
+  // 路径 jail：解析后必须仍在 workspace 内。
+  const inside = dir === workspace || dir.startsWith(`${workspace}${path.sep}`)
+  const maxFileBytes = Math.max(1024, Number(options.maxFileBytes ?? 512 * 1024) || 512 * 1024)
+  const maxTotalBytes = Math.max(maxFileBytes, Number(options.maxTotalBytes ?? 8 * 1024 * 1024) || 8 * 1024 * 1024)
+  const maxFiles = Math.max(1, Number(options.maxFiles ?? 40) || 40)
+  const clock = typeof options.clock === 'function' ? options.clock : () => Date.now()
+  let seq = 0
+
+  function listFiles(): Array<{ name: string; size: number; at: number }> {
+    try {
+      return fs.readdirSync(dir)
+        .map((name) => {
+          try {
+            const stat = fs.statSync(path.join(dir, name))
+            return stat.isFile() ? { name, size: stat.size, at: stat.mtimeMs } : null
+          } catch { return null }
+        })
+        .filter((item): item is { name: string; size: number; at: number } => item !== null)
+    } catch { return [] }
+  }
+
+  /** 淘汰：文件数 / 总字节超限时按最旧删除。 */
+  function evict(): void {
+    const files = listFiles().sort((a, b) => a.at - b.at)
+    let total = files.reduce((sum, file) => sum + file.size, 0)
+    let count = files.length
+    for (const file of files) {
+      if (count <= maxFiles && total <= maxTotalBytes) break
+      try { fs.rmSync(path.join(dir, file.name), { force: true }) } catch { /* ignore */ }
+      total -= file.size
+      count -= 1
+    }
+  }
+
+  function save(input: { ticketId: string; stepIndex: number; toolName: string; text: string }): SpillFile | null {
+    if (!inside) return null
+    const text = String(input?.text ?? '')
+    if (text.length === 0) return null
+    const bytes = Buffer.byteLength(text, 'utf8')
+    seq += 1
+    const name = `${safeSegment(input?.ticketId ?? '', 'ticket')}__s${Number(input?.stepIndex) || 0}__${seq}__${safeSegment(input?.toolName ?? 'tool', 'tool')}.txt`
+    const abs = path.resolve(dir, name)
+    if (!abs.startsWith(`${dir}${path.sep}`)) return null
+    try {
+      fs.mkdirSync(dir, { recursive: true })
+      // 单文件超限：拒绝落盘（调用方按「无法回读」降级，不静默截断原文）。
+      if (bytes > maxFileBytes) return null
+      fs.writeFileSync(abs, text, 'utf8')
+      evict()
+      return { relPath: path.relative(workspace, abs).split(path.sep).join('/'), bytes, lines: text.split('\n').length }
+    } catch {
+      return null
+    }
+  }
+
+  function read(relPath: string): string | null {
+    const abs = path.resolve(workspace, String(relPath ?? ''))
+    if (!abs.startsWith(`${workspace}${path.sep}`)) return null
+    try { return fs.readFileSync(abs, 'utf8') } catch { return null }
+  }
+
+  function stats() {
+    const files = listFiles()
+    return { dir: path.relative(workspace, dir).split(path.sep).join('/'), files: files.length, bytes: files.reduce((sum, file) => sum + file.size, 0) }
+  }
+
+  function clear(): void {
+    try { fs.rmSync(dir, { recursive: true, force: true }) } catch { /* ignore */ }
+    void clock
+  }
+
+  return Object.freeze({ save, read, stats, clear })
+}

package/worker/tool-batch.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · A3 `tool-batch`（批量调用，设计 §6）。
+ *
+ * 形态借鉴 dsh-ops 的 `batchingGuidance`，但**只做引导与纠偏**：
+ *   * **首轮一次教学**：把「可以在同一轮里发多个 tool_calls，它们按序执行」写进**历史**
+ *     （一条 user 消息），**不改系统提示词**；
+ *   * 之后只做**形状纠偏**（例如把多个操作塞进一个工具的数组参数、或一轮超出批量上限）：
+ *     追加一条提示，**不阻断、不改写模型程序**；
+ *   * 批量执行**复用现有工具实现**（`registry.execute`），不新开旁路；
+ *   * 不支持 PTC 执行模式时，模块整体 `skipped: unsupported-host`（显式状态，不静默）。
+ *
+ * A 组共同底线：任何压缩/隐藏/批量都**不得改变工具的可观察语义** ——
+ * 本模块从不改写 tool_call、从不拦截执行，只往历史里追加文字。
+ */
+
+
+
+export type BatchMode = 'native' | 'ptc'
+
+export interface BatchOptions {
+  enabled?: boolean
+  /** 期望的执行模式；本项目 Worker 是原生多调用（native），PTC 未实现。 */
+  mode?: BatchMode
+  /** 单轮批量上限（与 WorkerLimits.maxToolCallsPerStep 对齐）。 */
+  maxBatchPerTurn?: number
+}
+
+export interface BatchStatus {
+  /** `active` = 引导与纠偏生效；`skipped` = 不做任何事（显式给出原因）。 */
+  state: 'active' | 'skipped'
+  reason: string | null
+  mode: BatchMode
+  maxBatchPerTurn: number
+}
+
+/** 归一化后的工具调用（与 Agent Loop 的 validateToolCalls 输出一致）。 */
+export interface BatchCallView {
+  id: string
+  name: string
+  /** 原始 JSON 参数字符串（本模块只读，不改写）。 */
+  args: string
+}
+
+export interface BatchAdvisor {
+  status(): BatchStatus
+  /** 首轮教学文本（进历史；不含任何工具语义改写）。 */
+  guidance(): string
+  /**
+   * 形状纠偏：返回**要追加的提示文本**（不阻断执行）。
+   * 合规时返回 null。
+   */
+  review(calls: BatchCallView[]): { ok: boolean; correction: string | null; reason: string | null }
+  /** 本任务是否已教学过。 */
+  taught(): boolean
+  markTaught(): void
+  stats(): { taught: boolean; corrections: number }
+}
+
+/** 单次批量教学文本（一次性；之后不再重复注入）。 */
+export const BATCH_GUIDANCE = [
+  '【批量调用提示（一次性）】',
+  '你可以在同一轮里返回多个 tool_calls：它们会按返回顺序依次执行，每个结果都会回灌给你。',
+  '把互不依赖的读取/检索/写入合并到同一轮，能减少往返次数；有依赖时必须分轮。',
+  '不要把一个列表塞进单个工具的参数里伪装成批量（例如把多个路径写进一个 path 字段）；',
+  '请直接发多个 tool_calls。',
+].join('\n')
+
+export function createBatchAdvisor(options: BatchOptions = {}): BatchAdvisor {
+  const mode: BatchMode = options.mode === 'ptc' ? 'ptc' : 'native'
+  const maxBatchPerTurn = Math.max(1, Number(options.maxBatchPerTurn ?? 4) || 4)
+  const enabled = options.enabled !== false
+  let taught = false
+  let corrections = 0
+
+  // 本项目 Worker 走 chat/HTTP 工具回路，没有 PTC（程序化工具调用）执行器：
+  // 请求 PTC ⇒ 显式 skipped，而不是偷偷降级成 native。
+  const unsupported = mode === 'ptc'
+  const status = (): BatchStatus => (enabled && !unsupported
+    ? { state: 'active', reason: null, mode, maxBatchPerTurn }
+    : { state: 'skipped', reason: unsupported ? 'unsupported-host' : 'disabled-by-config', mode, maxBatchPerTurn })
+
+  function review(calls: BatchCallView[]): { ok: boolean; correction: string | null; reason: string | null } {
+    if (status().state !== 'active') return { ok: true, correction: null, reason: null }
+    const list = Array.isArray(calls) ? calls : []
+    if (list.length > maxBatchPerTurn) {
+      corrections += 1
+      return {
+        ok: false,
+        reason: 'batch-too-large',
+        correction: `【批量形状纠偏】本轮 ${list.length} 个 tool_calls 超过单轮上限 ${maxBatchPerTurn}；已全部按序执行，下一轮请拆分。`,
+      }
+    }
+    // 形状纠偏：单个工具的参数里出现「看起来像批量」的数组（>=2 项字符串），提示改发多个 tool_calls。
+    for (const call of list) {
+      let args: Record<string, unknown> = {}
+      try {
+        const parsed = JSON.parse(String(call?.args ?? '{}'))
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) args = parsed as Record<string, unknown>
+      } catch { continue }
+      const arrayish = Object.entries(args).filter(([, value]) => Array.isArray(value) && value.length >= 2 && value.every((item) => typeof item === 'string'))
+      if (arrayish.length > 0 && list.length === 1) {
+        corrections += 1
+        return {
+          ok: false,
+          reason: 'array-faked-batch',
+          correction: `【批量形状纠偏】把多个值塞进了 ${call.name} 的 ${arrayish.map(([key]) => key).join('/')} 参数；这不会被执行器当成批量。下一轮请改为在同一轮返回多个 tool_calls。`,
+        }
+      }
+    }
+    return { ok: true, correction: null, reason: null }
+  }
+
+  return Object.freeze({
+    status,
+    guidance: () => BATCH_GUIDANCE,
+    review,
+    taught: () => taught,
+    markTaught: () => { taught = true },
+    stats: () => ({ taught, corrections }),
+  })
+}