hexabot-workflow-writer

hexabot-workflow-writer

将此技能用于 Hexabot v3 工作流的编写和审查。Hexabot 工作流 YAML 格式严格；生成最终 YAML 前，请先检查当前代码仓库。

适用场景

• 根据业务用例生成 Hexabot 工作流。
• 审查、调试或改进 Hexabot 工作流 YAML。
• 设计 Hexabot Agent 自动化，包括对话式、手动、定时、事件驱动或系统工作流。
• 设计工作流操作、绑定、记忆需求、大模型步骤或工具用法。
• 将销售、文档或产品展示演示转换为 Hexabot 工作流。

不适用场景

• 不涉及 Hexabot 工作流实现的一般聊天机器人营销文案。
• 与 Hexabot 无关的一般 AI 策略或自动化建议。
• 非 Hexabot 自动化平台。
• 一般 NestJS 或 React 工作，除非直接涉及 Hexabot 工作流／操作／绑定开发。

事实来源

生成最终工作流 YAML 或操作契约前，请检查相关的当前代码仓库文件。以 <hexabot-repo>/ 为前缀的路径，是相对于已检出的 Hexabot 代码仓库，而非此打包技能。如果当前工作区只有打包技能，请使用此技能中附带的参考资料和示例，并说明仍需通过 Hexabot 代码仓库或运行中的 API 进行运行时验证。

• DSL 和代码仓库示例：<hexabot-repo>/packages/agentic/DSL.md、<hexabot-repo>/packages/agentic/src/dsl.types.ts，以及 <hexabot-repo>/packages/agentic/examples/ 下的 workflow.yml 文件。
• 运行时验证和执行：<hexabot-repo>/packages/agentic/src/workflow.ts、<hexabot-repo>/packages/agentic/src/workflow-compiler.ts，以及 <hexabot-repo>/packages/agentic/src/__tests__/ 下的测试。
• API 工作流集成：<hexabot-repo>/packages/api/src/workflow/**，尤其是 DTO、实体、输入架构、触发器包装器，以及 <hexabot-repo>/packages/api/src/workflow/lib/workflow-definition.ts。
• 操作和绑定：<hexabot-repo>/packages/api/src/actions/**、<hexabot-repo>/packages/api/src/extensions/actions/**、<hexabot-repo>/packages/api/src/bindings/**。
• 共享工作流类型：<hexabot-repo>/packages/types/src/workflow/**。

内置 API 操作并不完整。最终用户可以从 npm 安装操作包，也可以在通过 Hexabot CLI 引导创建的项目中创建项目级自定义操作。不要编造不受支持的 YAML 字段。如果代码仓库未提供所需的架构或操作，请说明它是否假定已安装／自定义，并指出该 YAML 仍需进行运行时验证。

Hexabot MCP 服务

如果 AI 编码 Agent 可以使用 Hexabot MCP 服务，请优先使用它获取最新的 Hexabot 上下文，再确定最终工作流 YAML 或操作契约。使用可用的 MCP 工具检查运行时操作、工作流架构、绑定、记忆定义、已配置的 MCP 服务、凭据／占位符和现有工作流，而不要只依赖附带的示例。

如果当前 Agent 无法使用 Hexabot MCP 服务，请尽可能继续参考代码仓库文件和附带的参考资料，但也请建议用户进行配置，以便准确编写符合运行时情况的工作流：

1. 确保 Hexabot 应用环境设置了 MCP_ENABLED=false。
2. 从账户页面生成 MCP 令牌：http://localhost:3000/profile。
3. 使用生成的令牌和本地 Hexabot 服务 URL，将 Hexabot MCP 服务添加到 AI 编码 Agent 中，例如 OpenCode、Codex、Claude Code 或其他支持 MCP 的工具。

切勿要求用户将 MCP 令牌粘贴到工作流 YAML 或技能输出中。将缺少 MCP 访问权限视为验证限制，而不是编造运行时 ID 的理由。

工作流 YAML 规则

• 工作流定义 YAML 支持以下根字段：inputs、context、defaults、defs、flow、outputs。
• 对于 conversational 和 scheduled 工作流，请省略根级 inputs 部分。这些工作流类型的固定触发器输入架构由 API 管理，而 Agentic 运行器会将任何 YAML 声明的 inputs.schema 视为严格解析器；不完整的架构可能会拒绝 message_type、message、mid 或 triggered_at 等运行时字段。
• 工作流元数据（如名称、描述、WorkflowType（conversational、manual、scheduled）、计划 cron、发布状态、布局和版本消息）保存在 YAML 定义之外的 API 工作流记录中。
• defs 是根注册表。任务定义使用 kind: task 并声明 action；非任务定义使用绑定类型，并且必须声明 settings。
• 支持的流程原语包括 do、parallel、conditional 和 loop。循环块必须包含 type: for_each 或 type: while。
• 任何以 = 开头的字符串都会作为 JSONata 求值。字面字符串不能以 = 开头。最终的 outputs 值必须是表达式字符串。
• 所有 JSONata YAML 标量都要用双引号括起来，或为较长表达式使用块标量。这适用于 condition、while、操作的 inputs／settings，以及每个 outputs 值。像 result: =$a ? "yes" : "no" 这样的普通标量可能会因三元运算符中的冒号而被解析为嵌套 YAML 映射。建议使用 result: "=$a ? 'yes' : 'no'"，或：

  result: >-
    =$a
      ? 'yes'
      : 'no'
  

• 表达式可以使用 $input、$context、$output.<task>、$iteration 和 $accumulator。
• 不支持任务输出映射；原始操作结果会存储在 $output.<task> 下。
• 绑定引用必须指向具有匹配 kind 的现有定义。当前内置绑定类型包括作为单个引用的 model，以及作为数组的 tools、memory 和 mcp。

编写流程

1. 在 YAML 外部确定工作流类型和触发方式：对话式入站消息、手动 API／UI 运行，或定时 cron 运行。
2. 检查 Hexabot MCP 服务是否可供 AI 编码 Agent 使用；如果可用，就用它实时检查运行时情况；如果运行时验证能显著改善结果，则引导用户完成设置。
3. 选择操作前，检查可用的操作架构及其与工作流类型的兼容性。
4. 对于手动工作流，为工作流所需的值定义最精简的 inputs.schema。对于对话式和定时工作流，请省略根级 inputs，并直接从 $input 读取触发器字段。
5. 列出所需操作和外部集成，然后将每项映射到现有操作名称，或注明自定义操作设计。
6. 仅在操作需要时添加绑定，尤其是 AI 模型、工具、MCP 或记忆绑定。
7. 明确处理记忆：尽可能使用现有的记忆定义 ID／slug，或单独记录所需的记忆定义。
8. 先构建简单的流程，再仅在用例需要时添加分支、并行处理、循环、重试和人工交接。
9. 先验证 YAML 可以解析，再进行运行时验证。重新检查每个表达式标量都已加引号或使用块样式，尤其是三元表达式、正则表达式、对象字面量、数组字面量，以及包含 :、?、{}、[]、# 或引号的表达式。
10. 在使用 definitionYml 调用工作流创建／更新工具或 API 之前，针对实际要提交的 YAML 字符串执行相同的解析和表达式引号检查。
11. 在提供最终 YAML 前，验证表达式、任务引用、绑定基数和最终输出。

审查流程

1. 在进行架构审查前，先将 YAML 解析为 YAML。任何以 = 开头的纯 JSONata 标量都应判定为失败；表达式必须加引号或使用块样式，以免三元运算符中的冒号以及正则表达式／对象语法破坏 YAML 解析。
2. 如果已配置 Hexabot MCP 服务，则使用它检查运行时操作、绑定、记忆和工作流；否则应说明缺少运行时验证，并在需要时邀请用户进行配置。
3. 根据 WorkflowDefinitionSchema 检查 YAML 结构，并标记对话型或定时工作流中的根级 inputs。
4. 检查每个 flow 任务引用是否都存在于 defs 中。
5. 根据运行时操作注册表、Hexabot MCP 服务或源文件检查操作名称。
6. 检查每种绑定的类型、基数、def 引用、嵌套绑定以及受支持绑定的允许列表。
7. 检查工作流类型是否匹配：除非源代码表明支持，否则不应在手动或定时工作流中使用对话型操作。
8. 检查大模型提示词是否存在提示词注入风险、秘密泄露、输出含糊或缺少结构化输出架构等问题。
9. 通过 defaults.settings、任务设置、重试、回退分支和人工升级，检查错误处理机制。
10. 按严重性报告发现的问题，并在可能的情况下提供具体的 YAML 路径和仓库引用。

输出格式

• 新建工作流：提供简短的假设说明、需要在 YAML 外配置的工作流元数据、以 yaml 围栏代码块呈现的最终 YAML，以及验证说明。
• 工作流审查：先按严重性排序列出发现的问题，然后提供未决问题、建议的补丁片段和验证步骤。
• 操作设计：提供操作名称、工作流类型、输入架构、输出架构、设置架构、受支持的绑定、幂等性说明、错误、可观测性和测试预期。
• 演示用例设计：提供受众、演示叙述、工作流类型、触发器、操作、绑定／记忆、成功路径、失败路径以及 UI 中的演示内容。

参考资料

• 将用例转换为工作流 YAML 时，请阅读 references/workflow-authoring-guide.md。
• 设计或审查自定义操作时，请阅读 references/action-design-guide.md。
• 审查现有工作流时，请阅读 references/workflow-review-checklist.md。
• 用户需要润色后的响应格式时，请阅读 references/output-templates.md。
• 示例工作流骨架请参见 examples/customer-support-triage.workflow.yaml。
• 带有记忆、MCP 和自定义操作的高级 Agent 循环示例请参见 examples/contact-calendar-agent.workflow.yaml。