refactor: reorganize CLI commands — workflow/thread/step/turn 四层模型 #463

New Issue

2026-05-24T10:03:18Z

xiaoju commented

2026-05-24 10:03:18 +00:00

背景

当前 CLI 命令全挤在 thread 下，概念混乱：

thread step 既是动词（执行）又是名词（步骤）
thread steps / thread step-details / thread fork 操作对象是 step，不是 thread
list vs running 概念容易混淆
kill 做了停止+归档两件事
workflow put 是 CAS 层语义，用户视角应该是"注册"

四层模型

workflow → thread → step → turn
模板定义    执行实例   单步结果   agent 内部交互

目标命令结构

uwf workflow
  add <file>                        # 注册 workflow（原 put）
  list                              # 列出已注册的
  show <id>                         # 查看定义

uwf thread
  start <workflow> -p <text>        # 创建 thread
  exec <thread-id> [-c N] [--background]  # 执行（原 thread step）
  list [--status idle|running]      # 合并 list + running，带状态列
  show <thread-id>                  # head + meta
  read <thread-id>                  # markdown 渐进式阅读
  stop <thread-id>                  # 停止后台执行
  cancel <thread-id>                # 放弃 thread，移出活跃列表（原 kill）

uwf step
  list <thread-id>                  # 列出 thread 的所有 step（原 thread steps）
  show <step-hash>                  # step 元信息（role, agent, output, timestamp）
  read <step-hash> [--before N]     # markdown 渐进式阅读 turns（新功能）
  fork <step-hash>                  # 从 step 分叉，产出新 thread（原 thread fork）

uwf cas
  get <hash>                        # 原始 CAS 数据兜底

改动映射

旧命令	新命令	说明
`workflow put`	`workflow add`	语义更准确
`thread step <id> -c N`	`thread exec <id> -c N`	消除名词/动词歧义
`thread steps <id>`	`step list <id>`	归属到 step 层
`thread step-details <hash>`	`step show <hash>`	归属到 step 层
`thread fork <hash>`	`step fork <hash>`	操作对象是 step
`thread list` + `thread running`	`thread list [--status]`	合并，带状态列
`thread kill`	`thread stop` + `thread cancel`	拆分：停止执行 vs 放弃 thread
(新)	`step read <hash>`	markdown 渐进式阅读 turns

不做

turn 不单独建命令组，step read --before N + cas get 够用
不保留旧命令 alias，直接 breaking change

前置依赖

#462 统一 agent detail/turn schema（step read 需要统一的 turn 结构）

涉及文件

packages/cli-workflow/src/commands/thread.ts — 拆分、重命名
packages/cli-workflow/src/commands/step.ts — 新建
packages/cli-workflow/src/cli.ts — 注册新命令组
packages/cli-workflow/src/__tests__/ — 测试更新
所有 workflow YAML 文档（如有 CLI 引用）

## 背景当前 CLI 命令全挤在 `thread` 下，概念混乱： - `thread step` 既是动词（执行）又是名词（步骤） - `thread steps` / `thread step-details` / `thread fork` 操作对象是 step，不是 thread - `list` vs `running` 概念容易混淆 - `kill` 做了停止+归档两件事 - `workflow put` 是 CAS 层语义，用户视角应该是"注册" ## 四层模型 ``` workflow → thread → step → turn 模板定义执行实例单步结果 agent 内部交互 ``` ## 目标命令结构 ``` uwf workflow add <file> # 注册 workflow（原 put） list # 列出已注册的 show <id> # 查看定义 uwf thread start <workflow> -p <text> # 创建 thread exec <thread-id> [-c N] [--background] # 执行（原 thread step） list [--status idle|running] # 合并 list + running，带状态列 show <thread-id> # head + meta read <thread-id> # markdown 渐进式阅读 stop <thread-id> # 停止后台执行 cancel <thread-id> # 放弃 thread，移出活跃列表（原 kill） uwf step list <thread-id> # 列出 thread 的所有 step（原 thread steps） show <step-hash> # step 元信息（role, agent, output, timestamp） read <step-hash> [--before N] # markdown 渐进式阅读 turns（新功能） fork <step-hash> # 从 step 分叉，产出新 thread（原 thread fork） uwf cas get <hash> # 原始 CAS 数据兜底 ``` ## 改动映射 | 旧命令 | 新命令 | 说明 | |--------|--------|------| | `workflow put` | `workflow add` | 语义更准确 | | `thread step <id> -c N` | `thread exec <id> -c N` | 消除名词/动词歧义 | | `thread steps <id>` | `step list <id>` | 归属到 step 层 | | `thread step-details <hash>` | `step show <hash>` | 归属到 step 层 | | `thread fork <hash>` | `step fork <hash>` | 操作对象是 step | | `thread list` + `thread running` | `thread list [--status]` | 合并，带状态列 | | `thread kill` | `thread stop` + `thread cancel` | 拆分：停止执行 vs 放弃 thread | | *(新)* | `step read <hash>` | markdown 渐进式阅读 turns | ## 不做 - turn 不单独建命令组，`step read --before N` + `cas get` 够用 - 不保留旧命令 alias，直接 breaking change ## 前置依赖 - #462 统一 agent detail/turn schema（`step read` 需要统一的 turn 结构） ## 涉及文件 - `packages/cli-workflow/src/commands/thread.ts` — 拆分、重命名 - `packages/cli-workflow/src/commands/step.ts` — 新建 - `packages/cli-workflow/src/cli.ts` — 注册新命令组 - `packages/cli-workflow/src/__tests__/` — 测试更新 - 所有 workflow YAML 文档（如有 CLI 引用）

xiaoju referenced this issue

2026-05-24 10:23:09 +00:00

feat: use git worktree for isolated development in solve-issue workflow #465