Metadata-Version: 2.4
Name: dhcckb-allusion-tracer
Version: 0.1.0
Summary: 典故溯源与历代化用检索工具 — MCP Server，跨 6 个中文古籍数据源检索典故出处、历代征引、语义变迁和群体分布。
Project-URL: Homepage, https://pypi.org/project/dhcckb-allusion-tracer/
Author-email: Digital Humanities Platform <dh@example.com>
License: MIT
License-File: LICENSE
Keywords: allusion-tracing,chinese-classics,digital-humanities,literary-reference,mcp,text-mining
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: diskcache>=5.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 典故溯源与历代化用检索工具 (Allusion Tracer)

**dhcckb-allusion-tracer** 是一个 MCP (Model Context Protocol) Server，提供典故溯源、历代征引检索、语义变迁分析和群体时代分布统计功能。数据来源于 6 个中文古籍网站。

## 功能概览

| 工具 | 说明 |
|------|------|
| `allusion_source_trace` | 典故溯源考镜 — 检索最早典籍出处（经史子集），标注多源分歧 |
| `allusion_diachronic_citations` | 历代征引检索 — 返回按时间线排序的化用引文列表 |
| `allusion_semantic_change` | 语义变迁分析 — 情感色彩/隐喻对象演变，标注突变节点 |
| `allusion_demographic_distribution` | 群体与时代分布 — 使用频次、群体占比、流行高峰期 |

## 数据源

| 标识符 | 名称 | 需要登录 |
|--------|------|----------|
| `ctext` | 中国哲学书电子化计划 (ctext.org) | 否 |
| `souyun` | 搜韵 (sou-yun.cn) | 否 |
| `shidian` | 识典古籍 (shidianguji.com) | 否 |
| `hytung` | 瀚堂典藏 (hytung.cn) | 是 |
| `zhonghua` | 中华经典古籍库 | 是 |
| `nlc` | 中国国家数字图书馆 (nlc.cn) | 部分 |

默认使用 `ctext` + `souyun` + `shidian`（免登录），其余数据源需配置凭据后启用。

## 安装

```bash
# 通过 pip 安装
pip install dhcckb-allusion-tracer

# 或使用 uv
uv tool install dhcckb-allusion-tracer

# 开发安装
git clone <repo> && cd allusion-tracer
pip install -e ".[dev]"
```

**要求**：Python 3.11+

## 配置

### 环境变量 / .env 文件

在项目目录或 `$HOME` 下创建 `.env` 文件，或直接设置环境变量：

```bash
# 瀚堂典藏凭据（如需）
HYTUNG_USERNAME=your_username
HYTUNG_PASSWORD=your_password

# 中华经典古籍库凭据（如需）
ZHONGHUA_USERNAME=your_username
ZHONGHUA_PASSWORD=your_password

# 缓存目录（可选，默认 ~/.allusion_tracer/cache）
ALLUSION_TRACER_CACHE_DIR=/path/to/cache
```

### 自定义 .env 路径

```bash
ALLUSION_TRACER_ENV=/path/to/custom.env uv run allusion-tracer
```

## 使用方式

### 作为 MCP Server 运行（stdio）

```bash
# 直接启动
uvx dhcckb-allusion-tracer

# 或
python -m allusion_tracer
```

### 在 Claude Desktop 中配置

在 `claude_desktop_config.json`（或 `mcp.json`）中添加：

```json
{
  "mcpServers": {
    "allusion-tracer": {
      "command": "uvx",
      "args": ["dhcckb-allusion-tracer"],
      "env": {
        "HYTUNG_USERNAME": "your_username",
        "HYTUNG_PASSWORD": "your_password"
      }
    }
  }
}
```

### 在 VS Code Copilot 中配置

在 `.vscode/mcp.json` 中添加：

```json
{
  "servers": {
    "allusion-tracer": {
      "type": "stdio",
      "command": "uvx",
      "args": ["dhcckb-allusion-tracer"]
    }
  }
}
```

## Tool 调用示例

### 1. 典故溯源

```
工具: allusion_source_trace
参数: { "keyword": "破釜沉舟", "max_results": 3 }
```

返回最早的典籍出处（如《史记·项羽本纪》），包含原文句段、释义和出处链接。

### 2. 历代征引检索

```
工具: allusion_diachronic_citations
参数: { "keyword": "高山流水", "dynasty_from": "隋唐", "dynasty_to": "清", "max_results": 20 }
```

返回隋唐至清代间使用"高山流水"典故的诗文引文列表，按时间排序。

### 3. 语义变迁分析

```
工具: allusion_semantic_change
参数: { "keyword": "望帝春心托杜鹃", "granularity": "dynasty", "include_raw_citations": true }
```

返回该典故从先秦到清的语义变化时间线，包括情感色彩、隐喻对象变化和突变节点。

### 4. 群体与时代分布

```
工具: allusion_demographic_distribution
参数: { "keyword": "杜鹃啼血", "group_by": "dynasty", "visualization_format": "markdown_table" }
```

返回各朝代使用频次、使用群体占比和流行高峰期。

## 返回结构

所有工具返回统一的 JSON 结构，包含：

```json
{
  "keyword": "查询关键词",
  "... 工具特定字段 ...": "...",
  "unavailable_sources": ["数据源名称"],
  "error": "错误信息（如有）"
}
```

### 错误信息示例

```json
{
  "keyword": "不存在关键词",
  "error": "未在任何数据源中找到相关结果。建议尝试更具体的表述或换用其他关键词。"
}
```

## 项目结构

```
allusion_tracer/
├── adapters/          # 6 个数据源适配器（ctext/souyun/hytung/shidian/zhonghua/nlc）
│   ├── base.py        # 基类：RateLimiter, BaseAdapter
│   ├── ctext.py       # ctext.org 适配器
│   ├── souyun.py      # 搜韵适配器
│   ├── hytung.py      # 瀚堂典藏适配器
│   ├── shidian.py     # 识典古籍适配器
│   ├── zhonghua.py    # 中华经典古籍库适配器
│   └── nlc.py         # 国家数字图书馆适配器
├── cache/             # 缓存层（SQLite/JSON 文件双后端）
├── tools/             # 4 个 MCP Tool 实现
├── aggregator.py      # 跨源去重/排序/冲突检测
├── config.py          # 全局配置与凭据管理
├── models.py          # Pydantic 数据模型
└── server.py          # MCP Server 入口（stdio）
```

## 缓存

- 默认使用 SQLite 缓存，位于 `~/.allusion_tracer/cache/cache.db`
- 缓存 TTL：24 小时（可在 config 中调整）
- 可通过 `ALLUSION_TRACER_CACHE_DIR` 自定义缓存目录

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check src/
```

## 许可证

MIT License
