uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(cli): cli-workflow 模块化改进 #90

New Issue
Closed
opened 2026-05-07 16:15:58 +00:00 by xingyue · 1 comment
xingyue commented 2026-05-07 16:15:58 +00:00
Owner
Copy Link
Copy Source

What

cli-workflow 包的模块化审查，发现若干结构性问题需要改进。

Why

当前代码存在重复逻辑、职责混杂的模块、以及不一致的模式，影响可维护性和扩展性。

Changes Proposed

🔴 高优先级

1. cli-dispatch.ts 是 777 行的"上帝模块"

  • 混合了命令路由、参数校验、输出格式化、usage 渲染、deprecation 处理
  • 违反 "one module = one responsibility"
  • 建议拆分为：cli-usage.ts、cli-command-table.ts、精简的 cli-dispatch.ts

2. cmd-kill.ts / cmd-pause.ts / cmd-resume.ts 是复制粘贴的克隆体

  • 三个文件各 43 行，逻辑完全一致，只有命令类型字符串不同
  • 建议提取 sendThreadControlCommand 到 worker-spawn.ts

3. dispatch wrapper 工厂化

  • 大量 dispatch 函数遵循相同模式：校验参数 → 调用 cmd → 处理 Result → 输出
  • 可以用高阶函数工厂砍掉 ~200 行重复代码

🟡 中优先级

4. argv 解析位置不一致

  • run-argv.ts / live-argv.ts 是独立模块 ✅
  • cmd-add.ts、cmd-fork.ts、cmd-threads.ts 内嵌解析 ❌
  • 建议统一模式

5. Worker 控制文件读取重复

  • 读取 workers/{hash}.json 的模式分散在 4 个文件中
  • 建议提取 readWorkerCtl 到 worker-spawn.ts

🟢 低优先级

6. bundle-store.ts 重复定义 pathExists — fs-utils.ts 已导出，应直接 import

7. thread-scan.ts 首行解析重复 — 可提取 readFirstLineField 通用函数

8. cmd-live.ts 颜色工具可提取到 cli-color.ts

9. cmd-init.ts 模板内容可分离到 init-templates.ts

10. cmd-cas.ts 的 _threadId 参数 — 四个函数都未使用，属残留参数

优先级总结

优先级 改进项 预估收益
🔴 HIGH kill/pause/resume 去重 ~80 行重复
🔴 HIGH 拆分 cli-dispatch.ts 可维护性大幅提升
🟡 MED dispatch wrapper 工厂化 ~200 行
🟡 MED argv 解析模式统一 规范一致性
🟡 MED worker ctl 读取去重 ~40 行
🟢 LOW 其余 5 项 代码整洁度

Ref

代码审查由 @xingyue 完成

## What `cli-workflow` 包的模块化审查，发现若干结构性问题需要改进。 ## Why 当前代码存在重复逻辑、职责混杂的模块、以及不一致的模式，影响可维护性和扩展性。 ## Changes Proposed ### 🔴 高优先级 **1. `cli-dispatch.ts` 是 777 行的"上帝模块"** - 混合了命令路由、参数校验、输出格式化、usage 渲染、deprecation 处理 - 违反 "one module = one responsibility" - 建议拆分为：`cli-usage.ts`、`cli-command-table.ts`、精简的 `cli-dispatch.ts` **2. `cmd-kill.ts` / `cmd-pause.ts` / `cmd-resume.ts` 是复制粘贴的克隆体** - 三个文件各 43 行，逻辑完全一致，只有命令类型字符串不同 - 建议提取 `sendThreadControlCommand` 到 `worker-spawn.ts` **3. dispatch wrapper 工厂化** - 大量 dispatch 函数遵循相同模式：校验参数 → 调用 cmd → 处理 Result → 输出 - 可以用高阶函数工厂砍掉 ~200 行重复代码 ### 🟡 中优先级 **4. argv 解析位置不一致** - `run-argv.ts` / `live-argv.ts` 是独立模块 ✅ - `cmd-add.ts`、`cmd-fork.ts`、`cmd-threads.ts` 内嵌解析 ❌ - 建议统一模式 **5. Worker 控制文件读取重复** - 读取 `workers/{hash}.json` 的模式分散在 4 个文件中 - 建议提取 `readWorkerCtl` 到 `worker-spawn.ts` ### 🟢 低优先级 **6. `bundle-store.ts` 重复定义 `pathExists`** — `fs-utils.ts` 已导出，应直接 import **7. `thread-scan.ts` 首行解析重复** — 可提取 `readFirstLineField` 通用函数 **8. `cmd-live.ts` 颜色工具可提取到 `cli-color.ts`** **9. `cmd-init.ts` 模板内容可分离到 `init-templates.ts`** **10. `cmd-cas.ts` 的 `_threadId` 参数** — 四个函数都未使用，属残留参数 ## 优先级总结 | 优先级 | 改进项 | 预估收益 | |---|---|---| | 🔴 HIGH | kill/pause/resume 去重 | ~80 行重复 | | 🔴 HIGH | 拆分 cli-dispatch.ts | 可维护性大幅提升 | | 🟡 MED | dispatch wrapper 工厂化 | ~200 行 | | 🟡 MED | argv 解析模式统一 | 规范一致性 | | 🟡 MED | worker ctl 读取去重 | ~40 行 | | 🟢 LOW | 其余 5 项 | 代码整洁度 | ## Ref 代码审查由 @xingyue 完成
xingyue commented 2026-05-07 16:18:52 +00:00
Author
Owner
Copy Link
Copy Source

补充：按一级子命令聚合源码目录结构

当前所有 cmd-*.ts 平铺在 src/ 下，15+ 个文件没有体现它们所属的一级子命令分组。

现状

src/
  cmd-add.ts        # workflow add
  cmd-list.ts       # workflow list
  cmd-show.ts       # workflow show
  cmd-remove.ts     # workflow rm
  cmd-history.ts    # workflow history
  cmd-rollback.ts   # workflow rollback
  cmd-run.ts        # thread run
  cmd-threads.ts    # thread list
  cmd-thread.ts     # thread show / thread rm
  cmd-fork.ts       # thread fork
  cmd-ps.ts         # thread ps
  cmd-kill.ts       # thread kill
  cmd-pause.ts      # thread pause
  cmd-resume.ts     # thread resume
  cmd-live.ts       # thread live
  cmd-cas.ts        # cas get/put/list/rm
  cmd-gc.ts         # cas gc
  cmd-init.ts       # init workspace/template
  cmd-help.ts       # skill/help

文件名看不出属于哪个组，随着命令增多会越来越混乱。

建议

按一级子命令建目录：

src/
  commands/
    workflow/
      add.ts
      list.ts
      show.ts
      remove.ts
      history.ts
      rollback.ts
      index.ts          # re-export + subcommand table
    thread/
      run.ts
      list.ts
      show.ts
      remove.ts
      fork.ts
      ps.ts
      kill.ts           # (或合并 kill/pause/resume → control.ts)
      pause.ts
      resume.ts
      live.ts
      index.ts
    cas/
      get.ts
      put.ts
      list.ts
      rm.ts
      gc.ts
      index.ts
    init/
      workspace.ts
      template.ts
      templates.ts      # 模板字符串数据
      index.ts
  cli.ts
  cli-dispatch.ts       # 只做顶层路由，子命令表在各组 index.ts 里
  cli-output.ts
  cli-usage.ts

收益

  1. 目录即文档 — 一眼看出命令分组结构
  2. 职责边界清晰 — 每组的 index.ts 自带子命令表，cli-dispatch.ts 只组合各组
  3. 扩展友好 — 新增子命令只需在对应组目录加文件 + 注册
  4. 与 cli-dispatch.ts 拆分配合 — 子命令表从 dispatch 下沉到各组，dispatch 瘦身

这和 #90 的 dispatch 拆分改进是天然配合的。

## 补充：按一级子命令聚合源码目录结构 当前所有 `cmd-*.ts` 平铺在 `src/` 下，15+ 个文件没有体现它们所属的一级子命令分组。 ### 现状 ``` src/ cmd-add.ts # workflow add cmd-list.ts # workflow list cmd-show.ts # workflow show cmd-remove.ts # workflow rm cmd-history.ts # workflow history cmd-rollback.ts # workflow rollback cmd-run.ts # thread run cmd-threads.ts # thread list cmd-thread.ts # thread show / thread rm cmd-fork.ts # thread fork cmd-ps.ts # thread ps cmd-kill.ts # thread kill cmd-pause.ts # thread pause cmd-resume.ts # thread resume cmd-live.ts # thread live cmd-cas.ts # cas get/put/list/rm cmd-gc.ts # cas gc cmd-init.ts # init workspace/template cmd-help.ts # skill/help ``` 文件名看不出属于哪个组，随着命令增多会越来越混乱。 ### 建议 按一级子命令建目录： ``` src/ commands/ workflow/ add.ts list.ts show.ts remove.ts history.ts rollback.ts index.ts # re-export + subcommand table thread/ run.ts list.ts show.ts remove.ts fork.ts ps.ts kill.ts # (或合并 kill/pause/resume → control.ts) pause.ts resume.ts live.ts index.ts cas/ get.ts put.ts list.ts rm.ts gc.ts index.ts init/ workspace.ts template.ts templates.ts # 模板字符串数据 index.ts cli.ts cli-dispatch.ts # 只做顶层路由，子命令表在各组 index.ts 里 cli-output.ts cli-usage.ts ``` ### 收益 1. **目录即文档** — 一眼看出命令分组结构 2. **职责边界清晰** — 每组的 `index.ts` 自带子命令表，`cli-dispatch.ts` 只组合各组 3. **扩展友好** — 新增子命令只需在对应组目录加文件 + 注册 4. **与 `cli-dispatch.ts` 拆分配合** — 子命令表从 dispatch 下沉到各组，dispatch 瘦身 这和 #90 的 dispatch 拆分改进是天然配合的。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#90
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?