Agents
Agent 索引
使用 UniRL 文档作为 coding-agent 上下文时从这里开始。
本页面向人类阅读，帮助你理解 agent 应该如何读 UniRL。/llms.txt 是给工具和 agent 发现文档用的机器入口，不应该再拆成一个新的 docs category。
Agent 如何使用这些文档
Agent 应该把文档当成 routing layer，而不是源码替代品：
- 先打开
/llms.txt或/md/agents/index.md，发现当前维护中的文档入口。 - 根据下面的任务表，选择最接近的页面和 package README。
- 修改前继续读附近源码实现。
- 需要局部上下文时优先用
/md/<docs-slug>/index.md，只有需要单文件 corpus 时再用/llms-full.txt。
因此 docsite 里只需要突出 Agent 索引；/llms.txt 保持为根级机器入口。
基本原则
- 维护中的训练入口是
python -m unirl.train_diffusion --config-name=<domain>/<recipe>（以及train_vlm/train_pe/train_unified_model）。 - 分桶的
examples/<domain>/<recipe>.yaml文件是权威配置面。 - package README 是离代码最近的局部 contract。
- 不要从 stale scratch docs 或 ignored local files 推断运行行为，除非用户明确指向它们。
按任务阅读
| 任务 | 先读 |
|---|---|
| 运行或验证 recipe | /zh/docs/getting-started/first-run，然后 examples/ 下的启动器 |
| 理解配置 | /zh/docs/configuration/hydra，然后 unirl/config/README.md |
| 选择实验 | /zh/docs/configuration/experiments，然后 examples/<domain>/<name>.yaml |
| 理解 runtime flow | /zh/docs/architecture/overview，然后 unirl/README.md |
| 修改 rollout engine | unirl/rollout/README.md |
| 开发 train stack 或 training backend | /zh/docs/architecture/trainer-v2，然后 unirl/train/readme.md |
| 修改 GRPO / NFT / DPPO loss | unirl/algorithms/README.md |
| 修改 SDE kernel、sigma schedule 或 log-prob path | unirl/sde/README.md |
| 修改 reward | /zh/docs/guides/rewards，然后 unirl/reward/README.md |
| 调试 trainer-to-rollout weight sync | unirl/distributed/weight_sync/README.md |
| 准备 prompt 数据 | /zh/docs/guides/data-preparation |
| 添加数据或模型 artifact | /zh/docs/guides/data-and-models |
| 调试多机运行 | /zh/docs/guides/multinode |
Agent Markdown 入口
这些入口固定输出英文，避免中英混杂。入口说明集中放在这里，不再散落到每个 docs 页面：
| Endpoint | 用途 |
|---|---|
/llms.txt | compact discovery index and access guidance |
/llms-full.txt | full English Markdown corpus |
/md/agents/index.md | English Agent Index |
/md/configuration/hydra/index.md | English Hydra configuration page |
安全编辑策略
- 根据任务表定位 owner package。
- 阅读对应 package README 和最接近的现有实现。
- 优先使用 typed config dataclass，不做 ad hoc string parsing。
- 只有 runnable behavior 变化时才新增或更新 recipe。
- 启动作业前先做 Hydra compose check。