把 proto、日志和请求参数拼成一段上下文，调试 gRPC 报错才不用来回翻三个地方
把 proto、日志和请求参数单独拎出来看，都只是半张拼图。真正定位 gRPC 报错，得把它们拼成一段能被模型和人都读懂的连续上下文。
为什么“来回翻三个地方”是 gRPC 调试最大的隐性成本
gRPC 的报错链路天然割裂。客户端拿到的错误通常只是一行 status code 加一条 message，比如 UNIMPLEMENTED: unknown service xxx 或者 DEADLINE_EXCEEDED。这一行东西本身不含 proto 定义、不含服务端日志、更不含请求参数。你第一反应是去翻 proto 看字段对不对，然后跳回日志看服务端有没有打出来，再去追请求参数到底传了什么。三次上下文切换，每次都在打断思路。
我遇到过一个真实案例：客户端报 INVALID_ARGUMENT: field "page_size" must be in range [1, 100]，但 proto 里 page_size 明明写的是 int32，请求里传的也是 20。单看这三个地方任何一个都看不出问题。最后拼起来才发现，服务端生成的校验代码里读的是 pageSize 这个 camelCase 的 JSON 字段名，而客户端用 page_size 序列化。proto 定义和请求参数单独看都没错，错在序列化命名约定和校验逻辑之间。这种错，只翻一个地方永远找不到。
上下文拼接的核心：让 proto、日志、参数在同一段文本里互相解释
拼上下文不是把三样东西堆在一起就完事。堆在一起只会得到一坨更长的文本，模型和人一样会看漏。有效拼接要做三件事：对齐、标注、压缩。
对齐：用请求 ID 把日志和参数锁死
gRPC 服务端日志和客户端参数之间，最常见的对齐键是 metadata 里的 x-request-id。如果你们还没加这个，先加上。没有请求 ID，服务端日志就是一堆无序事件，参数就是一堆孤立字段。
对齐之后的上下文大概是这样的结构：
[request_id] a1b2c3d4
[client_params] {"user_id": 123, "page_size": 20, "cursor": ""}
[server_log]
2025-01-15 10:32:11.421 INFO grpc.server.service.UserService/ListUsers request_id=a1b2c3d4
2025-01-15 10:32:11.489 WARN validation failed field=pageSize value=0
2025-01-15 10:32:11.490 ERROR grpc.server.interceptor.ValidationInterceptor INVALID_ARGUMENT
[proto]
message ListUsersRequest {
int32 page_size = 1; // @validate: range [1, 100]
string cursor = 2;
}
这段文本里，日志里的 field=pageSize value=0 和 proto 里的 page_size 以及请求参数里的 "page_size": 20 形成了三角对照。任何人或模型看到 value=0 而参数传的是 20，立刻会想到序列化命名问题。这就是对齐的价值——错误不再是孤立的，而是被两侧证据夹在中间。
标注：给每段内容标明来源和角色
不标注来源的拼接上下文，模型容易混淆“这是客户端说的还是服务端说的”。标注要简洁，不要写成大段元数据。推荐用行内注释或者前缀标记：
[proto]后面跟的是接口定义，不含运行时状态[client_params]后面跟的是客户端实际发送的序列化后参数[server_log]后面跟的是服务端处理过程中的关键事件
标注还有一个作用：当模型建议“检查 page_size 的序列化命名”时，你知道它指的是 proto 里的字段名和 client_params 里的 JSON key 之间的映射，而不是去改服务端日志配置。没有标注，模型可能会给出“在服务端加日志”这种正确但无用的建议。
压缩：日志只保留与请求相关的片段
服务端日志如果全量贴进去，一个高并发服务的单次请求日志可能混着几十个其他请求的 interleaved 输出。拼上下文之前，必须按 request_id 过滤，并且只保留关键事件：进入 handler、参数校验、下游调用、异常退出。Info 级别的“连接建立”“心跳检测”这些噪音全部去掉。
我一般的做法是：按 request_id grep 之后，只保留 WARN 和 ERROR 行，加上紧邻这些行的前后各 2 条 INFO。这样一段上下文通常控制在 300-500 行以内，模型能全量读进去，人也扫得完。
拼好的上下文喂给调试助手，要怎么写提示词
有了对齐、标注、压缩后的上下文，提示词本身不需要太花哨。关键是把“错误现象”和“上下文”分开，并明确要求模型给出证据链而不是直接给结论。
我常用的提示词模板：
下面是一个 gRPC 调用的完整上下文。错误发生在 [客户端/服务端/网关]，错误码和消息是：
[错误码] [错误消息]
上下文如下：
[proto 定义]
...（贴 proto 相关 message 和 service 定义，只贴相关方法）
[客户端参数]
...（贴序列化后的实际参数）
[服务端日志]
...（贴按 request_id 过滤后的关键日志）
请按以下步骤分析：
1. 先指出错误发生在调用链的哪个环节
2. 列出与错误直接相关的 proto 字段、请求参数值、日志行
3. 给出最可能的 2 个原因，按概率排序
4. 对每个原因，说明需要查看什么来确认或排除
这个模板的重点是第 2 步和第 4 步。强制模型先列证据，再给原因，最后给验证路径。这样得到的回答是可操作的，而不是“可能是序列化问题”这种空话。
实测下来，用这个模板分析上面那个 pageSize 的案例，GPT-4o 和 Claude 3.5 Sonnet 都能在第一次回答里指出“proto 字段是 snake_case，但服务端日志显示 field=pageSize，说明服务端校验代码里用了 camelCase，请求参数可能被错误映射或者校验代码字段名写死”。这个结论直接指向修复方向。
上下文拼得好不好，有一个硬指标：能否让另一个人 5 分钟内复现
拼上下文的最终检验标准不是“模型看懂了吗”，而是换一个不熟悉这个服务的人，拿着这段上下文，能不能在 5 分钟内复现错误并定位到根因。如果能，说明这段上下文是自洽的、完整的、信息密度足够的。
我经历过相反的情况：贴了 200 行日志、完整 proto 文件、客户端完整参数 JSON，但没做对齐和压缩。模型回答得像在猜，一会儿说超时问题，一会儿说参数问题。人看了也晕。问题就出在日志里混了多个请求，proto 贴了无关的 50 个 message，参数里有一堆和错误无关的字段。信息量大了，信噪比反而低了。
所以拼上下文的时候，脑子里要有一个假想的“接手人”。这个人什么都不知道，但很聪明。你给的东西要让他能沿着证据链走一遍，而不是靠猜。
常见问题
拼接上下文时 proto 要贴完整文件吗？
不要。只贴相关 method 的 request/response message 定义，以及这些 message 引用的嵌套 message。如果 message 里有 google.protobuf.Timestamp 这类标准类型，不用贴定义。完整 proto 文件会引入大量与当前错误无关的 service 和 message，稀释模型注意力。
服务端日志没有 request_id 怎么办？
先补上。如果暂时改不了代码，退而求其次用时间窗口 + 客户端 IP + method 名做近似对齐。但这种方式在高并发下会错位，拼出来的上下文可能把请求 A 的日志和请求 B 的参数配成一对，分析结果完全不可信。所以 request_id 是底线。
客户端参数应该贴序列化前的还是序列化后的？
贴序列化后的。因为错误往往发生在序列化之后、反序列化之后的某个环节。如果你贴的是序列化前的内存对象，模型看不到实际发送的字段名和值，也看不出字段缺失、命名转换、默认值被吞掉这些问题。如果序列化后的参数是二进制，转成 JSON 或文本格式再贴。