@twinsearth/dsh-master 3.2.9 → 3.3.0

package/worker/tool-compact.ts

@@ -0,0 +1,317 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 模块层 A · A1 `tool-compact`（工具输出紧凑化）。
+ *
+ * 只处理**已知内置工具**的输出形状，未知工具一律原样透传。三档模式：
+ *   * `off`     —— 不计算；
+ *   * `shadow`  —— 真算「本可节省多少」，但**仍返回原文**（默认档，零行为变化）；
+ *   * `enforce` —— 紧凑结果确实更短时才替换。
+ *
+ * 安全边界：紧凑化只作用于模型可见的工具回执文本，不改工具执行、不改权限、
+ * 不改错误码；`applied` 仅在 `compactChars < originalChars` 时为 true。
+ *
+ * 归因（设计 §5.4）：`estimatedTokens` 不是 `savedChars/4` 的近似，而是
+ * `baselineOutputTokens(toolName, 原始长度) − actualOutputTokens(紧凑长度)`，
+ * 拟合参数在 `worker/baseline-fit.ts` 冻结、版本随参数变更。
+ */
+
+import { attributedSavedTokens, A1_FIT_VERSION } from './baseline-fit.ts'
+
+export type CompactMode = 'off' | 'shadow' | 'enforce'
+
+export interface CompactInput {
+  toolName: string
+  args?: Record<string, unknown>
+  text: string
+}
+
+export interface CompactResult {
+  module: 'a1-compact'
+  toolName: string
+  mode: CompactMode
+  /** 是否是本模块能处理的工具（未知工具为 false）。 */
+  applicable: boolean
+  /** 是否真的替换了输出（仅 enforce 且更短时为 true）。 */
+  applied: boolean
+  evaluated: boolean
+  text: string
+  originalChars: number
+  compactChars: number
+  savedChars: number
+  /** §5.4 归因：固定拟合式给出的节省 token（baseline − actual）。 */
+  estimatedTokens: number
+  /** 拟合式版本；报表据此判断归因口径。 */
+  fitVersion: string
+  /** 大输出落盘信息（有则说明原文可回读）。 */
+  spill?: { relPath: string; bytes: number; lines: number }
+}
+
+const MODES: readonly CompactMode[] = Object.freeze(['off', 'shadow', 'enforce'])
+
+export function normalizeCompactMode(value?: string): CompactMode {
+  const raw = String(value ?? '').trim().toLowerCase()
+  return (MODES as readonly string[]).includes(raw) ? (raw as CompactMode) : 'shadow'
+}
+
+function compactListDir(text: string): string | null {
+  if (text === '(empty)') return text
+  const lines = text.split('\n')
+  const compact = []
+  for (const line of lines) {
+    if (line.startsWith('dir ')) compact.push(`${line.slice(4)}/`)
+    else if (line.startsWith('file ')) compact.push(line.slice(5))
+    else return null // 未知形状：不猜
+  }
+  return compact.join('\n')
+}
+
+function compactWriteFile(text: string): string | null {
+  const match = /^written (\d+) bytes to (.+)$/u.exec(text)
+  if (!match) return null
+  return `ok ${match[2]} (+${match[1]} B)`
+}
+
+function compactShell(text: string): string | null {
+  if (!/^STDOUT:/u.test(text)) return null
+  const match = /^STDOUT:\n([\s\S]*?)\nSTDERR:\n([\s\S]*)$/u.exec(text)
+  if (!match) return null
+  const stdout = match[1].replace(/[ \t]+$/gmu, '').replace(/\n{3,}/gu, '\n\n').trim()
+  const stderr = match[2].replace(/[ \t]+$/gmu, '').replace(/\n{3,}/gu, '\n\n').trim()
+  if (!stdout && !stderr) return '(no output)'
+  // grep -n 形态（path:line:text）优先进「命中行合并」，能省掉重复文件名。
+  if (!stderr) {
+    const grep = compactGrepLike(stdout)
+    if (grep !== null) return grep
+  }
+  if (!stderr) return stdout
+  if (!stdout) return `[stderr]\n${stderr}`
+  return `${stdout}\n[stderr]\n${stderr}`
+}
+
+/**
+ * 文件读取：**去冗余空行但保留行号**。
+ *
+ * 行号本身要花字符，所以这里算两个候选，取更短者（且必须短于原文才替换）：
+ *   a) 带行号 + 空行游程压缩 —— 定位性最好；
+ *   b) 只压空白/空行、不带行号 —— 兜底，保证绝不「越压越长」。
+ */
+function compactReadFile(text: string): string | null {
+  if (text === '') return null
+  const lines = text.split('\n')
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+
+  const plainOut: string[] = []
+  let plainBlank = 0
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/[ \t]+$/u, '')
+    if (line.trim() === '') {
+      plainBlank += 1
+      if (plainBlank > 1) continue
+    } else {
+      plainBlank = 0
+    }
+    plainOut.push(line)
+  }
+  while (plainOut.length > 0 && plainOut[plainOut.length - 1] === '') plainOut.pop()
+  const plain = plainOut.join('\n')
+
+  const numberedOut: string[] = []
+  let blankStart = -1
+  const flushBlanks = (endLine: number) => {
+    if (blankStart < 0) return
+    numberedOut.push(blankStart === endLine ? `⋯${blankStart}` : `⋯${blankStart}-${endLine}`)
+    blankStart = -1
+  }
+  for (let index = 0; index < lines.length; index += 1) {
+    const lineNo = index + 1
+    const line = lines[index].replace(/[ \t]+$/u, '')
+    if (line.trim() === '') {
+      if (blankStart < 0) blankStart = lineNo
+      continue
+    }
+    flushBlanks(lineNo - 1)
+    numberedOut.push(`${lineNo}: ${line}`)
+  }
+  flushBlanks(lines.length)
+  const numbered = numberedOut.join('\n')
+
+  const candidates = [numbered, plain].filter((candidate) => candidate.length < text.length)
+  if (candidates.length === 0) return null
+  // 优先带行号（定位性），但它必须确实更短。
+  return candidates.includes(numbered) ? numbered : plain
+}
+
+/* ------------------------------------------------------------------ *
+ * grep 形态（设计 §6：命中行 + 上下文一行）
+ *
+ * 本项目的 Worker 工具面暂无独立 grep 工具，但 shell 里的 `grep -n` 结果就是
+ * `path:line:text` 形态；这里对它做「同文件合并 + 每条命中带一处上下文」的压缩。
+ * ------------------------------------------------------------------ */
+
+const GREP_LINE = /^([^\s:][^:]*):(\d+):(.*)$/u
+
+function compactGrepLike(text: string): string | null {
+  const lines = text.split('\n').filter((line) => line !== '')
+  if (lines.length < 3) return null
+  const parsed = []
+  for (const line of lines) {
+    const match = GREP_LINE.exec(line)
+    if (!match) return null // 形状不符：不猜，原样返回
+    parsed.push({ file: match[1], line: Number(match[2]), text: match[3].trim() })
+  }
+  const byFile = new Map<string, Array<{ line: number; text: string }>>()
+  for (const hit of parsed) {
+    const list = byFile.get(hit.file) ?? []
+    list.push({ line: hit.line, text: hit.text })
+    byFile.set(hit.file, list)
+  }
+  const out: string[] = []
+  for (const [file, hits] of byFile) {
+    const sorted = [...hits].sort((a, b) => a.line - b.line)
+    // 同文件命中合并成一行：`path: 12: text | 13: text`
+    out.push(`${file}: ${sorted.map((hit) => `${hit.line}: ${hit.text}`).join(' | ')}`)
+  }
+  const compact = out.join('\n')
+  return compact.length < text.length ? compact : null
+}
+
+/* ------------------------------------------------------------------ *
+ * 错误回执：给「可执行的下一步」
+ * ------------------------------------------------------------------ */
+
+const ERROR_HINTS: Array<{ match: RegExp; hint: string }> = [
+  { match: /path-outside-mandate/u, hint: '改用 Mandate.scope 内的路径' },
+  { match: /sensitive-path-denied/u, hint: '该路径被禁止写入，换普通源码文件' },
+  { match: /file-too-large/u, hint: '先用 fs_list_dir 定位，再分段读取' },
+  { match: /not-a-file/u, hint: '该路径不是文件，先用 fs_list_dir 查看' },
+  { match: /content-too-large/u, hint: '拆成多次写入或改用片段修改' },
+  { match: /shell-(?:redirection|substitution|cd|parent-traversal|absolute-path|home-path|env-expansion)/u, hint: '去掉重定向/变量/绝对路径，只用单条只读命令' },
+  { match: /shell-git-write/u, hint: '写操作交给 create_pr，不要在 shell 里改远端' },
+  { match: /未授权执行 Shell|vmIsolation|隔离证明/u, hint: '当前 Manifest 未授权 Shell，改用文件工具' },
+  { match: /超时|aborted/u, hint: '缩小操作范围或拆分命令后重试' },
+]
+
+function compactError(text: string): string | null {
+  const isError = /^(?:执行报错|【系统拒绝】|错误[:：]|Error[:：])/u.test(text)
+    || /^(?:ENOENT|EACCES|EPERM|EISDIR|ENOTDIR)\b/u.test(text)
+  if (!isError) return null
+  const hint = ERROR_HINTS.find((item) => item.match.test(text))?.hint
+  if (!hint) return null
+  // 保留原始错误码/首行（可定位），把冗长堆栈压掉，再补一条可执行建议。
+  const firstLine = text.split('\n').map((line) => line.trim()).filter(Boolean)[0] ?? ''
+  const compact = `${firstLine}\n→ 建议: ${hint}`
+  return compact.length < text.length ? compact : null
+}
+
+function formatterFor(toolName: string): ((text: string) => string | null) | null {
+  if (toolName === 'fs_read_file') return (text) => compactError(text) ?? compactReadFile(text)
+  if (toolName === 'fs_list_dir') return (text) => compactError(text) ?? compactListDir(text)
+  if (toolName === 'fs_write_file') return (text) => compactError(text) ?? compactWriteFile(text)
+  if (toolName === 'exec_shell_in_vm') return (text) => compactError(text) ?? compactGrepLike(text) ?? compactShell(text)
+  return null
+}
+
+/** 大输出落盘后再给摘要（§6 强制约束：原文仍可经 spill 文件回读）。 */
+export interface SpillSink {
+  save(input: { text: string }): { relPath: string; bytes: number; lines: number } | null
+}
+
+export interface ToolCompactorOptions {
+  mode?: string
+  /** 提供后，超过阈值的回执先落盘再摘要（仅在 enforce 生效）。 */
+  spill?: SpillSink | null
+  /** 触发落盘的最小字符数（默认 6000）。 */
+  spillThresholdChars?: number
+  /** 摘要保留的头/尾行数。 */
+  spillHeadLines?: number
+  spillTailLines?: number
+}
+
+export interface ToolCompactor {
+  mode: CompactMode
+  compact(input: CompactInput): CompactResult
+}
+
+/** 头尾摘要 + 回读提示（大输出用）。 */
+function headTailSummary(text: string, spilled: { relPath: string; bytes: number; lines: number }, head: number, tail: number): string {
+  const lines = text.split('\n')
+  const headLines = lines.slice(0, head)
+  const tailLines = tail > 0 ? lines.slice(Math.max(head, lines.length - tail)) : []
+  const marker = `⋯[已落盘 ${spilled.relPath}：${spilled.bytes} B / ${spilled.lines} 行；完整内容用 fs_read_file 读取该路径]`
+  return [...headLines, marker, ...tailLines].join('\n')
+}
+
+export function createToolCompactor(options: ToolCompactorOptions = {}): ToolCompactor {
+  const mode = normalizeCompactMode(options.mode)
+  const spill = options.spill ?? null
+  const spillThresholdChars = Math.max(500, Number(options.spillThresholdChars ?? 6000) || 6000)
+  const spillHeadLines = Math.max(1, Number(options.spillHeadLines ?? 20) || 20)
+  const spillTailLines = Math.max(0, Number(options.spillTailLines ?? 5) || 5)
+
+  function compact(input: CompactInput): CompactResult {
+    const text = String(input?.text ?? '')
+    const toolName = String(input?.toolName ?? '')
+    // §6 强制约束：大输出先落盘（**只在 enforce**，shadow 不得产生副作用），再给摘要。
+    if (mode === 'enforce' && spill && text.length >= spillThresholdChars) {
+      const spilled = spill.save({ text })
+      if (spilled) {
+        const summary = headTailSummary(text, spilled, spillHeadLines, spillTailLines)
+        if (summary.length < text.length) {
+          return {
+            module: 'a1-compact',
+            toolName,
+            mode,
+            applicable: true,
+            evaluated: true,
+            applied: true,
+            text: summary,
+            originalChars: text.length,
+            compactChars: summary.length,
+            savedChars: text.length - summary.length,
+            estimatedTokens: attributedSavedTokens(toolName, text.length, summary.length),
+            fitVersion: A1_FIT_VERSION,
+            spill: spilled,
+          }
+        }
+      }
+    }
+    const base: CompactResult = {
+      module: 'a1-compact',
+      toolName,
+      mode,
+      applicable: false,
+      applied: false,
+      evaluated: false,
+      text,
+      originalChars: text.length,
+      compactChars: text.length,
+      savedChars: 0,
+      estimatedTokens: 0,
+      fitVersion: A1_FIT_VERSION,
+    }
+    if (mode === 'off') return base
+    const formatter = formatterFor(toolName)
+    if (!formatter) return base
+    const compacted = formatter(text)
+    if (compacted === null) return { ...base, applicable: true, evaluated: true }
+    const compactChars = compacted.length
+    const savedChars = Math.max(0, text.length - compactChars)
+    const applied = mode === 'enforce' && compactChars < text.length
+    return {
+      ...base,
+      applicable: true,
+      evaluated: true,
+      applied,
+      text: applied ? compacted : text,
+      compactChars,
+      savedChars,
+      // §5.4：归因用固定拟合式的差额，而不是 savedChars/4 的近似。
+      estimatedTokens: attributedSavedTokens(toolName, text.length, compactChars),
+      fitVersion: A1_FIT_VERSION,
+    }
+  }
+
+  return Object.freeze({ mode, compact })
+}

package/worker/tool-disclosure.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * 3.3.0 · A2 `tool-disclosure`（渐进式纰漏，设计 §6）。
+ *
+ * 目的：把**常驻工具面**收敛到有界集合（读/写/搜索/执行 + 少量必备），
+ * 高级工具（PDF/Word/批量改等）改为**按需加载**，避免 schema 常驻挤占 prompt。
+ *
+ * 纪律：
+ *   * 加载动作**本身计成本**：一次加载带来的 schema token 记入 `governance` 账
+ *     （归类：`phase:'authoring'` / `source:'authoring'` / `meta.kind:'tools.load'`），
+ *     报表里与 execution 节省并列展示，绝不混算成节省；
+ *   * 开关 `enabled` + `allowlist`；**关闭时恢复全量工具面**（fail-open 到原行为）；
+ *   * 只有 `enforce` 档真的收敛工具面；`shadow` 只记录「本可收敛」。
+ */
+
+import type { WorkerTool, ToolSchema } from './types.ts'
+
+export interface DisclosureOptions {
+  enabled?: boolean
+  /** 常驻工具（有界集合）。未列出的工具视为「高级工具」，需按需加载。 */
+  resident?: string[]
+  /** allowlist：为空表示「所有非常驻工具都可按需加载」；非空则只允许加载列出的工具。 */
+  allowlist?: string[]
+  /** 常驻集合之外是否真的隐藏（false = 全量暴露，等价于关闭）。 */
+  hideNonResident?: boolean
+}
+
+/** 默认常驻：只保留最基础的四类能力 + 加载入口本身。 */
+export const DEFAULT_RESIDENT_TOOLS = Object.freeze(['fs_read_file', 'fs_list_dir', 'fs_write_file', 'exec_shell_in_vm', 'load_tools'])
+
+export interface DisclosureState {
+  readonly enabled: boolean
+  /** 当前可见（模型能看到 schema）的工具名。 */
+  visible(allNames: string[]): string[]
+  /** 已按需加载的工具。 */
+  loaded(): string[]
+  /** 记录一次加载；返回本次加载带来的 schema token 估算（0 表示无变化）。 */
+  load(input: { names: string[]; schemas: ToolSchema[] }): { loaded: string[]; schemaTokens: number; schemaCount: number; events: number }
+  /** 本任务累计加载成本（供 governance 记账）。 */
+  stats(): { loadEvents: number; schemaTokens: number; schemaCount: number; loaded: string[] }
+  /** 判定某工具是否允许被加载（allowlist 约束）。 */
+  canLoad(name: string): boolean
+}
+
+const tokensOf = (text: string): number => (text.length > 0 ? Math.ceil(text.length / 4) : 0)
+
+export function createDisclosureState(options: DisclosureOptions = {}): DisclosureState {
+  const enabled = options.enabled === true
+  const resident = new Set(
+    (Array.isArray(options.resident) && options.resident.length > 0 ? options.resident : DEFAULT_RESIDENT_TOOLS)
+      .map((name) => String(name ?? '')),
+  )
+  const allowlist = new Set((Array.isArray(options.allowlist) ? options.allowlist : []).map((name) => String(name ?? '')))
+  const hideNonResident = options.hideNonResident !== false
+  const loadedSet = new Set<string>()
+  let loadEvents = 0
+  let schemaTokens = 0
+  let schemaCount = 0
+
+  function visible(allNames: string[]): string[] {
+    const names = allNames.map((name) => String(name ?? '')).filter(Boolean)
+    // 关闭（或未启用隐藏）⇒ 恢复全量工具面：fail-open 到原行为。
+    if (!enabled || !hideNonResident) return names
+    return names.filter((name) => resident.has(name) || loadedSet.has(name))
+  }
+
+  function canLoad(name: string): boolean {
+    const tool = String(name ?? '')
+    if (!tool) return false
+    if (resident.has(tool)) return true
+    if (allowlist.size === 0) return true
+    return allowlist.has(tool)
+  }
+
+  function load(input: { names: string[]; schemas: ToolSchema[] }): { loaded: string[]; schemaTokens: number; schemaCount: number; events: number } {
+    const requested = (Array.isArray(input?.names) ? input.names : []).map((name) => String(name ?? '')).filter(Boolean)
+    const newly = requested.filter((name) => !resident.has(name) && !loadedSet.has(name) && canLoad(name))
+    if (newly.length > 0) {
+      for (const name of newly) loadedSet.add(name)
+      loadEvents += 1
+      const schemas = (Array.isArray(input?.schemas) ? input.schemas : []).filter((schema) => newly.includes(String(schema?.name ?? '')))
+      schemaCount += schemas.length
+      schemaTokens += tokensOf(JSON.stringify(schemas))
+    }
+    return { loaded: [...loadedSet], schemaTokens, schemaCount, events: loadEvents }
+  }
+
+  return Object.freeze({
+    enabled,
+    visible,
+    loaded: () => [...loadedSet],
+    load,
+    canLoad,
+    stats: () => ({ loadEvents, schemaTokens, schemaCount, loaded: [...loadedSet] }),
+  })
+}
+
+/**
+ * `load_tools` 元工具：模型用它「按需加载」高级工具，返回值里带完整 schema。
+ * 常驻于工具面（否则模型无法表达加载意图）。
+ */
+export function createLoadToolsTool(state: DisclosureState, tools: WorkerTool[]): WorkerTool {
+  return {
+    name: 'load_tools',
+    description: '按需加载高级工具（返回其完整 schema）。参数 names 为工具名数组。',
+    parameters: {
+      type: 'object',
+      properties: { names: { type: 'array', items: { type: 'string' } } },
+      required: ['names'],
+    },
+    async execute(args) {
+      const requested = Array.isArray(args?.names) ? args.names.map((name) => String(name ?? '')) : []
+      if (requested.length === 0) return '执行报错: names 不能为空'
+      const known = new Set(tools.map((tool) => tool.name))
+      const unknown = requested.filter((name) => !known.has(name))
+      const denied = requested.filter((name) => known.has(name) && !state.canLoad(name))
+      const schemas = tools
+        .filter((tool) => requested.includes(tool.name) && known.has(tool.name) && state.canLoad(tool.name))
+        .map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }))
+      const result = state.load({ names: schemas.map((schema) => schema.name), schemas })
+      const lines: string[] = []
+      if (schemas.length > 0) lines.push(`已加载 ${schemas.length} 个工具，完整 schema：\n${JSON.stringify(schemas, null, 2)}`)
+      if (unknown.length > 0) lines.push(`未知工具: ${unknown.join(', ')}`)
+      if (denied.length > 0) lines.push(`不在 allowlist，拒绝加载: ${denied.join(', ')}`)
+      lines.push(`累计加载 ${result.events} 次，schema token ≈ ${result.schemaTokens}`)
+      return lines.join('\n')
+    },
+  }
+}