@yejiming/dsh-data-agent 0.0.11 → 0.0.12

package/lib/index.js

@@ -1,7 +1,7 @@
 import { o as clientsSchema, t as createConnectionService } from "./connections-5sfdEDsG.js";
 import { a as DEFAULT_PRESET_ID, i as DEFAULT_MAX_RESULT_CHARS, o as DEFAULT_QUERY_TIMEOUT_MS, r as DEFAULT_MAX_QUERY_CHARS, t as DEFAULT_CONNECT_TIMEOUT_MS } from "./defaults-DP4RyRh1.js";
 import { r as apply$1 } from "./command-DuCpwVbl.js";
-import { n as apply$2 } from "./tool-DVh61An-.js";
+import { n as apply$2 } from "./tool-DgL0fBfj.js";
 import { createHash } from "node:crypto";
 import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -186,12 +186,11 @@ function resolveDshHome(env = process.env) {
 /**
 * Install the packaged `preset/data-agent/` directory into
 * `$DSH_HOME/.agent-presets/<presetId>/`. Idempotent: an existing target is
-* normally left untouched. The exact package-owned 0.0.9 composition is
-* migrated once because its two dynamic package rows are incompatible with
-* DSH Desktop's unpacked-ASAR loader; user-edited compositions are never
-* overwritten. `installPreset: false` never calls this. Best-effort — a
-* failure logs a warning with manual install instructions instead of failing
-* the boot.
+* normally left untouched. Exact package-owned legacy compositions are
+* migrated once when their runtime contract changes; user-edited compositions
+* are never overwritten. `installPreset: false` never calls this. Best-effort
+* — a failure logs a warning with manual install instructions instead of
+* failing the boot.
 */
 async function installPreset(ctx, presetId) {
 	const targetDir = join(resolveDshHome(), ".agent-presets", presetId);
@@ -210,13 +209,13 @@ async function installPreset(ctx, presetId) {
 		return false;
 	}
 }
-/** SHA-256 of the unmodified 0.0.9 composition that imported /tool and /command dynamically. */
-const LEGACY_PRESET_0_0_9_SHA256 = "bae875a90d638ea78715030246b0f8a9f1a2c3359ca61febb6ceb59d0fcd930a";
+/** SHA-256 values of unmodified package-owned compositions safe to migrate. */
+const LEGACY_MANAGED_PRESET_SHA256 = /* @__PURE__ */ new Set(["bae875a90d638ea78715030246b0f8a9f1a2c3359ca61febb6ceb59d0fcd930a", "d3c6f4049580069eec1c6b7de101f12c7fb30482ad317434afb69afb08a91fc6"]);
 /** Public for regression tests of the non-destructive preset migration gate. */
 function isLegacyManagedPreset(source) {
-	return createHash("sha256").update(source).digest("hex") === LEGACY_PRESET_0_0_9_SHA256;
+	return LEGACY_MANAGED_PRESET_SHA256.has(createHash("sha256").update(source).digest("hex"));
 }
-/** Upgrade only the exact package-owned legacy composition; preserve every edited preset. */
+/** Upgrade only exact package-owned legacy compositions; preserve every edited preset. */
 async function synchronizeExistingPreset(ctx, targetDir, sourceDir, presetId) {
 	const composition = join(targetDir, "agent.cordis.yml");
 	try {
@@ -224,7 +223,7 @@ async function synchronizeExistingPreset(ctx, targetDir, sourceDir, presetId) {
 		if (isLegacyManagedPreset(current)) {
 			const replacement = await readFile(join(sourceDir, "agent.cordis.yml"), "utf8");
 			await writeFile(composition, replacement, "utf8");
-			ctx.logger.info("data-agent: migrated preset at %s to profile-preloaded tools (removed dynamic /tool and /command rows)", composition);
+			ctx.logger.info("data-agent: migrated package-owned preset at %s to the current runtime contract", composition);
 			return true;
 		}
 		if (current.includes("@yejiming/dsh-data-agent/tool") || current.includes("@yejiming/dsh-data-agent/command")) {

package/lib/{tool-DVh61An-.js → tool-DgL0fBfj.js}

@@ -1,5 +1,8 @@
 import { a as classifyStatement, c as assertSingleStatement, i as runClientQuery, n as redactQueryResult, o as clientsSchema, r as redactSecretText, s as enforceReadRowLimit } from "./connections-5sfdEDsG.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 { randomUUID } from "node:crypto";
+import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
 import z from "schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 const VIEW_KINDS = [
@@ -203,11 +206,14 @@ function parseAnalysisRequest(input, prefix = "render-analysis") {
 	if (!isRecord(input)) fail(prefix + ": 请求必须是对象");
 	assertOnlyKeys(input, [
 		"title",
+		"outputName",
 		"summary",
 		"datasets",
 		"views"
 	], prefix);
 	const title = requireNonEmptyString(input["title"], prefix + ".title");
+	const outputName = optionalString(input, "outputName", prefix);
+	if (outputName !== void 0 && outputName.trim().length === 0) fail(prefix + ".outputName: 必须是非空字符串");
 	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 个");
@@ -242,6 +248,7 @@ function parseAnalysisRequest(input, prefix = "render-analysis") {
 		datasets: parsedDatasets,
 		views: parsedViews
 	};
+	if (outputName !== void 0) request.outputName = outputName;
 	if (summary !== void 0) request.summary = summary;
 	return request;
 }
@@ -312,13 +319,15 @@ function rowsToArrays(columns, rows) {
 }
 /** JSON-encoded UTF-8 size of the normalized report (the 512 KiB bound). */
 function reportJsonBytes(report) {
-	return new TextEncoder().encode(JSON.stringify(report)).length;
+	const { htmlPath: _htmlPath, ...dataReport } = report;
+	return new TextEncoder().encode(JSON.stringify(dataReport)).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("、") + "。";
+	if (report.htmlPath !== void 0) text += "Dashboard HTML已保存：" + report.htmlPath;
 	return text;
 }
 const BASE_VIEW_PROPERTIES = {
@@ -508,6 +517,10 @@ const RENDER_ANALYSIS_PARAMETERS = {
 		required: true,
 		description: "报告标题，如「月度经营分析」"
 	},
+	outputName: {
+		type: "string",
+		description: "可选语义化HTML文件名（仅basename，可省略.html），如「电商经营全景分析-2023-09至2026-08」；缺省时使用title，不要使用随机ID"
+	},
 	summary: {
 		type: "string",
 		description: "可选一句话结论/摘要，显示在报告头部"
@@ -554,6 +567,10 @@ const ANALYSIS_REPORT_OUTPUT_SCHEMA = {
 			required: true
 		},
 		summary: { type: "string" },
+		htmlPath: {
+			type: "string",
+			required: true
+		},
 		datasets: {
 			type: "array",
 			required: true,
@@ -810,6 +827,127 @@ async function runStructuredReadQuery(ctx, connection, sql, resolved, toolName,
 	};
 }
 //#endregion
+//#region src/analysis-html.ts
+/**
+* Offline HTML artifact for one validated AnalysisReportV1.
+*
+* The generated page has no network/runtime dependencies. Untrusted report
+* strings stay inside escaped JSON and are projected with textContent only;
+* chart geometry is derived from already-validated finite numeric fields.
+* @module @yejiming/dsh-data-agent/analysis-html
+*/
+const ANALYSIS_REPORT_DIRECTORY = "analysis-reports";
+/** Convert a report title/output name into a bounded, readable filename segment. */
+function analysisFileSegment(value, fallback) {
+	const sanitize = (candidate) => candidate.normalize("NFKC").replace(/\.html$/i, "").replace(/[\u0000-\u001f\u007f-\u009f]/g, "").replace(/[^\p{Letter}\p{Number}]+/gu, "-").replace(/^-+|-+$/g, "").slice(0, 96);
+	return sanitize(value) || sanitize(fallback) || "analysis-report";
+}
+/** Relative path shared by the writer and DSH's mutation presentation. */
+function analysisArtifactRelativePath(title, outputName) {
+	const basename = analysisFileSegment(outputName ?? title, "分析报告");
+	return `${ANALYSIS_REPORT_DIRECTORY}/${basename}.html`;
+}
+/** Escape JSON so data cannot close its application/json script element. */
+function escapeJsonForHtmlScript(value) {
+	return JSON.stringify(value).replace(/&/g, "\\u0026").replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+/** Render one complete, offline Dashboard document. */
+function renderAnalysisHtml(report, generatedAt = (/* @__PURE__ */ new Date()).toISOString()) {
+	return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'none'; font-src 'none'; object-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'">
+  <title>DSH Data Agent Analysis</title>
+  <style>
+    :root{color-scheme:light dark;--bg:oklch(97.4% .006 255);--panel:oklch(99.2% .003 255);--text:oklch(27% .035 255);--muted:oklch(52% .025 255);--line:oklch(88% .012 255);--grid:oklch(92% .008 255);--accent:oklch(58% .16 255);--palette:#4e79a7,#f28e2b,#59a14f,#e15759,#76b7b2,#edc948,#b07aa1,#9c755f}
+    @media(prefers-color-scheme:dark){:root{--bg:oklch(19% .018 255);--panel:oklch(23% .02 255);--text:oklch(93% .012 255);--muted:oklch(72% .018 255);--line:oklch(35% .022 255);--grid:oklch(31% .018 255);--accent:oklch(72% .13 255)}}
+    *{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:14px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif}main{width:min(1440px,calc(100% - 32px));margin:0 auto;padding:24px 0 48px}header{padding-bottom:16px;margin-bottom:16px;border-bottom:1px solid var(--line)}h1{margin:0;font-size:24px;line-height:1.25;font-weight:650;letter-spacing:-.015em}header p{max-width:1120px;margin:7px 0 0;color:var(--muted)}.report-count{font-size:13px;color:var(--text)}.metric-band{display:flex;flex-wrap:wrap;gap:8px;padding-bottom:12px;margin-bottom:12px;border-bottom:1px solid var(--line)}.metric{flex:1 1 180px;min-width:150px;padding:9px 12px;background:var(--panel);border:1px solid var(--line);border-radius:8px;break-inside:avoid}.metric-label{margin:0;color:var(--muted);font-size:12px}.metric-value{margin:2px 0 0;font-size:18px;line-height:1.35;font-weight:650;font-variant-numeric:tabular-nums;overflow-wrap:anywhere}.dashboard{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.view{min-width:0;padding:11px 12px;background:var(--panel);border:1px solid var(--line);border-radius:8px;break-inside:avoid}.view.full,.view.table{grid-column:1/-1}.view h2{font-size:13px;line-height:1.4;font-weight:650;margin:0 0 8px}.empty{padding:28px 12px;text-align:center;color:var(--muted);border:1px dashed var(--line);border-radius:7px}.chart{width:100%;height:auto;min-height:260px;display:block}.axis{stroke:var(--line);stroke-width:1}.grid{stroke:var(--grid);stroke-width:1}.axis-label,.legend{fill:var(--muted);font-size:11px}.legend-row{display:flex;gap:12px;flex-wrap:wrap;color:var(--muted);font-size:12px;margin-top:6px}.dot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:5px}details{margin-top:10px;border-top:1px solid var(--line);padding-top:8px}summary{cursor:pointer;color:var(--accent);font-size:12px}.table-wrap{overflow:auto;max-height:460px;border:1px solid var(--line);border-radius:6px}table{width:100%;border-collapse:collapse;white-space:nowrap;font-size:12px}th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line);vertical-align:top}th{position:sticky;top:0;background:var(--bg);font-weight:600}td{max-width:420px;white-space:pre-wrap;overflow-wrap:anywhere}.null{color:var(--muted);font-style:italic}footer{margin-top:18px;color:var(--muted);font-size:12px}
+    @media(max-width:880px){main{width:min(100% - 20px,1440px);padding-top:18px}h1{font-size:21px}.dashboard{grid-template-columns:1fr}.view{grid-column:1!important}.metric{flex-basis:100%}}
+    @media print{:root{color-scheme:light;--bg:oklch(98.5% .003 255);--panel:oklch(99.5% .002 255);--text:oklch(24% .025 255);--muted:oklch(48% .02 255);--line:oklch(84% .01 255);--grid:oklch(90% .008 255)}.dashboard{display:block}.view{margin:0 0 12px}.table-wrap{max-height:none;overflow:visible}details{display:block}details>summary{display:none}details>*{display:block!important}main{width:100%;padding:0}}
+  </style>
+</head>
+<body>
+  <main>
+    <header id="report-header"></header>
+    <section id="metric-band" class="metric-band" aria-label="关键指标"></section>
+    <section id="dashboard" class="dashboard" aria-label="分析视图"></section>
+    <footer id="report-footer"></footer>
+  </main>
+  <script type="application/json" id="report-data">${escapeJsonForHtmlScript(report)}<\/script>
+  <script>
+  (()=>{'use strict';
+    const report=JSON.parse(document.getElementById('report-data').textContent||'{}');
+    const palette=['#4e79a7','#f28e2b','#59a14f','#e15759','#76b7b2','#edc948','#b07aa1','#9c755f'];
+    const ns='http://www.w3.org/2000/svg';
+    const el=(tag,className,text)=>{const node=document.createElement(tag);if(className)node.className=className;if(text!==undefined)node.textContent=String(text);return node};
+    const svgEl=(tag,attrs={})=>{const node=document.createElementNS(ns,tag);for(const [key,value] of Object.entries(attrs))node.setAttribute(key,String(value));return node};
+    const datasetFor=id=>report.datasets.find(item=>item.id===id);
+    const indexOf=(dataset,field)=>dataset.columns.indexOf(field);
+    const number=value=>value===null||value===undefined||value===''?null:(Number.isFinite(Number(value))?Number(value):null);
+    const extent=(values,includeZero=false)=>{const finite=values.filter(Number.isFinite);let min=finite.length?Math.min(...finite):0,max=finite.length?Math.max(...finite):1;if(includeZero){min=Math.min(0,min);max=Math.max(0,max)}if(min===max){min-=1;max+=1}return[min,max]};
+    const scale=(value,min,max,start,end)=>start+(value-min)/(max-min)*(end-start);
+    const titleFor=view=>view.label||({metric:'指标',line:'趋势',bar:'对比',pie:'构成',scatter:'分布',table:'明细'}[view.kind]||view.id);
+    const empty=()=>el('div','empty','暂无数据');
+    function tableFor(dataset,columns){const selected=(columns&&columns.length?columns:dataset.columns).map(name=>[name,indexOf(dataset,name)]);const wrap=el('div','table-wrap');const table=el('table');const head=el('thead');const hr=el('tr');selected.forEach(([name])=>hr.append(el('th','',name)));head.append(hr);table.append(head);const body=el('tbody');dataset.rows.forEach(row=>{const tr=el('tr');selected.forEach(([,index])=>{const value=row[index];const td=el('td',value===null?'null':'',value===null?'NULL':value);tr.append(td)});body.append(tr)});table.append(body);wrap.append(table);return wrap}
+    function detailsFor(dataset,columns){const details=el('details');details.append(el('summary','','查看原始数据（'+dataset.rows.length+'行）'));details.append(tableFor(dataset,columns));return details}
+    function baseSvg(){const svg=svgEl('svg',{viewBox:'0 0 760 300',role:'img',class:'chart','aria-label':'数据图表'});for(let i=0;i<5;i++){const y=30+i*55;svg.append(svgEl('line',{x1:58,y1:y,x2:738,y2:y,class:'grid'}))}svg.append(svgEl('line',{x1:58,y1:250,x2:738,y2:250,class:'axis'}));svg.append(svgEl('line',{x1:58,y1:20,x2:58,y2:250,class:'axis'}));return svg}
+    function axisText(svg,text,x,y,anchor='start'){const node=svgEl('text',{x,y,'text-anchor':anchor,class:'axis-label'});node.textContent=String(text);svg.append(node)}
+    function legend(card,names){if(names.length<2)return;const row=el('div','legend-row');names.forEach((name,index)=>{const item=el('span');const dot=el('i','dot');dot.style.background=palette[index%palette.length];item.append(dot,document.createTextNode(String(name)));row.append(item)});card.append(row)}
+    function lineChart(card,view,dataset){const xIndex=indexOf(dataset,view.x.field);const grouped=new Map();if(view.seriesField){const groupIndex=indexOf(dataset,view.seriesField),yIndex=indexOf(dataset,view.y[0]);dataset.rows.forEach((row,index)=>{const name=row[groupIndex]??'';if(!grouped.has(name))grouped.set(name,[]);grouped.get(name).push({index,x:row[xIndex],y:number(row[yIndex])})})}else view.y.forEach(field=>{const yIndex=indexOf(dataset,field);grouped.set(field,dataset.rows.map((row,index)=>({index,x:row[xIndex],y:number(row[yIndex])}))) });const all=[...grouped.values()].flat().map(point=>point.y).filter(value=>value!==null);if(!all.length){card.append(empty());return}const [min,max]=extent(all);const svg=baseSvg();axisText(svg,max.toLocaleString(),52,27,'end');axisText(svg,min.toLocaleString(),52,250,'end');axisText(svg,view.x.label||view.x.field,398,286,'middle');const count=Math.max(2,dataset.rows.length);[...grouped.entries()].forEach(([name,points],seriesIndex)=>{let segment=[];const flush=()=>{if(segment.length){svg.append(svgEl('polyline',{points:segment.join(' '),fill:'none',stroke:palette[seriesIndex%palette.length],'stroke-width':3,'stroke-linejoin':'round','stroke-linecap':'round'}));segment=[]}};points.forEach(point=>{if(point.y===null){flush();return}const x=scale(point.index,0,count-1,62,734),y=scale(point.y,min,max,246,24);segment.push(x+','+y);svg.append(svgEl('circle',{cx:x,cy:y,r:3,fill:palette[seriesIndex%palette.length]}))});flush()});card.append(svg);legend(card,[...grouped.keys()])}
+    function barChart(card,view,dataset){const xIndex=indexOf(dataset,view.x.field);const series=view.seriesField?[view.seriesField]:view.y;const values=[];const entries=[];if(view.seriesField){const groupIndex=indexOf(dataset,view.seriesField),yIndex=indexOf(dataset,view.y[0]);dataset.rows.forEach((row,index)=>{const value=number(row[yIndex]);if(value!==null){values.push(value);entries.push({index,value,name:row[groupIndex]??'',x:row[xIndex]??''})}})}else dataset.rows.forEach((row,index)=>view.y.forEach((field,seriesIndex)=>{const value=number(row[indexOf(dataset,field)]);if(value!==null){values.push(value);entries.push({index,value,name:field,seriesIndex,x:row[xIndex]??''})}}));if(!values.length){card.append(empty());return}const [min,max]=extent(values,true),svg=baseSvg(),zero=scale(0,min,max,246,24),groups=Math.max(1,dataset.rows.length),barWidth=Math.max(2,Math.min(36,620/(groups*Math.max(1,series.length))));svg.append(svgEl('line',{x1:58,y1:zero,x2:738,y2:zero,stroke:'var(--muted)','stroke-width':1.5}));entries.forEach((entry,entryIndex)=>{const seriesIndex=entry.seriesIndex??Math.max(0,series.indexOf(entry.name));const center=scale(entry.index+.5,0,groups,62,734);const offset=(seriesIndex-(series.length-1)/2)*barWidth;const y=scale(entry.value,min,max,246,24);svg.append(svgEl('rect',{x:center+offset-barWidth*.42,y:Math.min(y,zero),width:barWidth*.84,height:Math.max(1,Math.abs(zero-y)),rx:2,fill:palette[(seriesIndex<0?entryIndex:seriesIndex)%palette.length]}))});axisText(svg,max.toLocaleString(),52,27,'end');axisText(svg,min.toLocaleString(),52,250,'end');axisText(svg,view.x.label||view.x.field,398,286,'middle');card.append(svg);legend(card,series)}
+    function pieChart(card,view,dataset){const cIndex=indexOf(dataset,view.categoryField),vIndex=indexOf(dataset,view.valueField);const entries=dataset.rows.map(row=>({name:row[cIndex]??'',value:number(row[vIndex])??0})),total=entries.reduce((sum,item)=>sum+item.value,0);if(total<=0){card.append(empty());return}const svg=svgEl('svg',{viewBox:'0 0 760 300',role:'img',class:'chart','aria-label':'构成图'}),cx=235,cy=150,r=105;let angle=-Math.PI/2;entries.forEach((entry,index)=>{const next=angle+entry.value/total*Math.PI*2,x1=cx+Math.cos(angle)*r,y1=cy+Math.sin(angle)*r,x2=cx+Math.cos(next)*r,y2=cy+Math.sin(next)*r,large=next-angle>Math.PI?1:0;const path=svgEl('path',{d:'M '+cx+' '+cy+' L '+x1+' '+y1+' A '+r+' '+r+' 0 '+large+' 1 '+x2+' '+y2+' Z',fill:palette[index%palette.length]});svg.append(path);angle=next});entries.forEach((entry,index)=>{const y=46+index*25;svg.append(svgEl('circle',{cx:490,cy:y-4,r:5,fill:palette[index%palette.length]}));axisText(svg,entry.name+'  '+(entry.value/total*100).toFixed(1)+'%',505,y)});card.append(svg)}
+    function scatterChart(card,view,dataset){const xi=indexOf(dataset,view.xField),yi=indexOf(dataset,view.yField),points=dataset.rows.map(row=>[number(row[xi]),number(row[yi])]).filter(point=>point[0]!==null&&point[1]!==null);if(!points.length){card.append(empty());return}const [xmin,xmax]=extent(points.map(point=>point[0])),[ymin,ymax]=extent(points.map(point=>point[1])),svg=baseSvg();points.forEach(point=>svg.append(svgEl('circle',{cx:scale(point[0],xmin,xmax,62,734),cy:scale(point[1],ymin,ymax,246,24),r:4,fill:palette[0],opacity:.82})));axisText(svg,ymax.toLocaleString(),52,27,'end');axisText(svg,ymin.toLocaleString(),52,250,'end');axisText(svg,xmin.toLocaleString(),62,270);axisText(svg,xmax.toLocaleString(),734,270,'end');axisText(svg,view.xField,398,288,'middle');card.append(svg)}
+    const header=document.getElementById('report-header');header.append(el('h1','',report.title));if(report.summary)header.append(el('p','',report.summary));header.append(el('p','report-count',report.datasets.length+'个数据集 · '+report.views.length+'个视图'));
+    const widths=new Map();let firstChartPlaced=false;report.views.forEach(view=>{if(view.kind==='metric')return;if(view.width){widths.set(view.id,view.width);if(['line','bar','pie','scatter'].includes(view.kind))firstChartPlaced=true;return}const width=view.kind==='table'||!firstChartPlaced?'full':'half';widths.set(view.id,width);if(['line','bar','pie','scatter'].includes(view.kind))firstChartPlaced=true});
+    const metricBand=document.getElementById('metric-band');const metrics=report.views.filter(view=>view.kind==='metric');if(metrics.length===0)metricBand.remove();else metrics.forEach(view=>{const dataset=datasetFor(view.datasetId),metric=el('article','metric');metric.append(el('p','metric-label',titleFor(view)));if(!dataset||dataset.rows.length===0)metric.append(el('p','metric-value','—'));else{const value=number(dataset.rows[0][indexOf(dataset,view.field)]);metric.append(el('p','metric-value',value===null?'—':(view.format==='percent'?(value*100).toLocaleString()+'%':value.toLocaleString())))}metricBand.append(metric)});
+    const dashboard=document.getElementById('dashboard');report.views.filter(view=>view.kind!=='metric').forEach(view=>{const dataset=datasetFor(view.datasetId),card=el('article','view '+(widths.get(view.id)==='full'?'full ':'')+view.kind);card.append(el('h2','',titleFor(view)));if(!dataset||dataset.rows.length===0)card.append(empty());else if(view.kind==='table')card.append(tableFor(dataset,view.columns));else{if(view.kind==='line')lineChart(card,view,dataset);if(view.kind==='bar')barChart(card,view,dataset);if(view.kind==='pie')pieChart(card,view,dataset);if(view.kind==='scatter')scatterChart(card,view,dataset);card.append(detailsFor(dataset))}dashboard.append(card)});
+    document.getElementById('report-footer').textContent='由 DSH Data Agent 生成 · '+${escapeJsonForHtmlScript(generatedAt)}+' · 离线HTML';
+  })();
+  <\/script>
+</body>
+</html>`;
+}
+/** Atomically persist one report and return the report enriched with htmlPath. */
+async function writeAnalysisHtml(report, options) {
+	const directory = resolve(options.cwd, ANALYSIS_REPORT_DIRECTORY);
+	const relativePath = analysisArtifactRelativePath(report.title, options.outputName);
+	const htmlPath = resolve(options.cwd, relativePath);
+	const complete = {
+		...report,
+		htmlPath
+	};
+	const basename = analysisFileSegment(options.outputName ?? report.title, "分析报告");
+	const temporaryPath = resolve(directory, `.${basename}.${randomUUID()}.tmp`);
+	try {
+		await mkdir(directory, { recursive: true });
+		await writeFile(temporaryPath, renderAnalysisHtml(complete, options.generatedAt), {
+			encoding: "utf8",
+			flag: "wx"
+		});
+		await link(temporaryPath, htmlPath);
+		await unlink(temporaryPath).catch(() => void 0);
+	} catch (error) {
+		await unlink(temporaryPath).catch(() => void 0);
+		const message = error instanceof Error ? error.message : String(error);
+		const detail = error?.code === "EEXIST" ? "目标文件已存在，请使用更具体的outputName" : message;
+		throw new Error(`render-analysis: 保存Dashboard HTML失败（${htmlPath}）：${detail}`, { cause: error });
+	}
+	return complete;
+}
+//#endregion
+//#region src/presentation-text.ts
+/** Surface-neutral control-sequence sanitization for generic tool cards. */
+const CONTROL_ESCAPE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu;
+const OSC_SEQUENCE = /\u001b\][\s\S]*?(?:\u0007|\u001b\\)/gu;
+const CSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]/gu;
+const ESC_SEQUENCE = /\u001b(?:[@-_]|[ -/]+[@-~]?)/gu;
+/** Remove control effects while keeping their presence visible to the user. */
+function sanitizePresentationText(value) {
+	return String(value ?? "").replace(OSC_SEQUENCE, "⟦OSC⟧").replace(CSI_SEQUENCE, "⟦ESC⟧").replace(ESC_SEQUENCE, "⟦ESC⟧").replace(/\r\n?/gu, "\\n").replace(/\n/gu, "\\n").replace(/\t/gu, "\\t").replace(CONTROL_ESCAPE, (character) => `\\x${character.codePointAt(0).toString(16).padStart(2, "0")}`);
+}
+//#endregion
 //#region src/tool.ts
 /** Cordis plugin name (diagnostics only). */
 const name = "data-agent-tool";
@@ -852,7 +990,7 @@ function validateSingleSql(sql, toolName) {
 	assertSingleStatement(sql, toolName);
 }
 /**
-* The Web-only render-analysis tool (D1-D5): one call builds one versioned
+* The surface-neutral 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.
@@ -860,7 +998,7 @@ function validateSingleSql(sql, toolName) {
 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.",
+		description: "Render one versioned analysis report (v1) from 1-6 read-only datasets using 1-8 metric, line, bar, pie, scatter, or table views, then save an offline Dashboard HTML file under analysis-reports/ in the current session workspace. 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,
@@ -872,14 +1010,18 @@ function defineRenderAnalysisTool(ctx, resolved) {
 		},
 		presentCall: (args) => ({
 			card: "generic",
-			kind: "read",
-			title: "render-analysis《" + args.title + "》",
-			rawInput: args.title
+			kind: "edit",
+			title: "render-analysis《" + sanitizePresentationText(args.title) + "》",
+			rawInput: sanitizePresentationText(args.title),
+			locations: [{ path: analysisArtifactRelativePath(args.title, args.outputName) }]
 		}),
 		presentResult: (args, result) => ({
 			card: "generic",
-			title: "render-analysis《" + args.title + "》",
-			content: result.content
+			title: "render-analysis《" + sanitizePresentationText(args.title) + "》",
+			content: result.content.map((item) => item.type === "text" ? {
+				...item,
+				text: sanitizePresentationText(item.text)
+			} : item)
 		}),
 		async execute(args, exec) {
 			const request = parseAnalysisRequest(args);
@@ -928,7 +1070,11 @@ function defineRenderAnalysisTool(ctx, resolved) {
 			};
 			const bytes = reportJsonBytes(report);
 			if (bytes > 524288) throw new Error("render-analysis: 报告 JSON 超过 524288 字节上限（当前 " + bytes + " 字节）；请聚合、筛选或拆分报告，不得静默删减数据");
-			return report;
+			const sessionCwd = exec.agent?.session?.header?.cwd;
+			return await writeAnalysisHtml(report, {
+				cwd: typeof sessionCwd === "string" && sessionCwd.length > 0 ? sessionCwd : process.cwd(),
+				outputName: request.outputName
+			});
 		}
 	});
 }
@@ -1122,7 +1268,7 @@ function apply(ctx, config) {
 			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));
+	ctx.tools.register(defineRenderAnalysisTool(ctx, resolved));
 }
 //#endregion
 export { name as i, apply as n, inject as r, Config as t };

package/lib/tool.js

@@ -1,2 +1,2 @@
-import { i as name, n as apply, r as inject, t as Config } from "./tool-DVh61An-.js";
+import { i as name, n as apply, r as inject, t as Config } from "./tool-DgL0fBfj.js";
 export { Config, apply, inject, name };

package/lib/types/analysis-html.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Offline HTML artifact for one validated AnalysisReportV1.
+ *
+ * The generated page has no network/runtime dependencies. Untrusted report
+ * strings stay inside escaped JSON and are projected with textContent only;
+ * chart geometry is derived from already-validated finite numeric fields.
+ * @module @yejiming/dsh-data-agent/analysis-html
+ */
+import type { AnalysisReportV1 } from './analysis.ts';
+export declare const ANALYSIS_REPORT_DIRECTORY = "analysis-reports";
+/** Convert a report title/output name into a bounded, readable filename segment. */
+export declare function analysisFileSegment(value: string, fallback: string): string;
+/** Relative path shared by the writer and DSH's mutation presentation. */
+export declare function analysisArtifactRelativePath(title: string, outputName?: string): string;
+/** Escape JSON so data cannot close its application/json script element. */
+export declare function escapeJsonForHtmlScript(value: unknown): string;
+/** Render one complete, offline Dashboard document. */
+export declare function renderAnalysisHtml(report: AnalysisReportV1, generatedAt?: string): string;
+export interface WriteAnalysisHtmlOptions {
+    cwd: string;
+    outputName?: string;
+    generatedAt?: string;
+}
+/** Atomically persist one report and return the report enriched with htmlPath. */
+export declare function writeAnalysisHtml(report: AnalysisReportV1, options: WriteAnalysisHtmlOptions): Promise<AnalysisReportV1 & {
+    htmlPath: string;
+}>;

package/lib/types/analysis.d.ts

@@ -87,6 +87,8 @@ export interface AnalysisDatasetRequestV1 {
 /** The wire request accepted by the render-analysis tool. */
 export interface AnalysisRequestV1 {
     title: string;
+    /** Semantic output basename; directory is always analysis-reports/. */
+    outputName?: string;
     summary?: string;
     datasets: AnalysisDatasetRequestV1[];
     views: AnalysisViewV1[];
@@ -102,6 +104,8 @@ export interface AnalysisReportV1 {
     version: typeof ANALYSIS_REPORT_VERSION;
     title: string;
     summary?: string;
+    /** Absolute path of the generated HTML artifact (absent on legacy v1 meta). */
+    htmlPath?: string;
     datasets: AnalysisDatasetResultV1[];
     views: AnalysisViewV1[];
 }
@@ -136,7 +140,7 @@ export declare function rowsToArrays(columns: string[], rows: readonly Record<st
 /** JSON-encoded UTF-8 size of the normalized report (the 512 KiB bound). */
 export declare function reportJsonBytes(report: AnalysisReportV1): number;
 /** One-line model-facing summary; never re-injects rows into model context (D5). */
-export declare function formatAnalysisSummary(report: Pick<AnalysisReportV1, 'title' | 'datasets' | 'views'>): string;
+export declare function formatAnalysisSummary(report: Pick<AnalysisReportV1, 'title' | 'datasets' | 'views' | 'htmlPath'>): string;
 /** The view union: exactly the six supported kinds, nothing else. */
 export declare const ANALYSIS_VIEWS_SCHEMA: {
     readonly oneOf: readonly [{
@@ -423,6 +427,10 @@ export declare const RENDER_ANALYSIS_PARAMETERS: {
         readonly required: true;
         readonly description: "报告标题，如「月度经营分析」";
     };
+    readonly outputName: {
+        readonly type: "string";
+        readonly description: "可选语义化HTML文件名（仅basename，可省略.html），如「电商经营全景分析-2023-09至2026-08」；缺省时使用title，不要使用随机ID";
+    };
     readonly summary: {
         readonly type: "string";
         readonly description: "可选一句话结论/摘要，显示在报告头部";
@@ -748,6 +756,10 @@ export declare const ANALYSIS_REPORT_OUTPUT_SCHEMA: {
         readonly summary: {
             readonly type: "string";
         };
+        readonly htmlPath: {
+            readonly type: "string";
+            readonly required: true;
+        };
         readonly datasets: {
             readonly type: "array";
             readonly required: true;

package/lib/types/index.d.ts

@@ -166,12 +166,11 @@ export declare function resolveDshHome(env?: Record<string, string | undefined>)
 /**
  * Install the packaged `preset/data-agent/` directory into
  * `$DSH_HOME/.agent-presets/<presetId>/`. Idempotent: an existing target is
- * normally left untouched. The exact package-owned 0.0.9 composition is
- * migrated once because its two dynamic package rows are incompatible with
- * DSH Desktop's unpacked-ASAR loader; user-edited compositions are never
- * overwritten. `installPreset: false` never calls this. Best-effort — a
- * failure logs a warning with manual install instructions instead of failing
- * the boot.
+ * normally left untouched. Exact package-owned legacy compositions are
+ * migrated once when their runtime contract changes; user-edited compositions
+ * are never overwritten. `installPreset: false` never calls this. Best-effort
+ * — a failure logs a warning with manual install instructions instead of
+ * failing the boot.
  */
 export declare function installPreset(ctx: Context, presetId: string): Promise<boolean>;
 /** Public for regression tests of the non-destructive preset migration gate. */

package/lib/types/presentation-text.d.ts

@@ -0,0 +1,3 @@
+/** Surface-neutral control-sequence sanitization for generic tool cards. */
+/** Remove control effects while keeping their presence visible to the user. */
+export declare function sanitizePresentationText(value: unknown): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yejiming/dsh-data-agent",
   "description": "Data Agent for DSH Web and TUI: shared database connections, a masked TUI form, secure credential references, SQL tools, and the data-agent preset",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "publishConfig": {
     "access": "public"
   },
@@ -78,25 +78,25 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage-json": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage-json": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7",
     "react": "^18.2.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -130,26 +130,26 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-tool": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-storage-json": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-client-ui-tool": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-scope": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-storage-json": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-subprocess": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-subprocess-local": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.7",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.0.0",

package/preset/data-agent/agent.cordis.yml

@@ -27,9 +27,11 @@
       你是数据工程师 Agent。工作目录 {{cwd}}。可用工具：sql-query（只读 SQL，返回结构化
       JSON 结果）、sql-write（写/管理 SQL，单条自动提交）、sql-cmd（原始客户端输出，兼容
       SHOW TABLES、DESCRIBE users 等命令）、str_replace_editor（查看、创建和修改本地文件）。
-      Web 界面可用时另有 render-analysis：把一次调用渲染成一份版本化分析报告（1-6 个只读
-      数据集、1-8 个 metric/line/bar/pie/scatter/table 视图，同一数据集可被多个视图通过
-      datasetId 复用）。是否生成分析由你自主判断：先用 sql-query 探查表结构与样例数据并
+      另有 render-analysis：把一次调用渲染成一份版本化分析
+      报告（1-6 个只读数据集、1-8 个 metric/line/bar/pie/scatter/table 视图，同一数据集可被
+      多个视图通过 datasetId 复用），并在当前工作目录的 analysis-reports/ 中保存离线 HTML
+      Dashboard。Web 可同时打开分析面板；TUI 只返回 HTML 路径，不输出字符图。是否生成分析
+      由你自主判断：先用 sql-query 探查表结构与样例数据并
       核对事实（禁止臆造表名与列名）；schema 探查、单标量或原始明细等无视觉增益的查询
       直接回答、不强制画图；简单关系可生成一个主图，涉及多指标、时间或分群的复杂问题可
       生成 3-6 个互补视图。聚合、Top N、排序必须写在 SQL 中，line/time 数据需 ORDER BY。