codeabc 0.1.0__py3-none-any.whl

backend/services/action_plan.py

@@ -0,0 +1,366 @@
+"""Priority action plan — turn the analyses into an ordered "what do I fix first?" list.
+
+The health score tells a non-programmer *how* a codebase is doing and *which
+dimensions* drag it down. The obvious next question is "OK, so what do I actually
+do?" — and a category score doesn't answer that. This module does.
+
+It reads the same analysis results (security findings, untested core files,
+complexity, import cycles, tech debt) and emits a single ranked list of concrete
+actions, each pinned to a real file where possible and written in plain language:
+what's wrong, why it matters, and roughly how big the fix is.
+
+Ranking favours impact-over-effort: a hardcoded secret outranks a long function,
+and an untested file that ten others depend on outranks one nothing imports.
+
+Pure function over already-computed analysis dicts — no repo access required.
+"""
+
+from __future__ import annotations
+
+# Severity weights drive the ordering: higher sorts first.
+_PRIORITY_RANK = {"high": 0, "medium": 1, "low": 2}
+
+# Caps so the plan stays a short, actionable list rather than a dump.
+_MAX_ITEMS = 12
+_MAX_PER_CATEGORY = 4
+
+
+def _security_actions(security: dict | None) -> list[dict]:
+    if not security or not security.get("findings"):
+        return []
+    actions: list[dict] = []
+    # Critical findings (secrets / dangerous calls) first, then the rest.
+    findings = sorted(
+        security["findings"],
+        key=lambda f: 0 if f.get("category") in ("hardcoded_secret", "dangerous_call") else 1,
+    )
+    for f in findings[:_MAX_PER_CATEGORY]:
+        critical = f.get("category") in ("hardcoded_secret", "dangerous_call")
+        actions.append(
+            {
+                "priority": "high" if critical else "medium",
+                "category": "security",
+                "title": f"处理安全隐患：{f.get('file', '?')}:{f.get('line', '?')}",
+                "target": f.get("file", ""),
+                "detail": f.get("reason", "存在潜在安全问题，建议人工核查。"),
+                "effort": "small",
+            }
+        )
+    return actions
+
+
+def _coverage_actions(test_coverage: dict | None) -> list[dict]:
+    if not test_coverage:
+        return []
+    actions: list[dict] = []
+    # Untested core files are already ranked by fan-in upstream.
+    for f in (test_coverage.get("untested_core") or [])[:_MAX_PER_CATEGORY]:
+        fan_in = f.get("fan_in", 0)
+        actions.append(
+            {
+                "priority": "high" if fan_in >= 5 else "medium",
+                "category": "test_coverage",
+                "title": f"给核心文件补测试：{f.get('path', '?')}",
+                "target": f.get("path", ""),
+                "detail": f.get(
+                    "reason",
+                    f"这个文件没有测试，却有 {fan_in} 个文件依赖它，改动缺少自动验证。",
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _complexity_actions(complexity_files: list[dict] | None) -> list[dict]:
+    if not complexity_files:
+        return []
+    actions: list[dict] = []
+    # Only flag genuinely gnarly files (cyclomatic complexity > 20).
+    gnarly = sorted(
+        (f for f in complexity_files if f.get("complexity", 0) > 20),
+        key=lambda f: f.get("complexity", 0),
+        reverse=True,
+    )
+    for f in gnarly[:_MAX_PER_CATEGORY]:
+        cx = f.get("complexity", 0)
+        actions.append(
+            {
+                "priority": "medium" if cx > 40 else "low",
+                "category": "complexity",
+                "title": f"拆分复杂逻辑：{f.get('path', '?')}",
+                "target": f.get("path", ""),
+                "detail": (
+                    f"圈复杂度约 {cx}，分支太多、读起来和改起来都费劲，建议拆成更小的函数。"
+                ),
+                "effort": "large",
+            }
+        )
+    return actions
+
+
+def _deep_nesting_actions(deep_nesting_files: list[dict] | None) -> list[dict]:
+    if not deep_nesting_files:
+        return []
+    actions: list[dict] = []
+    # Deepest first; the analyzer already filtered to the flagged threshold.
+    deepest = sorted(deep_nesting_files, key=lambda f: f.get("depth", 0), reverse=True)
+    for f in deepest[:_MAX_PER_CATEGORY]:
+        depth = f.get("depth", 0)
+        func = f.get("function", "?")
+        actions.append(
+            {
+                "priority": "medium" if depth >= 6 else "low",
+                "category": "deep_nesting",
+                "title": f"拍平深层嵌套：{f.get('path', '?')} 的 {func}",
+                "target": f.get("path", ""),
+                "detail": (
+                    f"函数 {func} 的控制流嵌套了 {depth} 层，读的时候要同时记住每一层的条件，"
+                    "很容易看晕。建议用提前 return / 卫语句 / 把里层抽成一个小函数来拍平。"
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _long_functions_actions(long_functions_files: list[dict] | None) -> list[dict]:
+    if not long_functions_files:
+        return []
+    actions: list[dict] = []
+    # Longest first; the analyzer already filtered to the flagged threshold.
+    longest = sorted(long_functions_files, key=lambda f: f.get("length", 0), reverse=True)
+    for f in longest[:_MAX_PER_CATEGORY]:
+        length = f.get("length", 0)
+        func = f.get("function", "?")
+        actions.append(
+            {
+                "priority": "medium" if length >= 120 else "low",
+                "category": "long_function",
+                "title": f"拆分过长的函数：{f.get('path', '?')} 的 {func}",
+                "target": f.get("path", ""),
+                "detail": (
+                    f"函数 {func} 有 {length} 行，一口气读完很吃力、中间没有自然的停顿点。"
+                    "建议按职责拆成几个各做一件事、名字取好的小函数。"
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _duplicate_code_actions(duplicate_code_clusters: list[list[dict]] | None) -> list[dict]:
+    if not duplicate_code_clusters:
+        return []
+    actions: list[dict] = []
+    # Largest clusters first; the analyzer already filtered to real duplicates.
+    biggest = sorted(duplicate_code_clusters, key=len, reverse=True)
+    for cluster in biggest[:_MAX_PER_CATEGORY]:
+        spots = "、".join(f"{o.get('path', '?')}:{o.get('line', '?')}" for o in cluster)
+        actions.append(
+            {
+                "priority": "medium" if len(cluster) >= 3 else "low",
+                "category": "duplicate_code",
+                "title": f"抽取重复代码：{cluster[0].get('path', '?')} 等 {len(cluster)} 处",
+                "target": cluster[0].get("path", ""),
+                "detail": (
+                    f"同一段代码出现在 {len(cluster)} 个地方（{spots}）。"
+                    "改一处时其余几处不会跟着变，建议抽成公共函数，以后只改一处。"
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _too_many_params_actions(too_many_params_files: list[dict] | None) -> list[dict]:
+    if not too_many_params_files:
+        return []
+    actions: list[dict] = []
+    # Widest first; the analyzer already filtered to the flagged threshold.
+    widest = sorted(too_many_params_files, key=lambda f: f.get("params", 0), reverse=True)
+    for f in widest[:_MAX_PER_CATEGORY]:
+        params = f.get("params", 0)
+        func = f.get("function", "?")
+        actions.append(
+            {
+                "priority": "medium" if params >= 8 else "low",
+                "category": "too_many_params",
+                "title": f"减少参数个数：{f.get('path', '?')} 的 {func}",
+                "target": f.get("path", ""),
+                "detail": (
+                    f"函数 {func} 有 {params} 个参数，调用时要记住每个位置传什么、很容易传错。"
+                    "建议把关系紧密的参数打包成一个对象（或 dataclass），或拆成更小的函数。"
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _typing_actions(typing_files: list[dict] | None) -> list[dict]:
+    if not typing_files:
+        return []
+    actions: list[dict] = []
+    # Files with the most unannotated public symbols and low coverage first;
+    # only surface genuinely under-annotated files (not a stray missing hint).
+    weak = sorted(
+        (f for f in typing_files if f.get("missing", 0) >= 3 and f.get("coverage", 1) < 0.6),
+        key=lambda f: (-f.get("missing", 0), f.get("coverage", 1)),
+    )
+    for f in weak[:_MAX_PER_CATEGORY]:
+        missing = f.get("missing", 0)
+        pct = round(f.get("coverage", 0) * 100)
+        actions.append(
+            {
+                "priority": "low",
+                "category": "typing",
+                "title": f"补类型注解：{f.get('path', '?')}",
+                "target": f.get("path", ""),
+                "detail": (
+                    f"这个文件里有 {missing} 个对外函数没写类型注解（类型覆盖率约 {pct}%），"
+                    "补上参数和返回值的类型能让编辑器提示更准、也更容易发现用错类型的调用。"
+                ),
+                "effort": "small",
+            }
+        )
+    return actions
+
+
+def _architecture_actions(import_cycles: list[dict] | None) -> list[dict]:
+    if not import_cycles:
+        return []
+    actions: list[dict] = []
+    for c in import_cycles[:_MAX_PER_CATEGORY]:
+        files = c.get("files", [])
+        preview = "、".join(files[:3]) + ("…" if len(files) > 3 else "")
+        actions.append(
+            {
+                "priority": "medium",
+                "category": "architecture",
+                "title": f"打破循环依赖（{len(files)} 个文件）",
+                "target": files[0] if files else "",
+                "detail": (
+                    f"这些文件互相 import 形成环：{preview}。循环依赖会让模块难以单独理解和测试。"
+                ),
+                "effort": "medium",
+            }
+        )
+    return actions
+
+
+def _tech_debt_actions(tech_debt_files: list[dict] | None) -> list[dict]:
+    if not tech_debt_files:
+        return []
+    # Only surface the single worst offender — tech debt is low priority next to
+    # security and missing tests, and we don't want to crowd the list.
+    worst = max(tech_debt_files, key=lambda f: f.get("count", 0), default=None)
+    if not worst or worst.get("count", 0) < 3:
+        return []
+    return [
+        {
+            "priority": "low",
+            "category": "tech_debt",
+            "title": f"清理技术债标记：{worst.get('path', '?')}",
+            "target": worst.get("path", ""),
+            "detail": (
+                f"这个文件有 {worst.get('count', 0)} 处 TODO/FIXME/HACK 标记，"
+                "择期清理能降低后续维护成本。"
+            ),
+            "effort": "small",
+        }
+    ]
+
+
+def build_action_plan(
+    *,
+    security: dict | None = None,
+    test_coverage: dict | None = None,
+    complexity_files: list[dict] | None = None,
+    tech_debt_files: list[dict] | None = None,
+    import_cycles: list[dict] | None = None,
+    deep_nesting_files: list[dict] | None = None,
+    long_functions_files: list[dict] | None = None,
+    too_many_params_files: list[dict] | None = None,
+    duplicate_code_clusters: list[list[dict]] | None = None,
+    typing_files: list[dict] | None = None,
+) -> dict:
+    """Build a ranked, plain-language remediation list from existing analyses.
+
+    All arguments are optional and keyword-only; callers pass whichever analyses
+    are available. Returns::
+
+        {
+          "total": int,
+          "items": [
+            {
+              "priority": "high" | "medium" | "low",
+              "category": str,
+              "title": str,
+              "target": str,    # file path, or "" when not file-specific
+              "detail": str,    # plain-language explanation
+              "effort": "small" | "medium" | "large",
+            },
+            ...
+          ],
+          "notes": [str, ...],
+        }
+    """
+    items: list[dict] = []
+    items += _security_actions(security)
+    items += _coverage_actions(test_coverage)
+    items += _complexity_actions(complexity_files)
+    items += _deep_nesting_actions(deep_nesting_files)
+    items += _long_functions_actions(long_functions_files)
+    items += _too_many_params_actions(too_many_params_files)
+    items += _duplicate_code_actions(duplicate_code_clusters)
+    items += _architecture_actions(import_cycles)
+    items += _typing_actions(typing_files)
+    items += _tech_debt_actions(tech_debt_files)
+
+    # Stable sort by priority so within a priority the source order (security,
+    # coverage, complexity, …) is preserved.
+    items.sort(key=lambda a: _PRIORITY_RANK.get(a["priority"], 9))
+    items = items[:_MAX_ITEMS]
+
+    notes: list[str] = []
+    if not items:
+        notes.append("没有发现需要优先处理的问题，代码基线良好。")
+    elif items[0]["priority"] == "high":
+        notes.append("列表已按优先级排序，建议从第一条开始处理。")
+
+    return {"total": len(items), "items": items, "notes": notes}
+
+
+_PRIORITY_LABEL = {"high": "🔴 高", "medium": "🟡 中", "low": "⚪ 低"}
+_EFFORT_LABEL = {"small": "小", "medium": "中", "large": "大"}
+
+
+def render_action_plan_markdown(project_name: str, data: dict | None) -> str:
+    """Render the action plan as a Markdown section."""
+    if not data or not data.get("items"):
+        return ""
+    lines = [
+        f"# 优先行动清单（{project_name}）",
+        "",
+        "> 按「先做哪个最值」排序：安全和缺测试的核心文件排在前面。",
+        "",
+        "| # | 优先级 | 事项 | 工作量 |",
+        "|---|--------|------|--------|",
+    ]
+    for i, item in enumerate(data["items"], start=1):
+        prio = _PRIORITY_LABEL.get(item["priority"], item["priority"])
+        effort = _EFFORT_LABEL.get(item["effort"], item["effort"])
+        lines.append(f"| {i} | {prio} | {item['title']} | {effort} |")
+
+    lines += ["", "## 说明", ""]
+    for item in data["items"]:
+        lines.append(f"- **{item['title']}** — {item['detail']}")
+
+    notes = data.get("notes", [])
+    if notes:
+        lines += ["", "## 注意事项", ""]
+        for n in notes:
+            lines.append(f"- {n}")
+
+    return "\n".join(lines).rstrip() + "\n"

backend/services/activity.py

@@ -0,0 +1,313 @@
+"""Project activity pulse: recent commit timeline and contributor rhythm.
+
+When a non-programmer evaluates code they didn't write — outsourced work,
+a library they're considering, a fork they inherited — one of the first
+questions is "is this actively maintained?". The import graph and test
+coverage say nothing about velocity. This module answers that question
+from git history: how many commits landed recently, who is active, and
+which parts of the codebase are in motion.
+
+Four time windows:
+  week      last 7 days
+  month     last 30 days
+  quarter   last 90 days
+  total     all history in the collected log
+
+For each window it reports commit count, unique authors, the files that
+changed, and a simple activity label: ``active`` / ``slowing`` /
+``stale`` / ``abandoned``.
+
+It reuses the git log text already collected by :func:`churn.collect_git_log`
+(format ``::C::hash::timestamp::author``), so no extra shell call is needed.
+
+Pure function over the log text — unit-testable with fixture strings, no
+repo required.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+_COMMIT_RE = re.compile(r"::C::([0-9a-f]+)::(\d+)::(.*)")
+_NUMSTAT_RE = re.compile(r"^(\d+|-)\t(\d+|-)\t(.+)$")
+
+# Heuristic thresholds for activity labels (commits per 30-day window)
+_ACTIVE_THRESHOLD = 5  # ≥5 commits in last month → active
+_SLOWING_THRESHOLD = 1  # ≥1 commit in last month but <5 → slowing
+
+
+def _label(commits_last_30d: int, days_since_last: float) -> str:
+    if days_since_last > 365:
+        return "abandoned"
+    if days_since_last > 90:
+        return "stale"
+    if commits_last_30d >= _ACTIVE_THRESHOLD:
+        return "active"
+    if commits_last_30d >= _SLOWING_THRESHOLD:
+        return "slowing"
+    return "quiet"
+
+
+_LABEL_ZH = {
+    "active": "活跃（近 30 天有 {n} 次提交）",
+    "slowing": "减速中（近 30 天仅 {n} 次提交，势头在减弱）",
+    "quiet": "平静（近 30 天没有提交，但最近 3 个月内有活动）",
+    "stale": "沉寂（超过 3 个月没有新提交）",
+    "abandoned": "疑似停摆（超过一年没有新提交）",
+}
+
+
+def _label_zh(label: str, commits_last_30d: int) -> str:
+    return _LABEL_ZH.get(label, label).format(n=commits_last_30d)
+
+
+def analyze_activity(git_log: str | None, *, now: float | None = None) -> dict:
+    """Summarise recent project activity from git log text.
+
+    Args:
+        git_log: output of ``churn.collect_git_log`` — ``None`` means no git
+            history available (uploaded project without .git).
+        now: optional Unix timestamp to use as "now" (for testing).
+
+    Returns::
+
+        {
+          "available": bool,
+          "total_commits": int,
+          "first_commit_days_ago": float | None,
+          "last_commit_days_ago": float | None,
+          "label": str,           # active | slowing | quiet | stale | abandoned
+          "label_zh": str,
+          "windows": {
+            "week":    {"commits": int, "authors": [str, ...], "files": [str, ...]},
+            "month":   {...},
+            "quarter": {...},
+            "total":   {...},
+          },
+          "top_contributors": [{"author": str, "commits": int}, ...],
+          "recently_changed": [str, ...],   # files touched in last 7 days, ranked
+          "notes": [str, ...],
+        }
+    """
+    if not git_log:
+        return {
+            "available": False,
+            "total_commits": 0,
+            "first_commit_days_ago": None,
+            "last_commit_days_ago": None,
+            "label": "unknown",
+            "label_zh": "无 git 历史（上传的项目无法分析活跃度）",
+            "windows": {},
+            "top_contributors": [],
+            "recently_changed": [],
+            "notes": ["上传的项目没有 git 历史，活跃度分析不可用。"],
+        }
+
+    ts_now = now if now is not None else time.time()
+
+    # Parse commits
+    commits: list[dict] = []
+    current: dict | None = None
+    for line in git_log.splitlines():
+        m = _COMMIT_RE.match(line)
+        if m:
+            if current:
+                commits.append(current)
+            current = {
+                "hash": m.group(1),
+                "ts": int(m.group(2)),
+                "author": m.group(3).strip(),
+                "files": [],
+            }
+            continue
+        if current is None:
+            continue
+        nm = _NUMSTAT_RE.match(line)
+        if nm:
+            fname = nm.group(3).strip()
+            # git renames: "old => new" or "{old => new}/suffix"
+            if " => " in fname:
+                fname = re.sub(r"\{[^}]* => ([^}]*)\}", r"\1", fname).replace(" => ", "/")
+            current["files"].append(fname)
+
+    if current:
+        commits.append(current)
+
+    if not commits:
+        return {
+            "available": True,
+            "total_commits": 0,
+            "first_commit_days_ago": None,
+            "last_commit_days_ago": None,
+            "label": "unknown",
+            "label_zh": "无法解析 git 提交记录",
+            "windows": {},
+            "top_contributors": [],
+            "recently_changed": [],
+            "notes": ["git 日志为空或格式无法识别。"],
+        }
+
+    # Sort newest → oldest (git log is already newest-first but be safe)
+    commits.sort(key=lambda c: c["ts"], reverse=True)
+    newest_ts = commits[0]["ts"]
+    oldest_ts = commits[-1]["ts"]
+    total_commits = len(commits)
+    days_since_last = (ts_now - newest_ts) / 86400
+    first_commit_days_ago = (ts_now - oldest_ts) / 86400
+
+    # Window boundaries (seconds from now)
+    _WINDOWS = {
+        "week": 7 * 86400,
+        "month": 30 * 86400,
+        "quarter": 90 * 86400,
+        "total": float("inf"),
+    }
+
+    windows: dict[str, dict] = {}
+    for name, span in _WINDOWS.items():
+        cutoff = ts_now - span
+        wc = [c for c in commits if c["ts"] >= cutoff]
+        authors: list[str] = []
+        files: list[str] = []
+        seen_a: set[str] = set()
+        seen_f: set[str] = set()
+        for c in wc:
+            if c["author"] not in seen_a:
+                authors.append(c["author"])
+                seen_a.add(c["author"])
+            for f in c["files"]:
+                if f not in seen_f:
+                    files.append(f)
+                    seen_f.add(f)
+        windows[name] = {
+            "commits": len(wc),
+            "authors": authors[:10],
+            "files": files[:15],
+        }
+
+    # Top contributors (total history)
+    author_counts: dict[str, int] = {}
+    for c in commits:
+        author_counts[c["author"]] = author_counts.get(c["author"], 0) + 1
+    top_contributors = sorted(author_counts.items(), key=lambda x: -x[1])[:8]
+
+    # Recently changed files (last 7 days)
+    recently_changed = windows["week"]["files"]
+
+    # Activity label
+    commits_last_30d = windows["month"]["commits"]
+    label = _label(commits_last_30d, days_since_last)
+    label_zh = _label_zh(label, commits_last_30d)
+
+    notes = _build_notes(
+        label, commits_last_30d, days_since_last, total_commits, len(author_counts)
+    )
+
+    return {
+        "available": True,
+        "total_commits": total_commits,
+        "first_commit_days_ago": round(first_commit_days_ago, 1),
+        "last_commit_days_ago": round(days_since_last, 1),
+        "label": label,
+        "label_zh": label_zh,
+        "windows": windows,
+        "top_contributors": [{"author": a, "commits": n} for a, n in top_contributors],
+        "recently_changed": recently_changed,
+        "notes": notes,
+    }
+
+
+def _build_notes(
+    label: str,
+    commits_last_30d: int,
+    days_since_last: float,
+    total_commits: int,
+    unique_authors: int,
+) -> list[str]:
+    notes = []
+    if label == "active":
+        notes.append(
+            f"项目处于活跃维护期，近 30 天有 {commits_last_30d} 次提交，是一个健康的节奏。"
+        )
+    elif label == "slowing":
+        notes.append(
+            f"近 30 天提交减少到 {commits_last_30d} 次，势头在放缓；"
+            "如依赖此项目需关注它的维护节奏。"
+        )
+    elif label == "quiet":
+        notes.append(
+            f"近 30 天没有新提交，但最近 3 个月内有活动，"
+            f"距上次提交约 {round(days_since_last)} 天。可能正处于稳定期或低活跃阶段。"
+        )
+    elif label == "stale":
+        notes.append(
+            f"已超过 3 个月没有新提交（距上次提交 {round(days_since_last)} 天），"
+            "项目可能处于停更或维护模式，使用前请确认依赖的稳定性。"
+        )
+    elif label == "abandoned":
+        notes.append(
+            f"超过一年没有提交（距上次提交约 {round(days_since_last / 30)} 个月），"
+            "项目可能已停止维护，建议寻找活跃的替代方案或做好长期自维护的准备。"
+        )
+    if unique_authors == 1:
+        notes.append("这是单人项目，整个提交历史由一位作者贡献，对外部依赖方来说存在单点风险。")
+    elif unique_authors <= 3:
+        notes.append(f"小型团队项目，共 {unique_authors} 位贡献者参与了提交历史。")
+    else:
+        notes.append(f"共 {unique_authors} 位贡献者参与过提交，社区基础相对健康。")
+    if total_commits < 20:
+        notes.append(f"总提交数较少（{total_commits} 次），项目可能较新或提交历史较短。")
+    return notes
+
+
+def render_activity_markdown(project_name: str, data: dict | None) -> str:
+    """Render the activity summary as a Markdown section, or ``""`` if unavailable."""
+    if not data or not data.get("available"):
+        return ""
+    label_zh = data.get("label_zh", "")
+    lines = [
+        f"# 活跃度脉冲（{project_name}）",
+        "",
+        f"> 状态：**{label_zh}**",
+        "",
+    ]
+    for note in data.get("notes", []):
+        lines.append(f"- {note}")
+
+    # Window summary table
+    windows = data.get("windows", {})
+    if windows:
+        lines.append("")
+        lines.append("## 提交节奏")
+        lines.append("")
+        lines.append("| 时间窗口 | 提交次数 | 活跃作者 |")
+        lines.append("|----------|----------|----------|")
+        _WIN_LABELS = {
+            "week": "近 7 天",
+            "month": "近 30 天",
+            "quarter": "近 90 天",
+            "total": "全部历史",
+        }
+        for key in ("week", "month", "quarter", "total"):
+            w = windows.get(key, {})
+            label = _WIN_LABELS.get(key, key)
+            lines.append(f"| {label} | {w.get('commits', 0)} | {len(w.get('authors', []))} |")
+
+    top = data.get("top_contributors", [])
+    if top:
+        lines.append("")
+        lines.append("## 主要贡献者")
+        lines.append("")
+        for t in top[:5]:
+            lines.append(f"- {t['author']}（{t['commits']} 次提交）")
+
+    recent = data.get("recently_changed", [])
+    if recent:
+        lines.append("")
+        lines.append("## 近 7 天改动的文件")
+        lines.append("")
+        for f in recent[:10]:
+            lines.append(f"- `{f}`")
+
+    return "\n".join(lines).rstrip() + "\n"