TraceGuard

AI Agent 的工具调用前置拦截器。在执行之前，把危险动作拦下来。

---

🚀 30 秒上手（先跑这一条）

pip install ai-traceguard
traceguard demo

它会现场演一遍：造一个文件 → 让 AI 去删 → 看 TraceGuard 把它拦下来。 不用配置、不联网、不会动你的项目。看完你就懂了。

然后三步接进你自己的代码：

traceguard init                 # ① 生成策略文件

from traceguard import TraceGuard
guard = TraceGuard(policy="traceguard-policy.yaml", mode="strict")   # ② 创建护栏

def delete_file(path):
    d = guard.check("delete_file", {"path": path})   # ③ 在每个工具体最前面加这三行
    if not d.allowed:
        return f"被拦截：{d.reason}"
    Path(path).unlink()

traceguard test                 # 自检：应输出 delete_file: BLOCKED / read_file: ALLOWED

不确定装没装对？跑 traceguard selfcheck —— 它会检查策略文件、审计库，能修的自动修。

---

它解决什么问题

AI Agent 会删掉生产库、把 API Key 发到外部、在死循环里把 Token 烧光。 市面上的可观测 / 追踪工具只能事后记录——等你看到日志，数据已经没了。

TraceGuard 不同：它站在工具调用的执行路径上，在动作发生之前做出确定性的允许 / 阻断判断。

追踪工具告诉你「凌晨 3 点删了什么」； TraceGuard 让它在「凌晨 3 点删不掉」。

---

安装

pip install ai-traceguard

零依赖服务、零配置文件、零网络请求。装完即用。

---

快速开始

from traceguard import TraceGuard

guard = TraceGuard(policy="policies/base.yaml", mode="strict")

decision = guard.check("delete_file", {"path": "/data/users.csv"})
if not decision.allowed:
    print(f"已阻断：{decision.reason}")
else:
    # 执行真正的工具逻辑
    pass

CLI 自检：

traceguard test
# delete_file: BLOCKED
# read_file: ALLOWED

---

策略包（Guard Packs）

开箱即用的策略模板，覆盖最常见的翻车场景：

策略包	作用
pack-anti-delete	拦截文件 / 数据库删除
pack-anti-token-runaway	拦截 Token 预算超支
pack-anti-data-leak	拦截敏感数据外发

traceguard init --pack anti-delete
# 生成 traceguard-policy.yaml

---

审计链（Audit Chain）

每一次裁决都会写入本地的 SHA-256 哈希链。任何后续篡改都会破坏链条，可被检出。

traceguard verify
# 审计链有效

导出给审计 / 合规团队（Pro 能力）：

from traceguard_pro import export_audit_jsonl, verify_exported_jsonl

export_audit_jsonl("traceguard-audit.db", "audit-export.jsonl")
assert verify_exported_jsonl("audit-export.jsonl")   # 第三方可独立复核

---

三种模式

模式	行为
strict	HIGH 风险阻断，MEDIUM 需要审批
balanced	HIGH 需要审批，MEDIUM 放行
observe	全部放行，全部记录（灰度 / 观测用）

---

合规与安全

TraceGuard 的设计目标是架构上零风险：

• 无网络请求。 拦截层永不联系外部服务器，因此没有可被拦截、泄露或审查的东西。
• 无模型 API。 不代理、不转售、不路由任何模型调用。
• 只存本地 SQLite。 审计数据属于你，永远不出本机。
• 离线授权。 授权码本地 HMAC 验签，可在气隙环境中运行。

因此：无需 ICP 备案、无需生成式 AI 备案、无数据出境评估。详见 docs/compliance.md。

---

商业版（TraceGuard Pro）

开源核心（MIT）足够个人使用；生产与合规场景需要的确定性能力放在 Pro：

能力	说明	版本
参数级敏感信息扫描	拦截参数里的 api_key / password / private_key / PII	Pro
Token 预算 + 死循环拦截	会话超预算、同调用反复重试时阻断	Pro
可校验审计导出	JSONL 导出，第三方可独立重算哈希链	Pro
行业策略包	金融 / 医疗 / DevOps 预设	Pro
人工审批流	MEDIUM 风险改为人工审批而非静默放行	Team
席位报表 / 自定义包 / SLA	—	Enterprise

未持有效授权时，ProGuard 会优雅降级为开源核心行为，方便先试后买。

---

文档

• 快速开始（中文版）
• 合规说明
• 安全策略
• 贡献指南
• 变更日志

---

许可证

核心：MIT。商业增值包 traceguard-pro 采用商业许可，详见其 README。

---

English (short)

TraceGuard is a local runtime guardrail for AI agents. It intercepts dangerous tool calls before execution — no network, no server, deterministic decisions, and a tamper-evident local SHA-256 audit chain. Install with pip install ai-traceguard. Full English docs: README.en.md.