ARTICLE / 开源项目

补充PII安全平台注册表特性的研究

Updated
Reading time
5 min

PR 地址：NousResearch/hermes-agent#47045 · 让 PII 安全平台检测从硬编码集合走向动态注册表

研究摘要

Hermes 在构建会话上下文时，需要判断当前交互平台是否属于 PII 安全平台——只有被判定为安全的平台，才会获得包含敏感个人信息在内的完整上下文提示。此前这套判定依赖 session.py 里一个硬编码的平台集合：接入一个新的聊天前端，就要改一次核心代码，插件作者没有任何自助入口。

本 PR 把检测优先级从"硬编码优先"改为"平台注册表优先"：插件作者只需在自己的 PlatformEntry 上设置 pii_safe=True，Hermes 就会自动将该平台视为 PII 安全，全程无需触碰 session.py。硬编码集合被完整保留为兜底，所有既有平台行为不变，267 个状态机回归测试全部通过。改动集中在 build_session_context_prompt() 一个函数内，仅 +19/-12 行。

一、问题背景：PII 判定的扩展权握在核心代码手里

1.1 会话上下文里的 PII 门禁

build_session_context_prompt() 负责把会话上下文组装成发送给模型的提示。其中有一个关键门禁：PII 安全平台判定。被判定为 PII 安全的平台，可以拿到包含敏感个人信息的完整上下文；未被判定的平台则被降级处理，避免敏感信息被注入对话。

这个门禁的判定依据，是一个硬编码在 session.py 中的 _PII_SAFE_PLATFORMS 集合。

1.2 硬编码的三个代价

一是扩展必须改核心代码。Hermes 的插件生态里，一个新平台接入要走 PlatformEntry 注册路径，但"这个平台是否 PII 安全"的结论却写在核心模块里——平台身份由注册表定义，平台属性却要改 session.py，身份与属性被割裂在两个地方。

二是插件作者没有自助入口。平台作者比任何人都清楚自己的平台是否收集、存储敏感个人信息，但他们无法通过公开的注册机制表达这一事实，只能提 PR 改核心代码，把维护负担转嫁给 Hermes 核心团队。

三是误改风险。任何对硬编码集合的修改都发生在核心热路径上，一次误编辑就可能影响所有平台的 PII 判定，而它本不该是高频改动点。

1.3 PII 判定的语义：信任声明而非技术事实

PII 安全判定的本质是信任声明：被标记为安全的平台，意味着它不收集、不存储、不转发敏感个人信息，Hermes 才放心把包含个人信息的完整上下文注入该平台的会话。这个判定不是代码正确性问题，而是平台数据处理方式的属性。正因为它是平台属性，理应随平台定义（PlatformEntry）一起声明，而不是沉淀在核心模块的硬编码集合里——这是本 PR 优先级翻转的深层动机。

二、特性设计：注册表优先、硬编码兜底的两步检测

2.1 检测逻辑的优先级翻转

改动核心是一处优先级调整，build_session_context_prompt() 里的判定逻辑变为两步：

  1. 先查平台注册表：如果当前平台在 PlatformEntry 注册表中存在条目，且 pii_safe=True，直接判定为 PII 安全；
  2. 再查硬编码集合：注册表没有条目（或未标记）的平台，回落到 _PII_SAFE_PLATFORMS 硬编码集合判定。

两步检测的语义被写进 docstring，让后来者一眼看懂判定顺序。

2.2 为什么注册表优先

平台身份本就由注册表承载：PlatformEntry 定义了平台的名字、能力、接入方式。把"是否 PII 安全"这个属性也放回注册表，平台的身份与属性就回到了同一处声明，插件作者可以随平台定义一起表达安全属性。而硬编码集合作为兜底保留，保证那些尚未注册、或注册时未声明安全属性的既有平台，行为与升级前完全一致——这是向后兼容的根基。

2.3 改动面收敛

整个特性收敛在 gateway/session.py 一个文件内（+19/-12）：检测逻辑、docstring、以及被保留的硬编码集合。没有引入新配置项、没有改提示词组装、没有动其他模块。一个函数内的优先级翻转，换来的是插件生态的自助扩展能力。选择在既有函数内翻转优先级而不是另建独立检测模块，是因为 PII 判定只有一个消费点，最小改动面把回归风险压在最低，也让后来者在一个函数内就能看完完整的判定链路。

三、实测结果

PR body 附带的回归验证为状态机全量测试：

测试结果
tests/test_hermes_state.py（会话状态机全量）267 passed

注册表优先的检测路径在状态机全量回归中无任何失败，硬编码兜底路径的行为保持不变，验证了向后兼容承诺。

四、能力边界

  • 注册表优先仅对已注册平台生效：未注册或未声明 pii_safe 的平台仍走硬编码集合，该集合继续承担兜底职责；
  • 单点改动、范围明确：只影响 PII 判定这一个门禁，不改变会话上下文构建的其他环节，也不改变提示词内容本身；
  • 语义责任在插件作者：pii_safe=True 意味着平台作者声明自己的平台不会泄露敏感信息，这是一个信任声明——如果插件作者误标，PII 门禁会按声明放行，因此该字段的使用需要平台作者对自身数据处理方式有准确判断；
  • PR 未附带真机多平台验证：PR body 只给出了状态机测试结果，未提供在具体第三方平台上的端到端验证记录，实际效果依赖插件侧配合声明；
  • 未附平台注册引导文档：PR 只改检测逻辑，插件作者如何为自家平台声明 pii_safe 的操作指引不在本 PR 范围内，生态落地依赖文档补齐。

五、PR 信息

  • PR 地址：https://github.com/NousResearch/hermes-agent/pull/47045
  • 改动规模：+19 / -12，1 个文件（gateway/session.py）
  • PR 状态：closed
  • 提交时间：2026-06-16

本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。

RELATED SIGNALS

继续探索