dhcckb-mingqing-narrative 0.3.1

明清小说与戏曲叙事检索、事件分析及标注辅助 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 种核心事件类型，并新增 11 种可跨小说、笔记与戏曲使用的扩展类型。
• test.jsonl：随包保存，供后续评测扩展使用。
• 小型演示语料：仅用于没有本机索引时的功能验证。

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

安装

已发布到 PyPI 时：

uvx --from dhcckb-mingqing-narrative==0.3.1 dhcckb-mingqing-narrative --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

建立索引会逐篇处理约两万份 HTML 并重建全文检索表，首次通常需 20—60 分钟。完成后终端会回到 PowerShell 提示符，并显示实际片段数。调用 get_corpus_status 后，只有同时看到 chinese_novel_index.available: true、record_count 为具体数字且 fts_tokenizer 非空，才表示索引完整可检索。检索时可用 sources: ["chinese_novel_local_index"] 限定该库；不传 sources 时会与 Excel 索引一起参与召回。

Cherry Studio 配置

PyPI 安装方式：

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

如果 Windows 找不到 uvx，命令改填 C:\Users\你的用户名\.cherrystudio\bin\uvx.exe。参数依次填 --refresh、--from、dhcckb-mingqing-narrative==0.3.1、dhcckb-mingqing-narrative；环境变量填上面的索引路径。

标注结构与两种模式

新版不再把“超自然”“身体动作”“情绪表达”等泛类混作事件类型。每份草稿严格分三层：

1. 事件容器：event_type 只能是规范代码，例如《红楼梦》核心层的 DRM（梦幻）、MTG（会面），或跨文体扩展的 REV（启示/预言揭示）、IDN（身份识认）等；
2. 事件内部叙事成分：narrations[].type 才使用 ACT（行动）、PSY（心理）、DLG（对话）、TXT（嵌入文本）等；
3. 实体关系：仅在原文有明确证据时输出 CMD、CARE、CFL 等实体—实体关系。人物共现与人物参与事件不再冒充关系标注。

annotate_narrative_text 和 extract_narrative_units 都接受 annotation_mode：

• passage（默认）：适合用户输入的片段，只生成候选事件及内部成分；不套用章节的 8—15 个事件限制；
• chapter：适合完整章回的初稿。仍须人工审核章回标题、句子边界、事件数及无缝覆盖，系统不会把它伪装成已完成的章节级精标。

例如“宝玉梦游太虚幻境，警幻仙姑引他观看册簿，醒来后若有所失”应以 DRM 梦幻事件容器表示；“梦游／引观／醒来”是 ACT 成分，“若有所失”是以宝玉为对象的 PSY 成分。

主要工具

工具	用途
annotate_narrative_text	主入口一：对输入片段或完整章回生成待审核叙事标注草稿；支持 annotation_mode
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	从文本抽取待审核的事件容器及其内部叙事成分，支持 annotation_mode
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