git:20260904.86d066f to git:20260905.1418735

# GeeLo —— 给 AI 助手的说明（权威版）

> **这一份是所有 AI 工具的唯一权威说明。**

> `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` 都只是指回这里的桩，

> 不要在那几份里找内容，也不要往那几份里写内容。

>

> 读到这份文件的 AI：**不需要再问"要不要先了解一下项目"，看完这一页你就知道全部了。**

> 用户接下来提的多半是"帮我写个 XX 的 GEE 脚本"，你按下面的铁律直接开工。

**这个目录是工具，不是工作区。** 别把成果、临时脚本、探针写进来。

---

## GeeLo 是什么

一个跑在本地的 GEE 开发闭环：**AI 写 GEE 脚本 → 自己在本机连真服务器跑 → 看服务端返回

什么 → 自己改 → 再跑**，调通了再交付。

它解决的是一个具体问题：AI 写 GEE 代码的水平早就够用了，问题出在**它写完之后不知道

自己写得对不对**——而波段名、集合是不是空的、归约器要几个输入，这些只有真连服务器

才知道。

---

## 两个功能

| | 功能 | 谁在用 | 干什么 |

|---|---|---|---|

| **1** | `测试台\` | **AI（你）** | 把 GEE 的 JavaScript **原样**在本机跑，真连 Earth Engine 服务器。用来**自己调 bug**，而不是把没验证的代码丢给用户 |

| **2** | `送进编辑器\` | **AI + 用户** | 把脚本推进用户的 EE 脚本仓库并用 Chrome 打开 Code Editor。**可选功能**，用户不一定装了 |

功能一是核心，天天在用。功能二配一次就不用管，**而且用户可能根本没装**——

用之前先确认 `送进编辑器\配置.json` 存在，不存在就别用，直接把脚本路径交给用户。

---

## ★ 铁律（这几条是这套工具存在的全部理由）

### 1. 写完 GEE 脚本，必须实跑验证后再交付

```

node "<GeeLo>\测试台\跑GEE.js" --timeout 900 "<脚本绝对路径>"

```

**不许只做静态审读就说"应该没问题"。** 波段名写错、集合是空的、归约器参数个数不对

——这些静态看一律看不出来，`node --check` 全过，只有真连服务器才暴露。

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

GEE 是**惰性计算**：`print` / `Map.addLayer` / `Export` 才触发真算。三个推论：

- **语法检查毫无用处**

- **报错的行号往往不是有 bug 的行**（错误统一在 `print` 那一刻爆出来）

- **零报错也可能全错**。必须再看一层：数值合不合理、量级对不对、符号对不对

> 真事：一次 RSEI 脚本「✓ 跑通，无报错无告警」，但 PC1 四个载荷全是正号——

> 物理上不可能（NDVI 与 NDBSI 实测相关 −0.93）。根因是

> `ee.Reducer.centeredCovariance()` **不替你减均值**。

> **所以交付前一定要问自己：这些数字讲得通吗？**

完整案例在 `示例脚本\RSEI_哨兵2_厦门岛.js` 的文件头，值得读一遍。

### 3. 不确定就写探针问服务器，不要猜

能连服务器之后，"我记得应该是……"一律改成三行探针实测。比查文档快，也比记忆可靠。

波段名、reducer 返回几个波段、行政区在数据集里叫什么，全都这么定。

```js

print('A) 双波段 kendallsCorrelation() ：', 集合.reduce(ee.Reducer.kendallsCorrelation()).bandNames());

print('B) 双波段 kendallsCorrelation(2) ：', 集合.reduce(ee.Reducer.kendallsCorrelation(2)).bandNames());

```

探针脚本写到**临时目录**，不要留在用户的文件夹里。

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

GEE 的算力不是白来的。**Debug 阶段一律先小规模跑通再放大**：

先拿一小块区域、先测一个时间段、先看几个样本；逻辑没问题了再逐步放大。

每次都直接怼整个研究区，一轮 Debug 十几次，成本高得吓人。

### 5. 不要污染用户的文件夹

- 临时脚本、探针、中间产物 → 你的临时目录

- 成果脚本 → 当前工作区，**一个成果一个文件**

- GeeLo 目录本身（`测试台\`、`送进编辑器\`）**别乱改**，那是稳定的工具

### 6. 写 `.bat` 的唯一正确姿势

**纯 ASCII 内容 + `chcp 65001 >nul` + 所有中文交给 Node 输出。**

理由（都踩过）：cmd 按当前代码页解析 .bat 的字节，.bat 里出现中文文件名换个代码页就崩；

Node 输出 UTF-8，而 Explorer 起的控制台是 cp936，不 `chcp` 中文全是乱码。

文件名可以是中文（`%~dp0` 是运行时展开的），**内容不行**。

### 7. 报告要给证据

说"跑通了"必须附上实跑输出。跑不通就说跑不通，别粉饰。

### 8. 调通之后，**你自己**把它送进 Code Editor（仅当功能二已配置）

```

:: 中间迭代：只推送，不弹浏览器（否则每改一版弹一个标签页，很烦）

node "<GeeLo>\送进编辑器\gee-open.js" "<脚本.js>" --no-browser

:: ★ 最终版：真开浏览器，让用户直接看到结果

node "<GeeLo>\送进编辑器\gee-open.js" "<脚本.js>"

```

**规矩（五条，都要遵守）：**

1. **先确认功能二装了**（`送进编辑器\配置.json` 存在）。没装就别推，把脚本路径交给用户。

2. **必须先在测试台跑通、并且数值检查通过**，才允许推送。

顺畅的流程最容易让人跳过判断——铁律 2 依然有效：**跑通不等于对**。

3. **迭代中一律加 `--no-browser`**，只有最终那一次才真开浏览器。

4. **一个成果只推最终版一次。** 推送会在用户的 EE 仓库造提交，

写五版推五次就是五个提交，很脏。

5. **推完要在回复里明说**「已推送到 `<仓库>`，标签页已在你的 Chrome 里打开」，

不要悄悄做掉。用户要知道他的账号被写入了什么。

★ 右键菜单**继续保留**——用户自己改完脚本随手右键的场景依然存在，

这条只是**多加一条路径**，不是替代。

---

## ★ 用户还没配好？你带着他装（三步，全在你能力范围内）

**第一件事永远是先跑自检**，它会逐项告诉你缺什么：

```

node "<GeeLo>\测试台\环境自检.js"

```

自检有九项，按它报出来的 `[失败]` 逐条处理。三种最常见的失败：

### ① 「@google/earthengine 没装」

依赖不进版本库（约 104 MB），克隆下来必须装一次：

```

cd /d "<GeeLo>\测试台"

npm install

```

装不上多半是 npm 要走代理：`npm config set proxy http://127.0.0.1:<端口>`。

### ② 「凭据文件不存在」

这一步**你替用户跑不了**（要开浏览器登录 Google），必须让他自己在命令行敲：

```

pip install earthengine-api

earthengine authenticate

```

登完会在 `%USERPROFILE%\.config\earthengine\credentials` 留下 `refresh_token`。

**之后再也不需要 Python。**

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

你只需要知道"这个文件在不在"，`fs.existsSync` 就够了。

### ③ 「项目 ID 还是占位符」

发布版 `测试台\配置.txt` 里写的是 `ee-your-project-id`，**必须换成用户自己的**。

问用户要，或者告诉他去哪看：`code.earthengine.google.com` 右上角的项目选择器，

或 Assets 面板里 `projects/<这里就是>/assets/…`。拿到之后你可以直接替他改：

```

项目ID = 他给你的那个

```

★ `配置.txt` 是 **GBK 编码**的，改的时候别把它整个重写成 UTF-8——

虽然解析器两种都认（键名判据只看 ASCII 的 `ID` 两个字母），但别人再用记事本

打开就会看到乱码。只改那一行的值最安全。

★ 也可以不改文件，用环境变量临时覆盖：`set EE_PROJECT=<项目ID>`。

### 全部通过之后，跑一次演示确认真的通了

```

node "<GeeLo>\测试台\跑GEE.js" "<GeeLo>\测试台\示例\演示_这就是CodeEditor的JS.js"

```

看到 `✓ 跑通，无报错无告警` 就可以开工了。

（功能二「送进编辑器」的配置见 `送进编辑器\说明.md` 第八节。

它要用户自己去网页上生成一次 git 凭据，**同样不要让他把凭据贴给你**。）

---

## 常用命令

把 `<GeeLo>` 换成本仓库的实际绝对路径。

（如果你是在别的文件夹里干活，那个文件夹的 `AGENTS.md` 里写着绝对路径。）

```

:: 跑一个脚本（默认超时 300 秒，重的脚本给 900）

node "<GeeLo>\测试台\跑GEE.js" --timeout 900 "<脚本.js>"

:: 跑整个目录

node "<GeeLo>\测试台\跑GEE.js" --all "<目录>"

:: 环境有问题时先自检（它会逐项告诉你缺什么、怎么补）

node "<GeeLo>\测试台\环境自检.js"

:: 在别的文件夹开一个 GEE 工作区（生成那边的 AGENTS.md / CLAUDE.md）

node "<GeeLo>\new-workspace.js" "D:\某个项目文件夹"

```

退出码：`0` 全部无报错 / `1` 有脚本报错 / `2` 启动阶段就失败（依赖、Node 版本、凭据、网络）。

测试台的安全边界：`Export.*` **只校验参数不真导出**（不烧配额、不写用户的 Drive/Asset）；

脚本在 `vm` 沙箱里跑，拿不到 `require` / `process`；全程只读。

---

## 目录地图

```

GeeLo\ ← 工具（稳定，别乱改）

├ README.md 给人看的总入口：装什么、怎么用

├ AGENTS.md 你正在读的这页（★ 所有 AI 的权威说明）

├ CLAUDE.md / GEMINI.md / .github/copilot-instructions.md

│ 各家 AI 的入口桩，内容都指回 AGENTS.md

├ new-workspace.js / 新建工作区.bat ★ 在别的文件夹开工作区

├ 测试台\ 功能一（AI 用，核心）

│ ├ 说明.md 用法、能查出什么、踩过的坑

│ ├ 原理.txt 为什么本机能跑 GEE（接手必读）

│ ├ 跑GEE.js 主程序

│ ├ 配置.txt ★ 换电脑通常只改这里的项目 ID

│ ├ 环境自检.bat / 安装.bat

│ └ 示例\ 一个正常的、一个故意写错的

├ 送进编辑器\ 功能二（可选）

│ └ 说明.md 设计、方案对比、踩过的坑、换电脑清单

├ 示例脚本\ 一个完整的 RSEI 成果脚本（含两个"跑通但结果错"的记录）

└ 文档\设计笔记_上下文注入.md 这套「AI 自动懂背景」怎么设计的

```

---

## 深入文档（需要时再读，别一上来全看）

| 什么时候读 | 读哪份 |

|---|---|

| 测试台报错看不懂 / 想知道它能查出什么 | `测试台\说明.md` |

| 换电脑调不通 / 要把工具交接给别人 | `测试台\原理.txt` |

| 右键功能出问题 / 换账号 / 凭据泄露要换 | `送进编辑器\说明.md`（凭据维护见八之二） |

| 要把这套「AI 自动懂背景」的做法搬到别的项目 | `文档\设计笔记_上下文注入.md` |

---

## 环境事实

- **Windows + Node.js 20.19 以上**（推荐 22 LTS 或更高）。依赖 `https-proxy-agent@9`

是纯 ESM 包，老版本 Node 用 `require()` 加载会报 `ERR_REQUIRE_ESM`。

- **PowerShell 5.1 里 `&&` 不可用**，用 `;` 或 `if ($?) { ... }`。

- **代理**：测试台会自己找一条能通 Google 的路（配置.txt → 环境变量 → 直连 → 扫常见端口），

一般不用管。功能二不自己探测，复用 `git config --global http.proxy`。

- **EE 项目 ID** 在 `测试台\配置.txt`。发布版里是占位符 `ee-your-project-id`，

用户没改的话自检第 4 项会明确报出来。

- **凭据不在这个仓库里**：

EE 凭据在 `%USERPROFILE%\.config\earthengine\credentials`，

git 凭据在 `%USERPROFILE%\.gitcookies`。

这是刻意的设计——拷贝或分享本目录不会泄露账号。

**绝对不要把这两个文件的内容打印出来、贴进对话或写进任何文件。**