核心用法
Agent Audit Trail 是一套面向 AI 代理的审计日志基础设施，采用只追加（append-only）、哈希链式（hash-chained）设计，确保每一条代理操作、工具调用、决策和外部写入都可被完整追溯且不可篡改。
日志结构与存储
- 存储位置:
audit/atlas-actions.ndjson，NDJSON 格式，每行一个独立 JSON 对象 - 链式完整性: 每条记录包含
prev_hash（前一条哈希）和hash（自身 SHA256），形成加密链条 - 单调序列:
ord字段确保严格时序，防止重排 - 时区规范: 强制 Europe/London ISO-8601 格式带偏移量
关键字段体系
| 维度 | 字段 | 说明 |
|------|------|------|
| 时间 | `ts` | 带时区的 ISO-8601 时间戳 |
| 分类 | `kind`, `plane`, `gate` | 事件类型、四平面模型、真值门 |
| 身份 | `actor`, `provenance` | 执行主体与来源会话 |
| 影响 | `target`, `summary` | 操作对象与可读描述 |
| 完整性 | `ord`, `prev_hash`, `hash` | 序列号与哈希链 |
事件类型覆盖
涵盖 tool-call（工具调用）、external-write（外部写入）、credential-access（凭据访问）、decision（决策）、payment（支付）等 11 种核心事件，完整映射代理生命周期。
集成方式
1. 目录初始化: mkdir -p audit && touch audit/atlas-actions.ndjson
2. TOOLS.md 配置: 声明审计日志路径、格式与字段规范
3. SOUL.md 约束: 将"只追加哈希链审计日志"纳入系统不变量
4. Python 辅助脚本: audit_append.py 提供完整的追加、哈希计算、链验证功能
链完整性验证
内置验证脚本可检测：
- 哈希计算不匹配（记录被篡改）
prev_hash断裂（链条断裂）- 输出
Chain OK — {n} entries verified或精确报错位置
显著优点
| 优势 | 说明 |
|------|------|
| **法规合规** | 原生实现 EU AI Act Article 12 高风险 AI 系统自动事件记录要求，2026 年 8 月强制生效 |
| **防篡改设计** | SHA256 哈希链使任何单条记录修改都会导致后续所有哈希失效，检测概率 100% |
| **最小依赖** | 纯 Python 标准库实现，无外部依赖，MIT-0 许可证零限制 |
| **四平面模型** | 创新性地将事件映射到 `ingress`/`interpretation`/`decision`/`action` 四平面，便于安全分析 |
| **真值门集成** | 与 SOUL.md 真值门体系对齐，如 `external-write` 门要求 provenance + intent + approval + tool-log + ordering |
| **支付原生支持** | 内置 `payment` 事件类型，直接支持 ACTP/x402 等 AI 代理支付场景的审计追踪 |
| **可扩展性** | NDJSON 格式便于流式处理、分片存储、与现有日志基础设施（ELK、BigQuery 等）集成 |
潜在缺点与局限性
| 局限 | 说明 |
|------|------|
| **本地存储风险** | 默认单节点本地文件存储，面临磁盘故障、误删除、勒索软件风险；需配合远程备份（v2.1+ 计划 S3/GCS 只追加写入） |
| **无实时告警** | 当前版本仅提供事后验证，缺乏实时异常检测、阈值告警、SIEM 集成 |
| **无访问控制** | 文件系统级权限依赖，缺乏字段级加密、细粒度 RBAC、审计员隔离机制 |
| **查询能力有限** | 原生仅支持线性扫描，复杂过滤、聚合需外部工具；v2.1+ 计划 `export`/`stats` 命令 |
| **时区硬编码** | Europe/London 时区为默认，全球化部署需手动调整偏移量计算 |
| **JSON Schema 待发布** | 当前为文档级规范，v2.1+ 将提供正式 `audit/log-schema.json` 用于 CI 验证 |
| **合规报告手工** | Article 12 结构化报告模板计划 v2.1+ 发布，当前需自行组装 |
适合人群
- 高风险 AI 系统开发者: 需满足 EU AI Act 合规要求的高风险系统（关键基础设施、HR 决策、执法辅助、移民/庇护决策等）
- AI 代理运营方: 运行多租户、多域代理系统，需跨域操作追溯与责任界定
- 金融科技 AI 团队: 涉及 ACTP/x402 链上支付的代理，需支付事件与链上交易的双向审计
- 企业合规官: 需向监管机构提供不可篡改的系统操作证据
- 安全审计员: 需要哈希链完整性验证作为独立审计依据
常规风险
| 风险类别 | 具体风险 | 缓解建议 |
|----------|----------|----------|
| **可用性** | 日志文件持续增长导致磁盘耗尽 | 设置 logrotate 或按域/时间分片；监控磁盘水位 |
| **保密性** | `provenance`、`summary` 可能包含敏感会话 ID、用户输入 | 字段级加密或 tokenization；限制审计文件访问权限（0400） |
| **完整性** | 攻击者获取 root 后可直接删除/截断日志文件 | 启用 append-only 文件属性（`chattr +a` Linux）；尽快启用远程只追加存储 |
| **不可否认性** | 单一代理同时充当记录者与验证者，缺乏第三方见证 | 定期将哈希锚定到公共区块链或独立见证服务；多人审批关键操作 |
| **误用** | 代理未正确调用 `append()` 导致事件遗漏 | TOOLS.md + SOUL.md 强制约束；CI 检查代码中 `external-write` 等门必须伴随日志调用 |
| **合规缺口** | 仅记录不等于合规，需配套风险评估、人工验证、留存策略 | 强制前置运行 `agent-self-assessment` 确定风险分级；建立季度复评机制 |