Skill Seekers 仓库开发与架构指南从 CLAUDE.md 到源码级实现解析【免费下载链接】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 等 18 类来源转化为生产级 AI Skill 的开源项目覆盖 21 个 AI 平台LLM 平台、RAG 框架、向量数据库、AI 编程助手。本文以仓库根目录的CLAUDE.md为骨架逐层拆解其命令体系、CLI 架构、转换器/适配器设计模式、MCP 服务与测试规范并结合src/skill_seekers/下的真实源码给出调用链与文件定位。读完本文你将掌握该仓库的日常开发命令、五大架构模式工厂 模板方法 策略 适配器 中央参数定义、scan智能扫描管线的工作机制以及如何按官方约定新增平台适配器、源类型转换器和 CLI 参数。项目总览定位、版本与目录结构CLAUDE.md开篇即给出项目定位将 18 种来源类型的文档转换为 21 AI 平台的可用格式以skill-seekers名称发布到 PyPI。版本号不是硬编码字符串而是由 src/skill_seekers/_version.py 动态从 pyproject.toml 读取Python 3.11 用内置tomllib更早版本回退到tomli读取失败时兜底为3.10.0.dev0。当前仓库中 pyproject.toml 记录版本为3.10.0.dev0、requires-python 3.10即整个项目要求 Python 3.10。架构蓝图沉淀在文档层UML 图与模块总览见 docs/UML_ARCHITECTURE.mdStarUML 工程文件在 docs/UML/skill_seekers.mdj代码重构历史与大统一Grand Unification五阶段说明见 docs/UNIFICATION_PLAN.md。Skill Seekers 包总览 UML 图从这张包总览图与 src/skill_seekers/ 目录结构可以看到核心代码分为cli/命令行主流程、mcp/MCP 服务器、web/FastAPI 后端、services/领域逻辑、embedding/、sync/、benchmark/、workflows/等相对独立的部分后五者与 scrape→build→package 主流程解耦。必备命令安装、测试、质量与发布CLAUDE.md强调由于采用src/布局运行测试或 CLI 前必须先安装。完整命令集如下# 运行测试或 CLI 前的必需步骤src/ 布局 pip install -e . # 运行全部测试提交前必须全部通过不可跳过 pytest tests/ -v # 快速迭代跳过耗时约 20 分钟的慢速 MCP 测试 pytest tests/ --ignoretests/test_mcp_fastmcp.py --ignoretests/test_mcp_server.py --ignoretests/test_install_skill_e2e.py -q # 单条测试 pytest tests/test_scraper_features.py::test_detect_language -vv -s # 代码质量检查推送前必须通过与 CI 对齐 uvx ruff check src/ tests/ uvx ruff format --check src/ tests/ mypy src/skill_seekers # CI 中为 continue-on-error # 自动修复 lint / 格式问题 uvx ruff check --fix --unsafe-fixes src/ tests/ uvx ruff format src/ tests/ # 构建与发布 uv build uv publish从中可以看到项目的工具链约定pip负责安装、pytest负责测试、ruff负责 lint 与格式化、mypy负责静态类型检查CI 中允许失败、uv负责构建发布。测试文件集中在 tests/ 目录如 tests/test_scraper_features.py 就是test_detect_language等特性测试的所在地。CI 矩阵与 Git 工作流CI 在向main或development分支的 push/PR 时触发包含两个作业Lint 作业Python 3.12 UbuntuTest 作业Ubuntu macOSPython 3.10/3.11/3.12排除 macOS 3.10 组合。两者都通过才能合并。Git 工作流约定为main主分支要求测试通过 1 个 reviewdevelopment默认 PR 目标分支要求测试通过功能分支从development切出命名feature/{task-id}-{description}PR 一律指向development绝不直接指向main。这套双主线 功能分支模型保证了合并到主分支的代码都经过 review同时让日常开发在development上快速迭代。架构解析五大核心设计1. CLI统一 create 命令与命令分发CLI 入口在 src/skill_seekers/cli/main.py。三个核心命令构成主流程skill-seekers create source # 自动检测URL、owner/repo、./path、file.pdf 等 skill-seekers scan dir # AI 驱动发现 → 为每个检测到的框架生成一个 config project-codebase.json skill-seekers package dir # 按平台打包--target claude/gemini/openai/...从源码看分发机制采用双表结构COMMAND_CLASSES 中create、detect、scan、doctor、ui五个命令被实现为Cls(args).execute()的类分发——直接消费 argparse 解析出的 namespace没有_reconstruct_argv回环、没有重复 argparse其余约 14 个命令enhance、package、upload、install、config、workflows等仍走 COMMAND_MODULES 的模块分发通过module.main(args...)调用文档标注为待迁移到类分发。2. scan 命令AI 驱动的项目知识库引导器scanissue #327 引入是CLAUDE.md着墨最多的命令其管线实现在 src/skill_seekers/cli/scan_command.py核心七步collect_signals()signal_collectors.py确定性、有界地收集 manifest README Dockerfile/CI 抽样源码 git remote。采用按类别字节预算manifest 24 KB / README 6 KB / CI 6 KB / 样本 28 KB总计 64 KB防止过大的 package.json 挤占其他类别_SOURCE_DIRS覆盖约 14 种目录布局Gocmd/、Rustcrates/、JS monorepoapps/packages/、Mavensource/、根目录 Django 等对扁平布局 Python 项目还会向下走一层根目录。detect_with_ai(bundle, AgentClient)一次 LLM 调用、结构化 JSON 输出。信号是每个文件的前 2 KB整文件采样、不做正则解析——WS4 中因正则漏掉 Go 多行 import 与 Rustmod/extern crate而改为全量采样。canonical-slug 提示词与 canonical-name 解析器耦合改一个必须同步另一个。resolve_or_generate_with_status()按顺序尝试out_dir/slug.json上次运行的缓存→config_fetcher.resolve_config_path_canonical_name_candidates处理Godot Engine→godot、Godot 引擎、React フレームワーク、Lodash Bibliothek等 CJK/欧洲语言后缀→generate_config_with_ai兜底。始终为查找名追加.json并始终写入嵌套的metadata.detected_version不放在顶层因为顶层metadata.version已表示配置 schema 版本。emit_codebase_config()总是写出project-codebase.json一个指向项目根目录的type: local源。diff_against_existing()以文件名 slug而非内部data[name]为键做 diff避免 AI 返回显示名与注册表 canonical slug 不同时反复重扫。_archive_removed()检测中消失的配置移动而非删除用户可能手工编辑过到out_dir/.archived/UTC-timestamp/在 diff 之后、新写入之前执行。maybe_publish()原生异步WS11可选地把新生成的 AI 配置提交到社区注册表。提交前用_find_existing_issue查询 GitHub Search API 是否存在同名 open issue幂等保护对限流、5xx 等瞬时失败以 0s/5s/15s 退避重试_prompt_async通过asyncio.to_thread包装input()避免阻塞事件循环。成本护栏--max-ai-generations N默认 10限制无界 AI 生成--dry-run只预览不写盘、不调用 AI--probe-urls对 AI 生成的 URL 做 HEAD 检查404 时重试对确认失效的 URL 在metadata._url_unverified打标。安全性所有写入走_atomic_write_json先写.tmp再用os.replaceKeyboardInterrupt打断写入不会损坏配置_safe_size保护stat()断开的符号链接不会导致 scan 崩溃ScanCommand.execute调用logging.basicConfig使logger.warning/error可见未产出任何配置且未产出 codebase 配置时退出码非零。公共常量SourceDetector.CODE_PROJECT_MARKERS原_CODE_PROJECT_MARKERS由 source_detector 与 signal_collectors 共享现支持约 50 种 manifest 类型Pipfile、environment.yml、deno.json、flake.nix、Chart.yaml、deps.edn、dune-project、BUILD.bazel 等改为公开以便跨模块访问不触达私有属性。3. SkillConverter模板方法 工厂模式全部 18 种源类型实现 skill_converter.py 中的SkillConverter基类converter get_converter(web, config) # Factory 查找 converter.run() # 模板方法extract() → build_skill()CONVERTER_REGISTRY将源类型映射到(模块, 类)从源码可见 共 18 个条目webdoc_scraper、github、pdf、word、epub、video、localcodebase_scraper、jupyter、html、openapi、asciidoc、pptx、rss、manpage、confluence、notion、chat、configunified_scraper。create_command.py 从ExecutionContext构建配置后调用get_converter()再运行集中式 enhancementget_converter(config, {...})用同样的工厂形字典构造UnifiedScraper因此 create_command/MCP 中没有特殊分支。基类只解析一次skill_dir去除尾部分隔符防止--output以/结尾时派生路径落入 skill 目录被打包并经由data_file_for()派生data_file子类不得自行重新派生路径。4. DocumentSkillBuilder9 个文档类抓取器的公共构建端src/skill_seekers/cli/document_skill_builder.py 的DocumentSkillBuilder位于SkillConverter与 9 个文档抓取器epub、word、pptx、html、pdf、jupyter、man、rss、chat之间统一负责categorize_content、参考文件写入表格、截断、图片防护、index.mdSKILL.md生成与load_extracted_data。变化点集中在类属性DOC_NOUN、SOURCE_LABEL、LOAD_TOTAL_KEY、PATTERN_KEYWORDS、RANGE_LABEL等和小钩子方法category_stem、_write_reference_section、_write_skill_md_metadata。其输出被 tests/golden/phase2/ 的 golden 树逐字节锁定——UPDATE_GOLDENS1可重写但只应在有意为之的情况下使用。存留的整方法覆写均为领域形态且按抓取器加注注释。5. UnifiedScraper多源配置的调度引擎unified_scraper.py 通过类级SOURCE_DISPATCH表分发_scrape_with_converter()是 13 个机械型源类型的共享引擎get_converter() 公开的converter.extract() 缓存拷贝 子 skill 构建因此注册进CONVERTER_REGISTRY的新类型会自动在 unified 配置中生效。documentation/github/local 三个源类型保持定制实现源码注释说明了原因。run()有意不遵循基类模板TestRunOrchestration测试锁定了 run() 必须触发 workflows。数据流五阶段管线1. Scrape - 源特有抓取器将内容抽取到 output/{name}_data/pages/*.json 2. Build - build_skill() 分类页面、提取模式生成 output/{name}/SKILL.md 3. Enhance -可选LLM 重写 SKILL.md--enhance-level 0-3自动检测 API vs LOCAL 模式 4. Package - 平台适配器格式化输出.zip、.tar.gz、JSON、向量索引 5. Upload -可选平台 API 上传这个五阶段模型与create/enhance/package/upload四个命令一一对应也是理解全项目数据流的主线索。平台适配器策略 工厂工厂get_adaptor(platform, config)位于 adaptors/init.py返回SkillAdaptor实例基类SkillAdaptor与SkillMetadata定义在 adaptors/base.py。目录结构如下src/skill_seekers/cli/adaptors/ ├── __init__.py # 工厂get_adaptor(platform, config)ADAPTORS 注册表 ├── base.py # 抽象基类SkillAdaptor、SkillMetadata ├── openai_compatible.py # OpenAI 兼容平台的共享基类 ├── claude.py # --target claude ├── gemini.py # --target gemini ├── openai.py # --target openai ├── markdown.py # --target markdown ├── minimax.py # --target minimax ├── opencode.py # --target opencode ├── kimi.py # --target kimi ├── deepseek.py # --target deepseek ├── qwen.py # --target qwen ├── openrouter.py # --target openrouter ├── together.py # --target together ├── fireworks.py # --target fireworks ├── langchain.py # --target langchain ├── llama_index.py # --target llama-index ├── haystack.py # --target haystack ├── chroma.py # --target chroma ├── faiss_helpers.py # --target faiss ├── qdrant.py # --target qdrant ├── weaviate.py # --target weaviate ├── pinecone_adaptor.py # --target pinecone └── streaming_adaptor.py # --target streaming所有适配器都使用--target指定。关键实现约束从 adaptors/init.py 可见每个适配器导入都用try/except ImportError包裹缺少可选依赖不会破坏整个注册表——这是该项目可选依赖必须真可选原则的落地。18 种源类型转换器每种源类型一个{type}_scraper.py实现为SkillConverter子类不提供main()。create_command.py 用 source_detector.py 自动检测源类型然后调用get_converter()。完整的 18 类为webdoc_scraper、github、pdf、word、epub、video、localcodebase_scraper、jupyter、html、openapi、asciidoc、pptx、rss、manpage、confluence、notion、chat、configunified_scraper。需要说明的是source_detector.py 的模块注释 指出Confluence、Notion、Slack/Discord chat 属于 API/导出型来源无法从单一参数自动检测需使用各自的专用子命令skill-seekers confluence、notion、chat。CLI 参数系统单一来源定义src/skill_seekers/cli/ ├── parsers/ # 中央 SubcommandParser 类——每个命令旗标的唯一定义处 │ └── create_parser.py # 渐进式帮助披露--help-web、--help-github 等 ├── arguments/ # 参数定义 │ ├── common.py # add_all_standard_arguments() - 所有抓取器共享 │ └── create.py # UNIVERSAL_ARGUMENTS、WEB_ARGUMENTS、GITHUB_ARGUMENTS 等 ├── exit_codes.py # EXIT_SUCCESS/ERROR/VALIDATION/INTERRUPT └── source_detector.py # 从输入字符串自动检测源类型设计核心是单点定义命令模块的独立main(argsNone)路径也从中央SubcommandParser类构建解析器——新增/修改旗标只能改parsers/*.py。防漂移测试 tests/test_cli_parsers.py 中的TestCentralModuleParserSync与TestCentralParserSingleSource会在 dests/defaults/option strings 出现任何分叉时让 CI 失败。ExecutionContext.override()是上下文局部的一个叠加在未修改基类单例上的ContextVar对 MCP 服务器线程/异步安全向工作线程传播需通过copy_context。独立子系统cli/ 之外四个顶层包与主流程相对独立embedding/FastAPI 嵌入生成服务器python -m skill_seekers.embedding.server带缓存层cache.py与多后端生成器OpenAI、sentence-transformers、Anthropic服务于向量数据库适配器sync/实时文档同步系统——detector.py内容哈希 / 修改时间变更检测、monitor.py定时增量重抓、notifier.pyemail/Slack/webhook让生成的 skill 在上游文档变化时保持新鲜benchmark/性能套件runner.py、framework.py测量 scrape/embedding/storage/e2e 的耗时、内存与 CPU产出对比与优化报告workflows/随包附带的默认 enhancement 工作流预设供 enhancement 步骤消费。C3.x 代码库分析管线本地代码库分析功能全部为默认开启、可跳过--skip-*旗标C3.1pattern_recognizer.py——设计模式检测10 种 GoF 模式、9 种语言C3.2test_example_extractor.py——从测试提取用法示例C3.3how_to_guide_builder.py——AI 增强的教学指南C3.4config_extractor.py——配置模式提取C3.5generate_router.py——架构总览生成C3.10signal_flow_analyzer.py——Godot 信号流分析。对应的测试如 tests/test_pattern_recognizer.py、tests/test_test_example_extractor.py、tests/test_how_to_guide_builder.py 可帮助理解各分析器的行为边界。MCP Server40 个工具与进程内执行src/skill_seekers/mcp/server_fastmcp.py 通过 FastMCP 暴露 40 个工具传输方式为 stdioClaude Code或 HTTPCursor/Windsurf可选依赖安装pip install -e .[mcp]。几个关键实现决策工具进程内运行经 mcp/tools/_common.py 的run_cli_main()——用命令真实解析器解析同一份 argv锁保护的 sys.argv 补丁捕获 stdout/stderr 与 contextvar 日志契约统一为(stdout, stderr, returncode)。无子进程启动开销旧的硬超时仅是建议性的。刻意例外enhance_skillLOCAL agent与install_skill的 enhancement 步骤保持子进程方式——agent 必须是真实子进程才能满足 fork-bomb 防护环境语义SKILL_SEEKER_ENHANCE_ACTIVE。这两处永远不要改为进程内。领域逻辑位于skill_seekers.services/marketplace_manager、marketplace_publisher、config_publisher、source_manager、git_repoCLI 无需[mcp]extra 即可导入旧的skill_seekers.mcp.*路径是向后兼容的垫片mcp/内没有任何sys.pathhack。Seeker HUDWeb UIFastAPI 后端在 src/skill_seekers/web/React 前端在 ui/详细文档见 docs/guides/WEB_UI.md。HUD 路由位于 src/skill_seekers/web/routes/一个屏幕一个模块统一register(app, ctx)app.py 保留原始路由。EnhancementAgentClient 是唯一的 AI 传输层所有 AI 调用都经由AgentClientsrc/skill_seekers/cli/agent_client.py它集中处理截断闸门、超时策略与错误分类。API_PROVIDERSprovider 注册表与AGENT_PRESETS本地 agent 命令模板只存在于该文件。每个API_PROVIDERS条目声明其线上protocolanthropic/openai/google与supports_images能力_call_api按解析出的 protocol 分支而非 provider 名——因此新增 OpenAI/Anthropic 兼容 provider 无需新分支。适配器声明 provider/endpoint/model/prompt统一经SkillAdaptor._enhance_skill_md_via_client原子保存 备份路由。多模态图像输入走AgentClient.call_with_image()供video_visual帧 OCR 跨所有支持图像的 provider 使用不再绕过 AgentClient 直接调用 SDK。API 模式设置了 API key 时按注册顺序检测 Anthropic、Google Gemini、OpenAI、Moonshot/Kimi、MiniMaxSKILL_SEEKER_PROVIDER可强制指定。模型变量SKILL_SEEKER_MODEL全局或ANTHROPIC_MODEL/GOOGLE_MODEL/OPENAI_MODEL/MOONSHOT_MODEL/MINIMAX_MODELANTHROPIC_BASE_URL支持兼容端点。MiniMax 额外有MINIMAX_API_REGIONglobal_en/cn_zh与MINIMAX_API_PROTOCOLopenai/anthropic。视觉 OCR providerSKILL_SEEKER_VISION_PROVIDERauto挑选第一个带 key 的图像能力 provider。LOCAL 模式回退Claude Code、Kimi Code、Codex、Copilot、OpenCode、自定义 agent——命令由build_local_agent_command()构建。从 agent_client.py 的 AGENT_PRESETS 可以看到每个 agent 的命令模板、版本检查命令、是否走 stdin、以及是否支持--dangerously-skip-permissionsheadless 运行插入该旗标。控制项--enhance-level 0关闭/1仅 SKILL.md/2默认均衡/3完整--agent claude|codex|copilot|opencode|kimi|custom。关键实现细节智能分类doc_scraper.py:smart_categorize()对页面按类别关键词打分URL 命中 3 分、标题命中 2 分、内容命中 1 分阈值要求 2 分以上否则回退到 other。内容抽取doc_scraper.pyFALLBACK_MAIN_SELECTORS常量配合_find_main_content()处理 CSS 选择器回退链接在提前返回之前从完整页面抽取而非仅主内容body被有意排除在回退选择器之外。三流 GitHub 架构unified_codebase_analyzer.pyStream 1代码分析AST、模式、测试、指南Stream 2文档README、docs/、wikiStream 3社区issues、PRs、metadata。深度控制basic1-2 分钟或c3x20-60 分钟。测试体系测试标记pytest.inipytest tests/ -v # 默认仅快速测试 pytest tests/ -v -m slow # 包含慢速测试5s pytest tests/ -v -m integration # 需要外部服务 pytest tests/ -v -m e2e # 资源密集型 pytest tests/ -v -m not slow and not integration # 最快子集已知合法跳过约 11 项2chromadb 与 Python 3.14 不兼容pydantic v12未安装 weaviate-client2Qdrant 未运行需要 docker2未安装 langchain / llama_index3未设置 GITHUB_TOKEN。sys.modules 陷阱tests/test_swift_detection.py 会从sys.modules删除skill_seekers.cli模块。它必须同时保存并恢复sys.modules条目与父包属性setattr测试文件本身给出了模式参考——这是编写涉及模块卸载/重载测试时必须照做的样板。依赖与安装选项核心依赖包括langchain、llama-index、anthropic、httpx、PyMuPDF、pydantic。平台相关依赖全部可选安装方式与 pyproject.toml 的[project.optional-dependencies]对应pip install -e .[mcp] # MCP 服务器 pip install -e .[gemini] # Google Gemini pip install -e .[openai] # OpenAI pip install -e .[docx] # Word 文档 pip install -e .[epub] # EPUB 电子书 pip install -e .[video] # 视频轻量 pip install -e .[video-full]# 视频Whisper 视觉 pip install -e .[jupyter] # Jupyter 笔记本 pip install -e .[pptx] # PowerPoint pip install -e .[rss] # RSS/Atom 源 pip install -e .[confluence]# Confluence wiki pip install -e .[notion] # Notion 页面 pip install -e .[chroma] # ChromaDB pip install -e .[all] # 全部除 video-full 外开发依赖使用 pyproject.toml 中的 PEP 735[dependency-groups]声明。环境变量速查ANTHROPIC_API_KEYsk-ant-... # Claude AI或兼容端点 ANTHROPIC_BASE_URLhttps://... # 可选Claude 兼容 API 端点 GOOGLE_API_KEYAIza... # Google Gemini可选 OPENAI_API_KEYsk-... # OpenAI可选 GITHUB_TOKENghp_... # 提高 GitHub 限流额度另见 docs/reference/ENVIRONMENT_VARIABLES.md 获取更完整的环境变量清单。如何新增功能官方扩展指南新增平台适配器创建src/skill_seekers/cli/adaptors/{platform}.py继承 adaptors/base.py 的SkillAdaptor在 adaptors/init.py 注册try/except import 加入ADAPTORS字典在 pyproject.toml 添加可选依赖在 tests/ 添加测试。新增源类型转换器创建src/skill_seekers/cli/{type}_scraper.py——文档形来源继承DocumentSkillBuilder分类/参考文件/index/SKILL.md 开箱即用只需实现extract()与钩子方法否则继承SkillConverter并实现extract()和build_skill()同时设置SOURCE_TYPE在 skill_converter.py 的CONVERTER_REGISTRY注册——这一步同时让该类型自动在 unified 配置中生效UnifiedScraper 引擎在 create_command.py 的_build_config()中添加源类型配置构建在 source_detector.py 添加自动检测按需添加可选依赖添加测试。新增 CLI 参数子命令旗标只在中央解析器类parsers/{cmd}_parser.py中定义——模块main()从它构建否则防漂移测试会失败通用参数UNIVERSAL_ARGUMENTS位于 arguments/create.py源特有参数相应的字典WEB_ARGUMENTS、GITHUB_ARGUMENTS等同样在 arguments/create.py跨抓取器共享add_all_standard_arguments()位于 arguments/common.py。小结CLAUDE.md本质上是 Skill Seekers 的开发契约它定义了从本地迭代pip install -e .pytestruffmypy到 CI/发布uv build/uv publish的完整质量闸门同时也是一份精准的架构地图。对照源码可以确认文档中的每个模式都有真实落点——COMMAND_CLASSES双表分发、CONVERTER_REGISTRY的 18 类注册、adaptors/__init__.py的 try/except 可选导入、AGENT_PRESETS的本地 agent 模板、scan_command.py的七步管线与原子写入安全措施。对于希望为该仓库贡献新平台适配器、新源类型或新 CLI 参数的开发者按本文最后一节的四步/六步流程即可遵循项目约定提交代码并由防漂移测试与 golden 树守护既有行为不被破坏。【免费下载链接】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），仅供参考
