| name | long-term-task |
| description | 面向跨多轮、长时间、需要持续推进与可恢复状态的任务守护技能。用于用户明确说“长期任务”“长时任务”“持续任务”“一直做完”“继续推进”时，要求先落状态、持续更新验证结果与下一步，并防止把阶段性进展误报成完成；同时必须优先服从用户指定的输出格式，不得为了“持续任务感”污染 JSON-only、代码块-only 或截图判定输出。 |
Long-term Task
Claude Code 对齐核心
这个技能的目标不是“更啰嗦”，而是把长期循环的 stop hook 行为对齐到 Claude Code 的 Stop Hook 机制，并保持输出格式绝对安全：
- 主循环状态：使用 Markdown + YAML frontmatter（不是 JSON，属于本地自定义状态）
- Stop hook 输入：遵循 Claude Code
StopHookInput（session_id / transcript_path / cwd / stop_hook_active / last_assistant_message）
- Stop hook 输出：遵循
HookJSONOutput（continue / stopReason / decision / reason / systemMessage）
- 强制继续：用
decision=block + reason 触发 Stop hook feedback 回喂
- 主动终止：不输出 JSON，或
continue=false + stopReason（触发 preventContinuation）
Claude Code 参考细节见：references/claude-ralph-loop.md
主循环状态文件（Markdown）
路径约定（Codex 全局）：
C:\Users\<你>\.codex\.omx\ralph-loop.local.md（全局单文件）C:\Users\<你>\.codex\.omx\ralph-loops\index.json（全局多任务索引）C:\Users\<你>\.codex\.omx\ralph-loops\<taskId>.md（全局任务状态）
（Claude Code 不提供该状态文件，这是本技能基于 Stop hook 机制的本地约定）
格式：YAML frontmatter + prompt 正文
---
iteration: 1
max_iterations: 50
completion_promise: "DONE"
session_id: "<omx-session-id>"
started_at: "2026-04-11T01:40:00Z"
auto_chunk: true
max_output_chars: 800
non_interactive: true
reporting: final_only
---
<任务提示与完成条件>
规则：
iteration 只由 stop hook 自动递增，不手改max_iterations <= 0 视为无限循环completion_promise 为空 / null 时不会自动结束session_id 用于会话隔离，避免别的会话误阻塞auto_chunk: true 时启用分段输出提示max_output_chars 为每轮输出字数上限提示（尽量遵守）non_interactive: true 表示持续模式 禁止中途询问reporting: final_only 表示 仅在完成后汇报总结
Stop Hook 行为（Claude Code 对齐）
对齐要点：
- 退出时读取
.omx/ralph-loop.local.md
- 优先使用
last_assistant_message，仅在缺失时回退到 transcript_path JSONL
- 若
<promise>...</promise> 与 completion_promise 完全一致 → 删除状态文件并允许退出
- 否则用
decision=block + reason=prompt 阻止退出，并把同一 prompt继续喂回
- 状态文件损坏 / transcript 不可读时 → 停止循环并清理状态文件
注意：此处只做“行为对齐”，不直接修改当前 hooks 配置。
Stop Hook 缺失 / 不可用时的回退（稳定性增强）
当环境没有真实 Stop Hook 回喂或检测到 stop hook 不生效时，必须切换为“非交互持续模式”：
- 不再输出
HookJSONOutput（避免等待回喂而停住）
- 不向用户反复确认“是否继续”
- 仅在 破坏性 / 权限 / 重大分支 时提示阻塞，其余继续执行
- 中间进展只写入 state（
last_verified / next_actions / blocked_reason）
- 汇报节奏改为 任务全部完成后一次性总结（除非用户要求中途汇报）
目的：在缺少 stop hook 的环境里依然保持持续推进，不再“停下来问”。
非交互持续模式（non_interactive）
若任务上下文包含“持续模式 / 不要停 / 不用问 / 做到底 / 继续推进”等语义，或 stop hook 不可用：
- 视作
non_interactive: true
- 禁止中途询问“是否继续/是否确认”
- 只在 不可逆、破坏性、权限不足 时报告阻塞
- 进度与证据写入 state，最终完成后再总结
JSON 证据状态（只做验证，不驱动循环）
继续使用你已有的 .omx/state/.../ralph-state.json 或其他 JSON 状态：
建议字段：
goal / task_descriptioncurrent_phaselast_verifiednext_actionschanged_files（如适用）artifacts / evidence（如适用）blocked_reason（如适用）
规则：
last_verified 只写已验证事实next_actions 必须是可执行动作
输出格式纪律（不可污染）
如果用户要求：
- JSON-only / 代码块-only / 固定 schema
必须：
- 严格输出指定格式
- 不追加“继续/未完成”语句
- 不塞入额外字段
- 把“未完成/下一步”写入 state，而不是污染输出
输出门禁（防止中途汇报）
当 non_interactive: true 或任务语义为“持续模式”时：
- 禁止阶段性总结或进度汇报
- 仅在“全部完成”时输出最终总结
- 若必须阻塞（破坏性/权限/重大分支），只写阻塞原因，不追加“请确认是否继续”
工作流（对齐版）
- 初始化
.omx/ralph-loop.local.md（包含 prompt + completion_promise）
- 强制写入：
non_interactive: true、reporting: final_only
- 侦测 stop hook 可用性与
non_interactive 语义
- 确保状态文件存在：
- 推荐路径：
C:\Users\<你>\.codex\.omx\state\long-term-task\<session_id>.json
- 若不存在必须创建（空结构也可），避免“只口头描述不落盘”
- 每轮执行后更新 JSON：
last_verified / next_actions
- 允许自由文本输出时：完成后输出
<promise>...</promise> 精确匹配
- 必须严格 JSON 输出时：手动清理 loop 状态文件 + 更新 JSON 状态
编排模式（ralplan + ralph 包装盒）
目标：把 long-term-task 作为兜底层，自动编排 ralplan($plan --consensus) 与 ralph，但不破坏它们的权威职责。
默认策略（推荐）：
- 先判断是否需要规划
- 用户明确说“计划 / 方案 / ralplan / plan / 共识 / 先想清楚”→ 调用
$plan --consensus
- 任务非常明确且用户说“直接做 / 继续 / 做到底”→ 跳过规划，直接
$ralph
- 规划完成后是否执行
- 若用户明确说“执行 / 继续 / 做完”，或在规划阶段选择“批准并执行”→ 调用
$ralph
- 若用户只要计划 → 停在 plan，不自动执行
- 执行阶段
- 由
$ralph 负责实现/验证/完结
- long-term-task 只做 Stop Hook 与 JSON 进度记录，不干预 ralph 的验收口径
强制边界：
- long-term-task 不替代 plan/ralph 的职责
- 没有用户批准时，不自动执行
- 仍遵守“输出格式不可污染”的规则
结论：long-term-task 可以作为“包装盒 + 兜底层”，但执行权在 ralph，规划权在 plan/ralplan。
全局多任务（推荐）
使用全局脚本管理任务与 active 切换（不依赖项目目录）：
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs init task-a --prompt "任务：……"
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs list
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs activate task-a
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs bind task-a --session-id <session-id>
node C:\Users\<你>\.codex\tools\omx\ralph-loop.mjs sync
并行原则：
不同会话（session_id）可绑定不同 taskId，Stop hook 会优先按 session_id 选择对应任务，从而实现“全局多任务并行”。
严格 JSON 输出的处理
当 JSON-only 输出不允许插入 <promise> 时：
completion_promise 设为空或 null- 通过删除
.omx/ralph-loop.local.md 结束循环
- 在 JSON state 里记录完成或阻塞原因
与其他技能的关系
- 防止过早宣布完成：
$task-completion-guard
- 需要持续执行直到完成：
$ralph
- 需要长期规划与跨轮交接：按用户要求再考虑
planning-with-files
- 需要共识规划：
$plan --consensus（ralplan）
禁止事项
- 不得为了“持续任务感”污染 JSON 输出
- 不得把猜测写进
last_verified
- 不得把空话写成
next_actions
- 不得手改
iteration 破坏循环
- 不得在未完成时输出
<promise>
- 持续模式下不得中途询问是否继续（除非破坏性/权限/重大分支）
- 任务派发需等全部完成后再汇报总结（除非用户要求中途汇报）
最小完成标准
