tako 文档 GitHub

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. 现状