方寸 API 文档

格律诗词校验与辅助创作接口。

认证

所有 API 端点无需认证，公开访问。按 IP 限流。

限流

端点	限制
/api/validate_meter	60 次/分钟
/api/free_rhyme	60 次/分钟
/api/dictionary/search	120 次/分钟
/api/dictionary/allusion	120 次/分钟
其他	60 次/分钟

超限返回 429 Too Many Requests。

错误处理

错误统一返回 JSON：

{ "error": "错误描述" }

状态码	含义
400	参数校验失败（无效枚举值、参数过长等）
404	资源不存在（如韵部名不存在）
429	请求频率超限

参数约束

约束	说明
参数长度	所有查询参数上限 2000 字符
请求体	上限 50 KB
`genre`	`Shi`（诗）或 `Ci`（词）
`book`	`Pingshuiyun`（平水韵）、`Cilinzhengyun`（词林正韵）或 `Zhonghua_Tongyun`（中华通韵）
`mode`	`head`、`tail`、`pair`、`tongwei`
`tone`	`P`（平）或 `Z`（仄）

校验格律

核心接口。检测诗词的平仄和押韵是否符合格律规则。返回逐字谱面、结构化错误（含 expected/actual）、韵部信息。

POST /api/validate_meter

请求体 (JSON)

字段	类型		说明
poem_text	string	必填	诗词文本（标点自动忽略，只提取汉字）
genre	string	可选	`Shi`（诗）或 `Ci`（词），默认 `Shi`
rhyme_book_name	string	可选	韵书名，默认 `Pingshuiyun`。可选：`Pingshuiyun`（平水韵）、`Cilinzhengyun`（词林正韵，词用旧韵时务必选此项）、`Zhonghua_Tongyun`（中华通韵）
rule_name	string	可选	指定规则名（如 `沁园春_龙谱_格一`），不传则自动匹配
ensure_longpu	bool	可选	仅匹配龙谱规则，默认 `false`
warnings	string \| string[]	可选	重字检测模式，默认 `default`。可选值见下方
include_punctuation	bool	可选	是否检测句读标点，默认 `false`。为 `true` 时，`poem_text` 应带标点，检测器将校验韵(。)、句(，)、读(、)标点是否正确

warnings 可选值

值	说明
`default`	标准重字检测（叠词豁免），不传时默认
`2gram`	连续两字组合（2-gram）重复检测
`rhyme_duplicate`	仅检测韵脚位置之间的重字
`none`	不检测重字，不可与其他值组合

支持数组组合，如 ["default", "rhyme_duplicate"]（两种检测结果拼接返回）。

请求示例

curl -X POST https://write.sjtuguoxue.space/api/validate_meter \
  -H "Content-Type: application/json" \
  -d '{
    "poem_text": "白日依山尽，黄河入海流。欲穷千里目，更上一层楼。",
    "genre": "Shi",
    "rhyme_book_name": "Pingshuiyun"
  }'

响应字段

字段	类型	说明
is_valid	bool	格律是否通过
closest_rule	object	匹配的规则（name, genre, cipai, char_count）
chars	string[]	清洗后的汉字数组
tone_pattern	string[]	逐字期望声调：`P`(平) / `Z`(仄) / `A`(中，不限)
errors	array	错误列表（见下方）
warnings	array	警告列表（如重字提示）
rhyme_name	string?	检测到的韵部名（如 `十一尤`），换韵时为 `(换韵)`
rhyme_positions	int[]	韵脚所在位置（0-based）
rhyme_chars	string[]	韵脚字
display_segments	array	分段显示数据。`tone`：`P`=平、`Z`=仄、`A`=中（可平可仄）

error 对象

字段	类型	说明
position	int	出错位置（0-based）
character	string	出错的字
error_type	string	`Tone`（平仄）或 `Rhyme`（押韵）
expected	string	期望值（Tone: `P`/`Z`；Rhyme: 目标韵部名）
actual	string	实际值（Tone: `P`/`Z`；Rhyme: 实际韵部名）
message	string	人类可读描述

warning 对象

字段	类型	说明
positions	int[]	出现位置（0-based）
character	string	重复的字（2gram 模式为两字组合）
warning_type	string	`Duplicate`（标准重字）、`Duplicate_2gram`（2-gram）、`Rhyme_Duplicate`（韵脚重字）
message	string	人类可读描述

AI Agent 提示：用 tone_pattern 了解全局谱面要求，用 error 的 expected/actual 定位需替换的字及目标声调。修字后重新调用 validate 验证。

LLM / Agent 填词建议：填词时强烈建议开启 "include_punctuation": true。词牌句读结构复杂（韵、句、读交替），标点检测会返回每个位置应使用的标点类型（韵→句号、句→逗号、读→顿号），帮助模型准确断句，避免句读错位。

查字

查询单个汉字的声调和所属韵部。支持繁体自动转简体。

GET /api/char/lookup

参数	类型		说明
char	string	必填	单个汉字
book	string	可选	韵书名。不传则返回所有韵书

示例 — 指定韵书

curl "https://write.sjtuguoxue.space/api/char/lookup?char=花&book=Pingshuiyun" \

{
  "char": "花",
  "tones": ["平", "上"],
  "rhyme_categories": [
    { "name": "六麻", "tone_type": "P" }
  ]
}

示例 — 不指定韵书（返回所有）

{
  "char": "花",
  "tones": ["平", "上"],
  "rhyme_categories": {
    "Pingshuiyun": ["六麻"],
    "Cilinzhengyun": ["第3部_仄", "第10部_平"]
  }
}

tones 为原始声调（平、上、去、入），rhyme_categories 为韵书中的韵部归属。

查韵部字表

查看某个韵部包含哪些字。

GET /api/rhyme/lookup

参数	类型		说明
book	string	可选	韵书名，默认 `Pingshuiyun`
category	string	必填	韵部名，如 `一东`
include	string	可选	包含关联韵部，逗号分隔（如 `neighbor`）
limit	int	可选	返回字数上限。不传则全量返回（行为不变），传入时 `total` 仍为完整数量
offset	int	可选	跳过前 N 个字，默认 `0`。与 `limit` 配合使用可分页

示例

curl "https://write.sjtuguoxue.space/api/rhyme/lookup?book=Pingshuiyun&category=一东" \

{
  "category_name": "一东",
  "tone_type": "P",
  "total": 392,
  "characters": ["中", "总", "种", "同", "东", "红", "风", ...],
  "relations": {
    "neighbor": ["二冬"]
  }
}

字表按词频降序排列（常用字在前）。relations 标注邻韵等关系。
传入 include=neighbor 时，响应变为 { "primary": {...}, "related": [...] }，同时返回邻韵字表。

韵部列表

列出韵书中的所有韵部概览。

GET /api/rhyme/list

参数	类型		说明
book	string	可选	韵书名，默认 `Pingshuiyun`
tone	string	可选	按声调过滤：`P`（平声韵）或 `Z`（仄声韵）

示例

curl "https://write.sjtuguoxue.space/api/rhyme/list?book=Pingshuiyun&tone=P" \

{
  "book": "Pingshuiyun",
  "categories": [
    {
      "name": "一东",
      "tone_type": "P",
      "char_count": 392,
      "preview": "中总种同衕东梦红风冲"
    },
    {
      "name": "二冬",
      "tone_type": "P",
      "char_count": 262,
      "preview": "从共重龙供冲封鍾鐘钟"
    }
  ]
}

preview 为该韵部最高频的前 10 个字。

格律规则列表

列出可用的诗词格律规则或词牌。

GET /api/rules/list

参数	类型		说明
genre	string	可选	`Shi` 或 `Ci`，默认 `Ci`
search	string	可选	按关键词搜索规则名或词牌名

示例 — 搜索五绝

curl "https://write.sjtuguoxue.space/api/rules/list?genre=Shi&search=五绝" \

[
  { "name": "五绝仄起首句入韵", "char_count": 20 },
  { "name": "五绝仄起",         "char_count": 20 },
  { "name": "五绝平起",         "char_count": 20 },
  { "name": "五绝平起首句入韵", "char_count": 20 }
]

诗 (Shi) 约 16 条规则，词 (Ci) 约 2500+ 条词牌变体。

词语联想

按首字、尾字查诗词用语，或查对仗字。数据来源于古诗词语料统计。

GET /api/dictionary/search

参数	类型		说明
term	string	必填	查询字（支持繁体）
mode	string	可选	`head`（以此字开头）、`tail`（以此字结尾）、`pair`（对仗字/词）、`tongwei`（同位词，对语的对语）。默认 `head`
length	string	可选	词语长度（`2`、`3`...），`all` 返回所有长度。默认 `2`
tone	string	可选	末字声调过滤：`P`（平）或 `Z`（仄）。默认不过滤
limit	int	可选	返回结果数上限。不传则全量返回
offset	int	可选	跳过前 N 条结果，默认 `0`

示例 — 首字联想

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=明&mode=head&length=2" \

[
  ["明月", 2298],
  ["明朝", 1683],
  ["明日", 1398],
  ["明年", 797],
  ["明时", 296]
]

返回 [词语, 频次] 数组，按频次降序排列。

示例 — 对仗字

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=月&mode=pair" \

[
  ["风", 4450],
  ["云", 3575],
  ["花", 1386],
  ["山", 1340],
  ["天", 1142]
]

对仗模式返回与查询字/词在古诗中常对仗的字/词及频次。支持单字和多字查询。

示例 — 多字对仗

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=明月&mode=pair" \

[
  ["白云", 176],
  ["清风", 94],
  ["青山", 71],
  ["西风", 54],
  ["浮云", 47]
]

示例 — 同位词（单字）

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=月&mode=tongwei" \

[
  ["雨", 96],
  ["日", 96],
  ["水", 96],
  ["酒", 85],
  ["风", 80]
]

同位词（tongwei）= 对语的对语。返回与查询字/词在诗中处于相同语法位置、可互相替换的字/词。分数 = 共享对仗伙伴数量。

示例 — 同位词（多字）

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=明月&mode=tongwei" \

[
  ["流水", 66],
  ["落日", 55],
  ["芳草", 55],
  ["细雨", 44],
  ["白日", 39]
]

典故检索

检索包含指定字/词的典形词（文学典故），返回释义、典源、同源典形词和古诗例句。数据约 13,000 条。

GET /api/dictionary/allusion

参数	类型		说明
term	string	必填	1-4 个汉字（支持繁体）
limit	int	可选	最多返回条数，默认 `60`，上限 `200`

示例

curl "https://write.sjtuguoxue.space/api/dictionary/allusion?term=月&limit=5" \

[
  {
    "id": 42,
    "w": "月桂",
    "d": "借指月中桂树，喻科举及第",
    "src": "月中桂",
    "src_text": "《酉阳杂俎》载……",
    "related": [
      { "w": "折桂", "d": "比喻科举登第" },
      { "w": "蟾宫", "d": "借指月宫" }
    ],
    "examples": ["昔年曾向嫦娥妒，今日相逢恐未真"],
    "rc": 5
  }
]

响应字段说明

字段	说明
w	典形词
d	释义
src	典源词（典故名）
src_text	典源内容（截断 ≤300 字）
related[]	同源典形词列表（含 `w` 和 `d`）
examples[]	包含该典故的古诗例句
rc	同源典形词数量（related count）

排序策略：精确匹配优先 → 匹配位置靠前 → 短词优先（2-4 字适合入诗）→ 同源越多越经典。
单字搜索走倒排索引，多字搜索对各字的 ID 集合取交集后过滤子串匹配。

自由诗韵脚检测

对自由诗（古体诗/新诗/歌词等不限格律的诗体）进行轻量韵脚检测，提取韵脚候选字并按共同韵部前向分组。

POST /api/free_rhyme

参数	类型		说明
lines	string[]	必填	诗行数组，每行一个字符串
rhyme_book_name	string	可选	韵书名，默认 `Zhonghua_Tongyun`（中华通韵），可选 `Pingshuiyun`（平水韵）、`Cilinzhengyun`（词林正韵）
merge_tones	boolean	可选	是否合并平仄声调（同韵部的平声字和仄声字视为同韵）。默认 `false`

韵书选择建议：
• 古体诗、歌行体（如《卖炭翁》《长恨歌》）→ 指定 Pingshuiyun（平水韵）
• 新诗、歌词、现代自由诗 → 默认 Zhonghua_Tongyun（中华通韵），建议 merge_tones: true（现代诗词不讲究平仄分押）
• 词 → 指定 Cilinzhengyun（词林正韵）

示例 — 新诗（默认中华通韵）

curl -X POST https://write.sjtuguoxue.space/api/free_rhyme \
  -H "Content-Type: application/json" \
  -d '{"lines": ["春眠不觉晓，", "处处闻啼鸟。", "夜来风雨声，", "花落知多少。"]}'

{
  "candidates": [
    { "line": 0, "pos": 4, "char": "晓", "categories": ["二巧"] },
    { "line": 1, "pos": 4, "char": "鸟", "categories": ["二巧"] },
    { "line": 2, "pos": 4, "char": "声", "categories": ["十一庚"] },
    { "line": 3, "pos": 4, "char": "少", "categories": ["二巧"] }
  ],
  "groups": [
    { "positions": [
      { "line": 0, "pos": 4 },
      { "line": 1, "pos": 4 },
      { "line": 3, "pos": 4 }
    ] }
  ]
}

示例 — 古体诗（平水韵）

curl -X POST https://write.sjtuguoxue.space/api/free_rhyme \
  -H "Content-Type: application/json" \
  -d '{"lines": ["卖炭翁，伐薪烧炭南山中。", "满面尘灰烟火色，两鬓苍苍十指黑。"], "rhyme_book_name": "Pingshuiyun"}'

{
  "candidates": [
    { "char": "翁", "categories": ["一东"], ... },
    { "char": "中", "categories": ["一东", "一送"], ... },
    { "char": "色", "categories": ["十三职"], ... },
    { "char": "黑", "categories": ["十三职"], ... }
  ],
  "groups": [
    { "positions": [/* 翁, 中 */] },
    { "positions": [/* 色, 黑 */] }
  ]
}

使用 merge_tones: true 后，同韵部的平声和仄声字合并为一组（如中华通韵"九熬_平"与"九熬_仄"视为同韵）。新诗和歌词通常不讲究平仄分押，建议开启。

响应字段说明

字段	说明
candidates[]	所有韵脚候选字（标点前或行末的 CJK 字符），含所属韵部
groups[]	韵脚分组（≥2 个候选字共享韵部），用于同色着色
positions[].line	所在行号（0-based）
positions[].pos	行内字符位置（0-based）

分组算法：前向贪心 — 取首个未分组字的韵部为锚集，向后扫描共享韵部的字拉入组，锚集不扩展。仅返回 ≥2 成员的组。

调用统计摘要

返回指定日期的关键调用指标摘要。export_image（导出图片）为北极星指标，置于顶层。

GET /api/stats/summary

参数	类型		说明
date	string	可选	日期，格式 `YYYY-MM-DD`（UTC+8）。缺省返回当天

示例

curl https://write.sjtuguoxue.space/api/stats/summary?date=2026-06-03

{
  "date": "2026-06-03",
  "export_image": 12,
  "total_api_calls": 123,
  "total_events": 45,
  "api_calls": {
    "validate_meter": 50,
    "dictionary/search": 25,
    "char/definitions": 30
  },
  "events": {
    "export_image": 12,
    "create_board": 10,
    "copy_text": 8
  },
  "sources": {
    "frontend": 100,
    "api": 50,
    "android": 18
  }
}

响应字段说明

字段	说明
date	统计日期
export_image	北极星指标 — 导出图片次数
total_api_calls	当日 API 调用总量（不含前端事件）
total_events	当日前端事件总量
api_calls	各 API 路由调用量，按次数降序
events	各前端事件调用量，按次数降序
sources	按来源分布（frontend / api / android），按次数降序