Geedl

---
name: geedl
description: Use when a Google Earth Engine task needs a neural network or per-pixel uncertainty — 在 GEE 上做预测/回归/分类而自带的 smileRandomForest / smileGradientTreeBoost / libsvm 不够用时，尤其是用户要【逐像元不确定性 σ】（随机森林无论如何给不出）。也用于把 Python 训好的模型权重搬进 GEE 做前向传播、MLP/1D 卷积推理出图、GEDI 生物量或冠层高度这类稀疏标签建模。流程是 GEE 出数据 → Python 学模型 → 权重搬回 GEE → JS 出图，带两道机器判定的门禁。仅支持 Windows。
---

# GeeDL · 在 GEE 上跑神经网络，并证明跑的是你训练的那个模型

**存在理由：GEE 有 PB 级影像和无限像元并行，但一个神经网络都跑不了**
（只有 RF、SVM 那几个，没有梯度、没有反向传播）。Python 反过来。

```
GEE 出数据  →  Python 学模型  →  权重搬回 GEE  →  JS 前向传播出图
```

难的不是接，是**证明接对了**。所以一半的代码是检查。

---

## ★ 先判断：这个活该不该用 GeeDL

**大多数 GEE 任务不该用。** 用错了就是拿大炮打蚊子，还多两道门禁要过。

| 用户要什么 | 用什么 |
|---|---|
| 写个 NDVI/RSEI/LST 脚本、调通某个 GEE 报错 | **geelo skill**，不是这个 |
| 分类/回归，精度够用就行 | GEE 自带 `smileRandomForest`，不用这个 |
| **逐像元不确定性 σ** | ★ **GeeDL** —— RF 无论如何给不出 |
| 已有 Python 训好的小模型，要搬上 GEE 出图 | ★ **GeeDL** |
| 稀疏点标签（GEDI/ICESat/通量塔/样地）建模 | ★ **GeeDL**（它的取样和检查是为这个设计的）|
| 1D 卷积（时间轴=波段轴）、LSTM 等非全连接结构 | ★ **GeeDL** —— 能做，见下面的能力表 |

**判据一句话：需要 σ，或者需要 RF 给不了的模型结构 —— 否则别用。**
**别对用户说「CNN / LSTM 做不了」**，那是错的。硬边界只有两条：
GEE 上不能训练，以及参数规模（2D 卷积 / U-Net 会爆）。

`训练` 步骤会强制跑岭回归和随机森林做基线。**MLP 打不过它们时，
唯一站得住的理由是「我要 σ」。** 连 σ 都不需要就老实回去用 `smileRandomForest`。

---

## 工具在哪

**`<GeeDL>` = 本文件所在目录的上两级**（本文件是 `<GeeDL>/skills/geedl/SKILL.md`）。

- **Claude Code**：可以直接用 `${CLAUDE_PLUGIN_ROOT}`
- **Codex / 其他**：`${CLAUDE_PLUGIN_ROOT}` **不会展开**，先算成绝对路径再执行
- **直接 clone 的**：`<GeeDL>` 就是仓库根目录

**不要问用户路径**，你自己能算出来。

---

## 第一步：自检

```bash
cd /d "<工作目录>" && python "<GeeDL>/run.py" 自检
```

九项逐条报。按结果处理：

| 结果 | 你怎么做 |
|---|---|
| 全部 `OK` | **直接开工，别汇报"我检查了环境"** |
| 缺 Python 模块 | `pip install -r "<GeeDL>/requirements.txt"` |
| **没找到 GeeLo** | 跑 `node "<GeeDL>/装GeeLo.js"`，它自己 clone + npm install |
| GeeLo 依赖没装 | 按自检打印的那条 `npm install` 跑 |
| **EE 项目 ID 没配** | 跑 GeeLo 的 `认证.js`，见下 |

### 项目 ID 没配 —— 一条命令解决

```bash
node "<GeeLo>/测试台/认证.js"
```

自动开浏览器 → 用户点「允许」→ 凭据写好 → 自动 `setx EE_PROJECT`。
**不需要用户复制任何东西。** 多个项目时用 `--project=<ID>` 指定。

★ 认证完提醒用户：`EE_PROJECT` 是 `setx` 写的，**当前终端读不到**。
后续命令要么新开终端，要么临时带上 `EE_PROJECT=<id>`（bash）/
`$env:EE_PROJECT='<id>';`（PowerShell）。

★ **绝对不要让用户把 `credentials` 内容贴给你**，也不要自己读它、打印它。

---

## 只有一个入口

```bash
python run.py 自检        换电脑第一件事
python run.py 取数        GEE 取样 + 记特征指纹
python run.py 训练        训练 + 空间分块CV + 基线对照
python run.py 导权重      导权重 + 组装 GEE 脚本
python run.py 传asset     权重传成 EE asset
python run.py 门禁        ★ 机器判定通过与否
python run.py 出图        门禁没过会直接拒绝执行
python run.py 全部        上面一整串
python run.py 新建 "D:\某目录"   在别处开一条新管线
```

参数原样透传：`python run.py 取数 --year 2022 --roi 100.8 23.9 101.6 24.7`、
`python run.py 训练 --hidden 64 32`、`python run.py 出图 --自包含`。

**没有 `01_取数.py` 那种编号脚本。** 全部走 `run.py`。

---

## ★ 五条铁律

### 1. 两道门禁都过了才许出图

| 门禁 | 验什么 | **验不了什么** |
|---|---|---|
| 一致性（`门禁`）| 同样输入 → GEE 和 Python 同样输出 | **输入本身对不对** |
| **特征指纹**（`出图` 检查一）| 两边特征栈算出同样的值 | 模型权重对不对 |

**缺一不可。** 特征栈在 `场景/<name>.py` 和 `场景/<name>.js` 里各写了一遍。

实测：只把 JS 侧一个云量阈值从 40 改成 60 ——

```
特征指纹    [0,0,0,0,0,0] → [0.21, 0.20, 0.079, 0.31, 0.023, 0.10]   ★抓住
高度均值    21.897        → 21.788        看不出
一致性门禁  全绿          → 全绿          抓不住
```

一致性门禁是**机器判定**：`05` 末尾打印 `GATE_RESULT PASS/FAIL`，
`run.py` 解析它，FAIL 就非零退出、`出图` 被挡。

**不要用 `--跳过门禁`。**

### 2. 「跑通」不等于「对」

GEE 是惰性计算，零报错也可能全错。**已实测到的静默故障**
（跑通、无报错、无告警、图照出，但结果错）：

| 故障 | 后果 |
|---|---|
| 稀疏标签上随机撒点 | 只采到 **21** 个样本，相关系数符号全反 |
| 漏 `sort('idx')` | 预测出 **4380 米**高的树冠 |
| 特征定义漂移 | 地图只变 1%，全无感 |
| 多场景时选错数据集 | 配置写 A，**静默训练了 B**，还输出漂亮结果 |
| 照抄别的产品的质量过滤 | `predictor_limit_flag` 恒为 255，`eq(0)` 把 **25228→0** |

所以交付前一定要再问：**这些数字讲得通吗？量级对吗？符号对吗？**

### 3. 基线对照不许跳过，输了要照实说

`训练` 会强制跑岭回归和 RF，用**空间分块** CV（不是随机划分，
遥感数据有空间自相关，随机划分 R² 会虚高）。
**MLP 没赢就照实报，别粉饰**，也别拿随机划分那个数去邀功。
报喜不报忧是这套东西最该防的失败模式。

### 4. 改场景改两个文件，改完从 `取数` 重跑

`场景/<name>.py` 和 `场景/<name>.js`，两边特征栈逐行对应。`引擎/` 别动。

### 5. 省配额：先小后大

Debug 阶段先拿一小块 ROI、一年、少量样本。通了再放大。

---

## 换研究对象：改三处

复制 `场景/_新场景模板.py` 和 `.js`，把 `配置.txt` 的 `scene` 改成新名字：

1. **`build_stack()` / `buildFeatures()`** —— 特征栈 + 标签（**两边都改**）
2. **`sample()`** —— 标签稠密就直接采；标签**稀疏**（GEDI/ICESat/通量塔/样地）
   **必须两段式**，否则静默只拿到几十个样本
3. **`sanity()` 和 `CAVEAT`** —— 领域常识检查 + 已知系统性偏差。**千万别省**：
   `CAVEAT` 写不出来说明你还没搞清楚这个标签有什么毛病，那才是最危险的状态

### ★ 换标签源必须先探针看质量标记的实际取值

**不要照抄别的产品的过滤条件。** 逐条单独施加、各看存活量，再定用哪几个。

---

## GEE 能做到什么（实测，非推测）

| | |
|---|---|
| 全连接 MLP、任意深度 | ✅ `matrixMultiply` 逐像元真矩阵乘 |
| ReLU/sigmoid/tanh/softplus/softmax | ✅ 与 numpy 逐位对齐 |
| 1D 卷积（时间轴 = 波段轴）| ✅ |
| LSTM / GRU（时间步展开）| ✅ 用 `iterate()` 展开 |
| 2D 卷积 / U-Net | ⚠️ 受**参数规模**限制，不是不能写；通道一多就超预算 |
| **训练 / 反向传播** | ❌ **绝无可能** —— 这就是要 Python 那一半的全部理由 |

**甜点区：5 万参数以内。** 实测 250×200 矩阵乘 6.5 秒。

---

## 别污染用户的文件夹

- 探针、临时脚本 → **临时目录**
- `产物/` 是全部输出，删掉不影响代码；**别手改 `产物/脚本/`**，那是每次 `导权重` 重新生成的
- `<GeeDL>` 里的东西**别改**，那是插件本体。要在别处干活就 `run.py 新建`

报告要给证据：说"跑通了"就附实跑输出和关键数值；跑不通就说跑不通。

---

## 要更多细节时读这些

| 什么时候 | 读哪份 |
|---|---|
| 完整规矩、目录地图 | `<GeeDL>/AGENTS.md` |
| 为什么这么设计、边界在哪、五个静默故障的细节 | `<GeeDL>/文档/设计文档.md` 第 3、5、6 节 |
| 写普通 GEE 脚本（不涉及神经网络）| **geelo skill** |

**别一上来全读**，按需取。

---

## 环境事实

- Windows + Python 3.8+（`numpy` `pandas` `scikit-learn` `earthengine-api`，
  **不需要 torch / tensorflow**）+ Node.js 20.19+
- 前置依赖 **GeeLo**，提供实跑测试台。`配置.txt` 的 `geelo = auto` 会自己找
- PowerShell 5.1 里 `&&` 不可用，用 `;` 或 `if ($?) { ... }`
- 中文 Windows 控制台是 GBK，`✓` 这类字符会让 print 抛 `UnicodeEncodeError`。
  `引擎/配置.py` 已兜底，但**加新 print 时别用花哨符号**
- 凭据在 `%USERPROFILE%\.config\earthengine\credentials`，**不在仓库里** ——
  克隆或分享本仓库不会泄露任何人的账号