# 3x3视野贪心资源收集算法使用指南

## 概述

本项目实现了一个基于3x3视野的贪心算法，用于在迷宫环境中收集资源。该算法的核心特点是：

- **视野限制**：每次移动时只考虑当前位置周围3x3范围内的单元格
- **贪心策略**：在可见范围内选择价值最高的资源
- **移动限制**：只能进行上下左右四个方向的移动
- **智能探索**：当视野内没有资源时，会进行探索性移动寻找新资源

## 文件说明

### 主要文件

1. **`greedy_3x3_algorithm.py`** - 独立的3x3视野贪心算法模块
2. **`tanxin.py`** - 原有的贪心算法实现，已集成新的3x3算法
3. **`greedy_resource_collector.py`** - 完整版本的贪心收集器（支持全局搜索）
4. **`strict_3x3_greedy.py`** - 严格的3x3视野算法演示

### 演示文件

- **`greedy_resource_collector.py`** - 包含演示的完整贪心算法
- **`strict_3x3_greedy.py`** - 专门的3x3算法演示

## 使用方法

### 1. 基本使用

```python
from greedy_3x3_algorithm import Greedy3x3Algorithm

# 创建迷宫（二维数组，[y][x]格式）
maze = [
    ['s', '0', 'g5', '1', 't3'],  # s=起点, g5=价值5的金币, 1=墙壁, t3=损失3的陷阱
    ['0', '1', '0', '0', 'g2'],   # 0=可通行路径
    ['g3', '0', '1', 't2', '0'],
    ['0', 't1', '0', '0', 'g4'],
    ['1', '0', 'g1', '0', 'e']    # e=终点
]

# 创建算法实例
algorithm = Greedy3x3Algorithm(maze, debug=True)

# 运行算法
result = algorithm.run()

# 查看结果
print(f"总价值: {result['total_value']}")
print(f"收集资源数量: {result['resources_count']}")
print(f"移动步数: {result['total_moves']}")

# 打印详细结果
algorithm.print_result()
```

### 2. 在现有项目中集成

```python
from tanxin import Greedy3x3ResourceCollector

# 使用现有的迷宫数据
map_data = your_maze_data  # 二维数组格式

# 创建收集器
collector = Greedy3x3ResourceCollector(map_data)

# 运行收集算法
result = collector.run_3x3_greedy_collection()

# 获取兼容格式的路径 (y, x格式)
path_yx = collector.get_path()
total_reward = collector.get_total_reward()
marked_map = collector.add_path_to_map()
```

### 3. 运行演示

```bash
# 运行独立算法演示
python greedy_3x3_algorithm.py

# 运行集成演示
echo "2" | python tanxin.py

# 运行比较演示
python strict_3x3_greedy.py
```

## 算法详解

### 地图元素说明

- **`s`** - 起点 (Start)
- **`e`** - 终点 (End)  
- **`g数字`** - 金币资源，数字表示价值（如 `g5` = 价值5的金币）
- **`t数字`** - 陷阱资源，数字表示损失（如 `t3` = 损失3的陷阱）
- **`0`** - 可通行的路径
- **`1`** - 墙壁，无法通过
- **`l`** - 锁/机关
- **`b`** - Boss

### 算法流程

1. **初始化**：从起点开始，初始化路径和收集状态
2. **视野扫描**：获取当前位置3x3范围内的所有单元格
3. **资源评估**：
   - 优先选择正价值资源（金币）
   - 如果没有正价值资源，选择损失最小的负价值资源（陷阱）
4. **移动决策**：
   - 如果找到资源，移动到该位置并收集
   - 如果没有资源，进行探索性移动到未访问的位置
5. **循环执行**：重复步骤2-4直到满足停止条件

### 停止条件

- 达到最大移动步数（默认1000步）
- 连续多步（默认20步）无法找到新资源
- 无法进行任何移动

## 算法参数

### Greedy3x3Algorithm 参数

```python
algorithm = Greedy3x3Algorithm(
    maze,                    # 必需：迷宫地图
    start_pos=None,         # 可选：起始位置(x,y)，默认自动寻找
    end_pos=None,           # 可选：目标位置(x,y)，默认自动寻找  
    debug=False             # 可选：是否输出调试信息
)

result = algorithm.run(
    max_moves=1000,         # 最大移动步数
    max_stuck=20            # 连续无资源的最大步数
)
```

## 结果格式

算法执行后返回的结果字典包含：

```python
{
    'path': [(x1,y1), (x2,y2), ...],           # 移动路径 (x,y格式)
    'path_yx_format': [(y1,x1), (y2,x2), ...], # 移动路径 (y,x格式，兼容现有代码)
    'collected_resources': [                     # 收集的资源详情
        {
            'position': (x, y),
            'type': 'g5',
            'value': 5
        },
        ...
    ],
    'total_value': 15,                          # 资源总价值
    'total_moves': 25,                          # 总移动步数
    'resources_count': 8,                       # 收集资源数量
    'start_pos': (0, 0),                        # 起始位置
    'end_pos': (4, 4),                          # 目标位置
    'final_pos': (2, 3),                        # 最终位置
    'explored_positions_count': 15,             # 探索位置数量
    'algorithm_name': '3x3视野贪心算法'
}
```

## 性能特点

### 优势

1. **局部最优**：在有限视野内做出最优决策
2. **探索能力**：能够智能探索未知区域
3. **资源优先**：优先收集高价值资源，避免低价值陷阱
4. **防死循环**：具备多种机制防止无限循环

### 限制

1. **视野限制**：可能错过视野外的高价值资源
2. **局部陷阱**：可能陷入局部最优解
3. **路径效率**：为了收集资源，路径可能不是最短的

## 测试用例

项目包含多个测试迷宫：

### 简单测试迷宫

```python
simple_maze = [
    ['s', '0', 'g5', '1', 't3'],
    ['0', '1', '0', '0', 'g2'],
    ['g3', '0', '1', 't2', '0'],
    ['0', 't1', '0', '0', 'g4'],
    ['1', '0', 'g1', '0', 'e']
]
```

### 复杂测试迷宫

```python
complex_maze = [
    ['s', '0', 'g5', '1', 't3', '0', 'g8'],
    ['0', '1', '0', '0', 'g2', '1', '0'],
    ['g3', '0', '1', 't2', '0', '0', 'g6'],
    ['0', 't1', '0', '0', 'g4', '1', '0'],
    ['1', '0', 'g1', '0', '0', '0', 't5'],
    ['0', 'g7', '0', '1', '0', 'g9', '0'],
    ['t4', '0', '0', '0', '1', '0', 'e']
]
```

## 扩展开发

### 自定义评估函数

可以通过继承 `Greedy3x3Algorithm` 类来自定义资源评估逻辑：

```python
class CustomGreedy3x3(Greedy3x3Algorithm):
    def _evaluate_resource_value(self, cell):
        # 自定义评估逻辑
        if cell.startswith('special'):
            return 100  # 特殊资源高价值
        return super()._evaluate_resource_value(cell)
```

### 自定义移动策略

```python
class CustomGreedy3x3(Greedy3x3Algorithm):
    def _find_exploration_target(self):
        # 自定义探索策略
        adjacent = self.get_adjacent_positions(self.current_pos)
        # 选择最靠近终点的位置
        if adjacent:
            return min(adjacent, key=lambda pos: 
                abs(pos[0] - self.end_pos[0]) + abs(pos[1] - self.end_pos[1]))
        return None
```

## 常见问题

### Q: 算法为什么会在某些位置反复移动？

A: 这是因为算法在视野内找不到新资源时，会进行探索性移动。连续20步无资源后会自动停止。

### Q: 如何提高算法的收集效率？

A: 可以调整参数：
- 减小 `max_stuck` 参数，减少无效探索
- 增加迷宫中的资源密度
- 优化迷宫布局，减少死胡同

### Q: 算法支持什么样的迷宫格式？

A: 支持二维列表格式，使用 `[y][x]` 索引方式。单元格内容为字符串。

### Q: 如何集成到现有项目？

A: 可以使用 `tanxin.py` 中的 `Greedy3x3ResourceCollector` 类，它与现有代码兼容。

## 版本信息

- **版本**: 1.0
- **作者**: GitHub Copilot
- **创建日期**: 2025年1月
- **Python版本**: 3.6+
- **依赖**: 无额外依赖，使用Python标准库