SYSTEM ARCHITECTURE · FINANCIAL AGENT · DEMO.ZHUYUNYIN.COM

从一份原始文档,到一句可追溯的结论

面向金融研究的确定性证据系统:把 SEC 财报、卖方研报、业绩电话会与产业智库, 切成物理可定位的原文片段,编译成公司知识主页,并在多跳推理时让每个数字都能点回原件页码。

justbugs/dsh-financial-agent DeepSeek Harness 纯插件端 · Apache 2.0
原生 MCP 规范服务化 · 混合记忆底座 (Tri-Store) · 零心算幻觉
$ git clone https://github.com/justbugs/dsh-financial-agent.git
前往 GitHub
1,088高纯度切片
52图谱实体
61带溯源三元组
0悬空引用
45回归门禁

01整体数据流

系统由两条时间线构成:离线编译(文档进门 → 三态底座 + Wiki)与在线问答(提问 → 可溯源结论)。 两条线共享同一份证据底座,因此在线阶段的每个引用都能锚定到离线阶段切出的物理位置。

💡 交互提示:点击流程图中任意方框节点,即可立即弹出查看真实的底层切片、代码或计算实例 支持键盘 ESC 关闭 · ← → 键切换
flowchart TB
    subgraph SRC["① 文档接入"]
        direction LR
        A1["SEC 归档
10-K / 10-Q"] A2["卖方研报
大摩 / 高盛 / 巴克莱"] A3["业绩电话会
高管前瞻与供给答疑"] A4["产业智库
TrendForce 等"] end subgraph ING["② 解析与切片"] direction LR B1["结构解析
页码 / 章节 / 评级"] B2["语义切片
句窗 · 长度约束"] B3["质量闸门
去重池 · 噪声过滤"] B4["页码映射
表单类型注册表"] end subgraph STORE["③ 三态证据底座"] direction LR C1["文本证据库
全文索引 + 时间截断"] C2["时序量化库
列存行情分析"] C3["实体关系图
带出处的三元组"] end subgraph COG["④ 编译层"] direction LR D1["公司知识主页
零 Token 目录树"] D2["实体归一与别名
双向种子归一化"] end subgraph ASK["⑤ 在线问答"] direction LR E1["粗筛召回
词法 + 行业渗透"] E2["图谱扩散
多跳因果重排"] E3["确定性复算
AST 纯算术沙箱"] E4["事实门禁
NLI 蕴含判定"] end subgraph RES["⑥ 最终产出"] direction LR OUT["可追溯研究报告
带原件证据链接 · 零心算幻觉"] end A1 --> B1 A2 --> B1 A3 --> B1 A4 --> B1 B1 --> B2 --> B3 --> B4 B4 --> C1 B4 --> C3 C1 --> D1 C3 --> D2 D1 --> E1 C1 --> E1 E1 --> E2 E2 --> E3 E3 --> E4 C2 --> E3 E4 --> OUT click A1 call openExampleModal("A1") "查看 SEC 归档实例" click A2 call openExampleModal("A2") "查看 卖方研报实例" click A3 call openExampleModal("A3") "查看 电话会纪要实例" click A4 call openExampleModal("A4") "查看 产业智库研报实例" click B1 call openExampleModal("B1") "查看 结构元数据解析实例" click B2 call openExampleModal("B2") "查看 语义句窗切片实例" click B3 call openExampleModal("B3") "查看 质量闸门过滤实例" click B4 call openExampleModal("B4") "查看 物理页码映射注册实例" click C1 call openExampleModal("C1") "查看 SQLite FTS5 证据库实例" click C2 call openExampleModal("C2") "查看 时序量化行情查询实例" click C3 call openExampleModal("C3") "查看 实体关系三元组实例" click D1 call openExampleModal("D1") "查看 公司知识主页 Wiki 实例" click D2 call openExampleModal("D2") "查看 实体归一化别名映射实例" click E1 call openExampleModal("E1") "查看 粗筛召回与行业渗透实例" click E2 call openExampleModal("E2") "查看 HippoRAG 图扩散重排实例" click E3 call openExampleModal("E3") "查看 确定性复算沙箱实例" click E4 call openExampleModal("E4") "查看 事实蕴含门禁判定实例" click OUT call openExampleModal("OUT") "查看 可追溯研究报告输出实例" classDef src fill:#141b28,stroke:#2c3a52,color:#c9d4e8 classDef ing fill:#141b28,stroke:#3a5c8a,color:#c9d4e8 classDef sto fill:#121a2b,stroke:#4c9aff,color:#dce7fb classDef cog fill:#161428,stroke:#7c5cff,color:#ded6ff classDef ask fill:#111d1a,stroke:#2ecc8f,color:#d3f5e6 classDef out fill:#231a12,stroke:#f5a623,color:#ffe8c9 class A1,A2,A3,A4 src class B1,B2,B3,B4 ing class C1,C2,C3 sto class D1,D2 cog class E1,E2,E3,E4 ask class OUT out
快速节点实例选择器 (点击立即展开对应样例)

两条时间线共享同一底座 · 在线阶段的每个引用都可锚定到离线切片的物理位置

02核心子系统与深度解构

点击上方或下方模块标签,随时切入各子系统的详细实现规范、踩坑治理策略与核心元数据表格。

文档接入与高精度切片流水线

这是整个系统的地基——下游所有能力的上限,都由这一步的切片质量与物理锚定决定。

Stage 1 · Parse

多格式高保真结构解析

按来源自适应分派解析器:PDF 走 PyMuPDF 高速逐页提取,SEC 归档走标准章节识别,Markdown 走语义层级。 自动提取券商、评级、目标价、发布日期元信息,为后续时序截断与横向共识矩阵提供基础。

Stage 2 · Chunk

Sentence-Window 语义窗口切片

抛弃机械定长切分,以 2~3 句为核心窗口,外延包含上下文窗口,并维持 120~350 字符约束。 每个切片自包含物理页码、章节名及事件时间/发布时间双时间戳,绝不产生无谓词碎片。

Stage 3 · Quality Gate

质量闸门与单事务原子去重 ← 重点踩坑治理

噪声过滤:剔除表单复选框(☒)、无实质内容的短标题(<80 字符且无动词数字)、通用免责声明。
原子入库事务:内存中预先生成并校验全量切片,DB 删除与写入被严格包裹在单事务中(with conn:),杜绝异常时出现旧数据已删、新数据未进的空洞。

Stage 4 · Locate

SEC 真实报告页码注册表 ← 典型架构演进

SEC EDGAR 原生 HTML 无分页注释,早期曾导致整份 10-K 的 800+ 切片全部堆在 P1。
现在将映射抽象为按表单类型解耦的注册表(10-K / 10-Q / 8-K 各独立维护),支持运行时动态注册新表单,彻底解决了换文档类型即失效的问题。

这一层的设计取舍:宁可少切,不可切错。 碎片切片的代价是双重的——它既污染检索结果,又在图谱里制造虚假共现。质量闸门必须放在入库之前,而不是事后清理。

三态物理底座设计

金融数据形态差异巨大,通用存储必然妥协。系统将数据解耦为三个物理独立的专用引擎:

Store A · Text

态 1:文本证据库 (SQLite FTS5 + 双时间戳)

全文倒排索引 + 结构化元数据。支持按标的、类型、年份及发布时间硬截断。
时间截断是物理级防前视偏差的核心设计:指定 as_of_date 时,任何晚于基准日发布的数据绝不进入候选池。

文档类型切片数量核心覆盖范围
10-K 年报570 条三大审计报表、MD&A、分销与供应链、附注
10-Q 季报218 条季度财报、最新监管诉讼、未结清款项
卖方 / 产业研报268 条大摩、高盛、巴克莱、伯恩斯坦、TrendForce
业绩电话会23 条Q4 FY24 财报电话会高管问答全文
新闻与监管9 条欧盟 DMA 法案调查、反垄断进展
Store B · Timeseries

态 2:时序量化库 (列存行情与技术面)

列式存储的高频日线与分钟线,用于估值锚定与技术面统计。计算下推至存储层执行向量化聚合,避免将千万级行情数据反序列化至上下文。

Store C · Graph

态 3:实体关系图 (SQLite Graph · 悬空引用 = 0)

当前包含 52 个核心实体 / 61 条因果三元组。悬空引用率为 0%——每条边必须绑定一个真实存在的证据切片 ID,这是系统的硬约束。

为什么“悬空引用 = 0”是不可妥协的底线?

图谱中最致命的隐患不是漏边,而是边的出处指向了不存在的片段或占位符。这会导致下游模型看似有据可查,实则推理链建立在空中楼阁之上。 系统在入库与归一化时提供三态诊断暴露:

状态含义诊断意义
matched图谱中存在且具备活跃边正常参与 Personalized PageRank 扩散
registered_isolated已在实体表登记但度数为 0明确暴露结构性缺边,绝不隐瞒
unmatched完全未被识别暴露词表与同义词映射缺口

编译层:公司知识主页 (Wiki)

在检索之上再叠一层零 Token 消耗的确定性编译产物——把一家公司的核心事实固化成结构化看板, 让后续分析无需从零翻找万行语料。

Compiled Artifact

公司知识主页的核心构成

  • 核心审计财报大盘:三大表摘要、同比增幅、分部营收,每个数字精确绑定原件页码。
  • 无损骨架目录树 (TOC):章节 → 真实物理页码 → 文档指纹 (Hash),附带定向检索命令。
  • 量纲与底表锚点:显式给出底表拆解公式与量纲缩放因子(例如百万换算为十亿显式包含 / 1000)。
  • 业绩会与产业前瞻信号:高管供给指引、DRAM/NAND 成本通胀预警。
  • 卖方横向共识矩阵:大摩、高盛、巴克莱目标价、P/E、ASP、出货量口径横向对比。

目录树绑定文档指纹的必要性

页码映射是极度脆弱的:一旦重新解析导致分页漂移,整张目录树就会静默失效。比没有目录更糟的是让分析师自信地读错章节。 因此每个目录条目均绑定文档 SHA-256 内容哈希,一旦源文件变更便强制校验,防止分页漂移。

在线问答:四阶段确定性推理链

核心设计原则:让每一层只做它最擅长的事——词法负责高召回,图谱负责因果排序,沙箱负责算术,门禁负责事实一致性。

Stage 1 · Recall

粗筛召回 + 行业单向渗透

词法检索提供毫秒级高召回,并通过中文领域别名自动展开(如将“存储芯片涨价”自动转为 DRAM 相关检索式)。
行业渗透单向门禁:分析 Apple 成本时,检索范围允许向上下游半导体智库(TrendForce)单向渗透,但严禁渗透进入 SEC 官方财报科目,防止非审计估算污染官方财务底表。

Stage 2 · Rank

HippoRAG 个性化拓扑扩散 (PPR)

以查询种子为激活源,在加权因果图上进行随机游走重排。针对 Apple、NVIDIA 等 Super-Hub 实体施加 0.15 初始能量阻尼与度数平滑, 确保激活能量精准流向具体的业务因果链(如 DRAM 供给紧缺 → 现货涨价 → 硬件毛利承压)。

Stage 3 · Compute

确定性复算沙箱 (AST 安全求值)

报告中所有计算推导强制剥离出 LLM,交给专用的 Python AST 白名单沙箱求值。
严格限制为单行纯算术表达式(支持 abs, round, min, max, sqrt),硬拦截换行、赋值、模块 import,从根本上隔离任意代码执行(RCE)风险。

Stage 4 · Gate

事实蕴含门禁 (生成与裁决解耦)

由独立的本地判别模型裁决“证据切片是否真正蕴含该陈述”,打破模型自问自答的证实偏见。
对未校准的置信度采取保守宽松筛,避免硬阈值造成假阴性误伤。

底层技术选型与实现理由

所有核心组件均可在本地与无网隔离环境下独立闭环运行,不产生外部 API 计费依赖。

系统层级选用技术设计选型理由
文本证据库SQLite 3 (FTS5 + 触发器)单文件零依赖、进程内无 IPC 开销、强事务与双时间戳复合过滤
时序行情库DuckDB + Parquet 列存列式存储、向量化执行引擎,高频聚合与指标计算下推至存储层
图计算引擎纯 NumPy 矩阵幂迭代免装庞大图数据库,HippoRAG 扩散在 15ms 内收敛,随机游走完全可复现
算术校验器AST 白名单求值器零依赖、严格白名单函数约束,彻底阻断 Prompt 注入引致的任意代码执行
事实门禁本地轻量判别模型裁决与生成分离,私有化部署保障数据绝对不出内网
对外服务协议标准 MCP / JSON-RPC即插即用,任何合规客户端或命令行环境均可一键挂载

📦 获取完整开源插件端代码 GitHub

可直接通过 Git 克隆并在本地一键跑通全量 45 项单元与集成回归测试:

# 1. 克隆代码库
git clone https://github.com/justbugs/dsh-financial-agent.git
cd dsh-financial-agent

# 2. 安装依赖并运行全量测试
pip install -e .
python -m unittest discover tests