你不需要资深开发经验。这篇文章不是教你写代码是教你怎么跟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不是就直接拒掉检查文件有没有损坏生成标准化文件元数据文件名、大小、总页数模块3PDF解析把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可视化界面——适合完全不想碰命令行的用户。点几下鼠标就完事。三个核心功能上传财报文件查看任务列表和进度系统配置状态检查。全程有进度条不会让用户盯着空白页面等半天。这个工具能改成什么财报分析只是起点。同样的模块化架构换成不同的解析规则和抽取模板简历自动解析——从一堆PDF简历中提取姓名、经历、技能、教育背景合同关键条款提取——自动找出合同中的金额、日期、甲乙方、违约条款论文批量摘要——从大量PDF论文中提取摘要、方法、结论、引用关系招标文件分析——自动提取技术要求、评分标准、资质门槛你需要改的只有三个模块PDF解析可以复用抽取指标换成你要的字段报告模板换成你需要的格式。其他模块——文件接入、数据校验、任务调度——几乎不用动。模块化架构的价值就一句话搭一次用很多次。写在最后这篇文章展示的不是代码怎么写。是思路怎么把一个模糊的业务需求通过系统性的拆解和设计变成AI可以逐步实现的可执行方案。跟AI协作搭工具不是一股脑把需求丢给它然后等结果。是你先把问题想清楚、拆明白、定好标准再让AI一个模块一个模块地帮你实现。你是架构师。AI是你的执行助手。这个角色分工搞清楚了你能搭的工具远不止财报分析。今晚就可以动手试试。既然看到这里了随手点个赞、在看、转发三连吧。谢谢你看我的文章我们下次再见。#AI Agent #财报分析 #自动化工作流 #ArkClaw #大象AI共学作者大象-推动 AI 共学让普通人轻松上手AI相关链接1. ArkClaw火山引擎https://www.volcengine.com/product/arkclaw2. pdfplumber 文档https://github.com/jsvine/pdfplumber