Generate a persistent .nexus-map/ knowledge base that lets any AI session instantly understand a codebase's architecture, systems, dependencies, and change hotspots. Use when starting work on an unfamiliar repository, onboarding with AI-assisted context, preparing for a major refactoring initiative,

nexus mapper — AI 项目探测协议本 Skill 指导 AI Agent 使用 PROBE 五阶段协议，对任意本地 Git 仓库执行系统性探测，产出 .nexus map/ 分层知识库。何时调用 / 何时不调用场景调用 : : 用户提供本地 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 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。输入契约语言支持：自动按文件扩展名 dispatch，语言配置（扩展名映射 + Tree sitter 查询）存储在 scripts/languages.json 。当前已接入 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 等 30+ 语言。非标准语言：若仓库含有内置未支持的语言，通过命令行参数动态补充（详见 references/05 language customization.md ）： add extension .templ=templ 添加新文件扩展名映射 add query templ struct "(component declaration ...)" 添加结构查询 language config <JSON FILE 复杂配置时使用 JSON 文件扫描过滤：AST 提取与 raw/file tree.txt 生成共享同一套过滤规则： exclude dirs django static,.go root 按目录名或仓库相对路径忽略杂物目录 use gitignore 启用 <repo path /.gitignore 规则（默认开启），忽略其中声明的文件和目录 no gitignore 不应用 .gitignore 规则；此时仍会保留内置排除项和 exclude dirs 输出格式执行完成后，目标仓库根目录下将产出：所有生成的 Markdown 文件必须带一个简短头部，至少包含： generated by 、 verified at 、 provenance 。 concept model.json 的人类可读名称字段统一使用 label ，不要添加 title 。如果 PROFILE 阶段发现语言覆盖降级或人工推断， provenance 必须明确标注。 PROBE 阶段门控 [!IMPORTANT] 进入每个阶段前必须先读对应 reference，不得跳过。各阶段详细步骤、完成检查清单与边界场景处理均在 reference 中定义。执行守则守则1: OBJECT 拒绝形式主义 OBJECT 的存在意义是打破 REASON 的幸存者偏差。大量工程事实隐藏在目录命名和 git 热点背后，第一直觉几乎总是错的。不合格质疑（禁止提交）：问题不在措辞，而在于没有证据线索，也无法在 BENCHMARK 阶段验证。合格质疑格式：守则2: implemented 节点必须有真实 code path [!IMPORTANT] 写入 concept model.json 前，必须先区分节点是 implemented 、 planned 还是 inferred 。只有 implemented 节点允许写入 code path ，且必须亲手验证存在。对于 planned 或 inferred 节点，使用：禁止：用勉强相关的文件冒充 code path 、把状态塞进路径字段（如 code path: "PLANNED" ）。守则3: EMIT 原子性先全部写入 .nexus map/.tmp/ ，全部成功后整体移动到正式目录，删除 .tmp/ 。目的：中途失败不留半成品。下次执行检测到 .tmp/ 存在 → 清理后重新生成。幂等性规则：状态处理方式 .nexus map/ 不存在直接继续 .nexus map/ 存在且 INDEX.md 有效询问用户：「是否覆盖？[y/n]」 .nexus map/ 存在但文件不完整「检测到未完成分析，将重新生成」，直接继续守则4: INDEX.md 的角色——冷启动路由器，而非静态字典 INDEX.md 的读者是从未见过这个仓库的 AI 。两个硬约束： < 2000 tokens — 超过就重写，不是截断结论必须具体 — 证据不足时明确写出 evidence gap 或 unknown ，并说明缺了什么证据写完后执行 token 估算：行数 × 平均 30 tokens/行 = 粗估值。 INDEX.md 必须包含的强制路由块（Hard Trigger Block） ——生成时把这段结构写入文件末尾：守则5: 最小执行面与敏感信息保护 [!IMPORTANT] 默认只运行本 Skill 自带脚本和必要的只读检查。不要因为"想更懂仓库"就执行目标仓库里的构建脚本、测试脚本或自定义命令。默认允许： extract ast.py 、 git detective.py 、目录遍历、文本搜索、只读文件查看默认禁止：执行目标仓库的 npm install 、 pnpm dev 、 python main.py 、 docker compose up 等，除非用户明确要求遇到 .env 、密钥文件、凭据配置时：只记录其存在和用途，不抄出具体值守则6: 降级与人工推断必须显式可见 [!IMPORTANT] 如果 AST 覆盖不完整，或者某部分来自人工阅读而非脚本产出，必须在最终文件中显式标注 provenance。 dependencies.md 中凡是非 AST 直接支持的依赖关系，必须标注 inferred from file tree/manual inspection domains.md 、 systems.md 、 INDEX.md 如果涉及未支持语言区域，必须说明 unsupported language downgrade 若写入进度快照、Sprint 状态，必须附 verified at ，避免过期信息伪装成当前事实不确定性表达规范避免只写：待确认 · 可能是 · 疑似 · 也许 · 待定 · 暂不清楚 · pending · maybe · possibly · TBD 如果证据不足，按以下格式写： unknown: 未发现直接证据表明 api/ 是主入口，当前仅能确认 cli.py 被 README 引用 evidence gap: 仓库没有 git 历史，因此 hotspots 部分跳过允许诚实地写不确定，但必须解释不确定来自哪一条缺失证据。脚本工具链依赖安装（首次使用）：持久化记忆规则（写入宿主 AGENTS.md）建议把以下规则写入仓库的 AGENTS.md 、 CLAUDE.md 或同类持久记忆文件，使知识库在长期对话中保持活跃：按需查询工具（PROBE 辅助） scripts/query graph.py 读取 raw/ast nodes.json ，零额外依赖（纯 Python 标准库）。阶段推荐查询用途 REASON hub analysis 数据验证核心系统假说，不靠目录名猜测 OBJECT impact git stats 验证边界假设，查看真实上下游依赖 EMIT summary , file 生成 systems.md / dependencies.md 的数据支撑各查询模式的核心价值： hub analysis 用于 REASON 期验证架构假说； impact git stats 用于 OBJECT 期量化边界风险； summary 与 file 用于 EMIT 期生成精确数据支撑。

nexus-mapper