企业官网建设流程全解析

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_Seekers

Skill 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 设计思路：

一个值得注意的工程细节：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 --dist=loadfile -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/ --cov=src/skill_seekers --cov-report=term # 代码质量检查（与 CI 对齐） ruff check src/ tests/ ruff format --check src/ tests/ # 类型检查（非阻塞——CI 中 mypy 为 continue-on-error） mypy src/skill_seekers --show-error-codes --pretty

Pytest 配置要点（来自 pyproject.toml）：asyncio_mode = "auto"，因此@pytest.mark.asyncio是隐式的；测试标记包括slow、integration、e2e、venv、bootstrap、benchmark、asyncio、serial、network、mcp_only。其中serial用于必须独跑的测试（共享 HTTP 服务器、单例变更），network用于真正发起 HTTP 调用或需要 Docker 服务的测试。

CI 注意点：CI 锁定ruff==0.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 字符
• 目标 Python：3.10+
• 启用的 lint 规则：E、W、F、I、B、C4、UP、ARG、SIM
• 忽略的规则：E501（行长交给 formatter）、F541（f-string 风格）、ARG002（接口兼容所需的未使用方法参数）、B007（有意的未使用循环变量）、I001（导入排序交给 formatter）、SIM114（可读性优先）

导入与依赖守卫

导入按"标准库 → 第三方 → 第一方"分组排序（经 ruff/isort），skill_seekers被视为 first-party。只有在需要前向引用时才使用from __future__ import annotations。

可选依赖必须用 try/except ImportError 守卫，模式见 adaptors/init.py：

try: 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，测试目录放宽为两项均为 false

Docstring、错误处理与 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：包含<Type>ToSkillConverter类与main()函数
• cli/arguments/<type>.py：CLI 参数定义
• 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_CLASSES（create/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 UI（Seeker HUD）

Seeker 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/ --cov=src/skill_seekers --cov-report=term-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 Checklist）：

ruff 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/CD：7 个 GitHub Actions 工作流

仓库 .github/workflows/ 目录下共有 7 个工作流：

部署方式

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:local

MCP 服务器

# 启动 FastMCP 服务器 skill-seekers-mcp # 或使用 Python 模块方式 python -m skill_seekers.mcp.server_fastmcp

server_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 用户运行（用户skillseeker，UID 1000）
• 依赖安全：定期通过pip audit或safety check做安全更新
• 沙箱化：视频处理的可选依赖可能很重，仅在需要时安装[video-full]

面向 Agent 的实战建议与总结

AGENTS.md 本质上是一份"可执行的仓库契约"：它把安装前置、测试命令、CI 阶段、代码风格、注册点和安全红线都写成机器可验证的条目。对 AI 编码 Agent 而言，最有价值的用法是：

1. 上手任何任务前先执行pip install -e ".[dev]"，否则连测试都无法启动（conftest.py 会硬性退出）；
2. 修改后自检遵循 Pre-commit Checklist 三连（ruff check → ruff format --check →pytest tests/ -v -x），与 CI 第一步保持一致；
3. 扩展新源码类型时，按 Scraper 模式的三件套结构添加文件，并同步更新PARSERS、COMMAND_MODULES、VALID_SOURCE_TYPES三处注册点，避免出现"命令存在但配置校验拒绝"的漂移；
4. 扩展新平台时，在 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