saffronandindia/headlights-oss

# Headlights [](https://github.com/saffronandindia/headlights-oss/actions/workflows/ci.yml) **一份关于你的 AI agent 实际操作行为的防篡改记录。** 当 AI agent 犯错时（总会有一个犯错），部署它的机构几乎从来没有证据来重构该 agent 当时看到了什么、推断出了什么、做了什么，以及是谁授权的。飞机上有飞行记录仪。而生产环境中的 AI agent 却没有。Headlights 正是为填补这一空白而生。 它面向那些必须对生产环境中的 agent 负责的团队：包括构建它的开发者，以及作为其运作后盾的平台、风险和合规负责人。 在你的 agent 运行的 workflow 中安装 SDK，记录 agent 做出的每一个决策，并生成一个经过签名的、仅可追加的链。监管机构、法庭或客户的律师可以在几个月或几年后对其进行验证。开源，无供应商锁定，全程无专有审计员介入。 基于 [Agent Audit Trail 草案](https://datatracker.ietf.org/doc/draft-sharif-agent-audit-trail/) 构建，这是一份尚未被工作组采纳的 IETF 个人提案。采用 Apache 2.0 许可证。关于真实 AI agent 故障的配套实地记录发布在 [useheadlights.com](https://useheadlights.com)。 ## Packages | 路径 | 介绍 | | --- | --- | | [`chain/`](chain/) | 哈希链原语。ECDSA P-256 签名，仅可追加，防篡改。 | | [`sdk-python/`](sdk-python/) | Python SDK，用于从 agent 内部将行为记录写入链中。 | | [`verifier/`](verifier/) | 用于验证任何链导出文件的公开 CLI。无状态。无外部请求。 | | [`server/`](server/) | 参考用的 FastAPI 后端，用于托管链，并提供 trace-viewer endpoint。 | | [`dashboard-reference/`](dashboard-reference/) | 最小化的 Next.js 仪表板，从参考服务器读取数据。 | | [`scorecard/`](scorecard/) | AI 行为记分卡的静态评估标准。 | | [`specs/`](specs/) | 协议规范。包含链格式、决策、记分卡研究及评估标准。 | | [`marketing/`](marketing/) | 内部试用的 agents（发现、起草、上传）。它们在运行时自身也会被记录到 Headlights 链中。 | | [`examples/`](examples/) | 端到端演示。从这里开始入手。 | ## 快速开始 ``` # 从此 repo 的 checkout 开始： pip install -e ./chain ./sdk-python ./verifier ./server # 通过 SDK 生成签名的 conduct chain： python examples/loan_analyser_demo.py # 验证任何 chain export： headlights-verify path/to/chain.json ``` 五分钟即可获得你的第一个证明。 你的 agent 发起的每一次调用都会成为一条*行为记录*：一条经过签名且带有时间戳的条目，用于捕获模型版本、输入、输出和结果。这些记录在每个 session 中链接成一条防篡改的链，这就是以下防护组件所写入并由 verifier 检验的内容。 ## 治理防护组件 在原始记录 API 之上，SDK 提供了一层轻量级的、具名的**治理防护组件**（governance guards）：执行前后的检查，每一项都会将其决策记录为有效的 AAT 记录。它们将 [Headlights 事件库](https://useheadlights.com/library) 中记录的失败模式转换为你可运行的代码。共计八个模块，分为两层。 **记录层**（在操作发生后写入）：`ConductRecord`、`MetricRecord`。 **网关层**（在操作发生前按顺序执行）：`AuthorityGate`、`ConstraintGate`、`PersonaGuard`、`CitationVerifier`、`VerificationGate`、`EgressGate`。 这八个模块现已全部发布，遵循相同的轻量级模式：没有引入新的加密方式，也没有新的记录格式，只是一些委托给该链的具名检查。在该工具包中，之前没有对应物的两个组件是 **AuthorityGate**（指令的来源是否有权约束该 agent？）和 **EgressGate**（是否有敏感数据正在离开信任边界？）。 ``` from headlights_sdk import Client from headlights_sdk.guards import AuthorityGate, EgressGate client = Client(agent_id="urn:org:agent", agent_version="1.0.0") # 拒绝来自未授权绑定 agent 的源的指令。 AuthorityGate(client, authorised_sources={"urn:org:ops-console"}).enforce( source="urn:org:ops-console", instruction="run payroll" ) # 阻止敏感数据离开 trust boundary。 EgressGate( client, trusted_destinations={"https://internal.corp"}, sensitive_patterns={"aws_key": r"AKIA[0-9A-Z]{16}"}, ).enforce(content=reply, destination="https://partner.example") ``` 完整详情请见[防护组件 README](sdk-python/headlights_sdk/guards/README.md)，实时模块介绍位于 [useheadlights.com/code](https://useheadlights.com/code)。 ## 状态 发布前的 Alpha 版本 (v0.1.0a1)。哈希链原语、验证器 CLI、SDK（包括新增的治理防护层）、参考服务器、记分卡评估标准以及内部试用的营销 pipeline 均已具备功能，并由测试套件覆盖。托管平台、Web 仪表板的界面优化以及 PyPI 发布仍待后续进行。 与 [Agent Audit Trail 草案](https://datatracker.ietf.org/doc/draft-sharif-agent-audit-trail/) 保持一致，这是一份尚未被工作组采纳的 IETF 个人提案。协议详情请参阅 [`specs/chain.md`](specs/chain.md) 和 [`specs/decisions.md`](specs/decisions.md)，行为记分卡请参阅 [`specs/scorecard-rubric.md`](specs/scorecard-rubric.md)。 ## 运行测试 ``` # 以 editable 模式安装所有内容，以便 packages 能够相互看到 pip install -e ./chain ./sdk-python ./verifier ./server # 从 repo 根目录运行完整套件 PYTHONPATH=chain:sdk-python:verifier:server:. python -m pytest -q ``` ## 安全 如果你发现漏洞，请遵循 [SECURITY.md](SECURITY.md) 中的披露流程。请勿针对安全漏洞提交公开的 GitHub issue。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 ## 许可证 Apache 2.0，版权所有 Stellae Consulting Pty Ltd。请参阅 [LICENSE](LICENSE)。

标签：人工智能, 合规追踪, 哈希链, 智能体审计, 用户模式Hook绕过, 逆向工具, 防篡改