人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载Skill_Seekers 是一个把文档网站、GitHub 仓库和 PDF 等 18 种来源自动转换为 Claude AI Skills 的开源项目本文以仓库根目录的 CONTRIBUTING.md 为骨架系统拆解其双分支协作模型、本地开发环境搭建、编码与测试规范并结合src/skill_seekers源码、pyproject.toml配置与测试脚本说明「如何正确地向该项目提交一份高质量 PR」。读完本文你将能独立完成从 fork、建分支、写代码、跑通受内存守护的测试套件到按规范提交 PR 的完整贡献闭环并理解新增 scraper 源类型时需要触碰的注册点。1. 双分支工作流main / development / featureSkill_Seekers 采用双分支模型Two-Branch Workflow这是所有贡献者必须先理解的第一条规则所有 PR 必须指向development分支而不是main。1.1 分支结构main (production) ↑ │ (only maintainer merges) │ development (integration) ← default branch for PRs ↑ │ (all contributor PRs go here) │ feature branches1.2 各分支职责分支角色规则main生产分支始终稳定仅由维护者从development合并受保护需测试通过 1 次 reviewdevelopment集成分支所有 PR 的默认目标分支活跃开发在此进行受保护需测试通过由维护者合并到mainfeature 分支贡献者的工作分支从development创建命名要有描述性如feature/123-add-github-scraping通过 PR 合回development1.3 完整操作示例# 1. Fork 并 clone这里以本镜像仓库为例 git clone https://gitcode.com/gh_mirrors/sk/Skill_Seekers.git cd Skill_Seekers # 2. 添加 upstream 远程仓库 git remote add upstream 上游仓库地址 # 3. 从 development 创建 feature 分支 git checkout development git pull upstream development git checkout -b my-feature # 4. 修改、提交、推送 git add . git commit -m Add my feature git push origin my-feature # 5. 创建指向 development 分支的 Pull Request⚠️ 提交到main的 PR 会被拒绝提交信息建议使用清晰描述性写法如feat: add github scraping。2. 项目生态贡献之前先找对仓库CONTRIBUTING.md 明确说明 Skill_Seekers 横跨多个仓库不同诉求应贡献到不同仓库避免把 Web 前端或配置改动误提到主仓库想做什么对应仓库核心 CLI、scrapers、MCP 工具、adaptorsSkill_Seekers本仓库网站、文档、UI/UXskillseekersweb预设配置、社区配置skill-seekers-configsGitHub Action 集成skill-seekers-actionClaude Code 插件skill-seekers-pluginHomebrew 公式homebrew-skill-seekers本仓库内也有与这些生态对应的落地目录例如 distribution/github-action/action.ymlGitHub Action 定义、distribution/claude-pluginClaude Code 插件以及configs/下的预设抓取配置见第 4 节。修改前务必确认你改的是主仓库中真正对应的部分。3. 开发环境搭建Development Setup3.1 前置条件Python 3.10 或更高MCP 集成必需pyproject.toml 中requires-python 3.10与此一致Git3.2 安装步骤# 1. Fork 并 clone 仓库见 1.3 # 2. 安装依赖editable 模式便于开发时实时生效 pip install -e . pip install -e .[dev] pip install -e .[all].[dev]对应 pyproject.toml 中[dependency-groups] dev定义pytest、pytest-asyncio、pytest-cov、coverage、ruff、mypy、psutil测试内存守护依赖、boto3 等云存储测试依赖。.[all]聚合所有可选特性依赖MCP、各 LLM 平台、RAG 向量库、云存储、新源类型等。video-full因含 OpenCV/easyocr/faster-whisper 等重型原生依赖被刻意排除在all之外需要时单独安装。测试部分还建议使用uv sync管理环境并安装pytest-timeout、pytest-xdist以支持超时控制与并行执行。3.3 常用命令流程# 3. 从 development 创建功能分支 git checkout development git pull upstream development git checkout -b feature/my-awesome-feature # 4. 修改代码见第 6、8 节了解结构与规范 # 5. 运行测试 python -m pytest tests/ -v # 6. 提交 git add . git commit -m Add awesome feature # 7. 推送到自己的 fork git push origin feature/my-awesome-feature # 8. 创建 Pull Request4. 如何贡献Bug 报告、功能建议与新框架配置4.1 报告 Bug报告前先检索 [existing issues]GitHub issues 页避免重复。一份合格的 Bug 报告应包含清晰的标题与描述可复现步骤期望行为 vs 实际行为截图如适用环境信息操作系统、Python 版本等错误信息与堆栈追踪CONTRIBUTING.md 给出了贴近本项目的示例**Bug:** MCP tool fails when config has no categories **Steps to Reproduce:** 1. Create config with empty categories: categories: {} 2. Run skill-seekers create --config configs/test.json 3. See error **Expected:** Should use auto-inferred categories **Actual:** Crashes with KeyError **Environment:** - OS: Ubuntu 22.04 - Python: 3.10.5 - Version: 1.0.04.2 建议增强功能以 issue 形式提交需包含清晰标题、功能详述、受益用例、工作方式示例、备选方案。4.3 新增框架配置Adding New Framework Configs项目欢迎新的框架配置流程是在configs/目录创建配置文件用不同页数充分测试提交 PR附上配置文件、框架简介、测试结果抓取页数、识别出的分类仓库中configs/已有一批现成示例例如 configs/claude-code.json、configs/react.json、configs/unity-dotween.json 等。以claude-code.json为例一个完整的抓取配置包含如下关键字段{ name: claude-code, description: Claude Code CLI and development environment. ..., merge_mode: rule-based, sources: [ { type: documentation, base_url: https://code.claude.com/docs/en/, start_urls: [https://code.claude.com/docs/en/overview, ...], selectors: { main_content: #content-area, #content-container, article, main, title: h1, code_blocks: pre code }, url_patterns: { include: [/docs/en/], exclude: [/docs/fr/, /changelog, github.com] }, categories: { getting_started: [overview, quickstart], mcp: [mcp, model-context-protocol] }, rate_limit: 0.5, max_pages: 250 } ] }其中merge_mode合并模式、selectorsCSS 选择器、url_patternsURL 包含/排除规则、categories文档分类映射、rate_limit请求间隔秒数与max_pages最大抓取页数共同决定了抓取行为与产出 SKILL 的分类结构。建议新增配置时参考同目录既有文件的字段完整度。示例 PR 描述**Add Svelte Documentation Config** Adds configuration for Svelte documentation (https://svelte.dev/docs). - Config: configs/svelte.json - Tested with max_pages: 100 - Successfully categorized: getting_started, components, api, advanced - Total pages available: ~1504.4 Pull Requests 总则Fork 仓库并从development创建分支新增了代码就补测试改了 API 就更新文档确保测试套件通过遵循编码规范第 6 节PR 提交到development分支5. Pull Request 流程与 Code Review 原则5.1 提交前自检清单本地测试通过python -m pytest tests/ -v代码符合 PEP 8 风格本项目变体见第 6 节文档已按需更新CHANGELOG.md 已更新如适用提交信息清晰且具描述性5.2 PR 模板## Description Brief description of what this PR does. ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update ## How Has This Been Tested? Describe the tests you ran to verify your changes. ## Checklist - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my own code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes5.3 Review 流程维护者通常在 3-5 个工作日内 review及时回应反馈或修改意见通过后由维护者合并贡献会进入下一个 release5.4 Code Review 黄金原则Fix both, dont follow precedent这是 CONTRIBUTING.md 中最具项目特色的一条工程哲学当 reviewer 指出你 PR 中的反模式时不能指着仓库里另一处相同写法来辩护。X.py already does this不是正当理由——它恰恰说明两处都需要修而不是这个坏味道被默许了。✅ 正确回应Good catch — Ill fix bothnew_file.pyandexisting_file.pyin this PR.本次一并修复✅ 正确回应Out of scope here, but Ill file a follow-up to fixexisting_file.py.记一个后续 issue❌ 错误回应Butexisting_file.pydoes the same thing, so this matches the convention.以既有坏代码为借口这条规则对维护者同样有效指出反模式的人应当愿意接受更广范围的修复或自己开 follow-up issue。坏先例即惯例正是代码库僵化的根源。6. 编码规范PEP 8 变体与 Ruff6.1 Python 风格项目遵循 PEP 8 但做了若干修改与 pyproject.toml 中[tool.ruff] line-length 100完全一致行宽100 字符而非默认 79缩进4 空格引号字符串使用双引号命名函数/变量用snake_case类用PascalCase常量用UPPER_SNAKE_CASE6.2 代码组织顺序# 1. Standard library imports import os import sys from pathlib import Path # 2. Third-party imports import requests from bs4 import BeautifulSoup # 3. Local application imports from cli.utils import open_folder # 4. Constants MAX_PAGES 1000 DEFAULT_RATE_LIMIT 0.5 # 5. Functions and classes def my_function(): Docstring describing what this function does. pass6.3 文档与类型标注所有函数应有 docstring、尽量使用类型标注、复杂逻辑加注释。仓库中大量模块正是这么做的例如 src/skill_seekers/cli/skill_converter.py 的基类即为带类型标注和 docstring 的示范def scrape_page(url: str, selectors: dict) - dict: Scrape a single page and extract content. Args: url: The URL to scrape selectors: Dictionary of CSS selectors Returns: Dictionary containing extracted content Raises: RequestException: If page cannot be fetched pass6.4 Ruff本项目的 lint 与格式化工具项目使用Ruff集 Flake8、isort、Black 等为一体、速度极快的 Python linter。# 检查 lint 错误 uvx ruff check src/ tests/ # 自动修复 uvx ruff check --fix src/ tests/ # 格式化代码 uvx ruff format src/ tests/常用 Ruff 规则对应 pyproject.toml 中[tool.ruff.lint] select的E/W/F/I/B/C4/UP/ARG/SIM系列SIM102- 简化嵌套 if改用andSIM117- 合并多个with语句B904- 使用from e进行正确的异常链SIM113- 用enumerate代替手动计数器B007- 未使用的循环变量用_ARG002- 删除未使用的函数参数注ARG002与B007在[tool.ruff.lint] ignore中被豁免接口合规或有时是有意为之但规则表仍列出以说明团队的关注点。6.5 CI/CD 集成所有 PR 会自动依次运行ruff check- Lint 校验ruff format --check- 格式校验pytest- 测试套件提交前先在本地跑同样的检查uvx ruff check src/ tests/ uvx ruff format --check src/ tests/ pytest tests/ -v7. 测试从单文件到带内存守护的完整套件7.1 运行方式CONTRIBUTING.md 给出了两条主路径且与仓库内脚本一一对应# 方式一带内存监控与逐测试超时的完整套件 python scripts/run_tests_safe.py -- tests/ -v --timeout120 # 方式二三阶段测试快速阶段默认 2 个 worker bash scripts/run_tests_fast.sh # 调整进程树内存预算 python scripts/run_tests_safe.py --max-rss-mb 2048 -- tests/ -q --timeout120 # 只跑单个测试文件 python -m pytest tests/test_mcp_server.py -v # 带覆盖率统计 python -m pytest tests/ --covsrc/skill_seekers --cov-reportterm7.2 内存守护测试运行器run_tests_safe.py这是本项目测试基建的一大特色。scripts/run_tests_safe.py 是一个用psutil实现的「守护型」pytest 运行器限制整个进程树的聚合 RSS默认上限4 GiB--max-rss-mb一旦超限立即以退出码 137 终止当系统可用内存低于 2 GiB--min-available-mb时同样停止测试退出时清理全部后代进程os.killpgpsutil.wait_procs防止子进程残留这些采样限制属于安全余量safety margin并非操作系统的硬性上限收到 SIGTERMCI 环境或 CtrlC 时会优雅转发信号让 pytest 先输出汇总再清理。7.3 三阶段测试脚本run_tests_fast.shscripts/run_tests_fast.sh 将测试拆为三个互不重叠的阶段对应 pyproject.toml 中[tool.pytest.ini_options] markers声明的标记体系Phase 1 快速单元测试-m not slow and not integration and not e2e and not network and not serial and not mcp_only默认 2 个 workerTEST_WORKERS可调、--timeout120Phase 2 串行/集成/E2E-m (integration or e2e or slow or network or serial) and not mcp_only、--timeout300Phase 3 MCP 测试-m mcp_only、--timeout180。两个脚本都支持环境变量TEST_PYTHON、TEST_WORKERS、TEST_MAX_RSS_MB覆盖默认值适合 CI 或资源受限环境。7.4 编写测试的约定测试放在tests/目录文件名以test_开头与 pyproject.toml 的python_files [test_*.py]一致测试名要有描述性涉及子进程的 fixture 必须走 tests/subprocess_helpers.py 的run_process_tree这样超时时能连带杀掉孙进程bootstrap 会调用 bash → uv → Python只杀 bash 会让昂贵的 Python 分析存活生成物放在tmp_path中mock 掉真实的 agent/API 边界移除 mock 前先 join 后台线程测试不得调用已安装的 AI CLI也不得同步当前活动环境。参考示例def test_config_validation_with_missing_fields(): Test that config validation fails when required fields are missing. config {name: test} # Missing base_url result validate_config(config) assert result is False7.5 覆盖率目标整体覆盖率目标80%关键路径100%覆盖修复 bug 时必须补回归测试仓库测试规模相当可观tests/下 200 个测试文件覆盖 scraper、adaptor、MCP、Web UI、workflows、同步机制等新增功能时务必保证不破坏既有断言。8. 项目结构与扩展点读懂代码再动手8.1 顶层结构CONTRIBUTING.md 给出了精确的目录映射以下为精简版完整说明见文档原文Skill_Seekers/ ├── src/skill_seekers/ # 主包src/ 布局 │ ├── cli/ # CLI 命令与入口 │ │ ├── main.py # 统一 CLI 入口COMMAND_MODULES 字典 │ │ ├── source_detector.py # 自动探测源类型 │ │ ├── create_command.py # 统一 create 命令路由 │ │ ├── config_validator.py # VALID_SOURCE_TYPES 集合 │ │ ├── unified_scraper.py # 多源编排器 │ │ ├── unified_skill_builder.py # 成对合成 通用合并 │ │ ├── doc_scraper.py / github_scraper.py / pdf_scraper.py / ... │ │ ├── adaptors/ # 平台适配器Strategy 模式 │ │ ├── arguments/ # 每个源一个的 CLI 参数定义 │ │ ├── parsers/ # 每个源一个的子命令解析器 │ │ └── storage/ # 云存储适配器 │ ├── services/ # 共享领域逻辑marketplace、config publishing、git sources │ ├── mcp/ # MCP server tools进程内薄封装 cli/ services/ │ └── sync/ # 同步监控 ├── configs/ # 预设 JSON 抓取配置 ├── docs/ # 文档 ├── tests/ # 115 测试文件pytest └── .github/workflows/ # CI/CD 工作流8.2 Scraper 模式18 种源类型的统一接口每种源类型都是一个SkillConverter子类位于cli/type_scraper.py文档型源继承DocumentSkillBuilder后者提供完整的构建侧逻辑通过skill-seekers create的自动探测抵达——不存在每种类型的独立main()。在 src/skill_seekers/cli/skill_converter.py 中SkillConverter是所有转换器的抽象基类子类实现extract()run()统一执行「提取 构建 返回退出码」get_converter(source_type, config)负责按CONVERTER_REGISTRY查找并实例化对应转换器同时通过OPTIONAL_DEP_CHECKS在转换器查找阶段就快速失败缺可选依赖时立刻给出安装提示而不是在抓取中途崩溃。新增一种源类型时必须注册到 4 个位置CONVERTER_REGISTRYskill_converter.py——同时启用多源统一配置中的能力create_command.py的_build_config()source_detector.py自动探测逻辑config_validator.py的VALID_SOURCE_TYPES。CLI 参数只定义一次集中在parsers/*.py的SubcommandParser类中src/skill_seekers/cli/parsers/base.py并有专门的 drift-guard 测试强制保持一致——这意味着新增源类型时不要在各命令文件里散落定义参数而应在中央 parser 类中完成。8.3 其他关键设计统一 CLI 入口src/skill_seekers/cli/main.py 以COMMAND_CLASSEScreate/detect/scan/doctor/ui与COMMAND_MODULESenhance/package/upload/install/estimate等实现懒加载分发Adaptorscli/adaptors/下 26 个文件体现 Strategy Factory 模式SkillAdaptorABC 20 实现覆盖 Claude、OpenAI、Gemini、Qwen、Kimi、Chroma、Qdrant、Weaviate 等StorageBaseStorageAdaptor S3/GCS/Azure 的 Strategy FactoryParsersSubcommandParser 28 个子类的 Template MethodAnalysisBasePatternDetector 10 个 GoF 检测器的 Template Method。新增类或模块时请同步更新对应 UML 图见第 9 节保持架构文档与代码同步。9. UML 架构文档与文档规范9.1 UML 资源位置完整的 UML 类图在 StarUML 中维护并从源码同步docs/UML_ARCHITECTURE.md - 含内嵌 PNG 图的总览docs/UML/skill_seekers.mdj - StarUML 工程文件docs/UML/exports/ - 14 张 PNG 导出包总览 13 张类图docs/UML/html/ - HTML API 参考9.2 文档应写在哪里README.md- 总览、快速开始、基础用法README.md另有 README.zh-CN.md 等 12 种语言版本docs/- 详细指南与教程CHANGELOG.md- 所有显著变更代码注释- 复杂逻辑与非显然决策9.3 文档风格语言清晰简洁包含代码示例UI 相关功能配截图与代码变更保持同步10. 发布流程与贡献者认可10.1 Release 流程由维护者执行更新相关文件中的版本号更新 CHANGELOG.md创建并推送版本 tagGitHub Actions 自动生成 release在相关渠道发布公告10.2 贡献者认可贡献者会在以下位置获得署名README.md 的 contributors 区块、每个 release 的 CHANGELOG.md、GitHub contributors 页面。结语回到 CONTRIBUTING.md 开篇那句话——正是像你这样的人让 Skill_Seekers 变得更好。无论你想修一个 MCP 工具的 bug、为某个框架新增抓取配置还是接入一种全新的文档源类型只要遵循本文梳理的路径从development建分支 → 按 PEP 8 变体与 Ruff 写代码 → 用带内存守护的测试脚本验证 → 按 PR 模板提交你的改动就能顺畅地汇入主干。特别记住两条项目特色约定所有 PR 指向development以及 fix both, dont follow precedent——不要用既有坏代码为自己的反模式背书。祝贡献愉快赞分享人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载相关推荐Gutenberg 代码贡献完全指南开发环境搭建、Git 工作流与编码测试规范Gutenberg 代码贡献完全指南开发环境搭建、Git 工作流与编码测试规范 本文是 Gutenberg 项目WordPress 的块编辑器插件可从官方后端前端Zstandard 贡献指南分支工作流、性能基准测试与编码规范完全解析Zstandard 贡献指南分支工作流、性能基准测试与编码规范完全解析 本文围绕 Zstandardzstd官方贡献文档 CONTRIBUTING.md数据工程Caffe 开发与贡献指南分支工作流、测试体系与代码规范全解析Caffe 开发与贡献指南分支工作流、测试体系与代码规范全解析 Caffe 是由 Berkeley AI ResearchBAIR/ BVLC 主导、社区深度学习计算机视觉创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Skill_Seekers 贡献指南：分支工作流、开发环境、编码规范与测试基建全解析
人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载Skill_Seekers 是一个把文档网站、GitHub 仓库和 PDF 等 18 种来源自动转换为 Claude AI Skills 的开源项目本文以仓库根目录的 CONTRIBUTING.md 为骨架系统拆解其双分支协作模型、本地开发环境搭建、编码与测试规范并结合src/skill_seekers源码、pyproject.toml配置与测试脚本说明「如何正确地向该项目提交一份高质量 PR」。读完本文你将能独立完成从 fork、建分支、写代码、跑通受内存守护的测试套件到按规范提交 PR 的完整贡献闭环并理解新增 scraper 源类型时需要触碰的注册点。1. 双分支工作流main / development / featureSkill_Seekers 采用双分支模型Two-Branch Workflow这是所有贡献者必须先理解的第一条规则所有 PR 必须指向development分支而不是main。1.1 分支结构main (production) ↑ │ (only maintainer merges) │ development (integration) ← default branch for PRs ↑ │ (all contributor PRs go here) │ feature branches1.2 各分支职责分支角色规则main生产分支始终稳定仅由维护者从development合并受保护需测试通过 1 次 reviewdevelopment集成分支所有 PR 的默认目标分支活跃开发在此进行受保护需测试通过由维护者合并到mainfeature 分支贡献者的工作分支从development创建命名要有描述性如feature/123-add-github-scraping通过 PR 合回development1.3 完整操作示例# 1. Fork 并 clone这里以本镜像仓库为例 git clone https://gitcode.com/gh_mirrors/sk/Skill_Seekers.git cd Skill_Seekers # 2. 添加 upstream 远程仓库 git remote add upstream 上游仓库地址 # 3. 从 development 创建 feature 分支 git checkout development git pull upstream development git checkout -b my-feature # 4. 修改、提交、推送 git add . git commit -m Add my feature git push origin my-feature # 5. 创建指向 development 分支的 Pull Request⚠️ 提交到main的 PR 会被拒绝提交信息建议使用清晰描述性写法如feat: add github scraping。2. 项目生态贡献之前先找对仓库CONTRIBUTING.md 明确说明 Skill_Seekers 横跨多个仓库不同诉求应贡献到不同仓库避免把 Web 前端或配置改动误提到主仓库想做什么对应仓库核心 CLI、scrapers、MCP 工具、adaptorsSkill_Seekers本仓库网站、文档、UI/UXskillseekersweb预设配置、社区配置skill-seekers-configsGitHub Action 集成skill-seekers-actionClaude Code 插件skill-seekers-pluginHomebrew 公式homebrew-skill-seekers本仓库内也有与这些生态对应的落地目录例如 distribution/github-action/action.ymlGitHub Action 定义、distribution/claude-pluginClaude Code 插件以及configs/下的预设抓取配置见第 4 节。修改前务必确认你改的是主仓库中真正对应的部分。3. 开发环境搭建Development Setup3.1 前置条件Python 3.10 或更高MCP 集成必需pyproject.toml 中requires-python 3.10与此一致Git3.2 安装步骤# 1. Fork 并 clone 仓库见 1.3 # 2. 安装依赖editable 模式便于开发时实时生效 pip install -e . pip install -e .[dev] pip install -e .[all].[dev]对应 pyproject.toml 中[dependency-groups] dev定义pytest、pytest-asyncio、pytest-cov、coverage、ruff、mypy、psutil测试内存守护依赖、boto3 等云存储测试依赖。.[all]聚合所有可选特性依赖MCP、各 LLM 平台、RAG 向量库、云存储、新源类型等。video-full因含 OpenCV/easyocr/faster-whisper 等重型原生依赖被刻意排除在all之外需要时单独安装。测试部分还建议使用uv sync管理环境并安装pytest-timeout、pytest-xdist以支持超时控制与并行执行。3.3 常用命令流程# 3. 从 development 创建功能分支 git checkout development git pull upstream development git checkout -b feature/my-awesome-feature # 4. 修改代码见第 6、8 节了解结构与规范 # 5. 运行测试 python -m pytest tests/ -v # 6. 提交 git add . git commit -m Add awesome feature # 7. 推送到自己的 fork git push origin feature/my-awesome-feature # 8. 创建 Pull Request4. 如何贡献Bug 报告、功能建议与新框架配置4.1 报告 Bug报告前先检索 [existing issues]GitHub issues 页避免重复。一份合格的 Bug 报告应包含清晰的标题与描述可复现步骤期望行为 vs 实际行为截图如适用环境信息操作系统、Python 版本等错误信息与堆栈追踪CONTRIBUTING.md 给出了贴近本项目的示例**Bug:** MCP tool fails when config has no categories **Steps to Reproduce:** 1. Create config with empty categories: categories: {} 2. Run skill-seekers create --config configs/test.json 3. See error **Expected:** Should use auto-inferred categories **Actual:** Crashes with KeyError **Environment:** - OS: Ubuntu 22.04 - Python: 3.10.5 - Version: 1.0.04.2 建议增强功能以 issue 形式提交需包含清晰标题、功能详述、受益用例、工作方式示例、备选方案。4.3 新增框架配置Adding New Framework Configs项目欢迎新的框架配置流程是在configs/目录创建配置文件用不同页数充分测试提交 PR附上配置文件、框架简介、测试结果抓取页数、识别出的分类仓库中configs/已有一批现成示例例如 configs/claude-code.json、configs/react.json、configs/unity-dotween.json 等。以claude-code.json为例一个完整的抓取配置包含如下关键字段{ name: claude-code, description: Claude Code CLI and development environment. ..., merge_mode: rule-based, sources: [ { type: documentation, base_url: https://code.claude.com/docs/en/, start_urls: [https://code.claude.com/docs/en/overview, ...], selectors: { main_content: #content-area, #content-container, article, main, title: h1, code_blocks: pre code }, url_patterns: { include: [/docs/en/], exclude: [/docs/fr/, /changelog, github.com] }, categories: { getting_started: [overview, quickstart], mcp: [mcp, model-context-protocol] }, rate_limit: 0.5, max_pages: 250 } ] }其中merge_mode合并模式、selectorsCSS 选择器、url_patternsURL 包含/排除规则、categories文档分类映射、rate_limit请求间隔秒数与max_pages最大抓取页数共同决定了抓取行为与产出 SKILL 的分类结构。建议新增配置时参考同目录既有文件的字段完整度。示例 PR 描述**Add Svelte Documentation Config** Adds configuration for Svelte documentation (https://svelte.dev/docs). - Config: configs/svelte.json - Tested with max_pages: 100 - Successfully categorized: getting_started, components, api, advanced - Total pages available: ~1504.4 Pull Requests 总则Fork 仓库并从development创建分支新增了代码就补测试改了 API 就更新文档确保测试套件通过遵循编码规范第 6 节PR 提交到development分支5. Pull Request 流程与 Code Review 原则5.1 提交前自检清单本地测试通过python -m pytest tests/ -v代码符合 PEP 8 风格本项目变体见第 6 节文档已按需更新CHANGELOG.md 已更新如适用提交信息清晰且具描述性5.2 PR 模板## Description Brief description of what this PR does. ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update ## How Has This Been Tested? Describe the tests you ran to verify your changes. ## Checklist - [ ] My code follows the style guidelines of this project - [ ] I have performed a self-review of my own code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes5.3 Review 流程维护者通常在 3-5 个工作日内 review及时回应反馈或修改意见通过后由维护者合并贡献会进入下一个 release5.4 Code Review 黄金原则Fix both, dont follow precedent这是 CONTRIBUTING.md 中最具项目特色的一条工程哲学当 reviewer 指出你 PR 中的反模式时不能指着仓库里另一处相同写法来辩护。X.py already does this不是正当理由——它恰恰说明两处都需要修而不是这个坏味道被默许了。✅ 正确回应Good catch — Ill fix bothnew_file.pyandexisting_file.pyin this PR.本次一并修复✅ 正确回应Out of scope here, but Ill file a follow-up to fixexisting_file.py.记一个后续 issue❌ 错误回应Butexisting_file.pydoes the same thing, so this matches the convention.以既有坏代码为借口这条规则对维护者同样有效指出反模式的人应当愿意接受更广范围的修复或自己开 follow-up issue。坏先例即惯例正是代码库僵化的根源。6. 编码规范PEP 8 变体与 Ruff6.1 Python 风格项目遵循 PEP 8 但做了若干修改与 pyproject.toml 中[tool.ruff] line-length 100完全一致行宽100 字符而非默认 79缩进4 空格引号字符串使用双引号命名函数/变量用snake_case类用PascalCase常量用UPPER_SNAKE_CASE6.2 代码组织顺序# 1. Standard library imports import os import sys from pathlib import Path # 2. Third-party imports import requests from bs4 import BeautifulSoup # 3. Local application imports from cli.utils import open_folder # 4. Constants MAX_PAGES 1000 DEFAULT_RATE_LIMIT 0.5 # 5. Functions and classes def my_function(): Docstring describing what this function does. pass6.3 文档与类型标注所有函数应有 docstring、尽量使用类型标注、复杂逻辑加注释。仓库中大量模块正是这么做的例如 src/skill_seekers/cli/skill_converter.py 的基类即为带类型标注和 docstring 的示范def scrape_page(url: str, selectors: dict) - dict: Scrape a single page and extract content. Args: url: The URL to scrape selectors: Dictionary of CSS selectors Returns: Dictionary containing extracted content Raises: RequestException: If page cannot be fetched pass6.4 Ruff本项目的 lint 与格式化工具项目使用Ruff集 Flake8、isort、Black 等为一体、速度极快的 Python linter。# 检查 lint 错误 uvx ruff check src/ tests/ # 自动修复 uvx ruff check --fix src/ tests/ # 格式化代码 uvx ruff format src/ tests/常用 Ruff 规则对应 pyproject.toml 中[tool.ruff.lint] select的E/W/F/I/B/C4/UP/ARG/SIM系列SIM102- 简化嵌套 if改用andSIM117- 合并多个with语句B904- 使用from e进行正确的异常链SIM113- 用enumerate代替手动计数器B007- 未使用的循环变量用_ARG002- 删除未使用的函数参数注ARG002与B007在[tool.ruff.lint] ignore中被豁免接口合规或有时是有意为之但规则表仍列出以说明团队的关注点。6.5 CI/CD 集成所有 PR 会自动依次运行ruff check- Lint 校验ruff format --check- 格式校验pytest- 测试套件提交前先在本地跑同样的检查uvx ruff check src/ tests/ uvx ruff format --check src/ tests/ pytest tests/ -v7. 测试从单文件到带内存守护的完整套件7.1 运行方式CONTRIBUTING.md 给出了两条主路径且与仓库内脚本一一对应# 方式一带内存监控与逐测试超时的完整套件 python scripts/run_tests_safe.py -- tests/ -v --timeout120 # 方式二三阶段测试快速阶段默认 2 个 worker bash scripts/run_tests_fast.sh # 调整进程树内存预算 python scripts/run_tests_safe.py --max-rss-mb 2048 -- tests/ -q --timeout120 # 只跑单个测试文件 python -m pytest tests/test_mcp_server.py -v # 带覆盖率统计 python -m pytest tests/ --covsrc/skill_seekers --cov-reportterm7.2 内存守护测试运行器run_tests_safe.py这是本项目测试基建的一大特色。scripts/run_tests_safe.py 是一个用psutil实现的「守护型」pytest 运行器限制整个进程树的聚合 RSS默认上限4 GiB--max-rss-mb一旦超限立即以退出码 137 终止当系统可用内存低于 2 GiB--min-available-mb时同样停止测试退出时清理全部后代进程os.killpgpsutil.wait_procs防止子进程残留这些采样限制属于安全余量safety margin并非操作系统的硬性上限收到 SIGTERMCI 环境或 CtrlC 时会优雅转发信号让 pytest 先输出汇总再清理。7.3 三阶段测试脚本run_tests_fast.shscripts/run_tests_fast.sh 将测试拆为三个互不重叠的阶段对应 pyproject.toml 中[tool.pytest.ini_options] markers声明的标记体系Phase 1 快速单元测试-m not slow and not integration and not e2e and not network and not serial and not mcp_only默认 2 个 workerTEST_WORKERS可调、--timeout120Phase 2 串行/集成/E2E-m (integration or e2e or slow or network or serial) and not mcp_only、--timeout300Phase 3 MCP 测试-m mcp_only、--timeout180。两个脚本都支持环境变量TEST_PYTHON、TEST_WORKERS、TEST_MAX_RSS_MB覆盖默认值适合 CI 或资源受限环境。7.4 编写测试的约定测试放在tests/目录文件名以test_开头与 pyproject.toml 的python_files [test_*.py]一致测试名要有描述性涉及子进程的 fixture 必须走 tests/subprocess_helpers.py 的run_process_tree这样超时时能连带杀掉孙进程bootstrap 会调用 bash → uv → Python只杀 bash 会让昂贵的 Python 分析存活生成物放在tmp_path中mock 掉真实的 agent/API 边界移除 mock 前先 join 后台线程测试不得调用已安装的 AI CLI也不得同步当前活动环境。参考示例def test_config_validation_with_missing_fields(): Test that config validation fails when required fields are missing. config {name: test} # Missing base_url result validate_config(config) assert result is False7.5 覆盖率目标整体覆盖率目标80%关键路径100%覆盖修复 bug 时必须补回归测试仓库测试规模相当可观tests/下 200 个测试文件覆盖 scraper、adaptor、MCP、Web UI、workflows、同步机制等新增功能时务必保证不破坏既有断言。8. 项目结构与扩展点读懂代码再动手8.1 顶层结构CONTRIBUTING.md 给出了精确的目录映射以下为精简版完整说明见文档原文Skill_Seekers/ ├── src/skill_seekers/ # 主包src/ 布局 │ ├── cli/ # CLI 命令与入口 │ │ ├── main.py # 统一 CLI 入口COMMAND_MODULES 字典 │ │ ├── source_detector.py # 自动探测源类型 │ │ ├── create_command.py # 统一 create 命令路由 │ │ ├── config_validator.py # VALID_SOURCE_TYPES 集合 │ │ ├── unified_scraper.py # 多源编排器 │ │ ├── unified_skill_builder.py # 成对合成 通用合并 │ │ ├── doc_scraper.py / github_scraper.py / pdf_scraper.py / ... │ │ ├── adaptors/ # 平台适配器Strategy 模式 │ │ ├── arguments/ # 每个源一个的 CLI 参数定义 │ │ ├── parsers/ # 每个源一个的子命令解析器 │ │ └── storage/ # 云存储适配器 │ ├── services/ # 共享领域逻辑marketplace、config publishing、git sources │ ├── mcp/ # MCP server tools进程内薄封装 cli/ services/ │ └── sync/ # 同步监控 ├── configs/ # 预设 JSON 抓取配置 ├── docs/ # 文档 ├── tests/ # 115 测试文件pytest └── .github/workflows/ # CI/CD 工作流8.2 Scraper 模式18 种源类型的统一接口每种源类型都是一个SkillConverter子类位于cli/type_scraper.py文档型源继承DocumentSkillBuilder后者提供完整的构建侧逻辑通过skill-seekers create的自动探测抵达——不存在每种类型的独立main()。在 src/skill_seekers/cli/skill_converter.py 中SkillConverter是所有转换器的抽象基类子类实现extract()run()统一执行「提取 构建 返回退出码」get_converter(source_type, config)负责按CONVERTER_REGISTRY查找并实例化对应转换器同时通过OPTIONAL_DEP_CHECKS在转换器查找阶段就快速失败缺可选依赖时立刻给出安装提示而不是在抓取中途崩溃。新增一种源类型时必须注册到 4 个位置CONVERTER_REGISTRYskill_converter.py——同时启用多源统一配置中的能力create_command.py的_build_config()source_detector.py自动探测逻辑config_validator.py的VALID_SOURCE_TYPES。CLI 参数只定义一次集中在parsers/*.py的SubcommandParser类中src/skill_seekers/cli/parsers/base.py并有专门的 drift-guard 测试强制保持一致——这意味着新增源类型时不要在各命令文件里散落定义参数而应在中央 parser 类中完成。8.3 其他关键设计统一 CLI 入口src/skill_seekers/cli/main.py 以COMMAND_CLASSEScreate/detect/scan/doctor/ui与COMMAND_MODULESenhance/package/upload/install/estimate等实现懒加载分发Adaptorscli/adaptors/下 26 个文件体现 Strategy Factory 模式SkillAdaptorABC 20 实现覆盖 Claude、OpenAI、Gemini、Qwen、Kimi、Chroma、Qdrant、Weaviate 等StorageBaseStorageAdaptor S3/GCS/Azure 的 Strategy FactoryParsersSubcommandParser 28 个子类的 Template MethodAnalysisBasePatternDetector 10 个 GoF 检测器的 Template Method。新增类或模块时请同步更新对应 UML 图见第 9 节保持架构文档与代码同步。9. UML 架构文档与文档规范9.1 UML 资源位置完整的 UML 类图在 StarUML 中维护并从源码同步docs/UML_ARCHITECTURE.md - 含内嵌 PNG 图的总览docs/UML/skill_seekers.mdj - StarUML 工程文件docs/UML/exports/ - 14 张 PNG 导出包总览 13 张类图docs/UML/html/ - HTML API 参考9.2 文档应写在哪里README.md- 总览、快速开始、基础用法README.md另有 README.zh-CN.md 等 12 种语言版本docs/- 详细指南与教程CHANGELOG.md- 所有显著变更代码注释- 复杂逻辑与非显然决策9.3 文档风格语言清晰简洁包含代码示例UI 相关功能配截图与代码变更保持同步10. 发布流程与贡献者认可10.1 Release 流程由维护者执行更新相关文件中的版本号更新 CHANGELOG.md创建并推送版本 tagGitHub Actions 自动生成 release在相关渠道发布公告10.2 贡献者认可贡献者会在以下位置获得署名README.md 的 contributors 区块、每个 release 的 CHANGELOG.md、GitHub contributors 页面。结语回到 CONTRIBUTING.md 开篇那句话——正是像你这样的人让 Skill_Seekers 变得更好。无论你想修一个 MCP 工具的 bug、为某个框架新增抓取配置还是接入一种全新的文档源类型只要遵循本文梳理的路径从development建分支 → 按 PEP 8 变体与 Ruff 写代码 → 用带内存守护的测试脚本验证 → 按 PR 模板提交你的改动就能顺畅地汇入主干。特别记住两条项目特色约定所有 PR 指向development以及 fix both, dont follow precedent——不要用既有坏代码为自己的反模式背书。祝贡献愉快赞分享人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载相关推荐Gutenberg 代码贡献完全指南开发环境搭建、Git 工作流与编码测试规范Gutenberg 代码贡献完全指南开发环境搭建、Git 工作流与编码测试规范 本文是 Gutenberg 项目WordPress 的块编辑器插件可从官方后端前端Zstandard 贡献指南分支工作流、性能基准测试与编码规范完全解析Zstandard 贡献指南分支工作流、性能基准测试与编码规范完全解析 本文围绕 Zstandardzstd官方贡献文档 CONTRIBUTING.md数据工程Caffe 开发与贡献指南分支工作流、测试体系与代码规范全解析Caffe 开发与贡献指南分支工作流、测试体系与代码规范全解析 Caffe 是由 Berkeley AI ResearchBAIR/ BVLC 主导、社区深度学习计算机视觉创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考