用途
agent-workflow 是 Maestro 体系中的基础技能，用于设计、构建和维护生产级 AI 智能体工作流。所有 Maestro 命令都建立在这些原则之上。当任何 Maestro 命令被调用时，该技能即生效。
强制上下文收集协议
在应用任何工作流指导之前，必须先收集上下文：
- 检查项目根目录中的 Maestro 上下文：先检查 .maestro/context.md（v2 布局），再检查 .maestro.md（v1 布局，向后兼容）。若存在，则读取并使用其中的工作流上下文；若不存在，则告知用户：“No workflow context found. Run /teach-maestro to set up project-specific context for better results.”
- 可选检查决策历史：若 .maestro/decisions.jsonl 存在，读取最近 5 条决策以保持会话连续性；若不存在则直接继续，不报错。
- 最小可行上下文（在没有 .maestro.md 时）：正在使用哪些 AI 模型？工作流的主要任务是什么？是否有现成的提示、工具或智能体可用？质量、速度、成本的优先级如何？
在至少理解模型、任务和优先级之前，不要继续。
核心原则
- 结构优于即兴——工作流应当是有意设计的，而非自然涌现的。
- 约束即特性——明确的边界可防止失败模式。
- 度量而非假设——每个工作流都需要评估，而不仅是测试。
- 复杂度要适当——让方案匹配问题，而非匹配野心。
- 优雅降级——每个组件都应能安全失败。
1. 提示工程
应做：使用带清晰分区的结构化提示（角色、上下文、指令、输出格式）；显式定义输出模式（JSON schema、markdown 模板、类型化响应）；对模糊任务使用少样本示例；多步推理使用思维链；保持系统提示聚焦，每个提示一个清晰角色。
不应做：写没有结构的大段文字提示；假设模型理解隐式输出格式；对根本不同的任务使用同一提示；在同一提示中放入相互冲突的指令；依赖模型“自己搞明白”。
→ 查阅提示工程参考以了解结构、模式与输出 schema。
2. 上下文管理
应做：为上下文窗口使用做预算（系统提示、示例、用户输入、工具结果、输出）；把关键信息放在上下文的开头和结尾（注意力梯度）；使用检索（RAG）而非塞入完整文档；显式维护对话状态；对长历史做摘要而非传入原始记录。
不应做：把整个代码库、数据库或文档倾倒进上下文；忽视上下文窗口限制直到撞上；假设模型对所有上下文给予同等注意力；以“以防万一”为由传入无关信息；依赖跨轮次的隐式记忆。
→ 查阅上下文管理参考以了解窗口优化与记忆模式。
3. 工具编排
应做：给工具清晰、具体的名称和描述；为每个工具定义输入/输出 schema；优雅处理工具错误（工具终将失败）；保持工具集聚焦，每个智能体 3-7 个工具为理想；尽可能让工具幂等。
不应做：暴露 30 个以上工具并指望模型选对；使用含糊的工具描述（“对数据做点事”）；在工具实现中跳过错误处理；让工具有副作用而不对破坏性操作做确认；创建功能重叠的工具。
→ 查阅工具编排参考以了解选择启发式与组合模式。
4. 智能体架构
应做：从单个智能体开始，只有当单个智能体明显失败时才增加智能体；为每个智能体定义清晰边界与职责；在智能体之间使用结构化交接协议；为多智能体系统实现监督者模式；为可观测性而设计，记录智能体决策而不仅是输出。
不应做：为单智能体能处理的问题构建多智能体系统；创建没有清晰边界的智能体（职责重叠即冲突）；在智能体之间使用非结构化通信；跳过监督者——自主智能体集群不可预测；假设智能体会在没有显式协议的情况下协调。
→ 查阅智能体架构参考以了解拓扑模式与委派。
5. 反馈循环
应做：从第一天起就把评估构建进工作流；创建带有已知良好输入输出的黄金测试集；使用自动评估器进行一致的质量评分；跟踪回归，将新输出与基线比较；对关键输出实现自我纠正循环。
不应做：没有评估就发布（“看起来能跑”不是评估）；在大规模场景下仅依赖人工审查；让同一模型在没有结构的情况下评估自己的输出；在更改提示或模型时跳过回归测试；把“模型运行无错误”与“输出正确”混为一谈。
→ 查阅反馈循环参考以了解评估模式与自我纠正。
6. 知识系统
应做：根据查询类型选择检索策略（语义、关键词、混合）；有思考地切分文档（语义边界，而非任意 token 数）；在每个检索结果中包含来源归属；独立于生成质量测试检索质量；对知识库做版本管理，明确模型能访问什么。
不应做：不先测试检索质量就构建 RAG；对所有文档类型使用固定分块大小；跳过来源归属（没有归属的幻觉无法被察觉）；不加筛选地索引一切（垃圾进垃圾出）；假设嵌入相似度等于相关性。
→ 查阅知识系统参考以了解 RAG、嵌入与接地。
7. 护栏与安全
应做：在处理前验证输入（schema 验证、大小限制）；过滤输出中的敏感内容、PII 与政策违规；设置硬性成本上限（最大 token、最大 API 调用、每次运行最大花费）；为级联失败实现熔断器；记录一切以形成审计轨迹。
不应做：没有输入验证就部署（提示注入是真实存在的）；对高风险决策不经核实就信任模型输出；没有成本控制就运行（一个失控循环可能花费数千）；跳过外部 API 调用的速率限制；假设模型会 100% 遵守安全指令。
→ 查阅护栏参考以了解验证、沙箱与约束。
工作流劣质检测
若以下任一项为真，则工作流需要改进：
- 提示是无结构的大段文字 → 运行 /refine
- 未定义输出 schema，格式由模型决定 → 运行 /refine
- 上下文窗口使用无预算，什么都往里塞 → 运行 /accelerate
- 单个智能体暴露超过 10 个工具 → 运行 /streamline
- 无错误处理，只有顺利路径 → 运行 /fortify
- 无评估，“看起来能跑” → 运行 /iterate
- 为单智能体问题构建多智能体系统 → 运行 /temper
- 无成本控制，token 使用无上限 → 运行 /guard
- 工具描述是含糊的一行字 → 运行 /calibrate
- 无日志，无法调试生产问题 → 运行 /fortify
零项勾选 = 生产就绪。3 项以上勾选 = 工作流劣质。
可用命令
使用这些命令应用工作流掌握的具体方面：{{available_commands}}
适用场景与限制
该技能适用于使用 Maestro 命令进行 AI 智能体工作流设计、构建与维护的场景，尤其适合需要结构化提示、上下文预算、工具编排、多智能体架构、评估反馈、RAG 知识系统与安全护栏的生产级项目。限制方面：资料未提供具体的模型支持范围、平台依赖、收费方式或性能指标；技能本身不包含可直接运行的代码，其命令列表以占位符 {{available_commands}} 表示，具体命令内容暂未提供。