dhcckb-mingqing-narrative 0.3.0

明清小说与戏曲叙事检索、事件分析及标注辅助 MCP Server

明清小说与戏曲叙事研究 MCP Server

本版本是面向公共 PyPI 发布的本地优先研究工具，不以《红楼梦》为唯一对象。它有两条主流程：

1. 对用户输入的小说、笔记或戏曲片段生成可审核的叙事标注；
2. 在本机 Excel、可选 chinese-novel 镜像和其他已配置语料中召回近似文本，再进行规则型排序。

它把用户导入的《红楼梦》标注样例、事件层/关系层规则和本机语料索引连接到 MCP 工具中，支持：

• 读取标注 Schema 与原始事件层、关系层规则；
• 抽取待审核的实体、事件、realis 与事件层代码；
• 从导入的《红楼梦》样例中检索相近标注参照；
• 在本机 Excel 语料索引和可选 chinese-novel 公共小说镜像中检索作品与段落；
• 生成不写回数据库的标注草稿。

所有自动结果都是研究线索和待审核草稿，不能直接断言文本影响、改写、来源关系或人工精标结论。

随包资源

• 红楼梦标注数据-1785681374295.json：以压缩只读资源形式导入，共 120 回、9,717 条叙事记录；原数据中的 _aiGenerated 标记会随结果保留。因此，除非记录明确为 human_verified，系统不会称其为人工 Gold Data。
• 事件层.md、关系层.md：通过 get_annotation_guideline 可读取；并整理为可机读的 25 种事件类型、7 种功能类型、8 种叙事成分及 16 种关系类型。
• test.jsonl：随包保存，供后续评测扩展使用。
• 小型演示语料：仅用于没有本机索引时的功能验证。

不会随包发布： 你的大型明清小说和戏曲 Excel 全文。它由本机 SQLite 索引引用，既减小发行包，也避免将未确认授权范围的文本上传到 PyPI。

安装

已发布到 PyPI 时：

uvx dhcckb-mingqing-narrative==0.3.0 --version

未发布或希望使用本地源码时，在项目目录执行：

python -m venv .venv
.\.venv\Scripts\python -m pip install .

建立本机 Excel 语料索引

首次执行一次。下面的输出路径可以自行调整，但不要放到准备发布的包目录中：

dhcckb-mingqing-build-corpus-index `
  "D:\博士生资料\博士论文相关\数据库资料\数据库统一规范化_合集_v3_篇名折次修订.xlsx" `
  --output "D:\博士生资料\博士论文相关\数据库资料\mingqing_narrative_corpus.sqlite"

该过程会读取工作表 全部数据，建立只在本机使用的 SQLite 全文索引。完整语料量较大，请预留磁盘空间。若要先验证流程，可增加 --max-rows 100。

然后在 Cherry Studio 的 MCP 配置的环境变量中设置：

MINGQING_CORPUS_INDEX_PATH=D:\博士生资料\博士论文相关\数据库资料\mingqing_narrative_corpus.sqlite

在聊天中先调用 get_corpus_status。其中 local_excel_index.available 显示 true，才说明 Excel 已真正接入。

接入 chinese-novel 公共小说库

luoxuhai/chinese-novel 是一个 MIT 许可、但已归档的静态 GitHub 小说库：作品信息在每部书的 info.json，各回正文保存为递增编号的 HTML 文件。它没有正式搜索 API，因此本项目不在每次查询时抓取网页，而是先显式下载一个本机镜像并建立检索索引；这样更稳定，也不会在公共服务中隐式下载或传播全文。

dhcckb-mingqing-fetch-chinese-novel `
  --output "D:\数字人文语料\chinese-novel"

dhcckb-mingqing-build-chinese-novel-index `
  "D:\数字人文语料\chinese-novel" `
  --output "D:\数字人文语料\chinese_novel.sqlite"

在 MCP 环境变量中追加：

CHINESE_NOVEL_INDEX_PATH=D:\数字人文语料\chinese_novel.sqlite

调用 get_corpus_status 后，chinese_novel_index.available: true 表示已接入。检索时可用 sources: ["chinese_novel_local_index"] 限定该库；不传 sources 时会与 Excel 索引一起参与召回。

Cherry Studio 配置

PyPI 安装方式：

{
  "name": "明清小说叙事研究",
  "type": "stdio",
  "command": "uvx",
  "args": ["dhcckb-mingqing-narrative==0.3.0"],
  "env": {
    "MINGQING_CORPUS_INDEX_PATH": "D:\\博士生资料\\博士论文相关\\数据库资料\\mingqing_narrative_corpus.sqlite",
    "CHINESE_NOVEL_INDEX_PATH": "D:\\数字人文语料\\chinese_novel.sqlite"
  }
}

如果你的 Cherry Studio 只显示“命令 / 参数 / 环境变量”三个输入框：命令填 uvx；参数填 dhcckb-mingqing-narrative==0.3.0；环境变量填上面的两个索引路径。

主要工具

工具	用途
annotate_narrative_text	主入口一：对输入片段生成待审核叙事标注草稿
find_similar_narratives	主入口二：跨已配置语料抽取并检索近似叙事文本
get_corpus_status	检查导入样例、规则、Excel 与 chinese-novel 索引是否实际装载
get_annotation_schema	读取通用 Schema 及事件层/关系层扩展字段
get_annotation_guideline	读取机读规则；可选返回原始 Markdown 提示词
search_corpus	检索演示集、Excel 索引和 chinese-novel 本机镜像
get_source_passage	读取检索结果对应的本机原文
extract_narrative_units	从短文本抽取待审核的实体和事件候选
search_annotation_examples	从导入《红楼梦》标注样例检索参照
create_annotation_draft	生成带质量提示的只读标注草稿
search_similar_passages	在局部候选中按字符特征与规则事件特征排序

推荐验证顺序

1. get_corpus_status
2. get_annotation_guideline，参数 {"layer":"event"}
3. extract_narrative_units，例如：宝玉梦游太虚幻境，警幻仙姑引他观看册簿，醒来后若有所失。
4. search_annotation_examples，传入相同文本
5. Excel 或 chinese-novel 索引装载后调用 search_corpus，例如：{"keywords":["梦", "册"], "keyword_logic":"AND"}

安全与数据边界

• 服务默认是 stdio；HTTP 模式只允许监听 127.0.0.1 / localhost / ::1。
• MCP 不会写回、覆盖或删除任何标注记录。
• Excel 索引与 chinese-novel 索引仅由你配置的本地路径读取；包不会上传原文。
• 下载 chinese-novel 快照是单独、显式的 CLI 操作；使用、再发布文本前请保留上游 MIT 许可并确认具体部署场景的权利边界，详见 THIRD_PARTY_NOTICES.md。
• search_similar_passages 当前是“跨库局部候选召回 + 字符特征/规则事件排序”，不是向量检索或 LLM Judge。
• 外部 CBDB、CHGIS 等权威库仍需取得正式 API 授权后另行接入。

本地验证

.\.venv\Scripts\python scripts\smoke_test.py