# 交付物上报技能 — 运维部署指南

> 本文档写给**运维001**，确保新初始化的数字生命容器能正确上报交付物。
> 读完这篇，你就知道每个新容器启动后该检查什么、配在哪里。

---

## 一、容器初始化检查清单

### □ 1. 确定 AGENT_ID

每台容器需要一个**语义唯一名**，格式：`{主人名}-{角色}`

| 容器 | AGENT_ID 示例 |
|------|--------------|
| 刘雨飏 主容器 | `agent-node` |
| 刘雨飏 雨飏001 容器 | `agent-node-tuye` |
| 芯葶 容器 | `agent-node-xinting` |

**存放位置**（优先级从高到低）：

| 位置 | 命令/文件 | 说明 |
|------|-----------|------|
| 环境变量 | `export FMODE_AGENT_ID=agent-node` | 最优先，重构建容不失 |
| 环境变量 | `export AGENT_ID=agent-node` | 兼容旧脚本 |
| 配置文件 | `~/.fmode/config.json` → `agentId` | 持久化，被 env 覆盖 |
| 项目配置 | `<cwd>/.fmode/config.json` → `agentId` | 项目级覆盖 |

**推荐做法**：`echo 'export FMODE_AGENT_ID=agent-node' >> ~/.bashrc`

> ⚠️ **不要依赖 hostname**。Docker 容器重启后 hostname 变随机 hash（如 `6ec71e98949e`），云函数会判 `404 agent not found`。

### □ 2. 确保 FMODE_SESSION_TOKEN 可被读取

SessionToken 是用户登录后生成的凭据，控制 ACL（**访问权限**）。

**存放位置**：

| 位置 | 文件 | 说明 |
|------|------|------|
| 环境变量 | `FMODE_SESSION_TOKEN` | 最优 |
| 用户配置 | `~/.fmode/config/user.json` → `sessionToken` | Hermes/Fmode Studio 自动维护 |
| 旧配置 | `~/.fmode/config.json` → `sessionToken` | 兼容旧版本 |

**推荐做法**：登录一次 FMODE Studio 后，token 自动写入 user.json。
如 env 缺失，技能会从配置文件兜底读取。

### □ 3. 验证

```bash
# 查看当前容器身份
skill-deliverable check

# 成功输出示例：
# {
#   "agentId": "agent-node",
#   "sessionToken": "r:852951...",
#   "status": "ready",
#   "hostname": "6ec71e98949e"   // 仅显示，不用于上报
# }
```

---

## 二、FmodeStudio 容器生命周期集成

在 `fmode-studio` 的 Docker 部署脚本中，新增：

```bash
# 设置 AGENT_ID
export FMODE_AGENT_ID="agent-$(hostname -s)"  # 或用固定语义名

# 确认 sessionToken 有来源
if [ -z "$FMODE_SESSION_TOKEN" ] && [ -f "$HOME/.fmode/config/user.json" ]; then
  export FMODE_SESSION_TOKEN=$(python3 -c "import json;print(json.load(open('$HOME/.fmode/config/user.json'))['sessionToken'])")
fi

# 运行检查
npx --yes skill-deliverable@latest check
```

---

## 三、容灾：云函数 404/403 怎么办

### 「404 agent not found」
→ FmodeAgent 表里没有这个 agentId 的记录。
- **新容器首次上报时会自动注册**（云函数 v2 特性），等待第一次 report() 即可
- 若等不及，用 master key 手动在 Parse `FmodeAgent` 表创建同名记录

### 「403 only owner or superadmin can report」
→ session 用户不是这个 agent 的 owner。
- 确认该容器的报告人的 session 和该 agent 是否是同一个人
- 云函数 v2 **已移除 superadmin 检查**，只校验 owner（用户=他自己容器的 owner）
- 若 agent 无 owner（旧数据），首次成功上报会自动绑定

---

## 四、常见问题

### Q: 容器重建后上报失败？
A: 重建后 AGENT_ID 丢失 → 重设 env `FMODE_AGENT_ID`。skill-deliverable 已做 hostname 兜底但语义名丢失时 hostname 会变导致 404。**必须持久化 AGENT_ID**。

### Q: 一台机器跑了多个容器怎么办？
A: 每个容器设不同的 AGENT_ID，各自上报各自的。FmodeAgent 表以 agentId 区分。

### Q: 能不能手动上报测试？
A: 可以。`skill-deliverable report --title "测试" --project test`。失败看 `/tmp/agent-deliverable-report.log`。

---

## 版本记录

| 版本 | 日期 | 变更 |
|------|------|------|
| 0.0.1 | 2026-09-23 | 初版：分离 fmode-hub 独立成技能 + 云函数 v2 改良 |