Metadata-Version: 2.3
Name: dhcckb-mingqing-narrative
Version: 0.3.1
Summary: 明清小说与戏曲叙事检索、事件分析及标注辅助 MCP Server
License: MIT
Requires-Python: >=3.11
Requires-Dist: mcp>=1.12.0,<2.0.0
Requires-Dist: httpx>=0.27.0,<1.0.0
Requires-Dist: openpyxl>=3.1.0,<4.0.0
Description-Content-Type: text/markdown; charset=UTF-8

# 明清小说与戏曲叙事研究 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 时：

```powershell
uvx --from dhcckb-mingqing-narrative==0.3.1 dhcckb-mingqing-narrative --version
```

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

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

## 建立本机 Excel 语料索引

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

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

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

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

```text
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，因此本项目不在每次查询时抓取网页，而是先显式下载一个本机镜像并建立检索索引；这样更稳定，也不会在公共服务中隐式下载或传播全文。

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

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

在 MCP 环境变量中追加：

```text
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 安装方式：

```json
{
  "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 授权后另行接入。

## 本地验证

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