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

chapter2/system-hint/NOTES.md

@@ -0,0 +1,141 @@
+# System-Hint Agent Implementation Notes
+
+## Comparison with Week1/Context Pattern
+
+This project follows the same ReAct loop pattern as week1/context with the following enhancements:
+
+### Similarities to Week1/Context:
+1. **ReAct Loop**: Standard Reasoning + Acting pattern
+2. **Command-Line Interface**: Uses argparse for CLI arguments
+3. **Interactive Mode**: Default mode for user interaction
+4. **Task Execution**: `execute_task()` method with max iterations
+5. **Kimi K3 Model**: Uses the same LLM provider setup
+
+### Key Enhancements:
+
+#### 1. System Prompt Architecture
+- **Week1/Context**: Basic system prompt with tool descriptions
+- **System-Hint**: Enhanced system prompt with:
+  - TODO list management rules
+  - Error handling guidelines
+  - Loop prevention strategies
+  - Behavioral instructions
+
+#### 2. Context Management
+- **Week1/Context**: Manages conversation history with optional context modes
+- **System-Hint**: Dynamic system hints that update after each interaction:
+  - Current timestamp
+  - System state (directory, OS, shell)
+  - TODO list status
+  - Tool call counters
+
+#### 3. Tool Feedback
+- **Week1/Context**: Standard tool results
+- **System-Hint**: Enhanced tool results with:
+  - Timestamps on each result
+  - Call numbers (e.g., "Tool call #3")
+  - Detailed error messages with suggestions
+  - Execution duration tracking
+
+#### 4. Task Management
+- **Week1/Context**: Single-task execution
+- **System-Hint**: Built-in TODO list system:
+  - Automatic creation for complex tasks
+  - Status tracking (pending, in_progress, completed, cancelled)
+  - Persistent across conversation turns
+
+## Sample Task
+
+The default sample task demonstrates analyzing week1 and week2 projects, similar to the context project's financial analysis tasks but focused on code exploration:
+
+```python
+# Sample task that exercises multiple tools
+task = """Analyze and summarize the AI Agent projects in week1 and week2 directories:
+1. Navigate to the parent directory to access both week1 and week2 folders
+2. For week1 directory:
+   - List all project folders
+   - Read key files from projects
+   - Identify the key concepts
+3. For week2 directory:
+   - List all project folders  
+   - Read README files
+   - Understand advanced features
+4. Create a comprehensive analysis file
+"""
+```
+
+## Command-Line Usage
+
+Following week1/context pattern with additional options:
+
+```bash
+# Interactive mode (default)
+python main.py
+
+# Single task execution (like week1/context)
+python main.py --mode single --task "Your task here"
+
+# Sample task (new)
+python main.py --mode sample
+
+# Feature flags (new)
+python main.py --no-todo --no-timestamps --mode single --task "Simple task"
+```
+
+## Configuration Flexibility
+
+Unlike week1/context which has fixed context modes, system-hint allows granular control:
+
+```python
+# Week1/Context approach
+context_mode = ContextMode.FULL  # or NO_HISTORY, NO_REASONING, etc.
+
+# System-Hint approach
+config = SystemHintConfig(
+    enable_timestamps=True,     # Toggle individually
+    enable_tool_counter=True,
+    enable_todo_list=True,
+    enable_detailed_errors=True,
+    enable_system_state=True
+)
+```
+
+## Best Practices Demonstrated
+
+1. **Prevent Infinite Loops**: Tool call counter shows "Tool call #N" to help agent recognize repetitive behavior
+2. **Temporal Awareness**: Timestamps help agent understand event sequences
+3. **Task Organization**: TODO lists for complex multi-step objectives
+4. **Error Recovery**: Detailed error messages with actionable suggestions
+5. **Context Preservation**: System state tracking across tool calls
+
+## Testing
+
+Similar to week1/context with additional component tests:
+
+```bash
+# Basic component tests
+python test_basic.py
+
+# Quick demonstration
+python quickstart.py
+
+# Full interactive testing
+python main.py
+```
+
+## Key Learnings
+
+1. **System hints significantly improve agent efficiency** - Agents complete tasks with fewer iterations
+2. **TODO lists provide structure** - Complex tasks become manageable
+3. **Tool counters prevent loops** - Agents recognize and avoid repetitive behavior
+4. **Detailed errors enable recovery** - Agents can adapt strategies based on specific error information
+5. **Timestamps provide context** - Useful for multi-session or long-running tasks
+
+## Future Enhancements
+
+Potential improvements building on this foundation:
+- Memory persistence across sessions
+- Collaborative TODO lists for multi-agent systems
+- Adaptive hint generation based on task complexity
+- Performance metrics tracking
+- Integration with external task management systems