understand-domain

/understand-domain

从代码库中提取业务领域知识——领域、业务流和流程步骤——并在仪表板中生成交互式水平流程图。

工作原理

• 如果已存在知识图谱（.ua/knowledge-graph.json，或者在 .understand-anything/ 目录存在时使用旧路径 .understand-anything/knowledge-graph.json），则从中提取领域知识（成本低，不扫描文件）
• 如果不存在知识图谱，则进行轻量扫描：文件树 + 入口点检测 + 抽样文件
• 使用 --full 标志可强制重新扫描，即使知识图谱已存在

说明

阶段 0：确定 PROJECT_ROOT

将 PROJECT_ROOT 设置为当前工作目录。

工作树重定向。 如果 PROJECT_ROOT 位于 Git 工作树中（而非主检出目录），则将输出重定向到主仓库根目录。由 Claude Code 管理的工作树是临时的——写入其中的数据目录（.ua/ 或旧版 .understand-anything/）会在会话结束时被销毁，领域图也会随之丢失（问题 #133）。通过比较 git rev-parse --git-dir 和 git rev-parse --git-common-dir 来检测工作树；在普通检出目录或子模块中，它们会解析为同一路径；在工作树中则不同，且 --git-common-dir 的父目录就是主仓库根目录。

COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
  COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
  GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
  if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
    MAIN_ROOT=$(dirname "$COMMON_ABS")
    if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
      echo "[understand-domain] Detected git worktree at $PROJECT_ROOT"
      echo "[understand-domain] Redirecting output to main repo root: $MAIN_ROOT"
      echo "[understand-domain] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

在后续阶段中，凡是提及“当前项目”或 <project-root>，都使用 $PROJECT_ROOT（不要直接使用 CWD）。

确定数据目录 $UA_DIR。 所有 Understand-Anything 产物都存放在项目的数据目录中。现在确定 $PROJECT_ROOT 后，立即确定一次该目录，并在后续阶段的所有读取和写入操作中复用 $UA_DIR：

UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"

这样，在 .understand-anything/ 目录已存在时会保留该旧目录（现有项目无需迁移即可继续使用），否则使用新的 .ua/。由于每个阶段都可能在新的 Shell 中运行，因此像传递 $PROJECT_ROOT 一样传递 $UA_DIR；如果后续命令块需要，可以使用上面的命令重新确定它。

重要： 不要假设插件根目录就是技能路径字符串向上两级的目录。在许多安装中，~/.agents/skills/understand-domain 是指向实际插件检出目录的符号链接。请优先使用运行时提供的插件根目录（对于 Claude），然后再依次查找通用符号链接、技能符号链接解析结果，以及常见的基于克隆的安装路径。

按如下方式确定插件根目录：

SKILL_REAL=$(realpath ~/.agents/skills/understand-domain 2>/dev/null || readlink -f ~/.agents/skills/understand-domain 2>/dev/null || echo "")
SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand-domain 2>/dev/null || readlink -f ~/.copilot/skills/understand-domain 2>/dev/null || echo "")
COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")

PLUGIN_ROOT=""
for candidate in \
  "${CLAUDE_PLUGIN_ROOT}" \
  "$HOME/.understand-anything-plugin" \
  "$SELF_RELATIVE" \
  "$COPILOT_SELF_RELATIVE" \
  "$HOME/.codex/understand-anything/understand-anything-plugin" \
  "$HOME/.opencode/understand-anything/understand-anything-plugin" \
  "$HOME/.pi/understand-anything/understand-anything-plugin" \
  "$HOME/understand-anything/understand-anything-plugin"; do
  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
    PLUGIN_ROOT="$candidate"
    break
  fi
done

if [ -z "$PLUGIN_ROOT" ]; then
  echo "Error: Cannot find the understand-anything plugin root."
  echo "Checked:"
  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
  echo "  - $HOME/.understand-anything-plugin"
  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand-domain>}"
  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand-domain>}"
  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
  echo "  - $HOME/understand-anything/understand-anything-plugin"
  echo "Make sure the plugin is installed correctly."
  exit 1
fi

在后续阶段中，凡是引用 Agent 定义，都使用 $PLUGIN_ROOT。

阶段 1：检测现有图谱

1. 检查 $UA_DIR/knowledge-graph.json 是否存在
2. 如果存在且未传入 --full，则在基于它推导之前检查新鲜度：
   • 将 project.gitCommitHash 从图谱元数据中读取为 GRAPH_COMMIT_RAW。切换到 $PROJECT_ROOT，先将其解析为提交，再用于任何 Git 差异检查；将解析出的提交与 git rev-parse HEAD 进行比较，并检查项目范围内已提交的更改和工作树更改：

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • 必须使用 -- . 路径规格：只更改同一单体仓库中其他项目的提交不能使此图谱过时。仅哈希不匹配并不表示图谱过时；如果项目差异为空，则图谱并未过时。
   • 在每条命令的输出中忽略所选数据目录（.ua/ 或旧版 .understand-anything/），因为其中包含生成的图谱产物，而非项目源代码变更。
   • 如果已提交差异或任何工作树命令报告了项目文件，则警告领域提取可能遗漏了这些更改。建议：运行 /understand 以刷新知识图谱。
   • 仅当 GRAPH_COMMIT_RAW 成功解析时才运行提交差异检查。如果图谱提交或 Git 元数据缺失、无效或不可用，请给出简短的尽力而为警告并继续，不要阻塞流程。
3. 完成上述预检后，进入阶段 3（基于图谱推导）。
4. 否则，进入阶段 2（轻量扫描）。使用 --full 时，跳过此预检，因为该命令会执行全新扫描，而不是使用现有图谱。

阶段 2：轻量扫描（路径 1）

预处理脚本不会生成领域图谱，而是生成原始素材（文件树、入口点、导出项／导入项），这样领域分析 Agent 就能专注于实际的领域分析，而不必花费数十次工具调用来探索代码库。可以把它看作一份速查表：低成本的 Python 预处理 → 高成本的大模型获得精简、清晰的输入 → 以更低成本获得更好的结果。

1. 运行此技能附带的预处理脚本，并传入阶段 0 中的 $PROJECT_ROOT：

   python ./extract-domain-context.py "$PROJECT_ROOT"
   

   此操作会输出 $UA_DIR/intermediate/domain-context.json，其中包含：
   • 文件树（遵循 .gitignore）
   • 检测到的入口点（HTTP 路由、CLI 命令、事件处理程序、定时任务、导出的处理程序）
   • 文件签名（每个文件的导出项、导入项）
   • 每个入口点的代码片段（签名 + 前几行）
   • 项目元数据（package.json、README 等）
2. 将生成的 domain-context.json 作为阶段 4 的上下文读取
3. 进入阶段 4

阶段 3：基于现有图谱推导（路径 2）

1. 读取 $UA_DIR/knowledge-graph.json
2. 将图谱数据整理为结构化上下文：
   • 所有节点及其类型、名称、摘要和标签
   • 所有边及其类型（尤其是 calls、imports、contains）
   • 所有图层及其描述
   • 如有，包含导览步骤
3. 这是领域分析器的上下文——无需读取文件
4. 进入阶段 4

阶段 4：领域分析

1. 从 $PLUGIN_ROOT/agents/domain-analyzer.md 读取 domain-analyzer Agent 提示词
2. 调用一个子 Agent，传入 domain-analyzer 提示词以及阶段 2 或 3 中的上下文
3. 该 Agent 将输出写入 $UA_DIR/intermediate/domain-analysis.json

阶段 5：验证并保存

1. 读取领域分析输出
2. 使用标准图谱验证流程进行验证（架构现已支持 domain/flow/step 类型）
3. 如果验证失败，记录警告，但保存有效内容（容错处理）
4. 保存到 $UA_DIR/domain-graph.json
5. 清理 $UA_DIR/intermediate/domain-analysis.json 和 $UA_DIR/intermediate/domain-context.json

阶段 6：启动仪表板

1. 自动触发 /understand-dashboard，可视化领域图谱
2. 仪表板会检测 domain-graph.json，并默认显示领域视图