# GOGO 项目中心 · HTML 进度文件部署指引（面向 AI 智能体）

> **阅读对象：AI 智能体（Agent）。**
> 本文件说明如何把你在别的对话 / 工具里生成的 HTML 进度文件，实时上传或更新到站点
> **https://project.gogo198.icu** 的指定文件夹下，并安全地完成部署与验证。
>
> - 在线最新版：**https://project.gogo198.icu/AI-DEPLOY-GUIDE.md**（可直接 WebFetch 读取）
> - 本文件已随站点部署，与本地源 `project\www\AI-DEPLOY-GUIDE.md` 保持同步
> - 指引版本：**v2.2（2026-09-20）** · 站点已上线，域名与区域均已配置完成
> - 🔴 **v2.2 新增 §2.1（务必先读）**：本站是**多项目共享**站点，而部署是**整站覆盖** ——
>   **每次部署前必须先全量下行同步线上 `files/`**，否则会把其他项目的看板清成 404（见 §2.1）
> - 已按「全新目录冷启动」实测：建文件夹 + 上传 HTML + 部署 + 更新，全链路通过（见 §5.1）

---

## 0. 一分钟速查卡（TL;DR）

```
【部署源根目录】  ⚠️ **不是固定路径！** 先按 §0.1 定位。
                  本机常见位置：C:\Users\A\WorkBuddy\<会话时间戳目录>\project\www
                  找不到 / 会话目录变了 → 按 §2.0 从线上 bootstrap 重建（3 条命令）
【关键锚点文件】  <根目录>\.edgeone\project.json  ← 新建目录时**必须**先建它（见 §2.0）
【HTML 放哪里】   <根目录>\files\<小写英文短名>.html
【清单文件】      <根目录>\manifest.json      ← 新增/改名/改标题必须动这里
【缓存版本号】    <根目录>\index.html  →  var VERSION = 'YYYYMMDDx';
【部署命令】      MCP deploy_folder
                    projectName     = "gogo-project"     ← 必须完全一致
                    projectType     = "static"
                    builtFolderPath = workspacePath = 上面的根目录
【部署后验证】    curl -s https://project.gogo198.icu/manifest.json
【分享链接用】    https://project.gogo198.icu/files/<文件名>.html   ← **正式域名**
                  预设域 gogo-project-nih5tlm0.edgeone.dev 需带 eo_token、且中国大陆访问 401，
                  **不要**用它做分享链接
【正式域名】      https://project.gogo198.icu          （已生效，HTTPS 可用）
【加速区域】      全球可用区（不含中国大陆）= overseas  【免备案 · 建后不可改】
【项目 ID】       makers-tuzwtoopzx6d
```

### 铁律四条（违反任何一条，用户都看不到你的更新）

1. **每次部署必须 bump `VERSION`** —— EdgeOne 有 CDN 缓存，不换版本号用户刷到的是旧页面。**这是最高频故障。**
2. **HTML 必须自包含** —— CSS/JS 内联，不引用本地相对路径的图片或样式文件。
3. **文件名只用小写英文 + 数字 + 连字符** —— 中文名、空格、大写都可能导致访问异常。
4. 🔴 **多项目共享本站：部署前必须全量下行同步线上 `files/`** —— 部署是**整站覆盖**，
   本地缺的文件部署后会**当场 404**（会把别的项目的看板清掉）。做法见 **§2.1**。
   **这是最容易被漏、后果最严重的一条。**

### 0.1 先定位部署源目录（**第一步，别跳过**）

本指引**不保证**部署源在哪个路径——它随会话目录变化。按下述顺序定位：

**方法 A · 按关键文件搜（最可靠）**

```bash
# 找含 gogo-project 的 .edgeone/project.json，其上级目录就是部署源根
find /c/Users/A/WorkBuddy -name project.json -path '*/.edgeone/*' 2>/dev/null
# 或直接搜已上传的看板文件
find /c/Users/A/WorkBuddy -name 'gocontent-progress.html' 2>/dev/null
```

**方法 B · Python 定位（推荐，自动判定）**

```python
import os, json
ROOT = r'C:\Users\A\WorkBuddy'
for dirpath, dirnames, filenames in os.walk(ROOT):
    pj = os.path.join(dirpath, '.edgeone', 'project.json')
    if os.path.isfile(pj):
        try:
            if json.load(open(pj, encoding='utf-8')).get('Name') == 'gogo-project':
                print('部署源根目录 =', os.path.dirname(pj[:-len('/.edgeone/project.json')]))
        except Exception:
            pass
```

**方法 C · 都不存在** → 说明本机还没有部署源，按 §2.0 从线上 bootstrap 新建。

> ❗ **不要用当前会话的 cwd 直接当部署源**。WorkBuddy 每次会话会新建时间戳目录，
> 直接在新目录里部署且没有 `.edgeone/project.json` 时，CLI **可能新建项目**（见 §6 禁止事项 1）。

---

## 1. 站点现状（2026-09-20 已配置完成，实测通过）

本项目已经建好并绑定域名，**你不需要再做任何平台侧配置**，只需按第 4 节 SOP 推文件。

### 1.1 平台配置实测记录

| 项目 | 值 | 状态 |
|---|---|---|
| 平台 | 腾讯云 EdgeOne Pages（Makers）· **中国站** | — |
| 项目名 | `gogo-project` | 运行中 |
| 项目 ID | `makers-tuzwtoopzx6d` | — |
| **加速区域** | **全球可用区（不含中国大陆）** · API 值 `overseas` | ✅ 免备案 |
| 自定义域名 | `project.gogo198.icu` | ✅ **已生效** |
| 域名 CNAME 目标 | `project.gogo198.icu.pages.dnsoe5.com` | ✅ DNS 已解析 |
| 预设域名 | `gogo-project-nih5tlm0.edgeone.dev` | ✅ 已生效 |
| HTTPS 证书 | 控制台可能显示「申请中配置」并带蓝点 | ⚠️ 见下方说明 |
| 关联环境 | 生产 | — |
| 部署类型 | static（纯静态） | — |

> **关于 HTTPS「申请中配置」**：这是控制台的状态显示滞后，**实测证书已签发且校验通过**
> （`curl -sI https://project.gogo198.icu/` → HTTP 200，`ssl_verify_result=0`）。
> 若你遇到证书告警，等待几分钟后重试即可，**不要去改动或删除域名绑定**。

> ⚠️ **别被 MCP 返回值里的 `region` 字段误导（2026-09-20 实测）**：
> `deploy_folder` 成功后返回的 `"region": "global"` / `"regionLabel": "国际站 (Global)"` **不是项目的真实加速区域**，
> 只是工具的默认标签。经 Pages API 实测，`gogo-project` 的真实 `Area` 为 **`overseas`**。
> **判断区域请以控制台「项目概览 → 加速区域」或 Pages API 的 `Area` 字段为准**，不要据此字段去"修正"项目。
>
> 可用下列命令自助复核（返回 `"Area":"overseas"` 即正确）：

```bash
curl -s -X POST "https://pages-api.cloud.tencent.com/v1" \
  -H "Authorization: Bearer <你的 Pages API Token>" -H "Content-Type: application/json" \
  -d '{"Action":"DescribePagesProjects","Limit":50,"Offset":0}' | head -c 400
```

> 补充：CLI 部署时输出的 `Deploying ... (Production environment, global area)` **同样是误标**，
> 只要它同时输出 `Using Project ID: makers-tuzwtoopzx6d` 就是正确复用，不必理会 area 字样。

### 1.2 线上实测基线（2026-09-20 18:44，可作为你验证时的对照）

| 路径 | HTTP | 字节数 | 说明 |
|---|---|---|---|
| `/`（首页外壳） | 200 | 11805 | 固定基准 |
| `/manifest.json` | 200 | 321 | 随清单条目增减而变 |
| `/files/gocontent-progress.html` | 200 | 22009 | 固定基准 |
| `/AI-DEPLOY-GUIDE.md`（本文件） | 200 | 17825 | **随版本迭代变化，不必比对** |

四条全 200 = 站点健康。若某条不是 200，先排查是否路径写错或文件名大小写不符。

### 1.3 加速区域为什么必须保持 `overseas`（重要背景）

- `global` = 全球可用区（**含中国大陆**）→ 自定义域名**必须完成工信部备案**才能绑定，否则绑不上；
- `overseas` = 全球可用区（**不含中国大陆**）→ **免备案**，可直接绑定自定义域名；
- **加速区域一经创建不可修改，只能删项目重建**，且重建会换项目 ID 与预设域名。

> ⚠️ **实战教训（2026-09-20）**：MCP `deploy_folder` 在项目**不存在时会自动新建**，
> 而自动新建的项目区域默认是 `global`（需备案），曾导致域名一度绑不上。
> 本项目当时已通过「删除项目 + 以 `Area="overseas"` 重建」纠正为 `overseas`。
>
> **因此：`projectName` 必须严格写 `gogo-project`。** 拼错 = 静默新建一个需备案的新项目。

---

## 2. 站点结构（务必先理解）

本站是「**SPA 外壳 + manifest 清单 + 平铺 HTML 文件**」结构：

```
project/www/
├── index.html          ← 站点首页（外壳）。日常只改里面的 var VERSION，勿重写结构
├── manifest.json       ← 目录清单：决定左侧栏显示哪些文件夹 / 文件
├── AI-DEPLOY-GUIDE.md  ← 本指引（勿删，其他 AI 靠它自助部署）
└── files/              ← 所有进度 HTML 都放这里，平铺存放
    └── gocontent-progress.html
```

工作方式：

1. 首页 `index.html` 启动时 `fetch('manifest.json?v=' + VERSION)`；
2. 按清单渲染左侧目录树（文件夹 → 文件）；
3. 点击条目 → 右侧 iframe 加载对应 HTML（`src` 也会追加 `?v=VERSION`）；
4. 每个文件都有**独立分享链接**：`https://project.gogo198.icu/files/<文件名>.html`。

> 📌 **「文件夹」是虚拟的（重要）**
> `manifest.json` 里的 `folders[]` 只是侧栏的**分组显示**，服务器上**不需要也不应该**建真实子目录。
> 所有 HTML **一律平铺**放在 `files/` 下。
> → 所谓「创建文件夹」= 在 `manifest.json` 的 `folders` 数组里**追加一个对象**，**仅此一步**，
>   不需要 `mkdir`，也不需要部署时传目录结构。

---

## 2.0 首次使用：本机没有部署源时，从线上 bootstrap

如果你（AI）所在机器上找不到部署源目录（见 §0.1 方法 C），**直接从线上重建**即可，
只需 4 条命令，之后就能正常走 SOP。

```bash
export PATH=/usr/bin:/bin:$PATH
D="<你想放部署源的目录>"          # 例如 C:/Users/A/WorkBuddy/<会话目录>/project/www
mkdir -p "$D/files" "$D/.edgeone"

# ① 拉外壳 + 清单 + 已有文件
curl -o "$D/index.html"                       https://project.gogo198.icu/index.html
curl -o "$D/manifest.json"                    https://project.gogo198.icu/manifest.json
# ⚠️ 下面这一条只是「示例」，不是全部！bootstrap 之后必须按 §2.1 做一次
#    「全量下行同步」把 files/ 补齐，否则部署时会把其他项目的看板清成 404
curl -o "$D/files/gocontent-progress.html"     https://project.gogo198.icu/files/gocontent-progress.html

# ② 建立项目锚点（❗缺了这步，CLI 可能新建项目）
printf '%s' '{"Name":"gogo-project","ProjectId":"makers-tuzwtoopzx6d"}' > "$D/.edgeone/project.json"
```

> ❗ **`.edgeone/project.json` 是 CLI 关联项目的锚点**，内容必须是：
> ```json
> {"Name":"gogo-project","ProjectId":"makers-tuzwtoopzx6d"}
> ```
> 有它时 CLI 会输出 `Project gogo-project already exists. Using existing project.`
> 和 `Using Project ID: makers-tuzwtoopzx6d` —— **看到这两行就说明没走新建分支，域名绑定安全**。
> 若输出里出现「Creating project」，**立刻中止**并核对 project.json。

bootstrap 完成后，**先做 §2.1 的全量下行同步**，再回到 §4 的 SOP 正常操作。

---

## 2.1 🔴 多项目共享本站：部署前必须全量下行同步（2026-09-20 新增）

**本站是多个项目共用一个站点**：每个项目在侧栏各占一个虚拟文件夹（GoContent / Gochat / 词元出海 …），
所有 HTML 都平铺在同一个 `files/` 目录下（见 §2）。

而 **EdgeOne Pages 的部署是「整站覆盖」**：部署完成后，**站点内容 = 你本地部署源目录的内容**。

> ❗ **最危险的误解**：以为「我只要上传我自己那一份 HTML 就行」。
> 实际上你推的是**整个目录** —— **本地 `files/` 里没有的文件，部署后线上立刻 404**。
> 若你按 §2.0 从线上 bootstrap 只拉了 1 份示例文件就部署，**会把其他项目的看板全部清掉**，
> 而部署命令本身不会报任何错。

### 因此：任何一次部署之前，先把本地 `files/` 补齐到与线上一致

```python
import json, os, urllib.request
BASE = "https://project.gogo198.icu"
ROOT = r"<DEPLOY_ROOT>"                     # 换成 §0.1 定位到的部署源根目录
m = json.load(urllib.request.urlopen(BASE + "/manifest.json"))
for f in m.get("folders", []):
    for it in f.get("files", []):
        p = it["path"]
        dst = os.path.join(ROOT, p.replace("/", os.sep))
        os.makedirs(os.path.dirname(dst), exist_ok=True)
        data = urllib.request.urlopen(BASE + "/" + p).read()
        open(dst, "wb").write(data)
        print(len(data), p)
```

等价的 bash 写法（有 `jq` 时）：

```bash
export PATH=/usr/bin:/bin:$PATH
D="<DEPLOY_ROOT>"; mkdir -p "$D/files"
for p in $(curl -s https://project.gogo198.icu/manifest.json \
           | python -c "import sys,json;m=json.load(sys.stdin);[print(i['path']) for f in m.get('folders',[]) for i in f.get('files',[])]"); do
  curl -o "$D/$p" "https://project.gogo198.icu/$p"
done
```

### 两道反证（缺一不算完成）

| 时机 | 反证 | 通过标准 |
|---|---|---|
| **部署前** | 本地 `files/` 的 HTML 数量 vs 线上 `manifest.json` 的 `files[].path` 条目数 | **相等**（外加你待新增的那一条） |
| **部署后** | 抽查访问**至少一个别的项目**的看板 URL | 仍返回 **200**（证明没清掉别人的文件） |

### 命名也要防冲突（多项目并存）

新建文件夹 / 文件前，**先拉一次线上 `manifest.json` 查重**：

- `path` 撞车 → 换你的 `FILE_SLUG`（例：`gochat-progress` 已存在 → 用 `gochat-main-progress`）；
- folder 名已存在 → 在它的 `files[]` 里**追加条目**，**不要**新建同名 folder；
- 更新已有页面 → **同名覆盖**，永不改名（改名 = 用户收藏的链接失效）。

---

## 3. manifest.json 规范

UTF-8 编码，必须是**合法 JSON**（不能有中文引号、末尾多余逗号）。

```json
{
  "title": "GOGO 项目中心 · 进度看板",
  "updated": "2026-09-20",
  "folders": [
    {
      "name": "GoContent",
      "desc": "内容管理 SaaS 平台（content.gogo198.net）",
      "files": [
        {
          "title": "GoContent V3 · 项目总进度看板",
          "path": "files/gocontent-progress.html",
          "updated": "2026-09-20",
          "status": "进行中"
        }
      ]
    }
  ]
}
```

| 字段 | 必填 | 说明 |
|---|---|---|
| `folders[].name` | ✅ | 文件夹名（= 项目名），如 `GoContent`、`Gochat`、`词元出海` |
| `folders[].desc` | ❌ | 一句话说明，显示在文件夹名下方 |
| `files[].title` | ✅ | 侧栏显示标题（中文可读），如「GoContent V3 · 项目总进度看板」 |
| `files[].path` | ✅ | 相对路径，**必须以 `files/` 开头** |
| `files[].updated` | ❌ | 更新日期 `YYYY-MM-DD`，显示在条目右侧 |
| `files[].status` | ❌ | 状态标签：含「进行/开发/迭代」→ 黄色；含「完成/上线」→ 紫色；含「正常」→ 绿色 |

改完**必须校验合法性**：

```bash
python -c "import json;json.load(open(r'C:\Users\A\WorkBuddy\2026-08-31-15-43-52\project\www\manifest.json',encoding='utf-8'));print('JSON OK')"
```

---

## 4. 标准操作流程（SOP · 六步）

> 🔴 **第 0 步（隐藏前置，最容易漏）**：若本机部署源是新建的（bootstrap），
> 或距上次部署已隔了一段时间 —— 先按 **§2.1** 做一次「全量下行同步」再往下走。
> 本站是**多项目共享**站点，部署是**整站覆盖**：本地缺文件 = 把别人的看板清成 404。

### 步骤 1 · 准备 HTML 文件

- 编码 **UTF-8**，含 `<meta charset="UTF-8">`；
- **自包含**：CSS 写在 `<style>`、JS 写在 `<script>` 内；
  **不要引用本地相对路径资源**（`./img/a.png`、`style.css`）——服务器上只有你上传的那一个文件，引用本地资源必然裂图。
  必须用图时，引 `https://` 公网图片，或把图片转成 base64 data-URI 内联；
- 建议在页面顶部或页脚标注「最后更新：YYYY-MM-DD HH:mm」，方便用户判断新鲜度；
- 建议同时兼容手机（加 `<meta name="viewport" content="width=device-width, initial-scale=1.0">`），因为文件会被 iframe 嵌入且用户常手机上查看。

### 步骤 2 · 命名并放入 `files/`

命名规则：**小写英文字母 + 数字 + 连字符 `-`**，语义化、无空格、无中文。

| 场景 | 文件名示例 |
|---|---|
| 项目总看板 | `files/gocontent-progress.html` |
| 某项目第 3 次周报 | `files/gocontent-weekly-03.html` |
| 某模块进度 | `files/gochat-payment-progress.html` |

```bash
# 覆盖更新时同路径覆盖即可（分享链接保持不变）
cp "<你的生成路径>/xxx.html" \
   "C:/Users/A/WorkBuddy/2026-08-31-15-43-52/project/www/files/<小写英文短名>.html"
```

> Windows 沙箱下 `cp` 可能被 `-i` 别名拦截，改用 `\cp -f` 或先 `export PATH=/usr/bin:/bin:$PATH`。

### 步骤 3 · 更新 manifest.json

- **3a 更新已有文件**（路径没变）：只把该条目 `updated` 改成今天，`status` / `title` 按需调整；
- **3b 新增文件到已有文件夹**：在对应 `folders[].files` 数组里追加一个对象；
- **3c 新增文件夹**（新项目）：

```json
{
  "name": "Gochat",
  "desc": "境外 IM 桥接应用",
  "files": [
    {"title": "Gochat 开发进度看板", "path": "files/gochat-progress.html", "updated": "2026-09-20", "status": "进行中"}
  ]
}
```

同时把根节点 `"updated"` 也改成今天。改完跑第 3 节的 JSON 校验命令。

### 步骤 4 · bump 缓存版本号（**不做这步用户看不到更新**）

编辑 `project/www/index.html`，找到（约第 111 行）：

```javascript
var VERSION = 'YYYYMMDDx';   // 例：2026-09-20 当日第 4 次部署 → 20260920d
```

> 以文件里那一行的**当前实际值**为基准，把它改成一个**比它更大 / 不同**的值即可。

规则：`YYYYMMDD` + 当日序号字母（同日第 1 次 `a`、第 2 次 `b`……）。
例：2026-09-20 的第 4 次部署 → `20260920d`。**必须与上一次不同。**

> ⚠️ 用 Edit 工具改完，**务必回读一遍确认落盘**（历史上出现过"提示成功但内容未写入"的情况）。

### 步骤 5 · 部署

**方式 A · MCP 工具（首选）**

```
工具：mcp__edgeone-pages__deploy_folder
参数：
  builtFolderPath : C:\Users\A\WorkBuddy\2026-08-31-15-43-52\project\www
  workspacePath   : C:\Users\A\WorkBuddy\2026-08-31-15-43-52\project\www
  projectType     : static
  projectName     : gogo-project        ← 必须完全一致
```

**方式 B · EdgeOne CLI（无 MCP 连接器时的备选）**

```bash
export PATH=/usr/bin:/bin:$PATH
cd "C:/Users/A/WorkBuddy/2026-08-31-15-43-52/project/www"
edgeone makers deploy . -n gogo-project --json
```

> - 本机 `~/.edgeone/` 已存有 CLI 登录凭证，通常**无需再传 Token**、也不会交互式提示。
> - ⚠️ **若目录是新建的（bootstrap）**：先确认 `.edgeone/project.json` 存在且内容正确（见 §2.0），
>   再执行 deploy，并**盯住输出**：必须出现 `Project gogo-project already exists` + `Using Project ID: makers-tuzwtoopzx6d`。
> - 成功标志：`{"status":"success", "projectId":"makers-tuzwtoopzx6d", ...}`；
>   projectId 必须是这个值，换成别的 ID 就说明建错项目了。
> - CLI 的 `-a / --area`（`global` / `overseas`）**只在新建项目时生效**；项目已存在时按名字复用，区域保持不变。本项目区域已固定为 `overseas`，**正常部署不要带 `-a`**。
> - 部署成功以 CLI 输出 `Status: Success` 为准；**不要**只凭「命令没报错」就宣布成功。

### 步骤 6 · 验证（必做，三重校验）

```bash
export PATH=/usr/bin:/bin:$PATH
V=<你刚写入的新 VERSION>

# ① 清单是否更新（应能看到你的新条目）
curl -s "https://project.gogo198.icu/manifest.json?v=$V"

# ② 文件是否可访问（HTTP 200，且字节数与本地文件一致）
curl -s -w "HTTP=%{http_code} size=%{size_download}\n" -o /tmp/_p.bin \
  "https://project.gogo198.icu/files/<小写英文短名>.html?v=$V"
ls -l "C:/Users/A/WorkBuddy/2026-08-31-15-43-52/project/www/files/<小写英文短名>.html"

# ③ 首页是否可访问
curl -s -w "HTTP=%{http_code} size=%{size_download}\n" -o /tmp/_p.bin \
  "https://project.gogo198.icu/?v=$V"
```

**判定标准**：三条全 200，且 ② 的线上字节数 == 本地字节数，② 的 manifest 含你的新条目 = **部署成功**。

> 数字对不上就是没部署成功，不要向用户交付"应该好了"这类结论。

---

## 5. 常见场景对照表

| 你要做的事 | 操作要点 |
|---|---|
| 🔴 **每次部署前的固定动作** | 先按 **§2.1 全量下行同步**线上 `files/`（多项目共享站点，部署是整站覆盖）→ 再走下面的场景 |
| **新项目首次上传进度页** | 选/建文件夹（先拉 manifest 查重）→ 存 `files/xxx.html` → manifest 加条目 → bump VERSION → 部署 → 验证（含**抽查别的项目仍 200**） |
| **更新已上传的进度页** | 覆盖同名文件（路径不变 → **分享链接不变**）→ 改 `updated` → bump VERSION → 部署 |
| **同一项目多份文件**（周报 / 模块） | 同一 folder 的 `files` 数组追加多条，共用文件夹 |
| **删除某个看板** | manifest 里删该条目（HTML 文件可留可删）→ bump VERSION → 部署 |
| **改文件夹名** | 改 `folders[].name` → bump VERSION → 部署（`path` 不变则分享链接不变） |
| **改文件显示标题** | 只改 `files[].title`（中文可读）→ bump VERSION → 部署（链接依旧不变） |

> **核心原则：只要 `path` 不变，分享链接就永远不变。**
> 更新一律走「同名覆盖」，**不要**为每次更新另起新文件名——否则对方收藏的链接就失效了。

---

### 5.1 端到端自检记录（2026-09-20 实测，可放心照做）

用一个**全新空目录**完整演练了一遍，全部通过：

| 演练项 | 结果 |
|---|---|
| 从线上 bootstrap 部署源（4 条命令） | ✅ 拉到 index.html 11805B / manifest.json 321B / 看板 22009B |
| 新建目录 + `.edgeone/project.json` 后部署 | ✅ CLI 输出 `Project gogo-project already exists`，projectId `makers-tuzwtoopzx6d`，**未新建项目** |
| **创建文件夹**（manifest 追加 folders 对象） | ✅ 线上侧栏立即出现新分组 |
| **上传 HTML** 到该文件夹 | ✅ `files/selftest-check.html` 线上 908B，与本地逐字节一致 |
| 分享链接可访问 | ✅ `https://project.gogo198.icu/files/<文件名>.html` 返回 200 |
| 后续更新（同名覆盖 + bump VERSION） | ✅ 走 §5 对照表，链接不变 |

> 演练用的临时文件夹已于验证后移除，说明「建 / 删 / 改」也都可控。

---

## 6. 禁止事项（都是踩过的坑）

1. **不要部署 `project/www` 以外的目录**，**不要改 `projectName`**。
   写成别的名字 = 静默新建一个 `global` 区域项目 = 需备案、域名绑不上、且无法改区只能重建。
2. **不要忘记 bump `VERSION`** —— 最高频故障，表现为「用户说没变化，但其实部署成功了」。
3. **不要引用本地相对路径资源** —— 上传后不存在，页面裂图 / 样式丢失。
4. **不要在 manifest 里写非法 JSON**（中文引号、末尾逗号）—— 整站侧栏会显示「加载 manifest.json 失败」。
5. **不要删除 `AI-DEPLOY-GUIDE.md`** —— 后续其他 AI 依赖它自助部署。
6. **不要改动 `index.html` 的结构与样式** —— 除非用户明确要求改站点外观；日常只改 `var VERSION`。
7. **不要动域名绑定 / 加速区域 / HTTPS 配置** —— 已配置完成且实测正常（见 1.1）。控制台显示「申请中配置」属正常滞后，**不要去删了重建**。
8. **不要在本文件里写入任何密钥**（API Token、SMTP 授权码、密码）—— 本文件是**公网可读**的（`https://project.gogo198.icu/AI-DEPLOY-GUIDE.md`）。
9. 🔴 **不要在只含自己一份 HTML 的部署源里直接部署**（2026-09-20 新增）—— 本站**多项目共享**且部署是**整站覆盖**，本地缺的文件部署后会当场 404，等于**清掉其他项目的看板**，而命令不会报任何错。**每次部署前按 §2.1 全量下行同步**，并在部署后抽查别的项目看板仍返回 200。

---

## 7. 同账号关联站点（**务必不要串站**）

同一个腾讯云账号下共有 **3 个** EdgeOne Pages 项目。**每个站的部署源目录完全不同，请勿交叉部署**：

| 站点 | 域名 | 项目名 | 项目 ID | 区域 | 本地部署源 | 用途 |
|---|---|---|---|---|---|---|---|
| **GOGO 项目中心**（本文件） | `project.gogo198.icu` | `gogo-project` | `makers-tuzwtoopzx6d` | overseas | `…\2026-08-31-15-43-52\project\www` | 各项目进度看板汇总 |
| Gogo 云端知识库 | `kb.gogo198.icu` | `gogo-kb` | `makers-q8qrpmccei0x` | overseas | `…\2026-08-31-15-43-52\kb\www` | 资料 / 文档类 HTML 知识库 |
| 翘秀家风 | `qiaoxiu.gogo198.icu`、`www.gogo198.icu` | `qiaoxiu-jiafeng-global` | `makers-yh7as3c7j6vr` | overseas | `…\2026-08-31-15-43-52\qiaoxiu\dist` | 家族站（含 fullstack 云函数） |

三者**同属 overseas 免备案区**，这是本账号的统一约定。

> **判断该推哪个站**：进度看板 / 项目周报 → 本站（project）。
> 资料文档 / 攻略 / 路书 / 分析报告 → 知识库（kb）。
> 家族内容 → 翘秀（qiaoxiu）。

---

## 8. 进阶：什么时候需要云函数（后端能力）

本站在 `static` 模式下**纯前端、无后端**。若需求超出静态范围（如接收表单提交、发邮件、存数据、鉴权），
需要改为 **fullstack** 部署并新增 `cloud-functions/` 目录。同账号的翘秀家风站已有成熟实现，**实战经验如下（直接复用，少踩坑）**：

| 需求 | 做法 |
|---|---|
| 目录结构 | `www/cloud-functions/<路由>/index.js`，导出 `export async function onRequestPost(context)` |
| 读环境变量 | `context.env.XXX` |
| 持久化存储 | `@edgeone/pages-blob` 的 `getStore({name, consistency:"strong"})`（**必须 `strong`**，否则刚写入读不到） |
| 发邮件 | `nodemailer` + QQ 邮箱 SMTP（授权码，非登录密码），运行环境 Node v20 |
| 依赖声明 | 每个云函数目录内单独放 `package.json` 声明依赖 |

**已踩过的三个坑：**

1. **CLI `env set` 写的环境变量不一定进运行时**（实测读到空值）→ 关键凭据要有**代码内兜底常量**，并在文档里说明轮换方式。
2. **`Response.redirect()` 传相对路径在 Makers 上会 500** → 改用手动设置 `302` + `Location` 响应头。
3. **防刷/限流**要自己实现（如按 IP 计数、60 秒 5 次 → 超限返回 429），平台不提供现成能力。

> 本项目当前**不需要**改 fullstack。除非用户明确要求加后端，否则保持 `projectType: "static"`。

---

## 9. 兜底：如果你（AI）没有部署能力

若当前环境既无 MCP 连接器、也无 `edgeone` CLI、或网络不通：

1. 正常生成 HTML，保存到 `C:\Users\A\WorkBuddy\2026-08-31-15-43-52\project\www\files\<小写英文短名>.html`；
2. 按第 3 节改好 `manifest.json`，按第 4 步 bump `VERSION`；
3. **在回复里明确告诉用户**：「文件已就位，等待部署」，并列出你准备的 `title` / `path` / `updated`；
4. 由用户或另一个具备部署能力的会话执行步骤 5–6。

**不要**在未部署成功的情况下声称"已上线"。

---

## 10. 元信息

| 项 | 值 |
|---|---|
| 正式域名 | https://project.gogo198.icu |
| 平台 | 腾讯云 EdgeOne Pages（Makers）· 中国站 |
| 项目名 | `gogo-project` |
| 项目 ID | `makers-tuzwtoopzx6d` |
| 加速区域 | **全球可用区（不含中国大陆）** · API 值 `overseas` · **免备案** |
| 自定义域名 | `project.gogo198.icu`（已生效） |
| CNAME 目标 | `project.gogo198.icu.pages.dnsoe5.com` |
| 预设域名 | `gogo-project-nih5tlm0.edgeone.dev`（中国大陆网络直连返回 401 属正常，自定义域名不受此限） |
| 部署类型 | static（纯静态） |
| 本地部署源 | `C:\Users\A\WorkBuddy\2026-08-31-15-43-52\project\www` |
| 清单文件 | `manifest.json` |
| 控制台入口 | https://console.cloud.tencent.com/edgeone/makers |
| 指引版本 | **v2.2**（2026-09-20）· 上一版 v2.1 |
| 🔴 多项目共享约束 | 本站为**多项目共用**；部署是**整站覆盖** → **每次部署前必须全量下行同步线上 `files/`**（见 §2.1，铁律第 4 条 / 禁止事项第 9 条） |
| 端到端自检 | 2026-09-20 全新目录演练：建文件夹 + 上传 HTML + 部署 + 更新，全链路通过 |

---

*本指引随站点部署，可由任何 AI 通过 `https://project.gogo198.icu/AI-DEPLOY-GUIDE.md` 自助读取。*
*修订本文件后，请同步更新第 10 节的版本号并重新部署。*