# Pitfall Log / 踩坑日志 项目：CodeGraphContext/CodeGraphContext 摘要：发现 34 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Improve Readme Formatting and Structure。 ## 1. 安装坑 · 来源证据：Improve Readme Formatting and Structure - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Improve Readme Formatting and Structure - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1030 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving… - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1331 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable expo… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible withou… - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1333 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 4. 配置坑 · 来源证据：Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1322 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 5. 运行坑 · 来源证据：[Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1328 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 运行坑 · 来源证据：[Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1308 | 来源类型 github_issue 暴露的待验证使用条件。 ## 7. 安全/权限坑 · 来源证据：AI: Implement Prompt Text Truncation Safety - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AI: Implement Prompt Text Truncation Safety - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1102 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 8. 安全/权限坑 · 来源证据：Fix invalid gradient usage in graph node stylin - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Fix invalid gradient usage in graph node stylin - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1306 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 9. 安全/权限坑 · 来源证据：feat/chore: Add automated validation for database credentials in the MCP setup wizard - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat/chore: Add automated validation for database credentials in the MCP setup wizard - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1059 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 安全/权限坑 · 来源证据：feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, pro… - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Pyth… - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1332 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 安装坑 · 失败模式：installation: Improve Readme Formatting and Structure - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Improve Readme Formatting and Structure - 对用户的影响：Developers may fail before the first successful local run: Improve Readme Formatting and Structure - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1030 | Improve Readme Formatting and Structure ## 12. 安装坑 · 失败模式：installation: Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-pars... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - 对用户的影响：Developers may fail before the first successful local run: Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1334 | Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution ## 13. 安装坑 · 失败模式：installation: VSCode-Extension-v0.1.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: VSCode-Extension-v0.1.0 - 对用户的影响：Upgrade or migration may change expected behavior: VSCode-Extension-v0.1.0 - 证据：failure_mode_cluster:github_release | https://github.com/CodeGraphContext/CodeGraphContext/releases/tag/v0.1.0-alpha | VSCode-Extension-v0.1.0 ## 14. 安装坑 · 失败模式：installation: bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails o... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving users unaware whic... - 对用户的影响：Developers may fail before the first successful local run: bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving users unaware whic... - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1331 | bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving users unaware whic... ## 15. 安装坑 · 来源证据：Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - 对用户的影响：可能阻塞安装或首次运行。 - 证据：community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1334 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 16. 配置坑 · 失败模式：configuration: AI: Implement Prompt Text Truncation Safety - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: AI: Implement Prompt Text Truncation Safety - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: AI: Implement Prompt Text Truncation Safety - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1102 | AI: Implement Prompt Text Truncation Safety ## 17. 配置坑 · 失败模式：configuration: Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP mis... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1322 | Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass ## 18. 配置坑 · 失败模式：configuration: Fix invalid gradient usage in graph node stylin - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Fix invalid gradient usage in graph node stylin - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Fix invalid gradient usage in graph node stylin - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1306 | Fix invalid gradient usage in graph node stylin ## 19. 配置坑 · 失败模式：configuration: feat/chore: Add automated validation for database credentials in the MCP setup wizard - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: feat/chore: Add automated validation for database credentials in the MCP setup wizard - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat/chore: Add automated validation for database credentials in the MCP setup wizard - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1059 | feat/chore: Add automated validation for database credentials in the MCP setup wizard ## 20. 配置坑 · 失败模式：configuration: feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unrefer... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods,... - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods,... - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1332 | feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods,... ## 21. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/CodeGraphContext/CodeGraphContext | README/documentation is current enough for a first validation pass. ## 22. 运行坑 · 运行可能依赖外部服务 - 严重度：medium - 证据强度：source_linked - 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。 - 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。 - 证据：packet_text.keyword_scan | https://github.com/CodeGraphContext/CodeGraphContext | matched external service / cloud / webhook / database keyword ## 23. 维护坑 · 失败模式：migration: Extension: Clean Event Listeners on Panel Disposal - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: Extension: Clean Event Listeners on Panel Disposal - 对用户的影响：Developers may hit a documented source-backed failure mode: Extension: Clean Event Listeners on Panel Disposal - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1117 | Extension: Clean Event Listeners on Panel Disposal ## 24. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/CodeGraphContext/CodeGraphContext | no_demo; severity=medium ## 26. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/CodeGraphContext/CodeGraphContext | no_demo; severity=medium ## 27. 能力坑 · 失败模式：capability: [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all pla... - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1308 | [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms ## 28. 能力坑 · 失败模式：capability: chore(a11y): Form field elements missing "id" or "name" attributes on landing page - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: chore(a11y): Form field elements missing "id" or "name" attributes on landing page - 对用户的影响：Developers may hit a documented source-backed failure mode: chore(a11y): Form field elements missing "id" or "name" attributes on landing page - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1305 | chore(a11y): Form field elements missing "id" or "name" attributes on landing page ## 29. 能力坑 · 失败模式：conceptual: [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1328 | [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs ## 30. 能力坑 · 失败模式：conceptual: feat: `codegraphcontext analyze complexity` threshold flag has no documented output format an... - 严重度：low - 证据强度：source_linked - 发现：Developers should check this conceptual risk before relying on the project: feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output - 对用户的影响：Developers may hit a documented source-backed failure mode: feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1333 | feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output ## 31. 运行坑 · 失败模式：performance: feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks - 对用户的影响：Developers may hit a documented source-backed failure mode: feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks - 证据：failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1339 | feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks ## 32. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext | issue_or_pr_quality=unknown ## 33. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext | release_recency=unknown ## 34. 维护坑 · 失败模式：maintenance: v0.0.11-alpha - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v0.0.11-alpha - 对用户的影响：Upgrade or migration may change expected behavior: v0.0.11-alpha - 证据：failure_mode_cluster:github_release | https://github.com/CodeGraphContext/CodeGraphContext/releases/tag/v0.0.11-alpha | v0.0.11-alpha