Back to Details

ralph-hats

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ralph Hats

Ralph Hats

Use this skill to operate the full Ralph hat lifecycle for user-authored hat collections.

使用此技能可操作用户自定义hat集合的完整Ralph hat生命周期。

Use This Skill For

适用场景

Creating a new hat collection in
```
.ralph/hats/
```
Inspecting an existing hat collection and explaining its topology
Validating trigger routing, event flow, and completion behavior
Improving or refactoring hats for clearer roles and safer routing
Recommending better orchestration patterns for a Ralph workflow

在
```
.ralph/hats/
```
目录中创建新的hat集合
检查现有hat集合并解释其拓扑结构
验证触发器路由、事件流和完成行为
优化或重构hat，使其角色更清晰、路由更安全
为Ralph工作流推荐更优的编排模式

Core Assumptions

核心假设

Core runtime config already lives in
```
ralph.yml
```
or another
```
-c
```
source.
User-authored hats are stored separately and passed with
```
-H
```
.
This skill operates public hat collections, not Ralph built-in presets.

核心运行时配置已存于
```
ralph.yml
```
或其他
```
-c
```
指定的源文件中。
用户自定义的hat单独存储，并通过
```
-H
```
参数传入。
此技能仅用于操作公开的hat集合，而非Ralph内置预设。

Workflow

工作流程

If a hats file already exists, read it first and explain the current topology before proposing changes.
If creating a new workflow, write it to
```
.ralph/hats/<name>.yml
```
.
Keep the hats file focused on hats-only data. Leave runtime limits and other core config in the main config file.
Validate with
```
ralph hats validate
```
.
Visualize topology with
```
ralph hats graph
```
when the event flow is not trivial.
Use
```
ralph hats show <hat>
```
when you need to inspect one hat's effective configuration.
When the user wants stronger confidence, run a targeted
```
ralph run -c ... -H ... -p "..."
```
exercise or provide the exact test command.

若hat文件已存在，在提出修改建议前，先读取文件并解释当前的拓扑结构。
若创建新工作流，将其写入
```
.ralph/hats/<name>.yml
```
文件。
hat文件仅保留与hat相关的数据。将运行时限制和其他核心配置留在主配置文件中。
使用
```
ralph hats validate
```
命令进行验证。
当事件流较为复杂时，使用
```
ralph hats graph
```
命令可视化拓扑结构。
若需检查单个hat的有效配置，使用
```
ralph hats show <hat>
```
命令。
当用户需要更强的验证信心时，运行针对性的
```
ralph run -c ... -H ... -p "..."
```
测试，或提供准确的测试命令。

Guardrails

约束规则

Only use hats-file top-level keys that Ralph accepts today:
```
name
```
,
```
description
```
,
```
events
```
,
```
event_loop
```
,
```
hats
```
.
In a hats file,
```
event_loop
```
is only for hats overlay keys such as
```
starting_event
```
and
```
completion_promise
```
.
Never use
```
task.start
```
or
```
task.resume
```
as hat triggers. Ralph reserves those for coordination. Use semantic delegated events like
```
work.start
```
,
```
review.start
```
, or
```
research.start
```
.
Each trigger must route to exactly one hat.
Keep
```
description
```
populated on every hat.
Prefer
```
events:
```
metadata when custom event names would otherwise be opaque.
Do not write user workflows into
```
presets/
```
from this skill.

仅使用当前Ralph支持的hat文件顶级键：
```
name
```
、
```
description
```
、
```
events
```
、
```
event_loop
```
、
```
hats
```
。
在hat文件中，
```
event_loop
```
仅用于hat覆盖键，如
```
starting_event
```
和
```
completion_promise
```
。
切勿将
```
task.start
```
或
```
task.resume
```
用作hat触发器。这些事件由Ralph预留用于协调。使用语义化的委托事件，如
```
work.start
```
、
```
review.start
```
或
```
research.start
```
。
每个触发器必须仅路由到一个hat。
为每个hat填写
```
description
```
字段。
若自定义事件名称不清晰，优先使用
```
events:
```
元数据。
切勿通过此技能将用户工作流写入
```
presets/
```
目录。

Output Expectations

输出要求

When editing or creating hats, produce the file changes and the validation result.
When only inspecting, produce a concise topology summary, the main risks, and concrete improvement options.

编辑或创建hat时，需提供文件变更内容和验证结果。
仅进行检查时，需提供简洁的拓扑结构摘要、主要风险以及具体的优化方案。

Read These References When Needed

必要时参考以下文档

For current hats schema and supported fields:
```
references/schema.md
```
For command recipes and validation workflow:
```
references/commands.md
```
For pattern and file examples:
```
references/examples.md
```

当前hat的 schema 和支持字段：
```
references/schema.md
```
命令示例和验证工作流：
```
references/commands.md
```
模式和文件示例：
```
references/examples.md
```