ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter2/kv-cache/tests/manual/_bootstrap.py

@@ -0,0 +1,11 @@
+"""Helpers for running kv-cache manual smoke scripts from tests/manual."""
+
+from pathlib import Path
+import sys
+
+
+def add_project_root() -> Path:
+    project_root = Path(__file__).resolve().parents[2]
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+    return project_root

chapter2/kv-cache/tests/manual/check_agent_error_recovery.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Manual live check for agent recovery after tool errors."""
+
+import os
+import sys
+
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+
+def check_agent_error_recovery():
+    """Run the live agent against an intentionally failing tool path."""
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+
+    print("🧪 Testing agent error recovery")
+    print("=" * 60)
+
+    agent = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=True,
+    )
+
+    task = """Please do the following:
+    1. Try to read a file that doesn't exist: 'non_existent_file.txt'
+    2. Then find Python files in chapter1/context directory
+    3. Tell me what you found"""
+
+    print(f"Task: {task[:100]}...")
+    result = agent.execute_task(task, max_iterations=10)
+
+    print(f"\n✓ Completed in {result['iterations']} iterations")
+    print(f"✓ Tool calls made: {len(result['tool_calls'])}")
+
+    error_count = 0
+    for tool_call in result["tool_calls"]:
+        if tool_call.result and not tool_call.result.get("success", True):
+            error_count += 1
+            print(
+                f"• Tool error in {tool_call.name}: "
+                f"{tool_call.result.get('error', 'Unknown')[:50]}..."
+            )
+
+    print(f"✓ Errors encountered and handled: {error_count}")
+    print(f"✓ Agent continued despite errors: {result['success']}")
+
+    if result["final_answer"]:
+        print("\nFinal answer provided despite errors:")
+        print(f"{result['final_answer'][:200]}...")
+
+
+if __name__ == "__main__":
+    check_agent_error_recovery()

chapter2/kv-cache/tests/manual/check_cache_invalidation.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Test script to verify KV cache is properly invalidated in incorrect modes
+"""
+
+import os
+import sys
+import logging
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+# Set up logging to see details
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def test_cache_invalidation():
+    """Test that incorrect modes properly invalidate KV cache each iteration"""
+    
+    # Get API key
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+    
+    print("🔬 Testing KV Cache Invalidation")
+    print("="*60)
+    
+    # Simple task that requires multiple iterations
+    task = "Find Python files in chapter1/context and tell me how many there are."
+    
+    print(f"Task: {task}")
+    print("-"*40)
+    
+    # Test 1: CORRECT mode (should use cache)
+    print("\n1️⃣ Testing CORRECT mode (should use cache):")
+    agent_correct = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=True
+    )
+    
+    result_correct = agent_correct.execute_task(task, max_iterations=5)
+    metrics_correct = result_correct["metrics"]
+    
+    print(f"\n  Results for CORRECT mode:")
+    print(f"  • Iterations: {result_correct['iterations']}")
+    print(f"  • TTFT per iteration: {[f'{t:.2f}s' for t in metrics_correct.ttft_per_iteration]}")
+    print(f"  • Cached tokens: {metrics_correct.cached_tokens}")
+    print(f"  • Cache hits: {metrics_correct.cache_hits}")
+    
+    # Test 2: DYNAMIC_SYSTEM mode (should NOT use cache)
+    print("\n2️⃣ Testing DYNAMIC_SYSTEM mode (should NOT use cache):")
+    agent_dynamic = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.DYNAMIC_SYSTEM,
+        root_dir="../..",
+        verbose=True
+    )
+    
+    result_dynamic = agent_dynamic.execute_task(task, max_iterations=5)
+    metrics_dynamic = result_dynamic["metrics"]
+    
+    print(f"\n  Results for DYNAMIC_SYSTEM mode:")
+    print(f"  • Iterations: {result_dynamic['iterations']}")
+    print(f"  • TTFT per iteration: {[f'{t:.2f}s' for t in metrics_dynamic.ttft_per_iteration]}")
+    print(f"  • Cached tokens: {metrics_dynamic.cached_tokens}")
+    print(f"  • Cache hits: {metrics_dynamic.cache_hits}")
+    
+    # Analysis
+    print("\n" + "="*60)
+    print("📊 ANALYSIS:")
+    print("-"*40)
+    
+    # Check TTFT improvement
+    if len(metrics_correct.ttft_per_iteration) > 1:
+        correct_improvement = (metrics_correct.ttft_per_iteration[0] - metrics_correct.ttft_per_iteration[-1]) / metrics_correct.ttft_per_iteration[0] * 100
+        print(f"CORRECT mode TTFT improvement: {correct_improvement:.1f}%")
+    
+    if len(metrics_dynamic.ttft_per_iteration) > 1:
+        dynamic_improvement = (metrics_dynamic.ttft_per_iteration[0] - metrics_dynamic.ttft_per_iteration[-1]) / metrics_dynamic.ttft_per_iteration[0] * 100
+        print(f"DYNAMIC mode TTFT improvement: {dynamic_improvement:.1f}%")
+    
+    # Verify cache behavior
+    print("\n✅ Verification:")
+    if metrics_correct.cached_tokens > 0:
+        print(f"  ✓ CORRECT mode used cache: {metrics_correct.cached_tokens} tokens")
+    else:
+        print(f"  ✗ CORRECT mode did NOT use cache (unexpected!)")
+    
+    if metrics_dynamic.cached_tokens == 0:
+        print(f"  ✓ DYNAMIC mode did NOT use cache (expected)")
+    else:
+        print(f"  ✗ DYNAMIC mode used cache: {metrics_dynamic.cached_tokens} tokens (unexpected!)")
+    
+    # Check TTFT consistency
+    print("\n🔍 TTFT Consistency Check:")
+    if len(metrics_correct.ttft_per_iteration) > 2:
+        # CORRECT mode should show improvement after first iteration
+        first_ttft = metrics_correct.ttft_per_iteration[0]
+        avg_rest = sum(metrics_correct.ttft_per_iteration[1:]) / len(metrics_correct.ttft_per_iteration[1:])
+        if avg_rest < first_ttft * 0.7:  # At least 30% improvement
+            print(f"  ✓ CORRECT mode shows cache benefit (first: {first_ttft:.2f}s, avg rest: {avg_rest:.2f}s)")
+        else:
+            print(f"  ⚠️ CORRECT mode improvement less than expected")
+    
+    if len(metrics_dynamic.ttft_per_iteration) > 2:
+        # DYNAMIC mode should NOT show significant improvement
+        all_ttfts = metrics_dynamic.ttft_per_iteration
+        min_ttft = min(all_ttfts)
+        max_ttft = max(all_ttfts)
+        if (max_ttft - min_ttft) / max_ttft < 0.3:  # Less than 30% variation
+            print(f"  ✓ DYNAMIC mode shows consistent TTFT (no cache benefit)")
+        else:
+            print(f"  ⚠️ DYNAMIC mode shows unexpected TTFT variation")
+    
+    print("\n💡 Key Finding:")
+    print("The CORRECT mode should show significant TTFT improvement after the first")
+    print("iteration due to KV cache, while incorrect modes should maintain")
+    print("consistently high TTFT because the cache is invalidated on each iteration.")
+
+if __name__ == "__main__":
+    test_cache_invalidation()

chapter2/kv-cache/tests/manual/check_cached_tokens.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Test script to verify cached tokens are being parsed correctly from Kimi API
+"""
+
+import os
+import sys
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+def test_cached_tokens():
+    """Test that cached tokens are correctly parsed from API response"""
+    
+    # Get API key
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+    
+    print("🔍 Testing Cached Tokens Parsing")
+    print("="*60)
+    
+    # Simple task that requires a few iterations
+    task = "Find Python files in chapter1/context directory and tell me how many there are."
+    
+    print(f"Task: {task}")
+    print("-"*40)
+    
+    # Run with correct implementation (should use cache)
+    print("\nRunning agent with CORRECT implementation...")
+    agent = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=True  # Enable verbose to see token logging
+    )
+    
+    result = agent.execute_task(task, max_iterations=5)
+    metrics = result["metrics"]
+    
+    print("\n" + "="*60)
+    print("📊 Cache Token Results:")
+    print(f"  • Total iterations: {result['iterations']}")
+    print(f"  • Cached tokens accumulated: {metrics.cached_tokens}")
+    print(f"  • Cache hits: {metrics.cache_hits}")
+    print(f"  • Cache misses: {metrics.cache_misses}")
+    
+    # Check each iteration's TTFT
+    if metrics.ttft_per_iteration:
+        print(f"\n  • TTFT per iteration:")
+        for i, ttft in enumerate(metrics.ttft_per_iteration, 1):
+            status = "🔴 No cache" if i == 1 else "🟢 With cache"
+            print(f"      Iteration {i}: {ttft:.3f}s {status}")
+    
+    # Verify cache is working
+    print("\n✅ Verification:")
+    if metrics.cached_tokens > 0:
+        print(f"  ✓ Cached tokens detected: {metrics.cached_tokens}")
+    else:
+        print(f"  ⚠️ No cached tokens detected - cache may not be working")
+    
+    if len(metrics.ttft_per_iteration) > 1:
+        first_ttft = metrics.ttft_per_iteration[0]
+        second_ttft = metrics.ttft_per_iteration[1]
+        if second_ttft < first_ttft * 0.8:  # At least 20% improvement
+            print(f"  ✓ TTFT improved from {first_ttft:.3f}s to {second_ttft:.3f}s")
+        else:
+            print(f"  ⚠️ TTFT did not improve significantly")
+    
+    print("\n💡 Note: Kimi API should return cached_tokens in the usage object")
+    print("   starting from the second iteration when context is stable.")
+
+if __name__ == "__main__":
+    test_cached_tokens()

chapter2/kv-cache/tests/manual/check_completion.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Test script to verify the agent correctly identifies final answers
+when no tool calls are made
+"""
+
+import os
+import sys
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+def test_completion_logic():
+    """Test that the agent correctly handles responses without tool calls as final answers"""
+    
+    # Get API key
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+    
+    print("🧪 Testing Final Answer Detection")
+    print("="*60)
+    
+    # Test 1: Simple question that doesn't require tools
+    print("\n1️⃣ Test: Simple question without tools")
+    task1 = "What is 2 + 2? Just tell me the answer, no need to use any tools."
+    
+    agent = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=False
+    )
+    
+    result = agent.execute_task(task1, max_iterations=5)
+    print(f"   Task: {task1}")
+    print(f"   ✓ Completed in {result['iterations']} iteration(s)")
+    print(f"   ✓ Tool calls: {len(result['tool_calls'])}")
+    print(f"   ✓ Has final answer: {result['success']}")
+    if result['final_answer']:
+        print(f"   Answer: {result['final_answer'][:100]}")
+    
+    # Test 2: Question that requires tools
+    print("\n2️⃣ Test: Question requiring tools")
+    task2 = "How many Python files are in the chapter1/context directory?"
+    
+    agent2 = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=False
+    )
+    
+    result2 = agent2.execute_task(task2, max_iterations=5)
+    print(f"   Task: {task2}")
+    print(f"   ✓ Completed in {result2['iterations']} iteration(s)")
+    print(f"   ✓ Tool calls: {len(result2['tool_calls'])}")
+    print(f"   ✓ Has final answer: {result2['success']}")
+    
+    if result2['tool_calls']:
+        print("   Tools used:")
+        for tc in result2['tool_calls']:
+            print(f"     • {tc.name}")
+    
+    # Test 3: Multi-step task
+    print("\n3️⃣ Test: Multi-step task")
+    task3 = "Find Python files in chapter1/context, then tell me if there's a file named 'agent.py'"
+    
+    agent3 = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=False
+    )
+    
+    result3 = agent3.execute_task(task3, max_iterations=10)
+    print(f"   Task: {task3}")
+    print(f"   ✓ Completed in {result3['iterations']} iteration(s)")
+    print(f"   ✓ Tool calls: {len(result3['tool_calls'])}")
+    print(f"   ✓ Has final answer: {result3['success']}")
+    
+    # Summary
+    print("\n" + "="*60)
+    print("📊 Summary:")
+    print(f"  • Test 1 (no tools): {result['iterations']} iterations, {len(result['tool_calls'])} tools")
+    print(f"  • Test 2 (with tools): {result2['iterations']} iterations, {len(result2['tool_calls'])} tools")
+    print(f"  • Test 3 (multi-step): {result3['iterations']} iterations, {len(result3['tool_calls'])} tools")
+    
+    print("\n✅ The agent correctly:")
+    print("  1. Identifies final answers when no tools are needed")
+    print("  2. Uses tools when necessary to gather information")
+    print("  3. Provides final answer after tool execution")
+    print("\nNo explicit 'final answer' keyword needed!")
+
+if __name__ == "__main__":
+    test_completion_logic()

chapter2/kv-cache/tests/manual/check_tool_calling.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Test script to verify the updated agent works with standard OpenAI tool calling
+"""
+
+import os
+import sys
+import json
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+def test_tool_calling():
+    """Test that the agent correctly uses OpenAI tool calling format"""
+    
+    # Get API key
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+    
+    print("🧪 Testing Standard OpenAI Tool Calling Format")
+    print("="*60)
+    
+    # Simple task that requires tool calls
+    task = "Find all Python files in the chapter1/context directory and tell me how many there are."
+    
+    print(f"📝 Task: {task}")
+    print("-"*60)
+    
+    # Create agent with correct implementation
+    agent = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=True  # Enable verbose to see tool calls
+    )
+    
+    # Execute task
+    result = agent.execute_task(task, max_iterations=5)
+    
+    # Check results
+    print("\n" + "="*60)
+    print("📊 Results:")
+    print(f"✓ Success: {result['success']}")
+    print(f"✓ Iterations: {result['iterations']}")
+    print(f"✓ Tool Calls Made: {len(result['tool_calls'])}")
+    
+    if result['tool_calls']:
+        print("\n🔧 Tool Calls:")
+        for tc in result['tool_calls']:
+            print(f"  • {tc.name}({tc.arguments})")
+            if tc.result and tc.result.get('success'):
+                if tc.name == 'find':
+                    print(f"    → Found {tc.result.get('count', 0)} files")
+    
+    if result['final_answer']:
+        print(f"\n💬 Final Answer:")
+        print(f"  {result['final_answer'][:200]}...")
+    
+    # Test metrics
+    metrics = result['metrics']
+    print(f"\n📈 Performance Metrics:")
+    print(f"  • TTFT: {metrics.ttft:.3f}s")
+    print(f"  • Total Time: {metrics.total_time:.3f}s")
+    print(f"  • Cached Tokens: {metrics.cached_tokens}")
+    
+    print("\n✅ Tool calling test completed successfully!")
+
+if __name__ == "__main__":
+    test_tool_calling()

chapter2/kv-cache/tests/manual/check_ttft.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Test script to demonstrate TTFT tracking across iterations
+Shows how cache usage improves response times
+"""
+
+import os
+import sys
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+def test_ttft_tracking():
+    """Test and display TTFT tracking across iterations"""
+    
+    # Get API key
+    api_key = os.getenv("MOONSHOT_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY environment variable")
+        sys.exit(1)
+    
+    print("📊 TTFT Tracking Demonstration")
+    print("="*60)
+    
+    # Task that requires multiple iterations
+    task = """Analyze the chapter1/context directory:
+    1. Find all Python files
+    2. Read the agent.py file (first 100 lines)
+    3. Search for classes in the code
+    4. Provide a summary of what you found"""
+    
+    print(f"Task: {task[:100]}...")
+    print("="*60)
+    
+    # Test with correct implementation (should show cache benefits)
+    print("\n✅ CORRECT Implementation (with KV cache):")
+    print("-"*40)
+    
+    agent = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=False  # Set to True to see detailed logs
+    )
+    
+    result = agent.execute_task(task, max_iterations=10)
+    metrics = result["metrics"]
+    
+    # Display TTFT progression
+    print(f"Iterations completed: {result['iterations']}")
+    print(f"Tool calls made: {len(result['tool_calls'])}")
+    print(f"\nTTFT per iteration:")
+    
+    for i, ttft in enumerate(metrics.ttft_per_iteration, 1):
+        bar_length = int(ttft * 10)  # Visual bar representation
+        bar = "█" * min(bar_length, 50)
+        print(f"  Iter {i:2d}: {ttft:6.3f}s {bar}")
+    
+    # Calculate statistics
+    if len(metrics.ttft_per_iteration) > 1:
+        first = metrics.ttft_per_iteration[0]
+        last = metrics.ttft_per_iteration[-1]
+        avg_all = sum(metrics.ttft_per_iteration) / len(metrics.ttft_per_iteration)
+        avg_after_first = sum(metrics.ttft_per_iteration[1:]) / len(metrics.ttft_per_iteration[1:])
+        
+        print(f"\n📈 Performance Analysis:")
+        print(f"  • First iteration:    {first:.3f}s (cold start)")
+        print(f"  • Last iteration:     {last:.3f}s")
+        print(f"  • Average (all):      {avg_all:.3f}s")
+        print(f"  • Average (cached):   {avg_after_first:.3f}s")
+        print(f"  • Speed improvement:  {(first - last) / first * 100:.1f}%")
+        print(f"  • Cached tokens:      {metrics.cached_tokens:,}")
+    
+    # Compare with dynamic system prompt (no cache benefits)
+    print("\n" + "="*60)
+    print("❌ DYNAMIC SYSTEM Implementation (breaks KV cache):")
+    print("-"*40)
+    
+    agent2 = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.DYNAMIC_SYSTEM,
+        root_dir="../..",
+        verbose=False
+    )
+    
+    result2 = agent2.execute_task(task, max_iterations=10)
+    metrics2 = result2["metrics"]
+    
+    print(f"Iterations completed: {result2['iterations']}")
+    print(f"Tool calls made: {len(result2['tool_calls'])}")
+    print(f"\nTTFT per iteration:")
+    
+    for i, ttft in enumerate(metrics2.ttft_per_iteration, 1):
+        bar_length = int(ttft * 10)
+        bar = "█" * min(bar_length, 50)
+        print(f"  Iter {i:2d}: {ttft:6.3f}s {bar}")
+    
+    if len(metrics2.ttft_per_iteration) > 1:
+        first2 = metrics2.ttft_per_iteration[0]
+        last2 = metrics2.ttft_per_iteration[-1]
+        avg_all2 = sum(metrics2.ttft_per_iteration) / len(metrics2.ttft_per_iteration)
+        
+        print(f"\n📉 Performance Analysis:")
+        print(f"  • First iteration:    {first2:.3f}s")
+        print(f"  • Last iteration:     {last2:.3f}s")
+        print(f"  • Average (all):      {avg_all2:.3f}s")
+        print(f"  • Speed improvement:  {(first2 - last2) / first2 * 100:.1f}% (minimal)")
+        print(f"  • Cached tokens:      {metrics2.cached_tokens:,} (should be 0)")
+    
+    # Comparison
+    print("\n" + "="*60)
+    print("🔬 COMPARISON:")
+    print("-"*40)
+    
+    if metrics.ttft_per_iteration and metrics2.ttft_per_iteration:
+        avg1 = sum(metrics.ttft_per_iteration) / len(metrics.ttft_per_iteration)
+        avg2 = sum(metrics2.ttft_per_iteration) / len(metrics2.ttft_per_iteration)
+        
+        print(f"Average TTFT:")
+        print(f"  • Correct (with cache):   {avg1:.3f}s")
+        print(f"  • Dynamic (no cache):     {avg2:.3f}s")
+        print(f"  • Difference:             {avg2 - avg1:.3f}s slower without cache")
+        print(f"  • Performance penalty:    {(avg2 - avg1) / avg1 * 100:.1f}% slower")
+        
+        print(f"\nCache Usage:")
+        print(f"  • Correct:   {metrics.cached_tokens:,} tokens cached")
+        print(f"  • Dynamic:   {metrics2.cached_tokens:,} tokens cached")
+    
+    print("\n💡 Key Observation:")
+    print("The correct implementation shows significant TTFT improvement after the")
+    print("first iteration due to KV cache, while dynamic system prompt maintains")
+    print("consistently high TTFT because the cache is invalidated on each request.")
+
+if __name__ == "__main__":
+    test_ttft_tracking()

chapter2/kv-cache/tests/manual/demo_quick.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""
+Quick demonstration of KV cache impact
+Shows the difference between correct and incorrect implementations
+"""
+
+import os
+import sys
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass
+
+from _bootstrap import add_project_root
+
+add_project_root()
+
+from agent import KVCacheAgent, KVCacheMode
+
+from agentbook.providers import PROVIDERS
+
+def main():
+    """Run a quick demo comparing correct vs incorrect implementation"""
+    
+    # Get API key. 优先 Moonshot/Kimi；缺失时回退 OPENROUTER_API_KEY
+    # （KVCacheAgent 会自动切换到 OpenRouter 端点并映射模型名）。
+    # 接受哪些环境变量由 agentbook 的 provider 注册表定义。
+    api_key = PROVIDERS["kimi"].api_key() or os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        print("❌ Please set MOONSHOT_API_KEY (or KIMI_API_KEY / OPENROUTER_API_KEY)")
+        print("   export MOONSHOT_API_KEY='your-api-key-here'")
+        sys.exit(1)
+    
+    print("🚀 KV Cache Quick Demo")
+    print("="*60)
+    
+    # Simple task that requires multiple tool calls
+    task = """Please do the following:
+    1. Find all Python files in the chapter1 directory
+    2. Read the main.py file from the context project
+    3. Search for the word 'agent' in chapter1 files
+    4. Provide a brief summary of what you found"""
+    
+    print(f"📝 Task: {task}")
+    print("="*60)
+    
+    # Test 1: Correct implementation
+    print("\n✅ Testing CORRECT implementation (with KV cache)...")
+    print("-"*60)
+    agent_correct = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.CORRECT,
+        root_dir="../..",
+        verbose=False  # Set to True for detailed logs
+    )
+    
+    result_correct = agent_correct.execute_task(task, max_iterations=10)
+    metrics_correct = result_correct["metrics"]
+    
+    print(f"✓ TTFT: {metrics_correct.ttft:.3f}s")
+    print(f"✓ Total Time: {metrics_correct.total_time:.3f}s")
+    print(f"✓ Cached Tokens: {metrics_correct.cached_tokens:,}")
+    print(f"✓ Cache Hits: {metrics_correct.cache_hits}")
+    print(f"✓ Total Tokens Used: {metrics_correct.prompt_tokens + metrics_correct.completion_tokens:,}")
+    
+    # Test 2: Incorrect implementation (dynamic system prompt)
+    print("\n❌ Testing INCORRECT implementation (dynamic system prompt)...")
+    print("-"*60)
+    agent_incorrect = KVCacheAgent(
+        api_key=api_key,
+        mode=KVCacheMode.DYNAMIC_SYSTEM,
+        root_dir="../..",
+        verbose=False
+    )
+    
+    result_incorrect = agent_incorrect.execute_task(task, max_iterations=10)
+    metrics_incorrect = result_incorrect["metrics"]
+    
+    print(f"✗ TTFT: {metrics_incorrect.ttft:.3f}s")
+    print(f"✗ Total Time: {metrics_incorrect.total_time:.3f}s")
+    print(f"✗ Cached Tokens: {metrics_incorrect.cached_tokens:,}")
+    print(f"✗ Cache Hits: {metrics_incorrect.cache_hits}")
+    print(f"✗ Total Tokens Used: {metrics_incorrect.prompt_tokens + metrics_incorrect.completion_tokens:,}")
+    
+    # Comparison
+    print("\n📊 Performance Impact:")
+    print("="*60)
+    
+    ttft_diff = ((metrics_incorrect.ttft - metrics_correct.ttft) / metrics_correct.ttft) * 100
+    time_diff = ((metrics_incorrect.total_time - metrics_correct.total_time) / metrics_correct.total_time) * 100
+    cache_lost = metrics_correct.cached_tokens - metrics_incorrect.cached_tokens
+    
+    print(f"⚡ TTFT increased by: {ttft_diff:.1f}%")
+    print(f"⏱️  Total time increased by: {time_diff:.1f}%")
+    print(f"💾 Cache tokens lost: {cache_lost:,}")
+    
+    if ttft_diff > 50:
+        print("\n⚠️  Dynamic system prompts severely impact performance!")
+        print("   Even small context changes can invalidate the entire KV cache.")
+    
+    print("\n💡 Key Takeaway:")
+    print("   Maintaining stable context is crucial for LLM performance.")
+    print("   Small implementation details can have major performance impacts!")
+
+if __name__ == "__main__":
+    main()