朝鲜王朝实录조선왕조실록搜索技能实战基于 k-skill 的 sillok_search.py 官方站点抓取方案【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本技术指南围绕 k-skill 开源仓库中的joseon-sillok-search技能展开讲解如何借助 nomadamas/k-skill CLI 与随附的 sillok_search.py 脚本直接读取韩国国史编纂委员会국사편찬위원회官方实录网站sillok.history.go.kr的公开 HTML完成关键词检索、王名/年份过滤、结果摘要与文章详情국역/원문抽取。读完本文你将掌握该技能的全部 CLI 参数语义、端到端工作流、底层 HTML 解析原理、分页与过滤算法以及通过单元测试验证的工程细节可直接复制命令用于真实的历史文献检索场景。一、技能定位面向 Agent 的官方实录检索器joseon-sillok-search是 k-skill 技能集仓库目录joseon-sillok-search/同时以packages/k-skill-cli/skills/joseon-sillok-search/形式随 CLI 分发包捆绑中的一个history 类别技能其skill.json中的 profile 为lookup查询类面向ko-KR韩国语场景版本标记为 v1。它的核心定位在 instruction.md 中说得非常直白不依赖任何第三方 API、不维护本地索引而是直接对官方站点的「搜索结果显示页 HTML」和「文章详情页 HTML」进行抓取与解析。v1 的能力范围被刻意收敛为关键词检索keyword search可选的按王名过滤--king可选的按公元纪年过滤--year整理检索结果的标题 / 摘要 / 原文链接从文章详情页抽取 국역韩文翻译与 원문汉文原文摘要该技能适合以下典型用户请求文档「When to use」章节给出的示例조선왕조실록에서 훈민정음 찾아줘在实录里找训民正音세종 때 실록에서 측우기 관련 기사 검색해줘检索世宗时期实录中测雨器相关条目1443년 조선왕조실록 기록 찾아줘查找 1443 年的实录记录정조실록에서 수원 관련 기록 몇 개 보여줘从正祖实录中展示几条水原相关记录这些自然语言请求由 Agent 理解后转换为下文将详述的 CLI 调用。二、运行前提与输入参数2.1 前提条件Prerequisites按官方文档运行本技能只需满足可用的互联网连接所有数据均实时抓取自官方站点python3运行环境无需任何 API Key这也是该方案最大的易用性来源helper 脚本sillok_search.py已随nomadamas/k-skillCLI 打包也可直接阅读仓库源码 joseon-sillok-search/scripts/sillok_search.py。脚本对第三方依赖的要求极低requests属于可选依赖源码第 17-20 行以 try/except 方式导入缺失时自动退化为标准库urllib因此即便在无pip install的裸环境里也能运行。2.2 输入参数总览文档「Inputs」章节与源码 parse_args 函数 共同定义了完整的命令行参数面参数必选类型默认值说明--query✅ 必选str无发送给实录站点的检索关键词缺省直接报错--king可选str无王名过滤如세종、정조、세종실록自动做别名规范化--year可选int正整数无公元纪年过滤如1443源码用positive_int校验传入0或负数会抛出ArgumentTypeError有对应测试test_rejects_non_positive_year--limit可选int正整数5源码DEFAULT_LIMIT返回结果条数上限--type可选k或wkk 국역韩文翻译检索w 원문汉文原文检索--timeout可选int正整数30秒源码DEFAULT_TIMEOUTHTTP 超时时间需要特别说明--type的语义官方站点对「翻译文本」与「原文文本」分别建了检索通道选择w意味着直接在汉文原文里匹配关键词例如检索「임진왜란/壬辰倭乱」的古文写法时更精确。三、端到端工作流文档「Workflow」章节给出了 5 步标准流程与源码 search_sillok 函数 的实现一一对应发起官方检索通过 CLI 调用npx -y nomadamas/k-skill0 exec joseon-sillok-search scripts/sillok_search.py -- --query ...向官方检索 endpoint 发送 POST 请求解析结果页从返回的搜索 HTML 中解析出结果总数、按王分类的统计왕별 분류、文章链接与摘要收窄结果按需追加--king、--year再次过滤这一步既可以放在请求时也可以依赖脚本内置过滤逐篇抓详情对选中的每篇文章打开/id/article_id详情页抽取 국역 与 원문 摘要结构化输出将所有数据组装为结构化的 JSON 返回给调用方。3.1 CLI 实战命令文档「CLI examples」提供的四条命令可直接复制运行覆盖了参数组合的主要形态# 基础关键词检索默认检索 국역、最多 5 条 npx -y nomadamas/k-skill0 exec joseon-sillok-search scripts/sillok_search.py -- --query 훈민정음 # 组合过滤王名 公元年份 条数 npx -y nomadamas/k-skill0 exec joseon-sillok-search scripts/sillok_search.py -- --query 훈민정음 --king 세종 --year 1443 --limit 3 # 王名别名自动规范化세종실록 会被归一为 세종 npx -y nomadamas/k-skill0 exec joseon-sillok-search scripts/sillok_search.py -- --query 측우기 --king 세종실록 --limit 5 # 切换到汉文原文检索通道 npx -y nomadamas/k-skill0 exec joseon-sillok-search scripts/sillok_search.py -- --query 임진왜란 --type w --limit 5命令语法说明exec joseon-sillok-search scripts/sillok_search.py指示 k-skill CLI 在技能目录内执行scripts/sillok_search.py双横线--之后是传给该脚本的自身参数。若不用 npx也可直接以python3 scripts/sillok_search.py --query 훈민정음的方式运行仓库内的源码。四、源码深度解析抓取与解析原理4.1 网络层浏览器式请求头 双客户端容错源码顶部常量定义了三个核心 URL与文档「Notes」章节完全一致官方主页https://sillok.history.go.kr检索 endpointhttps://sillok.history.go.kr/search/searchResultList.doPOST文章详情https://sillok.history.go.kr/id/article_idGETDEFAULT_HEADERS模拟了真实浏览器的请求特征Accept-Language: ko-KR、Referer: https://sillok.history.go.kr/main/main.do以及一个完整的 Chrome/136 macOS UA 串。这类「以公开 HTML 表面为数据源」的方案必须携带贴近真实浏览器的头以提高请求被站点正常响应的概率。HTTP 客户端采用双通道策略build_http_client / fetch_text优先使用requests库若已安装发起 POST/GET若requests不可用、或抛出传输类异常RequestException、OSError自动回退到标准库urllib的OpenerDirector其内部挂载了HTTPCookieProcessorCookieJar 维持会话与HTTPSHandler默认 TLS 校验值得强调的是HTTP 错误HTTPError不会触发回退而是直接抛错TLS 校验始终开启ssl.create_default_context()这一点被测试test_build_opener_keeps_default_tls_verification和test_fetch_text_keeps_requests_tls_verification_enabled显式锁定防止未来改动意外关闭证书校验。4.2 检索请求体构造build_search_payload源码 L423-L431构造的 POST 表单字段为字段值含义topSearchWord用户关键词检索词pageIndex页码从 1 开始分页游标initPageUnit0初始化分页单元typek/w检索通道sillokTypeS实录类型topSearchWord_imespan classnewbatang…/span高亮样式用的 HTML 回显4.3 搜索结果页解析parse_search_results源码 L334-L378通过三组正则从结果页 HTML 中抽取信息结果总数优先读取隐藏字段totalCount失败则回退到页面文本「검색결과N개」分通道计数按--type选择隐藏字段countK국역/countW원문/countM/countC中的对应项用于后续分页总数计算王别分类统计匹配classcate-item的链接其 href 为javascript:searchCategory(...)解析出形如「세종 (5)」的分类标签与命中数存入categories列表结果条目匹配classresult-box区块从中提取goView(article_id, n)跳转函数里的文章 ID、classsubject的标题、classtext的摘要并拼接出https://sillok.history.go.kr/id/article_id形式的正式链接。4.4 标题元数据解析王名规范化与纪年换算这是本技能最具历史领域特色的部分。实录条目标题形如세종실록 102권, 세종 25년 12월 30일 경술 2번째기사 / 훈민정음을 창제하다parse_result_title_metadata源码 L312-L331要做三件事拆分文章标题以/为界取后半段作为article_title如「훈민정음을 창제하다」解析王名与纪年用正则捕获「XX N년」或「XX 즉위년」即位年即位年视为第 1 年换算公元年份查KING_ACCESSION_YEARS表拿到该王即位时的公元年再执行gregorian_year accession_year regnal_year即位年特殊处理为直接取即位年。该表覆盖从 태조(1392) 到 순종(1907)、순종부록(1910) 的全部 25 位王及增修/修正本。王名别名规范化由 normalize_king_name 与KING_ALIASES表实现用户输入「세종실록」「정조실록」「연산군일기」等带后缀写法时会被统一映射为 canonical 王名如세종、연산군而「선조수정실록」→「선조수정」、「순종실록부록」→「순종부록」等特殊卷也都有独立条目。这正好印证了文档「Response policy」中「输入的王名稍有不同也能归一到 canonical 王名」的承诺。4.5 过滤与分页算法filter_results源码 L381-L397在客户端侧做二次过滤王名用规范化后的名称做精确匹配年份则按换算出的公元年份做精确相等比较。search_sillok中的分页主循环源码 L471-L487是关键设计点从pageIndex1开始逐页抓取首页返回后用type_count / 每页条数向上取整算出总页数并受MAX_PAGES 20硬上限保护当过滤条件命中率低时会继续向后翻页直到累计过滤结果达到limit或当前页为空——测试test_search_continues_to_later_pages_for_filtered_matches专门验证了「第 1 页全是非目标王条目、第 2 页才命中」时会正确请求第 2 页最终只对filtered_results[:limit]中的文章逐篇抓取详情页。4.6 详情页解析与文本清洗parse_detail_page源码 L400-L420从/id/article_id页面提取headerclasstitle中的日期行含「세종실록102권, 세종 25년 12월 30일 경술 2/2 기사 / 1443년 명 정통(正統) 8년」这种中韩历法对照信息titleh3中的文章标题국역 文本classview-item left区块内classview-text원문 文本classview-item right区块内classview-text분류分类classview_font02的列表项如「어문학-어학(語學)」。清洗层clean_text/clean_article_text源码 L203-L219依次执行剔除 HTML 注释 → 将br转成换行 → 剥离标签 → 反转义实体 → 压缩空白。clean_article_text还会用DETAIL_FOOTER_PATTERN精确裁剪掉文末的版本注记与版权行——形如【태백산사고본】 33책 102권 42장 A면 【국편영인본】 4책 533면的书志学信息以及ⓒ 세종대왕기념사업회版权脚注避免污染正文测试test_strips_bibliographic_and_copyright_footer_from_article_text验证了该行为。4.7 结构化 JSON 输出脚本最终输出search_sillok 返回值的顶层结构为{ query: 훈민정음, type: k, filters: { king: 세종, year: 1443, limit: 3 }, total_results: 21, type_count: 11, returned_count: 3, categories: [ { label: 세종, count: 5, token: ... } ], items: [ { article_id: kda_12512030_002, url: https://sillok.history.go.kr/id/kda_12512030_002, title: 세종실록 102권, ... / 훈민정음을 창제하다, article_title: 훈민정음을 창제하다, summary: 이달에 임금이 친히 언문 28자를 지었다., king: 세종, regnal_year: 25, gregorian_year: 1443, detail: { header: ..., title: ..., translated_text: ..., original_text: ..., classification: 어문학-어학(語學) }, excerpt: 국역正文前 280 字符无 국역 时退化为 summary 前 280 字符 } ] }excerpt字段的设计值得一提它取详情页 국역 正文的前 280 字符作为可读摘要若详情缺失则回退到结果页 summary保证 Agent 始终有可供引用的文本。任何网络/解析异常都会以{error: ...}JSON 形式输出到 stderr 并返回退出码 1main 函数。五、测试验证工程可靠性的保障仓库在 scripts/test_sillok_search.py 中提供了完整的unittest测试套件与 scripts/test_sillok_search.py 同源构建了含真实 DOM 结构的样例 HTML覆盖以下关键行为标题元数据解析세종 25년→ 纪年 25、公元 1443문종 즉위년→ 纪年 1、公元 1450即位年特殊规则结果页解析总数 21、국역 计数 11、分类「전체/세종/정조」及其计数、条目 ID 与 URL 拼接王/年过滤king세종, year1443后只保留目标条目kda_12512030_002详情页解析국역/원문/분류 三字段抽取以及书志脚注与版权行的剥离网络回归默认 TLS 校验保持开启、requests传输失败时回退urllib、构建客户端时 opener 始终可用跨页翻页过滤命中在第 2 页时能正确继续抓取参数校验--year 0被拒绝。这些测试既可作为回归保护也是理解各解析函数输入输出契约的最佳样例——例如 SAMPLE_DETAIL_HTML 中「훈민정음을 창제하다」对应的 원문 为「○是月, 上親制諺文二十八字。」完整示范了韩汉对照的抽取结果。六、响应策略与完成标准文档「Response policy」与「Done when」明确了 Agent 的行为边界也是使用本技能时应遵循的规则回答内容以官方实录站点确认的「文章标题 链接 摘要 详情摘要」为核心链接统一整理为https://sillok.history.go.kr/id/...格式年份语义--year一律按公元纪年过滤源码中的gregorian_year字段即由此而来王名归一세종、세종실록等输入差异会自动归一化不做过度推断v1 明确不实现semantic search、embedding、大规模索引构建源码也确无相关代码只做公开 HTML 表面抓取空结果如实报告命中 0 条时不得臆造内容原样返回空结果判定完成的条件官方站点真实检索到 ≥1 条结果、必要时王/年过滤已生效、至少包含 1 条文章详情摘要、链接均为官方/id/格式。七、适用边界与注意事项该方案依赖官方站点的公开 HTML 结构与接口稳定性站点改版可能导致解析正则失效届时需同步更新 sillok_search.py 中的正则常量抓取属于对公网资源的轻量访问脚本已内置 30 秒超时、20 页翻页上限建议按需控制--limit避免大规模并发请求数据版权归国史编纂委员会所有文中链接指向官方页面适合学术检索与个人研究用途若使用 CLI 分发版本指令以npx -y nomadamas/k-skill0 instruct joseon-sillok-search输出的最新内容为准helper 文件清单可通过npx -y nomadamas/k-skill0 files joseon-sillok-search查看见 SKILL.md。从「关键词 → 王/年过滤 → 详情抽取 → 结构化 JSON」的完整链路看joseon-sillok-search是一个无密钥依赖、工程化程度高正则解析、纪年换算、双客户端容错、280 字符摘要、跨页翻页均有源码与测试支撑的领域查询技能可作为 Agent 在历史文献检索场景中的开箱即用组件。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考