调用的可观测性 · 第 6 课 · MCP 与工具接入

1一条记录要回答五个问题

记录的价值不在「记了」，而在事后能不能回答。下面五个问题是一条调用记录的最低配置。

一条记录要回答五个问题：调了什么、成了没有、谁触发的、在哪次对话里、什么时候。

要回答的问题	记什么	为什么需要
调了什么	哪台服务器上的哪个工具	出问题时先要知道动作落在哪台外部服务上
成了没有	成功、被拒还是出错；成功记结果摘要，失败记原因	失败的调用必须显形，不能混在成功里
谁触发的	发起这次调用的用户	把动作归属到人，才谈得上追责与配额
在哪次对话里	哪次会话，以及这次提问里的第几轮	多轮调用要靠轮次排出先后顺序
什么时候	发生的时间	与其他日志对齐，还原当时的现场

调用记录与「会话消息」「智能体配置」不是同一类数据：它记录的是取用工具这一动作，而非回答的内容。三者可以互相回指，拼出一条完整的证据链——这也是记录中要带上会话与轮次的原因。

2进度如何先于正文送达

不必等回答写完才知道用了工具：调用事件先到，它已带上这一轮调了什么、成了没有。多轮调用时按发生顺序推多次。

event: meta
data: {"status":"ok","skill":{"name":"数学解题引导"},
"citations":[…],
"tool_calls":[{"ref":"formula_hint@campus-tools","status":"ok",
"text":"去括号时：括号前的系数要乘到括号内每一项……"}]}

event: delta
data: {"text":"先看这一步……"}

tool_calls 只在本次确有调用时出现；技能不带工具时这一项直接不出现，而不是给一个空数组——前端据此判断「要不要显示工具那一栏」。这与引用列表同一口径：有则带上，没有则省去。

为什么调用事件要先于正文：回答开始前就该把「出处」告诉页面，而这次调了哪些工具同样属于出处。反过来做，工具栏会迟一步才出现，用户多一次状态跳变。顺序由「哪些信息要在首字之前备齐」决定。

3可观测性的三个层次

日志回答「这一条怎么了」，指标回答「整体健康吗」，追踪回答「这次为什么慢、为什么错」。

日志（log，离散事件）

每一次调用一条，带上五个问题的答案。它是追溯的最小单位，也是审计的依据。

指标（metric，聚合量）

调用次数、成功率、耗时分布、失败原因分布。它回答的是趋势与容量问题：哪台服务器在退化、哪个工具总是失败、配额是否即将耗尽。

追踪（trace，一条链路）

一次提问里的多轮调用按先后串成一条链，可看清「先查了什么、再算了什么、在哪一轮卡住」。工具调用尤其需要它，因为一次回答背后可能是好几轮调用。

三者不是三选一：没有日志，追踪断了细节；没有指标，问题只能等用户来报；没有追踪，多轮调用的顺序与耗时无从还原。本课做到的是第一层，第二、三层属于第 8 课。

4本课要求：管理侧要看到什么

把上面三层落到界面上，本课需要四类能力。

能力	要看什么	为什么
登记与维护	服务器名称、地址、是否已配令牌	令牌原文不出现在任何返回里，只显示是否配过
连接与断开	当前是否连通、失败原因	这是「配置」与「运行」的分界
查看已发现的工具	这台服务器暴露了哪些工具、各需要什么参数	写引用时对照的就是这份清单
查看最近的调用记录	按时间倒序看发生过哪些调用、状态如何	判断「工具配得对不对、服务器稳不稳」的第一手依据

这些能力对非管理角色一律拒绝：按标识访问不存在或不属于自己的服务器，返回的响应与访问一个不存在的标识完全一致——判定在服务端完成，前端隐藏入口不构成保护。这是第 3 课确立的规矩（认证与授权分离、默认拒绝），本课没有例外。