chore: organize repository build entry points and workflow docs

Makefile

@@ -1,10 +1,41 @@
-all: slime slime-cuda
+CXX ?= g++
+NVCC ?= nvcc
+CXXFLAGS ?= -O3 -std=c++17
+NVCCFLAGS ?= -O3 -std=c++17
 
+# Keep the original default build compatible; use `make bench` for the current CLI.
+.PHONY: all legacy bench research show tools test test-gpu clean help
+all: legacy
+legacy: slime slime-cuda
 slime: slime.cpp
-	g++ -o slime slime.cpp -O3 -std=c++17
+	$(CXX) $(CXXFLAGS) $< -o $@
-
 slime-cuda: slime.cu
-	nvcc -o slime-cuda slime.cu -O3 -std=c++17
+	$(NVCC) $(NVCCFLAGS) $< -o $@
-
+bench:
+	$(MAKE) -C bench
+research:
+	$(MAKE) -C research
+show:
+	$(MAKE) -C show
+tools:
+	$(MAKE) -C tools
+test:
+	$(MAKE) -C bench test
+test-gpu:
+	$(MAKE) -C bench test-gpu
 clean:
-	rm -f slime slime-cuda
+	rm -f slime slime-cuda sliming
+	$(MAKE) -C bench clean
+	$(MAKE) -C research clean
+	$(MAKE) -C codex clean
+	$(MAKE) -C show clean
+	$(MAKE) -C tools clean
+help:
+	@echo 'make bench        Build the current CUDA benchmark CLI'
+	@echo 'make test         Run CLI host-side checks (nvcc required, GPU not required)'
+	@echo 'make test-gpu     Run CLI GPU integration checks'
+	@echo 'make legacy       Build the original CPU/CUDA brute-force programs (default)'
+	@echo 'make research     Build research prototypes'
+	@echo 'make show         Build teaching examples'
+	@echo 'make tools        Build the single-chunk checker'
+	@echo 'make clean        Remove compiled outputs; retain reports and datasets'

README.md

@@ -0,0 +1,55 @@
+# 史莱姆区块搜索与 CUDA 基准
+
+当前可直接使用的入口是 **[bench/slime-bench](bench/README.md)**：指定中心区块、曼哈顿半径和实心 `n×n` 图案，测量全部有效种子的普通候选分支搜索时间，支持单张或多张 NVIDIA GPU。
+
+```sh
+make bench
+./bench/bin/slime-bench --x 0 --z 0 --radius 512 --size 5 \
+  --position-batch 128 --devices all --repeat 3
+```
+
+H100 编译：`make -C bench -B CUDA_ARCH=90`。需要 CUDA Toolkit 和 C++17 编译器。普通分支不包含拒绝重抽补扫，不能将它的结果声明为严格完整目录；参数和计时口径见 [CLI 使用说明](bench/README.md)。
+
+## 目录导航
+
+| 路径 | 用途 |
+|---|---|
+| [`bench/`](bench/README.md) | 当前 CLI、测试、已保存的本机计时样例 |
+| [`include/`](include/README.md) | CLI 与研究代码共用的算法实现 |
+| [`research/`](research/README.md) | 求解原型、算法实验、正确性验证和测量报告 |
+| [`research/experiments/`](research/experiments/README.md) | 最近的完整覆盖、成组筛选和调度实验 |
+| [`show/`](show/README.md) | 分步骤教学代码、博客/视频稿及 Manim 工程 |
+| [`codex/`](codex/README.md) | 早期 CPU/CUDA 对照实现及脚本 |
+| [`exp/`](exp/README.md) | 独立 SMT 逆向搜索探索 |
+| [`tools/`](tools/README.md) | 单区块检查小工具与历史汇编参考 |
+| `slime.cpp`、`slime.cu` | 最初的暴力扫描实现，保留原入口 |
+
+研究现状见 [优化汇总](research/OPTIMIZATION_SUMMARY.md)。历史报告是当次源码与硬件下的记录，不应自动视为当前 CLI 性能。
+
+## 常用命令
+
+```sh
+make help       # 查看构建入口
+make bench      # 当前 CLI
+make test       # CLI 范围/数学/参数检查：需要 nvcc，不需要 GPU
+make test-gpu   # CLI GPU 集成验证
+make legacy     # 最初 CPU/CUDA 程序；单独 make 仍保持这个行为
+make tools      # 单区块检查工具
+```
+
+`make research` 和 `make show` 构建相应研究/教学程序。`make clean` 只清理各入口的编译产物，不删除实验数据或报告。
+
+## 哪些文件应进入 Git
+
+- 保留源代码、构建脚本、文档、依赖锁文件，以及报告引用的基准 JSON/JSONL 和确定性输入数据；部分复现脚本直接读取这些文件。
+- 忽略可执行文件、对象文件、`bin/`、虚拟环境、Python 缓存、渲染输出、临时日志和本机配置。
+- 临时跑分或个人导出可放在根目录 `artifacts/`，整个目录已忽略。不要把 `.gitignore` 扩大成忽略全部 JSON/TXT/汇编，否则会漏掉复现材料。
+
+```sh
+mkdir -p artifacts
+./bench/bin/slime-bench --radius 64 --size 5 --output artifacts/local.json
+```
+
+历史研究和教学跑分脚本部分会直接更新各自的 `results/` 与报告，运行它们后出现 Git 修改是预期行为；日常机器测速请使用上述 CLI 和 `artifacts/`。将新结果作为正式基准保存时，应连同硬件、命令、源码版本和结论一起审核提交。
+
+旧研究头文件路径保留为兼容转发；修改算法时请修改 `include/slime/` 中的实现。旧报告里的源文件哈希保留原测量值，后续运行的实验脚本会额外记录新共用头文件的哈希。