Windmill 架构深耕指南用 improve-codebase-architecture 技能扫描并重构浅层模块【免费下载链接】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 开源仓库内置的improve-codebase-architecture技能展开完整讲解一套扫描代码库 → 生成可视化 HTML 架构评审报告 → 用户挑选候选 → 持续追问打磨的架构深化工作流。你将掌握深度depth与浅度shallow模块的判别方法、删除测试deletion test与接缝seam纪律、HTML 报告的渲染规范与图表模式以及如何用grilling与domain-modeling技能把一次架构重构落到实处。这套方法论不仅能用于 Windmill 自身的 Rust 后端、Svelte 前端与 TypeScript CLI也可迁移到任何代码库的模块重构中。技能定位面向可测试性与 AI 可导航性的架构深化.agents/skills/improve-codebase-architecture/SKILL.md是 Windmill 仓库中由 Claude Code 技能体系驱动的一个工作流技能。它开篇即声明自身目的暴露架构摩擦点并提出深化机会deepening opportunities——也就是把浅层模块重构为深层模块deep modules的候选改造。其核心衡量标准有两条可测试性testability模块的接口是否就是测试面测试能否穿过接口直接验证行为AI 可导航性AI-navigability人类与 AI Agent 能否在少量跳跃内理解一个概念的全部实现。技能元数据中有一行值得注意的配置--- name: improve-codebase-architecture description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. disable-model-invocation: true ---其中disable-model-invocation: true表明该技能不允许模型自主触发只能由用户显式调用通常通过斜杠命令/improve-codebase-architecture之类的方式发起。这意味着整个流程由用户掌控节奏扫描什么、选哪个候选、是否继续深化决策权始终在人。前置基础两套必须沿用的术语体系执行本技能前需要先建立两套共享词汇一套是架构设计词汇来自codebase-design技能另一套是领域词汇来自仓库根目录的CONTEXT.md。架构词汇/codebase-design技能技能要求在每个建议中精确使用这些术语不要漂移成 componentserviceAPIboundary。核心词汇定义见.agents/skills/codebase-design/SKILL.md术语定义注意事项Module模块任何同时拥有接口与实现的东西刻意与规模无关可以是函数、类、包也可以是跨层切片避免使用 unit、component、serviceInterface接口调用方为正确使用模块而必须知道的一切类型签名、不变量、顺序约束、错误模式、所需配置、性能特征避免使用 API、signature过于狭窄只指类型层表面Implementation实现模块内部的内容即其代码主体与 Adapter 区分Postgres 仓储是小适配器 大实现内存假件是大适配器 小实现Depth深度接口处的杠杆调用方或测试每学习一单位接口能获得的、可调用的行为量模块深 大量行为藏在小型接口之后浅 接口几乎和实现一样复杂Seam接缝Michael Feathers 术语——无需原地编辑即可改变行为的位置即模块接口所在的位置避免使用 boundary与 DDD 的限界上下文语义过载Adapter适配器在接缝处满足接口的具体实现描述的是角色而非本质——Leverage杠杆调用方从深度中获得的东西每学习一单位接口获得更多能力一份实现回馈 N 个调用点与 M 个测试——Locality局部性维护者从深度中获得的东西变更、缺陷、知识与验证都集中在一处而非散布在调用方之间修一次处处修复技能对深度给出了直白的判别标准深模块 小型接口 大量实现 ┌─────────────────────┐ │ Small Interface │ ← 少量方法、简单参数 ├─────────────────────┤ │ Deep Implementation│ ← 复杂逻辑被隐藏 └─────────────────────┘ 浅模块 大型接口 少量实现应避免 ┌─────────────────────────────────┐ │ Large Interface │ ← 大量方法、复杂参数 ├─────────────────────────────────┤ │ Thin Implementation │ ← 只是透传 └─────────────────────────────────┘设计接口时反复自问三个问题能否减少方法数量能否简化参数能否把更多复杂性藏进内部codebase-design技能还定义了四条关键原则深度是接口的属性不是实现的属性。深层模块内部可以由许多小型、可 mock、可替换的部分组成——它们只是不进入接口。模块既有内部接缝私有于实现、供自身测试使用也有位于接口处的外部接缝。删除测试the deletion test想象删除这个模块。如果复杂性随之消失说明它只是透传pass-through如果复杂性重新散布到 N 个调用方说明它在物有所值。接口就是测试面the interface is the test surface调用方与测试穿过同一个接缝。如果你想越过接口去测试模块的形状可能就错了。一个适配器意味着假设的接缝两个适配器才意味着真实的接缝one adapter hypothetical seam, two real除非真的有东西跨接缝变化否则不要引入接缝。单个适配器的接缝只是间接层。领域词汇CONTEXT.md技能要求先读仓库根目录的 CONTEXT.md其中的领域语言为好的接缝命名。这份文件是 Windmill 自身的领域术语表ubiquitous language例如Step流程flow中的一个节点即用户在图中选中并在右侧面板配置的单元代码中类型化为FlowModule。避免module与架构语义混淆、node、action。Step setting存储于 step 之上的逐步骤运行时选项重试、错误处理、超时、并发限制、优先级、缓存、防抖、提前停止、跳过、挂起、休眠、存活期。避免advanced setting、step config、flow option。Configured指某 step setting 的配置对象已存在于该 step 上刻意区别于会改变运行时行为——一个 setting 可以已配置却仍是 no-op如sleep为0。避免enabled、active、effective。Trigger step轮询流程的第一步按调度运行并返回自上次运行以来发现的条目空返回意味着无事可处理流程提前结束并标记为 skipped 而非 failed。避免poll script、trigger node、schedule step。Member / Role / Owner权限模型中的成员、角色viewer/writer/admin、member/admin、以及专指路径前缀u/alice、f/team的 owner。避免participant、ACL entry、permission level、access level。这两套词汇构成了技能输出的语言纪律领域部分用CONTEXT.md的词汇架构部分用codebase-design的词汇。例如应说Order 摄入模块而不是FooBarHandler或Order 服务。流程第一步Explore——先划定范围再扫描技能强调Scope before you scan——YAGNI。深化一个模块的回报在于让未来的变更更容易因此应当把更多权重放在最近经常变动的代码区域上。决定看哪里要先于怎么看用户指定方向则直接采纳如果用户点名了一个模块、子系统或痛点直接以其为准跳过下面的推断。否则回溯提交历史找热点用git log --oneline往回走一段足够长的提交历史找出反复出现的文件与区域hot spots让这些路径首先吸引你的注意力。如果变更散乱、没有明确热点就扩大搜索范围。先读领域术语表技能明确要求先读CONTEXT.md该文件在 Windmill 仓库根目录确实存在内容即上文所述术语表。随后派一个子代理sub-agent去遍历代码库。技能特别叮嘱不要遵循僵硬的启发式规则要有机地探索并记录你感到摩擦friction的地方哪里理解一个概念需要在许多小模块之间来回跳跃哪些模块是浅的——接口几乎与实现一样复杂哪些纯函数仅仅为了可测试性被提取出来但真正的缺陷藏在它们的调用方式里缺乏局部性哪些紧耦合的模块跨接缝泄漏代码库的哪些部分未被测试或难以通过当前接口测试对任何怀疑是浅模块的东西立即应用删除测试删除它会集中复杂性还是只是移动复杂性会集中正是你要的信号。流程第二步把候选呈现为 HTML 报告输出位置与打开方式技能要求把报告写成自包含的单个 HTML 文件写入操作系统临时目录绝不能落进仓库。临时目录从$TMPDIR解析回退到/tmpWindows 为%TEMP%文件命名为tmpdir/architecture-review-timestamp.html保证每次运行都有新文件。随后为用户打开报告Linuxxdg-open pathmacOSopen pathWindowsstart path并明确告知用户绝对路径。渲染技术栈报告用TailwindCDN做布局与样式用MermaidCDN绘制能够可靠传达结构的图/流程/序列。技能强调混搭而非全盘 Mermaid关系是图状的调用图、依赖、序列→ 用 Mermaid需要更编辑化的视觉质量图、剖面图、折叠动画→ 用手工构建的 div/SVG。每个候选都必须有before/after 可视化整体风格要求可视化优先Be visual。完整脚手架规范见仓库文件.agents/skills/improve-codebase-architecture/HTML-REPORT.md其骨架结构如下!doctype html html langen head meta charsetutf-8 / titleArchitecture review — {{repo name}}/title script srchttps://cdn.tailwindcss.com/script 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 /* 小规模自定义层虚线接缝线、手绘感的箭头等 */ .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头部区包含仓库名、日期和一个紧凑图例实线框 模块虚线 接缝红色箭头 泄漏加粗深色框 深模块。不写引言段直接进入候选卡片。候选卡片Candidate card每个候选是一个article图表承担主要表达任务散文稀疏、平实且严格使用术语表中的词汇。卡片包含Title标题——简短直接命名深化动作例如 Collapse the Order intake pipeline折叠 Order 摄入流水线Badge row徽章行——推荐强度徽章Strong用 emerald 绿、Worth exploring用 amber 琥珀、Speculative用 slate 灰外加一个依赖类别标签in-process、local-substitutable、ports adapters、mockFiles涉及文件——等宽字体、font-mono text-sm的列表Problem问题——一句话当前架构为何造成摩擦Solution方案——一句话会改变什么Wins收益——用≤6 词的要点表述例如 Tests hit one interface、Pricing logic stops leaking、Delete 4 shallow wrappersBefore / After diagram前后对比图——两栏并排的核心展示。技能明确要求如果图需要一段文字才能被理解就重画这张图。报告不写解释性段落问题、方案、收益都要压缩成一句话/要点。五种图表模式.agents/skills/improve-codebase-architecture/HTML-REPORT.md给出了五种可混搭的图表模式刻意让每张图不雷同Mermaid graph依赖/调用流的主力当要表达X 调 Y、Y 调 Z看看这乱象时用flowchart/graph用classDef把泄漏边染红、深模块染深色序列图适合表达改前 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手工盒子与箭头当 Mermaid 布局不配合时模块用带边框和标签的div箭头用绝对定位的 SVGline/path。适合after图想呈现一个厚边框深模块、内部变灰的感觉——Mermaid 无法渲染出这种重量感。剖面图Cross-section适合层叠浅度用水平色带h-12 border-l-4堆叠表示一次调用穿过的层次改前 6 条细层各无所事事改后 1 条粗带标注整合后的职责。质量图Mass diagram适合接口与实现等宽每个模块画两个矩形——接口表面积与实现面积。改前接口矩形几乎与实现矩形同高浅改后接口矩形矮、实现矩形高深。调用图折叠Call-graph collapse改前是嵌套盒子组成的函数调用树改后整棵树折叠进一个盒子如今内部化的调用在盒内以淡色显示。风格规范与语气纪律编辑风格而非仪表盘风格慷慨留白标题可选衬线字体font-serif配 stone/slate 色系。克制用色一种强调色emerald 或 indigo 红色表泄漏 琥珀色表警告。图高约 320px保证 before/after 并排不滚动。图内模块标签用text-xs uppercase tracking-wider——它们应读作示意schematic而非 UI。报告中唯一的脚本是 Tailwind CDN 与 Mermaid ESM import其余完全静态。语气纪律Tone是全文档最严格的约束精确使用module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality绝不替换为component、service、unit指 moduleAPI、signature指 interfaceboundary指 seamlayer、wrapper指 module符合风格的措辞Order 摄入模块很浅——接口几乎与实现匹配、Pricing 跨接缝泄漏、深化一个接口、一处测试、两个适配器为接缝正名生产环境 HTTP、测试环境内存Wins 要点用术语命名收益locality缺陷集中于一个模块、leverage一个接口、N 个调用点、接口收缩实现吸收包装器。不要写更易维护更干净的代码——这些词不在术语表里不配出现不兜圈子、不铺垫能写成要点的就写要点能删的就删遇到术语表没有的词先找表内的词再说。报告收尾Top recommendation报告以Top recommendation首要推荐结束一张更大的卡片写清首选哪个候选、为什么并附上指向该候选卡片的锚点链接。仅此而已。技能还规定此时不要提出接口方案。写完文件后向用户提问你想深入探索哪一个流程第三步Grilling loop——持续追问直到共识用户选定候选后运行/grilling技能.agents/skills/grilling/SKILL.md与其一起走决策树——约束、依赖、深化后的模块形态、接缝后面是什么、哪些测试能存活。grilling技能把对话建模为设计树design tree每个决策都会分支出一系列依赖它的决策。按**轮次rounds**推进前沿frontier是前提已全部确定、现在就能问的决策集合——每轮把整个前沿一次问完逐条编号并给出推荐答案等用户答完再进入下一轮。每问格式化如下❓ **Q1** - **question title**: question body, might be multiple paragraphs, including multiple choices ➡️ your recommended answer关键分工是找事实是你的工作不是用户的。当某个前沿问题需要环境事实文件系统、工具等时派子代理去查绝不把你自己能查到的东西抛给用户也不阻塞等待——正在进行的探索是一个未定前提只有下游问题才等它其余前沿现在就先问。决策属于用户逐个摆给用户并等待。当前沿为空决策树每条分支都访问过、没有东西被静默假设且用户确认达成共识后本次会话才结束。在决策结晶的过程中副作用会内联发生——运行/domain-modeling技能.agents/skills/domain-modeling/SKILL.md让领域模型保持最新给深化后的模块取了一个CONTEXT.md中没有的概念名把该术语加入CONTEXT.md文件不存在则惰性创建。对话中把模糊术语变清晰了就地更新CONTEXT.md。想为深化模块探索替代接口运行/codebase-design技能使用其 design-it-twice 并行子代理模式。配套能力一Deepening——依赖分类决定测试策略.agents/skills/codebase-design/DEEPENING.md给出了在已知依赖的情况下安全深化一组浅模块的方法。评估深化候选时先把其依赖分类类别决定了深化后的模块如何跨接缝测试依赖类别定义深化策略1. In-process进程内纯计算、内存状态、无 I/O总是可深化——合并模块直接通过新接口测试无需适配器2. Local-substitutable本地可替换有本地测试替身的依赖Postgres 用 PGLite、内存文件系统替身存在即可深化深化模块用测试套件内的替身测试接缝是内部的外部接口无端口3. Remote but owned远程但自有Ports Adapters跨网络边界的自有服务微服务、内部 API在接缝处定义端口port深模块拥有逻辑传输层作为适配器注入测试用内存适配器生产用 HTTP/gRPC/队列适配器4. True external真外部Mock不受你控制的第三方服务Stripe、Twilio 等深化模块把外部依赖作为注入的端口测试提供 mock 适配器技能给出了推荐句式在接缝处定义端口为生产环境实现 HTTP 适配器、为测试实现内存适配器这样逻辑即使跨网络部署也位于一个深模块内。**接缝纪律Seam discipline**两条铁律一个适配器意味着假设的接缝两个适配器才意味着真实的接缝除非至少有两个适配器站得住脚通常是生产 测试否则不要引入端口——单适配器接缝只是间接层内部接缝 vs 外部接缝深模块可以有内部接缝私有于实现、供自身测试使用以及接口处的外部接缝不要因为测试要用内部接缝就把它暴露到接口上。测试策略替换而非叠加replace, dont layer一旦深化模块接口处的测试存在浅模块上的旧单元测试就成了废品——删除它们在深化模块的接口处编写新测试接口即测试面测试断言接口处的可观察结果而非内部状态测试应能挺过内部重构——它们描述行为而非实现。如果实现变了测试就得改说明测试越过了接口。配套能力二Design It Twice——为接口并行设计多种方案/codebase-design技能还包含 design-it-twice 并行子代理模式见.agents/skills/codebase-design/DESIGN-IT-TWICE.md。基于 Ousterhout 的Design It Twice——你的第一个想法不太可能最好。流程分三步界定问题空间先给用户写一份面向问题的解释——新接口必须满足的约束、依赖及其类别、一个粗略的示意代码草图不是提案只是让约束具体化。展示后立即进入第二步用户在子代理并行工作时阅读思考。并行派发 3 个子代理每个都要产出截然不同的接口方案并各自领到不同的设计约束Agent 1最小化接口——最多 1–3 个入口最大化每个入口的杠杆。Agent 2最大化灵活性——支持更多用例与扩展。Agent 3为最常见的调用方优化——让默认场景变得琐碎。Agent 4如有围绕跨接缝依赖的端口与适配器设计。每个子代理的简报都要同时包含codebase-design词汇与CONTEXT.md词汇输出接口类型、方法、参数 不变量、顺序、错误模式、调用方用法示例、实现藏在接缝后面的内容、依赖策略与适配器、权衡杠杆高在哪、薄在哪。顺序呈现并对比逐个呈现让用户消化然后用散文对比——按深度接口处杠杆、局部性变更集中在哪、接缝位置三个维度。最后给出你自己的推荐哪个方案最强、为什么若不同方案元素可组合提出混合方案。技能要求要有观点——用户要的是强判断不是一份菜单。配套能力三Domain Modeling——让领域模型保持鲜活/domain-modeling技能.agents/skills/domain-modeling/SKILL.md是主动纪律——挑战术语、发明边界场景、在术语定型的瞬间写下词汇表与决策。仅读CONTEXT.md取词不算此技能它用于改变模型时。文件结构多数仓库是单一上下文——根目录一个CONTEXT.md加src/若根目录存在CONTEXT-MAP.md则是多上下文仓库映射表指出每个上下文的位置。文件惰性创建——只有有内容可写时才建。会话期间要持续与词汇表冲突立即指出、模糊术语给精确规范词、用具体场景压力测试领域关系、与代码交叉验证你的代码取消整个 Order但你刚说支持部分取消——哪个对、术语一解决就内联更新CONTEXT.md。CONTEXT.md的格式规范见.agents/skills/domain-modeling/CONTEXT-FORMAT.md# {Context Name} {一到两句描述该上下文是什么、为何存在} ## Language **Order**: {一到两句描述} _Avoid_: Purchase, transaction **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account四条规则要有观点同一概念有多个词时挑最好的其余列进_Avoid_定义要紧凑最多一两句定义是什么而非做什么只收本项目特有的术语通用编程概念超时、错误类型、工具模式不属于即使项目大量使用收词前自问这是本上下文独有的概念还是通用编程概念自然聚类时按子标题分组若所有术语属于单一内聚领域平铺列表即可。同时CONTEXT.md必须完全不含实现细节——它不是规格书、不是草稿本、不是实现决策的仓库只是一份词汇表。技能依赖全景improve-codebase-architecture不是孤立的它与.agents技能体系中的其他技能形成依赖网全部文件均位于仓库.agents/skills/目录下技能/文档路径在本工作流中的角色improve-codebase-architecture.agents/skills/improve-codebase-architecture/SKILL.md主流程扫描 → 报告 → 追问HTML 报告规范.agents/skills/improve-codebase-architecture/HTML-REPORT.md报告脚手架、图表模式、风格与语气纪律codebase-design.agents/skills/codebase-design/SKILL.md架构术语表与深度原则Deepening.agents/skills/codebase-design/DEEPENING.md依赖分类、接缝纪律、替换式测试策略Design It Twice.agents/skills/codebase-design/DESIGN-IT-TWICE.md替代接口的并行设计方案grilling.agents/skills/grilling/SKILL.md设计树式持续追问domain-modeling.agents/skills/domain-modeling/SKILL.md领域术语的内联维护CONTEXT 格式.agents/skills/domain-modeling/CONTEXT-FORMAT.mdCONTEXT.md词汇表格式规范领域术语表CONTEXT.mdWindmill 领域语言Step、Trigger step、Member、Role 等在 Windmill 这个具体仓库中这套技能体系与工程实践相互印证仓库既有 Rust 后端的windmill-*系列 crate如windmill-common、windmill-queue、windmill-api也有 Svelte 前端的frontend/src与 TypeScript CLI 的cli/src以及ai_evals/评估套件——模块化程度高、模块数量多正是找浅模块、定接缝、做深化的理想试验场。技能文档中的抽象原则删除测试、接口即测试面、一个/两个适配器可以逐一映射到这些真实模块的耦合与测试边界上。总结一次架构深化的完整闭环把整条工作流串起来看improve-codebase-architecture提供的是一次由人掌控节奏、由 Agent 承担侦查与呈现的架构重构闭环Explore按热点划定范围 → 读CONTEXT.md→ 派子代理有机遍历记录摩擦点 → 对嫌疑浅模块做删除测试Present生成写入临时目录的自包含 HTML 报告Tailwind Mermaid前后对比图 推荐强度徽章 Top recommendation→ 问用户选哪个此时不提出接口Grill/grilling以设计树、前沿、轮次的方式把决策逐一定型事实由子代理代查、决策留给用户 → 决策结晶时用/domain-modeling内联更新CONTEXT.md→ 需要探索替代接口时走 design-it-twice 并行子代理模式Verify按DEEPENING.md的依赖分类决定测试策略遵循替换而非叠加删掉浅模块旧测试、在深化后的接口处写新测试让测试在内部重构中存活。这套方法论的可迁移性正在于其词汇纪律与原则的与语言无关无论目标代码库是 Rust、TypeScript 还是 Svelte只要坚持 module/interface/depth/seam/adapter/leverage/locality 这一套精确语言坚持接口即测试面与一个适配器是假设、两个才是真实架构讨论就能避免语义漂移重构建议就能落到可测试、可导航的实处。【免费下载链接】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），仅供参考