feat(cli): init command — scaffold local workflow package #36

New Issue

2026-05-07T10:47:18Z

xingyue commented

2026-05-07 10:47:18 +00:00

Summary

新增 uncaged-workflow init 命令，创建本地 workflow 开发 monorepo。

Motivation

目前创建 workflow 需要手动搭建 bun package、配置 dependencies、写 boilerplate。缺少标准化的脚手架，导致：

新手不知道从哪开始
Coding agent（Cursor/Hermes）缺少 instructions，不知道如何开发 workflow
没有统一的文件结构和 build 流程

Design

核心概念

Workspace — bun monorepo，包含多个 template 和一个 workflows 实例包
Template — 独立 package，纯数据（roles + moderator + WorkflowDefinition），不绑 agent，可发布共享
Workflow 实例 — workflows 包里的一个文件，import template + bind agent + export run + descriptor。就几行代码，手写即可

生成的 Workspace 结构

my-workflows/
├── package.json                  # bun workspace
├── biome.json
├── tsconfig.json
├── AGENTS.md                     # coding agent instructions
├── templates/
│   ├── review-pr/                # template package（独立发布）
│   │   ├── package.json          # @my/workflow-template-review-pr
│   │   └── src/
│   │       ├── roles.ts          # RoleMeta type + RoleDefinition
│   │       ├── moderator.ts      # pure routing function
│   │       └── index.ts          # export WorkflowDefinition
│   └── deploy-service/
│       └── ...
├── workflows/
│   ├── package.json              # 单个 package，依赖 template + agent 包
│   └── src/
│       ├── review-pr.ts          # 一个文件 = 一个实例（手写）
│       └── solve-issue.ts        # 也可以实例化别人发布的 template
└── dist/
    ├── review-pr.esm.js          # build 输出，per-file
    └── solve-issue.esm.js

实例文件示例（手写，不需要 CLI 生成）

// workflows/src/review-pr.ts
import { reviewPrDefinition } from "@my/workflow-template-review-pr";
import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
import { createWorkflow, createExtract } from "@uncaged/workflow";

export const descriptor = { /* from template */ };
export const run = createWorkflow(
  reviewPrDefinition,
  { agent: createCursorAgent() },
  createExtract({ baseUrl: "...", apiKey: "...", model: "..." }),
);

CLI 接口

# 初始化 workspace monorepo
uncaged-workflow init workspace my-workflows

# 在 workspace 里添加一个新 template
uncaged-workflow init template review-pr

# build 所有实例 → dist/*.esm.js
uncaged-workflow build

AGENTS.md

给 Cursor / Hermes 等 coding agent 的开发指南，内容从 CLAUDE.md + architecture.md 精炼：

项目结构 — workspace / template / workflow 实例的职责
核心概念 — Role（pure data）、Moderator（pure routing）、Agent（runtime binding）、ExtractFn
开发流程 — 定义 RoleMeta → 写 RoleDefinition → 写 Moderator → 手写实例文件绑定 agent
编码规范 — functional-first, type not interface, no ?:, no class, Crockford Base32 log tags
Template 复用 — 如何基于已有 template 修改，如何发布共享
Build & Test — bun run check → bun test → uncaged-workflow build → uncaged-workflow add
常见陷阱 — no dynamic import, no default export, no console.log

Template 机制

Template = 独立 package，导出 WorkflowDefinition（roles + moderator），不包含 agent binding
可以复用已发布的 template（如 @uncaged/workflow-template-solve-issue）
也可以在本地 templates/ 下开发自己的
所有 workflow 建议通过 template 构建，方便后续发布共享

Implementation Notes

init 命令放在 cli-workflow 包里，新增 cmd-init.ts
两个子命令：init workspace、init template
init workspace 生成 root package.json（workspace 配置）、biome.json、tsconfig.json、AGENTS.md、workflows/ package
init template 在 templates/ 下创建新 package，生成 roles/moderator/index boilerplate
生成的 workspace 应该能直接 bun install 跑通

Acceptance Criteria

uncaged-workflow init workspace <name> 生成可用的 monorepo
uncaged-workflow init template <name> 在 workspace 内创建 template package
workspace 内 bun install 成功
AGENTS.md 内容完整，coding agent 能据此独立开发
有测试覆盖

## Summary 新增 `uncaged-workflow init` 命令，创建本地 workflow 开发 monorepo。 ## Motivation 目前创建 workflow 需要手动搭建 bun package、配置 dependencies、写 boilerplate。缺少标准化的脚手架，导致： - 新手不知道从哪开始 - Coding agent（Cursor/Hermes）缺少 instructions，不知道如何开发 workflow - 没有统一的文件结构和 build 流程 ## Design ### 核心概念 - **Workspace** — bun monorepo，包含多个 template 和一个 workflows 实例包 - **Template** — 独立 package，纯数据（roles + moderator + WorkflowDefinition），不绑 agent，可发布共享 - **Workflow 实例** — workflows 包里的一个文件，import template + bind agent + export `run` + `descriptor`。就几行代码，手写即可 ### 生成的 Workspace 结构 ``` my-workflows/ ├── package.json # bun workspace ├── biome.json ├── tsconfig.json ├── AGENTS.md # coding agent instructions ├── templates/ │ ├── review-pr/ # template package（独立发布） │ │ ├── package.json # @my/workflow-template-review-pr │ │ └── src/ │ │ ├── roles.ts # RoleMeta type + RoleDefinition │ │ ├── moderator.ts # pure routing function │ │ └── index.ts # export WorkflowDefinition │ └── deploy-service/ │ └── ... ├── workflows/ │ ├── package.json # 单个 package，依赖 template + agent 包 │ └── src/ │ ├── review-pr.ts # 一个文件 = 一个实例（手写） │ └── solve-issue.ts # 也可以实例化别人发布的 template └── dist/ ├── review-pr.esm.js # build 输出，per-file └── solve-issue.esm.js ``` ### 实例文件示例（手写，不需要 CLI 生成） ```typescript // workflows/src/review-pr.ts import { reviewPrDefinition } from "@my/workflow-template-review-pr"; import { createCursorAgent } from "@uncaged/workflow-agent-cursor"; import { createWorkflow, createExtract } from "@uncaged/workflow"; export const descriptor = { /* from template */ }; export const run = createWorkflow( reviewPrDefinition, { agent: createCursorAgent() }, createExtract({ baseUrl: "...", apiKey: "...", model: "..." }), ); ``` ### CLI 接口 ```bash # 初始化 workspace monorepo uncaged-workflow init workspace my-workflows # 在 workspace 里添加一个新 template uncaged-workflow init template review-pr # build 所有实例 → dist/*.esm.js uncaged-workflow build ``` ### AGENTS.md 给 Cursor / Hermes 等 coding agent 的开发指南，内容从 CLAUDE.md + architecture.md 精炼： 1. **项目结构** — workspace / template / workflow 实例的职责 2. **核心概念** — Role（pure data）、Moderator（pure routing）、Agent（runtime binding）、ExtractFn 3. **开发流程** — 定义 RoleMeta → 写 RoleDefinition → 写 Moderator → 手写实例文件绑定 agent 4. **编码规范** — functional-first, type not interface, no ?:, no class, Crockford Base32 log tags 5. **Template 复用** — 如何基于已有 template 修改，如何发布共享 6. **Build & Test** — `bun run check` → `bun test` → `uncaged-workflow build` → `uncaged-workflow add` 7. **常见陷阱** — no dynamic import, no default export, no console.log ### Template 机制 - Template = 独立 package，导出 `WorkflowDefinition`（roles + moderator），不包含 agent binding - 可以复用已发布的 template（如 `@uncaged/workflow-template-solve-issue`） - 也可以在本地 `templates/` 下开发自己的 - 所有 workflow 建议通过 template 构建，方便后续发布共享 ## Implementation Notes - `init` 命令放在 `cli-workflow` 包里，新增 `cmd-init.ts` - 两个子命令：`init workspace`、`init template` - `init workspace` 生成 root package.json（workspace 配置）、biome.json、tsconfig.json、AGENTS.md、workflows/ package - `init template` 在 `templates/` 下创建新 package，生成 roles/moderator/index boilerplate - 生成的 workspace 应该能直接 `bun install` 跑通 ## Acceptance Criteria - [ ] `uncaged-workflow init workspace <name>` 生成可用的 monorepo - [ ] `uncaged-workflow init template <name>` 在 workspace 内创建 template package - [ ] workspace 内 `bun install` 成功 - [ ] AGENTS.md 内容完整，coding agent 能据此独立开发 - [ ] 有测试覆盖

xingyue referenced this issue

2026-05-07 13:15:37 +00:00

#36 Phase 1 Testing: init workspace — 生成 monorepo 骨架 #46

xingyue referenced this issue

2026-05-07 13:15:39 +00:00

#36 Phase 2 Testing: init template — 创建 template package #47

xingyue referenced this issue

2026-05-07 13:15:41 +00:00

#36 Phase 3 Testing: AGENTS.md — coding agent 开发指南 #48

xingyue commented

2026-05-07 13:15:56 +00:00

Phase 拆分

## Phase 拆分 ### Phase 1: `init workspace` — 生成 monorepo 骨架 - Testing issue: #46 ### Phase 2: `init template` — 创建 template package - Testing issue: #47 ### Phase 3: AGENTS.md — coding agent 开发指南 - Testing issue: #48

xiaomo referenced this issue

2026-05-07 13:33:42 +00:00

rfc(cli): 子命令按资源域分组重组 #54