防篡改的 AI 代理审计追踪 —— 哈希链式运行时记录，渲染为运行时报告，你的客户可以自行核验。
你的插桩捕获的每一个操作（工具调用、模型调用、数据访问、审批）都会成为仅追加、哈希链式日志中的一条 运行时记录；运行时报告 是将该链渲染为一个 HTML 页面，在读者的浏览器中重新计算哈希链，并根据其验证过的记录渲染所显示的内容（对于不依赖页面自身代码的检查，可对 JSONL 运行 halo verify）。任何持有链检查点的一方都可以验证截至该检查点的记录自检查点生成以来未被篡改，而无需信任生成记录的一方——该检查点是承重部件：仅凭链本身，除了操作记录器的一方之外，对所有人都是防篡改的（LIMITS.md §1）。当客户的安全团队问“你的代理对我们的数据做了什么？”时，你递给他们一个链接，而不是一段文字。安全审查已经在 SOC 2 检查清单旁边提出 AI 相关问题——而且越来越多的问题来自 ISO 42001、欧盟 AI 法案的记录保存条款，以及客户自己的问卷。如今，一份书面保证仍然能通过。这个项目背后的赌注是，这种情况不会持续太久。
被 Help Net Security 报道（2026 年 8 月）。
记录格式是开放的，可自由实现。本包是参考实现：记录器、验证器、见证客户端和报告服务器。
正在使用 halo-record，或正在考虑？ 告诉我你是谁、用途是什么 → 谁在使用 halo-record？
有人要求你在你的代理中放入一个记录器。你不应盲目相信：
pip install halo-record 只安装一个包。halo serve --verify-email（通过你在 $HALO_SMTP_HOST 中配置的服务器，以 SMTP 方式将一次性验证码和报告的主体名称发送到报告查看者输入的地址）。除非你主动调用，否则这些功能均关闭；没有其他记录内容离开你的基础设施。summaries=False）完全不保留摘要。脱敏是尽力而为（对常见密钥和 PII 格式的正则表达式，外加熵兜底）：将其视为纵深防御，而非保证。你提供的 summary 之外的结果字段会以相同模式扫描和掩码，但不会截断到 200 个字符（LIMITS §13）。每一层证明什么——本项目中的承重区分（LIMITS.md §1）：你自己持有的链证明记录未被编辑，相对于某人已持有的链头；只有操作者外部持有的检查点才能证明没有记录被移除；没有任何哈希能证明每个操作都被捕获。
| 主张 | 自持链 | + 外部检查点 | + 可信捕获 |
|---|---|---|---|
| 检测对已建立产物的编辑 | ✔ | ✔ | ✔ |
| 检测对已提交历史的改写 | — | ✔ | ✔ |
| 检测缺失/延迟的检查点 | — | ✔（约定节奏） | ✔ |
| 证明每个操作都被记录 | — | — | 取决于捕获边界 |
安装前先看一个： 示例运行时报告——虚构数据、真实链，打开时其脚本会在你的浏览器中重新计算内嵌记录的哈希链。
无需代理。使用 uv，无需安装任何东西：
uvx --from halo-record halo demo --serve
或经典方式：
pip install halo-record
halo demo --serve
要么搭建一个虚构的支持代理供应商，包含两个客户，见证这些链（用一个本地见证文件代表操作者之外的一方——参见 LIMITS.md §1），提供他们受门控的 Runtime Reports，并在你的浏览器中打开操作员控制台。然后尝试篡改测试：从其中一个 .jsonl 文件中删除一行并重新加载。报告会捕获它。
在边界处一行：
from halo_record import trace
agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # wraps your entrypoint; records the run boundary to ./audit.jsonl — add record_call() or a framework adapter at each tool boundary to capture individual calls
from halo import ... 便捷垫片也会随附提供——但 PyPI 上的 halo 名称属于一个无关的终端加载动画包，如果该包已安装，它会在导入时胜出。halo_record 则没有歧义，因此示例使用它。
如果没有 log=，记录会写入 ~/.halo/my-agent.jsonl（每个 agent 一条链）。包装器封存运行边界；证据存在于每次调用的记录中。使用框架适配器（见下方矩阵）捕获这些记录——或者显式捕获，这也能展示委托链接是如何建立的：
from halo_record import Recorder, record_call
rec = Recorder("audit.jsonl")
with record_call(rec, "crm.lookup", {"account": "acct-9"}) as call: # one sealed record per tool call
call.result = crm.lookup("acct-9")
with record_call(rec, "payments.refund", {"amount": 120},
parent_id=rec.last_record_id()) as call: # child links to the action that spawned it
call.result = payments.refund(120)
然后渲染报告：
halo report audit.jsonl -o report.html # one chain -> HTML that re-verifies in the browser
halo serve ./records --port 8721 # all tenants, gated per customer
升级一个最初由 0.2.45 提供服务的目录？halo serve 会在启动时重新读取每个先前的授权。对某个文件的授权，如果其记录不携带 subject id（例如 agent.jsonl 这样的普通 Recorder 文件），会被隔离，并在每次启动时打印出来，同时附带重新签发它的 halo grant 命令——参见 LIMITS.md §17，“Serving a directory first served by 0.2.45”。
当你在浏览器中看到自己 agent 的 Runtime Report 时，快速入门就结束了。如果你得到了一个 JSONL 文件却没有报告，那说明出了问题：请提交一个 issue。
如果某个护栏或策略层检查了该操作，其裁决可以随记录一起传递——这是一个可选块，记录门控做出的决定，并像其他所有字段一样被封入哈希链：
from halo_record import build
build("tool_call", "security", tool="payments.refund",
verification={"status": "allowed", "verifier": "gate/1.2",
"policy_ref": "sha256:1f3a...",
"checked_at": "2026-08-01T12:00:00Z"})
一个命名说明：该包导出了一个 record 函数（装饰器），它会在包对象上遮蔽 halo_record.record 模块。当你需要其内部实现时，请直接从模块路径导入——from halo_record.record import build——而不是 import halo_record.record as record。
其封存进记录后为：
"verification": {"status": "allowed", "verifier": "gate/1.2", "policy_ref": "sha256:1f3a...", "checked_at": "2026-08-01T12:00:00Z"}
record_call(...) 接受相同的 verification= 关键字参数。status 在块内是必需的；verifier、policy_ref 和 checked_at 是可选的。每个状态的含义如下：
| 状态 | 门禁报告的内容 | 操作是否执行？ |
|---|---|---|
allowed | 它允许了该操作 | 是 — 操作继续进行 |
blocked | 它拒绝了该操作 | 由集成决定，而非此字段 — 记录仍可能携带结果，且阻止本身并不证明未执行 |
modified | 它在执行前修改了该操作 — action.input 描述的是已执行的操作，即修改后的形式 | 是，以修改后的形式 |
unverified | 它运行了（或被咨询了）但未做出判定 — 与缺失的块不同，后者意味着根本没有做出验证声明 | 是 — 操作在没有裁决的情况下继续进行 |
该块由操作者的集成代码提供，并记录其报告的门禁所述内容 — 与 principal 相同的信任姿态（参见 LIMITS）。密封证明状态在事后未被编辑；它并不证明检查确实发生、裁决正确，或已阻止的操作未执行。这不是独立验证。
要使 policy_ref 可用作证据，请使用规则集的内容哈希并保留规则集工件 — 无法解析的标签会使该字段沦为装饰。
| 在边界处捕获 | 从现有遥测中摄取 |
|---|---|
原生记录器（from halo_record import trace） | OpenTelemetry GenAI spans |
| MCP 拦截器 | LiteLLM 回调 |
| LangChain / LangGraph 回调 | Langfuse 导出 |
| OpenAI Agents SDK 钩子 | 任何网关 / 反向代理日志 |
| Claude Agent SDK 钩子 | Claude Code 和 Codex CLI 的 PostToolUse 钩子（在工具运行后触发） |
框架适配器和摄取路径会为每条记录打上 source 标签，因此报告会披露每条证据是如何收集的。捕获的记录和摄取的记录存在于同一条链中。
对于 LangChain / LangGraph，它是一个回调处理器：
from halo_record import Recorder
from halo_record.integrations.langchain import HaloCallbackHandler
recorder = Recorder("audit.jsonl")
result = my_chain.invoke(inputs, config={"callbacks": [HaloCallbackHandler(recorder)]}) # every tool call becomes a record
对于 MCP，一次调用即可包装客户端会话——随后任何使用 MCP 的 agent 都会为每次工具调用发出记录，无论它由哪个框架驱动：
from mcp import Client # mcp 2.x
from halo_record import Recorder
from halo_record.integrations.mcp import instrument_client_session
async def run(server): # an MCPServer, a server URL, or stdio parameters
async with Client(server) as client:
instrument_client_session(client, Recorder("audit.jsonl"), server="stripe")
await client.call_tool("charge", {"customer": "cus_123", "amount": 500}) # recorded
对包装客户端上的每次 call_tool() 调用都会被记录，返回错误结果的工具会被标记为 error（适配器会同时读取 isError 和 mcp 2.x 的 is_error）。在 mcp 1.x 上，传入已初始化的 ClientSession 而不是 Client；包装器是相同的。
对于网关或代理日志（Cloudflare AI Gateway、Portkey、模型前面的 nginx），将日志行映射到链中——明确标记为已摄取，而非边界捕获：
from halo_record.integrations.gateway import record_log
record_log(Recorder("audit.jsonl"), {"tool": "gen_ai:gpt-4o", "model": "gpt-4o", "status": 200, "subject": "acme-corp"})
任何发出 OpenTelemetry GenAI span 的内容（CrewAI、LlamaIndex，以及大多数带有 OTel 插桩的 agent 框架）都会通过 OTel 适配器进入链中，而 TypeScript 包 为 Vercel AI SDK 和 JS agent 生态系统提供了原生适配器。缺少适用于你的技术栈的适配器？提交一个 issue。大多数适配器大约只有一百行代码。
Claude Code 在每次工具调用后都会触发一个 PostToolUse 钩子。将其指向 halo hook，每个操作——文件写入、shell 命令、MCP 连接器调用——都会成为本地链中的一条记录。无需修改代码；只需一项设置条目：