@v587d/capital-generation 2.8.3 → 2.9.1

package/lib/net/eastmoney-client.d.ts

@@ -1,42 +1,10 @@
 /**
- * 东财（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）。
- */
-/**
- * 东财系请求的**共享最小间隔**（毫秒）。
- *
- * 1000ms = 1 次/秒，低于「>5 次/秒」阈值，并同时满足「1 分钟 200 次 / 5 分钟 300 次」这类累计窗口口径。
+ * Shared eastmoney network face: one process-wide throttle and one request path for both data
+ * planes (Hub datasets and web_retriever text). Eastmoney limits by egress IP, so two throttles
+ * equal no throttle. Throttling/status mapping live only here; SSRF checking, when needed, is
+ * injected via `transport` and owned by the caller's `createHttpRequester`.
  */
+/** 1 request/second, below eastmoney's >5/s trigger and within its cumulative windows. */
 export declare const EASTMONEY_MIN_INTERVAL_MS = 1000;
 export interface EastmoneyFetchInit {
     headers?: Record<string, string>;
@@ -44,42 +12,30 @@ export interface EastmoneyFetchInit {
 }
 export interface EastmoneyResponse {
     status: number;
-    /** 注入式 transport（闸门适配层）可以不提供 headers。 */
     headers?: Headers;
     text: string;
 }
 export interface EastmoneyClient {
     /**
-     * 发一个东财请求并读回正文。**只负责**：串行 + 最小间隔、合并请求头、发请求、读正文、
-     * 把 HTTP 错误状态归类成带 `status` 的错误。
-     *
-     * 刻意**不**解析 JSON、不定义错误码：两个调用方的错误码语义不同（数据面是
-     * `eastmoney_http_error` / `eastmoney_rate_limit`，web_retriever 是 `SourceError` 的
-     * `UPSTREAM` / `NETWORK`），在这一层统一会覆盖掉调用方自己的契约。
-     */
+       * Send and read text: serialization, minimum interval, headers, status classification. No JSON
+       * or error codes; callers keep their own semantics.
+       */
     fetchText(url: string, init?: EastmoneyFetchInit): Promise<EastmoneyResponse>;
-    /**
-     * 同上，但把响应解析成 JSON。
-     *
-     * 为什么与 `fetchText` 分开而不是让调用方自己 `JSON.parse(text)`：数据面的既有测试用具
-     * **只有 `json()` 没有 `text()`** 的假 Response。走 `response.json()` 既保持数据面原有形状，
-     * 也让"解析失败"能在这一层被归成同一种错误（调用方仍可自行决定错误码）。
-     */
+    /** Separate from fetchText because data-plane test doubles only provide `json()`, and parse failures classify here. */
     fetchJson(url: string, init?: EastmoneyFetchInit): Promise<unknown>;
 }
-/**: 传输层错误。`status` 只在"上游返回了 HTTP 错误状态"时给出。 */
+/** Transport error; `status` is set only when upstream returned an HTTP error status. */
 export declare class EastmoneyTransportError extends Error {
     readonly status?: number | undefined;
     constructor(message: string, status?: number | undefined);
 }
-/** 传输器返回的最小响应形状（真实 `Response` 天然满足；闸门适配层按此构造）。 */
 export interface EastmoneyTransportResponse {
     status: number;
     headers?: Headers;
     text(): Promise<string>;
     json(): Promise<unknown>;
 }
-/** 可注入传输器：默认裸 `fetch`（数据面），web_retriever 侧注入 SSRF 闸门实现。 */
+/** Injectable transport; defaults to bare fetch, web_retriever injects its SSRF-gated implementation. */
 export type EastmoneyTransport = (url: string, init: {
     headers: Record<string, string>;
     signal?: AbortSignal;
@@ -87,18 +43,10 @@ export type EastmoneyTransport = (url: string, init: {
 export declare function createEastmoneyClient(options?: {
     userAgent?: string;
     minIntervalMs?: number;
-    /** 注入进程级共享节流器时 `minIntervalMs` 失效（节流只该有一份）。 */
     throttle?: <T>(task: () => Promise<T>) => Promise<T>;
     transport?: EastmoneyTransport;
 }): EastmoneyClient;
-/**
- * **进程级共享节流器**：数据面与 web_retriever 侧可能各持一个客户端实例（transport 不同），
- * 但东财风控按出口 IP 计，节流必须仍只有一份。两侧客户端都从这里取。
- */
+/** Process-wide throttle: both clients (different transports) hit the same egress IP, so they share one. */
 export declare function sharedEastmoneyThrottle(): <T>(task: () => Promise<T>) => Promise<T>;
-/**
- * **进程级单例**（数据面用，默认裸 fetch transport）：所有默认客户端共享同一个节流器，
- * 等于回到"两份独立限流"的老问题的解法。宿主进程内所有东财请求都应经这里或
- * 显式注入 `sharedEastmoneyThrottle()` 的实例。
- */
+/** Process-wide client for the data plane (bare fetch), sharing the process throttle. */
 export declare function sharedEastmoneyClient(): EastmoneyClient;

package/lib/net/eastmoney-client.js

@@ -1,46 +1,14 @@
 /**
- * 东财（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）。
+ * Shared eastmoney network face: one process-wide throttle and one request path for both data
+ * planes (Hub datasets and web_retriever text). Eastmoney limits by egress IP, so two throttles
+ * equal no throttle. Throttling/status mapping live only here; SSRF checking, when needed, is
+ * injected via `transport` and owned by the caller's `createHttpRequester`.
  */
 import { createRequestThrottle } from './throttle.js';
-/**
- * 东财系请求的**共享最小间隔**（毫秒）。
- *
- * 1000ms = 1 次/秒，低于「>5 次/秒」阈值，并同时满足「1 分钟 200 次 / 5 分钟 300 次」这类累计窗口口径。
- */
+/** 1 request/second, below eastmoney's >5/s trigger and within its cumulative windows. */
 export const EASTMONEY_MIN_INTERVAL_MS = 1000;
 const DEFAULT_USER_AGENT = 'Mozilla/5.0';
-/**: 传输层错误。`status` 只在"上游返回了 HTTP 错误状态"时给出。 */
+/** Transport error; `status` is set only when upstream returned an HTTP error status. */
 export class EastmoneyTransportError extends Error {
     status;
     constructor(message, status) {
@@ -53,7 +21,7 @@ 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）共用这一份，避免状态判定被复制。 */
+    /** Throttle + send + status check, shared by the text and json paths. */
     const send = (url, init) => throttle(async () => {
         if (init.signal?.aborted) {
             const error = new Error('eastmoney request aborted');
@@ -68,17 +36,15 @@ export function createEastmoneyClient(options = {}) {
             });
         }
         catch (error) {
-            // 取消原样抛出（`AbortError`），调用方据此区分"网络失败"与"调用方不要了"。
+            // Abort passes through unchanged so callers can tell cancellation from network failure.
             if (error instanceof Error && error.name === 'AbortError')
                 throw error;
-            // 已带分类 `code` 的错误（如闸门注入的 `LocalFetchError`：ABORTED/TIMEOUT/REDIRECT…）
-            // 原样抛出：再包一层会把"取消"降级成网络失败（docs/dev/web-retriever.md §4.2），也丢掉失败原因。
+            // Errors that already carry a classification code pass through: wrapping would downgrade cancellation to a network failure.
             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 两者都有）。
+        // Check status, not response.ok: some test doubles only expose status/text/json.
         if (response.status >= 400) {
             throw new EastmoneyTransportError(`eastmoney returned HTTP ${response.status}`, response.status);
         }
@@ -98,20 +64,13 @@ function createEastmoneyTransport() {
     return (url, init) => globalThis.fetch(url, init);
 }
 let sharedThrottle;
-/**
- * **进程级共享节流器**：数据面与 web_retriever 侧可能各持一个客户端实例（transport 不同），
- * 但东财风控按出口 IP 计，节流必须仍只有一份。两侧客户端都从这里取。
- */
+/** Process-wide throttle: both clients (different transports) hit the same egress IP, so they share one. */
 export function sharedEastmoneyThrottle() {
     sharedThrottle ??= createRequestThrottle(EASTMONEY_MIN_INTERVAL_MS);
     return sharedThrottle;
 }
 let shared;
-/**
- * **进程级单例**（数据面用，默认裸 fetch transport）：所有默认客户端共享同一个节流器，
- * 等于回到"两份独立限流"的老问题的解法。宿主进程内所有东财请求都应经这里或
- * 显式注入 `sharedEastmoneyThrottle()` 的实例。
- */
+/** Process-wide client for the data plane (bare fetch), sharing the process throttle. */
 export function sharedEastmoneyClient() {
     shared ??= createEastmoneyClient({ throttle: sharedEastmoneyThrottle() });
     return shared;

package/lib/net/throttle.d.ts

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

package/lib/net/throttle.js

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

package/lib/ocr/client.d.ts

@@ -1,26 +1,17 @@
 /**
- * PaddleOCR AIStudio **异步 job** 客户端（`ocr` 的上游实现，唯一一份出网实现）。
+ * Async PaddleOCR jobs client — the plugin's only OCR egress implementation.
  *
- * 生命周期（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[]` 一项一页）。
+ * Flow: POST job → poll state → fetch result JSONL (one layout result per page).
  *
- * ⛔ 两条只能从真报文里拿到的事实，决定了本文件的形状：
- * 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` 自己处理。
+ * ⛔ Two response-shape facts determine the code below:
+ * 1. Business failures arrive as HTTP 200 with `{ code: nonzero, jobId absent }`, so always check `code`.
+ * 2. Unknown `optionalPayload` keys are silently ignored; send only documented example keys.
  */
 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 页。超页是**上游会失败**，提前拦比事后猜便宜。 */
+/** Upstream PDF page limit; reject earlier than letting the remote job fail. */
 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 {
@@ -31,7 +22,7 @@ export interface OcrProgress {
     extracted_pages: number;
     total_pages: number;
 }
-/** 一次轮询看到的作业状态（只保留我们用得上的字段）。 */
+/** Poll status, narrowed to fields used here. */
 export interface OcrJobState {
     state: string;
     progress?: OcrProgress;
@@ -39,9 +30,9 @@ export interface OcrJobState {
     errorMsg?: string;
 }
 export interface OcrSubmitInput {
-    /** 公网可达的 `.pdf` 直链：由**上游**去取文件，本机不落任何字节。 */
+    /** Public PDF URL fetched by the provider; no local bytes are involved. */
     fileUrl?: string;
-    /** 本地文档字节（`file` 形态）：走 multipart 上传。 */
+    /** Local document bytes uploaded as multipart. */
     file?: {
         bytes: Uint8Array;
         filename: string;
@@ -53,7 +44,7 @@ export interface OcrWaitOutcome {
     status: 'done' | 'pending';
     job_id: string;
     progress?: OcrProgress;
-    /** `status === 'done'` 时一定有。 */
+    /** Present whenever status is done. */
     document?: OcrDocument;
     json_url?: string;
     elapsed_ms: number;
@@ -66,7 +57,7 @@ export interface PaddleOcrClientOptions {
     pollIntervalMs?: number;
     waitBudgetMs?: number;
     resultMaxBytes?: number;
-    /** 注入以便测试：睡眠必须可取消。 */
+    /** Injectable sleep keeps polling cancellable. */
     sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
     now?: () => number;
 }
@@ -75,7 +66,7 @@ export interface PaddleOcrClient {
     submit(input: OcrSubmitInput): Promise<string>;
     poll(jobId: string, signal: AbortSignal): Promise<OcrJobState>;
     wait(jobId: string, signal: AbortSignal, progress?: OcrProgress): Promise<OcrWaitOutcome>;
-    /** 提交并等到有结果（或自有预算耗尽回 pending）。 */
+    /** Submit and poll until terminal, or return pending when the wait budget is exhausted. */
     parse(input: OcrSubmitInput): Promise<OcrWaitOutcome>;
     load(jsonUrl: string, signal: AbortSignal): Promise<OcrDocument>;
 }

package/lib/ocr/client.js

@@ -1,30 +1,21 @@
 /**
- * PaddleOCR AIStudio **异步 job** 客户端（`ocr` 的上游实现，唯一一份出网实现）。
+ * Async PaddleOCR jobs client — the plugin's only OCR egress implementation.
  *
- * 生命周期（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[]` 一项一页）。
+ * Flow: POST job → poll state → fetch result JSONL (one layout result per page).
  *
- * ⛔ 两条只能从真报文里拿到的事实，决定了本文件的形状：
- * 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` 自己处理。
+ * ⛔ Two response-shape facts determine the code below:
+ * 1. Business failures arrive as HTTP 200 with `{ code: nonzero, jobId absent }`, so always check `code`.
+ * 2. Unknown `optionalPayload` keys are silently ignored; send only documented example keys.
  */
 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 页。超页是**上游会失败**，提前拦比事后猜便宜。 */
+/** Upstream PDF page limit; reject earlier than letting the remote job fail. */
 export const PADDLE_OCR_MAX_PAGES = 100;
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
-/** 自有等待预算必须**小于**工具声明的 `timeoutMs`：留出不确定返回与写盘的余量。 */
+/** Wait budget stays below the tool timeout, leaving time for the response and disk write. */
 const DEFAULT_WAIT_BUDGET_MS = 200_000;
-/** 结果 JSONL 的体积上限（实测 15 页 258 KB；上限给到 8 MB 并在超限时响亮失败）。 */
+/** JSONL response cap; exceeding it fails loudly rather than parsing a partial document. */
 const DEFAULT_RESULT_MAX_BYTES = 8 * 1024 * 1024;
 export class OcrError extends Error {
     code;
@@ -55,16 +46,14 @@ function sleepAbortable(ms, signal) {
     });
 }
 /**
- * 把传输层异常翻成 OCR 错误码。
- *
- * ⚠️ `createHttpRequester` 对 4xx/5xx 抛的是 `LocalFetchError('HTTP', '… returned HTTP 401')`，
- * 状态码只在消息文本里。这里按文本识别鉴权类失败（401/403）**只为了把"该去卡片填 token"
- * 这条最有用的话送到模型面前**；识别不到就退回 `UPSTREAM`，绝不假装知道上游说了什么。
+ * Map transport exceptions to OCR codes. `LocalFetchError` carries the HTTP status
+ * only in its message, so recognize 401/403 to point at the token card; otherwise
+ * fall back to UPSTREAM rather than infer upstream details.
  */
 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('NO_CREDENTIAL', `PaddleOCR 拒绝鉴权（${message}）：请在 设置 → 插件 → 自动模式填写 PaddleOCR Token`);
     }
     return new OcrError('UPSTREAM', message);
 }
@@ -79,11 +68,11 @@ export function createPaddleOcrClient(options) {
     async function authorizedHeaders() {
         const token = await options.resolveToken();
         if (!token) {
-            throw new OcrError('NO_CREDENTIAL', 'PaddleOCR Token 未配置：在 设置 → 插件 → 插件配置 → Capital 模式 填写（credentials 引用 PADDLE_OCR_TOKEN，环境变量同名亦可）');
+            throw new OcrError('NO_CREDENTIAL', 'PaddleOCR Token 未配置：在 设置 → 插件 → 插件配置 → 自动模式填写（credentials 引用 PADDLE_OCR_TOKEN，环境变量同名亦可）');
         }
         return { authorization: `bearer ${token}` };
     }
-    /** 发一次请求并**校验 body.code**：上游用 HTTP 200 装业务错误（见文件头 ⛔ 1）。 */
+    /** Send and validate `body.code`; HTTP 200 can still be a business error. */
     async function call(request, signal) {
         let outcome;
         try {
@@ -111,13 +100,13 @@ export function createPaddleOcrClient(options) {
         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('NO_CREDENTIAL', `PaddleOCR 未鉴权（code 401 ${message}）：请在 设置 → 插件 → 自动模式填写 Token`);
             throw new OcrError('UPSTREAM', `PaddleOCR 返回业务错误 code=${String(code)}：${message}`);
         }
         return parsed;
     }
     function optionalPayload(charts) {
-        // 只带官方示例出现过的三个键（文件头 ⛔ 2）。
+        // Send only the three documented example keys.
         return { useDocOrientationClassify: false, useDocUnwarping: false, useChartRecognition: charts };
     }
     async function submit(input) {
@@ -134,15 +123,12 @@ export function createPaddleOcrClient(options) {
             const form = new FormData();
             form.append('model', model);
             form.append('optionalPayload', JSON.stringify(payload));
-            // `fs.readBytes` 的返回类型是 `Uint8Array<ArrayBufferLike>`，而 `Blob` 只接受
-            // ArrayBuffer 背书的视图；字节确实是新分配的 ArrayBuffer，在边界上收敛一次类型。
+            // Narrow the buffer-backed view at this runtime boundary; the bytes are freshly allocated.
             form.append('file', new Blob([file.bytes], { type: 'application/octet-stream' }), file.filename);
             extraHeaders = {};
             body = form;
         }
-        // ⛔ `headers`（bearer）与 `extraHeaders`（content-type）**都要**带上：只传后者就等于
-        //    把作业提交发成一个无鉴权请求（实测 401），而轮询那条路是带着 token 的——
-        //    两条出网路径形状不一致，恰是"只测接好的那个入口"能长期潜伏的形态。
+        // ⛔ Send both bearer and content-type headers; omitting either makes the two egress paths diverge.
         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) {
@@ -171,10 +157,8 @@ export function createPaddleOcrClient(options) {
         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 鉴权。
+        // ⛔ Fetch the presigned result URL without our bearer: object storage rejects mixed auth
+        // and the token must not leak to a third-party host.
         let outcome;
         try {
             outcome = await options.request({ url: jsonUrl, accept: 'application/json', maxBytes: resultMaxBytes, maxContentChars: resultMaxBytes }, signal);
@@ -185,7 +169,7 @@ export function createPaddleOcrClient(options) {
                 throw error;
             throw mapTransportFailure(error);
         }
-        // 结果 JSONL 单独定上限（15 页实测 258 KB），超限就是真超限，不能继续当完整文档解析。
+        // Cap the result JSONL separately; an oversize response is not a usable document.
         if (outcome.truncated) {
             throw new OcrError('RESULT_INVALID', `解析结果超出 ${resultMaxBytes} 字节上限并被截断：整份文档作废，不给半份 markdown`);
         }
@@ -203,8 +187,7 @@ export function createPaddleOcrClient(options) {
             }
             if (!record)
                 throw new OcrError('RESULT_INVALID', '结果 JSONL 的某一行不是对象');
-            // ⛔ 成功行**也带** `errorMsg`：2026-09-25 实测每行都是 `{errorCode: 0, errorMsg: "Success", …}`。
-            //    判据只能是 `errorCode !== 0`——把"有 errorMsg"当失败会把每一份成功解析的文档报成失败。
+            // ⛔ Successful rows also carry errorMsg; use errorCode !== 0, not field presence.
             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);
@@ -268,7 +251,7 @@ export function createPaddleOcrClient(options) {
                 const code = error?.code;
                 if (code === 'ABORTED' || (error instanceof Error && error.name === 'AbortError'))
                     throw error;
-                // 睡眠本身不会失败成别的错误；真出了就算作业状态未知，别硬编成上游错误。
+                // A sleep failure means job state is unknown; do not relabel it as an upstream error.
                 throw new OcrError('RESULT_INVALID', `轮询等待异常（已轮询 ${attempts} 次）：${error instanceof Error ? error.message : String(error)}`);
             }
         }

package/lib/ocr/markdown.d.ts

@@ -1,15 +1,10 @@
 /**
- * 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），帮不上。
- *
- * 归一化只做**无损排版**：不删正文、不改数字、不做摘要。数字一律照抄上游。
+ * PaddleOCR output -> model-readable markdown (the only implementation). Upstream emits
+ * tables as inline HTML with per-cell `style=`, so on a measured 15-page report ~60% of
+ * characters were style boilerplate; `prettifyMarkdown`-style flags are silently ignored.
+ * Normalization is lossless layout only: no text, numbers or tables are dropped.
  */
-/** 上游一页的解析产物（我们只取 markdown 文本与图片计数）。 */
+/** One page as returned upstream (we use markdown text and image count). */
 export interface OcrSourcePage {
     page: number;
     markdown: string;
@@ -17,23 +12,23 @@ export interface OcrSourcePage {
 }
 export interface OcrPageEntry {
     page: number;
-    /** 该页正文在 `document` 里的起始码点下标（含）。 */
+    /** Code-point offset into `document` (inclusive). */
     start: number;
-    /** 结束下标（不含）。 */
+    /** End offset (exclusive). */
     end: number;
     chars: number;
-    /** 该页第一个标题行（索引用，没有则省略）。 */
+    /** First heading line on the page, for the index. */
     heading?: string;
 }
 export interface OcrDocument {
-    /** 全篇：各页正文以 `<!-- page:N -->` 分隔（渲染不可见，页定位靠它）。 */
+    /** Pages separated by `<!-- page:N -->`; invisible when rendered, used for page lookup. */
     document: string;
     pages: OcrPageEntry[];
     chars: number;
     images: number;
-    /** 转成 GFM 的 HTML 表数量。 */
+    /** Number of HTML tables converted to GFM. */
     tables: number;
-    /** 剥掉的 style 样板字符数（回执里用来证明"不是截断，是排版噪音"）。 */
+    /** Stripped style characters, so the receipt can prove layout noise, not truncation. */
     styleCharsRemoved: number;
 }
 export interface OcrHit {
@@ -47,13 +42,13 @@ export interface NormalizedMarkdown {
     tables: number;
     styleCharsRemoved: number;
 }
-/** 剥样式 + HTML 表转 GFM + 收空行。对不含 HTML 的正文近似恒等。 */
+/** Strip styles, convert HTML tables to GFM, collapse blank lines; near-identity otherwise. */
 export declare function normalizeOcrMarkdown(source: string): NormalizedMarkdown;
-/** 把逐页 markdown 拼成一份文档，并算出**页偏移索引**（按页取回与关键词定位都靠它）。 */
+/** Join per-page markdown and record page offsets, used by page reads and keyword lookup. */
 export declare function buildOcrDocument(sourcePages: OcrSourcePage[]): OcrDocument;
 /**
- * 页区间解析：`"1-3"` / `"5"` / `"2-4,9"`（1 起始，闭区间）。
- * 越界页码**响亮失败**而不是静默少给——"这页没有"和"我没给"在回执里必须能区分。
+ * `"1-3"` / `"5"` / `"2-4,9"` (1-based, inclusive). Out-of-range pages fail loudly:
+ * "page absent" and "not requested" must stay distinguishable in the receipt.
  */
 export declare function parsePageRange(spec: string, totalPages: number): number[];
 export interface PageExcerpt {
@@ -62,14 +57,13 @@ export interface PageExcerpt {
     heading?: string;
     text: string;
 }
-/** 按页切出正文（纯字符串切片，不重跑上游）。 */
+/** Slice pages out of the stored text; never re-runs upstream. */
 export declare function selectPages(document: OcrDocument, pages: number[]): PageExcerpt[];
 /**
- * 关键词定位：在**已落盘的文档**里找命中，回带页号的上下文片段。
- *
- * 为什么不靠 `pages` 硬读：一份 15 页研报归一化后约 2.7 万字符，而工具输出预算 6,144——
- * 想拿财务预测表就得能"跳着看"。上游页区间不影响算力（整篇都算过），所以定位必须在这份
- * 归一化文本上做，不再出网。
+ * Keyword lookup over the persisted normalized text (no egress): the output budget is
+ * smaller than a whole report, so callers must be able to jump. Adjacent hits merge into
+ * one window, and windows never cross a page boundary — a miscited page is worse than
+ * fewer hits — which also keeps `<!-- page:N -->` markers out of excerpts.
  */
 export declare function locateQuery(document: OcrDocument, query: string, limit: number, windowChars: number): OcrHit[];
 export { PAGE_MARKER_PREFIX };