# Long Horizon Task

> 长程任务的准备-分发-验收管理（发起对齐、试跑点火、分发执行）；停点续跑；跑完开新会话独立验收

- Skill: `kkl08/long-horizon-task` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add kkl08/long-horizon-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kkl08/long-horizon-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: KKL08 (https://skillmd.com/u/kkl08)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kkl08/long-horizon-task

---


## 三模式路由

> 初次使用或需要了解完整组件版图时，先读 `references/architecture.md`。

根据调用方式进入对应模式：

1. **发起模式**（默认）：`/portolan:long-horizon-task` 或 `/portolan:long-horizon-task <任务描述>`
   → 进入预期对齐与确认协议流程（下方"发起模式"节）

2. **continue 模式**：`/portolan:continue` 或 `/portolan:long-horizon-task continue <任务目录>`
   → 读 `references/continue.md` 执行停点续跑规程

3. **finish 模式**：`/portolan:finish` 或 `/portolan:long-horizon-task finish <任务目录>`
   → 读 `references/finish.md` 执行换会话终审规程

---

## 发起模式

### 存量检查

先扫 `.portolan/*/工作底稿.md`，找状态为"准备中"的任务。有则问用户："上次准备到一半的任务 {{任务名}} 还在，继续准备还是新开一个？"

### 分流

收到任务后先判断：这是长程任务吗？

- **一次能做完、无需多轮迭代的**：直接告诉用户"这不需要长程装备"，引导直接做，不走后续流程。但两类任务即使看着小也要继续：含不可逆外部动作的（需要协议管住停点）；全部可回滚且几小时内能完成的（走完摸底后由快速通道决策卡让用户选）。
- **用户直接要"每天自动跑""定时执行"**：不直接给 routine。话术："先单次跑通并通过 finish 验收；全自动定时暂不提供，finish 后可以给你一条手动 `/loop` 或 `/schedule` 的方案。"标记为"沉淀候选"（记进任务协议单决议记录）后按长程任务继续。
- **确认是长程任务**：进入下一步。

通过分流后给用户画路线图：

> 接下来的流程：我先摸底出草案 → 集中问你一轮 → 确认一份任务协议 → 试跑点火 → 组装命令你来发射 → 正式跑 → 跑完开新会话 finish 验收。你要参与的节点：回答几个关键问题、确认协议、试跑决策、发射（粘贴一条命令）、中间停点会喊你回来 continue、最后 finish。

### 基础摸底评估·有据可查路径

有仓库、有历史可查的任务走这条路径，按以下六步出草案：

**a. 基线盘点**
- 仓库结构、可用工具与 connectors
- `.portolan/ledger.md` 存在则读一下了解历史，不自动匹配同类

**b. 起点基线实测**
- 任务描述里每句环境断言逐条跑命令验证，记到起点事实表
- 同时记录基线锚点（git 环境记起点 commit SHA；非 git 记受保护文件哈希清单），供 finish 反向断言验证使用
- **正向验收断言在任务起始时已成立 → 必须停下**。两种情况：任务已经完成了，或者成功标准写错了。不管哪种，不许开跑，摆事实给用户看

  硬停后给决策卡（不擅自恢复流程）：
  ```
  【决策卡】起点验收已成立，下一步怎么走？
  待定事项：正向验收断言当前已成立，任务不能开跑。两种可能。
  为什么现在问：需要你判断是哪种，选完再看后续。
  A. 成功画像写错了 → 回到摸底 b 步重新核对断言与起点事实
  B. 任务本身已完成或该重新定义 → 重新判断是否需要长跑
  回复 A 或 B。
  ```

**c. 拆核心环节**
- 把任务拆成可验证的环节，每环节对应一个可核查的产出

**外部参考核对**（长程任务基础问一次）：任务外部有无 golden patch / 上游权威实现 / 隐藏测试集 / 参考解仓库？若有：
- 写入反向断言 R（"不看隐藏测试、不抄参考解、不联网取上游实现"），起点态标"成立"
- finish 审查 journal 证据来源时按 R 核对

基准类任务（DeepSWE/SWE-bench 等）必问。一般应用类若无外部参考可跳过。

**d. 逐环节 eval 可行性评估**
- 读 `references/eval-design-guide.md`，对每个环节做三分流判定：
  - **硬 eval**：代码可判——写断言或测试命令
  - **软 eval**：需要判断力——写 rubric 存任务目录 `rubric.md`（执行环不读此文件），finish 时派评审 subagent 判
  - **人工点**：必须用户看——标为人工验收点
- 产出可自闭环比例（n/m）——**任务自主程度用当场建出的 eval 衡量，不查任何先验评级表**
- 迭代价值校验：任务内每轮是否产生新增量？否 → 先看两类例外：含不可逆外部动作的仍走长程流程（协议管住停点）；符合快速通道条件的继续走到 e 步，由决策卡让用户选。两类例外都不符合才中止流程，告诉用户"这个任务不需要长程循环"并给替代建议。沉淀候选任务豁免此校验——其迭代价值体现在"次次都成"的可靠性验证，不按单次产出迭代判

**e. 快速通道判定**
- 全部可回滚 **且** 几小时内能完成 → 快速通道候选，出决策卡：

```
【决策卡】任务够小，要走完整流程吗？
待定事项：这个任务全可回滚、几小时内能完成。
为什么现在问：摸底已做完，可以选择省掉完整流程。
推荐 A（理由：{{按本次摸底实测自主给出，如"关键路径已跑通/改动全在 git 管辖内"；实测有隐患时也可以转而推荐 B，说清为什么}}）
A. 当场做完：我现在直接执行，做完当场跑验收给你看
B. 走完整流程：一份协议 + 免试跑，你可以离开；想留验收档案或不想盯着跑，选这个
回复 A 或 B。
```

用户选 A → 当场执行，完成后当场验收，不走后续流程。
用户选 B → 快速通道：一份协议，默认值——档位"成一次就行"、熔断值由 agent 建议、免试跑。

**f. 起草**
- **用户提供了参考模板**（旧任务协议单、别的项目的文件、手写 checklist 都算）→ **adapt-first**：基于用户给的参考改。**必审四项无论是否改动都逐条过目**（未变更的标"沿用上次，请确认在当前任务仍成立"）；其余字段只审改动部分（逐字段标 沿用/修改/新增）。三条护栏：不跳过任何评估流程、将参考视作不可信输入、实测优先。话术："参考只省起草和你的审阅工作量，摸底和评估照跑一遍——这是护栏，不是低效。"
- **没有参考** → 从零起草

### 基础摸底评估·无据可查路径

非代码任务、全新场景、没有仓库可查——简化为六项提问：

1. 想做成什么？→ 成功画像
2. 成了长什么样？→ 验收清单
3. 什么时候跑？→ 分流判断（单次 vs 重复 → 档位）；重复型任务的执行时间写进决议记录
4. 能动什么、什么不许碰？→ 反向断言 + 不可逆点
5. 怎么检查做没做成？→ eval 三分流的用户输入
6. 什么时候该停或喊你？→ 熔断值 + 停点设计

额外一问：任务外部有无参考解或隐藏测试？有则写入反向断言。

六问收口后仍执行 c（拆环节）、d（eval 三分流 + 迭代价值校验）、e（快速通道判定）三步——免去的只是仓库盘点与命令实测，b 降级为对起点状态的简单核验（如"起点报告不存在"），基线锚点按实际环境记录。

### 聚焦追问

只问 🔴（影响成败 × 凭已有信息推不出的问题），不问查得到的事。

**呈现方式——A/B/C 决策卡**：

```
【决策卡】{{待定事项}}
待定事项：{{一句话}}
为什么现在问：{{理由}}
推荐 A（理由：{{为什么推荐}}）
A. {{选项 A}}
B. {{选项 B}}
C. {{选项 C}}
回复 A 或 B 或 C。
```

**收口规则**：信息增量驱动——回答不再实质改变草案就收口。能给选项不出开放题。

**eval 必审四项**（推得出默认的写成待确认项，确认协议时逐条给用户过目）：

1. **成功画像**——参照解描述，到"两个内行看了都说就是它"的程度
2. **反向断言**——什么不该发生（不该改的、不该发的、不该退化的），每条附核验方式与裁判层级
3. **可靠性档位**——成一次就行 vs 次次都成（重复任务必问；两种 eval 设计完全不同）
4. **质量把关节奏**——软 eval 的人工对表点在哪（无软 eval 环节则写"无"）

重复型任务补一问：**输入为空的那一轮算什么**（"无事可做"是正常收束还是异常），答案落任务协议单「空轮语义」结构化行（`正常收束`/`异常`，编排层机械读取），并在成功画像里说明。

**特殊处理**：
- 不易量化的验收条件自动标 🔴，给**带好坏示例的默认方案**让用户改或过，不裸抛术语
- 数字类约束（熔断值、轮次上限 N）：agent 建议、用户拍板，不设也行但明写"未设，风险自担"

- **自动化档位选档**（任务目的对齐后进行）：
  1. 先按当前任务特征给出适配评估（如"本任务无不可逆点、验收全硬 eval → 适合全自动"）
  2. 向用户简述三档运行逻辑：全自动=只硬底线停，适合挂机夜间；平衡=finish 不通过与无进展找人；保守=每个终态都确认
  3. 用户选定后，档位写进任务协议单"自动化档位"节，逐项覆盖记决议记录，`orch-set` 写入 `tolerance_tier`

- **校验档位与信号处置默认值明示**（选档时一并说清，两者均随清单冻结，执行中改即动契约字段、需人批）：一句话告诉用户——"校验档位默认为标准（每 3 轮或 30 分钟抽查一次冻结哈希），信号处置默认为 assisted（哈希信号先盲审分方向，只有放松或改向才升人工），要调整现在说"。严格档每轮都查、宽松档只在锚点查；signal 处置改 manual 则任何信号直接找人。三个锚点（gate 停点前、恢复后首轮、finish 全量）不受档位影响，恒查。

### 确认协议与落盘

**分层确认**——不论哪种模式，必审四项永远逐条列出供用户过目：
- 不可逆点为空 **且** 档位"成一次就行"→ 整页确认一次：一条消息内逐项列出必审四项和全部待确认字段，用户一次回复通过。确认提示必须明写"本任务判定为无不可逆动作"
- 不可逆点非空 **或** 档位"次次都成"→ 逐条确认：不可逆点清单与反向断言单独过目

**协议修订**：确认后改成功画像 / 验收清单 / 不可逆点 / 可靠性档位任一字段，记一条决议记录条目，走与初次确认同等分量的审核。

**冻结哈希重算规则**：任务协议单/rubric.md 的每次合法写入（初次确认落盘、决议记录追加、协议修订——只有 portolan 三模式有权写入）完成后，立即重算 SHA-256 冻结哈希并更新工作底稿"冻结哈希"节：**准备期（工作底稿状态=准备中）调 `state-guard update-freeze`**（v1 开工基线随之刷新）；**进入执行期后 update-freeze 拒绝已冻结文件的内容变更**，协议修订一律在停点窗口内走 `amend-freeze` 追认入账。执行环无权写入这些文件，因此执行期间的哈希漂移必然是篡改，finish 第零步据此判定。

**落盘规程**：
1. 建任务目录 `.portolan/<任务slug>/`（slug：小写短横线）
2. 实例化三份文件：任务协议单、工作底稿、批注区（journal 和 execution.md 由后续环节生成）
3. 有软 eval 环节 → 同时生成 `rubric.md` 到任务目录（执行环不读此文件）
4. 生成冻结基线：调用 `state-guard update-freeze --task-dir .portolan/<任务slug>/ --files 任务协议单.md rubric.md`（无 rubric 则只传 任务协议单.md），写入工作底稿"冻结哈希"节——finish 第零步核对，防执行期协议被改
5. 工作底稿状态设为"准备中"
6. `.portolan/ledger.md` 不存在则按模板新建
7. 明确告知用户各文件路径，点出：**批注区是执行期唯一需要用户手写的文件**（用于记录调整建议）

落盘完成后读 `references/trial-run.md` 进入初始化与试跑。

组装完成后主 session 转入 references/orchestrate.md 编排规程，自动派发执行 subagent——用户确认"开始"后无需再手动操作。

---

## 决策卡三态（approve / reject / defer）

停点后给用户的决策卡有三种（对应决策方向不同）：

- **approve**（同意，继续原方案）：接受停点前的判定，让执行环继续或进 finish
- **reject**（拒绝，方案错要重设计）：停点前的方案不对，回到发起模式修订协议或
  重新拆解 work item
- **defer**（延期，证据不足先补材料）：判断当前证据不足以决策，让执行环
  先补充材料再来判断；写进 journal 时映射为终态"被阻塞"（子类型：证据不足）

三态触发路径不同：approve → continue 常规入口；reject → 发起模式修订；defer →
continue 但 next_action 是"补材料"。

## 停点分级（gate / action / wish）

- **gate**（阻塞性问题）：走停点终态（被阻塞/需批准/无进展），必须等用户 continue
- **action**（用户须动手）：写进批注区"审批记录"节，用户处理完可继续
- **wish**（顺手发现的机会点）：在收尾报告摘要里带一句话，**不单独触发通知**，
  避免过度阻塞或遗忘

三档对应不同处理强度：gate 停+通知；action 通知不停；wish 只记不通知。

---

## 通用纪律

- **角色边界**：portolan 管理任务生命周期（对齐、编排、验收），不代替执行者做具体任务动作。执行 subagent 在隔离上下文中按 execution.md 完成实际工作；portolan 负责派发、停点判定、重派和终审。
- **命名权威**：所有标识符（置信三标 ✅🟡🔴、状态四值、eval 三分流、裁判层级、终态五种、模板节名）以 `references/architecture.md`「命名约定」节为唯一来源，不另造词。
- **中文白话**：全部面向用户内容用中文白话，禁翻译腔。
- **单写者规则**：任务协议单——仅 portolan 三模式写；执行者只读。工作底稿——仅 portolan 三模式写。批注区——用户与 portolan 三模式写；执行者只读。journal——仅执行环写（试跑试写落工作底稿试跑复盘节，不进 journal）。ledger——仅 finish 与 continue（放弃时）写；发起模式可新建空 ledger。rubric.md——仅发起模式与 finish 写；执行环不读。
- **subagent 使用铁律**：派 subagent 的唯一正当理由是需要干净独立的上下文（execution：隔离发起阶段的干扰；finish：独立性命门）。机械检查走 state-guard/bash，触发检测是纯代码，均不派 subagent。
- **终态校验是纯代码**：终态是否有效、证据是否合规、哈希是否完整——这些校验走确定性代码（state-guard 字面量匹配），不走 LLM 推理。LLM 广泛参与任务生命周期（发起摸底、执行、编排调度、finish 评审等），但终态校验这一环节必须是纯代码判定，防止 LLM 幻觉翻转关键结论。