@onco-foundry/mask-port 0.1.4 → 0.1.6

package/dist/index.d.ts

@@ -6,3 +6,4 @@ 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

@@ -6,3 +6,4 @@ 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.js

@@ -9,6 +9,7 @@
 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;
 // prompt 是模块内置资产，不开放注入：本模块定位就是医疗文书脱敏，提取口径由模块自己保证。
 const SYSTEM_PROMPT = `你从医疗文书扫描件（病历、检查报告、住院单等）的 OCR 文本中提取隐私信息。只提取以下类别：
@@ -46,13 +47,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 无法解析');
     }
 };
 /**
@@ -97,25 +98,25 @@ export const createLlmSensitiveWordFinder = (options) => {
             });
         }
         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/textin_masker.d.ts

@@ -37,6 +37,6 @@ export type TextInMaskerOptions = {
 export declare const findSensitiveWordsByRules: (text: string) => readonly SensitiveWord[];
 /**
  * 创建 TextIn 识别脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
- * 同一敏感词在一行出现多次时逐处遮盖、逐处登记 mapping（占位符按类别各自编号）。
+ * 同一敏感词出现多次时逐处遮盖、逐处登记 mapping；跨行命中拆成多个框，仍登记为一个实体。
  */
 export declare const createTextInMasker: (options: TextInMaskerOptions) => Masker;

package/dist/textin_masker.js

@@ -13,6 +13,7 @@ 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';
 const DEFAULT_TEXTIN_BASE_URL = 'https://api.textin.com';
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -82,9 +83,39 @@ const locateWordQuad = (line, beginIndex, wordLength) => {
     return line.position === undefined ? undefined : toQuad(line.position);
 };
 const scaleQuadToImage = (quad, scaleX, scaleY) => quad.map(([x, y]) => [x * scaleX, y * scaleY]);
+/**
+ * Find exact occurrences against the same newline-joined text seen by the finder,
+ * then split each occurrence into line-local spans for geometry lookup.
+ */
+const locateWordSpans = (lines, recognizedText, word) => {
+    const lineRanges = [];
+    let offset = 0;
+    for (const line of lines) {
+        lineRanges.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;
+        const spans = lineRanges.flatMap(range => {
+            const spanStart = Math.max(hit, range.start);
+            const spanEnd = Math.min(end, range.end);
+            return spanStart < spanEnd
+                ? [{ line: range.line, beginIndex: spanStart - range.start, length: spanEnd - spanStart }]
+                : [];
+        });
+        occurrences.push(spans);
+    }
+    return occurrences;
+};
 /**
  * 创建 TextIn 识别脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
- * 同一敏感词在一行出现多次时逐处遮盖、逐处登记 mapping（占位符按类别各自编号）。
+ * 同一敏感词出现多次时逐处遮盖、逐处登记 mapping；跨行命中拆成多个框，仍登记为一个实体。
  */
 export const createTextInMasker = (options) => {
     const credentials = z.object({
@@ -126,7 +157,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;
@@ -144,20 +175,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;
@@ -165,11 +196,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));
@@ -178,20 +217,18 @@ export const createTextInMasker = (options) => {
             const counters = new Map();
             for (const word of requested) {
                 let located = 0;
-                for (const line of lines) {
-                    let fromIndex = 0;
-                    while (true) {
-                        const hit = line.text.indexOf(word.text, fromIndex);
-                        if (hit < 0)
-                            break;
-                        fromIndex = hit + word.text.length;
-                        const locatedLine = options.requireAllMatches && line.char_positions?.length !== line.text.length
-                            ? { ...line, char_positions: undefined } : line;
-                        const quad = locateWordQuad(locatedLine, hit, word.text.length);
+                for (const spans of locateWordSpans(lines, recognizedText, word.text)) {
+                    const occurrenceQuads = [];
+                    let complete = spans.length > 0;
+                    for (const span of spans) {
+                        const locatedLine = options.requireAllMatches && span.line.char_positions?.length !== span.line.text.length
+                            ? { ...span.line, char_positions: undefined } : span.line;
+                        const quad = locateWordQuad(locatedLine, span.beginIndex, span.length);
                         if (quad === undefined) {
                             if (options.requireAllMatches)
-                                throw new AppError('TextIn 脱敏敏感词缺少坐标', 502);
-                            continue;
+                                throw new MaskingError('mask_coordinates_missing', 'TextIn 脱敏敏感词缺少坐标');
+                            complete = false;
+                            break;
                         }
                         if (options.requireAllMatches) {
                             const scaled = scaleQuadToImage(quad, scaleX, scaleY);
@@ -205,11 +242,14 @@ 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));
+                    }
+                    if (complete && occurrenceQuads.length > 0) {
                         located++;
-                        finalQuads.push(clampQuad(scaleQuad(scaleQuadToImage(quad, scaleX, scaleY), SAFETY_SCALE), imageWidth, imageHeight));
+                        finalQuads.push(...occurrenceQuads);
                         const count = (counters.get(word.target) ?? 0) + 1;
                         counters.set(word.target, count);
                         mappings.push({
@@ -220,17 +260,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.4",
+  "version": "0.1.6",
   "type": "module",
   "files": [
     "dist",
@@ -18,8 +18,8 @@
     "zod": "^4.4.3",
     "@onco-foundry/capability-registry": "0.1.1",
     "@onco-foundry/errors": "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/trace-port": "0.3.2"
   },
   "publishConfig": {
     "access": "public"