BankWeave

BankWeave

多家银行，一个环，一切指控皆有证据。

BankWeave 是一组 AI Agent，负责调查多家银行的洗钱警报，并以 FalkorDB 作为共享大脑。它能快速排除无辜警报，揭露任何单家银行都无法发现的洗钱网络，并为每个结论提供可点击查看的图路径。它还会记录每个判断依据的独立理由数量，发现其中某个理由失效时及时察觉，并拒绝提交无法证明的报告。

• 赛道： 01 基于关联数据行动的 Agent（主赛道）、02 Agent 记忆与协作、最佳博客文章
• 在线部署： https://bankweave.vercel.app（Vercel 上的 UI） · API：https://bankweave-api.onrender.com/docs（Render） · 图数据库：FalkorDB Cloud（ap-south-1）
• MCP Registry： 已发布为 io.github.LSUDOKO/bankweave（v3.0.0，流式 HTTP）
• 通过 Claude 使用： claude mcp add --transport http bankweave https://bankweave-api.onrender.com/mcp，或作为 stdio 包使用：claude mcp add bankweave -- docker run -i --rm ghcr.io/lsudoko/bankweave-mcp（17 个只读 FalkorDB 工具，每个工具都会返回执行过的 Cypher；docs/MCP.md）
• 在 FalkorDB 官方浏览器中查看证据： 我们的 Cloud 实例中环路、PageRank、刷卡记录、SAR 溯源和向量搜索的截图与录屏
• 五分钟了解项目： 3D 解说（八个场景，每个场景调用一次 FalkorDB）和图谱浏览器（十二种预设，可实时运行）
• 演示视频： 在 YouTube 上观看、在落地页观看或下载 MP4（配有旁白和内嵌字幕）：先通过白板讲解问题，再播放问题短片的结尾，随后展示运行在 FalkorDB Cloud 上的产品、硬件边缘、MCP 以及 FalkorDB 官方浏览器。亲自构建：video/build.py --long
• 博客文章： docs/BLOG.md 现已在真实数据上运行。 FalkorDB Cloud 上的生产实例存有 IBM 标注的 6 家银行 AML 交易数据：3,024 个账户、24,990 笔转账、36 个图（6 个银行图、包含 10,178 个节点和 37,448 条边的联盟图、27 个案件图、Agent 记忆和类型知识库）。Agent 已完成 1,208 条警报的分流：1,113 条已说明原因并予以清除，95 条已升级为案件。每个案件都包含主张、证据、每条证据背后的 Cypher 查询、带来源门控的报告和签名的 Merkle 密封。

BankWeave 是为 FalkorDB Graph Hacks 打造的独立项目。它不是 FalkorDB 产品，也与 FalkorDB 的 QueryWeaver 或 Weights & Biases Weave 无关。

---

问题

1. 警报疲劳。 基于规则的交易监控会在缺乏上下文的情况下标记单个信号；行业资料显示，85-95% 的警报都是误报。
2. 视野碎片化。 银行只能看到涉及自身的交易。洗钱方案会跨机构扩散，因此每家银行看到的局部情况都显得无害。
3. 报告缺乏可验证性。 可疑活动报告（SAR）必须给出充分依据，而如今这些依据都是人工整理的。

BankWeave 的功能

1. 将 IBM 的公开 AMLworld 洗钱数据集加载到每家银行各自隔离的 FalkorDB 图中，并创建一个通过加盐哈希账户 ID 将各图连接起来的联盟图。
2. 一组 Agent（Orchestrator、Triage、Investigator、Skeptic、Reporter，以及独立的 Auditor、Archivist）通过存储在图中的任务黑板处理警报队列，并将 FalkorDB 原生算法作为工具调用（也通过 MCP 提供）。
3. 无害警报会在毫秒内说明原因并予以清除；可疑警报则会转为案件，每个案件都存放在独立的 case_<id> 图中，主张会关联到证据及生成证据的查询。
4. 基于 3 篇 2026 年论文构建的信任层确保 Agent 诚实守信（见下文）。
5. 所有操作都由人工批准。所有结果都会与 IBM 的标注进行对比，并显示在记分板上。

3.0 版新增内容

区域	可执行的操作	位置
控制台	侧边栏列出全部十四个页面并显示实时计数；可通过 Ctrl K 搜索页面和案件；所有页面采用统一的卡片系统：基于实时查询的统计卡片、状态标签和圆角图表	每个页面
仪表板	查看待处理案件、已判定警报、独立索赔、等待人工处理的操作；查看最新案件的索赔支持、下一项审批、Agent 团队、警报分流仪表，以及 FalkorDB Cloud 延迟、图和记忆	/command
图探索器	类似 FalkorDB 浏览器的页面：选择图，编写 Cypher（GRAPH.RO_QUERY，引擎会拒绝写入），查看带标签的 Obsidian 风格力导向图、悬停查看邻域并打开属性面板。提供十二个预设，每个都展示 FalkorDB 在我们的数据上的一项功能：跨银行环路、algo.pageRank、algo.labelPropagation、algo.wcc、algo.SPpaths、Double Metaphone 全文搜索、HNSW 向量 KNN、共享身份、Agent 的警报到索赔链路、SAR 的溯源信息、类型学知识库、学习到的流程	/explorer
3D 讲解	在 three.js 舞台上滚动浏览八个场景：六个银行切片和逐图 ACL、将联盟串联起来的哈希 ID、algo.wcc 清除警报、一个银行能看到其中 37.5% 的环路、PageRank 枢纽和 algo.SPpaths、六条路径合并为四个源头、KYC 级联、由硬件密钥签名的 Merkle 根。每个数值都来自 API；每个场景都会显示运行的 Cypher	/explainer
托管 MCP	claude mcp add --transport http bankweave https://bankweave-api.onrender.com/mcp：17 个只读工具（案件、回显证明索赔、资金路径、环路、枢纽、连通分量、向量和语音搜索、分流、类型学、受保护的 Cypher）、3 个提示词、2 个资源	/mcp、docs/MCP.md
着陆页	以带逐字显示效果的光泽蓝色气泡为背景的居中主视觉，实时控制台从中升起；包含「新增内容」便当式布局、以实时页面高亮截图呈现的评估、真实工具录制内容和 FalkorDB Browser 证明	/
真实工具，实机录制	在 Wokwi 中运行的 ESP32 草图会将真实刷卡操作发送到实时 API，EMVLab 会解码其输出的 field 55	硬件实验室，下方

着陆页	仪表板

图探索器：联盟图中的跨银行环路	3D 讲解：从单个银行的视角查看环路

图探索器：algo.pageRank 枢纽（悬停可聚焦于一个社群）	3D 讲解：六个银行切片，每个银行只能看到自己的图

警报队列	案件工作区

审批	硬件实验室

FalkorDB 官方浏览器中的验证

Agent 使用的同一份数据，已在 FalkorDB 自带的浏览器中打开（browser.falkordb.com，连接到我们的 FalkorDB Cloud 实例：FalkorDB v4.22，36 个图，约 81 MB）。下方的查询均为只读，并直接在浏览器中输入；耗时是引擎自身的 RT 读数。显示实例主机名的连接栏已裁掉。

查询	验证内容
跨银行环路：涉及银行数最多的案例、其账户、银行和转账（12 个节点，166 条边，1.85 ms）	一条 Cypher 查询即可看到任何单家银行图都不包含的完整环路
CALL algo.pageRank('Account','TRANSFERS') 前 12 名（3.55 ms）	调查员调用的枢纽检测由原生 GraphBLAS 执行，而非 Python
(:Account)-[:CARD_TXN]->(:Terminal)（5 个节点，29 条边，0.41 ms）	POS/ATM 刷卡记录（包括通过 Wokwi ESP32 发送的一笔）都是联盟图中的真实边；Terminal 节点包含 POS-MUM-…、Mumbai、GPS 19.076、72.8777
case_C-70431130 中的 (:SAR)-[:CONTAINS]->(:Sentence)-[:CITES]->(:Claim)-[:SUPPORTED_BY]->(:Evidence)（0.61 ms）	每条报告语句都引用一项主张，且每项主张都有证据支撑：来源追溯门槛由图模式实现
db.idx.vector.queryNodes('Account','behavior_vec',10, …)（0.36 ms）	HNSW 向量搜索可在五家不同银行找到行为相似的账户
不同银行中共享 Device 或 IP 的账户（291 个节点，220 条边，2.79 ms）	联盟用于连接各银行数据切片的身份关联

跨银行环路	algo.pageRank

连接到终端的银行卡刷卡记录（包括 Wokwi 刷卡记录）	Mumbai POS 节点及其属性

SAR → 语句 → 主张 → 证据	HNSW 向量 KNN

跨银行共享的设备和 IP	FalkorDB Cloud 控制台：实例（免费层级，ap-south-1，v4.22.0，运行正常）

托管 MCP，实时调用（无需安装，纯 HTTP）：

$ curl -s -X POST https://bankweave-api.onrender.com/mcp -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
17 tools: engine_overview, list_graphs, graph_schema, list_cases, get_case, explain_claim,
account_network, trace_money_path, find_rings, top_hubs, connected_components, similar_accounts,
search_customers, list_alerts, triage_alert, typology_guidance, run_readonly_cypher

$ ... "method":"tools/call","params":{"name":"top_hubs","arguments":{}}
{"graph": "consortium", "result": [{"account": "e8ccd1faa8d3a4ba", "bank": "001", "score": 0.0027...}, ...

排名第一的账户与上方 FalkorDB 浏览器中 PageRank 查询的第 1 行匹配。

2.0 版新增内容

领域	可执行的操作	位置
指挥中心	在同一视图中查看实时警报、待处理案件、经过独立支持的主张、等待审核的证据，以及 FalkorDB 的健康状况（内存、图、引擎）	/
黄金场景	A：由 algo.wcc 排除的误报。B：横跨 4 家银行的团伙（单家银行最多只能识别其 50%；E2：平均为 43.8%，没有一家能识别完整团伙）。C：一栋共享的 200 单位建筑背后的一项理赔，以及 KYC 更新将触发的级联影响。实时计算；免费层 API 休眠时会立即加载捆绑快照	/scenarios
模式徽章	每个页面都会标明当前运行模式：使用 LLM Agent 实时运行、使用确定性 Agent 实时运行，或使用预置数据回放	导航栏、页面标题
FalkorDB 实验室	查看所有图及其计数、索引和 GRAPH.MEMORY USAGE；17 个一键运行项（10 种算法、按语音和词干检索的全文搜索、向量 KNN、JS UDF、FLEX、三模态查询）；只读 GRAPH.PROFILE/GRAPH.EXPLAIN 检查器；MCP 工具浏览器，展示模式、实时负载、各工具执行的 Cypher 语句及其 Engine X-Ray；逐银行 ACL；以图形式呈现的程序性记忆	/lab
案件工作区	证据独立性探索器（“15 条路径 → 12 个来源”）、撤销任意证据并查看级联影响、来源 DAG（React Flow）、调查回放、双时态时间机器、在 GRAPH.COPY 沙盒中模拟冻结、制裁筛查、加密货币出金关联、Agent 执行轨迹瀑布图	/cases/<id>
签名导出	FinCEN 风格的 SAR XML 和可打印的审计档案：包含每句话、引用的证据、带执行哈希的每条查询，以及覆盖整个案件的 Ed25519 签名 Merkle 根	/cases/<id>/dossier
3D 联盟	以外部存根隔开的银行切片、它们汇合的联盟（流动粒子、PageRank 枢纽），以及叠加其上的案件和理赔；支持飞行穿越、回声坍缩、失效冲击波，以及带心跳倒计时的终止并恢复	/consortium-3d
评估	E2 核心指标、E1 表格及阈值探索器、E6 记分卡、标注遗漏项的 E3-E5，以及标记为本地基准测试的 E7	/evaluation
硬件实验室（设备孪生、真实密码学）	POS/ATM 数字孪生向图中写入包含真实 EMV TLV 的 ISO 8583 数据；Wokwi ESP32 终端；使用 WebAuthn 或虚拟安全密钥对 Merkle 根签署审批（若证据之后发生变化，则会显示“Merkle seal broken”）；具备 PCR 证明且在遭到篡改时会自我隔离的可信执行环境；银行间 ECDH-PSI	/hardware-lab、hardware/wokwi/
集成	OpenSanctions 筛查（配置 API 密钥后实时运行，否则使用捆绑的样例列表）、链上钱包事实、采用 OpenTelemetry 格式的跨度及 OTLP 导出	/integrations/*、案件标签页

刷卡终端、可信执行环境和安全密钥以软件设备孪生的形式运行（ESP32 终端运行于 Wokwi），生成真实的 EMV/ISO 8583 数据、真实签名和真实密钥交换，并通过实体设备会调用的同一 API 写入真实图数据。

线上网站截图

在 https://bankweave.vercel.app 上截取，使用 Render API 和 FalkorDB Cloud （ap-south-1），Agent 使用 Groq 免费层；模式徽标显示“Live · LLM + FalkorDB”。

黄金场景：A 已由 algo.wcc 清除，B 是跨银行环形网络，C 是级联	银行与联盟：一家银行的碎片与联盟的对比

案例	案例工作区：证据独立性（“15 条路径 → 14 个来源”）

来源 DAG	在 GRAPH.COPY 沙盒上模拟冻结

Agent 跟踪瀑布图（来自线上 Agent、形如 OpenTelemetry 的 span）	制裁筛查与加密货币出金桥接

SAR：每句话都注明其证据	附有签名 Merkle 根的审计档案

信任层：回声证明置信度与级联	3D 联盟

FalkorDB 实验室：图、节点、边、内存	算法与索引，一键即可操作

GRAPH.PROFILE / GRAPH.EXPLAIN 检查器	MCP 工具，展示实时负载及其执行的 Cypher

引擎功能：JS UDF、三模查询、按银行 ACL	评估

有数据为证，并突出显示证据。 首页的“数据胜于宣传”展示了线上评估页面的以下截图：

E2：单家银行最高检出率为 43.8%，完整识别环形网络的数量为 0/36，联盟检出率为 100%	E1：校准后的图评分 F1 为 0.205，而将所有内容都升级处理时为 0.063

E6：检出 27.8% 的回声，28 份 SAR 中有 25 份通过关卡，级联召回率为 100%	E7：向量 KNN 耗时 0.4 ms，遍历整个联盟的 PageRank 耗时 57.5 ms

硬件信任层（设备孪生、真实密码学）

银行不会让软件单独行动：终端提供设备证据，HSM 和飞地保护身份哈希，人类则使用安全密钥签字确认。BankWeave 在软件中运行这三者的设备孪生，并将它们分别接入 FalkorDB。

在真实工具上记录。 hardware/wokwi/ 中的示例运行于 Wokwi ESP32 模拟器：它连接到 Wokwi-GUEST，在孟买 POS 上轻触 Card A，开发板通过 HTTPS 将其发送到实时 API，API 返回 00 APPROVED，将 CARD_TXN 边写入 FalkorDB Cloud，并返回显示在串行监视器上的 ISO 8583 字段 55。随后，EMVLab.org 对该确切 TLV 进行解码（金额、货币、IFD 序列号 D0006301、ATC、密码、PAN）。

Wokwi ESP32 → 实时 API → FalkorDB	EMVLab 解码轻触产生的字段 55

实时网站上的 Hardware Lab：

终端：POS 和 ATM 孪生及其最近的轻触记录、EMV TLV，可在 EMVLab 上验证	安全密钥：使用 WebAuthn 或虚拟 VaultKey 为案例的 Merkle 根签名

飞地：证明文档、PCR、HSM 签名者、银行链接	Wokwi 上的 ESP32：真实示例、示意图和实时串行日志

两个银行图之间的 ECDH-PSI（X25519）	Wokwi 轻触记录作为边显示在 FalkorDB Cloud 中（FalkorDB Browser）

每个设备孪生生成的内容：

组件	真实输出	运行方式
卡片终端	BER-TLV 编码（由 EMVLab 验证）、ISO 8583 字段布局、图写入（CARD_TXN、USES_DEVICE {emv_atc, terminal_id, gps, nfc_uid}）、供 Agent 分类处理的警报、异常旅行和 ATC 重放检测	终端和卡片；9F26 是 HMAC，而非芯片的 3DES/AES MAC
Wokwi ESP32	电路在 Wokwi 中运行并发送真实的 HTTPS 请求	Wokwi 模拟器中的 ESP32 开发板
审批密钥	WebAuthn ES256 验证、签名计数器、针对声明/证据/语句的 Merkle 根、撤销时破坏密封	VaultKey 是标签页中的 WebCrypto 密钥
飞地 / HSM	HMAC-SHA256 盲化、SHA-384 PCR、ES384 签名的 Nitro 风格文档、(:EnclaveAttestation) 节点、隔离期间以 423 拒绝数据接入	无 TEE 硬件或 AWS Nitro PKI 链
PSI	X25519 标量乘法、可交换盲化	两家银行在同一进程中运行

外部验证工具：EMVLab TLV 解码器 · EMVLab 密码工具 · WebAuthn.me 调试器 · Chrome 虚拟身份验证器 · Wokwi ESP32 · OpenSanctions · FalkorDB Cloud。

FalkorDB 至关重要的原因

关闭 FalkorDB，BankWeave 就无法完成任何核心工作：

没有图……	因为
无法看到环路	环路仅存在于银行之间的路径中；它连接的位置是财团图（参见 E2）
分诊无法清除任何内容	连通分量、模式评分、跨银行链接和共享身份都通过图查询获取
没有任何声明有证据支持	证据是图中的一条路径、一项算法评分或一个共享属性，并与其查询一同存储
无法计算置信度	回声证明置信度统计 SUPPORTED_BY 边上不同 origin 的数量
无法级联失效	依赖关系通过类型化边表示（SUPPORTED_BY、DERIVED_FROM、JUSTIFIED_BY、CITES）
Agent 无法协作或恢复任务	任务、心跳和案件时间线都存储在图中

使用中的 FalkorDB 功能：多图（在同一实例中存放每家银行、财团、每个案件、流程和类型学知识库的图）、原生算法（algo.wcc、algo.labelPropagation、 algo.pageRank、algo.betweenness、algo.HarmonicCentrality、algo.SPpaths、algo.SSpaths、 algo.maxFlow、algo.bfs、algo.MSF）、支持 Double Metaphone 语音匹配和英语词干提取的全文索引、用于行为画像的向量索引（HNSW）、JavaScript UDF（FalkorDB 的 FLEX 库和我们自己的 aml_temporal）、GRAPH.COPY 沙盒、 GRAPH.PROFILE/GRAPH.EXPLAIN、GRAPH.MEMORY USAGE、限定于单个图的 ACL，以及用于实时发布/订阅的 Redis 协议。

证明：BankWeave 使用的每项 FalkorDB 功能

特性	代码位置	运行证据
多图（同一实例中的隔离图）	consortium、bank_<id>、case_<id>、procedures、typology_kb（backend/app/db.py）	运行期间，浏览器显示 43-188 个图；FalkorDB Cloud 中有 consortium、6 个银行图和 typology_kb
algo.wcc	预计算连通分量大小；分流孤岛（detection/precompute.py、detection/algorithms.py）	E7 耗时；警报队列中的分流原因“孤立集群”
algo.labelPropagation	社区（detection/precompute.py）	每个账户的 Account.community
algo.pageRank	在案件图中查找枢纽；SPNSA 中间人	FalkorDB Cloud 上的 （3.55 ms）；E7 耗时
algo.betweenness（带种子）	骡子桥接节点；SPNSA
algo.HarmonicCentrality	协调者候选项	find_orchestrator 工具、反驳轮次
algo.SPpaths	资金路径：主张的主要证据	每个案件中都有 path 证据及其查询
algo.SSpaths、algo.bfs	reach、bfs_reach 工具（案件图）	Investigator 和 MCP 均可使用
algo.maxFlow	通过合并后的 FLOWS 边计算风险资金	枢纽主张引用最大流证据
algo.MSF	backbone 工具：环路的生成骨干	Investigator、Reporter 和 MCP 均可使用
全文索引 + Double Metaphone	Person.name、Company.name（detection/identity.py）	test_identity.py：拼写变体可找到其原始身份
全文索引 + 英文词干提取	类型知识图谱（knowledge/typology_kb.py）	回答会引用来源；遇到不相关问题时会拒绝作答
向量索引（HNSW，余弦）	16 维行为画像（app/services/loader.py）	behavior_neighbors、分流特征、线索扩展
范围索引，包括关系属性索引	TRANSFERS.ts（txn_id 边索引已在 2.0 中删除：没有查询会用到它，而且它占用约 8 MB）	CALL db.indexes()
JavaScript UDF（GRAPH.UDF LOAD）	aml_temporal.timeRespectingReach 使用 getNeighbors 遍历 TRANSFERS，仅沿后续转账继续遍历（backend/udf/aml_temporal.js）	test_lab.py::test_udf_libraries_load_and_run；Lab → Engine 特性
FLEX（FalkorDB 的 UDF 库，随代码库提供，版本为 1.0.1）	flex.text.jaroWinkler、flex.text.levenshtein 用于名称，flex.sim.jaccard 用于共享身份属性	Lab 运行 flex_names、flex_jaccard
GRAPH.COPY	模拟冻结操作会复制案件图，在副本中删除账户，然后重新运行 algo.maxFlow + algo.wcc（app/routers/workspace.py）	test_workspace.py：流量从 80 → 0，沙箱已删除
GRAPH.PROFILE / GRAPH.EXPLAIN	每次工具调用均可使用只读检查器和 Engine X-Ray；查询必须先通过 GRAPH.RO_QUERY（app/services/engine.py）	test_lab.py::test_inspect_refuses_writes
GRAPH.MEMORY USAGE	Lab 和 Command Center 中的逐图内存用量；100 MB 云端套餐的容量保护机制（app/services/capacity.py）	/lab/graphs
ACL（~graph 键模式、ACL LOG）	只能对自己的图执行 GRAPH.RO_QUERY 的银行用户（/lab/acl-demo）	consortium、其他银行及写入操作均会被拒绝并记录日志（见上方截图）。FalkorDB Cloud 用户无法管理 ACL，因此此功能在 Docker 上运行
同一查询中包含多个 CALL	三模态查询：语音全文检索 → HNSW 向量孪生 → 对 FLOWS 执行 algo.SPpaths	Lab trimodal（约 10 ms）
参数化 Cypher，读取时使用 ro_query	所有查询（docs/QUERIES.md：204 个已注册查询 + 67 个内联查询）	只读 MCP 工具 cypher_readonly
同一图上的并发写入者	任务黑板（agents/blackboard.py）	test_blackboard.py：6 个线程、20 个任务，每个任务只认领一次
FalkorDB Browser	直观检查每个图	下方截图
FalkorDB Cloud	已载入 IBM 子集数据的在线实例（ap-south-1）	scripts/make_slice.py + 种子数据日志

来自运行中的 FalkorDB Cloud 实例的实证

FalkorDB Browser 连接到实时网站所用生产实例的截图 （docs/img/cloud/）：

内容	截图
多图：一个实例中包含 consortium、六个银行图和案例图
正在使用的索引类型：1 个向量索引（HNSW）、2 个全文索引（语音索引）、14 个范围索引
按标签和属性列出的所有索引
consortium 上的 algo.pageRank（4.3 ms）
行为画像上的向量相似度计算（0.5 ms）
Double Metaphone 全文搜索："Hana Sharma" 可找到 "Hannah Sharma"
实时 Agent 找到的环：一个枢纽向四家银行的账户付款（consortium 图，0.98 ms）
该案例自己的图：索赔、SUPPORTED_BY 及 Skeptic CHALLENGED_BY 证据；SAR、Sentence、Event 和 Action 也都在这里

来自 IBM 数据本地运行的实证

FalkorDB Browser 中的 consortium 环	案例图：索赔及其证据

实时网站上的银行与 consortium 对比	黄金场景 B：一家银行持有 37.5% 的环

真实 IBM 数据上的警报队列	案例工作区

架构

flowchart TB
  UI[Next.js UI: queue, network weave, case workspace, SAR, trust, approvals, scoreboard] -- REST / WebSocket --> API
  API[FastAPI + WebSocket bridge] --> W
  subgraph W[Agent worker: LangGraph flow]
    O[Orchestrator] --> T[Triage] --> I[Investigator] <--> S[Skeptic] --> R[Reporter] --> A[Auditor]
    H[Human approval] --> AR[Archivist]
  end
  W -- tools --> TOOLS[Tool registry]
  MCP[MCP server: 34 tools] --> TOOLS
  TOOLS -- Cypher / algo.* --> F[(FalkorDB: consortium, bank_*, case_*, procedures, typology_kb)]
  TOOLS -- SQL --> PG[(Postgres KYC)]
  W -- events --> RD[(Redis pub/sub)] --> API
  W -- LiteLLM --> LLM[Groq free tier: writer qwen3.8-27b + different, larger auditor gpt-oss-120b]

大模型负责规划、选择工具和撰写文本。Cypher 和 algo.* 负责计算。没有 API 密钥时，Agent 会运行确定性策略（并在 UI 中标明），因此系统始终可运行。

图模型

完整架构：docs/GRAPH_MODEL.md。简而言之：

• consortium：Account（哈希 ID、银行、度数、PageRank、分量、社区、模式评分、过手统计数据、16 维行为向量）-[:TRANSFERS]-> Account；每对账户之间有一条折叠后的 -[:FLOWS]-> 边；身份层（Person/Company -[:OWNS]->；USES_DEVICE、USES_IP、REGISTERED_AT）、Alert、Decision、黑板 Task、案例镜像。
• bank_<id>：银行自己的 Account，以及 ExternalAccount 占位节点；仅包含与该银行相关的转账。
• case_<id>：Claim -[:SUPPORTED_BY|CHALLENGED_BY]-> Evidence {origin, cypher}、 Claim -[:DERIVED_FROM]-> Claim、Action -[:JUSTIFIED_BY]-> Claim、 SAR -[:CONTAINS]-> Sentence -[:CITES]-> Evidence|Claim、Evidence -[:SUPERSEDES]-> Evidence、 Case -[:HAD_EVENT]-> Event -[:NEXT]-> Event。

Cypher 查询和算法

产品运行的每个查询都列在 docs/QUERIES.md 中，该文档由代码生成。以下是一些关键内容：

// echo-proof confidence: count independent origins, not paths
MATCH (c:Claim {id:$id})-[:SUPPORTED_BY]->(e:Evidence)
WHERE e.state IN ['active', 'needs_verification']
RETURN count(e) AS paths, count(DISTINCT e.origin) AS independent_sources

// money path between two accounts: the primary evidence for a claim
MATCH (s:Account {id:$src}), (d:Account {id:$dst})
CALL algo.SPpaths({sourceNode:s, targetNode:d, relTypes:['TRANSFERS'],
                   maxLen:$max_len, pathCount:$path_count, relDirection:$direction})
YIELD path, pathWeight
RETURN [n IN nodes(path) | n.id] AS accounts, [t IN relationships(path) | t.txn_id] AS txn_ids

// money at risk: max flow from flagged accounts to the hub (collapsed FLOWS edges)
CALL algo.maxFlow({sourceNodes:srcs, targetNodes:tgts, relationshipTypes:['FLOWS'],
                   capacityProperty:'capacity', nodeLabels:['Account']})
YIELD maxFlow, edges, edgeFlows

// premise check: does this action rest on overturned evidence?
MATCH (a:Action {id:$id})-[:JUSTIFIED_BY]->(c:Claim)
OPTIONAL MATCH (c)-[:SUPPORTED_BY|DERIVED_FROM*1..5]->(e:Evidence {state:'superseded'})
RETURN c.id, collect(e.id) AS stale

FalkorDB 没有原生提供的功能，都用纯 Cypher 实现（并明确说明）：度数（预计算）、按时间排序的环（迭代式的时间约束扩展，每跳执行一个查询）、3 环（模式评分）、特征向量中心性（SPNSA 中改用 PageRank）。

Agent 和 MCP 工具

Agent	职责
Orchestrator	将未处理的警报转化为黑板任务，重置过期认领
Triage	说明原因并清除警报，或创建案件图
Investigator	选择图工具（大模型）或遵循已学习的流程；编写与证据关联的主张；引用具名类型学
Skeptic	根据 KYC 事实和属性共享背景，论证无辜解释；最多进行 2 轮
Reporter + Auditor	通过溯源门控生成 SAR；由另一个更强大的模型进行审计
Archivist	保存有效的工具调用序列（程序性记忆），关闭案件

托管 MCP（只读，无需安装）： claude mcp add --transport http bankweave https://bankweave-api.onrender.com/mcp。 它通过同一个 Render API，使用 Streamable HTTP 提供 17 个只读工具；每个工具都通过 GRAPH.RO_QUERY 运行，并返回图、Cypher、参数和耗时。Claude Desktop 和 Cursor 的安装命令、工具表格及真实对话记录见 docs/MCP.md。

完整的本地 MCP 服务（python -m mcp_server.server，支持 stdio 或 --http PORT）提供全部 34 个工具（32 个 Agent 工具，以及 cypher_readonly 和 list_graphs）， 包括 trace_flow、find_hub、find_bridges、money_at_risk、typology_patterns、 passthrough_check、clue_expand、hunt_regions、resolve_entity、behavior_neighbors、 kyc_lookup、kb_query、echo_check、invalidate_evidence、premise_check，以及 cypher_readonly 和 list_graphs。每个结果都包含执行过的 Cypher。

Claude Desktop 配置：

{ "mcpServers": { "bankweave": {
  "command": "/path/to/BankWeave/backend/.venv/bin/python",
  "args": ["-m", "mcp_server.server"], "cwd": "/path/to/BankWeave/backend" } } }

信任层

功能	可防止的问题	来源
回声防护置信度	多条路径指向同一事实，导致重复计数	GraphEcho，arXiv 2609.17695
级联失效 + 前提检查	基于证据已被推翻的信念采取行动	PACMI，arXiv 2610.05732
溯源门控 + 偏差报告	流畅的报告臆造证据无法支持的一致意见	Active Provenance Gate，arXiv 2609.31422

• 每条 Evidence 都带有 origin（例如 attr:D00063、flow:a->b、typ:cycle:a）。 置信度根据不同来源计算；同一栋楼内有 200 个单位的地址会被降低权重。 UI 会显示“N 条路径，K 个独立来源”及其旁边的朴素估算值。
• 替代证据不会将其删除。依赖项沿有效性阶梯移动 （active < needs_verification < historical_only < superseded）；若操作依据的是过期 证据，必须添加明确的覆盖说明才能获批。
• SAR 根据封闭证据包起草。首先运行代码检查（引用的 ID 存在、处于有效状态且属于该案件）；然后由另一个模型逐句判断蕴含关系。只有在溯源保真度 >= 0.95 时才会发布，且最多进行 3 次修复；否则会生成偏差报告，并排展示 Investigator 和 Skeptic 的立场。建议不能依据回声防护置信度低于 0.5 的主张。

记忆与协调（Track 02）

• 共享状态： 黑板由 Task 节点构成；认领通过单个原子查询完成（经 6 个并发工作进程验证，每个任务恰好完成一次）。
• 终止与恢复： 工作进程会发送心跳；过期认领会被重置，任何工作进程都可从图中继续。演示控制区有一个 Kill 按钮；案件页面提供“Resume from graph”。
• 情景记忆： 每个案件的 Event 时间线（HAD_EVENT、NEXT），可在 UI 中重放。
• 语义记忆： 带有效性状态和历史记录的主张与证据（beliefs_as_of）。
• 程序性记忆： procedures 图存储促成获批结果的工具调用序列。
• 跨案件回忆： 主张摘要会镜像到联盟中（Account <-[:ABOUT]- Claim）。
• 隔离： 在同一个 FalkorDB 实例中使用各银行和各案件的独立图。

评估

E1：警报分类（IBM HI-Small，20 家银行组成的联盟）

从该时段后半段选取 4,000 个触发警报的账户（129 个非法账户，基准率为 3.2%）；权重和阈值仅使用前半段数据确定。

方法	精确率	召回率	F1	升级处理的账户数	未升级处理的警报
基于规则：全部升级处理	3.2%	100.0%	0.062	4,000	0.0%
不使用图的规则（≥3 条规则）	33.3%	7.8%	0.126	30	99.2%
BankWeave 图评分，人工设定权重（无标签）	18.9%	14.0%	0.161	95	97.6%
BankWeave 图评分，在开发集上校准	17.8%	24.0%	0.205	174	95.7%

_{eval/results/E1_alert_triage.json，提交 49f9388，HI-Small_Trans.csv（20 家银行，图前缀 'ibm_'）}

E2：没有任何一家银行能单独看到整个团伙

在跨银行的 36 个洗钱团伙中（平均每个团伙涉及 3.5 家银行），持有该团伙账户最多的单家银行仅持有 43.8% 的账户，且 0.0% 的情况下能持有整个团伙。它确实能观察到 95.7% 的洗钱转账，但大多数交易对手是其他银行的客户，无法对其展开调查。联盟图则涵盖了每个团伙的 100% 账户。

_{eval/results/E2_consortium_vs_single_bank.json，提交 49f9388，HI-Small_Trans.csv（20 家银行，图前缀 'ibm_'）}

E3：猎查模式（SPNSA 复现，k=200，r=1）

种子输入	子图账户数	非法账户比例	论文（HI-Small）
随机（10 次均值）	250	3.4%	2.4%
度数不平衡	336	17.0%	13.7%
模式一致性（论文参数）	280	7.5%	22.6%
模式，不加度数惩罚（事后消融）	378	11.6%	—

该图中的基准率：2.5%。我们未能复现论文的排名：使用其参数时，度数惩罚会使我们选取的 20 家银行子集中模式评分的效果反转（账户级 AUC 为 0.3743，而不加惩罚时为 0.638），因此度数不平衡在这里表现最佳。所有输入的效果都优于随机输入。

_{eval/results/E3_spnsa_hunt.json，提交 cc7037a，HI-Small_Trans.csv（20 家银行，图前缀 'ibm_'）}

E4：过手交易匹配

标记了 708 个账户；其中 4.8% 为非法账户，而基准率为 2.5%。去除重复链后的金额：74,961,854,871（IBM 金额涉及多种货币，因此这是原始总和，并非美元金额）。

_{eval/results/E4_passthrough.json，提交 154672b，HI-Small_Trans.csv（20 家银行，图前缀 'ibm_'）}

E5：线索引导的追查

从 12 个洗钱团伙中各取 2 个线索成员：最佳的第 2 轮达到 33.3% 的精确率和 3.4% 的召回率。效果较弱；图信号版本（无 GNN）大多只能找到线索成员的直接关联方。

_{eval/results/E5_clue_expansion.json，提交 706ae01，HI-Small_Trans.csv（20 家银行，图前缀 'ibm_'）}

E6：Agent 实际案例中的信任层

在基于 IBM 实时数据切片构建的 Agent 所处理的 28 个案例中：

• **回声：**510 个证据项中有 27.8% 重复了已见来源；101 项主张中有 37 项的支持路径数量多于独立来源数量。经过回声验证的平均置信度为 41.7%，按路径计数时为 48.8%。
• **来源门控：**28 份 SAR 中有 25 份已发布，另有 3 份以差异报告结案；平均来源保真度为 0.988；26 份至少需要一轮修复。
• **级联失效：**在 50 个脚本化依赖图中，受影响节点的召回率为 100.0%，精确率为 100.0%。
• **过时审批：**没有任何操作在证据被推翻且未获覆盖批准的情况下获得批准。

_{eval/results/E6_trust_layer.json，提交 f3cff38，IBM_SLICE_Trans.csv（6 家银行，图前缀 ''）}

E7：速度（单台本地机器）

联盟图：28,307 个账户，1,315,597 笔转账。

操作	中位数	第 95 百分位
扩展邻域	3.1 ms	6.1 ms
类型模式	12.5 ms	674.0 ms
跨银行关联	0.6 ms	0.9 ms
共享身份	0.7 ms	0.9 ms
行为邻居	0.4 ms	1.0 ms
过账检查	2.8 ms	10.5 ms
分流信号：枢纽账户	1.1 ms	2.3 ms
分流信号：普通账户	15.4 ms	58.0 ms
联盟 PageRank	57.5 ms
联盟 WCC	39.5 ms

_{eval/results/E7_performance.json，提交 b8a1292，ibm_}

部署（线上）

部件	所在位置	方式
图数据库	FalkorDB Cloud，AWS ap-south-1	使用 scripts/make_slice.py + scripts/seed_all.sh 填充数据（真实 IBM 切片：24,990 笔交易，6 家银行）
API + Agent 工作进程	Render Web 服务 bankweave-api（新加坡）	根目录 Dockerfile；使用 Render CLI 创建；Agent 在 API 进程中运行
实时事件	进程内事件总线（单个服务无需 Redis）	backend/app/events.py
KYC Postgres	Neon（aws-ap-southeast-1）	python -m app.services.kyc_synth --postgres-only
UI	Vercel bankweave.vercel.app	从 frontend/ 运行 vercel deploy --prod
大模型	Groq 免费套餐（写入器 qwen/qwen3.8-27b，审计器 openai/gpt-oss-120b），OpenRouter 免费模型作为备用	backend/agents/llm.py

Render 免费套餐在空闲 15 分钟后会休眠；首个请求会唤醒它（约需一分钟），随后 Agent 会从图黑板恢复运行。GitHub Actions 任务每 10 分钟访问一次 /health 以保持服务活跃；服务唤醒期间，主要页面仍会显示从真实 API 响应中捕获的内容（scripts/capture_snapshots.py），并在屏幕上标明。

FalkorDB Cloud 免费套餐提供 100 MB 空间，并启用 noeviction。从 2.0 起，图以紧凑形式加载（KYC_ARGS=--compact，不创建未使用的 txn_id 边索引，也不为约 100 个节点的案例图创建 ID 索引），/health 会报告已用内存；scripts/cloud_reseed.sh 会重建云端图，同时保留已固定的案例。仅当 CAPACITY_PRUNE=true 时，才会自动清理旧案例图。

可选环境变量：OPENSANCTIONS_API_KEY（实时制裁筛查）、HELIUS_API_KEY（Solana 钱包查询）、EVM_RPC_URL、OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_HEADERS（将 Agent span 导出到 Langfuse、Jaeger 或任意 OTLP 收集器）、DOSSIER_SIGNING_KEY（用于案卷签名的十六进制 Ed25519 种子）、PINNED_CASES、CAPACITY_PRUNE。

在本地运行

预构建的 API 镜像：docker pull ghcr.io/lsudoko/bankweave-api:latest（每次发布时都会推送）。

docker compose up -d                       # FalkorDB (6390, Browser 3030), Redis (6391), Postgres (5440)
cp .env.example .env                       # add GROQ_API_KEY (free) for LLM agents (optional)
cd backend && uv sync && cd ..
scripts/seed_all.sh                        # sample dataset -> bank graphs, consortium, identity, precompute
cd backend && uv run python -m app.services.baseline && uv run uvicorn app.main:app --port 8000
cd frontend && pnpm install && pnpm dev -p 3001

打开 http://localhost:3001，进入 Demo control 并点击 Start agents（Agent 会开始分流警报并创建案例；仪表板会实时更新）。

用于评估的 IBM 数据：运行 scripts/download_ibm.sh（需要 Kaggle 令牌），或使用公开镜像 hf.co/datasets/eexzzm/IBM-Transactions-for-Anti-Money-Laundering-HI-Small-Trans，然后运行 GRAPH_PREFIX=ibm_ scripts/seed_all.sh data/raw/HI-Small_Trans.csv --top-n 20 和 GRAPH_PREFIX=ibm_ eval/run_all.sh。

测试：cd backend && uv run pytest（55 个测试，针对本地 FalkorDB）。

硬件：hardware/wokwi/ 中的 ESP32 终端在 Wokwi 中运行，并通过 HTTPS 向 POST /hardware/pos-tap 发送刷卡事件（参见其 README）。

数据

• IBM 反洗钱交易数据（AMLworld、HI-Small），标准的带标签反洗钱基准数据集。由于真实银行交易数据无法公开，IBM 使用多 Agent 世界模型生成了该数据集：5,078,345 笔交易、5,177 笔已标记的洗钱转账、8 种洗钱类型。标签仅用于 eval/。运行中的实例采用其中涵盖 6 家银行的子集（3,024 个账户、24,990 笔转账）。
• 身份层（backend/app/services/kyc_synth.py，随机种子 42）：人员、姓名变体、设备、IP、地址和 Postgres KYC 表。为便于审计数据泄漏，生成规则如下：尝试成员共用设备的概率为 P=0.40，无辜账户为 P=0.03；6% 的无辜账户共用家庭地址或 IP；一栋可容纳 200 人的楼（A-77）内有约 15 个账户，其中包括一些尝试成员。
• 本地设置用示例数据集（data/demo，随机种子 42）：IBM 格式的交易数据，包含无辜账户背景数据和 16 个跨银行洗钱方案，涵盖 IBM 的 8 种模式。
• 根据反洗钱合规要求，项目中不包含任何真实个人的个人数据。

AI 工具使用披露

项目在 Claude Code（Anthropic）的协助下构建；它根据团队的指导编写了大部分代码，团队审查并理解了每个模块。运行时，Agent 通过 Groq 使用免费版大模型（撰写 Agent 使用 qwen/qwen3.8-27b，审计 Agent 使用 openai/gpt-oss-120b，该模型来自另一家供应商，规模也更大），并以 OpenRouter 的免费模型作为备用。

范围与设计说明

• 数据采用 IBM 的 AMLworld 基准数据集并加入了有文档说明的身份层；接入银行自己的数据流时，只需将数据加载到相同的图模型中（scripts/seed_all.sh 可接受任何 IBM 格式的 CSV）。
• 缺少 IBM 的 Patterns 文件时，系统会将相互关联的洗钱转账分组，近似表示洗钱尝试（每个结果文件中均有说明）。
• 线索引导的追踪使用图信号，而非论文中的 GNN。
• 联盟 ID 为加盐哈希值。ECDH-PSI 握手使用真实的 X25519 算术；在此部署中，两家银行的端均在同一个服务中运行，在生产环境中则由各银行分别运行。
• 飞地、刷卡终端和 VaultKey 均以软件设备孪生体运行（Wokwi 中的 ESP32），并使用真实加密技术（HMAC、SHA-384 PCR、ECDSA P-384/P-256、Ed25519、X25519）；实体 HSM、终端和密钥可接入相同的端点。EMV 应用密码（9F26）使用 HMAC。
• SAR 导出为供审核使用的 FinCEN-风格 XML，并非 BSA E-Filing 提交文件。
• 制裁筛查在配置 API 密钥时使用实时 OpenSanctions，未配置时则使用内置示例列表；仅基于姓名的匹配会通过出生日期或国家进行确认。
• Evaluation 页面上的阈值探索器基于运行中的数据子集运行，该子集与模型训练数据有重叠，因此其数值偏乐观；留出测试结果见 E1 的表格。

许可证

MIT，详见 LICENSE。