linxsci-sdk 0.3.0__tar.gz

linxsci_sdk-0.3.0/.env.example

@@ -0,0 +1,8 @@
+# Optional environment overrides. Ordinary users can run setup instead.
+SCHOLAR_BASE_URL=https://linxsci.com
+SCHOLAR_OPENAPI_KEY=replace-with-your-scholar-key
+# Test service, when explicitly needed: http://101.126.93.213:28888
+# Optional, only when required by the deployed PDF API:
+# SCHOLAR_MINERU_API_KEY=replace-with-your-mineru-key
+# Optional alternate local configuration file:
+# SCHOLAR_CONFIG_FILE=/absolute/path/config.json

linxsci_sdk-0.3.0/Install.bat

@@ -0,0 +1,13 @@
+@echo off
+chcp 65001 >nul
+cd /d "%~dp0"
+where py >nul 2>nul
+if %errorlevel% equ 0 (
+  py -3 install.py %*
+) else (
+  python install.py %*
+)
+set "linxsci_result=%errorlevel%"
+if %linxsci_result% neq 0 echo 安装或配置未完成，请查看上方提示。需要 Python 3.9 或更新版本。
+pause
+exit /b %linxsci_result%

linxsci_sdk-0.3.0/Install.command

@@ -0,0 +1,11 @@
+#!/bin/bash
+cd -- "$(dirname -- "$0")" || exit 1
+if command -v python3 >/dev/null 2>&1; then
+  python3 install.py "$@"
+  result=$?
+else
+  echo "请先安装 Python 3.9 或更新版本：https://www.python.org/downloads/"
+  result=2
+fi
+read -r -p "按回车关闭窗口…" _linxsci_done
+exit "$result"

linxsci_sdk-0.3.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include install.py Install.command Install.bat
+include Scholar-OpenAPI-v2-使用文档.md .env.example
+recursive-include examples *.py
+recursive-include docs *.md
+recursive-include tools *.py
+recursive-include tests *.py

linxsci_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: linxsci-sdk
+Version: 0.3.0
+Summary: Scholar OpenAPI v2 CLI and Python client
+Project-URL: Homepage, https://linxsci.com
+Project-URL: Repository, https://github.com/LinxSci/linxsci-skills
+Project-URL: Documentation, https://github.com/LinxSci/linxsci-skills/blob/main/README.md
+Project-URL: Issues, https://github.com/LinxSci/linxsci-skills/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# LinxSci SDK、CLI 与 Skills
+
+让 AI 助手帮你搜索学术论文、阅读相关章节、查询引用，并解析你指定的 PDF。
+
+你需要一个已有的 Scholar API Key，以及能够执行本地 Python 脚本的 AI 助手。运行环境需要 **Python 3.9+**；本工具不需要额外 Python 运行依赖。
+
+## 命令和 Skill 如何命名
+
+| 层级 | 当前名称或用法 |
+| --- | --- |
+| PyPI 安装包名 | `linxsci-sdk` |
+| 终端命令名 | `linxsci`，例如 `linxsci search "graph neural networks"` |
+| Python 导入名 | `linxsci`，例如 `from linxsci import ScholarClient` |
+| AI Skill 名称 | `linxsci-skills`，在助手中使用 `$linxsci-skills` |
+
+当前论文相关动作直接使用 `linxsci <动作>`，例如 `linxsci setup`、`linxsci search`、`linxsci paper`。单独执行 `linxsci` 显示帮助。未来新增能力可注册独立命令组，例如 `linxsci patents search`；这是命名示例，当前只提供 Scholar API 能力。
+
+本文统一使用表中的新名称。已有 Key 配置和 `SCHOLAR_*` 环境变量继续复用；安装过旧名称包的开发者先按 [名称迁移说明](docs/DEVELOPMENT.md#14-从旧名称迁移) 更新，避免两个包共用同一终端入口。新增能力的开发步骤见 [开发者指南](docs/DEVELOPMENT.md#91-新增其他-skill-的命名与入口)。
+
+## 对外发布路线
+
+通过 **PyPI 发布 CLI / SDK，通过官方 GitHub 仓库维护和分发 Skill**。源码已上传至 [LinxSci/linxsci-skills](https://github.com/LinxSci/linxsci-skills)，PyPI 首次发布仍在准备中。以下包名安装命令仅在 PyPI 发布成功后适用；发布前可使用本地 wheel、ZIP 或源码安装。
+
+CLI 的推荐安装与使用方式：
+
+```bash
+uv tool install linxsci-sdk
+linxsci setup
+linxsci search "graph neural networks"
+```
+
+升级使用 `uv tool upgrade linxsci-sdk`；找不到命令时按 [uv 官方工具指南](https://docs.astral.sh/uv/guides/tools/) 使用 `uv tool update-shell`，然后重新打开终端。SDK 用户应在自己的 Python 项目环境中执行 `python -m pip install linxsci-sdk`；`uv tool install` 的隔离环境不会把 SDK 安装到当前 Python 项目。
+
+Skill 官方仓库为 [LinxSci/linxsci-skills](https://github.com/LinxSci/linxsci-skills)，可使用支持 GitHub Skill 的安装器：
+
+```bash
+npx skills add https://github.com/LinxSci/linxsci-skills --skill linxsci-skills
+```
+
+该方式需要 Node.js / npx，按提示选择目标助手和安装范围。已安装本 CLI 的用户也可以运行 `linxsci install-skill` 安装随包携带的完整 Skill。安装后按 [普通用户指南](docs/USER_GUIDE.md) 配置 Key。官网接入步骤见 [官网接入说明](docs/WEBSITE_PUBLISHING.md) 与 [发布指南](docs/RELEASING.md)。
+
+## 普通用户：安装、配置、提问
+
+1. 下载发布方提供的 `linxsci-skills-0.3.0.zip`，解压。
+2. macOS 双击 `Install.command`；Windows 双击 `Install.bat`。也可以在解压目录运行 `python3 install.py`（Windows 用 `py -3 install.py`）。
+3. 在向导中确认服务地址，输入你的 API Key。输入时 Key 不会显示。向导保存配置并检查连接。
+4. 在助手中输入：
+
+> 使用 $linxsci-skills 搜索图神经网络相关论文，阅读方法章节，比较主要方法并附上来源。
+
+默认使用正式服务 **https://linxsci.com**，无需在用户电脑部署 Scholar。已有本地配置或环境变量优先于默认值，升级不会自动替换用户保存的测试地址。切换正式服务可运行 `linxsci setup --online`；ZIP 用户在解压目录运行 `python3 skills/linxsci-skills/scripts/cli.py setup --online`。测试环境配置见 [测试指南](docs/TESTING.md)。
+
+安装器默认将 Skill 放到 `~/.agents/skills/linxsci-skills`，见 [官方本地 Skill 说明](https://learn.chatgpt.com/docs/build-skills)。客户端未发现 Skill 时重启助手；其他加载位置可通过 `--skills-dir` 指定。旧版客户端使用 `~/.codex/skills` 时，也可显式指定该目录。
+
+ZIP 安装后即可在助手中使用 Skill；安装器不注册终端的 `linxsci` 命令。需要该命令时，按下面的 wheel 或源码安装流程操作。完整操作步骤、更新和故障处理见 [普通用户指南](docs/USER_GUIDE.md)。本项目不包含 AI 助手或 Scholar 服务器，也不负责注册账号或发放 Key。
+
+## 已安装 CLI 的用户
+
+当前发布文件可本地安装；尚未上传到 PyPI。安装 wheel 后执行：
+
+```bash
+linxsci install-skill
+linxsci setup --base-url https://linxsci.com
+linxsci search 'graph neural networks'
+```
+
+`linxsci setup` 一次保存配置，后续 CLI、SDK 和本地 Skill 共用。不需要每次 export 环境变量。`linxsci config` 查看配置状态，不显示 Key；`linxsci config --clear` 清除保存的地址和 Key。更新包后运行 `linxsci install-skill --update` 更新助手使用的脚本，旧 Skill 保留备份。
+
+逐个接口的完整命令、请求文件、ID 编码及 PDF 上传方式见 [全部 34 个接口的 CLI 使用指南](docs/CLI_GUIDE.md)。
+
+## 从本地源码开始测试
+
+在项目根目录执行。首次创建环境并安装开发版；已有 `.venv` 时可跳过创建：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip setuptools wheel
+python3 -m pip install -e .
+
+linxsci --version
+linxsci setup --base-url http://101.126.93.213:28888
+```
+
+Windows 激活命令为 `.venv\Scripts\activate`。统一使用同一个虚拟环境，不要混用 `.venv` 和 `.venv-1`。旧 pip 可能提示找不到 setup.py/setup.cfg，先执行上述升级命令；指定解释器安装时使用 `.venv/bin/python -m pip install -e .`，不要写成 `python -m python3 -m pip ...`。
+
+从旧名称的开发版本更新时，先按 [名称迁移说明](docs/DEVELOPMENT.md#14-从旧名称迁移) 卸载旧包，再安装当前源码。用 `linxsci --version` 和 `linxsci --help` 确认入口。已有 Key 无需重新输入；`linxsci install-skill --update` 会将本工具管理的旧 Skill 迁移到新目录并备份。
+
+按向导输入已有 API Key，输入时不会显示。`setup` 会检查一次连接，成功后即可检索；之后需要单独检查连接时运行 `linxsci doctor --json`，确认 `ok` 为 true 且 `base_url` 是测试服务地址。检查连接也会实际调用接口，无需反复执行。
+
+## 论文检索和阅读示例
+
+以下命令在已经激活虚拟环境、完成 Key 配置后执行。CLI 会输出服务返回的数据，整理和比较论文可以交给安装了 Skill 的助手。
+
+### 1. 按英文或中文主题检索
+
+```bash
+linxsci search "graph neural networks"
+linxsci search "大语言模型智能体"
+```
+
+将引号中的文字替换为自己的研究主题。检查返回论文的标题、摘要和主题是否相关，记录实际返回的论文 ID；未检索到结果时不应编造论文。
+
+### 2. 保存搜索结果
+
+```bash
+linxsci --output search.json search "graph neural networks"
+```
+
+响应原始内容保存到当前目录的 `search.json`，可用编辑器打开核查。`--output` 是全局选项，放在 `linxsci` 之后、`search` 或 `paper` 等具体动作之前。
+
+### 3. 查看论文详情、目录和相关章节
+
+先从搜索响应选择一篇论文，再从其目录选择章节。下列中文占位参数必须替换为真实返回值后执行：
+
+```bash
+linxsci paper "实际论文ID"
+linxsci paper "实际论文ID" --resource toc
+linxsci paper "实际论文ID" --resource sections --item-id "实际章节ID"
+```
+
+论文 ID 保留 `local:`、`arxiv:`、`openalex:`、`s2:` 或 `doi:` 来源前缀，不要用论文标题代替 ID。便捷命令接收未编码的 ID，并负责 URL 编码；章节 ID 必须来自接口响应，不能根据章节名称猜测。
+
+测试通过的标准是：详情对应所选论文，目录能定位真实章节，读取的章节内容与所选 ID 一致。不要仅凭接口未报错就判断内容正确。
+
+## 在助手中测试 Skill
+
+源码安装只提供 CLI/SDK。需要通过 `$linxsci-skills` 使用时，再安装 Skill；首次执行：
+
+```bash
+linxsci install-skill
+```
+
+已由本工具安装过，或修改源码后要同步到安装副本，执行：
+
+```bash
+linxsci install-skill --update
+```
+
+在支持本地 Skill 和脚本执行的助手中新建对话，分别尝试：
+
+**检索与筛选**
+
+> 使用 $linxsci-skills 检索图神经网络相关论文，选择最多三篇最相关的，说明相关性，并附实际返回的论文 ID 和来源。结果不足三篇时请如实说明。
+
+**按章节阅读**
+
+> 使用 $linxsci-skills 阅读论文“实际论文ID”，先查看目录，再读取方法相关章节，解释主要方法，并标明章节依据。
+
+**比较两篇论文**
+
+> 使用 $linxsci-skills 比较论文“实际论文ID一”和“实际论文ID二”的方法和实验结论，逐项列出来源。未找到证据的数据请明确说明，不要补写。
+
+将提示中的论文 ID 替换为实际检索结果。检查助手是否真正调用服务、引用是否能对应响应、数值是否有章节证据，以及是否存在重复检索或无目的读取全文。
+
+开发时也可在新对话中直接指定当前仓库 `skills/linxsci-skills/SKILL.md` 的绝对路径，要求助手读取该文件并执行同目录下的脚本，从而直接测试当前源码。复制安装的 Skill 不会随源码自动更新，修改后要先同步，避免误测旧版本。
+
+## 测试样例与验收重点
+
+| 测试样例 | 验收重点 |
+| --- | --- |
+| 英文、中文关键词检索 | 执行真实搜索，返回相关论文；空结果如实说明 |
+| 保存搜索结果 | `search.json` 存在，保留服务原始响应 |
+| 论文详情与目录 | 使用真实且带来源前缀的 ID，内容与论文对应 |
+| 读取指定章节 | 使用目录返回的实际章节 ID，证据能定位到正文 |
+| 助手筛选和比较 | 有真实调用记录，论文来源和结论可核查，不编造数值 |
+
+本地修改可直接连接测试环境验证，无需每次先 push Git 或重新打包。调优前后固定提示词和模型设置，记录结果准确性、调用次数、耗时以及需要人工纠正的地方。完整的 8 个验收场景、故障处理及记录模板见 [测试环境验收与 Skill 调优](docs/TESTING.md)。
+
+## 能力与范围
+
+已适配新版数字框架错误码、请求追踪和计费异常诊断。覆盖接口文档中的 34 条路由：服务信息和健康、论文搜索和标识解析、详情/内容/目录/章节/图表资源/引用、推荐、作者/机构/期刊、PDF 解析任务。全部 34 个接口均提供便捷命令，无需填写 HTTP 方法或接口路径；`request` 保留作通用调试入口。
+
+| 接口分类 | 数量 | 调用入口 |
+| --- | --- | --- |
+| 服务信息与健康检查 | 4 | `meta`、`usage`、`health live/ready` |
+| 论文搜索与解析 | 6 | `search`、`search-openalex`、`search-semantic-scholar`、`search-google-scholar`、`resolve`、`batch-get` |
+| 论文详情与引用 | 11 | `paper`，搭配 `--resource` 和 `--item-id` |
+| 论文推荐 | 2 | `recommend`、`mobile-cards` |
+| 作者、机构与期刊 | 7 | `author`、`institution`、`venue`（可加 `--papers`）、`resolve-entities` |
+| PDF 解析 | 4 | `parse-pdf`、`upload`、`task`（结果加 `--result`） |
+
+只需调用指定接口时，可以直接使用便捷命令。例如：
+
+```bash
+linxsci mobile-cards
+linxsci search-openalex "large language models"
+```
+
+四个搜索命令都直接接收检索词，可通过 `--body @文件.json` 添加契约中定义的其他参数。其他 JSON 请求文件需先按实际 Agent API 契约准备。便捷命令自动选择接口方法和路径；JSON 请求可通过 `--body @文件路径` 传入请求。PDF 上传为 multipart，使用 `linxsci upload /实际路径/paper.pdf`。在助手中也可直接提出“使用 $linxsci-skills 调用指定接口”，并提供接口路径及必要参数。
+
+研究比较和总结由助手根据实际读取的内容完成。目前接口文档未定义多数 POST 的业务字段、分页和 PDF 状态模型；这些高级接口应按部署版本的上游契约使用，不能假定空 JSON 有效。所有路由可调用不代表每条接口都已有专用表单或经过真实生产验证。
+
+## 开发与发布
+
+- [SDK 开发者指南：安装、配置、方法签名与全部 34 个接口](docs/DEVELOPMENT.md)
+- [CLI 使用指南：全部 34 个接口逐一调用](docs/CLI_GUIDE.md)
+- [测试环境验收与 Skill 调优](docs/TESTING.md)
+- [发布指南：构建、验证与分发](docs/RELEASING.md)
+- [官网接入说明：下载入口、三类文档与发布文件](docs/WEBSITE_PUBLISHING.md)
+- [Skill 指令](skills/linxsci-skills/SKILL.md)
+- [原始接口文档](Scholar-OpenAPI-v2-使用文档.md)
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 tools/build_release.py --bundle-only
+```

linxsci_sdk-0.3.0/README.md

@@ -0,0 +1,207 @@
+# LinxSci SDK、CLI 与 Skills
+
+让 AI 助手帮你搜索学术论文、阅读相关章节、查询引用，并解析你指定的 PDF。
+
+你需要一个已有的 Scholar API Key，以及能够执行本地 Python 脚本的 AI 助手。运行环境需要 **Python 3.9+**；本工具不需要额外 Python 运行依赖。
+
+## 命令和 Skill 如何命名
+
+| 层级 | 当前名称或用法 |
+| --- | --- |
+| PyPI 安装包名 | `linxsci-sdk` |
+| 终端命令名 | `linxsci`，例如 `linxsci search "graph neural networks"` |
+| Python 导入名 | `linxsci`，例如 `from linxsci import ScholarClient` |
+| AI Skill 名称 | `linxsci-skills`，在助手中使用 `$linxsci-skills` |
+
+当前论文相关动作直接使用 `linxsci <动作>`，例如 `linxsci setup`、`linxsci search`、`linxsci paper`。单独执行 `linxsci` 显示帮助。未来新增能力可注册独立命令组，例如 `linxsci patents search`；这是命名示例，当前只提供 Scholar API 能力。
+
+本文统一使用表中的新名称。已有 Key 配置和 `SCHOLAR_*` 环境变量继续复用；安装过旧名称包的开发者先按 [名称迁移说明](docs/DEVELOPMENT.md#14-从旧名称迁移) 更新，避免两个包共用同一终端入口。新增能力的开发步骤见 [开发者指南](docs/DEVELOPMENT.md#91-新增其他-skill-的命名与入口)。
+
+## 对外发布路线
+
+通过 **PyPI 发布 CLI / SDK，通过官方 GitHub 仓库维护和分发 Skill**。源码已上传至 [LinxSci/linxsci-skills](https://github.com/LinxSci/linxsci-skills)，PyPI 首次发布仍在准备中。以下包名安装命令仅在 PyPI 发布成功后适用；发布前可使用本地 wheel、ZIP 或源码安装。
+
+CLI 的推荐安装与使用方式：
+
+```bash
+uv tool install linxsci-sdk
+linxsci setup
+linxsci search "graph neural networks"
+```
+
+升级使用 `uv tool upgrade linxsci-sdk`；找不到命令时按 [uv 官方工具指南](https://docs.astral.sh/uv/guides/tools/) 使用 `uv tool update-shell`，然后重新打开终端。SDK 用户应在自己的 Python 项目环境中执行 `python -m pip install linxsci-sdk`；`uv tool install` 的隔离环境不会把 SDK 安装到当前 Python 项目。
+
+Skill 官方仓库为 [LinxSci/linxsci-skills](https://github.com/LinxSci/linxsci-skills)，可使用支持 GitHub Skill 的安装器：
+
+```bash
+npx skills add https://github.com/LinxSci/linxsci-skills --skill linxsci-skills
+```
+
+该方式需要 Node.js / npx，按提示选择目标助手和安装范围。已安装本 CLI 的用户也可以运行 `linxsci install-skill` 安装随包携带的完整 Skill。安装后按 [普通用户指南](docs/USER_GUIDE.md) 配置 Key。官网接入步骤见 [官网接入说明](docs/WEBSITE_PUBLISHING.md) 与 [发布指南](docs/RELEASING.md)。
+
+## 普通用户：安装、配置、提问
+
+1. 下载发布方提供的 `linxsci-skills-0.3.0.zip`，解压。
+2. macOS 双击 `Install.command`；Windows 双击 `Install.bat`。也可以在解压目录运行 `python3 install.py`（Windows 用 `py -3 install.py`）。
+3. 在向导中确认服务地址，输入你的 API Key。输入时 Key 不会显示。向导保存配置并检查连接。
+4. 在助手中输入：
+
+> 使用 $linxsci-skills 搜索图神经网络相关论文，阅读方法章节，比较主要方法并附上来源。
+
+默认使用正式服务 **https://linxsci.com**，无需在用户电脑部署 Scholar。已有本地配置或环境变量优先于默认值，升级不会自动替换用户保存的测试地址。切换正式服务可运行 `linxsci setup --online`；ZIP 用户在解压目录运行 `python3 skills/linxsci-skills/scripts/cli.py setup --online`。测试环境配置见 [测试指南](docs/TESTING.md)。
+
+安装器默认将 Skill 放到 `~/.agents/skills/linxsci-skills`，见 [官方本地 Skill 说明](https://learn.chatgpt.com/docs/build-skills)。客户端未发现 Skill 时重启助手；其他加载位置可通过 `--skills-dir` 指定。旧版客户端使用 `~/.codex/skills` 时，也可显式指定该目录。
+
+ZIP 安装后即可在助手中使用 Skill；安装器不注册终端的 `linxsci` 命令。需要该命令时，按下面的 wheel 或源码安装流程操作。完整操作步骤、更新和故障处理见 [普通用户指南](docs/USER_GUIDE.md)。本项目不包含 AI 助手或 Scholar 服务器，也不负责注册账号或发放 Key。
+
+## 已安装 CLI 的用户
+
+当前发布文件可本地安装；尚未上传到 PyPI。安装 wheel 后执行：
+
+```bash
+linxsci install-skill
+linxsci setup --base-url https://linxsci.com
+linxsci search 'graph neural networks'
+```
+
+`linxsci setup` 一次保存配置，后续 CLI、SDK 和本地 Skill 共用。不需要每次 export 环境变量。`linxsci config` 查看配置状态，不显示 Key；`linxsci config --clear` 清除保存的地址和 Key。更新包后运行 `linxsci install-skill --update` 更新助手使用的脚本，旧 Skill 保留备份。
+
+逐个接口的完整命令、请求文件、ID 编码及 PDF 上传方式见 [全部 34 个接口的 CLI 使用指南](docs/CLI_GUIDE.md)。
+
+## 从本地源码开始测试
+
+在项目根目录执行。首次创建环境并安装开发版；已有 `.venv` 时可跳过创建：
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip setuptools wheel
+python3 -m pip install -e .
+
+linxsci --version
+linxsci setup --base-url http://101.126.93.213:28888
+```
+
+Windows 激活命令为 `.venv\Scripts\activate`。统一使用同一个虚拟环境，不要混用 `.venv` 和 `.venv-1`。旧 pip 可能提示找不到 setup.py/setup.cfg，先执行上述升级命令；指定解释器安装时使用 `.venv/bin/python -m pip install -e .`，不要写成 `python -m python3 -m pip ...`。
+
+从旧名称的开发版本更新时，先按 [名称迁移说明](docs/DEVELOPMENT.md#14-从旧名称迁移) 卸载旧包，再安装当前源码。用 `linxsci --version` 和 `linxsci --help` 确认入口。已有 Key 无需重新输入；`linxsci install-skill --update` 会将本工具管理的旧 Skill 迁移到新目录并备份。
+
+按向导输入已有 API Key，输入时不会显示。`setup` 会检查一次连接，成功后即可检索；之后需要单独检查连接时运行 `linxsci doctor --json`，确认 `ok` 为 true 且 `base_url` 是测试服务地址。检查连接也会实际调用接口，无需反复执行。
+
+## 论文检索和阅读示例
+
+以下命令在已经激活虚拟环境、完成 Key 配置后执行。CLI 会输出服务返回的数据，整理和比较论文可以交给安装了 Skill 的助手。
+
+### 1. 按英文或中文主题检索
+
+```bash
+linxsci search "graph neural networks"
+linxsci search "大语言模型智能体"
+```
+
+将引号中的文字替换为自己的研究主题。检查返回论文的标题、摘要和主题是否相关，记录实际返回的论文 ID；未检索到结果时不应编造论文。
+
+### 2. 保存搜索结果
+
+```bash
+linxsci --output search.json search "graph neural networks"
+```
+
+响应原始内容保存到当前目录的 `search.json`，可用编辑器打开核查。`--output` 是全局选项，放在 `linxsci` 之后、`search` 或 `paper` 等具体动作之前。
+
+### 3. 查看论文详情、目录和相关章节
+
+先从搜索响应选择一篇论文，再从其目录选择章节。下列中文占位参数必须替换为真实返回值后执行：
+
+```bash
+linxsci paper "实际论文ID"
+linxsci paper "实际论文ID" --resource toc
+linxsci paper "实际论文ID" --resource sections --item-id "实际章节ID"
+```
+
+论文 ID 保留 `local:`、`arxiv:`、`openalex:`、`s2:` 或 `doi:` 来源前缀，不要用论文标题代替 ID。便捷命令接收未编码的 ID，并负责 URL 编码；章节 ID 必须来自接口响应，不能根据章节名称猜测。
+
+测试通过的标准是：详情对应所选论文，目录能定位真实章节，读取的章节内容与所选 ID 一致。不要仅凭接口未报错就判断内容正确。
+
+## 在助手中测试 Skill
+
+源码安装只提供 CLI/SDK。需要通过 `$linxsci-skills` 使用时，再安装 Skill；首次执行：
+
+```bash
+linxsci install-skill
+```
+
+已由本工具安装过，或修改源码后要同步到安装副本，执行：
+
+```bash
+linxsci install-skill --update
+```
+
+在支持本地 Skill 和脚本执行的助手中新建对话，分别尝试：
+
+**检索与筛选**
+
+> 使用 $linxsci-skills 检索图神经网络相关论文，选择最多三篇最相关的，说明相关性，并附实际返回的论文 ID 和来源。结果不足三篇时请如实说明。
+
+**按章节阅读**
+
+> 使用 $linxsci-skills 阅读论文“实际论文ID”，先查看目录，再读取方法相关章节，解释主要方法，并标明章节依据。
+
+**比较两篇论文**
+
+> 使用 $linxsci-skills 比较论文“实际论文ID一”和“实际论文ID二”的方法和实验结论，逐项列出来源。未找到证据的数据请明确说明，不要补写。
+
+将提示中的论文 ID 替换为实际检索结果。检查助手是否真正调用服务、引用是否能对应响应、数值是否有章节证据，以及是否存在重复检索或无目的读取全文。
+
+开发时也可在新对话中直接指定当前仓库 `skills/linxsci-skills/SKILL.md` 的绝对路径，要求助手读取该文件并执行同目录下的脚本，从而直接测试当前源码。复制安装的 Skill 不会随源码自动更新，修改后要先同步，避免误测旧版本。
+
+## 测试样例与验收重点
+
+| 测试样例 | 验收重点 |
+| --- | --- |
+| 英文、中文关键词检索 | 执行真实搜索，返回相关论文；空结果如实说明 |
+| 保存搜索结果 | `search.json` 存在，保留服务原始响应 |
+| 论文详情与目录 | 使用真实且带来源前缀的 ID，内容与论文对应 |
+| 读取指定章节 | 使用目录返回的实际章节 ID，证据能定位到正文 |
+| 助手筛选和比较 | 有真实调用记录，论文来源和结论可核查，不编造数值 |
+
+本地修改可直接连接测试环境验证，无需每次先 push Git 或重新打包。调优前后固定提示词和模型设置，记录结果准确性、调用次数、耗时以及需要人工纠正的地方。完整的 8 个验收场景、故障处理及记录模板见 [测试环境验收与 Skill 调优](docs/TESTING.md)。
+
+## 能力与范围
+
+已适配新版数字框架错误码、请求追踪和计费异常诊断。覆盖接口文档中的 34 条路由：服务信息和健康、论文搜索和标识解析、详情/内容/目录/章节/图表资源/引用、推荐、作者/机构/期刊、PDF 解析任务。全部 34 个接口均提供便捷命令，无需填写 HTTP 方法或接口路径；`request` 保留作通用调试入口。
+
+| 接口分类 | 数量 | 调用入口 |
+| --- | --- | --- |
+| 服务信息与健康检查 | 4 | `meta`、`usage`、`health live/ready` |
+| 论文搜索与解析 | 6 | `search`、`search-openalex`、`search-semantic-scholar`、`search-google-scholar`、`resolve`、`batch-get` |
+| 论文详情与引用 | 11 | `paper`，搭配 `--resource` 和 `--item-id` |
+| 论文推荐 | 2 | `recommend`、`mobile-cards` |
+| 作者、机构与期刊 | 7 | `author`、`institution`、`venue`（可加 `--papers`）、`resolve-entities` |
+| PDF 解析 | 4 | `parse-pdf`、`upload`、`task`（结果加 `--result`） |
+
+只需调用指定接口时，可以直接使用便捷命令。例如：
+
+```bash
+linxsci mobile-cards
+linxsci search-openalex "large language models"
+```
+
+四个搜索命令都直接接收检索词，可通过 `--body @文件.json` 添加契约中定义的其他参数。其他 JSON 请求文件需先按实际 Agent API 契约准备。便捷命令自动选择接口方法和路径；JSON 请求可通过 `--body @文件路径` 传入请求。PDF 上传为 multipart，使用 `linxsci upload /实际路径/paper.pdf`。在助手中也可直接提出“使用 $linxsci-skills 调用指定接口”，并提供接口路径及必要参数。
+
+研究比较和总结由助手根据实际读取的内容完成。目前接口文档未定义多数 POST 的业务字段、分页和 PDF 状态模型；这些高级接口应按部署版本的上游契约使用，不能假定空 JSON 有效。所有路由可调用不代表每条接口都已有专用表单或经过真实生产验证。
+
+## 开发与发布
+
+- [SDK 开发者指南：安装、配置、方法签名与全部 34 个接口](docs/DEVELOPMENT.md)
+- [CLI 使用指南：全部 34 个接口逐一调用](docs/CLI_GUIDE.md)
+- [测试环境验收与 Skill 调优](docs/TESTING.md)
+- [发布指南：构建、验证与分发](docs/RELEASING.md)
+- [官网接入说明：下载入口、三类文档与发布文件](docs/WEBSITE_PUBLISHING.md)
+- [Skill 指令](skills/linxsci-skills/SKILL.md)
+- [原始接口文档](Scholar-OpenAPI-v2-使用文档.md)
+
+```bash
+python3 -m unittest discover -s tests -v
+python3 tools/build_release.py --bundle-only
+```

linxsci_sdk-0.3.0/Scholar-OpenAPI-v2-/344/275/277/347/224/250/346/226/207/346/241/243.md

@@ -0,0 +1,105 @@
+# Scholar OpenAPI v2 使用文档
+
+Scholar 的 `/openapi/v2` 将请求转发给独立 Agent API。客户端只需使用 Scholar API Key；服务端负责向 Agent API 提供自己的 Key。接口路径、业务请求参数和上游业务响应以 Agent API 的 `/openapi/v1` 契约为准。健康检查分别转发到 Agent API 的 `/health/live` 和 `/health/ready`。
+
+可直接导入 [Postman 集合](./Scholar-OpenAPI-v2.postman_collection.json) 调用下表中的接口。
+
+## 认证和配置
+
+| 请求头 | 提供方 | 用途 |
+| --- | --- | --- |
+| `Authorization: Bearer <Scholar OpenAPI Key>` | 客户端 | Scholar 校验 API Key，所有 v2 接口都需要。 |
+| `X-Request-ID` | 客户端，可选 | 转发给 Agent API；Scholar 自身返回错误时也会在响应头回传。 |
+| `X-ANYTHINGRIGHT-REQ-ID` | 客户端，可选 | 指定 Scholar 框架响应中的 `extra.request-id`；未提供时由框架生成。 |
+| `X-MinerU-API-Key` | 客户端，按需 | PDF 解析相关请求转发给 Agent API。 |
+
+Scholar 服务端配置 `AgentPublicServerIp` 和 `AgentPublicAPIKey`；相应环境变量 `AGENT_PUBLIC_API_URL`、`AGENT_PUBLIC_API_KEY` 可在配置项为空时使用。转发到 Agent API `/openapi/v1` 的请求会由服务端附加 `X-API-Key`，客户端无需提供第二把 Key。v2 的这组配置与旧版 Agent API 配置独立。
+
+## 接口目录
+
+以下为 Scholar 对外路径。除健康检查外，上游使用相同的 HTTP 方法及 `/openapi/v1` 路径前缀。
+
+| Postman 分类 | 方法 | Scholar 路径 | 接口 |
+| --- | --- | --- | --- |
+| 服务信息与健康检查 | GET | `/openapi/v2/meta` | 接口元信息 |
+| 服务信息与健康检查 | GET | `/openapi/v2/usage` | 用量信息 |
+| 服务信息与健康检查 | GET | `/openapi/v2/health/live` | 存活检查 |
+| 服务信息与健康检查 | GET | `/openapi/v2/health/ready` | 就绪检查 |
+| 论文搜索与解析 | POST | `/openapi/v2/papers/search` | 综合论文搜索 |
+| 论文搜索与解析 | POST | `/openapi/v2/search/openalex` | OpenAlex 搜索 |
+| 论文搜索与解析 | POST | `/openapi/v2/search/semantic-scholar` | Semantic Scholar 搜索 |
+| 论文搜索与解析 | POST | `/openapi/v2/search/google-scholar` | Google Scholar 搜索 |
+| 论文搜索与解析 | POST | `/openapi/v2/papers/resolve` | 论文标识解析 |
+| 论文搜索与解析 | POST | `/openapi/v2/papers:batchGet` | 批量获取论文 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}` | 论文详情 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/content` | 论文内容 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/toc` | 论文目录 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/sections/{section_id}` | 论文章节 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/figures` | 论文图表 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/assets/{asset_id}` | 论文资源 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/references` | 参考文献 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/citations` | 被引论文 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/related` | 相关论文 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/graph` | 引用图谱 |
+| 论文详情与引用 | GET | `/openapi/v2/papers/{paper_id}/citation` | 论文引用格式 |
+| 论文推荐 | POST | `/openapi/v2/recommendations` | 论文推荐 |
+| 论文推荐 | GET | `/openapi/v2/recommendations/mobile-cards` | 移动端推荐卡片 |
+| 作者、机构与期刊 | GET | `/openapi/v2/authors/{author_id}` | 作者详情 |
+| 作者、机构与期刊 | GET | `/openapi/v2/authors/{author_id}/papers` | 作者论文 |
+| 作者、机构与期刊 | GET | `/openapi/v2/institutions/{institution_id}` | 机构详情 |
+| 作者、机构与期刊 | GET | `/openapi/v2/institutions/{institution_id}/papers` | 机构论文 |
+| 作者、机构与期刊 | GET | `/openapi/v2/venues/{venue_id}` | 期刊或会议详情 |
+| 作者、机构与期刊 | GET | `/openapi/v2/venues/{venue_id}/papers` | 期刊或会议论文 |
+| 作者、机构与期刊 | POST | `/openapi/v2/entities:resolve` | 实体标识解析 |
+| PDF 解析 | POST | `/openapi/v2/pdf/parse` | 创建 PDF 解析任务 |
+| PDF 解析 | POST | `/openapi/v2/pdf/parse/upload` | 上传 PDF 并创建解析任务 |
+| PDF 解析 | GET | `/openapi/v2/pdf/parse/{task_id}` | 查询 PDF 解析任务 |
+| PDF 解析 | GET | `/openapi/v2/pdf/parse/{task_id}/result` | 获取 PDF 解析结果 |
+
+`paper_id` 支持 `local:`、`arxiv:`、`openalex:`、`s2:`、`doi:` 前缀。ID 中的 `/` 需要 URL 编码，例如 `doi:10.1000%2Fexample`。`POST` 接口的 JSON 字段按 Agent API 契约填写；Postman 中的 `{}` 只是待编辑模板。PDF 上传使用 `multipart/form-data` 的 `file` 字段，具体参数与文件大小限制以 Agent API 配置为准。
+
+## API Key 调用与计费流程
+
+正常调用依次经过 Scholar 的 API Key 校验、member 的 `/internal/openapi/calls/begin`、Agent API 转发和 member 的 `/internal/openapi/calls/finish`。若服务端 Agent API 配置缺失，请求会在 `begin` 前返回；若 `begin` 拒绝请求，则不会转发上游或调用 `finish`。路由映射生成固定的 `openapi_v2_*` action，例如论文资源接口的 action 为 `openapi_v2_paper_asset`。
+
+首次调用尚未登记的 action 时，member 会在 `openapi_register` 创建**待启用**记录；该次请求返回 HTTP 503，且不会转发给 Agent API。管理员按免费或计费策略配置并启用对应 action 后，才能继续调用。
+
+每次请求预计调用量为 1。Agent API 返回 2xx 时，实际调用量为 1；返回其他状态或发生连接失败时，实际调用量为 0，member 根据 `finish` 结果释放预占积分。每日调用限额由 member 检查。
+
+## 响应与错误
+
+Agent API 已返回且 `finish` 成功时，Scholar 保留上游 HTTP 状态码和响应体，并透传 `Content-Type`、`X-Request-ID`、`Retry-After`、`Cache-Control`。这也适用于 Agent API 的业务错误，例如 `validation_error` 或 `asset_unavailable`；其错误体仍使用 Agent API 的格式。
+
+Scholar 自身产生的鉴权、配置、用量和连接错误使用统一框架结构：
+
+```json
+{
+  "code": -1,
+  "data": {},
+  "error": {
+    "code": -3900,
+    "msg": "OpenAPI action openapi_v2_paper_asset has been registered but is not enabled. Ask an administrator to configure and enable it before retrying."
+  },
+  "extra": {
+    "request-id": "example-request-id",
+    "cost": 0.01
+  }
+}
+```
+
+示例中的 HTTP 状态为 503；`extra.cost` 是本次请求耗时，单位为秒。这里的 `extra.request-id` 来自 `X-ANYTHINGRIGHT-REQ-ID` 或由框架生成。member 内部使用的 `-3501`、`-3500` 会分别转换为下表的对外错误码。
+
+| HTTP | `error.code` | 原因与处理 |
+| --- | --- | --- |
+| 401 | `-401` | Scholar API Key 缺失、无效或无法识别用户；检查 `Authorization`。 |
+| 404 | `-404` | 未匹配到 v2 接口映射；检查路径和 HTTP 方法。 |
+| 503 | `-3900` | 接口 action 已登记但未启用；联系管理员配置、启用后重试。 |
+| 429 | `-3901` | 已达到每日调用限额；额度恢复后重试或联系管理员。 |
+| 503 | `-3902` | Agent API 地址或服务端 Key 未配置；联系服务端管理员。 |
+| 502 | `-3903` | Agent API 连接或传输失败；Scholar 会尝试以失败结果调用 `finish`。 |
+| 502 | `-3904` | member 的 `begin` 未成功，尚未转发上游；检查 member 服务和内部鉴权配置。 |
+| 502 | `-3905` | Agent API 已返回，但 member 的 `finish` 未确认；先查询执行与计费结果，再决定是否重试可能产生写入的请求。 |
+
+## Postman 调用
+
+导入 [Scholar OpenAPI v2 集合](./Scholar-OpenAPI-v2.postman_collection.json)，设置 `scholar_base_url` 和 `scholar_api_key`。GET 请求可直接按路径变量调用；POST 请求先按 Agent API 契约填写 JSON。调用 `/openapi/v2/pdf/parse/upload` 时，在 Postman 的 `file` 字段中选择本地 PDF。