nexus-mapper — AI 项目探测协议 "你不是在写代码文档。你是在为下一个接手的 AI 建立思维基础。" 本 Skill 指导 AI Agent 使用 PROBE 五阶段协议，对任意本地 Git 仓库执行系统性探测，产出 .nexus-map/ 分层知识库。 ⚠️ CRITICAL — 五阶段不可跳过 [!IMPORTANT] 在 PROFILE、REASON、OBJECT、BENCHMARK 完成前，不得产出最终 .nexus-map/ 。这不是为了形式完整，而是为了防止 AI 把第一眼假设直接写成结论。最终产物必须建立在脚本输出、仓库结构、反证挑战和回查验证之上。 ❌ 禁止行为：跳过 OBJECT 直接写输出资产在 BENCHMARK 完成前生成 concept_model.json PROFILE 阶段脚本失败后继续执行后续阶段 ✅ 必须做到：每个阶段完成后显式确认「✅ 阶段名完成」再进入下一阶段 OBJECT 提出足以推翻当前假设的最少一组高价值质疑，通常为 1-3 条，绝不凑数 implemented 节点的 code_path 必须在仓库中真实存在； planned/inferred 节点不得伪造 code_path （见守则2） 📌 何时调用 / 何时不调用场景调用用户提供本地 repo 路径，希望 AI 理解其架构 ✅ 需要生成 .nexus-map/INDEX.md 供后续 AI 会话冷启动 ✅ 用户说「帮我分析项目」「建立项目知识库」「让 AI 了解这个仓库」 ✅ 运行环境无 shell 执行能力（纯 API 调用模式，无 run_command 工具） ❌ 宿主机无本地 Python 3.10+ ❌ 目标仓库无任何已知语言源文件（ .py/.ts/.java/.go/.rs/.cpp 等均无） ❌ 用户只想查询某个特定文件/函数 → 直接用 view_file / grep_search ❌ ⚠️ 前提检查（缺失项要显式告知；可降级时优先降级而不是中止）前提检查方式目标路径存在 $repo_path 可访问 Python 3.10+ python --version

= 3.10 脚本依赖已安装 python -c "import tree_sitter" 无报错有 shell 执行能力 Agent 环境支持 run_command 工具调用 git 历史是加分项，不是硬阻塞项。没有 .git 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。 📥 输入契约 repo_path: 目标仓库的本地绝对路径（必填）语言支持：自动按文件扩展名 dispatch，语言配置（扩展名映射 + Tree-sitter 查询）存储在 scripts/languages.json ，优先用 bundled structural queries 提取模块/类/函数；若 grammar 可加载但当前没有结构 query，则至少保留 Module 级节点并在输出中标注 module-only coverage 。当前已接入的常见语言包括 Python/JavaScript/TypeScript/TSX/Bash/Java/Go/Rust/C#/C/C++/Kotlin/Ruby/Swift/Scala/PHP/Lua/Elixir/GDScript/Dart/Haskell/Clojure/SQL/Proto/Solidity/Vue/Svelte/R/Perl。不支持的语言扩展：若仓库含有内置未支持的语言文件，agent 可通过命令行参数动态赋予支持： --add-extension .templ=templ 添加新文件扩展名映射（可重复） --add-query templ struct "(component_declaration ...)" 为某语言添加结构查询（可重复）查询参数格式： --add-query 其中为 struct 或 imports 。高级用法：若配置复杂，可用 --language-config 显式指定一个 JSON 配置文件，格式同前，允许扩展名映射、自定义查询和显式标记不支持的语言。如果当前任务涉及“补一个暂未适配的语言”或“为某种非标准扩展名补 Tree-sitter 支持”，应继续读取 references/05-language-customization.md 。该文件不是阶段门控文件，而是命令行扩展与可选 JSON 配置的专项操作说明。 📤 输出格式执行完成后，目标仓库根目录下将产出： .nexus-map/ ├── INDEX.md ← AI 冷启动主入口（< 2000 tokens） ├── arch/ │ ├── systems.md ← 系统边界 + 代码位置 │ ├── dependencies.md ← Mermaid 依赖图 + 时序图 │ └── test_coverage.md ← 静态测试面：测试文件、覆盖到的核心模块、证据缺口 ├── concepts/ │ ├── concept_model.json ← Schema V1 机器可读图谱 │ └── domains.md ← 核心领域概念说明 ├── hotspots/ │ └── git_forensics.md ← Git 热点 + 耦合对分析 └── raw/ ├── ast_nodes.json ← Tree-sitter 解析原始数据 ├── git_stats.json ← Git 热点与耦合数据 └── file_tree.txt ← 过滤后的文件树所有生成的 Markdown 文件必须带一个简短头部，至少包含： generated_by verified_at provenance concept_model.json 的人类可读名称字段统一使用 label 。不要添加 title ；若某个生成结果出现 title ，应在 EMIT 阶段删除并并回 label 语义。如果 PROFILE 阶段发现已知但未支持的语言文件， provenance 必须明确写出哪些部分属于人工推断或降级分析。如果 PROFILE 阶段发现 module-only coverage ，也必须写清楚：这些语言已被计入 AST 文件覆盖，但没有类/函数级结构保证。如果 PROFILE 阶段发现某个通过覆盖配置声明的语言仍然无法加载 parser，也必须写清楚：这是 configured-but-unavailable ，不能伪装成已覆盖。 🔍 按需查询工具 scripts/query_graph.py 读取 raw/ast_nodes.json ，提供精准的局部依赖查询。在 PROBE 各阶段辅助认知生成，也可在后续开发中按需使用。零额外依赖 ——纯 Python 标准库，输入 ast_nodes.json 即可运行。查询模式

查看某个文件的类/函数结构及 import 清单