16
CLI Refactor · workflow

metadata-driven-cli-refactor

16-metadata-driven-cli-refactor.md
⚙️
P1 source: codex-sessions created: 2026-06-13
◉

WHAT IS THIS

定位

Metadata 驱动的 CLI 重构 workflow。适合 CLI command 大量重复，且后端或 schema 已经能描述工具、参数、输出时使用。

⚡

TRIGGERS

触发场景
▸recruit、hr 等 domain 有重复 command runner。
▸CLI schema、formatter、resolver、audit、confirmation 逻辑散在多个目录。
▸新增 tool 时要手写 command、help、schema、formatter。
▸需要支持 online-first schema cache、offline fallback、structured output。
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT
  • 当前 CLI command tree。
  • API schema 或 metadata endpoint。
  • Formatter、input parser、runner。
  • CLI docs reference。
  • 测试和 build 命令。
↗ OUTPUT
  • Tool registry。
  • Unified runner。
  • Schema cache。
  • Resolver pipeline。
  • Structured formatter。
  • 更新后的 CLI docs。
🪜

STEPS

编排步骤
  1. 1
    建现状地图
    找 command、action、client、schema、formatter 的重复路径。
  2. 2
    统一 client surface
    先把 API client 改成显式 domain 或 canonical contract。
  3. 3
    抽 registry 和 runner
    把输入解析、确认、audit、执行、输出收尾放进共享 runner。
  4. 4
    加 schema cache
    默认 online-first，成功写缓存，失败 fallback。--offline 只读缓存，--refresh 禁止 fallback。
  5. 5
    加 structured formatter
    识别 items/list/records/data 等常见集合，保证 JSON/NDJSON 机器输出不变。
  6. 6
    接 metadata registry
    用 cached schema 注册 command，但保留本地 overlay，比如 examples、description。
  7. 7
    删除旧兼容接口
    rg 搜旧方法，能删就删，不能删写明兼容期限。
  8. 8
    分阶段提交
    每阶段独立 commit，每阶段都跑 test/lint/build。
⚙

AGENT ROLES

Agent 分工
⚙
CLI Mapper
找重复 command 和调用链。
⚙
Contract Agent
统一 client surface。
⚙
Runner Agent
抽 registry 和 runner。
⚙
Cache Agent
实现 schema cache。
⚙
Formatter Agent
实现 structured formatter。
⚙
Docs Agent
更新 CLI reference。
✓

ACCEPTANCE GATE

验收 gate
⊘

FAILURE HANDLING

失败处理
⤳
如果 metadata contract 不稳定，先跑 →#01。
⊘
如果 formatter 改坏机器输出，立即回退 formatter 层，不改 runner。
⊘
如果 schema cache 掩盖线上错误，--refresh 必须能强制失败。
⌘

TEMPLATE

阶段模板
TEMPLATE
| Stage | Goal | Files | Tests | Commit |
| --- | --- | --- | --- | --- |