Tommy3714/ghostlog

# 👻 GhostLog **AI Agent 事件响应平台** 当你的 AI agent 在凌晨 3 点做出了错误的决定——删除了错误的记录、调用了错误的 API、执行了不可逆的操作——你会怎么做？ 现状：无能为力。没有回放，没有影响范围，没有回滚映射，没有应对方案。 **GhostLog** 为每个 AI agent 提供防篡改的决策日志、事件回放、影响范围计算器和告警系统。与框架无关。零必填配置。几分钟即可接入任何 Python agent。 ## 问题所在 组织部署 AI agent 的速度已经超过了他们对其进行治理的能力。每个服务账户、每个 API 密钥、每个工作流累积的操作，事后根本无人能审计。 GhostLog 正是缺失的基础设施层。 ## 功能 - **决策回放** —— 逐步展示 agent 为何做出该选择，包含每一步完整的输入/输出 - **哈希链审计追踪** —— 每一个操作都通过 SHA-256 与前一个操作链接；从设计上保证防篡改 - **影响范围计算器** —— 记录所有受影响的系统和资源，区分可逆与不可逆操作，支持按单次操作和单次事件统计 - **不可逆操作告警** —— 在 agent 执行不可撤销操作的瞬间触发（webhook + 控制台） - **事件声明与解决** —— 声明、回放、记录根本原因、标记为已解决 - **REST API** —— 完整的 FastAPI 接口，用于仪表盘、集成和告警流水线 - **与框架无关** —— 适配任何 Python agent：LangChain、Claude Code、n8n 以及自定义 agent - **零配置启动** —— 开箱即用支持 SQLite，生产环境可无缝接入 Postgres ## 快速开始 ``` pip install ghostlog ``` ``` from ghostlog import GhostTracer, RiskLevel tracer = GhostTracer(agent_id="my-agent") # Decorator style @tracer.trace(action_type="db_write", risk_level=RiskLevel.HIGH) async def write_record(data: dict) -> dict: ... # Context manager style — 完全控制 async with tracer.action("Delete user record", risk_level=RiskLevel.CRITICAL) as ctx: ctx.touch("postgres", "users", "DELETE", reversible=False) ctx.record_reasoning("User requested GDPR deletion") result = await db.delete(user_id) ctx.record_output(result) # 从当前会话声明 incident incident_id = tracer.declare_incident( title="Agent deleted wrong user", severity=RiskLevel.CRITICAL, ) ``` ## 运行示例 ``` git clone https://github.com/YOUR_USERNAME/ghostlog cd ghostlog pip install -e ".[dev]" python examples/basic_agent.py ``` ## REST API ``` uvicorn ghostlog.api.main:app --reload ``` | Endpoint | 描述 | |---|---| | `GET /incidents` | 所有已声明的事件 | | `GET /incidents/{id}/replay` | 逐步的决策回放 | | `GET /incidents/{id}/blast-radius` | 跨所有操作的完整影响范围 | | `POST /incidents/{id}/resolve` | 结合根本原因和解决方案进行处理 | | `GET /actions/high-risk` | 跨所有 agent 的高风险/严重操作 | | `GET /actions/{id}/blast-radius` | 单次操作的影响范围 | 交互式文档：`http://localhost:8000/docs` ## 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `GHOSTLOG_DB` | `~/.ghostlog/ghostlog.db` | SQLite 数据库路径 | | `GHOSTLOG_WEBHOOK_URL` | *(无)* | 用于告警的 Webhook URL | | `GHOSTLOG_ALERT_EMAIL` | *(无)* | 用于接收严重告警的邮箱 | ## 运行测试 ``` pytest tests/ -v ``` ## 路线图 - [ ] Postgres 后端 - [ ] 回滚执行器（自动撤销可逆操作） - [ ] PagerDuty / Slack / OpsGenie 集成 - [ ] Web 仪表盘 (React) - [ ] OpenTelemetry 导出 - [ ] 多 agent 会话追踪 (A2A) - [ ] LangChain / Claude Code 原生适配器 ## 贡献 欢迎提交 PR。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT

标签：API集成, AV绕过, FastAPI, Python, 可观测性, 审计日志, 无后门, 网络测绘, 逆向工具