SuperAPI AI 工具集

understand

编程与开发

查看项目

更新于 11-10 16:20

技能介绍

用途

Understand(/understand)用于分析代码库,产出 knowledge-graph.json 知识图谱文件,放在项目数据目录(.ua/,若已存在旧版 .understand-anything/ 则沿用),以此驱动交互式看板,帮助理解项目架构、组件以及它们之间的关系。

主要能力

  • 全量分析:从预检、文件分析到架构与导览生成的多阶段流程(文档中出现 7 个阶段的分段进度提示)。
  • 增量更新:借助 prepare-incremental.mjs 依据上次分析的 commit 计算变更文件,按 SKIP、PARTIAL_UPDATE、ARCHITECTURE_UPDATE、FULL_UPDATE 四种动作决定后续流程;必要时重跑架构与导览阶段。
  • 自动更新开关:--auto-update / --no-auto-update 写入 $UA_DIR/config.json 的 autoUpdate 字段。
  • 图谱审查:--review 调用 LLM graph-reviewer 做完整审查,而非内联确定性校验。
  • 输出语言:--language 支持 ISO 639-1 代码或语言名称(如 zh、ja、en、chinese 等),支持 zh-TW 等区域变体,默认 en,并持久化到 config.json。
  • 排除规则:--exclude 接受逗号分隔的 glob,优先级高于内置默认与 .understandignore,支持 gitignore 语法与 ! 取反。
  • 指定目录:参数中可出现一个非 flag 的目录路径,替代当前工作目录。
  • 子域图谱合并:合并 $UA_DIR 下除 knowledge-graph.json 之外的 knowledge-graph.json 文件。
  • git worktree 处理:检测到 worktree 时将输出重定向到主仓库根目录(可用 UNDERSTAND_NO_WORKTREE_REDIRECT=1 关闭重定向)。

使用方式

典型用法是调用 /understand,可附加参数,例如:

  • /understand --full
  • /understand --review --language zh
  • /understand --exclude "tests/,docs/"
  • /understand /path/to/repo

运行时依赖 Node.js ≥ 22 与 pnpm ≥ 10;若缺少 pnpm 会提示安装后重跑。首次使用会解析插件根目录,并在 packages/core/dist/index.js 不存在时执行 pnpm install 与 pnpm --filter @understand-anything/core build。产物目录包括 $UA_DIR/intermediate 与 $UA_DIR/tmp,超过 7 天的 .trash-* 目录会被清理。

适用场景

适合需要快速建立项目架构全景、跟踪代码结构变化、并用可视化图谱辅助新人上手或架构评审的仓库;也适合对既有图谱做局部增量刷新,避免每次全量重算。

限制

文档未给出具体收费、平台支持范围与效果指标,这些事实暂未提供。分析耗时随代码库规模增长,文档为此提供分批进度提示;增量流程仅将具有结构性变化且当前未被忽略的文件交给 file-analyzer,删除、新忽略、纯外观变更与生成产物不会进入重分析。