# GeeLo —— 给 AI 助手的说明（权威版） > **这一份是所有 AI 工具的唯一权威说明。** > `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` 都只是指回这里的桩， > 不要在那几份里找内容，也不要往那几份里写内容。 > > `skills/geelo/SKILL.md` 是 Claude Code 插件入口，摘录了铁律 1—4 和常用命令， > **同样以本文件为准**；改了这里的铁律，记得同步那一份。 > > 读到这份文件的 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 "\测试台\跑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 "\送进编辑器\gee-open.js" "<脚本.js>" --no-browser :: ★ 最终版：真开浏览器，让用户直接看到结果 node "\送进编辑器\gee-open.js" "<脚本.js>" ``` **规矩（五条，都要遵守）：** 1. **先确认功能二装了**（`送进编辑器\配置.json` 存在）。没装就别推，把脚本路径交给用户。 2. **必须先在测试台跑通、并且数值检查通过**，才允许推送。 顺畅的流程最容易让人跳过判断——铁律 2 依然有效：**跑通不等于对**。 3. **迭代中一律加 `--no-browser`**，只有最终那一次才真开浏览器。 4. **一个成果只推最终版一次。** 推送会在用户的 EE 仓库造提交， 写五版推五次就是五个提交，很脏。 5. **推完要在回复里明说**「已推送到 `<仓库>`，标签页已在你的 Chrome 里打开」， 不要悄悄做掉。用户要知道他的账号被写入了什么。 ★ 右键菜单**继续保留**——用户自己改完脚本随手右键的场景依然存在， 这条只是**多加一条路径**，不是替代。 --- ## ★ 用户还没配好？你带着他装（三步，全在你能力范围内） **第一件事永远是先跑自检**，它会逐项告诉你缺什么： ``` node "\测试台\环境自检.js" ``` 自检有九项，按它报出来的 `[失败]` 逐条处理。三种最常见的失败： ### ① 「@google/earthengine 没装」 依赖不进版本库（约 104 MB），克隆下来必须装一次： ``` cd /d "\测试台" npm install ``` 装不上多半是 npm 要走代理：`npm config set proxy http://127.0.0.1:<端口>`。 ### ② 「凭据文件不存在」或 ③ 「项目 ID 还是占位符」 这两条**同一条命令解决**，你可以直接跑： ``` node "\测试台\认证.js" ``` 它做三件事：自动开浏览器让用户点「允许」→ 把凭据写进 `%USERPROFILE%\.config\earthengine\credentials` → 列出他的 Cloud 项目并 自动 `setx EE_PROJECT`。 **不需要 Python。** 原来那套 `pip install earthengine-api` + `earthengine authenticate` 已经不需要了——认证.js 用的是同一个公开 client，产出的凭据文件两边完全兼容。 配合要点： - 跑完告诉用户「浏览器已经打开了，选账号点『允许』就行」，**不用他复制任何东西** - 他有多个项目而你不在交互式终端时，认证.js 会**把清单打出来**。 拿给用户选，然后 `node "\测试台\认证.js" --project=<他选的ID>` - `EE_PROJECT` 是 `setx` 写的，**当前终端读不到**，后续命令要新开终端 或临时带上环境变量 - 已有凭据时它拒绝覆盖；换账号 / 凭据失效才加 `--force`（旧的自动备份） ★ **不要让用户把 `credentials` 的内容贴给你**，也不要自己去读它、打印它。 你只需要知道"这个文件在不在"，`fs.existsSync` 就够了。 ★★ **不要去编辑 `测试台\配置.txt`。** 要设项目 ID 就用： ``` node "\测试台\认证.js" --project=<项目ID> ``` 它内部就是 `setx EE_PROJECT`，不碰任何文件。理由（两条都踩过）： 1. `配置.txt` 是 **GBK 编码**。用 PowerShell 按 ANSI 读写去改那一行**会报错**， 改坏了还会把整份文件的中文注释变成乱码。 2. 装成插件时它在插件目录里，`/plugin update` 会把它整个冲掉。 `配置读取.js` 本来就把 `EE_PROJECT` 排在 `配置.txt` 前面，所以环境变量一定赢。 ### 全部通过之后，跑一次演示确认真的通了 ``` node "\测试台\跑GEE.js" "\测试台\示例\演示_这就是CodeEditor的JS.js" ``` 看到 `✓ 跑通，无报错无告警` 就可以开工了。 （功能二「送进编辑器」的配置见 `送进编辑器\说明.md` 第八节。 它要用户自己去网页上生成一次 git 凭据，**同样不要让他把凭据贴给你**。） --- ## 常用命令 把 `` 换成本仓库的实际绝对路径。 （如果你是在别的文件夹里干活，那个文件夹的 `AGENTS.md` 里写着绝对路径。） ``` :: 跑一个脚本（默认超时 300 秒，重的脚本给 900） node "\测试台\跑GEE.js" --timeout 900 "<脚本.js>" :: 跑整个目录 node "\测试台\跑GEE.js" --all "<目录>" :: 环境有问题时先自检（它会逐项告诉你缺什么、怎么补） node "\测试台\环境自检.js" :: 在别的文件夹开一个 GEE 工作区（生成那边的 AGENTS.md / CLAUDE.md） node "\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`。 这是刻意的设计——拷贝或分享本目录不会泄露账号。 **绝对不要把这两个文件的内容打印出来、贴进对话或写进任何文件。**