用 agent 直接产出 docx:一次实体误识别让我加了三道校验

让 agent 批量生成行业周报 docx,第一次交付就出现一份把个股周报当成行业周报的废稿。后来我在链路里加了三道校验:实体、体量、渲染。

目录
  1. 链路长什么样
  2. 根因:中文实体名在自然语言接口里会漂移
  3. 三道校验,我现在每次都跑
  4. 第一道:实体校验
  5. 第二道:体量校验
  6. 第三道:渲染校验
  7. xlsx 的链路不太一样:公式要重算验证
  8. 一个反直觉的结论:让 agent 先出"提纲"再出"全文"
  9. 复盘

2026-09-24 那天我在做一个行业跟踪项目,需要 agent 自动产出周报 docx。第一批交付看起来完美——文件名规范、格式整齐、有表格有结论。

直到我自己点开其中一份,发现标题写的是:

text
自选股周报:SUNEDISON SEMICONDUCTOR PTE. LTD.、Taiwan Semiconductor Manufacturing Compa.docx

我要的是「半导体设备(申万)行业指数」周报,它给我生成了两家公司的个股周报。数据是真的,格式是对的,主题完全错了。

后来这份文件被扔进了一个叫 _discarded_误识别产物 的目录。这个目录名本身就是最好的教训总结。

链路长什么样

那次的项目结构是:

text
C:\Users\admin\WorkBuddy\2026-09-24-19-47-37\miaoxiang\industry_stock_tracker\
  行业_板块周报:半导体设备(申万)(行业指数)(2026-09-21~2026-09-24).docx   18256 字节
  行业_板块周报:半导体设备(申万)(行业指数)(2026-09-21~2026-09-24).pdf    240150 字节
  行业_板块周报:半导体设备(申万)(行业指数)(2026-10-05~2026-10-07).docx   14559 字节
  行业_板块周报:半导体设备(申万)(行业指数)(2026-10-05~2026-10-07).pdf    203112 字节
  _discarded_误识别产物\
    自选股周报:SUNEDISON SEMICONDUCTOR PTE. LTD.、Taiwan Semiconductor ....docx   5742 字节
    自选股周报:SUNEDISON SEMICONDUCTOR PTE. LTD.、Taiwan Semiconductor ....pdf   72373 字节

两个细节值得注意:

  1. 正常稿 18KB,误识别稿只有 5.7KB。体量差 3 倍——内容少意味着它只填了两家公司的数据,而不是一个行业几十只成分股。这个体量差本身就是可检测信号。
  2. 每份 docx 都配了一份 pdf。这不是多余,是校验手段(后面讲)。

根因:中文实体名在自然语言接口里会漂移

我当时用的取数接口是自然语言的(问"半导体设备行业指数最近一周表现")。这类接口的问题在于:它会把你的问句解析成一个代码,而解析可能解析错。

同一个项目里我记录了另一组更精确的证据(来自另一个看板项目):

text
801030.SI 基础化工  → 882202.WI
801740.SI 国防军工  → 882102.WI
801050.SI          → 000819.SH(序号1/4828、分位0)
HSSCHKY.HI         → 930915.CSI

801050.SI 那次特别典型:返回的 000819.SH 有完整数据、有 4828 条序列、有分位值——只是分位是 0。因为那个序号对应的是序列最开头。

所以问题的形状不是"报错",是"合法但错位"。这类错误不会自己喊出来。

三道校验,我现在每次都跑

校验检查什么拒绝条件
实体校验返回的代码 == 请求的代码不一致,或代码为空
体量校验产出文件大小 / 条目数与历史同期偏差 > 50%
渲染校验docx → pdf 是否成功,页数是否合理转换失败或页数为 0

第一道:实体校验

这是最关键的一道,做法很土但有效——把返回结果里的代码字段打出来对一遍。

python
# 拿到结果先做三件事:核对代码、核对日期、核对序列长度
expect_code = "801050.SI"
got = resp["code"]              # 必须等于 expect_code
assert got == expect_code, f"实体漂移: 请求 {expect_code} 返回 {got}"
assert resp["date"] == today,   f"日期不是今天: {resp['date']}"
assert resp["maxseq"] > 500,    f"序列太短,可能是新指数或错标的: {resp['maxseq']}"

最后一行 maxseq > 500 是"新指数钉死 0/100"那条规则的实现——样本不足 500 个交易日的指数不计入均值,否则分位数会失真。

校验失败不要直接弃用,改成"代码在前 + 严禁替换"的严格问句重问一次,通常一次就中。这是实测出来的,比换数据源便宜。

第二道:体量校验

那条 5.7KB vs 18KB 的对比,后来被我写成了规则:

bash
# 产出后立刻比体量,偏差过大就人工看一眼再发
ls -l "行业_板块周报:"*.docx | awk '{print $5, $NF}'

行业周报正常在 14~19KB。低于 10KB 基本可以判定"内容不全",高于 30KB 则可能是把原始数据全塞进去了。

体量是最便宜的完整性指标,比读完正文便宜一万倍。

第三道:渲染校验

每份 docx 都配 pdf,不是为了发给人看,是因为 docx 会"渲染崩坏"——字体缺失、表格溢出、分页错乱。这些问题在 docx 源码里看不出来,必须转一次才暴露。

转 pdf 之后看两个数:页数、文件大小。上面那两份正常稿的 pdf 分别是 240KB / 203KB,误识别稿只有 72KB。三个数字都指向同一件事。

xlsx 的链路不太一样:公式要重算验证

我机器上的 Excel 生成 skill 走的是另一条路。它的文件在:

text
C:\Users\admin\.workbuddy\plugins\marketplaces\workbuddy-builtin\
  builtin-plugins\sheetagent\skills\excel-generation\SKILL.md

frontmatter 里有一句我很认同的定位:

本 skill 引导主代理读设计准则后直接写 openpyxl 脚本生成本地 xlsx,并用 recalc 校验公式零错误。

两个关键决策:

  1. 直接写 openpyxl 脚本,不用模板套。因为模板的合并单元格、样式继承、条件格式在脚本里无法可靠复制。
  2. 写完必须 recalc。因为 openpyxl 写进去的公式没有计算值——=SUM(B2:B10) 写进去只是个字符串,用 Excel 打开才会算。如果不 recalc 就交付,任何人用脚本读这份 xlsx 都会读到空值。

这是 xlsx 和 docx 最大的区别:

text
docx  →  内容就是文本,写完即可读
xlsx  →  单元格可能是公式,不重算就是空
pptx  →  内容在 shape 里,位置错一位就溢出边界

第三条是我踩过的:pptx 的文本框如果按"字符数"估宽度,中文字符会被低估——结果标题溢出到画布外,导出的图里只剩半行字。

一个反直觉的结论:让 agent 先出"提纲"再出"全文"

我原来的做法是"一次生成完整文档"。改成两段之后废稿率明显下降:

text
第一段:只产出 5 行
  标题 / 时间范围 / 标的代码 / 数据条数 / 章节列表
  → 我肉眼 5 秒就能判断对不对

第二段:确认无误后再生成全文

为什么有效?因为错误的成本不对称。主题错了,全文写得再好也是废稿;而主题检查只需要 5 行。

那次误识别如果先出提纲,第一行就会写着「自选股周报:SUNEDISON...」,我一眼就能拦下来,不用等到 5.7KB 的文档生成完。

复盘

三条我现在固定执行:

  1. 实体校验放在取数之后、生成之前。对不上代码就不往下走。
  2. 出全文之前先出 5 行提纲。这是投入产出比最高的一步。
  3. docx 必转 pdf,xlsx 必 recalc。渲染层的问题只能靠渲染发现。

还有一个没解决的:那份误识别稿的数据本身是对的,只是标的错了。这意味着"数据校验"通不过它,"实体校验"才能。我后来在取数函数里强制加了一个必填参数 expect_code,不传就报错——从接口层面杜绝"忘了校验"。