ralph-hats

Ralph Hats

使用此技能操作用户编写的帽子集合的完整 Ralph 帽子生命周期。

适用场景

• 在 .ralph/hats/ 中创建新的帽子集合
• 检查现有帽子集合并说明其拓扑结构
• 验证触发器路由、事件流和完成行为
• 改进或重构帽子，让角色更清晰、路由更安全
• 为 Ralph 工作流推荐更好的编排模式

核心假设

• 核心运行时配置已存放在 ralph.yml 或其他 -c 来源中。
• 用户编写的帽子单独存放，并通过 -H 传入。
• 此技能用于操作公开的帽子集合，而不是 Ralph 内置预设。

工作流

1. 如果帽子文件已存在，先阅读并说明当前拓扑结构，再提出更改建议。
2. 如果要创建新工作流，将其写入 .ralph/hats/<name>.yml。
3. 保持帽子文件只包含帽子相关数据。将运行时限制和其他核心配置留在主配置文件中。
4. 使用 ralph hats validate 进行验证。
5. 如果事件流并非简单直接，使用 ralph hats graph 将其可视化。
6. 如果需要检查某个帽子的有效配置，使用 ralph hats show <hat>。
7. 如果用户希望获得更高把握，可以运行针对性的 ralph run -c ... -H ... -p "..." 测试，或提供确切的测试命令。

防护措施

• 仅使用 Ralph 当前接受的帽子文件顶层键： name、description、events、event_loop、hats。
• 在帽子文件中，event_loop 仅用于帽子覆盖配置键，例如 starting_event 和 completion_promise。
• 切勿将 task.start 或 task.resume 用作帽子触发器。Ralph 将这些事件保留用于协调。请使用语义明确的委派事件，例如 work.start、 review.start 或 research.start。
• 每个触发器必须只路由到一个帽子。
• 确保每个帽子都填写了 description。
• 如果自定义事件名称不够直观，优先使用 events: 元数据。
• 不要通过此技能将用户工作流写入 presets/。

输出要求

• 编辑或创建帽子时，提供文件更改和验证结果。
• 仅进行检查时，提供简明的拓扑摘要、主要风险和具体的改进选项。

按需阅读以下参考资料

• 当前帽子架构和支持字段：references/schema.md
• 命令示例和验证工作流：references/commands.md
• 模式和文件示例：references/examples.md