玄枢.玄空 API
基于 470 部先秦至民国原典（39,018,114 汉字）构建 ·
113 个端点 · 交互式文档 · OpenAPI
470部典籍
39,018,114汉字
236,119检索单元
86理论概念
13矛盾裁决
123原书实证
图像正确性说明
本库不使用扩散模型生成任何卦象、纳甲、飞星盘、罗盘。
扩散模型无法可靠渲染中文字形与阴阳爻画，画错会使图像成为错误知识源。
一切知识图由 kb/svg_glyph.py 程序化绘制，数据直接取自经《卜筮正宗》
《增删卜易》等原书逐条校验的符号表，正确性由构造保证，并由 _v/v8_svg.py 反向解析回结构化数据逐项比对（57 项）。
RealVisXL 仅用于封面与章节配图等装饰性画面，不承载任何卦象信息。
快速开始
./start.sh # 建库（缺失时）+ 自检 + 启动 http://127.0.0.1:8848
端点一览（113 个）
### 系统
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/health` | 健康检查 |
| `GET` | `/api/v1/meta` | 知识库总览与覆盖边界 |
| `GET` | `/api/v1/guide` | 中文上手手册（HTML） |
### 典籍
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/books` | 典籍列表（可筛选/分页） |
| `GET` | `/api/v1/books/{book_id}` | 典籍详情（含审计信息） |
| `GET` | `/api/v1/books/by-path/{path}` | 按相对路径取典籍 |
| `GET` | `/api/v1/books/{book_id}/text` | 典籍全文（分页） |
| `GET` | `/api/v1/books/{book_id}/chapters` | 典籍章节/检索单元目录 |
### 检索
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/search` | 混合检索（关键词 + 语义） |
| `GET` | `/api/v1/search/similar` | 相似段落（以库中某段为查询） |
| `GET` | `/api/v1/search/context` | 命中段落的上下文（前后若干单元） |
| `GET` | `/api/v1/search/exact` | 中文精确全文检索（SQLite FTS5 二元组索引） |
### 符号层
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/ganzhi` | 天干/地支全表 |
| `GET` | `/api/v1/ganzhi/{symbol}` | 单个天干/地支 |
| `GET` | `/api/v1/wuxing` | 五行属性与生克 |
| `POST` | `/api/v1/wuxing/relations` | 两五行（或两干支）的生克关系 |
| `GET` | `/api/v1/shishen` | 十神全矩阵（10 日主 × 10 目标） |
| `GET` | `/api/v1/shishen/of/{day}/{target}` | 求某目标干相对日主的十神 |
| `GET` | `/api/v1/canggan` | 地支藏干 |
| `GET` | `/api/v1/canggan/{zhi}` | 按地支取藏干 |
| `GET` | `/api/v1/nayin` | 六十甲子纳音 |
| `GET` | `/api/v1/nayin/{gan_zhi}` | 按干支取纳音（繁简皆可） |
| `GET` | `/api/v1/changsheng` | 十二长生 |
| `GET` | `/api/v1/changsheng/of/{gan}/{zhi}` | 某干在某支的长生状态 |
| `GET` | `/api/v1/zhi-relations` | 地支关系（六合/六冲/三合/三会/六害） |
| `GET` | `/api/v1/hexagrams` | 六十四卦列表 |
| `GET` | `/api/v1/hexagrams/{num}` | 按卦序取卦（1–64） |
| `GET` | `/api/v1/hexagrams/by-name/{name}` | 按卦名取卦（繁简皆可） |
| `GET` | `/api/v1/ershi-shan` | 二十四山（角度/五行/三元） |
| `GET` | `/api/v1/najia` | 八卦纳甲（六爻装卦）——已迁至 /api/v1/liuyao/najia |
| `GET` | `/api/v1/jiuxing` | 九星（紫白飞星） |
| `GET` | `/api/v1/shensha` | 神煞表 |
| `GET` | `/api/v1/shensha/{name}` | 按名取神煞 |
### 六爻
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/liuyao` | 六爻总览（纳甲/六亲/六神/世应） |
| `GET` | `/api/v1/liuyao/najia` | 八卦纳甲（装卦六爻地支） |
| `GET` | `/api/v1/liuyao/liuqin` | 六亲（生克映射） |
| `GET` | `/api/v1/liuyao/liushen` | 六神（六兽），可按日干取序列 |
| `GET` | `/api/v1/liuyao/shiying` | 世应安法 + 京房八宫六十四卦序 |
| `GET` | `/api/v1/liuyao/terms` | 六爻术语表（用神/旬空/月破/飞伏/进退…） |
| `POST` | `/api/v1/liuyao/cast` | 六爻装卦（纳甲+六亲+六神+世应+旬空月破旺衰） |
| `GET` | `/api/v1/liuyao/yongshen` | 用神取用（占何事取何六亲） |
| `GET` | `/api/v1/liuyao/xunkong` | 旬空查询（六十甲子旬空） |
| `GET` | `/api/v1/liuyao/yuepo` | 月破查询（定月建所冲之支） |
| `GET` | `/api/v1/liuyao/wangxiang` | 五爻在某月建的旺相休囚死 |
### 计算器
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/calc/ganzhi` | 公历日期→干支历（日/月/年柱+旬空+辟卦月） |
| `POST` | `/api/v1/calc/bazi` | 四柱排盘（节气精确，以 lunar-python 天文算法） |
| `POST` | `/api/v1/calc/meihua` | 梅花易数起卦（单数法） |
| `POST` | `/api/v1/calc/feixing` | 玄空飞星排盘（向盘/山盘） |
### 工具
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/convert/s2t` | 简体→繁体 |
| `GET` | `/api/v1/convert/t2s` | 繁体→简体 |
### 理论
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/concepts` | 理论概念列表（6 层） |
| `GET` | `/api/v1/concepts/graph` | 概念关系图（节点+边） |
| `GET` | `/api/v1/concepts/{cid}` | 概念详情（含相关概念与矛盾） |
| `GET` | `/api/v1/contradictions` | 矛盾登记与裁决 |
| `GET` | `/api/v1/contradictions/{cid}` | 单条矛盾裁决详情 |
| `GET` | `/api/v1/evidence` | 原书实证引文（123 条，逐条可回查原书） |
| `GET` | `/api/v1/theory` | 理论体系全文（Markdown） |
| `GET` | `/api/v1/audit` | 典籍审计报告（Markdown） |
| `GET` | `/api/v1/verification` | 六爻典籍核实报告（Markdown） |
| `GET` | `/api/v1/audit/json` | 典籍审计结果（JSON） |
### 图形
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/glyph` | 图形类型清单 |
| `GET` | `/api/v1/glyph/{kind}` | 取图形（SVG） |
| `GET` | `/api/v1/glyph/{kind}/data` | 取图形对应的结构化数据（JSON） |
### 知识图谱
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/graph` | 知识图谱全图（分层节点 + 关系边） |
| `GET` | `/api/v1/graph/layer/{layer}` | 按层取概念 |
| `GET` | `/api/v1/graph/path` | 概念关系路径（相关概念逐跳展开） |
### 裁决与排盘
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/decide/chain` | 择一链（主据 + 退路顺序） |
| `GET` | `/api/v1/decide/{topic}` | 某主题的择一链 |
| `POST` | `/api/v1/judge/bazi` | 八字裁决：格局 / 用神 / 吉凶（滴天髓主） |
| `POST` | `/api/v1/judge/liuyao` | 六爻裁决：应期 / 吉凶（卜筮正宗主） |
| `GET` | `/api/v1/judge/liqi` | 玄空理气：三盘 + 旺山旺向（沈氏为主） |
| `GET` | `/api/v1/judge/liqi/full` | 玄空理气全格局：十四类格局逐项判定（沈氏《玄空学》全） |
| `GET` | `/api/v1/liqi/ju216` | 原书 216 局挨星图直查（《沈氏玄空学》卷四总断+逐运） |
| `GET` | `/api/v1/liqi/tables` | 玄空格局常数表（地盘/替卦/合十/四十八局/地运年数…） |
| `POST` | `/api/v1/pan/ziwei` | 紫微斗数排盘（十二宫 / 主星 / 四化 / 三方四正） |
| `GET` | `/api/v1/ziwei/miao` | 紫微庙旺落陷定表（《紫微諸星廟陷訣》） |
| `GET` | `/api/v1/ziwei/miao/{star}` | 判某星在某宫的庙陷 |
| `GET` | `/api/v1/pan/qizheng` | 七政四余排盘（七政黄经 + 二十八宿 + 十二宫） |
| `GET` | `/api/v1/pan/qizheng/xiu` | 二十八宿分野表 |
| `GET` | `/api/v1/liqi/jian` | 兼向起星图：216 局替卦/出卦判据（沈氏卷五原文） |
| `GET` | `/api/v1/liqi/duan` | 章仲山《宅断》案例检索（原书 40 例，含仲山断语与沈注） |
| `GET` | `/api/v1/liqi/ju` | 卷六诸诀常数表（紫白吉星/月三煞/禽星穿宫/八门加临…） |
| `GET` | `/api/v1/liqi/zibai/yue` | 逐年月紫白吉星表（原书图版，依推算法实算） |
| `GET` | `/api/v1/liqi/zibai/qixing` | 起星立成图：24 山 → 替卦星（以星代卦） |
| `GET` | `/api/v1/liqi/zibai/shijia` | 时家白星起例（冬至三时顺、夏至三时逆） |
| `GET` | `/api/v1/liqi/zibai/ri` | 逐日紫白顺逆局起例（上中下元 × 顺逆） |
| `GET` | `/api/v1/liqi/dajie` | 七星打劫二十四局全表（依《沈氏玄空学》判据实算并经局数反验） |
### 版权
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/copyright/boundary` | 版权边界书清单（可一键剔除） |
### 推演
| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/v1/divine` | 断吉凶（统一入口：八字 / 六爻 / 两盘合参） |
| `GET` | `/api/v1/divine/matters` | 支持断吉凶的事项与用神对照 |
| `POST` | `/api/v1/pan/ziwei/full` | 紫微斗数完整排盘（14 主星 + 16 辅星 + 宫干 + 大限） |
| `GET` | `/api/v1/pan/ziwei/stars` | 紫微安星表（主星/辅星安法与出处） |
| `POST` | `/api/v1/pan/qizheng/full` | 七政四余完整排盘（躔度 / 命身宫 / 十二宫星曜分布） |
| `GET` | `/api/v1/pan/qizheng/chandu` | 星命躔度计算（任意时刻的七政四余躔度） |
| `GET` | `/api/v1/pan/qizheng/gong` | 十二宫（黄道十二等分）起讫度数 |
| `GET` | `/api/v1/ephemeris/precision` | 星历精度自证：与 IMCCE 官方 vsop87.chk 逐项比对 |
### 教材系统
| 方法 | 路径 | 说明 |
|---|---|---|
| `GET` | `/api/v1/academy/status` | 教材路由自检 |
| `GET` | `/api/v1/academy/curriculum` | 全量课程总纲 |
| `GET` | `/api/v1/academy/lessons` | 课时清单 |
| `GET` | `/api/v1/academy/evidence` | 原书实证命题检索 |
| `POST` | `/api/v1/academy/symbols/match` | 两干（或两行）的关系：十神与生克 |
| `GET` | `/api/v1/academy/matters` | 六爻取用事项表 |
| `POST` | `/api/v1/academy/tutor/ask` | AI 导师问答（先检索后作答） |
### 周易测股
| 方法 | 路径 | 说明 |
|---|---|---|
| `POST` | `/api/v1/stock/liuyao` | 六爻占个股（象义倾向 + 变盘观察窗口） |
| `POST` | `/api/v1/stock/meihua` | 梅花易数测大盘（体用生克 + 主互变三段） |
| `GET` | `/api/v1/stock/sectors` | 五行板块轮动榜（月建旺衰 → 行业强弱象义） |
| `GET` | `/api/v1/stock/cycle` | 辟卦干支周期钟（年月级阴阳消长背景） |
| `GET` | `/api/v1/stock/quote` | 行情快照（三源容灾，仅位置参照） |
| `GET` | `/api/v1/stock/mappings` | 行业五行八卦映射表（全量公开） |
| `POST` | `/api/v1/stock/interpret` | 解卦（典籍解卦 + 综合解读可选） |
| `POST` | `/api/v1/stock/interpret/meihua` | 解卦·梅花测大盘（典籍 + 综合解读可选） |
| `POST` | `/api/v1/stock/interpret/sectors` | 解卦·五行板块榜（典籍 + 综合解读可选） |
| `POST` | `/api/v1/stock/interpret/cycle` | 解卦·辟卦周期钟（典籍 + 综合解读可选） |
边界
- 排盘与装卦接口只做符号层推演，不输出吉凶断语——取用神有扶抑/调候/病药/格神四说，
吉凶需「格局→用神→大运→神煞」加权链而各家权重不同，自动化断必然失真。
- 本库只覆盖这 470 部书的范围，不得据此断言库外流派之是非。
- 繁简与版本差异：统一经域内安全归一，检索时繁简皆可命中。
本文件由 _v/gen_docs.py 从数据库与
api/server.py 自动生成，改数据后重跑即可，数字不会过时。