langchain v3+ agent开发需严格对齐模块结构、运行时与调试配置：必须使用langchain_openai.chatopenai等子包导入，禁用justmycode并启用subprocess调试，统一python解释器与环境变量。
LangChain 的 Agent 开发环境在 VSCode 中不是“装个插件就跑起来”，而是必须分层对齐 Python 运行时、框架版本、调试协议和 LLM 接入方式。2026 年实测下来，**直接 pip install langchain 后写 AgentExecutor 就报错 AttributeError: module 'langchain' has no attribute 'llms' 的情况，90% 是因为没切到 v3+ 的模块结构或没禁用旧版兼容层**。
确认 LangChain v3+ 模块结构与 import 写法
LangChain v3（2025 年底起为默认）彻底移除了 langchain.llms、langchain.chains 等顶层模块，全部下沉到子包。写错 import 会立刻失败：
-
from langchain_openai import ChatOpenAI✅（不是langchain.llms.OpenAI） -
from langchain_core.tools import tool✅（不是langchain.tools） -
from langgraph.graph import StateGraph✅（Agent 编排推荐用langgraph，非langchain.agents）
运行时验证命令：python -c "from langchain_core.runnables import Runnable" —— 若报 ModuleNotFoundError，说明装的是旧版或未激活正确虚拟环境。
VSCode 必须启用的 Python 和 Jupyter 扩展组合
仅装 ms-python.python 不够，langchain 调试依赖 Jupyter 内核通信与变量实时 inspection。实测缺失以下任一，debugger 无法进入 Runnable.invoke() 内部：
-
ms-python.python：确保 Python 解释器路径指向你venv的bin/python（Linux/macOS）或Scripts\python.exe（Windows） -
ms-toolsai.jupyter：必须启用，且需在命令面板（Ctrl+Shift+P）中执行Jupyter: Select Interpreter to Start Jupyter Server，选同一虚拟环境 -
ms-vscode.vscode-typescript-next：LangChain v3 的 TypeScript 绑定（如langchain-js）虽非必需，但 VSCode 的智能提示严重依赖它解析类型定义
检查点：Python: Show Output 面板里应出现 Starting Jedi Python language server 和 Jupyter Server started 两行日志。
launch.json 中调试 Agent 的关键参数
VSCode 默认的 Python 调试配置不识别 langgraph 或 Runnable 的异步调用栈。要进断点，必须显式启用 subProcess 和禁用 justMyCode：
将小说章节转换为电影分镜剧本。用户上传txt/md/docx文本，AI分析场景、角色、情绪、镜头语言，输出专业分镜脚本。适用于用户提及“分镜”“storyboard”“小说转分镜”“影视改编”“镜头脚本”或需要将小说改编为分镜的场景。
{
"version": "0.2.0",
"configurations": [
{
"name": "LangChain Agent Debug",
"type": "python",
"request": "launch",
"module": "langchain_core.runnables.base",
"args": [],
"console": "integratedTerminal",
"justMyCode": false,
"subProcess": true,
"env": {
"LANGCHAIN_TRACING_V2": "true",
"LANGCHAIN_ENDPOINT": "https://api.smith.langchain.com"
}
}
]
}
注意：justMyCode: false 是硬性要求，否则断点卡在 Runnable.__call__ 外层就停住；subProcess: true 才能穿透 asyncio.run() 启动的事件循环。
LLM 接入时最容易被忽略的环境隔离问题
本地跑 ChatOpenAI 或 ChatQwen 时，API key 和 base_url 错误常表现为超时而非报错。真实原因往往是：
- VSCode 终端用了系统 Python，而调试器用了虚拟环境 Python —— 两者
.env文件不共享 -
os.getenv("OPENAI_API_KEY")在调试器中返回None，但终端里能取到（因为没 reload 环境变量） - DeepSeek / Qwen 等国产模型需手动设
base_url，但langchain_openai.ChatOpenAI默认只认 OpenAI 官方地址
解决方式：统一在 .vscode/settings.json 加：
"python.defaultInterpreterPath": "./venv/bin/python",
"python.envFile": "${workspaceFolder}/.env"
然后确保 .env 文件里写的是 QWEN_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1 这类完整地址，而不是只写 key。
langchain.agents 已成弃用路径，真正落地 Agent 流程得靠 langgraph + langchain_core 的组合；VSCode 调试器若没设 justMyCode: false，连最简单的 tool 调用都进不去源码。
