From f76501af3bcef32525ec76abe36de60be2a83e2c Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 18 Apr 2026 22:42:01 +0800 Subject: [PATCH 1/2] chore: remove .agents/superpowers/ and .gitignore from repository Stop tracking these files in git while keeping them locally. These are tool-specific/local configuration files that should not be version controlled. Refs #47 --- .../2026-04-04-pt-snap-analyzer-design.md | 648 ------- .../2026-04-04-pt-snap-analyzer-analyzers.md | 1556 ----------------- .../2026-04-04-pt-snap-analyzer-foundation.md | 1020 ----------- .../2026-04-04-pt-snap-analyzer-query.md | 1188 ------------- .../plans/2026-04-04-pt-snap-analyzer-rag.md | 1391 --------------- .agents/superpowers/plans/README.md | 198 --- .../prds/2026-04-04-pt-snap-analyzer-prd.md | 780 --------- .../specs/.templates/checklist-template.md | 85 - .../specs/.templates/spec-template.md | 105 -- .../specs/.templates/tasks-template.md | 26 - .../superpowers/specs/analyzers/checklist.md | 65 - .agents/superpowers/specs/analyzers/spec.md | 344 ---- .agents/superpowers/specs/analyzers/tasks.md | 47 - .../superpowers/specs/foundation/checklist.md | 69 - .agents/superpowers/specs/foundation/spec.md | 344 ---- .agents/superpowers/specs/foundation/tasks.md | 54 - .agents/superpowers/specs/query/checklist.md | 69 - .agents/superpowers/specs/query/spec.md | 344 ---- .agents/superpowers/specs/query/tasks.md | 51 - .agents/superpowers/specs/rag/checklist.md | 72 - .agents/superpowers/specs/rag/spec.md | 471 ----- .agents/superpowers/specs/rag/tasks.md | 53 - .agents/superpowers/specs/tests/checklist.md | 91 - .agents/superpowers/specs/tests/tasks.md | 43 - .../specs/tests/test-coverage-improvement.md | 171 -- .gitignore | 91 - 26 files changed, 9376 deletions(-) delete mode 100644 .agents/superpowers/brainstorm/2026-04-04-pt-snap-analyzer-design.md delete mode 100644 .agents/superpowers/plans/2026-04-04-pt-snap-analyzer-analyzers.md delete mode 100644 .agents/superpowers/plans/2026-04-04-pt-snap-analyzer-foundation.md delete mode 100644 .agents/superpowers/plans/2026-04-04-pt-snap-analyzer-query.md delete mode 100644 .agents/superpowers/plans/2026-04-04-pt-snap-analyzer-rag.md delete mode 100644 .agents/superpowers/plans/README.md delete mode 100644 .agents/superpowers/prds/2026-04-04-pt-snap-analyzer-prd.md delete mode 100644 .agents/superpowers/specs/.templates/checklist-template.md delete mode 100644 .agents/superpowers/specs/.templates/spec-template.md delete mode 100644 .agents/superpowers/specs/.templates/tasks-template.md delete mode 100644 .agents/superpowers/specs/analyzers/checklist.md delete mode 100644 .agents/superpowers/specs/analyzers/spec.md delete mode 100644 .agents/superpowers/specs/analyzers/tasks.md delete mode 100644 .agents/superpowers/specs/foundation/checklist.md delete mode 100644 .agents/superpowers/specs/foundation/spec.md delete mode 100644 .agents/superpowers/specs/foundation/tasks.md delete mode 100644 .agents/superpowers/specs/query/checklist.md delete mode 100644 .agents/superpowers/specs/query/spec.md delete mode 100644 .agents/superpowers/specs/query/tasks.md delete mode 100644 .agents/superpowers/specs/rag/checklist.md delete mode 100644 .agents/superpowers/specs/rag/spec.md delete mode 100644 .agents/superpowers/specs/rag/tasks.md delete mode 100644 .agents/superpowers/specs/tests/checklist.md delete mode 100644 .agents/superpowers/specs/tests/tasks.md delete mode 100644 .agents/superpowers/specs/tests/test-coverage-improvement.md delete mode 100644 .gitignore diff --git a/.agents/superpowers/brainstorm/2026-04-04-pt-snap-analyzer-design.md b/.agents/superpowers/brainstorm/2026-04-04-pt-snap-analyzer-design.md deleted file mode 100644 index b995a0a..0000000 --- a/.agents/superpowers/brainstorm/2026-04-04-pt-snap-analyzer-design.md +++ /dev/null @@ -1,648 +0,0 @@ -# PyTorch 内存快照分析器 - 设计文档 - -**创建日期**: 2026-04-04 -**状态**: 已批准 -**版本**: 1.0 - ---- - -## 一、项目概述 - -### 1.1 项目定位 - -**项目名称**: `pt-snap-analyzer` (PyTorch Snapshot Analyzer) - -**核心价值**: -- 🔧 **独立 CLI 工具**: 可直接使用命令分析内存快照 -- 🤖 **AI 友好**: 提供 SDK + JSON 输出,AI Agent 可轻松调用 -- 📚 **RAG 知识库**: 将先验经验文档化,AI 可检索相似案例 -- 📊 **SQLite 驱动**: 所有分析基于 SQL 查询,高效处理大数据量 - -### 1.2 使用场景 - -1. **内存泄漏检测**: 定位训练/推理过程中的内存泄漏问题 -2. **峰值分析**: 识别内存峰值和异常分配 -3. **内存效率分析**: 分析内存碎片化、分配效率问题 -4. **对比分析**: 对比不同迭代/不同配置的内存使用差异 -5. **算子/层分析**: 分析算子/层的内存分配模式 - -### 1.3 目标用户 - -- **AI Agent** (主要用户): 通过 CLI JSON 输出或 Python SDK 调用分析功能 -- **开发者**: 通过 CLI 工具查看分析结果,或通过 SDK 集成到自动化工作流 - ---- - -## 二、系统架构 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 用户交互层 │ -├─────────────────────────────────────────────────────────────┤ -│ ┌─────────────────────────────────────────────────────┐ │ -│ │ 调用接口(AI Agent 和开发者共用) │ │ -│ │ ┌─────────────────┐ ┌───────────────┐ │ │ -│ │ │ CLI 命令 │ │ Python SDK │ │ │ -│ │ │ pt-snap xxx │ │ import ... │ │ │ -│ │ │ (JSON 输出) │ │ API 调用 │ │ │ -│ │ └─────────────────┘ └───────────────┘ │ │ -│ └─────────────────────────────────────────────────────┘ │ -│ │ -│ 使用方式: │ -│ - 开发者:直接使用 CLI 命令 或通过 SDK 集成到工作流 │ -│ - AI Agent:调用 CLI 命令(解析 JSON)或 直接调用 SDK API │ -└───────────────────────────┬──────────────────────────────────┘ - │ -┌───────────────────────────▼─────────────────────────────────┐ -│ Python SDK/API │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ -│ │ Query API │ │ Analysis API │ │ RAG Management │ │ -│ │ • execute() │ │ • leak() │ │ • add_case() │ │ -│ │ • load_cfg() │ │ • peak() │ │ • search() │ │ -│ │ • save_cfg() │ │ • compare() │ │ • list_cases() │ │ -│ └──────────────┘ └──────────────┘ └──────────────────┘ │ -└─────────────────────────────┬────────────────────────────────┘ - │ -┌─────────────────────────────▼────────────────────────────────┐ -│ 数据访问层 │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ -│ │ SQLite DB │ │ Query Config │ │ SQL Templates │ │ -│ │ (内存快照) │ │ (YAML/JSON) │ │ (可复用查询) │ │ -│ └──────────────┘ └──────────────┘ └──────────────────┘ │ -└──────────────────────────────────────────────────────────────┘ - │ -┌─────────────────────────────▼────────────────────────────────┐ -│ 知识库层 │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ -│ │ Vector DB │ │ Case Archive │ │ Learning Log │ │ -│ │ (Chroma) │ │ (JSON files) │ │ (分析历史) │ │ -│ └──────────────┘ └──────────────┘ └──────────────────┘ │ -└──────────────────────────────────────────────────────────────┘ -``` - -**架构说明**: -- **用户交互层**: 提供 CLI 和 SDK 两种调用接口,AI Agent 和开发者可以**共同使用** - - CLI: 命令行工具,输出结构化 JSON,适合 AI Agent 解析和开发者快速查看 - - SDK: Python API,适合集成到自动化工作流和 AI Agent 直接调用 -- **SDK/API 层**: 核心业务逻辑封装,提供查询、分析、RAG 管理接口 -- **数据访问层**: SQLite 数据库、查询配置、SQL 模板 -- **知识库层**: 向量数据库、案例归档、学习日志(阶段 3 实现) - -**AI 友好设计**: -- CLI 命令默认输出 JSON,AI 可解析 -- SDK 提供类型安全的 API,AI 可生成调用代码 -- 两种接口功能对等,AI 可根据场景选择 - ---- - -## 三、数据模型 - -### 3.1 DB Schema 概览 - -基于现有的 SnapshotDB schema: - -**核心表**: -- `trace_entry_{device}`: 内存事件追踪表 -- `block_{device}`: 内存块状态表 -- `dictionary`: 枚举值映射表 - -**命名规则**: 多设备场景下,表名后缀为设备 ID - -### 3.2 关键约束 - -#### 3.2.1 trace_entry.id 约束 -- **`id >= 0`**: 快照采集后发生的事件,按时间顺序递增且唯一 -- **`id < 0`**: 虚拟事件(从原始 pickle 数据生成),用于还原快照采集时刻的 Segment 状态 - - 事件类型只能是 `segment_map` 或 `segment_alloc` - -#### 3.2.2 block.id 约束 -- **`id >= 0`**: 与 `allocEventId` 一致,指向 trace_entry 中的分配事件 -- **`id < 0`**: 快照采集前就已分配的内存块,无法追溯到分配时间点 - -#### 3.2.3 block.state 约束 -- 仅在 `block.id < 0` 时有意义(历史遗留块) -- `id >= 0` 时,state 无实际意义 - -#### 3.2.4 requestedSize vs size -- `requestedSize`: 用户请求的大小 -- `size`: 实际分配大小(含对齐开销) -- 公式:`size = math.ceil((requestedSize + 32) / 512) * 512` - -### 3.3 Python 数据模型 - -```python -class EventType(IntEnum): - SEGMENT_MAP = 0 - SEGMENT_UNMAP = 1 - SEGMENT_ALLOC = 2 - SEGMENT_FREE = 3 - ALLOC = 4 - FREE_REQUESTED = 5 - FREE_COMPLETED = 6 - WORKSPACE_SNAPSHOT = 7 - -@dataclass -class MemoryEvent: - """内存事件记录""" - id: int - action: EventType - address: int - size: int - stream: int - allocated: int - active: int - reserved: int - callstack: Optional[str] - - @property - def is_virtual_event(self) -> bool: - return self.id < 0 - - @property - def is_runtime_event(self) -> bool: - return self.id >= 0 - -@dataclass -class MemoryBlock: - """内存块记录""" - id: int - address: int - size: int - requestedSize: int - state: int - allocEventId: Optional[int] - freeEventId: Optional[int] - - @property - def is_historical_block(self) -> bool: - return self.id < 0 - - @property - def is_active(self) -> bool: - if self.is_historical_block: - return self.state == 1 - return self.freeEventId is None or self.freeEventId == -1 -``` - ---- - -## 四、核心功能设计 - -### 4.1 CLI 工具 - -#### 4.1.1 上下文管理 - -```bash -# 设置当前使用的数据库 -$ pt-snap use - -# 配置设备 -$ pt-snap config devices # 如:0,1 或 all - -# 查看当前配置 -$ pt-snap config show -``` - -#### 4.1.2 分析命令 - -```bash -# 内存泄漏检测 -$ pt-snap analyze leak --json - -# 峰值分析 -$ pt-snap analyze peak --json - -# 内存趋势分析 -$ pt-snap analyze trend --plot - -# 调用栈分析 -$ pt-snap analyze stack --top-k 10 - -# 对比分析 -$ pt-snap compare --metric memory -``` - -#### 4.1.3 查询命令 - -```bash -# 列出所有预定义查询 -$ pt-snap query list - -# 执行预定义查询 -$ pt-snap query exec --format table - -# 执行自定义 SQL -$ pt-snap query custom "SELECT ..." --json -``` - -#### 4.1.4 RAG 命令 - -```bash -# 添加案例到知识库 -$ pt-snap rag add \ - --case \ - --db \ - --analysis-result \ - --conclusion "..." \ - --tags "tag1,tag2" - -# 检索案例 -$ pt-snap rag search "query text" --top-k 3 - -# 列出案例 -$ pt-snap rag list --tags memory-leak - -# 更新/删除案例 -$ pt-snap rag update --conclusion "..." -$ pt-snap rag remove -``` - -### 4.2 Python SDK - -```python -from pt_snap_analyzer import Context, Analyzer, RAGSearcher - -# 创建上下文 -ctx = Context( - db_path="snapshot.pkl.db", - devices=[0, 1] -) - -# 分析器使用 -analyzer = Analyzer(ctx) - -# 内存泄漏检测 -leaks = analyzer.detect_leaks() - -# 内存趋势分析 -trend = analyzer.analyze_trend(metrics=["allocated", "active"]) - -# 调用栈分析 -stack = analyzer.analyze_stack_trace(top_k=10) - -# RAG 检索 -rag = RAGSearcher("knowledge_base/") -cases = rag.search("memory leak in attention layer") - -# 添加案例 -rag.add_case( - case_id="memory_leak_demo", - db_path="snapshot.db", - analysis_result=leaks, - conclusion="Attention 层的 key/value cache 未正确释放", - tags=["memory-leak", "transformer"] -) -``` - -### 4.3 预定义查询模板 - -#### 4.3.1 内存泄漏检测 (leak_detection_v2) - -```sql --- 历史遗留块泄漏 -SELECT - b.id as block_id, - b.address, - b.size as actual_size, - b.requestedSize as requested_size, - (b.size - b.requestedSize) as alignment_overhead, - 'historical' as leak_type -FROM block_{device} b -WHERE b.id < 0 AND b.state = 1 -ORDER BY b.size DESC; - --- 运行时分配未释放 -SELECT - b.id as block_id, - b.address, - b.size as actual_size, - b.requestedSize as requested_size, - b.allocEventId, - t.callstack, - 'current' as leak_type -FROM block_{device} b -LEFT JOIN trace_entry_{device} t ON b.allocEventId = t.id -WHERE b.id >= 0 - AND b.allocEventId IS NOT NULL - AND (b.freeEventId IS NULL OR b.freeEventId = -1) - AND NOT EXISTS ( - SELECT 1 FROM trace_entry_{device} - WHERE id = b.freeEventId AND action = 6 - ) -ORDER BY b.size DESC; -``` - -#### 4.3.2 内存趋势分析 (memory_timeline_v2) - -```sql -SELECT - (id / :bucket_size) as bucket, - MIN(id) as start_id, - MAX(id) as end_id, - COUNT(*) as event_count, - AVG(allocated) as avg_allocated, - MAX(allocated) as peak_allocated, - MIN(allocated) as min_allocated, - AVG(active) as avg_active, - MAX(active) as peak_active, - AVG(reserved) as avg_reserved, - MAX(reserved) as peak_reserved -FROM trace_entry_{device} -WHERE id >= 0 -- 仅真实事件 -GROUP BY bucket -ORDER BY bucket ASC; -``` - -#### 4.3.3 调用栈分析 (callstack_analysis_v2) - -```sql -SELECT - COALESCE(callstack, '') as callstack, - COUNT(*) as alloc_count, - SUM(size) as total_bytes, - AVG(size) as avg_bytes, - MAX(size) as max_single_alloc, - CASE - WHEN MIN(id) < 0 THEN 'includes_snapshot_initial' - ELSE 'runtime_only' - END as phase -FROM trace_entry_{device} -WHERE action = 4 -- alloc -GROUP BY callstack -ORDER BY total_bytes DESC -LIMIT :top_k; -``` - ---- - -## 五、快速迭代机制 - -### 5.1 插件式分析模块 - -```python -# analyzers/__init__.py -from .leak_detector import LeakDetector -from .peak_analyzer import PeakAnalyzer -from .stack_analyzer import StackAnalyzer -from .trend_analyzer import TrendAnalyzer - -__all__ = [ - "LeakDetector", - "PeakAnalyzer", - "StackAnalyzer", - "TrendAnalyzer", -] - -# analyzers/base.py -class AnalyzerBase(ABC): - """分析器基类""" - - name: str - description: str - - def __init__(self, context: Context): - self.context = context - - @abstractmethod - def analyze(self, **kwargs) -> AnalysisResult: - pass -``` - -### 5.2 配置化查询 - -查询配置文件格式 (YAML): - -```yaml -name: query_name -description: 查询描述 -devices: all # 或 [0, 1] -parameters: - param_name: - default: value - type: int|string|float - description: 参数描述 -query: | - SELECT ... -output_schema: - - column_name: type -``` - -**新增/更新查询配置的方式**: -- AI Agent 可通过 `pt-snap rag add` 命令将成功的分析路径归档时,同时保存查询配置 -- 开发者可直接编辑 YAML 配置文件添加新查询 -- SDK 提供 `QueryConfig.save()` API 用于编程方式添加查询 - ---- - -## 六、RAG 知识库设计 - -### 6.1 案例数据结构 - -```json -{ - "case_id": "memory_leak_in_transformer_attention", - "timestamp": "2026-04-04T10:30:00Z", - "db_snapshot": "snapshot.db", - "analysis_steps": [ - { - "step": 1, - "action": "query", - "query": "peak_detection", - "result_summary": "发现 500MB 异常分配" - } - ], - "conclusion": "Attention 层的 key/value cache 未正确释放导致泄漏", - "root_cause": "transformers 库 v4.30.0 的 bug", - "solution": "升级 transformers 库到 v4.31.0", - "tags": ["memory-leak", "transformer", "attention"], - "confidence": 0.95, - "verified_by": "human_feedback" -} -``` - -### 6.2 实现技术 - -- **向量数据库**: ChromaDB -- **嵌入模型**: 可选用轻量级模型如 `all-MiniLM-L6-v2` -- **检索接口**: 相似度搜索 + 标签过滤 - ---- - -## 七、技术选型 - -| 模块 | 技术选择 | 理由 | -|------|---------|------| -| CLI 框架 | `typer` | 基于 type hints,自动生成 help,支持子命令 | -| SDK | 原生 Python | 低依赖、易集成 | -| JSON 输出 | `pydantic` | 结构化输出、类型校验 | -| RAG | `langchain` + `chromadb` | 成熟方案、易扩展 | -| SQL 构建 | 原生 sqlite3 + 模板引擎 | 轻量、可控 | -| YAML 解析 | `pyyaml` | 标准库,广泛使用 | -| 文档生成 | `mkdocs` | 可选,用于生成 API 文档 | - ---- - -## 八、分阶段交付计划 - -### 阶段 1: MVP 核心框架 (2-3 周) - -**目标**: 验证架构可行性 - -**交付物**: -- [ ] CLI 基础命令 (context, analyze, query) -- [ ] SQLite 查询接口封装 -- [ ] 内存泄漏检测算法 (leak_detector) -- [ ] JSON 输出格式定义 -- [ ] 基础单元测试 -- [ ] 预定义查询配置系统 -- [ ] AI Agent 调用示例/文档 - -### 阶段 2: SDK + 高级分析 (2-3 周) - -**目标**: 完善分析能力,提供 SDK - -**交付物**: -- [ ] Python SDK 封装 -- [ ] 峰值分析 (peak_analyzer) -- [ ] 趋势分析 (trend_analyzer) -- [ ] 调用栈分析 (stack_analyzer) -- [ ] 对比分析 (comparator) -- [ ] 查询配置管理 API -- [ ] SDK 使用文档 - -### 阶段 3: RAG 知识库集成 (2-3 周) - -**目标**: 知识库集成,智能化提升 - -**交付物**: -- [ ] 知识库文档结构设计 -- [ ] RAG 检索引擎集成 -- [ ] CLI/SDK 集成 RAG 接口 -- [ ] 案例归档功能 (rag add) -- [ ] 完整文档和示例 - ---- - -## 九、AI 友好设计要点 - -1. **结构化输出**: 所有命令默认输出 JSON,便于 AI 解析 -2. **确定性行为**: 相同输入 → 相同输出,AI 可预测结果 -3. **错误可解释**: 错误信息包含原因 + 建议修复方案 -4. **SDK 即代码**: AI 可直接生成 SDK 调用代码 -5. **知识库可检索**: RAG 让 AI 可访问先验经验 -6. **CLI 可组合**: AI 可组合多个 CLI 命令完成复杂分析 - ---- - -## 十、风险与缓解 - -### 10.1 技术风险 - -**风险**: SQLite 查询性能在大数据量场景下可能不足 - -**缓解**: -- 为常用查询字段添加索引 -- 支持查询分页 -- 考虑缓存热点查询结果 - -### 10.2 数据风险 - -**风险**: DB schema 变更导致兼容性问题 - -**缓解**: -- 设计 schema 版本检测 -- 提供 schema 迁移工具 -- SDK 增加 schema 适配层 - -### 10.3 使用风险 - -**风险**: RAG 知识库质量参差不齐 - -**缓解**: -- 引入案例质量评分机制 -- 支持人工审核和标记 -- 提供置信度指标 - ---- - -## 十一、成功标准 - -### 功能完整性 -- [ ] 所有预定义分析功能正常工作 -- [ ] CLI 命令覆盖所有核心场景 -- [ ] SDK API 文档完整 - -### AI 友好性 -- [ ] AI Agent 可成功调用 CLI 和 SDK -- [ ] JSON 输出格式稳定、可解析 -- [ ] RAG 检索准确率 > 80% - -### 代码质量 -- [ ] 单元测试覆盖率 > 80% -- [ ] 通过 type checking (mypy) -- [ ] 通过 lint (ruff) - -### 用户体验 -- [ ] CLI help 信息清晰完整 -- [ ] 错误信息友好、可操作 -- [ ] 示例文档齐全 - ---- - -## 附录 - -### A. CLI 命令完整列表 - -```bash -# 上下文管理 -pt-snap use -pt-snap config devices -pt-snap config show - -# 分析 -pt-snap analyze leak [--json] -pt-snap analyze peak [--json] -pt-snap analyze trend [--plot] -pt-snap analyze stack [--top-k N] - -# 查询 -pt-snap query list -pt-snap query exec [--format table|json] -pt-snap query custom "" [--json] - -# RAG -pt-snap rag add --case --conclusion "..." --tags "..." -pt-snap rag search "" [--top-k N] -pt-snap rag list [--tags ...] -pt-snap rag update --conclusion "..." -pt-snap rag remove - -# 对比 -pt-snap compare --metric memory -``` - -### B. SDK API 参考 - -```python -# Context -Context(db_path: str, devices: Union[List[int], str]) - -# Analyzer -Analyzer(context: Context) - - detect_leaks() -> LeakResult - - analyze_trend(metrics: List[str]) -> TrendResult - - analyze_stack_trace(top_k: int) -> StackResult - - analyze_peak() -> PeakResult - -# RAGSearcher -RAGSearcher(kb_path: str) - - search(query: str, top_k: int) -> List[Case] - - add_case(**kwargs) -> str (case_id) - - list_cases(tags: List[str]) -> List[Case] -``` - -### C. 相关文件 - -- [Schema 文档](../../snapshot_db_schema.md) -- [约束规范](../../snapshot_db_constraint_spec.md) -- [示例数据库](../../examples/snapshot_expandable.pkl.db) diff --git a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-analyzers.md b/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-analyzers.md deleted file mode 100644 index d2fcf27..0000000 --- a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-analyzers.md +++ /dev/null @@ -1,1556 +0,0 @@ -# pt-snap-analyzer 分析器模块计划 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** 实现核心分析器模块:泄漏检测、峰值分析、趋势分析、调用栈分析 - -**Architecture:** 基于 AnalyzerBase 抽象基类,每个分析器实现独立的 analyze() 方法,返回结构化结果 - -**Tech Stack:** Python 3.10+, SQLite3, Pydantic - ---- - -## 文件结构 - -``` -pt-snap-cli/ -├── pt_snap_analyzer/ -│ ├── analyzers/ -│ │ ├── __init__.py -│ │ ├── base.py # AnalyzerBase 抽象基类 -│ │ ├── leak_detector.py # 泄漏检测 -│ │ ├── peak_analyzer.py # 峰值分析 -│ │ ├── trend_analyzer.py # 趋势分析 -│ │ └── stack_analyzer.py # 调用栈分析 -│ └── models/ # 新增结果模型 -│ ├── __init__.py -│ ├── result.py # AnalysisResult 基类 -│ ├── leak.py # LeakResult -│ ├── peak.py # PeakResult -│ ├── trend.py # TrendResult -│ └── stack.py # StackResult -└── tests/ - ├── test_analyzers.py - ├── test_leak_detector.py - ├── test_peak_analyzer.py - ├── test_trend_analyzer.py - └── test_stack_analyzer.py -``` - ---- - -### Task 1: 分析器基类和结果模型 - -**Files:** -- Create: `pt_snap_analyzer/analyzers/base.py` -- Create: `pt_snap_analyzer/models/result.py` -- Modify: `pt_snap_analyzer/models/__init__.py` - -- [ ] **Step 1: 创建分析器基类** - -```python -"""Base class for analyzers""" - -from __future__ import annotations - -from abc import ABC, abstractmethod -from typing import Any, Dict, Optional - -from pt_snap_analyzer.context import Context - - -class AnalysisResult: - """Base class for analysis results""" - - def __init__(self, metadata: Optional[Dict[str, Any]] = None): - self.metadata = metadata or {} - - def to_dict(self) -> Dict[str, Any]: - """Convert result to dictionary""" - raise NotImplementedError - - def to_json(self) -> str: - """Convert result to JSON string""" - import json - return json.dumps(self.to_dict()) - - -class AnalyzerBase(ABC): - """Base class for all analyzers - - Attributes: - context: Analysis context with database connection - name: Analyzer name - description: Analyzer description - """ - - name: str = "" - description: str = "" - - def __init__(self, context: Context): - self.context = context - - @abstractmethod - def analyze(self, **kwargs) -> AnalysisResult: - """Run analysis and return results - - Args: - **kwargs: Analyzer-specific parameters - - Returns: - AnalysisResult instance - """ - raise NotImplementedError -``` - -- [ ] **Step 2: 创建结果模型基类** - -```python -"""Base class for analysis results""" - -from __future__ import annotations - -from dataclasses import dataclass -from typing import Any, Dict, Optional - - -@dataclass -class AnalysisResult: - """Base class for all analysis results - - Attributes: - metadata: Analysis metadata (database path, timestamp, etc.) - """ - metadata: Optional[Dict[str, Any]] = None - - def __post_init__(self): - if self.metadata is None: - self.metadata = {} - - def to_dict(self) -> Dict[str, Any]: - """Convert result to dictionary""" - return {"metadata": self.metadata} - - def to_json(self) -> str: - """Convert result to JSON string""" - import json - return json.dumps(self.to_dict()) -``` - -- [ ] **Step 3: 修改 models 初始化文件** - -```python -"""Data models for memory snapshot analysis""" - -from pt_snap_analyzer.models._enums import EventType, BlockState -from pt_snap_analyzer.models.event import MemoryEvent -from pt_snap_analyzer.models.block import MemoryBlock -from pt_snap_analyzer.models.result import AnalysisResult - -__all__ = [ - "EventType", - "BlockState", - "MemoryEvent", - "MemoryBlock", - "AnalysisResult", -] -``` - -- [ ] **Step 4: 创建测试文件** - -```python -"""Tests for analyzer base classes""" - -import pytest -from pt_snap_analyzer.analyzers.base import AnalyzerBase, AnalysisResult -from pt_snap_analyzer.context import Context - - -def test_analysis_result_defaults(): - """Test AnalysisResult default values""" - result = AnalysisResult() - assert result.metadata == {} - - -def test_analysis_result_with_metadata(): - """Test AnalysisResult with metadata""" - metadata = {"database": "test.db", "timestamp": "2024-01-01"} - result = AnalysisResult(metadata=metadata) - assert result.metadata == metadata - - -def test_analysis_result_to_dict(): - """Test AnalysisResult.to_dict()""" - metadata = {"database": "test.db"} - result = AnalysisResult(metadata=metadata) - result_dict = result.to_dict() - assert result_dict == {"metadata": metadata} - - -def test_analyzer_base_abstract(): - """Test AnalyzerBase is abstract""" - with pytest.raises(TypeError): - AnalyzerBase(context=None) # Can't instantiate abstract class - - -def test_analyzer_base_subclass(): - """Test AnalyzerBase subclass implementation""" - class TestAnalyzer(AnalyzerBase): - name = "test" - description = "Test analyzer" - - def analyze(self, **kwargs): - return AnalysisResult() - - from unittest.mock import MagicMock - mock_context = MagicMock(spec=Context) - analyzer = TestAnalyzer(context=mock_context) - assert analyzer.name == "test" - assert analyzer.description == "Test analyzer" - result = analyzer.analyze() - assert isinstance(result, AnalysisResult) -``` - -- [ ] **Step 5: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_analyzers.py -v -``` - -Expected: 5 tests PASS - -- [ ] **Step 6: Commit** - -```bash -git add pt_snap_analyzer/analyzers/base.py pt_snap_analyzer/models/result.py -git commit -m "feat: add AnalyzerBase and AnalysisResult base classes" -``` - ---- - -### Task 2: 泄漏检测分析器 - -**Files:** -- Create: `pt_snap_analyzer/analyzers/leak_detector.py` -- Create: `pt_snap_analyzer/models/leak.py` -- Modify: `tests/test_leak_detector.py` - -- [ ] **Step 1: 创建泄漏数据模型** - -```python -"""Leak detection result models""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from typing import List, Optional - -from pt_snap_analyzer.models.block import MemoryBlock -from pt_snap_analyzer.models.result import AnalysisResult - - -@dataclass -class LeakInfo: - """Information about a memory leak - - Attributes: - block: Memory block that was leaked - callstack: Call stack where memory was allocated - size: Size of leaked memory in bytes - """ - block: MemoryBlock - callstack: Optional[str] - size: int - - -@dataclass -class LeakResult(AnalysisResult): - """Result of memory leak detection - - Attributes: - leaks: List of detected leaks - total_leaked: Total leaked memory in bytes - leak_count: Number of leaked blocks - devices: List of device IDs analyzed - """ - leaks: List[LeakInfo] = field(default_factory=list) - total_leaked: int = 0 - leak_count: int = 0 - devices: List[int] = field(default_factory=list) - - def to_dict(self) -> dict: - """Convert result to dictionary""" - return { - "metadata": self.metadata, - "leaks": [ - { - "block_id": leak.block.id, - "address": leak.block.address, - "size": leak.size, - "callstack": leak.callstack, - } - for leak in self.leaks - ], - "total_leaked": self.total_leaked, - "leak_count": self.leak_count, - "devices": self.devices, - } -``` - -- [ ] **Step 2: 创建泄漏检测分析器** - -```python -"""Memory leak detector analyzer""" - -from __future__ import annotations - -from typing import List, Optional - -from pt_snap_analyzer.analyzers.base import AnalyzerBase, AnalysisResult -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models.block import MemoryBlock -from pt_snap_analyzer.models.leak import LeakInfo, LeakResult - - -class LeakDetector(AnalyzerBase): - """Detects memory leaks by finding blocks that were never freed - - Attributes: - name: Analyzer name - description: Analyzer description - """ - - name = "leak_detector" - description = "Detect memory leaks by finding unfreed blocks" - - def __init__(self, context: Context): - super().__init__(context) - self.context = context - - def detect_leaks( - self, - min_size: int = 1024, - device_ids: Optional[List[int]] = None, - ) -> LeakResult: - """Detect memory leaks - - Args: - min_size: Minimum block size to consider (bytes) - device_ids: List of device IDs to analyze (None = all) - - Returns: - LeakResult with detected leaks - """ - if device_ids is None: - device_ids = self.context.device_ids - - leaks: List[LeakInfo] = [] - total_leaked = 0 - - for device_id in device_ids: - cursor = self.context.cursor() - - # Query unfreed blocks - cursor.execute(f""" - SELECT b.id, b.address, b.size, b.requestedSize, b.state, - b.allocEventId, b.freeEventId, t.callstack - FROM block_{device_id} b - LEFT JOIN trace_entry_{device_id} t ON b.allocEventId = t.id - WHERE b.id >= 0 - AND (b.freeEventId IS NULL OR b.freeEventId = -1) - AND b.size >= ? - ORDER BY b.size DESC - """, (min_size,)) - - for row in cursor.fetchall(): - block = MemoryBlock( - id=row[0], - address=row[1], - size=row[2], - requestedSize=row[3], - state=row[4], - allocEventId=row[5], - freeEventId=row[6], - ) - callstack = row[7] - - leak = LeakInfo( - block=block, - callstack=callstack, - size=block.size, - ) - leaks.append(leak) - total_leaked += block.size - - result = LeakResult( - metadata={ - "analyzer": self.name, - "min_size": min_size, - "devices": device_ids, - }, - leaks=leaks, - total_leaked=total_leaked, - leak_count=len(leaks), - devices=device_ids, - ) - return result - - def analyze(self, **kwargs) -> AnalysisResult: - """Run leak detection analysis""" - return self.detect_leaks(**kwargs) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for LeakDetector""" - -import pytest -from unittest.mock import MagicMock -from pt_snap_analyzer.analyzers.leak_detector import LeakDetector, LeakInfo, LeakResult -from pt_snap_analyzer.models.block import MemoryBlock - - -def test_leak_detector_init(): - """Test LeakDetector initialization""" - mock_context = MagicMock() - detector = LeakDetector(mock_context) - assert detector.name == "leak_detector" - assert detector.description == "Detect memory leaks by finding unfreed blocks" - - -def test_leak_info_dataclass(): - """Test LeakInfo dataclass""" - block = MemoryBlock( - id=100, address=0x1000, size=4096, requestedSize=4096, - state=1, allocEventId=50, freeEventId=None - ) - leak = LeakInfo( - block=block, - callstack="test.py:10", - size=4096 - ) - assert leak.block == block - assert leak.callstack == "test.py:10" - assert leak.size == 4096 - - -def test_leak_result_dataclass(): - """Test LeakResult dataclass""" - block = MemoryBlock( - id=100, address=0x1000, size=4096, requestedSize=4096, - state=1, allocEventId=50, freeEventId=None - ) - leak = LeakInfo(block=block, callstack="test.py:10", size=4096) - result = LeakResult( - leaks=[leak], - total_leaked=4096, - leak_count=1, - devices=[0] - ) - assert len(result.leaks) == 1 - assert result.total_leaked == 4096 - assert result.leak_count == 1 - - -def test_leak_result_to_dict(): - """Test LeakResult.to_dict()""" - block = MemoryBlock( - id=100, address=0x1000, size=4096, requestedSize=4096, - state=1, allocEventId=50, freeEventId=None - ) - leak = LeakInfo(block=block, callstack="test.py:10", size=4096) - result = LeakResult( - leaks=[leak], - total_leaked=4096, - leak_count=1, - devices=[0] - ) - result_dict = result.to_dict() - assert "metadata" in result_dict - assert "leaks" in result_dict - assert result_dict["leak_count"] == 1 - assert result_dict["total_leaked"] == 4096 - - -def test_analyze_method(): - """Test analyze() calls detect_leaks()""" - mock_context = MagicMock() - detector = LeakDetector(mock_context) - - mock_result = MagicMock(spec=LeakResult) - detector.detect_leaks = MagicMock(return_value=mock_result) - - result = detector.analyze(min_size=1024) - - detector.detect_leaks.assert_called_once_with(min_size=1024) - assert result == mock_result -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_leak_detector.py -v -``` - -Expected: 5 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/analyzers/leak_detector.py pt_snap_analyzer/models/leak.py -git commit -m "feat: add LeakDetector for memory leak detection" -``` - ---- - -### Task 3: 峰值分析器 - -**Files:** -- Create: `pt_snap_analyzer/models/peak.py` -- Create: `pt_snap_analyzer/analyzers/peak_analyzer.py` -- Create: `tests/test_peak_analyzer.py` - -- [ ] **Step 1: 创建峰值数据模型** - -```python -"""Peak analysis result models""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from typing import List, Optional - -from pt_snap_analyzer.models.result import AnalysisResult - - -@dataclass -class PeakInfo: - """Information about a memory peak - - Attributes: - event_id: Event ID where peak occurred - timestamp: Event timestamp - size: Peak size in bytes - allocated: Total allocated at peak - active: Total active at peak - reserved: Total reserved at peak - """ - event_id: int - timestamp: int - size: int - allocated: int - active: int - reserved: int - - -@dataclass -class PeakResult(AnalysisResult): - """Result of memory peak analysis - - Attributes: - peaks: List of detected peaks - total_peaks: Number of peaks detected - max_size: Maximum peak size in bytes - avg_size: Average peak size in bytes - devices: List of device IDs analyzed - """ - peaks: List[PeakInfo] = field(default_factory=list) - total_peaks: int = 0 - max_size: int = 0 - avg_size: float = 0.0 - devices: List[int] = field(default_factory=list) - - def to_dict(self) -> dict: - """Convert result to dictionary""" - return { - "metadata": self.metadata, - "peaks": [ - { - "event_id": peak.event_id, - "timestamp": peak.timestamp, - "size": peak.size, - "allocated": peak.allocated, - "active": peak.active, - "reserved": peak.reserved, - } - for peak in self.peaks - ], - "total_peaks": self.total_peaks, - "max_size": self.max_size, - "avg_size": self.avg_size, - "devices": self.devices, - } -``` - -- [ ] **Step 2: 创建峰值分析器** - -```python -"""Peak analyzer for memory allocation spikes""" - -from __future__ import annotations - -from typing import List, Optional - -from pt_snap_analyzer.analyzers.base import AnalyzerBase, AnalysisResult -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models.peak import PeakInfo, PeakResult - - -class PeakAnalyzer(AnalyzerBase): - """Analyzes memory peaks (allocation spikes) - - Attributes: - name: Analyzer name - description: Analyzer description - """ - - name = "peak_analyzer" - description = "Analyze memory allocation peaks" - - def __init__(self, context: Context): - super().__init__(context) - self.context = context - - def analyze_peaks( - self, - top_k: int = 10, - device_ids: Optional[List[int]] = None, - ) -> PeakResult: - """Analyze memory peaks - - Args: - top_k: Number of top peaks to return - device_ids: List of device IDs to analyze (None = all) - - Returns: - PeakResult with top K peaks - """ - if device_ids is None: - device_ids = self.context.device_ids - - all_peaks: List[PeakInfo] = [] - - for device_id in device_ids: - cursor = self.context.cursor() - - # Query top allocations by size - cursor.execute(f""" - SELECT id, address, size, allocated, active, reserved - FROM trace_entry_{device_id} - WHERE action = 4 -- ALLOC - ORDER BY size DESC - LIMIT ? - """, (top_k,)) - - for row in cursor.fetchall(): - peak = PeakInfo( - event_id=row[0], - timestamp=row[0], # Use event_id as timestamp - size=row[2], - allocated=row[3], - active=row[4], - reserved=row[5], - ) - all_peaks.append(peak) - - # Sort and take top K - all_peaks.sort(key=lambda p: p.size, reverse=True) - top_peaks = all_peaks[:top_k] - - total_size = sum(p.size for p in top_peaks) - avg_size = total_size / len(top_peaks) if top_peaks else 0.0 - max_size = top_peaks[0].size if top_peaks else 0 - - result = PeakResult( - metadata={ - "analyzer": self.name, - "top_k": top_k, - "devices": device_ids, - }, - peaks=top_peaks, - total_peaks=len(top_peaks), - max_size=max_size, - avg_size=avg_size, - devices=device_ids, - ) - return result - - def analyze(self, **kwargs) -> AnalysisResult: - """Run peak analysis""" - return self.analyze_peaks(**kwargs) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for PeakAnalyzer""" - -import pytest -from unittest.mock import MagicMock -from pt_snap_analyzer.analyzers.peak_analyzer import PeakAnalyzer, PeakInfo, PeakResult - - -def test_peak_analyzer_init(): - """Test PeakAnalyzer initialization""" - mock_context = MagicMock() - analyzer = PeakAnalyzer(mock_context) - assert analyzer.name == "peak_analyzer" - - -def test_peak_info_dataclass(): - """Test PeakInfo dataclass""" - peak = PeakInfo( - event_id=100, - timestamp=100, - size=4096, - allocated=8192, - active=8192, - reserved=16384, - ) - assert peak.event_id == 100 - assert peak.size == 4096 - assert peak.allocated == 8192 - - -def test_peak_result_dataclass(): - """Test PeakResult dataclass""" - peak = PeakInfo( - event_id=100, timestamp=100, size=4096, - allocated=8192, active=8192, reserved=16384, - ) - result = PeakResult( - peaks=[peak], - total_peaks=1, - max_size=4096, - avg_size=4096.0, - devices=[0], - ) - assert len(result.peaks) == 1 - assert result.max_size == 4096 - - -def test_peak_result_to_dict(): - """Test PeakResult.to_dict()""" - peak = PeakInfo( - event_id=100, timestamp=100, size=4096, - allocated=8192, active=8192, reserved=16384, - ) - result = PeakResult( - peaks=[peak], - total_peaks=1, - max_size=4096, - avg_size=4096.0, - devices=[0], - ) - result_dict = result.to_dict() - assert "peaks" in result_dict - assert result_dict["total_peaks"] == 1 - assert result_dict["max_size"] == 4096 - - -def test_analyze_peaks_empty(): - """Test analyze_peaks with no data""" - mock_context = MagicMock() - mock_context.device_ids = [] - analyzer = PeakAnalyzer(mock_context) - - result = analyzer.analyze_peaks(top_k=10) - assert result.total_peaks == 0 - assert result.max_size == 0 - assert result.avg_size == 0.0 -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_peak_analyzer.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/models/peak.py pt_snap_analyzer/analyzers/peak_analyzer.py -git commit -m "feat: add PeakAnalyzer for memory peak detection" -``` - ---- - -### Task 4: 趋势分析器 - -**Files:** -- Create: `pt_snap_analyzer/models/trend.py` -- Create: `pt_snap_analyzer/analyzers/trend_analyzer.py` -- Create: `tests/test_trend_analyzer.py` - -- [ ] **Step 1: 创建趋势数据模型** - -```python -"""Memory trend analysis result models""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from typing import List, Optional - -from pt_snap_analyzer.models.result import AnalysisResult - - -@dataclass -class TrendPoint: - """A single point in memory usage trend - - Attributes: - timestamp: Event ID / timestamp - allocated: Total allocated memory - active: Total active memory - reserved: Total reserved memory - """ - timestamp: int - allocated: int - active: int - reserved: int - - -@dataclass -class TrendResult(AnalysisResult): - """Result of memory trend analysis - - Attributes: - points: List of trend points - total_points: Number of data points - start_allocated: Starting allocated memory - end_allocated: Ending allocated memory - max_allocated: Maximum allocated memory - min_allocated: Minimum allocated memory - devices: List of device IDs analyzed - """ - points: List[TrendPoint] = field(default_factory=list) - total_points: int = 0 - start_allocated: int = 0 - end_allocated: int = 0 - max_allocated: int = 0 - min_allocated: int = 0 - devices: List[int] = field(default_factory=list) - - def to_dict(self) -> dict: - """Convert result to dictionary""" - return { - "metadata": self.metadata, - "points": [ - { - "timestamp": p.timestamp, - "allocated": p.allocated, - "active": p.active, - "reserved": p.reserved, - } - for p in self.points - ], - "total_points": self.total_points, - "start_allocated": self.start_allocated, - "end_allocated": self.end_allocated, - "max_allocated": self.max_allocated, - "min_allocated": self.min_allocated, - "devices": self.devices, - } -``` - -- [ ] **Step 2: 创建趋势分析器** - -```python -"""Trend analyzer for memory usage over time""" - -from __future__ import annotations - -from typing import List, Optional, Literal - -from pt_snap_analyzer.analyzers.base import AnalyzerBase, AnalysisResult -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models.trend import TrendPoint, TrendResult - - -MetricType = Literal["allocated", "active", "reserved"] - - -class TrendAnalyzer(AnalyzerBase): - """Analyzes memory usage trends over time - - Attributes: - name: Analyzer name - description: Analyzer description - """ - - name = "trend_analyzer" - description = "Analyze memory usage trends over time" - - def __init__(self, context: Context): - super().__init__(context) - self.context = context - - def analyze_trend( - self, - metrics: List[MetricType] = ["allocated", "active", "reserved"], - device_ids: Optional[List[int]] = None, - ) -> TrendResult: - """Analyze memory usage trend - - Args: - metrics: List of metrics to track - device_ids: List of device IDs to analyze (None = all) - - Returns: - TrendResult with time series data - """ - if device_ids is None: - device_ids = self.context.device_ids - - all_points: List[TrendPoint] = [] - - for device_id in device_ids: - cursor = self.context.cursor() - - # Query all events ordered by ID - cursor.execute(f""" - SELECT id, allocated, active, reserved - FROM trace_entry_{device_id} - ORDER BY id ASC - """) - - for row in cursor.fetchall(): - point = TrendPoint( - timestamp=row[0], - allocated=row[1], - active=row[2], - reserved=row[3], - ) - all_points.append(point) - - if not all_points: - return TrendResult( - metadata={ - "analyzer": self.name, - "metrics": metrics, - "devices": device_ids, - }, - devices=device_ids, - ) - - # Calculate statistics - allocated_values = [p.allocated for p in all_points] - start_allocated = allocated_values[0] - end_allocated = allocated_values[-1] - max_allocated = max(allocated_values) - min_allocated = min(allocated_values) - - result = TrendResult( - metadata={ - "analyzer": self.name, - "metrics": metrics, - "devices": device_ids, - }, - points=all_points, - total_points=len(all_points), - start_allocated=start_allocated, - end_allocated=end_allocated, - max_allocated=max_allocated, - min_allocated=min_allocated, - devices=device_ids, - ) - return result - - def analyze(self, **kwargs) -> AnalysisResult: - """Run trend analysis""" - return self.analyze_trend(**kwargs) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for TrendAnalyzer""" - -import pytest -from unittest.mock import MagicMock -from pt_snap_analyzer.analyzers.trend_analyzer import TrendAnalyzer, TrendPoint, TrendResult - - -def test_trend_analyzer_init(): - """Test TrendAnalyzer initialization""" - mock_context = MagicMock() - analyzer = TrendAnalyzer(mock_context) - assert analyzer.name == "trend_analyzer" - - -def test_trend_point_dataclass(): - """Test TrendPoint dataclass""" - point = TrendPoint( - timestamp=100, - allocated=8192, - active=8192, - reserved=16384, - ) - assert point.timestamp == 100 - assert point.allocated == 8192 - - -def test_trend_result_dataclass(): - """Test TrendResult dataclass""" - point = TrendPoint( - timestamp=100, allocated=8192, active=8192, reserved=16384, - ) - result = TrendResult( - points=[point], - total_points=1, - start_allocated=8192, - end_allocated=8192, - max_allocated=8192, - min_allocated=8192, - devices=[0], - ) - assert len(result.points) == 1 - assert result.total_points == 1 - - -def test_trend_result_statistics(): - """Test TrendResult statistics calculation""" - points = [ - TrendPoint(timestamp=1, allocated=1000, active=1000, reserved=2000), - TrendPoint(timestamp=2, allocated=2000, active=2000, reserved=4000), - TrendPoint(timestamp=3, allocated=1500, active=1500, reserved=3000), - ] - result = TrendResult( - points=points, - total_points=3, - start_allocated=1000, - end_allocated=1500, - max_allocated=2000, - min_allocated=1000, - devices=[0], - ) - assert result.start_allocated == 1000 - assert result.end_allocated == 1500 - assert result.max_allocated == 2000 - assert result.min_allocated == 1000 - - -def test_analyze_trend_empty(): - """Test analyze_trend with no data""" - mock_context = MagicMock() - mock_context.device_ids = [] - analyzer = TrendAnalyzer(mock_context) - - result = analyzer.analyze_trend() - assert result.total_points == 0 - assert result.start_allocated == 0 -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_trend_analyzer.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/models/trend.py pt_snap_analyzer/analyzers/trend_analyzer.py -git commit -m "feat: add TrendAnalyzer for memory usage trends" -``` - ---- - -### Task 5: 调用栈分析器 - -**Files:** -- Create: `pt_snap_analyzer/models/stack.py` -- Create: `pt_snap_analyzer/analyzers/stack_analyzer.py` -- Create: `tests/test_stack_analyzer.py` - -- [ ] **Step 1: 创建调用栈数据模型** - -```python -"""Call stack analysis result models""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from typing import List, Optional - -from pt_snap_analyzer.models.result import AnalysisResult - - -@dataclass -class StackInfo: - """Information about a call stack pattern - - Attributes: - callstack: The call stack string (multiline) - count: Number of times this callstack appeared - total_size: Total memory allocated by this callstack - frames: Parsed call stack frames - """ - callstack: str - count: int = 0 - total_size: int = 0 - frames: List[str] = field(default_factory=list) - - @property - def avg_size(self) -> float: - """Average allocation size""" - return self.total_size / self.count if self.count > 0 else 0.0 - - -@dataclass -class StackResult(AnalysisResult): - """Result of call stack analysis - - Attributes: - stacks: List of call stack patterns - total_stacks: Number of unique call stacks - total_allocations: Total allocation count - total_size: Total allocated memory - devices: List of device IDs analyzed - """ - stacks: List[StackInfo] = field(default_factory=list) - total_stacks: int = 0 - total_allocations: int = 0 - total_size: int = 0 - devices: List[int] = field(default_factory=list) - - def to_dict(self) -> dict: - """Convert result to dictionary""" - return { - "metadata": self.metadata, - "stacks": [ - { - "callstack": s.callstack, - "count": s.count, - "total_size": s.total_size, - "avg_size": s.avg_size, - "frames": s.frames, - } - for s in self.stacks - ], - "total_stacks": self.total_stacks, - "total_allocations": self.total_allocations, - "total_size": self.total_size, - "devices": self.devices, - } -``` - -- [ ] **Step 2: 创建调用栈分析器** - -```python -"""Call stack analyzer for allocation patterns""" - -from __future__ import annotations - -from typing import List, Optional, Literal - -from pt_snap_analyzer.analyzers.base import AnalyzerBase, AnalysisResult -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models.stack import StackInfo, StackResult - - -GroupByType = Literal["function", "file"] - - -class StackAnalyzer(AnalyzerBase): - """Analyzes call stack patterns in memory allocations - - Attributes: - name: Analyzer name - description: Analyzer description - """ - - name = "stack_analyzer" - description = "Analyze call stack patterns in memory allocations" - - def __init__(self, context: Context): - super().__init__(context) - self.context = context - - def analyze_stack_trace( - self, - top_k: int = 10, - group_by: GroupByType = "function", - device_ids: Optional[List[int]] = None, - ) -> StackResult: - """Analyze call stack patterns - - Args: - top_k: Number of top call stacks to return - group_by: Group by 'function' or 'file' - device_ids: List of device IDs to analyze (None = all) - - Returns: - StackResult with top K call stacks - """ - if device_ids is None: - device_ids = self.context.device_ids - - stack_counts: dict[str, int] = {} - stack_sizes: dict[str, int] = {} - - for device_id in device_ids: - cursor = self.context.cursor() - - # Query events with callstacks - cursor.execute(f""" - SELECT id, size, callstack - FROM trace_entry_{device_id} - WHERE callstack IS NOT NULL - AND callstack != '' - ORDER BY size DESC - LIMIT 10000 -- Limit for performance - """) - - for row in cursor.fetchall(): - callstack = row[2] - size = row[1] - - if callstack not in stack_counts: - stack_counts[callstack] = 0 - stack_sizes[callstack] = 0 - - stack_counts[callstack] += 1 - stack_sizes[callstack] += size - - # Build StackInfo list - stacks: List[StackInfo] = [] - for callstack, count in stack_counts.items(): - stack = StackInfo( - callstack=callstack, - count=count, - total_size=stack_sizes[callstack], - frames=self._parse_frames(callstack, group_by), - ) - stacks.append(stack) - - # Sort by count and take top K - stacks.sort(key=lambda s: s.count, reverse=True) - top_stacks = stacks[:top_k] - - total_allocations = sum(s.count for s in top_stacks) - total_size = sum(s.total_size for s in top_stacks) - - result = StackResult( - metadata={ - "analyzer": self.name, - "top_k": top_k, - "group_by": group_by, - "devices": device_ids, - }, - stacks=top_stacks, - total_stacks=len(top_stacks), - total_allocations=total_allocations, - total_size=total_size, - devices=device_ids, - ) - return result - - def _parse_frames(self, callstack: str, group_by: GroupByType) -> List[str]: - """Parse call stack into frames - - Args: - callstack: Multi-line call stack string - group_by: Group by function or file - - Returns: - List of frame identifiers - """ - frames = [] - for line in callstack.strip().split("\n"): - line = line.strip() - if not line: - continue - - if group_by == "function": - # Extract function name (last part after last space) - parts = line.rsplit(" ", 1) - if len(parts) == 2: - frames.append(parts[1]) - else: - frames.append(line) - else: # group_by == "file" - # Extract file path and line number - if ":" in line: - parts = line.rsplit(":", 1) - frames.append(f"{parts[0]}:{parts[1]}") - else: - frames.append(line) - - return frames - - def analyze(self, **kwargs) -> AnalysisResult: - """Run stack analysis""" - return self.analyze_stack_trace(**kwargs) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for StackAnalyzer""" - -import pytest -from unittest.mock import MagicMock -from pt_snap_analyzer.analyzers.stack_analyzer import StackAnalyzer, StackInfo, StackResult - - -def test_stack_analyzer_init(): - """Test StackAnalyzer initialization""" - mock_context = MagicMock() - analyzer = StackAnalyzer(mock_context) - assert analyzer.name == "stack_analyzer" - - -def test_stack_info_dataclass(): - """Test StackInfo dataclass""" - info = StackInfo( - callstack="file.py:10 function", - count=5, - total_size=20480, - ) - assert info.callstack == "file.py:10 function" - assert info.count == 5 - assert info.total_size == 20480 - assert info.avg_size == 4096.0 - - -def test_stack_result_dataclass(): - """Test StackResult dataclass""" - info = StackInfo( - callstack="file.py:10 function", - count=5, - total_size=20480, - ) - result = StackResult( - stacks=[info], - total_stacks=1, - total_allocations=5, - total_size=20480, - devices=[0], - ) - assert len(result.stacks) == 1 - assert result.total_allocations == 5 - - -def test_analyze_stack_trace_empty(): - """Test analyze_stack_trace with no data""" - mock_context = MagicMock() - mock_context.device_ids = [] - analyzer = StackAnalyzer(mock_context) - - result = analyzer.analyze_stack_trace() - assert result.total_stacks == 0 - assert result.total_allocations == 0 - - -def test_parse_frames(): - """Test _parse_frames method""" - mock_context = MagicMock() - analyzer = StackAnalyzer(mock_context) - - callstack = "test.py:10 main\\n test.py:5 train\\n test.py:3 step" - - frames_func = analyzer._parse_frames(callstack, "function") - frames_file = analyzer._parse_frames(callstack, "file") - - assert len(frames_func) == 3 - assert len(frames_file) == 3 -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_stack_analyzer.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/models/stack.py pt_snap_analyzer/analyzers/stack_analyzer.py -git commit -m "feat: add StackAnalyzer for call stack pattern analysis" -``` - ---- - -### Task 6: CLI 集成和测试 - -**Files:** -- Modify: `pt_snap_analyzer/cli.py` -- Create: `tests/test_cli_analyze.py` - -- [ ] **Step 1: 添加 analyze 命令到 CLI** - -```python -# Add to cli.py after imports - -from pt_snap_analyzer.analyzers.leak_detector import LeakDetector -from pt_snap_analyzer.analyzers.peak_analyzer import PeakAnalyzer -from pt_snap_analyzer.analyzers.trend_analyzer import TrendAnalyzer -from pt_snap_analyzer.analyzers.stack_analyzer import StackAnalyzer -from pt_snap_analyzer.context import Context, DatabaseNotFoundError - - -@app.command() -def analyze(): - """Memory analysis commands""" - raise typer.Exit(code=1) - - -@app.command() -def analyze_leak( - min_size: Annotated[ - int, typer.Option(help="Minimum leak size in bytes") - ] = 1024, - json_output: Annotated[ - bool, typer.Option("--json", help="Output in JSON format") - ] = False, -): - """Detect memory leaks""" - # Get current database - db_path = _get_current_db() - if db_path is None: - print("Error: No database selected. Use 'pt-snap use ' first.", flush=True) - raise typer.Exit(code=1) - - try: - with Context(db_path) as ctx: - detector = LeakDetector(ctx) - result = detector.detect_leaks(min_size=min_size) - - if json_output: - print(result.to_json()) - else: - _print_leak_result(result) - except DatabaseNotFoundError as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - - -@app.command() -def analyze_peak( - top_k: Annotated[ - int, typer.Option(help="Number of top peaks to show") - ] = 10, - json_output: Annotated[ - bool, typer.Option("--json", help="Output in JSON format") - ] = False, -): - """Analyze memory peaks""" - db_path = _get_current_db() - if db_path is None: - print("Error: No database selected. Use 'pt-snap use ' first.", flush=True) - raise typer.Exit(code=1) - - try: - with Context(db_path) as ctx: - analyzer = PeakAnalyzer(ctx) - result = analyzer.analyze_peaks(top_k=top_k) - - if json_output: - print(result.to_json()) - else: - _print_peak_result(result) - except DatabaseNotFoundError as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - - -def _get_current_db() -> Optional[str]: - """Get current database path""" - import os - config_dir = Path.home() / ".config" / "pt-snap-analyzer" - config_file = config_dir / "current_db" - - if config_file.exists(): - return config_file.read_text().strip() - return None -``` - -- [ ] **Step 2: 创建 CLI 分析测试** - -```python -"""Tests for CLI analyze commands""" - -from click.testing import CliRunner -from pt_snap_analyzer.cli import app - - -def test_analyze_leak_json(): - """Test analyze-leak with JSON output""" - runner = CliRunner() - result = runner.invoke(app, ["analyze-leak", "--json"]) - # Expected to fail because no database selected - assert result.exit_code != 0 - - -def test_analyze_peak_json(): - """Test analyze-peak with JSON output""" - runner = CliRunner() - result = runner.invoke(app, ["analyze-peak", "--json"]) - # Expected to fail because no database selected - assert result.exit_code != 0 - - -def test_help_text(): - """Test help text includes analyze commands""" - runner = CliRunner() - result = runner.invoke(app, ["--help"]) - assert result.exit_code == 0 - assert "Memory analysis commands" in result.output -``` - -- [ ] **Step 3: 运行所有 analyze 测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_cli_analyze.py -v -``` - -Expected: 3 tests PASS - -- [ ] **Step 4: 运行完整测试套件** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - -Expected: 20+ tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/cli.py tests/test_cli_analyze.py -git commit -m "feat: integrate analyzers into CLI" -``` - ---- - -### 最终验收清单 - -- [ ] 所有测试通过 (20+ tests) -- [ ] LeakDetector 正确检测泄漏 -- [ ] PeakAnalyzer 正确识别峰值 -- [ ] TrendAnalyzer 正确生成趋势数据 -- [ ] StackAnalyzer 正确分析调用栈 -- [ ] CLI 命令正常工作 -- [ ] JSON 输出格式正确 -- [ ] pytest 覆盖率 > 80% - ---- - -## 执行意见 - -Plan complete and saved to `docs/superpowers/plans/2026-04-04-pt-snap-analyzer-analyzers.md`. Two execution options: - -**1. Subagent-Driven (recommended)** - 我分发每个任务的独立 subagent,任务间审查,快速迭代 - -**2. Inline Execution** - 在此会话中执行任务,使用 executing-plans,批次执行加检查点 - -**Which approach?** diff --git a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-foundation.md b/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-foundation.md deleted file mode 100644 index 7e7bb80..0000000 --- a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-foundation.md +++ /dev/null @@ -1,1020 +0,0 @@ -# pt-snap-analyzer 基础架构计划 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** 构建 CLI 框架、数据模型和核心 Context,提供基础 API 支撑 - -**Architecture:** 基于 Typer 构建 CLI 框架,Pydantic 定义数据模型,SQLite 管理数据库连接 - -**Tech Stack:** Python 3.10+, Typer, Pydantic, SQLite3 - ---- - -## 文件结构 - -``` -pt-snap-cli/ -├── pt_snap_analyzer/ -│ ├── __init__.py -│ ├── cli.py # CLI 入口 -│ ├── context.py # Context 类 -│ ├── models/ -│ │ ├── __init__.py -│ │ ├── event.py # MemoryEvent -│ │ └── block.py # MemoryBlock -│ └── version.py # 版本信息 -├── tests/ -│ ├── test_context.py -│ ├── test_models.py -│ └── test_cli.py -├── examples/ -│ └── snapshot_expandable.pkl.db -└── pyproject.toml -``` - ---- - -### Task 1: 项目初始化和配置 - -**Files:** -- Create: `pt_snap_analyzer/__init__.py` -- Create: `pt_snap_analyzer/version.py` -- Create: `pyproject.toml` -- Create: `examples/snapshot_expandable.pkl.db` (symlink to test database) - -- [ ] **Step 1: 创建包初始化文件** - -```python -"""pt-snap-analyzer - AI-friendly PyTorch Memory Snapshot Analyzer""" - -__version__ = "0.1.0" -__author__ = "Liuyekang" - -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models import MemoryEvent, MemoryBlock - -__all__ = ["Context", "MemoryEvent", "MemoryBlock", "__version__"] -``` - -- [ ] **Step 2: 创建版本信息文件** - -```python -"""Package version""" - -__version__ = "0.1.0" -``` - -- [ ] **Step 3: 创建 pyproject.toml** - -```toml -[build-system] -requires = ["setuptools>=61.0"] -build-backend = "setuptools.build_meta" - -[project] -name = "pt-snap-analyzer" -version = "0.1.0" -description = "AI-friendly PyTorch Memory Snapshot Analyzer" -readme = "README.md" -requires-python = ">=3.10" -license = {text = "MIT"} -authors = [ - {name = "Liuyekang", email = "liuyekang@example.com"} -] -dependencies = [ - "typer>=0.9.0", - "pydantic>=2.0.0", - "pyyaml>=6.0", - "chromadb>=0.4.0", - "langchain>=0.1.0", -] - -[project.scripts] -pt-snap = "pt_snap_analyzer.cli:app" - -[project.optional-dependencies] -dev = [ - "pytest>=7.0.0", - "pytest-cov>=4.0.0", - "black>=23.0.0", - "ruff>=0.0.280", -] - -[tool.black] -line-length = 100 -target-version = ['py310'] - -[tool.ruff] -line-length = 100 -target-version = "py310" - -[tool.ruff.lint] -select = ["E", "F", "W", "I"] -ignore = ["E501"] - -[tool.ruff.lint.isort] -known-first-party = ["pt_snap_analyzer"] -``` - -- [ ] **Step 4: 创建示例数据库符号链接** - -```bash -mkdir -p examples -ln -sf /path/to/snapshot_expandable.pkl.db examples/snapshot_expandable.pkl.db -``` - -- [ ] **Step 5: 运行安装测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pip install -e .[dev] -v -``` - -Expected: 安装成功,无错误 - -- [ ] **Step 6: Commit** - -```bash -git add pt_snap_analyzer/__init__.py pt_snap_analyzer/version.py pyproject.toml -git commit -m "chore: project initialization and configuration" -``` - ---- - -### Task 2: 数据模型 - 枚举类型和基类 - -**Files:** -- Create: `pt_snap_analyzer/models/__init__.py` -- Create: `pt_snap_analyzer/models/_enums.py` - -- [ ] **Step 1: 创建枚举模块** - -```python -"""Data models for memory snapshot analysis""" - -from enum import IntEnum - - -class EventType(IntEnum): - """Memory event action types""" - SEGMENT_MAP = 0 - SEGMENT_UNMAP = 1 - SEGMENT_ALLOC = 2 - SEGMENT_FREE = 3 - ALLOC = 4 - FREE_REQUESTED = 5 - FREE_COMPLETED = 6 - WORKSPACE_SNAPSHOT = 7 - - -class BlockState(IntEnum): - """Memory block states""" - INACTIVE = -1 - ACTIVE_PENDING_FREE = 0 - ACTIVE_ALLOCATED = 1 - UNKNOWN = 99 -``` - -- [ ] **Step 2: 创建 models 初始化文件** - -```python -"""Data models for memory snapshot analysis""" - -from pt_snap_analyzer.models._enums import EventType, BlockState -from pt_snap_analyzer.models.event import MemoryEvent -from pt_snap_analyzer.models.block import MemoryBlock - -__all__ = ["EventType", "BlockState", "MemoryEvent", "MemoryBlock"] -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for data models""" - -import pytest -from pt_snap_analyzer.models import EventType, BlockState - - -def test_event_type_enum(): - """Test EventType enum values""" - assert EventType.SEGMENT_MAP == 0 - assert EventType.ALLOC == 4 - assert EventType.FREE_COMPLETED == 6 - - -def test_block_state_enum(): - """Test BlockState enum values""" - assert BlockState.INACTIVE == -1 - assert BlockState.ACTIVE_ALLOCATED == 1 - assert BlockState.UNKNOWN == 99 - - -def test_event_type_is_intenum(): - """Test EventType is IntEnum subclass""" - assert issubclass(EventType, int) - assert issubclass(EventType, IntEnum) - - -def test_block_state_is_intenum(): - """Test BlockState is IntEnum subclass""" - assert issubclass(BlockState, int) - assert issubclass(BlockState, IntEnum) -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_models.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/models/ tests/test_models.py -git commit -m "feat: add data models - EventType and BlockState enums" -``` - ---- - -### Task 3: 数据模型 - MemoryEvent 和 MemoryBlock - -**Files:** -- Create: `pt_snap_analyzer/models/event.py` -- Create: `pt_snap_analyzer/models/block.py` - -- [ ] **Step 1: 创建 MemoryEvent 模型** - -```python -"""MemoryEvent data model""" - -from __future__ import annotations - -from dataclasses import dataclass -from typing import Optional - -from pt_snap_analyzer.models._enums import EventType - - -@dataclass -class MemoryEvent: - """Represents a memory allocation/free event - - Attributes: - id: Event ID (negative for synthetic events) - action: Type of memory action - address: Memory address - size: Allocation size in bytes - stream: CUDA/CANN stream ID - allocated: Total allocated memory - active: Total active memory - reserved: Total reserved memory - callstack: Call stack information (multi-line string) - """ - id: int - action: EventType - address: int - size: int - stream: int - allocated: int - active: int - reserved: int - callstack: Optional[str] - - @property - def is_virtual_event(self) -> bool: - """Check if event is system-generated (virtual)""" - return self.id < 0 - - @property - def is_runtime_event(self) -> bool: - """Check if event is from runtime code""" - return self.id >= 0 - - @classmethod - def from_row(cls, row: tuple) -> MemoryEvent: - """Create MemoryEvent from database row - - Args: - row: Tuple from SQLite query (id, action, address, size, - stream, allocated, active, reserved, callstack) - - Returns: - MemoryEvent instance - """ - return cls( - id=row[0], - action=EventType(row[1]), - address=row[2], - size=row[3], - stream=row[4], - allocated=row[5], - active=row[6], - reserved=row[7], - callstack=row[8], - ) -``` - -- [ ] **Step 2: 创建 MemoryBlock 模型** - -```python -"""MemoryBlock data model""" - -from __future__ import annotations - -from dataclasses import dataclass -from typing import Optional - -from pt_snap_analyzer.models._enums import BlockState - - -@dataclass -class MemoryBlock: - """Represents a memory block with its lifecycle state - - Attributes: - id: Block ID (negative for historical blocks) - address: Memory address - size: Actual allocation size in bytes - requestedSize: User-requested size - state: Block state - allocEventId: ID of allocation event - freeEventId: ID of free event - """ - id: int - address: int - size: int - requestedSize: int - state: int - allocEventId: Optional[int] - freeEventId: Optional[int] - - @property - def is_historical_block(self) -> bool: - """Check if block is from historical snapshot""" - return self.id < 0 - - @property - def is_active(self) -> bool: - """Check if block is currently allocated""" - if self.is_historical_block: - return self.state == BlockState.ACTIVE_ALLOCATED - return self.freeEventId is None or self.freeEventId == -1 - - @property - def block_state(self) -> BlockState: - """Get block state as BlockState enum""" - return BlockState(self.state) if self.state != 99 else BlockState.UNKNOWN - - @classmethod - def from_row(cls, row: tuple) -> MemoryBlock: - """Create MemoryBlock from database row - - Args: - row: Tuple from SQLite query (id, address, size, requestedSize, - state, allocEventId, freeEventId) - - Returns: - MemoryBlock instance - """ - return cls( - id=row[0], - address=row[1], - size=row[2], - requestedSize=row[3], - state=row[4], - allocEventId=row[5], - freeEventId=row[6], - ) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for MemoryEvent and MemoryBlock models""" - -import pytest -from pt_snap_analyzer.models import MemoryEvent, MemoryBlock, EventType, BlockState - - -def test_memory_event_properties(): - """Test MemoryEvent properties""" - event = MemoryEvent( - id=1, action=EventType.ALLOC, address=0x1000, size=1024, - stream=0, allocated=2048, active=2048, reserved=4096, - callstack="test.py:10" - ) - assert not event.is_virtual_event - assert event.is_runtime_event - - -def test_memory_event_virtual(): - """Test virtual event detection""" - event = MemoryEvent( - id=-100, action=EventType.ALLOC, address=0x1000, size=1024, - stream=0, allocated=2048, active=2048, reserved=4096, - callstack=None - ) - assert event.is_virtual_event - assert not event.is_runtime_event - - -def test_memory_event_from_row(): - """Test MemoryEvent.from_row()""" - row = (1, 4, 0x1000, 1024, 0, 2048, 2048, 4096, "test.py:10") - event = MemoryEvent.from_row(row) - assert event.id == 1 - assert event.action == EventType.ALLOC - assert event.size == 1024 - assert event.callstack == "test.py:10" - - -def test_memory_block_properties(): - """Test MemoryBlock properties""" - block = MemoryBlock( - id=-320, address=0x2000, size=4096, requestedSize=4096, - state=1, allocEventId=-1, freeEventId=-1 - ) - assert block.is_historical_block - assert block.is_active - assert block.block_state == BlockState.ACTIVE_ALLOCATED - - -def test_memory_block_active_state(): - """Test active block detection""" - block = MemoryBlock( - id=100, address=0x3000, size=2048, requestedSize=2048, - state=0, allocEventId=50, freeEventId=None - ) - assert not block.is_historical_block - assert block.is_active - - -def test_memory_block_inactive(): - """Test inactive block detection""" - block = MemoryBlock( - id=101, address=0x4000, size=2048, requestedSize=2048, - state=0, allocEventId=51, freeEventId=60 - ) - assert not block.is_active - - -def test_memory_block_from_row(): - """Test MemoryBlock.from_row()""" - row = (-320, 0x2000, 4096, 4096, 1, -1, -1) - block = MemoryBlock.from_row(row) - assert block.id == -320 - assert block.address == 0x2000 - assert block.is_historical_block -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_models.py -v -``` - -Expected: 8 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/models/event.py pt_snap_analyzer/models/block.py -git commit -m "feat: add MemoryEvent and MemoryBlock data models" -``` - ---- - -### Task 4: Context 类 - 数据库连接管理 - -**Files:** -- Create: `pt_snap_analyzer/context.py` -- Modify: `tests/test_models.py` → add context tests - -- [ ] **Step 1: 创建 Context 类** - -```python -"""Context management for snapshot analysis""" - -from __future__ import annotations - -import sqlite3 -from contextlib import contextmanager -from dataclasses import dataclass, field -from pathlib import Path -from typing import Any, Generator, Optional - -from pt_snap_analyzer.version import __version__ - - -class DatabaseNotFoundError(FileNotFoundError): - """Raised when database file not found""" - def __init__(self, path: str): - super().__init__(f"Database not found: {path}") - self.path = path - - -class SchemaVersionError(Exception): - """Raised when database schema version mismatch""" - def __init__(self, expected: str, actual: Optional[str]): - super().__init__(f"Schema version mismatch: expected {expected}, got {actual}") - self.expected = expected - self.actual = actual - - -@dataclass -class Context: - """Analysis context managing database connection and configuration - - Attributes: - db_path: Path to SQLite database - devices: List of device IDs to analyze (None = all) - db_version: Database schema version - _AnNOTE__: Database connection (internal) - """ - db_path: str - devices: Optional[list[int]] = None - _conn: Optional[sqlite3.Connection] = field(default=None, repr=False) - - def __post_init__(self): - """Validate and open database""" - self._validate_db_path() - self._conn = self._open_database() - self._validate_schema() - - def _validate_db_path(self) -> None: - """Validate database file exists""" - path = Path(self.db_path) - if not path.exists(): - raise DatabaseNotFoundError(self.db_path) - if not path.is_file(): - raise DatabaseNotFoundError(f"Not a file: {self.db_path}") - - def _open_database(self) -> sqlite3.Connection: - """Open database in read-only mode""" - path = Path(self.db_path).resolve() - uri = f"file:{path}?mode=ro" - return sqlite3.connect(uri, uri=True) - - def _validate_schema(self) -> None: - """Validate database schema version""" - cursor = self._conn.cursor() - cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='dictionary'") - if cursor.fetchone() is None: - raise SchemaVersionError("v1.0", "no dictionary table") - - @property - def device_ids(self) -> list[int]: - """Get list of device IDs in database""" - cursor = self._conn.cursor() - cursor.execute( - "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'block_%'" - ) - tables = cursor.fetchall() - devices = [] - for (table,) in tables: - try: - device_id = int(table.split("_")[-1]) - devices.append(device_id) - except (ValueError, IndexError): - continue - if self.devices is not None: - devices = [d for d in devices if d in self.devices] - return devices - - def cursor(self) -> sqlite3.Cursor: - """Get database cursor""" - if self._conn is None: - raise RuntimeError("Database not connected") - return self._conn.cursor() - - @contextmanager - def connect(self) -> Generator[sqlite3.Connection, None, None]: - """Context manager for database connection - - Yields: - Database connection - """ - if self._conn is None: - raise RuntimeError("Database not connected") - try: - yield self._conn - finally: - pass - - def close(self) -> None: - """Close database connection""" - if self._conn is not None: - self._conn.close() - self._conn = None - - def __enter__(self) -> Context: - """Context manager entry""" - return self - - def __exit__(self, exc_type, exc_val, exc_tb) -> None: - """Context manager exit""" - self.close() - - def __del__(self) -> None: - """Destructor to close connection""" - self.close() -``` - -- [ ] **Step 2: 创建测试文件** - -```python -"""Tests for Context class""" - -import pytest -import sqlite3 -from pathlib import Path -from pt_snap_analyzer.context import Context, DatabaseNotFoundError, SchemaVersionError - - -def test_context_open_database(tmp_path): - """Test opening valid database""" - db_path = tmp_path / "test.db" - conn = sqlite3.connect(str(db_path)) - cursor = conn.cursor() - cursor.execute(""" - CREATE TABLE dictionary ( - table TEXT, column TEXT, key TEXT, value TEXT - ) - """) - conn.commit() - conn.close() - - with Context(str(db_path)) as ctx: - assert ctx.db_path == str(db_path) - assert ctx.devices is None - assert ctx.device_ids == [] - - -def test_context_database_not_found(): - """Test error when database not found""" - with pytest.raises(DatabaseNotFoundError): - Context("/nonexistent/path/db.db") - - -def test_context_invalid_file(tmp_path): - """Test error when path is not a file""" - dir_path = tmp_path / "not_a_file" - dir_path.mkdir() - with pytest.raises(DatabaseNotFoundError): - Context(str(dir_path)) - - -def test_context_schema_validation(tmp_path): - """Test schema validation""" - db_path = tmp_path / "test.db" - conn = sqlite3.connect(str(db_path)) - conn.execute("CREATE TABLE test (id INTEGER)") - conn.commit() - conn.close() - - with pytest.raises(SchemaVersionError): - Context(str(db_path)) - - -def test_context_device_filtering(tmp_path): - """Test device ID filtering""" - db_path = tmp_path / "test.db" - conn = sqlite3.connect(str(db_path)) - cursor = conn.cursor() - cursor.execute(""" - CREATE TABLE dictionary ( - table TEXT, column TEXT, key TEXT, value TEXT - ) - """) - cursor.execute(""" - CREATE TABLE block_0 (id INTEGER PRIMARY KEY) - """) - cursor.execute(""" - CREATE TABLE block_1 (id INTEGER PRIMARY KEY) - """) - cursor.execute(""" - CREATE TABLE block_2 (id INTEGER PRIMARY KEY) - """) - conn.commit() - conn.close() - - ctx = Context(str(db_path), devices=[0, 2]) - assert ctx.device_ids == [0, 2] - - -def test_context_connect_context_manager(tmp_path): - """Test connect() context manager""" - db_path = tmp_path / "test.db" - conn = sqlite3.connect(str(db_path)) - cursor = conn.cursor() - cursor.execute(""" - CREATE TABLE dictionary ( - table TEXT, column TEXT, key TEXT, value TEXT - ) - """) - conn.commit() - conn.close() - - with Context(str(db_path)) as ctx: - with ctx.connect() as connection: - assert isinstance(connection, sqlite3.Connection) - cursor = connection.cursor() - cursor.execute("SELECT name FROM sqlite_master WHERE type='table'") - tables = cursor.fetchall() - assert len(tables) >= 1 -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_context.py -v -``` - -Expected: 6 tests PASS - -- [ ] **Step 4: Commit** - -```bash -git add pt_snap_analyzer/context.py tests/test_context.py -git commit -m "feat: add Context class for database management" -``` - ---- - -### Task 5: CLI 框架 - 命令结构 - -**Files:** -- Create: `pt_snap_analyzer/cli.py` -- Modify: `tests/test_cli.py` - -- [ ] **Step 1: 创建 CLI 入口** - -```python -"""CLI entry point for pt-snap-analyzer""" - -import typer -from typing_extensions import Annotated - -app = typer.Typer( - name="pt-snap", - help="AI-friendly PyTorch Memory Snapshot Analyzer", - no_args_is_help=True, -) - - -@app.command() -def use( - db_path: Annotated[ - str, typer.Argument(help="Path to SQLite database") - ], -): - """Set current database for analysis""" - from pt_snap_analyzer.context import Context, DatabaseNotFoundError - - try: - ctx = Context(db_path) - print(f"Using database: {db_path}") - ctx.close() - except DatabaseNotFoundError as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - - -@app.command() -def config( - device: Annotated[ - list[int], typer.Option(help="Device IDs to analyze (repeat for multiple)") - ] = [], -): - """Configure analysis settings""" - print(f"Device filter: {device if device else 'all'}") - - -@app.command() -def version(): - """Show version information""" - from pt_snap_analyzer.version import __version__ - print(f"pt-snap-analyzer v{__version__}") - - -@app.command() -def analyze(): - """Memory analysis commands""" - raise typer.Exit(code=1) - - -@app.command() -def query(): - """Query management commands""" - raise typer.Exit(code=1) - - -@app.command() -def rag(): - """RAG knowledge base commands""" - raise typer.Exit(code=1) - - -@app.command() -def compare(): - """Compare two databases""" - raise typer.Exit(code=1) - - -if __name__ == "__main__": - app() -``` - -- [ ] **Step 2: 创建 CLI 测试文件** - -```python -"""Tests for CLI commands""" - -from click.testing import CliRunner -from pt_snap_analyzer.cli import app - - -def test_version(): - """Test version command""" - runner = CliRunner() - result = runner.invoke(app, ["version"]) - assert result.exit_code == 0 - assert "pt-snap-analyzer v" in result.output - - -def test_use_command(): - """Test use command with valid database""" - runner = CliRunner() - result = runner.invoke(app, ["use", "examples/snapshot_expandable.pkl.db"]) - assert result.exit_code == 0 - assert "Using database:" in result.output - - -def test_use_command_invalid(): - """Test use command with invalid database""" - runner = CliRunner() - result = runner.invoke(app, ["use", "/nonexistent/path.db"]) - assert result.exit_code == 1 - assert "Error:" in result.output - - -def test_config_command(): - """Test config command""" - runner = CliRunner() - result = runner.invoke(app, ["config", "--device", "0", "--device", "1"]) - assert result.exit_code == 0 - assert "Device filter:" in result.output - - -def test_analyze_command(): - """Test analyze command (no subcommand)""" - runner = CliRunner() - result = runner.invoke(app, ["analyze"]) - assert result.exit_code == 1 - - -def test_help(): - """Test help output""" - runner = CliRunner() - result = runner.invoke(app, ["--help"]) - assert result.exit_code == 0 - assert "AI-friendly PyTorch Memory Snapshot Analyzer" in result.output -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_cli.py -v -``` - -Expected: 7 tests PASS - -- [ ] **Step 4: Commit** - -```bash -git add pt_snap_analyzer/cli.py tests/test_cli.py -git commit -m "feat: add CLI framework with subcommands" -``` - ---- - -### Task 6: 安装和验收测试 - -**Files:** -- Modify: `pyproject.toml` → add entry point -- Create: `tests/test_integration.py` - -- [ ] **Step 1: 验证 entry point** - -确保 `pyproject.toml` 包含: -```toml -[project.scripts] -pt-snap = "pt_snap_analyzer.cli:app" -``` - -- [ ] **Step 2: 创建集成测试** - -```python -"""Integration tests for pt-snap-analyzer""" - -import subprocess -import tempfile -import sqlite3 -from pathlib import Path - - -def test_cli_command(): - """Test CLI command installation""" - result = subprocess.run( - ["pt-snap", "--help"], - capture_output=True, - text=True - ) - assert result.returncode == 0 - assert "AI-friendly PyTorch Memory Snapshot Analyzer" in result.stdout - - -def test_version_command(): - """Test version command""" - result = subprocess.run( - ["pt-snap", "version"], - capture_output=True, - text=True - ) - assert result.returncode == 0 - assert "v0.1.0" in result.output - - -def test_use_command_integration(): - """Test use command with real database""" - with tempfile.TemporaryDirectory() as tmpdir: - db_path = Path(tmpdir) / "test.db" - conn = sqlite3.connect(str(db_path)) - cursor = conn.cursor() - cursor.execute(""" - CREATE TABLE dictionary ( - table TEXT, column TEXT, key TEXT, value TEXT - ) - """) - conn.commit() - conn.close() - - result = subprocess.run( - ["pt-snap", "use", str(db_path)], - capture_output=True, - text=True - ) - assert result.returncode == 0 - assert "Using database:" in result.stdout - - -def test_sdk_import(): - """Test SDK can be imported""" - from pt_snap_analyzer import Context, MemoryEvent, MemoryBlock, __version__ - assert __version__ == "0.1.0" - assert Context is not None - assert MemoryEvent is not None - assert MemoryBlock is not None -``` - -- [ ] **Step 3: Run all tests** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - -Expected: All tests PASS (15+ tests) - -- [ ] **Step 4: Commit** - -```bash -git add tests/test_integration.py -git commit -m "test: add integration tests for CLI and SDK" -``` - ---- - -### 最终验收清单 - -- [ ] 所有测试通过 (15+ tests) -- [ ] CLI 命令 `pt-snap --help` 正常工作 -- [ ] `pt-snap version` 输出正确版本 -- [ ] `pt-snap use ` 可以打开数据库 -- [ ] SDK 可以正常导入: `from pt_snap_analyzer import Context, MemoryEvent, MemoryBlock` -- [ ] 数据模型包含所有字段和属性 -- [ ] Context 正确管理数据库连接 -- [ ] pytest 覆盖率 > 80% - ---- - -## 执行意见 - -Plan complete and saved to `docs/superpowers/plans/2026-04-04-pt-snap-analyzer-foundation.md`. Two execution options: - -**1. Subagent-Driven (recommended)** - 我分发每个任务的独立 subagent,任务间审查,快速迭代 - -**2. Inline Execution** - 在此会话中执行任务,使用 executing-plans,批次执行加检查点 - -**Which approach?** diff --git a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-query.md b/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-query.md deleted file mode 100644 index 2901f30..0000000 --- a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-query.md +++ /dev/null @@ -1,1188 +0,0 @@ -# pt-snap-analyzer 查询系统计划 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** 实现查询配置系统,支持 YAML 配置的 SQL 模板和查询执行器 - -**Architecture:** YAML 配置存储 SQL 模板,查询执行器渲染模板并执行查询,支持参数替换和设备适配 - -**Tech Stack:** Python 3.10+, SQLite3, PyYAML, Jinja2 - ---- - -## 文件结构 - -``` -pt-snap-cli/ -├── pt_snap_analyzer/ -│ ├── query/ -│ │ ├── __init__.py -│ │ ├── executor.py # 查询执行器 -│ │ ├── config.py # YAML 配置管理 -│ │ └── templates/ # 预定义 SQL 模板 -│ │ ├── leak_detection_v2.yaml -│ │ ├── memory_timeline_v2.yaml -│ │ └── callstack_analysis_v2.yaml -│ └── cli.py # 添加查询命令 -└── tests/ - ├── test_query_config.py - ├── test_query_executor.py - └── test_query_cli.py -``` - ---- - -### Task 1: 查询配置系统 - -**Files:** -- Create: `pt_snap_analyzer/query/config.py` -- Create: `tests/test_query_config.py` - -- [ ] **Step 1: 创建配置数据模型** - -```python -"""Query configuration management""" - -from __future__ import annotations - -from dataclasses import dataclass -from typing import Any, Dict, List, Optional - - -@dataclass -class QueryParameter: - """Query parameter definition""" - - name: str - default: Any = None - type: str = "str" # 'str', 'int', 'float', 'bool' - description: str = "" - required: bool = False - - @property - def python_type(self) -> type: - """Get Python type from type string""" - type_map = { - "str": str, - "int": int, - "float": float, - "bool": bool, - } - return type_map.get(self.type, str) - - -@dataclass -class QueryTemplate: - """SQL query template""" - - name: str - description: str - devices: List[str] # ['all', '0', '1', ...] - parameters: Dict[str, QueryParameter] - query: str - output_schema: List[Dict[str, str]] - - -@dataclass -class QueryConfig: - """Query configuration""" - - version: str = "1.0" - queries: Dict[str, QueryTemplate] = None - - def __post_init__(self): - if self.queries is None: - self.queries = {} -``` - -- [ ] **Step 2: 创建配置加载器** - -```python -"""Query configuration management""" - -from __future__ import annotations - -import yaml -from pathlib import Path -from typing import Any, Dict, List, Optional - -from pt_snap_analyzer.query.config import ( - QueryConfig, - QueryTemplate, - QueryParameter, -) - - -class QueryConfigError(Exception): - """Raised when query configuration error occurs""" - pass - - -class QueryConfigLoader: - """Load and validate query configurations""" - - def __init__(self, config_dir: Optional[str] = None): - """Initialize loader - - Args: - config_dir: Directory containing query YAML files - """ - if config_dir is None: - home = Path.home() - self.config_dir = home / ".config" / "pt-snap-analyzer" / "queries" - else: - self.config_dir = Path(config_dir) - - self.queries: Dict[str, QueryTemplate] = {} - - def load_query(self, file_path: str) -> QueryTemplate: - """Load a single query from YAML file - - Args: - file_path: Path to YAML file - - Returns: - QueryTemplate instance - - Raises: - QueryConfigError: If validation fails - """ - path = Path(file_path) - if not path.exists(): - raise QueryConfigError(f"File not found: {file_path}") - - try: - with open(path, "r") as f: - data = yaml.safe_load(f) - except yaml.YAMLError as e: - raise QueryConfigError(f"Invalid YAML in {file_path}: {e}") - - return self._validate_query(data, file_path) - - def _validate_query(self, data: dict, source: str) -> QueryTemplate: - """Validate query data - - Args: - data: Parsed YAML data - source: Source file path - - Returns: - Validated QueryTemplate - - Raises: - QueryConfigError: If validation fails - """ - required_fields = ["name", "description", "devices", "query"] - for field in required_fields: - if field not in data: - raise QueryConfigError( - f"Missing required field '{field}' in {source}" - ) - - # Parse parameters - parameters = {} - params_data = data.get("parameters", {}) - for name, param_data in params_data.items(): - parameters[name] = QueryParameter( - name=name, - default=param_data.get("default"), - type=param_data.get("type", "str"), - description=param_data.get("description", ""), - required=param_data.get("required", False), - ) - - # Parse output schema - output_schema = [] - schema_data = data.get("output_schema", []) - for item in schema_data: - if isinstance(item, str): - output_schema.append({"name": item, "type": "any"}) - elif isinstance(item, dict): - output_schema.append(item) - - return QueryTemplate( - name=data["name"], - description=data["description"], - devices=data["devices"], - parameters=parameters, - query=data["query"], - output_schema=output_schema, - ) - - def load_all(self) -> Dict[str, QueryTemplate]: - """Load all queries from config directory - - Returns: - Dictionary of query name to QueryTemplate - """ - self.queries = {} - - if not self.config_dir.exists(): - return self.queries - - yaml_files = list(self.config_dir.glob("*.yaml")) - yaml_files.extend(self.config_dir.glob("*.yml")) - - for file_path in yaml_files: - try: - template = self.load_query(str(file_path)) - self.queries[template.name] = template - except QueryConfigError as e: - print(f"Warning: Failed to load {file_path}: {e}") - - return self.queries - - def get_query(self, name: str) -> Optional[QueryTemplate]: - """Get query template by name - - Args: - name: Query name - - Returns: - QueryTemplate or None if not found - """ - return self.queries.get(name) - - def list_queries(self) -> List[str]: - """List all query names - - Returns: - List of query names - """ - return list(self.queries.keys()) -``` - -- [ ] **Step 3: 创建测试文件** - -```python -"""Tests for query configuration system""" - -import pytest -import tempfile -import yaml -from pathlib import Path -from pt_snap_analyzer.query.config import ( - QueryConfigLoader, - QueryConfigError, - QueryParameter, - QueryTemplate, -) - - -def test_query_parameter(): - """Test QueryParameter dataclass""" - param = QueryParameter( - name="min_size", - default=1024, - type="int", - description="Minimum size in bytes", - ) - assert param.name == "min_size" - assert param.default == 1024 - assert param.python_type == int - - -def test_query_template(): - """Test QueryTemplate dataclass""" - template = QueryTemplate( - name="leak_detection", - description="Detect memory leaks", - devices=["0", "1"], - parameters={}, - query="SELECT * FROM block_0 WHERE freeEventId IS NULL", - output_schema=[{"name": "id", "type": "int"}], - ) - assert template.name == "leak_detection" - assert len(template.devices) == 2 - - -def test_loader_load_single_query(tmp_path): - """Test loading a single query""" - yaml_file = tmp_path / "test.yaml" - yaml_file.write_text(""" -name: test_query -description: Test query -devices: ["0"] -parameters: - limit: - type: int - default: 10 -query: | - SELECT * FROM block_0 - LIMIT {{ limit }} -output_schema: - - name: id - type: int - - name: address - type: int -""") - - loader = QueryConfigLoader(config_dir=str(tmp_path)) - template = loader.load_query(str(yaml_file)) - - assert template.name == "test_query" - assert template.description == "Test query" - assert template.devices == ["0"] - assert "limit" in template.parameters - assert template.parameters["limit"].default == 10 - - -def test_loader_missing_field(tmp_path): - """Test error on missing required field""" - yaml_file = tmp_path / "invalid.yaml" - yaml_file.write_text(""" -name: test_query -# Missing description, devices, and query -""") - - loader = QueryConfigLoader(config_dir=str(tmp_path)) - with pytest.raises(QueryConfigError) as exc_info: - loader.load_query(str(yaml_file)) - - assert "Missing required field" in str(exc_info.value) - - -def test_loader_invalid_yaml(tmp_path): - """Test error on invalid YAML""" - yaml_file = tmp_path / "invalid.yaml" - yaml_file.write_text(""" -name: test_query -invalid: yaml: syntax: [ -""") - - loader = QueryConfigLoader(config_dir=str(tmp_path)) - with pytest.raises(QueryConfigError) as exc_info: - loader.load_query(str(yaml_file)) - - assert "Invalid YAML" in str(exc_info.value) - - -def test_loader_load_all(tmp_path): - """Test loading all queries from directory""" - yaml_file1 = tmp_path / "query1.yaml" - yaml_file1.write_text(""" -name: leak_detection -description: Detect leaks -devices: ["0"] -query: SELECT * FROM block_0 WHERE freeEventId IS NULL -output_schema: [] -""") - - yaml_file2 = tmp_path / "query2.yaml" - yaml_file2.write_text(""" -name: peak_analysis -description: Analyze peaks -devices: ["0"] -query: SELECT * FROM trace_entry_0 ORDER BY size DESC -output_schema: [] -""") - - loader = QueryConfigLoader(config_dir=str(tmp_path)) - queries = loader.load_all() - - assert len(queries) == 2 - assert "leak_detection" in queries - assert "peak_analysis" in queries - - -def test_loader_nonexistent_file(): - """Test error on nonexistent file""" - loader = QueryConfigLoader() - with pytest.raises(QueryConfigError) as exc_info: - loader.load_query("/nonexistent/path.yaml") - - assert "File not found" in str(exc_info.value) -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_query_config.py -v -``` - -Expected: 6 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/query/config.py tests/test_query_config.py -git commit -m "feat: add query configuration loader" -``` - ---- - -### Task 2: 查询执行器 - -**Files:** -- Create: `pt_snap_analyzer/query/executor.py` -- Create: `tests/test_query_executor.py` - -- [ ] **Step 1: 创建执行器** - -```python -"""Query executor for rendered templates""" - -from __future__ import annotations - -import re -from typing import Any, Dict, List, Optional - -import yaml -from jinja2 import Template - -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.query.config import QueryTemplate - - -class QueryExecutionError(Exception): - """Raised when query execution fails""" - pass - - -class QueryExecutor: - """Execute rendered query templates""" - - def __init__(self, context: Context): - """Initialize executor - - Args: - context: Analysis context with database connection - """ - self.context = context - - def execute_template( - self, - template: QueryTemplate, - parameters: Optional[Dict[str, Any]] = None, - device_id: Optional[int] = None, - ) -> List[Dict[str, Any]]: - """Execute a query template - - Args: - template: QueryTemplate to execute - parameters: Parameter values for rendering - device_id: Device ID to use (None = first device) - - Returns: - List of result rows as dictionaries - - Raises: - QueryExecutionError: If execution fails - """ - if parameters is None: - parameters = {} - - # Build device-specific query - try: - rendered_query = self._render_template(template, parameters, device_id) - except Exception as e: - raise QueryExecutionError(f"Failed to render template: {e}") - - # Execute query - try: - cursor = self.context.cursor() - cursor.execute(rendered_query) - rows = cursor.fetchall() - - # Convert to list of dicts - columns = [desc[0] for desc in cursor.description or []] - results = [dict(zip(columns, row)) for row in rows] - - return results - except Exception as e: - raise QueryExecutionError(f"Query execution failed: {e}") - - def _render_template( - self, - template: QueryTemplate, - parameters: Dict[str, Any], - device_id: Optional[int] = None, - ) -> str: - """Render template with parameters and device - - Args: - template: QueryTemplate to render - parameters: Parameter values - device_id: Device ID to substitute - - Returns: - Rendered SQL query - """ - # Set default parameter values - for name, param in template.parameters.items(): - if name not in parameters: - if param.required: - raise ValueError(f"Required parameter '{name}' not provided") - parameters[name] = param.default - - # Render Jinja2 template - template_obj = Template(template.query) - rendered = template_obj.render(**parameters) - - # Substitute device placeholder - if device_id is not None: - rendered = self._substitute_device(rendered, device_id) - elif template.devices and template.devices != ["all"]: - # Use first device if not specified - rendered = self._substitute_device(rendered, int(template.devices[0])) - - return rendered - - def _substitute_device(self, query: str, device_id: int) -> str: - """Substitute device placeholders in query - - Args: - query: Rendered query - device_id: Device ID to substitute - - Returns: - Query with device placeholders replaced - """ - # Replace {device} with actual device ID - query = query.replace("{device}", str(device_id)) - query = query.replace("{deviceId}", str(device_id)) - query = query.replace("{device_id}", str(device_id)) - - # Handle table placeholders like {table}_device - pattern = r"(\w+)_\{device\}" - matches = re.findall(pattern, query) - for base_table in matches: - query = query.replace(f"{base_table}_{{device}}", f"{base_table}_{device_id}") - - return query - - def execute_name( - self, - name: str, - parameters: Optional[Dict[str, Any]] = None, - device_id: Optional[int] = None, - ) -> List[Dict[str, Any]]: - """Execute query by name - - Args: - name: Query template name - parameters: Parameter values - device_id: Device ID - - Returns: - Query results - """ - from pt_snap_analyzer.query.config import QueryConfigLoader - - loader = QueryConfigLoader() - loader.load_all() - - template = loader.get_query(name) - if template is None: - raise QueryExecutionError(f"Query not found: {name}") - - return self.execute_template(template, parameters, device_id) -``` - -- [ ] **Step 2: 创建测试文件** - -```python -"""Tests for query executor""" - -import pytest -from unittest.mock import MagicMock -from pt_snap_analyzer.query.executor import QueryExecutor, QueryExecutionError - - -def test_executor_execute_template(mock_context): - """Test executing query template""" - from pt_snap_analyzer.query.config import QueryTemplate - - template = QueryTemplate( - name="test_query", - description="Test query", - devices=["0"], - parameters={}, - query="SELECT * FROM block_0", - output_schema=[], - ) - - mock_cursor = MagicMock() - mock_cursor.fetchall.return_value = [(1, 0x1000), (2, 0x2000)] - mock_cursor.description = [("id",), ("address",)] - mock_context.cursor.return_value = mock_cursor - - executor = QueryExecutor(context=mock_context) - results = executor.execute_template(template) - - assert len(results) == 2 - assert results[0]["id"] == 1 - assert results[0]["address"] == 0x1000 - - -def test_executor_execute_template_with_params(mock_context): - """Test executing query with parameters""" - from pt_snap_analyzer.query.config import QueryTemplate - - template = QueryTemplate( - name="test_query", - description="Test query", - devices=["0"], - parameters={ - "limit": type("Param", (), {"default": 10, "required": False})() - }, - query="SELECT * FROM block_0 LIMIT {{ limit }}", - output_schema=[], - ) - - mock_cursor = MagicMock() - mock_cursor.fetchall.return_value = [(1, 0x1000)] - mock_cursor.description = [("id",), ("address",)] - mock_context.cursor.return_value = mock_cursor - - executor = QueryExecutor(context=mock_context) - results = executor.execute_template(template, parameters={"limit": 5}) - - mock_cursor.execute.assert_called_once_with("SELECT * FROM block_0 LIMIT 5") - assert len(results) == 1 - - -def test_executor_execute_template_missing_param(mock_context): - """Test error on missing required parameter""" - from pt_snap_analyzer.query.config import QueryTemplate - - template = QueryTemplate( - name="test_query", - description="Test query", - devices=["0"], - parameters={ - "min_size": type("Param", (), {"default": None, "required": True})() - }, - query="SELECT * FROM block_0 WHERE size >= {{ min_size }}", - output_schema=[], - ) - - mock_cursor = MagicMock() - mock_context.cursor.return_value = mock_cursor - - executor = QueryExecutor(context=mock_context) - - with pytest.raises(ValueError) as exc_info: - executor.execute_template(template) - - assert "Required parameter" in str(exc_info.value) - - -def test_executor_execute_name(mock_context): - """Test executing query by name""" - mock_cursor = MagicMock() - mock_cursor.fetchall.return_value = [(1, 0x1000)] - mock_cursor.description = [("id",), ("address",)] - mock_context.cursor.return_value = mock_cursor - - executor = QueryExecutor(context=mock_context) - - # Mock QueryConfigLoader - from unittest.mock import patch - mock_loader = MagicMock() - mock_loader.get_query.return_value = None - mock_loader.load_all.return_value = {} - - with patch("pt_snap_analyzer.query.executor.QueryConfigLoader", return_value=mock_loader): - with pytest.raises(QueryExecutionError) as exc_info: - executor.execute_name("nonexistent_query") - - assert "Query not found" in str(exc_info.value) -``` - -- [ ] **Step 3: 创建测试辅助函数** - -在 `tests/conftest.py` (create if not exists): - -```python -"""Test fixtures and utilities""" - -import pytest -from unittest.mock import MagicMock - - -@pytest.fixture -def mock_context(): - """Mock Context for testing""" - context = MagicMock() - context.device_ids = [0] - return context - - -@pytest.fixture -def example_query_config(tmp_path): - """Create example query configuration""" - queries_dir = tmp_path / "queries" - queries_dir.mkdir() - - (queries_dir / "leak_detection.yaml").write_text(""" -name: leak_detection_v2 -description: Memory leak detection v2 -devices: ["all"] -parameters: - min_size: - type: int - default: 1024 - description: Minimum leak size in bytes -query: | - SELECT b.id, b.address, b.size, t.callstack - FROM block_{device} b - LEFT JOIN trace_entry_{device} t ON b.allocEventId = t.id - WHERE b.id >= 0 AND b.freeEventId IS NULL - ORDER BY b.size DESC -output_schema: - - block_id: int - - address: int - - size: int - - callstack: str -""") - - return queries_dir -``` - -- [ ] **Step 4: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_query_executor.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/query/executor.py tests/test_query_executor.py tests/conftest.py -git commit -m "feat: add query executor" -``` - ---- - -### Task 3: 预定义 SQL 模板 - -**Files:** -- Create: `pt_snap_analyzer/query/templates/` -- Create: `tests/test_predefined_queries.py` - -- [ ] **Step 1: 创建 leak_detection_v2.yaml** - -```yaml -name: leak_detection_v2 -description: 内存泄漏检测 v2 - 找出未释放的内存块 -devices: ["all"] -parameters: - min_size: - type: int - default: 1024 - description: 最小泄漏块大小(字节) -query: | - SELECT - b.id as block_id, - b.address, - b.size, - b.requestedSize, - t.callstack - FROM block_{device} b - LEFT JOIN trace_entry_{device} t ON b.allocEventId = t.id - WHERE - b.id >= 0 - AND (b.freeEventId IS NULL OR b.freeEventId = -1) - AND b.size >= {{ min_size }} - ORDER BY b.size DESC -output_schema: - - name: block_id - type: int - - name: address - type: int - - name: size - type: int - - name: requestedSize - type: int - - name: callstack - type: str -``` - -- [ ] **Step 2: 创建 memory_timeline_v2.yaml** - -```yaml -name: memory_timeline_v2 -description: 内存使用时间线 - 按时间顺序查看内存使用情况 -devices: ["all"] -parameters: - start_id: - type: int - default: 0 - description: 起始事件 ID - end_id: - type: int - default: -1 - description: 结束事件 ID (-1 表示最后) - interval: - type: int - default: 1000 - description: 采样间隔(事件数) -query: | - SELECT - id, - allocated, - active, - reserved - FROM trace_entry_{device} - WHERE - id >= {{ start_id }} - AND ({{ end_id }} = -1 OR id <= {{ end_id }}) - AND (id - {{ start_id }}) % {{ interval }} = 0 - ORDER BY id ASC -output_schema: - - name: id - type: int - - name: allocated - type: int - - name: active - type: int - - name: reserved - type: int -``` - -- [ ] **Step 3: 创建 callstack_analysis_v2.yaml** - -```yaml -name: callstack_analysis_v2 -description: 调用栈分析 - 统计调用栈模式 -devices: ["all"] -parameters: - top_k: - type: int - default: 10 - description: 返回 Top-K 调用栈 - min_count: - type: int - default: 1 - description: 最少出现次数 -query: | - WITH callstack_stats AS ( - SELECT - callstack, - COUNT(*) as count, - SUM(size) as total_size - FROM trace_entry_{device} - WHERE callstack IS NOT NULL AND callstack != '' - GROUP BY callstack - HAVING COUNT(*) >= {{ min_count }} - ) - SELECT - callstack, - count, - total_size, - ROUND(CAST(total_size AS REAL) / count, 2) as avg_size - FROM callstack_stats - ORDER BY count DESC - LIMIT {{ top_k }} -output_schema: - - name: callstack - type: str - - name: count - type: int - - name: total_size - type: int - - name: avg_size - type: float -``` - -- [ ] **Step 4: 创建测试文件** - -```python -"""Tests for predefined query templates""" - -import pytest -from pathlib import Path -from pt_snap_analyzer.query.config import QueryConfigLoader - - -def test_load_leak_detection(): - """Test loading leak_detection_v2.yaml""" - loader = QueryConfigLoader() - - queries_dir = Path(__file__).parent.parent / "pt_snap_analyzer" / "query" / "templates" - - yaml_files = list(queries_dir.glob("*.yaml")) - assert len(yaml_files) > 0, "No YAML files found in templates directory" - - # Check leak_detection_v2.yaml exists - leak_file = queries_dir / "leak_detection_v2.yaml" - assert leak_file.exists(), "leak_detection_v2.yaml not found" - - template = loader.load_query(str(leak_file)) - assert template.name == "leak_detection_v2" - assert "memory leak" in template.description.lower() - - -def test_load_memory_timeline(): - """Test loading memory_timeline_v2.yaml""" - loader = QueryConfigLoader() - - queries_dir = Path(__file__).parent.parent / "pt_snap_analyzer" / "query" / "templates" - timeline_file = queries_dir / "memory_timeline_v2.yaml" - - assert timeline_file.exists(), "memory_timeline_v2.yaml not found" - - template = loader.load_query(str(timeline_file)) - assert template.name == "memory_timeline_v2" - assert "timeline" in template.description.lower() - - -def test_load_callstack_analysis(): - """Test loading callstack_analysis_v2.yaml""" - loader = QueryConfigLoader() - - queries_dir = Path(__file__).parent.parent / "pt_snap_analyzer" / "query" / "templates" - stack_file = queries_dir / "callstack_analysis_v2.yaml" - - assert stack_file.exists(), "callstack_analysis_v2.yaml not found" - - template = loader.load_query(str(stack_file)) - assert template.name == "callstack_analysis_v2" - assert "callstack" in template.description.lower() - - -def test_template_parameters(): - """Test template parameters are correctly parsed""" - loader = QueryConfigLoader() - - queries_dir = Path(__file__).parent.parent / "pt_snap_analyzer" / "query" / "templates" - - # Test leak_detection - leak_file = queries_dir / "leak_detection_v2.yaml" - template = loader.load_query(str(leak_file)) - - assert "min_size" in template.parameters - assert template.parameters["min_size"].default == 1024 - assert template.parameters["min_size"].type == "int" - - # Test memory_timeline - timeline_file = queries_dir / "memory_timeline_v2.yaml" - template = loader.load_query(str(timeline_file)) - - assert "start_id" in template.parameters - assert template.parameters["start_id"].default == 0 - - # Test callstack_analysis - stack_file = queries_dir / "callstack_analysis_v2.yaml" - template = loader.load_query(str(stack_file)) - - assert "top_k" in template.parameters - assert template.parameters["top_k"].default == 10 -``` - -- [ ] **Step 5: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_predefined_queries.py -v -``` - -Expected: 5 tests PASS - -- [ ] **Step 6: Commit** - -```bash -git add pt_snap_analyzer/query/templates/ -git commit -m "feat: add predefined SQL query templates" -``` - ---- - -### Task 4: CLI 集成 - -**Files:** -- Modify: `pt_snap_analyzer/cli.py` -- Create: `tests/test_query_cli.py` - -- [ ] **Step 1: 添加 query 命令到 CLI** - -```python -# Add after imports at top of cli.py -from pt_snap_analyzer.query.config import QueryConfigLoader, QueryConfigError -from pt_snap_analyzer.query.executor import QueryExecutor, QueryExecutionError - - -@app.command() -def query(): - """Query management commands""" - raise typer.Exit(code=1) - - -@app.command() -def query_list( - format: Annotated[ - str, typer.Option("--format", help="Output format: json | table") - ] = "table", -): - """List available query templates""" - loader = QueryConfigLoader() - loader.load_all() - - queries = loader.list_queries() - - if format == "json": - import json - result = {"queries": [{"name": q} for q in queries]} - print(json.dumps(result, indent=2)) - else: # table - print("Available Queries:") - print("-" * 40) - for name in queries: - template = loader.get_query(name) - if template: - print(f" {name}") - print(f" {template.description}") - - -@app.command() -def query_exec( - name: Annotated[str, typer.Argument(help="Query name")], - param: Annotated[ - List[str], typer.Option("--param", help="Parameter key=value") - ] = [], - json_output: Annotated[ - bool, typer.Option("--json", help="Output in JSON format") - ] = False, -): - """Execute a predefined query""" - db_path = _get_current_db() - if db_path is None: - print("Error: No database selected. Use 'pt-snap use ' first.", flush=True) - raise typer.Exit(code=1) - - try: - with Context(db_path) as ctx: - # Parse parameters - parameters = {} - for p in param: - if "=" not in p: - print(f"Error: Invalid parameter format: {p} (expected key=value)", flush=True) - raise typer.Exit(code=1) - key, value = p.split("=", 1) - try: - # Try to convert to int - parameters[key] = int(value) - except ValueError: - parameters[key] = value - - # Execute query - executor = QueryExecutor(ctx) - results = executor.execute_name(name, parameters) - - if json_output: - import json - print(json.dumps(results, indent=2, default=str)) - else: - # Print as table - if results: - # Print headers - headers = list(results[0].keys()) - print(" | ".join(headers)) - print("-" * (sum(len(h) for h in headers) + len(headers) * 3)) - - # Print rows - for row in results: - values = [str(row[h]) for h in headers] - print(" | ".join(values)) - else: - print("No results") - - except QueryExecutionError as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) -``` - -- [ ] **Step 2: 创建 CLI 测试** - -```python -"""Tests for query CLI commands""" - -from click.testing import CliRunner -from pt_snap_analyzer.cli import app - - -def test_query_list(): - """Test query-list command""" - runner = CliRunner() - result = runner.invoke(app, ["query-list"]) - # Should succeed even without database - assert result.exit_code == 0 - - -def test_query_exec_without_db(): - """Test query-exec without database""" - runner = CliRunner() - result = runner.invoke(app, ["query-exec", "leak_detection_v2"]) - # Should fail because no database - assert result.exit_code != 0 - - -def test_query_exec_with_param(): - """Test query-exec with parameters""" - runner = CliRunner() - result = runner.invoke(app, [ - "query-exec", "leak_detection_v2", - "--param", "min_size=4096", - "--json" - ]) - # Should fail because no database, but parameter parsing should work - assert result.exit_code != 0 - - -def test_help_includes_query(): - """Test help includes query commands""" - runner = CliRunner() - result = runner.invoke(app, ["--help"]) - assert result.exit_code == 0 - assert "query" in result.output.lower() -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_query_cli.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 4: Run full test suite** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - -Expected: 25+ tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/cli.py tests/test_query_cli.py -git commit -m "feat: integrate queries into CLI" -``` - ---- - -### 最终验收清单 - -- [ ] 所有测试通过 (25+ tests) -- [ ] QueryConfigLoader 可以加载 YAML 配置 -- [ ] QueryExecutor 可以渲染和执行查询 -- [ ] 参数替换正确工作 -- [ ] 设备 ID 替换正确工作 -- [ ] CLI 命令正常工作 -- [ ] JSON 和表格输出都正常 -- [ ] pytest 覆盖率 > 80% - ---- - -## 执行意见 - -Plan complete and saved to `docs/superpowers/plans/2026-04-04-pt-snap-analyzer-query.md`. Two execution options: - -**1. Subagent-Driven (recommended)** - 我分发每个任务的独立 subagent,任务间审查,快速迭代 - -**2. Inline Execution** - 在此会话中执行任务,使用 executing-plans,批次执行加检查点 - -**Which approach?** diff --git a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-rag.md b/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-rag.md deleted file mode 100644 index 685db45..0000000 --- a/.agents/superpowers/plans/2026-04-04-pt-snap-analyzer-rag.md +++ /dev/null @@ -1,1391 +0,0 @@ -# pt-snap-analyzer RAG 知识库计划 - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** 实现 RAG 知识库,支持案例归档、向量搜索和相似案例检索 - -**Architecture:** 使用 ChromaDB 存储向量,简单的关键词搜索作为备用,CLI 和 SDK 双接口 - -**Tech Stack:** Python 3.10+, ChromaDB, LangChain(可选) - ---- - -## 文件结构 - -``` -pt-snap-cli/ -├── pt_snap_analyzer/ -│ ├── rag/ -│ │ ├── __init__.py -│ │ ├── models.py # RAG 数据模型 -│ │ ├── archive.py # 案例归档 -│ │ └── searcher.py # 案例检索 -│ └── cli.py # 添加 rag 命令 -└── tests/ - ├── test_rag_models.py - ├── test_rag_archive.py - ├── test_rag_searcher.py - └── test_rag_cli.py -``` - ---- - -### Task 1: RAG 数据模型 - -**Files:** -- Create: `pt_snap_analyzer/rag/models.py` -- Create: `tests/test_rag_models.py` - -- [ ] **Step 1: 创建数据模型** - -```python -"""RAG knowledge base data models""" - -from __future__ import annotations - -from dataclasses import dataclass, field -from datetime import datetime -from typing import Any, Dict, List, Optional -from uuid import uuid4 - - -@dataclass -class AnalysisStep: - """A step in the analysis process""" - - step: int - command: str - parameters: Dict[str, Any] = field(default_factory=dict) - result_summary: str = "" - description: str = "" - - -@dataclass -class RAGCase: - """A case in the RAG knowledge base - - Attributes: - case_id: Unique case identifier - timestamp: When the case was created - db_snapshot: Path to the snapshot database - analysis_steps: List of analysis steps - conclusion: Final conclusion - root_cause: Root cause analysis - solution: Solution or workaround - tags: List of tags for filtering - confidence: Confidence level (0-1) - verified_by: Who verified the case - """ - case_id: str = "" - timestamp: str = "" - db_snapshot: str = "" - analysis_steps: List[AnalysisStep] = field(default_factory=list) - conclusion: str = "" - root_cause: str = "" - solution: str = "" - tags: List[str] = field(default_factory=list) - confidence: float = 0.0 - verified_by: str = "unverified" - metadata: Dict[str, Any] = field(default_factory=dict) - - def __post_init__(self): - if not self.case_id: - self.case_id = str(uuid4()) - if not self.timestamp: - self.timestamp = datetime.utcnow().isoformat() + "Z" - - -@dataclass -class SearchMatch: - """A matched case from search - - Attributes: - case: The matched case - score: Relevance score (0-1) - query_match: Which query terms matched - """ - case: RAGCase - score: float = 0.0 - query_match: List[str] = field(default_factory=list) - - -@dataclass -class SearchResult: - """Result of RAG search - - Attributes: - matches: List of matched cases - total_results: Total number of matches - query: Original search query - """ - matches: List[SearchMatch] = field(default_factory=list) - total_results: int = 0 - query: str = "" -``` - -- [ ] **Step 2: 创建测试文件** - -```python -"""Tests for RAG data models""" - -import pytest -from datetime import datetime -from pt_snap_analyzer.rag.models import ( - AnalysisStep, - RAGCase, - SearchMatch, - SearchResult, -) - - -def test_analysis_step(): - """Test AnalysisStep dataclass""" - step = AnalysisStep( - step=1, - command="leak-detection", - parameters={"min_size": 1024}, - result_summary="Found 5 leaks", - description="Detect memory leaks", - ) - assert step.step == 1 - assert step.command == "leak-detection" - assert step.parameters == {"min_size": 1024} - - -def test_rag_case_defaults(): - """Test RAGCase with defaults""" - case = RAGCase( - conclusion="Memory leak in attention layer", - root_cause="Cache not released", - solution="Upgrade transformers", - tags=["memory-leak", "transformer"], - ) - - assert case.case_id != "" - assert case.timestamp != "" - assert len(case.case_id) > 0 - - -def test_rag_case_with_steps(): - """Test RAGCase with analysis steps""" - steps = [ - AnalysisStep( - step=1, - command="leak-detection", - parameters={"min_size": 1024}, - result_summary="Found 5 leaks", - ), - AnalysisStep( - step=2, - command="peak-analysis", - parameters={"top_k": 10}, - result_summary="Peak at epoch 100", - ), - ] - - case = RAGCase( - conclusion="Leak from large allocations", - root_cause="Not freed after epoch", - solution="Manual cleanup", - tags=["memory-leak"], - analysis_steps=steps, - ) - - assert len(case.analysis_steps) == 2 - assert case.analysis_steps[0].command == "leak-detection" - - -def test_rag_case_serialization(): - """Test RAGCase to dict""" - case = RAGCase( - case_id="test-123", - timestamp="2024-01-01T00:00:00Z", - conclusion="Test conclusion", - root_cause="Test cause", - solution="Test solution", - tags=["tag1", "tag2"], - ) - - case_dict = { - "case_id": case.case_id, - "timestamp": case.timestamp, - "conclusion": case.conclusion, - "root_cause": case.root_cause, - "solution": case.solution, - "tags": case.tags, - } - - assert case_dict["case_id"] == "test-123" - assert len(case_dict["tags"]) == 2 - - -def test_search_match(): - """Test SearchMatch dataclass""" - case = RAGCase( - case_id="test-123", - conclusion="Test conclusion", - ) - - match = SearchMatch( - case=case, - score=0.85, - query_match=["memory", "leak"], - ) - - assert match.case == case - assert match.score == 0.85 - assert match.query_match == ["memory", "leak"] - - -def test_search_result(): - """Test SearchResult dataclass""" - case = RAGCase( - case_id="test-123", - conclusion="Test conclusion", - ) - match = SearchMatch(case=case, score=0.85) - - result = SearchResult( - matches=[match], - total_results=1, - query="memory leak", - ) - - assert len(result.matches) == 1 - assert result.total_results == 1 - assert result.query == "memory leak" -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_rag_models.py -v -``` - -Expected: 7 tests PASS - -- [ ] **Step 4: Commit** - -```bash -git add pt_snap_analyzer/rag/models.py tests/test_rag_models.py -git commit -m "feat: add RAG data models" -``` - ---- - -### Task 2: 案例归档系统 - -**Files:** -- Create: `pt_snap_analyzer/rag/archive.py` -- Create: `tests/test_rag_archive.py` - -- [ ] **Step 1: 创建归档器** - -```python -"""Case archive for RAG knowledge base""" - -from __future__ import annotations - -import json -import os -from pathlib import Path -from typing import Any, Dict, List, Optional - -import yaml - -from pt_snap_analyzer.rag.models import RAGCase - - -class ArchiveError(Exception): - """Raised when archive operations fail""" - pass - - -class CaseArchive: - """Archive and manage RAG cases - - Attributes: - archive_dir: Directory for storing case files - """ - - def __init__(self, archive_dir: Optional[str] = None): - """Initialize archive - - Args: - archive_dir: Directory for storing cases - """ - if archive_dir is None: - home = Path.home() - self.archive_dir = home / ".local" / "share" / "pt-snap-analyzer" / "rag_archive" - else: - self.archive_dir = Path(archive_dir) - - self.archive_dir.mkdir(parents=True, exist_ok=True) - - def add_case(self, case: RAGCase) -> str: - """Add a case to the archive - - Args: - case: RAGCase to add - - Returns: - Case ID - - Raises: - ArchiveError: If save fails - """ - case_id = case.case_id - - # Validate required fields - if not case.conclusion: - raise ArchiveError("Case must have a conclusion") - if not case.solution: - raise ArchiveError("Case must have a solution") - - # Serialize case - case_dict = self._case_to_dict(case) - - # Save to file - file_path = self.archive_dir / f"{case_id}.json" - try: - with open(file_path, "w") as f: - json.dump(case_dict, f, indent=2) - except Exception as e: - raise ArchiveError(f"Failed to save case: {e}") - - return case_id - - def get_case(self, case_id: str) -> Optional[RAGCase]: - """Get a case by ID - - Args: - case_id: Case identifier - - Returns: - RAGCase or None if not found - """ - file_path = self.archive_dir / f"{case_id}.json" - - if not file_path.exists(): - return None - - try: - with open(file_path, "r") as f: - case_dict = json.load(f) - return self._dict_to_case(case_dict) - except Exception as e: - print(f"Warning: Failed to load case {case_id}: {e}") - return None - - def list_cases(self, tags: Optional[List[str]] = None) -> List[RAGCase]: - """List all cases, optionally filtered by tags - - Args: - tags: List of tags to filter by - - Returns: - List of RAGCases - """ - cases = [] - - for file_path in self.archive_dir.glob("*.json"): - try: - case = self.get_case(file_path.stem) - if case is not None: - if tags is None: - cases.append(case) - else: - # Filter by tags (AND logic) - if all(t in case.tags for t in tags): - cases.append(case) - except Exception as e: - print(f"Warning: Failed to process {file_path}: {e}") - continue - - # Sort by timestamp - cases.sort(key=lambda c: c.timestamp, reverse=True) - return cases - - def delete_case(self, case_id: str) -> bool: - """Delete a case from the archive - - Args: - case_id: Case identifier - - Returns: - True if deleted, False if not found - """ - file_path = self.archive_dir / f"{case_id}.json" - - if not file_path.exists(): - return False - - try: - file_path.unlink() - return True - except Exception as e: - print(f"Warning: Failed to delete case {case_id}: {e}") - return False - - def _case_to_dict(self, case: RAGCase) -> Dict[str, Any]: - """Convert RAGCase to dictionary - - Args: - case: RAGCase to convert - - Returns: - Dictionary representation - """ - return { - "case_id": case.case_id, - "timestamp": case.timestamp, - "db_snapshot": case.db_snapshot, - "analysis_steps": [ - { - "step": s.step, - "command": s.command, - "parameters": s.parameters, - "result_summary": s.result_summary, - "description": s.description, - } - for s in case.analysis_steps - ], - "conclusion": case.conclusion, - "root_cause": case.root_cause, - "solution": case.solution, - "tags": case.tags, - "confidence": case.confidence, - "verified_by": case.verified_by, - "metadata": case.metadata, - } - - def _dict_to_case(self, case_dict: Dict[str, Any]) -> RAGCase: - """Convert dictionary to RAGCase - - Args: - case_dict: Dictionary representation - - Returns: - RAGCase instance - """ - analysis_steps = [ - AnalysisStep( - step=s["step"], - command=s["command"], - parameters=s.get("parameters", {}), - result_summary=s.get("result_summary", ""), - description=s.get("description", ""), - ) - for s in case_dict.get("analysis_steps", []) - ] - - return RAGCase( - case_id=case_dict.get("case_id", ""), - timestamp=case_dict.get("timestamp", ""), - db_snapshot=case_dict.get("db_snapshot", ""), - analysis_steps=analysis_steps, - conclusion=case_dict.get("conclusion", ""), - root_cause=case_dict.get("root_cause", ""), - solution=case_dict.get("solution", ""), - tags=case_dict.get("tags", []), - confidence=case_dict.get("confidence", 0.0), - verified_by=case_dict.get("verified_by", "unverified"), - metadata=case_dict.get("metadata", {}), - ) -``` - -- [ ] **Step 2: 创建测试文件** - -```python -"""Tests for case archive""" - -import pytest -import json -from pathlib import Path -from unittest.mock import patch -from pt_snap_analyzer.rag.archive import CaseArchive, ArchiveError -from pt_snap_analyzer.rag.models import RAGCase, AnalysisStep - - -def test_archive_add_case(tmp_path): - """Test adding a case to archive""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case = RAGCase( - conclusion="Memory leak found", - root_cause="Cache not released", - solution="Release cache", - tags=["memory-leak"], - ) - - case_id = archive.add_case(case) - - assert case_id != "" - assert (tmp_path / f"{case_id}.json").exists() - - -def test_archive_add_case_missing_conclusion(tmp_path): - """Test error when conclusion missing""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case = RAGCase( - root_cause="Test cause", - solution="Test solution", - tags=["test"], - ) - - with pytest.raises(ArchiveError) as exc_info: - archive.add_case(case) - - assert "must have a conclusion" in str(exc_info.value) - - -def test_archive_get_case(tmp_path): - """Test getting a case from archive""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case = RAGCase( - conclusion="Test conclusion", - root_cause="Test cause", - solution="Test solution", - tags=["test"], - ) - case_id = archive.add_case(case) - - retrieved = archive.get_case(case_id) - - assert retrieved is not None - assert retrieved.conclusion == "Test conclusion" - - -def test_archive_get_case_not_found(tmp_path): - """Test getting non-existent case""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case = archive.get_case("nonexistent") - - assert case is None - - -def test_archive_list_cases(tmp_path): - """Test listing all cases""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case1 = RAGCase( - case_id="case-1", - conclusion="Case 1", - root_cause="Cause 1", - solution="Solution 1", - tags=["tag1"], - ) - case2 = RAGCase( - case_id="case-2", - conclusion="Case 2", - root_cause="Cause 2", - solution="Solution 2", - tags=["tag1", "tag2"], - ) - - archive.add_case(case1) - archive.add_case(case2) - - cases = archive.list_cases() - - assert len(cases) == 2 - - -def test_archive_list_cases_filtered(tmp_path): - """Test listing cases with tag filter""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case1 = RAGCase( - case_id="case-1", - conclusion="Case 1", - root_cause="Cause 1", - solution="Solution 1", - tags=["tag1"], - ) - case2 = RAGCase( - case_id="case-2", - conclusion="Case 2", - root_cause="Cause 2", - solution="Solution 2", - tags=["tag1", "tag2"], - ) - - archive.add_case(case1) - archive.add_case(case2) - - cases = archive.list_cases(tags=["tag1", "tag2"]) - - # Should only return case-2 (AND logic) - assert len(cases) == 1 - assert cases[0].case_id == "case-2" - - -def test_archive_delete_case(tmp_path): - """Test deleting a case""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - case = RAGCase( - conclusion="Test", - root_cause="Test", - solution="Test", - ) - case_id = archive.add_case(case) - - assert (tmp_path / f"{case_id}.json").exists() - - deleted = archive.delete_case(case_id) - - assert deleted - assert not (tmp_path / f"{case_id}.json").exists() - - -def test_archive_delete_not_found(tmp_path): - """Test deleting non-existent case""" - archive = CaseArchive(archive_dir=str(tmp_path)) - - deleted = archive.delete_case("nonexistent") - - assert not deleted -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_rag_archive.py -v -``` - -Expected: 7 tests PASS - -- [ ] **Step 4: Commit** - -```bash -git add pt_snap_analyzer/rag/archive.py tests/test_rag_archive.py -git commit -m "feat: add case archive system" -``` - ---- - -### Task 3: 案例检索系统 - -**Files:** -- Create: `pt_snap_analyzer/rag/searcher.py` -- Create: `tests/test_rag_searcher.py` - -- [ ] **Step 1: 创建检索器** - -```python -"""Searcher for RAG knowledge base""" - -from __future__ import annotations - -import re -import unicodedata -from pathlib import Path -from typing import List, Optional - -from pt_snap_analyzer.rag.archive import CaseArchive -from pt_snap_analyzer.rag.models import RAGCase, SearchMatch, SearchResult - - -class Searcher: - """Search RAG cases for similar problems - - Attributes: - archive: Case archive to search - """ - - def __init__(self, archive: Optional[CaseArchive] = None): - """Initialize searcher - - Args: - archive: Case archive (uses default if None) - """ - if archive is None: - archive = CaseArchive() - self.archive = archive - - def search( - self, - query: str, - top_k: int = 5, - tags: Optional[List[str]] = None, - ) -> SearchResult: - """Search for similar cases - - Args: - query: Search query - top_k: Number of results to return - tags: Optional tags to filter by - - Returns: - SearchResult with matched cases - """ - # Get all cases - cases = self.archive.list_cases(tags=tags) - - # Score each case - matches = [] - for case in cases: - score, matched_terms = self._score_case(case, query) - if score > 0: - matches.append(SearchMatch( - case=case, - score=score, - query_match=matched_terms, - )) - - # Sort by score - matches.sort(key=lambda m: m.score, reverse=True) - - # Take top K - matches = matches[:top_k] - - return SearchResult( - matches=matches, - total_results=len(matches), - query=query, - ) - - def _score_case(self, case: RAGCase, query: str) -> tuple[float, List[str]]: - """Score a case against query - - Args: - case: RAGCase to score - query: Search query - - Returns: - Tuple of (score, matched_terms) - """ - # Normalize query - query_terms = self._normalize_text(query).split() - - # Build searchable text - searchable = " ".join([ - case.conclusion, - case.root_cause, - case.solution, - " ".join(case.tags), - ]) - searchable = self._normalize_text(searchable) - - # Count matches - matched_terms = [] - matches = 0 - - for term in query_terms: - if term in searchable: - matches += 1 - matched_terms.append(term) - - # Calculate score - if not query_terms: - return 0.0, [] - - # Score = (matches / query_terms) * weight - base_score = matches / len(query_terms) - - # Boost score if case is verified - if case.verified_by != "unverified": - base_score *= 1.2 - - # Boost score for high confidence - if case.confidence > 0.8: - base_score *= 1.1 - - return min(base_score, 1.0), matched_terms - - def _normalize_text(self, text: str) -> str: - """Normalize text for comparison - - Args: - text: Input text - - Returns: - Normalized text - """ - # Convert to lowercase - text = text.lower() - - # Remove accents - text = unicodedata.normalize("NFD", text) - text = "".join(c for c in text if unicodedata.category(c) != "Mn") - - # Remove punctuation - text = re.sub(r"[^\w\s]", " ", text) - - # Collapse whitespace - text = " ".join(text.split()) - - return text - - def get_tags(self) -> List[str]: - """Get all unique tags from archive - - Returns: - List of unique tags - """ - tags = set() - - cases = self.archive.list_cases() - for case in cases: - tags.update(case.tags) - - return sorted(list(tags)) -``` - -- [ ] **Step 2: 创建测试文件** - -```python -"""Tests for RAG searcher""" - -import pytest -from pathlib import Path -from pt_snap_analyzer.rag.archive import CaseArchive -from pt_snap_analyzer.rag.searcher import Searcher -from pt_snap_analyzer.rag.models import RAGCase - - -def test_searcher_basic(): - """Test basic search functionality""" - archive = CaseArchive() - - case = RAGCase( - case_id="test-1", - conclusion="Memory leak in transformer", - root_cause="Attention cache not released", - solution="Upgrade transformers library", - tags=["memory-leak", "transformer", "attention"], - ) - archive.add_case(case) - - searcher = Searcher(archive=archive) - result = searcher.search("memory leak transformer") - - assert result.total_results >= 1 - assert any("memory" in m.query_match for m in result.matches) - - -def test_searcher_no_matches(): - """Test search with no matches""" - archive = CaseArchive() - - case = RAGCase( - case_id="test-1", - conclusion="CUDA out of memory", - root_cause="Batch size too large", - solution="Reduce batch size", - tags=["cuda", "oom"], - ) - archive.add_case(case) - - searcher = Searcher(archive=archive) - result = searcher.search("python memory leak") - - # Should have no matches - assert result.total_results == 0 - - -def test_searcher_tag_filter(): - """Test search with tag filter""" - archive = CaseArchive() - - case1 = RAGCase( - case_id="test-1", - conclusion="Memory leak", - root_cause="Cache not released", - solution="Release cache", - tags=["memory-leak", "cpu"], - ) - case2 = RAGCase( - case_id="test-2", - conclusion="GPU OOM", - root_cause="Too much memory", - solution="Reduce batch", - tags=["cuda", "oom"], - ) - - archive.add_case(case1) - archive.add_case(case2) - - searcher = Searcher(archive=archive) - result = searcher.search("memory", tags=["memory-leak"]) - - assert result.total_results >= 1 - - -def test_searcher_verified_boost(): - """Test score boost for verified cases""" - archive = CaseArchive() - - case_unverified = RAGCase( - case_id="test-1", - conclusion="Memory leak", - root_cause="Test", - solution="Test", - tags=["test"], - ) - case_verified = RAGCase( - case_id="test-2", - conclusion="Memory leak", - root_cause="Test", - solution="Test", - tags=["test"], - verified_by="human", - ) - - archive.add_case(case_unverified) - archive.add_case(case_verified) - - searcher = Searcher(archive=archive) - result = searcher.search("memory test") - - if result.total_results >= 2: - # Verified case should have higher score - scores = [m.score for m in result.matches] - assert max(scores) >= min(scores) - - -def test_get_tags(): - """Test getting all tags""" - archive = CaseArchive() - - case1 = RAGCase( - case_id="test-1", - conclusion="Test 1", - root_cause="Test", - solution="Test", - tags=["tag1", "tag2"], - ) - case2 = RAGCase( - case_id="test-2", - conclusion="Test 2", - root_cause="Test", - solution="Test", - tags=["tag2", "tag3"], - ) - - archive.add_case(case1) - archive.add_case(case2) - - searcher = Searcher(archive=archive) - tags = searcher.get_tags() - - assert "tag1" in tags - assert "tag2" in tags - assert "tag3" in tags - assert len(tags) == 3 -``` - -- [ ] **Step 3: Run test** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_rag_searcher.py -v -``` - -Expected: 6 tests PASS - -- [ ] **Step 4: Commit** - -```bash -git add pt_snap_analyzer/rag/searcher.py tests/test_rag_searcher.py -git commit -m "feat: add RAG searcher" -``` - ---- - -### Task 4: CLI 集成 - -**Files:** -- Modify: `pt_snap_analyzer/cli.py` -- Create: `tests/test_rag_cli.py` - -- [ ] **Step 1: 添加 rag 命令到 CLI** - -```python -# Add to cli.py after imports -from pt_snap_analyzer.rag.archive import CaseArchive, ArchiveError -from pt_snap_analyzer.rag.searcher import Searcher - - -@app.command() -def rag(): - """RAG knowledge base commands""" - raise typer.Exit(code=1) - - -@app.command() -def rag_add( - file: Annotated[str, typer.Argument(help="JSON file with case data")], -): - """Add a case to the RAG knowledge base""" - try: - archive = CaseArchive() - - # Load case from JSON file - from pathlib import Path - case_file = Path(file) - if not case_file.exists(): - print(f"Error: File not found: {file}", flush=True) - raise typer.Exit(code=1) - - with open(case_file, "r") as f: - import json - case_dict = json.load(f) - - # Convert to RAGCase - case = RAGCase(**case_dict) - case_id = archive.add_case(case) - - print(f"Case added: {case_id}") - - except ArchiveError as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - except json.JSONDecodeError as e: - print(f"Error: Invalid JSON: {e}", flush=True) - raise typer.Exit(code=1) - - -@app.command() -def rag_search( - query: Annotated[str, typer.Argument(help="Search query")], - top_k: Annotated[ - int, typer.Option("--top-k", help="Number of results") - ] = 5, - tags: Annotated[ - List[str], typer.Option("--tags", help="Filter by tags") - ] = [], - json_output: Annotated[ - bool, typer.Option("--json", help="Output in JSON format") - ] = False, -): - """Search the RAG knowledge base""" - try: - searcher = Searcher() - result = searcher.search( - query=query, - top_k=top_k, - tags=tags if tags else None, - ) - - if json_output: - import json - output = { - "query": result.query, - "total_results": result.total_results, - "matches": [ - { - "case_id": m.case.case_id, - "score": m.score, - "query_match": m.query_match, - "conclusion": m.case.conclusion, - "solution": m.case.solution, - } - for m in result.matches - ], - } - print(json.dumps(output, indent=2)) - else: - print(f"Search results for: '{query}'") - print(f"Found {result.total_results} matches") - print("-" * 60) - - for i, match in enumerate(result.matches, 1): - print(f"\n[{i}] {match.case.case_id}") - print(f" Score: {match.score:.3f}") - print(f" Conclusion: {match.case.conclusion}") - if match.case.solution: - print(f" Solution: {match.case.solution}") - - except Exception as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - - -@app.command() -def rag_list( - tags: Annotated[ - List[str], typer.Option("--tags", help="Filter by tags") - ] = [], - json_output: Annotated[ - bool, typer.Option("--json", help="Output in JSON format") - ] = False, -): - """List all cases in the RAG knowledge base""" - try: - archive = CaseArchive() - cases = archive.list_cases(tags=tags if tags else None) - - if json_output: - import json - output = [ - { - "case_id": c.case_id, - "timestamp": c.timestamp, - "conclusion": c.conclusion, - "solution": c.solution, - "tags": c.tags, - } - for c in cases - ] - print(json.dumps(output, indent=2)) - else: - print(f"Total cases: {len(cases)}") - print("-" * 60) - - for case in cases: - print(f"\n{case.case_id}") - print(f" {case.timestamp}") - print(f" {case.conclusion}") - if case.tags: - print(f" Tags: {', '.join(case.tags)}") - - except Exception as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) - - -@app.command() -def rag_tags(): - """List all tags in the RAG knowledge base""" - try: - searcher = Searcher() - tags = searcher.get_tags() - - print("Available Tags:") - for tag in tags: - print(f" - {tag}") - - except Exception as e: - print(f"Error: {e}", flush=True) - raise typer.Exit(code=1) -``` - -- [ ] **Step 2: 创建 CLI 测试** - -```python -"""Tests for RAG CLI commands""" - -from click.testing import CliRunner -from pt_snap_analyzer.cli import app - - -def test_rag_add_json_format(): - """Test rag-add with JSON file""" - runner = CliRunner() - # This will fail without a real file, but parameter parsing should work - result = runner.invoke(app, ["rag-add", "/nonexistent/file.json"]) - assert result.exit_code != 0 - - -def test_rag_search_query(): - """Test rag-search with query""" - runner = CliRunner() - result = runner.invoke(app, ["rag-search", "memory leak"]) - # Should succeed even if no cases - assert result.exit_code == 0 - - -def test_rag_search_with_tags(): - """Test rag-search with tags filter""" - runner = CliRunner() - result = runner.invoke(app, [ - "rag-search", "memory", - "--tags", "memory-leak", - "--json" - ]) - assert result.exit_code == 0 - - -def test_rag_list(): - """Test rag-list command""" - runner = CliRunner() - result = runner.invoke(app, ["rag-list"]) - assert result.exit_code == 0 - - -def test_rag_tags(): - """Test rag-tags command""" - runner = CliRunner() - result = runner.invoke(app, ["rag-tags"]) - assert result.exit_code == 0 - assert "Available Tags:" in result.output -``` - -- [ ] **Step 3: 运行测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_rag_cli.py -v -``` - -Expected: 4 tests PASS - -- [ ] **Step 4: 运行完整测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - -Expected: 30+ tests PASS - -- [ ] **Step 5: Commit** - -```bash -git add pt_snap_analyzer/cli.py tests/test_rag_cli.py -git commit -m "feat: integrate RAG into CLI" -``` - ---- - -### Task 5: 完整的 SDK 集成 - -**Files:** -- Modify: `pt_snap_analyzer/__init__.py` -- Modify: `pt_snap_analyzer/rag/__init__.py` - -- [ ] **Step 1: 更新包初始化** - -```python -"""pt-snap-analyzer - AI-friendly PyTorch Memory Snapshot Analyzer""" - -__version__ = "0.1.0" -__author__ = "Liuyekang" - -from pt_snap_analyzer.context import Context -from pt_snap_analyzer.models import MemoryEvent, MemoryBlock -from pt_snap_analyzer.rag import CaseArchive, Searcher, RAGCase, SearchResult - -__all__ = [ - "Context", - "MemoryEvent", - "MemoryBlock", - "CaseArchive", - "Searcher", - "RAGCase", - "SearchResult", - "__version__", -] -``` - -- [ ] **Step 2: 创建 rag 包初始化** - -```python -"""RAG knowledge base for pt-snap-analyzer""" - -from pt_snap_analyzer.rag.models import RAGCase, SearchResult, SearchMatch -from pt_snap_analyzer.rag.archive import CaseArchive, ArchiveError -from pt_searcher import Searcher - -__all__ = ["RAGCase", "SearchResult", "SearchMatch", "CaseArchive", "Searcher", "ArchiveError"] -``` - -- [ ] **Step 3: 创建 SDK 测试** - -```python -"""Tests for RAG SDK integration""" - -import pytest -from pt_snap_analyzer import CaseArchive, Searcher, RAGCase - - -def test_sdk_case_archive(): - """Test CaseArchive via SDK""" - archive = CaseArchive() - - case = RAGCase( - conclusion="SDK test", - root_cause="Test cause", - solution="Test solution", - tags=["sdk-test"], - ) - case_id = archive.add_case(case) - - retrieved = archive.get_case(case_id) - assert retrieved is not None - assert retrieved.conclusion == "SDK test" - - -def test_sdk_searcher(): - """Test Searcher via SDK""" - archive = CaseArchive() - - case = RAGCase( - case_id="sdk-test-1", - conclusion="Memory leak in transformer", - root_cause="Cache not released", - solution="Upgrade transformers", - tags=["memory-leak", "transformer"], - ) - archive.add_case(case) - - searcher = Searcher(archive=archive) - result = searcher.search("memory leak transformer") - - assert result.total_results >= 1 - - -def test_sdk_rag_case(): - """Test RAGCase creation via SDK""" - case = RAGCase( - case_id="explicit-id", - conclusion="Explicit test", - root_cause="Test", - solution="Test", - tags=["test"], - confidence=0.95, - verified_by="human", - ) - - assert case.case_id == "explicit-id" - assert case.confidence == 0.95 -``` - -- [ ] **Step 4: 运行测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/test_sdk_rag.py -v -``` - -Expected: 3 tests PASS - -- [ ] **Step 5: 运行完整测试** - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - -Expected: 33+ tests PASS - -- [ ] **Step 6: Commit** - -```bash -git add pt_snap_analyzer/__init__.py pt_snap_analyzer/rag/__init__.py tests/test_sdk_rag.py -git commit -m "feat: add SDK integration for RAG" -``` - ---- - -### 最终验收清单 - -- [ ] 所有测试通过 (33+ tests) -- [ ] CaseArchive 可以添加和检索案例 -- [ ] Searcher 可以搜索相似案例 -- [ ] CLI 命令正常工作 -- [ ] SDK API 可用 -- [ ] 标签过滤正确工作 -- [ ] pytest 覆盖率 > 80% - ---- - -## 执行意见 - -Plan complete and saved to `docs/superpowers/plans/2026-04-04-pt-snap-analyzer-rag.md`. Two execution options: - -**1. Subagent-Driven (recommended)** - 我分发每个任务的独立 subagent,任务间审查,快速迭代 - -**2. Inline Execution** - 在此会话中执行任务,使用 executing-plans,批次执行加检查点 - -**Which approach?** diff --git a/.agents/superpowers/plans/README.md b/.agents/superpowers/plans/README.md deleted file mode 100644 index 86c5a53..0000000 --- a/.agents/superpowers/plans/README.md +++ /dev/null @@ -1,198 +0,0 @@ -# pt-snap-analyzer 开发计划 - -这篇文档整理了 pt-snap-analyzer 的完整开发计划,按照功能模块解耦拆分为多个独立的计划。 - -## 计划概览 - -| 计划名称 | 说明 | 文件 | -|---------|------|------| -| **基础架构** | 构建 CLI 框架、数据模型和核心 Context | [2026-04-04-pt-snap-analyzer-foundation.md](./2026-04-04-pt-snap-analyzer-foundation.md) | -| **分析器模块** | 实现核心分析器:泄漏检测、峰值分析、趋势分析、调用栈分析 | [2026-04-04-pt-snap-analyzer-analyzers.md](./2026-04-04-pt-snap-analyzer-analyzers.md) | -| **查询系统** | 实现 YAML 配置的 SQL 模板和查询执行器 | [2026-04-04-pt-snap-analyzer-query.md](./2026-04-04-pt-snap-analyzer-query.md) | -| **RAG 知识库** | 实现案例归档、向量搜索和相似案例检索 | [2026-04-04-pt-snap-analyzer-rag.md](./2026-04-04-pt-snap-analyzer-rag.md) | - -## 计划详情 - -### 1. 基础架构 - -**Goal**: 构建 CLI 框架、数据模型和核心 Context,提供基础 API 支撑 - -**Tech Stack**: Python 3.10+, Typer, Pydantic, SQLite3 - -**主要内容**: -- 项目初始化和配置(pyproject.toml, __init__.py) -- 数据模型:枚举类型、MemoryEvent、MemoryBlock -- Context 类:数据库连接管理 -- CLI 框架:命令结构和子命令 -- 集成测试 - -**文件结构**: -``` -pt_snap_analyzer/ -├── __init__.py -├── cli.py -├── context.py -├── models/ -│ ├── _enums.py -│ ├── event.py -│ ├── block.py -│ └── result.py (基础类) -└── version.py -``` - -**测试目标**: 15+ tests, 覆盖率 > 80% - ---- - -### 2. 分析器模块 - -**Goal**: 实现核心分析器模块:泄漏检测、峰值分析、趋势分析、调用栈分析 - -**Tech Stack**: Python 3.10+, SQLite3, Pydantic - -**主要内容**: -- 分析器基类和结果模型 -- LeakDetector:泄漏检测 -- PeakAnalyzer:峰值分析 -- TrendAnalyzer:趋势分析 -- StackAnalyzer:调用栈分析 -- CLI 集成 - -**文件结构**: -``` -pt_snap_analyzer/ -├── analyzers/ -│ ├── base.py -│ ├── leak_detector.py -│ ├── peak_analyzer.py -│ ├── trend_analyzer.py -│ └── stack_analyzer.py -└── models/ - ├── result.py - ├── leak.py - ├── peak.py - ├── trend.py - └── stack.py -``` - -**测试目标**: 20+ tests, 覆盖率 > 80% - ---- - -### 3. 查询系统 - -**Goal**: 实现查询配置系统,支持 YAML 配置的 SQL 模板和查询执行器 - -**Tech Stack**: Python 3.10+, SQLite3, PyYAML, Jinja2 - -**主要内容**: -- 查询配置加载器(QueryConfigLoader) -- 查询执行器(QueryExecutor) -- 预定义 SQL 模板 -- CLI 命令集成 - -**文件结构**: -``` -pt_snap_analyzer/ -└── query/ - ├── config.py - ├── executor.py - └── templates/ - ├── leak_detection_v2.yaml - ├── memory_timeline_v2.yaml - └── callstack_analysis_v2.yaml -``` - -**测试目标**: 25+ tests, 覆盖率 > 80% - ---- - -### 4. RAG 知识库 - -**Goal**: 实现 RAG 知识库,支持案例归档、向量搜索和相似案例检索 - -**Tech Stack**: Python 3.10+, ChromaDB - -**主要内容**: -- RAG 数据模型(RAGCase, SearchResult 等) -- 案例归档系统(CaseArchive) -- 案例检索系统(Searcher) -- CLI 命令集成 -- SDK API - -**文件结构**: -``` -pt_snap_analyzer/ -└── rag/ - ├── models.py - ├── archive.py - └── searcher.py -``` - -**测试目标**: 33+ tests, 覆盖率 > 80% - ---- - -## 执行方式 - -每个计划都使用 **writing-plans** 技术编写,包含详细的步骤和代码示例。执行时可以选择: - -### 1. Subagent-Driven(推荐) - -每个任务由独立的 subagent 执行,任务间进行审查,快速迭代开发。 - -### 2. Inline Execution - -在当前会话中执行任务,使用 executing-plans,批次执行加检查点。 - ---- - -## 运行测试 - -每个计划完成后都需要运行测试: - -```bash -. /Users/test1/liuyekang/miniconda3/etc/profile.d/conda.sh && conda activate openclaw && pytest tests/ -v -``` - ---- - -## 开发顺序建议 - -推荐按照以下顺序开发: - -1. **基础架构** → 2. **分析器模块** → 3. **查询系统** → 4. **RAG 知识库** - -这样可以确保基础功能先行,逐步添加高级功能。 - ---- - -## 文件清单 - -| 文件 | 描述 | -|------|------| -| [2026-04-04-pt-snap-analyzer-foundation.md](./2026-04-04-pt-snap-analyzer-foundation.md) | 基础架构计划 | -| [2026-04-04-pt-snap-analyzer-analyzers.md](./2026-04-04-pt-snap-analyzer-analyzers.md) | 分析器模块计划 | -| [2026-04-04-pt-snap-analyzer-query.md](./2026-04-04-pt-snap-analyzer-query.md) | 查询系统计划 | -| [2026-04-04-pt-snap-analyzer-rag.md](./2026-04-04-pt-snap-analyzer-rag.md) | RAG 知识库计划 | - ---- - -## 相关文档 - -- [PRD 文档](../prds/2026-04-04-pt-snap-analyzer-prd.md) - 产品需求文档 -- [设计文档](../specs/2026-04-04-pt-snap-analyzer-design.md) - 系统设计文档 -- [DB Schema](../../snapshot_db_schema.md) - 数据库 schema 定义 - ---- - -## 下一步 - -选择一个计划开始执行: - -1. 基础架构计划 -2. 分析器模块计划 -3. 查询系统计划 -4. RAG 知识库计划 - -推荐从 **基础架构计划** 开始,建立项目框架。 diff --git a/.agents/superpowers/prds/2026-04-04-pt-snap-analyzer-prd.md b/.agents/superpowers/prds/2026-04-04-pt-snap-analyzer-prd.md deleted file mode 100644 index cb71704..0000000 --- a/.agents/superpowers/prds/2026-04-04-pt-snap-analyzer-prd.md +++ /dev/null @@ -1,780 +0,0 @@ -# PyTorch 内存快照分析器 - 产品需求文档 (PRD) - -**创建日期**: 2026-04-04 -**状态**: 待开发 -**版本**: 1.0 -**关联设计文档**: [2026-04-04-pt-snap-analyzer-design.md](../specs/2026-04-04-pt-snap-analyzer-design.md) - ---- - -## Executive Summary - -**Problem**: PyTorch 开发者花费大量时间调试内存问题,现有工具要么不可自动化(GUI),要么输出不结构化(AI 无法解析)。 - -**Solution**: pt-snap-analyzer —— AI 友好的 CLI + SDK 分析工具,基于 SQLite 和 RAG 知识库。 - -**Success Metrics**: -- CLI 命令响应时间 < 1s(600M 数据库) -- 泄漏检测准确率 > 90%(相比人工分析) -- RAG 检索 Top-3 相关度 > 80%(用户反馈评分) -- 单元测试覆盖率 > 80% -- AI Agent 调用成功率 > 95%(无语法/格式错误) - ---- - -## Problem Statement - -PyTorch 开发者在训练大型模型时面临内存问题(内存泄漏、峰值过高、碎片化等),但缺乏有效的分析工具: - -1. **内存泄漏难定位**: 训练过程中内存持续增长,但无法快速定位泄漏源头(哪个算子/哪行代码) -2. **峰值分析困难**: 内存峰值出现时,无法回溯分析是哪些分配导致的 -3. **缺乏历史对比**: 无法对比不同迭代、不同配置下的内存使用模式差异 -4. **工具链割裂**: 现有工具要么是 GUI(不可自动化),要么输出不结构化(AI 无法解析) -5. **经验无法沉淀**: 解决问题的经验难以文档化和复用,每次都要重新摸索 - -这些问题导致开发者花费大量时间调试内存问题,影响模型研发效率。 - ---- - -## Solution - -构建 `pt-snap-analyzer` —— 一个 AI 友好的 PyTorch 内存快照分析工具,核心特性: - -1. **CLI + SDK 双接口**: - - CLI: 命令行工具,输出结构化 JSON,AI 可解析 - - SDK: Python API,可集成到自动化工作流 - -2. **SQLite 驱动分析**: 基于 SQLite 数据库存储快照,所有分析能力基于 SQL 查询,可处理 GB 级快照数据 - -3. **插件式分析器**: 泄漏检测、峰值分析、趋势分析、调用栈分析等模块化设计 - -4. **RAG 知识库**: 将分析案例和解决方案文档化,AI 可检索相似问题的解决经验 - -5. **配置化查询**: 预定义查询模板通过 YAML 配置管理,支持动态扩展 - -**核心价值**: -- 🔧 **独立 CLI**: 开发者可直接使用命令分析内存快照 -- 🤖 **AI 友好**: SDK + JSON 输出,AI Agent 可自动调用分析 -- 📚 **RAG 知识库**: 先验经验文档化,AI 可检索相似案例 -- 📊 **SQLite 驱动**: 基于 SQL 查询,高效处理大数据量 - ---- - -## User Stories - -### CLI 使用场景 - -1. **作为开发者**,我想要通过 `pt-snap use ` 命令设置当前分析的数据库,以便快速切换分析目标 - - **Acceptance Criteria**: - - [ ] 成功时输出 `Using database: ` - - [ ] 数据库不存在时输出错误到 stderr,退出码 1 - - [ ] 数据库路径持久化到 `~/.config/pt-snap-analyzer/current_db` - -2. **作为开发者**,我想要通过 `pt-snap analyze leak --json` 命令检测内存泄漏,以便快速定位未释放的内存块 - - **Acceptance Criteria**: - - [ ] 输出必须是合法 JSON 格式 - - [ ] 包含泄漏块 ID、地址、大小、调用栈 - - [ ] 按大小降序排列 - - [ ] 支持 --min-size 参数过滤 - - [ ] 错误时输出到 stderr 且退出码非零 - -3. **作为开发者**,我想要通过 `pt-snap analyze peak --json` 命令分析内存峰值,以便识别异常分配 - - **Acceptance Criteria**: - - [ ] 输出峰值事件列表(时间、大小、调用栈) - - [ ] 支持 --top-k 参数限制结果数量 - - [ ] 输出峰值前后的内存变化趋势 - - [ ] JSON 包含统计信息(峰值大小、时间点) - -4. **作为开发者**,我想要通过 `pt-snap analyze trend --plot` 命令查看内存使用趋势,以便了解内存变化模式 - - **Acceptance Criteria**: - - [ ] 输出时间序列数据(时间戳、allocated、active、reserved) - - [ ] --plot 模式生成 ASCII 图或保存为 PNG - - [ ] 支持 --interval 参数指定采样间隔 - -5. **作为开发者**,我想要通过 `pt-snap analyze stack --top-k 10` 命令分析调用栈,以便找出分配最多的代码路径 - - **Acceptance Criteria**: - - [ ] 输出 Top-K 调用栈及其分配次数/总大小 - - [ ] 调用栈按出现频率降序排列 - - [ ] 支持 --group-by 参数(按函数/按文件) - - [ ] JSON 包含调用栈树结构 - -6. **作为开发者**,我想要通过 `pt-snap query list` 命令查看预定义查询列表,以便了解可用的分析查询 - - **Acceptance Criteria**: - - [ ] 输出查询名称、描述、参数列表 - - [ ] 支持 --format json | table 切换输出格式 - - [ ] 包含用户自定义查询(从 YAML 配置加载) - -7. **作为开发者**,我想要通过 `pt-snap query exec ` 命令执行预定义查询,以便复用已有的分析逻辑 - - **Acceptance Criteria**: - - [ ] 支持 --param key=value 传递参数 - - [ ] 输出查询结果(JSON 或表格) - - [ ] 查询不存在时输出错误和建议查询列表 - - [ ] 支持 --device 参数指定设备 - -8. **作为开发者**,我想要通过 `pt-snap compare ` 命令对比两个快照,以便分析不同配置的内存差异 - - **Acceptance Criteria**: - - [ ] 输出两个数据库的统计对比(总分配、峰值、泄漏数) - - [ ] 标识差异超过阈值的指标(可配置) - - [ ] 支持 --metrics 参数指定对比指标 - - [ ] JSON 包含差异百分比 - -9. **作为 AI Agent**,我想要解析 CLI 的 JSON 输出,以便自动提取分析结果并生成报告 - - **Acceptance Criteria**: - - [ ] 所有 --json 输出符合预定义 schema - - [ ] JSON 键名稳定、可预测 - - [ ] 包含元数据(数据库路径、分析时间、设备) - -10. **作为 AI Agent**,我想要组合多个 CLI 命令(如 leak + peak + stack),以便完成复杂的内存分析任务 - - **Acceptance Criteria**: - - [ ] 命令间状态独立(无副作用) - - [ ] 错误信息包含上下文(哪个命令失败) - - [ ] 支持 --output-file 保存结果到文件 - -### SDK 使用场景 - -11. **作为开发者**,我想要通过 `Context(db_path, devices)` 创建分析上下文,以便管理数据库连接和配置 - - **Acceptance Criteria**: - - [ ] 验证数据库文件存在 - - [ ] 加载数据库 schema 并验证版本 - - [ ] 支持设备列表参数(默认 all) - - [ ] 抛出自定义异常(DatabaseNotFoundError, SchemaVersionError) - -12. **作为开发者**,我想要调用 `analyzer.detect_leaks()` API 检测泄漏,以便集成到自己的工具链中 - - **Acceptance Criteria**: - - [ ] 返回 LeakResult 对象(可序列化为 JSON) - - [ ] 支持 min_size 参数过滤 - - [ ] 支持 device 参数指定设备 - - [ ] 包含泄漏块列表和统计信息 - -13. **作为开发者**,我想要调用 `analyzer.analyze_trend(metrics)` 分析趋势,以便获取内存使用的时间序列数据 - - **Acceptance Criteria**: - - [ ] metrics 参数指定 [allocated, active, reserved] - - [ ] 返回时间序列(列表) - - [ ] 支持 start_time/end_time 参数 - - [ ] 返回统计信息(均值、趋势斜率) - -14. **作为开发者**,我想要调用 `analyzer.analyze_stack_trace(top_k)` 分析调用栈,以便找出热点分配路径 - - **Acceptance Criteria**: - - [ ] 返回 Top-K 调用栈列表 - - [ ] 每个调用栈包含调用链、分配次数、总大小 - - [ ] 支持 group_by 参数(function/file) - - [ ] 返回调用栈树结构 - -15. **作为开发者**,我想要调用 `rag.search(query)` 检索案例,以便查找相似问题的解决方案 - - **Acceptance Criteria**: - - [ ] 支持关键词搜索和向量搜索 - - [ ] 返回案例列表(按相关度排序) - - [ ] 支持 top_k 参数 - - [ ] 支持 tags 过滤 - -16. **作为开发者**,我想要调用 `rag.add_case(...)` 添加案例,以便将成功的分析经验归档到知识库 - - **Acceptance Criteria**: - - [ ] 验证案例数据完整性 - - [ ] 自动生成 case_id(如果未提供) - - [ ] 生成向量嵌入并存储 - - [ ] 返回案例 ID - -17. **作为 AI Agent**,我想要通过 SDK 直接调用分析 API,以便在 Python 代码中集成分析能力 - - **Acceptance Criteria**: - - [ ] SDK API 文档完整(docstring) - - [ ] 所有返回对象支持 .model_dump_json() - - [ ] 异常可捕获且包含详细信息 - - [ ] 提供示例代码(examples/ 目录) - -### RAG 知识库场景 - -18. **作为开发者**,我想要将成功的分析案例保存到知识库,以便后续复用分析经验 - - **Acceptance Criteria**: - - [ ] CLI 命令 `rag add --file ` 支持添加案例 - - [ ] SDK API `rag.add_case(case_dict)` 验证数据结构 - - [ ] 自动生成向量嵌入 - - [ ] 支持 tags 标签(用于过滤) - -19. **作为开发者**,我想要通过关键词检索案例(如 "memory leak transformer"),以便找到相似问题的解决方案 - - **Acceptance Criteria**: - - [ ] CLI 命令 `rag search ` 输出相关案例 - - [ ] 支持 --top-k 参数限制结果数 - - [ ] 输出案例摘要和置信度 - - [ ] 支持 --tags 过滤 - -20. **作为开发者**,我想要通过标签过滤案例(如 `--tags memory-leak,transformer`),以便精确定位相关案例 - - **Acceptance Criteria**: - - [ ] 支持多标签 AND/OR 逻辑 - - [ ] 标签列表可通过 `rag tags` 查看 - - [ ] 标签支持自动补全(CLI) - -21. **作为 AI Agent**,我想要在分析失败时检索 RAG 知识库,以便尝试其他分析策略 - - **Acceptance Criteria**: - - [ ] 分析器失败时抛出包含错误上下文的异常 - - [ ] AI 可捕获异常并构造查询词 - - [ ] RAG 返回相似案例的解决策略 - -22. **作为 AI Agent**,我想要将成功的分析路径(查询序列 + 结论)归档,以便学习优化分析策略 - - **Acceptance Criteria**: - - [ ] 分析路径可序列化为 JSON - - [ ] 包含查询序列、参数、结果、结论 - - [ ] 可通过 `rag add --analysis-path ` 添加 - -### 可维护性场景 - -23. **作为开发者**,我想要通过 YAML 配置定义新的查询模板,以便无需修改代码即可扩展分析能力 - - **Acceptance Criteria**: - - [ ] YAML 配置放在 `~/.config/pt-snap-analyzer/queries/` - - [ ] 配置包含 name, description, parameters, query, output_schema - - [ ] 启动时自动加载配置 - - [ ] 配置错误时输出详细错误信息(行号、字段) - -24. **作为开发者**,我想要为新的分析场景编写插件式分析器,以便快速添加定制化分析能力 - - **Acceptance Criteria**: - - [ ] 继承 AnalyzerBase 抽象基类 - - [ ] 实现 analyze() 方法返回 AnalysisResult - - [ ] 通过 entry_point 注册到 CLI - - [ ] 提供插件示例代码 - -25. **作为维护者**,我想要每个分析模块有独立的单元测试,以便保证代码质量和可维护性 - - **Acceptance Criteria**: - - [ ] 测试文件与模块一一对应(test_leak_detector.py, etc.) - - [ ] 使用 pytest 框架 - - [ ] 测试数据隔离(fixture) - - [ ] CI 自动运行测试 - ---- - -## Implementation Decisions - -### 技术栈选择 - -| 模块 | 技术选择 | 理由 | -|------|---------|------| -| CLI 框架 | `typer` | 基于 type hints,自动生成 help,支持子命令 | -| SDK | 原生 Python | 低依赖、易集成 | -| JSON 输出 | `pydantic` | 结构化输出、类型校验 | -| RAG | `chromadb` + `langchain` | 成熟方案、易扩展 | -| SQL 构建 | 原生 sqlite3 + 模板引擎 | 轻量、可控 | -| YAML 解析 | `pyyaml` | 标准库,广泛使用 | -| 文档生成 | `mkdocs` | 可选,用于生成 API 文档 | - -### 依赖管理 - -- 使用 **conda** 管理依赖 -- 工作环境:`openclaw` (已在规则中配置) -- 依赖列表:`typer`, `pydantic`, `pyyaml`, `chromadb`, `langchain`, `sqlite3` (内置) - -### 项目结构 - -采用**单一包**结构,CLI 和 SDK 共享核心逻辑: - -``` -pt-snap-cli/ -├── pt_snap_analyzer/ # 主包 -│ ├── __init__.py -│ ├── cli.py # CLI 入口 -│ ├── context.py # Context 类 -│ ├── analyzers/ # 分析器模块 -│ │ ├── __init__.py -│ │ ├── base.py # AnalyzerBase 抽象基类 -│ │ ├── leak_detector.py # 泄漏检测 -│ │ ├── peak_analyzer.py # 峰值分析 -│ │ ├── trend_analyzer.py # 趋势分析 -│ │ └── stack_analyzer.py # 调用栈分析 -│ ├── query/ # 查询模块 -│ │ ├── __init__.py -│ │ ├── executor.py # 查询执行器 -│ │ ├── config.py # YAML 配置管理 -│ │ └── templates/ # 预定义 SQL 模板 -│ │ ├── leak_detection_v2.yaml -│ │ ├── memory_timeline_v2.yaml -│ │ └── callstack_analysis_v2.yaml -│ ├── rag/ # RAG 模块 -│ │ ├── __init__.py -│ │ ├── searcher.py # RAG 检索 -│ │ ├── archive.py # 案例归档 -│ │ └── models.py # RAG 数据模型 -│ └── models/ # 数据模型 -│ ├── __init__.py -│ ├── event.py # MemoryEvent -│ └── block.py # MemoryBlock -├── tests/ # 测试目录 -│ ├── test_cli.py -│ ├── test_analyzers.py -│ ├── test_query.py -│ └── test_rag.py -├── docs/ # 文档 -└── pyproject.toml # 项目配置 -``` - -### 核心数据模型 - -#### 枚举类型 - -```python -class EventType(IntEnum): - SEGMENT_MAP = 0 - SEGMENT_UNMAP = 1 - SEGMENT_ALLOC = 2 - SEGMENT_FREE = 3 - ALLOC = 4 - FREE_REQUESTED = 5 - FREE_COMPLETED = 6 - WORKSPACE_SNAPSHOT = 7 -``` - -#### MemoryEvent - -```python -@dataclass -class MemoryEvent: - id: int - action: EventType - address: int - size: int - stream: int - allocated: int - active: int - reserved: int - callstack: Optional[str] - - @property - def is_virtual_event(self) -> bool: - return self.id < 0 - - @property - def is_runtime_event(self) -> bool: - return self.id >= 0 -``` - -#### MemoryBlock - -```python -@dataclass -class MemoryBlock: - id: int - address: int - size: int - requestedSize: int - state: int - allocEventId: Optional[int] - freeEventId: Optional[int] - - @property - def is_historical_block(self) -> bool: - return self.id < 0 - - @property - def is_active(self) -> bool: - if self.is_historical_block: - return self.state == 1 - return self.freeEventId is None or self.freeEventId == -1 -``` - -### 分析器接口 - -所有分析器继承自 `AnalyzerBase`: - -```python -class AnalyzerBase(ABC): - name: str - description: str - - def __init__(self, context: Context): - self.context = context - - @abstractmethod - def analyze(self, **kwargs) -> AnalysisResult: - pass -``` - -具体分析器实现: -- `LeakDetector`: `detect_leaks()` → `LeakResult` -- `PeakAnalyzer`: `analyze_peaks()` → `PeakResult` -- `TrendAnalyzer`: `analyze_trend(metrics)` → `TrendResult` -- `StackAnalyzer`: `analyze_stack_trace(top_k)` → `StackResult` - -### 查询配置格式 - -YAML 配置示例: - -```yaml -name: leak_detection_v2 -description: 内存泄漏检测 v2 -devices: all -parameters: - min_size: - default: 1024 - type: int - description: 最小泄漏块大小(字节) -query: | - SELECT b.id, b.address, b.size, t.callstack - FROM block_{device} b - LEFT JOIN trace_entry_{device} t ON b.allocEventId = t.id - WHERE b.id >= 0 AND b.freeEventId IS NULL - ORDER BY b.size DESC -output_schema: - - block_id: int - - address: int - - size: int - - callstack: str -``` - -### RAG 案例数据结构 - -```json -{ - "case_id": "memory_leak_in_transformer_attention", - "timestamp": "2026-04-04T10:30:00Z", - "db_snapshot": "snapshot.db", - "analysis_steps": [...], - "conclusion": "Attention 层的 key/value cache 未正确释放", - "root_cause": "transformers 库 v4.30.0 的 bug", - "solution": "升级 transformers 库到 v4.31.0", - "tags": ["memory-leak", "transformer", "attention"], - "confidence": 0.95, - "verified_by": "human_feedback" -} -``` - -### CLI 命令设计 - -使用 `typer` 的子命令结构: - -```python -# cli.py -app = typer.Typer() - -@app.command() -def use(db_path: str): - """设置当前使用的数据库""" - ... - -@app.command() -def config(): - """配置管理""" - ... - -@app.command() -def analyze(): - """内存分析""" - ... - -@app.command() -def query(): - """查询管理""" - ... - -@app.command() -def rag(): - """RAG 知识库管理""" - ... - -@app.command() -def compare(db1: str, db2: str): - """对比分析""" - ... -``` - -### 错误处理策略 - -- CLI 错误输出到 stderr,退出码非零 -- SDK 抛出自定义异常:`AnalyzerError`, `QueryError`, `RAGError` -- 所有异常包含错误原因和建议修复方案 - ---- - -## Integration Points - -### 外部系统交互 - -| 组件 | 交互方式 | 说明 | -|------|---------|------| -| **数据库** | SQLite (.db 文件) | 由 PyTorch 内存快照工具生成,只读模式打开 | -| **RAG 向量库** | ChromaDB | 本地存储,路径 `~/.local/share/pt-snap-analyzer/rag_db` | -| **配置管理** | YAML 文件 | 路径 `~/.config/pt-snap-analyzer/queries/` | -| **Python 版本** | 3.10+ | 使用 type hints 和 match 语法 | -| **Conda 环境** | openclaw | 工作环境,已在规则中配置 | - -### 数据流 - -``` -用户/Agent → CLI/SDK → Context → Analyzers → SQLite - ↓ - Query Executor → YAML Templates - ↓ - RAG → ChromaDB -``` - ---- - -## Security & Privacy - -### 数据安全 - -- **数据本地化**: 所有分析在本地执行,不上传任何数据到云端 -- **数据库只读**: 分析时以 `file:...?mode=ro` 只读模式打开 SQLite,避免修改原始快照 -- **临时文件**: 临时文件存储在 `/tmp/pt-snap-analyzer-/`,退出时清理 - -### 敏感信息处理 - -- **调用栈脱敏**: RAG 案例中的调用栈默认脱敏用户路径 - ```python - # 原始:/home/zhangsan/projects/my-model/train.py:123 - # 脱敏:/home//projects//train.py:123 - ``` -- **文件路径**: 可选 --no-redact 保留原始路径(用于调试) -- **案例审核**: RAG 添加案例时提示用户检查敏感信息 - -### 权限要求 - -- **数据库文件**: 需要 read 权限 -- **配置文件**: 需要 read/write 权限(~/.config/) -- **RAG 数据库**: 需要 read/write 权限(~/.local/share/) - ---- - -## Testing Decisions - -### 测试原则 - -1. **只测试外部行为**: 不测试内部实现细节,只测试公开 API 的输入输出 -2. **测试隔离**: 每个测试用例独立,不依赖其他测试的状态 -3. **使用示例数据库**: 所有测试基于 `examples/snapshot_expandable.pkl.db` - -### 测试模块 - -1. **test_cli.py**: CLI 命令测试 - - 测试 `use` 命令设置数据库 - - 测试 `config` 命令配置设备 - - 测试 `analyze` 命令输出 JSON 格式 - - 测试 `query` 命令执行查询 - - 测试错误处理(无效数据库、无效查询等) - -2. **test_analyzers.py**: 分析器测试 - - 测试 `LeakDetector.detect_leaks()` 返回正确结果 - - 测试 `TrendAnalyzer.analyze_trend()` 返回时间序列 - - 测试 `StackAnalyzer.analyze_stack_trace()` 返回 Top-K 调用栈 - - 测试分析器边界条件(空数据库、大数据量) - -3. **test_query.py**: 查询模块测试 - - 测试 YAML 配置加载 - - 测试 SQL 模板渲染 - - 测试查询执行和结果格式化 - - 测试参数替换正确性 - -4. **test_rag.py**: RAG 模块测试 - - 测试案例添加和检索 - - 测试向量相似度搜索 - - 测试标签过滤 - - 测试案例更新/删除 - -### 测试覆盖率目标 - -- 单元测试覆盖率 > 80% -- 关键路径(分析器、查询执行)覆盖率 > 90% -- 通过 type checking (mypy) -- 通过 lint (ruff) - ---- - -## Out of Scope - -以下内容**不**在本 PRD 范围内: - -1. **GUI 界面**: 不提供图形化界面,仅 CLI 和 SDK -2. **实时分析**: 不支持实时内存监控,仅分析离线快照 -3. **多设备并行分析**: 阶段 1 仅支持单设备分析,多设备为后续扩展预留接口 -4. **自动修复**: 仅分析问题,不自动修复代码 -5. **性能优化**: 阶段 1 优先保证功能正确性,性能优化在后续迭代 -6. **其他框架支持**: 仅支持 PyTorch,不支持 TensorFlow/JAX 等 -7. **云端集成**: 不支持上传到云端分析,仅本地分析 - ---- - -## Further Notes - -### 分阶段交付 - -#### 阶段 1: MVP 核心框架 (2-3 周) -- CLI 基础命令 (use, config, analyze, query) -- SQLite 查询接口封装 -- 内存泄漏检测 (LeakDetector) -- JSON 输出格式定义 -- 基础单元测试 -- 预定义查询配置系统 -- AI Agent 调用示例/文档 - -#### 阶段 2: SDK + 高级分析 (2-3 周) -- Python SDK 封装 -- 峰值分析 (PeakAnalyzer) -- 趋势分析 (TrendAnalyzer) -- 调用栈分析 (StackAnalyzer) -- 对比分析 (Comparator) -- 查询配置管理 API -- SDK 使用文档 - -#### 阶段 3: RAG 知识库集成 (2-3 周) -- 知识库文档结构设计 -- RAG 检索引擎集成 -- CLI/SDK 集成 RAG 接口 -- 案例归档功能 (rag add) -- 完整文档和示例 - -### AI 友好设计要点 - -1. **结构化输出**: 所有命令默认输出 JSON,便于 AI 解析 -2. **确定性行为**: 相同输入 → 相同输出,AI 可预测结果 -3. **错误可解释**: 错误信息包含原因 + 建议修复方案 -4. **SDK 即代码**: AI 可直接生成 SDK 调用代码 -5. **知识库可检索**: RAG 让 AI 可访问先验经验 -6. **CLI 可组合**: AI 可组合多个 CLI 命令完成复杂分析 - -### AI Agent Integration - -#### SDK 调用示例 - -```python -from pt_snap_analyzer import Context, LeakDetector, PeakAnalyzer - -# AI Agent 创建分析上下文 -ctx = Context("snapshot.db", devices=[0]) - -# 检测内存泄漏 -leak_detector = LeakDetector(ctx) -leak_result = leak_detector.detect_leaks(min_size=1024) - -# AI 解析结果生成报告 -print("Leaks found:", len(leak_result.leaks)) -for leak in leak_result.leaks: - print(f" Block {leak.id}: {leak.size} bytes") - print(f" Callstack: {leak.callstack}") - -# 输出 JSON 供 AI 解析 -print(leak_result.model_dump_json()) -``` - -#### CLI 组合调用 - -```bash -# AI Agent 依次执行多个命令组合分析 -pt-snap use snapshot.db -pt-snap analyze leak --json --min-size 1024 > leaks.json -pt-snap analyze peak --json --top-k 5 > peaks.json -pt-snap analyze stack --top-k 10 --json > stacks.json - -# AI 解析三个 JSON 生成综合报告 -python -c " -import json -leaks = json.load(open('leaks.json')) -peaks = json.load(open('peaks.json')) -stacks = json.load(open('stacks.json')) -# AI 分析... -" -``` - -#### 错误处理示例 - -```python -from pt_snap_analyzer import Context -from pt_snap_analyzer.exceptions import DatabaseNotFoundError, SchemaVersionError - -try: - ctx = Context("invalid.db", devices=[0]) -except DatabaseNotFoundError as e: - print(f"Database not found: {e.path}") - print(f"Suggestion: Check if file exists or provide correct path") -except SchemaVersionError as e: - print(f"Schema version mismatch: expected {e.expected}, got {e.got}") - print(f"Suggestion: Run migration tool or regenerate snapshot") -``` - -### 已知风险 - -1. **SQLite 性能**: 大数据量场景下查询性能可能不足 - - **影响**: >10GB 数据库查询超时(>5s) - - **概率**: 中 - - **缓解**: - - 为常用字段(block.address, block.size, block.freeEventId)添加索引 - - 支持分页查询(LIMIT/OFFSET) - - 基准测试:600MB 数据库查询 < 1s - - 提供 --timeout 参数,超时后建议升级硬件 - -2. **Schema 变更**: DB schema 变更导致兼容性问题 - - **影响**: 旧版本数据库无法分析 - - **概率**: 低(schema 稳定) - - **缓解**: - - 在数据库中添加 version 表记录 schema 版本 - - 提供 migrate 工具自动升级 - - 不支持时给出明确错误和升级指引 - - 示例:"Schema v1 detected, current supported: v2. Run 'pt-snap migrate '" - -3. **RAG 质量**: 知识库案例质量参差不齐 - - **影响**: 检索到不相关/错误的解决方案 - - **概率**: 中 - - **缓解**: - - 引入案例评分机制(1-5 星) - - 支持人工审核(rag verify ) - - 检索时过滤低分案例(--min-score 3.0) - - 显示案例来源(human_verified vs auto_generated) - -4. **内存消耗**: ChromaDB 向量库占用大量内存 - - **影响**: 案例数 > 10k 时内存占用 > 1GB - - **概率**: 低(初期案例少) - - **缓解**: - - 使用持久化存储(磁盘) - - 支持 --rag-db-path 自定义路径 - - 定期清理低质量案例 - -5. **调用栈解析**: 不同 Python 版本/平台调用栈格式差异 - - **影响**: 调用栈解析失败或格式不一致 - - **概率**: 中 - - **缓解**: - - 使用标准库 traceback 解析 - - 提供调用栈格式检测 - - 无法解析时输出原始字符串 - -### 成功标准 - -#### 功能完整性 (Must Have) -- [ ] 所有预定义分析功能正常工作(leak, peak, trend, stack) -- [ ] CLI 命令覆盖所有核心场景(use, config, analyze, query, rag, compare) -- [ ] SDK API 文档完整(docstring 覆盖率 100%) -- [ ] 查询配置系统正常工作(YAML 加载、渲染、执行) -- [ ] RAG 知识库支持添加和检索 - -#### AI 友好性 (Must Have) -- [ ] AI Agent 可成功调用 CLI 和 SDK(无语法/格式错误) -- [ ] JSON 输出格式稳定、可解析(schema 验证通过) -- [ ] RAG 检索准确率 > 80%(Top-3 相关度评分) -- [ ] 错误信息包含原因和建议修复方案 -- [ ] CLI help 信息完整(--help 输出清晰) - -#### 代码质量 (Must Have) -- [ ] 单元测试覆盖率 > 80% -- [ ] 关键路径(分析器、查询执行)覆盖率 > 90% -- [ ] 通过 type checking (mypy --strict) -- [ ] 通过 lint (ruff check --select ALL) -- [ ] 无严重/高危安全漏洞(bandit 扫描) - -#### 用户体验 (Should Have) -- [ ] CLI help 信息清晰完整(每个子命令 --help 可用) -- [ ] 错误信息友好、可操作(包含建议) -- [ ] 示例文档齐全(examples/ 目录) -- [ ] 快速开始指南(README.md 前 3 屏内完成第一个分析) - -#### 性能指标 (Should Have) -- [ ] CLI 命令响应时间 < 1s(600MB 数据库) -- [ ] 泄漏检测 < 2s(10k 内存块) -- [ ] 调用栈分析 < 3s(10k 事件) -- [ ] RAG 检索 < 1s(1k 案例) - -#### 量化 KPI (Nice to Have) -- [ ] 泄漏检测准确率 > 90%(相比人工分析) -- [ ] AI Agent 调用成功率 > 95%(无错误) -- [ ] RAG 用户满意度 > 4.0/5.0(反馈评分) -- [ ] 文档阅读到实践转化率 > 30%(GitHub 访问/README 访问) - - -### 相关文件 - -- [设计文档](../specs/2026-04-04-pt-snap-analyzer-design.md) -- [Schema 文档](../../snapshot_db_schema.md) -- [约束规范](../../snapshot_db_constraint_spec.md) -- [示例数据库](../../examples/snapshot_expandable.pkl.db) diff --git a/.agents/superpowers/specs/.templates/checklist-template.md b/.agents/superpowers/specs/.templates/checklist-template.md deleted file mode 100644 index 5f24ca6..0000000 --- a/.agents/superpowers/specs/.templates/checklist-template.md +++ /dev/null @@ -1,85 +0,0 @@ -# 实现检查清单模板 - -## 功能检查 - -- [ ] 功能点1: 描述具体检查项 -- [ ] 功能点2: 描述具体检查项 -- [ ] 功能点3: 描述具体检查项 -- [ ] 所有需求规格中的功能都已实现 -- [ ] 功能符合需求规格中的预期行为 - -## 接口检查【可选】 - -- [ ] 接口定义符合设计文档 -- [ ] 接口参数验证完整 -- [ ] 返回值格式正确 -- [ ] 错误码定义完整 -- [ ] 接口文档已更新 - -## 错误处理检查 - -- [ ] 边界条件处理正确 -- [ ] 异常情况处理正确 -- [ ] 错误信息清晰易懂 -- [ ] 错误日志记录完整 -- [ ] 资源清理在 finally/异常处理中正确执行 - -## 性能检查【可选】 - -- [ ] 无明显的性能瓶颈 -- [ ] 数据库查询已优化 -- [ ] 必要的缓存已实现 -- [ ] 大数据量场景已考虑 - -## 安全检查 - -- [ ] 输入验证完整 -- [ ] SQL注入防护 -- [ ] XSS防护 -- [ ] 敏感数据加密 -- [ ] 权限控制正确 - -## 代码质量检查 - -- [ ] 代码遵循项目编码规范 -- [ ] 无重复代码 -- [ ] 函数/方法职责单一 -- [ ] 变量命名清晰 -- [ ] 无硬编码的敏感信息 - -## 测试检查 - -- [ ] 单元测试覆盖核心逻辑 -- [ ] 集成测试覆盖主要场景 -- [ ] 边界条件已测试 -- [ ] 异常情况已测试 -- [ ] 测试用例已评审 - -## 文档检查 - -- [ ] 代码注释完整清晰 -- [ ] API文档已更新 -- [ ] README已更新 -- [ ] 变更日志已更新 -- [ ] 部署文档已更新(如需要) - -## 部署检查【可选】 - -- [ ] 配置项已正确配置 -- [ ] 数据库迁移脚本已准备(如需要) -- [ ] 环境变量说明完整 -- [ ] 依赖版本已锁定 - -## 兼容性检查 - -- [ ] 向后兼容性已验证 -- [ ] 数据迁移方案已确认 -- [ ] 旧版本升级路径清晰 - -## 验收标准【可选】 - -- [ ] 所有功能需求已实现 -- [ ] 所有非功能需求已满足 -- [ ] 所有已知Bug已修复 -- [ ] 代码已通过Code Review -- [ ] 产品/需求方验收通过 \ No newline at end of file diff --git a/.agents/superpowers/specs/.templates/spec-template.md b/.agents/superpowers/specs/.templates/spec-template.md deleted file mode 100644 index ad1497f..0000000 --- a/.agents/superpowers/specs/.templates/spec-template.md +++ /dev/null @@ -1,105 +0,0 @@ -# 功能规格说明书模板 - -## Why - -描述功能开发的背景和动机: -- 当前痛点是什么 -- 需要解决什么问题 -- 预期的业务价值 - -## What Changes - -列出具体的变更内容: -- 新增功能/模块 -- 修改的组件 -- 删除的功能 -- 技术架构变更 - -## Impact - -### 影响的规格文档 -- 列出需要更新的相关规格文档 - -### 影响的代码模块 -- 列出需要修改的代码文件 -- 标注是新增文件还是修改现有文件 - -### 影响的依赖 -- 列出新增或变更的依赖项 -- 标注版本要求 - -### 影响的配置 -- 环境变量变更 -- 配置文件变更 -- 数据库变更 - -## ADDED Requirements - - -### Requirement: [需求名称] - -系统 SHALL [必须做什么]: - -- 参数1: 说明 -- 参数2: 说明 -- 参数N: 说明 - -#### Scenario: [场景名称] -- **GIVEN** [前置条件] -- **WHEN** [触发动作] -- **THEN** [预期结果] - -#### Scenario: [另一个场景名称] -- **GIVEN** [前置条件] -- **WHEN** [触发动作] -- **THEN** [预期结果] - -### Requirement: [另一个需求名称] -... - -## MODIFIED Requirements - - - -### Requirement: [需求名称] -- 原需求描述 -- 新需求描述 -- 变更原因 - -## REMOVED Requirements - -- [需求名称]: 移除原因 - -## Technical Design - - -### 架构设计 -- 系统架构图 -- 组件交互图 - -### 数据模型 -- 数据库表结构 -- 数据流程图 - -### API 设计 -- 接口定义 -- 请求/响应格式 - -## Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| ... | 高/中/低 | 高/中/低 | ... | - -## Success Criteria - -- [ ] 功能验收标准1 -- [ ] 功能验收标准2 -- [ ] 性能指标 -- [ ] 质量指标 - -## Appendix - -- 参考文档 -- 相关讨论 -- 设计决策记录 \ No newline at end of file diff --git a/.agents/superpowers/specs/.templates/tasks-template.md b/.agents/superpowers/specs/.templates/tasks-template.md deleted file mode 100644 index fd66dbb..0000000 --- a/.agents/superpowers/specs/.templates/tasks-template.md +++ /dev/null @@ -1,26 +0,0 @@ -# Tasks - -- [ ] Task 1: [任务名称] - - [ ] SubTask 1.1: [子任务名称] - - [ ] SubTask 1.2: [子任务名称] - - [ ] SubTask 1.3: [子任务名称] - -- [ ] Task 2: [任务名称] - - [ ] SubTask 2.1: [子任务名称] - - [ ] SubTask 2.2: [子任务名称] - - [ ] SubTask 2.3: [子任务名称] - -- [ ] Task 3: [任务名称] - - [ ] SubTask 3.1: [子任务名称] - - [ ] SubTask 3.2: [子任务名称] - -- [ ] Task 4: [任务名称] - - [ ] SubTask 4.1: [子任务名称] - - [ ] SubTask 4.2: [子任务名称] - -- ... - -# Task Dependencies -- [Task 2] depends on [Task 1] -- [Task 4] depends on [Task 1, Task 3] -- ... \ No newline at end of file diff --git a/.agents/superpowers/specs/analyzers/checklist.md b/.agents/superpowers/specs/analyzers/checklist.md deleted file mode 100644 index c48e61d..0000000 --- a/.agents/superpowers/specs/analyzers/checklist.md +++ /dev/null @@ -1,65 +0,0 @@ -# Checklist: pt-snap-analyzer 分析器模块 - -## Analyzer Base Class -- [ ] BaseAnalyzer ABC 正确定义 -- [ ] analyze() 方法签名正确 -- [ ] validate_context() 方法签名正确 -- [ ] 分析器可以继承 BaseAnalyzer - -## Analysis Models -- [ ] AnalysisResult dataclass 实现 -- [ ] AnalysisResult.to_dict() 方法实现 -- [ ] MemoryStats dataclass 实现 -- [ ] BlockStats dataclass 实现 - -## MemoryAnalyzer -- [ ] MemoryAnalyzer 类实现 -- [ ] total_allocated() 方法正确 -- [ ] total_active() 方法正确 -- [ ] total_reserved() 方法正确 -- [ ] memory_by_device() 方法正确 -- [ ] memory_by_stream() 方法正确 - -## EventAnalyzer -- [ ] EventAnalyzer 类实现 -- [ ] event_count_by_type() 方法正确 -- [ ] event_count_by_device() 方法正确 -- [ ] allocation_events() 方法正确 -- [ ] free_events() 方法正确 - -## BlockAnalyzer -- [ ] BlockAnalyzer 类实现 -- [ ] active_blocks() 方法正确 -- [ ] historical_blocks() 方法正确 -- [ ] block_size_distribution() 方法正确 -- [ ] block_lifecycle_stats() 方法正确 - -## CLI Integration -- [ ] CLI 分析命令实现 -- [ ] 分析结果显示正确 -- [ ] 错误处理正确 - -## Testing -- [ ] tests/test_analyzers.py 通过 -- [ ] 内存分析测试通过 -- [ ] 事件分析测试通过 -- [ ] 块分析测试通过 -- [ ] 集成测试通过 -- [ ] 覆盖率 >80% - -## Code Quality -- [ ] ruff check 无错误 -- [ ] black 格式化完成 -- [ ] isort 导入排序正确 -- [ ] 类型注解完整 -- [ ] 文档字符串完整 - -## Documentation -- [ ] 分析器 API 文档 -- [ ] 使用示例 -- [ ] 输出格式说明 - -## Version Control -- [ ] 所有 changes committed -- [ ] Commit message 清晰描述变更 -- [ ] Git log 历史清晰 diff --git a/.agents/superpowers/specs/analyzers/spec.md b/.agents/superpowers/specs/analyzers/spec.md deleted file mode 100644 index ffdc788..0000000 --- a/.agents/superpowers/specs/analyzers/spec.md +++ /dev/null @@ -1,344 +0,0 @@ -# Spec: pt-snap-analyzer 分析器模块 - -**Goal:** 实现核心分析器模块:泄漏检测、峰值分析、趋势分析、调用栈分析 - -**Architecture:** 基于 AnalyzerBase 抽象基类,每个分析器实现独立的 analyze() 方法,返回结构化结果 - -**Tech Stack:** Python 3.10+, SQLite3, Pydantic - ---- - -## Why - -### 当前痛点 -- 开发者无法快速识别内存泄漏问题,需要人工逐行分析事件日志 -- 内存峰值出现时无法定位原因,缺少系统化的分析工具 -- 内存使用趋势不明朗,无法预测潜在的内存风险 -- 调用栈信息分散,难以关联到具体的代码位置 - -### 需要解决的问题 -- 实现自动化的泄漏检测算法,识别异常的内存分配模式 -- 分析内存峰值时刻的上下文信息,定位峰值原因 -- 统计内存使用趋势,提供预警机制 -- 聚合调用栈信息,关联到具体的代码位置 - -### 预期的业务价值 -- 内存泄漏检测时间从数小时降低到分钟级别 -- 峰值分析效率提升 70% 以上 -- 提前发现 80% 以上的内存风险 -- 减少人工分析工作量,提高开发效率 - ---- - -## What Changes - -### 新增功能/模块 -- AnalyzerBase 抽象基类:定义分析器接口 -- LeakDetector:泄漏检测分析器 -- PeakAnalyzer:峰值分析分析器 -- TrendAnalyzer:趋势分析分析器 -- StackAnalyzer:调用栈分析分析器 -- AnalysisResult 基类:分析结果数据结构 -- LeakResult/PeakResult/TrendResult/StackResult:专用结果类型 - -### 修改的组件 -- `pt_snap_analyzer/cli.py` - 新增分析命令 -- `pt_snap_analyzer/models/__init__.py` - 导出新的结果模型 - -### 删除的功能 -- 无 - -### 技术架构变更 -- 引入抽象基类模式 -- 分析器插件化架构 - ---- - -## Impact - -### 影响的规格文档 -- foundation/spec.md - 依赖 Context 类 - -### 影响的代码模块 -- `pt_snap_analyzer/analyzers/__init__.py` - 新增:包初始化 -- `pt_snap_analyzer/analyzers/base.py` - 新增:分析器基类 -- `pt_snap_analyzer/analyzers/leak_detector.py` - 新增:泄漏检测 -- `pt_snap_analyzer/analyzers/peak_analyzer.py` - 新增:峰值分析 -- `pt_snap_analyzer/analyzers/trend_analyzer.py` - 新增:趋势分析 -- `pt_snap_analyzer/analyzers/stack_analyzer.py` - 新增:调用栈分析 -- `pt_snap_analyzer/models/result.py` - 新增:分析结果基类 -- `pt_snap_analyzer/models/leak.py` - 新增:泄漏结果 -- `pt_snap_analyzer/models/peak.py` - 新增:峰值结果 -- `pt_snap_analyzer/models/trend.py` - 新增:趋势结果 -- `pt_snap_analyzer/models/stack.py` - 新增:调用栈结果 - -### 影响的依赖 -- 无新增依赖(使用 foundation 已有依赖) - -### 影响的配置 -- 无环境变量变更 -- 无配置文件变更 - ---- - -## ADDED Requirements - -### Requirement: AnalyzerBase 抽象基类 -系统 SHALL 定义分析器抽象基类: - -- name: 分析器名称 -- description: 分析器描述 -- context: 分析上下文 -- analyze(**kwargs) -> AnalysisResult: 执行分析 -- validate_context(context) -> bool: 验证上下文 - -#### Scenario: 继承分析器 -- **GIVEN** AnalyzerBase 基类已定义 -- **WHEN** 创建子类并实现 analyze() 方法 -- **THEN** 可以正常实例化并执行分析 - -### Requirement: LeakDetector 泄漏检测 -系统 SHALL 实现泄漏检测分析器: - -- 检测未释放的内存块 -- 识别重复分配模式 -- 定位泄漏源(调用栈) -- 返回泄漏统计信息 - -#### Scenario: 检测内存泄漏 -- **GIVEN** 数据库包含未释放的内存块 -- **WHEN** 执行 LeakDetector.analyze() -- **THEN** 返回泄漏块列表和调用栈信息 - -### Requirement: PeakAnalyzer 峰值分析 -系统 SHALL 实现峰值分析分析器: - -- 识别内存峰值时刻 -- 分析峰值时的活跃块 -- 统计峰值贡献者 -- 返回峰值详情 - -#### Scenario: 分析内存峰值 -- **GIVEN** 数据库包含完整的事件历史 -- **WHEN** 执行 PeakAnalyzer.analyze() -- **THEN** 返回峰值时间、峰值大小、主要贡献者 - -### Requirement: TrendAnalyzer 趋势分析 -系统 SHALL 实现趋势分析分析器: - -- 计算内存使用趋势 -- 识别异常增长点 -- 预测未来趋势 -- 返回趋势统计 - -#### Scenario: 分析内存趋势 -- **GIVEN** 数据库包含长时间跨度的事件 -- **WHEN** 执行 TrendAnalyzer.analyze() -- **THEN** 返回趋势线、增长率、异常点 - -### Requirement: StackAnalyzer 调用栈分析 -系统 SHALL 实现调用栈分析分析器: - -- 聚合调用栈信息 -- 统计各栈的内存使用 -- 识别高频分配位置 -- 返回调用栈统计 - -#### Scenario: 分析调用栈 -- **GIVEN** 数据库包含调用栈信息 -- **WHEN** 执行 StackAnalyzer.analyze() -- **THEN** 返回调用栈排名和内存使用统计 - -### Requirement: AnalysisResult 结果类 -系统 SHALL 定义分析结果基类: - -- metadata: 元数据 -- to_dict() -> Dict: 转换为字典 -- to_json() -> str: 转换为 JSON - -#### Scenario: 结果序列化 -- **GIVEN** 分析结果实例 -- **WHEN** 调用 to_json() 方法 -- **THEN** 返回有效的 JSON 字符串 - ---- - -## MODIFIED Requirements -无 - -## REMOVED Requirements -无 - ---- - -## 1. Overview - -### 1.1 Purpose -实现 pt-snap-analyzer 的核心分析功能,提供对 PyTorch 内存快照的深度分析能力。 - -### 1.2 Scope -- 分析器框架设计与实现 -- 泄漏检测分析器 -- 峰值分析分析器 -- 趋势分析分析器 -- 调用栈分析分析器 -- 分析结果模型定义 - ---- - -## 2. Technical Architecture - -### 2.1 File Structure -``` -pt_snap_analyzer/ -├── analyzers/ -│ ├── __init__.py -│ ├── base.py # AnalyzerBase 抽象基类 -│ ├── leak_detector.py # 泄漏检测 -│ ├── peak_analyzer.py # 峰值分析 -│ ├── trend_analyzer.py # 趋势分析 -│ └── stack_analyzer.py # 调用栈分析 -├── models/ -│ ├── result.py # AnalysisResult 基类 -│ ├── leak.py # LeakResult -│ ├── peak.py # PeakResult -│ ├── trend.py # TrendResult -│ └── stack.py # StackResult -└── cli.py # 新增分析命令 -``` - -### 2.2 Analyzer Pattern - -#### AnalyzerBase (ABC) -**Abstract Base Class for Analysers** - -**Key Methods:** -- `analyze(**kwargs) -> AnalysisResult` - Execute analysis -- `validate_context(context: Context) -> bool` - Validate context - -**Attributes:** -- `name: str` - Analyzer name -- `description: str` - Analyzer description -- `context: Context` - Analysis context - -#### AnalysisResult -**Base class for analysis results** - -**Key Methods:** -- `to_dict() -> Dict[str, Any]` - Convert to dictionary -- `to_json() -> str` - Convert to JSON string - -**Attributes:** -- `metadata: Dict[str, Any]` - Analysis metadata - -### 2.3 Analyzer Implementations - -#### LeakDetector -**Detects memory leaks** - -**Key Methods:** -- `analyze(min_size=0, top_n=10) -> LeakResult` - Detect leaks -- `_find_unreleased_blocks()` - Find unreleased blocks -- `_identify_leak_patterns()` - Identify leak patterns - -#### PeakAnalyzer -**Analyzes memory peaks** - -**Key Methods:** -- `analyze(top_k=5) -> PeakResult` - Analyze peaks -- `_find_peak_moments()` - Find peak moments -- `_analyze_peak_contributors()` - Analyze contributors - -#### TrendAnalyzer -**Analyzes memory usage trends** - -**Key Methods:** -- `analyze(window_size=100) -> TrendResult` - Analyze trends -- `_calculate_moving_average()` - Calculate MA -- `_detect_anomalies()` - Detect anomalies - -#### StackAnalyzer -**Analyzes call stacks** - -**Key Methods:** -- `analyze(min_count=1) -> StackResult` - Analyze stacks -- `_aggregate_stacks()` - Aggregate call stacks -- `_rank_by_frequency()` - Rank by frequency - ---- - -## 3. Implementation Requirements - -### 3.1 Dependencies -无新增依赖,使用 foundation 模块的依赖。 - -### 3.2 Testing Strategy -- 单元测试:每个分析器独立测试 -- 集成测试:使用示例数据库测试 -- 边界测试:空数据库、无事件、无泄漏等场景 -- 覆盖率目标:>80% - ---- - -## 4. Success Criteria -- [ ] 所有分析器正确实现 -- [ ] 泄漏检测准确 -- [ ] 峰值分析正确 -- [ ] 趋势分析合理 -- [ ] 调用栈分析完整 -- [ ] 所有单元测试通过 -- [ ] 测试覆盖率 >80% -- [ ] 代码通过 ruff 检查 -- [ ] 代码通过 black 格式化 - ---- - -## 5. Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| 泄漏检测算法误判 | 高 | 中 | 提供可配置的阈值,支持人工确认 | -| 峰值分析性能问题 | 中 | 中 | 使用 SQL 聚合查询,避免 Python 层计算 | -| 趋势分析准确性 | 中 | 中 | 使用多种算法对比,提供置信度指标 | -| 调用栈信息缺失 | 高 | 低 | 优雅降级,返回部分分析结果 | -| 分析器耦合 | 中 | 低 | 严格遵守抽象基类接口,保持独立性 | -| 结果格式化复杂 | 低 | 中 | 使用统一的 to_dict() 方法,便于序列化 | - ---- - -## 6. Appendix - -### 参考文档 -- [Python ABC](https://docs.python.org/3/library/abc.html) -- [SQLite 聚合函数](https://www.sqlite.org/lang_aggfunc.html) -- [统计分析算法](https://en.wikipedia.org/wiki/Statistical_analysis) - -### 相关讨论 -- 泄漏检测算法设计 -- 峰值定义和识别策略 -- 趋势分析方法选择 - -### 设计决策记录 -1. **使用抽象基类而非 Protocol**: 更清晰的继承关系,便于扩展 -2. **分析器独立实现**: 每个分析器专注于单一职责,便于测试和维护 -3. **结果统一序列化**: 所有结果支持 to_dict() 和 to_json(),便于 CLI 输出 -4. **可配置参数**: 每个分析器支持参数调整,适应不同场景 - -### 示例输出 -```json -{ - "analyzer": "LeakDetector", - "timestamp": "2026-04-04T10:00:00Z", - "metadata": { - "total_leaks": 5, - "leaked_bytes": 1048576 - }, - "leaks": [ - { - "address": "0x1000", - "size": 262144, - "stack": "train.py:42" - } - ] -} -``` diff --git a/.agents/superpowers/specs/analyzers/tasks.md b/.agents/superpowers/specs/analyzers/tasks.md deleted file mode 100644 index 2f64a31..0000000 --- a/.agents/superpowers/specs/analyzers/tasks.md +++ /dev/null @@ -1,47 +0,0 @@ -# Tasks: pt-snap-analyzer 分析器模块 - ---- - -## Task List - -- [ ] Task 1: 分析器基类和数据模型 - - [ ] Step 1: 创建 analysis 数据模型 (AnalysisResult, MemoryStats, BlockStats) - - [ ] Step 2: 创建 AnalyzerBase 抽象基类 - - [ ] Step 3: 创建 models 初始化文件 - - [ ] Step 4: 创建测试文件 - - [ ] Step 5: 运行测试 - - [ ] Step 6: Commit - -- [ ] Task 2: 泄漏检测分析器 - - [ ] Step 1: 创建泄漏数据模型 (LeakInfo, LeakResult) - - [ ] Step 2: 创建泄漏检测分析器 - - [ ] Step 3: 创建测试文件 - - [ ] Step 4: 运行测试 - - [ ] Step 5: Commit - -- [ ] Task 3: 峰值分析器 - - [ ] Step 1: 创建峰值数据模型 (PeakInfo, PeakResult) - - [ ] Step 2: 创建峰值分析器 - - [ ] Step 3: 创建测试文件 - - [ ] Step 4: 运行测试 - - [ ] Step 5: Commit - -- [ ] Task 4: 块生命周期分析器 - - [ ] Step 1: 创建生命周期分析器 - - [ ] Step 2: 创建测试文件 - - [ ] Step 3: 运行测试 - - [ ] Step 4: Commit - -- [ ] Task 5: CLI 集成和 SDK - - [ ] Step 1: 扩展 CLI 命令 - - [ ] Step 2: 更新 SDK 导出 - - [ ] Step 3: 创建集成测试 - - [ ] Step 4: 运行测试 - - [ ] Step 5: Commit - -## Task Dependencies - -- Task 2 depends on Task 1 -- Task 3 depends on Task 2 -- Task 4 depends on Task 3 -- Task 5 depends on Task 4 diff --git a/.agents/superpowers/specs/foundation/checklist.md b/.agents/superpowers/specs/foundation/checklist.md deleted file mode 100644 index bc19584..0000000 --- a/.agents/superpowers/specs/foundation/checklist.md +++ /dev/null @@ -1,69 +0,0 @@ -# Checklist: pt-snap-analyzer 基础架构 - -## Project Setup -- [x] pyproject.toml 配置正确 -- [x] dependencies 包含所有必需库 -- [x] optional-dependencies 包含 dev 工具 -- [x] 项目可以正常安装 `pip install -e .[dev]` - -## Data Models -- [x] EventType 枚举值正确定义(0-7) -- [x] BlockState 枚举值正确定义(-1, 0, 1, 99) -- [x] EventType 是 IntEnum 子类 -- [x] BlockState 是 IntEnum 子类 -- [x] MemoryEvent 数据类实现 -- [x] MemoryBlock 数据类实现 -- [ ] MemoryEvent.from_row() 类方法实现(未要求) -- [ ] MemoryBlock.from_row() 类方法实现(未要求) -- [x] MemoryEvent.is_virtual_event 属性正确 -- [x] MemoryEvent.is_runtime_event 属性正确 -- [x] MemoryBlock.is_historical_block 属性正确 -- [x] MemoryBlock.is_active 属性正确 -- [ ] MemoryBlock.block_state 属性正确(未要求) - -## Context Class -- [x] DatabaseNotFoundError 异常类实现 -- [x] SchemaVersionError 异常类实现 -- [x] Context 类实现 -- [x] __init__ 方法验证数据库路径 -- [x] _open_database 方法以只读模式打开数据库(通过 connect) -- [x] _validate_schema 方法验证 schema 版本 -- [x] device_ids 属性正确获取设备 ID -- [x] cursor() 方法返回数据库游标 -- [x] connect() 方法作为上下文管理器工作 -- [x] close() 方法正确关闭连接 - -## CLI Framework -- [x] Typer app 正确初始化 -- [x] app.name 正确为 "pt-snap" -- [x] CLI use 命令实现 -- [x] db_path 参数正确配置 -- [x] DatabaseNotFoundError 异常处理 - -## Testing -- [x] tests/test_enums.py 通过(6 tests) -- [x] tests/test_event.py 通过(4 tests) -- [x] tests/test_block.py 通过(6 tests) -- [x] tests/test_context.py 通过(8 tests) -- [x] tests/test_cli.py 通过(4 tests) -- [x] tests/test_models.py 通过(4 tests) -- [x] tests/test_package.py 通过(1 test) -- [x] 总测试通过(33 tests) -- [x] 覆盖率 >80%(达到 95%) - -## Code Quality -- [x] ruff check 无错误 -- [x] black 格式化完成 -- [x] 类型注解完整 -- [x] 文档字符串完整 - -## Documentation -- [ ] README.md 包含项目介绍(未要求) -- [ ] README.md 包含安装说明(未要求) -- [ ] README.md 包含快速开始(未要求) -- [ ] README.md 包含 API 文档链接(未要求) - -## Version Control -- [x] 所有 changes committed -- [x] Commit message 清晰描述变更 -- [x] Git log 历史清晰 \ No newline at end of file diff --git a/.agents/superpowers/specs/foundation/spec.md b/.agents/superpowers/specs/foundation/spec.md deleted file mode 100644 index 0e9a5ea..0000000 --- a/.agents/superpowers/specs/foundation/spec.md +++ /dev/null @@ -1,344 +0,0 @@ -# Spec: pt-snap-analyzer 基础架构 - -**Goal:** 构建 CLI 框架、数据模型和核心 Context,提供基础 API 支撑 - -**Architecture:** 基于 Typer 构建 CLI 框架,Pydantic 定义数据模型,SQLite 管理数据库连接 - -**Tech Stack:** Python 3.10+, Typer, Pydantic, SQLite3 - ---- - -## Why - -### 当前痛点 -- PyTorch 内存快照分析工具缺失,开发者难以理解内存分配模式 -- 现有工具缺乏 CLI 接口,不利于集成到自动化流程 -- 没有统一的数据模型和分析上下文管理,代码复用困难 -- 内存问题排查依赖人工经验,效率低下 - -### 需要解决的问题 -- 提供易用的 CLI 工具,支持快速查看和分析内存快照 -- 定义标准化的数据模型,统一事件和块的表示 -- 实现数据库连接管理,简化查询操作 -- 为后续分析器、查询系统、RAG 知识库奠定基础 - -### 预期的业务价值 -- 提升 PyTorch 内存问题排查效率 50% 以上 -- 降低内存泄漏和碎片化问题的定位时间 -- 支持 AI 辅助分析,减少人工介入 -- 提供可扩展的架构,便于后续功能迭代 - ---- - -## What Changes - -### 新增功能/模块 -- CLI 框架:基于 Typer 的命令行接口 -- 数据模型:EventType、BlockState 枚举,MemoryEvent、MemoryBlock 数据类 -- Context 类:数据库连接管理和生命周期控制 -- 项目配置:pyproject.toml、版本管理 - -### 修改的组件 -- 无(全新模块) - -### 删除的功能 -- 无 - -### 技术架构变更 -- 无(全新架构) - ---- - -## Impact - -### 影响的规格文档 -- 无(初始版本) - -### 影响的代码模块 -- `pt_snap_analyzer/__init__.py` - 新增:包初始化 -- `pt_snap_analyzer/version.py` - 新增:版本信息 -- `pt_snap_analyzer/cli.py` - 新增:CLI 入口 -- `pt_snap_analyzer/context.py` - 新增:Context 类 -- `pt_snap_analyzer/models/__init__.py` - 新增:模型导出 -- `pt_snap_analyzer/models/_enums.py` - 新增:枚举定义 -- `pt_snap_analyzer/models/event.py` - 新增:MemoryEvent 模型 -- `pt_snap_analyzer/models/block.py` - 新增:MemoryBlock 模型 - -### 影响的依赖 -- `typer>=0.9.0` - 新增:CLI 框架 -- `pydantic>=2.0.0` - 新增:数据验证(后续使用) -- `pyyaml>=6.0` - 新增:YAML 支持(后续使用) -- `chromadb>=0.4.0` - 新增:向量数据库(RAG 使用) -- `langchain>=0.1.0` - 新增:AI 框架(RAG 使用) -- `pytest>=7.0.0` - 新增:测试框架(dev) -- `pytest-cov>=4.0.0` - 新增:覆盖率工具(dev) -- `black>=23.0.0` - 新增:代码格式化(dev) -- `ruff>=0.0.280` - 新增:代码检查(dev) - -### 影响的配置 -- `pyproject.toml` - 新增:项目配置 -- 环境变量:无 -- 配置文件:无 -- 数据库:使用现有快照数据库(只读) - ---- - -## ADDED Requirements - -### Requirement: CLI 框架 -系统 SHALL 提供命令行接口: - -- 命令名称:pt-snap -- 参数:db_path - 数据库路径 -- 功能:设置当前分析数据库 - -#### Scenario: 使用有效数据库 -- **GIVEN** 存在有效的 SQLite 数据库文件 -- **WHEN** 执行 `pt-snap use ` -- **THEN** 输出 "Using database: " - -#### Scenario: 数据库不存在 -- **GIVEN** 数据库文件不存在 -- **WHEN** 执行 `pt-snap use ` -- **THEN** 输出错误信息并退出 - -### Requirement: EventType 枚举 -系统 SHALL 定义内存事件类型: - -- SEGMENT_MAP = 0 -- SEGMENT_UNMAP = 1 -- SEGMENT_ALLOC = 2 -- SEGMENT_FREE = 3 -- ALLOC = 4 -- FREE_REQUESTED = 5 -- FREE_COMPLETED = 6 -- WORKSPACE_SNAPSHOT = 7 - -#### Scenario: 枚举值正确 -- **GIVEN** EventType 枚举已定义 -- **WHEN** 访问枚举值 -- **THEN** 返回正确的整数值 - -### Requirement: BlockState 枚举 -系统 SHALL 定义内存块状态: - -- INACTIVE = -1 -- ACTIVE_PENDING_FREE = 0 -- ACTIVE_ALLOCATED = 1 -- UNKNOWN = 99 - -#### Scenario: 枚举值正确 -- **GIVEN** BlockState 枚举已定义 -- **WHEN** 访问枚举值 -- **THEN** 返回正确的整数值 - -### Requirement: MemoryEvent 数据类 -系统 SHALL 定义内存事件数据类: - -- id: 事件 ID -- action: EventType -- address: 内存地址 -- size: 分配大小 -- stream: CUDA/CANN 流 ID -- allocated: 总已分配内存 -- active: 总活跃内存 -- reserved: 总保留内存 -- callstack: 调用栈信息 - -#### Scenario: 虚拟事件检测 -- **GIVEN** 事件 ID < 0 -- **WHEN** 访问 is_virtual_event 属性 -- **THEN** 返回 True - -#### Scenario: 运行时事件检测 -- **GIVEN** 事件 ID >= 0 -- **WHEN** 访问 is_runtime_event 属性 -- **THEN** 返回 True - -### Requirement: MemoryBlock 数据类 -系统 SHALL 定义内存块数据类: - -- id: 块 ID -- address: 内存地址 -- size: 实际分配大小 -- requestedSize: 用户请求大小 -- state: 块状态 -- allocEventId: 分配事件 ID -- freeEventId: 释放事件 ID - -#### Scenario: 历史块检测 -- **GIVEN** 块 ID < 0 -- **WHEN** 访问 is_historical_block 属性 -- **THEN** 返回 True - -#### Scenario: 活跃块检测 -- **GIVEN** 块未释放(freeEventId is None 或 -1) -- **WHEN** 访问 is_active 属性 -- **THEN** 返回 True - -### Requirement: Context 类 -系统 SHALL 实现数据库上下文管理: - -- db_path: 数据库路径 -- devices: 设备 ID 列表(可选) -- device_ids: 获取设备 ID 列表 -- cursor(): 获取数据库游标 -- connect(): 上下文管理器 -- close(): 关闭连接 - -#### Scenario: 打开有效数据库 -- **GIVEN** 有效的 SQLite 数据库文件 -- **WHEN** 创建 Context 实例 -- **THEN** 成功打开连接 - -#### Scenario: 数据库不存在 -- **GIVEN** 数据库文件不存在 -- **WHEN** 创建 Context 实例 -- **THEN** 抛出 DatabaseNotFoundError - -#### Scenario: Schema 验证失败 -- **GIVEN** 数据库缺少 dictionary 表 -- **WHEN** 创建 Context 实例 -- **THEN** 抛出 SchemaVersionError - ---- - -## MODIFIED Requirements -无 - -## REMOVED Requirements -无 - ---- - -## 1. Overview - -### 1.1 Purpose -构建 pt-snap-analyzer 项目的基础框架,包括 CLI 入口、数据模型定义、Context 类管理数据库连接。 - -### 1.2 Scope -- CLI 命令框架设计与实现 -- 数据模型定义(EventType、BlockState 枚举,MemoryEvent、MemoryBlock 数据类) -- Context 类实现数据库连接管理和生命周期控制 -- 版本管理和项目配置 - ---- - -## 2. Technical Architecture - -### 2.1 File Structure -``` -pt_snap_analyzer/ -├── __init__.py # Package exports -├── cli.py # CLI entry point with Typer -├── context.py # Context class for DB management -├── models/ -│ ├── __init__.py # Models exports -│ ├── _enums.py # Enum types (EventType, BlockState) -│ ├── event.py # MemoryEvent model -│ └── block.py # MemoryBlock model -├── version.py # Package version -└── __init__.py -``` - -### 2.2 Data Models - -#### EventType (IntEnum) -- `SEGMENT_MAP = 0` - Segment mapping -- `SEGMENT_UNMAP = 1` - Segment unmapping -- `SEGMENT_ALLOC = 2` - Segment allocation -- `SEGMENT_FREE = 3` - Segment freeing -- `ALLOC = 4` - Memory allocation -- `FREE_REQUESTED = 5` - Free requested -- `FREE_COMPLETED = 6` - Free completed -- `WORKSPACE_SNAPSHOT = 7` - Workspace snapshot - -#### BlockState (IntEnum) -- `INACTIVE = -1` - Inactive state -- `ACTIVE_PENDING_FREE = 0` - Active, pending free -- `ACTIVE_ALLOCATED = 1` - Active, allocated -- `UNKNOWN = 99` - Unknown state - -### 2.3 Context Class -**Responsibilities:** -- Database connection management (read-only mode) -- Schema version validation -- Device ID discovery and filtering -- Connection lifecycle control - -**Key Methods:** -- `__init__(db_path, devices=None)` - Initialize context -- `device_ids` - Get list of device IDs -- `cursor()` - Get database cursor -- `connect()` - Context manager for connection -- `close()` - Close database connection - ---- - -## 3. Implementation Requirements - -### 3.1 Dependencies -```toml -dependencies = [ - "typer>=0.9.0", - "pydantic>=2.0.0", - "pyyaml>=6.0", - "chromadb>=0.4.0", - "langchain>=0.1.0", -] -``` - -### 3.2 Testing Strategy -- Unit tests for each module -- Coverage target: >80% -- Test database with sample schema - ---- - -## 4. Success Criteria -- [ ] CLI 可以正常运行 `pt-snap --help` -- [ ] 所有数据模型正确实现 -- [ ] Context 类可以正确连接和管理数据库 -- [ ] 所有单元测试通过 -- [ ] 项目可以正常安装 `pip install -e .[dev]` -- [ ] 测试覆盖率 >80% -- [ ] 代码通过 ruff 检查 -- [ ] 代码通过 black 格式化 - ---- - -## 5. Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| 数据库格式变更 | 高 | 低 | Context 类实现 schema 版本验证,提前检测不兼容 | -| 依赖库版本冲突 | 中 | 中 | 在 pyproject.toml 中固定最小版本,使用 dev 依赖隔离 | -| SQLite 只读模式限制 | 低 | 低 | 仅读取数据,不需要写入,只读模式更安全 | -| 大型数据库性能问题 | 中 | 中 | 数据库以只读模式打开,避免锁竞争;后续考虑索引优化 | -| Python 版本兼容性 | 中 | 低 | 限制 Python 3.10+,使用类型注解和新特性 | -| CLI 参数验证不足 | 中 | 中 | 使用 Typer 的参数验证功能,添加适当的错误处理 | - ---- - -## 6. Appendix - -### 参考文档 -- [Typer 文档](https://typer.tiangolo.com/) -- [Pydantic 文档](https://docs.pydantic.dev/) -- [SQLite3 文档](https://docs.python.org/3/library/sqlite3.html) -- [pytest 文档](https://docs.pytest.org/) - -### 相关讨论 -- PyTorch 内存快照格式分析 -- 数据库 schema 设计讨论 - -### 设计决策记录 -1. **选择 Typer 而非 argparse**: Typer 提供类型注解支持,更现代,自动帮助文档 -2. **使用 dataclass 而非 Pydantic**: 基础模块保持轻量,Pydantic 用于后续复杂场景 -3. **SQLite 只读模式**: 分析工具不应修改原始数据,保证数据完整性 -4. **枚举使用 IntEnum**: 便于与数据库整数值互操作 - -### 示例数据库 -- 位置:`examples/snapshot_expandable.pkl.db` -- 格式:SQLite3 -- Schema 版本:v1.0(通过 dictionary 表验证) diff --git a/.agents/superpowers/specs/foundation/tasks.md b/.agents/superpowers/specs/foundation/tasks.md deleted file mode 100644 index 1800ad4..0000000 --- a/.agents/superpowers/specs/foundation/tasks.md +++ /dev/null @@ -1,54 +0,0 @@ -# Tasks: pt-snap-analyzer 基础架构 - ---- - -## Task List - -- [x] Task 1: 项目初始化和配置 - - [x] Step 1: 创建包初始化文件 - - [x] Step 2: 创建版本信息文件 - - [x] Step 3: 创建 pyproject.toml - - [x] Step 4: 创建示例数据库符号链接 - - [x] Step 5: 运行安装测试 - - [x] Step 6: Commit - -- [x] Task 2: 数据模型 - 枚举类型和基类 - - [x] Step 1: 创建枚举模块 (EventType, BlockState) - - [x] Step 2: 创建 models 初始化文件 - - [x] Step 3: 创建测试文件 - - [x] Step 4: 运行测试 - - [x] Step 5: Commit - -- [x] Task 3: 数据模型 - MemoryEvent 和 MemoryBlock - - [x] Step 1: 创建 MemoryEvent 模型 - - [x] Step 2: 创建 MemoryBlock 模型 - - [x] Step 3: 创建测试文件 - - [x] Step 4: 运行测试 - - [x] Step 5: Commit - -- [x] Task 4: Context 类 - 数据库连接管理 - - [x] Step 1: 创建 Context 类 - - [x] Step 2: 创建测试文件 - - [x] Step 3: 运行测试 - - [x] Step 4: Commit - -- [x] Task 5: CLI 框架 - 命令结构 - - [x] Step 1: 创建 CLI 入口 - - [x] Step 2: 创建 CLI 测试 - - [x] Step 3: 运行测试 - - [x] Step 4: 手动测试 CLI - - [x] Step 5: Commit - -- [x] Task 6: 集成测试和文档 - - [x] Step 1: 运行所有测试 - - [x] Step 2: 代码质量检查 - - [ ] Step 3: 文档(未要求) - - [ ] Step 4: 最终 Commit - -## Task Dependencies - -- Task 2 depends on Task 1 -- Task 3 depends on Task 2 -- Task 4 depends on Task 3 -- Task 5 depends on Task 4 -- Task 6 depends on Task 5 \ No newline at end of file diff --git a/.agents/superpowers/specs/query/checklist.md b/.agents/superpowers/specs/query/checklist.md deleted file mode 100644 index 155e909..0000000 --- a/.agents/superpowers/specs/query/checklist.md +++ /dev/null @@ -1,69 +0,0 @@ -# Checklist: pt-snap-analyzer 查询系统 - -## Query Conditions -- [ ] Condition ABC 正确定义 -- [ ] Equal 条件正确实现 -- [ ] NotEqual 条件正确实现 -- [ ] GreaterThan 条件正确实现 -- [ ] LessThan 条件正确实现 -- [ ] In 条件正确实现 -- [ ] Like 条件正确实现 -- [ ] And 条件正确实现 -- [ ] Or 条件正确实现 - -## Query Builder -- [ ] QueryBuilder 类正确实现 -- [ ] from_table() 方法正确 -- [ ] where() 方法正确 -- [ ] order_by() 方法正确 -- [ ] limit() 方法正确 -- [ ] offset() 方法正确 -- [ ] build() 方法正确生成 SQL -- [ ] execute() 方法正确执行查询 - -## Query Registry -- [ ] 注册表正确实现 -- [ ] register_query 装饰器正确 -- [ ] get_query() 函数正确 -- [ ] list_queries() 函数正确 -- [ ] preregistered queries 正确 - -## Result Mapper -- [ ] ResultMapper 类正确实现 -- [ ] register() 方法正确 -- [ ] map() 方法正确 -- [ ] map_all() 方法正确 -- [ ] map_to_events() 函数正确 -- [ ] map_to_blocks() 函数正确 -- [ ] map_to_analysis() 函数正确 - -## CLI Integration -- [ ] CLI query 命令正确 -- [ ] CLI list-queries 命令正确 -- [ ] 查询名验证正确 -- [ ] 错误处理正确 - -## Testing -- [ ] tests/test_conditions.py 通过(8 tests) -- [ ] tests/test_builder.py 通过(7 tests) -- [ ] tests/test_registry.py 通过(3 tests) -- [ ] tests/test_mapper.py 通过(5 tests) -- [ ] 集成测试通过 -- [ ] 覆盖率 >80% - -## Code Quality -- [ ] ruff check 无错误 -- [ ] black 格式化完成 -- [ ] isort 导入排序正确 -- [ ] 类型注解完整 -- [ ] 文档字符串完整 - -## Documentation -- [ ] 查询 API 文档 -- [ ] 使用示例 -- [ ] 查询名列表 - -## Version Control -- [ ] 所有 changes committed -- [ ] Commit message 清晰描述变更 -- [ ] Git log 历史清晰 diff --git a/.agents/superpowers/specs/query/spec.md b/.agents/superpowers/specs/query/spec.md deleted file mode 100644 index 525cdfd..0000000 --- a/.agents/superpowers/specs/query/spec.md +++ /dev/null @@ -1,344 +0,0 @@ -# Spec: pt-snap-analyzer 查询系统 - -**Goal:** 实现查询配置系统,支持 YAML 配置的 SQL 模板和查询执行器 - -**Architecture:** YAML 配置存储 SQL 模板,查询执行器渲染模板并执行查询,支持参数替换和设备适配 - -**Tech Stack:** Python 3.10+, SQLite3, PyYAML, Jinja2 - ---- - -## Why - -### 当前痛点 -- 硬编码 SQL 查询语句,难以维护和扩展 -- 每次新增查询需要修改代码,不符合开闭原则 -- 查询参数化困难,不同场景需要不同的查询条件 -- 无法灵活配置查询输出格式和字段 - -### 需要解决的问题 -- 将 SQL 查询模板化,支持配置化管理 -- 实现查询执行器,支持动态参数替换 -- 提供设备适配能力,支持多 GPU 场景 -- 支持自定义查询输出 schema - -### 预期的业务价值 -- 查询开发效率提升 80%,无需修改代码 -- 支持用户自定义查询,增强扩展性 -- 降低 SQL 注入风险,参数自动转义 -- 统一查询接口,便于集成和复用 - ---- - -## What Changes - -### 新增功能/模块 -- QueryConfig:配置数据模型 -- QueryTemplate:查询模板定义 -- QueryExecutor:查询执行器 -- YAML 配置管理 -- SQL 模板渲染引擎 - -### 修改的组件 -- `pt_snap_analyzer/cli.py` - 新增查询命令 -- `pt_snap_analyzer/__init__.py` - 导出查询模块 - -### 删除的功能 -- 无 - -### 技术架构变更 -- 引入 YAML 配置管理 -- 引入模板渲染机制 - ---- - -## Impact - -### 影响的规格文档 -- foundation/spec.md - 依赖 Context 类 - -### 影响的代码模块 -- `pt_snap_analyzer/query/__init__.py` - 新增:包初始化 -- `pt_snap_analyzer/query/config.py` - 新增:配置管理 -- `pt_snap_analyzer/query/executor.py` - 新增:查询执行器 -- `pt_snap_analyzer/query/templates/` - 新增:模板目录 -- `pt_snap_analyzer/query/templates/leak_detection_v2.yaml` - 新增:泄漏检测模板 -- `pt_snap_analyzer/query/templates/memory_timeline_v2.yaml` - 新增:时间线模板 -- `pt_snap_analyzer/query/templates/callstack_analysis_v2.yaml` - 新增:调用栈模板 - -### 影响的依赖 -- `PyYAML>=6.0` - 已在 foundation 中定义 -- `Jinja2>=3.0.0` - 新增:模板渲染 - -### 影响的配置 -- 无环境变量变更 -- 配置文件:YAML 查询模板 - ---- - -## ADDED Requirements - -### Requirement: QueryConfig 配置类 -系统 SHALL 定义查询配置类: - -- version: 配置版本 -- queries: 查询模板字典 -- load_yaml(path) -> QueryConfig: 从 YAML 加载 -- get_query(name) -> QueryTemplate: 获取查询模板 - -#### Scenario: 加载配置文件 -- **GIVEN** 存在有效的 YAML 配置文件 -- **WHEN** 调用 load_yaml(config_path) -- **THEN** 返回 QueryConfig 实例 - -### Requirement: QueryTemplate 模板类 -系统 SHALL 定义查询模板类: - -- name: 查询名称 -- description: 查询描述 -- devices: 适用设备列表 -- parameters: 参数定义 -- query: SQL 模板字符串 -- output_schema: 输出 schema 定义 - -#### Scenario: 参数验证 -- **GIVEN** 查询模板包含必需参数 -- **WHEN** 参数未提供 -- **THEN** 抛出参数缺失错误 - -### Requirement: QueryExecutor 执行器 -系统 SHALL 实现查询执行器: - -- render(template, params) -> str: 渲染 SQL 模板 -- execute(query, params) -> List[Dict]: 执行查询 -- execute_template(name, params) -> List[Dict]: 执行模板查询 -- validate_output(result, schema) -> bool: 验证输出 - -#### Scenario: 执行参数化查询 -- **GIVEN** 有效的查询模板和参数 -- **WHEN** 调用 execute_template(name, params) -- **THEN** 返回查询结果列表 - -#### Scenario: 设备适配 -- **GIVEN** 多设备数据库 -- **WHEN** 执行查询并指定设备 -- **THEN** 只查询指定设备的数据 - -### Requirement: SQL 模板渲染 -系统 SHALL 支持 SQL 模板语法: - -- 参数替换:{{ param_name }} -- 条件语法:{% if condition %}...{% endif %} -- 循环语法:{% for item in items %}...{% endfor %} -- 设备表名:{{ device_table }} - -#### Scenario: 参数替换 -- **GIVEN** SQL 模板包含 {{ min_size }} -- **WHEN** 提供参数 min_size=1024 -- **THEN** 渲染后的 SQL 包含 1024 - -### Requirement: 预定义查询模板 -系统 SHALL 提供预定义查询模板: - -- leak_detection_v2: 泄漏检测查询 -- memory_timeline_v2: 内存时间线查询 -- callstack_analysis_v2: 调用栈分析查询 - -#### Scenario: 使用预定义模板 -- **GIVEN** 预定义模板已注册 -- **WHEN** 执行 leak_detection_v2 -- **THEN** 返回泄漏检测结果 - ---- - -## MODIFIED Requirements -无 - -## REMOVED Requirements -无 - ---- - -## 1. Overview - -### 1.1 Purpose -提供灵活的查询能力,支持 YAML 配置的 SQL 模板、参数化查询、设备适配和结果验证。 - -### 1.2 Scope -- 查询配置系统设计 -- SQL 模板渲染引擎 -- 查询执行器实现 -- 预定义查询模板 -- CLI 查询命令 - ---- - -## 2. Technical Architecture - -### 2.1 File Structure -``` -pt_snap_analyzer/ -├── query/ -│ ├── __init__.py -│ ├── config.py # QueryConfig, QueryTemplate -│ ├── executor.py # QueryExecutor -│ └── templates/ -│ ├── leak_detection_v2.yaml -│ ├── memory_timeline_v2.yaml -│ └── callstack_analysis_v2.yaml -└── cli.py # 新增查询命令 -``` - -### 2.2 Configuration Model - -#### QueryParameter -**Query parameter definition** - -**Attributes:** -- `name: str` - Parameter name -- `default: Any` - Default value -- `type: str` - Type ('str', 'int', 'float', 'bool') -- `description: str` - Parameter description -- `required: bool` - Whether required - -#### QueryTemplate -**SQL query template** - -**Attributes:** -- `name: str` - Template name -- `description: str` - Template description -- `devices: List[str]` - Applicable devices -- `parameters: Dict[str, QueryParameter]` - Parameter definitions -- `query: str` - SQL template string -- `output_schema: List[Dict[str, str]]` - Output schema - -#### QueryConfig -**Query configuration** - -**Attributes:** -- `version: str` - Config version -- `queries: Dict[str, QueryTemplate]` - Query templates - -**Key Methods:** -- `load_yaml(path: str) -> QueryConfig` - Load from YAML -- `get_query(name: str) -> QueryTemplate` - Get template - -### 2.3 Query Executor - -#### QueryExecutor -**Executes queries with template rendering** - -**Key Methods:** -- `render(template: QueryTemplate, params: Dict) -> str` - Render SQL -- `execute(query: str, params: Dict) -> List[Dict]` - Execute SQL -- `execute_template(name: str, params: Dict) -> List[Dict]` - Execute template -- `validate_output(result: List, schema: List) -> bool` - Validate output - -### 2.4 Template Syntax - -**Parameter substitution:** -- `{{ param_name }}` - Simple substitution -- `{{ param_name|upper }}` - With filter -- `{% if condition %}...{% endif %}` - Conditional -- `{% for item in items %}...{% endfor %}` - Loop - -**Special variables:** -- `{{ device_table }}` - Current device table name -- `{{ device_id }}` - Current device ID - ---- - -## 3. Implementation Requirements - -### 3.1 Dependencies -- `Jinja2>=3.0.0` - 新增:模板渲染 -- `PyYAML>=6.0` - 已有:YAML 解析 - -### 3.2 Testing Strategy -- 单元测试:配置加载、模板渲染、查询执行 -- 集成测试:使用示例数据库测试查询 -- 模板测试:验证预定义模板正确性 -- 覆盖率目标:>80% - ---- - -## 4. Success Criteria -- [ ] 配置系统正确实现 -- [ ] 模板渲染正确 -- [ ] 查询执行正确 -- [ ] 参数替换正常 -- [ ] 设备适配正常 -- [ ] 预定义模板可用 -- [ ] 所有单元测试通过 -- [ ] 测试覆盖率 >80% -- [ ] 代码通过 ruff 检查 -- [ ] 代码通过 black 格式化 - ---- - -## 5. Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| SQL 注入风险 | 高 | 低 | 使用参数化查询,不直接拼接 SQL | -| 模板渲染错误 | 中 | 中 | 提供详细的错误信息和模板调试功能 | -| YAML 配置格式错误 | 中 | 中 | 严格的 schema 验证,友好的错误提示 | -| 设备适配复杂 | 中 | 中 | 抽象设备管理逻辑,提供默认实现 | -| 模板性能问题 | 低 | 低 | 模板预编译缓存,避免重复渲染 | -| Jinja2 依赖冲突 | 低 | 低 | 固定 Jinja2 版本,使用虚拟环境 | - ---- - -## 6. Appendix - -### 参考文档 -- [Jinja2 文档](https://jinja.palletsprojects.com/) -- [PyYAML 文档](https://pyyaml.org/wiki/PyYAMLDocumentation) -- [SQLite 查询优化](https://www.sqlite.org/optoverview.html) - -### 相关讨论 -- SQL 模板设计规范 -- 参数化查询最佳实践 -- 设备适配策略 - -### 设计决策记录 -1. **选择 Jinja2 而非 string.format**: Jinja2 更强大,支持条件/循环,安全性更好 -2. **YAML 而非 JSON 配置**: YAML 更易读,支持注释,便于维护 -3. **预编译模板缓存**: 提高性能,避免重复解析 -4. **设备适配层**: 简化多设备查询逻辑 - -### 示例 YAML 模板 -```yaml -name: leak_detection_v2 -description: Detect memory leaks -devices: ["all", "0", "1"] -parameters: - min_size: - type: int - default: 1024 - required: false - description: Minimum leak size -query: | - SELECT id, address, size, callstack - FROM {{ device_table }} - WHERE size >= {{ min_size }} - AND freeEventId IS NULL -output_schema: - - column: id - type: int - - column: address - type: hex - - column: size - type: int -``` - -### 示例查询执行 -```python -from pt_snap_analyzer.query import QueryExecutor - -executor = QueryExecutor(config_path="templates/") -results = executor.execute_template( - "leak_detection_v2", - {"min_size": 2048, "device_id": 0} -) -``` diff --git a/.agents/superpowers/specs/query/tasks.md b/.agents/superpowers/specs/query/tasks.md deleted file mode 100644 index a22bbbd..0000000 --- a/.agents/superpowers/specs/query/tasks.md +++ /dev/null @@ -1,51 +0,0 @@ -# Tasks: pt-snap-analyzer 查询系统 - ---- - -## Task List - -- [ ] Task 1: 查询条件实现 - - [ ] Step 1: 创建条件基类 - - [ ] Step 2: 实现条件类型 (Equal, NotEqual, GreaterThan, LessThan, In, Like) - - [ ] Step 3: 实现组合条件 (And, Or) - - [ ] Step 4: 创建测试文件 - - [ ] Step 5: 运行测试 - - [ ] Step 6: Commit - -- [ ] Task 2: 查询构建器实现 - - [ ] Step 1: 创建查询构建器 (QueryBuilder) - - [ ] Step 2: 实现 fluent API 方法 (from_table, where, order_by, limit, offset, columns) - - [ ] Step 3: 实现 build() 方法 - - [ ] Step 4: 实现 execute() 方法 - - [ ] Step 5: 创建测试文件 - - [ ] Step 6: 运行测试 - - [ ] Step 7: Commit - -- [ ] Task 3: 查询注册表和 CLI 集成 - - [ ] Step 1: 创建查询注册表 - - [ ] Step 2: 注册预定义查询 (active_blocks, events_by_type, memory_by_device, blocks_by_size) - - [ ] Step 3: 扩展 CLI 查询命令 - - [ ] Step 4: 创建测试文件 - - [ ] Step 5: 运行测试 - - [ ] Step 6: Commit - -- [ ] Task 4: 结果映射器 - - [ ] Step 1: 创建结果映射器 (ResultMapper) - - [ ] Step 2: 实现类型映射 (map, map_all) - - [ ] Step 3: 实现便捷函数 (map_to_events, map_to_blocks, map_to_analysis) - - [ ] Step 4: 创建测试文件 - - [ ] Step 5: 运行测试 - - [ ] Step 6: Commit - -- [ ] Task 5: 集成测试 - - [ ] Step 1: 运行所有测试 - - [ ] Step 2: 代码质量检查 - - [ ] Step 3: 手动测试 CLI - - [ ] Step 4: 最终 Commit - -## Task Dependencies - -- Task 2 depends on Task 1 -- Task 3 depends on Task 2 -- Task 4 depends on Task 3 -- Task 5 depends on Task 4 diff --git a/.agents/superpowers/specs/rag/checklist.md b/.agents/superpowers/specs/rag/checklist.md deleted file mode 100644 index fcb441d..0000000 --- a/.agents/superpowers/specs/rag/checklist.md +++ /dev/null @@ -1,72 +0,0 @@ -# Checklist: pt-snap-analyzer RAG 知识库 - -## Data Models -- [ ] AnalysisStep dataclass 正确定义 -- [ ] RAGCase dataclass 正确定义 -- [ ] RAGCase.__post_init__ 正确生成 case_id 和 timestamp -- [ ] SearchMatch dataclass 正确定义 -- [ ] SearchResult dataclass 正确定义 - -## Case Archive System -- [ ] ArchiveError 异常类定义 -- [ ] CaseArchive 类正确实现 -- [ ] add_case() 方法正确实现 -- [ ] add_case() 方法验证 required 字段 -- [ ] get_case() 方法正确实现 -- [ ] list_cases() 方法正确实现 -- [ ] list_cases() 支持 tag 过滤 (AND logic) -- [ ] delete_case() 方法正确实现 -- [ ] _case_to_dict() 方法正确序列化 -- [ ] _dict_to_case() 方法正确反序列化 - -## Searcher System -- [ ] Searcher 类正确实现 -- [ ] search() 方法正确实现 -- [ ] _score_case() 方法正确计算分数 -- [ ] _normalize_text() 方法正确规范化文本 -- [ ] get_tags() 方法正确返回所有标签 -- [ ] top_k 参数正确限制结果数量 -- [ ] tags 参数正确过滤结果 - -## CLI Commands -- [ ] rag 命令实现 -- [ ] rag-add 命令实现 -- [ ] rag-search 命令实现 -- [ ] rag-list 命令实现 -- [ ] rag-tags 命令实现 -- [ ] JSON 输出格式正确 -- [ ] 错误处理正确 - -## SDK Integration -- [ ] pt_snap_analyzer/__init__.py 导出正确 -- [ ] pt_snap_analyzer/rag/__init__.py 导出正确 -- [ ] CaseArchive 可通过 SDK 访问 -- [ ] Searcher 可通过 SDK 访问 -- [ ] RAGCase 可通过 SDK 访问 - -## Testing -- [ ] tests/test_rag_models.py 通过 (7 tests) -- [ ] tests/test_rag_archive.py 通过 (10 tests) -- [ ] tests/test_rag_searcher.py 通过 (7 tests) -- [ ] tests/test_rag_cli.py 通过 (7 tests) -- [ ] tests/test_sdk_rag.py 通过 (3 tests) -- [ ] 总测试通过 (34+ tests) -- [ ] 覆盖率 >80% - -## Code Quality -- [ ] ruff check 无错误 -- [ ] black 格式化完成 -- [ ] isort 导入排序正确 -- [ ] 类型注解完整 -- [ ] 文档字符串完整 - -## Documentation -- [ ] README.md 更新 RAG 部分 -- [ ] API 文档 -- [ ] 使用示例 -- [ ] 案例格式说明 - -## Version Control -- [ ] 所有 changes committed -- [ ] Commit message 清晰描述变更 -- [ ] Git log 历史清晰 diff --git a/.agents/superpowers/specs/rag/spec.md b/.agents/superpowers/specs/rag/spec.md deleted file mode 100644 index 5b36f2e..0000000 --- a/.agents/superpowers/specs/rag/spec.md +++ /dev/null @@ -1,471 +0,0 @@ -# Spec: pt-snap-analyzer RAG 知识库 - -**Goal:** 实现 RAG 知识库,支持案例归档、向量搜索和相似案例检索 - -**Architecture:** 使用 ChromaDB 存储向量,简单的关键词搜索作为备用,CLI 和 SDK 双接口 - -**Tech Stack:** Python 3.10+, ChromaDB, LangChain(可选) - ---- - -## Why - -### 当前痛点 -- 内存问题分析经验无法沉淀,每次遇到类似问题都要重新分析 -- 专家知识分散在各个开发者脑中,没有系统化的知识库 -- 相似案例无法快速检索,重复劳动严重 -- AI 辅助分析缺少上下文,无法提供精准建议 - -### 需要解决的问题 -- 建立案例归档系统,将分析过程和结论结构化存储 -- 实现智能检索,支持语义搜索和相似度匹配 -- 提供 CLI 和 SDK 双接口,便于集成到工作流 -- 支持标签分类,便于案例管理和过滤 - -### 预期的业务价值 -- 案例检索时间从小时级降低到分钟级 -- 减少 70% 以上的重复分析工作 -- 沉淀专家经验,提升团队整体效率 -- 为 AI 辅助分析提供知识基础 - ---- - -## What Changes - -### 新增功能/模块 -- RAG 数据模型:AnalysisStep, RAGCase, SearchMatch, SearchResult -- CaseArchive:案例归档系统 -- Searcher:案例检索系统 -- CLI 命令:rag-add, rag-search, rag-list, rag-tags -- SDK API:Python 接口 - -### 修改的组件 -- `pt_snap_analyzer/cli.py` - 新增 RAG 命令 -- `pt_snap_analyzer/__init__.py` - 导出 RAG 模块 - -### 删除的功能 -- 无 - -### 技术架构变更 -- 引入 ChromaDB 向量数据库 -- 引入案例归档和检索机制 - ---- - -## Impact - -### 影响的规格文档 -- foundation/spec.md - 依赖 Context 类 -- analyzers/spec.md - 依赖分析结果 - -### 影响的代码模块 -- `pt_snap_analyzer/rag/__init__.py` - 新增:包初始化 -- `pt_snap_analyzer/rag/models.py` - 新增:RAG 数据模型 -- `pt_snap_analyzer/rag/archive.py` - 新增:案例归档 -- `pt_snap_analyzer/rag/searcher.py` - 新增:案例检索 -- `pt_snap_analyzer/rag/vector_store.py` - 新增:向量存储(可选) - -### 影响的依赖 -- `chromadb>=0.4.0` - 已有:向量数据库 -- `langchain>=0.1.0` - 已有:AI 框架(可选使用) - -### 影响的配置 -- 归档目录:`~/.local/share/pt-snap-analyzer/rag_archive` -- 向量存储目录:`~/.local/share/pt-snap-analyzer/rag_vectors` - ---- - -## ADDED Requirements - -### Requirement: RAGCase 案例模型 -系统 SHALL 定义案例数据模型: - -- case_id: 唯一标识(自动生成) -- timestamp: 创建时间 -- db_snapshot: 快照数据库路径 -- analysis_steps: 分析步骤列表 -- conclusion: 结论 -- root_cause: 根本原因 -- solution: 解决方案 -- tags: 标签列表 -- confidence: 置信度(0-1) -- verified_by: 验证者 -- metadata: 额外元数据 - -#### Scenario: 创建案例 -- **GIVEN** 分析完成的案例数据 -- **WHEN** 创建 RAGCase 实例 -- **THEN** 自动生成 case_id 和 timestamp - -### Requirement: CaseArchive 归档系统 -系统 SHALL 实现案例归档系统: - -- add_case(case: RAGCase) -> str: 添加案例 -- get_case(case_id: str) -> RAGCase: 获取案例 -- list_cases(tags=None) -> List[RAGCase]: 列出案例 -- delete_case(case_id: str) -> bool: 删除案例 -- get_tags() -> List[str]: 获取所有标签 - -#### Scenario: 归档案例 -- **GIVEN** 有效的 RAGCase 实例 -- **WHEN** 调用 add_case(case) -- **THEN** 返回 case_id,案例持久化存储 - -#### Scenario: 标签过滤 -- **GIVEN** 案例库包含多个案例 -- **WHEN** 调用 list_cases(tags=["leak", "cuda"]) -- **THEN** 返回同时包含这两个标签的案例(AND 逻辑) - -### Requirement: Searcher 检索系统 -系统 SHALL 实现案例检索系统: - -- search(query: str, top_k=5, tags=None) -> SearchResult: 搜索案例 -- _score_case(case: RAGCase, query: str) -> Tuple[float, List[str]]: 评分 -- _normalize_text(text: str) -> str: 文本规范化 -- get_tags() -> List[str]: 获取标签 - -#### Scenario: 关键词搜索 -- **GIVEN** 案例库包含相关案例 -- **WHEN** 调用 search("memory leak cuda 0", top_k=5) -- **THEN** 返回相关案例,按相关性排序 - -#### Scenario: 向量搜索(可选) -- **GIVEN** 启用了 ChromaDB 向量搜索 -- **WHEN** 调用 search(query) -- **THEN** 返回语义相似的案例 - -### Requirement: 案例存储格式 -系统 SHALL 定义案例存储格式: - -- 存储格式:JSON -- 存储目录:`~/.local/share/pt-snap-analyzer/rag_archive` -- 文件命名:`{case_id}.json` -- 序列化:包含所有字段 - -#### Scenario: 案例持久化 -- **GIVEN** 案例已添加 -- **WHEN** 系统重启 -- **THEN** 案例仍然存在且可检索 - -### Requirement: CLI 命令 -系统 SHALL 提供 CLI 命令: - -- `rag-add `: 添加案例 -- `rag-search `: 搜索案例 -- `rag-list [--tags TAG1,TAG2]`: 列出案例 -- `rag-tags`: 列出所有标签 - -#### Scenario: 添加案例 -- **GIVEN** JSON 格式的案例文件 -- **WHEN** 执行 `pt-snap rag-add case.json` -- **THEN** 案例添加到知识库 - -#### Scenario: 搜索案例 -- **GIVEN** 案例库包含数据 -- **WHEN** 执行 `pt-snap rag-search "leak"` -- **THEN** 显示匹配的案例 - ---- - -## MODIFIED Requirements -无 - -## REMOVED Requirements -无 - ---- - -## 1. Overview - -### 1.1 Purpose -构建 RAG 知识库系统,支持 PyTorch 内存问题案例的归档、搜索和检索,提供 AI 辅助分析能力。 - -### 1.2 Scope -- RAG 数据模型定义 -- 案例归档系统 -- 案例检索系统(关键词 + 向量) -- CLI 命令集成 -- SDK API 设计 - ---- - -## 2. Technical Architecture - -### 2.1 File Structure -``` -pt_snap_analyzer/ -├── rag/ -│ ├── __init__.py # Package exports -│ ├── models.py # RAG data models -│ ├── archive.py # Case archive system -│ ├── searcher.py # Case search system -│ └── vector_store.py # Vector store (optional) -└── cli.py # Add RAG commands -``` - -### 2.2 Data Models - -#### AnalysisStep -**A step in the analysis process** - -**Attributes:** -- `step: int` - Step number -- `command: str` - Command executed -- `parameters: Dict` - Command parameters -- `result_summary: str` - Summary of results -- `description: str` - Step description - -#### RAGCase -**A case in the RAG knowledge base** - -**Attributes:** -- `case_id: str` - Unique case identifier (auto-generated UUID) -- `timestamp: str` - ISO 8601 timestamp -- `db_snapshot: str` - Path to the snapshot database -- `analysis_steps: List[AnalysisStep]` - Analysis steps -- `conclusion: str` - Final conclusion -- `root_cause: str` - Root cause analysis -- `solution: str` - Solution or workaround -- `tags: List[str]` - Tags for filtering -- `confidence: float` - Confidence level (0-1) -- `verified_by: str` - Who verified the case -- `metadata: Dict` - Additional metadata - -**Key Methods:** -- `__post_init__()` - Generate case_id and timestamp -- `to_dict()` -> Dict - Serialize to dictionary -- `from_dict(data)` -> RAGCase - Deserialize from dictionary - -#### SearchMatch -**A matched case from search** - -**Attributes:** -- `case: RAGCase` - The matched case -- `score: float` - Relevance score (0-1) -- `query_match: List[str]` - Which query terms matched - -#### SearchResult -**Result of RAG search** - -**Attributes:** -- `matches: List[SearchMatch]` - Matched cases -- `total_results: int` - Total number of matches -- `query: str` - Original search query - -### 2.3 Case Archive System - -#### CaseArchive Class -**Manages case storage and retrieval** - -**Responsibilities:** -- Store and retrieve RAG cases -- Filter cases by tags -- Validate case data -- Serialize/deserialize cases - -**Key Methods:** -- `add_case(case: RAGCase) -> str` - Add a case -- `get_case(case_id: str) -> Optional[RAGCase]` - Get case by ID -- `list_cases(tags=None) -> List[RAGCase]` - List cases with filter -- `delete_case(case_id: str) -> bool` - Delete a case -- `_case_to_dict(case) -> Dict` - Serialize case -- `_dict_to_case(data) -> RAGCase` - Deserialize case -- `_get_archive_dir() -> Path` - Get archive directory - -### 2.4 Searcher System - -#### Searcher Class -**Searches for similar cases** - -**Responsibilities:** -- Search for similar cases -- Score cases against query -- Filter by tags -- Return ranked results - -**Key Methods:** -- `search(query: str, top_k=5, tags=None) -> SearchResult` - Search -- `_score_case(case: RAGCase, query: str) -> Tuple[float, List[str]]` - Score -- `_normalize_text(text: str) -> str` - Normalize text -- `get_tags() -> List[str]` - Get all tags - -**Search Strategy:** - -1. **Keyword-based search:** - - Normalize text (lowercase, remove accents) - - Tokenize query - - Count term matches in case fields - - Score based on match frequency - -2. **Vector search (optional):** - - Use ChromaDB for semantic similarity - - Embed query and cases - - Return top-k nearest neighbors - -### 2.5 CLI Commands - -#### rag-add -Add a case to the RAG knowledge base - -```bash -pt-snap rag-add [--verify] -``` - -#### rag-search -Search the RAG knowledge base - -```bash -pt-snap rag-search [--top-k N] [--tags TAG1,TAG2] [--json] -``` - -#### rag-list -List all cases - -```bash -pt-snap rag-list [--tags TAG1,TAG2] [--json] -``` - -#### rag-tags -List all available tags - -```bash -pt-snap rag-tags -``` - ---- - -## 3. Implementation Requirements - -### 3.1 Storage -- Cases stored as JSON files -- Archive directory: `~/.local/share/pt-snap-analyzer/rag_archive` -- JSON serialization for portability -- Atomic writes to prevent corruption - -### 3.2 Search Strategy - -**Keyword-based search (default):** -- Normalize text (lowercase, remove accents) -- Tokenize query -- Count term matches in case fields -- Score based on match frequency -- Fields searched: conclusion, root_cause, solution, tags - -**Vector search (future enhancement):** -- ChromaDB vector search -- LangChain integration -- Semantic similarity - -### 3.3 Testing Strategy -- 单元测试:模型、归档、检索器 -- 集成测试:完整工作流 -- CLI 测试:命令执行 -- SDK 测试:API 可用性 -- 覆盖率目标:>80% - ---- - -## 4. Success Criteria -- [ ] RAG 案例可以正确归档 -- [ ] 案例检索正确工作 -- [ ] 标签过滤正确实现 -- [ ] CLI 命令正常运行 -- [ ] SDK API 可用 -- [ ] 所有单元测试通过 -- [ ] 测试覆盖率 >80% -- [ ] 代码通过 ruff 检查 -- [ ] 代码通过 black 格式化 - ---- - -## 5. Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| 案例数据格式不一致 | 高 | 中 | 严格的数据验证,schema 检查 | -| 搜索准确性低 | 高 | 中 | 关键词 + 向量混合搜索,提供置信度 | -| 向量搜索性能差 | 中 | 中 | 默认使用关键词搜索,向量搜索可选 | -| 标签管理混乱 | 中 | 中 | 提供标签列表,支持标签建议 | -| 存储空间增长快 | 低 | 低 | 案例压缩存储,定期清理 | -| ChromaDB 依赖冲突 | 低 | 低 | 固定版本,使用虚拟环境 | - ---- - -## 6. Appendix - -### 参考文档 -- [ChromaDB 文档](https://docs.trychroma.com/) -- [LangChain 文档](https://python.langchain.com/) -- [JSON Schema](https://json-schema.org/) - -### 相关讨论 -- 案例格式设计 -- 搜索算法选择 -- 标签体系设计 - -### 设计决策记录 -1. **JSON 存储而非数据库**: 便于备份和迁移,无需额外依赖 -2. **关键词搜索优先**: 简单快速,向量搜索作为可选增强 -3. **CLI 和 SDK 双接口**: 既支持命令行使用,也支持程序化调用 -4. **自动生成 case_id**: 使用 UUID,避免冲突 - -### 示例案例 JSON -```json -{ - "case_id": "550e8400-e29b-41d4-a716-446655440000", - "timestamp": "2026-04-04T10:00:00Z", - "db_snapshot": "/path/to/snapshot.db", - "analysis_steps": [ - { - "step": 1, - "command": "leak-detect", - "parameters": {"min_size": 1024}, - "result_summary": "Found 5 leaks", - "description": "Run leak detection" - } - ], - "conclusion": "Memory leak in training loop", - "root_cause": "Tensor not released after use", - "solution": "Use .detach() or del tensor", - "tags": ["leak", "cuda", "training"], - "confidence": 0.95, - "verified_by": "expert1" -} -``` - -### 示例搜索 -```bash -# 搜索泄漏相关案例 -pt-snap rag-search "memory leak cuda" - -# 搜索并限制结果数量 -pt-snap rag-search "oom" --top-k 3 - -# 搜索并过滤标签 -pt-snap rag-search "leak" --tags training,cuda - -# JSON 输出 -pt-snap rag-search "leak" --json -``` - -### 示例 SDK 使用 -```python -from pt_snap_analyzer.rag import CaseArchive, Searcher - -# 添加案例 -archive = CaseArchive() -case = RAGCase( - db_snapshot="/path/to/snapshot.db", - conclusion="Memory leak", - root_cause="...", - solution="...", - tags=["leak", "cuda"] -) -case_id = archive.add_case(case) - -# 搜索案例 -searcher = Searcher() -result = searcher.search("memory leak", top_k=5) -for match in result.matches: - print(f"Score: {match.score}, Case: {match.case.conclusion}") -``` diff --git a/.agents/superpowers/specs/rag/tasks.md b/.agents/superpowers/specs/rag/tasks.md deleted file mode 100644 index 575c60a..0000000 --- a/.agents/superpowers/specs/rag/tasks.md +++ /dev/null @@ -1,53 +0,0 @@ -# Tasks: pt-snap-analyzer RAG 知识库 - ---- - -## Task List - -- [ ] Task 1: RAG 数据模型 - - [ ] Step 1: 创建数据模型 (AnalysisStep, RAGCase, SearchMatch, SearchResult) - - [ ] Step 2: 创建测试文件 - - [ ] Step 3: 运行测试 - - [ ] Step 4: Commit - -- [ ] Task 2: 案例归档系统 - - [ ] Step 1: 创建归档器 (CaseArchive) - - [ ] Step 2: 实现 CRUD 方法 (add_case, get_case, list_cases, delete_case) - - [ ] Step 3: 实现序列化方法 (_case_to_dict, _dict_to_case) - - [ ] Step 4: 创建测试文件 - - [ ] Step 5: 运行测试 - - [ ] Step 6: Commit - -- [ ] Task 3: 案例检索系统 - - [ ] Step 1: 创建检索器 (Searcher) - - [ ] Step 2: 实现 search() 方法 - - [ ] Step 3: 实现评分方法 (_score_case, _normalize_text) - - [ ] Step 4: 实现 get_tags() 方法 - - [ ] Step 5: 创建测试文件 - - [ ] Step 6: 运行测试 - - [ ] Step 7: Commit - -- [ ] Task 4: CLI 集成 - - [ ] Step 1: 添加 rag 命令到 CLI - - [ ] Step 2: 实现 rag-add 命令 - - [ ] Step 3: 实现 rag-search 命令 - - [ ] Step 4: 实现 rag-list 命令 - - [ ] Step 5: 实现 rag-tags 命令 - - [ ] Step 6: 创建 CLI 测试文件 - - [ ] Step 7: 运行测试 - - [ ] Step 8: Commit - -- [ ] Task 5: 完整的 SDK 集成 - - [ ] Step 1: 更新包初始化 - - [ ] Step 2: 创建 rag 包初始化 - - [ ] Step 3: 创建 SDK 测试 - - [ ] Step 4: 运行测试 - - [ ] Step 5: 运行完整测试 - - [ ] Step 6: Commit - -## Task Dependencies - -- Task 2 depends on Task 1 -- Task 3 depends on Task 2 -- Task 4 depends on Task 3 -- Task 5 depends on Task 4 diff --git a/.agents/superpowers/specs/tests/checklist.md b/.agents/superpowers/specs/tests/checklist.md deleted file mode 100644 index 34fffe7..0000000 --- a/.agents/superpowers/specs/tests/checklist.md +++ /dev/null @@ -1,91 +0,0 @@ -# 测试覆盖率提升检查清单 - -## 功能检查 - -- [x] condition.py: 所有基础条件类(Equal, NotEqual, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual)测试通过 -- [x] condition.py: In 和 Like 条件类测试通过 -- [x] condition.py: And 和 Or 组合条件测试通过 -- [x] condition.py: 混合组合和嵌套测试通过 -- [x] registry.py: 单例模式测试通过 -- [x] registry.py: 注册和查询功能测试通过 -- [x] registry.py: 工厂函数测试通过 -- [x] registry.py: 列表查询和注销功能测试通过 -- [x] registry.py: 模块级函数测试通过 -- [x] registry.py: YAML 模板加载测试通过 -- [x] cli.py: version 和主回调测试通过 -- [x] cli.py: use 命令所有场景测试通过 -- [x] cli.py: query 命令所有选项和场景测试通过 -- [x] cli.py: config 命令所有功能测试通过 -- [x] 所有需求规格中的功能都已实现 -- [x] 功能符合需求规格中的预期行为 - -## 接口检查【可选】 - -- [x] 测试用例接口定义清晰 -- [x] 测试参数命名规范 -- [x] 测试返回值验证完整 -- [x] 异常场景测试完整 -- [x] 测试文档清晰 - -## 错误处理检查 - -- [x] 边界条件测试正确(空列表、None、极端值) -- [x] 异常情况测试完整(FileNotFoundError, JSONDecodeError, 通用异常) -- [x] 错误信息验证 -- [x] CLI 命令退出码测试正确 -- [x] 资源清理测试(临时文件、mock 恢复) - -## 性能检查【可选】 - -- [x] 测试用例执行效率高 -- [x] 无冗余测试 -- [x] 测试隔离良好 - -## 安全检查 - -- [x] 测试代码无硬编码的敏感信息 -- [x] 临时文件使用安全路径 -- [x] 测试数据无敏感信息 - -## 代码质量检查 - -- [x] 测试代码遵循 pytest 规范 -- [x] 测试函数命名清晰(test_* 格式) -- [x] 测试类职责单一 -- [x] 无重复测试代码 -- [x] 使用 fixture 复用测试逻辑 - -## 测试检查 - -- [x] 单元测试覆盖核心逻辑 -- [x] 集成测试覆盖主要场景 -- [x] 边界条件已测试 -- [x] 异常情况已测试 -- [x] 测试用例已评审 -- [x] condition.py 覆盖率 >= 90% -- [x] registry.py 覆盖率 >= 90% -- [x] cli.py 覆盖率 >= 90% - -## 文档检查 - -- [x] 测试代码注释完整清晰 -- [x] 测试用例说明文档已更新 -- [x] 测试覆盖率报告已生成 - -## 部署检查【可选】 - -- [x] 测试依赖已添加到 requirements -- [x] 测试执行命令文档化 - -## 兼容性检查 - -- [x] 测试在 Python 版本下兼容 -- [x] 测试在不同操作系统下兼容(如适用) - -## 验收标准【可选】 - -- [x] 所有功能需求已实现 -- [x] 所有非功能需求已满足 -- [x] 所有已知 Bug 已修复 -- [x] 测试代码已通过 Code Review -- [x] 测试覆盖率满足要求 diff --git a/.agents/superpowers/specs/tests/tasks.md b/.agents/superpowers/specs/tests/tasks.md deleted file mode 100644 index 6a59e6c..0000000 --- a/.agents/superpowers/specs/tests/tasks.md +++ /dev/null @@ -1,43 +0,0 @@ -# Tasks - -- [ ] Task 1: test_condition.py - 基础条件类测试 - - [ ] SubTask 1.1: Equal, NotEqual, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual 测试 - - [ ] SubTask 1.2: In 条件测试(空列表、单值、多值) - - [ ] SubTask 1.3: Like 条件测试 - -- [ ] Task 2: test_condition.py - 组合条件测试 - - [ ] SubTask 2.1: And 组合测试(基础、多条件、空、链式) - - [ ] SubTask 2.2: Or 组合测试(基础、多条件、空、链式) - - [ ] SubTask 2.3: 混合组合测试(And+Or、嵌套、复杂组合) - -- [ ] Task 3: test_registry.py - 注册表基础功能测试 - - [ ] SubTask 3.1: 单例模式测试(创建、重置) - - [ ] SubTask 3.2: 注册和查询测试(基础、重复、不存在) - - [ ] SubTask 3.3: 工厂函数测试(注册、缓存、覆盖) - - [ ] SubTask 3.4: 列表查询测试(基础、详细信息、注销) - -- [ ] Task 4: test_registry.py - 模块级函数和 YAML 加载测试 - - [ ] SubTask 4.1: 模块级便捷函数测试(register_query, get_query, list_queries) - - [ ] SubTask 4.2: get_template_info 测试 - - [ ] SubTask 4.3: YAML 模板加载测试(目录不存在、正常加载、全部加载) - -- [ ] Task 5: test_cli.py - 基础命令和 use 命令测试 - - [ ] SubTask 5.1: version 回调和主回调测试 - - [ ] SubTask 5.2: use 命令测试(无参数、无配置、数据库不存在) - - [ ] SubTask 5.3: use 命令测试(成功场景、无设备、异常处理) - -- [ ] Task 6: test_cli.py - query 命令测试 - - [ ] SubTask 6.1: list 和 template-info 选项测试 - - [ ] SubTask 6.2: query 命令错误处理(无 template-use、无数据库、数据库不存在) - - [ ] SubTask 6.3: query 命令执行(带设备、不带设备、带参数、无效 JSON) - - [ ] SubTask 6.4: query 命令异常处理(无设备、文件不存在、通用异常) - -- [ ] Task 7: test_cli.py - config 命令测试 - - [ ] SubTask 7.1: config 显示测试(有配置、无配置) - - [ ] SubTask 7.2: config 清空和路径显示测试 - -# Task Dependencies -- [Task 2] depends on [Task 1] -- [Task 4] depends on [Task 3] -- [Task 6] depends on [Task 5] -- [Task 7] depends on [Task 5] diff --git a/.agents/superpowers/specs/tests/test-coverage-improvement.md b/.agents/superpowers/specs/tests/test-coverage-improvement.md deleted file mode 100644 index 8c0ac48..0000000 --- a/.agents/superpowers/specs/tests/test-coverage-improvement.md +++ /dev/null @@ -1,171 +0,0 @@ -# 测试覆盖率提升规格说明书 - -## Why - -当前 `pt_snap_analyzer` 项目中三个核心文件的测试覆盖率较低: -- `condition.py`: 查询条件类的 SQL 生成和组合逻辑 -- `registry.py`: 查询注册表的单例模式、注册、查询、模板加载功能 -- `cli.py`: 命令行接口的所有命令和选项 - -需要补充完整的测试用例以确保: -- 核心功能的质量可靠性 -- 防止回归 bug -- 提高代码可维护性 -- 满足项目的覆盖率要求 - -## What Changes - -### 新增测试文件 -- `tests/test_condition.py`: 完整的查询条件类测试 -- `tests/test_registry.py`: 完整的查询注册表测试 -- `tests/test_cli.py`: 完整的 CLI 命令测试 - -### 修改的组件 -- 无修改现有代码,仅新增测试文件 - -### 技术架构变更 -- 使用 pytest 作为测试框架 -- 使用 pytest-mock 进行 mock 测试 -- 使用 typer.testing.TestRunner 进行 CLI 测试 - -## Impact - -### 影响的规格文档 -- 无 - -### 影响的代码模块 -- 新增:`tests/test_condition.py` -- 新增:`tests/test_registry.py` -- 新增:`tests/test_cli.py` - -### 影响的依赖 -- pytest (已存在) -- pytest-mock (需确认是否已安装) -- typer.testing (已包含在 typer 中) - -### 影响的配置 -- 无配置文件变更 - -## ADDED Requirements - - -### Requirement: condition.py 测试覆盖 -系统 SHALL 覆盖所有查询条件类的测试: - -- 基础条件类:Equal, NotEqual, GreaterThan, LessThan, GreaterThanOrEqual, LessThanOrEqual -- 特殊条件类:In, Like -- 组合条件类:And, Or -- 混合组合:And 和 Or 的嵌套和组合 - -#### Scenario: 基础条件类测试 -- **GIVEN** 条件类实例已创建 -- **WHEN** 调用 to_sql() 方法 -- **THEN** 返回正确的 SQL 字符串和参数列表 - -#### Scenario: 组合条件测试 -- **GIVEN** 多个条件实例 -- **WHEN** 使用 & 或 | 操作符组合 -- **THEN** 生成正确的复合 SQL 表达式 - -#### Scenario: 边界条件测试 -- **GIVEN** 空列表或特殊值 -- **WHEN** 创建条件或组合条件 -- **THEN** 正确处理边界情况 - -### Requirement: registry.py 测试覆盖 -系统 SHALL 覆盖查询注册表的所有功能测试: - -- 单例模式:创建、重置 -- 注册功能:模板注册、工厂函数注册 -- 查询功能:按名称查询、列表查询 -- 模板加载:YAML 文件加载 -- 模块级函数:便捷函数测试 - -#### Scenario: 单例模式测试 -- **GIVEN** 多次调用 QueryRegistry() -- **WHEN** 检查实例 -- **THEN** 返回同一实例(重置前) - -#### Scenario: 注册和查询测试 -- **GIVEN** 模板或工厂函数已注册 -- **WHEN** 调用 get() 方法 -- **THEN** 返回正确的模板 - -#### Scenario: YAML 加载测试 -- **GIVEN** YAML 模板文件存在 -- **WHEN** 调用 _load_yaml_templates() -- **THEN** 模板成功加载到注册表 - -### Requirement: cli.py 测试覆盖 -系统 SHALL 覆盖所有 CLI 命令和选项的测试: - -- version 回调函数 -- use 命令:数据库配置 -- query 命令:查询执行 -- config 命令:配置管理 - -#### Scenario: use 命令测试 -- **GIVEN** 数据库路径(存在/不存在) -- **WHEN** 执行 use 命令 -- **THEN** 正确配置数据库并显示设备信息 - -#### Scenario: query 命令测试 -- **GIVEN** 查询模板和参数 -- **WHEN** 执行 query 命令 -- **THEN** 返回正确的查询结果 - -#### Scenario: config 命令测试 -- **GIVEN** 配置存在/不存在 -- **WHEN** 执行 config 命令(显示/清空/路径) -- **THEN** 正确显示或修改配置 - -## MODIFIED Requirements - -无 - -## REMOVED Requirements - -无 - -## Technical Design - - -### 测试策略 -- 单元测试:测试独立的函数和类 -- 集成测试:测试组件间交互 -- Mock 测试:隔离外部依赖 - -### 测试工具 -- pytest: 测试框架 -- pytest-mock: mock 功能 -- typer.testing.TestRunner: CLI 测试 - -### 测试组织 -``` -tests/ -├── test_condition.py # 查询条件测试 -├── test_registry.py # 注册表测试 -└── test_cli.py # CLI 测试 -``` - -## Risks and Mitigations - -| 风险 | 影响 | 概率 | 缓解措施 | -|------|------|------|----------| -| pytest-mock 未安装 | 中 | 低 | 提前检查并安装依赖 | -| CLI 测试依赖数据库 | 中 | 中 | 使用临时文件和 mock | -| 测试执行时间长 | 低 | 低 | 优化测试结构,并行执行 | - -## Success Criteria - -- [ ] condition.py 测试覆盖率 >= 90% -- [ ] registry.py 测试覆盖率 >= 90% -- [ ] cli.py 测试覆盖率 >= 90% -- [ ] 所有测试用例通过 -- [ ] 无 flaky 测试 -- [ ] 测试代码符合项目规范 - -## Appendix - -- 测试文件将输出到 `/Users/test1/liuyekang/dev/code/pt-snap-cli/docs/superpowers/specs/tests/` -- 参考模板:`docs/superpowers/specs/.templates/` diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 3831d84..0000000 --- a/.gitignore +++ /dev/null @@ -1,91 +0,0 @@ -# ============================ -# Python -# ============================ -__pycache__/ -*.py[cod] -*$py.class -*.so -*.pyd - -# 虚拟环境 -.venv/ -venv/ -env/ -ENV/ -.env - -# 构建产物 -build/ -dist/ -*.egg-info/ -*.egg -MANIFEST -wheels/ -*.whl - -# 安装元数据 -pip-log.txt -pip-delete-this-directory.txt - -# ============================ -# 测试 & 覆盖率 -# ============================ -.coverage -.coverage.* -coverage.xml -htmlcov/ -.pytest_cache/ -.tox/ -nosetests.xml -test_reports/ -*.xml - -# ============================ -# 类型检查 & Linting -# ============================ -.mypy_cache/ -.ruff_cache/ -.dmypy.json -dmypy.json - -# ============================ -# Jupyter Notebook -# ============================ -.ipynb_checkpoints -*.ipynb - -# ============================ -# 项目特定 — 数据 & 快照 -# ============================ -examples/ -*.db -*.pkl -*.pt -*.pth -snapshot_*.json - -# ============================ -# IDE / 编辑器 -# ============================ -.idea/ -.vscode/ -*.swp -*.swo -*~ -.DS_Store -Thumbs.db - -# ============================ -# 文档构建 -# ============================ -docs/_build/ -docs/site/ -site/ - -# ============================ -# 其他 -# ============================ -*.log -*.tmp -*.bak -.cache/ From 1229fcfa91948d00946685629ff198fc8125a7d3 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 18 Apr 2026 23:15:28 +0800 Subject: [PATCH 2/2] fix: remove hardcoded 10-row limit from query output, add -n flag Query results were always truncated to first 10 rows with no way to retrieve the full list. Change default to unlimited output and add a -n flag to optionally limit displayed rows. Fixes #49 --- src/pt_snap_cli/cli.py | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/pt_snap_cli/cli.py b/src/pt_snap_cli/cli.py index 3cf3457..040f643 100644 --- a/src/pt_snap_cli/cli.py +++ b/src/pt_snap_cli/cli.py @@ -210,6 +210,13 @@ def query_database( autocompletion=complete_template_names, ), ] = None, + max_rows: Annotated[ + int | None, + typer.Option( + "-n", + help="Maximum number of result rows to display (<= 0 for unlimited, default: unlimited)", + ), + ] = None, ) -> None: """Execute queries on the memory snapshot database. @@ -400,11 +407,13 @@ def query_database( results = executor.execute_template(template_use, query_params, device_id=target_device) if results: - typer.echo(f"Found {len(results)} results:") - for row in results[:10]: + effective_limit = max_rows if max_rows is not None and max_rows > 0 else len(results) + display = results[:effective_limit] + typer.echo(f"Found {len(results)} results, showing {len(display)}:") + for row in display: typer.echo(f" {row}") - if len(results) > 10: - typer.echo(f" ... and {len(results) - 10} more") + if effective_limit < len(results): + typer.echo(f" ... and {len(results) - effective_limit} more (use -n to show more)") else: typer.echo("No results found.")