@onco-foundry/mask-port 0.1.0

package/dist/qwen_agent_masker.js

@@ -0,0 +1,249 @@
+import { Buffer } from 'node:buffer';
+import { createBareAgent, tool } from 'agent-lattice';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { AppError } from '@onco-foundry/errors';
+import { defineCapability } from '@onco-foundry/capability-registry';
+import { loadActiveVersionedResource, resourceFileReferenceSchema, versionedManifestBaseShape, } from '@onco-foundry/resource-versioning';
+import { createTracer } from '@onco-foundry/trace-port';
+import { MASK_TARGETS } from './masker.js';
+import { clampQuad, normalizeQuad, normalizedToPixels, polygonSvg, scaleQuad, } from './quad.js';
+const DEFAULT_MAX_INPUT_BYTES = 30 * 1024 * 1024;
+const MAX_INPUT_PIXELS = 40_000_000;
+const DEFAULT_MAX_TURNS = 15;
+const DEFAULT_MAX_TOKENS = 4096;
+/** 遮盖执行的安全边：贴边的框容易漏笔画，统一外扩一档，属于遮盖动作的一部分。 */
+const MASK_SAFETY_SCALE = 1.2;
+const promptManifestSchema = z.object({
+    ...versionedManifestBaseShape,
+    promptVersion: z.string().min(1),
+    provenance: z.string().min(1),
+    systemPrompt: resourceFileReferenceSchema,
+});
+const detectionSchema = z.object({
+    /** 图中识别到的姓名原文。 */
+    text: z.string().min(1),
+    kind: z.enum(['printed', 'handwritten']),
+    /** 旋转四边形：按阅读方向左上、右上、右下、左下，相对整张图 0-1000 归一化坐标。 */
+    quad: z.array(z.tuple([z.number(), z.number()])).length(4),
+});
+/** 能力入参契约：V1 只接 patient_name（契约写死；直接调 mask() 时由内部目标校验兜底）。 */
+export const qwenAgentNameMaskInputSchema = z.object({
+    imageBytes: z.instanceof(Uint8Array).refine((bytes) => bytes.byteLength > 0, '图片字节不能为空'),
+    targets: z.array(z.literal('patient_name')).min(1),
+    rotationClockwiseDegrees: z.union([z.literal(0), z.literal(90), z.literal(180), z.literal(270)]).optional(),
+});
+/** MaskResult 的 zod 契约：注册表名片与消费侧 parse 拿回类型用。 */
+const maskResultSchema = z.object({
+    maskedImageBytes: z.custom((value) => value instanceof Uint8Array),
+    mapping: z.array(z.object({
+        placeholder: z.string(),
+        target: z.enum(MASK_TARGETS),
+        originalText: z.string(),
+    })),
+    recognizedText: z.string().optional(),
+    processorVersion: z.object({
+        engine: z.string(),
+        model: z.string().optional(),
+        prompt: z.string().optional(),
+    }).optional(),
+});
+/**
+ * 能力名片：Qwen 脱敏智能体向能力注册表自报家门的最小元数据。
+ * kind 是 code——与 tencent/textin 同是 Masker 端口的平级实现，边界上就是一次脱敏调用；
+ * 内部跑 LLM loop 还是调专用 API 是后端选型，不该改变 kind（见 CapabilityKind 的定义）。
+ * version 不归名片管：asCapability 默认取 prompt 版本，场景可覆盖。
+ */
+export const qwenAgentNameMaskCapabilityCard = {
+    name: 'qwen-agent-name-mask',
+    kind: 'code',
+    summary: '对医疗单据图片做病人姓名脱敏，返回脱敏图与占位符映射',
+    input: qwenAgentNameMaskInputSchema,
+    output: maskResultSchema,
+};
+/**
+ * Qwen 脱敏智能体：模型在 loop 里闭环完成「报框 → 看遮盖结果 → 补框/确认」。
+ *
+ * 模型只负责看和报（report_quads 报旋转框、remove_quads 撤销报错的框、submit 确认无残留）；遮盖动作永远由
+ * 代码执行，每次变动后把重绘的遮盖图作为 tool_result 图片喂回模型。
+ * 遮盖决策与最终裁判都归模型，代码不加内容判断；maxTurns 是资源边界，耗尽仍未
+ * submit 等于没有交付物，图片不放行（422）。原始模型响应不写磁盘、不进错误信息。
+ */
+export const createQwenAgentMasker = async (options) => {
+    const optionsResult = z.object({
+        baseURL: z.url(),
+        apiKey: z.string().trim().min(1),
+        model: z.string().trim().min(1),
+    }).safeParse(options);
+    if (!optionsResult.success) {
+        throw new AppError('Qwen 脱敏智能体配置非法', 500);
+    }
+    const prompts = await loadActiveVersionedResource({
+        baseDir: new URL('./resources/qwen-agent-name/', import.meta.url),
+        manifestSchema: promptManifestSchema,
+        ...(options.promptVersionOverride === undefined
+            ? {}
+            : { versionOverride: options.promptVersionOverride }),
+    });
+    const systemPrompt = prompts.files.get(prompts.manifest.systemPrompt.file);
+    if (systemPrompt === undefined) {
+        throw new Error(`Qwen 脱敏智能体 prompt 资源缺少文件：${prompts.manifest.systemPrompt.file}`);
+    }
+    const { promptVersion } = prompts.manifest;
+    const tracer = options.tracer ?? createTracer({ kind: 'noop' });
+    // prompt 版本在装配处还不知道，加载完版本化资源后回填进版本链。
+    tracer.setVersions({ prompt: promptVersion, model: options.model });
+    const mask = async (request) => {
+        const processorVersion = {
+            engine: 'qwen-agent-name-masker-v1',
+            model: options.model,
+            prompt: promptVersion,
+        };
+        if (request.targets.length === 0) {
+            return { maskedImageBytes: request.imageBytes, mapping: [], processorVersion };
+        }
+        const unsupported = request.targets.filter((target) => target !== 'patient_name');
+        if (unsupported.length > 0) {
+            throw new AppError(`Qwen 脱敏智能体 V1 只支持 patient_name，不能处理：${unsupported.join('、')}`, 400);
+        }
+        if (request.imageBytes.byteLength > (options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES)) {
+            throw new AppError('Qwen 脱敏智能体输入图片超过大小上限', 413);
+        }
+        const rotation = request.rotationClockwiseDegrees ?? 0;
+        if (![0, 90, 180, 270].includes(rotation)) {
+            throw new AppError('Qwen 脱敏智能体图片旋转角度只支持 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('Qwen 脱敏智能体无法解码输入图片', 400);
+        });
+        const width = upright.info.width;
+        const height = upright.info.height;
+        const covered = [];
+        let nextId = 1;
+        let masked = upright.data;
+        let submitted = false;
+        const renderMasked = async () => {
+            masked = covered.length === 0
+                ? upright.data
+                : await sharp(upright.data)
+                    .composite([{ input: polygonSvg(width, height, covered.map((entry) => entry.quad)), blend: 'over' }])
+                    .jpeg({ quality: 94 })
+                    .toBuffer();
+            return masked;
+        };
+        /** 反馈文本里的当前遮盖清单：模型撤销框时按这里的编号引用。 */
+        const coveredListText = () => covered.map((entry) => `#${entry.id} ${entry.mapping.originalText}`).join('、');
+        const maskedImageContent = () => ({
+            type: 'image',
+            source: {
+                type: 'base64',
+                media_type: 'image/jpeg',
+                data: masked.toString('base64'),
+            },
+        });
+        const reportQuadsTool = tool('report_quads', '报告需要遮盖的病人姓名位置。每处是一个完整覆盖姓名文字外缘的旋转四边形，'
+            + '坐标相对整张图 0-1000 归一化。调用后会收到遮盖后的新图片和当前遮盖清单。', z.object({ detections: z.array(detectionSchema).min(1) }), async ({ detections }) => {
+            for (const detection of detections) {
+                const quad = clampQuad(scaleQuad(normalizedToPixels(normalizeQuad(detection.quad), width, height), MASK_SAFETY_SCALE), width, height);
+                covered.push({
+                    id: nextId,
+                    quad,
+                    mapping: {
+                        placeholder: `[姓名${nextId}]`,
+                        target: 'patient_name',
+                        originalText: detection.text,
+                    },
+                });
+                nextId += 1;
+            }
+            await renderMasked();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `已遮盖 ${detections.length} 处。当前遮盖清单：${coveredListText()}。`
+                            + '请检查这张遮盖后的图片：某个框打错位置了就调用 remove_quads 按编号撤销再重报；'
+                            + '仍能看到病人姓名的任何残留（哪怕首尾残字或部分笔画）就继续调用 report_quads 补充；'
+                            + '确认没有任何残留后调用 submit。',
+                    },
+                    maskedImageContent(),
+                ],
+            };
+        });
+        const removeQuadsTool = tool('remove_quads', '撤销之前报告错误的框。参数是遮盖清单里的编号（不带 # 号）。撤销后收到重绘的新图片，'
+            + '再用 report_quads 报告正确的框。', z.object({ ids: z.array(z.number().int().positive()).min(1) }), async ({ ids }) => {
+            const found = ids.filter((id) => covered.some((entry) => entry.id === id));
+            for (const id of found) {
+                covered.splice(covered.findIndex((entry) => entry.id === id), 1);
+            }
+            await renderMasked();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: found.length === ids.length
+                            ? `已撤销 ${found.length} 处。当前遮盖清单：${coveredListText() || '（空）'}。`
+                            : `已撤销 ${found.length} 处，编号 ${ids.filter((id) => !found.includes(id)).join('、')} 不存在。`
+                                + `当前遮盖清单：${coveredListText() || '（空）'}。`,
+                    },
+                    maskedImageContent(),
+                ],
+            };
+        });
+        const submitTool = tool('submit', '确认遮盖后的图片上已没有任何病人姓名残留，结束本次脱敏。'
+            + '原图本来就没有病人姓名时直接调用。', z.object({}), () => {
+            submitted = true;
+            return { content: '已确认无残留，脱敏完成。', endTurn: true };
+        });
+        const agent = createBareAgent({
+            name: 'qwen-agent-name-masker',
+            model: options.model,
+            baseURL: options.baseURL,
+            apiKey: options.apiKey,
+            modelClient: options.modelClient,
+            systemPrompt,
+            maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+            maxTurns: options.maxTurns ?? DEFAULT_MAX_TURNS,
+            thinkingConfig: { type: 'disabled' },
+            tools: [reportQuadsTool, removeQuadsTool, submitTool],
+            tracer,
+        });
+        const response = await agent.prompt([
+            { type: 'text', text: '请对这张医疗单据做病人姓名脱敏。' },
+            {
+                type: 'image',
+                source: {
+                    type: 'base64',
+                    media_type: 'image/jpeg',
+                    data: upright.data.toString('base64'),
+                },
+            },
+        ]);
+        if (response.is_error) {
+            throw new AppError(`Qwen 脱敏智能体运行失败：${response.subtype}`, 502);
+        }
+        if (!submitted) {
+            throw new AppError('Qwen 脱敏智能体未确认无残留，图片未放行', 422);
+        }
+        const maskedImageBytes = rotation === 0
+            ? masked
+            : await sharp(masked).rotate((360 - rotation) % 360).jpeg({ quality: 94 }).toBuffer();
+        return {
+            maskedImageBytes: new Uint8Array(maskedImageBytes),
+            mapping: covered.map((entry) => entry.mapping),
+            processorVersion,
+        };
+    };
+    return {
+        mask,
+        asCapability: (asOptions) => defineCapability({
+            ...qwenAgentNameMaskCapabilityCard,
+            version: asOptions?.version ?? promptVersion,
+            run: async (input) => await mask(input),
+        }),
+    };
+};

package/dist/redact_text.d.ts

@@ -0,0 +1,8 @@
+/** 按 mapping 把原文全文改写成脱敏文本：originalText 换成对应占位符。 */
+import type { MaskMappingEntry } from './masker.ts';
+/**
+ * 与「对脱敏图再跑一次 OCR」等价，但得到的是显式占位符而非遮盖噪声。
+ * 同一原文出现多次时按顺序各换一个占位符（每次只换第一处命中），
+ * 保持与 mapping 的一一对应；词互相包含时长的先换，避免误切。
+ */
+export declare const redactTextByMapping: (text: string, mapping: readonly MaskMappingEntry[]) => string;

package/dist/redact_text.js

@@ -0,0 +1,17 @@
+/** 按 mapping 把原文全文改写成脱敏文本：originalText 换成对应占位符。 */
+/**
+ * 与「对脱敏图再跑一次 OCR」等价，但得到的是显式占位符而非遮盖噪声。
+ * 同一原文出现多次时按顺序各换一个占位符（每次只换第一处命中），
+ * 保持与 mapping 的一一对应；词互相包含时长的先换，避免误切。
+ */
+export const redactTextByMapping = (text, mapping) => {
+    const entries = mapping
+        .filter((entry) => entry.originalText !== '')
+        .map((entry, index) => ({ entry, index }))
+        .sort((a, b) => b.entry.originalText.length - a.entry.originalText.length || a.index - b.index);
+    let redacted = text;
+    for (const { entry } of entries) {
+        redacted = redacted.replace(entry.originalText, entry.placeholder);
+    }
+    return redacted;
+};

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

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

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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]]。

package/dist/tencent_masker.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 腾讯云医疗报告图片脱敏适配器（mrs ImageMask 接口）。
+ * 调用形态：POST https://mrs.tencentcloudapi.com/，Action=ImageMask，Version=2020-09-10，
+ * 签名走腾讯云 API 3.0 的 TC3-HMAC-SHA256。
+ * 接口文档：https://cloud.tencent.com/document/product/1314/102293
+ */
+import type { Masker } from './masker.ts';
+export type TencentMaskerOptions = {
+    readonly secretId: string;
+    readonly secretKey: string;
+    readonly region: string;
+    /** 测试注入缝：替换掉真实的 HTTP 层，不碰网络。 */
+    readonly fetch?: typeof fetch;
+};
+/**
+ * 创建腾讯医疗脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
+ * 注意：腾讯接口只回打码后的图片，不回传每处脱敏的位置与类别，
+ * 因此 mapping 恒为空——回溯明细依赖双份归档下的人工复核，不靠这个字段。
+ */
+export declare const createTencentMasker: (options: TencentMaskerOptions) => Masker;

package/dist/tencent_masker.js

@@ -0,0 +1,126 @@
+/**
+ * 腾讯云医疗报告图片脱敏适配器（mrs ImageMask 接口）。
+ * 调用形态：POST https://mrs.tencentcloudapi.com/，Action=ImageMask，Version=2020-09-10，
+ * 签名走腾讯云 API 3.0 的 TC3-HMAC-SHA256。
+ * 接口文档：https://cloud.tencent.com/document/product/1314/102293
+ */
+import { createHash, createHmac } from 'node:crypto';
+import { AppError } from '@onco-foundry/errors';
+const TENCENT_MRS_HOST = 'mrs.tencentcloudapi.com';
+const TENCENT_MRS_SERVICE = 'mrs';
+const TENCENT_MRS_ACTION = 'ImageMask';
+const TENCENT_MRS_VERSION = '2020-09-10';
+const TC3_ALGORITHM = 'TC3-HMAC-SHA256';
+const TC3_CONTENT_TYPE = 'application/json; charset=utf-8';
+const TC3_SIGNED_HEADERS = 'content-type;host';
+/** 患者信息类目标：腾讯接口把它们合并成一个 PatientFlag。 */
+const PATIENT_TARGETS = [
+    'patient_name',
+    'id_number',
+    'phone',
+    'address',
+];
+/**
+ * 端口目标集到腾讯 MaskFlag 的映射。腾讯接口的目标比我们粗：
+ * 医院名（HospitalFlag）与条码（BarFlag）不在端口目标集里，恒为 false。
+ */
+const toMaskFlag = (targets) => ({
+    HospitalFlag: false,
+    BarFlag: false,
+    PatientFlag: targets.some((target) => PATIENT_TARGETS.includes(target)),
+    DoctorFlag: targets.includes('doctor_signature'),
+});
+const sha256Hex = (content) => createHash('sha256').update(content, 'utf8').digest('hex');
+const hmacSha256 = (key, content) => createHmac('sha256', key).update(content, 'utf8').digest();
+/**
+ * TC3-HMAC-SHA256 签名：拼规范请求 → 拼待签字符串 → 派生签名密钥链 → 得 Authorization。
+ * 签名覆盖请求体 sha256，headers 只签 content-type 与 host（腾讯文档的最小集合）。
+ */
+const signRequest = (options, timestampSeconds, payload) => {
+    // 签名日期按 UTC 取，与 timestamp 同源。
+    const date = new Date(timestampSeconds * 1000).toISOString().slice(0, 10);
+    const canonicalRequest = [
+        'POST',
+        '/',
+        '',
+        `content-type:${TC3_CONTENT_TYPE}\nhost:${TENCENT_MRS_HOST}\n`,
+        TC3_SIGNED_HEADERS,
+        sha256Hex(payload),
+    ].join('\n');
+    const credentialScope = `${date}/${TENCENT_MRS_SERVICE}/tc3_request`;
+    const stringToSign = [
+        TC3_ALGORITHM,
+        String(timestampSeconds),
+        credentialScope,
+        sha256Hex(canonicalRequest),
+    ].join('\n');
+    const signingKey = hmacSha256(hmacSha256(hmacSha256(`TC3${options.secretKey}`, date), TENCENT_MRS_SERVICE), 'tc3_request');
+    const signature = createHmac('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
+    return `${TC3_ALGORITHM} Credential=${options.secretId}/${credentialScope}, `
+        + `SignedHeaders=${TC3_SIGNED_HEADERS}, Signature=${signature}`;
+};
+/**
+ * 创建腾讯医疗脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
+ * 注意：腾讯接口只回打码后的图片，不回传每处脱敏的位置与类别，
+ * 因此 mapping 恒为空——回溯明细依赖双份归档下的人工复核，不靠这个字段。
+ */
+export const createTencentMasker = (options) => {
+    const doFetch = options.fetch ?? fetch;
+    return {
+        async mask(request) {
+            // 没有目标就是脱敏关闭的空调用，不打远程请求。
+            if (request.targets.length === 0) {
+                return {
+                    maskedImageBytes: request.imageBytes,
+                    mapping: [],
+                    processorVersion: { engine: 'tencent-mrs-image-mask-2020-09-10' },
+                };
+            }
+            const payload = JSON.stringify({
+                Image: { Base64: Buffer.from(request.imageBytes).toString('base64') },
+                MaskFlag: toMaskFlag(request.targets),
+                // 扫描件常有旋转，交给服务端矫正后识别率更高。
+                AutoFixImageDirection: true,
+            });
+            const timestampSeconds = Math.floor(Date.now() / 1000);
+            let response;
+            try {
+                response = await doFetch(`https://${TENCENT_MRS_HOST}/`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': TC3_CONTENT_TYPE,
+                        'Host': TENCENT_MRS_HOST,
+                        'X-TC-Action': TENCENT_MRS_ACTION,
+                        'X-TC-Version': TENCENT_MRS_VERSION,
+                        'X-TC-Region': options.region,
+                        'X-TC-Timestamp': String(timestampSeconds),
+                        'Authorization': signRequest(options, timestampSeconds, payload),
+                    },
+                    body: payload,
+                });
+            }
+            catch (error) {
+                throw new AppError(`腾讯医疗脱敏请求未送达：${error instanceof Error ? error.message : String(error)}`, 502);
+            }
+            const body = await response.json().catch(() => undefined);
+            const requestId = body?.Response?.RequestId;
+            if (!response.ok) {
+                throw new AppError(`腾讯医疗脱敏 HTTP ${response.status}${requestId ? `（RequestId ${requestId}）` : ''}`, 502);
+            }
+            const apiError = body?.Response?.Error;
+            if (apiError !== undefined) {
+                throw new AppError(`腾讯医疗脱敏接口报错：${apiError.Code ?? '未知错误'} ${apiError.Message ?? ''}`
+                    + `${requestId ? `（RequestId ${requestId}）` : ''}`, 502);
+            }
+            const maskedImage = body?.Response?.MaskedImage;
+            if (typeof maskedImage !== 'string' || maskedImage === '') {
+                throw new AppError(`腾讯医疗脱敏返回缺少 MaskedImage${requestId ? `（RequestId ${requestId}）` : ''}`, 502);
+            }
+            return {
+                maskedImageBytes: new Uint8Array(Buffer.from(maskedImage, 'base64')),
+                mapping: [],
+                processorVersion: { engine: 'tencent-mrs-image-mask-2020-09-10' },
+            };
+        },
+    };
+};

package/dist/textin_masker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 合合 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 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[]>;
+export type TextInMaskerOptions = {
+    readonly appId: string;
+    readonly secretCode: string;
+    readonly baseURL?: string;
+    readonly timeoutMs?: number;
+    readonly maxInputBytes?: number;
+    /** 测试注入缝：替换掉真实的 HTTP 层，不碰网络。 */
+    readonly fetch?: typeof fetch;
+    /**
+     * 敏感词判定器。缺省用内置规则（身份证号、手机号正则）；
+     * 需要患者姓名、地址等规则盖不住的目标时必须注入自定义判定器。
+     */
+    readonly findSensitiveWords?: SensitiveWordFinder;
+};
+/** 内置规则判定器：身份证号（18 位）与手机号（1 开头 11 位）。 */
+export declare const findSensitiveWordsByRules: (text: string) => readonly SensitiveWord[];
+/**
+ * 创建 TextIn 识别脱敏器。凭证在 create 时一次绑定，之后 mask 只传业务参数。
+ * 同一敏感词在一行出现多次时逐处遮盖、逐处登记 mapping（占位符按类别各自编号）。
+ */
+export declare const createTextInMasker: (options: TextInMaskerOptions) => Masker;