@v587d/capital-generation 2.8.3 → 2.9.0

package/lib/chart/tool.d.ts

@@ -1,16 +1,6 @@
-/**
- * `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。
- */
+/** render_chart: render data into workspace artifacts and return only a small receipt.
+ * Series costs zero model tokens and rows stay host-side; numeric conclusions still go through
+ * data_junior. */
 import type { Context } from '@deepseek-ai/cordis';
 import { WorkspaceDatasetStore } from '../data-collector/store.js';
 import { type ChartSourceTokenStore } from './source-token.js';
@@ -30,7 +20,7 @@ type ToolExecLike = {
     signal: AbortSignal;
 };
 export declare const CHART_ARTIFACT_DIR = "capital-analysis/charts";
-/** 回执字段全部是可以进上下文的小元数据；序列本体永远不在这里。 */
+/** Receipt is small metadata only; series never appears here. */
 export interface ChartReceipt {
     chart_ref: string;
     chart_id: string;
@@ -62,22 +52,9 @@ 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。
-     */
+    /** Resolve per render, not at apply: host rows may mount later; absence degrades to chart_url=null. */
     charts?: () => ChartPublisher | undefined;
-    /**
-     * 惰性解析"图表 → 本轮交付"发布器（官方 `deliverables/presented`）。
-     *
-     * 与 `charts` 同理每次出图解析一次：宿主平面的 `sessions` / `sessionProjections`
-     * 不可用时返回 undefined，整条链路照常降级——图仍在 workspace 里，回执照样给 html_path，
-     * 只是本轮交付行不会登记这张图。
-     */
+    /** Same lazy rule: an absent publisher skips only the deliverable row. */
     chartEvents?: () => ChartEventPublisher | undefined;
     now?: () => number;
 }

package/lib/chart/tool.js

@@ -56,10 +56,7 @@ function normalizeStoreError(error) {
             return undefined;
     }
 }
-/**
- * 工具框架对 throw 的错误只保留 message；把 ChartError 的 details 在这里展开成
- * JSON 信封，模型才能拿到 array_keys / available 等一次修正所需的信息。
- */
+/** Errors keep only message; expand details into JSON so the model can self-correct. */
 function toolVisibleError(error) {
     const normalized = error instanceof ChartError ? error : normalizeStoreError(error);
     if (!normalized)
@@ -126,13 +123,10 @@ export async function renderChart(input, args, exec) {
     const spec = normalizeChartSpec(args.spec);
     if (typeof args.title === 'string' && args.title.trim().length > 0)
         spec.title = args.title.trim().slice(0, 200);
-    // ── 取数：两条来源都在宿主进程内完成，rows 不进入任何消息 ────────────────────
+    // The token carries the direct data-agent session; the nested child never sees raw rows.
     let rows;
     let meta;
     if (datasetId !== undefined) {
-        // A chart_source_ref carries the direct data-agent session that already has
-        // access to the parent Dataset scope. The nested visualization child is
-        // only the caller of render_chart; it never receives raw rows.
         const readSession = tokenSource?.sourceSession ?? session;
         const { ref, rows: datasetRows } = await input.store.readPresentationRows({ session: readSession, dataset_id: datasetId, signal: exec.signal });
         rows = datasetRows;
@@ -144,7 +138,6 @@ export async function renderChart(input, args, exec) {
         rows = extracted.rows;
         meta = { source_kind: 'path' };
     }
-    // ── 有界化 ───────────────────────────────────────────────────────────────
     const chartId = newChartId();
     const payload = buildChartPayload({ chart_id: chartId, spec, rows, meta });
     const library = loadVendoredChartLibrary();
@@ -162,8 +155,7 @@ export async function renderChart(input, args, exec) {
         signal: exec.signal,
     });
     const pathOf = (name) => written.find((file) => file.name === name)?.path ?? `${dir}/${name}`;
-    // 序列旁路：把 series.json 的**绝对路径**登记给 host 平面路由，客户端凭 chart_url 取数。
-    // 登记失败（服务缺失/实现异常）不阻断出图——图已经落盘了，降级成"只有文件路径"。
+    // Register the absolute series.json path with the host route; failure degrades to file paths only.
     let chartUrl = null;
     const seriesFile = written.find((file) => file.name === 'series.json');
     if (input.charts && seriesFile !== undefined) {
@@ -191,14 +183,11 @@ export async function renderChart(input, args, exec) {
         html_path: pathOf('chart.html'),
         created_at: generatedAt,
     });
-    // Direct unit callers that do not install the production registry still get
-    // a stable receipt; production apply() always injects the registry.
+    // Unit callers without the registry still get a stable receipt.
     const chartRef = artifact?.chart_ref ?? `chart_${chartId.slice(3)}`;
-    // 对话流呈现：把这张图登记为**用户正在看的那条会话**的本轮交付物
-    // （owner scope 与 chart_ref 同源，因此 specialist 出的图正好落在主会话）。
-    // 走官方 `deliverables/presented`——**不能**改回自定义事件类型：会话日志的事件词汇表
-    // 是闭集，非 first-party 类型会让整份会话在冷加载时打不开（事故记录见 src/chart/events.ts）。
-    // 事件不进模型消息历史。呈现通道可选：写不进去不影响图表产物与回执。
+    // Register as this turn's deliverable via first-party deliverables/presented — never a custom
+    // event type (closed vocabulary breaks cold load; see src/chart/events.ts). Owner scope matches
+    // chart_ref; these events never enter model message history.
     let deliverableTrace;
     try {
         const publisher = input.chartEvents?.();
@@ -219,10 +208,7 @@ export async function renderChart(input, args, exec) {
     catch (error) {
         deliverableTrace = `交付登记抛错（已吞掉，不影响出图）：${error instanceof Error ? error.message : String(error)}`;
     }
-    // 诊断落盘**默认关闭**：交付行"静默不出现"是最难查的故障（2026-09-20 连查四轮），
-    // 而宿主终端不总能拿到（cordis logger 只进内存），所以留一条可从磁盘定位的出口；
-    // 但它属于调试产物，不该出现在对外版本的 workspace 里。
-    // 需要时用 `CAPITAL_CHART_TRACE=1` 启动宿主，图表产物目录会多出 deliverable-trace.txt。
+    // Trace file only under CAPITAL_CHART_TRACE=1; a debugging aid, not a release artifact.
     if (chartTraceEnabled()) {
         try {
             await input.store.writeWorkspaceFiles({
@@ -233,7 +219,7 @@ export async function renderChart(input, args, exec) {
             });
         }
         catch {
-            // 诊断落盘失败不影响出图。
+            // Trace write failures never affect chart output.
         }
     }
     return {

package/lib/chart-render-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/chart-render` row: render_chart only. Row-level expression of "only the
+ * visualization specialist holds the chart pipeline"; shares token/artifact state with
+ * `tools/chart-source`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-chart-render-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/chart-render-entry.js

@@ -0,0 +1,17 @@
+import { createChartEventPublisher } from './chart/events.js';
+import { chartEventContextOf } from './chart/event-context.js';
+import { registerChartTool } from './chart/tool.js';
+import { capitalDatasetStore } from './runtime.js';
+import { capitalSharedRuntimeOf } from './chart-source-entry.js';
+export const name = 'capital-chart-render-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    const shared = capitalSharedRuntimeOf(ctx);
+    registerChartTool(ctx, {
+        store: capitalDatasetStore(ctx),
+        sourceTokens: shared.sourceTokens,
+        artifacts: shared.artifacts,
+        charts: () => ctx.get('capitalCharts'),
+        chartEvents: () => createChartEventPublisher(chartEventContextOf(ctx)),
+    });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * `tools/chart-source` row: prepare_chart_source. The token store must be the same
+ * instance used by `tools/chart-render`; separate stores make `render_chart` always
+ * report `chart_source_expired` without throwing. Prefer the host-plane runtime, fall
+ * back to the root-keyed module cache.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type CapitalShared } from './runtime.js';
+export declare const name = "capital-chart-source-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+/** Host row first, root-keyed module cache as fallback (monolith carriers). */
+export declare function capitalSharedRuntimeOf(ctx: Context): CapitalShared;

package/lib/chart-source-entry.js

@@ -0,0 +1,20 @@
+import { registerChartSourceTool } from './chart/source-token.js';
+import { capitalDatasetStore, capitalSharedRuntime } from './runtime.js';
+export const name = 'capital-chart-source-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    const shared = capitalSharedRuntimeOf(ctx);
+    registerChartSourceTool(ctx, { store: capitalDatasetStore(ctx), tokens: shared.sourceTokens });
+}
+/** Host row first, root-keyed module cache as fallback (monolith carriers). */
+export function capitalSharedRuntimeOf(ctx) {
+    try {
+        const hostShared = ctx.get('capitalChartRuntime');
+        if (hostShared !== undefined)
+            return hostShared;
+    }
+    catch {
+        // Monolith carrier without the host row.
+    }
+    return capitalSharedRuntime(ctx);
+}

package/lib/collect-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/collect` row: request_data / list_capabilities / describe_capability /
+ * dc_status backed by hub + 128 sources. The preset isolates hub/store to this row;
+ * time tools live in `tools/time`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-collect-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/collect-entry.js

@@ -0,0 +1,10 @@
+import { createCollectorRuntime } from './collector-runtime.js';
+import { registerDataCollectorTools } from './data-collector/tools.js';
+import { readCollectorConfig } from './capital-settings.js';
+export const name = 'capital-collect-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    const config = readCollectorConfig(ctx);
+    const { hub, diagnostics } = createCollectorRuntime(ctx, config);
+    registerDataCollectorTools(ctx, hub, diagnostics);
+}

package/lib/collector-runtime.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared data_collector assembly (store + hub + 128 sources). Both `tools/collect` and
+ * the monolith need it; duplicating would drift capability registration, credential
+ * probes and time tools. Collector domain only — no dataset/chart/watchlist tools.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { provideDataCollectorHub } from './data-collector/hub.js';
+import { type DataCollectorDiagnostics } from './data-collector/tools.js';
+import { capitalDatasetStore } from './runtime.js';
+export interface CollectorConfig {
+    fuyaoCredentialRef?: string;
+    ftshareCredentialRef?: string;
+    /** Flat projection of `retriever.windDocs.credentialRef`. */
+    windCredentialRef?: string;
+}
+export interface CollectorRuntime {
+    store: ReturnType<typeof capitalDatasetStore>;
+    hub: ReturnType<typeof provideDataCollectorHub>;
+    /** Injected into `dc_status` by the caller that owns the `tools/collect` row. */
+    diagnostics: DataCollectorDiagnostics;
+}
+export declare function createCollectorRuntime(ctx: Context, config?: CollectorConfig): CollectorRuntime;

package/lib/collector-runtime.js

@@ -0,0 +1,97 @@
+import { provideDataCollectorHub } from './data-collector/hub.js';
+import { capitalDatasetStore } from './runtime.js';
+import { rootPolicyProbes } from './agents/root-tool-policy.js';
+import { rolePolicyProbes } from './agents/role-tool-policy.js';
+import { createTencentSources } from './sources/tencent-http.js';
+import { createEastmoneySources } from './sources/eastmoney-http.js';
+import { createFuyaoRestSources, resolveFuyaoApiKey } from './sources/fuyao-rest.js';
+import { createFtshareSources, resolveFtshareApiKey } from './sources/ftshare-rest.js';
+import { createWindSources } from './sources/wind-mcp.js';
+import { createWindCredentialResolver } from './retriever-runtime.js';
+function diagnosticsFor(ctx, config) {
+    const fuyaoCredentialRef = config.fuyaoCredentialRef || 'FUYAO_API_KEY';
+    return {
+        probeApiKey: async () => {
+            try {
+                const credentials = ctx.get('credentials');
+                if (credentials?.resolve) {
+                    const resolved = await credentials.resolve(fuyaoCredentialRef);
+                    if (resolved?.value)
+                        return { present: true, source: resolved.source ?? `credentials(${fuyaoCredentialRef})` };
+                }
+                const processLike = globalThis.process;
+                if (processLike?.env?.[fuyaoCredentialRef])
+                    return { present: true, source: `env(${fuyaoCredentialRef})` };
+                return { present: false, source: null };
+            }
+            catch (error) {
+                return { present: false, source: null, error: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        // dc_status readout for root/role convergence; desktop does not persist host logs.
+        // Keep the real session shape: opened root and delegated child converge differently.
+        rootPolicy: () => [
+            ...rootPolicyProbes().map((probe) => ({ ...probe, allowed: [] })),
+            ...rolePolicyProbes().map((probe) => ({
+                agentId: probe.agentId,
+                root: probe.root,
+                presetId: probe.presetId,
+                outcome: probe.outcome,
+                // Roles have no allow-list (family rows define the surface); report sibling
+                // denials and call-level guard rejections.
+                allowed: [],
+                denied: probe.denied,
+                failed: probe.failed,
+            })),
+        ],
+    };
+}
+/** Registers all 128 sources; registration is structural, credentials resolve per call. */
+function registerSources(ctx, hub, config) {
+    ctx.effect(() => {
+        const sources = createTencentSources();
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个腾讯数据源（tencent_*）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.tencent-sources()');
+    ctx.effect(() => {
+        const sources = createEastmoneySources();
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个东方财富数据源（eastmoney_*）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.eastmoney-sources()');
+    ctx.effect(() => {
+        const sources = createFuyaoRestSources(() => resolveFuyaoApiKey(ctx, config.fuyaoCredentialRef || 'FUYAO_API_KEY'));
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个同花顺数据源（key 每次调用现取）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.fuyao-sources()');
+    ctx.effect(() => {
+        const sources = createFtshareSources(() => resolveFtshareApiKey(ctx, config.ftshareCredentialRef || 'FTSHARE_API_KEY'));
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个 FTShare 数据源（ftshare_*，key 每次调用现取）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.ftshare-sources()');
+    const wind = createWindCredentialResolver(ctx, config.windCredentialRef);
+    ctx.effect(() => {
+        const sources = createWindSources(wind.resolve);
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个 Wind 数据源（wind_*，与 wind_docs 共用 ${wind.credentialRef}）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.wind-sources()');
+}
+export function createCollectorRuntime(ctx, config = {}) {
+    const store = capitalDatasetStore(ctx);
+    // The collector preset isolates these services; keep them in the realm to avoid
+    // process-wide name collisions across presets.
+    ctx.provide('datasetStore', store);
+    const hub = provideDataCollectorHub(ctx, { store });
+    registerSources(ctx, hub, config);
+    // Builds runtime only; model tools belong to the `tools/collect` and `tools/time` rows.
+    return { store, hub, diagnostics: diagnosticsFor(ctx, config) };
+}

package/lib/data-collector/args.d.ts

@@ -1,38 +1,20 @@
 /**
- * Dataset 工具边界的**宽容参数解析**。
- *
- * 模型经常把数组/对象参数序列化成 JSON 字符串再传（实测：`"select": "[\"date_ms\"]"`、
- * `"group_by": "[]"`、`"aggregates": "[{...}]"`、`"limit": "1"`），于是参数其实是对的，
- * 却报 `query_spec_invalid: select must contain 1-32 column names`，模型只能反复试错。
- *
- * 这里在**工具边界**做一次宽容解析，查询引擎本身保持严格：能解析成正确类型就放行，
- * 解析不了就原样交给校验器报错（错误信息仍指向真实问题）。
- *
- * 本模块由 `query_dataset`（dataset-tools.ts）与 `describe_dataset`（describe.ts）共用，
- * 保证两个工具对同一种"字符串化的 JSON"给出**完全一致**的宽容度——两份实现漂移会让模型
- * 在换工具后重新踩同一个坑。
+ * Lenient parameter parsing at the Dataset tool boundary: models often send stringified JSON.
+ * Shared by query_dataset and describe_dataset so both accept exactly the same shapes.
  */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function parseJsonContainer(value: unknown): unknown;
-/** 列名数组：接受真数组、JSON 数组字符串，或单个列名字符串。 */
+/** Accept a real array, a JSON array string, or a single column name. */
 export declare function coerceNameList(value: unknown): unknown;
-/** 对象数组：接受真数组、JSON 数组字符串，或单个对象（对象本身或其 JSON 字符串）。 */
 export declare function coerceObjectList(value: unknown): unknown;
 export declare function coerceLimit(value: unknown): unknown;
 export declare const QUERY_NAME_LIST_FIELDS: readonly ["select", "group_by"];
 export declare const QUERY_OBJECT_LIST_FIELDS: readonly ["filters", "aggregates", "order_by"];
-/** 把 QuerySpec 的数组/对象字段与 limit 统一解析成引擎期望的类型（不改其余字段）。 */
+/** Coerce QuerySpec array/object fields and limit to engine types; leave other fields untouched. */
 export declare function coerceQueryShape(input: Record<string, unknown>): Record<string, unknown>;
-/** dataset_id 的形态校验；不合法一律在工具边界抛错，绝不带进 store。 */
+/** Reject an invalid dataset_id at the tool boundary; never pass it to the store. */
 export declare function readDatasetId(value: unknown): string;
-/** task_id 是可选元数据：空值等同于未提供，只做长度上限校验。 */
 export declare function readOptionalTaskId(value: unknown): string | undefined;
-/** 可选的字符串参数（time_column / primary_key）：非字符串一律视为未提供。 */
 export declare function readOptionalString(value: unknown): string | undefined;
-/**
- * 列名过滤参数（describe_dataset 的 `columns_of_interest`）。
- *
- * 接受真数组 / JSON 数组字符串 / 单个列名字符串；解析结果不是数组就抛错——静默忽略一个
- * 写错的过滤条件会让模型以为"结果已经收窄"，而实际返回的是全量（或反过来），所以这里响亮失败。
- */
+/** columns_of_interest: accept array/JSON/single name; a wrong shape fails loudly rather than silently widening results. */
 export declare function readOptionalColumnList(value: unknown): string[] | undefined;

package/lib/data-collector/args.js

@@ -1,17 +1,7 @@
 import { DatasetStoreError } from './store.js';
 /**
- * Dataset 工具边界的**宽容参数解析**。
- *
- * 模型经常把数组/对象参数序列化成 JSON 字符串再传（实测：`"select": "[\"date_ms\"]"`、
- * `"group_by": "[]"`、`"aggregates": "[{...}]"`、`"limit": "1"`），于是参数其实是对的，
- * 却报 `query_spec_invalid: select must contain 1-32 column names`，模型只能反复试错。
- *
- * 这里在**工具边界**做一次宽容解析，查询引擎本身保持严格：能解析成正确类型就放行，
- * 解析不了就原样交给校验器报错（错误信息仍指向真实问题）。
- *
- * 本模块由 `query_dataset`（dataset-tools.ts）与 `describe_dataset`（describe.ts）共用，
- * 保证两个工具对同一种"字符串化的 JSON"给出**完全一致**的宽容度——两份实现漂移会让模型
- * 在换工具后重新踩同一个坑。
+ * Lenient parameter parsing at the Dataset tool boundary: models often send stringified JSON.
+ * Shared by query_dataset and describe_dataset so both accept exactly the same shapes.
  */
 export function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -29,7 +19,7 @@ export function parseJsonContainer(value) {
         return undefined;
     }
 }
-/** 列名数组：接受真数组、JSON 数组字符串，或单个列名字符串。 */
+/** Accept a real array, a JSON array string, or a single column name. */
 export function coerceNameList(value) {
     if (Array.isArray(value))
         return value;
@@ -43,7 +33,6 @@ export function coerceNameList(value) {
     }
     return value;
 }
-/** 对象数组：接受真数组、JSON 数组字符串，或单个对象（对象本身或其 JSON 字符串）。 */
 export function coerceObjectList(value) {
     if (Array.isArray(value))
         return value;
@@ -64,7 +53,7 @@ export function coerceLimit(value) {
 }
 export const QUERY_NAME_LIST_FIELDS = ['select', 'group_by'];
 export const QUERY_OBJECT_LIST_FIELDS = ['filters', 'aggregates', 'order_by'];
-/** 把 QuerySpec 的数组/对象字段与 limit 统一解析成引擎期望的类型（不改其余字段）。 */
+/** Coerce QuerySpec array/object fields and limit to engine types; leave other fields untouched. */
 export function coerceQueryShape(input) {
     const shape = { ...input };
     for (const field of QUERY_NAME_LIST_FIELDS)
@@ -77,14 +66,13 @@ export function coerceQueryShape(input) {
         shape.limit = coerceLimit(shape.limit);
     return shape;
 }
-/** dataset_id 的形态校验；不合法一律在工具边界抛错，绝不带进 store。 */
+/** Reject an invalid dataset_id at the tool boundary; never pass it to the store. */
 export function readDatasetId(value) {
     if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
         throw new DatasetStoreError('dataset_id_invalid', 'dataset_id is invalid');
     }
     return value;
 }
-/** task_id 是可选元数据：空值等同于未提供，只做长度上限校验。 */
 export function readOptionalTaskId(value) {
     if (value === undefined || value === null || value === '')
         return undefined;
@@ -93,16 +81,10 @@ export function readOptionalTaskId(value) {
     }
     return value;
 }
-/** 可选的字符串参数（time_column / primary_key）：非字符串一律视为未提供。 */
 export function readOptionalString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
-/**
- * 列名过滤参数（describe_dataset 的 `columns_of_interest`）。
- *
- * 接受真数组 / JSON 数组字符串 / 单个列名字符串；解析结果不是数组就抛错——静默忽略一个
- * 写错的过滤条件会让模型以为"结果已经收窄"，而实际返回的是全量（或反过来），所以这里响亮失败。
- */
+/** columns_of_interest: accept array/JSON/single name; a wrong shape fails loudly rather than silently widening results. */
 export function readOptionalColumnList(value) {
     if (value === undefined || value === null || value === '')
         return undefined;

package/lib/data-collector/dataset-tools.d.ts

@@ -1,3 +1,9 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { WorkspaceDatasetStore } from './store.js';
-export declare function registerDatasetTools(ctx: Context, store: WorkspaceDatasetStore): void;
+/**
+ * Dataset read family. writeProfile is off by default: profiles are host-computed, and the tool is
+ * absent from every family row; the monolithic entry opts in explicitly.
+ */
+export declare function registerDatasetTools(ctx: Context, store: WorkspaceDatasetStore, options?: {
+    writeProfile?: boolean;
+}): void;