我用AI Agent从零搭了一个财报分析工具，拆给你看全过程

大象AI共学

52人浏览 · 2026-07-13 00:47:29

大象AI共学 · 2026-07-13 00:47:29 发布

你不需要资深开发经验。

这篇文章不是教你写代码，是教你怎么跟AI协作搭一个真实可用的工具——从模糊需求到模块拆解，从数据标准到校验防线。看完你就能自己动手。

ArkClaw-实操案例

先说结论：这个工具干了什么

老板扔给你一份200页的上市公司年报PDF，让你一小时把营收、净利润、负债率这些核心数据整理出来，写一份分析结论。

你手动翻PDF

找表格

摘录数字

半天搞不完，还容易抄错。

引用来源找不到页码，复核的时候想死的心都有。

我做了一个自动化工具：

上传PDF → 自动解析 → 自动提取指标 → 生成带页码来源的报告和表格。

所有数据100%可溯源，找不到的字段直接标"待人工复核"，绝不编数据。

最终产出不是一篇文章，是五个文件：

outputs/task-20260709-130602/
├── report.md          # 分析报告（给领导看）
├── metrics.csv        # 结构化指标表（Excel直接打开，继续加工）
├── evidence.json      # 全量证据链（每个数字从哪页哪个表格来的）
├── review-needed.md   # 待人工复核清单（AI不确定的数据汇总在这）
└── run-log.md         # 运行日志（出问题时回来查）

五个文件，各有用途。为什么要拆成五个，后面单独说。

第一步：别急着写代码，先把需求说清楚

很多人用AI搭工具第一步就错了——直接丢一句"帮我做个财报分析工具"给大模型，然后期望它返回完美成品。

不可能的。

正确的方式：先把需求变成一张清晰的产品地图，再让AI帮你一个模块一个模块地实现。

先看下全貌：

## 配置模块
目的：让入门用户完成基础部署。
包含：
API Key 配置。
模型供应商配置。
环境变量检查。
输出目录配置。
网盘或飞书授权状态检查。
验收：
用户执行一个检查命令后，能看到每一项配置是否通过。
密钥不在日志、报告和对话中明文输出。

## 文件接入模块
目的：统一处理本地 PDF、网盘文件和飞书文件。
输入：
本地文件路径。
文件夹路径。
文件链接。
飞书云文档或云空间路径，待 Arkclaw 环境确认。
输出：
标准化文件清单。
文件元数据：文件名、大小、页数、来源、任务 ID。
无法读取文件的错误说明。

## PDF 解析模块
目的：把 PDF 转成可供模型处理的文本块和表格块。
设计要求：
按页切分。
保留页码。
表格单独抽取。
对目录、封面、免责声明等低价值页面做降权。
对扫描件标注 OCR 置信度或解析失败。

## 指标抽取模块
目的：从文本和表格中提取结构化财务指标。
字段建议：
字段        说明        是否必填
company_name        公司名称        是
stock_code        股票代码，如可识别        否
report_year        报告年份        是
currency        币种        是
revenue        营业收入        是
net_profit        净利润或归母净利润        是
gross_margin        毛利率        否
operating_cash_flow        经营活动现金流量净额        是
total_assets        总资产        是
total_liabilities        总负债        是
debt_asset_ratio        资产负债率        否
r_and_d_expense        研发费用        否
source_page        来源页码        是
source_table        来源表格名        否
confidence        置信度        是
review_required        是否需要人工复核        是

## 数据校验模块
目的：降低模型幻觉和财务口径错误。
校验规则建议：
数值必须能追溯到原文或表格。
同一指标出现多个值时，优先使用合并报表口径，并标注口径。
毛利率、资产负债率等可计算指标要记录计算公式。
单位必须统一，例如元、万元、百万元、亿元。
年度、季度、半年度口径不能混用。
如果 PDF 中没有明确数据，不允许模型猜测。

## 报告生成模块
输出结构建议：
摘要结论。
公司与报告基本信息。
核心财务指标表。
收入与利润分析。
现金流与资产负债分析。
业务分部或战略变化，如可识别。
风险提示。
数据来源与待复核清单。
报告口吻：
清晰、克制、可复核。
避免夸张判断。
不给买入、卖出、持有建议。
对不确定内容明确标注。

## 多入口任务模块
需要设计三种入口：
终端入口
示例命令：
arkclaw run financial-report-analysis --input ./reports --output ./outputs --mode compare
对话入口
示例指令：
请分析 ./reports/某公司2025年年报.pdf，输出经营分析报告和指标表，所有关键数据要带页码。
飞书机器人入口

## 示例消息：
/财报分析 文件=某公司2025年年报.pdf 输出=报告+表格 模式=单公司
飞书入口若 Arkclaw 当前不可直接支持，请设计为「二期扩展」并说明替代方案。

三个问题定边界

动手之前，先回答三个问题：

它是什么？一个面向AI学习者和业务分析人群的教学型AI Agent工作流。

它不是什么？不是专业投研终端，不是投资决策工具，不提供任何买卖建议。

谁会用？三类人：

入门开发者/AI爱好者——想学Agent实际落地方法
金融/咨询/运营从业者——日常要处理财报做行业研究
学生/课题研究者——需要批量处理上市公司财报做实证研究

两条铁律

定完边界，定红线：

1. 绝对不编数据——PDF里找不到的字段，直接标记"待人工复核"，宁可空着也不编一个数字凑数
2. 绝对不做投资建议——所有输出报告头部强制展示免责声明，"仅辅助研究，不构成任何投资建议"

这两条红线不光是写在文档里，它直接决定了整个技术架构怎么设计——数据校验模块怎么做、待复核清单怎么生成、报告模板怎么写。

第二步：把一个大需求拆成七个小模块

这是整篇文章最核心的部分。

"从PDF里提取财报数据"听起来是一个任务。

但如果你直接让AI去干，它会给你一堆不可控的输出

可能漏数据
可能编数据
可能搞错单位
可能引用不到页码。

解决办法就一句话：

拆成模块。每个模块只做一件事，模块之间用标准数据格式连接。

拆完长这样：

配置校验 → 文件接入 → PDF解析 → 指标抽取 → 数据校验 → 报告生成 → 任务调度

七个模块，每层只有一进一出。

模块1：配置校验

什么都不做，先跑检查。

arkclaw financial-report check

逐项检查：

✅ 大模型API Key配置正常
✅ PDF解析依赖库安装完成
✅ 输出目录写入权限正常
✅ 模型连通性测试通过
🎉 所有校验项全部通过

这一步的意义不只是"检查环境"。

它是一个心智模型——在你动手之前，先确认地基是稳的。

后面所有模块都建立在"校验全通过"的前提下。

地基不稳，后面全白搭。

模块2：文件接入

支持两种输入：

单文件路径：--input ./reports/比亚迪2025年年报.pdf
文件夹路径：--input ./reports/（批量处理目录下所有PDF）

做的事情很简单：

校验是不是PDF（不是就直接拒掉）
检查文件有没有损坏
生成标准化文件元数据：文件名、大小、总页数

模块3：PDF解析

把PDF变成AI能处理的文本。

逐页读取，每页内容开头标记页码锚点。

单独提取PDF里的所有表格，保留每个表格所属的页码和序号。

有一个聪明的设计：自动识别目录页和免责声明页，降低这些页面的权重。

为什么？

因为目录里经常出现"营业收入……见第62页"这样的引用文字。

如果不降权，AI可能把目录里的引用当成正式数据，导致重复提取。

解析过程有实时日志——当前处理到第几页、提取了几个表格、预计还要多久。

190页的PDF解析可能要几分钟，没有进度提示，用户会以为卡死了。

模块4：指标抽取——AI真正干活的地方

用大模型从文本中提取指定的财务指标。包括：

公司名称、报告年份、币种
营业收入、归母净利润
经营活动现金流净额
总资产、总负债、资产负债率
研发费用

关键设计：强制绑定来源

每个指标不光给数字，必须附带四个信息{键值对}：

{
  "name": "revenue",
  "value": 6800,
  "unit": "亿元",
  "source_page": 62,
  "source_table": "合并利润表",
  "source_text": "2025年度营业收入约6800亿元",
  "confidence": "high",
  "review_required": false
}

为什么这么严格？

因为大模型有一个天然倾向——它想"帮"你。

当某个字段在PDF里找不到时，它可能会"合理推测"一个数字填上去。

这个行为在我们的工具里是被严格禁止的。

Prompt里写死了一条规则：没有明确对应内容的字段，直接输出"未识别"，自动进入待复核清单。

两种运行模式

single模式：分析单家公司年报，生成一份完整报告
compare模式：批量处理同行业多家公司年报，输出横向对比表

对比模式有一个额外的问题——不同公司的财务指标名称不一样。

有的叫"营业收入"，有的叫"营业总收入"，有的叫"主营业务收入"。

AI需要自动识别这些等价表述，并在对比表里标注口径差异。

模块5：数据校验——给AI输出加一道安全网

这一步很多人会忽略。但它可能是最重要的模块。

不管大模型多聪明，它的输出都不是100%可靠的。

你需要在校验层捕获三类错误：

数值合理性校验——营收识别成1000万亿元？明显超常识，自动标记待复核。资产负债率算出来150%？超过100%就一定有错。
单位归一化——不同公司财报金额单位不一样。有的用"元"，有的用"万元"，有的用"亿元"。不统一，对比的时候数字会差成千上万倍。这个模块把所有金额统一转换到"亿元"，并标注原始单位。
逻辑一致性校验——算出来的毛利率和财报里披露的毛利率差超过5%？要么提取错了数字，要么单位搞混了。标记待复核。

所有校验不通过的数据，统一进入review-needed.md待复核清单，不会混进最终报告。

模块6：报告生成

按严格模板生成，不是自由发挥：

# 【AI辅助生成】XX公司2025年年度报告分析
> ⚠️ 免责声明：本报告仅用于研究辅助，所有数据请对照原始PDF财报独立复核。

## 二、核心财务指标汇总
| 指标 | 数值 | 来源页码 |
|-----|------|---------|
| 营业收入 | XXX 亿元 | P62 |
| 归母净利润 | XXX 亿元 | P64 |

两个细节：

1. 免责声明在最顶部——不管谁打开，第一眼就看到"不构成投资建议"
2. 每个数字都带来源页码——"P62"意味着你可以直接翻到PDF第62页核对原文

模块7：任务调度

支持三种入口：

# 终端命令行
arkclaw financial-report run --input ./reports/比亚迪2025年年报.pdf --mode single

# 自然语言对话
"分析宁德时代2025年年报.pdf，输出经营分析报告和指标表"

# （二期）飞书机器人
/财报分析 文件=某公司2025年年报.pdf 输出=报告+表格 模式=单公司

每个任务自动分配唯一ID，所有产出文件归集到独立目录，不同任务的结果永远不会互相覆盖。

第三步：为什么输出是五个文件而不是一个

很多人会问：一个报告不就够了吗？

不够。因为使用场景不同：

report.md 给领导看。
- 有叙述、有判断、有数据引用。
- 但数据密度不够，不适合进一步做计算。
metrics.csv 给你做数据加工。
- 直接Excel打开，做图表、做趋势分析、做跨公司对比。
- CSV格式的好处是任何工具都能读——Python、Excel、飞书表格、SQL数据库，无缝接入。
evidence.json 是审计用的。
- 任何人对某个数字有疑问
- ——"为什么这里的营收是6800亿？"
- ——打开evidence.json就能看到：这个数字来自第62页的合并利润表，原文是"2025年度营业收入约6800亿元"，置信度high。
- 每个数据都有完整的溯源链条，推不倒。
review-needed.md 告诉你哪些数据AI自己都不确定。
- 有些字段PDF里找不到明确匹配值，有些不同页面出现了冲突数据。
- 全部汇总在这个文件里，引导你优先核对。
run-log.md 是出问题时用的。
- 任务执行到哪一步卡住了？
- PDF解析失败还是模型调用超时？打开日志就能定位。

一个用途一个文件。

比把所有东西塞进一篇Report里好用得多。

而且模块间数据格式标准统一（JSON/CSV/Markdown），后续替换任何一个模块的实现，完全不影响其他部分。

第四步：错误处理——不让用户看到技术报错

很多开发者容易忽略这一点，但用户感知最强烈的就是这个。

如果你的工具遇到问题时，返回给用户的是一堆Python traceback——用户会觉得这东西不可靠。

对每个错误场景，我定义了用户侧看到的友好提示：

出了什么问题	用户看到的不是报错
PDF路径不存在	❌ 未找到指定文件，请确认路径是否填写正确
API Key配置错误	❌ API Key校验失败，请重新运行配置向导
90%以上解析失败	❌ 当前PDF识别成功率过低，疑似扫描件图片格式，请替换为可复制文本型PDF
任务执行超时	⚠️ 任务执行超时，已保存当前中间结果

每一条提示都告诉用户两件事：出了什么问题 + 下一步该怎么做。

第五步：三种入口，覆盖不同使用习惯

不是所有人都喜欢打开终端敲命令。

终端入口——适合开发者日常批量处理：

arkclaw financial-report run --input ./reports/比亚迪2025年年报.pdf --mode single

自然语言对话入口——适合不想记命令参数的用户：
- "分析宁德时代2025年年报.pdf，输出经营分析报告和指标表，所有关键数据带页码"系统自动识别参数，切到对应模式执行。
Web可视化界面——适合完全不想碰命令行的用户。点几下鼠标就完事。
三个核心功能：
- 上传财报文件
- 查看任务列表和进度
- 系统配置状态检查。
全程有进度条，不会让用户盯着空白页面等半天。