SuperAPI AI 工具集

uw-scan

编程与开发

查看项目

更新于 10-30 10:34

技能介绍

用途

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(事实基准)

使用方式

  1. 步骤 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. 步骤 1:读取清单,派发 Explore 子代理完成裁决、叙述观察、确认/修正层边界,返回架构文档内容,由主代理写入。扫描器层级映射:database→database、domain→domain_model、service→service_layer、api→api、messaging→messaging、frontend→frontend;测试与基础设施记录在各自小节。

  2. 步骤 1-LEGACY(仅回退时):通过 git remote get-url origin 与 git branch --show-current 收集仓库信息,解析 SSH/HTTPS 远程地址生成 repository 块,再派发子代理从头发现分层。

  3. 步骤 2:检查 docs/unwind/architecture.md 是否存在,存在则作为“先前分析”传入刷新模式。

  4. 步骤 3:创建输出目录并写入文档:

mkdir -p docs/unwind
  1. 步骤 5:向用户展示结果摘要与检测到的层及置信度,并让用户选择:立即打开仪表盘(推荐,调用 unwind:uw-dashboard)、继续分层分析(调用 unwind:uw-analyze)、或先审阅架构文档。

适用场景

  • 开始在陌生代码库上工作
  • 新项目上手
  • 规划迁移或大规模重构之前
  • 开始安全审计或代码审查

限制

  • 确定性扫描依赖 Node/pnpm 与 @unwind/core;不可用时降级为纯 LLM 探索,此时代码库层面的事实基准缺失,层识别依赖模型推断。
  • 扫描器无法归类的文件需人工/子代理裁决。
  • 架构文档驱动后续全部分析,因此建议用户在继续前先审阅其准确性。
  • 文档中另有定价、平台支持范围等信息暂未提供。