backup materials and knowledge-base docs

文档润色流和知识库构建流/claude-scholar-upstream/rules/coding-style.md

@@ -0,0 +1,250 @@
+# Code Style Rule
+
+Enforce code style standards for ML projects to ensure maintainability and consistency.
+
+## Core Principles
+
+### Small File Principle (200-400 lines)
+
+- Keep each file within 200-400 lines
+- Split into multiple modules when exceeding 400 lines
+- Organize related functionality under the same directory
+
+**Example structure:**
+```
+src/model_module/
+├── brain_decoder/
+│   ├── __init__.py          # Factory & Registry (50 lines)
+│   ├── base_model.py        # Base class (200 lines)
+│   ├── transformer.py       # Transformer impl (300 lines)
+│   └── cnn.py               # CNN impl (250 lines)
+```
+
+### Immutability First
+
+- Use dataclass for configuration (immutable)
+- Avoid mutating input parameters inside functions
+- Use `@dataclass(frozen=True)` to ensure config immutability
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class ModelConfig:
+    hidden_dim: int
+    num_layers: int
+    dropout: float = 0.1
+```
+
+### Error Handling
+
+- Use try/except for exception handling
+- Catch specific exception types, avoid bare except
+- Log error information for debugging
+
+```python
+try:
+    data = load_data(path)
+except FileNotFoundError as e:
+    logger.error(f"Data file not found: {path}")
+    raise
+```
+
+### Type Hints
+
+- All functions must have type hints
+- Use types from the typing module
+- Use TypeVar for complex types
+
+```python
+from typing import Dict, List, Optional, TypeVar
+
+T = TypeVar('T', bound=Dataset)
+
+def process_data(data: List[Dict], config: Config) -> Optional[DataFrame]:
+    ...
+```
+
+## Python Specific Standards
+
+### Import Order
+
+```python
+# 1. Standard library
+import os
+from pathlib import Path
+
+# 2. Third-party libraries
+import torch
+import numpy as np
+from hydra import compose, initialize
+
+# 3. Local modules
+from src.data_module import DataLoader
+from src.model_module import Model
+```
+
+### Naming Conventions
+
+```python
+# Class names: PascalCase
+class DataLoader:
+    pass
+
+# Functions/variables: snake_case
+def load_config():
+    batch_size = 32
+
+# Constants: UPPER_SNAKE_CASE
+MAX_EPOCHS = 100
+DEFAULT_LR = 0.001
+
+# Private: underscore prefix
+def _internal_function():
+    pass
+```
+
+### Docstrings
+
+```python
+def train_model(cfg: Config) -> Model:
+    """Train the model.
+
+    Args:
+        cfg: Training configuration object.
+
+    Returns:
+        Trained model instance.
+
+    Raises:
+        ValueError: When configuration is invalid.
+    """
+    ...
+```
+
+## ML Project Specific Standards
+
+### Factory & Registry Pattern
+
+All modules must use factory and registry patterns:
+
+```python
+# dataset/__init__.py
+DATASET_FACTORY: Dict[str, Type[Dataset]] = {}
+
+def register_dataset(name: str):
+    def decorator(cls):
+        DATASET_FACTORY[name] = cls
+        return cls
+    return decorator
+
+def DatasetFactory(name: str) -> Type[Dataset]:
+    return DATASET_FACTORY.get(name, SimpleDataset)
+```
+
+### Config-Driven Models
+
+Model `__init__` should only accept a `cfg` parameter:
+
+```python
+@register_model('MyModel')
+class MyModel(nn.Module):
+    def __init__(self, cfg: Config):
+        super().__init__()
+        # All hyperparameters from cfg
+        self.hidden_dim = cfg.model.hidden_dim
+```
+
+### Directory Structure
+
+```
+run/
+├── conf/                    # Hydra configs
+├── pipeline/                # Workflow scripts
+└── outputs/                 # Output directory
+
+src/
+├── data_module/             # Data module
+│   ├── dataset/
+│   ├── augmentation/
+│   └── utils.py
+├── model_module/            # Model module
+├── trainer_module/          # Trainer module
+└── utils/                   # Shared utilities
+```
+
+## Prohibited Patterns
+
+❌ **Prohibited:**
+- Files exceeding 800 lines
+- Nesting deeper than 4 levels
+- Mutable default arguments: `def foo(a=[]):`
+- Global variables (use config instead)
+- Bare except: `except:`
+- Hardcoded hyperparameters (use cfg)
+- Unused imports
+- print() debug statements (use logger)
+
+✅ **Recommended:**
+- Split large files
+- Use early returns to reduce nesting
+- `def foo(a=None):`
+- Config-driven parameters
+- Specific exception catching
+- Type hints
+- Docstrings
+- Logger for logging
+
+## Verification Checklist
+
+Before committing code, ensure:
+
+```bash
+# Type checking
+mypy src/
+
+# Code style
+ruff check .
+
+# Tests
+pytest
+```
+
+Violations of these rules will be flagged by the code-reviewer agent.
+
+## Logging Standards
+
+### Logger Naming
+
+```python
+import logging
+
+# Use module-level logger with __name__
+logger = logging.getLogger(__name__)
+```
+
+### Log Levels
+
+| Level | Usage |
+|-------|-------|
+| `DEBUG` | Detailed diagnostic info (tensor shapes, config values) |
+| `INFO` | Training progress, epoch results, key milestones |
+| `WARNING` | Recoverable issues (fallback behavior, deprecation) |
+| `ERROR` | Failures that need attention but don't crash |
+| `CRITICAL` | Unrecoverable errors |
+
+## Module `__init__.py` Standards
+
+Every package `__init__.py` must define `__all__` for explicit public API:
+
+```python
+# src/data_module/__init__.py
+from .dataset import DatasetFactory, register_dataset
+from .augmentation import AugmentationFactory
+
+__all__ = [
+    "DatasetFactory",
+    "register_dataset",
+    "AugmentationFactory",
+]
+```