⚡

st st

这是一个用于管理持久任务计划的技能，适用于软件开发项目中跟踪任务状态和依赖关系。它使用JSONL文件存储计划，支持任务添加、状态更新、依赖设置、注释管理等功能，并能导出导入计划快照，确保状态跨会话持久性和可审查性。关键词：任务计划，持久化，JSONL，依赖管理，状态跟踪，项目管理，DevOps。

DevOps 0 次安装 0 次浏览 更新于 3/8/2026

name: st description: 在仓库提交的JSONL文件（.step/st-plan.jsonl）中管理持久任务计划，使状态能在回合/会话间存活并在git中可审查。当用户要求"使用 $st"、“恢复计划”、“导出/导入计划状态”、“检查点里程碑”、“跟踪依赖/阻塞工作”、“显示就绪的下一个任务”、“在磁盘上保持共享TODO状态”、“比较和对比 $st vs 计划文件”，或当工作有3个以上依赖步骤且临时update_plan不够持久时使用。

st

概述

在仓库中维护一个持久的计划文件（默认：.step/st-plan.jsonl），使用原地 JSONL v3 持久化，具有双车道：

  • event 车道用于变更
  • checkpoint 车道用于定期全状态快照

计划项使用类型化依赖边（deps: [{id,type}]）加上notes和comments，并通过show/read视图确定性渲染。

工作流

  1. 解析仓库根目录和计划路径。
  2. 如果运行有3个以上依赖步骤、可能跨越回合，或已使用update_plan，在编辑前采用$st作为持久的真理来源。
  3. 如果缺失，使用scripts/st_plan.py init初始化计划存储。
  4. 使用scripts/st_plan.py show（或通过ready / blocked的聚焦视图）重新水化当前状态。
  5. 通过脚本子命令（add, set-status, set-deps, set-notes, add-comment, remove, import-plan）应用计划变更；不要手动编辑现有的JSONL行。
  6. 每个变更命令后，消耗发出的update_plan: {...}负载并在同一回合发布update_plan。
  7. 当需要时，使用emit-update-plan从持久状态重新生成负载。
  8. 当需要跨会话交接时，导出/导入快照。

命令

从目标仓库根目录运行命令。

CODEX_SKILLS_HOME="${CODEX_HOME:-$HOME/.codex}"
CLAUDE_SKILLS_HOME="${CLAUDE_HOME:-$HOME/.claude}"
ST_PLAN="$CODEX_SKILLS_HOME/skills/st/scripts/st_plan.py"
[ -f "$ST_PLAN" ] || ST_PLAN="$CLAUDE_SKILLS_HOME/skills/st/scripts/st_plan.py"
ST_QUERY="$CODEX_SKILLS_HOME/skills/st/scripts/st_query_fast.sh"
[ -f "$ST_QUERY" ] || ST_QUERY="$CLAUDE_SKILLS_HOME/skills/st/scripts/st_query_fast.sh"

uv run "$ST_PLAN" init --file .step/st-plan.jsonl
uv run "$ST_PLAN" add --file .step/st-plan.jsonl --id st-001 --step "重现失败测试" --deps ""
uv run "$ST_PLAN" add --file .step/st-plan.jsonl --id st-002 --step "修补核心逻辑" --deps "st-001"
uv run "$ST_PLAN" set-status --file .step/st-plan.jsonl --id st-001 --status in_progress
uv run "$ST_PLAN" set-deps --file .step/st-plan.jsonl --id st-002 --deps "st-001:blocks,st-003:blocks"
uv run "$ST_PLAN" set-notes --file .step/st-plan.jsonl --id st-002 --notes "需要基准证据"
uv run "$ST_PLAN" add-comment --file .step/st-plan.jsonl --id st-002 --text "暂停直到CI清理" --author tk
uv run "$ST_PLAN" ready --file .step/st-plan.jsonl --format markdown
uv run "$ST_PLAN" blocked --file .step/st-plan.jsonl --format json
uv run "$ST_PLAN" show --file .step/st-plan.jsonl --format markdown
uv run "$ST_PLAN" emit-update-plan --file .step/st-plan.jsonl
uv run "$ST_PLAN" export --file .step/st-plan.jsonl --output .step/st-plan.snapshot.json
uv run "$ST_PLAN" import-plan --file .step/st-plan.jsonl --input .step/st-plan.snapshot.json --replace

操作规则

  • 除非明确使用--allow-multiple-in-progress，否则保持恰好一个in_progress项。
  • 在每个项的deps数组中跟踪先决条件；依赖是规范JSONL模式的一部分。
  • 将CLI依赖解析为逗号分隔的id或id:type令牌；缺失类型规范化为blocks，类型必须为kebab-case。
  • 要求依赖完整性：
    • 依赖ID必须存在于当前计划中，
    • 无自依赖，
    • 无依赖循环。
  • 仅当所有依赖都为completed时，才允许in_progress和completed。
  • 写入前规范化用户状态术语：
    • open, queued -> pending
    • active, doing -> in_progress
    • done, closed -> completed
  • 变更命令（add, set-status, set-deps, set-notes, add-comment, remove, import-plan）在持久写入后自动打印update_plan:负载行。
  • 锁边车策略：在git仓库内时，变更命令需要锁文件（<plan-file>.lock，例如.step/st-plan.jsonl.lock）被git忽略；在第一次变更前添加到.gitignore。
  • 变更原子重写JSONL文件（temp + fsync + os.replace）并在当前seq水印处压缩为规范replace事件加检查点快照。
  • import-plan --replace在同一原地写入模型中原子重置状态。
  • 更喜欢简洁、稳定的项ID（st-001, st-002, …）。
  • 更喜欢show --format markdown用于执行：它将步骤分组为Ready, Waiting on Dependencies, In Progress, 和终端/手动桶。

快速查询助手（jq + rg）

  • 使用scripts/st_query_fast.sh针对大日志进行低延迟只读查询。
  • 需要PATH上的jq和rg。
  • 示例：
    • "$ST_QUERY" --file .step/st-plan.jsonl ready
    • "$ST_QUERY" --file .step/st-plan.jsonl blocked
    • "$ST_QUERY" --file .step/st-plan.jsonl show
    • "$ST_QUERY" --file .step/st-plan.jsonl show st-002

同步检查清单（$st -> update_plan）

  • 每个$st变更后（add, set-status, set-deps, set-notes, add-comment, remove, import-plan），解析发出的update_plan: {...}行并在同一回合发布update_plan。
  • 如果没有可用的发出负载（例如在init或shell管道后），运行：
    • uv run "$ST_PLAN" emit-update-plan --file .step/st-plan.jsonl
  • 在update_plan中保持来自$st的项排序。
  • 映射状态：
    • in_progress -> in_progress
    • completed -> completed
    • pending, blocked, deferred, canceled -> pending
  • 仅将依赖边保留在$st中（deps）；不要在update_plan中编码依赖。
  • 如果项有dep_state=waiting_on_deps，永远不要在update_plan中将该步骤发布为in_progress。
  • 在变更$st的回合的最终响应前，通过比较重新检查无漂移：
    • uv run "$ST_PLAN" show --file .step/st-plan.jsonl --format json
    • 最新的发出update_plan负载。

验证

  • 运行轻量级CLI健全性检查：
    • uv run "$ST_PLAN" --help
    • uv run "$ST_PLAN" emit-update-plan --file .step/st-plan.jsonl
    • uv run "$ST_PLAN" show --file .step/st-plan.jsonl --format json

参考文献

  • 阅读references/jsonl-format.md了解事件模式、状态/依赖状态词汇和快照导入/导出形状。