Skip to main content 홈 크리에이터 dylanckawalec mermate nexus-mapper
nexus-mapper 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, or enabling reliable cold-start AI sessions across a team. Produces INDEX.md, systems.md, concept_model.json, git_forensics.md and more. Requires shell execution and Python 3.10+. For ad-hoc file queries or instant impact analysis during active development, use nexus-query instead.
설치로 이동 Skills Marketplace 커뮤니티가 만든 AI 스킬을 발견하고 탐색하세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/DylanCkawalec/Mermate --skill nexus-mapper명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Zip 다운로드 다운로드 중... Core agentic infrastructure of the Mermate application — detached agent sessions (run/finalize/attach/stop), agent modes, depth scoring and role caps, Opseeq stage-event bridge with heartbeat lifecycle, run lineage and trace store, boot/health gates, and the Python MCP bridge. Use when working on server/routes/agent.js, opseeq-bridge.js, run tracking, server boot/health, mcp_service/, or cross-cutting pipeline behavior rather than a single tab.
name nexus-mapper description 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, or enabling reliable cold-start AI sessions across a team. Produces INDEX.md, systems.md, concept_model.json, git_forensics.md and more. Requires shell execution and Python 3.10+. For ad-hoc file queries or instant impact analysis during active development, use nexus-query instead.
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 或历史过少时，跳过热点分析，并在输出中明确记录这是一次降级探测。
输入契约 repo_path: 目标仓库的本地绝对路径（必填）
语言支持 ：自动按文件扩展名 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 文件
输出格式 .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。
如果 PROFILE 阶段发现语言覆盖降级或人工推断，provenance 必须明确标注。
PROBE 阶段门控
[!IMPORTANT]
进入每个阶段前必须先读对应 reference，不得跳过。
各阶段详细步骤、完成检查清单与边界场景处理均在 reference 中定义。
[Skill 激活时] → read references/probe-protocol.md （阶段步骤蓝图，含边界场景与三维度质疑框架）
[EMIT 前] → read references/output-schema.md （Schema 校验规范）
[非标准语言时] → read references/language-customization.md（按需，非门控）
执行守则
守则1: OBJECT 拒绝形式主义 OBJECT 的存在意义是打破 REASON 的幸存者偏差。大量工程事实隐藏在目录命名和 git 热点背后，第一直觉几乎总是错的。
Q1: 我对系统结构的把握还不够扎实
Q2: xxx 目录的职责暂时没有直接证据
问题不在措辞，而在于没有证据线索，也无法在 BENCHMARK 阶段验证。
Q1: git_stats 显示 tasks/analysis_tasks.py 变更 21 次（high risk），
但 HYPOTHESIS 认为编排入口是 evolution/detective_loop.py。
矛盾：若 detective_loop 是入口，为何 analysis_tasks 热度更高？
证据线索: git_stats.json hotspots[0].path
验证计划: view tasks/analysis_tasks.py 的 class 定义 + import 树
守则2: implemented 节点必须有真实 code_path
[!IMPORTANT]
写入 concept_model.json 前，必须先区分节点是 implemented、planned 还是 inferred。
只有 implemented 节点允许写入 code_path，且必须亲手验证存在。
ls $repo_path /src/nexus/application/weaving/
ls $repo_path /src/nexus/application/nonexist/
对于 planned 或 inferred 节点，使用：
{
"implementation_status" : "planned" ,
"code_path" : null ,
"evidence_path" : "docs/architecture.md" ,
"evidence_gap" : "仓库中未发现 src/agents/monarch/，仅在设计文档中出现"
}
禁止：用勉强相关的文件冒充 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） ——生成时把这段结构写入文件末尾：
## [操作指南] 强制执行步骤
> 本节是对所有读取本文件的 AI 发出的硬性操作指令，不是建议。
### 步骤1 — 必须先读完以下所有文件（顺序不限）
读完本文件后，在执行任何任务之前，必须依次 read 以下文件完整内容：
- `.nexus-map/arch/systems.md` — 系统边界与代码位置
- `.nexus-map/arch/dependencies.md` — 系统间依赖关系与 Mermaid 图
- `.nexus-map/arch/test_coverage.md` — 测试面与证据缺口
- `.nexus-map/hotspots/git_forensics.md` — Git 热点与耦合风险
- `.nexus-map/concepts/domains.md` — 核心领域概念
> 这些文件均为高密度摘要，总量通常 < 5000 tokens，是必要的上下文成本。
> 不得以"任务简单"或"只改一个文件"为由跳过。
### 步骤2 — 按任务类型追加操作（步骤1 完成后执行）
- 若任务涉及**接口修改、新增跨模块调用、删除/重命名公共函数** ：
→ 必须运行 `query_graph.py --impact <目标文件>` 确认影响半径后再写代码。
- 若任务需要**判断某文件被谁引用** ：
→ 运行 `query_graph.py --who-imports <模块名>` 。
- 若仓库结构已发生重大变化（新增系统、重构模块边界）：
→ 任务完成后评估是否需要重新运行 nexus-mapper 更新知识库。
守则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 inspectiondomains.md、systems.md、INDEX.md 如果涉及未支持语言区域，必须说明 unsupported language downgrade若写入进度快照、Sprint 状态，必须附 verified_at，避免过期信息伪装成当前事实
不确定性表达规范 避免只写：待确认 · 可能是 · 疑似 · 也许 · 待定 · 暂不清楚 · pending · maybe · possibly · TBD
unknown: 未发现直接证据表明 api/ 是主入口，当前仅能确认 cli.py 被 README 引用evidence gap: 仓库没有 git 历史，因此 hotspots 部分跳过 允许诚实地写不确定，但必须解释不确定来自哪一条缺失证据。
脚本工具链
SKILL_DIR=".agent/skills/nexus-mapper"
SKILL_DIR="/path/to/nexus-mapper"
python $SKILL_DIR /scripts/extract_ast.py <repo_path> [--max-nodes 500] \
--file-tree-out <repo_path>/.nexus-map/raw/file_tree.txt \
> <repo_path>/.nexus-map/raw/ast_nodes.json
python $SKILL_DIR /scripts/extract_ast.py <repo_path> [--max-nodes 500] \
--add-extension .templ=templ \
--add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def" \
> <repo_path>/.nexus-map/raw/ast_nodes.json
python $SKILL_DIR /scripts/extract_ast.py <repo_path> [--max-nodes 500] \
--language-config /custom/path/to/language-config.json \
> <repo_path>/.nexus-map/raw/ast_nodes.json
pip install -r $SKILL_DIR /scripts/requirements.txt
持久化记忆规则（写入宿主 AGENTS.md） 建议把以下规则写入仓库的 AGENTS.md、CLAUDE.md 或同类持久记忆文件，使知识库在长期对话中保持活跃：
如果仓库中存在 .nexus-map/INDEX.md，先阅读它，然后在执行任务前读完其路由块中列出的所有文件。
如果 .nexus-map/ 不存在，且当前任务涉及跨模块修改或接口变更，先向用户提议运行 nexus-mapper；若用户需立即开始，至少先运行 query_graph.py --summary 建立结构感知。
当任务改变了项目的结构认知（系统边界、入口、依赖关系），在交付前评估是否需要更新 .nexus-map。
按需查询工具（PROBE 辅助） scripts/query_graph.py 读取 raw/ast_nodes.json，零额外依赖（纯 Python 标准库）。
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --file <path>
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --who-imports <mod>
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --impact <path>
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --impact <path> --git-stats <git_stats.json>
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --hub-analysis
python $SKILL_DIR /scripts/query_graph.py <ast_nodes.json> --summary
阶段 推荐查询 用途 REASON --hub-analysis数据验证核心系统假说，不靠目录名猜测 OBJECT --impact --git-stats验证边界假设，查看真实上下游依赖 EMIT --summary, --file生成 systems.md / dependencies.md 的数据支撑
各查询模式的核心价值：--hub-analysis 用于 REASON 期验证架构假说；--impact --git-stats 用于 OBJECT 期量化边界风险；--summary 与 --file 用于 EMIT 期生成精确数据支撑。
