library-book-search

图书馆图书搜索（Data4Library）

此技能的功能

通过 k-skill-proxy 代理的 HTTP API 查询韩国国立中央图书馆的 图书馆信息之海（Data4Library） 开放 API。

• 按关键词搜索图书。
• 通过 ISBN 查看详细书目和借阅信息。
• 通过 ISBN + 地区代码查找拥有该图书的图书馆列表。
• 通过图书馆代码 + ISBN 确认特定图书馆的馆藏/可借状态。

使用时机

• “帮我用图书馆信息之海找历史相关的书”
• “找拥有这个 ISBN 的首尔图书馆”
• “确认正读图书馆是否有这本书”
• “能查询图书馆图书吗？”

前提条件

• 互联网连接
• 可使用 curl 的环境
• 可访问配置了 DATA4LIBRARY_AUTH_KEY 的 k-skill-proxy 部署（默认托管或自托管）

凭据要求

用户无需任何密钥，DATA4LIBRARY_AUTH_KEY 仅在代理服务器上管理。

• 用户侧 无需必需密钥。
• KSKILL_PROXY_BASE_URL — 仅在使用自托管或单独代理时设置。留空则使用默认托管地址 https://k-skill-proxy.nomadamas.org。
• DATA4LIBRARY_AUTH_KEY 仅放在 代理服务器 环境中。不要求用户提供认证密钥，也不在响应中暴露。

代理基础 URL

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
BASE="${BASE%/}"

工作流程

1) 收集意图和最小输入

根据用户请求，仅询问所需的值。

• 关键词图书搜索：只需 keyword 即可开始。
• 详细查询：需要 ISBN（10位或13位）。
• 馆藏图书馆查询：需要 ISBN + 广域地区代码（region）。如果有市郡区详细代码（dtl_region），可一并使用。
• 特定图书馆馆藏确认：需要图书馆代码（libraryCode）+ ISBN。

如果没有图书馆代码或地区代码，先通过 library-search 显示候选，或向用户询问更多已知的图书馆名称或地区。如果仅凭名称无法确定，不随意选择一个。

2) 搜索图书（/v1/data4library/book-search）

curl -fsS --get "${BASE}/v1/data4library/book-search" \
  --data-urlencode "keyword=역사" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

别名：也接受 q、query、page、limit。

响应中 response.docs[].doc 主要字段：

• bookname — 书名
• authors — 作者
• publisher — 出版社
• publication_year — 出版年份
• isbn13 — 用于详细/馆藏查询的 ISBN

3) 获取图书详情（/v1/data4library/book-detail）

curl -fsS --get "${BASE}/v1/data4library/book-detail" \
  --data-urlencode "isbn13=9788971998557" \
  --data-urlencode "loaninfoYN=Y"

• 提供 loaninfoYN=Y 时，会同时请求上游提供的热门借阅地区、年龄、借阅次数等附加信息。
• 如果详细响应为空，提示可能是 ISBN 错误、未收录图书或上游延迟。

4) 查找拥有某书的图书馆（/v1/data4library/libraries-by-book）

curl -fsS --get "${BASE}/v1/data4library/libraries-by-book" \
  --data-urlencode "isbn=9788971998557" \
  --data-urlencode "region=11" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

• region 是图书馆信息之海的地区代码。例如，需要首尔特别市代码时使用 11 这样的数字代码。
• 如果有 dtl_region，可进一步缩小范围。
• 如果结果有多个，摘要显示图书馆名称、地址、主页、电话（如果响应中有），实时可借状态通过单独的 book-exists 确认。

5) 检查单个图书馆的馆藏（/v1/data4library/book-exists）

curl -fsS --get "${BASE}/v1/data4library/book-exists" \
  --data-urlencode "libraryCode=111001" \
  --data-urlencode "isbn13=9788971998557"

• 直接解释 hasBook、loanAvailable 等上游响应字段。
• 可借状态可能因图书馆系统同步延迟而不准确，建议最终访问前通过图书馆主页或电话确认。

6) 可选：图书馆列表（/v1/data4library/library-search）

curl -fsS --get "${BASE}/v1/data4library/library-search" \
  --data-urlencode "region=11" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=10"

为用户总结

• 首先整理书名、作者、出版社、出版年份、ISBN。
• 馆藏图书馆列表根据用户的地区和移动可能性，仅显示主要候选。
• 不要冗长地粘贴整个 JSON，而是建议所需字段和下一步（详细查询/馆藏确认/图书馆选择）。

上游参考

• 图书馆信息之海开放 API 使用方法：https://www.data4library.kr/apiUtilization

失败模式

• 代理未设置 DATA4LIBRARY_AUTH_KEY → 503 / upstream_not_configured
• 缺少关键词、ISBN、地区代码、图书馆代码 → 400 / bad_request
• ISBN 位数错误 → 使用去除连字符的 ISBN-10（允许末尾 X）或 ISBN-13 重新请求
• 图书馆代码/地区代码不明确 — 向用户显示候选并让其选择
• Data4Library API 临时故障、调用限制、数据未收录

注意事项

• 基本姿态是只读查询。不进行预约、借阅、基于个人信息的图书馆登录自动化。
• DATA4LIBRARY_AUTH_KEY 仅用于代理服务器。用户侧没有密钥。
• 代理会注入上游 authKey 和 format=json，因此不信任用户传递的 authKey/format。