@onco-foundry/mask-port 0.1.5 → 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.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;
@@ -156,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;
@@ -174,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;
@@ -195,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));
@@ -217,7 +226,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 +242,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 +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.5",
+  "version": "0.1.6",
   "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/errors": "0.1.1",
+    "@onco-foundry/resource-versioning": "0.3.0",
+    "@onco-foundry/trace-port": "0.3.2"
   },
   "publishConfig": {
     "access": "public"