tborys/driftshield

# DriftShield 找出 AI Agent 首次出错的位置。 DriftShield 是一个用于 AI 工作流的开源失败运行调查工具。当运行中断时，团队通常只能依赖日志、链路追踪和猜测。DriftShield 会将运行过程重构为决策图，突出显示推理首次发生偏移的位置，并将失败转化为人类可检查的报告。 随着团队从单一 Prompt 向多步骤的 Agentic 工作流转变， failures 变得越来越难以解释。一个工作流可能遵循了正确的步骤，但仍然产生了错误的结果；可能承认了一个约束，随后又忽略了它；或者在不同的运行中表现得不一致。 OSS 核心专注于一次分析一个失败的运行。它帮助团队解释发生了什么，检查运行在哪里中断，识别该运行中已知的故障机制，并生成一个用于调试、审查和后续跟进的调查级产物。 可选的私有路径丰富功能可以在团队明确启用时，添加更丰富的单次运行分析。更广泛的重复追踪和组织级别的优先级排序是后续的产品层，而不是捆绑的 OSS 保证。 ## 为什么选择 DriftShield - 从原始日志和链路追踪转向可检查的失败调查 - 查看工作流在哪里中断以及运行是如何偏离正轨的 - 识别单个失败运行中的已知故障机制 - 为工程师和产品团队提供用于调试和审查的共享产物 ## 适用对象 - 构建多步骤或 Agentic 工作流的 AI 工程师 - 发布 AI 驱动功能的产品团队 - 注重可靠性和正确性的团队 ## 演示 ## 支持的来源 | 来源 | 格式 | 状态 | |--------|--------|--------| | Claude Code | JSONL | 稳定版 | | Claude Desktop | JSON | 实验性 | | Codex CLI | JSONL | 实验性 | | Codex Desktop | JSON | 实验性 | | OpenClaw | JSONL | 实验性 | DriftShield 使用解析器协议。只需实现单一接口即可添加新的来源。 ## 社区签名包 OSS 仓库支持一种刻意简化的拉取流程，用于获取社区安全的签名包。这些包是遵循公共契约的版本化 JSON 清单，可以直接从 Git ref 或 tag 获取。 示例： ``` source .venv/bin/activate driftshield signatures pull community-general --ref ``` 默认情况下，这会从 `tborys/driftshield` 拉取，并将验证后的清单存储在 `~/.local/share/driftshield/signatures///` 下。 如果你需要测试或镜像包的来源，可以直接覆盖来源 URL： ``` driftshield signatures pull community-general \ --ref local-smoke \ --url http://127.0.0.1:8000/community-general.json ``` 当前 OSS 拉取路径的兼容性规则： - `schema_version` 是兼容性门槛，在安装前会进行验证 - `pack_metadata.version` 是包的发布版本，决定了安装路径 - OSS 拉取路径仅接受 `pack_kind: community` - 该拉取流程是有意设计的，未来可在不将 DriftShield 绑定到特定市场设计的情况下进行替换 ## OSS 范围和产品边界 这个公共仓库是 OSS 的识别和调查层。 它包括： - 解析和摄入记录 - 单次运行调查和报告 - 社区签名包支持 - 用于失败运行分析的公共安全仪表板、CLI 流程和 API 路径 它本身并不承诺提供： - 受控的跨运行重复追踪 - 组织级别的优先级排序或排名 - 治理、保证或企业工作流策略层 如果公共文档中的某句话听起来像是关于跨运行重复情况或整个组织中最重要事项的捆绑承诺，那么它就超出了此 OSS 层的范围。 ## 快速开始 ### 前置条件 - Python 3.12+ - Node.js 20+ - Docker（可选，但本地 API/仪表板 Postgres 路径需要） ### 1. 从干净的克隆开始设置 ``` git clone https://github.com/tborys/driftshield.git cd driftshield ./scripts/dev-setup.sh ``` 这将创建本地环境文件，安装后端和前端依赖，并在 Docker 可用时启动本地 Postgres。OSS 路径不需要私有凭据或专有的设置步骤。 ### 2. 获取第一个有用的结果 ``` cd driftshield source .venv/bin/activate driftshield report tests/fixtures/transcripts/sample_claude_code_session.jsonl --type summary ``` 这将从捆绑的样本记录生成一份取证报告，这是从干净的克隆到生成有意义的 DriftShield 调查产物的最短支持路径。 ### 3. 验证仓库 ``` cd .. ./scripts/dev-verify.sh ``` ### 4. 运行完整的本地技术栈 API 摄入流程和 Web 仪表板需要一个本地 Postgres 实例。受支持的开发路径是 `docker-compose.dev.yml`；用于生产的 `docker-compose.yml` 不是主要的快速启动路径。 启动后端： ``` cd driftshield source .venv/bin/activate set -a source .env set +a driftshield-api ``` 后端从进程环境中读取 `API_KEY` 和 `DATABASE_URL`，因此在启动前请先执行 `source driftshield/.env`。 启动前端（在单独的终端中）： ``` cd driftshield/frontend npm run dev ``` 打开 http://localhost:5173 查看已摄入的会话。 ### 5. 将记录摄入到本地 API ``` cd driftshield source .venv/bin/activate set -a source .env set +a DRIFTSHIELD_API_URL=http://localhost:8080 \ driftshield ingest --path tests/fixtures/transcripts/sample_claude_code_session.jsonl ``` 或者摄入当前项目的最新 Claude Code 会话： ``` set -a source .env set +a source .venv/bin/activate driftshield ingest --latest ``` ### 通过 API 生成取证报告 在后端运行并从 `driftshield/.env` 导出 `API_KEY` 的情况下，直接将记录上传到 API，并在一次调用中获取持久化的 `forensic_report.v1` payload： ``` cd driftshield source .venv/bin/activate set -a source .env set +a curl -sS \ -X POST http://localhost:8080/api/forensics/report \ -H "X-API-Key: $API_KEY" \ -F "file=@tests/fixtures/transcripts/sample_claude_code_session.jsonl" \ -F "format=claude_code" \ -F "report_type=summary" ``` 这将返回已摄入的 `session_id`、持久化的取证案例元数据，以及 CLI 和仪表板界面共享的完整 JSON 报告契约。 ## 工作原理 ``` Transcript → Parser → Canonical Events → Decision Graph → Risk Heuristics → Report ``` 1. **解析器** 读取原始记录并生成一系列规范事件（工具调用、输出、分支、交接、假设、约束检查） 2. **图构建器** 将事件连接成具有父子关系的决策树 3. **风险启发式算法** 扫描每个节点以查找失败模式 4. **拐点检测** 对会话中 Agent 轨迹发生变化的点进行评分 5. **报告** 以 Markdown、JSON 或通过 Web 仪表板的形式展示调查结果 ## 内置风险检测器 | 检测器 | 捕获内容 | |----------|----------------| | Coverage Gap (覆盖缺口) | 输出引用的项目少于输入提供的项目 | | Assumption Mutation (假设突变) | 步骤之间的假设在未经确认的情况下发生了变化 | | Policy Divergence (策略偏离) | Agent 行为与先前声明的约束相矛盾 | | Constraint Violation (约束违规) | 显式约束被检查后被忽略 | | Context Contamination (上下文污染) | 来自一个上下文的信息泄漏到不相关的决策中 | 风险检测器是可叠加的。每个检测器都实现了一个 `RiskHeuristic` 接口，可以在不修改现有代码的情况下进行扩展。 ## CLI 参考 在执行 `source .venv/bin/activate` 之后，所有命令均在 `driftshield/` 目录下运行。 ``` # 导入 transcript 文件 driftshield ingest --path # 导入最新的 Claude Code session driftshield ingest --latest # 列出已导入的 session driftshield list # 分析 session 的风险信号 driftshield analyze # 检查 decision graph 中的特定 node driftshield inspect --node 0 # 生成报告 driftshield report # 从 CLI 生成 JSON report contract driftshield report --format json # 发现可用的 transcript 来源 driftshield connectors list ``` ## 技术栈 | 层级 | 技术 | |-------|-----------| | 后端 | Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, Pydantic | | CLI | Typer + Rich | | 前端 | React 19, TypeScript, Vite, Tailwind CSS 4, TanStack Query | | 图形可视化 | @xyflow/react | | 数据库 | PostgreSQL 16 (生产环境), 内存 SQLite (测试) | | 测试 | pytest (后端), Playwright (端到端), Vitest (前端单元) | | 基础设施 | Docker, docker-compose, GitHub Actions | ## 项目结构 ``` driftshield/ ├── src/driftshield/ │ ├── api/ # FastAPI routes (ingest, sessions, reports, connectors) │ ├── cli/ # Typer commands and session discovery │ ├── connectors/ # Auto-discovery of transcript sources │ ├── core/ │ │ ├── analysis/ # Risk heuristics, inflection detection, session analysis │ │ ├── graph/ # Decision graph builder and models │ │ └── models.py # Domain models (CanonicalEvent, RiskClassification) │ ├── db/ # SQLAlchemy models, persistence, Alembic migrations │ ├── parsers/ # Transcript format parsers (protocol + implementations) │ └── reports/ # Jinja2 report templates ├── frontend/ # React investigation dashboard ├── tests/ # Backend test suite └── docker-compose.yml # Production deployment ``` ## Docker 部署 ``` cd driftshield # 使用所需值创建 .env cp .env.example .env # 编辑 .env：设置 API_KEY 和 DB_PASSWORD # 启动 stack docker compose up -d ``` 生产环境的 compose 文件使用 PostgreSQL 16 在端口 8080 上运行应用。`API_KEY` 和 `DB_PASSWORD` 均为必填项，如果缺失将在启动时失败。 ## 贡献 欢迎贡献。DriftShield 由 Tomasz Borys 创立并维护，Pull Request 的审查会考虑到这种创始人主导的 OSS 范围。请遵循以下步骤： 1. **Fork** 该仓库到您自己的 GitHub 账号 2. **克隆** 您 fork 的仓库到本地 3. 从 `main` 分支为您的更改**创建一个分支** 4. **进行更改**，并在适用的地方添加测试 5. 提交前**运行验证**： ./scripts/dev-verify.sh 6. 从您 fork 的分支向 `tborys/driftshield:main` **发起 Pull Request** 所有 Pull Request 均由 DriftShield 的创始人兼现任维护者 Tomasz Borys 审查和合并。不允许直接推送到 `main` 分支。 ### 代码风格 - Python: Ruff (行长 100)，MyPy strict，约定式提交 - TypeScript: ESLint 9 flat config，严格模式，禁止使用 `any` 类型 - 前端样式使用 Tailwind CSS ### 添加解析器 在 `src/driftshield/parsers/` 中实现 `ParserProtocol` 接口。每个解析器将原始记录格式转换为 `CanonicalEvent` 对象列表。请参阅 `claude_code.py` 获取参考实现。 ## 许可证 AGPL-3.0-or-later。请参阅 [LICENSE](./LICENSE)。

标签：Agent Drift, AI Engineering, AI Workflow, AI安全, AI对齐, AI工作流, AI调试, API集成, Chat Copilot, Claude, Codex, CVE检测, DLL 劫持, Forensic, LLM, OpenAI, Python, Reasoning Error, Unmanaged PE, 二进制发布, 内存规避, 决策图, 可观测性, 可视化分析, 可靠性工程, 多步推理, 大模型安全, 大语言模型, 开源工具, 故障排查, 数据库接管, 无后门, 根因分析, 溯源分析, 网络测绘, 请求拦截