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

RFC: Replace extractRefs function with schema-level casRef annotation #285

New Issue
Closed
opened 2026-05-16 10:30:08 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-16 10:30:08 +00:00
Owner
Copy Link
Copy Source

背景

当前 RoleDefinition 中的 extractRefs 是一个函数，用于从 role output 的 meta 中提取 CAS hash 引用。这是 WorkflowDefinition 中除 systemPrompt 和 condition check 之外的第三个不可序列化成员。

实际使用中，extractRefs 的模式非常简单：

  • 大多数 role: null
  • coder: (meta) => [meta.completedPhase]
  • planner: (meta) => meta.status === "planned" ? meta.phases.map(p => p.hash) : []

这些都可以用 schema 上的元数据标注来声明式表达。

目标

用 Zod .meta({ casRef: true }) 标注替代 extractRefs 函数，使 RoleDefinition 少一个函数成员，推动 WorkflowDefinition 更接近纯数据。

设计

Schema 标注

coderSchema: completedPhase 字段加 .meta({ casRef: true })
plannerSchema: 用 discriminatedUnion 区分 planned/failed，phases[].hash 加 .meta({ casRef: true })

运行时自动收集

collectCasRefs(schema, meta) 遍历带 casRef: true meta 标注的 schema，从 meta 对象中递归收集所有对应值。

Descriptor 兼容

casRef 标注在 Zod -> JSON Schema 转换时，作为 x-cas-ref: true 保留到 descriptor 中。

Phase 拆分

Phase 1: 实现 casRef 收集器

  • 写一个 collectCasRefs(schema, meta) 函数
  • 单元测试覆盖：flat field、nested array、discriminated union、null 场景

Phase 2: 迁移现有模板 + 移除 extractRefs

  • 将 develop / solve-issue 模板的 extractRefs 改为 schema 标注
  • ��� RoleDefinition 类型中移除 extractRefs 字段
  • create-workflow.ts 改用 collectCasRefs

Phase 3: Descriptor 增强

  • buildDescriptor 在 JSON Schema 输出中保留 x-cas-ref 标注
  • Dashboard 可展示哪些字段是 CAS ref

完成标准

  • 所有 Phase 的 testing issue 已 close
  • extractRefs 从 RoleDefinition 类型中移除
  • 所有现有 smoke test 通过
## 背景 当前 RoleDefinition 中的 extractRefs 是一个函数，用于从 role output 的 meta 中提取 CAS hash 引用。这是 WorkflowDefinition 中除 systemPrompt 和 condition check 之外的第三个不可序列化成员。 实际使用中，extractRefs 的模式非常简单： - 大多数 role: null - coder: (meta) => [meta.completedPhase] - planner: (meta) => meta.status === "planned" ? meta.phases.map(p => p.hash) : [] 这些都可以用 schema 上的元数据标注来声明式表达。 ## 目标 用 Zod .meta({ casRef: true }) 标注替代 extractRefs 函数，使 RoleDefinition 少一个函数成员，推动 WorkflowDefinition 更接近纯数据。 ## 设计 ### Schema 标注 coderSchema: completedPhase 字段加 .meta({ casRef: true }) plannerSchema: 用 discriminatedUnion 区分 planned/failed，phases[].hash 加 .meta({ casRef: true }) ### 运行时自动收集 collectCasRefs(schema, meta) 遍历带 casRef: true meta 标注的 schema，从 meta 对象中递归收集所有对应值。 ### Descriptor 兼容 casRef 标注在 Zod -> JSON Schema 转换时，作为 x-cas-ref: true 保留到 descriptor 中。 ## Phase 拆分 ### Phase 1: 实现 casRef 收集器 - 写一个 collectCasRefs(schema, meta) 函数 - 单元测试覆盖：flat field、nested array、discriminated union、null 场景 ### Phase 2: 迁移现有模板 + 移除 extractRefs - 将 develop / solve-issue 模板的 extractRefs 改为 schema 标注 - ��� RoleDefinition 类型中移除 extractRefs 字段 - create-workflow.ts 改用 collectCasRefs ### Phase 3: Descriptor 增强 - buildDescriptor 在 JSON Schema 输出中保留 x-cas-ref 标注 - Dashboard 可展示哪些字段是 CAS ref ## 完成标准 - [ ] 所有 Phase 的 testing issue 已 close - [ ] extractRefs 从 RoleDefinition 类型中移除 - [ ] 所有现有 smoke test 通过
xiaomo commented 2026-05-16 11:55:31 +00:00
Owner
Copy Link
Copy Source

All 3 phases merged: #288 → #290 → #292 ✅

All 3 phases merged: #288 → #290 → #292 ✅
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
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#285
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?