@onco-foundry/mask-port 0.1.6 → 0.2.1

package/README.md

@@ -0,0 +1,10 @@
+# mask-port
+
+`createLlmSensitiveWordFinder` 使用 Anthropic 兼容 Messages API 提取敏感词，供图片脱敏器定位。
+
+## 模型请求预算
+
+- `maxTokens`：正整数，默认 **65536**（此前固定为 16384）。推理型模型的思考可能占用同一预算；实际消耗由模型响应决定，设置上限不等于每次用满。
+- `timeoutMs`：正整数，默认 **300000 ms**（此前为 120000 ms）。调用方包裹的 OCR 请求也需提供足够的总超时；内层增加超时不会延长外层截止时间。
+
+按供应商和所选模型支持的输出上限设置 `maxTokens`，支持较小预算的模型需显式覆盖默认值。无效配置在创建判定器时抛错。配置调整不改变输出格式校验，也不会将缺失输出视为脱敏成功。

package/dist/create_masker.d.ts

@@ -2,6 +2,7 @@ import type { Masker } from './masker.ts';
 import { type QwenAgentMaskerOptions } from './qwen_agent_masker.ts';
 import { type TencentMaskerOptions } from './tencent_masker.ts';
 import { type TextInMaskerOptions } from './textin_masker.ts';
+import { type PaddleMaskerOptions } from './paddle_masker.ts';
 /**
  * 脱敏器的装配选项：kind 判别用哪个实现。
  * 加新供应商时在这里加一个 union 成员，调用方只改 kind。
@@ -13,6 +14,8 @@ export type MaskerOptions = {
 } & TencentMaskerOptions) | ({
     readonly kind: 'textin';
 } & TextInMaskerOptions) | ({
+    readonly kind: 'paddle';
+} & PaddleMaskerOptions) | ({
     readonly kind: 'qwen-agent-name';
 } & QwenAgentMaskerOptions);
 /** 脱敏端口的唯一工厂：换供应商只改 kind，调用方不 import 具体实现。 */

package/dist/create_masker.js

@@ -2,6 +2,7 @@ import { createFakeMasker } from './fake_masker.js';
 import { createQwenAgentMasker, } from './qwen_agent_masker.js';
 import { createTencentMasker } from './tencent_masker.js';
 import { createTextInMasker } from './textin_masker.js';
+import { createPaddleMasker } from './paddle_masker.js';
 /** 脱敏端口的唯一工厂：换供应商只改 kind，调用方不 import 具体实现。 */
 export const createMasker = async (options) => {
     switch (options.kind) {
@@ -11,6 +12,8 @@ export const createMasker = async (options) => {
             return createTencentMasker(options);
         case 'textin':
             return createTextInMasker(options);
+        case 'paddle':
+            return createPaddleMasker(options);
         case 'qwen-agent-name':
             return await createQwenAgentMasker(options);
     }

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { MASK_TARGETS, type Masker, type MaskMappingEntry, type MaskRequest, type MaskResult, type MaskTarget, } from './masker.ts';
 export { createMasker, type MaskerOptions } from './create_masker.ts';
+export { createPaddleMasker, type PaddleMaskerOptions } from './paddle_masker.ts';
 export { createTencentMasker, type TencentMaskerOptions } from './tencent_masker.ts';
-export { createTextInMasker, findSensitiveWordsByRules, type SensitiveWord, type SensitiveWordFinder, type TextInMaskerOptions, } from './textin_masker.ts';
+export { createTextInMasker, type TextInMaskerOptions, } from './textin_masker.ts';
+export { findSensitiveWordsByRules, type SensitiveWord, type SensitiveWordFinder, } from './sensitive_word_finder.ts';
 export { redactTextByMapping } from './redact_text.ts';
 export { createLlmSensitiveWordFinder, type LlmSensitiveWordFinderOptions, } from './llm_sensitive_word_finder.ts';
 export { createQwenAgentMasker, qwenAgentNameMaskCapabilityCard, qwenAgentNameMaskInputSchema, type QwenAgentMasker, type QwenAgentMaskerOptions, type QwenAgentNameMaskInput, } from './qwen_agent_masker.ts';

package/dist/index.js

@@ -1,7 +1,9 @@
 export { MASK_TARGETS, } from './masker.js';
 export { createMasker } from './create_masker.js';
+export { createPaddleMasker } from './paddle_masker.js';
 export { createTencentMasker } from './tencent_masker.js';
-export { createTextInMasker, findSensitiveWordsByRules, } from './textin_masker.js';
+export { createTextInMasker, } from './textin_masker.js';
+export { findSensitiveWordsByRules, } from './sensitive_word_finder.js';
 export { redactTextByMapping } from './redact_text.js';
 export { createLlmSensitiveWordFinder, } from './llm_sensitive_word_finder.js';
 export { createQwenAgentMasker, qwenAgentNameMaskCapabilityCard, qwenAgentNameMaskInputSchema, } from './qwen_agent_masker.js';

package/dist/llm_sensitive_word_finder.d.ts

@@ -6,11 +6,14 @@
  * 注意：OCR 全文含隐私，启用它意味着文本出域给该模型服务；
  * 只有该服务被批准作为隐私数据处理方时才可装配。
  */
-import type { SensitiveWordFinder } from './textin_masker.ts';
+import type { SensitiveWordFinder } from './sensitive_word_finder.ts';
 export type LlmSensitiveWordFinderOptions = {
     readonly baseURL: string;
     readonly apiKey: string;
     readonly model: string;
+    /** 输出预算，包含推理 token；默认 65536，调用方须匹配模型支持的上限。 */
+    readonly maxTokens?: number;
+    /** 单次模型请求超时，默认 300000 ms；外层调用链须给予相应时间。 */
     readonly timeoutMs?: number;
     /** 测试注入缝：替换掉真实的 HTTP 层，不碰网络。 */
     readonly fetch?: typeof fetch;

package/dist/llm_sensitive_word_finder.js

@@ -10,7 +10,8 @@ import { z } from 'zod';
 import { AppError } from '@onco-foundry/errors';
 import { MASK_TARGETS } from './masker.js';
 import { MaskingError } from './masking_error.js';
-const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_MAX_TOKENS = 65_536;
 // prompt 是模块内置资产，不开放注入：本模块定位就是医疗文书脱敏，提取口径由模块自己保证。
 const SYSTEM_PROMPT = `你从医疗文书扫描件（病历、检查报告、住院单等）的 OCR 文本中提取隐私信息。只提取以下类别：
 - patient_name：患者姓名（包括「姓名：」标签后的、正文叙述中出现的）
@@ -67,12 +68,14 @@ export const createLlmSensitiveWordFinder = (options) => {
         baseURL: z.url(),
         apiKey: z.string().trim().min(1),
         model: z.string().trim().min(1),
-    }).safeParse({ baseURL: options.baseURL, apiKey: options.apiKey, model: options.model });
+        maxTokens: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_TOKENS),
+        timeoutMs: z.number().int().positive().max(2_147_483_647).default(DEFAULT_TIMEOUT_MS),
+    }).safeParse({ baseURL: options.baseURL, apiKey: options.apiKey, model: options.model, maxTokens: options.maxTokens, timeoutMs: options.timeoutMs });
     if (!credentials.success) {
         throw new AppError('LLM 敏感词判定器配置非法', 500);
     }
     const doFetch = options.fetch ?? fetch;
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const { maxTokens, timeoutMs } = credentials.data;
     return async (text) => {
         if (text.trim() === '')
             return [];
@@ -91,7 +94,7 @@ export const createLlmSensitiveWordFinder = (options) => {
                     messages: [{ role: 'user', content: text }],
                     temperature: 0,
                     // 推理型模型的思考也吃 max_tokens：给小了会在正文输出前被截断，响应里一个 text 块都没有。
-                    max_tokens: 16384,
+                    max_tokens: maxTokens,
                     stream: false,
                 }),
                 signal: AbortSignal.timeout(timeoutMs),

package/dist/paddle_masker.d.ts

@@ -0,0 +1,14 @@
+import type { Masker } from './masker.ts';
+import { type SensitiveWordFinder } from './sensitive_word_finder.ts';
+export type PaddleMaskerOptions = {
+    readonly baseURL: string;
+    readonly appId: string;
+    readonly secretCode: string;
+    readonly timeoutMs?: number;
+    readonly maxInputBytes?: number;
+    readonly requireAllMatches?: boolean;
+    readonly fetch?: typeof fetch;
+    readonly findSensitiveWords?: SensitiveWordFinder;
+};
+/** 创建使用自建 Paddle OCR token 坐标的医疗图片脱敏器。 */
+export declare const createPaddleMasker: (options: PaddleMaskerOptions) => Masker;

package/dist/paddle_masker.js

@@ -0,0 +1,252 @@
+import { Buffer } from 'node:buffer';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { AppError } from '@onco-foundry/errors';
+import { MaskingError } from './masking_error.js';
+import { clampQuad, polygonSvg, scaleQuad } from './quad.js';
+import { findSensitiveWordsByRules, } from './sensitive_word_finder.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_INPUT_BYTES = 30 * 1024 * 1024;
+const MAX_INPUT_PIXELS = 40_000_000;
+const TOKEN_SAFETY_SCALE = 1.3;
+const RULE_TARGETS = ['id_number', 'phone'];
+const TARGET_LABELS = {
+    patient_name: '姓名',
+    id_number: '证件号',
+    phone: '手机号',
+    address: '地址',
+    doctor_signature: '签字',
+    medical_record_number: '病历号',
+};
+const quad8Schema = z.array(z.number().finite()).length(8);
+const tokenSchema = z.object({
+    text: z.string(),
+    score: z.number().finite().optional(),
+    quad: quad8Schema,
+});
+const lineSchema = z.object({
+    text: z.string(),
+    score: z.number().finite().optional(),
+    quad: quad8Schema,
+    tokens: z.array(tokenSchema).default([]),
+});
+const responseSchema = z.object({
+    code: z.number(),
+    message: z.string().default(''),
+    engine: z.object({
+        name: z.string().min(1),
+        runtime: z.string().min(1),
+    }).optional(),
+    pages: z.array(z.object({
+        width: z.number().positive(),
+        height: z.number().positive(),
+        lines: z.array(lineSchema).default([]),
+    })).optional(),
+});
+const toQuad = (position) => [
+    [position[0], position[1]],
+    [position[2], position[3]],
+    [position[4], position[5]],
+    [position[6], position[7]],
+];
+const locateWordSpans = (lines, recognizedText, word) => {
+    const ranges = [];
+    let offset = 0;
+    for (const line of lines) {
+        ranges.push({ line, start: offset, end: offset + line.text.length });
+        offset += line.text.length + 1;
+    }
+    const occurrences = [];
+    let fromIndex = 0;
+    while (word.length > 0) {
+        const hit = recognizedText.indexOf(word, fromIndex);
+        if (hit < 0)
+            break;
+        fromIndex = hit + word.length;
+        const end = hit + word.length;
+        occurrences.push(ranges.flatMap((range) => {
+            const start = Math.max(hit, range.start);
+            const finish = Math.min(end, range.end);
+            return start < finish
+                ? [{ line: range.line, beginIndex: start - range.start, length: finish - start }]
+                : [];
+        }));
+    }
+    return occurrences;
+};
+/**
+ * 选择与字符区间相交的原生 token。结构不自洽时返回整行框，宁可多盖。
+ */
+const locateSpanQuads = (span) => {
+    if (span.line.tokens.map((token) => token.text).join('') !== span.line.text) {
+        return [toQuad(span.line.quad)];
+    }
+    const end = span.beginIndex + span.length;
+    let offset = 0;
+    const tokens = [];
+    for (const token of span.line.tokens) {
+        const tokenEnd = offset + token.text.length;
+        if (offset < end && tokenEnd > span.beginIndex)
+            tokens.push(token);
+        offset = tokenEnd;
+    }
+    return tokens.length > 0
+        ? tokens.map((token) => toQuad(token.quad))
+        : [toQuad(span.line.quad)];
+};
+const scaledToImage = (quad, scaleX, scaleY) => quad.map(([x, y]) => [x * scaleX, y * scaleY]);
+const validateQuad = (quad, width, height) => {
+    const xs = quad.map(([x]) => x);
+    const ys = quad.map(([, y]) => y);
+    const twiceArea = Math.abs(quad.reduce((sum, [x, y], index) => {
+        const next = quad[(index + 1) % quad.length];
+        return sum + x * next[1] - next[0] * y;
+    }, 0));
+    if (twiceArea < 1
+        || quad.flat().some((value) => !Number.isFinite(value))
+        || Math.min(...xs) < 0
+        || Math.min(...ys) < 0
+        || Math.max(...xs) > width
+        || Math.max(...ys) > height) {
+        throw new MaskingError('mask_coordinates_invalid', 'Paddle 脱敏坐标无效');
+    }
+};
+/** 创建使用自建 Paddle OCR token 坐标的医疗图片脱敏器。 */
+export const createPaddleMasker = (options) => {
+    const parsed = z.object({
+        baseURL: z.url(),
+        appId: z.string().trim().min(1),
+        secretCode: z.string().trim().min(1),
+    }).safeParse(options);
+    if (!parsed.success)
+        throw new AppError('Paddle 脱敏服务配置非法', 500);
+    const baseUrl = options.baseURL.replace(/\/+$/u, '');
+    const doFetch = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const finder = options.findSensitiveWords ?? findSensitiveWordsByRules;
+    return {
+        async mask(request) {
+            if (request.targets.length === 0) {
+                return {
+                    maskedImageBytes: request.imageBytes,
+                    mapping: [],
+                    processorVersion: { engine: 'paddle-token-masker-v1' },
+                };
+            }
+            if (options.findSensitiveWords === undefined) {
+                const unsupported = request.targets.filter((target) => !RULE_TARGETS.includes(target));
+                if (unsupported.length > 0) {
+                    throw new AppError(`Paddle 脱敏内置规则只支持 ${RULE_TARGETS.join('、')}，`
+                        + `不能处理：${unsupported.join('、')}（可注入 findSensitiveWords 扩展）`, 400);
+                }
+            }
+            if (request.imageBytes.byteLength > (options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES)) {
+                throw new AppError('Paddle 脱敏输入图片超过大小上限', 413);
+            }
+            const metadata = await sharp(request.imageBytes, { limitInputPixels: MAX_INPUT_PIXELS })
+                .metadata()
+                .catch(() => {
+                throw new MaskingError('image_decode_failed', 'Paddle 脱敏无法解码输入图片', 400);
+            });
+            if (!metadata.width || !metadata.height) {
+                throw new MaskingError('image_decode_failed', 'Paddle 脱敏无法读取图片尺寸', 400);
+            }
+            const rotation = request.rotationClockwiseDegrees ?? 0;
+            let response;
+            try {
+                response = await doFetch(`${baseUrl}/v1/ocr?rotation_hint=${rotation}`, {
+                    method: 'POST',
+                    headers: {
+                        'x-ti-app-id': options.appId,
+                        'x-ti-secret-code': options.secretCode,
+                        'Content-Type': 'application/octet-stream',
+                    },
+                    body: Buffer.from(request.imageBytes),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (error) {
+                throw new MaskingError('text_recognition_request_failed', `Paddle 脱敏请求未完成：${error instanceof Error ? error.name : '未知错误'}`);
+            }
+            if (!response.ok) {
+                throw new MaskingError('text_recognition_http_failed', `Paddle 脱敏 HTTP ${response.status}`);
+            }
+            const payload = responseSchema.safeParse(await response.json().catch(() => undefined));
+            if (!payload.success) {
+                throw new MaskingError('text_recognition_invalid_response', 'Paddle 脱敏响应结构校验失败');
+            }
+            if (payload.data.code !== 200 || !payload.data.pages) {
+                throw new MaskingError('text_recognition_provider_failed', `Paddle 脱敏接口返回业务错误（code=${payload.data.code}）`);
+            }
+            if (payload.data.pages.length !== 1) {
+                throw new MaskingError('text_recognition_multiple_pages', 'Paddle 脱敏需要单页图片识别结果');
+            }
+            const page = payload.data.pages[0];
+            const lines = page.lines;
+            const recognizedText = lines.map((line) => line.text).join('\n');
+            if (options.requireAllMatches && !recognizedText.trim()) {
+                throw new MaskingError('text_recognition_empty', 'Paddle 脱敏未识别出文字');
+            }
+            let detected;
+            try {
+                detected = await finder(recognizedText);
+            }
+            catch (error) {
+                if (error instanceof MaskingError)
+                    throw error;
+                throw new MaskingError('sensitive_word_failed', '敏感词判定器执行失败');
+            }
+            if (options.requireAllMatches && detected.some((word) => !word.text || !(word.target in TARGET_LABELS) || !recognizedText.includes(word.text))) {
+                throw new MaskingError('sensitive_word_not_locatable', 'Paddle 脱敏判定结果无法定位');
+            }
+            const scaleX = metadata.width / page.width;
+            const scaleY = metadata.height / page.height;
+            const quads = [];
+            const mapping = [];
+            const counters = new Map();
+            for (const word of detected.filter((item) => item.text !== '' && request.targets.includes(item.target))) {
+                let located = 0;
+                for (const spans of locateWordSpans(lines, recognizedText, word.text)) {
+                    const occurrence = spans.flatMap(locateSpanQuads).map((quad) => scaledToImage(quad, scaleX, scaleY));
+                    if (occurrence.length === 0)
+                        continue;
+                    for (const quad of occurrence) {
+                        if (options.requireAllMatches)
+                            validateQuad(quad, metadata.width, metadata.height);
+                        quads.push(clampQuad(scaleQuad(quad, TOKEN_SAFETY_SCALE), metadata.width, metadata.height));
+                    }
+                    located++;
+                    const count = (counters.get(word.target) ?? 0) + 1;
+                    counters.set(word.target, count);
+                    mapping.push({
+                        placeholder: `[${TARGET_LABELS[word.target]}${count}]`,
+                        target: word.target,
+                        originalText: word.text,
+                    });
+                }
+                if (options.requireAllMatches && located === 0) {
+                    throw new MaskingError('sensitive_word_not_locatable', 'Paddle 脱敏敏感词无法定位');
+                }
+            }
+            let maskedImageBytes;
+            try {
+                maskedImageBytes = await sharp(request.imageBytes, { limitInputPixels: MAX_INPUT_PIXELS })
+                    .composite([{ input: polygonSvg(metadata.width, metadata.height, quads), blend: 'over' }])
+                    .jpeg({ quality: 94 })
+                    .toBuffer();
+            }
+            catch {
+                throw new MaskingError('mask_render_failed', 'Paddle 脱敏图片遮盖失败');
+            }
+            const engine = payload.data.engine;
+            return {
+                maskedImageBytes: new Uint8Array(maskedImageBytes),
+                mapping,
+                processorVersion: {
+                    engine: 'paddle-token-masker-v1',
+                    ...(engine ? { model: `${engine.name}@${engine.runtime}` } : {}),
+                },
+            };
+        },
+    };
+};

package/dist/sensitive_word_finder.d.ts

@@ -0,0 +1,10 @@
+import type { MaskTarget } from './masker.ts';
+/** 一个待遮盖的敏感词及其类别。判定哪些词敏感是业务判断，由调用方注入。 */
+export type SensitiveWord = {
+    readonly text: string;
+    readonly target: MaskTarget;
+};
+/** 吃 OCR 原文全文，吐出必须逐字引用原文的敏感词。 */
+export type SensitiveWordFinder = (text: string) => readonly SensitiveWord[] | Promise<readonly SensitiveWord[]>;
+/** 内置规则判定器：身份证号（18 位）与手机号（1 开头 11 位）。 */
+export declare const findSensitiveWordsByRules: (text: string) => readonly SensitiveWord[];

package/dist/sensitive_word_finder.js

@@ -0,0 +1,11 @@
+/** 内置规则判定器：身份证号（18 位）与手机号（1 开头 11 位）。 */
+export const findSensitiveWordsByRules = (text) => {
+    const words = [];
+    for (const match of text.matchAll(/(?<!\d)\d{17}[\dXx](?!\d)/gu)) {
+        words.push({ text: match[0], target: 'id_number' });
+    }
+    for (const match of text.matchAll(/(?<!\d)1[3-9]\d{9}(?!\d)/gu)) {
+        words.push({ text: match[0], target: 'phone' });
+    }
+    return words;
+};

package/dist/textin_masker.d.ts

@@ -9,14 +9,8 @@
  * 下游按 mapping 替换出脱敏文本后可省掉第二次 OCR。注意本引擎接触的是原文图片，
  * 装配它意味着「原文出域给 TextIn」这一策略决定已经做出。
  */
-import type { Masker, MaskTarget } from './masker.ts';
-/** 一个待遮盖的敏感词及其类别。判定「哪些词敏感」是业务判断，由调用方注入。 */
-export type SensitiveWord = {
-    readonly text: string;
-    readonly target: MaskTarget;
-};
-/** 敏感词判定器：吃 OCR 原文全文，吐出要遮盖的词。可同步可异步。 */
-export type SensitiveWordFinder = (text: string) => readonly SensitiveWord[] | Promise<readonly SensitiveWord[]>;
+import type { Masker } from './masker.ts';
+import { type SensitiveWordFinder } from './sensitive_word_finder.ts';
 export type TextInMaskerOptions = {
     readonly appId: string;
     readonly secretCode: string;
@@ -33,8 +27,6 @@ export type TextInMaskerOptions = {
      */
     readonly findSensitiveWords?: SensitiveWordFinder;
 };
-/** 内置规则判定器：身份证号（18 位）与手机号（1 开头 11 位）。 */
-export declare const findSensitiveWordsByRules: (text: string) => readonly SensitiveWord[];
 /**
  * 创建 TextIn 识别脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
  * 同一敏感词出现多次时逐处遮盖、逐处登记 mapping；跨行命中拆成多个框，仍登记为一个实体。

package/dist/textin_masker.js

@@ -15,6 +15,7 @@ import { z } from 'zod';
 import { AppError } from '@onco-foundry/errors';
 import { MaskingError } from './masking_error.js';
 import { clampQuad, polygonSvg, scaleQuad } from './quad.js';
+import { findSensitiveWordsByRules, } from './sensitive_word_finder.js';
 const DEFAULT_TEXTIN_BASE_URL = 'https://api.textin.com';
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_INPUT_BYTES = 30 * 1024 * 1024;
@@ -32,17 +33,6 @@ const TARGET_LABELS = {
     doctor_signature: '签字',
     medical_record_number: '病历号',
 };
-/** 内置规则判定器：身份证号（18 位）与手机号（1 开头 11 位）。 */
-export const findSensitiveWordsByRules = (text) => {
-    const words = [];
-    for (const match of text.matchAll(/(?<!\d)\d{17}[\dXx](?!\d)/gu)) {
-        words.push({ text: match[0], target: 'id_number' });
-    }
-    for (const match of text.matchAll(/(?<!\d)1[3-9]\d{9}(?!\d)/gu)) {
-        words.push({ text: match[0], target: 'phone' });
-    }
-    return words;
-};
 /** TextIn 行坐标：四边形 4 顶点 8 个数，顺序左上、右上、右下、左下。 */
 const quad8Schema = z.array(z.number()).length(8);
 const lineSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onco-foundry/mask-port",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "type": "module",
   "files": [
     "dist",
@@ -17,9 +17,9 @@
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
     "@onco-foundry/capability-registry": "0.1.1",
-    "@onco-foundry/errors": "0.1.1",
     "@onco-foundry/resource-versioning": "0.3.0",
-    "@onco-foundry/trace-port": "0.3.2"
+    "@onco-foundry/errors": "0.1.1",
+    "@onco-foundry/trace-port": "0.3.3"
   },
   "publishConfig": {
     "access": "public"