wf

Snailuu 的 Trellis workflow overlay 管理 CLI —— 给已初始化的 Trellis 项目覆盖/同步私有通用工作流。

相关仓库(私有):

• snailuu/workflow-overlay —— workflow.md 定制 + hooks + Matt Pocock 思考纪律 + Spec Kit 风格 Trellis-native 关卡
• snailuu/specs —— gRPC/Event Go 微服务 + React H5 spec 骨架；由官方 trellis init --template/--registry 读取,wf 不再复制

职责边界

wf 只管理 workflow overlay:

• 覆盖 / 同步 .trellis/workflow.md
• 覆盖 / 同步 .trellis/config.yaml
• 同步 overlay 独有 skills
• 记录当前项目使用的 overlay commit

wf 不管理 spec template / registry:

• 不 clone snailuu/specs
• 不复制 .trellis/spec/
• 不提供 template 选择器
• 不更新项目内已沉淀的 spec 内容

spec 初始化请直接使用官方 Trellis:

trellis init --template <template-id> --registry <registry-source>

前置条件

1. Node.js 20+
2. npm i -g @mindfoldhq/trellis(官方 Trellis CLI)
3. GitHub HTTPS 凭证已配好(至少能读取 snailuu/workflow-overlay)

安装

推荐从 npm 安装:

npm i -g @snailuu/wf

也可以用一次性执行方式:

npx @snailuu/wf --help

本地开发时通过 pnpm link 使用:

cd wf && pnpm install && pnpm build && pnpm link --global

之后在任意目录都可以直接跑 wf 命令。修改代码后重新 pnpm build,link 关系不需要重建。

命令

| 命令 | 说明 | |---|---| | wf init [--template <name>] [--registry <source>] | 兼容入口:代跑官方 trellis init,再应用 overlay；template/registry 仅透传给 Trellis | | wf sync [--update] | 老项目升级 workflow / config / skills(不动 spec / tasks);--update 仅兼容旧习惯,现在默认实时获取远程 overlay | | wf update | 检查 GitHub 上最新 overlay 是否可获取(不落地缓存) | | wf status | 显示当前项目 + 远程版本 + 差异 | | wf doctor | 环境自检(trellis / git / overlay 仓库可达性) |

场景

新项目

推荐把 spec 初始化交给官方 Trellis,再用 wf 覆盖工作流:

mkdir my-new-service && cd my-new-service
git init
trellis init --codex --claude \
  --template go-microservice \
  --registry gh:snailuu/specs
wf sync

如果仍想使用兼容入口,wf init 只会把 template/registry 透传给官方 Trellis:

wf init --template go-microservice --registry gh:snailuu/specs

老项目升级

cd ~/some-project
wf update                          # 可选:检查远程仓库权限/最新 commit
wf sync                            # 实时获取 GitHub overlay 并应用到当前项目

一步搞定:

wf sync

wf sync --update 为兼容旧习惯仍可用,但现在 sync 本身每次都会实时获取 GitHub 最新 overlay。

状态检查

wf status

输出示例:

▶ 项目 /path/to/project
  overlay commit: f13fd58
  updated at:     2026-07-02T...

▶ 远程 GitHub overlay
  overlay: ✓ (f13fd58)

▶ 差异 项目 vs 远程 overlay
  workflow.md: 一致
  config.yaml: 一致

环境变量

| 变量 | 说明 | |---|---| | WF_OVERLAY_REPO | 覆盖默认 overlay 仓库 URL(便于测试) | | WF_OVERLAY_REF | 可选:锁定 overlay 的 branch / tag / commit |

wf init / wf sync / wf status / wf update 都会实时从 GitHub 获取 overlay 到临时目录,命令结束后自动清理;不要求用户预先下载 overlay 到本地缓存。生产/团队环境建议通过 WF_OVERLAY_REF 锁定 tag 或 commit,避免实时 main 分支变动直接影响项目初始化/同步。

spec registry/template 的 source/ref 由官方 Trellis CLI 管理,例如 trellis init --template <name> --registry <source>。

目录结构

wf/
├─ src/
│  ├─ cli.ts              入口(citty 注册所有命令)
│  ├─ commands/           init / sync / update / status / doctor
│  ├─ core/               config / source / git / trellis / overlay
│  ├─ ui/                 log(彩色) + prompts(@clack 封装)
│  └─ utils/              fs + hash
├─ tsup.config.ts
└─ package.json

开发

pnpm dev                  # tsup watch 模式
pnpm build                # 构建 dist/cli.js
pnpm typecheck            # tsc --noEmit

陷阱

• 别在项目里改 .trellis/workflow.md —— wf sync 会覆盖(有 .bak.<ts> 备份)。想改回 overlay 仓库改一次,所有项目共享。
• config.yaml 是规范类文件 —— wf sync 会备份后覆盖。需要改统一行为时回 overlay 仓库改一次。
• spec 是活文档 —— wf sync 不动 spec。初始化和模板选择交给官方 trellis init --template/--registry。

未来路线(v0.2+)

• wf overlay apply / wf overlay sync —— 更明确地区分 overlay 管理和 Trellis 初始化
• wf sync-all —— 扫描 ~/project/ 下所有 wf 项目批量 sync