企业官网建设流程全解析

Skill_Seekers 三流 GitHub 架构解析：代码、文档与社区洞察的统一分析流水线

【免费下载链接】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 架构"（Three-Stream GitHub Architecture）的完整实现：它将任意 GitHub 仓库拆分为代码（Code）、文档（Documentation）、社区洞察（Insights）三条独立数据流，再经由统一代码库分析器、多源合并器与路由器生成器，产出既包含 C3.x 深度分析、又携带真实用户问题与解决方案的 Claude AI Skill。读完本文，你将掌握三流数据模型的设计动机、各阶段核心类的调用链、质量指标与可复现的 Python 调用方式，并能在自己的技能生成流程中直接复用它。

核心设计思想：C3.x 是分析深度，不是源类型

三流架构的出发点非常明确：GitHub 仓库应被拆成三条互不干扰的独立数据流，每条流服务于不同的技能生成目标，避免把代码、文档和社区数据混在一起导致上下文污染。

架构上最重要的洞察写在了 unified_codebase_analyzer.py 的模块注释里：

• basic模式（1-2 分钟）：文件结构、导入关系、入口点；
• c3x模式（20-60 分钟）：完整 C3.x 套件 + GitHub 洞察。

统一分析器对任意源（GitHub URL 或本地路径）在任意深度下都有效，GitHub 只是"源"的一种，C3.x 只是"深度"的一种，二者解耦后整个流水线变得极其灵活。

Phase 1：GitHub 三流抓取器

核心实现位于 github_fetcher.py，配套测试为 test_github_fetcher.py。

数据类模型

抓取结果用 4 个 dataclass 表达（github_fetcher.py）：

@dataclass class CodeStream: directory: Path files: List[Path] @dataclass class DocsStream: readme: Optional[str] contributing: Optional[str] docs_files: List[Dict] @dataclass class InsightsStream: metadata: Dict # stars, forks, language, description common_problems: List[Dict] # Open issues with 5+ comments known_solutions: List[Dict] # Closed issues with comments top_labels: List[Dict] # Label frequency counts @dataclass class ThreeStreamData: code_stream: CodeStream docs_stream: DocsStream insights_stream: InsightsStream

GitHubThreeStreamFetcher的构造参数（github_fetcher.py）包括repo_url、github_token（默认读GITHUB_TOKEN环境变量）、interactive（False 用于 CI/CD）、profile_name（多 token 配置），以及三个 issue 过滤参数issue_since（ISO8601 日期）、issue_labels、issue_state（open/closed/all，默认all）。

核心特性

• URL 解析：同时支持 HTTPS（https://github.com/owner/repo）与 SSH（git@github.com:owner/repo.git）两种格式（github_fetcher.py）；.git后缀通过精确的endswith(".git")检查移除，而不是盲目的rstrip，避免误删仓库名末尾字符。
• 浅克隆：使用git clone --depth 1保证抓取速度（github_fetcher.py）。
• 文件分类：文档模式覆盖**/README.md、**/CONTRIBUTING.md、docs/*.md、docs/**/*.md、doc/、documentation/、*.rst；代码扩展名覆盖 20 种主流语言（.py/.js/.ts/.tsx/.go/.rs/.java/.kt/.c/.cpp/.rb/.php/.swift/.cs/.scala/.clj等）；同时排除node_modules、__pycache__、venv、.venv、.git、build、dist、.tox等常见目录，隐藏文件默认跳过但允许docs/、doc/、documentation/目录内的隐藏文档（github_fetcher.py）。
• Issue 洞察：issues 端点天然混入 pull request，代码会显式过滤"pull_request" in i的条目；open 且评论 ≥ 5 的 issue归入common_problems，closed 且有评论的 issue归入known_solutions，两类各按评论数降序取前 10，并用Counter统计 label 出现频率生成top_labels前 10（github_fetcher.py）。
• 编码回退：读取文件优先 UTF-8，失败时回退 latin-1，再失败返回None（github_fetcher.py）。
• 分页抓取：per_page上限 100，通过Link: rel="next"头跟进分页，直到凑满max_issues；当配额只够抓一个状态时，会先把配额给 open 状态，再把剩余配额给 closed，避免固定五五开导致配额浪费（github_fetcher.py）。

速率限制保障

GitHub API 未认证时限制为 60 次/小时，携带 token 时为 5000 次/小时。三流抓取器通过 rate_limit_handler.py 做了前置检查（check_upfront()）与逐响应检查（check_response()），支持 profile 自动切换、倒计时提示与 CI 非交互模式。如果未配置 token，会提示运行skill-seekers config --github进行配置（rate_limit_handler.py）。

修复的经典 Bug

1. .rstrip('.git')会把react末尾的t一起删掉 → 改为精确的endswith('.git')检查；
2. SSH 格式git@github.com:无法解析 → 新增对应解析分支；
3. 文件分类漏掉docs/*.md深层文档 → 同时加入docs/*.md与docs/**/*.md两个模式。

Phase 2：统一代码库分析器

核心实现位于 unified_codebase_analyzer.py，配套测试为 test_unified_analyzer.py。

AnalysisResult统一承载所有分析结果（unified_codebase_analyzer.py）：code_analysis（dict）、github_docs（可选）、github_insights（可选）、source_type（local或github）、analysis_depth（basic或c3x）。

analyze()入口（unified_codebase_analyzer.py）通过"github.com" in source自动判别源类型：GitHub URL 走三流抓取器_analyze_github，本地路径走_analyze_local（校验目录存在性与类型，否则抛FileNotFoundError/NotADirectoryError）。

basic 深度（1-2 分钟）

• 文件清单（路径、大小、扩展名）；
• 目录结构树（跳过隐藏项，仅列一级子目录）；
• 导入关系抽取（Python 的import/from、JS/TS 的import/require，每种扩展名最多采样 10 个文件、每个文件前 50 行）；
• 入口点探测（main.py、index.js、setup.py、pyproject.toml、package.json、Dockerfile、docker-compose.yml等 14 种模式）；
• 统计信息（文件总数、总字节数、扩展名分布、语言分布）。

c3x 深度（20-60 分钟）

c3x_analysis()的关键增强在于：不再是占位符，而是真正调用底层 C3.x 组件。它调用 codebase_scraper.py 的analyze_codebase()，传入depth="deep"、build_api_reference=True、build_dependency_graph=True、detect_patterns=True、extract_test_examples=True、build_how_to_guides=True、extract_config_patterns=True，并通过enhance_level=0关闭 AI 以提升速度，分析结果写入临时目录后由_load_c3x_results()读取（unified_codebase_analyzer.py）。

C3.x 结果与输出文件的映射关系：

此外还有两个防御性设计：分析失败时回退到带空占位符的analysis_type="c3x_failed"结果（与"真成功但结果为空"区分开），并在finally中清理临时分析目录，避免每次运行泄漏临时文件（unified_codebase_analyzer.py）。

Phase 3：多源合并与冲突检测

核心实现位于 merge_sources.py，配套测试为 test_merge_sources_github.py。

四层合并算法

1. Layer 1：C3.x 代码分析（ground truth，代码是实际运行的）；
2. Layer 2：HTML 文档（官方意图）；
3. Layer 3：GitHub 文档（README、CONTRIBUTING）；
4. Layer 4：GitHub 洞察（issues、metadata、labels）。

新增的三个函数

• categorize_issues_by_topic(problems, solutions, topics)：把 open/closed issue 按主题关键词做文本匹配（标题 + labels 拼接后统计关键词命中数），归入最优主题，未命中的落入other，空分类会被移除（merge_sources.py）；
• generate_hybrid_content(api_data, github_docs, github_insights, conflicts)：把 GitHub 文档、元数据（stars/forks/language/description）、Top 5 问题与解决方案、Top labels 以及冲突摘要（按类型与严重度统计）织入最终输出，产出github_context、conflict_summary与issue_links（merge_sources.py）；
• _match_issues_to_apis(apis, problems, solutions)：把 API 名拆成关键词（下划线转空格、按点分段），与 issue 标题/标签做子串匹配，建立"API → 相关 issue"的链接关系（merge_sources.py）。

RuleBasedMerger 的四条确定性规则

RuleBasedMerger接受可选的github_streams参数后，会把 docs/insights 两层提取出来。单 API 的合并遵循 4 条规则（merge_sources.py）：

1. 仅在文档中出现 → 标记docs_only，附警告 "documented but not found in codebase"；
2. 仅在代码中出现 → 标记code_only，私有 API（以下划线开头）提示 "Internal/private API"，否则警告 "exists in code but is not documented"；
3. 两者一致 → 标记matched，合并签名与描述；
4. 存在冲突 → 标记conflict，签名优先采用代码版本（prefer_code_signature），描述保留文档版本，并用⚠️警告展示差异。

AIEnhancedMerger则在此基础上把冲突数据、文档 API、代码 API 写入临时工作区，通过AgentClient驱动本地 AI Agent 按MERGE_INSTRUCTIONS.md的规则进行智能调和（代码签名为准、文档描述保留、差异加实现注记），失败时自动回退到规则合并（merge_sources.py）。CLI 入口merge_sources支持rule-based/claude-enhanced/ai-enhanced三种模式，其中ai-enhanced被作为claude-enhanced的同义词兼容处理（merge_sources.py）。

Phase 4：带 GitHub 洞察的路由器生成

核心实现位于 generate_router.py，配套测试为 test_generate_router_github.py。

RouterGenerator接收子技能 config 列表与可选的github_streams，从 insights 流中提取github_metadata、github_issues，从 docs 流中提取github_docs。

路由关键词的 2 倍加权

这是提升路由准确性的关键技巧：GitHub issue label 被重复追加两次实现 2x 权重（generate_router.py）：

# Phase 4: Add GitHub issue labels (weight 2x by including twice) for label_info in top_labels[:10]: label = label_info['label'].lower() if any(keyword.lower() in label or label in keyword.lower() for keyword in skill_keywords): keywords.append(label) # First inclusion keywords.append(label) # Second inclusion (2x weight)

此外，_extract_skill_specific_labels()会扫描与技能关键词匹配的 issue，提取它们携带的全部非通用 label（排除 bug/enhancement/question 等 7 个通用标签），同样以 2x 权重加入路由关键词（generate_router.py）。

增强后的 Router 模板

生成的SKILL.md在保留原结构（frontmatter、When to Use、How It Works、Routing Logic、Quick Reference、All Available Skills）的基础上新增：

• Repository Info：仓库 URL、stars、语言、描述（使用 GitHub API 返回的html_url而非 config 里的base_url）；
• Quick Start：从 README 提取首个有效章节（1500 字符软上限，会为完整代码块扩展；不足 50 字符时重试 2000 字符），README 缺失或过短时回退到框架级 Hello World 模板（fastapi/fastmcp/django/react）；
• Common Issues：Top 5 GitHub 社区问题（标题 + Issue 编号 + 评论数）；
• Common Patterns：从 closed issue 标题解析出的"问题 → 解决方案"模式（Fixed X→ "X not working" /Resolved X→ "X issue" /Added X→ "Missing X"）；
• Examples：优先把真实 issue 标题转成自然提问（_convert_issue_to_question，如 "OAuth fails on redirect" → "How do I fix oauth redirect failures?"），并保证同一 issue 不被重复使用；
• references/ 渐进披露：额外生成github_issues.md（完整 issue 清单与链接）和getting_started.md（README 精炼版），保持主文档精简。

frontmatter 兼容 agentskills.io 规范（name、description、license、compatibility），且会根据 GitHub 元数据中的语言自动生成兼容性说明（如 Python → "Python 3.10+，requires {router} package"）并从 license 字段提取许可证名称（generate_router.py）。

Phase 5：端到端质量验证

E2E 测试位于 test_e2e_three_stream_pipeline.py，共 8 个测试，覆盖 5 大类：

1. E2E 基础工作流（2 个）：GitHub URL → basic 分析 → 合并输出；issue 按主题归类（验证 oauth/auth/authentication 主题下 issue 的正确归类）；
2. E2E 路由器生成（1 个）：完整工作流，验证 metadata、docs、issues、路由关键词（含 2x 加权断言：oauth_keywords.count("oauth") >= 2）；
3. E2E 质量指标（2 个）：GitHub 开销控制在 20-60 行/技能；4 个子技能的路由器控制在 60-250 行；
4. E2E 向后兼容（2 个）：无 GitHub 流时路由器仍生成有效 SKILL.md 且不含⭐/Repository Info等 GitHub 专属章节；fetch_github_metadata=False时分析结果不含 GitHub 数据；
5. E2E token 效率（1 个）：三流输出紧凑、无跨流污染（README 内容不出现在 code 流中）。

实施完成时的质量指标（引自原实现总结）：

原文档记录的 81 个测试分布在五个阶段（Phase 1: 24、Phase 2: 24、Phase 3: 15、Phase 4: 10、Phase 5: 8）；从当前仓库源码看，这些测试文件仍在持续演进，例如 test_github_fetcher.py 中定义的测试函数已增长到 30 余个，test_merge_sources_github.py 中定义的测试函数也扩展到 17 个。

复现测试的命令：

python -m pytest tests/test_github_fetcher.py \ tests/test_unified_analyzer.py \ tests/test_merge_sources_github.py \ tests/test_generate_router_github.py \ tests/test_e2e_three_stream_pipeline.py -v

完整使用示例

以下四个示例直接来自实现总结，可在本地环境中运行验证。

示例 1：GitHub 仓库 basic 深度分析

from skill_seekers.cli.unified_codebase_analyzer import UnifiedCodebaseAnalyzer # Analyze GitHub repo with basic depth analyzer = UnifiedCodebaseAnalyzer() result = analyzer.analyze( source="https://github.com/facebook/react", depth="basic", fetch_github_metadata=True ) # Access three streams print(f"Files: {len(result.code_analysis['files'])}") print(f"README: {result.github_docs['readme'][:100]}") print(f"Stars: {result.github_insights['metadata']['stars']}") print(f"Top issues: {len(result.github_insights['common_problems'])}")

示例 2：C3.x 深度分析

# Deep C3.x analysis (20-60 minutes) result = analyzer.analyze( source="https://github.com/jlowin/fastmcp", depth="c3x", fetch_github_metadata=True ) # Access C3.x components print(f"Design patterns: {len(result.code_analysis['c3_1_patterns'])}") print(f"Test examples: {result.code_analysis['c3_2_examples_count']}") print(f"How-to guides: {len(result.code_analysis['c3_3_guides'])}") print(f"Config patterns: {len(result.code_analysis['c3_4_configs'])}") print(f"Architecture: {len(result.code_analysis['c3_7_architecture'])}")

示例 3：带 GitHub 的路由器生成

from skill_seekers.cli.generate_router import RouterGenerator from skill_seekers.cli.github_fetcher import GitHubThreeStreamFetcher # Fetch GitHub repo fetcher = GitHubThreeStreamFetcher("https://github.com/jlowin/fastmcp") three_streams = fetcher.fetch() # Generate router with GitHub integration generator = RouterGenerator( ['configs/fastmcp-oauth.json', 'configs/fastmcp-async.json'], github_streams=three_streams ) # Generate enhanced SKILL.md skill_md = generator.generate_skill_md() # Result includes: repository stats, README quick start, common issues # Generate router config config = generator.create_router_config() # Result includes: routing keywords with 2x weight for GitHub labels

create_router_config()产出的路由配置包含_router: True标记、_sub_skills列表与_routing_keywords映射，max_pages固定为 500（路由器只抓取概览页），避免递归抓取（generate_router.py）。

示例 4：本地路径分析（同一结构）

# Works with local paths too! result = analyzer.analyze( source="/path/to/local/repo", depth="c3x", fetch_github_metadata=False # No GitHub streams ) # Same unified result structure print(f"Analysis type: {result.code_analysis['analysis_type']}") print(f"Source type: {result.source_type}") # 'local'

Phase 6 待办与后续演进方向

实施总结发布时 Phase 6（文档与示例）仍处于待办状态，剩余约 2 小时工作量：

• 更新 CLI help 文本中的三流信息、README 中的 GitHub 示例、CLAUDE.md 中的三流架构说明；
• 创建 FastMCP + GitHub（完整工作流）与 React + GitHub（多源）示例，并加入官方 configs 目录。

文档同时列出了五个未来增强方向：缓存 GitHub API 响应以减少 API 调用、扩展支持 GitLab/Bitbucket URL、增加 issue 搜索能力、实现 issue 趋势分析（发现热门话题）、支持多子项目的 monorepo。

总结

三流 GitHub 架构是 Skill_Seekers 将"外部 GitHub 仓库"转化为高质量技能的关键基建。它用三条解耦的数据流（代码 / 文档 / 洞察）配合两档分析深度（basic / c3x），在保持向后兼容的同时实现了：81/81 测试全部通过的确定性质量保障、每技能仅 20-60 行的极低 GitHub 开销、以及基于真实社区 issue 的 2x 加权路由关键词。其完整调用链——github_fetcher.py → unified_codebase_analyzer.py → merge_sources.py → generate_router.py，以及对应的 E2E 测试 均可直接查阅，作为自行扩展 GitLab/Bitbucket 源或多源合并逻辑的参考蓝本。

【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址: https://gitcode.com/gh_mirrors/sk/Skill_Seekers