session-archaeology

会话考古

Agent Skills™ 的一部分，由 googleadsagent.ai™ 提供

描述

会话考古是对过往 Agent 会话进行系统性挖掘和分析，以提取可复用模式、识别反复出现的失败模式，并根据实际运行历史推导新技能的过程。每次 Agent 会话都会产生丰富的记录——完整记录推理过程、工具使用、错误、修正和最终结果。大多数团队都会丢弃这些数据。会话考古将其视为最有价值的训练信号：来自特定领域、特定代码库和特定工作流的真实执行轨迹。

这项技能将 googleadsagent.ai™ 用来持续改进 Buddy™ 的方法正式化：通过挖掘数千次过往的 Google Ads 分析会话来提升表现。考古流程会识别哪些提示词模式带来了准确的建议，哪些工具调用序列能可靠地完成任务，以及哪些错误恢复策略取得了成功。随后，这些发现会被编入新的 Agent Skills™，或用于完善现有技能，从而形成持续改进的飞轮。

该流程分为三个层面：单次会话审查（本次运行中出了什么问题）、跨会话模式分析（许多次运行中反复出现哪些模式），以及趋势识别（Agent 的行为如何随时间变化）。每个层面都会带来不同的洞见和改进类型。

适用场景

• Agent 质量已陷入停滞，需要新的优化信号
• 希望从真实执行数据中推导新技能或规则
• 反复出现的失败表明存在系统性问题，而非随机错误
• 为新团队成员提供培训，帮助他们了解 Agent 的行为模式
• 基于真实会话记录构建回归测试套件
• 准备进行模型版本迁移（比较不同模型版本的行为）

工作原理

graph TD
    A[Session Transcripts] --> B[Session Parser]
    B --> C[Event Extraction]
    C --> D[Pattern Classifier]
    D --> E{Pattern Type}
    E -->|Success Pattern| F[Skill Candidate]
    E -->|Failure Pattern| G[Mistake Taxonomy Entry]
    E -->|Neutral| H[Archive]
    F --> I[Pattern Validation]
    G --> I
    I --> J[Cross-Session Correlation]
    J --> K{Frequency > Threshold?}
    K -->|Yes| L[Skill Codification]
    K -->|No| M[Watch List]
    L --> N[Agent Skills™ Repository]
    M --> J

考古工作流首先会将原始会话记录解析为结构化事件流——每次工具调用、每次模型响应、每个错误和每次人工干预都会成为一个独立事件。模式分类器会为每个事件序列分配类型：成功模式（能够可靠完成任务的工具链）、失败模式（具有可识别根本原因的反复错误）和中性模式（既无明显好处也无明显坏处）。成功模式和失败模式会进入验证阶段，在此阶段进行跨会话交叉关联。频率超过阈值的模式会被编入正式技能或规则。

实现

会话记录解析器：

from dataclasses import dataclass, field
from typing import Literal

@dataclass
class SessionEvent:
    timestamp: str
    event_type: Literal["tool_call", "model_response", "error", "human_input", "correction"]
    content: dict
    duration_ms: int = 0
    token_count: int = 0
    success: bool = True

@dataclass
class ParsedSession:
    session_id: str
    events: list[SessionEvent] = field(default_factory=list)
    total_tokens: int = 0
    total_duration_ms: int = 0
    outcome: Literal["success", "partial", "failure"] = "success"

def parse_session_transcript(transcript_path: str) -> ParsedSession:
    with open(transcript_path) as f:
        lines = [json.loads(line) for line in f if line.strip()]

    session = ParsedSession(session_id=transcript_path)
    for entry in lines:
        event = SessionEvent(
            timestamp=entry.get("timestamp", ""),
            event_type=classify_event_type(entry),
            content=entry,
            duration_ms=entry.get("duration_ms", 0),
            token_count=entry.get("usage", {}).get("total_tokens", 0),
            success=not entry.get("error"),
        )
        session.events.append(event)
        session.total_tokens += event.token_count
        session.total_duration_ms += event.duration_ms

    session.outcome = determine_outcome(session.events)
    return session

模式提取引擎：

class PatternExtractor:
    def __init__(self, min_frequency=3, min_confidence=0.7):
        self.min_frequency = min_frequency
        self.min_confidence = min_confidence
        self.pattern_store = {}

    def extract_tool_sequences(self, sessions: list[ParsedSession]) -> list[dict]:
        sequences = []
        for session in sessions:
            tool_events = [e for e in session.events if e.event_type == "tool_call"]
            for window_size in range(2, min(6, len(tool_events) + 1)):
                for i in range(len(tool_events) - window_size + 1):
                    seq = tuple(e.content.get("tool_name") for e in tool_events[i:i + window_size])
                    success = all(e.success for e in tool_events[i:i + window_size])
                    sequences.append({"sequence": seq, "success": success, "session": session.session_id})
        return self.aggregate_sequences(sequences)

    def aggregate_sequences(self, sequences):
        counts = {}
        for seq in sequences:
            key = seq["sequence"]
            if key not in counts:
                counts[key] = {"total": 0, "success": 0, "sessions": set()}
            counts[key]["total"] += 1
            counts[key]["success"] += int(seq["success"])
            counts[key]["sessions"].add(seq["session"])

        patterns = []
        for seq, stats in counts.items():
            if stats["total"] >= self.min_frequency:
                confidence = stats["success"] / stats["total"]
                if confidence >= self.min_confidence:
                    patterns.append({
                        "sequence": seq,
                        "frequency": stats["total"],
                        "confidence": confidence,
                        "sessions": len(stats["sessions"]),
                    })
        return sorted(patterns, key=lambda p: p["confidence"] * p["frequency"], reverse=True)

错误分类体系构建器：

class MistakeTaxonomy:
    CATEGORIES = {
        "hallucination": {"description": "Model generated factually incorrect content"},
        "tool_misuse": {"description": "Wrong tool selected or incorrect parameters"},
        "context_loss": {"description": "Agent lost track of prior context or instructions"},
        "scope_creep": {"description": "Agent exceeded the boundaries of the task"},
        "format_violation": {"description": "Output did not match required format"},
    }

    def __init__(self):
        self.entries = []

    def classify_mistake(self, event: SessionEvent, context: list[SessionEvent]) -> dict:
        error_text = str(event.content.get("error", ""))
        prev_events = context[-5:]
        category = self.match_category(error_text, prev_events)
        return {
            "category": category,
            "event": event,
            "context_window": prev_events,
            "suggested_fix": self.suggest_fix(category, error_text),
        }

    def suggest_fix(self, category: str, error_text: str) -> str:
        fixes = {
            "hallucination": "Add verification loop with ground-truth checking",
            "tool_misuse": "Add pre-flight tool parameter validation",
            "context_loss": "Implement context checkpointing between stages",
            "scope_creep": "Add task boundary assertions in system prompt",
            "format_violation": "Add schema grader to verification pipeline",
        }
        return fixes.get(category, "Review and add specific guard for this error type")

最佳实践

1. 自动解析会话 — 设置钩子，在每次会话完成后立即解析并索引会话记录；数据一旦过时，价值就会降低。
2. 优先关注失败模式 — 成功模式固然有用，但每个工程工时投入到失败模式中，都能带来影响最大的改进。
3. 构建不断完善的错误分类体系 — 维护一个分类清晰、可搜索的数据库，记录每种失败类型、建议的修复方法和发生次数。
4. 设定最低出现频次 — 只观察到一次的模式可能只是噪声；在将技能正式编入体系前，要求它至少在不同会话中出现 3 次。
5. 跟踪模式随时间的演变 — 失败模式出现频率上升表示发生了回归；频率下降则说明近期修复有效。
6. 从成功的工具序列中推导技能 — 如果同一组 3 个工具的调用序列出现在 80% 的成功会话中，就将其编入体系，作为推荐工作流。
7. 分享前先匿名化 — 会话记录包含用户数据、API 密钥和业务逻辑；在跨团队分析前，请移除敏感内容。

平台兼容性

特性	Claude Code	Cursor	Codex	Gemini CLI
会话记录访问	✅ JSONL 日志	✅ Agent 记录	✅ 执行日志	✅ 会话日志
自动解析	✅ Hooks	✅ 扩展	✅ 脚本	✅ 脚本
跨会话分析	✅ 完整支持	✅ 完整支持	✅ 完整支持	✅ 完整支持
模式提取	✅ 完整支持	✅ 完整支持	✅ 完整支持	✅ 完整支持
技能派生	✅ SKILL.md	✅ SKILL.md	✅ 指令	✅ 系统提示词

相关技能

• 验证循环 - 评分器输出会作为结构化评估数据输入会话考古，用于模式挖掘
• 认知脚手架 - 通过考古分析验证注意力模式，找出效果最佳的脚手架区域
• 上下文工程 - 从会话记录中挖掘令牌使用模式，以优化上下文预算分配

关键词

session-archaeology、pattern-mining、mistake-taxonomy、session-analysis、skill-derivation、cross-session-analysis、agent-improvement、transcript-parsing、failure-analysis、agent-skills

---

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License