uw-build-layer 是 nearform/unwind 体系中的一个构建执行器技能,由 unwind:uw-build 调度,角色是“按切片构建器”。它的任务是在目标技术栈中重建源系统的某一个切片(一个层,或某层的一个阶段),在目标仓库中产出真实代码,并生成映射文件供编排器衡量完整度。
用途方面,该技能用于代码库迁移/重建流程中的执行环节:接收编排器下发的切片信息,包括 sliceId、targetRoot(重建代码所在位置)、目标技术栈决策(语言、框架、数据存储、ORM 等,来自 REBUILD-PLAN.md / rebuild-decisions.json)、切片的候选清单(种子项,即 [MUST] 列表,每项含 sourceId、kind、name、源位置/链接)、该切片所属的层,以及 docs/unwind/layers/** 下该层的规格文档路径。
主要能力方面,技能强调功能等价而非逐字移植,[MUST] 条目不可违背,必须记录每个映射,绝不静默跳过。它要求先阅读规格与层文档(含 [MUST]、[SHOULD]、[DON'T] 条目及详情),必要时查阅其链接的源文件;文档是判断哪些内容重要的权威依据,源码仅作参考。然后按目标技术栈的惯用方式(其文件夹/命名约定,不照搬源码树)为每个 [MUST](以及干净的 [SHOULD])创建目标等价实现,跳过 [DON'T] 条目(仅当行为仍然需要时构建惯用等价物)。
使用方式方面,技能要求将映射文件写入 <sourceRepo>/docs/unwind/.cache/rebuild-map/<sliceId>.json,使用种子中逐字给出的 sourceId,并针对实际写出的文件计算 targetIds(kind:<target-path>:<name>,路径相对 targetRoot),不得把条目映射到未写出的代码。完成后需报告简短摘要:构建了什么、有意省略了什么及原因、本切片无法构建的 [MUST] 条目(留作未映射,以便如实暴露为缺口)。技能本身不运行扫描或校验器,由编排器在返回后扫描目标并运行 verify-rebuild.mjs。
它还规定了按层保留的契约:database 层保留每个表/实体、字段类型/可空性/默认值、关系(外键、删除行为)、编码规则的唯一性/索引、作为契约的物理表/列名,而 ORM/库、迁移工具、查询语法可变;domain 层保留实体形状、值对象、枚举、不变量/校验规则、关系,类/结构体/记录与语言习惯可变;service 层保留业务规则、公式、边界情况、顺序/事务边界、影响行为的硬编码常量,内部分解、依赖注入风格、辅助结构可变;api 层保留 HTTP 方法+路径(参数可重命名不可删除)、状态码、请求/响应体结构、各路由鉴权要求、错误契约,框架、路由风格、中间件机制可变;messaging 层保留事件/消息名称+负载模式、主题/队列语义、投递保证、消费者幂等规则,代理/库、序列化细节可变;frontend 层保留面向用户行为、所消费的数据契约(与 API 一致)、作为产品一部分的路由/视图,组件框架、样式、状态管理可变;tests 层保留所断言的内容(行为保证),测试需可在目标上运行以兼作等价性向量,测试框架、断言库可变;infrastructure 层保留构建/部署目标、运行时配置键、入口点/引导行为、环境契约,工具、IaC 语法、打包可变。特别对于 api 和 database,校验器会对目标进行确定性比对(端点方法+路径;表+字段名),逻辑上精确才能获得“等价”而非仅“存在”。
适用场景为 unwind 驱动的分层代码重建与迁移工作。限制包括:需要由 unwind:uw-build 调度并在其流程内运行;未提供种子清单时可仅依据层文档工作,但完整度只能按判断说明;无法构建的 [MUST] 条目应留作未映射缺口;不自行运行扫描或验证器。