mystiquemide/zeltho

# Zeltho **一个用于区块链基础设施的自主事件响应 agent —— 检测异常，使用 Qwen Cloud 诊断根本原因，提出排序后的修复方案，并在采取行动前等待人工批准。** 专为 **Qwen Cloud Global AI Hackathon**（赛道 4：Autopilot Agent）而构建。 [](https://nextjs.org) [](https://www.python.org) [](https://fastapi.tiangolo.com) [](https://soliditylang.org) [](LICENSE)  ## 为什么开发这个项目 区块链基础设施总是在没人值守的时段发生故障。在 2025 年，因链上攻击造成的损失高达 34 亿美元，平均检测时间以小时计，而非秒级。虽然存在自动修复机制，但大多数都是黑盒——运维人员无法看到*为什么*选择某个修复方案，这使得全面自动化对于处理真实资金的系统来说难以被接受。 Zeltho 运行完整的闭环——**检测 → 诊断 → 修复 → 批准 → 执行**——并且每次都会在批准环节停止。它会解释其推理过程，提出带有风险评分的排序方案，并且只有在人类签字确认后才会执行。 ## 界面预览 | 诊断，带有实时的链上依据 | 实时系统健康状态 | |---|---| |  |  | ## 核心功能 - **五阶段 pipeline** —— 一个区块链事件将转化为经过诊断、解释、人类批准并执行的修复方案，每一步都有日志记录。 - **五个不同的 Qwen Cloud 模型** —— 使用 `qwen3.6-flash` 进行严重性预过滤，使用 `qwen3.7-max` 进行根本原因诊断，使用 `qwen3.7-plus` 进行修复规划，使用 `text-embedding-v4` + `qwen3-rerank` 进行历史事件相似度搜索。 - **实时链上依据** —— 诊断过程通过 Alchemy（当前的 gas price、Chainlink ETH/USD 预言机报价、当前区块号）提取真实的 Sepolia 网络数据，而不是孤立地对本地测试网进行推理。 - **人类可读的事件简报**，由 Hermes Agent (NousResearch) 通过其原生的 Alibaba Cloud DashScope 集成运行 —— 将结构化的诊断结果和选定的修复方案转化为通俗易懂的英文，方便没有一直盯着 pipeline 的值班工程师理解。 - **硬性人工批准门槛** —— 没有明确的批准步骤，任何操作都不会执行。任何风险级别都不存在自动批准路径。 - 每个事件都有**完整的推理记录**，可通过 API 查询，并在 dashboard 中可见。 ## 技术栈 | 层级 | 技术 | |---|---| | 智能合约 | Solidity 0.8.20, Hardhat（5 个合约，用于模拟预言机、gas、协议、跨链桥和治理事件） | | 后端 | Python 3.11, FastAPI，全异步 | | AI / 推理 | Qwen Cloud（5 个模型），Hermes Agent | | 链上数据 | Alchemy (Sepolia JSON-RPC) | | 前端 | Next.js 16, React 19, TypeScript | | 持久化 | JSON 文件存储（关于在此规模下为何如此选择，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)） | ## 架构 ``` flowchart LR subgraph Chain["Hardhat Testnet"] C1[Oracle] C2[GasOracle] C3[Protocol] C4[Bridge] C5[Governor] end subgraph Backend["FastAPI Backend"] Listener[Event Listener] Diagnose[Diagnosis Engine] Remediate[Remediation Planner] Briefing[Hermes Briefing] Executor[Executor] end subgraph External["External Services"] Qwen[Qwen Cloud\n5 models] Alchemy[Alchemy\nSepolia RPC] Hermes[Hermes Agent] end Human[Human Operator] Dashboard[Next.js Dashboard] Chain -->|events, 2s poll| Listener Listener -->|severity pre-filter| Qwen Listener --> Diagnose Diagnose -->|root cause| Qwen Diagnose -->|live reference data| Alchemy Diagnose --> Remediate Remediate -->|ranked options| Qwen Remediate --> Briefing Briefing --> Hermes Hermes -->|via DashScope| Qwen Briefing --> Dashboard Dashboard <--> Human Human -->|approve| Executor Executor -->|simulated tx| Chain ``` ### 事件生命周期 ``` sequenceDiagram participant Chain as Hardhat Chain participant Listener as Event Listener participant Diag as Diagnosis (qwen3.7-max) participant Remед as Remediation (qwen3.7-plus) participant Human as Human Operator participant Exec as Executor Chain->>Listener: emits event (e.g. PriceDeviationDetected) Listener->>Listener: severity pre-filter (qwen3.6-flash) Listener->>Diag: incident created Diag->>Diag: gather live Alchemy reference data Diag-->>Human: root cause + confidence + evidence Human->>Remед: request remediation options Remед-->>Human: 3 ranked options (risk score, gas estimate) Human->>Human: review, approve one option Human->>Exec: approve + execute Exec->>Chain: submit remediation Exec-->>Human: confirmation + reasoning trace ``` 有关完整的详细分析，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，其中包括对哪些是真实集成、哪些是本次构建中的模拟情况的如实说明（链上执行是模拟的；Alchemy 集成是直接的 JSON-RPC，而不是完整的 MCP server 连接）。 ## 快速开始 ``` git clone https://github.com/mystiquemide/zeltho.git cd zeltho python -m venv .venv && source .venv/bin/activate # or .venv\Scripts\activate on Windows pip install -r requirements.txt npm install cp .env.example .env # fill in QWEN_API_KEY and ALCHEMY_API_KEY npx hardhat node # terminal 1 npx hardhat run scripts/deploy-all.js --network localhost # once uvicorn backend.main:app --reload # terminal 2 python -m backend.listener # terminal 3 cd frontend && npm install && npm run dev # terminal 4 ``` 访问 `http://localhost:3000` 查看着陆页，访问 `http://localhost:3000/dashboard` 查看实时 dashboard。使用以下命令触发测试事件： ``` npx hardhat run scripts/trigger-incident-1-oracle.js --network localhost ``` 完整的设置演练（包括运行测试）请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 环境变量 请参阅 [.env.example](.env.example)（后端）和 [frontend/.env.example](frontend/.env.example)。必需变量：`QWEN_API_KEY`，`ALCHEMY_API_KEY`。 ## 验证状态 - 31 个后端测试通过（`pytest`），覆盖了完整的事件生命周期和 API 边缘情况（重复诊断拒绝、修复 ID 伪造、跨事件 ID 复用等） - 前端类型检查无误（`tsc --noEmit`）且 lint 检查无误（`eslint`） - CI 会在每次 push 和 PR 时运行这两项检查 —— 参见 [.github/workflows/ci.yml](.github/workflows/ci.yml) ## 部署 有关在 Alibaba Cloud ECS 上运行所有四个服务的信息，请参阅 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)。 ## 仓库结构 ``` zeltho/ ├── backend/ # FastAPI app, diagnosis/remediation/briefing engines, stores ├── contracts/ # Solidity contracts simulating 5 incident types ├── scripts/ # Deploy + incident-trigger scripts ├── frontend/ # Next.js landing page + dashboard ├── tests/ # Backend test suite └── docs/ # Architecture, PRD, deployment, task breakdown ``` ## 安全 有关如何报告漏洞以及此构建版本中默认未加锁的内容，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 [MIT](LICENSE)

标签：AI智能体, AV绕过, FastAPI, PB级数据处理, Web3安全, 区块链, 安全运维, 库, 应急响应, 模块化设计, 自动化修复, 逆向工具