repo-explainer#

Mission#

Turn a GitHub repo URL into a self-contained HTML report that a non-developer (PM, designer, manager) can read and walk away understanding:

1. What the project does (in plain language)
2. Who it is for and what problem it solves
3. How it is built (tech stack + architecture)
4. What the key modules are and how they interact
5. What the main user flow looks like
6. What external dependencies it relies on

Hard rule: every claim must be grounded in actual source code, not just the README. Cite path:line for each non-trivial conclusion.

Inputs#

The skill accepts either of two source forms:

1. GitHub URL — https://github.com/<owner>/<repo> (with optional /tree/<branch> suffix). The repo is shallow-cloned into ./workspace/<owner>__<repo>/.
2. Local directory path — absolute, relative, or ~-prefixed. Analyzed in-place; nothing is cloned or copied. If the directory is a git checkout whose origin (or first available remote) points at github.com, the owner / repo / branch / commit SHA are auto-recovered so path:line evidence still renders as clickable permalinks. If not, evidence renders as monospace text and the report still works.

Optional:

• --subpath — focus on a sub-directory (for monorepos), e.g. packages/core. Applies to both modes.
• Audience hint — pm | designer | engineer (default pm).

If the user gives a non-GitHub URL (and not a local path), refuse politely and point at the scope limitation.

Workflow#

Execute the following 6 stages in order. Each stage has a dedicated script under scripts/. Do NOT skip stages.

Stage 1 — Fetch#

bash

# Remote mode — shallow-clone a public GitHub repo
python3 scripts/fetch_repo.py <github_url> [--subpath <path>]

# Local mode — analyze a directory in-place (auto-detected when the
# argument is an existing path; force with --local for ambiguous cases)
python3 scripts/fetch_repo.py <local_dir> [--subpath <path>] [--local]

The script auto-detects the mode:

• Argument starts with http:// / https:// and contains github.com → remote mode (clone)
• Argument is an existing local directory → local mode (in-place)
• Otherwise → fall back to URL parser (which will refuse non-GitHub URLs)

Remote mode behavior:

• Shallow-clone ( --depth=1) to ./workspace/<owner>__<repo>/
• Hard cap repo size at 500 MB; if exceeded, abort and ask the user to pick a sub-path
• Capture default branch, latest commit SHA, repo description, star count, primary language (via GitHub REST API, no auth needed for public repos but works with GH_TOKEN if set)

Local mode behavior:

• Resolve the path (absolute / relative / ~-prefixed); reject if not a directory
• Apply the same 500 MB size cap (excluding .git, node_modules, venv, __pycache__, dist, build, target)
• Try git -C <path> for: HEAD SHA, current branch, origin remote. If the remote URL matches github.com/<owner>/<repo>(.git)?, owner / repo / branch / commit_sha are populated so downstream path:line evidence becomes clickable permalinks identical to remote mode.
• If the directory is not a git repo, all four GitHub coordinates are left null — the renderers degrade evidence to monospace text and the hero shows a 📁 <local-path> badge instead of a repo link.

The output meta.json schema is identical across both modes; only the mode field ( "remote" / "local") and the optional null-ness of owner / repo / branch / commit_sha distinguish them.

Stage 2 — Scan#

bash

python3 scripts/scan_structure.py ./workspace/<owner>__<repo>/

Produces scan.json containing:

• Directory tree (depth ≤ 4, files counted per dir)
• Language breakdown (lines of code per language, via simple extension map)
• Manifest files detected ( package.json, pyproject.toml, go.mod, pom.xml, Cargo.toml, Gemfile, composer.json, requirements.txt, Dockerfile, docker-compose.yml, CI YAMLs)
• Parsed dependencies from each manifest
• Entry-point candidates ( main.*, index.*, app.*, cmd/, bin/, cli.*, plus framework-specific routes like routes/, pages/, controllers/)
• README excerpts (first 300 lines)

Stage 3 — Analyze#

bash

python3 scripts/analyze_modules.py ./workspace/<owner>__<repo>/ scan.json

Produces analysis.json containing:

• Top-N modules: ranked by (a) inbound import count, (b) LOC, (c) presence in entry-point graph
• For each top module: file paths, exported symbols (best-effort regex per language), one-line "what it does" guess from docstring/comment
• API surface: HTTP routes, CLI commands, exported public functions
• Data models: classes/structs that look like entities (heuristic: fields-only, named like nouns)
• External calls: detected SDK usage (e.g. boto3, openai, redis, kafka, axios, fetch) with path:line evidence

Stage 4 — Synthesize#

bash

python3 scripts/synthesize_summary.py analysis.json scan.json > summary.json

Calls the LLM (via Mira's built-in capability — the orchestrating agent performs this step in-context, the script just prepares a structured prompt payload). The agent must produce JSON conforming to templates/summary.schema.json:

json

{
  "project_name": "...",
  "one_liner": "≤30 字白话定位",
  "who_for": "目标用户群体",
  "problem_solved": "...",
  "core_value": "...",
  "tech_stack": [{"layer": "前端|后端|数据|基础设施", "items": ["..."]}],
  "key_models": [{"name": "PolicyAST", "path": "src/core/types", "purpose": "...", "key_fields": "id, rules[], snapshot_id", "evidence": "path:line"}],
  "key_modules": [{"name": "...", "path": "...", "responsibility": "...", "principle": "实现原理一句话", "subflow": ["步骤1","步骤2"], "evidence_list": ["path:line", "path:line"]}],
  "limitations": [{"title": "...", "detail": "...", "category": "performance|security|scalability|usability|compatibility|documentation|test_coverage|architecture|other", "severity": "low|medium|high", "evidence": "path:line 或 issue 链接,可空"}],
  "main_flow": [{"step": 1, "actor": "用户|系统", "action": "...", "evidence": "path:line"}],
  "api_surface": [{"type": "HTTP|CLI|SDK", "signature": "...", "purpose": "...", "evidence": "path:line"}],
  "dependencies": [{"name": "...", "purpose": "...", "criticality": "核心|辅助"}],
  "highlights": ["特色 1", "特色 2", "..."],
  "architecture_mermaid": "graph TD\n  ...",
  "sequence_mermaid": "sequenceDiagram\n  ...",
  "glossary": [{"term": "...", "plain": "白话解释"}]
}

Rules for the agent during synthesis:

• Every evidence field MUST be a real path:line from the scanned repo

• Mermaid node labels MUST use business language ("登录请求"), NOT class names ("AuthController")

• Mermaid safety (HARD RULE — violating this breaks rendering on Feishu / GitHub / Notion / Mermaid Live). Both architecture_mermaid and sequence_mermaid MUST follow:

  • No HTML-confusable chars in node labels or sequence message text: forbid < > " ' (use full-width 「」 or remove); replace path/file.ts style with path file.ts or file 文件.
  • No code-fence-confusable chars: forbid backticks ``, pipes |` inside labels (Markdown table parser eats them).
  • No rect rgb(...) colour blocks inside sequenceDiagram — Feishu / Notion Mermaid renderers commonly fail on them. Use Note over X,Y: 阶段 N 描述 to mark phases instead.
  • Quote labels with non-ASCII: in graph TD, wrap labels containing Chinese / spaces in double quotes — A["登录请求"], not A[登录请求]. In sequenceDiagram, use participant ALIAS as 显示名 (NO quotes).
  • Replace these symbols inside labels / messages: < > → 全角 〈 〉 or remove; & → 加; em-dash — → space; slash / inside message text → space (slash in participant alias is fine).
  • One statement per line, no inline ;. Indent body by 2-4 spaces.
  • Self-check before emitting: paste your mermaid into https://mermaid.live mentally — if any line contains the forbidden chars above, rewrite it.

• glossary MUST contain every technical term that appears in one_liner / core_value / highlights

• key_models: extract core domain/data structs/classes/protobuf/schemas (e.g. Alert, PolicyAST, Snapshot, User). These are the nouns the project moves around. Render BEFORE key_modules so readers learn the "what" before the "how". Keep 5-12 entries.

• key_modules: keep principle (核心原理 1-2 句) and subflow (3-6 步关键流程) for each module — readers should leave understanding not just what each module does but HOW it works.

• limitations: MUST include 4-8 entries. Sources allowed: (a) TODO/FIXME/XXX/HACK comments grep'd from source, (b) open issues / known issues in README, (c) obvious architectural gaps (e.g. no rate limiting on public API, single-node only, no auth on /metrics, hardcoded secrets in tests, missing test coverage, deprecated dependency). Be honest and specific — generic items like "需要更多测试" are forbidden. If evidence cannot be cited, leave evidence empty rather than fake.

• If a field cannot be confidently filled, leave empty string — never fabricate

Stage 5 — Render (BOTH formats, in parallel)#

The pipeline MUST produce both an HTML report and a Markdown report from the same summary.json — never just one. Markdown is for embedding in Feishu / Notion / GitHub READMEs / chat; HTML is for sharing / printing / standalone viewing.

bash

# 5a · HTML (themed, single-file, interactive)
python3 scripts/render_html.py summary.json \
    --meta_json meta.json \
    --file_count "$(jq '.structure.total_files' scan.json)" \
    --theme midnight \
    > report.html

# 5b · Markdown (Mermaid-native, GitHub/Feishu-friendly)
python3 scripts/render_markdown.py summary.json \
    --meta_json meta.json \
    --file_count "$(jq '.structure.total_files' scan.json)" \
    > report.md

Both renderers share the same section order and the same evidence-link contract:

• Sections (identical in both formats): Hero (one_liner + project_name + repo link) → TL;DR (who_for / problem / value) → Tech Stack table → Architecture diagram (Mermaid) → Key Models table → Key Modules detail cards → Main Flow (sequence diagram) → API Surface table → Dependencies table → Highlights → Limitations / 待优化点 → Glossary
• Every evidence: path:line rendered as a clickable link to https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<line>
• HTML extras: 3 themes (midnight / light / terminal), @media print rules, drop-shadow + auto-classified subgraph colors + legend, localStorage theme persistence
• Markdown extras: ```mermaid fenced blocks (rendered natively by GitHub / GitLab / Obsidian / Typora / Bear / VS Code preview), shields.io badges in the hero, severity emoji (🔴 high / 🟠 medium / 🟢 low) in the limitations section

Stage 6 — Deliver#

• Upload both report.html AND report.md via mcp__runtime__upload_file — never just one
• Return to user: ① uploaded HTML URL ② uploaded Markdown URL ③ brief 3-line summary (project name, one-liner, top-3 highlights) ④ note that they can click any path:line link to verify, and that the Markdown version can be pasted directly into Feishu / Notion / GitHub issues

Failure Modes#

SymptomAction404 from GitHub APITell user repo is private/non-existent; stopClone >500 MBAsk user to pick a sub-path; offer top-3 sub-dirs by sizeZero recognized manifests AND zero code filesReport "not a code repo" and stopLLM synthesis returns invalid JSONRetry once with schema reminder; if still fails, fall back to a degraded report (skip the broken section, mark it [未能可靠生成])Mermaid render error in HTMLThe HTML uses Mermaid 10+; on parse error the diagram block shows the raw text instead — DO NOT block the rest of the report. The Markdown report is unaffected since GitHub/Feishu render Mermaid independently.Markdown render errorThe Markdown renderer is pure Python with no runtime deps and emits raw fenced ```mermaid blocks — only fails on invalid summary.json. If render_markdown.py fails, still deliver the HTML; report markdown error to the user.

Non-Goals (explicit)#

• Not a security auditor
• Not a code review tool
• Not a runner/installer
• Not a comparison-with-other-projects tool (use competitive-analysis)
• Not a deep call-graph tracer (out of MVP scope)

Examples#

Trigger — GitHub URL:

帮我解读一下 https://github.com/tiangolo/fastapi 这个项目

Trigger — local directory:

帮我分析下 ~/code/my-side-project 这个目录在做什么

explain this folder /Users/me/work/checkout-service

Not a trigger (private/internal GitLab, out of scope):

帮我分析下 https://code.byted.org/some/private/repo

Not a trigger (only wants to run, not understand):

这个 github 项目怎么跑起来