🎯 今日核心问题

  1. 「分析这份财报」为什么无法直接当步骤执行?一个步骤要满足什么条件才算「原子」?
  2. 怎么用 Prompt 约束逼出可执行步骤,而不是「第一步:理解需求」这种废步骤?
  3. 步骤之间传递的不是文本,而是结构化数据时,怎么设计契约?

📖 精读提纲

【一】什么叫「原子步骤」——四个验收条件

步骤写成「分析财报」,Executor 只能瞎猜。一步能否直接执行,取决于是否同时满足四条:

拿这四个条件去筛「分析这份财报」,一条都不满足。所以 Planner 必须先做一次结构化拆解:把「分析」背后的意图展开——要估值?要风险预警?要同比趋势?不同意图的步骤完全不同。这一步失败率最高,最值得花 Prompt 成本。

【二】用「意图澄清 + 模板化拆解」逼出好步骤

有效手段不是让模型自由拆,而是给它一个有限的任务模板库:先分类、再套模板。Few-shot 给 3-4 个「目标 → 步骤序列」示范并限定输出结构,比纯指令稳定得多——模型有了可对齐的骨架。

第二步是强制每个步骤携带 I/O 契约:让模型同时填 inputSpec 和 outputSpec,后者必须是「字段 + 类型 + 单位」。加了这条约束,废话步骤会明显减少——模型发现自己写不出 outputSpec,「理解财报结构」就填不出来。

第三步是自动校验 + 打回重拆:纯 Java 校验步骤数、outputSpec 非空、dependsOn 无环。不过就把错误原因连同原计划打回给模型重拆,成本极低,能挡掉 80% 的烂计划。

【三】实战应用:Spring Boot 场景

场景:财报分析 Agent,输入是一份 PDF(已用 PyMuPDF 抽出文本,第1周学过),输出一份 5 段式分析。合理的步骤序列应该是:

  1. 识别财报类型与报告期(年报/半年报,哪一年)——防止后面把半年报当全年算。
  2. 抽取三大报表关键科目(营收、净利润、经营现金流、有息负债、应收账款)。
  3. 计算派生指标(毛利率、净利率、营收同比、经营现金流/净利润)。
  4. 做异常检测(应收增速远超营收增速、经营现金流连续为负等)。
  5. 结合行业常识写风险提示与结论。

第 1 步是很多人漏掉的:不先确认报告期,第 3 步的同比就算错,错误一路传到结论。这正是原子化的价值——把数据正确性放在第 1 步显式验收。

Spring Boot 里,把每一类步骤实现成一个 StepHandler 接口(supports(stepType) + handle(ctx)),用 Spring 的 Map<String, StepHandler> 注入做分发。这样「抽科目」这类确定性的正则/表格解析,不必交给模型;只有第 4、5 步这种需要判断的才用 LLM。混合编排能省下大量 token,也把关键数字的准确性锁死了。

【四】常见误区

💻 代码示例

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)自己审一遍自己,以及怎么避免「自己审自己」变成走过场。