本教程的核心在于通过一个 4W 情景感知框架 来深度理解用户，从而实现更智能、更个性化的交流。为了方便代码的复制，本demo将所有的代码放在的一个文件中。
在每次回应前，AI 都会像人类一样思考：
- WHO (用户是谁): 基于动态用户画像，了解你的个性和偏好。
- WHAT (在聊什么): 分析当前对话的核心主题。
- WHY (意图为何): 洞察你字面下的真实意图和潜在需求。
- HOW (需求为何): 提炼出需要解决的具体问题或任务，选择匹配的策略。
这种“先理解，后回应”的模式，结合策略规划、工具调用和多模态能力，让 AI 不再是简单的问答机器，而是一个真正“更懂你”的智能伙伴。
本项目通过一系列精心设计的模块，实现了 AI 代理的复杂思考与决策流程：
AI 会在每次对话时对当前情景进行全面分析，构建一个“情景快照”（Situational Snapshot），这正是 4W 框架的具体实现：
WHO(用户是谁): 动态更新和利用用户画像数据。WHAT(聊什么): 分析当前对话的主题，并判断是否为新话题。WHY(意图为何): 挖掘用户的显式意图和最多三个潜在的隐式意图。HOW(需求为何): 提炼用户的核心需求和关键实体，并综合选择匹配的策略。
AI 会在对话过程中持续学习和完善你的用户画像（User Profile）。这不仅仅是简单的信息记录，而是基于大五人格模型 (OCEAN) 的深度推断，涵盖：
- 身份认同 (Inferred Identity): 推断用户的基本信息。
- 个性与价值观 (Personality and Values): 分析性格标签和价值观。
- 沟通风格 (Communication Profile): 识别沟通特点和语言习惯。
- 知识与兴趣 (Knowledge and Interests): 记录技能、爱好、好恶等。
- 目标与愿景 (Goals and Aspirations): 捕捉用户提及的目标。
在理解了情景和用户后，AI 不会草率地直接回答，而是先制定一个明确的行动计划（Action Plan）。它会从多种策略中选择最合适的一种：
直接解答 (DIRECT_ANSWER): 对于简单、明确的问题，直接给出答案。澄清反问 (CLARIFY_ASK): 当需求不够明确时，通过少量问题主动澄清。深入追问 (INTERROGATE): 当用户意图非常模糊或宏大时，通过一连串问题进行深入探索，以协助用户理清思路。工具调用 (TOOL_USE): 当需要执行计算、查询API等具体任务时，调用相应工具。检索增强生成 (RAG_QUERY): 当需要基于内部知识库回答时，先进行精确检索。搜索代理 (SEARCH_AGENT_DELEGATION): 当需要最新的、开放域的互联网信息时，委托给专门的搜索子代理。对冲回答 (HEDGING): 对于没有唯一答案的复杂或主观问题，提供多种可能性、观点或选项，而非给出单一结论。拒绝回答 (REFUSE): 当用户的请求不安全、不道德或超出能力范围时，礼貌地拒绝回答。
框架内置了灵活的工具管理器和专门的子代理，使其能力可以轻松扩展：
- 工具箱: 预置了如网页内容抓取 (
get_url_content)、计算器 (calculator) 和模拟的公司财报查询等工具。 - 搜索子代理 (Search Agent): 一个独立的 LangGraph 工作流，专门负责处理需要互联网搜索的复杂查询，实现任务的分解和委托。
AI 不仅能理解文本，还能“看懂”图片。你可以直接上传图片、粘贴图片URL，AI 会：
- 调用多模态视觉模型（如
qwen-vl-plus）对一张或多张图片进行综合描述。 - 将图片内容作为对话上下文，进行相关的提问和讨论。
内置多种预设的 AI 人格（Persona），例如“专业AI助手”、“友好伙伴”、“创意缪斯”、“互联网段子手”等。你可以随时切换，体验不同风格的对话。
Web UI 界面右侧的“AI 在想什么”面板会实时展示 AI 的思考过程，包括情景快照分析结果和行动规划详情，让你清晰地了解 AI 每一步的决策依据。
当对话历史变得过长时，系统会自动触发压缩机制，将早期的对话内容总结为一段“前情提要”，既能保留长期记忆，又能避免超出模型的上下文长度限制。
本框架的核心是基于 LangGraph 构建的状态机工作流。用户的每一次输入都会触发这个图的完整执行流程，模拟了 AI 的“思考链”。
请按照以下步骤在您的本地环境中部署和运行本项目。
- Python 3.12 或更高版本。
- 一个包管理工具，如
pip。
git clone https://github.com/zhao6300/3wchat.git
或者
git clone https://gitee.com/ht6300/3wchat.git
cd 3wchat项目依赖已在 requirements.txt 文件中列出。请运行以下命令进行安装：
pip install -r requirements.txt以下是 requirements.txt 文件的内容：
gradio
openai
langgraph
langchain-core
langchain-google-genai
pydantic
requests
python-dotenv
这是最关键的一步。我们强烈建议使用环境变量来配置应用。在项目根目录创建一个名为 .env 的文件，并将以下内容复制进去，然后根据你的需求进行修改。
# -----------------------------------------------------------------------------
# 核心 API 配置 (必须)
# -----------------------------------------------------------------------------
# 你的 API Key 来自一个兼容 OpenAI 接口的服务 (例如: 阿里云 DashScope)
API_KEY="YOUR_API_KEY"
# 服务的 Base URL
BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
# -----------------------------------------------------------------------------
# 模型选择 (可选 - 如果不设置，将使用代码中的默认值)
# 你可以为不同任务分配不同模型，以平衡成本和性能。
# 例如，使用 qwen-turbo 处理简单任务，qwen-max 处理核心任务。
# -----------------------------------------------------------------------------
ANALYSIS_MODEL="qwen-plus-latest"
STRATEGY_MODEL="qwen-plus-latest"
RESPONSE_MODEL="qwen-plus-latest"
SUMMARY_MODEL="qwen-plus-latest"
RETRIEVAL_MODEL="qwen-plus-latest"
PROFILE_MODEL="qwen-plus-latest"
VISION_MODEL="qwen-vl-plus"
# -----------------------------------------------------------------------------
# 行为定制 (可选 - 如果不设置，将使用代码中的默认值)
# -----------------------------------------------------------------------------
# 对话历史超过多少条消息后触发压缩
HISTORY_COMPRESSION_THRESHOLD=20
# 压缩时保留最近多少条消息不被压缩
MESSAGES_TO_KEEP_UNCOMPRESSED=6
# 每隔多少轮对话更新一次用户画像 (1 表示每轮都更新)
PROFILE_UPDATE_INTERVAL=1
# -----------------------------------------------------------------------------
# 工具配置 (可选)
# -----------------------------------------------------------------------------
# 用于 get_url_content 工具的 Jina Reader API Key
# 访问 https://jina.ai/reader/ 获取免费 Key
JINA_API_KEY=""-
API 配置 (必须)
API_KEY: 您的服务密钥。请务必替换"YOUR_API_KEY"。BASE_URL: API 的入口地址。默认配置为阿里云 DashScope 的通义千问模型服务。
-
模型选择 (可选)
- 您可以为框架中不同的思考步骤（分析、策略、响应等）指定不同的模型。这对于优化成本非常有用，例如为简单任务（如摘要）使用更便宜的模型。
VISION_MODEL: 用于识别和描述图片的多模态模型。
-
行为定制 (可选)
HISTORY_COMPRESSION_THRESHOLD: 对话历史的长度阈值。当消息总数超过此值时，会触发自动摘要功能。MESSAGES_TO_KEEP_UNCOMPRESSED: 在执行摘要时，保留最近的 N 条消息，以确保短期上下文的完整性。PROFILE_UPDATE_INTERVAL: 控制用户画像的更新频率。1表示每轮对话都更新，5表示每 5 轮对话更新一次。
python 3w_chat.py如果一切正常，您会在终端看到类似以下的输出：
Running on local URL: http://127.0.0.1:7860
现在，您可以在浏览器中打开 http://127.0.0.1:7860，开始与您的高级 AI 助手进行交互！
- 会话管理: 在左侧边栏，您可以创建新会话 (
+ 新建会话)、切换不同会话或删除当前选中的会话。每个会话都有独立的历史记录和用户画像。 - 切换人格: 在左侧边栏的下拉菜单中选择一个AI人格，AI的回复风格会立即改变。
- 发送消息与图片: 在底部的输入框中输入文本，或点击“🖼️ 上传图片”按钮来发送图片。您也可以直接在文本中粘贴图片的 URL。
- 观察思考过程: 在右侧的“🧠 AI 在想什么”面板中，实时查看AI对您输入的分析（情景快照）和决策过程（行动规划），深入了解其工作原理。
本框架具有良好的可扩展性，您可以轻松进行定制：
- 添加新工具:
- 使用
@tool装饰器定义一个新的工具函数。 - 在主程序入口处，使用
tool_manager.register_tool(your_new_tool)进行注册。
- 使用
- 添加新的人格:
- 打开
PersonaManager类。 - 在
_load_default_personas方法中，仿照现有格式添加一个新的Persona实例。
- 打开
- 更换或调整模型:
- 直接修改
.env文件中的模型名称即可。
- 直接修改