dsh-llmasking：DeepSeek Harness 传输层数据脱敏插件

DeepSeek Harness (DSH) 的插件生态强调模块化。在开发涉及敏感信息的智能体时，会话日志、终端 UI 和工具执行通常保留真实值，而真实数据一旦发出网络请求，即存在泄露风险。dsh-llmasking 旨在解决这个问题：它在数据离开进程之前对其进行脱敏，确保模型只能看到占位符，而会话日志、UI 和工具执行看到的仍是实时还原的真实值。

插件简介¶

名称: yolorouter/dsh-llmasking
类别: admin-security
许可: MIT
维护者: yolorouter

该插件运行在 DSH 的 llm/stream 水平面。它会拦截每一次模型调用，构建一个不可变的脱敏副本发送给模型；同时包装响应流，将占位符在流中实时还原回真实值。这实现了“日志保留真相，传输携带掩码”的安全模型。

安装与启用¶

安装前请确保环境满足要求：Node >= 22，DSH >= 0.1.0-rc.6（最后验证日期 2026-08-16）。

安装插件：

    dsh plugin --profile my add dsh-llmasking

启动 Harness：

    dsh --profile my

验证插件状态：

    dsh --profile my --dump-config | grep -A1 "id: llmasking"

或者在 Web UI 的设置中检查插件状态，应为 **active**。

核心功能¶

传输层脱敏：敏感值仅在从 DSH 进程到模型提供商的传输过程中被掩码，绝不离开进程。
通用检测器：支持邮箱、银行卡（含 Luhn 校验）、IP、URL、国际电话、密钥家族（云密钥/PEM/JWT/Git Token/高熵密码）。
区域规则：
- CN：手机号、ISO 7064 校验的身份证号、固定电话。
- US：SSN、电话。
自定义关键词：支持添加额外的字面量关键词进行脱敏。
会话一致性：同一个值在当前会话中始终映射为同一个占位符。
单向删除：脱敏后的占位符（如 [SECRET_1]）无法逆向映射回原始值。
流处理：拦截 llm/stream 水平面的每一次调用，处理占位符跨 SSE 边界被分割的情况（在块结束处 flush 并拼接）。
零开销透传：对于不含敏感数据的请求，走零开销 passthrough 路径。
失败安全：
- 掩码失败：拒绝发送请求（Fail Closed）。
- 恢复失败：在日志中发出警告后放行（Fail Open）。

配置¶

默认配置已足够，通常无需修改。配置通过 cordis.patch.yml 进行，采用行替换而非深度合并。

- replace:
    - id: llmasking
      config:
        keywords: ["acme-corp-token"]
        regions: ["CN", "US"]
        maskSystem: true
        teachModel: true

配置项说明：
* mode (默认 enforce)：enforce 强制掩码；monitor 为影子模式，仅计数不掩码，用于建立信任。
* keywords (默认 [])：额外需要掩码的关键词。
* regions (默认 all)：启用的地理规则包（如 CN, US）。
* maskSystem (默认 true)：是否掩码系统提示词槽位。
* teachModel (默认 true)：是否在系统提示词中添加占位符说明，要求模型逐字复现。

使用与监控¶

Slash 命令¶

/llmasking：查看当前会话的脱敏状态、模式、检测器配置及统计信息。
/llmasking verify：本地运行哨兵值通过真实的脱敏管道，显示 原始值 -> 占位符 的结果，用于验证管道是否生效。
/llmasking status：同 /llmasking。

日志记录¶

每次掩码操作会在 DSH 日志中写入一条收据行（仅记录数量和类型，不记录具体值）：

llmasking: 3 value(s) masked on the wire this turn (PHONE, EMAIL, SECRET)

权限与数据¶

文件访问：无。插件不读写用户文件，仅读取自身包清单以获取版本号。
网络调用：无。插件不调用任何端点、遥测或第三方服务，仅转换 DSH 已发出的请求。
凭证访问：无。API 密钥通过适配器头部传输，插件位于适配器上方，无法接触到密钥材料。

生态背景¶

DeepSeek Harness 的理念是“一切皆插件”。dsh-llmasking 作为社区维护的插件，遵循 MIT 许可证，可在其 GitHub 仓库查看源码与目录：https://github.com/yolorouter/dsh-llmasking