Dossier：为Agentic工作流打造防篡改审计日志系统

Dossier是一个基于JSONL的轻量级审计日志工具，专为多Agent协作场景设计，提供SHA-256哈希链、PII令牌化、GDPR合规的隐私擦除等核心能力。

• 原作者/维护者：stefanhoth
• 来源平台：github
• 原始标题：dossier
• 原始链接：https://github.com/stefanhoth/dossier
• 来源发布时间/更新时间：2026-06-01T08:45:56Z

原作者与来源

• 原作者/维护者：stefanhoth
• 来源平台：github
• 原始标题：dossier
• 原始链接：https://github.com/stefanhoth/dossier
• 来源发布时间/更新时间：2026-06-01T08:45:56Z 原作者与来源\n\n- 原作者/维护者: stefanhoth\n- 来源平台: GitHub\n- 原始标题: dossier\n- 原始链接: https://github.com/stefanhoth/dossier\n- 发布时间: 2026-05-30\n- 更新时间: 2026-06-01\n\n为什么Agentic工作流需要审计日志？\n\n随着大型语言模型（LLM）能力的不断提升，AI Agent已经从单一任务执行者演变为能够自主协作、链式调用的智能体网络。在这种多Agent协作的场景中，一个编排器（Orchestrator）可能调用子Agent，子Agent又可能触发数据库写入、邮件发送或部署操作。当系统出现问题时，开发者需要回答三个关键问题：发生了什么？谁对谁说了什么？我能信任这份记录吗？\n\n传统的应用日志往往只记录"某个函数被调用了"，但在Agentic工作流中，我们需要更细粒度的追踪：Agent A何时将任务委托给Agent B？B返回了什么结果？整个调用链的上下文如何传递？更重要的是，当Agent处理敏感数据时，如何既保留审计线索，又满足GDPR等隐私法规的要求？\n\nDossier的核心设计理念\n\nDossier项目围绕一个核心原则构建：当自主Agent代表你或彼此采取行动时，你需要一份可以信任的记录。它实现了Agent Data Format Spec v2.0规范，采用仅追加（append-only）的JSONL格式存储事件，并通过密码学手段确保日志的不可篡改性。\n\n项目的命名本身就很形象——"dossier"在法语中意为"档案"，暗示每个Agent都会留下一份可追溯的纸质档案。这种设计哲学与区块链的不可篡改账本有异曲同工之妙，但更加轻量和实用。\n\n防篡改的哈希链机制\n\nDossier最核心的技术特性是其基于SHA-256的哈希链（Hash Chain）设计。每条事件记录都包含以下元数据字段：\n\n- seqNo: 序列号，标识事件在链中的位置\n- prevHash: 前一条记录的SHA-256哈希值（首条记录为"genesis"）\n- eventId: UUID v4唯一标识符\n- traceId: 用于将同一工作流中的所有事件分组\n- timestamp: ISO 8601格式的时间戳\n\n这种设计意味着任何对历史记录的篡改——哪怕只是修改一个字节——都会破坏哈希链的连续性。dossier verify命令可以检测出这种篡改，为合规审计提供技术保障。这种机制类似于Git的提交哈希，但针对事件日志场景做了专门优化。\n\nGDPR合规的隐私保护方案\n\nAgent经常需要处理个人身份信息（PII），这在带来便利的同时也引入了合规风险。Dossier提供了一套完整的PII令牌化（Tokenization）方案：\n\n1. 数据分离存储: PII数据被替换为tok_<hex>格式的令牌，实际数据存储在独立的side-store中\n2. 密码学擦除: 通过dossier privacy shred <subject>命令，可以删除特定用户的所有PII数据\n3. 审计链完整性: 删除操作不会破坏日志链，令牌引用保留在日志中，证明记录曾存在但不暴露实际数据\n\n这种"crypto-shredding"技术巧妙地平衡了审计需求与隐私权，是GDPR"被遗忘权"的技术实现范例。\n\n多场景应用实践\n\nDossier的设计使其适用于多种实际场景：\n\nAgent间通信审计: 当Agent A将任务委托给Agent B时，双方都在共享日志中追加事件。traceId将单次工作流的所有事件分组，seqNo和prevHash确保序列的不可篡改性。审核者可以使用dossier read --trace <id>完整回放特定工作流的执行过程。\n\n自动化管道可观测性: 记录管道各步骤的每个action/status对，支持通过时间范围导出合规报告包。\n\n模式版本管理: 随着Agent协议演进，dossier migrate支持向前迁移旧日志文件（v1 → v2），dossier schema管理Draft → Active → Deprecated → Sunset的生命周期，确保旧版本读取器保持兼容。\n\n快速上手与工具链\n\nDossier提供零安装体验，可直接通过npx使用：\n\nbash\n初始化工作空间\nnpx @stefanhoth/dossier init\n\n写入事件（如编排器委托给子Agent）\necho '{\"action\":\"delegate\",\"status\":\"completed\",\"agent\":\"planner\",\"_meta\":{\"traceId\":\"wf-001\"}}' | npx @stefanhoth/dossier write\n\n验证链完整性\nnpx @stefanhoth/dossier verify events/$(date +%Y-%m-%d).jsonl\n\n\n项目还提供了Claude Code技能（Skill），通过npx skills add stefanhoth/dossier安装后，Claude Code可以自动学习何时以及如何记录Agent事件，包括Agent间交接模式和审计工作流。\n\n技术架构与扩展性\n\nDossier采用模块化架构，当前支持文件后端存储，PostgreSQL后端已预留接口。配置通过dossier.config.yaml管理，支持热存储保留期设置、隐私功能开关等。\n\n事件格式强制要求包含_meta.schemaVersion、timestamp、traceId、seqNo、prevHash以及顶层的action和status字段，这种约束确保了跨工具互操作性。\n\n结语：信任是Agentic系统的基石\n\n在AI Agent日益自主化的今天，可审计性（Auditability）将成为区分玩具原型与生产级系统的关键特性。Dossier用不到千行代码实现了一个生产可用的审计日志方案，其设计哲学——"每个Agent都留下纸质档案"——值得所有构建Agent系统的开发者深思。\n\n对于正在构建多Agent系统的团队，Dossier提供了一个立即可用的审计基础设施，让你可以专注于业务逻辑，而将"信任"交给密码学保障。