Skill Seekers 多源抓取实战指南17 类来源自动检测、配置与故障排查全解析【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_SeekersSkill Seekers 是一套把文档网站、GitHub 仓库、PDF、视频、团队 Wiki 等知识源转换为 Claude AI Skill 的开源工具链而create命令是这一切的单一入口。本篇以 docs/user-guide/02-scraping.md 为骨架结合仓库源码如 source_detector.py、create_command.py深度展开读完你将掌握来源自动检测的底层判定逻辑、17 类来源的完整命令与参数、统一 JSON 配置格式的字段细节以及限流、断点续抓、流式处理等实战排障手段能够独立把任意知识源高质量抓取成可用的 Skill 草稿。一、抓取体系总览17 类来源一张表Skill Seekers 可以提取17 类来源的知识。绝大多数来源都可以直接作为create的 positional 参数传入由系统自动判定类型只有 Confluence、Notion、Slack/Discord 三类由于依赖 API 或导出目录需要走专属参数或对应子命令。SourceCommandBest ForDocumentationcreate urlWeb docs, tutorials, API refsGitHubcreate repoSource code, issues, releasesPDFcreate file.pdfManuals, papers, reportsLocalcreate ./pathYour projects, internal codeWordcreate file.docxReports, specificationsEPUBcreate file.epubE-books, long-form docsVideocreate url/fileTutorials, presentationsJupytercreate file.ipynbData science, experimentsLocal HTMLcreate file.htmlOffline docs, saved pagesOpenAPIcreate spec.yamlAPI specs, Swagger docsAsciiDoccreate file.adocTechnical documentationPowerPointcreate file.pptxSlide decks, presentationsRSS/Atomcreate feed.rssBlog feeds, news sourcesMan Pagescreate cmd.1Unix command documentationConfluenceconfluenceTeam wikis, knowledge basesNotionnotionWorkspace docs, databasesSlack/DiscordchatChat history, discussions注本指南以 Skill Seekers v3.9.0 为基准命令与参数以当前仓库实际实现为准。二、来源自动检测一次create如何决定走哪条抓取管线create之所以能用一个命令覆盖 17 类来源核心在于 source_detector.py 中的SourceDetector.detect()。从源码看它的判定顺序非常明确source_detector.py文件扩展名优先依次匹配.jsonconfig、.pdf、.docx、.epub、.ipynb、.html/.htm、.pptx、.adoc/.asciidoc、.man与.1.8man page且要求文件名不含点避免把access.log.1误判为 man 页、视频扩展名.mp4/.mkv/.avi/.mov/.webm/.flv/.wmv、.rss/.atomOpenAPI 内容嗅探.yaml/.yml文件只有内容中检测到openapi:或swagger:键才会被当作 OpenAPI specsource_detector.py视频 URL 检测YouTube 等视频链接优先于普通 URL目录检测os.path.isdir命中后若目录内 HTML 文件占比超过阈值默认抽样 500 个文件、至少 3 个 HTML、比例 ≥ 50%会被判为 HTML 镜像目录如 wget 下载的整站文档否则走本地代码库分析若目录根部存在pyproject.toml、package.json、go.mod等CODE_PROJECT_MARKERS清单中的工程清单文件则直接视为代码项目source_detector.pyGitHub 模式owner/repo或github.com/owner/repo(.git)格式命中source_detector.pyURL 与域名推断http(s)://直接走 web 抓取无协议但含.的输入会自动补全https://兜底报错均不命中则抛出带示例提示的ValueError。在 create_command.py 中execute()的流程是SourceDetector.resolve()判定类型 → 初始化ExecutionContext配置的唯一真相源→ 校验参数兼容性不兼容参数会告警并忽略→ 路由到对应 converter → 集中式增强与工作流 → 可选结构化索引create_command.py。这也解释了为什么--dry-run会跳过增强增强涉及真实 AI 调用预览模式不应触发。提示--html-path是 HTML 抓取器的强制覆盖开关即使目录混有其他文件也能强制走 HTML 管线create_command.py。三、文档网站抓取Documentation Scraping3.1 基本用法# 自动检测并抓取 skill-seekers create https://docs.react.dev/ # 自定义 Skill 名称 skill-seekers create https://docs.react.dev/ --name react-docs # 添加描述 skill-seekers create https://docs.react.dev/ \ --description React JavaScript library documentation--name默认从来源自动推导--description会写入生成的SKILL.md头部。二者在 create.py 中被定义为通用参数对所有来源生效。3.2 使用预设配置仓库configs/目录内置了一批开箱即用的预设如 configs/react.json、configs/godot.json 等先用estimate预览规模再决定是否采用# 列出仓库内置的抓取预设配置 skill-seekers estimate --all # 使用某个预设 skill-seekers create --config react skill-seekers create --config django skill-seekers create --config fastapiestimate命令estimate_pages.py只做 URL 发现与计数不下载正文可用来在正式抓取前估算页数与耗时--max-discovery可控制发现的 URL 上限。3.3 自定义配置统一 JSON 格式自 v2.11.0 起所有配置必须使用带sources数组的统一格式详见 CONFIG_FORMAT.md即使只有一个来源也要包在数组中# 创建配置文件 cat configs/my-docs.json EOF { name: my-framework, description: My framework documentation, sources: [ { type: documentation, base_url: https://docs.example.com/, max_pages: 200, rate_limit: 0.5, selectors: { main_content: article, title: h1 }, url_patterns: { include: [/docs/, /api/], exclude: [/blog/, /search] } } ] } EOF # 使用配置 skill-seekers create --config configs/my-docs.jsondocumentation 类型关键字段默认值来自 CONFIG_FORMAT.mdFieldTypeRequiredDefaultDescriptionnamestringYes-Skill 名字母、数字、短横线、下划线base_urlstringYes-文档基址descriptionstringNo写入 SKILL.md 的描述start_urlsarrayNo[base_url]起始爬取 URL可覆盖默认首页selectorsobjectNo见下文内容提取的 CSS 选择器url_patternsobjectNo{}包含/排除 URL 规则categoriesobjectNo{}内容分类规则rate_limitnumberNo0.5请求间隔秒max_pagesnumberNo500最大抓取页数max_retriesnumberNo3每页抓取尝试次数连接/超时/5xx 瞬时失败按指数退避重试设为1可禁用重试merge_modestringNoclaude-enhanced多来源合并策略extract_apibooleanNofalse是否提取 API 参考llms_txt_urlstringNoautollms.txt 文件路径若站点提供选择器与自动检测省略selectors.main_content时抓取器会按顺序尝试默认候选选择器直到命中为止main→div[rolemain]→article→[rolemain]→.content→.doc-content→#main-content。仅当自动检测选错元素时才需要手动指定。title默认取titlecode_blocks默认取pre code。URL 模式规则模式匹配 URL 路径*表示通配如/api/v*/**表示递归如/docs/**/*.htmlexclude优先级高于include。3.4 高级参数# 限制页数适合测试 skill-seekers create url --max-pages 50 # 调整请求间隔 skill-seekers create url --rate-limit 1.0 # 并行 Worker更快 skill-seekers create url --workers 5 --async # 预演不真正创建 skill-seekers create url --dry-run # 断点续抓 skill-seekers create url --resume # 忽略缓存、全新开始 skill-seekers create url --fresh源码层面的补充说明--workers上限为 10create.py配合--async可获得约 23 倍的提速帮助文本标注对 JavaScript 渲染的 SPA 站点可加--browser使用 Playwright 无头浏览器渲染后再抓取--rate-limit的默认值来自constants.py的DEFAULT_RATE_LIMIT命令行参数优先级高于配置文件CONFIG_FORMAT.md 明确 CLI takes precedence。四、GitHub 仓库抓取4.1 基本用法# 直接用 owner/repo skill-seekers create facebook/react # 显式 flag skill-seekers create --repo facebook/react # 自定义名称 skill-seekers create facebook/react --name react-sourceGitHub 判定依赖GITHUB_REPO_PATTERN与GITHUB_URL_PATTERN两个正则source_detector.py同时支持https://github.com/owner/repo与带.git后缀的形式。4.2 使用 GitHub Token# 设置 token 以提升 API 限额 export GITHUB_TOKENghp_... # 使用 token 抓取 skill-seekers create facebook/reactToken 带来的收益请求限额从匿名 60 次/小时提升到5000 次/小时可访问私有仓库获得更高的 GraphQL 限额。--token也可以直接作为命令行参数传入create.py。4.3 会提取哪些内容DataDefaultFlag to DisableSource code✅--scrape-only只抓取、不构建 SkillREADME✅-Issues✅--no-issuesReleases✅--no-releasesChangelog✅--no-changelog对应配置字段CONFIG_FORMAT.mdenable_codebase_analysis默认 true、code_analysis_depthsurface/standard/deep默认standard、fetch_issues默认 true、issue_state默认open避免抓取已关闭的陈旧 issue 造成 token 膨胀、max_issues默认 20、issue_labels、include_issue_labels默认 false、include_issue_milestones默认 false、fetch_releases、max_releases默认 20、fetch_changelog、analyze_commit_history默认 false、file_patterns、exclude_patterns。4.4 精细控制抓取范围# 跳过 Issues更快 skill-seekers create facebook/react --no-issues # 限制 issue 数量CLI 默认上限 100 skill-seekers create facebook/react --max-issues 50 # 只抓取不构建 skill-seekers create facebook/react --scrape-only # 非交互模式适合 CI/CD遇限流直接失败而非等待 skill-seekers create facebook/react --non-interactiveCLI 层还额外提供--since只抓取某日期之后更新的 issue支持 ISO8601 与YYYY-MM-DD、--issue-labels逗号分隔的标签过滤、--issue-stateopen/closed/all、--max-comments默认 0 表示禁用开启后每个 issue 会额外消耗分页 API 调用、--per-issue-files每个 issue 单独写一个带 YAML frontmatter 的 markdown 文件、--local-repo-path用本地克隆替代 GitHub API 文件限额进行无限制的 C3.x 代码分析。五、PDF 提取5.1 基本用法# 直接传文件 skill-seekers create manual.pdf --name product-manual # 显式指定 skill-seekers create --pdf manual.pdf --name docs5.2 扫描版 PDF 的 OCR# 开启 OCR skill-seekers create --pdf scanned.pdf --ocr依赖安装pip install skill-seekers[pdf-ocr] # 还需系统包tesseract-ocr5.3 密码保护 PDF{ name: secure-docs, sources: [{ type: pdf, pdf_path: protected.pdf, password: secret123 }] }5.4 页范围提取{ sources: [{ type: pdf, pdf_path: manual.pdf, page_range: [1, 100] }] }CLI 的--pages支持更灵活的语法如1-10或5,7,9create.py。PDF 类型其余配置字段enable_ocr默认 false、extract_images默认 false与image_output_dir默认自动、extract_tables默认 false与table_formatmarkdown/json/csv默认 markdown、split_by_chapters默认 false、chunk_size默认 1000 字符、chunk_overlap默认 100 字符。仓库内置tests/test_pdf_scraper.py、tests/test_pdf_advanced_features.py等测试覆盖了图片、表格与章节拆分等高级路径。六、本地代码库分析6.1 基本用法# 分析当前目录 skill-seekers create . # 指定目录 skill-seekers create ./my-project6.2 分析预设# 快速分析约 1-2 分钟 skill-seekers create ./my-project --preset quick # 标准分析约 5-10 分钟默认 skill-seekers create ./my-project --preset standard # 全面分析约 20-60 分钟 skill-seekers create ./my-project --preset comprehensive预设的实现位于 scrape_presets.pyquickrate_limit 0.1s、5 个 worker、异步、关闭 RAG 分块与续传、standard0.5s、3 workers、开启分块与续传、comprehensive1.0s、2 workers、全功能。用户显式传入的--rate-limit/--workers会覆盖预设值。6.3 各预设的分析范围FeatureQuickStandardComprehensiveCode structure✅✅✅API extraction✅✅✅Comments-✅✅Patterns-✅✅Test examples--✅How-to guides--✅Config patterns--✅对应配置字段CONFIG_FORMAT.mdlanguages默认自动检测、file_patterns、exclude_patterns默认排除常见目录、analysis_depthquick/standard/comprehensive默认standard、extract_api、extract_patterns、extract_test_examples、extract_how_to_guides、extract_config_patterns均默认 true、include_comments、include_docstrings、include_readme均默认 true。6.4 语言与文件过滤# 限定语言 skill-seekers create ./my-project \ --languages Python,JavaScript # 限定文件模式 skill-seekers create ./my-project \ --file-patterns *.py,*.js6.5 跳过重型功能skill-seekers create ./my-project \ --skip-dependency-graph \ --skip-patterns \ --skip-test-examplesCLI 还支持--skip-how-to-guides、--skip-docs、--skip-api-reference、--skip-config-patterns别名--skip-config、--no-comments等开关create.py可按需裁剪分析管线。七、视频提取7.1 基本用法# YouTube 视频 skill-seekers create https://www.youtube.com/watch?vdQw4w9WgXcQ # 本地视频文件 skill-seekers create presentation.mp4 # 显式指定 URL skill-seekers create --video-url https://www.youtube.com/watch?v...视频 URL 检测发生在目录判定之前source_detector.py本地文件则靠扩展名命中。7.2 视觉分析画面提取# 安装完整视频支持含 Whisper 与场景检测 pip install skill-seekers[video-full] skill-seekers create --setup # 自动检测 GPU 并安装 PyTorch # 开启视觉提取 skill-seekers create --video-url url --visual依赖分级pip install skill-seekers[video] # 仅转写 pip install skill-seekers[video-full] # Whisper、场景检测视频相关参数create.py还包括--video-playlist播放列表、--video-languages转写语言默认en、--whisper-model默认base、--visual-interval画面扫描间隔默认 0.7s、--visual-min-gap帧最小间隔默认 0.5s、--visual-similarity去重像素差阈值默认 3.0越小帧越多、--vision-ocr对低置信度代码帧回退到视觉 API、--start-time/--end-time支持秒、MM:SS、HH:MM:SS。注意--start-time/--end-time仅适用于单个视频。八、文档与办公格式提取以下格式均以文件扩展名自动检测--name可自定义输出 Skill 名--xxx为对应显式 flag。8.1 Word.docxskill-seekers create report.docx --name project-report skill-seekers create --docx report.docx处理能力文本、表格、标题、图片、内嵌元数据。8.2 EPUBskill-seekers create programming-guide.epub --name guide skill-seekers create --epub programming-guide.epub处理能力章节、元数据、目录、内嵌图片。8.3 Jupyter Notebook.ipynbskill-seekers create analysis.ipynb --name>skill-seekers create docs.html --name offline-docs skill-seekers create --html-path docs.html处理能力完整 HTML 解析、文本提取、链接解析。--html-path也支持目录并可强制覆盖自动检测。8.5 OpenAPI/Swaggerskill-seekers create api-spec.yaml --name my-api skill-seekers create --spec api-spec.yaml提取内容端点、请求/响应 Schema、认证信息、示例。注意 YAML 需包含openapi:或swagger:键才会被识别。8.6 AsciiDocskill-seekers create guide.adoc --name dev-guide skill-seekers create --asciidoc-path guide.adoc依赖pip install skill-seekers[asciidoc]处理能力章节、代码块、表格、交叉引用、includes。8.7 PowerPoint.pptxskill-seekers create slides.pptx --name presentation skill-seekers create --pptx slides.pptx依赖pip install skill-seekers[pptx]提取内容幻灯片文本、演讲者备注、图片、表格、幻灯片顺序。8.8 RSS/Atom 订阅源skill-seekers create blog.rss --name blog-archive skill-seekers create updates.atom --name updates skill-seekers create --feed-url https://engineering.example.com/feed.xml依赖pip install skill-seekers[rss]提取内容文章、标题、日期、作者、分类。配置中还可启用follow_links与max_articles控制跟进与数量。8.9 Man Page.1.8 / .manskill-seekers create curl.1 --name curl-manual skill-seekers create --man-names ls,grep,find处理能力标准章节NAME、SYNOPSIS、DESCRIPTION、OPTIONS 等与格式化。man 页判定要求文件名不含点如git.1是 man 页access.log.1不是。九、团队协作平台提取这三类来源无法通过单个参数自动检测需要 API 凭据或本地导出目录source_detector.py 明确说明。9.1 Confluence# 从 Confluence API skill-seekers create \ --conf-base-url https://wiki.example.com \ --space-key DEV \ --name team-docs # 从 Confluence 导出目录 skill-seekers create --conf-export-path ./confluence-export/依赖pip install skill-seekers[confluence]提取内容页面、页面树、附件、标签、空间。配置字段base_urlspace_key或export_path、username、token、max_pages。9.2 Notion# 从 Notion API export NOTION_API_KEYsecret_... skill-seekers create --database-id abc123 --name product-wiki # 从 Notion 导出目录 skill-seekers create --notion-export-path ./notion-export/依赖pip install skill-seekers[notion]提取内容页面、数据库、块、属性、关系。--page-id也可作为入口create.py。9.3 Slack / Discord 聊天记录# Slack 导出 skill-seekers create --chat-export-path ./slack-export/ --name team-discussions # Discord 导出 skill-seekers create --chat-export-path ./discord-export/ --name server-archive依赖pip install skill-seekers[chat]提取内容消息、线程、频道、表情回应、附件。--platform可选slack/discord默认slack。十、常见抓取模式从预演到生产模式 1先测试后全量# 预演预览 skill-seekers create source --dry-run # 小规模试抓 skill-seekers create source --max-pages 10 # 全量抓取 skill-seekers create source--dry-run会同时跳过增强与工作流阶段create_command.py是零成本验证配置与选择器的最佳手段。模式 2迭代式开发# 不增强直接抓取快 skill-seekers create source --enhance-level 0 # 检查输出 ls output/my-skill/ cat output/my-skill/SKILL.md # 之后再增强 skill-seekers enhance output/my-skill/--enhance-level取值 0关闭、1仅 SKILL.md、2架构/配置默认、3全量增强并会自动在 API 模式设置了ANTHROPIC_API_KEY/MOONSHOT_API_KEY等与本地 Agent 模式--agent可选 claude/codex/copilot/opencode/kimi/custom之间切换create.py。模式 3并行处理# 快速异步抓取 skill-seekers create url --async --workers 5 # 更快注意限流 skill-seekers create url --async --workers 10 --rate-limit 0.2--workers上限为 10--rate-limit调低到 0.2s 时务必确认目标站点可承受。模式 4断点续抓# 开始抓取 skill-seekers create source # ...中途中断... # 查看可恢复任务 skill-seekers resume --list # 恢复指定任务 skill-seekers resume job-idresume子命令实现在 resume_command.py支持列出可恢复任务、按 job-id 恢复以及清理过期任务create侧的--resume/--fresh则用于同一来源的续抓与重来。十一、故障排查Troubleshooting Scraping11.1 No content extracted原因CSS 选择器不匹配。解法# 先去掉 main_content 走自动检测依次尝试 main、div[rolemain]、article、.content 等 skill-seekers create url --dry-run # 若自动检测失败手动确认正确选择器 curl -s url | grep -i article\|main\|content # 在配置中显式指定 { sources: [{ type: documentation, base_url: https://..., selectors: { main_content: div.content } }] }11.2 Rate limit exceeded原因请求过于频繁。解法# 放慢请求 skill-seekers create url --rate-limit 2.0 # GitHub 来源使用 token export GITHUB_TOKENghp_...11.3 Too many pages原因站点比预期更大。解法# 先估算规模 skill-seekers estimate configs/my-config.json # 限制页数 skill-seekers create url --max-pages 100 # 收紧 URL 排除规则 { sources: [{ type: documentation, base_url: https://..., url_patterns: { exclude: [/blog/, /archive/, /search] } }] }estimate会同时给出推荐页数缓冲与预计抓取耗时基于rate_limit估算见 estimate_pages.py。11.4 Memory error原因站点过大导致内存不足。解法# 使用流式模式 skill-seekers create url --streaming # 或缩小分块 skill-seekers create url --chunk-tokens 500流式摄入实现在 streaming_ingest.py通过--streaming-chunk-chars默认 4000 字符/块与--streaming-overlap-chars默认 200控制分块粒度package.py--chunk-tokens则控制 RAG 语义分块的 token 大小默认值来自defaults.jsoncommon.py。十二、性能优化速查TipCommandImpactUse presets--config reactFaster setupAsync mode--async --workers 53-5x fasterSkip enhancement--enhance-level 0Skip 60 secUse cache--skip-scrapeInstant rebuildResume--resumeContinue interrupted补充--skip-scrape直接复用已抓取数据重建 Skill配合--fresh清缓存重来可灵活控制缓存行为对 GitHub 大仓库可考虑--local-repo-path绕过 API 文件数限制显著加速深度分析。十三、下一步Enhancement Guide - 提升 Skill 质量增强模式与工作流Packaging Guide - 导出到各平台Config Format - 18 类来源的完整 JSON 配置规范与多来源统一配置CLI Reference - 全部命令与参数参考更多内置配置示例见仓库 configs/ 目录如 react、godot、blender、unity 系列实际体验时建议从skill-seekers create 小站点 --dry-run开始配合skill-seekers estimate估算规模再按“测试 → 全量 → 增强”的节奏推进即可稳定地把各类知识源沉淀为可复用的 Claude AI Skill。【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考