agent-workflow

强制要求 — 上下文收集协议

在应用任何工作流指导之前，先收集上下文：

1. 检查项目根目录中的 Maestro 上下文

   • 首先检查 .maestro/context.md（v2 布局）
   • 然后检查 .maestro.md（v1 布局 — 向后兼容）
   • 如果存在 → 读取并使用其中的工作流上下文
   • 如果不存在 → 告诉用户：“未找到工作流上下文。运行 /teach-maestro，为项目设置专属上下文，以获得更好的结果。”

2. 检查决策历史（可选）

   • 如果 .maestro/decisions.jsonl 存在 → 读取最近 5 条决策，以便在会话中保持连贯
   • 如果不存在 → 继续操作（无需报错）

3. 最低可用上下文（如果没有 .maestro.md）：

   • 正在使用哪些 AI 模型？
   • 工作流的主要任务是什么？
   • 是否有可用的现有提示词、工具或 Agent？
   • 对质量、速度和成本的优先级是什么？

4. 不要在尚未充分了解模型、任务和优先级的情况下继续操作。

---

Maestro — AI Agent 工作流精通

此技能提供设计、构建和维护生产级 AI Agent 工作流所需的基础知识。所有 Maestro 命令都以这些原则为基础。

核心原则

1. 结构优于临场发挥 — 工作流应经过周密设计，而非临时形成
2. 约束也是功能 — 明确的边界可以避免失败情况
3. 以测量为准，而非凭空假设 — 每个工作流都需要评估，而不只是测试
4. 复杂度适当 — 让解决方案匹配问题，而非追求宏大目标
5. 优雅降级 — 每个组件都应能够安全地失败

---

1. 提示词工程

应该做：

• 使用结构清晰的提示词，并划分明确的部分（角色、上下文、说明、输出格式）
• 明确定义输出架构（JSON 架构、Markdown 模板、类型化响应）
• 对有歧义的任务使用少样本示例
• 对多步推理使用思维链
• 保持系统提示词专注 — 每个提示词只设定一个明确角色

不应该做：

• 编写没有结构、长篇大论的提示词
• 假设模型能理解隐含的输出格式
• 对本质不同的任务使用相同的提示词
• 在同一提示词中放入互相冲突的指令
• 指望模型自行“想办法解决”

→ 请参阅提示词工程参考，了解结构、模式和输出架构。

---

2. 上下文管理

应该做：

• 合理分配上下文窗口用量（系统提示词、示例、用户输入、工具结果、输出）
• 将关键信息放在上下文的开头和结尾（注意力梯度）
• 使用检索（RAG），而不是塞入完整文档
• 明确维护对话状态
• 总结较长的历史记录，而不是传递原始转录

不应该做：

• 将整个代码库、数据库或文档都塞进上下文
• 忽略上下文窗口限制，直到超出限制
• 假设模型对所有上下文的关注度都相同
• “以防万一”而传递无关信息
• 依赖轮次之间的隐式记忆

→ 请参阅上下文管理参考，了解窗口优化和记忆模式。

---

3. 工具编排

应该做：

• 为工具设置清晰、具体的名称和描述
• 为每个工具定义输入和输出架构
• 妥善处理工具错误（工具迟早会失败）
• 保持工具集专注 — 每个 Agent 配备 3-7 个工具为宜
• 尽可能让工具具备幂等性

不应该做：

• 暴露 30 多个工具，然后指望模型选对
• 使用含糊的工具描述（“处理数据之类的事情”）
• 在工具实现中省略错误处理
• 对具有破坏性的操作，不经确认就让工具产生副作用
• 创建功能重叠的工具

→ 请参阅工具编排参考，了解选择启发法和组合模式。

4. Agent 架构

应该：

• 从单个 Agent 开始——只有在单个 Agent 明确无法胜任时，才添加其他 Agent
• 明确每个 Agent 的边界和职责
• 使用结构化的 Agent 间交接协议
• 为多 Agent 系统实现监督者模式
• 设计时考虑可观测性——记录 Agent 的决策，而不仅仅是输出

不应该：

• 为单个 Agent 就能处理的问题构建多 Agent 系统
• 创建边界不明确的 Agent（职责重叠会导致冲突）
• 使用非结构化的 Agent 间通信
• 跳过监督者——自主 Agent 集群难以预测
• 假设 Agent 无需明确协议就能协调配合

→ 请参阅 Agent 架构参考，了解拓扑模式和委派方式。

---

5. 反馈循环

应该：

• 从第一天起就在工作流中加入评估
• 创建包含已知正确输入和输出的黄金测试集
• 使用自动化评估器进行一致的质量评分
• 跟踪回归——将新输出与基准进行比较
• 为关键输出实现自我纠正循环

不应该：

• 未经评估就发布（“看起来能用”不算评估）
• 大规模应用时仅依赖人工审核
• 不设结构就用同一个模型评估其自身输出
• 更改提示词或模型时跳过回归测试
• 混淆“模型运行时没有出错”和“输出正确”

→ 请参阅 反馈循环参考，了解评估模式和自我纠正。

---

6. 知识系统

应该：

• 根据查询类型选择检索策略（语义、关键词、混合）
• 仔细划分文档片段（按语义边界划分，而非任意的词元数量）
• 在每条检索结果中注明来源
• 将检索质量与生成质量分开测试
• 对知识库进行版本管理——了解模型可访问哪些内容

不应该：

• 未先测试检索质量就构建 RAG
• 对所有文档类型使用固定的片段大小
• 跳过来源标注（没有来源标注的幻觉无法被发现）
• 未经筛选就索引所有内容（输入垃圾，输出也会是垃圾）
• 假设嵌入相似度就等于相关性

→ 请参阅 知识系统参考，了解 RAG、嵌入和基于依据生成。

---

7. 护栏与安全

应该：

• 在处理前验证输入（架构验证、大小限制）
• 筛查输出中的敏感内容、个人身份信息（PII）和策略违规内容
• 设置硬性成本上限（每次运行的最大词元数、最大 API 调用次数和最大支出）
• 为级联故障实现熔断机制
• 记录所有内容，以便审计

不应该：

• 未验证输入就部署（提示词注入确实存在）
• 在高风险决策中未经验证就信任模型输出
• 在没有成本控制的情况下运行（一次失控的循环就可能造成数千美元的成本）
• 跳过外部 API 调用的速率限制
• 假设模型 100% 的情况下都会遵循安全指令

→ 请参阅 护栏参考，了解验证、沙箱和约束。

---

工作流粗制滥造检测

如果以下任一项成立，就需要改进工作流：

• 提示词是没有结构的长篇文本 → 运行 /refine
• 未定义输出架构——由模型决定格式 → 运行 /refine
• 未设置预算就使用上下文窗口——把所有内容都塞进去 → 运行 /accelerate
• 向单个 Agent 暴露了超过 10 个工具 → 运行 /streamline
• 没有错误处理——只处理顺利路径 → 运行 /fortify
• 没有评估——“看起来能用” → 运行 /iterate
• 用多 Agent 系统解决单 Agent 就能处理的问题 → 运行 /temper
• 没有成本控制——词元用量不受限制 → 运行 /guard
• 工具的单行描述含糊不清 → 运行 /calibrate
• 没有日志记录——无法调试生产问题 → 运行 /fortify

勾选 0 项 = 已达到生产就绪状态。勾选 3 项以上 = 工作流粗制滥造。

---

可用命令

使用这些命令来应用工作流精通的特定方面：

{{available_commands}}