transport-lit — 基于 MCP 的交通灰色文献

（于 2026-08-27 由 dot-lit 更名而来；DOT_LIT_* 环境变量和旧数据目录仍会被识别。）

transport-lit 为 AI 助手（Claude Desktop、Claude Code、任意 MCP 客户端）提供对交通研究报告的关键词搜索，这些报告是 PubMed 未收录、Semantic Scholar 覆盖不佳的。它始于 ROSA-P——美国国家交通图书馆的仓库（NHTSA DOT HS 报告、FHWA/FRA/FTA/FAA、UTC 和州 DOT 研究；https://rosap.ntl.bts.gov），现在采集三大洲的六个 OAI-PMH 来源，以及你从 TRID 导出的任何内容：

transport-lit sources 列出它们；transport-lit harvest --source <key>|all 采集它们；search_reports 中的 collection 过滤器选择一个（例如 "VTI"、"BASt"、"World Bank"、"CEPAL"、"TRID"）。添加另一个 OAI-PMH 仓库只需在 src/transport_lit/sources.py 中增加一条记录。

我创建这个项目是为了我个人的学术和研究用途， 也很乐意与任何觉得它有用的人分享。我欢迎关于错误、集成需求、改进和其他评论的反馈。 我会定期查看这些反馈，并尽可能整合，同时记录这些整合。 如果你有兴趣帮助支持这个项目，或者对它还有其他想法，我也欢迎！ — Alex Quistberg （提交 issue）

它采用对 OAI-PMH 源唯一可行的方法：将整个 仓库的元数据采集到本地 SQLite 数据库，在此基础上构建 FTS5 全文索引， 并基于该索引提供搜索。除可选的 PDF 全文抓取外，不会实时查询任何内容。重新采集是增量的（OAI 请求中的 from=），且成本很低。

工具接口

另外还有一个提示词 literature_scan(topic)，它引导模型进行带引用的多查询扫描。每个工具都带有 MCP 注解（readOnlyHint、idempotentHint；只有 get_fulltext 是 openWorldHint，因为它可能抓取一个 PDF）。

id 接受 dot:93144、93144、oai:dot.stacks:dot:93144 或落地 URL。导入的记录使用其他前缀（trid:813520、import:…）。

查询语法：裸词先按 AND 组合；如果匹配所有词的命中数少于 limit，剩余位置将由任意词匹配填充（match_mode = all_terms / any_terms）。用引号表示短语（"driver improvement"），用尾随 * 表示前缀。排序采用 BM25，标题、报告编号和作者的权重高于摘要。

Related MCP server: Personal Research Assistant MCP

设置

需要 Python 3.12+ 和 uv。

git clone https://github.com/aquistbe/transport-lit && cd transport-lit
uv tool install .            # installs `transport-lit` (CLI) and `transport-lit-mcp` (server) on PATH
export TRANSPORT_LIT_CONTACT=you@example.org   # identifies your harvester to ROSA-P (put it in your shell profile)
transport-lit probe                # live check: Identify / ListMetadataFormats / ListSets
transport-lit harvest              # full harvest the first time (~15 min), incremental afterwards
transport-lit status               # counts, last run, coverage by year
transport-lit search driver improvement program evaluation

开发时使用 uv sync，并在命令前加上 uv run（例如 uv run pytest）。

任意 MCP 客户端、任意模型

服务器通过 stdio（默认）和 Streamable HTTP / SSE 提供标准 MCP 服务（transport-lit-mcp --transport streamable-http --port 8765，端点 /mcp）。transport-lit mcp-config [client] 会为以下客户端打印可直接粘贴的配置片段：Claude Desktop、Claude Code、Cursor、VS Code（Copilot 代理模式）、Zed、Continue、LM Studio、Goose、Open WebUI 和 LibreChat（后两者通过 HTTP）。Dockerfile 可构建一个 HTTP 服务器镜像，索引放在卷上。

开放模型。 已于 2026-08-26 使用 Ollama qwen2.5:3b（3 B 参数）通过 tests/ollama_smoke.py 进行了端到端测试：在给出“查找关于驾驶员改善计划的报告；列出 3 个标题及其年份和 id”后，模型调用了一次 search_reports({"query": "driver improvement", "limit": 3})，并给出了来自三个来源的正确标题、年份、id 和落地 URL。让小型模型能够工作的设计选择：十个工具，描述以一行开头；扁平的 JSON 参数并带默认值；紧凑的命中对象（搜索结果中不包含原始元数据）；以及一个服务器 instructions 字符串，用于指明来源和过滤器。使用任何支持工具调用的模型运行冒烟测试：OLLAMA_MODEL=llama3.1 uv run python tests/ollama_smoke.py "…"。

在 Claude Desktop 中注册

transport-lit install-claude-desktop          # prints the JSON to add
transport-lit install-claude-desktop --write  # merges it into claude_desktop_config.json (keeps a .bak)

它写入的条目很简单：

{ "mcpServers": { "transport-lit": { "command": "/Users/you/.local/bin/transport-lit-mcp", "args": [],
                               "env": { "TRANSPORT_LIT_DATA_DIR": "/Users/you/.local/share/transport-lit",
                                        "TRANSPORT_LIT_CONTACT": "you@example.org" } } } }

之后重启 Claude Desktop。对于 Claude Code：claude mcp add transport-lit -- transport-lit-mcp。

配置（环境变量）

变量也可以放在 ~/.config/transport-lit/env 中，以 KEY=VALUE 行的形式（真实的环境变量优先）；NII 应用程序 ID 或 NCBI 密钥就应该放在那里，这样 launchd 任务、MCP 服务器和手动运行都能看到它。不需要任何凭据；所有端点都是公开的。

从 PyPI 安装（无需克隆）

uv tool install transport-lit            # CLI + MCP server on PATH
uvx --from transport-lit transport-lit-mcp   # or run the server ad hoc
uv tool install "transport-lit[semantic]"    # with the bundled embedding backend

通过 GitHub 的 trusted publishing 发布在 https://pypi.org/project/transport-lit/：打标签会运行 release.yml（构建、GitHub release），然后它再派发 publish.yml——即注册为 trusted publisher 的那个工作流——上传在 pypi 环境上等待维护者批准。PyPI 会拒绝来自可复用工作流的令牌，并且匹配的是顶层工作流文件，这就是为什么发布是一个单独派发的工作流，而不是 release 内部的一个 job。server.json 是 MCP Registry（registry.modelcontextprotocol.io）的清单，在 PyPI 包存在之后提交。

固定版本

发布版本是 git 标签 vMAJOR.MINOR.PATCH（语义化版本：patch = 修复，minor = 新工具/新来源，major = 对工具表面或数据库 schema 的破坏性变更）。每个标签都会触发 release 工作流，它运行测试、构建 wheel + sdist 并附加到 GitHub Release。Python 依赖由提交的 uv.lock 固定；CI 使用 uv sync --frozen 安装，因此发布总是针对测试过的确切版本运行。要安装特定版本：

uv tool install "transport-lit==0.3.0"                            # a pinned PyPI release
uv tool install git+https://github.com/aquistbe/transport-lit@v0.3.0  # or the matching git tag
uv tool upgrade transport-lit                                     # move to the latest release

采集

transport-lit harvest                     # ROSA-P; auto: incremental if a complete full harvest exists, else full
transport-lit harvest --source all        # every configured source (vti, bast, wbokr, ipea, cepal, rosap)
transport-lit harvest --mode full         # walk the whole repository again
transport-lit harvest --mode incremental  # from = start of last complete run − 1 h, until = now
transport-lit harvest --from 2026-08-01T00:00:00Z   # explicit window (full timestamp required)
transport-lit harvest --max-pages 3       # testing only; the run is recorded as failed/partial
transport-lit reindex                     # re-parse the cached raw pages (no network) after a parser change

采集器做什么以及为什么（所有行为已于 2026-08-26 对照 ROSA-P 验证）：

• ListRecords&metadataPrefix=oai_dc，每页 100 条记录，跟随 resumptionToken 直到某一页没有它为止。只有到那时运行才会被标记为 complete；任何错误都会使其保持 failed 并且不会推进“上次采集”指针，因此 harvest_status 永远不会声称部分索引是完整的。

• 节奏控制： 每 TRANSPORT_LIT_MIN_INTERVAL 秒一个请求（默认 1 秒）。令牌在发出后约 60 秒过期，因此重试使用短退避（2/4/6 秒）。

• badResumptionToken、传输错误、截断的 XML，或令牌仍有效时收到空信封 → 重新发起列表请求。ROSA-P 不按稳定的 datestamp 顺序返回记录（每页都检查过），因此恢复会从顶部重新开始列表；upsert 使其幂等。如果排序是单调的，采集器就会改为通过 until= 从看到的最小 datestamp 继续。每次运行最多 8 次恢复，之后标记为 failed。

• noRecordsMatch： ROSA-P 不发送该错误码；空的选择性采集会以没有 <ListRecords> 元素的 OAI-PMH 信封形式返回。只有在没有令牌在起作用时才将其映射为“无事可做”；在列表中途则视为截断。

• 静默截断检查： 每页都将令牌的 cursor 与本地计数进行比较；完整采集返回的记录比上一次完整采集少 >5% 时，会在运行说明中标记。两者都会出现在 harvest_status().last_harvest.notes 中。

• 删除： 仓库报告 deletedRecord=no，因此本地永远不会删除任何内容；从 ROSA-P 消失的记录会留在索引中，直到对全新的 TRANSPORT_LIT_DATA_DIR 进行完整重新采集。

• 缓存： 每个 OAI 页面都以 gzip 形式存储在 raw/run<N>-p<page>.xml.gz 下，因此可以更改解析器并重建索引而无需访问网络；PDF 及其提取的文本缓存在 pdf/ 下和 fulltext 表中。

• from/until 按照每个仓库声明的 granularity（从 Identify 读取）格式化：ROSA-P、DiVA 和 DSpace 接受完整的 YYYY-MM-DDThh:mm:ssZ 时间戳，OPUS (BASt) 只接受 YYYY-MM-DD，并且窗口每边各放宽一天。

• 宽泛仓库（World Bank、IPEA、CEPAL）在采集时通过多语言交通词汇表（sources.TRANSPORT_RE，en/es/pt/de/fr/sv）过滤：如果某个术语出现在标题中，或者（IPEA、CEPAL）如果主题词中出现两个不同的术语，则保留该记录。摘要被忽略——发展类文献会顺带提到道路和港口——World Bank 的主题也被忽略（每条记录 100+ 个主题词）。这是在 2026-08-26 针对随机 20 条标题样本调优的：宽松的标题+主题+摘要规则保留了 15,271 条 World Bank 记录，精确率约为 35–50%；最终规则保留 976 条，精确率 18/20，IPEA 207 条，约 16/20，CEPAL 1,165 条，约 15/20。召回率是代价；如果你想要另一种权衡，就放宽 sources.py 中的 min_subject_hits 并运行 transport-lit reindex --source <key>（无需网络）。运行说明会记录保留与跳过的数量。

• transport-lit doctor [--repair] 检查 SQLite 完整性、两个 FTS 索引、卡在 running 状态的运行、不可能的时间戳和 WAL 大小，并修复可安全修复的部分；存储还会在关闭时对 WAL 做 checkpoint。transport-lit cite prefetch [--source …] 批量（每请求 50 条）将每条带 DOI/PMID/OpenAlex 的记录解析为其 OpenAlex work，从而无需逐条调用即可知道它们的 cited_by_count。

transport-lit reindex --source <key> 重新解析缓存的页面并修剪当前解析器/过滤器不再保留的记录，因此过滤器变更永远不需要重新采集。

每月重建和每周更新（维护计划）

语料库变化缓慢，因此节奏是：每周增量采集和每月全新重建。harvest --fresh 完整采集到临时存储中，然后原子地替换活动索引中的 dot: 记录——这是 ROSA-P 停止提供的记录消失的唯一方式（其 OAI-PMH 端点不跟踪删除）。导入的来源（TRID 导出）不受影响，失败的重建不会改变任何东西。

transport-lit install-schedule          # shows the two launchd agents
transport-lit install-schedule --write  # installs them: Mon 06:00 `--source all` incremental, 1st 05:00 `--source all --fresh`

日志存放在 $TRANSPORT_LIT_DATA_DIR/logs/。在 Linux 上使用命令打印出的 cron 行。

每月维护清单（与重建一起完成）：阅读新的 GitHub issues；uv lock --upgrade && uv run pytest；在 release 的 changelog 部分记录修复；在 pyproject.toml 和 src/transport_lit/__init__.py 中提升 version；git tag vX.Y.Z && git push --tags。

TRID：导入你导出的内容

TRID（https://trid.trb.org）是最完整的交通文献目录，也是 ROSA-P 的自然补充，但它没有 API，其 FAQ 说 TRB“不授予对 TRID 后端系统的访问权限，也不解除导出/下载限制”，并且其 robots.txt 禁止 AI 爬虫。每个用户可以做的是搜索和导出。所以：

1. 在 TRID 中运行你的搜索，选择 Export → RIS（也提供 CSV 和 XML）。

2. transport-lit import ~/Downloads/trid-driver-improvement.ris --collection "TRID: driver improvement"

记录从 TRID 视图 URL 获得 id trid:<accession>，进入 TRID 集合（search_reports(..., collection="TRID")），重新导入同一文件是幂等的。导入器是通用的 RIS，因此 Zotero/EndNote/Scopus 导出用 --source <prefix> 也能以相同方式工作。对导入记录调用 get_fulltext 只跟随直接的 .pdf 链接；否则请使用 landing_url。

ROSA-P 的 OAI-PMH 端点提供什么

https://rosap.ntl.bts.gov/fedora/oai — 仓库“DOT Stacks”（CDC Stacks 平台），协议 2.0，最早 datestamp 2008-07-02，无删除跟踪，无 OAI 集合（ListSets 为空），并且 oai_dc 是唯一的元数据格式。不过它实际上是限定的 Dublin Core：dc:contributor.author、dc:description.abstract、dc:relation.isPartOf、dc:identifier.uri（DOI 和报告编号，例如 DOT HS 813 827）、dc:coverage.spatial、dc:title.alternative 和 dc:description.tableOfContents 等元素都存在。解析器（dc.py）保留每个原始字段并从中派生类型化列。dc:relation.isPartOf（分号分隔）正是 list_collections / collection 过滤器所使用的。

PDF 链接不在元数据中；get_fulltext 从落地页读取 citation_pdf_url，并回退到 datastream 约定 /view/dot/{n}/dot_{n}_DS1.pdf。

验证（2026-08-26）

v0.4.0 语义搜索。 342,462 个向量（fastembed 多语言 MiniLM-L12，384 维，8 核上数据并行 94 条记录/秒——整个语料库 60 分钟）。跨语言检查：semantic 模式下的 "elderly pedestrian crashes at night" 在其前 8 个结果中，除了 PubMed 和英文 CiNii 条目外，还返回了三份日文 CiNii 报告（夜間 高齢歩行者 死亡事故 分析，1995–2011）；词汇检查："point system for problem drivers license suspension recidivism" 找到了 ROSA-P 的 1997 年加州车辆扣押评估和 1986 年行政吊销报告，它们与查询词没有任何重叠。混合延迟 ≈ 0.6 秒（查询编码占主导），关键词 ≈ 25 毫秒。这里记录一个操作教训以免有人重蹈覆辙：当另一个进程（例如正在运行的 MCP 服务器）打开着数据库时，绝不要删除 SQLite 的 -wal 文件——它保存着尚未 checkpoint 的已提交数据。

v0.3.0 API 数据源。 OpenAlex：58 页，11,448 份报告（10 个主题，type:report），1,428 份带有 PDF 链接。CiNii：730 页，20 个查询共 144,348 次命中，118,609 条唯一记录。PubMed：17 个日期切片中的 105,028 篇文章（E-utilities 将 retstart 上限设为 10,000，因此切片是递归查找的）。开放模型检查：Ollama qwen2.5:3b 用一次正确的 search_reports 调用回答了一个驾驶员改善问题。

v0.2.0 多源采集。 VTI：120 页，11,944 条已见，11,460 条唯一（DiVA 会在多个集合中提供某些记录），0 个恢复令牌。BASt：30 页，2,987 条已见，2,970 条唯一；1,901 条带有直接 PDF 链接；执行了按天粒度的增量路径（24 条记录）。World Bank：404 页 / 40,332 条已见；IPEA：144 / 14,400；CEPAL：522 / 52,199——全部结束于一个无令牌页面，0 个恢复令牌；过滤后的计数见上。定点搜索：Fußgänger Unfall（BASt）→ 碰撞重建和乡村道路碰撞统计；acidentes de trânsito mortalidade（IPEA）→ "Mortalidade por acidentes de transporte terrestre e desigualdades interestaduais no Brasil"；seguridad vial peatones（CEPAL）→ 道路安全治理和活动评估；pedestrian safety（VTI）→ 1990 年代儿童行人培训研究。

v0.1.0（首次 ROSA-P 采集）

采集完整性。 第 1 次运行（full）在 15 分钟内遍历了 908 页 / 90,706 条记录（00:03:59–00:19:11 UTC），0 个恢复令牌，0 次游标不匹配，并结束于一个包含 6 条记录且没有恢复令牌的页面——这是 OAI-PMH 对完整列表的定义。存储中有 90,603 条唯一记录；103 条记录的差距是同一记录出现在两个页面上，这是因为 ROSA-P 不会以稳定顺序返回记录（采集器会记录此情况："datestamp ordering violated on page 2"）。30 分钟后的第二次独立完整遍历，进入一个单独的目录，返回了完全相同的数字——908 页、90,706 条已见、90,603 条唯一——并且两个 ID 集合完全相同（任一遍都没有独有的记录）。这 103 次重复是存储库在两个页面上提供同一条记录，而不是记录被跳过。

按年代统计的覆盖率（74,448 条记录有年份，占 82 %；其余 16,155 条在任何元数据字段中都没有日期；year_source 表示年份来自 dc:date（48,658）、纯年份描述行（22,205）还是标题（3,585））：

已知条目检索（transport-lit search …，除非另有说明，否则排名第 1）：

真实查询 driver improvement program evaluation negligent operator（前 6 条，共 10 条）：

1. dot:18905 — 弗吉尼亚驾驶员改善计划短期效果评估（Lynn）— all_terms

2. dot:29326 — 新泽西记分制度回顾（Carnegie、Ozbay、Mudigonda，2013；FHWA NJ-2013-004）— all_terms

3. dot:18959 — ……弗吉尼亚驾驶员改善计划对疏忽驾驶的影响：12 个月报告（Lynn）

4. dot:18969 — ……弗吉尼亚驾驶员改善计划对疏忽驾驶的影响：24 个月报告（Lynn）

5. dot:17678 — 新泽西 MVC 行政处罚驾驶员再犯率研究（Carnegie 等，2009）

6. dot:17677 — 辩诉交易对机动车违法行为影响的研究（Carnegie 等，2009）

全文提取在 dot:93144（DOT HS 813 827，3.7 MB PDF，通过 citation_pdf_url 解析）上进行了检查。单元测试：uv run pytest（两种元数据配置文件的解析器、年份回退、FTS 搜索/过滤、upsert 幂等性、查询分词器、ID 规范化）。

布局

src/transport_lit/
  config.py    paths, User-Agent, pacing, limits (env-overridable)
  oai.py       rate-limited OAI-PMH client; typed errors; raw-page cache
  dc.py        oai_dc record -> typed dict (authors, year, DOI, report numbers, collections …)
  store.py     SQLite schema, FTS5 index + triggers, search, stats, harvest-run bookkeeping
  harvest.py   full / incremental harvest with completeness + truncation handling
  fulltext.py  PDF resolution, download (size-capped), pypdf extraction, cache
  server.py    MCP tools (FastMCP / MCPServer)
  importers.py RIS import (TRID exports and any other reference-manager export)
  cli.py       transport-lit probe | harvest [--fresh] | import | reindex | status | search | get | fulltext
               | install-claude-desktop | install-schedule
.github/workflows/  ci.yml (tests on push/PR), release.yml (wheel + GitHub Release on tag)
tests/         unit tests (parser, store, query tokenizer)

后续添加第二个数据源（例如 NHTSA crashstats）

存储是数据源无关的：records.id 是一个带前缀的字符串（目前是 dot:93144），harvest_runs.source 记录哪个采集器写入了运行，FTS 索引不关心行的来源。要添加一个数据源：

1. 编写 src/transport_lit/sources/<name>.py，暴露 harvest(store, *, mode, progress)，它生成与 dc.parse_record 产生的相同形状的字典（id、title、authors、year、abstract、report_numbers、doi、landing_url、collections、raw、……），并调用 store.upsert_records()。使用新的 id 前缀（nhtsa:812115），并将你自己的 source 名称传递给 store.start_run()，以便 harvest_status 可以单独报告它。

2. 复用 oai.RateLimiter 和 config.USER_AGENT 以保持礼节；将原始响应存储在 raw/<source>/ 下以保证可重现性。

3. 为 harvest.status() 提供一个按数据源划分的块（按 id 前缀计数）。

4. 为 transport-lit harvest 添加一个 --source 选项，并且如果数据源有自己的分面，则在 search_reports 上添加相应的过滤器。

5. 按 DOI / 报告编号（records.doi、records.report_numbers）与 ROSA-P 去重，而不是按标题——NHTSA 报告通常同时出现在两个地方。

NHTSA crashstats 数据源的已验证事实，以免有人重新推导：https://crashstats.nhtsa.dot.gov/Api/Public/Publication/{id} 直接返回 PDF（812115 → NMVCCS 关键原因报告，application/pdf，约 0.5 MB）。它是一个文档检索端点，而不是搜索或列表 API，因此连接器将需要一种枚举策略（例如 ROSA-P report_numbers 中已有的 DOT HS 编号），而不是爬取。

美国以外：已评估的候选数据源（2026-08-26）

进行了实时探测，以了解 (a) 馆藏是 文献 而非数据集，以及 (b) 是否存在适合此采集器的机器访问。计数是端点当天报告的数字。

按地区（当日探测；"open" 表示已确认未认证机器访问）：

具有 completeListSize 的三个 OAI-PMH 仓库（VTI、BASt、World Bank OKR）适合现有收割器，带有源前缀和每个源的 metadataPrefix；DSpace 7 站点也容忍 from/until 并返回正确的 noRecordsMatch，因此 oai.py 中的 ROSA-P 怪癖已经是更难的情况。

TRID 不在范围内

TRID（https://trid.trb.org）没有公共 API、没有 OAI-PMH 端点，也没有批量导出。其 FAQ 声明："TRB 不授予对 TRID 后端系统的访问权限，也不会为个人或组织解除导出/下载限制"，并且该数据库不得用于训练 LLM。这里特意不对其进行爬取。

v2 顺序（2026-08-26 商定）

1. VTI + BASt（已完成，v0.2.0）— 2. World Bank OKR, IPEA, CEPAL（已完成，v0.2.0）—

2. IRDB 日本 — 4. OpenAlex type:report 作为全球兜底 — 5. 一个 PubMed 交通 子集（见下文）。VTI 说明：DiVA 的 oai_dc 不携带全文链接；将 该源切换到 swepub_mods/mets_kb 将为 get_fulltext 提供 FULLTEXT01.pdf URL。

PubMed：一个交通/伤害子集，而非全部 PubMed

PubMed 的 E-utilities（esearch/efetch，免费，无密钥时 3 请求/秒）可以通过固定策略维护一个本地子集，并按照相同的每周/每月节奏使用 mindate/maxdate 刷新。两个互补的过滤器，用 OR 组合在一起：

• MeSH 策略 — "Accidents, Traffic"[MeSH] OR "Pedestrians"[MeSH] OR "Bicycling"[MeSH] OR "Automobile Driving"[MeSH] OR "Motorcycles"[MeSH] OR "Wounds and Injuries"[MeSH] AND ("Transportation"[MeSH] OR "Built Environment"[MeSH] OR "City Planning"[MeSH]) — 捕获一般和临床期刊中的交通论文。

• 期刊列表 — Accident Analysis & Prevention、Traffic Injury Prevention、Journal of Safety Research、Injury Prevention、Injury Epidemiology、Journal of Transport & Health、 Safety Science、Transportation Research Part F、Transport Reviews、BMC Public Health （仅限交通标签）等 — 捕获未使用 MeSH 术语索引的交通论文。

SafetyLit（safetylit.org，世界卫生组织下属的每周伤害文献公报）维护的正是这样一个期刊列表，并按主题人工分类文章，这使其成为期刊过滤器的最佳种子；其网站在 2026-08-26 检查时无法访问（每个主机名都连接被拒），因此其当前状态未确认。

每周摘要（SafetyLit 风格公报）

transport-lit digest --days 7 [--abstracts] 打印一份 Markdown 公报，列出上周进入索引的所有内容，按来源分组并带有计数。它由 first_seen_at 驱动，该字段在首次看到记录时设置，并在全新重建时保留，因此每月重建不会让整个索引看起来都是新的。whats_new 工具向模型暴露相同的数据，模型随后可以撰写摘要——这正是 SafetyLit 手工完成的编辑步骤。

与其他文献 MCP 的比较

PubMed、Semantic Scholar、OpenAlex 和 arXiv MCP 服务器将实时查询代理到一个 API。transport-lit 在三个方面有所不同：它索引聚合器缺乏的灰色文献（机构报告、州 DOT 评估、ITRD 贡献机构），它在收割后在本地索引上离线运行（查询时无速率限制、无需密钥），并且它是多来源的，采用单一 id 方案，因此模型可以一次搜索所有内容并导出引文。那些服务器拥有而本服务器尚缺的：引文图（谁引用了谁）、作者消歧，以及语义（嵌入）搜索——见下文。

引文图（v0.5）

get_references / get_citations（CLI：transport-lit cite refs|cites <id> [--in-index]）将 OpenAlex 的引文图附加到索引。记录通过其 OpenAlex id、DOI、PMID，或者——对于许多无日期、无 DOI 的机构报告——通过年份在 ±1 以内的精确规范化标题来匹配 OpenAlex 作品（结果中的 match 说明是哪种方式）。边在首次请求时获取，并缓存在 citations/works 表中；引用列表在 90 天后刷新，参考文献永不改变。本身在索引中的被引作品会返回其 record_id，搜索命中一旦已知就携带 cited_by_count。

2026-08-27 验证：俄勒冈州 DMV DIP 评估（dot:21848，无 DOI，ROSA-P 中无日期）通过标题解析，并列出 6 篇引用作品，其中包括爱荷华州的 DIP 评估和新泽西州再犯研究；Lynn 1982 年弗吉尼亚 24 个月报告被 2003 年 Cochrane 对驾照后驾驶员教育的综述引用（pubmed:12917984，在索引中）；一篇 2020 年首尔老年行人论文有 57 条参考文献，其中 19 条在索引中。OpenAlex 解析 NTL 的 10.21949/… DOI（15,493 条 ROSA-P 记录带有 DOI）；没有任何 DOI 的记录——ROSA-P 90,599 条中的 73,000 条——依赖标题匹配，该匹配接受精确规范化标题、前缀关系（版本或副标题尾部），或 ≥ 0.8 的 token 重叠，且年份始终在 ±1 以内。在索引场所中未被任何人引用的灰色文献仍将显示为零；这是引文数据的属性，而非索引的属性。OpenCitations 和 Semantic Scholar 可以作为回退添加到相同的表中。

语义搜索（v0.4）

关键词搜索是 FTS5/BM25。添加向量将 search_reports 转变为混合搜索（BM25 和余弦通过倒数排名融合），可以按含义并跨语言查找记录——英语查询可以到达瑞典语、德语、西班牙语、葡萄牙语或日语记录。一切都在本地运行；无需账户，无需 GPU。

uv tool install "transport-lit[semantic]"   # adds fastembed (ONNX runtime), ~60 MB
transport-lit embed                         # default backend: fastembed, multilingual MiniLM-L12 (384-d, 220 MB model, one-time download)
transport-lit embed --backend ollama --model qwen3-embedding:8b     # opt-in: any Ollama embedding model, truncated to 1024-d
transport-lit search "programa de mejoramiento de conductores" --mode semantic

语义结果按来源多样化：除非 source/collection 缩小搜索范围（TRANSPORT_LIT_SEMANTIC_PER_SOURCE），否则任何单一来源填充的结果不得超过所请求结果的一半。实测原因：CiNii 占索引的三分之一，并拥有数千个简短的英文标题（"Pedestrian safety problems and countermeasures"），这些标题比任何带摘要的记录都更接近短查询；有/无摘要的余弦差距仅为 ~0.01，因此这是语料库构成问题，而非长度伪影，上限是诚实的补救措施。mode="semantic" 是专家设置；hybrid 仍是默认。

混合融合将关键词列表权重设为 1.0，语义列表权重设为 0.7（TRANSPORT_LIT_SEMANTIC_WEIGHT），并且仅语义候选必须超过余弦 0.5（TRANSPORT_LIT_SEMANTIC_MIN）；这使精确查询保持精确，而 mode="semantic" 仍然是召回/跨语言设置。

embed 只处理尚无向量的记录，因此首次遍历后，每周收割只需增加几秒。向量存储在 $TRANSPORT_LIT_DATA_DIR/vectors/<backend-model>/ 中，作为内存映射的 float16 矩阵（342k × 384 ≈ 260 MB）；搜索是分块点积，无需扩展。活动向量集记录在索引中，因此 search_reports(mode=…) 使用生成它的任何后端：hybrid（默认）、keyword 或 semantic；每个结果中的 mode_used 说明实际运行的是哪种，并且在不存在向量时降级为 keyword。harvest_status() 报告后端、模型、维度和覆盖率。

后端于 2026-08-26 在一台 10 核 Apple Silicon 笔记本电脑上测量，256 条真实记录（标题 + 摘要）：fastembed MiniLM-L12 在 CPU 上约 30 条/秒（CoreML 提供程序并不更快）；Ollama qwen3-embedding:0.6b 约 20 条/秒（1024 维），qwen3-embedding:8b 约 1.4 条/秒（4096 维，截断到 1024）。因此，使用默认模型对 342k 条记录进行首次完整遍历是一次性约 3 小时；每周增量只需几秒钟。使用 --source 用更重的模型嵌入单个来源。请注意，MiniLM 模型最多读取 128 个 token（标题加上摘要的前约 90 个词）；Qwen 读取完整的 1,500 字符窗口，并在查询时获得模型的检索指令前缀。大多数用户应安装快照（见下文），完全不必运行完整遍历。

快照：跳过采集

uv tool install "transport-lit[semantic]"
transport-lit snapshot install https://github.com/aquistbe/transport-lit/releases/download/v0.4.0/transport-lit-2026-08.tar.gz
transport-lit mcp-config claude-desktop     # or install-claude-desktop --write

这可以在几分钟内完成一个完整、可搜索的安装：224k 条记录（除 CiNii 和 TRID 之外的所有内容）及向量。transport-lit snapshot build <file.tar.gz> 将 SQLite 索引和活动向量打包；snapshot install <url-or-file> 将快照解压到一个全新的 TRANSPORT_LIT_DATA_DIR 中，之后每周增量采集使其保持最新（快照携带采集簿记，因此 harvest --source all 知道从哪里继续）。快照不包含 CiNii（其 API 条款要求注册，且未说明再分发）和 TRID 导入（TRB 的条款）；用户需自行采集这些来源。发布版本在构建了快照时会附带一个快照。