Windmill 架构评审 HTML 报告格式设计深度模块、接缝与泄漏的可视化规范【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill本文以 Windmill 仓库中.agents/skills/improve-codebase-architecture/HTML-REPORT.md这份技能配套规范为主体完整拆解架构评审报告的单文件 HTML 技术底座Tailwind Mermaid 双 CDN、页面骨架、候选卡片结构与五种图表模式并结合仓库内 codebase-design 词汇表、依赖分类文档 与 CONTEXT.md 域语言讲清这类报告为什么长这样以及如何在 Windmill 这样的 Rust Svelte 大型代码库中落地。读完你能掌握一套可复制的架构改进报告写作与渲染规范从扫描热点模块、生成前后对比图到用严格术语纪律产出可被人与 Agent 共同消费的单文件报告。一、定位HTML 报告在架构改进流程中的位置HTML-REPORT.md不是独立文档而是 improve-codebase-architecture 技能 的渲染规范。该技能的定位摘自 SKILL.md 前置元数据是Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.即扫描代码库中的深化机会把浅模块变深的重构以可视化 HTML 报告呈现候选项然后针对用户选定的候选项进入追问循环。完整流程分三步Explore探索先定范围再扫描YAGNI。若用户指明了方向就直接采用否则回溯git log --oneline找持续出现的热文件让热点路径优先吸引注意力。同时先读 CONTEXT.md 域词汇表再派子代理沿代码有机地游走记录五类摩擦理解一个概念是否要在许多小模块间跳来跳去、哪些模块是浅的接口复杂度接近实现复杂度、纯函数是否只为了可测性被抽出而真实 bug 藏在调用方式里缺乏 locality、紧耦合模块是否互相泄漏、哪些部分难测试。对任何疑似浅模块执行删除测试删掉它复杂度是集中了还是只是搬走了集中才是想要的信号。Present呈现把候选项写成一个自包含 HTML 文件——这就是本文档规范的对象。Grilling追问用户选定候选项后运行 grilling 技能 沿决策树逐轮质询约束、依赖、深化后模块的形状、接缝背后放什么、哪些测试能存活期间用 domain-modeling 技能 保持域模型最新。报告文件有几条硬性产出规则来自 SKILL.mdHTML-REPORT.md 不重复写入OS 临时目录保证nothing lands in the repo——报告是一次性工件不污染仓库。临时目录从$TMPDIR解析回退到/tmpWindows 用%TEMP%文件名tmpdir/architecture-review-timestamp.html保证每次运行得到新文件。写完后主动打开Linux 用xdg-open pathmacOS 用open pathWindows 用start path并把绝对路径告知用户。报告用Tailwind via CDN做布局样式、Mermaid via CDN做图表Mermaid 与手写 CSS/SVG 混用每个候选项都要有前后对比可视化结尾有一个Top recommendation小节且不要预先提出接口方案文件写完后只问用户 Which of these would you like to explore?。值得注意的是该技能前置元数据中标记了disable-model-invocation: true即它由人手动触发、不由模型自动调用——架构评审是显式决策行为而非常驻流程。二、技术底座两个 CDN 脚本 两套可视化体系HTML-REPORT.md开篇即定下基调The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — dont lean on Mermaid for everything, itll start to look generic.拆解出四条设计决策决策内容动机单文件自包含整份报告是一个 HTML 文件落在 OS 临时目录可直接用系统默认浏览器打开无需构建步骤、不进仓库样式走 CDNTailwind Play CDNcdn.tailwindcss.com零本地资源依赖工具类即开即用图形走 CDNMermaid 11 的 ESM 模块mermaid11的.esm.min.mjs图形状的依赖关系、调用流、时序可靠渲染双轨可视化Mermaid 负责图形状内容手写div 内联 SVG 负责编辑感视觉质量图、横截面全部押注 Mermaid 会start to look generic开始显得千篇一律Mermaid 的初始化配置也写死在规范里这是报告里仅有的两处脚本之一mermaid.initialize({ startOnLoad: true, theme: neutral, securityLevel: loose });startOnLoad: true页面加载后自动渲染所有pre classmermaid块不需要任何应用代码触发theme: neutral中性主题与石色/石板色stone/slate编辑风排版不冲突securityLevel: loose允许 Mermaid 渲染自定义 HTML 片段支撑更自由的节点标签。规范末尾再次强调静态边界见第七节样式指导第 4 条除 Tailwind CDN 与 Mermaid ESM 导入外报告不含任何应用代码、没有任何 Mermaid 自身渲染之外的交互。它是一张可以截图、打印、转发给同事的静态架构图纸而不是一个网页应用。三、Scaffold完整页面骨架文档给出了可直接复制的 HTML 骨架HTML-REPORT.md 原文逐行保留仅补中文注释!doctype html html langen head meta charsetutf-8 / titleArchitecture review — {{repo name}}/title !-- 唯一的样式脚本Tailwind Play CDN -- script srchttps://cdn.tailwindcss.com/script !-- 唯一的逻辑脚本Mermaid 11 ESM 模块 -- script typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid11/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 classbg-stone-50 text-slate-900 font-sans main classmax-w-5xl mx-auto px-6 py-12 space-y-12 header.../header section idcandidates classspace-y-10.../section section idtop-recommendation.../section /main /body /html骨架里有三处值得展开的设计自定义样式层只有三条规则.seamstroke-dasharray: 4 4虚线、.leak#dc2626红色即 Tailwind 的 red-600、.deep#0f172a → #1e293b即 slate-900 → slate-800 的 135° 渐变。它们恰好对应报告图例中的三个视觉语义——接缝、泄漏、深模块与第四节 Header 的图例一一对应。这说明规范不是随意给的 CSS而是把词汇表直接编码进了样式类名seam、leak、deep都是 codebase-design 词汇表内的术语。页面级排版bg-stone-50 text-slate-900奠定暖灰底 深石板字的编辑风基调max-w-5xl mx-auto把正文控制在约 1024px 宽space-y-12给出大段留白——这是editorial, not corporate-dashboard见第七节的落点。两个固定 section 锚点#candidates候选卡片区卡间间距 10与#top-recommendation结尾的顶级推荐区见第八节。锚点 ID 是写死的因为 Top recommendation 卡片里要放指向对应候选卡片的 anchor link——跨区跳转依赖这些稳定 ID。四、Header一行图例拒绝引言规范对页头的要求极为克制Repo name, date, and a compact legend: solid box module, dashed line seam, red arrow leakage, thick dark box deep module. No introduction paragraph — straight into the candidates.即页头只包含三样东西仓库名、日期、一条紧凑图例实线框 module模块虚线 seam接缝红色箭头 leakage泄漏加粗深色框 deep module深模块且明确禁止引言段落——straight into the candidates直接进入候选项。这与全文的语气纪律一致见第九节报告是图纸不是演讲稿读者进来第一眼就要看到候选卡片。图例的四项符号与第三节自定义样式层完全咬合虚线由.seam实现、红箭头由.leak上色、深模块由.deep渐变填充。也就是说规范保证了图例承诺的每种视觉符号都有对应 CSS 类可用渲染者不需要自己临时发明。五、Candidate Card每张深化机会一个 article规范原文对卡片区的定位是The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the/codebase-designskill) without ceremony.——图承担重量散文要稀疏、朴素且直接使用 codebase-design 词汇表术语不搞仪式化措辞。每个候选项是一个article包含六个固定组件组件规范要求说明Title短标题命名这次深化例如 Collapse the Order intake pipelineBadge row推荐强度徽章 依赖类别标签Strong emerald翡翠绿、Worth exploring amber琥珀、Speculative slate石板灰依赖标签见下文Files等宽字体文件列表font-mono text-smBefore / After diagram全卡片的视觉中心两列并排见第六节五种模式Problem一句话什么在痛Solution一句话什么会改变Wins项目符号每条 ≤6 词如 Tests hit one interface、Pricing logic stops leaking、Delete 4 shallow wrappers紧接规范有一句极强的质量约束No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.禁止解释性段落。如果一张图需要一段话才能被看懂那就重画这张图。这是把图不达意的责任推回给图本身而非用散文打补丁。徽章上的依赖类别标签从哪来Badge row 里的四个依赖标签——in-process、local-substitutable、ports adapters、mock——不是随意起的名字而是直接对应 DEEPENING.md 定义的四类依赖该类目标签决定了深化后的模块如何跨接缝被测试In-process进程内纯计算、内存态、无 I/O。永远可深化——合并模块后直接通过新接口测试不需要适配器。Local-substitutable本地可替代存在本地测试替身的依赖如用 PGLite 替 Postgres、内存文件系统。只要替身存在就可深化替身跑在测试套件里接缝在模块内部外部接口不暴露端口。Remote but owned远端但自有即 Ports Adapters自己服务之间的网络边界微服务、内部 API。在接缝处定义一个端口接口深模块拥有逻辑传输以适配器注入测试用内存适配器生产用 HTTP/gRPC/队列适配器。推荐句式固定为Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though its deployed across a network.True external真外部即 Mock不掌控的第三方服务Stripe、Twilio 等。深化模块把外部依赖作为注入端口接收测试提供 mock 适配器。放在 Windmill 的语境里这个分类可以直接对号入座仓库内测试广泛使用真实 Postgres如 backend/tests 目录下的 SQL/Rust 集成测试涉及 Postgres 的深化候选通常落为local-substitutable有 PGLite 这类本地替身可用而 worker 与 API 之间的队列交互windmill-queue这类自有远端依赖则对应ports adapters类。规范把分类做成卡片标签等于要求每张深化提案在呈现时就已回答它靠什么被测试——这是 DEEPENING.md 中dependency category determines how the deepened module is tested across its seam的直接落地。接缝纪律与卡片内容的呼应DEEPENING.md 还有两条接缝纪律约束卡片中 Before/After 图的画法One adapter means a hypothetical seam. Two adapters means a real one.一个适配器只是假想接缝两个才是真实接缝以及内部接缝 vs 外部接缝的区分——深模块可以拥有私有于实现、供自身测试使用的内部接缝不应仅因测试要用就把内部接缝暴露到外部接口上。这解释了为什么规范强调After 图应该像一个厚边框的深模块、内部细节被灰化见 6.2深化后的模块在图上只呈现外部接缝内部复杂度被有意藏起来。六、五种图表模式Mermaid 与手绘各取所长规范原文Pick the pattern that fits the candidate. Mix them. Dont make every diagram look the same — variety is part of the point.——挑匹配该候选项的模式混着用别让所有图长一样多样性本身是目的之一。五种模式及其适用场景6.1 Mermaid 流程图依赖与调用流的主力适用点是一句话X calls Y calls Z, and look at the mess.X 调 Y 调 Z看这团乱麻。要点用flowchart或graph包在 Tailwind 卡片里以免显得空降用classDef把泄漏边染红、深模块染深**时序图sequence diagram**特别适合表现before: 6 round-trips; after: 1之前 6 次往返、之后 1 次这类削减往返的深化。规范给出的完整示例div classrounded-lg border border-slate-200 bg-white p-4 pre classmermaid 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解读这个示例OrderHandler → OrderValidator → OrderRepo是正常调用链C -.leak.- D用 Mermaid 的虚线箭头语法-.文本.-把OrderRepo对PricingClient的越界依赖画成泄漏——定价逻辑本不该从仓储层漏出去。classDef leak用stroke:#dc2626,stroke-width:2px与自定义层.leak同色加粗描边class C,D leak把这两个节点都染上泄漏样式。外层rounded-lg border bg-white p-4即Tailwind 卡片包裹要求。6.2 手绘盒子与箭头当 Mermaid 布局不顺时适用点模块用带边框和标签的div表示箭头用绝对定位在相对容器之上的内联 SVGline或path元素。当 After 图需要呈现一个厚边框的深模块、内部细节被灰化的视觉重量时用它——Mermaid 画不出那种重量感。这正好与 DEEPENING.md 的内部/外部接缝纪律呼应深化后外部观察者只应看到厚边框和极简接口。6.3 横截面Cross-section分层浅薄适用点layered shallowness层层皆浅。把水平条带h-12 border-l-4即固定高度 4px 左边框叠起来表示一次调用穿过的各层。Before6 层薄带每层什么都没做After1 条厚带标注合并后的职责。border-l-4的粗左边框就是厚薄的视觉载体——带子越厚职责越集中。6.4 质量图Mass diagram接口与实现的面积对比适用点interface as wide as implementation接口宽得跟实现一样。每个模块画两个矩形一个表示接口表面积一个表示实现。Before接口矩形几乎和实现矩形一样高浅After接口矩形短、实现矩形高深。这一模式是 codebase-design SKILL.md 中Deep vs shallow ASCII 图的直接图形化——该词汇表用字符画定义了┌─────────────────────┐ ┌─────────────────────────────────┐ │ Small Interface │ ← │ Large Interface │ ← ├─────────────────────┤ ├─────────────────────────────────┤ │ Deep Implementation│ │ Thin Implementation │ └─────────────────────┘ └─────────────────────────────────┘并给出设计接口时的三问能否减少方法数能否简化参数能否把更多复杂度藏进内部注意该词汇表还特意拒绝了Ousterhout 的深度 实现行数 / 接口行数定义rewards padding the implementation——奖励堆砌实现改用depth-as-leverage深度即杠杆接口处单位认知成本换来的行为量。质量图因此比较的是表面积 vs 隐藏的行为量而非代码行数。6.5 调用图坍缩Call-graph collapseBefore函数调用树渲染成嵌套盒子After同一棵树坍缩为一个盒子原本的调用以淡化形式显示在盒子内部。这是删除测试成功的视觉表达被内化的调用从接口上消失成为实现细节。五种模式的共同点全部服务于 Before/After 并排两列的呈现且都在让浅薄可见、让深度可见——这与报告的目标surface architectural friction是同一件事。七、Style guidance编辑风排版四条纪律规范给出的四条样式指导逐条可验证、可执行Editorial, not corporate-dashboard编辑风而非企业仪表盘风。大留白。标题可用衬线体font-serif与 stone/slate 配色配合效果好。颜色克制一个强调色emerald 或 indigo 红色给泄漏 琥珀色给警告。与徽章配色Strongemerald、Worth exploringamber、Speculativeslate共用同一色板保证整份报告色彩语义一致。图高约 320px使 Before/After 能并排放下而无需滚动——这是图承担重量的硬约束如果两列图需要滚动才能同时看到对比就失效了。图内模块标签用text-xs uppercase tracking-wider——它们是示意图标签schematic不是 UI 文案。全大写 宽字距 小字号让图上文字读起来像工程图纸注记而非界面元素。规范原文合并表述的最后一条仅有的脚本是 Tailwind CDN 和 Mermaid ESM 导入报告其余部分是完全静态的——无应用代码、无 Mermaid 渲染之外的交互。八、Top recommendation结尾的一张大卡One larger card. Candidate name, one sentence on why, anchor link to its card. Thats it.报告以 Top recommendation 小节收尾只有一张更大的卡片包含三样东西——候选项名字、一句为什么先做它、指向该候选卡片的锚点链接。Thats it. 是规范里最不容商量的收尾不许展开论述不许列实施计划不许预先设计接口SKILL.md 明确 Do NOT propose interfaces yet。选择权留给用户深化方案在后续的 grilling 循环中共同推导。九、语气与术语纪律词汇表即接口HTML-REPORT.md最独特的一节是 Tone。它把用词提升到规范层面Plain English, concise — but the architectural nouns and verbs come straight from the/codebase-designskill. Concision is not an excuse to drift.普通英语、简洁但架构名词与动词必须原样取自 codebase-design 词汇表简洁不是跑偏的借口。具体是两张清单必须精确使用Use exactly术语codebase-design 中的定义要点module有接口与实现的一切刻意尺度无关——函数、类、包、跨层切片皆可。避免unit、component、serviceinterface调用方为正确使用该模块必须知道的一切类型签名也包括不变量、顺序约束、错误模式、必需配置、性能特征。避免API、signature太窄只指类型层面implementation模块内部本体。与adapter区分适配器描述角色填哪个槽位实现描述实质depth / deep / shallow深度是接口处的杠杆单位接口认知换来的行为量。大量行为藏在小接口后 深接口复杂度接近实现复杂度 浅seamMichael Feathers不修改原地即可改变行为的位置即模块接口所在的位置。避免boundary与 DDD 的 bounded context 撞车adapter在接缝上满足接口的具体事物描述角色而非实质。小适配器可有大实现Postgres repo大适配器可有极小实现in-memory fakeleverage调用方从深度得到的单位接口认知换来的能力。一份实现在 N 个调用点、M 个测试上回报locality维护者从深度得到的变更、bug、知识、验证集中在一处。修一次处处修好永远不许替换Never substitutecomponent/service/unit替 module· API/signature替 interface· boundary替 seam· layer/wrapper当指 module 时。规范还给了四条合身句式示范这些句式可以直接当写作模板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 项目符号必须用词汇表术语命名收益规范给出了三类范式locality: bugs concentrate in one module、leverage: one interface, N call sites、interface shrinks; implementation absorbs the wrappers。同时点名禁止 easier to maintain、cleaner code 这类话——those terms arent in the glossary and dont earn their place这些词不在词汇表里不配占位置。收尾两条语气禁令无含糊其辞no hedging、无清嗓子no throat-clearing即禁 its worth noting that… 之类If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it.能成为条目的句子做成条目能砍掉的条目直接砍掉。若某个词不在词汇表里先去词汇表里找一个现成的而不是发明新词。这套纪律的深层目的在 codebase-design SKILL.md 里写明Consistent language is the whole point.语言一致就是全部意义——当报告、评审、Agent 提示词、CONTEXT.md 全部使用同一组术语时深/浅/接缝/泄漏才能成为跨文档、跨会话可检索、可对齐的公共词汇。对 LLM 与 Agent 而言术语一致性直接决定了它们能否在后续 grilling 循环中准确引用报告中的结论。十、域语言衔接与下游流程SKILL.md 要求报告Use CONTEXT.md vocabulary for the domain, and the/codebase-designvocabulary for the architecture——域用 CONTEXT.md 的词架构用 codebase-design 的词。若 CONTEXT.md 定义了 Order就谈 the Order intake module既不叫 the FooBarHandler按代码命名也不叫 the Order service被词汇表明确拉黑的词。以 Windmill 的 CONTEXT.md 为例它固定了 Flows 域的术语Step 在代码中类型化为FlowModule、Step setting、Configured、Trigger step 等与权限域术语Member、Role、Owner且每条都带 Avoid 禁用词清单。这意味着在 Windmill 里写架构评审报告时涉及流程图节点的候选卡片必须称 Step并明确避免与架构术语 module 混淆——CONTEXT.md 特意注明 module (ambiguous with the architectural sense)涉及权限模块的候选则要按 Member/Role 而非 user/permission 命名。两套词汇表各管一半、互不越界正是 HTML-REPORT.md Use exactly / Never substitute 纪律能成立的理由。报告写完后进入 SKILL.md 第三节的Grilling loop用户选定候选项后grilling 技能 以设计树组织追问——每轮把前沿所有前置决策已定的问题一次性问全每题附推荐答案找事实是 Agent 的活找决策是用户的活。过程中侧效应当场落地深化模块若以 CONTEXT.md 中没有的概念命名就把该术语补进 CONTEXT.md文件惰性创建想探索深化模块的替代接口时运行 codebase-design 的 Design It Twice 并行子代理模式3 个以上子代理各自产出激进不同的接口设计按深度、局部性、接缝位置横向比较。十一、来源与本地化改造按 UPSTREAM.md 的说明improve-codebase-architecture连同grilling、codebase-design、domain-modeling、grill-me五个技能是从外部技能仓库 vendor 进来的MIT 协议固定在特定 commit 上UPSTREAM.md 同时收录了完整 MIT 许可文本五者构成一个依赖闭包grill-me是运行grilling的桩improve-codebase-architecture的词汇来自codebase-design、域模型维护来自domain-modeling删掉任何一个都会破坏其他技能。本地在上游基础上做了最小化改造以保持刷新时只是一次 diff其中两条与本文档直接相关链接策略上游各 SKILL.md 中指向自身捆绑文件的 markdown 链接被替换为散文里的仓库根路径如.agents/skills/improve-codebase-architecture/HTML-REPORT.md。原因是本仓库通过.claude/skills/skill/SKILL.md符号链接镜像只镜像了 SKILL.md 本身——兄弟相对链接经符号链接读取时会断裂而仓库根路径在散文里永远成立。配套文件也就是 HTML-REPORT.md 这类保留兄弟相对链接因为它们只在真实路径下被读取。ADR 全量移除上游的improve-codebase-architecture会读取并引用docs/adr/下的架构决策记录HTML-REPORT.md中原本还有一行ADR callout row本仓库未采纳 ADR 实践故连同 domain-modeling 的 ADR 格式文件、Offer ADRs sparingly 小节、报告中的 ADR 行一并删除——a skill that offers to create them is how the practice arrives by side effect rather than by decision技能主动提供创建 ADR就是让实践以副作用而非决策的方式悄悄落地。这也解释了为什么本文看到的报告结构里没有任何 ADR 槽位。刷新策略也已写明对新 commit 的同路径做 diff、重新应用这些改造其中 ADR 移除是唯一需要判断的——若团队日后正式采纳 ADR应取回上游版本而不是在这里重写。十二、小结一份规范为何同时是工程规范与语言规范HTML-REPORT.md表面是一份 HTML 模板规范实际上同时约束了三层东西工程层单文件自包含 两个 CDN 静态渲染使架构报告成为零依赖、可即时打开、不进仓库的一次性工件视觉层图例模块/接缝/泄漏/深模块→ 自定义 CSS 层.seam/.leak/.deep→ 五种图表模式 → 320px 图高与并排两列保证 Before/After 对比永远同时可见语言层badge 依赖标签对应 DEEPENING.md 四分类、Wins 与正文强制使用 codebase-design 词汇表、域名取自动态维护的 CONTEXT.md——报告因此不只是给人看的图也是给后续 grilling 循环、Agent 会话和词汇表迭代可引用的术语锚点。想在自己的 Rust Svelte 代码库上复现这套流程入口就是 improve-codebase-architecture 技能定义手动触发技能按 Explore → Present → Grilling 三步走报告渲染时对照 HTML-REPORT.md 的本节骨架与五条图表模式逐条实现即可所有术语以 codebase-design 词汇表 为唯一事实来源域术语以仓库根 CONTEXT.md 为准。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考