← 返回目录

第 12 讲　按名单批量：一次给全班出结课作业

【可执行状态】现在就能做（填制引擎跑在公网，按附录 C 把 doc-filler 连接器接进入口即可）

【本讲对应资产】doc-filler 引擎（5 个工具）；本讲用 filler_scenarios filler_help filler_batch filler_check

【本讲原理来源】L3 第 18 课《Agent 生态认知革命》、吴恩达《Agentic AI》·工具使用与评估

引子：四十份作业，你怎么证明一个人都没落下

先在心里算一笔账：班上四十个人，每人一份结课作业封面，你打算怎么交？

交一叠 docx 就算交完了吗？假如三周以后教务处来电话：第三十一号学生说他没收到，你手上哪一样东西能立刻答得上？是一份 Excel 选课名单，还是一份能逐条对上产物的对账表？

这个追问，是本讲全部内容的起点。批量出件最难的一步从来不是“生成得快”，而是“事后说得清”。生成快是顺带的，说得清才叫交付。所以这一讲要练的，是在填制之外再加一道更硬的动作：按名单出件，再拿名单回头对账——一条记录一个人，一份产物一个交代。

一、场景

学期最后一周，赵老师（化名）手上有两件要交的东西：一份结课作业封面，和一份能证明“每个学生都拿到了”的名单。

班上一共 40 人，选课名单是教务系统导出来的 Excel：学号、姓名、专业。按学院的规矩，一人一份结课作业，姓名和学号各不相同，教师姓名和课程名称全班一样。

上一次她是这么干的：打开模板，填第一个学生的姓名学号，另存；再打开模板，填第二个……到第十九份的时候，学号多了一位，交上去之后是学生自己发现的。比如那位学生发来一句：老师，我这个学号好像长了。她翻回去一查，果然串了行。

这一讲的活，机器比人适合得多——它不会在第十九份上开始手抖。 但有一件事机器替不了：你得能证明 40 个人一个都没落下。

二、原理一页：名单即数据，份数即证据

2.1 学生粒度：一条记录一个人

homework 场景（结课 / 考查作业），模板里 8 个占位符，数据粒度是学生粒度（记录列表叫 students）。两层分工和学生粒度对得很齐。

每条记录各自的字段（一名学生一条）：

顶层公共信息（全班共用，走 context_json）：

{“semester”:“2026学年春季学期”,“department”:“智能金融学院”,“generate_time”:“2026年9月17日”}

（本书正文里的 JSON 用全角引号排版，与正文引号体例保持一致；实际在入口里输入时，按工具提示的数据形状填即可。）

五项学生字段 + 三项公共信息，就是模板 8 个占位符取值的两层；具体哪个占位符取哪一层，调 filler_help 看映射表最准。

记录条数 = 出件份数。 这句话在本讲是一把尺子：名单上 40 条，就该有 40 份。少一份，就是有人没拿到作业——这是教学事故，不是格式问题。比如名单上写了 39 条，机器就老老实实出 39 份，它不会替你补上第 40 个人，也不会提醒你“好像少了一个”——它只对给它看的东西负责，所以名单得先由你数对。

2.2 历史纵深：一份作业封面走过四代，只有第四代留下了“证据”

四十份同格式的封面，这件事老师们做了几十年。看清它换过哪几代做法，你就明白为什么这一讲要把“对账”看得比“出件”更重。

第一代，手抄名单。 上世纪七八十年代，结课作业封面是老师或课代表一张一张手抄的——学号、姓名、课程、教师，抄四十遍。打个比方，那就像把同一句话写四十张纸条，写到后面几张，笔画已经开始走形。抄错的地方没人会发现，因为没有底稿可比。

第二代，复写纸与刻章。 八十年代有了复写纸：同一张表格下垫三四张，一次能出四份；课程名称、教师这类每份都一样的信息，刻成铅字章一盖了事。但姓名和学号还得一份一份写，复写纸一次最多四五份，四十份要分十次做。例如，一位老教师回忆，学期末办公室最常见的景象，是几个人围着一张桌子，一人分十份地写。

第三代，Word 与“另存为”。 九十年代以后模板进了电脑，做法变成“打开模板 → 填 → 另存为 → 再打开模板 → 再填”。这一代最大的进步是版式不用重画，最大的隐患也正在这里：你手上没有任何一样东西，能告诉你四十份里有没有漏掉一个人。 另存出来的四十几份文件，名字形态一样、内容只差几个字，人眼一晚上也数不清。

第四代，也就是这一讲：名单进、批量出、回头对账。 名单是唯一的输入，产物是唯一的输出，两头都有名字可点。这一代真正的进步不是快，而是“可对数”——它第一次让“一个都没落下”变成一句能验证的话。

回头看这条线，规律很清楚：前三代解决的都是“怎样写得快一点”，第四代解决的是“怎样证明写全了”。 一件要负责任的事，最后一定要落到“可验证”上；否则快得越多，心里越没底。

2.3 名单对账：三个数

“按名单批量”这类活必须配一个对账动作，三个数：

• 应交 N 份：选课名单的条数（名单以教务系统导出为准，不是以“我印象里班上有多少人”为准）
• 实交 N 份：引擎返回的 documents 里有几个产物文件。只按报告里的产物清单数，不是按你眼睛数文件夹
• 缺谁：应交的份数减去实交的份数，缺的那几个名字是谁。比如应交 40、实交 39，那 1 个差额就是缺的那个人；差额若是 2，多半是名单里多抄了一行，或者出件时漏了两个。

对账的办法要落到学号上，不能只靠姓名：

• 学号是唯一的，姓名不是——同一个班有名同姓的两个人是很常见的事。
• 产物文件名的形态是“学生姓名 - 课程名称 - 结课作业.docx”（本书实测样例：王振杰-财经公文写作-结课作业.docx）。文件名里有姓名、没有学号，所以对账时先用“名单里的姓名 → 产物文件名里的姓名”比一遍，再把名单里的学号逐条核进产物内容，两边都要对得上。
• 差额不为零时，不要手工补一份了事——那会绕过校验。回去改数据、重跑、重新对账，让报告和名单一致。

2.4 设问自答之一：40 份要多久

问得实在。这个问题的答案分两半：出件那一半，和整理名单那一半。

出件那一半，份数不是难点。 本书实测跑的是名单里的两位学生（王振杰、蒋泽熙），一次 filler_batch 调用出件；换成 40 位学生，就是把 students 列表写满 40 条，动作还是同一个——一个动作对两条记录，和对四十条记录，是同一件事，只是记录多了。 你不需要为份数加人、加时间、加耐心。

整理名单那一半，才是真正花时间的地方。 从教务系统导出来的 Excel 通常有多余的列（成绩、联系方式、选课时间），有的还夹着筛选隐藏行。比如，一位老师复制名单时漏了被筛选隐藏的那一行，结果全班只出了 39 份，缺的正是那个被藏起来的学生。这一步花的那几分钟，是这一讲唯一不能省的人工时间——因为它是数据的入口，入口错，整批跟着错。

一句话记住：手工出件的时间随份数涨；批量出件的时间只跟名单整理那一步有关。

2.5 设问自答之二：姓名里有生僻字，会不会乱码

会有人担心：学生名字里有个不常见的字，机器一处理就变成方块或者问号。

把这件事拆成两段看，就清楚了。一段是文件里的字。成品 docx 用 Unicode 存字，中文（含生僻字）本身不会因为“生僻”而变成方块，这一层不是本讲的风险点。另一段是文件名进下载链接的那一步。中文文件名（王振杰-财经公文写作-结课作业.docx）要变成链接里的百分号编码，例如“王”会写成 %E7%8E%8B 这样一串；某些客户端对这个编码不友好，点开会报错，或者存下来一个乱码名。

所以处理办法是两条：第一，文件本身没问题，别对着一个乱码的文件名就以为内容错了——把链接里的编码形态复制完整，或者换一个浏览器再点；第二，下载下来打开看一眼，确认姓名那一行是对的，这一眼比猜测便宜得多。

生成得对，不等于传得顺；传得不顺，不等于生成错了。 这两件事要分开判断，否则容易冤枉工具，也容易放过真错。

2.6 设问自答之三：班上有两个同名的人怎么办

这是学生粒度场景里最容易被漏掉的一种情况，而且它不会报错。

假设名单里有两个“张伟”，学号一个 01 结尾、一个 17 结尾。如果你对账时拿姓名当唯一键，系统会把两个人认成同一个人：出一份文件、对一次账，账面还“平”了——因为你的键本身就把两个人压成了一个。等到其中一个学生来问“为什么没我的”，你才发觉。

正确做法只有一条：对账以学号为唯一键。 名单里的学号、产物内容里的学号，逐条对；姓名用来在文件名层面做初筛，但不能用来做去重。打个比方，学号是身份证号，姓名是称呼——同一栋楼里叫“小王”的可能有三个人，你点名靠的是号，不是称呼。

2.7 实测长什么样

本书写作时跑过两条真实记录：名单里的王振杰、蒋泽熙，课程《财经公文写作》，教师任渝。

产出：王振杰-财经公文写作-结课作业.docx，88,523 字节，公网可下载（HTTP 200）。 蒋泽熙一份同样校验通过。

（本讲的实测样例只跑了名单里的这两位；全班 40 人的做法与这两位完全相同，差别只在 students 列表里多写 38 条。）

2.8 一张对照表：人工做法与批量做法，差在哪里

把上面几节摊成一张表，差距比“快慢”更值得看：

表里最该注意的是倒数第二行：结课作业的错，不是“格式不对退回来重做”，而是学生的东西真没到手上。所以本讲的交付标准比别处更硬——名单、份数、文件名、学号，四个东西必须两两对得上。

三、动手三件套

一句话指令（可直接复制，把名单换成你的）

用 filler_scenarios 选 homework 场景，再用 filler_help 看数据骨架；

然后用 filler_batch 按名单给全班出结课作业：

list_json 里一名学生一条（学号、学生姓名、专业、课程名称、教师姓名）；

context_json 传 {“semester”:“2026学年春季学期”,“department”:“智能金融学院”,“generate_time”:“2026年9月17日”}；

出完把实交份数列给我，并与名单条数对账：应交几份、实交几份、缺哪几个人；

最后调 filler_check 把校验报告读给我。

四条要求各有用处：点场景（homework 是学生粒度）、点两层数据、点对账（应交 / 实交 / 缺谁）、点校验（报告通过才算交付）。

只有一两名学生、想先试通链路时，把 filler_batch 换成 filler_run，其他照旧——先出一份，读回核对，再出整批，这是所有名单类活的标准节奏。

预期产物

（本书写作时的实测样例：王振杰-财经公文写作-结课作业.docx，88,523 字节，公网可下载。）

校验点（这一步不许跳）

1. 应交 = 名单条数：名单从教务系统导出，逐条数过一遍。40 人的班就是 40 条。
2. 实交 = 报告里 documents 的条数：只认报告，不认“文件夹里看着挺多”。
3. 差额为零，缺谁写得出来：不为零时先别补件，先查数据。
4. 学号逐条核：抽三份（第一份、中间一份、最后一份），把学号与学生本人对一遍。学号错一位是最典型的错误，也是最难事后发现的错误。
5. 公共信息三处一致：学年学期、开课部门、生成时间，40 份都要一致（示例里是“2026学年春季学期”“智能金融学院”“2026年9月17日”）。
6. 占位符残留 = 0：成品里搜不到 {{ 记号。
7. 校验结论过门：filler_check 给出的结论必须是「校验通过（未替换 0 / 缺失 0）」。不是这个结论，不交。

四、常见错误与排错

错误一：份数比名单少。

表现：应交 40 份，实交 39 份或 1 份。

原因：数据形状传错——给了单条字典（不是列表）时会被自动包成一条；或名单本身少抄了一行（Excel 里被筛选隐藏的行，复制时最容易漏）。

排错：先核名单条数，再核份数；两个数都对了再看内容。

错误二：姓名对了，学号错了。

表现：文件名全对，打开内容发现学号串了行。

原因：students 列表里姓名与学号本来就是两列，粘贴时错位。

排错：抽三份逐字核学号；发现串行，改数据重跑，不要手工改成品。

错误三：班上有两个同名的学生，只出了一份。

表现：份数比名单少一人，且少的那个姓名和别人重名。

原因：以为“同名就是同一人”，或者对账时用姓名做了去重键。

排错：对账以学号为唯一键；重名的情况要在名单里就看出来，别等到出件后才发现。

错误四：想着“缺两份而已”，手工补做了。

表现：交上去的份数够了，但补的那两份没走过校验。

原因：图快，绕过了链路。

排错：补件只能是重跑出来的。手工补的那份一旦有占位符残留或学号写错，问题照样落在学生头上。

错误五：链接发给别人，或者贴进了班群。

表现：图省事，把整批下载链接直接丢进群。

原因：这些链接里带着学生的姓名与学号，等于把个人信息发到了公开场合。

排错：产物的链接不转发，见下一节的边界。

五、边界与红线

学生名单的数据边界，本讲的规矩只有一句：只在本机、只在你自己的环境里流转一次。

具体是四条：

• 名单文件放本机：选课名单从教务系统导出后，放在自己电脑上一个明确的目录里，不放公共盘、不丢在桌面、不进聊天记录。
• 只提交必要的字段：这条链路只需要学号、姓名、专业、课程名称、教师姓名。成绩、身份证号、联系方式、家庭信息一概不放进去——多一个字段，多一份风险，而且对出件毫无用处。
• 只在本次任务的链路上走一趟：数据只用于这一次出件；出完就把名单从工作目录里收好，产物与名单都不外传、不发群、不用于非教学场合、不拿去做任何演示素材。
• 产物链接不外发：链接里带着学生姓名与学号；发给学员本人可以，丢进公开群、贴到公开页面不行。

另外三条红线：

• 成绩与作业是学生的：作业内容、评分、评语属学生个人信息与教学资料，不导出、不带出教学场景。
• 出件不等于交付：对账没做、校验没通过、名单还有缺人的，不许交。
• 签字责任在人：40 份作业交出去之前，本人复看并签字，这条没有例外。举个例子，即便报告上写着「校验通过」，签字的那一刻起，这四十份就是“你交的件”，出任何问题都是你的责任，不是引擎的。

六、拓展与学科迁移

• 变式一：按名单出别的表。 同一套做法可以出考查作业、课程论文封面、实习鉴定表、实训报告封面——只要一人一份、姓名学号不同，都是学生粒度。
• 变式二：按名单出成绩单或通知。 辅导员场景里常见：按班级名单出成绩告知单、学业警示通知、家长告知书；注意成绩与告知类材料的字段比作业更多，放进链路的字段要按“最小必要”重新剪一遍。
• 变式三：一个学院一起出件。 教学秘书把全院班级名单并成一张表，按班分批跑 filler_batch；这时“份数对账”比单个班更要紧——应交几个班、实交几份，一眼对不上就是有班漏了。
• 跨专业：电子商务专业的实训报告、财务管理专业的案例作业、国际经济与贸易专业的报关实训封面——学生粒度的活方法完全一致。
• 跨角色：辅导员（班级名单出通知类材料）、教学秘书（全院按班批量出件）、专业负责人（专业级名单对账与归档）。
• 接下一讲：出完件之后还差一步——第 13 讲，校验报告怎么读，以及为什么报告上不是「校验通过」就不许交付。

带走一句话

机器能保证四十份长得一样，只有你能保证四十份一个人不少——对账的那三个数，就是你的签名。

背后的引擎（本讲速查）

本讲要点（速记）

• 记录条数 = 出件份数：名单 40 条就该有 40 份，份数不对先查数据形状
• 对账三个数：应交（名单条数）/ 实交（报告里的产物条数）/ 缺谁
• 对账认学号不认姓名：学号唯一，姓名可能重名
• 缺件只能重跑，不能手工补：绕过校验的补件等于没校验
• 数据边界一句话：名单只在本机、只在自己的环境里流转一次；链接不外发
• 实测规模：王振杰-财经公文写作-结课作业.docx，88,523 字节，公网可下载

参考文献

[1] 教育部. 高等学校预防与处理学术不端行为办法: 教育部令第 40 号[Z]. 2016-06-16.

[2] 中华人民共和国教育部. 教育部关于加快建设高水平本科教育 全面提高人才培养能力的意见: 教高〔2018〕2号[A]. 2018.

[3] OpenAI. Function calling[EB/OL]. https://platform.openai.com/docs/guides/function-calling.

数据与平台：本讲实测数据来自 zhenyuonline.cn 的 doc-filler 引擎填制能力（2026-09-17 实跑）。

homework 场景（结课 / 考查作业）模板 8 个占位符，学生粒度，两条学生记录（32303801 王振杰、32304017 蒋泽熙，专业均为资产评估与管理，课程《财经公文写作》，教师任渝），

配顶层公共信息（semester = 2026学年春季学期、department = 智能金融学院、generate_time = 2026年9月17日），

产出 王振杰-财经公文写作-结课作业.docx，88,523 字节，公网可下载（HTTP 200），校验通过（未替换 0 / 缺失 0）。

产物已作脱敏处理；本讲不给出 40 份全班的耗时数字，因为该书实测只跑了两条记录。