feat: Role 四段式描述 (identity/prepare/execute/report) #361

2026-05-21T01:41:54Z

xiaoju commented

2026-05-21 01:41:54 +00:00

What

扩展 RoleDefinition，新增 identity/prepare/execute/report 四段式字段。

Why

Agent 需要区分准备阶段（加载 skill）、执行阶段和汇报阶段。不同 agent 适配同一个 workflow 时，需要结构化的 role 描述。(#359)

Changes

workflow-protocol/types.ts — RoleDefinition 新增 4 字段（string | null），systemPrompt 改为可选
workflow-protocol/schemas.ts — ROLE_DEFINITION schema 更新，新字段均为 optional
cli-workflow/validate.ts — 放宽校验，接受新字段
cli-workflow/commands/workflow.ts — materialize 时 strip null 字段
cli-workflow/commands/thread.ts — read 时优先显示 identity
cli-workflow/cli.ts — 加 --version 从 package.json 读取
所有 package 版本统一 0.5.0

Ref

Refs #359, #360

## What 扩展 RoleDefinition，新增 identity/prepare/execute/report 四段式字段。 ## Why Agent 需要区分准备阶段（加载 skill）、执行阶段和汇报阶段。不同 agent 适配同一个 workflow 时，需要结构化的 role 描述。(#359) ## Changes - `workflow-protocol/types.ts` — RoleDefinition 新增 4 字段（string | null），systemPrompt 改为可选 - `workflow-protocol/schemas.ts` — ROLE_DEFINITION schema 更新，新字段均为 optional - `cli-workflow/validate.ts` — 放宽校验，接受新字段 - `cli-workflow/commands/workflow.ts` — materialize 时 strip null 字段 - `cli-workflow/commands/thread.ts` — read 时优先显示 identity - `cli-workflow/cli.ts` — 加 --version 从 package.json 读取 - 所有 package 版本统一 0.5.0 ## Ref Refs #359, #360

xiaoju added 1 commit 2026-05-21 01:41:54 +00:00

feat: add four-phase role description (identity/prepare/execute/report) fc7d482b4f

- Extend RoleDefinition with identity, prepare, execute, report fields
- Make systemPrompt optional (nullable) for four-phase workflows
- Update ROLE_DEFINITION JSON Schema (all new fields optional)
- Update validate.ts to accept new fields
- Update workflow.ts to strip null fields before CAS storage
- Update thread read to prefer identity over systemPrompt
- Add --version flag to uwf CLI
- Bump all packages to 0.5.0

Refs #359

xiaoju added 1 commit 2026-05-21 02:32:00 +00:00

feat: add buildRolePrompt in agent-kit, integrate with uwf-hermes 505f85e3c4

- New buildRolePrompt() in workflow-agent-kit: four-phase prompt assembly
  with fallback to systemPrompt
- Export from agent-kit index
- Update uwf-hermes to use buildRolePrompt instead of raw systemPrompt
- Add tests for all modes: four-phase, legacy, mixed

Refs #359, #362

xiaoju added 1 commit 2026-05-21 02:56:15 +00:00

feat: add four-phase example workflow (analyze-topic) c0c8d6499e

Refs #359, #363

xiaomo requested changes 2026-05-21 03:02:45 +00:00

Dismissed

xiaomo left a comment

设计方向 👍，但需要更彻底：

必须改

删掉 systemPrompt — 既然拆成四段式就不要保留旧字段，不需要向前兼容。涉及 types.ts、schemas.ts、validate.ts、buildRolePrompt fallback 逻辑、materialize strip 逻辑。
四段式字段全部 required — identity/prepare/execute/report 不应该是 optional/nullable。Role 必须完整描述四个阶段。schema required 数组加上这四个字段，类型改为 string（不是 string | null）。
thread.ts — 去掉 systemPrompt fallback 后，建议直接用 buildRolePrompt(roleDef) 统一渲染，而不是只显示 identity。
buildRolePrompt — 去掉 legacy 分支，简化为直接拼四段，不需要模式判断。
现有 workflow YAML 迁移 — 确认所有现存 workflow 文件都改成四段式，不留 systemPrompt。

设计方向 👍，但需要更彻底： ## 必须改 1. **删掉 `systemPrompt`** — 既然拆成四段式就不要保留旧字段，不需要向前兼容。涉及 `types.ts`、`schemas.ts`、`validate.ts`、`buildRolePrompt` fallback 逻辑、`materialize` strip 逻辑。 2. **四段式字段全部 required** — `identity`/`prepare`/`execute`/`report` 不应该是 optional/nullable。Role 必须完整描述四个阶段。schema `required` 数组加上这四个字段，类型改为 `string`（不是 `string | null`）。 3. **`thread.ts`** — 去掉 systemPrompt fallback 后，建议直接用 `buildRolePrompt(roleDef)` 统一渲染，而不是只显示 identity。 4. **`buildRolePrompt`** — 去掉 legacy 分支，简化为直接拼四段，不需要模式判断。 5. **现有 workflow YAML 迁移** — 确认所有现存 workflow 文件都改成四段式，不留 systemPrompt。

xiaoju added 1 commit 2026-05-21 03:08:01 +00:00

refactor: remove systemPrompt, make four-phase fields required 192ad656a4

Breaking change per review:
- Remove systemPrompt from RoleDefinition entirely
- identity/prepare/execute/report are now required (string, not nullable)
- Remove all legacy fallback logic in buildRolePrompt
- Simplify validate.ts, workflow.ts materialize
- Migrate all test fixtures and example workflows

Refs #359

xiaomo approved these changes 2026-05-21 03:10:54 +00:00

xiaomo left a comment

LGTM ✅ systemPrompt 零残留，四段式全 required，测试覆盖到位。

xiaomo merged commit fe035c065d into main

2026-05-21 03:11:00 +00:00

xiaomo referenced this issue from a commit

2026-05-21 03:11:02 +00:00

Merge pull request 'feat: Role 四段式描述 (identity/prepare/execute/report)' (#361) from feat/359-role-four-phase into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: uncaged/workflow#361