报告类CLI

报告类 CLI

定位:报告 = 把多次取数/分析结果组织成结构化成稿。关键设计判断不是「用哪个命令」,而是要不要 CLI 分段——简单报告靠上下文 + 大纲直出(不用 CLI),复杂报告用 CLI 分段生成、最后拼接。

📎 案例参考:实战 C sales-report(直出六段式 + 生图脚本)· 控制价审核 report-gen(9 步 pipeline 分段)。场景视角见场景指南/报告。

两种报告,两种架构

	简单报告	复杂报告
怎么出	上下文 + 大纲直接成文,一次过	CLI 分段生成 → 拼接
用 CLI 吗	❌ 不用(取数/生图可用轻脚本)	✅ 每段一个子命令 + 中间产物
适用	数据已在上下文、单视图、一个 context 装得下	多阶段重计算、异步任务、数据量大、要可复现
例	销售达成报告 MD(六段式)	控制价审核报告(scan→insight→price→report)

简单报告 · 上下文 + 大纲直出

数据已经在手(或一两次查询就够),按固定大纲一次写成。模板是核心——references/report-template.md 写清每段要什么数据字段,AI 读它就知道每段怎么填。

1 Ask Question 确认口径(项目范围 / 时间)   ← 先问后做,不抢答
2 调 sales-query 取齐六段数据             ← 复用分析类 CLI,不自己写 SQL
3 按六段式模板直接成文(MD)              ← 一次过,无需 CLI 编排
4 (可选)build_html_report.py 生图       ← 轻脚本:MD+数据 → ECharts HTML

生图脚本不算「报告 CLI 编排」——它只是把成稿渲染成 HTML 的一步工具。报告主体仍是「上下文直出」。

复杂报告 · 一块块做出来,再拼成一篇

以控制价审核报告为例,从「这份报告是怎么产出的」来看。

先看这份报告由哪些块组成

一份控制价审核报告,成稿大致是这几块:

① 整体风险概览      这次审的清单,整体贵不贵、风险多大
② 造价指标异常      单方造价/含量等指标,跟历史比,哪些超标
③ 异常归因          超标的指标,背后是什么工程原因
④ 单价偏离明细      逐条清单单价跟对标比,哪些偏高

每一块背后都是一坨重活:取数、跟历史项目对标、算指标、逐条核查单价。一个人不可能把这些原始数据全装在脑子里一口气写完——AI 的上下文(context)同理装不下。所以做法是:一块一块地做,每做完一块就存成草稿,最后把草稿拼成一篇。

报告的「生产线」:每一步做出报告的一块

每个 CLI 命令负责报告里的一块,做完把这块存成一个草稿文件:

这一步	在为报告准备哪一块	存下的草稿
`resolve-bq`	确认这次审哪个清单	标的信息
`confirm-audit-mode` ⏸	按什么口径审(要你定)	审核模式
`confirm-similar` ⏸	拿哪些历史项目对标(要你定)	对标集
`prefetch-benchmark`	取历史采样	对标基准
`scan`	② 造价指标异常	`scan.json`
`insight`	③ 异常归因	`insight.json`
`price`(提交→查→取)	④ 单价偏离明细	`price_result.json`
`report`	把①②③④拼成成稿	`report.md`
`canvas open`	推到工作台展示	—

为什么要「一块块存草稿」,而不是一口气写

这是复杂报告的关键。每一步做完自己这块、把结果存成文件,再告诉 AI 下一步做哪块:

报告数据一直在硬盘的草稿文件里,不在 AI 脑子里 → 报告再大、数据再多,也写得动(上下文不会爆)。
存了草稿就能改一段、接着写:你说「归因那段再深入点」,只要重做 insight 这一块、再拼一次,前面的取数和单价核查都不用重来。
能复盘:每块草稿都在,出了错能回看是哪一块的问题。

就像人写长报告会先分头整理素材、各存一个文档,最后再汇编——而不是开一个空白页从头硬写到尾。

哪几步要停下来问你(⏸)

不是每步都能自动跑。「按什么口径审」「拿哪些历史项目对标」是业务判断,得你拍板——所以这两步单拎出来、停下来问你确认,而不是让 AI 替你默认一个。这是报告该有的决策点,不能为了”少几步”就省掉。(这也是设计指南/AUI设计说的先问后做。)

有一块要等:单价核查

单价核查要后台算很久,所以拆成三下:提交核查 → 查进度 → 取结果。提交后会拿到一个任务号,后面靠它查、靠它取;没提交过就不让取结果——免得 AI 一着急又重新提交,把这块活儿白跑两遍。

最后一步:把各块拼成一篇

report 这步读回前面存的各块草稿(指标异常、归因、单价明细),按固定模板组装成 report.md,每段结论前置;同时把要在工作台展示的内容也一并备好,AI 直接拿去展示就行。这一步 AI 只负责把结论用业务话说顺,数据怎么拼是程序的事。

谁干什么:程序 vs AI

程序(CLI)负责	AI 负责
取数、跟历史对标、算指标、核查单价	决定走到哪一步
把各块按模板拼成报告	该停下来问你的地方停下来
把展示内容备成现成的	把结论用业务语言说清楚

一句话:报告里”算数据”的活全交给程序、结果存成草稿;AI 只当”主编”——决定顺序、把关你该拍板的地方、把结论写顺。 这套设计的实测效果(80 分钟→15 分钟)见实践分享/控制价审核CLI化实战。

判断:简单还是复杂?

数据一个 context 装得下?  否 → 复杂
有多阶段重计算/异步任务?  是 → 复杂
要可复现 / 中间态可修订?  是 → 复杂
否则                      → 简单(大纲直出)

别过度设计:简单报告硬上 pipeline = 浪费;也别硬扛:复杂报告硬塞一个 context 直出 = 数据装不下、不可复现、错口径。

共通设计点

先问后做:报告口径不抢答,先 Ask Question 确认范围/时间(见设计指南/AUI设计)。
数字必有出处:每个带量级的数字来自查询结果或用户提供的示例数据,并在口径说明里标注来源。
结构稳定:固定段式(如六段式),每段结论前置。
产物双形态:MD(评审/二次编辑)+ HTML(ECharts 可视化,可 --echarts-local 离线内联,便于邮件)。
Skill 串联:报告出稿后,可接设计指南/CLI设计/操作类CLI发布到企微/飞书/邮件,完成「最后一公里」。

案例:用户问题 → CLI

报告类的转换特征:先判”简单还是复杂”,再决定要不要 CLI 分段——同样是「出份报告」,装得下就直出,装不下/要可复现就 pipeline。

▸ 简单·直出「出一份 5 月销售达成报告」

sales-query aggregate/rank ...      # 复用分析类 CLI 取齐六段数据
# → 按六段式模板(references/report-template.md)一次成文 MD,无需报告 CLI

数据一两次查询就够、单视图、一个 context 装得下 → 大纲直出,别上 pipeline。

▸ 简单·直出「这个项目本周成交情况总结一下」

sales-query find --dsl '{...本周成交...}'
# → 数据在手,直接成文;(可选)build_html_report.py 生 ECharts 图

生图脚本只是渲染一步,不算「报告 CLI 编排」,报告主体仍是上下文直出。

▸ 复杂·分段「审信宏城一期的控制价,出份审核报告」

report-gen resolve-bq → confirm-audit-mode ⏸ → confirm-similar ⏸
         → scan(②指标异常) → insight(③归因) → price(④单价偏离)
         → report(拼成稿 report.md)

多阶段重计算 + 异步 + 要可复现 → 每块落草稿文件,上下文不爆、可复盘。

▸ 复杂·分段「把全年 12 个项目的成本对标做成一份报告」

for 项目 in 12 个: report-gen scan/insight → 各自落 <项目>.json
report-gen report --inputs *.json     # 最后汇编成一篇

数据量大到一个 context 装不下 → 分头整理、各存草稿,最后拼。

▸ 修订「上次那份报告,归因那段再深入点」

report-gen insight --redo --depth deep   # 只重做这一块
report-gen report                        # 再拼一次,取数/单价核查不重来

中间产物落了文件,才能「改一段、接着写」——这正是复杂报告分段的回报。

坏味道

简单报告硬套多命令 pipeline → 过度设计
复杂报告塞一个 prompt 直出 → 数据截断、口径漂、不可复现
中间产物不落文件 → 无法对话修订、无法复盘
报告数字不标来源 → 示例数据冒充实时查询

一句话

报告类的核心判断是**「要不要把生成过程拆进 CLI」**:能一次写完就直出,装不下/要可复现就分段拼接。场景落地见场景指南/报告。