Show HN: Halo——为 AI 智能体提供开源、防篡改的运行时证据

为 AI 智能体提供防篡改的 运行时记录：一条供应商运行却无法编辑的审计轨迹。

你的智能体执行的每一个动作（工具调用、模型调用、数据访问、审批）都会成为仅追加、哈希链式日志中的一条记录。任何一方都可以验证日志从未被篡改，而无需信任生成日志的人。当客户的安全团队问“你的智能体对我们的数据做了什么？”时，你可以递给他们一个链接，而不是一段文字说明。如今，安全审查已经在 SOC 2 清单旁边加入了 AI 问题，而一份书面保证仍然能通过。而这个项目背后的赌注是，这种情况不会持续太久。

记录格式是开放的，任何人都可以自由实现。本软件包是参考实现：记录器、验证器、见证客户端和报告服务。

为什么你可以信任这段代码

你被要求将记录器放入你的智能体内部。你不应该仅凭信任就接受：

• 零运行时依赖。 仅使用标准库。pip install halo-record 只会安装一个包。
• 无网络调用，除了见证服务（它是可选的，且仅接收记录数量和链指纹）。记录内容永远不会离开你的基础设施。
• 原始输入不会进入记录。 参数会被哈希化，并仅存储为脱敏摘要——永远不会存储原始值。脱敏是尽力而为的（基于常见密钥和 PII 格式的正则表达式），请将其视为纵深防御而非保证。
• 足够小，可以审计。 约 4,300 行 Python。一个下午就能通读全部代码。
• Apache-2.0。

无需智能体即可体验。使用 uv，无需安装任何东西：

uvx --from halo-record halo demo --serve

或者传统方式：

pip install halo-record halo demo --serve

以上任一命令都会搭建一个包含两个客户的虚构支持代理供应商场景，对链进行见证，提供带访问权限的运行时报告，并在你的浏览器中打开操作控制台。然后可以尝试篡改测试：从某个 .jsonl 文件中删除一行，再重新加载。报告会检测到它。

在边界处，只需一行代码：

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl") # 包装你的入口点；将每次工具调用记录到 ./audit.jsonl

如果不指定 log=，记录会存入 ~/.halo/my-agent.jsonl（每个智能体一条链）。也可以对你已运行的智能体使用适配器（见下文矩阵）。然后渲染报告：

halo report audit.jsonl -o report.html # 一条链 -> 自验证 HTML halo serve ./records --port 8721 # 所有租户，按客户进行访问控制

当你能够在浏览器中查看自己智能体的运行时报告时，快速入门就结束了。如果你得到了一个 JSONL 文件却没有报告，那说明有问题：请提交 issue。

连接到你已运行的智能体

在边界处捕获	从现有遥测中提取
原生记录器 (from halo import trace)	OpenTelemetry GenAI 跨度
MCP 拦截器	LiteLLM 回调
LangChain / LangGraph 回调	Langfuse 导出
OpenAI Agents SDK 钩子	任何网关/反向代理日志
Claude Code / Claude Agent SDK 钩子

每条记录都带有一个 source 标签，因此报告会披露每条证据是如何收集的。捕获的记录和提取的记录存在于同一条链中。

任何会发出 OpenTelemetry GenAI 跨度的东西（CrewAI、LlamaIndex，以及大多数具备 OTel 插装的智能体框架）都可以通过 OTel 适配器进入链中，而 TypeScript 软件包 则为 Vercel AI SDK 和 JS 智能体生态提供了原生适配器。缺少你技术栈的适配器？提交一个 issue。大多数适配器只有约一百行代码。

Claude Code 在每次工具调用后会触发一个 PostToolUse 钩子。将其指向 halo hook，那么每个动作——文件写入、shell 命令、MCP 连接器调用——都会成为本地链中的一条记录。无需修改代码；只需要添加一项设置：

{ "hooks": { "PostToolUse": [ {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]} ] } }

将其添加到 ~/.claude/settings.json，记录就会落入 ~/.halo/audit.jsonl（可通过 $HALO_LOG 覆盖）。那些不接触数据、网络或外部状态的纯编排工具会被跳过——链记录的是信任边界上的动作，而非思考过程。设置 HALO_HASH_ONLY=1 可以只记录内容哈希，不记录摘要。然后，照常运行：

halo verify ~/.halo/audit.jsonl halo report ~/.halo/audit.jsonl -o report.html

任何暴露操作后钩子的智能体运行时都可以接入同一个命令——这个钩子从标准输入读取一个 JSON 事件，并追加一条记录。

完整性 vs. 完备性（请阅读本节）

一条自持的链可以证明 完整性：事后没有任何内容被编辑或重新排序。它无法证明 完备性：记录器的操作者可以删除出问题的那一天并重新密封整条链，或者根本不写入任何记录，而链内部仍然保持一致。

完备性需要一个不受操作者控制的外部方，能定期持有链的指纹（仅记录计数和头部哈希，别无其他）。这就是见证：

halo anchor audit.jsonl witness.jsonl # 将检查点锚定到本地见证 halo anchor audit.jsonl witness.jsonl --check # 根据见证进行完备性判定

任何人都可以运行一个见证。你自己运行的见证可以向 你 证明完整性；而要向 你的客户 证明完备性，则需要一个他们有理由信任的见证。无论哪种，协议都是开放的。

一个托管且被认可的见证将使这个项目得以持续。早期访问请联系：bkuan001@gmail.com。

这在合规体系中处于什么位置

halo-record 是一个证据层，而不是认证本身。它生成的是各类评估框架以不同措辞反复要求得到的工件：

• 安全问卷和 SOC 2 审查： 用可验证的运行时报告来回答 AI 相关章节，而不是截图和文字描述。
• AIUC-1： 为智能体行为要求提供连续的运行时证据，而非在审计时临时拼凑。
• OWASP（GenAI 安全项目）： 作为 OWASP LLM 应用 Top 10 和 Agentic Security Initiative 中智能体行为风险（过度自主、工具滥用、敏感信息泄露）背后的运行时证据——记录智能体实际做了什么，使用了哪些工具和数据。
• AARM (CSA)： 生成 AARM 所要求的防篡改操作回执（R5/R6）——带链式结构和独立见证。halo-record 是回执层；将其与执行网关配对，即可构成完整的 AARM 系统。参见 AARM.md。
• 《欧盟 AI 法案》： 高风险 AI 系统的日志和记录保存义务。
• ISO 42001 / NIST AI RMF： 管理体系控制背后的运行证据。

这些本身并不能认证任何东西。它为你的评估者提供了一些可以验证的东西。

halo verify 验证 schema + 哈希链（失败时返回非零退出码；适合 CI） halo report 将链渲染为自验证的 HTML 运行时报告 halo serve 通过 HTTP 提供按租户划分的报告，并根据客户限制访问范围 halo grant 指定报告接收者（邮箱或域名） halo anchor 见证链头部，或使用 --check 进行完备性检查 halo demo 搭建完整的供应商演示（记录 -> 见证 -> 带访问控制的报告） halo sample 输出一个有效的示例日志 halo hash 计算某个 JSON 值的规范 sha256 halo hook Claude Code PostToolUse 钩子

计算记录的哈希值：取出去除 integrity.hash 的记录，将 integrity.prev_hash 设为上一条记录的哈希；使用 RFC 8785（JSON 规范化方案）进行规范化；对字节进行 SHA-256。第一条记录的 prev_hash 为 64 个零。验证过程重新计算每个哈希并检查每个链接。不需要任何密钥——这正是关键所在。

你认为能绕过验证器篡改链吗？尝试和结果在这里。

完整的字段参考：halo-record.schema.json。

同一记录器也提供了 Node 版本：halo-record-ts。相同的链格式，相同的见证协议。用任一语言编写的记录，都可以用另一语言的验证器进行验证。

Apache-2.0

Tamper-evident runtime records for AI agents : the audit trail the vendor runs but cannot edit.

Every action your agent takes (tool calls, model calls, data access, approvals) becomes one record in an append-only, hash-chained log. Any party can verify the log was never altered, without trusting whoever produced it. When a customer's security team asks "what did your agent do with our data?", you hand them a link instead of a paragraph. Security reviews already ask AI questions next to the SOC 2 checklist, and today a written assurance still passes. The bet behind this project is that it won't for long.

The record format is open and free to implement. This package is the reference implementation: recorder, verifier, witness client, and report server.

Why you can trust this code

You are being asked to put a recorder inside your agent. You should not take that on faith:

• Zero runtime dependencies. Standard library only. pip install halo-record installs exactly one package.
• No network calls , except the witness, which is opt-in and receives only a record count and a chain fingerprint. Record contents never leave your infrastructure.
• Raw inputs never enter a record. Arguments are hashed and stored only as a redacted summary — never the raw value. Redaction is best-effort (regex over common secret and PII formats): treat it as defense-in-depth, not a guarantee.
• Small enough to audit. ~4,300 lines of Python. Read all of it in an afternoon.
• Apache-2.0.

No agent required. With uv, nothing to install:

uvx --from halo-record halo demo --serve

or the classic way:

pip install halo-record
halo demo --serve

Either one scaffolds a fictional support-agent vendor with two customers, witnesses the chains, serves their gated Runtime Reports, and opens the operator console in your browser. Then try the tamper test: delete a line from one of the .jsonl files and reload. The report catches it.

One line at the boundary:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

Without log=, records go to ~/.halo/my-agent.jsonl (one chain per agent). Or use the adapter for what you already run (see the matrix below). Then render the report:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

The quickstart ends when you are looking at your own agent's Runtime Report in a browser. If you got a JSONL file and no report, something is wrong: open an issue.

Connect to what you already run

Captured at the boundary	Ingested from existing telemetry
Native recorder (from halo import trace)	OpenTelemetry GenAI spans
MCP interceptor	LiteLLM callbacks
LangChain / LangGraph callback	Langfuse export
OpenAI Agents SDK hooks	Any gateway / reverse-proxy log
Claude Code / Claude Agent SDK hook

Every record carries a source tag, so the report discloses how each piece of evidence was collected. Captured and ingested records live in the same chain.

Anything that emits OpenTelemetry GenAI spans (CrewAI, LlamaIndex, and most agent frameworks with OTel instrumentation) lands in the chain through the OTel adapter, and the TypeScript package ships native adapters for the Vercel AI SDK and the JS agent ecosystem. Missing an adapter for your stack? Open an issue. Most adapters are about a hundred lines.

Claude Code fires a PostToolUse hook after every tool call. Point it at halo hook and each action — file writes, shell commands, MCP connector calls — becomes a record in a local chain. No code changes; one settings entry:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

Add that to ~/.claude/settings.json and records land in ~/.halo/audit.jsonl (override with $HALO_LOG). Pure-orchestration tools that touch no data, network, or external state are skipped — the chain records trust-boundary actions, not thinking. Set HALO_HASH_ONLY=1 to record content hashes without summaries. Then, the usual:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

Any agent runtime that exposes a post-action hook can feed the same command — the hook reads one event as JSON on stdin and appends one record.

Integrity vs. completeness (read this part)

A self-held chain proves integrity : nothing was edited or reordered after the fact. It cannot prove completeness : the operator of a recorder can delete the bad day and re-seal the chain, or never write a record at all, and the chain stays internally consistent.

Completeness requires a party outside the operator's control holding periodic fingerprints of the chain (a count and a head hash, nothing else). That is the witness:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

Anyone can run a witness. A witness you run yourself proves integrity to you ; proving completeness to your customer requires a witness they have reason to trust. The protocol is open either way.

A hosted, recognized witness is how this project will sustain itself. Early access: bkuan001@gmail.com.

Where this sits in a compliance stack

halo-record is an evidence layer, not a certification. It produces the artifact that assessment frameworks keep asking for in different words:

• Security questionnaires and SOC 2 reviews: answer the AI sections with a verifiable Runtime Report instead of screenshots and prose.
• AIUC-1: continuous runtime evidence for agent-behavior requirements, instead of evidence reconstructed at audit time.
• OWASP (GenAI Security Project): the runtime evidence behind the agent-behavior risks in the OWASP Top 10 for LLM Applications and the Agentic Security Initiative — excessive agency, tool misuse, sensitive-information disclosure — recorded as what the agent actually did, with which tools and data.
• AARM (CSA): produces the tamper-evident action receipt AARM specifies (R5/R6) — chained and independently witnessed. halo-record is the receipt layer; pair it with an enforcement gateway for a full AARM system. See AARM.md.
• EU AI Act: logging and record-keeping obligations for high-risk AI systems.
• ISO 42001 / NIST AI RMF: the operational evidence behind management-system controls.

None of this certifies anything by itself. It gives your assessor something verifiable to look at.

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

To compute a record's hash: take the record excluding integrity.hash, with integrity.prev_hash set to the previous record's hash; canonicalize with RFC 8785 (JSON Canonicalization Scheme); SHA-256 the bytes. The first record's prev_hash is 64 zeros. Verification recomputes every hash and checks every link. No secret required; that is the point.

Think you can tamper with a chain without the verifier noticing? Attempts and results live here.

Full field reference: halo-record.schema.json.

The same recorder ships for Node: halo-record-ts. Same chain format, same witness protocol. Records written in either language verify with either verifier.

Apache-2.0