# 示例：Web 服务器 / API

服务器区别性关注点是**生命周期**：代理需要在后台启动服务器、验证它已启动、与之交互，然后干净地关闭它。一个阻塞 shell 的前台 `npm start` 对代理毫无用处。

## 应遵循的结构

一个好的服务器运行技能有：

1. **前置条件和设置** — 与任何项目相同。
2. **运行** — 后台启动模式（如下），不是一个阻塞命令。
3. **验证** — 一个 `curl` 或类似命令，确认服务器确实已启动。
4. **停止** — 如何干净地终止后台进程。

如果后台启动 + 就绪轮询 + 冒烟 curl 序列超过几行，将其放入技能目录中的 `smoke.sh`，并在 `SKILL.md` 中说"运行冒烟脚本"。一个命令，退出码告诉你服务器是否健康。

## 后台启动模式

不要写：

> ```bash
> npm start
> ```

那是阻塞的。改为展示如何在后台启动、等待就绪以及稍后找到 PID：

> ```bash
> npm start &> /tmp/server.log &
> SERVER_PID=$!
>
> # 等待服务器启动（根据需要调整超时/端口）
> for i in {1..30}; do
>   curl -sf http://localhost:3000/health > /dev/null && break
>   sleep 1
> done
> ```

然后验证步骤：

> ```bash
> curl http://localhost:3000/health
> # → {"status":"ok"}
> ```

以及停止：

> ```bash
> kill $SERVER_PID
> # 或者，如果丢失了 PID：
> pkill -f "node.*server.js"
> ```

## 值得记录的细节

- **哪个端口。** 明确说明，并说明如何覆盖它（`PORT=4000 npm start`）。
- **"就绪"的表现形式。** 指示就绪的特定日志行，或要访问的健康端点。
- **必需的环境变量。** 数据库 URL、API 密钥等——如果列表很长，附带一个 `.env` 模板。
- **热重载 vs 生产模式。** 如果它们在意义上有区别，说明每种模式在什么时候使用。
- **依赖的服务。** 如果服务器需要 Redis/Postgres 等，要么指出一个 docker-compose 来启动它们，要么直接包含 `docker run` 命令。

## 示例片段

以下是典型 Node API 的运行部分可能的样子：

> ## 运行
>
> 在后台启动开发服务器：
>
> ```bash
> npm run dev &> /tmp/api.log &
> ```
>
> 服务器在 3000 端口监听。等待它就绪，然后验证：
>
> ```bash
> for i in {1..20}; do
>   curl -sf http://localhost:3000/health && break
>   sleep 0.5
> done
> curl http://localhost:3000/health
> # → {"status":"ok","version":"1.2.3"}
> ```
>
> 日志在 `/tmp/api.log`。使用以下命令停止：
>
> ```bash
> pkill -f "tsx watch src/index.ts"
> ```
>
> ### 环境
>
> | 变量 | 必需 | 默认值 | 注释 |
> |---|---|---|---|
> | `DATABASE_URL` | 是 | — | Postgres 连接字符串 |
> | `PORT` | 否 | `3000` | |
> | `LOG_LEVEL` | 否 | `info` | `debug` / `info` / `warn` / `error` |
