接手一个自己不熟悉的代码仓库时最常见的动作是先看 README再翻目录结构最后挑几个核心文件从头读。这个过程在几千文件的项目里很容易失控目录层级深、循环依赖多、框架代码和业务代码混在一起还没理解主流程人已经被细节淹没。开源社区最近出现了一类 Skill 项目专门解决这个问题把整个仓库解析成一张可交互的结构图每个目录、文件、关键模块都变成图上的节点哪里看不懂就点哪里AI 在点击后结合仓库上下文解释这个组件的职责、依赖关系和阅读顺序。标题里提到的这个开源 Skill 项目在 GitHub 上已经积累了超过 4 万 Star说明这类需求是普遍存在的。这篇文章要按“看完能自己复现”的标准拆解这个 Skill 的实现链路。你会看到仓库扫描、依赖抽取、结构图数据格式、页面渲染、点击解释这几个环节分别怎么实现以及一个完整的最小可运行案例。文章中的代码用于说明思路实际项目要结合自己的语言、包名和目录结构调整。1. 为什么“结构图 点哪里解释哪里”能解决读仓库的难题1.1 阅读陌生代码库的三个具体困难第一是定位难。文件一多入口模块、工具模块、配置模块、测试模块混在一起只能靠命名猜猜错之后顺着错误路径读下去时间浪费得很快。第二是关系难。只看单个文件读不出全貌真正要理解的是它被谁依赖、依赖谁、处在哪一层但这些关系不会自动显示出来。第三是上下文难。读一个函数时往往需要同时知道调用方、被调用方和配置来源跨文件跳转几次后当前这行代码到底在哪个流程里很容易丢失。结构图恰好把“定位”和“关系”变成了可视信息。而“点击后解释”解决的是第三个困难不用再靠人工在多个文件之间来回跳AI 直接基于节点上下文给出说明。这样理解陌生仓库的路径就从“逐行读代码”变成了“看图定位、点击提问、按解释深入”。1.2 为什么静态结构图不够用很多项目已经能用工具生成 UML 类图或依赖树但这些图是静态的生成出来只是给人看读者仍然要自己跟代码、自己对号入座。把 AI 的生成式解释绑定到节点上之后图的定位从“辅助阅读”变成了“可交互的讲解入口”。用户点击一个节点得到的不是一串文件路径而是“这个文件在项目里承担什么职责、关键函数有哪些、应该按什么顺序读”这类可以直接消化的信息。这也是 Skill 这种形态的优势不需要用户先安装独立的桌面软件只需要把它放进 AI 编码助手或智能体的工作目录用户用自然语言说“分析一下这个仓库”Skill 就会按照预设流程生成结构图并启动本地服务。托管在 GitHub 或 Gitee 都可以克隆到本地后放入助手的 skills 目录再赋予执行权限即可。2. 拆解 Skill 的完整工作链路2.1 六个环节构成一条处理流水线一个能够“把仓库变成结构图再点击解释”的 Skill本质上是一条数据处理流水线文件扫描递归遍历仓库过滤掉依赖目录、构建产物、缓存和二进制文件。依赖抽取对不同语言文件做 import、require 等语句解析得到文件之间的引用关系。节点映射把文件路径映射成图节点 id把引用关系映射成有向边。图形渲染前端把节点和边渲染成可拖拽、可缩放、可点击的结构图。点击解释用户点击节点后把该文件的路径与关键代码片段提交给 LLM返回职责说明。结果回显把解释显示到页面侧栏或回传给 AI 助手。前三个环节是分析层中间一个是展示层后两个是智能层。分析层做错了后面的图再好看也没有意义智能层做得不好图就只是另一种形式的文档。2.2 Skill 的入口是描述文件在常见 AI 编码助手中Skill 通常由一个 SKILL.md 描述文件和若干脚本组成。描述文件说明这个 Skill 在什么情况下触发、执行顺序是什么、依赖哪些命令。AI 助手读到描述文件后并不是直接执行里面的命令而是把描述内容交给模型由模型决定什么时候调用、以什么参数调用。这个设计解释了为什么 Skill 适合做“分析仓库”这类任务仓库路径每次都不一样模型需要根据用户输入动态决定传给扫描脚本的--root参数。如果写成固定脚本就没有这种灵活性。2.3 示例项目的目录结构下面是一个最小的 Skill 工程结构后续所有代码都围绕它展开repo-map-skill/ ├── SKILL.md ├── requirements.txt ├── scripts/ │ ├── scan_repo.py │ └── explain_node.py ├── templates/ │ └── viz.html └── server.py文件不多但覆盖了分析、解释、展示三个层面。把这个目录放到 AI 助手能读取的 skills 目录下然后在任意仓库里让助手执行“分析仓库结构”就能跑通完整链路。3. 实现扫描与依赖抽取先保证结构图数据是对的3.1 环境准备与依赖示例代码用 Python 编写因为处理文件系统和正则抽取比较方便。需要的基础环境如下依赖版本建议用途Python3.10 及以上编写扫描与解释脚本requests最新稳定版调用 LLM 接口Node.js18 及以上仅用于本地预览时的静态资源非必需浏览器Chrome 或 Edge打开结构图页面如果只想跑通分析层不接 LLMrequests 也可以不装。下面是 requirements.txtrequests2.31安装命令pip install -r requirements.txt这里要提醒一句不同 AI 助手的 Skill 规范并不完全一样。项目落地前先确认你使用的助手期望 SKILL.md 放在哪个目录、frontmatter 支持哪些字段再按它的规范调整不要照搬本文的路径结构。3.2 文件扫描要先把“噪音”过滤掉扫描的目标不是把仓库所有文件都收进来而是收“对理解项目结构有帮助的源文件”。node_modules、venv、dist、build、target、pycache、Lock 文件这类内容一旦进入图里结构图就会变成噪音图真正有价值的业务代码反而被淹没。scan_repo.py 的扫描部分用一个忽略集合控制范围import argparse import json import os import re from pathlib import Path DEFAULT_IGNORE { .git, .idea, .vscode, node_modules, venv, .venv, __pycache__, dist, build, target, out, *.pyc, *.log, *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml, } EXT_PATTERNS { .py: re.compile(r^\s*(?:from\s([\.\w])\simport|import\s([\.\w])), re.M), .js: re.compile(r(?:from\s[\]([^\])[\]|require\([\]([^\])[\]\)), re.M), .ts: re.compile(r(?:from\s[\]([^\])[\]|import\s[\]([^\])[\]), re.M), .java: re.compile(r^import\s([\w\.]);, re.M), } def should_ignore(path: Path) - bool: parts path.parts if any(part in DEFAULT_IGNORE for part in parts): return True return any( rule.startswith(*) and path.name.endswith(rule[1:]) for rule in DEFAULT_IGNORE ) def find_files(root: Path): for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if not should_ignore(Path(dirpath) / d)] for name in filenames: path Path(dirpath) / name if not should_ignore(path) and path.suffix in EXT_PATTERNS: yield path关键点有两处。一是should_ignore同时处理目录名和文件后缀避免只过滤目录不过滤文件。二是dirnames[:] [...]直接修改 os.walk 返回的目录列表这是 Python 里停止递归的惯用写法改成普通赋值会导致过滤掉的目录仍然被遍历。3.3 依赖抽取从 import 语句到有向边结构图里的边来自文件之间的引用关系。示例用正则匹配 import、require、from 语句原因是这个最小案例不需要引入重量级解析器但在真实项目里正则只能处理最简单的写法动态 import、别名映射、跨语言调用都匹配不到。抽取逻辑如下def extract_imports(path: Path): pattern EXT_PATTERNS[path.suffix] text path.read_text(encodingutf-8, errorsignore) results [] for match in pattern.finditer(text): dep next((g for g in match.groups() if g), None) if dep: results.append(dep) return results拿到依赖名之后要把依赖名映射回仓库内的文件。最朴素的做法是把点号分隔的包名转换成路径例如src.utils映射成src/utils.py然后在文件列表里查找。这个映射在小型 Python 项目里通常够用一旦遇到包名和目录名不一致、使用了路径别名、或者同一依赖有多个入口文件就必须换成对应语言的 AST 解析器。构建节点和边的完整逻辑def main(): parser argparse.ArgumentParser(description仓库结构图扫描器) parser.add_argument(--root, default., help仓库根目录) parser.add_argument(--output, defaultgraph.json, help输出文件) args parser.parse_args() root Path(args.root).resolve() files list(find_files(root)) nodes [] edges [] file_to_node {} for i, f in enumerate(files): rel f.relative_to(root).as_posix() node_id str(i) file_to_node[rel] node_id nodes.append({ id: node_id, label: rel, type: f.suffix.lstrip(.), path: rel, }) for f in files: rel f.relative_to(root).as_posix() src file_to_node.get(rel) for dep in extract_imports(f): dep_path dep.replace(., /) .py dst file_to_node.get(dep_path) if dst: edges.append({source: src, target: dst, relation: import}) graph {nodes: nodes, edges: edges} Path(args.output).write_text( json.dumps(graph, ensure_asciiFalse, indent2), encodingutf-8 ) print(fnodes{len(nodes)} edges{len(edges)} output{args.output}) if __name__ __main__: main()运行方式python scripts/scan_repo.py --root ./my-project --output graph.json正常输出类似nodes36 edges47 outputgraph.json如果 nodes 数量明显偏少先检查根目录是否传错如果缺少依赖目录先检查 EXT_PATTERNS 是否覆盖了项目使用的语言。4. 生成可交互结构图绑定“点击解释”事件4.1 结构图数据格式要兼顾前端和解释接口scan_repo.py 输出的 graph.json 是整个 Skill 的中间产物前端和解释接口都依赖它。节点必须带 path 字段因为点击解释时需要读取该路径下的真实代码label 用相对路径便于人识别type 字段可以用于后续前端按语言着色。示例输出{ nodes: [ {id: 0, label: main.py, type: py, path: main.py}, {id: 1, label: utils.py, type: py, path: utils.py} ], edges: [ {source: 0, target: 1, relation: import} ] }4.2 用 vis-network 渲染节点和边前端选择 vis-network 是为了减少自研成本它原生支持拖拽、缩放、点击事件并且只依赖一个 js 文件。页面加载后先读取 graph.json再把节点和边交给 DataSet最后监听 click 事件。!DOCTYPE html html langzh-CN head meta charsetUTF-8 / title仓库结构图/title link relstylesheet hrefhttps://unpkg.com/vis-network/styles/vis-network.min.css / script srchttps://unpkg.com/vis-network/standalone/umd/vis-network.min.js/script style body { margin: 0; font-family: Microsoft YaHei, sans-serif; } #graph { width: 100vw; height: 80vh; } #panel { position: fixed; right: 0; top: 0; width: 360px; height: 80vh; overflow-y: auto; background: #fff; border-left: 1px solid #ddd; padding: 16px; box-sizing: border-box; } /style /head body div idgraph/div div idpanel h3点击左侧节点查看解释/h3 div iddetail尚未选择节点/div /div script fetch(graph.json) .then(r r.json()) .then(graph { const nodes graph.nodes.map(n ({ id: n.id, label: n.label, title: n.path })); const edges graph.edges.map(e ({ from: e.source, to: e.target })); const container document.getElementById(graph); const data { nodes: new vis.DataSet(nodes), edges: new vis.DataSet(edges) }; const network new vis.Network(container, data, { layout: { hierarchical: { enabled: false } }, physics: { stabilization: true } }); network.on(click, params { const nodeId params.nodes[0]; if (!nodeId) return; fetch(/explain?node${encodeURIComponent(nodeId)}) .then(r r.json()) .then(res { document.getElementById(detail).innerText res.explanation; }); }); }); /script /body /html点击事件里只取了params.nodes[0]因为一次点击可能同时命中多个节点这里只解释最上层命中的那一个。如果是为生产设计可以改成点击后弹出菜单由用户决定解释当前文件还是递归解释整个子图。4.3 点击解释接口不要整文件提交给模型explain_node.py 的逻辑是根据节点 id 找到 path读取该文件最关键的一部分内容连同系统提示词一起提交给 LLM。这里有一个重要的工程取舍不要把整个文件提交进去。几百行的大文件会立刻把上下文窗口吃掉而且包含大量与“这个文件是干什么的”无关的实现细节。import argparse import json import os from pathlib import Path import requests def read_node_context(graph_path, node_id, context_lines60): graph json.loads(Path(graph_path).read_text(encodingutf-8)) node next((n for n in graph[nodes] if n[id] node_id), None) if not node: raise ValueError(fnode not found: {node_id}) path Path(node[path]) code path.read_text(encodingutf-8, errorsignore).splitlines() head \n.join(code[:context_lines]) return node, head def explain(node, snippet): payload { model: os.getenv(LLM_MODEL, gpt-4o-mini), messages: [ { role: system, content: 你是一名资深代码审阅者。请用中文解释给定文件的作用、核心逻辑、被谁依赖、以及阅读建议。, }, { role: user, content: f文件路径: {node[path]}\n文件内容前 {60} 行:\n{snippet}, }, ], } resp requests.post( os.getenv(LLM_ENDPOINT), headers{Authorization: fBearer {os.getenv(LLM_API_KEY) or }}, jsonpayload, timeout60, ) resp.raise_for_status() return resp.json()[choices][0][message][content] def main(): parser argparse.ArgumentParser() parser.add_argument(--graph, requiredTrue, helpgraph.json 路径) parser.add_argument(--node, requiredTrue, help节点 id) args parser.parse_args() node, snippet read_node_context(args.graph, args.node) print(explain(node, snippet)) if __name__ __main__: main()调用前需要设置三个环境变量export LLM_ENDPOINThttps://api.openai.com/v1/chat/completions export LLM_API_KEY你的Key export LLM_MODELgpt-4o-mini上面是通用的 OpenAI 兼容接口调用方式。如果使用其他兼容接口只需要换 base URL 和模型名不需要改请求结构。密钥不要提交到仓库也不要写死在代码里。4.4 本地预览服务把页面和接口串起来为了让浏览器同时能拿到 graph.json 和 /explain 接口需要一个极简 HTTP 服务。这里用 Python 标准库实现目的是少引依赖import json import subprocess from http.server import BaseHTTPRequestHandler, HTTPServer from pathlib import Path from urllib.parse import urlparse, parse_qs GRAPH_PATH Path(graph.json) HTML_PATH Path(templates/viz.html) class Handler(BaseHTTPRequestHandler): def do_GET(self): parsed urlparse(self.path) if parsed.path /: self.send_html(HTML_PATH) elif parsed.path /graph.json: self.send_json(GRAPH_PATH.read_text(encodingutf-8)) elif parsed.path /explain: node parse_qs(parsed.query).get(node, [])[0] if not node: self.send_error(400, missing node) return result subprocess.run( [python, scripts/explain_node.py, --graph, str(GRAPH_PATH), --node, node], capture_outputTrue, textTrue, timeout90, ) explanation result.stdout.strip() or result.stderr self.send_json(json.dumps({explanation: explanation}, ensure_asciiFalse)) else: self.send_error(404) def send_html(self, path): self.send_response(200) self.send_header(Content-Type, text/html; charsetutf-8) self.end_headers() self.wfile.write(path.read_bytes()) def send_json(self, text): self.send_response(200) self.send_header(Content-Type, application/json; charsetutf-8) self.end_headers() self.wfile.write(text.encode(utf-8)) if __name__ __main__: HTTPServer((127.0.0.1, 8000), Handler).serve_forever()启动python server.py然后访问http://127.0.0.1:8000就能看到结构图。这里用 subprocess 调用 explain_node.py 是为了隔离错误避免解释脚本的异常拖垮页面代价是每次点击都启动一个 Python 进程高频点击时会有明显延迟生产环境应改成常驻进程或异步队列。5. 注册成 Skill 并完成运行验证5.1 编写 SKILL.md 描述文件把扫描、解释、展示脚本放在一个目录里并为它写 SKILL.mdAI 助手才能在正确时机调用它。下面是一个最小示例--- name: repo_map description: 分析代码仓库结构并生成可交互结构图支持点击节点解释模块作用 --- 当用户要求“分析仓库结构”“画依赖图”“解释某个模块”时使用本 Skill。 执行步骤 1. 运行 scripts/scan_repo.py把用户指定的仓库路径作为 --root 参数传入输出保存为 graph.json。 2. 运行 server.py提示用户访问本地页面查看结构图。 3. 用户点击节点后由 /explain 接口封装 explain_node.py 的调用返回该节点对应的模块解释。这里要注意不同助手的 Skill 加载方式不完全一致。有的是读 SKILL.md 全文由模型自行决定工具调用有的要求描述文件里同时声明命令白名单。落地前先读当前助手的 Skill 规范文档本文示例是一个“说明思路”的最小结构。5.2 单元级验证先不接 LLM 验证分析层在接 LLM 之前先把分析层跑通避免把网络和密钥问题混进结构图排查里。验证路径准备一个小仓库里面至少有两个互相 import 的 Python 文件。运行python scripts/scan_repo.py --root ./demo --output graph.json。打开 graph.json确认 nodes 数量正确、edges 数量与手工数出的 import 数量一致。用 Python 快速检查节点 id 是否唯一import json graph json.load(open(graph.json, encodingutf-8)) node_ids [n[id] for n in graph[nodes]] assert len(node_ids) len(set(node_ids)), node id 重复 print(nodes:, len(node_ids), edges:, len(graph[edges]))这一步能过滤掉大部分分析层错误再做页面和 LLM 联调时问题面会小很多。5.3 联调验证从页面点击到解释回显拿到 graph.json 后启动 server.py在浏览器打开页面依次检查检查项预期结果失败时的排查方向页面能打开显示结构图与空白边栏端口被占用、HTML 路径不对、CDN 加载失败节点与边可见图上有节点、有连线graph.json 为空、前端数据字段名不匹配点击节点右侧出现正在请求点击事件未绑定、node id 编码错误请求返回右侧显示模块解释LLM 密钥、endpoint、模型名、网络环境点击无关区域不触发请求点击事件中未判断 nodeId 是否存在最后一项是常见体验问题点空白区域时会触发 click 事件但 params.nodes 是空数组。如果代码里直接在空数组上取 [0]会得到 undefined然后带着 undefined 去请求接口产生无效请求。示例代码里已经加了if (!nodeId) return;。6. 常见问题与排查链路6.1 结构图噪音过大关键模块被淹没现象生成的图里节点特别多业务文件和依赖文件挤在一起。原因忽略规则没有覆盖项目实际使用的依赖目录或者扫描了构建产物。检查方式先数 graph.json 里 nodes 数量再对比 source tree 里实际源文件数量。解决方式把 ignore 集合补全并按目录层级做折叠。例如只展开前两层目录第三层及以下合并为“聚合节点”点击聚合节点再展开。这个策略对大中型仓库几乎是必须的否则图渲染出来后连点都点不准。6.2 边数量明显偏少现象两个文件明明有 import 关系图里却没有边。原因依赖名到文件路径的映射规则太简单比如包名与目录名不一致或者正则没有匹配到某种写法或者 import 的库不是仓库内文件被过滤了。检查步骤先确认被依赖文件确实存在于仓库中。在 extract_imports 里临时打印所有命中结果看是否连 import 语句都没匹配到。如果匹配到了但目标文件不匹配检查 dep_path 拼接规则。仍无法解决时换成目标语言的 AST 解析库。Python 项目可以直接用标准库 ast 模块它对 import 语法的覆盖比正则完整得多。6.3 点击节点后解释接口报错或超时现象点击节点后页面一直转圈最终无内容。可能原因按顺序排查现象常见原因检查方式返回 401/403LLM_API_KEY 错误或未设置查看环境变量确认 Key 有效返回 404LLM_ENDPOINT 指向错误打印请求 URL确认是完整的接口地址返回 429触发速率限制检查配额增加重试和退避超时 90 秒提交内容过长或模型在排队缩短 context_lines调整 timeout返回空内容模型返回了空 choices打印原始响应检查模型名是否支持每次点击都会在解释脚本的临时进程里发生错误信息会被 server.py 捕获并返回给页面。所以页面没反应时先看浏览器 Network 面板里 /explain 的响应体里面要么是 Python 堆栈要么是 HTTP 状态码能直接定位大部分问题。6.4 浏览器直接打开 HTML 看不到图现象用 file:// 协议打开 viz.html页面空白或加载失败。原因fetch 加载本地 JSON 时受浏览器同源策略限制file:// 协议下无法发起普通 fetch 请求。解决方式统一通过 HTTP 服务访问也就是运行 server.py 后访问 127.0.0.1:8000。这也是示例里单独写一个本地服务的原因不是多此一举。7. 从最小案例到生产可用的改进方向7.1 分析层按语言接入真实解析器正则抽取只能作为起步方案。生产环境建议按信息密度从高到低推进Python用标准库 ast 提取 import、function、class 定义可以同时生成类和函数级节点。JavaScript/TypeScript用 babel/parser 等成熟解析器能处理动态导入。Java用 JavaParser 解析 import 与类型引用。多语言仓库先识别语言占比再按语言分派解析器最后统一汇入同一张图。节点粒度也要可配置文件级、类级、函数级。文件级适合快速总览函数级适合深入理解某条链路。粒度越细生成的节点越多解释请求也越多两者需要权衡。7.2 智能层给模型提供更好的上下文点击解释时只传前 60 行是不够的。改进思路包括先过滤测试文件和自动生成文件避免解释重点偏移。对目标文件做摘要提取函数签名、类名、关键注释再提交给模型。把调用方与被调用方的文件名一并提交让解释能说清楚上下游。对重复点击做缓存同一个文件只请求一次 LLM后续直接返回缓存结果。这些改动都不会改变整体架构只是在 explain_node.py 内部增加上下文组装逻辑和缓存层。7.3 工程化日志、缓存、安全与部署从学习环境进入生产环境至少要补齐这些点场景学习环境生产环境依赖安装pip install -r requirements.txt锁定版本、容器化、私有源LLM 密钥环境变量密钥管理服务禁止进日志代码上传直接上传仓库源文件先做敏感信息扫描排除配置和密钥文件请求耗时每次点击 10 到 90 秒缓存、异步任务、结果推送错误处理终端看堆栈统一日志、监控、告警数据安全不关注是否允许外部 LLM 读取代码需要明确评估其中数据安全最容易忽略。结构图 Skill 会把文件内容发送给 LLM 接口如果仓库里包含生产密钥、客户数据、内部协议描述必须先做过滤和审批流程再允许对这类仓库生成解释。7.4 可复用的落地清单按下面清单检查一个“仓库结构图 Skill”是否达到可发布状态忽略规则覆盖项目所有噪音目录graph.json 中节点可理解、有边界。节点 id 唯一边有方向数据格式与前端字段一致。分析层与 LLM 层可以独立验证排错时能分清是哪一层出问题。LLM 服务有超时、重试、缓存密钥不写入仓库。页面通过 HTTP 服务访问不依赖 file:// 协议。对大型仓库支持目录折叠或子图懒加载。对敏感仓库有明确的拦截与审批策略。这类 Skill 的价值不在于把代码“画出来”而在于把“读代码的路径”变成一条可以被交互和解释驱动的链路。项目拿到手先扫描结构再顺着点击解释一路走下去理解成本会比闷头翻文件低很多。如果打算做一个类似工具建议从最小可运行案例开始先能扫出正确的节点和边再考虑页面的观感和 AI 解释的质量。