---
name: fmode-task-progress
description: "任务进度四态上报+成果交付入库：init-tables 初始化 FmodeAgent/AgentTaskStatus/AgentDeliverable 三表，progress 上报 ack→running→done/failed+心跳，deliver 把交付链接上报入库（幂等覆盖），status 查询本 agent/全集群视角。适用：(1) Agent 干活要让平台 App/看板实时可见 (2) 任务有交付物需交付即报 (3) 集群进度巡检。"
description_en: "Task progress (4-state) reporting + deliverable registration: init FmodeAgent/AgentTaskStatus/AgentDeliverable tables, report ack→running→done/failed + heartbeat, register deliverable URLs (idempotent upsert), query mine/all scope. Triggers: task progress, deliverable reporting, agent dashboard."
---

# Fmode Task Progress — 任务进度+成果上报技能

> 装上本技能，你的 Agent 干活进度与成果交付即刻进入 FmodeAgent 平台（App 四 Tab / 看板实时可见）。
> 来源：FmodeAgent 集群实战验证的「任务进度上报+成果交付上报」能力（agent-status-reporter 家族）。

## 一、快速开始

```bash
# 1. 初始化/校验三表（幂等，可重跑）
node skills/fmode-task-progress/scripts/init-tables.mjs

# 2. 任务四态上报
node scripts/progress.mjs ack     --agent my-agent --task task-001 --name "课纲修订"
node scripts/progress.mjs running --agent my-agent --task task-001
node scripts/progress.mjs done    --agent my-agent --task task-001 --note "已验收"
# 失败时
node scripts/progress.mjs failed  --agent my-agent --task task-001 --note "API 403，待充值"

# 3. running 心跳保鲜（30s 无心跳=疑似死亡，调度层会主动查）
node scripts/progress.mjs heartbeat --agent my-agent --task task-001

# 4. 交付即报（有交付物+链接就立即报，每章/每版/每次部署各一条）
node scripts/deliver.mjs --agent my-agent --task task-001 \
  --title "课纲 v1.0.6" --url "https://s3.fmode.cn/xxx/index.html" \
  --type courseware --project warmup --summary "修订完成已验收"

# 5. 查询
node scripts/status.mjs mine --agent my-agent     # 本 agent 最近任务+交付
node scripts/status.mjs all                       # 全集群（masterKey 视角）
```

## 二、凭据链（零硬编码）

四级解析（`parse-client.mjs` 统一实现，找不到时报指引退出，绝不猜）：

| 级 | 来源 | 场景 |
|---|------|------|
| 1 | 环境变量 `PARSE_APP_ID` / `PARSE_MASTER_KEY`（`PARSE_SERVER_URL` 可覆盖地址） | CI/容器 |
| 2 | `~/.fmode/config.json` → `parse` 段 `{appId, masterKey}` | 个人开发机 |
| 3 | `future-server/config/config.nova.json` → `parse` 段 | 平台开发机标准位置 |
| 4 | 以上皆无 → 打印配置指引，退出码 2 | —— |

**密钥红线**：config.nova.json 凭据绝不入 git；本技能脚本零硬编码，凭据只在运行时读取。

## 三、三张表

| 表 | 作用 | 关键字段 |
|---|------|---------|
| `FmodeAgent` | Agent 注册+心跳 | agentId / soulSummary / containerRef / lastHeartbeat(Date) / status / scope |
| `AgentTaskStatus` | 任务四态 | agentId / taskId / taskName / status(ack\|running\|done\|failed) / startedAt / endedAt / heartbeatAt / resultNote |
| `AgentDeliverable` | 成果 | agentId / taskId / title / project / deliverableType(report\|code\|courseware\|data) / url / summary / deliveredAt(Date) |

数据流：`Agent 上报 → Parse 表 → App 四 Tab / 看板（scope 三视角 mine/company/all）`。

## 四、★ Parse Date 字段铁律（schema 111 坑，已实测验证）

写 `Date` 类型字段（`lastHeartbeat`/`startedAt`/`endedAt`/`heartbeatAt`/`deliveredAt`）时：

```bash
# ✗ 错误：裸字符串 → Parse 报 code=111 schema 不匹配
{"startedAt": "2026-09-12T08:00:00.000Z"}

# ✓ 正确：__type Date 包装
{"startedAt": {"__type": "Date", "iso": "2026-09-12T08:00:00.000Z"}}
```

实测（2026-09-12，server.fmode.cn/parse）：
- 裸字符串写 `AgentTaskStatus.startedAt` → `code=111`（"Expected Date" 类错误）
- 包装后写 → 成功入库，查询返回 `{"__type":"Date","iso":"..."}`

本技能所有脚本统一走 `parse-client.mjs` 的 `wrapDate()`，**自己拼 JSON 直连 REST 时必须记得包装**。
同类包装：Pointer 字段 `{"__type":"Pointer","className":"Company","objectId":"xxx"}`。

## 五、上报纪律（★ 核心章节）

**交付即报**：
- 任务节点有明确交付物+链接 → **立即上报**（每章/每版/每次部署/每轮大修各一条）
- **漏报即补**：发现漏报马上用 `--delivered-at` 补录真实交付时间
- 幂等保障：同 agentId+taskId+deliverableType 覆盖更新，补报不产生重复条目

**进度四态+心跳**：

| 状态 | 触发 | 记录 |
|---|------|------|
| ack | 接任务回执 | taskName / startedAt |
| running | 开工 | heartbeatAt 保鲜 |
| done | 完成+验收过 | endedAt + resultNote |
| failed | 失败/超时/验收不过 | endedAt + 根因（不掩盖） |
| heartbeat | running 期间每 30s | 只刷 heartbeatAt |

- **30s 无心跳 = 疑似死亡**：调度层主动查进程与产物，不靠"以为还在跑"
- **done 的前提是验收过**：只收到 DONE 标记但未独立验证 → 不报 done

## 六、多工具安装

### Hermes Agent
```bash
git clone https://git.fmode.cn/fmode/skill-task-progress.git
cp -r skill-task-progress/skills/fmode-task-progress ~/.hermes/skills/
```

### Claude Code / Codex
```bash
git clone https://github.com/fmodecn/skill-task-progress.git
cp -r skill-task-progress/skills/fmode-task-progress ~/.claude/skills/   # 或 ~/.codex/skills/
```

### WorkBuddy / 其他
复制 `skills/fmode-task-progress` 到对应技能目录，README 按工具规范并入。

## 七、故障对照

| 症状 | 根因 | 对策 |
|---|------|------|
| `code=111` schema 错 | Date 字段裸字符串 | 走 `wrapDate()`（本技能脚本已内置），手拼 JSON 记得 `__type` 包装 |
| 凭据报错退出码 2 | 四级链全空 | 按报错指引配 env 或 `~/.fmode/config.json` parse 段 |
| 重复成果条目 | 未用幂等覆盖键 | deliver.mjs 按 agentId+taskId+deliverableType upsert，勿绕过 |
| 查询 403 | REST masterKey 不在环境 | 走四级凭据链，勿用过期 sessionToken |