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 家族）。

一、快速开始

# 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）时：

# ✗ 错误：裸字符串 → 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

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

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

SKILL.md 6.1 KB تاريخچه خام