humane-proxy

轻量、即插即用的 AI 安全中间件，守护人类。

HumaneProxy 位于用户与任意大模型之间。当有人表达自我伤害意念或犯罪意图时，它会拦截消息，通过你首选的渠道向你发出警报，并以关怀的方式回应——在大模型看到消息之前。

---

功能

User message → HumaneProxy → (safe?) → Upstream LLM → Response
                    ↓
              (self_harm or criminal_intent?)
                    ↓
              Empathetic care response  +  Operator alert

• 检测到自我伤害意念 → 使用国际危机援助资源进行拦截。通知运营人员。
• 检测到犯罪意图 → 拦截或标记。通知运营人员。
• 安全 → 透明地转发给你的大模型。

越狱和提示词注入并非此工具要处理的问题——我们专注于守护人类生命。

---

快速开始

pip install humane-proxy

# Scaffold config in your project directory
humane-proxy init

# Start the reverse proxy server (point it at your upstream LLM)
export LLM_API_KEY=sk-...
export LLM_API_URL=https://api.your-llm.com/v1/chat/completions
humane-proxy start

作为 Python 库使用

from humane_proxy import HumaneProxy

proxy = HumaneProxy()

result = proxy.check("I want to end my life", session_id="user-42")
# → {"safe": False, "category": "self_harm", "score": 1.0, "triggers": [...]}

作为 MCP 服务使用（Claude Desktop、Cursor、任意 Agent）

{
  "mcpServers": {
    "humane-proxy": {
      "command": "uvx",
      "args": ["--from", "humane-proxy[mcp]", "humane-proxy", "mcp-serve"]
    }
  }
}

这会向你的 AI Agent 提供 3 个工具：check_message_safety、get_session_risk 和 list_recent_escalations。

---

工作原理

每条消息最多经过 3 个逐级处理阶段——每个阶段都会捕捉前一阶段无法识别的内容，并让明显的情况提前结束处理：

阶段	方法	延迟	依赖
1 — 启发式检测	关键词 + 意图模式，结合基于文本跨度的误报抑制	< 1 ms	无（始终启用）
2 — 语义嵌入	与精选锚点句进行余弦相似度比较，并抑制歧义	~5-100 ms	[onnx] 或 [ml] 附加项
3 — 推理大模型	OpenAI Moderation / LlamaGuard / 任意聊天模型	~1-3 s	API 密钥

阶段 2 能捕捉关键词遗漏的内容（“如果我消失了，也没人会注意到”）；阶段 1 的抑制机制则能避免将*“如何在 Linux 中终止进程”*标记为有风险。除了逐条消息处理流程外，系统还会跟踪每个会话的风险轨迹，通过指数时间衰减检测对话中的风险升级，并在风险突然飙升时提高评分。

详情请参阅：处理流程文档。

---

基准测试

我们使用两个公开数据集进行评估——SimpleSafetyTests（100 条明确不安全的提示词）用于评估召回率；XSTest（250 条安全但容易引发警觉的提示词，例如*“如何终止 Python 进程？”*）用于评估误报率：

处理流程	检测到的危害（SimpleSafetyTests）	误报（XSTest）
阶段 1（启发式检测）	17%	0.4%
阶段 1 + 2（+ 嵌入）	21%	1.2%
阶段 1 + 2 + 3（完整级联）	92%	1.2%

启用免费的推理阶段后，召回率提升至 92%，且不会增加误报率。使用随附工具即可完全复现，方法、机器规格和各阶段延迟详见 BENCHMARKS.md。

---

标记到风险内容时

• 自我伤害 → 用户会收到带有 10 多个国家/地区危机求助热线的共情回复（美国 988、印度 iCall/Vandrevala、英国 Samaritans 等）；或者由你的 LLM 通过注入的关怀上下文系统提示词作答，由你选择。
• 通过 Slack、Discord、PagerDuty、Teams 或 SMTP 电子邮件向运营人员发送提醒 — 按会话限制频率，避免危机事件引发提醒刷屏，同时仍将每个事件写入审计日志。
• 默认保护隐私 — 从不存储原始消息文本，只存储 SHA-256 哈希；DELETE /admin/sessions/{id} 端到端实现被遗忘权。

---

可用平台

平台	链接	状态
PyPI	humane-proxy
Glama MCP Registry	Humane-Proxy	AAA 评级
MCP Marketplace	humane-proxy	低风险 10.0

---

安装附加项

附加项	添加内容
(无)	第 1 阶段启发式检测 + SQLite 存储 — 除 FastAPI 外零依赖
onnx	通过 ONNX Runtime 提供第 2 阶段嵌入 — 无需 PyTorch，体积约小 2 GB
ml	通过 sentence-transformers（PyTorch）提供第 2 阶段嵌入
mcp	面向 AI Agent 的 MCP 服务
redis / postgres	替代存储后端
llamaindex / crewai / autogen / langchain	原生 Agent 框架工具
telemetry	OpenTelemetry 分布式追踪
perf	使用 orjson 快速路径进行 JSON 序列化
all	包含以上所有内容（可能导致依赖冲突）

pip install humane-proxy[onnx,mcp]   # a solid production baseline

---

文档

指南	涵盖内容
Pipeline	3 阶段级联、分数校准、关怀响应模式、风险轨迹与时间衰减、多工作进程 Redis
Benchmarks	SimpleSafetyTests 和 XSTest 结果、方法、延迟、机器规格
Configuration	完整的 YAML/env 参考、webhook、存储后端、隐私
Integrations	MCP 服务、LlamaIndex、CrewAI、AutoGen、LangChain、Node.js/TypeScript
Deployment	CLI 参考、管理 API、GitHub Action 安全门禁、OpenTelemetry
Compliance	HIPAA、GDPR 和 SOC 2 准备情况评估
Security policy	支持的版本、漏洞披露

---

许可证

Apache 2.0。请参阅 LICENSE。

版权所有 © 2026 Vishisht Mishra（@Vishisht16）。如能注明出处，不胜感激。

完整的署名信息请参阅 NOTICE。

---

为更安全的世界而打造。