uncaged/nerve
Archived
10
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: replace WorkflowSpec/compileWorkflowSpec with simple createRole helper #252

New Issue
Closed
opened 2026-04-29 09:49:07 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-04-29 09:49:07 +00:00
Owner
Copy Link
Copy Source

Background

We over-engineered the RFC-003 config layer. WorkflowSpec, RoleSpec, and compileWorkflowSpec add unnecessary abstraction on top of WorkflowDefinition / Role, which were already fine.

What we actually need is one helper function:

function createRole<M>(
  adapter: AgentFn,
  prompt: PromptInput,
  meta: ZodSchema<M>,
  extract: LlmExtractor,
): Role<M>

Workflows become simple factory functions that accept agents + extractor config:

export function createSolveIssueWorkflow(opts: {
  agents: { coder: AgentFn; reviewer: AgentFn },
  extractor: LlmExtractor,
}) {
  return {
    name: 'solve-issue',
    roles: {
      coder: createRole(opts.agents.coder, coderPrompt, coderSchema, opts.extractor),
      reviewer: createRole(opts.agents.reviewer, reviewPrompt, reviewSchema, opts.extractor),
    },
    moderator,
  } satisfies WorkflowDefinition<...>;
}

Changes Required

1. Delete from @uncaged/nerve-core

  • WorkflowSpec type
  • RoleSpec type
  • PromptInput type (move to workflow-utils if still needed)
  • Any exports related to these

2. Delete from @uncaged/nerve-daemon

  • compileWorkflowSpec function and its types (CompileWorkflowSpecDeps)
  • compile-workflow-spec.ts file and tests
  • Remove from daemon index exports

3. Add to @uncaged/nerve-workflow-utils

  • createRole<M>(adapter, prompt, meta, extract): Role<M> — the one helper
    • adapter: AgentFn — direct function reference
    • prompt: string | ((start, messages) => Promise<string>)
    • meta: zod schema for extraction
    • extract: { provider: string; model: string; apiKey: string; baseUrl: string } or similar LlmExtractor config
    • Returns Role<M> — resolves prompt, calls adapter, extracts meta, returns { content, meta }

4. Update workspace workflows (~/.uncaged-nerve)

  • Each workflow becomes a factory: createXxxWorkflow({ agents, extractor })
  • index.ts calls factory with concrete adapters and extractor config
  • No more importing compile/WorkflowSpec/RoleSpec

5. Keep unchanged

  • WorkflowDefinition / Role types — untouched
  • AgentFn + adapter packages — untouched
  • zodMeta helper — may still be useful inside createRole

Ref

Supersedes the WorkflowSpec parts of RFC-003. Adapter packages and knowledge layer remain valid.

小橘 🍊（NEKO Team）

## Background We over-engineered the RFC-003 config layer. `WorkflowSpec`, `RoleSpec`, and `compileWorkflowSpec` add unnecessary abstraction on top of `WorkflowDefinition` / `Role`, which were already fine. What we actually need is one helper function: ```ts function createRole<M>( adapter: AgentFn, prompt: PromptInput, meta: ZodSchema<M>, extract: LlmExtractor, ): Role<M> ``` Workflows become simple factory functions that accept agents + extractor config: ```ts export function createSolveIssueWorkflow(opts: { agents: { coder: AgentFn; reviewer: AgentFn }, extractor: LlmExtractor, }) { return { name: 'solve-issue', roles: { coder: createRole(opts.agents.coder, coderPrompt, coderSchema, opts.extractor), reviewer: createRole(opts.agents.reviewer, reviewPrompt, reviewSchema, opts.extractor), }, moderator, } satisfies WorkflowDefinition<...>; } ``` ## Changes Required ### 1. Delete from `@uncaged/nerve-core` - `WorkflowSpec` type - `RoleSpec` type - `PromptInput` type (move to workflow-utils if still needed) - Any exports related to these ### 2. Delete from `@uncaged/nerve-daemon` - `compileWorkflowSpec` function and its types (`CompileWorkflowSpecDeps`) - `compile-workflow-spec.ts` file and tests - Remove from daemon index exports ### 3. Add to `@uncaged/nerve-workflow-utils` - `createRole<M>(adapter, prompt, meta, extract): Role<M>` — the one helper - `adapter`: `AgentFn` — direct function reference - `prompt`: `string | ((start, messages) => Promise<string>)` - `meta`: zod schema for extraction - `extract`: `{ provider: string; model: string; apiKey: string; baseUrl: string }` or similar LlmExtractor config - Returns `Role<M>` — resolves prompt, calls adapter, extracts meta, returns `{ content, meta }` ### 4. Update workspace workflows (`~/.uncaged-nerve`) - Each workflow becomes a factory: `createXxxWorkflow({ agents, extractor })` - `index.ts` calls factory with concrete adapters and extractor config - No more importing compile/WorkflowSpec/RoleSpec ### 5. Keep unchanged - `WorkflowDefinition` / `Role` types — untouched - `AgentFn` + adapter packages — untouched - `zodMeta` helper — may still be useful inside createRole ## Ref Supersedes the WorkflowSpec parts of RFC-003. Adapter packages and knowledge layer remain valid. 小橘 🍊（NEKO Team）
This repo is archived. You cannot comment on issues.
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
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/nerve#252
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?