fix: 增加日志
This commit is contained in:
266
AGENTS.md
Normal file
266
AGENTS.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Agent Guide for HeurAMS
|
||||
|
||||
This document contains essential information for AI agents working in the HeurAMS (Heuristic Assisted Memory Scheduler) codebase.
|
||||
|
||||
## Project Overview
|
||||
|
||||
HeurAMS is a Python-based memory scheduling application with a TUI interface built using Textual. It implements a spaced repetition system with configurable algorithms, puzzles, and data persistence.
|
||||
|
||||
**Key Technologies**:
|
||||
- Python 3 (setuptools)
|
||||
- Textual (TUI framework)
|
||||
- TOML for configuration
|
||||
- JSON and TOML for data persistence
|
||||
- Bidirectional mapping via `bidict`
|
||||
|
||||
**Project Structure**:
|
||||
```
|
||||
src/heurams/
|
||||
├── __init__.py # Package entry point
|
||||
├── context.py # Global context, paths, config context manager
|
||||
├── services/ # Core services (config, logger, timer, audio, TTS)
|
||||
├── kernel/ # Core business logic
|
||||
│ ├── algorithms/ # Spaced repetition algorithms (FSRS, SM2)
|
||||
│ ├── particles/ # Data models (Atom, Electron, Nucleon, Orbital)
|
||||
│ ├── puzzles/ # Puzzle types (MCQ, cloze, recognition)
|
||||
│ └── reactor/ # Scheduling and processing logic
|
||||
├── providers/ # External service providers
|
||||
│ ├── audio/ # Audio playback implementations
|
||||
│ ├── tts/ # Text-to-speech implementations
|
||||
│ └── llm/ # LLM integrations
|
||||
├── interface/ # Textual TUI interface
|
||||
│ ├── widgets/ # UI widget components
|
||||
│ ├── screens/ # Application screens
|
||||
│ └── __main__.py # Application entry point
|
||||
└── default/ # Default configuration and data templates
|
||||
```
|
||||
|
||||
## Essential Commands
|
||||
|
||||
### Development Setup
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Install package in development mode
|
||||
pip install -e .
|
||||
|
||||
# Build package (produces dist/)
|
||||
python -m build
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
```bash
|
||||
# Run the TUI application
|
||||
python -m heurams.interface
|
||||
|
||||
# Alternative: if installed via pip
|
||||
heurams # (if console scripts are configured)
|
||||
```
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run tests (if test suite exists)
|
||||
pytest
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=heurams
|
||||
```
|
||||
|
||||
**Note**: The test directory appears to have been removed. Previous test files were located in `tests/` (deleted per git status). If adding new tests, follow pytest conventions and place them in a `tests/` directory at the project root.
|
||||
|
||||
### Linting and Formatting
|
||||
No specific linting or formatting configuration observed. Use standard Python conventions.
|
||||
|
||||
## Code Organization
|
||||
|
||||
### Key Modules
|
||||
|
||||
1. **context.py** (`src/heurams/context.py`):
|
||||
- Defines `rootdir`, `workdir`, and `config_var` (ContextVar) for configuration
|
||||
- Provides `ConfigContext` context manager for temporary configuration switching
|
||||
- Configuration is loaded from `config/config.toml` relative to workdir, falling back to default config
|
||||
|
||||
2. **Services** (`src/heurams/services/`):
|
||||
- `config.py`: `ConfigFile` class for TOML configuration management
|
||||
- `logger.py`: Comprehensive logging setup with rotation and namespacing
|
||||
- `timer.py`: Time services with configurable overrides for testing
|
||||
- `audio_service.py`: Audio playback abstraction
|
||||
- `tts_service.py`: Text-to-speech service abstraction
|
||||
|
||||
3. **Kernel** (`src/heurams/kernel/`):
|
||||
- **Particles**: Data models representing memory items:
|
||||
- `Atom`: Composite of Nucleon (content), Electron (algorithm data), Orbital (strategy)
|
||||
- `Nucleon`: Content data (TOML)
|
||||
- `Electron`: Algorithm data (JSON)
|
||||
- `Orbital`: Strategy configuration (TOML)
|
||||
- **Algorithms**: Spaced repetition algorithm implementations (FSRS, SM2)
|
||||
- **Puzzles**: Interactive puzzle types for review sessions
|
||||
- **Reactor**: Scheduling and state management
|
||||
|
||||
4. **Providers** (`src/heurams/providers/`):
|
||||
- Abstract base classes and implementations for external services
|
||||
- Audio playback (`playsound_audio.py`, `termux_audio.py`)
|
||||
- TTS (`edge_tts.py`)
|
||||
- LLM (`openai.py`)
|
||||
|
||||
5. **Interface** (`src/heurams/interface/`):
|
||||
- Textual-based TUI with multiple screens
|
||||
- Widgets for different puzzle types
|
||||
- CSS styling in `css/` directory
|
||||
|
||||
## Naming Conventions and Style Patterns
|
||||
|
||||
### Code Style
|
||||
- **Indentation**: 4 spaces (no tabs observed)
|
||||
- **Line length**: No explicit limit, typical Python conventions
|
||||
- **Imports**: Standard library first, then third-party, then local modules
|
||||
- **Type hints**: Used extensively throughout codebase
|
||||
- **Docstrings**: Chinese and English mixed, some functions have descriptive docstrings
|
||||
|
||||
### Naming
|
||||
- **Classes**: `CamelCase` (e.g., `ConfigFile`, `BaseAlgorithm`, `HeurAMSApp`)
|
||||
- **Functions/Methods**: `snake_case` (e.g., `get_daystamp`, `setup_logging`)
|
||||
- **Variables**: `snake_case` (e.g., `config_var`, `atom_registry`)
|
||||
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_LOG_LEVEL`)
|
||||
|
||||
### Patterns Observed
|
||||
- Use `typing` module for type annotations (`TypedDict`, `Union`, `Optional`, etc.)
|
||||
- Context variables via `contextvars` for configuration management
|
||||
- Registry pattern using `bidict` for global object tracking (e.g., `atom_registry`)
|
||||
- Service abstraction with provider pattern (audio, TTS, LLM)
|
||||
- Configuration-driven behavior with fallback defaults
|
||||
|
||||
## Testing Approach
|
||||
|
||||
**Current State**: Test directory removed, but `.pytest_cache` indicates pytest was used.
|
||||
|
||||
**If adding tests**:
|
||||
- Place tests in `tests/` directory at project root
|
||||
- Follow pytest conventions
|
||||
- Use `pytest.fixture` for shared test resources
|
||||
- Mock external dependencies (audio, TTS, LLM providers)
|
||||
- Test configuration overrides via `ConfigContext`
|
||||
|
||||
**Testable Components**:
|
||||
- Algorithm implementations (FSRS, SM2)
|
||||
- Puzzle logic validation
|
||||
- Configuration loading and saving
|
||||
- Atom persistence and evaluation
|
||||
|
||||
## Important Gotchas
|
||||
|
||||
### Configuration Loading
|
||||
- Configuration is loaded from `config/config.toml` relative to the **current working directory**
|
||||
- If not found, falls back to `src/heurams/default/config/config.toml`
|
||||
- The `config_var` ContextVar is used throughout the codebase to access configuration
|
||||
- Use `ConfigContext` for temporary configuration changes in tests or specific operations
|
||||
|
||||
### Path Handling
|
||||
- `rootdir`: Package directory (`src/heurams/`)
|
||||
- `workdir`: Current working directory (set at runtime)
|
||||
- Data paths (`nucleon_dir`, `electron_dir`, etc.) are relative to `workdir` by default
|
||||
- The application may change working directory in development mode (see `__main__.py` lines 61-63)
|
||||
|
||||
### Eval Security
|
||||
- The `Atom.do_eval()` method evaluates strings prefixed with `"eval:"` in data structures
|
||||
- This is a security consideration - user-provided content could execute arbitrary code
|
||||
- Evaluation is limited to a sandboxed environment but caution is advised
|
||||
|
||||
### Logging
|
||||
- Logging is configured automatically via `logger.py` setup
|
||||
- Logs go to `/tmp/heurams.log` by default (configurable)
|
||||
- Logger names are prefixed with `"heurams."` automatically
|
||||
- Third-party library log levels are set to WARNING to reduce noise
|
||||
|
||||
### Time Overrides
|
||||
- `daystamp_override` and `timestamp_override` in config allow time manipulation for testing
|
||||
- When set to values other than `-1`, they override `get_daystamp()` and `get_timestamp()`
|
||||
- Useful for reproducible testing of scheduling algorithms
|
||||
|
||||
## Configuration
|
||||
|
||||
### Default Configuration (`src/heurams/default/config/config.toml`)
|
||||
```toml
|
||||
# Debug settings
|
||||
persist_to_file = 1
|
||||
daystamp_override = -1
|
||||
timestamp_override = -1
|
||||
quick_pass = 0
|
||||
|
||||
# Default number of new memory items
|
||||
tasked_number = 8
|
||||
|
||||
# Timezone offset for daystamp calculation (seconds)
|
||||
timezone_offset = +28800 # China Standard Time (UTC+8)
|
||||
|
||||
# Puzzle defaults
|
||||
[puzzles.mcq]
|
||||
max_riddles_num = 2
|
||||
|
||||
[puzzles.cloze]
|
||||
min_denominator = 3
|
||||
|
||||
# Data paths (relative to workdir or absolute)
|
||||
[paths]
|
||||
nucleon_dir = "./data/nucleon"
|
||||
electron_dir = "./data/electron"
|
||||
orbital_dir = "./data/orbital"
|
||||
cache_dir = "./data/cache"
|
||||
```
|
||||
|
||||
### User Configuration
|
||||
Place `config.toml` in `config/` directory relative to where the application is run. The structure should match the default configuration.
|
||||
|
||||
## Running the Application
|
||||
|
||||
### Development Mode
|
||||
When running from within the project directory, the application may change working directory to ensure data paths resolve correctly (see `__main__.py`).
|
||||
|
||||
### Production/Installed Mode
|
||||
When installed via pip, the working directory is wherever the command is executed. Ensure a `config/` directory with `config.toml` exists, or rely on defaults.
|
||||
|
||||
### Entry Points
|
||||
- Primary: `python -m heurams.interface`
|
||||
- The `__main__.py` performs environment checks, ensures directories exist, then launches the Textual app
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Dependencies
|
||||
- Listed in `requirements.txt`: `bidict`, `playsound`, `textual`, `toml`
|
||||
- Additional dependencies may be needed for specific providers (e.g., `edge-tts`)
|
||||
|
||||
### Adding New Features
|
||||
|
||||
**New Puzzle Type**:
|
||||
1. Add class in `src/heurams/kernel/puzzles/`
|
||||
2. Inherit from `BasePuzzle`
|
||||
3. Add corresponding widget in `src/heurams/interface/widgets/`
|
||||
4. Integrate into appropriate screens
|
||||
|
||||
**New Algorithm**:
|
||||
1. Add class in `src/heurams/kernel/algorithms/`
|
||||
2. Inherit from `BaseAlgorithm`
|
||||
3. Implement `revisor()`, `is_due()`, `rate()`, `nextdate()` methods
|
||||
4. Update algorithm selection logic if needed
|
||||
|
||||
**New Provider**:
|
||||
1. Add implementation in relevant provider directory (`audio/`, `tts/`, `llm/`)
|
||||
2. Inherit from base class in same directory
|
||||
3. Register in provider registry (see `__init__.py` in provider directories)
|
||||
|
||||
### Data Models
|
||||
- **Nucleon**: Content data (TOML), contains metadata and puzzle content
|
||||
- **Electron**: Algorithm state (JSON), tracks review history and scheduling
|
||||
- **Orbital**: Strategy configuration (TOML), defines review parameters
|
||||
- **Atom**: Composite of all three, managed via `atom_registry`
|
||||
|
||||
### Persistence
|
||||
- Data is saved to paths specified in configuration
|
||||
- Formats: TOML for Nucleon/Orbital, JSON for Electron
|
||||
- Automatic directory creation on save
|
||||
- The `Atom.persist()` method handles saving individual components
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: Based on codebase analysis on 2025-12-15*
|
||||
Reference in New Issue
Block a user