目录与补录规范
基础理论 · 总览导读
目录与补录规范
本文是全库结构约定的唯一权威。新增、迁移、重编号资料一律依此执行;与其它文档冲突时以本文为准。定稿 2026-08-27(目录结构 2.0 收尾)。
一、结构骨架
文献资料/
├── 01-基础理论/ 全库公共地基(阴阳五行、干支历法、易学象数、河洛九宫)
├── 02-丹道修炼/
├── 03-传统中医/
├── 04-术数推演/ 下设二级科目(命理/占筮/三式/相术/堪舆/择吉)
└── 05-术法仪轨/
每个科目(必要时每个二级科目)下用同一套六栏:
| 栏 | 收什么 | 边界 |
|---|---|---|
01-典籍原文/ | 公版古籍全文、底本 | 不放白话解释、专题文章或学习笔记 |
02-典籍AI注解/ | 白话译、导读、分章注解、逐章精读 | 一书一目录 |
03-总览导读/ | 范围说明、术语、学习路线、书目、安全提示 | 元信息,不含具体知识 |
04-学理源流/ | 原理、历史源流、流派与人物 | 讲"为什么" |
05-方法整理/ | 传统方法、操作次第、风险边界 | 讲"怎么做";资料性整理,不代表本库认可其有效性 |
06-专题分享/ | 比较研究、现代研究、案例、个人经验 | 一切主观内容归此栏 |
栏目按功能角色划分,不按主题划分——这是六栏制的要点:任何新资料都能唯一定位,不必为新主题新建顶层目录。
2026-09-10 六栏改号与更名:为让网站目录把原典和注解排在最前,六栏编号改为 01-典籍原文 / 02-典籍AI注解 / 03-总览导读 / 04-学理源流 / 05-方法整理 / 06-专题分享;"典籍注解"全库更名"典籍AI注解",标明该栏白话、导读与精读为 AI 辅助生成,与原典区分。网站目录的顺序与名称直接取自目录名的 NN- 前缀和名称(后端 ensureCatalogPath 解析前缀作排序),调整顺序只改目录名,不改代码;文章 xzyx_id 未变。改号用 move_and_fix_links.py 移动目录,再用 tools/renumber_columns_20260910.py 通改正文与链接文本。
不作正统与旁支之判。 同一科目下的各体系一律平级编号,不以其中某门为中心把其他体系降格为"旁支""支流""其他"。
资料量不等于地位:七政四余存续少于八字,但其源流早于子平法,故与 01-八字命理/、02-紫微斗数/ 同级作 03-七政四余/。
尚无正文的体系不建目录(见第三节),其定位与收录优先级写在该科目根的 00-*总览.md 里,资料到位后按同级建目录、编号顺延。
二级科目根可放 00- 总览文章。 当一个科目下已成卷的门与尚未成卷的门并存时,用 00-命法总览.md 这类入口文章承载全科目的定位说明与收录优先级——00- 前缀不参与门类编号,不与 01-、02- 冲突。
二、命名约定
- 文件、目录一律
NN-名称前缀,两位数字,同级连续; - 典籍全文:
NN-书名_作者_版本.md(如01-葬书_托名郭璞_殆知阁文本.md); - 典籍原文子目录(2026-09-10 起):同一
01-典籍原文/超过约 40 部即可按传统书目类别分子目录,超过 99 部必须分(两位编号)。子目录同样NN-名称、各带 README,按书的类别切(医经/伤寒金匮/本草…,祖典/参同悟真/钟吕全真…),不按来源或朝代切;术数各二级科目自带的典籍原文暂不分。基础理论、丹道、中医、仪轨四栏已分,迁移用move_and_fix_links.py,xzyx_id 不变; - 精读目录:一书一目录,索引文件命名
00-总目与凡例.md或00-精读指南.md; - 通读版长文:
00-通读-原卷名.md,置于所属栏目之首; - 同角色同名:门内学理的统一容器叫
01-学理;门内骨架笔记叫基础理论(与科目级"01-基础理论"同名但不同层,前者是该门骨架,后者是全库公共地基);主题细分用主题名(01-干支详解、02-十神详解、02-主星详解)。
三、空栏与空目录
不预建空栏目,也不放 .gitkeep。 某栏暂无内容时,只在父级 README 里写明"待收",不建立目录——空目录 git 不跟踪,克隆后会消失,建了等于没建。
四、补录五步
① 定科目:看文章主旨,不看它提到了什么。(文中提到符箓不等于归入术法仪轨;提到经络不等于归入中医。)
② 定栏目:按上表六选一。判不准时问一句"这是客观整理还是我的看法"——后者一律 06-专题分享/。
③ 命名:依第二节。编号只管排序,改编号不影响网站文章身份(见第六节)。
④ 建索引:新建目录必须同时给 README.md(或 00-总目),并在父级 README 的表里加一行。README 体例:
# 栏目名
一句话定位(+ 该栏的操守/边界声明)
## 子目录 或 ## 篇目
| … | 链接 | 一句话钩子 |
## 阅读次序(可选)
## 整理要点(分歧点、口径、红线)
漏掉这一步是历史上所有导航空洞的来源。
典籍原文栏(含子目录)的篇目表不必手写:python tools/update_dianji_readmes.py --write 会给 README 未链接到的工作本补一节表格,并维护父栏的"子目录"表。
⑤ 收尾三件套:
python tools/write_xzyx_ids.py --write 文献资料 # 给新文件盖 ID
python tools/check_md_links.py 文献资料 # 断链必须为 0
双击 xzyx/打包资料库.cmd # 需要上站时才跑
五、迁移与重命名
不要手工改路径字符串。 移动目录会同时改变两类相对链接:被移动目录内部文件的 ../ 层数,以及外部文件指向它的前缀。用工具:
python tools/move_and_fix_links.py 文献资料 --move 旧路径 新路径 --write
它把每条链接解析为库内绝对路径、套用映射后重算相对路径,并顺带清理空掉的父目录。先不加 --write 跑 dry-run 看清影响面,执行后必须跑断链检查。
六、两条硬约束
xzyx_id是文章在网站上的身份证,永远不要手删 frontmatter 里那一行。 既有资料已显式写入；新增文章及新增栏目 README 也须一并写入新身份，库根 README 不导入。原值写入之后，改目录、改文件名、重编号不得重算该值；若删掉该行，导入器会退回按路径算 ID，文章身份随之断裂、产生重复。2026-09-06内容补充均在新建文件时写入显式ID，未重算旧文身份。- 新增一级目录必须同步修改
xzyx/xzyx-content/.../XzImportServiceImpl.java的ROOTS白名单(以及tools/write_xzyx_ids.py里同名映射),否则该目录在网站上完全不存在,且不会有任何报错。
八、典籍收书流程与登记规则(2026-09-10 起)
殆知阁镜像(garychowcmu/daizhigev20,固定提交 4a6d6f20)是本库典籍原文的固定来源,收书走脚本,不手工复制:
tools/daizhige_plans/<日期>-<批次>.tsv # 选书清单:来源路径、目标目录、书名、责任者
python tools/fetch_daizhige.py 清单.tsv --validate # 核书名、目录、重名
python tools/fetch_daizhige.py 清单.tsv --download # 下载到 tmp/daizhige_staging,按 git blob 校验
python tools/fetch_daizhige.py 清单.tsv --place # 生成 NN-书名_作者_版本.md,自带来源卡
python tools/update_dianji_readmes.py --write # 补 README 篇目表与子目录表
python tools/write_xzyx_ids.py --write 文献资料 && python tools/check_md_links.py 文献资料
不再逐书登记(馆主 2026-09-10 定):新收典籍不再写入 05-书目总览 与 07-收录登记,两文档停止更新、只作 2026-09-07 前的历史记录。当前书目以各 01-典籍原文/ README 表为准,来源路径、固定 blob、取得日期记录在每份工作本首部的"来源与范围"表和 tools/daizhige_plans/ 清单里。只收与科目主旨相关的书,不整库照搬;千里命稿等仍在版权期的近人著作不收全文。
七、已知待办
05-术法仪轨/前两批已有8篇学习文章与2份仪书，第三批另增20份仪书、戒律与章奏工作本；图像、白话、更多传承文书仍需补充，不以文件数称全库完备；- 已在既有根目录内新建皇极象数、体相与声相两个有实际正文的专题；新增子专题遵守六栏职责与同级编号，不新增第六个发布根目录;
- 2026-09-10 第四批从殆知阁新收 630 份工作本(基础 40、术数 68、丹道 203、中医 170、仪轨 138 上下),典籍原文由 221 份增至 851 份;网站导入限制已同步放宽(整包 600 MB、单文件 16 MB、6000 篇,JVM 堆 2 GB);
04-术数推演/占全库半数以上篇目,若继续膨胀,可考虑将六个二级科目升为一级科目(须同步改ROOTS白名单);- 2026-09-07在占筮门内新增焦氏易林、灵棋、测字、龟卜四个有正文的平级门类，仍采用原文与注解分栏，不新建空栏目；
- 其余内容待办见08-完善路线图。