# handian

**Repository Path**: jasydong/handian

## Basic Information

- **Project Name**: handian
- **Description**: 汉字字典
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 汉字通 · Handict

查询汉字所有信息的 Web 程序：**字形演进**（甲骨文 → 金文 → 楚系简帛 → 小篆 → 隶书 → 楷书）、**字源解析**（含《说文解字》释文）、**字义延伸**（本义 → 引申义链条）、**成语**（精选 + 全库检索）、**古籍例证**（精选引文 + 语料全文检索）。

## 功能一览

| 模块 | 内容 | 数据来源 |
| --- | --- | --- |
| 字形演进 | 六个阶段的字形图片（SVG）与逐阶段解说 | 汉典 zdic.net（运行时抓取并缓存） |
| 字源解析 | 字源故事 + 《说文解字》释文 | 人工精校（48 字） |
| 字义延伸 | 本义 → 引申义链条，附例词 | 人工精校（48 字） |
| 成语 | 精选成语（拼音/释义/出处）+ 含该字成语全库检索 | chinese-xinhua 成语库（31648 条） |
| 古籍例证 | 精选经典引文 + 14 部古籍语料全文检索（自动高亮） | chinese-poetry（《论语》《孟子》《大学》《中庸》《诗经》《楚辞》《古文观止》《唐诗三百首》《曹操诗集》及蒙学读物，含《文字蒙求》） |
| 笔顺动画 | 逐笔书写演示（播放 / 下一笔 / 重置），依国家规范笔顺 | Hanzi Writer（MIT，本地内置）+ hanzi-writer-data 数据集 |
| 拼音检索 | 按音节浏览全部同音字，精校字置前并标记 | 基于汉字库（16142 字）+ 精校档案实时索引 |
| 部首检索 | 按部首笔画分组浏览同部首字，精校字置前并标记 | 基于汉字库（标注部首的 7063 字）+ 精校档案 |
| 字族图谱 | 48 精校字与相关字的力导向关联网络（拖拽/悬停/点击） | 精校档案 related 字段 |
| 全局搜索 | 成语子串检索；拼音音节（可带调）搜同音字；成语拼音全拼与首字母匹配 | 成语库（31648 条）+ 拼音/成语拼音索引 |
| 任意字检索 | 非精校字仍可查询：基本信息、字典释义、字形、成语、古籍 | chinese-xinhua 汉字库（16142 字） |

48 个精校汉字按四类组织：自然造化（日月水火…）、人之形体（人口目耳…）、万物生灵（马牛羊鱼…）、人文伦理（家安明武…仁义礼智孝学书道食）。

## 运行

```bash
cd handian
python3 server.py          # http://127.0.0.1:8400
```

依赖：Python 3.10+，`fastapi`、`uvicorn`、`requests`、`beautifulsoup4`、`opencc-python-reimplemented`。

```bash
pip install -r requirements.txt
python3 scripts/fetch_strokes.py   # 下载笔顺数据集到 static/strokes/（约 30MB，一次性）
```

界面字体为[霞鹜文楷](https://github.com/lxgw/LxgwWenKai)（OFL 协议），已内置本地副本（`static/vendor/lxgw/`），无需外网即可正常显示。

## 测试

```bash
python3 scripts/verify_curated.py   # 校验精校数据
```

无头浏览器界面测试（可选，需本地有 Playwright Chromium）：

```bash
node /path/to/shot.js   # 截图首页/详情页/搜索页，检查布局溢出与资源加载
```

## 目录结构

```
handian/
├── server.py               # FastAPI 后端（API + 汉典字形抓取缓存）
├── data/
│   ├── curated*.py         # 48 字人工精校档案（字源/说文/字义/引文）
│   ├── raw/                # 成语库 idiom.json、汉字库 word.json
│   ├── corpus/             # 13 部古籍语料（JSON）
│   └── glyphs/             # 字形抓取清单缓存
├── static/
│   ├── index.html / style.css / app.js   # 前端（原生 JS 单页应用）
│   ├── glyphs/             # 缓存的字形 SVG（不入库）
│   ├── strokes/            # 笔顺数据（hanzi-writer-data，不入库，fetch_strokes.py 下载）
│   └── vendor/             # 本地依赖：霞鹜文楷字体、Hanzi Writer
└── scripts/
    ├── warmup_glyphs.py    # 预热精校字的字形缓存
    ├── fetch_strokes.py    # 下载笔顺数据集
    └── verify_curated.py   # 校验精校成语/引文与语料一致性
```

## API

- `GET /api/index` — 首页数据：分类字表与统计
- `GET /api/char/{字}` — 单字全量信息（支持繁体输入，自动转简体）
- `GET /api/search?q=词` — 搜索：成语子串、拼音音节搜字（`shui`/`shuǐ`）、成语拼音全拼（`yi lao yong yi`）与首字母（`ylyy`）
- `GET /api/strokes/{字}` — 笔顺数据（本地 hanzi-writer-data 数据集直读）
- `GET /api/pinyin` · `GET /api/pinyin/{音节}` — 拼音音节索引与同音字
- `GET /api/radicals` · `GET /api/radicals/{部首}` — 部首笔画分组索引与同部首字（繁体部首自动转简体）
- `GET /api/graph` — 字族图谱节点边数据

## 数据校验

`python3 scripts/verify_curated.py` 会核对：

1. 每条精选成语存在于 31648 条成语库中
2. 每条古籍引文与语料原文逐字一致（去标点比对）
3. 引文包含本字（通假字以按语说明）、相关字与阶段键合法

## 数据版权

- 字形图片来自[汉典](https://www.zdic.net/)，仅供学习研究
- 成语/汉字数据来自 [chinese-xinhua](https://github.com/pwxcoo/chinese-xinhua)（搜集整理，非商用）
- 古籍语料来自 [chinese-poetry](https://github.com/chinese-poetry/chinese-poetry)（MIT）
- 48 字精校档案为本项目人工整理，采用《说文解字》及古文字学通行观点