Skill Seekers 的 AGENTS.md 工程指南面向 AI 编码 Agent 的仓库导航、测试与扩展规范【免费下载链接】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、视频、Notebook、Wiki 等内容转换为可供 21 个 LLM 平台与 RAG 流水线直接消费的 AI Skill 的 Python CLI 工具当前仓库源码版本见 pyproject.toml为3.10.0.dev0仓库根目录的 AGENTS.md 是专为 AI 编码 Agent 编写的综合参考文档其标注版本 v3.6.0 属于文档快照实际以发布版本为准。本文以 AGENTS.md 为骨架结合仓库源码、配置与测试完整讲解如何快速完成环境搭建、跑通测试与 CI 流程、理解分层架构与关键设计模式并在此基础上为 Skill Seekers 贡献新源码类型与新平台适配器。读完本文你将掌握Skill Seekers 的完整开发环境初始化与测试矩阵17 种源码类型与 22 个平台适配器的注册与扩展机制统一多源抓取流水线Unified Pipeline与 MCP 服务器的内部结构以及一套可直接复用的代码风格与提交流程规范。项目概览与核心能力Skill Seekers 本质上是一个通用预处理层universal preprocessing layer它把原始文档与代码转化为结构化的知识资产再按目标平台格式打包成可安装的 Skill。其能力可归纳为三个维度17 种源码类型文档网站documentation、GitHub 仓库、PDF、Word 文档、EPUB、视频、本地代码库local、Jupyter Notebook、HTML、OpenAPI 规范、AsciiDoc、PowerPoint、Confluence、Notion、RSS 订阅、man 手册页、聊天记录导出chat。这一清单在 config_validator.py 中以VALID_SOURCE_TYPES集合形式被强制执行。导出目标平台Claude、Gemini、OpenAI、MiniMax、OpenCode、Kimi、DeepSeek、Qwen、OpenRouter、Together AI、Fireworks AI、Markdown、LangChain、LlamaIndex、Haystack、Weaviate、ChromaDB、FAISS、Qdrant、Pinecone。从源码看adaptors/init.py 中的ADAPTORS注册表实际注册了 22 个适配器除文档列出的平台外还包含ibm-bob与atlas。MCP 服务器基于 FastMCP 的 Model Context Protocol 服务器server_fastmcp.py供 AI 助手直接调用抓取、打包、工作流与向量库导出能力。环境搭建editable 安装是硬前提安装命令与可选依赖组AGENTS.md 明确指出运行测试前必须先以 editable 模式安装。原因在 tests/conftest.py 中写得很清楚——pytest_configure会尝试导入skill_seekers一旦ModuleNotFoundError就打印安装提示并sys.exit(1)直接退出。# 必做src/ 布局下测试的硬性前置 pip install -e . # 带开发工具pytest, ruff, mypy, coverage pip install -e .[dev] # 按需选择 LLM 平台支持 pip install -e .[gemini] # Google Gemini pip install -e .[openai] # OpenAI ChatGPT pip install -e .[all-llms] # 全部 LLM 平台 # 除 video-full 外的全部可选依赖 pip install -e .[all] # 完整视频处理依赖较重 pip install -e .[video-full]结合 pyproject.toml 可梳理出更细的 extras 设计思路Extra 组用途典型依赖mcpMCP 服务器已真正可选化mcp1.25,2、uvicorn、starlette、sse-starlettegemini/openai单一 LLM 平台google-generativeai/openai1.0.0kimi/deepseek/qwen/openrouter/together/fireworks/minimax其余平台复用 OpenAI 兼容 API均依赖openai1.0.0all-llms全部 LLM 平台google-generativeaiopenaidocx/epubWord/EPUB 解析mammoth、python-docx/ebooklibvideo/video-full视频转录 / 完整视觉提取yt-dlp、youtube-transcript-api/faster-whisper、opencv-python-headless、pytesseractchroma/weaviate/pinecone/rag-upload向量数据库上传chromadb、weaviate-client4、pinecone5.0.0s3/gcs/azure/all-cloud云存储boto3、google-cloud-storage、azure-storage-blobjupyter/asciidoc/pptx/confluence/notion/rss/chat新增源码类型依赖nbformat、asciidoc、python-pptx、atlassian-python-api、notion-client、feedparser、slack-sdkbrowserSPA 站点无头浏览器渲染playwright1.40.0embeddingFastAPI 嵌入服务fastapi、sentence-transformers、voyageaiuiSeeker HUD Web UIfastapi、uvicorn一个值得注意的工程细节video-full曾引入easyocr但因它会拉取错误的 GPU 版 PyTorch 而移除了因此[all]显式排除video-full需要完整视频能力时用skill-seekers video --setup自动检测 GPU 并安装正确的 PyTorch。环境变量创建.env文件或直接导出以下变量即可ANTHROPIC_API_KEY # 用于 Claude AI 增强 GOOGLE_API_KEY # 用于 Gemini 支持 OPENAI_API_KEY # 用于 OpenAI 支持 GITHUB_TOKEN # 用于 GitHub 仓库抓取获得更高 API 速率限制构建 / 测试 / 代码质量完整命令矩阵AGENTS.md 给出了一套从全量到快速迭代的测试命令体系# 完整测试套件绝不可跳过——必须全部通过 pytest tests/ -v # 快速迭代跳过 slow / integration / E2E / network / MCP pytest tests/ -m not slow and not integration and not e2e and not network and not serial and not mcp_only -q # 快速并行需先安装 pytest-xdist pytest tests/ -n auto --distloadfile -m not slow and not integration and not e2e and not network and not serial and not mcp_only -q # 推荐本地开发使用的三阶段 runner 脚本 bash scripts/run_tests_fast.sh # 单个测试 pytest tests/test_scraper_features.py::test_detect_language -v # 跳过慢速 / 集成测试 pytest tests/ -v -m not slow and not integration # 带覆盖率 pytest tests/ --covsrc/skill_seekers --cov-reportterm # 代码质量检查与 CI 对齐 ruff check src/ tests/ ruff format --check src/ tests/ # 类型检查非阻塞——CI 中 mypy 为 continue-on-error mypy src/skill_seekers --show-error-codes --prettyPytest 配置要点来自 pyproject.tomlasyncio_mode auto因此pytest.mark.asyncio是隐式的测试标记包括slow、integration、e2e、venv、bootstrap、benchmark、asyncio、serial、network、mcp_only。其中serial用于必须独跑的测试共享 HTTP 服务器、单例变更network用于真正发起 HTTP 调用或需要 Docker 服务的测试。CI 注意点CI 锁定ruff0.15.8而非 dev 依赖中的0.14.13。如果本地格式化和 CI 表现不一致请先核对 CI 版本。CI 测试阶段测试被拆成 3 个并行 job——test-fast约 3386 个单元测试跨 OS/Python 矩阵用 xdist 跑、test-serial约 69 个串行/集成/E2E/网络测试、test-mcp约 193 个 MCP 测试需要[mcp]extras。以上数量来自 AGENTS.md 的 CI 描述具体以 .github/workflows/tests.yml 的当前配置为准。代码风格与工程规范Ruff 格式规则来自 pyproject.toml行宽100 字符目标 Python3.10启用的 lint 规则E、W、F、I、B、C4、UP、ARG、SIM忽略的规则E501行长交给 formatter、F541f-string 风格、ARG002接口兼容所需的未使用方法参数、B007有意的未使用循环变量、I001导入排序交给 formatter、SIM114可读性优先导入与依赖守卫导入按标准库 → 第三方 → 第一方分组排序经 ruff/isortskill_seekers被视为 first-party。只有在需要前向引用时才使用from __future__ import annotations。可选依赖必须用 try/except ImportError 守卫模式见 adaptors/init.pytry: from .claude import ClaudeAdaptor from .minimax import MiniMaxAdaptor except ImportError: ClaudeAdaptor None MiniMaxAdaptor None命名与类型约定文件snake_case.py如 source_detector.py、config_validator.py类PascalCase如SkillAdaptor、ClaudeAdaptor、SourceDetector函数/方法snake_case如get_adaptor()、detect_language()常量UPPER_CASE如ADAPTORS、DEFAULT_CHUNK_TOKENS、VALID_SOURCE_TYPES私有成员下划线前缀如_read_existing_content()、_validate_unified()类型提示渐进式gradual typing采用现代语法str | None、list[str]。mypy 配置为disallow_untyped_defs false、check_untyped_defs true、ignore_missing_imports true测试目录放宽为两项均为 falseDocstring、错误处理与 lint 抑制每个文件必须有模块级 docstring公开函数/类使用 Google 风格 docstring包含Args:、Returns:、Raises:章节禁用裸except:必须使用具体异常非法参数用raise ValueError(...)状态错误用raise RuntimeError(...)包装异常时用raise ... from e链接可选依赖导入失败时给出清晰的安装指引使用行内# noqa: XXXX抑制警告如重导出用# noqa: F401项目布局从根目录快速定位代码src/skill_seekers/ # 主包src/ 布局 cli/ # CLI 命令与入口100 文件 adaptors/ # 平台适配器策略模式继承 SkillAdaptor arguments/ # CLI 参数定义每个源码类型一个 parsers/ # 子命令解析器每个源码类型一个 storage/ # 云存储继承 BaseStorageAdaptor main.py # 统一 CLI 入口COMMAND_MODULES 字典 source_detector.py # 从用户输入自动检测源码类型 create_command.py # 统一 create 命令路由 config_validator.py # VALID_SOURCE_TYPES 集合 各类型校验 unified_scraper.py # 多源编排scraped_data dispatch unified_skill_builder.py # 成对合成 通用合并 mcp/ # MCP 服务器FastMCP legacy tools/ # MCP 工具实现按类别分文件 server_fastmcp.py # FastMCP 服务器实现 server_legacy.py # Legacy MCP 服务器 sync/ # 同步监控Pydantic 模型 benchmark/ # 基准测试框架 embedding/ # FastAPI 嵌入服务器 workflows/ # YAML 工作流预设 _version.py # 从 pyproject.toml 读取版本 tests/ # pytest 测试160 个测试文件 test_adaptors/ # 22 个适配器专项测试文件 conftest.py # 测试配置含包检查 configs/ # 预设 JSON 抓取配置 docs/ # 文档指南、集成、架构仓库中现成的预设配置位于 configs/ 目录例如react.json、godot_unified.json、unity-dotween.json、astrovalley_unified.json等可直接作为统一配置格式的实操参考。项目架构总览图docs/UML/exports/00_package_overview.png可用于理解上述各模块之间的依赖关系。关键设计模式理解后可扩展的四个支柱1. Adaptor策略模式所有平台逻辑收敛在 cli/adaptors/ 下。新平台需要继承SkillAdaptor实现format_skill_md()、package()、upload()三个核心方法并在 adaptors/init.py 的ADAPTORS字典中注册。注册表通过get_adaptor(platform, config)工厂方法对外提供实例未知平台会抛出带可用平台列表的ValueError。get_enhancement_platforms()与get_upload_platforms()直接由各适配器的supports_enhancement()/supports_upload()能力派生保证命令行--target选项永远不会与真实能力漂移。2. Scraper 模式每种源码类型遵循三件套结构cli/type_scraper.py包含TypeToSkillConverter类与main()函数cli/arguments/type.pyCLI 参数定义cli/parsers/type_parser.py子命令解析器新增类型需要同时在三处注册parsers/init.py 的PARSERS列表、main.py 的COMMAND_MODULES字典、config_validator.py 的VALID_SOURCE_TYPES集合。3. 统一流水线Unified Pipeline多源配置skill-seekers create configs/xxx_unified.json由 unified_scraper.py 编排SOURCE_DISPATCH字典把源码类型映射到_scrape_type()方法通过 getattr 动态派发便于测试打桩走抓取各源 → 冲突检测 → 规则/AI 合并 → 构建统一 Skill五个阶段。unified_skill_builder.py 负责最终合成生成带合并 API 与冲突警告⚠️ 内联标记的SKILL.md、按源组织的references/目录以及独立的冲突摘要章节对documentation github pdf组合使用成对合成pairwise synthesis其余组合走_generic_merge()。_MANAGED_REFERENCE_ENTRIES保证被删除的源不会在references/留下陈旧内容。4. CLI 子命令与 MCP 工具CLI 采用 git 风格子命令统一入口在 main.py命令分两类——COMMAND_CLASSEScreate/detect/scan/doctor/ui类式Cls(args).execute()派发直接传递已解析的 namespace与COMMAND_MODULES模块式main(args...)派发取代了旧版脆弱的_reconstruct_argv往返解析MCP 工具按类别存放在 mcp/tools/ 下scrape_generic_tool统一处理所有新增源码类型server_fastmcp.py 采用装饰器式注册共提供 34 个工具覆盖配置、抓取、打包、拆分、源管理、市场、向量库与工作流 7 大类源码类型自动检测source_detector.py 中的SourceDetector.detect()根据正则与文件扩展名自动识别输入GitHub 仓库支持owner/repo与 URL 两种形态GITHUB_REPO_PATTERN/GITHUB_URL_PATTERN此外支持 URL、本地目录、PDF/DOCX/EPUB/IPYNB/HTML/OpenAPI/AsciiDoc/PPTX/RSS/man 页/视频文件/配置 JSON 等 14 类型。注意Confluence、Notion、Slack/Discord 聊天是 API/导出型来源无法从单个参数自动检测需使用各自专用子命令。SourceValidationError是ValueError的子类用于区分无法检测与已检测但不可用两种失败。Web UISeeker HUDSeeker HUD 是本地 Web 应用前端为 React 19 Vite Tailwind/shadcn位于 ui/后端为 FastAPI位于 src/skill_seekers/web/。# 启动应用自动打开浏览器API 运行在 :8770 skill-seekers ui # 前端开发模式热重载将 /api 代理到 :8770 cd ui npm install npm run dev # 构建前端Vite 输出到 src/skill_seekers/web/dist # 后端直接托管该目录wheel 也将其作为 package-data 打包 cd ui npm run build后端依赖用pip install -e .[ui]fastapi uvicorn也包含在[all]与 dev 组中。打包细节构建后的 SPA 从src/skill_seekers/web/dist打入 wheel该目录被 gitignore发布流程会在uv build前执行npm run build若前端未构建skill-seekers ui会给出警告。Job 以子进程方式运行python -m skill_seekers.web.runner日志以流式输出并带有[[PROGRESS:nn]]进度标记UI 状态存放在~/.skill-seekers/ui/jobs、projects、activity、skill overrides、settings。API 测试见 tests/test_web_api.py。CLI 命令全集# 核心命令 skill-seekers create source # 从任意源创建 Skill自动检测类型 skill-seekers create source --index # 额外生成 SQLite 搜索索引 scripts/search.py skill-seekers scan dir # AI 检测项目技术栈并输出各框架配置 skill-seekers enhance directory # AI 增强 skill-seekers package directory # 为目标平台打包 skill-seekers upload file # 上传 Skill 到目标平台 skill-seekers install source # 一键工作流抓取 增强 打包 上传 # 工具类命令 skill-seekers estimate source # 抓取前预估页数 skill-seekers detect source [--json] # 只读查看 create 会如何分类无效输入退出码 2 skill-seekers doctor [--json] # 依赖与配置健康检查--json 供 CI/Agent 使用 skill-seekers config # 配置 API Key 与设置 skill-seekers workflows # 列出与应用工作流预设 skill-seekers resume job_id # 恢复被中断的抓取 # 高级命令 skill-seekers stream source # 流式摄取 skill-seekers update directory # 增量更新 skill-seekers multilang directory # 多语言支持从 pyproject.toml 可见这些命令还有独立的 entry point如skill-seekers-create、skill-seekers-enhance-status、skill-seekers-quality、skill-seekers-benchmark、skill-seekers-cloud、skill-seekers-embed等既支持skill-seekers cmd统一入口也支持独立二进制调用。测试指南测试结构单元测试tests/test_*.py覆盖单个模块适配器测试tests/test_adaptors/test_*_adaptor.py覆盖平台适配器E2E 测试tests/test_*_e2e.py端到端集成测试运行测试# 快速运行跳过 slow/integration pytest tests/ -v -m not slow and not integration # 完整套件 pytest tests/ -v # 带覆盖率报告 pytest tests/ --covsrc/skill_seekers --cov-reportterm-missing # 按类别筛选 pytest tests/ -v -m slow # 仅慢速测试 pytest tests/ -v -m integration # 仅集成测试 pytest tests/ -v -m e2e # 仅 E2E 测试测试夹具与隔离机制测试夹具位于 tests/fixtures/含合成样例 PDF/DOCX/EPUB、冲突样例 JSON 与生成脚本。conftest.py 中还提供了两个关键的自动隔离夹具_isolate_user_config会把ConfigManager.CONFIG_FILE重定向到临时目录防止开发者本机~/.config/skill-seekers/config.json中的默认增强级别泄漏进测试_reset_execution_context在每个测试前后重置ExecutionContext单例避免状态污染。Git 工作流与提交前检查main生产分支受保护development默认 PR 目标活跃开发分支功能分支从development创建提交前清单Pre-commit Checklistruff check src/ tests/ ruff format --check src/ tests/ pytest tests/ -v -x # 遇到第一个失败即停止绝不提交 API Key一律使用环境变量ANTHROPIC_API_KEY、GOOGLE_API_KEY、OPENAI_API_KEY、GITHUB_TOKEN.env已在.gitignore中。CI/CD7 个 GitHub Actions 工作流仓库 .github/workflows/ 目录下共有 7 个工作流工作流职责tests.ymlruff mypy lint job随后 pytest 矩阵Ubuntu macOSPython 3.10–3.12并上传 Codecovrelease.yml打 tag 触发测试 → 版本校验 → 通过uv build发布到 PyPItest-vector-dbs.yml测试向量库适配器weaviate、chroma、faiss、qdrantdocker-publish.yml多平台 Docker 构建amd64、arm64产出 CLI 与 MCP 镜像quality-metrics.yml质量分析带可配置阈值scheduled-updates.yml每周为热门框架更新 Skillvector-db-export.yml每周向量库导出部署方式Docker基于 Python 3.12 slim 基础镜像的多阶段 Dockerfile# 构建 CLI 镜像 docker build -t skill-seekers:local -f Dockerfile . # 运行 CLI docker run -v $(pwd)/output:/output skill-seekers:local create https://docs.example.com # 构建并运行 MCP 服务器监听 8765 端口 docker build -t skill-seekers-mcp:local -f Dockerfile.mcp . docker run -p 8765:8765 skill-seekers-mcp:localMCP 服务器# 启动 FastMCP 服务器 skill-seekers-mcp # 或使用 Python 模块方式 python -m skill_seekers.mcp.server_fastmcpserver_fastmcp.py 支持 stdio默认向后兼容与 HTTP 两种传输方式python -m skill_seekers.mcp.server_fastmcp --http [--port 8080]。在 Claude 等客户端中集成时stdio 配置使用{command: python, args: [-m, skill_seekers.mcp.server_fastmcp]}HTTP 配置则指向http://localhost:8000/sse。若未安装mcp包直接运行会给出pip install mcp的安装提示。安全注意事项API Key绝不提交到版本控制使用环境变量或.env文件Docker以非 root 用户运行用户skillseekerUID 1000依赖安全定期通过pip audit或safety check做安全更新沙箱化视频处理的可选依赖可能很重仅在需要时安装[video-full]面向 Agent 的实战建议与总结AGENTS.md 本质上是一份可执行的仓库契约它把安装前置、测试命令、CI 阶段、代码风格、注册点和安全红线都写成机器可验证的条目。对 AI 编码 Agent 而言最有价值的用法是上手任何任务前先执行pip install -e .[dev]否则连测试都无法启动conftest.py 会硬性退出修改后自检遵循 Pre-commit Checklist 三连ruff check → ruff format --check →pytest tests/ -v -x与 CI 第一步保持一致扩展新源码类型时按 Scraper 模式的三件套结构添加文件并同步更新PARSERS、COMMAND_MODULES、VALID_SOURCE_TYPES三处注册点避免出现命令存在但配置校验拒绝的漂移扩展新平台时在 cli/adaptors/ 下实现SkillAdaptor子类并在ADAPTORS注册能力集合supports_enhancement/supports_upload会自动反映到 CLI 选项中。总体来看Skill Seekers 的代码组织以注册表驱动为核心源码类型、平台适配器、CLI 命令、MCP 工具四类扩展点都通过显式的字典或集合集中声明配合严格的测试标记分层unit / serial / network / mcp与三阶段 CI使得这个覆盖 17 种输入、20 输出平台的大型工具库仍然保持了可验证、可扩展、可协作的工程秩序。想要进一步深入可以继续阅读 docs/ARCHITECTURE.md 了解整体设计阅读 docs/CLI_REFERENCE.md 与 docs/CONFIG_FORMAT.md 掌握命令与配置格式细节或直接以 configs/ 下的统一配置为起点跑通一条完整的create → enhance → package → upload流水线。【免费下载链接】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），仅供参考
