@v587d/capital-generation 2.8.3 → 2.9.1

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;

package/lib/data-collector/dataset-tools.js

@@ -2,7 +2,8 @@ import { MAX_QUERY_AGGREGATES, MAX_QUERY_FILTERS, MAX_QUERY_GROUP_BY, MAX_QUERY_
 import { coerceQueryShape, isRecord, parseJsonContainer, readDatasetId, readOptionalTaskId, } from './args.js';
 import { MAX_DESCRIBE_QUERIES, SAFE_RESULT_CHARS, describeDataset, normalizeDescribeArgs, } from './describe.js';
 import { normalizeQueryDates, withIsoTimeColumns } from './query-time.js';
-import { delegatedSession } from '../tool-exec.js';
+import { authorizedSession } from '../tool-exec.js';
+import { DATASET_READING_PRESET_IDS } from '../preset-ids.js';
 const jsonObject = (properties = {}, required = []) => ({
     type: 'object',
     properties,
@@ -104,27 +105,15 @@ function tool(name, description, parameters, schema, execute, options = {}) {
         parameters,
         output: { schema, render },
         execute,
-        // `isConcurrencySafe` 是框架的**现成机制**：为 true 时，同一个 assistant 步里的多个调用
-        // 会被放进有界并发池（默认上限 10），结果仍按模型顺序在**同一个下一步**一起返回。
-        // 这正是 describe_dataset 省往返的手段——多个 dataset 由模型一次发完，而不是把 N 份结果
-        // 合并成一个超长载荷（见 docs/design/describe-dataset-design.md §2.1）。
-        // 宿主侧是 **fail-closed**，两版源码同为「没有这个函数就 exclusive」；2026-10-16 用一次性
-        // headless 探针在真机核过（账本 L30）：两颗除声明与否外逐字相同的工具，三颗**已声明**在
-        // 1 毫秒内一起派发、整批 706 毫秒；三颗**未声明**严格 call→result 交替、整批 1426 毫秒。
-        // ⚠ 混发会把已声明的那颗拖回串行（池在遇到第一颗未声明调用处断开），所以"要不要标"是
-        // 按**工具**定的、不是按**这一次批次**定的：见下面 query_dataset 那条刻意不标的理由。
+        // Framework concurrency pool: multiple calls in one assistant step run together and return
+        // in the same next step. Mixed batches fall back to serial, so this is per-tool, not per-call.
         ...(options.concurrencySafe === true ? { isConcurrencySafe: () => true } : {}),
     };
 }
 /**
- * 模型经常把数组/对象参数序列化成 JSON 字符串再传（实测：`"select": "[\"date_ms\"]"`、
- * `"group_by": "[]"`、`"aggregates": "[{...}]"`、`"limit": "1"`），于是参数其实是对的，
- * 却报 `query_spec_invalid: select must contain 1-32 column names`，模型只能反复试错。
- *
- * 宽容解析原语已外迁到 src/data-collector/args.ts：`query_dataset` 与 `describe_dataset`
- * 必须共用同一套解析（两份实现漂移会让模型在换工具后重新踩同一个坑）。
+ * Lenient boundary parsing for stringified JSON arrays/objects, shared with describe.ts; the query
+ * engine itself stays strict so migration between tools cannot change behavior.
  */
-/** envelope 自身的元数据字段，不属于 QuerySpec；模型按协议原样传 envelope 时忽略它们。 */
 const QUERY_ENVELOPE_FIELDS = ['type', 'task_id', 'time_column'];
 function normalizeQueryArgs(args) {
     const outerDatasetId = readDatasetId(args.dataset_id);
@@ -244,27 +233,14 @@ const querySpecProperties = {
     error_policy: { type: 'string', enum: ['strict', 'skip_with_warning'] },
 };
 const querySpecSchema = jsonObject(querySpecProperties);
-/** envelope 形态独有的三个字段；flat 形态把它们视为 QuerySpec 之外的元数据。 */
 const queryEnvelopeProperties = {
     type: { type: 'string', enum: ['query_request'], description: '可选：声明使用 query_request envelope 形态' },
     task_id: { type: 'string' },
     query: querySpecSchema,
 };
 /**
- * 工具参数 schema 的根**只能**是 `{ type: 'object', properties, required }`。
- *
- * 事故（2026-09-14）：这里原本是根级 `{ oneOf: [flat, envelope] }`，没有 `type`。
- * 模型供应商在请求进入时就整体校验 `tools[].function.parameters`，直接返回
- * `Invalid schema for function 'query_dataset': schema must be a JSON Schema of
- * 'type: "object"', got 'type: null'`（HTTP 400）。这一步发生在模型生成第一个
- * token 之前，而这套工具表在会话组作用域里**主 Agent 也带着**，于是每个 Capital
- * 会话都在第 1 轮第 1 步整体失败，与用户问什么无关。
- *
- * flat 与 envelope 的判定本来就在工具边界由 normalizeQueryArgs 完成（query 存在即
- * envelope），所以 schema 用「一个对象 + 两边字段都列出（都非必需，dataset_id 除外）」
- * 描述即可——这比根级 oneOf 更准确：oneOf 的两个分支都带 additionalProperties:false，
- * 混合传参（如 query + limit）在任何分支下都不合法，而宿主其实接受。
- * 回归测试：test/apply-integration.test.mjs（所有注册工具的 parameters 根必须是 object）。
+ * Root parameters must be a single object: a root-level oneOf makes providers return HTTP 400
+ * before the first token. Both forms are distinguished at the boundary, so list both field sets.
  */
 const queryParametersSchema = jsonObject({
     ...querySpecProperties,
@@ -282,12 +258,8 @@ const queryResultSchema = jsonObject({
     warnings: { type: 'array', items: { type: 'string' } },
 }, ['dataset_id', 'columns', 'rows', 'matched_row_count', 'group_count', 'returned_count', 'limit', 'warnings']);
 /**
- * `describe_dataset` 的参数：**一次只处理一个 dataset_id**。
- *
- * 多个 dataset 由模型在**同一条 assistant 消息**里发多个调用完成——本工具声明了
- * `isConcurrencySafe`，框架会把它们放进并发池，N 份结果在同一个下一步一起返回。
- * 因此这里刻意**不**接受 `dataset_ids` 数组：把 N 份结果合并成一个工具结果，才是
- * 体积预算/digest 那套复杂机制的来源（见 docs/design/describe-dataset-design.md §2.1）。
+ * One dataset_id per call; multiple datasets go as multiple calls in one assistant message.
+ * Merging them into one result is what the size budget exists to avoid.
  */
 const describeParametersSchema = jsonObject({
     dataset_id: datasetIdSchema,
@@ -302,11 +274,7 @@ const describeQueryOutcomeSchema = jsonObject({
     result: queryResultSchema,
     error: jsonObject({ code: { type: 'string' }, detail: { type: 'string' } }, ['code', 'detail']),
 }, ['index']);
-/**
- * 输出覆盖两种形态：正常结果（`status: 'ok'`）与体积闸门回执（`status: 'too_large'`）。
- * 根必须是单一 object（根级 oneOf 会被供应商 400 拒绝，见上面 query_dataset 的事故注释），
- * 所以两边的字段都列出来、都非必需，只有 `status` 与 `dataset_id` 恒有。
- */
+/** Single object root, listing both ok and too_large fields (root oneOf is rejected by providers). */
 const describeResultSchema = jsonObject({
     status: { type: 'string', enum: ['ok', 'too_large'] },
     dataset_id: { type: 'string' },
@@ -342,39 +310,41 @@ const describeResultSchema = jsonObject({
     validation: profileValidationSchema,
     warnings: { type: 'array', items: { type: 'string' } },
     queries: { type: 'array', items: describeQueryOutcomeSchema },
-    /** 仅 too_large：被拦下的形状、字节数、体积归因与重试指引。 */
+    /** Only for too_large: blocked shape, byte counts, attribution and retry hint. */
     shape: { type: 'string', enum: ['array', 'envelope_item', 'document', 'none'] },
     bytes: { type: 'integer' },
     facts_bytes: { type: 'integer' },
     queries_bytes: { type: 'integer' },
     hint: { type: 'string' },
 }, ['status', 'dataset_id']);
-export function registerDatasetTools(ctx, store) {
+/**
+ * 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 function registerDatasetTools(ctx, store, options = {}) {
     const tools = ctx.get('tools');
     if (!tools)
         return;
     const registrations = [
-        tool('inspect_dataset', '读取当前 session 已授权 Dataset 的元数据和可读性。只返回 DatasetRef 与可读性信息，不返回原始 rows，也不接受任何文件路径。query_access.shape 取值：array / envelope_item = 行集合，可 profile 也可 query；document = 顶层是文档对象（财务指标、回测结果这类），可 profile（宿主给结构摘要与有界内容）但不能 query；none = 不可读，reason 说明原因。批量描述多份 Dataset 请用 describe_dataset（一次一份、可并发）；本工具用于单点复核。', jsonObject({ dataset_id: datasetIdSchema }, ['dataset_id']), datasetRefWithAccessSchema, async (args, exec) => store.inspectDataset(readDatasetId(args.dataset_id), delegatedSession(exec, 'inspect_dataset'), exec.signal)),
+        tool('inspect_dataset', '读取当前 session 已授权 Dataset 的元数据和可读性。只返回 DatasetRef 与可读性信息，不返回原始 rows，也不接受任何文件路径。query_access.shape 取值：array / envelope_item = 行集合，可 profile 也可 query；document = 顶层是文档对象（财务指标、回测结果这类），可 profile（宿主给结构摘要与有界内容）但不能 query；none = 不可读，reason 说明原因。批量描述多份 Dataset 请用 describe_dataset（一次一份、可并发）；本工具用于单点复核。', jsonObject({ dataset_id: datasetIdSchema }, ['dataset_id']), datasetRefWithAccessSchema, async (args, exec) => store.inspectDataset(readDatasetId(args.dataset_id), authorizedSession(ctx, exec, 'inspect_dataset', DATASET_READING_PRESET_IDS), exec.signal)),
         tool('profile_dataset', `由宿主读取 Dataset 并返回基础质量检查与四类事实；原始 rows 不进入模型上下文。行集合返回：① schema/quality——字段 observed/contract 类型、missing/null/invalid 计数、重复行、时间顺序；② statistics——数值字段的 count/sum/min/max/mean/分位数；③ categories——字符串字段的 distinct_count 与最多 5 个高频取值（truncated=true 表示未列全）；④ time_facts——时间列覆盖范围与首行/末行的数值取值（回答"最新值、区间涨跌"必须用它，不要用 min/max 代替首末值）；⑤ structure——行内数组/对象的路径摘要（对象字段用 .name、数组元素用 []；未抽样时用 total_elements，超过 50 项时用 sampled_elements，后者明确表示只是抽样，不能据此回答完整数量）。文档型 Dataset（顶层是文档对象，没有行数组）返回 structure 结构摘要 + document 有界内容，不返回行列统计。time_column 可显式指定，省略时按列名候选并只在取值全为数字或日期样式时采用。不接受任何文件路径、脚本内容或额外 schema。批量描述请用 describe_dataset（一次一份、可并发）；本工具用于单点复核或补取一份完整 profile。`, jsonObject({
             dataset_id: datasetIdSchema,
             task_id: { type: 'string' },
             time_column: { type: 'string' },
             primary_key: { type: 'string' },
         }, ['dataset_id']), profileDatasetResultSchema, async (args, exec) => store.profileDataset({
-            session: delegatedSession(exec, 'profile_dataset'),
+            session: authorizedSession(ctx, exec, 'profile_dataset', DATASET_READING_PRESET_IDS),
             dataset_id: readDatasetId(args.dataset_id),
             task_id: readOptionalTaskId(args.task_id),
             time_column: typeof args.time_column === 'string' ? args.time_column : undefined,
             primary_key: typeof args.primary_key === 'string' ? args.primary_key : undefined,
             signal: exec.signal,
         })),
-        // 刻意**不**标并发安全（与 describe_dataset 相反，且这是量出来的）：真会话里 query_dataset
-        // 单颗中位 17 毫秒（25 次样本），一次消息发 6 颗串行也只多付约 85 毫秒；而它的成本主体是
-        // 读 raw.json 后的 `JSON.parse` + 聚合，Node 单线程下这部分**并发也不会重叠**，标了买不到什么。
-        // 多份数据 / 多条查询的诉求已经由 describe_dataset 的 `queries` 承接（那颗标了）。
+        // Deliberately not concurrency-safe: parsing raw.json and aggregating is CPU-bound on Node's
+        // single thread, so parallel calls cannot overlap; describe_dataset covers multi-query needs.
         tool('query_dataset', `对当前 session 已授权的 json_rows Dataset 执行固定 QuerySpec：参数是一个 JSON 对象，QuerySpec 字段既可平铺在根上（flat），也可整体放进 query（query_request envelope，宿主自动展开）；两种形态同时给出时以 query 为准。支持受限 filter、group_by、count/min/max/avg/sum、asc/desc 和 limit。必须返回聚合或分组结果，禁止原始行投影；select 可省略，默认返回分组列和聚合别名。默认 error_policy=skip_with_warning，脏值会被排除并在 warnings 披露；需要全量类型一致性时显式使用 strict。**时间筛选直接写日期**：时间列（如 date_ms）的 filter 值可写 "2026-08-23" / "2026-08" / "2026" 或 {period:"last_3_months"}（period 省略锚点时以该 Dataset 最后一天为准），宿主按该列自身的时区偏移换算成边界，不要自己算毫秒；日期写法配 >、<、!= 无意义会报 query_type_conflict（用 >= / <= / =）。结果里时间列会附 *_iso 可读日期。最多 ${MAX_QUERY_FILTERS} 个条件、${MAX_QUERY_GROUP_BY} 个分组列、${MAX_QUERY_AGGREGATES} 个聚合、${MAX_QUERY_LIMIT} 行，结果最多 ${MAX_QUERY_OUTPUT_BYTES} 字节。数值字符串只在 Dataset schema 明确为 number/integer 时兼容。query_dataset 是受控分组/聚合工具，不是通用 raw.json 读取或自定义分析工具：select 只能引用 group_by 列或聚合别名，取不到原始行（首末/最新值请用 profile 的 time_facts）。select/group_by/aggregates/order_by 请传真正的 JSON 数组（宿主也兼容 JSON 字符串，但不要依赖）。若还要 profile/元数据，可用 describe_dataset 的 queries 参数一次拿到；本工具用于单点补查。`, queryParametersSchema, queryResultSchema, async (args, exec) => {
             const normalized = normalizeQueryArgs(args);
-            const session = delegatedSession(exec, 'query_dataset');
+            const session = authorizedSession(ctx, exec, 'query_dataset', DATASET_READING_PRESET_IDS);
             const timeColumn = typeof args.time_column === 'string' && args.time_column.length > 0 ? args.time_column : undefined;
             const prepared = await normalizeQueryDates({
                 store,
@@ -396,11 +366,11 @@ export function registerDatasetTools(ctx, store) {
         }),
         tool('describe_dataset', `读取一份 Dataset 的**默认入口**：一次调用完成 inspect（元数据与可读性/形状）、profile（宿主算基础质量与四类事实，写入 profile_ref）与受控 query（可选）；原始 rows 不进入模型上下文。一次只处理一个 dataset_id——本轮有多份数据时，请在**同一条消息里一次发出多个调用**（本工具可并发执行，结果会一起返回），不要一份一份等。行集合返回：① 元数据 artifact_ref/capability/source_label/captured_at/retention_until 与 query_access.shape（array / envelope_item = 行集合；document = 顶层文档对象，只能 profile，queries 由宿主跳过）；② profile 四类事实——statistics（count/sum/min/max/mean/分位数）、categories（distinct + 最多 5 个高频取值）、time_facts（覆盖范围与首行/末行取值；回答"最新值、区间涨跌"必须用它，不要用 min/max 代替）、structure（嵌套路径摘要）；③ queries——每条的 QueryResult，或该条自己的 error（单条失败不影响其余）。columns_of_interest 只对这些列返回 statistics/categories/schema（并同样收窄 time_facts 的首末值投影，时间列永远保留），是收窄结果体积的唯一手段。结果超过 ${SAFE_RESULT_CHARS} 码点时宿主不返回超长载荷，而返回 {status:'too_large', profile_ref, columns, bytes, facts_bytes, queries_bytes, hint}：facts_bytes/queries_bytes 是体积归因（哪边大砍哪边），按 hint 重发一次即可——queries 大就先去掉 queries（聚合改单独走 query_dataset），facts 大就用 columns_of_interest 收窄列（或减少 queries，最多 ${MAX_DESCRIBE_QUERIES} 条）。单点复核仍可用 inspect_dataset / profile_dataset / query_dataset；不接受任何文件路径、脚本内容或自定义表达式。`, describeParametersSchema, describeResultSchema, async (args, exec) => describeDataset({
             store,
-            session: delegatedSession(exec, 'describe_dataset'),
+            session: authorizedSession(ctx, exec, 'describe_dataset', DATASET_READING_PRESET_IDS),
             request: normalizeDescribeArgs(args),
             signal: exec.signal,
         }), 
-        // 让"同一条消息里的多个 describe_dataset"进框架并发池：这是省往返的机制本身。
+        // This is the mechanism that saves round trips: multiple describes run in one pool.
         { concurrencySafe: true }),
         tool('write_profile', '将当前 session 对已授权 Dataset 生成的基础质量 profile 持久化到 workspace。宿主生成不可变 profile_ref；profile 不得包含原始 rows、文件路径、凭据或未定义字段。', jsonObject({
             dataset_id: datasetIdSchema,
@@ -419,14 +389,15 @@ export function registerDatasetTools(ctx, store) {
                 warnings: { type: 'array', items: { type: 'string' } },
             }, ['row_count', 'columns', 'quality', 'warnings']),
         }, ['dataset_id', 'profile']), profileRefSchema, async (args, exec) => store.writeProfile({
-            session: delegatedSession(exec, 'write_profile'),
+            session: authorizedSession(ctx, exec, 'write_profile', DATASET_READING_PRESET_IDS),
             dataset_id: readDatasetId(args.dataset_id),
             task_id: readOptionalTaskId(args.task_id),
             profile: args.profile,
             signal: exec.signal,
         })),
     ];
-    for (const definition of registrations) {
+    const withWriteProfile = options.writeProfile === true;
+    for (const definition of registrations.filter((item) => withWriteProfile || item.name !== 'write_profile')) {
         ctx.effect(() => tools.register(definition), `capital-generation.dataset-tool(${definition.name})`);
     }
 }

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

@@ -1,37 +1,20 @@
 import { type DatasetInspection, type ProfileDatasetResult, type SessionLike, type WorkspaceDatasetStore } from './store.js';
 import { type QueryResult, type QuerySpec } from './query.js';
 /**
- * `describe_dataset`：把「inspect_dataset → profile_dataset →（可选）query_dataset」三次调用
- * 合成**一次**（每份 Dataset 一次），供 data_junior 使用。
- *
- * 设计要点（完整理由见 docs/design/describe-dataset-design.md）：
- *
- * 1. **一次调用只处理一个 dataset**。多个 dataset 由模型在**同一条 assistant 消息**里发多个
- *    调用完成——工具声明了 `isConcurrencySafe`，框架会把它们放进并发池，N 份结果在同一个
- *    下一步一起返回。因此**不需要**把 N 份结果合并成一个超长载荷，也就不需要任何
- *    digest / 公平份额 / 裁剪阶梯：单份结果的体积与今天"inspect + profile 两次结果之和"同量级。
- * 2. **形状分支由宿主做**：document 型 Dataset 直接跳过 queries，不再依赖模型先 inspect 再判断。
- * 3. **唯一的体积闸门** {@link SAFE_RESULT_CHARS}：序列化后超过它就不返回超长载荷，改返回
- *    一个小回执（含全部列名与 profile_ref），让模型用 `columns_of_interest` 收窄后重发。
- *    把"剪枝器静默截断"变成"响亮且可操作的重试"，而不是在宿主里做内容改写。
- * 4. **不碰读权限**：一切仍走 store 的受控方法，原始 rows 不进任何 Agent 上下文。
- */
-/**
- * 单份结果的码点上限。preset 的工具结果剪枝阈值是 8192（head 4096 + tail 1024，按码点），
- * 这里取 7000 留出余量：超过 8192 会被剪掉中间段，而"被剪"与"被本闸门拦下"的区别是
- * **后者会让模型知道发生了什么并给出重试办法**。
+ * `describe_dataset`: inspect + profile + optional query in one call per Dataset. A single size gate
+ * (SAFE_RESULT_CHARS) returns a small retryable receipt instead of letting the pruner truncate.
  */
+/** Cap below the preset's 8192 prune threshold: overflow is loud and retryable instead of silently clipped. */
 export declare const SAFE_RESULT_CHARS = 7000;
-/** 单次调用的 queries 条数上限：防的是请求体积，不是结果体积（结果另有闸门）。 */
+/** Request-size cap, not a result-size cap. */
 export declare const MAX_DESCRIBE_QUERIES = 8;
 export interface DescribeRequest {
     dataset_id: string;
     task_id?: string;
     time_column?: string;
     primary_key?: string;
-    /** 只对这些列返回 statistics / categories / schema；省略即全量。 */
+    /** Restrict statistics/categories/schema to these columns; omitted means all. */
     columns_of_interest?: string[];
-    /** 受控 QuerySpec 列表；`dataset_id` 由管线补成当前 dataset。 */
     queries: QuerySpec[];
 }
 export interface DescribeQueryOutcome {
@@ -77,18 +60,13 @@ export interface DescribeTooLarge {
     shape: DatasetInspection['query_access']['shape'];
     columns: string[];
     bytes: number;
-    /** 体积归因：facts（元数据 + profile 事实块）部分的码点数。 */
+    /** Size attribution: codepoints of facts vs queries, so the hint can name the bigger side. */
     facts_bytes: number;
-    /** 体积归因：queries（含各条 result）部分的码点数。 */
     queries_bytes: number;
     hint: string;
 }
 export type DescribeOutput = DescribeResult | DescribeTooLarge;
-/**
- * 工具边界归一化：宽容解析（字符串化的 JSON 数组/对象、单个对象、envelope 形态），
- * 引擎侧保持严格。与 `query_dataset` 的 `normalizeQueryArgs` 共用同一套解析原语
- * （src/data-collector/args.ts），避免两个工具的宽容度漂移。
- */
+/** Lenient boundary parsing, sharing primitives with query_dataset so both tools accept the same shapes. */
 export declare function normalizeDescribeArgs(args: Record<string, unknown>): DescribeRequest;
 export interface DescribeDatasetInput {
     store: WorkspaceDatasetStore;
@@ -96,8 +74,5 @@ export interface DescribeDatasetInput {
     request: DescribeRequest;
     signal?: AbortSignal;
 }
-/**
- * 单份 Dataset 的完整管线。失败一律抛错（`isError`）：单 dataset 调用里没有"部分成功"，
- * 把失败做成成功信封会让会话日志无法区分（见 docs/design/tool-result-error-signal.md）。
- */
+/** Fail loudly on any error: a single-dataset call has no partial success. */
 export declare function describeDataset(input: DescribeDatasetInput): Promise<DescribeOutput>;

package/lib/data-collector/describe.js

@@ -3,28 +3,12 @@ import { DatasetQueryError } from './query.js';
 import { normalizeQueryDates, withIsoTimeColumns } from './query-time.js';
 import { coerceQueryShape, isRecord, parseJsonContainer, readDatasetId, readOptionalColumnList, readOptionalString, readOptionalTaskId, } from './args.js';
 /**
- * `describe_dataset`：把「inspect_dataset → profile_dataset →（可选）query_dataset」三次调用
- * 合成**一次**（每份 Dataset 一次），供 data_junior 使用。
- *
- * 设计要点（完整理由见 docs/design/describe-dataset-design.md）：
- *
- * 1. **一次调用只处理一个 dataset**。多个 dataset 由模型在**同一条 assistant 消息**里发多个
- *    调用完成——工具声明了 `isConcurrencySafe`，框架会把它们放进并发池，N 份结果在同一个
- *    下一步一起返回。因此**不需要**把 N 份结果合并成一个超长载荷，也就不需要任何
- *    digest / 公平份额 / 裁剪阶梯：单份结果的体积与今天"inspect + profile 两次结果之和"同量级。
- * 2. **形状分支由宿主做**：document 型 Dataset 直接跳过 queries，不再依赖模型先 inspect 再判断。
- * 3. **唯一的体积闸门** {@link SAFE_RESULT_CHARS}：序列化后超过它就不返回超长载荷，改返回
- *    一个小回执（含全部列名与 profile_ref），让模型用 `columns_of_interest` 收窄后重发。
- *    把"剪枝器静默截断"变成"响亮且可操作的重试"，而不是在宿主里做内容改写。
- * 4. **不碰读权限**：一切仍走 store 的受控方法，原始 rows 不进任何 Agent 上下文。
- */
-/**
- * 单份结果的码点上限。preset 的工具结果剪枝阈值是 8192（head 4096 + tail 1024，按码点），
- * 这里取 7000 留出余量：超过 8192 会被剪掉中间段，而"被剪"与"被本闸门拦下"的区别是
- * **后者会让模型知道发生了什么并给出重试办法**。
+ * `describe_dataset`: inspect + profile + optional query in one call per Dataset. A single size gate
+ * (SAFE_RESULT_CHARS) returns a small retryable receipt instead of letting the pruner truncate.
  */
+/** Cap below the preset's 8192 prune threshold: overflow is loud and retryable instead of silently clipped. */
 export const SAFE_RESULT_CHARS = 7_000;
-/** 单次调用的 queries 条数上限：防的是请求体积，不是结果体积（结果另有闸门）。 */
+/** Request-size cap, not a result-size cap. */
 export const MAX_DESCRIBE_QUERIES = 8;
 function errorEnvelope(error) {
     if (error instanceof DatasetQueryError || error instanceof DatasetStoreError) {
@@ -33,29 +17,13 @@ function errorEnvelope(error) {
     }
     return { code: 'query_failed', detail: error instanceof Error ? error.message : String(error) };
 }
-/** 与剪枝器同口径：按 Unicode 码点量体积，不按 UTF-16 码元。 */
+/** Match the pruner: measure Unicode code points, not UTF-16 units. */
 function codePointLength(text) {
     return [...text].length;
 }
 /**
- * 丢掉值为 `undefined` 的自有属性。
- *
- * ⛔ 这是**必须**的收尾步骤，不是风格问题（2026-09-23 真机事故）：
- * DSH 用 `snapshotJsonValue`（`@deepseek-ai/dsh-util-values`）校验工具的**返回值**，
- * 规则是"无损 JSON"——任何自有属性值为 `undefined`（以及 NaN/Infinity/-0、数组空洞、
- * 非 plain 对象）都会让 `walkJsonValue` 返回 undefined，宿主随即抛
- * `ToolOutputError: tool "describe_dataset" returned invalid output: value is not lossless JSON`，
- * **整次调用作废**。
- *
- * 而 `JSON.stringify` 会**静默丢掉** undefined 属性，所以本地怎么自测都看不出来。
- * 实测（真机会话 42f42c9e）：同一批 5 次调用里 3 次失败——全是数值列的日线缺
- * `categories`、无数值列的 ticker_search 缺 `statistics`；而 quote 与 corporate_actions
- * 恰好两类列都有，所以成功。模型只看到一句"invalid output"，误判成列名不匹配，
- * 重试一次后回退到 inspect/profile 老路。
- *
- * `store.ts` 的 `buildProfile` 一直用"条件展开"（`...(有内容 ? { statistics } : {})`）避开这个坑；
- * 这里改成**单一收尾闸门**：内部怎么组装都行，出工具前一律过 `compact()`。
- * 回归断言见 test/describe-dataset.test.mjs 的 `assertLosslessJson()`。
+ * Strip own properties whose value is `undefined`: DSH validates tool output as lossless JSON and
+ * invalidates the whole call. JSON.stringify hides these, so local self-tests cannot catch them.
  */
 function compact(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
@@ -74,16 +42,12 @@ function normalizeQueryItem(value, index, datasetId) {
         throw new DatasetQueryError('query_spec_invalid', `queries[${index}].dataset_id must match the describe_dataset dataset_id`);
     }
     const shape = coerceQueryShape(source);
-    // envelope 与消息元数据不属于 QuerySpec；dataset_id 由管线按当前 dataset 补。
+    // Envelope and message metadata are not QuerySpec; dataset_id is filled by the pipeline.
     for (const field of ['type', 'task_id', 'dataset_id'])
         delete shape[field];
     return shape;
 }
-/**
- * 工具边界归一化：宽容解析（字符串化的 JSON 数组/对象、单个对象、envelope 形态），
- * 引擎侧保持严格。与 `query_dataset` 的 `normalizeQueryArgs` 共用同一套解析原语
- * （src/data-collector/args.ts），避免两个工具的宽容度漂移。
- */
+/** Lenient boundary parsing, sharing primitives with query_dataset so both tools accept the same shapes. */
 export function normalizeDescribeArgs(args) {
     const dataset_id = readDatasetId(args.dataset_id);
     const rawQueries = args.queries;
@@ -131,23 +95,14 @@ function restrictFacts(profile, columns, shape, warnings) {
         : Object.fromEntries(Object.entries(map).filter(([column]) => keep.has(column)));
     return { statistics: pick(profile.statistics), categories: pick(profile.categories), schema: pick(profile.schema), keep };
 }
-/**
- * `time_facts.first` / `last` 也按 `columns_of_interest` 收窄。
- *
- * 为什么不收窄是错的：该参数承诺"只对这些列返回事实"，而首末行投影**每个数值列都带一份**
- * （7 列日线 = 每个投影 7 个键），是 time_facts 里最占体积的部分。时间列本身永远保留：
- * 它是首末值的时间坐标，删了这两个投影就没有意义（实测整份 describe 里 time_facts 占 1320 字符）。
- */
+/** Narrow first/last projections too; the time column always stays or the projection loses its coordinate. */
 function restrictTimeFacts(facts, keep) {
     if (facts === undefined || keep === undefined)
         return facts;
     const pick = (row) => Object.fromEntries(Object.entries(row).filter(([column]) => column === facts.time_column || keep.has(column)));
     return { ...facts, first: pick(facts.first), last: pick(facts.last) };
 }
-/**
- * 单份 Dataset 的完整管线。失败一律抛错（`isError`）：单 dataset 调用里没有"部分成功"，
- * 把失败做成成功信封会让会话日志无法区分（见 docs/design/tool-result-error-signal.md）。
- */
+/** Fail loudly on any error: a single-dataset call has no partial success. */
 export async function describeDataset(input) {
     const { store, session, request, signal } = input;
     const inspection = await store.inspectDataset(request.dataset_id, session, signal);
@@ -172,10 +127,8 @@ export async function describeDataset(input) {
             warnings.push('document Dataset has no row array; queries were not executed');
     }
     else {
-        // 内嵌 queries 与 `query_dataset` 必须**完全同构**（同一份 query-time 归一）：
-        // 曾经这里直连引擎，于是同一个回合里 `query_dataset` 的日期串能用、内嵌的却把
-        // `">=": "2026"` 当数字 2026 比（全中 243 行）、`">=": "2026-07"` 被整条跳过（0 行）。
-        // 时间列优先用请求里显式指定的，其次用 profile 已经认出来的那个。
+        // Embedded queries must be isomorphic to query_dataset (same query-time normalization);
+        // otherwise the same date string behaves differently in the same turn.
         const axisColumn = request.time_column ?? profile.time_facts?.time_column;
         for (const [index, query] of request.queries.entries()) {
             try {
@@ -198,18 +151,15 @@ export async function describeDataset(input) {
                 queries.push({ index, result });
             }
             catch (error) {
-                // 单条 query 失败不炸整份：把错误记在该条上，模型可以在下一次调用里修正。
                 queries.push({ index, error: errorEnvelope(error) });
             }
         }
     }
     const facts = restrictFacts(profile, request.columns_of_interest, shape, warnings);
-    // 内部按"该有就有、没有就是 undefined"组装，**出工具前统一过 compact()**：
-    // undefined 属性会被 DSH 的输出校验判成 `value is not lossless JSON`（见 compact 注释）。
+    // Assemble with undefined allowed, then compact once before returning (see compact).
     const value = compact({
         status: 'ok',
-        // 来自 inspect_dataset 的元数据。**刻意不带 DatasetRef.schema**：它与 profile 的逐列 schema
-        // 同名不同义，带上既会撞名、又会让宽表体积翻倍；逐列事实已由 profile.schema 覆盖。
+        // Deliberately omit DatasetRef.schema: it collides with profile.schema and doubles wide-table size.
         dataset_id: inspection.dataset_id,
         task_id: inspection.task_id,
         session_id: inspection.session_id,
@@ -222,7 +172,6 @@ export async function describeDataset(input) {
         retention_until: inspection.retention_until,
         params_digest: inspection.params_digest,
         query_access: inspection.query_access,
-        // 来自 profile_dataset
         profile_id: profile.profile_id,
         profile_ref: profile.artifact_ref,
         columns: profile.columns,
@@ -240,10 +189,8 @@ export async function describeDataset(input) {
     const encoded = JSON.stringify(value);
     const bytes = codePointLength(encoded);
     if (bytes > SAFE_RESULT_CHARS) {
-        // 体积归因：把 queries 部分单量出来，hint 指名先砍哪边。2026-10-10 真机（task_fh_300803_20261010）：
-        // 两份宽表各带 5-6 聚合的 queries 打穿闸门，而回执只说"用 columns_of_interest 收窄"——列本来
-        // 已经很窄，超预算的其实是 queries，模型只好 describe（去 queries）+ query_dataset 各来一轮，
-        // 4 次调用里 2 次本可省。归因字段让 hint 直指大头，不引入第二道闸门（⛔ 体积闸门仍只有一道）。
+        // Attribution lets the hint name the big side without adding a second gate
+        // (there is still exactly one size gate).
         const queriesBytes = codePointLength(JSON.stringify(value.queries));
         const factsBytes = bytes - queriesBytes;
         return compact({