> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 氛围编程

# 氛围编程（Vibe Code）

> 氛围编程的标准循环是  说清需求 => AI 生成 => 预览检验 => 精准反馈 => AI 修复，循环推进
> 成败的关键在反馈质量——同一句"加载失败"，给 F12 报错原文的三轮修好，只说"看不见图"的修五遍也没动

不会写提示词也能做出能跑的应用，这是氛围编程（vibe code）的门槛；但要从"能跑"走到"能交付"，靠的是下面这几条反馈纪律。

## 一、反馈的三条纪律

### 1. 报错给原文，不给感受

"看不见图""做的很乱"这类自然语言，AI 无法精准定位；**F12 的错误日志，AI 基本一把过**。反馈时带上报错原文 + 文件行号 + 触发操作（具体模板见[预览排障](https://gisagent.mapgis.com/docs/preview-error.md)）。

配套纪律：**删对话 = 删现场**。有用户反复改不好就"把这个对话删了重新发起"——新对话里 AI 看不到之前生成的代码和改过 5 遍的历史，反而更定位不了，而且删掉的内容连技术支持也找不回来。**不需要删，AI 可以在原对话里自修复**。

### 2. 渐进式、结果驱动，一步一验收

不要一句话要 10 个页面 + 全部交互 + 完美 UI。正确节奏是先让 AI **把地图和管网搞出来**，跑通后再逐层加页面、调细节——每步都有可验收的结果，错了知道错在哪一步。第一轮就要大而全，结果往往是"看着都有、处处是坑"，返工成本远高于渐进式。

### 3. 提示词不行，先让 AI 帮你写提示词

不会写提示词没关系：**把需求先发给 DeepSeek，让它生成结构化提示词，再复制给工作平台的 AI**。把两份回答放在一起对比，反复临摹几次，就摸清了 AI 的"性格"和对话方式——这比背提示词模板有效得多。

## 二、真实踩坑对照

以下每一条都来自实际的氛围编程现场：

| 现象 | 现场还原 | 正确姿势 |
| :- | :- | :- |
| 底图瓦片全挂，报 `ERR_NAME_NOT_RESOLVED` | 提示词里写了 `https://t{0-7}.tianditu.gov.cn/...`，AI 把 `{0-7}` 原样照抄进代码，浏览器真去解析这个域名 | **直接贴一条能打开的完整 URL**（含真实 x/y/z 和 tk），让 AI 反推模板；报错原文一贴，AI 一轮就改成 t0/t1/t2 具体域名列表 |
| 后台"请求了国外的底图"加载不上 | 页面代码里默认 OSM/国外 CDN，内网环境不可达 | 把 F12 **Network** 标签的失败请求发给 AI，明确要求换国内底图 |
| 底图能出图但数据整体偏移几百米 | 数据与底图坐标系不匹配（WGS84/GCJ02/BD09 混用），不是预览 bug | 按[空间参考系](https://gisagent.mapgis.com/docs/spatial-crs.md)的匹配决策表处理，别在预览问题里绕圈 |
| 页面区块"内容都是空的" | 根因藏在代码里：`height: calc(100vh - 320px)` 算出的容器过矮、`App.initMap` 定义了但模块 `return` 里没导出 | 说清**哪个页面哪个区块**+ 附 Console 报错，两类问题 AI 都能一轮定位；只说"是空的"就要来回猜 |
| 改了 5 遍没修好，删对话重来 | 每轮反馈都是"还是不行"级别的感受描述 | 改不好通常不是 AI 无能，是反馈里缺报错原文；补上日志原话即可续修 |
| 反复横跳：画了过滤又撤销、撤销又重做 | "删除不在 DMA 范围内的点位"→ 两分钟后"撤销"→ 又按边界框重做一遍 | 下指令前**先让 AI 报影响面**（"这个操作会改动哪些文件、影响哪些点位？"），确认后再执行，一个来回就省两轮 |
| 数字明显不合理没人发现 | 成果汇报写"管线总长 17,385 km"——实际整个管网约 167 km，单位换算错了两个量级 | AI 的自报数字要抽查量级：13 平方公里城区管网不可能是上万公里；发现后把该行输出贴回对话让 AI 修单位 |

## 三、需求陈述模板

一条合格的首轮需求包含五件事，缺一件就多一轮往返：

```text theme={null}
目标：做一个漏损管控专题图，DMA 分区 + 压力监测 + 漏损定位
数据：用本对话上传的"管网数据1016.rar"，不要自己编管网
底图：天地图，用这条地址的格式（贴完整可用 URL，含 tk）
交互：图层开关、点击查看详情、左侧分区列表点击后飞行定位
验收：打开 index.html 能看到管网叠加在天地图底图上、无 Console 红色报错
```

* **数据口径写死**："管网数据采用本对话中上传的文件"这类指认，能避免 AI 用模拟数据顶替真实数据。
* **验收判据写在需求里**：把"能看到什么算做完"提前说清，AI 交付前会自检，你验收也有依据。
* **tk/token 只留在对话里**：含 token 的 URL 不要写进对外交付的文档、页面或截图。

## 四、过软件工程这道门槛

氛围编程有一个分水岭：**能不能从"自然语言预研"进化到"软件工程"**——需求能拆步、反馈带日志、结果做验收、版本能回退。迈过去，产出就不再是单页面 demo，而是页面之间联动跳转、人机交互完整的系统；迈不过去，就会一直停在"改 5 遍还是不行"的循环里。

判断自己是否已经过线，看三个行为：

1. 反馈里出现的是 `Uncaught TypeError: ... at app.js:147` 而不是"坏了""很乱"；
2. 大需求会主动拆成"先地图管网 → 再十个页面 → 再补空区块"的阶梯；
3. 收到成果会先核一眼数字量级和预览，再进入下一轮。

***

**使用提示：** 每次卡住时先自问——"我把 F12 的原文给 AI 了吗？我是不是该把这一步拆小一点？"这两个动作能解决氛围编程里八成的挫败。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.