@v587d/capital-generation 0.0.0-stage → 2.6.0

package/lib/ocr/markdown.js

@@ -0,0 +1,209 @@
+/**
+ * PaddleOCR 输出 → 模型可读 markdown 的归一化（`ocr` 的呈现层，唯一一份实现）。
+ *
+ * 为什么必须归一化（2026-09-25 拿真报文实测，贵州茅台 15 页研报）：上游把**表格输出成内联
+ * HTML**，每个单元格都带 `style='text-align: center; word-wrap: break-word;'`——
+ * 105,639 个字符里 63,232 个（60%）是 `style='...'` 样板，去掉再转成 GFM 管道表只剩 27,156。
+ * 本仓的场景恰恰是"大量表格、图形"，不处理就等于**预算的六成买的是 HTML 属性**，
+ * 而 `prettifyMarkdown` 这类 flag 在上游被静默忽略（未知键也返回 Success），帮不上。
+ *
+ * 归一化只做**无损排版**：不删正文、不改数字、不做摘要。数字一律照抄上游。
+ */
+const PAGE_MARKER_PREFIX = '<!-- page:';
+/** HTML 实体：财报文档里 `&amp;` 出现在公司名与科目名里，不解开就是脏数据。 */
+const NAMED_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+function decodeEntities(value) {
+    return value.replace(/&(#\d+|#x[0-9a-f]+|[a-z]+);/giu, (whole, body) => {
+        const lowered = body.toLowerCase();
+        if (lowered.startsWith('#x')) {
+            const code = Number.parseInt(lowered.slice(2), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        if (lowered.startsWith('#')) {
+            const code = Number.parseInt(lowered.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        return NAMED_ENTITIES[lowered] ?? whole;
+    });
+}
+function stripTags(value) {
+    return decodeEntities(value.replace(/<[^>]*>/gu, ' '))
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function escapeCell(value) {
+    // GFM 单元格里的竖线必须转义，否则一行被切成更多列——表格串列比报错危险（声明与正文不一致）。
+    return value.replace(/\|/gu, '\\|');
+}
+/** 取一行 `<tr>` 里的单元格文本。 */
+function rowCells(row) {
+    const cells = [];
+    // 先按**开**标签切：畸形行（少写 `</td>`，实测存在）也能一格一切；再按闭标签截断本段，
+    // 防止 `1</td><td>2` 这类残留把下一格的内容并进来。第一格之前的 `<thead>` 碎片一律丢弃。
+    // ⚠️ 单元格标签是 `<td>` **或** `<th>`（上游表头行用 `<th>`，实测）：写成 `<t(?:d|th)`
+    //    只匹配得到 `<td`，`<th>` 行切不出格、整行被 `kept` 丢掉——表头静默消失。
+    //    `\b` 在这里是必要的：它让 `<thead>` / `<table>` 不被误当成单元格开标签。
+    for (const segment of row.split(/<t(?:d|h)\b[^>]*>/giu).slice(1)) {
+        cells.push(stripTags(segment.split(/<\/t(?:d|h)\s*>/iu)[0] ?? ''));
+    }
+    return cells;
+}
+/**
+ * 一张 HTML 表 → GFM 管道表。
+ *
+ * 表头按上游第一行处理（上游会把 `<thead><th>` 放第一行）；列数以各行最大值为准并补齐，
+ * 因为 GFM 要求分隔行列数与表头一致，少一格整张表退化成裸文本。
+ */
+function tableToMarkdown(tableHtml) {
+    const rows = [...tableHtml.matchAll(/<tr\b[^>]*>([\s\S]*?)(?:<\/tr>|$)/giu)].map((match) => rowCells(match[1]));
+    const kept = rows.filter((cells) => cells.length > 0);
+    if (kept.length === 0)
+        return stripTags(tableHtml);
+    const width = Math.max(...kept.map((cells) => cells.length));
+    const lines = kept.map((cells) => `| ${cells.map(escapeCell).join(' | ')}${'|'.repeat(width - cells.length)} |`);
+    lines.splice(1, 0, `|${' --- |'.repeat(width)}`);
+    return lines.join('\n');
+}
+/** 剥样式 + HTML 表转 GFM + 收空行。对不含 HTML 的正文近似恒等。 */
+export function normalizeOcrMarkdown(source) {
+    const styleMatches = source.match(/\s(?:style|class)\s*=\s*(?:"[^"]*"|'[^']*')/giu) ?? [];
+    const styleCharsRemoved = styleMatches.reduce((total, match) => total + match.length, 0);
+    let tables = 0;
+    const withoutTables = source.replace(/<table\b[^>]*>[\s\S]*?(?:<\/table>|$)/giu, (match) => {
+        tables += 1;
+        return `\n${tableToMarkdown(match)}\n`;
+    });
+    const cleaned = withoutTables
+        .replace(/<br\s*\/?\s*>/giu, ' ')
+        .replace(/<\/?(?:td|th|tr|thead|tbody|tfoot|table|div|span|p|font|img|a|sup|sub|b|i|u|s|em|strong)\b[^>]*>/giu, '')
+        .replace(/\s(?:style|class)\s*=\s*(?:"[^"]*"|'[^']*')/giu, '')
+        // 上游会把标题粘在正文尾巴上（实测 `2024-11-12## 盈利预测`），标题不在行首就没法进索引；
+        // 要求 `#` 后必须有空格，避免把 "评级#买入" 这类没有空格的井号误拆。
+        .replace(/(?<=\S)(#{1,6}\s+\S)/gu, '\n\n$1')
+        .replace(/[ \t]+\n/gu, '\n')
+        .replace(/\n{3,}/gu, '\n\n');
+    return { markdown: cleaned.trim(), tables, styleCharsRemoved };
+}
+function firstHeading(markdown) {
+    for (const line of markdown.split('\n')) {
+        const heading = /^#{1,6}\s+(.+)$/u.exec(line.trim());
+        if (heading?.[1])
+            return heading[1].trim().slice(0, 120);
+    }
+    return undefined;
+}
+/** 把逐页 markdown 拼成一份文档，并算出**页偏移索引**（按页取回与关键词定位都靠它）。 */
+export function buildOcrDocument(sourcePages) {
+    const chunks = [];
+    const pages = [];
+    let offset = 0;
+    let tables = 0;
+    let images = 0;
+    let styleCharsRemoved = 0;
+    for (const sourcePage of sourcePages) {
+        const normalized = normalizeOcrMarkdown(sourcePage.markdown);
+        tables += normalized.tables;
+        images += sourcePage.images;
+        styleCharsRemoved += normalized.styleCharsRemoved;
+        const marker = `${PAGE_MARKER_PREFIX}${sourcePage.page} -->\n`;
+        const body = normalized.markdown;
+        const entry = {
+            page: sourcePage.page,
+            start: offset + marker.length,
+            end: offset + marker.length + body.length,
+            chars: body.length,
+        };
+        const heading = firstHeading(body);
+        if (heading !== undefined)
+            entry.heading = heading;
+        pages.push(entry);
+        chunks.push(`${marker}${body}\n\n`);
+        offset += marker.length + body.length + 2;
+    }
+    const document = chunks.join('').trimEnd();
+    return { document, pages, chars: document.length, images, tables, styleCharsRemoved };
+}
+function pageOf(pages, at) {
+    return pages.find((entry) => at >= entry.start && at < entry.end) ?? pages[pages.length - 1];
+}
+/**
+ * 页区间解析：`"1-3"` / `"5"` / `"2-4,9"`（1 起始，闭区间）。
+ * 越界页码**响亮失败**而不是静默少给——"这页没有"和"我没给"在回执里必须能区分。
+ */
+export function parsePageRange(spec, totalPages) {
+    const taken = [];
+    for (const part of spec.split(',')) {
+        const trimmed = part.trim();
+        if (trimmed.length === 0)
+            continue;
+        const span = /^(\d+)\s*(?:-|–|~)\s*(\d+)$/u.exec(trimmed);
+        if (span) {
+            const from = Number(span[1]);
+            const to = Number(span[2]);
+            if (from < 1 || to > totalPages || from > to) {
+                throw new Error(`pages out of range: '${trimmed}' (document has ${totalPages} pages)`);
+            }
+            for (let page = from; page <= to; page += 1)
+                if (!taken.includes(page))
+                    taken.push(page);
+            continue;
+        }
+        const single = /^\d+$/u.test(trimmed) ? Number(trimmed) : Number.NaN;
+        if (!Number.isInteger(single) || single < 1 || single > totalPages) {
+            throw new Error(`pages out of range: '${trimmed}' (document has ${totalPages} pages)`);
+        }
+        if (!taken.includes(single))
+            taken.push(single);
+    }
+    if (taken.length === 0)
+        throw new Error(`pages is empty after normalization: '${spec}'`);
+    return taken;
+}
+/** 按页切出正文（纯字符串切片，不重跑上游）。 */
+export function selectPages(document, pages) {
+    return pages.map((page) => {
+        const entry = document.pages.find((item) => item.page === page);
+        if (!entry)
+            throw new Error(`page ${page} is not in this document`);
+        const excerpt = { page, chars: entry.chars, text: document.document.slice(entry.start, entry.end) };
+        if (entry.heading !== undefined)
+            excerpt.heading = entry.heading;
+        return excerpt;
+    });
+}
+/**
+ * 关键词定位：在**已落盘的文档**里找命中，回带页号的上下文片段。
+ *
+ * 为什么不靠 `pages` 硬读：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算 6,144——
+ * 想拿财务预测表就得能"跳着看"。上游页区间不影响算力（整篇都算过），所以定位必须在这份
+ * 归一化文本上做，不再出网。
+ */
+export function locateQuery(document, query, limit, windowChars) {
+    const haystack = document.document;
+    const needle = query.trim();
+    if (needle.length === 0)
+        throw new Error('query must not be empty');
+    const hits = [];
+    const loweredNeedle = needle.toLowerCase();
+    const lowered = haystack.toLowerCase();
+    let cursor = 0;
+    let lastEnd = -1;
+    while (hits.length < limit) {
+        const at = lowered.indexOf(loweredNeedle, cursor);
+        if (at < 0)
+            break;
+        cursor = at + needle.length;
+        // 相邻命中合并成一段窗口：否则同一句话的三次命中会占满 limit，看着像三条证据其实是一条。
+        if (at < lastEnd)
+            continue;
+        const entry = pageOf(document.pages, at);
+        // 窗口**不越页**：片段被标成"第 N 页"就是要能被引用回第 N 页，跨了页就是错引（错引比少引危险）。
+        // 顺带把 `<!-- page:N -->` 存储标记挡在外面——那是落盘布局，不是给模型回传正文的东西。
+        const from = Math.max(entry?.start ?? 0, at - windowChars);
+        const to = Math.min(entry?.end ?? haystack.length, at + needle.length + windowChars);
+        hits.push({ page: entry?.page ?? 1, at, excerpt: haystack.slice(from, to).replace(/\n+/gu, ' ⏎ ') });
+        lastEnd = to;
+    }
+    return hits;
+}
+export { PAGE_MARKER_PREFIX };

package/lib/ocr/store.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `ocr` 的**产物层**：解析结果一律落 `capital-data/ocr/<doc_id>/`，模型侧只拿 `doc_id` 与索引。
+ *
+ * 为什么必须落盘而不是留在内存：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算
+ * 只有 6,144（`SOURCE_OUTPUT_BUDGET_CHARS`）。落盘之后"按页取回 / 关键词定位"才是**纯本地
+ * 零花费**的第二、第三次读取；否则每次翻页都要重跑上游、再花一次 job。
+ *
+ * ```text
+ * capital-data/ocr/<doc_id>/
+ * ├── meta.json      # 页偏移索引与花费口径（model / charts / job_id / created_at）
+ * └── document.md    # 全篇归一化 markdown，页分隔 `<!-- page:N -->`
+ * ```
+ *
+ * `doc_id` 是**内容寻址**的：`sha1(归一化输入 + model + flags)` 前 12 位。因此"同一份文档
+ * 重复解析"自动命中缓存不再出网；`refresh` 才强制重跑（上游对同一份 PDF 两次给出过
+ * 18% 与 19% 的不同数字，重跑**不是**独立验证，引用必须带 `doc_id` 与 `created_at`）。
+ *
+ * 写入顺序是 `document.md` → `meta.json`：**meta 的在场即代表产物完整**。中途被中断
+ * （超时、取消）留下半件产物时，下一次读取按"未缓存"处理并重写（`overwrite`），
+ * 不会把模型永久锁死在一个坏 `doc_id` 上。
+ */
+import type { SessionLike, WorkspaceDatasetStore } from '../data-collector/store.js';
+import type { OcrDocument, OcrPageEntry } from './markdown.js';
+export declare const OCR_ARTIFACT_SUBDIR = "capital-data/ocr";
+export declare const OCR_DOC_ID_PATTERN: RegExp;
+/** 本地文档字节的读取上限：上游 100 页口径下的研报/公告量级，超限宁可报错也不要缓冲整份。 */
+export declare const OCR_MAX_SOURCE_BYTES: number;
+/** 产物元数据（落盘形态）。字段名与回执一致，模型看到的和盘上的不是两份真相。 */
+export interface OcrArtifactMeta {
+    doc_id: string;
+    /**
+     * 输入指认：`url:<http(s) URL>` 或 `file:<workspace 相对路径>`。**绝不落绝对路径**。
+     * 续查（只传 `job_id` + `doc_id`）时本机没有重算种子的输入，此时**留空而不是编一个**——
+     * 把作业号写成来源会被当成"这条 URL 就是文档出处"。
+     */
+    source?: string;
+    source_kind: 'url' | 'file' | 'job';
+    job_id: string;
+    model: string;
+    /** 提交时的图表识别开关；续查时无从得知，留空。 */
+    charts?: boolean;
+    pages: number;
+    chars: number;
+    images: number;
+    tables: number;
+    style_chars_removed: number;
+    page_entries: OcrPageEntry[];
+    created_at: string;
+}
+export interface OcrArtifact {
+    meta: OcrArtifactMeta;
+    document: OcrDocument;
+}
+/** `seed` 由各形态自己拼（URL 文本 / 文件字节），统一在此收敛成 `ocr_<12 hex>`。 */
+export declare function deriveOcrDocId(seed: string | Uint8Array, model: string, charts: boolean): string;
+/** 回执里给模型的 opaque 引用（与 Dataset/profile 引用同一套 `workspace://` 口径）。 */
+export declare function ocrArtifactRef(docId: string): string;
+/**
+ * 落盘产物**自己**坏了（调用方没做错任何事）。
+ *
+ * 为什么要单独一个类型：翻成回执的那一层要把"下一步该传什么"写清楚，而那一步需要的指认
+ * （当初解析用过的 url / file）只有这份 meta 里有。让调用方重新去猜链接，等于把一次
+ * 可机械执行的修复推回给人或模型。
+ */
+export declare class OcrArtifactError extends Error {
+    readonly reason: 'meta_unreadable' | 'meta_invalid' | 'document_missing';
+    readonly docId: string;
+    readonly sourceKind: OcrArtifactMeta['source_kind'] | undefined;
+    readonly source: string | undefined;
+    constructor(reason: 'meta_unreadable' | 'meta_invalid' | 'document_missing', docId: string, sourceKind: OcrArtifactMeta['source_kind'] | undefined, source: string | undefined, message: string);
+}
+/**
+ * 读回一份产物。三种"读不到"必须能区分：
+ *  - `undefined`：从未解析过（meta 与 document 都不在）——调用方据此决定提交新 job。
+ *  - 抛错：meta 在但正文丢失/损坏，或半件产物——**不能**当成"没有内容"，也不能静默重跑
+ *    （重跑要花一次 job，用户看不到钱去哪了），交给调用方翻成带 `doc_id` 的失败回执。
+ */
+export declare function readOcrArtifact(store: WorkspaceDatasetStore, input: {
+    session: SessionLike;
+    doc_id: string;
+    signal?: AbortSignal;
+}): Promise<OcrArtifact | undefined>;
+/** 落盘。`overwrite` 只在调用方**已经决定**重新生成时传（见文件头的写入顺序）。 */
+export declare function writeOcrArtifact(store: WorkspaceDatasetStore, input: {
+    session: SessionLike;
+    meta: OcrArtifactMeta;
+    document: OcrDocument;
+    signal?: AbortSignal;
+    overwrite?: boolean;
+}): Promise<{
+    artifact_ref: string;
+    paths: string[];
+}>;
+/** 拼一条与盘上记录同形状的 meta（`document` 只提供算好的排版统计）。 */
+export declare function buildArtifactMeta(input: {
+    doc_id: string;
+    source?: string;
+    source_kind: OcrArtifactMeta['source_kind'];
+    charts?: boolean;
+    job_id: string;
+    model: string;
+    document: OcrDocument;
+    createdAt: string;
+}): OcrArtifactMeta;
+/**
+ * 读取**待解析**的本地文档字节（`file` 形态的入口）。
+ *
+ * 只接受 session workspace 内的相对路径：绝对路径（含 Windows 盘符）与 `..` 段在
+ * `normalizeWorkspaceRelativePath` 就被拒，之后仍要过沙箱归属校验。模型从 `@xxx.pdf`
+ *  mention 里看到的是路径末段，因此回执话术要求它传 workspace 相对路径。
+ */
+export declare function readOcrSourceBytes(store: WorkspaceDatasetStore, input: {
+    session: SessionLike;
+    path: string;
+    signal?: AbortSignal;
+}): Promise<{
+    bytes: Uint8Array;
+    filename: string;
+}>;

package/lib/ocr/store.js

@@ -0,0 +1,226 @@
+/**
+ * `ocr` 的**产物层**：解析结果一律落 `capital-data/ocr/<doc_id>/`，模型侧只拿 `doc_id` 与索引。
+ *
+ * 为什么必须落盘而不是留在内存：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算
+ * 只有 6,144（`SOURCE_OUTPUT_BUDGET_CHARS`）。落盘之后"按页取回 / 关键词定位"才是**纯本地
+ * 零花费**的第二、第三次读取；否则每次翻页都要重跑上游、再花一次 job。
+ *
+ * ```text
+ * capital-data/ocr/<doc_id>/
+ * ├── meta.json      # 页偏移索引与花费口径（model / charts / job_id / created_at）
+ * └── document.md    # 全篇归一化 markdown，页分隔 `<!-- page:N -->`
+ * ```
+ *
+ * `doc_id` 是**内容寻址**的：`sha1(归一化输入 + model + flags)` 前 12 位。因此"同一份文档
+ * 重复解析"自动命中缓存不再出网；`refresh` 才强制重跑（上游对同一份 PDF 两次给出过
+ * 18% 与 19% 的不同数字，重跑**不是**独立验证，引用必须带 `doc_id` 与 `created_at`）。
+ *
+ * 写入顺序是 `document.md` → `meta.json`：**meta 的在场即代表产物完整**。中途被中断
+ * （超时、取消）留下半件产物时，下一次读取按"未缓存"处理并重写（`overwrite`），
+ * 不会把模型永久锁死在一个坏 `doc_id` 上。
+ */
+import { DatasetStoreError } from '../data-collector/store.js';
+import { WORKSPACE_DATA_DIR } from '../data-collector/store.js';
+export const OCR_ARTIFACT_SUBDIR = `${WORKSPACE_DATA_DIR}/ocr`;
+export const OCR_DOC_ID_PATTERN = /^ocr_[0-9a-f]{12}$/u;
+const META_FILE = 'meta.json';
+const DOCUMENT_FILE = 'document.md';
+/** 本地文档字节的读取上限：上游 100 页口径下的研报/公告量级，超限宁可报错也不要缓冲整份。 */
+export const OCR_MAX_SOURCE_BYTES = 32 * 1024 * 1024;
+/**
+ * 与 `hub.ts` / `sources.ts` 同一个 `process.getBuiltinModule` 惯用法（本仓刻意不装
+ * `@types/node`）。拿不到就**响亮失败**：`doc_id` 是缓存键，退回一个更弱的哈希会让两份不同
+ * 文档撞在同一个 `doc_id` 上、把 A 的正文当 B 交出去。
+ */
+function createHash(algorithm) {
+    const processLike = globalThis.process;
+    const hash = processLike?.getBuiltinModule?.('node:crypto')?.createHash?.(algorithm);
+    if (!hash)
+        throw new Error('node:crypto is unavailable; cannot derive a content-addressed doc_id');
+    return hash;
+}
+/** `seed` 由各形态自己拼（URL 文本 / 文件字节），统一在此收敛成 `ocr_<12 hex>`。 */
+export function deriveOcrDocId(seed, model, charts) {
+    const hash = createHash('sha1');
+    hash.update(seed);
+    hash.update(`\u0000${model}\u0000${charts ? 'charts' : 'no-charts'}`);
+    return `ocr_${hash.digest('hex').slice(0, 12)}`;
+}
+/** 回执里给模型的 opaque 引用（与 Dataset/profile 引用同一套 `workspace://` 口径）。 */
+export function ocrArtifactRef(docId) {
+    return `workspace://${OCR_ARTIFACT_SUBDIR}/${docId}`;
+}
+function requireDocId(docId) {
+    if (!OCR_DOC_ID_PATTERN.test(docId))
+        throw new Error('doc_id is invalid: expected ocr_<12 hex characters>');
+    return docId;
+}
+function metaPath(docId) {
+    return `${OCR_ARTIFACT_SUBDIR}/${requireDocId(docId)}/${META_FILE}`;
+}
+function documentPath(docId) {
+    return `${OCR_ARTIFACT_SUBDIR}/${requireDocId(docId)}/${DOCUMENT_FILE}`;
+}
+function isNotFound(error) {
+    return error instanceof DatasetStoreError && error.code === 'dataset_not_found';
+}
+function isTooLarge(error) {
+    return error instanceof DatasetStoreError && error.code === 'dataset_too_large';
+}
+/**
+ * 落盘产物**自己**坏了（调用方没做错任何事）。
+ *
+ * 为什么要单独一个类型：翻成回执的那一层要把"下一步该传什么"写清楚，而那一步需要的指认
+ * （当初解析用过的 url / file）只有这份 meta 里有。让调用方重新去猜链接，等于把一次
+ * 可机械执行的修复推回给人或模型。
+ */
+export class OcrArtifactError extends Error {
+    reason;
+    docId;
+    sourceKind;
+    source;
+    constructor(reason, docId, sourceKind, source, message) {
+        super(message);
+        this.reason = reason;
+        this.docId = docId;
+        this.sourceKind = sourceKind;
+        this.source = source;
+        this.name = 'OcrArtifactError';
+    }
+}
+/**
+ * 读回一份产物。三种"读不到"必须能区分：
+ *  - `undefined`：从未解析过（meta 与 document 都不在）——调用方据此决定提交新 job。
+ *  - 抛错：meta 在但正文丢失/损坏，或半件产物——**不能**当成"没有内容"，也不能静默重跑
+ *    （重跑要花一次 job，用户看不到钱去哪了），交给调用方翻成带 `doc_id` 的失败回执。
+ */
+export async function readOcrArtifact(store, input) {
+    const docId = requireDocId(input.doc_id);
+    let metaText;
+    try {
+        metaText = await store.readWorkspaceText({ session: input.session, path: metaPath(docId), signal: input.signal });
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        if (isTooLarge(error))
+            throw error;
+        throw new OcrArtifactError('meta_unreadable', docId, undefined, undefined, `产物 ${docId} 的 meta.json 读不出来：${error instanceof Error ? error.message : String(error)}`);
+    }
+    let meta;
+    try {
+        meta = normalizeMeta(JSON.parse(metaText), docId);
+    }
+    catch (error) {
+        throw new OcrArtifactError('meta_invalid', docId, undefined, undefined, `产物 ${docId} 的 meta.json 不是可识别的记录：${error instanceof Error ? error.message : String(error)}`);
+    }
+    let text;
+    try {
+        text = await store.readWorkspaceText({ session: input.session, path: documentPath(docId), signal: input.signal });
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            throw new OcrArtifactError('document_missing', docId, meta.source_kind, meta.source, `产物 ${docId} 的 document.md 缺失（meta 在、正文不在）`);
+        }
+        throw error;
+    }
+    return { meta, document: { document: text, pages: meta.page_entries, chars: meta.chars, images: meta.images, tables: meta.tables, styleCharsRemoved: meta.style_chars_removed } };
+}
+/** 落盘。`overwrite` 只在调用方**已经决定**重新生成时传（见文件头的写入顺序）。 */
+export async function writeOcrArtifact(store, input) {
+    const docId = requireDocId(input.meta.doc_id);
+    const written = await store.writeWorkspaceFiles({
+        session: input.session,
+        dir: `${OCR_ARTIFACT_SUBDIR}/${docId}`,
+        files: [
+            { name: DOCUMENT_FILE, content: input.document.document },
+            { name: META_FILE, content: `${JSON.stringify(input.meta)}\n` },
+        ],
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.overwrite ? { overwrite: true } : {}),
+    });
+    return { artifact_ref: ocrArtifactRef(docId), paths: written.map((file) => file.path) };
+}
+/** meta 是**我们**写出去的记录，读回来时仍逐字段核一遍——手改过的盘也要能响亮失败。 */
+function normalizeMeta(value, docId) {
+    const record = (typeof value === 'object' && value !== null ? value : {});
+    const pages = Array.isArray(record.page_entries) ? record.page_entries : [];
+    const entries = pages.map((item) => {
+        const page = (typeof item === 'object' && item !== null ? item : {});
+        if (typeof page.page !== 'number' || typeof page.start !== 'number' || typeof page.end !== 'number' || typeof page.chars !== 'number') {
+            throw new Error('page_entries 项缺字段');
+        }
+        const heading = typeof page.heading === 'string' ? { heading: page.heading } : {};
+        return { page: page.page, start: page.start, end: page.end, chars: page.chars, ...heading };
+    });
+    const text = (key) => {
+        if (typeof record[key] !== 'string')
+            throw new Error(`meta.${key} 不是字符串`);
+        return record[key];
+    };
+    const num = (key) => {
+        if (typeof record[key] !== 'number')
+            throw new Error(`meta.${key} 不是数字`);
+        return record[key];
+    };
+    if (record.doc_id !== docId)
+        throw new Error(`meta.doc_id 与目录不一致（${String(record.doc_id)}）`);
+    const source = typeof record.source === 'string' ? { source: record.source } : {};
+    const charts = typeof record.charts === 'boolean' ? { charts: record.charts } : {};
+    return {
+        doc_id: docId,
+        ...source,
+        source_kind: sourceKind(record.source_kind),
+        job_id: text('job_id'),
+        model: text('model'),
+        ...charts,
+        pages: num('pages'),
+        chars: num('chars'),
+        images: num('images'),
+        tables: num('tables'),
+        style_chars_removed: num('style_chars_removed'),
+        page_entries: entries,
+        created_at: text('created_at'),
+    };
+}
+/** 来源类别缺省或写歪时**响亮失败**：把不认识的 provenance 默认成 `url` 会伪造出处。 */
+function sourceKind(value) {
+    if (value === 'url' || value === 'file' || value === 'job')
+        return value;
+    throw new Error(`meta.source_kind 不认识：${String(value)}`);
+}
+/** 拼一条与盘上记录同形状的 meta（`document` 只提供算好的排版统计）。 */
+export function buildArtifactMeta(input) {
+    return {
+        doc_id: requireDocId(input.doc_id),
+        ...(input.source === undefined ? {} : { source: input.source }),
+        source_kind: input.source_kind,
+        job_id: input.job_id,
+        model: input.model,
+        ...(input.charts === undefined ? {} : { charts: input.charts }),
+        pages: input.document.pages.length,
+        chars: input.document.chars,
+        images: input.document.images,
+        tables: input.document.tables,
+        style_chars_removed: input.document.styleCharsRemoved,
+        page_entries: input.document.pages,
+        created_at: input.createdAt,
+    };
+}
+/**
+ * 读取**待解析**的本地文档字节（`file` 形态的入口）。
+ *
+ * 只接受 session workspace 内的相对路径：绝对路径（含 Windows 盘符）与 `..` 段在
+ * `normalizeWorkspaceRelativePath` 就被拒，之后仍要过沙箱归属校验。模型从 `@xxx.pdf`
+ *  mention 里看到的是路径末段，因此回执话术要求它传 workspace 相对路径。
+ */
+export async function readOcrSourceBytes(store, input) {
+    const bytes = await store.readWorkspaceBytes({
+        session: input.session,
+        path: input.path,
+        maxBytes: OCR_MAX_SOURCE_BYTES,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    });
+    const filename = input.path.split('/').pop() ?? 'document';
+    return { bytes, filename };
+}

package/lib/sources/eastmoney-http.d.ts

@@ -0,0 +1,2 @@
+import type { DataSource } from '../data-collector/hub.js';
+export declare function createEastmoneySources(): DataSource[];