OpenClaw Workflow Architect

Nguyên tắc phân tầng cốt lõi

Mọi quyết định thiết kế đều bắt đầu từ hai câu hỏi này:

"Bước này đang nói chuyện với AI để lý luận, hiểu ngữ cảnh, ra quyết định?"
→ Đó là việc của OpenProse
"Bước này đang xác định điều gì xảy ra sau khi AI đã quyết định?"
→ Đó là việc của Lobster

Lobster làm tốt	OpenProse làm tốt
Chạy chuỗi CLI theo thứ tự xác định	Đọc kỹ năng, lý luận về ngữ cảnh
Cổng phê duyệt trước side effects

Đọc references/layering-guide.md để có bảng phân tích chi tiết và danh sách anti-patterns.

Phần 1 — Nhận diện input

Xác định loại input trước khi làm bất cứ điều gì:

- Mô tả bằng lời (người dùng mô tả yêu cầu chưa có code) → đến Phần 2 (Phỏng vấn)
File có sẵn (người dùng cung cấp .lobster, .prose, hoặc code Python/script) → đến Phần 3 (Phân tích)
Hỗn hợp → chạy Phần 3 trước, sau đó Phần 2 với thông tin đã phân tích

Phần 2 — Phỏng vấn thiết kế mới

Hỏi lần lượt các câu sau (chỉ hỏi những câu chưa rõ từ ngữ cảnh):

Q1. Quy trình có bao nhiêu bước chính? Bước nào cần con người phê duyệt trước khi tiếp tục?

Q2. Có bước nào cần chạy song song không? (ví dụ: xử lý nhiều bài học cùng lúc, nhiều tác nhân nghiên cứu độc lập)

Q3. Có vòng lặp qua danh sách không? (ví dụ: lặp qua từng bài học, từng file, từng khách hàng)

Q4. Với mỗi bước: đây là bước AI lý luận (cần hiểu ngữ cảnh, ra quyết định) hay bước thực thi xác định (lưu file, gọi CLI, kiểm tra schema)?

Q5. Model đang dùng là gì? Có phải một trong các Prose Complete systems không?

- Prose Complete: Claude Code + Opus, OpenCode + Opus, Amp + Opus
Nếu không (ví dụ: Gemini 3 Flash Preview) → xem cảnh báo tương thích bên dưới

Sau phỏng vấn: Vẽ sơ đồ tầng dạng text, xác nhận với người dùng trước khi chọn mode và sinh file.

Cảnh báo tương thích model

Nếu model không phải Prose Complete system:

CODEBLOCK0

Chờ người dùng xác nhận mode trước khi tiếp tục.

Phần 3 — Phân tích file có sẵn

Chạy checklist này với mỗi file được cung cấp:

Checklist anti-patterns

- [ ] Có file Python/script làm cầu nối để đưa context vào LLM?

→ Triệu chứng: prepare_prompt.py, build_context.py, script đọc SKILL.md rồi nhét vào prompt → Vấn đề: Lobster đang làm việc của OpenProse → Fix: Chuyển sang OpenProse session — nó đọc skill file trực tiếp

- [ ] Có workaround cho vòng lặp (script Python riêng vì "Lobster không có for-loop")?

→ Vấn đề: Đang ở sai tầng → Fix: OpenProse có for item in list: native

- [ ] Có tự build logic spawn sub-agent thủ công (inject vào AGENTS.md, tự quản lý state)?

→ Vấn đề: Đang tái tạo thứ OpenProse đã có sẵn → Fix: OpenProse parallel: block + session isolation

- [ ] approval: required có đặt trước bước có side effect không?

→ Nếu không: lỗi thiết kế nghiêm trọng — side effect có thể chạy mà không có kiểm soát

- [ ] Dùng tools.allow: ["lobster"] thay vì tools.alsoAllow?

→ Cảnh báo: allow là allowlist thuần — có thể vô tình block các core tools khác → Fix: Dùng alsoAllow trừ khi chủ ý chạy restrictive mode

- [ ] Context của phiên chính bị phình to do sub-agent không có isolation?

→ Fix: Mỗi OpenProse sub-session có context riêng

Đầu ra phân tích: Trình bày báo cáo ngắn theo cấu trúc:
CODEBLOCK1

Xác nhận người dùng đồng ý với đề xuất trước khi sinh file mới.

Phần 4 — Chọn mode sinh file

Sau phỏng vấn hoặc phân tích, hỏi người dùng chọn một trong ba mode:

Mode A — Lobster only

Khi nào phù hợp:

- Model không phải Prose Complete
Quy trình chủ yếu là thực thi xác định, ít AI orchestration phức tạp
Cần chạy được ngay, không muốn phụ thuộc vào OpenProse runtime

Cách sinh:

- Một file .lobster chính làm orchestrator
Các bước AI reasoning → dùng llm-task với schema rõ ràng
Vòng lặp → Python/CLI script nhỏ emit JSON list, Lobster xử lý
Multi-step → nhiều file .lobster gọi nhau có cấu trúc

Mode B — OpenProse only

Khi nào phù hợp:

- Model là Prose Complete system
Quy trình nặng về AI orchestration, multi-agent, parallel execution
Không có side effects phức tạp cần approval gate Lobster

Cách sinh:

- Một file .prose chính
Các bước thực thi đơn giản xử lý trực tiếp trong session
Ghi chú # COMPATIBILITY: ở đầu file nếu model chưa được xác nhận

Mode C — Auto (mixed)

Khi nào phù hợp:

- Quy trình phức tạp có cả AI orchestration lẫn side effects cần kiểm soát
Muốn tận dụng điểm mạnh của cả hai

Cách sinh (thứ tự bắt buộc):

1. Sinh .prose làm tầng điều phối trước
Xác định các điểm gọi Lobster trong INLINECODE18
Sinh từng .lobster tương ứng sau
Sinh thêm fallback-orchestrator.lobster nếu model không phải Prose Complete

Phần 5 — Sinh file vào workspace

Cấu trúc thư mục chuẩn

CODEBLOCK2

Quy trình sinh file

CODEBLOCK3

Template ghi chú tương thích (dùng cho Mode B/C với non-Prose Complete)

CODEBLOCK4

Checklist trước khi lưu file

- [ ] approval: required đặt trước mọi bước có side effect
[ ] Dùng alsoAllow thay vì INLINECODE23
[ ] Có timeoutMs và maxStdoutBytes cho mọi Lobster call
[ ] Mọi bước Lobster có id duy nhất
[ ] File .prose có requires: và ensures: rõ ràng (Mode B/C)
[ ] Worker files nhận đủ context cần thiết qua args hoặc INLINECODE31

Tham chiếu nhanh

Cần tra cứu	Đọc file
Cú pháp đầy đủ `.lobster`, tham số runtime, approval flow	INLINECODE33
Cú pháp `.prose`, state modes, slash commands

技能名称: openclaw-workflow-architect
详细描述:

OpenClaw 工作流架构师

核心分层原则

所有设计决策都从这两个问题开始：

这一步是在 与AI对话 以进行推理、理解上下文、做出决策吗？
→ 这是 OpenProse 的职责
这一步是在确定 AI决策后要发生什么 吗？
→ 这是 Lobster 的职责

Lobster 擅长	OpenProse 擅长
按确定顺序运行 CLI 链	阅读技能文件，推理上下文
副作用前的审批网关

阅读 references/layering-guide.md 以获取详细分析表和反模式列表。

第一部分 — 输入识别

在做任何事情之前，先确定输入类型：

- 口头描述（用户描述需求，尚无代码） → 前往第二部分（访谈）
现有文件（用户提供 .lobster、.prose 或 Python 代码/脚本） → 前往第三部分（分析）
混合型 → 先运行第三部分，然后使用已分析的信息运行第二部分

第二部分 — 新设计访谈

依次询问以下问题（仅询问上下文中尚未明确的问题）：

Q1. 流程有多少个主要步骤？哪些步骤需要人工批准才能继续？

Q2. 是否有步骤需要并行运行？（例如：同时处理多个课程、多个独立的研究代理）

Q3. 是否有遍历列表的循环？（例如：遍历每个课程、每个文件、每个客户）

Q4. 对于每个步骤：这是 AI 推理 步骤（需要理解上下文、做出决策）还是 确定性执行 步骤（保存文件、调用 CLI、检查 schema）？

Q5. 当前使用的模型是什么？是否是 Prose Complete 系统之一？

- Prose Complete：Claude Code + Opus、OpenCode + Opus、Amp + Opus
如果不是（例如：Gemini 3 Flash Preview） → 查看下面的兼容性警告

访谈后： 绘制文本形式的分层图，在选择模式和生成文件前与用户确认。

模型兼容性警告

如果模型不是 Prose Complete 系统：

⚠️ 兼容性警告
模型 [模型名称] 尚未被确认为 Prose Complete 系统。

- .lobster 文件：完全可用 ✓
.prose 文件：可能无法正常运行 — OpenProse 需要模型具备足够能力

在读取规范时模拟虚拟机。

可选方案：
A. 仅 Lobster — 可立即运行，AI 推理通过 llm-task 进行
B. 仅 OpenProse — 继续但需要实际测试
C. 自动（混合）— 两者都生成，测试后由您选择使用哪个

等待用户确认模式后再继续。

第三部分 — 分析现有文件

对提供的每个文件运行此检查清单：

反模式检查清单

- [ ] 是否存在 Python 文件/脚本作为桥梁，将上下文传递给 LLM？

→ 症状： prepareprompt.py、buildcontext.py、读取 SKILL.md 然后塞入提示词的脚本 → 问题： Lobster 正在做 OpenProse 的工作 → 修复： 切换到 OpenProse 会话 — 它直接读取技能文件

- [ ] 是否存在循环的变通方案（因为 Lobster 没有 for 循环而单独编写的 Python 脚本）？

→ 问题： 处于错误的层级 → 修复： OpenProse 原生支持 for item in list:

- [ ] 是否手动构建了生成子代理的逻辑（注入到 AGENTS.md、自行管理状态）？

→ 问题： 正在重新实现 OpenProse 已有的功能 → 修复： OpenProse 的 parallel: 块 + 会话隔离

- [ ] approval: required 是否放置在 有副作用的步骤之前？

→ 如果不是： 严重的设计错误 — 副作用可能在无控制的情况下运行

- [ ] 是否使用了 tools.allow: [lobster] 而不是 tools.alsoAllow？

→ 警告： allow 是纯粹的允许列表 — 可能无意中阻止了其他核心工具 → 修复： 除非有意运行限制模式，否则使用 alsoAllow

- [ ] 主会话的上下文是否因子代理没有隔离而变得臃肿？

→ 修复： 每个 OpenProse 子会话都有独立的上下文

分析输出： 按以下结构呈现简短报告：

问题：[描述]
原因：[解释为什么这是反模式]
建议：[具体的修复方法]

在生成新文件前，确认用户同意建议。

第四部分 — 选择文件生成模式

在访谈或分析之后，请用户选择三种模式之一：

模式 A — 仅 Lobster

适用场景：

- 模型不是 Prose Complete
流程主要是确定性执行，AI 编排不复杂
需要立即运行，不想依赖 OpenProse 运行时

生成方式：

- 一个主 .lobster 文件作为编排器
AI 推理步骤 → 使用带有清晰 schema 的 llm-task
循环 → 小的 Python/CLI 脚本输出 JSON 列表，由 Lobster 处理
多步骤 → 多个 .lobster 文件按结构相互调用

模式 B — 仅 OpenProse

适用场景：

- 模型是 Prose Complete 系统
流程侧重于 AI 编排、多代理、并行执行
没有需要 Lobster 审批网关的复杂副作用

生成方式：

- 一个主 .prose 文件
简单的执行步骤直接在会话中处理
如果模型未经确认，在文件开头添加 # COMPATIBILITY: 注释

模式 C — 自动（混合）

适用场景：

- 复杂流程，同时包含 AI 编排和需要控制的副作用
希望充分利用两者的优势

生成方式（强制顺序）：

1. 先生成 .prose 作为编排层
在 .prose 中确定调用 Lobster 的点
随后生成对应的每个 .lobster 文件
如果模型不是 Prose Complete，额外生成 fallback-orchestrator.lobster

第五部分 — 在工作区生成文件

标准目录结构

workflows/
├── [流程名称].prose # 模式 B 或 C
├── [流程名称].lobster # 模式 A 或 C
├── gates/
│ └── [网关名称].lobster # 可复用的审批网关
└── workers/
└── [工作器名称].lobster # 子工作器

文件生成流程

1. 检查 workflows/ 目录 — 如果不存在则创建
[模式 A] 生成主 .lobster → 如果需要则生成 workers/
[模式 B] 生成 .prose → 如果需要则添加兼容性注释
[模式 C] 生成 .prose → 生成被 .prose 调用的 .lobster → 生成 workers/
报告已创建的文件列表
提供具体的运行命令指南

兼容性注释模板（用于非 Prose Complete 系统的模式 B/C）

yaml

============================================================

兼容性说明

模型：[模型名称] — 尚未确认为 Prose Complete 系统

.lobster 文件：完全可用 ✓

.prose 文件：需要实际测试 — 如果 .prose 无法正常运行，

请参阅 fallback-orchestrator.lobster

Prose Complete 系统：Claude Code + Opus、OpenCode + Opus、Amp + Opus

============================================================

保存文件前的检查清单

- [ ] approval: required 放置在具有副作用的每个步骤之前
[ ] 使用 alsoAllow 而不是 allow
[ ] 每个 Lobster 调用都有 timeoutMs 和 maxStdoutBytes
[ ] 每个 Lobster 步骤都有唯一的 id
[ ] .prose 文件具有清晰的 requires: 和 ensures:（模式 B/C）
[ ] 工作器文件通过 args 或 stdin 接收所需的全部上下文

快速参考

| 需要查阅的内容 | 阅读文件 |
|-------------|---------|
| .lobster 完整语法、运行时参数、审批

openclaw-workflow-architect开放式工作流架构