📦 数据文件

明信片百科是开源知识库，不提供远程数据接口：全部词条在构建时被解析成一份树形全量 JSON，作为仓库内的数据文件 data/baike.json 随源码一起提交。需要在自己应用中读取词条列表、词条内容时，直接获取这份文件即可，无需申请密钥、不会有任何调用限制。

获取方式

📂 文件位置：仓库根目录 data/baike.json，UTF-8 编码的 application/json
🔗 源码仓库：https://gitee.com/post-hi/com.post-hi.baike
💾 取得数据：git clone 仓库后读取该文件，或下载仓库归档 / Release 压缩包取出 data/baike.json，也可以把这一个文件单独复制进自己的项目
🚚 需要 HTTP 访问时：请自行把这 380 KB 左右的静态文件部署到自己的静态站点、对象存储或应用资源目录；文件内容与本站页面完全一致
🔄 更新时机：词条合并进主仓库后，在构建（npm run docs:build）或手动执行 npm run docs:data 时刷新；用 meta.generatedAt、meta.commit、meta.version 判断数据新鲜度
⚖️ 使用许可：项目基于 MIT 协议开源，引用数据请注明来源「明信片百科」，并保留对应词条的站内链接
⚠️ 时效提示：资费、平台规模、平台功能等时效性内容以官方公示为准，重要场景请在应用内提示用户二次核对

树形结构

数据自外向内依次深入：meta → categories → pages → entries → fields / details。

text

meta                         站点与版本信息
categories[]                 分类（百科词条 / 拓展知识）
└── pages[]                  页面（种类细分、圈内术语……）
    ├── blocks[]             页面级附加区块（如资费速查、礼仪总纲）
    └── entries[]            词条（一个页面包含多个词条）
        ├── fields           规范化字段（英文键，推荐取数入口）
        ├── details[]        原始字段明细（中文标签，逐条有序）
        ├── points[]         无标签要点列表
        └── subsections[]    词条内小节（如写片指南的登记规则）

一个真实词条的完整数据示例：

json

{
  "name": "许愿（Wish）",
  "title": "许愿",
  "titleAlias": "Wish",
  "aliases": ["空注册"],
  "intro": "盒片（盒装片）是市面最基础、量产化最高的常规明信片品类。",
  "notices": ["区分：实地寄出是邮寄行为；原地片是产出的卡片品类。"],
  "fields": {
    "definition": "玩家个人十分想要收集的题材、款式的明信片，一般会整理写在个人简介、换片帖当中。",
    "feature": "换片时对方如果寄出你的许愿片，属于高诚意交换。",
    "scenario": "换片沟通、求片、个人收藏清单标注。"
  },
  "details": [
    { "marker": "✅", "label": "定义", "text": "玩家个人十分想要收集的题材、款式的明信片……", "key": "definition" },
    { "marker": "📌", "label": "圈内特点", "text": "换片时对方如果寄出你的许愿片，属于高诚意交换。", "key": "feature" },
    { "marker": "🎯", "label": "适用场景", "text": "换片沟通、求片、个人收藏清单标注。", "key": "scenario" }
  ],
  "raw": "## 许愿（Wish）\n- ✅ **定义**：……"
}

数据类型说明

meta 站点信息

字段	类型	一定存在	含义
`title`	string	是	站点名称
`description`	string	是	站点简介
`version`	string	是	站点版本号，与仓库 `package.json` 一致
`generatedAt`	string	是	生成时间，格式 `YYYY-MM-DD HH:mm:ss`
`commit`	string	是	生成时所依据的最后一次提交短哈希（读不到 git 信息时为空字符串）
`repo`	string	是	源码仓库地址
`file`	string	是	本数据文件在仓库中的路径 `data/baike.json`
`license`	string	是	数据许可协议
`pageCount`	number	是	导出的页面数量
`entryCount`	number	是	导出的词条总数，可用于本地校验数据是否解析完整

categories / pages 页面节点

字段	类型	一定存在	含义
`name`	string	是	分类名称，与侧边栏分组一致：`百科词条`、`拓展知识`
`slug`	string	是	页面标识（文件名），如 `term`
`title`	string	是	页面标题，如 `圈内术语`
`icon`	string	否	页面 emoji 图标
`path`	string	是	站内页面路径，如 `/term`，可拼本站域名生成词条出处链接
`intro`	string	否	页面简介（多个段落以空行分隔）
`notices`	string[]	否	页面级提示（源文顶部引用块）
`blocks`	object[]	否	页面级附加区块，元素为 `{ title, icon?, items: string[] }`
`entries`	object[]	是	该页面的词条数组

entries 词条节点

字段	类型	一定存在	含义
`name`	string	是	词条标题原文，如 `许愿（Wish）`
`title`	string	是	去掉尾部括号后的主名称，如 `许愿`
`titleAlias`	string	否	标题括号内的别名/英文，如 `Wish`
`aliases`	string[]	否	词条内标注的圈内别名
`intro`	string	否	词条标题之后的概述段落
`notices`	string[]	否	词条内的区分、补充说明（源文引用块）
`fields`	object	是	规范化字段，键为英文；可能为空对象
`details`	object[]	是	全部带标签明细，保留中文标签与原文顺序；可能为空数组
`points`	string[]	否	无标签的要点列表（如书写布局说明、视频教程链接）
`subsections`	object[]	否	词条内小节，元素为 `{ title, fields, details, points? }`
`raw`	string	是	该词条的原文 Markdown，任何情况下都不丢信息

details 明细项

字段	类型	含义
`marker`	string	行首 emoji 符号（如 `✅`、`📌`），源文没有时为空字符串
`label`	string	中文标签原文（如 `定义`、`品类特点`），与本站页面显示一致
`text`	string \| string[]	内容文本；源文该条带缩进子列表（如平台「大事记」）时为字符串数组
`key`	string \| null	该标签对应的 `fields` 英文键；未收录的标签为 `null`

字段映射表

fields 的键固定为英文，由站内中文标签映射而来。同一条词条内同一英文键出现多次时，fields 值为字符串数组（details 始终逐条保留）。

`fields` 键	对应中文标签
`definition`	定义
`feature`	圈内特点、品类特点、核心特点、邮路特点、玩法机制、玩法规则、制作形式、收藏玩法、演变体系、机制、要点、区分要点、三要素分工、志号细分、核心价值、核心要求、换片约定、特点、圈内规则
`pros` / `cons`	优点 / 缺点
`caution`	圈内注意、邮寄注意、使用注意、禁止行为、圈内提示、提示
`etiquette`	圈内礼仪、礼仪、避免空登、避免纯模板敷衍、真诚大于字数
`positioning`	圈内定位、圈内地位、圈内用途
`scenario`	适用场景
`distinction`	区分提示
`abbr` / `carrier` / `language` / `summary` / `gameplay`	简称 / 载体 / 语言 / 简介 / 玩法
`postcardCode` / `timeline` / `website` / `reference`	明信片编码 / 大事记 / 官网 / 参考来源
`stampRule` / `channel` / `deadline`	邮票约定 / 交寄渠道 / 平台时限

取值规则与兼容性

✅ 优先读 fields：英文键、集合固定、语义稳定，适合直接建模到代码里。
📌 兜底读 details：fields 里没有想要的内容时遍历 details，用中文 label 匹配；key 为 null 的项表示该标签未纳入映射表。
⚠️ 类型判断：fields 与 details[].text 的值都可能是 string 或 string[]，取值时先判断是否为数组。
🧩 缺失即无：字段不存在表示该词条没有这一项，不是数据异常；请对所有非 raw/title 字段做可缺处理。
🧾 行内 Markdown：文本中保留 [文字](/path)、**加粗**、`代码` 等行内语法，渲染前可自行解析或用正则剥离。
🚚 向前兼容：百科后续可能新增词条、页面与 fields 键，请务必忽略未知键、不要按键数量做断言；raw 是永不失效的兜底数据。

用法示例

Node.js 直接读取仓库内的数据文件：

import { readFile } from 'node:fs/promises'

const data = JSON.parse(await readFile('./data/baike.json', 'utf8'))

// 扁平化成「名称 → 词条」索引，同时收录标题、括号别名与圈内别名
const index = new Map()
for (const page of data.categories.flatMap((c) => c.pages)) {
  for (const entry of page.entries) {
    entry.page = { title: page.title, path: page.path }
    for (const key of [entry.title, entry.titleAlias, ...(entry.aliases || [])]) {
      if (key) index.set(key, entry)
    }
  }
}

const entry = index.get('跑片')
const toArray = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v])
console.log(entry.fields.definition)          // 定义
console.log(toArray(entry.fields.scenario))   // 适用场景（可能为数组）
console.log(entry.raw)                        // 原文 Markdown

各平台词条速查（按页面 slug 取整页数据）：

const platforms = data.categories
  .flatMap((c) => c.pages)
  .find((p) => p.slug === 'platform')
for (const e of platforms.entries) {
  console.log(e.title, e.fields.abbr, e.fields.website)
}

命令行取全部词条名（jq 读本地文件）：

bash

jq -r '.categories[].pages[].entries[].title' data/baike.json

浏览器等前端环境：把 data/baike.json 作为自己项目的静态资源或打包内置，再 fetch('/你的路径/baike.json') 或直接 import 使用。

常见问题

❓ 为什么不做远程 API？ 本项目是开源公益知识库，不承担为第三方应用提供在线接口的运维成本；数据文件随仓库分发，一次拿到全量、可离线、可用 git 追溯版本，比远程接口更稳定。
❓ 为什么是一个全量文件？ 百科体量不大（当前 9 个页面、175 个词条，文件约 380 KB），一次读取即可在本地建立完整索引，比逐条请求更快也更省资源。
❓ 数据多久更新？ 跟随站点发布节奏；data/baike.json 只在词条内容真正发生变化时才会重写，反复构建不会产生无意义的版本差异。
❓ 格式会变吗？ 结构变动会先在本页更新数据类型说明；建议记录 meta.version 与 meta.generatedAt，遇到未知结构一律回退到 raw 解析。
❓ 本地怎么重新生成？ 在仓库根执行 npm run docs:data（由 scripts/gen-data.mjs 解析 docs/ 页面，docs:build 会自动先执行一次），产物 data/baike.json 属仓库文件、需要与词条改动一起提交。

📦 数据文件 ​

获取方式 ​

树形结构 ​

数据类型说明 ​

meta 站点信息 ​

categories / pages 页面节点 ​

entries 词条节点 ​

details 明细项 ​

字段映射表 ​

取值规则与兼容性 ​

用法示例 ​

常见问题 ​