uw-build 用于在 Unwind 流程中执行代码重建。它接收 uw-plan 产出的重建计划,将规范文档转化为目标技术栈中的实际代码,并通过重新扫描目标仓库、与源图谱进行前后对比来量化完整性。
用途
该技能在规划完成后调用,负责执行重建。它根据层文档和 REBUILD-PLAN.md 在选定的目标仓库中生成代码,并测量有多少源节点被忠实迁移。与仅依赖模型声称的方式不同,完整性通过重新扫描目标仓库并与源图谱做差异对比来验证。
前置条件
运行前需要已完成的计划文件:docs/unwind/REBUILD-PLAN.md、docs/unwind/.cache/rebuild-decisions.json、docs/unwind/rebuild-graph.json 以及 docs/unwind/layers/** 下的层文档。需要先运行 uw-plan 和 uw-graph/uw-dashboard。
主要产出
- 目标仓库中的目标技术栈代码(通过构建子代理生成)
- docs/unwind/.cache/rebuild-state.json:持久化重建账本,支持恢复与循环
- docs/unwind/.cache/rebuild-map/<sliceId>.json:每个切片的源到目标映射
- docs/unwind/.cache/rebuild-progress.json:仪表盘渲染的进度覆盖层
- docs/unwind/rebuild-verification-graph.json 与 docs/unwind/rebuild-gaps.md:验证图谱与缺口报告
使用方式
执行分为几个阶段。阶段 A 读取计划:定位已安装的 Unwind 插件并加载核心辅助脚本,然后读取重建计划、决策文件、重建图谱和层文档,按依赖顺序派生切片列表(数据库 → 领域 → 服务 → API → 消息 → 前端 → 测试 → 基础设施)。
阶段 B 是构建访谈:只询问计划未回答的新决策,如范围(单切片/单阶段/整体重建)、目标输出位置、验证深度(结构+契约差异 / 加入目标测试运行)、执行模式(逐步推进/循环直到验证通过)、首个切片,以及若已有状态文件则选择恢复或重启。若目标语言不在 tree-sitter 契约提取支持范围内(TypeScript/JavaScript、Python、Rust、Java、C#),会提示验证仅能到文件粒度。之后初始化状态账本 rebuild-state.json。
阶段 C 是构建循环:对每个切片,先读取种子文件并调度通用构建子代理使用 unwind:uw-build-layer 执行重建,粘贴已确定的技术栈、种子、层和规范路径;然后运行 merge-rebuild-map.mjs 合并映射并派生进度,运行 verify-rebuild.mjs 在隔离目录中重新扫描目标、写入验证图谱和缺口报告、提升节点状态并打印完整性百分比;接着执行内层缺口闭合循环,若该切片的 [MUST] 完整性低于目标且上一轮有进展,则重新调度构建代理针对缺口修复,直到达标或无进展;最后根据模式推进。
循环模式
可在 /loop 技能下自定节奏运行 /loop /uw-build。每次迭代处理一个范围内切片,读取验证图谱中的完整性百分比,更新 loopState;若百分比未提升则 dryRounds 递增,否则重置。当完整性达到目标(默认 100% 范围内 [MUST])、dryRounds 达到 2(卡住需升级给用户)、或出现错误/计划未回答的新决策时停止循环。
适用场景
适用于在目标技术栈中重建已有系统,需要按层逐步迁移并量化完整性、记录源到目标映射、追踪缺口、支持断点恢复与循环迭代的场景。
限制
若没有 @unwind/core(无 Node/pnpm/core),构建代理仍可从文档运行并以纯 JSON 记录状态,但没有验证图谱,完整性仅由 LLM 声称,需明确说明。验证深度中的 run-tests 需要重建后的应用可运行。目标语言不在 tree-sitter 支持列表时,验证仅能检查文件存在性而非契约差异。结构存在不等于行为正确;行为等价需使用 run-tests 深度或项目的等价向量。重启操作需明确确认,且仅删除指定状态文件,不得在未询问时改动目标代码。