dvcrn Agent Audit Trail
AI决策的不可篡改黑匣子 The Immutable Black Box for AI Decisions
追踪、审计和验证AI Agent决策，提供密码学保证。 Track, audit, and verify AI agent decisions with cryptographic guarantees.
🎯 概述 / Overview
Agent Audit Trail 是一个为AI决策提供密码学保证的审计追踪工具，可以记录、验证和审计AI Agent的每一个决策过程。
Agent Audit Trail is an audit trail system that provides cryptographic guarantees for AI decisions, enabling recording, verification, and auditing of every AI Agent decision process.
核心特性 / Core Features
- 🔗 密码学链条 - SHA-256哈希链确保不可篡改 / Cryptographic chain with SHA-256 hashing ensures immutability
- 📝 完整记录 - 捕获输入、推理、输出全过程 / Complete recording of input, reasoning, and output
- ✅ 完整性验证 - 自动检测任何篡改行为 / Integrity verification detects any tampering
- 📊 多格式导出 - JSON、CSV、HTML、Markdown / Multiple export formats
- ⚡ CLI和API - 命令行和编程接口双重支持 / Both CLI and programmatic interfaces
- 🔐 本地存储 - 所有数据存储在本地，无外部依赖 / All data stored locally, no external dependencies
📦 安装 / Installation
NPM (推荐 / Recommended)
# 全局安装 / Install globally
npm install -g openclaw-audit-trail
# 或项目依赖 / Or as project dependency
npm install openclaw-audit-trail
ClawHub
clawhub install openclaw-audit-trail
从源码 / From Source
git clone https://github.com/ZhenRobotics/openclaw-audit-trail.git
cd openclaw-audit-trail
npm install
npm link
🚀 快速开始 / Quick Start
初始化 / Initialize
# 初始化审计追踪 / Initialize audit trail
audit-trail init --agent-id my-ai-agent --version 1.0.0
# 或使用别名 / Or use alias
aat init --agent-id my-agent
记录决策 / Record Decisions
# 简单记录 / Simple recording
audit-trail record \
--prompt "Should I approve this loan?" \
--decision "Approved" \
--reasoning "Credit score 750, income verified, debt ratio acceptable"
# 带更多细节 / With more details
audit-trail record \
--prompt "Classify this image" \
--decision "cat" \
--reasoning "Detected feline features with 95% confidence" \
--agent-id vision-classifier
验证完整性 / Verify Integrity
# 验证审计链 / Verify audit chain
audit-trail verify
# 预期输出 / Expected output:
# ✓ Chain integrity intact
# Total entries: 42
# Verified: 42/42
列出决策 / List Decisions
# 列出最近的决策 / List recent decisions
audit-trail list --limit 10
# 按时间过滤 / Filter by time
audit-trail list --start 1700000000 --end 1700100000
导出审计追踪 / Export Audit Trail
# 导出为JSON / Export as JSON
audit-trail export --output audit-report.json --format json
# 导出为HTML报告 / Export as HTML report
audit-trail export --output audit-report.html --format html --include-reasoning
# 导出为CSV / Export as CSV
audit-trail export --output audit-data.csv --format csv
💻 编程使用 / Programmatic Usage
TypeScript/JavaScript API
import { AgentAuditTrail } from 'openclaw-audit-trail';
// 初始化 / Initialize
const trail = new AgentAuditTrail({
agentId: 'my-ai-agent',
agentVersion: '1.0.0',
storagePath: './audit-data'
});
await trail.initialize();
// 记录决策 / Record a decision
const entry = await trail.recordDecision(
// 输入 / Input
{
prompt: 'Should I send this email?',
context: { urgency: 'high', recipient: 'user@example.com' }
},
// 推理 / Reasoning
{
steps: [
{
step: 1,
action: 'analyze',
thought: 'Checking email content for sensitive information',
timestamp: Date.now()
},
{
step: 2,
action: 'decide',
thought: 'No sensitive data detected, urgency is high',
timestamp: Date.now()
}
],
model: 'gpt-4',
temperature: 0.7
},
// 输出 / Output
{
decision: 'send',
confidence: 0.95,
alternatives: [
{ decision: 'delay', confidence: 0.05, reasoning: 'Wait for manual review' }
]
},
// 执行时间 / Execution time
1250
);
console.log(`Decision recorded: ${entry.id}`);
// 验证完整性 / Verify integrity
const verification = trail.verify();
if (!verification.valid) {
console.error('Chain compromised!', verification.errors);
}
// 导出 / Export
const htmlReport = await trail.export({
format: 'html',
includeMetadata: true,
includeReasoning: true
});
await trail.close();
简化版本 / Simplified Version
// 用于简单用例 / For simple use cases
const entry = await trail.recordSimple(
'What is 2+2?',
'4',
'Basic arithmetic calculation',
50 // execution time in ms
);
🎯 使用场景 / Use Cases
1. AI安全与合规 / AI Safety & Compliance
场景 / Scenario: 金融机构使用AI进行贷款审批 / Financial institution using AI for loan approvals
await trail.recordDecision(
{
prompt: 'Approve loan application #12345',
context: { creditScore: 720, income: 80000, debtRatio: 0.3 }
},
{
steps: [
{ step: 1, action: 'evaluate', thought: 'Checking credit score threshold' },
{ step: 2, action: 'analyze', thought: 'Debt-to-income ratio acceptable' },
{ step: 3, action: 'decide', thought: 'All criteria met for approval' }
]
},
{
decision: 'approved',
confidence: 0.92,
metadata: { loanAmount: 50000, interestRate: 0.045 }
},
2300
);
好处 / Benefits: 完整的监管合规审计追踪，能够向客户解释决策 / Full audit trail for regulatory compliance, ability to explain decisions to customers
2. 自主系统 / Autonomous Systems
场景 / Scenario: 自动驾驶汽车决策日志 / Self-driving car decision logging
await trail.recordDecision(
{
prompt: 'Pedestrian detected crossing street',
context: { speed: 35, distance: 50, weather: 'clear' }
},
{
steps: [
{ step: 1, action: 'detect', thought: 'Pedestrian at 50m ahead' },
{ step: 2, action: 'calculate', thought: 'Stopping distance: 35m' },
{ step: 3, action: 'decide', thought: 'Initiate emergency brake' }
]
},
{ decision: 'emergency_brake', confidence: 1.0 },
120
);
好处 / Benefits: 事故调查黑匣子记录，安全分析 / Black box recording for accident investigation, safety analysis
3. 内容审核 / Content Moderation
场景 / Scenario: AI审核用户生成内容 / AI moderating user-generated content
await trail.recordDecision(
{
prompt: 'Moderate comment: "..."',
context: { userId: 'user123', platform: 'forum' }
},
{
steps: [
{ step: 1, action: 'scan', thought: 'Checking for hate speech patterns' },
{ step: 2, action: 'analyze', thought: 'Detected potential violation' }
]
},
{
decision: 'flag_for_review',
confidence: 0.75,
metadata: { violationType: 'potential_hate_speech' }
},
850
);
好处 / Benefits: 用户透明度，政策执行的证据 / Transparency for users, evidence for policy enforcement
4. 研究与开发 / Research & Development
场景 / Scenario: 调试AI Agent行为 / Debugging AI agent behavior
# 查找所有失败的决策 / Find all failed decisions
audit-trail list --limit 100 | grep "failed"
# 导出上周的决策用于分析 / Export last week's decisions for analysis
audit-trail export --output weekly-decisions.json \
--start $(date -d '7 days ago' +%s) \
--format json --include-reasoning
# 验证未发生篡改 / Verify no tampering occurred
audit-trail verify
好处 / Benefits: 可重现的实验，决策模式分析 / Reproducible experiments, decision pattern analysis
🏗️ 架构 / Architecture
┌─────────────────────────────────────────┐
│ CLI / API Layer │
│ (User Interface & Integration) │
└──────────────┬──────────────────────────┘
│
┌──────────────▼──────────────────────────┐
│ AgentAuditTrail (Main API) │
│ - Record decisions │
│ - Query & export │
│ - Verification │
└──────────────┬──────────────────────────┘
│
┌──────────┴──────────┐
│ │
┌───▼──────────┐ ┌──────▼─────────┐
│ AuditChain │ │ Storage Layer │
│ │ │ │
│ - Hash chain │ │ - JSON files │
│ - Integrity │ │ - SQLite │
│ - Verify │ │ - PostgreSQL │
└──────────────┘ └────────────────┘
🔐 安全性 / Security
密码学保证 / Cryptographic Guarantees
- SHA-256哈希 - 工业标准加密哈希 / Industry-standard cryptographic hash
- 链式关联 - 每个条目引用前一个哈希 / Each entry references previous hash
- 篡改检测 - 任何修改立即可检测 / Any modification is immediately detectable
- 创世哈希 - 唯一链标识符 / Unique chain identifier
数据隐私 / Data Privacy
- ✅ 本地存储 - 所有数据存储在本地文件系统 / All data stored locally
- ✅ 无外部传输 - 不连接任何外部服务器 / No external server connections
- ✅ 用户控制 - 完全由用户控制数据 / User has full control of data
- ✅ 可删除 - 用户可随时删除审计数据 / Users can delete audit data anytime
📊 技术规格 / Technical Specifications
- 语言 / Language: TypeScript
- Node.js版本 / Version: >= 18.0.0
- 加密算法 / Crypto: SHA-256
- 存储格式 / Storage: JSON (SQLite, PostgreSQL planned)
- 导出格式 / Export: JSON, CSV, HTML, Markdown
- 测试覆盖 / Test Coverage: 100% (25/25 tests passing)
📝 CLI 命令参考 / CLI Command Reference
init - 初始化 / Initialize
audit-trail init --agent-id <id> [--version <ver>] [--storage-path <path>]
record - 记录决策 / Record Decision
audit-trail record \
--prompt <text> \
--decision <text> \
--reasoning <text> \
[--agent-id <id>]
verify - 验证完整性 / Verify Integrity
audit-trail verify [--agent-id <id>]
list - 列出决策 / List Decisions
audit-trail list [--limit <n>] [--start <timestamp>] [--end <timestamp>]
export - 导出数据 / Export Data
audit-trail export \
--output <file> \
--format <json|csv|html|markdown> \
[--include-reasoning]
info - 显示信息 / Show Information
audit-trail info [--agent-id <id>]
🗺️ 路线图 / Roadmap
v1.1 (即将推出 / Coming Soon)
- SQLite 存储后端 / SQLite storage backend
- PostgreSQL 存储后端 / PostgreSQL storage backend
- 数字签名支持 / Digital signature support
- 压缩支持 / Compression support
- Web 仪表板 / Web dashboard
v1.2 (未来 / Future)
- 区块链集成 / Blockchain integration
- 实时流API / Real-time streaming API
- 高级分析 / Advanced analytics
- 多Agent支持 / Multi-agent support
🐛 常见问题 / FAQ
Q: 如何确保审计数据不被篡改？ / How to ensure audit data cannot be tampered with?
A: 使用密码学哈希链。每个条目包含前一条目的SHA-256哈希，任何修改都会破坏链条。定期运行 audit-trail verify 检测篡改。
A: Use cryptographic hash chain. Each entry contains the SHA-256 hash of the previous entry. Any modification breaks the chain. Run audit-trail verify regularly to detect tampering.
Q: 审计数据存储在哪里？ / Where is audit data stored?
A: 默认存储在 ./audit-data 目录。可通过 --storage-path 参数或环境变量 STORAGE_PATH 自定义。
A: Stored in ./audit-data directory by default. Customizable via --storage-path parameter or STORAGE_PATH environment variable.
Q: 支持分布式审计吗？ / Does it support distributed auditing?
A: 当前版本(v1.0.0)支持本地文件存储。未来版本将支持SQLite、PostgreSQL和区块链集成。
A: Current version (v1.0.0) supports local file storage. Future versions will support SQLite, PostgreSQL, and blockchain integration.
📞 支持 / Support
- GitHub Issues: https://github.com/ZhenRobotics/openclaw-audit-trail/issues
- 文档 / Documentation: https://github.com/ZhenRobotics/openclaw-audit-trail#readme
- Email: support@zhenrobotics.com
📄 许可证 / License
MIT License - 查看 LICENSE 文件了解详情。
MIT License - see LICENSE file for details.
以透明为理念构建。让AI决策可审计、可信任。 Built with transparency in mind. Make AI decisions auditable and trustworthy.
🔗 GitHub: https://github.com/ZhenRobotics/openclaw-audit-trail 📦 NPM: https://www.npmjs.com/package/openclaw-audit-trail 🦅 ClawHub: https://clawhub.ai/ZhenStaff/openclaw-audit-trail
版本 / Version: 1.0.0 最后更新 / Last Updated: 2026-03-13 状态 / Status: ✅ Production Ready