一、为什么市面上的 Agent 都不愿“透明”？
1.1 一个被全行业刻意忽视的体验黑洞
打开任何一个 AI Agent 产品——无论是国外还是国内主流大模型应用——你会发现一个惊人的共同点：你永远看不到 AI 是怎么想的。
用户输入一个问题，等了几秒，Agent 返回了一串“调用工具”、“搜索中”、“正在思考”的提示，然后给出了答案。中间发生了什么？模型在决定调用工具之前做了什么判断？为什么选了工具 A 而不是工具 B？每一步消耗了多少 Token？花了多少钱？
这些问题，用户永远不知道。不是因为技术做不到，而是因为没人愿意做。
我们来剖析一下背后的原因：
（1）产品理念冲突：魔法感 vs. 可信赖
大厂的产品经理们喜欢“魔法感”。用户说完话，AI 直接给答案，好像一切都理所当然。如果让用户看到 AI 其实是一步步推出来的——“我得先查一下当前时间”、“我需要搜索最新新闻”、“我还得验证一下这个地址是否安全”——这种“祛魅”会削弱产品的神秘感。
但对于一个个人 AI 管家来说，它需要的恰恰是可信赖，而不是魔法感。管家是可以被主人质疑的——“你刚才为什么要做这个操作？”——如果没有推理过程的记录，就无法追溯决策依据。
（2）商业利益冲突：成本透明化会劝退用户
Token 消耗明细这个东西，技术上就是解析流式响应中 usage 字段的几行代码。但为什么 ChatGPT 不告诉你每次对话花了多少钱？因为一旦用户知道了精确成本，就会开始计算 ROI，从而减少使用频率。对商业公司来说，模糊成本、制造黑盒，更符合商业利益。
（3）技术成本与商业回报不匹配
这两个功能确实有一定的工作量。深度思考折叠区涉及流式解析、前后端通信、动态 DOM 渲染、历史消息回显、交互优化（折叠/复制/滚动控制）等一系列问题。Token 明细虽然代码量不大，但需要理解 SSE 协议、设计估算算法、处理好前后端展示。做出来之后，公司怎么赚钱？不直接。所以大公司不会优先做这类“不赚钱但费工程师”的功能。
1.2 本文要做什么
本文以我个人开发的“Web3多链监控交易系统”中的Agent功能板块为蓝本，详细拆解两个核心功能的完整实现：
| 深度思考折叠区 | 实时流式展示 AI 的完整推理过程 | SSE 流解析、缓冲区设计、前后端通信、工具调用后的递归处理、历史消息回显 |
| Token 消耗明细 | 细粒度展示系统提示词、对话历史、工具定义各部分的 Token 消耗 | Token 估算算法、usage 字段解析、明细可视化 |
文章会贴出所有关键技术环节的代码片段（仅保留完整方法实现，但核心算法和数据结构全部公开），以及设计原理的深入分析。读完本文，你将完全理解如何为自己的 Agent 系统实现类似功能。
1.3 技术栈与架构预览
本文涉及的系统采用以下技术栈：
-
后端：Python + PyWebView（桌面端框架）+ DeepSeek API
-
前端：原生 JavaScript（无框架），通过 window.evaluate_js 与 Python 通信
-
数据流：SSE（Server-Sent Events）流式响应
-
数据库：SQLite（存储聊天历史与推理内容）
整体数据流如下图所示：
用户消息 → agent_process_input → _build_system_prompt → _call_model_with_tools ↓ _stream_deepseek_reasoner（核心函数） ↓ ┌───────────┼───────────┐ │ │ │ 解析 SSE 提取 usage 检测 tool_calls │ │ │ ↓ ↓ ↓ 推理内容 Token 明细 执行工具 → 清洗消息 → 递归调用 ↓ ↓ _push_thinking 拼接明细 ↓ ↓ └───────────┼───────────┘ ↓ window.evaluate_js → 前端实时渲染
在后续章节中，我们将沿着这条数据流，逐一拆解每个环节的实现细节。
二、整体技术架构设计
在深入具体实现之前，必须先把整个系统的架构和数据流讲清楚。深度思考可视化不是单一模块的功能，而是跨越多层架构的全链路设计——从最底层的 HTTP 流式请求，到中间的 Python 业务逻辑，到最上层的前端 DOM 渲染，每一层都有需要解决的技术问题。
2.1 核心模块与职责划分
整个系统由四个核心模块构成，它们各自承担明确的职责：
| AI 调用层 | ai_calls.py | 发起流式请求、解析 SSE 响应、提取推理内容与 Token 信息、处理工具调用的递归逻辑 |
| 消息推送层 | base.py | 提供 _push_thinking 方法，将推理片段安全地推送到前端，处理 JSON 转义与异常兜底 |
| 前端渲染层 | agent.js | 接收推理片段，动态创建/更新折叠区 DOM，处理用户交互（折叠、复制、滚动控制） |
| 系统提示词层 | ai_calls.py | 构建完整的系统提示词，注入主人信息、反思笔记、关键词记忆检索结果等 |
设计原则：
-
单向数据流：推理内容从后端 → 前端是单向推送，前端不需要轮询或请求。
-
职责分离：AI 调用层只负责“获取数据”，消息推送层只负责“传递数据”，前端渲染层只负责“展示数据”。
-
降级容错：每一层都有独立的错误处理，单层失败不影响其他层的正常运行。
2.2 全链路数据流详解
下图展示了从用户发送消息到前端展示推理过程的完整数据流：
┌─────────────────────────────────────────────────────────────┐ │ 用户发送消息 │ └────────────────────────┬────────────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ agent_process_input (api_agent.py) │ │ ├── 提取平台、模型、用户输入等参数 │ │ ├── 生成 batch_id（用于关联工具调用日志） │ │ ├── 调用 _save_chat_message 保存用户消息到数据库 │ │ ├── 调用 _build_system_prompt 构建系统提示词 │ │ │ ├── 注入主人信息（偏好链、兴趣领域等） │ │ │ ├── 注入 Agent 自我认知（角色、性格等） │ │ │ ├── 注入反思笔记（最近一次深度观察） │ │ │ ├── 注入关键词匹配记忆检索结果 │ │ │ └── 拼接工具列表描述 │ │ ├── 调用 _load_recent_history 加载最近对话历史 │ │ └── 调用 _call_model_with_tools(messages, \”thinking\”) │ └────────────────────────┬────────────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ _call_model_with_tools (ai_calls.py) │ │ ├── 根据 model_type 路由到对应方法 │ │ │ ├── \”thinking\” → _stream_deepseek_reasoner │ │ │ ├── \”deepseek\” → _call_deepseek_with_tools │ │ │ ├── \”local\” → _call_local_model │ │ │ └── 其他 → 检查自定义模型配置 │ │ └── 返回最终回复文本或 None │ └────────────────────────┬────────────────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────┐ │ _stream_deepseek_reasoner (ai_calls.py) │ │ ├── 清洗消息（_sanitize_messages） │ │ ├── 构建流式请求 payload（含 reasoning_effort=\’max\’） │ │ ├── 发起 HTTP 流式 POST 请求 │ │ &
