# heuristic_learning **Repository Path**: Morphlng/heuristic_learning ## Basic Information - **Project Name**: heuristic_learning - **Description**: A bunch of deterministic task for testing Autoresearch project - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-13 - **Last Updated**: 2026-09-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

🎮 Heuristic Learning

让 Agent 持续改进可读、可测、可复现的游戏策略。
不训练神经网络，只写规则，然后用真实分数说话。

Python 3.11+ Managed by uv Rule-only policies Autoresearch

Heuristic Learning 是一组面向 Autoresearch 的优化任务。Agent 可以读取环境状态、分析失败轨迹、修改策略并补充回归测试；评估程序只认固定种子上的游戏分数。每次尝试都会留下 trial ledger，失败也不会被抹掉。 项目受 [Learning Beyond Gradients](https://github.com/Trinkle23897/learning-beyond-gradients) 启发。这里更关注一套可反复运行的工程基准：同一个仓库容纳不同难度的任务，共享评估协议，但各自保留策略、结果和搜索配置。 ## 🕹️ 任务 | 任务 | 环境 | 分数范围 | 动作空间 | 搜索策略 | 适合验证 | | --- | --- | ---: | --- | --- | --- | | `cartpole` | `CartPole-v1` | `0..500` | `0=LEFT 1=RIGHT` | Linear | 快速开发、基本迭代链路 | | `pong` | `Pong-v5` | `-21..21` | `0=NOOP 1=FIRE 2=UP 3=DOWN 4=UP 5=DOWN` | Linear | 目标跟踪、动作语义、几何预测 | | `breakout` | `Breakout-v5` | `0..864` | `0=NOOP 1=FIRE 2=RIGHT 3=LEFT` | MCTS | 长周期探索、回球控制、打破稳定循环 | **动作编号不跨任务通用**，`TaskSpec.action_meanings` 是唯一权威来源，由各任务模块（`src/heuristic_learning/tasks/*.py`）声明，策略也从同一常量取值，`heuristic-learning list` 会打印出来： ```bash uv run --locked heuristic-learning list ``` `tests/test_registry.py` 会把每个声明和真实环境对照，所以声明和实现对不上时测试会失败。 观测契约同样按 backend 区分，详见 `contracts.py` 里 `Policy` 的 docstring：Atari 的观测是**带 batch 维**的 `(1, 3, 210, 160)` RGB `uint8` 数组（单帧是 `observation[0]`），`info["ram"]` 提供原始的 `(1, 128)` Atari RAM，`info` 里还有 `lives`、`elapsed_step`；`cartpole` 则是原生的 `(4,)` float32 向量。 评估同时输出两个指标： - `score_mean`：环境的原始平均分。 - `progress`：按任务分数范围映射到 `0..1`，供 Autoresearch 比较候选。 初始策略很简单。NumPy、SciPy、OpenCV、Pandas 和 scikit-learn 已作为项目依赖提供，Agent 可以用它们做视觉检测、几何计算、统计分析或可解释的传统方法，但不能引入神经网络训练和隐藏模型。 ## 🚀 开始运行 ### 系统依赖 Debian/Ubuntu 上： ```bash sudo apt-get install -y libopengl0 libgl1 ``` ### 安装与运行 项目使用 uv，依赖从公共 PyPI 解析： ```bash uv sync --locked uv run --locked heuristic-learning list ``` 直接评估策略： ```bash uv run --locked heuristic-learning run cartpole --split dev --episodes 5 uv run --locked heuristic-learning run pong --split dev --episodes 1 uv run --locked heuristic-learning run breakout --split dev --episodes 1 ``` ## 📈 Trial ledger 每次评估都会向 `results//trials.jsonl` 追加记录，并重建 `summary.csv`： ```text results/ ├── breakout/ ├── cartpole/ └── pong/ ``` 这两个文件由 `.gitignore` 排除，属于本地证据而非源码：它们每次运行都会变，提交进去会让记录里的 `diff_identifier` 在策略代码毫无改动时也发生变化。`results//` 目录本身仍由 `.gitkeep` 保留在版本控制中。 记录包含种子、每局得分、环境步数、耗时、Git revision 和工作区差异标识。Pong 如果到达步数上限仍未结束，按下界 `-21` 计分，避免策略靠拖延比赛得到中性分数。`timed_out` 字段对两个 backend 语义一致：被步数上限截断即为 timeout，声明了 `timeout_score` 的任务此时用下界计分。 种子分为三组： | Split | 种子区间 | 用途 | | --- | ---: | --- | | `dev` | `0..999` | 日常开发和调参 | | `holdout` | `1000..1999` | 阶段性验证 | | `audit` | `2000` 起 | 最终证据 | 不要在 holdout 或 audit 上搜索参数，也不要挑选表现好看的种子。理论分数上限和历史失败记录都属于评估协议，不能为提高指标而修改。 ## 🧪 开发与测试 ```bash uv run isort src tests uv run black src tests uv run pytest ``` 策略实现集中在 `src/heuristic_learning/tasks/`，通用环境适配、指标和 ledger 分别位于 `environments.py`、`registry.py` 与 `ledger.py`。新增任务时，同时添加 task module、测试、结果目录，以及在 task module 里声明 `ACTION_MEANINGS`（registry 与策略都从这里取值）。 ## 🌿 分支约定 `master` 保存所有任务的共同基线。远程 Run 使用 `runs//` 这类短命分支，评审后合并或挑选提交，然后删除分支。这样既能练习建分支与提交，又不会积累长期漂移的 task branches。