@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/tools/index.ts

@@ -0,0 +1,274 @@
+/**
+ * The Agent tool surface of dsh-data-table (docs/issue/0022 P3b).
+ *
+ * Seven tools, one registry. Each `execute` delegates to a module beside this
+ * one, so the registry is a list of names, schemas and renderers — the part a
+ * reviewer reads to see what the Agent may do — and never the part that decides
+ * how a workbook changes.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { rollbackWorkbook } from '../workbook-manager.ts'
+import { projectScopeOf, runInProject, type SessionRegistry } from '../store/project.ts'
+import { optionalRevision, parseIndex } from '../request-params.ts'
+import { lineageOfArgs } from '../audit.ts'
+import { UNIVER_API_CATALOG, UNIVER_API_VERSION } from '../contract/univer-api-catalog.ts'
+import { optionalAuditText, optionalIntent, optionalString, parseNonEmptyString, workbookIdOf } from './arguments.ts'
+import {
+  asRecordOrUndefined,
+  asJsonValue,
+  renderCatalogResult,
+  renderEditResult,
+  renderFindResult,
+  renderHistoryResult,
+  renderReadResult,
+  renderSummaryAndValue,
+  spillLargeToolResult,
+} from './render.ts'
+import { asApiArguments, executeUniverApi, parseUniverApiAction } from './univer-api.ts'
+import { executeWorkbookCatalog } from './workbook-catalog.ts'
+import { executeWorkbookEdit } from './workbook-edit.ts'
+import { findWorkbookContent } from './workbook-find.ts'
+import { executeHistoryQuery } from './workbook-history.ts'
+import { readWorkbookTarget } from './workbook-read.ts'
+
+/** Register every workbook tool the Agent may call. */
+/** What `ctx.tools.register` accepts: the plugin's wrapper must produce the same shape. */
+type ToolDefinition = Parameters<Context['tools']['register']>[0]
+
+/**
+ * The Agent Session a tool call runs in.
+ *
+ * `agent.id` **is** the Session id (`Agent` is the live face of one Session), and
+ * it is the same id the browser sends as `x-dsh-session` — which is what lets the
+ * two halves name one directory. Empty when the call runs in no Agent at all.
+ */
+function sessionIdOf(exec: unknown): string {
+  return String((exec as { agent?: { id?: unknown } } | undefined)?.agent?.id ?? '')
+}
+
+export function registerWorkbookTools(ctx: Context): void {
+    // Every tool runs inside the calling Session's project, established once
+    // here rather than in each `execute`: the store root is read deep inside
+    // `workbook-manager`, and a second registration path that forgot the scope
+    // would read and write another project's workbooks.
+    const register = (definition: ToolDefinition): void => {
+      // The project comes from the Session **header**, through the Host's own
+      // registry — never from the calling Agent's Session object, whose `cwd` is
+      // not a field it has (see `store/project.ts`). When no Host service names a
+      // project (a test harness, an embedding with no policy) the wrapper leaves
+      // the scope unset instead of inventing one.
+      const projectOf = (exec: unknown): string | undefined =>
+        projectScopeOf((ctx as unknown as { sessions?: SessionRegistry }).sessions, sessionIdOf(exec))
+      ctx.tools.register({
+        ...definition,
+        execute: (args, exec) => {
+          const project = projectOf(exec)
+          const run = async (): Promise<unknown> => definition.execute(args, exec)
+          return project === undefined ? run() : runInProject(project, run)
+        },
+      })
+    }
+    register(defineTool({
+      name: 'workbook_catalog',
+      description: '工作簿目录与生命周期入口。action=list、create、rename、delete；任何数据读写都必须显式指定 workbookId。未指定 workbookId 时，存储文件名（= id）按 `yyyymmdd-中文名含义` 生成，中文名 ≤25 字。',
+      parameters: {
+        action: { type: 'string', required: true, enum: ['list', 'create', 'rename', 'delete'] },
+        workbookId: { type: 'string', description: 'create 时可指定稳定 id；rename/delete 时必填。指定时请遵循同一命名规则：`yyyymmdd-中文名含义`（如 20261002-销售汇总），中文名 ≤25 字；省略则由 name 自动生成。' },
+        name: { type: 'string', description: 'create/rename 时的工作簿名称，也是自动生成的 id 里那半段中文名的来源（≤25 字）。' },
+        confirm: { type: 'boolean', description: 'delete 必须显式传 true' },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderCatalogResult(value) },
+      async execute(args, exec) {
+        return asJsonValue(await spillLargeToolResult('workbook_catalog', await executeWorkbookCatalog(args)))
+      },
+    }))
+
+    register(defineTool({
+      name: 'workbook_read',
+      description: '读取明确工作簿内的 workbook、sheet、range 或 cells。sheet 可填写 sheet、sheetId 或 sheetName；单 sheet 工作簿可省略。target.kind=workbook 会返回 sheetName ↔ sheetId 映射与每个 sheet 的规模，先用本工具取得 revision，再将其作为 workbook_edit 的 baseRevision。',
+      parameters: {
+        workbookId: { type: 'string', required: true, description: '工作簿 id（必填）；先用 workbook_catalog(action=list) 获取' },
+        target: {
+          type: 'json',
+          required: true,
+          description: '目标：{ kind: workbook|sheet|range|cells, sheet?|sheetId?|sheetName?, range?, cells? }。sheet 可用 id 或名称；range 使用 0-based 坐标且结束坐标 inclusive；cells 为 [{row,column}]。',
+        },
+        include: { type: 'array', items: { type: 'string' }, description: '可选：values、formulas、cells、styles、snapshot、backfill。range 读取默认只返回 values；formulas / cells 是同一份数据的另两种视图，会成倍占用回显预算，仅在确实需要时按需索取。backfill 仅对 kind=workbook 有效：为每个 sheet 返回数据区行数、列数、结论行数、run 时间、来源与 schema 更新时间，以及 complete 提示，用于判断工作簿是否回填完整。' },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderReadResult(value) },
+      async execute(args) {
+        return asJsonValue(await spillLargeToolResult('workbook_read', await readWorkbookTarget(workbookIdOf(args.workbookId), args.target, args.include)))
+      },
+    }))
+
+    register(defineTool({
+      name: 'workbook_find',
+      description: '在指定工作簿中查找 sheet 名、单元格值或公式。sheet 可填写 id 或名称。不会修改任何内容。',
+      parameters: {
+        workbookId: { type: 'string', required: true, description: '工作簿 id（必填）；先用 workbook_catalog(action=list) 获取' },
+        query: { type: 'string', required: true, description: '查找文本；match=regex 时为正则表达式' },
+        scope: { type: 'string', enum: ['sheets', 'cells', 'formulas'], description: '默认 cells' },
+        match: { type: 'string', enum: ['contains', 'exact', 'regex'], description: '默认 contains' },
+        sheet: { type: 'string', description: '可选 sheet id 或名称；也接受 sheetId/sheetName' },
+        range: { type: 'json', description: '可选 0-based 搜索范围（结束坐标 inclusive）' },
+        limit: { type: 'number', description: '默认 100，最多 500' },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderFindResult(value) },
+      async execute(args) {
+        return asJsonValue(await spillLargeToolResult('workbook_find', await findWorkbookContent(workbookIdOf(args.workbookId), args)))
+      },
+    }))
+
+    register(defineTool({
+      name: 'workbook_edit',
+      description: '唯一的业务写入口。一个语义 versions 分组落为一个可回放 Version，分组内 commands 是按顺序记录的 Step；Host 负责 revision、Version 和并发控制，Agent 不得传 versionId。command 的 sheet、sheetId、sheetName 可互换；单 sheet 工作簿可省略 sheet。兼容 commands 简写：整组命令视为一个 Version。批量结果落表优先用 import_file 或 update_cells + sourcePath（一次命令 + 一个本地文件路径），不要把大数据逐格内联进 values。',
+      parameters: {
+        workbookId: { type: 'string', required: true, description: '工作簿 id（必填）；先用 workbook_catalog(action=list) 获取' },
+        baseRevision: { type: 'number', description: '可选的乐观锁，仅在需要阻止覆盖他人修改时传；不传表示接受当前主线。只做单元格写入的计划在本值过期时会自动变基到最新 revision 并返回 transformed: true；含行/列结构操作的计划才会返回 REVISION_CONFLICT，此时重新读取后重试整个计划' },
+        opId: { type: 'string', description: '幂等请求 id；多个 Version 分组会派生稳定子 id' },
+        intent: { type: 'string', description: '本次编辑的简短业务意图，作为未单独声明 intent 的分组审计信息' },
+        agentRunId: { type: 'string', description: '可选 Agent 运行关联 id；仅用于审计同一次运行产生的多个 Version' },
+        sessionId: { type: 'string', description: '关联的 DSH session id' },
+        turnId: { type: 'string', description: '当前对话轮次 id' },
+        intentId: { type: 'string', description: '关联的意图 id' },
+        taskId: { type: 'string', description: '关联的业务任务 id' },
+        subtaskId: { type: 'string', description: '关联的业务子任务 id' },
+        parentSubtaskId: { type: 'string', description: '关联的父子任务 id' },
+        runId: { type: 'string', description: '本次执行尝试 id' },
+        traceId: { type: 'string', description: '可选技术追踪 id' },
+        domain: { type: 'string', description: '业务域，例如 data' },
+        dryRun: { type: 'boolean', description: 'true 时用与正式提交完全相同的校验路径在内存中预检，不写入历史；返回 revisionBefore/revisionAfter/affectedSheets/affectedCellCount/warnings 预检清单' },
+        versions: {
+          type: 'array',
+          items: { type: 'json' },
+          description: '推荐。1–20 个语义 Version 分组，每项为 { summary, intent?, commands }。summary 是用户可读的变更说明；commands 中的 1–100 条命令成为该 Version 的有序 Step。append_rows 超过 1000 行会自动拆成多个 Step；append_rows、update_cells、import_file 都可传 sourcePath 从本地 CSV/JSON/JSONL/XLSX/XLS 导入（≤128 MiB、最多 100000 行数据 × 50 列）；所有分组总数最多 100 条命令。整个编辑计划一次性提交。',
+        },
+        commands: {
+          type: 'array',
+          items: { type: 'json' },
+          description: '兼容简写。1–100 条声明式命令，整组作为一个 Version；与 versions 二选一。type 支持 update_cells、import_file、clear_range、delete_cells、insert_rows、delete_rows、insert_columns、delete_columns、create_sheet、duplicate_sheet、delete_sheet、rename_sheet、append_rows、format_cells、merge_cells、unmerge_cells、freeze_panes、set_column_width、set_row_height、sort_range、set_hyperlink、remove_hyperlink。duplicate_sheet 用于跨工作簿复用 sheet 布局：{ type: duplicate_sheet, sheet, name, sheetId?, fromWorkbookId? } 会新建一个 sheet 并复制源 sheet 的单元格内容（标题块、表头行、长 SQL 文本都算）与列宽；fromWorkbookId 省略时取当前工作簿，源 sheet 必须已存在（同一批次内刚创建的 sheet 不在此列）；样式、合并、冻结、数据校验不复制。命令字段可使用 sheet/sheetId/sheetName、fromWorkbookId、range、cells、values、data、name、index、count、columns、rows、sourcePath、sourceFormat、startRow、startColumn、headerRowIndex、verifyHeader、verifyCapacity、allowTruncate、style、freeze、sort、size、url、label、meta。update_cells 的单个 cell 还可给 valueFromFile（本地文本文件路径，≤1 MiB），用于把长文本（典型是 SQL）从文件写进单元格而不必内联进工具调用；同给 value 时 value 优先。range 的结束坐标 startRow/endRow/startColumn/endColumn 都是 inclusive（0-based）：想写 4 行 2 列请用 {startRow:4,startColumn:0,endRow:7,endColumn:1}。update_cells 省略 range 时按 values 从 startRow/startColumn 推导，两者都省略则默认落在第 1 行第 0 列（表头下方的首个数据行，会覆盖该处已有内容；要往数据区末尾追加请用 append_rows，要指定起点请显式传 startRow/startColumn）；range 与 values 冲突时以 values 为准并在返回值 warnings 中提示。批量导入通道：update_cells 省略 values 并给 sourcePath 时按文件数据落位；{ type: import_file, sheet, startRow, startColumn, sourcePath, sourceFormat?, verifyCapacity?, allowTruncate? } 是推荐的一次性导入命令，startRow 是必填的 0-based 起点，源文件第一行作为列名、只写入数据行，且第 0 行不必是表头，回执含 workbookId/revisionBefore/revisionAfter/sheetId/range/rowsWritten/cellsWritten/sourceRowCount/truncated/firstRow/lastRow/valuesHash 与自动扩容说明；源文件超出可写区间时默认报错，只有显式传 allowTruncate: true 才会截断导入（回执 truncated: true 并在 warnings 说明）。写入越界（含 update_cells）会自动扩容 rowCount，无需 insert_rows。append_rows 默认要求第 0 行就是表头且列名一致；报告型 sheet 请用 headerRowIndex 指向真实列头行（数据写在它下面，列头行本身不被覆盖），或用 import_file / update_cells + sourcePath；verifyHeader: false 只跳过列名文本比对，列数仍需一致。行上限 SHEET_MAX_ROWS=100000（物理行 0–100000，row 0 可为表头），单条命令超过 SHEET_MAX_APPEND_ROWS=1000 行时 append_rows 会自动拆成多个 Step。insert_rows/delete_rows 接受 range:{startRow,endRow} 或 index/startRow + count，insert_columns/delete_columns 接受 range:{startColumn,endColumn} 或 index/startColumn + count；count 缺省时按 range 跨度推导。create_sheet 可省略 sheetId（Host 会生成稳定 id），同一批次内后续命令可按 sheet 名引用新建的 sheet。同一 cell 在本次计划中被多次写入会返回 warnings。',
+        },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderEditResult(value) },
+      async execute(args, exec) {
+        return asJsonValue(await spillLargeToolResult('workbook_edit', await executeWorkbookEdit({
+          workbookId: workbookIdOf(args.workbookId),
+          versions: args.versions,
+          commands: args.commands,
+          baseRevision: optionalRevision(args.baseRevision),
+          opId: optionalString(args.opId),
+          intent: optionalIntent(args.intent),
+          agentRunId: optionalAuditText(args.agentRunId, 'agentRunId', 160),
+          lineage: lineageOfArgs(args, exec),
+          dryRun: args.dryRun === true,
+        })))
+      },
+    }))
+
+    register(defineTool({
+      name: 'workbook_history',
+      description: '历史查询入口。action=list 返回 Version（默认）及其隐藏 Step；diff 比较两个 revision；replay 读取某个 revision 或其中一个 step 的可回放快照。',
+      parameters: {
+        workbookId: { type: 'string', required: true, description: '工作簿 id（必填）；先用 workbook_catalog(action=list) 获取' },
+        action: { type: 'string', enum: ['list', 'diff', 'replay'], description: '默认 list' },
+        limit: { type: 'number', description: 'list 默认 20、最多 100' },
+        fromRevision: { type: 'number', description: 'diff 起始 revision' },
+        toRevision: { type: 'number', description: 'diff 终止 revision，或 replay 目标 revision' },
+        revision: { type: 'number', description: 'replay 目标 revision（优先于 toRevision）' },
+        step: { type: 'number', description: 'replay 中的 0-based Step；省略则读取整个 Version 末尾' },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderHistoryResult(value) },
+      async execute(args, exec) {
+        return asJsonValue(await spillLargeToolResult('workbook_history', await executeHistoryQuery(workbookIdOf(args.workbookId), args)))
+      },
+    }))
+
+    register(defineTool({
+      name: 'workbook_restore',
+      description: '将 workbook 恢复到某个可回放 revision，并作为新的恢复 Version 记录。原先后续版本保留为 superseded 历史，不会被删除。',
+      parameters: {
+        workbookId: { type: 'string', required: true, description: '工作簿 id（必填）；先用 workbook_catalog(action=list) 获取' },
+        targetRevision: { type: 'number', required: true, description: '要恢复到的 revision' },
+        baseRevision: { type: 'number', description: '当前 revision，用于并发保护' },
+        opId: { type: 'string', description: '可选幂等恢复操作 id' },
+        sessionId: { type: 'string', description: '关联的 DSH session id' },
+        turnId: { type: 'string', description: '当前对话轮次 id' },
+        intentId: { type: 'string', description: '关联的意图 id' },
+        taskId: { type: 'string', description: '关联的业务任务 id' },
+        subtaskId: { type: 'string', description: '关联的业务子任务 id' },
+        parentSubtaskId: { type: 'string', description: '关联的父子任务 id' },
+        runId: { type: 'string', description: '本次执行尝试 id' },
+        traceId: { type: 'string', description: '可选技术追踪 id' },
+        domain: { type: 'string', description: '业务域，例如 data' },
+      },
+      output: { schema: { type: 'json' }, render: (_args, value) => renderSummaryAndValue(`工作簿已恢复：${String(asRecordOrUndefined(value)?.workbookId ?? '')} revision=${String(asRecordOrUndefined(value)?.revision ?? 0)}`, value) },
+      async execute(args, exec) {
+        const id = workbookIdOf(args.workbookId)
+        const result = await rollbackWorkbook({
+          workbookId: id,
+          targetRevision: parseIndex(args.targetRevision, 'targetRevision'),
+          expectedRevision: optionalRevision(args.baseRevision),
+          actor: 'agent',
+          opId: optionalString(args.opId),
+          lineage: lineageOfArgs(args, exec),
+        })
+        return asJsonValue({ ok: true, workbookId: id, revision: result.meta.revision ?? 0, operation: result.operation })
+      },
+    }))
+
+    register(defineTool({
+      name: 'univer_api',
+      description: 'Univer Adapter Registry。action=catalog/search 发现已注册的安全能力；action=invoke 调用其中一个适配器。它不是任意 JavaScript 或原始 Injector 入口；所有写入仍会落为可回放历史。',
+      parameters: {
+        action: { type: 'string', required: true, enum: ['catalog', 'search', 'invoke'] },
+        query: { type: 'string', description: 'search 的关键词' },
+        workbookId: { type: 'string', description: 'invoke 时必填' },
+        api: { type: 'string', description: 'invoke 时必填；先用 catalog/search 确认' },
+        arguments: { type: 'json', description: 'invoke 参数，结构由 catalog 定义' },
+        baseRevision: { type: 'number', description: '写入适配器的并发基准' },
+        opId: { type: 'string', description: '写入适配器的幂等 id' },
+        sessionId: { type: 'string', description: '关联的 DSH session id' },
+        turnId: { type: 'string', description: '当前对话轮次 id' },
+        intentId: { type: 'string', description: '关联的意图 id' },
+        taskId: { type: 'string', description: '关联的业务任务 id' },
+        subtaskId: { type: 'string', description: '关联的业务子任务 id' },
+        parentSubtaskId: { type: 'string', description: '关联的父子任务 id' },
+        runId: { type: 'string', description: '本次执行尝试 id' },
+        traceId: { type: 'string', description: '可选技术追踪 id' },
+        domain: { type: 'string', description: '业务域，例如 data' },
+      },
+      output: {
+        schema: { type: 'json' },
+        render: (args, value) => {
+          const record = asRecordOrUndefined(value) ?? {}
+          const action = asRecordOrUndefined(args)?.action
+          const summary = action === 'catalog'
+            ? `Univer API 目录（version=${String(record.version ?? '')}，${Array.isArray(record.catalog) ? record.catalog.length : 0} 项）`
+            : action === 'search'
+              ? `搜索到 ${Array.isArray(record.results) ? record.results.length : 0} 个 Univer API`
+              : `Univer Adapter 调用已完成：workbookId=${String(record.workbookId ?? '')} revision=${String(record.revision ?? 0)}`
+          return renderSummaryAndValue(summary, value)
+        },
+      },
+      async execute(args, exec) {
+        const action = parseUniverApiAction(args.action)
+        if (action === 'catalog') return asJsonValue(await spillLargeToolResult('univer_api', { ok: true, version: UNIVER_API_VERSION, catalog: UNIVER_API_CATALOG }))
+        if (action === 'search') {
+          const query = parseNonEmptyString(args.query, 'query').toLowerCase()
+          const results = UNIVER_API_CATALOG.filter(definition => (definition.api + ' ' + definition.description + ' ' + (definition.operation ?? '')).toLowerCase().includes(query))
+          return asJsonValue(await spillLargeToolResult('univer_api', { ok: true, version: UNIVER_API_VERSION, query, results }))
+        }
+        const result = await executeUniverApi({
+          workbookId: workbookIdOf(args.workbookId),
+          api: parseNonEmptyString(args.api, 'api'),
+          arguments: asApiArguments(args.arguments),
+          expectedRevision: optionalRevision(args.baseRevision),
+          opId: optionalString(args.opId),
+          lineage: lineageOfArgs(args, exec),
+        })
+        return asJsonValue(await spillLargeToolResult('univer_api', result))
+      },
+    }))
+
+}

package/src/tools/render.ts

@@ -0,0 +1,301 @@
+/**
+ * How a tool result reaches the model (docs/issue/0022 P3b).
+ *
+ * A tool answers with text blocks, and a large value is spilled to disk with a
+ * pointer instead of being inlined into the conversation. Both decisions are
+ * about *presentation*, so they sit together and neither tool owns them.
+ */
+import { randomUUID } from 'node:crypto'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+import { formatCellReference } from '#contracts'
+import { operationSummary } from '../contract/operations.ts'
+import { toolOutputRoot } from '../store/paths.ts'
+import { pruneToolOutput } from '../store/retention.ts'
+import type { WorkbookOperation } from '../types.ts'
+
+export interface ToolTextBlock { type: 'text'; text: string }
+
+export function textBlock(text: string): ToolTextBlock {
+  return { type: 'text', text }
+}
+
+export function asRecordOrUndefined(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : undefined
+}
+
+export function renderSummaryAndValue(summary: string, value: unknown): ToolTextBlock[] {
+  const detailPath = asRecordOrUndefined(value)?.detailPath
+  const json = JSON.stringify(value, null, 2)
+  const header = summary.trim().length === 0 ? '' : `${summary}\n\n`
+  if (json.length <= TOOL_RESULT_INLINE_LIMIT) return [textBlock(`${header}${json}`)]
+  const preview = json.slice(0, TOOL_RESULT_INLINE_LIMIT)
+  const tail = typeof detailPath === 'string'
+    ? `\n…（结果过大，已截断）\n完整结果：${detailPath}（用 read 工具读取完整 JSON）`
+    : '\n…（结果过大，已截断）'
+  return [textBlock(`${header}${preview}${tail}`)]
+}
+
+/**
+ * Model-facing tool output.
+ *
+ * DSH treats `output.render` as the only content the model sees
+ * (harness `createSuccessResult`), so a constant string silently drops the
+ * whole workbook payload. These helpers keep a readable summary plus the real
+ * JSON inline, and oversized results are spilled to
+ * `<storage root>/tool-output/*.json` during `execute` and reported as
+ * `detailPath` instead of being truncated away.
+ */
+export const TOOL_RESULT_INLINE_LIMIT = 24_000
+
+/** Spill an oversized canonical value so the model can still page through it. */
+export async function spillLargeToolResult(toolName: string, value: unknown): Promise<Record<string, unknown>> {
+  const record = asRecordOrUndefined(value) ?? { value }
+  if (JSON.stringify(record).length <= TOOL_RESULT_INLINE_LIMIT) return record
+  const directory = toolOutputRoot()
+  const detailPath = join(directory, `${toolName}-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}.json`)
+  await mkdir(directory, { recursive: true })
+  await writeFile(detailPath, JSON.stringify(value, null, 2), 'utf8')
+  // Keep the directory bounded. Nothing used to, so these accumulated for the
+  // life of the installation.
+  await pruneToolOutput()
+  return { ...record, detailPath }
+}
+
+/** Keep large write payloads out of the model/tool transcript. */
+export function compactToolValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(compactToolValue)
+  if (typeof value !== 'object' || value === null) return value
+  const record = value as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(record)) {
+    if (key === 'operation' && isOperationRecord(item)) result[key] = operationReceipt(item)
+    else if ((key === 'operations' || key === 'rebasedOperations') && Array.isArray(item)) {
+      result[key] = item.map(candidate => isOperationRecord(candidate) ? operationReceipt(candidate) : compactToolValue(candidate))
+    }
+    else result[key] = compactToolValue(item)
+  }
+  return result
+}
+
+export function asJsonValue(value: unknown): JsonValue {
+  const serialized = JSON.stringify(compactToolValue(value))
+  if (serialized === undefined) throw new Error('工具结果无法序列化')
+  return JSON.parse(serialized) as JsonValue
+}
+
+export function isOperationRecord(value: unknown): value is WorkbookOperation {
+  if (typeof value !== 'object' || value === null) return false
+  const operation = value as Partial<WorkbookOperation>
+  return typeof operation.opId === 'string' && typeof operation.workbookId === 'string'
+    && typeof operation.revision === 'number' && typeof operation.type === 'string'
+    && typeof operation.timestamp === 'string' && typeof operation.payload === 'object'
+    && operation.payload !== null
+}
+
+export function operationReceipt(operation: WorkbookOperation): Record<string, unknown> {
+  const payload = operation.payload
+  const cells = Array.isArray(payload.cells) ? payload.cells : []
+  const range = payload.range ?? payload.merge
+  const sheetRef = payload.sheetId ?? payload.sheetName
+  const payloads = operation.type === 'batch' ? (payload.operations ?? []).map(step => step.payload) : [payload]
+  const sheetIds = [...new Set(payloads.map(item => item.sheetId ?? item.sheetName).filter((value): value is string => typeof value === 'string'))]
+  const totalCellCount = operation.type === 'batch'
+    ? payloads.reduce((total, item) => total + (Array.isArray(item.cells) ? item.cells.length : 0), 0)
+    : cells.length
+  const totalRowCount = operation.type === 'batch'
+    ? payloads.reduce((total, item) => total + (Array.isArray(item.rows) ? item.rows.length : 0), 0)
+    : Array.isArray(payload.rows) ? payload.rows.length : 0
+  return {
+    opId: operation.opId,
+    workbookId: operation.workbookId,
+    revision: operation.revision,
+    parentRevision: operation.parentRevision ?? Math.max(0, operation.revision - 1),
+    ...(operation.versionId === undefined ? {} : { versionId: operation.versionId }),
+    ...(operation.versionStatus === undefined ? {} : { versionStatus: operation.versionStatus }),
+    ...(operation.versionSummary === undefined ? {} : { versionSummary: operation.versionSummary }),
+    ...(operation.versionIntent === undefined ? {} : { versionIntent: operation.versionIntent }),
+    ...(operation.agentRunId === undefined ? {} : { agentRunId: operation.agentRunId }),
+    ...(operation.lineage === undefined ? {} : { lineage: operation.lineage }),
+    ...(operation.restoredFromRevision === undefined ? {} : { restoredFromRevision: operation.restoredFromRevision }),
+    actor: operation.actor,
+    type: operation.type,
+    timestamp: operation.timestamp,
+    summary: operationSummary(operation),
+    ...(sheetRef === undefined ? {} : { sheetId: sheetRef }),
+    ...(sheetIds.length > 0 && operation.type === 'batch' ? { sheetIds } : {}),
+    ...(totalCellCount > 0 ? { cellCount: totalCellCount } : {}),
+    ...(totalRowCount > 0 ? { rowCount: totalRowCount } : {}),
+    ...(range === undefined ? {} : { range }),
+  }
+}
+
+export interface SheetOverview {
+  id: string
+  name: string
+  rowCount: number
+  columnCount: number
+  maxRow: number | null
+  maxColumn: number | null
+  nonEmptyCells: number
+}
+
+export function isNonEmptyCell(cell: unknown): boolean {
+  const record = asRecordOrUndefined(cell)
+  if (record === undefined) return false
+  if (typeof record.f === 'string' && record.f.length > 0) return true
+  return record.v !== undefined && record.v !== null && record.v !== ''
+}
+
+/** Compact per-sheet map (`name ↔ id` + size) that Agent callers use to address sheets. */
+export function sheetOverviews(snapshot: unknown): SheetOverview[] {
+  const root = asRecordOrUndefined(snapshot) ?? {}
+  const sheets = asRecordOrUndefined(root.sheets) ?? {}
+  const order = Array.isArray(root.sheetOrder)
+    ? root.sheetOrder.filter((item): item is string => typeof item === 'string')
+    : Object.keys(sheets)
+  const result: SheetOverview[] = []
+  for (const id of order) {
+    const sheet = asRecordOrUndefined(sheets[id])
+    if (sheet === undefined) continue
+    let maxRow = -1
+    let maxColumn = -1
+    let nonEmptyCells = 0
+    const cellData = asRecordOrUndefined(sheet.cellData)
+    if (cellData !== undefined) {
+      for (const [rowKey, line] of Object.entries(cellData)) {
+        const row = Number(rowKey)
+        const cells = asRecordOrUndefined(line)
+        if (!Number.isInteger(row) || cells === undefined) continue
+        for (const [columnKey, cell] of Object.entries(cells)) {
+          const column = Number(columnKey)
+          if (!Number.isInteger(column)) continue
+          maxRow = Math.max(maxRow, row)
+          maxColumn = Math.max(maxColumn, column)
+          if (isNonEmptyCell(cell)) nonEmptyCells += 1
+        }
+      }
+    }
+    result.push({
+      id,
+      name: typeof sheet.name === 'string' ? sheet.name : id,
+      rowCount: typeof sheet.rowCount === 'number' ? sheet.rowCount : 0,
+      columnCount: typeof sheet.columnCount === 'number' ? sheet.columnCount : 0,
+      maxRow: maxRow < 0 ? null : maxRow,
+      maxColumn: maxColumn < 0 ? null : maxColumn,
+      nonEmptyCells,
+    })
+  }
+  return result
+}
+
+export function sheetMapSummary(sheets: readonly SheetOverview[]): string {
+  if (sheets.length === 0) return '当前工作簿没有 sheet。'
+  return sheets.map(sheet => {
+    // `== null` on purpose: callers that summarise a sheet without reading its
+    // cells leave these absent rather than null, and `workbook_catalog` was
+    // printing `rows 0-undefined × cols 0-undefined` because of it.
+    const extent = sheet.maxRow == null || sheet.maxColumn == null
+      ? '暂无数据'
+      : `数据 rows 0-${sheet.maxRow} × cols 0-${sheet.maxColumn}`
+    return `- ${sheet.name} ↔ ${sheet.id}（${extent}，非空 ${sheet.nonEmptyCells}）`
+  }).join('\n')
+}
+
+/** Inline `名称（id）` list used by self-healing error messages. */
+export function sheetReferenceList(snapshot: unknown): string {
+  const sheets = sheetOverviews(snapshot)
+  if (sheets.length === 0) return '（当前工作簿没有 sheet）'
+  return sheets.map(sheet => `${sheet.name}（${sheet.id}）`).join(' / ')
+}
+
+export function renderCatalogResult(value: unknown): ToolTextBlock[] {
+  const record = asRecordOrUndefined(value) ?? {}
+  const action = typeof record.action === 'string' ? record.action : 'list'
+  if (Array.isArray(record.workbooks)) {
+    const workbooks = record.workbooks as Array<Record<string, unknown>>
+    const lines = workbooks.map(item => `- ${String(item.id)}（${String(item.name)}）revision=${String(item.revision ?? 0)} sheets=${String(item.sheetCount ?? 0)} updatedAt=${String(item.updatedAt ?? '')}`)
+    return renderSummaryAndValue(workbooks.length === 0 ? '没有工作簿；请用 workbook_catalog(action=create) 创建。' : `共 ${workbooks.length} 个工作簿：\n${lines.join('\n')}`, value)
+  }
+  const workbook = asRecordOrUndefined(record.workbook)
+  if (workbook !== undefined) {
+    const sheets = Array.isArray(workbook.sheets) ? workbook.sheets as SheetOverview[] : []
+    return renderSummaryAndValue(`工作簿已就绪：${String(workbook.id)}（${String(workbook.name)}）revision=${String(workbook.revision ?? 0)}\n${sheetMapSummary(sheets)}`, value)
+  }
+  return renderSummaryAndValue(`工作簿目录操作已完成：action=${action}`, value)
+}
+
+export function renderReadResult(value: unknown): ToolTextBlock[] {
+  const record = asRecordOrUndefined(value) ?? {}
+  const parts = [`workbookId: ${String(record.workbookId ?? '')}，revision: ${String(record.revision ?? 0)}`]
+  const workbook = asRecordOrUndefined(record.workbook)
+  if (workbook !== undefined) {
+    const sheets = Array.isArray(workbook.sheets) ? workbook.sheets as SheetOverview[] : []
+    parts.push(`工作簿：${String(workbook.name ?? '')}，sheet 数：${sheets.length}`)
+    parts.push(sheetMapSummary(sheets))
+  }
+  const sheet = asRecordOrUndefined(record.sheet)
+  if (sheet !== undefined) parts.push(`sheet：${String(sheet.name ?? '')} ↔ ${String(sheet.id ?? '')}`)
+  const range = asRecordOrUndefined(record.range)
+  if (range !== undefined && typeof range.startRow === 'number') {
+    parts.push(`range：rows ${range.startRow}-${range.endRow} × cols ${range.startColumn}-${range.endColumn}（0-based，end inclusive）`)
+  }
+  if (Array.isArray(record.values)) {
+    const first = record.values[0]
+    parts.push(`values：${record.values.length} 行 × ${Array.isArray(first) ? first.length : 0} 列`)
+  } else if (Array.isArray(record.cells)) {
+    parts.push(`cells：${record.cells.length} 个`)
+  }
+  if (typeof record.detailPath === 'string') parts.push(`完整结果：${record.detailPath}`)
+  return renderSummaryAndValue(parts.join('\n'), value)
+}
+
+export function renderFindResult(value: unknown): ToolTextBlock[] {
+  const record = asRecordOrUndefined(value) ?? {}
+  const results = Array.isArray(record.results) ? record.results as Array<Record<string, unknown>> : []
+  const lines = results.slice(0, 20).map(item => `- ${formatCellReference({
+    sheet: typeof item.sheetName === 'string' ? item.sheetName : typeof item.sheetId === 'string' ? item.sheetId : '',
+    row: typeof item.row === 'number' ? item.row : 0,
+    column: typeof item.column === 'number' ? item.column : 0,
+  })} = ${JSON.stringify(item.value ?? null)}`)
+  const summary = `匹配 ${results.length} 处${record.truncated === true ? '（已截断，请缩小范围或提高 limit）' : ''}（query=${String(record.query ?? '')}，scope=${String(record.scope ?? '')}）`
+  return renderSummaryAndValue(lines.length === 0 ? summary : `${summary}\n${lines.join('\n')}`, value)
+}
+
+export function renderHistoryResult(value: unknown): ToolTextBlock[] {
+  const record = asRecordOrUndefined(value) ?? {}
+  if (Array.isArray(record.versions)) {
+    const versions = record.versions as Array<Record<string, unknown>>
+    const lines = versions.map(item => `- revision=${String(item.revision)} status=${String(item.status ?? '')} steps=${String(item.stepCount ?? '')} ${String(item.summary ?? '')}`)
+    return renderSummaryAndValue(`workbookId: ${String(record.workbookId ?? '')}，revision: ${String(record.revision ?? 0)}，Version ${versions.length} 个\n${lines.join('\n')}`, value)
+  }
+  return renderSummaryAndValue(`历史查询已完成：action=${String(record.action ?? '')}，workbookId=${String(record.workbookId ?? '')}`, value)
+}
+
+export function renderEditResult(value: unknown): ToolTextBlock[] {
+  const record = asRecordOrUndefined(value) ?? {}
+  const dryRun = record.dryRun === true
+  const lines = [
+    dryRun
+      ? `编辑预检通过，尚未写入（revision 保持 ${String(record.revision ?? record.revisionBefore ?? 0)}）。`
+      : `工作簿编辑已提交（revision ${String(record.revisionBefore ?? '?')} → ${String(record.revisionAfter ?? record.revision ?? '?')}）。`,
+    `workbookId: ${String(record.workbookId ?? '')}`,
+    `Version ${String(record.versionCount ?? 0)} 个 / 命令 ${String(record.commandCount ?? 0)} 条，影响 sheet：${Array.isArray(record.affectedSheets) && record.affectedSheets.length > 0 ? (record.affectedSheets as unknown[]).join('、') : '（无）'}，单元格 ${String(record.affectedCellCount ?? 0)} 个`,
+  ]
+  if (record.replayed === true) lines.push('该 opId 之前已提交，本次为幂等重放。')
+  if (record.transformed === true) {
+    const rebased = Array.isArray(record.rebasedOperations) ? record.rebasedOperations.length : 0
+    lines.push(`提交前检测到 ${rebased} 个并发编辑（均为单元格写入），已自动变基到最新 revision 后提交；行/列结构未变化，本计划的坐标仍然有效。`)
+  }
+  if (Array.isArray(record.warnings) && record.warnings.length > 0) {
+    lines.push('warnings：')
+    for (const warning of record.warnings as unknown[]) lines.push(`- ${String(warning)}`)
+  }
+  if (dryRun && Array.isArray(record.versions)) {
+    for (const version of record.versions as Array<Record<string, unknown>>) {
+      lines.push(`- ${String(version.summary ?? '')}：${String(version.stepCount ?? 0)} 个 step`)
+    }
+  }
+  return renderSummaryAndValue(lines.join('\n'), value)
+}