Skip to content

README.md

Latest commit

 

History

History
312 lines (253 loc) · 12.6 KB

README.md

File metadata and controls

312 lines (253 loc) · 12.6 KB
Raw

Math Idea Graph · 数学思想知识图谱

一个纯静态、可追溯来源的数学知识图谱：概念（Concept）与定义（Definition）分开存储， 关系按类型独立记录，搜索与关系图在浏览器本地运行。没有 AI 生成、没有大模型 API、没有后端服务。

  • 首页搜索 → 概念页 / 定义页
  • 概念页包含：定义、前置概念（含多层递归）、思想动机、关系网络（局部图 + 类型化关系列表）、 历史脉络（时间线 + 文献）、延伸探索、思想主线
  • 全局关系图：拖动、缩放、按关系类型筛选、按名称定位、高亮一阶关系

界面

首页 概念页（同伦等价）
首页 概念页
搜索结果 全局关系图
搜索 关系图

技术栈

层 选择
站点 Astro 7（静态输出）
语言 TypeScript + HTML/CSS
公式 KaTeX（构建期渲染为静态 HTML）
知识库 Markdown + YAML frontmatter、JSON
搜索 MiniSearch（构建期生成索引，浏览器本地检索；中文单字 + 二元组分词）
关系图 Cytoscape.js
校验 自研校验脚本（npm run validate）
测试 Vitest（单元/集成）+ 可选的无头浏览器验收脚本
部署 GitHub Pages（支持仓库子路径）

快速开始

要求 Node.js ≥ 22.18（脚本直接用 Node 运行 TypeScript，依赖其原生类型擦除）。 推荐 pnpm；npm 亦可。

pnpm install        # 或 npm install
pnpm dev            # 开发服务器 http://localhost:4321
pnpm build          # 先校验数据，再产出 dist/
pnpm preview        # 预览构建结果

常用脚本：

命令 作用
npm run dev 本地开发
npm run validate 知识库校验（ID 唯一、断链、关系类型、必填字段、LaTeX、连通性等）
npm run validate:strict 同上，但把警告也视为失败
npm run test Vitest 单元测试
npm run typecheck tsc --noEmit
npm run build validate + 生产构建
npm run smoke 可选：启动无头 Chrome 跑 11 项端到端验收（需先 build）

在受限环境（如无图形会话的容器）中，smoke 需要能够启动浏览器进程。

目录结构

.
├── astro.config.mjs          # site / base（GitHub Pages 子路径）
├── data/                     # 知识库（与页面代码完全分离）
│   ├── domains.json          # 数学领域注册表
│   ├── sources.json          # 文献来源注册表
│   ├── concepts/*.md         # 概念（YAML frontmatter + 可选正文）
│   ├── definitions/*.md      # 定义（每条独立 ID）
│   ├── relations/*.json      # 类型化关系（按主题分文件）
│   └── history/*.md          # 历史事件（必须关联来源）
├── scripts/
│   ├── validate.ts           # 校验脚本
│   └── smoke-browser.mjs     # 可选的端到端验收脚本
├── src/
│   ├── components/           # 页面组件（定义卡、关系列表、时间线、关系图…）
│   ├── layouts/BaseLayout.astro
│   ├── lib/                  # 类型、Schema、数据装载、搜索、图数据、渲染、URL
│   ├── pages/                # 首页、搜索、概念、定义、领域、关系图、关于、404
│   └── styles/               # 设计令牌、布局、组件、数学排版
├── tests/                    # Vitest 测试
└── public/                   # favicon、.nojekyll

数据模型

所有实体共享同一个 ID 命名空间：只允许小写字母、数字与连字符（homotopy-equivalence）。 中文名称只用于显示，绝不作为关系标识。

概念 data/concepts/<id>.md

---
id: homotopy-equivalence
name_zh: 同伦等价
name_en: Homotopy Equivalence
aliases: [同伦等价关系, homotopy equivalent]
domain: homotopy-theory          # 必须在 data/domains.json 中登记
summary: >-
  一句话以上的简介，可含 $行内公式$。
motivation:
  problem: 原本存在的问题
  gap: 原有理论的不足
  innovation: 为什么需要引入新概念
  resolution: 新概念解决了什么
main_idea: 思想主线（单独展示）
featured: true
review_status: approved        # approved | pending
updated: 2026-11-04
sources: [hatcher-2002]
extensions:                    # 延伸探索（按 kind 分组展示）
  - kind: modern_development   # direct_generalization | application | conceptual_connection | modern_development
    concept_id: model-category
    note: 为什么值得从这里继续
    sources: [quillen-1967]
---

正文（可选），渲染为「补充笔记」，支持 Markdown 与 KaTeX。

定义 data/definitions/<id>.md

---
id: def-homotopy-equivalence-standard
name_zh: 同伦等价的标准定义
name_en: Standard Definition of Homotopy Equivalence
concept_id: homotopy-equivalence
order: 1                       # 同一概念下的展示顺序，越小越靠前
statement: |-                  # 严格数学表述（Markdown + $...$）
  设 $X, Y$ 为拓扑空间 …
latex: |-                      # 核心公式（展示模式），可为空
  g \circ f \simeq \mathrm{id}_X, \qquad f \circ g \simeq \mathrm{id}_Y
applies_to: [拓扑空间, 连续映射]
conditions:
  - $X$、$Y$ 为拓扑空间
explanation: >-
  定义解释。
prerequisites: [topological-space, continuous-map, homotopy]
related_definitions: [def-homotopy-inverse]
sources: [hatcher-2002]
review_status: approved
---

关系 data/relations/*.json

[
  {
    "id": "rel-homotopy-equivalence-requires-homotopy",
    "source": "homotopy-equivalence",
    "target": "homotopy",
    "type": "requires",
    "note": "为什么成立、在什么意义上成立（不能为空）",
    "conditions": "适用时填写",
    "sources": ["hatcher-2002"],
    "review_status": "approved"
  }
]

支持的 type（必须区分语义，禁止 related_to）：

type 含义
requires 严格数学前置：source 的定义逻辑上使用了 target
learning_prerequisite 学习顺序建议，不一定是逻辑依赖
generalizes source 是 target 的推广
special_case_of source 是 target 的特例
equivalent_to 在给定条件下两种表述等价（无向）
constructed_from source 由 target 的数据/结构构造
applies_to 把 source 的工具用于研究 target
invariant_under source 在 target 所代表的变换下不变
conceptual_connection 思想联系（无向，不是形式化依赖）
inspired_by 问题意识或方法来自 target
historical_influence 历史影响（史实关系，需来源支持）

历史事件 data/history/<id>.md

---
id: evt-whitehead-1949-combinatorial-homotopy
title: Whitehead 建立 CW 复形与同伦等价判据
year: 1949
precision: year            # year | decade | century | unknown
display_date: "1949"
people: ["J. H. C. Whitehead"]
concept_ids: [cw-complex, whitehead-theorem]
sources: [whitehead-1949]  # 必填，至少一条
review_status: approved
---

事件描述（正文）。

文献 data/sources.json

{
  "id": "whitehead-1949",
  "authors": ["J. H. C. Whitehead"],
  "title": "Combinatorial homotopy I",
  "year": 1949,
  "venue": "Bulletin of the American Mathematical Society 55, 213–245",
  "type": "paper",
  "url": "https://www.ams.org/…",
  "locator": "55, 213–245",
  "review_status": "approved"
}

添加内容

  1. 新概念：在 data/concepts/ 新建 <id>.md，填好 frontmatter。
  2. 新定义：在 data/definitions/ 新建文件，concept_id 指向已存在的概念。
  3. 新关系：在 data/relations/ 任意 JSON 数组里追加对象（source / target 必须存在）。
  4. 新历史事件：在 data/history/ 新建文件，并至少关联一条已登记来源。
  5. 新文献：先加到 data/sources.json，再在其它条目中引用其 id。
  6. 运行 npm run validate，通过后 npm run build。

页面、搜索索引、关系图都由数据自动生成；新增概念/定义/关系不需要修改页面代码。 新增一个数学领域时，只需在 data/domains.json 加一条记录。

校验规则

npm run validate 会检查：

  • 必填字段、类型、枚举（review_status、关系类型、延伸类型、日期精度、来源类型）
  • 全实体 ID 唯一；ID 形态合法（禁止中文 ID）
  • 关系两端存在、无自环、无重复关系、对称关系不重复声明
  • 定义所属概念、定义前置概念、相关定义存在
  • 概念延伸条目、历史事件概念、所有来源引用存在（断链检查）
  • 历史事件必须关联来源
  • LaTeX 可被 KaTeX 解析（行内与展示公式、latex 字段、条件字段）
  • 空字段（applies_to / conditions）、updated 日期格式
  • 未使用来源、名称/别名冲突（仅提示，不自动合并）、关系图弱连通性
  • review_status: approved 但没有任何来源的条目（警告）

搜索实现

  • 构建期由 src/pages/search-index.json.ts 生成 /search-index.json。
  • 中文按单字 + 二元组切分，英文/数字/希腊字母按整词切分（src/lib/search.ts）。
  • 先做 AND 检索（精度优先），无结果时退化为 OR，但要求至少命中一个长度 ≥ 2 的实词， 避免「zzzz-not-a-term」因单字母 a 召回大量无关条目。
  • 完全命中名称/别名时优先排序，避免「同伦」被「同伦类型」压过。
  • 结果区分 Concept 与 Definition；两者各自有独立页面。

关系图

  • src/lib/graph.ts：纯数据层（构建、邻域展开、类型筛选），有单元测试。
  • src/lib/graph-ui.ts：Cytoscape 封装（布局、着色、线型、高亮、筛选、双击打开）。
  • 概念页的局部图：以当前概念为中心，点击节点展开邻居，双击节点打开概念页， 面板中也有「打开概念页」按钮。
  • /graph/ 的全局图：拖动/缩放/筛选/搜索定位/高亮一阶关系，图例说明每种关系类型。
  • 边的颜色与线型按关系类型区分：实线（逻辑依赖）、虚线（学习顺序、历史影响）、点线（应用、思想联系）。

部署到 GitHub Pages

方式一：GitHub Actions（推荐）

仓库已包含 .github/workflows/deploy.yml。在仓库 Settings → Pages → Build and deployment 选择 GitHub Actions，然后推送到 main 即可。

工作流会：

  1. 安装依赖（pnpm，含 lockfile）
  2. 运行 validate 与单元测试
  3. 以 SITE_URL=https://<owner>.github.io、SITE_BASE=/<repo>/ 构建
  4. 上传 dist/ 并部署

方式二：手动构建

# 用户/组织站点（https://<user>.github.io/）
SITE_URL=https://<user>.github.io SITE_BASE=/ npm run build

# 项目站点（https://<user>.github.io/<repo>/）
SITE_URL=https://<user>.github.io SITE_BASE=/<repo>/ npm run build

# 然后把 dist/ 发布到 gh-pages 分支

Windows PowerShell：

$env:SITE_URL='https://<user>.github.io'; $env:SITE_BASE='/<repo>/'; npm run build

子路径注意事项：站内所有链接都经过 src/lib/urls.ts 的 withBase()， _astro/ 静态资源由 Astro 自动加 base 前缀；public/.nojekyll 防止 Jekyll 处理带下划线的目录。 自定义域名时把 SITE_BASE 设为 /。

数学内容政策

  • 只收录有教材或论文支持的定义与关系；历史事件必须给出文献。
  • 没有把握的卷期、页码、人物归属会标为「待审核」（review_status: pending）并写明待核内容。
  • 不为了填满页面而编造关系、年代或引文；宁可留空并显示「待补充」。
  • 术语约定不一致时（例如「形变收缩」是否要求子空间固定），在定义解释中明确写出本库采用的约定。

已知限制

  • 初始知识库聚焦代数拓扑与几何群论（23 个概念、26 条定义、62 条关系、25 条文献）。
  • 部分历史条目的卷期页码仍待核对（见对应来源条目的「待审核」说明）。
  • 搜索是字面匹配 + 中文二元组，不理解同义词；同义词需显式登记为 aliases。
  • 关系图使用力导向布局，节点很多时需要手动拖动或按类型筛选。
  • 知识库未做增量构建优化；数据量很大时可考虑拆分为多个入口。

许可

代码用于示例与教学。文献书目信息版权归原出版方；引用内容请遵循原出版方许可。