fin-trace
yiwufen/fin-trace
DeepSeek Harness (dsh) plugin embedding the fin-trace agent loop — multi-hop relationship reasoning over a financial knowledge graph, exposed as async tools (start/status/cancel)
Installation
dsh plugin --profile web add github:yiwufen/fin-traceREADME
Graph Explorer
金融知识图谱上的多跳推理 Agent
Web 应用 · A2A Agent · MCP 服务 · 自主探索 · 每一步都有 KU ID 可查证
LLM 告诉你"宁德时代是电池龙头"。
Graph Explorer 告诉你"宁德时代的匈牙利供应商里，谁在同时向被制裁的俄罗斯实体供货，传导路径经 过哪些中间节点，每一步的证据在哪。"
这是让 AI 从"知道"到"调查"的跨越。
Demo
Playground
直接在浏览器里试用，无需本地部署：
限量 10 次使用（分享令牌，见下方产品形态）。
产品形态
Graph Explorer 以一个进程（:3001）同时提供四种接口：
| 接口 | 说明 |
|---|---|
| Web 应用 | 聊天式调查界面：邀请码注册、多会话管理、管理后台（/admin，用户/邀请码/分享令牌/设置）、分享链接（/s/:token，可限次）、公开 Landing page、移动端 PWA |
| A2A Agent | graph_explore skill，Agent Card 见 /.well-known/agent-card.json，供 Host Agent（如 OpenClaw）异步调用 |
| MCP 服务 | /mcp 暴露 graph_explore_start/status/cancel（异步提交 + 轮询） |
| HTTP API | /api/*，驱动 Web 前端（认证、会话、管理、分享、设置） |
本文档其余部分聚焦核心：多跳探索 Agent 本身。
问题
大模型能回答"什么是供应链风险"，但无法回答：
某车企的二级供应商里，哪些同时暴露在美国出口管制清单中？传导路径是什么？每一步的证据在哪？
这不是知识检索，这是调查。它要求：
[种子实体] [跳 1] [跳 2] [跳 3]
│ │ │ │
宁德时代 ──投资──→ 匈牙利 Supplier X ──采购──→ 美国受限原材料
│ │
└──供应──→ 德国 BMW ←──── 制裁传导 ────┘
每一步都是独立的图谱查询，每条边都需要 KU ID 锚定。直接问 LLM，它会在单次推理中"跳步"——编造看似合理的中间节点，给你一段漂亮的文字而不是一份可审计的调查结果。
它做什么
┌─────────────────────────────────────────────────────────┐
│ 一次 graph_explore 调用 │
│ │
│ 输入: goal + seed_entities + max_depth │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Think │ ──→ │ Act │ ──→ │ Observe │ ──→ ... │
│ │ 策略决策 │ ←── │ 图谱查询 │ ←── │ 结果分析 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ ↑ ↑ ↑ │
│ └───────────────┴───────────────┘ │
│ 一次完整调查约 3-12 分钟（步数/预算驱动） │
│ │
│ 输出: findings + event_threads + exploration_meta │
└─────────────────────────────────────────────────────────┘
不是一个数据库查询（~1s），而是一个完整的调查任务（通常 3-12 分钟；时长由步数预算与充分性门控决定，Agent 自主收敛）。Agent 自主决定每一步查什么、往哪个方向走、何时收敛。
| 场景 | 能回答的问题 |
|---|---|
| 供应链风险 | 某车企供应商体系里，谁在给被制裁实体供货？传导路径经过哪些中间节点？ |
| 政策传导 | 欧盟碳关税 → 哪些中间环节 → 最终影响南方航空的运营成本？ |
| 重叠暴露 | 宁德时代和比亚迪的供应商有多少重叠？谁更依赖高风险供应商？ |
| 事件因果 | 某房企违约后，哪些城投平台的融资成本出现了连锁反应？ |
| 关系验证 | A 和 B 声称合作，但它们之间到底有没有实际投资或采购证据？ |
一句话：当问题需要"从 A 走到 D，经过 B 和 C，且每一步都要有证据"，用 Graph Explorer。
为什么不用 LLM 直接问
┌──────────────────────────────────────────────────────────────────────┐
│ 直接问 LLM │
│ 输入 ──→ 单次推理（黑盒） ──→ 一段漂亮文字 │
│ ✕ 无实时数据 ✕ 可能跳步/编造 ✕ 无引用来源 │
└──────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────┐
│ Graph Explorer │
│ 输入 ──→ Think→Act→Observe ×N轮 ──→ findings + threads + meta │
│ ✓ 实时图谱 ✓ 每跳可审计 ✓ 每条可追溯到 KU ID │
└──────────────────────────────────────────────────────────────────────┘
| 直接问 LLM | Graph Explorer | |
|---|---|---|
| 数据 | 训练截止日，无私有数据 | 实时金融知识图谱 |
| 推理 | 单次推理，长链易跳步 | 每跳一次图谱查询，路径可审计 |
| 证据 | 无引用 | 每条发现附带 KU ID |
| 输出 | 自然语言，需人工整理 | 结构化 JSON，可被下游消费 |
核心差异：可追溯。 不是"AI 说有关系"，而是"AI 找到了一条路径，每一步都有 KU ID 可以查证。"
30 秒开始
git clone <repo-url> && cd fin-trace
cp config.example.json config.json # 填入 LLM API key（首次启动也会自动生成）
npm install && npm run dev # 构建前端并启动，监听 :3001
启动后浏览器访问 http://localhost:3001 即为 Web 应用（聊天界面；管理后台在 /admin）。
A2A 集成（推荐）
fin-trace 是 A2A Agent，暴露 Agent Card 供 Host Agent 自动发现。启动后即可通过 A2A JSON-RPC 调用：
GET http://localhost:3001/.well-known/agent-card.json # Agent Card
POST http://localhost:3001/a2a # A2A JSON-RPC
直接连接知识图谱（调试用）
如需直接调 KG MCP 服务调试：
{
"mcpServers": {
"knowledge-graph": {
"transport": "streamable-http",
"url": "https://kg.yiyiyiwufeng.cn/mcp"
}
}
}
Host Agent 集成（OpenClaw）
fin-trace 是 A2A Agent（3-20 分钟任务），通过 Agent Card 自动发现。OpenClaw 的 sessions_spawn 封装了 A2A 协议，Host Agent 以 spawn + yield 模式调用：
// 1. 判断用户问题是否需要多跳推理
// 需要 → spawn 子 Agent；不需要 → 用 search_knowledge
// 2. spawn
session = sessions_spawn(
agent="fin-trace",
prompt="探索目标: <goal>\n起始实体: <entities>\n最大深度: 2"
)
// 3. yield，释放主 session
sessions_yield(wait_for=[session.id])
// 4. 被平台唤醒后，检查 exploration_meta.reliability_note
// 按 confidence 分层使用 findings，用自己的话回答用户
完整集成指令见
skills/fin-trace.md。
输入 → 输出一览
// 输入
{ "goal": "调查美国出口管制对宁德时代欧洲供应链的传导影响",
"seed_entities": ["宁德时代"], "max_depth": 3 }
// 输出（通常 3-12 分钟，Agent 自主收敛）
{
"findings": [{
"id": "f_001",
"category": "chain",
"statement": "宁德时代→Supplier X→BMW 供应链中，Supplier X 同时从美国采购受限原材料",
"confidence": "high",
"evidence": ["ku_20240315_001", "ku_20240315_045", "ku_20240601_122"]
}],
"event_threads": [{
"title": "制裁通过二级供应商传导至欧洲整车厂",
"narrative": "2024年3月美国商务部更新出口管制清单，Supplier X 原材料受限，进而影响 BMW 电池模组交付",
"thread_events": [
{ "ku_id": "ku_20240315_001", "entity": "美国商务部", "event_type": "sanction_update" }
],
"relationships": [
{ "from_idx": 0, "to_idx": 1, "type": "causal",
"reasoning": "管制清单更新直接导致 Supplier X 原材料受限" }
]
}],
"exploration_meta": {
"completion_reason": "sufficient",
"stats": { "steps": 7, "entities_visited": 23, "findings_count": 4 }
}
}
核心能力
┌────────────────────────────────────────────────────────────────────┐
│ │
│ ⚉ 自主多跳探索 ⚉ 四类结构化发现 │
│ 策略自决策，路径透明 chain · concentration │
│ 会扩展、会回退、会换方向 pattern_violation · absence │
│ │
│ ⚉ 事件脉络构建 ⚉ 生产级容错 │
│ 散落事件 → 因果故事线 多级降级 · 格式修复 · 收敛检测 │
│ 每段关系附带推理说明 Token 预算分池（config 驱动）· 多级压缩 │
│ │
│ ⚉ 不保证零幻觉，但保证可验证 ← 每条 finding 都有 KU ID │
│ │
└────────────────────────────────────────────────────────────────────┘
四类发现
chain 模式违规 集中度 缺失
────── ────── ────── ──────
A→B→C 的 预期 A 但 15家供应商里 尽管公开宣称
传导链路 找到了 B 12家有中断记录 合作，A和B之间
无直接投资证据
事件脉络
event_threads 不只是散落的事件列表——离散事件被串联成有因果、时序、共享实体关系的故事线，每段关系附带 reasoning，可追溯到 source_finding_ids。
容错
MCP 多级降级 → LLM 格式自修复 → 连续相同决策自动切换策略 → 多级压缩升级。一次查询失败不会中断整个调查。
架构
浏览器（Web 应用） 上游 LLM（OpenClaw 等 A2A 客户端） MCP 客户端
/api/* · 静态资源 · SSE a2a_send_task(target="fin-trace") /mcp
认证 · 会话 · 管理后台 a2a_task_status(taskId) graph_explore_start/status/cancel
│ │ │
└────────────┬─────────────┴──────────────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ Graph Explorer（:3001） │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Chat Loop（对话循环） │ │
│ │ 多轮对话 → 调用探索 / 直接回复 │ │
│ │ ↓ graph_explore │ │
│ │ Agent Loop │ │
│ │ │ │
│ │ EXPLORING │ │
│ │ ┌──────┐ ┌──────┐ ┌───────┐ │ │
│ │ │ Think │─→│ Act │─→│Observe│ │ │
│ │ └──────┘ └──┬───┘ └───┬───┘ │ │
│ │ ↑ │ │ │ │
│ │ └──────┴──────────┘ │ │
│ │ × N 轮 │ │
│ │ │ │
│ │ FINALIZE │ │
│ │ 构建 Threads → 验证 → 输出 │ │
│ └─────────────────────────────────┘ │
│ ↕ MCP（内部 KG 通信） │
│ ┌─────────────────────────────────┐ │
│ │ lookup · trace · timeline │ │
│ │ expand · scan │ │
│ │ (每个工具一跳语义邻接，组合涌现多跳)│ │
│ └─────────────────────────────────┘ │
│ │
│ ↕ MCP（内部） │
└──────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 金融知识图谱（内部 KG MCP 服务） │
└─────────────────────────────────────────┘
对外三种方式接入——浏览器直接用 Web 应用，Host Agent 走 A2A task lifecycle，MCP 客户端走 /mcp 异步工具。区别在于它不是一次查询，而是一个完整的自主探索循环，必须用异步方式调用。
设计原则
"库优于框架" — Agent Loop 全部在自己代码里，零框架依赖
单跳工具，多跳涌现 — 每个工具一次取一层语义邻接（KG 为实体-事件二部图，一条关系 = 两条边，详见
design-docs/tools.md），复杂推理从 Agent Loop 的组合调用中涌现配置解耦 — 知识图谱地址、LLM endpoint 均在
config.json，不硬编码证据链完整 — Finding 必须有 KU ID 支撑；Thread 必须验证
ku_id存在性
项目结构
src/
├── index.ts # 服务入口：HTTP + A2A + MCP + 静态托管
├── api.ts # HTTP API（/api/*：认证、会话、管理、分享、设置）
├── mcp-server.ts # 出站 MCP 服务（/mcp：graph_explore_start/status/cancel）
├── account-handler.ts # 账户注册（邀请码）
├── user-store.ts # 用户存储（data/users.json）
├── auth/ # 密码哈希 · 会话 · Cookie
├── settings-store.ts # data/settings.json（admin_token、邀请码、密钥覆盖）
├── share-store.ts # 分享令牌（/s/:token）
├── session-store.ts # 会话持久化
├── static-files.ts # web/dist/ 静态托管
├── logger.ts
├── a2a/ # A2A 协议：agent-card · JSON-RPC 路由 · Task 存储 · SSE
├── agent/ # 核心：Agent Loop（EXPLORING → FINALIZE）
│ ├── loop.ts / state.ts / prompt.ts
│ ├── tools.ts # 5 个 KG 工具（内部 MCP）
│ ├── mcp-client.ts / findings.ts / threads.ts
│ └── context.ts / error-handler.ts / config.ts
├── chat/ # 对话循环（多轮对话，调用 agent）
├── llm/ # LLM 客户端（OpenAI-compatible）
└── tool-categories.ts
web/ # 前端 workspace（Vite + React + Tailwind，PWA）
eval/ # Golden set 评测框架（run | judge | report）
tests/e2e/ # 冒烟场景（捕获输出）
design-docs/ # 核心设计文档
docs/ # 部署指南 + 历史 spec/plan
skills/ # 跨平台 skill 定义（fin-trace.md）
License
GNU Affero General Public License v3.0 — 使用本项目或基于本项目的衍生作品，通过计算机网络提供服务的，必须开源全部源代码。
Ähnliche Plugins
WeKnora (dsh-weknora)
tencent/weknora
weknora
tencent/weknora
archify (deepseek-harness)
tt-a1i/archify
BrowserSkill (dsh-plugin-browserskill)
tencent/browserskill