@v587d/capital-generation 0.0.0-stage → 2.6.0

package/lib/data-collector/describe.js

@@ -0,0 +1,256 @@
+import { DatasetStoreError, } from './store.js';
+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 会被剪掉中间段，而"被剪"与"被本闸门拦下"的区别是
+ * **后者会让模型知道发生了什么并给出重试办法**。
+ */
+export const SAFE_RESULT_CHARS = 7_000;
+/** 单次调用的 queries 条数上限：防的是请求体积，不是结果体积（结果另有闸门）。 */
+export const MAX_DESCRIBE_QUERIES = 8;
+function errorEnvelope(error) {
+    if (error instanceof DatasetQueryError || error instanceof DatasetStoreError) {
+        const prefix = `${error.code}: `;
+        return { code: error.code, detail: error.message.startsWith(prefix) ? error.message.slice(prefix.length) : error.message };
+    }
+    return { code: 'query_failed', detail: error instanceof Error ? error.message : String(error) };
+}
+/** 与剪枝器同口径：按 Unicode 码点量体积，不按 UTF-16 码元。 */
+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()`。
+ */
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function normalizeQueryItem(value, index, datasetId) {
+    if (!isRecord(value))
+        throw new DatasetQueryError('query_spec_invalid', `queries[${index}] must be an object`);
+    let source = value;
+    if (value.query !== undefined) {
+        const envelope = isRecord(value.query) ? value.query : parseJsonContainer(value.query);
+        if (!isRecord(envelope))
+            throw new DatasetQueryError('query_spec_invalid', `queries[${index}].query must be an object`);
+        source = envelope;
+    }
+    if (source.dataset_id !== undefined && source.dataset_id !== 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 补。
+    for (const field of ['type', 'task_id', 'dataset_id'])
+        delete shape[field];
+    return shape;
+}
+/**
+ * 工具边界归一化：宽容解析（字符串化的 JSON 数组/对象、单个对象、envelope 形态），
+ * 引擎侧保持严格。与 `query_dataset` 的 `normalizeQueryArgs` 共用同一套解析原语
+ * （src/data-collector/args.ts），避免两个工具的宽容度漂移。
+ */
+export function normalizeDescribeArgs(args) {
+    const dataset_id = readDatasetId(args.dataset_id);
+    const rawQueries = args.queries;
+    let list = [];
+    if (rawQueries !== undefined && rawQueries !== null && rawQueries !== '') {
+        const parsed = parseJsonContainer(rawQueries);
+        if (Array.isArray(rawQueries))
+            list = rawQueries;
+        else if (Array.isArray(parsed))
+            list = parsed;
+        else if (isRecord(rawQueries))
+            list = [rawQueries];
+        else if (isRecord(parsed))
+            list = [parsed];
+        else
+            throw new DatasetQueryError('query_spec_invalid', 'queries must be an array of QuerySpec objects (a JSON array string is also accepted)');
+    }
+    if (list.length > MAX_DESCRIBE_QUERIES) {
+        throw new DatasetQueryError('query_spec_invalid', `queries must contain at most ${MAX_DESCRIBE_QUERIES} items`);
+    }
+    return {
+        dataset_id,
+        task_id: readOptionalTaskId(args.task_id),
+        time_column: readOptionalString(args.time_column),
+        primary_key: readOptionalString(args.primary_key),
+        columns_of_interest: readOptionalColumnList(args.columns_of_interest),
+        queries: list.map((item, index) => normalizeQueryItem(item, index, dataset_id)),
+    };
+}
+function restrictFacts(profile, columns, shape, warnings) {
+    const facts = { statistics: profile.statistics, categories: profile.categories, schema: profile.schema };
+    if (columns === undefined || columns.length === 0)
+        return facts;
+    if (shape === 'document') {
+        warnings.push('columns_of_interest has no effect on a document Dataset');
+        return facts;
+    }
+    const known = new Set(profile.columns);
+    const unknown = columns.filter((column) => !known.has(column));
+    if (unknown.length > 0)
+        warnings.push(`columns_of_interest ignored unknown columns: ${unknown.join(', ')}`);
+    const keep = new Set(columns.filter((column) => known.has(column)));
+    const pick = (map) => map === undefined
+        ? undefined
+        : 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 字符）。
+ */
+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）。
+ */
+export async function describeDataset(input) {
+    const { store, session, request, signal } = input;
+    const inspection = await store.inspectDataset(request.dataset_id, session, signal);
+    if (!inspection.query_access.readable) {
+        const reason = inspection.query_access.reason;
+        const code = reason === 'dataset_too_large' ? 'dataset_too_large' : 'dataset_not_row_readable';
+        throw new DatasetStoreError(code, `Dataset ${inspection.dataset_id} cannot be read for description (${reason ?? 'none'})`);
+    }
+    const profile = await store.profileDataset({
+        session,
+        dataset_id: inspection.dataset_id,
+        task_id: request.task_id,
+        time_column: request.time_column,
+        primary_key: request.primary_key,
+        signal,
+    });
+    const shape = inspection.query_access.shape;
+    const warnings = [...profile.warnings];
+    const queries = [];
+    if (shape === 'document') {
+        if (request.queries.length > 0)
+            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 已经认出来的那个。
+        const axisColumn = request.time_column ?? profile.time_facts?.time_column;
+        for (const [index, query] of request.queries.entries()) {
+            try {
+                const prepared = await normalizeQueryDates({
+                    store,
+                    session,
+                    dataset_id: inspection.dataset_id,
+                    query: { ...query, dataset_id: inspection.dataset_id },
+                    ...(axisColumn === undefined ? {} : { time_column: axisColumn }),
+                    signal,
+                });
+                const result = await store.queryDataset({
+                    session,
+                    dataset_id: inspection.dataset_id,
+                    query: prepared.query,
+                    signal,
+                });
+                if (prepared.axis !== undefined)
+                    withIsoTimeColumns(result, prepared.axis);
+                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 注释）。
+    const value = compact({
+        status: 'ok',
+        // 来自 inspect_dataset 的元数据。**刻意不带 DatasetRef.schema**：它与 profile 的逐列 schema
+        // 同名不同义，带上既会撞名、又会让宽表体积翻倍；逐列事实已由 profile.schema 覆盖。
+        dataset_id: inspection.dataset_id,
+        task_id: inspection.task_id,
+        session_id: inspection.session_id,
+        artifact_ref: inspection.artifact_ref,
+        format: inspection.format,
+        capability: inspection.capability,
+        source_label: inspection.source_label,
+        row_count: profile.row_count,
+        captured_at: inspection.captured_at,
+        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,
+        quality: profile.quality,
+        statistics: facts.statistics,
+        categories: facts.categories,
+        schema: facts.schema,
+        time_facts: restrictTimeFacts(profile.time_facts, facts.keep),
+        structure: profile.structure,
+        document: profile.document,
+        validation: profile.validation,
+        warnings,
+        queries,
+    });
+    const encoded = JSON.stringify(value);
+    const bytes = codePointLength(encoded);
+    if (bytes > SAFE_RESULT_CHARS) {
+        return compact({
+            status: 'too_large',
+            dataset_id: inspection.dataset_id,
+            profile_ref: profile.artifact_ref,
+            shape,
+            columns: profile.columns,
+            bytes,
+            hint: shape === 'document'
+                ? '文档型 Dataset 的结果超预算：直接调 profile_dataset 取有界内容（本工具的列过滤对文档无效）'
+                : '结果超预算：重发一次 describe_dataset，用 columns_of_interest 指定本次问题真正需要的列，或减少 queries 条数',
+        });
+    }
+    return value;
+}

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

@@ -0,0 +1,187 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { DataTimeContract } from '../time/tools.js';
+import type { DatasetRef, SaveDatasetInput, SessionLike } from './store.js';
+/**
+ * 规范化内部 data_key 片段：斜杠/冒号等路径分隔符一律映射为点，其余非常规
+ * 字符折叠为点、合并连续点、去掉首尾点。data_key 只是宿主内部路由/审计身份，
+ * 不出现在模型可见协议、人设或工具输出中。
+ */
+export declare function normalizeKeyToken(value: string): string;
+/**
+ * 生成内部 data_key：provider.kind.resource（例如
+ * buildDataKey('fuyao', 'api', '/api/a-share/prices/snapshot')
+ * => 'fuyao.api.api.a-share.prices.snapshot'）。
+ */
+export declare function buildDataKey(provider: string, kind: string, resource: string): string;
+/**
+ * 数据请求：capability 是模型可见的短能力名（全局唯一），session 由工具层以
+ * exec.agent.session 注入，不接受模型传参。内部 data_key 不出现在请求协议里。
+ */
+export interface DataRequest {
+    capability: string;
+    params: Record<string, unknown>;
+    /** force_refresh=true 绕过已验证 manifest 并生成新的不可变 Dataset。 */
+    force_refresh?: boolean;
+    /** 本次用户任务关联 id（可复用）；只用于追溯，不要求模型理解。 */
+    task_id?: string;
+    session: SessionLike;
+}
+/**
+ * 数据源契约：capability 为唯一注册键与模型可见名；name/source/data_key
+ * 均为宿主内部字段（日志、路由、审计），不得进入工具 schema、输出或人设。
+ */
+export interface SchemaDescriptor {
+    capability: string;
+    name: string;
+    source: string;
+    data_key: string;
+    source_label?: string;
+    paginated?: boolean;
+    /** 可复用 Dataset 的最长采集年龄；未声明时仅受 Dataset 保留期约束。宿主内部字段。 */
+    cacheMaxAgeMs?: number;
+    /**
+     * 行数组位置的显式声明。龙虎榜这类响应的行数组不在 `item` 下（`stock_items`），
+     * 只靠形状推断会把整份数据判成「不可读的文档」。谁产出数据谁声明行在哪里，
+     * 存储层不再猜。
+     */
+    rowShape?: RowShapeHint;
+    /** 一行摘要：只用于能力目录（选能力够用），控制在 ~50 字以内。 */
+    summary?: string;
+    /** 完整说明：只在 describe_capability 详情里返回（单位、null 语义、时间口径、分页口径）。 */
+    description?: string;
+    input_schema: object;
+    /** 机器可读时间参数契约，由时间工具与数据源共同使用。 */
+    time_contract?: DataTimeContract;
+    output_schema?: object;
+}
+/** 能力目录项：只带"选能力"所需的信息，体积必须远小于工具结果剪枝阈值。 */
+export interface CapabilitySummary {
+    capability: string;
+    summary: string;
+    paginated: boolean;
+}
+/** 单个能力的完整契约：参数与输出字段字典，调用前必读。 */
+export interface CapabilityDetail extends CapabilitySummary {
+    description: string;
+    input_schema: object;
+    /** `output_schema` 的模型可见投影，见 renderOutputFields；声明不出字段时为 null。 */
+    output_fields: string | null;
+}
+export interface DataSource {
+    schema: SchemaDescriptor;
+    execute(request: DataRequest, signal: AbortSignal): Promise<{
+        data: unknown;
+        schema?: object | null;
+    }>;
+    /** Optional source-specific output guard; false rejects the result before persistence. */
+    validateOutput?: (data: unknown) => boolean;
+    /**
+     * Optional parameter canonicalization. The Hub calls it BEFORE computing the
+     * in-flight merge key and params_digest, so requests that differ only in
+     * case/whitespace/list order/default values share one Dataset instead of
+     * writing several. It must be idempotent (execute calls it again) and may
+     * throw to reject invalid parameters before anything is queued. Sources that
+     * omit it keep their previous behaviour exactly.
+     */
+    normalizeParams?: (params: Record<string, unknown>) => Record<string, unknown>;
+}
+/** Dataset 落盘器（Hub 的唯一成功出口）。 */
+export interface DatasetStoreLike {
+    save(input: SaveDatasetInput): Promise<DatasetRef>;
+    /** Optional for compatibility with lightweight test stores; production store implements manifest lookup. */
+    findLatest?(input: {
+        session: SessionLike;
+        capability: string;
+        params_digest: string;
+        signal?: AbortSignal;
+    }): Promise<DatasetRef | undefined>;
+}
+/** 数据源声明的行数组位置；缺省按 `item` 推断。 */
+export interface RowShapeHint {
+    /** 行数组所在的顶层键名（默认 `item`）。 */
+    rowKey?: string;
+    /** 可选的多个行数组路径，支持 `[]` 展开并合并为一组 rows。 */
+    rowKeys?: string[];
+    /** 顶层本身就是行数组。 */
+    rootArray?: boolean;
+}
+export interface DataCollectorHubOptions {
+    /** 必需：宿主侧 Dataset store；缺失时 request 直接失败。 */
+    store: DatasetStoreLike;
+    /** 队列最大长度；默认 50。 */
+    maxQueueLength?: number;
+    /** 传输层执行超时；默认 30_000 ms。只是请求超时，不是数据生命周期。 */
+    requestTimeoutMs?: number;
+    /** 时钟注入（测试用）；默认 Date.now。 */
+    now?: () => number;
+}
+/**
+ * Phase 1 数据执行器：FIFO 串行执行外部数据源，成功后由宿主 store 立即
+ * 原子落盘为不可变 Dataset，只回传 DatasetRef。
+ *
+ * 明确不做：长期 raw data 内存缓存、按 data_key 的查询、source_preference 路由。
+ * 已验证 DatasetRef 的复用由 workspace manifest 提供，内存只保留 in-flight 队列。
+ */
+export declare class DataCollectorHub {
+    private readonly queue;
+    /** 正在执行的队列项（执行期间不在 queue 中，但仍参与合并与容量判断）。 */
+    private active;
+    private readonly sources;
+    private readonly cacheLookups;
+    private readonly store;
+    private running;
+    private readonly maxQueueLength;
+    private readonly requestTimeoutMs;
+    private readonly now;
+    constructor(options: DataCollectorHubOptions);
+    registerSource(source: DataSource): () => void;
+    /**
+     * 入队并阻塞等待完成：先按 capability+params_digest 查找当前 session 下仍有效的
+     * manifest；force_refresh=true 或没有可复用 Dataset 时才进入数据源队列。相同的
+     * in-flight 请求仍共享一次执行，成功后立即由宿主 store 原子落盘。
+     *
+     * 参数规范化（source 可选）发生在这里：merge key 与 digest 都用规范化后的参数，
+     * 因此「大小写/空白/重复项不同、语义相同」的请求命中同一个 Dataset。未知
+     * capability 不做处理，仍由执行阶段抛出统一的 no data source 错误。
+     */
+    request(request: DataRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<DatasetRef>;
+    /** 应用 source 的可选参数规范化；未声明或 capability 未注册时原样返回。 */
+    private normalizeRequest;
+    /** 挂一个等待者并返回其结算承诺；signal 触发时摘除等待者并拒绝（不影响共享执行）。 */
+    private awaitSettlement;
+    /** 结算一个等待者：无论成败都摘除监听，防止重复结算。 */
+    private settleWaiter;
+    /**
+     * 能力目录（模型可见的最外层发现入口）：只含 capability、一行摘要与是否分页。
+     *
+     * 目录刻意不带 input_schema / output_schema —— 全量 schema 一度达 23KB，
+     * 会被工具结果剪枝器截掉中间部分，导致排在中间的能力在发现阶段不可见。
+     * 目录必须一次性全部返回（体积预算由测试守住），详情走 describeCapability。
+     * 不含任何内部路由字段（name/source/data_key/source_label）。
+     */
+    listCapabilities(): CapabilitySummary[];
+    /** 当前已注册的能力名（用于未知名字的引导与诊断）。 */
+    capabilityNames(): string[];
+    /**
+     * 能力目录的模型可见形态：一行一条 `capability|summary|paginated`（1=分页、0=不分页）。
+     * 同等信息量下 JSON 数组要 5530 字符（69 条实测，其中 58% 是键名与标点），行编码 2435、
+     * 均摊从 80 降到 35 字符——目录余量从 +7 条变成 +105 条。信息量没变、依然一次性全量返回，
+     * §1.1 那条"不分页、不裁剪"的硬约束原样成立。结构化形态仍由 listCapabilities 提供（测试与内部消费）。
+     */
+    capabilityDirectory(): string;
+    /**
+     * 单个能力的完整契约；名字未注册时返回 undefined，由工具层分类成可引导的错误。
+     * 返回值只含模型可见字段，是新建的普通对象，不回传内部 live data。
+     * `output_fields` 是 `output_schema` 的投影：详情体积按列数增长会被宽表打穿，见 renderOutputFields。
+     */
+    describeCapability(capability: string): CapabilityDetail | undefined;
+    private processNext;
+}
+export declare function provideDataCollectorHub(ctx: Context, options: DataCollectorHubOptions): DataCollectorHub;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        dataCollectorHub: DataCollectorHub;
+    }
+}