Msg from codex

[793383996]

结论
按你贴的清单和 README.zh-CN 逐项实测，这 29 个工具里：

• 16 个当前可正常用
• 5 个可用但有限制或结果质量有瑕疵
• 8 个当前不可用

图本身已经可用，数据库在 graph.db，Wiki 也已生成到 wiki。源码文件没有被我改动；git status 仍只看到你原本就有的未跟踪文件 .code-review-graphignore。

逐项结果 1/3

工具	状态	实测结果
build_or_update_graph_tool	受限	MCP 调用持续在 120s 超时；但 CLI code-review-graph build/update 正常，说明底层功能在，MCP 包装层不稳定。
get_minimal_context_tool	失败	多次调用都在 120s 超时。
list_graph_stats_tool	正常	返回稳定；当前图为 91 files / 1248 nodes / 6519 edges。
get_docs_section_tool	失败	usage、commands、review-delta 都返回 not_found，但错误里又说这些 section 可用，明显异常。
query_graph_tool	受限	file_summary、callers_of、callees_of、tests_for、imports_of、importers_of、inheritors_of 都能跑；但 minimal 模式下 imports_of/importers_of 结果对象是空的，standard 才正常。短名称也可能歧义，常要传 qualified_name。
traverse_graph_tool	正常	BFS 遍历 createLegacyCommandRegistry 正常，返回了节点、深度、截断标记和下一步建议。
semantic_search_nodes_tool	受限	可用，但当前是无嵌入的 hybrid/关键字式搜索，结果质量受限。
find_large_functions_tool	正常	正常找出大函数，如 toStr 730 行、f_init 575 行。
embed_graph_tool	失败	明确报错：sentence-transformers not installed。这是环境缺依赖，不是仓库内容问题。

逐项结果 2/3

工具	状态	实测结果
get_impact_radius_tool	正常	对 app-services.ts 返回 high 风险，37 个直接变更节点，462 个影响节点，68 个文件受影响。注意 changed_files 必须传数组。
get_review_context_tool	正常	对同一文件返回 high 风险、68 个受影响文件、34 个测试缺口。changed_files 也必须传数组。
detect_changes_tool	受限	MCP 调用超时；CLI code-review-graph detect-changes --brief 正常。
get_affected_flows_tool	正常	对 app-services.ts 返回 14 条受影响执行流。changed_files 必须传数组。
list_flows_tool	正常	正常返回关键执行流，前几项包括 scheduleRecalculate、flushRecalculate、bootstrapDsqApp。
get_flow_tool	正常	bootstrapDsqApp 详情可正常展开，返回 50 个节点、5 层深度。
list_communities_tool	正常	正常，当前识别到 9 个社区。
get_community_tool	正常	services-settings 详情正常，返回 98 个节点、0.303 cohesion。
get_architecture_overview_tool	正常	正常，返回 9 个社区、114 条跨社区边、2 条高耦合警告。
get_hub_nodes_tool	失败	传 repo_root 报 'str' object has no attribute 'resolve'；不传则报 'NoneType' object has no attribute 'resolve'。
get_bridge_nodes_tool	失败	同上。
get_knowledge_gaps_tool	失败	同上。
get_surprising_connections_tool	失败	同上。
get_suggested_questions_tool	失败	同上。

逐项结果 3/3

工具	状态	实测结果
refactor_tool	受限	rename 预览正常，dead_code 可跑，suggest 也能跑；但建议质量偏噪，出现把 bootstrapDsqApp 这类实际执行流入口判成“unused”的情况。
apply_refactor_tool	正常	用 dry_run 验证成功，正确给出 i18n.ts 和 bootstrap.ts 的 rename diff，未落盘。
generate_wiki_tool	正常	成功生成 10 个 Wiki 页面。
get_wiki_page_tool	正常	成功读取 services-settings 页面内容。
list_repos_tool	正常	初始为空；注册后能正确列出当前仓库。
cross_repo_search_tool	正常	在我把当前仓库注册为 DSQ 后可正常搜索，createDsqServices 搜到了跨仓库结果。

补充
这次测试里我额外做了两件“环境级”操作：

• 生成了图和 Wiki 工件，位置分别在 graph.db 和 wiki。
• 为了验证 cross_repo_search_tool，我把当前仓库注册成了 DSQ。这不会改源码，但会改 code-review-graph 的本地仓库注册表。

如果你要，我下一步可以直接帮你做两件事里的任意一件：

1. 输出一份“可直接发 issue 的问题清单”，按工具分组列出复现步骤和错误信息。
2. 把当前仓库从多仓库注册表里注销，恢复到测试前状态。

Code Review Graph 异常 MCP 调用链系统排查与修复计划

摘要

【严厉质控结论】不合格。当前异常不是单点故障，而是“运行包与源码漂移 + 打包资源缺失 + 首跳上下文算法不一致 + 缺少真实 MCP 集成回归”叠加导致的系统性问题。修复目标不是只让单个工具“能跑”，而是保证源码、安装包、MCP 传输层、首跳决策和发布链路一致，最终恢复 README 承诺的“低 Token、稳定、可重复”的工作流。

已验证问题

• get_hub_nodes_tool、get_bridge_nodes_tool、get_knowledge_gaps_tool、get_surprising_connections_tool、get_suggested_questions_tool：
  表现：MCP 调用时报 'str' object has no attribute 'resolve'。
  复现：在非源码目录下直接调用已安装包或通过 FastMCP Client 调用这 5 个工具即可复现。
  根因：运行中的 site-packages 版 tools/analysis_tools.py 仍执行 _validate_repo_root(repo_root)，而 _validate_repo_root() 期待 Path，实际传入 str。
  影响：所有高层架构分析工具在正常 MCP 场景下硬失败，AI 无法完成结构诊断和问题提问链路。

• get_docs_section_tool：
  表现：调用 usage、commands 等 section 返回 not_found，但错误里又列出这些 section 名称。
  复现：在非源码目录下调用已安装包的 get_docs_section('usage') 可稳定复现。
  根因：wheel 未包含 docs/LLM-OPTIMIZED-REFERENCE.md；同时当前源码的 main.py 中 get_docs_section_tool 未走 _resolve_repo_root()，serve --repo 对它不生效。
  影响：README 所依赖的“按 section 精准取文档、避免整篇加载”的 token 优化链路在正常安装场景下失效。

• get_minimal_context_tool：
  表现：同一仓库下它给出 Risk: low (0.00)，而 detect_changes_tool(detail_level='minimal') 对同一仓库给出 risk_score=0.8、157 changed function/class、132 test gaps。
  复现：对 D:\Android\Project\DSQ 直接调用两者即可复现不一致。
  根因：get_minimal_context() 直接调用 analyze_changes()，但没有像 detect_changes_func() 那样把 diff ranges 规范化为绝对路径；analyze_changes() 内部拿到的是相对 diff path，映射不到图中的绝对文件路径，导致 changed nodes 近似为 0。
  影响：AI 首跳风险评估失真，会错误选择后续工具，既损害 token 效率，也损害审查正确性。

• build_or_update_graph_tool、detect_changes_tool 的“120s 超时”：
  表现：在你之前的外部 MCP 宿主中发生超时；但本地直接函数调用和本地 FastMCP Client 调用均可快速返回。
  复现：当前源码仓库内未能稳定复现相同超时。
  根因判断：优先归类为运行时集成风险，不是当前核心算法的确定性逻辑错误。已知风险点包括：运行包与源码不一致、旧版 main.py 未关闭 stdio banner、缺少真实 MCP 端到端回归、长任务仅做了 to_thread，没有面向宿主超时策略的任务化/进度化保障。
  影响：在部分宿主中会表现为随机超时、握手污染或长任务失败，导致用户误判为算法故障。

• 版本与初始化信息漂移：
  表现：源码目录与 site-packages 目录均标记为 2.3.2，但实现不同；同时 code_review_graph/__init__.py 仍是 2.1.0。
  复现：从源码目录和非源码目录分别导入同名模块可观察到不同实现；直接读取 __init__.py 可见版本不一致。
  根因：发布/安装流程缺少“源码、wheel、已安装包”一致性校验。
  影响：问题定位、用户反馈、回归验证和发布判断都会失真。

实施变更

• 统一运行时与发布物
  将当前源码作为唯一真源，修正 code_review_graph/__init__.py 版本号与 pyproject.toml 一致，并发布新补丁版本，不允许继续以相同版本号承载不同实现。
  在发布流程中新增“从非源码目录导入并验证关键工具”的安装后校验，杜绝源码好、安装包坏的情况。

• 修复 docs 工具链
  将 LLM-OPTIMIZED-REFERENCE.md 从仓库外部相对路径依赖改为包内资源，优先使用 importlib.resources 读取，避免依赖当前工作目录或源码树。
  在 main.py 中让 get_docs_section_tool 与其它工具一样统一走 _resolve_repo_root(repo_root)。
  在打包配置中明确把该文档资源打进 wheel，而不是只放进 sdist。

• 收敛变更分析算法
  抽取一个共享的“changed files + diff ranges 规范化”辅助函数，作为 get_minimal_context() 与 detect_changes_func() 的唯一事实来源。
  get_minimal_context() 保留紧凑输出，但必须复用 detect_changes_func() 同级别的路径归一化和 diff range 映射逻辑，确保首跳风险与正式审查结论一致。
  若无 diff ranges 可用，再显式回退到文件级风险摘要，并在返回中标注降级路径，不能静默给出低风险。

• 修复并固化 analysis 工具回归
  保留当前源码中已修正的 tools/analysis_tools.py 实现，统一通过 _get_store(repo_root or None) 进入，不再显式把 str 交给 _validate_repo_root()。
  为这 5 个工具补充字符串 repo_root、缺省 repo_root、无图/无仓库三类回归测试。

• 加固 MCP 初始化与长任务稳定性
  保留 show_banner=False 的 stdio 安全设置，并补真实断言，防止回归到会污染 JSON-RPC 握手的行为。
  对长任务保持 asyncio.to_thread，同时补 FastMCP Client 端到端 smoke test；若仍需跨宿主规避 120s 限制，则优先采用 FastMCP 官方的 task/progress 能力，而不是继续靠同步等待。

测试计划

• 安装包真实场景验证
  在非源码目录、只依赖已安装 wheel 的环境里调用：
  get_docs_section_tool('usage') 必须返回 ok。
  5 个 analysis 工具传字符串 repo_root 必须全部返回结构化结果，不得抛 resolve 异常。

• 首跳一致性验证
  使用一个带真实 git diff 的 fixture 仓库和 D:\Android\Project\DSQ 复现仓库：
  get_minimal_context_tool 的风险等级、关键 changed entities、test gap 计数必须与 detect_changes_tool(detail_level='minimal') 在同一数量级，不允许再出现 0.00 对 0.80 这种分裂结果。

• MCP 传输层验证
  使用 FastMCP Client 对 main.mcp 做端到端调用，至少覆盖 get_docs_section_tool、get_minimal_context_tool、detect_changes_tool、build_or_update_graph_tool。
  验证 stdio 模式配置包含 show_banner=False，并确认从中立工作目录调用时行为稳定。

• 打包与发布验证
  校验 wheel 内容中包含文档资源。
  clean venv 安装后，importlib.metadata.version('code-review-graph')、code_review_graph.__version__、CLI --version 三者一致。
  发布前执行“源码目录调用”和“非源码目录调用”双路径 smoke，确保不会再次出现同版本不同实现。

默认假设

• 修复范围包含源码、wheel 打包、MCP 初始化链路和回归测试，不仅限于单个函数补丁。
• 外部宿主里的 120 秒超时先按“集成风险”处理；只有在修复并重新安装新包后仍可本地复现，才升级为核心算法缺陷。
• 当前环境缺少 pytest 与 build 模块，实施时应先在干净虚拟环境中安装 dev/build 依赖，再执行完整验证。
• 官方/稳定方案优先级如下：Python 官方 importlib.resources 处理包内文档资源；FastMCP 官方 Client/task/progress 机制处理长任务与 transport 稳定性；detect_changes 的路径归一化逻辑作为首跳风险分析的唯一基线。