1. 项目缘起：从“黑盒”到“透明”的探索
最近在折腾AI Agent开发，特别是用Claude Code来写一些自动化脚本和小应用。我让Claude帮我写了一个经典的贪吃蛇游戏，整个过程很顺畅，代码质量也不错。但作为一个喜欢刨根问底的开发者，我总感觉少了点什么——我看到的只是Claude最终吐出来的那几十行Python代码，而它背后“思考”的过程，比如它调用了哪些工具、如何规划步骤、遇到了什么错误又怎么回退的，对我来说完全是个“黑盒”。这就像你请了一个顶级大厨，他只把做好的菜端上来，却不让你看厨房里发生了什么。对于学习AI工作流和调试复杂的Agent任务来说，这种不透明性是个很大的障碍。
于是，我想搞清楚Claude Code这个“AI员工”到底是怎么干活的。它收到我的指令后，内部究竟发起了哪些请求？调用了哪些函数？参数是什么？有没有失败重试？传统的做法可能是去翻SDK文档或者看网络日志，但都比较麻烦。这时，我想到了ccglass这个工具。简单来说，ccglass是一个专门用于观测和分析AI Agent内部工作流的工具，它能让你像用X光一样，“看清”Agent与底层大模型（LLM）之间的每一次对话、每一次工具调用。这个项目的核心，就是利用ccglass，把我让Claude写贪吃蛇游戏这个看似简单的任务，背后所有的“真实请求”给完整地呈现出来。
通过这个实践，你不仅能得到一个可玩的贪吃蛇游戏，更重要的是，你能获得一套方法论，去深入理解任何AI Agent的执行链路。这对于调试复杂任务、优化提示词、评估Agent成本乃至学习其决策逻辑，都至关重要。无论你是刚接触AI Agent的新手，还是想提升现有应用可观测性的资深开发者，这个“解剖”过程都会给你带来新的启发。
2. 环境与工具准备：搭建你的观测平台
工欲善其事，必先利其器。要让ccglass成功捕获到Claude Code的请求，我们需要一个能运行Claude Code，并能被ccglass监控的环境。这里我选择了一条对大多数开发者都比较友好的路径：在本地使用VSCode配合Claude Code扩展，并通过一个Python中间层来“代理”和记录所有请求。
2.1 Claude Code的安装与基础配置
首先，你需要在VSCode中安装Claude Code扩展。打开VSCode，进入扩展市场，搜索“Claude Code”并安装。安装完成后，你通常需要在侧边栏找到Claude的图标，并登录你的Claude账户（通常是Anthropic的账户）来获得API访问权限。这里有一个关键点：Claude Code扩展默认会直接使用其集成的后端服务与Claude API通信，这个通道我们很难直接拦截。因此，我们的策略不是去破解这个扩展，而是“模拟”或“重定向”它的请求。
一个更可行的方案是，我们不直接依赖VSCode扩展的完整工作流，而是使用Claude提供的官方Python SDK来构建一个我们能够完全控制的脚本。这样，ccglass就能清晰地捕获到我们脚本发出的每一个API调用。你可以通过pip安装Anthropic的官方库：
pip install anthropic安装后，你需要设置你的API密钥。在项目根目录创建一个.env文件，将你的Claude API密钥放进去：
ANTHROPIC_API_KEY=your_api_key_here然后，在Python脚本中通过os.getenv或python-dotenv来加载它。这就为我们创建了一个标准、可控的与Claude对话的环境。
2.2 认识ccglass：AI工作流的“显微镜”
ccglass并不是一个广为人知的流行框架，它在社区中的定位更偏向于一个专业的可观测性工具。你可以把它理解为一个“AI Agent的调试器”或“工作流录制器”。它的核心功能是装饰（Decorator）或包装（Wrapper）你的AI调用代码，自动记录下每次LLM调用的输入（提示词）、输出（响应）、消耗的Token数、使用的模型、调用的工具（函数）及其参数和结果、执行耗时等元数据。
这些数据会被ccglass收集、结构化，并通常以一个本地Web界面的形式展示出来，形成一个清晰的可视化时间线。这样，你就能一目了然地看到：“哦，Agent首先分析了我的需求，然后调用了Python代码生成工具，生成后可能还调用了一个代码验证工具，最后把结果返回给了我。” 整个过程不再是魔法，而变成了可追溯、可审计的步骤。
对于本项目，我们不需要部署复杂的ccglass服务端。我们可以利用其核心的日志记录理念，自己构建一个轻量级的“请求记录器”。具体来说，我们将创建一个自定义的Anthropic客户端类，它继承或包装官方客户端，在每次调用messages.create方法前后，将详细的请求和响应信息以结构化的格式（如JSON）保存到本地文件或打印出来。这就是我们自制“ccglass”的核心。
2.3 构建自制请求记录器
下面是一个简单的自制记录器示例，它模拟了ccglass的核心记录功能：
import json import time from datetime import datetime from anthropic import Anthropic import os from dotenv import load_dotenv load_dotenv() class ClaudeClientWithLogging: """一个包装了Anthropic官方客户端并添加了详细日志记录的类。""" def __init__(self): self.api_key = os.getenv("ANTHROPIC_API_KEY") if not self.api_key: raise ValueError("请在.env文件中设置ANTHROPIC_API_KEY") # 初始化真正的客户端 self.client = Anthropic(api_key=self.api_key) # 日志文件 self.log_file = f"claude_trace_{datetime.now().strftime('%Y%m%d_%H%M%S')}.jsonl" self.log_entries = [] def log_interaction(self, entry): """记录一次交互到内存和文件。""" self.log_entries.append(entry) # 使用jsonl格式，每行一个JSON对象，便于后续分析 with open(self.log_file, 'a', encoding='utf-8') as f: f.write(json.dumps(entry, ensure_ascii=False) + '\n') print(f"[LOG] 记录一次交互: {entry.get('type', 'unknown')}") def create_message(self, **kwargs): """包装messages.create方法，记录请求和响应。""" trace_id = f"trace_{int(time.time()*1000)}" # 1. 记录请求 request_entry = { "trace_id": trace_id, "type": "request", "timestamp": datetime.now().isoformat(), "model": kwargs.get('model'), "max_tokens": kwargs.get('max_tokens'), "messages": kwargs.get('messages'), "tools": kwargs.get('tools'), # 记录可能使用的工具定义 "metadata": kwargs.get('metadata', {}) } self.log_interaction(request_entry) # 2. 执行实际请求并计时 start_time = time.time() try: response = self.client.messages.create(**kwargs) elapsed_ms = int((time.time() - start_time) * 1000) except Exception as e: elapsed_ms = int((time.time() - start_time) * 1000) # 3. 记录错误响应 error_entry = { "trace_id": trace_id, "type": "response_error", "timestamp": datetime.now().isoformat(), "elapsed_ms": elapsed_ms, "error": str(e) } self.log_interaction(error_entry) raise e # 4. 记录成功响应 response_entry = { "trace_id": trace_id, "type": "response_success", "timestamp": datetime.now().isoformat(), "elapsed_ms": elapsed_ms, "response_id": response.id, "model": response.model, "role": response.role, "content": [c.model_dump() for c in response.content], # 将内容对象转为字典 "usage": { "input_tokens": response.usage.input_tokens, "output_tokens": response.usage.output_tokens }, "stop_reason": response.stop_reason } self.log_interaction(response_entry) return response # 使用我们包装的客户端 client = ClaudeClientWithLogging()这个ClaudeClientWithLogging类就是我们的“ccglass”核心。它会在每次API调用时，生成一个唯一的trace_id来关联请求和响应，并详细记录下所有相关信息，保存为.jsonl格式的日志文件。这种格式易于用脚本分析，也方便导入到其他可视化工具中。
3. 任务执行与请求捕获：让贪吃蛇“现形”
有了可控的客户端和记录器，我们就可以开始执行“编写贪吃蛇游戏”这个任务，并观察全过程了。我们的目标不是简单地拿到最终代码，而是记录下Claude为了完成这个任务，可能进行的多轮对话和思考过程。
3.1 设计一个能激发多步推理的提示词
如果我们只是问：“用Python写一个贪吃蛇游戏”，Claude可能会直接输出一整段代码。这虽然高效，但内部可能只是一次简单的代码生成调用，观测到的链路太短，价值不大。为了看到更丰富的Agent行为（比如规划、分解任务、可能调用代码解释或验证工具），我们需要设计一个更复杂、要求更高的提示词。
我使用了类似下面的提示词，旨在模拟一个真实开发场景：
system_prompt = """你是一个专业的Python开发助手。请按照以下步骤为用户创建一个可运行的贪吃蛇游戏： 1. 首先，分析在命令行环境中实现贪吃蛇游戏需要哪些核心模块（如输入处理、游戏循环、图形绘制等）。 2. 然后，逐步构建游戏。先实现游戏地图和蛇的初始状态表示。 3. 接着，实现蛇的移动逻辑和方向控制。 4. 再实现食物的随机生成和碰撞检测（吃到食物、撞墙、撞自身）。 5. 最后，整合所有部分，并确保游戏循环逻辑正确。 请分步进行，每一步完成后向我确认，或直接给出该部分的代码。如果使用任何假设（如使用`curses`库或`keyboard`库），请先说明。"""这个提示词要求分步执行，并且提到了具体的库（curses），这更有可能让Claude在回复中展示其“思考-行动”的过程，甚至可能主动提出要使用某个“代码执行”工具来验证部分逻辑（虽然在我们这个简单记录场景，它没有实际执行环境，但请求中可能会包含工具调用的意图）。
3.2 发起对话并记录全链路
现在，我们使用包装好的客户端发起这次对话：
# 发起初始请求 print("开始请求Claude创建贪吃蛇游戏...") try: response = client.create_message( model="claude-3-5-sonnet-20241022", # 使用一个较新的模型 max_tokens=4000, system=system_prompt, messages=[ {"role": "user", "content": "请开始创建贪吃蛇游戏。"} ] # 注意：这里我们没有传递tools参数，因此Claude不会进行实际工具调用。 # 但它的回复内容中，可能会以文本形式描述其“计划”或“步骤”。 ) # 打印Claude的第一轮回复 print("\n--- Claude的第一轮回复 ---") for content_block in response.content: if content_block.type == 'text': print(content_block.text) # 接下来，我们可以根据Claude的回复进行多轮对话 # 例如，Claude可能会说：“第一步，我们需要表示游戏区域。我假设我们使用一个二维列表...” # 我们可以回复：“好的，请给出这一步的代码。” # 这个过程会持续，直到游戏完成。 # 每一轮对话都会被我们的client.create_message方法记录。 except Exception as e: print(f"请求过程中发生错误: {e}")在实际操作中，我让这个对话进行了3-4轮。Claude首先给出了一个计划，然后分步提供了地图表示、蛇的移动、食物生成等代码片段。每一轮问答，都被我们的记录器完整地捕获了下来，生成了一个包含多个request和response_success条目的日志文件。
3.3 关键发现：解读日志中的“真实请求”
执行完毕后，打开生成的.jsonl日志文件，我们就能像用ccglass一样，清晰地看到整个工作流。以下是我从日志中提炼的一些关键观察，这些正是“真实请求”的细节：
- 请求的结构化：每个请求体都是一个清晰的JSON对象，包含了
model,messages(对话历史),max_tokens,temperature(虽然我们没指定，默认会有) 等字段。这揭示了Claude API的输入规范。 - 对话历史的维护：在第二轮及之后的请求中，
messages数组包含了之前所有的用户和助手消息。这意味着每次请求，我们都需要把完整的上下文发送过去，Token消耗会累积。这对于计算成本和理解Agent的“记忆”机制很重要。 - 响应的复杂性：响应体不仅仅是文本。
content字段是一个列表，其中可以包含type为"text"的文本块。如果启用了工具调用，这里还可能出现type为"tool_use"的块。我们的简单任务没有用到工具，所以全是文本块。这帮助我们理解了Agent输出结果的标准化格式。 - Token消耗明细：每个响应都附带了
usage字段，明确列出了本次调用消耗的input_tokens和output_tokens。这是进行成本核算和性能优化的直接依据。例如，我发现让Claude分步输出，虽然请求次数多了，但单次输出的Token数较少，总成本可能与一次输出长篇代码相差不大，但获得了更清晰的过程。 - 元信息丰富：
response_id,model,stop_reason等字段，对于调试和日志追踪非常有价值。stop_reason如果是“max_tokens”，就说明输出被截断了，需要调整max_tokens参数。
通过分析这些日志，我恍然大悟：原来Claude Code（或任何基于类似API的Agent）在VSCode里看似流畅的交互，背后就是这些一次次的HTTP请求堆砌起来的。它的“思考”过程，就蕴含在我们提供给它的对话历史以及它根据这些历史生成的下一段文本之中。
4. 深度分析：从请求日志反推AI Agent的工作模式
捕获到原始请求和响应只是第一步，就像拿到了飞机的黑匣子数据。接下来，我们需要解读这些数据，从而理解AI Agent（在这个例子中是Claude）是如何工作的。这对于我们设计更高效的提示词、构建更稳定的Agent系统至关重要。
4.1 会话状态的管理与成本
从日志中可以明显看出，Claude API本身是无状态的。它不会记住上一次对话的内容，除非我们在本次请求的messages参数中把历史对话全部传递过去。这就是所谓的“上下文窗口”（Context Window）管理。
- 我们的做法：在每轮对话中，我们都将之前所有的
user和assistant消息作为上下文传入。这保证了对话的连贯性，Claude才能基于之前的讨论继续编写代码。 - 带来的影响：
- Token成本：输入Token数会随着对话轮次线性增长（实际上是累积增长）。一次长对话的总成本可能远高于多次独立短对话。在我们的贪吃蛇例子中，虽然分了4步，但每次请求都携带了增长的历史，总输入Token数大约是最终代码Token数的好几倍。
- 上下文长度限制：所有模型都有上下文长度上限（如200K Token）。对于超长对话，需要设计摘要或选择性遗忘的机制，这本身就是Agent架构中的一个核心挑战。
- 工程启示：在构建生产级Agent时，我们不能无脑地堆积全部历史。需要实现一个“对话记忆管理”模块，可能采用“滑动窗口”只保留最近N条消息，或者对早期历史进行“摘要”后再放入上下文。ccglass这类工具能帮你精确分析每一轮消耗的Token，从而优化这个策略。
4.2 工具调用（Tool Use）的潜在模式
虽然我们这个简单任务没有显式使用工具，但Claude API是支持工具调用（Function Calling/Tool Use）的。在更复杂的Agent场景中，这是核心能力。通过分析请求日志的格式，我们可以推断出其工作模式：
- 工具定义在请求中：如果我们需要Claude使用工具（比如执行一段生成的代码、查询数据库），我们必须在请求的
tools参数中，以JSON Schema格式定义好工具的名称、描述和参数。这相当于给了Agent一个“技能列表”。 - 工具调用在响应中：Claude的响应
content里，可能会出现type为"tool_use"的块，其中包含它决定调用的工具名称和参数。然后，我们需要在本地执行这个工具（如运行一段Python代码），并将执行结果作为下一条user消息的一部分，以type为"tool_result"的块形式，发送给Claude。 - 循环往复：这样就形成了一个“模型思考 -> 决定调用工具 -> 用户执行工具并返回结果 -> 模型基于结果继续思考”的循环。一个强大的AI Agent，正是通过多次这样的循环来完成复杂任务的。我们的日志记录器可以清晰地记录下每一次“模型请求”、“工具调用请求”、“工具返回结果”的节点，从而绘制出完整的Agent工作流图谱。
实操心得：在定义工具时，描述（description）字段极其重要。清晰、具体的描述能极大提高模型选择正确工具和生成正确参数的几率。例如，与其定义一个叫
run_code的工具，不如定义为run_python_code_in_isolated_sandbox，并在描述中写明：“在安全的沙箱环境中执行一段Python代码字符串，返回标准输出和标准错误。无法访问网络和文件系统。”
4.3 停止原因（Stop Reason）与输出控制
响应中的stop_reason字段是一个重要的诊断信息。它告诉我们模型为什么停止生成文本。
“end_turn”：模型自然地结束了它的回复。这是最理想的情况。“max_tokens”：达到了max_tokens参数设置的限制，输出被截断。这说明我们设置的max_tokens可能不够，需要根据任务调大。但也要注意盲目调大会增加不必要的成本和等待时间。“stop_sequence”：遇到了我们预设的停止序列（如“\n\nHuman:”）。这在设计特定的交互格式时有用。
在我们的贪吃蛇任务日志中，所有回复的stop_reason都是“end_turn”，说明我们的max_tokens设置是充足的，对话进行得很顺畅。如果看到“max_tokens”，我们就需要检查输出的代码是否完整，很可能游戏循环的最后几行被截掉了，导致代码无法运行。
5. 可视化与进阶应用：让日志“活”起来
原始的JSONL日志文件虽然信息全面，但可读性不强。ccglass这类工具的核心价值之一，就是提供可视化界面。我们可以用一些简单的方法，自己实现基础的可视化，让分析更直观。
5.1 使用Streamlit快速构建日志查看器
Streamlit是一个快速创建数据应用的工具，非常适合用来将我们的日志可视化。下面是一个简单的脚本，可以展示对话流和Token消耗：
# trace_viewer.py import streamlit as st import json import pandas as pd from datetime import datetime st.set_page_config(page_title="Claude 请求追踪分析器", layout="wide") st.title("🎮 贪吃蛇游戏开发 - Claude 请求链路追踪") uploaded_file = st.file_uploader("上传你的 .jsonl 追踪日志文件", type=['jsonl']) if uploaded_file is not None: logs = [] for line in uploaded_file: logs.append(json.loads(line.decode('utf-8'))) df = pd.DataFrame(logs) # 1. 显示总体统计 st.header("📊 总体统计") col1, col2, col3 = st.columns(3) total_requests = len(df[df['type'].str.contains('request')]) total_input_tokens = df[df['type']=='response_success']['usage'].apply(lambda x: x.get('input_tokens', 0)).sum() total_output_tokens = df[df['type']=='response_success']['usage'].apply(lambda x: x.get('output_tokens', 0)).sum() col1.metric("总请求数", total_requests) col2.metric("总输入Token", f"{total_input_tokens:,}") col3.metric("总输出Token", f"{total_output_tokens:,}") # 2. 显示对话时间线 st.header("💬 对话时间线") df['timestamp'] = pd.to_datetime(df['timestamp']) df_sorted = df.sort_values('timestamp') for idx, row in df_sorted.iterrows(): with st.expander(f"{row['timestamp'].strftime('%H:%M:%S')} - {row['type']} (Trace: {row.get('trace_id', 'N/A')})"): if row['type'] == 'request': st.markdown("**请求详情**") st.json(row.get('messages', []), expanded=False) if row.get('tools'): st.markdown("**定义的工具**") st.json(row['tools'], expanded=False) elif row['type'] == 'response_success': st.markdown("**响应详情**") st.text(f"模型: {row.get('model')}, 耗时: {row.get('elapsed_ms')}ms") st.text(f"Token消耗: 输入 {row.get('usage', {}).get('input_tokens')}, 输出 {row.get('usage', {}).get('output_tokens')}") st.markdown("**回复内容**") for content in row.get('content', []): if content['type'] == 'text': st.code(content['text'], language='python' if 'python' in content['text'].lower() else 'text') # 3. Token消耗折线图 st.header("📈 Token消耗趋势") success_df = df[df['type']=='response_success'].copy() if not success_df.empty: success_df['request_seq'] = range(1, len(success_df)+1) chart_data = success_df[['request_seq', 'usage']].copy() chart_data['input_tokens'] = chart_data['usage'].apply(lambda x: x.get('input_tokens')) chart_data['output_tokens'] = chart_data['usage'].apply(lambda x: x.get('output_tokens')) st.line_chart(chart_data.set_index('request_seq')[['input_tokens', 'output_tokens']])运行streamlit run trace_viewer.py，上传你的日志文件，你就能看到一个交互式的仪表盘，清晰地展示了整个对话流程、每轮的具体内容以及Token消耗的变化趋势。这比看纯文本日志要直观得多。
5.2 基于观测的Agent优化实践
观测的最终目的是优化。通过分析这次贪吃蛇任务的日志，我们可以得出一些优化Agent设计的经验：
- 提示词工程：我发现，在第一轮请求中，由于我的系统提示词较长，消耗了约500个输入Token。如果这是一个会被频繁调用的Agent，可以考虑精简系统提示词，或者将固定的上下文（如公司规范、代码风格）通过其他方式（如RAG检索）动态注入，以减少每次请求的固定开销。
- 分步vs整体：分步请求让过程更透明，也便于在中间步骤进行人工校正或干预。但代价是总输入Token数增加（因为要携带历史）。对于逻辑复杂、容错率低的任务（如部署脚本），分步更安全。对于简单、成熟的任务（如生成工具函数），一次性请求更经济。ccglass的数据可以帮助你做出量化决策。
- 错误处理与重试：在我们的记录器中，我们捕获了请求异常。在生产环境中，你需要根据不同的错误类型（如网络超时、速率限制、内容过滤）设计重试、回退或上报逻辑。观测到的错误日志是设计这些策略的基础。
- 成本监控与预警：通过实时分析
usage数据，可以设置成本预警。例如，如果单次对话的输入Token超过某个阈值，可能意味着上下文积累过多，需要触发摘要或清理操作。
5.3 将模式推广到复杂Agent系统
贪吃蛇游戏只是一个简单的起点。这种“请求捕获-分析-可视化”的模式，可以无缝推广到任何复杂的AI Agent系统中。
- 多工具编排：当一个Agent需要顺序或并行调用搜索工具、代码解释器、数据库查询等多个工具时，ccglass这样的观测平台能清晰地展示出整个编排流程，帮你发现瓶颈（比如某个工具调用特别慢）或逻辑错误（比如工具调用顺序不对）。
- 评估与测试：你可以录制Agent处理一系列标准测试用例的完整流程。通过对比不同提示词版本或模型版本下的工作流日志，可以定量评估哪个版本更高效、更准确、成本更低。
- 调试与溯源：当用户报告Agent输出了一个错误结果时，你可以通过
trace_id快速定位到当时的完整会话上下文、工具调用参数和结果，精准复现问题，而不是靠猜测。
让Claude写贪吃蛇游戏只是一个引子，真正有价值的是通过ccglass（或自制的记录器）打开的那个“观察窗”。它让你从被动的API调用者，变成了主动的AI工作流架构师和调试员。当你能够看清每一个请求、每一次思考、每一次工具调用的细节时，你构建和驾驭AI Agent的能力，才会发生质的飞跃。
