Tianluo

田螺姑娘 (tianluo) — Long-Running Task Orchestration

> 田螺姑娘（中国民间传说）：渔夫白天出海，姑娘从田螺壳出来悄悄做饭打扫，渔夫归来时房间整洁饭菜在桌。 > > 长跑 agent 应像田螺姑娘：主人睡觉/离开时悄悄推进任务，不打扰；主人回来时只看终态报告，不看运行细节；遇到不能独立决定的事才低声请示。 > > 本 skill 是纯方法论——领域踩坑请放项目 memory/docs，不进本 skill。

1. 适用 / 不适用

全部满足才用本 skill：

• 单次执行跨度 ≥ 1 hour（短任务手动盯就行）
• 实体数 ≥ 2 或阶段数 ≥ 2（否则没 state-machine 复杂度）
• 状态可轮询（API / 文件 / 进程查得到）
• 故障可分类（瞬时 / 配置 / 代码 / 未知）且每类有应对
• 终态可自动判定（产物存在 OR 指标达标）

不适用：

• __analysis.md`（根因 / stderr tail / 建议下一步）
• 本 entity 暂停，其他继续（故障隔离）
• 人工介入后改 state 解除 hold

2.5 分层结构化诊断（必查所有层）

抽象层级（具体技术栈映射各异）：

1. 调度层：外部调度器视角 + 资源消耗指标
2. 执行容器层：每个进程/容器的 exitCode + 主机 + 生命周期
3. 日志层：覆盖全部（实例 × 流 × 角色），不只看主进程 stdout
4. 业务进度层：子进程内部信号（不只是父进程 heartbeat）
5. 产出层：最终产物是否真的在生成

关键：只看 1 层就下结论是错误的。失败 90% 来自层间不一致。

3. 八条不变量（违反任一 → 大概率错决策）

1. State = single source of truth（不是 agent 记忆）
2. Prompt 自包含（每次触发零上下文重建）
3. 动作 = 有预算重试 + ladder 升级
4. 诊断扫所有层（不只看表面）
5. 授权 = 白名单 + 破坏性留 prompt
6. ⭐ 提交即记录：submit 成功 → 下一个工具调用必写 state（taskid / jobname / submitted_at）。submit 与 record 是原子对。
7. ⭐ Plan-time 一次性枚举所有 fork：在设计任务链时把所有未来需要用户决策的分叉一次性列给用户（含选项 / 默认 / 推迟代价）。运行期只走自主白名单 → 不中断。是 long-running 区别于一般 agent 的核心 discipline。
8. ⭐ File-role 严格分离：runtime state（机器读，JSON）/ intent plan（人审，MD）/ failure artifacts（postmortem，MD）/ memory（cross-session pits，MD）四类文件分离，绝不合并。Manus 的 mono-file (task_plan + findings + log 一体) 是反模式——会导致状态被自然语言污染、无法 grep、无法 pre-commit hook 校验。

> ⭐ 标注的三条是本 skill essence，业界其他长链路框架（StateFlow / ReWOO / Cursor harness / Manus / Claude Plan Mode）都没同时强调。

4. Plan-time fork enumeration（核心独特价值）

Why：长跑链最大失败模式不是技术故障，是中途阻塞等回复。每个未来"问用户"点都是 8h 死锁的潜在源。

Plan 阶段必做：

走查整个任务链，列出所有 future fork 类型：

| Fork 类型 | 例子 | |---|---| | 分支决策 | "metric X > 阈值 → A 路径，否则 B 路径" | | 资源阈值 | "这步会跑 14h，OK？" | | 跨依赖 | "等 X 完成 vs 立即推进" | | 风险兜底 | "如 OOM → A. 降配 / B. 切 LoRA / C. hold" | | 输出去向 | "ckpt 上传哪 / 写哪个 DB" |

Plan 文档模板（参见 templates/plan-doc-skeleton.md）：

#  Plan

## Success Gate (terminal-state 判定)

## 决策点（请一次性回复）
### Q1: 
- 选项: a / b / c
- 默认: 
- 推迟代价: 

### Q2: ... (共 N 个)

明确说"答完跑到终态不再中断"。回完写进 state.json pre_authorized_decisions 字段，后续 cron 直接读。

Success Gate 配套：每个 plan 必须显式声明终态判定条件（借鉴 Spec-Driven Development 的 verification criteria）。Cron prompt 在每轮检查 success_gate；满足即自动 stop loop。否则 long-running chain 不知何时才算"完"。

反面模式（必须避免）：

• "先按默认走，遇到问题再问"——保证翻车
• 决策点藏在某步骤里没显式列——agent 中途才意识到要问
• 没有 success_gate——cron 永远循环
• agent 在 cron 运行时读自己的 plan.md 当 ground truth（Claude Plan Mode 退出后那种用法）：会 self-reference drift。plan.md 是给人看的合同，运行时 ground truth 是 cron prompt + state.json

5. 业界对照（一句话每个）

| 方案 | 与本 skill 关系 | |---|---| | Anthropic Effective Harnesses | 同质：init.sh + progress 文件 + commit 即 state；本 skill §2.1 更细化 | | Anthropic Building Effective Agents | 互补：他们讲 5+1 building blocks 设计模式，本 skill 讲 deploy/runtime | | Anthropic Three-Agent Harness | 互补：plan/gen/eval 三角色，本 skill 5 部件可作其 deploy backbone | | Anthropic Managed Agents | 借鉴：durable event log 比 state.json 更鲁棒（可补） | | Anthropic Claude Code Plan Mode | 反向借鉴：他们让 agent 退出 plan mode 时读 plan.md 当 ground truth；本 skill 故意不让 agent 读 plan.md（runtime ground truth 是 cron prompt + state.json，避免 self-reference drift）| | Cursor Self-Driving Codebases | 同质：Planner/Worker/Judge 三角色 ≈ 本 skill cron + manualhold | | Codex Automations | 互补：event-driven trigger 可补到本 skill cron 上（不只时间触发） | | Manus 3-file pattern (taskplan + findings + progress) | 反模式警告：Manus 把 plan + findings + log 合一，互联网研究 agent 适用，但长跑 ML pipeline 必须分离（不变量 #8）。可借鉴的只是"PreToolUse hook 在破坏性操作前 re-read intent" | | GitHub Spec Kit / SDD | 借鉴：Spec 中的 verification criteria → 本 skill plan 的 success_gate（已采纳） | | StateFlow (学术) | 借鉴：fixed escalation ladder（已写进 §2.3） | | ReWOO | 同源：plan-once-then-exec 思想 ≈ 本 skill §4，但 ReWOO 没强调"用户预先 confirm 所有 fork" | | LangGraph checkpointers | 借鉴：JSON state snapshot per node-step 比纯 state.json overwrite 更鲁棒（可补 versioned schema）| | HITL 三模式 (approval/conditional/audit) | 借鉴：本 skill §2.4 可升级为三档 audit-based 模式 |

6. 典型 state.json 骨架

参见 templates/state-schema.json。

7. Cron / 触发机制选择

• OS crontab：跨 session 持久（推荐生产环境）
• Claude Code CronCreate：session-only，进程退出就没。开窗跑短期 OK
• ScheduleWakeup（Claude Code dynamic loop）：模型自己决定下次唤醒时间
• Event trigger（Codex Automations 风格）：状态机变化 / 文件落盘触发，比时间触发更精准

间隔推荐 10-15 min：短了 agent 自己打架，长了响应慢。

8. 项目级经验如何固化（不进 skill）

本 skill 只留方法论。项目特定的踩坑、框架特性、配方陷阱写到：

• ~/.claude/projects//memory/feedback_*.md —— 跨 session 持久 pit（如"X framework 在 Y 共享文件系统上的 mkdir race"）
• /experiments/_plan.md —— 单次实验的前置 plan + 决策点（含 success_gate）
• /experiments/_findings.md —— 单次实验运行中的临时记录（append-only scratchpad；agent 边跑边写"我发现 X"），借鉴 Manus findings.md 但严格只 append、不当 ground truth
• /experiments/_lessons.md —— 实验完成后的 postmortem
• 不要把"X framework on Y filesystem 触发的 race"这种两层组件特定的 bug 写进 skill

9. 何时不要用本 skill

• 任务 < 10 min（手动）
• Workflow 完全确定（用 5+1 blocks 的 Prompt Chain 即可）
• 需要主观判断每步（用 Three-Agent Harness 的 evaluator）
• 没有外部 state（用普通 agent，无需 cron）

---

文件结构

long-running-orchestration/
├── SKILL.md                       # 本文件，纯方法论
├── reference/
│   ├── 5-layer-debugging.md       # 各层诊断细则（抽象层级）
│   ├── retry-budget-ladder.md     # StateFlow-style 升级阶梯
│   ├── plan-time-fork-types.md    # 5 类 fork 详解 + 反面模式
│   └── industry-comparison.md     # 与其他框架的对照表
└── templates/
    ├── state-schema.json          # state.json 骨架
    ├── cron-prompt-skeleton.md    # cron prompt 模板（自包含）
    ├── plan-doc-skeleton.md       # plan 文档（含 Q1..Qn）
    └── failure-analysis.md        # manual_hold 时写的诊断

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yeewangcn
• Source: yeewangcn/tianluo
• License: MIT
• Homepage: https://github.com/yeewangcn/tianluo

Install and usage instructions live in the source repository linked above.