跳到主内容
芝麻园地
← 返回博客
#前端开发#儿童教育#SVG#PDF导出#Astro

给娃做了个「A4 助学工坊」:生字描红、口算练习与格纸打印,怎么做到严格一页 A4?

给家长和老师做的免费在线 A4 学习纸生成器:支持汉字田字格/米字格字帖描红、20/100以内加减乘除口算出题、标准空白练习纸生成。采用物理毫米坐标排版与开源楷体矢量字体嵌入,严格保证单页恰好 A4,支持直接下载矢量 PDF 与干净打印,配套独立家长参考答案。

芝麻园地 24 分钟

家里有幼小衔接或小学低年级娃的家长,大概都经历过这种折腾: 老师让每天练习 4 个生字,或者做 20 道 20 以内口算题。打开网上的字帖生成器或口算生成网页,往往遇到一堆让人抓狂的问题:

  • 满屏浮动广告,点一下“打印”弹出来三个推广窗口;
  • 打印排版不可控,网页上的预览看着挺好,一按 Ctrl+P,最后两道题硬生生被挤到了第二页,白白浪费一张纸;
  • 有的工具为了“凑一页”,悄悄把字号缩小、或者干脆把最后几个字截断舍弃;
  • 导出的所谓的“PDF”其实是把网页截了张低清位图塞进去,打印出来字体毛糙发虚;
  • 算术出题漏洞百出,要么经常抽到重复题,要么口算题和答案混在一张纸上,家长核对特别费劲。

为了让家长和老师能30 秒内选好内容、调好难度,直接拿到一张孩子拿笔就能练的高清 A4 练习纸,我们在芝麻园地开发了全新工具——A4 助学工坊(A4 Learning Workshop)。

👉 在线体验入口:https://zhimayuandi.com/tools/a4-workshop

无需注册、零广告、零数据上传,支持汉字字帖描红、小学加减乘除口算与标准空白格纸,且严格保证:练习纸恰好一页 A4,题目与答案完全分离。

这篇文章不仅想聊聊这个小工具背后的设计思考和技术细节,也借这个机会分享:我是如何借助 AI 智能体(Agent),从一个模糊想法完整跑通产品落地的真实协同过程。


一、人机协同实践:我是如何让智能体做出一款复杂应用的?

很多人使用 AI 辅助编程时,最常遇到的挫败感是:“一上来就让 AI 帮我写代码,改了十轮越改越乱,最后代码成了一团乱麻不得不推倒重来。”

做「A4 助学工坊」时,我没有直接扔一句“帮我写个字帖和口算网站”,而是采用了一套极其清晰高效的人机协同四步法,这也是整个应用高质量落地的关键秘诀:

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  阶段一:发散   │ ───> │  阶段二:收敛   │ ───> │  阶段三:设计   │ ───> │  阶段四:落地   │
│ 需求头脑风暴讨论│      │ 编写需求文档    │      │ 智能体出系统设计│      │ 智能体全链路实现│
│ (澄清场景与痛点)│      │ (requirements)  │      │ (system-design) │      │ (代码/测试/构建)│
└─────────────────┘      └─────────────────┘      └─────────────────┘      └─────────────────┘

1. 第一步:头脑风暴与需求讨论(把模糊诉求聊透)

先不急着写一行代码,而是把 AI 智能体当作资深产品搭子,进行一轮高密度的需求发散讨论:

  • 梳理真实使用人群:是幼小衔接、小学一二年级家长还是代课老师?
  • 梳理典型场景:今天课堂留了 4 个生字练习、每天清晨 20 道 20 以内口算打卡、放学回家临时需要一张空白田字格纸;
  • 划定首期铁律边界(P0):不做复杂的账号登录、不做拍照批改、不做 AI 智能判卷,死磕“拿到就能练的干净 A4 纸”,将核心精力聚焦在排版精度与出题质量上。

2. 第二步:沉淀确定性的需求基线(requirements.md)

头脑风暴结束后,我将共识整理成白纸黑字的需求规格文档:

  • 功能需求(FR-01 到 FR-10):明确生字标准格(20mm)与大格(25mm)的列数与模式配比,明确口算加减乘除范围与进退位约束,明确题目必须去重,明确练习卷与答案卷必须独立;
  • 非功能约束(NFR-01 到 NFR-08):明确计算必须 100% 运行在浏览器本地、单页 PDF 不得超过 5MB、样式严禁污染全站弹层等;
  • 验收场景(AC-01 到 AC-15):列出具体的测试用例(如“输入春风花草田字格每字一行应为 4 行”、“100 以内退位减法每题必须有借位”等)。

有了这份文档,人与 AI 之间就有了坚实的需求契约,不再存在“猜谜”空间。

3. 第三步:让智能体主导系统架构设计(system-design.md)

有了需求文档后,我并没有急于让它编码,而是发出指令:“请根据 requirements.md 进行深度系统设计”。

智能体给出了非常专业且深思熟虑的架构设计方案:

  • 为什么放弃像素(px)? 决定基于物理毫米(mm)建立结构化绘制原语(Line/Rect/Text),实现屏幕展示、PDF 和原生打印的一致性;
  • 为什么放弃前端截图(html2canvas)? 决定寻找符合部编版教学规范的开源楷体,用 Python fontTools 做离线子集化提取 3500 常用字,让 jsPDF 实现真正的矢量嵌入;
  • 为什么打印不用 window.print() 直接打主页? 决定通过隔离 iframe 注入 @page 独立环境,彻底避免影响全站全局样式。

系统设计文档把数据结构(WorksheetSpec、PageScene)、状态流转、目录划分和测试方案全盘定型。

4. 第四步:按图索骥,端到端编码与闭环验证

到了最后一步,指令变得极其简洁有力:

“请根据系统设计和需求分析实现一下。”

此时智能体执行起来如鱼得水:

  • 编写离线字体处理脚本,裁剪出 1.7MB 的中文字体与 manifest.json;
  • 编写纯逻辑模块(进退位判定、Mulberry32 随机数、物理毫米排版);
  • 编写 11 组核心单元测试,执行 node --test 全部跑通;
  • 编写 React 交互 Island、Astro 双语页面与中英文元数据;
  • 执行 astro check 与 pnpm build 全量静态验证,一次性交付,几乎零返工。

给朋友们的建议:使用 AI 编写稍微复杂的软件时,千万别跳过“需求文档”和“系统设计文档”。把思考和推演留在文档阶段,编码落地就会像流水线一样顺畅自然。


二、核心产品原则:绝不妥协的“单页原则”

在立项之初,我们就确立了一条铁律:所见即所得,一页就是一页(Zero Overflow Compromise)。

很多在线打印工具的做法是:当用户输入的汉字过多、或者选了 48 题口算时,要么偷偷缩小字号把内容“塞进去”,要么用 CSS 把超出容器的部分 overflow: hidden 截断。这在教育场景下是极其不负责任的——字号过小会伤害低年级孩子的视力与握笔姿势,而静默截断会导致孩子少练生字。

在 A4 助学工坊中:

  1. 真实物理容量硬约束:标准 20mm 田字格一页最多容纳 10 行汉字(每字 1 行即最多 10 个字,每字 2 行最多 5 个字);25mm 大格最多容纳 8 行。一旦超出,页面会直接以清晰明确的红框提示“当前版式最多可容纳 10 行,当前需要 14 行”,并禁用下载和打印按钮,绝不偷偷截断或降级。
  2. 算术排版分级管控:标准档(4 列,行高 18mm)最多容纳 52 题;宽松档(3 列,行高 24mm,大字号)最多容纳 27 题。当用户勾选 48 题又切换到宽松档时,系统明确提示“宽松档最多 27 题”,引导家长做合理决策。
  3. 练习卷与答案卷彻底分离:家长练习纸上绝不带答案;点击“展开参考答案”后,系统在独立区域生成一张题序、编号 100% 对应的独立单页答案卷,支持单独下载或打印。

三、纸面排版引擎:抛弃像素,回归物理毫米模型

屏幕设备有千差万别的 DPR(设备像素比)、缩放比和视口宽度。如果直接使用 HTML+CSS 的 px 单位进行排版,在不同屏幕上渲染出的物理尺寸必定产生漂移。

为此,我们构建了一套独立的物理毫米纸面模型(PageScene):

  • 基准规格:固定 A4 纵向 210mm × 297mm,四周设置各 12mm 的绝对安全留白(符合主流家庭喷墨与激光打印机的物理不可打印边距);
  • 布局划分:
    • 页头预留 24mm(容纳标题、班级、姓名、日期可手写横线);
    • 练习主区域 186mm × 236mm(左上角物理绝对坐标 x: 12mm, y: 42mm);
    • 页脚预留 7mm(展示可选的练习卷唯一识别编码,如 WS-7A3B9F2C);
    • 针对纯格纸模式:当关闭所有标题和信息栏时,系统自动释放页头预留,将练习区铺满整张 186mm × 273mm 的纯格纸。

整个布局引擎是一个纯纯的函数式管道:

WorksheetSpec (用户配置)
      ↓
validate.js (NFC规范化、码点解析、约束校验)
      ↓
layout.js (毫米计算、容量检查、格线与文字对齐)
      ↓
Immutable WorksheetDocument (包含 PageScene 绘图原语)
      ↓
┌───────────────────────┬─────────────────────────┬─────────────────────────┐
│     SVG 矢量预览      │     jsPDF 矢量下载      │   隔离 iframe 原生打印  │
└───────────────────────┴─────────────────────────┴─────────────────────────┘

PageScene 只输出极其纯粹的轻量几何原语:

  • LinePrimitive:指定 x1, y1, x2, y2(毫米)、线宽、颜色、虚线阵列(用于田字格、米字格中线);
  • RectPrimitive:指定外边框矩形;
  • TextPrimitive:指定文本、精确 baseline 毫米位置、字号(pt)与对齐锚点。

四、最大的技术挑战:中文字体子集化与矢量 PDF 导出

在做汉字字帖时,很多开发者容易踩两个大坑:

  1. 依赖客户端本机字体:用 CSS font-family: Kaiti,结果在 Mac 上显示楷体,在 Windows 上显示黑体,在 Linux 或手机上直接变成了无衬线字体,字形完全不符合部编版教学字形规范;
  2. PDF 生成靠截图:用 html2canvas 截一张大图塞到 PDF 里。这不仅会让导出的 PDF 动辄几十兆,而且用打印机打出来边缘充满锯齿和模糊毛刺,完全无法当作正规描红字帖。

要实现真正的矢量字体直接嵌入 PDF,挑战在于:

  • jsPDF 依赖原生 TrueType (.ttf) 文件并将其 base64 打包进 PDF;
  • 完整的一套中文字体(如思源宋体、开源文楷)通常在 25MB ~ 35MB 之间。如果让用户的浏览器每次下载 25MB 字体,或者导出一张 A4 纸生成一个 30MB 的 PDF,是完全不可接受的。

优雅的解决方案:fontTools 离线子集化

我们选用了广受好评、字形规范优美的开源教学字体 霞鹜文楷(LXGW WenKai,SIL OFL 1.1 开源协议)。

在构建期,我们编写了一个自动化的 Python 处理脚本 scripts/prepare-a4-font.py:

  1. 以国家《通用规范汉字表》一级常用字(3,500 字)和 GB2312 一级字库为基础,结合英文字母、数字、常用中文标点和数学算术符号(+, −, ×, ÷, =);
  2. 使用 fontTools.subset.Subsetter 对 25MB 的原始字体进行精准切削抽离;
  3. 将最终字体体积压缩至 1.70 MB!
  4. 同时从 TrueType 内部的 cmap 和 hmtx 表中提取出字体度量信息,生成一份紧凑的 manifest.json:
    • 记录字体的 unitsPerEm、ascender、descender;
    • 记录包含 3,889 个字符的精准 Unicode 码点清单;
    • 记录每个字符的 advance 宽度。
# 核心子集化逻辑片段
from fontTools.ttLib import TTFont
from fontTools.subset import Subsetter, Options

options = Options()
options.desubroutinize = True
options.name_IDs = ["*"]

font = TTFont("LXGWWenKai-Regular.ttf")
subsetter = Subsetter(options=options)
subsetter.populate(text="".join(full_char_set))
subsetter.subset(font)
font.save("public/fonts/a4-workshop/handwriting.ttf") # 1.7MB

带来的巨大收益:

  • 秒级加载:1.7MB 在现代网络下仅需百毫秒加载,浏览器通过 FontFace 注入,jsPDF 导出时直接读入 VFS;
  • 纯矢量高清:导出的单页 PDF 大小仅 1.8MB 左右,在 PDF 阅览器中放大到 1000% 依然是丝滑圆润的矢量曲线;
  • 毫秒级缺字拦截:在用户输入汉字时,前端直接用 manifest.json 的 Set<number> 校验。如果用户输入了极度罕见的生僻字,系统会当场高亮指出具体字符,绝不让打印机打出“豆腐块”缺字方框。

五、算术出题引擎:不仅是随机出题,更是严谨数学规则

很多口算生成器写得很随意:Math.random() * 20,减法判断 a > b 就完了。但在真实的幼小衔接教学中,“进位”和“退位(借位)”是具有严格教学梯度的。

我们重写了算术候选池生成算法:

1. 逐位十进制进退位判定

加法进位绝不只是看个位数相加。例如 50 + 50 = 100,十位数产生了进位,属于纯正的进位加法。

export function hasAdditionCarry(a, b) {
  let carry = 0;
  let na = Math.floor(a), nb = Math.floor(b);
  while (na > 0 || nb > 0 || carry > 0) {
    const da = na % 10, db = nb % 10;
    if (da + db + carry >= 10) return true;
    carry = Math.floor((da + db + carry) / 10);
    na = Math.floor(na / 10);
    nb = Math.floor(nb / 10);
  }
  return false;
}

同理,减法借位也通过逐位比对:

export function hasSubtractionBorrow(a, b) {
  if (a < b) return false;
  let borrow = 0;
  let na = Math.floor(a), nb = Math.floor(b);
  while (na > 0 || nb > 0) {
    const da = na % 10, db = nb % 10;
    if (da - borrow < db) return true;
    borrow = 0;
    na = Math.floor(na / 10);
    nb = Math.floor(nb / 10);
  }
  return false;
}

2. 约束去重与加减混合配额

  • 全局唯一题对:以 operator:left:right 为唯一键去重。注意:根据教学规范,3 + 5 和 5 + 3 交换加数被视为两道不同的启发题,但同一份练习纸内绝不出现两道完全相同的题目;
  • 候选池不足有限结束:例如用户选择“10 以内加法、必须进位、出 24 题”。实际上 10 以内进位加法(和<=10)的所有可能题目只有 1+9, 2+8, ..., 9+1 共 9 题。算法在枚举完候选池后发现只有 9 题,会立即返回结构化错误:候选池题目不足:当前约束下仅有 9 道可用加法题,需要 24 道,引导用户放宽条件或减少题数,坚决不搞死循环,也不偷偷塞入重复题;
  • 可复现伪随机种子(Mulberry32):修改纸面标题、切换明暗主题、缩放预览或下载两次 PDF,题序与题目绝对保持一致;只有用户主动点击“换一套题”时,才会派发新种子重新抽题。

六、隔离 iframe 打印:绝不污染全站样式

在网页中调用 window.print() 最让人头疼的是 CSS 样式渗透:

  • 很多工具直接在全局样式里写 @media print { body * { display: none } },往往会把挂载在 <body> 上的全局弹窗(如 CommandPalette ⌘K 搜索框)搞崩溃;
  • 打印时往往带出网页的页眉、侧边栏和底栏。

我们采用了动态隔离 iframe 打印方案:

  1. 点击“直接打印”时,在屏幕外动态挂载一个无边框 iframe;
  2. 向 iframe 内部独立写入完整的纯净 HTML 骨架与 @page { size: A4 portrait; margin: 0; };
  3. 将当前 PageScene 渲染的矢量 SVG 灌入 iframe;
  4. 等待 iframe 内部的 document.fonts.ready 加载确认就绪,微任务缓冲一帧后,调用 iframe.contentWindow.print();
  5. 监听 afterprint 事件并在打印完成后彻底销毁 iframe。

主页面与打印宿主完全物理隔离,主站样式和搜索弹层零污染。


七、工程质量与自动化测试验证

整个功能开发严格遵循芝麻园地项目的工程规范:

  • 纯逻辑测试覆盖:编写了 tests/a4-workshop-core.node.mjs,包含 11 组细致的原生单元测试,覆盖了:
    • Mulberry32 确定性随机数与洗牌;
    • 文本 NFC 规范化与标点分隔符识别;
    • 码点上限与缺字检测;
    • 加减法逐位进位/借位精准性;
    • 候选池不足有限终止与加减混合平衡;
    • 字帖 10 行/8 行单页硬约束与溢出拒绝;
    • 48 题宽松档容量拦截;
    • 真实 manifest.json 3,889 个字符覆盖率验证。
  • 全仓严格检查:执行 pnpm exec astro check,全仓 1,362 个文件保持 0 错误、0 警告;
  • 双语完整构建:pnpm build 输出 585 个页面,英文版 /en/tools/a4-workshop 和中文版 /tools/a4-workshop 均生成了独立的 canonical、hreflang、JSON-LD 与站内搜索索引;儿童乐园分类统计同步更新。

八、写在最后

做一个工具很容易,但把一个工具做到“刚刚好、不添乱、不凑数、足够好用”,却需要很多看不见的工程细节:

  • 为了不用截图,我们啃了 TrueType 规范做了字体子集;
  • 为了不浪费打印纸,我们算清了每个毫米的网格和安全边距;
  • 为了不泄露孩子隐私,我们白名单过滤掉了所有私人正文,刷新不留底。

愿每一位用心陪伴孩子成长的家长和老师,都能在需要的时候,花上 10 秒钟,打印出一张舒心、干净、孩子爱练的 A4 练习纸。

欢迎体验与提出建议: 🔗 A4 助学工坊:https://zhimayuandi.com/tools/a4-workshop