{
"canonical_name": "abhigyanpatwari/GitNexus",
"compilation_id": "pack_f4e5a85ca3684d2badbbfd080366c44f",
"created_at": "2026-05-19T05:57:10.598482+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install -g gitnexus` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install -g gitnexus",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_e0ef6aab3f61406597df3ec16439aefd"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_4842c0bcb05a3e9ca0869761521a95e1",
"canonical_name": "abhigyanpatwari/GitNexus",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/abhigyanpatwari/GitNexus",
"slug": "gitnexus",
"source_packet_id": "phit_8d513b4cc2ee48bab92c98267ef23313",
"source_validation_id": "dval_728adcfc41dd4b1bbe14dc63f4032755"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 local_cli的用户",
"github_forks": 4350,
"github_stars": 38039,
"one_liner_en": "GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration",
"one_liner_zh": "GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:knowledge, rag, graph"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "GitNexus",
"title_zh": "GitNexus 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_8d513b4cc2ee48bab92c98267ef23313",
"page_model": {
"artifacts": {
"artifact_slug": "gitnexus",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install -g gitnexus",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/abhigyanpatwari/GitNexus#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f5cfc2c1ce264d6ab4928a417c66e389 | https://github.com/abhigyanpatwari/GitNexus/issues/1518 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f9b5bf45777e4195a5b65bec8eb05125 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_36bbed40ba504142b4564a0335aa0b91 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to install GitNexus in Mac",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fbf96b8de8644eb9b2c948cdc732d96c | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Unable to install GitNexus in Mac",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f7ed64eb318442009c0c45bd394f15e7 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_8498a2d89f154c749aac4e7486f4d1f6 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4b1ddd7fb9104e66b60f9d726b19d298 | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_a2a4f1ac62124129844a1b1664fecdff | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_d6aff7caa0db4beda6fe67cb86b7ccdd | https://github.com/abhigyanpatwari/GitNexus/issues/1542 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b7e053347355476db324ef874ef9991c | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_1438bc0fa83941fc6074de2c5412cd25 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing. Context: Observed when using windows",
"title": "失败模式：installation: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing",
"user_impact": "Developers may fail before the first successful local run: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing"
},
{
"body": "Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_ebb5d6efaf48e8d879678b8a170aacf8 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"failure_mode_cluster:github_issue | fmev_de5b96783d1677ac281ee6c73055380b | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Context: Observed when using node, windows",
"title": "失败模式：installation: MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"user_impact": "Developers may fail before the first successful local run: MCP error with Claude: Failed to reconnect to gitnexus: -32000"
},
{
"body": "Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.12",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_ad68a701c98e79e3531d2d8292fd6acb | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.12 | Release Candidate v1.6.6-rc.12"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.12. Context: Observed when using node, windows",
"title": "失败模式：installation: Release Candidate v1.6.6-rc.12",
"user_impact": "Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.12"
},
{
"body": "Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.13",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_691d71a9a9f7c1da63532e7f4913d598 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.13 | Release Candidate v1.6.6-rc.13"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.13. Context: Observed when using node, windows",
"title": "失败模式：installation: Release Candidate v1.6.6-rc.13",
"user_impact": "Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.13"
},
{
"body": "Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.14",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_fe26658ac0f7dbfc1389758a44d9f3ac | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.14 | Release Candidate v1.6.6-rc.14"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.14. Context: Observed when using node, windows",
"title": "失败模式：installation: Release Candidate v1.6.6-rc.14",
"user_impact": "Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.14"
},
{
"body": "Developers should check this installation risk before relying on the project: Unable to install GitNexus in Mac",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_e8a618cc1ed2879b84e81b16d9f8d995 | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | Unable to install GitNexus in Mac"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Unable to install GitNexus in Mac. Context: Observed when using node, macos",
"title": "失败模式：installation: Unable to install GitNexus in Mac",
"user_impact": "Developers may fail before the first successful local run: Unable to install GitNexus in Mac"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 38 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 114,
"forks": 4350,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 38039
},
"source_url": "https://github.com/abhigyanpatwari/GitNexus",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration",
"title": "GitNexus 能力包",
"trial_prompt": "# GitNexus - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for abhigyanpatwari/GitNexus.\n\nProject:\n- Name: GitNexus\n- Repository: https://github.com/abhigyanpatwari/GitNexus\n- Summary: GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to GitNexus. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-integration: MCP Integration. Produce one small intermediate artifact and wait for confirmation.\n5. indexing-pipeline: Indexing Pipeline. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/abhigyanpatwari/GitNexus\n- https://github.com/abhigyanpatwari/GitNexus#readme\n- gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-impact-analysis/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-pr-review/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md\n- gitnexus-cursor-integration/skills/gitnexus-debugging/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: MCP error with Claude: Failed to reconnect to gitnexus: -32000（https://github.com/abhigyanpatwari/GitNexus/issues/1683）；github/github_issue: [Bug] Incorrect edge relationships when duplicate package, class, and me（https://github.com/abhigyanpatwari/GitNexus/issues/1680）；github/github_issue: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently （https://github.com/abhigyanpatwari/GitNexus/issues/1431）；github/github_issue: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ （https://github.com/abhigyanpatwari/GitNexus/issues/1444）；github/github_issue: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB per（https://github.com/abhigyanpatwari/GitNexus/issues/1674）；github/github_issue: [Bug] Incorrect edge relationships when duplicate package, class, and me（https://github.com/abhigyanpatwari/GitNexus/issues/1680）；github/github_issue: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB per（https://github.com/abhigyanpatwari/GitNexus/issues/1674）；github/github_issue: MCP error with Claude: Failed to reconnect to gitnexus: -32000（https://github.com/abhigyanpatwari/GitNexus/issues/1683）；github/github_issue: Windows: FTS skip-guard too aggressive when extension is locally install（https://github.com/abhigyanpatwari/GitNexus/issues/1690）；github/github_issue: GitNexus Enterprise for open source（https://github.com/abhigyanpatwari/GitNexus/issues/1685）；github/github_issue: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_（https://github.com/abhigyanpatwari/GitNexus/issues/1472）；github/github_issue: cpp SFINAE: expand type_traits predicate registry (Tier A)（https://github.com/abhigyanpatwari/GitNexus/issues/1629）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1683"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug] Incorrect edge relationships when duplicate package, class, and me",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1680"
},
{
"kind": "github_issue",
"source": "github",
"title": "WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently ",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1431"
},
{
"kind": "github_issue",
"source": "github",
"title": "GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ ",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1444"
},
{
"kind": "github_issue",
"source": "github",
"title": "Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB per",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1674"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug] Incorrect edge relationships when duplicate package, class, and me",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1680"
},
{
"kind": "github_issue",
"source": "github",
"title": "Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB per",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1674"
},
{
"kind": "github_issue",
"source": "github",
"title": "MCP error with Claude: Failed to reconnect to gitnexus: -32000",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1683"
},
{
"kind": "github_issue",
"source": "github",
"title": "Windows: FTS skip-guard too aggressive when extension is locally install",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1690"
},
{
"kind": "github_issue",
"source": "github",
"title": "GitNexus Enterprise for open source",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1685"
},
{
"kind": "github_issue",
"source": "github",
"title": "bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1472"
},
{
"kind": "github_issue",
"source": "github",
"title": "cpp SFINAE: expand type_traits predicate registry (Tier A)",
"url": "https://github.com/abhigyanpatwari/GitNexus/issues/1629"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration",
"effort": "安装已验证",
"forks": 4350,
"icon": "search",
"name": "GitNexus 能力包",
"risk": "可发布",
"slug": "gitnexus",
"stars": 38039,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"评测体系"
],
"thumb": "blue",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/abhigyanpatwari/GitNexus 项目说明书\n\n生成时间：2026-05-16 01:16:25 UTC\n\n## 目录\n\n- [Introduction to GitNexus](#introduction)\n- [Quick Start Guide](#quick-start)\n- [Key Concepts](#key-concepts)\n- [System Architecture](#system-architecture)\n- [Package Structure](#package-structure)\n- [MCP Integration](#mcp-integration)\n- [Multi-Repo Registry Architecture](#multi-repo-registry)\n- [Indexing Pipeline](#indexing-pipeline)\n- [Knowledge Graph](#knowledge-graph)\n- [Search System](#search-system)\n\n\n\n## Introduction to GitNexus\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Quick Start Guide](#quick-start), [Key Concepts](#key-concepts)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)\n- [src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)\n- [src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/tree-sitter/parser-loader.ts)\n- [src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/scope-extractor.ts)\n- [src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)\n- [src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)\n- [src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [src/mcp/resources.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/resources.ts)\n- [src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/repo-manager.ts)\n- [src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/grpc-patterns/node.ts)\n- [src/core/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/http-patterns/php.ts)\n- [gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n\n# Introduction to GitNexus\n\nGitNexus is a local-first code intelligence platform that transforms source code repositories into interactive, queryable knowledge graphs. It provides developers with deep visibility into code relationships, symbol dependencies, execution flows, and cross-repository impact analysis.\n\n## What is GitNexus?\n\nGitNexus is a graph-based code analysis tool that:\n\n- **Clones and indexes GitHub repositories** locally on your machine\n- **Parses source code** across multiple programming languages using tree-sitter grammars\n- **Builds a knowledge graph** representing symbols, imports, inheritance, and call relationships\n- **Provides AI-powered tools** for querying, refactoring, and understanding code impact\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx:12-14]()\n\nThe system operates with a clear data-privacy guarantee: public repositories are cloned locally, parsed entirely on your machine, and no data leaves your environment. 资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx:26-27]()\n\n## Installation and Setup\n\n### Prerequisites\n\n| Requirement | Version |\n|-------------|---------|\n| Node.js | 18+ |\n| npm | Latest stable |\n| Git | Configured with remote origin |\n\n### Quick Start\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx:20-21]()\n\nAfter starting the server, the web interface automatically detects when the server is ready and opens the graph visualization without requiring page refresh. 资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx:39-41]()\n\n## Architecture Overview\n\nGitNexus follows a modular architecture with distinct phases for code ingestion, graph construction, and query execution.\n\n```mermaid\ngraph TD\n subgraph Ingestion[\"Ingestion Pipeline\"]\n CLONE[Git Clone] --> PARSE[Code Parsing]\n PARSE --> EXTRACT[Symbol Extraction]\n EXTRACT --> EMIT[Graph Emission]\n end\n \n subgraph Analysis[\"Analysis Engine\"]\n EMIT --> INDEX[Workspace Index]\n INDEX --> RESOLVE[Scope Resolution]\n RESOLVE --> MODEL[Semantic Model]\n end\n \n subgraph Query[\"Query Layer\"]\n MODEL --> MCP[Model Context Protocol]\n MCP --> TOOLS[AI Tools]\n end\n```\n\n### Supported Languages\n\nGitNexus uses tree-sitter for language-agnostic parsing. The following languages are supported through grammar loaders: 资料来源：[src/core/tree-sitter/parser-loader.ts:31-48]()\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | tree-sitter-javascript | Core language |\n| TypeScript | tree-sitter-typescript | Full type support |\n| TSX | tree-sitter-typescript | React JSX syntax |\n| Python | tree-sitter-python | Indentation-based parsing |\n| PHP | tree-sitter-php | Laravel patterns supported |\n\nGrammar loading is centralized in a single registry table. Adding or removing a grammar requires only one entry modification—no scattered conditional spreads or per-grammar branches. 资料来源：[src/core/tree-sitter/parser-loader.ts:21-30]()\n\n## Core Pipeline Phases\n\n### 1. Manifest Extraction\n\nThe manifest extraction phase processes `group.yaml` configuration files to identify cross-repository symbol references.\n\n```mermaid\nflowchart TD\n LINKS[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol]\n RES --> OK{found?}\n OK -->|yes| REF[Real symbol uid + ref]\n OK -->|no| SYN[Synthetic uid manifest::repo::cid]\n REF --> EMIT[Emit Contract + CrossLink]\n SYN --> EMIT\n EMIT --> BRIDGE[Bridge query #795]\n```\n\nLabel-scoped queries in `resolveSymbol` prevent accidental cross-matches using context-aware node types: 资料来源：[src/core/group/PIPELINE.md:14-24]()\n\n- `topic` → `(n:Function|Method|Class|Interface)`\n- `grpc` method → `(n:Function|Method)`, service → `(n:Class|Interface)`\n- `lib` → `(n:Package|Module)`\n\n### 2. Language-Specific Pattern Extraction\n\nGitNexus includes specialized extractors for framework-specific patterns:\n\n#### gRPC Patterns (Node.js/TypeScript)\n\nThe gRPC pattern extractor compiles tree-sitter queries for common protobuf service patterns: 资料来源：[src/core/group/extractors/grpc-patterns/node.ts:1-38]()\n\n| Pattern | Purpose |\n|---------|---------|\n| `grpcMethod` | Detects RPC method definitions |\n| `grpcClient` | Identifies `@GrpcClient(...)` decorator usage |\n| `getService` | Finds `getService()` calls |\n| `newSimpleCtor` | Matches simple constructor patterns |\n| `newQualifiedCtor` | Matches qualified constructor patterns |\n| `loadPackageDefinition` | Detects `loadPackageDefinition()` usage |\n\nBundles are pre-compiled for JavaScript, TypeScript, and TSX: 资料来源：[src/core/group/extractors/grpc-patterns/node.ts:40-42]()\n\n#### HTTP Patterns (PHP)\n\nPHP extraction supports common web frameworks: 资料来源：[src/core/group/extractors/http-patterns/php.ts:1-45]()\n\n| Pattern | Framework | Query Target |\n|---------|-----------|--------------|\n| `laravelRoute` | Laravel | Route definitions |\n| `httpFacade` | Laravel | HTTP facade calls |\n| `guzzleMember` | Guzzle | HTTP client usage |\n| `fileGetContents` | PHP Core | File read operations |\n\n### 3. Scope Extraction\n\nThe scope extraction phase builds the fundamental parse representation used throughout the pipeline.\n\n```mermaid\nflowchart LR\n subgraph Input[\"LanguageProvider Hooks\"]\n RSK[resolveScopeKind]\n BSF[bindingScopeFor]\n II[interpretImport]\n ITB[interpretTypeBinding]\n CC[classifyCallForm]\n end\n \n subgraph Process[\"ScopeExtractor\"]\n Input --> EXTRACT[extract function]\n EXTRACT --> PF[ParsedFile]\n end\n \n PF --> OUTPUT[ownedDefs referenceSites parsedImports]\n```\n\nThe `ScopeExtractorHooks` interface declares the exact subset of `LanguageProvider` methods used, enabling targeted testing and explicit dependency contracts. 资料来源：[src/core/ingestion/scope-extractor.ts:38-56]()\n\n### 4. Heritage Processing (Inheritance Analysis)\n\nThe heritage processor resolves inheritance relationships across the codebase:\n\n```mermaid\ngraph LR\n IMP[implements] --> MAP[heritage-map.ts]\n EXT[extends] --> MAP\n MAP --> RESOLVE[resolveExtendsType]\n RESOLVE --> EMIT[implements relationship to implementor files]\n```\n\nInheritance handling is language-aware with configurable strategies. For `extends` relationships, the system determines whether to treat them as implementation relationships based on language-specific conventions. 资料来源：[src/core/ingestion/heritage-processor.ts:18-29]()\n\n### 5. Reference Emission\n\nReferences connect code locations to the symbols they use:\n\n```mermaid\nflowchart TD\n REF[Reference] --> RESOLVE[Resolve caller def]\n RESOLVE --> WALK[Walk up scope tree]\n WALK --> FOUND{Found Function-like?}\n FOUND -->|yes| EMIT[Emit edge to caller]\n FOUND -->|no| FALLBACK[Use innermost ancestor scope]\n FALLBACK --> SKIP[Skip if no def found]\n```\n\nReference emission optionally flushes scope trees when `INGESTION_EMIT_SCOPES=1` is set, creating: 资料来源：[src/core/ingestion/emit-references.ts:26-35]()\n\n- `Scope` nodes for every scope in the tree\n- `CONTAINS` edges from parent to child scope\n- `DEFINES` edges from scope to owned definitions\n- `IMPORTS` edges from scope to target modules\n\n### 6. Workspace Index Construction\n\nThe workspace index provides efficient reverse-lookups for scope-based queries:\n\n| Map | Purpose |\n|-----|---------|\n| `classScopeByDefId` | Class def `nodeId` → class `Scope` |\n| `classScopeIdToDefId` | Class `Scope.id` → class def `nodeId` |\n\nThe `classScopeIdToDefId` inverse map enables the implicit-`this` overload picker to skip O(C) reverse scans. 资料来源：[src/core/ingestion/scope-resolution/workspace-index.ts:18-27]()\n\n## MCP Tools (Model Context Protocol)\n\nGitNexus exposes AI tooling through the Model Context Protocol: 资料来源：[src/mcp/resources.ts:15-27]()\n\n| Tool | Capability |\n|------|------------|\n| `query` | Process-grouped code intelligence—execution flows related to a concept |\n| `context` | 360-degree symbol view—categorized refs, processes it participates in |\n| `impact` | Symbol blast radius—what breaks at depth 1/2/3 with confidence |\n| `detect_changes` | Git-diff impact—what do your current changes affect |\n| `rename` | Multi-file coordinated rename with confidence-tagged edits |\n| `cypher` | Raw graph queries |\n| `list_repos` | Discover indexed repositories |\n\n### MCP Resources\n\nEach indexed repository exposes structured resources:\n\n```\ngitnexus://repo/{name}/context → Stats, staleness check\ngitnexus://repo/{name}/clusters → All functional areas\ngitnexus://repo/{name}/processes → All execution flows\ngitnexus://repo/{name}/schema → Graph schema for Cypher\n```\n\n资料来源：[src/mcp/resources.ts:29-33]()\n\n## Repository Management\n\nThe `repo-manager.ts` module handles repository registration and working directory matching:\n\n```mermaid\ngraph TD\n REG[Register Repo] --> CWDMATCH[CwdMatch Check]\n CWDMATCH --> MATCH{Result}\n MATCH -->|path| SAME[Same directory tree]\n MATCH -->|sibling-by-remote| SIBLING[Different clone same remote]\n MATCH -->|none| NONE[No relationship]\n SIBLING --> DRIFT[Calculate commit drift]\n DRIFT --> HINT[Optional warning]\n```\n\nThe `CwdMatch` interface captures: 资料来源：[src/storage/repo-manager.ts:14-37]()\n\n- Whether `cwd` is the registered path, a sibling clone, or unrelated\n- The git toplevel when `cwd` is inside a work tree\n- HEAD commit information for drift calculation\n- Human-readable warnings when drift is detected\n\n## Git Integration\n\nGitNexus integrates with Git for repository identification and naming: 资料来源：[src/storage/git.ts:14-26]()\n\n```typescript\nhasGitDir(dirPath) // Check for .git directory\ngetRemoteOriginUrl(repoPath) // Read remote.origin.url\nsanitizeRepoName(name) // Prevent argument injection\n```\n\nThe `sanitizeRepoName` function:\n1. Strips leading dashes to prevent git command-line argument injection\n2. Replaces filesystem-unsafe characters across Windows/macOS/Linux\n\n资料来源：[src/storage/git.ts:45-52]()\n\n## Web Interface\n\n### Graph Visualization\n\nThe interactive graph displays code relationships with visual encoding: 资料来源：[gitnexus-web/src/components/HelpPanel.tsx:7-9]()\n\n| Visual Element | Meaning |\n|----------------|---------|\n| Node size | Connection count—larger nodes are depended on by more files |\n| Edge direction | Points from importer → imported |\n| Edge color | Relationship type (import, call, inheritance) |\n\n### Status Bar\n\nThe status bar displays indexing progress and repository state:\n\n- Progress bar during analysis phases\n- \"Ready\" indicator when idle\n- Sponsor link for community support\n\n资料来源：[gitnexus-web/src/components/StatusBar.tsx:7-18]()\n\n## Cross-Impact Analysis\n\nWhen analyzing symbol changes, GitNexus computes affected code across repositories:\n\n```mermaid\nflowchart TD\n CHANGE[User changes symbol S in repo R] --> LOCAL[Local impact engine per-repo uid expansion]\n LOCAL --> IDS[Affected uid set]\n IDS --> BRIDGE[Bridge query MATCH Contract WHERE uid IN ids]\n BRIDGE --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n OTHER --> FDO[Fan-out impact to consuming repo]\n```\n\nThis enables understanding how a change in one service affects dependent services through contract relationships. 资料来源：[src/core/group/PIPELINE.md:31-40]()\n\n## Semantic Model Contract\n\nThe scope resolution pipeline enforces a single source of truth: 资料来源：[src/core/ingestion/scope-resolution/contract/scope-resolver.ts:48-57]()\n\n> `ParsedFile` is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline.\n\nKey invariants:\n- Symbol-indexed lookups live on `SemanticModel` for the entire codebase\n- Scope-shaped lookups (which `SemanticModel` doesn't carry) live on `WorkspaceResolutionIndex`\n- Edges from `runScopeResolution` and legacy DAG are indistinguishable to downstream consumers\n\n## Summary\n\nGitNexus provides a comprehensive code intelligence platform with:\n\n- **Multi-language parsing** via tree-sitter grammars\n- **Framework-specific pattern detection** for gRPC, Laravel, Guzzle\n- **Scope-aware reference resolution** with heritage tracking\n- **AI-accessible tooling** through MCP\n- **Cross-repository impact analysis** through contract graphs\n- **Local-first architecture** ensuring data privacy\n\nThe system is designed for extensibility—adding new language support requires only grammar registration, and new framework patterns can be dropped into the extractors without modifying the orchestration pipeline.\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to GitNexus](#introduction), [MCP Integration](#mcp-integration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [RUNBOOK.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md)\n- [gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md)\n- [gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n- [gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n- [gitnexus-web/src/components/DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n- [gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n\n# Quick Start Guide\n\n## Overview\n\nGitNexus is a local-first code analysis tool that clones GitHub repositories, parses source code, and builds an interactive knowledge graph directly in your browser. The tool operates entirely on your machine—no data leaves your computer during analysis.\n\n资料来源：[gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md)\n\n## System Requirements\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Node.js | 18.0.0+ | Runtime for the backend server |\n| npm | 9.0.0+ | Package manager |\n| Supported OS | macOS, Linux, Windows | Platform for running the server |\n| Web Browser | Modern browser | Chrome, Firefox, Edge, or Safari |\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## Installation Options\n\nGitNexus supports two installation methods depending on your workflow preferences.\n\n### Global Installation (Recommended)\n\nInstall GitNexus globally using npm for command-line access from any directory:\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Local Installation\n\nFor project-specific usage, install locally within your project directory:\n\n```bash\nnpm install gitnexus\nnpx gitnexus serve\n```\n\n## Getting Started Workflow\n\nThe onboarding process follows a three-step workflow that automatically connects the web interface to the backend server.\n\n```mermaid\nflowchart TD\n A[Install GitNexus] --> B[Start Server]\n B --> C[Auto-detect Server]\n C --> D[Open Graph UI]\n \n A1[Global: npm install -g] --> B\n A2[Local: npm install] --> B\n \n B --> B1[gitnexus serve]\n B1 --> B2[Server running on port]\n \n C --> C1[Backend Polling]\n C1 --> C2[Connection Established]\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Step 1: Install and Run\n\nOpen a terminal at your project root, then install GitNexus and start the server:\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\nThe server will initialize and begin listening for connections from the web interface.\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Step 2: Wait for Server Startup\n\nThe web interface automatically detects when the server is ready through backend polling. A progress indicator shows the connection status while waiting.\n\n| State | Description |\n|-------|-------------|\n| `onboarding` | Initial state, awaiting server connection |\n| `analyze` | Server detected, ready for repository analysis |\n| `landing` | Server connected with indexed repositories |\n| `loading` | Processing in progress |\n| `success` | Analysis complete |\n\n资料来源：[gitnexus-web/src/components/DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n### Step 3: Auto-Connect\n\nThe page automatically detects the running server and establishes a WebSocket connection. No page refresh is required—the graph UI loads once the connection is established.\n\n## Analyzing a Repository\n\nAfter connecting to the server, you can analyze any public GitHub repository.\n\n```mermaid\nflowchart LR\n A[Enter GitHub URL] --> B[Server Clones Repo]\n B --> C[Parse Code Structure]\n C --> D[Build Knowledge Graph]\n D --> E[Interactive UI]\n```\n\n### Supported Repository Types\n\n| Type | Support | Notes |\n|------|---------|-------|\n| Public Repositories | ✅ Full | Clone and analyze available |\n| Private Repositories | ❌ Not supported | Requires authentication (future) |\n| Local Repositories | ✅ Via server path | Mounted directories on server machine |\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n### Analysis Workflow\n\n1. **Enter Repository URL**: Paste a GitHub repository URL into the input field\n2. **Start Analysis**: Click the analyze button to begin processing\n3. **Monitor Progress**: View real-time progress with phase indicators\n4. **Cancel if Needed**: Stop analysis at any point before completion\n\n```typescript\n// Analysis phases observed in the codebase\ntype AnalysisPhase = \n | 'cloning' // Repository being cloned\n | 'parsing' // Code being parsed\n | 'indexing' // Building graph index\n | 'complete'; // Analysis finished\n```\n\n资料来源：[gitnexus-web/src/components/StatusBar.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/StatusBar.tsx)\n\n### Privacy and Data Handling\n\n> Public repos only · Cloned locally by the server · No data leaves your machine\n\nRepositories are cloned directly to your local machine. Code parsing and graph generation occur locally without external data transmission.\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n## Managing Multiple Repositories\n\nWhen multiple repositories have been analyzed, you can switch between them using the repository dropdown in the header.\n\n```mermaid\nflowchart TD\n A[Repository Dropdown] --> B{Select Repo}\n B -->|Same Repo| C[Stay on Current View]\n B -->|Different Repo| D[Switch Repository]\n D --> E[Load New Graph]\n \n F[Active Repository] --> G[Highlighted with accent]\n H[Other Repositories] --> I[Normal styling]\n```\n\n### Repository Selection UI\n\n| Element | Visual Indicator | Behavior |\n|---------|------------------|----------|\n| Active repo | `border-l-2 border-accent` with accent background | Current selection |\n| Other repos | Hover state with `hover:bg-hover` | Clickable to switch |\n| Re-analyze button | Available per repository | Trigger fresh analysis |\n\n资料来源：[gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n### Switching Repositories\n\n1. Open the repository dropdown menu\n2. Click on any repository name\n3. The graph view updates automatically to show the selected repository's knowledge graph\n4. The dropdown closes after selection\n\n```typescript\n// Header component handles repo switching\nonClick={() => {\n if (repo.name !== projectName) onSwitchRepo?.(repo.name);\n setIsRepoDropdownOpen(false);\n}}\n```\n\n## Troubleshooting\n\n### Server Detection Issues\n\nIf the web interface fails to detect the running server:\n\n| Symptom | Solution |\n|---------|----------|\n| \"Connecting...\" message persists | Verify server is running with `gitnexus serve` |\n| Server on different port | Ensure default port is not blocked |\n| Browser console errors | Check WebSocket connection in developer tools |\n\n### Analysis Failures\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| Validation error | Invalid GitHub URL format | Enter a valid `https://github.com/user/repo` URL |\n| Network timeout | Large repository | Retry or clone locally and use local path |\n| Parse errors | Unsupported language | Check supported languages list |\n\n资料来源：[gitnexus-web/src/components/RepoAnalyzer.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/RepoAnalyzer.tsx)\n\n## Configuration\n\n### Backend Server Configuration\n\nThe server can be configured via environment variables or command-line arguments:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--port` | 3001 | Server listening port |\n| `--host` | localhost | Server bind address |\n| `--data-dir` | ~/.gitnexus | Local storage for cloned repos |\n\n资料来源：[RUNBOOK.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md)\n\n### Frontend Settings\n\nThe web interface provides configuration options through the Settings panel:\n\n- **API Provider Selection**: Choose between Ollama and other providers\n- **Model Configuration**: Set the language model for Graph RAG features\n- **Connection Testing**: Verify backend connectivity\n\n## Next Steps\n\nAfter completing the quick start:\n\n| Task | Description |\n|------|-------------|\n| Explore the Graph | Navigate nodes, zoom, and pan to explore code relationships |\n| Search Symbols | Use the search feature to find functions, classes, and imports |\n| View Dependencies | Click nodes to see import/export relationships |\n| Enable AI Features | Configure Ollama in settings for Graph RAG capabilities |\n| Re-analyze Repos | Use the re-analyze button to refresh repository data |\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n---\n\n\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Knowledge Graph](#knowledge-graph), [Indexing Pipeline](#indexing-pipeline), [MCP Integration](#mcp-integration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/types.ts)\n- [gitnexus/src/core/embeddings/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/types.ts)\n- [gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/utils/ast-helpers.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/utils/ast-helpers.ts)\n- [gitnexus/src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n- [gitnexus/src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/grpc-patterns/node.ts)\n- [gitnexus/src/core/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.ts)\n\n\n# Key Concepts\n\nGitNexus is a sophisticated code repository analysis platform that combines AST-based parsing, dependency graph construction, and semantic embeddings to provide deep insights into codebase architecture. This page covers the fundamental concepts and data structures that power GitNexus's analysis capabilities.\n\n---\n\n## Graph Data Model\n\nThe graph model forms the core of GitNexus's representation of codebases. Every symbol, import, and relationship in a repository is abstracted into graph nodes and edges.\n\n### Node Types\n\nThe graph supports multiple node types representing different code constructs:\n\n| Node Type | Description | Examples |\n|-----------|-------------|----------|\n| `Class` | Class/struct definitions | `class UserService`, `struct Point` |\n| `Interface` | Interface/type definitions | `interface IRepository`, `trait EventHandler` |\n| `Function` | Function/method definitions | `function calculateTotal()`, `def process()` |\n| `Method` | Class/instance methods | `void sendEmail()`, `async def fetch()` |\n| `Module` | File-level modules/packages | `namespace App\\Services`, `module db` |\n| `Package` | Package/module declarations | `package main`, `module foo` |\n\n### Edge Types\n\nEdges represent relationships between nodes:\n\n| Edge Type | Direction | Description |\n|-----------|-----------|-------------|\n| `imports` | importer → imported | Direct import/require statements |\n| `calls` | caller → callee | Function/method invocations |\n| `extends` | subclass → parent | Inheritance relationships |\n| `implements` | impl → interface | Interface implementation |\n| `uses` | consumer → provider | Framework/annotation usage |\n| `contains` | container → contained | Structural containment |\n\n### Node Identifiers\n\nNodes are identified using a deterministic ID scheme:\n\n```typescript\ngenerateId(nodeType: string, uniqueKey: string): string\n```\n\nThe `uniqueKey` typically combines the file path with the symbol name, ensuring uniqueness across the codebase.\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n---\n\n## Ingestion Pipeline\n\nThe ingestion pipeline is a multi-phase system that transforms raw source code into structured graph data.\n\n### Phase Overview\n\n```mermaid\nflowchart TD\n subgraph Phase1[Phase 1: Discovery]\n SC[Scan Files] --> PL[Parse Languages]\n PL --> ID[Identify Code Units]\n end\n \n subgraph Phase2[Phase 2: Extraction]\n ID --> HA[Heritage Analysis]\n HA --> CA[Call Analysis]\n end\n \n subgraph Phase3[Phase 3: Linking]\n CA --> RI[Resolve Imports]\n RI --> XR[Cross-Repo Links]\n end\n \n subgraph Phase4[Phase 4: Indexing]\n XR --> EMB[Generate Embeddings]\n EMB --> STORE[Persist to Database]\n end\n```\n\n### Heritage Processing\n\nHeritage processing extracts inheritance relationships from source code. The `HeritageMap` maintains parent-child relationships across multiple inheritance scenarios:\n\n```typescript\ninterface ParentEntry {\n readonly kind: 'extends' | 'implements';\n readonly parentName: string;\n readonly filePath: string;\n}\n```\n\nThe heritage processor handles:\n\n- **Simple inheritance**: Single class extension\n- **Multiple inheritance**: Multiple parent classes (with C3 linearization for languages supporting it)\n- **Interface implementation**: Distinguishing between `extends` and `implements` based on language semantics\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-50]()\n\n### Call Processing\n\nThe call processor analyzes function invocations and return types across file boundaries:\n\n| Phase | Purpose |\n|-------|---------|\n| P (per-file) | Build type environment and resolve local calls |\n| E1-E3 (cross-file) | Accumulate imported bindings, return types, and type maps |\n| Registry Primary | Languages using built-in registry skip certain phases |\n\nThe processor uses a local-first resolution strategy, preferring local symbol matches over imported ones:\n\n```typescript\n// Consulted ONLY when SymbolTable has no unambiguous match\nimportedReturnTypesMap?: ReadonlyMap>\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-80]()\n\n---\n\n## Pattern Extraction System\n\nGitNexus uses a pattern-based extraction system that allows framework and language-specific analyzers to be added without modifying the core orchestrator.\n\n### Pattern Bundle Architecture\n\nEach language/framework combination defines a `PatternBundle` containing compiled tree-sitter queries:\n\n```typescript\ninterface GrpcPatternBundle {\n grpcMethod: CompiledPatterns>;\n grpcClient: CompiledPatterns>;\n getService: CompiledPatterns>;\n newSimpleCtor: CompiledPatterns>;\n newQualifiedCtor: CompiledPatterns>;\n loadPackageDefinition: CompiledPatterns>;\n}\n```\n\n### Language-Specific Extractors\n\nThe system supports multiple language extractors:\n\n#### JavaScript/TypeScript gRPC Patterns\n\nExtracts gRPC service definitions from Node.js/TypeScript codebases:\n\n- `grpcMethod`: gRPC method declarations\n- `grpcClient`: Client instantiation patterns\n- `getService`: Service retrieval patterns\n\n#### PHP HTTP Patterns\n\nHandles PHP-specific HTTP interactions:\n\n| Pattern | Tree-sitter Query Target |\n|---------|--------------------------|\n| `laravelRoute` | Laravel route definitions |\n| `httpFacade` | HTTP facade usage |\n| `guzzleMember` | Guzzle HTTP client patterns |\n| `fileGetContents` | File reading operations |\n\n```typescript\nconst LARAVEL_ROUTE_SPEC: PatternSpec> = {\n meta: {},\n query: `\n (function_call_expression\n function: (name) @fn (#eq? @fn \"Route::get\")\n arguments: (arguments . (argument (string) @path)))\n `,\n};\n```\n\n资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-60]()\n\n### Extensibility Model\n\nAdding new language support requires only dropping a new file in `*-patterns/` and registering it in `index.ts`. The orchestrator never imports individual grammars, ensuring loose coupling.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:1-20]()\n\n---\n\n## Tree-Sitter Parser Integration\n\nGitNexus leverages tree-sitter for robust, error-tolerant parsing across multiple programming languages.\n\n### Supported Languages\n\n| Language | Package | Notes |\n|----------|---------|-------|\n| TypeScript | `tree-sitter-typescript` | Reuses TSX parser |\n| TSX | `tree-sitter-typescript` | Shares binding with TS |\n| Python | `tree-sitter-python` | Standard Python 3 syntax |\n| Java | `tree-sitter-java` | Java 17+ features |\n| C# | `tree-sitter-c-sharp` | Uses explicit subpath for Node 22 compatibility |\n| C++ | `tree-sitter-cpp` | C++20 features supported |\n| PHP | `tree-sitter-php` | PHP 8.x syntax |\n\n### Parser Loader\n\nThe parser loader provides dynamic language loading with graceful fallback:\n\n```typescript\n[SupportedLanguages.CSharp]: {\n load: () => _require('tree-sitter-c-sharp/bindings/node/index.js'),\n unavailableNote: 'C# parsing requires `tree-sitter-c-sharp/bindings/node/index.js`'\n}\n```\n\nThe explicit subpath import for C# bypasses Node 22's DEP0151 deprecation warning on bare-package imports.\n\n### AST Caching\n\nParsed ASTs are cached to avoid redundant parsing:\n\n```typescript\nlet tree = astCache.get(file.path);\nif (!tree) {\n const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent)\n });\n astCache.set(file.path, tree);\n}\n```\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-80]()\n\n---\n\n## Semantic Embeddings\n\nGitNexus provides semantic search capabilities through code embeddings, enabling natural language queries against the codebase.\n\n### WebGPU Acceleration\n\nEmbedding generation can utilize WebGPU for GPU-accelerated computation:\n\n```typescript\ninterface EmbeddingConfig {\n backend: 'webgpu' | 'wasm' | 'cpu';\n model: string;\n dimensions: number;\n}\n```\n\n### Fallback Strategy\n\nWhen WebGPU is unavailable, the system offers graceful degradation:\n\n| Option | Performance | Description |\n|--------|-------------|-------------|\n| CPU | Slow | Works universally, ~X minutes for large codebases |\n| WebAssembly | Moderate | Cross-browser compatibility |\n| WebGPU | Fast | Best performance on supported browsers |\n\nThe fallback dialog provides estimated processing time based on repository size:\n\n```typescript\n~{estimatedMinutes} min for {nodeCount} nodes\n```\n\n资料来源：[gitnexus/src/core/embeddings/types.ts]()\n\n---\n\n## Cross-Repository Impact Analysis\n\nGitNexus supports tracking dependencies and impacts across multiple repositories.\n\n### Contract System\n\nContracts define explicit dependencies between repositories:\n\n```mermaid\nflowchart TD\n Y[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol label-scoped Cypher]\n RES --> OK{found?}\n OK -->|yes| REF[real symbol uid + ref]\n OK -->|no| SYN[synthetic uid manifest::repo::cid]\n```\n\n### Cross-Impact Query Engine\n\nWhen a symbol changes in one repository, GitNexus can identify affected contracts in dependent repositories:\n\n```mermaid\nflowchart TD\n U[User changes symbol S in repo R] --> LI[Local impact engine per-repo uid expansion]\n LI --> IDS[Affected uid set]\n IDS --> BR[Bridge query MATCH Contract WHERE uid IN ids]\n BR --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n OTHER --> FE[Fan-out impact to consuming repo]\n```\n\n### Label-Scoped Resolution\n\nQueries use label-scoped matching to prevent cross-contamination:\n\n| Topic | Node Pattern |\n|-------|--------------|\n| `topic` | `(n:Function\\|Method\\|Class\\|Interface)` |\n| `grpc` method | `(n:Function\\|Method)` |\n| `grpc` service | `(n:Class\\|Interface)` |\n| `lib` | `(n:Package\\|Module)` |\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:40-80]()\n\n---\n\n## Symbol Resolution\n\n### Binding Accumulator\n\nThe binding accumulator tracks symbol-to-type mappings across the codebase:\n\n```typescript\n/** Phase 14 E1: imported bindings to seed into buildTypeEnv */\nimportedBindingsMap?: ReadonlyMap>\n```\n\n### Type Environment\n\nType resolution follows a strict priority order:\n\n1. Local symbol table matches (highest priority)\n2. Imported return types map\n3. Imported raw return types (for iteration)\n4. Cross-file heritage map fallback\n\n### AST Helpers\n\nThe AST helper utilities provide common operations across different language grammars:\n\n```typescript\ninterface ClassInfo {\n classId: string;\n className: string;\n}\n\n// Handles language-specific node traversal\nconst nameNode = children.find((c: SyntaxNode) =>\n c.type === 'type_identifier' ||\n c.type === 'identifier' ||\n c.type === 'name' ||\n c.type === 'constant'\n);\n```\n\nSpecial handling exists for:\n- Kotlin's anonymous `interface` keyword in class declarations\n- For-loop element type extraction\n- Scoped type identifiers\n\n资料来源：[gitnexus/src/core/ingestion/utils/ast-helpers.ts:1-80]()\n\n---\n\n## Architecture Summary\n\nGitNexus's architecture follows a clean separation of concerns:\n\n```mermaid\ngraph TB\n subgraph Ingestion[\"Ingestion Layer\"]\n PS[Parser Selector] --> TP[TypeScript Parser]\n PS --> PP[Python Parser]\n PS --> JP[Java Parser]\n TP --> QE[Query Engine]\n PP --> QE\n JP --> QE\n QE --> H[Heritage Map]\n QE --> C[Call Processor]\n end\n \n subgraph Pattern[\"Pattern Extraction\"]\n G[gRPC Bundle] --> E[Extractor]\n HTTP[PHP HTTP] --> E\n E --> SG[Symbol Graph]\n end\n \n subgraph Storage[\"Storage & Query\"]\n SG --> DB[(Graph DB)]\n H --> DB\n C --> DB\n end\n \n subgraph UI[\"Web Interface\"]\n DZ[DropZone] --> HX[Header]\n HX --> SB[StatusBar]\n SB --> GP[Graph Panel]\n end\n \n DB --> GP\n EMB[Embeddings] --> GP\n```\n\n### Key Design Principles\n\n1. **Registry Pattern**: Languages using built-in registries (e.g., Python, Java) skip certain processing phases\n2. **Event Loop Yielding**: Long-running operations yield to the event loop every 20 files to prevent blocking\n3. **Error-Tolerant Parsing**: Parse failures are logged and skipped without halting the entire process\n4. **Lazy Language Loading**: Tree-sitter language parsers are loaded on-demand to minimize memory footprint\n\n---\n\n## See Also\n\n- [Architecture Overview](../architecture/overview.md)\n- [Pattern Extractors](../extractors/index.md)\n- [API Reference](../api/index.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Structure](#package-structure), [Indexing Pipeline](#indexing-pipeline), [MCP Integration](#mcp-integration), [Multi-Repo Registry Architecture](#multi-repo-registry)\n\n\nRelevant Source Files\n\nThe following source files were used to generate this documentation:\n\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n- [gitnexus/src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [gitnexus-shared/src/scope-resolution/parsed-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n- [gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n\n# System Architecture\n\nGitNexus is a code analysis and visualization platform that provides dependency graph generation, scope-aware symbol resolution, and cross-repository impact analysis. The system architecture is designed around a multi-stage ingestion pipeline that transforms source code into a queryable knowledge graph.\n\n## Overview\n\nGitNexus operates as a client-server application:\n\n- **Backend Server** (`gitnexus/src/`): A Node.js server responsible for code ingestion, AST parsing, scope resolution, and graph construction\n- **Web Frontend** (`gitnexus-web/src/`): A React-based visualization layer that renders the interactive dependency graph\n\nThe architecture emphasizes separation of concerns: language-specific extraction logic is isolated from the core orchestration, enabling extensibility without modifying the main pipeline.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Core Architectural Principles\n\n### Single Source of Truth\n\nThe `ParsedFile` model (defined in `gitnexus-shared/src/scope-resolution/parsed-file.ts`) serves as the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Scope-resolution passes must not build a parallel parse representation.\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-40](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n\n### Same-Graph Guarantee\n\nEdges emitted by `runScopeResolution` and edges emitted by the legacy DAG are indistinguishable to downstream consumers:\n\n| Aspect | Legacy DAG | Scope Resolution |\n|--------|------------|-------------------|\n| Node Identity | `generateId()` with same qualified-name keyspace | Identical |\n| Edge Vocabulary | `'import-resolved' \\| 'global' \\| 'local-call' \\| 'same-file' \\| 'interface-dispatch' \\| 'read' \\| 'write'` | Identical |\n\nThis ensures transparent interoperability between both code paths.\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n\n### Language Extensibility\n\nThe orchestrator never imports a grammar directly. Adding support for a new language or framework requires only:\n\n1. Dropping one file in `*-patterns/` directory\n2. Registering it in `index.ts`\n\nNo orchestrator edits are required.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Ingestion Pipeline\n\nThe ingestion pipeline processes source code through a series of stages to build the dependency graph.\n\n```mermaid\ngraph TD\n subgraph Ingestion\n FS[File System] --> SCOPE[Scope Extractor]\n SCOPE --> PARSE[Parsing Phase]\n PARSE --> CALLS[Call Processor]\n CALLS --> HERITAGE[Heritage Processor]\n HERITAGE --> FINALIZE[Graph Finalization]\n end\n \n subgraph Language Support\n PARSER[Parser Loader] --> TS[Tree-sitter Grammars]\n TS --> LANG[Language Registry]\n LANG --> PROVIDER[Language Providers]\n end\n \n SCOPE -.-> PROVIDER\n PARSE -.-> PROVIDER\n CALLS -.-> PROVIDER\n HERITAGE -.-> PROVIDER\n```\n\n### Stage 1: Scope Extraction\n\nThe `ScopeExtractor` is the central, source-agnostic driver that converts language provider captures into `ParsedFile` artifacts.\n\n**Key responsibilities:**\n- Build scope tree from `@scope.*` matches\n- Maintain structural invariants (non-module has parent; parent contains child)\n- Produce `ParsedFile` containing: `scopes`, `parsedImports`, `localDefs`, `referenceSites`\n\n**Design principles:**\n- Source-agnostic: Consumes `CaptureMatch[]` from providers\n- One AST walk per language: Providers handle AST traversal internally\n- Pure-ish: Same matches produce same `ParsedFile` output\n- Centralized invariant enforcement via `buildScopeTree`\n\n资料来源：[gitnexus/src/core/ingestion/scope-extractor.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### Stage 2: Call Resolution\n\nThe call processor resolves function and method calls to their definitions.\n\n```mermaid\ngraph LR\n subgraph Input\n FILES[Source Files] --> LANG[Language Detection]\n end\n \n subgraph Processing\n LANG --> PARSE[Parse with Tree-sitter]\n PARSE --> QUERY[Execute Queries]\n QUERY --> MATCHES[Capture Matches]\n MATCHES --> RESOLVE[Resolve Calls to Defs]\n end\n \n subgraph Output\n RESOLVE --> EDGES[Call Edges in Graph]\n end\n```\n\n**Registry-Primary Language Gate:**\n\nFor languages marked as `isRegistryPrimary`, scope-based phase owns CALLS processing, bypassing the legacy call processor:\n\n```typescript\n// Registry-primary gate: scope-based phase owns CALLS for this lang.\nif (isRegistryPrimary(language)) continue;\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n\n### Stage 3: Heritage Processing\n\nHeritage processing resolves class inheritance relationships (`extends` and `implements`).\n\n**Heritage types:**\n- `extends` → creates `EXTENDS` relationship\n- `implements` → creates `IMPLEMENTS` relationship\n\n**Processing logic:**\n```typescript\nif (h.kind === 'extends') {\n const { type: relType, idPrefix } = resolveExtendsType(\n h.parentName,\n h.filePath,\n ctx,\n getHeritageStrategyForLanguage(fileLanguage),\n );\n // Create relationship with confidence score\n graph.addRelationship({\n type: relType,\n confidence: Math.sqrt(child.confidence * parent.confidence),\n });\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n\n### Stage 4: Heritage Map Construction\n\nThe heritage map tracks class/interface inheritance for Method Resolution Order (MRO) calculations.\n\n**Key data structures:**\n\n| Structure | Purpose |\n|-----------|---------|\n| `directParents` | `Map` — parent relationships by kind |\n| `implementorFiles` | `Map>` — tracking implementing files |\n\n**Public API:**\n- `getParentEntries(childNodeId)` → returns `readonly ParentEntry[]`\n- `getParents(childNodeId)` → returns deduplicated `string[]`\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n\n## Parser Architecture\n\n### Tree-sitter Integration\n\nGitNexus uses Tree-sitter for universal AST parsing across supported languages.\n\n**Grammar loading strategy:**\n\n```typescript\nconst SOURCES: Record = {\n [SupportedLanguages.JavaScript]: {\n load: () => _require('tree-sitter-javascript'),\n unavailableNote: 'JavaScript parsing requires `tree-sitter-javascript`...',\n },\n [SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript,\n },\n [`${SupportedLanguages.TypeScript}:tsx`]: {\n load: () => _require('tree-sitter-typescript').tsx,\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n },\n // Additional languages...\n};\n```\n\n**Configuration rules:**\n- Grammars must be in `dependencies` (not `optionalDependencies`)\n- Failures indicate real install problems and should never be hidden\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-80](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n### Supported Languages\n\nThe system supports multiple programming languages through a registry pattern:\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | `tree-sitter-javascript` | Registry-primary |\n| TypeScript | `tree-sitter-typescript` | Registry-primary |\n| TSX | `tree-sitter-typescript` | Re-uses TS binding |\n| Python | `tree-sitter-python` | Pattern-based extraction |\n| PHP | `tree-sitter-php` | Framework patterns (Laravel, Guzzle) |\n| C# | `tree-sitter-c-sharp` | Using directive decomposition |\n| Go | `tree-sitter-go` | gRPC pattern support |\n| Ruby | `tree-sitter-ruby` | MRO strategies |\n\n## Workspace Index\n\nThe workspace index provides O(totalScopes) build-time indexing for efficient runtime lookups.\n\n**Interface:**\n\n```typescript\nexport interface WorkspaceResolutionIndex {\n /** Class def `nodeId` → that class's `Scope`. */\n readonly classScopeByDefId: ReadonlyMap;\n \n /** Inverse: class `Scope.id` → class def `nodeId`. */\n readonly classScopeIdToDefId: ReadonlyMap;\n}\n```\n\n**Semantic model lookups:**\n\n| Lookup Type | Source | Purpose |\n|-------------|--------|---------|\n| Owner-keyed method | `model.methods.lookupAllByOwner` | Registry + scope-resolution |\n| Name-keyed callable | `model.symbols.lookupCallableByName` | Symbol resolution |\n| File-indexed symbol | `model.symbols.lookupExactAll` | Exact matching |\n| Scope-shaped | `WorkspaceResolutionIndex` | Implicit `this` overload picker |\n\nThis split preserves the single-source-of-truth invariant: symbol-indexed lookups live on `SemanticModel`; scope-shaped lookups live on `WorkspaceResolutionIndex`.\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## Pattern Extraction System\n\n### Language Pattern Bundles\n\nEach language has pattern bundles compiled from Tree-sitter query specifications:\n\n**Example: PHP HTTP Patterns**\n\n```typescript\nconst PHP_PATTERNS: PhpPatternBundle = {\n laravelRoute: mk(LARAVEL_ROUTE_SPEC, 'laravel-route'),\n httpFacade: mk(HTTP_FACADE_SPEC, 'http-facade'),\n guzzleMember: mk(GUZZLE_MEMBER_SPEC, 'guzzle-member'),\n fileGetContents: mk(FILE_GET_CONTENTS_SPEC, 'file-get-contents'),\n};\n```\n\n**Example: gRPC Patterns (Node.js/TypeScript)**\n\n```typescript\nconst JAVASCRIPT_BUNDLE = compileBundle(JavaScript, 'javascript-grpc');\nconst TYPESCRIPT_BUNDLE = compileBundle(TypeScript.typescript, 'typescript-grpc');\nconst TSX_BUNDLE = compileBundle(TypeScript.tsx, 'tsx-grpc');\n```\n\n**Pattern categories:**\n- HTTP route handlers\n- gRPC service clients\n- Framework-specific patterns (Laravel, Guzzle, etc.)\n- Import/export declarations\n- Call expressions\n\n资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.ts)\n\n## Data Models\n\n### ParsedFile Structure\n\n```typescript\ninterface ParsedFile {\n readonly scopes: Scope[];\n readonly parsedImports: ParsedImport[];\n readonly localDefs: LocalDef[];\n readonly referenceSites: ReferenceSite[];\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `scopes` | Every `Scope` created for this file, in tree-topological order (module first, then children) |\n| `parsedImports` | Raw `ParsedImport[]` — finalize phase resolves each to concrete `ImportEdge` |\n| `localDefs` | Defs structurally declared in this file; superset of `Scope.ownedDefs` |\n| `referenceSites` | Pre-resolution usage facts; populated by resolution phase |\n\n**What `ParsedFile` deliberately does NOT carry:**\n- Linked `ImportEdge`s (finalize output)\n- `ScopeTree` instance (callers build from `scopes`)\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n\n## Git Integration\n\nThe system integrates with Git repositories for analysis:\n\n**Key functions:**\n\n| Function | Purpose |\n|----------|---------|\n| `hasGitDir(dirPath)` | Check for `.git` directory presence |\n| `getRemoteOriginUrl(repoPath)` | Read `remote.origin.url` for repo naming |\n| `sanitizeRepoName(name)` | Prevent argument injection, ensure cross-platform compatibility |\n\n**Security considerations:**\n- Leading dashes are stripped to prevent git command-line argument injection\n- Characters unsafe for directory names are replaced with underscores\n- `execSync` uses `stdio: ['ignore', 'pipe', 'ignore']` to prevent information leakage\n\n资料来源：[gitnexus/src/storage/git.ts:1-80](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n## Manifest Extraction\n\nThe manifest extraction system links contracts across repositories:\n\n```mermaid\nflowchart TD\n Y[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol label-scoped Cypher]\n RES --> OK{found?}\n OK -->|yes| REF[real symbol uid + ref]\n OK -->|no| SYN[synthetic uid manifest::repo::cid]\n \n REF --> EMIT[emit provider + consumer Contract objects + CrossLink]\n SYN --> EMIT\n \n EMIT --> BRIDGE[(bridge.lbug #795)]\n```\n\n**Label-scoped queries** prevent accidental cross-matches:\n- `topic` → `(n:Function|Method|Class|Interface)`\n- `grpc` method → `(n:Function|Method)`, service → `(n:Class|Interface)`\n- `lib` → `(n:Package|Module)`\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Cross-Impact Query System\n\nThe cross-impact query system tracks dependencies across repository boundaries:\n\n```mermaid\nflowchart TD\n U[User changes symbol S in repo R] --> LI[Local impact engine per-repo uid expansion]\n LI --> IDS[Affected uid set]\n \n IDS --> BR[Bridge query MATCH Contract WHERE uid IN ids]\n BR --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n \n OTHER --> FE[Fan-out impact to consuming repo]\n```\n\nThis enables developers to understand the blast radius of changes across service boundaries.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Frontend Architecture\n\nThe web frontend provides the visualization layer:\n\n**Key components:**\n\n| Component | Purpose |\n|-----------|---------|\n| `Header.tsx` | Repository switching, analysis triggers |\n| `DropZone.tsx` | Server connection and repo loading |\n| `HelpPanel.tsx` | Interactive legend and search |\n| `StatusBar.tsx` | Progress tracking and sponsor links |\n| `OnboardingGuide.tsx` | First-time user setup flow |\n\n**Connection states:**\n- `onboarding` — initial setup phase\n- `analyze` — server up but no repos indexed\n- `landing` — server up with indexed repos\n- `success` / `loading` — operation in progress\n\n资料来源：[gitnexus-web/src/components/DropZone.tsx:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n## Error Handling and Resilience\n\n**Language unavailability:**\n```typescript\nif (!isLanguageAvailable(language)) {\n if (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n }\n continue;\n}\n```\n\n**Parse error handling:**\n```typescript\ntry {\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n });\n} catch (parseError) {\n continue; // Skip malformed files\n}\n```\n\n**Event loop yielding:**\n```typescript\nif (i % 20 === 0) await yieldToEventLoop();\n```\n\nFiles are processed in batches of 20 with event loop yields to prevent UI blocking during large repository analysis.\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n\n## Performance Considerations\n\n| Optimization | Mechanism |\n|-------------|-----------|\n| AST Caching | `astCache` stores parsed trees keyed by file path |\n| Preprocessing | Per-language source preprocessing (e.g., UE macro stripping for C++) |\n| Batch Processing | 20-file batches with `yieldToEventLoop()` |\n| Workspace Index | O(totalScopes) build-time indexing for O(1) runtime lookups |\n| Confidence Scoring | Geometric mean (`Math.sqrt(child.confidence * parent.confidence)`) for inheritance |\n\n## Summary\n\nGitNexus implements a modular, extensible code analysis architecture:\n\n1. **Pipeline-driven ingestion** with clearly delineated stages\n2. **Language-agnostic core** with pluggable pattern extractors\n3. **Single semantic model** ensuring consistency across analysis paths\n4. **Cross-repository impact tracking** for change propagation analysis\n5. **Tree-sitter-based parsing** with efficient grammar loading\n\nThe architecture prioritizes extensibility (new languages = new pattern files), performance (caching, batching, indexing), and correctness (invariant enforcement, same-graph guarantees).\n\n---\n\n\n\n## Package Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/package.json)\n- [gitnexus-web/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/package.json)\n- [gitnexus-shared/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/package.json)\n- [eval/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/eval/package.json)\n\n\n# Package Structure\n\nGitNexus is organized as a **monorepo** with four distinct packages, each serving a specific role in the codebase intelligence platform. The architecture separates concerns between the backend analysis engine, web interface, shared type definitions, and evaluation tooling.\n\n## Monorepo Overview\n\n```mermaid\ngraph TD\n subgraph \"GitNexus Monorepo\"\n Web[gitnexus-web React Frontend]\n Core[gitnexus Core Engine]\n Shared[gitnexus-shared Shared Types]\n Eval[eval Evaluation]\n end\n \n Web <--> Shared\n Core <--> Shared\n Core <--> Web\n Eval --> Core\n```\n\n## Package Breakdown\n\n| Package | Role | Technology |\n|---------|------|------------|\n| `gitnexus` | Core analysis engine, CLI, ingestion pipeline | Node.js, TypeScript |\n| `gitnexus-web` | Web UI, visualization, user interactions | React, TypeScript |\n| `gitnexus-shared` | Shared types, utilities, interfaces | TypeScript |\n| `eval` | Evaluation harness, benchmarking | TypeScript |\n\n## gitnexus — Core Engine\n\nThe core package is the backbone of GitNexus, handling all code analysis, parsing, and knowledge graph construction.\n\n### Directory Structure\n\n```\ngitnexus/src/\n├── cli/ # Command-line interface commands\n│ ├── index.ts # CLI entry point with command registration\n│ ├── wiki.js # Wiki generation command\n│ ├── augment.js # Search pattern augmentation\n│ └── publish.js # Registry notification\n├── core/\n│ ├── ingestion/ # Code parsing and analysis\n│ │ ├── model/ # Heritage map generation\n│ │ ├── scope-extractor.ts\n│ │ ├── heritage-processor.ts\n│ │ └── scope-resolution/\n│ │ └── workspace-index.ts\n│ ├── tree-sitter/ # Parser loader and language support\n│ │ └── parser-loader.ts\n│ └── group/ # Module extraction and contracts\n│ ├── extractors/\n│ │ └── grpc-patterns/\n│ │ └── node.ts\n│ └── PIPELINE.md\n└── storage/\n └── git.ts # Git operations utility\n```\n\n### Key Modules\n\n#### Ingestion Pipeline\n\nThe ingestion system processes source code and builds the knowledge graph:\n\n```mermaid\nflowchart TD\n A[Source Files] --> B[Language Detection]\n B --> C[Tree-sitter Parsing]\n C --> D[AST Analysis]\n D --> E[Scope Extraction]\n E --> F[Heritage Processing]\n F --> G[Knowledge Graph]\n```\n\n- **Scope Extractor** (`scope-extractor.ts`): Extracts bindings, imports, and symbol references using language-specific providers.\n- **Heritage Processor** (`heritage-processor.ts`): Resolves class inheritance and interface implementation relationships.\n- **Workspace Index** (`workspace-index.ts`): Builds O(totalScopes) index for class scope lookups.\n\n#### Tree-sitter Parser Loader\n\nThe parser loader (`parser-loader.ts`) provides language-specific parsing through tree-sitter grammars:\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | `tree-sitter-javascript` | Standard JS parsing |\n| TypeScript | `tree-sitter-typescript` | TS and TSX supported |\n| Python | `tree-sitter-python` | Python source parsing |\n| Java | `tree-sitter-java` | Java class analysis |\n| C# | `tree-sitter-c-sharp` | Uses subpath export |\n| C++ | `tree-sitter-cpp` | C++ source parsing |\n| Go | `tree-sitter-go` | Go package parsing |\n| Rust | `tree-sitter-rust` | Rust module parsing |\n| PHP | `tree-sitter-php` | Uses `php_only` export |\n| Ruby | `tree-sitter-ruby` | Ruby parsing |\n| Vue | `tree-sitter-typescript` | Reuses TypeScript grammar |\n| C | `tree-sitter-c` | Required, ABI-sensitive |\n\n资料来源：[parser-loader.ts:26-90](gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n#### CLI Commands\n\nThe CLI (`index.ts`) provides multiple commands:\n\n- `serve` — Start the backend server\n- `ingest ` — Analyze and index a repository\n- `query ` — Search the knowledge graph\n- `wiki` — Generate documentation from module structure\n- `augment ` — Add knowledge graph context to search\n- `publish [path]` — Notify registry of fresh index\n\n资料来源：[index.ts](gitnexus/src/cli/index.ts)\n\n## gitnexus-web — Frontend Application\n\nThe web package provides the interactive UI for visualizing and exploring the knowledge graph.\n\n### Component Architecture\n\n```\ngitnexus-web/src/\n└── components/\n ├── Header.tsx # Navigation, repo switching\n ├── DropZone.tsx # Server connection, initial probe\n ├── OnboardingGuide.tsx # Setup wizard\n ├── AnalyzeOnboarding.tsx # GitHub repo analyzer\n ├── HelpPanel.tsx # Contextual help, AI queries\n └── StatusBar.tsx # Progress, status indicators\n```\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Header` | Repository switching, analysis triggers, navigation |\n| `DropZone` | Server detection, backend polling, connection states |\n| `OnboardingGuide` | Step-by-step setup instructions |\n| `AnalyzeOnboarding` | GitHub URL input and cloning |\n| `HelpPanel` | Contextual help, Nexus AI integration |\n| `StatusBar` | Progress bar, ready state, sponsor link |\n\n#### Connection States\n\nThe `DropZone` component manages backend connection through polling:\n\n```typescript\ntype ConnectionPhase = 'onboarding' | 'analyze' | 'landing' | 'success' | 'loading';\n```\n\n资料来源：[DropZone.tsx](gitnexus-web/src/components/DropZone.tsx)\n\n#### Help Panel Modes\n\nThe `HelpPanel` provides contextual guidance for different exploration modes:\n\n- **Graph view** — Node size meaning, edge direction, click interactions\n- **Search & filter** — Query syntax guidance\n- **Nexus AI** — Semantic query examples, \"Semantic Ready\" status\n\n资料来源：[HelpPanel.tsx](gitnexus-web/src/components/HelpPanel.tsx)\n\n## gitnexus-shared — Shared Type System\n\nThe shared package defines TypeScript interfaces, types, and utilities used across both the core engine and web frontend.\n\n### Core Types\n\n| Type | Description |\n|------|-------------|\n| `ParsedFile` | Parsed source file with imports and definitions |\n| `ParsedImport` | Raw import statement |\n| `BindingRef` | Reference to a symbol binding |\n| `ReferenceSite` | Usage location of a symbol |\n| `Scope` | Lexical scope with owned definitions |\n| `ScopeKind` | Scope classification (module, class, function, etc.) |\n| `SymbolDefinition` | Definition of a symbol |\n| `TypeRef` | Reference to a type |\n\n资料来源：[scope-extractor.ts:1-25](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### Utility Functions\n\nThe shared package exports utility functions used throughout the codebase:\n\n- `buildPositionIndex` — Position indexing for source locations\n- `buildScopeTree` — Scope hierarchy construction\n- `canParentScope` — Scope relationship validation\n- `makeScopeId` — Scope identifier generation\n- `isClassLike` — Class-like scope detection\n\n## eval — Evaluation Harness\n\nThe eval package provides benchmarking and evaluation tooling for the analysis engine. It validates correctness of ingestion, querying, and relationship detection.\n\n## Dependency Flow\n\n```mermaid\ngraph LR\n Shared --> Core\n Shared --> Web\n Core --> Web\n Eval --> Core\n \n subgraph \"gitnexus-shared\"\n Shared\n end\n \n subgraph \"gitnexus\"\n Core\n end\n \n subgraph \"gitnexus-web\"\n Web\n end\n \n subgraph \"eval\"\n Eval\n end\n```\n\n## Data Models\n\n### LanguageProvider Interface\n\nThe `LanguageProvider` interface defines hooks for language-specific analysis:\n\n```typescript\ntype ScopeExtractorHooks = Pick<\n LanguageProvider,\n | 'resolveScopeKind'\n | 'bindingScopeFor'\n | 'interpretImport'\n | 'interpretTypeBinding'\n | 'classifyCallForm'\n>;\n```\n\n资料来源：[scope-extractor.ts:55-66](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### WorkspaceResolutionIndex\n\nBuild-time index for efficient scope lookups:\n\n```typescript\ninterface WorkspaceResolutionIndex {\n readonly classScopeByDefId: ReadonlyMap;\n readonly classScopeIdToDefId: ReadonlyMap;\n}\n```\n\n资料来源：[workspace-index.ts](gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## Adding New Language Support\n\nTo add support for a new language:\n\n1. Add grammar to `SOURCES` in `parser-loader.ts`:\n ```typescript\n [SupportedLanguages.NewLang]: {\n load: () => _require('tree-sitter-newlang'),\n unavailableNote: 'NewLang parsing requires tree-sitter-newlang.',\n },\n ```\n\n2. Register patterns in the group extractors if needed for module extraction.\n\n3. Implement language-specific hooks in `LanguageProvider` if the default extraction is insufficient.\n\n资料来源：[parser-loader.ts](gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n---\n\n\n\n## MCP Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Multi-Repo Registry Architecture](#multi-repo-registry)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/mcp/server.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/server.ts)\n- [gitnexus/src/mcp/tools.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/tools.ts)\n- [gitnexus/src/mcp/resources.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts)\n- [gitnexus/src/cli/setup.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts)\n- [gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)\n- [gitnexus/hooks/claude/gitnexus-hook.cjs](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/hooks/claude/gitnexus-hook.cjs)\n\n\n# MCP Integration\n\nGitNexus provides a Model Context Protocol (MCP) server that exposes the knowledge graph as a set of tools and resources for AI code assistants like Claude. This integration enables AI assistants to query repository structure, understand code relationships, and perform impact analysis directly within their workflow.\n\n## Overview\n\nThe MCP server operates over stdio (standard input/output), making it compatible with any editor or IDE that supports the MCP protocol. When connected, AI assistants can leverage GitNexus's indexed knowledge graph to provide context-aware responses about your codebase.\n\n```mermaid\ngraph TD\n A[\"AI Editor (Claude, Cursor, etc.)\"] -->|\"MCP Protocol stdio\"| B[\"GitNexus MCP Server\"]\n B --> C[\"gitnexus mcp\"]\n C --> D[\"Knowledge Graph DB (Indexed Repos)\"]\n \n E[\"Tool Requests\"] --> B\n B --> F[\"Query Results\"]\n \n G[\"Resource Requests\"] --> B\n B --> H[\"Repo Context Clusters Processes\"]\n```\n\n资料来源：[gitnexus/README.md:17](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L17)\n\n## Starting the MCP Server\n\n### Command-Line Usage\n\n```bash\ngitnexus mcp\n```\n\nThis starts the MCP server in stdio mode, serving all indexed repositories. The server listens for JSON-RPC requests from connected clients and returns structured responses.\n\n资料来源：[gitnexus/README.md:17](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L17)\n\n### Startup Behavior\n\nThe MCP server entry point implements intelligent binary resolution:\n\n1. **Preferred**: Uses the globally-installed `gitnexus` binary (starts in ~1 second)\n2. **Fallback**: Uses `npx -y gitnexus@` when the binary isn't on PATH\n\nThe npx fallback is slower due to cold-cache installation of native dependencies (can exceed 30 seconds), which may exceed Claude Code's MCP connection timeout. The binary path is resolved at module load time and persisted in user config.\n\n```typescript\nfunction getMcpEntry() {\n const bin = resolveGitnexusBin();\n\n if (bin) {\n return { command: bin, args: ['mcp'] };\n }\n\n // Fallback: npx (works without a global install, but slow cold-start)\n if (process.platform === 'win32') {\n return {\n command: 'cmd',\n args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],\n };\n }\n // ...\n}\n```\n\n资料来源：[gitnexus/src/cli/setup.ts:45-62](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts#L45-L62)\n\n## MCP Tools\n\nThe MCP server exposes a comprehensive set of tools for querying and manipulating the knowledge graph. Each tool corresponds to a specific capability within GitNexus.\n\n### Available Tools\n\n| Tool | Purpose | Description |\n|------|---------|-------------|\n| `query` | Process-grouped code intelligence | Find execution flows related to a concept |\n| `context` | 360-degree symbol view | View categorized refs and processes a symbol participates in |\n| `impact` | Symbol blast radius analysis | Determine what breaks at depth 1/2/3 with confidence scores |\n| `detect_changes` | Git-diff impact analysis | Analyze what your current changes affect |\n| `rename` | Multi-file coordinated rename | Perform confidence-tagged edits across files |\n| `cypher` | Raw graph queries | Execute direct Cypher queries against the graph |\n| `list_repos` | Repository discovery | List all indexed repositories |\n\n资料来源：[gitnexus/src/mcp/resources.ts:47-56](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts#L47-L56)\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Editor as AI Editor\n participant MCP as MCP Server\n participant Graph as Knowledge Graph\n \n Editor->>MCP: tool_request(query, \"auth module\")\n MCP->>MCP: Parse request & validate\n MCP->>Graph: Execute graph query\n Graph-->>MCP: Query results with execution flows\n MCP-->>Editor: Structured JSON response\n```\n\n## MCP Resources\n\nResources provide read-only access to repository metadata and graph schema information. They follow a `gitnexus://` URI scheme for addressing.\n\n### Resource Types\n\n| Resource | URI Pattern | Description |\n|----------|-------------|-------------|\n| Repository Stats | `gitnexus://repo/{name}/context` | Stats, staleness check, symbol counts |\n| Functional Clusters | `gitnexus://repo/{name}/clusters` | All functional areas and groupings |\n| Execution Flows | `gitnexus://repo/{name}/processes` | All execution flows in the repo |\n| Graph Schema | `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |\n\n### Resource Content Format\n\nEach resource returns structured Markdown documentation. For example, the `context` resource includes:\n\n```\nThis project is indexed by GitNexus as **{repo.name}** ({stats.nodes || 0} symbols, {stats.edges || 0} relationships, {stats.processes || 0} execution flows).\n```\n\n资料来源：[gitnexus/src/mcp/resources.ts:30-36](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts#L30-L36)\n\n## Editor Integration\n\n### Claude Desktop Configuration\n\nFor Claude Desktop integration, add the GitNexus MCP server to your configuration:\n\n```json\n{\n \"mcpServers\": {\n \"gitnexus\": {\n \"command\": \"gitnexus\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n### Editor Hook System\n\nGitNexus includes Claude-specific hooks that integrate with the MCP server:\n\n```mermaid\ngraph LR\n A[\"gitnexus-hook.cjs\"] -->|Integration| B[\"Claude Code\"]\n A -->|Query| C[\"Knowledge Graph\"]\n B -->|Requests| C\n```\n\nThe hook enables real-time code context awareness during editing sessions, allowing Claude to reference repository structure without manual context switching.\n\n资料来源：[gitnexus/hooks/claude/gitnexus-hook.cjs](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/hooks/claude/gitnexus-hook.cjs)\n\n## Architecture\n\n### Component Overview\n\n```mermaid\ngraph TD\n subgraph \"MCP Layer\"\n A[\"server.ts Request Handler\"] --> B[\"tools.ts Tool Registry\"]\n A --> C[\"resources.ts Resource Provider\"]\n end\n \n subgraph \"Core Services\"\n B --> D[\"runFullAnalysis\"]\n B --> E[\"WikiGenerator\"]\n C --> F[\"RepoRegistry\"]\n end\n \n subgraph \"Data Layer\"\n D --> G[\"LadybugDB (SQLite)\"]\n F --> G\n end\n```\n\n### Request Processing\n\n1. **Connection**: Client establishes stdio connection to `gitnexus mcp`\n2. **Initialization**: Server sends protocol handshake with available capabilities\n3. **Tool Invocation**: Client sends `tools/call` requests\n4. **Query Execution**: Server routes to appropriate handler (graph DB, file system)\n5. **Response**: Structured JSON-RPC response returned via stdio\n\n## Use Cases\n\n### Semantic Code Understanding\n\nWhen asking Claude questions like \"Which files depend on the auth module?\", the MCP server:\n\n1. Receives the `query` tool call\n2. Searches the knowledge graph for import relationships\n3. Returns execution flows and dependency chains\n\n### Impact Analysis\n\nBefore making changes, use the `impact` tool to understand the blast radius:\n\n- **Depth 1**: Direct dependencies\n- **Depth 2**: Transitive dependencies\n- **Depth 3**: Full impact tree with confidence scores\n\n### Change Detection\n\nThe `detect_changes` tool compares current working directory state against the indexed snapshot, returning:\n\n- Modified files\n- Added imports/exports\n- Removed dependencies\n\n## Configuration\n\n### Multi-Repository Support\n\nThe MCP server serves all indexed repositories registered in the global registry. Use `gitnexus list` to see available repos:\n\n```bash\ngitnexus list # List all indexed repositories\ngitnexus status # Show index status for current repo\n```\n\n资料来源：[gitnexus/README.md:20-24](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L20-L24)\n\n### Binaries on Windows\n\nOn Windows, `gitnexus` may have multiple entries from `where`:\n- POSIX shell script (not directly executable)\n- `.cmd`/`.bat` wrapper (preferred for `spawn()`)\n\nThe setup code prefers the wrapper to ensure reliable execution:\n\n```typescript\nconst cmdLine = lines.find((l) => /\\.(cmd|bat)$/i.test(l));\nreturn cmdLine || lines[0] || null;\n```\n\n资料来源：[gitnexus/src/cli/setup.ts:21-24](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts#L21-L24)\n\n## Summary\n\nThe MCP Integration layer transforms GitNexus from a standalone analysis tool into a collaborative AI assistant. By exposing the knowledge graph through the Model Context Protocol, it enables:\n\n- **Deep Context**: AI understands codebase structure, not just file names\n- **Impact Awareness**: Changes can be validated against dependency graphs\n- **Cross-Repo Intelligence**: Multi-repository analysis through unified queries\n- **Workflow Integration**: Seamless incorporation into daily editing tasks\n\nThe architecture prioritizes fast startup (global binary preference) and reliable cross-platform execution, making it practical for CI/CD environments and interactive development alike.\n\n---\n\n\n\n## Multi-Repo Registry Architecture\n\n### 相关页面\n\n相关主题：[MCP Integration](#mcp-integration), [Knowledge Graph](#knowledge-graph)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/repo-manager.ts)\n- [gitnexus/src/cli/list.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/list.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n- [gitnexus/src/cli/analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/analyze.ts)\n- [gitnexus/src/core/run-analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/run-analyze.ts)\n\n\n# Multi-Repo Registry Architecture\n\n## Overview\n\nThe Multi-Repo Registry is GitNexus's core system for managing multiple indexed repositories within a single global registry. It provides the foundation for repository discovery, identity resolution, and multi-repo querying across the CLI, MCP server, and web interface.\n\nThe registry persists as `~/.gitnexus/registry.json`, storing metadata for each indexed repository including its path, name, last indexed commit, and statistics about the generated knowledge graph (nodes, edges, processes).\n\n## Registry Data Model\n\n### RegistryEntry Interface\n\nEach entry in the registry represents a single indexed repository:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | The resolved repository name (see Name Resolution Precedence) |\n| `path` | `string` | Absolute filesystem path to the repository |\n| `indexedAt` | `number` | Unix timestamp when the repo was last indexed |\n| `lastCommit` | `string \\| undefined` | Git commit SHA of the last analyzed state |\n| `stats` | `RegistryStats \\| undefined` | Graph statistics (files, nodes, edges, communities, processes, embeddings) |\n| `remoteUrl` | `string \\| undefined` | The `remote.origin.url` for the repo |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:60-70]()\n\n### CwdMatch Interface\n\nThe registry provides a matching interface to resolve the current working directory against indexed repositories:\n\n```typescript\nexport interface CwdMatch {\n match: 'path' | 'sibling-by-remote' | 'none';\n entry?: RegistryEntry;\n cwdGitRoot?: string;\n cwdHead?: string;\n drift?: number;\n hint?: string;\n}\n```\n\nThe `CwdMatch` interface supports three match scenarios:\n\n| Match Type | Description |\n|------------|-------------|\n| `path` | Exact path match — `cwd` is a subdirectory of a registered repo |\n| `sibling-by-remote` | Same remote URL — `cwd` is a different on-disk clone of a registered repo |\n| `none` | No relationship found |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:200-220]()\n\n## Name Resolution Precedence\n\nGitNexus employs a four-tier name resolution strategy to determine the registry name for an indexed repository:\n\n```mermaid\ngraph TD\n A[Start: Determine registry name] --> B{T Explicit --name provided?}\n B -->|Yes| C[Use explicit name]\n B -->|No| D{Existing entry with preserved alias?}\n D -->|Yes| E[Use preserved alias]\n D -->|No| F{remote.origin.url available?}\n F -->|Yes| G[Derive name from remote URL]\n F -->|No| H[Use path.basename]\n \n C --> I[Store in registry]\n E --> I\n G --> I\n H --> I\n```\n\n### Resolution Tiers\n\n| Priority | Source | Rationale |\n|----------|--------|-----------|\n| 1 | `--name ` CLI flag | Explicit user-provided alias |\n| 2 | Preserved alias on existing entry | Maintains name across re-analyzes |\n| 3 | `git config --get remote.origin.url` | Recovers meaningful names for monorepo subprojects, git worktrees, and Gas-Town-style layouts |\n| 4 | `path.basename(repoPath)` | Original default behavior |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:290-310]()\n\n### Git Worktree Support\n\nA key architectural concern is handling git worktrees correctly. When running `gitnexus analyze` inside a linked worktree, the system uses `git rev-parse --git-common-dir` to derive the **canonical repository root**, preventing worktrees from being registered under their directory slug (e.g., `wt-feature`) instead of the actual repo name (e.g., `repo`).\n\n```typescript\nexport const resolveRepoIdentityRoot = (fromPath: string): string => {\n const resolved = path.resolve(fromPath);\n const canonical = getCanonicalRepoRoot(resolved);\n if (!canonical) return resolved;\n if (canonical === resolved) return canonical;\n if (hasGitDir(resolved)) return canonical; // linked worktree\n return resolved; // arbitrary subdir → preserve as-is\n};\n```\n\nWithout this, each worktree would re-register as a \"different\" project, causing AGENTS.md to be rewritten with the wrong MCP URI and silently accumulating duplicate registry entries.\n\n资料来源：[gitnexus/src/storage/git.ts:90-110]()\n\n## Registry Operations\n\n### Registration Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as gitnexus analyze\n participant RM as repo-manager\n participant FS as filesystem\n participant Git as git utilities\n \n CLI->>RM: registerRepo(repoPath, opts)\n RM->>Git: getRemoteOriginUrl(repoPath)\n RM->>Git: resolveRepoIdentityRoot(repoPath)\n RM->>RM: resolveName(precedence tiers)\n RM->>RM: checkDuplicateName()\n alt duplicate found & !allowDuplicateName\n RM-->>CLI: throw RegistryNameCollisionError\n else allowed or no duplicate\n RM->>FS: persist to registry.json\n RM-->>CLI: return resolved name\n end\n```\n\n#### Registration Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `name` | `string \\| undefined` | Explicit alias for registry name |\n| `allowDuplicateName` | `boolean` | Bypass collision guard, allowing two paths to share the same name |\n\nThe duplicate-name guard only fires when the user explicitly passes a `name`; un-aliased basename collisions continue to register silently so existing users see no behavior change.\n\n资料来源：[gitnexus/src/core/run-analyze.ts:45-60]()\n\n### Listing Repositories\n\nThe `gitnexus list` command displays all indexed repositories with collision-aware formatting:\n\n```typescript\nexport const listCommand = async () => {\n const entries = await listRegisteredRepos({ validate: true });\n const nameCounts = new Map();\n \n for (const entry of entries) {\n const key = entry.name.toLowerCase();\n nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);\n }\n \n for (const entry of entries) {\n const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;\n const header = hasCollision ? `${entry.name} (${entry.path})` : entry.name;\n // display with path disambiguation for collisions\n }\n};\n```\n\nEntries with name collisions display their path to disambiguate:\n\n```\n myapp (/projects/myapp)\n myapp (/worktrees/myapp-feature)\n```\n\n资料来源：[gitnexus/src/cli/list.ts:15-50]()\n\n### Repository Switching (Web Interface)\n\nThe web interface supports switching between indexed repositories via a dropdown menu. The Header component renders available repos with an \"active\" indicator for the current project:\n\n```tsx\n{availableRepos.map((repo) => (\n
\n \n
\n))}\n```\n\n资料来源：[gitnexus-web/src/components/Header.tsx:1-50]()\n\n## Error Handling\n\n### RegistryNameCollisionError\n\nWhen two different repository paths attempt to register under the same name without the `--allow-duplicate-name` flag, the system throws `RegistryNameCollisionError` with actionable guidance:\n\n```\nRegistry name collision:\n \"myapp\" is already used by \"/projects/myapp\".\n\nOptions:\n • Pick a different alias: gitnexus analyze --name \n • Allow the duplicate: gitnexus analyze --allow-duplicate-name\n```\n\n资料来源：[gitnexus/src/cli/analyze.ts:30-45]()\n\n### AnalysisNotFinalizedError\n\nIf the analysis pipeline fails to complete, users receive diagnostic guidance:\n\n1. Re-run `gitnexus analyze` — transient native errors often clear on retry\n2. Inspect the storage path for leftover `lbug.wal` indicating an aborted write\n3. Run with `NODE_OPTIONS=\"--max-old-space-size=8192 --trace-exit\"` for detailed tracing\n\n资料来源：[gitnexus/src/cli/analyze.ts:50-70]()\n\n## MCP Server Integration\n\nThe MCP server exposes registry information through the `gitnexus://repo/{name}/*` URI scheme:\n\n| Resource URI | Content |\n|--------------|---------|\n| `gitnexus://repo/{name}/context` | Stats, staleness check |\n| `gitnexus://repo/{name}/clusters` | All functional areas |\n| `gitnexus://repo/{name}/processes` | All execution flows |\n| `gitnexus://repo/{name}/schema` | Graph schema for Cypher |\n\n资料来源：[gitnexus/src/mcp/resources.ts:40-55]()\n\n## Configuration Storage\n\nRegistry metadata is stored alongside the index in the GitNexus storage directory:\n\n```typescript\nconst { registryPath, indexPath, metaPath } = getStoragePaths(repoName, repoPath);\n```\n\nThe registry file (`registry.json`) maintains the authoritative list of all indexed repositories and is the single source of truth for repository discovery across CLI, MCP, and web components.\n\n## Summary\n\nThe Multi-Repo Registry Architecture provides:\n\n- **Centralized repository tracking** via `~/.gitnexus/registry.json`\n- **Intelligent name resolution** with support for aliases, git remotes, and worktrees\n- **Collision detection** with graceful degradation via `--allow-duplicate-name`\n- **Unified discovery** across CLI (`list`, `query`), MCP (`list_repos`), and web interfaces\n- **Cross-repo intelligence** enabling queries and context to span multiple repositories\n\n---\n\n\n\n## Indexing Pipeline\n\n### 相关页面\n\n相关主题：[Knowledge Graph](#knowledge-graph), [Search System](#search-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/ingestion/pipeline-phases/parse.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/parse.ts)\n- [gitnexus-shared/src/scope-resolution/parsed-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n- [gitnexus/src/core/ingestion/parsing-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/parsing-processor.ts)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n\n# Indexing Pipeline\n\nThe Indexing Pipeline is the core ingestion system that transforms source code repositories into a graph-based representation. It scans, parses, extracts semantic relationships, and builds the knowledge graph that powers GitNexus's dependency visualization and impact analysis capabilities.\n\n## Overview\n\nThe pipeline operates as a multi-phase execution engine where each phase depends on the output of previous phases. It processes source files through sequential stages, extracting code symbols, relationships, and metadata to construct the semantic graph.\n\n```mermaid\ngraph TD\n A[Source Files] --> B[Structure Phase]\n B --> C[Parse Phase]\n C --> D[Scope Extraction]\n D --> E[Finalize Phase]\n E --> F[Call Processing]\n E --> G[Heritage Processing]\n D --> H[Communities Detection]\n F --> I[Graph Completion]\n G --> I\n H --> I\n I --> J[Indexed Graph]\n```\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md]()\n\n## Pipeline Architecture\n\n### Phase Execution Model\n\nThe pipeline is built on a `PipelinePhase` abstraction where each phase declares its dependencies and implements an `execute` function:\n\n```typescript\nconst pipelinePhase: PipelinePhase = {\n name: 'parse',\n deps: ['structure', 'markdown', 'cobol'],\n async execute(\n ctx: PipelineContext,\n deps: ReadonlyMap>,\n ): Promise { /* ... */ }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/parse.ts:1-24]()\n\n### Pipeline Context\n\nThe `PipelineContext` carries shared state across phases:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `graph` | `SemanticGraph` | The graph being built |\n| `repoPath` | `string` | Absolute path to the repository |\n| `pipelineStart` | `number` | Timestamp when pipeline started |\n| `onProgress` | `ProgressCallback` | Progress reporting callback |\n| `options` | `PipelineOptions` | Configuration for the pipeline |\n\n## Phase Breakdown\n\n### Structure Phase\n\nThe entry point that discovers and classifies files in the repository. It builds the initial file inventory with metadata including paths, sizes, and detected languages.\n\n### Parse Phase\n\nThe parse phase transforms source files into structured AST representations using tree-sitter parsers. It processes files in a chunked, parallel manner to handle large repositories efficiently.\n\n```typescript\nconst result = await runChunkedParseAndResolve(\n ctx.graph,\n scannedFiles,\n allPaths,\n totalFiles,\n ctx.repoPath,\n ctx.pipelineStart,\n ctx.onProgress,\n ctx.options,\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/parse.ts:17-24]()\n\n#### Parsing Processor\n\nThe `parsing-processor.ts` handles the actual file parsing and extraction:\n\n```typescript\nconst merged = mergeChunkResults(graph, symbolTable, chunkResults);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n### Scope Extraction Phase\n\nScope extraction produces `ParsedFile` objects that represent the semantic structure of each source file. This is the per-file, parallelizable boundary between extraction and cross-file resolution.\n\n#### ParsedFile Structure\n\n```typescript\ninterface ParsedFile {\n readonly scopes: Scope[]; // All scopes in the file\n readonly parsedImports: ParsedImport[]; // Raw imports before resolution\n readonly localDefs: SymbolDefinition[]; // Structurally declared definitions\n readonly referenceSites: ReferenceSite[]; // Pre-resolution usage facts\n}\n```\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-30]()\n\nThe `ParsedFile` deliberately does NOT carry:\n- Linked `ImportEdge`s (those are finalize output)\n- A `ScopeTree` instance (callers build one from `scopes`)\n\n#### Scope Extraction Hooks\n\nLanguage providers implement these hooks for scope extraction:\n\n```typescript\nexport type ScopeExtractorHooks = Pick<\n LanguageProvider,\n | 'resolveScopeKind'\n | 'bindingScopeFor'\n | 'interpretImport'\n | 'interpretTypeBinding'\n | 'classifyCallForm'\n>;\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-extractor.ts:30-48]()\n\n### Call Processing Phase\n\nCall processing extracts function/method invocations and builds dispatch information. It works with language providers to query ASTs using tree-sitter queries:\n\n```typescript\ninterface PreparedFile {\n language: SupportedLanguages;\n provider: ReturnType;\n tree: ReturnType;\n matches: ReturnType;\n parentMap: ReadonlyMap;\n typeEnv: ReturnType;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-20]()\n\nThe call processor skips registry-primary languages since scope-based phases own CALLS extraction for those languages.\n\n### Heritage Processing Phase\n\nHeritage processing extracts inheritance relationships (extends/implements) and resolves them into graph edges:\n\n```mermaid\ngraph TD\n H[Heritage Record] -->|extends| E{Extends Type Check}\n H -->|implements| I{Is Implements}\n E -->|IMPLEMENTS| I\n E -->|CLASS| C[Add Extends Edge]\n I -->|Yes| Impl[Add Implements Edge]\n```\n\nFor `extends` relationships, the processor determines the relationship type based on the language:\n\n```typescript\nconst { type: relType, idPrefix } = resolveExtendsType(\n h.parentName,\n h.filePath,\n ctx,\n getHeritageStrategyForLanguage(fileLanguage),\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-50]()\n\n### Communities Detection Phase\n\nDetects code communities and modules within the codebase, enabling grouped visualization and analysis.\n\n## Scope Resolution\n\n### Resolution Indexes\n\nAfter the main parsing phases, scope resolution builds cross-file indexes:\n\n```typescript\nexport interface ScopeResolutionIndexes {\n readonly scopeTree: ScopeTree;\n readonly defs: DefIndex;\n readonly qualifiedNames: QualifiedNameIndex;\n readonly moduleScopes: ModuleScopeIndex;\n readonly methodDispatch: MethodDispatchIndex;\n readonly imports: ImportEdge[];\n readonly bindings: BindingIndex;\n readonly referenceSites: ReferenceSite[];\n readonly stats: FinalizeStats;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution-indexes.ts:1-35]()\n\n### Workspace Resolution Index\n\nThe workspace index provides fast lookups for class and module scopes:\n\n```typescript\nexport interface WorkspaceResolutionIndex {\n /** Class def `nodeId` → that class's `Scope`. */\n readonly classScopeByDefId: ReadonlyMap;\n\n /** Class `Scope.id` → class def `nodeId`. */\n readonly classScopeIdToDefId: ReadonlyMap;\n\n /** Module scope by file path. */\n readonly moduleScopeByFile: ReadonlyMap;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-30]()\n\n### Building the Index\n\n```typescript\nexport function buildWorkspaceResolutionIndex(\n parsedFiles: readonly ParsedFile[],\n): WorkspaceResolutionIndex {\n const classScopeByDefId = new Map();\n const classScopeIdToDefId = new Map();\n const moduleScopeByFile = new Map();\n\n for (const parsed of parsedFiles) {\n const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');\n if (moduleScope !== undefined) moduleScopeByFile.set(parsed.filePath, moduleScope);\n\n for (const scope of parsed.scopes) {\n if (scope.kind !== 'Class') continue;\n const cd = scope.ownedDefs.find((d) => isClassLike(d.type));\n if (cd !== undefined) {\n classScopeByDefId.set(cd.nodeId, scope);\n classScopeIdToDefId.set(scope.id, cd.nodeId);\n }\n }\n }\n\n return { classScopeByDefId, classScopeIdToDefId, moduleScopeByFile };\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:30-55]()\n\n## Language Support\n\nThe pipeline supports multiple languages through provider-specific implementations:\n\n### PHP Import Resolution\n\n```typescript\nexport function resolvePhpImportTargetInternal(\n targetRaw: string,\n _fromFile: string,\n allFilePaths: ReadonlySet,\n resolutionConfig?: unknown,\n): string | null\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/php/import-target.ts:1-30]()\n\n### C Header Scanning\n\n```typescript\nexport function scanHeaderFiles(repoPath: string): ReadonlySet {\n const headers = new Set();\n walk(repoPath, repoPath, headers);\n return headers;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/c/header-scan.ts:1-20]()\n\n### C# Import Decomposition\n\n```typescript\ntype ImportKind = 'namespace' | 'alias' | 'static';\n\ninterface ImportSpec {\n readonly kind: ImportKind;\n readonly source: string;\n readonly name: string;\n readonly alias?: string;\n readonly atNode: SyntaxNode;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/csharp/import-decomposer.ts:1-30]()\n\n## Semantic Model Contract\n\nThe `ParsedFile` is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Key invariants:\n\n1. **Scope-resolution passes MUST NOT build a parallel parse representation** — they should reuse the orchestrator's `treeCache`\n2. **Edits from `runScopeResolution` and the legacy DAG are indistinguishable** to downstream consumers\n3. **Node identity uses the same `generateId()` helper** across both paths\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts:1-30]()\n\n## Performance Considerations\n\n### Chunked Processing\n\nFiles are processed in chunks to maintain responsiveness:\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n const file = files[i];\n onProgress?.(i + 1, files.length);\n if (i % 20 === 0) await yieldToEventLoop();\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:10-15]()\n\n### Worker Pool Dispatch\n\nThe parsing processor uses a worker pool for parallel file processing:\n\n```typescript\nconst chunkResults = await workerPool.dispatch(\n parseableFiles,\n (filesProcessed) => {\n onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');\n },\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n### Cache Management\n\nASTs are cached with buffer size optimization for large files:\n\n```typescript\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\ntree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n});\nastCache.set(file.path, tree);\n```\n\n## Configuration\n\n### Language Availability\n\n```typescript\nconst language = getLanguageFromFilename(file.path);\nif (!language) continue;\nif (!isLanguageAvailable(language)) {\n if (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n }\n continue;\n}\n```\n\n### Tree-sitter Queries\n\nEach language provider supplies tree-sitter queries for extraction:\n\n```typescript\nconst provider = getProvider(language);\nconst queryStr = provider.treeSitterQueries;\nif (!queryStr) continue;\n```\n\n## Summary\n\nThe Indexing Pipeline transforms source code into a queryable graph through:\n\n1. **Structure Discovery** — File enumeration and classification\n2. **Parallel Parsing** — Tree-sitter AST generation with caching\n3. **Scope Extraction** — Per-file semantic structure extraction\n4. **Cross-file Resolution** — Import and reference resolution\n5. **Relationship Building** — Heritage, calls, and dependencies\n6. **Index Materialization** — Fast lookup indexes for the graph\n\nThe pipeline is designed for incremental updates and supports both full repository ingestion and targeted re-indexing of changed files.\n\n---\n\n\n\n## Knowledge Graph\n\n### 相关页面\n\n相关主题：[Indexing Pipeline](#indexing-pipeline), [Search System](#search-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/graph/graph.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/graph.ts)\n- [gitnexus/src/core/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/types.ts)\n- [gitnexus-shared/src/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/graph/types.ts)\n- [gitnexus/src/core/ingestion/model/semantic-model.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/semantic-model.ts)\n- [gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/emit-references.ts)\n- [gitnexus/src/core/ingestion/structure-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/structure-processor.ts)\n- [gitnexus/src/core/ingestion/parsing-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/parsing-processor.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts)\n\n\n# Knowledge Graph\n\nThe Knowledge Graph is the core data structure in GitNexus that represents a codebase as an interconnected network of nodes and relationships. It serves as the semantic backbone for code exploration, dependency analysis, and AI-powered queries.\n\n## Overview\n\nThe Knowledge Graph transforms source code into a queryable graph where:\n\n- **Nodes** represent code entities (files, functions, classes, interfaces, modules)\n- **Edges** represent relationships (imports, calls, containment, inheritance)\n\nThis abstraction enables powerful navigation patterns like tracing execution flows, finding circular dependencies, and identifying highly-connected components.\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n## Core Architecture\n\n### Graph Interface\n\nThe `KnowledgeGraph` interface provides the fundamental operations for building and querying the graph:\n\n```typescript\ninterface KnowledgeGraph {\n addNode(node: GraphNode): void;\n addRelationship(relationship: GraphRelationship): void;\n removeNode(nodeId: string): boolean;\n removeNodesByFile(filePath: string): number;\n removeRelationship(relationshipId: string): boolean;\n getNode(id: string): GraphNode | undefined;\n forEachNode(fn: (node: GraphNode) => void): void;\n forEachRelationship(fn: (rel: GraphRelationship) => void): void;\n nodeCount: number;\n relationshipCount: number;\n}\n```\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n### Node Structure\n\nGraph nodes contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Unique identifier (e.g., `File:src/index.ts`) |\n| `label` | `NodeLabel` | Entity type (File, Function, Class, etc.) |\n| `properties` | `Record` | Metadata (name, filePath, line numbers, language) |\n\n资料来源：[gitnexus-shared/src/graph/types.ts]()\n\n### Relationship Structure\n\nRelationships connect nodes with semantic meaning:\n\n```typescript\ninterface GraphRelationship {\n id: string;\n type: RelationshipType;\n sourceId: string;\n targetId: string;\n confidence: number; // 0.0 - 1.0\n reason: string; // Human-readable explanation\n}\n```\n\n资料来源：[gitnexus-shared/src/graph/types.ts]()\n\n## Node Types\n\nThe system recognizes multiple node labels representing different code entities:\n\n| Node Label | Description |\n|------------|-------------|\n| `File` | Source file node |\n| `Folder` | Directory node |\n| `Function` | Function or method |\n| `Class` | Class definition |\n| `Interface` | Interface definition |\n| `Struct` | Struct definition (Go, Rust, C) |\n| `Enum` | Enumeration |\n| `Trait` | Trait definition |\n| `Module` | Module (COBOL programs, packages) |\n| `Property` | Data item or property |\n| `TypeAlias` | Type alias definition |\n| `Const` | Constant declaration |\n| `Static` | Static member |\n| `Record` | Record type |\n| `Union` | Union type |\n| `Typedef` | Type definition |\n| `Macro` | Preprocessor macro |\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts]()\n\n## Relationship Types\n\n### Core Relationships\n\n| Type | Description | Direction |\n|------|-------------|-----------|\n| `CONTAINS` | Parent-child hierarchy | Parent → Child |\n| `IMPORTS` | Import/require statements | Importer → Imported |\n| `CALLS` | Function invocations | Caller → Callee |\n| `DECLARES` | Symbol definitions | Scope → Symbol |\n| `EXTENDS` | Inheritance (parent class) | Child → Parent |\n| `IMPLEMENTS` | Interface implementation | Class → Interface |\n| `USES` | Variable/type usage | User → Used |\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n### Confidence Scoring\n\nRelationships include a `confidence` score:\n\n- `1.0` - Resolved reference (fully verified)\n- `0.5` - Unresolved reference (symbol not found in index)\n\n```typescript\ngraph.addRelationship({\n id: `rel:imports:${scopeId}->${targetModule}:${localName}`,\n sourceId: scopeId,\n targetId: targetModule,\n type: 'IMPORTS',\n confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,\n reason: `import ${edge.kind} ${edge.localName}`,\n});\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n \n## Build Pipeline\n\nThe Knowledge Graph is constructed through a multi-phase pipeline:\n\n```mermaid\ngraph TD\n A[Source Files] --> B[Structure Processor]\n B --> C[File/Folder Nodes]\n C --> D[Parsing Processor]\n D --> E[Symbol Nodes]\n E --> F[Emit References]\n F --> G[Import Edges]\n G --> H[Wildcard Synthesis]\n H --> I[Final Graph]\n```\n\n### Phase 1: Structure Processing\n\nThe structure processor creates nodes for the file system hierarchy:\n\n```typescript\nconst processStructure = (graph: KnowledgeGraph, paths: string[]) => {\n paths.forEach((path) => {\n const parts = path.split('/');\n let currentPath = '';\n let parentId = '';\n\n parts.forEach((part, index) => {\n const isFile = index === parts.length - 1;\n const label = isFile ? 'File' : 'Folder';\n currentPath = currentPath ? `${currentPath}/${part}` : part;\n const nodeId = generateId(label, currentPath);\n \n graph.addNode({\n id: nodeId,\n label: label,\n properties: { name: part, filePath: currentPath },\n });\n\n if (parentId) {\n graph.addRelationship({\n id: generateId('CONTAINS', `${parentId}->${nodeId}`),\n type: 'CONTAINS',\n sourceId: parentId,\n targetId: nodeId,\n confidence: 1.0,\n reason: '',\n });\n }\n parentId = nodeId;\n });\n });\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/structure-processor.ts]()\n\n### Phase 2: Parsing and Symbol Extraction\n\nThe parsing processor extracts code symbols and relationships from source files:\n\n```typescript\nexport const mergeChunkResults = (\n graph: KnowledgeGraph,\n symbolTable: SymbolTableWriter,\n chunkResults: readonly ParseWorkerResult[],\n): WorkerExtractedData => {\n for (const result of chunkResults) {\n for (const node of result.nodes) {\n graph.addNode({\n id: node.id,\n label: node.label as NodeLabel,\n properties: node.properties,\n });\n }\n for (const rel of result.relationships) {\n graph.addRelationship(rel);\n }\n for (const sym of result.symbols) {\n symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type, {\n parameterCount: sym.parameterCount,\n requiredParameterCount: sym.requiredParameterCount,\n parameterTypes: sym.parameterTypes,\n returnType: sym.returnType,\n declaredType: sym.declaredType,\n });\n }\n }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts]()\n\n### Phase 3: Reference Emission\n\nReferences connect code entities across scopes and files:\n\n```typescript\nexport interface EmitStats {\n readonly edgesEmitted: number;\n readonly skippedNoCaller: number; // No caller def resolved\n readonly skippedMissingTarget: number; // Target not in DefIndex\n readonly scopeNodesEmitted: number; // Only if INGESTION_EMIT_SCOPES=1\n readonly scopeEdgesEmitted: number;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n### Phase 4: Wildcard Import Synthesis\n\nFor languages with whole-module import semantics (Go, Ruby, C/C++, Swift), wildcard imports are expanded into per-symbol bindings:\n\n```typescript\nconst IMPORTABLE_SYMBOL_LABELS = new Set([\n 'Function', 'Class', 'Interface', 'Struct', 'Enum',\n 'Trait', 'TypeAlias', 'Const', 'Static', 'Record',\n 'Union', 'Typedef', 'Macro',\n]);\n\n/** Max synthetic bindings per importing file — prevents memory bloat */\nconst MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts]()\n\nThe synthesis process:\n\n1. Collects IMPORTS edges for wildcard languages\n2. Retrieves exported symbols per file\n3. Creates named import bindings up to the limit\n\n## Language-Specific Processors\n\n### COBOL Processor\n\nCOBOL files undergo specialized processing with unique node types:\n\n```typescript\n// PROGRAM-ID -> Module node\nconst moduleId = generateId('Module', `${filePath}:${extracted.programName}`);\n\n// SECTIONs -> Namespace nodes\n// Paragraphs -> Property nodes\n// Data items -> Property nodes\ngraph.addNode({\n id: moduleId,\n label: 'Module',\n properties: {\n name: extracted.programName,\n filePath,\n language: SupportedLanguages.Cobol,\n isExported: true,\n },\n});\n```\n\nNested programs are linked to their enclosing programs:\n\n```typescript\nconst enclosing = extracted.programs.find(\n (p) => p.startLine < prog.startLine &&\n p.endLine > prog.endLine &&\n p.nestingDepth < prog.nestingDepth,\n);\nconst nestedParent = enclosing\n ? programModuleIds.get(enclosing.name.toUpperCase()) ?? moduleId\n : moduleId;\n```\n\n资料来源：[gitnexus/src/core/ingestion/cobol-processor.ts]()\n\n## Symbol Table Integration\n\nThe Knowledge Graph integrates with a symbol table for cross-reference resolution:\n\n```typescript\nsymbolTable.add(\n filePath,\n symbolName,\n nodeId,\n symbolType,\n {\n parameterCount: number,\n requiredParameterCount: number,\n parameterTypes: string[],\n returnType: string,\n declaredType: string,\n }\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts]()\n\n## Query Patterns\n\nThe graph supports various query patterns for code exploration:\n\n| Pattern | Description |\n|---------|-------------|\n| File dependencies | Traverse IMPORTS edges from a File node |\n| Call graph | Follow CALLS edges from a Function node |\n| Impact analysis | Reverse-traverse USES edges |\n| Circular dependencies | Detect cycles in IMPORTS graph |\n| Component boundaries | Find connected components |\n\n## Web Interface Visualization\n\nThe GitNexus web UI visualizes the Knowledge Graph with:\n\n- **Node size** reflects connection count — larger nodes are depended on by more files\n- **Edges** point from importer to imported\n- **Click interactions** open detail panels showing imports, exports, and reverse dependencies\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `INGESTION_EMIT_SCOPES` | `false` | Enable scope tree nodes in graph |\n\n```typescript\nfunction isScopeEmissionEnabled(): boolean {\n const TRUTHY = new Set(['true', '1', 'yes']);\n const raw = process.env['INGESTION_EMIT_SCOPES'];\n return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n## Summary\n\nThe Knowledge Graph is a fundamental abstraction in GitNexus that transforms codebase structure into a queryable graph. By modeling files, symbols, and their relationships with confidence scores, it enables:\n\n- Semantic code navigation\n- Dependency analysis\n- AI-powered queries over code structure\n- Documentation generation\n\nThe multi-phase build pipeline progressively enriches the graph from raw file structure through parsing, reference resolution, and language-specific processing to produce a comprehensive semantic model of the codebase.\n\n---\n\n\n\n## Search System\n\n### 相关页面\n\n相关主题：[Indexing Pipeline](#indexing-pipeline), [Knowledge Graph](#knowledge-graph)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/search/hybrid-search.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/hybrid-search.ts)\n- [gitnexus/src/core/search/bm25-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/bm25-index.ts)\n- [gitnexus/src/core/search/fts-indexes.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/fts-indexes.ts)\n- [gitnexus/src/core/embeddings/embedding-pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n- [gitnexus-web/src/components/QueryFAB.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/QueryFAB.tsx)\n- [gitnexus-web/src/components/WebGPUFallbackDialog.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/WebGPUFallbackDialog.tsx)\n- [gitnexus-web/src/components/FileTreePanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/FileTreePanel.tsx)\n\n\n# Search System\n\nGitNexus provides a multi-layered search system that enables users to explore code repositories through various search modalities. The system combines traditional keyword-based search with semantic understanding powered by embeddings, supporting navigation by filename, function name, import path, and natural language queries.\n\n## Architecture Overview\n\nThe search system in GitNexus follows a hybrid architecture that leverages both classical information retrieval techniques and modern neural embedding approaches. This dual-strategy design allows users to perform fast exact-match searches while also enabling semantic understanding of code relationships.\n\n```mermaid\ngraph TD\n subgraph \"Search Entry Points\"\n CMD[⌘K / Ctrl K - Global Search]\n FAB[QueryFAB - Natural Language]\n FILE[FileTreePanel Search]\n end\n \n subgraph \"Search Pipeline\"\n HY[Hybrid Search Engine]\n BM[BM25 Index]\n FTS[Full-Text Search Index]\n EMB[Embedding Pipeline]\n end\n \n subgraph \"Result Handling\"\n RES[Results Aggregation]\n HL[Highlight Matching Nodes]\n NAV[Navigate to Graph]\n end\n \n CMD --> HY\n FAB --> HY\n FILE --> BM\n HY --> BM\n HY --> EMB\n HY --> FTS\n BM --> RES\n FTS --> RES\n EMB --> RES\n RES --> HL\n HL --> NAV\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Hybrid Search Engine | `hybrid-search.ts` | Orchestrates search across multiple backends |\n| BM25 Index | `bm25-index.ts` | Classical keyword-based ranking |\n| FTS Indexes | `fts-indexes.ts` | Full-text search infrastructure |\n| Embedding Pipeline | `embedding-pipeline.ts` | Neural embedding generation and similarity |\n\n资料来源：[gitnexus/src/core/search/hybrid-search.ts]() [gitnexus/src/core/search/bm25-index.ts]()\n\n## Search Modalities\n\nGitNexus supports three distinct search modalities that address different user needs:\n\n### 1. Global Quick Search (⌘K / Ctrl+K)\n\nThe primary search interface is accessible via keyboard shortcut `⌘K` on macOS or `Ctrl+K` on Windows/Linux. This modal provides instant access to search nodes across the entire repository.\n\n**Features:**\n\n- Search by filename\n- Search by function name\n- Search by import path\n- Live highlighting of matching nodes in the graph\n- Fuzzy matching support for typo tolerance\n\n**UI Behavior:**\nWhen activated, the search modal overlays the main interface with a centered input field. Results appear in real-time as the user types, with matches highlighted across the knowledge graph visualization. 资料来源：[gitnexus-web/src/components/HelpPanel.tsx]() [gitnexus-web/src/components/FileTreePanel.tsx]()\n\n### 2. Natural Language Query (Nexus AI)\n\nGitNexus integrates an AI-powered search capability that allows users to ask questions in natural language about the codebase. This feature relies on the semantic embedding pipeline.\n\n**Example Queries:**\n\n- \"Which files depend on the auth module?\"\n- \"Find circular dependencies in this repo\"\n- \"What are the most connected components?\"\n- \"Show me all files that import useEffect\"\n\n**Prerequisites:**\nThe repository must be indexed and ready for semantic queries. The system checks for \"Semantic Ready\" status before allowing natural language queries. 资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n### 3. File Tree Search\n\nA dedicated search interface within the file tree panel allows users to filter and locate specific files in the repository structure. This is particularly useful for large codebases with deep directory hierarchies.\n\n**Implementation Details:**\n\n```tsx\n setSearchQuery(e.target.value)}\n className=\"w-full rounded border border-border-subtle bg-elevated py-1.5 pr-3 pl-8 text-xs text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none\"\n/>\n```\n\n资料来源：[gitnexus-web/src/components/FileTreePanel.tsx]()\n\n## Hybrid Search Engine\n\nThe `HybridSearchEngine` class serves as the central orchestrator for search operations, combining multiple ranking strategies to produce relevant results.\n\n### Search Strategy\n\nThe hybrid approach combines:\n\n1. **BM25 Ranking**: Classical TF-IDF variant optimized for keyword matching\n2. **Full-Text Search (FTS)**: Structured index for structured queries\n3. **Embedding Similarity**: Vector-based semantic matching\n\n### Result Aggregation\n\nResults from multiple search backends are aggregated using a weighted scoring system. The final ranking considers:\n\n- Keyword match score (BM25)\n- Semantic similarity score (embeddings)\n- Graph position relevance\n- Connection count to other nodes\n\n```mermaid\ngraph LR\n A[User Query] --> B[Query Parser]\n B --> C[BM25 Search]\n B --> D[Embedding Query]\n B --> E[FTS Query]\n C --> F[Score Normalization]\n D --> F\n E --> F\n F --> G[Weighted Aggregation]\n G --> H[Result Ranking]\n H --> I[Graph Highlighting]\n```\n\n资料来源：[gitnexus/src/core/search/hybrid-search.ts]()\n\n## BM25 Index\n\nThe BM25 (Best Matching 25) algorithm provides the foundation for keyword-based search ranking in GitNexus. This classical information retrieval technique offers predictable, fast matching for exact and partial term queries.\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| Term Frequency Normalization | Prevents bias toward longer documents |\n| Document Length Scaling | Adaptive ranking based on field length |\n| Saturation Function | Diminishing returns for repeated terms |\n| IDF Weighting | Downweights common terms |\n\n### Index Structure\n\nThe BM25 index maintains:\n\n- **Inverted index**: Maps terms to document positions\n- **Document statistics**: Length, term counts, field weights\n- **IDF table**: Global term importance values\n\n资料来源：[gitnexus/src/core/search/bm25-index.ts]()\n\n## Full-Text Search Indexes\n\nThe FTS (Full-Text Search) subsystem provides structured indexing capabilities for code-specific queries. Unlike BM25 which focuses on term matching, FTS supports phrase queries, proximity searches, and structured field filtering.\n\n### Index Types\n\n1. **Token Index**: Standard word tokenization\n2. **Code Token Index**: Language-aware tokenization preserving syntax\n3. **Symbol Index**: Function/class/variable name index\n\n### Query Capabilities\n\n| Query Type | Syntax | Example |\n|------------|--------|---------|\n| Exact phrase | `\"term1 term2\"` | `\"useState hook\"` |\n| Prefix match | `term*` | `use*` |\n| Field filter | `field:value` | `type:function` |\n| Boolean | `AND / OR / NOT` | `useState AND hook` |\n\n资料来源：[gitnexus/src/core/search/fts-indexes.ts]()\n\n## Embedding Pipeline\n\nThe embedding pipeline transforms code entities into dense vector representations that capture semantic meaning. This enables similarity-based search and natural language understanding.\n\n```mermaid\ngraph TD\n subgraph \"Embedding Pipeline\"\n SRC[Source Code] --> PRE[Preprocessor]\n PRE --> TOK[Tokenization]\n TOK --> ENC[Encoder Model]\n ENC --> VEC[Vector Output]\n end\n \n subgraph \"Storage\"\n VEC --> ANN[Approximate NN Index]\n VEC --> DIM[Dimension Reduction]\n end\n \n subgraph \"Query Flow\"\n Q[Query Text] --> QENC[Query Encoder]\n QENC --> DIST[Distance Calculation]\n ANN --> DIST\n DIST --> TOP[Top-K Results]\n end\n```\n\n### WebGPU Acceleration\n\nEmbedding generation is computationally intensive. GitNexus leverages WebGPU for GPU-accelerated embedding computation when available. If WebGPU is not supported, the system falls back to CPU-based computation with a warning about reduced performance.\n\n**Performance Characteristics:**\n\n- WebGPU: Real-time embedding generation\n- CPU: Batch processing with estimated completion time\n- Memory: Handles large codebases with streaming processing\n\n资料来源：[gitnexus/src/core/embeddings/embedding-pipeline.ts]() [gitnexus-web/src/components/WebGPUFallbackDialog.tsx]()\n\n### Model Configuration\n\nThe embedding pipeline supports configurable embedding models. Users can select from available models in the settings panel or specify custom model identifiers.\n\n**Configuration Options:**\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| Model ID | Embedding model identifier |varies |\n| Dimension | Vector dimensionality | 768 |\n| Batch Size | Documents per batch | 32 |\n| Max Sequence | Maximum input length | 512 |\n\n资料来源：[gitnexus-web/src/components/SettingsPanel.tsx]()\n\n## Query Interface (QueryFAB)\n\nThe QueryFAB (Floating Action Button) component provides persistent access to the natural language query interface. It appears as a floating button in the UI and expands to reveal the query input.\n\n### Features\n\n- Natural language query input\n- Real-time result preview\n- Execution time display\n- Result count indicators\n- Query result highlighting on graph\n- Clear highlight functionality\n\n### Result Display\n\n```tsx\n
\n```\n\n**Result Metrics:**\n\n| Metric | Display | Color |\n|--------|---------|-------|\n| Row count | `{count} rows` | cyan-400 |\n| Highlighted nodes | `{count} highlighted` | cyan-400 |\n| Execution time | `{time}ms` | text-muted |\n\n资料来源：[gitnexus-web/src/components/QueryFAB.tsx]()\n\n## Graph Integration\n\nThe search system is tightly integrated with the knowledge graph visualization. Search results directly influence the graph display:\n\n### Highlighting\n\nMatching nodes are highlighted in the graph with visual indicators:\n\n- **Primary matches**: Full opacity, accent color border\n- **Secondary matches**: Reduced opacity, subtle highlight\n- **Related nodes**: Connected nodes shown with edge highlighting\n\n### Navigation\n\nClicking a search result navigates the graph to focus on the corresponding node, opening the detail panel with:\n\n- Imports and exports\n- Reverse dependencies\n- Node metadata\n- Code preview (where applicable)\n\n### Keyboard Navigation\n\n| Shortcut | Action |\n|----------|--------|\n| `⌘K` / `Ctrl+K` | Open global search |\n| `⌘↵` / `Ctrl+↵` | Execute query |\n| `Escape` | Close search modal |\n| `↑` / `↓` | Navigate results |\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n## Performance Considerations\n\n### Index Build Time\n\nInitial index construction scales with repository size:\n\n| Repository Size | BM25 Index | FTS Index | Embedding Index |\n|-----------------|------------|-----------|-----------------|\n| Small (<100 files) | < 1s | < 2s | ~30s |\n| Medium (100-1000 files) | 2-10s | 5-30s | 2-10 min |\n| Large (>1000 files) | 10-60s | 30-120s | 10+ min |\n\n### Query Latency\n\n| Search Type | Typical Latency |\n|-------------|-----------------|\n| BM25 exact | < 10ms |\n| FTS structured | < 20ms |\n| Semantic (cached) | < 50ms |\n| Semantic (uncached) | 100-500ms |\n\n### Optimization Strategies\n\n1. **Incremental indexing**: Only re-index changed files\n2. **Query caching**: Cache recent semantic query results\n3. **Approximate nearest neighbor**: Trade accuracy for speed in embedding search\n4. **Streaming processing**: Handle large files without memory overflow\n\n## Configuration\n\n### Server Settings\n\nThe search system can be configured through the settings panel:\n\n```typescript\ninterface SearchConfig {\n // BM25 parameters\n k1: number; // Term frequency saturation\n b: number; // Document length normalization\n \n // Embedding settings\n modelId: string; // Embedding model\n device: 'webgpu' | 'cpu';\n \n // FTS settings\n analyzer: 'standard' | 'code';\n minTokenLength: number;\n}\n```\n\n### Ollama Integration\n\nFor self-hosted embedding models, GitNexus supports integration with Ollama:\n\n```typescript\nconst checkOllamaStatus = async (baseUrl: string): Promise<{\n ok: boolean;\n error: string | null;\n}> => {\n const response = await fetch(`${baseUrl}/api/tags`, {\n method: 'GET',\n headers: { 'Content-Type': 'application/json' }\n });\n // ...\n};\n```\n\n资料来源：[gitnexus-web/src/components/SettingsPanel.tsx]()\n\n## Summary\n\nThe GitNexus Search System provides a comprehensive, multi-layered approach to code exploration:\n\n1. **Fast keyword search** via BM25 and FTS indexes for exact matching\n2. **Semantic understanding** through embedding-based similarity\n3. **Natural language queries** powered by AI integration\n4. **Deep graph integration** for visual exploration of search results\n\nThe hybrid architecture ensures that users can find exactly what they're looking for through traditional search while also discovering unexpected relationships through semantic queries.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：abhigyanpatwari/GitNexus\n\n摘要：发现 38 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error。\n\n## 1. 安装坑 · 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f5cfc2c1ce264d6ab4928a417c66e389 | https://github.com/abhigyanpatwari/GitNexus/issues/1518 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9b5bf45777e4195a5b65bec8eb05125 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36bbed40ba504142b4564a0335aa0b91 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Unable to install GitNexus in Mac\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to install GitNexus in Mac\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbf96b8de8644eb9b2c948cdc732d96c | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f7ed64eb318442009c0c45bd394f15e7 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8498a2d89f154c749aac4e7486f4d1f6 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4b1ddd7fb9104e66b60f9d726b19d298 | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2a4f1ac62124129844a1b1664fecdff | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aff7caa0db4beda6fe67cb86b7ccdd | https://github.com/abhigyanpatwari/GitNexus/issues/1542 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安全/权限坑 · 来源证据：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7e053347355476db324ef874ef9991c | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 失败模式：installation: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：Developers may fail before the first successful local run: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing. Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_1438bc0fa83941fc6074de2c5412cd25 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n## 12. 安装坑 · 失败模式：installation: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：Developers may fail before the first successful local run: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ebb5d6efaf48e8d879678b8a170aacf8 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000, failure_mode_cluster:github_issue | fmev_de5b96783d1677ac281ee6c73055380b | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n## 13. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.12. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ad68a701c98e79e3531d2d8292fd6acb | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.12 | Release Candidate v1.6.6-rc.12\n\n## 14. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.13\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.13\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.13. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_691d71a9a9f7c1da63532e7f4913d598 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.13 | Release Candidate v1.6.6-rc.13\n\n## 15. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.14\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.14\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.14. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_fe26658ac0f7dbfc1389758a44d9f3ac | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.14 | Release Candidate v1.6.6-rc.14\n\n## 16. 安装坑 · 失败模式：installation: Unable to install GitNexus in Mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Unable to install GitNexus in Mac\n- 对用户的影响：Developers may fail before the first successful local run: Unable to install GitNexus in Mac\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Unable to install GitNexus in Mac. Context: Observed when using node, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e8a618cc1ed2879b84e81b16d9f8d995 | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | Unable to install GitNexus in Mac\n\n## 17. 安装坑 · 失败模式：installation: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：Developers may fail before the first successful local run: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427. Context: Observed when using node, python, windows, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9ec12d39ffa06f5c08b0ad85182bddd7 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n\n## 18. 安装坑 · 失败模式：installation: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：Developers may fail before the first successful local run: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%). Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_122d12d9d7145c261627cb5c59179ac1 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%), failure_mode_cluster:github_issue | fmev_6c9acc8d3c792d067bb848a0833634a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n## 19. 安装坑 · 失败模式：installation: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 re...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：Developers may fail before the first successful local run: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_623b7791e3c0dc9791ade56a9bde72a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n\n## 20. 安装坑 · 失败模式：installation: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist acro...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_006addf62ce5971f44bd372e453a3fe2 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d73fddaa3691a761b14cb569d5acbb58 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d4e580f0f3653876a2e755ee3ca34259 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n## 21. 安装坑 · 失败模式：installation: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：Developers may fail before the first successful local run: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression). Context: Observed when using node, python, docker, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_78c629867f92802da91b458f6e7bc14f | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n\n## 22. 安装坑 · 来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26a9d2c26b004c6ba8a99533ff1d6ac5 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 安装坑 · 来源证据：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash)…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec175ee0cb4d4d31bae2f29144c7d619 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 24. 安装坑 · 来源证据：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c4087a57d5e4c949662a9721355ac8f | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. 配置坑 · 失败模式：configuration: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?. Context: Observed when using node, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_53da1aec043bc339e2d1e3db40239192 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n\n## 26. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | README/documentation is current enough for a first validation pass.\n\n## 27. 运行坑 · 失败模式：runtime: GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: GitNexus Enterprise for open source\n- 对用户的影响：Developers may hit a documented source-backed failure mode: GitNexus Enterprise for open source\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Enterprise for open source. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f47b7a16378d6157c47cb32462d648cd | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source, failure_mode_cluster:github_issue | fmev_b0d64cb50e22bb1f6f82577f2f9468ed | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source\n\n## 28. 运行坑 · 失败模式：runtime: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record t...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.. Context: Observed when using macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_83c386b31413aad9103fe675ded0d557 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type., failure_mode_cluster:github_issue | fmev_ef20949c8067cc8c69adefcfe3cac1b3 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n## 29. 运行坑 · 失败模式：runtime: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d05c00b4ab6372cd518729b619d7a572 | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n## 30. 运行坑 · 失败模式：runtime: cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: cpp SFINAE: expand type_traits predicate registry (Tier A). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_356daa9356830c10f89e67ea3f087c37 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n## 31. 运行坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_761efc4dc902430dbff83585f209b270 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. 运行坑 · 来源证据：cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0576badcd5a477bb2b988a8a0afa3d6 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. 维护坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dd127cfb66644c49407761777f40c18 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | last_activity_observed missing\n\n## 35. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 36. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 37. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | issue_or_pr_quality=unknown\n\n## 38. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | release_recency=unknown\n\n\n",
"markdown_key": "gitnexus",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1031059905",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/abhigyanpatwari/GitNexus"
},
{
"evidence_id": "art_49e97a18b5a047ed92f0af7dd10b8914",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/abhigyanpatwari/GitNexus#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "GitNexus 说明书",
"toc": [
"https://github.com/abhigyanpatwari/GitNexus 项目说明书",
"目录",
"Introduction to GitNexus",
"What is GitNexus?",
"Installation and Setup",
"Architecture Overview",
"Core Pipeline Phases",
"MCP Tools (Model Context Protocol)",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "dad1ca7ab55ee3dae13729e4cbbce54b8c070f15",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/guides/microservices-thrift.md",
"docs/guides/microservices-grpc.md",
"docs/plans/2026-03-26-feat-cobol-full-language-coverage-plan.md",
"docs/code-indexing/cobol/graph-model.md",
"docs/code-indexing/cobol/copy-expansion.md",
"docs/code-indexing/cobol/deep-indexing.md",
"docs/code-indexing/cobol/file-detection.md",
"docs/code-indexing/cobol/regex-extraction.md",
"docs/code-indexing/cobol/performance.md",
"docs/code-indexing/cobol/README.md",
"docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md",
"docs/superpowers/plans/2026-04-02-pr626-high-fixes.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# gitnexus-monorepo - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 gitnexus-monorepo 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`AGENTS.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `npx gitnexus analyze` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86, `clm_0013` supported 0.86 等\n- `claude mcp add gitnexus -- npx -y gitnexus@latest mcp` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `claude mcp add gitnexus -- cmd /c npx -y gitnexus@latest mcp` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `git clone https://github.com/abhigyanpatwari/gitnexus.git` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx gitnexus@latest serve` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx gitnexus analyze # incremental by default; preserves embeddings` 证据：`AGENTS.md` Claim：`clm_0011` supported 0.86\n- `npx gitnexus analyze --force # full rebuild from scratch (opt out of incremental)` 证据：`AGENTS.md` Claim：`clm_0012` supported 0.86\n- `npx gitnexus analyze --embeddings # also generate embeddings for new/changed nodes` 证据：`AGENTS.md` Claim：`clm_0013` supported 0.86\n- `npx gitnexus analyze --drop-embeddings # explicit opt-in to wipe existing embeddings` 证据：`AGENTS.md` Claim：`clm_0014` supported 0.86\n- `npx gitnexus serve # HTTP API on port 4747 (from any indexed repo)` 证据：`AGENTS.md` Claim：`clm_0015` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86, `clm_0013` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `gitnexus-claude-plugin/.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `AGENTS.md`, `README.md`, `gitnexus-claude-plugin/.claude-plugin/plugin.json`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0017` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md` Claim：`clm_0018` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`, `gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `gitnexus-claude-plugin/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：3014\n- 重要文件覆盖：40/3014\n- 证据索引条目：80\n- 角色 / Skill 条目：12\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 gitnexus-monorepo 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 gitnexus-monorepo 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 gitnexus-monorepo 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 12 个角色 / Skill / 项目文档条目。\n\n- **gitnexus-cli**（skill）：Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \\\"Index this repo\\\", \\\"Reanalyze the codebase\\\", \\\"Generate a wiki\\ 激活提示：当用户任务与“gitnexus-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`\n- **gitnexus-debugging**（skill）：Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \\\"Why is X failing?\\\", \\\"Where does this error come from?\\\", \\\"Trace this bug\\ 激活提示：当用户任务与“gitnexus-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`\n- **gitnexus-exploring**（skill）：Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \\\"How does X work?\\\", \\\"What calls this function?\\\", \\\"Show me the auth flow\\ 激活提示：当用户任务与“gitnexus-exploring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`\n- **gitnexus-guide**（skill）：Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \\\"What GitNexus tools are available?\\\", \\\"How do I use GitNexus?\\ 激活提示：当用户任务与“gitnexus-guide”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md`\n- **gitnexus-impact-analysis**（skill）：Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \\\"Is it safe to change X?\\\", \\\"What depends on this?\\\", \\\"What will break?\\ 激活提示：当用户任务与“gitnexus-impact-analysis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-impact-analysis/SKILL.md`\n- **gitnexus-pr-review**（skill）：Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \\\"Review this PR\\\", \\\"What does PR 42 change?\\\", \\\"Is this PR safe to merge?\\ 激活提示：当用户任务与“gitnexus-pr-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-pr-review/SKILL.md`\n- **gitnexus-refactoring**（skill）：Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \\\"Rename this function\\\", \\\"Extract this into a module\\\", \\\"Refactor this class\\\", \\\"Move this to a separate file\\ 激活提示：当用户任务与“gitnexus-refactoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md`\n- **gitnexus-debugging**（skill）：Trace bugs through call chains using knowledge graph 激活提示：当用户任务与“gitnexus-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-cursor-integration/skills/gitnexus-debugging/SKILL.md`\n- **gitnexus-exploring**（skill）：Navigate unfamiliar code using GitNexus knowledge graph 激活提示：当用户任务与“gitnexus-exploring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-cursor-integration/skills/gitnexus-exploring/SKILL.md`\n- **gitnexus-impact-analysis**（skill）：Analyze blast radius before making code changes 激活提示：当用户任务与“gitnexus-impact-analysis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-cursor-integration/skills/gitnexus-impact-analysis/SKILL.md`\n- **gitnexus-pr-review**（skill）：Use when the user wants to review a pull request, understand what a PR changes, assess risk of merging, or check for missing test coverage. Examples: \\\"Review this PR\\\", \\\"What does PR 42 change?\\\", \\\"Is this PR safe to merge?\\ 激活提示：当用户任务与“gitnexus-pr-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-cursor-integration/skills/gitnexus-pr-review/SKILL.md`\n- **gitnexus-refactoring**（skill）：Plan safe refactors using blast radius and dependency mapping 激活提示：当用户任务与“gitnexus-refactoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`gitnexus-cursor-integration/skills/gitnexus-refactoring/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **COBOL Code Indexing**（documentation）：GitNexus indexes COBOL codebases using a regex-only extraction strategy, bypassing tree-sitter entirely. This document explains why, how the pipeline works, and links to detailed sub-documents. 证据：`docs/code-indexing/cobol/README.md`\n- **Scope**（documentation）：Project: GitNexus · Environment: dev · Maintainer: repository maintainers see GitHub 证据：`AGENTS.md`\n- **Scope**（documentation）：Project: GitNexus · Environment: dev · Maintainer: repository maintainers see GitHub 证据：`CLAUDE.md`\n- **GitNexus**（documentation）：GitNexus ⚠️ Important Notice: GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is not affiliated with, endorsed by, or created by this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus. 证据：`README.md`\n- **GitNexus SWE-bench Evaluation Harness**（documentation）：GitNexus SWE-bench Evaluation Harness 证据：`eval/README.md`\n- **GitNexus — Cursor integration**（documentation）：Static config that adds GitNexus knowledge-graph augmentation and skill files to Cursor. 证据：`gitnexus-cursor-integration/README.md`\n- **GitNexus**（documentation）：Graph-powered code intelligence for AI agents. Index any codebase into a knowledge graph, then query it via MCP or CLI. 证据：`gitnexus/README.md`\n- **tree-sitter-dart**（documentation）：tree-sitter-dart This is a tree-sitter grammar written for the dart programming language. We attempt to adhere as closely as possible to the dart language spec. Initially it was started with a copy of the tree-sitter Java grammar which is why there may be a few relics included in here. For the sake of simplifying the syntax tree, many items were made inlined with tree-sitter's \"underscore\" method of writing rules. 证据：`gitnexus/vendor/tree-sitter-dart/README.md`\n- **GitNexus vendor notice**（documentation）：This directory is a GitNexus-managed vendored copy of the official tree-sitter-swift@0.7.1 npm runtime package, including its official native prebuilds. GitNexus keeps the top-level tree-sitter dependency pinned to ^0.21.1 until the broader parser runtime upgrade is handled separately. 证据：`gitnexus/vendor/tree-sitter-swift/README.md`\n- **Package**（package_manifest）：{ \"name\": \"gitnexus-shared\", \"version\": \"1.0.0\", \"private\": true, \"description\": \"Shared type definitions for GitNexus CLI and web\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"default\": \"./dist/index.js\" }, \"./test-helpers\": { \"types\": \"./dist/test-helpers.d.ts\", \"default\": \"./dist/test-helpers.js\" } }, \"scripts\": { \"build\": \"tsc\" }, \"files\": \"dist\", \"src\" , \"devDependencies\": { \"typescript\": \"^6.0.3\" } } 证据：`gitnexus-shared/package.json`\n- **Package**（package_manifest）：{ \"name\": \"gitnexus\", \"private\": true, \"version\": \"0.0.0\", \"engines\": { \"node\": \"^20.19.0 =22.12.0\" }, \"type\": \"module\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc -b && vite build\", \"preview\": \"vite preview\", \"test\": \"vitest run\", \"test:watch\": \"vitest\", \"test:coverage\": \"vitest run --coverage\", \"test:e2e\": \"playwright test\", \"test:e2e:ui\": \"playwright test --ui\", \"test:e2e:report\": \"playwright show-report\" }, \"dependencies\": { \"gitnexus-shared\": \"file:../gitnexus-shared\", \"@langchain/anthropic\": \"^1.3.29\", \"@langchain/core\": \"^1.1.44\", \"@langchain/google-genai\": \"^2.1.30\", \"@langchain/langgraph\": \"^1.2.9\", \"@langchain/ollama\": \"^1.2.6\", \"@langchain/openai\": \"^1.4.5\", \"@sigma/edge-curve\": \"… 证据：`gitnexus-web/package.json`\n- **Package**（package_manifest）：{ \"name\": \"gitnexus\", \"version\": \"1.6.4\", \"description\": \"Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.\", \"author\": \"Abhigyan Patwari\", \"license\": \"PolyForm-Noncommercial-1.0.0\", \"homepage\": \"https://github.com/abhigyanpatwari/GitNexus readme\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/abhigyanpatwari/GitNexus.git\", \"directory\": \"gitnexus\" }, \"bugs\": { \"url\": \"https://github.com/abhigyanpatwari/GitNexus/issues\" }, \"keywords\": \"mcp\", \"model-context-protocol\", \"code-intelligence\", \"knowledge-graph\", \"cursor\", \"claude\", \"codex\", \"ai-agent\", \"gitnexus\", \"static-analysis\", \"codebase-indexing\" , \"type\": \"module\", \"bin\": { \"gitnexus\":… 证据：`gitnexus/package.json`\n- **Package**（package_manifest）：{ \"name\": \"gitnexus-monorepo\", \"private\": true, \"scripts\": { \"prepare\": \"husky\", \"format\": \"prettier --write .\", \"format:check\": \"prettier --check .\", \"lint\": \"eslint .\", \"lint:fix\": \"eslint --fix .\", \"gitnexus:refresh\": \"gitnexus analyze --embeddings --skills\", \"gitnexus:full\": \"gitnexus analyze --force --embeddings --skills\" }, \"devDependencies\": { \"@typescript-eslint/eslint-plugin\": \"^8.57.2\", \"@typescript-eslint/parser\": \"^8.57.2\", \"eslint\": \"^9.39.4\", \"eslint-config-prettier\": \"^10.1.8\", \"eslint-plugin-react-hooks\": \"^7.0.1\", \"eslint-plugin-unused-imports\": \"^4.4.1\", \"husky\": \"^9.1.7\", \"lint-staged\": \"^15.5.0\", \"prettier\": \"^3.8.0\", \"prettier-plugin-tailwindcss\": \"^0.7.0\" }, \"lint-stag… 证据：`package.json`\n- **Contributing to GitNexus**（documentation）：How to propose changes, run checks locally, and open pull requests. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"tree-sitter-dart\", \"version\": \"1.0.0\", \"description\": \"Dart grammar attempt for tree-sitter\", \"repository\": \"https://github.com/UserNobody14/tree-sitter-dart\", \"license\": \"ISC\", \"main\": \"bindings/node\", \"types\": \"bindings/node\", \" vendoredBy\": \"gitnexus - pinned to UserNobody14/tree-sitter-dart commit 80e23c07b64494f7e21090bb3450223ef0b192f4. Build deps are hoisted into gitnexus/package.json optionalDependencies, and native compilation is performed by gitnexus/scripts/build-tree-sitter-dart.cjs at gitnexus postinstall.\", \"peerDependencies\": { \"tree-sitter\": \"^0.21.0\" }, \"peerDependenciesMeta\": { \"tree sitter\": { \"optional\": true } } } 证据：`gitnexus/vendor/tree-sitter-dart/package.json`\n- **Package**（package_manifest）：{ \"name\": \"tree-sitter-proto\", \"version\": \"0.4.1\", \"description\": \"tree-sitter grammar for protobuf — ABI 14 build from coder3101/tree-sitter-proto latest grammar.js, compatible with tree-sitter 0.25\", \"repository\": \"https://github.com/coder3101/tree-sitter-proto\", \"license\": \"MIT\", \"main\": \"bindings/node\", \" vendoredBy\": \"gitnexus — build deps node-addon-api, node-gyp-build are hoisted into gitnexus/package.json optionalDependencies, and native compilation is performed by gitnexus/scripts/build-tree-sitter-proto.cjs at gitnexus postinstall. Do NOT re-add a dependencies block or an install script here — doing so reintroduces https://github.com/abhigyanpatwari/GitNexus/issues/836 ENOTEMPTY o… 证据：`gitnexus/vendor/tree-sitter-proto/package.json`\n- **Package**（package_manifest）：{ \"name\": \"tree-sitter-swift\", \"version\": \"0.7.1\", \"description\": \"A tree-sitter grammar for the Swift programming language\", \"main\": \"bindings/node/index.js\", \"types\": \"bindings/node/index.d.ts\", \"license\": \"MIT\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/alex-pinkus/tree-sitter-swift.git\" }, \" vendoredBy\": \"gitnexus - minimal runtime package copied from official tree-sitter-swift@0.7.1 gitHead 88bfd19a89be9d0481b14566fb6160cccea2fe0a . Keeps upstream prebuilds while allowing GitNexus to stay on tree-sitter@0.21.1 until 858 is resolved.\", \"scripts\": { \"install\": \"node-gyp-build\" }, \"dependencies\": { \"node-addon-api\": \"^8.0.0\", \"node-gyp-build\": \"^4.8.0\" }, \"peerDependen… 证据：`gitnexus/vendor/tree-sitter-swift/package.json`\n- **GitNexus CLI Commands**（skill_instruction）：All commands work via npx — no global install required. 证据：`gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md`\n- **Debugging with GitNexus**（skill_instruction）：- \"Why is this function failing?\" - \"Trace where this error comes from\" - \"Who calls this method?\" - \"This endpoint returns 500\" - Investigating bugs, errors, or unexpected behavior 证据：`gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md`\n- **Exploring Codebases with GitNexus**（skill_instruction）：- \"How does authentication work?\" - \"What's the project structure?\" - \"Show me the main components\" - \"Where is the database logic?\" - Understanding code you haven't seen before 证据：`gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md`\n- **GitNexus Guide**（skill_instruction）：Quick reference for all GitNexus MCP tools, resources, and the knowledge graph schema. 证据：`gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md`\n- **Impact Analysis with GitNexus**（skill_instruction）：- \"Is it safe to change this function?\" - \"What will break if I modify X?\" - \"Show me the blast radius\" - \"Who uses this code?\" - Before making non-trivial code changes - Before committing — to understand what your changes affect 证据：`gitnexus-claude-plugin/skills/gitnexus-impact-analysis/SKILL.md`\n- **PR Review with GitNexus**（skill_instruction）：- \"Review this PR\" - \"What does PR 42 change?\" - \"Is this safe to merge?\" - \"What's the blast radius of this PR?\" - \"Are there missing tests for this PR?\" - Reviewing someone else's code changes before merge 证据：`gitnexus-claude-plugin/skills/gitnexus-pr-review/SKILL.md`\n- **Refactoring with GitNexus**（skill_instruction）：- \"Rename this function safely\" - \"Extract this into a module\" - \"Split this service\" - \"Move this to a new file\" - Any task involving renaming, extracting, splitting, or restructuring code 证据：`gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md`\n- **Debugging with GitNexus**（skill_instruction）：When to Use - \"Why is this function failing?\" - \"Trace where this error comes from\" - \"Who calls this method?\" - \"This endpoint returns 500\" - Investigating bugs, errors, or unexpected behavior 证据：`gitnexus-cursor-integration/skills/gitnexus-debugging/SKILL.md`\n- **Exploring Codebases with GitNexus**（skill_instruction）：When to Use - \"How does authentication work?\" - \"What's the project structure?\" - \"Show me the main components\" - \"Where is the database logic?\" - Understanding code you haven't seen before 证据：`gitnexus-cursor-integration/skills/gitnexus-exploring/SKILL.md`\n- **Impact Analysis with GitNexus**（skill_instruction）：When to Use - \"Is it safe to change this function?\" - \"What will break if I modify X?\" - \"Show me the blast radius\" - \"Who uses this code?\" - Before making non-trivial code changes - Before committing — to understand what your changes affect 证据：`gitnexus-cursor-integration/skills/gitnexus-impact-analysis/SKILL.md`\n- **PR Review with GitNexus**（skill_instruction）：- \"Review this PR\" - \"What does PR 42 change?\" - \"Is this safe to merge?\" - \"What's the blast radius of this PR?\" - \"Are there missing tests for this PR?\" - Reviewing someone else's code changes before merge 证据：`gitnexus-cursor-integration/skills/gitnexus-pr-review/SKILL.md`\n- **Refactoring with GitNexus**（skill_instruction）：When to Use - \"Rename this function safely\" - \"Extract this into a module\" - \"Split this service\" - \"Move this to a new file\" - Any task involving renaming, extracting, splitting, or restructuring code 证据：`gitnexus-cursor-integration/skills/gitnexus-refactoring/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"gitnexus-marketplace\", \"owner\": { \"name\": \"GitNexus\", \"email\": \"nico@gitnexus.dev\" }, \"metadata\": { \"description\": \"Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search\", \"homepage\": \"https://github.com/nicosxt/gitnexus\" }, \"plugins\": { \"name\": \"gitnexus\", \"version\": \"1.3.3\", \"source\": \"./gitnexus-claude-plugin\", \"description\": \"Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.\" } } 证据：`.claude-plugin/marketplace.json`\n- **Plugin**（structured_config）：{ \"name\": \"gitnexus\", \"description\": \"Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase.\", \"version\": \"1.3.6\", \"author\": { \"name\": \"GitNexus\" }, \"homepage\": \"https://github.com/abhigyanpatwari/GitNexus\", \"repository\": \"https://github.com/abhigyanpatwari/GitNexus\", \"keywords\": \"code-intelligence\", \"knowledge-graph\", \"mcp\", \"static-analysis\" } 证据：`gitnexus-claude-plugin/.claude-plugin/plugin.json`\n- **Package**（package_manifest）：{\"name\": \"expo-app-fixture\", \"dependencies\": {\"expo-router\": \"^3.0.0\"}} 证据：`gitnexus/test/fixtures/expo-app/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@monorepo/auth\", \"version\": \"1.0.0\" } 证据：`gitnexus/test/fixtures/group/test-monorepo/services/auth/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@monorepo/gateway\", \"version\": \"1.0.0\" } 证据：`gitnexus/test/fixtures/group/test-monorepo/services/gateway/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@monorepo/orders\", \"version\": \"1.0.0\" } 证据：`gitnexus/test/fixtures/group/test-monorepo/services/orders/package.json`\n- **Package**（package_manifest）：{ \"name\": \"api-e2e-test\", \"version\": \"1.0.0\", \"private\": true, \"dependencies\": { \"next\": \"14.0.0\", \"react\": \"18.0.0\" } } 证据：`gitnexus/test/fixtures/lang-resolution/api-e2e-test/package.json`\n- **Acceptance**（source_file）：PolyForm Noncommercial License 1.0.0 证据：`LICENSE`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`gitnexus/vendor/tree-sitter-swift/LICENSE`\n- **COBOL COPY Expansion**（documentation）：The COPY statement is COBOL's include mechanism -- analogous to include in C or import in modern languages. GitNexus expands COPY statements before regex extraction so that symbols defined inside copybooks data items, paragraphs, etc. are visible in the program's extracted graph. 证据：`docs/code-indexing/cobol/copy-expansion.md`\n- **COBOL Deep Indexing**（documentation）：Beyond basic symbol extraction program name, paragraphs, CALL, PERFORM, COPY , GitNexus performs deep indexing of COBOL-specific constructs: data items, EXEC SQL/CICS blocks, file declarations, FD entries, ENTRY points, and MOVE statements. 证据：`docs/code-indexing/cobol/deep-indexing.md`\n- **COBOL File Detection**（documentation）：GitNexus detects COBOL files through two mechanisms: extension-based mapping and directory-based override for extensionless files. This document covers both, plus the copybook/program classification logic. 证据：`docs/code-indexing/cobol/file-detection.md`\n- **COBOL Graph Model**（documentation）：This document describes the graph nodes and edges that GitNexus creates for COBOL codebases. The COBOL graph model is richer than most tree-sitter languages because it captures domain-specific constructs: file declarations, FD entries, data hierarchies, SQL tables, CICS maps, and cross-program contracts. 证据：`docs/code-indexing/cobol/graph-model.md`\n- **COBOL Performance and Tuning**（documentation）：This document covers real-world benchmarks, worker pool configuration, memory management, known limitations, and troubleshooting for COBOL indexing. 证据：`docs/code-indexing/cobol/performance.md`\n- **COBOL Regex Extraction**（documentation）：The extractCobolSymbolsWithRegex function in cobol-preprocessor.ts performs single-pass, state-machine-driven extraction of all COBOL symbols. This document describes the state machine, line processing flow, and every regex pattern used. 证据：`docs/code-indexing/cobol/regex-extraction.md`\n- **Using GitNexus across gRPC microservices**（documentation）：Using GitNexus across gRPC microservices 证据：`docs/guides/microservices-grpc.md`\n- **Using GitNexus across Apache Thrift microservices**（documentation）：Using GitNexus across Apache Thrift microservices 证据：`docs/guides/microservices-thrift.md`\n- **PR 626 HIGH-Priority Fixes Implementation Plan**（documentation）：PR 626 HIGH-Priority Fixes Implementation Plan 证据：`docs/superpowers/plans/2026-04-02-pr626-high-fixes.md`\n- **PR 626 HIGH-Priority Fixes Design**（documentation）：Date: 2026-04-02 PR: abhigyanpatwari/GitNexus 626 — Intra-repo service communication tracking Scope: 4 HIGH-priority issues identified by abhigyanpatwari and xkonjin Approach: Minimal targeted fixes option A — no refactoring, no scope creep 证据：`docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md`\n- **Summary**（documentation）：- gitnexus/ CLI / core / MCP server - gitnexus-web/ Vite / React UI - .github/ workflows, actions - eval/ or other tooling - Docs / agent config only AGENTS.md , CLAUDE.md , .cursor/ , llms.txt , etc. 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Architecture — GitNexus**（documentation）：Monorepo: CLI/MCP gitnexus/ + browser UI gitnexus-web/ . 证据：`ARCHITECTURE.md`\n- **Changelog**（documentation）：All notable changes to GitNexus will be documented in this file. 证据：`CHANGELOG.md`\n- **Definition of Done — GitNexus**（documentation）：Last reviewed: 2026-04-23 · Version: 2.0.0 证据：`DoD.md`\n- **Guardrails — GitNexus**（documentation）：Rules for human contributors and AI agents . Complements AGENTS.md workflows and CONTRIBUTING.md PR process . 证据：`GUARDRAILS.md`\n- **Migration Guide**（documentation）：impact tool may now return { status: 'ambiguous' } PR 888, issue 470 证据：`MIGRATION.md`\n- **Runbook — GitNexus**（documentation）：Short, copy-paste operations for local development , MCP , and CI . Commands assume a Unix shell; on Windows use Git Bash or equivalent paths. 证据：`RUNBOOK.md`\n- **Security Policy**（documentation）：GitNexus is developed on main . Security fixes are applied to the latest released minor on npm gitnexus and to the published Docker images Dockerfile.cli , Dockerfile.web . Older minors are not back-patched. 证据：`SECURITY.md`\n- **Testing — GitNexus**（documentation）：How we structure tests and which commands to run locally and in CI. 证据：`TESTING.md`\n- **Review Context**（documentation）：Project Overview GitNexus is a code intelligence tool that builds a knowledge graph from source code using tree-sitter AST parsing across 12 languages and KuzuDB for graph storage. Two packages: gitnexus/ CLI/MCP, TypeScript and gitnexus-web/ browser . 证据：`compound-engineering.local.md`\n- **Changelog**（documentation）：All notable changes to GitNexus will be documented in this file. 证据：`gitnexus/CHANGELOG.md`\n- **Swift Ingestion Gaps**（documentation）：Tracks missing Swift features in the GitNexus ingestion pipeline. Organized by priority. 证据：`swift-ingestion-gaps.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/code-indexing/cobol/README.md`, `AGENTS.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/code-indexing/cobol/README.md`, `AGENTS.md`, `CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to GitNexus**：importance `high`\n - source_paths: README.md, ARCHITECTURE.md\n- **Quick Start Guide**：importance `high`\n - source_paths: RUNBOOK.md, gitnexus/README.md\n- **Key Concepts**：importance `medium`\n - source_paths: gitnexus/src/core/graph/types.ts, gitnexus/src/core/embeddings/types.ts\n- **System Architecture**：importance `high`\n - source_paths: ARCHITECTURE.md, gitnexus/src/core/ingestion/pipeline.ts, gitnexus/src/mcp/server.ts\n- **Package Structure**：importance `medium`\n - source_paths: gitnexus/package.json, gitnexus-web/package.json, gitnexus-shared/package.json, eval/package.json\n- **MCP Integration**：importance `high`\n - source_paths: gitnexus/src/mcp/server.ts, gitnexus/src/mcp/tools.ts, gitnexus/src/mcp/resources.ts, gitnexus/hooks/claude/gitnexus-hook.cjs\n- **Multi-Repo Registry Architecture**：importance `medium`\n - source_paths: gitnexus/src/storage/repo-manager.ts, gitnexus/src/cli/list.ts, gitnexus/src/mcp/local/local-backend.ts\n- **Indexing Pipeline**：importance `high`\n - source_paths: gitnexus/src/core/ingestion/pipeline.ts, gitnexus/src/core/ingestion/pipeline-phases/runner.ts, gitnexus/src/core/ingestion/pipeline-phases/parse.ts, gitnexus/src/core/ingestion/pipeline-phases/communities.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dad1ca7ab55ee3dae13729e4cbbce54b8c070f15`\n- inspected_files: `package.json`, `README.md`, `docs/guides/microservices-thrift.md`, `docs/guides/microservices-grpc.md`, `docs/plans/2026-03-26-feat-cobol-full-language-coverage-plan.md`, `docs/code-indexing/cobol/graph-model.md`, `docs/code-indexing/cobol/copy-expansion.md`, `docs/code-indexing/cobol/deep-indexing.md`, `docs/code-indexing/cobol/file-detection.md`, `docs/code-indexing/cobol/regex-extraction.md`, `docs/code-indexing/cobol/performance.md`, `docs/code-indexing/cobol/README.md`, `docs/superpowers/specs/2026-04-02-pr626-high-fixes-design.md`, `docs/superpowers/plans/2026-04-02-pr626-high-fixes.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f5cfc2c1ce264d6ab4928a417c66e389 | https://github.com/abhigyanpatwari/GitNexus/issues/1518 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f9b5bf45777e4195a5b65bec8eb05125 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_36bbed40ba504142b4564a0335aa0b91 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Unable to install GitNexus in Mac\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to install GitNexus in Mac\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_fbf96b8de8644eb9b2c948cdc732d96c | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_f7ed64eb318442009c0c45bd394f15e7 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8498a2d89f154c749aac4e7486f4d1f6 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_4b1ddd7fb9104e66b60f9d726b19d298 | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a2a4f1ac62124129844a1b1664fecdff | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d6aff7caa0db4beda6fe67cb86b7ccdd | https://github.com/abhigyanpatwari/GitNexus/issues/1542 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_b7e053347355476db324ef874ef9991c | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：abhigyanpatwari/GitNexus\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Unable to install GitNexus in Mac（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/abhigyanpatwari/GitNexus 项目说明书\n\n生成时间：2026-05-16 01:16:25 UTC\n\n## 目录\n\n- [Introduction to GitNexus](#introduction)\n- [Quick Start Guide](#quick-start)\n- [Key Concepts](#key-concepts)\n- [System Architecture](#system-architecture)\n- [Package Structure](#package-structure)\n- [MCP Integration](#mcp-integration)\n- [Multi-Repo Registry Architecture](#multi-repo-registry)\n- [Indexing Pipeline](#indexing-pipeline)\n- [Knowledge Graph](#knowledge-graph)\n- [Search System](#search-system)\n\n\n\n## Introduction to GitNexus\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Quick Start Guide](#quick-start), [Key Concepts](#key-concepts)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)\n- [src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)\n- [src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/tree-sitter/parser-loader.ts)\n- [src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/scope-extractor.ts)\n- [src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)\n- [src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)\n- [src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [src/mcp/resources.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/mcp/resources.ts)\n- [src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/repo-manager.ts)\n- [src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/grpc-patterns/node.ts)\n- [src/core/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/http-patterns/php.ts)\n- [gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n\n# Introduction to GitNexus\n\nGitNexus is a local-first code intelligence platform that transforms source code repositories into interactive, queryable knowledge graphs. It provides developers with deep visibility into code relationships, symbol dependencies, execution flows, and cross-repository impact analysis.\n\n## What is GitNexus?\n\nGitNexus is a graph-based code analysis tool that:\n\n- **Clones and indexes GitHub repositories** locally on your machine\n- **Parses source code** across multiple programming languages using tree-sitter grammars\n- **Builds a knowledge graph** representing symbols, imports, inheritance, and call relationships\n- **Provides AI-powered tools** for querying, refactoring, and understanding code impact\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx:12-14]()\n\nThe system operates with a clear data-privacy guarantee: public repositories are cloned locally, parsed entirely on your machine, and no data leaves your environment. 资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx:26-27]()\n\n## Installation and Setup\n\n### Prerequisites\n\n| Requirement | Version |\n|-------------|---------|\n| Node.js | 18+ |\n| npm | Latest stable |\n| Git | Configured with remote origin |\n\n### Quick Start\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx:20-21]()\n\nAfter starting the server, the web interface automatically detects when the server is ready and opens the graph visualization without requiring page refresh. 资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx:39-41]()\n\n## Architecture Overview\n\nGitNexus follows a modular architecture with distinct phases for code ingestion, graph construction, and query execution.\n\n```mermaid\ngraph TD\n subgraph Ingestion[\"Ingestion Pipeline\"]\n CLONE[Git Clone] --> PARSE[Code Parsing]\n PARSE --> EXTRACT[Symbol Extraction]\n EXTRACT --> EMIT[Graph Emission]\n end\n \n subgraph Analysis[\"Analysis Engine\"]\n EMIT --> INDEX[Workspace Index]\n INDEX --> RESOLVE[Scope Resolution]\n RESOLVE --> MODEL[Semantic Model]\n end\n \n subgraph Query[\"Query Layer\"]\n MODEL --> MCP[Model Context Protocol]\n MCP --> TOOLS[AI Tools]\n end\n```\n\n### Supported Languages\n\nGitNexus uses tree-sitter for language-agnostic parsing. The following languages are supported through grammar loaders: 资料来源：[src/core/tree-sitter/parser-loader.ts:31-48]()\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | tree-sitter-javascript | Core language |\n| TypeScript | tree-sitter-typescript | Full type support |\n| TSX | tree-sitter-typescript | React JSX syntax |\n| Python | tree-sitter-python | Indentation-based parsing |\n| PHP | tree-sitter-php | Laravel patterns supported |\n\nGrammar loading is centralized in a single registry table. Adding or removing a grammar requires only one entry modification—no scattered conditional spreads or per-grammar branches. 资料来源：[src/core/tree-sitter/parser-loader.ts:21-30]()\n\n## Core Pipeline Phases\n\n### 1. Manifest Extraction\n\nThe manifest extraction phase processes `group.yaml` configuration files to identify cross-repository symbol references.\n\n```mermaid\nflowchart TD\n LINKS[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol]\n RES --> OK{found?}\n OK -->|yes| REF[Real symbol uid + ref]\n OK -->|no| SYN[Synthetic uid manifest::repo::cid]\n REF --> EMIT[Emit Contract + CrossLink]\n SYN --> EMIT\n EMIT --> BRIDGE[Bridge query #795]\n```\n\nLabel-scoped queries in `resolveSymbol` prevent accidental cross-matches using context-aware node types: 资料来源：[src/core/group/PIPELINE.md:14-24]()\n\n- `topic` → `(n:Function|Method|Class|Interface)`\n- `grpc` method → `(n:Function|Method)`, service → `(n:Class|Interface)`\n- `lib` → `(n:Package|Module)`\n\n### 2. Language-Specific Pattern Extraction\n\nGitNexus includes specialized extractors for framework-specific patterns:\n\n#### gRPC Patterns (Node.js/TypeScript)\n\nThe gRPC pattern extractor compiles tree-sitter queries for common protobuf service patterns: 资料来源：[src/core/group/extractors/grpc-patterns/node.ts:1-38]()\n\n| Pattern | Purpose |\n|---------|---------|\n| `grpcMethod` | Detects RPC method definitions |\n| `grpcClient` | Identifies `@GrpcClient(...)` decorator usage |\n| `getService` | Finds `getService()` calls |\n| `newSimpleCtor` | Matches simple constructor patterns |\n| `newQualifiedCtor` | Matches qualified constructor patterns |\n| `loadPackageDefinition` | Detects `loadPackageDefinition()` usage |\n\nBundles are pre-compiled for JavaScript, TypeScript, and TSX: 资料来源：[src/core/group/extractors/grpc-patterns/node.ts:40-42]()\n\n#### HTTP Patterns (PHP)\n\nPHP extraction supports common web frameworks: 资料来源：[src/core/group/extractors/http-patterns/php.ts:1-45]()\n\n| Pattern | Framework | Query Target |\n|---------|-----------|--------------|\n| `laravelRoute` | Laravel | Route definitions |\n| `httpFacade` | Laravel | HTTP facade calls |\n| `guzzleMember` | Guzzle | HTTP client usage |\n| `fileGetContents` | PHP Core | File read operations |\n\n### 3. Scope Extraction\n\nThe scope extraction phase builds the fundamental parse representation used throughout the pipeline.\n\n```mermaid\nflowchart LR\n subgraph Input[\"LanguageProvider Hooks\"]\n RSK[resolveScopeKind]\n BSF[bindingScopeFor]\n II[interpretImport]\n ITB[interpretTypeBinding]\n CC[classifyCallForm]\n end\n \n subgraph Process[\"ScopeExtractor\"]\n Input --> EXTRACT[extract function]\n EXTRACT --> PF[ParsedFile]\n end\n \n PF --> OUTPUT[ownedDefs referenceSites parsedImports]\n```\n\nThe `ScopeExtractorHooks` interface declares the exact subset of `LanguageProvider` methods used, enabling targeted testing and explicit dependency contracts. 资料来源：[src/core/ingestion/scope-extractor.ts:38-56]()\n\n### 4. Heritage Processing (Inheritance Analysis)\n\nThe heritage processor resolves inheritance relationships across the codebase:\n\n```mermaid\ngraph LR\n IMP[implements] --> MAP[heritage-map.ts]\n EXT[extends] --> MAP\n MAP --> RESOLVE[resolveExtendsType]\n RESOLVE --> EMIT[implements relationship to implementor files]\n```\n\nInheritance handling is language-aware with configurable strategies. For `extends` relationships, the system determines whether to treat them as implementation relationships based on language-specific conventions. 资料来源：[src/core/ingestion/heritage-processor.ts:18-29]()\n\n### 5. Reference Emission\n\nReferences connect code locations to the symbols they use:\n\n```mermaid\nflowchart TD\n REF[Reference] --> RESOLVE[Resolve caller def]\n RESOLVE --> WALK[Walk up scope tree]\n WALK --> FOUND{Found Function-like?}\n FOUND -->|yes| EMIT[Emit edge to caller]\n FOUND -->|no| FALLBACK[Use innermost ancestor scope]\n FALLBACK --> SKIP[Skip if no def found]\n```\n\nReference emission optionally flushes scope trees when `INGESTION_EMIT_SCOPES=1` is set, creating: 资料来源：[src/core/ingestion/emit-references.ts:26-35]()\n\n- `Scope` nodes for every scope in the tree\n- `CONTAINS` edges from parent to child scope\n- `DEFINES` edges from scope to owned definitions\n- `IMPORTS` edges from scope to target modules\n\n### 6. Workspace Index Construction\n\nThe workspace index provides efficient reverse-lookups for scope-based queries:\n\n| Map | Purpose |\n|-----|---------|\n| `classScopeByDefId` | Class def `nodeId` → class `Scope` |\n| `classScopeIdToDefId` | Class `Scope.id` → class def `nodeId` |\n\nThe `classScopeIdToDefId` inverse map enables the implicit-`this` overload picker to skip O(C) reverse scans. 资料来源：[src/core/ingestion/scope-resolution/workspace-index.ts:18-27]()\n\n## MCP Tools (Model Context Protocol)\n\nGitNexus exposes AI tooling through the Model Context Protocol: 资料来源：[src/mcp/resources.ts:15-27]()\n\n| Tool | Capability |\n|------|------------|\n| `query` | Process-grouped code intelligence—execution flows related to a concept |\n| `context` | 360-degree symbol view—categorized refs, processes it participates in |\n| `impact` | Symbol blast radius—what breaks at depth 1/2/3 with confidence |\n| `detect_changes` | Git-diff impact—what do your current changes affect |\n| `rename` | Multi-file coordinated rename with confidence-tagged edits |\n| `cypher` | Raw graph queries |\n| `list_repos` | Discover indexed repositories |\n\n### MCP Resources\n\nEach indexed repository exposes structured resources:\n\n```\ngitnexus://repo/{name}/context → Stats, staleness check\ngitnexus://repo/{name}/clusters → All functional areas\ngitnexus://repo/{name}/processes → All execution flows\ngitnexus://repo/{name}/schema → Graph schema for Cypher\n```\n\n资料来源：[src/mcp/resources.ts:29-33]()\n\n## Repository Management\n\nThe `repo-manager.ts` module handles repository registration and working directory matching:\n\n```mermaid\ngraph TD\n REG[Register Repo] --> CWDMATCH[CwdMatch Check]\n CWDMATCH --> MATCH{Result}\n MATCH -->|path| SAME[Same directory tree]\n MATCH -->|sibling-by-remote| SIBLING[Different clone same remote]\n MATCH -->|none| NONE[No relationship]\n SIBLING --> DRIFT[Calculate commit drift]\n DRIFT --> HINT[Optional warning]\n```\n\nThe `CwdMatch` interface captures: 资料来源：[src/storage/repo-manager.ts:14-37]()\n\n- Whether `cwd` is the registered path, a sibling clone, or unrelated\n- The git toplevel when `cwd` is inside a work tree\n- HEAD commit information for drift calculation\n- Human-readable warnings when drift is detected\n\n## Git Integration\n\nGitNexus integrates with Git for repository identification and naming: 资料来源：[src/storage/git.ts:14-26]()\n\n```typescript\nhasGitDir(dirPath) // Check for .git directory\ngetRemoteOriginUrl(repoPath) // Read remote.origin.url\nsanitizeRepoName(name) // Prevent argument injection\n```\n\nThe `sanitizeRepoName` function:\n1. Strips leading dashes to prevent git command-line argument injection\n2. Replaces filesystem-unsafe characters across Windows/macOS/Linux\n\n资料来源：[src/storage/git.ts:45-52]()\n\n## Web Interface\n\n### Graph Visualization\n\nThe interactive graph displays code relationships with visual encoding: 资料来源：[gitnexus-web/src/components/HelpPanel.tsx:7-9]()\n\n| Visual Element | Meaning |\n|----------------|---------|\n| Node size | Connection count—larger nodes are depended on by more files |\n| Edge direction | Points from importer → imported |\n| Edge color | Relationship type (import, call, inheritance) |\n\n### Status Bar\n\nThe status bar displays indexing progress and repository state:\n\n- Progress bar during analysis phases\n- \"Ready\" indicator when idle\n- Sponsor link for community support\n\n资料来源：[gitnexus-web/src/components/StatusBar.tsx:7-18]()\n\n## Cross-Impact Analysis\n\nWhen analyzing symbol changes, GitNexus computes affected code across repositories:\n\n```mermaid\nflowchart TD\n CHANGE[User changes symbol S in repo R] --> LOCAL[Local impact engine per-repo uid expansion]\n LOCAL --> IDS[Affected uid set]\n IDS --> BRIDGE[Bridge query MATCH Contract WHERE uid IN ids]\n BRIDGE --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n OTHER --> FDO[Fan-out impact to consuming repo]\n```\n\nThis enables understanding how a change in one service affects dependent services through contract relationships. 资料来源：[src/core/group/PIPELINE.md:31-40]()\n\n## Semantic Model Contract\n\nThe scope resolution pipeline enforces a single source of truth: 资料来源：[src/core/ingestion/scope-resolution/contract/scope-resolver.ts:48-57]()\n\n> `ParsedFile` is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline.\n\nKey invariants:\n- Symbol-indexed lookups live on `SemanticModel` for the entire codebase\n- Scope-shaped lookups (which `SemanticModel` doesn't carry) live on `WorkspaceResolutionIndex`\n- Edges from `runScopeResolution` and legacy DAG are indistinguishable to downstream consumers\n\n## Summary\n\nGitNexus provides a comprehensive code intelligence platform with:\n\n- **Multi-language parsing** via tree-sitter grammars\n- **Framework-specific pattern detection** for gRPC, Laravel, Guzzle\n- **Scope-aware reference resolution** with heritage tracking\n- **AI-accessible tooling** through MCP\n- **Cross-repository impact analysis** through contract graphs\n- **Local-first architecture** ensuring data privacy\n\nThe system is designed for extensibility—adding new language support requires only grammar registration, and new framework patterns can be dropped into the extractors without modifying the orchestration pipeline.\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Introduction to GitNexus](#introduction), [MCP Integration](#mcp-integration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [RUNBOOK.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md)\n- [gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md)\n- [gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n- [gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n- [gitnexus-web/src/components/DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n- [gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n\n# Quick Start Guide\n\n## Overview\n\nGitNexus is a local-first code analysis tool that clones GitHub repositories, parses source code, and builds an interactive knowledge graph directly in your browser. The tool operates entirely on your machine—no data leaves your computer during analysis.\n\n资料来源：[gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/README.md)\n\n## System Requirements\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Node.js | 18.0.0+ | Runtime for the backend server |\n| npm | 9.0.0+ | Package manager |\n| Supported OS | macOS, Linux, Windows | Platform for running the server |\n| Web Browser | Modern browser | Chrome, Firefox, Edge, or Safari |\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## Installation Options\n\nGitNexus supports two installation methods depending on your workflow preferences.\n\n### Global Installation (Recommended)\n\nInstall GitNexus globally using npm for command-line access from any directory:\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Local Installation\n\nFor project-specific usage, install locally within your project directory:\n\n```bash\nnpm install gitnexus\nnpx gitnexus serve\n```\n\n## Getting Started Workflow\n\nThe onboarding process follows a three-step workflow that automatically connects the web interface to the backend server.\n\n```mermaid\nflowchart TD\n A[Install GitNexus] --> B[Start Server]\n B --> C[Auto-detect Server]\n C --> D[Open Graph UI]\n \n A1[Global: npm install -g] --> B\n A2[Local: npm install] --> B\n \n B --> B1[gitnexus serve]\n B1 --> B2[Server running on port]\n \n C --> C1[Backend Polling]\n C1 --> C2[Connection Established]\n```\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Step 1: Install and Run\n\nOpen a terminal at your project root, then install GitNexus and start the server:\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\nThe server will initialize and begin listening for connections from the web interface.\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### Step 2: Wait for Server Startup\n\nThe web interface automatically detects when the server is ready through backend polling. A progress indicator shows the connection status while waiting.\n\n| State | Description |\n|-------|-------------|\n| `onboarding` | Initial state, awaiting server connection |\n| `analyze` | Server detected, ready for repository analysis |\n| `landing` | Server connected with indexed repositories |\n| `loading` | Processing in progress |\n| `success` | Analysis complete |\n\n资料来源：[gitnexus-web/src/components/DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n### Step 3: Auto-Connect\n\nThe page automatically detects the running server and establishes a WebSocket connection. No page refresh is required—the graph UI loads once the connection is established.\n\n## Analyzing a Repository\n\nAfter connecting to the server, you can analyze any public GitHub repository.\n\n```mermaid\nflowchart LR\n A[Enter GitHub URL] --> B[Server Clones Repo]\n B --> C[Parse Code Structure]\n C --> D[Build Knowledge Graph]\n D --> E[Interactive UI]\n```\n\n### Supported Repository Types\n\n| Type | Support | Notes |\n|------|---------|-------|\n| Public Repositories | ✅ Full | Clone and analyze available |\n| Private Repositories | ❌ Not supported | Requires authentication (future) |\n| Local Repositories | ✅ Via server path | Mounted directories on server machine |\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n### Analysis Workflow\n\n1. **Enter Repository URL**: Paste a GitHub repository URL into the input field\n2. **Start Analysis**: Click the analyze button to begin processing\n3. **Monitor Progress**: View real-time progress with phase indicators\n4. **Cancel if Needed**: Stop analysis at any point before completion\n\n```typescript\n// Analysis phases observed in the codebase\ntype AnalysisPhase = \n | 'cloning' // Repository being cloned\n | 'parsing' // Code being parsed\n | 'indexing' // Building graph index\n | 'complete'; // Analysis finished\n```\n\n资料来源：[gitnexus-web/src/components/StatusBar.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/StatusBar.tsx)\n\n### Privacy and Data Handling\n\n> Public repos only · Cloned locally by the server · No data leaves your machine\n\nRepositories are cloned directly to your local machine. Code parsing and graph generation occur locally without external data transmission.\n\n资料来源：[gitnexus-web/src/components/AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n## Managing Multiple Repositories\n\nWhen multiple repositories have been analyzed, you can switch between them using the repository dropdown in the header.\n\n```mermaid\nflowchart TD\n A[Repository Dropdown] --> B{Select Repo}\n B -->|Same Repo| C[Stay on Current View]\n B -->|Different Repo| D[Switch Repository]\n D --> E[Load New Graph]\n \n F[Active Repository] --> G[Highlighted with accent]\n H[Other Repositories] --> I[Normal styling]\n```\n\n### Repository Selection UI\n\n| Element | Visual Indicator | Behavior |\n|---------|------------------|----------|\n| Active repo | `border-l-2 border-accent` with accent background | Current selection |\n| Other repos | Hover state with `hover:bg-hover` | Clickable to switch |\n| Re-analyze button | Available per repository | Trigger fresh analysis |\n\n资料来源：[gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n### Switching Repositories\n\n1. Open the repository dropdown menu\n2. Click on any repository name\n3. The graph view updates automatically to show the selected repository's knowledge graph\n4. The dropdown closes after selection\n\n```typescript\n// Header component handles repo switching\nonClick={() => {\n if (repo.name !== projectName) onSwitchRepo?.(repo.name);\n setIsRepoDropdownOpen(false);\n}}\n```\n\n## Troubleshooting\n\n### Server Detection Issues\n\nIf the web interface fails to detect the running server:\n\n| Symptom | Solution |\n|---------|----------|\n| \"Connecting...\" message persists | Verify server is running with `gitnexus serve` |\n| Server on different port | Ensure default port is not blocked |\n| Browser console errors | Check WebSocket connection in developer tools |\n\n### Analysis Failures\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| Validation error | Invalid GitHub URL format | Enter a valid `https://github.com/user/repo` URL |\n| Network timeout | Large repository | Retry or clone locally and use local path |\n| Parse errors | Unsupported language | Check supported languages list |\n\n资料来源：[gitnexus-web/src/components/RepoAnalyzer.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/RepoAnalyzer.tsx)\n\n## Configuration\n\n### Backend Server Configuration\n\nThe server can be configured via environment variables or command-line arguments:\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--port` | 3001 | Server listening port |\n| `--host` | localhost | Server bind address |\n| `--data-dir` | ~/.gitnexus | Local storage for cloned repos |\n\n资料来源：[RUNBOOK.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/RUNBOOK.md)\n\n### Frontend Settings\n\nThe web interface provides configuration options through the Settings panel:\n\n- **API Provider Selection**: Choose between Ollama and other providers\n- **Model Configuration**: Set the language model for Graph RAG features\n- **Connection Testing**: Verify backend connectivity\n\n## Next Steps\n\nAfter completing the quick start:\n\n| Task | Description |\n|------|-------------|\n| Explore the Graph | Navigate nodes, zoom, and pan to explore code relationships |\n| Search Symbols | Use the search feature to find functions, classes, and imports |\n| View Dependencies | Click nodes to see import/export relationships |\n| Enable AI Features | Configure Ollama in settings for Graph RAG capabilities |\n| Re-analyze Repos | Use the re-analyze button to refresh repository data |\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n---\n\n\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Knowledge Graph](#knowledge-graph), [Indexing Pipeline](#indexing-pipeline), [MCP Integration](#mcp-integration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/types.ts)\n- [gitnexus/src/core/embeddings/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/types.ts)\n- [gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/utils/ast-helpers.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/utils/ast-helpers.ts)\n- [gitnexus/src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n- [gitnexus/src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/grpc-patterns/node.ts)\n- [gitnexus/src/core/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.ts)\n\n\n# Key Concepts\n\nGitNexus is a sophisticated code repository analysis platform that combines AST-based parsing, dependency graph construction, and semantic embeddings to provide deep insights into codebase architecture. This page covers the fundamental concepts and data structures that power GitNexus's analysis capabilities.\n\n---\n\n## Graph Data Model\n\nThe graph model forms the core of GitNexus's representation of codebases. Every symbol, import, and relationship in a repository is abstracted into graph nodes and edges.\n\n### Node Types\n\nThe graph supports multiple node types representing different code constructs:\n\n| Node Type | Description | Examples |\n|-----------|-------------|----------|\n| `Class` | Class/struct definitions | `class UserService`, `struct Point` |\n| `Interface` | Interface/type definitions | `interface IRepository`, `trait EventHandler` |\n| `Function` | Function/method definitions | `function calculateTotal()`, `def process()` |\n| `Method` | Class/instance methods | `void sendEmail()`, `async def fetch()` |\n| `Module` | File-level modules/packages | `namespace App\\Services`, `module db` |\n| `Package` | Package/module declarations | `package main`, `module foo` |\n\n### Edge Types\n\nEdges represent relationships between nodes:\n\n| Edge Type | Direction | Description |\n|-----------|-----------|-------------|\n| `imports` | importer → imported | Direct import/require statements |\n| `calls` | caller → callee | Function/method invocations |\n| `extends` | subclass → parent | Inheritance relationships |\n| `implements` | impl → interface | Interface implementation |\n| `uses` | consumer → provider | Framework/annotation usage |\n| `contains` | container → contained | Structural containment |\n\n### Node Identifiers\n\nNodes are identified using a deterministic ID scheme:\n\n```typescript\ngenerateId(nodeType: string, uniqueKey: string): string\n```\n\nThe `uniqueKey` typically combines the file path with the symbol name, ensuring uniqueness across the codebase.\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n---\n\n## Ingestion Pipeline\n\nThe ingestion pipeline is a multi-phase system that transforms raw source code into structured graph data.\n\n### Phase Overview\n\n```mermaid\nflowchart TD\n subgraph Phase1[Phase 1: Discovery]\n SC[Scan Files] --> PL[Parse Languages]\n PL --> ID[Identify Code Units]\n end\n \n subgraph Phase2[Phase 2: Extraction]\n ID --> HA[Heritage Analysis]\n HA --> CA[Call Analysis]\n end\n \n subgraph Phase3[Phase 3: Linking]\n CA --> RI[Resolve Imports]\n RI --> XR[Cross-Repo Links]\n end\n \n subgraph Phase4[Phase 4: Indexing]\n XR --> EMB[Generate Embeddings]\n EMB --> STORE[Persist to Database]\n end\n```\n\n### Heritage Processing\n\nHeritage processing extracts inheritance relationships from source code. The `HeritageMap` maintains parent-child relationships across multiple inheritance scenarios:\n\n```typescript\ninterface ParentEntry {\n readonly kind: 'extends' | 'implements';\n readonly parentName: string;\n readonly filePath: string;\n}\n```\n\nThe heritage processor handles:\n\n- **Simple inheritance**: Single class extension\n- **Multiple inheritance**: Multiple parent classes (with C3 linearization for languages supporting it)\n- **Interface implementation**: Distinguishing between `extends` and `implements` based on language semantics\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-50]()\n\n### Call Processing\n\nThe call processor analyzes function invocations and return types across file boundaries:\n\n| Phase | Purpose |\n|-------|---------|\n| P (per-file) | Build type environment and resolve local calls |\n| E1-E3 (cross-file) | Accumulate imported bindings, return types, and type maps |\n| Registry Primary | Languages using built-in registry skip certain phases |\n\nThe processor uses a local-first resolution strategy, preferring local symbol matches over imported ones:\n\n```typescript\n// Consulted ONLY when SymbolTable has no unambiguous match\nimportedReturnTypesMap?: ReadonlyMap>\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-80]()\n\n---\n\n## Pattern Extraction System\n\nGitNexus uses a pattern-based extraction system that allows framework and language-specific analyzers to be added without modifying the core orchestrator.\n\n### Pattern Bundle Architecture\n\nEach language/framework combination defines a `PatternBundle` containing compiled tree-sitter queries:\n\n```typescript\ninterface GrpcPatternBundle {\n grpcMethod: CompiledPatterns>;\n grpcClient: CompiledPatterns>;\n getService: CompiledPatterns>;\n newSimpleCtor: CompiledPatterns>;\n newQualifiedCtor: CompiledPatterns>;\n loadPackageDefinition: CompiledPatterns>;\n}\n```\n\n### Language-Specific Extractors\n\nThe system supports multiple language extractors:\n\n#### JavaScript/TypeScript gRPC Patterns\n\nExtracts gRPC service definitions from Node.js/TypeScript codebases:\n\n- `grpcMethod`: gRPC method declarations\n- `grpcClient`: Client instantiation patterns\n- `getService`: Service retrieval patterns\n\n#### PHP HTTP Patterns\n\nHandles PHP-specific HTTP interactions:\n\n| Pattern | Tree-sitter Query Target |\n|---------|--------------------------|\n| `laravelRoute` | Laravel route definitions |\n| `httpFacade` | HTTP facade usage |\n| `guzzleMember` | Guzzle HTTP client patterns |\n| `fileGetContents` | File reading operations |\n\n```typescript\nconst LARAVEL_ROUTE_SPEC: PatternSpec> = {\n meta: {},\n query: `\n (function_call_expression\n function: (name) @fn (#eq? @fn \"Route::get\")\n arguments: (arguments . (argument (string) @path)))\n `,\n};\n```\n\n资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-60]()\n\n### Extensibility Model\n\nAdding new language support requires only dropping a new file in `*-patterns/` and registering it in `index.ts`. The orchestrator never imports individual grammars, ensuring loose coupling.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:1-20]()\n\n---\n\n## Tree-Sitter Parser Integration\n\nGitNexus leverages tree-sitter for robust, error-tolerant parsing across multiple programming languages.\n\n### Supported Languages\n\n| Language | Package | Notes |\n|----------|---------|-------|\n| TypeScript | `tree-sitter-typescript` | Reuses TSX parser |\n| TSX | `tree-sitter-typescript` | Shares binding with TS |\n| Python | `tree-sitter-python` | Standard Python 3 syntax |\n| Java | `tree-sitter-java` | Java 17+ features |\n| C# | `tree-sitter-c-sharp` | Uses explicit subpath for Node 22 compatibility |\n| C++ | `tree-sitter-cpp` | C++20 features supported |\n| PHP | `tree-sitter-php` | PHP 8.x syntax |\n\n### Parser Loader\n\nThe parser loader provides dynamic language loading with graceful fallback:\n\n```typescript\n[SupportedLanguages.CSharp]: {\n load: () => _require('tree-sitter-c-sharp/bindings/node/index.js'),\n unavailableNote: 'C# parsing requires `tree-sitter-c-sharp/bindings/node/index.js`'\n}\n```\n\nThe explicit subpath import for C# bypasses Node 22's DEP0151 deprecation warning on bare-package imports.\n\n### AST Caching\n\nParsed ASTs are cached to avoid redundant parsing:\n\n```typescript\nlet tree = astCache.get(file.path);\nif (!tree) {\n const parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent)\n });\n astCache.set(file.path, tree);\n}\n```\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-80]()\n\n---\n\n## Semantic Embeddings\n\nGitNexus provides semantic search capabilities through code embeddings, enabling natural language queries against the codebase.\n\n### WebGPU Acceleration\n\nEmbedding generation can utilize WebGPU for GPU-accelerated computation:\n\n```typescript\ninterface EmbeddingConfig {\n backend: 'webgpu' | 'wasm' | 'cpu';\n model: string;\n dimensions: number;\n}\n```\n\n### Fallback Strategy\n\nWhen WebGPU is unavailable, the system offers graceful degradation:\n\n| Option | Performance | Description |\n|--------|-------------|-------------|\n| CPU | Slow | Works universally, ~X minutes for large codebases |\n| WebAssembly | Moderate | Cross-browser compatibility |\n| WebGPU | Fast | Best performance on supported browsers |\n\nThe fallback dialog provides estimated processing time based on repository size:\n\n```typescript\n~{estimatedMinutes} min for {nodeCount} nodes\n```\n\n资料来源：[gitnexus/src/core/embeddings/types.ts]()\n\n---\n\n## Cross-Repository Impact Analysis\n\nGitNexus supports tracking dependencies and impacts across multiple repositories.\n\n### Contract System\n\nContracts define explicit dependencies between repositories:\n\n```mermaid\nflowchart TD\n Y[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol label-scoped Cypher]\n RES --> OK{found?}\n OK -->|yes| REF[real symbol uid + ref]\n OK -->|no| SYN[synthetic uid manifest::repo::cid]\n```\n\n### Cross-Impact Query Engine\n\nWhen a symbol changes in one repository, GitNexus can identify affected contracts in dependent repositories:\n\n```mermaid\nflowchart TD\n U[User changes symbol S in repo R] --> LI[Local impact engine per-repo uid expansion]\n LI --> IDS[Affected uid set]\n IDS --> BR[Bridge query MATCH Contract WHERE uid IN ids]\n BR --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n OTHER --> FE[Fan-out impact to consuming repo]\n```\n\n### Label-Scoped Resolution\n\nQueries use label-scoped matching to prevent cross-contamination:\n\n| Topic | Node Pattern |\n|-------|--------------|\n| `topic` | `(n:Function\\|Method\\|Class\\|Interface)` |\n| `grpc` method | `(n:Function\\|Method)` |\n| `grpc` service | `(n:Class\\|Interface)` |\n| `lib` | `(n:Package\\|Module)` |\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:40-80]()\n\n---\n\n## Symbol Resolution\n\n### Binding Accumulator\n\nThe binding accumulator tracks symbol-to-type mappings across the codebase:\n\n```typescript\n/** Phase 14 E1: imported bindings to seed into buildTypeEnv */\nimportedBindingsMap?: ReadonlyMap>\n```\n\n### Type Environment\n\nType resolution follows a strict priority order:\n\n1. Local symbol table matches (highest priority)\n2. Imported return types map\n3. Imported raw return types (for iteration)\n4. Cross-file heritage map fallback\n\n### AST Helpers\n\nThe AST helper utilities provide common operations across different language grammars:\n\n```typescript\ninterface ClassInfo {\n classId: string;\n className: string;\n}\n\n// Handles language-specific node traversal\nconst nameNode = children.find((c: SyntaxNode) =>\n c.type === 'type_identifier' ||\n c.type === 'identifier' ||\n c.type === 'name' ||\n c.type === 'constant'\n);\n```\n\nSpecial handling exists for:\n- Kotlin's anonymous `interface` keyword in class declarations\n- For-loop element type extraction\n- Scoped type identifiers\n\n资料来源：[gitnexus/src/core/ingestion/utils/ast-helpers.ts:1-80]()\n\n---\n\n## Architecture Summary\n\nGitNexus's architecture follows a clean separation of concerns:\n\n```mermaid\ngraph TB\n subgraph Ingestion[\"Ingestion Layer\"]\n PS[Parser Selector] --> TP[TypeScript Parser]\n PS --> PP[Python Parser]\n PS --> JP[Java Parser]\n TP --> QE[Query Engine]\n PP --> QE\n JP --> QE\n QE --> H[Heritage Map]\n QE --> C[Call Processor]\n end\n \n subgraph Pattern[\"Pattern Extraction\"]\n G[gRPC Bundle] --> E[Extractor]\n HTTP[PHP HTTP] --> E\n E --> SG[Symbol Graph]\n end\n \n subgraph Storage[\"Storage & Query\"]\n SG --> DB[(Graph DB)]\n H --> DB\n C --> DB\n end\n \n subgraph UI[\"Web Interface\"]\n DZ[DropZone] --> HX[Header]\n HX --> SB[StatusBar]\n SB --> GP[Graph Panel]\n end\n \n DB --> GP\n EMB[Embeddings] --> GP\n```\n\n### Key Design Principles\n\n1. **Registry Pattern**: Languages using built-in registries (e.g., Python, Java) skip certain processing phases\n2. **Event Loop Yielding**: Long-running operations yield to the event loop every 20 files to prevent blocking\n3. **Error-Tolerant Parsing**: Parse failures are logged and skipped without halting the entire process\n4. **Lazy Language Loading**: Tree-sitter language parsers are loaded on-demand to minimize memory footprint\n\n---\n\n## See Also\n\n- [Architecture Overview](../architecture/overview.md)\n- [Pattern Extractors](../extractors/index.md)\n- [API Reference](../api/index.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Package Structure](#package-structure), [Indexing Pipeline](#indexing-pipeline), [MCP Integration](#mcp-integration), [Multi-Repo Registry Architecture](#multi-repo-registry)\n\n\nRelevant Source Files\n\nThe following source files were used to generate this documentation:\n\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n- [gitnexus/src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/tree-sitter/parser-loader.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [gitnexus-shared/src/scope-resolution/parsed-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n- [gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n\n# System Architecture\n\nGitNexus is a code analysis and visualization platform that provides dependency graph generation, scope-aware symbol resolution, and cross-repository impact analysis. The system architecture is designed around a multi-stage ingestion pipeline that transforms source code into a queryable knowledge graph.\n\n## Overview\n\nGitNexus operates as a client-server application:\n\n- **Backend Server** (`gitnexus/src/`): A Node.js server responsible for code ingestion, AST parsing, scope resolution, and graph construction\n- **Web Frontend** (`gitnexus-web/src/`): A React-based visualization layer that renders the interactive dependency graph\n\nThe architecture emphasizes separation of concerns: language-specific extraction logic is isolated from the core orchestration, enabling extensibility without modifying the main pipeline.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Core Architectural Principles\n\n### Single Source of Truth\n\nThe `ParsedFile` model (defined in `gitnexus-shared/src/scope-resolution/parsed-file.ts`) serves as the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Scope-resolution passes must not build a parallel parse representation.\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-40](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n\n### Same-Graph Guarantee\n\nEdges emitted by `runScopeResolution` and edges emitted by the legacy DAG are indistinguishable to downstream consumers:\n\n| Aspect | Legacy DAG | Scope Resolution |\n|--------|------------|-------------------|\n| Node Identity | `generateId()` with same qualified-name keyspace | Identical |\n| Edge Vocabulary | `'import-resolved' \\| 'global' \\| 'local-call' \\| 'same-file' \\| 'interface-dispatch' \\| 'read' \\| 'write'` | Identical |\n\nThis ensures transparent interoperability between both code paths.\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n\n### Language Extensibility\n\nThe orchestrator never imports a grammar directly. Adding support for a new language or framework requires only:\n\n1. Dropping one file in `*-patterns/` directory\n2. Registering it in `index.ts`\n\nNo orchestrator edits are required.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Ingestion Pipeline\n\nThe ingestion pipeline processes source code through a series of stages to build the dependency graph.\n\n```mermaid\ngraph TD\n subgraph Ingestion\n FS[File System] --> SCOPE[Scope Extractor]\n SCOPE --> PARSE[Parsing Phase]\n PARSE --> CALLS[Call Processor]\n CALLS --> HERITAGE[Heritage Processor]\n HERITAGE --> FINALIZE[Graph Finalization]\n end\n \n subgraph Language Support\n PARSER[Parser Loader] --> TS[Tree-sitter Grammars]\n TS --> LANG[Language Registry]\n LANG --> PROVIDER[Language Providers]\n end\n \n SCOPE -.-> PROVIDER\n PARSE -.-> PROVIDER\n CALLS -.-> PROVIDER\n HERITAGE -.-> PROVIDER\n```\n\n### Stage 1: Scope Extraction\n\nThe `ScopeExtractor` is the central, source-agnostic driver that converts language provider captures into `ParsedFile` artifacts.\n\n**Key responsibilities:**\n- Build scope tree from `@scope.*` matches\n- Maintain structural invariants (non-module has parent; parent contains child)\n- Produce `ParsedFile` containing: `scopes`, `parsedImports`, `localDefs`, `referenceSites`\n\n**Design principles:**\n- Source-agnostic: Consumes `CaptureMatch[]` from providers\n- One AST walk per language: Providers handle AST traversal internally\n- Pure-ish: Same matches produce same `ParsedFile` output\n- Centralized invariant enforcement via `buildScopeTree`\n\n资料来源：[gitnexus/src/core/ingestion/scope-extractor.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### Stage 2: Call Resolution\n\nThe call processor resolves function and method calls to their definitions.\n\n```mermaid\ngraph LR\n subgraph Input\n FILES[Source Files] --> LANG[Language Detection]\n end\n \n subgraph Processing\n LANG --> PARSE[Parse with Tree-sitter]\n PARSE --> QUERY[Execute Queries]\n QUERY --> MATCHES[Capture Matches]\n MATCHES --> RESOLVE[Resolve Calls to Defs]\n end\n \n subgraph Output\n RESOLVE --> EDGES[Call Edges in Graph]\n end\n```\n\n**Registry-Primary Language Gate:**\n\nFor languages marked as `isRegistryPrimary`, scope-based phase owns CALLS processing, bypassing the legacy call processor:\n\n```typescript\n// Registry-primary gate: scope-based phase owns CALLS for this lang.\nif (isRegistryPrimary(language)) continue;\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n\n### Stage 3: Heritage Processing\n\nHeritage processing resolves class inheritance relationships (`extends` and `implements`).\n\n**Heritage types:**\n- `extends` → creates `EXTENDS` relationship\n- `implements` → creates `IMPLEMENTS` relationship\n\n**Processing logic:**\n```typescript\nif (h.kind === 'extends') {\n const { type: relType, idPrefix } = resolveExtendsType(\n h.parentName,\n h.filePath,\n ctx,\n getHeritageStrategyForLanguage(fileLanguage),\n );\n // Create relationship with confidence score\n graph.addRelationship({\n type: relType,\n confidence: Math.sqrt(child.confidence * parent.confidence),\n });\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n\n### Stage 4: Heritage Map Construction\n\nThe heritage map tracks class/interface inheritance for Method Resolution Order (MRO) calculations.\n\n**Key data structures:**\n\n| Structure | Purpose |\n|-----------|---------|\n| `directParents` | `Map` — parent relationships by kind |\n| `implementorFiles` | `Map>` — tracking implementing files |\n\n**Public API:**\n- `getParentEntries(childNodeId)` → returns `readonly ParentEntry[]`\n- `getParents(childNodeId)` → returns deduplicated `string[]`\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/heritage-map.ts)\n\n## Parser Architecture\n\n### Tree-sitter Integration\n\nGitNexus uses Tree-sitter for universal AST parsing across supported languages.\n\n**Grammar loading strategy:**\n\n```typescript\nconst SOURCES: Record = {\n [SupportedLanguages.JavaScript]: {\n load: () => _require('tree-sitter-javascript'),\n unavailableNote: 'JavaScript parsing requires `tree-sitter-javascript`...',\n },\n [SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript,\n },\n [`${SupportedLanguages.TypeScript}:tsx`]: {\n load: () => _require('tree-sitter-typescript').tsx,\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n },\n // Additional languages...\n};\n```\n\n**Configuration rules:**\n- Grammars must be in `dependencies` (not `optionalDependencies`)\n- Failures indicate real install problems and should never be hidden\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-80](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n### Supported Languages\n\nThe system supports multiple programming languages through a registry pattern:\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | `tree-sitter-javascript` | Registry-primary |\n| TypeScript | `tree-sitter-typescript` | Registry-primary |\n| TSX | `tree-sitter-typescript` | Re-uses TS binding |\n| Python | `tree-sitter-python` | Pattern-based extraction |\n| PHP | `tree-sitter-php` | Framework patterns (Laravel, Guzzle) |\n| C# | `tree-sitter-c-sharp` | Using directive decomposition |\n| Go | `tree-sitter-go` | gRPC pattern support |\n| Ruby | `tree-sitter-ruby` | MRO strategies |\n\n## Workspace Index\n\nThe workspace index provides O(totalScopes) build-time indexing for efficient runtime lookups.\n\n**Interface:**\n\n```typescript\nexport interface WorkspaceResolutionIndex {\n /** Class def `nodeId` → that class's `Scope`. */\n readonly classScopeByDefId: ReadonlyMap;\n \n /** Inverse: class `Scope.id` → class def `nodeId`. */\n readonly classScopeIdToDefId: ReadonlyMap;\n}\n```\n\n**Semantic model lookups:**\n\n| Lookup Type | Source | Purpose |\n|-------------|--------|---------|\n| Owner-keyed method | `model.methods.lookupAllByOwner` | Registry + scope-resolution |\n| Name-keyed callable | `model.symbols.lookupCallableByName` | Symbol resolution |\n| File-indexed symbol | `model.symbols.lookupExactAll` | Exact matching |\n| Scope-shaped | `WorkspaceResolutionIndex` | Implicit `this` overload picker |\n\nThis split preserves the single-source-of-truth invariant: symbol-indexed lookups live on `SemanticModel`; scope-shaped lookups live on `WorkspaceResolutionIndex`.\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## Pattern Extraction System\n\n### Language Pattern Bundles\n\nEach language has pattern bundles compiled from Tree-sitter query specifications:\n\n**Example: PHP HTTP Patterns**\n\n```typescript\nconst PHP_PATTERNS: PhpPatternBundle = {\n laravelRoute: mk(LARAVEL_ROUTE_SPEC, 'laravel-route'),\n httpFacade: mk(HTTP_FACADE_SPEC, 'http-facade'),\n guzzleMember: mk(GUZZLE_MEMBER_SPEC, 'guzzle-member'),\n fileGetContents: mk(FILE_GET_CONTENTS_SPEC, 'file-get-contents'),\n};\n```\n\n**Example: gRPC Patterns (Node.js/TypeScript)**\n\n```typescript\nconst JAVASCRIPT_BUNDLE = compileBundle(JavaScript, 'javascript-grpc');\nconst TYPESCRIPT_BUNDLE = compileBundle(TypeScript.typescript, 'typescript-grpc');\nconst TSX_BUNDLE = compileBundle(TypeScript.tsx, 'tsx-grpc');\n```\n\n**Pattern categories:**\n- HTTP route handlers\n- gRPC service clients\n- Framework-specific patterns (Laravel, Guzzle, etc.)\n- Import/export declarations\n- Call expressions\n\n资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.ts)\n\n## Data Models\n\n### ParsedFile Structure\n\n```typescript\ninterface ParsedFile {\n readonly scopes: Scope[];\n readonly parsedImports: ParsedImport[];\n readonly localDefs: LocalDef[];\n readonly referenceSites: ReferenceSite[];\n}\n```\n\n| Field | Description |\n|-------|-------------|\n| `scopes` | Every `Scope` created for this file, in tree-topological order (module first, then children) |\n| `parsedImports` | Raw `ParsedImport[]` — finalize phase resolves each to concrete `ImportEdge` |\n| `localDefs` | Defs structurally declared in this file; superset of `Scope.ownedDefs` |\n| `referenceSites` | Pre-resolution usage facts; populated by resolution phase |\n\n**What `ParsedFile` deliberately does NOT carry:**\n- Linked `ImportEdge`s (finalize output)\n- `ScopeTree` instance (callers build from `scopes`)\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n\n## Git Integration\n\nThe system integrates with Git repositories for analysis:\n\n**Key functions:**\n\n| Function | Purpose |\n|----------|---------|\n| `hasGitDir(dirPath)` | Check for `.git` directory presence |\n| `getRemoteOriginUrl(repoPath)` | Read `remote.origin.url` for repo naming |\n| `sanitizeRepoName(name)` | Prevent argument injection, ensure cross-platform compatibility |\n\n**Security considerations:**\n- Leading dashes are stripped to prevent git command-line argument injection\n- Characters unsafe for directory names are replaced with underscores\n- `execSync` uses `stdio: ['ignore', 'pipe', 'ignore']` to prevent information leakage\n\n资料来源：[gitnexus/src/storage/git.ts:1-80](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n## Manifest Extraction\n\nThe manifest extraction system links contracts across repositories:\n\n```mermaid\nflowchart TD\n Y[group.yaml links] --> ME[ManifestExtractor]\n ME --> LOOP{for each link}\n LOOP --> RES[resolveSymbol label-scoped Cypher]\n RES --> OK{found?}\n OK -->|yes| REF[real symbol uid + ref]\n OK -->|no| SYN[synthetic uid manifest::repo::cid]\n \n REF --> EMIT[emit provider + consumer Contract objects + CrossLink]\n SYN --> EMIT\n \n EMIT --> BRIDGE[(bridge.lbug #795)]\n```\n\n**Label-scoped queries** prevent accidental cross-matches:\n- `topic` → `(n:Function|Method|Class|Interface)`\n- `grpc` method → `(n:Function|Method)`, service → `(n:Class|Interface)`\n- `lib` → `(n:Package|Module)`\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Cross-Impact Query System\n\nThe cross-impact query system tracks dependencies across repository boundaries:\n\n```mermaid\nflowchart TD\n U[User changes symbol S in repo R] --> LI[Local impact engine per-repo uid expansion]\n LI --> IDS[Affected uid set]\n \n IDS --> BR[Bridge query MATCH Contract WHERE uid IN ids]\n BR --> CL[CrossLink traversal]\n CL --> OTHER[Matching contract in other repo]\n \n OTHER --> FE[Fan-out impact to consuming repo]\n```\n\nThis enables developers to understand the blast radius of changes across service boundaries.\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n## Frontend Architecture\n\nThe web frontend provides the visualization layer:\n\n**Key components:**\n\n| Component | Purpose |\n|-----------|---------|\n| `Header.tsx` | Repository switching, analysis triggers |\n| `DropZone.tsx` | Server connection and repo loading |\n| `HelpPanel.tsx` | Interactive legend and search |\n| `StatusBar.tsx` | Progress tracking and sponsor links |\n| `OnboardingGuide.tsx` | First-time user setup flow |\n\n**Connection states:**\n- `onboarding` — initial setup phase\n- `analyze` — server up but no repos indexed\n- `landing` — server up with indexed repos\n- `success` / `loading` — operation in progress\n\n资料来源：[gitnexus-web/src/components/DropZone.tsx:1-50](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n## Error Handling and Resilience\n\n**Language unavailability:**\n```typescript\nif (!isLanguageAvailable(language)) {\n if (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n }\n continue;\n}\n```\n\n**Parse error handling:**\n```typescript\ntry {\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n });\n} catch (parseError) {\n continue; // Skip malformed files\n}\n```\n\n**Event loop yielding:**\n```typescript\nif (i % 20 === 0) await yieldToEventLoop();\n```\n\nFiles are processed in batches of 20 with event loop yields to prevent UI blocking during large repository analysis.\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-60](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n\n## Performance Considerations\n\n| Optimization | Mechanism |\n|-------------|-----------|\n| AST Caching | `astCache` stores parsed trees keyed by file path |\n| Preprocessing | Per-language source preprocessing (e.g., UE macro stripping for C++) |\n| Batch Processing | 20-file batches with `yieldToEventLoop()` |\n| Workspace Index | O(totalScopes) build-time indexing for O(1) runtime lookups |\n| Confidence Scoring | Geometric mean (`Math.sqrt(child.confidence * parent.confidence)`) for inheritance |\n\n## Summary\n\nGitNexus implements a modular, extensible code analysis architecture:\n\n1. **Pipeline-driven ingestion** with clearly delineated stages\n2. **Language-agnostic core** with pluggable pattern extractors\n3. **Single semantic model** ensuring consistency across analysis paths\n4. **Cross-repository impact tracking** for change propagation analysis\n5. **Tree-sitter-based parsing** with efficient grammar loading\n\nThe architecture prioritizes extensibility (new languages = new pattern files), performance (caching, batching, indexing), and correctness (invariant enforcement, same-graph guarantees).\n\n---\n\n\n\n## Package Structure\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/package.json)\n- [gitnexus-web/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/package.json)\n- [gitnexus-shared/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/package.json)\n- [eval/package.json](https://github.com/abhigyanpatwari/GitNexus/blob/main/eval/package.json)\n\n\n# Package Structure\n\nGitNexus is organized as a **monorepo** with four distinct packages, each serving a specific role in the codebase intelligence platform. The architecture separates concerns between the backend analysis engine, web interface, shared type definitions, and evaluation tooling.\n\n## Monorepo Overview\n\n```mermaid\ngraph TD\n subgraph \"GitNexus Monorepo\"\n Web[gitnexus-web React Frontend]\n Core[gitnexus Core Engine]\n Shared[gitnexus-shared Shared Types]\n Eval[eval Evaluation]\n end\n \n Web <--> Shared\n Core <--> Shared\n Core <--> Web\n Eval --> Core\n```\n\n## Package Breakdown\n\n| Package | Role | Technology |\n|---------|------|------------|\n| `gitnexus` | Core analysis engine, CLI, ingestion pipeline | Node.js, TypeScript |\n| `gitnexus-web` | Web UI, visualization, user interactions | React, TypeScript |\n| `gitnexus-shared` | Shared types, utilities, interfaces | TypeScript |\n| `eval` | Evaluation harness, benchmarking | TypeScript |\n\n## gitnexus — Core Engine\n\nThe core package is the backbone of GitNexus, handling all code analysis, parsing, and knowledge graph construction.\n\n### Directory Structure\n\n```\ngitnexus/src/\n├── cli/ # Command-line interface commands\n│ ├── index.ts # CLI entry point with command registration\n│ ├── wiki.js # Wiki generation command\n│ ├── augment.js # Search pattern augmentation\n│ └── publish.js # Registry notification\n├── core/\n│ ├── ingestion/ # Code parsing and analysis\n│ │ ├── model/ # Heritage map generation\n│ │ ├── scope-extractor.ts\n│ │ ├── heritage-processor.ts\n│ │ └── scope-resolution/\n│ │ └── workspace-index.ts\n│ ├── tree-sitter/ # Parser loader and language support\n│ │ └── parser-loader.ts\n│ └── group/ # Module extraction and contracts\n│ ├── extractors/\n│ │ └── grpc-patterns/\n│ │ └── node.ts\n│ └── PIPELINE.md\n└── storage/\n └── git.ts # Git operations utility\n```\n\n### Key Modules\n\n#### Ingestion Pipeline\n\nThe ingestion system processes source code and builds the knowledge graph:\n\n```mermaid\nflowchart TD\n A[Source Files] --> B[Language Detection]\n B --> C[Tree-sitter Parsing]\n C --> D[AST Analysis]\n D --> E[Scope Extraction]\n E --> F[Heritage Processing]\n F --> G[Knowledge Graph]\n```\n\n- **Scope Extractor** (`scope-extractor.ts`): Extracts bindings, imports, and symbol references using language-specific providers.\n- **Heritage Processor** (`heritage-processor.ts`): Resolves class inheritance and interface implementation relationships.\n- **Workspace Index** (`workspace-index.ts`): Builds O(totalScopes) index for class scope lookups.\n\n#### Tree-sitter Parser Loader\n\nThe parser loader (`parser-loader.ts`) provides language-specific parsing through tree-sitter grammars:\n\n| Language | Grammar Package | Notes |\n|----------|-----------------|-------|\n| JavaScript | `tree-sitter-javascript` | Standard JS parsing |\n| TypeScript | `tree-sitter-typescript` | TS and TSX supported |\n| Python | `tree-sitter-python` | Python source parsing |\n| Java | `tree-sitter-java` | Java class analysis |\n| C# | `tree-sitter-c-sharp` | Uses subpath export |\n| C++ | `tree-sitter-cpp` | C++ source parsing |\n| Go | `tree-sitter-go` | Go package parsing |\n| Rust | `tree-sitter-rust` | Rust module parsing |\n| PHP | `tree-sitter-php` | Uses `php_only` export |\n| Ruby | `tree-sitter-ruby` | Ruby parsing |\n| Vue | `tree-sitter-typescript` | Reuses TypeScript grammar |\n| C | `tree-sitter-c` | Required, ABI-sensitive |\n\n资料来源：[parser-loader.ts:26-90](gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n#### CLI Commands\n\nThe CLI (`index.ts`) provides multiple commands:\n\n- `serve` — Start the backend server\n- `ingest ` — Analyze and index a repository\n- `query ` — Search the knowledge graph\n- `wiki` — Generate documentation from module structure\n- `augment ` — Add knowledge graph context to search\n- `publish [path]` — Notify registry of fresh index\n\n资料来源：[index.ts](gitnexus/src/cli/index.ts)\n\n## gitnexus-web — Frontend Application\n\nThe web package provides the interactive UI for visualizing and exploring the knowledge graph.\n\n### Component Architecture\n\n```\ngitnexus-web/src/\n└── components/\n ├── Header.tsx # Navigation, repo switching\n ├── DropZone.tsx # Server connection, initial probe\n ├── OnboardingGuide.tsx # Setup wizard\n ├── AnalyzeOnboarding.tsx # GitHub repo analyzer\n ├── HelpPanel.tsx # Contextual help, AI queries\n └── StatusBar.tsx # Progress, status indicators\n```\n\n### Key Components\n\n| Component | Purpose |\n|-----------|---------|\n| `Header` | Repository switching, analysis triggers, navigation |\n| `DropZone` | Server detection, backend polling, connection states |\n| `OnboardingGuide` | Step-by-step setup instructions |\n| `AnalyzeOnboarding` | GitHub URL input and cloning |\n| `HelpPanel` | Contextual help, Nexus AI integration |\n| `StatusBar` | Progress bar, ready state, sponsor link |\n\n#### Connection States\n\nThe `DropZone` component manages backend connection through polling:\n\n```typescript\ntype ConnectionPhase = 'onboarding' | 'analyze' | 'landing' | 'success' | 'loading';\n```\n\n资料来源：[DropZone.tsx](gitnexus-web/src/components/DropZone.tsx)\n\n#### Help Panel Modes\n\nThe `HelpPanel` provides contextual guidance for different exploration modes:\n\n- **Graph view** — Node size meaning, edge direction, click interactions\n- **Search & filter** — Query syntax guidance\n- **Nexus AI** — Semantic query examples, \"Semantic Ready\" status\n\n资料来源：[HelpPanel.tsx](gitnexus-web/src/components/HelpPanel.tsx)\n\n## gitnexus-shared — Shared Type System\n\nThe shared package defines TypeScript interfaces, types, and utilities used across both the core engine and web frontend.\n\n### Core Types\n\n| Type | Description |\n|------|-------------|\n| `ParsedFile` | Parsed source file with imports and definitions |\n| `ParsedImport` | Raw import statement |\n| `BindingRef` | Reference to a symbol binding |\n| `ReferenceSite` | Usage location of a symbol |\n| `Scope` | Lexical scope with owned definitions |\n| `ScopeKind` | Scope classification (module, class, function, etc.) |\n| `SymbolDefinition` | Definition of a symbol |\n| `TypeRef` | Reference to a type |\n\n资料来源：[scope-extractor.ts:1-25](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### Utility Functions\n\nThe shared package exports utility functions used throughout the codebase:\n\n- `buildPositionIndex` — Position indexing for source locations\n- `buildScopeTree` — Scope hierarchy construction\n- `canParentScope` — Scope relationship validation\n- `makeScopeId` — Scope identifier generation\n- `isClassLike` — Class-like scope detection\n\n## eval — Evaluation Harness\n\nThe eval package provides benchmarking and evaluation tooling for the analysis engine. It validates correctness of ingestion, querying, and relationship detection.\n\n## Dependency Flow\n\n```mermaid\ngraph LR\n Shared --> Core\n Shared --> Web\n Core --> Web\n Eval --> Core\n \n subgraph \"gitnexus-shared\"\n Shared\n end\n \n subgraph \"gitnexus\"\n Core\n end\n \n subgraph \"gitnexus-web\"\n Web\n end\n \n subgraph \"eval\"\n Eval\n end\n```\n\n## Data Models\n\n### LanguageProvider Interface\n\nThe `LanguageProvider` interface defines hooks for language-specific analysis:\n\n```typescript\ntype ScopeExtractorHooks = Pick<\n LanguageProvider,\n | 'resolveScopeKind'\n | 'bindingScopeFor'\n | 'interpretImport'\n | 'interpretTypeBinding'\n | 'classifyCallForm'\n>;\n```\n\n资料来源：[scope-extractor.ts:55-66](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n### WorkspaceResolutionIndex\n\nBuild-time index for efficient scope lookups:\n\n```typescript\ninterface WorkspaceResolutionIndex {\n readonly classScopeByDefId: ReadonlyMap;\n readonly classScopeIdToDefId: ReadonlyMap;\n}\n```\n\n资料来源：[workspace-index.ts](gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## Adding New Language Support\n\nTo add support for a new language:\n\n1. Add grammar to `SOURCES` in `parser-loader.ts`:\n ```typescript\n [SupportedLanguages.NewLang]: {\n load: () => _require('tree-sitter-newlang'),\n unavailableNote: 'NewLang parsing requires tree-sitter-newlang.',\n },\n ```\n\n2. Register patterns in the group extractors if needed for module extraction.\n\n3. Implement language-specific hooks in `LanguageProvider` if the default extraction is insufficient.\n\n资料来源：[parser-loader.ts](gitnexus/src/core/tree-sitter/parser-loader.ts)\n\n---\n\n\n\n## MCP Integration\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Multi-Repo Registry Architecture](#multi-repo-registry)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/mcp/server.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/server.ts)\n- [gitnexus/src/mcp/tools.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/tools.ts)\n- [gitnexus/src/mcp/resources.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts)\n- [gitnexus/src/cli/setup.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts)\n- [gitnexus/README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)\n- [gitnexus/hooks/claude/gitnexus-hook.cjs](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/hooks/claude/gitnexus-hook.cjs)\n\n\n# MCP Integration\n\nGitNexus provides a Model Context Protocol (MCP) server that exposes the knowledge graph as a set of tools and resources for AI code assistants like Claude. This integration enables AI assistants to query repository structure, understand code relationships, and perform impact analysis directly within their workflow.\n\n## Overview\n\nThe MCP server operates over stdio (standard input/output), making it compatible with any editor or IDE that supports the MCP protocol. When connected, AI assistants can leverage GitNexus's indexed knowledge graph to provide context-aware responses about your codebase.\n\n```mermaid\ngraph TD\n A[\"AI Editor (Claude, Cursor, etc.)\"] -->|\"MCP Protocol stdio\"| B[\"GitNexus MCP Server\"]\n B --> C[\"gitnexus mcp\"]\n C --> D[\"Knowledge Graph DB (Indexed Repos)\"]\n \n E[\"Tool Requests\"] --> B\n B --> F[\"Query Results\"]\n \n G[\"Resource Requests\"] --> B\n B --> H[\"Repo Context Clusters Processes\"]\n```\n\n资料来源：[gitnexus/README.md:17](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L17)\n\n## Starting the MCP Server\n\n### Command-Line Usage\n\n```bash\ngitnexus mcp\n```\n\nThis starts the MCP server in stdio mode, serving all indexed repositories. The server listens for JSON-RPC requests from connected clients and returns structured responses.\n\n资料来源：[gitnexus/README.md:17](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L17)\n\n### Startup Behavior\n\nThe MCP server entry point implements intelligent binary resolution:\n\n1. **Preferred**: Uses the globally-installed `gitnexus` binary (starts in ~1 second)\n2. **Fallback**: Uses `npx -y gitnexus@` when the binary isn't on PATH\n\nThe npx fallback is slower due to cold-cache installation of native dependencies (can exceed 30 seconds), which may exceed Claude Code's MCP connection timeout. The binary path is resolved at module load time and persisted in user config.\n\n```typescript\nfunction getMcpEntry() {\n const bin = resolveGitnexusBin();\n\n if (bin) {\n return { command: bin, args: ['mcp'] };\n }\n\n // Fallback: npx (works without a global install, but slow cold-start)\n if (process.platform === 'win32') {\n return {\n command: 'cmd',\n args: ['/c', 'npx', '-y', NPX_REF, 'mcp'],\n };\n }\n // ...\n}\n```\n\n资料来源：[gitnexus/src/cli/setup.ts:45-62](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts#L45-L62)\n\n## MCP Tools\n\nThe MCP server exposes a comprehensive set of tools for querying and manipulating the knowledge graph. Each tool corresponds to a specific capability within GitNexus.\n\n### Available Tools\n\n| Tool | Purpose | Description |\n|------|---------|-------------|\n| `query` | Process-grouped code intelligence | Find execution flows related to a concept |\n| `context` | 360-degree symbol view | View categorized refs and processes a symbol participates in |\n| `impact` | Symbol blast radius analysis | Determine what breaks at depth 1/2/3 with confidence scores |\n| `detect_changes` | Git-diff impact analysis | Analyze what your current changes affect |\n| `rename` | Multi-file coordinated rename | Perform confidence-tagged edits across files |\n| `cypher` | Raw graph queries | Execute direct Cypher queries against the graph |\n| `list_repos` | Repository discovery | List all indexed repositories |\n\n资料来源：[gitnexus/src/mcp/resources.ts:47-56](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts#L47-L56)\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant Editor as AI Editor\n participant MCP as MCP Server\n participant Graph as Knowledge Graph\n \n Editor->>MCP: tool_request(query, \"auth module\")\n MCP->>MCP: Parse request & validate\n MCP->>Graph: Execute graph query\n Graph-->>MCP: Query results with execution flows\n MCP-->>Editor: Structured JSON response\n```\n\n## MCP Resources\n\nResources provide read-only access to repository metadata and graph schema information. They follow a `gitnexus://` URI scheme for addressing.\n\n### Resource Types\n\n| Resource | URI Pattern | Description |\n|----------|-------------|-------------|\n| Repository Stats | `gitnexus://repo/{name}/context` | Stats, staleness check, symbol counts |\n| Functional Clusters | `gitnexus://repo/{name}/clusters` | All functional areas and groupings |\n| Execution Flows | `gitnexus://repo/{name}/processes` | All execution flows in the repo |\n| Graph Schema | `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |\n\n### Resource Content Format\n\nEach resource returns structured Markdown documentation. For example, the `context` resource includes:\n\n```\nThis project is indexed by GitNexus as **{repo.name}** ({stats.nodes || 0} symbols, {stats.edges || 0} relationships, {stats.processes || 0} execution flows).\n```\n\n资料来源：[gitnexus/src/mcp/resources.ts:30-36](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/resources.ts#L30-L36)\n\n## Editor Integration\n\n### Claude Desktop Configuration\n\nFor Claude Desktop integration, add the GitNexus MCP server to your configuration:\n\n```json\n{\n \"mcpServers\": {\n \"gitnexus\": {\n \"command\": \"gitnexus\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n### Editor Hook System\n\nGitNexus includes Claude-specific hooks that integrate with the MCP server:\n\n```mermaid\ngraph LR\n A[\"gitnexus-hook.cjs\"] -->|Integration| B[\"Claude Code\"]\n A -->|Query| C[\"Knowledge Graph\"]\n B -->|Requests| C\n```\n\nThe hook enables real-time code context awareness during editing sessions, allowing Claude to reference repository structure without manual context switching.\n\n资料来源：[gitnexus/hooks/claude/gitnexus-hook.cjs](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/hooks/claude/gitnexus-hook.cjs)\n\n## Architecture\n\n### Component Overview\n\n```mermaid\ngraph TD\n subgraph \"MCP Layer\"\n A[\"server.ts Request Handler\"] --> B[\"tools.ts Tool Registry\"]\n A --> C[\"resources.ts Resource Provider\"]\n end\n \n subgraph \"Core Services\"\n B --> D[\"runFullAnalysis\"]\n B --> E[\"WikiGenerator\"]\n C --> F[\"RepoRegistry\"]\n end\n \n subgraph \"Data Layer\"\n D --> G[\"LadybugDB (SQLite)\"]\n F --> G\n end\n```\n\n### Request Processing\n\n1. **Connection**: Client establishes stdio connection to `gitnexus mcp`\n2. **Initialization**: Server sends protocol handshake with available capabilities\n3. **Tool Invocation**: Client sends `tools/call` requests\n4. **Query Execution**: Server routes to appropriate handler (graph DB, file system)\n5. **Response**: Structured JSON-RPC response returned via stdio\n\n## Use Cases\n\n### Semantic Code Understanding\n\nWhen asking Claude questions like \"Which files depend on the auth module?\", the MCP server:\n\n1. Receives the `query` tool call\n2. Searches the knowledge graph for import relationships\n3. Returns execution flows and dependency chains\n\n### Impact Analysis\n\nBefore making changes, use the `impact` tool to understand the blast radius:\n\n- **Depth 1**: Direct dependencies\n- **Depth 2**: Transitive dependencies\n- **Depth 3**: Full impact tree with confidence scores\n\n### Change Detection\n\nThe `detect_changes` tool compares current working directory state against the indexed snapshot, returning:\n\n- Modified files\n- Added imports/exports\n- Removed dependencies\n\n## Configuration\n\n### Multi-Repository Support\n\nThe MCP server serves all indexed repositories registered in the global registry. Use `gitnexus list` to see available repos:\n\n```bash\ngitnexus list # List all indexed repositories\ngitnexus status # Show index status for current repo\n```\n\n资料来源：[gitnexus/README.md:20-24](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md#L20-L24)\n\n### Binaries on Windows\n\nOn Windows, `gitnexus` may have multiple entries from `where`:\n- POSIX shell script (not directly executable)\n- `.cmd`/`.bat` wrapper (preferred for `spawn()`)\n\nThe setup code prefers the wrapper to ensure reliable execution:\n\n```typescript\nconst cmdLine = lines.find((l) => /\\.(cmd|bat)$/i.test(l));\nreturn cmdLine || lines[0] || null;\n```\n\n资料来源：[gitnexus/src/cli/setup.ts:21-24](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts#L21-L24)\n\n## Summary\n\nThe MCP Integration layer transforms GitNexus from a standalone analysis tool into a collaborative AI assistant. By exposing the knowledge graph through the Model Context Protocol, it enables:\n\n- **Deep Context**: AI understands codebase structure, not just file names\n- **Impact Awareness**: Changes can be validated against dependency graphs\n- **Cross-Repo Intelligence**: Multi-repository analysis through unified queries\n- **Workflow Integration**: Seamless incorporation into daily editing tasks\n\nThe architecture prioritizes fast startup (global binary preference) and reliable cross-platform execution, making it practical for CI/CD environments and interactive development alike.\n\n---\n\n\n\n## Multi-Repo Registry Architecture\n\n### 相关页面\n\n相关主题：[MCP Integration](#mcp-integration), [Knowledge Graph](#knowledge-graph)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/repo-manager.ts)\n- [gitnexus/src/cli/list.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/list.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n- [gitnexus/src/cli/analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/analyze.ts)\n- [gitnexus/src/core/run-analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/run-analyze.ts)\n\n\n# Multi-Repo Registry Architecture\n\n## Overview\n\nThe Multi-Repo Registry is GitNexus's core system for managing multiple indexed repositories within a single global registry. It provides the foundation for repository discovery, identity resolution, and multi-repo querying across the CLI, MCP server, and web interface.\n\nThe registry persists as `~/.gitnexus/registry.json`, storing metadata for each indexed repository including its path, name, last indexed commit, and statistics about the generated knowledge graph (nodes, edges, processes).\n\n## Registry Data Model\n\n### RegistryEntry Interface\n\nEach entry in the registry represents a single indexed repository:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | The resolved repository name (see Name Resolution Precedence) |\n| `path` | `string` | Absolute filesystem path to the repository |\n| `indexedAt` | `number` | Unix timestamp when the repo was last indexed |\n| `lastCommit` | `string \\| undefined` | Git commit SHA of the last analyzed state |\n| `stats` | `RegistryStats \\| undefined` | Graph statistics (files, nodes, edges, communities, processes, embeddings) |\n| `remoteUrl` | `string \\| undefined` | The `remote.origin.url` for the repo |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:60-70]()\n\n### CwdMatch Interface\n\nThe registry provides a matching interface to resolve the current working directory against indexed repositories:\n\n```typescript\nexport interface CwdMatch {\n match: 'path' | 'sibling-by-remote' | 'none';\n entry?: RegistryEntry;\n cwdGitRoot?: string;\n cwdHead?: string;\n drift?: number;\n hint?: string;\n}\n```\n\nThe `CwdMatch` interface supports three match scenarios:\n\n| Match Type | Description |\n|------------|-------------|\n| `path` | Exact path match — `cwd` is a subdirectory of a registered repo |\n| `sibling-by-remote` | Same remote URL — `cwd` is a different on-disk clone of a registered repo |\n| `none` | No relationship found |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:200-220]()\n\n## Name Resolution Precedence\n\nGitNexus employs a four-tier name resolution strategy to determine the registry name for an indexed repository:\n\n```mermaid\ngraph TD\n A[Start: Determine registry name] --> B{T Explicit --name provided?}\n B -->|Yes| C[Use explicit name]\n B -->|No| D{Existing entry with preserved alias?}\n D -->|Yes| E[Use preserved alias]\n D -->|No| F{remote.origin.url available?}\n F -->|Yes| G[Derive name from remote URL]\n F -->|No| H[Use path.basename]\n \n C --> I[Store in registry]\n E --> I\n G --> I\n H --> I\n```\n\n### Resolution Tiers\n\n| Priority | Source | Rationale |\n|----------|--------|-----------|\n| 1 | `--name ` CLI flag | Explicit user-provided alias |\n| 2 | Preserved alias on existing entry | Maintains name across re-analyzes |\n| 3 | `git config --get remote.origin.url` | Recovers meaningful names for monorepo subprojects, git worktrees, and Gas-Town-style layouts |\n| 4 | `path.basename(repoPath)` | Original default behavior |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:290-310]()\n\n### Git Worktree Support\n\nA key architectural concern is handling git worktrees correctly. When running `gitnexus analyze` inside a linked worktree, the system uses `git rev-parse --git-common-dir` to derive the **canonical repository root**, preventing worktrees from being registered under their directory slug (e.g., `wt-feature`) instead of the actual repo name (e.g., `repo`).\n\n```typescript\nexport const resolveRepoIdentityRoot = (fromPath: string): string => {\n const resolved = path.resolve(fromPath);\n const canonical = getCanonicalRepoRoot(resolved);\n if (!canonical) return resolved;\n if (canonical === resolved) return canonical;\n if (hasGitDir(resolved)) return canonical; // linked worktree\n return resolved; // arbitrary subdir → preserve as-is\n};\n```\n\nWithout this, each worktree would re-register as a \"different\" project, causing AGENTS.md to be rewritten with the wrong MCP URI and silently accumulating duplicate registry entries.\n\n资料来源：[gitnexus/src/storage/git.ts:90-110]()\n\n## Registry Operations\n\n### Registration Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as gitnexus analyze\n participant RM as repo-manager\n participant FS as filesystem\n participant Git as git utilities\n \n CLI->>RM: registerRepo(repoPath, opts)\n RM->>Git: getRemoteOriginUrl(repoPath)\n RM->>Git: resolveRepoIdentityRoot(repoPath)\n RM->>RM: resolveName(precedence tiers)\n RM->>RM: checkDuplicateName()\n alt duplicate found & !allowDuplicateName\n RM-->>CLI: throw RegistryNameCollisionError\n else allowed or no duplicate\n RM->>FS: persist to registry.json\n RM-->>CLI: return resolved name\n end\n```\n\n#### Registration Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `name` | `string \\| undefined` | Explicit alias for registry name |\n| `allowDuplicateName` | `boolean` | Bypass collision guard, allowing two paths to share the same name |\n\nThe duplicate-name guard only fires when the user explicitly passes a `name`; un-aliased basename collisions continue to register silently so existing users see no behavior change.\n\n资料来源：[gitnexus/src/core/run-analyze.ts:45-60]()\n\n### Listing Repositories\n\nThe `gitnexus list` command displays all indexed repositories with collision-aware formatting:\n\n```typescript\nexport const listCommand = async () => {\n const entries = await listRegisteredRepos({ validate: true });\n const nameCounts = new Map();\n \n for (const entry of entries) {\n const key = entry.name.toLowerCase();\n nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);\n }\n \n for (const entry of entries) {\n const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;\n const header = hasCollision ? `${entry.name} (${entry.path})` : entry.name;\n // display with path disambiguation for collisions\n }\n};\n```\n\nEntries with name collisions display their path to disambiguate:\n\n```\n myapp (/projects/myapp)\n myapp (/worktrees/myapp-feature)\n```\n\n资料来源：[gitnexus/src/cli/list.ts:15-50]()\n\n### Repository Switching (Web Interface)\n\nThe web interface supports switching between indexed repositories via a dropdown menu. The Header component renders available repos with an \"active\" indicator for the current project:\n\n```tsx\n{availableRepos.map((repo) => (\n
\n \n
\n))}\n```\n\n资料来源：[gitnexus-web/src/components/Header.tsx:1-50]()\n\n## Error Handling\n\n### RegistryNameCollisionError\n\nWhen two different repository paths attempt to register under the same name without the `--allow-duplicate-name` flag, the system throws `RegistryNameCollisionError` with actionable guidance:\n\n```\nRegistry name collision:\n \"myapp\" is already used by \"/projects/myapp\".\n\nOptions:\n • Pick a different alias: gitnexus analyze --name \n • Allow the duplicate: gitnexus analyze --allow-duplicate-name\n```\n\n资料来源：[gitnexus/src/cli/analyze.ts:30-45]()\n\n### AnalysisNotFinalizedError\n\nIf the analysis pipeline fails to complete, users receive diagnostic guidance:\n\n1. Re-run `gitnexus analyze` — transient native errors often clear on retry\n2. Inspect the storage path for leftover `lbug.wal` indicating an aborted write\n3. Run with `NODE_OPTIONS=\"--max-old-space-size=8192 --trace-exit\"` for detailed tracing\n\n资料来源：[gitnexus/src/cli/analyze.ts:50-70]()\n\n## MCP Server Integration\n\nThe MCP server exposes registry information through the `gitnexus://repo/{name}/*` URI scheme:\n\n| Resource URI | Content |\n|--------------|---------|\n| `gitnexus://repo/{name}/context` | Stats, staleness check |\n| `gitnexus://repo/{name}/clusters` | All functional areas |\n| `gitnexus://repo/{name}/processes` | All execution flows |\n| `gitnexus://repo/{name}/schema` | Graph schema for Cypher |\n\n资料来源：[gitnexus/src/mcp/resources.ts:40-55]()\n\n## Configuration Storage\n\nRegistry metadata is stored alongside the index in the GitNexus storage directory:\n\n```typescript\nconst { registryPath, indexPath, metaPath } = getStoragePaths(repoName, repoPath);\n```\n\nThe registry file (`registry.json`) maintains the authoritative list of all indexed repositories and is the single source of truth for repository discovery across CLI, MCP, and web components.\n\n## Summary\n\nThe Multi-Repo Registry Architecture provides:\n\n- **Centralized repository tracking** via `~/.gitnexus/registry.json`\n- **Intelligent name resolution** with support for aliases, git remotes, and worktrees\n- **Collision detection** with graceful degradation via `--allow-duplicate-name`\n- **Unified discovery** across CLI (`list`, `query`), MCP (`list_repos`), and web interfaces\n- **Cross-repo intelligence** enabling queries and context to span multiple repositories\n\n---\n\n\n\n## Indexing Pipeline\n\n### 相关页面\n\n相关主题：[Knowledge Graph](#knowledge-graph), [Search System](#search-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/ingestion/pipeline-phases/parse.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/parse.ts)\n- [gitnexus-shared/src/scope-resolution/parsed-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/scope-resolution/parsed-file.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n- [gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/scope-extractor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/scope-extractor.ts)\n- [gitnexus/src/core/ingestion/parsing-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/parsing-processor.ts)\n- [gitnexus/src/core/ingestion/call-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/call-processor.ts)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/PIPELINE.md)\n\n\n# Indexing Pipeline\n\nThe Indexing Pipeline is the core ingestion system that transforms source code repositories into a graph-based representation. It scans, parses, extracts semantic relationships, and builds the knowledge graph that powers GitNexus's dependency visualization and impact analysis capabilities.\n\n## Overview\n\nThe pipeline operates as a multi-phase execution engine where each phase depends on the output of previous phases. It processes source files through sequential stages, extracting code symbols, relationships, and metadata to construct the semantic graph.\n\n```mermaid\ngraph TD\n A[Source Files] --> B[Structure Phase]\n B --> C[Parse Phase]\n C --> D[Scope Extraction]\n D --> E[Finalize Phase]\n E --> F[Call Processing]\n E --> G[Heritage Processing]\n D --> H[Communities Detection]\n F --> I[Graph Completion]\n G --> I\n H --> I\n I --> J[Indexed Graph]\n```\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md]()\n\n## Pipeline Architecture\n\n### Phase Execution Model\n\nThe pipeline is built on a `PipelinePhase` abstraction where each phase declares its dependencies and implements an `execute` function:\n\n```typescript\nconst pipelinePhase: PipelinePhase = {\n name: 'parse',\n deps: ['structure', 'markdown', 'cobol'],\n async execute(\n ctx: PipelineContext,\n deps: ReadonlyMap>,\n ): Promise { /* ... */ }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/parse.ts:1-24]()\n\n### Pipeline Context\n\nThe `PipelineContext` carries shared state across phases:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `graph` | `SemanticGraph` | The graph being built |\n| `repoPath` | `string` | Absolute path to the repository |\n| `pipelineStart` | `number` | Timestamp when pipeline started |\n| `onProgress` | `ProgressCallback` | Progress reporting callback |\n| `options` | `PipelineOptions` | Configuration for the pipeline |\n\n## Phase Breakdown\n\n### Structure Phase\n\nThe entry point that discovers and classifies files in the repository. It builds the initial file inventory with metadata including paths, sizes, and detected languages.\n\n### Parse Phase\n\nThe parse phase transforms source files into structured AST representations using tree-sitter parsers. It processes files in a chunked, parallel manner to handle large repositories efficiently.\n\n```typescript\nconst result = await runChunkedParseAndResolve(\n ctx.graph,\n scannedFiles,\n allPaths,\n totalFiles,\n ctx.repoPath,\n ctx.pipelineStart,\n ctx.onProgress,\n ctx.options,\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/parse.ts:17-24]()\n\n#### Parsing Processor\n\nThe `parsing-processor.ts` handles the actual file parsing and extraction:\n\n```typescript\nconst merged = mergeChunkResults(graph, symbolTable, chunkResults);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n### Scope Extraction Phase\n\nScope extraction produces `ParsedFile` objects that represent the semantic structure of each source file. This is the per-file, parallelizable boundary between extraction and cross-file resolution.\n\n#### ParsedFile Structure\n\n```typescript\ninterface ParsedFile {\n readonly scopes: Scope[]; // All scopes in the file\n readonly parsedImports: ParsedImport[]; // Raw imports before resolution\n readonly localDefs: SymbolDefinition[]; // Structurally declared definitions\n readonly referenceSites: ReferenceSite[]; // Pre-resolution usage facts\n}\n```\n\n资料来源：[gitnexus-shared/src/scope-resolution/parsed-file.ts:1-30]()\n\nThe `ParsedFile` deliberately does NOT carry:\n- Linked `ImportEdge`s (those are finalize output)\n- A `ScopeTree` instance (callers build one from `scopes`)\n\n#### Scope Extraction Hooks\n\nLanguage providers implement these hooks for scope extraction:\n\n```typescript\nexport type ScopeExtractorHooks = Pick<\n LanguageProvider,\n | 'resolveScopeKind'\n | 'bindingScopeFor'\n | 'interpretImport'\n | 'interpretTypeBinding'\n | 'classifyCallForm'\n>;\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-extractor.ts:30-48]()\n\n### Call Processing Phase\n\nCall processing extracts function/method invocations and builds dispatch information. It works with language providers to query ASTs using tree-sitter queries:\n\n```typescript\ninterface PreparedFile {\n language: SupportedLanguages;\n provider: ReturnType;\n tree: ReturnType;\n matches: ReturnType;\n parentMap: ReadonlyMap;\n typeEnv: ReturnType;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-20]()\n\nThe call processor skips registry-primary languages since scope-based phases own CALLS extraction for those languages.\n\n### Heritage Processing Phase\n\nHeritage processing extracts inheritance relationships (extends/implements) and resolves them into graph edges:\n\n```mermaid\ngraph TD\n H[Heritage Record] -->|extends| E{Extends Type Check}\n H -->|implements| I{Is Implements}\n E -->|IMPLEMENTS| I\n E -->|CLASS| C[Add Extends Edge]\n I -->|Yes| Impl[Add Implements Edge]\n```\n\nFor `extends` relationships, the processor determines the relationship type based on the language:\n\n```typescript\nconst { type: relType, idPrefix } = resolveExtendsType(\n h.parentName,\n h.filePath,\n ctx,\n getHeritageStrategyForLanguage(fileLanguage),\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-50]()\n\n### Communities Detection Phase\n\nDetects code communities and modules within the codebase, enabling grouped visualization and analysis.\n\n## Scope Resolution\n\n### Resolution Indexes\n\nAfter the main parsing phases, scope resolution builds cross-file indexes:\n\n```typescript\nexport interface ScopeResolutionIndexes {\n readonly scopeTree: ScopeTree;\n readonly defs: DefIndex;\n readonly qualifiedNames: QualifiedNameIndex;\n readonly moduleScopes: ModuleScopeIndex;\n readonly methodDispatch: MethodDispatchIndex;\n readonly imports: ImportEdge[];\n readonly bindings: BindingIndex;\n readonly referenceSites: ReferenceSite[];\n readonly stats: FinalizeStats;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution-indexes.ts:1-35]()\n\n### Workspace Resolution Index\n\nThe workspace index provides fast lookups for class and module scopes:\n\n```typescript\nexport interface WorkspaceResolutionIndex {\n /** Class def `nodeId` → that class's `Scope`. */\n readonly classScopeByDefId: ReadonlyMap;\n\n /** Class `Scope.id` → class def `nodeId`. */\n readonly classScopeIdToDefId: ReadonlyMap;\n\n /** Module scope by file path. */\n readonly moduleScopeByFile: ReadonlyMap;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:1-30]()\n\n### Building the Index\n\n```typescript\nexport function buildWorkspaceResolutionIndex(\n parsedFiles: readonly ParsedFile[],\n): WorkspaceResolutionIndex {\n const classScopeByDefId = new Map();\n const classScopeIdToDefId = new Map();\n const moduleScopeByFile = new Map();\n\n for (const parsed of parsedFiles) {\n const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');\n if (moduleScope !== undefined) moduleScopeByFile.set(parsed.filePath, moduleScope);\n\n for (const scope of parsed.scopes) {\n if (scope.kind !== 'Class') continue;\n const cd = scope.ownedDefs.find((d) => isClassLike(d.type));\n if (cd !== undefined) {\n classScopeByDefId.set(cd.nodeId, scope);\n classScopeIdToDefId.set(scope.id, cd.nodeId);\n }\n }\n }\n\n return { classScopeByDefId, classScopeIdToDefId, moduleScopeByFile };\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts:30-55]()\n\n## Language Support\n\nThe pipeline supports multiple languages through provider-specific implementations:\n\n### PHP Import Resolution\n\n```typescript\nexport function resolvePhpImportTargetInternal(\n targetRaw: string,\n _fromFile: string,\n allFilePaths: ReadonlySet,\n resolutionConfig?: unknown,\n): string | null\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/php/import-target.ts:1-30]()\n\n### C Header Scanning\n\n```typescript\nexport function scanHeaderFiles(repoPath: string): ReadonlySet {\n const headers = new Set();\n walk(repoPath, repoPath, headers);\n return headers;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/c/header-scan.ts:1-20]()\n\n### C# Import Decomposition\n\n```typescript\ntype ImportKind = 'namespace' | 'alias' | 'static';\n\ninterface ImportSpec {\n readonly kind: ImportKind;\n readonly source: string;\n readonly name: string;\n readonly alias?: string;\n readonly atNode: SyntaxNode;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/languages/csharp/import-decomposer.ts:1-30]()\n\n## Semantic Model Contract\n\nThe `ParsedFile` is the single semantic model consumed by both the legacy DAG and the scope-resolution pipeline. Key invariants:\n\n1. **Scope-resolution passes MUST NOT build a parallel parse representation** — they should reuse the orchestrator's `treeCache`\n2. **Edits from `runScopeResolution` and the legacy DAG are indistinguishable** to downstream consumers\n3. **Node identity uses the same `generateId()` helper** across both paths\n\n资料来源：[gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts:1-30]()\n\n## Performance Considerations\n\n### Chunked Processing\n\nFiles are processed in chunks to maintain responsiveness:\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n const file = files[i];\n onProgress?.(i + 1, files.length);\n if (i % 20 === 0) await yieldToEventLoop();\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:10-15]()\n\n### Worker Pool Dispatch\n\nThe parsing processor uses a worker pool for parallel file processing:\n\n```typescript\nconst chunkResults = await workerPool.dispatch(\n parseableFiles,\n (filesProcessed) => {\n onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');\n },\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n### Cache Management\n\nASTs are cached with buffer size optimization for large files:\n\n```typescript\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\ntree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n});\nastCache.set(file.path, tree);\n```\n\n## Configuration\n\n### Language Availability\n\n```typescript\nconst language = getLanguageFromFilename(file.path);\nif (!language) continue;\nif (!isLanguageAvailable(language)) {\n if (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n }\n continue;\n}\n```\n\n### Tree-sitter Queries\n\nEach language provider supplies tree-sitter queries for extraction:\n\n```typescript\nconst provider = getProvider(language);\nconst queryStr = provider.treeSitterQueries;\nif (!queryStr) continue;\n```\n\n## Summary\n\nThe Indexing Pipeline transforms source code into a queryable graph through:\n\n1. **Structure Discovery** — File enumeration and classification\n2. **Parallel Parsing** — Tree-sitter AST generation with caching\n3. **Scope Extraction** — Per-file semantic structure extraction\n4. **Cross-file Resolution** — Import and reference resolution\n5. **Relationship Building** — Heritage, calls, and dependencies\n6. **Index Materialization** — Fast lookup indexes for the graph\n\nThe pipeline is designed for incremental updates and supports both full repository ingestion and targeted re-indexing of changed files.\n\n---\n\n\n\n## Knowledge Graph\n\n### 相关页面\n\n相关主题：[Indexing Pipeline](#indexing-pipeline), [Search System](#search-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/graph/graph.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/graph.ts)\n- [gitnexus/src/core/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/types.ts)\n- [gitnexus-shared/src/graph/types.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-shared/src/graph/types.ts)\n- [gitnexus/src/core/ingestion/model/semantic-model.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/model/semantic-model.ts)\n- [gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/emit-references.ts)\n- [gitnexus/src/core/ingestion/structure-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/structure-processor.ts)\n- [gitnexus/src/core/ingestion/parsing-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/parsing-processor.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts)\n\n\n# Knowledge Graph\n\nThe Knowledge Graph is the core data structure in GitNexus that represents a codebase as an interconnected network of nodes and relationships. It serves as the semantic backbone for code exploration, dependency analysis, and AI-powered queries.\n\n## Overview\n\nThe Knowledge Graph transforms source code into a queryable graph where:\n\n- **Nodes** represent code entities (files, functions, classes, interfaces, modules)\n- **Edges** represent relationships (imports, calls, containment, inheritance)\n\nThis abstraction enables powerful navigation patterns like tracing execution flows, finding circular dependencies, and identifying highly-connected components.\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n## Core Architecture\n\n### Graph Interface\n\nThe `KnowledgeGraph` interface provides the fundamental operations for building and querying the graph:\n\n```typescript\ninterface KnowledgeGraph {\n addNode(node: GraphNode): void;\n addRelationship(relationship: GraphRelationship): void;\n removeNode(nodeId: string): boolean;\n removeNodesByFile(filePath: string): number;\n removeRelationship(relationshipId: string): boolean;\n getNode(id: string): GraphNode | undefined;\n forEachNode(fn: (node: GraphNode) => void): void;\n forEachRelationship(fn: (rel: GraphRelationship) => void): void;\n nodeCount: number;\n relationshipCount: number;\n}\n```\n\n资料来源：[gitnexus/src/core/graph/types.ts]()\n\n### Node Structure\n\nGraph nodes contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `string` | Unique identifier (e.g., `File:src/index.ts`) |\n| `label` | `NodeLabel` | Entity type (File, Function, Class, etc.) |\n| `properties` | `Record` | Metadata (name, filePath, line numbers, language) |\n\n资料来源：[gitnexus-shared/src/graph/types.ts]()\n\n### Relationship Structure\n\nRelationships connect nodes with semantic meaning:\n\n```typescript\ninterface GraphRelationship {\n id: string;\n type: RelationshipType;\n sourceId: string;\n targetId: string;\n confidence: number; // 0.0 - 1.0\n reason: string; // Human-readable explanation\n}\n```\n\n资料来源：[gitnexus-shared/src/graph/types.ts]()\n\n## Node Types\n\nThe system recognizes multiple node labels representing different code entities:\n\n| Node Label | Description |\n|------------|-------------|\n| `File` | Source file node |\n| `Folder` | Directory node |\n| `Function` | Function or method |\n| `Class` | Class definition |\n| `Interface` | Interface definition |\n| `Struct` | Struct definition (Go, Rust, C) |\n| `Enum` | Enumeration |\n| `Trait` | Trait definition |\n| `Module` | Module (COBOL programs, packages) |\n| `Property` | Data item or property |\n| `TypeAlias` | Type alias definition |\n| `Const` | Constant declaration |\n| `Static` | Static member |\n| `Record` | Record type |\n| `Union` | Union type |\n| `Typedef` | Type definition |\n| `Macro` | Preprocessor macro |\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts]()\n\n## Relationship Types\n\n### Core Relationships\n\n| Type | Description | Direction |\n|------|-------------|-----------|\n| `CONTAINS` | Parent-child hierarchy | Parent → Child |\n| `IMPORTS` | Import/require statements | Importer → Imported |\n| `CALLS` | Function invocations | Caller → Callee |\n| `DECLARES` | Symbol definitions | Scope → Symbol |\n| `EXTENDS` | Inheritance (parent class) | Child → Parent |\n| `IMPLEMENTS` | Interface implementation | Class → Interface |\n| `USES` | Variable/type usage | User → Used |\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n### Confidence Scoring\n\nRelationships include a `confidence` score:\n\n- `1.0` - Resolved reference (fully verified)\n- `0.5` - Unresolved reference (symbol not found in index)\n\n```typescript\ngraph.addRelationship({\n id: `rel:imports:${scopeId}->${targetModule}:${localName}`,\n sourceId: scopeId,\n targetId: targetModule,\n type: 'IMPORTS',\n confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,\n reason: `import ${edge.kind} ${edge.localName}`,\n});\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n \n## Build Pipeline\n\nThe Knowledge Graph is constructed through a multi-phase pipeline:\n\n```mermaid\ngraph TD\n A[Source Files] --> B[Structure Processor]\n B --> C[File/Folder Nodes]\n C --> D[Parsing Processor]\n D --> E[Symbol Nodes]\n E --> F[Emit References]\n F --> G[Import Edges]\n G --> H[Wildcard Synthesis]\n H --> I[Final Graph]\n```\n\n### Phase 1: Structure Processing\n\nThe structure processor creates nodes for the file system hierarchy:\n\n```typescript\nconst processStructure = (graph: KnowledgeGraph, paths: string[]) => {\n paths.forEach((path) => {\n const parts = path.split('/');\n let currentPath = '';\n let parentId = '';\n\n parts.forEach((part, index) => {\n const isFile = index === parts.length - 1;\n const label = isFile ? 'File' : 'Folder';\n currentPath = currentPath ? `${currentPath}/${part}` : part;\n const nodeId = generateId(label, currentPath);\n \n graph.addNode({\n id: nodeId,\n label: label,\n properties: { name: part, filePath: currentPath },\n });\n\n if (parentId) {\n graph.addRelationship({\n id: generateId('CONTAINS', `${parentId}->${nodeId}`),\n type: 'CONTAINS',\n sourceId: parentId,\n targetId: nodeId,\n confidence: 1.0,\n reason: '',\n });\n }\n parentId = nodeId;\n });\n });\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/structure-processor.ts]()\n\n### Phase 2: Parsing and Symbol Extraction\n\nThe parsing processor extracts code symbols and relationships from source files:\n\n```typescript\nexport const mergeChunkResults = (\n graph: KnowledgeGraph,\n symbolTable: SymbolTableWriter,\n chunkResults: readonly ParseWorkerResult[],\n): WorkerExtractedData => {\n for (const result of chunkResults) {\n for (const node of result.nodes) {\n graph.addNode({\n id: node.id,\n label: node.label as NodeLabel,\n properties: node.properties,\n });\n }\n for (const rel of result.relationships) {\n graph.addRelationship(rel);\n }\n for (const sym of result.symbols) {\n symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type, {\n parameterCount: sym.parameterCount,\n requiredParameterCount: sym.requiredParameterCount,\n parameterTypes: sym.parameterTypes,\n returnType: sym.returnType,\n declaredType: sym.declaredType,\n });\n }\n }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts]()\n\n### Phase 3: Reference Emission\n\nReferences connect code entities across scopes and files:\n\n```typescript\nexport interface EmitStats {\n readonly edgesEmitted: number;\n readonly skippedNoCaller: number; // No caller def resolved\n readonly skippedMissingTarget: number; // Target not in DefIndex\n readonly scopeNodesEmitted: number; // Only if INGESTION_EMIT_SCOPES=1\n readonly scopeEdgesEmitted: number;\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n### Phase 4: Wildcard Import Synthesis\n\nFor languages with whole-module import semantics (Go, Ruby, C/C++, Swift), wildcard imports are expanded into per-symbol bindings:\n\n```typescript\nconst IMPORTABLE_SYMBOL_LABELS = new Set([\n 'Function', 'Class', 'Interface', 'Struct', 'Enum',\n 'Trait', 'TypeAlias', 'Const', 'Static', 'Record',\n 'Union', 'Typedef', 'Macro',\n]);\n\n/** Max synthetic bindings per importing file — prevents memory bloat */\nconst MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts]()\n\nThe synthesis process:\n\n1. Collects IMPORTS edges for wildcard languages\n2. Retrieves exported symbols per file\n3. Creates named import bindings up to the limit\n\n## Language-Specific Processors\n\n### COBOL Processor\n\nCOBOL files undergo specialized processing with unique node types:\n\n```typescript\n// PROGRAM-ID -> Module node\nconst moduleId = generateId('Module', `${filePath}:${extracted.programName}`);\n\n// SECTIONs -> Namespace nodes\n// Paragraphs -> Property nodes\n// Data items -> Property nodes\ngraph.addNode({\n id: moduleId,\n label: 'Module',\n properties: {\n name: extracted.programName,\n filePath,\n language: SupportedLanguages.Cobol,\n isExported: true,\n },\n});\n```\n\nNested programs are linked to their enclosing programs:\n\n```typescript\nconst enclosing = extracted.programs.find(\n (p) => p.startLine < prog.startLine &&\n p.endLine > prog.endLine &&\n p.nestingDepth < prog.nestingDepth,\n);\nconst nestedParent = enclosing\n ? programModuleIds.get(enclosing.name.toUpperCase()) ?? moduleId\n : moduleId;\n```\n\n资料来源：[gitnexus/src/core/ingestion/cobol-processor.ts]()\n\n## Symbol Table Integration\n\nThe Knowledge Graph integrates with a symbol table for cross-reference resolution:\n\n```typescript\nsymbolTable.add(\n filePath,\n symbolName,\n nodeId,\n symbolType,\n {\n parameterCount: number,\n requiredParameterCount: number,\n parameterTypes: string[],\n returnType: string,\n declaredType: string,\n }\n);\n```\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts]()\n\n## Query Patterns\n\nThe graph supports various query patterns for code exploration:\n\n| Pattern | Description |\n|---------|-------------|\n| File dependencies | Traverse IMPORTS edges from a File node |\n| Call graph | Follow CALLS edges from a Function node |\n| Impact analysis | Reverse-traverse USES edges |\n| Circular dependencies | Detect cycles in IMPORTS graph |\n| Component boundaries | Find connected components |\n\n## Web Interface Visualization\n\nThe GitNexus web UI visualizes the Knowledge Graph with:\n\n- **Node size** reflects connection count — larger nodes are depended on by more files\n- **Edges** point from importer to imported\n- **Click interactions** open detail panels showing imports, exports, and reverse dependencies\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `INGESTION_EMIT_SCOPES` | `false` | Enable scope tree nodes in graph |\n\n```typescript\nfunction isScopeEmissionEnabled(): boolean {\n const TRUTHY = new Set(['true', '1', 'yes']);\n const raw = process.env['INGESTION_EMIT_SCOPES'];\n return raw !== undefined && TRUTHY.has(raw.trim().toLowerCase());\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts]()\n\n## Summary\n\nThe Knowledge Graph is a fundamental abstraction in GitNexus that transforms codebase structure into a queryable graph. By modeling files, symbols, and their relationships with confidence scores, it enables:\n\n- Semantic code navigation\n- Dependency analysis\n- AI-powered queries over code structure\n- Documentation generation\n\nThe multi-phase build pipeline progressively enriches the graph from raw file structure through parsing, reference resolution, and language-specific processing to produce a comprehensive semantic model of the codebase.\n\n---\n\n\n\n## Search System\n\n### 相关页面\n\n相关主题：[Indexing Pipeline](#indexing-pipeline), [Knowledge Graph](#knowledge-graph)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/search/hybrid-search.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/hybrid-search.ts)\n- [gitnexus/src/core/search/bm25-index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/bm25-index.ts)\n- [gitnexus/src/core/search/fts-indexes.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/fts-indexes.ts)\n- [gitnexus/src/core/embeddings/embedding-pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/embeddings/embedding-pipeline.ts)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n- [gitnexus-web/src/components/QueryFAB.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/QueryFAB.tsx)\n- [gitnexus-web/src/components/WebGPUFallbackDialog.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/WebGPUFallbackDialog.tsx)\n- [gitnexus-web/src/components/FileTreePanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/FileTreePanel.tsx)\n\n\n# Search System\n\nGitNexus provides a multi-layered search system that enables users to explore code repositories through various search modalities. The system combines traditional keyword-based search with semantic understanding powered by embeddings, supporting navigation by filename, function name, import path, and natural language queries.\n\n## Architecture Overview\n\nThe search system in GitNexus follows a hybrid architecture that leverages both classical information retrieval techniques and modern neural embedding approaches. This dual-strategy design allows users to perform fast exact-match searches while also enabling semantic understanding of code relationships.\n\n```mermaid\ngraph TD\n subgraph \"Search Entry Points\"\n CMD[⌘K / Ctrl K - Global Search]\n FAB[QueryFAB - Natural Language]\n FILE[FileTreePanel Search]\n end\n \n subgraph \"Search Pipeline\"\n HY[Hybrid Search Engine]\n BM[BM25 Index]\n FTS[Full-Text Search Index]\n EMB[Embedding Pipeline]\n end\n \n subgraph \"Result Handling\"\n RES[Results Aggregation]\n HL[Highlight Matching Nodes]\n NAV[Navigate to Graph]\n end\n \n CMD --> HY\n FAB --> HY\n FILE --> BM\n HY --> BM\n HY --> EMB\n HY --> FTS\n BM --> RES\n FTS --> RES\n EMB --> RES\n RES --> HL\n HL --> NAV\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Hybrid Search Engine | `hybrid-search.ts` | Orchestrates search across multiple backends |\n| BM25 Index | `bm25-index.ts` | Classical keyword-based ranking |\n| FTS Indexes | `fts-indexes.ts` | Full-text search infrastructure |\n| Embedding Pipeline | `embedding-pipeline.ts` | Neural embedding generation and similarity |\n\n资料来源：[gitnexus/src/core/search/hybrid-search.ts]() [gitnexus/src/core/search/bm25-index.ts]()\n\n## Search Modalities\n\nGitNexus supports three distinct search modalities that address different user needs:\n\n### 1. Global Quick Search (⌘K / Ctrl+K)\n\nThe primary search interface is accessible via keyboard shortcut `⌘K` on macOS or `Ctrl+K` on Windows/Linux. This modal provides instant access to search nodes across the entire repository.\n\n**Features:**\n\n- Search by filename\n- Search by function name\n- Search by import path\n- Live highlighting of matching nodes in the graph\n- Fuzzy matching support for typo tolerance\n\n**UI Behavior:**\nWhen activated, the search modal overlays the main interface with a centered input field. Results appear in real-time as the user types, with matches highlighted across the knowledge graph visualization. 资料来源：[gitnexus-web/src/components/HelpPanel.tsx]() [gitnexus-web/src/components/FileTreePanel.tsx]()\n\n### 2. Natural Language Query (Nexus AI)\n\nGitNexus integrates an AI-powered search capability that allows users to ask questions in natural language about the codebase. This feature relies on the semantic embedding pipeline.\n\n**Example Queries:**\n\n- \"Which files depend on the auth module?\"\n- \"Find circular dependencies in this repo\"\n- \"What are the most connected components?\"\n- \"Show me all files that import useEffect\"\n\n**Prerequisites:**\nThe repository must be indexed and ready for semantic queries. The system checks for \"Semantic Ready\" status before allowing natural language queries. 资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n### 3. File Tree Search\n\nA dedicated search interface within the file tree panel allows users to filter and locate specific files in the repository structure. This is particularly useful for large codebases with deep directory hierarchies.\n\n**Implementation Details:**\n\n```tsx\n setSearchQuery(e.target.value)}\n className=\"w-full rounded border border-border-subtle bg-elevated py-1.5 pr-3 pl-8 text-xs text-text-primary placeholder:text-text-muted focus:border-accent focus:outline-none\"\n/>\n```\n\n资料来源：[gitnexus-web/src/components/FileTreePanel.tsx]()\n\n## Hybrid Search Engine\n\nThe `HybridSearchEngine` class serves as the central orchestrator for search operations, combining multiple ranking strategies to produce relevant results.\n\n### Search Strategy\n\nThe hybrid approach combines:\n\n1. **BM25 Ranking**: Classical TF-IDF variant optimized for keyword matching\n2. **Full-Text Search (FTS)**: Structured index for structured queries\n3. **Embedding Similarity**: Vector-based semantic matching\n\n### Result Aggregation\n\nResults from multiple search backends are aggregated using a weighted scoring system. The final ranking considers:\n\n- Keyword match score (BM25)\n- Semantic similarity score (embeddings)\n- Graph position relevance\n- Connection count to other nodes\n\n```mermaid\ngraph LR\n A[User Query] --> B[Query Parser]\n B --> C[BM25 Search]\n B --> D[Embedding Query]\n B --> E[FTS Query]\n C --> F[Score Normalization]\n D --> F\n E --> F\n F --> G[Weighted Aggregation]\n G --> H[Result Ranking]\n H --> I[Graph Highlighting]\n```\n\n资料来源：[gitnexus/src/core/search/hybrid-search.ts]()\n\n## BM25 Index\n\nThe BM25 (Best Matching 25) algorithm provides the foundation for keyword-based search ranking in GitNexus. This classical information retrieval technique offers predictable, fast matching for exact and partial term queries.\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| Term Frequency Normalization | Prevents bias toward longer documents |\n| Document Length Scaling | Adaptive ranking based on field length |\n| Saturation Function | Diminishing returns for repeated terms |\n| IDF Weighting | Downweights common terms |\n\n### Index Structure\n\nThe BM25 index maintains:\n\n- **Inverted index**: Maps terms to document positions\n- **Document statistics**: Length, term counts, field weights\n- **IDF table**: Global term importance values\n\n资料来源：[gitnexus/src/core/search/bm25-index.ts]()\n\n## Full-Text Search Indexes\n\nThe FTS (Full-Text Search) subsystem provides structured indexing capabilities for code-specific queries. Unlike BM25 which focuses on term matching, FTS supports phrase queries, proximity searches, and structured field filtering.\n\n### Index Types\n\n1. **Token Index**: Standard word tokenization\n2. **Code Token Index**: Language-aware tokenization preserving syntax\n3. **Symbol Index**: Function/class/variable name index\n\n### Query Capabilities\n\n| Query Type | Syntax | Example |\n|------------|--------|---------|\n| Exact phrase | `\"term1 term2\"` | `\"useState hook\"` |\n| Prefix match | `term*` | `use*` |\n| Field filter | `field:value` | `type:function` |\n| Boolean | `AND / OR / NOT` | `useState AND hook` |\n\n资料来源：[gitnexus/src/core/search/fts-indexes.ts]()\n\n## Embedding Pipeline\n\nThe embedding pipeline transforms code entities into dense vector representations that capture semantic meaning. This enables similarity-based search and natural language understanding.\n\n```mermaid\ngraph TD\n subgraph \"Embedding Pipeline\"\n SRC[Source Code] --> PRE[Preprocessor]\n PRE --> TOK[Tokenization]\n TOK --> ENC[Encoder Model]\n ENC --> VEC[Vector Output]\n end\n \n subgraph \"Storage\"\n VEC --> ANN[Approximate NN Index]\n VEC --> DIM[Dimension Reduction]\n end\n \n subgraph \"Query Flow\"\n Q[Query Text] --> QENC[Query Encoder]\n QENC --> DIST[Distance Calculation]\n ANN --> DIST\n DIST --> TOP[Top-K Results]\n end\n```\n\n### WebGPU Acceleration\n\nEmbedding generation is computationally intensive. GitNexus leverages WebGPU for GPU-accelerated embedding computation when available. If WebGPU is not supported, the system falls back to CPU-based computation with a warning about reduced performance.\n\n**Performance Characteristics:**\n\n- WebGPU: Real-time embedding generation\n- CPU: Batch processing with estimated completion time\n- Memory: Handles large codebases with streaming processing\n\n资料来源：[gitnexus/src/core/embeddings/embedding-pipeline.ts]() [gitnexus-web/src/components/WebGPUFallbackDialog.tsx]()\n\n### Model Configuration\n\nThe embedding pipeline supports configurable embedding models. Users can select from available models in the settings panel or specify custom model identifiers.\n\n**Configuration Options:**\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| Model ID | Embedding model identifier |varies |\n| Dimension | Vector dimensionality | 768 |\n| Batch Size | Documents per batch | 32 |\n| Max Sequence | Maximum input length | 512 |\n\n资料来源：[gitnexus-web/src/components/SettingsPanel.tsx]()\n\n## Query Interface (QueryFAB)\n\nThe QueryFAB (Floating Action Button) component provides persistent access to the natural language query interface. It appears as a floating button in the UI and expands to reveal the query input.\n\n### Features\n\n- Natural language query input\n- Real-time result preview\n- Execution time display\n- Result count indicators\n- Query result highlighting on graph\n- Clear highlight functionality\n\n### Result Display\n\n```tsx\n
\n```\n\n**Result Metrics:**\n\n| Metric | Display | Color |\n|--------|---------|-------|\n| Row count | `{count} rows` | cyan-400 |\n| Highlighted nodes | `{count} highlighted` | cyan-400 |\n| Execution time | `{time}ms` | text-muted |\n\n资料来源：[gitnexus-web/src/components/QueryFAB.tsx]()\n\n## Graph Integration\n\nThe search system is tightly integrated with the knowledge graph visualization. Search results directly influence the graph display:\n\n### Highlighting\n\nMatching nodes are highlighted in the graph with visual indicators:\n\n- **Primary matches**: Full opacity, accent color border\n- **Secondary matches**: Reduced opacity, subtle highlight\n- **Related nodes**: Connected nodes shown with edge highlighting\n\n### Navigation\n\nClicking a search result navigates the graph to focus on the corresponding node, opening the detail panel with:\n\n- Imports and exports\n- Reverse dependencies\n- Node metadata\n- Code preview (where applicable)\n\n### Keyboard Navigation\n\n| Shortcut | Action |\n|----------|--------|\n| `⌘K` / `Ctrl+K` | Open global search |\n| `⌘↵` / `Ctrl+↵` | Execute query |\n| `Escape` | Close search modal |\n| `↑` / `↓` | Navigate results |\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx]()\n\n## Performance Considerations\n\n### Index Build Time\n\nInitial index construction scales with repository size:\n\n| Repository Size | BM25 Index | FTS Index | Embedding Index |\n|-----------------|------------|-----------|-----------------|\n| Small (<100 files) | < 1s | < 2s | ~30s |\n| Medium (100-1000 files) | 2-10s | 5-30s | 2-10 min |\n| Large (>1000 files) | 10-60s | 30-120s | 10+ min |\n\n### Query Latency\n\n| Search Type | Typical Latency |\n|-------------|-----------------|\n| BM25 exact | < 10ms |\n| FTS structured | < 20ms |\n| Semantic (cached) | < 50ms |\n| Semantic (uncached) | 100-500ms |\n\n### Optimization Strategies\n\n1. **Incremental indexing**: Only re-index changed files\n2. **Query caching**: Cache recent semantic query results\n3. **Approximate nearest neighbor**: Trade accuracy for speed in embedding search\n4. **Streaming processing**: Handle large files without memory overflow\n\n## Configuration\n\n### Server Settings\n\nThe search system can be configured through the settings panel:\n\n```typescript\ninterface SearchConfig {\n // BM25 parameters\n k1: number; // Term frequency saturation\n b: number; // Document length normalization\n \n // Embedding settings\n modelId: string; // Embedding model\n device: 'webgpu' | 'cpu';\n \n // FTS settings\n analyzer: 'standard' | 'code';\n minTokenLength: number;\n}\n```\n\n### Ollama Integration\n\nFor self-hosted embedding models, GitNexus supports integration with Ollama:\n\n```typescript\nconst checkOllamaStatus = async (baseUrl: string): Promise<{\n ok: boolean;\n error: string | null;\n}> => {\n const response = await fetch(`${baseUrl}/api/tags`, {\n method: 'GET',\n headers: { 'Content-Type': 'application/json' }\n });\n // ...\n};\n```\n\n资料来源：[gitnexus-web/src/components/SettingsPanel.tsx]()\n\n## Summary\n\nThe GitNexus Search System provides a comprehensive, multi-layered approach to code exploration:\n\n1. **Fast keyword search** via BM25 and FTS indexes for exact matching\n2. **Semantic understanding** through embedding-based similarity\n3. **Natural language queries** powered by AI integration\n4. **Deep graph integration** for visual exploration of search results\n\nThe hybrid architecture ensures that users can find exactly what they're looking for through traditional search while also discovering unexpected relationships through semantic queries.\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：abhigyanpatwari/GitNexus\n\n摘要：发现 38 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error。\n\n## 1. 安装坑 · 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f5cfc2c1ce264d6ab4928a417c66e389 | https://github.com/abhigyanpatwari/GitNexus/issues/1518 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9b5bf45777e4195a5b65bec8eb05125 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36bbed40ba504142b4564a0335aa0b91 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Unable to install GitNexus in Mac\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to install GitNexus in Mac\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbf96b8de8644eb9b2c948cdc732d96c | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f7ed64eb318442009c0c45bd394f15e7 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8498a2d89f154c749aac4e7486f4d1f6 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4b1ddd7fb9104e66b60f9d726b19d298 | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2a4f1ac62124129844a1b1664fecdff | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aff7caa0db4beda6fe67cb86b7ccdd | https://github.com/abhigyanpatwari/GitNexus/issues/1542 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安全/权限坑 · 来源证据：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7e053347355476db324ef874ef9991c | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 失败模式：installation: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：Developers may fail before the first successful local run: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing. Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_1438bc0fa83941fc6074de2c5412cd25 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n## 12. 安装坑 · 失败模式：installation: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：Developers may fail before the first successful local run: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ebb5d6efaf48e8d879678b8a170aacf8 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000, failure_mode_cluster:github_issue | fmev_de5b96783d1677ac281ee6c73055380b | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n## 13. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.12. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ad68a701c98e79e3531d2d8292fd6acb | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.12 | Release Candidate v1.6.6-rc.12\n\n## 14. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.13\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.13\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.13. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_691d71a9a9f7c1da63532e7f4913d598 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.13 | Release Candidate v1.6.6-rc.13\n\n## 15. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.14\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.14\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.14. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_fe26658ac0f7dbfc1389758a44d9f3ac | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.14 | Release Candidate v1.6.6-rc.14\n\n## 16. 安装坑 · 失败模式：installation: Unable to install GitNexus in Mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Unable to install GitNexus in Mac\n- 对用户的影响：Developers may fail before the first successful local run: Unable to install GitNexus in Mac\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Unable to install GitNexus in Mac. Context: Observed when using node, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e8a618cc1ed2879b84e81b16d9f8d995 | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | Unable to install GitNexus in Mac\n\n## 17. 安装坑 · 失败模式：installation: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：Developers may fail before the first successful local run: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427. Context: Observed when using node, python, windows, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9ec12d39ffa06f5c08b0ad85182bddd7 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n\n## 18. 安装坑 · 失败模式：installation: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：Developers may fail before the first successful local run: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%). Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_122d12d9d7145c261627cb5c59179ac1 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%), failure_mode_cluster:github_issue | fmev_6c9acc8d3c792d067bb848a0833634a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n## 19. 安装坑 · 失败模式：installation: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 re...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：Developers may fail before the first successful local run: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_623b7791e3c0dc9791ade56a9bde72a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n\n## 20. 安装坑 · 失败模式：installation: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist acro...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_006addf62ce5971f44bd372e453a3fe2 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d73fddaa3691a761b14cb569d5acbb58 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d4e580f0f3653876a2e755ee3ca34259 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n## 21. 安装坑 · 失败模式：installation: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：Developers may fail before the first successful local run: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression). Context: Observed when using node, python, docker, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_78c629867f92802da91b458f6e7bc14f | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n\n## 22. 安装坑 · 来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26a9d2c26b004c6ba8a99533ff1d6ac5 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 安装坑 · 来源证据：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash)…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec175ee0cb4d4d31bae2f29144c7d619 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 24. 安装坑 · 来源证据：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c4087a57d5e4c949662a9721355ac8f | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. 配置坑 · 失败模式：configuration: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?. Context: Observed when using node, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_53da1aec043bc339e2d1e3db40239192 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n\n## 26. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | README/documentation is current enough for a first validation pass.\n\n## 27. 运行坑 · 失败模式：runtime: GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: GitNexus Enterprise for open source\n- 对用户的影响：Developers may hit a documented source-backed failure mode: GitNexus Enterprise for open source\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Enterprise for open source. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f47b7a16378d6157c47cb32462d648cd | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source, failure_mode_cluster:github_issue | fmev_b0d64cb50e22bb1f6f82577f2f9468ed | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source\n\n## 28. 运行坑 · 失败模式：runtime: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record t...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.. Context: Observed when using macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_83c386b31413aad9103fe675ded0d557 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type., failure_mode_cluster:github_issue | fmev_ef20949c8067cc8c69adefcfe3cac1b3 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n## 29. 运行坑 · 失败模式：runtime: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d05c00b4ab6372cd518729b619d7a572 | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n## 30. 运行坑 · 失败模式：runtime: cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: cpp SFINAE: expand type_traits predicate registry (Tier A). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_356daa9356830c10f89e67ea3f087c37 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n## 31. 运行坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_761efc4dc902430dbff83585f209b270 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. 运行坑 · 来源证据：cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0576badcd5a477bb2b988a8a0afa3d6 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. 维护坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dd127cfb66644c49407761777f40c18 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | last_activity_observed missing\n\n## 35. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 36. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 37. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | issue_or_pr_quality=unknown\n\n## 38. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：abhigyanpatwari/GitNexus\n\n摘要：发现 38 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error。\n\n## 1. 安装坑 · 来源证据：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: Local path analysis not working in Docker version - always throws \"path must be an absolute path\" error\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f5cfc2c1ce264d6ab4928a417c66e389 | https://github.com/abhigyanpatwari/GitNexus/issues/1518 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to o…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9b5bf45777e4195a5b65bec8eb05125 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_36bbed40ba504142b4564a0335aa0b91 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Unable to install GitNexus in Mac\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Unable to install GitNexus in Mac\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fbf96b8de8644eb9b2c948cdc732d96c | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f7ed64eb318442009c0c45bd394f15e7 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8498a2d89f154c749aac4e7486f4d1f6 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 安装坑 · 来源证据：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension r…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4b1ddd7fb9104e66b60f9d726b19d298 | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 配置坑 · 来源证据：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a2a4f1ac62124129844a1b1664fecdff | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 配置坑 · 来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aff7caa0db4beda6fe67cb86b7ccdd | https://github.com/abhigyanpatwari/GitNexus/issues/1542 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安全/权限坑 · 来源证据：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present bina…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b7e053347355476db324ef874ef9991c | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 失败模式：installation: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：Developers may fail before the first successful local run: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing. Context: Observed when using windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_1438bc0fa83941fc6074de2c5412cd25 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n## 12. 安装坑 · 失败模式：installation: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 对用户的影响：Developers may fail before the first successful local run: MCP error with Claude: Failed to reconnect to gitnexus: -32000\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: MCP error with Claude: Failed to reconnect to gitnexus: -32000. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_ebb5d6efaf48e8d879678b8a170aacf8 | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000, failure_mode_cluster:github_issue | fmev_de5b96783d1677ac281ee6c73055380b | https://github.com/abhigyanpatwari/GitNexus/issues/1683 | MCP error with Claude: Failed to reconnect to gitnexus: -32000\n\n## 13. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.12\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.12\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.12. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_ad68a701c98e79e3531d2d8292fd6acb | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.12 | Release Candidate v1.6.6-rc.12\n\n## 14. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.13\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.13\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.13. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_691d71a9a9f7c1da63532e7f4913d598 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.13 | Release Candidate v1.6.6-rc.13\n\n## 15. 安装坑 · 失败模式：installation: Release Candidate v1.6.6-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Release Candidate v1.6.6-rc.14\n- 对用户的影响：Upgrade or migration may change expected behavior: Release Candidate v1.6.6-rc.14\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Release Candidate v1.6.6-rc.14. Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_release | fmev_fe26658ac0f7dbfc1389758a44d9f3ac | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.6-rc.14 | Release Candidate v1.6.6-rc.14\n\n## 16. 安装坑 · 失败模式：installation: Unable to install GitNexus in Mac\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Unable to install GitNexus in Mac\n- 对用户的影响：Developers may fail before the first successful local run: Unable to install GitNexus in Mac\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Unable to install GitNexus in Mac. Context: Observed when using node, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_e8a618cc1ed2879b84e81b16d9f8d995 | https://github.com/abhigyanpatwari/GitNexus/issues/1164 | Unable to install GitNexus in Mac\n\n## 17. 安装坑 · 失败模式：installation: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：Developers may fail before the first successful local run: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427. Context: Observed when using node, python, windows, linux\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_9ec12d39ffa06f5c08b0ad85182bddd7 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n\n## 18. 安装坑 · 失败模式：installation: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 对用户的影响：Developers may fail before the first successful local run: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%). Context: Observed when using node, python, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_122d12d9d7145c261627cb5c59179ac1 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%), failure_mode_cluster:github_issue | fmev_6c9acc8d3c792d067bb848a0833634a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1674 | Windows + Node v24.14.0: gitnexus@1.6.3 analyze crashes at LadybugDB persist (60%)\n\n## 19. 安装坑 · 失败模式：installation: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 re...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 对用户的影响：Developers may fail before the first successful local run: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary). Context: Observed when using node, windows\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_623b7791e3c0dc9791ade56a9bde72a3 | https://github.com/abhigyanpatwari/GitNexus/issues/1690 | Windows: FTS skip-guard too aggressive when extension is locally installed (BM25 returns 0 results despite present binary)\n\n## 20. 安装坑 · 失败模式：installation: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist acro...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 对用户的影响：Developers may fail before the first successful local run: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules. Context: Observed when using python\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_006addf62ce5971f44bd372e453a3fe2 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d73fddaa3691a761b14cb569d5acbb58 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules, failure_mode_cluster:github_issue | fmev_d4e580f0f3653876a2e755ee3ca34259 | https://github.com/abhigyanpatwari/GitNexus/issues/1680 | [Bug] Incorrect edge relationships when duplicate package, class, and method names exist across different modules\n\n## 21. 安装坑 · 失败模式：installation: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 对用户的影响：Developers may fail before the first successful local run: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression). Context: Observed when using node, python, docker, macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_78c629867f92802da91b458f6e7bc14f | https://github.com/abhigyanpatwari/GitNexus/issues/1472 | bug: analyze --embeddings crashes on ARM64 with UNREACHABLE_CODE in wal_record.cpp (ladybugdb 0.16.1 VECTOR extension regression)\n\n## 22. 安装坑 · 来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_26a9d2c26b004c6ba8a99533ff1d6ac5 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 23. 安装坑 · 来源证据：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash)…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：WSL2 + 1.6.4-rc.88 + ladybug 0.16.1: list/status/--version persistently SIGSEGV (~2.5GB dumps each, exit 0 masks crash) — related to #1427\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ec175ee0cb4d4d31bae2f29144c7d619 | https://github.com/abhigyanpatwari/GitNexus/issues/1431 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 24. 安装坑 · 来源证据：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c4087a57d5e4c949662a9721355ac8f | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 25. 配置坑 · 失败模式：configuration: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?. Context: Observed when using node, docker\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_53da1aec043bc339e2d1e3db40239192 | https://github.com/abhigyanpatwari/GitNexus/issues/1444 | GitNexus Embedding performance on large Java projects (900k+ edges, 8k+ files): Is a 10-hour runtime expected? How to optimize to within 30 minutes?\n\n## 26. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | README/documentation is current enough for a first validation pass.\n\n## 27. 运行坑 · 失败模式：runtime: GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: GitNexus Enterprise for open source\n- 对用户的影响：Developers may hit a documented source-backed failure mode: GitNexus Enterprise for open source\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: GitNexus Enterprise for open source. Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_f47b7a16378d6157c47cb32462d648cd | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source, failure_mode_cluster:github_issue | fmev_b0d64cb50e22bb1f6f82577f2f9468ed | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | GitNexus Enterprise for open source\n\n## 28. 运行坑 · 失败模式：runtime: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record t...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 对用户的影响：Developers may hit a documented source-backed failure mode: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.. Context: Observed when using macos\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_83c386b31413aad9103fe675ded0d557 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type., failure_mode_cluster:github_issue | fmev_ef20949c8067cc8c69adefcfe3cac1b3 | https://github.com/abhigyanpatwari/GitNexus/issues/1611 | Schema creation warning: Runtime exception: Corrupted wal file. Read out invalid WAL record type.\n\n## 29. 运行坑 · 失败模式：runtime: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_d05c00b4ab6372cd518729b619d7a572 | https://github.com/abhigyanpatwari/GitNexus/issues/1684 | analyze hangs or stalls on microsoft/TypeScript repo root (raised file-size limits)\n\n## 30. 运行坑 · 失败模式：runtime: cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this runtime risk before relying on the project: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：Developers may hit a documented source-backed failure mode: cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: cpp SFINAE: expand type_traits predicate registry (Tier A). Context: Source discussion did not expose a precise runtime context.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_356daa9356830c10f89e67ea3f087c37 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n## 31. 运行坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_761efc4dc902430dbff83585f209b270 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 32. 运行坑 · 来源证据：cpp SFINAE: expand type_traits predicate registry (Tier A)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：cpp SFINAE: expand type_traits predicate registry (Tier A)\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0576badcd5a477bb2b988a8a0afa3d6 | https://github.com/abhigyanpatwari/GitNexus/issues/1629 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 33. 维护坑 · 来源证据：GitNexus Enterprise for open source\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：GitNexus Enterprise for open source\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8dd127cfb66644c49407761777f40c18 | https://github.com/abhigyanpatwari/GitNexus/issues/1685 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 34. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | last_activity_observed missing\n\n## 35. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 36. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | no_demo; severity=medium\n\n## 37. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | issue_or_pr_quality=unknown\n\n## 38. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# GitNexus - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for abhigyanpatwari/GitNexus.\n\nProject:\n- Name: GitNexus\n- Repository: https://github.com/abhigyanpatwari/GitNexus\n- Summary: GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: GitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a GitHub repo or ZIP file, and get an interactive knowledge graph wit a built in Graph RAG Agent. Perfect for code exploration\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to GitNexus. Produce one small intermediate artifact and wait for confirmation.\n2. quick-start: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. mcp-integration: MCP Integration. Produce one small intermediate artifact and wait for confirmation.\n5. indexing-pipeline: Indexing Pipeline. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/abhigyanpatwari/GitNexus\n- https://github.com/abhigyanpatwari/GitNexus#readme\n- gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-debugging/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-exploring/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-guide/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-impact-analysis/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-pr-review/SKILL.md\n- gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md\n- gitnexus-cursor-integration/skills/gitnexus-debugging/SKILL.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：abhigyanpatwari/GitNexus\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g gitnexus\n```\n\n来源：https://github.com/abhigyanpatwari/GitNexus#readme\n\n## 来源\n\n- repo: https://github.com/abhigyanpatwari/GitNexus\n- docs: https://github.com/abhigyanpatwari/GitNexus#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_728adcfc41dd4b1bbe14dc63f4032755"
}