@onco-foundry/mask-port 0.1.5 → 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,8 +1,11 @@
 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';
 export { createFakeMasker } from './fake_masker.ts';
+export { MaskingError, type MaskingFailureReason } from './masking_error.ts';

package/dist/index.js

@@ -1,8 +1,11 @@
 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';
 export { createFakeMasker } from './fake_masker.js';
+export { MaskingError } from './masking_error.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

@@ -9,7 +9,9 @@
 import { z } from 'zod';
 import { AppError } from '@onco-foundry/errors';
 import { MASK_TARGETS } from './masker.js';
-const DEFAULT_TIMEOUT_MS = 120_000;
+import { MaskingError } from './masking_error.js';
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_MAX_TOKENS = 65_536;
 // prompt 是模块内置资产，不开放注入：本模块定位就是医疗文书脱敏，提取口径由模块自己保证。
 const SYSTEM_PROMPT = `你从医疗文书扫描件（病历、检查报告、住院单等）的 OCR 文本中提取隐私信息。只提取以下类别：
 - patient_name：患者姓名（包括「姓名：」标签后的、正文叙述中出现的）
@@ -46,13 +48,13 @@ const extractJsonArray = (content) => {
     const start = cleaned.indexOf('[');
     const end = cleaned.lastIndexOf(']');
     if (start < 0 || end <= start) {
-        throw new AppError('LLM 敏感词提取返回的结构不是 JSON 数组', 502);
+        throw new MaskingError('sensitive_word_invalid_output', 'LLM 敏感词提取返回的结构不是 JSON 数组');
     }
     try {
         return JSON.parse(cleaned.slice(start, end + 1));
     }
     catch {
-        throw new AppError('LLM 敏感词提取返回的 JSON 无法解析', 502);
+        throw new MaskingError('sensitive_word_invalid_output', 'LLM 敏感词提取返回的 JSON 无法解析');
     }
 };
 /**
@@ -66,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 [];
@@ -90,32 +94,32 @@ 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),
             });
         }
         catch (error) {
-            throw new AppError(`LLM 敏感词提取请求未完成：${error instanceof Error ? error.name : '未知错误'}`, 502);
+            throw new MaskingError('sensitive_word_request_failed', `LLM 敏感词提取请求未完成：${error instanceof Error ? error.name : '未知错误'}`);
         }
         if (!response.ok) {
-            throw new AppError(`LLM 敏感词提取 HTTP ${response.status}`, 502);
+            throw new MaskingError('sensitive_word_http_failed', `LLM 敏感词提取 HTTP ${response.status}`);
         }
         const payload = modelResponseSchema.safeParse(await response.json().catch(() => undefined));
         if (!payload.success) {
-            throw new AppError('LLM 敏感词提取响应缺少模型输出', 502);
+            throw new MaskingError('sensitive_word_invalid_response', 'LLM 敏感词提取响应缺少模型输出');
         }
         // 带推理的模型会先回 thinking 块，取第一个 text 块。
         const textBlock = payload.data.content.find((block) => block.type === 'text' && block.text);
         if (textBlock?.text === undefined) {
             const blockTypes = payload.data.content.map((block) => block.type).join('、');
-            throw new AppError(`LLM 敏感词提取响应缺少文本输出（stop_reason=${payload.data.stop_reason ?? '未知'}，`
-                + `块类型=${blockTypes}；stop_reason=max_tokens 说明思考烧光了 token 上限）`, 502);
+            throw new MaskingError('sensitive_word_output_missing', `LLM 敏感词提取响应缺少文本输出（stop_reason=${payload.data.stop_reason ?? '未知'}，`
+                + `块类型=${blockTypes}；stop_reason=max_tokens 说明思考烧光了 token 上限）`);
         }
         const parsed = extractedSchema.safeParse(extractJsonArray(textBlock.text));
         if (!parsed.success) {
-            throw new AppError('LLM 敏感词提取返回的结构校验失败', 502);
+            throw new MaskingError('sensitive_word_invalid_output', 'LLM 敏感词提取返回的结构校验失败');
         }
         const seen = new Set();
         const words = [];

package/dist/masking_error.d.ts

@@ -0,0 +1,7 @@
+import { AppError } from '@onco-foundry/errors';
+/** Safe machine-readable categories. Values never contain source text or provider response bodies. */
+export type MaskingFailureReason = 'image_decode_failed' | 'text_recognition_request_failed' | 'text_recognition_http_failed' | 'text_recognition_invalid_response' | 'text_recognition_provider_failed' | 'text_recognition_multiple_pages' | 'text_recognition_empty' | 'sensitive_word_request_failed' | 'sensitive_word_http_failed' | 'sensitive_word_invalid_response' | 'sensitive_word_invalid_output' | 'sensitive_word_output_missing' | 'sensitive_word_failed' | 'sensitive_word_not_locatable' | 'mask_coordinates_missing' | 'mask_coordinates_invalid' | 'mask_render_failed';
+export declare class MaskingError extends AppError {
+    readonly reason: MaskingFailureReason;
+    constructor(reason: MaskingFailureReason, message: string, statusCode?: number);
+}

package/dist/masking_error.js

@@ -0,0 +1,9 @@
+import { AppError } from '@onco-foundry/errors';
+export class MaskingError extends AppError {
+    reason;
+    constructor(reason, message, statusCode = 502) {
+        super(message, statusCode);
+        this.name = 'MaskingError';
+        this.reason = reason;
+    }
+}

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

@@ -13,7 +13,9 @@ 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_TEXTIN_BASE_URL = 'https://api.textin.com';
 const DEFAULT_TIMEOUT_MS = 120_000;
 const DEFAULT_MAX_INPUT_BYTES = 30 * 1024 * 1024;
@@ -31,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({
@@ -156,7 +147,7 @@ export const createTextInMasker = (options) => {
                 .jpeg({ quality: 92 })
                 .toBuffer({ resolveWithObject: true })
                 .catch(() => {
-                throw new AppError('TextIn 脱敏无法解码输入图片', 400);
+                throw new MaskingError('image_decode_failed', 'TextIn 脱敏无法解码输入图片', 400);
             });
             const imageWidth = upright.info.width;
             const imageHeight = upright.info.height;
@@ -174,20 +165,20 @@ export const createTextInMasker = (options) => {
                 });
             }
             catch (error) {
-                throw new AppError(`TextIn 脱敏请求未完成：${error instanceof Error ? error.name : '未知错误'}`, 502);
+                throw new MaskingError('text_recognition_request_failed', `TextIn 脱敏请求未完成：${error instanceof Error ? error.name : '未知错误'}`);
             }
             if (!response.ok) {
-                throw new AppError(`TextIn 脱敏 HTTP ${response.status}`, 502);
+                throw new MaskingError('text_recognition_http_failed', `TextIn 脱敏 HTTP ${response.status}`);
             }
             const payload = recognizeResponseSchema.safeParse(await response.json().catch(() => undefined));
             if (!payload.success) {
-                throw new AppError('TextIn 脱敏响应结构校验失败', 502);
+                throw new MaskingError('text_recognition_invalid_response', 'TextIn 脱敏响应结构校验失败');
             }
             if (payload.data.code !== 200 || payload.data.result === undefined) {
-                throw new AppError(`TextIn 脱敏接口报错：${payload.data.code} ${payload.data.message}`, 502);
+                throw new MaskingError('text_recognition_provider_failed', `TextIn 脱敏接口返回业务错误（code=${payload.data.code}）`);
             }
             if (options.requireAllMatches && payload.data.result.pages.length !== 1) {
-                throw new AppError('TextIn 脱敏需要单页图片识别结果', 502);
+                throw new MaskingError('text_recognition_multiple_pages', 'TextIn 脱敏需要单页图片识别结果');
             }
             const page = payload.data.result.pages[0];
             const lines = page.lines;
@@ -195,11 +186,19 @@ export const createTextInMasker = (options) => {
             const scaleX = page.width !== undefined && page.width > 0 ? imageWidth / page.width : 1;
             const scaleY = page.height !== undefined && page.height > 0 ? imageHeight / page.height : 1;
             if (options.requireAllMatches && !recognizedText.trim()) {
-                throw new AppError('TextIn 脱敏未识别出文字，无法确认处理结果', 502);
+                throw new MaskingError('text_recognition_empty', 'TextIn 脱敏未识别出文字，无法确认处理结果');
+            }
+            let detected;
+            try {
+                detected = await finder(recognizedText);
+            }
+            catch (error) {
+                if (error instanceof MaskingError)
+                    throw error;
+                throw new MaskingError('sensitive_word_failed', '敏感词判定器执行失败');
             }
-            const detected = await finder(recognizedText);
             if (options.requireAllMatches && detected.some(word => !word.text || !(word.target in TARGET_LABELS) || !recognizedText.includes(word.text))) {
-                throw new AppError('TextIn 脱敏判定结果无法定位', 502);
+                throw new MaskingError('sensitive_word_not_locatable', 'TextIn 脱敏判定结果无法定位');
             }
             const requested = detected
                 .filter((word) => word.text !== '' && request.targets.includes(word.target));
@@ -217,7 +216,7 @@ export const createTextInMasker = (options) => {
                         const quad = locateWordQuad(locatedLine, span.beginIndex, span.length);
                         if (quad === undefined) {
                             if (options.requireAllMatches)
-                                throw new AppError('TextIn 脱敏敏感词缺少坐标', 502);
+                                throw new MaskingError('mask_coordinates_missing', 'TextIn 脱敏敏感词缺少坐标');
                             complete = false;
                             break;
                         }
@@ -233,7 +232,7 @@ export const createTextInMasker = (options) => {
                                 Math.min(...xs) < 0 || Math.min(...ys) < 0 ||
                                 Math.max(...xs) > imageWidth || Math.max(...ys) > imageHeight ||
                                 Math.max(...xs) <= Math.min(...xs) || Math.max(...ys) <= Math.min(...ys)) {
-                                throw new AppError('TextIn 脱敏坐标无效', 502);
+                                throw new MaskingError('mask_coordinates_invalid', 'TextIn 脱敏坐标无效');
                             }
                         }
                         occurrenceQuads.push(clampQuad(scaleQuad(scaleQuadToImage(quad, scaleX, scaleY), SAFETY_SCALE), imageWidth, imageHeight));
@@ -251,17 +250,23 @@ export const createTextInMasker = (options) => {
                     }
                 }
                 if (options.requireAllMatches && located === 0) {
-                    throw new AppError('TextIn 脱敏敏感词无法定位', 502);
+                    throw new MaskingError('sensitive_word_not_locatable', 'TextIn 脱敏敏感词无法定位');
                 }
             }
             const overlay = polygonSvg(imageWidth, imageHeight, finalQuads);
-            const uprightMasked = await sharp(upright.data)
-                .composite([{ input: overlay, blend: 'over' }])
-                .jpeg({ quality: 94 })
-                .toBuffer();
-            const maskedImageBytes = rotation === 0
-                ? uprightMasked
-                : await sharp(uprightMasked).rotate((360 - rotation) % 360).jpeg({ quality: 94 }).toBuffer();
+            let maskedImageBytes;
+            try {
+                const uprightMasked = await sharp(upright.data)
+                    .composite([{ input: overlay, blend: 'over' }])
+                    .jpeg({ quality: 94 })
+                    .toBuffer();
+                maskedImageBytes = rotation === 0
+                    ? uprightMasked
+                    : await sharp(uprightMasked).rotate((360 - rotation) % 360).jpeg({ quality: 94 }).toBuffer();
+            }
+            catch {
+                throw new MaskingError('mask_render_failed', 'TextIn 脱敏图片遮盖失败');
+            }
             return {
                 maskedImageBytes: new Uint8Array(maskedImageBytes),
                 mapping: mappings,

package/package.json

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