说文外挂 · 部件级汉字理解模型
概述
本技能提供一个已训练完毕的"部件向量"小模型：把汉字拆解为直接部件（清→水+青），为 8,869 个部件各学习一个 32 维向量，并用双目标训练使其承载《说文解字》式结构语义——形符向量锁定部首类别（水→水部），声符向量锁定读音韵母（青→ing）。用于回答"这个字为什么这样写""哪些字与它同源/同声旁""部件在字里扮演什么角色"等结构分析问题。
模型能力边界（务必向用户说明）：
- 它提供结构层证据（拆解、部首、声旁、统计亲缘），不替代《说文解字》的文献考据（本义引申链、甲骨文金文字形演变等需另行查证典籍）。
- 声旁→韵母预测精度 42.2%：汉字读音历史演变导致同声旁多读（如"相"），输出应表述为概率倾向而非定论。
快速开始
所有命令在技能根目录执行，Python 需 numpy（重训另需 scipy、hanzi-chaizi）：
cd <技能目录>/scripts
python query.py 清 晴 # 逐字分析：拆解/形旁/声旁/部首预测/韵母预测/近邻/家族
python query.py --text 清水河山 # 批量分析一段文本中的已收录字
python query.py --component 青 # 部件视角：该部件的部首/韵母亲和度 + 作形旁/声旁的字例
python query.py --stats # 模型规模与指标
输出为 UTF-8 JSON。若用户只要简要结论，读取 JSON 后用一句话总结即可，不要整段粘贴。
回答框架（说文式三段）
回答"X 字怎么理解"类问题时，按此结构组织，并明确区分层级：
- 结构层（本模型，客观可查）：
query.py X得到的拆解——形旁（表义类属）、声旁（表音倾向及概率）。 - 传统训诂层（标注来源）：如需《说文》原文释义，须查证典籍原文，不得凭记忆编造；查不到就明说。
- 演变层（谨慎）：字形演变、本义引申属文献考据问题，学界有争议时摆出各家说法。
重训 / 复现（仅在用户明确要求时）
python scripts/build_data.py # 需联网下载 Unicode Unihan 18.0（~34MB）+ pip install hanzi-chaizi
python scripts/train.py # 纯 numpy 训练 1500 轮（数分钟），写出 data/embeddings.json
python scripts/gen_report.py # 生成 HTML 验证报告
注意：重训会覆盖捆绑的已训练模型；先备份 data/embeddings.json。
资源
scripts/query.py— 主查询 CLI（仅依赖 numpy），日常使用只跑它scripts/store.py— 数据存取层（数据集与模型均以纯文本 JSON 读写，兼容 .gz/.npz 旧格式）scripts/build_data.py/train.py/gen_report.py— 数据构建、训练、报告生成data/dataset.json— 26,712 字：拆解、部首、读音、形旁/声旁标注（约 2.7MB）data/embeddings.json— 已训练的部件向量与分类头（纯文本 JSON，约 2.6MB）data/analysis.json— 定性分析结果（字形近邻、部件亲和度等）assets/demo_report.html— 完整验证报告示例（含训练曲线与 42 字逐字验证卡片）references/method.md— 方法论、指标解读与已知局限（回答深挖问题时加载）references/THIRD_PARTY_NOTICES.md— 第三方数据/代码许可声明（Unihan、hanzi-chaizi）
为什么用纯文本存储
发布平台（SkillHub）只接受纯文本文件类型，.png / .gz / .npz 等二进制会被服务端直接拒绝。
因此模型以 JSON 序列化 numpy 数组（浮点保留 5 位小数），数据集使用明文 JSON。
对全部 26,712 字逐字对照：部首/韵母 argmax 判定与 float64 原版完全一致（0 字差异），
部首概率最大绝对偏差 1.2e-05。代价是体积增大（总计约 5.4MB），换取平台兼容性。
训练中间态（字偏置 B、标签 y）不进分发包，仅保留在本地 npz 中。
