wehub-skill-sync
123 lines
6.9 KiB
Markdown
123 lines
6.9 KiB
Markdown
# HTML 报告格式
|
||
|
||
架构评审渲染为 OS 临时目录下的单个自包含 HTML 文件。Tailwind 和 Mermaid 均来自 CDN。Mermaid 能可靠处理图形化图表；手写的 div 和内联 SVG 负责更偏编辑性的视觉元素（质量图、横截面）。两者混合使用——不要事事依赖 Mermaid，否则会显得千篇一律。
|
||
|
||
## 脚手架
|
||
|
||
```html
|
||
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>架构评审 — {{仓库名称}}</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>
|
||
/* 用于 Tailwind 未覆盖场景的小型自定义层：
|
||
虚线接缝线、手绘风格箭头等 */
|
||
.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>
|
||
```
|
||
|
||
## 页头
|
||
|
||
仓库名称、日期，以及一个紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，粗深色框 = 深层模块。无需引言段落——直接进入候选方案。
|
||
|
||
## 候选卡片
|
||
|
||
图表承载主要信息。文字描述应简洁、平实，直接使用词汇表中的术语（参见 [LANGUAGE.md](LANGUAGE.md)），无需额外说明。
|
||
|
||
每个候选方案为一个 `<article>`：
|
||
|
||
- **标题** —— 简短，指明深化方向（例如"折叠订单接收管道"）。
|
||
- **徽章行** —— 推荐强度（`强烈推荐` = 翠绿色，`值得探索` = 琥珀色，`探索性` = 石板色），外加依赖分类标签（`进程内`、`本地可替代`、`端口与适配器`、`模拟`）。
|
||
- **文件** —— 等宽字体列表，`font-mono text-sm`。
|
||
- **改造前/改造后对比图** —— 核心内容。两列并排。具体模式见下文。
|
||
- **问题** —— 一句话。痛点所在。
|
||
- **解决方案** —— 一句话。变更内容。
|
||
- **收益** —— 要点列表，每项不超过 6 个词。例如"测试仅命中一个接口"、"定价逻辑不再泄漏"、"删除 4 个浅层包装器"。
|
||
- **ADR 标注**（如适用）—— 琥珀色背景框中的一行文字。
|
||
|
||
无需解释性段落。如果图表需要一段文字才能理解，请重新绘制图表。
|
||
|
||
## 图表模式
|
||
|
||
根据候选方案选择匹配的模式。可混合使用。不要让每张图表看起来都一样——多样性本身就是目的之一。
|
||
|
||
### Mermaid 图（依赖/调用流的常用方案）
|
||
|
||
当表达要点是"X 调用 Y，Y 调用 Z，一团乱麻"时，使用 Mermaid 的 `flowchart` 或 `graph`。将其包裹在 Tailwind 风格的卡片中，使其不显得突兀。使用 classDef 将泄漏边着色为红色，将深层模块着色为深色。时序图非常适合"改造前：6 次往返；改造后：1 次"的场景。
|
||
|
||
```html
|
||
<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>
|
||
```
|
||
|
||
### 手写方框箭头图（当 Mermaid 的布局不合心意时）
|
||
|
||
模块使用带边框和标签的 `<div>` 实现。箭头使用内联 SVG `<line>` 或 `<path>` 元素，在相对定位的容器上进行绝对定位。当你想让"改造后"图看起来像一个粗边框的深层模块，内部元素变灰显示时，可以使用这种方式——Mermaid 无法以合适的视觉重量渲染这种效果。
|
||
|
||
### 横截面图（适用于层次化浅度分析）
|
||
|
||
堆叠水平条带（`h-12 border-l-4`）来展示调用经过的层次。改造前：6 个薄层，每层无所作为。改造后：1 个厚条带，标注合并后的职责。
|
||
|
||
### 质量图（适用于"接口与实现等宽"）
|
||
|
||
每个模块两个矩形——一个表示接口表面积，一个表示实现。改造前：接口矩形几乎与实现矩形一样高（浅层）。改造后：接口矩形矮小，实现矩形高大（深层）。
|
||
|
||
### 调用图折叠
|
||
|
||
改造前：以嵌套方框形式呈现的函数调用树。改造后：同一棵树折叠为一个方框，原内部调用在方框内以淡显方式显示。
|
||
|
||
## 样式指导
|
||
|
||
- 偏编辑风格，而非企业仪表盘风格。留白充足。标题可选衬线字体（`font-serif` 与 stone/slate 搭配效果良好）。
|
||
- 颜色慎用：一种强调色（翠绿或靛蓝），加上用于泄漏的红色和用于警告的琥珀色。
|
||
- 图表高度保持约 320px，使改造前/改造后能舒适地并排显示，无需滚动。
|
||
- 图表内模块标签使用 `text-xs uppercase tracking-wider`——它们应呈现为示意图风格，而非 UI 风格。
|
||
- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其他部分均为静态内容——无应用代码，除 Mermaid 自身渲染外无交互功能。
|
||
|
||
## 最佳推荐部分
|
||
|
||
一张较大的卡片。候选方案名称、一句话说明理由、以及指向其卡片的锚点链接。仅此而已。
|
||
|
||
## 语气
|
||
|
||
简明英语，简洁——但架构名词和动词直接来自 [LANGUAGE.md](LANGUAGE.md)。简洁不是偏离术语的借口。
|
||
|
||
**精确使用：** module（模块）、interface（接口）、implementation（实现）、depth（深度）、deep（深层）、shallow（浅层）、seam（接缝）、adapter（适配器）、leverage（杠杆效应）、locality（局部性）。
|
||
|
||
**切勿替换为：** component（组件）、service（服务）、unit（单元）代替 module（模块）· API、signature（签名）代替 interface（接口）· boundary（边界）代替 seam（接缝）· layer（层）、wrapper（包装器）代替 module（模块），当你的意思是 module 时。
|
||
|
||
**符合该风格的表述：**
|
||
|
||
- "订单接收模块较浅——接口几乎与实现相当。"
|
||
- "定价逻辑跨越接缝泄漏。"
|
||
- "深化：一个接口，一个测试点。"
|
||
- "两个适配器证明了接缝的价值：生产环境用 HTTP，测试环境用内存。"
|
||
- "收益要点"使用词汇表术语说明收益：*"局部性：bug 集中在一个模块"*、*"杠杆效应：一个接口，N 个调用点"*、*"接口缩小；实现吸收了包装器"*。不要写 *"更易维护"* 或 *"代码更整洁"*——这些术语不在词汇表中，不应占位。
|
||
|
||
不要含糊其辞、不要铺垫、不要写"值得一提的是……"。如果一个句子可以写成要点，就写成要点。如果一个要点可以被删除，就删除它。如果某个术语不在 [LANGUAGE.md](LANGUAGE.md) 中，在创造新术语之前，先使用已有的术语。
|