feature: 优化安装速度

[raychen911]

No description provided.

[helloopenworld]

AI Code Review

确认。现在我已经有了所有的发现。让我来写审查意见。

发现的问题

🚨 Critical

• trpc_agent_sdk/agents/__init__.py:86（及 trpc_agent_sdk/agents/utils/__init__.py:52）：__all__ 仍包含懒加载的 graph 导出名，导致 from trpc_agent_sdk.agents import * 在未安装 graph 可选依赖时抛 ImportError，破坏向后兼容。
  • import * 会对 __all__ 中每个名字调用 getattr(module, name)，从而触发 __getattr__ 去加载 _langgraph_agent/_langgraph，在没有 langgraph/langchain_core 的环境下必然失败。新增的 test_optional_graph_dependencies.py 只覆盖显式 from ... import LlmAgent，未覆盖 import * 路径。建议从 __all__ 中移除这些 graph 导出，或把它们放入单独的子模块 __all__。

⚠️ Warning

• trpc_agent_sdk/knowledge/_knowledge.py:41（history: List[BaseMessage] = [] 与 document: Document = None，对应 pyproject.toml:76 knowledge extra）：当未安装 langchain_core 时 Document/BaseMessage 回退为 Any，Pydantic 模型字段失去类型校验且默认值 None/[] 仍可构造，但任何依赖这些字段真实类型（如序列化、model_validate 校验 langchain 对象）的下游代码会静默接受错误类型。

  • 这是 knowledge extra 的真实降级路径；建议至少在 ImportError 分支记录一次 warning，或确认核心包确实不需要这些类型校验。

• pyproject.toml:80：新增 deepseek-langchain extra 定义后，全仓库（examples/pipeline_test/docs）无任何引用，属于死配置。

  • 若无人使用建议移除，避免给用户造成“存在官方支持的 deepseek 集成”的误导；否则应在文档/示例中补一处引用。

• pipeline_test/run_all_examples.sh:393：INCLUDE_MANUAL=true 时无条件拼接 EXTRAS="${EXTRAS},mem0,cube"，但当 RUN_MODE=evaluation（EXTRAS="eval"）时会把 eval,mem0,cube 一起装，属于不必要的依赖安装；更重要的是 run-agent/a2a 模式下若示例实际还用到 knowledge-hf 之外的缺失 extra（如 langchain_tool 在 a2a 模式被排除但 a2a 示例可能间接触发），可能在 CI 产生 ModuleNotFoundError。

  • 建议按 mode 精确声明所需 extras，并核对 a2a 模式是否真的不需要 agent-claude（run_ecosystem_examples.sh 同时装了 a2a,agent-claude，而 run_all_examples.sh 的 a2a 模式只装 a2a）。

• build.sh:48：EXTRAS="${2:-dev}" 后若用户显式传空串（./build.sh uv ""），INSTALL_SPEC=".[]" 会让 pip/uv 解析失败。

  • 建议对空 EXTRAS 做归一化（回退到 dev 或省略 []）。

💡 Suggestion

• build.sh:470（build.sh 整体）：pip 分支末尾的 --dry-run . 在已 --editable .[dev] 安装后再做一次非 editable 的 dry-run 解析，意义有限且与 uv 分支的 uv pip check 不对称；可考虑统一用 pip check / uv pip check 做依赖一致性校验，去掉冗余 dry-run。

总结

本次 PR 主要是将 langgraph/langchain/fastapi 等从核心依赖拆为可选 extra 并改为懒加载，整体方向正确且配套了 install/CI 脚本与示例文档同步更新。存在一个必须修复的兼容性问题：__all__ 仍列懒加载的 graph 导出，会使 import * 在无 graph 依赖时失败。

测试建议

• 补充一条测试：在屏蔽 langgraph/langchain_core 的子进程中执行 from trpc_agent_sdk.agents import *，验证不会因 __all__ 中的 graph 名字而抛 ImportError。
• 补充一条测试：仅安装核心依赖（不含 knowledge extra）时 from trpc_agent_sdk.knowledge import KnowledgeBase, SearchRequest, SearchDocument 可正常导入并实例化，确认 Document/BaseMessage 回退为 Any 不影响核心模型构造。

[helloopenworld]

AI Code Review

现在我已经掌握了完整的情况，让我来总结一下我的审查结论。

发现的问题

🚨 Critical

• tests/agents/test_optional_graph_dependencies.py:13-20：测试的 BlockGraphImports meta path finder 只实现了 find_spec 并对受阻塞模块 raise ModuleNotFoundError，但该 finder 没有提供 loader，依赖 importlib 在 find_spec 抛错时传播异常。问题在于 finder 会在导入 langgraph/langchain/langchain_core 及其任意子模块时抛 ModuleNotFoundError，但子进程仍可能因 langchain 主包（被阻塞）的子模块查找路径命中其它 finder 而绕过；更关键的是该 finder 对所有以这三个名字开头的顶层包抛错，包括 langchain 本身——而 from trpc_agent_sdk.agents import LlmAgent 等核心导入若间接（经由 runners→tools→...）触发任何 langchain 子模块导入就会失败。当前 CI 的 requirements-test.txt 仍安装 langgraph/langchain_community（requirements-test.txt:20,39），子进程里这些包实际存在，finder 主动抛错来模拟"未安装"——这是可行策略，但子进程是全新的解释器、meta_path 重置为默认，sys.meta_path.insert 仅在该子进程内生效，符合预期。真正风险：测试只校验 assert "trpc-agent-py[graph]" in str(exc)，但若未来核心路径意外引入 langchain 导入，finder 抛出的 ModuleNotFoundError 不会被 __getattr__ 转成带提示的 ImportError（因为发生在核心导入而非 LangGraphAgent 的 __getattr__），测试会以 ModuleNotFoundError 失败而非"提示安装"——这会让该测试无法起到"核心导入不依赖 graph"的守卫作用，反而可能误报。建议改用真正不安装 langchain_core/langgraph 的独立环境来验证依赖边界，或在 finder 中对核心导入路径放行、仅对 LangGraphAgent 触发的导入抛错。

⚠️ Warning

• pyproject.toml:134-149 与 pipeline_test/run_all_examples.sh:377-397：[all] extra 与各 run_* 脚本安装的 extras 列表存在不一致，可能导致 pipeline 示例运行时缺包。[all] 包含 langchain>=0.3.27（完整 langchain 主包），而 run_all_examples.sh 的 all/run-agent 模式只装 graph,a2a,agent-claude,knowledge,knowledge-hf,langchain_tool,mempalace,eval，其中 knowledge/knowledge-hf 只声明 langchain-core+langchain_community+langchain_huggingface，不含完整 langchain 主包。但 examples/knowledge_with_* 多个示例 try: from langchain_text_splitters ... except ImportError: from langchain.text_splitter ...（如 examples/knowledge_with_prompt_template/agent/tools.py:24-26），langchain_text_splitters 未在任何 extra/requirements 中声明，回退路径 langchain.text_splitter 又需要完整 langchain 主包——两者都缺。pipeline_test/requirements.txt 也未声明这两个包。这些 knowledge 示例在 run_all_examples.sh 中并未被 skip（仅 knowledge_with_vectorstore 在 skip 列表），运行时会因 ImportError 失败。建议在 knowledge/knowledge-hf extra 或 pipeline_test/requirements.txt 中补上 langchain-text-splitters（或将完整 langchain 纳入 knowledge 相关 extras）。

• pyproject.toml:80：新增 deepseek-langchain = ["langchain-deepseek"] extra，但全仓库（trpc_agent_sdk/、examples/、tests/）均无 langchain_deepseek 的导入或引用（SDK 内的 DeepSeek 支持走 models/openai_adapter/_deepseek.py，不依赖该包）。该 extra 是死配置，会误导用户安装无用依赖。建议删除该 extra，或若计划使用则在文档中说明。

• trpc_agent_sdk/knowledge/_knowledge.py:17-22,71：将 langchain_core 的 Document/BaseMessage 改为 try/except 失败时回退到 Any，使 trpc_agent_sdk.knowledge 可在未装 langchain 时导入。但 SearchDocument.document: Document = None（_knowledge.py:71）在 Document = Any 时字段无类型校验，且 SearchRequest.history: List[BaseMessage] = [] 同样退化为 List[Any]。这本身可接受，但 requirements-test.txt:39-40 仍安装 langchain_community/langchain_huggingface 而 CI 并未装 langchain-core（被移出 core deps），tests/knowledge/test_knowledge.py:15 直接 from langchain_core.documents import Document。若 CI 环境未通过 knowledge extra 间接带入 langchain-core，该测试会在 collection 阶段 ImportError。建议确认 CI 是否安装 langchain-core（目前 requirements-test.txt 未列出 langchain-core，只列出 langchain_community/langchain_huggingface，二者虽通常传递依赖带入 core，但不保证），或显式在 requirements-test.txt 增加 langchain-core。

• build.sh:206-207：pip 分支仍安装 requirements.txt + requirements-test.txt，这两个文件把 langchain==0.3.27、langgraph==0.6.0、fastapi==0.116.1 等重新钉死并作为基础依赖安装，与本次"将 langgraph/langchain/fastapi 拆为可选 extra"的核心目标直接冲突。build.sh 默认 EXTRAS="dev"（build.sh:127），但 pip 分支会先装 requirements.txt 把所有重型依赖装回，使"可选依赖"在 ./build.sh pip 路径下形同虚设。建议让 build.sh 的 pip 分支也基于 extras 安装，或将 requirements.txt/requirements-test.txt 与新的 extras 模型对齐。

💡 Suggestion

• pipeline_test/_install_deps.sh:9-25：pipeline_ensure_uv 先 command -v uv 再 "${python_bin}" -m uv，但 pipeline_uv_cmd（_install_deps.sh:27-35）也按同样优先级选择 uv 还是 python -m uv。两处对 uv 来源的判断重复且分散，若 command -v uv 命中的 uv 与目标 PYTHON_BIN 不匹配（如系统 uv + 另一解释器），可能在混用环境时产生混淆。可统一为一个函数解析 uv 命令并复用，便于维护。

总结

本次 PR 将 LangGraph/LangChain/FastAPI 等重型依赖从 core 拆为可选 extra 并通过 __getattr__ 延迟加载，方向正确，核心导入链已确认不依赖 graph 包；但 extras 声明与 requirements*.txt/pipeline 脚本之间存在多处不一致，可能导致 CI 与示例运行时缺包或重复安装，其中 knowledge 示例缺 langchain-text-splitters/完整 langchain 主包是较明确的风险，建议修复后再合入。

测试建议

• 补充一个真正在"未安装 langchain-core/langgraph"的独立 venv 中运行 import trpc_agent_sdk.agents（含 LlmAgent、Runner、TRPC_EVENT_MARKER）的集成测试，替代当前用 meta path finder 模拟缺包的子进程测试，以避免 finder 行为与真实缺包语义不一致。
• 在 pipeline 中实际执行一次 run_all_examples.sh all（含 --include-manual）验证 knowledge/langchain_tools 类示例是否能正常导入与运行，覆盖 langchain-text-splitters 回退路径。

[helloopenworld]

meta path finder 模拟缺包测试无法稳定守卫核心导入

BlockGraphImports finder 对所有以 langchain/langgraph/langchain_core 开头的顶层包抛 ModuleNotFoundError，若核心导入路径意外引入这些导入，异常不会经 LangGraphAgent 的 getattr 转成带提示的 ImportError，测试会以 ModuleNotFoundError 失败而非提示安装，守卫失效甚至误报。建议改用真正不安装 langchain-core/langgraph 的独立环境，或在 finder 中对核心导入放行。

[helloopenworld]

AI Code Review

所有示例都指向 [graph]。其中 team_member_agent_langgraph 特别使用了 init_chat_model("deepseek:...")，这需要 langchain-deepseek。这是一个 Warning（兼容性风险）。

我现在有足够的信息来撰写审查报告了。让我整理一下。

已确定的实际问题：

1. Warning — examples/team_member_agent_langgraph 使用了 init_chat_model("deepseek:...")，这需要 langchain-deepseek（来自 deepseek-langchain 扩展），但 README 和流水线的 EXTRAS 仅安装了 [graph]（不包含 langchain-deepseek）。示例在运行时会失败。

让我再仔细检查一下 pyproject 中 dev 扩展的清理工作是否会破坏 build.sh 的 pip 路径。build.sh 的 pip 路径安装了 requirements.txt、requirements-test.txt 和 --editable .[dev]。requirements.txt 中固定了 langchain==0.3.27、langgraph==0.6.0 和 fastapi。因此，pip 路径仍然会安装这些包。没问题。

再检查一个：build.sh 的 pip 路径安装了 --dry-run .（核心安装），这可能会因为现在已在核心依赖中而触发重新解析 python-dotenv 和 mcp<2.0.0。没问题。

让我验证一下 pipeline_test/run_agent_examples.sh 是否安装了 [graph]——对于 team_member_agent_langgraph，这意味着使用 [graph] 运行，但同样缺少 deepseek。确认。相同的问题。

让我写出审查报告。

发现的问题

🚨 Critical

（无）

⚠️ Warning

• examples/team_member_agent_langgraph/agent/agent.py:46-49：示例使用 init_chat_model("deepseek:...")，需要 langchain-deepseek 包，但该包未包含在 graph extra 中。
  • 该示例 README 仅写 ./build.sh "[graph]"，而 pyproject.toml:82 的 deepseek-langchain = ["langchain-deepseek"] 是独立 extra；pipeline_test/run_all_examples.sh:379,382 的 all/run-agent 模式 EXTRAS 也只装 graph 不装 deepseek-langchain。运行时 init_chat_model 会因找不到 langchain_deepseek.ChatDeepSeek 而抛 ImportError，导致该示例在本地和流水线中失败。建议在该示例 README 安装命令与流水线 EXTRAS 中补上 deepseek-langchain，或改用 SDK 自身的 OpenAIModel。

    model = init_chat_model(
        f"deepseek:{model_name}",
        ...
    )

💡 Suggestion

• build.sh:700-715：uv 安装路径未对安装结果做任何冒烟校验（旧 build_mac_uv.sh 有 import trpc_agent_sdk 校验），可加一行 uv run --no-sync python -c "import trpc_agent_sdk" 以便在依赖边界拆分后尽早暴露核心导入失败。

总结

整体为依赖边界拆分（将 langgraph/langchain/fastapi 等从核心依赖移至 optional extras）及构建脚本统一化，方向正确且核心 Agent 导入链已清理干净、配套了可选依赖守卫测试。主要风险是 team_member_agent_langgraph 示例依赖 langchain-deepseek 但未在 [graph]/流水线 extras 中声明，会导致该示例运行失败，建议修复。

测试建议

• 补充一个在仅安装 graph（不含 deepseek-langchain）环境下运行 examples/team_member_agent_langgraph 的用例，验证 init_chat_model("deepseek:...") 的依赖声明是否完整。
• 在 CI 中增加一条“仅核心依赖（无任何 extras）下 import trpc_agent_sdk 及导入 LlmAgent/Runner 成功”的步骤，固化本次可选依赖边界的回归保护。