# dao-zang — 道藏知识库离线检索与原文提取

本 skill 在"道藏工作区"(含 `ChromaDB/` 与 `Markdowns/`)中检索经文段落,
并从原始 Markdown 精确提取原文。**完全离线**:不调用任何嵌入 API、不需要网络。

## 环境要求

| 依赖 | 说明 |
|---|---|
| Python ≥ 3.10 | 已装 3.13 即可 |
| `chromadb` (1.5.x) | 打开 ChromaDB 数据库 |
| (可选) `onnxruntime` + `tokenizers` | 语义引擎(本地 bge-m3);已装 1.28.0 / 0.23.1 |
| (仅数据准备) `huggingface_hub` + `pyarrow` | 从数据集下载并重建向量库 |
| 道藏工作区 | 含 `ChromaDB/`(库)与 `Markdowns/`(3,152 个原文文件) |

## 两种检索引擎

| 引擎 | 命令 | 特点 |
|---|---|---|
| **text**(默认,零依赖) | `--engine text` 或省略 | ChromaDB 内置全文过滤 + 词频/IDF 排序;首次查询数秒暖机,之后约 1 秒 |
| **semantic**(可选) | `--engine semantic` | 本地 bge-m3 ONNX 模型嵌入查询,与库中向量同模型同维度(1024, cosine),质量与在线版一致 |
| auto(默认值) | `--engine auto` | 模型可用则 semantic,否则 text |

安装本地模型(默认官方 BAAI/bge-m3 onnx 导出,约 2.2GB;断点续传):

```powershell
python scripts\setup_local_model.py --dir <工作区>\models\bge-m3
# 国内镜像: --base-url https://hf-mirror.com (或设环境变量 HF_ENDPOINT)
# 小体积 int8 量化版 (~543MB, 更快): 加 --quantized
# 也可用环境变量 DAOZANG_EMBED_MODEL 指向已有模型目录
```

模型来源:官方仓库 https://huggingface.co/BAAI/bge-m3/ 的 `onnx/` 导出
(model.onnx + model.onnx_data + tokenizer.json, FP32);`--quantized` 改用
Xenova/bge-m3 的 int8 量化版。

## 数据准备 (数据集 Godners/DaoZang)

道藏工作区需要两部分数据:

1) 原文 Markdowns/ 3,152 篇;
2) 向量数据 data/*.parquet (6 分片, 共 ~1.3GB, 285,117 块含 bge-m3 向量)。

一键准备(下载 + 重建,断点续传):

```powershell
python scripts\setup_workspace.py --dir <工作区>
# 数据已就绪只重建库: --skip-download
# 已有库只补数据: --skip-build
# 国内镜像: --endpoint https://hf-mirror.com
# 复用本地缓存 (SHA-256 校验): --cache <目录>
```

或者手工分步:

```powershell
# 1) 原文
python -c "from huggingface_hub import snapshot_download; snapshot_download('Godners/DaoZang', repo_type='dataset', allow_patterns=['markdowns/*'], local_dir='.')"
# 2) 向量数据 data/*.parquet (6 分片, 共 ~1.3GB)
python -c "from huggingface_hub import snapshot_download; snapshot_download('Godners/DaoZang', repo_type='dataset', allow_patterns=['data/*.parquet'], local_dir='.')"
# 3) 离线重建向量库 (无需重新下载)
python scripts\setup_workspace.py --dir . --skip-download
```

`setup_workspace.py` 重建的库与数据集逐块对应(id = md5(source)[:16] + chunk_index),
与官方向量库一致;重建完全离线,不调用嵌入 API。

安装包形态（v2.0 三版本）见各版本 README：v1 全量直接复制 / v2 程序+markdown 在包内、
RAG 库从 HF 下载 / v3 从 GitHub 克隆程序+markdown 并从 HF 下载 RAG 库。

## 快速上手

**方式 A：一键启动器（推荐）** — `scripts\daozang.cmd` 自动定位 Python 与工作区:

```powershell
scripts\daozang.cmd check --selftest          # 便携自检（含真实冒烟查询）
scripts\daozang.cmd query "周天火候" 5
scripts\daozang.cmd query "天地悉皆归" 3 --source 清静妙经
scripts\daozang.cmd query "内丹修炼 周天火候" 3 --original
scripts\daozang.cmd extract 清静经 --list
scripts\daozang.cmd extract 太上老君说常清静妙经 0 --context 300
```

Python 查找顺序:环境变量 `DAOZANG_PYTHON` > `py -3` > `python`。

**方式 B：直接调用 Python 脚本**（等价;`--workspace` 可省略）:

```powershell
python scripts\query_daozang.py "周天火候" 5
python scripts\query_daozang.py "天地悉皆归" 3 --source 清静妙经
python scripts\query_daozang.py "内丹修炼 周天火候" 3 --original
python scripts\query_daozang.py "什么是内丹修炼中的周天火候？" 3 --engine semantic
python scripts\extract_original.py 清静经 --list
python scripts\extract_original.py 太上老君说常清静妙经 0 --context 300
```

工作区自动定位顺序:`--workspace` 参数 > 环境变量 `DAOZANG_WORKSPACE` > 从当前
目录向上找 > 从 `scripts/` 所在目录向上找——**任意目录下直接运行即可**,无需先
cd 到工作区。自动查找要求候选目录同时含 `ChromaDB/` 与 `Markdowns/`(≥1 个 .md),
避免把残留空库误判为工作区;显式 `--workspace` 只校验 `ChromaDB/`。脚本会先
chdir 到工作区(规避 chroma 1.5.9 在 Windows 下绝对路径的 bug)。

## 便携自检

新环境、换机器或报错时,先跑自检(静态检查零第三方依赖):

```powershell
python scripts\check_env.py             # Python/依赖/工作区/模型 逐项检查
python scripts\check_env.py --selftest  # 另做一次真实检索冒烟测试 (需 chromadb)
python scripts\check_env.py --json      # 机器可读输出 (exit: 0 就绪 / 1 警告 / 2 不可用)
```

## 输出解读

```
[相关度 1.2291] 正统道藏-None-藏外道书-古书隐楼藏书.md (第1035块)
  得药"。还复默运周天火候，是谓四候封固。……
  ── 原文 [….md 第 40~42 行] (窗口 38~45 行) ──
  ……⟦……周天火候……⟧……
```

- `source` = Markdowns/ 下的原文件名(可溯源);
- `--original` 输出的窗口保留原文格式(标题、`>` 引用、全角缩进等),`⟦...⟧`
  标出与检索块的精确对应范围,`--context N` 控制窗口大小(默认 300,自动对齐段落)。

## 已知限制与注意

1. text 引擎是关键词/短语匹配:自然语言问句建议先抽取专名或原句短语;要语义
   匹配请安装本地模型用 `--engine semantic`。
2. chroma 的 metadata `where` 不支持 `$contains`(静默返回 0),`--source` 因此
   采用"文件系统匹配文件名 + `$in`"实现,只匹配文件名。
3. `extract_original.py` 的定位依赖"清洗重放"与建库脚本逐字符一致;用
   `setup_workspace.py` 重建的库与数据集逐块对应,可直接配合使用。
4. 在 DSH 中运行脚本会因 `import chromadb`(读取 site-packages)先被沙箱拒绝
   一次,属预期;用完整文件访问(danger-full-access)重试同一命令即可。
5. `daozang.cmd` 的 query/extract 附加参数上限 8 个(含引号参数计 1 个),超过
   请改用方式 B 直接调用 Python。

## 文件清单

```
dao-zang/
├── SKILL.md                  # skill 定义 (frontmatter: name/description/whenToUse)
├── scripts/
│   ├── daozang.cmd           # 便携启动器 (自动定位 Python/工作区, 任意目录可用)
│   ├── query_daozang.py      # 主检索脚本 (text/semantic/auto 三引擎 + --original)
│   ├── extract_original.py   # 原文定位提取 (清洗重放 + 偏移映射 + 窗口)
│   ├── check_env.py          # 便携可用性自检 (零第三方依赖; --selftest 冒烟)
│   ├── local_embed.py        # 本地 bge-m3 ONNX 推理适配器
│   ├── setup_local_model.py  # 本地模型下载器 (断点续传)
│   └── setup_workspace.py    # 数据准备: 从 DaoZang 数据集下载 + 离线重建向量库
└── references/
    └── USAGE.md              # 本文件
```