@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.2

package/lib/dsh-adapter/openai-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-sse.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/openai-sse.ts"],"names":[],"mappings":"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"}

package/lib/dsh-adapter/openai-sse.js

@@ -0,0 +1,462 @@
+/**
+ * openai-sse — shared helpers for talking to OpenAI-compatible
+ * `/chat/completions` endpoints. Both `cloud-llm-adapter` (DeepSeek)
+ * and `local-llm-adapter` (`mode: 'real'`) drive their wire envelope
+ * and SSE parse through this module so a wire-protocol change lands
+ * in one place.
+ *
+ * Wire shape:
+ *   POST {baseUrl}/chat/completions
+ *     { model, messages, stream: true, tools?, temperature?, max_tokens? }
+ *   response: `text/event-stream` of `data: {...}` frames ending in
+ *     `data: [DONE]`. The adapter translates frames into the DSH
+ *     `StreamChunk` union (block-start, text-delta, reasoning-delta,
+ *     tool-call-delta, block-end, usage, finish).
+ *
+ * @module dsh-edge-agent/openai-sse
+ */
+import { attributionHeaders, LlmError, ToolCallId as brandCallId } from '@deepseek-ai/dsh-llm';
+/**
+ * §7.105 (2026-10-21): an empty tool-call id is FATAL, not cosmetic.
+ *
+ * OpenAI-compatible endpoints may omit the tool-call `id` entirely (some
+ * llama.cpp / vLLM builds send `tool_calls` deltas with no `id` field) or
+ * send `id: ""`. The host persists that id verbatim into the v4 session log,
+ * and the log validator rejects the WHOLE FILE on the next load
+ * ("tool call id requires a nonempty string") — so ONE bad tool call makes
+ * the entire session history unloadable, not just the affected turn.
+ *
+ * Never let an empty id escape this module. The synthesized id is stored in
+ * the per-stream `toolCalls` map, which keeps it stable across every delta
+ * of one call and identical to the final `block-end` block, so the host's
+ * assistant message advertises exactly one id for the call.
+ */
+function synthesizeToolCallId(wireIndex) {
+    return `call_local_${wireIndex}_${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Pick the first candidate that is a NONEMPTY string, else `fallback`.
+ * `??` is not enough: an empty string survives `??` but is an invalid
+ * OpenAI `id` / `tool_call_id`.
+ */
+function firstNonEmptyId(candidates, fallback) {
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate !== '')
+            return candidate;
+    }
+    return fallback;
+}
+/** Build the wire body for `POST /chat/completions`. */
+export function buildChatCompletionsBody(options, defaultModel, temperature, 
+// §7.87.5 (2026-09-19): inject `chat_template_kwargs={enable_thinking: false}`
+// for thinking models (qwen3.5 / QwQ / DeepSeek-R1). Default OFF — production
+// wants fast non-reasoning answers; users can opt-in via env var.
+enableThinking = false, 
+// §7.106 (2026-10-23): also send the standard `reasoning_effort:"none"` —
+// the dialect OLLAMA's /v1 layer actually honors (probe-verified on the
+// user's <内网主机>:11434: chat_template_kwargs AND top-level `think:false`
+// are both silently dropped there; reasoning_effort:none removed
+// message.reasoning and took completion 46→6 tokens). Without it the
+// 256-token model-detect call has its budget eaten by reasoning and
+// returns empty content (finish=length → json-parse-failed → fail-open).
+// Only the local pool sets this — unknown-field-strict servers stay on
+// the old dialect alone.
+alsoReasoningEffort = false) {
+    const wireMessages = [];
+    if (options.system !== undefined && options.system.length > 0) {
+        wireMessages.push({ role: 'system', content: options.system });
+    }
+    // §7.105 (2026-10-21): resolve tool-call ids UP FRONT so an assistant
+    // tool-call and its tool-result always carry the SAME id on the wire.
+    //
+    // `??` lets an EMPTY id through (it is not nullish), and a tool-call id
+    // that is empty on the wire is rejected upstream. It is also the id the
+    // host persists into the session log — the v4 log validator rejects the
+    // WHOLE file on an empty tool-call id ("tool call id requires a nonempty
+    // string"), so one empty id makes an entire session fail to load.
+    //
+    // The blocks are deep-frozen at runtime, so the resolved id is carried in a
+    // side map instead of being written back. Results always follow their call
+    // in conversation order, so a FIFO queue pairs an id-less result with the
+    // id-less call it answers.
+    const resolvedIds = new Map();
+    const pendingEmptyCallIds = [];
+    for (const message of options.messages) {
+        const blocks = (Array.isArray(message.content) ? message.content : []);
+        for (const block of blocks) {
+            if (block.type === 'tool-call') {
+                const existing = firstNonEmptyId([block.toolCallId, block.callId, block.id], '');
+                if (existing !== '') {
+                    resolvedIds.set(block, existing);
+                }
+                else {
+                    const synthesized = `call_${Math.random().toString(36).slice(2)}`;
+                    resolvedIds.set(block, synthesized);
+                    pendingEmptyCallIds.push(synthesized);
+                }
+            }
+            else if (block.type === 'tool-result') {
+                const existing = firstNonEmptyId([block.toolCallId, block.callId, block.id], '');
+                if (existing !== '') {
+                    resolvedIds.set(block, existing);
+                }
+                else {
+                    resolvedIds.set(block, pendingEmptyCallIds.shift() ?? `call_${Math.random().toString(36).slice(2)}`);
+                }
+            }
+        }
+    }
+    for (const message of options.messages) {
+        // Cordis messages use content-block arrays. We need to translate:
+        //   - text blocks → concatenated text content
+        //   - tool-call blocks → OpenAI `tool_calls` field (assistant messages)
+        //   - tool-result blocks → separate `role: 'tool'` messages with `tool_call_id`
+        const blocks = (Array.isArray(message.content) ? message.content : []);
+        // §7.119 (2026-10-26): DSH 的**规范** tool-result 形状是「消息级」的 ——
+        //   { role:'tool', toolCallId:'call_x', source:{kind:'tool',callId:'call_x'},
+        //     content:[{type:'text', text:'…'}] }
+        // （上游 `createToolResultMessage()` 造的就是这个形状，见
+        // @deepseek-ai/dsh-llm lib/index.js。）
+        //
+        // 旧实现只认 content 里 `type==='tool-result'` 的块，于是把上面这条消息
+        // 当成普通消息处理：tool_call_id 直接丢失 → §7.106 的配对守卫（下面
+        // 205-215 行）判定它「找不到配对的 call」→ 降级成
+        //   role:'user', content:"[tool-result (unreferenced) lost its matching
+        //   call; output:]\n<真实输出>"
+        // 也就是说**模型的每一个工具结果都是以「丢失配对」的 user 文本进去的**，
+        // 而 assistant 侧的 tool_call 从来没被真正应答过。
+        //
+        // 实测：真实会话里 100% 的 tool/result 事件都是这个形状（77/77）——
+        // 整条工具结果通道是坏的，不是偶发。
+        //
+        // 这里补一条消息级分支：能取到 id 就按真正的 `role:'tool'` + `tool_call_id`
+        // 下发，取不到才回落到下面的块级路径（保持旧行为）。
+        if (message.role === 'tool') {
+            const messageId = firstNonEmptyId([
+                message.toolCallId,
+                message.source?.callId,
+                message.source?.toolCallId,
+            ], '');
+            if (messageId !== '') {
+                const toolText = typeof message.content === 'string'
+                    ? message.content
+                    : extractText(blocks);
+                wireMessages.push({ role: 'tool', tool_call_id: messageId, content: toolText });
+                continue;
+            }
+        }
+        const textParts = [];
+        const toolCalls = [];
+        const toolResults = [];
+        for (const block of blocks) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                textParts.push(block.text);
+            }
+            else if (block.type === 'tool-call') {
+                toolCalls.push({
+                    id: resolvedIds.get(block) ?? firstNonEmptyId([block.toolCallId, block.callId, block.id], `call_${Math.random().toString(36).slice(2)}`),
+                    type: 'function',
+                    function: {
+                        name: String(block.name ?? ''),
+                        arguments: typeof block.arguments === 'string' ? block.arguments : JSON.stringify(block.arguments ?? {}),
+                    },
+                });
+            }
+            else if (block.type === 'tool-result') {
+                toolResults.push({
+                    id: resolvedIds.get(block) ?? firstNonEmptyId([block.toolCallId, block.callId, block.id], ''),
+                    content: typeof block.content === 'string' ? block.content : extractText(block.content),
+                });
+            }
+            // reasoning blocks are intentionally skipped for the wire format
+        }
+        // Tool results become separate `role: 'tool'` messages
+        if (toolResults.length > 0) {
+            for (const tr of toolResults) {
+                wireMessages.push({ role: 'tool', tool_call_id: tr.id, content: tr.content });
+            }
+            continue;
+        }
+        // Build the wire message with appropriate fields
+        const wireMsg = { role: message.role };
+        wireMsg.content = textParts.length > 0 ? textParts.join('') : (toolCalls.length > 0 ? null : '');
+        if (toolCalls.length > 0) {
+            wireMsg.tool_calls = toolCalls;
+        }
+        wireMessages.push(wireMsg);
+    }
+    // §7.106 (2026-10-23) pairing guard: every `role:'tool'` message must
+    // reference an assistant tool_call that EXISTS IN THIS BODY. Strict
+    // gateways (minimax 2013 "tool result's tool id() not found") enforce the
+    // referential integrity DeepSeek silently tolerates. Broken histories come
+    // from the ollama-era models' empty-id tool calls (§7.105 class): a result
+    // whose call was pruned out of the window, or whose FIFO-synthesized id
+    // was never claimed by an assistant message, is an orphan no upstream will
+    // accept. Demote orphans to plain user text — the tool OUTPUT survives for
+    // the model to read, only the dangling reference goes away.
+    {
+        const claimedCallIds = new Set();
+        for (const m of wireMessages) {
+            const tcs = m.tool_calls;
+            if (Array.isArray(tcs)) {
+                for (const tc of tcs) {
+                    if (typeof tc.id === 'string' && tc.id.length > 0)
+                        claimedCallIds.add(tc.id);
+                }
+            }
+        }
+        for (let i = 0; i < wireMessages.length; i++) {
+            const m = wireMessages[i];
+            if (m.role !== 'tool')
+                continue;
+            const id = typeof m.tool_call_id === 'string' ? m.tool_call_id : '';
+            if (id.length > 0 && claimedCallIds.has(id))
+                continue;
+            const text = typeof m.content === 'string' ? m.content : '';
+            wireMessages[i] = {
+                role: 'user',
+                content: `[tool-result ${id.length > 0 ? id : '(unreferenced)'} lost its matching call; output:]\n${text}`,
+            };
+        }
+    }
+    const body = {
+        // CRITICAL: use the adapter's configured `defaultModel` (the real upstream
+        // model name, e.g. "deepseek-chat"), NOT `options.model` which is the Cordis
+        // provider route ID (e.g. "cloud-llm"). The route ID is meaningless
+        // to the upstream API — only the adapter knows its own model name.
+        model: defaultModel,
+        messages: wireMessages,
+        stream: true,
+    };
+    if (options.tools !== undefined && options.tools.length > 0) {
+        body.tools = options.tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+            },
+        }));
+    }
+    if (temperature !== undefined)
+        body.temperature = temperature;
+    if (options.maxTokens !== undefined)
+        body.max_tokens = options.maxTokens;
+    // §7.87.5 (2026-09-19): disable chain-of-thought for thinking-capable models
+    // (qwen3.5 / QwQ / DeepSeek-R1). Without this, max_tokens gets burned on
+    // reasoning and `content` returns "" (finish_reason="length"). Pass-through
+    // is a no-op for non-thinking servers — they ignore unknown kwargs.
+    if (!enableThinking) {
+        body.chat_template_kwargs = { enable_thinking: false };
+        if (alsoReasoningEffort)
+            body.reasoning_effort = 'none';
+    }
+    return body;
+}
+/** Pull the text out of a content-block array into one concatenated string. */
+export function extractText(blocks) {
+    return blocks
+        .filter((block) => block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+}
+/** Read a `Response` body as an SSE stream and yield finished frames. */
+export async function* iterateSseFrames(response, onError) {
+    if (!response.ok || response.body === null) {
+        const text = await response.text().catch(() => '');
+        throw new LlmError(`OpenAI-compatible SSE: HTTP ${response.status} from ${response.url}: ${text.slice(0, 512)}`, 'PROVIDER_ERROR');
+    }
+    const stream = response.body;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buffer = '';
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const events = splitSseEvents(buffer);
+            buffer = events.remainder;
+            for (const event of events.events) {
+                const chunk = parseSseEvent(event);
+                if (chunk !== undefined)
+                    yield chunk;
+            }
+        }
+    }
+    catch (error) {
+        onError(error.message ?? String(error));
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * Translate a `text-delta` or `tool-call-delta` SSE event into a DSH
+ * `StreamChunk`. Returns `null` for `finish` events — the caller
+ * tracks the finish reason separately and emits the terminal `finish`
+ * through `terminalChunks` once the SSE stream closes.
+ */
+export function sseEventToChunk(event, toolCalls) {
+    if (event.kind === 'text-delta') {
+        return { chunk: { type: 'text-delta', index: 0, text: event.text }, sawText: true, sawToolCall: false };
+    }
+    if (event.kind === 'tool-call-delta') {
+        const current = toolCalls.get(event.index) ?? { id: '', name: '', arguments: '' };
+        // §7.105 (2026-10-21): the upstream `id` may be absent or empty. A
+        // tool-call id must be a NONEMPTY string — the host's v4 session-log
+        // validator rejects the entire log on an empty id ("tool call id requires
+        // a nonempty string"), which is how one local-llm tool call made a whole
+        // session fail to load. Prefer the upstream id when it has one; otherwise
+        // synthesize a stable id for this wire index and remember it, so every
+        // later delta of the same call and the final `block-end` agree.
+        if (event.id !== undefined && event.id !== '')
+            current.id = event.id;
+        else if (current.id === '')
+            current.id = synthesizeToolCallId(event.index);
+        if (event.name !== undefined)
+            current.name = event.name;
+        current.arguments += event.argumentsDelta;
+        toolCalls.set(event.index, current);
+        const idForChunk = current.id;
+        // CRITICAL: dsh-session's `snapshotJsonValue` rejects chunks with `undefined`
+        // fields (throws "carries non-JSON-serializable data"). When DeepSeek splits
+        // a tool call across multiple deltas, intermediate chunks omit `name` (and
+        // on the very first chunk the local accumulator's `name` is still `''`).
+        // Strip `undefined` so the chunk survives lossless JSON validation.
+        // §7.58 (2026-09-16): the chunk index MUST equal the index `terminalChunks`
+        // later uses for the matching `block-end` — both are `wire index + 1`
+        // (index 0 belongs to text). They used to disagree (delta = wire index 0,
+        // block-end = 1-based sequential): the host `BlockAssembler` keys partials
+        // by index, so the delta-accumulated call and the block-end landed in two
+        // different blocks → one persisted assistant message with the SAME
+        // tool-call duplicated under a single shared id, and the next replay got
+        // DeepSeek 400 "Duplicate value for 'tool_call_id' … in message[N]"
+        // (session 24303d6a turn 2, 2026-09-15). Only text-less tool turns were
+        // affected — when text came first, it squatted index 0 and the colliding
+        // delta was harmlessly merged into the text partial.
+        const chunk = {
+            type: 'tool-call-delta',
+            index: event.index + 1,
+            id: brandCallId(idForChunk),
+            argumentsDelta: event.argumentsDelta,
+        };
+        if (event.name !== undefined)
+            chunk.name = event.name;
+        return {
+            chunk,
+            sawText: false,
+            sawToolCall: true,
+        };
+    }
+    return null;
+}
+/** Extract the finish reason out of a `finish` event. */
+export function sseFinishReason(event) {
+    return event.kind === 'finish' ? event.finishReason : undefined;
+}
+/** Emit the terminal chunks: text `block-end`, sorted tool-call `block-end`s, then `finish`. */
+export function* terminalChunks(sawText, assembledText, toolCalls, finishKind, sawToolCall) {
+    if (sawText) {
+        yield { type: 'block-end', index: 0, block: { type: 'text', text: assembledText } };
+    }
+    // CRITICAL: Tool-call block-ends must use indices that don't collide with text (index 0).
+    // The BlockAssembler uses chunk.index to track blocks, so text and tool-calls must have
+    // distinct indices. §7.58: the mapping is EXACTLY `wire index + 1` — the same one
+    // sseEventToChunk applies to live tool-call-delta chunks — so each call's delta
+    // partial and its block-end land in the SAME block slot. Sequential numbering
+    // (`toolCallIndex++`) instead would diverge whenever wire indices have gaps and
+    // double the tool-calls whenever a delta partial was already open (see the
+    // duplicate-id incident documented at the tool-call-delta yield above).
+    for (const [wireIndex, call] of [...toolCalls.entries()].sort((a, b) => a[0] - b[0])) {
+        yield {
+            type: 'block-end',
+            index: wireIndex + 1,
+            block: {
+                type: 'tool-call',
+                // §7.105 (2026-10-21): the block-end id is the one the host persists
+                // into `assistant/message`, so it must never be empty. `sseEventToChunk`
+                // already synthesized one when the upstream omitted it; this guard
+                // covers a map populated by any other path.
+                id: brandCallId((call.id !== '' ? call.id : synthesizeToolCallId(wireIndex))),
+                name: call.name,
+                arguments: call.arguments,
+            },
+        };
+    }
+    yield {
+        type: 'finish',
+        reason: finishKind === 'length'
+            ? { kind: 'max-tokens' }
+            : finishKind === 'tool-calls' || sawToolCall
+                ? { kind: 'tool-calls' }
+                : { kind: 'stop' },
+    };
+}
+export function splitSseEvents(buffer) {
+    const events = [];
+    let idx = buffer.indexOf('\n\n');
+    let cursor = 0;
+    while (idx !== -1) {
+        events.push(buffer.slice(cursor, idx));
+        cursor = idx + 2;
+        idx = buffer.indexOf('\n\n', cursor);
+    }
+    return { events, remainder: buffer.slice(cursor) };
+}
+export function parseSseEvent(raw) {
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        if (!line.startsWith('data:'))
+            continue;
+        const payload = line.slice(5).trim();
+        if (payload.length === 0 || payload === '[DONE]')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch {
+            continue;
+        }
+        const record = parsed;
+        const choices = record.choices;
+        if (!Array.isArray(choices) || choices.length === 0)
+            continue;
+        const choice = choices[0];
+        const delta = choice.delta;
+        const content = delta?.content;
+        if (typeof content === 'string' && content.length > 0) {
+            return { kind: 'text-delta', text: content };
+        }
+        const toolCalls = delta?.tool_calls;
+        if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+            const first = toolCalls[0];
+            const fn = first.function;
+            const index = typeof first.index === 'number' ? first.index : 0;
+            return {
+                kind: 'tool-call-delta',
+                index,
+                id: typeof first.id === 'string' ? first.id : undefined,
+                name: typeof fn?.name === 'string' ? fn.name : undefined,
+                argumentsDelta: typeof fn?.arguments === 'string' ? fn.arguments : '',
+            };
+        }
+        const finishReason = choice.finish_reason;
+        if (typeof finishReason === 'string') {
+            if (finishReason === 'tool_calls') {
+                return { kind: 'finish', finishReason: 'tool-calls' };
+            }
+            return {
+                kind: 'finish',
+                finishReason: finishReason === 'length' ? 'length' : 'stop',
+            };
+        }
+    }
+    return undefined;
+}
+/** Default attribution headers every request should carry. */
+export function defaultAttributionHeaders() {
+    return attributionHeaders();
+}

package/lib/dsh-adapter/pii-utils.d.ts

@@ -0,0 +1,96 @@
+/**
+ * pii-utils — 共享的 PII 检测与脱敏工具
+ *
+ * 本模块是**全项目 PII 正则的唯一事实源**（`PII_PATTERNS`）。
+ * 消费方：
+ *   - `privacy-policy.ts` 的 `DEFAULT_POLICY.sanitizationRules`（直接复用
+ *     `PII_PATTERNS`，不再各写一份字面量）
+ *   - `sanitizer-pipeline.ts` 经由 `privacyPolicy.getSanitizationRules()`
+ *     消费 pattern 字符串做**可逆**脱敏
+ *   - `prompt-guard` / `audit-log` / `local-storage` 经由本模块的
+ *     `redactString` / `redactObject` 做**不可逆**掩码
+ *
+ * 两条链路共用同一批 pattern，只有替换语义不同（占位符 vs 掩码），
+ * 因此 pattern 必须集中定义，禁止在别处重复书写。
+ *
+ * @module dsh-edge-agent/pii-utils
+ */
+export type PIIName = 'id-card' | 'bank-card' | 'phone' | 'email' | 'api-key' | 'ip-address' | 'mac-address' | 'passport' | 'license-plate' | 'credential';
+/**
+ * PII 正则字面量（唯一事实源）。
+ *
+ * 以 `RegExp` source 语法书写（不含分隔符与 flags），便于同时用于
+ * `new RegExp(pattern, 'gi')`（脱敏管线）与本模块的 `RegExp` 实例。
+ *
+ * 规则顺序见 `PII_ORDER` —— 顺序是语义的一部分，长规则必须先跑。
+ */
+export declare const PII_PATTERNS: Record<PIIName, string>;
+/**
+ * 规则求值顺序。长规则优先（id-card → bank-card → phone），防止短规则
+ * 在更长的数字串内部误命中。
+ *
+ * 注意：顺序生效的前提是 `redactString` / `sanitize` 采用**累进匹配**
+ * （每条规则在上一条的产出上继续匹配），否则顺序没有意义。
+ */
+export declare const PII_ORDER: PIIName[];
+/** 各 PII 类型的数据分级，与 privacy-policy 的 dataClassifications 对应。 */
+export declare const PII_DATA_CLASS: Record<PIIName, 'confidential' | 'secret'>;
+/** 不可逆掩码函数（仅用于日志/存储，不参与上云脱敏）。 */
+export declare const PII_MASKS: Record<PIIName, (match: string) => string>;
+export interface PIIRule {
+    name: PIIName;
+    pattern: RegExp;
+    mask: (match: string) => string;
+}
+/**
+ * 10 种 PII 规则，由 `PII_PATTERNS` + `PII_MASKS` 按 `PII_ORDER` 组装。
+ * 与 privacy-policy 的 sanitizationRules 共用同一批 pattern 字面量。
+ */
+export declare const PII_RULES: PIIRule[];
+/**
+ * 对单个字符串应用所有 PII 规则，返回脱敏后的字符串和脱敏明细。
+ *
+ * 累进匹配：每条规则在**上一条规则的产出**（`result`）上继续匹配，而不是
+ * 回到原始 `text`。否则后序规则会命中前序规则已经掩码掉的区间，导致
+ * `result.replace` 静默 no-op、而 `matches` 里却记了一笔不存在的脱敏
+ * （2026-08-30 修复）。
+ *
+ * 同一取值在文本中出现多次时一次性全部替换，且只计一笔，避免计数虚高。
+ */
+export declare function redactString(text: string, rules?: PIIRule[]): {
+    redacted: string;
+    matches: Array<{
+        type: string;
+        masked: string;
+    }>;
+};
+/**
+ * 深度遍历对象，对所有字符串值应用 PII 脱敏。
+ * 返回新对象（不修改原对象）。
+ */
+export declare function redactObject<T>(obj: T, rules?: PIIRule[]): {
+    redacted: T;
+    count: number;
+};
+export declare function normalizeForPII(text: string): {
+    normalized: string;
+    /** `charMap[i]` = 规范化后第 i 个字符在原文本 `text` 中的源位置。
+     *  严格单调递增(规范化要么 1:0 删,要么 1:1 改,从不插入字符)。
+     *  长度 = normalized.length。 */
+    charMap: number[];
+    /** 规范化是否实际改变了文本(便于审计/forensics)。 */
+    changed: boolean;
+};
+/**
+ * 把 `normalizeForPII()` 返回的 charMap + normalized 上的命中区间
+ * `[start, end)` 翻回 `text` 上的对应区间。
+ *
+ * 用法:`sliceOriginal(text, charMap, start, end)` → 用户原始子串
+ * (含被丢弃的空白、被转换的中文数字)。
+ *
+ * 注意:返回字符串的字符数可能 > (end - start),因为 whitespace
+ * 不在 charMap 里但仍在原文本里。
+ */
+export declare function sliceOriginal(text: string, charMap: number[], start: number, end: number): string;
+export declare function containsCredential(text: string): boolean;
+//# sourceMappingURL=pii-utils.d.ts.map

package/lib/dsh-adapter/pii-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii-utils.d.ts","sourceRoot":"","sources":["../../src/dsh-adapter/pii-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,OAAO,GACf,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GACvD,YAAY,GAAG,aAAa,GAAG,UAAU,GAAG,eAAe,GAAG,YAAY,CAAA;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CA8BhD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,EAW9B,CAAA;AAED,+DAA+D;AAC/D,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,QAAQ,CAWrE,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAwBhE,CAAA;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;CAChC;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,OAAO,EAI5B,CAAA;AAEH;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,OAAO,EAAc,GAC3B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAwBxE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,GAAG,EAAE,CAAC,EACN,KAAK,GAAE,OAAO,EAAc,GAC3B;IAAE,QAAQ,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuBhC;AAsED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB;;kCAE8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;CACjB,CAmDA;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,MAAM,CASR;AAUD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD"}