用途
uw-scan 用于在开始逆向工程一个陌生代码库时,先识别其分层、模式与结构,再进入详细分析。它是 Unwind 流水线的第一阶段(scan → analyze → grill → plan → dashboard)。
主要能力
- 确定性扫描:运行 @unwind/core 扫描器,生成 machine-readable 的 scan-manifest.json,作为文件清单、每文件结构符号、导入图和初版重建分层分配的“事实基准”。
- 架构推导:架构文档由清单派生,因此层数与入口点可验证而非猜测。
- 辅助裁决:子代理负责处理扫描器无法分类的文件(unassigned 桶),逐项归入真实层,或确认其确实为横切/非层内容,并为每一层补充技术、模式等叙述性观察。
- 刷新模式:若已存在 architecture.md,则对比新旧代码库状态,标注变化、更新层状态与置信度、增删入口点、更新分析时间戳。
- 优雅回退:当 Node/pnpm 或 @unwind/core 不可用时,跳过确定性扫描,回退到纯 LLM 的 Explore 流程(步骤 1-LEGACY)。该技能始终可用,扫描只是增强项而非硬依赖。
输出
docs/unwind/architecture.md(派生文档)docs/unwind/.cache/scan-manifest.json(事实基准)
使用方式
- 步骤 0:构建并运行扫描器。脚本会定位已安装的 Unwind 插件根目录并懒构建 @unwind/core:
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 discovery"; }
node "$UNWIND_PLUGIN_ROOT/skills/scripts/scan.mjs" "$(pwd)"
成功则写入 scan-manifest.json 并进入步骤 1;非零退出则跳到步骤 1-LEGACY。
-
步骤 1:读取清单,派发 Explore 子代理完成裁决、叙述观察、确认/修正层边界,返回架构文档内容,由主代理写入。扫描器层级映射:database→database、domain→domain_model、service→service_layer、api→api、messaging→messaging、frontend→frontend;测试与基础设施记录在各自小节。
-
步骤 1-LEGACY(仅回退时):通过 git remote get-url origin 与 git branch --show-current 收集仓库信息,解析 SSH/HTTPS 远程地址生成 repository 块,再派发子代理从头发现分层。
-
步骤 2:检查 docs/unwind/architecture.md 是否存在,存在则作为“先前分析”传入刷新模式。
-
步骤 3:创建输出目录并写入文档:
mkdir -p docs/unwind
- 步骤 5:向用户展示结果摘要与检测到的层及置信度,并让用户选择:立即打开仪表盘(推荐,调用 unwind:uw-dashboard)、继续分层分析(调用 unwind:uw-analyze)、或先审阅架构文档。
适用场景
- 开始在陌生代码库上工作
- 新项目上手
- 规划迁移或大规模重构之前
- 开始安全审计或代码审查
限制
- 确定性扫描依赖 Node/pnpm 与 @unwind/core;不可用时降级为纯 LLM 探索,此时代码库层面的事实基准缺失,层识别依赖模型推断。
- 扫描器无法归类的文件需人工/子代理裁决。
- 架构文档驱动后续全部分析,因此建议用户在继续前先审阅其准确性。
- 文档中另有定价、平台支持范围等信息暂未提供。