linxsci 0.3.1__py3-none-any.whl

linxsci/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: linxsci-skills
+description: Use LinxSci OpenAPI v2 for academic paper search, content and citations, recommendations, research entities, PDF parsing, and explicit API health or usage queries.
+---
+
+# linxsci-skills
+
+[简体中文](SKILL.zh-CN.md)
+
+Use `scripts/cli.py` from this skill. Replace `<skill-dir>` with the absolute directory containing this file. Scripts require only Python 3.9+ and its standard library; no SDK installation is needed.
+
+## Install the skill independently
+
+This skill does not require the `linxsci` terminal command, the PyPI package, or an installed SDK. It runs its bundled Python scripts directly. You need Python 3.9+, an assistant with local skill discovery and script execution, and a LinxSci API key for service calls.
+
+### Option 1: GitHub skill installer
+
+If Node.js/npx is available, run:
+
+```bash
+npx skills add https://github.com/LinxSci/linxsci-skills --skill linxsci-skills
+```
+
+Choose the assistant and installation scope in that installer's prompts. This installs the complete skill; it does not need `pip install linxsci` or `uv tool install linxsci`. Keep this copy updated with the same external installer.
+
+### Option 2: Standalone ZIP or downloaded source
+
+Extract `linxsci-skills-0.3.1.zip`. In the extracted bundle, run `python3 install.py` (Windows: `py -3 install.py`), or double-click `Install.command` / `Install.bat`. The installer copies the complete skill and starts hidden-input key setup. No pip, SDK, or Node.js is required for this option. For installation only, run `python3 install.py --no-config`.
+
+The ZIP's `install.py` accepts the following options (place them after `install.py`):
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--skills-dir PATH` | `~/.agents/skills` | Assistant scan parent directory; `/linxsci-skills` is appended |
+| `--update` | Off | Update a managed existing copy and retain a backup |
+| `--no-config` | Off | Copy the skill without starting key setup |
+| `--online` | Off | Suggest the production root during setup |
+| `--base-url URL` | Saved/release root | Suggest an explicit root during setup; takes precedence over `--online` |
+
+`python3 install.py --help` shows installer help. `--online` and `--base-url` have no effect with `--no-config`. These flags belong to the ZIP installer; the standalone script uses `install-skill` for copying and a separate `setup` command for configuration.
+
+If you downloaded the repository or only the complete skill folder, run the bundled script directly:
+
+```bash
+python3 /absolute/path/to/source/skills/linxsci-skills/scripts/cli.py install-skill
+```
+
+The default destination is `~/.agents/skills/linxsci-skills`. For an assistant with another scan directory, add `--skills-dir /absolute/path/to/assistant/skills` (the parent directory, without the final `linxsci-skills`). Restart or refresh the assistant if discovery does not update.
+
+### Configure and verify using only the skill
+
+After default installation on macOS/Linux:
+
+```bash
+python3 "$HOME/.agents/skills/linxsci-skills/scripts/cli.py" routes
+python3 "$HOME/.agents/skills/linxsci-skills/scripts/cli.py" setup
+```
+
+On Windows, invoke `py -3 "C:\absolute\path\to\linxsci-skills\scripts\cli.py" setup`. For custom destinations, use the corresponding absolute script path. `routes` checks local execution without a key or network request. `setup` hides API key input, saves configuration, and performs one connection check. Then ask the assistant to use `$linxsci-skills`. Setup requires an interactive terminal; never ask the user to put their key in chat.
+
+To update a copy managed by the bundled installer, extract/download the new version and run **the new source's** `scripts/cli.py install-skill --update`, or the new ZIP's `python3 install.py --update --no-config`. Existing managed copies are backed up outside the scan directory. Manual or external-installer copies must be updated through their own installation method. Keep the complete `SKILL.md`, `scripts/`, `references/`, `agents/`, `service.json`, and supporting files together; copying `SKILL.md` alone cannot execute this skill.
+
+For every action below, use the absolute `scripts/cli.py` path. The [command reference](references/cli.md) documents standalone invocation, all commands, parameter types, defaults, required inputs, and examples.
+
+## Choose the requested action
+
+All 34 routes in [the API reference](references/api.md) have [convenience commands](references/cli.md). Follow the user's requested endpoint and parameters directly. A usage query does not require paper search; a recommendation request does not require section reading. Read the relevant contract when needed. `routes` lists supported methods and paths without network access.
+
+```bash
+python3 <skill-dir>/scripts/cli.py usage
+python3 <skill-dir>/scripts/cli.py health ready
+python3 <skill-dir>/scripts/cli.py search-openalex "large language models"
+python3 <skill-dir>/scripts/cli.py recommend --body @recommendations.json
+```
+
+Prepare JSON files from the deployed Agent API contract or user-provided request data. The four search commands accept a positional query; optional `--body` adds fields without overriding it. Do not invent POST fields, filters, pagination or task states. `{}` is not a universally valid request. `meta` does not guarantee a complete schema. If required business parameters are missing, identify the missing contract or request data.
+
+## Configuration
+
+`LINXSCI_BASE_URL` and `LINXSCI_OPENAPI_KEY` override setup's saved configuration. The default service is `https://linxsci.com`; supply a root without `/openapi/v2`. Saved settings override release defaults and persist across upgrades.
+
+Do not read or display keys, or ask users to send them in chat. If configuration is missing, have the user run setup locally with hidden key input:
+
+```bash
+python3 <skill-dir>/scripts/cli.py setup
+python3 <skill-dir>/scripts/cli.py setup --online
+```
+
+`config` shows redacted settings. Clear configuration only when the user asks. `doctor` calls `/meta` and consumes a service call; reuse an existing successful connection check instead of probing repeatedly.
+
+## Research workflow
+
+```bash
+python3 <skill-dir>/scripts/cli.py search "graph neural networks"
+python3 <skill-dir>/scripts/cli.py paper "<returned-paper-id>"
+python3 <skill-dir>/scripts/cli.py paper "<returned-paper-id>" --resource toc
+python3 <skill-dir>/scripts/cli.py paper "<returned-paper-id>" --resource sections --item-id "<returned-section-id>"
+```
+
+Use actual returned paper IDs with `local:`, `arxiv:`, `openalex:`, `s2:` or `doi:` prefixes. Convenience commands accept raw IDs, including DOI slashes, and encode them. Get section/asset IDs from responses. Read details and contents before relevant sections; fetch full content only when needed.
+
+Synthesize research answers from content actually read. Cite returned paper IDs, links and section evidence. Distinguish abstract evidence from full text, report missing content and avoid invented numbers. There is no documented server-side ask, trends or automatic-review endpoint.
+
+## PDF and transport
+
+```bash
+python3 <skill-dir>/scripts/cli.py upload /absolute/path/paper.pdf
+python3 <skill-dir>/scripts/cli.py task "<returned-task-id>"
+python3 <skill-dir>/scripts/cli.py task "<returned-task-id>" --result
+python3 <skill-dir>/scripts/cli.py --output /absolute/path/asset.bin paper "<returned-paper-id>" --resource assets --item-id "<returned-asset-id>"
+```
+
+Upload sends the local file to the configured service; perform it when the user requests parsing that file. Record the returned task ID, inspect actual statuses and fetch results after completion. Do not recreate tasks or poll indefinitely.
+
+Global `--framework-request-id` goes before the action and sends `X-ANYTHINGRIGHT-REQ-ID` for framework `extra.request-id`. Endpoint `--request-id` sends the separate upstream/proxy `X-Request-ID`. Repeat `--param key=value` for query parameters and `--field key=value` for upload fields. Generic `request` paths are relative to `/openapi/v2` and require separately encoded dynamic segments, including DOI slashes.
+
+When the upstream contract needs `X-MinerU-API-Key`, the user can set `LINXSCI_MINERU_API_KEY` locally. PDF create/upload/status/result commands and generic PDF requests read it.
+
+## Keep tool output small
+
+Use the default compact JSON and structured errors; `--pretty` / `--human-errors` are for terminal reading. Once the actual schema is known, use global `--select <JSON-Pointer>`, `--fields <literal,keys>` and `--limit <N>` before the action to keep only screening fields such as actual paper IDs, titles and source links. These flags only shape the local response and do not change server pagination or requests. Do not assume a `data.items` path or field aliases; derive them from the actual contract or a saved response. If metadata such as pagination is needed, retain it separately when selecting an array. Null and false values carry information and are preserved.
+
+For repeated uniform records, `--table` encodes `columns` once and returns `rows`. Get full paper content or individual sections only when needed. Endpoint output larger than 12000 characters is automatically saved as complete original bytes in a private temporary file; read the returned absolute `file` selectively using `scripts/cli.py --select <actual-pointer> --fields <actual,keys> read-output <absolute-file>`, without another API call. `truncated:true` and `preview` do not constitute full evidence. Binary assets also return file metadata. Temporary files remain available until removed. For an explicit destination use `--output /absolute/path/response.json --output-summary`. `--max-output-chars 0` disables automatic spilling for JSON/text when full output is necessary. See [all output options](references/cli.md#compact-output-and-explicit-response-views).
+
+A `response_output_error` with `request_completed:true` and `do_not_repeat:true` means the API call succeeded but local formatting/saving failed; inspect its preserved raw response file and fix the view locally. Do not repeat task creation or upload for a formatting failure. Preserve public error codes, trace IDs, Retry-After and `execution_uncertain`, especially `-3905`.
+
+## Output and failures
+
+Endpoint stdout defaults to compact JSON or file metadata. Global `--output` preserves response bytes, including binary assets. Exit codes: 0 success, 1 HTTP/network failure, 2 argument/local-file failure. Errors default to structured JSON; `--json-errors` remains a compatibility flag for these diagnostics without exposing the full upstream error message. Structured HTTP/network diagnostics expose `error_code`, `request_id`, `framework_request_id`, and `execution_uncertain`.
+
+Upstream responses and business errors keep their original format. Framework errors use `code/data/error/extra`; `extra.cost` is elapsed seconds, not a charge. Do not assume common list fields or PDF terminal states.
+
+| Error code | Action |
+| --- | --- |
+| `-401` / `-404` | Check client key / method and path |
+| `-3900` | Ask an administrator to enable the registered action; avoid repeated retries |
+| `-3901` | Wait for daily quota reset or administrative action |
+| `-3902` | Ask the administrator to configure the upstream URL/key |
+| `-3903` | Inspect upstream connectivity; failure does not prove the operation did not execute |
+| `-3904` | Request preparation failed before forwarding; contact the administrator |
+| `-3905` | Upstream returned but accounting completion is unconfirmed; check execution and billing before retrying writes |
+
+Do not treat all 502/503 errors identically. No automatic retries are performed. Preserve `Retry-After`, but it does not resolve `-3905` uncertainty. Expected call quantity is 1; upstream 2xx means actual 1, otherwise 0, with reserved-credit release confirmed by the service. Do not guarantee release based solely on HTTP failure. Avoid redundant search, diagnosis and polling. See [the API reference](references/api.md) for details.

linxsci/SKILL.zh-CN.md

@@ -0,0 +1,160 @@
+---
+name: linxsci-skills
+description: 调用 LinxSci OpenAPI v2，支持文献检索、论文内容与引用、推荐、学术实体和 PDF 解析。用于 LinxSci 研究任务、指定接口调用，以及服务健康和用量查询。
+---
+
+# linxsci-skills
+
+[English](SKILL.md)
+
+使用本 Skill 的统一入口 `scripts/cli.py`。所有示例中的 `<skill-dir>` 都替换为本文件所在目录的绝对路径；脚本仅依赖 Python 3.9+ 标准库，无需安装 SDK。
+
+## 独立安装 Skill
+
+本 Skill 不依赖终端的 `linxsci` 命令、PyPI 安装包或已安装的 SDK，直接运行随 Skill 提供的 Python 脚本。需要 Python 3.9+、支持本地 Skill 发现及脚本执行的 AI 助手；调用远程服务时还需要已有的 LinxSci API Key。
+
+### 方式一：GitHub Skill 安装器
+
+本机有 Node.js / npx 时运行：
+
+```bash
+npx skills add https://github.com/LinxSci/linxsci-skills --skill linxsci-skills
+```
+
+按安装器提示选择助手及安装范围。此方式安装完整 Skill，不需要 `pip install linxsci` 或 `uv tool install linxsci`。后续使用同一个外部安装器更新该副本。
+
+### 方式二：独立 ZIP 或下载源码
+
+解压 `linxsci-skills-0.3.1.zip`，在解压后的目录运行 `python3 install.py`（Windows 使用 `py -3 install.py`），也可双击 `Install.command` / `Install.bat`。安装器复制完整 Skill 并启动隐藏输入 Key 的配置向导。此方式不需要 pip、SDK 或 Node.js。只安装、不配置时运行 `python3 install.py --no-config`。
+
+ZIP 内的 `install.py` 支持以下参数，均放在 `install.py` 之后：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--skills-dir PATH` | `~/.agents/skills` | 助手扫描父目录，安装器追加 `/linxsci-skills` |
+| `--update` | 关闭 | 更新本工具管理的已有副本并保留备份 |
+| `--no-config` | 关闭 | 仅复制 Skill，不启动 Key 配置向导 |
+| `--online` | 关闭 | 向导建议使用正式服务根地址 |
+| `--base-url URL` | 保存/发行地址 | 明确指定向导建议的服务根地址，优先于 `--online` |
+
+`python3 install.py --help` 可查看帮助。设置 `--no-config` 后，`--online` 和 `--base-url` 不再生效。这些是 ZIP 安装器参数；独立脚本使用 `install-skill` 完成复制，再单独使用 `setup` 配置。
+
+如果下载的是仓库源码或完整 Skill 目录，可直接运行包内脚本：
+
+```bash
+python3 /absolute/path/to/source/skills/linxsci-skills/scripts/cli.py install-skill
+```
+
+默认安装位置是 `~/.agents/skills/linxsci-skills`。助手使用其他扫描目录时，加上 `--skills-dir /absolute/path/to/assistant/skills`，参数为安装父目录，不包含末尾的 `linxsci-skills`。安装后未发现 Skill 时，刷新或重启助手。
+
+### 仅使用 Skill 完成配置与验证
+
+macOS / Linux 默认安装后：
+
+```bash
+python3 "$HOME/.agents/skills/linxsci-skills/scripts/cli.py" routes
+python3 "$HOME/.agents/skills/linxsci-skills/scripts/cli.py" setup
+```
+
+Windows 使用 `py -3 "C:\absolute\path\to\linxsci-skills\scripts\cli.py" setup`。自定义安装目录时使用对应的脚本绝对路径。`routes` 不需要 Key、不联网，可验证本地脚本能否运行；`setup` 在交互终端中隐藏输入 Key、保存配置，并检查一次连接。随后在助手中使用 `$linxsci-skills`。不要让用户将 Key 发到对话中。
+
+更新本工具管理的副本时，下载或解压新版，使用**新版本源码中的** `scripts/cli.py install-skill --update`，或在新 ZIP 内执行 `python3 install.py --update --no-config`。旧副本备份到助手扫描目录之外。手动复制或外部安装器管理的副本应按原安装方式更新。必须完整保留 `SKILL.md`、`scripts/`、`references/`、`agents/`、`service.json` 及其他配套文件；仅复制 `SKILL.md` 无法执行接口。
+
+后续所有操作均使用 Skill 内 `scripts/cli.py` 的绝对路径。[命令参考](references/cli.zh-CN.md) 逐项说明独立调用方式、全部命令、参数类型、默认值、必填条件和示例。
+
+## 接口调用入口
+
+本 Skill 可调用 [接口文档](references/api.zh-CN.md) 中的全部 34 个接口，覆盖服务信息与健康、各来源搜索和标识解析、论文详情与引用、推荐、作者/机构/期刊及 PDF 解析。全部接口都提供便捷命令，按 [命令速查](references/cli.zh-CN.md) 选择；`request` 保留作通用调试入口。
+
+用户指定接口或操作时，按目标路由、参数和响应直接执行；例如查询用量不需要先检索论文，调用推荐接口不需要先走章节阅读流程。按任务需要读取接口文档，使用 `routes` 查看支持的方法与路径（不联网）。
+
+```bash
+python3 <skill-dir>/scripts/cli.py health ready
+python3 <skill-dir>/scripts/cli.py usage
+python3 <skill-dir>/scripts/cli.py search-openalex "large language models"
+python3 <skill-dir>/scripts/cli.py recommend --body @recommendations.json
+python3 <skill-dir>/scripts/cli.py resolve-entities --body @entities.json
+```
+
+四个搜索命令都直接接收检索词，可选 `--body` 提供附加 JSON 对象，检索词以位置参数为准。示例中的 JSON 文件须先按部署环境的 Agent API 契约或用户提供的参数准备。便捷命令自动选择方法和路径；JSON 请求使用 `--body @file.json`，PDF 上传接口 `/pdf/parse/upload` 使用 `upload /absolute/path/paper.pdf`，由脚本构造 multipart 的 `file` 字段。接口调用不要求助手额外完成综述或研究分析。
+
+## 配置与发现
+
+脚本优先读取环境变量 `LINXSCI_BASE_URL` 和 `LINXSCI_OPENAPI_KEY`，其次读取 `setup` 保存的用户本地配置。地址默认值是正式服务 `https://linxsci.com`，可显式配置其他部署地址；服务根地址不含 `/openapi/v2`。已有配置优先于发行默认值，升级不会自动切换用户保存的地址。不要读取、展示或让用户把 Key 发到对话。缺少配置时请用户在本机运行向导，Key 通过隐藏输入保存：
+
+```bash
+python3 <skill-dir>/scripts/cli.py setup
+# 线上地址作为默认提示：
+python3 <skill-dir>/scripts/cli.py setup --online
+```
+
+`config` 仅显示配置状态，`config --clear` 清除保存的配置；执行清除需来自用户请求。
+
+```bash
+python3 <skill-dir>/scripts/cli.py doctor
+# 需要元信息正文时再调用：
+python3 <skill-dir>/scripts/cli.py meta
+python3 <skill-dir>/scripts/cli.py routes
+```
+
+首次接入可用 `doctor`（调用 `/meta`）验证连接；它也经过用量检查和计费流程，已有有效连接结果时不重复探测。根据 [接口文档](references/api.zh-CN.md) 核对目标路由；对于未定义的业务请求模型，读取部署环境的上游契约或用户提供的请求 JSON。`meta` 不保证返回完整 schema；缺少目标接口必需的业务参数时，说明需要补充的契约或请求 JSON，不猜测字段和分页，也不擅自改为其他接口任务。
+
+## 文献工作流
+
+```bash
+python3 <skill-dir>/scripts/cli.py search 'graph neural networks'
+python3 <skill-dir>/scripts/cli.py paper 'arxiv:2301.07041'
+python3 <skill-dir>/scripts/cli.py paper 'arxiv:2301.07041' --resource toc
+python3 <skill-dir>/scripts/cli.py paper 'arxiv:2301.07041' --resource sections --item-id '<returned-section-id>'
+```
+
+从搜索结果中取实际论文 ID；先看详情、目录，再读取相关章节，需要完整文本时才读 `--resource content`。论文 ID 需要 `local:`、`arxiv:`、`openalex:`、`s2:` 或 `doi:` 前缀。便捷命令接收未经编码的 ID（例如 `doi:10.1000/example`），随附脚本负责编码。章节和资源 ID 必须取自返回结果。
+
+回答研究问题时由助手综合已读取内容，附上实际返回的论文标识、链接和章节依据。区分摘要和全文证据，说明缺失内容；不要声称存在服务端 `ask`、趋势榜或自动综述接口。
+
+## 其他接口与 PDF
+
+全部接口优先使用 [便捷命令速查](references/cli.zh-CN.md)，无需填写 HTTP 方法和路径。各来源检索、推荐、实体和 PDF 创建任务也都有独立命令。
+
+```bash
+python3 <skill-dir>/scripts/cli.py resolve --body @resolve.json
+python3 <skill-dir>/scripts/cli.py author '<returned-author-id>' --papers --param '<upstream-key>=<value>'
+python3 <skill-dir>/scripts/cli.py upload /absolute/path/paper.pdf
+python3 <skill-dir>/scripts/cli.py task '<returned-task-id>'
+python3 <skill-dir>/scripts/cli.py task '<returned-task-id>' --result
+python3 <skill-dir>/scripts/cli.py --output /absolute/path/asset.bin paper 'arxiv:2301.07041' --resource assets --item-id '<returned-asset-id>'
+```
+
+全局可选参数 `--framework-request-id <id>`（放在 `scripts/cli.py` 之后、具体动作之前）发送 `X-ANYTHINGRIGHT-REQ-ID`，对应 LinxSci 自身错误的 `extra.request-id`；各接口命令的 `--request-id <id>` 发送独立的 `X-Request-ID`。两者用途不同。通用 `request` 的路径相对于 `/openapi/v2`，每个动态 ID 独立 URL 编码（包括 DOI 中的斜杠）；查询参数用重复的 `--param key=value`。JSON 通过 `--body @file.json` 原样传入。`upload` 可传 `--field key=value`；上游契约需要 `X-MinerU-API-Key` 时，在本机设置 `LINXSCI_MINERU_API_KEY`，`parse-pdf`、`upload`、`task`（含 `--result`）及通用 PDF `request` 都会读取它。
+
+上传会发送本地文件到配置服务，仅在用户请求解析该文件时执行。任务状态结构未定义，使用实际返回的标识和状态；不自动无限轮询或重复创建任务，确认完成后获取结果。
+
+## 控制工具输出量
+
+默认使用紧凑 JSON 和结构化错误，`--pretty` / `--human-errors` 仅用于人工终端阅读。确认真实响应模型后，可将全局 `--select <JSON-Pointer>`、`--fields <字面字段,列表>`、`--limit <N>` 放在动作之前，仅保留筛选所需的真实论文 ID、标题、来源链接等字段。这些选项只调整本地响应，不改变请求或服务端分页；不能猜测 `data.items` 路径或字段别名，应按实际契约或保存的响应选择。选择数组时如需分页等外层元信息，应另外保留。`null` 和 `false` 有语义，不会自动丢弃。
+
+大量字段一致的记录可用 `--table`，仅声明一次 `columns` 并返回 `rows`。全文或具体章节按需获取。接口输出超过 12000 字符时自动将完整原始字节保存到私有临时文件，应通过 `scripts/cli.py --select <真实路径> --fields <真实,字段> read-output <文件绝对路径>` 按需读取，不再次调用 API。`truncated:true` 和 `preview` 不代表完整证据；二进制资源同样返回文件元信息。临时文件保留到读取后自行删除。指定路径时使用 `--output /absolute/path/response.json --output-summary`；确需完整 JSON/文本时可用 `--max-output-chars 0` 关闭自动转存。详见 [全部输出选项](references/cli.zh-CN.md#紧凑输出与显式响应筛选)。
+
+`response_output_error` 配合 `request_completed:true`、`do_not_repeat:true` 表示接口已成功执行，仅本地格式化/保存失败，应读取保留的原始响应文件并在本地修正，不能为格式问题重复上传或创建任务。保留业务错误码、两种请求 ID、Retry-After 和 `execution_uncertain`，尤其不能丢失 `-3905` 的含义。
+
+## 输出与故障
+
+接口 stdout 默认输出紧凑 JSON 或文件元信息；`--output`（放在 `scripts/cli.py` 之后、具体动作之前）保留响应原始字节，适用于二进制资源。上游响应原样透传，LinxSci 自身错误则使用 `code/data/error/extra` 框架结构；读取 `error.code` 和 `extra.request-id`，不把它当作上游业务模型。`extra.cost` 是请求耗时（秒），不是扣费金额。不要假定列表字段或 PDF 终态。
+
+退出码：0 成功，1 HTTP/网络错误，2 参数/本地文件错误。随附脚本的结构化 HTTP/网络诊断提供 `error_code`、`request_id`、`framework_request_id`、`execution_uncertain`。随附脚本默认输出紧凑的结构化 JSON 诊断，保留可用的两种请求 ID；`--json-errors` 是兼容选项，`--human-errors` 切换文本诊断，不展示服务端错误消息全文。
+
+按 HTTP 状态和实际 `error.code` 区分故障：
+
+| error.code | 处理 |
+| --- | --- |
+| `-401` / `-404` | 检查 LinxSci Key / 路径和方法 |
+| `-3900` | action 已登记但未启用，联系管理员配置并启用；不要反复重试 |
+| `-3901` | 每日调用限额已满，额度恢复后或管理员处理后再调用 |
+| `-3902` | 服务端 Agent API 地址或 Key 缺失，联系管理员 |
+| `-3903` | 上游连接/传输失败，检查连接；不要将失败等同于业务操作一定未执行 |
+| `-3904` | 请求准备失败，未转发上游，联系管理员排查 |
+| `-3905` | 上游已返回但计量完成尚未确认，先查询执行与计费结果，再决定是否重试，尤其不要直接重复上传或创建解析任务 |
+
+上游业务错误（例如 `validation_error`、`asset_unavailable`）保留其原有格式；不要把全部 502/503 当作相同原因。脚本不自动重试；保留 `Retry-After`，但它不能替代 `-3905` 的执行/计费核查。
+
+每次请求预计调用量为 1，Agent API 2xx 对应实际调用量 1，其他状态或连接失败对应 0，预占释放由 服务确认计量完成后确定。不要根据 HTTP 失败自行保证扣费已经释放，尤其遇到 `-3905`。避免无目的的重复检索、诊断与轮询；查询动作也走调用限额。详细规则见 [references/api.md](references/api.zh-CN.md)。

linxsci/__init__.py

@@ -0,0 +1,5 @@
+"""LinxSci SDK and self-contained Agent Skill."""
+from .scripts.client import Response, LinxSciClient, LinxSciError
+
+__version__ = "0.3.1"
+__all__ = ["Response", "LinxSciClient", "LinxSciError"]

linxsci/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "linxsci-skills"
+  short_description: "Search papers, read citations, and parse PDFs with LinxSci"
+  default_prompt: "Use $linxsci-skills to find papers on a topic, read relevant sections, and summarize the evidence with sources."

linxsci/references/api.md

@@ -0,0 +1,98 @@
+# LinxSci OpenAPI v2
+
+[简体中文](api.zh-CN.md)
+
+Use the service root `https://linxsci.com` with the `/openapi/v2` prefix. All endpoints require a LinxSci API key. JSON business fields, pagination and task status fields follow the selected endpoint's API contract.
+
+## Authentication and tracing
+
+| Header | Required | Purpose |
+| --- | --- | --- |
+| `Authorization: Bearer <LinxSci OpenAPI Key>` | Yes | Client authentication |
+| `X-Request-ID` | No | Provider/proxy trace ID; the SDK generates one when omitted |
+| `X-ANYTHINGRIGHT-REQ-ID` | No | Framework trace ID, returned as `extra.request-id` on framework errors; generated by the service when omitted |
+| `X-MinerU-API-Key` | When required | Additional key for PDF parsing endpoints |
+
+Configure the client key using local setup or `LINXSCI_OPENAPI_KEY`. The service handles its own provider authentication; client applications only supply the headers above as needed.
+
+## Routes
+
+| Category | Method | LinxSci path | Endpoint |
+| --- | --- | --- | --- |
+| Service and health | GET | `/openapi/v2/meta` | API metadata |
+| Service and health | GET | `/openapi/v2/usage` | Usage |
+| Service and health | GET | `/openapi/v2/health/live` | Liveness |
+| Service and health | GET | `/openapi/v2/health/ready` | Readiness |
+| Search and resolution | POST | `/openapi/v2/papers/search` | Paper search |
+| Search and resolution | POST | `/openapi/v2/search/openalex` | OpenAlex search |
+| Search and resolution | POST | `/openapi/v2/search/semantic-scholar` | Semantic Scholar search |
+| Search and resolution | POST | `/openapi/v2/search/google-scholar` | Google Scholar search |
+| Search and resolution | POST | `/openapi/v2/papers/resolve` | Resolve paper identifiers |
+| Search and resolution | POST | `/openapi/v2/papers:batchGet` | Batch paper lookup |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}` | Paper details |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/content` | Paper content |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/toc` | Table of contents |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/sections/{section_id}` | Section |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/figures` | Figures |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/assets/{asset_id}` | Assets |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/references` | References |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/citations` | Citing papers |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/related` | Related papers |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/graph` | Citation graph |
+| Papers and citations | GET | `/openapi/v2/papers/{paper_id}/citation` | Citation format |
+| Recommendations | POST | `/openapi/v2/recommendations` | Recommendations |
+| Recommendations | GET | `/openapi/v2/recommendations/mobile-cards` | Mobile recommendation cards |
+| Authors, institutions and venues | GET | `/openapi/v2/authors/{author_id}` | Author details |
+| Authors, institutions and venues | GET | `/openapi/v2/authors/{author_id}/papers` | Author papers |
+| Authors, institutions and venues | GET | `/openapi/v2/institutions/{institution_id}` | Institution details |
+| Authors, institutions and venues | GET | `/openapi/v2/institutions/{institution_id}/papers` | Institution papers |
+| Authors, institutions and venues | GET | `/openapi/v2/venues/{venue_id}` | Venue details |
+| Authors, institutions and venues | GET | `/openapi/v2/venues/{venue_id}/papers` | Venue papers |
+| Authors, institutions and venues | POST | `/openapi/v2/entities:resolve` | Resolve entity identifiers |
+| PDF parsing | POST | `/openapi/v2/pdf/parse` | Create a PDF parsing task |
+| PDF parsing | POST | `/openapi/v2/pdf/parse/upload` | Upload a PDF and create a task |
+| PDF parsing | GET | `/openapi/v2/pdf/parse/{task_id}` | Task status |
+| PDF parsing | GET | `/openapi/v2/pdf/parse/{task_id}/result` | Task result |
+
+Paper IDs support `local:`, `arxiv:`, `openalex:`, `s2:`, and `doi:` prefixes. Encode each dynamic path segment, including slashes in DOIs, for example `doi:10.1000%2Fexample`. Convenience SDK/CLI methods accept raw IDs and encode them. Generic requests require pre-encoded paths. Prepare POST JSON according to the endpoint contract; `{}` is not a universally valid request. PDF upload uses the multipart `file` field; file limits and additional fields depend on the service.
+
+## Usage and limits
+
+Each request has an expected call quantity of 1. A provider 2xx response corresponds to an actual quantity of 1; other statuses or connection failures correspond to 0. Reserved credits are released after the service confirms accounting completion. A failed HTTP response alone does not establish that credits have been released. Daily limits and endpoint availability are enforced by the service; inspect `usage` and the error codes below when needed.
+
+## Responses and errors
+
+Successful provider responses retain their status, body and relevant headers (`Content-Type`, `X-Request-ID`, `Retry-After`, and `Cache-Control`). Provider business errors such as `validation_error` and `asset_unavailable` keep their own response schemas. The SDK preserves raw response bytes. CLI presentation, field selection and file output are described in the [command guide](cli.md#compact-output-and-explicit-response-views).
+
+Framework authentication, service configuration, usage and connection errors use:
+
+```json
+{
+  "code": -1,
+  "data": {},
+  "error": {
+    "code": -3900,
+    "msg": "This endpoint is not enabled. Contact the service administrator."
+  },
+  "extra": {"request-id": "example-request-id", "cost": 0.01}
+}
+```
+
+This example has HTTP status 503. `extra.cost` is elapsed time in seconds, not a monetary charge. `extra.request-id` comes from `X-ANYTHINGRIGHT-REQ-ID` or is generated by the service.
+
+| HTTP | `error.code` | Meaning and action |
+| --- | --- | --- |
+| 401 | `-401` | Missing or invalid client key; check Authorization or run setup |
+| 404 | `-404` | Unsupported method or path; check the route table |
+| 503 | `-3900` | Endpoint not enabled; contact the service administrator |
+| 429 | `-3901` | Daily limit reached; wait for reset or contact the administrator |
+| 503 | `-3902` | Provider connection settings are missing; contact the administrator |
+| 502 | `-3903` | Provider connection/transport failed; check service connectivity before retrying |
+| 502 | `-3904` | Request preparation failed before forwarding; contact the administrator |
+| 502 | `-3905` | Provider returned but accounting completion is unconfirmed; check execution and billing before retrying |
+
+Preserve both trace IDs and any `Retry-After` value for troubleshooting. Do not automatically repeat uploads or task creation after an uncertain result. In particular, `-3905` does not mean the operation failed to execute, and `Retry-After` does not resolve that uncertainty.
+
+## Manual clients
+
+In Postman or another HTTP client, configure the service root and bearer key, then use the routes above. For POST requests, prepare the documented endpoint-specific JSON. For `/openapi/v2/pdf/parse/upload`, select the local PDF in the multipart `file` field.

linxsci/references/api.zh-CN.md

@@ -0,0 +1,98 @@
+# LinxSci OpenAPI v2 使用文档
+
+[English](api.md)
+
+服务根地址为 `https://linxsci.com`，接口前缀为 `/openapi/v2`，所有接口均需要 LinxSci API Key。业务 JSON 字段、分页及任务状态字段按对应接口的 API 契约使用。
+
+## 认证与请求追踪
+
+| 请求头 | 是否必填 | 用途 |
+| --- | --- | --- |
+| `Authorization: Bearer <LinxSci OpenAPI Key>` | 是 | 客户端鉴权 |
+| `X-Request-ID` | 否 | 上游/代理请求追踪；未提供时 SDK 自动生成 |
+| `X-ANYTHINGRIGHT-REQ-ID` | 否 | 框架请求追踪，对应框架错误的 `extra.request-id`；未提供时由服务生成 |
+| `X-MinerU-API-Key` | 按需 | PDF 解析接口所需的附加 Key |
+
+客户端 Key 可通过本机配置向导或 `LINXSCI_OPENAPI_KEY` 设置。上游服务鉴权由 LinxSci 管理，客户端仅需按要求提供上述请求头。
+
+## 接口目录
+
+| 分类 | 方法 | LinxSci 路径 | 接口 |
+| --- | --- | --- | --- |
+| 服务信息与健康检查 | 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 解析结果 |
+
+论文 ID 支持 `local:`、`arxiv:`、`openalex:`、`s2:`、`doi:` 前缀。动态路径段需分别 URL 编码，包含 DOI 中的斜杠，例如 `doi:10.1000%2Fexample`。SDK/CLI 便捷方法接收原始 ID 并自动编码；通用请求接收已编码路径。POST JSON 按接口契约准备，不能假定 `{}` 通用有效。PDF 上传使用 multipart 的 `file` 字段，文件大小限制及附加字段由服务决定。
+
+## 用量与限额
+
+每次请求的预计调用量为 1。上游返回 2xx 时实际调用量为 1，其他状态或连接失败时为 0。预占积分在服务确认计量完成后释放，不能仅根据 HTTP 失败保证已经释放。每日限额及接口可用性由服务检查，需要时通过 `usage` 和下表错误码排查。
+
+## 响应与错误
+
+成功的上游响应保留其状态、响应体及相关响应头（`Content-Type`、`X-Request-ID`、`Retry-After`、`Cache-Control`）。`validation_error`、`asset_unavailable` 等业务错误保留原有响应模型。SDK 保留原始响应字节；CLI 的显示、字段筛选及文件输出见 [命令指南](cli.zh-CN.md#紧凑输出与显式响应筛选)。
+
+鉴权、服务配置、用量及连接等框架错误采用：
+
+```json
+{
+  "code": -1,
+  "data": {},
+  "error": {
+    "code": -3900,
+    "msg": "This endpoint is not enabled. Contact the service administrator."
+  },
+  "extra": {"request-id": "example-request-id", "cost": 0.01}
+}
+```
+
+该示例的 HTTP 状态为 503。`extra.cost` 是耗时，单位为秒，不是扣费金额。`extra.request-id` 来自 `X-ANYTHINGRIGHT-REQ-ID`，或由服务生成。
+
+| HTTP | `error.code` | 含义与处理 |
+| --- | --- | --- |
+| 401 | `-401` | 客户端 Key 缺失或无效，检查 Authorization 或重新运行配置向导 |
+| 404 | `-404` | 方法或路径不支持，核对接口目录 |
+| 503 | `-3900` | 接口未启用，联系服务管理员 |
+| 429 | `-3901` | 达到每日限额，等待额度恢复或联系管理员 |
+| 503 | `-3902` | 上游服务连接配置缺失，联系管理员 |
+| 502 | `-3903` | 上游连接或传输失败，检查服务连接后再决定是否重试 |
+| 502 | `-3904` | 请求准备失败，尚未转发，联系管理员 |
+| 502 | `-3905` | 上游已返回，但计量完成尚未确认，先核查执行和计费结果再决定是否重试 |
+
+排查问题时保留两种请求 ID 和 `Retry-After`（如有）。结果不确定时，不自动重复上传或创建任务。尤其 `-3905` 不代表操作未执行，`Retry-After` 也不能替代执行结果核查。
+
+## 手动调用
+
+在 Postman 或其他 HTTP 客户端中设置服务根地址和 Bearer Key，再按上表选择方法和路径。POST 使用对应接口要求的 JSON。调用 `/openapi/v2/pdf/parse/upload` 时，在 multipart 的 `file` 字段选择本地 PDF。