家里有幼小衔接或小学低年级娃的家长,大概都经历过这种折腾: 老师让每天练习 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 助学工坊中:
- 真实物理容量硬约束:标准 20mm 田字格一页最多容纳 10 行汉字(每字 1 行即最多 10 个字,每字 2 行最多 5 个字);25mm 大格最多容纳 8 行。一旦超出,页面会直接以清晰明确的红框提示“当前版式最多可容纳 10 行,当前需要 14 行”,并禁用下载和打印按钮,绝不偷偷截断或降级。
- 算术排版分级管控:标准档(4 列,行高 18mm)最多容纳 52 题;宽松档(3 列,行高 24mm,大字号)最多容纳 27 题。当用户勾选 48 题又切换到宽松档时,系统明确提示“宽松档最多 27 题”,引导家长做合理决策。
- 练习卷与答案卷彻底分离:家长练习纸上绝不带答案;点击“展开参考答案”后,系统在独立区域生成一张题序、编号 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 导出
在做汉字字帖时,很多开发者容易踩两个大坑:
- 依赖客户端本机字体:用 CSS
font-family: Kaiti,结果在 Mac 上显示楷体,在 Windows 上显示黑体,在 Linux 或手机上直接变成了无衬线字体,字形完全不符合部编版教学字形规范; - 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:
- 以国家《通用规范汉字表》一级常用字(3,500 字)和 GB2312 一级字库为基础,结合英文字母、数字、常用中文标点和数学算术符号(
+,−,×,÷,=); - 使用
fontTools.subset.Subsetter对 25MB 的原始字体进行精准切削抽离; - 将最终字体体积压缩至 1.70 MB!
- 同时从 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 打印方案:
- 点击“直接打印”时,在屏幕外动态挂载一个无边框 iframe;
- 向 iframe 内部独立写入完整的纯净 HTML 骨架与
@page { size: A4 portrait; margin: 0; }; - 将当前
PageScene渲染的矢量 SVG 灌入 iframe; - 等待 iframe 内部的
document.fonts.ready加载确认就绪,微任务缓冲一帧后,调用iframe.contentWindow.print(); - 监听
afterprint事件并在打印完成后彻底销毁 iframe。
主页面与打印宿主完全物理隔离,主站样式和搜索弹层零污染。
七、工程质量与自动化测试验证
整个功能开发严格遵循芝麻园地项目的工程规范:
- 纯逻辑测试覆盖:编写了
tests/a4-workshop-core.node.mjs,包含 11 组细致的原生单元测试,覆盖了:- Mulberry32 确定性随机数与洗牌;
- 文本 NFC 规范化与标点分隔符识别;
- 码点上限与缺字检测;
- 加减法逐位进位/借位精准性;
- 候选池不足有限终止与加减混合平衡;
- 字帖 10 行/8 行单页硬约束与溢出拒绝;
- 48 题宽松档容量拦截;
- 真实
manifest.json3,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