@v587d/capital-generation 0.0.0-stage → 2.6.0

package/lib/net/eastmoney-client.js

@@ -0,0 +1,118 @@
+/**
+ * 东财（eastmoney.com）**共享网络面**：全进程一个节流器、一条请求路径。
+ *
+ * ## 为什么需要它（2026-09-24 核实）
+ *
+ * 本仓的东财出口一度是**两份互不知情的实现**：`src/data-collector` 侧经由
+ * `src/sources/eastmoney-http.ts` 的裸 `fetch`（无 sleep、无队列），web_retriever 侧是我新加的
+ * 第二个客户端。两份独立节流 = 同一个出口 IP 上两个速率，等于没限。
+ *
+ * 社区实测的东财风控阈值是「每秒 >5 次 / 单 IP 并发 ≥10 / 1 分钟 ≥200 次 / 5 分钟 ≥300 次 →
+ * 临时封 IP」，参考实践因此要求 `em_get()` 串行 + 限流。本仓 `DataCollectorHub` 的 FIFO 只保证
+ * "同一时刻只跑一个请求"，**不含最小间隔**——串行 ≠ 节流，连打十个请求仍是一秒十次。
+ *
+ * ## 分层（刻意如此，不要合并）
+ *
+ * - **数据面**按「可复用性」分两处，这是有意的：
+ *   - 可复用的**数值/分页**端点（行情、财务、资金流）走 `DataCollectorHub`，落成不可变 Dataset ——
+ *     那里 Dataset 复用是**收益**；
+ *   - 流式的**文本**来源（快讯、个股新闻、研报）走 web_retriever 的具名来源工具 ——
+ *     那里 Dataset 复用是**语义错误**（"最新 20 条快讯"不是可复用快照）。
+ * - **网络面**只有这一份：两条数据面都从这里取请求路径与节流器，**共享同一个 process 级实例**。
+ *   这正是"切勿一刀切"的落点：切的判据是**可复用性**（数据面），不是 provider，也不是网络面。
+ *
+ * ## 边界
+ *
+ * 本模块**不**做 SSRF 出口校验，但**出口校验在哪一份实现里**必须说清楚：
+ * - web_retriever 侧的三个 `eastmoney_*` 工具通过 `createEastmoneyClient({ transport })`
+ *   注入 `createHttpRequester` 的闸门实现（DNS 公网 IP 校验 + 手动重定向重校验 + 大小/超时上限），
+ *   与其余六个来源共用同一份出口治理；
+ * - 数据面（Hub 侧能力）用默认 transport（裸 `fetch`）：URL 全部是代码内常量 + 白名单参数，
+ *   模型不能投喂任意 URL，这是既有行为。
+ * 闸门只有 `createHttpRequester` 一份实现；本层只加节流与状态归类，不复制第二套校验
+ * （AGENTS.md §9.7）。
+ */
+import { createRequestThrottle } from './throttle.js';
+/**
+ * 东财系请求的**共享最小间隔**（毫秒）。
+ *
+ * 1000ms = 1 次/秒，低于「>5 次/秒」阈值，并同时满足「1 分钟 200 次 / 5 分钟 300 次」这类累计窗口口径。
+ */
+export const EASTMONEY_MIN_INTERVAL_MS = 1000;
+const DEFAULT_USER_AGENT = 'Mozilla/5.0';
+/**: 传输层错误。`status` 只在"上游返回了 HTTP 错误状态"时给出。 */
+export class EastmoneyTransportError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'EastmoneyTransportError';
+    }
+}
+export function createEastmoneyClient(options = {}) {
+    const userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+    const throttle = options.throttle ?? createRequestThrottle(options.minIntervalMs ?? EASTMONEY_MIN_INTERVAL_MS);
+    const transport = options.transport ?? createEastmoneyTransport();
+    /** 节流 + 发请求 + 状态判定：两条读取路径（text / json）共用这一份，避免状态判定被复制。 */
+    const send = (url, init) => throttle(async () => {
+        if (init.signal?.aborted) {
+            const error = new Error('eastmoney request aborted');
+            error.name = 'AbortError';
+            throw error;
+        }
+        let response;
+        try {
+            response = await transport(url, {
+                headers: { 'user-agent': userAgent, ...(init.headers ?? {}) },
+                ...(init.signal === undefined ? {} : { signal: init.signal }),
+            });
+        }
+        catch (error) {
+            // 取消原样抛出（`AbortError`），调用方据此区分"网络失败"与"调用方不要了"。
+            if (error instanceof Error && error.name === 'AbortError')
+                throw error;
+            // 已带分类 `code` 的错误（如闸门注入的 `LocalFetchError`：ABORTED/TIMEOUT/REDIRECT…）
+            // 原样抛出：再包一层会把"取消"降级成网络失败（docs/dev/web-retriever.md §4.2），也丢掉失败原因。
+            if (typeof error?.code === 'string')
+                throw error;
+            throw new EastmoneyTransportError(`eastmoney request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // 按 `status` 判定而不是 `response.ok`：本仓多处测试的假 Response 只提供 status/text/json，
+        // 用 `ok` 会让它们在 200 上误判成失败（真实的 fetch Response 两者都有）。
+        if (response.status >= 400) {
+            throw new EastmoneyTransportError(`eastmoney returned HTTP ${response.status}`, response.status);
+        }
+        return response;
+    });
+    return {
+        async fetchText(url, init = {}) {
+            const response = await send(url, init);
+            return { status: response.status, headers: response.headers, text: await response.text() };
+        },
+        async fetchJson(url, init = {}) {
+            return await (await send(url, init)).json();
+        },
+    };
+}
+function createEastmoneyTransport() {
+    return (url, init) => globalThis.fetch(url, init);
+}
+let sharedThrottle;
+/**
+ * **进程级共享节流器**：数据面与 web_retriever 侧可能各持一个客户端实例（transport 不同），
+ * 但东财风控按出口 IP 计，节流必须仍只有一份。两侧客户端都从这里取。
+ */
+export function sharedEastmoneyThrottle() {
+    sharedThrottle ??= createRequestThrottle(EASTMONEY_MIN_INTERVAL_MS);
+    return sharedThrottle;
+}
+let shared;
+/**
+ * **进程级单例**（数据面用，默认裸 fetch transport）：所有默认客户端共享同一个节流器，
+ * 等于回到"两份独立限流"的老问题的解法。宿主进程内所有东财请求都应经这里或
+ * 显式注入 `sharedEastmoneyThrottle()` 的实例。
+ */
+export function sharedEastmoneyClient() {
+    shared ??= createEastmoneyClient({ throttle: sharedEastmoneyThrottle() });
+    return shared;
+}

package/lib/net/throttle.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 通用请求节流器：把会打到**同一上游**的请求串成一条带最小间隔的链。
+ *
+ * ## 为什么是"链"而不是 `await sleep()`
+ *
+ * 多个工具调用可能**并发**进入（模型在同一条消息里发多个调用时，框架会把它们放进并发池）。
+ * 各自 sleep 之后仍会同时发出请求——间隔就白设了。串到一条 Promise 链上，才能保证
+ * "上一个请求**发出后**至少 N 毫秒，下一个才发出"。链本身不会因某个任务失败而断掉。
+ *
+ * ## 为什么是独立的中性模块
+ *
+ * 它纯属**网络面**关切，不属于任何一条数据面：东财 Hub 侧（`src/sources/eastmoney-http.ts`）
+ * 与 web_retriever 侧（`src/web-retriever/sources.ts`）都要用。若把它放在任一侧，另一侧就得
+ * 反向依赖对方——那正是"客户端被复制"的前身（见 `src/net/eastmoney-client.ts` 的分层说明）。
+ */
+export declare function createRequestThrottle(minIntervalMs: number): <T>(task: () => Promise<T>) => Promise<T>;

package/lib/net/throttle.js

@@ -0,0 +1,34 @@
+/**
+ * 通用请求节流器：把会打到**同一上游**的请求串成一条带最小间隔的链。
+ *
+ * ## 为什么是"链"而不是 `await sleep()`
+ *
+ * 多个工具调用可能**并发**进入（模型在同一条消息里发多个调用时，框架会把它们放进并发池）。
+ * 各自 sleep 之后仍会同时发出请求——间隔就白设了。串到一条 Promise 链上，才能保证
+ * "上一个请求**发出后**至少 N 毫秒，下一个才发出"。链本身不会因某个任务失败而断掉。
+ *
+ * ## 为什么是独立的中性模块
+ *
+ * 它纯属**网络面**关切，不属于任何一条数据面：东财 Hub 侧（`src/sources/eastmoney-http.ts`）
+ * 与 web_retriever 侧（`src/web-retriever/sources.ts`）都要用。若把它放在任一侧，另一侧就得
+ * 反向依赖对方——那正是"客户端被复制"的前身（见 `src/net/eastmoney-client.ts` 的分层说明）。
+ */
+export function createRequestThrottle(minIntervalMs) {
+    if (!Number.isFinite(minIntervalMs) || minIntervalMs < 0) {
+        // 配错的节流器会静默变成"没有节流"，而上游风控不会报"你太快了"——只会封 IP 或给空数据。
+        throw new Error(`createRequestThrottle: minIntervalMs must be a non-negative finite number, got ${String(minIntervalMs)}`);
+    }
+    let chain = Promise.resolve();
+    let lastStartedAt = 0;
+    return (task) => {
+        const result = chain.then(async () => {
+            const wait = minIntervalMs - (Date.now() - lastStartedAt);
+            if (wait > 0)
+                await new Promise((resolve) => setTimeout(resolve, wait));
+            lastStartedAt = Date.now();
+            return task();
+        });
+        chain = result.then(() => undefined, () => undefined);
+        return result;
+    };
+}

package/lib/ocr/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * PaddleOCR AIStudio **异步 job** 客户端（`ocr` 的上游实现，唯一一份出网实现）。
+ *
+ * 生命周期（2026-09-25 真报文实测，15 页贵州茅台研报，31 秒完成）：
+ * `POST /api/v2/ocr/jobs` → `{code:0,msg:'Success',data:{jobId}}`
+ * → `GET /api/v2/ocr/jobs/{jobId}` 轮询 `data.state`：`pending` → `running`
+ * （带 `extractProgress.{totalPages,extractedPages}`）→ `done`（带 `resultUrl.jsonUrl`）
+ * → `GET jsonUrl` 拿 **JSONL**（每行一个批次，`result.layoutParsingResults[]` 一项一页）。
+ *
+ * ⛔ 两条只能从真报文里拿到的事实，决定了本文件的形状：
+ * 1. **上游把错误装在 HTTP 200 里**：模型名写错返回 `{code:10007,msg:'模型传参错误'}`
+ *    且没有 `data.jobId`。只判 `status === 200` 会把失败当成功、`jobId` 变 `undefined`，
+ *    然后拿 `undefined` 去轮询——所以每个响应都先看 `code`。
+ * 2. **`optionalPayload` 的未知键被静默忽略**（塞 `zzzBogusKey` 照样返回 Success）。
+ *    公开文档那页讲的其实是同步 `/layout-parsing`，`mergeTables` / `prettifyMarkdown`
+ *    在 jobs 上是否生效无法证明，因此**只传官方示例里出现过的三个键**，
+ *    不拿没验证过的开关换"看起来能配"的假象。表格噪音靠 `markdown.ts` 自己处理。
+ */
+import type { HttpOutcome, HttpRequest } from '../web-retriever/local-fetch.js';
+import { type OcrDocument } from './markdown.js';
+export declare const PADDLE_OCR_DEFAULT_ENDPOINT = "https://paddleocr.aistudio-app.com/api/v2/ocr/jobs";
+export declare const PADDLE_OCR_DEFAULT_MODEL = "PaddleOCR-VL-1.6";
+/** 上游文档口径：PDF 默认最多 100 页。超页是**上游会失败**，提前拦比事后猜便宜。 */
+export declare const PADDLE_OCR_MAX_PAGES = 100;
+export type OcrErrorCode = 'NO_CREDENTIAL' | 'UPSTREAM' | 'JOB_FAILED' | 'RESULT_INVALID' | 'TOO_MANY_PAGES' | 'TIMEOUT';
+export declare class OcrError extends Error {
+    readonly code: OcrErrorCode;
+    constructor(code: OcrErrorCode, message: string);
+}
+export interface OcrProgress {
+    extracted_pages: number;
+    total_pages: number;
+}
+/** 一次轮询看到的作业状态（只保留我们用得上的字段）。 */
+export interface OcrJobState {
+    state: string;
+    progress?: OcrProgress;
+    jsonUrl?: string;
+    errorMsg?: string;
+}
+export interface OcrSubmitInput {
+    /** 公网可达的 `.pdf` 直链：由**上游**去取文件，本机不落任何字节。 */
+    fileUrl?: string;
+    /** 本地文档字节（`file` 形态）：走 multipart 上传。 */
+    file?: {
+        bytes: Uint8Array;
+        filename: string;
+    };
+    charts: boolean;
+    signal: AbortSignal;
+}
+export interface OcrWaitOutcome {
+    status: 'done' | 'pending';
+    job_id: string;
+    progress?: OcrProgress;
+    /** `status === 'done'` 时一定有。 */
+    document?: OcrDocument;
+    json_url?: string;
+    elapsed_ms: number;
+}
+export interface PaddleOcrClientOptions {
+    endpoint?: string;
+    model?: string;
+    resolveToken: () => Promise<string | undefined>;
+    request: (request: HttpRequest, signal?: AbortSignal) => Promise<HttpOutcome>;
+    pollIntervalMs?: number;
+    waitBudgetMs?: number;
+    resultMaxBytes?: number;
+    /** 注入以便测试：睡眠必须可取消。 */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    now?: () => number;
+}
+export interface PaddleOcrClient {
+    readonly model: string;
+    submit(input: OcrSubmitInput): Promise<string>;
+    poll(jobId: string, signal: AbortSignal): Promise<OcrJobState>;
+    wait(jobId: string, signal: AbortSignal, progress?: OcrProgress): Promise<OcrWaitOutcome>;
+    /** 提交并等到有结果（或自有预算耗尽回 pending）。 */
+    parse(input: OcrSubmitInput): Promise<OcrWaitOutcome>;
+    load(jsonUrl: string, signal: AbortSignal): Promise<OcrDocument>;
+}
+export declare function createPaddleOcrClient(options: PaddleOcrClientOptions): PaddleOcrClient;

package/lib/ocr/client.js

@@ -0,0 +1,281 @@
+/**
+ * PaddleOCR AIStudio **异步 job** 客户端（`ocr` 的上游实现，唯一一份出网实现）。
+ *
+ * 生命周期（2026-09-25 真报文实测，15 页贵州茅台研报，31 秒完成）：
+ * `POST /api/v2/ocr/jobs` → `{code:0,msg:'Success',data:{jobId}}`
+ * → `GET /api/v2/ocr/jobs/{jobId}` 轮询 `data.state`：`pending` → `running`
+ * （带 `extractProgress.{totalPages,extractedPages}`）→ `done`（带 `resultUrl.jsonUrl`）
+ * → `GET jsonUrl` 拿 **JSONL**（每行一个批次，`result.layoutParsingResults[]` 一项一页）。
+ *
+ * ⛔ 两条只能从真报文里拿到的事实，决定了本文件的形状：
+ * 1. **上游把错误装在 HTTP 200 里**：模型名写错返回 `{code:10007,msg:'模型传参错误'}`
+ *    且没有 `data.jobId`。只判 `status === 200` 会把失败当成功、`jobId` 变 `undefined`，
+ *    然后拿 `undefined` 去轮询——所以每个响应都先看 `code`。
+ * 2. **`optionalPayload` 的未知键被静默忽略**（塞 `zzzBogusKey` 照样返回 Success）。
+ *    公开文档那页讲的其实是同步 `/layout-parsing`，`mergeTables` / `prettifyMarkdown`
+ *    在 jobs 上是否生效无法证明，因此**只传官方示例里出现过的三个键**，
+ *    不拿没验证过的开关换"看起来能配"的假象。表格噪音靠 `markdown.ts` 自己处理。
+ */
+import { buildOcrDocument } from './markdown.js';
+export const PADDLE_OCR_DEFAULT_ENDPOINT = 'https://paddleocr.aistudio-app.com/api/v2/ocr/jobs';
+export const PADDLE_OCR_DEFAULT_MODEL = 'PaddleOCR-VL-1.6';
+/** 上游文档口径：PDF 默认最多 100 页。超页是**上游会失败**，提前拦比事后猜便宜。 */
+export const PADDLE_OCR_MAX_PAGES = 100;
+const DEFAULT_POLL_INTERVAL_MS = 5_000;
+/** 自有等待预算必须**小于**工具声明的 `timeoutMs`：留出不确定返回与写盘的余量。 */
+const DEFAULT_WAIT_BUDGET_MS = 200_000;
+/** 结果 JSONL 的体积上限（实测 15 页 258 KB；上限给到 8 MB 并在超限时响亮失败）。 */
+const DEFAULT_RESULT_MAX_BYTES = 8 * 1024 * 1024;
+export class OcrError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OcrError';
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : undefined;
+}
+function sleepAbortable(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason ?? new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * 把传输层异常翻成 OCR 错误码。
+ *
+ * ⚠️ `createHttpRequester` 对 4xx/5xx 抛的是 `LocalFetchError('HTTP', '… returned HTTP 401')`，
+ * 状态码只在消息文本里。这里按文本识别鉴权类失败（401/403）**只为了把"该去卡片填 token"
+ * 这条最有用的话送到模型面前**；识别不到就退回 `UPSTREAM`，绝不假装知道上游说了什么。
+ */
+function mapTransportFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/HTTP\s*(401|403)\b/u.test(message)) {
+        return new OcrError('NO_CREDENTIAL', `PaddleOCR 拒绝鉴权（${message}）：请在 设置 → 插件 → Capital 模式 填写 PaddleOCR Token`);
+    }
+    return new OcrError('UPSTREAM', message);
+}
+export function createPaddleOcrClient(options) {
+    const endpoint = options.endpoint || PADDLE_OCR_DEFAULT_ENDPOINT;
+    const model = options.model || PADDLE_OCR_DEFAULT_MODEL;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const waitBudgetMs = options.waitBudgetMs ?? DEFAULT_WAIT_BUDGET_MS;
+    const resultMaxBytes = options.resultMaxBytes ?? DEFAULT_RESULT_MAX_BYTES;
+    const sleep = options.sleep ?? sleepAbortable;
+    const now = options.now ?? Date.now;
+    async function authorizedHeaders() {
+        const token = await options.resolveToken();
+        if (!token) {
+            throw new OcrError('NO_CREDENTIAL', 'PaddleOCR Token 未配置：在 设置 → 插件 → 插件配置 → Capital 模式 填写（credentials 引用 PADDLE_OCR_TOKEN，环境变量同名亦可）');
+        }
+        return { authorization: `bearer ${token}` };
+    }
+    /** 发一次请求并**校验 body.code**：上游用 HTTP 200 装业务错误（见文件头 ⛔ 1）。 */
+    async function call(request, signal) {
+        let outcome;
+        try {
+            outcome = await options.request(request, signal);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ABORTED' || (error instanceof Error && error.name === 'AbortError'))
+                throw error;
+            throw mapTransportFailure(error);
+        }
+        if (outcome.truncated) {
+            throw new OcrError('RESULT_INVALID', `上游响应被体积上限截断（${request.url.slice(0, 80)}）：截断的 JSON 是解析失败，不是少读几条`);
+        }
+        let parsed;
+        try {
+            parsed = asRecord(JSON.parse(outcome.text));
+        }
+        catch {
+            throw new OcrError('RESULT_INVALID', `上游返回的不是 JSON（HTTP ${outcome.status}）：${outcome.text.slice(0, 160)}`);
+        }
+        if (!parsed)
+            throw new OcrError('RESULT_INVALID', `上游返回的形状不认识（HTTP ${outcome.status}）`);
+        const code = parsed.code;
+        if (code !== undefined && code !== 0) {
+            const message = typeof parsed.msg === 'string' ? parsed.msg : '(无 msg)';
+            if (code === 401)
+                throw new OcrError('NO_CREDENTIAL', `PaddleOCR 未鉴权（code 401 ${message}）：请在 设置 → 插件 → Capital 模式 填写 Token`);
+            throw new OcrError('UPSTREAM', `PaddleOCR 返回业务错误 code=${String(code)}：${message}`);
+        }
+        return parsed;
+    }
+    function optionalPayload(charts) {
+        // 只带官方示例出现过的三个键（文件头 ⛔ 2）。
+        return { useDocOrientationClassify: false, useDocUnwarping: false, useChartRecognition: charts };
+    }
+    async function submit(input) {
+        const headers = await authorizedHeaders();
+        const payload = optionalPayload(input.charts);
+        let body;
+        let extraHeaders;
+        if (input.fileUrl !== undefined) {
+            extraHeaders = { 'content-type': 'application/json' };
+            body = JSON.stringify({ fileUrl: input.fileUrl, model, optionalPayload: payload });
+        }
+        else {
+            const file = input.file;
+            const form = new FormData();
+            form.append('model', model);
+            form.append('optionalPayload', JSON.stringify(payload));
+            // `fs.readBytes` 的返回类型是 `Uint8Array<ArrayBufferLike>`，而 `Blob` 只接受
+            // ArrayBuffer 背书的视图；字节确实是新分配的 ArrayBuffer，在边界上收敛一次类型。
+            form.append('file', new Blob([file.bytes], { type: 'application/octet-stream' }), file.filename);
+            extraHeaders = {};
+            body = form;
+        }
+        // ⛔ `headers`（bearer）与 `extraHeaders`（content-type）**都要**带上：只传后者就等于
+        //    把作业提交发成一个无鉴权请求（实测 401），而轮询那条路是带着 token 的——
+        //    两条出网路径形状不一致，恰是"只测接好的那个入口"能长期潜伏的形态。
+        const parsed = await call({ url: endpoint, method: 'POST', headers: { ...headers, ...extraHeaders }, body }, input.signal);
+        const jobId = asRecord(parsed.data)?.jobId;
+        if (typeof jobId !== 'string' || jobId.length === 0) {
+            throw new OcrError('RESULT_INVALID', `提交成功但响应里没有 data.jobId：${JSON.stringify(parsed).slice(0, 200)}`);
+        }
+        return jobId;
+    }
+    async function poll(jobId, signal) {
+        const parsed = await call({ url: `${endpoint}/${encodeURIComponent(jobId)}`, headers: await authorizedHeaders() }, signal);
+        const data = asRecord(parsed.data);
+        if (!data)
+            throw new OcrError('RESULT_INVALID', `轮询响应缺 data：${JSON.stringify(parsed).slice(0, 200)}`);
+        const state = typeof data.state === 'string' ? data.state : '';
+        if (state.length === 0)
+            throw new OcrError('RESULT_INVALID', `轮询响应缺 state：${JSON.stringify(data).slice(0, 200)}`);
+        const progress = asRecord(data.extractProgress);
+        const resultUrl = asRecord(data.resultUrl);
+        const outcome = { state };
+        if (progress && typeof progress.extractedPages === 'number' && typeof progress.totalPages === 'number') {
+            outcome.progress = { extracted_pages: progress.extractedPages, total_pages: progress.totalPages };
+        }
+        if (typeof resultUrl?.jsonUrl === 'string')
+            outcome.jsonUrl = resultUrl.jsonUrl;
+        if (typeof data.errorMsg === 'string')
+            outcome.errorMsg = data.errorMsg;
+        return outcome;
+    }
+    async function load(jsonUrl, signal) {
+        // ⛔ 结果地址是**预签名**的对象存储 URL（实测主机 `paddleocr-store-8.bj.bcebos.com`，与作业
+        //    API 不同域）。带上我们的 bearer，BOS 会把它当作待验签请求并索要 `date` 头，直接
+        //    HTTP 400 `MissingDateHeader`；不带才拿得下来（实测 200 / 308 KB）。而且把 token 发给
+        //    第三方存储域本身就是密钥外流——这条路**只**靠签名过的 URL 鉴权。
+        let outcome;
+        try {
+            outcome = await options.request({ url: jsonUrl, accept: 'application/json', maxBytes: resultMaxBytes, maxContentChars: resultMaxBytes }, signal);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'ABORTED' || (error instanceof Error && error.name === 'AbortError'))
+                throw error;
+            throw mapTransportFailure(error);
+        }
+        // 结果 JSONL 单独定上限（15 页实测 258 KB），超限就是真超限，不能继续当完整文档解析。
+        if (outcome.truncated) {
+            throw new OcrError('RESULT_INVALID', `解析结果超出 ${resultMaxBytes} 字节上限并被截断：整份文档作废，不给半份 markdown`);
+        }
+        const sourcePages = [];
+        for (const line of outcome.text.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            let record;
+            try {
+                record = asRecord(JSON.parse(trimmed));
+            }
+            catch {
+                throw new OcrError('RESULT_INVALID', `结果 JSONL 有一行不是 JSON（长度 ${trimmed.length}）：整份文档作废`);
+            }
+            if (!record)
+                throw new OcrError('RESULT_INVALID', '结果 JSONL 的某一行不是对象');
+            // ⛔ 成功行**也带** `errorMsg`：2026-09-25 实测每行都是 `{errorCode: 0, errorMsg: "Success", …}`。
+            //    判据只能是 `errorCode !== 0`——把"有 errorMsg"当失败会把每一份成功解析的文档报成失败。
+            const errorCode = record.errorCode;
+            const failed = typeof errorCode === 'number' ? errorCode !== 0 : typeof errorCode === 'string' ? errorCode !== '0' && errorCode.length > 0 : false;
+            const result = asRecord(record.result);
+            const layouts = Array.isArray(result?.layoutParsingResults) ? result.layoutParsingResults : [];
+            if (failed) {
+                throw new OcrError('JOB_FAILED', `上游批次失败 errorCode=${String(errorCode)}：${typeof record.errorMsg === 'string' && record.errorMsg.length > 0 ? record.errorMsg : '(无 errorMsg)'}`);
+            }
+            for (const item of layouts) {
+                const layout = asRecord(item);
+                const markdown = asRecord(layout?.markdown);
+                if (typeof markdown?.text !== 'string') {
+                    throw new OcrError('RESULT_INVALID', 'layoutParsingResults 的一项缺 markdown.text：不给静默空白页');
+                }
+                sourcePages.push({
+                    page: sourcePages.length + 1,
+                    markdown: markdown.text,
+                    images: markdown.images && typeof markdown.images === 'object' ? Object.keys(markdown.images).length : 0,
+                });
+            }
+        }
+        if (sourcePages.length === 0)
+            throw new OcrError('RESULT_INVALID', '上游返回 0 页：空 markdown 会被当成"这篇文档没有内容"，比报错危险');
+        if (sourcePages.length > PADDLE_OCR_MAX_PAGES) {
+            throw new OcrError('TOO_MANY_PAGES', `解析出 ${sourcePages.length} 页，超出上游 ${PADDLE_OCR_MAX_PAGES} 页口径`);
+        }
+        return buildOcrDocument(sourcePages);
+    }
+    async function wait(jobId, signal, prior) {
+        const started = now();
+        let last = prior;
+        let attempts = 0;
+        while (true) {
+            const elapsed = now() - started;
+            if (elapsed >= waitBudgetMs) {
+                return { status: 'pending', job_id: jobId, ...(last ? { progress: last } : {}), elapsed_ms: elapsed };
+            }
+            const state = await poll(jobId, signal);
+            attempts += 1;
+            if (state.progress)
+                last = state.progress;
+            if (state.state === 'done') {
+                if (!state.jsonUrl)
+                    throw new OcrError('RESULT_INVALID', `作业标记 done 但没有 resultUrl.jsonUrl：${jobId}`);
+                const document = await load(state.jsonUrl, signal);
+                return {
+                    status: 'done',
+                    job_id: jobId,
+                    document,
+                    json_url: state.jsonUrl,
+                    ...(last ? { progress: last } : {}),
+                    elapsed_ms: now() - started,
+                };
+            }
+            if (state.state === 'failed') {
+                throw new OcrError('JOB_FAILED', `上游作业失败：${state.errorMsg ?? '(没有 errorMsg 字段)'}`);
+            }
+            try {
+                await sleep(Math.min(pollIntervalMs, Math.max(200, waitBudgetMs - (now() - started))), signal);
+            }
+            catch (error) {
+                const code = error?.code;
+                if (code === 'ABORTED' || (error instanceof Error && error.name === 'AbortError'))
+                    throw error;
+                // 睡眠本身不会失败成别的错误；真出了就算作业状态未知，别硬编成上游错误。
+                throw new OcrError('RESULT_INVALID', `轮询等待异常（已轮询 ${attempts} 次）：${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    async function parse(input) {
+        const jobId = await submit(input);
+        return wait(jobId, input.signal);
+    }
+    return { model, submit, poll, wait, parse, load };
+}

package/lib/ocr/markdown.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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），帮不上。
+ *
+ * 归一化只做**无损排版**：不删正文、不改数字、不做摘要。数字一律照抄上游。
+ */
+/** 上游一页的解析产物（我们只取 markdown 文本与图片计数）。 */
+export interface OcrSourcePage {
+    page: number;
+    markdown: string;
+    images: number;
+}
+export interface OcrPageEntry {
+    page: number;
+    /** 该页正文在 `document` 里的起始码点下标（含）。 */
+    start: number;
+    /** 结束下标（不含）。 */
+    end: number;
+    chars: number;
+    /** 该页第一个标题行（索引用，没有则省略）。 */
+    heading?: string;
+}
+export interface OcrDocument {
+    /** 全篇：各页正文以 `<!-- page:N -->` 分隔（渲染不可见，页定位靠它）。 */
+    document: string;
+    pages: OcrPageEntry[];
+    chars: number;
+    images: number;
+    /** 转成 GFM 的 HTML 表数量。 */
+    tables: number;
+    /** 剥掉的 style 样板字符数（回执里用来证明"不是截断，是排版噪音"）。 */
+    styleCharsRemoved: number;
+}
+export interface OcrHit {
+    page: number;
+    at: number;
+    excerpt: string;
+}
+declare const PAGE_MARKER_PREFIX = "<!-- page:";
+export interface NormalizedMarkdown {
+    markdown: string;
+    tables: number;
+    styleCharsRemoved: number;
+}
+/** 剥样式 + HTML 表转 GFM + 收空行。对不含 HTML 的正文近似恒等。 */
+export declare function normalizeOcrMarkdown(source: string): NormalizedMarkdown;
+/** 把逐页 markdown 拼成一份文档，并算出**页偏移索引**（按页取回与关键词定位都靠它）。 */
+export declare function buildOcrDocument(sourcePages: OcrSourcePage[]): OcrDocument;
+/**
+ * 页区间解析：`"1-3"` / `"5"` / `"2-4,9"`（1 起始，闭区间）。
+ * 越界页码**响亮失败**而不是静默少给——"这页没有"和"我没给"在回执里必须能区分。
+ */
+export declare function parsePageRange(spec: string, totalPages: number): number[];
+export interface PageExcerpt {
+    page: number;
+    chars: number;
+    heading?: string;
+    text: string;
+}
+/** 按页切出正文（纯字符串切片，不重跑上游）。 */
+export declare function selectPages(document: OcrDocument, pages: number[]): PageExcerpt[];
+/**
+ * 关键词定位：在**已落盘的文档**里找命中，回带页号的上下文片段。
+ *
+ * 为什么不靠 `pages` 硬读：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算 6,144——
+ * 想拿财务预测表就得能"跳着看"。上游页区间不影响算力（整篇都算过），所以定位必须在这份
+ * 归一化文本上做，不再出网。
+ */
+export declare function locateQuery(document: OcrDocument, query: string, limit: number, windowChars: number): OcrHit[];
+export { PAGE_MARKER_PREFIX };