# Scholar Library · 文献研究插件

面向高校学生与研究员的本地文献库，通过标准MCP接入AI宿主。宿主负责理解与写作；插件负责收集、版本、原件、TextIn任务、证据检索、引用完整性检查、关系、导出和恢复。

**状态：0.1.0 开发版，持续更新、完善与迭代中。** 能力及验收边界见[验收记录](docs/acceptance.md)。历史开发记录报告 TextIn 直连 API 完成30篇中英文论文、374页解析，以及字段/表格抽取实测；原始材料、响应与本机诊断库不公开，不能仅凭该摘要独立复核；广泛材料质量、人工语义指标及第二种图形AI宿主验收尚未完成，不能视为计划全部验收通过。

## 环境与兼容性

- Python 3.12+、[uv](https://docs.astral.sh/uv/getting-started/installation/)、Git，以及支持本地 stdio MCP 的 AI 客户端。MCP 是客户端调用本地工具的协议，不是另一个聊天模型。
- macOS 已有本机运行证据；Linux 使用相同 POSIX 文件锁接口，但尚需独立实机验收。
- Windows 原生 Python 暂不支持。可在 WSL2/Linux 内安装并让客户端启动 WSL 中的服务；这一组合尚未实机验收，不提供 Windows 原生安装包。
- 首次安装会下载 Python/依赖，需要网络。API 服务的额度、价格和产品权限由各服务商控制，开源代码不包含免费额度或凭据。

## 安装与运行

```sh
git clone https://github.com/SAKURAfan1023/scholar-library.git
cd scholar-library
uv sync --locked --python 3.12
uv run python scripts/configure_local.py
uv run python scripts/smoke_mcp.py
```

最后一步在临时合成库中验证 MCP，不上传论文、不调用 OCR。将生成的 `.mcp.json` 内容导入客户端的 MCP 配置；直接作为 Codex 本地插件使用时，仓库中的 manifest 和 Skill 也一并保留。宿主各自的插件注册界面可能不同，配置导入后必须实际调用 `workspace_status` 确认连接。

手工启动服务用于排障：

```sh
uv run scholar-library
```

以上命令启动stdio MCP服务，等待客户端请求；不会自动上传。`.mcp.example.json` 提供无密钥格式示例，`configure_local.py` 生成的 `.mcp.json` 是本机专用文件，不进入 Git；移动源码后重新生成。正式安装使用`python3 scripts/build_release.py`构建独立安装包，解压后运行`python3 install_release.py --target <新的安装目录>`，将生成的`mcp.json`交给支持本地stdio MCP的客户端。安装会下载锁定依赖，不是全离线安装包。

默认库为`~/.local/share/scholar-library`，可用环境变量`SCHOLAR_DATA_DIR`指定。运行环境、源码与文献库相互独立；真实材料不进入Git或插件安装包。

TextIn凭据通过系统钥匙串配置：

```sh
uv run scholar-configure TEXTIN_APP_ID
uv run scholar-configure TEXTIN_SECRET_CODE
```

同名环境变量可覆盖钥匙串，适合受控部署；不要把值写入MCP配置或分享给AI。OpenAlex可配置`OPENALEX_API_KEY`，可选语义索引配置`EMBEDDING_API_KEY`。服务商是否开通产品仍须真实验证。

## 第一次使用

1. 创建专用材料目录，将要研究的PDF/DOCX/图片/文本放入其中。
2. 向AI说明研究问题、输入目录、哪些服务允许联网、可用页数和请求预算。
3. AI调用workspace_status、create_project，建立授权项目，再检索或导入指定材料。
4. 阅读、追问、对比后将带引用主张保存为research记录，按需要导出。

示例提示：

> 使用文献插件研究“检索增强生成如何降低文献问答中的错误引用”。先检查工作区，建立研究项目。优先检索Crossref和arXiv，列出候选与来源状态。只下载我选中的开放PDF。全文解析前核对项目上传授权和页数预算。回答必须带原文片段和PDF页序，区分作者结论、推断和证据不足。

已有授权在项目内持续有效，无需每次调用重复确认。`host_text`控制向宿主返回正文，但无法控制宿主接收后的保存策略。TextIn页范围限制处理页，上传的仍是整个文件。

## 能力

- Crossref/OpenAlex/arXiv/PubMed检索及逐来源状态；DOI/PMID/arXiv解析；公开PDF下载。
- BibTeX/RIS/CSL-JSON与Zotero交换题录，付费数据库通过授权本地全文导入。
- 独立文献版本、来源快照、阅读和筛选理由，重复与冲突候选。
- 免费离线PDF文字层解析、原页图核对；TextIn xParse任务续接、分批论文解析、原始缓存、页图读取；单独字段/表格抽取。
- 中英文关键词检索、可选OpenAI兼容embedding混合检索；向量本地保存。
- 带精确摘录的回答/卡片/综述，跨论文关系，方法评价；生成产物不污染原文检索。
- Markdown、JSON、CSV、BibTeX、RIS、CSL-JSON、HTML、PDF、DOCX，GB/T 7714与APA参考文献。
- 带哈希的备份/恢复、删除影响预览、版本冲突控制。

## 边界

- 单人本地库，允许多个新服务进程连接；不放网络盘。备份需关闭其他连接；Windows尚未支持POSIX文件锁。
- 单文件100MiB、PDF最多2000页、每次TextIn处理1–100页；这是本地保护值，不代表服务商必然支持。服务商拒绝时保留任务及失败状态。
- `request_budget`累计计入网络检索、下载、解析提交、查询和向量请求，`page_budget`计入解析/抽取预留页数。未知提交不释放预留量，避免超支；不报告无法核实的货币费用。
- 本地MD/TXT/DOCX解析不做OCR。DOCX使用段落/表格位置而不是稳定页码，文本框和复杂布局可能未提取。PDF可用parse_local_pdf离线提取文字层进入索引；扫描页/图片需TextIn。文字层完整不代表视觉内容完整，表格、公式、双栏顺序须看原页复核。
- OpenAlex标志与Crossref撤稿通知都是来源信息，不是论文质量保证；元数据源不全、错误或过期均可能影响结论。
- 下载和embedding拒绝内网地址并固定实际连接IP；遇到本机代理的198.18/15合成DNS地址时，会通过Cloudflare HTTPS DNS核实公开域名（仅发送域名，另计一次请求预算），不会关闭内网保护。
- 表格CSV保存表格文本；复杂单元格结构在解析JSON中保留。HTML使用离线KaTeX；PDF/DOCX保留TeX源码，暂不转换为原生数学对象。
- 删除清理题录、证据和索引并标记相关产物过期；输入文件、旧导出、备份、原始对象文件及服务商副本保留，不能称为彻底擦除。
- 不提供后台调研/通知、团队服务、付费墙绕过或自动安装模型；宿主不调用工具时不会自主运行研究。

## 开发验证

```sh
uv run pytest -q
uv run ruff check src tests scripts
uv run python scripts/smoke_mcp.py
uv run python scripts/benchmark.py
uv run python scripts/probe_metadata.py
```

前四项使用独立合成测试库，不调用付费接口。最后一项只联网查询公开题录并保存来源状态，不上传本机论文。可用`scripts/evaluate.py`对人工标注证据问题计算Recall@10；人工语义支持率不能用合成测试替代。标注格式及指标边界见[评估说明](docs/evaluation.md)。

参考[设计与调研](docs/design.md)、[验收记录](docs/acceptance.md)。

题录交换保留常用出版字段，原始导入文件和未映射字段可追溯；两条ACL官方题录的三格式往返已实测。复杂定制字段与不同管理器兼容性仍需针对样本验证。

## 直接调用TextIn API

`uv run python scripts/textin_acceptance.py submit VERSION_ID --start 1 --end 2`提交现有版本；`poll JOB_ID`只查询已有任务；`extract VERSION_ID --key '全部作者（按原文顺序）'`抽取字段，`--table-header`可重复指定表头。这些命令使用HTTP API，不通过MCP，凭据读取系统钥匙串。每次请求先落盘记录，已知任务不重复上传。

独立安装目录同时提供textin_acceptance.py，可用该目录的runtime/bin/python -I执行。用户明确授权无限预算时page_budget/request_budget支持null；未授权时默认0。

## 配置与数据链路

| 配置 | 用途 | 默认/要求 |
| --- | --- | --- |
| `SCHOLAR_DATA_DIR` | SQLite、原件、证据与导出所在的本地库 | `~/.local/share/scholar-library` |
| `TEXTIN_APP_ID` / `TEXTIN_SECRET_CODE` | TextIn 解析与抽取 | 按需配置；本地文字层解析不需要 |
| `OPENALEX_API_KEY` | OpenAlex 检索 | 按服务商当前要求配置 |
| `EMBEDDING_API_KEY` | 可选语义向量服务 | 非必需；使用前确认正文传输授权 |
| 项目 `input_root` | 可读取的材料目录 | 建项目时显式指定 |
| 项目 policy / budgets | 联网、上传、正文返回与请求/页数预算 | 默认拒绝未授权动作，不把旧测试授权带入新项目 |

```mermaid
flowchart LR
  User[用户授权与研究问题] --> Host[AI 宿主]
  Host --> MCP[本地 MCP 工具]
  MCP --> Store[独立 SQLite 库与原件]
  MCP --> Evidence[证据片段与引用校验]
  MCP -->|按项目授权和预算| Provider[题录检索 / TextIn / 可选向量服务]
  Evidence --> Export[研究记录与多格式导出]
```

AI 推理在宿主侧进行；本插件负责存储、工具执行和证据约束，不要求另外填一个通用聊天模型 Key。`host_text` 开启后宿主会接收正文，仍须考虑宿主自身的数据政策。

## 常见问题与更新

- **服务启动后没有聊天窗口**：stdio 服务在等待 MCP 客户端连接；先用 `smoke_mcp.py` 核对，再在宿主调用 `workspace_status`。
- **找不到凭据**：钥匙串和客户端所用系统账户应一致；Linux 需要可用的 keyring 后端，也可从受控启动环境注入同名变量。
- **检索/上传被拒绝**：先核对当前项目授权与预算。不要通过关闭安全检查或自动重试来绕过失败。
- **找不到之前的记录**：核对 `SCHOLAR_DATA_DIR` 和当前运行版本；更新源码不等于已重启宿主中的旧服务。
- **解析成功但理解错误**：先回看原页和具体摘录，按 [评估说明](docs/evaluation.md) 保存待人工核对状态。

源码方式升级：先保存本地改动，再 `git pull --ff-only`、`uv sync --locked`、重新生成 `.mcp.json` 并在客户端重载服务。独立安装包应安装到新目录，验证后切换配置。数据始终与源码/运行环境分开保存，重要库先备份。

## 目录与验证证据

`src/` 是核心实现，`skills/` 是 Agent 工作流，`tests/` 是自动回归，`scripts/` 含构建、自检和显式联网实验，`docs/` 保存设计与验证边界。`output/`、数据目录、凭据和本机安装清单不公开。

当前公开版本复现结果见 [发布验证](docs/public-validation.md)；[历史验收摘要](docs/acceptance.md) 和 [完成度审计](docs/completion-audit.md) 是带日期的开发记录，不代表读者设备、实时外部接口或全部语义质量通过。

## 维护、贡献与使用声明

**持续更新、完善与迭代中。禁止恶意转载与滥用。** 转载须保留版权和许可声明，请注明原仓库及修改内容；不得冒充作者或官方、夹带恶意代码、盗取凭据、泄露个人资料或伪造研究/学习证据。

代码按 [MIT License](LICENSE) 开源。上述反滥用声明不额外撤销 MIT 授予的合法使用、修改、转载或商用权利；第三方材料和服务不随代码一并授权。完整说明见 [USE_POLICY.md](USE_POLICY.md)、[第三方声明](THIRD_PARTY_NOTICES.md)。

欢迎通过仓库 Issues 反馈 Bug 或建议。请包含版本、系统、脱敏复现步骤、预期与实际结果；不要上传密钥或真实私密材料。提交代码前阅读 [贡献指南](CONTRIBUTING.md)，安全问题见 [SECURITY.md](SECURITY.md)。