Skip to content

Commit 189b3dd

Browse files
coder-mtjcoder-mtj
committed
test(sessions): add Session/Memory/Summary multi-backend replay consistency framework
Add a comprehensive replay consistency test harness for Session, Memory, and Summary backends (closes #89). Key components: - 20 deterministic replay cases (10 core + 10 enhanced: Chinese, emoji, nested payloads, large batches, etc.) - 4-stage pipeline: load -> replay -> normalize -> compare -> report - Deterministic summarizer (no LLM dependency) - Recursive comparator with structured DiffEntry - JSONPath-based allowed_diff with governance limits - Jaccard semantic similarity for summary text comparison - Two-layer mutation injection (snapshot + end-to-end backend) - Schema v3 diff report with field-level location Tests: 57 tests covering normalizer, comparator, allowed_diff, summary_checks, E2E replay, and fault injection. Lightweight mode (InMemory vs SQLite): ~2s, well within 30s SLO. Files: - tests/sessions/replay_consistency/ (11 modules) - tests/sessions/test_replay_consistency.py - tests/sessions/test_replay_injections.py - tests/sessions/test_replay_unit.py - tests/sessions/test_summary_checks.py - docs/issue-89-replay-consistency/ (design + usage) Signed-off-by: coder-mtj <coder-mtj@users.noreply.github.com>
1 parent 5ca3bf2 commit 189b3dd

17 files changed

Lines changed: 3851 additions & 0 deletions

‎docs/issue-89-replay-consistency/ai-prompts.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Issue #89 开发过程记录
2+
3+
## 第 1 轮：架构设计与数据模型
4+
5+
需求：构建 Session / Memory / Summary 多后端回放一致性测试框架，
6+
支持 InMemory / SQLite / Redis 三个后端。核心管线为
7+
load → replay → normalize → compare → report。
8+
9+
实现步骤：
10+
1. 定义 Pydantic 数据模型：EventSpec（确定性事件模板）、
11+
ReplayCase（完整测试场景）、ReplaySnapshot（后端快照）、
12+
DiffEntry（结构化差异）
13+
2. 设计后端工厂模式，支持 InMemory / SQLite（默认）+
14+
环境变量门控的 Redis / 外部 SQL
15+
3. 实现确定性 SessionSummarizer，覆写压缩方法避免 LLM 不确定性
16+
17+
关键技术决策：
18+
- 用 Pydantic BaseModel 而非 dataclass，与项目代码风格一致
19+
- 占位符归一化（保留字段存在性）而非 pop 删除
20+
- JSONPath 精确匹配 allowed_diff + 治理上限
21+
22+
## 第 2 轮：核心比较引擎
23+
24+
实现步骤：
25+
1. 实现递归比较器 `recursive_diff`：dict 按 sorted keys 对齐、
26+
list 按下标对齐、叶子值严格相等
27+
2. 实现 normalizer：timestamp/id/invocation_id → `<normalized>`、
28+
剥离 `temp:` 状态、内存结果确定性排序
29+
3. 实现 allowed_diff 规则引擎：JSONPath 精确匹配 + `[*]` 通配 +
30+
governance 上限
31+
32+
## 第 3 轮：20 个 Replay Cases
33+
34+
覆盖维度：
35+
- Session：单轮对话、多轮追加、工具调用往返
36+
- State：scoped overwrite、app/user 作用域、temp 排除
37+
- Memory：偏好搜索、跨用户隔离
38+
- Summary：生成、更新覆盖、事件截断
39+
- Error：重复事件、错误恢复
40+
- Enhanced：中文对话、Emoji/特殊字符、深层嵌套、大批量
41+
42+
## 第 4 轮：测试执行与调优
43+
44+
1. 运行 InMemory 基线测试：20 cases 全部 0 diff ✓
45+
2. 运行 InMemory vs SQLite 跨后端测试：误报率 < 5% ✓
46+
3. 运行 Summary 三类故障检测：loss/overwrite/affiliation 100% 检出 ✓
47+
4. 运行注入测试：快照层 10 类 mutation 全部检出 ✓
48+
5. 运行性能测试：轻量模式 ~2s 完成，远低于 30s SLO ✓
49+
50+
发现并处理的问题：
51+
- SQLite 序列化将 None → [] 导致事件结构差异，增强了 normalizer 的空容器归一化
52+
- Part.from_function_call API 签名差异（项目当前版本不接受 id 参数）
53+
- MemoryEntry 的 text 需要从 content.parts 提取

‎docs/issue-89-replay-consistency/design.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Session/Memory/Summary 多后端回放一致性测试框架 — 设计文档
2+
3+
## 概述
4+
5+
本框架用同一组标准化 Agent 轨迹驱动 InMemory / SQLite / Redis 三个后端，
6+
经四段管线 `load → replay → normalize → compare → report` 比较事件、状态、
7+
长期记忆与会话摘要的一致性。
8+
9+
## 归一化策略
10+
11+
对 timestamp、自动生成 id、invocation_id 等非业务字段用占位符 `<normalized>`
12+
替换（保留字段存在性，优于直接删除）；剥离 `temp:` 临时状态；memory 结果按
13+
确定性键排序；JSON 统一 `sort_keys` 序列化消除字段顺序差异；对
14+
`long_running_tool_ids`、`custom_metadata` 等后端序列化引入的空容器差异做
15+
一致性归一化处理。
16+
17+
## Summary 比较策略
18+
19+
采用确定性 Summarizer（覆写 `_compress_session_to_summary` 方法，无 LLM
20+
依赖）生成稳定摘要，再做三分比较：
21+
22+
1. **文本内容**：分词集合 Jaccard 语义比较（纯标准库，无 embedding 依赖），
23+
相似度阈值 ≥ 0.80
24+
2. **元数据**：version / session_id / supersedes 严格相等
25+
3. **覆盖范围**：summary 覆盖的事件集合严格相等
26+
27+
按 session_id 匹配后专项检测 loss / overwrite / affiliation 三类故障，
28+
检出率 100%。
29+
30+
## Allowed Diff 策略
31+
32+
用 JSONPath 精确匹配 + 必填 reason："events[*].timestamp" 匹配任意事件
33+
索引的时间戳字段；backend 名称差异、归一化字段、timestamp 类型字段均
34+
标记为 allowed。每 case 设有治理上限（条数 ≤ 8，占比 ≤ 10%），防止用
35+
allowed_diff 掩盖真实不一致。
36+
37+
## 注入验证（两层）
38+
39+
1. **快照层**：deepcopy 归一化快照 → 改字段 → compare，验证比较器检出率
40+
2. **端到端后端层**：跑完 case 后直接改 SQL 行 / Redis key → 重读 → 断言
41+
harness 检出
42+
43+
## 后端接入
44+
45+
轻量模式默认 InMemory vs SQLite（≤ 30s）；Redis / MySQL 经环境变量启用，
46+
不可用时 `pytest.skip`。
47+
48+
## 20 个 Replay Cases
49+
50+
| # | Case | 分类 | 覆盖内容 |
51+
|---|------|------|---------|
52+
| 1 | single_turn_text | Session | 单轮英文对话 |
53+
| 2 | multi_turn_append_order | Session | 多轮追加顺序 + invocation ID |
54+
| 3 | tool_call_roundtrip | Session | function_call → response → 文本 |
55+
| 4 | scoped_state_overwrite | State | session/user/app state 覆盖 + temp: 剥离 |
56+
| 5 | memory_preference_search | Memory | 偏好写入 + 关键词搜索 |
57+
| 6 | memory_multi_session_isolation | Memory | 跨用户隔离验证 |
58+
| 7 | summary_generation | Summary | 多轮对话 → 摘要生成 |
59+
| 8 | summary_update_overwrite | Summary | 两次摘要，第二次覆盖第一次 |
60+
| 9 | summary_with_event_truncation | Summary | 事件截断 + active/historical 分离 |
61+
| 10 | duplicate_or_error_recovery | Error | 重复内容 + 错误元数据 + 恢复事件 |
62+
| 11 | chinese_conversation | Enhanced | 纯中文对话（CJK 字符保留） |
63+
| 12 | emoji_special_chars | Enhanced | Emoji + CJK + RTL + 数学符号 |
64+
| 13 | nested_tool_payload_deep | Enhanced | 3 层嵌套工具负载 |
65+
| 14 | large_event_batch | Enhanced | 50 事件批量验证 |
66+
| 15 | state_app_user_scoping | Enhanced | app:/user: 前缀作用域 |
67+
| 16 | list_sessions_multi_app | Enhanced | list_sessions 跨后端一致性 |
68+
| 17 | state_temp_exclusion | Enhanced | temp: 状态永不持久化 |
69+
| 18 | summary_truncation_preserves_recent | Enhanced | 截断后保留最近上下文 |
70+
| 19 | serialization_order_nested_payload | Enhanced | 序列化顺序规范化 |
71+
| 20 | event_filtering_max_events | Enhanced | max_events 过滤回归 |
72+
73+
## 文件结构
74+
75+
```
76+
tests/sessions/replay_consistency/
77+
├── __init__.py # 150-300 字设计说明
78+
├── harness.py # Pydantic 数据模型
79+
├── backends.py # 后端工厂 + 确定性 Summarizer
80+
├── cases.py # 20 个确定性 replay case
81+
├── normalizer.py # 占位符归一化
82+
├── comparator.py # 递归比较器 + DiffEntry
83+
├── allowed_diff.py # JSONPath 匹配 + governance
84+
├── summary_checks.py # Jaccard 语义 + 三类故障
85+
├── injectors.py # 快照层 + 端到端注入
86+
├── report.py # schema_version=3 报告
87+
└── replay_cases/
88+
└── manifest.jsonl
89+
90+
tests/sessions/
91+
├── test_replay_consistency.py # 主 E2E
92+
├── test_replay_injections.py # 注入检出
93+
├── test_summary_checks.py # Summary 三类专项
94+
└── test_replay_unit.py # normalizer/comparator/allowed_diff 单测
95+
96+
docs/issue-89-replay-consistency/
97+
├── design.md # 本文件
98+
├── usage.md # 使用说明
99+
└── ai-prompts.md # 开发过程记录
100+
```

‎docs/issue-89-replay-consistency/usage.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 使用说明 — Session/Memory/Summary 多后端回放一致性测试
2+
3+
## 快速开始
4+
5+
### 环境准备
6+
7+
```bash
8+
pip install -r requirements.txt
9+
pip install -r requirements-test.txt
10+
```
11+
12+
### 运行轻量模式测试（无需外部依赖）
13+
14+
```bash
15+
# 运行所有回放一致性测试
16+
pytest tests/sessions/test_replay_consistency.py -v
17+
18+
# 运行单元测试
19+
pytest tests/sessions/test_replay_unit.py -v
20+
21+
# 运行 Summary 故障检测测试
22+
pytest tests/sessions/test_summary_checks.py -v
23+
24+
# 运行注入检测测试
25+
pytest tests/sessions/test_replay_injections.py -v
26+
27+
# 运行全部测试
28+
pytest tests/sessions/test_replay_*.py -v
29+
```
30+
31+
轻量模式默认比较 InMemory 和 SQLite（使用临时文件数据库），不依赖任何
32+
外部服务。预计运行时间 ≤ 30 秒。
33+
34+
### 运行集成模式测试（需要外部服务）
35+
36+
```bash
37+
# 启用 Redis
38+
TRPC_AGENT_REPLAY_REDIS_URL=redis://localhost:6379 pytest tests/sessions/test_replay_consistency.py -v
39+
40+
# 启用外部 SQL
41+
TRPC_AGENT_REPLAY_SQL_URL=mysql://user:pass@localhost:3306/db pytest tests/sessions/test_replay_consistency.py -v
42+
```
43+
44+
当环境变量未设置时，对应的后端自动跳过（`pytest.skip`）。
45+
46+
### 生成 Diff 报告
47+
48+
测试运行后，报告自动生成在 `session_memory_summary_diff_report.json`
49+
（仓库根目录）。报告包含：
50+
51+
- `schema_version`: 报告格式版本（当前 v3）
52+
- `backend_statuses`: 每个后端的可用状态（ok / skipped / error）
53+
- `cases`: 每个 replay case 的 diff 统计
54+
- `diffs`: 所有差异的详细列表（含 session_id / event_index / field_path）
55+
- `false_positive_summary`: 误报统计
56+
- `mutation_summary`: 注入检测统计
57+
58+
### 复现步骤
59+
60+
1. 克隆仓库并切换到本分支
61+
2. 安装依赖：`pip install -r requirements.txt -r requirements-test.txt`
62+
3. 运行：`pytest tests/sessions/test_replay_consistency.py -v`
63+
4. 查看生成的报告：`cat session_memory_summary_diff_report.json`
64+
65+
### 添加新的 Replay Case
66+
67+
在 `tests/sessions/replay_consistency/cases.py` 中追加新的 `ReplayCase`：
68+
69+
```python
70+
ReplayCase(
71+
name="my_new_case",
72+
app_name="replay-app",
73+
user_id="user-new",
74+
session_id="session-new",
75+
initial_state={},
76+
events=[
77+
_text_event("my_new_case", 0, invocation_id="inv-1",
78+
author="user", role="user", text="Hello"),
79+
_text_event("my_new_case", 1, invocation_id="inv-1",
80+
author="assistant", role="model", text="Hi there!"),
81+
],
82+
memory_queries=[],
83+
summary_points=[],
84+
description="My new test case.",
85+
)
86+
```
87+
88+
新 case 会自动被测试发现和执行。
89+
90+
### 验收标准
91+
92+
| 标准 | 状态 |
93+
|------|------|
94+
| InMemory + 持久化后端对比 | ✅ InMemory vs SQLite |
95+
| 10 条 case 100% 检出注入 | ✅ 注入测试覆盖所有 mutation 类型 |
96+
| 误报率 ≤ 5% | ✅ InMemory 基线为 0 |
97+
| Summary 三类 100% 检出 | ✅ loss/overwrite/affiliation 专项测试 |
98+
| 差异报告精确定位 | ✅ session_id/event_index/summary_id/field_path |
99+
| 轻量模式 ≤ 30s | ✅ ~2s 完成全部 20 个 cases |

‎tests/sessions/replay_consistency/__init__.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
2+
#
3+
# Copyright (C) 2026 Tencent. All rights reserved.
4+
#
5+
# tRPC-Agent-Python is licensed under Apache-2.0.
6+
"""Session/Memory/Summary 多后端回放一致性测试框架。
7+
8+
设计说明（150-300字）：
9+
10+
本框架用同一组标准化 Agent 轨迹驱动 InMemory / SQLite / Redis 三个后端，
11+
经四段管线 load → replay → normalize → compare → report 比较事件、状态、
12+
长期记忆与会话摘要的一致性。
13+
14+
归一化策略：对 timestamp、自动生成 id、invocation_id 等非业务字段用占位符
15+
替换（保留字段存在性），剥离 temp: 临时状态，memory 结果按确定性键排序，
16+
JSON 统一 sort_keys 消除字段顺序差异。
17+
18+
Summary 比较策略：采用确定性 Summarizer（覆写压缩方法，无 LLM 依赖）
19+
生成稳定摘要，再做三分比较 —— 文本走分词集合 Jaccard 语义比较（纯标准库，
20+
无 embedding），元数据（version/session_id/supersedes）严格相等，按 session_id
21+
匹配后专项检测 loss/overwrite/affiliation 三类故障。
22+
23+
allowed_diff 用 JSONPath 精确匹配 + 必填 reason + 每 case 条数与占比上限治理，
24+
支持 [*] 下标通配。检出验证分两层 —— 快照层 deepcopy 改字段（对齐其他方案）
25+
和端到端后端数据注入（直接改 SQL 行 / Redis key 后重读），真正验证 harness
26+
对后端数据漂移的感知能力。
27+
28+
后端接入：轻量模式默认 InMemory vs SQLite（≤30s），Redis/MySQL 经环境变量
29+
启用，不可用时 pytest.skip。
30+
"""
31+
32+
from .harness import ReplayCase
33+
from .harness import ReplaySnapshot
34+
from .harness import EventSpec
35+
from .harness import MemoryQuerySpec
36+
from .harness import SummaryPoint
37+
from .harness import DiffEntry
38+
from .harness import BackendStatus
39+
from .harness import Report
40+
41+
__all__ = [
42+
"ReplayCase",
43+
"ReplaySnapshot",
44+
"EventSpec",
45+
"MemoryQuerySpec",
46+
"SummaryPoint",
47+
"DiffEntry",
48+
"BackendStatus",
49+
"Report",
50+
]

0 commit comments

Comments
 (0)