feat(trace): M40 span 写侧脱敏 + 共享上游错误收敛 helper
stderr 的 JSONL 是无主人在场的落盘面,却在此前原样落工具结果(result)、
子代理回复(text/summary)与上游报文,等于一次 tail 就能拷走整段对话。
本切片交付两件地基:
1) 写侧脱敏(trace.JSONRecorder)
- 新增 trace/span_props.go:safePropKeys 白名单与 projectSpanProps 投影,
读侧(safeSpanProps)与写侧共用同一张表、同一个投影函数;
- WriteSpan 落盘前经 trace.SanitizeRecord 投影:白名单键清洗,表外键只留
Digest(bytes/runes/sha256 前缀,收进 omitted),事件先 RedactEvent 再把
正文键折成 Digest。落到磁盘的只有元数据,正文一个字节都不留;
- 新增 trace/digest.go:Digest/DigestOf/DigestOfValue,给「脱敏后仍要能诊断」
一个构造上不含正文的取值形态(体积 + 指纹),两条投影都按类型放行它。
2) 共享上游错误体收敛 helper(给 M41/M42,禁止三家各写一份)
- trace.UpstreamError(upstream, status, contentType, body):只保留 status /
contentType / bodyLen / body sha256 前缀 / 上游 JSON 的 error.code /
error.type / 截断 128 rune 的 error.message,其余一律丢弃,响应体原文绝不
进 error 或日志;*UpstreamErrorInfo 提供 Error()/Attrs()/Unwrap()(errors.Is
可判 ErrUpstream 走降级链);
- trace.HostOf / trace.MaskQuery:日志里的 URL 只回来源,凭据类 query 与
fragment 值打码为 ***,user:pass@ 整段打码。
3) 剥掉三处正文上 span
- loop:tool span 不再放 result,改放 result_summary(与 tool_execution.end
帧同源、已脱敏截断)与 result_digest;
- orchestration:subagent span 不再放 text,subagent.done 事件不再放 summary,
改记 status/steps/chars/sha256;
- automations:AddRuleByName 不再 %v 整个 payload,改记 subject/type/bytes/sha256。
测试:以哨兵正文在落盘字节上断言(JSONL / slog 输出),并分别对「编排层收到的
原始 span」与「写侧投影」两层各钉一遍;UpstreamError 用回显 input 的 422 报文
与 HTML 错误页各钉一条;解析出/未解析出 JSON 都不回原文。以上均做过变异验证
(去掉保护即变红)。
验收:go build ./... + go vet ./... + go test -count=1 ./... 全绿;
trace/loop/orchestration 另跑 -race 全绿。
This commit is contained in:
1 parent
240b59708d
commit
003d12a712
18 files changed
+1612
-71
No files matched your search
@@ -0,0 +1,193 @@
|
||||
package loop
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/model"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
|
||||
)
|
||||
|
||||
// 本文件钉住 M40 的工具侧写盘边界,分两层各钉一遍:
|
||||
//
|
||||
// - **循环层**:真跑一次循环,按 writer 收到的**原始 SpanRecord**断言 —— tool
|
||||
// span 里根本没有 `result` 原文(曾经是原样落盘的工具结果全文,M38 排查出的
|
||||
// 最严重一条),只有 result_summary(已脱敏、已截断,供回看面读)与
|
||||
// result_digest(字节/rune/sha256 前缀);
|
||||
// - **写侧**:同一份记录的 stderr JSONL 字节里搜不到正文。
|
||||
//
|
||||
// 两层分开断言是刻意的:只测 JSONL 的话,写侧白名单会替循环层的漏做遮挡,把
|
||||
// 「span 里曾经存着正文」这件事测不出来(反过来也一样)。
|
||||
//
|
||||
// 口径:工具结果正文留在会话库,span 只留摘要与指纹 —— 于是「成功还是失败、
|
||||
// 输出多大、两次是不是同一份」仍可分辨,脱敏不该把 span 变得没用。
|
||||
|
||||
// captureWriter 收下每个 span 的**原始**记录(未经写侧投影),供测试按 span 层断言。
|
||||
type captureWriter struct {
|
||||
mu sync.Mutex
|
||||
recs []trace.SpanRecord
|
||||
}
|
||||
|
||||
// WriteSpan 记录一份 span。
|
||||
func (c *captureWriter) WriteSpan(rec trace.SpanRecord) error {
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
c.recs = append(c.recs, rec)
|
||||
return nil
|
||||
}
|
||||
|
||||
// snapshot 返回已收集记录的副本。
|
||||
func (c *captureWriter) snapshot() []trace.SpanRecord {
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
out := make([]trace.SpanRecord, len(c.recs))
|
||||
copy(out, c.recs)
|
||||
return out
|
||||
}
|
||||
|
||||
// teeWriter 把同一份 span 同时交给「原始记录捕获器」与 JSONL 记录器,使两层
|
||||
// 断言落在同一次运行上。
|
||||
type teeWriter []trace.Writer
|
||||
|
||||
// WriteSpan 依次写入每个出口,返回第一个错误。
|
||||
func (t teeWriter) WriteSpan(rec trace.SpanRecord) error {
|
||||
var firstErr error
|
||||
for _, w := range t {
|
||||
if err := w.WriteSpan(rec); err != nil && firstErr == nil {
|
||||
firstErr = err
|
||||
}
|
||||
}
|
||||
return firstErr
|
||||
}
|
||||
|
||||
// runToolTurnTraced 跑一个「一次工具调用 + 收尾」的回合,返回原始 span 记录与
|
||||
// stderr JSONL 的原始字节。
|
||||
func runToolTurnTraced(t *testing.T, toolResult any, toolErr error) ([]trace.SpanRecord, string) {
|
||||
t.Helper()
|
||||
call := `{"tool_calls":[{"name":"echo","args":{"q":"hi"}}]}`
|
||||
ad := &mockAdapter{chat: []mgResp{
|
||||
{resp: model.Response{Content: call}},
|
||||
{resp: model.Response{Content: "done"}},
|
||||
}}
|
||||
td := dispatcherWith(t, &mockTool{name: "echo", result: toolResult, err: toolErr})
|
||||
a := newTestAgent(t, ad, td)
|
||||
var buf bytes.Buffer
|
||||
capture := &captureWriter{}
|
||||
writer := teeWriter{capture, trace.NewJSONRecorder(&buf)}
|
||||
l := New(Options{Agent: a, Tracer: trace.New(writer), MaxRounds: 8})
|
||||
if _, err := l.Run(context.Background(), "sess", []model.Message{model.TextMessage(model.RoleUser, "go")}); err != nil {
|
||||
t.Fatalf("Run: %v", err)
|
||||
}
|
||||
return capture.snapshot(), buf.String()
|
||||
}
|
||||
|
||||
// TestRun_ToolResultNeverEntersSpan 是循环层的泄漏钉:工具结果里有一段哨兵正文,
|
||||
// span 的 props 与 stderr JSONL 里都搜不到它。
|
||||
//
|
||||
// 哨兵刻意放在**摘要窗口之外**:结果摘要(result_summary,回看面要读的那份)按
|
||||
// 设计就是结果的有界前缀(80 rune),它是摘要、不是正文 —— 本测试钉的是「整段
|
||||
// 结果不再落盘」,因此不能把断言的前提设成「连摘要都不许有」。
|
||||
func TestRun_ToolResultNeverEntersSpan(t *testing.T) {
|
||||
t.Parallel()
|
||||
const sentinel = "SENTINEL-TOOL-BODY-3b7d-工具结果的后半段"
|
||||
result := strings.Repeat("拿到的报表行:", 40) + sentinel
|
||||
recs, raw := runToolTurnTraced(t, result, nil)
|
||||
|
||||
span := toolSpanOf(t, recs)
|
||||
if _, ok := span.Props["result"]; ok {
|
||||
t.Fatalf("tool span 仍带着 result 原文:%+v", span.Props)
|
||||
}
|
||||
if _, ok := span.Props["text"]; ok {
|
||||
t.Fatalf("tool span 带着 text 原文:%+v", span.Props)
|
||||
}
|
||||
propsBlob := mustMarshal(t, span.Props)
|
||||
if strings.Contains(propsBlob, sentinel) {
|
||||
t.Fatalf("tool span 的 props 带着正文:%s", propsBlob)
|
||||
}
|
||||
digest, ok := span.Props["result_digest"].(trace.Digest)
|
||||
if !ok {
|
||||
t.Fatalf("tool span 没有 result_digest:%+v", span.Props)
|
||||
}
|
||||
if digest.Bytes != len(result) {
|
||||
t.Fatalf("result_digest.Bytes = %d, want %d(输出大小必须仍可读)", digest.Bytes, len(result))
|
||||
}
|
||||
summary, _ := span.Props["result_summary"].(string)
|
||||
if summary == "" {
|
||||
t.Fatalf("result_summary 缺席:回看面会失去结果摘要:%+v", span.Props)
|
||||
}
|
||||
if n := len([]rune(summary)); n > 81 {
|
||||
t.Fatalf("result_summary 长度 = %d rune,want 有界(摘要不是正文)", n)
|
||||
}
|
||||
|
||||
// 写侧:同一份记录落盘后仍搜不到正文,也不含任何结果原文的长尾。
|
||||
if strings.Contains(raw, sentinel) {
|
||||
t.Fatalf("工具结果正文落进了 JSONL:%s", raw)
|
||||
}
|
||||
if strings.Contains(raw, strings.Repeat("拿到的报表行:", 16)) {
|
||||
t.Fatalf("JSONL 里出现了超出一份摘要的结果原文:%s", raw)
|
||||
}
|
||||
}
|
||||
|
||||
// TestRun_ToolSpanStillTellsOKFromError 是「脱敏不能把 span 变得没用」的验收钉:
|
||||
// 成功与失败在落盘上仍可分辨 —— 终态不同、失败的带已脱敏的 error、输出体积可读。
|
||||
func TestRun_ToolSpanStillTellsOKFromError(t *testing.T) {
|
||||
t.Parallel()
|
||||
const secret = "abcdef1234567890"
|
||||
small := "ok"
|
||||
large := strings.Repeat("失", 500)
|
||||
|
||||
okRecs, okRaw := runToolTurnTraced(t, small, nil)
|
||||
badRecs, badRaw := runToolTurnTraced(t, nil, &toolFailErr{msg: "boom: token=" + secret + " " + large})
|
||||
okSpan, badSpan := toolSpanOf(t, okRecs), toolSpanOf(t, badRecs)
|
||||
|
||||
if okSpan.Status != trace.SpanStatusOK || badSpan.Status != trace.SpanStatusError {
|
||||
t.Fatalf("status = %q / %q,成功与失败必须仍可分辨", okSpan.Status, badSpan.Status)
|
||||
}
|
||||
okDigest, _ := okSpan.Props["result_digest"].(trace.Digest)
|
||||
if okDigest.Bytes != len(small) {
|
||||
t.Fatalf("成功调用的 result_digest.Bytes = %d, want %d", okDigest.Bytes, len(small))
|
||||
}
|
||||
// 失败侧写盘面:错误原因仍可读("boom"),凭据已打码,长度有界。
|
||||
for _, surface := range []string{okRaw, badRaw} {
|
||||
if strings.Contains(surface, secret) {
|
||||
t.Fatalf("JSONL 带着凭据原文:%s", surface)
|
||||
}
|
||||
}
|
||||
if !strings.Contains(badRaw, "boom") {
|
||||
t.Fatalf("失败落盘里没有可诊断的原因:%s", badRaw)
|
||||
}
|
||||
if strings.Contains(badRaw, large) {
|
||||
t.Fatalf("失败落盘里带着整段错误文本:%s", badRaw)
|
||||
}
|
||||
}
|
||||
|
||||
// toolFailErr 是一个只提供 Error() 的工具失败(模拟工具自己拼的错误文本)。
|
||||
type toolFailErr struct{ msg string }
|
||||
|
||||
func (e *toolFailErr) Error() string { return e.msg }
|
||||
|
||||
// toolSpanOf 在记录里取那条工具 span。
|
||||
func toolSpanOf(t *testing.T, recs []trace.SpanRecord) trace.SpanRecord {
|
||||
t.Helper()
|
||||
for _, rec := range recs {
|
||||
if rec.Name == "tool.echo" {
|
||||
return rec
|
||||
}
|
||||
}
|
||||
t.Fatalf("记录里没有 tool.echo span:%+v", recs)
|
||||
return trace.SpanRecord{}
|
||||
}
|
||||
|
||||
// mustMarshal 把一段东西序列化成 JSON 文本,用于「搜不到正文」的断言。
|
||||
func mustMarshal(t *testing.T, v any) string {
|
||||
t.Helper()
|
||||
b, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
return string(b)
|
||||
}
|
||||
@@ -126,6 +126,27 @@ func (l *Loop) recordToolDone(span *trace.Span, tc agent.ToolCall, out ToolOutco
|
||||
_ = span.Record(trace.Event{Type: EventToolDone, Props: props})
|
||||
}
|
||||
|
||||
// recordToolResult 把一次**成功**调用的结果落成两样东西,都不是正文:
|
||||
//
|
||||
// - result_summary:与 `tool_execution.end` 帧**逐字同源**的已脱敏、已截断
|
||||
// 摘要(toolFrameResultSummary,同一条 trace.RedactText 路径)—— 回看面
|
||||
// `toolCalls[].resultSummary` 读的就是它;
|
||||
// - result_digest:字节数 / rune 数 / 内容 sha256 前缀(trace.DigestOfValue)。
|
||||
//
|
||||
// 🔴 原文绝不进 span:工具结果正文本来就留在会话库里,span 与 stderr 的 JSONL
|
||||
// 都不需要它,而它们正是最容易扩散的两个落盘面(一次 stderr tail 就能把整段
|
||||
// 工具输出拷走)。排查「这次调用拿到了多大一份东西、两次是不是同一份」靠
|
||||
// Digest 就够了。
|
||||
func recordToolResult(span *trace.Span, result any) {
|
||||
if span == nil {
|
||||
return
|
||||
}
|
||||
if summary := toolFrameResultSummary(result); summary != "" {
|
||||
_ = span.SetProp("result_summary", summary)
|
||||
}
|
||||
_ = span.SetProp("result_digest", trace.DigestOfValue(result))
|
||||
}
|
||||
|
||||
// argSummary 生成工具参数的「值摘要」:只放行 argValueKeys 表内的键,且
|
||||
// 密钥类键一律不给值(trace.IsSecretKey 与出图清洗同一判据);非标量值只给
|
||||
// 占位(数组(N)/对象(N)),因为容器里可能藏着正文或凭据。键按字典序处理,
|
||||
|
||||
@@ -26,15 +26,15 @@ import (
|
||||
// toolFrameResultSummary 把工具返回值渲染成 loop 侧的结果摘要文本,口径与图上那份
|
||||
// `props.result_summary`(读回看面的数据源)**逐字一致**。
|
||||
//
|
||||
// 图侧的取值链是:tool span 的 `result` prop → `trace.safeSpanProps` →
|
||||
// `RedactText(summarize(result))`。`RedactText` 是导出 API(凭据形状清洗 + 截断,
|
||||
// 连同密钥键名防线都在 trace/redact.go),但 `summarize` 只服务出图、未导出,
|
||||
// 且 `internal/runtime/trace/**` 不在本切片文件面内 —— 因此这里按同一口径重述那一步
|
||||
// 渲染(nil ⇒ 空、字符串原样、其余 JSON 编码,编码失败才回落 %v)。
|
||||
// 图侧的取值链是:tool span 的 `result_summary` prop(由 spanlog.go 的
|
||||
// recordToolResult 用**本函数**写入)→ `trace.safeSpanProps` 的白名单投影 →
|
||||
// 节点 `props.result_summary`。因此两侧不再是「各自重述同一步渲染」,而是同一个
|
||||
// 生产函数:span 里不再存结果原文(那正是 M40 修掉的写侧泄漏),出图也不可能
|
||||
// 再从原文反推 —— 摘要只在这里生成一次。
|
||||
//
|
||||
// 🔴 两边必须逐字一致:由 `tool_frame_summary_test.go` 用**真建图器**
|
||||
// (`trace.RunGraph` + 真 span → 反读图上那份 `result_summary`)逐字比对来钉住 ——
|
||||
// 照字面量写断言会与实现一起漂移。若哪天 trace 导出了这一步渲染,这里应改为直接调用。
|
||||
// 照字面量写断言会与实现一起漂移。
|
||||
func toolFrameResultSummary(result any) string {
|
||||
return trace.RedactText(renderToolResultSummary(result))
|
||||
}
|
||||
|
||||
@@ -321,7 +321,7 @@ func (l *Loop) invokeOne(ctx context.Context, d *tool.Dispatcher, tc agent.ToolC
|
||||
l.spanProp(toolSpan, "error", err.Error())
|
||||
l.spanProp(toolSpan, "error_kind", out.ErrKind)
|
||||
} else {
|
||||
l.spanProp(toolSpan, "result", result)
|
||||
recordToolResult(toolSpan, result)
|
||||
}
|
||||
l.finishSpan(toolSpan, spanStatusForToolPhase(phase))
|
||||
return out
|
||||
|
||||
Reference in new issue
Block a user