清理工作

.gitignore

@@ -1,4 +1,5 @@
 # Project specific additions
+AGENTS.md
 .devflag
 .vscode/
 .directory

AGENTS.md

@@ -1,238 +0,0 @@
-# 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)
-```
-
-### 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
-
-## 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*