个人站点：www.loginext.cn

FreightBI：货代经营分析垂直智能体——技术选型、设计思想与为什么不是「BI + ChatGPT」

摘要：货代企业「有数据、没结论」是长期痛点。FreightBI 不是再造一套 BI，也不是聊天 Copilot，而是一条围绕经营分析任务设计的垂直智能体工作流。本文从动机、设计思想、技术架构三个层面，介绍我们为什么做、参考了哪些理念、以及如何在 Electron 桌面端落地，结尾提供windows版本安装包。

一、先讲清楚：我们在做什么

FreightBI 是一个面向货代企业的 AI 数据分析智能体。

一句话定义：

从 Excel、ERP/FMS 导出表里，整理出可信的经营分析结果，自动生成专业分析报告和汇报 PPT，并提供可追溯的市场/行业参考对比。

它要解决的不是「怎么画一张图」，而是货代老板每月都在问的五个问题：

  1. 本月收入、毛利、TEU 到底如何？
  2. 哪条航线「量涨了、利跌了」？
  3. 哪个客户收入高但利润贡献低？
  4. 费用结构有没有异常波动？
  5. 是我们自己做差了，还是市场都这样？

这些问题的共同特征是：数据分散、格式非标、口径要人拍板、结论要能拿去开会——这不是通用 BI 或聊天 AI 擅长的事。

二、为什么做这个智能体：任务形态决定了产品形态

2.1 四类相邻方案，各自只解决一角

方案 擅长 卡在哪
通用 BI 标准数据的可视化 不懂货代口径，吃不下「表头在第 3 行」的 Excel
ERP/FMS 内置报表 业务单据流转 管单子，不管「企业整体赚没赚钱」
数据咨询 专业深度 按项目交付，无法「每月上传、自动复用」
通用大模型Chat 自然语言交互 算数不能交给模型，口径不能靠猜，结论不能只给一段话

货代企业往往已经有 ERP/FMS，但系统解决的是「业务运营数字化」，经营分析智能体解决的是「管理层决策数字化」——两者相关，但不是同一个问题。

ERP/FMS 能记账，为什么做不了经营分析？

  • 系统建来「管单子」，不是「看利润」：内置报表多是未收未付、单票毛利、业务量统计，老板关心的整体毛利率、航线贡献、客户集中度往往不在默认菜单里。
  • 数据天然是「碎的」：业务流水在 FMS 导出表，费用在财务 Excel，销售台账在 CRM——系统只守住自己那一摊，吞不下系统外的分摊表和临时快报。
  • 收入与成本的「口径战争」：操作看报价收入，财务看确认收入；含税/未税、代收代付是否计入毛利——分析层必须允许企业在接入阶段明确确认，这不是录单系统的设计重心。
  • 操作报表 ≠ 管理层汇报材料：老板要的是带执行摘要的经营报告和固定模板 PPT，不是再开一个系统菜单看数字。

FreightBI 不替代 ERP/FMS，而是承接其导出数据，补上「月报最后一公里」。

2.2 为什么是「智能体」，而不是功能模块堆叠

经营分析是一条有状态、多阶段、必须人机协同的任务链：

flowchart LR A[上传文件] --> B[识别结构] B --> C[建议映射] C --> D[确认口径] D --> E[标准化入库] E --> F[算指标] F --> G[异常规则] G --> H[市场参考] H --> I[写洞察] I --> J[装配报告] J --> K[生成 PPT]

任何一环的结果都会影响下一环。这不是单次 API 调用能完成的，而是需要：

  • 工作流编排（条件分支、挂起、恢复）
  • 状态持久化（映射确认到一半，明天继续）
  • 人机协同（低置信度映射必须停下来等人）
  • 交付物导向（PDF/PPT，不是聊天记录）

所以我们选择做垂直智能体，不是因为赶 AI 热点，而是因为任务本身具备智能体最擅长的特征。

2.3 三条核心判断

  1. 需求真实且高频：月报、周报、临时汇报是刚性场景
  2. 技术边界清晰：算数交给代码、口径交给人、语言交给模型
  3. 壁垒可逐步积累：映射规则复用、指标沉淀、行业样本——用得越多，越懂这家企业

三、设计思想：我们参考了哪些理念

FreightBI 的设计融合了近几年 AI 应用工程里几条被反复验证的路径。

3.1 「规则做事实，工作流做编排，模型做语言增强」

这是整个系统的第一性原理：

层级 职责 实现方式
规则引擎 收入、毛利、TEU、异常检测 TypeScript 确定性代码
工作流 节点编排、挂起/恢复、降级分支 SQLite 状态机 + IPC 进度
大模型 Sheet 语义理解、洞察文案、PPT 摘要 DeepSeek API

为什么这样分？

  • 算数不能交给模型：毛利率错一个小数点，老板就不会再信第二次
  • 口径不能靠猜：收入含税还是未税，40 尺柜算几个 TEU——模型再聪明也不能替财务拍板
  • 结论不能只给一段话：老板要的是能开会的报告和 PPT

这条原则借鉴了 Neuro-symbolic AI 的思路：符号系统（规则）管精确计算，神经网络（LLM）管语义理解和自然语言生成，二者各司其职。

可信设计的四条铁律：

  1. 规则做计算，AI 做解释
  2. 所有结论必须可追溯
  3. 不确定的数据必须允许人工确认
  4. 优先输出可信结果，再追求自动化程度

3.2 LangGraph 式有状态工作流

在智能体工作流设计中，我们明确参考了 LangGraph 的编排模型：

  • 每个节点有清晰的输入/输出
  • 支持条件分支（低置信度 → 人工确认）
  • 支持挂起与恢复（await_user_confirmation）
  • 支持降级路径（LLM 失败 → 仅输出规则异常和基础报告）

建议的节点图如下：

flowchart TD S[scan_input] --> C[classify_sheets] C --> M[suggest_mappings] M -->|低置信度| W[await_user_confirmation] M -->|高置信度| A[run_analysis] W -->|用户确认后| A A --> I[generate_insights] I --> R[assemble_report] R --> P[generate_ppt_outline] P --> F[finish] I -->|LLM 失败| D[降级：规则洞察 + 基础报告] D --> R

当前落地形态是 Electron 主进程内的 TypeScript 状态机，而非 Python + LangGraph + Celery——原因是桌面单体交付、零运维，主进程异步任务 + IPC 进度事件已能满足首阶段需求。控制流与 LangGraph「节点 + 条件边 + 循环」语义等价，便于未来云化迁移。

这是典型的 Concept First, Implementation Pragmatic 做法：先对齐正确的抽象，再选最贴合交付形态的实现。

3.3 Loop Engineering：行业对比 Agent

行业 benchmark 是经营分析里最容易「幻觉」的地方。我们彻底禁止了无公开来源的硬编码数字，行业参考 Agent 参考 Loop Engineering 模式：

flowchart TD A[Observe: 企业指标快照] --> B[Plan: 确定性检索词] B --> C[Act: 智谱 Search-Std / 百度·必应] C --> D[Extract: 从摘要抽取数值] D --> E[Verify: 校验来源与置信度] E --> F{3 项指标齐全 或 检索达 5 次?} F -->|否且 loops < 3| B F -->|是| G[Synthesize: 写入 report_benchmarks] G --> H[Finish: benchmark_status + detailNote]

关键设计决策：

  • Plan 阶段用确定性逻辑，避免 LLM 乱编检索词
  • Verify 阶段独立校验，Extract 和 Verify 分离（类似 Self-RAG / CRAG 的思路）
  • 检索失败时明确标注「行业参考不可用」，禁止编造 benchmark
  • 单次报告分析 智谱 Search-Std 最多 5 次，超出后停止新检索

3.4 Human-in-the-Loop：数据质量分级

数据质量分级（A/B/C/D）是 Human-in-the-Loop 思想的直接体现：

等级 含义 后续动作
A 结构完整、口径已确认 正常生成报告
B 有少量警告 允许分析，报告中标注质量说明
C 勉强可分析 需用户确认是否继续，结论降级表达
D 不可分析 阻断正式报告，仅输出扫描结果与修正建议

系统在数据不足时「敢说不知道」，而不是硬凑一份看起来专业的报告。

3.5 Local-First：为什么做成 Electron 桌面客户端

FreightBI 以 Electron 桌面安装包交付（Windows / macOS / Linux），安装在使用者自己的电脑上。

考量 桌面客户端 浏览器 SaaS
数据敏感 经营明细不出本机 需上云、IT 审批
工作流入口 ERP 导出 → 本地 Excel 反复上传下载
使用者 一个人操作，文件流转给老板 需账号体系、权限后台
研发聚焦 接入、规则、洞察、导出 租户、云端存储、协作

货代月报的真实制作方式是：运营负责人在自己工位上拼数据、出材料，老板通过 PDF/PPT 看结论——「操作一个人，服务一群人」。

这是 Local-First Software 理念在垂直 B 端场景的应用。

3.6 任务型 Agent vs 对话型 Copilot

FreightBI 智能体的目标不是自由聊天，而是围绕「完成一次经营分析任务」设计：

  • 输入：Excel 文件
  • 中间：映射确认、质量决策
  • 输出：报告 PDF + 固定模板 PPT + 异常清单

这借鉴了 Agent = Task Completion System 的定义，而非 Agent = Chatbot with Tools。

四、技术架构：如何在 Electron 里落地

4.1 技术栈一览

Electron 42 · electron-vite · React 19 · TypeScript · Vite 7
Ant Design 5 · @ant-design/charts · Zustand · better-sqlite3 · xlsx
DeepSeek（LLM）· 智谱 Search-Std（行业联网检索）
html2pptx-pro / pptxgenjs（PPT 导出）

4.2 进程与模块边界

flowchart TB subgraph Renderer["Renderer（React + Ant Design）"] P1[上传 / 映射确认] P2[报告查看 / 设置] P3[导出任务] end subgraph IPC["preload → contextBridge → IPC"] API[window.api] end subgraph Main["Main Process（TypeScript 业务内核）"] direction TB ING[ingestion/ 解析·扫描·映射·标准化] ANA[analysis/ 指标·异常·规则洞察] AGT[agent/ Benchmark Loop·检索工具] LLM[llm/ DeepSeek 调用] RPT[report/ 报告装配] EXP[export/ PDF·PPT] DB[(SQLite 映射规则·工作流·报告)] end Renderer --> API --> Main ING --> ANA --> RPT --> EXP ANA --> AGT AGT --> LLM Main --> DB

无独立后端服务、无 Redis/Celery——异步通过主进程任务 + IPC 进度事件完成。

4.3 三层业务架构

flowchart TB subgraph 接入层 A1[Excel/CSV 上传] A2[结构扫描 · Sheet 分类] A3[字段映射 · 用户确认] A4[标准化入库] end subgraph 分析层 B1[指标聚合] B2[规则异常检测] B3[历史对比] B4[市场/行业参考检索] end subgraph 输出层 C1[在线经营分析报告] C2[PDF 导出] C3[固定模板 PPT] C4[风险清单与行动建议] end 接入层 --> 分析层 --> 输出层

模块间严格分层：ingestion/ → analysis/ → report/ → export/，数据标准化与智能体解耦。

4.4 目录结构（与代码映射）

src/
  main/                    主进程业务内核
    services/
      ingestion/           解析、扫描、映射、标准化、质量评分
      analysis/            指标聚合、异常规则、规则洞察
      agent/               Benchmark Loop Agent、检索工具
      llm/                 DeepSeek 调用、洞察生成
      report/              报告装配、叙事结构
      export/              PDF、PPT（HTML 离屏渲染 + 原生 deck）
    db/                    SQLite 持久化
    ipc.ts                 IPC 通道映射
  preload/                 contextBridge 桥接（类型安全）
  renderer/                React 渲染层（页面/组件/store）
  shared/                  跨进程共享类型

4.5 几个值得展开的技术细节

半自动非标准数据接入

真实货代 Excel 的乱象：多 Sheet 混排、表头在第 4 行、合并单元格、「应收」「海运费」「Ocean Freight」并存。采用「结构扫描 + 规则初判 + 语义候选 + 人工确认」，一次确认、多次复用——映射规则存 SQLite，下月换文件自动加载。

规则驱动的异常检测

首阶段覆盖五类异常：概览、航线、客户、成本、数据质量。例如：

规则 ID 逻辑 默认阈值 优先级
GP_MOM_DROP 毛利率环比下降超过阈值 20% 高
TEU_COST_UP 单 TEU 成本环比上涨超过阈值 15% 高
NEG_ROUTE_PROFIT 某航线毛利为负且收入占比超阈值 10% 高
TOP3_CONC_RISK Top 3 客户收入占比超阈值 40% 中
COST_TYPE_SPIKE 某费用类型环比上涨超阈值 25% 中

异常由规则引擎触发，LLM 只负责解释异常含义和建议动作。

PPT 导出管线

  • 固定模板 + 规则计算结果绑定图表数据
  • LLM 生成标题与摘要文案
  • HTML 离屏渲染 → 截图 → 装配 PPTX

保证「数字来自代码，语言来自模型」的分工在最终交付物里依然成立。

降级策略

场景 行为
LLM 调用失败 走规则洞察 + 基础报告
行业检索 5 次仍不足 benchmark_status = partial，明确标注
数据质量 D 级 阻断正式报告，不生成盈利结论
Verifier 拒绝 不写入市场值，禁止编造 benchmark

五、业务场景：智能体如何跑通一条月报

场景 A：月度经营复盘（正常闭环）

背景：10 月底，运营负责人上传《华东货代_10月经营明细.xlsx》，准备周五经营会材料。

  1. 上传文件 → 系统扫描识别 2 个有效 Sheet，跳过「说明」页
  2. 加载历史映射 → 自动匹配 92% 字段，仅「杂费合计」需人工确认
  3. 确认口径 → 收入未税、40HC=2TEU，质量评级 B，允许分析
  4. 计算指标 → 收入 1,286 万、毛利率 18.2%、TEU 6,840
  5. 规则引擎触发 → 东南亚线负毛利；毛利率环比下降 22%
  6. 行业参考检索 → 公开来源显示东南亚运价指数环比上涨 8%，本企业降幅更大，倾向内部成本问题
  7. 生成报告与 PPT → 首页摘要 3 条发现、2 条风险、3 条行动建议

验证点：老板能否在 10 分钟内抓住「整体尚可、东南亚线需专项排查」的结论？

场景 B：数据质量不足（阻断分析）

背景：新客户首次上传，仅有汇总透视表，无业务单号明细。

  1. 系统扫描 → Sheet 类型为 summary_report，置信度 0.95
  2. 质量评级 D → 缺少主键与成本字段
  3. 阻断正式报告，输出修正建议：「请提供含业务单号的流水明细及费用分摊表」
  4. 智能体降级 → 不生成盈利结论，不输出行业 benchmark 对比

六、我们刻意不做的事

清晰的产品边界，和清晰的能力边界一样重要。FreightBI 首阶段明确不做：

  • 任意格式文件零配置全自动分析
  • 替代 ERP/FMS
  • 无公开来源支撑的行业 benchmark
  • 企业级多组织权限体系
  • 复杂预测与定价优化

北极星目标：让货代企业管理层在 10 分钟内看清本期经营真实情况，并基于系统生成的报告或 PPT 做出经营判断。

种子客户画像：

  • 年营收 5000 万–5 亿，员工 20–200 人
  • 已有月报习惯但依赖 Excel 人工整理
  • 老板有经营会/复盘需求，愿意试用「报告直出」体验

七、写在最后：垂直智能体的机会窗口

2024 年以来，大模型在语义理解、摘要生成、多步推理上已足够支撑「辅助读表、辅助写报告」；同时货代行业数字化程度提升，企业手里有了大量 Excel 和系统导出数据，却仍然缺「从数据到结论」的最后一公里。

FreightBI 的选择可以概括为：

不是给 BI 加一个 ChatGPT 插件，也不是再造一套货代系统，而是围绕货代经营分析任务从头设计的垂直智能体。

技术上是 Electron + React + TypeScript 的桌面单体；设计上是规则引擎 + 工作流编排 + LLM 语言增强的三层分工；产品上是任务完成型 Agent + Human-in-the-Loop + Local-First 的可信交付。

如果你也在做垂直领域的 AI 应用，欢迎在评论区交流：你的场景里，「算数、口径、语言」是怎么分工的？

关于项目

项目 内容
产品名称 FreightBI
定位 面向货代企业的 AI 数据分析智能体
技术栈 Electron · React 19 · TypeScript · Ant Design · SQLite
交付形态 Windows / macOS / Linux 桌面安装包
外部依赖 DeepSeek（LLM）、智谱 Search-Std（行业联网检索），Key 由使用者自行配置

系统下载地址：freightbi-1.0.0-win-x64

系统导出PPT文档：PPT汇报

ScreenShot_2026-06-30_163911_929

2026-06-30_164048

ScreenShot_2026-06-30_164303_800

posted on 2026-06-30 19:38  天涯轩  阅读(19)  评论(0)    收藏  举报

导航