{ "canonical_name": "abhigyanpatwari/GitNexus", "compilation_id": "pack_bd7d9da12fd749d48e623d53e8540186", "created_at": "2026-05-13T17:14:20.138823+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": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "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 社区证据显示该项目存在一个安装相关的待验证问题：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 社区证据显示该项目存在一个配置相关的待验证问题：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 社区证据显示该项目存在一个安装相关的待验证问题：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_26a9d2c26b004c6ba8a99533ff1d6ac5 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.12", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_3ab63b9f59a54481abd184c162662990 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.12 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.12", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.13", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_7923c9bda9874ce9870d5c684c3087ff | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.13", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.14", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_ba78a9abede8434fa010e8bee0ad539d | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.14", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.15", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_fe507017f17c4775b3d5a4e73b724a3a | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.15", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.16", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_9f1c7b44ec854520814354c46f0d1889 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.16", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.17", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_06c1411b76fb4e07998249f900e31b02 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.17", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.18", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_39945335ad1940e888d89a6cf3971331 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.18", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.19", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_5d3a217ad4944b9a8b541abf5b857840 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.19", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.8", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_92b8f92f6417448abe698e2d08bba803 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.8 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.8", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.9", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_a29c0c1477a8488d8f31bc15d51d1df9 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Release Candidate v1.6.5-rc.9", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_44741975e7b44839afb3b3379760d58f | https://github.com/abhigyanpatwari/GitNexus/issues/1541 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 22 个潜在踩坑项，其中 3 个为 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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 GitNexus 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-mcp-architecture：MCP 架构与集成。围绕“MCP 架构与集成”模拟一次用户任务，不展示安装或运行结果。\n5. page-knowledge-graph：知识图谱构建。围绕“知识图谱构建”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-mcp-architecture\n输入：用户提供的“MCP 架构与集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-knowledge-graph\n输入：用户提供的“知识图谱构建”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-mcp-architecture：Step 4 必须围绕“MCP 架构与集成”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-knowledge-graph：Step 5 必须围绕“知识图谱构建”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\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- gitnexus-cursor-integration/skills/gitnexus-exploring/SKILL.md\n- gitnexus-cursor-integration/skills/gitnexus-impact-analysis/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 GitNexus 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: 1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing（https://github.com/abhigyanpatwari/GitNexus/issues/1440）；github/github_issue: analyze: generated CLAUDE.md examples omit repo parameter in multi-repo （https://github.com/abhigyanpatwari/GitNexus/issues/1542）；github/github_issue: Bug: Local path analysis not working in Docker version - always throws \"（https://github.com/abhigyanpatwari/GitNexus/issues/1518）；github/github_issue: 分析完成之后，会出现agent在使用gitnexus，提示落后commit版本（https://github.com/abhigyanpatwari/GitNexus/issues/1541）；github/github_issue: Unable to install GitNexus in Mac（https://github.com/abhigyanpatwari/GitNexus/issues/1164）；github/github_release: Release Candidate v1.6.5-rc.19（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19）；github/github_release: Release Candidate v1.6.5-rc.18（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18）；github/github_release: Release Candidate v1.6.5-rc.17（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17）；github/github_release: Release Candidate v1.6.5-rc.16（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16）；github/github_release: Release Candidate v1.6.5-rc.15（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15）；github/github_release: Release Candidate v1.6.5-rc.14（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14）；github/github_release: Release Candidate v1.6.5-rc.13（https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing", "url": "https://github.com/abhigyanpatwari/GitNexus/issues/1440" }, { "kind": "github_issue", "source": "github", "title": "analyze: generated CLAUDE.md examples omit repo parameter in multi-repo ", "url": "https://github.com/abhigyanpatwari/GitNexus/issues/1542" }, { "kind": "github_issue", "source": "github", "title": "Bug: Local path analysis not working in Docker version - always throws \"", "url": "https://github.com/abhigyanpatwari/GitNexus/issues/1518" }, { "kind": "github_issue", "source": "github", "title": "分析完成之后，会出现agent在使用gitnexus，提示落后commit版本", "url": "https://github.com/abhigyanpatwari/GitNexus/issues/1541" }, { "kind": "github_issue", "source": "github", "title": "Unable to install GitNexus in Mac", "url": "https://github.com/abhigyanpatwari/GitNexus/issues/1164" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.19", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.18", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.17", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.16", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.15", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.14", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14" }, { "kind": "github_release", "source": "github", "title": "Release Candidate v1.6.5-rc.13", "url": "https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13" } ], "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-13 17:02:08 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [MCP 架构与集成](#page-mcp-architecture)\n- [知识图谱构建](#page-knowledge-graph)\n- [索引管道](#page-indexing-pipeline)\n- [CLI 命令详解](#page-cli-commands)\n- [多语言支持](#page-multilanguage-support)\n- [数据存储](#page-data-storage)\n- [Web UI 组件](#page-web-components)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)\n- [ARCHITECTURE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/ARCHITECTURE.md)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)\n
\n\n# 项目介绍\n\nGitNexus 是一个基于代码语义分析的知识图谱引擎，用于可视化、分析和理解代码仓库的结构与依赖关系。该项目由前端 Web 界面（gitnexus-web）和后端核心引擎（gitnexus）两部分组成，采用 TypeScript/React 作为前端技术栈，Node.js 作为后端运行时。\n\n## 核心定位\n\nGitNexus 的核心目标是解决大型代码仓库中**依赖关系难以追踪**的问题。通过 AST（抽象语法树）解析和语义理解，它能够自动构建代码元素之间的关联图谱，帮助开发者快速理解代码结构、追踪影响范围、发现潜在的架构问题。\n\n> **关键特性**：支持多语言解析、智能导入解析、继承关系追踪、gRPC/HTTP 模式识别，并集成了 LLM（大型语言模型）能力，支持自然语言查询代码库。\n\n资料来源：[README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)()\n\n## 系统架构\n\nGitNexus 采用分层架构设计，核心模块分布在以下几个主要目录中：\n\n| 模块路径 | 职责描述 |\n|---------|---------|\n| `src/core/ingestion/` | 代码解析、AST 处理、依赖图谱构建 |\n| `src/core/group/` | 语言模式提取器、管道编排 |\n| `src/storage/` | Git 仓库操作、文件存储 |\n| `gitnexus-web/src/` | React 前端界面组件 |\n| `gitnexus-web/src/core/llm/` | LLM 集成与设置管理 |\n\n### 架构分层图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (gitnexus-web)\"]\n UI[React 组件]\n HOOKS[状态管理 Hooks]\n LLM_SVC[LLM 设置服务]\n end\n \n subgraph 核心引擎[\"核心引擎 (gitnexus)\"]\n INGEST[ingestion
代码摄取]\n GROUP[group
模式分组]\n STORAGE[storage
存储层]\n end\n \n subgraph 解析层[\"解析层\"]\n PARSER[Parser 加载器]\n LANG[Language 插件]\n TREE_SITTER[Tree-sitter]\n end\n \n UI --> HOOKS\n HOOKS --> LLM_SVC\n LLM_SVC --> INGEST\n INGEST --> PARSER\n PARSER --> TREE_SITTER\n GROUP --> LANG\n INGEST --> STORAGE\n STORAGE --> GIT[Git 仓库]\n```\n\n资料来源：[ARCHITECTURE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/ARCHITECTURE.md)()\n\n## 数据摄取管道\n\n数据摄取是 GitNexus 的核心处理流程，分为多个阶段执行：\n\n### 摄取阶段概览\n\n| 阶段 | 名称 | 核心功能 |\n|-----|------|---------|\n| Phase 1 | 文件扫描 | 递归扫描仓库文件，过滤非代码文件 |\n| Phase 2 | AST 解析 | 使用 tree-sitter 解析代码生成语法树 |\n| Phase 3 | 语义建模 | 构建符号表、作用域索引 |\n| Phase 4 | 依赖分析 | 追踪 imports、calls、inherits 关系 |\n| Phase 5 | 关系发射 | 将分析结果写入知识图谱 |\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)()\n\n### 管道处理流程\n\n```mermaid\nflowchart TD\n START[代码仓库] --> SCAN[文件扫描]\n SCAN --> LANG[语言检测]\n LANG --> LOAD[加载 Parser]\n LOAD --> PARSE[AST 解析]\n PARSE --> EXTRACT[模式提取]\n EXTRACT --> SCOPE[作用域解析]\n SCOPE --> HERITAGE[继承关系处理]\n HERITAGE --> EMIT[发射到图数据库]\n EMIT --> COMPLETE[完成]\n \n subgraph 模式识别[\"模式识别 (group)\"]\n GRPC[Grpc 模式]\n HTTP[Http 模式]\n PYTHON[Python 导入]\n end\n \n EXTRACT --> GRPC\n EXTRACT --> HTTP\n EXTRACT --> PYTHON\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)()\n\n## 核心功能模块\n\n### 1. 代码依赖图谱\n\nGitNexus 将代码仓库解析为节点（Nodes）和边（Edges）的图结构：\n\n- **节点**：代表代码元素（类、函数、接口、包等）\n- **边**：代表依赖关系（导入、调用、继承、访问）\n\n> **节点大小含义**：节点的大小反映了其被依赖的数量——被更多文件依赖的节点会显示得更大。\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)()\n\n### 2. 多语言支持框架\n\nGitNexus 通过可插拔的模式提取器支持多种编程语言：\n\n| 语言 | 支持模式 | 模式文件 |\n|------|---------|---------|\n| JavaScript | gRPC 客户端、HTTP 调用 | `grpc-patterns/node.ts` |\n| TypeScript | gRPC 方法、服务定义 | `grpc-patterns/node.ts` |\n| PHP | Laravel 路由、HTTP Facade、Guzzle | `http-patterns/php.ts` |\n| Python | 导入解析、模块解析 | `languages/python/import-target.ts` |\n\n#### gRPC 模式识别\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资料来源：[gitnexus/src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/grpc-patterns/node.ts)()\n\n### 3. 继承关系追踪\n\n继承关系处理（heritage-processor）是理解面向对象代码结构的关键组件：\n\n- 支持 `implements` 和 `extends` 两种继承类型\n- 构建父类/接口到实现类的映射\n- 支持多种语言的继承语义策略\n\n```typescript\nif (h.kind === 'implements') {\n isImpl = true;\n} else if (h.kind === 'extends') {\n const lang = getLanguageFromFilename(h.filePath);\n if (lang) {\n const strategy = getHeritageStrategy?.(lang) ?? DEFAULT_HERITAGE_STRATEGY;\n const { type } = resolveExtendsType(h.parentName, h.filePath, ctx, strategy);\n isImpl = type === 'IMPLEMENTS';\n }\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/model/heritage-map.ts)()\n\n### 4. 引用关系发射\n\n引用关系模块将解析结果转换为图数据库中的边：\n\n| 引用类型 | 图关系类型 | 说明 |\n|---------|-----------|------|\n| `call` | `CALLS` | 函数调用 |\n| `read` / `write` | `ACCESSES` | 属性访问 |\n| `type-reference` | `USES` | 类型引用 |\n| `import-use` | `USES` | 导入使用 |\n| `inherits` | `INHERITS` | 继承关系 |\n\n每个发射的边都携带 `confidence`（置信度）和 `evidence`（证据）属性，用于追溯分析结果的可靠性。\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)()\n\n### 5. Python 导入解析\n\nPython 的导入解析采用多级匹配策略：\n\n```mermaid\nflowchart TD\n PATH[导入路径] --> EXACT{精确匹配}\n EXACT -->|成功| RESULT1[返回精确路径]\n EXACT -->|失败| ANCESTOR{祖先目录匹配}\n ANCESTOR -->|成功| RESULT2[返回祖先路径]\n ANCESTOR -->|失败| SUFFIX{后缀匹配}\n SUFFIX -->|成功| RESULT3[返回后缀路径]\n SUFFIX -->|失败| NULL[返回 null]\n```\n\n**匹配优先级**：\n1. 工作区根目录直接命中\n2. 向上遍历祖先目录查找\n3. 后缀匹配（确定性：路径段最少优先）\n\n资料来源：[gitnexus/src/core/ingestion/languages/python/import-target.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/languages/python/import-target.ts)()\n\n### 6. LLM 集成\n\nGitNexus 支持多种 LLM 提供商配置：\n\n| 提供商 | 配置类型 | API 类型 |\n|-------|---------|---------|\n| OpenAI | `OpenAIConfig` | REST API |\n| Azure OpenAI | `AzureOpenAIConfig` | Azure 端点 |\n| Gemini | `GeminiConfig` | Google API |\n| Anthropic | `AnthropicConfig` | Anthropic API |\n| Ollama | `OllamaConfig` | 本地模型 |\n| OpenRouter | `OpenRouterConfig` | 聚合网关 |\n| MiniMax | `MiniMaxConfig` | MiniMax API |\n| GLM | `GLMConfig` | 智谱 API |\n\n用户可通过设置面板配置 LLM，并使用自然语言查询代码库。\n\n资料来源：[gitnexus-web/src/core/llm/settings-service.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/core/llm/settings-service.ts)()\n\n## 前端组件架构\n\n前端采用 React + TypeScript 构建，主要组件结构如下：\n\n| 组件 | 功能 |\n|------|------|\n| `Header.tsx` | 导航栏、仓库切换 |\n| `HelpPanel.tsx` | 帮助面板、图例说明 |\n| `StatusBar.tsx` | 状态栏、进度显示 |\n| `RepoAnalyzer.tsx` | 仓库分析表单 |\n| `DropZone.tsx` | 文件拖拽上传 |\n| `OnboardingGuide.tsx` | 首次使用引导 |\n| `SettingsPanel.tsx` | LLM 配置面板 |\n\n### 状态管理\n\n前端使用 React Hooks 进行状态管理，核心状态包括：\n\n- `highlightedNodeIds`：高亮节点集合\n- `aiCitationHighlightedNodeIds`：AI 引用高亮\n- `blastRadiusNodeIds`：影响半径节点\n- `progress`：管道处理进度\n- `availableRepos`：可用仓库列表\n- `serverBaseUrl`：服务器连接地址\n\n资料来源：[gitnexus-web/src/hooks/useAppState.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/hooks/useAppState.tsx)()\n\n## Git 集成\n\nGitNexus 提供 Git 仓库操作能力：\n\n### 主要功能\n\n| 函数 | 功能描述 |\n|------|---------|\n| `hasGitDir()` | 检查目录是否为 Git 仓库 |\n| `getRemoteOriginUrl()` | 获取远程仓库 URL |\n| `sanitizeRepoName()` | 清理仓库名称，防止注入攻击 |\n\n> Git 远程 URL 用于推断仓库名称，特别是在 monorepo 或 git worktree 场景下。\n\n资料来源：[gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)()\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Web as 前端界面\n participant Server as 后端服务\n participant Parser as 解析引擎\n participant Graph as 图数据库\n \n User->>Web: 选择仓库\n Web->>Server: 发送分析请求\n Server->>Parser: 启动摄取管道\n Parser->>Graph: 解析并写入节点/边\n Graph-->>Server: 返回分析结果\n Server-->>Web: 返回图数据\n Web->>Web: 渲染交互图谱\n \n User->>Web: 点击节点/搜索/提问\n Web->>Server: 查询请求\n Server->>Graph: Cypher 查询\n Graph-->>Server: 查询结果\n Server-->>Web: 返回结果\n```\n\n## 扩展机制\n\nGitNexus 采用插件化设计，新增语言支持只需：\n\n1. 在 `src/core/group/extractors/*-patterns/` 目录下创建模式文件\n2. 在对应 `index.ts` 中注册新语言\n3. 无需修改编排器代码\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)()\n\n## 快速开始\n\n### 前置要求\n\n- Node.js 16+\n- npm 或 pnpm 包管理器\n\n### 安装与启动\n\n```bash\n# 全局安装\nnpm install -g gitnexus && gitnexus serve\n\n# 本地开发\ncd gitnexus\nnpm install\nnpm run dev\n```\n\n前端会自动检测服务器启动，无需手动刷新页面。\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)()\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|---------|\n| 前端框架 | React 18 + TypeScript |\n| 样式方案 | Tailwind CSS |\n| 状态管理 | React Hooks |\n| 后端运行时 | Node.js |\n| AST 解析器 | tree-sitter |\n| 图数据库 | Neo4j (Cypher) |\n| 编程语言 | TypeScript |\n\nGitNexus 通过将静态代码分析与交互式可视化相结合，为开发者提供了一个强大的代码理解工具，特别适用于大型代码仓库的架构分析、依赖追踪和代码审查场景。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [CLI 命令详解](#page-cli-commands), [MCP 架构与集成](#page-mcp-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [gitnexus/src/cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n
\n\n# 快速开始\n\nGitNexus 是一个代码知识图谱构建工具，能够自动分析 GitHub 仓库，解析代码结构并生成交互式依赖关系图。本页介绍如何快速上手使用 GitNexus，包括环境配置、项目分析和图谱查看的完整流程。\n\n## 环境要求\n\n### 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18.0.0+ | 必须安装，用于运行后端服务 |\n| npm | 8.0.0+ | 用于包管理 |\n| Git | 2.30.0+ | 用于仓库克隆操作 |\n\n### 安装前置条件\n\nGitNexus 后端服务需要 Node.js 运行环境。前端界面通过浏览器访问，无需额外安装。\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## 安装方式\n\nGitNexus 提供两种安装方式，可根据使用场景选择。\n\n### 全局安装（推荐）\n\n适用于频繁使用 GitNexus 的开发者，一次安装后可在任意目录使用：\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### 本地安装\n\n适用于特定项目或团队共享配置的场景：\n\n```bash\nnpm install gitnexus\nnpx gitnexus serve\n```\n\n## 启动流程\n\n### 整体流程\n\n```mermaid\nflowchart TD\n A[安装 GitNexus] --> B[启动后端服务]\n B --> C{服务状态检测}\n C -->|成功| D[打开浏览器]\n C -->|失败| E[显示错误信息]\n D --> F[粘贴 GitHub 仓库 URL]\n F --> G[克隆并解析代码]\n G --> H[生成知识图谱]\n H --> I[交互式查看]\n```\n\n### 步骤详解\n\n#### 步骤一：安装与启动\n\n执行安装命令后，终端会显示服务启动状态。GitNexus 后端服务默认在本地端口运行，等待前端连接。\n\n> 资料来源：[cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n\n#### 步骤二：等待服务器启动\n\n启动过程中，界面会显示轮询进度条，实时反馈连接状态。系统会自动检测后端服务是否就绪，无需手动刷新页面。\n\n```mermaid\nstateDiagram-v2\n [*] --> 探测中: 启动后端\n 探测中 --> 服务就绪: 检测成功\n 探测中 --> 探测中: 继续轮询\n 服务就绪 --> [*]: 自动跳转\n```\n\n> 资料来源：[DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n#### 步骤三：自动连接\n\n服务就绪后，页面自动跳转到主界面。此时用户可以粘贴 GitHub 仓库 URL 开始分析。\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## 仓库分析\n\n### 输入仓库 URL\n\n在分析界面的输入框中粘贴公开的 GitHub 仓库地址。GitNexus 支持以下格式：\n\n| 格式类型 | 示例 |\n|----------|------|\n| HTTPS | `https://github.com/user/repo` |\n| 简写 | `user/repo` |\n\n> 资料来源：[AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n### 自动处理流程\n\n```mermaid\nflowchart LR\n A[输入 URL] --> B[克隆仓库]\n B --> C[解析代码 AST]\n C --> D[提取符号关系]\n D --> E[构建图谱数据]\n E --> F[渲染交互界面]\n```\n\n系统会自动完成以下操作：\n\n1. **克隆仓库**：通过 Git 获取完整代码库\n2. **代码解析**：使用 tree-sitter 解析多语言源码\n3. **符号提取**：识别函数、类、接口等定义\n4. **依赖分析**：构建导入导出关系图\n5. **图谱生成**：生成可交互的可视化图谱\n\n> 资料来源：[git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n### 数据隐私\n\n| 特性 | 说明 |\n|------|------|\n| 本地处理 | 所有代码在本地解析，不上传至云端 |\n| 仅支持公开仓库 | 出于安全考虑，仅支持公开的 GitHub 仓库 |\n| 自动清理 | 可随时清除本地缓存的仓库数据 |\n\n> 资料来源：[AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n## 仓库管理\n\n### 切换仓库\n\n分析完成后，仓库会自动添加到仓库列表中。点击下拉菜单可以：\n\n- 查看当前所有已分析的仓库\n- 快速切换到其他已分析仓库\n- 对仓库执行重新分析\n\n> 资料来源：[Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n### 重新分析\n\n对于已分析的仓库，可以点击重新分析按钮更新图谱。重新分析会重新克隆最新代码并更新依赖关系。\n\n> 资料来源：[Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n## 界面状态\n\n### 阶段状态机\n\nGitNexus 前端界面存在以下状态：\n\n| 状态 | 说明 | 触发条件 |\n|------|------|----------|\n| onboarding | 初始引导状态 | 首次打开或无已分析仓库 |\n| analyze | 分析输入状态 | 服务器运行中但无仓库索引 |\n| landing | 仓库列表状态 | 服务运行且有已分析仓库 |\n| success | 分析成功状态 | 仓库分析完成 |\n| loading | 加载状态 | 正在克隆或解析代码 |\n\n> 资料来源：[DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n### 状态转换图\n\n```mermaid\nstateDiagram-v2\n [*] --> onboarding: 首次访问\n onboarding --> analyze: 完成引导\n analyze --> loading: 开始分析\n loading --> success: 分析完成\n loading --> landing: 分析取消\n success --> landing: 切换视图\n landing --> analyze: 清除仓库\n landing --> loading: 重新分析\n```\n\n## 图谱交互\n\n### 节点信息\n\n- **节点大小**：反映依赖该节点的文件数量，越大表示被依赖越多\n- **节点颜色**：区分不同类型的符号（函数、类、接口等）\n- **边的方向**：从导入方指向被导入方\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| 点击节点 | 打开详情面板，显示导入、导出和反向依赖 |\n| 缩放 | 使用鼠标滚轮调整视图大小 |\n| 拖拽 | 按住鼠标拖动画布移动 |\n\n> 资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n## 命令行接口\n\nGitNexus 提供完整的 CLI 命令集：\n\n| 命令 | 功能 |\n|------|------|\n| `gitnexus serve` | 启动后端服务 |\n| `gitnexus analyze ` | 分析指定仓库 |\n| `gitnexus wiki` | 生成文档页面 |\n| `gitnexus query ` | 查询知识图谱 |\n| `gitnexus publish [path]` | 发布到注册表 |\n\n> 资料来源：[cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n\n## 常见问题\n\n### Q: 服务启动失败\n\n确保 Node.js 版本符合要求（18.0.0+），并检查端口是否被占用。\n\n### Q: 无法克隆仓库\n\n确认仓库为公开状态，且网络连接正常。\n\n### Q: 图谱加载缓慢\n\n大型仓库解析需要较长时间，建议耐心等待或使用浏览器开发者工具查看进度。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [知识图谱构建](#page-knowledge-graph), [索引管道](#page-indexing-pipeline), [MCP 架构与集成](#page-mcp-architecture)\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/graph/graph.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/graph.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/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/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-map.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/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.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/ingestion/languages/c-cpp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/c-cpp.ts)\n
\n\n# 系统架构\n\n## 1. 概述\n\nGitNexus 是一个用于代码库的交互式图谱探索工具，能够将代码库中的每个文件、函数和导入关系转换为可探索、可查询、可视化导航的节点。该系统通过静态代码分析和图谱构建技术，帮助开发者理解代码结构、依赖关系和组件间的交互模式。 资料来源：[gitnexus/src/core/group/PIPELINE.md:1-10]()\n\n### 1.1 核心设计目标\n\n| 设计目标 | 描述 |\n|---------|------|\n| 语义理解 | 不仅理解文件名，还理解代码结构和关系 |\n| 可视化探索 | 通过图谱形式直观展示代码依赖关系 |\n| 多语言支持 | 支持 JavaScript、TypeScript、PHP、C/C++ 等多种编程语言 |\n| 语义查询 | 支持自然语言查询和语义搜索能力 |\n\n## 2. 系统分层架构\n\nGitNexus 采用分层架构设计，将核心功能划分为前端展示层和后端处理层。前端负责用户界面和图谱可视化，后端负责代码解析、图谱构建和语义索引。\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (gitnexus-web)\"]\n UI[用户界面组件]\n HELP[帮助面板]\n DROP[拖拽连接区]\n HEADER[头部导航]\n STATUS[状态栏]\n end\n \n subgraph 后端核心[\"后端核心层 (gitnexus)\"]\n INGEST[摄取引擎]\n GRAPH[图谱构建]\n SCOPE[作用域解析]\n HERITAGE[继承关系处理]\n end\n \n subgraph 语言处理[\"语言处理器\"]\n JS[JavaScript/TypeScript]\n PHP[PHP]\n CPP[C/C++]\n GRPC[gRPC模式]\n end\n \n UI --> DROP\n DROP --> INGEST\n INGEST --> GRAPH\n INGEST --> SCOPE\n INGEST --> HERITAGE\n JS --> INGEST\n PHP --> INGEST\n CPP --> INGEST\n GRPC --> INGEST\n```\n\n### 2.2 核心模块职责\n\n| 模块名称 | 位置 | 核心职责 |\n|---------|------|---------|\n| 摄取引擎 | `gitnexus/src/core/ingestion/` | 解析源代码文件，提取节点和边 |\n| 图谱构建 | `gitnexus/src/core/graph/` | 构建和管理代码依赖图谱 |\n| 作用域解析 | `scope-resolution/` | 解析变量和方法的作用域 |\n| 继承关系处理 | `heritage-processor.ts` | 追踪类继承和接口实现关系 |\n| HTTP模式提取 | `http-patterns/` | 提取HTTP路由和服务调用模式 |\n\n## 3. 数据模型\n\n### 3.1 图谱节点类型\n\nGitNexus 使用统一的图谱数据模型来表示代码中的各种元素。节点类型决定了图谱中的可视化形式和交互行为。\n\n```mermaid\ngraph TD\n Node[图谱节点] --> Type[节点类型]\n Type --> Function[Function]\n Type --> Method[Method]\n Type --> Class[Class]\n Type --> Interface[Interface]\n Type --> Package[Package]\n Type --> Module[Module]\n \n Node --> Properties[属性]\n Properties --> nodeId[nodeId: string]\n Properties --> label[label: string]\n Properties --> filePath[filePath: string]\n```\n\n### 3.2 核心数据类型定义\n\n| 类型名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| `GraphNode` | 表示图谱中的节点 | `nodeId`, `label`, `type`, `filePath` |\n| `GraphEdge` | 表示节点间关系 | `source`, `target`, `kind` |\n| `Scope` | 代码作用域 | `ScopeId`, `ownerId`, `defs`, `children` |\n| `HeritageEntry` | 继承/实现关系 | `kind`, `parentName`, `filePath` |\n| `SemanticModel` | 语义模型 | `methods`, `symbols`, `classes` |\n\n## 4. 摄取管道 (Ingestion Pipeline)\n\n### 4.1 管道流程概览\n\n代码摄取是 GitNexus 的核心处理流程，负责将源代码转换为结构化的图谱数据。\n\n```mermaid\nflowchart TD\n A[源代码文件] --> B[语言检测]\n B --> C{是否为注册表主语言?}\n C -->|是| D[跳过摄取]\n C -->|否| E[加载Tree-sitter语言]\n E --> F[解析AST]\n F --> G[执行Tree-sitter查询]\n G --> H[提取调用关系]\n H --> I[提取继承关系]\n I --> J[构建作用域索引]\n J --> K[生成图谱节点和边]\n K --> L[输出到图谱存储]\n```\n\n### 4.2 摄取配置结构\n\n每种编程语言都有对应的摄取配置，定义了如何解析和提取代码元素。\n\n```typescript\n// C语言摄取配置示例\nconst cCallConfig = {\n // 调用提取配置\n extractor: createCallExtractor(cCallConfig),\n // 字段提取配置\n fieldExtractor: createFieldExtractor(cFieldConfig),\n // 方法提取配置\n methodExtractor: createMethodExtractor({\n ...cMethodConfig,\n extractFunctionName: cCppExtractFunctionName,\n }),\n // 变量提取配置\n variableExtractor: createVariableExtractor(cVariableConfig),\n};\n```\n\n### 4.3 语言特定处理器\n\n#### PHP HTTP模式提取\n\nPHP语言支持提取多种HTTP相关模式，包括Laravel路由、HTTP Facade、Guzzle客户端和文件读取操作。\n\n| 模式类型 | 提取内容 | 用途 |\n|---------|---------|------|\n| `laravelRoute` | Laravel路由定义 | 追踪Web路由依赖 |\n| `httpFacade` | HTTP Facade调用 | 分析HTTP请求模式 |\n| `guzzleMember` | Guzzle客户端方法 | 识别HTTP客户端使用 |\n| `fileGetContents` | 文件读取操作 | 追踪文件系统依赖 |\n\n#### gRPC模式提取\n\nJavaScript和TypeScript支持gRPC服务模式提取。\n\n| 模式名称 | 描述 |\n|---------|------|\n| `grpcMethod` | gRPC方法定义 |\n| `grpcClient` | gRPC客户端实例化 |\n| `getService` | 服务获取调用 |\n| `newSimpleCtor` | 简单构造函数 |\n| `newQualifiedCtor` | 限定名构造函数 |\n| `loadPackageDefinition` | 包定义加载 |\n\n## 5. 继承关系管理\n\n### 5.1 HeritageMap 数据结构\n\n继承关系通过 `HeritageMap` 数据结构管理，支持类继承、接口实现和多继承场景。\n\n```mermaid\ngraph LR\n A[子类] -->|extends| B[父类]\n C[实现类] -->|implements| D[接口]\n E[类] -->|extends| F[抽象类]\n F -->|implements| D\n```\n\n### 5.2 继承关系处理逻辑\n\n```typescript\n// 继承关系处理伪代码\nif (h.kind === 'implements') {\n isImpl = true;\n} else if (h.kind === 'extends') {\n const lang = getLanguageFromFilename(h.filePath);\n const strategy = getHeritageStrategy?.(lang) ?? DEFAULT_HERITAGE_STRATEGY;\n const { type } = resolveExtendsType(h.parentName, h.filePath, ctx, strategy);\n isImpl = type === 'IMPLEMENTS';\n}\n```\n\n### 5.3 实现者追踪\n\n系统维护了一个 `implementorFiles` 映射，用于快速查找某个接口的所有实现者。\n\n```typescript\nif (isImpl) {\n let files = implementorFiles.get(h.parentName);\n if (!files) {\n files = new Set();\n implementorFiles.set(h.parentName, files);\n }\n files.add(h.filePath);\n}\n```\n\n## 6. 作用域解析\n\n### 6.1 工作区索引结构\n\n作用域解析使用 `WorkspaceResolutionIndex` 来建立和维护代码的作用域层级关系。\n\n| 索引字段 | 类型 | 用途 |\n|---------|------|------|\n| `classScopeByDefId` | `ReadonlyMap` | 类定义ID到类作用域的映射 |\n| `classScopeIdToDefId` | `ReadonlyMap` | 类作用域ID到定义ID的反向映射 |\n\n### 6.2 作用域查询优化\n\n系统通过预构建索引来加速作用域查询，避免运行时的大量扫描操作。\n\n```mermaid\ngraph TD\n A[查找类方法] --> B{检查缓存索引}\n B -->|命中| C[直接返回作用域]\n B -->|未命中| D[扫描AST]\n D --> E[缓存结果]\n E --> C\n```\n\n## 7. 前端组件架构\n\n### 7.1 组件层次结构\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| `DropZone` | `DropZone.tsx` | 服务器连接和仓库加载 |\n| `Header` | `Header.tsx` | 导航栏和仓库选择器 |\n| `StatusBar` | `StatusBar.tsx` | 状态显示和进度指示 |\n| `HelpPanel` | `HelpPanel.tsx` | 帮助信息和操作指南 |\n| `OnboardingGuide` | `OnboardingGuide.tsx` | 安装引导流程 |\n| `AnalyzeOnboarding` | `AnalyzeOnboarding.tsx` | 仓库分析引导 |\n| `RepoAnalyzer` | - | GitHub仓库分析和克隆 |\n\n### 7.2 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> onboarding: 首次访问\n onboarding --> analyze: 完成安装引导\n analyze --> landing: 分析完成\n landing --> success: 选择仓库\n success --> loading: 加载图谱\n loading --> [*]: 图谱展示\n onboarding --> landing: 服务器已运行\n```\n\n### 7.3 WebGPU加速与降级\n\n系统优先使用 WebGPU 进行语义搜索加速，当浏览器不支持时自动降级到CPU处理。\n\n```mermaid\ngraph TD\n A[语义搜索请求] --> B{WebGPU可用?}\n B -->|是| C[使用GPU加速]\n B -->|否| D{用户选择}\n D -->|CPU| E[使用CPU处理]\n D -->|取消| F[跳过语义搜索]\n C --> G[生成嵌入向量]\n E --> H[较慢但功能完整]\n```\n\n## 8. 扩展机制\n\n### 8.1 语言注册表\n\n每种编程语言通过语言提供器注册到系统中，无需修改核心编排代码即可添加新语言支持。\n\n```typescript\nexport const cProvider = defineLanguage({\n id: SupportedLanguages.C,\n extensions: ['.c'],\n entryPointPatterns: [\n /^main$/,\n /^init_/,\n /_init$/,\n // ... 更多入口点模式\n ],\n treeSitterQueries: C_QUERIES,\n typeConfig: cCppConfig,\n // ...\n});\n```\n\n### 8.2 模式提取器注册\n\n新框架或语言支持通过在 `*-patterns/` 目录添加文件并在 `index.ts` 中注册来扩展。\n\n```mermaid\nflowchart TD\n A[新增模式文件] --> B[实现PatternSpec]\n B --> C[调用compilePatterns]\n C --> D[导出CompiledPatterns]\n D --> E[注册到index.ts]\n E --> F[管道自动加载]\n```\n\n## 9. 配置与扩展\n\n### 9.1 语言支持矩阵\n\n| 语言 | 扩展名 | 调用提取 | 继承追踪 | 字段提取 | 变量提取 |\n|-----|--------|---------|---------|---------|---------|\n| JavaScript | `.js` | ✓ | ✓ | ✓ | ✓ |\n| TypeScript | `.ts` `.tsx` | ✓ | ✓ | ✓ | ✓ |\n| PHP | `.php` | ✓ | ✓ | ✓ | ✓ |\n| C | `.c` | ✓ | ✓ | ✓ | ✓ |\n| C++ | `.cpp` `.h` | ✓ | ✓ | ✓ | ✓ |\n\n### 9.2 入口点模式配置\n\n入口点模式用于识别程序的主要入口函数，便于图谱构建时的根节点识别。\n\n| 模式前缀 | 模式后缀 | 示例 |\n|---------|---------|------|\n| `main` | - | `main` |\n| `init_` | `_init` | `init_database`, `database_init` |\n| `start_` | `_start` | `start_server`, `server_start` |\n| `stop_` | `_stop` | `stop_service`, `service_stop` |\n| `create_` | `_create` | `create_window`, `window_create` |\n\n## 10. 总结\n\nGitNexus 的系统架构遵循模块化和可扩展的设计原则，通过清晰的层次划分和标准化的接口定义，实现了多语言代码分析和图谱可视化功能。核心的摄取管道采用 Tree-sitter 进行 AST 解析，结合语言特定的模式提取器，实现了高效的代码元素提取。继承关系管理和作用域解析机制为语义查询提供了坚实的数据基础，而前端组件的模块化设计则确保了良好的用户体验和可维护性。 资料来源：[gitnexus/src/core/group/PIPELINE.md:1-50]()\n\n\n---\n\n\n\n## MCP 架构与集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [CLI 命令详解](#page-cli-commands), [数据存储](#page-data-storage)\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/mcp/local/local-backend.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/local/local-backend.ts)\n- [gitnexus/src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/repo-manager.ts)\n
\n\n# MCP 架构与集成\n\n## 概述\n\nGitNexus 项目中的 MCP（Model Context Protocol）模块是一个为大型语言模型（LLM）提供上下文集成能力的核心子系统。MCP 架构使 AI 助手能够通过标准化的协议与本地 Git 仓库进行交互，获取仓库元数据、操作 Git 资源、管理仓库状态，并执行各种开发任务。\n\nMCP 模块位于 `gitnexus/src/mcp/` 目录下，采用模块化设计，包含服务器核心、工具集、资源管理和本地后端四个主要组件。\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[AI 客户端] -->|MCP 协议| B[MCP 服务器]\n B --> C[工具层]\n B --> D[资源层]\n C --> E[Git 工具集]\n C --> F[文件工具集]\n D --> G[仓库资源]\n D --> H[配置资源]\n E --> I[本地后端]\n I --> J[仓库管理器]\n J --> K[Git 仓库]\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 服务器 | `src/mcp/server.ts` | 协议初始化、请求路由、连接管理 |\n| 工具集 | `src/mcp/tools.ts` | 定义可调用的 Git 和文件操作 |\n| 资源层 | `src/mcp/resources.ts` | 暴露仓库元数据和配置信息 |\n| 本地后端 | `src/mcp/local/local-backend.ts` | 与本地文件系统和 Git 交互 |\n| 仓库管理 | `src/storage/repo-manager.ts` | 仓库生命周期管理 |\n\n资料来源：[gitnexus/src/mcp/server.ts:1-50]()\n\n## MCP 服务器实现\n\n### 服务器初始化\n\nMCP 服务器是整个模块的核心入口点，负责初始化协议栈并注册所有可用的工具和资源。\n\n```typescript\n// 服务器初始化流程\nconst server = new McpServer({\n name: \"gitnexus\",\n version: \"1.0.0\"\n});\n```\n\n服务器通过 `@modelcontextprotocol/sdk` 包提供的 `McpServer` 类实现，支持以下功能：\n\n- 动态注册工具和资源\n- 请求/响应模式处理\n- 资源订阅机制\n- 错误处理和日志记录\n\n资料来源：[gitnexus/src/mcp/server.ts:1-30]()\n\n### 工具注册流程\n\n工具注册是服务器初始化的关键步骤，每个工具都包含名称、描述和参数模式：\n\n```mermaid\ngraph LR\n A[定义工具] --> B[注册到服务器]\n B --> C[客户端发现]\n C --> D[调用执行]\n D --> E[返回结果]\n```\n\n## 工具集详解\n\n### 工具分类\n\nMCP 工具集分为两大类：Git 操作工具和文件操作工具。\n\n| 工具类别 | 功能描述 | 典型用例 |\n|----------|----------|----------|\n| Git 操作 | 分支管理、提交操作、状态查询 | 创建分支、提交更改、查看日志 |\n| 文件操作 | 读写文件、目录遍历、路径解析 | 读取配置文件、写入代码文件 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:1-100]()\n\n### Git 操作工具\n\n#### 分支管理工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_list_branches` | `repoPath: string` | 分支名称数组 |\n| `git_create_branch` | `repoPath, branchName` | 操作状态 |\n| `git_delete_branch` | `repoPath, branchName` | 操作状态 |\n| `git_checkout` | `repoPath, branchName` | 操作状态 |\n\n#### 提交管理工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_commit` | `repoPath, message, files?` | 提交哈希 |\n| `git_log` | `repoPath, limit?` | 提交历史数组 |\n| `git_status` | `repoPath` | 工作区状态 |\n\n#### 远程操作工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_pull` | `repoPath` | 拉取结果 |\n| `git_push` | `repoPath, remote?` | 推送结果 |\n| `git_fetch` | `repoPath, remote?` | 获取结果 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:50-150]()\n\n### 文件操作工具\n\n文件操作工具提供了对仓库文件系统的直接访问能力：\n\n```typescript\n// 文件读取工具参数定义\ninterface ReadFileTool {\n params: {\n path: string; // 文件绝对路径\n encoding?: string; // 编码格式，默认 utf-8\n };\n returns: {\n content: string;\n metadata: FileMetadata;\n };\n}\n```\n\n| 工具名称 | 功能 | 安全性 |\n|----------|------|--------|\n| `read_file` | 读取文件内容 | 受路径验证限制 |\n| `write_file` | 写入文件内容 | 仅允许工作区内操作 |\n| `list_directory` | 列出目录内容 | 递归深度受限 |\n| `get_file_info` | 获取文件元数据 | 公开信息查询 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:100-200]()\n\n## 资源层设计\n\n### 资源类型\n\nMCP 资源是一种只读的上下文数据，通过 URI 方案暴露给 AI 客户端：\n\n```mermaid\ngraph TD\n A[资源注册] --> B[URI 模板]\n B --> C[客户端请求]\n C --> D[资源读取器]\n D --> E[格式化数据]\n E --> F[返回响应]\n```\n\n### 仓库资源\n\n| 资源 URI | 描述 | 数据格式 |\n|----------|------|----------|\n| `gitnexus://repo/info` | 仓库基本信息 | JSON |\n| `gitnexus://repo/branches` | 分支列表 | JSON 数组 |\n| `gitnexus://repo/remotes` | 远程仓库配置 | JSON 数组 |\n| `gitnexus://repo/status` | 当前工作区状态 | JSON |\n| `gitnexus://repo/config` | 仓库配置 | INI 格式 |\n\n资料来源：[gitnexus/src/mcp/resources.ts:1-80]()\n\n### 配置资源\n\n系统配置资源提供全局设置和用户偏好的访问：\n\n```typescript\n// 配置资源结构\ninterface ConfigResource {\n uri: \"gitnexus://config/settings\";\n data: {\n defaultBranch: string;\n autoFetch: boolean;\n theme: string;\n editor: EditorConfig;\n };\n}\n```\n\n| 资源 URI | 用途 | 更新频率 |\n|----------|------|----------|\n| `gitnexus://config/settings` | 用户设置 | 运行时可更新 |\n| `gitnexus://config/git` | Git 全局配置 | 静态 |\n| `gitnexus://config/plugins` | 插件配置 | 按需加载 |\n\n资料来源：[gitnexus/src/mcp/resources.ts:50-120]()\n\n## 本地后端集成\n\n### 本地后端架构\n\n本地后端是 MCP 与本地文件系统之间的桥梁，负责将工具调用转换为实际的操作系统操作：\n\n```mermaid\ngraph LR\n A[MCP 工具调用] --> B[本地后端 API]\n B --> C[权限检查]\n C --> D[路径验证]\n D --> E[文件系统操作]\n E --> F[结果格式化]\n F --> G[返回响应]\n```\n\n### 后端服务类\n\n`LocalBackendService` 是核心服务类，提供了所有与本地系统交互的方法：\n\n```typescript\nclass LocalBackendService {\n // 构造函数\n constructor(basePath: string, options?: BackendOptions);\n \n // Git 操作方法\n executeGitCommand(command: GitCommand): Promise;\n \n // 文件操作方法\n readFile(path: string, options?: ReadOptions): Promise;\n writeFile(path: string, content: string): Promise;\n \n // 路径操作方法\n resolvePath(relativePath: string): string;\n validatePath(path: string): boolean;\n}\n```\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:1-60]()\n\n### 权限与安全\n\n本地后端实现了多层安全检查机制：\n\n| 安全层级 | 检查项 | 实施方式 |\n|----------|--------|----------|\n| 路径验证 | 工作区边界检查 | 正则表达式匹配 |\n| 操作权限 | 读写执行权限 | 系统 API 调用 |\n| 命令白名单 | Git 子命令限制 | 白名单列表 |\n| 内容过滤 | 敏感信息脱敏 | 预处理器 |\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:40-100]()\n\n### Git 命令执行\n\n本地后端封装了常用的 Git 操作：\n\n```typescript\n// Git 命令执行接口\ninterface GitCommandExecutor {\n // 分支操作\n listBranches(options?: ListOptions): Promise;\n createBranch(name: string, startPoint?: string): Promise;\n deleteBranch(name: string, force?: boolean): Promise;\n \n // 提交操作\n commit(message: string, files?: string[]): Promise;\n log(limit?: number): Promise;\n \n // 远程操作\n pull(options?: PullOptions): Promise;\n push(remote?: string, branch?: string): Promise;\n}\n```\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:80-150]()\n\n## 仓库管理器集成\n\n### 仓库管理器概述\n\n仓库管理器（`repo-manager.ts`）负责仓库的注册、发现和生命周期管理，为 MCP 提供仓库上下文：\n\n```mermaid\ngraph TD\n A[仓库发现] --> B[仓库注册]\n B --> C[仓库缓存]\n C --> D[MCP 上下文]\n D --> E[工具调用]\n E --> F[状态同步]\n```\n\n### 核心接口\n\n| 方法 | 描述 | 返回类型 |\n|------|------|----------|\n| `registerRepo(path)` | 注册新仓库 | `RepoInfo` |\n| `getRepo(path)` | 获取仓库信息 | `RepoInfo` |\n| `listRepos()` | 列出所有仓库 | `RepoInfo[]` |\n| `removeRepo(path)` | 移除仓库 | `void` |\n| `syncRepo(path)` | 同步仓库状态 | `SyncResult` |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:1-100]()\n\n### 仓库信息模型\n\n```typescript\ninterface RepoInfo {\n id: string; // 唯一标识符\n path: string; // 仓库路径\n name: string; // 仓库名称\n currentBranch: string; // 当前分支\n branches: string[]; // 本地分支列表\n remotes: RemoteInfo[]; // 远程仓库信息\n lastSync: Date; // 最后同步时间\n status: RepoStatus; // 仓库状态\n}\n```\n\n| 状态枚举 | 含义 |\n|----------|------|\n| `active` | 正常工作状态 |\n| `syncing` | 正在同步中 |\n| `error` | 发生错误 |\n| `inactive` | 未激活 |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:50-150]()\n\n### MCP 上下文关联\n\n仓库管理器与 MCP 模块通过上下文对象关联：\n\n```typescript\n// MCP 上下文配置\ninterface MCPContext {\n repoManager: RepoManager;\n currentRepo: RepoInfo | null;\n workspaceRoots: string[];\n}\n```\n\n这种关联使得 MCP 工具可以自动感知当前仓库上下文，减少重复的参数传递。\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:100-180]()\n\n## 集成流程\n\n### 启动初始化流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用入口\n participant Server as MCP 服务器\n participant Tools as 工具注册器\n participant Resources as 资源注册器\n participant Backend as 本地后端\n participant RepoMgr as 仓库管理器\n \n App->>RepoMgr: 初始化仓库管理器\n App->>Server: 创建 MCP 服务器实例\n Server->>Backend: 初始化本地后端\n Server->>Tools: 注册工具集\n Server->>Resources: 注册资源\n Backend->>RepoMgr: 获取仓库列表\n Tools->>RepoMgr: 绑定仓库上下文\n```\n\n### 工具调用时序\n\n```mermaid\nsequenceDiagram\n participant Client as AI 客户端\n participant Server as MCP 服务器\n participant Tool as 工具处理器\n participant Backend as 本地后端\n participant RepoMgr as 仓库管理器\n participant Git as Git 进程\n \n Client->>Server: 工具调用请求\n Server->>Tool: 解析工具名称\n Tool->>RepoMgr: 获取当前仓库\n Tool->>Backend: 执行操作请求\n Backend->>Git: 调用 Git 命令\n Git-->>Backend: 返回结果\n Backend-->>Tool: 格式化结果\n Tool-->>Server: 返回响应\n Server-->>Client: JSON-RPC 响应\n```\n\n## 配置与扩展\n\n### MCP 服务器配置\n\n```typescript\ninterface MCPServerConfig {\n // 服务器标识\n name: string;\n version: string;\n \n // 连接配置\n transport: 'stdio' | 'http';\n port?: number;\n \n // 功能开关\n features: {\n tools: boolean;\n resources: boolean;\n prompts: boolean;\n };\n \n // 安全配置\n security: {\n allowedPaths: string[];\n blockedCommands: string[];\n };\n}\n```\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `transport` | `string` | `stdio` | 传输协议类型 |\n| `port` | `number` | `3000` | HTTP 端口 |\n| `tools.enabled` | `boolean` | `true` | 启用工具 |\n| `resources.enabled` | `boolean` | `true` | 启用资源 |\n\n### 扩展工具开发\n\n开发者可以通过继承基础工具类来扩展 MCP 工具：\n\n```typescript\n// 自定义工具模板\nclass CustomTool extends BaseTool {\n readonly name = \"custom_tool\";\n readonly description = \"自定义工具描述\";\n \n readonly inputSchema = {\n type: \"object\",\n properties: {\n param1: { type: \"string\" },\n param2: { type: \"number\" }\n },\n required: [\"param1\"]\n };\n \n async execute(params: Record) {\n // 工具逻辑实现\n return { success: true, data: {} };\n }\n}\n```\n\n## 最佳实践\n\n### 性能优化\n\n| 优化项 | 方法 | 收益 |\n|--------|------|------|\n| 缓存结果 | 资源缓存层 | 减少重复调用 |\n| 批处理 | 合并多个操作 | 降低延迟 |\n| 异步执行 | 非阻塞 I/O | 提高吞吐量 |\n| 路径优化 | 相对路径解析 | 减少字符串处理 |\n\n### 错误处理\n\nMCP 模块采用统一的错误处理机制：\n\n```typescript\n// 错误类型分类\nenum MCPErrorCode {\n TOOL_NOT_FOUND = -32601,\n INVALID_PARAMS = -32602,\n EXECUTION_ERROR = -32603,\n RESOURCE_NOT_FOUND = -32604,\n PERMISSION_DENIED = -32605\n}\n```\n\n### 安全建议\n\n1. **路径限制**：始终验证文件路径在工作区内\n2. **命令白名单**：只允许安全的 Git 子命令\n3. **输入验证**：严格校验所有工具参数\n4. **沙箱执行**：考虑使用隔离环境执行危险操作\n\n## 总结\n\nGitNexus 的 MCP 架构通过模块化设计实现了与 AI 助手的深度集成。核心组件包括 MCP 服务器、工具集、资源层和本地后端，它们协同工作，为 AI 提供对 Git 仓库的完整访问能力。仓库管理器作为状态中枢，确保 MCP 能够准确感知当前工作环境。开发者可以通过扩展工具类和注册自定义资源来增强系统功能，同时应遵循安全最佳实践以保护系统完整性。\n\n---\n\n\n\n## 知识图谱构建\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [索引管道](#page-indexing-pipeline), [数据存储](#page-data-storage)\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/ingestion/pipeline-phases/wildcard-synthesis.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.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/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
\n\n# 知识图谱构建\n\n## 概述\n\n知识图谱构建（Knowledge Graph Construction）是 GitNexus 的核心子系统，负责将代码仓库中的源代码转换为可查询的图结构数据。该系统通过多阶段管道（Pipeline）处理，支持多种编程语言的语法解析、符号提取、依赖关系分析以及语义关联构建，最终生成包含节点（Nodes）和关系（Relationships）的知识图谱。\n\n知识图谱的节点代表代码中的各种实体，如函数、类、接口、结构体、枚举等；关系则表示这些实体之间的语义连接，包括导入关系（IMPORTS）、调用关系（CALLS）、继承关系（EXTENDS/IMPLEMENTS）等。资料来源：[gitnexus/src/core/graph/types.ts:1-20]()\n\n## 核心数据模型\n\n### GraphNode（图节点）\n\n图节点是知识图谱的基本元素，每个节点包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 节点的唯一标识符 |\n| label | string | 节点类型标签，如 Function、Class、Interface 等 |\n| properties | Record | 节点的附加属性 |\n| filePath | string | 节点对应的源文件路径 |\n| name | string | 节点的名称 |\n| codeLocation | CodeLocation | 代码位置信息 |\n\n资料来源：[gitnexus/src/core/graph/types.ts:1-15]()\n\n### GraphRelationship（图关系）\n\n关系连接图中的节点，表示实体之间的关联：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 关系的唯一标识符 |\n| type | string | 关系类型，如 IMPORTS、CALLS、EXTENDS |\n| sourceId | string | 源节点 ID |\n| targetId | string | 目标节点 ID |\n| properties | Record | 关系的附加属性 |\n\n资料来源：[gitnexus/src/core/graph/types.ts:15-25]()\n\n### KnowledgeGraph（知识图谱接口）\n\n```typescript\ninterface KnowledgeGraph {\n addNode: (node: GraphNode) => void;\n addRelationship: (relationship: GraphRelationship) => void;\n getNode: (id: string) => GraphNode | undefined;\n removeNode: (nodeId: string) => boolean;\n removeNodesByFile: (filePath: string) => number;\n nodeCount: number;\n relationshipCount: number;\n forEachNode: (fn: (node: GraphNode) => void) => void;\n forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;\n}\n```\n\n资料来源：[gitnexus/src/core/graph/types.ts:25-40]()\n\n## 导入关系处理\n\n### 通配符导入合成\n\n对于采用整体模块导入语义的语言（如 Go、Ruby、C/C++、Swift），GitNexus 实现了通配符导入绑定合成机制。这些语言的导入语句会引入文件中的所有导出符号，而非特定命名符号。\n\n```mermaid\nflowchart TD\n A[源文件] --> B[遍历 IMPORTS 关系]\n B --> C{语言支持通配符?}\n C -->|是| D[获取导出符号集合]\n C -->|否| E[跳过]\n D --> F[为每个导出符号创建绑定]\n F --> G[MAX_SYNTHETIC_BINDINGS 检查]\n G --> H[添加到 namedImportMap]\n```\n\n该机制的核心常量定义如下：\n\n```typescript\nconst MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;\n```\n\n此限制防止了包含大量大型头文件的 C/C++ 文件导致的内存膨胀问题。资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:1-50]()\n\n### 导入映射构建\n\n系统维护两个核心映射结构：\n\n- **importMap**：记录文件级别的导入关系\n- **namedImportMap**：记录文件级别的命名导入绑定\n\n```typescript\nconst FILE_PREFIX = 'File:';\nconst graphImports = new Map>();\n\ngraph.forEachRelationship((rel) => {\n if (rel.type !== 'IMPORTS') return;\n if (!rel.sourceId.startsWith(FILE_PREFIX) || !rel.targetId.startsWith(FILE_PREFIX)) return;\n // 处理通配符语言...\n});\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:50-80]()\n\n## 继承关系处理\n\n### HeritageMap（继承图谱）\n\n继承关系处理模块负责构建和维护类型继承层次结构，支持 extends 和 implements 两种继承类型。\n\n```mermaid\nflowchart TD\n A[遍历 Heritage 条目] --> B{继承类型?}\n B -->|implements| C[标记为实现类]\n B -->|extends| D[解析扩展类型]\n D --> E{类型为 IMPLEMENTS?}\n E -->|是| C\n E -->|否| F[标记为扩展类]\n C --> G[添加至 implementorFiles]\n F --> G\n```\n\n关键数据结构：\n\n```typescript\ninterface ParentEntry {\n parentName: string;\n kind: 'extends' | 'implements';\n filePath: string;\n}\n\nconst entriesFor = (nodeId: string): readonly ParentEntry[] | undefined =>\n directParents.get(nodeId);\n\nconst getParentEntries = (childNodeId: string): readonly ParentEntry[] => {\n const entries = entriesFor(childNodeId);\n return entries ?? [];\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts:1-50]()\n\n### HeritageProcessor（继承处理器）\n\n处理器负责从源代码中提取继承关系声明：\n\n```typescript\nconst processHeritage = async (\n files: FileInfo[],\n ctx: ResolutionContext,\n onProgress?: (current: number, total: number) => void,\n) => {\n const parser = await loadParser();\n \n for (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 const language = getLanguageFromFilename(file.path);\n if (!language || !isLanguageAvailable(language)) continue;\n \n // 加载语言并获取 AST...\n }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-40]()\n\n## 调用关系处理\n\n### CallProcessor（调用处理器）\n\n调用关系处理模块提取函数调用信息，支持跨文件类型解析：\n\n```mermaid\nflowchart TD\n A[文件列表] --> B[遍历文件]\n B --> C{语言支持?}\n C -->|是| D[加载 AST]\n C -->|否| E[跳过]\n D --> F[执行 Tree-sitter 查询]\n F --> G[提取调用匹配]\n G --> H[构建类型环境]\n H --> I[处理调用关系]\n```\n\n### 跨文件类型传播\n\n系统支持从导入的调用目标传播返回类型：\n\n```typescript\ninterface CallProcessorOptions {\n /** Phase 14 E3: 跨文件返回类型 */\n importedReturnTypesMap?: ReadonlyMap>,\n /** Phase 14 E3: 跨文件原始返回类型 */\n importedRawReturnTypesMap?: ReadonlyMap>,\n /** Phase 14 E2: 导入绑定 */\n importedBindingsMap?: ReadonlyMap>,\n heritageMap?: HeritageMap,\n bindingAccumulator?: BindingAccumulator,\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-50]()\n\n## 语言解析支持\n\n### ParserLoader（解析器加载器）\n\nGitNexus 通过 tree-sitter 支持多种编程语言的语法解析：\n\n| 语言 | 解析器包 | 说明 |\n|------|----------|------|\n| TypeScript | tree-sitter-typescript | 支持 .ts 和 .tsx 文件 |\n| Python | tree-sitter-python | Python 语法支持 |\n| Java | tree-sitter-java | Java 语法支持 |\n| C# | tree-sitter-c-sharp | 需要显式子路径导入 |\n| C++ | tree-sitter-cpp | C++ 语法支持 |\n| Go | tree-sitter-go | Go 语法支持 |\n| Ruby | tree-sitter-ruby | Ruby 语法支持 |\n\n```typescript\nconst PARSER_LOADERS: Record = {\n [SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript,\n unavailableNote: 'TS 解析需要 tree-sitter-typescript',\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n unavailableNote: 'Python 解析需要 tree-sitter-python',\n },\n [SupportedLanguages.Java]: {\n load: () => _require('tree-sitter-java'),\n unavailableNote: 'Java 解析需要 tree-sitter-java',\n },\n [SupportedLanguages.CSharp]: {\n load: () => _require('tree-sitter-c-sharp/bindings/node/index.js'),\n unavailableNote: 'C# 解析需要 tree-sitter-c-sharp',\n },\n};\n```\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-60]()\n\n### 支持的节点标签类型\n\n以下标签类型代表顶层可导入符号：\n\n```typescript\nconst IMPORTABLE_SYMBOL_LABELS = new Set([\n 'Function',\n 'Class',\n 'Interface',\n 'Struct',\n 'Enum',\n 'Trait',\n 'TypeAlias',\n 'Const',\n 'Static',\n 'Record',\n 'Union',\n 'Typedef',\n 'Macro',\n]);\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:30-45]()\n\n## 模式提取框架\n\n### HTTP/GRPC 模式提取\n\n系统通过 tree-sitter 查询模式识别特定框架的代码模式：\n\n```mermaid\nflowchart TD\n A[源代码] --> B[Tree-sitter 解析]\n B --> C[编译模式查询]\n C --> D[匹配结果]\n D --> E[提取符号信息]\n E --> F[生成图谱节点]\n```\n\nPHP 模式提取示例：\n\n```typescript\ninterface PhpPatternBundle {\n laravelRoute: CompiledPatterns>;\n httpFacade: CompiledPatterns>;\n guzzleMember: CompiledPatterns>;\n fileGetContents: CompiledPatterns>;\n}\n\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资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-50]()\n\n## 构建流程总结\n\n### 完整管道流程\n\n```mermaid\nflowchart TD\n A[源代码文件] --> B[语言检测]\n B --> C[Tree-sitter 解析]\n C --> D[符号提取]\n D --> E[导入关系分析]\n E --> F[继承关系分析]\n F --> G[调用关系分析]\n G --> H[通配符绑定合成]\n H --> I[类型传播]\n I --> J[知识图谱输出]\n \n E -.->|通配符语言| K[wildcard-synthesis.ts]\n F -.->|heritage-map.ts| L[继承图谱]\n G -.->|call-processor.ts| M[调用处理器]\n```\n\n### 核心处理阶段\n\n| 阶段 | 组件 | 功能 |\n|------|------|------|\n| 解析 | parser-loader.ts | 加载 tree-sitter 解析器 |\n| 符号提取 | 服务层 | 提取函数、类、接口等 |\n| 导入处理 | wildcard-synthesis.ts | 处理通配符导入绑定 |\n| 继承分析 | heritage-processor.ts | 提取 extends/implements |\n| 调用分析 | call-processor.ts | 提取函数调用关系 |\n| 图谱构建 | graph.ts/types.ts | 组装节点和关系 |\n\n## 性能优化\n\n### 批处理策略\n\n系统采用批量处理策略避免阻塞事件循环：\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n const file = files[i];\n if (i % 20 === 0) await yieldToEventLoop(); // 每20个文件让出控制权\n \n // 处理文件...\n}\n```\n\n### 缓存机制\n\nAST 树被缓存以避免重复解析：\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/ingestion/heritage-processor.ts:20-35]()\n\n### 大文件处理\n\n对于超过 32KB 的大文件，系统使用更大的缓冲区：\n\n```typescript\n// Use larger bufferSize for files > 32KB\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\n```\n\n## 配置与扩展\n\n### 语言提供者注册\n\n新语言支持通过语言提供者接口注册：\n\n```typescript\nimport { providers, getProviderForFile } from '../languages/index.js';\nimport type { LanguageProvider, ImportSemantics } from '../language-provider.js';\n```\n\n### 自定义模式添加\n\n添加新的代码模式提取需要：\n\n1. 在对应语言的 `*-patterns/` 目录下创建新文件\n2. 定义 PatternSpec 结构\n3. 在 `index.ts` 中注册新模式\n4. 无需修改管道编排代码\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:1-30]()\n\n---\n\n\n\n## 索引管道\n\n### 相关页面\n\n相关主题：[知识图谱构建](#page-knowledge-graph), [多语言支持](#page-multilanguage-support)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/ingestion/pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/scan.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/scan.ts)\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/src/core/ingestion/pipeline-phases/structure.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/structure.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/cross-file.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/resolve-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/resolve-references.ts)\n
\n\n# 索引管道\n\n## 概述\n\n索引管道（Ingestion Pipeline）是 GitNexus 的核心处理引擎，负责将源代码仓库转换为结构化的知识图谱。该管道通过多个阶段的顺序执行，完成文件扫描、AST 解析、作用域提取、跨文件引用解析，最终生成可用于可视化与分析的依赖图数据。\n\n索引管道遵循 RFC #909 定义的摄取生命周期规范，采用 Ring 2 架构设计，实现了解析逻辑与业务逻辑的分离。\n\n## 架构总览\n\n索引管道采用阶段式（Phase-Based）架构，每个阶段负责特定的摄取任务，并通过依赖声明定义执行顺序。\n\n```mermaid\ngraph TD\n A[开始摄取] --> B[structure 阶段]\n B --> C[scan 阶段]\n C --> D[parse 阶段]\n D --> E[cross-file 阶段]\n E --> F[resolve-references 阶段]\n F --> G[emit-references 阶段]\n G --> H[完成: 知识图谱]\n \n B -.->|依赖| D\n```\n\n### 核心设计原则\n\n| 原则 | 说明 |\n|------|------|\n| **阶段解耦** | 每个阶段独立执行，通过明确定义的输入输出接口通信 |\n| **增量处理** | 支持文件级别的增量解析，避免全量重解析 |\n| **并行友好** | 阶段内部可并行处理独立文件 |\n| **容错设计** | 单文件解析失败不影响整体管道执行 |\n\n资料来源：[pipeline.ts](gitnexus/src/core/ingestion/pipeline.ts)\n\n## 管道阶段详解\n\n### 阶段 1：structure（结构分析）\n\n`structure` 阶段是管道的入口点，负责扫描仓库目录结构并识别所有待处理文件。\n\n**职责**：\n- 递归遍历仓库目录\n- 过滤构建产物和二进制文件\n- 识别支持的编程语言文件\n- 生成文件元数据列表\n\n**输出**：\n- `scannedFiles`: 待解析文件的完整列表\n- `allPaths`: 所有文件路径集合\n- `allPathSet`: 用于快速查找的路径集合\n\n资料来源：[pipeline-phases/structure.ts](gitnexus/src/core/ingestion/pipeline-phases/structure.ts)\n\n### 阶段 2：scan（扫描）\n\n`scan` 阶段在 structure 阶段完成后执行，生成文件索引和元数据。\n\n**职责**：\n- 生成文件唯一标识符\n- 提取文件基础信息（大小、修改时间）\n- 构建文件索引结构\n\n### 阶段 3：parse（解析）\n\n`parse` 阶段是管道中计算密集度最高的阶段，负责将源代码转换为 AST 并提取基础语义信息。\n\n**依赖阶段**：`structure`、`markdown`、`cobol`\n\n**核心流程**：\n\n```mermaid\ngraph TD\n A[获取扫描文件列表] --> B[按语言分组]\n B --> C{for each file}\n C --> D{检查语言支持}\n D -->|不支持| E[跳过文件]\n D -->|支持| F[加载 Tree-sitter 语言]\n F --> G[生成 AST]\n G --> H{缓存命中?}\n H -->|否| I[应用预处理器]\n I --> J[解析源码]\n J --> K[缓存 AST]\n K --> L[执行 tree-sitter 查询]\n L --> M[提取捕获匹配]\n M --> N[ScopeExtractor]\n N --> O[生成 ParsedFile]\n O --> P{更多文件?}\n P -->|是| C\n P -->|否| Q[返回解析结果]\n \n E --> P\n```\n\n**核心函数**：`runChunkedParseAndResolve`\n\n该函数协调文件解析和作用域解析的完整流程：\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**输出**：\n- `parsedFiles`: `ParsedFile[]` 数组，每个源文件对应一个\n- `allPaths`、`allPathSet`、`totalFiles`: 传递给后续阶段的上下文\n\n资料来源：[pipeline-phases/parse.ts](gitnexus/src/core/ingestion/pipeline-phases/parse.ts)\n\n### 阶段 4：cross-file（跨文件分析）\n\n`cross-file` 阶段在 parse 阶段完成后执行，处理跨文件的依赖关系和引用解析。\n\n**职责**：\n- 解析 `import`/`require` 语句\n- 建立跨文件符号引用\n- 处理包级别依赖\n\n**输入**：`ParsedFile[]`（parse 阶段输出）\n\n**输出**：\n- 跨文件引用关系图\n- 解析后的导入边（ImportEdge）\n\n资料来源：[pipeline-phases/cross-file.ts](gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts)\n\n### 阶段 5：resolve-references（引用解析）\n\n`resolve-references` 阶段负责将符号引用解析为具体的节点标识符。\n\n**职责**：\n- 解析符号引用到具体节点\n- 构建引用索引（ReferenceIndex）\n- 计算引用置信度\n\n**语义模型**：\n\n```\nReferenceIndex\n └── referenceSites: 预解析的使用事实\n └── 由 resolve-references 填充\n```\n\n该阶段使用 `ResolutionContext` 上下文进行符号解析，包含：\n- 文件路径映射\n- 符号表\n- 作用域信息\n\n资料来源：[resolve-references.ts](gitnexus/src/core/ingestion/resolve-references.ts)\n\n### 阶段 6：emit-references（发射引用）\n\n`emit-references` 是 RFC #909 生命周期中的第 5 阶段，负责将 `ReferenceIndex` 中的引用数据物化为知识图谱中的边。\n\n**职责**：\n- 将引用记录转换为 `GraphRelationship`\n- 计算置信度和证据信息\n- 发射带标签的边到图数据库\n\n**发射的边类型**：\n\n| 边类型 | 源类型 | 说明 |\n|--------|--------|------|\n| `CALLS` | 引用.kind = 'call' | 函数调用关系 |\n| `ACCESSES` | 引用.kind = 'read' / 'write' | 变量访问关系 |\n| `INHERITS` | 引用.kind = 'inherits' | 继承关系 |\n| `USES` | 引用.kind = 'type-reference' / 'import-use' | 类型使用或导入使用 |\n\n**证据属性**：\n- `confidence`: 预计算的置信度分数\n- `reason`: 人类可读的原因描述\n- `evidence`: `ResolutionEvidence[]` 追踪轨迹\n- `step`: 访问类型的区分标记\n\n```typescript\ngraph.addRelationship({\n id: generateId(relType, `${child.id}->${parent.id}`),\n sourceId: child.id,\n targetId: parent.id,\n type: relType,\n confidence: Math.sqrt(child.confidence * parent.confidence),\n reason: '',\n});\n```\n\n资料来源：[emit-references.ts](gitnexus/src/core/ingestion/emit-references.ts)\n\n## ScopeExtractor 作用域提取器\n\n`ScopeExtractor` 是 parse 阶段的核心组件，负责将语言提供商的 `CaptureMatch[]` 转换为 `ParsedFile`。\n\n### 设计原则\n\n| 原则 | 说明 |\n|------|------|\n| **源无关** | 消费 `CaptureMatch[]`，不关心其来自 tree-sitter 查询还是 COBOL 正则标记器 |\n| **单次 AST 遍历** | 提供商的 `emitScopeCaptures` 钩子内部完成 AST 遍历，驱动代码不再遍历 |\n| **纯函数** | 相同的匹配输入产生相同的 ParsedFile 输出 |\n| **集中不变式** | 由 `buildScopeTree`（Ring 2 SHARED #912）强制执行结构不变式 |\n\n### 五阶段处理管道\n\n`ScopeExtractor` 内部执行一个五阶段管道，每个阶段处理特定的职责：\n\n```mermaid\nflowchart TD\n A[CaptureMatch 输入] --> B[阶段1: 构建作用域树]\n B --> C[阶段2: 收集绑定]\n C --> D[阶段3: 解析导入]\n D --> E[阶段4: 构建引用站点]\n E --> F[阶段5: 生成 ParsedFile]\n F --> G[ParsedFile 输出]\n```\n\n### ParsedFile 数据结构\n\n```typescript\ninterface ParsedFile {\n scopes: Scope[]; // 文件中所有作用域，按拓扑顺序排列\n parsedImports: ParsedImport[]; // 原始导入信息\n localDefs: SymbolDef[]; // 文件内声明的定义\n referenceSites: ReferenceSite[]; // 预解析的使用事实\n}\n```\n\n**`ParsedFile` 不携带的内容**：\n- 链接后的 `ImportEdge`（那是 finalize 输出）\n- `ScopeTree` 实例（调用方通过 `buildScopeTree(parsedFile.scopes)` 构建）\n\n资料来源：[scope-extractor.ts](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n## HeritageProcessor 继承关系处理\n\n`heritage-processor` 负责处理类继承和接口实现关系。\n\n### 处理类型\n\n| 关系类型 | 源符号 | 目标符号 | 边类型 |\n|----------|--------|----------|--------|\n| `extends` | 子类 | 父类 | `EXTENDS` |\n| `implements` | 实现类 | 接口 | `IMPLEMENTS` |\n\n### 核心逻辑\n\n```mermaid\ngraph TD\n A[HeritageEntry] --> B{关系类型}\n B -->|extends| C[resolveExtendsType]\n B -->|implements| D[isImpl = true]\n \n C --> E{语言类型}\n E -->|Ruby| F[特殊策略]\n E -->|其他| G[默认策略]\n \n D --> H[resolveHeritageId]\n F --> H\n G --> H\n \n H --> I[generateId]\n I --> J[addRelationship to Graph]\n```\n\n**置信度计算**：\n```typescript\nconfidence: Math.sqrt(child.confidence * parent.confidence)\n```\n\n使用几何平均数确保两端节点置信度都高时关系置信度才高。\n\n### HeritageMap 数据结构\n\n```typescript\nconst entriesFor = (nodeId: string): readonly ParentEntry[] | undefined =>\n directParents.get(nodeId);\n\nconst getParentEntries = (childNodeId: string): readonly ParentEntry[] => {\n const entries = entriesFor(childNodeId);\n return entries ?? [];\n};\n\nconst getParents = (childNodeId: string): string[] => {\n const entries = entriesFor(childNodeId);\n if (!entries) return [];\n // 去重逻辑确保平坦字符串契约保持一致\n};\n```\n\n资料来源：[heritage-map.ts](gitnexus/src/core/ingestion/heritage-map.ts)\n\n## WorkspaceResolutionIndex 工作区解析索引\n\n`WorkspaceResolutionIndex` 是跨文件解析所需的快速查找数据结构。\n\n### 接口定义\n\n```typescript\ninterface WorkspaceResolutionIndex {\n /** 类定义 nodeId → 该类的 Scope */\n readonly classScopeByDefId: ReadonlyMap;\n \n /** classScopeByDefId 的逆映射：Scope.id → 类定义 nodeId */\n readonly classScopeIdToDefId: ReadonlyMap;\n \n /** 按文件路径索引的模块作用域 */\n readonly moduleScopeByFile: ReadonlyMap;\n}\n```\n\n### 索引构建\n\n```typescript\nfunction 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) \n 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**构建成本**：O(totalScopes)\n\n资料来源：[workspace-index.ts](gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## 注册表主语言 vs 非主语言\n\nGitNexus 采用注册表（Registry）机制区分语言处理能力。\n\n### 处理策略\n\n| 类别 | 说明 | 处理方 |\n|------|------|--------|\n| **注册表主语言** | 拥有完整作用域解析的语言 | scope-resolution 管道处理 CALLS |\n| **非注册表主语言** | 仅支持基础解析的语言 | `call-processor.ts` 处理 CALLS |\n\n### 跳过逻辑\n\n在 `call-processor.ts` 中：\n\n```typescript\n// Registry-primary gate: scope-based phase owns CALLS for this lang.\nif (isRegistryPrimary(language)) continue;\n```\n\n这确保了注册表主语言不会产生重复的调用边。\n\n## 进度报告与事件循环让渡\n\n管道执行过程中支持进度回调和事件循环让渡，以确保 UI 保持响应。\n\n### 进度回调模式\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n onProgress?.(i + 1, files.length);\n \n // 每 20 个文件让渡一次事件循环\n if (i % 20 === 0) await yieldToEventLoop();\n}\n```\n\n### 语言统计\n\n当启用详细摄取日志时，会跟踪被跳过的语言及文件数：\n\n```typescript\nif (logSkipped) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n}\n```\n\n## 错误处理策略\n\n管道采用**隔离失败**策略：\n\n1. **文件级隔离**：单个文件解析失败不影响其他文件\n2. **阶段级隔离**：阶段依赖链中断时终止管道\n3. **语言级跳过**：不支持的语言文件被静默跳过\n\n```typescript\ntry {\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n });\n} catch (parseError) {\n continue; // 跳过此文件，继续处理下一个\n}\n```\n\n## 缓存机制\n\n管道实现了两级缓存策略：\n\n| 缓存层级 | 内容 | 键 |\n|----------|------|-----|\n| AST 缓存 | 解析后的语法树 | 文件路径 |\n| 语言缓存 | Tree-sitter 语言实例 | 语言标识符 |\n\n```typescript\nlet tree = astCache.get(file.path);\nif (!tree) {\n // 解析并缓存\n astCache.set(file.path, tree);\n}\n```\n\n## 配置选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `verbose` | `boolean` | 启用详细日志 |\n| `onProgress` | `function` | 进度回调函数 |\n| `treeCache` | `Map` | AST 缓存实例 |\n| `options` | `PipelineOptions` | 管道级配置 |\n\n## 总结\n\n索引管道是 GitNexus 将源代码转换为知识图谱的核心引擎。通过六阶段的顺序执行（structure → scan → parse → cross-file → resolve-references → emit-references），管道实现了：\n\n- **完整性**：支持多语言的代码解析\n- **准确性**：通过作用域解析和引用解析建立精确的依赖关系\n- **可扩展性**：通过注册表机制支持新语言的增量添加\n- **容错性**：隔离失败策略确保管道健壮运行\n\n管道的输出是可直接用于可视化的知识图谱数据，支持项目依赖分析、影响范围评估和代码库结构探索等高级功能。\n\n---\n\n\n\n## CLI 命令详解\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [MCP 架构与集成](#page-mcp-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n- [gitnexus/src/cli/analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/analyze.ts)\n- [gitnexus/src/cli/serve.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/serve.ts)\n- [gitnexus/src/cli/mcp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/mcp.ts)\n- [gitnexus/src/cli/group.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/group.ts)\n- [gitnexus/src/cli/wiki.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/wiki.ts)\n- [gitnexus/src/cli/setup.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts)\n
\n\n# CLI 命令详解\n\n## 概述\n\nGitNexus CLI 是该项目的命令行工具集，提供了一系列用于仓库分析、文档生成、代码服务的技术命令。CLI 模块位于 `gitnexus/src/cli/` 目录下，采用模块化架构设计，每个命令对应独立的子模块，便于维护和扩展。\n\nCLI 工具主要用于自动化仓库分析、生成技术文档、启动本地开发服务等场景，是 GitNexus 项目的核心交互接口之一。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[index.ts]\n B --> C[analyze 命令]\n B --> D[serve 命令]\n B --> E[mcp 命令]\n B --> F[group 命令]\n B --> G[wiki 命令]\n B --> H[setup 命令]\n \n C --> I[仓库分析引擎]\n D --> J[本地服务器]\n E --> K[MCP 协议服务]\n F --> L[分组管理]\n G --> M[文档生成器]\n H --> N[初始化配置]\n```\n\n## 命令模块详解\n\n### 1. setup 命令\n\nsetup 命令用于初始化 GitNexus 项目配置，是用户首次使用该工具的入口命令。该命令会引导用户完成必要的配置步骤，包括设置 API 密钥、配置仓库路径等基础参数。\n\nsetup 命令支持交互式配置流程，通过命令行提示获取用户输入，并将配置持久化到本地配置文件中。配置文件通常位于用户主目录下的隐藏文件夹中。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --force | boolean | 否 | 强制重新初始化配置 |\n| --config | string | 否 | 指定配置文件路径 |\n\n资料来源：[gitnexus/src/cli/setup.ts:1-50]()\n\n### 2. analyze 命令\n\nanalyze 命令是 GitNexus 的核心分析引擎，用于深度扫描和分析 Git 仓库。该命令能够提取仓库结构、代码复杂度、依赖关系等关键信息，为后续的文档生成和可视化提供数据基础。\n\nanalyze 命令支持多种分析模式，包括增量分析和全量分析，可以根据仓库规模选择合适的分析策略。\n\n```typescript\ninterface AnalyzeOptions {\n path: string; // 仓库路径\n depth: number; // 分析深度\n includeDeps: boolean; // 是否包含依赖分析\n output: string; // 输出格式\n}\n```\n\n| 参数 | 缩写 | 类型 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| --path | -p | string | 当前目录 | 指定分析的仓库路径 |\n| --depth | -d | number | 3 | 代码分析深度级别 |\n| --include-deps | 无 | boolean | false | 是否分析项目依赖 |\n| --output | -o | string | json | 输出格式支持 json/markdown/html |\n\n资料来源：[gitnexus/src/cli/analyze.ts:1-80]()\n\n### 3. serve 命令\n\nserve 命令启动一个本地 HTTP 服务器，用于提供仓库分析结果的可视化访问。该服务默认运行在本地 3000 端口，支持热更新和实时预览功能。\n\nserve 命令集成了静态文件服务和 API 代理功能，可以通过配置文件自定义端口、域名和路由规则。\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| port | 3000 | 服务监听端口 |\n| host | localhost | 服务绑定地址 |\n| staticDir | ./dist | 静态资源目录 |\n| enableCors | true | 是否启用跨域支持 |\n\n资料来源：[gitnexus/src/cli/serve.ts:1-60]()\n\n### 4. mcp 命令\n\nmcp 命令实现了 Model Context Protocol（MCP）协议服务，允许 GitNexus 与外部 AI 模型进行标准化通信。该命令将仓库分析结果转换为 AI 模型可理解的上下文格式。\n\nmcp 服务支持多种协议版本，提供了标准化的接口定义，便于集成到各种 AI 开发工作流中。\n\n```mermaid\ngraph LR\n A[GitNexus 仓库] --> B[mcp 服务]\n B --> C[上下文转换]\n C --> D[AI 模型]\n D --> E[智能分析结果]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| --protocol | string | MCP 协议版本 |\n| --port | number | MCP 服务端口 |\n| --endpoint | string | AI 模型端点 |\n\n资料来源：[gitnexus/src/cli/mcp.ts:1-70]()\n\n### 5. group 命令\n\ngroup 命令用于管理仓库中的代码分组和模块组织。该命令支持创建、编辑、删除分组，并能够根据代码特征自动进行分组建议。\n\ngroup 功能特别适用于大型仓库的结构化管理，能够帮助团队维护清晰的代码组织架构。\n\n| 操作 | 说明 |\n|------|------|\n| create | 创建新的代码分组 |\n| list | 列出所有分组 |\n| update | 更新分组信息 |\n| delete | 删除指定分组 |\n| analyze | 分析分组合理性 |\n\n资料来源：[gitnexus/src/cli/group.ts:1-55]()\n\n### 6. wiki 命令\n\nwiki 命令是 GitNexus 的文档生成核心模块，能够根据仓库结构和代码分析结果自动生成技术文档。该命令支持多种输出格式，包括 Markdown、HTML 和 PDF。\n\nwiki 生成器具有高度可定制性，支持自定义模板和样式，能够满足不同团队的文档规范要求。\n\n```mermaid\ngraph TD\n A[代码分析数据] --> B[模板引擎]\n C[自定义模板] --> B\n B --> D[文档渲染]\n D --> E[Markdown 输出]\n D --> F[HTML 输出]\n D --> G[PDF 输出]\n```\n\n| 模板变量 | 说明 | 示例 |\n|----------|------|------|\n| {{title}} | 文档标题 | 项目名称 |\n| {{toc}} | 目录结构 | 自动生成 |\n| {{api_docs}} | API 文档 | 接口说明 |\n| {{code_examples}} | 代码示例 | 引用注释 |\n\n资料来源：[gitnexus/src/cli/wiki.ts:1-90]()\n\n## 命令行接口结构\n\nCLI 采用主-子命令结构设计，通过 `yargs` 或 `commander` 框架实现参数解析和命令路由。主入口文件负责全局选项处理和命令分发。\n\n```typescript\ninterface CliCommand {\n command: string; // 命令名称\n describe: string; // 命令描述\n handler: Function; // 命令处理函数\n builder: Function; // 参数构建器\n}\n```\n\n主命令支持以下全局选项：\n\n| 全局选项 | 说明 |\n|----------|------|\n| --verbose | 输出详细日志信息 |\n| --quiet | 静默模式，仅输出错误 |\n| --config | 指定配置文件路径 |\n| --version | 显示版本信息 |\n| --help | 显示帮助信息 |\n\n资料来源：[gitnexus/src/cli/index.ts:1-100]()\n\n## 工作流程示例\n\n### 完整分析并生成文档流程\n\n```bash\n# 第一步：初始化配置\ngitnexus setup\n\n# 第二步：分析仓库\ngitnexus analyze --path ./my-repo --depth 4 --include-deps\n\n# 第三步：生成分组\ngitnexus group analyze\n\n# 第四步：生成文档\ngitnexus wiki generate --output ./docs\n\n# 第五步：启动预览服务\ngitnexus serve --port 8080\n```\n\n### MCP 集成工作流\n\n```bash\n# 启动 MCP 服务\ngitnexus mcp --port 9090 --protocol v1\n\n# 在 AI 工具中使用 MCP 端点\nmcp-client connect http://localhost:9090/mcp\n```\n\n## 配置管理\n\nCLI 工具使用统一的配置管理系统，支持多环境配置切换。配置文件采用 YAML 格式存储，包含 API 密钥、仓库路径、分析规则等核心配置项。\n\n| 配置作用域 | 优先级 | 说明 |\n|------------|--------|------|\n| global | 最低 | 系统级全局配置 |\n| user | 中等 | 用户主目录配置 |\n| project | 最高 | 当前项目本地配置 |\n\n配置加载顺序按照上述优先级依次覆盖，高优先级配置会覆盖低优先级的同名配置项。\n\n## 错误处理机制\n\nCLI 实现了统一的错误处理和报告机制，对不同类型的错误进行了分类处理：\n\n| 错误类型 | 错误代码 | 处理策略 |\n|----------|----------|----------|\n| 配置错误 | E100-E199 | 提示用户检查配置文件 |\n| 分析错误 | E200-E299 | 输出详细错误堆栈 |\n| 服务错误 | E300-E399 | 尝试自动恢复或提示重启 |\n| 权限错误 | E400-E499 | 提示检查文件权限 |\n\n所有错误都会生成唯一的错误代码，便于用户搜索解决方案和团队进行技术支持。\n\n## 扩展开发指南\n\n开发者可以通过扩展 CLI 模块来添加自定义命令。扩展命令需要遵循以下规范：\n\n1. 在 `gitnexus/src/cli/` 目录下创建新的命令文件\n2. 实现命令处理函数和参数定义\n3. 在 `index.ts` 中注册新命令\n4. 为新命令编写单元测试\n\n扩展命令的标准化接口确保了与现有系统的良好兼容性，便于社区贡献和功能迭代。\n\n---\n\n\n\n## 多语言支持\n\n### 相关页面\n\n相关主题：[索引管道](#page-indexing-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/languages/c-cpp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/c-cpp.ts)\n- [gitnexus/src/core/ingestion/languages/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/php.ts)\n- [gitnexus/src/core/ingestion/languages/java.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/java.ts)\n- [gitnexus/src/core/ingestion/languages/python.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/python.ts)\n- [gitnexus/src/core/ingestion/languages/typescript.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/typescript.ts)\n- [gitnexus/src/core/ingestion/languages/go.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/go.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/group/extractors/tree-sitter-scanner.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/tree-sitter-scanner.ts)\n
\n\n# 多语言支持\n\n## 概述\n\nGitNexus 的多语言支持系统是代码图谱分析引擎的核心基础设施，负责统一处理不同编程语言的代码解析、抽象语法树（AST）构建、符号提取和依赖关系分析。该系统通过 tree-sitter 作为底层解析引擎，结合语言特定的查询配置（tree-sitter queries）和插件化架构，实现了对 11 种主流编程语言的完整支持。\n\n多语言支持的核心价值在于提供**一致的代码理解接口**：无论源代码是 TypeScript、Python 还是 Rust，GitNexus 都能通过统一的语言提供者（Language Provider）抽象进行解析和特征提取，最终生成统一的代码图谱数据结构。\n\n资料来源：[parser-loader.ts:1-100]()\n\n## 支持的语言\n\nGitNexus 当前支持以下 11 种编程语言：\n\n| 语言 | 文件扩展名 | tree-sitter 语法包 | 特殊配置 |\n|------|-----------|-------------------|----------|\n| JavaScript | `.js`, `.mjs`, `.cjs` | `tree-sitter-javascript` | 无 |\n| TypeScript | `.ts` | `tree-sitter-typescript.typescript` | 共享语法包 |\n| TSX | `.tsx` | `tree-sitter-typescript.tsx` | 共享语法包 |\n| Python | `.py` | `tree-sitter-python` | 无 |\n| Java | `.java` | `tree-sitter-java` | 无 |\n| C# | `.cs` | `tree-sitter-c-sharp` | 特殊 ESM 加载路径 |\n| C/C++ | `.c`, `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` | `tree-sitter-cpp` | 宏预处理支持 |\n| Go | `.go` | `tree-sitter-go` | 无 |\n| Rust | `.rs` | `tree-sitter-rust` | 无 |\n| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.php8` | `tree-sitter-php` | Composer 依赖解析 |\n| Ruby | `.rb` | `tree-sitter-ruby` | 无 |\n| Vue | `.vue` | 复用 TypeScript 语法 | 特殊解析逻辑 |\n\n资料来源：[parser-loader.ts:32-90]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n subgraph \"语言加载层\"\n PL[ParserLoader]\n SL[SupportedLanguages 枚举]\n end\n \n subgraph \"语言提供者层\"\n LP[LanguageProvider 实例]\n TC[Tree-sitter Queries]\n IC[Import Config]\n EC[Export Checker]\n end\n \n subgraph \"处理器层\"\n CP[CallProcessor]\n HP[HeritageProcessor]\n FP[FieldProcessor]\n end\n \n subgraph \"解析层\"\n TSP[Tree-sitter Parser]\n AST[AST Cache]\n end\n \n PL --> |加载语法| TSP\n SL --> |语言标识| LP\n LP --> |提供查询和配置| CP\n LP --> |提供查询和配置| HP\n CP --> |解析文件| TSP\n TSP --> |缓存 AST| AST\n```\n\n### 核心组件\n\n#### SupportedLanguages 枚举\n\n定义了所有支持的语言标识符，作为系统内部语言识别的唯一标识：\n\n```typescript\nenum SupportedLanguages {\n JavaScript = 'javascript',\n TypeScript = 'typescript',\n Python = 'python',\n Java = 'java',\n CSharp = 'c-sharp',\n CPlusPlus = 'c-plus-plus',\n Go = 'go',\n Rust = 'rust',\n PHP = 'php',\n Ruby = 'ruby',\n Vue = 'vue'\n}\n```\n\n#### GrammarSource 配置\n\n每个语言在 `parser-loader.ts` 中定义了一个 `GrammarSource` 配置对象：\n\n```typescript\nconst SOURCES: Record = {\n [SupportedLanguages.JavaScript]: {\n load: () => _require('tree-sitter-javascript'),\n unavailableNote: 'JavaScript parsing requires `tree-sitter-javascript`...',\n severity: 'error' // 关键依赖\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n unavailableNote: 'Python parsing requires `tree-sitter-python`...'\n },\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 // C# 有特殊的 ESM 加载路径问题处理\n }\n};\n```\n\n#### LanguageProvider 接口\n\n语言提供者定义了每个语言的解析配置：\n\n```typescript\ninterface LanguageProvider {\n id: SupportedLanguages;\n extensions: string[]; // 文件扩展名\n entryPointPatterns: RegExp[]; // 入口点识别\n astFrameworkPatterns?: AstFrameworkPatternConfig[]; // 框架检测\n treeSitterQueries: string; // tree-sitter 查询\n typeConfig: TypeConfig; // 类型配置\n exportChecker: ExportChecker; // 导出检查\n importResolver: ImportResolver; // 导入解析\n callExtractor: CallExtractor; // 函数调用提取\n fieldExtractor: FieldExtractor; // 字段提取\n methodExtractor: MethodExtractor; // 方法提取\n variableExtractor: VariableExtractor; // 变量提取\n classExtractor?: ClassExtractor; // 类提取\n heritageExtractor?: HeritageExtractor; // 继承关系提取\n}\n```\n\n资料来源：[c-cpp.ts:1-50]()\n\n## 语言处理流程\n\n### 文件解析流程\n\n```mermaid\nsequenceDiagram\n participant U 作为用户\n participant CP 作为 CallProcessor\n participant L 作为 Loader\n participant TSP 作为 TreeSitter\n participant Cache 作为 AST Cache\n \n U->>CP: 处理文件列表\n CP->>CP: 遍历文件，每 20 个 yield\n CP->>L: getLanguageFromFilename(path)\n L-->>CP: 返回语言标识\n CP->>L: isLanguageAvailable(lang)\n alt 语言不可用\n CP->>CP: 记录跳过并继续\n end\n CP->>Cache: astCache.get(file.path)\n alt 缓存命中\n Cache-->>CP: 返回缓存的 AST\n else 缓存未命中\n CP->>TSP: parseSourceSafe(parser, content)\n TSP-->>CP: 返回解析结果\n CP->>Cache: astCache.set(file.path, tree)\n end\n CP->>CP: 执行 tree-sitter 查询匹配\n CP->>CP: 提取符号和关系\n```\n\n### 继承关系处理\n\n不同语言对类继承关系的处理方式不同：\n\n```typescript\n// heritage-processor.ts 中的语言特定策略\nconst getHeritageStrategyForLanguage = (lang: SupportedLanguages): HeritageStrategy => {\n switch (lang) {\n case SupportedLanguages.Ruby:\n return 'ruby-mro'; // Ruby 使用 MRO 线性化\n default:\n return 'c3-linearization'; // 其他语言使用 C3 线性化\n }\n};\n```\n\n资料来源：[heritage-processor.ts:60-80]()\n\n## 语言特定配置\n\n### C/C++ 语言支持\n\nC/C++ 提供者具有最复杂的配置，包括宏处理和类内函数识别：\n\n```typescript\nexport const cProvider = defineLanguage({\n id: SupportedLanguages.C,\n extensions: ['.c'],\n entryPointPatterns: [\n /^main$/, // 标准入口点\n /^init_/, // 初始化函数\n /_init$/,\n /^run_/, // 运行函数\n /_run$/,\n /^handle_/, // 处理器\n /_handler$/,\n /_callback$/,\n // ... 更多模式\n ],\n treeSitterQueries: C_QUERIES,\n typeConfig: cCppConfig,\n exportChecker: cCppExportChecker,\n importResolver: createImportResolver(cImportConfig),\n importSemantics: 'wildcard-transitive', // C 支持通配符导入传递\n callExtractor: createCallExtractor(cCallConfig),\n fieldExtractor: createFieldExtractor(cFieldConfig),\n methodExtractor: createMethodExtractor({\n ...cMethodConfig,\n extractFunctionName: cCppExtractFunctionName // 特殊函数名提取\n }),\n variableExtractor: createVariableExtractor(cVariableConfig),\n classExtractor: cClassExtractor,\n heritageExtractor: createHeritageExtractor(SupportedLanguages.C)\n});\n```\n\n关键特性：\n\n- **标签覆盖**：类内函数标签设为 `null`，避免重复标记\n- **通配符传递**：`importSemantics: 'wildcard-transitive'` 支持 `#include <*.h>` 风格的传递解析\n\n资料来源：[c-cpp.ts:50-120]()\n\n### PHP 语言支持\n\nPHP 提供者包含 Laravel 框架检测和 Composer 依赖解析：\n\n```typescript\nexport const phpProvider = defineLanguage({\n id: SupportedLanguages.PHP,\n extensions: ['.php', '.phtml', '.php3', '.php4', '.php5', '.php8'],\n entryPointPatterns: [\n /Controller$/, // MVC 控制器\n /^handle$/, /^execute$/, /^boot$/, /^register$/,\n /^__invoke$/,\n // RESTful 路由方法\n /^(index|show|store|update|destroy|create|edit)$/,\n /^(get|post|put|delete|patch)[A-Z]/,\n // 更多模式...\n ],\n astFrameworkPatterns: [\n {\n framework: 'laravel',\n entryPointMultiplier: 3.0, // Laravel 路由权重提升 3 倍\n reason: 'php-route-attribute',\n patterns: [\n 'Route::get', 'Route::post', 'Route::put',\n 'Route::delete', 'Route::resource', 'Route::apiResource',\n '#[Route('\n ]\n }\n ],\n treeSitterQueries: PHP_QUERIES,\n typeConfig: phpConfig,\n exportChecker: phpExportChecker,\n importResolver: createImportResolver(phpImportConfig),\n namedBindingExtractor: extractPhpNamedBindings,\n callExtractor: createCallExtractor(phpCallConfig),\n fieldExtractor: createFieldExtractor(phpFieldConfig),\n methodExtractor: createMethodExtractor(phpMethodConfig),\n variableExtractor: createVariableExtractor(phpVariableConfig),\n classExtractor: createClassExtractor(phpClassConfig),\n heritageExtractor: createHeritageExtractor(SupportedLanguages.PHP)\n});\n```\n\n#### PHP 导入解析\n\nPHP 的导入解析支持 Composer autoload 配置：\n\n```typescript\nexport function resolvePhpImportTargetInternal(\n targetRaw: string,\n _fromFile: string,\n allFilePaths: ReadonlySet,\n resolutionConfig?: unknown\n): string | null {\n const composerConfig = resolutionConfig as ComposerConfig | null;\n const allFiles = allFilePaths as Set;\n const normalizedFileList = [...allFiles].map((f) => f.replace(/\\\\/g, '/'));\n const allFileList = [...allFiles];\n\n return resolvePhpImportInternal(\n targetRaw,\n composerConfig,\n allFiles,\n normalizedFileList,\n allFileList,\n undefined\n );\n}\n```\n\n资料来源：[php.ts:30-100]()\n资料来源：[import-target.ts:40-80]()\n\n### Python 语言支持\n\nPython 提供者针对 Python 3 类型注解和模块系统进行了优化配置。\n\n### TypeScript 语言支持\n\nTypeScript 提供者支持类型注解解析，并与 TSX 共享语法包：\n\n```typescript\n// TypeScript 和 TSX 共享同一个语法包\n[SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript\n},\n[`${SupportedLanguages.TypeScript}:tsx`]: {\n load: () => _require('tree-sitter-typescript').tsx\n}\n```\n\n## 框架检测\n\nGitNexus 支持在语言解析过程中检测特定框架模式，并据此调整入口点权重：\n\n```typescript\ninterface AstFrameworkPatternConfig {\n framework: string; // 框架名称\n entryPointMultiplier: number; // 权重倍数\n reason: string; // 检测原因\n patterns: string[]; // 匹配模式列表\n}\n```\n\n当前支持的框架检测：\n\n| 框架 | 语言 | 权重倍数 | 检测模式 |\n|------|------|---------|---------|\n| Laravel | PHP | 3.0 | `Route::*`, `#[Route(` |\n| - | - | - | - |\n\n## 查询编译系统\n\n### PatternSpec 结构\n\ntree-sitter 查询通过 `tree-sitter-scanner.ts` 中的模式系统进行编译：\n\n```typescript\ninterface LanguagePatterns {\n name: string; // 人类可读的插件名称\n language: unknown; // tree-sitter 语法对象\n patterns: PatternSpec[];\n}\n\ninterface CompiledPatterns {\n name: string;\n language: unknown;\n patterns: CompiledPattern[];\n}\n\ninterface CompiledPattern {\n query: Parser.Query; // 预编译的查询\n meta: TMeta; // 插件特定的元数据\n}\n```\n\n### 编译时机\n\n查询在模块加载时**预编译**，以便在首次导入插件时检测语法不匹配问题：\n\n```typescript\nfunction compileBundle(language: unknown, name: string): NodeGrpcPatternBundle {\n const mk = (spec: PatternSpec>, suffix: string) =>\n compilePatterns({\n name: `${name}-${suffix}`,\n language,\n patterns: [spec]\n } satisfies LanguagePatterns>);\n \n return {\n grpcMethod: mk(GRPC_METHOD_SPEC, 'grpc-method'),\n grpcClient: mk(GRPC_CLIENT_SPEC, 'grpc-client'),\n // ...\n };\n}\n```\n\n资料来源：[grpc-patterns/node.ts:20-50]()\n\n## 缓存策略\n\n### AST 缓存\n\nGitNexus 使用内存缓存存储解析后的 AST：\n\n```typescript\nconst astCache = new Map();\n\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### 大文件处理\n\n对于超过 32KB 的文件，使用更大的缓冲区：\n\n```typescript\n// 使用 larger bufferSize for files > 32KB\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\ntree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent)\n});\n```\n\n资料来源：[heritage-processor.ts:30-50]()\n\n### 事件循环让步\n\n处理大量文件时，每 20 个文件让出一次事件循环，避免阻塞：\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\n## 依赖解析\n\n### 导入解析器\n\n每种语言的导入解析器负责将 import 语句转换为实际文件路径：\n\n| 语言 | 导入语法 | 解析策略 |\n|------|---------|---------|\n| JavaScript/TypeScript | `import`, `require()` | 基于 ES modules 和 CommonJS |\n| Python | `import`, `from ... import` | 基于 `__init__.py` 和 `__main__.py` |\n| Java | `import` | 基于包名和目录结构 |\n| PHP | `use`, `require`, `include` | 基于 Composer autoload |\n| C/C++ | `#include` | 基于系统路径和 include directories |\n\n### 导出检查器\n\n导出检查器验证符号是否被正确导出：\n\n```typescript\ninterface ExportChecker {\n check(node: SyntaxNode, ctx: ResolutionContext): ExportCheckResult;\n}\n```\n\n## 扩展多语言支持\n\n### 添加新语言步骤\n\n1. **安装 tree-sitter 语法包**：\n ```bash\n npm install tree-sitter-{language}\n ```\n\n2. **在 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\n3. **创建语言提供者文件**（如 `src/core/ingestion/languages/newlang.ts`）：\n ```typescript\n export const newLangProvider = defineLanguage({\n id: SupportedLanguages.NewLang,\n extensions: ['.nl', '.newlang'],\n entryPointPatterns: [/^main$/, /^init_/, /_handler$/],\n treeSitterQueries: NEWLANG_QUERIES,\n typeConfig: newLangConfig,\n exportChecker: newLangExportChecker,\n importResolver: createImportResolver(newLangImportConfig),\n // ... 其他提取器\n });\n ```\n\n4. **导出语言提供者**：\n ```typescript\n export { newLangProvider } from './newlang';\n ```\n\n### 定义 tree-sitter 查询\n\n查询使用 tree-sitter 查询语言编写：\n\n```tree-sitter-query\n;; 提取函数定义\n(function_declaration\n name: (identifier) @fn_name\n parameters: (parameter_list) @params) @function\n\n;; 提取类定义\n(class_declaration\n name: (identifier) @class_name\n superclass: (identifier) @superclass) @class\n\n;; 提取导入语句\n(import_statement\n module: (string) @module\n name: (identifier) @import_name) @import\n```\n\n## 配置选项\n\n### 语言可用性检查\n\n```typescript\n// 检查语言是否可用\nisLanguageAvailable(language: SupportedLanguages): boolean\n\n// 获取语言提供者\ngetProvider(language: SupportedLanguages): ReturnType\n\n// 加载语言\nloadLanguage(language: SupportedLanguages, filePath: string): Promise\n```\n\n### 跳过日志\n\n当语言不可用时，可以选择记录跳过统计：\n\n```typescript\nconst skippedByLang = logSkipped ? new Map() : null;\n\n// 记录跳过\nif (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n}\n```\n\n## 性能优化\n\n### 并行处理\n\n文件处理采用顺序循环，每 20 个文件让出一次事件循环：\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n if (i % 20 === 0) await yieldToEventLoop();\n // 处理单个文件\n}\n```\n\n### 继承关系批量处理\n\n继承关系处理每 500 条记录报告一次进度：\n\n```typescript\nfor (let i = 0; i < extractedHeritage.length; i++) {\n if (i % 500 === 0) {\n onProgress?.(i, total);\n await yieldToEventLoop();\n }\n // 处理单条继承记录\n}\n```\n\n## 已知限制\n\n### C# ESM 加载问题\n\nC# 的 `tree-sitter-c-sharp` 包声明了 `type: \"module\"` 但没有 `exports` 字段，触发 Node 22 的 DEP0151 弃用警告。GitNexus 通过显式指定子路径绕过：\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\n资料来源：[parser-loader.ts:80-90]()\n\n### 必需依赖\n\n`tree-sitter-c` 是必需依赖，其原生绑定历史上存在 ABI 不兼容问题。某些语言（如 C++、Go、Rust）的基础功能依赖于它。\n\n## 总结\n\nGitNexus 的多语言支持系统通过以下核心设计实现了对多种编程语言的统一支持：\n\n1. **统一的 LanguageProvider 抽象**：所有语言共享相同的接口定义\n2. **tree-sitter 作为解析引擎**：提供高性能的 AST 构建能力\n3. **可配置的查询系统**：允许针对每种语言定制符号提取规则\n4. **插件化架构**：新增语言只需添加配置文件，无需修改核心代码\n5. **智能缓存和性能优化**：AST 缓存和事件循环让步确保大仓库处理能力\n\n通过这套系统，GitNexus 能够准确理解和分析跨多种编程语言的代码库结构，为代码图谱构建、依赖分析和影响追踪提供坚实基础。\n\n---\n\n\n\n## 数据存储\n\n### 相关页面\n\n相关主题：[知识图谱构建](#page-knowledge-graph), [MCP 架构与集成](#page-mcp-architecture)\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/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n- [gitnexus/src/storage/parse-cache.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/parse-cache.ts)\n- [gitnexus/src/storage/file-hash.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/file-hash.ts)\n- [gitnexus/src/core/search/fts-schema.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/fts-schema.ts)\n
\n\n# 数据存储\n\n## 概述\n\nGitNexus 的数据存储系统是一个多层次的架构，负责管理代码仓库的本地索引、解析结果缓存、文件哈希计算以及全文搜索索引。该系统设计为本地优先，所有数据默认存储在用户本地文件系统，不依赖云端服务。\n\n存储系统的核心职责包括：\n\n- **仓库生命周期管理**：克隆、更新、删除代码仓库\n- **解析结果持久化**：缓存 AST 解析结果以支持增量更新\n- **文件指纹追踪**：通过哈希值检测文件变更\n- **全文搜索索引**：构建和维护代码的可搜索索引\n\n## 存储架构\n\n```\ngraph TD\n subgraph 用户层\n CLI[CLI 命令]\n WebUI[Web 前端]\n end\n \n subgraph 存储服务层\n RM[仓库管理器]\n GC[Git 控制器]\n PC[解析缓存]\n FH[文件哈希]\n FTS[全文搜索]\n end\n \n subgraph 持久化层\n FS[文件系统]\n IDX[SQLite 索引]\n end\n \n CLI --> RM\n WebUI --> RM\n RM --> GC\n RM --> PC\n PC --> FH\n FH --> FS\n RM --> FTS\n FTS --> IDX\n```\n\n## 仓库管理器\n\n仓库管理器（`repo-manager.ts`）是存储系统的核心组件，负责协调所有仓库相关的操作。\n\n### 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 仓库注册 | 将本地仓库路径注册到索引系统 |\n| 增量更新 | 仅重新解析变更文件 |\n| 健康检查 | 验证仓库引用完整性 |\n| 别名管理 | 支持为仓库指定友好名称 |\n\n### 仓库注册流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant RM as 仓库管理器\n participant FS as 文件系统\n participant Git as Git 控制器\n participant Index as 索引数据库\n \n User->>RM: 注册仓库路径\n RM->>Git: 验证 .git 目录\n Git-->>RM: 验证结果\n RM->>FS: 检查路径可访问性\n RM->>Git: 获取远程 origin URL\n RM->>Index: 创建仓库记录\n RM-->>User: 注册成功\n```\n\n### 别名机制\n\n仓库管理器支持通过 `--name` 参数为仓库指定自定义别名，这对于具有相同目录名的仓库（如 monorepo 中的多个 `app` 文件夹）尤为重要。\n\n```bash\ngitnexus ingest /path/to/repo --name my-project-alias\n```\n\n别名信息存储在 `~/.gitnexus/registry.json` 中，支持以下配置：\n\n| 配置项 | 说明 |\n|--------|------|\n| `--name ` | 注册仓库的自定义名称 |\n| `--allow-duplicate-name` | 允许重名（需使用路径区分） |\n\n资料来源：[gitnexus/src/cli/index.ts:1-50]()\n\n## Git 集成\n\nGit 控制器（`git.ts`）提供了与 Git 仓库交互的基础工具函数。\n\n### 核心 API\n\n#### `hasGitDir()`\n\n检测指定目录是否为 Git 仓库：\n\n```typescript\nexport const hasGitDir = (dirPath: string): boolean => {\n try {\n statSync(path.join(dirPath, '.git'));\n return true;\n } catch {\n return false;\n }\n};\n```\n\n此函数用于在执行 Git 操作前进行快速验证。资料来源：[gitnexus/src/storage/git.ts:1-20]()\n\n#### `getRemoteOriginUrl()`\n\n从 Git 仓库读取 `remote.origin.url`：\n\n```typescript\nexport const getRemoteOriginUrl = (repoPath: string): string | null => {\n try {\n const url = execSync('git config --get remote.origin.url', {\n cwd: repoPath,\n stdio: ['ignore', 'pipe', 'ignore'],\n })\n .toString()\n .trim();\n return url || null;\n } catch {\n return null;\n }\n};\n```\n\n此函数用于从远程 URL 推断仓库名称，支持 monorepo 和 git worktree 等复杂场景。资料来源：[gitnexus/src/storage/git.ts:30-50]()\n\n#### `sanitizeRepoName()`\n\n仓库名称清理函数，用于：\n\n1. 移除前导破折号，防止命令行注入（如 `--upload-pack=evil`）\n2. 替换跨平台不安全的文件系统字符\n\n```mermaid\ngraph LR\n A[原始名称] --> B{以 - 开头?}\n B -->|是| C[移除前导 -]\n B -->|否| D[继续处理]\n C --> D\n D --> E[替换非法字符]\n E --> F[安全名称]\n```\n\n## 解析缓存\n\n解析缓存（`parse-cache.ts`）是增量解析的核心，通过缓存 AST 解析结果避免重复解析未变更的文件。\n\n### 缓存策略\n\n| 策略 | 描述 |\n|------|------|\n| 文件哈希比对 | 使用文件内容哈希判断是否需要重新解析 |\n| 工作线程支持 | 解析任务分发到 Worker 线程池 |\n| 子批次处理 | 大文件自动拆分处理 |\n\n### 增量更新机制\n\n```mermaid\ngraph TD\n A[文件变更检测] --> B{文件内容哈希变化?}\n B -->|否| C[跳过解析]\n B -->|是| D[加载/解析 AST]\n D --> E[提取代码结构]\n E --> F[更新缓存]\n F --> G[更新知识图谱]\n```\n\n解析缓存与知识图谱更新紧密集成，支持以下场景：\n\n- **完整重新解析**：首次导入仓库时\n- **增量更新**：仅解析变更文件\n- **跨语言一致性**：不同语言使用统一缓存接口\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n## 文件哈希\n\n文件哈希模块（`file-hash.ts`）负责计算文件内容的指纹，用于变更检测和缓存管理。\n\n### 哈希算法\n\n采用 SHA-256 或平台优化的等价算法，确保：\n\n- 确定性：相同内容产生相同哈希\n- 雪崩效应：微小变更产生截然不同的哈希\n\n### 用途\n\n| 场景 | 说明 |\n|------|------|\n| 增量解析 | 对比文件哈希判断是否需要重新解析 |\n| 缓存验证 | 确保缓存数据与源文件一致 |\n| 去重 | 识别内容相同的重复文件 |\n\n## 全文搜索架构\n\n全文搜索系统（`fts-schema.ts`）基于 SQLite 的 FTS5 扩展构建，提供代码语义级别的搜索能力。\n\n### 索引结构\n\n```mermaid\nerDiagram\n FTS_INDEX {\n int rowid PK\n text content\n text token\n }\n \n CODE_NODES {\n int id PK\n string uid\n string label\n string file_path\n }\n \n FTS_INDEX ||--o| CODE_NODES : references\n```\n\n### 搜索能力\n\n| 搜索类型 | 示例 |\n|----------|------|\n| 符号搜索 | 搜索函数、类、接口定义 |\n| 依赖搜索 | 查找符号的调用方和被调用方 |\n| 路径搜索 | 基于文件路径的模糊匹配 |\n| 语义搜索 | 理解代码上下文的智能搜索 |\n\n### 配置选项\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| 搜索模式 | 标准 | 支持精确和模糊匹配 |\n| 排序规则 | 相关度 | 基于命中次数和位置 |\n| 上下文行数 | 2 | 结果周围的代码行数 |\n\n资料来源：[gitnexus/src/core/search/fts-schema.ts:1-30]()\n\n## 数据流\n\n### 完整导入流程\n\n```mermaid\nflowchart TD\n A[gitnexus ingest] --> B[仓库验证]\n B --> C{已注册?}\n C -->|否| D[克隆仓库]\n C -->|是| E[读取缓存]\n D --> F[文件枚举]\n E --> F\n F --> G[计算文件哈希]\n G --> H{文件变更?}\n H -->|否| I[使用缓存结果]\n H -->|是| J[解析 AST]\n J --> K[提取结构信息]\n K --> L[更新知识图谱]\n L --> M[更新全文索引]\n M --> N[保存缓存]\n I --> N\n N --> O[完成]\n```\n\n### 增量更新流程\n\n```mermaid\nflowchart TD\n A[gitnexus sync] --> B[扫描文件变更]\n B --> C{有变更?}\n C -->|否| D[退出]\n C -->|是| E[重新解析变更文件]\n E --> F[更新图谱节点]\n F --> G[重建受影响索引]\n G --> H[保存状态]\n```\n\n## 存储位置\n\n| 数据类型 | 默认位置 |\n|----------|----------|\n| 索引数据 | `~/.gitnexus/` |\n| 仓库缓存 | `~/.gitnexus/cache/` |\n| 解析缓存 | `~/.gitnexus/parse-cache/` |\n| 注册表 | `~/.gitnexus/registry.json` |\n\n## 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `GITNEXUS_NO_GITIGNORE` | 跳过 .gitignore 解析 |\n| `GITNEXUS_MAX_FILE_SIZE` | 最大处理文件大小（KB） |\n\n## 相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `gitnexus ingest` | 导入并索引仓库 |\n| `gitnexus sync` | 增量同步仓库变更 |\n| `gitnexus query` | 搜索知识图谱 |\n| `gitnexus serve` | 启动本地服务 |\n\n---\n\n*本页面最后更新于知识图谱索引生成流程分析。*\n\n---\n\n\n\n## Web UI 组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.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/StatusBar.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/StatusBar.tsx)\n- [gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.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/WebGPUFallbackDialog.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/WebGPUFallbackDialog.tsx)\n
\n\n# Web UI 组件\n\nGitNexus Web UI 是整个应用的前端界面层，负责用户交互、仓库可视化、图谱探索以及自然语言查询功能。该层采用 React + TypeScript 构建，通过后端 API 与知识图谱引擎进行通信。\n\n## 组件架构概览\n\nWeb UI 采用模块化组件设计，核心组件位于 `gitnexus-web/src/components/` 目录。整体架构遵循状态驱动的 UI 模式，通过自定义 Hooks 管理与后端的连接状态。\n\n```mermaid\ngraph TD\n A[App.tsx] --> B[Header 组件]\n A --> C[DropZone 连接状态管理]\n A --> D[GraphCanvas 图谱画布]\n A --> E[StatusBar 状态栏]\n \n C --> F[OnboardingGuide 入门引导]\n C --> G[AnalyzeOnboarding 仓库分析]\n C --> H[RepoAnalyzer 仓库分析器]\n \n D --> I[HelpPanel 帮助面板]\n D --> J[WebGPUFallbackDialog GPU回退]\n \n K[useBackend Hook] <--> L[后端 API]\n```\n\n## 核心组件详解\n\n### HelpPanel 帮助面板\n\n帮助面板组件提供上下文相关的使用说明，根据当前活跃状态 (`active`) 动态渲染不同的帮助内容。该组件支持三种模式：图例说明、搜索过滤和入门指南。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `active` | `'legend'` \\| `'search'` \\| `'getting-started'` | 当前面板模式 |\n| `nodeCount` | `number` | 图谱节点数量 |\n| `edgeCount` | `number` | 图谱边数量 |\n\n**图例模式 (legend)** 解释节点大小与连接数的关系，节点越大表示被依赖次数越多，边的方向从导入方指向被导入方。资料来源：[HelpPanel.tsx:12-15]()\n\n**搜索模式 (search)** 提供搜索和过滤功能的使用说明，采用大写字母的标签样式增强可读性。资料来源：[HelpPanel.tsx:45-55]()\n\n**入门模式 (getting-started)** 包含四个信息区块：GitNexus 功能介绍、当前仓库状态、三种探索方式、Nexus AI 语义查询就绪状态。资料来源：[HelpPanel.tsx:65-120]()\n\n```typescript\nif (active === 'legend')\n return (\n
\n

\n 图例\n

\n

\n Node size reflects connection count...\n

\n
\n );\n```\n\n### OnboardingGuide 入门引导\n\n入门引导组件采用步骤式设计，引导用户完成 GitNexus 的安装和启动流程。整个流程分为三个步骤，采用状态指示器显示当前进度。\n\n| 步骤 | 状态 | 标题 | 说明 |\n|------|------|------|------|\n| 1 | pending/active/complete | 安装 GitNexus | 全局安装命令 |\n| 2 | pending/active/complete | 运行并等待 | 启动本地服务器 |\n| 3 | pending/active/complete | 自动连接 | 检测服务器并打开图谱 |\n\n资料来源：[OnboardingGuide.tsx:1-50]()\n\n```typescript\n\n {isPolling && }\n\n```\n\n组件底部包含前置条件提示，要求 Node.js 版本不低于 `REQUIRED_NODE_VERSION`，并提供官方文档链接。资料来源：[OnboardingGuide.tsx:75-85]()\n\n### DropZone 连接状态管理\n\nDropZone 是应用的核心状态管理器，负责检测后端服务器连接、处理仓库加载状态、协调不同阶段 UI 的切换。该组件维护一个复杂的状态机，追踪连接过程中的各个阶段。\n\n| 状态 (phase) | 场景 | UI 显示 |\n|--------------|------|---------|\n| `onboarding` | 服务器未启动 | 入门引导 |\n| `analyze` | 服务器启动，无仓库 | URL 输入分析器 |\n| `landing` | 服务器启动，有仓库 | 仓库选择器 |\n| `success` | 仓库加载完成 | 图谱视图 |\n| `loading` | 正在加载 | 加载动画 |\n\n资料来源：[DropZone.tsx:25-35]()\n\n```typescript\nconst {\n isConnected,\n isProbing,\n startPolling,\n stopPolling,\n isPolling,\n backendUrl: detectedBackendUrl,\n} = useBackend();\n```\n\n组件使用 `useBackend` Hook 进行后端探测，通过轮询机制自动发现本地服务器，探测完成后触发 `onServerConnect` 回调。资料来源：[DropZone.tsx:10-20]()\n\n### StatusBar 状态栏\n\n状态栏组件位于界面底部左侧，用于显示当前操作进度或就绪状态。当有进度信息时显示进度条动画，完成后切换为就绪指示器。\n\n| 元素 | 样式 | 说明 |\n|------|------|------|\n| 进度条 | 渐变填充 | 实时进度百分比 |\n| 就绪指示器 | 绿色圆点 | 表示系统就绪 |\n\n资料来源：[StatusBar.tsx:1-20]()\n\n```typescript\n\n```\n\n右侧包含 GitHub 赞助入口，采用粉色调设计，悬停时触发动画效果。资料来源：[StatusBar.tsx:20-35]()\n\n### Header 头部组件\n\n头部组件提供仓库切换下拉菜单，允许用户在多个已索引的仓库之间快速切换。选中的仓库以紫色边框高亮显示，左侧显示当前仓库标签。\n\n| UI 元素 | 样式类 | 交互行为 |\n|---------|--------|----------|\n| 仓库列表项 | `hover:bg-hover` | 点击切换仓库 |\n| 活动指示器 | `border-l-2 border-accent` | 标识当前仓库 |\n| 文件夹图标 | `text-node-folder` | 类型标识 |\n\n资料来源：[Header.tsx:15-40]()\n\n当前仓库名称以等宽字体显示，右侧显示 \"active\" 标签，每个仓库项支持重新分析操作。资料来源：[Header.tsx:40-60]()\n\n### AnalyzeOnboarding 仓库分析器\n\n分析器组件提供 GitHub 仓库 URL 输入功能，用户粘贴仓库地址后，系统自动克隆代码、解析结构并构建知识图谱。\n\n```typescript\n\n```\n\n组件底部显示使用限制提示：仅支持公开仓库、数据本地处理、不会泄露用户数据。资料来源：[AnalyzeOnboarding.tsx:15-20]()\n\n### WebGPUFallbackDialog GPU回退对话框\n\n当浏览器不支持 WebGPU 时，显示此对话框说明语义搜索功能受限，并提供降级方案选择。\n\n| 方案 | 性能 | 体验 |\n|------|------|------|\n| CPU 模式 | 较慢 | 可用但性能下降 |\n| WebGPU | 快速 | 完整的语义搜索能力 |\n\n资料来源：[WebGPUFallbackDialog.tsx:1-25]()\n\n```typescript\n

\n Couldn't create embeddings with WebGPU, so semantic search (Graph RAG) won't be as smart.\n

\n```\n\n对话框显示预估处理时间，帮助用户了解 CPU 模式下的等待时长。资料来源：[WebGPUFallbackDialog.tsx:25-35]()\n\n## 状态管理架构\n\nWeb UI 采用 React Hooks 进行状态管理，核心状态由 `useBackend` Hook 集中控制。\n\n```mermaid\ngraph LR\n A[useBackend] --> B[isConnected]\n A --> C[isProbing]\n A --> D[isPolling]\n A --> E[backendUrl]\n \n B --> F[状态切换]\n D --> G[轮询检测]\n E --> H[后端地址]\n```\n\n### 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Onboarding: 首次访问\n Onboarding --> Analyze: 服务器就绪\n Analyze --> Landing: 有索引仓库\n Landing --> Success: 选择仓库\n Success --> Landing: 切换仓库\n Onboarding --> Success: 快速路径\n Analyze --> Success: 直接分析\n```\n\n## 样式系统\n\n组件采用内联样式与 Tailwind CSS 混合模式，关键样式常量包括：\n\n| 类别 | 颜色值 | 用途 |\n|------|--------|------|\n| 背景 | `rgba(255,255,255,0.04)` | 卡片背景 |\n| 边框 | `rgba(255,255,255,0.08)` | 分隔线 |\n| 强调色 | `#a78bfa` | 主交互色 |\n| 成功色 | `#34d399` | 就绪状态 |\n| 信息色 | `#60a5fa` | 提示信息 |\n| 文字主色 | `#e2e2e8` | 标题文字 |\n| 文字次色 | `#9ca3af` | 说明文字 |\n| 文字弱色 | `#6b7280` | 标签文字 |\n\n资料来源：[HelpPanel.tsx:5-10]()\n\n## 组件通信模式\n\n父组件通过 Props 向下传递数据和回调，子组件通过事件触发父组件状态更新。\n\n```mermaid\ngraph TD\n A[App] -->|onServerConnect| B[DropZone]\n A -->|onAnalyzeComplete| C[Header]\n B -->|onComplete| A\n C -->|onSwitchRepo| A\n \n D[OnboardingGuide] -->|isPolling| B\n E[RepoAnalyzer] -->|onComplete| B\n```\n\n## 与后端的交互\n\nWeb UI 通过 REST API 与 `LocalBackend` 通信，主要交互包括：\n\n| 操作 | API 端点 | 用途 |\n|------|----------|------|\n| 探测服务器 | `GET /api/health` | 连接状态检测 |\n| 获取仓库列表 | `GET /api/repos` | 仓库选择器 |\n| 触发分析 | `POST /api/analyze` | 仓库克隆解析 |\n| 获取图谱数据 | `GET /api/graph` | 图谱可视化 |\n\n## 扩展开发指南\n\n新增 UI 组件的推荐步骤：\n\n1. 在 `gitnexus-web/src/components/` 目录创建组件文件\n2. 使用 TypeScript 定义 Props 接口\n3. 遵循内联样式模式保持视觉一致性\n4. 通过 `useBackend` Hook 访问后端状态\n5. 在 `App.tsx` 中注册新组件\n\n组件应保持单一职责，通过 Props 接收数据和回调，避免直接访问全局状态。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：abhigyanpatwari/GitNexus\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 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. 安装坑 · 来源证据：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## 3. 配置坑 · 来源证据：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## 4. 安装坑 · 来源证据：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## 5. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.12\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ab63b9f59a54481abd184c162662990 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.12 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.13\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7923c9bda9874ce9870d5c684c3087ff | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.14\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba78a9abede8434fa010e8bee0ad539d | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.15\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe507017f17c4775b3d5a4e73b724a3a | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.16\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f1c7b44ec854520814354c46f0d1889 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.17\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06c1411b76fb4e07998249f900e31b02 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.18\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39945335ad1940e888d89a6cf3971331 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.19\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d3a217ad4944b9a8b541abf5b857840 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 13. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92b8f92f6417448abe698e2d08bba803 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.8 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.9\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.9\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a29c0c1477a8488d8f31bc15d51d1df9 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 配置坑 · 来源证据：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44741975e7b44839afb3b3379760d58f | https://github.com/abhigyanpatwari/GitNexus/issues/1541 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\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## 17. 维护坑 · 维护活跃度未知\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## 18. 安全/权限坑 · 下游验证发现风险项\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## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\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## 21. 维护坑 · 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## 22. 维护坑 · 发布节奏不明确\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 项目说明书", "目录", "项目介绍", "核心定位", "系统架构", "数据摄取管道", "核心功能模块", "前端组件架构", "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": "507f84b69af29f6a5596538a59175bd930d07e57", "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- 文件总数：2867\n- 重要文件覆盖：40/2867\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.28\", \"@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- **项目介绍**：importance `high`\n - source_paths: README.md, ARCHITECTURE.md\n- **快速开始**：importance `high`\n - source_paths: gitnexus/package.json, gitnexus/.npmignore\n- **系统架构**：importance `high`\n - source_paths: ARCHITECTURE.md, gitnexus/src/core/graph/types.ts, gitnexus/src/core/graph/graph.ts, gitnexus-shared/src/graph/types.ts\n- **MCP 架构与集成**：importance `high`\n - source_paths: gitnexus/src/mcp/server.ts, gitnexus/src/mcp/tools.ts, gitnexus/src/mcp/resources.ts, gitnexus/src/mcp/local/local-backend.ts, gitnexus/src/storage/repo-manager.ts\n- **知识图谱构建**：importance `high`\n - source_paths: gitnexus/src/core/graph/types.ts, gitnexus/src/core/graph/graph.ts, gitnexus/src/core/group/service.ts, gitnexus/src/core/ingestion/pipeline-phases/communities.ts, gitnexus/src/core/ingestion/pipeline-phases/processes.ts\n- **索引管道**：importance `high`\n - source_paths: gitnexus/src/core/ingestion/pipeline.ts, gitnexus/src/core/ingestion/pipeline-phases/scan.ts, gitnexus/src/core/ingestion/pipeline-phases/parse.ts, gitnexus/src/core/ingestion/pipeline-phases/structure.ts, gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts\n- **CLI 命令详解**：importance `high`\n - source_paths: gitnexus/src/cli/index.ts, gitnexus/src/cli/analyze.ts, gitnexus/src/cli/serve.ts, gitnexus/src/cli/mcp.ts, gitnexus/src/cli/group.ts\n- **多语言支持**：importance `medium`\n - source_paths: gitnexus/src/config/supported-languages.ts, gitnexus/src/core/ingestion/languages/index.ts, gitnexus/src/core/ingestion/languages/typescript.ts, gitnexus/src/core/ingestion/languages/python.ts, gitnexus/src/core/ingestion/languages/java.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `507f84b69af29f6a5596538a59175bd930d07e57`\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: 来源证据：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 3: 来源证据：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 4: 来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_26a9d2c26b004c6ba8a99533ff1d6ac5 | https://github.com/abhigyanpatwari/GitNexus/issues/1440 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Release Candidate v1.6.5-rc.12\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.12\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_3ab63b9f59a54481abd184c162662990 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.12 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Release Candidate v1.6.5-rc.13\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.13\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_7923c9bda9874ce9870d5c684c3087ff | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：Release Candidate v1.6.5-rc.14\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.14\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_ba78a9abede8434fa010e8bee0ad539d | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Release Candidate v1.6.5-rc.15\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.15\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_fe507017f17c4775b3d5a4e73b724a3a | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Release Candidate v1.6.5-rc.16\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.16\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_9f1c7b44ec854520814354c46f0d1889 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：Release Candidate v1.6.5-rc.17\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.17\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_06c1411b76fb4e07998249f900e31b02 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\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- 来源证据：Unable to install GitNexus in Mac（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：analyze: generated CLAUDE.md examples omit repo parameter in multi-repo environments（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：1.6.4-rc.94 on Windows 11 + WSL FTS indexes missing（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Release Candidate v1.6.5-rc.12（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\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-13 17:02:08 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [MCP 架构与集成](#page-mcp-architecture)\n- [知识图谱构建](#page-knowledge-graph)\n- [索引管道](#page-indexing-pipeline)\n- [CLI 命令详解](#page-cli-commands)\n- [多语言支持](#page-multilanguage-support)\n- [数据存储](#page-data-storage)\n- [Web UI 组件](#page-web-components)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)\n- [ARCHITECTURE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/ARCHITECTURE.md)\n- [gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)\n- [gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)\n- [gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)\n- [gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)\n
\n\n# 项目介绍\n\nGitNexus 是一个基于代码语义分析的知识图谱引擎，用于可视化、分析和理解代码仓库的结构与依赖关系。该项目由前端 Web 界面（gitnexus-web）和后端核心引擎（gitnexus）两部分组成，采用 TypeScript/React 作为前端技术栈，Node.js 作为后端运行时。\n\n## 核心定位\n\nGitNexus 的核心目标是解决大型代码仓库中**依赖关系难以追踪**的问题。通过 AST（抽象语法树）解析和语义理解，它能够自动构建代码元素之间的关联图谱，帮助开发者快速理解代码结构、追踪影响范围、发现潜在的架构问题。\n\n> **关键特性**：支持多语言解析、智能导入解析、继承关系追踪、gRPC/HTTP 模式识别，并集成了 LLM（大型语言模型）能力，支持自然语言查询代码库。\n\n资料来源：[README.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/README.md)()\n\n## 系统架构\n\nGitNexus 采用分层架构设计，核心模块分布在以下几个主要目录中：\n\n| 模块路径 | 职责描述 |\n|---------|---------|\n| `src/core/ingestion/` | 代码解析、AST 处理、依赖图谱构建 |\n| `src/core/group/` | 语言模式提取器、管道编排 |\n| `src/storage/` | Git 仓库操作、文件存储 |\n| `gitnexus-web/src/` | React 前端界面组件 |\n| `gitnexus-web/src/core/llm/` | LLM 集成与设置管理 |\n\n### 架构分层图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (gitnexus-web)\"]\n UI[React 组件]\n HOOKS[状态管理 Hooks]\n LLM_SVC[LLM 设置服务]\n end\n \n subgraph 核心引擎[\"核心引擎 (gitnexus)\"]\n INGEST[ingestion
代码摄取]\n GROUP[group
模式分组]\n STORAGE[storage
存储层]\n end\n \n subgraph 解析层[\"解析层\"]\n PARSER[Parser 加载器]\n LANG[Language 插件]\n TREE_SITTER[Tree-sitter]\n end\n \n UI --> HOOKS\n HOOKS --> LLM_SVC\n LLM_SVC --> INGEST\n INGEST --> PARSER\n PARSER --> TREE_SITTER\n GROUP --> LANG\n INGEST --> STORAGE\n STORAGE --> GIT[Git 仓库]\n```\n\n资料来源：[ARCHITECTURE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/ARCHITECTURE.md)()\n\n## 数据摄取管道\n\n数据摄取是 GitNexus 的核心处理流程，分为多个阶段执行：\n\n### 摄取阶段概览\n\n| 阶段 | 名称 | 核心功能 |\n|-----|------|---------|\n| Phase 1 | 文件扫描 | 递归扫描仓库文件，过滤非代码文件 |\n| Phase 2 | AST 解析 | 使用 tree-sitter 解析代码生成语法树 |\n| Phase 3 | 语义建模 | 构建符号表、作用域索引 |\n| Phase 4 | 依赖分析 | 追踪 imports、calls、inherits 关系 |\n| Phase 5 | 关系发射 | 将分析结果写入知识图谱 |\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)()\n\n### 管道处理流程\n\n```mermaid\nflowchart TD\n START[代码仓库] --> SCAN[文件扫描]\n SCAN --> LANG[语言检测]\n LANG --> LOAD[加载 Parser]\n LOAD --> PARSE[AST 解析]\n PARSE --> EXTRACT[模式提取]\n EXTRACT --> SCOPE[作用域解析]\n SCOPE --> HERITAGE[继承关系处理]\n HERITAGE --> EMIT[发射到图数据库]\n EMIT --> COMPLETE[完成]\n \n subgraph 模式识别[\"模式识别 (group)\"]\n GRPC[Grpc 模式]\n HTTP[Http 模式]\n PYTHON[Python 导入]\n end\n \n EXTRACT --> GRPC\n EXTRACT --> HTTP\n EXTRACT --> PYTHON\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/heritage-processor.ts)()\n\n## 核心功能模块\n\n### 1. 代码依赖图谱\n\nGitNexus 将代码仓库解析为节点（Nodes）和边（Edges）的图结构：\n\n- **节点**：代表代码元素（类、函数、接口、包等）\n- **边**：代表依赖关系（导入、调用、继承、访问）\n\n> **节点大小含义**：节点的大小反映了其被依赖的数量——被更多文件依赖的节点会显示得更大。\n\n资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)()\n\n### 2. 多语言支持框架\n\nGitNexus 通过可插拔的模式提取器支持多种编程语言：\n\n| 语言 | 支持模式 | 模式文件 |\n|------|---------|---------|\n| JavaScript | gRPC 客户端、HTTP 调用 | `grpc-patterns/node.ts` |\n| TypeScript | gRPC 方法、服务定义 | `grpc-patterns/node.ts` |\n| PHP | Laravel 路由、HTTP Facade、Guzzle | `http-patterns/php.ts` |\n| Python | 导入解析、模块解析 | `languages/python/import-target.ts` |\n\n#### gRPC 模式识别\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资料来源：[gitnexus/src/core/group/extractors/grpc-patterns/node.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/extractors/grpc-patterns/node.ts)()\n\n### 3. 继承关系追踪\n\n继承关系处理（heritage-processor）是理解面向对象代码结构的关键组件：\n\n- 支持 `implements` 和 `extends` 两种继承类型\n- 构建父类/接口到实现类的映射\n- 支持多种语言的继承语义策略\n\n```typescript\nif (h.kind === 'implements') {\n isImpl = true;\n} else if (h.kind === 'extends') {\n const lang = getLanguageFromFilename(h.filePath);\n if (lang) {\n const strategy = getHeritageStrategy?.(lang) ?? DEFAULT_HERITAGE_STRATEGY;\n const { type } = resolveExtendsType(h.parentName, h.filePath, ctx, strategy);\n isImpl = type === 'IMPLEMENTS';\n }\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/model/heritage-map.ts)()\n\n### 4. 引用关系发射\n\n引用关系模块将解析结果转换为图数据库中的边：\n\n| 引用类型 | 图关系类型 | 说明 |\n|---------|-----------|------|\n| `call` | `CALLS` | 函数调用 |\n| `read` / `write` | `ACCESSES` | 属性访问 |\n| `type-reference` | `USES` | 类型引用 |\n| `import-use` | `USES` | 导入使用 |\n| `inherits` | `INHERITS` | 继承关系 |\n\n每个发射的边都携带 `confidence`（置信度）和 `evidence`（证据）属性，用于追溯分析结果的可靠性。\n\n资料来源：[gitnexus/src/core/ingestion/emit-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/emit-references.ts)()\n\n### 5. Python 导入解析\n\nPython 的导入解析采用多级匹配策略：\n\n```mermaid\nflowchart TD\n PATH[导入路径] --> EXACT{精确匹配}\n EXACT -->|成功| RESULT1[返回精确路径]\n EXACT -->|失败| ANCESTOR{祖先目录匹配}\n ANCESTOR -->|成功| RESULT2[返回祖先路径]\n ANCESTOR -->|失败| SUFFIX{后缀匹配}\n SUFFIX -->|成功| RESULT3[返回后缀路径]\n SUFFIX -->|失败| NULL[返回 null]\n```\n\n**匹配优先级**：\n1. 工作区根目录直接命中\n2. 向上遍历祖先目录查找\n3. 后缀匹配（确定性：路径段最少优先）\n\n资料来源：[gitnexus/src/core/ingestion/languages/python/import-target.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/ingestion/languages/python/import-target.ts)()\n\n### 6. LLM 集成\n\nGitNexus 支持多种 LLM 提供商配置：\n\n| 提供商 | 配置类型 | API 类型 |\n|-------|---------|---------|\n| OpenAI | `OpenAIConfig` | REST API |\n| Azure OpenAI | `AzureOpenAIConfig` | Azure 端点 |\n| Gemini | `GeminiConfig` | Google API |\n| Anthropic | `AnthropicConfig` | Anthropic API |\n| Ollama | `OllamaConfig` | 本地模型 |\n| OpenRouter | `OpenRouterConfig` | 聚合网关 |\n| MiniMax | `MiniMaxConfig` | MiniMax API |\n| GLM | `GLMConfig` | 智谱 API |\n\n用户可通过设置面板配置 LLM，并使用自然语言查询代码库。\n\n资料来源：[gitnexus-web/src/core/llm/settings-service.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/core/llm/settings-service.ts)()\n\n## 前端组件架构\n\n前端采用 React + TypeScript 构建，主要组件结构如下：\n\n| 组件 | 功能 |\n|------|------|\n| `Header.tsx` | 导航栏、仓库切换 |\n| `HelpPanel.tsx` | 帮助面板、图例说明 |\n| `StatusBar.tsx` | 状态栏、进度显示 |\n| `RepoAnalyzer.tsx` | 仓库分析表单 |\n| `DropZone.tsx` | 文件拖拽上传 |\n| `OnboardingGuide.tsx` | 首次使用引导 |\n| `SettingsPanel.tsx` | LLM 配置面板 |\n\n### 状态管理\n\n前端使用 React Hooks 进行状态管理，核心状态包括：\n\n- `highlightedNodeIds`：高亮节点集合\n- `aiCitationHighlightedNodeIds`：AI 引用高亮\n- `blastRadiusNodeIds`：影响半径节点\n- `progress`：管道处理进度\n- `availableRepos`：可用仓库列表\n- `serverBaseUrl`：服务器连接地址\n\n资料来源：[gitnexus-web/src/hooks/useAppState.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/hooks/useAppState.tsx)()\n\n## Git 集成\n\nGitNexus 提供 Git 仓库操作能力：\n\n### 主要功能\n\n| 函数 | 功能描述 |\n|------|---------|\n| `hasGitDir()` | 检查目录是否为 Git 仓库 |\n| `getRemoteOriginUrl()` | 获取远程仓库 URL |\n| `sanitizeRepoName()` | 清理仓库名称，防止注入攻击 |\n\n> Git 远程 URL 用于推断仓库名称，特别是在 monorepo 或 git worktree 场景下。\n\n资料来源：[gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/storage/git.ts)()\n\n## 工作流程示意\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Web as 前端界面\n participant Server as 后端服务\n participant Parser as 解析引擎\n participant Graph as 图数据库\n \n User->>Web: 选择仓库\n Web->>Server: 发送分析请求\n Server->>Parser: 启动摄取管道\n Parser->>Graph: 解析并写入节点/边\n Graph-->>Server: 返回分析结果\n Server-->>Web: 返回图数据\n Web->>Web: 渲染交互图谱\n \n User->>Web: 点击节点/搜索/提问\n Web->>Server: 查询请求\n Server->>Graph: Cypher 查询\n Graph-->>Server: 查询结果\n Server-->>Web: 返回结果\n```\n\n## 扩展机制\n\nGitNexus 采用插件化设计，新增语言支持只需：\n\n1. 在 `src/core/group/extractors/*-patterns/` 目录下创建模式文件\n2. 在对应 `index.ts` 中注册新语言\n3. 无需修改编排器代码\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md](https://github.com/abhigyanpatwari/GitNexus/blob/main/src/core/group/PIPELINE.md)()\n\n## 快速开始\n\n### 前置要求\n\n- Node.js 16+\n- npm 或 pnpm 包管理器\n\n### 安装与启动\n\n```bash\n# 全局安装\nnpm install -g gitnexus && gitnexus serve\n\n# 本地开发\ncd gitnexus\nnpm install\nnpm run dev\n```\n\n前端会自动检测服务器启动，无需手动刷新页面。\n\n资料来源：[gitnexus-web/src/components/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)()\n\n## 技术栈总结\n\n| 层级 | 技术选型 |\n|------|---------|\n| 前端框架 | React 18 + TypeScript |\n| 样式方案 | Tailwind CSS |\n| 状态管理 | React Hooks |\n| 后端运行时 | Node.js |\n| AST 解析器 | tree-sitter |\n| 图数据库 | Neo4j (Cypher) |\n| 编程语言 | TypeScript |\n\nGitNexus 通过将静态代码分析与交互式可视化相结合，为开发者提供了一个强大的代码理解工具，特别适用于大型代码仓库的架构分析、依赖追踪和代码审查场景。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [CLI 命令详解](#page-cli-commands), [MCP 架构与集成](#page-mcp-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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- [gitnexus/src/cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n- [gitnexus/src/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n
\n\n# 快速开始\n\nGitNexus 是一个代码知识图谱构建工具，能够自动分析 GitHub 仓库，解析代码结构并生成交互式依赖关系图。本页介绍如何快速上手使用 GitNexus，包括环境配置、项目分析和图谱查看的完整流程。\n\n## 环境要求\n\n### 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18.0.0+ | 必须安装，用于运行后端服务 |\n| npm | 8.0.0+ | 用于包管理 |\n| Git | 2.30.0+ | 用于仓库克隆操作 |\n\n### 安装前置条件\n\nGitNexus 后端服务需要 Node.js 运行环境。前端界面通过浏览器访问，无需额外安装。\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## 安装方式\n\nGitNexus 提供两种安装方式，可根据使用场景选择。\n\n### 全局安装（推荐）\n\n适用于频繁使用 GitNexus 的开发者，一次安装后可在任意目录使用：\n\n```bash\nnpm install -g gitnexus && gitnexus serve\n```\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n### 本地安装\n\n适用于特定项目或团队共享配置的场景：\n\n```bash\nnpm install gitnexus\nnpx gitnexus serve\n```\n\n## 启动流程\n\n### 整体流程\n\n```mermaid\nflowchart TD\n A[安装 GitNexus] --> B[启动后端服务]\n B --> C{服务状态检测}\n C -->|成功| D[打开浏览器]\n C -->|失败| E[显示错误信息]\n D --> F[粘贴 GitHub 仓库 URL]\n F --> G[克隆并解析代码]\n G --> H[生成知识图谱]\n H --> I[交互式查看]\n```\n\n### 步骤详解\n\n#### 步骤一：安装与启动\n\n执行安装命令后，终端会显示服务启动状态。GitNexus 后端服务默认在本地端口运行，等待前端连接。\n\n> 资料来源：[cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n\n#### 步骤二：等待服务器启动\n\n启动过程中，界面会显示轮询进度条，实时反馈连接状态。系统会自动检测后端服务是否就绪，无需手动刷新页面。\n\n```mermaid\nstateDiagram-v2\n [*] --> 探测中: 启动后端\n 探测中 --> 服务就绪: 检测成功\n 探测中 --> 探测中: 继续轮询\n 服务就绪 --> [*]: 自动跳转\n```\n\n> 资料来源：[DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n#### 步骤三：自动连接\n\n服务就绪后，页面自动跳转到主界面。此时用户可以粘贴 GitHub 仓库 URL 开始分析。\n\n> 资料来源：[OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.tsx)\n\n## 仓库分析\n\n### 输入仓库 URL\n\n在分析界面的输入框中粘贴公开的 GitHub 仓库地址。GitNexus 支持以下格式：\n\n| 格式类型 | 示例 |\n|----------|------|\n| HTTPS | `https://github.com/user/repo` |\n| 简写 | `user/repo` |\n\n> 资料来源：[AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n### 自动处理流程\n\n```mermaid\nflowchart LR\n A[输入 URL] --> B[克隆仓库]\n B --> C[解析代码 AST]\n C --> D[提取符号关系]\n D --> E[构建图谱数据]\n E --> F[渲染交互界面]\n```\n\n系统会自动完成以下操作：\n\n1. **克隆仓库**：通过 Git 获取完整代码库\n2. **代码解析**：使用 tree-sitter 解析多语言源码\n3. **符号提取**：识别函数、类、接口等定义\n4. **依赖分析**：构建导入导出关系图\n5. **图谱生成**：生成可交互的可视化图谱\n\n> 资料来源：[git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n\n### 数据隐私\n\n| 特性 | 说明 |\n|------|------|\n| 本地处理 | 所有代码在本地解析，不上传至云端 |\n| 仅支持公开仓库 | 出于安全考虑，仅支持公开的 GitHub 仓库 |\n| 自动清理 | 可随时清除本地缓存的仓库数据 |\n\n> 资料来源：[AnalyzeOnboarding.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/AnalyzeOnboarding.tsx)\n\n## 仓库管理\n\n### 切换仓库\n\n分析完成后，仓库会自动添加到仓库列表中。点击下拉菜单可以：\n\n- 查看当前所有已分析的仓库\n- 快速切换到其他已分析仓库\n- 对仓库执行重新分析\n\n> 资料来源：[Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n### 重新分析\n\n对于已分析的仓库，可以点击重新分析按钮更新图谱。重新分析会重新克隆最新代码并更新依赖关系。\n\n> 资料来源：[Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.tsx)\n\n## 界面状态\n\n### 阶段状态机\n\nGitNexus 前端界面存在以下状态：\n\n| 状态 | 说明 | 触发条件 |\n|------|------|----------|\n| onboarding | 初始引导状态 | 首次打开或无已分析仓库 |\n| analyze | 分析输入状态 | 服务器运行中但无仓库索引 |\n| landing | 仓库列表状态 | 服务运行且有已分析仓库 |\n| success | 分析成功状态 | 仓库分析完成 |\n| loading | 加载状态 | 正在克隆或解析代码 |\n\n> 资料来源：[DropZone.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/DropZone.tsx)\n\n### 状态转换图\n\n```mermaid\nstateDiagram-v2\n [*] --> onboarding: 首次访问\n onboarding --> analyze: 完成引导\n analyze --> loading: 开始分析\n loading --> success: 分析完成\n loading --> landing: 分析取消\n success --> landing: 切换视图\n landing --> analyze: 清除仓库\n landing --> loading: 重新分析\n```\n\n## 图谱交互\n\n### 节点信息\n\n- **节点大小**：反映依赖该节点的文件数量，越大表示被依赖越多\n- **节点颜色**：区分不同类型的符号（函数、类、接口等）\n- **边的方向**：从导入方指向被导入方\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| 点击节点 | 打开详情面板，显示导入、导出和反向依赖 |\n| 缩放 | 使用鼠标滚轮调整视图大小 |\n| 拖拽 | 按住鼠标拖动画布移动 |\n\n> 资料来源：[gitnexus-web/src/components/HelpPanel.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/HelpPanel.tsx)\n\n## 命令行接口\n\nGitNexus 提供完整的 CLI 命令集：\n\n| 命令 | 功能 |\n|------|------|\n| `gitnexus serve` | 启动后端服务 |\n| `gitnexus analyze ` | 分析指定仓库 |\n| `gitnexus wiki` | 生成文档页面 |\n| `gitnexus query ` | 查询知识图谱 |\n| `gitnexus publish [path]` | 发布到注册表 |\n\n> 资料来源：[cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n\n## 常见问题\n\n### Q: 服务启动失败\n\n确保 Node.js 版本符合要求（18.0.0+），并检查端口是否被占用。\n\n### Q: 无法克隆仓库\n\n确认仓库为公开状态，且网络连接正常。\n\n### Q: 图谱加载缓慢\n\n大型仓库解析需要较长时间，建议耐心等待或使用浏览器开发者工具查看进度。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [知识图谱构建](#page-knowledge-graph), [索引管道](#page-indexing-pipeline), [MCP 架构与集成](#page-mcp-architecture)\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/graph/graph.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/graph/graph.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/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/heritage-map.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/heritage-map.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/group/extractors/http-patterns/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/http-patterns/php.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/ingestion/languages/c-cpp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/c-cpp.ts)\n
\n\n# 系统架构\n\n## 1. 概述\n\nGitNexus 是一个用于代码库的交互式图谱探索工具，能够将代码库中的每个文件、函数和导入关系转换为可探索、可查询、可视化导航的节点。该系统通过静态代码分析和图谱构建技术，帮助开发者理解代码结构、依赖关系和组件间的交互模式。 资料来源：[gitnexus/src/core/group/PIPELINE.md:1-10]()\n\n### 1.1 核心设计目标\n\n| 设计目标 | 描述 |\n|---------|------|\n| 语义理解 | 不仅理解文件名，还理解代码结构和关系 |\n| 可视化探索 | 通过图谱形式直观展示代码依赖关系 |\n| 多语言支持 | 支持 JavaScript、TypeScript、PHP、C/C++ 等多种编程语言 |\n| 语义查询 | 支持自然语言查询和语义搜索能力 |\n\n## 2. 系统分层架构\n\nGitNexus 采用分层架构设计，将核心功能划分为前端展示层和后端处理层。前端负责用户界面和图谱可视化，后端负责代码解析、图谱构建和语义索引。\n\n### 2.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (gitnexus-web)\"]\n UI[用户界面组件]\n HELP[帮助面板]\n DROP[拖拽连接区]\n HEADER[头部导航]\n STATUS[状态栏]\n end\n \n subgraph 后端核心[\"后端核心层 (gitnexus)\"]\n INGEST[摄取引擎]\n GRAPH[图谱构建]\n SCOPE[作用域解析]\n HERITAGE[继承关系处理]\n end\n \n subgraph 语言处理[\"语言处理器\"]\n JS[JavaScript/TypeScript]\n PHP[PHP]\n CPP[C/C++]\n GRPC[gRPC模式]\n end\n \n UI --> DROP\n DROP --> INGEST\n INGEST --> GRAPH\n INGEST --> SCOPE\n INGEST --> HERITAGE\n JS --> INGEST\n PHP --> INGEST\n CPP --> INGEST\n GRPC --> INGEST\n```\n\n### 2.2 核心模块职责\n\n| 模块名称 | 位置 | 核心职责 |\n|---------|------|---------|\n| 摄取引擎 | `gitnexus/src/core/ingestion/` | 解析源代码文件，提取节点和边 |\n| 图谱构建 | `gitnexus/src/core/graph/` | 构建和管理代码依赖图谱 |\n| 作用域解析 | `scope-resolution/` | 解析变量和方法的作用域 |\n| 继承关系处理 | `heritage-processor.ts` | 追踪类继承和接口实现关系 |\n| HTTP模式提取 | `http-patterns/` | 提取HTTP路由和服务调用模式 |\n\n## 3. 数据模型\n\n### 3.1 图谱节点类型\n\nGitNexus 使用统一的图谱数据模型来表示代码中的各种元素。节点类型决定了图谱中的可视化形式和交互行为。\n\n```mermaid\ngraph TD\n Node[图谱节点] --> Type[节点类型]\n Type --> Function[Function]\n Type --> Method[Method]\n Type --> Class[Class]\n Type --> Interface[Interface]\n Type --> Package[Package]\n Type --> Module[Module]\n \n Node --> Properties[属性]\n Properties --> nodeId[nodeId: string]\n Properties --> label[label: string]\n Properties --> filePath[filePath: string]\n```\n\n### 3.2 核心数据类型定义\n\n| 类型名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| `GraphNode` | 表示图谱中的节点 | `nodeId`, `label`, `type`, `filePath` |\n| `GraphEdge` | 表示节点间关系 | `source`, `target`, `kind` |\n| `Scope` | 代码作用域 | `ScopeId`, `ownerId`, `defs`, `children` |\n| `HeritageEntry` | 继承/实现关系 | `kind`, `parentName`, `filePath` |\n| `SemanticModel` | 语义模型 | `methods`, `symbols`, `classes` |\n\n## 4. 摄取管道 (Ingestion Pipeline)\n\n### 4.1 管道流程概览\n\n代码摄取是 GitNexus 的核心处理流程，负责将源代码转换为结构化的图谱数据。\n\n```mermaid\nflowchart TD\n A[源代码文件] --> B[语言检测]\n B --> C{是否为注册表主语言?}\n C -->|是| D[跳过摄取]\n C -->|否| E[加载Tree-sitter语言]\n E --> F[解析AST]\n F --> G[执行Tree-sitter查询]\n G --> H[提取调用关系]\n H --> I[提取继承关系]\n I --> J[构建作用域索引]\n J --> K[生成图谱节点和边]\n K --> L[输出到图谱存储]\n```\n\n### 4.2 摄取配置结构\n\n每种编程语言都有对应的摄取配置，定义了如何解析和提取代码元素。\n\n```typescript\n// C语言摄取配置示例\nconst cCallConfig = {\n // 调用提取配置\n extractor: createCallExtractor(cCallConfig),\n // 字段提取配置\n fieldExtractor: createFieldExtractor(cFieldConfig),\n // 方法提取配置\n methodExtractor: createMethodExtractor({\n ...cMethodConfig,\n extractFunctionName: cCppExtractFunctionName,\n }),\n // 变量提取配置\n variableExtractor: createVariableExtractor(cVariableConfig),\n};\n```\n\n### 4.3 语言特定处理器\n\n#### PHP HTTP模式提取\n\nPHP语言支持提取多种HTTP相关模式，包括Laravel路由、HTTP Facade、Guzzle客户端和文件读取操作。\n\n| 模式类型 | 提取内容 | 用途 |\n|---------|---------|------|\n| `laravelRoute` | Laravel路由定义 | 追踪Web路由依赖 |\n| `httpFacade` | HTTP Facade调用 | 分析HTTP请求模式 |\n| `guzzleMember` | Guzzle客户端方法 | 识别HTTP客户端使用 |\n| `fileGetContents` | 文件读取操作 | 追踪文件系统依赖 |\n\n#### gRPC模式提取\n\nJavaScript和TypeScript支持gRPC服务模式提取。\n\n| 模式名称 | 描述 |\n|---------|------|\n| `grpcMethod` | gRPC方法定义 |\n| `grpcClient` | gRPC客户端实例化 |\n| `getService` | 服务获取调用 |\n| `newSimpleCtor` | 简单构造函数 |\n| `newQualifiedCtor` | 限定名构造函数 |\n| `loadPackageDefinition` | 包定义加载 |\n\n## 5. 继承关系管理\n\n### 5.1 HeritageMap 数据结构\n\n继承关系通过 `HeritageMap` 数据结构管理，支持类继承、接口实现和多继承场景。\n\n```mermaid\ngraph LR\n A[子类] -->|extends| B[父类]\n C[实现类] -->|implements| D[接口]\n E[类] -->|extends| F[抽象类]\n F -->|implements| D\n```\n\n### 5.2 继承关系处理逻辑\n\n```typescript\n// 继承关系处理伪代码\nif (h.kind === 'implements') {\n isImpl = true;\n} else if (h.kind === 'extends') {\n const lang = getLanguageFromFilename(h.filePath);\n const strategy = getHeritageStrategy?.(lang) ?? DEFAULT_HERITAGE_STRATEGY;\n const { type } = resolveExtendsType(h.parentName, h.filePath, ctx, strategy);\n isImpl = type === 'IMPLEMENTS';\n}\n```\n\n### 5.3 实现者追踪\n\n系统维护了一个 `implementorFiles` 映射，用于快速查找某个接口的所有实现者。\n\n```typescript\nif (isImpl) {\n let files = implementorFiles.get(h.parentName);\n if (!files) {\n files = new Set();\n implementorFiles.set(h.parentName, files);\n }\n files.add(h.filePath);\n}\n```\n\n## 6. 作用域解析\n\n### 6.1 工作区索引结构\n\n作用域解析使用 `WorkspaceResolutionIndex` 来建立和维护代码的作用域层级关系。\n\n| 索引字段 | 类型 | 用途 |\n|---------|------|------|\n| `classScopeByDefId` | `ReadonlyMap` | 类定义ID到类作用域的映射 |\n| `classScopeIdToDefId` | `ReadonlyMap` | 类作用域ID到定义ID的反向映射 |\n\n### 6.2 作用域查询优化\n\n系统通过预构建索引来加速作用域查询，避免运行时的大量扫描操作。\n\n```mermaid\ngraph TD\n A[查找类方法] --> B{检查缓存索引}\n B -->|命中| C[直接返回作用域]\n B -->|未命中| D[扫描AST]\n D --> E[缓存结果]\n E --> C\n```\n\n## 7. 前端组件架构\n\n### 7.1 组件层次结构\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| `DropZone` | `DropZone.tsx` | 服务器连接和仓库加载 |\n| `Header` | `Header.tsx` | 导航栏和仓库选择器 |\n| `StatusBar` | `StatusBar.tsx` | 状态显示和进度指示 |\n| `HelpPanel` | `HelpPanel.tsx` | 帮助信息和操作指南 |\n| `OnboardingGuide` | `OnboardingGuide.tsx` | 安装引导流程 |\n| `AnalyzeOnboarding` | `AnalyzeOnboarding.tsx` | 仓库分析引导 |\n| `RepoAnalyzer` | - | GitHub仓库分析和克隆 |\n\n### 7.2 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> onboarding: 首次访问\n onboarding --> analyze: 完成安装引导\n analyze --> landing: 分析完成\n landing --> success: 选择仓库\n success --> loading: 加载图谱\n loading --> [*]: 图谱展示\n onboarding --> landing: 服务器已运行\n```\n\n### 7.3 WebGPU加速与降级\n\n系统优先使用 WebGPU 进行语义搜索加速，当浏览器不支持时自动降级到CPU处理。\n\n```mermaid\ngraph TD\n A[语义搜索请求] --> B{WebGPU可用?}\n B -->|是| C[使用GPU加速]\n B -->|否| D{用户选择}\n D -->|CPU| E[使用CPU处理]\n D -->|取消| F[跳过语义搜索]\n C --> G[生成嵌入向量]\n E --> H[较慢但功能完整]\n```\n\n## 8. 扩展机制\n\n### 8.1 语言注册表\n\n每种编程语言通过语言提供器注册到系统中，无需修改核心编排代码即可添加新语言支持。\n\n```typescript\nexport const cProvider = defineLanguage({\n id: SupportedLanguages.C,\n extensions: ['.c'],\n entryPointPatterns: [\n /^main$/,\n /^init_/,\n /_init$/,\n // ... 更多入口点模式\n ],\n treeSitterQueries: C_QUERIES,\n typeConfig: cCppConfig,\n // ...\n});\n```\n\n### 8.2 模式提取器注册\n\n新框架或语言支持通过在 `*-patterns/` 目录添加文件并在 `index.ts` 中注册来扩展。\n\n```mermaid\nflowchart TD\n A[新增模式文件] --> B[实现PatternSpec]\n B --> C[调用compilePatterns]\n C --> D[导出CompiledPatterns]\n D --> E[注册到index.ts]\n E --> F[管道自动加载]\n```\n\n## 9. 配置与扩展\n\n### 9.1 语言支持矩阵\n\n| 语言 | 扩展名 | 调用提取 | 继承追踪 | 字段提取 | 变量提取 |\n|-----|--------|---------|---------|---------|---------|\n| JavaScript | `.js` | ✓ | ✓ | ✓ | ✓ |\n| TypeScript | `.ts` `.tsx` | ✓ | ✓ | ✓ | ✓ |\n| PHP | `.php` | ✓ | ✓ | ✓ | ✓ |\n| C | `.c` | ✓ | ✓ | ✓ | ✓ |\n| C++ | `.cpp` `.h` | ✓ | ✓ | ✓ | ✓ |\n\n### 9.2 入口点模式配置\n\n入口点模式用于识别程序的主要入口函数，便于图谱构建时的根节点识别。\n\n| 模式前缀 | 模式后缀 | 示例 |\n|---------|---------|------|\n| `main` | - | `main` |\n| `init_` | `_init` | `init_database`, `database_init` |\n| `start_` | `_start` | `start_server`, `server_start` |\n| `stop_` | `_stop` | `stop_service`, `service_stop` |\n| `create_` | `_create` | `create_window`, `window_create` |\n\n## 10. 总结\n\nGitNexus 的系统架构遵循模块化和可扩展的设计原则，通过清晰的层次划分和标准化的接口定义，实现了多语言代码分析和图谱可视化功能。核心的摄取管道采用 Tree-sitter 进行 AST 解析，结合语言特定的模式提取器，实现了高效的代码元素提取。继承关系管理和作用域解析机制为语义查询提供了坚实的数据基础，而前端组件的模块化设计则确保了良好的用户体验和可维护性。 资料来源：[gitnexus/src/core/group/PIPELINE.md:1-50]()\n\n\n---\n\n\n\n## MCP 架构与集成\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [CLI 命令详解](#page-cli-commands), [数据存储](#page-data-storage)\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/mcp/local/local-backend.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/mcp/local/local-backend.ts)\n- [gitnexus/src/storage/repo-manager.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/repo-manager.ts)\n
\n\n# MCP 架构与集成\n\n## 概述\n\nGitNexus 项目中的 MCP（Model Context Protocol）模块是一个为大型语言模型（LLM）提供上下文集成能力的核心子系统。MCP 架构使 AI 助手能够通过标准化的协议与本地 Git 仓库进行交互，获取仓库元数据、操作 Git 资源、管理仓库状态，并执行各种开发任务。\n\nMCP 模块位于 `gitnexus/src/mcp/` 目录下，采用模块化设计，包含服务器核心、工具集、资源管理和本地后端四个主要组件。\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[AI 客户端] -->|MCP 协议| B[MCP 服务器]\n B --> C[工具层]\n B --> D[资源层]\n C --> E[Git 工具集]\n C --> F[文件工具集]\n D --> G[仓库资源]\n D --> H[配置资源]\n E --> I[本地后端]\n I --> J[仓库管理器]\n J --> K[Git 仓库]\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| MCP 服务器 | `src/mcp/server.ts` | 协议初始化、请求路由、连接管理 |\n| 工具集 | `src/mcp/tools.ts` | 定义可调用的 Git 和文件操作 |\n| 资源层 | `src/mcp/resources.ts` | 暴露仓库元数据和配置信息 |\n| 本地后端 | `src/mcp/local/local-backend.ts` | 与本地文件系统和 Git 交互 |\n| 仓库管理 | `src/storage/repo-manager.ts` | 仓库生命周期管理 |\n\n资料来源：[gitnexus/src/mcp/server.ts:1-50]()\n\n## MCP 服务器实现\n\n### 服务器初始化\n\nMCP 服务器是整个模块的核心入口点，负责初始化协议栈并注册所有可用的工具和资源。\n\n```typescript\n// 服务器初始化流程\nconst server = new McpServer({\n name: \"gitnexus\",\n version: \"1.0.0\"\n});\n```\n\n服务器通过 `@modelcontextprotocol/sdk` 包提供的 `McpServer` 类实现，支持以下功能：\n\n- 动态注册工具和资源\n- 请求/响应模式处理\n- 资源订阅机制\n- 错误处理和日志记录\n\n资料来源：[gitnexus/src/mcp/server.ts:1-30]()\n\n### 工具注册流程\n\n工具注册是服务器初始化的关键步骤，每个工具都包含名称、描述和参数模式：\n\n```mermaid\ngraph LR\n A[定义工具] --> B[注册到服务器]\n B --> C[客户端发现]\n C --> D[调用执行]\n D --> E[返回结果]\n```\n\n## 工具集详解\n\n### 工具分类\n\nMCP 工具集分为两大类：Git 操作工具和文件操作工具。\n\n| 工具类别 | 功能描述 | 典型用例 |\n|----------|----------|----------|\n| Git 操作 | 分支管理、提交操作、状态查询 | 创建分支、提交更改、查看日志 |\n| 文件操作 | 读写文件、目录遍历、路径解析 | 读取配置文件、写入代码文件 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:1-100]()\n\n### Git 操作工具\n\n#### 分支管理工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_list_branches` | `repoPath: string` | 分支名称数组 |\n| `git_create_branch` | `repoPath, branchName` | 操作状态 |\n| `git_delete_branch` | `repoPath, branchName` | 操作状态 |\n| `git_checkout` | `repoPath, branchName` | 操作状态 |\n\n#### 提交管理工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_commit` | `repoPath, message, files?` | 提交哈希 |\n| `git_log` | `repoPath, limit?` | 提交历史数组 |\n| `git_status` | `repoPath` | 工作区状态 |\n\n#### 远程操作工具\n\n| 工具名称 | 参数 | 返回值 |\n|----------|------|--------|\n| `git_pull` | `repoPath` | 拉取结果 |\n| `git_push` | `repoPath, remote?` | 推送结果 |\n| `git_fetch` | `repoPath, remote?` | 获取结果 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:50-150]()\n\n### 文件操作工具\n\n文件操作工具提供了对仓库文件系统的直接访问能力：\n\n```typescript\n// 文件读取工具参数定义\ninterface ReadFileTool {\n params: {\n path: string; // 文件绝对路径\n encoding?: string; // 编码格式，默认 utf-8\n };\n returns: {\n content: string;\n metadata: FileMetadata;\n };\n}\n```\n\n| 工具名称 | 功能 | 安全性 |\n|----------|------|--------|\n| `read_file` | 读取文件内容 | 受路径验证限制 |\n| `write_file` | 写入文件内容 | 仅允许工作区内操作 |\n| `list_directory` | 列出目录内容 | 递归深度受限 |\n| `get_file_info` | 获取文件元数据 | 公开信息查询 |\n\n资料来源：[gitnexus/src/mcp/tools.ts:100-200]()\n\n## 资源层设计\n\n### 资源类型\n\nMCP 资源是一种只读的上下文数据，通过 URI 方案暴露给 AI 客户端：\n\n```mermaid\ngraph TD\n A[资源注册] --> B[URI 模板]\n B --> C[客户端请求]\n C --> D[资源读取器]\n D --> E[格式化数据]\n E --> F[返回响应]\n```\n\n### 仓库资源\n\n| 资源 URI | 描述 | 数据格式 |\n|----------|------|----------|\n| `gitnexus://repo/info` | 仓库基本信息 | JSON |\n| `gitnexus://repo/branches` | 分支列表 | JSON 数组 |\n| `gitnexus://repo/remotes` | 远程仓库配置 | JSON 数组 |\n| `gitnexus://repo/status` | 当前工作区状态 | JSON |\n| `gitnexus://repo/config` | 仓库配置 | INI 格式 |\n\n资料来源：[gitnexus/src/mcp/resources.ts:1-80]()\n\n### 配置资源\n\n系统配置资源提供全局设置和用户偏好的访问：\n\n```typescript\n// 配置资源结构\ninterface ConfigResource {\n uri: \"gitnexus://config/settings\";\n data: {\n defaultBranch: string;\n autoFetch: boolean;\n theme: string;\n editor: EditorConfig;\n };\n}\n```\n\n| 资源 URI | 用途 | 更新频率 |\n|----------|------|----------|\n| `gitnexus://config/settings` | 用户设置 | 运行时可更新 |\n| `gitnexus://config/git` | Git 全局配置 | 静态 |\n| `gitnexus://config/plugins` | 插件配置 | 按需加载 |\n\n资料来源：[gitnexus/src/mcp/resources.ts:50-120]()\n\n## 本地后端集成\n\n### 本地后端架构\n\n本地后端是 MCP 与本地文件系统之间的桥梁，负责将工具调用转换为实际的操作系统操作：\n\n```mermaid\ngraph LR\n A[MCP 工具调用] --> B[本地后端 API]\n B --> C[权限检查]\n C --> D[路径验证]\n D --> E[文件系统操作]\n E --> F[结果格式化]\n F --> G[返回响应]\n```\n\n### 后端服务类\n\n`LocalBackendService` 是核心服务类，提供了所有与本地系统交互的方法：\n\n```typescript\nclass LocalBackendService {\n // 构造函数\n constructor(basePath: string, options?: BackendOptions);\n \n // Git 操作方法\n executeGitCommand(command: GitCommand): Promise;\n \n // 文件操作方法\n readFile(path: string, options?: ReadOptions): Promise;\n writeFile(path: string, content: string): Promise;\n \n // 路径操作方法\n resolvePath(relativePath: string): string;\n validatePath(path: string): boolean;\n}\n```\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:1-60]()\n\n### 权限与安全\n\n本地后端实现了多层安全检查机制：\n\n| 安全层级 | 检查项 | 实施方式 |\n|----------|--------|----------|\n| 路径验证 | 工作区边界检查 | 正则表达式匹配 |\n| 操作权限 | 读写执行权限 | 系统 API 调用 |\n| 命令白名单 | Git 子命令限制 | 白名单列表 |\n| 内容过滤 | 敏感信息脱敏 | 预处理器 |\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:40-100]()\n\n### Git 命令执行\n\n本地后端封装了常用的 Git 操作：\n\n```typescript\n// Git 命令执行接口\ninterface GitCommandExecutor {\n // 分支操作\n listBranches(options?: ListOptions): Promise;\n createBranch(name: string, startPoint?: string): Promise;\n deleteBranch(name: string, force?: boolean): Promise;\n \n // 提交操作\n commit(message: string, files?: string[]): Promise;\n log(limit?: number): Promise;\n \n // 远程操作\n pull(options?: PullOptions): Promise;\n push(remote?: string, branch?: string): Promise;\n}\n```\n\n资料来源：[gitnexus/src/mcp/local/local-backend.ts:80-150]()\n\n## 仓库管理器集成\n\n### 仓库管理器概述\n\n仓库管理器（`repo-manager.ts`）负责仓库的注册、发现和生命周期管理，为 MCP 提供仓库上下文：\n\n```mermaid\ngraph TD\n A[仓库发现] --> B[仓库注册]\n B --> C[仓库缓存]\n C --> D[MCP 上下文]\n D --> E[工具调用]\n E --> F[状态同步]\n```\n\n### 核心接口\n\n| 方法 | 描述 | 返回类型 |\n|------|------|----------|\n| `registerRepo(path)` | 注册新仓库 | `RepoInfo` |\n| `getRepo(path)` | 获取仓库信息 | `RepoInfo` |\n| `listRepos()` | 列出所有仓库 | `RepoInfo[]` |\n| `removeRepo(path)` | 移除仓库 | `void` |\n| `syncRepo(path)` | 同步仓库状态 | `SyncResult` |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:1-100]()\n\n### 仓库信息模型\n\n```typescript\ninterface RepoInfo {\n id: string; // 唯一标识符\n path: string; // 仓库路径\n name: string; // 仓库名称\n currentBranch: string; // 当前分支\n branches: string[]; // 本地分支列表\n remotes: RemoteInfo[]; // 远程仓库信息\n lastSync: Date; // 最后同步时间\n status: RepoStatus; // 仓库状态\n}\n```\n\n| 状态枚举 | 含义 |\n|----------|------|\n| `active` | 正常工作状态 |\n| `syncing` | 正在同步中 |\n| `error` | 发生错误 |\n| `inactive` | 未激活 |\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:50-150]()\n\n### MCP 上下文关联\n\n仓库管理器与 MCP 模块通过上下文对象关联：\n\n```typescript\n// MCP 上下文配置\ninterface MCPContext {\n repoManager: RepoManager;\n currentRepo: RepoInfo | null;\n workspaceRoots: string[];\n}\n```\n\n这种关联使得 MCP 工具可以自动感知当前仓库上下文，减少重复的参数传递。\n\n资料来源：[gitnexus/src/storage/repo-manager.ts:100-180]()\n\n## 集成流程\n\n### 启动初始化流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用入口\n participant Server as MCP 服务器\n participant Tools as 工具注册器\n participant Resources as 资源注册器\n participant Backend as 本地后端\n participant RepoMgr as 仓库管理器\n \n App->>RepoMgr: 初始化仓库管理器\n App->>Server: 创建 MCP 服务器实例\n Server->>Backend: 初始化本地后端\n Server->>Tools: 注册工具集\n Server->>Resources: 注册资源\n Backend->>RepoMgr: 获取仓库列表\n Tools->>RepoMgr: 绑定仓库上下文\n```\n\n### 工具调用时序\n\n```mermaid\nsequenceDiagram\n participant Client as AI 客户端\n participant Server as MCP 服务器\n participant Tool as 工具处理器\n participant Backend as 本地后端\n participant RepoMgr as 仓库管理器\n participant Git as Git 进程\n \n Client->>Server: 工具调用请求\n Server->>Tool: 解析工具名称\n Tool->>RepoMgr: 获取当前仓库\n Tool->>Backend: 执行操作请求\n Backend->>Git: 调用 Git 命令\n Git-->>Backend: 返回结果\n Backend-->>Tool: 格式化结果\n Tool-->>Server: 返回响应\n Server-->>Client: JSON-RPC 响应\n```\n\n## 配置与扩展\n\n### MCP 服务器配置\n\n```typescript\ninterface MCPServerConfig {\n // 服务器标识\n name: string;\n version: string;\n \n // 连接配置\n transport: 'stdio' | 'http';\n port?: number;\n \n // 功能开关\n features: {\n tools: boolean;\n resources: boolean;\n prompts: boolean;\n };\n \n // 安全配置\n security: {\n allowedPaths: string[];\n blockedCommands: string[];\n };\n}\n```\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `transport` | `string` | `stdio` | 传输协议类型 |\n| `port` | `number` | `3000` | HTTP 端口 |\n| `tools.enabled` | `boolean` | `true` | 启用工具 |\n| `resources.enabled` | `boolean` | `true` | 启用资源 |\n\n### 扩展工具开发\n\n开发者可以通过继承基础工具类来扩展 MCP 工具：\n\n```typescript\n// 自定义工具模板\nclass CustomTool extends BaseTool {\n readonly name = \"custom_tool\";\n readonly description = \"自定义工具描述\";\n \n readonly inputSchema = {\n type: \"object\",\n properties: {\n param1: { type: \"string\" },\n param2: { type: \"number\" }\n },\n required: [\"param1\"]\n };\n \n async execute(params: Record) {\n // 工具逻辑实现\n return { success: true, data: {} };\n }\n}\n```\n\n## 最佳实践\n\n### 性能优化\n\n| 优化项 | 方法 | 收益 |\n|--------|------|------|\n| 缓存结果 | 资源缓存层 | 减少重复调用 |\n| 批处理 | 合并多个操作 | 降低延迟 |\n| 异步执行 | 非阻塞 I/O | 提高吞吐量 |\n| 路径优化 | 相对路径解析 | 减少字符串处理 |\n\n### 错误处理\n\nMCP 模块采用统一的错误处理机制：\n\n```typescript\n// 错误类型分类\nenum MCPErrorCode {\n TOOL_NOT_FOUND = -32601,\n INVALID_PARAMS = -32602,\n EXECUTION_ERROR = -32603,\n RESOURCE_NOT_FOUND = -32604,\n PERMISSION_DENIED = -32605\n}\n```\n\n### 安全建议\n\n1. **路径限制**：始终验证文件路径在工作区内\n2. **命令白名单**：只允许安全的 Git 子命令\n3. **输入验证**：严格校验所有工具参数\n4. **沙箱执行**：考虑使用隔离环境执行危险操作\n\n## 总结\n\nGitNexus 的 MCP 架构通过模块化设计实现了与 AI 助手的深度集成。核心组件包括 MCP 服务器、工具集、资源层和本地后端，它们协同工作，为 AI 提供对 Git 仓库的完整访问能力。仓库管理器作为状态中枢，确保 MCP 能够准确感知当前工作环境。开发者可以通过扩展工具类和注册自定义资源来增强系统功能，同时应遵循安全最佳实践以保护系统完整性。\n\n---\n\n\n\n## 知识图谱构建\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [索引管道](#page-indexing-pipeline), [数据存储](#page-data-storage)\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/ingestion/pipeline-phases/wildcard-synthesis.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.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/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
\n\n# 知识图谱构建\n\n## 概述\n\n知识图谱构建（Knowledge Graph Construction）是 GitNexus 的核心子系统，负责将代码仓库中的源代码转换为可查询的图结构数据。该系统通过多阶段管道（Pipeline）处理，支持多种编程语言的语法解析、符号提取、依赖关系分析以及语义关联构建，最终生成包含节点（Nodes）和关系（Relationships）的知识图谱。\n\n知识图谱的节点代表代码中的各种实体，如函数、类、接口、结构体、枚举等；关系则表示这些实体之间的语义连接，包括导入关系（IMPORTS）、调用关系（CALLS）、继承关系（EXTENDS/IMPLEMENTS）等。资料来源：[gitnexus/src/core/graph/types.ts:1-20]()\n\n## 核心数据模型\n\n### GraphNode（图节点）\n\n图节点是知识图谱的基本元素，每个节点包含以下属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 节点的唯一标识符 |\n| label | string | 节点类型标签，如 Function、Class、Interface 等 |\n| properties | Record | 节点的附加属性 |\n| filePath | string | 节点对应的源文件路径 |\n| name | string | 节点的名称 |\n| codeLocation | CodeLocation | 代码位置信息 |\n\n资料来源：[gitnexus/src/core/graph/types.ts:1-15]()\n\n### GraphRelationship（图关系）\n\n关系连接图中的节点，表示实体之间的关联：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| id | string | 关系的唯一标识符 |\n| type | string | 关系类型，如 IMPORTS、CALLS、EXTENDS |\n| sourceId | string | 源节点 ID |\n| targetId | string | 目标节点 ID |\n| properties | Record | 关系的附加属性 |\n\n资料来源：[gitnexus/src/core/graph/types.ts:15-25]()\n\n### KnowledgeGraph（知识图谱接口）\n\n```typescript\ninterface KnowledgeGraph {\n addNode: (node: GraphNode) => void;\n addRelationship: (relationship: GraphRelationship) => void;\n getNode: (id: string) => GraphNode | undefined;\n removeNode: (nodeId: string) => boolean;\n removeNodesByFile: (filePath: string) => number;\n nodeCount: number;\n relationshipCount: number;\n forEachNode: (fn: (node: GraphNode) => void) => void;\n forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;\n}\n```\n\n资料来源：[gitnexus/src/core/graph/types.ts:25-40]()\n\n## 导入关系处理\n\n### 通配符导入合成\n\n对于采用整体模块导入语义的语言（如 Go、Ruby、C/C++、Swift），GitNexus 实现了通配符导入绑定合成机制。这些语言的导入语句会引入文件中的所有导出符号，而非特定命名符号。\n\n```mermaid\nflowchart TD\n A[源文件] --> B[遍历 IMPORTS 关系]\n B --> C{语言支持通配符?}\n C -->|是| D[获取导出符号集合]\n C -->|否| E[跳过]\n D --> F[为每个导出符号创建绑定]\n F --> G[MAX_SYNTHETIC_BINDINGS 检查]\n G --> H[添加到 namedImportMap]\n```\n\n该机制的核心常量定义如下：\n\n```typescript\nconst MAX_SYNTHETIC_BINDINGS_PER_FILE = 1000;\n```\n\n此限制防止了包含大量大型头文件的 C/C++ 文件导致的内存膨胀问题。资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:1-50]()\n\n### 导入映射构建\n\n系统维护两个核心映射结构：\n\n- **importMap**：记录文件级别的导入关系\n- **namedImportMap**：记录文件级别的命名导入绑定\n\n```typescript\nconst FILE_PREFIX = 'File:';\nconst graphImports = new Map>();\n\ngraph.forEachRelationship((rel) => {\n if (rel.type !== 'IMPORTS') return;\n if (!rel.sourceId.startsWith(FILE_PREFIX) || !rel.targetId.startsWith(FILE_PREFIX)) return;\n // 处理通配符语言...\n});\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:50-80]()\n\n## 继承关系处理\n\n### HeritageMap（继承图谱）\n\n继承关系处理模块负责构建和维护类型继承层次结构，支持 extends 和 implements 两种继承类型。\n\n```mermaid\nflowchart TD\n A[遍历 Heritage 条目] --> B{继承类型?}\n B -->|implements| C[标记为实现类]\n B -->|extends| D[解析扩展类型]\n D --> E{类型为 IMPLEMENTS?}\n E -->|是| C\n E -->|否| F[标记为扩展类]\n C --> G[添加至 implementorFiles]\n F --> G\n```\n\n关键数据结构：\n\n```typescript\ninterface ParentEntry {\n parentName: string;\n kind: 'extends' | 'implements';\n filePath: string;\n}\n\nconst entriesFor = (nodeId: string): readonly ParentEntry[] | undefined =>\n directParents.get(nodeId);\n\nconst getParentEntries = (childNodeId: string): readonly ParentEntry[] => {\n const entries = entriesFor(childNodeId);\n return entries ?? [];\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/model/heritage-map.ts:1-50]()\n\n### HeritageProcessor（继承处理器）\n\n处理器负责从源代码中提取继承关系声明：\n\n```typescript\nconst processHeritage = async (\n files: FileInfo[],\n ctx: ResolutionContext,\n onProgress?: (current: number, total: number) => void,\n) => {\n const parser = await loadParser();\n \n for (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 const language = getLanguageFromFilename(file.path);\n if (!language || !isLanguageAvailable(language)) continue;\n \n // 加载语言并获取 AST...\n }\n};\n```\n\n资料来源：[gitnexus/src/core/ingestion/heritage-processor.ts:1-40]()\n\n## 调用关系处理\n\n### CallProcessor（调用处理器）\n\n调用关系处理模块提取函数调用信息，支持跨文件类型解析：\n\n```mermaid\nflowchart TD\n A[文件列表] --> B[遍历文件]\n B --> C{语言支持?}\n C -->|是| D[加载 AST]\n C -->|否| E[跳过]\n D --> F[执行 Tree-sitter 查询]\n F --> G[提取调用匹配]\n G --> H[构建类型环境]\n H --> I[处理调用关系]\n```\n\n### 跨文件类型传播\n\n系统支持从导入的调用目标传播返回类型：\n\n```typescript\ninterface CallProcessorOptions {\n /** Phase 14 E3: 跨文件返回类型 */\n importedReturnTypesMap?: ReadonlyMap>,\n /** Phase 14 E3: 跨文件原始返回类型 */\n importedRawReturnTypesMap?: ReadonlyMap>,\n /** Phase 14 E2: 导入绑定 */\n importedBindingsMap?: ReadonlyMap>,\n heritageMap?: HeritageMap,\n bindingAccumulator?: BindingAccumulator,\n}\n```\n\n资料来源：[gitnexus/src/core/ingestion/call-processor.ts:1-50]()\n\n## 语言解析支持\n\n### ParserLoader（解析器加载器）\n\nGitNexus 通过 tree-sitter 支持多种编程语言的语法解析：\n\n| 语言 | 解析器包 | 说明 |\n|------|----------|------|\n| TypeScript | tree-sitter-typescript | 支持 .ts 和 .tsx 文件 |\n| Python | tree-sitter-python | Python 语法支持 |\n| Java | tree-sitter-java | Java 语法支持 |\n| C# | tree-sitter-c-sharp | 需要显式子路径导入 |\n| C++ | tree-sitter-cpp | C++ 语法支持 |\n| Go | tree-sitter-go | Go 语法支持 |\n| Ruby | tree-sitter-ruby | Ruby 语法支持 |\n\n```typescript\nconst PARSER_LOADERS: Record = {\n [SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript,\n unavailableNote: 'TS 解析需要 tree-sitter-typescript',\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n unavailableNote: 'Python 解析需要 tree-sitter-python',\n },\n [SupportedLanguages.Java]: {\n load: () => _require('tree-sitter-java'),\n unavailableNote: 'Java 解析需要 tree-sitter-java',\n },\n [SupportedLanguages.CSharp]: {\n load: () => _require('tree-sitter-c-sharp/bindings/node/index.js'),\n unavailableNote: 'C# 解析需要 tree-sitter-c-sharp',\n },\n};\n```\n\n资料来源：[gitnexus/src/core/tree-sitter/parser-loader.ts:1-60]()\n\n### 支持的节点标签类型\n\n以下标签类型代表顶层可导入符号：\n\n```typescript\nconst IMPORTABLE_SYMBOL_LABELS = new Set([\n 'Function',\n 'Class',\n 'Interface',\n 'Struct',\n 'Enum',\n 'Trait',\n 'TypeAlias',\n 'Const',\n 'Static',\n 'Record',\n 'Union',\n 'Typedef',\n 'Macro',\n]);\n```\n\n资料来源：[gitnexus/src/core/ingestion/pipeline-phases/wildcard-synthesis.ts:30-45]()\n\n## 模式提取框架\n\n### HTTP/GRPC 模式提取\n\n系统通过 tree-sitter 查询模式识别特定框架的代码模式：\n\n```mermaid\nflowchart TD\n A[源代码] --> B[Tree-sitter 解析]\n B --> C[编译模式查询]\n C --> D[匹配结果]\n D --> E[提取符号信息]\n E --> F[生成图谱节点]\n```\n\nPHP 模式提取示例：\n\n```typescript\ninterface PhpPatternBundle {\n laravelRoute: CompiledPatterns>;\n httpFacade: CompiledPatterns>;\n guzzleMember: CompiledPatterns>;\n fileGetContents: CompiledPatterns>;\n}\n\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资料来源：[gitnexus/src/core/group/extractors/http-patterns/php.ts:1-50]()\n\n## 构建流程总结\n\n### 完整管道流程\n\n```mermaid\nflowchart TD\n A[源代码文件] --> B[语言检测]\n B --> C[Tree-sitter 解析]\n C --> D[符号提取]\n D --> E[导入关系分析]\n E --> F[继承关系分析]\n F --> G[调用关系分析]\n G --> H[通配符绑定合成]\n H --> I[类型传播]\n I --> J[知识图谱输出]\n \n E -.->|通配符语言| K[wildcard-synthesis.ts]\n F -.->|heritage-map.ts| L[继承图谱]\n G -.->|call-processor.ts| M[调用处理器]\n```\n\n### 核心处理阶段\n\n| 阶段 | 组件 | 功能 |\n|------|------|------|\n| 解析 | parser-loader.ts | 加载 tree-sitter 解析器 |\n| 符号提取 | 服务层 | 提取函数、类、接口等 |\n| 导入处理 | wildcard-synthesis.ts | 处理通配符导入绑定 |\n| 继承分析 | heritage-processor.ts | 提取 extends/implements |\n| 调用分析 | call-processor.ts | 提取函数调用关系 |\n| 图谱构建 | graph.ts/types.ts | 组装节点和关系 |\n\n## 性能优化\n\n### 批处理策略\n\n系统采用批量处理策略避免阻塞事件循环：\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n const file = files[i];\n if (i % 20 === 0) await yieldToEventLoop(); // 每20个文件让出控制权\n \n // 处理文件...\n}\n```\n\n### 缓存机制\n\nAST 树被缓存以避免重复解析：\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/ingestion/heritage-processor.ts:20-35]()\n\n### 大文件处理\n\n对于超过 32KB 的大文件，系统使用更大的缓冲区：\n\n```typescript\n// Use larger bufferSize for files > 32KB\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\n```\n\n## 配置与扩展\n\n### 语言提供者注册\n\n新语言支持通过语言提供者接口注册：\n\n```typescript\nimport { providers, getProviderForFile } from '../languages/index.js';\nimport type { LanguageProvider, ImportSemantics } from '../language-provider.js';\n```\n\n### 自定义模式添加\n\n添加新的代码模式提取需要：\n\n1. 在对应语言的 `*-patterns/` 目录下创建新文件\n2. 定义 PatternSpec 结构\n3. 在 `index.ts` 中注册新模式\n4. 无需修改管道编排代码\n\n资料来源：[gitnexus/src/core/group/PIPELINE.md:1-30]()\n\n---\n\n\n\n## 索引管道\n\n### 相关页面\n\n相关主题：[知识图谱构建](#page-knowledge-graph), [多语言支持](#page-multilanguage-support)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/core/ingestion/pipeline.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/scan.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/scan.ts)\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/src/core/ingestion/pipeline-phases/structure.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/structure.ts)\n- [gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/pipeline-phases/cross-file.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/resolve-references.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/resolve-references.ts)\n
\n\n# 索引管道\n\n## 概述\n\n索引管道（Ingestion Pipeline）是 GitNexus 的核心处理引擎，负责将源代码仓库转换为结构化的知识图谱。该管道通过多个阶段的顺序执行，完成文件扫描、AST 解析、作用域提取、跨文件引用解析，最终生成可用于可视化与分析的依赖图数据。\n\n索引管道遵循 RFC #909 定义的摄取生命周期规范，采用 Ring 2 架构设计，实现了解析逻辑与业务逻辑的分离。\n\n## 架构总览\n\n索引管道采用阶段式（Phase-Based）架构，每个阶段负责特定的摄取任务，并通过依赖声明定义执行顺序。\n\n```mermaid\ngraph TD\n A[开始摄取] --> B[structure 阶段]\n B --> C[scan 阶段]\n C --> D[parse 阶段]\n D --> E[cross-file 阶段]\n E --> F[resolve-references 阶段]\n F --> G[emit-references 阶段]\n G --> H[完成: 知识图谱]\n \n B -.->|依赖| D\n```\n\n### 核心设计原则\n\n| 原则 | 说明 |\n|------|------|\n| **阶段解耦** | 每个阶段独立执行，通过明确定义的输入输出接口通信 |\n| **增量处理** | 支持文件级别的增量解析，避免全量重解析 |\n| **并行友好** | 阶段内部可并行处理独立文件 |\n| **容错设计** | 单文件解析失败不影响整体管道执行 |\n\n资料来源：[pipeline.ts](gitnexus/src/core/ingestion/pipeline.ts)\n\n## 管道阶段详解\n\n### 阶段 1：structure（结构分析）\n\n`structure` 阶段是管道的入口点，负责扫描仓库目录结构并识别所有待处理文件。\n\n**职责**：\n- 递归遍历仓库目录\n- 过滤构建产物和二进制文件\n- 识别支持的编程语言文件\n- 生成文件元数据列表\n\n**输出**：\n- `scannedFiles`: 待解析文件的完整列表\n- `allPaths`: 所有文件路径集合\n- `allPathSet`: 用于快速查找的路径集合\n\n资料来源：[pipeline-phases/structure.ts](gitnexus/src/core/ingestion/pipeline-phases/structure.ts)\n\n### 阶段 2：scan（扫描）\n\n`scan` 阶段在 structure 阶段完成后执行，生成文件索引和元数据。\n\n**职责**：\n- 生成文件唯一标识符\n- 提取文件基础信息（大小、修改时间）\n- 构建文件索引结构\n\n### 阶段 3：parse（解析）\n\n`parse` 阶段是管道中计算密集度最高的阶段，负责将源代码转换为 AST 并提取基础语义信息。\n\n**依赖阶段**：`structure`、`markdown`、`cobol`\n\n**核心流程**：\n\n```mermaid\ngraph TD\n A[获取扫描文件列表] --> B[按语言分组]\n B --> C{for each file}\n C --> D{检查语言支持}\n D -->|不支持| E[跳过文件]\n D -->|支持| F[加载 Tree-sitter 语言]\n F --> G[生成 AST]\n G --> H{缓存命中?}\n H -->|否| I[应用预处理器]\n I --> J[解析源码]\n J --> K[缓存 AST]\n K --> L[执行 tree-sitter 查询]\n L --> M[提取捕获匹配]\n M --> N[ScopeExtractor]\n N --> O[生成 ParsedFile]\n O --> P{更多文件?}\n P -->|是| C\n P -->|否| Q[返回解析结果]\n \n E --> P\n```\n\n**核心函数**：`runChunkedParseAndResolve`\n\n该函数协调文件解析和作用域解析的完整流程：\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**输出**：\n- `parsedFiles`: `ParsedFile[]` 数组，每个源文件对应一个\n- `allPaths`、`allPathSet`、`totalFiles`: 传递给后续阶段的上下文\n\n资料来源：[pipeline-phases/parse.ts](gitnexus/src/core/ingestion/pipeline-phases/parse.ts)\n\n### 阶段 4：cross-file（跨文件分析）\n\n`cross-file` 阶段在 parse 阶段完成后执行，处理跨文件的依赖关系和引用解析。\n\n**职责**：\n- 解析 `import`/`require` 语句\n- 建立跨文件符号引用\n- 处理包级别依赖\n\n**输入**：`ParsedFile[]`（parse 阶段输出）\n\n**输出**：\n- 跨文件引用关系图\n- 解析后的导入边（ImportEdge）\n\n资料来源：[pipeline-phases/cross-file.ts](gitnexus/src/core/ingestion/pipeline-phases/cross-file.ts)\n\n### 阶段 5：resolve-references（引用解析）\n\n`resolve-references` 阶段负责将符号引用解析为具体的节点标识符。\n\n**职责**：\n- 解析符号引用到具体节点\n- 构建引用索引（ReferenceIndex）\n- 计算引用置信度\n\n**语义模型**：\n\n```\nReferenceIndex\n └── referenceSites: 预解析的使用事实\n └── 由 resolve-references 填充\n```\n\n该阶段使用 `ResolutionContext` 上下文进行符号解析，包含：\n- 文件路径映射\n- 符号表\n- 作用域信息\n\n资料来源：[resolve-references.ts](gitnexus/src/core/ingestion/resolve-references.ts)\n\n### 阶段 6：emit-references（发射引用）\n\n`emit-references` 是 RFC #909 生命周期中的第 5 阶段，负责将 `ReferenceIndex` 中的引用数据物化为知识图谱中的边。\n\n**职责**：\n- 将引用记录转换为 `GraphRelationship`\n- 计算置信度和证据信息\n- 发射带标签的边到图数据库\n\n**发射的边类型**：\n\n| 边类型 | 源类型 | 说明 |\n|--------|--------|------|\n| `CALLS` | 引用.kind = 'call' | 函数调用关系 |\n| `ACCESSES` | 引用.kind = 'read' / 'write' | 变量访问关系 |\n| `INHERITS` | 引用.kind = 'inherits' | 继承关系 |\n| `USES` | 引用.kind = 'type-reference' / 'import-use' | 类型使用或导入使用 |\n\n**证据属性**：\n- `confidence`: 预计算的置信度分数\n- `reason`: 人类可读的原因描述\n- `evidence`: `ResolutionEvidence[]` 追踪轨迹\n- `step`: 访问类型的区分标记\n\n```typescript\ngraph.addRelationship({\n id: generateId(relType, `${child.id}->${parent.id}`),\n sourceId: child.id,\n targetId: parent.id,\n type: relType,\n confidence: Math.sqrt(child.confidence * parent.confidence),\n reason: '',\n});\n```\n\n资料来源：[emit-references.ts](gitnexus/src/core/ingestion/emit-references.ts)\n\n## ScopeExtractor 作用域提取器\n\n`ScopeExtractor` 是 parse 阶段的核心组件，负责将语言提供商的 `CaptureMatch[]` 转换为 `ParsedFile`。\n\n### 设计原则\n\n| 原则 | 说明 |\n|------|------|\n| **源无关** | 消费 `CaptureMatch[]`，不关心其来自 tree-sitter 查询还是 COBOL 正则标记器 |\n| **单次 AST 遍历** | 提供商的 `emitScopeCaptures` 钩子内部完成 AST 遍历，驱动代码不再遍历 |\n| **纯函数** | 相同的匹配输入产生相同的 ParsedFile 输出 |\n| **集中不变式** | 由 `buildScopeTree`（Ring 2 SHARED #912）强制执行结构不变式 |\n\n### 五阶段处理管道\n\n`ScopeExtractor` 内部执行一个五阶段管道，每个阶段处理特定的职责：\n\n```mermaid\nflowchart TD\n A[CaptureMatch 输入] --> B[阶段1: 构建作用域树]\n B --> C[阶段2: 收集绑定]\n C --> D[阶段3: 解析导入]\n D --> E[阶段4: 构建引用站点]\n E --> F[阶段5: 生成 ParsedFile]\n F --> G[ParsedFile 输出]\n```\n\n### ParsedFile 数据结构\n\n```typescript\ninterface ParsedFile {\n scopes: Scope[]; // 文件中所有作用域，按拓扑顺序排列\n parsedImports: ParsedImport[]; // 原始导入信息\n localDefs: SymbolDef[]; // 文件内声明的定义\n referenceSites: ReferenceSite[]; // 预解析的使用事实\n}\n```\n\n**`ParsedFile` 不携带的内容**：\n- 链接后的 `ImportEdge`（那是 finalize 输出）\n- `ScopeTree` 实例（调用方通过 `buildScopeTree(parsedFile.scopes)` 构建）\n\n资料来源：[scope-extractor.ts](gitnexus/src/core/ingestion/scope-extractor.ts)\n\n## HeritageProcessor 继承关系处理\n\n`heritage-processor` 负责处理类继承和接口实现关系。\n\n### 处理类型\n\n| 关系类型 | 源符号 | 目标符号 | 边类型 |\n|----------|--------|----------|--------|\n| `extends` | 子类 | 父类 | `EXTENDS` |\n| `implements` | 实现类 | 接口 | `IMPLEMENTS` |\n\n### 核心逻辑\n\n```mermaid\ngraph TD\n A[HeritageEntry] --> B{关系类型}\n B -->|extends| C[resolveExtendsType]\n B -->|implements| D[isImpl = true]\n \n C --> E{语言类型}\n E -->|Ruby| F[特殊策略]\n E -->|其他| G[默认策略]\n \n D --> H[resolveHeritageId]\n F --> H\n G --> H\n \n H --> I[generateId]\n I --> J[addRelationship to Graph]\n```\n\n**置信度计算**：\n```typescript\nconfidence: Math.sqrt(child.confidence * parent.confidence)\n```\n\n使用几何平均数确保两端节点置信度都高时关系置信度才高。\n\n### HeritageMap 数据结构\n\n```typescript\nconst entriesFor = (nodeId: string): readonly ParentEntry[] | undefined =>\n directParents.get(nodeId);\n\nconst getParentEntries = (childNodeId: string): readonly ParentEntry[] => {\n const entries = entriesFor(childNodeId);\n return entries ?? [];\n};\n\nconst getParents = (childNodeId: string): string[] => {\n const entries = entriesFor(childNodeId);\n if (!entries) return [];\n // 去重逻辑确保平坦字符串契约保持一致\n};\n```\n\n资料来源：[heritage-map.ts](gitnexus/src/core/ingestion/heritage-map.ts)\n\n## WorkspaceResolutionIndex 工作区解析索引\n\n`WorkspaceResolutionIndex` 是跨文件解析所需的快速查找数据结构。\n\n### 接口定义\n\n```typescript\ninterface WorkspaceResolutionIndex {\n /** 类定义 nodeId → 该类的 Scope */\n readonly classScopeByDefId: ReadonlyMap;\n \n /** classScopeByDefId 的逆映射：Scope.id → 类定义 nodeId */\n readonly classScopeIdToDefId: ReadonlyMap;\n \n /** 按文件路径索引的模块作用域 */\n readonly moduleScopeByFile: ReadonlyMap;\n}\n```\n\n### 索引构建\n\n```typescript\nfunction 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) \n 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**构建成本**：O(totalScopes)\n\n资料来源：[workspace-index.ts](gitnexus/src/core/ingestion/scope-resolution/workspace-index.ts)\n\n## 注册表主语言 vs 非主语言\n\nGitNexus 采用注册表（Registry）机制区分语言处理能力。\n\n### 处理策略\n\n| 类别 | 说明 | 处理方 |\n|------|------|--------|\n| **注册表主语言** | 拥有完整作用域解析的语言 | scope-resolution 管道处理 CALLS |\n| **非注册表主语言** | 仅支持基础解析的语言 | `call-processor.ts` 处理 CALLS |\n\n### 跳过逻辑\n\n在 `call-processor.ts` 中：\n\n```typescript\n// Registry-primary gate: scope-based phase owns CALLS for this lang.\nif (isRegistryPrimary(language)) continue;\n```\n\n这确保了注册表主语言不会产生重复的调用边。\n\n## 进度报告与事件循环让渡\n\n管道执行过程中支持进度回调和事件循环让渡，以确保 UI 保持响应。\n\n### 进度回调模式\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n onProgress?.(i + 1, files.length);\n \n // 每 20 个文件让渡一次事件循环\n if (i % 20 === 0) await yieldToEventLoop();\n}\n```\n\n### 语言统计\n\n当启用详细摄取日志时，会跟踪被跳过的语言及文件数：\n\n```typescript\nif (logSkipped) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n}\n```\n\n## 错误处理策略\n\n管道采用**隔离失败**策略：\n\n1. **文件级隔离**：单个文件解析失败不影响其他文件\n2. **阶段级隔离**：阶段依赖链中断时终止管道\n3. **语言级跳过**：不支持的语言文件被静默跳过\n\n```typescript\ntry {\n tree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent),\n });\n} catch (parseError) {\n continue; // 跳过此文件，继续处理下一个\n}\n```\n\n## 缓存机制\n\n管道实现了两级缓存策略：\n\n| 缓存层级 | 内容 | 键 |\n|----------|------|-----|\n| AST 缓存 | 解析后的语法树 | 文件路径 |\n| 语言缓存 | Tree-sitter 语言实例 | 语言标识符 |\n\n```typescript\nlet tree = astCache.get(file.path);\nif (!tree) {\n // 解析并缓存\n astCache.set(file.path, tree);\n}\n```\n\n## 配置选项\n\n| 选项 | 类型 | 说明 |\n|------|------|------|\n| `verbose` | `boolean` | 启用详细日志 |\n| `onProgress` | `function` | 进度回调函数 |\n| `treeCache` | `Map` | AST 缓存实例 |\n| `options` | `PipelineOptions` | 管道级配置 |\n\n## 总结\n\n索引管道是 GitNexus 将源代码转换为知识图谱的核心引擎。通过六阶段的顺序执行（structure → scan → parse → cross-file → resolve-references → emit-references），管道实现了：\n\n- **完整性**：支持多语言的代码解析\n- **准确性**：通过作用域解析和引用解析建立精确的依赖关系\n- **可扩展性**：通过注册表机制支持新语言的增量添加\n- **容错性**：隔离失败策略确保管道健壮运行\n\n管道的输出是可直接用于可视化的知识图谱数据，支持项目依赖分析、影响范围评估和代码库结构探索等高级功能。\n\n---\n\n\n\n## CLI 命令详解\n\n### 相关页面\n\n相关主题：[快速开始](#page-quick-start), [MCP 架构与集成](#page-mcp-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [gitnexus/src/cli/index.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/index.ts)\n- [gitnexus/src/cli/analyze.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/analyze.ts)\n- [gitnexus/src/cli/serve.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/serve.ts)\n- [gitnexus/src/cli/mcp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/mcp.ts)\n- [gitnexus/src/cli/group.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/group.ts)\n- [gitnexus/src/cli/wiki.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/wiki.ts)\n- [gitnexus/src/cli/setup.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/cli/setup.ts)\n
\n\n# CLI 命令详解\n\n## 概述\n\nGitNexus CLI 是该项目的命令行工具集，提供了一系列用于仓库分析、文档生成、代码服务的技术命令。CLI 模块位于 `gitnexus/src/cli/` 目录下，采用模块化架构设计，每个命令对应独立的子模块，便于维护和扩展。\n\nCLI 工具主要用于自动化仓库分析、生成技术文档、启动本地开发服务等场景，是 GitNexus 项目的核心交互接口之一。\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[index.ts]\n B --> C[analyze 命令]\n B --> D[serve 命令]\n B --> E[mcp 命令]\n B --> F[group 命令]\n B --> G[wiki 命令]\n B --> H[setup 命令]\n \n C --> I[仓库分析引擎]\n D --> J[本地服务器]\n E --> K[MCP 协议服务]\n F --> L[分组管理]\n G --> M[文档生成器]\n H --> N[初始化配置]\n```\n\n## 命令模块详解\n\n### 1. setup 命令\n\nsetup 命令用于初始化 GitNexus 项目配置，是用户首次使用该工具的入口命令。该命令会引导用户完成必要的配置步骤，包括设置 API 密钥、配置仓库路径等基础参数。\n\nsetup 命令支持交互式配置流程，通过命令行提示获取用户输入，并将配置持久化到本地配置文件中。配置文件通常位于用户主目录下的隐藏文件夹中。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| --force | boolean | 否 | 强制重新初始化配置 |\n| --config | string | 否 | 指定配置文件路径 |\n\n资料来源：[gitnexus/src/cli/setup.ts:1-50]()\n\n### 2. analyze 命令\n\nanalyze 命令是 GitNexus 的核心分析引擎，用于深度扫描和分析 Git 仓库。该命令能够提取仓库结构、代码复杂度、依赖关系等关键信息，为后续的文档生成和可视化提供数据基础。\n\nanalyze 命令支持多种分析模式，包括增量分析和全量分析，可以根据仓库规模选择合适的分析策略。\n\n```typescript\ninterface AnalyzeOptions {\n path: string; // 仓库路径\n depth: number; // 分析深度\n includeDeps: boolean; // 是否包含依赖分析\n output: string; // 输出格式\n}\n```\n\n| 参数 | 缩写 | 类型 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| --path | -p | string | 当前目录 | 指定分析的仓库路径 |\n| --depth | -d | number | 3 | 代码分析深度级别 |\n| --include-deps | 无 | boolean | false | 是否分析项目依赖 |\n| --output | -o | string | json | 输出格式支持 json/markdown/html |\n\n资料来源：[gitnexus/src/cli/analyze.ts:1-80]()\n\n### 3. serve 命令\n\nserve 命令启动一个本地 HTTP 服务器，用于提供仓库分析结果的可视化访问。该服务默认运行在本地 3000 端口，支持热更新和实时预览功能。\n\nserve 命令集成了静态文件服务和 API 代理功能，可以通过配置文件自定义端口、域名和路由规则。\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| port | 3000 | 服务监听端口 |\n| host | localhost | 服务绑定地址 |\n| staticDir | ./dist | 静态资源目录 |\n| enableCors | true | 是否启用跨域支持 |\n\n资料来源：[gitnexus/src/cli/serve.ts:1-60]()\n\n### 4. mcp 命令\n\nmcp 命令实现了 Model Context Protocol（MCP）协议服务，允许 GitNexus 与外部 AI 模型进行标准化通信。该命令将仓库分析结果转换为 AI 模型可理解的上下文格式。\n\nmcp 服务支持多种协议版本，提供了标准化的接口定义，便于集成到各种 AI 开发工作流中。\n\n```mermaid\ngraph LR\n A[GitNexus 仓库] --> B[mcp 服务]\n B --> C[上下文转换]\n C --> D[AI 模型]\n D --> E[智能分析结果]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| --protocol | string | MCP 协议版本 |\n| --port | number | MCP 服务端口 |\n| --endpoint | string | AI 模型端点 |\n\n资料来源：[gitnexus/src/cli/mcp.ts:1-70]()\n\n### 5. group 命令\n\ngroup 命令用于管理仓库中的代码分组和模块组织。该命令支持创建、编辑、删除分组，并能够根据代码特征自动进行分组建议。\n\ngroup 功能特别适用于大型仓库的结构化管理，能够帮助团队维护清晰的代码组织架构。\n\n| 操作 | 说明 |\n|------|------|\n| create | 创建新的代码分组 |\n| list | 列出所有分组 |\n| update | 更新分组信息 |\n| delete | 删除指定分组 |\n| analyze | 分析分组合理性 |\n\n资料来源：[gitnexus/src/cli/group.ts:1-55]()\n\n### 6. wiki 命令\n\nwiki 命令是 GitNexus 的文档生成核心模块，能够根据仓库结构和代码分析结果自动生成技术文档。该命令支持多种输出格式，包括 Markdown、HTML 和 PDF。\n\nwiki 生成器具有高度可定制性，支持自定义模板和样式，能够满足不同团队的文档规范要求。\n\n```mermaid\ngraph TD\n A[代码分析数据] --> B[模板引擎]\n C[自定义模板] --> B\n B --> D[文档渲染]\n D --> E[Markdown 输出]\n D --> F[HTML 输出]\n D --> G[PDF 输出]\n```\n\n| 模板变量 | 说明 | 示例 |\n|----------|------|------|\n| {{title}} | 文档标题 | 项目名称 |\n| {{toc}} | 目录结构 | 自动生成 |\n| {{api_docs}} | API 文档 | 接口说明 |\n| {{code_examples}} | 代码示例 | 引用注释 |\n\n资料来源：[gitnexus/src/cli/wiki.ts:1-90]()\n\n## 命令行接口结构\n\nCLI 采用主-子命令结构设计，通过 `yargs` 或 `commander` 框架实现参数解析和命令路由。主入口文件负责全局选项处理和命令分发。\n\n```typescript\ninterface CliCommand {\n command: string; // 命令名称\n describe: string; // 命令描述\n handler: Function; // 命令处理函数\n builder: Function; // 参数构建器\n}\n```\n\n主命令支持以下全局选项：\n\n| 全局选项 | 说明 |\n|----------|------|\n| --verbose | 输出详细日志信息 |\n| --quiet | 静默模式，仅输出错误 |\n| --config | 指定配置文件路径 |\n| --version | 显示版本信息 |\n| --help | 显示帮助信息 |\n\n资料来源：[gitnexus/src/cli/index.ts:1-100]()\n\n## 工作流程示例\n\n### 完整分析并生成文档流程\n\n```bash\n# 第一步：初始化配置\ngitnexus setup\n\n# 第二步：分析仓库\ngitnexus analyze --path ./my-repo --depth 4 --include-deps\n\n# 第三步：生成分组\ngitnexus group analyze\n\n# 第四步：生成文档\ngitnexus wiki generate --output ./docs\n\n# 第五步：启动预览服务\ngitnexus serve --port 8080\n```\n\n### MCP 集成工作流\n\n```bash\n# 启动 MCP 服务\ngitnexus mcp --port 9090 --protocol v1\n\n# 在 AI 工具中使用 MCP 端点\nmcp-client connect http://localhost:9090/mcp\n```\n\n## 配置管理\n\nCLI 工具使用统一的配置管理系统，支持多环境配置切换。配置文件采用 YAML 格式存储，包含 API 密钥、仓库路径、分析规则等核心配置项。\n\n| 配置作用域 | 优先级 | 说明 |\n|------------|--------|------|\n| global | 最低 | 系统级全局配置 |\n| user | 中等 | 用户主目录配置 |\n| project | 最高 | 当前项目本地配置 |\n\n配置加载顺序按照上述优先级依次覆盖，高优先级配置会覆盖低优先级的同名配置项。\n\n## 错误处理机制\n\nCLI 实现了统一的错误处理和报告机制，对不同类型的错误进行了分类处理：\n\n| 错误类型 | 错误代码 | 处理策略 |\n|----------|----------|----------|\n| 配置错误 | E100-E199 | 提示用户检查配置文件 |\n| 分析错误 | E200-E299 | 输出详细错误堆栈 |\n| 服务错误 | E300-E399 | 尝试自动恢复或提示重启 |\n| 权限错误 | E400-E499 | 提示检查文件权限 |\n\n所有错误都会生成唯一的错误代码，便于用户搜索解决方案和团队进行技术支持。\n\n## 扩展开发指南\n\n开发者可以通过扩展 CLI 模块来添加自定义命令。扩展命令需要遵循以下规范：\n\n1. 在 `gitnexus/src/cli/` 目录下创建新的命令文件\n2. 实现命令处理函数和参数定义\n3. 在 `index.ts` 中注册新命令\n4. 为新命令编写单元测试\n\n扩展命令的标准化接口确保了与现有系统的良好兼容性，便于社区贡献和功能迭代。\n\n---\n\n\n\n## 多语言支持\n\n### 相关页面\n\n相关主题：[索引管道](#page-indexing-pipeline)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/languages/c-cpp.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/c-cpp.ts)\n- [gitnexus/src/core/ingestion/languages/php.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/php.ts)\n- [gitnexus/src/core/ingestion/languages/java.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/java.ts)\n- [gitnexus/src/core/ingestion/languages/python.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/python.ts)\n- [gitnexus/src/core/ingestion/languages/typescript.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/typescript.ts)\n- [gitnexus/src/core/ingestion/languages/go.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/ingestion/languages/go.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/group/extractors/tree-sitter-scanner.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/group/extractors/tree-sitter-scanner.ts)\n
\n\n# 多语言支持\n\n## 概述\n\nGitNexus 的多语言支持系统是代码图谱分析引擎的核心基础设施，负责统一处理不同编程语言的代码解析、抽象语法树（AST）构建、符号提取和依赖关系分析。该系统通过 tree-sitter 作为底层解析引擎，结合语言特定的查询配置（tree-sitter queries）和插件化架构，实现了对 11 种主流编程语言的完整支持。\n\n多语言支持的核心价值在于提供**一致的代码理解接口**：无论源代码是 TypeScript、Python 还是 Rust，GitNexus 都能通过统一的语言提供者（Language Provider）抽象进行解析和特征提取，最终生成统一的代码图谱数据结构。\n\n资料来源：[parser-loader.ts:1-100]()\n\n## 支持的语言\n\nGitNexus 当前支持以下 11 种编程语言：\n\n| 语言 | 文件扩展名 | tree-sitter 语法包 | 特殊配置 |\n|------|-----------|-------------------|----------|\n| JavaScript | `.js`, `.mjs`, `.cjs` | `tree-sitter-javascript` | 无 |\n| TypeScript | `.ts` | `tree-sitter-typescript.typescript` | 共享语法包 |\n| TSX | `.tsx` | `tree-sitter-typescript.tsx` | 共享语法包 |\n| Python | `.py` | `tree-sitter-python` | 无 |\n| Java | `.java` | `tree-sitter-java` | 无 |\n| C# | `.cs` | `tree-sitter-c-sharp` | 特殊 ESM 加载路径 |\n| C/C++ | `.c`, `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` | `tree-sitter-cpp` | 宏预处理支持 |\n| Go | `.go` | `tree-sitter-go` | 无 |\n| Rust | `.rs` | `tree-sitter-rust` | 无 |\n| PHP | `.php`, `.phtml`, `.php3`, `.php4`, `.php5`, `.php8` | `tree-sitter-php` | Composer 依赖解析 |\n| Ruby | `.rb` | `tree-sitter-ruby` | 无 |\n| Vue | `.vue` | 复用 TypeScript 语法 | 特殊解析逻辑 |\n\n资料来源：[parser-loader.ts:32-90]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n subgraph \"语言加载层\"\n PL[ParserLoader]\n SL[SupportedLanguages 枚举]\n end\n \n subgraph \"语言提供者层\"\n LP[LanguageProvider 实例]\n TC[Tree-sitter Queries]\n IC[Import Config]\n EC[Export Checker]\n end\n \n subgraph \"处理器层\"\n CP[CallProcessor]\n HP[HeritageProcessor]\n FP[FieldProcessor]\n end\n \n subgraph \"解析层\"\n TSP[Tree-sitter Parser]\n AST[AST Cache]\n end\n \n PL --> |加载语法| TSP\n SL --> |语言标识| LP\n LP --> |提供查询和配置| CP\n LP --> |提供查询和配置| HP\n CP --> |解析文件| TSP\n TSP --> |缓存 AST| AST\n```\n\n### 核心组件\n\n#### SupportedLanguages 枚举\n\n定义了所有支持的语言标识符，作为系统内部语言识别的唯一标识：\n\n```typescript\nenum SupportedLanguages {\n JavaScript = 'javascript',\n TypeScript = 'typescript',\n Python = 'python',\n Java = 'java',\n CSharp = 'c-sharp',\n CPlusPlus = 'c-plus-plus',\n Go = 'go',\n Rust = 'rust',\n PHP = 'php',\n Ruby = 'ruby',\n Vue = 'vue'\n}\n```\n\n#### GrammarSource 配置\n\n每个语言在 `parser-loader.ts` 中定义了一个 `GrammarSource` 配置对象：\n\n```typescript\nconst SOURCES: Record = {\n [SupportedLanguages.JavaScript]: {\n load: () => _require('tree-sitter-javascript'),\n unavailableNote: 'JavaScript parsing requires `tree-sitter-javascript`...',\n severity: 'error' // 关键依赖\n },\n [SupportedLanguages.Python]: {\n load: () => _require('tree-sitter-python'),\n unavailableNote: 'Python parsing requires `tree-sitter-python`...'\n },\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 // C# 有特殊的 ESM 加载路径问题处理\n }\n};\n```\n\n#### LanguageProvider 接口\n\n语言提供者定义了每个语言的解析配置：\n\n```typescript\ninterface LanguageProvider {\n id: SupportedLanguages;\n extensions: string[]; // 文件扩展名\n entryPointPatterns: RegExp[]; // 入口点识别\n astFrameworkPatterns?: AstFrameworkPatternConfig[]; // 框架检测\n treeSitterQueries: string; // tree-sitter 查询\n typeConfig: TypeConfig; // 类型配置\n exportChecker: ExportChecker; // 导出检查\n importResolver: ImportResolver; // 导入解析\n callExtractor: CallExtractor; // 函数调用提取\n fieldExtractor: FieldExtractor; // 字段提取\n methodExtractor: MethodExtractor; // 方法提取\n variableExtractor: VariableExtractor; // 变量提取\n classExtractor?: ClassExtractor; // 类提取\n heritageExtractor?: HeritageExtractor; // 继承关系提取\n}\n```\n\n资料来源：[c-cpp.ts:1-50]()\n\n## 语言处理流程\n\n### 文件解析流程\n\n```mermaid\nsequenceDiagram\n participant U 作为用户\n participant CP 作为 CallProcessor\n participant L 作为 Loader\n participant TSP 作为 TreeSitter\n participant Cache 作为 AST Cache\n \n U->>CP: 处理文件列表\n CP->>CP: 遍历文件，每 20 个 yield\n CP->>L: getLanguageFromFilename(path)\n L-->>CP: 返回语言标识\n CP->>L: isLanguageAvailable(lang)\n alt 语言不可用\n CP->>CP: 记录跳过并继续\n end\n CP->>Cache: astCache.get(file.path)\n alt 缓存命中\n Cache-->>CP: 返回缓存的 AST\n else 缓存未命中\n CP->>TSP: parseSourceSafe(parser, content)\n TSP-->>CP: 返回解析结果\n CP->>Cache: astCache.set(file.path, tree)\n end\n CP->>CP: 执行 tree-sitter 查询匹配\n CP->>CP: 提取符号和关系\n```\n\n### 继承关系处理\n\n不同语言对类继承关系的处理方式不同：\n\n```typescript\n// heritage-processor.ts 中的语言特定策略\nconst getHeritageStrategyForLanguage = (lang: SupportedLanguages): HeritageStrategy => {\n switch (lang) {\n case SupportedLanguages.Ruby:\n return 'ruby-mro'; // Ruby 使用 MRO 线性化\n default:\n return 'c3-linearization'; // 其他语言使用 C3 线性化\n }\n};\n```\n\n资料来源：[heritage-processor.ts:60-80]()\n\n## 语言特定配置\n\n### C/C++ 语言支持\n\nC/C++ 提供者具有最复杂的配置，包括宏处理和类内函数识别：\n\n```typescript\nexport const cProvider = defineLanguage({\n id: SupportedLanguages.C,\n extensions: ['.c'],\n entryPointPatterns: [\n /^main$/, // 标准入口点\n /^init_/, // 初始化函数\n /_init$/,\n /^run_/, // 运行函数\n /_run$/,\n /^handle_/, // 处理器\n /_handler$/,\n /_callback$/,\n // ... 更多模式\n ],\n treeSitterQueries: C_QUERIES,\n typeConfig: cCppConfig,\n exportChecker: cCppExportChecker,\n importResolver: createImportResolver(cImportConfig),\n importSemantics: 'wildcard-transitive', // C 支持通配符导入传递\n callExtractor: createCallExtractor(cCallConfig),\n fieldExtractor: createFieldExtractor(cFieldConfig),\n methodExtractor: createMethodExtractor({\n ...cMethodConfig,\n extractFunctionName: cCppExtractFunctionName // 特殊函数名提取\n }),\n variableExtractor: createVariableExtractor(cVariableConfig),\n classExtractor: cClassExtractor,\n heritageExtractor: createHeritageExtractor(SupportedLanguages.C)\n});\n```\n\n关键特性：\n\n- **标签覆盖**：类内函数标签设为 `null`，避免重复标记\n- **通配符传递**：`importSemantics: 'wildcard-transitive'` 支持 `#include <*.h>` 风格的传递解析\n\n资料来源：[c-cpp.ts:50-120]()\n\n### PHP 语言支持\n\nPHP 提供者包含 Laravel 框架检测和 Composer 依赖解析：\n\n```typescript\nexport const phpProvider = defineLanguage({\n id: SupportedLanguages.PHP,\n extensions: ['.php', '.phtml', '.php3', '.php4', '.php5', '.php8'],\n entryPointPatterns: [\n /Controller$/, // MVC 控制器\n /^handle$/, /^execute$/, /^boot$/, /^register$/,\n /^__invoke$/,\n // RESTful 路由方法\n /^(index|show|store|update|destroy|create|edit)$/,\n /^(get|post|put|delete|patch)[A-Z]/,\n // 更多模式...\n ],\n astFrameworkPatterns: [\n {\n framework: 'laravel',\n entryPointMultiplier: 3.0, // Laravel 路由权重提升 3 倍\n reason: 'php-route-attribute',\n patterns: [\n 'Route::get', 'Route::post', 'Route::put',\n 'Route::delete', 'Route::resource', 'Route::apiResource',\n '#[Route('\n ]\n }\n ],\n treeSitterQueries: PHP_QUERIES,\n typeConfig: phpConfig,\n exportChecker: phpExportChecker,\n importResolver: createImportResolver(phpImportConfig),\n namedBindingExtractor: extractPhpNamedBindings,\n callExtractor: createCallExtractor(phpCallConfig),\n fieldExtractor: createFieldExtractor(phpFieldConfig),\n methodExtractor: createMethodExtractor(phpMethodConfig),\n variableExtractor: createVariableExtractor(phpVariableConfig),\n classExtractor: createClassExtractor(phpClassConfig),\n heritageExtractor: createHeritageExtractor(SupportedLanguages.PHP)\n});\n```\n\n#### PHP 导入解析\n\nPHP 的导入解析支持 Composer autoload 配置：\n\n```typescript\nexport function resolvePhpImportTargetInternal(\n targetRaw: string,\n _fromFile: string,\n allFilePaths: ReadonlySet,\n resolutionConfig?: unknown\n): string | null {\n const composerConfig = resolutionConfig as ComposerConfig | null;\n const allFiles = allFilePaths as Set;\n const normalizedFileList = [...allFiles].map((f) => f.replace(/\\\\/g, '/'));\n const allFileList = [...allFiles];\n\n return resolvePhpImportInternal(\n targetRaw,\n composerConfig,\n allFiles,\n normalizedFileList,\n allFileList,\n undefined\n );\n}\n```\n\n资料来源：[php.ts:30-100]()\n资料来源：[import-target.ts:40-80]()\n\n### Python 语言支持\n\nPython 提供者针对 Python 3 类型注解和模块系统进行了优化配置。\n\n### TypeScript 语言支持\n\nTypeScript 提供者支持类型注解解析，并与 TSX 共享语法包：\n\n```typescript\n// TypeScript 和 TSX 共享同一个语法包\n[SupportedLanguages.TypeScript]: {\n load: () => _require('tree-sitter-typescript').typescript\n},\n[`${SupportedLanguages.TypeScript}:tsx`]: {\n load: () => _require('tree-sitter-typescript').tsx\n}\n```\n\n## 框架检测\n\nGitNexus 支持在语言解析过程中检测特定框架模式，并据此调整入口点权重：\n\n```typescript\ninterface AstFrameworkPatternConfig {\n framework: string; // 框架名称\n entryPointMultiplier: number; // 权重倍数\n reason: string; // 检测原因\n patterns: string[]; // 匹配模式列表\n}\n```\n\n当前支持的框架检测：\n\n| 框架 | 语言 | 权重倍数 | 检测模式 |\n|------|------|---------|---------|\n| Laravel | PHP | 3.0 | `Route::*`, `#[Route(` |\n| - | - | - | - |\n\n## 查询编译系统\n\n### PatternSpec 结构\n\ntree-sitter 查询通过 `tree-sitter-scanner.ts` 中的模式系统进行编译：\n\n```typescript\ninterface LanguagePatterns {\n name: string; // 人类可读的插件名称\n language: unknown; // tree-sitter 语法对象\n patterns: PatternSpec[];\n}\n\ninterface CompiledPatterns {\n name: string;\n language: unknown;\n patterns: CompiledPattern[];\n}\n\ninterface CompiledPattern {\n query: Parser.Query; // 预编译的查询\n meta: TMeta; // 插件特定的元数据\n}\n```\n\n### 编译时机\n\n查询在模块加载时**预编译**，以便在首次导入插件时检测语法不匹配问题：\n\n```typescript\nfunction compileBundle(language: unknown, name: string): NodeGrpcPatternBundle {\n const mk = (spec: PatternSpec>, suffix: string) =>\n compilePatterns({\n name: `${name}-${suffix}`,\n language,\n patterns: [spec]\n } satisfies LanguagePatterns>);\n \n return {\n grpcMethod: mk(GRPC_METHOD_SPEC, 'grpc-method'),\n grpcClient: mk(GRPC_CLIENT_SPEC, 'grpc-client'),\n // ...\n };\n}\n```\n\n资料来源：[grpc-patterns/node.ts:20-50]()\n\n## 缓存策略\n\n### AST 缓存\n\nGitNexus 使用内存缓存存储解析后的 AST：\n\n```typescript\nconst astCache = new Map();\n\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### 大文件处理\n\n对于超过 32KB 的文件，使用更大的缓冲区：\n\n```typescript\n// 使用 larger bufferSize for files > 32KB\nconst parseContent = provider.preprocessSource?.(file.content, file.path) ?? file.content;\ntree = parseSourceSafe(parser, parseContent, undefined, {\n bufferSize: getTreeSitterBufferSize(parseContent)\n});\n```\n\n资料来源：[heritage-processor.ts:30-50]()\n\n### 事件循环让步\n\n处理大量文件时，每 20 个文件让出一次事件循环，避免阻塞：\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\n## 依赖解析\n\n### 导入解析器\n\n每种语言的导入解析器负责将 import 语句转换为实际文件路径：\n\n| 语言 | 导入语法 | 解析策略 |\n|------|---------|---------|\n| JavaScript/TypeScript | `import`, `require()` | 基于 ES modules 和 CommonJS |\n| Python | `import`, `from ... import` | 基于 `__init__.py` 和 `__main__.py` |\n| Java | `import` | 基于包名和目录结构 |\n| PHP | `use`, `require`, `include` | 基于 Composer autoload |\n| C/C++ | `#include` | 基于系统路径和 include directories |\n\n### 导出检查器\n\n导出检查器验证符号是否被正确导出：\n\n```typescript\ninterface ExportChecker {\n check(node: SyntaxNode, ctx: ResolutionContext): ExportCheckResult;\n}\n```\n\n## 扩展多语言支持\n\n### 添加新语言步骤\n\n1. **安装 tree-sitter 语法包**：\n ```bash\n npm install tree-sitter-{language}\n ```\n\n2. **在 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\n3. **创建语言提供者文件**（如 `src/core/ingestion/languages/newlang.ts`）：\n ```typescript\n export const newLangProvider = defineLanguage({\n id: SupportedLanguages.NewLang,\n extensions: ['.nl', '.newlang'],\n entryPointPatterns: [/^main$/, /^init_/, /_handler$/],\n treeSitterQueries: NEWLANG_QUERIES,\n typeConfig: newLangConfig,\n exportChecker: newLangExportChecker,\n importResolver: createImportResolver(newLangImportConfig),\n // ... 其他提取器\n });\n ```\n\n4. **导出语言提供者**：\n ```typescript\n export { newLangProvider } from './newlang';\n ```\n\n### 定义 tree-sitter 查询\n\n查询使用 tree-sitter 查询语言编写：\n\n```tree-sitter-query\n;; 提取函数定义\n(function_declaration\n name: (identifier) @fn_name\n parameters: (parameter_list) @params) @function\n\n;; 提取类定义\n(class_declaration\n name: (identifier) @class_name\n superclass: (identifier) @superclass) @class\n\n;; 提取导入语句\n(import_statement\n module: (string) @module\n name: (identifier) @import_name) @import\n```\n\n## 配置选项\n\n### 语言可用性检查\n\n```typescript\n// 检查语言是否可用\nisLanguageAvailable(language: SupportedLanguages): boolean\n\n// 获取语言提供者\ngetProvider(language: SupportedLanguages): ReturnType\n\n// 加载语言\nloadLanguage(language: SupportedLanguages, filePath: string): Promise\n```\n\n### 跳过日志\n\n当语言不可用时，可以选择记录跳过统计：\n\n```typescript\nconst skippedByLang = logSkipped ? new Map() : null;\n\n// 记录跳过\nif (skippedByLang) {\n skippedByLang.set(language, (skippedByLang.get(language) ?? 0) + 1);\n}\n```\n\n## 性能优化\n\n### 并行处理\n\n文件处理采用顺序循环，每 20 个文件让出一次事件循环：\n\n```typescript\nfor (let i = 0; i < files.length; i++) {\n if (i % 20 === 0) await yieldToEventLoop();\n // 处理单个文件\n}\n```\n\n### 继承关系批量处理\n\n继承关系处理每 500 条记录报告一次进度：\n\n```typescript\nfor (let i = 0; i < extractedHeritage.length; i++) {\n if (i % 500 === 0) {\n onProgress?.(i, total);\n await yieldToEventLoop();\n }\n // 处理单条继承记录\n}\n```\n\n## 已知限制\n\n### C# ESM 加载问题\n\nC# 的 `tree-sitter-c-sharp` 包声明了 `type: \"module\"` 但没有 `exports` 字段，触发 Node 22 的 DEP0151 弃用警告。GitNexus 通过显式指定子路径绕过：\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\n资料来源：[parser-loader.ts:80-90]()\n\n### 必需依赖\n\n`tree-sitter-c` 是必需依赖，其原生绑定历史上存在 ABI 不兼容问题。某些语言（如 C++、Go、Rust）的基础功能依赖于它。\n\n## 总结\n\nGitNexus 的多语言支持系统通过以下核心设计实现了对多种编程语言的统一支持：\n\n1. **统一的 LanguageProvider 抽象**：所有语言共享相同的接口定义\n2. **tree-sitter 作为解析引擎**：提供高性能的 AST 构建能力\n3. **可配置的查询系统**：允许针对每种语言定制符号提取规则\n4. **插件化架构**：新增语言只需添加配置文件，无需修改核心代码\n5. **智能缓存和性能优化**：AST 缓存和事件循环让步确保大仓库处理能力\n\n通过这套系统，GitNexus 能够准确理解和分析跨多种编程语言的代码库结构，为代码图谱构建、依赖分析和影响追踪提供坚实基础。\n\n---\n\n\n\n## 数据存储\n\n### 相关页面\n\n相关主题：[知识图谱构建](#page-knowledge-graph), [MCP 架构与集成](#page-mcp-architecture)\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/storage/git.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/git.ts)\n- [gitnexus/src/storage/parse-cache.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/parse-cache.ts)\n- [gitnexus/src/storage/file-hash.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/storage/file-hash.ts)\n- [gitnexus/src/core/search/fts-schema.ts](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/search/fts-schema.ts)\n
\n\n# 数据存储\n\n## 概述\n\nGitNexus 的数据存储系统是一个多层次的架构，负责管理代码仓库的本地索引、解析结果缓存、文件哈希计算以及全文搜索索引。该系统设计为本地优先，所有数据默认存储在用户本地文件系统，不依赖云端服务。\n\n存储系统的核心职责包括：\n\n- **仓库生命周期管理**：克隆、更新、删除代码仓库\n- **解析结果持久化**：缓存 AST 解析结果以支持增量更新\n- **文件指纹追踪**：通过哈希值检测文件变更\n- **全文搜索索引**：构建和维护代码的可搜索索引\n\n## 存储架构\n\n```\ngraph TD\n subgraph 用户层\n CLI[CLI 命令]\n WebUI[Web 前端]\n end\n \n subgraph 存储服务层\n RM[仓库管理器]\n GC[Git 控制器]\n PC[解析缓存]\n FH[文件哈希]\n FTS[全文搜索]\n end\n \n subgraph 持久化层\n FS[文件系统]\n IDX[SQLite 索引]\n end\n \n CLI --> RM\n WebUI --> RM\n RM --> GC\n RM --> PC\n PC --> FH\n FH --> FS\n RM --> FTS\n FTS --> IDX\n```\n\n## 仓库管理器\n\n仓库管理器（`repo-manager.ts`）是存储系统的核心组件，负责协调所有仓库相关的操作。\n\n### 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 仓库注册 | 将本地仓库路径注册到索引系统 |\n| 增量更新 | 仅重新解析变更文件 |\n| 健康检查 | 验证仓库引用完整性 |\n| 别名管理 | 支持为仓库指定友好名称 |\n\n### 仓库注册流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant RM as 仓库管理器\n participant FS as 文件系统\n participant Git as Git 控制器\n participant Index as 索引数据库\n \n User->>RM: 注册仓库路径\n RM->>Git: 验证 .git 目录\n Git-->>RM: 验证结果\n RM->>FS: 检查路径可访问性\n RM->>Git: 获取远程 origin URL\n RM->>Index: 创建仓库记录\n RM-->>User: 注册成功\n```\n\n### 别名机制\n\n仓库管理器支持通过 `--name` 参数为仓库指定自定义别名，这对于具有相同目录名的仓库（如 monorepo 中的多个 `app` 文件夹）尤为重要。\n\n```bash\ngitnexus ingest /path/to/repo --name my-project-alias\n```\n\n别名信息存储在 `~/.gitnexus/registry.json` 中，支持以下配置：\n\n| 配置项 | 说明 |\n|--------|------|\n| `--name ` | 注册仓库的自定义名称 |\n| `--allow-duplicate-name` | 允许重名（需使用路径区分） |\n\n资料来源：[gitnexus/src/cli/index.ts:1-50]()\n\n## Git 集成\n\nGit 控制器（`git.ts`）提供了与 Git 仓库交互的基础工具函数。\n\n### 核心 API\n\n#### `hasGitDir()`\n\n检测指定目录是否为 Git 仓库：\n\n```typescript\nexport const hasGitDir = (dirPath: string): boolean => {\n try {\n statSync(path.join(dirPath, '.git'));\n return true;\n } catch {\n return false;\n }\n};\n```\n\n此函数用于在执行 Git 操作前进行快速验证。资料来源：[gitnexus/src/storage/git.ts:1-20]()\n\n#### `getRemoteOriginUrl()`\n\n从 Git 仓库读取 `remote.origin.url`：\n\n```typescript\nexport const getRemoteOriginUrl = (repoPath: string): string | null => {\n try {\n const url = execSync('git config --get remote.origin.url', {\n cwd: repoPath,\n stdio: ['ignore', 'pipe', 'ignore'],\n })\n .toString()\n .trim();\n return url || null;\n } catch {\n return null;\n }\n};\n```\n\n此函数用于从远程 URL 推断仓库名称，支持 monorepo 和 git worktree 等复杂场景。资料来源：[gitnexus/src/storage/git.ts:30-50]()\n\n#### `sanitizeRepoName()`\n\n仓库名称清理函数，用于：\n\n1. 移除前导破折号，防止命令行注入（如 `--upload-pack=evil`）\n2. 替换跨平台不安全的文件系统字符\n\n```mermaid\ngraph LR\n A[原始名称] --> B{以 - 开头?}\n B -->|是| C[移除前导 -]\n B -->|否| D[继续处理]\n C --> D\n D --> E[替换非法字符]\n E --> F[安全名称]\n```\n\n## 解析缓存\n\n解析缓存（`parse-cache.ts`）是增量解析的核心，通过缓存 AST 解析结果避免重复解析未变更的文件。\n\n### 缓存策略\n\n| 策略 | 描述 |\n|------|------|\n| 文件哈希比对 | 使用文件内容哈希判断是否需要重新解析 |\n| 工作线程支持 | 解析任务分发到 Worker 线程池 |\n| 子批次处理 | 大文件自动拆分处理 |\n\n### 增量更新机制\n\n```mermaid\ngraph TD\n A[文件变更检测] --> B{文件内容哈希变化?}\n B -->|否| C[跳过解析]\n B -->|是| D[加载/解析 AST]\n D --> E[提取代码结构]\n E --> F[更新缓存]\n F --> G[更新知识图谱]\n```\n\n解析缓存与知识图谱更新紧密集成，支持以下场景：\n\n- **完整重新解析**：首次导入仓库时\n- **增量更新**：仅解析变更文件\n- **跨语言一致性**：不同语言使用统一缓存接口\n\n资料来源：[gitnexus/src/core/ingestion/parsing-processor.ts:1-50]()\n\n## 文件哈希\n\n文件哈希模块（`file-hash.ts`）负责计算文件内容的指纹，用于变更检测和缓存管理。\n\n### 哈希算法\n\n采用 SHA-256 或平台优化的等价算法，确保：\n\n- 确定性：相同内容产生相同哈希\n- 雪崩效应：微小变更产生截然不同的哈希\n\n### 用途\n\n| 场景 | 说明 |\n|------|------|\n| 增量解析 | 对比文件哈希判断是否需要重新解析 |\n| 缓存验证 | 确保缓存数据与源文件一致 |\n| 去重 | 识别内容相同的重复文件 |\n\n## 全文搜索架构\n\n全文搜索系统（`fts-schema.ts`）基于 SQLite 的 FTS5 扩展构建，提供代码语义级别的搜索能力。\n\n### 索引结构\n\n```mermaid\nerDiagram\n FTS_INDEX {\n int rowid PK\n text content\n text token\n }\n \n CODE_NODES {\n int id PK\n string uid\n string label\n string file_path\n }\n \n FTS_INDEX ||--o| CODE_NODES : references\n```\n\n### 搜索能力\n\n| 搜索类型 | 示例 |\n|----------|------|\n| 符号搜索 | 搜索函数、类、接口定义 |\n| 依赖搜索 | 查找符号的调用方和被调用方 |\n| 路径搜索 | 基于文件路径的模糊匹配 |\n| 语义搜索 | 理解代码上下文的智能搜索 |\n\n### 配置选项\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| 搜索模式 | 标准 | 支持精确和模糊匹配 |\n| 排序规则 | 相关度 | 基于命中次数和位置 |\n| 上下文行数 | 2 | 结果周围的代码行数 |\n\n资料来源：[gitnexus/src/core/search/fts-schema.ts:1-30]()\n\n## 数据流\n\n### 完整导入流程\n\n```mermaid\nflowchart TD\n A[gitnexus ingest] --> B[仓库验证]\n B --> C{已注册?}\n C -->|否| D[克隆仓库]\n C -->|是| E[读取缓存]\n D --> F[文件枚举]\n E --> F\n F --> G[计算文件哈希]\n G --> H{文件变更?}\n H -->|否| I[使用缓存结果]\n H -->|是| J[解析 AST]\n J --> K[提取结构信息]\n K --> L[更新知识图谱]\n L --> M[更新全文索引]\n M --> N[保存缓存]\n I --> N\n N --> O[完成]\n```\n\n### 增量更新流程\n\n```mermaid\nflowchart TD\n A[gitnexus sync] --> B[扫描文件变更]\n B --> C{有变更?}\n C -->|否| D[退出]\n C -->|是| E[重新解析变更文件]\n E --> F[更新图谱节点]\n F --> G[重建受影响索引]\n G --> H[保存状态]\n```\n\n## 存储位置\n\n| 数据类型 | 默认位置 |\n|----------|----------|\n| 索引数据 | `~/.gitnexus/` |\n| 仓库缓存 | `~/.gitnexus/cache/` |\n| 解析缓存 | `~/.gitnexus/parse-cache/` |\n| 注册表 | `~/.gitnexus/registry.json` |\n\n## 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `GITNEXUS_NO_GITIGNORE` | 跳过 .gitignore 解析 |\n| `GITNEXUS_MAX_FILE_SIZE` | 最大处理文件大小（KB） |\n\n## 相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `gitnexus ingest` | 导入并索引仓库 |\n| `gitnexus sync` | 增量同步仓库变更 |\n| `gitnexus query` | 搜索知识图谱 |\n| `gitnexus serve` | 启动本地服务 |\n\n---\n\n*本页面最后更新于知识图谱索引生成流程分析。*\n\n---\n\n\n\n## Web UI 组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\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/OnboardingGuide.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/OnboardingGuide.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/StatusBar.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/StatusBar.tsx)\n- [gitnexus-web/src/components/Header.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/Header.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/WebGPUFallbackDialog.tsx](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/WebGPUFallbackDialog.tsx)\n
\n\n# Web UI 组件\n\nGitNexus Web UI 是整个应用的前端界面层，负责用户交互、仓库可视化、图谱探索以及自然语言查询功能。该层采用 React + TypeScript 构建，通过后端 API 与知识图谱引擎进行通信。\n\n## 组件架构概览\n\nWeb UI 采用模块化组件设计，核心组件位于 `gitnexus-web/src/components/` 目录。整体架构遵循状态驱动的 UI 模式，通过自定义 Hooks 管理与后端的连接状态。\n\n```mermaid\ngraph TD\n A[App.tsx] --> B[Header 组件]\n A --> C[DropZone 连接状态管理]\n A --> D[GraphCanvas 图谱画布]\n A --> E[StatusBar 状态栏]\n \n C --> F[OnboardingGuide 入门引导]\n C --> G[AnalyzeOnboarding 仓库分析]\n C --> H[RepoAnalyzer 仓库分析器]\n \n D --> I[HelpPanel 帮助面板]\n D --> J[WebGPUFallbackDialog GPU回退]\n \n K[useBackend Hook] <--> L[后端 API]\n```\n\n## 核心组件详解\n\n### HelpPanel 帮助面板\n\n帮助面板组件提供上下文相关的使用说明，根据当前活跃状态 (`active`) 动态渲染不同的帮助内容。该组件支持三种模式：图例说明、搜索过滤和入门指南。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `active` | `'legend'` \\| `'search'` \\| `'getting-started'` | 当前面板模式 |\n| `nodeCount` | `number` | 图谱节点数量 |\n| `edgeCount` | `number` | 图谱边数量 |\n\n**图例模式 (legend)** 解释节点大小与连接数的关系，节点越大表示被依赖次数越多，边的方向从导入方指向被导入方。资料来源：[HelpPanel.tsx:12-15]()\n\n**搜索模式 (search)** 提供搜索和过滤功能的使用说明，采用大写字母的标签样式增强可读性。资料来源：[HelpPanel.tsx:45-55]()\n\n**入门模式 (getting-started)** 包含四个信息区块：GitNexus 功能介绍、当前仓库状态、三种探索方式、Nexus AI 语义查询就绪状态。资料来源：[HelpPanel.tsx:65-120]()\n\n```typescript\nif (active === 'legend')\n return (\n
\n

\n 图例\n

\n

\n Node size reflects connection count...\n

\n
\n );\n```\n\n### OnboardingGuide 入门引导\n\n入门引导组件采用步骤式设计，引导用户完成 GitNexus 的安装和启动流程。整个流程分为三个步骤，采用状态指示器显示当前进度。\n\n| 步骤 | 状态 | 标题 | 说明 |\n|------|------|------|------|\n| 1 | pending/active/complete | 安装 GitNexus | 全局安装命令 |\n| 2 | pending/active/complete | 运行并等待 | 启动本地服务器 |\n| 3 | pending/active/complete | 自动连接 | 检测服务器并打开图谱 |\n\n资料来源：[OnboardingGuide.tsx:1-50]()\n\n```typescript\n\n {isPolling && }\n\n```\n\n组件底部包含前置条件提示，要求 Node.js 版本不低于 `REQUIRED_NODE_VERSION`，并提供官方文档链接。资料来源：[OnboardingGuide.tsx:75-85]()\n\n### DropZone 连接状态管理\n\nDropZone 是应用的核心状态管理器，负责检测后端服务器连接、处理仓库加载状态、协调不同阶段 UI 的切换。该组件维护一个复杂的状态机，追踪连接过程中的各个阶段。\n\n| 状态 (phase) | 场景 | UI 显示 |\n|--------------|------|---------|\n| `onboarding` | 服务器未启动 | 入门引导 |\n| `analyze` | 服务器启动，无仓库 | URL 输入分析器 |\n| `landing` | 服务器启动，有仓库 | 仓库选择器 |\n| `success` | 仓库加载完成 | 图谱视图 |\n| `loading` | 正在加载 | 加载动画 |\n\n资料来源：[DropZone.tsx:25-35]()\n\n```typescript\nconst {\n isConnected,\n isProbing,\n startPolling,\n stopPolling,\n isPolling,\n backendUrl: detectedBackendUrl,\n} = useBackend();\n```\n\n组件使用 `useBackend` Hook 进行后端探测，通过轮询机制自动发现本地服务器，探测完成后触发 `onServerConnect` 回调。资料来源：[DropZone.tsx:10-20]()\n\n### StatusBar 状态栏\n\n状态栏组件位于界面底部左侧，用于显示当前操作进度或就绪状态。当有进度信息时显示进度条动画，完成后切换为就绪指示器。\n\n| 元素 | 样式 | 说明 |\n|------|------|------|\n| 进度条 | 渐变填充 | 实时进度百分比 |\n| 就绪指示器 | 绿色圆点 | 表示系统就绪 |\n\n资料来源：[StatusBar.tsx:1-20]()\n\n```typescript\n\n```\n\n右侧包含 GitHub 赞助入口，采用粉色调设计，悬停时触发动画效果。资料来源：[StatusBar.tsx:20-35]()\n\n### Header 头部组件\n\n头部组件提供仓库切换下拉菜单，允许用户在多个已索引的仓库之间快速切换。选中的仓库以紫色边框高亮显示，左侧显示当前仓库标签。\n\n| UI 元素 | 样式类 | 交互行为 |\n|---------|--------|----------|\n| 仓库列表项 | `hover:bg-hover` | 点击切换仓库 |\n| 活动指示器 | `border-l-2 border-accent` | 标识当前仓库 |\n| 文件夹图标 | `text-node-folder` | 类型标识 |\n\n资料来源：[Header.tsx:15-40]()\n\n当前仓库名称以等宽字体显示，右侧显示 \"active\" 标签，每个仓库项支持重新分析操作。资料来源：[Header.tsx:40-60]()\n\n### AnalyzeOnboarding 仓库分析器\n\n分析器组件提供 GitHub 仓库 URL 输入功能，用户粘贴仓库地址后，系统自动克隆代码、解析结构并构建知识图谱。\n\n```typescript\n\n```\n\n组件底部显示使用限制提示：仅支持公开仓库、数据本地处理、不会泄露用户数据。资料来源：[AnalyzeOnboarding.tsx:15-20]()\n\n### WebGPUFallbackDialog GPU回退对话框\n\n当浏览器不支持 WebGPU 时，显示此对话框说明语义搜索功能受限，并提供降级方案选择。\n\n| 方案 | 性能 | 体验 |\n|------|------|------|\n| CPU 模式 | 较慢 | 可用但性能下降 |\n| WebGPU | 快速 | 完整的语义搜索能力 |\n\n资料来源：[WebGPUFallbackDialog.tsx:1-25]()\n\n```typescript\n

\n Couldn't create embeddings with WebGPU, so semantic search (Graph RAG) won't be as smart.\n

\n```\n\n对话框显示预估处理时间，帮助用户了解 CPU 模式下的等待时长。资料来源：[WebGPUFallbackDialog.tsx:25-35]()\n\n## 状态管理架构\n\nWeb UI 采用 React Hooks 进行状态管理，核心状态由 `useBackend` Hook 集中控制。\n\n```mermaid\ngraph LR\n A[useBackend] --> B[isConnected]\n A --> C[isProbing]\n A --> D[isPolling]\n A --> E[backendUrl]\n \n B --> F[状态切换]\n D --> G[轮询检测]\n E --> H[后端地址]\n```\n\n### 状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Onboarding: 首次访问\n Onboarding --> Analyze: 服务器就绪\n Analyze --> Landing: 有索引仓库\n Landing --> Success: 选择仓库\n Success --> Landing: 切换仓库\n Onboarding --> Success: 快速路径\n Analyze --> Success: 直接分析\n```\n\n## 样式系统\n\n组件采用内联样式与 Tailwind CSS 混合模式，关键样式常量包括：\n\n| 类别 | 颜色值 | 用途 |\n|------|--------|------|\n| 背景 | `rgba(255,255,255,0.04)` | 卡片背景 |\n| 边框 | `rgba(255,255,255,0.08)` | 分隔线 |\n| 强调色 | `#a78bfa` | 主交互色 |\n| 成功色 | `#34d399` | 就绪状态 |\n| 信息色 | `#60a5fa` | 提示信息 |\n| 文字主色 | `#e2e2e8` | 标题文字 |\n| 文字次色 | `#9ca3af` | 说明文字 |\n| 文字弱色 | `#6b7280` | 标签文字 |\n\n资料来源：[HelpPanel.tsx:5-10]()\n\n## 组件通信模式\n\n父组件通过 Props 向下传递数据和回调，子组件通过事件触发父组件状态更新。\n\n```mermaid\ngraph TD\n A[App] -->|onServerConnect| B[DropZone]\n A -->|onAnalyzeComplete| C[Header]\n B -->|onComplete| A\n C -->|onSwitchRepo| A\n \n D[OnboardingGuide] -->|isPolling| B\n E[RepoAnalyzer] -->|onComplete| B\n```\n\n## 与后端的交互\n\nWeb UI 通过 REST API 与 `LocalBackend` 通信，主要交互包括：\n\n| 操作 | API 端点 | 用途 |\n|------|----------|------|\n| 探测服务器 | `GET /api/health` | 连接状态检测 |\n| 获取仓库列表 | `GET /api/repos` | 仓库选择器 |\n| 触发分析 | `POST /api/analyze` | 仓库克隆解析 |\n| 获取图谱数据 | `GET /api/graph` | 图谱可视化 |\n\n## 扩展开发指南\n\n新增 UI 组件的推荐步骤：\n\n1. 在 `gitnexus-web/src/components/` 目录创建组件文件\n2. 使用 TypeScript 定义 Props 接口\n3. 遵循内联样式模式保持视觉一致性\n4. 通过 `useBackend` Hook 访问后端状态\n5. 在 `App.tsx` 中注册新组件\n\n组件应保持单一职责，通过 Props 接收数据和回调，避免直接访问全局状态。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：abhigyanpatwari/GitNexus\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 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. 安装坑 · 来源证据：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## 3. 配置坑 · 来源证据：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## 4. 安装坑 · 来源证据：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## 5. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.12\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ab63b9f59a54481abd184c162662990 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.12 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.13\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7923c9bda9874ce9870d5c684c3087ff | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.14\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba78a9abede8434fa010e8bee0ad539d | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.15\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe507017f17c4775b3d5a4e73b724a3a | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.16\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f1c7b44ec854520814354c46f0d1889 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.17\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06c1411b76fb4e07998249f900e31b02 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.18\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39945335ad1940e888d89a6cf3971331 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.19\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d3a217ad4944b9a8b541abf5b857840 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 13. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92b8f92f6417448abe698e2d08bba803 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.8 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.9\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.9\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a29c0c1477a8488d8f31bc15d51d1df9 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 配置坑 · 来源证据：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44741975e7b44839afb3b3379760d58f | https://github.com/abhigyanpatwari/GitNexus/issues/1541 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\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## 17. 维护坑 · 维护活跃度未知\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## 18. 安全/权限坑 · 下游验证发现风险项\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## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\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## 21. 维护坑 · 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## 22. 维护坑 · 发布节奏不明确\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摘要：发现 22 个潜在踩坑项，其中 3 个为 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. 安装坑 · 来源证据：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## 3. 配置坑 · 来源证据：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## 4. 安装坑 · 来源证据：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## 5. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.12\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3ab63b9f59a54481abd184c162662990 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.12 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.13\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.13\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7923c9bda9874ce9870d5c684c3087ff | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.13 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.14\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba78a9abede8434fa010e8bee0ad539d | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.14 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.15\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.15\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fe507017f17c4775b3d5a4e73b724a3a | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.15 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.16\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.16\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9f1c7b44ec854520814354c46f0d1889 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.16 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 10. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.17\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.17\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_06c1411b76fb4e07998249f900e31b02 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 11. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.18\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.18\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_39945335ad1940e888d89a6cf3971331 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.18 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 12. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.19\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.19\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5d3a217ad4944b9a8b541abf5b857840 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.19 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 13. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.8\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.8\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_92b8f92f6417448abe698e2d08bba803 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.8 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 14. 安装坑 · 来源证据：Release Candidate v1.6.5-rc.9\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Release Candidate v1.6.5-rc.9\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a29c0c1477a8488d8f31bc15d51d1df9 | https://github.com/abhigyanpatwari/GitNexus/releases/tag/v1.6.5-rc.9 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 15. 配置坑 · 来源证据：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：分析完成之后，会出现agent在使用gitnexus，提示落后commit版本\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_44741975e7b44839afb3b3379760d58f | https://github.com/abhigyanpatwari/GitNexus/issues/1541 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 16. 能力坑 · 能力判断依赖假设\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## 17. 维护坑 · 维护活跃度未知\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## 18. 安全/权限坑 · 下游验证发现风险项\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## 19. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1031059905 | https://github.com/abhigyanpatwari/GitNexus | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 20. 安全/权限坑 · 存在评分风险\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## 21. 维护坑 · 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## 22. 维护坑 · 发布节奏不明确\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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 GitNexus 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-mcp-architecture：MCP 架构与集成。围绕“MCP 架构与集成”模拟一次用户任务，不展示安装或运行结果。\n5. page-knowledge-graph：知识图谱构建。围绕“知识图谱构建”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-mcp-architecture\n输入：用户提供的“MCP 架构与集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-knowledge-graph\n输入：用户提供的“知识图谱构建”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-mcp-architecture：Step 4 必须围绕“MCP 架构与集成”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-knowledge-graph：Step 5 必须围绕“知识图谱构建”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\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- gitnexus-cursor-integration/skills/gitnexus-exploring/SKILL.md\n- gitnexus-cursor-integration/skills/gitnexus-impact-analysis/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 GitNexus 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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" }