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

RFC: Agent 产出格式 — Frontmatter Markdown + Prompt 越权控制 #351

New Issue
Closed
opened 2026-05-19 04:35:03 +00:00 by xiaoju · 0 comments
xiaoju commented 2026-05-19 04:35:03 +00:00
Owner
Copy Link
Copy Source

背景

当前 agent adapter 输出 meta 的方式不够自然。Agent 的产出物需要同时服务两个消费者：

  1. 下游 agent — 需要完整的内容（content）
  2. moderator — 需要结构化的路由/决策信息（meta），但作为纯函数消费不了太多细节

同时，planner 越权行为无法从 tools 层面控制（每个 agent 工具集不同），需要在 prompt 层面解决。

设计方案

1. Agent 产出格式：Frontmatter Markdown

Agent 输出统一为带 YAML frontmatter 的 markdown：

---
status: completed
next: reviewer
confidence: 0.9
artifacts:
  - type: plan
    path: /tmp/plan.md
---

（正文内容，给下一个 agent 消费）
  • frontmatter — moderator 只解析 YAML header 做路由/决策
  • markdown body — 下游 agent 直接读，零序列化成本
  • 人类可读 — 调试时直接看文件就懂

2. Adapter 两层保障

  1. Prompt 层 — 要求 agent 直接输出 frontmatter markdown
  2. Adapter 层 — 校验格式，不合规时调用 extract 兜底（LLM 提取）

Happy path 零开销，只有 agent 不听话时才多一次 LLM 调用。

3. Prompt 越权控制

  • 在 prompt 开头明确声明「你的产出是 X」
  • 调整 prompt 各部分排序，让目标聚焦在前
  • 通过 prompt engineering 约束 scope，而非 sandbox

Phase 拆分

Phase 1: 定义 Frontmatter Markdown 规范

  • 定义 frontmatter schema（必填/可选字段）
  • 定义 adapter 的 parse + validate 逻辑
  • Testing issue: 待创建

Phase 2: Adapter 实现两层保障

  • prompt 模板中加入格式要求
  • adapter 校验 + extract 兜底
  • Testing issue: 待创建

Phase 3: Prompt 结构优化（越权控制）

  • 重新排列 prompt 各部分顺序
  • 明确产出目标声明
  • Testing issue: 待创建

完成标准

  • 所有 Phase 的 testing issue 已 close
  • 现有 workflow template 适配新格式
  • moderator 能正确解析 frontmatter 做路由
## 背景 当前 agent adapter 输出 meta 的方式不够自然。Agent 的产出物需要同时服务两个消费者： 1. **下游 agent** — 需要完整的内容（content） 2. **moderator** — 需要结构化的路由/决策信息（meta），但作为纯函数消费不了太多细节 同时，planner 越权行为无法从 tools 层面控制（每个 agent 工具集不同），需要在 prompt 层面解决。 ## 设计方案 ### 1. Agent 产出格式：Frontmatter Markdown Agent 输出统一为带 YAML frontmatter 的 markdown： ```markdown --- status: completed next: reviewer confidence: 0.9 artifacts: - type: plan path: /tmp/plan.md --- （正文内容，给下一个 agent 消费） ``` - **frontmatter** — moderator 只解析 YAML header 做路由/决策 - **markdown body** — 下游 agent 直接读，零序列化成本 - **人类可读** — 调试时直接看文件就懂 ### 2. Adapter 两层保障 1. **Prompt 层** — 要求 agent 直接输出 frontmatter markdown 2. **Adapter 层** — 校验格式，不合规时调用 extract 兜底（LLM 提取） Happy path 零开销，只有 agent 不听话时才多一次 LLM 调用。 ### 3. Prompt 越权控制 - 在 prompt 开头明确声明「你的产出是 X」 - 调整 prompt 各部分排序，让目标聚焦在前 - 通过 prompt engineering 约束 scope，而非 sandbox ## Phase 拆分 ### Phase 1: 定义 Frontmatter Markdown 规范 - 定义 frontmatter schema（必填/可选字段） - 定义 adapter 的 parse + validate 逻辑 - Testing issue: 待创建 ### Phase 2: Adapter 实现两层保障 - prompt 模板中加入格式要求 - adapter 校验 + extract 兜底 - Testing issue: 待创建 ### Phase 3: Prompt 结构优化（越权控制） - 重新排列 prompt 各部分顺序 - 明确产出目标声明 - Testing issue: 待创建 ## 完成标准 - [ ] 所有 Phase 的 testing issue 已 close - [ ] 现有 workflow template 适配新格式 - [ ] moderator 能正确解析 frontmatter 做路由
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#351
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?