当 Workers 的问题只在本地请求中出现时，过去通常需要反复添加日志、重现请求，再人工拼出执行路径。现在，wrangler dev 会为每个本地请求生成结构化 trace，Coding Agent 可以通过单个 API 查询失败位置和原因，不必先部署到远端环境。
从“看日志”变成“查请求”
结构化 trace 的价值不只是输出更多日志，而是把一次请求整理成可以被工具消费的数据。Agent 可以围绕请求 ID 检查入口、绑定调用、异常信息和执行步骤，再把结果压缩成明确的诊断结论：哪个阶段失败、失败原因是什么、是否需要修改代码。
这对以下场景尤其有用：
- Worker 在本地能稳定复现，但普通日志难以区分多个异步步骤。
- 一个请求同时访问 KV、D1、R2 或其他绑定，需要确认到底是哪次调用失败。
- 希望让 Coding Agent 自己重现问题并给出补丁，而不是把整段终端日志复制给它。
- 需要在部署前验证错误处理、输入校验和边界条件。
本地 trace 还缩短了反馈周期。请求仍然在开发机上运行，诊断数据也从本地环境产生，因此调试不需要先发布一个临时版本。
一个适合 Agent 的调试闭环
可以把调试过程拆成四步：启动本地 Worker、发起一个可复现请求、通过单一 trace API 获取结构化结果、让 Agent 根据结果检查相关代码。
下面的命令展示了一个可改造的工作流。由于具体 trace API 的路径和响应字段取决于实际版本，示例中的 /__local_traces/<request-id> 是占位写法；接入时应替换成当前 wrangler dev 提供的实际接口。
# 终端 1：启动本地 Worker
npx wrangler dev
# 终端 2：发送一个可复现请求，并保留响应头中的请求标识
curl -i http://127.0.0.1:8787/api/orders/42
# 使用实际请求 ID 查询结构化 trace
curl -sS \
"http://127.0.0.1:8787/__local_traces/<request-id>" \
-H 'Accept: application/json' | jq .
一个 Agent 可以按类似下面的提示处理返回结果：
你正在调试本地 Cloudflare Worker。
请读取刚刚请求对应的结构化 trace，只依据 trace 中的错误阶段、异常信息和调用链分析失败原因。
输出：
1. 失败的步骤；
2. 最可能的根因；
3. 需要检查的文件和函数；
4. 最小代码修改建议；
5. 一个可以重新执行的验证请求。
不要把“请求失败”当作根因，也不要猜测 trace 中不存在的事实。
如果希望让 Agent 自动化，可以把 trace 查询封装成一个小脚本。下面是一个最小的 Python 示例，假设 trace 接口返回 JSON，并使用 request_id 作为路径参数：
#!/usr/bin/env python3
import json
import sys
from urllib.request import Request, urlopen
if len(sys.argv) != 2:
raise SystemExit("用法: python fetch_trace.py <request-id>")
request_id = sys.argv[1]
url = f"http://127.0.0.1:8787/__local_traces/{request_id}"
request = Request(url, headers={"Accept": "application/json"})
with urlopen(request, timeout=5) as response:
trace = json.load(response)
print(json.dumps(trace, ensure_ascii=False, indent=2))
这个脚本本身不负责解释 trace，它只负责提供稳定、机器可读的输入。实际集成时，可以把它注册为 Agent 工具，或者在 CI 风格的本地调试脚本中调用，再把 JSON 交给模型分析。
结构化 trace 应该怎样使用
不要让 Agent 只看到最后一行异常。更可靠的做法是保留完整请求上下文，同时限制诊断范围：
- 用请求 ID 绑定一次调试会话，避免多个并发请求的 trace 混在一起。
- 优先读取结构化字段，例如阶段名称、异常类型、消息和时间顺序。
- 将敏感请求头、用户数据和密钥从 Agent 输入中剔除。
- 要求 Agent 给出可重现命令，而不是只生成自然语言结论。
- 修改代码后重新发送同一请求，确认新的 trace 不再出现原错误。
trace 能告诉 Agent“哪里失败”和“执行时发生了什么”，但它不能替代业务判断。比如，数据库查询成功并不代表查询结果符合业务预期；一个请求返回 200，也不代表响应内容正确。因此，自动修复仍然需要测试、断言和人工审阅。
采用时的检查清单
引入本地 tracing 时，可以先从一个固定的失败用例开始：
- 在
wrangler dev中确认该请求可以稳定复现。 - 为每次请求保存唯一标识。
- 确认 Agent 获取的是结构化 trace，而不是未经筛选的全部终端输出。
- 为隐私字段设置脱敏规则。
- 让 Agent 先分析，再修改；修改后必须重新执行请求。
- 为关键路径补充单元测试或集成测试，防止修复只适用于当前输入。
本地 trace 的核心变化，是让 Workers 调试从“开发者阅读日志”变成“工具查询一次请求并解释执行过程”。对于已经使用 Coding Agent 的团队，这能减少日志搬运和环境切换；对于生产问题，仍应结合远端观测、访问控制和完整测试体系使用。