Skip to content

财报透视(一):28 个小时、21 张任务卡 ​

10 月 31 日 16:27,第一个提交:chore: 初始化 finance-agent 陌阡AI工程骨架。

11 月 1 日 20:35,chore(release): v0.4.0,开源发布。

中间 28 个小时,56 次提交,21 张任务卡,9 个版本号。代码主要由 AI 按任务卡来写,人负责写需求、拍板和验收,以及在它要跑偏的时候把它拽回来。

这篇不讲代码,讲顺序:这个项目是按AI 工程治理模板的流程一步步走出来的。哪些闸门真的挡住了东西,哪些没挡住,都在 git log 里。

你在这里

这一篇讲的是全景图之外的东西:这张图是怎么一块一块画出来的。

一、PRD 初稿被整个推翻 ​

仓库里的需求文档,变更记录第一行是这样的:

日期变更内容来源
2026-10-31PRD 初稿:个人记账定位已废弃,被 v0.2.0 整体替换

对,这个项目最开始要做的是个人记账。骨架生成之后,第一版 PRD 写的是记账;同一天的需求对话之后,定位整个换成了另一件事:把年报变成能核对的数字。PRD 重写成 v0.2.0,记账方向进了「废弃清单」,截止移除时间一栏写的是「立即」。

这件事放在写代码之后发生,代价是推翻代码;放在写代码之前,代价只是重写一份文档。治理模板的第一条规矩「先文档、后代码」,最值钱的时刻就是这种时候:方向错了,发现得早。

重写后的 PRD 第 0 章是十条「已确认决策」,不再讨论。挑几条:

  • D1 定位:上传 A 股财报 PDF,整理成可核对的财务视图,只做信息提取与整理,不做预测、估值、荐股
  • D7 计算全部由脚本完成,LLM 只做科目对齐与文案措辞,数字不得由 LLM 生成或改写
  • D9 上传原件不留存,解析完成即删除
  • D10 红线:不出现投资建议类表述,用禁用词表做机器校验

做财报工具,「顺手」的诱惑很多:给异常项加一句结论,给指标打个分,给公司排个名。这类想法不管是人冒出来的还是 AI 提出来的,拿 D1 和 D10 一对,就不用争了。范围写在纸上,拒绝就不是情绪问题,是查表问题。

还有一处值得一提:PRD 第 4 章每个功能都带「布尔验收」。不是「解析要准确」,而是「评估集 10 份年报三表定位正确率 100%,定位错误即整体失败」。能判真假的验收标准,后面才能拿来卡任务。

二、架构、ADR、接口契约 ​

PRD 确认后是架构文档,然后是接口契约。这三份文档和第一批任务卡,是在同一分钟提交的(18:33),因为规矩是「确认即提交」:每份文档我确认一份,最后一起入库。

架构文档里记了 9 条 ADR(架构决策记录),每条写上下文、备选方案、决策、取舍、遗留风险。概览篇的技术选型表就是从这里来的。比如 PDF 解析库:

PyMuPDF:抽取快、能力强,但 AGPL / 商业双授权,闭源分发需购买商业许可。

决策:选定方案 3;解析器定义为接口,v1.1 可在接口后接入 OCR / 重引擎。

方案 3 就是 pdfplumber + pypdfium2。

ADR 只追加、不修改。图表从 PRD 里的 8 组,到第一版实现的 7 张,再到 10 张、11 张,每次改都不是去改旧的 ADR,而是追加 ADR-008、ADR-009,写清楚为什么改。

这里先埋一个伏笔:ADR-004 写的是「进程内 asyncio + 解析进程池」,代码最后写成了线程池。文档对,代码偏了,三天后才被我撞上:并发解析时整个进程崩溃。这件事放在第 7 篇讲。

三、任务卡:一次只拆三五张 ​

治理模板里最反直觉的一条规矩:禁止一次性把整个里程碑拆成全部任务。做完一批、验收通过,才拆下一批。

这个项目的任务卡是这么分批进来的:

批次时间任务卡内容
第一批10-31 18:33TASK-001~005骨架、三表定位、数值归一、科目 Schema、规则匹配
第二批10-31 20:04TASK-006~009表格还原、指标与勾稽、看板、溯源与导出
第三批10-31 22:23TASK-010~014上传入队、多期会话、落库、部署、指标缺口修补
之后11-01TASK-015~021根据试用反馈逐张追加

为什么不一次拆完?因为前面任务做完之前,后面的任务你根本写不准。第三批里的 TASK-014「指标与提取缺口修补」,是 TASK-007 评测完才知道要有的:扣非净利润 10 份年报取到 0 份,存货被母公司报表覆盖。如果第一天就把 21 张卡全写好,这张卡不会存在,存在的会是几张基于想象写的、和实际问题对不上的卡。

每张卡的结构是固定的:编号、前置依赖、优先级、执行步骤、布尔验收标准、评测方案,做完再补「评测结果」和「验收记录」。前置依赖不是 done,这张卡就不许开工。

四、一个达不到的验收标准 ​

TASK-007(指标计算与三表勾稽)的验收标准里有一条:200 个指标值与金标一致。实测是 153/200 = 76.5%。

AI 交上来的不是一个「已通过」,而是一段「待确认:端到端口径修订」:

当前金标由「行文本」路径生成,会把母公司资产负债表尾行并入合并口径(如负债合计取到 16.9B 而非 22.76B),与产品侧不是同一口径,因此 100% 一致不可达。

然后给出了四条替代标准:公式层在 fixture 上 100% 正确;勾稽 10/10 通过;端到端一致率 ≥ 75%,且每条差异都归因到「金标缺失 / 口径差异 / 产品缺陷」三类;剩下 17 条差异转成后续任务卡。

我确认了。现在回头看,这次修订一半是对的,一半埋了雷。

对的那一半:它没有偷偷把阈值改低,而是把差异逐条归因,写明哪些是金标的问题、哪些是产品的问题,产品的问题开了 TASK-014 去修。这比一个干巴巴的「76.5%,通过」有用得多。

埋雷的那一半:「勾稽 10/10 通过」这句话被写进了验收记录。写这个系列时我用现在的代码复跑,是 6 份通过、4 份跳过:科创板两家的「所有者权益合计」没取到,勾稽根本没法算。我无法确定当时那个 10/10 是怎么来的,任务卡里只有手抄的数字,没有脚本输出。

验收标准可以修订,但修订后的每一个数字,都得有一个能重跑的出处。 这条教训第 6 篇展开讲。

五、第二天下午,流程开始松动 ​

11 月 1 日上午,v0.2.0 内测版发布。接着开始用真实年报试用,反馈一条接一条:布局和原型差距大、要跨年对比、报表首行丢了……版本号从中午的 v0.2.1 一路涨到下午的 v0.2.6,6 个版本。

翻 git log 能看到流程是怎么松的。按规矩,任务卡要「人工审阅确认、入库、更新索引」之后才能开发。但这几张卡:

  • TASK-016、017 和它们的实现在同一个提交里(12:47)
  • TASK-019 和它的实现在同一个提交里(15:22)
  • TASK-020 和它的实现在同一个提交里(16:38)

卡还是写了,验收也做了,但「先确认卡、再写代码」变成了「代码和卡一起交」。节奏一快,闸门就从「事前」滑到了「事后」。

还有一张卡很有意思。TASK-016 的目标是「看板对齐高保真原型」,做完之后我看着页面觉得不对。下一张 TASK-017 的来源一栏写着:

v0.2.0 试用反馈(不再参考原型,按品牌与可用性重做)

背景里第一句是「原型方向作废」,主色改成红系,理由是四个字:「股市忌绿」。A 股里绿色是跌,一个财报工具满屏绿色,用户看着心里发慌。这种事原型阶段想不到,只有真的拿年报跑一遍、看一眼才知道。

到了晚上的 TASK-021(图表重构),流程又收紧了:18:04 先提交任务卡,18:32 和 18:47 两次修订卡的内容,19:01 才在同一分钟标记验收通过、提交实现。最后一张大卡反而走得最规矩,因为它改的是对外承诺的东西:图表清单、PRD、接口契约都要跟着变。

六、闸门挡住了什么,没挡住什么 ​

28 小时过去,回头看治理模板的几道闸门:

挡住了的:

  • 范围。PRD 的「不做」清单和红线,挡住了「顺手加个结论」的冲动。21 张任务卡我逐张翻过,没找到越界的功能。
  • 方向。记账改年报,发生在写代码之前。
  • 决策失忆。图表改了三次,每次为什么改,ADR 里都有。

没挡住的:

  • 验收口径的漂移。TASK-007 的修订是诚实的,但「10/10」这样的数字是手抄进任务卡的,后来和代码对不上,没有任何机制发现。
  • 文档和代码的偏离。ADR 写进程池,代码写线程池;需求文档写「异常项无页码不展示」,代码里页码字段永远是空的。文档评审过、代码验收过,两者之间的缝没人查。
  • 快节奏下的事前确认。任务卡和代码一起交,审阅就变成了追认。

这三条,后来都是我写这个系列、对照着文档逐行读代码时查出来的,修复记录在 TASK-022 和 v0.4.1 里,细节在第 7 篇。

治理模板能让 AI 在 28 小时里不跑偏,但它保证不了「做完」等于「做对」。闸门管的是顺序和范围;对不对,最后还是得有人拿着文档一行一行对代码。

版本说明

本文基于 v0.4.1(提交 5150928)。仓库的任务卡、PRD 与 ADR 都在 docs/ 下,可以对照本文的时间线看。

本文阅读--次|全站访问--次|访客--人