@yejiming/dsh-data-agent 0.0.5 → 0.0.9

package/lib/tool.js

@@ -1,7 +1,595 @@
-import { d as clientsSchema, f as enforceReadRowLimit, i as DEFAULT_MAX_RESULT_CHARS, o as DEFAULT_QUERY_TIMEOUT_MS, u as classifyStatement, y as assertSingleStatement } from "./defaults-Bac6QvNt.js";
-import { t as runClientQuery } from "./query-CmhTFklw.js";
+import { a as classifyStatement, c as assertSingleStatement, i as runClientQuery, n as redactQueryResult, o as clientsSchema, r as redactSecretText, s as enforceReadRowLimit } from "./connections-DeauhaZi.js";
+import { i as DEFAULT_MAX_RESULT_CHARS, o as DEFAULT_QUERY_TIMEOUT_MS, r as DEFAULT_MAX_QUERY_CHARS } from "./defaults-DP4RyRh1.js";
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+const VIEW_KINDS = [
+	"metric",
+	"line",
+	"bar",
+	"pie",
+	"scatter",
+	"table"
+];
+const AXIS_TYPES = ["category", "time"];
+const WIDTHS = ["full", "half"];
+const METRIC_FORMATS = ["number", "percent"];
+function fail(message) {
+	throw new Error(message);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Reject keys outside the allowed set (additionalProperties=false semantics). */
+function assertOnlyKeys(record, allowed, label) {
+	for (const key of Object.keys(record)) if (!allowed.includes(key)) fail(label + ": 不支持的字段 \"" + key + "\"");
+}
+function requireNonEmptyString(value, label) {
+	if (typeof value !== "string" || value.trim().length === 0) fail(label + ": 必须是非空字符串");
+	return value;
+}
+function optionalString(record, key, label) {
+	const value = record[key];
+	if (value === void 0) return void 0;
+	if (typeof value !== "string") fail(label + "." + key + ": 必须是字符串");
+	return value;
+}
+function optionalEnum(record, key, allowed, label) {
+	const value = record[key];
+	if (value === void 0) return void 0;
+	if (typeof value !== "string" || !allowed.includes(value)) fail(label + "." + key + ": 必须是 " + allowed.join("/") + " 之一");
+	return value;
+}
+/** Read a required non-empty string field with a concrete error path. */
+function requiredStringField(record, key, label) {
+	return requireNonEmptyString(record[key], label + "." + key);
+}
+/** Read an optional array of unique non-empty strings (the table whitelist). */
+function optionalStringArray(record, key, label) {
+	const value = record[key];
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim().length === 0)) fail(label + "." + key + ": 必须是非空字符串数组");
+	const items = value.map((item) => item);
+	if (new Set(items).size !== items.length) fail(label + "." + key + ": 列名不能重复");
+	return items;
+}
+function parseXAxis(value, label) {
+	if (!isRecord(value)) fail(label + ".x: 必须是对象 { field, type, label? }");
+	assertOnlyKeys(value, [
+		"field",
+		"type",
+		"label"
+	], label + ".x");
+	const field = requiredStringField(value, "field", label + ".x");
+	const type = optionalEnum(value, "type", AXIS_TYPES, label + ".x");
+	if (type === void 0) fail(label + ".x.type: 必须是 category/time 之一");
+	const axisLabel = optionalString(value, "label", label + ".x");
+	const axis = {
+		field,
+		type
+	};
+	if (axisLabel !== void 0) axis.label = axisLabel;
+	return axis;
+}
+function parseView(value, label, datasetIds) {
+	if (!isRecord(value)) fail(label + ": 必须是对象");
+	const kind = value["kind"];
+	if (typeof kind !== "string" || !VIEW_KINDS.includes(kind)) fail(label + ": kind 必须是 metric/line/bar/pie/scatter/table 之一");
+	const viewKind = kind;
+	const id = requiredStringField(value, "id", label);
+	const datasetId = requiredStringField(value, "datasetId", label);
+	if (!datasetIds.has(datasetId)) fail(label + ": 引用了不存在的 dataset id \"" + datasetId + "\"");
+	if (viewKind === "metric") {
+		assertOnlyKeys(value, [
+			"id",
+			"kind",
+			"datasetId",
+			"field",
+			"label",
+			"format"
+		], label);
+		const metric = {
+			id,
+			kind: "metric",
+			datasetId,
+			field: requiredStringField(value, "field", label),
+			label: requiredStringField(value, "label", label)
+		};
+		const format = optionalEnum(value, "format", METRIC_FORMATS, label);
+		if (format !== void 0) metric.format = format;
+		return metric;
+	}
+	const width = optionalEnum(value, "width", WIDTHS, label);
+	const viewLabel = optionalString(value, "label", label);
+	switch (viewKind) {
+		case "line":
+		case "bar": {
+			assertOnlyKeys(value, [
+				"id",
+				"kind",
+				"datasetId",
+				"label",
+				"width",
+				"x",
+				"y",
+				"seriesField"
+			], label);
+			const x = parseXAxis(value["x"], label);
+			const y = value["y"];
+			if (!Array.isArray(y) || y.length < 1 || y.length > 4 || y.some((item) => typeof item !== "string" || item.trim().length === 0)) fail(label + ".y: 必须是 1-4 个非空字段名");
+			const seriesField = optionalString(value, "seriesField", label);
+			if (seriesField !== void 0 && y.length >= 2) fail(label + ": seriesField 与多个 y 字段互斥，只能二选一");
+			const view = {
+				id,
+				kind: viewKind,
+				datasetId,
+				x,
+				y: y.map((item) => item)
+			};
+			if (viewLabel !== void 0) view.label = viewLabel;
+			if (width !== void 0) view.width = width;
+			if (seriesField !== void 0) view.seriesField = seriesField;
+			return view;
+		}
+		case "pie": {
+			assertOnlyKeys(value, [
+				"id",
+				"kind",
+				"datasetId",
+				"label",
+				"width",
+				"categoryField",
+				"valueField"
+			], label);
+			const view = {
+				id,
+				kind: "pie",
+				datasetId,
+				categoryField: requiredStringField(value, "categoryField", label),
+				valueField: requiredStringField(value, "valueField", label)
+			};
+			if (viewLabel !== void 0) view.label = viewLabel;
+			if (width !== void 0) view.width = width;
+			return view;
+		}
+		case "scatter": {
+			assertOnlyKeys(value, [
+				"id",
+				"kind",
+				"datasetId",
+				"label",
+				"width",
+				"xField",
+				"yField"
+			], label);
+			const view = {
+				id,
+				kind: "scatter",
+				datasetId,
+				xField: requiredStringField(value, "xField", label),
+				yField: requiredStringField(value, "yField", label)
+			};
+			if (viewLabel !== void 0) view.label = viewLabel;
+			if (width !== void 0) view.width = width;
+			return view;
+		}
+		case "table": {
+			assertOnlyKeys(value, [
+				"id",
+				"kind",
+				"datasetId",
+				"label",
+				"width",
+				"columns"
+			], label);
+			const view = {
+				id,
+				kind: "table",
+				datasetId
+			};
+			const columns = optionalStringArray(value, "columns", label);
+			if (viewLabel !== void 0) view.label = viewLabel;
+			if (width !== void 0) view.width = width;
+			if (columns !== void 0) view.columns = columns;
+			return view;
+		}
+	}
+}
+/**
+* Strictly parse a model-supplied analysis request. Every structural
+* violation (unknown fields, duplicate ids, dangling references, count or
+* union constraints) throws with a message naming the offending view/dataset.
+*/
+function parseAnalysisRequest(input, prefix = "render-analysis") {
+	if (!isRecord(input)) fail(prefix + ": 请求必须是对象");
+	assertOnlyKeys(input, [
+		"title",
+		"summary",
+		"datasets",
+		"views"
+	], prefix);
+	const title = requireNonEmptyString(input["title"], prefix + ".title");
+	const summary = optionalString(input, "summary", prefix);
+	const datasets = input["datasets"];
+	if (!Array.isArray(datasets) || datasets.length < 1 || datasets.length > 6) fail(prefix + ": datasets 必须是 1-6 个");
+	const parsedDatasets = [];
+	const datasetIds = /* @__PURE__ */ new Set();
+	for (let index = 0; index < datasets.length; index += 1) {
+		const label = prefix + ".datasets[" + index + "]";
+		const item = datasets[index];
+		if (!isRecord(item)) fail(label + ": 必须是对象");
+		assertOnlyKeys(item, ["id", "sql"], label);
+		const id = requiredStringField(item, "id", label);
+		if (datasetIds.has(id)) fail(label + ": dataset id \"" + id + "\" 重复");
+		datasetIds.add(id);
+		parsedDatasets.push({
+			id,
+			sql: requiredStringField(item, "sql", label)
+		});
+	}
+	const views = input["views"];
+	if (!Array.isArray(views) || views.length < 1 || views.length > 8) fail(prefix + ": views 必须是 1-8 个");
+	const parsedViews = [];
+	const viewIds = /* @__PURE__ */ new Set();
+	for (let index = 0; index < views.length; index += 1) {
+		const label = prefix + ".views[" + index + "]";
+		const view = parseView(views[index], label, datasetIds);
+		if (viewIds.has(view.id)) fail(label + ": view id \"" + view.id + "\" 重复");
+		viewIds.add(view.id);
+		parsedViews.push(view);
+	}
+	const request = {
+		title,
+		datasets: parsedDatasets,
+		views: parsedViews
+	};
+	if (summary !== void 0) request.summary = summary;
+	return request;
+}
+/** Whether one string parses to a finite number. */
+function isFiniteNumberText(value) {
+	return value.trim() !== "" && Number.isFinite(Number(value));
+}
+/** Whether one string parses as a time value. */
+function isParseableTimeText(value) {
+	return value.trim() !== "" && !Number.isNaN(Date.parse(value));
+}
+/**
+* Validate view→dataset semantics AFTER all queries succeeded and BEFORE any
+* meta is built: field existence, finite numerics, pie non-negativity, time
+* parseability, and table whitelist existence. The client is never asked to
+* aggregate, sort, or treat null as zero — validation happens here.
+*/
+function validateViewSemantics(views, datasets, prefix = "render-analysis") {
+	for (const view of views) {
+		const dataset = datasets.get(view.datasetId);
+		if (dataset === void 0) fail(prefix + ": view \"" + view.id + "\" 引用了未知 dataset \"" + view.datasetId + "\"");
+		const columns = new Set(dataset.columns);
+		const requireColumn = (field) => {
+			if (!columns.has(field)) fail(prefix + ": view \"" + view.id + "\" 引用了 dataset \"" + view.datasetId + "\" 中不存在的字段 \"" + field + "\"");
+		};
+		const requireNumeric = (field) => {
+			requireColumn(field);
+			for (const row of dataset.rows) {
+				const value = row[field] ?? null;
+				if (value !== null && !isFiniteNumberText(value)) fail(prefix + ": view \"" + view.id + "\" 的字段 \"" + field + "\" 含有非数值 \"" + value + "\"（不能转换为有限数）");
+			}
+		};
+		switch (view.kind) {
+			case "metric":
+				requireNumeric(view.field);
+				break;
+			case "line":
+			case "bar":
+				if (view.x.type === "time") {
+					requireColumn(view.x.field);
+					for (const row of dataset.rows) {
+						const value = row[view.x.field] ?? null;
+						if (value !== null && !isParseableTimeText(value)) fail(prefix + ": view \"" + view.id + "\" 的 x 字段 \"" + view.x.field + "\" 含有不可解析的时间值 \"" + value + "\"");
+					}
+				} else requireColumn(view.x.field);
+				if (view.seriesField !== void 0) requireColumn(view.seriesField);
+				for (const field of view.y) requireNumeric(field);
+				break;
+			case "pie":
+				requireColumn(view.categoryField);
+				requireNumeric(view.valueField);
+				for (const row of dataset.rows) {
+					const value = row[view.valueField] ?? null;
+					if (value !== null && Number(value) < 0) fail(prefix + ": view \"" + view.id + "\" 的 valueField \"" + view.valueField + "\" 含负数 \"" + value + "\"（饼图值必须非负）");
+				}
+				break;
+			case "scatter":
+				requireNumeric(view.xField);
+				requireNumeric(view.yField);
+				break;
+			case "table": for (const column of view.columns ?? []) requireColumn(column);
+		}
+	}
+}
+/** Compress object rows into column-aligned two-dimensional arrays (D2). */
+function rowsToArrays(columns, rows) {
+	return rows.map((row) => columns.map((column) => row[column] ?? null));
+}
+/** JSON-encoded UTF-8 size of the normalized report (the 512 KiB bound). */
+function reportJsonBytes(report) {
+	return new TextEncoder().encode(JSON.stringify(report)).length;
+}
+/** One-line model-facing summary; never re-injects rows into model context (D5). */
+function formatAnalysisSummary(report) {
+	const emptyIds = report.datasets.filter((dataset) => dataset.rows.length === 0).map((dataset) => dataset.id);
+	let text = "已生成分析报告《" + report.title + "》：" + report.datasets.length + " 个数据集、" + report.views.length + " 个视图（version 1）。";
+	if (emptyIds.length > 0) text += "其中 " + emptyIds.length + " 个数据集无数据：" + emptyIds.join("、") + "。";
+	return text;
+}
+const BASE_VIEW_PROPERTIES = {
+	id: {
+		type: "string",
+		required: true,
+		description: "视图唯一 id（本报告内不重复）"
+	},
+	kind: {
+		type: "string",
+		required: true,
+		description: "视图类型"
+	},
+	datasetId: {
+		type: "string",
+		required: true,
+		description: "引用本次请求中的一个 dataset id"
+	},
+	label: {
+		type: "string",
+		description: "可选视图标题，用于图表可访问名称与空态"
+	},
+	width: {
+		type: "string",
+		enum: ["full", "half"],
+		description: "可选宽度：full 整行 / half 半行（缺省由系统决定）"
+	}
+};
+const METRIC_VIEW_SCHEMA = {
+	type: "object",
+	properties: {
+		id: BASE_VIEW_PROPERTIES.id,
+		kind: {
+			type: "string",
+			const: "metric",
+			required: true
+		},
+		datasetId: BASE_VIEW_PROPERTIES.datasetId,
+		field: {
+			type: "string",
+			required: true,
+			description: "数值字段名（来自 dataset 查询结果的列）"
+		},
+		label: {
+			type: "string",
+			required: true,
+			description: "指标名称，如「本月营收」"
+		},
+		format: {
+			type: "string",
+			enum: ["number", "percent"],
+			description: "可选数值格式：number（默认）或 percent（值×100 后加 %）"
+		}
+	},
+	additionalProperties: false
+};
+const LINE_BAR_VIEW_SCHEMA = (kind) => ({
+	type: "object",
+	properties: {
+		id: BASE_VIEW_PROPERTIES.id,
+		kind: {
+			type: "string",
+			const: kind,
+			required: true
+		},
+		datasetId: BASE_VIEW_PROPERTIES.datasetId,
+		label: BASE_VIEW_PROPERTIES.label,
+		width: BASE_VIEW_PROPERTIES.width,
+		x: {
+			type: "object",
+			properties: {
+				field: {
+					type: "string",
+					required: true,
+					description: "x 轴字段名"
+				},
+				type: {
+					type: "string",
+					enum: ["category", "time"],
+					required: true,
+					description: "category 分类轴 / time 时间轴（数据需可由 Date 解析，SQL 请 ORDER BY）"
+				},
+				label: {
+					type: "string",
+					description: "可选 x 轴名称"
+				}
+			},
+			additionalProperties: false,
+			required: true
+		},
+		y: {
+			type: "array",
+			required: true,
+			items: { type: "string" },
+			description: "1-4 个数值 y 字段名；声明多个 y 时不得同时声明 seriesField"
+		},
+		seriesField: {
+			type: "string",
+			description: "可选分组字段：按该字段取值拆成多个系列（与多个 y 字段互斥）"
+		}
+	},
+	additionalProperties: false
+});
+const PIE_VIEW_SCHEMA = {
+	type: "object",
+	properties: {
+		id: BASE_VIEW_PROPERTIES.id,
+		kind: {
+			type: "string",
+			const: "pie",
+			required: true
+		},
+		datasetId: BASE_VIEW_PROPERTIES.datasetId,
+		label: BASE_VIEW_PROPERTIES.label,
+		width: BASE_VIEW_PROPERTIES.width,
+		categoryField: {
+			type: "string",
+			required: true,
+			description: "分类字段名"
+		},
+		valueField: {
+			type: "string",
+			required: true,
+			description: "非负数值字段名"
+		}
+	},
+	additionalProperties: false
+};
+const SCATTER_VIEW_SCHEMA = {
+	type: "object",
+	properties: {
+		id: BASE_VIEW_PROPERTIES.id,
+		kind: {
+			type: "string",
+			const: "scatter",
+			required: true
+		},
+		datasetId: BASE_VIEW_PROPERTIES.datasetId,
+		label: BASE_VIEW_PROPERTIES.label,
+		width: BASE_VIEW_PROPERTIES.width,
+		xField: {
+			type: "string",
+			required: true,
+			description: "数值 x 字段名"
+		},
+		yField: {
+			type: "string",
+			required: true,
+			description: "数值 y 字段名"
+		}
+	},
+	additionalProperties: false
+};
+const TABLE_VIEW_SCHEMA = {
+	type: "object",
+	properties: {
+		id: BASE_VIEW_PROPERTIES.id,
+		kind: {
+			type: "string",
+			const: "table",
+			required: true
+		},
+		datasetId: BASE_VIEW_PROPERTIES.datasetId,
+		label: BASE_VIEW_PROPERTIES.label,
+		width: BASE_VIEW_PROPERTIES.width,
+		columns: {
+			type: "array",
+			items: { type: "string" },
+			description: "可选列白名单；省略时按 dataset 列顺序显示"
+		}
+	},
+	additionalProperties: false
+};
+/** The view union: exactly the six supported kinds, nothing else. */
+const ANALYSIS_VIEWS_SCHEMA = { oneOf: [
+	METRIC_VIEW_SCHEMA,
+	LINE_BAR_VIEW_SCHEMA("line"),
+	LINE_BAR_VIEW_SCHEMA("bar"),
+	PIE_VIEW_SCHEMA,
+	SCATTER_VIEW_SCHEMA,
+	TABLE_VIEW_SCHEMA
+] };
+/** Wire parameter schema of the render-analysis tool. */
+const RENDER_ANALYSIS_PARAMETERS = {
+	title: {
+		type: "string",
+		required: true,
+		description: "报告标题，如「月度经营分析」"
+	},
+	summary: {
+		type: "string",
+		description: "可选一句话结论/摘要，显示在报告头部"
+	},
+	datasets: {
+		type: "array",
+		required: true,
+		items: {
+			type: "object",
+			properties: {
+				id: {
+					type: "string",
+					required: true,
+					description: "数据集唯一 id（供 views 引用）"
+				},
+				sql: {
+					type: "string",
+					required: true,
+					description: "一条只读 SQL（SELECT/SHOW/DESCRIBE/EXPLAIN；聚合、Top N、排序都写在 SQL 中）"
+				}
+			},
+			additionalProperties: false
+		},
+		description: "1-6 个数据集；每个按顺序恰好执行一次，同一数据集可被多个视图复用"
+	},
+	views: {
+		type: "array",
+		required: true,
+		items: ANALYSIS_VIEWS_SCHEMA,
+		description: "1-8 个视图；每个视图必须回答一个不同子问题，多个视图可共享同一 dataset"
+	}
+};
+/** Canonical output schema of the render-analysis tool. */
+const ANALYSIS_REPORT_OUTPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		version: {
+			type: "integer",
+			const: 1,
+			required: true
+		},
+		title: {
+			type: "string",
+			required: true
+		},
+		summary: { type: "string" },
+		datasets: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						required: true
+					},
+					columns: {
+						type: "array",
+						required: true,
+						items: { type: "string" }
+					},
+					rows: {
+						type: "array",
+						required: true,
+						items: {
+							type: "array",
+							items: { oneOf: [{ type: "string" }, { type: "null" }] }
+						}
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		views: {
+			type: "array",
+			required: true,
+			items: ANALYSIS_VIEWS_SCHEMA
+		}
+	},
+	additionalProperties: false
+};
+//#endregion
 //#region src/structured.ts
 function normalizeNewlines(text) {
 	return text.replace(/\r\n?/g, "\n");
@@ -164,6 +752,64 @@ function parseStructuredQueryOutput(type, stdout, maxRows) {
 	}
 }
 //#endregion
+//#region src/structured-read.ts
+/** Look up the session connection, failing with the same message for every tool. */
+async function requireToolConnection(ctx, exec, toolName) {
+	const sessionId = exec.agent?.id;
+	if (sessionId === void 0) throw new Error(toolName + ": 缺少会话上下文（agent loop 未注入）");
+	try {
+		return await ctx.dataAgentConnections.resolveForExecution(sessionId);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(toolName + ": " + message);
+	}
+}
+/** Run and redact a client result/error before it reaches tool/session output. */
+async function runRedactedClientQuery(ctx, connection, sql, options, signal) {
+	try {
+		const result = await runClientQuery(ctx, connection, sql, options, signal);
+		return redactQueryResult(result, connection);
+	} catch (error) {
+		const message = redactSecretText(error instanceof Error ? error.message : String(error), [connection.password]);
+		throw new Error(message, error instanceof Error ? { cause: error } : void 0);
+	}
+}
+/** Query runner options with the deployment overrides applied. */
+function runnerOptions(resolved, mode) {
+	return {
+		clients: resolved.clients,
+		timeoutMs: resolved.queryTimeoutMs,
+		maxResultChars: resolved.maxResultChars,
+		...mode !== void 0 ? { mode } : {}
+	};
+}
+/**
+* Execute one read-only SQL through the structured client template and parse
+* it into the canonical { columns, rows } shape, with maxRows enforced at both
+* the SQL level (LIMIT injection) and the parse level.
+*/
+async function runStructuredReadQuery(ctx, connection, sql, resolved, toolName, signal) {
+	if (sql.trim().length === 0) throw new Error(toolName + ": sql 不能为空");
+	if (sql.length > resolved.maxQueryChars) throw new Error(toolName + ": sql 超过长度上限（" + resolved.maxQueryChars + " 字符）");
+	assertSingleStatement(sql, toolName);
+	if (classifyStatement(sql, connection.type) !== "read") throw new Error(toolName + " 只执行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA）；写语句请使用 sql-write");
+	const limitedSql = enforceReadRowLimit(sql, connection.type, resolved.maxRows);
+	const startedAt = Date.now();
+	const result = await runRedactedClientQuery(ctx, connection, limitedSql, runnerOptions(resolved, "structured"), signal);
+	const elapsedMs = Date.now() - startedAt;
+	if (result.exitCode !== 0) {
+		const detail = result.stderr.trim() !== "" ? result.stderr.trim() : result.stdout.trim();
+		throw new Error(toolName + " 执行失败（exit " + result.exitCode + "）：" + detail);
+	}
+	const parsed = parseStructuredQueryOutput(connection.type, result.stdout, resolved.maxRows);
+	return {
+		columns: parsed.columns,
+		rows: parsed.rows,
+		elapsedMs,
+		truncated: result.truncated || parsed.rowLimitExceeded
+	};
+}
+//#endregion
 //#region src/tool.ts
 /** Cordis plugin name (diagnostics only). */
 const name = "data-agent-tool";
@@ -178,6 +824,7 @@ const Config = z.object({
 	queryTimeoutMs: z.number().step(1).min(1e3).default(DEFAULT_QUERY_TIMEOUT_MS),
 	maxResultChars: z.number().step(1).min(1024).default(DEFAULT_MAX_RESULT_CHARS),
 	maxRows: z.number().step(1).min(1).default(100),
+	maxQueryChars: z.number().step(1).min(1024).default(DEFAULT_MAX_QUERY_CHARS),
 	readonly: z.boolean().default(false),
 	clients: clientsSchema
 });
@@ -199,31 +846,95 @@ function formatResult(value) {
 function formatStructuredResult(value) {
 	return "```json\n" + JSON.stringify(value, null, 2) + "\n```";
 }
-/** Look up the session connection, failing with the same message for every tool. */
-function requireToolConnection(ctx, exec, toolName) {
-	const sessionId = exec.agent?.id;
-	if (sessionId === void 0) throw new Error(`${toolName}: 缺少会话上下文（agent loop 未注入）`);
-	const connection = ctx.dataAgentConnections.getWithSecret(sessionId);
-	if (connection === void 0) throw new Error(`请先在「数据库」标签页连接数据库，再使用 ${toolName}（未找到当前会话的连接）`);
-	return connection;
-}
-/** Empty and multi-statement checks shared by all three tools. */
+/** Empty and multi-statement checks shared by the write/raw tools. */
 function validateSingleSql(sql, toolName) {
-	if (sql.trim().length === 0) throw new Error(`${toolName}: sql 不能为空`);
+	if (sql.trim().length === 0) throw new Error(toolName + ": sql 不能为空");
 	assertSingleStatement(sql, toolName);
 }
-/** Query runner options with the deployment overrides applied. */
-function runnerOptions(resolved, mode) {
-	return {
-		clients: resolved.clients,
-		timeoutMs: resolved.queryTimeoutMs,
-		maxResultChars: resolved.maxResultChars,
-		...mode !== void 0 ? { mode } : {}
-	};
+/**
+* The Web-only render-analysis tool (D1-D5): one call builds one versioned
+* analysis report from 1-6 read-only datasets and 1-8 views. The full report
+* is persisted as presentationMeta; the model only receives a short summary
+* (output.render), never the rows themselves.
+*/
+function defineRenderAnalysisTool(ctx, resolved) {
+	return defineTool({
+		name: "render-analysis",
+		description: "Web only: render one versioned analysis report (v1) from 1-6 read-only datasets and 1-8 metric, line, bar, pie, scatter, or table views. First use sql-query to inspect and verify data, then call this tool only when visualization adds value. Use one primary chart for a simple relationship or 3-6 complementary views for multi-metric, time-series, or segmented analysis. Put aggregation, Top N, and sorting in SQL, and add ORDER BY for line or time datasets. Reuse a dataset across views via datasetId; each dataset runs once. Arbitrary chart options, scripts, HTML, CSS, and URLs are not accepted. Empty datasets are valid and render as no-data states.",
+		parameters: RENDER_ANALYSIS_PARAMETERS,
+		output: {
+			schema: ANALYSIS_REPORT_OUTPUT_SCHEMA,
+			render: (_args, value) => [{
+				type: "text",
+				text: formatAnalysisSummary(value)
+			}],
+			presentationMeta: (_args, value) => value
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			kind: "read",
+			title: "render-analysis《" + args.title + "》",
+			rawInput: args.title
+		}),
+		presentResult: (args, result) => ({
+			card: "generic",
+			title: "render-analysis《" + args.title + "》",
+			content: result.content
+		}),
+		async execute(args, exec) {
+			const request = parseAnalysisRequest(args);
+			const connection = await requireToolConnection(ctx, exec, "render-analysis");
+			const planned = request.datasets.map((dataset) => {
+				const sql = dataset.sql;
+				if (sql.trim().length === 0) throw new Error("render-analysis: dataset \"" + dataset.id + "\" 的 sql 不能为空");
+				if (sql.length > resolved.maxQueryChars) throw new Error("render-analysis: dataset \"" + dataset.id + "\" 的 sql 超过长度上限（" + resolved.maxQueryChars + " 字符）");
+				assertSingleStatement(sql, "render-analysis");
+				if (classifyStatement(sql, connection.type) !== "read") throw new Error("render-analysis: dataset \"" + dataset.id + "\" 必须是读语句（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA）");
+				return {
+					id: dataset.id,
+					sql: enforceReadRowLimit(sql, connection.type, resolved.maxRows)
+				};
+			});
+			const results = /* @__PURE__ */ new Map();
+			for (const item of planned) {
+				let read;
+				try {
+					read = await runStructuredReadQuery(ctx, connection, item.sql, resolved, "render-analysis", exec.signal);
+				} catch (error) {
+					if (exec.signal.aborted) throw error;
+					const message = error instanceof Error ? error.message : String(error);
+					throw new Error("render-analysis: dataset \"" + item.id + "\" 执行失败：" + message);
+				}
+				if (read.truncated) throw new Error("render-analysis: dataset \"" + item.id + "\" 的查询结果被截断（超过 maxRows/maxResultChars）；请缩小、聚合或拆分查询");
+				results.set(item.id, {
+					columns: read.columns,
+					rows: read.rows
+				});
+			}
+			validateViewSemantics(request.views, results);
+			const report = {
+				version: 1,
+				title: request.title,
+				...request.summary !== void 0 ? { summary: request.summary } : {},
+				datasets: request.datasets.map((dataset) => {
+					const data = results.get(dataset.id);
+					return {
+						id: dataset.id,
+						columns: data.columns,
+						rows: rowsToArrays(data.columns, data.rows)
+					};
+				}),
+				views: request.views
+			};
+			const bytes = reportJsonBytes(report);
+			if (bytes > 524288) throw new Error("render-analysis: 报告 JSON 超过 524288 字节上限（当前 " + bytes + " 字节）；请聚合、筛选或拆分报告，不得静默删减数据");
+			return report;
+		}
+	});
 }
 /**
 * Mount the data-agent database tools: `sql-query` (structured read-only),
-* `sql-write` (explicit write semantics), and `sqlcmd` (raw compatibility).
+* `sql-write` (explicit write semantics), and `sql-cmd` (raw compatibility).
 * @param ctx - the preset-scoped agent context.
 * @param config - validated loader configuration.
 */
@@ -232,12 +943,13 @@ function apply(ctx, config) {
 		queryTimeoutMs: config.queryTimeoutMs,
 		maxResultChars: config.maxResultChars,
 		maxRows: config.maxRows,
+		maxQueryChars: config.maxQueryChars,
 		readonly: config.readonly,
 		clients: config.clients
 	};
 	ctx.tools.register(defineTool({
 		name: "sql-query",
-		description: `在已连接数据库上执行一条只读 SQL（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA），返回结构化 JSON：{ columns, rows, affectedRows, elapsedMs, truncated }。SELECT 未写 LIMIT 时会自动限制为最多 ${resolved.maxRows} 行；所有结果最多返回 ${resolved.maxRows} 行。只执行单条语句；写操作请使用 sql-write，原始客户端输出请使用 sqlcmd。`,
+		description: `Execute exactly one read-only SQL statement (SELECT, SHOW, DESCRIBE, EXPLAIN, or a read-only SQLite PRAGMA) on the connected database. Returns structured JSON with columns, rows, affectedRows, elapsedMs, and truncated. An unbounded SELECT is limited automatically, and every result is capped at ${resolved.maxRows} rows. Use sql-write for write operations and sql-cmd when raw database-client output is required.`,
 		parameters: { sql: {
 			type: "string",
 			required: true,
@@ -293,30 +1005,19 @@ function apply(ctx, config) {
 			content: result.content
 		}),
 		async execute(args, exec) {
-			const connection = requireToolConnection(ctx, exec, "sql-query");
-			validateSingleSql(args.sql, "sql-query");
-			if (classifyStatement(args.sql, connection.type) !== "read") throw new Error("sql-query 只执行读语句（SELECT/SHOW/DESCRIBE/EXPLAIN，SQLite 还含查询型 PRAGMA）；写语句请使用 sql-write");
-			const limitedSql = enforceReadRowLimit(args.sql, connection.type, resolved.maxRows);
-			const startedAt = Date.now();
-			const result = await runClientQuery(ctx, connection, limitedSql, runnerOptions(resolved, "structured"), exec.signal);
-			const elapsedMs = Date.now() - startedAt;
-			if (result.exitCode !== 0) {
-				const detail = result.stderr.trim() !== "" ? result.stderr.trim() : result.stdout.trim();
-				throw new Error(`sql-query 执行失败（exit ${result.exitCode}）：${detail}`);
-			}
-			const parsed = parseStructuredQueryOutput(connection.type, result.stdout, resolved.maxRows);
+			const read = await runStructuredReadQuery(ctx, await requireToolConnection(ctx, exec, "sql-query"), args.sql, resolved, "sql-query", exec.signal);
 			return {
-				columns: parsed.columns,
-				rows: parsed.rows,
+				columns: read.columns,
+				rows: read.rows,
 				affectedRows: 0,
-				elapsedMs,
-				truncated: result.truncated || parsed.rowLimitExceeded
+				elapsedMs: read.elapsedMs,
+				truncated: read.truncated
 			};
 		}
 	}));
 	ctx.tools.register(defineTool({
 		name: "sql-write",
-		description: "在已连接数据库上执行一条写/管理语句（INSERT/UPDATE/DELETE/DDL 等）。每次调用都是独立客户端进程并自动提交，只接受单条语句，不支持跨调用的多语句事务；如需原子性，请改用单条 SQL（如 INSERT ... SELECT）或数据库端脚本/存储过程。只读查询请使用 sql-query。",
+		description: "Execute exactly one write or administrative SQL statement, such as INSERT, UPDATE, DELETE, or DDL, on the connected database. Each call starts an independent database-client process and auto-commits. Multi-statement transactions cannot span calls; use one atomic statement such as INSERT ... SELECT, or a database-side script or stored procedure. Use sql-query for read-only queries.",
 		parameters: { sql: {
 			type: "string",
 			required: true,
@@ -361,16 +1062,16 @@ function apply(ctx, config) {
 			content: result.content
 		}),
 		async execute(args, exec) {
-			const connection = requireToolConnection(ctx, exec, "sql-write");
+			const connection = await requireToolConnection(ctx, exec, "sql-write");
 			validateSingleSql(args.sql, "sql-write");
 			if (classifyStatement(args.sql, connection.type) === "read") throw new Error("sql-write 只执行写/管理语句；只读查询请使用 sql-query");
 			if (connection.readonly ?? resolved.readonly) throw new Error("当前连接为只读模式，sql-write 拒绝执行写/管理语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/查询型 PRAGMA 等）");
-			return runClientQuery(ctx, connection, args.sql, runnerOptions(resolved), exec.signal);
+			return runRedactedClientQuery(ctx, connection, args.sql, runnerOptions(resolved), exec.signal);
 		}
 	}));
 	ctx.tools.register(defineTool({
-		name: "sqlcmd",
-		description: `在已连接数据库上执行一条 SQL 或客户端命令（如 SHOW TABLES、DESCRIBE users），返回原始 exitCode/stdout/stderr 文本。新调用优先使用 sql-query（结构化只读结果）和 sql-write（明确写语义）。一次只执行一条语句；读 SELECT 会自动限制最多 ${resolved.maxRows} 行；每次调用为独立客户端进程并自动提交。`,
+		name: "sql-cmd",
+		description: `Execute exactly one SQL statement or database-client command, such as SHOW TABLES or DESCRIBE users, on the connected database and return raw exitCode, stdout, stderr, and truncated fields. Prefer sql-query for structured read results and sql-write for explicit write semantics. Read SELECT results are limited to ${resolved.maxRows} rows. Each call starts an independent database-client process and auto-commits.`,
 		parameters: { sql: {
 			type: "string",
 			required: true,
@@ -406,22 +1107,22 @@ function apply(ctx, config) {
 		},
 		presentCall: (args) => ({
 			card: "terminal",
-			title: `sqlcmd ${oneLine(args.sql)}`,
+			title: `sql-cmd ${oneLine(args.sql)}`,
 			description: "在数据库客户端执行一条 SQL"
 		}),
 		presentResult: (args, result) => ({
 			card: "terminal",
-			title: `sqlcmd ${oneLine(args.sql)}`,
+			title: `sql-cmd ${oneLine(args.sql)}`,
 			content: result.content
 		}),
 		async execute(args, exec) {
-			const connection = requireToolConnection(ctx, exec, "sqlcmd");
-			validateSingleSql(args.sql, "sqlcmd");
-			if ((connection.readonly ?? resolved.readonly) && classifyStatement(args.sql, connection.type) === "write") throw new Error("当前连接为只读模式，sqlcmd 拒绝执行非读语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/查询型 PRAGMA 等）");
-			const sql = classifyStatement(args.sql, connection.type) === "read" ? enforceReadRowLimit(args.sql, connection.type, resolved.maxRows) : args.sql;
-			return runClientQuery(ctx, connection, sql, runnerOptions(resolved), exec.signal);
+			const connection = await requireToolConnection(ctx, exec, "sql-cmd");
+			validateSingleSql(args.sql, "sql-cmd");
+			if ((connection.readonly ?? resolved.readonly) && classifyStatement(args.sql, connection.type) === "write") throw new Error("当前连接为只读模式，sql-cmd 拒绝执行非读语句（仅放行 SELECT/SHOW/DESCRIBE/EXPLAIN/查询型 PRAGMA 等）");
+			return runRedactedClientQuery(ctx, connection, classifyStatement(args.sql, connection.type) === "read" ? enforceReadRowLimit(args.sql, connection.type, resolved.maxRows) : args.sql, runnerOptions(resolved), exec.signal);
 		}
 	}));
+	if (ctx.get("webServer") !== void 0) ctx.tools.register(defineRenderAnalysisTool(ctx, resolved));
 }
 //#endregion
 export { Config, apply, inject, name };