@v587d/capital-generation 2.8.3 → 2.9.1

package/lib/chart/present-tool.js

@@ -0,0 +1,128 @@
+import { MAX_CHARTS_PER_TURN } from './events.js';
+import { callerSession } from '../tool-exec.js';
+const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const parameters = jsonObject({
+    chart_refs: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'data_junior 回传的全部 chart_ref，一次传完（最多 8 个，不猜写）。与 task_id 至少给一个。',
+    },
+    task_id: {
+        type: 'string',
+        description: '本任务 canonical task_id：省略 chart_refs 时按它登记本会话该任务的全部图表（上下文压缩后记不清 refs 时用）。',
+    },
+});
+const receiptSchema = jsonObject({
+    presented: {
+        type: 'array',
+        items: jsonObject({
+            chart_ref: { type: 'string' },
+            title: { type: 'string' },
+        }, ['chart_ref', 'title']),
+    },
+    failed: {
+        type: 'array',
+        items: jsonObject({
+            chart_ref: { type: 'string' },
+            reason: { type: 'string' },
+        }, ['chart_ref', 'reason']),
+    },
+}, ['presented', 'failed']);
+function normalizeRefs(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('present_charts 的 chart_refs 必须是字符串数组');
+    const refs = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || item.trim().length === 0)
+            throw new Error('present_charts 的 chart_refs 里不能有空值');
+        const ref = item.trim();
+        if (!refs.includes(ref))
+            refs.push(ref);
+    }
+    if (refs.length > MAX_CHARTS_PER_TURN) {
+        throw new Error(`present_charts 一次最多登记 ${MAX_CHARTS_PER_TURN} 张图（收到 ${refs.length} 个 chart_ref）`);
+    }
+    return refs;
+}
+function normalizeTaskId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0)
+        throw new Error('present_charts 的 task_id 必须是非空字符串');
+    return value.trim();
+}
+/** Present refs first; otherwise present the whole task so compaction cannot strand the charts. */
+function selectArtifacts(input, session, refs, taskId) {
+    const failed = [];
+    if (refs.length > 0) {
+        const selected = [];
+        for (const chartRef of refs) {
+            try {
+                selected.push(input.artifacts.resolve({ session, chart_ref: chartRef, task_id: taskId }));
+            }
+            catch (error) {
+                failed.push({ chart_ref: chartRef, reason: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        // A stale ref set must not strand charts the task_id can still find (compaction can mix both).
+        if (selected.length > 0 || taskId === undefined)
+            return { selected, failed };
+    }
+    if (taskId === undefined)
+        throw new Error('present_charts 需要 chart_refs 或 task_id：两者都不给就无法确定要登记哪几张图');
+    const all = input.artifacts.list({ session, task_id: taskId });
+    if (all.length === 0)
+        failed.push({ chart_ref: '(task)', reason: `本会话该 task_id 没有可登记的图表：${taskId}` });
+    const selected = all.slice(0, MAX_CHARTS_PER_TURN);
+    if (all.length > MAX_CHARTS_PER_TURN) {
+        failed.push({ chart_ref: '(task)', reason: `该 task_id 有 ${all.length} 张图，本轮最多登记 ${MAX_CHARTS_PER_TURN} 张；其余未展示` });
+    }
+    return { selected, failed };
+}
+export function registerPresentChartsTool(ctx, input) {
+    const tools = ctx.get('tools');
+    if (!tools)
+        return;
+    const definition = {
+        name: 'present_charts',
+        description: '把本会话已生成的图表登记为**最终答复的交付物**（官方 deliverables/presented）：用户会在本轮答复末尾的「本轮文件改动 / 交付」行看到卡片，点开即渲染自包含 chart.html。'
+            + '**只由主 Agent 在写最终答复前调用一次**：参数是 data_junior 回传的 chart_refs（一次全部传入，最多 8 个）；refs 已丢失时改传 task_id 登记该任务的全部图表；调用后立刻写最终答复。'
+            + '不要在过程轮 / 等待行前调用，不要分批重复调用；不要传文件路径或 HTML（路径由宿主解析）。'
+            + '不调用本工具，图表不会出现在对话里。',
+        parameters,
+        async execute(args, exec) {
+            const session = callerSession(exec);
+            const refs = normalizeRefs(args.chart_refs);
+            const taskId = normalizeTaskId(args.task_id);
+            if (refs.length === 0 && taskId === undefined) {
+                throw new Error('present_charts 需要 chart_refs 或 task_id：两者都不给就无法确定要登记哪几张图');
+            }
+            const publisher = input.chartEvents();
+            if (publisher === undefined) {
+                throw new Error('图表交付通道不可用（sessions / sessionProjections 解析不到）：图表已落盘，可在 workspace 打开 chart.html');
+            }
+            const { selected, failed } = selectArtifacts(input, session, refs, taskId);
+            const receipt = { presented: [], failed };
+            for (const artifact of selected) {
+                const accepted = publisher.publish({
+                    ownerSessionId: session.id,
+                    chart_id: artifact.chart_id,
+                    title: artifact.title,
+                    html_path: artifact.html_path,
+                });
+                if (accepted)
+                    receipt.presented.push({ chart_ref: artifact.chart_ref, title: artifact.title });
+                else
+                    receipt.failed.push({ chart_ref: artifact.chart_ref, reason: `本轮登记已达 ${MAX_CHARTS_PER_TURN} 张上限或回合已关闭，未写入交付行` });
+            }
+            return receipt;
+        },
+        output: {
+            schema: receiptSchema,
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+        },
+    };
+    ctx.effect(() => tools.register(definition), 'capital-generation.tool(present_charts)');
+}

package/lib/chart/runtime.d.ts

@@ -1,20 +1,7 @@
 /**
- * 浏览器侧渲染运行时 —— 以**源码字符串**形式存在，而不是一个模块。
- *
- * 为什么是字符串：同一段渲染代码有两个宿主，二者都不能 pre-built 共用同一份模块——
- *  1. **自包含 HTML 产物**（本步就有）：内联进 `<script>`，离线双击可开；
- *  2. **对话流内嵌视图**（Step 3）：DSH 客户端 bundle 里再包一次。
- * 写成字符串可以保证两边**逐字节同源**，不会出现"文件里对、页面上错"。
- * 代价是这里没有类型检查，所以 test/chart-runtime.test.mjs 会用 `new Function`
- * 做一次语法与 API 形状校验，把笔误挡在测试里而不是浏览器里。
- *
- * 约束：这段源码里**不能**出现反引号或 `${`（它本身在 TS 模板字符串里）。
- * 依赖：DOM，以及**由调用方传入**的图表库对象（自包含 HTML 传 UMD 全局，Step 3 客户端传
- * ESM import）。刻意不读、也不回退到 `globalThis.LightweightCharts`：那条全局正是与其它
- * 插件带的同库不同版本互相覆盖的来源（见内部设计文档 docs/design/chart-visualization.md §9 风险表）。
- * 形态：IIFE **返回** `{ render, version }`，由各宿主自行捕获（HTML 用 `var __capitalChart =`，
- * 客户端 bundle 存为模块局部），**不往任何全局挂载**。
- * 主题：只读 CSS 变量 `--dsw-*`（见 docs/reference/dsh-surface-ledger.md L7），
- * 不调 DSH 的 theme 服务；自包含 HTML 自己定义同一批变量，因此两边渲染完全一致。
+ * Browser render runtime, kept as source text: the same bytes are inlined into standalone HTML
+ * and re-packaged in the client bundle. Must contain no backtick or `${`, and must never fall
+ * back to `globalThis.LightweightCharts` — another plugin's copy could silently win. The IIFE
+ * returns `{ render, version }`; nothing is attached to globals.
  */
-export declare const CHART_RUNTIME_SOURCE = "\n(function () {\n  'use strict'\n\n  var FALLBACK = {\n    '--dsw-alias-bg-base': '#ffffff',\n    '--dsw-alias-border-l1': 'rgba(0, 0, 0, 0.10)',\n    '--dsw-alias-label-primary': '#1f2328',\n    '--dsw-alias-label-secondary': '#6b7280',\n    '--dsw-alias-brand-primary': '#2563eb',\n    '--dsw-alias-state-error-primary': '#d94a3d',\n    '--dsw-alias-state-success-primary': '#2f9e44'\n  }\n\n  // \u4E3B\u9898 token \u4E0D\u4E00\u5B9A\u662F\u5341\u516D\u8FDB\u5236\uFF08\u4E5F\u53EF\u80FD\u662F rgb/rgba \u6216\u81EA\u5B9A\u4E49 CSS \u8272\u503C\uFF09\u3002\u53EA\u6709\u786E\u8BA4\u662F\n  // \u5341\u516D\u8FDB\u5236\u65F6\u624D\u8FFD\u52A0 alpha\uFF1B\u5176\u4F59\u683C\u5F0F\u8F6C\u6362\u6210 rgba\uFF0C\u8F6C\u6362\u4E0D\u4E86\u5C31\u9000\u56DE\u539F\u8272\uFF0C\u7EDD\u4E0D\u62FC\u51FA\u975E\u6CD5 CSS\u3002\n  function withAlpha(color, alpha) {\n    var text = String(color || '').trim()\n    var hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text)\n    if (hex) {\n      var expanded = hex[1].length === 3\n        ? '#' + hex[1].split('').map(function (part) { return part + part }).join('')\n        : text\n      return expanded + Math.round(alpha * 255).toString(16).padStart(2, '0')\n    }\n    var rgb = /^rgba?\\(\\s*([^)]*)\\)$/i.exec(text)\n    if (rgb) {\n      var parts = rgb[1].split(/[,\\s/]+/).filter(Boolean)\n      if (parts.length >= 3 && parts.slice(0, 3).every(function (part) { return /^[-+]?\\d*\\.?\\d+%?$/.test(part) })) {\n        return 'rgba(' + parts.slice(0, 3).join(', ') + ', ' + alpha + ')'\n      }\n    }\n    return text\n  }\n\n  // \u591A\u5E8F\u5217\u914D\u8272\uFF1A\u7B2C\u4E00\u6761\u7528\u4E3B\u9898\u54C1\u724C\u8272\uFF0C\u5176\u4F59\u7528\u56FA\u5B9A\u8272\u677F\uFF08\u4FDD\u8BC1\u540C\u4E00\u6761\u5E8F\u5217\u5728\u4E0D\u540C\u56FE\u91CC\u989C\u8272\u4E00\u81F4\uFF09\u3002\n  var PALETTE = ['#f59e0b', '#10b981', '#8b5cf6', '#0ea5e9', '#ec4899']\n\n  function readToken(name) {\n    try {\n      var value = getComputedStyle(document.documentElement).getPropertyValue(name)\n      if (value && value.trim().length > 0) return value.trim()\n    } catch (error) {\n      /* \u975E\u6D4F\u89C8\u5668\u73AF\u5883\u6216\u53D6\u4E0D\u5230\u6837\u5F0F\u65F6\u9000\u56DE\u9ED8\u8BA4\u8272 */\n    }\n    return FALLBACK[name]\n  }\n\n  function resolveColors() {\n    return {\n      bg: readToken('--dsw-alias-bg-base'),\n      grid: readToken('--dsw-alias-border-l1'),\n      text: readToken('--dsw-alias-label-secondary'),\n      strong: readToken('--dsw-alias-label-primary'),\n      brand: readToken('--dsw-alias-brand-primary'),\n      up: readToken('--dsw-alias-state-error-primary'),\n      down: readToken('--dsw-alias-state-success-primary')\n    }\n  }\n\n  function showError(container, message) {\n    container.textContent = ''\n    var box = document.createElement('div')\n    box.setAttribute('data-chart-error', '1')\n    box.style.cssText = 'padding:12px;border:0.5px solid ' + readToken('--dsw-alias-border-l1') + ';border-radius:8px;color:' + readToken('--dsw-alias-label-secondary') + ';font-size:13px;line-height:1.6'\n    box.textContent = message\n    container.appendChild(box)\n  }\n\n  function applyIndexLabels(chart, labels) {\n    function format(time) {\n      var key = String(time)\n      return Object.prototype.hasOwnProperty.call(labels, key) ? labels[key] : key\n    }\n    // \u8F74\u7684\u523B\u5EA6\u6587\u6848\u5F52 timeScale.tickMarkFormatter \u7BA1\uFF0C\u5341\u5B57\u7EBF/\u63D0\u793A\u5F52 localization.timeFormatter\uFF1B\n    // \u5206\u7C7B\u8F74\u4E24\u8FB9\u90FD\u8981\u6362\u6389\uFF0C\u5426\u5219\u6807\u5C3A\u4E0A\u8FD8\u662F 2000 \u5E74\u90A3\u79CD\u5408\u6210\u65E5\u671F\u3002\n    chart.applyOptions({\n      localization: { timeFormatter: format },\n      timeScale: { tickMarkFormatter: function (time) { return format(time) } }\n    })\n  }\n\n  /**\n   * \u6302\u6807\u8BB0\u70B9\u3002v5 \u628A markers \u4ECE series API \u79FB\u5230\u4E86 createSeriesMarkers(series, markers)\n   * \u8FD4\u56DE\u7684\u63D2\u4EF6\u5BF9\u8C61\u4E0A\uFF1B\u8FD9\u91CC\u540C\u65F6\u517C\u5BB9\u4E24\u79CD\u5F62\u72B6\uFF0C\u4E0A\u6E38\u518D\u52A8\u4E00\u6B21\u4E5F\u4E0D\u4F1A\u9759\u9ED8\u4E22\u6389\u6807\u8BB0\u3002\n   */\n  function attachMarkers(anchor, markers, LWC) {\n    if (typeof LWC.createSeriesMarkers === 'function') {\n      LWC.createSeriesMarkers(anchor, markers)\n      return true\n    }\n    if (anchor && typeof anchor.setMarkers === 'function') {\n      anchor.setMarkers(markers)\n      return true\n    }\n    return false\n  }\n\n  function volumePointColor(point, colors) {\n    if (point.direction === 'up') return colors.up\n    if (point.direction === 'down') return colors.down\n    return colors.brand\n  }\n\n  function seriesColor(index, colors) {\n    return index === 0 ? colors.brand : PALETTE[(index - 1) % PALETTE.length]\n  }\n\n  function appendLegend(container, payload, colors) {\n    var items = []\n    if (payload.ohlc && payload.ohlc.label) items.push({ label: payload.ohlc.label, color: colors.up })\n    if (Array.isArray(payload.series)) {\n      payload.series.forEach(function (item, index) {\n        if (item && item.label) items.push({ label: item.label, color: seriesColor(index, colors) })\n      })\n    }\n    if (payload.volume && payload.volume.label) items.push({ label: payload.volume.label, color: colors.brand })\n    if (items.length === 0) return\n\n    var legend = document.createElement('div')\n    legend.setAttribute('data-chart-legend', '1')\n    legend.style.cssText = 'position:absolute;z-index:2;top:8px;left:8px;right:8px;display:flex;flex-wrap:wrap;gap:4px 10px;align-items:center;pointer-events:none;color:' + colors.text + ';font-size:11px;line-height:16px'\n    items.forEach(function (item) {\n      var entry = document.createElement('span')\n      entry.style.cssText = 'display:inline-flex;align-items:center;gap:4px;padding:1px 5px;border-radius:4px;background:' + withAlpha(colors.bg, 0.8)\n      var swatch = document.createElement('span')\n      swatch.style.cssText = 'width:7px;height:7px;border-radius:50%;background:' + item.color + ';flex:none'\n      var label = document.createElement('span')\n      label.textContent = item.label\n      entry.appendChild(swatch)\n      entry.appendChild(label)\n      legend.appendChild(entry)\n    })\n    container.appendChild(legend)\n  }\n\n  function renderCapitalChart(container, payload, library) {\n    if (!container) throw new Error('renderCapitalChart: container is required')\n    if (!payload || typeof payload !== 'object') throw new Error('renderCapitalChart: payload is required')\n    // \u56FE\u8868\u5E93\u7531\u8C03\u7528\u65B9\u6CE8\u5165\uFF0C\u7EDD\u4E0D\u56DE\u9000\u5230\u9875\u9762\u5168\u5C40\uFF1A\u56DE\u9000\u4F1A\u8BA9\"\u53E6\u4E00\u4E2A\u63D2\u4EF6\u7684\u540C\u5E93\u7248\u672C\"\u6084\u6084\u751F\u6548\u3002\n    var LWC = library\n    if (!LWC || typeof LWC.createChart !== 'function') {\n      showError(container, '\u56FE\u8868\u5E93\u672A\u52A0\u8F7D\uFF08\u8C03\u7528\u65B9\u672A\u63D0\u4F9B LightweightCharts\uFF09\u3002')\n      return null\n    }\n\n    var colors = resolveColors()\n    container.textContent = ''\n    if (container.style) container.style.position = 'relative'\n    container.setAttribute('data-chart-id', String(payload.chart_id || ''))\n    container.setAttribute('data-chart-kind', String(payload.kind || ''))\n\n    var chart = LWC.createChart(container, {\n      autoSize: true,\n      // attributionLogo \u4FDD\u6301\u5F00\u542F\uFF1A\u8FD9\u6EE1\u8DB3 Apache-2.0 \u5F52\u5C5E\u8981\u6C42\uFF08\u89C1 vendor/lightweight-charts/VERSION.json\uFF09\u3002\n      layout: { background: { color: 'transparent' }, textColor: colors.text, fontFamily: 'inherit', attributionLogo: true },\n      grid: { vertLines: { color: colors.grid }, horzLines: { color: colors.grid } },\n      rightPriceScale: { borderColor: colors.grid, entireTextOnly: true },\n      timeScale: { borderColor: colors.grid, rightOffset: 2, barSpacing: 6, minBarSpacing: 0.5 },\n      crosshair: { mode: LWC.CrosshairMode ? LWC.CrosshairMode.Normal : 0 },\n      localization: { locale: 'zh-CN' }\n    })\n\n    if (payload.axis === 'index' && payload.labels) applyIndexLabels(chart, payload.labels)\n\n    var anchor = null\n\n    if (payload.ohlc && Array.isArray(payload.ohlc.data) && payload.ohlc.data.length > 0) {\n      // kind=bar \u7528 BarSeries\uFF08OHLC \u67F1\uFF09\uFF0C\u5176\u4F59 OHLC \u56FE\u5F62\u7528 CandlestickSeries\u3002\n      // \u4E24\u8005\u7684\u6570\u636E\u5951\u7EA6\u76F8\u540C\uFF08\u90FD\u7EE7\u627F OhlcData\uFF09\uFF0C\u533A\u522B\u53EA\u5728\u6E32\u67D3\u6837\u5F0F\u3002\n      var isOhlcBar = payload.kind === 'bar'\n      var candles = chart.addSeries(isOhlcBar ? LWC.BarSeries : LWC.CandlestickSeries, {\n        upColor: colors.up,\n        downColor: colors.down,\n        borderUpColor: colors.up,\n        borderDownColor: colors.down,\n        wickUpColor: colors.up,\n        wickDownColor: colors.down\n      })\n      candles.setData(payload.ohlc.data)\n      anchor = candles\n    }\n\n    if (Array.isArray(payload.series)) {\n      for (var index = 0; index < payload.series.length; index += 1) {\n        var item = payload.series[index]\n        if (!item || !Array.isArray(item.data) || item.data.length === 0) continue\n        var color = seriesColor(index, colors)\n        var options = { title: item.label || '', priceLineVisible: false, lastValueVisible: true }\n        var series = null\n        if (item.type === 'area') {\n          options.lineColor = color\n          options.topColor = withAlpha(color, 0.2)\n          options.bottomColor = withAlpha(color, 0.02)\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.AreaSeries, options)\n        } else if (item.type === 'column') {\n          // \u5355\u503C\u67F1\uFF1AHistogramSeries \u5403 SingleValueData\uFF08{time, value}\uFF09\u3002\n          // \u6CE8\u610F\u4E0D\u80FD\u7528 BarSeries \u2014\u2014 \u5B83\u8981 OhlcData\uFF0C\u585E\u5355\u503C\u53EA\u4F1A\u753B\u51FA\u7A7A\u56FE\u3002\n          options.color = color\n          options.base = 0\n          series = chart.addSeries(LWC.HistogramSeries, options)\n        } else {\n          options.color = color\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.LineSeries, options)\n        }\n        series.setData(item.data)\n        if (anchor === null) anchor = series\n      }\n    }\n\n    if (payload.volume && Array.isArray(payload.volume.data) && payload.volume.data.length > 0) {\n      var volume = chart.addSeries(LWC.HistogramSeries, {\n        title: payload.volume.label || '',\n        priceFormat: { type: 'volume' },\n        priceLineVisible: false,\n        lastValueVisible: false\n      }, 1)\n      volume.setData(payload.volume.data.map(function (point) {\n        return { time: point.time, value: point.value, color: volumePointColor(point, colors) }\n      }))\n    }\n\n    if (anchor === null) {\n      showError(container, '\u8FD9\u5F20\u56FE\u6CA1\u6709\u53EF\u6E32\u67D3\u7684\u5E8F\u5217\uFF08payload \u91CC\u65E2\u6CA1\u6709 ohlc \u4E5F\u6CA1\u6709 series\uFF09\u3002')\n      return chart\n    }\n\n    if (Array.isArray(payload.markers) && payload.markers.length > 0) {\n      attachMarkers(anchor, payload.markers.map(function (marker) {\n        return { time: marker.time, position: marker.position, text: marker.text, color: colors.strong, shape: 'circle' }\n      }), LWC)\n    }\n\n    appendLegend(container, payload, colors)\n\n    // \u4E3B\u56FE\u4E0E\u6210\u4EA4\u91CF\u526F\u56FE\u7684\u9AD8\u5EA6\u6BD4 3:1\uFF1B\u53EA\u6709\u4E00\u4E2A pane \u65F6 panes()[1] \u4E0D\u5B58\u5728\u3002\n    var panes = typeof chart.panes === 'function' ? chart.panes() : []\n    if (panes.length > 1) {\n      if (typeof panes[0].setStretchFactor === 'function') panes[0].setStretchFactor(3)\n      if (typeof panes[1].setStretchFactor === 'function') panes[1].setStretchFactor(1)\n    }\n\n    chart.timeScale().fitContent()\n    return chart\n  }\n\n  return { render: renderCapitalChart, version: 1 }\n})()\n";
+export declare const CHART_RUNTIME_SOURCE = "\n(function () {\n  'use strict'\n\n  var FALLBACK = {\n    '--dsw-alias-bg-base': '#ffffff',\n    '--dsw-alias-border-l1': 'rgba(0, 0, 0, 0.10)',\n    '--dsw-alias-label-primary': '#1f2328',\n    '--dsw-alias-label-secondary': '#6b7280',\n    '--dsw-alias-brand-primary': '#2563eb',\n    '--dsw-alias-state-error-primary': '#d94a3d',\n    '--dsw-alias-state-success-primary': '#2f9e44'\n  }\n\n  // Hex colors receive alpha; other formats convert to rgba or stay unchanged, never emit invalid CSS.\n  function withAlpha(color, alpha) {\n    var text = String(color || '').trim()\n    var hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text)\n    if (hex) {\n      var expanded = hex[1].length === 3\n        ? '#' + hex[1].split('').map(function (part) { return part + part }).join('')\n        : text\n      return expanded + Math.round(alpha * 255).toString(16).padStart(2, '0')\n    }\n    var rgb = /^rgba?\\(\\s*([^)]*)\\)$/i.exec(text)\n    if (rgb) {\n      var parts = rgb[1].split(/[,\\s/]+/).filter(Boolean)\n      if (parts.length >= 3 && parts.slice(0, 3).every(function (part) { return /^[-+]?\\d*\\.?\\d+%?$/.test(part) })) {\n        return 'rgba(' + parts.slice(0, 3).join(', ') + ', ' + alpha + ')'\n      }\n    }\n    return text\n  }\n\n  // First series uses brand color; later series use a stable palette so one symbol keeps its color.\n  var PALETTE = ['#f59e0b', '#10b981', '#8b5cf6', '#0ea5e9', '#ec4899']\n\n  function readToken(name) {\n    try {\n      var value = getComputedStyle(document.documentElement).getPropertyValue(name)\n      if (value && value.trim().length > 0) return value.trim()\n    } catch (error) {\n      /* Non-browser or unavailable styles fall back to defaults. */\n    }\n    return FALLBACK[name]\n  }\n\n  function resolveColors() {\n    return {\n      bg: readToken('--dsw-alias-bg-base'),\n      grid: readToken('--dsw-alias-border-l1'),\n      text: readToken('--dsw-alias-label-secondary'),\n      strong: readToken('--dsw-alias-label-primary'),\n      brand: readToken('--dsw-alias-brand-primary'),\n      up: readToken('--dsw-alias-state-error-primary'),\n      down: readToken('--dsw-alias-state-success-primary')\n    }\n  }\n\n  function showError(container, message) {\n    container.textContent = ''\n    var box = document.createElement('div')\n    box.setAttribute('data-chart-error', '1')\n    box.style.cssText = 'padding:12px;border:0.5px solid ' + readToken('--dsw-alias-border-l1') + ';border-radius:8px;color:' + readToken('--dsw-alias-label-secondary') + ';font-size:13px;line-height:1.6'\n    box.textContent = message\n    container.appendChild(box)\n  }\n\n  function applyIndexLabels(chart, labels) {\n    function format(time) {\n      var key = String(time)\n      return Object.prototype.hasOwnProperty.call(labels, key) ? labels[key] : key\n    }\n    // Replace both tick and crosshair formatters for category axes or synthetic dates leak through.\n    chart.applyOptions({\n      localization: { timeFormatter: format },\n      timeScale: { tickMarkFormatter: function (time) { return format(time) } }\n    })\n  }\n\n  /** Support both v5 plugin markers and the older series API so markers never disappear silently. */\n  function attachMarkers(anchor, markers, LWC) {\n    if (typeof LWC.createSeriesMarkers === 'function') {\n      LWC.createSeriesMarkers(anchor, markers)\n      return true\n    }\n    if (anchor && typeof anchor.setMarkers === 'function') {\n      anchor.setMarkers(markers)\n      return true\n    }\n    return false\n  }\n\n  function volumePointColor(point, colors) {\n    if (point.direction === 'up') return colors.up\n    if (point.direction === 'down') return colors.down\n    return colors.brand\n  }\n\n  function seriesColor(index, colors) {\n    return index === 0 ? colors.brand : PALETTE[(index - 1) % PALETTE.length]\n  }\n\n  function appendLegend(container, payload, colors) {\n    var items = []\n    if (payload.ohlc && payload.ohlc.label) items.push({ label: payload.ohlc.label, color: colors.up })\n    if (Array.isArray(payload.series)) {\n      payload.series.forEach(function (item, index) {\n        if (item && item.label) items.push({ label: item.label, color: seriesColor(index, colors) })\n      })\n    }\n    if (payload.volume && payload.volume.label) items.push({ label: payload.volume.label, color: colors.brand })\n    if (items.length === 0) return\n\n    var legend = document.createElement('div')\n    legend.setAttribute('data-chart-legend', '1')\n    legend.style.cssText = 'position:absolute;z-index:2;top:8px;left:8px;right:8px;display:flex;flex-wrap:wrap;gap:4px 10px;align-items:center;pointer-events:none;color:' + colors.text + ';font-size:11px;line-height:16px'\n    items.forEach(function (item) {\n      var entry = document.createElement('span')\n      entry.style.cssText = 'display:inline-flex;align-items:center;gap:4px;padding:1px 5px;border-radius:4px;background:' + withAlpha(colors.bg, 0.8)\n      var swatch = document.createElement('span')\n      swatch.style.cssText = 'width:7px;height:7px;border-radius:50%;background:' + item.color + ';flex:none'\n      var label = document.createElement('span')\n      label.textContent = item.label\n      entry.appendChild(swatch)\n      entry.appendChild(label)\n      legend.appendChild(entry)\n    })\n    container.appendChild(legend)\n  }\n\n  function renderCapitalChart(container, payload, library) {\n    if (!container) throw new Error('renderCapitalChart: container is required')\n    if (!payload || typeof payload !== 'object') throw new Error('renderCapitalChart: payload is required')\n    // Use the injected library; never fall back to a global copy owned by another plugin.\n    var LWC = library\n    if (!LWC || typeof LWC.createChart !== 'function') {\n      showError(container, '\u56FE\u8868\u5E93\u672A\u52A0\u8F7D\uFF08\u8C03\u7528\u65B9\u672A\u63D0\u4F9B LightweightCharts\uFF09\u3002')\n      return null\n    }\n\n    var colors = resolveColors()\n    container.textContent = ''\n    if (container.style) container.style.position = 'relative'\n    container.setAttribute('data-chart-id', String(payload.chart_id || ''))\n    container.setAttribute('data-chart-kind', String(payload.kind || ''))\n\n    var chart = LWC.createChart(container, {\n      autoSize: true,\n      // attributionLogo stays enabled for Apache-2.0 attribution.\n      layout: { background: { color: 'transparent' }, textColor: colors.text, fontFamily: 'inherit', attributionLogo: true },\n      grid: { vertLines: { color: colors.grid }, horzLines: { color: colors.grid } },\n      rightPriceScale: { borderColor: colors.grid, entireTextOnly: true },\n      timeScale: { borderColor: colors.grid, rightOffset: 2, barSpacing: 6, minBarSpacing: 0.5 },\n      crosshair: { mode: LWC.CrosshairMode ? LWC.CrosshairMode.Normal : 0 },\n      localization: { locale: 'zh-CN' }\n    })\n\n    if (payload.axis === 'index' && payload.labels) applyIndexLabels(chart, payload.labels)\n\n    var anchor = null\n\n    if (payload.ohlc && Array.isArray(payload.ohlc.data) && payload.ohlc.data.length > 0) {\n      // kind=bar uses BarSeries; other OHLC kinds use CandlestickSeries with the same data contract.\n      var isOhlcBar = payload.kind === 'bar'\n      var candles = chart.addSeries(isOhlcBar ? LWC.BarSeries : LWC.CandlestickSeries, {\n        upColor: colors.up,\n        downColor: colors.down,\n        borderUpColor: colors.up,\n        borderDownColor: colors.down,\n        wickUpColor: colors.up,\n        wickDownColor: colors.down\n      })\n      candles.setData(payload.ohlc.data)\n      anchor = candles\n    }\n\n    if (Array.isArray(payload.series)) {\n      for (var index = 0; index < payload.series.length; index += 1) {\n        var item = payload.series[index]\n        if (!item || !Array.isArray(item.data) || item.data.length === 0) continue\n        var color = seriesColor(index, colors)\n        var options = { title: item.label || '', priceLineVisible: false, lastValueVisible: true }\n        var series = null\n        if (item.type === 'area') {\n          options.lineColor = color\n          options.topColor = withAlpha(color, 0.2)\n          options.bottomColor = withAlpha(color, 0.02)\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.AreaSeries, options)\n        } else if (item.type === 'column') {\n          // Single-value histograms need HistogramSeries; BarSeries would render an empty chart.\n          options.color = color\n          options.base = 0\n          series = chart.addSeries(LWC.HistogramSeries, options)\n        } else {\n          options.color = color\n          options.lineWidth = 2\n          series = chart.addSeries(LWC.LineSeries, options)\n        }\n        series.setData(item.data)\n        if (anchor === null) anchor = series\n      }\n    }\n\n    if (payload.volume && Array.isArray(payload.volume.data) && payload.volume.data.length > 0) {\n      var volume = chart.addSeries(LWC.HistogramSeries, {\n        title: payload.volume.label || '',\n        priceFormat: { type: 'volume' },\n        priceLineVisible: false,\n        lastValueVisible: false\n      }, 1)\n      volume.setData(payload.volume.data.map(function (point) {\n        return { time: point.time, value: point.value, color: volumePointColor(point, colors) }\n      }))\n    }\n\n    if (anchor === null) {\n      showError(container, '\u8FD9\u5F20\u56FE\u6CA1\u6709\u53EF\u6E32\u67D3\u7684\u5E8F\u5217\uFF08payload \u91CC\u65E2\u6CA1\u6709 ohlc \u4E5F\u6CA1\u6709 series\uFF09\u3002')\n      return chart\n    }\n\n    if (Array.isArray(payload.markers) && payload.markers.length > 0) {\n      attachMarkers(anchor, payload.markers.map(function (marker) {\n        return { time: marker.time, position: marker.position, text: marker.text, color: colors.strong, shape: 'circle' }\n      }), LWC)\n    }\n\n    appendLegend(container, payload, colors)\n\n    // Main/volume panes use a 3:1 ratio; a single pane has no second pane object.\n    var panes = typeof chart.panes === 'function' ? chart.panes() : []\n    if (panes.length > 1) {\n      if (typeof panes[0].setStretchFactor === 'function') panes[0].setStretchFactor(3)\n      if (typeof panes[1].setStretchFactor === 'function') panes[1].setStretchFactor(1)\n    }\n\n    chart.timeScale().fitContent()\n    return chart\n  }\n\n  return { render: renderCapitalChart, version: 1 }\n})()\n";

package/lib/chart/runtime.js

@@ -1,21 +1,8 @@
 /**
- * 浏览器侧渲染运行时 —— 以**源码字符串**形式存在，而不是一个模块。
- *
- * 为什么是字符串：同一段渲染代码有两个宿主，二者都不能 pre-built 共用同一份模块——
- *  1. **自包含 HTML 产物**（本步就有）：内联进 `<script>`，离线双击可开；
- *  2. **对话流内嵌视图**（Step 3）：DSH 客户端 bundle 里再包一次。
- * 写成字符串可以保证两边**逐字节同源**，不会出现"文件里对、页面上错"。
- * 代价是这里没有类型检查，所以 test/chart-runtime.test.mjs 会用 `new Function`
- * 做一次语法与 API 形状校验，把笔误挡在测试里而不是浏览器里。
- *
- * 约束：这段源码里**不能**出现反引号或 `${`（它本身在 TS 模板字符串里）。
- * 依赖：DOM，以及**由调用方传入**的图表库对象（自包含 HTML 传 UMD 全局，Step 3 客户端传
- * ESM import）。刻意不读、也不回退到 `globalThis.LightweightCharts`：那条全局正是与其它
- * 插件带的同库不同版本互相覆盖的来源（见内部设计文档 docs/design/chart-visualization.md §9 风险表）。
- * 形态：IIFE **返回** `{ render, version }`，由各宿主自行捕获（HTML 用 `var __capitalChart =`，
- * 客户端 bundle 存为模块局部），**不往任何全局挂载**。
- * 主题：只读 CSS 变量 `--dsw-*`（见 docs/reference/dsh-surface-ledger.md L7），
- * 不调 DSH 的 theme 服务；自包含 HTML 自己定义同一批变量，因此两边渲染完全一致。
+ * Browser render runtime, kept as source text: the same bytes are inlined into standalone HTML
+ * and re-packaged in the client bundle. Must contain no backtick or `${`, and must never fall
+ * back to `globalThis.LightweightCharts` — another plugin's copy could silently win. The IIFE
+ * returns `{ render, version }`; nothing is attached to globals.
  */
 export const CHART_RUNTIME_SOURCE = `
 (function () {
@@ -31,8 +18,7 @@ export const CHART_RUNTIME_SOURCE = `
     '--dsw-alias-state-success-primary': '#2f9e44'
   }
 
-  // 主题 token 不一定是十六进制（也可能是 rgb/rgba 或自定义 CSS 色值）。只有确认是
-  // 十六进制时才追加 alpha；其余格式转换成 rgba，转换不了就退回原色，绝不拼出非法 CSS。
+  // Hex colors receive alpha; other formats convert to rgba or stay unchanged, never emit invalid CSS.
   function withAlpha(color, alpha) {
     var text = String(color || '').trim()
     var hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(text)
@@ -52,7 +38,7 @@ export const CHART_RUNTIME_SOURCE = `
     return text
   }
 
-  // 多序列配色：第一条用主题品牌色，其余用固定色板（保证同一条序列在不同图里颜色一致）。
+  // First series uses brand color; later series use a stable palette so one symbol keeps its color.
   var PALETTE = ['#f59e0b', '#10b981', '#8b5cf6', '#0ea5e9', '#ec4899']
 
   function readToken(name) {
@@ -60,7 +46,7 @@ export const CHART_RUNTIME_SOURCE = `
       var value = getComputedStyle(document.documentElement).getPropertyValue(name)
       if (value && value.trim().length > 0) return value.trim()
     } catch (error) {
-      /* 非浏览器环境或取不到样式时退回默认色 */
+      /* Non-browser or unavailable styles fall back to defaults. */
     }
     return FALLBACK[name]
   }
@@ -91,18 +77,14 @@ export const CHART_RUNTIME_SOURCE = `
       var key = String(time)
       return Object.prototype.hasOwnProperty.call(labels, key) ? labels[key] : key
     }
-    // 轴的刻度文案归 timeScale.tickMarkFormatter 管，十字线/提示归 localization.timeFormatter；
-    // 分类轴两边都要换掉，否则标尺上还是 2000 年那种合成日期。
+    // Replace both tick and crosshair formatters for category axes or synthetic dates leak through.
     chart.applyOptions({
       localization: { timeFormatter: format },
       timeScale: { tickMarkFormatter: function (time) { return format(time) } }
     })
   }
 
-  /**
-   * 挂标记点。v5 把 markers 从 series API 移到了 createSeriesMarkers(series, markers)
-   * 返回的插件对象上；这里同时兼容两种形状，上游再动一次也不会静默丢掉标记。
-   */
+  /** Support both v5 plugin markers and the older series API so markers never disappear silently. */
   function attachMarkers(anchor, markers, LWC) {
     if (typeof LWC.createSeriesMarkers === 'function') {
       LWC.createSeriesMarkers(anchor, markers)
@@ -156,7 +138,7 @@ export const CHART_RUNTIME_SOURCE = `
   function renderCapitalChart(container, payload, library) {
     if (!container) throw new Error('renderCapitalChart: container is required')
     if (!payload || typeof payload !== 'object') throw new Error('renderCapitalChart: payload is required')
-    // 图表库由调用方注入，绝不回退到页面全局：回退会让"另一个插件的同库版本"悄悄生效。
+    // Use the injected library; never fall back to a global copy owned by another plugin.
     var LWC = library
     if (!LWC || typeof LWC.createChart !== 'function') {
       showError(container, '图表库未加载（调用方未提供 LightweightCharts）。')
@@ -171,7 +153,7 @@ export const CHART_RUNTIME_SOURCE = `
 
     var chart = LWC.createChart(container, {
       autoSize: true,
-      // attributionLogo 保持开启：这满足 Apache-2.0 归属要求（见 vendor/lightweight-charts/VERSION.json）。
+      // attributionLogo stays enabled for Apache-2.0 attribution.
       layout: { background: { color: 'transparent' }, textColor: colors.text, fontFamily: 'inherit', attributionLogo: true },
       grid: { vertLines: { color: colors.grid }, horzLines: { color: colors.grid } },
       rightPriceScale: { borderColor: colors.grid, entireTextOnly: true },
@@ -185,8 +167,7 @@ export const CHART_RUNTIME_SOURCE = `
     var anchor = null
 
     if (payload.ohlc && Array.isArray(payload.ohlc.data) && payload.ohlc.data.length > 0) {
-      // kind=bar 用 BarSeries（OHLC 柱），其余 OHLC 图形用 CandlestickSeries。
-      // 两者的数据契约相同（都继承 OhlcData），区别只在渲染样式。
+      // kind=bar uses BarSeries; other OHLC kinds use CandlestickSeries with the same data contract.
       var isOhlcBar = payload.kind === 'bar'
       var candles = chart.addSeries(isOhlcBar ? LWC.BarSeries : LWC.CandlestickSeries, {
         upColor: colors.up,
@@ -214,8 +195,7 @@ export const CHART_RUNTIME_SOURCE = `
           options.lineWidth = 2
           series = chart.addSeries(LWC.AreaSeries, options)
         } else if (item.type === 'column') {
-          // 单值柱：HistogramSeries 吃 SingleValueData（{time, value}）。
-          // 注意不能用 BarSeries —— 它要 OhlcData，塞单值只会画出空图。
+          // Single-value histograms need HistogramSeries; BarSeries would render an empty chart.
           options.color = color
           options.base = 0
           series = chart.addSeries(LWC.HistogramSeries, options)
@@ -254,7 +234,7 @@ export const CHART_RUNTIME_SOURCE = `
 
     appendLegend(container, payload, colors)
 
-    // 主图与成交量副图的高度比 3:1；只有一个 pane 时 panes()[1] 不存在。
+    // Main/volume panes use a 3:1 ratio; a single pane has no second pane object.
     var panes = typeof chart.panes === 'function' ? chart.panes() : []
     if (panes.length > 1) {
       if (typeof panes[0].setStretchFactor === 'function') panes[0].setStretchFactor(3)

package/lib/chart/series.d.ts

@@ -1,7 +1,7 @@
 import type { ChartKind, ChartSeriesType, MarkerPosition, NormalizedChartSpec } from './spec.js';
-/** 单张图保留的最大点数（下采样后）。轻量图表在这个量级仍然流畅，且载荷只有几十 KB。 */
+/** Post-downsample point cap; keeps the payload tens of KB and rendering fluid. */
 export declare const MAX_CHART_POINTS = 2000;
-/** 字段候选清单最多回报多少个（错误路径本身也不能变成上下文炸弹）。 */
+/** Error-path hints are capped too; an error must not become a context bomb. */
 export declare const MAX_FIELD_HINTS = 15;
 export interface ChartSeriesPayload {
     id: string;
@@ -43,7 +43,7 @@ export interface ChartPayload {
         text: string;
         position: MarkerPosition;
     }>;
-    /** 分类轴专用：合成时间 → 原始标签，运行时用它做刻度与十字线文案。 */
+    /** Category axis: synthetic time → original label for ticks and crosshair. */
     labels?: Record<string, string>;
     meta: {
         points: number;
@@ -60,31 +60,24 @@ export interface ChartPayload {
     };
 }
 /**
- * 从解析好的 JSON 里取出行数组。
- *
- * 真实数据源的同花顺返回常常是 envelope（行数组在 `item` / `data` / `stock_items` …），
- * 所以这里不能只认顶层数组；但也不能乱猜——猜错会让用户看到一张空图或错图。
- * 策略：顶层数组直接用；否则在候选键里找；候选都没有时列出**全部**数组型顶层键让模型
- * 自己指定路径，而不是静默取第一个。
+ * Sources often wrap rows in an envelope (item/data/stock_items); prefer known keys, and list
+ * candidates instead of silently guessing when several arrays match.
  */
 export declare function extractRows(value: unknown): {
     rows: unknown[];
     shape: string;
 };
 interface ParsedTime {
-    /** 交给图表库的值：'YYYY-MM-DD' 字符串（业务日）或 UTC 秒数。 */
+    /** Value handed to the library: 'YYYY-MM-DD' business day, or UTC seconds. */
     display: string | number;
-    /** 用于排序/过滤/对齐的比较键（UTC 秒）。 */
+    /** Comparison key (UTC seconds) for sort/filter/alignment. */
     seconds: number;
-    /** 该值是否来自"纯日期"字符串（决定整张图是否用业务日显示）。 */
+    /** True when the value came from a date-only string; decides business-day rendering. */
     dateOnly: boolean;
 }
 /**
- * 时间值解析。规则必须**确定**（同一份数据在任何机器上得到同一张图）：
- *  - 纯日期 `YYYY-MM-DD` → 业务日字符串，交给图表库按业务日显示（不做时区换算，避免差一天）；
- *  - `YYYY-MM-DD HH:mm[:ss]` 无时区 → 按 UTC 解释（显式规则，不依赖宿主本地时区）；
- *  - 数字/纯数字字符串 → epoch；`>= 1e11` 视为毫秒，否则视为秒；
- *  - 其余字符串 → `Date.parse`；失败即视为该行没有时间。
+ * Deterministic across machines: date-only stays a business-day string (no TZ shift), naive
+ * datetime is UTC, numbers >= 1e11 are epoch ms, unparseable means the row has no time.
  */
 export declare function parseTimeValue(value: unknown): ParsedTime | undefined;
 export interface BuildChartPayloadInput {

package/lib/chart/series.js

@@ -1,34 +1,28 @@
 /**
- * 把原始 rows 变成**有界、对齐、可渲染**的图表载荷。
- *
- * 边界（这是整个方案的核心不变量）：本模块的**输入**是原始 rows，**输出**是可视化载荷。
- * 输出会写进 workspace 产物并交给浏览器，永不进入模型上下文；工具只回一条小回执。
- * 因此这里可以放心读全量行，但必须保证输出有界（点数上限 + 字段数上限 + 标记数上限）。
+ * Turn raw rows into a bounded, aligned, renderable payload.
+ * Output goes to a workspace artifact and the browser, never into model context; input may be
+ * read in full, but the payload must stay bounded (points, series, fields, markers).
  */
 import { largestTriangleThreeBuckets } from './downsample.js';
 import { ChartError } from './errors.js';
 import { MAX_CHART_MARKERS, MAX_CHART_SERIES, OHLC_KINDS } from './spec.js';
-/** 单张图保留的最大点数（下采样后）。轻量图表在这个量级仍然流畅，且载荷只有几十 KB。 */
+/** Post-downsample point cap; keeps the payload tens of KB and rendering fluid. */
 export const MAX_CHART_POINTS = 2_000;
-/** 字段候选清单最多回报多少个（错误路径本身也不能变成上下文炸弹）。 */
+/** Error-path hints are capped too; an error must not become a context bomb. */
 export const MAX_FIELD_HINTS = 15;
-/** 判定"x 是时间列"的采样解析成功率阈值。 */
+/** Share of x values that must parse as time to keep a time axis. */
 const TIME_AXIS_THRESHOLD = 0.8;
-/** 分类轴的合成时间基准（UTC 秒）：1970 太容易被误认为真实时间，取 2000-01-01。 */
+/** Synthetic category-axis base (2000-01-01); 1970 reads as real data. */
 const INDEX_EPOCH_SECONDS = Date.UTC(2000, 0, 1) / 1000;
 const SECONDS_PER_DAY = 86_400;
-/** epoch 毫秒与秒的分界：>= 1e11 视为毫秒（1e11 秒 ≈ 公元 5138 年）。 */
+/** Values >= 1e11 are epoch ms (1e11 seconds is year 5138). */
 const MILLISECONDS_THRESHOLD = 1e11;
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 /**
- * 从解析好的 JSON 里取出行数组。
- *
- * 真实数据源的同花顺返回常常是 envelope（行数组在 `item` / `data` / `stock_items` …），
- * 所以这里不能只认顶层数组；但也不能乱猜——猜错会让用户看到一张空图或错图。
- * 策略：顶层数组直接用；否则在候选键里找；候选都没有时列出**全部**数组型顶层键让模型
- * 自己指定路径，而不是静默取第一个。
+ * Sources often wrap rows in an envelope (item/data/stock_items); prefer known keys, and list
+ * candidates instead of silently guessing when several arrays match.
  */
 export function extractRows(value) {
     if (Array.isArray(value))
@@ -50,7 +44,6 @@ export function extractRows(value) {
     }
     throw new ChartError('chart_no_rows', 'the JSON object contains no row array', { object_keys: Object.keys(value).slice(0, MAX_FIELD_HINTS) });
 }
-/** 字段候选清单：按出现顺序去重，最多 MAX_FIELD_HINTS 个。 */
 function collectFields(records) {
     const seen = [];
     const set = new Set();
@@ -66,12 +59,11 @@ function collectFields(records) {
     }
     return seen;
 }
+/** Hints live in the message so the model can self-correct even if details are dropped. */
 function assertFields(fields, available) {
     const missing = [...new Set(fields.filter((field) => field !== undefined))].filter((field) => !available.includes(field));
     if (missing.length === 0)
         return;
-    // 候选清单写进 message：模型看到的错误文本就是自愈所需的全部信息，
-    // 不依赖调用方是否把 details 透传出去。
     const hints = available.slice(0, MAX_FIELD_HINTS);
     const suffix = hints.length > 0 ? `; available fields: ${hints.join(', ')}${available.length > hints.length ? ` (共 ${available.length} 个，其余已省略)` : ''}` : '';
     throw new ChartError('chart_field_not_found', `field not found in the data: ${missing.join(', ')}${suffix}`, {
@@ -80,7 +72,7 @@ function assertFields(fields, available) {
         available_total: available.length,
     });
 }
-/** 数值读取：数字直接用，纯数字字符串兼容（与 Dataset schema 的 allow_numeric_string 同源）。 */
+/** Numbers pass through; pure numeric strings are accepted (same tolerance as Dataset allow_numeric_string). */
 function toNumber(value) {
     if (typeof value === 'number')
         return Number.isFinite(value) ? value : undefined;
@@ -98,11 +90,8 @@ function toNumber(value) {
 const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
 const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?$/;
 /**
- * 时间值解析。规则必须**确定**（同一份数据在任何机器上得到同一张图）：
- *  - 纯日期 `YYYY-MM-DD` → 业务日字符串，交给图表库按业务日显示（不做时区换算，避免差一天）；
- *  - `YYYY-MM-DD HH:mm[:ss]` 无时区 → 按 UTC 解释（显式规则，不依赖宿主本地时区）；
- *  - 数字/纯数字字符串 → epoch；`>= 1e11` 视为毫秒，否则视为秒；
- *  - 其余字符串 → `Date.parse`；失败即视为该行没有时间。
+ * Deterministic across machines: date-only stays a business-day string (no TZ shift), naive
+ * datetime is UTC, numbers >= 1e11 are epoch ms, unparseable means the row has no time.
  */
 export function parseTimeValue(value) {
     if (typeof value === 'number') {
@@ -157,23 +146,17 @@ export function buildChartPayload(input) {
         assertFields([spec.ohlc.open, spec.ohlc.high, spec.ohlc.low, spec.ohlc.close], available);
     if (spec.volume)
         assertFields([spec.volume.field], available);
-    // ── 1. 时间轴判定 ─────────────────────────────────────────────────────────
-    // 显式给了 x 但值不像时间（分类数据）时，自动降级为分类轴并用 x 的取值做刻度标签，
-    // 而不是报错让模型改口——"用 x 画柱状图"是最自然的表达。
+    // Explicit x that rarely parses as time degrades to a category axis instead of erroring.
     const axisField = spec.timeField;
     let axis = axisField === undefined ? 'index' : 'time';
-    // OHLC 图形（candlestick / bar）不允许降级：图表库的 OhlcData 需要真实有序时间轴，
-    // 拿分类轴硬画只会得到一张错位的图。
+    // OHLC kinds cannot degrade: the library needs a real ordered time axis, else the result is misaligned.
     if (axisField !== undefined && !OHLC_KINDS.includes(spec.kind)) {
-        // 后续预处理本来就会逐行解析时间；这里也统计全量，避免前 100 行的脏数据把整条
-        // 后面的真实时间序列误判成分类轴。
         const parsed = records.filter((record) => parseTimeValue(record[axisField]) !== undefined).length;
         if (parsed / records.length < TIME_AXIS_THRESHOLD) {
             axis = 'index';
             warnings.push(`x field "${axisField}" was treated as a category axis: only ${parsed}/${records.length} values look like time`);
         }
     }
-    // ── 2. 逐行预处理 ────────────────────────────────────────────────────────
     const prepared = [];
     let skippedRows = 0;
     records.forEach((record, sourceIndex) => {
@@ -197,14 +180,12 @@ export function buildChartPayload(input) {
     if (skippedRows > 0)
         warnings.push(`${skippedRows} row(s) skipped: the time field is missing or unparseable`);
     if (prepared.length === 0) {
-        // OHLC 图形必须给可解析的时间列：它不是"降级"问题，而是这张图根本画不出来。
-        // 错误必须直接把模型引到能用的 kind 上，而不是让它反复试同一个 spec。
+        // OHLC has no fallback; point the model at column/line instead of retrying the same spec.
         if (OHLC_KINDS.includes(spec.kind)) {
             throw new ChartError('chart_no_rows', `${spec.kind} 需要可解析的时间列，但字段 "${axisField ?? '(未提供 x)'}" 的值都解析不出日期或时间戳；分类数据请改用 kind=column（单值柱）或 line`);
         }
         throw new ChartError('chart_no_rows', 'no row has a usable time value');
     }
-    // ── 3. 排序 + 去重 + 区间过滤 ──────────────────────────────────────────────
     const ordered = [...prepared].sort((left, right) => left.time.seconds - right.time.seconds);
     if (ordered.some((row, index) => row !== prepared[index]))
         warnings.push('rows were reordered ascending by time (the chart library requires an ordered axis)');
@@ -233,19 +214,17 @@ export function buildChartPayload(input) {
         if (filtered.length === 0)
             throw new ChartError('chart_no_rows', 'spec.range excludes every row');
     }
-    // ── 4. 下采样（一次求下标，所有子序列共用）────────────────────────────────
+    // One LTTB index set is shared by every subplot so they stay time-aligned.
     const originalPoints = filtered.length;
     const primaryValues = primarySeriesValues(filtered, spec);
     const keep = originalPoints > MAX_CHART_POINTS ? largestTriangleThreeBuckets(primaryValues, MAX_CHART_POINTS) : filtered.map((_row, index) => index);
     const kept = keep.map((index) => filtered[index]).filter((row) => row !== undefined);
     const downsampled = kept.length < originalPoints;
-    // ── 5. 时间显示口径：全是纯日期才用业务日字符串 ────────────────────────────
     const useBusinessDay = axis === 'time' && kept.every((row) => row.time.dateOnly);
     if (axis === 'time' && !useBusinessDay && kept.some((row) => row.time.dateOnly)) {
         warnings.push('mixed date and datetime values; the axis is rendered as timestamps');
     }
     const displayTime = (row) => (useBusinessDay ? String(row.time.display) : row.time.seconds);
-    // ── 6. 子序列 ────────────────────────────────────────────────────────────
     const series = [];
     for (const item of spec.series.slice(0, MAX_CHART_SERIES)) {
         const data = [];
@@ -268,8 +247,7 @@ export function buildChartPayload(input) {
     if (spec.ohlc) {
         const data = [];
         let dropped = 0;
-        // OHLC 自洽性检查：脏数据确实存在，所以**不拦截**（拦截会让用户看不到任何图），
-        // 但必须如实披露，否则读者会把一根 high<low 的错柱子当成真行情。
+        // Inconsistent candles exist in real data: disclose them, never block — blocking hides the chart.
         let inconsistent = 0;
         const inconsistentExamples = [];
         for (const row of kept) {
@@ -308,7 +286,7 @@ export function buildChartPayload(input) {
                 dropped += 1;
                 continue;
             }
-            // A 股习惯：涨红跌绿。方向由同一行的 OHLC 推得，颜色映射留给运行时（跟随主题）。
+            // A-share convention: up = red, down = green; the actual colors come from the runtime theme.
             let direction;
             if (spec.ohlc) {
                 const open = toNumber(row.raw[spec.ohlc.open]);
@@ -324,12 +302,10 @@ export function buildChartPayload(input) {
             warnings.push(`volume: ${dropped} point(s) dropped (non-numeric or missing)`);
         volume = { label: '成交量', data };
     }
-    // ── 7. 标记点：吸附到保留下来的时间点 ──────────────────────────────────────
     const markers = [];
     const keptSeconds = kept.map((row) => row.time.seconds);
     for (const marker of spec.markers.slice(0, MAX_CHART_MARKERS)) {
-        // 两种定位都先化成"目标秒数"，再吸附到**保留**的时间点上：下采样把某个点丢掉时，
-        // 标记不该跟着消失（那正是用户最在意的那一天）。
+        // Resolve both forms to seconds, then snap to a kept point so downsampling cannot drop a marker.
         let targetSeconds;
         if (marker.index !== undefined) {
             const atIndex = filtered[marker.index];
@@ -383,7 +359,7 @@ export function buildChartPayload(input) {
         },
     };
 }
-/** 主序列取值（用于 LTTB）；K 线用收盘价，其余用第一个数值字段。 */
+/** LTTB source: close for OHLC, else the first numeric field. Field gaps carry the last value forward. */
 function primarySeriesValues(rows, spec) {
     const field = spec.ohlc ? spec.ohlc.close : spec.series[0]?.field ?? spec.volume?.field;
     const values = [];
@@ -395,7 +371,6 @@ function primarySeriesValues(rows, spec) {
     }
     return values;
 }
-/** 把标记点吸附到最近的**保留**时间点，避免下采样后标记消失。 */
 function nearestRow(rows, keptSeconds, target) {
     if (rows.length === 0)
         return undefined;

package/lib/chart/source-token.d.ts

@@ -1,10 +1,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { type SessionLike, WorkspaceDatasetStore } from '../data-collector/store.js';
-/**
- * The registry is host-only and never serializes this handle into Agent output.
- * Keeping the live Session object is required because DSH sandbox policies use
- * session.snapshotEvents() when resolving workspace permissions.
- */
+/** Host-only; never serialized into agent output. Keep the live Session: sandbox policies call
+ * session.snapshotEvents() to resolve workspace permissions. */
 export interface ChartSourceTokenRef {
     chart_source_ref: string;
     dataset_id: string;
@@ -21,13 +18,8 @@ export interface ChartSourceTokenStoreOptions {
     ttlMs?: number;
     newToken?: () => string;
 }
-/**
- * Short-lived capability tokens for nested visualization children.
- *
- * The token captures the direct data-agent session rather than asking a nested
- * child to re-prove the Dataset's one-hop session scope. Possession of the
- * opaque token is the capability; it is never converted into a filesystem path.
- */
+/** Short-lived capability tokens for nested visualization children. Possession is the capability;
+ * the token never becomes a filesystem path or raw rows. */
 export declare class ChartSourceTokenStore {
     private readonly tokens;
     private readonly now;
@@ -51,7 +43,7 @@ export declare class ChartSourceTokenStore {
     revoke(chartSourceRef: string): boolean;
     size(): number;
 }
-/** Register the delegated-child-only token issuer. */
+/** Preset-based authorization; see authorizedChartSession. */
 export declare function registerChartSourceTool(ctx: Context, options: {
     store: WorkspaceDatasetStore;
     tokens: ChartSourceTokenStore;