@v587d/capital-generation 0.0.0-stage → 2.6.1

package/lib/chart/source-token.js

@@ -0,0 +1,217 @@
+import { ChartError } from './errors.js';
+import { DatasetStoreError, } from '../data-collector/store.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 = []) => ({
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+});
+function render(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value) }];
+}
+function defaultTokenId() {
+    const cryptoLike = globalThis.crypto;
+    const suffix = cryptoLike?.randomUUID
+        ? cryptoLike.randomUUID()
+        : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+    return `cs_${suffix}`;
+}
+function sessionOf(exec) {
+    const session = exec.agent?.session;
+    if (!session || typeof session.id !== 'string' || session.id.length === 0) {
+        throw new ChartError('chart_source_invalid', 'the calling agent session was not provided');
+    }
+    return session;
+}
+function delegatedSession(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');
+    }
+    return session;
+}
+function readTaskId(value, required) {
+    if (value === undefined || value === null || value === '') {
+        if (required)
+            throw new ChartError('chart_source_invalid', 'task_id is required when using chart_source_ref');
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.trim().length === 0 || value.length > 256) {
+        throw new ChartError('chart_source_invalid', 'task_id must be a non-empty string of at most 256 characters');
+    }
+    return value.trim();
+}
+function readDatasetId(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
+        throw new ChartError('chart_source_invalid', 'dataset_id is invalid');
+    }
+    return value;
+}
+function readToken(value) {
+    if (typeof value !== 'string' || !CHART_SOURCE_TOKEN_PATTERN.test(value)) {
+        throw new ChartError('chart_source_invalid', 'chart_source_ref is invalid');
+    }
+    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.
+ */
+export class ChartSourceTokenStore {
+    tokens = new Map();
+    now;
+    ttlMs;
+    newToken;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.ttlMs = options.ttlMs ?? DEFAULT_CHART_SOURCE_TTL_MS;
+        this.newToken = options.newToken ?? defaultTokenId;
+        if (!Number.isSafeInteger(this.ttlMs) || this.ttlMs <= 0) {
+            throw new Error('ChartSourceTokenStore ttlMs must be a positive safe integer');
+        }
+    }
+    purgeExpired(now) {
+        for (const [token, record] of this.tokens) {
+            if (record.expires_at <= now)
+                this.tokens.delete(token);
+        }
+    }
+    async issue(input) {
+        const datasetId = readDatasetId(input.dataset_id);
+        const taskId = readTaskId(input.task_id, true);
+        const inspection = await input.store.inspectDataset(datasetId, input.session, input.signal);
+        if (!inspection.query_access.readable || !['array', 'envelope_item'].includes(inspection.query_access.shape)) {
+            throw new ChartError('chart_source_invalid', `Dataset ${datasetId} cannot be used as a chart source (${inspection.query_access.reason ?? inspection.query_access.shape})`);
+        }
+        const now = this.now();
+        this.purgeExpired(now);
+        const token = this.newToken();
+        if (!CHART_SOURCE_TOKEN_PATTERN.test(token)) {
+            throw new ChartError('chart_source_invalid', 'generated chart_source_ref is invalid');
+        }
+        if (this.tokens.has(token))
+            throw new ChartError('chart_source_invalid', 'generated chart_source_ref already exists');
+        const expiresAt = Math.min(inspection.retention_until, now + this.ttlMs);
+        const record = {
+            chart_source_ref: token,
+            dataset_id: inspection.dataset_id,
+            task_id: taskId,
+            expires_at: expiresAt,
+            sourceSession: input.session,
+            issued_at: now,
+        };
+        this.tokens.set(token, record);
+        return {
+            chart_source_ref: record.chart_source_ref,
+            dataset_id: record.dataset_id,
+            task_id: record.task_id,
+            expires_at: record.expires_at,
+        };
+    }
+    resolve(input) {
+        const token = readToken(input.chart_source_ref);
+        const now = input.now ?? this.now();
+        this.purgeExpired(now);
+        const record = this.tokens.get(token);
+        if (!record)
+            throw new ChartError('chart_source_expired', 'chart_source_ref is unknown or expired');
+        const taskId = readTaskId(input.task_id, true);
+        if (record.task_id !== null && record.task_id !== taskId) {
+            throw new ChartError('chart_source_scope_mismatch', 'chart_source_ref does not belong to this task');
+        }
+        if (input.session !== undefined) {
+            const caller = input.session;
+            const source = record.sourceSession;
+            const isSource = caller.id === source.id;
+            const isDirectChild = caller.header?.parentSession === source.id;
+            if (!isSource && !isDirectChild) {
+                throw new ChartError('chart_source_scope_mismatch', 'chart_source_ref is not authorized for this session');
+            }
+            if (source.header?.cwd !== undefined && caller.header?.cwd !== undefined && source.header.cwd !== caller.header.cwd) {
+                throw new ChartError('chart_source_scope_mismatch', 'chart_source_ref does not belong to this workspace');
+            }
+        }
+        return record;
+    }
+    revoke(chartSourceRef) {
+        return this.tokens.delete(chartSourceRef);
+    }
+    size() {
+        this.purgeExpired(this.now());
+        return this.tokens.size;
+    }
+}
+const outputSchema = jsonObject({
+    chart_source_ref: { type: 'string' },
+    dataset_id: { type: 'string' },
+    task_id: { type: 'string' },
+    expires_at: { type: 'integer' },
+}, ['chart_source_ref', 'dataset_id', 'task_id', 'expires_at']);
+/** Register the delegated-child-only token issuer. */
+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 读取。' +
+            '只返回 opaque token 和小型元数据，不返回原始数据、文件路径或数据行；必须提供 dataset_id，可选 task_id。',
+        parameters: jsonObject({
+            dataset_id: { type: 'string', description: '已授权的 DatasetRef dataset_id' },
+            task_id: { type: 'string', description: '当前可视化任务标识；用于绑定 token，必填' },
+        }, ['dataset_id', 'task_id']),
+        output: { schema: outputSchema, render },
+        async execute(args, exec) {
+            try {
+                const session = delegatedSession(exec);
+                return await options.tokens.issue({
+                    store: options.store,
+                    session,
+                    dataset_id: args.dataset_id,
+                    task_id: args.task_id,
+                    signal: exec.signal,
+                });
+            }
+            catch (error) {
+                if (error instanceof ChartError) {
+                    const visible = new Error(JSON.stringify(error.toEnvelope()));
+                    visible.name = error.name;
+                    visible.code = error.code;
+                    throw visible;
+                }
+                if (error instanceof DatasetStoreError) {
+                    const visible = new Error(JSON.stringify({ error: 'chart_source_invalid', detail: error.message }));
+                    visible.name = 'ChartError';
+                    visible.code = 'chart_source_invalid';
+                    throw visible;
+                }
+                throw error;
+            }
+        },
+    };
+    ctx.effect(() => tools.register(definition), 'capital-generation.tool(prepare_chart_source)');
+}
+export function chartSourceTokenForRender(tokens, args, session) {
+    const chartSourceRef = typeof args.chart_source_ref === 'string' && args.chart_source_ref.trim().length > 0
+        ? args.chart_source_ref.trim()
+        : undefined;
+    if (chartSourceRef === undefined)
+        return undefined;
+    if (!tokens)
+        throw new ChartError('chart_source_invalid', 'chart_source_ref is not available in this runtime');
+    const record = tokens.resolve({
+        chart_source_ref: chartSourceRef,
+        task_id: typeof args.task_id === 'string' ? args.task_id : undefined,
+        session,
+    });
+    return {
+        dataset_id: record.dataset_id,
+        task_id: record.task_id,
+        sourceSession: record.sourceSession,
+    };
+}

package/lib/chart/spec.d.ts

@@ -0,0 +1,58 @@
+export type ChartKind = 'line' | 'area' | 'column' | 'candlestick' | 'bar';
+export type ChartSeriesType = 'line' | 'area' | 'column';
+export type MarkerPosition = 'aboveBar' | 'belowBar' | 'inBar';
+export interface ChartSeriesSpec {
+    field: string;
+    label: string;
+    type: ChartSeriesType;
+}
+export interface ChartOhlcSpec {
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+}
+export interface ChartMarkerSpec {
+    text: string;
+    position: MarkerPosition;
+    /** 与 x 同口径的时间值；与 index 二选一。 */
+    time?: string | number;
+    /** 过滤后序列中的 0 基行号。 */
+    index?: number;
+}
+export interface NormalizedChartSpec {
+    kind: ChartKind;
+    /** time = 有真实时间列；index = 按行序（分类轴），标签由 labels 映射。 */
+    axis: 'time' | 'index';
+    timeField?: string;
+    series: ChartSeriesSpec[];
+    ohlc?: ChartOhlcSpec;
+    volume?: {
+        field: string;
+    };
+    markers: ChartMarkerSpec[];
+    range?: {
+        from?: string | number;
+        to?: string | number;
+    };
+    title?: string;
+}
+export declare const CHART_KINDS: readonly ChartKind[];
+/**
+ * 需要 OHLC 四字段（而不是单值字段选择）的 kind。
+ *
+ * 依据是图表库的数据契约本身：`CandlestickData` 与 `BarData` 都继承 `OhlcData`，
+ * 而 `LineData` / `HistogramData` 继承 `SingleValueData`。把单值序列塞进 BarSeries
+ * 不会报错，只会画出一张**空图** —— 所以这个约束必须在 spec 层硬拦，
+ * 不能指望"模型会写对"（这是实测出来的坑，不是推演）。
+ */
+export declare const OHLC_KINDS: readonly ChartKind[];
+export declare const CHART_SERIES_TYPES: readonly ChartSeriesType[];
+export declare const MARKER_POSITIONS: readonly MarkerPosition[];
+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 说明（错误信息与工具描述共用一处，避免两处措辞漂移）。 */
+export declare function describeKinds(): string;
+export declare function normalizeChartSpec(raw: unknown): NormalizedChartSpec;

package/lib/chart/spec.js

@@ -0,0 +1,265 @@
+/**
+ * 图表 spec 的归一化与校验。
+ *
+ * 设计要点（见内部设计文档 docs/design/chart-visualization.md §3.3）：
+ *  - spec 用**自由对象**表达，协议细节写在 skill 里按需加载，常驻的只有工具 schema——
+ *    这是"可视化不污染上下文"的关键：模型不需要在每轮都看一遍图表 DSL。
+ *  - 但自由对象不等于放任：这里做一次严格归一化，错误必须**可自愈**（点名字段 + 给候选）。
+ *  - 与 query_dataset 同源的宽容度：模型经常把对象/数组序列化成 JSON 字符串再传
+ *    （实测教训见 src/data-collector/dataset-tools.ts 的注释），这里在**工具边界**
+ *    做一次宽容解析，内部保持严格。
+ */
+import { ChartError } from './errors.js';
+export const CHART_KINDS = ['line', 'area', 'column', 'candlestick', 'bar'];
+/**
+ * 需要 OHLC 四字段（而不是单值字段选择）的 kind。
+ *
+ * 依据是图表库的数据契约本身：`CandlestickData` 与 `BarData` 都继承 `OhlcData`，
+ * 而 `LineData` / `HistogramData` 继承 `SingleValueData`。把单值序列塞进 BarSeries
+ * 不会报错，只会画出一张**空图** —— 所以这个约束必须在 spec 层硬拦，
+ * 不能指望"模型会写对"（这是实测出来的坑，不是推演）。
+ */
+export const OHLC_KINDS = ['candlestick', 'bar'];
+export const CHART_SERIES_TYPES = ['line', 'area', 'column'];
+export const MARKER_POSITIONS = ['aboveBar', 'belowBar', 'inBar'];
+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` 的错误，而不是一张空图。
+ */
+const KIND_ALIASES = {
+    histogram: 'column',
+    candles: 'candlestick',
+    candle: 'candlestick',
+    ohlc: 'bar',
+    candlestick_bar: 'bar',
+};
+const SERIES_TYPE_ALIASES = { histogram: 'column' };
+/** 面向模型的 kind 说明（错误信息与工具描述共用一处，避免两处措辞漂移）。 */
+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。 */
+function coerceObject(value) {
+    if (isRecord(value))
+        return value;
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    if (text.length === 0 || text[0] !== '{')
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 宽容解析对象数组：真数组、JSON 数组字符串、单个对象（或其 JSON 字符串）都接受。 */
+function coerceObjectList(value) {
+    if (Array.isArray(value))
+        return value;
+    if (isRecord(value))
+        return [value];
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    if (text.length === 0)
+        return undefined;
+    if (text[0] === '[' || text[0] === '{') {
+        try {
+            const parsed = JSON.parse(text);
+            if (Array.isArray(parsed))
+                return parsed;
+            if (isRecord(parsed))
+                return [parsed];
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function readFieldName(value, where) {
+    if (typeof value !== 'string')
+        throw new ChartError('chart_spec_invalid', `${where} must be a string field name`);
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || trimmed.length > MAX_FIELD_NAME) {
+        throw new ChartError('chart_spec_invalid', `${where} must be a field name of 1-${MAX_FIELD_NAME} characters`);
+    }
+    return trimmed;
+}
+function readOptionalFieldName(value, where) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return readFieldName(value, where);
+}
+/** 取第一个出现的别名键；用于容忍模型用 x / time / time_field 等等价说法。 */
+function pickAlias(source, names) {
+    for (const name of names)
+        if (source[name] !== undefined)
+            return source[name];
+    return undefined;
+}
+function readKind(value) {
+    if (typeof value !== 'string') {
+        throw new ChartError('chart_spec_invalid', `spec.kind is required and must be one of: ${describeKinds()}`);
+    }
+    const raw = value.trim().toLowerCase();
+    const kind = (KIND_ALIASES[raw] ?? raw);
+    if (!CHART_KINDS.includes(kind)) {
+        throw new ChartError('chart_spec_invalid', `spec.kind must be one of: ${describeKinds()} (got ${JSON.stringify(value)})`, { allowed: [...CHART_KINDS] });
+    }
+    return kind;
+}
+function readSeries(value) {
+    const list = coerceObjectList(value);
+    if (list === undefined || list.length === 0) {
+        throw new ChartError('chart_spec_invalid', 'spec.series is required for this kind: an array of 1-6 entries, each a field name or { field, label?, type? }');
+    }
+    if (list.length > MAX_CHART_SERIES) {
+        throw new ChartError('chart_spec_invalid', `spec.series accepts at most ${MAX_CHART_SERIES} entries (got ${list.length})`);
+    }
+    return list.map((entry, index) => {
+        if (typeof entry === 'string')
+            return { field: readFieldName(entry, `spec.series[${index}]`), label: entry.trim(), type: 'line' };
+        if (!isRecord(entry))
+            throw new ChartError('chart_spec_invalid', `spec.series[${index}] must be a field name or an object`);
+        const field = readFieldName(entry.field ?? entry.column ?? entry.name, `spec.series[${index}].field`);
+        const label = typeof entry.label === 'string' && entry.label.trim().length > 0 ? entry.label.trim() : field;
+        let type = 'line';
+        if (entry.type !== undefined) {
+            const raw = typeof entry.type === 'string' ? entry.type.trim().toLowerCase() : '';
+            const resolved = (SERIES_TYPE_ALIASES[raw] ?? raw);
+            if (!CHART_SERIES_TYPES.includes(resolved)) {
+                throw new ChartError('chart_spec_invalid', `spec.series[${index}].type must be one of: ${CHART_SERIES_TYPES.join(', ')} — 序列是单值字段，OHLC 图形（candlestick / bar）要用 spec.ohlc`, { allowed: [...CHART_SERIES_TYPES] });
+            }
+            type = resolved;
+        }
+        return { field, label, type };
+    });
+}
+function readOhlc(value) {
+    const ohlc = coerceObject(value);
+    if (!ohlc) {
+        throw new ChartError('chart_spec_invalid', 'candlestick requires spec.ohlc = { open, high, low, close } with four field names');
+    }
+    return {
+        open: readFieldName(ohlc.open, 'spec.ohlc.open'),
+        high: readFieldName(ohlc.high, 'spec.ohlc.high'),
+        low: readFieldName(ohlc.low, 'spec.ohlc.low'),
+        close: readFieldName(ohlc.close, 'spec.ohlc.close'),
+    };
+}
+function readVolume(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (typeof value === 'string')
+        return { field: readFieldName(value, 'spec.volume') };
+    const volume = coerceObject(value);
+    if (!volume)
+        throw new ChartError('chart_spec_invalid', 'spec.volume must be a field name or { field }');
+    const field = readOptionalFieldName(volume.field ?? volume.column, 'spec.volume.field');
+    if (field === undefined)
+        throw new ChartError('chart_spec_invalid', 'spec.volume requires a field name');
+    return { field };
+}
+function readMarkers(value) {
+    if (value === undefined || value === null)
+        return [];
+    const list = coerceObjectList(value);
+    if (list === undefined)
+        throw new ChartError('chart_spec_invalid', 'spec.markers must be an array of { time|index, text, position? }');
+    if (list.length > MAX_CHART_MARKERS) {
+        throw new ChartError('chart_spec_invalid', `spec.markers accepts at most ${MAX_CHART_MARKERS} entries (got ${list.length})`);
+    }
+    return list.map((entry, index) => {
+        if (!isRecord(entry))
+            throw new ChartError('chart_spec_invalid', `spec.markers[${index}] must be an object`);
+        const text = typeof (entry.text ?? entry.label) === 'string' ? String(entry.text ?? entry.label).trim() : '';
+        if (text.length === 0 || text.length > 120) {
+            throw new ChartError('chart_spec_invalid', `spec.markers[${index}].text must be 1-120 characters`);
+        }
+        const rawPosition = typeof entry.position === 'string' ? entry.position.trim() : 'aboveBar';
+        if (!MARKER_POSITIONS.includes(rawPosition)) {
+            throw new ChartError('chart_spec_invalid', `spec.markers[${index}].position must be one of: ${MARKER_POSITIONS.join(', ')}`, { allowed: [...MARKER_POSITIONS] });
+        }
+        const rawTime = pickAlias(entry, ['time', 'date', 'x']);
+        const rawIndex = entry.index ?? entry.i;
+        if (rawTime === undefined && rawIndex === undefined) {
+            throw new ChartError('chart_spec_invalid', `spec.markers[${index}] needs a time (matching spec.x) or a 0-based index`);
+        }
+        const marker = { text, position: rawPosition };
+        if (rawTime !== undefined) {
+            if (typeof rawTime !== 'string' && typeof rawTime !== 'number') {
+                throw new ChartError('chart_spec_invalid', `spec.markers[${index}].time must be a string or number`);
+            }
+            marker.time = rawTime;
+        }
+        if (rawIndex !== undefined) {
+            if (typeof rawIndex !== 'number' || !Number.isSafeInteger(rawIndex) || rawIndex < 0) {
+                throw new ChartError('chart_spec_invalid', `spec.markers[${index}].index must be a non-negative integer`);
+            }
+            marker.index = rawIndex;
+        }
+        return marker;
+    });
+}
+function readRange(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const range = coerceObject(value);
+    if (!range)
+        throw new ChartError('chart_spec_invalid', 'spec.range must be an object { from?, to? }');
+    const from = pickAlias(range, ['from', 'start']);
+    const to = pickAlias(range, ['to', 'end']);
+    const read = (raw, where) => {
+        if (raw === undefined || raw === null || raw === '')
+            return undefined;
+        if (typeof raw === 'number' && Number.isFinite(raw))
+            return raw;
+        if (typeof raw === 'string')
+            return raw.trim();
+        throw new ChartError('chart_spec_invalid', `spec.range.${where} must be a date string or an epoch number`);
+    };
+    const result = { from: read(from, 'from'), to: read(to, 'to') };
+    if (result.from === undefined && result.to === undefined)
+        return undefined;
+    return result;
+}
+export function normalizeChartSpec(raw) {
+    const spec = coerceObject(raw);
+    if (!spec) {
+        throw new ChartError('chart_spec_invalid', 'spec must be an object (a JSON object string is also accepted); see skill capital-chart-protocol');
+    }
+    const kind = readKind(spec.kind);
+    const timeField = readOptionalFieldName(pickAlias(spec, ['x', 'time_field', 'time']), 'spec.x');
+    const volume = readVolume(pickAlias(spec, ['volume', 'volume_field']));
+    const markers = readMarkers(spec.markers);
+    const range = readRange(spec.range);
+    const title = typeof spec.title === 'string' && spec.title.trim().length > 0 ? spec.title.trim().slice(0, MAX_CHART_TITLE) : undefined;
+    if (OHLC_KINDS.includes(kind)) {
+        const ohlc = readOhlc(spec.ohlc ?? spec.candles);
+        if (timeField === undefined) {
+            throw new ChartError('chart_spec_invalid', `${kind} requires spec.x: the time field name (OHLC 图形需要真实时间轴，不能退化成分类轴)`);
+        }
+        return { kind, axis: 'time', timeField, series: [], ohlc, volume, markers, range, title };
+    }
+    if (spec.ohlc !== undefined && spec.ohlc !== null && spec.ohlc !== '') {
+        throw new ChartError('chart_spec_invalid', `spec.ohlc 只用于 candlestick / bar；kind=${kind} 请改用 spec.series（单值字段选择）`);
+    }
+    const series = readSeries(spec.series ?? spec.fields ?? spec.y);
+    return { kind, axis: timeField === undefined ? 'index' : 'time', timeField, series, volume, markers, range, title };
+}

package/lib/chart/tool.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `render_chart`：把已经取到的数据渲染成图，**只回一条小回执**。
+ *
+ * 上下文经济学（这是本工具存在的理由）：
+ *  - 常驻成本 = 一条工具 schema；协议细节在 skill `capital-chart-protocol` 里按需加载；
+ *  - 每次调用成本 = spec（几十到一百多 token）+ 回执（几十 token）；
+ *  - 序列数据 **0 token**：由宿主写进 workspace 产物，浏览器走旁路取。
+ * 对照：让模型把 250 点日线写进参数 ≈ 5–8k token，还会被工具结果剪枝器截断。
+ *
+ * 权限边界（docs/dev/data-roles.md §1.1「数据调度纪律」的显式豁免）：本工具是**呈现**工具，不是数据工具。
+ * 它读 Dataset 只在宿主进程内进行，回执不含任何 rows —— 因此不越过"数据内容不进主 Agent
+ * 上下文"这条真正的边界。需要数值结论仍走 data_junior 的 profile / query。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { WorkspaceDatasetStore } from '../data-collector/store.js';
+import { type ChartSourceTokenStore } from './source-token.js';
+import { ChartArtifactRegistry } from './artifact-ref.js';
+import { type ChartEventPublisher } from './events.js';
+type AgentExecutionLike = {
+    session?: {
+        id?: string;
+        header?: {
+            cwd?: string;
+            parentSession?: string;
+        };
+    };
+};
+type ToolExecLike = {
+    agent?: AgentExecutionLike;
+    signal: AbortSignal;
+};
+export declare const CHART_ARTIFACT_DIR = "capital-analysis/charts";
+/** 回执字段全部是可以进上下文的小元数据；序列本体永远不在这里。 */
+export interface ChartReceipt {
+    chart_ref: string;
+    chart_id: string;
+    kind: string;
+    axis: 'time' | 'index';
+    title: string;
+    points: number;
+    original_points: number;
+    downsampled: boolean;
+    series_labels: string[];
+    has_volume: boolean;
+    markers: number;
+    dataset_id: string | null;
+    source_label: string | null;
+    captured_at: number | null;
+    chart_url: string | null;
+    spec_path: string;
+    series_path: string;
+    html_path: string;
+    warnings: string[];
+}
+export interface ChartPublisher {
+    publish(input: {
+        chartId: string;
+        filePath: string;
+    }): string | null;
+}
+export interface RenderChartInput {
+    store: WorkspaceDatasetStore;
+    sourceTokens?: ChartSourceTokenStore;
+    artifacts?: ChartArtifactRegistry;
+    /**
+     * 惰性解析 host 平面图表服务（`@v587d/capital-charts` 提供）。
+     *
+     * 每次画图时解析，而不是在 `apply` 时解析一次：host 平面行与本 preset 行的挂载先后
+     * 不由我们决定，一次性解析会把"服务稍后才可用"永久固化成 `chart_url=null`。
+     * 服务始终缺席（未安装/无 Web 载体/坏掉）时返回 undefined，整条链路照常降级：产物照样
+     * 落盘、`html_path` 照样可 present，只是 `chart_url` 为 null。
+     */
+    charts?: () => ChartPublisher | undefined;
+    /**
+     * 惰性解析"图表 → 本轮交付"发布器（官方 `deliverables/presented`）。
+     *
+     * 与 `charts` 同理每次出图解析一次：宿主平面的 `sessions` / `sessionProjections`
+     * 不可用时返回 undefined，整条链路照常降级——图仍在 workspace 里，回执照样给 html_path，
+     * 只是本轮交付行不会登记这张图。
+     */
+    chartEvents?: () => ChartEventPublisher | undefined;
+    now?: () => number;
+}
+export declare function renderChart(input: RenderChartInput, args: Record<string, unknown>, exec: ToolExecLike): Promise<ChartReceipt>;
+export declare function registerChartTool(ctx: Context, options: RenderChartInput): void;
+export {};