HTML Report Format（HTML 报告格式）

架构 review 渲染为 OS temp 目录中的 single self-contained HTML file。Tailwind 与 Mermaid 均来自 CDN。Mermaid 可靠处理 graph-shaped diagram；hand-built div 与 inline SVG 处理更 editorial 视觉（mass diagram、cross-section）。Mix 两者——不要全 lean Mermaid，会 generic。

Scaffold

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Architecture review — {{repo name}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
    <style>
      /* small custom layer for things Tailwind doesn't cover cleanly:
         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
      .seam { stroke-dasharray: 4 4; }
      .leak { stroke: #dc2626; }
      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
    </style>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>...</header>
      <section id="candidates" class="space-y-10">...</section>
      <section id="top-recommendation">...</section>
    </main>
  </body>
</html>

Header（页眉）

Repo name、date、compact legend：solid box = module，dashed line = seam，red arrow = leakage，thick dark box = deep module。无 introduction paragraph——straight into candidates。

Candidate card（候选卡片）

Diagram carry weight。Prose sparse、plain，使用 glossary term（LANGUAGE.md）without ceremony。

Each candidate 一个 <article>：

Title — short，names deepening（如「Collapse the Order intake pipeline」）。
Badge row — recommendation strength（Strong = emerald，Worth exploring = amber，Speculative = slate），plus dependency category tag（in-process、local-substitutable、ports & adapters、mock）。
Files — monospaced list，font-mono text-sm。
Before / After diagram — centrepiece。Two columns side by side。见下方 patterns。
Problem — one sentence。What hurts。
Solution — one sentence。What changes。
Wins — bullets，≤6 words each。如「Tests hit one interface」「Pricing logic stops leaking」「Delete 4 shallow wrappers」。
ADR callout（若 applicable）— one line amber-tinted box。

无 explanation paragraph。若 diagram 需 paragraph 才懂，redraw diagram。

Diagram patterns（图模式）

Pick fit candidate 的 pattern。Mix。不要每个 diagram 一样——variety 是 point 一部分。

Mermaid graph（dependency / call flow 的 workhorse）

Point 是「X calls Y calls Z，看 mess」时用 Mermaid flowchart 或 graph。Wrap 在 Tailwind-styled card。classDef 将 leakage edge 标红、deep module 标 dark。Sequence diagram 适合「before: 6 round-trips; after: 1」。

<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[OrderHandler] --> B[OrderValidator]
      B --> C[OrderRepo]
      C -.leak.-> D[PricingClient]
      classDef leak stroke:#dc2626,stroke-width:2px;
      class C,D leak
  </pre>
</div>

Hand-built boxes-and-arrows（Mermaid layout 打架时）

Module 为带 border label 的 <div>。Arrow 为 inline SVG <line> 或 <path>，absolute over relative container。「After」要 one thick-bordered deep module、greyed internals 时用——Mermaid weight 不对。

Cross-section（layered shallowness）

Stack horizontal band（h-12 border-l-4）展示 call 穿过的 layer。Before：6 thin layer 各 doing nothing。After：1 thick band 标 consolidated responsibility。

Mass diagram（「interface 与 implementation 一样宽」）

每 module 两个 rectangle——interface surface area 与 implementation。Before：interface 几乎与 implementation 一样高（shallow）。After：interface 短、implementation 高（deep）。

Call-graph collapse

Before：function call tree 为 nested box。After：collapse 成 one box，internal call faded inside。

Style guidance（风格指南）

Lean editorial，非 corporate-dashboard。Generous whitespace。Heading 可选 serif（font-serif 与 stone/slate 好配）。
Colour sparingly：one accent（emerald 或 indigo）plus red leakage、amber warning。
Diagram ~320px tall，before/after side by side 不 scroll。
Diagram 内 module label 用 text-xs uppercase tracking-wider——schematic，非 UI。
仅 Tailwind CDN 与 Mermaid ESM import script。Report 否则 static——无 app code，无 Mermaid 外 interactivity。

Top recommendation section

One larger card。Candidate name、one sentence why、anchor link 到 card。That's it。

Tone（语气）

Plain English、concise——但 architectural noun/verb straight from LANGUAGE.md。Concision 不是 drift 借口。

精确使用： module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。

Never substitute： component、service、unit（for module）· API、signature（for interface）· boundary（for seam）· layer、wrapper（for module，当你 mean module）。

Fit style 的 phrasing：

「Order intake module is shallow — interface nearly matches the implementation.」
「Pricing leaks across the seam.」
「Deepen: one interface, one place to test.」
「Two adapters justify the seam: HTTP in prod, in-memory in tests.」

Wins bullets 用 glossary term 命名 gain：「locality: bugs concentrate in one module」、「leverage: one interface, N call sites」、「interface shrinks; implementation absorbs the wrappers」。不要写 「easier to maintain」 或 「cleaner code」——不在 glossary，不 earn place。

No hedging、no throat-clearing、no「it's worth noting that…」。Sentence 能变 bullet 就变 bullet。Bullet 能 cut 就 cut。Term 不在 LANGUAGE.md 时，先 reach glossary term 再 invent。

由 skills/engineering/improve-codebase-architecture/HTML-REPORT.zh-CN.md 自动生成。