# Tianluo

> 田螺姑娘 (tianluo) — 让 Agent 像田螺姑娘一样在主人离开时（夜间 / 周末 / 用户睡眠中）自主推进多小时到多天的多阶段任务的方法论。核心抽象：持久 state + self-contained cron prompt + 有预算重试 + manual_hold 升级 + 多层诊断 + plan-time fork 枚举 + 文件角色分离。适用于 entity 数 ≥ 2、单跑 ≥ 1h、状态可轮询、故障可分类、终态可自动判定的场景（ML 流水线 / 爬虫批处理 / 仿真 sweep / 多目标巡检 / 长 CI / ...）。

- **Type:** Skill
- **Install:** `agentstack add skill-yeewangcn-tianluo-tianluo`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yeewangcn](https://agentstack.voostack.com/s/yeewangcn)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yeewangcn](https://github.com/yeewangcn)
- **Source:** https://github.com/yeewangcn/tianluo/tree/main/plugins/tianluo/skills/tianluo
- **Website:** https://github.com/yeewangcn/tianluo

## Install

```sh
agentstack add skill-yeewangcn-tianluo-tianluo
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 田螺姑娘 (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（task_id / job_name / 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`）：

```markdown
#  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 + manual_hold |
| Codex Automations | 互补：event-driven trigger 可补到本 skill cron 上（不只时间触发） |
| **Manus 3-file pattern** (task_plan + 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](https://github.com/yeewangcn)
- **Source:** [yeewangcn/tianluo](https://github.com/yeewangcn/tianluo)
- **License:** MIT
- **Homepage:** https://github.com/yeewangcn/tianluo

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yeewangcn-tianluo-tianluo
- Seller: https://agentstack.voostack.com/s/yeewangcn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.