journapi

标准、可扩展的学术制品元数据检索 SDK + CLI —— 首个数据源为期刊（通过公开的 ISSN Portal），提供 Provider 抽象层，为后续更多数据源（文献、DOI 等）预留扩展能力。

项目状态：alpha。ISSN Portal 公开网页接口已实现并测试；官方订阅 API（api.issn.org, REST + JWT）提供完整 Provider 骨架（需订阅凭据端到端验证）。

功能特性

• 期刊检索 — 按刊名、ISSN、eISSN、ISSN-L 搜索，返回 ISSN、ISSN-L、ISSN-H、标题、介质、国家等
• 单条记录 — 按 ISSN 精确查询，含 ISSN-L / ISSN-H、正式题名、出版频率、语言、年份等
• ISSN-L 集群 — 展开同一刊物全部介质版本（Print/Online），含频率、语言、创刊年份
• ISSN-H 家族信息 — 展示历史沿革家族标识与成员数（家族明细需订阅）
• Web UI — 内置浏览器界面，搜索 / 精确查询双模式，可视化浏览
• 中文支持 — 中文刊名自动分词转拼音检索（可选依赖）
• 礼貌抓取 — 限速（robots.txt Crawl-delay 1s）、重试退避、可选缓存
• Provider 抽象 — 注册式多数据源，官方订阅 API 自动降级到公开源
• CLI + JSON — 表格或 JSON 输出，方便脚本与 Agent 集成

架构概览

           +------------------------------------+
           |          Public API 层             |
           |   ArtifactSearchClient (门面)      |
           +----------------+-------------------+
                            |
          +-----------------+-----------------+
          |                 |                 |
          v                 v                 v
   +------------+   +------------+   +------------+
   |  issn_portal|   |issn_portal_|   |  第三方    |
   |   (公开网页)|   |  api(订阅) |   |  Provider  |
   +------+-----+   +------+-----+   +------+-----+
          |                 |                 |
          +-----------------+-----------------+
                            |
                            v
          +------------------------------------+
          |         Provider 抽象层            |
          |   ArtifactProvider (ABC)          |
          +----------------+-------------------+
                            |
                            v
          +------------------------------------+
          |         基础设施层                 |
          |  HTTP 客户端 | 限速 | 重试 | 缓存  |
          +------------------------------------+
                            |
                            v
          +------------------------------------+
          |         应用层                     |
          |  CLI (search/get/cluster/web)      |
          |  Web UI (内置浏览器界面)           |
          |  Agent Skill (AI 助手集成)         |
          +------------------------------------+

项目结构

journapi/
├── src/journapi/            SDK 核心
│   ├── api.py               ArtifactSearchClient 门面 + Provider 注册表
│   ├── models.py            统一数据模型（JournalRecord / SearchOptions 等）
│   ├── provider.py          ArtifactProvider 抽象基类
│   ├── http.py              HTTP 客户端（限速 / 重试 / 缓存）
│   ├── sources/             数据源
│   │   └── issn_portal/     ISSN Portal 期刊源
│   │       ├── provider.py  公开网页源（search / get / cluster）
│   │       └── api_client.py 官方订阅 API（REST + JWT）
│   ├── cli/                 CLI 入口（search / get / cluster / web）
│   └── web/                 内置 Web UI
│       ├── server.py        服务逻辑（模板加载 + 路由 + JSON API）
│       └── templates/       前端模板（base / search / record / cluster）
├── skills/                  AI Agent 技能
│   └── journapi-skill/     期刊检索技能（SKILL.md）
├── examples/                可运行示例
├── docs/                    详细文档
└── tests/                   单元测试

安装

包已发布到 PyPI（包名 journapi）。三种使用方式：

1. uvx 免安装直接运行（推荐）

uvx journapi --help
uvx journapi search "Hearing research"

2. pip 安装（长期使用 / 脚本内调用）

pip install journapi             # 仅 CLI
pip install "journapi[chinese]"  # 含中文刊名分词支持

3. uv tool 全局安装

uv tool install journapi
journapi search "Hearing research"

开发环境

git clone https://cnb.cool/xqitw/artifetch.git
cd journapi
uv sync --extra chinese --extra dev

快速开始

Python API

import asyncio
from journapi import ArtifactSearchClient, SearchOptions


async def main():
    async with ArtifactSearchClient() as client:
        # 1) 按刊名 / ISSN / eISSN / ISSN-L 搜索
        results = await client.search("Hearing research")
        for rec in results.items:
            print(rec.issn, rec.issn_l, rec.issn_h, rec.title)

        # 2) 按 ISSN 精确查询（含 ISSN-L / ISSN-H）
        rec = await client.get("0964-1998")
        print(rec.issn_l, rec.issn_h)  # 0964-1998 / 9063-7704

        # 3) 展开 ISSN-L 集群
        members = await client.cluster_issnl("0378-5955")
        for m in members:
            print(m.issn, m.medium, m.title)


asyncio.run(main())

完整示例见 examples/ 目录。

CLI

# 搜索期刊（刊名 / ISSN / eISSN / ISSN-L）
journapi search "Hearing research"
journapi search 0378-5955 --json
journapi search "hearing" --media online --country USA --page-size 50

# 单条记录
journapi get 0964-1998

# ISSN-L 集群
journapi cluster 0378-5955

# Web UI（浏览器界面）
journapi web --host 127.0.0.1 --port 8787
# 然后浏览器打开 http://127.0.0.1:8787

Web UI

journapi web 启动内置浏览器界面，支持：

• 🔍 搜索 — 按刊名 / 关键词模糊搜索，返回结果列表
• 🎯 精确查询 — 输入 ISSN / eISSN / ISSN-L 直接获取单条记录
• ISSN-L 集群 — 查看刊物全部介质版本
• ISSN-H 家族 — 展示历史沿革标识与成员数

模块说明

环境变量

Skills

通用智能体技能，通过 npx skills 安装。

npx skills add https://cnb.cool/xqitw/artifetch.git

关键设计

• Provider 抽象层 — 所有数据源实现 ArtifactProvider 接口，上层 API / CLI / Web 与具体源解耦
• 统一数据模型 — JournalRecord 跨数据源一致，字段可空性按数据层级区分（搜索卡片 / 详情页 / 集群页）
• 礼貌抓取 — 内置限速（robots.txt Crawl-delay 1s）、重试退避、可选缓存
• 自动降级 — 官方订阅 API 不可用时自动回退到公开网页源
• enrich 合并 — get() 自动从 ISSN-L 集群页合并频率/语言/年份，从搜索卡片反查 ISSN-H 家族成员数
• 前端模板化 — Web UI 前端为独立模板文件，Python 仅做 {{TOKEN}} 替换，无内嵌 HTML

合规说明

公开门户面向人工浏览。journapi 遵循其 robots.txt：/resource/ISSN/ 允许抓取，/resource/ISSN-L/ 与 /resource/ISSN-H/ 禁止抓取，并强制 1s 爬取延迟。生产 / 批量场景请订阅官方搜索 API 并使用订阅 Provider。

文档

• API 参考 — 客户端、模型、错误、Web 服务路由
• 数据源调研 — ISSN Portal 公开接口能力边界
• 示例 — 可运行脚本

贡献指南

欢迎参与贡献！详细的贡献规范和开发流程请参考 CONTRIBUTING.md。

许可证

MIT