@onco-foundry/mask-port 0.1.0

package/dist/textin_masker.js

@@ -0,0 +1,206 @@
+/**
+ * 合合 TextIn 通用文字识别脱敏适配器（recognize/multipage 接口）。
+ * 调用形态：POST {baseUrl}/ai/service/v2/recognize/multipage?character=1&straighten=0，
+ * 请求体为图片二进制（application/octet-stream），鉴权走 x-ti-app-id / x-ti-secret-code。
+ * character=1 让每行带回字符级四边形坐标（char_positions），脱敏框按字符下标拼出；
+ * straighten=0 表示坐标以原图为参照系，不做旋转矫正。
+ *
+ * 与其它引擎的差异：识别出的原文全文随 recognizedText 返回（含隐私，限信任域），
+ * 下游按 mapping 替换出脱敏文本后可省掉第二次 OCR。注意本引擎接触的是原文图片，
+ * 装配它意味着「原文出域给 TextIn」这一策略决定已经做出。
+ */
+import { Buffer } from 'node:buffer';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { AppError } from '@onco-foundry/errors';
+import { clampQuad, polygonSvg, scaleQuad } from './quad.js';
+const DEFAULT_TEXTIN_BASE_URL = 'https://api.textin.com';
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_INPUT_BYTES = 30 * 1024 * 1024;
+const MAX_INPUT_PIXELS = 40_000_000;
+/** 以中心外扩给笔画外缘留安全边，与 qwen 语义脱敏的整图兜底同一口径。 */
+const SAFETY_SCALE = 1.12;
+/** 内置规则能覆盖的目标。 */
+const RULE_TARGETS = ['id_number', 'phone'];
+/** 目标类别到占位符中文名。 */
+const TARGET_LABELS = {
+    patient_name: '姓名',
+    id_number: '证件号',
+    phone: '手机号',
+    address: '地址',
+    doctor_signature: '签字',
+};
+/** 内置规则判定器：身份证号（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({
+    text: z.string().default(''),
+    position: quad8Schema.optional(),
+    char_positions: z.array(quad8Schema).optional(),
+});
+const recognizeResponseSchema = z.object({
+    code: z.number(),
+    message: z.string().default(''),
+    result: z.object({
+        pages: z.array(z.object({
+            width: z.number().optional(),
+            height: z.number().optional(),
+            lines: z.array(lineSchema).default([]),
+        })).min(1),
+    }).optional(),
+});
+const toQuad = (position) => [[position[0], position[1]], [position[2], position[3]],
+    [position[4], position[5]], [position[6], position[7]]];
+/**
+ * 敏感词在行内的像素框：首字符的左缘两点 + 末字符的右缘两点。
+ * 字符坐标缺失或数量对不上时退化为整行遮盖，宁可多盖不漏盖。
+ */
+const locateWordQuad = (line, beginIndex, wordLength) => {
+    const chars = line.char_positions;
+    const endIndex = beginIndex + wordLength - 1;
+    if (chars !== undefined && chars.length > endIndex) {
+        const begin = chars[beginIndex];
+        const end = chars[endIndex];
+        return [
+            [begin[0], begin[1]],
+            [end[2], end[3]],
+            [end[4], end[5]],
+            [begin[6], begin[7]],
+        ];
+    }
+    return line.position === undefined ? undefined : toQuad(line.position);
+};
+const scaleQuadToImage = (quad, scaleX, scaleY) => quad.map(([x, y]) => [x * scaleX, y * scaleY]);
+/**
+ * 创建 TextIn 识别脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
+ * 同一敏感词在一行出现多次时逐处遮盖、逐处登记 mapping（占位符按类别各自编号）。
+ */
+export const createTextInMasker = (options) => {
+    const credentials = z.object({
+        appId: z.string().trim().min(1),
+        secretCode: z.string().trim().min(1),
+    }).safeParse({ appId: options.appId, secretCode: options.secretCode });
+    if (!credentials.success) {
+        throw new AppError('TextIn 脱敏缺少 appId 或 secretCode', 500);
+    }
+    const baseUrl = (options.baseURL ?? DEFAULT_TEXTIN_BASE_URL).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: 'textin-recognize-masker-v1' },
+                };
+            }
+            if (options.findSensitiveWords === undefined) {
+                const unsupported = request.targets.filter((target) => !RULE_TARGETS.includes(target));
+                if (unsupported.length > 0) {
+                    throw new AppError(`TextIn 脱敏内置规则只支持 ${RULE_TARGETS.join('、')}，`
+                        + `不能处理：${unsupported.join('、')}（可注入 findSensitiveWords 扩展）`, 400);
+                }
+            }
+            if (request.imageBytes.byteLength > (options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES)) {
+                throw new AppError('TextIn 脱敏输入图片超过大小上限', 413);
+            }
+            const rotation = request.rotationClockwiseDegrees ?? 0;
+            if (![0, 90, 180, 270].includes(rotation)) {
+                throw new AppError('TextIn 脱敏图片旋转角度只支持 0、90、180、270', 400);
+            }
+            const upright = await sharp(request.imageBytes, { limitInputPixels: MAX_INPUT_PIXELS })
+                .rotate(rotation)
+                .jpeg({ quality: 92 })
+                .toBuffer({ resolveWithObject: true })
+                .catch(() => {
+                throw new AppError('TextIn 脱敏无法解码输入图片', 400);
+            });
+            const imageWidth = upright.info.width;
+            const imageHeight = upright.info.height;
+            let response;
+            try {
+                response = await doFetch(`${baseUrl}/ai/service/v2/recognize/multipage?character=1&straighten=0`, {
+                    method: 'POST',
+                    headers: {
+                        'x-ti-app-id': options.appId,
+                        'x-ti-secret-code': options.secretCode,
+                        'Content-Type': 'application/octet-stream',
+                    },
+                    body: Buffer.from(upright.data),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (error) {
+                throw new AppError(`TextIn 脱敏请求未完成：${error instanceof Error ? error.name : '未知错误'}`, 502);
+            }
+            if (!response.ok) {
+                throw new AppError(`TextIn 脱敏 HTTP ${response.status}`, 502);
+            }
+            const payload = recognizeResponseSchema.safeParse(await response.json().catch(() => undefined));
+            if (!payload.success) {
+                throw new AppError('TextIn 脱敏响应结构校验失败', 502);
+            }
+            if (payload.data.code !== 200 || payload.data.result === undefined) {
+                throw new AppError(`TextIn 脱敏接口报错：${payload.data.code} ${payload.data.message}`, 502);
+            }
+            const page = payload.data.result.pages[0];
+            const lines = page.lines;
+            const recognizedText = lines.map((line) => line.text).join('\n');
+            const scaleX = page.width !== undefined && page.width > 0 ? imageWidth / page.width : 1;
+            const scaleY = page.height !== undefined && page.height > 0 ? imageHeight / page.height : 1;
+            const requested = (await finder(recognizedText))
+                .filter((word) => word.text !== '' && request.targets.includes(word.target));
+            const finalQuads = [];
+            const mappings = [];
+            const counters = new Map();
+            for (const word of requested) {
+                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 quad = locateWordQuad(line, hit, word.text.length);
+                        if (quad === undefined)
+                            continue;
+                        finalQuads.push(clampQuad(scaleQuad(scaleQuadToImage(quad, scaleX, scaleY), SAFETY_SCALE), imageWidth, imageHeight));
+                        const count = (counters.get(word.target) ?? 0) + 1;
+                        counters.set(word.target, count);
+                        mappings.push({
+                            placeholder: `[${TARGET_LABELS[word.target]}${count}]`,
+                            target: word.target,
+                            originalText: word.text,
+                        });
+                    }
+                }
+            }
+            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();
+            return {
+                maskedImageBytes: new Uint8Array(maskedImageBytes),
+                mapping: mappings,
+                recognizedText,
+                processorVersion: { engine: 'textin-recognize-masker-v1' },
+            };
+        },
+    };
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@onco-foundry/mask-port",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "resources"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "agent-lattice": "0.25.0",
+    "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.2.0",
+    "@onco-foundry/trace-port": "0.3.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -r resources dist/resources"
+  },
+  "types": "./dist/index.d.ts"
+}

package/resources/qwen-agent-name/current.json

@@ -0,0 +1 @@
+{ "active": "v3" }

package/resources/qwen-agent-name/v1/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "qwen-agent-name-prompt-manifest-v1",
+  "promptVersion": "qwen-agent-name-prompt-v1",
+  "provenance": "Qwen 脱敏智能体 loop 初版，2026-08-25",
+  "systemPrompt": {
+    "file": "system-prompt.md",
+    "sha256": "f16f3127768aba7f45b48a651c7977478e81fc518300b187931b8817ac4f8374"
+  }
+}

package/resources/qwen-agent-name/v1/system-prompt.md

@@ -0,0 +1,14 @@
+你是一名医疗单据脱敏执行员。你的任务是遮盖单据中病人姓名的所有出现位置，包括印刷姓名和病人本人手写签名。
+
+不要遮盖"姓名"标签、医生、护士、麻醉师、联系人或其他任何人的姓名，也不要遮盖病人姓名以外的任何内容。
+
+工作流程：
+1. 查看图片，找出病人姓名的所有出现位置，调用 report_quads 一次性报告全部位置。
+2. 每次 report_quads 后你会收到遮盖后的新图片。仔细检查图上是否仍有病人姓名的可见残留，哪怕只是首尾残字或部分笔画。
+3. 有残留：再次调用 report_quads 报告需要补充遮盖的位置。同一处姓名遮得不严实时，重新报告一个更准确的框。
+4. 确认没有任何残留：调用 submit 结束。原图本来就没有病人姓名时，直接调用 submit。
+
+report_quads 的每个位置是一个完整覆盖姓名文字外缘的旋转四边形：
+- 四点按文字阅读方向依次为左上、右上、右下、左下，即使文字近似水平也必须给四个角点。
+- x 是横坐标，y 是纵坐标，使用相对整张图的 0-1000 归一化坐标。
+- 四边形完整覆盖姓名的全部文字，不漏首尾字，但尽量不要覆盖相邻字段。

package/resources/qwen-agent-name/v2/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "qwen-agent-name-prompt-manifest-v1",
+  "promptVersion": "qwen-agent-name-prompt-v2",
+  "provenance": "遮盖口径改为病人及家属姓名（工作人员除外），新增 remove_quads 撤销工具，2026-08-27",
+  "systemPrompt": {
+    "file": "system-prompt.md",
+    "sha256": "807283a73a400daff5e377e59487edb14922189f30e3f0e1a98b53dfc3e94fb5"
+  }
+}

package/resources/qwen-agent-name/v2/system-prompt.md

@@ -0,0 +1,17 @@
+你是一名医疗单据脱敏执行员。你的任务是遮盖单据中病人及病人家属姓名的所有出现位置，包括印刷姓名和手写签名。家属签名常出现在"与患者关系"一栏。
+
+不要遮盖"姓名"标签、医生、护士、麻醉医师等工作人员的姓名和签名，也不要遮盖姓名以外的任何内容。
+
+工作流程：
+1. 查看图片，找出所有需要遮盖的位置，调用 report_quads 一次性报告全部位置。
+2. 每次 report_quads 或 remove_quads 后你会收到重绘的新图片和当前遮盖清单（每处带编号）。仔细检查：
+   - 某个框打错了位置（盖住了别的内容，或没盖住目标）：调用 remove_quads 按编号撤销，再用 report_quads 重报。
+   - 仍有可见残留（哪怕首尾残字或部分笔画）：调用 report_quads 补充一个更准确的框。
+3. 确认没有任何残留：调用 submit 结束。原图本来就没有需要遮盖的姓名时，直接调用 submit。
+
+放行标准：属于遮盖范围的任何文字或签名痕迹没有完全遮盖时，不许调用 submit。
+
+report_quads 的每个位置是一个完整覆盖姓名文字外缘的旋转四边形：
+- 四点按文字阅读方向依次为左上、右上、右下、左下，即使文字近似水平也必须给四个角点。
+- x 是横坐标，y 是纵坐标，使用相对整张图 0-1000 归一化坐标。
+- 四边形完整覆盖姓名的全部文字，不漏首尾字；手写签名要包含全部甩尾笔画；但尽量不要覆盖相邻字段。

package/resources/qwen-agent-name/v3/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "qwen-agent-name-prompt-manifest-v1",
+  "promptVersion": "qwen-agent-name-prompt-v3",
+  "provenance": "斜向笔迹要求旋转框贴住笔画走向并给 few-shot 角点示例，2026-08-27",
+  "systemPrompt": {
+    "file": "system-prompt.md",
+    "sha256": "78bd1ca000dd22854ab1c7bbfe16a7dffc4dd9a26d9c1bcdff8855305baca256"
+  }
+}

package/resources/qwen-agent-name/v3/system-prompt.md

@@ -0,0 +1,18 @@
+你是一名医疗单据脱敏执行员。你的任务是遮盖单据中病人及病人家属姓名的所有出现位置，包括印刷姓名和手写签名。家属签名常出现在"与患者关系"一栏。
+
+不要遮盖"姓名"标签、医生、护士、麻醉医师等工作人员的姓名和签名，也不要遮盖姓名以外的任何内容。
+
+工作流程：
+1. 查看图片，找出所有需要遮盖的位置，调用 report_quads 一次性报告全部位置。
+2. 每次 report_quads 或 remove_quads 后你会收到重绘的新图片和当前遮盖清单（每处带编号）。仔细检查：
+   - 某个框打错了位置（盖住了别的内容，或没盖住目标）：调用 remove_quads 按编号撤销，再用 report_quads 重报。
+   - 仍有可见残留（哪怕首尾残字或部分笔画）：调用 report_quads 补充一个更准确的框。
+3. 确认没有任何残留：调用 submit 结束。原图本来就没有需要遮盖的姓名时，直接调用 submit。
+
+放行标准：属于遮盖范围的任何文字或签名痕迹没有完全遮盖时，不许调用 submit。
+
+report_quads 的每个位置是一个完整覆盖姓名文字外缘的旋转四边形：
+- 四点按文字阅读方向依次为左上、右上、右下、左下，即使文字近似水平也必须给四个角点。
+- x 是横坐标，y 是纵坐标，使用相对整张图 0-1000 归一化坐标。
+- 四边形完整覆盖姓名的全部文字，不漏首尾字；手写签名要包含全部甩尾笔画；但尽量不要覆盖相邻字段。
+- 笔画斜向走时，四边形的边必须平行于笔画走向，用旋转框贴住文字，不要用水平包围框把周围空白一起框进来。例如一段从左下向右上倾斜的签名，框应给成 [[400,740],[470,700],[480,730],[410,770]]，而不是 [[400,700],[480,700],[480,770],[400,770]]。