DaoZang Skill — 道藏知识库离线检索与原文提取

面向 DeepSeek Harness (DSH) 的技能包：在"道藏工作区"（含 ChromaDB/ 向量库与 Markdowns/ 原文目录）中检索经文段落，并从原始 Markdown 精确提取原文（带行号与命中标记）。

完全离线：不调用任何嵌入 API、不需要网络。可选本地 bge-m3 模型启用语义检索。

功能一览

能力	说明
关键词检索	`text` 引擎（默认，零依赖）：ChromaDB 内置全文过滤 + 词频/IDF 排序
语义检索	`semantic` 引擎：本地 bge-m3 ONNX 模型，与库中 1024 维向量同模型同维度
引擎自动选择	`auto`：本地模型可用则语义，否则全文
原文提取	`--original`：从原始 `.md` 定位命中段落，`⟦...⟧` 标出范围，附原文行号
按文件过滤	`--source 关键词`：只检索文件名含关键词的经文
工作区自动定位	自动向上查找含 `ChromaDB/` + `Markdowns/` 的工作区，无需 `--workspace`
环境自检	`check_env.py`：静态检查依赖/工作区/模型，`--selftest` 跑真实检索冒烟
一键启动器	`daozang.cmd`：统一入口（check/query/extract），自动定位 Python 与工作区
状态浮标（可选）	DSH 对话窗口右侧显示 ChromaDB 块数/文件数与当前引擎

目录结构

dao-zang/
├── SKILL.md                  # skill 定义（frontmatter: name/description/whenToUse）
├── scripts/
│   ├── daozang.cmd           # 一键启动器（自动定位 Python 与工作区）
│   ├── check_env.py          # 环境自检（静态检查，--selftest 真实冒烟）
│   ├── query_daozang.py      # 主检索脚本（text/semantic/auto 三引擎 + --original）
│   ├── extract_original.py   # 原文定位提取（清洗重放 + 偏移映射 + 窗口）
│   ├── local_embed.py        # 本地 bge-m3 ONNX 推理适配器
│   ├── setup_local_model.py  # 模型下载器（官方 BAAI/bge-m3, 断点续传）
│   └── setup_workspace.py    # 全新工作区一键搭建（离线重建向量库）
└── references/USAGE.md       # 使用文档
install.ps1 / uninstall.ps1   # 安装 / 卸载脚本（UTF-8 BOM，兼容 PowerShell 5.1）

环境要求

Windows / macOS / Linux，Python ≥ 3.10
pip install chromadb（1.5.x）
语义引擎另需：pip install onnxruntime tokenizers
道藏工作区：含 ChromaDB/（285,117 块）与 Markdowns/（3,152 个原文文件）

安装

方式一：脚本安装（推荐，一键含数据与模型）

# 克隆/下载本仓库（或仅取 install.ps1 + dao-zang/ 两件）后在仓库目录执行。
# 默认: 安装 skill 到用户级 ~/.dsh/skills + 下载 ChromaDB.zip/Markdowns.zip 到当前目录
#       + 从 https://huggingface.co/BAAI/bge-m3/ 拉取模型 (~2.2GB)
.\install.ps1 -DataDir D:\daozang-workspace

# 常用参数:
#   -ProjectRoot <路径>    只安装到指定项目的 .dsh/skills
#   -DataDir <路径>        数据解压目录（默认当前目录）
#   -SkipData              数据已有，跳过下载
#   -SkipModel             跳过模型下载
#   -QuantizedModel        改用 int8 量化模型 (~543MB, 更快更小)
#   -ModelBaseUrl https://hf-mirror.com   国内镜像拉取模型
#   -Force                 覆盖更新
.\install.ps1 -ProjectRoot D:\Manuals\中华道藏 -Force

方式二：手动复制

把 dao-zang/ 目录整体复制到以下任一 skill 发现根：

根目录	优先级	作用域
`<工作区>/.dsh/skills/`	高	仅该工作区
`<工作区>/.agents/skills/`	中	仅该工作区
`~/.dsh/skills/`	低	当前用户所有工作区
`~/.agents/skills/`	低	当前用户所有工作区

数据手工下载：

curl -L -o ChromaDB.zip   https://huggingface.co/datasets/Godners/daozang-data/resolve/main/ChromaDB.zip
curl -L -o Markdowns.zip  https://huggingface.co/datasets/Godners/daozang-data/resolve/main/Markdowns.zip
Expand-Archive ChromaDB.zip, Markdowns.zip -DestinationPath D:\daozang-workspace

方式三：Harness 本体（可选）

把 dao-zang/ 复制到 DSH checkout 的 .agents/skills/ 下，随 harness 软件一起存在。

使用

安装后，在 DSH 对话输入框输入 /，菜单中会出现 dao-zang；也可以直接让助手 "使用 dao-zang skill 查……"。模型侧同样会在会话技能目录中自动发现该 skill。

命令行直接使用：

# 关键词检索（零依赖，默认引擎）
python <skill>/scripts/query_daozang.py "周天火候" 5 --workspace D:\Manuals\中华道藏

# 限定文件范围
python <skill>/scripts/query_daozang.py "天地悉皆归" 3 --source 清静妙经 --workspace D:\Manuals\中华道藏

# 检索 + 原文提取（带行号与 ⟦命中⟧ 标记）
python <skill>/scripts/query_daozang.py "内丹修炼 周天火候" 3 --original --workspace D:\Manuals\中华道藏

# 语义检索（需先安装本地模型）
python <skill>/scripts/query_daozang.py "什么是内丹修炼中的周天火候？" 3 --engine semantic --workspace D:\Manuals\中华道藏

# 按文件名 + 块序号直接提取原文
python <skill>/scripts/extract_original.py 清静经 --list --workspace D:\Manuals\中华道藏
python <skill>/scripts/extract_original.py 太上老君说常清静妙经 0 --context 300 --workspace D:\Manuals\中华道藏

本地模型（可选，语义引擎）

# 官方 BAAI/bge-m3 onnx 导出（默认，约 2.2GB，FP32，断点续传）
python <skill>/scripts/setup_local_model.py --dir D:\daozang-workspace\models\bge-m3

# 国内镜像
python <skill>/scripts/setup_local_model.py --dir ... --base-url https://hf-mirror.com

# 小体积 int8 量化版（~543MB，CPU 更快）
python <skill>/scripts/setup_local_model.py --dir ... --quantized

# 也可用环境变量指向已有模型目录
set DAOZANG_EMBED_MODEL=D:\path\to\bge-m3

模型来源：官方仓库 https://huggingface.co/BAAI/bge-m3/ 的 onnx/ 导出（model.onnx + model.onnx_data + tokenizer.json）。检索质量与在线 bge-m3 API 版一致（实测 Top-3 命中完全相同，相似度差 <0.01）。

DSH 对话窗口状态浮标（可选）

在对话窗口右侧、输入框上方显示 DaoZang 状态：ChromaDB 总块数 / 文件数 / 当前引擎（Text/Semantic/Auto），每次检索后自动更新。需要修改并重建 harness 的 ui-conversation 包：

packages/client/ui-conversation/src/client/skeleton/
├── DaoZangStatusBadge.tsx        （新增）
├── DaoZangStatusBadge.module.css （新增）
├── ConversationRoot.tsx          （挂载浮标）
└── ConversationRoot.module.css   （.root 加 position: relative）

pnpm exec tsc -b tsconfig.client.json   # checkout 根目录
cd packages/client/ui-conversation
pnpm exec tsdown --env.DSH_BUILD_FACE client

刷新页面生效（manifest rev 动态更新）；浮标数据来自检索脚本输出的状态头（总块数/文件数/引擎），每次使用时重新计算。

已知限制与注意

text 引擎是关键词/短语匹配：自然语言问句建议先抽取专名或原句短语，或使用 semantic 引擎。
chroma 1.5.9 的 metadata where 不支持 $contains（静默返回 0），--source 采用"文件系统匹配文件名 + $in"实现，只匹配文件名。
在 DSH 沙箱下运行脚本会因 import chromadb（读取 site-packages）先被拒绝一次，属预期；用完整文件访问（danger-full-access）重试同一命令即可。
原文定位依赖"清洗重放"与建库脚本逐字符一致；重建数据库并改动清洗逻辑后，请重跑工作区内的 _test_replay.py 回归验证。

数据与致谢

语料：《中华道藏》《正统道藏》Markdown 整理本（3,152 篇，共 285,117 个文本块）
嵌入模型：BAAI/bge-m3（1024 维，cosine），本地推理采用 Xenova/bge-m3 ONNX 导出
向量库：ChromaDB（嵌入式 PersistentClient，collection DaoZang）

版本

v2.0：工作区自动定位、一键启动器 daozang.cmd、环境自检 check_env.py、全新工作区搭建 setup_workspace.py
v1.0：离线双引擎检索 + 原文提取 + 本地模型 + 安装包