OmniProxy 手册

设置发送前文本脱敏

在将文本发送给指定的外部云端服务（远程模型、网络搜索或远程 MCP 服务）之前，脱敏模块可以根据预设规则识别并替换其中的敏感信息（如邮箱、电话等）。

首次配置前的建议：

先用虚构数据验证：任何规则引擎和本地复核模型都可能存在漏检（未识别出敏感词）或误判（把正常业务词替换掉）的情况。首次配置或修改规则后，建议使用类似 demo@example.com 的虚构数据进行测试，避免直接使用真实的客户名单或机密文本试错。
仅限可解析文本：本模块仅处理受支持请求中的结构化文本字段，不会对图片、音频、视频等二进制媒体文件自动施加同等保护；监控台调用记录、界面截图和导出文件在对外分享前仍需人工检查。

1. 为指定外部来源开启脱敏策略

OmniProxy 不提供“一键覆盖所有已有及未来来源”的全局总开关，你必须为每个需要保护的外部来源单独开启策略：

先在远程模型、网络搜索或MCP 服务中添加并验证好你的外部来源。
打开左侧导航栏的脱敏，在按来源发送前脱敏列表中找到目标来源。
打开该来源行的发送前脱敏开关，确认配置已保存。
检查同行的允许请求跳过脱敏开关：除非你的调用端确有显式传参跳过某次脱敏的特殊需求，否则请保持此项关闭（开启它代表“允许调用方申请跳过脱敏”，并不是“让脱敏变得更严格”；未显式申请跳过的普通请求仍会按该来源的默认策略脱敏）。
当你新增或切换到另一个模型来源、搜索来源或 MCP 连接时，请记得回到此处单独检查并开启它的脱敏开关。

上图为原生 App 的“脱敏”配置界面（当前环境尚未添加外部来源）。为具体来源开启策略后，请先通过下方的本地 JSON 预览测试规则命中情况，再发起真实调用核验；测试输出为空白并不代表“文本中没有敏感信息”。

2. 第一步验证：用本地 JSON 预览测试替换与恢复

脱敏页面下方提供了翻译可逆脱敏 JSON 测试工具。

理解本地预览的性质：虽然界面要求你先在下拉框中选择一个可用来源，但点击运行此 JSON 测试时，系统仅在本机执行占位符替换与还原演练，不会真正向远端云服务发起网络请求。因此，本地预览通过仅证明规则匹配和本机还原逻辑正常，不能单凭预览结果就断定真实外发链路已完全就绪。

在测试区选择刚才开启了脱敏的来源。
从页面自带的示例 JSON 结构开始修改，仅替换其中的 text 字段值（请保持合法的 JSON 格式，不要删掉花括号和引号直接填一句裸文本）。可直接复制以下包含虚构邮箱的测试输入：

{
  "mode": "translation",
  "text": "Contact demo@example.com."
}

点击运行测试，查看右侧输出的处理结果 JSON，重点核对以下字段：

outbound_json：准备发往外部的脱敏后结构（检查其中的 demo@example.com 是否已被替换为临时占位符，确认不再残留明文邮箱；注意不要把 JSON 字符串转义符当成脱敏保护）。
upstream_json：本机模拟回显的上游内容（并非远端模型的真实回答）。
restored_text 与 restore_status：本机将占位符还原回真实值后的文本及恢复状态（正常应为 ok）。
pii_match_count：标准正则规则命中的敏感项数量。
model_review_ran 与 review_incomplete：本地复核模型是否实际运行、复核过程是否完整。

每次修改规则、切换来源或调整允许名单后，都必须重新运行测试；任何报错、空结果或恢复失败都不算测试通过。

3. 第二步验证：在真实翻译调用中核验外发与本机恢复

支持可逆脱敏的外部模型翻译流程，会在每次请求外发前将敏感词替换为本次请求专用的临时占位符；等远端模型返回译文后，网关会校验占位符并在本机将其还原为原始值（如果上游返回的译文弄丢、重复或篡改了占位符，系统会按恢复错误处理，绝不会为了凑出译文而擅自把未脱敏的原文重新发出去补救。注意：普通的模型对话、搜索或 MCP 请求与这套翻译可逆恢复流程并非同一机制，不能混为一谈）。

完成本地 JSON 预览后，请按以下步骤做一次真实的端到端翻译验证：

保持目标远程模型来源的发送前脱敏处于开启状态，并在翻译工作区（或用固定名称映射模型）中将该模型设为翻译引擎。
打开左侧翻译工作区，语言方向设为“英语 → 简体中文”，输入虚构测试句并运行：

Contact demo@example.com.

注意观察译文框：本机恢复成功后，最终译文框中会重新显示出 demo@example.com（本例最终译文为“请联系 demo@example.com。”），因此请结合调用详情核对。
打开模型调用详情核对请求与响应：

检查实际外发的请求正文（Request）：确认其中的原始邮箱已被替换成了临时占位符。
检查上游返回的原始响应（Response）：确认占位符在翻译过程中被原样保留。
检查恢复状态（Restore Status）：确认为 ok 且最终译文准确还原了 demo@example.com。

上图为真实翻译调用返回字段的浏览器阅读视图（非脱敏页本地预览，亦非原生 App 截图）。图中完整保留了带占位符的外发请求、恢复状态 ok 以及还原后的最终中文译文，供你逐项对照核验。

4. 管理标准规则、本地模型复核与允许名单

启停内置标准规则（YAML 覆盖文档）

标准规则由本机引擎高速执行。“默认规则文档”为只读状态，你可以点击下载默认规则文档查阅当前版本支持的所有 rule_id。如果你需要开启或关闭某条内置规则，请通过用户覆盖文档进行配置（注意：覆盖文档仅用于控制已有内置规则的 enabled 启停状态，不支持让你自己编写任意的自定义正则表达式或脚本代码）：

先下载默认规则文档，记下你要调整的 rule_id 及原状态。
在“手工编辑覆盖文档”框中输入如下格式的 YAML 列表并点击应用更改（或者保存为无 BOM 的 UTF-8 .yaml 文件后通过上传覆盖文档导入）：

- rule_id: pii.regex_email
  enabled: true

校验约束：rule_id 必须真实存在于当前默认规则目录中，enabled 只能填布尔值 true 或 false。如果填入未知的 ID 或 YAML 语法有误，导入会被直接拒绝；若自行附加了 pattern 等只读属性，系统会忽略这些额外字段并给出警告，不会因此改写内置的正则匹配逻辑。应用更改后，请务必用虚构输入重跑一次测试；如需恢复原状，将 enabled 改回原值重新应用即可。

可选：启用本地模型复核

除了标准正则规则，你还可以在“复核模型”下拉框中选择一个当前已安装且适合复核任务的本地模型做二次把关：

不选复核模型时，标准规则依然独立工作；启用复核模型后会增加每次外发前的本机处理耗时。
选定过复核模型不代表每次请求都一定成功执行了复核——如果该本地模型离线或推理异常，测试结果中的 model_review_ran 或 review_incomplete 会反映真实状态，请以实际返回提示为准。

管理“允许名单”（白名单）

如果某些固定的非敏感词（如公开的客服邮箱或产品代号）总被规则误伤替换，可以将其加入允许名单：

打开允许名单管理，先输入一个虚构测试词点击添加，确认出现在列表中后重跑 JSON 测试，验证它不再被替换；测试完毕后将其从名单移除，再确认恢复替换效果。
谨慎添加真实值：一旦把某个词加进允许名单，意味着它在后续发往外部来源的请求中都会以明文直接放行，添加前请确认该内容在任何场景下外发均可以公开发送。

5. 脱敏功能的明确边界总结

为避免产生错误的安全感，请牢记以下五条边界：

不保证 100% 识别：无论是正则规则还是本地模型复核，都无法承诺拦截自然语言中所有变形或隐晦的敏感信息。
来源之间互不继承：为远程模型 A 开启了脱敏，不会自动保护远程模型 B，也不会覆盖网络搜索来源或 MCP 服务。
不保护二进制媒体：图片、语音、视频文件及未经解析的二进制流不受本页文本脱敏规则保护。
MCP 脱敏仅限部分请求参数：MCP 连接需单独开启脱敏，且仅替换受支持请求中的业务文本参数，不处理返回结果、不做可逆恢复（详见接入远程 MCP 工具服务）。
系统凭据掩码 ≠ 业务原文脱敏：OmniProxy 在常规运行日志中会自动隐藏 API Key 等认证凭据，但这不代表日志里的业务提问原文也是脱敏的；分享任何日志或报告前，仍需人工检查并清理业务文本。