@v587d/capital-generation 2.8.2 → 2.9.0

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;

package/lib/chart/source-token.js

@@ -1,5 +1,8 @@
 import { ChartError } from './errors.js';
 import { DatasetStoreError, } from '../data-collector/store.js';
+// Authorization has one implementation (src/tool-exec.ts); the error shape stays chart-specific.
+import { authorizeToolSession } from '../tool-exec.js';
+import { CHART_SOURCE_PRESET_IDS } from '../preset-ids.js';
 const CHART_SOURCE_TOKEN_PATTERN = /^cs_[A-Za-z0-9_-]{1,128}$/;
 const DEFAULT_CHART_SOURCE_TTL_MS = 15 * 60 * 1000;
 const jsonObject = (properties = {}, required = []) => ({
@@ -25,10 +28,14 @@ function sessionOf(exec) {
     }
     return session;
 }
-function delegatedSession(exec) {
+/** Shared preset-based authorizer; chart_source_scope_mismatch shape stays here (test-pinned). */
+function authorizedChartSession(ctx, exec) {
     const session = sessionOf(exec);
-    if (typeof session.header?.parentSession !== 'string' || session.header.parentSession.length === 0) {
-        throw new ChartError('chart_source_scope_mismatch', 'prepare_chart_source is restricted to delegated data agents');
+    const decision = authorizeToolSession(ctx, exec, 'prepare_chart_source', CHART_SOURCE_PRESET_IDS);
+    if (!decision.allowed) {
+        throw new ChartError('chart_source_scope_mismatch', decision.via === 'preset'
+            ? `prepare_chart_source 不对人设 ${decision.presetId} 开放；签发出图读能力只属于数据角色`
+            : 'prepare_chart_source is restricted to delegated data agents');
     }
     return session;
 }
@@ -55,13 +62,8 @@ function readToken(value) {
     }
     return value;
 }
-/**
- * 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 class ChartSourceTokenStore {
     tokens = new Map();
     now;
@@ -86,10 +88,8 @@ export class ChartSourceTokenStore {
         const taskId = readTaskId(input.task_id, true);
         const now = this.now();
         this.purgeExpired(now);
-        // 幂等：同一 session + task_id + dataset_id 在 TTL 内重复签发返回**同一个** token。
-        // 2026-10-10 真机（task_fh_300803_20261010）：data_junior 改了视图方案后为同一 dataset
-        // 重签，跟着就是 7.9K 字符的思考回合——skill 里的"不要重签"警告拦不住，所以把幂等沉到
-        // 工具层。token 是读能力而非一次性凭证（resolve 不消费），复用没有语义损失。
+        // Idempotent within TTL for the same session+task+dataset: re-issuing triggers huge thinking
+        // turns, and resolve() does not consume the token, so reuse has no semantic cost.
         for (const record of this.tokens.values()) {
             if (record.dataset_id === datasetId && record.task_id === taskId && record.sourceSession.id === input.session.id) {
                 return {
@@ -110,6 +110,7 @@ export class ChartSourceTokenStore {
         }
         if (this.tokens.has(token))
             throw new ChartError('chart_source_invalid', 'generated chart_source_ref already exists');
+        // Never outlive the dataset's retention.
         const expiresAt = Math.min(inspection.retention_until, now + this.ttlMs);
         const record = {
             chart_source_ref: token,
@@ -166,14 +167,14 @@ const outputSchema = jsonObject({
     task_id: { type: 'string' },
     expires_at: { type: 'integer' },
 }, ['chart_source_ref', 'dataset_id', 'task_id', 'expires_at']);
-/** Register the delegated-child-only token issuer. */
+/** Preset-based authorization; see authorizedChartSession. */
 export function registerChartSourceTool(ctx, options) {
     const tools = ctx.get('tools');
     if (!tools)
         return;
     const definition = {
         name: 'prepare_chart_source',
-        description: '为当前 delegated data agent 的指定 Dataset 签发短期 chart_source_ref，供 visualization_specialist 通过受控 render_chart 读取。' +
+        description: '为**当前数据角色会话**已授权的 Dataset 签发短期 chart_source_ref，供 visualization_specialist 通过受控 render_chart 读取（授权按人设判定，被委派与独立开启的数据模式都能签发）。' +
             '只返回 opaque token 和小型元数据，不返回原始数据、文件路径或数据行；必须提供 dataset_id，可选 task_id。' +
             '同一 task_id + dataset_id 重复调用幂等返回同一个 chart_source_ref（TTL 内），改了视图方案直接复用即可。',
         parameters: jsonObject({
@@ -183,7 +184,7 @@ export function registerChartSourceTool(ctx, options) {
         output: { schema: outputSchema, render },
         async execute(args, exec) {
             try {
-                const session = delegatedSession(exec);
+                const session = authorizedChartSession(ctx, exec);
                 return await options.tokens.issue({
                     store: options.store,
                     session,

package/lib/chart/spec.d.ts

@@ -15,14 +15,14 @@ export interface ChartOhlcSpec {
 export interface ChartMarkerSpec {
     text: string;
     position: MarkerPosition;
-    /** 与 x 同口径的时间值；与 index 二选一。 */
+    /** Time value matching x; mutually exclusive with index. */
     time?: string | number;
-    /** 过滤后序列中的 0 基行号。 */
+    /** 0-based row index into the filtered series. */
     index?: number;
 }
 export interface NormalizedChartSpec {
     kind: ChartKind;
-    /** time = 有真实时间列；index = 按行序（分类轴），标签由 labels 映射。 */
+    /** time = real time column; index = row order (category axis, labels mapped at render time). */
     axis: 'time' | 'index';
     timeField?: string;
     series: ChartSeriesSpec[];
@@ -38,14 +38,8 @@ export interface NormalizedChartSpec {
     title?: string;
 }
 export declare const CHART_KINDS: readonly ChartKind[];
-/**
- * 需要 OHLC 四字段（而不是单值字段选择）的 kind。
- *
- * 依据是图表库的数据契约本身：`CandlestickData` 与 `BarData` 都继承 `OhlcData`，
- * 而 `LineData` / `HistogramData` 继承 `SingleValueData`。把单值序列塞进 BarSeries
- * 不会报错，只会画出一张**空图** —— 所以这个约束必须在 spec 层硬拦，
- * 不能指望"模型会写对"（这是实测出来的坑，不是推演）。
- */
+/** OHLC kinds need four fields (library OhlcData vs SingleValueData); a single-value series in
+ * BarSeries silently draws an empty chart, so reject it at the spec layer. */
 export declare const OHLC_KINDS: readonly ChartKind[];
 export declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
 export declare const MARKER_POSITIONS: readonly MarkerPosition[];
@@ -53,6 +47,6 @@ export declare const MAX_CHART_SERIES = 6;
 export declare const MAX_CHART_MARKERS = 50;
 export declare const MAX_FIELD_NAME = 128;
 export declare const MAX_CHART_TITLE = 200;
-/** 面向模型的 kind 说明（错误信息与工具描述共用一处，避免两处措辞漂移）。 */
+/** Shared model-facing kind description so error text and tool docs cannot drift. */
 export declare function describeKinds(): string;
 export declare function normalizeChartSpec(raw: unknown): NormalizedChartSpec;

package/lib/chart/spec.js

@@ -1,24 +1,9 @@
-/**
- * 图表 spec 的归一化与校验。
- *
- * 设计要点（见内部设计文档 docs/design/chart-visualization.md §3.3）：
- *  - spec 用**自由对象**表达，协议细节写在 skill 里按需加载，常驻的只有工具 schema——
- *    这是"可视化不污染上下文"的关键：模型不需要在每轮都看一遍图表 DSL。
- *  - 但自由对象不等于放任：这里做一次严格归一化，错误必须**可自愈**（点名字段 + 给候选）。
- *  - 与 query_dataset 同源的宽容度：模型经常把对象/数组序列化成 JSON 字符串再传
- *    （实测教训见 src/data-collector/dataset-tools.ts 的注释），这里在**工具边界**
- *    做一次宽容解析，内部保持严格。
- */
+/** Normalize/validate the chart spec at the tool boundary. Errors must be self-correcting
+ * (name the field, list candidates); JSON-string forms are tolerated here, strict inside. */
 import { ChartError } from './errors.js';
 export const CHART_KINDS = ['line', 'area', 'column', 'candlestick', 'bar'];
-/**
- * 需要 OHLC 四字段（而不是单值字段选择）的 kind。
- *
- * 依据是图表库的数据契约本身：`CandlestickData` 与 `BarData` 都继承 `OhlcData`，
- * 而 `LineData` / `HistogramData` 继承 `SingleValueData`。把单值序列塞进 BarSeries
- * 不会报错，只会画出一张**空图** —— 所以这个约束必须在 spec 层硬拦，
- * 不能指望"模型会写对"（这是实测出来的坑，不是推演）。
- */
+/** OHLC kinds need four fields (library OhlcData vs SingleValueData); a single-value series in
+ * BarSeries silently draws an empty chart, so reject it at the spec layer. */
 export const OHLC_KINDS = ['candlestick', 'bar'];
 export const CHART_SERIES_TYPES = ['line', 'area', 'column'];
 export const MARKER_POSITIONS = ['aboveBar', 'belowBar', 'inBar'];
@@ -26,14 +11,7 @@ export const MAX_CHART_SERIES = 6;
 export const MAX_CHART_MARKERS = 50;
 export const MAX_FIELD_NAME = 128;
 export const MAX_CHART_TITLE = 200;
-/**
- * 容忍的说法 → canonical 名。
- *
- * `histogram` 是图表库的类名，但它画的是**着色柱**、不是统计分箱直方图；直接把它当
- * canonical 名会让模型以为"可以画分布"。canonical 用 `column`，同时接受旧说法以免硬失败。
- * 同理 `bar` 在中文语境里常被当成"柱状图"，而它其实是 OHLC 柱：单值柱状图会得到一条
- * 明确指向 `column` 的错误，而不是一张空图。
- */
+/** `histogram` maps to `column` (a colored bar, not a statistical bin); `bar` is an OHLC bar. */
 const KIND_ALIASES = {
     histogram: 'column',
     candles: 'candlestick',
@@ -42,14 +20,14 @@ const KIND_ALIASES = {
     candlestick_bar: 'bar',
 };
 const SERIES_TYPE_ALIASES = { histogram: 'column' };
-/** 面向模型的 kind 说明（错误信息与工具描述共用一处，避免两处措辞漂移）。 */
+/** Shared model-facing kind description so error text and tool docs cannot drift. */
 export function describeKinds() {
     return `${CHART_KINDS.join(' / ')}（candlestick 与 bar 需要 ohlc 四字段与真实时间列；单值柱状图用 column，本库没有统计分箱直方图）`;
 }
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
-/** 宽容解析：真对象直接用；JSON 字符串解析成对象后使用；其余返回 undefined。 */
+/** Tolerate JSON-string spec fragments at the tool boundary. */
 function coerceObject(value) {
     if (isRecord(value))
         return value;
@@ -66,7 +44,6 @@ function coerceObject(value) {
         return undefined;
     }
 }
-/** 宽容解析对象数组：真数组、JSON 数组字符串、单个对象（或其 JSON 字符串）都接受。 */
 function coerceObjectList(value) {
     if (Array.isArray(value))
         return value;
@@ -106,7 +83,6 @@ function readOptionalFieldName(value, where) {
         return undefined;
     return readFieldName(value, where);
 }
-/** 取第一个出现的别名键；用于容忍模型用 x / time / time_field 等等价说法。 */
 function pickAlias(source, names) {
     for (const name of names)
         if (source[name] !== undefined)