PII 打码挂哪层:贴工具、贴装配口,还是贴统一出口
模块:运行引擎 · 数据安全(doc/41 §3.2 B 线,规则口径继承 doc/06 §3.3)|状态:已落地(2026-10-23,
fd6a489)|证据:doc/41-任务看板与人工审批.md§3.2、doc/06-工具安全层.md§3.3、internal/runengine/pii.go
1. 场景与病灶
租户 A 的 agent 跑 cat .env。bash 工具今天零守卫(bash.go 明文写着「不做危险命令表」),.env 里的厂商 API Key 原样进 tool_result 帧、进 mh(模型消息表)、进 runlog(历史真源),再被记忆抽取带进 memory_items 长期保存。
多租户已经能区分人和组织,但数据在 agent 工具链里是裸奔的。密钥之外,用户在消息里贴的身份证号、手机号也一路原样喂给模型、抽进记忆——下周一条召回就把它们带回来一次。
旧线 doc/06 做过这件事(7 条密钥正则 + 两个挂载点),但代码随仓体翻篇出仓。本篇要回答的不是「要不要打码」,而是打在哪一层才能不漏——这正是旧方案踩过坑的地方。
2. 三个挂载点与它们的策略
PII 分两类:密钥类(API Key、token、密码——继承 doc/06 的 7 条正则并扩到 AKIA/AIza/hf_/sk- 家族与赋值形式)与证件类(身份证号、手机号、邮箱、银行卡)。
| 挂载点 | 位置 | 策略 | 没它会怎样 |
|---|---|---|---|
| ① 工具返回 | 工具统一出口 wrapToolErrors(tools.go:49)——自家工具 / media / pdf / tool_search / MCP 都走它,成功与错误两路都打码 |
打码后返回(原文不留):模型、mh、runlog、tool_result 帧全部只见过干净文本 | cat .env 的密钥落帧落库,被记忆抽走 |
| ② 模型输入装配 | 模型输入的唯一转换口 toSchemaMessages(midfold.go:373)——首轮 / 折叠 / 救援三条路一次覆盖 |
喂模型前打码:mh/runlog 保留原文(页面要显示用户原话),模型侧只见掩码 | 用户消息里的身份证号被模型复述进终稿、带进记忆 |
| ③ 记忆抽取入库 | memory.go 抽取管线 parseExtraction 之后、入库之前 |
密钥类拒收(整条丢弃);证件类打码后入库 | memory_items 慢慢攒成 PII 库,召回一次带一次 |
①与②策略不同是刻意的:工具输出夹带的密钥没有「用户想在页面上看到原文」的需求,焚掉最干净;用户消息原文要留在 runlog 里给页面回放,所以只在模型出口打码。
3. 候选对比:原方案的两个挂载点为什么不能用
这是本拍唯一真正值得记录的设计翻转——2026-10-23 落地时改的,别照原方案抄:
| 原方案 | 为什么不能用 | 改成的 |
|---|---|---|
| ① 贴真工具内侧(每把工具各包一层) | 只覆盖第一方工具,MCP 工具的结果会漏——MCP 恰是最不可信的一路 | 挂 wrapToolErrors:所有工具结果的唯一必经之路 |
② 挂 prepareInput |
只管首轮;折叠的原料是 mh 原文(user 行按设计存原文给页面显示)→ 折叠一次 PII 就复活(短对话安全、长对话漏,越重要的对话越漏) | 挂 toSchemaMessages:模型输入的唯一转换口,三条路一次覆盖 |
候选总表:
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 提示词劝阻 | 只在抽取提示词里写「不要抽密钥」 | 零代码 | 模型不听话就漏;输出侧根本没管 |
| B 贴真工具内侧 | 每把工具各包一层 | 位置直观 | 漏 MCP;新增工具忘记包就漏 |
| C 挂 prepareInput | 只在装配首轮时打码 | 一个点覆盖所有工具 | 折叠后复活;救援路径也漏 |
| D 三处统一出口(选定) | wrapToolErrors + toSchemaMessages + 记忆写入前 |
每一处都是唯一必经之路,新工具/新折叠路径自动覆盖 | 三处策略不同,要分别讲清「为什么这里这样打」 |
选 D。判断标准只有一条:这个点是不是所有流量都必经。是,就挂这里;不是,就要问「哪条路会绕过去」。
4. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 掩码规则 | 密钥类头尾各 4 位(doc/06 口径);证件类保留可人工核对的头尾、掩掉中段 | 逐条金样钉死;maskSpan / maskKeep 两个函数 |
| 幂等性 | 打码可重复跑,结果不变 | doc/06 就要求;MaskSecrets 去重区间后从后往前替换 |
| 工具输出要不要留原文 | 不留(打码即焚) | 没有「用户想在页面上看到密钥」的需求 |
| 用户消息要不要留原文 | 留(runlog/mh 存原文给页面回放),只在模型出口打码 | 两条代价并存:库里仍有 PII(at-rest 加密不做,见下) |
| 记忆里密钥类怎么办 | 整条拒收,extractStats.Rejected 计数 |
提示词劝阻变成程序拦截 |
| 记忆里证件类怎么办 | 打码后入库 | 记忆要复用;拒收会把可用信息一起扔掉 |
| 用户消息里已经带掩码的怎么办 | MaskPIIKeepUserMasked 保留用户自己打的掩码,不二次打码 |
避免把 *** 再打一遍 |
| 挂载顺序(handler 链) | gate(外)→ journal(中)→ pii(内,贴真工具) |
PII 在 journal 内:打码发生在结果返程上,意图与结果的分工不被打乱 |
| 旧线「就地改 state 写穿回历史」怎么处理 | v6 不用 BeforeModelRewriteState |
旧线那套会写穿回 REPL 历史——当前语义下当时想要,但 v6 的页面历史真源是 runlog,不能跟着模型出口一起改 |
| dev 探针 | POST /api/dev/pii-check body {text} → {masked, hits:[{kind,span}]} |
只读诊断口,长期保留 |
| at-rest 加密 | 不做(数据安全另案) | 库里的原文仍是明文,这是已知边界 |
| 向量库侧 PII | 不做 | 记忆端点本来就是 dev 观测口 |
| 对外 API 返回体的 PII 审查 | 不做 | 同上 |
5. 证据
方案:doc/41-任务看板与人工审批.md §3.2(三处挂载点 + 策略 + 踩坑修复表 + 本期不做)、§6 Loop B(B1–B3 三拍)。规则口径来源:doc/06-工具安全层.md §3.3(7 条正则、头尾各 4 位、幂等、两个旧挂载点)。
台账:tmp/41-任务看板与人工审批/(本地,不入库)。
代码符号:
| 位置 | 是什么 |
|---|---|
internal/runengine/pii.go:30 |
PIIKind:密钥类 / 证件类词表 |
internal/runengine/pii.go:66 |
piiRules:正则规则表 |
internal/runengine/pii.go:88 |
MaskPII(text) (string, []PIIHit):唯一扫描函数 |
internal/runengine/pii.go:152 |
maskSpan:按规则打码 |
internal/runengine/pii.go:164 |
maskKeep:保留头尾 |
internal/runengine/pii.go:180 |
piiToolWrapper:工具出口包装 |
internal/runengine/pii.go:200 |
hasSecretPII:记忆拒收判据 |
internal/runengine/pii.go:213 |
devPiiCheck:POST /api/dev/pii-check |
internal/runengine/pii.go:236 |
MaskPIIKeepUserMasked:不二次打码 |
internal/runengine/tools.go:49 |
wrapToolErrors:挂载点①(所有工具结果唯一必经) |
internal/runengine/midfold.go:373 |
toSchemaMessages:挂载点②(模型输入唯一转换口) |
internal/runengine/memory.go:553、:578 |
挂载点③(episode 与 item 两处) |
复核命令:
cd yk-tako-eino
grep -n "piiRules\|MaskPII\|hasSecretPII" internal/runengine/pii.go
grep -n "piiToolWrapper" internal/runengine/tools.go internal/runengine/pii.go
grep -rn "MaskPII" internal/runengine/midfold.go internal/runengine/memory.go活体验收(2026-10-23):pii_test.go 金样钉住掩码串与 span;pii_mount_test.go 钉住三个挂载点。活体:发含假证件号的消息 run 正常 complete(「模型不复述」类断言登记 declared_not_asserted);发「我的身份证号是 110101…,请记住」→ 抽取后记忆 dev 观测口读到打码后条目;构造夹带 sk- 的原文 → 该条不入库。
6. 现状
- 仍有效:三处挂载点;两类 PII 两类策略;工具输出打码即焚、用户原文留存;记忆拒收/打码分档;幂等掩码。
- 已翻转:原方案的「贴真工具内侧」「挂 prepareInput」两处都被落地时推翻(理由见 §3)。
- 明确不做:at-rest 加密、向量库侧 PII、对外 API 返回体 PII 审查。
- 同族问题:审批闸整条不做 → 工具三态守卫与审批回路;记忆入库管线 → 记忆要不要上向量;旧线规则表来源 → 工具三态守卫与审批回路。