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

refactor: add only accepts .esm.js, extracts descriptor from bundle export #8

New Issue
Closed
opened 2026-05-06 06:32:24 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-05-06 06:32:24 +00:00
Owner
Copy Link
Copy Source

背景

当前 add 同时支持 .ts 和 .esm.js 输入，内建了 build pipeline。应该简化：add 只接受 .esm.js bundle，build 留给用户工具链。

同时，bundle 的契约从"只 export default"改为"export default + export const descriptor"。add 时动态 import bundle 提取 descriptor，写成 .yaml。

新的 Bundle 契约

Bundle 必须导出两样东西：

// WorkflowFn — AsyncGenerator
export default async function* (input, options) {
  yield { role: "planner", content: "...", meta: {} };
  return { returnCode: 0, summary: "done" };
};

// Descriptor — 描述 workflow 的 roles 和 schema
export const descriptor = {
  description: "Solve issues automatically",
  roles: {
    planner: {
      description: "Creates a plan",
      schema: { type: "object", properties: { plan: { type: "string" } } },
    },
  },
};

add 命令新流程

uncaged-workflow add solve-issue solve-issue.esm.js [--types solve-issue.d.ts]
  1. 验证 .esm.js 后缀
  2. 验证单文件 ESM 约束（现有 validateWorkflowBundle）
  3. 动态 import bundle：检查 default export 是 function + descriptor named export 存在且合法
  4. 提取 descriptor → 序列化为 YAML → 写 {hash}.yaml
  5. 复制 bundle → {hash}.esm.js
  6. 如果同目录有同名 .d.ts 或 --types 指定 → 复制为 {hash}.d.ts（可选）
  7. XXH64 hash + 注册到 workflow.yaml

错误情况

  • 缺少 default export → 报错
  • default export 不是 function → 报错
  • 缺少 descriptor export → 报错
  • descriptor 格式不合法（缺 description 或 roles）→ 报错

需要改什么

删除

  • packages/workflow/src/build-pipeline.ts — 移除内建 build pipeline
  • packages/workflow/src/generate-types.ts — 不再自动生成 .d.ts
  • packages/workflow/src/json-schema-to-ts.ts — 不再需要
  • packages/cli-workflow/src/add-argv.ts — 简化参数解析
  • 相关测试

新增/修改

  • packages/workflow/src/bundle-validator.ts — 增加 descriptor export 验证（动态 import 后检查）
  • packages/workflow/src/extract-descriptor.ts — 动态 import bundle，提取 descriptor，验证格式
  • packages/cli-workflow/src/cmd-add.ts — 只接受 .esm.js，调用 extract-descriptor
  • packages/cli-workflow/src/bundle-store.ts — 存储 .esm.js + .yaml + 可选 .d.ts

更新文档

  • CLAUDE.md — 更新 bundle 契约描述
  • docs/rfc-001-workflow-engine.md Section 2 — 增加 descriptor export 要求
  • 在 docs/ 或 examples/ 里写构建指南

更新示例

  • examples/hello-world.ts — 增加 export const descriptor
  • 在 README 或 docs 里给出 bun build 命令示例

验证标准

  • uncaged-workflow add 只接受 .esm.js（.ts 输入报错）
  • add 时自动从 bundle 提取 descriptor → 写 .yaml
  • 缺少 descriptor export 时报错
  • .d.ts 可选
  • 示例 workflow 能构建 + add + run 端到端
  • bun test 全部通过
  • bunx biome check . 无错误
## 背景 当前 `add` 同时支持 `.ts` 和 `.esm.js` 输入，内建了 build pipeline。应该简化：`add` 只接受 `.esm.js` bundle，build 留给用户工具链。 同时，bundle 的契约从"只 export default"改为"export default + export const descriptor"。`add` 时动态 import bundle 提取 descriptor，写成 `.yaml`。 ## 新的 Bundle 契约 Bundle 必须导出两样东西： ```typescript // WorkflowFn — AsyncGenerator export default async function* (input, options) { yield { role: "planner", content: "...", meta: {} }; return { returnCode: 0, summary: "done" }; }; // Descriptor — 描述 workflow 的 roles 和 schema export const descriptor = { description: "Solve issues automatically", roles: { planner: { description: "Creates a plan", schema: { type: "object", properties: { plan: { type: "string" } } }, }, }, }; ``` ## `add` 命令新流程 ```bash uncaged-workflow add solve-issue solve-issue.esm.js [--types solve-issue.d.ts] ``` 1. 验证 `.esm.js` 后缀 2. 验证单文件 ESM 约束（现有 `validateWorkflowBundle`） 3. **动态 import bundle**：检查 default export 是 function + `descriptor` named export 存在且合法 4. 提取 `descriptor` → 序列化为 YAML → 写 `{hash}.yaml` 5. 复制 bundle → `{hash}.esm.js` 6. 如果同目录有同名 `.d.ts` 或 `--types` 指定 → 复制为 `{hash}.d.ts`（可选） 7. XXH64 hash + 注册到 `workflow.yaml` ### 错误情况 - 缺少 default export → 报错 - default export 不是 function → 报错 - 缺少 `descriptor` export → 报错 - `descriptor` 格式不合法（缺 description 或 roles）→ 报错 ## 需要改什么 ### 删除 - `packages/workflow/src/build-pipeline.ts` — 移除内建 build pipeline - `packages/workflow/src/generate-types.ts` — 不再自动生成 .d.ts - `packages/workflow/src/json-schema-to-ts.ts` — 不再需要 - `packages/cli-workflow/src/add-argv.ts` — 简化参数解析 - 相关测试 ### 新增/修改 - `packages/workflow/src/bundle-validator.ts` — 增加 descriptor export 验证（动态 import 后检查） - `packages/workflow/src/extract-descriptor.ts` — 动态 import bundle，提取 descriptor，验证格式 - `packages/cli-workflow/src/cmd-add.ts` — 只接受 .esm.js，调用 extract-descriptor - `packages/cli-workflow/src/bundle-store.ts` — 存储 .esm.js + .yaml + 可选 .d.ts ### 更新文档 - `CLAUDE.md` — 更新 bundle 契约描述 - `docs/rfc-001-workflow-engine.md` Section 2 — 增加 descriptor export 要求 - 在 docs/ 或 examples/ 里写构建指南 ### 更新示例 - `examples/hello-world.ts` — 增加 `export const descriptor` - 在 README 或 docs 里给出 bun build 命令示例 ## 验证标准 - [ ] `uncaged-workflow add` 只接受 .esm.js（.ts 输入报错） - [ ] add 时自动从 bundle 提取 descriptor → 写 .yaml - [ ] 缺少 descriptor export 时报错 - [ ] .d.ts 可选 - [ ] 示例 workflow 能构建 + add + run 端到端 - [ ] `bun test` 全部通过 - [ ] `bunx biome check .` 无错误
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#8
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?