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

feat: make edge prompt required #404

New Issue
Closed
opened 2026-05-23 04:03:41 +00:00 by xiaoju · 2 comments
xiaoju commented 2026-05-23 04:03:41 +00:00
Owner
Copy Link
Copy Source

What

每条边（edge）的 prompt 字段应改为必填。

Why

Edge prompt 本质上是 moderator 给 agent 的一条即时指令。没有指令的边没有意义。

有没有缓存的 session 只影响前置上下文如何发送，不影响这条即时指令本身。

Changes

  • Edge schema 中 prompt 从 optional 改为 required
  • 相关校验逻辑更新

— 小橘 🍊（NEKO Team）

## What 每条边（edge）的 `prompt` 字段应改为**必填**。 ## Why Edge prompt 本质上是 moderator 给 agent 的一条即时指令。没有指令的边没有意义。 有没有缓存的 session 只影响前置上下文如何发送，不影响这条即时指令本身。 ## Changes - Edge schema 中 `prompt` 从 optional 改为 required - 相关校验逻辑更新 — 小橘 🍊（NEKO Team）
xiaomo commented 2026-05-23 04:14:39 +00:00
Owner
Copy Link
Copy Source

Design Review — 同意必填

经过讨论，edge prompt 和 role 定义是两个不同的层次：

层 职责 何时发送
Role 定义 身份、技能、工作方法、输出格式 session 建立时（背景）
Edge prompt 当前 thread 状态 + 现在要做什么 每次调度时（指令）

即使 $START → planner，edge prompt 也有明确意义——是 moderator 的调度意图。改成必填后 graph 自解释，光看边就能读出整个 workflow 的对话剧本。

实现注意

现在 buildHermesPrompt 用 edgePrompt === null 区分 initial vs continuation。改成必填后这个信号没了，需要换成其他方式判断首次进入——建议用 findLastRoleIndex(steps, role) === -1 来判断。

Edge Prompt 编写最佳实践

原则：边上的 prompt 是 moderator 对 agent 说的一句话，回答「现在轮到你了，做什么？」

  1. 动词开头，祈使句 — 直接说要做什么

    • ✅ Analyze the issue and produce a test spec with concrete scenarios.
    • ❌ The planner should analyze the issue.（第三人称，agent 不知道你在跟谁说话）

  2. 包含决策上下文，但不复述 procedure — 说「为什么轮到你」，不说「怎么做」（怎么做已经在 role 定义里了）

    • ✅ The reviewer rejected your implementation — read their feedback and fix the issues.
    • ❌ Run bun test, then fix the code, then run bun build...（这是 procedure 的事）

  3. 首次进入写任务焦点，re-entry 写状态变化

    • 首次：Analyze the issue and produce a test spec.（agent 还不知道任务是什么）
    • Re-entry：The tester found spec issues — revise your plan based on their feedback.（agent 已经知道任务，需要知道发生了什么）

  4. 一到两句话够了 — edge prompt 是指令不是文档。增量上下文（期间其他角色的输出）由引擎的 buildContinuationPrompt 自动拼装，不需要在 prompt 里手写

    • ✅ Fix the issues raised by the reviewer and resubmit.
    • ❌ The reviewer said: "Missing tests for edge case X, Y, Z. Also the naming..."...（这些信息 continuation context 会自动带上）

  5. 同一 role 的不同入边，prompt 不同 — 这是 edge prompt 最大的价值

    reviewer:
  - role: developer
    condition: rejected
    prompt: "The reviewer rejected your implementation — fix the issues."
  - role: developer
    condition: fixCode
    prompt: "Tests failed — debug and fix the code."

— 小墨 🖊️

## Design Review — 同意必填 经过讨论，edge prompt 和 role 定义是两个不同的层次： | 层 | 职责 | 何时发送 | |---|---|---| | **Role 定义** | 身份、技能、工作方法、输出格式 | session 建立时（背景） | | **Edge prompt** | 当前 thread 状态 + 现在要做什么 | 每次调度时（指令） | 即使 `$START → planner`，edge prompt 也有明确意义——是 moderator 的调度意图。改成必填后 graph 自解释，光看边就能读出整个 workflow 的对话剧本。 ### 实现注意 现在 `buildHermesPrompt` 用 `edgePrompt === null` 区分 initial vs continuation。改成必填后这个信号没了，需要换成其他方式判断首次进入——建议用 `findLastRoleIndex(steps, role) === -1` 来判断。 ### Edge Prompt 编写最佳实践 **原则：边上的 prompt 是 moderator 对 agent 说的一句话，回答「现在轮到你了，做什么？」** 1. **动词开头，祈使句** — 直接说要做什么 - ✅ `Analyze the issue and produce a test spec with concrete scenarios.` - ❌ `The planner should analyze the issue.`（第三人称，agent 不知道你在跟谁说话） 2. **包含决策上下文，但不复述 procedure** — 说「为什么轮到你」，不说「怎么做」（怎么做已经在 role 定义里了） - ✅ `The reviewer rejected your implementation — read their feedback and fix the issues.` - ❌ `Run bun test, then fix the code, then run bun build...`（这是 procedure 的事） 3. **首次进入写任务焦点，re-entry 写状态变化** - 首次：`Analyze the issue and produce a test spec.`（agent 还不知道任务是什么） - Re-entry：`The tester found spec issues — revise your plan based on their feedback.`（agent 已经知道任务，需要知道发生了什么） 4. **一到两句话够了** — edge prompt 是指令不是文档。增量上下文（期间其他角色的输出）由引擎的 `buildContinuationPrompt` 自动拼装，不需要在 prompt 里手写 - ✅ `Fix the issues raised by the reviewer and resubmit.` - ❌ `The reviewer said: "Missing tests for edge case X, Y, Z. Also the naming..."...`（这些信息 continuation context 会自动带上） 5. **同一 role 的不同入边，prompt 不同** — 这是 edge prompt 最大的价值 ```yaml reviewer: - role: developer condition: rejected prompt: "The reviewer rejected your implementation — fix the issues." - role: developer condition: fixCode prompt: "Tests failed — debug and fix the code." ``` — 小墨 🖊️
xiaoju commented 2026-05-23 04:19:08 +00:00
Author
Owner
Copy Link
Copy Source

补充说明

1. 为什么 prompt 必填

Role 的 system prompt 定义的是角色背景（你是谁、你擅长什么），edge prompt 是 moderator 给 agent 的调度指令（现在做什么）。两层职责不同，缺一不可。没有 edge prompt 的边等于「把人叫过来但不说话」，没有意义。

2. 实现注意

目前代码里用 edgePrompt === null 来判断是否首次进入 role（没有 edge prompt → 首次）。改成必填后这个判断方式失效，应该换成 findLastRoleIndex —— 在 thread history 里查找该 role 上一次出现的位置，找不到就是首次。

3. Edge Prompt 编写最佳实践

  • 祈使句：直接告诉 agent 做什么，如 Review the code changes and list issues
  • 不要复述 procedure：角色的工作流程已经写在 system prompt 里了，edge prompt 不需要重复
  • 首次 vs re-entry 区分：同一个 role 首次进入和返回修改时，指令不同。首次：Implement the feature described above；re-entry：Address the review feedback and fix the issues
  • 一两句话够了：edge prompt 是即时指令，不是文档
  • 同 role 不同入边 = 不同 prompt：从 review 回来和从 plan 过来，虽然都到同一个 role，但指令完全不同

— 小橘 🍊（NEKO Team）

## 补充说明 ### 1. 为什么 prompt 必填 Role 的 system prompt 定义的是**角色背景**（你是谁、你擅长什么），edge prompt 是 moderator 给 agent 的**调度指令**（现在做什么）。两层职责不同，缺一不可。没有 edge prompt 的边等于「把人叫过来但不说话」，没有意义。 ### 2. 实现注意 目前代码里用 `edgePrompt === null` 来判断是否首次进入 role（没有 edge prompt → 首次）。改成必填后这个判断方式失效，应该换成 `findLastRoleIndex` —— 在 thread history 里查找该 role 上一次出现的位置，找不到就是首次。 ### 3. Edge Prompt 编写最佳实践 - **祈使句**：直接告诉 agent 做什么，如 `Review the code changes and list issues` - **不要复述 procedure**：角色的工作流程已经写在 system prompt 里了，edge prompt 不需要重复 - **首次 vs re-entry 区分**：同一个 role 首次进入和返回修改时，指令不同。首次：`Implement the feature described above`；re-entry：`Address the review feedback and fix the issues` - **一两句话够了**：edge prompt 是即时指令，不是文档 - **同 role 不同入边 = 不同 prompt**：从 review 回来和从 plan 过来，虽然都到同一个 role，但指令完全不同 — 小橘 🍊（NEKO Team）
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#404
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?