用途
uw-refresh 用于在长时间迁移过程中保持 Unwind 文档和 rebuild-graph.json 的最新状态,而不必每次都重新对全部代码执行 unwind。其核心思路是增量更新:确定性扫描会为每个文件生成指纹,刷新时只重新分析源文件实际发生变更的层,并将此前已记录、但源文件发生结构性变更的条目标记为过期。
主要能力
- 变更检测:对比基线生成 docs/unwind/.cache/changes.json,区分结构性变更、新增、删除、纯格式性变更(仅正文或注释改动,文档仍然有效、无需重新分析),并给出需要重新分析的 affectedLayers、需要重新确认的 staleItems 以及新增文件的 newItems。
- 刷新基线扫描:重新运行扫描以刷新 scan-manifest.json 与 meta.json 基线,使条目 id 与当前代码一致。
- 仅重新分析受影响层:对 affectedLayers 中的每个层,派发对应的 unwind:analyzing-* 专家,并以 seeds 文件和现有层文档作为上下文,要求其记录新增条目、重新确认过期条目、删除已不存在文件的文档;不影响未受影响的层。
- 验证与重建图:运行覆盖验证(循环验证直到受影响层达到 100%),重新生成 rebuild-graph.json;将仍被记录但已变更的节点标记为 coverage: "stale",将结构性变更的 done/verified 契约改为 rebuildStatus: "needs-recheck"。
- 复查 grill 发现:若存在 grill-findings.json,则对 contentHash 已不匹配当前清单的发现标记 stale;仍未解决的从 docs/unwind/questions/ 问卷中移除其区块;已回答的保留结论但记录漂移;必要时重新运行 /uw-grill。
- 优雅降级:若 @unwind/core/Node/pnpm 不可用,则跳过确定性步骤,回退到旧版 unwind:uw-analyze Refresh Mode(以之前的文档为上下文重新运行专家)。
使用方式
前置要求:必须先有一次完整运行,存在 docs/unwind/.cache/meta.json 基线、层文档与 coverage/。
主要步骤:
- 检测变更(在重新扫描之前运行,以保证基线仍反映上次分析状态):
UNWIND_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${UNWIND_PLUGIN_ROOT:-}}"
[ -f "$UNWIND_PLUGIN_ROOT/skills/scripts/_resolve-plugin-root.sh" ] || \
UNWIND_PLUGIN_ROOT="$(ls -dt "$HOME"/.claude/plugins/cache/*/unwind/*/ 2>/dev/null | head -1)"
source "${UNWIND_PLUGIN_ROOT%/}/skills/scripts/_resolve-plugin-root.sh"
ensure_unwind_core || { echo "core unavailable — using legacy refresh"; }
node "$UNWIND_PLUGIN_ROOT/skills/scripts/detect-changes.mjs" "$(pwd)"
若 structural、added、removed 均为空,则无需继续。
- 刷新基线扫描:
node "$UNWIND_PLUGIN_ROOT/skills/scripts/scan.mjs" "$(pwd)"
node "$UNWIND_PLUGIN_ROOT/skills/scripts/seed-layers.mjs" "$(pwd)"
-
仅对 affectedLayers 中的层派发对应 unwind:analyzing-* 专家。
-
验证并重建图:
node "$UNWIND_PLUGIN_ROOT/skills/scripts/verify-coverage.mjs" "$(pwd)"
node "$UNWIND_PLUGIN_ROOT/skills/scripts/build-graph.mjs" "$(pwd)"
4b. 若存在 grill 发现,检查哈希是否漂移并相应处理:
ls docs/unwind/.cache/grill-findings.json >/dev/null 2>&1 && echo "grill findings exist"
- 汇报:重新分析的层、新增/删除条目、解决的过期条目、新的覆盖率,并指向 docs/unwind/rebuild-graph.json。
适用场景
适用于长期迁移项目中代码持续变更、希望 Unwind 文档随代码演进而保持有效、且不希望每次都对全库重新运行专家分析的场景。
限制
需要先有一次完整运行作为基线;确定性步骤依赖 @unwind/core、Node 与 pnpm,缺失时会回退到旧版 Refresh Mode;具体 CLI 参数细节与收费信息暂未提供。