fin-trace

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

[图片: Node.js ≥ 20]

  [图片: License: AGPL v3]

  [图片: Status: Active]

Graph Explorer

金融知识图谱上的多跳推理 Agent

Web 应用 · A2A Agent · MCP 服务  ·  自主探索  ·  每一步都有 KU ID 可查证

---

> LLM 告诉你"宁德时代是电池龙头"。
>
> Graph Explorer 告诉你"宁德时代的匈牙利供应商里，谁在同时向被制裁的俄罗斯实体供货，传导路径经
> 过哪些中间节点，每一步的证据在哪。"
>
> **这是让 AI 从"知道"到"调查"的跨越。**

---

## Demo

  [图片: Graph Explorer Demo]

### Playground

直接在浏览器里试用，无需本地部署：

> 🔗 https://fin.yiyiyiwufeng.cn/s/6ivLlHN0i-ivP-NBO8ZB2kpb

限量 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 秒开始

```bash
git clone  && 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 服务调试：

```json
{
  "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="探索目标: \n起始实体: \n最大深度: 2"
)

// 3. yield，释放主 session
sessions_yield(wait_for=[session.id])

// 4. 被平台唤醒后，检查 exploration_meta.reliability_note
//    按 confidence 分层使用 findings，用自己的话回答用户
```

> 完整集成指令见 [`skills/fin-trace.md`](skills/fin-trace.md)。

**输入 → 输出一览**

```json
// 输入
{ "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](LICENSE) — 使用本项目或基于本项目的衍生作品，通过计算机网络提供服务的，必须开源全部源代码。