Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Agent Note: 网关推理正文的可逆隐私脱敏

Status: implemented

## Problem

Agent 发给模型的上下文可能包含工具读到的密钥、令牌和个人信息。已有指纹脱敏负责改写客户端特征,不保留逆向映射,不能在模型复述被遮盖的工具参数时还原原值。见 [Issue #634](https://github.com/aimod-cc/Agent2API/issues/634);界面术语参考 [magpie 的本地脱敏文档](https://usemagpie.ai/docs/zh/masking)。

## Decision

默认不改变网关行为。管理员在「设置 → 安全 → 本地隐私脱敏」分别启用凭据、个人信息分类与自定义词;管理面用受鉴权保护的 `GET/PUT /api/privacy-masking` 热更新整份设置。设置写入本机数据库,不参加云同步。失败时保留先前配置。GET 在同一快照中返回设置及内容 revision,PUT 必须携带该 revision 并在既有配置更新锁内比较后写入;旧页面保存返回 409,不覆盖其他页面刚启用的保护。revision 不写入配置正文,也不扩展云同步范围。保存提示在草稿修改后清除,刷新经既有应用确认框确认才丢弃草稿,冲突时保留编辑内容。

脱敏位于三个外部推理端点的鉴权、容量限制之后,以及任何提供商选路、协议翻译、重试和正文观测之前。只访问对应协议已知的文本、工具参数、描述和工具结果。工具描述包括命名空间子工具及 `additional_tools`、`tool_search_output` 中的声明;沿已知声明结构递归,只改写说明性文本,不改工具名、枚举、必填字段或自定义语法。工具参数与结果中的 JSON 文档按值识别凭据键名,保留变量引用、过期时间和编码附件。其他协议字段不会因键名被当作秘密改写;跟踪 ID、鉴权、签名推理和附件不重写。对同一请求同一原值复用随机占位符;响应层在原有记录与协议翻译之后用该请求的内存映射还原,不在日志或库中持久化映射。SSE 分片按选择、内容块和工具调用独立关联,保留事件顺序与协议结束帧。完整结构化输出只解析并还原助手 JSON 正文,实际未发生替换时保留原字节;截断、围栏或不支持该模式的正文保留上游结果并按 JSON 字符串片段还原,不因格式不完整替换为网关错误。流式正文同样按 JSON 字符串片段转义;推理、拒绝说明、指令和工具描述继续按普通文本还原。输出模式在入站首次确定,后续协议翻译或续写不重置。MCP 审批参数、参数增量和完成事件复用同一遍历,标识符不改写。SSE 行边界统一支持 CRLF、LF 和单独 CR,仅流首识别 BOM;真实回环发现原生上游接收层先于包装层丢弃单独 CR 事件,因此该层同步采用字节行边界,保留签名/未知字段及原始换行,跨传输块的 CR 等下一个字节或 EOF 再判;等待帧数或字节数达到上限且仍有待拼接占位符时显式报错,EOF 的自然未完文本仍保留。去重使用入站原始字节摘要;入口及普通 / 原生发送体在合并网关提示词后复用同一映射,包括流式自动续写。Responses 信封回显的 instructions 和 tools 同样按白名单还原;JSON 字符串标量先解码再遮盖,数字、布尔及 null 的文本仍扫描原始表示,防止转义绕过或非字符串值漏判。重复遮盖在计数前排除已拥有占位符,仅新增明文消耗预算。含 `previous_response_id` 或 `conversation` 的 Responses 请求在开启时明确报错,客户端可随请求重发完整 `input`,而不是为还原旧占位符保存跨请求的原值。

内置检测移植自 [固定版本的 Magpie 规则表](https://github.com/yetone/magpie/tree/d847b79690cb12951ceefbb53f51993abac76b43/internal/redact)(MIT,许可见 `licenses/magpie-MIT`):58 个确定性识别器包含凭据、钱包格式、校验位和个人信息的上下文排除。保留 UUID 或摘要中的误匹配、游标与工具元素标识,但真实凭据字段和明确配置的自定义词/规则仍可遮盖同形值。基础个人信息与普通附加类别跟随主开关,主目录用户名、登录名/主机名、公网 IP、云存储桶需另行开启。支持整词、大小写选项、日期变体、前缀或正则和精确白名单。对明确的凭据赋值不要求字母数字混合,并整体遮盖含冒号的值;示例域名只按整域或子域匹配,助记词按每段连续词完整遮盖。数字数组区间只从完整合法的 JSON 文档提取,并跳过 JSON 字符串;普通文字中方括号里的个人号码仍遮盖。每段文本只解析和索引一次,候选通过有序区间查询避免二次前缀扫描。修复范围后的扫描从实际消费位置继续,银行卡只在分组边界尝试有效前缀,不截断连续数字。自定义正则只排除零宽命中,不以四字节下限忽略管理员已保存的短规则。Rust 实现不运行外部模型或进程,不迁移 Magpie 的跨请求缓存、模型辅助识别及路由策略。

辅助识图子调用继承请求级映射,但用量、取消状态和关联 id 独立;启用脱敏的请求绕过跨请求识图缓存,避免缓存依赖旧映射的结果。内容敏感的标题/压缩分类在公共入口对原文计算,只将分类结果交给 handler,日志和发送链仍使用遮盖后的正文。真实保存发现标题规则写入后缺少运行期快照刷新,因此公共配置变更链同时刷新该快照,使首次保存即可在原文分类时生效,revision 也与盘面同步。标题识别入口把既有行为分类的显示名映射为配置 ID,避免 `Claude Code` 与 `claude-code` 的跨模块契约错位;未知分类不扩大识别。已启动尝试的发送体构造错误由统一帮助函数先定稿状态及原因,再沿原错误返回;未启动的校验路径不调用它。

## Alternatives considered

- 复用现有指纹词表:最少新增界面和数据,但该词表按提供商决定是否改写、可能删除文本,也没有反向映射,与隐私防护的语义不同。
- 分别在各提供商出站实现:能看到最终协议的每个字段,但覆盖容易随新提供商与重试分叉,也会让未遮盖的入站正文进入现有调试记录。用网关入口及对应出口统一处理,不改变各家鉴权。
- 只在识图结果包含可见占位符时跳过缓存:可保留更多缓存命中,但结果可能依赖仍在请求内扩展的映射或拼接后文本;启用时统一绕过读写,以额外识图调用换取请求隔离。
- 仅按方括号字符集合排除数字:扫描快,也无需解析,但会把普通文字中的联系方式误当 JSON;选择先验证完整文档再索引,增加一次线性语法校验以保留正确的个人信息保护。
- 跨请求维护映射以提升前缀缓存命中:会扩大敏感值的驻留时间和跨请求关联。首版每请求独立随机,牺牲请求间占位符一致性。

## Consequences

这是规则型文本保护,不是文件扫描、远端会话清理或全量数据防泄漏。面板内部助手/管理请求、图片附件、签名或加密块、协议标识不经此变换;开启时独立图像推理端点返回明确错误。被改写的正文需要解析并重新序列化,长请求和响应还原有上限。SSE 遇到可能未完的占位符会在有界队列里等后续分片;截断、改写过的占位符不保证还原。正常回传到客户端的内容会包含原值,对客户端处理与日志仍应按真实数据看待。

## Testing

`node scripts/test-privacy-masking.mjs <agent2api-server>` 启动独立网关和回环上游,验证三种协议的 JSON/SSE 文本和工具参数、未开启时的原样路径、出站鉴权不变、错误与请求隔离。纯 Rust 测试验证规则表、代表性正反例、校验位、SSE 出错后的轮询及请求级映射。集成脚本检验追加提示词、原始正文去重、历史请求拦截、高级规则出站、多语言数字密钥与计量值的区分,三种协议的 JSON 工具结果、标识符保留与 Responses 嵌套工具声明,另有关闭脱敏后让出站断言失败的负向控制。复审补充的八组出站用例在旧构建逐项失败,再验证修订后通过;覆盖纯字母/数字密码、完整冒号值、示例域名边界、file_password、同一匹配的多段助记词、三协议 JSON 标量、40,000 次词项及 Responses 信封回显。大输入用例核对真实上游接收到 40,000 个正确占位符及新增网关提示词,并以短响应隔离与匹配预算无关的大响应开销。界面明确将 Luhn 识别范围称为银行卡号,而不泛称银行账号,基础手机号明确限定中国大陆。新增回归覆盖转义 Unicode 的字符串标量、携带同一 revision 的并发保存,以及真实双页面的陈旧草稿写入冲突;取消刷新保留三个草稿区域,确认后才载入最新设置,编辑后不再显示旧的保存成功提示。 三协议 JSON 输出的引号、反斜杠与换行保持可解析,MCP 审批历史及交错调用的 delta/done 分别核对;相邻 IBAN 包含正则确实会吞入后续账号的原分组样例,而不只覆盖两位末组或未分组样例;原生 CR 从实际回环上游返回并保留签名,流等待达到上限的真实连接以错误结束。辅助识图用分块文本拼接后命中词项,连续两次请求各自还原且不复用旧缓存;大网关注入提示词引发遮盖失败时,报表里的实际尝试包含 503 和原因。Windows 调试网关夹具为既有深层辅助调用设置 16 MiB 线程栈,生产配置不变。 方括号个人号码、非完整 JSON 模式正文与无映射 JSON 的保真回归在已发布构建先实际失败;完整 SSE 序列包含结束事件,真实回环按空行派发并合并多行 data,缺失分隔符的负向输入明确报错。MCP 还原断言同时核对上游只有占位符,流错误断言排除客户端 deadline,故意挂起上游只触发客户端超时的负向模式必须失败。
34 changes: 34 additions & 0 deletions desktop-tauri/i18n/i18n-src/en/settings.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,38 @@
{
"刷新将丢弃尚未保存的本地隐私脱敏修改,是否继续?": "Refreshing will discard your unsaved local privacy masking changes. Continue?",
"本地隐私脱敏设置已在其他位置修改,请刷新后再保存;当前草稿未丢失": "Local privacy masking settings changed elsewhere. Refresh before saving again; your draft has been kept.",
"自定义脱敏规则必须是 JSON 数组": "Custom masking rules must be a JSON array",
"美国社会安全号码(SSN)": "US Social Security number (SSN)",
"护照号": "Passport number",
"IBAN": "IBAN",
"生日": "Date of birth",
"MAC 地址": "MAC address",
"序列号": "Serial number",
"主目录用户名": "Home directory username",
"登录用户名和主机名": "Login username and hostname",
"公网 IP": "Public IP address",
"云存储桶": "Cloud storage bucket",
"遮盖邮箱、中国大陆手机号、身份证号和银行卡号": "Mask email, mainland China mobile numbers, national ID and bank card numbers",
"附加个人信息分类": "Additional personal-data categories",
"自定义脱敏词(每行一个)": "Custom masking terms (one per line)",
"高级脱敏规则": "Advanced masking rules",
"自定义词忽略大小写": "Ignore letter case for custom terms",
"自定义词只匹配整词": "Match custom terms as whole words",
"原样放行的值(每行一个)": "Values to leave unchanged (one per line)",
"前缀或正则规则(开启凭据脱敏时生效)": "Prefix or regex rules (when credential masking is on)",
"每条规则填 prefix 或 regex,正则有捕获组时只遮盖第一组。自定义词支持同一天的日期变体。": "Set prefix or regex for each rule. With capture groups, only group 1 is masked. Custom terms recognize alternate spellings of the same date.",
"本地隐私脱敏": "Local privacy masking",
"服务端未返回本地隐私脱敏设置": "The server did not return privacy masking settings",
"本地隐私脱敏设置格式无效": "Invalid privacy masking settings",
"当前后端暂不支持本地隐私脱敏": "This backend does not support local privacy masking",
"自定义脱敏词最多 100 个,每个不超过 256 字节": "Use up to 100 custom terms of at most 256 bytes each",
"设置已保存:从下一个推理请求生效": "Saved. Applies from the next inference request.",
"正在读取设置…": "Loading settings…",
"默认关闭。仅保护经此网关的 Chat Completions、Responses 和 Messages,返回给客户端的文本和工具参数会还原。": "Off by default. Protects Chat Completions, Responses and Messages through this gateway. Text and tool arguments are restored for the client.",
"遮盖 API Key、Token、密码和已识别的私钥": "Mask API keys, tokens, passwords and recognizable private keys",
"遮盖邮箱和中国大陆手机号": "Mask email addresses and mainland China mobile numbers",
"自定义脱敏词(每行一个,精确区分大小写)": "Custom terms (one per line; exact, case-sensitive matches)",
"原值与占位符的映射只在本次请求内存中保留。附件、签名内容和面板内置助手不受此设置保护;启用时网关独立生图请求会报错。规则可能漏判,请用测试数据验证。": "Mappings live only in memory for this request. Attachments, signed content and the panel assistant are not covered. Standalone gateway image-generation requests fail when masking is enabled. Rules can miss data; test with sample values.",
"界面渲染": "Interface rendering",
"硬件加速": "Hardware acceleration",
"未能读取硬件加速设置": "Could not read hardware acceleration settings",
Expand Down
34 changes: 34 additions & 0 deletions desktop-tauri/i18n/i18n-src/ja/settings.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,38 @@
{
"刷新将丢弃尚未保存的本地隐私脱敏修改,是否继续?": "更新すると未保存のローカルプライバシー設定が破棄されます。続行しますか?",
"本地隐私脱敏设置已在其他位置修改,请刷新后再保存;当前草稿未丢失": "ローカルプライバシー設定が別の場所で変更されました。更新後に保存してください。下書きは保持されています。",
"自定义脱敏规则必须是 JSON 数组": "カスタムルールは JSON 配列で指定してください",
"美国社会安全号码(SSN)": "米国社会保障番号(SSN)",
"护照号": "パスポート番号",
"IBAN": "IBAN",
"生日": "生年月日",
"MAC 地址": "MAC アドレス",
"序列号": "シリアル番号",
"主目录用户名": "ホームディレクトリのユーザー名",
"登录用户名和主机名": "ログインユーザー名とホスト名",
"公网 IP": "グローバル IP アドレス",
"云存储桶": "クラウドストレージのバケット",
"遮盖邮箱、中国大陆手机号、身份证号和银行卡号": "メールアドレス、中国本土の携帯番号、身分証番号、銀行カード番号を隠す",
"附加个人信息分类": "追加の個人情報カテゴリ",
"自定义脱敏词(每行一个)": "カスタム遮蔽語(1 行に 1 語)",
"高级脱敏规则": "高度なマスキングルール",
"自定义词忽略大小写": "カスタム語の大文字・小文字を区別しない",
"自定义词只匹配整词": "カスタム語を単語単位で照合する",
"原样放行的值(每行一个)": "変更しない値(1 行に 1 件)",
"前缀或正则规则(开启凭据脱敏时生效)": "接頭辞または正規表現(認証情報の遮蔽が有効な場合)",
"每条规则填 prefix 或 regex,正则有捕获组时只遮盖第一组。自定义词支持同一天的日期变体。": "各ルールに prefix または regex を指定します。キャプチャグループがある場合は第1グループを隠します。同じ日付の別表記にも対応します。",
"本地隐私脱敏": "ローカルプライバシーマスキング",
"服务端未返回本地隐私脱敏设置": "サーバーからマスキング設定が返されませんでした",
"本地隐私脱敏设置格式无效": "マスキング設定の形式が無効です",
"当前后端暂不支持本地隐私脱敏": "現在のバックエンドはマスキングに対応していません",
"自定义脱敏词最多 100 个,每个不超过 256 字节": "カスタム語は最大100個、それぞれ256バイト以内です",
"设置已保存:从下一个推理请求生效": "保存しました。次の推論リクエストから適用されます。",
"正在读取设置…": "設定を読み込み中…",
"默认关闭。仅保护经此网关的 Chat Completions、Responses 和 Messages,返回给客户端的文本和工具参数会还原。": "既定ではオフです。このゲートウェイを通る Chat Completions、Responses、Messages を保護し、テキストとツール引数をクライアント向けに復元します。",
"遮盖 API Key、Token、密码和已识别的私钥": "API キー、トークン、パスワード、認識可能な秘密鍵を隠す",
"遮盖邮箱和中国大陆手机号": "メールアドレスと中国本土の携帯番号を隠す",
"自定义脱敏词(每行一个,精确区分大小写)": "カスタム語(1行に1個、大文字と小文字を区別して完全一致)",
"原值与占位符的映射只在本次请求内存中保留。附件、签名内容和面板内置助手不受此设置保护;启用时网关独立生图请求会报错。规则可能漏判,请用测试数据验证。": "対応付けはリクエスト中のメモリのみに保持されます。添付ファイル、署名付きコンテンツ、パネルのアシスタントは対象外です。有効時、単独の画像生成はエラーになります。検出漏れがあり得るためサンプルで確認してください。",
"界面渲染": "画面の描画",
"硬件加速": "ハードウェアアクセラレーション",
"未能读取硬件加速设置": "ハードウェアアクセラレーションの設定を読み込めませんでした",
Expand Down
Loading