项目简介
本地论文查阅修改助手是一个面向 Linux 的轻量级论文辅助 CLI Agent。用户输入问题后，模型可以调用本地工具和论文检索能力，帮助阅读、总结和分析本地论文内容。
项目默认使用 Qwen3-14B-AWQ，模型权重约为 9.4 GB。它适合拥有 NVIDIA GPU、希望在本地运行模型并保护论文和提问隐私的用户。默认情况下，项目不启用联网搜索，回答主要来自模型自身能力以及用户建立的本地知识库。
项目支持 MCP 协议，可以通过工具注册机制接入 MCP 服务。由于输入预算、系统提示词和工具输出长度都可以配置，因此它的用途不局限于论文辅助。
主要特性
- 在 Linux 环境中运行本地论文辅助 Agent。
- 默认使用 Qwen3-14B-AWQ 本地模型。
- 支持将文本型 PDF、Markdown 和 TXT 文件建立为本地检索知识库。
- 支持交互式提问，也支持通过命令行执行单次问题。
- 支持保存 Markdown 格式的问题和答案记录。
- 支持 MCP 协议和工具注册机制。
- 支持可选的 LangGraph 会话检查点，用于跨窗口继续会话。
- 提供环境、GPU 和模型配置检查脚本。
安装前准备
项目面向 Linux，并建议使用带有 NVIDIA GPU 的机器。模型权重约为 9.4 GB，实际运行时还需要为模型推理预留足够显存。调整模型、输入预算或输出长度时，也应结合显存容量进行评估。
扫描版 PDF 当前不支持 OCR。如果需要检索扫描论文，应先将内容转换为文本，或使用项目支持的文本型 PDF、Markdown、TXT 文件。
下载并安装项目
首先克隆 GitHub 仓库，并将项目目录命名为 local-agent：
git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agent如果不使用 Git，也可以在 GitHub 页面选择 Code → Download ZIP，解压后在项目目录打开终端。
进入项目目录后执行安装脚本：
bash scripts/install.sh安装完成后，运行启动脚本：
bash scripts/start.sh首次启动时需要等待模型加载。当终端出现 >>> 提示符后，即可输入问题。例如：
>>> 请解释残差连接解决了什么问题以后进入项目目录后，通常只需要运行 bash scripts/start.sh 即可启动。
首次运行与模型配置
如果模型目录不完整，或者需要重新选择模型，可以执行：
bash scripts/setup.sh当模型下载失败时，应先检查网络。也可以在具备网络的机器上下载完整模型目录，再复制到目标机器，并在配置过程中选择已有模型。
如果模型启动失败，可以查看终端提示的日志文件，日志通常位于：
logs/cli-vllm-*.log同时确认 GPU 显存没有被其他程序占用。
导入自己的论文并建立索引
要让 Agent 根据自己的论文回答问题，请将文本型 PDF、Markdown 或 TXT 文件放入 data/knowledge/ 目录。例如，目录可以包含多篇论文和相关笔记。
文件准备好后，执行知识库索引命令：
bash scripts/start.sh rag-index第一次建立索引时会下载独立的检索模型，因此需要网络连接。索引完成后重新启动交互式 Agent：
bash scripts/start.sh此时可以提出依赖本地论文的问题，例如：
根据本地论文总结 YOLOv1 的核心创新，列出来源。如果没有放入论文或没有建立索引，回答将主要来自模型自身知识，而不是本地论文内容。项目默认不启用联网搜索。
交互式使用
启动后，在 >>> 提示符后输入问题并回车即可。适合连续追问、比较论文观点或逐步分析同一主题。
可以使用以下内置命令管理交互过程：
/help：查看对话命令。/new：开始新会话。/exit、/quit或Ctrl+D：退出程序。
每轮问题和答案默认保存为 Markdown 文件，路径格式为：
output/月/日/时间_微秒.md使用命令行执行单次任务
如果不需要进入交互式界面，可以直接将问题作为启动脚本的参数：
bash scripts/start.sh "总结注意力机制"使用 --quiet 可以只输出答案：
bash scripts/start.sh "总结注意力机制" --quiet如果不希望保存答案文件，可以添加 --no-save：
bash scripts/start.sh "问题" --no-save配置输入预算、输出长度与提示词
Agent 的输入预算和系统提示词可以在 config/agent.yaml 中修改，因此项目也可以用于其他本地 Agent 场景。
需要特别区分两个参数：配置文件中的 tool_output_max_chars: 4000 是工具结果的字符截断上限，并不是模型答案的 token 上限。模型最大输出长度由环境文件中的 LOCAL_AGENT_MAX_TOKENS 控制，.env.example 默认设置为 2048 token。
Agent 输入预算默认是 4096 token。调整输入预算、系统提示词、工具输出长度或最大输出 token 时，应综合考虑上下文长度和可用显存，避免配置过高导致模型无法正常运行。
跨窗口保存和恢复会话
默认情况下，会话上下文只保存在当前进程中。关闭 CLI 后，程序不会自动恢复上下文，已经生成的 Markdown 答案文件也不会自动读回。
如果需要跨窗口继续同一个会话，可以在 config/agent.yaml 中将 run.checkpoint_enabled 改为 true，并始终使用同一个会话 ID：
bash scripts/start.sh -i --thread-id my-paper会话状态会保存到：
data/checkpoints/langgraph.sqlite输入 /new，或者启动新的交互窗口时不指定会话 ID，都会创建新会话。每次模型调用默认使用最近 4 轮对话，并且仍然受到 4096 token 输入预算限制。
环境检查与故障排查
遇到问题时，建议先运行环境检查脚本：
bash scripts/doctor.sh该脚本会检查环境、GPU 和模型配置，但不会加载大模型，也不会开始推理，因此适合在正式启动前或故障排查时使用。
- 没有 GPU：建议使用带有 NVIDIA GPU 的 Linux 机器。
- 模型目录不完整：运行
bash scripts/setup.sh，重新选择模型或继续下载。 - 模型下载失败：检查网络，或在有网络的机器上下载完整模型目录后复制到目标环境。
- 模型启动失败：查看
logs/cli-vllm-*.log，并确认显存没有被其他程序占用。 - 本地论文没有被使用：确认文件位于
data/knowledge/，且已经执行bash scripts/start.sh rag-index。
实用使用建议
- 首次使用前先运行
bash scripts/doctor.sh，尽早发现 GPU、模型目录或配置问题。 - 将需要引用和分析的论文集中放入
data/knowledge/，完成索引后再提问。 - 提问时明确要求总结范围、输出格式或列出来源，以便更容易核对本地论文内容。
- 如果显存不足，不要盲目增大输入预算、工具输出上限或最大输出 token。
- 需要连续处理同一研究主题时，启用检查点并固定
--thread-id。 - 扫描版 PDF 不能直接依赖当前项目进行 OCR，应先准备可检索的文本内容。
总结
paperchecker 提供了一套从本地模型启动、论文索引到 CLI 问答的完整流程。安装项目后，可以使用默认模型进行一般问题分析，也可以把自己的文本型论文放入知识库并建立索引，让 Agent 基于本地资料回答问题。通过 agent.yaml、环境变量和会话检查点，还可以进一步调整上下文、输出和会话管理方式。
项目代码采用 MIT 许可证。使用过程中如遇到启动或模型问题，优先运行诊断脚本并检查日志。