---
date: 2026-05-19
tags: [agent-pool, dev-env, slot-staleness, npm-install, schema-drift]
severity: low
status: workflow-recommendation
---

# Slot 池长期不重置时同时撞 schema 漂移 + 依赖陈旧 + Caddy 端口配置

## 现象

slot-3 池上次活跃是 9 天前（`backend/.env` mtime 2026-05-09 13:54），中间 develop 合了 `c5a5c83a feat(robot-manager): v3 28-stage 整体重构（67 commits epic）`。重新 claim 后启动会撞三件事：

1. **schema 漂移**：`db push` 卡在 generated column 类型变更，**只能 `db:reset`**（或手动 drop schema + push）
2. **依赖陈旧**：v3 epic 加了 `@modelcontextprotocol/sdk` 但 slot 的 node_modules 没装，backend 启动报 `Cannot find module '@modelcontextprotocol/sdk/server/mcp.js'`
3. **frontend `$PORT` 不读 .env**：slot 的 `frontend/package.json` 用 `"dev": "next dev -p ${PORT:-3000}"`，但 npm run dev **不会自动加载 .env**，导致 frontend 起在 :3000 而不是 .env 里的 `FRONTEND_PORT=3700`。Caddy 反代 :3700 → 反代空，用户访问 Caddy 域名 404

## 正确的 slot 复用 prep（按顺序）

```bash
# 假设已 claim slot-N，进入它
cd $FFOA_AGENT_DIR/backend

# 1. 装新增依赖（develop 合并新包后必跑）
npm install

# 2. schema 对齐（develop 大改时用 reset，参考 multi-schema reset learning）
npm run db:push:force   # 优先尝试
# 如果撞 generated column / 残留对象：手动 drop schema + push（见相关 learning）

# 3. seed + itadmin
npm run db:seed
npm run init:itadmin

# 4. 起 backend
nohup npm run start:dev > /tmp/slot-N-backend.log 2>&1 &
disown

# 5. 起 frontend（关键：手动 export PORT 覆盖默认 3000）
cd ../frontend
PORT=$FFOA_AGENT_FRONTEND_PORT nohup npm run dev > /tmp/slot-N-frontend.log 2>&1 &
disown
```

或者：

```bash
PORT=3700 npm run dev   # 直接传，比 .env 优先
```

## 关键点

- **`PORT=` 必须显式覆盖**：frontend dev script 是 `next dev -p ${PORT:-3000}`，shell 不读 `.env`，必须 `PORT=... npm run dev`。后端不一样——后端用 `dotenv -e .env -- ...` 在 npm script 里加载 .env，所以后端自动用 `BACKEND_PORT`。
- **频繁 sync 主仓库**：长期搁置的 slot 跟 develop 漂移大，应该定期 `git pull` + `npm install`
- **slot 复用的"温度"决定准备成本**：刚 claim 的热 slot（同周内的） → 仅 `npm install` + `db:push`；冷 slot（> 1 周）→ 全套 reset

## 后续优化想法

- 修 frontend `package.json` 的 dev script 用 `dotenv-cli`：`"dev": "dotenv -e .env -- next dev -p $FRONTEND_PORT -H 0.0.0.0"`（要传非默认 var 名 `$FRONTEND_PORT` 而非 `$PORT`，避免跟 backend 冲突）
- 写 `scripts/dev/agent-pool/agent-warm.sh <slot-N>` 一键做 "npm install + schema 同步 + seed + itadmin"，给冷 slot 复用前跑
- 或在 `agent-claim.sh` 检查 slot 上次活跃时间，> 7 天自动建议 `agent-warm`