chore: import zh skill improve-codebase-architecture

2026-07-13 21:36:19 +08:00
commit c876f07333
6 changed files with 302 additions and 0 deletions
@@ -0,0 +1,122 @@
+# 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) 中，在创造新术语之前，先使用已有的术语。