Skill_Seekers 贡献指南：分支工作流、开发环境、编码规范与测试基建全解析

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫

Skill_Seekers 是一个把文档网站、GitHub 仓库和 PDF 等 18 种来源自动转换为 Claude AI Skills 的开源项目，本文以仓库根目录的 CONTRIBUTING.md 为骨架，系统拆解其双分支协作模型、本地开发环境搭建、编码与测试规范，并结合src/skill_seekers源码、pyproject.toml配置与测试脚本，说明「如何正确地向该项目提交一份高质量 PR」。读完本文，你将能独立完成从 fork、建分支、写代码、跑通受内存守护的测试套件，到按规范提交 PR 的完整贡献闭环，并理解新增 scraper 源类型时需要触碰的注册点。

1. 双分支工作流：main / development / feature

Skill_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 branches

1.2 各分支职责

1.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 前端或配置改动误提到主仓库：

本仓库内也有与这些生态对应的落地目录，例如 distribution/github-action/action.yml（GitHub Action 定义）、distribution/claude-plugin（Claude Code 插件）以及configs/下的预设抓取配置（见第 4 节）。修改前务必确认你改的是主仓库中真正对应的部分。

3. 开发环境搭建（Development Setup）

3.1 前置条件

• Python 3.10 或更高（MCP 集成必需，pyproject.toml 中requires-python = ">=3.10"与此一致）
• Git

3.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 Request

4. 如何贡献：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.0

4.2 建议增强功能

以 issue 形式提交，需包含：清晰标题、功能详述、受益用例、工作方式示例、备选方案。

4.3 新增框架配置（Adding New Framework Configs）

项目欢迎新的框架配置，流程是：

1. 在configs/目录创建配置文件
2. 用不同页数充分测试
3. 提交 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（合并模式）、selectors（CSS 选择器）、url_patterns（URL 包含/排除规则）、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: ~150

4.4 Pull Requests 总则

1. Fork 仓库并从development创建分支
2. 新增了代码就补测试
3. 改了 API 就更新文档
4. 确保测试套件通过
5. 遵循编码规范（第 6 节）
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 changes

5.3 Review 流程

1. 维护者通常在 3-5 个工作日内 review
2. 及时回应反馈或修改意见
3. 通过后由维护者合并
4. 贡献会进入下一个 release

5.4 Code Review 黄金原则：Fix both, don't follow precedent

这是 CONTRIBUTING.md 中最具项目特色的一条工程哲学：当 reviewer 指出你 PR 中的反模式时，不能指着仓库里另一处相同写法来辩护。"X.py already does this"不是正当理由——它恰恰说明两处都需要修，而不是这个坏味道被默许了。

• ✅ 正确回应："Good catch — I'll fix bothnew_file.pyandexisting_file.pyin this PR."（本次一并修复）
• ✅ 正确回应："Out of scope here, but I'll 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 变体与 Ruff

6.1 Python 风格

项目遵循 PEP 8 但做了若干修改（与 pyproject.toml 中[tool.ruff] line-length = 100完全一致）：

• 行宽：100 字符（而非默认 79）
• 缩进：4 空格
• 引号：字符串使用双引号
• 命名：函数/变量用snake_case；类用PascalCase；常量用UPPER_SNAKE_CASE

6.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.""" pass

6.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 """ pass

6.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（改用and）
• SIM117- 合并多个with语句
• B904- 使用from e进行正确的异常链
• SIM113- 用enumerate代替手动计数器
• B007- 未使用的循环变量用_
• ARG002- 删除未使用的函数参数

注：ARG002与B007在[tool.ruff.lint] ignore中被豁免（接口合规或有时是有意为之），但规则表仍列出以说明团队的关注点。

6.5 CI/CD 集成

所有 PR 会自动依次运行：

1. ruff check- Lint 校验
2. ruff format --check- 格式校验
3. pytest- 测试套件

提交前先在本地跑同样的检查：

uvx ruff check src/ tests/ uvx ruff format --check src/ tests/ pytest tests/ -v

7. 测试：从单文件到带内存守护的完整套件

7.1 运行方式

CONTRIBUTING.md 给出了两条主路径，且与仓库内脚本一一对应：

# 方式一：带内存监控与逐测试超时的完整套件 python scripts/run_tests_safe.py -- tests/ -v --timeout=120 # 方式二：三阶段测试（快速阶段默认 2 个 worker） bash scripts/run_tests_fast.sh # 调整进程树内存预算 python scripts/run_tests_safe.py --max-rss-mb 2048 -- tests/ -q --timeout=120 # 只跑单个测试文件 python -m pytest tests/test_mcp_server.py -v # 带覆盖率统计 python -m pytest tests/ --cov=src/skill_seekers --cov-report=term

7.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.killpg+psutil.wait_procs），防止子进程残留；
• 这些采样限制属于安全余量（safety margin），并非操作系统的硬性上限；
• 收到 SIGTERM（CI 环境）或 Ctrl+C 时会优雅转发信号，让 pytest 先输出汇总再清理。

7.3 三阶段测试脚本（run_tests_fast.sh）

scripts/run_tests_fast.sh 将测试拆为三个互不重叠的阶段（对应 pyproject.toml 中[tool.pytest.ini_options] markers声明的标记体系）：

1. Phase 1 快速单元测试：-m "not slow and not integration and not e2e and not network and not serial and not mcp_only"，默认 2 个 worker（TEST_WORKERS可调）、--timeout=120；
2. Phase 2 串行/集成/E2E：-m "(integration or e2e or slow or network or serial) and not mcp_only"、--timeout=300；
3. Phase 3 MCP 测试：-m "mcp_only"、--timeout=180。

两个脚本都支持环境变量（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 False

7.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 个位置：

1. CONVERTER_REGISTRY（skill_converter.py）——同时启用多源统一配置中的能力；
2. create_command.py的_build_config()；
3. source_detector.py（自动探测逻辑）；
4. 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_CLASSES（create/detect/scan/doctor/ui）与COMMAND_MODULES（enhance/package/upload/install/estimate等）实现懒加载分发；
• Adaptors：cli/adaptors/下 26 个文件，体现 Strategy + Factory 模式（SkillAdaptorABC + 20+ 实现，覆盖 Claude、OpenAI、Gemini、Qwen、Kimi、Chroma、Qdrant、Weaviate 等）；
• Storage：BaseStorageAdaptor+ S3/GCS/Azure 的 Strategy + Factory；
• Parsers：SubcommandParser+ 28 个子类的 Template Method；
• Analysis：BasePatternDetector+ 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 流程（由维护者执行）

1. 更新相关文件中的版本号
2. 更新 CHANGELOG.md
3. 创建并推送版本 tag
4. GitHub Actions 自动生成 release
5. 在相关渠道发布公告

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, don't follow precedent"——不要用既有坏代码为自己的反模式背书。祝贡献愉快！

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫