Understand-Anything /understand-domain 技能深度解析从代码库中自动提取业务领域知识并生成可交互流程图谱【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything在大型代码库中结构依赖图能回答“谁调用了谁”却回答不了“这段代码在做什么业务”。Understand-Anything 的/understand-domain技能正是为此设计它通过一个 Skill 工作流加一个轻量 Python 预处理器从代码库中提取业务领域Domain、业务流程Flow与流程步骤Step三级知识生成独立的domain-graph.json并在 Dashboard 中以横向领域流程图呈现。读完本文你可以完整掌握该技能的六阶段工作流、两条分析路径轻量扫描 / 从既有知识图谱派生、预处理器extract-domain-context.py的扫描策略与限额设计以及领域图谱的 JSON 结构与校验持久化机制。工作机制总览两条路径同一份输出/understand-domain的核心设计见 SKILL.md是“两条路径、同一产物”路径 2派生自既有知识图谱如果项目中已存在知识图谱.ua/knowledge-graph.json或当旧目录存在时的.understand-anything/knowledge-graph.json则直接从图谱中派生领域知识——节点、边、分层、Tour 已包含摘要与标签因此这一步几乎零成本不需要重新扫描任何源文件路径 1轻量扫描如果没有知识图谱则执行一次轻量扫描——文件树 入口点检测 抽样文件产出“原材料”交给 LLM 分析--full参数即使存在知识图谱也会强制走一次全新扫描。这套设计出自项目的设计文档 2026-04-01-business-domain-knowledge-design.md其动机是文件级依赖图的价值有限——导入关系在 IDE 里本来就可见真正稀缺的是内嵌在代码中的业务逻辑与领域概念。设计文档估算轻量扫描路径的 token 成本约为完整/understand扫描的 10%–20%。Phase 0解析 PROJECT_ROOT、UA_DIR 与插件根目录这是整个技能中最容易被忽视、却决定产物能否留存的一步。0.1 Worktree 重定向防止产物随临时工作区销毁当PROJECT_ROOT位于 git worktree而非主检出内时输出会被重定向到主仓库根目录。原因是由 Claude Code 管理的 worktree 是临时性的——会话结束后 worktree 被销毁写在其中的数据目录.ua/或旧版.understand-anything/连同领域图谱一起丢失。SKILL.md 给出的检测方法是对比git rev-parse --git-dir与git rev-parse --git-common-dir——在普通检出或子模块中两者解析到同一路径在 worktree 中两者不同且--git-common-dir的父目录即主仓库根。关键片段引自 SKILL.mdCOMMON_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 PROJECT_ROOT$MAIN_ROOT fi fi fi注意逃生阀设置环境变量UNDERSTAND_NO_WORKTREE_REDIRECT1可让输出保留在 worktree 中适合你明确知道会话产物无需长期保存的场景。0.2 数据目录$UA_DIR新旧目录并存策略所有 Understand-Anything 产物都放在项目数据目录中。解析规则是一行UA_DIR$PROJECT_ROOT/$([ -d $PROJECT_ROOT/.understand-anything ] echo .understand-anything || echo .ua)即若旧版.understand-anything/目录已存在则继续沿用老项目无需迁移否则使用新版.ua/。由于每个 Phase 可能运行在全新 shell 中$UA_DIR需要像$PROJECT_ROOT一样向后传递必要时用上面这行重新解析。0.3 插件根目录$PLUGIN_ROOT的多候选解析SKILL.md 明确警告不要假设插件根就是技能路径上两级父目录——在~/.agents/skills/understand-domain这类安装中它通常是指向真实插件检出的符号链接。正确的解析顺序是优先使用运行时注入的${CLAUDE_PLUGIN_ROOT}然后依次尝试~/.understand-anything-plugin、由~/.agents/skills/understand-domain真实路径上溯两级、由~/.copilot/skills/understand-domain上溯两级最后回退到 codex/opencode/pi 等常见的克隆安装路径。每个候选必须同时存在package.json和pnpm-workspace.yaml才被采纳全部落空则报错退出并打印所有已检查路径。$PLUGIN_ROOT在后续 Phase 中用于定位 agent 定义文件。Phase 1检测既有图谱与新鲜度检查流程是检查$UA_DIR/knowledge-graph.json是否存在若存在且未传--full先做新鲜度预检再决定从图谱派生从图谱元数据读取project.gitCommitHash记为GRAPH_COMMIT_RAW先git rev-parse --verify --end-of-options ${GRAPH_COMMIT_RAW}^{commit}将其解析为真实提交再与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 -- .-- .路径限定是必须的只触及 monorepo 中兄弟项目提交的 commit 不应让本项目的图谱变旧仅哈希不一致、而项目内 diff 为空不算过期。所有命令输出中都要忽略数据目录本身.ua/或.understand-anything/因为里面是生成产物而非源码漂移。若检测到项目文件变更提示“领域提取可能遗漏这些变更”并建议先运行/understand刷新知识图谱。提交 diff 仅在GRAPH_COMMIT_RAW成功解析时才执行图谱 commit 或 Git 元数据缺失/非法时只做尽力而为的警告并继续不阻塞流程。预检通过后进入 Phase 3从图谱派生否则进入 Phase 2轻量扫描。使用--full时跳过预检因为此时命令会执行全新扫描而不是消费既有图谱。Phase 2轻量扫描路径 1与 extract-domain-context.py 全解析SKILL.md 对这一步的定位非常明确预处理脚本不产生领域图谱它产出的是原材料——文件树、入口点、导出/导入——让 domain-analyzer agent 把宝贵的工具调用次数花在真正的领域分析上而不是花几十次调用探索代码库。设计文档将其概括为便宜的 Python 预处理 → 昂贵的 LLM 拿到干净的小输入 → 更低成本、更好结果。调用方式为python ./extract-domain-context.py $PROJECT_ROOT产物是$UA_DIR/intermediate/domain-context.json随后在 Phase 4 作为上下文使用。下面结合 extract-domain-context.py 的源码逐块解析。2.1 限额常量为 Agent 上下文预算设计的扫描器脚本头部的一组常量extract-domain-context.py#L29-L37定义了扫描的规模上限常量值作用MAX_FILE_TREE_DEPTH6文件树递归深度上限MAX_FILES_PER_DIR50单目录最多收录文件数MAX_FILES_TOTAL5000全局源文件上限MAX_SAMPLED_FILES40参与签名提取的抽样文件数MAX_LINES_PER_FILE80每文件读取行数上限MAX_ENTRY_POINTS200入口点数量上限MAX_OUTPUT_BYTES512 KB输出体积上限保证不超出 agent 上下文限制SOURCE_EXTENSIONS覆盖 25 种语言扩展名TS/JS、Python、Go、Rust、Java/Kotlin/Scala、Ruby、C#、PHP、Swift、C/C、Elixir、Haskell、Lua、R 等SKIP_DIRS硬编码跳过了node_modules、.git、dist、build、__pycache__、.next、target、Pods等构建与依赖目录同时也跳过了.ua与.understand-anything数据目录。2.2 文件树扫描与 .gitignore 感知scan_file_tree()从项目根做深度优先遍历按“目录优先、名称字母序”排序跳过符号链接防死循环、SKIP_DIRS命中项与.gitignore命中项。.gitignore的解析parse_gitignore()是一个简化版的 glob 到正则转换**/映射为(.*/)?*映射为[^/]*?映射为[^/]以/结尾的模式补(/|$)。无效模式会向 stderr 打印警告并跳过不会中断扫描。2.3 入口点检测静态模式匹配而非 ASTdetect_entry_points()用一组预编译正则extract-domain-context.py#L77-L121对每个源文件全文做匹配命中后记录行号与“签名 前 5 行”的代码片段截断到 300 字符。模式按业务语义分为五类类型覆盖的模式httpExpress/Koa 路由app.get/post/put/patch/delete/all/use、装饰器路由Flask/FastAPI/NestJS 的route/get/api_view及 Spring 的RequestMapping/GetMapping、Next.js/Remix 路由处理器export async function GET/POST/...、GraphQL resolverQuery/Mutation/...、gRPC service.proto中的service Xxx {cliCommander 风格.command(name)、argparseadd_parser(name)event.on(event-name)监听器、EventHandler/Subscribe/Listener/on_event装饰器cronCron/Schedule/Scheduled/crontab(...)manual泛化导出的处理器export (async) function handleX/processX/onX扫描会自动跳过测试文件.test.、.spec.、__tests__、_test.py、test_*.py与脚本自身总量到达MAX_ENTRY_POINTS200即停止。每个入口点记录file、line、type、description、match截断至 120 字符与snippet六个字段。2.4 文件签名按业务关键词优先抽样extract_file_signatures()并不平等对待所有文件——它先用一组业务关键词controller、service、handler、router、route、api、model、entity、repository、usecase、command、query、event、subscriber、listener、middleware、guard、interceptor、resolver、workflow、flow、process、pipeline、job、task对路径打分得分高的文件优先取前 40 个MAX_SAMPLED_FILES读取前 80 行提取exportsJS/TS 的export (default)? (async)? function|class|const|... 名称Python 回退到顶层def/classimportsimport ... from ...与from ... import两类模式各截前 20 条preview文件头部 500 字符。这套“关键词优先级”设计从源码结构看体现了明确的假设业务领域知识最可能存在于控制器、服务、处理器这类命名惯例中。2.5 元数据抽取与渐进式截断extract_metadata()会读取METADATA_FILES清单package.json、Cargo.toml、go.mod、pyproject.toml、pom.xml、build.gradle、Gemfile、docker-compose.yml、各类 README 等。对package.json做结构化解析只保留 name、description、scripts 键、依赖名列表README 截取前 2000 字符TOML/JSON/YAML/XML/Gradle 文件截取前 1000 字符。最终输出前_truncate_to_fit()保证整个 JSON 不超过 512 KB采用四级渐进裁剪extract-domain-context.py#L350-L380文件树截断到前 200 条文件签名中的preview截断到 200 字符入口点中的snippet截断到 100 字符签名数减到 20 条、入口点数减到 100 条。这种“逐层降级而不是丢弃”的策略确保了任何规模的项目都能得到一份可被 LLM 一次消化的上下文文件。domain-context.json的完整结构为{ projectRoot: ..., fileCount: 123, fileTree: [src/...], entryPoints: [{ file: ..., line: 42, type: http, description: ..., match: ..., snippet: ... }], fileSignatures: [{ file: ..., exports: [], imports: [], lines: 0, preview: ... }], metadata: { package.json: { name: ..., description: ..., scripts: [], dependencies: [], devDependencies: [] } } }Phase 3从既有图谱派生路径 2若 Phase 1 确认knowledge-graph.json新鲜则直接读取该文件并将其格式化为结构化上下文包含全部节点类型、名称、摘要、标签全部边类型尤其是calls、imports、contains;全部分层layers及其描述Tour 步骤如有。这份上下文直接交给 domain-analyzer不需要读取任何源文件。这是该路径成本远低于路径 1 的原因/understand产出的节点摘要已经完成了“代码说了什么”的第一遍翻译领域分析只是在其上做第二次抽象。Phase 4领域分析与三级层次模型技能会读取$PLUGIN_ROOT/agents/domain-analyzer.md即 domain-analyzer.md的 agent 提示词派发一个子 agent把 Phase 2 或 Phase 3 的上下文一并注入。该 agent 是“业务领域分析专家”其核心产出遵循三级层次Business Domain——高层业务领域如“Order Management”“User Authentication”“Payment Processing”Business Flow——领域内的具体流程如“Create Order”“Process Refund”Business Step——流程中的单个动作如“Validate input”“Check inventory”。agent 的提示词规定了严格的输出 schemaversion、project元数据、nodes、edges、以及有意留空的layers与tour——Dashboard 用独立的领域视图渲染不走 layers/tour关键约束值得逐条对照flow_step边的 weight 编码步骤顺序N 个步骤时第 i 步 weight 为round(i/N, 1)5 步即 0.1/0.2/0.3/0.4/0.5核心要求是 weight单调递增且全部落在 0.0–1.0 闭区间内每个 flow 必须通过contains_flow边挂到某个 domain每个 step 必须通过flow_step边挂到某个 flowcross_domain边描述领域间交互可用description字段解释交互内容step 节点的filePath必须是相对项目根的路径无法确定时就省略filePath与lineRange必须使用代码中真实的业务术语不得发明代码中不存在的流程规模建议2–6 个 domain、每 domain 2–5 个 flow、每 flow 3–8 个 step小项目可以更少节点 ID 前缀后必须 kebab-casedomain:order-management而非domain:OrderManagement所有节点非空summary、至少一个 tagcomplexity取simple|moderate|complex之一禁止重复 ID 与自环边。节点结构示例引自 agent 提示词{ id: domain:order-management, type: domain, name: Order Management, summary: 2-3 sentences about what this domain handles, tags: [relevant-tags], complexity: simple|moderate|complex, domainMeta: { entities: [key domain objects], businessRules: [important constraints/invariants], crossDomainInteractions: [how this domain interacts with others] } }flow 节点的domainMeta则记录触发方式entryPoint如POST /api/orders与entryTypehttp|cli|event|cron|manual——注意这与 Phase 2 预处理器检测出的入口点类型枚举完全对应两条路径产出的字段语义是一致的。agent 将结果写入$UA_DIR/intermediate/domain-analysis.json文本回复只允许一段简短摘要domain/flow/step 数量与关键领域名不得把完整 JSON 贴进对话。Phase 5校验与保存——错误容忍的落盘策略SKILL.md 规定读取分析输出 → 用标准图谱校验流水线校验schema 已支持domain/flow/step节点类型→校验失败时记录警告但保存有效部分错误容忍→ 保存到$UA_DIR/domain-graph.json→ 清理中间文件intermediate/domain-analysis.json与intermediate/domain-context.json。在核心包中这套类型系统落在 schema.tsGraphNodeSchema的type枚举显式包含domain, flow, step三种节点类型schema.ts#L420-L440并带有可选的domainMeta字段边类型枚举同样收录了contains_flow、flow_step、cross_domain且weight被约束为 0–1 闭区间——这与 domain-analyzer 提示词中的手工约束是同一套规则的机器校验版本。schema 中还维护了一份别名归一化表如business_domain → domain、has_flow → contains_flow意味着 LLM 输出的措辞变体在校验时会被自动纠正这是 Phase 5 “保存有效部分”能够成立的前提。落盘逻辑见 persistence/index.ts#L165-L197saveDomainGraph()写入前会先对filePath做净化sanitiseFilePaths再序列化loadDomainGraph()默认走validateGraph校验校验失败抛出携带 fatal 原因的错误也支持validate: false的宽松读取。从源码结构看领域图谱与结构图谱共用同一套KnowledgeGraph类型与校验器这正是设计文档中“Separate File, Shared Schema”方案 C的实现两份文件各自独立有效搜索、校验、过滤对两者通用同时不污染结构图谱。Phase 6启动 Dashboard 的领域视图技能的最后一步是自动触发/understand-dashboard见 understand-dashboard/SKILL.md来可视化领域图谱。Dashboard 会检测项目数据目录下的domain-graph.json并默认切换到领域视图——横向流程图形式domain 为簇、flow 为泳道、step 按flow_stepweight 的顺序从左到右排列cross_domain边则展示领域间交互。领域视图组件的实现在 DomainGraphView.tsx。启动方式上dashboard 技能优先走免安装的预构建 viewer失败则回退到pnpm install Vite 开发服务器最终都会打印带?token参数的访问 URLtoken 用于通过访问门禁。关键产物与文件速查产物/文件位置说明技能定义understand-anything-plugin/skills/understand-domain/SKILL.md六阶段工作流的权威描述预处理器understand-anything-plugin/skills/understand-domain/extract-domain-context.py轻量扫描器产出原材料 JSON分析 agentunderstand-anything-plugin/agents/domain-analyzer.md三级层次模型、输出 schema 与约束规则领域上下文$UA_DIR/intermediate/domain-context.jsonPhase 2 产物Phase 5 后清理领域分析结果$UA_DIR/intermediate/domain-analysis.jsonPhase 4 产物Phase 5 后清理最终图谱$UA_DIR/domain-graph.json与知识图谱同 schema独立有效类型与校验understand-anything-plugin/packages/core/src/schema.tsdomain/flow/step 节点与四类边持久化understand-anything-plugin/packages/core/src/persistence/index.tssaveDomainGraph/loadDomainGraph设计文档docs/superpowers/specs/2026-04-01-business-domain-knowledge-design.md背景动机、双路径架构与 token 成本估算小结/understand-domain的工程质量体现在三处克制其一输入侧用 512 KB 硬上限、四级渐进截断与业务关键词优先级抽样确保喂给 LLM 的上下文永远可控其二分析侧把“扫描”与“理解”分离——便宜的静态预处理负责找事实入口点、文件签名昂贵的 LLM 只做业务抽象且提示词以单调 weight、kebab-case ID、不虚构流程等硬约束压缩幻觉空间其三输出侧复用知识图谱的 schema 与校验器让领域图谱天然享受搜索、过滤与 Dashboard 渲染的全部基础设施同时以独立文件保证结构图谱零污染。对于已经跑过/understand的项目--full之外的默认路径几乎不产生额外文件读取成本这使得“先全量理解、后按需补领域视图”成为一条低摩擦的使用路线。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考