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

package/lib/types/tools/cells.js

@@ -0,0 +1,298 @@
+/**
+ * Payload vocabulary shared by the two tools that write to a workbook
+ * (docs/issue/0022 P3b).
+ *
+ * `workbook_edit` and `univer_api` both accept a value matrix plus a range, both
+ * accept cells whose value comes from a file, both declare a table's columns, and
+ * both size a row or column. That translation lives here rather than in either
+ * tool: a tool importing the other tool is exactly the coupling this phase
+ * exists to prevent, and every helper here is about building a payload, not about
+ * which endpoint received it.
+ */
+import { statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { SHEET_MAX_COLUMNS, SHEET_MAX_NAME, SHEET_MAX_ROWS, } from "../types.js";
+import { parseA1Range, parseIndex, parseRange } from "../request-params.js";
+import { asToolArguments, parseNonEmptyString } from "./arguments.js";
+/** Sheet column types a modelled table may declare. */
+const COLUMN_TYPES = ['string', 'number', 'boolean', 'date', 'currency'];
+export function parseCells(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw new Error('cells 必须是非空数组');
+    if (value.length > SHEET_MAX_ROWS * SHEET_MAX_COLUMNS)
+        throw new Error('一次修改的单元格数量超过上限');
+    return value.map((item, index) => {
+        if (typeof item !== 'object' || item === null || Array.isArray(item))
+            throw new Error(`第 ${index + 1} 个 cell 不是对象`);
+        const raw = item;
+        const cellValue = raw.value;
+        if (cellValue !== null && typeof cellValue !== 'string' && typeof cellValue !== 'number' && typeof cellValue !== 'boolean') {
+            throw new Error(`第 ${index + 1} 个 cell 的 value 必须是 string/number/boolean/null`);
+        }
+        if (typeof cellValue === 'number' && !Number.isFinite(cellValue))
+            throw new Error(`第 ${index + 1} 个 cell 的 value 不是有限数字`);
+        if (raw.formula !== undefined && typeof raw.formula !== 'string')
+            throw new Error(`第 ${index + 1} 个 cell 的 formula 必须是字符串`);
+        return {
+            row: parseIndex(raw.row, `cells[${index}].row`),
+            column: parseIndex(raw.column, `cells[${index}].column`),
+            value: cellValue,
+            ...(raw.formula === undefined ? {} : { formula: raw.formula }),
+        };
+    });
+}
+/**
+ * Resolve `cells[].valueFromFile` into a literal value (docs/issue/0011 I4 / T7).
+ *
+ * Long text had to be inlined into the tool call, and the same SQL was retyped
+ * into every workbook that needed it. A cell may now name a local text file
+ * instead. The content is read here and handed to the ordinary `parseCells`
+ * validation, so nothing bypasses the existing cell limits.
+ */
+export async function resolveCellFileValues(value, label) {
+    return Promise.all(value.map(async (item, index) => {
+        if (typeof item !== 'object' || item === null || Array.isArray(item))
+            return item;
+        const raw = item;
+        if (raw.valueFromFile === undefined || raw.valueFromFile === null)
+            return item;
+        const path = resolve(parseNonEmptyString(raw.valueFromFile, `${label}.cells[${index}].valueFromFile`));
+        let info;
+        try {
+            info = statSync(path);
+        }
+        catch {
+            throw new Error(`${label}.cells[${index}].valueFromFile 文件不存在：${path}`);
+        }
+        if (!info.isFile())
+            throw new Error(`${label}.cells[${index}].valueFromFile 不是文件：${path}`);
+        if (info.size > TEXT_CELL_MAX_BYTES) {
+            throw new Error(`${label}.cells[${index}].valueFromFile 文件过大（${info.size} 字节，上限 ${TEXT_CELL_MAX_BYTES}）`);
+        }
+        const content = await readFile(path, 'utf8');
+        const { valueFromFile: _consumed, ...rest } = raw;
+        // An explicit `value` still wins, so the field is a fallback rather than an
+        // override that could silently disagree with the caller.
+        return raw.value === undefined ? { ...rest, value: content } : rest;
+    }));
+}
+/**
+ * Resolve the target range of a value matrix.
+ *
+ * The matrix size is unambiguous, so it is the authority: `range` only needs
+ * to anchor the write, and a `range` whose declared end disagrees with
+ * `values` is corrected and reported as a warning instead of failing a large
+ * batch. End coordinates are inclusive, which the tool description now states.
+ */
+export function parseValueRange(value, matrix, label, warnings = []) {
+    const rowCount = matrix.length;
+    const columnCount = matrix[0]?.length ?? 0;
+    const derived = (startRow, startColumn) => parseRange({ startRow, startColumn, endRow: startRow + rowCount - 1, endColumn: startColumn + columnCount - 1 });
+    if (value === undefined || value === null)
+        return derived(1, 0);
+    let startRow;
+    let startColumn;
+    let declaredEndRow;
+    let declaredEndColumn;
+    if (typeof value === 'string') {
+        const parsed = parseA1Range(value);
+        startRow = parsed.startRow;
+        startColumn = parsed.startColumn;
+        declaredEndRow = parsed.endRow;
+        declaredEndColumn = parsed.endColumn;
+    }
+    else {
+        const raw = asToolArguments(value, label + '.range');
+        startRow = raw.startRow === undefined ? 1 : parseIndex(raw.startRow, label + '.range.startRow');
+        startColumn = raw.startColumn === undefined ? 0 : parseIndex(raw.startColumn, label + '.range.startColumn');
+        declaredEndRow = raw.endRow === undefined ? undefined : parseIndex(raw.endRow, label + '.range.endRow');
+        declaredEndColumn = raw.endColumn === undefined ? undefined : parseIndex(raw.endColumn, label + '.range.endColumn');
+    }
+    const target = derived(startRow, startColumn);
+    if (declaredEndRow === undefined && declaredEndColumn === undefined)
+        return target;
+    if (declaredEndRow === target.endRow && declaredEndColumn === target.endColumn)
+        return target;
+    // Supplying only the range origin is enough. A declared end that disagrees
+    // is downgraded to a warning: the values matrix already fixes the extent.
+    const declared = { endRow: declaredEndRow ?? target.endRow, endColumn: declaredEndColumn ?? target.endColumn };
+    if (declared.endRow < target.startRow || declared.endColumn < target.startColumn) {
+        throw new Error(`${label}.range 结束位置不能小于开始位置：range 为 rows ${startRow}-${declared.endRow} × cols ${startColumn}-${declared.endColumn}`);
+    }
+    const declaredRows = declared.endRow - target.startRow + 1;
+    const declaredColumns = declared.endColumn - target.startColumn + 1;
+    warnings.push(`${label}.range 与 values 尺寸不一致：range 为 ${declaredRows}×${declaredColumns}（rows ${startRow}-${declared.endRow} × cols ${startColumn}-${declared.endColumn}），values 为 ${rowCount}×${columnCount}；已按 values 落位为 rows ${target.startRow}-${target.endRow} × cols ${target.startColumn}-${target.endColumn}（end 坐标 inclusive）`);
+    return target;
+}
+export function parseApiValues(matrix, range) {
+    const rowCount = range.endRow - range.startRow + 1;
+    const columnCount = range.endColumn - range.startColumn + 1;
+    if (matrix.length !== rowCount)
+        throw new Error(`values 行数必须为 ${rowCount}`);
+    const cells = [];
+    for (const [rowOffset, line] of matrix.entries()) {
+        if (line.length !== columnCount)
+            throw new Error(`values[${rowOffset}] 列数必须为 ${columnCount}`);
+        for (const [columnOffset, cell] of line.entries()) {
+            if (cell !== null && typeof cell !== 'string' && typeof cell !== 'number' && typeof cell !== 'boolean') {
+                throw new Error(`values[${rowOffset}][${columnOffset}] 必须是 string/number/boolean/null`);
+            }
+            if (typeof cell === 'number' && !Number.isFinite(cell))
+                throw new Error('values 不能包含非有限数字');
+            cells.push({ row: range.startRow + rowOffset, column: range.startColumn + columnOffset, value: cell });
+        }
+    }
+    return cells;
+}
+/** A single cell of long text (typically a SQL body) read from a local file. */
+export const TEXT_CELL_MAX_BYTES = 1024 * 1024;
+export function parseFreeze(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('freeze 必须是对象');
+    const raw = value;
+    const rows = raw.rows === undefined ? 0 : parseIndex(raw.rows, 'freeze.rows');
+    const columns = raw.columns === undefined ? 0 : parseIndex(raw.columns, 'freeze.columns');
+    return { rows, columns };
+}
+export function parseSort(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error('sort 必须是对象');
+    const raw = value;
+    const direction = raw.direction === undefined ? 'asc' : raw.direction;
+    if (direction !== 'asc' && direction !== 'desc')
+        throw new Error('sort.direction 必须是 asc 或 desc');
+    return { column: parseIndex(raw.column, 'sort.column'), direction };
+}
+export function cellValue(type, value) {
+    switch (type) {
+        case 'number':
+        case 'currency': {
+            const numeric = typeof value === 'number' ? value : Number(value);
+            return Number.isFinite(numeric) ? numeric : String(value);
+        }
+        case 'boolean':
+            return typeof value === 'boolean' ? value : String(value) === 'true';
+        case 'date':
+            return value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+        default:
+            return String(value);
+    }
+}
+/** Validate one sheet argument; throws a model-facing message on bad input. */
+export function validateSheet(args) {
+    const name = args.name === undefined || args.name === null ? undefined : parseNonEmptyString(args.name, 'name');
+    if (name !== undefined && name.length > SHEET_MAX_NAME)
+        throw new Error(`表格名称过长（最多 ${SHEET_MAX_NAME} 字符）`);
+    if (args.columns !== undefined && !Array.isArray(args.columns))
+        throw new Error('columns 必须是数组；已有 sheet 可省略，Host 会从表头推断');
+    const rawColumns = Array.isArray(args.columns) ? args.columns : [];
+    if (rawColumns.length === 0 && !Array.isArray(args.rows))
+        throw new Error('至少需要一列');
+    if (rawColumns.length > SHEET_MAX_COLUMNS)
+        throw new Error(`列数超过上限（最多 ${SHEET_MAX_COLUMNS} 列）`);
+    const keys = new Set();
+    const columns = rawColumns.map((column, index) => {
+        // Column-definition errors have to state the accepted structure and echo
+        // what arrived: "列定义必须是对象" alone cost a debugging round in the
+        // original session (docs/issue/0011 I7 / T6).
+        if (typeof column !== 'object' || column === null || Array.isArray(column)) {
+            throw new Error(`列定义必须是对象：columns[${index}] 期望 { key, label, type }，实际收到 ${JSON.stringify(column) ?? String(column)}`);
+        }
+        const raw = column;
+        if (typeof raw.key !== 'string' || !/^[A-Za-z0-9_]+$/.test(raw.key)) {
+            throw new Error(`列 key 必须是仅含字母、数字、下划线的非空字符串：columns[${index}] 期望 { key, label, type }，实际收到 ${JSON.stringify(raw)}`);
+        }
+        if (keys.has(raw.key))
+            throw new Error(`列 key 重复：${raw.key}（columns[${index}]）`);
+        keys.add(raw.key);
+        if (typeof raw.label !== 'string' || raw.label.length === 0) {
+            throw new Error(`列 ${raw.key} 缺少 label：期望 { key: ${JSON.stringify(raw.key)}, label: string, type: string }，实际收到 ${JSON.stringify(raw)}`);
+        }
+        if (!COLUMN_TYPES.includes(raw.type)) {
+            throw new Error(`列 ${raw.key} 类型未知：${String(raw.type)}；type 只能是 ${COLUMN_TYPES.join('、')}`);
+        }
+        return { key: raw.key, label: raw.label, type: raw.type };
+    });
+    if (!Array.isArray(args.rows))
+        throw new Error('rows 必须是数组');
+    if (args.rows.length > SHEET_MAX_ROWS) {
+        throw new Error(`行数超过上限（最多 ${SHEET_MAX_ROWS} 行）；请使用分页查询或拆成多个 workbook`);
+    }
+    const rows = args.rows.every(row => Array.isArray(row))
+        ? args.rows.map((row, index) => {
+            if (columns.length === 0)
+                throw new Error('rows 使用二维数组时必须同时提供 columns');
+            const values = row;
+            if (values.length > columns.length)
+                throw new Error(`第 ${index + 1} 行列数超过 columns 定义`);
+            return Object.fromEntries(columns.map((column, columnIndex) => [column.key, values[columnIndex] ?? null]));
+        })
+        : args.rows.map((row, index) => {
+            if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+                throw new Error(`第 ${index + 1} 行不是对象`);
+            }
+            return row;
+        });
+    return { name, columns, rows };
+}
+export function chunkRows(rows, size) {
+    const chunks = [];
+    for (let start = 0; start < rows.length; start += size)
+        chunks.push(rows.slice(start, start + size));
+    return chunks;
+}
+export function dimensionRange(index, dimension) {
+    return dimension === 'column'
+        ? { startRow: 0, startColumn: index, endRow: 0, endColumn: index }
+        : { startRow: index, startColumn: 0, endRow: index, endColumn: 0 };
+}
+/**
+ * Row/column structural commands accept either an explicit `range` (matching
+ * the documented command vocabulary) or the older `index`/`startRow` +
+ * `count` pair. Missing position arguments report the full accepted contract
+ * instead of the single `startRow` field the old implementation demanded.
+ */
+export function dimensionCommandRange(raw, index, dimension) {
+    const label = `commands[${index}]`;
+    const positionField = dimension === 'row' ? 'startRow' : 'startColumn';
+    const endField = dimension === 'row' ? 'endRow' : 'endColumn';
+    const explicit = raw.range;
+    if (typeof explicit === 'string') {
+        const parsed = parseA1Range(explicit);
+        return dimension === 'row'
+            ? { startRow: parsed.startRow, startColumn: 0, endRow: parsed.endRow, endColumn: 0 }
+            : { startRow: 0, startColumn: parsed.startColumn, endRow: 0, endColumn: parsed.endColumn };
+    }
+    const range = explicit === undefined || explicit === null ? undefined : asToolArguments(explicit, `${label}.range`);
+    const startValue = range?.[positionField] ?? raw[positionField] ?? raw.index;
+    if (startValue === undefined || startValue === null) {
+        throw new Error(`${label} 缺少${dimension === 'row' ? '行' : '列'}位置：请传 ${label}.range:{${positionField},${endField}}（0-based，结束坐标 inclusive），或传 ${label}.index / ${label}.${positionField} 搭配 count`);
+    }
+    const start = parseIndex(startValue, `${label}.${positionField}`);
+    const rawEnd = range?.[endField];
+    const end = rawEnd === undefined || rawEnd === null ? start : parseIndex(rawEnd, `${label}.${endField}`);
+    if (end < start)
+        throw new Error(`${label}.range 结束位置不能小于开始位置（${start} > ${end}）`);
+    return dimension === 'row'
+        ? { startRow: start, startColumn: 0, endRow: end, endColumn: 0 }
+        : { startRow: 0, startColumn: start, endRow: 0, endColumn: end };
+}
+export function parseFiniteNumber(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(`${label} 必须是有限数字`);
+    return value;
+}
+export function parseHyperlink(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error('url 必须是非空字符串');
+    const url = value.trim();
+    if (!/^(?:https?:|mailto:|file:|#)/i.test(url))
+        throw new Error('url 只支持 http(s)、mailto、file 或 sheet 内部链接');
+    return url;
+}
+export function parseHyperlinkLabel(value) {
+    if (typeof value !== 'string')
+        throw new Error('label 必须是字符串');
+    return value;
+}

package/lib/types/tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare function registerWorkbookTools(ctx: Context): void;

package/lib/types/tools/index.js

@@ -0,0 +1,250 @@
+/**
+ * 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 { rollbackWorkbook } from "../workbook-manager.js";
+import { projectScopeOf, runInProject } from "../store/project.js";
+import { optionalRevision, parseIndex } from "../request-params.js";
+import { lineageOfArgs } from "../audit.js";
+import { UNIVER_API_CATALOG, UNIVER_API_VERSION } from "../contract/univer-api-catalog.js";
+import { optionalAuditText, optionalIntent, optionalString, parseNonEmptyString, workbookIdOf } from "./arguments.js";
+import { asRecordOrUndefined, asJsonValue, renderCatalogResult, renderEditResult, renderFindResult, renderHistoryResult, renderReadResult, renderSummaryAndValue, spillLargeToolResult, } from "./render.js";
+import { asApiArguments, executeUniverApi, parseUniverApiAction } from "./univer-api.js";
+import { executeWorkbookCatalog } from "./workbook-catalog.js";
+import { executeWorkbookEdit } from "./workbook-edit.js";
+import { findWorkbookContent } from "./workbook-find.js";
+import { executeHistoryQuery } from "./workbook-history.js";
+import { readWorkbookTarget } from "./workbook-read.js";
+/**
+ * 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) {
+    return String(exec?.agent?.id ?? '');
+}
+export function registerWorkbookTools(ctx) {
+    // 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) => {
+        // 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) => projectScopeOf(ctx.sessions, sessionIdOf(exec));
+        ctx.tools.register({
+            ...definition,
+            execute: (args, exec) => {
+                const project = projectOf(exec);
+                const run = async () => 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/lib/types/tools/render.d.ts

@@ -0,0 +1,47 @@
+import type { JsonValue } from '@deepseek-ai/dsh-util-values';
+import type { WorkbookOperation } from '../types.ts';
+export interface ToolTextBlock {
+    type: 'text';
+    text: string;
+}
+export declare function textBlock(text: string): ToolTextBlock;
+export declare function asRecordOrUndefined(value: unknown): Record<string, unknown> | undefined;
+export declare function renderSummaryAndValue(summary: string, value: unknown): ToolTextBlock[];
+/**
+ * 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 declare const TOOL_RESULT_INLINE_LIMIT = 24000;
+/** Spill an oversized canonical value so the model can still page through it. */
+export declare function spillLargeToolResult(toolName: string, value: unknown): Promise<Record<string, unknown>>;
+/** Keep large write payloads out of the model/tool transcript. */
+export declare function compactToolValue(value: unknown): unknown;
+export declare function asJsonValue(value: unknown): JsonValue;
+export declare function isOperationRecord(value: unknown): value is WorkbookOperation;
+export declare function operationReceipt(operation: WorkbookOperation): Record<string, unknown>;
+export interface SheetOverview {
+    id: string;
+    name: string;
+    rowCount: number;
+    columnCount: number;
+    maxRow: number | null;
+    maxColumn: number | null;
+    nonEmptyCells: number;
+}
+export declare function isNonEmptyCell(cell: unknown): boolean;
+/** Compact per-sheet map (`name ↔ id` + size) that Agent callers use to address sheets. */
+export declare function sheetOverviews(snapshot: unknown): SheetOverview[];
+export declare function sheetMapSummary(sheets: readonly SheetOverview[]): string;
+/** Inline `名称（id）` list used by self-healing error messages. */
+export declare function sheetReferenceList(snapshot: unknown): string;
+export declare function renderCatalogResult(value: unknown): ToolTextBlock[];
+export declare function renderReadResult(value: unknown): ToolTextBlock[];
+export declare function renderFindResult(value: unknown): ToolTextBlock[];
+export declare function renderHistoryResult(value: unknown): ToolTextBlock[];
+export declare function renderEditResult(value: unknown): ToolTextBlock[];