dsh-mask 0.1.1

package/lib/mask.mjs

@@ -0,0 +1,45 @@
+// lib/mask.mjs — 消息遮罩助手（零依赖；把 UserMessage 的文本内容块替换为占位符）。
+
+/**
+ * 遮罩单条 UserMessage 的文本内容块（保留消息结构与来源，仅替换 text 块）。
+ * 非文本块（图片、工具调用等）原样保留，向前兼容。
+ * @param {object} message - UserMessage（含 content 数组）。
+ * @param {import('./strip.mjs').Stripper} stripper - 累计脱敏器。
+ * @returns {{message: object, replaced: number}} 遮罩后消息与本次替换数。
+ */
+export function maskMessage(message, stripper) {
+  if (message === null || typeof message !== 'object' || !Array.isArray(message.content)) {
+    return { message, replaced: 0 }
+  }
+  let replaced = 0
+  let changed = false
+  const content = message.content.map((block) => {
+    if (block === null || typeof block !== 'object' || block.type !== 'text' || typeof block.text !== 'string') {
+      return block
+    }
+    const result = stripper.stripInto(block.text)
+    if (result.replaced > 0) {
+      replaced += result.replaced
+      changed = true
+    }
+    return { ...block, text: result.text }
+  })
+  if (!changed) return { message, replaced: 0 }
+  return { message: { ...message, content }, replaced }
+}
+
+/**
+ * 遮罩消息数组，返回遮罩后数组与总替换数。
+ * @param {object[]} messages - UserMessage 数组。
+ * @param {import('./strip.mjs').Stripper} stripper - 累计脱敏器。
+ * @returns {{messages: object[], replaced: number}} 遮罩后数组与总替换数。
+ */
+export function maskMessages(messages, stripper) {
+  let replaced = 0
+  const masked = (Array.isArray(messages) ? messages : []).map((message) => {
+    const result = maskMessage(message, stripper)
+    replaced += result.replaced
+    return result.message
+  })
+  return { messages: masked, replaced }
+}

package/lib/sanitize.mjs

@@ -0,0 +1,45 @@
+// lib/sanitize.mjs — 展示/日志脱敏纯函数（零依赖）。
+//
+// 规则：任何可能携带 PII 原文的文本在进入日志、命令结果或工具结果前都必须
+// 过这里的纯函数。函数绝不抛错、绝不访问 I/O；输入不合法时返回保守的脱敏文本。
+// 复用 lib/strip.mjs 的检测器词汇，保证"脱敏"与"遮罩"覆盖同一套 PII 类型。
+
+import { BUILTIN_PATTERNS } from './strip.mjs'
+
+/** 合并全部内置检测器为单条脱敏正则（按 PII 原文整体打码）。 */
+const REDACT_RE = new RegExp(BUILTIN_PATTERNS.map(pattern => pattern.source.source).join('|'), 'gu')
+
+/** key=value 形态的凭据（值整体打码；键名保留供定位）。 */
+const CREDENTIAL_ASSIGNMENT = /\b((?:api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|password|passwd|client[_-]?secret|private[_-]?key)\s*=\s*)([^\s&;,]+)/giu
+
+/** URL userinfo（user:password@）——错误消息可能回显远端地址。 */
+const URL_USERINFO = /\/\/([^/\s:@]+):([^/\s@]+)@/gu
+
+/**
+ * 文本脱敏：PII 实体、密钥赋值、URL 凭据整体打码。
+ * 非字符串输入先 String() 强转（绝不抛错——测试锁定此契约）。
+ * @param {unknown} text - 任意输出文本（错误消息、命令/工具结果等）。
+ * @returns {string} 脱敏文本。
+ */
+export function redactText(text) {
+  if (typeof text !== 'string') return String(text)
+  return text
+    .replace(URL_USERINFO, '//***@')
+    .replace(CREDENTIAL_ASSIGNMENT, '$1***')
+    .replace(REDACT_RE, '***')
+}
+
+/**
+ * 映射表脱敏：把 {占位符: 原文} 归约为 {占位符: '***'} 的安全摘要。
+ * 用于任何"必须展示映射却绝不含原文"的边界；正常路径根本不应序列化映射。
+ * @param {unknown} mapping - 占位符到原文的映射（或任意输入）。
+ * @returns {Record<string, string>} 仅含占位符键的安全摘要。
+ */
+export function redactMapping(mapping) {
+  if (mapping === null || typeof mapping !== 'object') return /** @type {Record<string, string>} */ ({})
+  const out = /** @type {Record<string, string>} */ ({})
+  for (const [placeholder] of Object.entries(mapping)) {
+    out[placeholder] = '***'
+  }
+  return out
+}

package/lib/store.mjs

@@ -0,0 +1,125 @@
+// lib/store.mjs — 恢复表存储（内存 Stripper + 受控 storageDomain 持久化，零 I/O 除领域读写）。
+
+import { createStripper } from './strip.mjs'
+import { DEFAULTS, RESTORE_TABLE } from './constants.mjs'
+import { registryUnavailable } from './errors.mjs'
+
+/**
+ * 恢复表：每会话一个累计 Stripper（内存），可选持久化映射到 storageDomain。
+ *
+ * 不变量：PII 原文只出现在这里的内存 Map 与受控 storageDomain（persist 开启时），
+ * 绝不进会话日志。mask/stats 走内存；restore 内存未命中时若 persist 开启则从
+ * 领域回载（跨重启还原）。
+ */
+export class RestoreStore {
+  /**
+   * @param {object} options - {entities, maxEntries, maxSessions, persist, domainPromise, onError}。
+   *   domainPromise 为 Promise<{table(name): {get, put}}> | null。
+   */
+  constructor(options) {
+    this.entities = options.entities ?? DEFAULTS.ENTITIES
+    this.maxEntries = options.maxEntries ?? DEFAULTS.MAX_RESTORE_ENTRIES_PER_SESSION
+    this.maxSessions = options.maxSessions ?? DEFAULTS.MAX_SESSIONS
+    this.persistEnabled = options.persist ?? DEFAULTS.PERSIST_RESTORE_TABLE
+    this.domainPromise = options.domainPromise ?? null
+    this.onError = options.onError ?? (() => {})
+    /** @type {Map<string, import('./strip.mjs').Stripper>} 会话 id -> 累计脱敏器（LRU）。 */
+    this.strippers = new Map()
+  }
+
+  /**
+   * 取得（或创建）会话的累计脱敏器。
+   * @param {string} sessionId - 会话 id。
+   * @returns {import('./strip.mjs').Stripper} 脱敏器。
+   */
+  stripperFor(sessionId) {
+    let stripper = this.strippers.get(sessionId)
+    if (stripper === undefined) {
+      stripper = createStripper({ entities: this.entities, maxEntries: this.maxEntries })
+      this.strippers.set(sessionId, stripper)
+      this._pruneSessions()
+    }
+    return stripper
+  }
+
+  /**
+   * 累计遮罩一段文本（本会话占位符不重置）。
+   * @param {string} sessionId - 会话 id。
+   * @param {string} text - 待遮罩文本。
+   * @returns {{text: string, replaced: number, distribution: Record<string, number>}} 遮罩结果 + 本次增量。
+   */
+  mask(sessionId, text) {
+    return this.stripperFor(sessionId).stripInto(text)
+  }
+
+  /**
+   * 会话累计统计（审计用，绝不含原文）。
+   * @param {string} sessionId - 会话 id。
+   * @returns {{replaced: number, distribution: Record<string, number>}} 统计。
+   */
+  stats(sessionId) {
+    return this.stripperFor(sessionId).stats()
+  }
+
+  /**
+   * 还原一段文本中的占位符；内存未命中且 persist 开启时从领域回载。
+   * @param {string} sessionId - 会话 id。
+   * @param {string} text - 含占位符文本。
+   * @returns {Promise<string>} 还原后的文本。
+   */
+  async restore(sessionId, text) {
+    let stripper = this.strippers.get(sessionId)
+    if (stripper === undefined && this.persistEnabled && this.domainPromise !== null) {
+      stripper = await this._load(sessionId)
+    }
+    if (stripper === undefined) return text
+    return stripper.restore(text)
+  }
+
+  /**
+   * 持久化会话映射到 storageDomain（尽力而为；失败仅上报，绝不阻断遮罩）。
+   * @param {string} sessionId - 会话 id。
+   * @returns {Promise<void>}
+   */
+  async persist(sessionId) {
+    if (!this.persistEnabled || this.domainPromise === null) return
+    const stripper = this.strippers.get(sessionId)
+    if (stripper === undefined) return
+    try {
+      const domain = await this.domainPromise
+      const table = domain.table(RESTORE_TABLE)
+      await table.put(sessionId, { sessionId, entries: stripper.mapping(), updatedAt: Date.now() })
+    } catch (error) {
+      this.onError(registryUnavailable(error instanceof Error ? error.message : String(error)))
+    }
+  }
+
+  /**
+   * 从领域回载会话映射。
+   * @param {string} sessionId - 会话 id。
+   * @returns {Promise<import('./strip.mjs').Stripper|undefined>} 脱敏器或 undefined。
+   */
+  async _load(sessionId) {
+    try {
+      const domain = await this.domainPromise
+      const record = await domain.table(RESTORE_TABLE).get(sessionId)
+      if (record === undefined || record.entries === undefined) return undefined
+      const stripper = createStripper({ entities: this.entities, maxEntries: this.maxEntries })
+      stripper.loadMapping(record.entries)
+      this.strippers.set(sessionId, stripper)
+      this._pruneSessions()
+      return stripper
+    } catch (error) {
+      this.onError(registryUnavailable(error instanceof Error ? error.message : String(error)))
+      return undefined
+    }
+  }
+
+  /** 会话数超限时逐出最久未用（映射仍在领域，restore 按需回载）。 */
+  _pruneSessions() {
+    while (this.strippers.size > this.maxSessions) {
+      const oldest = this.strippers.keys().next().value
+      this.strippers.delete(oldest)
+    }
+  }
+}

package/lib/strip.mjs

@@ -0,0 +1,255 @@
+// lib/strip.mjs — PII 脱敏/还原纯函数（零依赖）。
+//
+// 移植自上游 Pii-Stripper-Middleware 的 core.py（发送前匿名化 + 返回后恢复），
+// 逐条对齐：正则检测、重叠消解（同起点取高分、区间不重叠）、相同原文复用同一
+// 占位符、还原按占位符长度降序。新增：KEY（密钥）检测器（规格要求的"密钥"）、
+// 每会话累计计数与类型分布（审计用，绝不含明文）、有界逐出（maxEntries）。
+// 函数绝不访问 I/O；输入非字符串时保守转字符串。
+
+import { ENTITY_LABELS, LIMITS } from './constants.mjs'
+
+/**
+ * 内置正则检测器（实体 -> 多条 pattern，各自带置信度）。
+ * 与上游 REGEX_PATTERNS + 中文自定义识别器对齐，新增 key（密钥）检测器。
+ * 每条 pattern 都以 g 标志编译（供 matchAll 遍历）。
+ */
+export const BUILTIN_PATTERNS = Object.freeze([
+  { entity: 'phone', source: /(?<!\d)1[3-9]\d{9}(?!\d)/gu, score: 0.95 },
+  { entity: 'id-card', source: /(?<!\d)\d{17}[\dXx](?!\d)/gu, score: 0.92 },
+  { entity: 'email', source: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/gu, score: 0.9 },
+  { entity: 'bank-card', source: /(?<!\d)\d{16,19}(?!\d)/gu, score: 0.65 },
+  { entity: 'ip', source: /\b(?:\d{1,3}\.){3}\d{1,3}\b/gu, score: 0.85 },
+  { entity: 'key', source: /sk-[A-Za-z0-9_-]{16,}/gu, score: 0.95 },
+  { entity: 'key', source: /gh[pousr]_[A-Za-z0-9]{16,}/gu, score: 0.95 },
+  { entity: 'key', source: /xox[baprs]-[A-Za-z0-9-]{10,}/gu, score: 0.9 },
+  { entity: 'key', source: /AKIA[0-9A-Z]{16}/gu, score: 0.9 },
+  { entity: 'key', source: /Bearer[ \t]+[A-Za-z0-9._~+/=-]{8,}/gu, score: 0.9 },
+])
+
+/**
+ * 检测到的一个 PII 实体片段。
+ * @typedef {{text: string, entity: string, label: string, start: number, end: number, score: number}} PIIEntity
+ */
+
+/**
+ * PII 脱敏器：把 PII 替换为 `<LABEL_N>` 占位符，并能按映射还原。
+ *
+ * 同一会话内跨请求累计（stripInto 不重置），保证同一原文始终复用同一占位符，
+ * 使模型在整段历史里看到的占位符语义一致；strip() 是单次模式（每次重置），
+ * 供 mask_test 这类"试跑一段文本"的独立场景使用。
+ */
+export class Stripper {
+  /**
+   * @param {object} options - {patterns: Array<{entity: string, source: RegExp, score: number}>, maxEntries?: number}。
+   */
+  constructor(options) {
+    this.patterns = options.patterns
+    this.maxEntries = options.maxEntries ?? LIMITS.MAX_RESTORE_ENTRIES
+    this.reset()
+  }
+
+  /** 清空占位符计数、映射与统计（每次单次 strip 前调用）。 */
+  reset() {
+    /** @type {Map<string, number>} 标签 -> 已生成占位符数（单调递增，保证跨请求唯一）。 */
+    this.counter = new Map()
+    /** @type {Map<string, string>} 占位符 -> 原文（还原用）。 */
+    this.placeholderMap = new Map()
+    /** @type {Map<string, string>} 原文 -> 占位符（相同原文复用）。 */
+    this.valueMap = new Map()
+    this.totalReplaced = 0
+    /** @type {Map<string, number>} 标签 -> 累计替换次数（审计分布）。 */
+    this.distribution = new Map()
+  }
+
+  /**
+   * 单次脱敏：先重置再替换，返回脱敏文本（上游 strip 语义）。
+   * @param {unknown} text - 待脱敏文本（非字符串保守转字符串）。
+   * @returns {string} 脱敏后的文本。
+   */
+  strip(text) {
+    this.reset()
+    return this._apply(text)
+  }
+
+  /**
+   * 累计脱敏：不重置，返回本次替换的增量统计。
+   * @param {unknown} text - 待脱敏文本（非字符串保守转字符串）。
+   * @returns {{text: string, replaced: number, distribution: Record<string, number>}} 脱敏文本 + 本次增量。
+   */
+  stripInto(text) {
+    const startReplaced = this.totalReplaced
+    const startDist = new Map(this.distribution)
+    const out = this._apply(text)
+    const replaced = this.totalReplaced - startReplaced
+    const distribution = /** @type {Record<string, number>} */ ({})
+    for (const [label, count] of this.distribution) {
+      const before = startDist.get(label) ?? 0
+      if (count > before) distribution[label] = count - before
+    }
+    return { text: out, replaced, distribution }
+  }
+
+  /**
+   * 把脱敏文本中的占位符还原为原文（按占位符长度降序，避免短占位符提前匹配）。
+   * @param {string} text - 含占位符的文本。
+   * @returns {string} 还原后的文本。
+   */
+  restore(text) {
+    if (typeof text !== 'string') return String(text)
+    let result = text
+    const entries = [...this.placeholderMap.entries()].sort((a, b) => b[0].length - a[0].length)
+    for (const [placeholder, original] of entries) {
+      result = result.split(placeholder).join(original)
+    }
+    return result
+  }
+
+  /** @returns {Record<string, string>} {占位符: 原文} 只读副本。 */
+  mapping() {
+    return Object.fromEntries(this.placeholderMap)
+  }
+
+  /**
+   * 从持久化的 {占位符: 原文} 映射回载（恢复表跨重启还原）。
+   * 回载后重建各标签计数，保证后续新占位符编号继续单调不冲突。
+   * 累计统计（totalReplaced/distribution）属于进程内遥测，不回载。
+   * @param {Record<string, string>} entries - 占位符到原文的映射。
+   */
+  loadMapping(entries) {
+    for (const [placeholder, original] of Object.entries(entries ?? {})) {
+      this.placeholderMap.set(placeholder, original)
+      this.valueMap.set(original, placeholder)
+      const match = /^<([A-Z_]+)_(\d+)>$/u.exec(placeholder)
+      if (match !== null) {
+        const label = match[1]
+        const number = Number(match[2])
+        const current = this.counter.get(label) ?? 0
+        if (number > current) this.counter.set(label, number)
+      }
+    }
+  }
+
+  /**
+   * 累计统计（审计用）：替换总数 + 类型分布。绝不含原文与映射。
+   * @returns {{replaced: number, distribution: Record<string, number>}} 统计。
+   */
+  stats() {
+    return { replaced: this.totalReplaced, distribution: Object.fromEntries(this.distribution) }
+  }
+
+  /**
+   * 检测 + 重叠消解 + 替换，返回脱敏文本（核心管道）。
+   * @param {unknown} input - 任意文本（非字符串保守转字符串）。
+   * @returns {string} 脱敏文本。
+   */
+  _apply(input) {
+    const text = typeof input === 'string' ? input : String(input)
+    if (text.length === 0 || text.length > LIMITS.MAX_TEXT_LENGTH) return text
+    const entities = this._detect(text)
+    const resolved = this._resolveOverlaps(entities)
+    return this._applyReplacements(text, resolved)
+  }
+
+  /**
+   * 正则检测全部实体。
+   * @param {string} text - 文本。
+   * @returns {PIIEntity[]} 实体列表。
+   */
+  _detect(text) {
+    /** @type {PIIEntity[]} */
+    const entities = []
+    for (const pattern of this.patterns) {
+      for (const match of text.matchAll(pattern.source)) {
+        entities.push({
+          text: match[0],
+          entity: pattern.entity,
+          label: ENTITY_LABELS[pattern.entity] ?? pattern.entity,
+          start: match.index,
+          end: match.index + match[0].length,
+          score: pattern.score,
+        })
+      }
+    }
+    return entities
+  }
+
+  /**
+   * 重叠消解：按起点升序、同起点按置信度降序；与已选实体重叠者丢弃
+   * （上游先到先得 + 同位置取高分语义）。
+   * @param {PIIEntity[]} entities - 未消解实体。
+   * @returns {PIIEntity[]} 消解后实体。
+   */
+  _resolveOverlaps(entities) {
+    if (entities.length === 0) return []
+    const sorted = [...entities].sort((a, b) => a.start - b.start || b.score - a.score)
+    const result = []
+    let lastEnd = -1
+    for (const entity of sorted) {
+      if (entity.start >= lastEnd) {
+        result.push(entity)
+        lastEnd = entity.end
+      }
+    }
+    return result
+  }
+
+  /**
+   * 逐实体替换为占位符（相同原文复用同一占位符），并累计统计。
+   * @param {string} text - 原文。
+   * @param {PIIEntity[]} entities - 已消解实体（按起点升序）。
+   * @returns {string} 脱敏文本。
+   */
+  _applyReplacements(text, entities) {
+    const parts = []
+    let lastEnd = 0
+    for (const entity of [...entities].sort((a, b) => a.start - b.start)) {
+      parts.push(text.slice(lastEnd, entity.start))
+      const original = entity.text
+      let placeholder = this.valueMap.get(original)
+      if (placeholder === undefined) {
+        placeholder = this._makePlaceholder(entity.label)
+        this.placeholderMap.set(placeholder, original)
+        this.valueMap.set(original, placeholder)
+      }
+      parts.push(placeholder)
+      lastEnd = entity.end
+      this.totalReplaced += 1
+      this.distribution.set(entity.label, (this.distribution.get(entity.label) ?? 0) + 1)
+    }
+    parts.push(text.slice(lastEnd))
+    this._prune()
+    return parts.join('')
+  }
+
+  /**
+   * 生成唯一占位符 `<LABEL_N>`；计数单调递增，跨请求不重复。
+   * @param {string} label - 实体标签。
+   * @returns {string} 占位符。
+   */
+  _makePlaceholder(label) {
+    const count = (this.counter.get(label) ?? 0) + 1
+    this.counter.set(label, count)
+    return `<${label}_${count}>`
+  }
+
+  /** 超过 maxEntries 时逐出最旧映射（计数仍单调，还原旧占位符会失效，可预期）。 */
+  _prune() {
+    while (this.placeholderMap.size > this.maxEntries) {
+      const oldest = this.placeholderMap.keys().next().value
+      const original = this.placeholderMap.get(oldest)
+      this.placeholderMap.delete(oldest)
+      if (original !== undefined) this.valueMap.delete(original)
+    }
+  }
+}
+
+/**
+ * 按启用的实体集创建脱敏器。
+ * @param {object} [options] - {entities?: string[], maxEntries?: number}。
+ * @returns {Stripper} 配置好的脱敏器。
+ */
+export function createStripper(options = {}) {
+  const enabled = new Set(options.entities ?? Object.keys(ENTITY_LABELS))
+  const patterns = BUILTIN_PATTERNS.filter(pattern => enabled.has(pattern.entity))
+  return new Stripper({ patterns, maxEntries: options.maxEntries })
+}

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "dsh-mask",
+  "description": "PII masking middleware for DeepSeek Harness: anonymize names, phones, emails, ID cards, bank cards, keys, and addresses to placeholders before they reach the model, restore them at the display layer, keep the restore table only in memory and a controlled storage domain, never log plaintext, and expose /mask and the mask_test tool",
+  "version": "0.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-mask.git"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-mask#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-mask/issues"
+  },
+  "author": "PerryLink",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "types.d.ts",
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "filesystem:read",
+      "storage-domain:read",
+      "storage-domain:write",
+      "session-log:read",
+      "credentials:none",
+      "network:none"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.0-rc.6"
+      ]
+    },
+    "capability": {
+      "id": "mask",
+      "kind": "command",
+      "invocation": "/mask status",
+      "expected": "the /mask command is registered on the commands service: status reports masked counts and type distribution, on/off toggles masking at runtime, restore <text> unmaps placeholders back to the values stored for this session; mask_test tool masks a snippet and reports the placeholder result"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-json": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.0"
+  },
+  "dependencies": {
+    "typescript": "^5.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@types/node": "^22.19.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.check.json",
+    "typecheck:ci": "tsc -p tsconfig.check.json",
+    "test": "node --test \"test/*.test.mjs\"",
+    "coverage": "node --test --experimental-test-coverage \"test/*.test.mjs\"",
+    "verify:self-contained": "node scripts/verify-self-contained.mjs",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "check:readmes": "node scripts/verify-readmes.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "cordis",
+    "pii",
+    "mask",
+    "privacy",
+    "anonymization",
+    "security"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}

package/types.d.ts

@@ -0,0 +1,47 @@
+// types.d.ts — dsh-mask 类型契约（会话事件声明合并 + 配置类型）。
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * 一次请求前脱敏的审计记录（log-only）：只记"替换了多少处 + 类型分布"，
+     * 绝不携带 PII 原文或占位符映射。注意：当前宿主构建（KNOWN_SESSION_EVENT_TYPES）
+     * 尚未收录 mask/*，运行时经自适应门跳过 append；宿主收录后自动开启
+     * （见 README「会话事件」）。
+     */
+    'mask/applied': {
+      sessionId: string
+      replaced: number
+      distribution: Record<string, number>
+    }
+  }
+}
+
+export interface Config {
+  /** 总开关；false 时命令、工具与 pre-step 监听器全部卸载。 */
+  enabled?: boolean
+  /** 检测模式；只有 'regex' 实现，'regex+ner'（姓名/地址识别）预留并响亮失败。 */
+  mode?: 'regex' | 'regex+ner'
+  /** 启用的实体类型；regex 集为 phone/email/id-card/bank-card/key/ip，person/address 需 NER。 */
+  entities?: string[]
+  /** 遮罩作用域；只有 'messages'（agent/pre-step 消息）实现，'tools' 预留并响亮失败。 */
+  scope?: 'messages' | 'tools'
+  /** 注册 /mask 命令（默认 true）。 */
+  registerCommand?: boolean
+  /** tools 服务存在时注册 mask_test 工具（默认 true）。 */
+  registerTools?: boolean
+  /** 恢复表持久化到受控 storageDomain（false = 仅内存，重启丢失）。 */
+  persistRestoreTable?: boolean
+  /** 每会话恢复条目上限（超出逐出最旧）。 */
+  maxRestoreEntriesPerSession?: number
+  /** 内存会话脱敏器上限（LRU 逐出，映射按需从领域回载）。 */
+  maxSessions?: number
+}
+
+/** mask_test 工具规范结果。 */
+export interface MaskTestValue {
+  ok: boolean
+  masked: string
+  replaced: number
+  distribution: { label: string; count: number }[]
+  error?: string
+}