Skip to content

kali20gakki/msAgent / skills/minos/document-ux-review

document-ux-review

Verified

当用户希望你像第一次接触项目的人一样,真实按仓库的 README、安装文档或 quick start 跑一遍,并判断“新人能不能走通”“文档是否可用”“哪里会卡住”“安装/启动说明是否对新手友好”时,使用这个 skill。它适用于 repo onboarding audit、documentation UX review、quickstart validation、README walkthrough、按文档验证安装与运行并输出问题报告的场景;即使用户只是说“按 README 试一下”“帮我检查这个仓库文档能不能跑通”“看看 quick start 为什么带不动新人”,也应触发。不要用于纯翻译、润色、摘要、风格对比、治理项检查,或只想直接修环境/修单个报错而不做完整文档体验审查的请求。

FileKindSize
README.mdmarkdown5.9 KB
SKILL.mdskill md16.4 KB
evals/evals.jsonconfig5.2 KB
scripts/render_report_html.pyscript58.4 KB

scripts/render_report_html.py

View on GitHub
# -------------------------------------------------------------------------
# This file is part of the MindStudio project.
# Copyright (c) 2026 Huawei Technologies Co.,Ltd.
#
# MindStudio is licensed under Mulan PSL v2.
# You can use this software according to the terms and conditions of the Mulan PSL v2.
# You may obtain a copy of Mulan PSL v2 at:
#
#          http://license.coscl.org.cn/MulanPSL2
#
# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
# EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
# MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
# See the Mulan PSL v2 for more details.
# -------------------------------------------------------------------------

#!/usr/bin/env python3

import argparse
import html
import json
import re
from pathlib import Path


REF_RE = re.compile(r"((?:[\w.-]+(?:[\\/][\w.-]+)*)\.md:(\d+)(?:-(\d+))?)")
CODE_BLOCK_RE = re.compile(r"```(?:[\w+-]+)?\n([\s\S]*?)```")


def read_text(path: Path) -> str:
    return path.read_text(encoding="utf-8", errors="replace") if path.exists() else ""


def clean_value(text: str) -> str:
    cleaned = str(text or "").strip()
    if (
        cleaned.startswith("`")
        and cleaned.endswith("`")
        and len(cleaned) >= 2
        and cleaned.count("`") == 2
    ):
        return cleaned[1:-1].strip()
    return cleaned


def slugify(text: str) -> str:
    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-") or "section"


def split_sections(markdown: str) -> dict[str, str]:
    sections: dict[str, str] = {}
    matches = list(re.finditer(r"(?m)^##\s+(.+)$", markdown))
    for idx, match in enumerate(matches):
        title = match.group(1).strip()
        start = match.end()
        end = matches[idx + 1].start() if idx + 1 < len(matches) else len(markdown)
        sections[title] = markdown[start:end].strip()
    return sections


def load_json_file(path: Path, fallback):
    text = read_text(path)
    if not text.strip():
        return fallback
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        return fallback


def normalize_section_title(title: str) -> str:
    title = re.sub(r"^\d+(?:\.\d+)*\.?\s*", "", title.strip())
    return re.sub(r"\s+", "", title)


def get_section_text(sections: dict[str, str], *aliases: str) -> str:
    normalized_sections = {
        normalize_section_title(key): value for key, value in sections.items()
    }
    for alias in aliases:
        if alias in sections:
            return sections[alias]
        normalized_alias = normalize_section_title(alias)
        if normalized_alias in normalized_sections:
            return normalized_sections[normalized_alias]
    return ""


def normalize_table_rows(headers: list[str], rows: list[list[str]]) -> list[list[str]]:
    if not headers:
        return []
    target_len = len(headers)
    normalized_rows = []
    for row in rows:
        normalized = [cell.strip() for cell in row]
        if not any(normalized):
            continue
        if len(normalized) < target_len:
            normalized += [""] * (target_len - len(normalized))
        elif len(normalized) > target_len:
            normalized = normalized[:target_len]
        normalized_rows.append(normalized)
    return normalized_rows


def first_nonempty(*values: str) -> str:
    for value in values:
        cleaned = str(value or "").strip()
        if cleaned:
            return cleaned
    return ""


def parse_key_values(section_text: str) -> tuple[dict[str, str], list[str]]:
    data: dict[str, str] = {}
    ordered: list[str] = []
    for line in section_text.splitlines():
        stripped = line.strip()
        if not stripped.startswith("- "):
            continue
        content = stripped[2:].strip()
        if ":" in content:
            key, value = content.split(":", 1)
        elif ":" in content:
            key, value = content.split(":", 1)
        else:
            ordered.append(content)
            continue
        key = key.strip()
        value = value.strip()
        data[key] = value
        ordered.append(content)
    return data, ordered


def parse_list(section_text: str) -> list[str]:
    items = []
    for line in section_text.splitlines():
        stripped = line.strip()
        if stripped.startswith("- "):
            items.append(stripped[2:].strip())
        elif re.match(r"\d+\.\s+", stripped):
            items.append(re.sub(r"^\d+\.\s+", "", stripped))
    return items


def extract_first_table(section_text: str) -> tuple[list[str], list[list[str]]]:
    lines = [line.rstrip() for line in section_text.splitlines()]
    table_lines: list[str] = []
    in_table = False
    for line in lines:
        if line.strip().startswith("|"):
            table_lines.append(line.strip())
            in_table = True
        elif in_table:
            break
    if len(table_lines) < 2:
        return [], []
    header = [cell.strip() for cell in table_lines[0].strip("|").split("|")]
    rows = []
    for line in table_lines[2:]:
        rows.append([cell.strip() for cell in line.strip("|").split("|")])
    return header, rows


def parse_detailed_issues(section_text: str) -> list[dict[str, str]]:
    issues: list[dict[str, str]] = []
    matches = list(re.finditer(r"(?m)^###\s+(.+)$", section_text))
    for idx, match in enumerate(matches):
        title = match.group(1).strip()
        start = match.end()
        end = matches[idx + 1].start() if idx + 1 < len(matches) else len(section_text)
        body = section_text[start:end].strip()
        fields: dict[str, str] = {"标题": title}
        current_key = None
        for raw in body.splitlines():
            line = raw.rstrip()
            stripped = line.strip()
            bullet = re.match(r"^-\s*([^::]+)[::](.*)$", stripped)
            if bullet:
                current_key = bullet.group(1).strip()
                fields[current_key] = bullet.group(2).strip()
                continue
            if current_key and stripped:
                fields[current_key] = (
                    fields.get(current_key, "") + "\n" + stripped
                ).strip()
        issues.append(fields)
    return issues


def parse_commit(text: str) -> str:
    for candidate in re.findall(r"\b([0-9a-f]{7,40})\b", text, re.IGNORECASE):
        if len(candidate) == 40 or re.search(r"[a-f]", candidate, re.IGNORECASE):
            return candidate
    return ""


def parse_branch(text: str) -> str:
    cleaned = clean_value(text)
    if not cleaned:
        return ""
    commit = parse_commit(cleaned)
    if commit:
        cleaned = re.sub(rf"\b{re.escape(commit)}\b", "", cleaned, flags=re.IGNORECASE)
    cleaned = re.sub(r"(?i)\b(commit(?:\s+id)?|sha|revision)\b", "", cleaned)
    cleaned = re.sub(r"[()@,,:/|]+", " ", cleaned)
    cleaned = re.sub(r"\s+", " ", cleaned).strip()
    if cleaned.lower() in {"unknown", "n/a", "na"}:
        return ""
    return cleaned


def extract_score(text: str) -> str:
    match = re.search(r"总体评分[::]\s*`?([^`\n]+/100)`?", text)
    return match.group(1).strip() if match else ""


def parse_risks(section_text: str) -> list[str]:
    risks = []
    in_risks = False
    for line in section_text.splitlines():
        stripped = line.strip()
        if stripped.startswith("- 主要风险"):
            in_risks = True
            continue
        if in_risks and re.match(r"\d+\.\s+", stripped):
            risks.append(re.sub(r"^\d+\.\s+", "", stripped))
        elif in_risks and stripped.startswith("- "):
            break
    return risks


def inline_format(text: str) -> str:
    escaped = html.escape(text)
    if "`" in escaped:
        parts = escaped.split("`")
        rebuilt = []
        for idx, part in enumerate(parts):
            if idx % 2 == 1:
                rebuilt.append(f"<code>{part}</code>")
            else:
                rebuilt.append(part)
        escaped = "".join(rebuilt)
    escaped = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", escaped)
    return escaped


def render_simple_markdown(text: str) -> str:
    if not text.strip():
        return ""

    placeholders = {}

    def stash_code(match: re.Match[str]) -> str:
        key = f"__CODE_BLOCK_{len(placeholders)}__"
        placeholders[key] = (
            f"<pre><code>{html.escape(match.group(1).strip())}</code></pre>"
        )
        return key

    text = CODE_BLOCK_RE.sub(stash_code, text)
    blocks = re.split(r"\n\s*\n", text.strip())
    rendered = []
    for block in blocks:
        stripped = block.strip()
        if not stripped:
            continue
        if stripped in placeholders:
            rendered.append(placeholders[stripped])
            continue
        lines = stripped.splitlines()
        if all(line.strip().startswith("- ") for line in lines):
            items = "".join(
                f"<li>{inline_format(line.strip()[2:].strip())}</li>" for line in lines
            )
            rendered.append(f"<ul>{items}</ul>")
            continue
        if all(re.match(r"\d+\.\s+", line.strip()) for line in lines):
            items = "".join(
                "<li>{}</li>".format(
                    inline_format(re.sub(r"^\d+\.\s+", "", line.strip()))
                )
                for line in lines
            )
            rendered.append(f"<ol>{items}</ol>")
            continue
        rendered.append(
            f"<p>{inline_format(' '.join(line.strip() for line in lines))}</p>"
        )
    return "".join(rendered)


def severity_class(text: str) -> str:
    mapping = {
        "阻塞": "sev-blocker",
        "高": "sev-high",
        "中": "sev-medium",
        "低": "sev-low",
        "缺失": "sev-high",
        "不完整": "sev-high",
        "不清晰": "sev-medium",
        "部分具备": "sev-medium",
        "偏弱": "sev-medium",
    }
    for key, value in mapping.items():
        if key in text:
            return value
    return "sev-neutral"


def status_class(text: str) -> str:
    mapping = {
        "OK": "status-ok",
        "完全走通": "status-ok",
        "阻塞": "status-blocked",
        "未走通": "status-blocked",
        "偏差继续": "status-deviation",
        "部分走通": "status-deviation",
        "未执行": "status-skipped",
    }
    for key, value in mapping.items():
        if key in text:
            return value
    return "status-neutral"


def build_ref_map(texts: list[str], repo_root: Path) -> dict[str, dict]:
    refs: dict[str, dict] = {}
    for text in texts:
        for match in REF_RE.finditer(text):
            full = match.group(1)
            if full in refs:
                continue
            file_part, start_str, end_str = (
                match.group(1).split(":", 1)[0].replace("\\", "/"),
                match.group(2),
                match.group(3),
            )
            start = int(start_str)
            end = int(end_str) if end_str else start
            path = repo_root / file_part
            excerpt_lines = []
            if path.exists():
                all_lines = read_text(path).splitlines()
                start_idx = max(1, start)
                end_idx = min(len(all_lines), end)
                if end_idx - start_idx > 24:
                    excerpt_range = list(range(start_idx, start_idx + 12)) + list(
                        range(max(start_idx + 12, end_idx - 6), end_idx + 1)
                    )
                    last = None
                    for line_no in excerpt_range:
                        if last and line_no - last > 1:
                            excerpt_lines.append("... (中间省略若干行) ...")
                        excerpt_lines.append(f"{line_no}: {all_lines[line_no - 1]}")
                        last = line_no
                else:
                    for line_no in range(start_idx, end_idx + 1):
                        excerpt_lines.append(f"{line_no}: {all_lines[line_no - 1]}")
            refs[full] = {
                "id": f"ref-{slugify(full)}",
                "label": full,
                "file": file_part,
                "excerpt": "\n".join(excerpt_lines)
                if excerpt_lines
                else "未找到本地源码摘录。",
            }
    return refs


def render_ref_links(text: str, ref_map: dict[str, dict]) -> str:
    parts = []
    for match in REF_RE.finditer(text):
        ref = match.group(1)
        ref_info = ref_map.get(ref)
        if ref_info:
            parts.append(
                f'<a class="doc-link" href="#{ref_info["id"]}">{html.escape(ref)}</a>'
            )
    if parts:
        return '<div class="doc-links">' + " ".join(parts) + "</div>"
    return f"<div>{inline_format(text)}</div>"


def issue_summary_from_row(row: list[str]) -> str:
    if len(row) > 4:
        return row[4].strip()
    return ""


def scenario_top_issue(scenario: dict) -> str:
    for row in scenario.get("issue_rows", []):
        summary = issue_summary_from_row(row)
        if summary:
            return summary
    for issue in scenario.get("issues", []):
        summary = first_nonempty(
            issue.get("标题", ""),
            issue.get("实际现象", ""),
            issue.get("影响分析", ""),
        )
        if summary:
            return summary
    return "未识别关键问题"


def scenario_from_run_dir(run_dir: Path, repo_root: Path) -> dict:
    outputs = run_dir / "outputs"
    report_text = read_text(outputs / "report.md")
    transcript_text = read_text(outputs / "transcript.md")
    grading = load_json_file(run_dir / "grading.json", {})
    metadata = load_json_file(run_dir.parent.parent / "eval_metadata.json", {})
    sections = split_sections(report_text)
    overview, _ = parse_key_values(get_section_text(sections, "1. 审查对象", "审查对象"))
    conclusion_text = get_section_text(
        sections, "2. 总体评分与结论", "总体评分与结论"
    )
    conclusion, _ = parse_key_values(conclusion_text)
    flow_header, flow_rows = extract_first_table(
        get_section_text(sections, "3. 体验流程图", "体验流程图")
    )
    issue_header, issue_rows = extract_first_table(
        get_section_text(sections, "5. 关键问题概览", "关键问题概览")
    )
    industry_header, industry_rows = extract_first_table(
        get_section_text(
            sections,
            "8. 开源项目关键章节与业界实践检查",
            "开源项目关键章节与业界实践检查",
        )
    )
    issues = parse_detailed_issues(get_section_text(sections, "6. 详细问题", "详细问题"))
    risks = parse_risks(conclusion_text)
    overview = {key: clean_value(value) for key, value in overview.items()}
    conclusion = {key: clean_value(value) for key, value in conclusion.items()}
    flow_rows = normalize_table_rows(flow_header, flow_rows)
    issue_rows = normalize_table_rows(issue_header, issue_rows)
    industry_rows = normalize_table_rows(industry_header, industry_rows)
    baseline_text = first_nonempty(
        overview.get("评审基线", ""),
        overview.get("审查基线", ""),
        overview.get("评审分支和commit id", ""),
        overview.get("审查分支和commit id", ""),
        conclusion.get("结论基线", ""),
    )
    branch = clean_value(
        first_nonempty(
            overview.get("评审分支", ""),
            overview.get("审查分支", ""),
            parse_branch(baseline_text),
        )
    )
    commit = clean_value(
        first_nonempty(
            overview.get("评审提交", ""),
            overview.get("评审 commit id", ""),
            overview.get("审查提交", ""),
            parse_commit(baseline_text),
            parse_commit(transcript_text),
        )
    )
    scenario_name = clean_value(
        metadata.get("eval_name")
        or run_dir.name
        or run_dir.parent.parent.name.replace("eval-", " ").replace("-", " ").strip()
    ).replace("-", " ")
    if not scenario_name:
        scenario_name = "未命名场景"
    score = clean_value(extract_score(report_text) or conclusion.get("总体评分", ""))
    status = clean_value(conclusion.get("是否按文档走通", ""))
    refs = build_ref_map([report_text, transcript_text], repo_root)

    return {
        "scenario_name": scenario_name,
        "report_text": report_text,
        "overview": overview,
        "conclusion": conclusion,
        "score": score,
        "status": status,
        "risks": risks,
        "flow_header": flow_header,
        "flow_rows": flow_rows,
        "issue_header": issue_header,
        "issue_rows": issue_rows,
        "industry_header": industry_header,
        "industry_rows": industry_rows,
        "issues": issues,
        "newbie_notes": parse_list(
            get_section_text(sections, "7. 新手友好度观察", "新手友好度观察")
        ),
        "positive_notes": parse_list(
            get_section_text(sections, "9. 正向观察", "8. 正向观察", "正向观察")
        ),
        "priority_fixes": parse_list(
            get_section_text(
                sections, "10. 优先修复建议", "9. 优先修复建议", "优先修复建议"
            )
        ),
        "appendix": get_section_text(sections, "11. 附录", "10. 附录", "附录"),
        "grading": grading,
        "refs": refs,
        "branch": branch,
        "commit": commit,
    }


def render_table(
    headers: list[str], rows: list[list[str]], table_type: str, ref_map: dict[str, dict]
) -> str:
    rows = normalize_table_rows(headers, rows)
    if not headers or not rows:
        return ""
    parts = [f'<table class="report-table {table_type}"><thead><tr>']
    for header in headers:
        parts.append(f"<th>{inline_format(header)}</th>")
    parts.append("</tr></thead><tbody>")
    for row in rows:
        parts.append("<tr>")
        for idx, cell in enumerate(row):
            classes = []
            if table_type == "flow" and idx == 3:
                classes.append(status_class(cell))
                classes.append("cell-center")
            if idx == len(row) - 1 and table_type in {"flow", "issues", "industry"}:
                classes.append(severity_class(cell))
                classes.append("cell-center")
            if table_type == "issues" and idx == 1:
                classes.append("cell-center")
            if table_type == "industry" and idx == 1:
                classes.append("cell-center")
            class_attr = f' class="{" ".join(classes)}"' if classes else ""
            if table_type == "flow" and idx == 3:
                content = f"<span class='pill table-pill {status_class(cell)}'>{inline_format(cell)}</span>"
            elif table_type == "flow" and idx == len(row) - 1:
                content = f"<span class='pill table-pill {severity_class(cell)}'>{inline_format(cell)}</span>"
            elif table_type == "issues" and idx == 1:
                content = f"<span class='pill table-pill {severity_class(cell)}'>{inline_format(cell)}</span>"
            elif table_type == "industry" and idx == 1:
                content = f"<span class='pill table-pill {severity_class(cell)}'>{inline_format(cell)}</span>"
            else:
                content = (
                    render_ref_links(cell, ref_map)
                    if (".md:" in cell or "原文:`" in cell)
                    else inline_format(cell)
                )
            parts.append(f"<td{class_attr}>{content}</td>")
        parts.append("</tr>")
    parts.append("</tbody></table>")
    return "".join(parts)


def render_issue_cards(issues: list[dict[str, str]], ref_map: dict[str, dict]) -> str:
    if not issues:
        return ""
    parts = ['<div class="issue-grid">']
    for issue in issues:
        severity = issue.get("严重程度", "")
        parts.append(f'<section class="issue-card {severity_class(severity)}">')
        parts.append(
            f'<div class="issue-card-header"><h4>{inline_format(issue.get("标题", "未命名问题"))}</h4>'
        )
        if severity:
            parts.append(
                f'<span class="pill {severity_class(severity)}">{inline_format(severity)}</span>'
            )
        parts.append("</div>")
        category = issue.get("分类", "")
        if category:
            parts.append(
                f'<div class="meta-line"><strong>分类:</strong>{inline_format(category)}</div>'
            )
        location = issue.get("文档位置", "")
        if location:
            parts.append(
                '<div class="meta-line"><strong>文档位置:</strong>'
                + render_ref_links(location, ref_map)
                + "</div>"
            )
        excerpt = issue.get("文档原文 / 摘录", "")
        if excerpt:
            parts.append(
                f'<div class="quote-box"><strong>原文摘录</strong>{render_simple_markdown(excerpt)}</div>'
            )
        for key in ["复现上下文", "实际现象", "影响分析", "修改建议"]:
            value = issue.get(key, "")
            if value:
                parts.append(
                    f'<div class="issue-block"><div class="issue-label">{inline_format(key)}</div>{render_simple_markdown(value)}</div>'
                )
        parts.append("</section>")
    parts.append("</div>")
    return "".join(parts)


def render_source_refs(ref_map: dict[str, dict]) -> str:
    if not ref_map:
        return ""
    parts = [
        '<section class="source-section"><h3>文档依据摘录</h3><p class="section-note">点击报告中的文档位置可直接跳转到这里,查看本地源码中的对应行内容。</p>'
    ]
    for ref in sorted(ref_map.values(), key=lambda item: item["label"]):
        parts.append(f'<article class="source-card" id="{ref["id"]}">')
        parts.append(
            f'<div class="source-label">{html.escape(ref["label"])}<span>{html.escape(ref["file"])}</span></div>'
        )
        parts.append(f"<pre><code>{html.escape(ref['excerpt'])}</code></pre>")
        parts.append("</article>")
    parts.append("</section>")
    return "".join(parts)


def build_html(scenarios: list[dict], report_title: str) -> str:
    scores = []
    for scenario in scenarios:
        score = scenario.get("score", "")
        match = re.search(r"(\d+)", score)
        if match:
            scores.append(int(match.group(1)))
    avg_score = round(sum(scores) / len(scores)) if scores else None
    repo = scenarios[0]["overview"].get("仓库", "") if scenarios else ""

    html_parts = [
        "<!DOCTYPE html><html lang='zh'><head><meta charset='utf-8'>",
        "<meta name='viewport' content='width=device-width, initial-scale=1'>",
        f"<title>{html.escape(report_title)}</title>",
        "<style>",
        "body{margin:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;background:#f6f4ee;color:#161512;line-height:1.65}",
        ".page{max-width:1220px;margin:0 auto;padding:32px 24px 72px}",
        ".hero{background:linear-gradient(135deg,#1a1b18,#32352e);color:#fff;border-radius:20px;padding:28px 30px 24px;margin-bottom:22px;box-shadow:0 18px 40px rgba(0,0,0,.18)}",
        ".hero h1{margin:0 0 8px;font-size:2rem;line-height:1.2}",
        ".hero p{margin:0;color:rgba(255,255,255,.82)}",
        ".hero-meta{display:flex;flex-wrap:wrap;gap:12px 18px;margin-top:18px;font-size:.92rem}",
        ".hero-meta a{color:#ffd2c6}",
        ".score-big{display:inline-flex;align-items:center;justify-content:center;min-width:100px;padding:10px 16px;border-radius:999px;background:#f1d7b0;color:#4a2c12;font-weight:700}",
        ".summary-bar{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:14px;margin:20px 0 28px}",
        ".card{background:#fff;border:1px solid #e5dfd2;border-radius:16px;padding:16px 18px;box-shadow:0 8px 18px rgba(24,24,20,.05)}",
        ".card h3{margin:0 0 8px;font-size:.82rem;text-transform:uppercase;letter-spacing:.05em;color:#7b7467}",
        ".card .value{font-size:1.28rem;font-weight:700;color:#181714}",
        ".scenario{margin-top:28px;background:#fff;border:1px solid #e5dfd2;border-radius:22px;padding:26px 24px;box-shadow:0 14px 30px rgba(24,24,20,.06)}",
        ".scenario h2{margin:0 0 12px;font-size:1.5rem}",
        ".meta-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:12px;margin-bottom:18px}",
        ".meta-item{background:#faf8f2;border:1px solid #ece6d8;border-radius:12px;padding:12px 14px}",
        ".meta-item .label{font-size:.74rem;text-transform:uppercase;letter-spacing:.04em;color:#8a826f;margin-bottom:6px}",
        ".meta-item .content{font-size:.96rem}",
        ".meta-item a{color:#a24a2a}",
        ".pill{display:inline-flex;align-items:center;border-radius:999px;padding:4px 10px;font-size:.74rem;font-weight:700;letter-spacing:.02em}",
        ".sev-blocker{background:#f8d6d6;color:#8f2020}.sev-high{background:#fde4cf;color:#9a531e}.sev-medium{background:#f4ebc8;color:#7b6615}.sev-low{background:#dff0db;color:#2f6b34}.sev-neutral{background:#ece7dc;color:#645f55}",
        ".status-ok{background:#dff0db;color:#2f6b34}.status-blocked{background:#f8d6d6;color:#8f2020}.status-deviation{background:#fde4cf;color:#9a531e}.status-skipped{background:#ece7dc;color:#645f55}.status-neutral{background:#ece7dc;color:#645f55}",
        ".section-title{margin:28px 0 12px;font-size:1.08rem;font-weight:800}",
        ".risk-list,.note-list{margin:10px 0 0;padding-left:18px}",
        ".timeline{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:14px;margin:16px 0 20px}",
        ".timeline-card{border:1px solid #e8e1d4;border-radius:16px;padding:14px 15px;background:#fcfbf7}",
        ".timeline-card h4{margin:0 0 8px;font-size:1rem;line-height:1.35}",
        ".timeline-meta{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:10px}",
        ".timeline-block{margin-top:8px}.timeline-label{font-size:.74rem;text-transform:uppercase;letter-spacing:.04em;color:#8a826f;margin-bottom:3px}",
        ".report-table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #e5dfd2;border-radius:14px;overflow:hidden}",
        ".report-table th,.report-table td{border:1px solid #e8e1d4;padding:10px 12px;vertical-align:top;text-align:left;font-size:.9rem}",
        ".report-table th{background:#f3efe5;color:#5b5548;font-size:.76rem;text-transform:uppercase;letter-spacing:.04em}",
        ".issue-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:16px}",
        ".issue-card{border:1px solid #e5dfd2;border-radius:18px;padding:18px 18px 16px;background:#fff;box-shadow:0 10px 22px rgba(24,24,20,.05)}",
        ".issue-card-header{display:flex;justify-content:space-between;gap:12px;align-items:flex-start;margin-bottom:10px}",
        ".issue-card h4{margin:0;font-size:1.06rem;line-height:1.35}",
        ".meta-line{font-size:.9rem;margin:8px 0}.meta-line strong{color:#5f584a}",
        ".quote-box{background:#f8f4ea;border:1px solid #e6decd;border-radius:12px;padding:12px 13px;margin:12px 0}",
        ".quote-box strong{display:block;margin-bottom:6px}",
        ".issue-block{margin-top:12px}.issue-label{font-size:.75rem;font-weight:800;letter-spacing:.04em;text-transform:uppercase;color:#857d6f;margin-bottom:4px}",
        ".doc-links{display:flex;flex-wrap:wrap;gap:8px}.doc-link{display:inline-flex;align-items:center;padding:4px 9px;border-radius:999px;background:#f0ebe1;color:#8c4b2e;text-decoration:none;font-size:.82rem;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.doc-link:hover{background:#e7ddcb}",
        ".source-section{margin-top:18px}.source-card{border:1px solid #e6decd;border-radius:14px;background:#faf8f2;padding:12px 14px;margin-bottom:12px}",
        ".source-label{display:flex;justify-content:space-between;gap:12px;align-items:center;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.84rem;margin-bottom:10px;color:#5c5449}",
        ".source-label span{color:#918978;font-size:.78rem}",
        "pre{background:#151618;color:#f4f2eb;border-radius:12px;padding:14px;overflow:auto;font-size:.84rem;line-height:1.55} code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}",
        "table code,p code,li code,div code{background:#f0ebe1;border:1px solid #e3dac7;border-radius:4px;padding:1px 5px;color:#4d463a}",
        ".section-note{color:#756d5f;font-size:.92rem}",
        "@media (max-width: 720px){.page{padding:20px 14px 52px}.hero{padding:22px 18px}.scenario{padding:20px 16px}}",
        "</style></head><body><div class='page'>",
        f"<section class='hero'><h1>{html.escape(report_title)}</h1><p>这是一份聚焦真实上手体验的最终报告页,只展示按照 skill 对仓库文档进行逐步体验后得到的审查结论,不展示 benchmark、反馈控件或基线翻页界面。</p>",
    ]
    html_parts.append("<div class='hero-meta'>")
    if repo:
        html_parts.append(
            f"<div><strong>仓库:</strong><a href='{html.escape(repo)}'>{html.escape(repo)}</a></div>"
        )
    html_parts.append(f"<div><strong>场景数:</strong>{len(scenarios)}</div>")
    if avg_score is not None:
        html_parts.append(f"<div class='score-big'>平均评分 {avg_score}/100</div>")
    html_parts.append("</div></section>")
    html_parts.append("<section class='summary-bar'>")
    html_parts.append(
        f"<div class='card'><h3>审查方式</h3><div class='value'>真实执行 + 新手视角</div></div>"
    )
    html_parts.append(
        f"<div class='card'><h3>输出形式</h3><div class='value'>单页 HTML 最终报告</div></div>"
    )
    html_parts.append(
        f"<div class='card'><h3>关注重点</h3><div class='value'>走通性 / 易用性 / 行业实践</div></div>"
    )
    html_parts.append("</section>")

    for scenario in scenarios:
        refs = scenario["refs"]
        overview = scenario["overview"]
        conclusion = scenario["conclusion"]
        html_parts.append("<section class='scenario'>")
        html_parts.append(f"<h2>{html.escape(scenario['scenario_name'])}</h2>")
        html_parts.append("<div class='meta-grid'>")
        meta_items = [
            ("仓库链接", overview.get("仓库", "")),
            ("评审提交", scenario.get("commit", "") or overview.get("评审提交", "")),
            ("审查时间", overview.get("审查时间", "")),
            ("体验环境", overview.get("体验环境", "")),
            ("已具备环境", overview.get("用户声明的已具备环境", "")),
            ("隔离策略", overview.get("采用的隔离策略", "")),
            ("总体评分", scenario.get("score", "")),
            ("走通状态", scenario.get("status", "")),
        ]
        for label, value in meta_items:
            if not value:
                continue
            content = (
                f"<a href='{html.escape(value)}'>{html.escape(value)}</a>"
                if label == "仓库链接"
                else inline_format(value)
            )
            html_parts.append(
                f"<div class='meta-item'><div class='label'>{html.escape(label)}</div><div class='content'>{content}</div></div>"
            )
        html_parts.append("</div>")

        if scenario["risks"]:
            html_parts.append(
                "<h3 class='section-title'>关键风险</h3><ul class='risk-list'>"
            )
            for risk in scenario["risks"]:
                html_parts.append(f"<li>{inline_format(risk)}</li>")
            html_parts.append("</ul>")

        if scenario["flow_rows"]:
            html_parts.append(
                "<h3 class='section-title'>体验流程</h3><div class='timeline'>"
            )
            for row in scenario["flow_rows"]:
                step = row[0] if len(row) > 0 else ""
                basis = row[1] if len(row) > 1 else ""
                expected = row[2] if len(row) > 2 else ""
                status = row[3] if len(row) > 3 else ""
                phenomenon = row[4] if len(row) > 4 else ""
                cause = row[5] if len(row) > 5 else ""
                severity = row[6] if len(row) > 6 else ""
                html_parts.append("<article class='timeline-card'>")
                html_parts.append(f"<h4>步骤 {inline_format(step)}</h4>")
                html_parts.append("<div class='timeline-meta'>")
                if status:
                    html_parts.append(
                        f"<span class='pill {status_class(status)}'>{inline_format(status)}</span>"
                    )
                if severity:
                    html_parts.append(
                        f"<span class='pill {severity_class(severity)}'>{inline_format(severity)}</span>"
                    )
                html_parts.append("</div>")
                if basis:
                    html_parts.append(
                        f"<div class='timeline-block'><div class='timeline-label'>文档依据</div>{render_ref_links(basis, refs)}</div>"
                    )
                if expected:
                    html_parts.append(
                        f"<div class='timeline-block'><div class='timeline-label'>预期动作</div><div>{inline_format(expected)}</div></div>"
                    )
                if phenomenon:
                    html_parts.append(
                        f"<div class='timeline-block'><div class='timeline-label'>现象 / 结果</div><div>{inline_format(phenomenon)}</div></div>"
                    )
                if cause:
                    html_parts.append(
                        f"<div class='timeline-block'><div class='timeline-label'>原因 / 成功依据</div><div>{inline_format(cause)}</div></div>"
                    )
                html_parts.append("</article>")
            html_parts.append("</div>")
            html_parts.append(
                render_table(
                    scenario["flow_header"], scenario["flow_rows"], "flow", refs
                )
            )

        if scenario["issue_rows"]:
            html_parts.append("<h3 class='section-title'>问题概览</h3>")
            html_parts.append(
                render_table(
                    scenario["issue_header"], scenario["issue_rows"], "issues", refs
                )
            )

        if scenario["issues"]:
            html_parts.append("<h3 class='section-title'>详细问题</h3>")
            html_parts.append(render_issue_cards(scenario["issues"], refs))

        if scenario["newbie_notes"]:
            html_parts.append(
                "<h3 class='section-title'>小白用户视角</h3><ul class='note-list'>"
            )
            for note in scenario["newbie_notes"]:
                html_parts.append(f"<li>{inline_format(note)}</li>")
            html_parts.append("</ul>")

        if scenario["industry_rows"]:
            html_parts.append(
                "<h3 class='section-title'>开源项目关键章节与业界实践检查</h3>"
            )
            html_parts.append(
                render_table(
                    scenario["industry_header"],
                    scenario["industry_rows"],
                    "industry",
                    refs,
                )
            )

        if scenario["positive_notes"]:
            html_parts.append(
                "<h3 class='section-title'>做得好的地方</h3><ul class='note-list'>"
            )
            for note in scenario["positive_notes"]:
                html_parts.append(f"<li>{inline_format(note)}</li>")
            html_parts.append("</ul>")

        if scenario["priority_fixes"]:
            html_parts.append(
                "<h3 class='section-title'>优先修复建议</h3><ol class='note-list'>"
            )
            for note in scenario["priority_fixes"]:
                html_parts.append(f"<li>{inline_format(note)}</li>")
            html_parts.append("</ol>")

        html_parts.append(render_source_refs(refs))
        html_parts.append("</section>")

    html_parts.append("</div></body></html>")
    return "".join(html_parts)


def scenario_display_name(name: str) -> str:
    key = name.lower().replace("_", "-")
    if "macos" in key and "source" in key:
        return "场景 A:macOS 源码编译路径"
    if "skip" in key and "toolkit" in key:
        return "场景 B:已有基础环境,跳过 toolkit 安装"
    if "linux" in key and "install" in key:
        return "场景:Linux 隔离安装路径"
    return name.replace("-", " ")


def scenario_meaning(name: str) -> str:
    key = name.lower().replace("_", "-")
    if "macos" in key and "source" in key:
        return "代表没有现成 macOS 安装包时,用户是否能仅凭 README 和安装文档走通源码构建路径。"
    if "skip" in key and "toolkit" in key:
        return "代表用户已具备部分基础环境,希望跳过重复安装,只验证剩余文档流程是否能继续走通。"
    if "linux" in key and "install" in key:
        return "代表在隔离 Linux 环境中,用户从零开始按文档完成安装与运行验证。"
    return "代表一个真实的文档体验场景。"


def step_phase_name(expected: str) -> str:
    text = expected.lower()
    if "源码" in expected or "clone" in text or "仓库" in expected:
        return "准备源码"
    if "软件包" in expected or "发布包" in expected or "校验" in expected:
        return "获取安装包"
    if "判断" in expected or "是否可走" in expected or "路径" in expected:
        return "选择路径"
    if "编译" in expected:
        return "源码构建"
    if "安装" in expected or "whl" in text or "plugin" in text:
        return "安装组件"
    if "启动" in expected and ("daemon" in text or "dynolog" in text):
        return "启动服务"
    if "验证" in expected or "status" in text:
        return "验证结果"
    if "训练" in expected or "推理" in expected or "task" in text:
        return "运行样例"
    if "monitor" in text or "trace" in text:
        return "功能验证"
    return "执行步骤"


def step_purpose(expected: str, status: str, severity: str) -> str:
    base = expected or "执行当前文档步骤"
    if "OK" in status or "完全走通" in status:
        tail = "这一环已按文档完成,可以作为后续步骤继续推进的可靠前提。"
    elif "阻塞" in status or "未走通" in status:
        tail = "这一环已经成为主流程中断点,如果不补齐前置条件或修正文档,后续步骤无法正常继续。"
    elif "偏差继续" in status or "部分走通" in status:
        tail = "这一环需要带着执行偏差继续,说明文档对环境或路径存在隐含假设。"
    elif "未执行" in status:
        tail = "这一环没有进入执行,通常是因为前序步骤已经阻塞。"
    else:
        tail = "这一环用于确认当前文档步骤是否能稳定成立。"

    if "阻塞" in severity:
        tail += " 从审查优先级看,这也是一个需要优先修复的关键节点。"
    elif severity == "高":
        tail += " 这一步虽然不一定立刻卡死,但会显著增加新手试错成本。"
    return f"目标:{base}。{tail}"


def common_styles() -> str:
    return """
body{margin:0;background:#f5f2ea;color:#171612;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;line-height:1.62}
*{box-sizing:border-box}
a,td,th,div,p,li,span{overflow-wrap:anywhere;word-break:break-word}
.page{max-width:1160px;margin:0 auto;padding:28px 18px 64px}
.topbar{display:flex;flex-wrap:wrap;justify-content:space-between;gap:12px;align-items:center;margin-bottom:18px}
.topbar a{color:#8a4b2d;text-decoration:none;font-weight:600}
.hero{background:#1d1f1b;color:#fff;border-radius:18px;padding:22px 22px 18px;box-shadow:0 12px 28px rgba(0,0,0,.16)}
.hero h1{margin:0;font-size:1.68rem;line-height:1.22;font-weight:800;letter-spacing:-.01em}
.hero-meta{display:flex;flex-wrap:wrap;gap:10px 16px;margin-top:14px;color:rgba(255,255,255,.84);font-size:.9rem}
.hero-meta a{color:#ffd7ca}
.card-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:14px;margin:18px 0 24px}
.mini-card{background:#fff;border:1px solid #e6ded0;border-radius:14px;padding:14px 15px;box-shadow:0 8px 18px rgba(20,20,18,.05)}
.mini-card .label{font-size:.73rem;text-transform:uppercase;letter-spacing:.05em;color:#817869;margin-bottom:6px}
.mini-card .value{font-size:1rem;font-weight:650;color:#171612;line-height:1.45}
.section{background:#fff;border:1px solid #e6ded0;border-radius:18px;padding:22px 20px;margin-top:18px;box-shadow:0 10px 24px rgba(20,20,18,.05)}
.section h2{margin:0 0 14px;font-size:1.28rem;line-height:1.28;font-weight:800}
.section h3{margin:0 0 11px;font-size:1.06rem;line-height:1.36;font-weight:760}
.section p{font-size:.97rem;line-height:1.7;color:#1d1b17}
.summary-list,.note-list{margin:10px 0 0;padding-left:18px}
.summary-list li,.note-list li{margin-top:7px;font-size:.96rem}
.scenario-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:16px}
.scenario-card{background:#fcfbf7;border:1px solid #e8dfd0;border-radius:16px;padding:18px 16px;text-decoration:none;color:inherit;display:block;box-shadow:0 8px 18px rgba(20,20,18,.04)}
.scenario-card:hover{border-color:#d0b79f;transform:translateY(-1px)}
.scenario-card h3{margin:0 0 8px;font-size:1.08rem;line-height:1.35}
.scenario-card p{margin:0 0 10px;color:#5f584d;font-size:.94rem;line-height:1.62}
.meta-row{display:flex;flex-wrap:wrap;gap:8px 10px;margin-top:12px}
.pill{display:inline-flex;align-items:center;border-radius:999px;padding:4px 10px;font-size:.74rem;font-weight:750;line-height:1.2}
.table-pill{justify-content:center;min-width:72px;max-width:132px;white-space:normal;text-align:center;padding:6px 12px;font-size:.78rem;line-height:1.3}
.sev-blocker{background:#f8d6d6;color:#8f2020}.sev-high{background:#fde4cf;color:#9a531e}.sev-medium{background:#f6edca;color:#7b6615}.sev-low{background:#dff0db;color:#2f6b34}.sev-neutral{background:#ece7dc;color:#645f55}
.status-ok{background:#dff0db;color:#2f6b34}.status-blocked{background:#f8d6d6;color:#8f2020}.status-deviation{background:#fde4cf;color:#9a531e}.status-skipped{background:#ece7dc;color:#645f55}.status-neutral{background:#ece7dc;color:#645f55}
.report-table{width:100%;border-collapse:collapse;border:1px solid #e8dfd0;border-radius:14px;overflow:hidden;background:#fff}
.report-table th,.report-table td{border:1px solid #e8dfd0;padding:11px 12px;vertical-align:top;text-align:left;font-size:.92rem;line-height:1.58}
.report-table th{background:#f4efe4;color:#645c4f;font-size:.83rem;text-transform:uppercase;letter-spacing:.04em;font-weight:800;text-align:center;vertical-align:middle}
.report-table tbody tr:nth-child(even) td{background:#fcfaf5}
.report-table td.cell-center{text-align:center;vertical-align:middle}
.timeline{display:grid;grid-template-columns:1fr;gap:16px;margin:12px 0 18px}
.timeline-card{border:1px solid #e6ddd0;border-left:4px solid #d3ba9b;border-radius:18px;background:linear-gradient(180deg,#fcfbf7 0%,#fff 100%);padding:16px 16px 15px;box-shadow:0 10px 20px rgba(20,20,18,.05)}
.timeline-card h4{margin:0 0 6px;font-size:1.1rem;line-height:1.4;font-weight:820;letter-spacing:-.01em}
.timeline-step-tag{display:inline-flex;align-items:center;padding:4px 9px;border-radius:999px;background:#efe5d6;color:#7c5936;font-size:.73rem;font-weight:800;letter-spacing:.04em;text-transform:uppercase;margin-bottom:9px}
.timeline-meta{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:10px}
.timeline-block{margin-top:10px;padding:11px 12px;border-radius:12px;background:#fff;border:1px solid #ece3d6}
.timeline-label{display:inline-flex;align-items:center;padding:4px 8px;border-radius:999px;background:#f2ebe0;color:#6b5a43;font-size:.76rem;letter-spacing:.03em;font-weight:800;margin-bottom:8px}
.timeline-content{font-size:.97rem;line-height:1.66;color:#1d1b17}
.timeline-block.intro{background:#f8f3eb;border-color:#e7dccb}
.issue-grid{display:grid;grid-template-columns:1fr;gap:18px}
.issue-card{border:1px solid #e8dfd0;border-radius:16px;background:#fff;padding:16px 15px;box-shadow:0 8px 18px rgba(20,20,18,.04)}
.issue-card h4{margin:0;font-size:1.08rem;line-height:1.42;font-weight:800}
.issue-card-header{display:flex;justify-content:space-between;gap:10px;align-items:flex-start;margin-bottom:10px}
.meta-line{margin:8px 0;font-size:.96rem;line-height:1.62}
.quote-box{background:#f8f4ea;border:1px solid #e7decd;border-radius:12px;padding:12px 13px;margin:13px 0}
.issue-label{display:inline-flex;align-items:center;padding:4px 8px;border-radius:999px;background:#f2ebe0;font-size:.73rem;text-transform:uppercase;letter-spacing:.04em;font-weight:800;color:#6f614d;margin-bottom:7px}
.issue-block{margin-top:13px}
.issue-block p,.issue-block li,.quote-box p,.quote-box li{font-size:.96rem;line-height:1.68}
.doc-links{display:flex;flex-wrap:wrap;gap:8px}.doc-link{display:inline-flex;align-items:center;padding:4px 9px;border-radius:999px;background:#f0ebe1;color:#8c4b2e;text-decoration:none;font-size:.81rem;font-family:ui-monospace,SFMono-Regular,Menlo,monospace}.doc-link:hover{background:#e6ddcb}
.details-wrap{margin-top:18px}.details-wrap details{border:1px solid #e7decd;border-radius:14px;background:#faf8f2;padding:12px 14px}.details-wrap summary{cursor:pointer;font-weight:700;color:#5b5447}
.source-card{border:1px solid #e6ddcd;border-radius:12px;background:#fff;padding:12px 12px;margin-top:12px}.source-label{display:flex;justify-content:space-between;gap:10px;align-items:center;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.83rem;color:#5e564a;margin-bottom:8px}.source-label span{color:#8b8477;font-size:.77rem}
pre{background:#17191c;color:#f6f3ec;border-radius:12px;padding:13px;overflow:auto;font-size:.83rem;line-height:1.55}code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
table code,p code,li code,div code{background:#f0ebe1;border:1px solid #e3dac7;border-radius:4px;padding:1px 5px;color:#4d463a}
.backlink{display:inline-flex;align-items:center;gap:6px;color:#8a4b2d;text-decoration:none;font-weight:700}
@media (max-width:720px){.page{padding:18px 12px 48px}.hero{padding:18px 16px}.section{padding:16px 14px}.hero h1{font-size:1.42rem}.section h2{font-size:1.16rem}.timeline-card h4{font-size:1rem}.mini-card .value{font-size:.96rem}}
"""


def render_source_refs_collapsible(ref_map: dict[str, dict]) -> str:
    if not ref_map:
        return ""
    return (
        '<div class="details-wrap"><details><summary>查看文档依据摘录</summary>'
        + render_source_refs(ref_map)
        + "</details></div>"
    )


def build_overall_findings(scenarios: list[dict]) -> list[str]:
    findings = []
    if not scenarios:
        return findings
    blocked = sum(1 for s in scenarios if "未走通" in s.get("status", ""))
    partial = sum(1 for s in scenarios if "部分" in s.get("status", ""))
    findings.append(
        f"本轮共覆盖 {len(scenarios)} 个代表性场景,其中未走通 {blocked} 个,部分走通 {partial} 个。"
    )
    top_issue_texts = []
    seen = set()
    for scenario in scenarios:
        summary = scenario_top_issue(scenario)
        if summary != "未识别关键问题" and summary not in seen:
            seen.add(summary)
            top_issue_texts.append(summary)
    for text in top_issue_texts[:3]:
        findings.append(text)
    if not top_issue_texts:
        findings.append("当前未从问题概览或详细问题中识别出明确的关键问题,报告可能缺少该章节或仅输出了空表头。")
    return findings


def build_index_html(
    scenarios: list[dict], report_title: str, page_links: dict[str, str]
) -> str:
    scores = []
    for scenario in scenarios:
        match = re.search(r"(\d+)", scenario.get("score", ""))
        if match:
            scores.append(int(match.group(1)))
    avg_score = round(sum(scores) / len(scores)) if scores else None
    repo = scenarios[0]["overview"].get("仓库", "") if scenarios else ""
    branches = sorted({s.get("branch", "") for s in scenarios if s.get("branch", "")})
    commits = sorted({s.get("commit", "") for s in scenarios if s.get("commit", "")})
    branch_text = (
        branches[0] if len(branches) == 1 else f"{len(branches)} 个评审分支" if branches else ""
    )
    commit_text = (
        commits[0] if len(commits) == 1 else f"{len(commits)} 个提交快照" if commits else ""
    )

    parts = [
        "<!DOCTYPE html><html lang='zh'><head><meta charset='utf-8'>",
        "<meta name='viewport' content='width=device-width, initial-scale=1'>",
        f"<title>{html.escape(report_title)}</title><style>{common_styles()}</style></head><body><div class='page'>",
        f"<section class='hero'><h1>{html.escape(report_title)}</h1><div class='hero-meta'>",
    ]
    if repo:
        parts.append(
            f"<div><strong>仓库:</strong><a href='{html.escape(repo)}'>{html.escape(repo)}</a></div>"
        )
    if branch_text:
        parts.append(
            f"<div><strong>评审分支:</strong>{html.escape(branch_text)}</div>"
        )
    if commit_text:
        parts.append(
            f"<div><strong>评审提交:</strong>{html.escape(commit_text)}</div>"
        )
    parts.append(f"<div><strong>场景数:</strong>{len(scenarios)}</div>")
    if avg_score is not None:
        parts.append(f"<div><strong>平均评分:</strong>{avg_score}/100</div>")
    parts.append("</div></section>")

    parts.append("<section class='section'><h2>总体结论</h2><ul class='summary-list'>")
    for finding in build_overall_findings(scenarios):
        parts.append(f"<li>{inline_format(finding)}</li>")
    parts.append("</ul></section>")

    parts.append(
        "<section class='section'><h2>场景目录</h2><div class='scenario-grid'>"
    )
    for scenario in scenarios:
        filename = scenario.get("page_filename") or page_links.get(
            scenario["scenario_name"], "#"
        )
        display_name = scenario_display_name(scenario["scenario_name"])
        meaning = scenario_meaning(scenario["scenario_name"])
        status = scenario.get("status", "")
        score = scenario.get("score", "")
        top_issue = scenario_top_issue(scenario)
        parts.append(
            f"<a class='scenario-card' href='{html.escape(filename)}'><h3>{html.escape(display_name)}</h3>"
        )
        parts.append(f"<p>{inline_format(meaning)}</p>")
        parts.append(f"<p><strong>代表问题:</strong>{inline_format(top_issue)}</p>")
        parts.append("<div class='meta-row'>")
        if score:
            parts.append(
                f"<span class='pill sev-neutral'>评分 {inline_format(score)}</span>"
            )
        if status:
            parts.append(
                f"<span class='pill {status_class(status)}'>{inline_format(status)}</span>"
            )
        blocker_count = sum(
            1
            for row in scenario.get("issue_rows", [])
            if len(row) > 1 and "阻塞" in row[1]
        )
        if blocker_count:
            parts.append(
                f"<span class='pill sev-blocker'>阻塞问题 {blocker_count}</span>"
            )
        parts.append("</div></a>")
    parts.append("</div></section></div></body></html>")
    return "".join(parts)


def build_scenario_html(
    scenario: dict, report_title: str, page_links: dict[str, str], index_name: str
) -> str:
    refs = scenario["refs"]
    overview = scenario["overview"]
    display_name = scenario_display_name(scenario["scenario_name"])
    meaning = scenario_meaning(scenario["scenario_name"])

    parts = [
        "<!DOCTYPE html><html lang='zh'><head><meta charset='utf-8'>",
        "<meta name='viewport' content='width=device-width, initial-scale=1'>",
        f"<title>{html.escape(display_name)} - {html.escape(report_title)}</title>",
        f"<style>{common_styles()}</style></head><body><div class='page'>",
        f"<div class='topbar'><a class='backlink' href='{html.escape(index_name)}'>← 返回总览</a></div>",
        f"<section class='hero'><h1>{html.escape(display_name)}</h1><div class='hero-meta'><div>{inline_format(meaning)}</div></div></section>",
    ]

    parts.append("<section class='section'><h2>总体结论</h2><div class='card-grid'>")
    meta_items = [
        ("总体评分", scenario.get("score", "")),
        ("走通状态", scenario.get("status", "")),
        ("仓库链接", overview.get("仓库", "")),
        ("评审分支", scenario.get("branch", "") or overview.get("评审分支", "")),
        ("评审提交", scenario.get("commit", "") or overview.get("评审提交", "")),
        ("审查时间", overview.get("审查时间", "")),
        ("体验环境", overview.get("体验环境", "")),
        ("已具备环境", overview.get("用户声明的已具备环境", "")),
        ("隔离策略", overview.get("采用的隔离策略", "")),
    ]
    for label, value in meta_items:
        if not value:
            continue
        content = (
            f"<a href='{html.escape(value)}'>{html.escape(value)}</a>"
            if label == "仓库链接"
            else inline_format(value)
        )
        parts.append(
            f"<div class='mini-card'><div class='label'>{html.escape(label)}</div><div class='value'>{content}</div></div>"
        )
    parts.append("</div>")
    conclusion = scenario.get("conclusion", {})
    if conclusion.get("总体评价"):
        parts.append(f"<p>{inline_format(conclusion['总体评价'])}</p>")
    if scenario["risks"]:
        parts.append("<h3>关键风险</h3><ul class='summary-list'>")
        for risk in scenario["risks"]:
            parts.append(f"<li>{inline_format(risk)}</li>")
        parts.append("</ul>")
    parts.append("</section>")

    if scenario["flow_rows"]:
        parts.append("<section class='section'><h2>体验流程</h2><div class='timeline'>")
        for row in scenario["flow_rows"]:
            step = row[0] if len(row) > 0 else ""
            basis = row[1] if len(row) > 1 else ""
            expected = row[2] if len(row) > 2 else ""
            status = row[3] if len(row) > 3 else ""
            phenomenon = row[4] if len(row) > 4 else ""
            cause = row[5] if len(row) > 5 else ""
            severity = row[6] if len(row) > 6 else ""
            phase = step_phase_name(expected)
            purpose = step_purpose(expected, status, severity)
            step_title = f"步骤 {step}:{expected}" if expected else f"步骤 {step}"
            parts.append("<article class='timeline-card'>")
            parts.append(
                f"<div class='timeline-step-tag'>{inline_format(phase)}</div><h4>{inline_format(step_title)}</h4><div class='timeline-meta'>"
            )
            if status:
                parts.append(
                    f"<span class='pill {status_class(status)}'>{inline_format(status)}</span>"
                )
            if severity:
                parts.append(
                    f"<span class='pill {severity_class(severity)}'>{inline_format(severity)}</span>"
                )
            parts.append("</div>")
            parts.append(
                f"<div class='timeline-block intro'><div class='timeline-label'>本步说明</div><div class='timeline-content'>{inline_format(purpose)}</div></div>"
            )
            if basis:
                parts.append(
                    f"<div class='timeline-block'><div class='timeline-label'>文档依据</div><div class='timeline-content'>{render_ref_links(basis, refs)}</div></div>"
                )
            if phenomenon:
                parts.append(
                    f"<div class='timeline-block'><div class='timeline-label'>结果</div><div class='timeline-content'>{inline_format(phenomenon)}</div></div>"
                )
            if cause:
                parts.append(
                    f"<div class='timeline-block'><div class='timeline-label'>判断依据</div><div class='timeline-content'>{inline_format(cause)}</div></div>"
                )
            parts.append("</article>")
        parts.append("</div></section>")

    if scenario["issue_rows"]:
        parts.append("<section class='section'><h2>问题概览</h2>")
        parts.append(
            render_table(
                scenario["issue_header"], scenario["issue_rows"], "issues", refs
            )
        )
        parts.append("</section>")

    if scenario["issues"]:
        parts.append("<section class='section'><h2>详细问题</h2>")
        parts.append(render_issue_cards(scenario["issues"], refs))
        parts.append("</section>")

    if scenario["newbie_notes"]:
        parts.append(
            "<section class='section'><h2>小白用户视角</h2><ul class='note-list'>"
        )
        for note in scenario["newbie_notes"]:
            parts.append(f"<li>{inline_format(note)}</li>")
        parts.append("</ul></section>")

    if scenario["industry_rows"]:
        parts.append("<section class='section'><h2>开源项目关键章节与业界实践检查</h2>")
        parts.append(
            render_table(
                scenario["industry_header"], scenario["industry_rows"], "industry", refs
            )
        )
        parts.append("</section>")

    if scenario["priority_fixes"]:
        parts.append(
            "<section class='section'><h2>优先修复建议</h2><ol class='note-list'>"
        )
        for note in scenario["priority_fixes"]:
            parts.append(f"<li>{inline_format(note)}</li>")
        parts.append("</ol></section>")

    parts.append(
        f"<section class='section'><h2>文档依据</h2><p class='section-note'>点击正文中的文档位置会跳到下方对应摘录。为避免正文过长,这部分默认折叠。</p>{render_source_refs_collapsible(refs)}</section>"
    )
    parts.append("</div></body></html>")
    return "".join(parts)


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Render a document UX review HTML report set (overview page plus scenario detail pages)"
    )
    parser.add_argument(
        "--run-dir",
        action="append",
        required=True,
        help="Run directory containing outputs/report.md",
    )
    parser.add_argument(
        "--repo-root", required=True, help="Local repository root for source excerpts"
    )
    parser.add_argument(
        "--output",
        required=True,
        help="Overview HTML path inside the report output folder; scenario pages will be written beside it",
    )
    parser.add_argument("--title", default="文档体验审查最终报告", help="Page title")
    args = parser.parse_args()

    repo_root = Path(args.repo_root)
    scenarios = [
        scenario_from_run_dir(Path(run_dir), repo_root) for run_dir in args.run_dir
    ]
    output_path = Path(args.output)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    page_links: dict[str, str] = {}
    for idx, scenario in enumerate(scenarios, start=1):
        filename = f"scenario-{idx}-{slugify(scenario['scenario_name'])}.html"
        page_links[scenario["scenario_name"]] = filename
        scenario["page_filename"] = filename

    index_html = build_index_html(scenarios, args.title, page_links)
    output_path.write_text(index_html, encoding="utf-8")

    for scenario in scenarios:
        scenario_path = output_path.parent / scenario["page_filename"]
        scenario_html = build_scenario_html(
            scenario, args.title, page_links, output_path.name
        )
        scenario_path.write_text(scenario_html, encoding="utf-8")


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall