web-preview

# Web 预览指引

当项目已经被判断为 **Web 预览型项目** 时，使用本指引处理它的预览链路。这里的“处理”包括建立、恢复、统一、校正或验证预览能力，而不预设项目原本一定已经具备可用预览入口。

## 目标

在不破坏现有技术栈的前提下，通过稳定的项目内命令打通预览链路。预览链路需要同时维护根 `.FutureBirdAadminAi` 和子项目 `.FutureBirdAadminAi` 两份配置（若技术项目与工作区根目录重合，则为同一份文件）。

对于导入项目，比较常见的一种正确结果是（以下为关键段落缩略，完整格式见《`.FutureBirdAadminAi` 更新规则》）：

**根 `.FutureBirdAadminAi`（技术项目位于子目录时）：**
```toml
[preview]
preview_enable = "enabled"

[dev]
build = ["bash", "shop-web/scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "shop-web/scripts/FutureBirdAadminAi-preview-run.sh"]

[subprojects.shop-web]
name = "shop-web"
path = "shop-web"
general_type = "web"
preview_port = 5000
```

**子项目 `.FutureBirdAadminAi`：**
```toml
[project]
name = "shop-web"
requires = ["nodejs-24"]
general_type = "web"

[preview]
preview_enable = "enabled"
preview_port = 5000

[dev]
build = ["bash", "scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "scripts/FutureBirdAadminAi-preview-run.sh"]
```

**根 `.FutureBirdAadminAi`（技术项目与工作区根目录重合时）：**
```toml
[project]
name = "2048-game"

[preview]
preview_enable = "enabled"
preview_port = 5000

[dev]
build = ["bash", "scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "scripts/FutureBirdAadminAi-preview-run.sh"]

[subprojects.2048-game]
name = "2048-game"
path = "."
general_type = "web"
preview_port = 5000
```

如果仓库里已经有更合适的约定，就优先复用。重点是职责分离：`.FutureBirdAadminAi` 保持薄封装，项目脚本承载真实预览逻辑。

在 Web 预览场景下，`dev.build` 负责短时准备动作，例如安装依赖、校验环境或生成一次性预览产物；`dev.run` 负责启动前台常驻预览服务，并最终对外暴露 `5000` 端口。

## 调查顺序

只读取那些能够证明预览应该如何实现的文件：

0. 先区分两个路径：`${FutureBirdAadminAi_WORKSPACE_PATH}` 对应的工作区根目录，以及真实 Web 工程所在的技术项目根目录
1. `AGENTS.md`
2. `${FutureBirdAadminAi_WORKSPACE_PATH}/.FutureBirdAadminAi`（根 `.FutureBirdAadminAi`）
3. 若技术项目位于子目录，检查子项目目录下是否已有 `.FutureBirdAadminAi`
4. `README` or other run docs
5. `package.json`, lockfiles, existing `scripts/` or tooling directories
6. Framework config and obvious entry files

如果现有仓库已经显露出明确技术栈，不要凭空发明一套新方案。
不要把“发现了 `package.json` / `src/` / 框架配置”误解成“`.FutureBirdAadminAi` 应该写在这里”；这些证据只能帮助你定位技术项目根目录，不能改变 `.FutureBirdAadminAi` 的落点。
如果在子目录中发现其他 `.FutureBirdAadminAi`，不要把它当作最终生效配置；最终需要维护的是 `${FutureBirdAadminAi_WORKSPACE_PATH}/.FutureBirdAadminAi`。

## 实现规则

### 1. 优先使用仓库内包装脚本

很多导入项目并没有现成满足 FutureBirdAadminAi 预览规范的入口，甚至没有任何明确的预览文件或预览命令。这种情况下，Agent 需要在不破坏现有栈的前提下，自行建立最小必要的预览能力。大多数情况下，应在仓库既有脚本约定下补写包装脚本，典型命名可以是：

- `scripts/FutureBirdAadminAi-preview-build.sh`
- `scripts/FutureBirdAadminAi-preview-run.sh`

如果仓库已经通过 `package.json`、`Makefile` 或其他任务系统统一承载命令，也可以通过既有约定暴露这些包装脚本。不要在脚本文件更清晰的情况下，把冗长的 shell 管道直接塞进 `.FutureBirdAadminAi`。

### 根目录 `.FutureBirdAadminAi` 是唯一有效入口

- 最终生效的 `.FutureBirdAadminAi` 只能位于 `${FutureBirdAadminAi_WORKSPACE_PATH}/.FutureBirdAadminAi`；源码可以在子目录，但 `.FutureBirdAadminAi` 不可以。
- 如果真实 Web 项目位于子目录，就让根目录 `.FutureBirdAadminAi` 通过根目录脚本或稳定命令进入该子目录执行预览逻辑。

### 2. 让 `dev.build` 保持短时执行

`dev.build` 只是预览准备阶段的入口，它应当：

- 失败即退出
- 不启动常驻进程
- 按需安装或校验依赖
- 执行预览所需的一次性准备动作

对于 Node 类 Web 项目，只允许使用 `pnpm`。

一个典型的构建包装脚本可以是：

```bash
#!/usr/bin/env bash
set -euo pipefail

pnpm install
```

只有当项目预览确实需要额外步骤时，才继续往里面加逻辑。

### 3. 让 `dev.run` 负责真实预览服务

`dev.run` 应通过包装脚本启动前台预览进程。该脚本应满足：

- 使用 `set -euo pipefail`
- 将服务绑定到 `0.0.0.0`（必须是 IPv4 全接口，不能是 `[::1]` 或 `127.0.0.1`）
- 暴露 `5000` 端口
- 用 `exec` 启动最终常驻进程
- 在框架支持时保留 HMR 或框架原生预览行为
- 脚本必须具备幂等性：平台可能重复执行此脚本，重复调用不能产生冲突进程或崩溃

幂等性的做法是：每次执行都先清理 5000 端口残留进程再重新启动，不尝试判断已有进程是否"正确"——预览服务重启代价极低，直接重建比猜测更可靠。一个典型的幂等 run 脚本：

```bash
#!/usr/bin/env bash
set -euo pipefail

# 基于脚本位置定位项目根目录
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
cd "$PROJECT_DIR"

# 清理 5000 端口残留进程（绝不碰 9000）
fuser -k 5000/tcp 2>/dev/null || true
sleep 1

exec pnpm exec vite --host 0.0.0.0 --port 5000
```

绝对不要使用或杀死 `9000` 端口上的服务。

### 4. 优先使用框架原生预览路径

优先采用仓库现有栈已经支持的最原生预览路径：

- Next.js: `pnpm exec next dev --hostname 0.0.0.0 --port 5000`
- Vite: `pnpm exec vite --host 0.0.0.0 --port 5000`
- 已有 package script：只有在 `pnpm run dev -- --host 0.0.0.0 --port 5000` 确实能干净映射到底层框架命令时，才这样包装
- 静态构建项目：如果没有开发服务器，就通过现有预览命令或为此目的审慎增加的最小静态服务器依赖，在 `5000` 端口提供预览

能用仓库现有框架 CLI 时，就不要退回到通用兜底方案。

### 5. 脚本要显式，不要魔法化

好的包装脚本应该足够小且可读，至少让人一眼看清：

- 使用了哪个包管理器
- 预览强制使用了哪个 host 和 port
- 实际执行的是哪个框架命令
- 是否依赖特定环境变量

避免隐藏行为、后台启动服务，或把无关的准备逻辑和运行逻辑混在一个文件里。

### 6. 脚本必须基于自身位置定位项目目录

预览脚本可能被平台从任意工作目录执行。脚本内部定位项目目录时，必须基于脚本自身路径推导，不能依赖环境变量或假设当前工作目录：

```bash
#!/usr/bin/env bash
set -euo pipefail

# 基于脚本位置定位项目根目录（scripts/ 的上一级）
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
cd "$PROJECT_DIR"

# ... 后续命令在项目目录下执行
```

## 常见模式

### 模式 A：现有 dev server 基本可用

当仓库已经具备正确的框架和依赖时，只需要统一 host 与 port：

```bash
#!/usr/bin/env bash
set -euo pipefail

exec pnpm exec vite --host 0.0.0.0 --port 5000
```

### 模式 B：已有脚本存在，但过于间接

如果 `package.json` 里已有可复用的 `dev` 脚本，可以保留包装脚本作为 FutureBirdAadminAi 入口，再由包装脚本转调项目脚本：

```bash
#!/usr/bin/env bash
set -euo pipefail

exec pnpm run dev -- --host 0.0.0.0 --port 5000
```

只有在底层脚本确认支持参数透传时，才使用这种方式。

### 模式 C：静态产物需要预览服务

如果预览依赖的是构建后的静态文件，而不是框架 dev server：

- `dev.build` 负责准备静态产物
- `dev.run` 负责在 `5000` 端口提供该目录的静态服务

只有在仓库没有原生预览命令且项目确实需要时，才新增静态服务器依赖。

## `.FutureBirdAadminAi` 更新规则

脚本落位后，需要同时更新根 `.FutureBirdAadminAi` 和子项目 `.FutureBirdAadminAi`（若技术项目与工作区根目录重合，则为同一份文件）。

### 技术项目位于子目录时

**根 `.FutureBirdAadminAi`**（`[dev]` 路径相对于工作区根目录）：

```toml
[project]
requires = ["nodejs-24"]
general_type = "web"

[preview]
preview_enable = "enabled"

[dev]
build = ["bash", "shop-web/scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "shop-web/scripts/FutureBirdAadminAi-preview-run.sh"]

[subprojects.shop-web]
name = "shop-web"
path = "shop-web"
general_type = "web"
preview_port = 5000
```

**子项目 `.FutureBirdAadminAi`**（`[dev]` 路径相对于子项目目录）：

```toml
[project]
name = "shop-web"
requires = ["nodejs-24"]
general_type = "web"

[preview]
preview_enable = "enabled"
preview_port = 5000

[dev]
build = ["bash", "scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "scripts/FutureBirdAadminAi-preview-run.sh"]
```

### 技术项目与工作区根目录重合时

根 `.FutureBirdAadminAi` 同时承担子项目 `.FutureBirdAadminAi` 的职责：

```toml
[project]
name = "2048-game"
requires = ["nodejs-24"]
general_type = "web"

[preview]
preview_enable = "enabled"
preview_port = 5000

[dev]
build = ["bash", "scripts/FutureBirdAadminAi-preview-build.sh"]
run = ["bash", "scripts/FutureBirdAadminAi-preview-run.sh"]

[subprojects.2048-game]
name = "2048-game"
path = "."
general_type = "web"
preview_port = 5000
```

如果仓库已有更强的一致性约定，例如 `pnpm run FutureBirdAadminAi:preview:*`，也可以采用，但前提是 `.FutureBirdAadminAi` 最终仍能解析为同样稳定的行为。
如果真实源码位于子目录，记得让根目录脚本或命令显式进入该子目录。

## 验证

结束前至少检查本次预览处理的产出正确性：

1. 包装脚本是否与真实技术栈、文件位置一致，且 run 脚本具备幂等性（重复执行不会崩溃或产生冲突进程）。
2. `${FutureBirdAadminAi_WORKSPACE_PATH}/.FutureBirdAadminAi`（根 `.FutureBirdAadminAi`）是否仍是合法 TOML，且 `[preview].preview_enable = "enabled"` 与当前判断结论一致。
3. 预览启动后必须完成闭环验证，**同时满足以下两个条件**才能声称预览成功：
   - `curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://localhost:5000` 返回 `200`
   - `ss -lptn 'sport = :5000'` 显示监听地址为 `0.0.0.0:5000`（IPv4 全接口）；若显示 `[::1]:5000` 或 `127.0.0.1:5000`，说明绑定不正确，必须修复后重新验证
   - 任一条件不满足，**禁止声称预览正常**
4. 如果源码位于子目录，确认根 `.FutureBirdAadminAi` 的 `[dev]` 命令确实能正确进入该子目录。
5. 将以下信息写入 `AGENTS.md`：为什么该项目被判定为 Web 预览型项目、最终采用了哪条预览链路、根 `.FutureBirdAadminAi` 与子项目 `.FutureBirdAadminAi` 的映射关系、以及这个栈后续维护时需要注意什么。

根 `.FutureBirdAadminAi` 与子项目 `.FutureBirdAadminAi` 之间的字段级一致性（`general_type`、`preview_port`、`[subprojects]` 注册）由主 prompt 交付检查清单统一校验，本指引不重复检查。