@onco-foundry/mask-port 0.1.0

package/dist/create_masker.d.ts

@@ -0,0 +1,19 @@
+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';
+/**
+ * 脱敏器的装配选项：kind 判别用哪个实现。
+ * 加新供应商时在这里加一个 union 成员，调用方只改 kind。
+ */
+export type MaskerOptions = {
+    readonly kind: 'fake';
+} | ({
+    readonly kind: 'tencent';
+} & TencentMaskerOptions) | ({
+    readonly kind: 'textin';
+} & TextInMaskerOptions) | ({
+    readonly kind: 'qwen-agent-name';
+} & QwenAgentMaskerOptions);
+/** 脱敏端口的唯一工厂：换供应商只改 kind，调用方不 import 具体实现。 */
+export declare const createMasker: (options: MaskerOptions) => Promise<Masker>;

package/dist/create_masker.js

@@ -0,0 +1,17 @@
+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';
+/** 脱敏端口的唯一工厂：换供应商只改 kind，调用方不 import 具体实现。 */
+export const createMasker = async (options) => {
+    switch (options.kind) {
+        case 'fake':
+            return createFakeMasker();
+        case 'tencent':
+            return createTencentMasker(options);
+        case 'textin':
+            return createTextInMasker(options);
+        case 'qwen-agent-name':
+            return await createQwenAgentMasker(options);
+    }
+};

package/dist/fake_masker.d.ts

@@ -0,0 +1,3 @@
+import type { Masker } from './masker.ts';
+/** 不做任何脱敏的 Masker：原样返回图片，mapping 为空。供测试和本地开发使用。 */
+export declare function createFakeMasker(): Masker;

package/dist/fake_masker.js

@@ -0,0 +1,12 @@
+/** 不做任何脱敏的 Masker：原样返回图片，mapping 为空。供测试和本地开发使用。 */
+export function createFakeMasker() {
+    return {
+        async mask(request) {
+            return {
+                maskedImageBytes: request.imageBytes,
+                mapping: [],
+                processorVersion: { engine: 'fake-masker-v1' },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+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 { createTencentMasker, type TencentMaskerOptions } from './tencent_masker.ts';
+export { createTextInMasker, findSensitiveWordsByRules, type SensitiveWord, type SensitiveWordFinder, type TextInMaskerOptions, } from './textin_masker.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';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { MASK_TARGETS, } from './masker.js';
+export { createMasker } from './create_masker.js';
+export { createTencentMasker } from './tencent_masker.js';
+export { createTextInMasker, findSensitiveWordsByRules, } from './textin_masker.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';

package/dist/llm_sensitive_word_finder.d.ts

@@ -0,0 +1,22 @@
+/**
+ * LLM 敏感词判定器：把 OCR 全文发给 Anthropic 兼容模型（Messages API），提取隐私实体。
+ * 模型只回原文中逐字出现的词，脱敏器按这些词在字符坐标里定位遮盖。
+ * 协议与上游 agent-lattice 一致：POST {baseURL}/v1/messages。
+ *
+ * 注意：OCR 全文含隐私，启用它意味着文本出域给该模型服务；
+ * 只有该服务被批准作为隐私数据处理方时才可装配。
+ */
+import type { SensitiveWordFinder } from './textin_masker.ts';
+export type LlmSensitiveWordFinderOptions = {
+    readonly baseURL: string;
+    readonly apiKey: string;
+    readonly model: string;
+    readonly timeoutMs?: number;
+    /** 测试注入缝：替换掉真实的 HTTP 层，不碰网络。 */
+    readonly fetch?: typeof fetch;
+};
+/**
+ * 创建 LLM 敏感词判定器，直接作为 TextIn 脱敏器的 findSensitiveWords 使用。
+ * 模型返回的词若不在端口目标集内、不是原文子串或为空，一律丢弃。
+ */
+export declare const createLlmSensitiveWordFinder: (options: LlmSensitiveWordFinderOptions) => SensitiveWordFinder;

package/dist/llm_sensitive_word_finder.js

@@ -0,0 +1,125 @@
+/**
+ * LLM 敏感词判定器：把 OCR 全文发给 Anthropic 兼容模型（Messages API），提取隐私实体。
+ * 模型只回原文中逐字出现的词，脱敏器按这些词在字符坐标里定位遮盖。
+ * 协议与上游 agent-lattice 一致：POST {baseURL}/v1/messages。
+ *
+ * 注意：OCR 全文含隐私，启用它意味着文本出域给该模型服务；
+ * 只有该服务被批准作为隐私数据处理方时才可装配。
+ */
+import { z } from 'zod';
+import { AppError } from '@onco-foundry/errors';
+import { MASK_TARGETS } from './masker.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+// prompt 是模块内置资产，不开放注入：本模块定位就是医疗文书脱敏，提取口径由模块自己保证。
+const SYSTEM_PROMPT = `你从医疗文书扫描件（病历、检查报告、住院单等）的 OCR 文本中提取隐私信息。只提取以下类别：
+- patient_name：患者姓名（包括「姓名：」标签后的、正文叙述中出现的）
+- id_number：身份证号等证件号码
+- phone：手机号、联系电话
+- address：住址、联系地址
+- doctor_signature：医生姓名（签名处或「医师：」标签后的）
+
+要求：
+- 只输出原文中逐字出现的字符串，不改写、不概括、不补全。
+- 医院名、科室名、病名、药名不是隐私，不要提取。
+- 没有可提取的内容就输出空数组。
+- 只输出 JSON 数组，形如 [{"text":"张三","target":"patient_name"}]，不要输出任何其他内容。`;
+const extractedSchema = z.array(z.object({
+    text: z.string(),
+    target: z.string(),
+}));
+const modelResponseSchema = z.object({
+    content: z.array(z.object({
+        type: z.string(),
+        text: z.string().optional(),
+    })).min(1),
+});
+const extractJsonArray = (content) => {
+    const cleaned = content.trim()
+        .replace(/^```(?:json)?\s*/u, '')
+        .replace(/\s*```$/u, '');
+    const start = cleaned.indexOf('[');
+    const end = cleaned.lastIndexOf(']');
+    if (start < 0 || end <= start) {
+        throw new AppError('LLM 敏感词提取返回的结构不是 JSON 数组', 502);
+    }
+    try {
+        return JSON.parse(cleaned.slice(start, end + 1));
+    }
+    catch {
+        throw new AppError('LLM 敏感词提取返回的 JSON 无法解析', 502);
+    }
+};
+/**
+ * 创建 LLM 敏感词判定器，直接作为 TextIn 脱敏器的 findSensitiveWords 使用。
+ * 模型返回的词若不在端口目标集内、不是原文子串或为空，一律丢弃。
+ */
+export const createLlmSensitiveWordFinder = (options) => {
+    const credentials = z.object({
+        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 });
+    if (!credentials.success) {
+        throw new AppError('LLM 敏感词判定器配置非法', 500);
+    }
+    const doFetch = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return async (text) => {
+        if (text.trim() === '')
+            return [];
+        let response;
+        try {
+            response = await doFetch(`${options.baseURL.replace(/\/$/u, '')}/v1/messages`, {
+                method: 'POST',
+                headers: {
+                    'x-api-key': options.apiKey,
+                    'anthropic-version': '2023-06-01',
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model: options.model,
+                    system: SYSTEM_PROMPT,
+                    messages: [{ role: 'user', content: text }],
+                    temperature: 0,
+                    max_tokens: 4096,
+                    stream: false,
+                }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new AppError(`LLM 敏感词提取请求未完成：${error instanceof Error ? error.name : '未知错误'}`, 502);
+        }
+        if (!response.ok) {
+            throw new AppError(`LLM 敏感词提取 HTTP ${response.status}`, 502);
+        }
+        const payload = modelResponseSchema.safeParse(await response.json().catch(() => undefined));
+        if (!payload.success) {
+            throw new AppError('LLM 敏感词提取响应缺少模型输出', 502);
+        }
+        // 带推理的模型会先回 thinking 块，取第一个 text 块。
+        const textBlock = payload.data.content.find((block) => block.type === 'text' && block.text);
+        if (textBlock?.text === undefined) {
+            throw new AppError('LLM 敏感词提取响应缺少文本输出', 502);
+        }
+        const parsed = extractedSchema.safeParse(extractJsonArray(textBlock.text));
+        if (!parsed.success) {
+            throw new AppError('LLM 敏感词提取返回的结构校验失败', 502);
+        }
+        const seen = new Set();
+        const words = [];
+        for (const item of parsed.data) {
+            const word = item.text.trim();
+            if (word === '' || !text.includes(word))
+                continue;
+            if (!MASK_TARGETS.includes(item.target))
+                continue;
+            const key = `${item.target}${word}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            words.push({ text: word, target: item.target });
+        }
+        return words;
+    };
+};

package/dist/masker.d.ts

@@ -0,0 +1,45 @@
+/** 脱敏目标类别。 */
+export declare const MASK_TARGETS: readonly ['patient_name', 'id_number', 'phone', 'address', 'doctor_signature'];
+export type MaskTarget = (typeof MASK_TARGETS)[number];
+export type MaskRequest = {
+    /** 待脱敏的图片字节。 */
+    readonly imageBytes: Uint8Array;
+    /** 本次要脱敏的目标类别。 */
+    readonly targets: readonly MaskTarget[];
+    /** 图片内容顺时针旋转多少度后可正立阅读；缺省表示无需旋转。 */
+    readonly rotationClockwiseDegrees?: 0 | 90 | 180 | 270;
+};
+/**
+ * 一处脱敏的对应记录：脱敏版上的占位符对应原文的哪段内容。
+ * 证据链回溯时用它把脱敏版上的行号定位回原文区间。
+ */
+export type MaskMappingEntry = {
+    /** 脱敏版上替换原文的占位符，如 [姓名1]。 */
+    readonly placeholder: string;
+    /** 该处脱敏的目标类别。 */
+    readonly target: MaskTarget;
+    /** 被遮盖的原文内容。 */
+    readonly originalText: string;
+};
+export type MaskResult = {
+    /** 脱敏后的图片字节。 */
+    readonly maskedImageBytes: Uint8Array;
+    /** 占位符与原文区间的对应记录，按出现顺序排列。 */
+    readonly mapping: readonly MaskMappingEntry[];
+    /**
+     * 脱敏过程中顺带识别出的原文全文（含隐私，限信任域内使用）。
+     * 只有内部带 OCR 的引擎（如 TextIn）才返回；下游用它按 mapping 替换出
+     * 脱敏文本后，可以省掉对脱敏图的第二次 OCR。其它引擎不返回该字段。
+     */
+    readonly recognizedText?: string;
+    /** 产出绑定的脱敏实现、模型与 prompt 版本，供归档审计。 */
+    readonly processorVersion?: {
+        readonly engine: string;
+        readonly model?: string;
+        readonly prompt?: string;
+    };
+};
+/** 图片脱敏端口：遮盖指定类别的隐私信息，并返回占位符映射供回溯。 */
+export type Masker = {
+    mask(request: MaskRequest): Promise<MaskResult>;
+};

package/dist/masker.js

@@ -0,0 +1,8 @@
+/** 脱敏目标类别。 */
+export const MASK_TARGETS = [
+    'patient_name',
+    'id_number',
+    'phone',
+    'address',
+    'doctor_signature',
+];

package/dist/quad.d.ts

@@ -0,0 +1,13 @@
+export type Point = readonly [number, number];
+export type Quad = readonly [Point, Point, Point, Point];
+/**
+ * 把模型返回的旋转框规范化成 0-1000 归一化坐标。
+ * 容忍模型偶尔返回 0-1 小数坐标；越界和零面积框拒绝（交付合同，不是内容判断）。
+ */
+export declare const normalizeQuad: (raw: unknown) => Quad;
+export declare const normalizedToPixels: (quad: Quad, width: number, height: number) => Quad;
+/** 以中心为原点外扩，给笔画外缘留安全边。 */
+export declare const scaleQuad: (quad: Quad, factor: number) => Quad;
+export declare const clampQuad: (quad: Quad, width: number, height: number) => Quad;
+/** 把像素坐标旋转框渲染成白色多边形 SVG 遮罩，供 sharp composite 使用。 */
+export declare const polygonSvg: (width: number, height: number, quads: readonly Quad[]) => Buffer;

package/dist/quad.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { AppError } from '@onco-foundry/errors';
+/**
+ * 把模型返回的旋转框规范化成 0-1000 归一化坐标。
+ * 容忍模型偶尔返回 0-1 小数坐标；越界和零面积框拒绝（交付合同，不是内容判断）。
+ */
+export const normalizeQuad = (raw) => {
+    const points = z.array(z.tuple([z.number(), z.number()])).length(4).parse(raw);
+    const scale = Math.max(...points.flatMap((point) => point.map(Math.abs))) <= 1.5 ? 1000 : 1;
+    const normalized = points.map(([x, y]) => [x * scale, y * scale]);
+    if (normalized.some(([x, y]) => x < 0 || x > 1000 || y < 0 || y > 1000)) {
+        throw new AppError('Qwen 语义脱敏返回了越界坐标', 502);
+    }
+    const twiceArea = Math.abs(normalized.reduce((sum, [x, y], index) => {
+        const next = normalized[(index + 1) % normalized.length];
+        return sum + x * next[1] - next[0] * y;
+    }, 0));
+    if (twiceArea < 1) {
+        throw new AppError('Qwen 语义脱敏返回了零面积旋转框', 502);
+    }
+    return normalized;
+};
+export const normalizedToPixels = (quad, width, height) => quad.map(([x, y]) => [x / 1000 * width, y / 1000 * height]);
+/** 以中心为原点外扩，给笔画外缘留安全边。 */
+export const scaleQuad = (quad, factor) => {
+    const centerX = quad.reduce((sum, [x]) => sum + x, 0) / quad.length;
+    const centerY = quad.reduce((sum, [, y]) => sum + y, 0) / quad.length;
+    return quad.map(([x, y]) => [
+        centerX + (x - centerX) * factor,
+        centerY + (y - centerY) * factor,
+    ]);
+};
+export const clampQuad = (quad, width, height) => quad.map(([x, y]) => [
+    Math.max(0, Math.min(width, x)),
+    Math.max(0, Math.min(height, y)),
+]);
+/** 把像素坐标旋转框渲染成白色多边形 SVG 遮罩，供 sharp composite 使用。 */
+export const polygonSvg = (width, height, quads) => {
+    const polygons = quads.map((quad) => {
+        const points = quad.map(([x, y]) => `${x.toFixed(2)},${y.toFixed(2)}`).join(' ');
+        return `<polygon points="${points}" fill="#ffffff"/>`;
+    }).join('');
+    return Buffer.from(`<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${polygons}</svg>`);
+};

package/dist/qwen_agent_masker.d.ts

@@ -0,0 +1,81 @@
+import { type ModelClient } from 'agent-lattice';
+import { z } from 'zod';
+import { type Capability } from '@onco-foundry/capability-registry';
+import { type Tracer } from '@onco-foundry/trace-port';
+import { type Masker, type MaskResult } from './masker.ts';
+export type QwenAgentMaskerOptions = {
+    readonly baseURL: string;
+    readonly apiKey: string;
+    readonly model: string;
+    /** 缺省 noop；传入后 loop 的模型调用与工具执行以原生事件流进追踪后端。 */
+    readonly tracer?: Tracer;
+    /** 测试注入缝：替换掉真实的模型客户端，不碰网络。 */
+    readonly modelClient?: ModelClient;
+    /** loop 轮次上限：资源边界，不是对模型的判断；耗尽仍未 submit 则整次失败。 */
+    readonly maxTurns?: number;
+    readonly maxTokens?: number;
+    readonly maxInputBytes?: number;
+    /** 仅用于离线回归指定旧 prompt；生产不传，按 current.json 加载。 */
+    readonly promptVersionOverride?: string;
+};
+/** 能力入参契约：V1 只接 patient_name（契约写死；直接调 mask() 时由内部目标校验兜底）。 */
+export declare const qwenAgentNameMaskInputSchema: z.ZodObject<{
+    imageBytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    targets: z.ZodArray<z.ZodLiteral<"patient_name">>;
+    rotationClockwiseDegrees: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>;
+}, z.core.$strip>;
+export type QwenAgentNameMaskInput = z.infer<typeof qwenAgentNameMaskInputSchema>;
+/**
+ * 能力名片：Qwen 脱敏智能体向能力注册表自报家门的最小元数据。
+ * kind 是 code——与 tencent/textin 同是 Masker 端口的平级实现，边界上就是一次脱敏调用；
+ * 内部跑 LLM loop 还是调专用 API 是后端选型，不该改变 kind（见 CapabilityKind 的定义）。
+ * version 不归名片管：asCapability 默认取 prompt 版本，场景可覆盖。
+ */
+export declare const qwenAgentNameMaskCapabilityCard: {
+    readonly name: 'qwen-agent-name-mask';
+    readonly kind: 'code';
+    readonly summary: '对医疗单据图片做病人姓名脱敏，返回脱敏图与占位符映射';
+    readonly input: z.ZodObject<{
+        imageBytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+        targets: z.ZodArray<z.ZodLiteral<"patient_name">>;
+        rotationClockwiseDegrees: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<90>, z.ZodLiteral<180>, z.ZodLiteral<270>]>>;
+    }, z.core.$strip>;
+    readonly output: z.ZodObject<{
+        maskedImageBytes: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
+        mapping: z.ZodArray<z.ZodObject<{
+            placeholder: z.ZodString;
+            target: z.ZodEnum<{
+                address: "address";
+                doctor_signature: "doctor_signature";
+                id_number: "id_number";
+                patient_name: "patient_name";
+                phone: "phone";
+            }>;
+            originalText: z.ZodString;
+        }, z.core.$strip>>;
+        recognizedText: z.ZodOptional<z.ZodString>;
+        processorVersion: z.ZodOptional<z.ZodObject<{
+            engine: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+export type QwenAgentMasker = Masker & {
+    /**
+     * 投射成注册表能力：名片、run、版本一次绑好，registry.register 直接收。
+     * 默认版本取本实例的 prompt 版本（行为随 prompt 变）；场景要钉自己的版本标识时传 version 覆盖。
+     */
+    asCapability(options?: {
+        readonly version?: string;
+    }): Capability<QwenAgentNameMaskInput, MaskResult>;
+};
+/**
+ * Qwen 脱敏智能体：模型在 loop 里闭环完成「报框 → 看遮盖结果 → 补框/确认」。
+ *
+ * 模型只负责看和报（report_quads 报旋转框、remove_quads 撤销报错的框、submit 确认无残留）；遮盖动作永远由
+ * 代码执行，每次变动后把重绘的遮盖图作为 tool_result 图片喂回模型。
+ * 遮盖决策与最终裁判都归模型，代码不加内容判断；maxTurns 是资源边界，耗尽仍未
+ * submit 等于没有交付物，图片不放行（422）。原始模型响应不写磁盘、不进错误信息。
+ */
+export declare const createQwenAgentMasker: (options: QwenAgentMaskerOptions) => Promise<QwenAgentMasker>;