🎯 今日核心问题
- 「分析这份财报」为什么无法直接当步骤执行?一个步骤要满足什么条件才算「原子」?
- 怎么用 Prompt 约束逼出可执行步骤,而不是「第一步:理解需求」这种废步骤?
- 步骤之间传递的不是文本,而是结构化数据时,怎么设计契约?
📖 精读提纲
【一】什么叫「原子步骤」——四个验收条件
步骤写成「分析财报」,Executor 只能瞎猜。一步能否直接执行,取决于是否同时满足四条:
- 单一动作:只涉及一次工具调用或一次模型加工。「提取三年营收 + 算复合增速」是两个动作,得拆两步,否则失败了你不知道该重试哪一半。
- 输入确定:这一步的数据来源必须是明确的(哪个工具、哪份文件、哪个前序步骤的哪个字段),不能说「相关数据」。
- 产出可验收:能写出判断标准。比如「一个 Map,key 是年份,value 是营收(单位:亿元)」,或者「3 条结论,每条必须引用财报中的具体数字」。
- 失败可归因:出错时能判断是数据没拿到、还是加工逻辑错了。做不到这一点,重试就是盲猜。
拿这四个条件去筛「分析这份财报」,一条都不满足。所以 Planner 必须先做一次结构化拆解:把「分析」背后的意图展开——要估值?要风险预警?要同比趋势?不同意图的步骤完全不同。这一步失败率最高,最值得花 Prompt 成本。
【二】用「意图澄清 + 模板化拆解」逼出好步骤
有效手段不是让模型自由拆,而是给它一个有限的任务模板库:先分类、再套模板。Few-shot 给 3-4 个「目标 → 步骤序列」示范并限定输出结构,比纯指令稳定得多——模型有了可对齐的骨架。
第二步是强制每个步骤携带 I/O 契约:让模型同时填 inputSpec 和 outputSpec,后者必须是「字段 + 类型 + 单位」。加了这条约束,废话步骤会明显减少——模型发现自己写不出 outputSpec,「理解财报结构」就填不出来。
第三步是自动校验 + 打回重拆:纯 Java 校验步骤数、outputSpec 非空、dependsOn 无环。不过就把错误原因连同原计划打回给模型重拆,成本极低,能挡掉 80% 的烂计划。
【三】实战应用:Spring Boot 场景
场景:财报分析 Agent,输入是一份 PDF(已用 PyMuPDF 抽出文本,第1周学过),输出一份 5 段式分析。合理的步骤序列应该是:
- 识别财报类型与报告期(年报/半年报,哪一年)——防止后面把半年报当全年算。
- 抽取三大报表关键科目(营收、净利润、经营现金流、有息负债、应收账款)。
- 计算派生指标(毛利率、净利率、营收同比、经营现金流/净利润)。
- 做异常检测(应收增速远超营收增速、经营现金流连续为负等)。
- 结合行业常识写风险提示与结论。
第 1 步是很多人漏掉的:不先确认报告期,第 3 步的同比就算错,错误一路传到结论。这正是原子化的价值——把数据正确性放在第 1 步显式验收。
Spring Boot 里,把每一类步骤实现成一个 StepHandler 接口(supports(stepType) + handle(ctx)),用 Spring 的 Map<String, StepHandler> 注入做分发。这样「抽科目」这类确定性的正则/表格解析,不必交给模型;只有第 4、5 步这种需要判断的才用 LLM。混合编排能省下大量 token,也把关键数字的准确性锁死了。
【四】常见误区
- ❌ 把「收集资料」「理解需求」「制定方案」当步骤——这些没有产出物,是元动作,不是执行步骤。
- ❌ 全流程都让 LLM 做。财务数字抽取用模型就是给自己埋雷,正则/表格库能做到 100%,模型做到 95% 还不可复现。
- ❌ 步骤间靠自然语言传值(「把上一步的结果传给下一步」)。必须定字段名,例如
s2.revenueByYear,否则 Executor 会开始自由发挥。 - ❌ 拆得太碎,20 步的财报分析计划。步骤数超过 8 步,先合并同类项,否则延迟和失败率都会爆。
💻 代码示例
public record DecomposedStep(
String id,
String stepType, // EXTRACT / CALC / ANALYZE / WRITE,对应 StepHandler
String goal,
String inputSpec, // 数据从哪来,字段名
String outputSpec, // 产出字段+类型+单位
String acceptance, // 一句话验收标准
List<String> dependsOn) {}
record DecomposedPlan(String intent, List<DecomposedStep> steps) {}
interface TaskDecomposer {
@SystemMessage("""
你是任务分解器。把用户的模糊目标拆成 3-8 个原子步骤。
每个步骤必须满足:
1. stepType 只能是 EXTRACT / CALC / ANALYZE / WRITE 之一
2. outputSpec 必须写明字段名、类型、单位,例如 "revenueByYear: Map<int,BigDecimal>,单位亿元"
3. acceptance 必须是可判定的陈述句
4. 禁止出现"收集资料""理解需求""制定方案"这类无产出物的步骤
示例:
用户目标:判断这家公司现金流是否健康
输出:[
{"id":"s1","stepType":"EXTRACT","goal":"抽取近3年经营现金流净额",
"inputSpec":"财报原文现金流表","outputSpec":"ocfByYear: Map<int,BigDecimal>,单位亿元",
"acceptance":"3个年度均有数值且与原文一致","dependsOn":[]},
{"id":"s2","stepType":"CALC","goal":"计算经营现金流/净利润比值",
"inputSpec":"s1.ocfByYear + s1.netProfitByYear","outputSpec":"ratioByYear: Map<int,BigDecimal>,保留2位小数",
"acceptance":"3个年度比值均落在0-3之间或无数据说明","dependsOn":["s1"]}
]
只输出 JSON。
""")
DecomposedPlan decompose(@UserMessage String goal);
}
// 确定性校验器:不合格就带原因打回重拆
@Component
public class PlanValidator {
public List<String> validate(DecomposedPlan p) {
List<String> errs = new ArrayList<>();
if (p.steps().isEmpty() || p.steps().size() > 8)
errs.add("步骤数必须在1-8之间,当前 " + p.steps().size());
Set<String> ids = p.steps().stream().map(DecomposedStep::id).collect(Collectors.toSet());
for (DecomposedStep s : p.steps()) {
if (s.outputSpec() == null || s.outputSpec().isBlank())
errs.add(s.id() + " 缺少 outputSpec");
if (s.acceptance() == null || s.acceptance().length() < 6)
errs.add(s.id() + " acceptance 不可判定");
if (!Set.of("EXTRACT","CALC","ANALYZE","WRITE").contains(s.stepType()))
errs.add(s.id() + " stepType 非法: " + s.stepType());
for (String d : s.dependsOn())
if (!ids.contains(d)) errs.add(s.id() + " 依赖了不存在的步骤 " + d);
}
// 环检测(Kahn)
Map<String,Integer> indeg = new HashMap<>();
Map<String,List<String>> adj = new HashMap<>();
p.steps().forEach(s -> indeg.putIfAbsent(s.id(), 0));
for (DecomposedStep s : p.steps())
for (String d : s.dependsOn()) {
adj.computeIfAbsent(d, k -> new ArrayList<>()).add(s.id());
indeg.merge(s.id(), 1, Integer::sum);
}
Deque<String> q = indeg.entrySet().stream().filter(e -> e.getValue()==0)
.map(Map.Entry::getKey).collect(Collectors.toCollection(ArrayDeque::new));
int seen = 0;
while (!q.isEmpty()) { String u = q.poll(); seen++;
for (String v : adj.getOrDefault(u, List.of()))
if (indeg.merge(v, -1, Integer::sum) == 0) q.add(v); }
if (seen != p.steps().size()) errs.add("计划存在循环依赖");
return errs;
}
}
// 分发:确定性步骤不走模型
@Service
public class StepHandlerRegistry {
private final Map<String, StepHandler> byType;
public StepHandlerRegistry(List<StepHandler> handlers) {
this.byType = handlers.stream()
.collect(Collectors.toMap(StepHandler::type, h -> h));
}
public StepHandler of(String stepType) {
StepHandler h = byType.get(stepType);
if (h == null) throw new IllegalArgumentException("未注册 stepType: " + stepType);
return h;
}
}
一次真实输出(经 PlanValidator 校验通过的计划片段):
intent: 财报健康度分析
s1 EXTRACT goal=识别报告类型与报告期 outputSpec=reportType:String(年报/半年报/季报), period:LocalDate
acceptance=报告期能明确到年份且与封面一致
s2 EXTRACT goal=抽取三大报表关键科目 outputSpec=revenue/netProfit/ocf/ar/debt: Map<int,BigDecimal>,单位亿元
acceptance=5个科目×3年共15个数值全部非空,且能定位到原文页码
s3 CALC goal=计算四大派生指标 outputSpec=grossMargin/netMargin/yoyGrowth/ocfToNP
acceptance=每项指标均有计算公式记录,可复算
s4 ANALYZE goal=识别3类财务异常信号 outputSpec=flags: List<{type,evidence,severity}>
acceptance=每条flag必须引用s3中的具体指标数值
✏️ 今日动手
拿一份真实 A 股年报(巨潮资讯下载 PDF,用 PyMuPDF 抽文本),写 TaskDecomposer + PlanValidator,把「分析这家公司的现金流健康度」拆成计划并让校验器通过。要求:① 故意喂一个模糊目标(「分析这份财报」),记录模型拆出的 plan 并检查哪些步骤被 validator 打回;② 实现 EXTRACT 的确定性 handler(正则抽「经营活动产生的现金流量净额」),对比它和纯 LLM 抽取在同一份 PDF 上的准确率;③ 把「意图分类」结果(估值/风险/趋势)打进日志,看看同一个目标模型倾向于归到哪一类。
🔖 明日预告
计划再漂亮,Executor 写出来的结论也可能是错的。明天讲反思机制:让 Agent 在交付前拿着验收标准(今天写的 acceptance)自己审一遍自己,以及怎么避免「自己审自己」变成走过场。