@chengxianglibra/dsh-data-analysis 0.1.2 → 0.2.1

package/lib/presentation/build/index.js

@@ -7,10 +7,11 @@ import {
 } from "../contracts/index.js";
 var escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 var inlineJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
-async function buildPresentation(value) {
+async function buildPresentation(value, options = { html: true }) {
   parsePresentationDocument(value);
   const documentBytes = Buffer.from(JSON.stringify(value), "utf8");
   const document = parsePresentationDocument(JSON.parse(documentBytes.toString("utf8")));
+  if (!options.html) return { document, documentBytes };
   const [portable, staticAssets] = await Promise.all([
     import(new URL("../../../lib/presentation/assets/portable.js", import.meta.url).href),
     import(new URL("../../../lib/presentation/assets/static.js", import.meta.url).href)
@@ -35,7 +36,7 @@ async function buildPresentation(value) {
   ].join("; ");
   const htmlBytes = Buffer.from(
     `<!doctype html>
-<html lang="zh-CN">
+<html lang="${escapeHtml(document.locale)}">
 <head>
 <meta charset="utf-8">
 <meta http-equiv="Content-Security-Policy" content="${escapeHtml(csp)}">

package/lib/presentation/commit.js

@@ -23,18 +23,18 @@ async function sameDirectory(filename, expected) {
     if (actual.dev !== expected.dev || actual.ino !== expected.ino)
         throw new Error('presentation-directory-changed');
 }
-/** Owns only one newly-created build. A single directory rename publishes both complete files. */
+/** Owns only one newly-created build. A single directory rename publishes all requested complete files. */
 export async function commitPresentation(workspaceRoot, input, assertOwner, signal) {
     signal?.throwIfAborted();
     const document = parsePresentationDocument(structuredClone(input.document));
     const built = {
         document,
         documentBytes: Buffer.from(input.documentBytes),
-        htmlBytes: Buffer.from(input.htmlBytes),
+        htmlBytes: input.htmlBytes && Buffer.from(input.htmlBytes),
     };
     if (built.documentBytes.length > PRESENTATION_BUDGETS.documentBytes ||
-        built.htmlBytes.length === 0 ||
-        built.htmlBytes.length > PRESENTATION_BUDGETS.htmlBytes)
+        (built.htmlBytes !== undefined &&
+            (built.htmlBytes.length === 0 || built.htmlBytes.length > PRESENTATION_BUDGETS.htmlBytes)))
         throw new Error('presentation-build-budget');
     if (!built.documentBytes.equals(Buffer.from(JSON.stringify(document))))
         throw new Error('presentation-build-document-mismatch');
@@ -82,6 +82,8 @@ export async function commitPresentation(workspaceRoot, input, assertOwner, sign
             ['presentation.json', built.documentBytes],
             ['index.html', built.htmlBytes],
         ]) {
+            if (!bytes)
+                continue;
             await sameDirectory(temporary, ownedIdentity);
             signal?.throwIfAborted();
             const file = await open(path.join(temporary, asset), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
@@ -112,8 +114,9 @@ export async function commitPresentation(workspaceRoot, input, assertOwner, sign
         await check();
         await sameDirectory(final, ownedIdentity);
         const document = await readPresentationAsset(root, built.document.reportId, built.document.buildId, 'presentation.json', signal);
-        const html = await readPresentationAsset(root, built.document.reportId, built.document.buildId, 'index.html', signal);
-        if (!document.equals(built.documentBytes) || !html.equals(built.htmlBytes))
+        const html = built.htmlBytes &&
+            (await readPresentationAsset(root, built.document.reportId, built.document.buildId, 'index.html', signal));
+        if (!document.equals(built.documentBytes) || (html && !html.equals(built.htmlBytes)))
             throw new Error('presentation-build-changed');
         await check();
         return parsePresentationReceipt({
@@ -131,12 +134,16 @@ export async function commitPresentation(workspaceRoot, input, assertOwner, sign
                     sha256: presentationSha256(document),
                     bytes: document.length,
                 },
-                html: {
-                    asset: 'index.html',
-                    path: path.join(final, 'index.html'),
-                    sha256: presentationSha256(html),
-                    bytes: html.length,
-                },
+                ...(html
+                    ? {
+                        html: {
+                            asset: 'index.html',
+                            path: path.join(final, 'index.html'),
+                            sha256: presentationSha256(html),
+                            bytes: html.length,
+                        },
+                    }
+                    : {}),
             },
         });
     }

package/lib/presentation/contracts/asset-path.js

@@ -0,0 +1,9 @@
+/** Fixed Build locator shared by the browser and Workspace storage. */
+import { parsePresentationBuildId } from "./index.js";
+export function presentationAssetRelativePath(reportId, buildId, asset) {
+    parsePresentationBuildId(reportId, '/reportId');
+    parsePresentationBuildId(buildId);
+    if (asset !== 'presentation.json' && asset !== 'index.html')
+        throw new Error('invalid-asset');
+    return `.dsh-data-analysis/presentations/${reportId}/builds/${buildId}/${asset}`;
+}

package/lib/presentation/contracts/catalog.js

@@ -0,0 +1,62 @@
+import { parsePresentationReceipt } from "./index.js";
+export const REPORT_HISTORY_BYTES = 16 * 1024 * 1024;
+export const REPORT_HISTORY_LIMIT = 4096;
+export function parseReportVersion(value) {
+    const entry = value;
+    if (!entry ||
+        Object.keys(entry).sort().join(',') !== 'publishedAt,receipt,source' ||
+        !(entry.publishedAt === null ||
+            (typeof entry.publishedAt === 'string' &&
+                Number.isFinite(Date.parse(entry.publishedAt)) &&
+                new Date(entry.publishedAt).toISOString() === entry.publishedAt)) ||
+        !(entry.source === null ||
+            (entry.source &&
+                Object.keys(entry.source).sort().join(',') === 'kind,sessionId' &&
+                ['agent', 'reader'].includes(entry.source.kind) &&
+                (entry.source.sessionId === null ||
+                    (typeof entry.source.sessionId === 'string' &&
+                        !!entry.source.sessionId.trim() &&
+                        entry.source.sessionId.length <= 512)))))
+        throw new Error('invalid-report-history');
+    parsePresentationReceipt(entry.receipt);
+    return entry;
+}
+export function parseReportHistory(value) {
+    const history = value;
+    if (!history ||
+        !Array.isArray(history.versions) ||
+        !history.versions.length ||
+        history.versions.length > REPORT_HISTORY_LIMIT ||
+        typeof history.legacyHistoryUnavailable !== 'boolean')
+        throw new Error('invalid-report-history');
+    const ids = new Set();
+    for (const entry of history.versions) {
+        const { receipt } = parseReportVersion(entry);
+        if (receipt.workspaceId !== history.workspaceId ||
+            receipt.reportId !== history.reportId ||
+            ids.has(receipt.buildId))
+            throw new Error('invalid-report-history');
+        ids.add(receipt.buildId);
+    }
+    if (history.currentBuildId !== history.versions[0].receipt.buildId)
+        throw new Error('invalid-report-history');
+    return history;
+}
+export function parseReportCatalog(value) {
+    const catalog = value;
+    if (!catalog ||
+        typeof catalog.workspaceId !== 'string' ||
+        !Array.isArray(catalog.reports) ||
+        catalog.reports.length > 4096 ||
+        !Number.isInteger(catalog.unavailable) ||
+        catalog.unavailable < 0)
+        throw new Error('invalid-report-catalog');
+    const ids = new Set();
+    for (const item of catalog.reports) {
+        const { receipt } = parseReportVersion(item);
+        if (receipt.workspaceId !== catalog.workspaceId || ids.has(receipt.reportId))
+            throw new Error('invalid-report-catalog');
+        ids.add(receipt.reportId);
+    }
+    return catalog;
+}

package/lib/presentation/contracts/charts.js

@@ -20,26 +20,6 @@ export const CHART_TYPES = [
     'funnel',
     'waterfall',
 ];
-export const CHART_LABELS = {
-    line: '折线图',
-    area: '面积图',
-    stackedArea: '堆叠面积图',
-    sparkline: '迷你趋势图',
-    bar: '柱状图',
-    horizontalBar: '横向条形图',
-    stackedBar: '堆叠柱状图',
-    stackedBar100: '百分比堆叠柱状图',
-    horizontalStackedBar: '横向堆叠条形图',
-    horizontalStackedBar100: '横向百分比堆叠条形图',
-    histogram: '直方图',
-    boxPlot: '箱线图',
-    scatter: '散点图',
-    heatmap: '热力图',
-    pie: '环形图',
-    leaderboard: '排行榜',
-    funnel: '漏斗图',
-    waterfall: '瀑布图',
-};
 const trendTypes = ['line', 'area', 'stackedArea', 'sparkline'];
 const ratioTypes = ['stackedBar100', 'horizontalStackedBar100'];
 const singleSeriesTypes = [
@@ -233,9 +213,6 @@ export function parseChartViewShape(value, path = '') {
 export function chartColumns(view) {
     return [...new Set([view.x, ...view.y, ...Object.values(view.bindings ?? {})])];
 }
-export function chartSeriesFields(view) {
-    return [...view.y];
-}
 /** Verifies supplied values only: never bins, ranks, accumulates, normalizes or sorts. */
 export function validateChartView(view, dataset, path = '', dataPath = '/data', rowIndices) {
     const rows = rowIndices ? rowIndices.map((index) => dataset.rows[index]) : dataset.rows;

package/lib/presentation/contracts/index.js

@@ -263,7 +263,7 @@ export function formatCell(value, _column) {
     return value === null ? '—' : String(value);
 }
 function common(value, generated) {
-    version(value, '', generated ? 2 : 1);
+    version(value, '', generated ? 3 : 2);
     string(value.title, '/title', 512);
     const sources = array(value.sources, '/sources', budgets.sources);
     const sourceIds = sources.map((value, i) => {
@@ -566,18 +566,27 @@ function interaction(value, datasets, generated) {
         }
     });
 }
+function presentationLanguage(value, expected) {
+    if (value.schemaVersion !== expected)
+        fail('/schemaVersion', `Only schemaVersion ${expected} is accepted. Regenerate this report with an explicit locale.`, 'report-version-unsupported');
+    if (value.locale !== 'zh-CN' && value.locale !== 'en-US')
+        fail('/locale', 'Report locale must be zh-CN or en-US. Ask DSH to regenerate the report with an explicit language.', 'report-locale-invalid');
+}
 export function parsePresentationDraft(value) {
     bytes(value, budgets.draftBytes);
     const entry = object(value, '');
-    keys(entry, ['schemaVersion', 'title', 'datasets', 'sources', 'blocks'], ['interaction'], '');
+    presentationLanguage(entry, 2);
+    keys(entry, ['schemaVersion', 'locale', 'title', 'datasets', 'sources', 'blocks'], ['interaction'], '');
     common(entry, false);
     return entry;
 }
 export function parsePresentationDocument(value) {
     bytes(value, budgets.documentBytes);
     const entry = object(value, '');
+    presentationLanguage(entry, 3);
     keys(entry, [
         'schemaVersion',
+        'locale',
         'workspaceId',
         'reportId',
         'buildId',
@@ -618,11 +627,13 @@ export function parsePresentationReceipt(value) {
     string(entry.title, '/title', 512);
     string(entry.summary, '/summary', 2048);
     const files = object(entry.files, '/files');
-    keys(files, ['document', 'html'], [], '/files');
+    keys(files, ['document'], ['html'], '/files');
     for (const [key, asset, max] of [
         ['document', 'presentation.json', budgets.documentBytes],
         ['html', 'index.html', budgets.htmlBytes],
     ]) {
+        if (key === 'html' && !Object.hasOwn(files, key))
+            continue;
         const path = `/files/${key}`;
         const file = object(files[key], path);
         keys(file, ['asset', 'path', 'sha256', 'bytes'], [], path);
@@ -643,8 +654,9 @@ export function parsePresentationReceipt(value) {
         integer(file.bytes, `${path}/bytes`, 1, max);
     }
     const documentPath = String(object(files.document, '/files/document').path);
-    const htmlPath = String(object(files.html, '/files/html').path);
-    if (documentPath.slice(0, -'presentation.json'.length) !== htmlPath.slice(0, -'index.html'.length)) {
+    const htmlPath = files.html ? String(object(files.html, '/files/html').path) : undefined;
+    if (htmlPath !== undefined &&
+        documentPath.slice(0, -'presentation.json'.length) !== htmlPath.slice(0, -'index.html'.length)) {
         fail('/files/html/path', 'Both files must belong to the same build directory.', 'file_boundary');
     }
     return entry;

package/lib/presentation/contracts/types.js

@@ -1,4 +1,4 @@
-export const PRESENTATION_SCHEMA_VERSION = 2;
+export const PRESENTATION_SCHEMA_VERSION = 3;
 export const PRESENTATION_BUDGETS = {
     documentBytes: 4 * 1024 * 1024,
     draftBytes: 256 * 1024,

package/lib/presentation/delivery.js

@@ -1,8 +1,13 @@
+import { finishCleanup, PendingTasks } from "../lifecycle.js";
 import { MARIVO_PRESENT_TOOL_NAME, MARIVO_PRESENTATION_DELIVERY_KIND, parsePresentationDelivery, } from "./receipt.js";
 /** Persist the same envelope on nested Code dispatch even when code discards the return value. */
 export function installMarivoPresentationCodeDelivery(ctx) {
+    const tasks = new PendingTasks();
+    let active = true;
     const pending = new Map();
     const stopResult = ctx.on('tools/result', (exec, result) => {
+        if (!active)
+            return;
         if (exec.name !== MARIVO_PRESENT_TOOL_NAME || exec.parent === undefined || result.isError)
             return;
         try {
@@ -19,38 +24,48 @@ export function installMarivoPresentationCodeDelivery(ctx) {
             /* Invalid output cannot create a success card. */
         }
     });
-    const stopLog = ctx.on('tools/code-dispatch-log', async (dispatch, next) => {
-        const content = await next();
-        if (dispatch.name !== MARIVO_PRESENT_TOOL_NAME)
-            return content;
-        const key = String(dispatch.subCallId);
-        const item = pending.get(key);
-        pending.delete(key);
-        if (dispatch.isError ||
-            !item ||
-            item.delivery.dshSessionId !== String(dispatch.agent?.session.id) ||
-            item.rootCallId !== String(dispatch.exec.rootCallId))
-            return content;
-        const root = [...(dispatch.agent?.session.events ?? [])]
-            .reverse()
-            .find((event) => event.type === 'tool/call' && String(event.data.callId) === item.rootCallId);
-        if (root?.type !== 'tool/call' || root.data.turn !== item.delivery.turn)
-            return content;
-        return [
-            ...content,
-            {
-                type: MARIVO_PRESENTATION_DELIVERY_KIND,
-                delivery: item.delivery,
-            },
-        ];
-    }, { prepend: true });
-    let active = true;
+    let stopLog;
+    try {
+        stopLog = ctx.on('tools/ptc-dispatch-log', (dispatch, next) => tasks.track((async () => {
+            const content = await next();
+            if (!active)
+                return content;
+            if (dispatch.name !== MARIVO_PRESENT_TOOL_NAME)
+                return content;
+            const key = String(dispatch.subCallId);
+            const item = pending.get(key);
+            pending.delete(key);
+            if (dispatch.isError ||
+                !item ||
+                item.delivery.dshSessionId !== String(dispatch.agent?.session.id) ||
+                item.rootCallId !== String(dispatch.exec.rootCallId))
+                return content;
+            const root = [...(dispatch.agent?.session.snapshotEvents() ?? [])]
+                .reverse()
+                .find((event) => event.type === 'tool/call' && String(event.data.callId) === item.rootCallId);
+            if (root?.type !== 'tool/call' || root.data.turn !== item.delivery.turn)
+                return content;
+            return [
+                ...content,
+                {
+                    type: MARIVO_PRESENTATION_DELIVERY_KIND,
+                    delivery: item.delivery,
+                },
+            ];
+        })()), { prepend: true });
+    }
+    catch (error) {
+        active = false;
+        void finishCleanup([stopResult, () => tasks.drain()]);
+        throw error;
+    }
+    let closing;
     return () => {
-        if (!active)
-            return;
+        if (closing)
+            return closing;
         active = false;
-        stopLog();
-        stopResult();
+        closing = finishCleanup([stopLog, stopResult, () => tasks.drain()]);
         pending.clear();
+        return closing;
     };
 }

package/lib/presentation/export-html.js

@@ -0,0 +1,214 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, realpath, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { registerMarivoTool } from "../tool-lifecycle.js";
+import { readReceiptAsset } from "./asset.js";
+import { parsePresentationBuildId } from "./contracts/index.js";
+import { readReportHistory } from "./reports.js";
+export const MARIVO_EXPORT_HTML_TOOL_NAME = 'marivo_export_html';
+export function parseHtmlOutputPath(value) {
+    if (typeof value !== 'string' ||
+        !value ||
+        value.length > 4096 ||
+        value.includes('\\') ||
+        value.includes('\0') ||
+        path.isAbsolute(value) ||
+        !value.endsWith('.html'))
+        throw new Error('invalid-html-output-path');
+    const segments = value.split('/');
+    if (segments.some((part) => !part || part === '.' || part === '..') ||
+        segments[0].toLowerCase() === '.dsh-data-analysis')
+        throw new Error('invalid-html-output-path');
+    return value;
+}
+/** Workspace-local hard-link publication is atomic and never replaces an existing target. */
+async function writeHtml(root, relative, bytes, assertOwner) {
+    const parents = [root];
+    const identities = [];
+    const inspect = async (filename) => {
+        const stat = await lstat(filename);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (await realpath(filename)) !== filename)
+            throw new Error('html-output-directory-mismatch');
+        return stat;
+    };
+    const check = async () => {
+        await assertOwner();
+        for (const [index, directory] of parents.entries()) {
+            const stat = await inspect(directory);
+            if (stat.dev !== identities[index].dev || stat.ino !== identities[index].ino)
+                throw new Error('html-output-directory-changed');
+        }
+    };
+    identities.push(await inspect(root));
+    for (const part of relative.split('/').slice(0, -1)) {
+        await check();
+        const directory = path.join(parents.at(-1), part);
+        try {
+            await mkdir(directory, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        identities.push(await inspect(directory));
+        parents.push(directory);
+    }
+    await check();
+    const target = path.join(root, relative);
+    // Stage at the highest ancestor on the destination filesystem, outside movable
+    // output subdirectories where possible, without introducing cross-device links.
+    const stagingParent = parents[identities.findIndex((identity) => identity.dev === identities.at(-1).dev)];
+    const temporary = path.join(stagingParent, `.html-export-${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    const owned = await handle.stat();
+    let linked = false;
+    const removeOwned = async (filename) => {
+        try {
+            const stat = await lstat(filename);
+            if (stat.dev === owned.dev && stat.ino === owned.ino)
+                await unlink(filename);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    };
+    try {
+        await check();
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await check();
+        await link(temporary, target);
+        linked = true;
+        await check();
+        const stat = await lstat(target);
+        if (stat.dev !== owned.dev || stat.ino !== owned.ino || stat.size !== bytes.length)
+            throw new Error('html-output-changed');
+        await removeOwned(temporary);
+        await check();
+        return target;
+    }
+    catch (error) {
+        // Paths may have moved or been replaced. The open handle still owns the exact inode,
+        // including any published hard link: erase failed output without following new paths.
+        const failures = [error];
+        try {
+            await handle.truncate(0);
+            await handle.sync();
+        }
+        catch (cleanupError) {
+            failures.push(cleanupError);
+        }
+        if (linked) {
+            try {
+                await removeOwned(target);
+            }
+            catch (cleanupError) {
+                failures.push(cleanupError);
+            }
+        }
+        if (failures.length > 1)
+            throw new AggregateError(failures, 'html-export-cleanup-failed');
+        throw error;
+    }
+    finally {
+        try {
+            await removeOwned(temporary);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function createMarivoExportHtmlTool(source, session) {
+    return defineTool({
+        name: MARIVO_EXPORT_HTML_TOOL_NAME,
+        description: 'Export a saved complete report as self-contained offline HTML only when requested. Uses the current Session Workspace, without analysis, Python, publication, new Builds or unsaved reader state. Specify build_id for an exact version; otherwise freezes current at call start. output_path must be a new Workspace-relative .html file; existing files are never overwritten. Returns file metadata, not HTML content. After success, call native present({files:[{path: result.path, description: "Offline HTML report"}]}) to deliver the file before your final response.',
+        parameters: {
+            report_id: {
+                type: 'string',
+                required: true,
+                description: 'Saved Report ID from its receipt.',
+            },
+            build_id: { type: 'string', description: 'Exact saved Build ID; omit to export current.' },
+            output_path: {
+                type: 'string',
+                required: true,
+                description: 'New Workspace-relative .html path, e.g. reports/analysis.html. Parent directories may be created.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    workspace_id: { type: 'string', required: true },
+                    report_id: { type: 'string', required: true },
+                    build_id: { type: 'string', required: true },
+                    path: { type: 'string', required: true },
+                    mime_type: { type: 'string', required: true },
+                    bytes: { type: 'number', required: true },
+                    sha256: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            presentationMeta: (_args, value) => value,
+        },
+        presentCall(args) {
+            return {
+                card: 'generic',
+                kind: 'edit',
+                title: 'Export report HTML',
+                locations: [{ path: args.output_path }],
+            };
+        },
+        timeoutMs: 120_000,
+        async execute(args, exec) {
+            const reportId = parsePresentationBuildId(args.report_id, '/report_id');
+            const buildId = args.build_id === undefined
+                ? undefined
+                : parsePresentationBuildId(args.build_id, '/build_id');
+            const relative = parseHtmlOutputPath(args.output_path);
+            const owner = exec.agent;
+            if (!owner || owner.session !== session)
+                throw new Error('presentation-session-mismatch');
+            exec.signal.throwIfAborted();
+            const workspace = await source();
+            const root = path.resolve(workspace.path);
+            const check = async () => {
+                exec.signal.throwIfAborted();
+                if (owner.session !== session)
+                    throw new Error('presentation-session-mismatch');
+                const current = await source();
+                if (current.id !== workspace.id || path.resolve(current.path) !== root)
+                    throw new Error('presentation-workspace-changed');
+                exec.signal.throwIfAborted();
+            };
+            await check();
+            const history = await readReportHistory(root, workspace.id, reportId, exec.signal);
+            const receipt = buildId === undefined
+                ? history.versions[0].receipt
+                : history.versions.find((entry) => entry.receipt.buildId === buildId)?.receipt;
+            if (!receipt)
+                throw new Error('presentation-build-unavailable');
+            await check();
+            const asset = await readReceiptAsset(root, workspace.id, receipt, 'index.html', exec.signal);
+            await check();
+            const filename = await writeHtml(root, relative, asset.bytes, check);
+            return {
+                workspace_id: workspace.id,
+                report_id: reportId,
+                build_id: receipt.buildId,
+                path: filename,
+                mime_type: 'text/html',
+                bytes: asset.bytes.length,
+                sha256: asset.sha256,
+            };
+        },
+    });
+}
+export function registerMarivoExportHtmlTool(ctx, source, session) {
+    return registerMarivoTool(ctx, createMarivoExportHtmlTool(source, session));
+}

package/lib/presentation/files.js

@@ -2,16 +2,14 @@ import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, open, realpath } from 'node:fs/promises';
 import path from 'node:path';
+import { presentationAssetRelativePath } from "./contracts/asset-path.js";
 import { PRESENTATION_BUDGETS, parsePresentationBuildId, } from "./contracts/index.js";
 export function presentationReportPath(root, reportId) {
     parsePresentationBuildId(reportId, '/reportId');
     return path.join(root, '.dsh-data-analysis', 'presentations', reportId);
 }
 export function presentationAssetPath(root, reportId, buildId, asset) {
-    parsePresentationBuildId(buildId);
-    if (asset !== 'presentation.json' && asset !== 'index.html')
-        throw new Error('invalid-asset');
-    return path.join(presentationReportPath(root, reportId), 'builds', buildId, asset);
+    return path.join(root, presentationAssetRelativePath(reportId, buildId, asset));
 }
 export function presentationSha256(bytes) {
     return createHash('sha256').update(bytes).digest('hex');
@@ -46,7 +44,8 @@ export async function readReportFile(workspaceRoot, filename, maximum, signal) {
             throw new Error('asset-not-file');
         if (before.size > maximum)
             throw new Error('asset-too-large');
-        const bytes = Buffer.alloc(maximum + 1);
+        // Allocate for the observed file, retaining one extra byte to detect growth.
+        const bytes = Buffer.alloc(before.size + 1);
         let length = 0;
         while (length < bytes.length) {
             signal?.throwIfAborted();

package/lib/presentation/projection/index.js

@@ -179,7 +179,8 @@ export class MarivoPresentationProjection {
         }
         this.#assertReady(options.signal);
         return parsePresentationDocument({
-            schemaVersion: 2,
+            schemaVersion: 3,
+            locale: draft.locale,
             reportId: options.reportId,
             workspaceId: options.workspaceId,
             buildId: options.buildId,

package/lib/presentation/projection/program.js

@@ -33,7 +33,6 @@ ${MARIVO_PRESENTATION_SQL_CODE_PROGRAM}
 def read(request):
     sessions, artifacts, contracts = {}, {}, {}
     sources, datasets, diagnostics = [], [], []
-    definition_sources = []
     read_at = datetime.now(timezone.utc).isoformat()
     try:
         for index, declared in enumerate(request["sources"]):
@@ -58,7 +57,7 @@ def read(request):
             except Exception:
                 # Only the requested source becomes unavailable. Exception messages may
                 # include credentials, project paths or raw SQL and are never returned.
-                sources.append({**declared, "status": "unavailable", "reason": "The declared Artifact cannot be restored through the bound Workspace public API."})
+                sources.append({**declared, "status": "unavailable", "reason": "marivo.presentation.source-unavailable"})
                 continue
 
             artifacts[declared["id"]], contracts[declared["id"]] = artifact, contract
@@ -85,17 +84,11 @@ def read(request):
                 except ProjectionFailure:
                     raise
                 except Exception:
-                    fact("选择的 Finding unavailable", "The requested Finding cannot be read through the persisted Artifact public API.")
+                    fact("选择的 Finding unavailable", "marivo.presentation.finding-unavailable")
                     diagnostics.append({"code": "finding_unavailable", "path": source_path + "/ref/findingId", "message": "Artifact is available; its requested Finding is unavailable."})
-            if meta.kind == "metric_frame" or any(item.semantic_kind.value == "metric" for item in contract.semantic_inputs):
-                definition_sources.append(declared["id"])
-                fact("指标定义说明", "信息：Artifact 公开契约未提供生成时的指标定义快照，来源概要无法展示当时的指标含义与口径。不影响已保存数据、图表及已有代码的展示，正常阅读无需处理；核验历史口径需补充生成时的定义快照，当前语义层定义不能替代历史定义。")
             fact("revalidation", "not_requested")
             sources.append({**declared, "status": "available", "label": text(str(meta.kind) + " " + artifact.ref, 512), "facts": facts, "code": sql_code_snapshot(session, artifact)})
 
-        if definition_sources:
-            diagnostics.append({"code": "definition_unavailable", "path": "/sources", "message": "信息：" + str(len(definition_sources)) + " 个指标来源的 Artifact 公开契约未提供生成时的指标定义快照，来源概要无法展示当时的指标含义与口径。不影响已保存数据、图表及已有代码的展示，正常阅读无需处理；核验历史口径需补充生成时的定义快照，当前语义层定义不能替代历史定义。"})
-
         for selection in request["datasets"]:
             dataset_path = "/datasets/" + str(selection["index"])
             artifact = artifacts.get(selection["sourceId"])