paperseek 0.1.0__tar.gz

paperseek-0.1.0/LICENSE

@@ -0,0 +1,181 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work by
+the copyright owner or by an individual or Legal Entity authorized to submit on
+behalf of the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to communication on
+electronic mailing lists, source code control systems, and issue tracking
+systems that are managed by, or on behalf of, the Licensor for the purpose of
+discussing and improving the Work, but excluding communication that is
+conspicuously marked or otherwise designated in writing by the copyright owner as
+"Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work to
+which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the Derivative
+Works; within the Source form or documentation, if provided along with the
+Derivative Works; or within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents of the NOTICE
+file are for informational purposes only and do not modify the License. You may
+add Your own attribution notices within Derivative Works that You distribute,
+alongside or as an addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied, including, without limitation, any warranties or
+conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on the
+same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright 2026 PaperSeek contributors
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

paperseek-0.1.0/PKG-INFO

@@ -0,0 +1,505 @@
+Metadata-Version: 2.4
+Name: paperseek
+Version: 0.1.0
+Summary: LLM based Literature Search Agent
+Author-email: MingfengHong <hongmingfeng24@mails.ucas.ac.cn>
+Maintainer-email: MingfengHong <hongmingfeng24@mails.ucas.ac.cn>
+License: Apache-2.0
+Project-URL: Homepage, https://www.paperseek.xyz/
+Project-URL: Repository, https://github.com/MingfengHong/paperseek
+Project-URL: Issues, https://github.com/MingfengHong/paperseek/issues
+Project-URL: Documentation, https://docs.paperseek.xyz/
+Project-URL: Online-Demo, https://www.paperseek.xyz/
+Keywords: literature-search,openalex,crossref,web-of-science,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dateutil>=2.5
+Requires-Dist: urllib3<3,>=1.25.3
+Requires-Dist: typing-extensions>=4.7
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.23
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == "dev"
+Dynamic: license-file
+
+# PaperSeek
+
+[![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![CI](https://github.com/MingfengHong/paperseek/actions/workflows/ci.yml/badge.svg)](https://github.com/MingfengHong/paperseek/actions/workflows/ci.yml)
+[![Status](https://img.shields.io/badge/status-alpha-orange)](#项目状态)
+[![ModelScope visits](https://img.shields.io/badge/ModelScope%20visits-2.6k-624AFF?logo=modelscope&logoColor=white)](https://modelscope.cn/studios/HongMingfeng/PaperSeek)
+
+**文档站：[PaperSeek Docs](https://docs.paperseek.xyz/) | 语言：简体中文 | [English](README.en.md)**
+
+**LLM based Literature Search Agent.** PaperSeek 是一个面向研究者的文献发现工具，支持用自然语言发起检索、自动迭代查询、扩展候选论文、排序结果并导出可复核的文献列表。
+
+在线体验：[点击体验](https://www.paperseek.xyz/)。在线版提供 `Quick Start`、`ModelScope Service` 和 `Use your own API` 三种模式：登录用户可使用站点提供的每日免费 Quick Start 额度；ModelScope 模式使用登录用户自己的 API-Inference 授权；自带 API 模式可由用户填写自己的模型和数据源 Key。详情见 [在线体验版使用说明](docs/online-demo.md)。
+
+![PaperSeek web interface](https://raw.githubusercontent.com/MingfengHong/paperseek/main/docs/assets/paperseek-web.png)
+
+完整使用说明见 [PaperSeek 用户手册](docs/user-manual.md)；部署说明见 [Docker、Vercel 与 ModelScope 部署指南](docs/deployment.md)。
+
+## 概览
+
+PaperSeek 将研究问题组织成一条可观察的检索工作流：
+
+- 输入中文或英文研究问题。
+- 由 LLM 生成适合数据源的检索查询。
+- 根据命中数量自动放宽或收窄查询。
+- 统一整理题名、作者、期刊、年份、DOI、摘要、引用数和链接等元数据。
+- 对候选文献进行 LLM 相关性评分。
+- 可选地通过 OpenAlex 引用关系扩展高匹配论文的前向引用和后向参考文献。
+- 可选地用 Discipline Fields 把检索限制在一个或多个学科领域。
+- 在网页中查看工作流、结果表和引用图，并导出 CSV。
+
+PaperSeek 专注于第一轮候选文献发现和元数据整理。系统综述流程、全文获取、版权合规和最终研究判断仍需由研究者完成。
+
+## 功能概览
+
+| 功能 | 说明 |
+| --- | --- |
+| 自然语言检索 | 输入研究问题，自动生成数据源查询。 |
+| 多轮迭代 | 根据目标结果数量自动调整查询，默认最多 5 轮。 |
+| 相关性排序 | LLM 对候选论文打分并给出简短理由。 |
+| Discipline Fields | 在 Web UI 或 CLI 中选择 OpenAlex Field 学科分类；OpenAlex 使用原生 field filter，WoS 映射为 WC 类目，Crossref 作为检索上下文。 |
+| OpenAlex 引用扩展 | 从高匹配论文扩展参考文献和被引论文。 |
+| 结果导出 | 在 Results 页面勾选论文并导出 CSV。 |
+| 引用图 | 使用箭头显示引用方向，支持拖拽、缩放和平移。 |
+| CLI 与 Web UI | 既可命令行运行，也可打开本地网页交互使用。 |
+| 中英文界面 | Web UI 可在 `EN` 和 `中文` 之间切换，选择会保存在当前浏览器。 |
+| 本地历史记录 | 开源自托管版默认把搜索记录、日志事件和结果保存到本地 SQLite，便于回看和复用。 |
+| Docker / Vercel / ModelScope 部署 | 支持 Docker 完整部署、Vercel 一键体验部署和 ModelScope Docker 创空间部署。 |
+| 配置诊断 | `doctor`、`smoke`、`sources` 帮助排查 API Key、数据源和协议问题。 |
+| 可选 Agent Skill | `skills/paperseek/` 可单独复制到支持 Skill 的 agent 平台，不随 Python 包自动安装。 |
+
+## 快速开始
+
+```bash
+git clone https://github.com/MingfengHong/paperseek.git
+cd paperseek
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+Windows PowerShell：
+
+```powershell
+git clone https://github.com/MingfengHong/paperseek.git
+cd paperseek
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+启动网页界面：
+
+```bash
+paperseek-web
+```
+
+打开：
+
+```text
+http://127.0.0.1:8765/
+```
+
+也可以直接使用命令行：
+
+```bash
+paperseek "open innovation and digital platforms" --source openalex
+```
+
+## 部署
+
+Docker 是完整 Web UI 的推荐部署方式：
+
+```bash
+docker compose up --build
+```
+
+打开：
+
+```text
+http://127.0.0.1:8765/
+```
+
+Vercel 可用于快速体验和轻量 Web UI 部署：
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FMingfengHong%2Fpaperseek)
+
+ModelScope 创空间也可通过 Docker 方式部署。点击下方按钮查看 PaperSeek 的创空间部署步骤：
+
+<a href="docs/deployment.md#modelscope-studio"><img src="docs/assets/deploy-modelscope.svg" alt="Deploy to ModelScope" height="32"></a>
+
+长时间搜索、引用扩展和大量请求建议使用 Docker 或 VPS。完整说明见 [部署指南](docs/deployment.md)。
+
+## 最小配置
+
+PaperSeek 至少需要一个 LLM。默认数据源是 OpenAlex；OpenAlex 可匿名测试，但建议申请免费 API Key 以获得更稳定的访问体验。
+
+以 DeepSeek 为例：
+
+```bash
+export LLM_PROVIDER=deepseek
+export LLM_API_TYPE=openai_chat
+export LLM_MODEL=deepseek-v4-flash
+export LLM_BASE_URL=https://api.deepseek.com
+export LLM_API_KEY=your-llm-api-key
+paperseek-web
+```
+
+以中国科技云为例：
+
+```bash
+export LLM_PROVIDER=cstcloud
+export LLM_API_TYPE=openai_chat
+export LLM_MODEL=DeepSeek-V4-Flash
+export LLM_BASE_URL=https://uni-api.cstcloud.cn/v1
+export LLM_API_KEY=your-cstcloud-api-key
+paperseek-web
+```
+
+以 ModelScope API-Inference 为例：
+
+```bash
+export LLM_PROVIDER=modelscope
+export LLM_API_TYPE=openai_chat
+export LLM_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
+export LLM_BASE_URL=https://api-inference.modelscope.cn/v1
+export LLM_API_KEY=your-modelscope-token
+paperseek-web
+```
+
+Windows PowerShell：
+
+```powershell
+$env:LLM_PROVIDER = "deepseek"
+$env:LLM_API_TYPE = "openai_chat"
+$env:LLM_MODEL = "deepseek-v4-flash"
+$env:LLM_BASE_URL = "https://api.deepseek.com"
+$env:LLM_API_KEY = "your-llm-api-key"
+paperseek-web
+```
+
+本地 Ollama 不需要 LLM API Key：
+
+```bash
+export LLM_PROVIDER=ollama
+export LLM_API_TYPE=openai_chat
+export LLM_MODEL=qwen3:8b
+export LLM_BASE_URL=http://127.0.0.1:11434/v1
+paperseek-web
+```
+
+项目提供 `.env.example`。你可以复制为 `.env` 作为本地配置参考，但不要提交真实 API Key。CLI 和 Web 后端会自动读取当前目录或项目根目录下的 `.env`；已经存在的系统环境变量优先于 `.env`。
+
+## Web UI
+
+PaperSeek 的网页界面分为四个工作区：
+
+| 页面 | 用途 |
+| --- | --- |
+| Search | 输入研究问题，选择 Discipline Fields，配置数据源、LLM、迭代次数和目标结果数；实时查看工作流与系统日志。 |
+| Results | 查看最终排序结果，搜索、过滤、排序、勾选，并导出论文 CSV。 |
+| Citation Map | 查看 OpenAlex 引用扩展形成的关系图，按箭头方向探索论文之间的引用关系。 |
+| History | 查看本地保存的搜索运行、最终检索式、结果列表和运行事件。 |
+
+如果后端已经通过系统环境变量或 `.env` 配置了 API Key，Web UI 会显示环境中已配置的状态，不会把密钥内容发送到浏览器。Web UI 中填写的 API Key、Base URL 和参数只用于当前浏览器会话，不写入本地配置文件。历史记录会保存运行参数摘要、检索式、日志事件和结果，但不会保存任何 API Key。
+
+Results 导出的 CSV 文件名使用研究问题主题和本地日期，便于区分多次运行。
+
+## CLI 用法
+
+基本检索：
+
+```bash
+paperseek "responsible AI governance in public sector" --source openalex
+```
+
+显式子命令：
+
+```bash
+paperseek search "digital platforms and open innovation" --source openalex
+```
+
+JSON 输出：
+
+```bash
+paperseek search "open innovation" --source openalex --output json
+```
+
+常用参数：
+
+```bash
+paperseek search "your research question" \
+  --source openalex \
+  --field management \
+  --discipline "Computer Science" \
+  --min 5 \
+  --max 50 \
+  --iterations 5 \
+  --llm-provider deepseek \
+  --llm-api-type openai_chat \
+  --llm-model deepseek-v4-flash \
+  --llm-base-url https://api.deepseek.com \
+  --llm-key your-llm-api-key
+```
+
+诊断配置：
+
+```bash
+paperseek doctor
+paperseek doctor --source openalex --json
+```
+
+测试数据源最小真实请求：
+
+```bash
+paperseek smoke --source openalex --query "machine learning"
+paperseek smoke --source crossref --query "open innovation" --json
+```
+
+查看数据源能力：
+
+```bash
+paperseek sources
+paperseek sources --json
+```
+
+查看本地历史记录：
+
+```bash
+paperseek history list
+paperseek history show <RUN_ID> --json
+paperseek history path
+```
+
+保存 CLI 用户级配置：
+
+```bash
+paperseek config path
+paperseek config set LLM_API_KEY your-llm-api-key
+paperseek config list
+paperseek config unset LLM_API_KEY
+```
+
+环境变量优先于用户级配置。`paperseek config list` 会遮蔽密钥。
+
+Discipline Fields 支持使用 OpenAlex Field ID、字段标签或 `https://openalex.org/fields/<id>` URL。多个字段可以重复传入 `--discipline` / `--discipline-field`，也可以在环境变量中用分号分隔，例如：
+
+```bash
+export DISCIPLINE_FIELDS="17;14"
+paperseek search "open innovation and digital platforms" --source openalex
+```
+
+`--field` / `SEARCH_FIELD` 是自由文本领域提示，主要影响 LLM 生成的检索式；`--discipline` / `DISCIPLINE_FIELDS` 是结构化学科限制。OpenAlex 会应用 `primary_topic.field.id` 过滤，WoS Starter 会映射到 `WC=` 类目，Crossref 没有共享学科 taxonomy 时会把所选学科作为查询上下文。
+
+## 数据源
+
+| 数据源 | 默认状态 | API Key | 适合场景 | 说明 |
+| --- | --- | --- | --- | --- |
+| OpenAlex | 默认 | 推荐 | 精确检索、摘要、引用数、引用扩展、引用图 | 开放学术元数据库，适合通用文献发现与引用关系探索。 |
+| Crossref | 支持 | 通常不需要 | DOI、出版元数据、期刊和出版社信息校验 | DOI 与出版元数据注册库，适合题录校验和 DOI 补全。 |
+| Web of Science Starter | 适配中 | 必需 | 已有 Clarivate API 权限的机构用户 | 商业数据库 API，返回字段和可用性取决于订阅计划与机构授权。 |
+
+## LLM 服务商
+
+PaperSeek 支持两类主流接口协议：OpenAI 风格接口和 Anthropic Messages API。Provider 表示模型服务商，API Type 表示请求协议。
+
+| Provider | 默认 API Type | 默认模型 |
+| --- | --- | --- |
+| OpenAI | `openai_responses` | `gpt-5.4-mini` |
+| Anthropic | `anthropic_messages` | `claude-sonnet-4-6` |
+| Google Gemini | `openai_chat` | `gemini-3.5-flash` |
+| DeepSeek | `openai_chat` | `deepseek-v4-flash` |
+| 中国科技云 CSTCloud | `openai_chat` | `DeepSeek-V4-Flash` |
+| 阿里云百炼 DashScope | `openai_chat` | `qwen3.6-plus` |
+| Kimi Moonshot | `openai_chat` | `kimi-k2.6` |
+| 智谱 AI GLM | `openai_chat` | `glm-5.1` |
+| 硅基流动 SiliconFlow | `openai_chat` | `deepseek-ai/DeepSeek-V4-Flash` |
+| OpenRouter | `openai_chat` | `openai/gpt-5.4-mini` |
+| 火山方舟 | `openai_chat` | `doubao-seed-2-0-mini-260428` |
+| 腾讯混元 | `openai_chat` | `hunyuan-turbos-latest` |
+| 百度千帆 | `openai_chat` | `ernie-5.0` |
+| ModelScope 魔搭 | `openai_chat` | `Qwen/Qwen3-235B-A22B-Instruct-2507` |
+| Ollama | `openai_chat` | `qwen3:8b` |
+| Custom | `openai_chat` | 空，用户自行填写 |
+
+默认模型用于初始化表单和命令参数示例。实际可用模型以各服务商控制台、账号权限和兼容层为准。
+
+中国科技云 CSTCloud 提供 OpenAI API Compatible 大模型接口，Base URL 为 `https://uni-api.cstcloud.cn/v1`。PaperSeek 内置的 provider 为 `cstcloud`，默认模型为 `DeepSeek-V4-Flash`。获取 Key 可打开 [中国科技云 API Keys](https://uni-api.cstcloud.cn/api_keys)，登录中国科技云统一认证后按页面要求提交申请信息；中国科学院院内用户可使用中国科技云通行证登录，通行证通常为院邮箱账号及密码。接口说明见 [中国科技云大模型 API 接口使用手册](https://uni-api.cstcloud.cn/doc/llm/)。
+
+## 工作流
+
+一次搜索通常包含四步：
+
+1. **Query Generation**：LLM 根据研究问题、可选 Field Hint 和 Discipline Fields 生成初始查询。
+2. **Source Search**：请求 OpenAlex、Crossref 或 WoS Starter，并记录 HTTP 状态和命中数量。
+3. **Query Refinement**：若命中数过少或过多，LLM 调整查询并继续下一轮。
+4. **Ranking & Results**：将候选池交给 LLM 统一评分，输出前若干条结果。
+
+如果启用 OpenAlex 引用扩展，PaperSeek 会从高匹配论文中选择 seed paper，加入 seed 的参考文献和被引论文，再对完整候选池统一评分。默认最大输出 50 条。
+
+候选池较大时，LLM 排序会自动分批并发执行。默认批大小为 `8`、并发为 `4`；超过 32 篇候选论文时会自适应放大批大小。单个排序批次失败时只回退该批次，不会使整次检索失败。
+
+## 引用图
+
+Citation Map 使用箭头表示引用方向：
+
+```text
+A -> B  表示 A 引用了 B
+```
+
+图中节点来自最终结果和 OpenAlex 引用扩展记录。你可以拖动节点、缩放和平移画布，并查看节点详情。引用图适合发现关键词检索遗漏的经典文献、相邻主题和近期延伸研究。
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `DATA_SOURCE` | `openalex`、`crossref` 或 `wos`，默认 `openalex`。 |
+| `LLM_PROVIDER` | LLM 服务商，例如 `openai`、`deepseek`、`cstcloud`、`anthropic`、`ollama`。 |
+| `LLM_API_TYPE` | `openai_responses`、`openai_chat` 或 `anthropic_messages`。 |
+| `LLM_MODEL` | 模型名称。 |
+| `LLM_BASE_URL` | API Base URL。 |
+| `LLM_API_KEY` | LLM API Key；Ollama 可不填。 |
+| `OPENALEX_API_KEY` | OpenAlex API Key，推荐填写。 |
+| `OPENALEX_EMAIL` | OpenAlex 联系邮箱。 |
+| `CROSSREF_EMAIL` | Crossref polite pool 邮箱。 |
+| `WOS_API_KEY` | Clarivate Web of Science Starter API Key。 |
+| `WOS_DB` | WoS 数据库代码，默认 `WOS`。 |
+| `SEARCH_FIELD` | 自由文本学科或领域提示。 |
+| `DISCIPLINE_FIELDS` | OpenAlex Field ID、标签或 URL；多个值建议用分号分隔，并会映射到 OpenAlex / WoS 学科限定。 |
+| `TARGET_MIN` / `TARGET_MAX` | 目标结果数量范围。 |
+| `MAX_ITERATIONS` | 最大查询调整轮数。 |
+| `EXPAND_CITATIONS` | 是否启用 OpenAlex 引用扩展，默认 `true`。 |
+| `FETCH_ABSTRACTS` | 是否尝试从外部 DOI 元数据补摘要，默认 `false`。 |
+| `CITATION_SEED_COUNT` | 引用扩展 seed 论文数量。 |
+| `CITATION_PER_SEED` | 每个 seed 抓取的引用邻居数量。 |
+| `CITATION_MAX_RECORDS` | 引用扩展候选上限。 |
+| `RANKING_BATCH_SIZE` | LLM 排序批大小，默认 `8`；候选数较多时会自适应放大以减少批次数。 |
+| `RANKING_CONCURRENCY` | LLM 排序并发数，默认 `4`；单个批次失败不会使整个检索失败。 |
+| `LLM_TIMEOUT_SECONDS` | 单次 LLM 请求超时秒数，默认 `180`，最小 `30`。 |
+| `PAPERSEEK_HISTORY_ENABLED` | 是否启用本地历史记录，默认 `true`。 |
+| `PAPERSEEK_TIMEZONE` | 本地历史记录时间戳时区，默认 `Asia/Shanghai`；Web UI 会优先使用浏览器检测到的时区。 |
+| `PAPERSEEK_DATA_DIR` | 本地数据目录，默认 `~/.paperseek`。 |
+| `PAPERSEEK_HISTORY_DB` | 本地历史 SQLite 数据库路径，默认 `~/.paperseek/paperseek.db`。 |
+
+## API 获取方式
+
+### OpenAlex
+
+OpenAlex 可匿名访问，但推荐配置免费 API Key：
+
+1. 打开 [OpenAlex](https://openalex.org/) 并注册账号。
+2. 进入 [OpenAlex API settings](https://openalex.org/settings/api)。
+3. 复制 API Key。
+4. 在 Web UI 填写 `OpenAlex API Key`，或设置 `OPENALEX_API_KEY`。
+
+### Crossref
+
+Crossref REST API 通常不需要 API Key。建议设置邮箱进入 polite pool：
+
+```bash
+export CROSSREF_EMAIL=you@example.org
+```
+
+如果需要更高限额、优先支持或生产级 SLA，可以了解 Crossref Metadata Plus。PaperSeek 使用 Crossref 公共/Polite REST API 路径。
+
+### Web of Science Starter API
+
+WoS Starter 需要在 Clarivate Developer Portal 申请，通常适合已有机构订阅权限的用户：
+
+1. 打开 [Clarivate Developer Portal 注册页](https://developer.clarivate.com/signup)，点击 `Register`。
+2. 建议使用机构邮箱注册，并尽量与 Web of Science 数据库账号一致。
+3. 登录后进入 [Applications](https://developer.clarivate.com/applications)，点击 `Register Application`。
+4. 填写应用信息：
+   - `Application ID` 使用数字、小写字母、`-` 或 `_`。
+   - `Application Name` 可写为机构或项目名称。
+   - `Application Description` 可说明用于 Web of Science API 检索。
+   - `Client Type` 保持默认 `Public: Single Page Application`。
+   - 不勾选 OAuth2.0 Flows。
+5. 打开 [Web of Science Starter API](https://developer.clarivate.com/apis/wos-starter) 页面。
+6. 找到刚注册的 Application，点击 `Subscribe`。
+7. 按身份和机构权限选择计划。机构成员通常选择 Institutional Member 相关计划。
+8. 看到 `Subscription approval is pending` 后等待审批。机构申请通常需要数个工作日。
+9. 获得 API Key 后，在 Web UI 填写 `WoS API Key`，或设置 `WOS_API_KEY`。
+
+WoS Starter 的权限、每日请求量和返回字段取决于订阅计划与机构授权。若遇到 HTTP 401，先检查是否使用 `https://` 和正确 key；若遇到 Clarivate 返回的非标准 HTTP 512，应优先检查 Clarivate 服务状态、订阅审批和检索式兼容性。
+
+## Python API 与 core
+
+社区版安装包已经内置可复用核心模块 `paperseek_core`，不需要额外安装单独的 `paperseek-core` 仓库依赖。常规用户和下游代码建议从 `paperseek` 导入稳定入口：
+
+```python
+from paperseek import PaperSeekAgent
+```
+
+`LiteratureSearchAgent` 和 `WosSearchAgent` 仍保留为兼容旧代码的别名，新代码请使用 `PaperSeekAgent`。
+
+## Agent Skill
+
+仓库包含一个可选的 PaperSeek Skill：
+
+```text
+skills/paperseek/
+```
+
+它用于指导支持 Skill 的 AI agent 正确调用 PaperSeek，包括数据源选择、配置诊断、JSON 结果解析和引用图边界。Skill 使用 progressive disclosure：`SKILL.md` 保持简短，详细命令契约放在 `references/`。
+
+这个 Skill **不会随 Python 包自动安装**。如果需要在 agent 平台中使用，可以手动复制或链接 `skills/paperseek/` 到对应平台的 Skill 目录。
+
+Skill 中的 launcher 与自包含 runtime：
+
+```text
+skills/paperseek/scripts/paperseek.py
+skills/paperseek/scripts/paperseek_skill_runtime.py
+```
+
+单独发布 Skill 时，复制 `skills/paperseek/` 即可。`paperseek.py` 会优先调用完整 PaperSeek 包；如果未安装包，会回退到 `paperseek_skill_runtime.py`，使用 Python 标准库直接完成 OpenAlex、Crossref 和带 key 的 WoS Starter 核心文献检索。Web UI、引用图和完整历史管理仍需要安装完整包。
+
+## 项目状态
+
+PaperSeek 当前处于 alpha 阶段。CLI、Web UI、OpenAlex、Crossref、引用扩展、CSV 导出和 Skill 基本可用，但仍建议对正式研究结论进行人工复核。
+
+欢迎贡献：
+
+- 新数据源适配器。
+- 更稳健的查询生成与排序提示词。
+- 更好的引用图交互。
+- Web API、CLI、provider parsing 和导出行为测试。
+- 文档、示例和错误诊断改进。
+
+贡献前可阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。安全问题请参考 [SECURITY.md](SECURITY.md)。
+
+## 致谢
+
+PaperSeek 的设计和实现参考了以下开源项目：
+
+- [dr-dumpling/paper-search-cli](https://github.com/dr-dumpling/paper-search-cli/)：参考 CLI 使用方式与文献检索工作流设计。
+- [666ghj/MiroFish](https://github.com/666ghj/MiroFish)：参考 Web 前端界面的左右分栏和工作流展示风格。
+- [clarivate/wosstarter_python_client](https://github.com/clarivate/wosstarter_python_client)：参考 Web of Science Starter API 的客户端调用方式。
+- [Lloyd-Jahn/openclaw-paper-search](https://github.com/Lloyd-Jahn/openclaw-paper-search)：参考文献搜索工具的组织方式。
+
+## 开源协议
+
+PaperSeek 使用 [Apache License 2.0](LICENSE) 开源。