AgentEvolver 源码解读 · 第 1 章：工程骨架与训练入口
> 此篇为 C:/GitHub/AgentEvolver/ 真本源码之通读。前作《深度研究》已把三大机制讲成「鸟瞰」，此番自顶向下，先剖骨架——进程如何编排、训练主循环何在、配置如何收口。读毕此章，再去第 2–6 章看各模块，便知它们挂在哪根梁上。
---
一、仓库三层与「壳」「核」之分
AgentEvolver 不是从零造轮，而是骑在 veRL 之上的自进化改装车。目录分三层：
| 层 | 路径 | 角色 |
|---|---|---|
| 入口壳 | launcher.py、agentevolver/main_ppo.py | 进程编排、Hydra 拉起训练 |
| 机制核 | agentevolver/module/* | task_manager / exp_manager / adv_processor / agent_flow / context_manager |
| 环境边 | env_service/* | 与 AppWorld/BFCL/OpenWorld 对话的 HTTP 服务 |
launcher.py 只是壳，main_ppo.py 才是训练循环真核，而 module/trainer/ae_ray_trainer.py 的 AgentEvolverRayPPOTrainer 才是真正 fit() 的地方。三层逐级下沉，配置沿路注入。---
二、launcher.py：进程编排器
launcher.py 干四件事，件件是「脏活」：
1. 起伴生服务（pty_launch）
--with-appworld / --with-reme / --with-logview 各对应一个 pty_launch：def pty_launch(service_name, success_std_string="Starting server on"):
service_path = os.environ.get(f'{service_name.upper()}_PATH')
service_script = os.environ.get(f'{service_name.upper()}_SCRIPT')
companion = LaunchCommandWhenAbsent(
full_argument_list=[service_script], dir=service_path,
tag="appworld_env_service", use_pty=True)
companion.launch(launch_wait_time=1800, success_std_string=success_std_string)
本质是 utils/daemon.py 的 LaunchCommandWhenAbsent：用伪终端起子进程，等日志里冒出 success_std_string 才算活。ReMe 等的是 Uvicorn running on，AppWorld 等的是 Starting server on。这就解释了上一章「curl /healthz 验活」——服务起没起，launcher 和 curl 看的是同一根弦。
2. 配置备份与占位符回填
launcher.py 把 ./config 和 ./agentevolver 整包拷进 launcher_record//backup ，并把 yaml 另存为 yaml_backup.yaml，随后递归替换占位符：config = _replace_placeholder_in_config(
config, placeholder="${trainer.experiment_name}", replacement=exp_name)
_replace_placeholder_in_config 是个深度 walk——遍历 dict/list，凡字符串里含 ${trainer.experiment_name} 一律换成实名。此举让「实验名」一处定、处处随，避免多服务各喊各名。
3. 训练子进程
最后subprocess.run 拉起真核：cmd = [sys.executable, '-m', args.target, # agentevolver.main_ppo
'--config-path', os.path.abspath(exe_exp_base),
'--config-name', os.path.basename(exe_yaml_path)]
注意 args.target 默认 agentevolver.main_ppo——壳到此交棒。
4. 善后
--kill / -k 用 pgrep+kill -TERM/-KILL 清理残留 ray/python 进程（排除 vscode 与自身），防端口/显存被占。---
三、main_ppo.py：训练主循环真核
@hydra.main(config_path="../config", config_name="script_config") 是入口。run_ppo 里先 ray.init，注入 runtime_env（TOKENIZERS_PARALLELISM、VLLM_USE_V1=1、WANDB_* 等），再断言 max_prompt+max_response ≤ max_model_len，而后把活甩给 Ray actor：
runner = TaskRunner.remote()
ray.get(runner.run.remote(config))
TaskRunner.run 才是重头戏，按序：
1. 落盘模型：copy_to_local 把 HF checkpoint 拉到本地；hf_tokenizer / hf_processor 初始化。
2. 选 worker 类：fsdp 策略下，从 module/exp_manager/het_fsdp_worker.py 取 HETAsyncActorRolloutRefWorker（异步 rollout）或 HETActorRolloutRefWorker。这「HET」前缀即第 3 章异策略损失的载体。
3. 资源与角色映射：ResourcePoolManager + role_worker_mapping（ActorRollout / Critic / RewardModel / RefPolicy）。
4. 奖励函数：load_reward_manager 同时给训练集与验证集各造一个。
5. 双 TaskManager：
train_task_manager = TaskManager(..., mixture_strategy=UnifiedMixtureStrategy(...), ...)
val_task_manager = TaskManager(..., mixture_strategy=OriginalOnlyStrategy(), ...)
训练集用混合策略（原任务+合成），验证集只用 OriginalOnlyStrategy——保证评测不被合成数据污染。
6. 交棒训练器：AgentEvolverRayPPOTrainer(...).init_workers() 后 .fit()。
另有两个小机关值得记：kl_penalty 可按环境变量 DEBUG_ARG=kl_control monkeypatch（前端 token 加权 KL）；get_custom_reward_fn 用 importlib 动态载入用户自定义奖励函数。
---
四、config/agentevolver.yaml：总配置图
一份 yaml 收尽六段。要点：
algorithm.adv_estimator: grpo——默认纯 GRPO（关 ADCA 时即上一章「最小化训练」）。data.max_response_length: 21580、actor_rollout_ref.rollout.max_model_len: 25580——长轨迹是大头。rollout.n: 8、multi_turn.max_steps: 30、context_template: linear——多轮、每组 8 条、线性上下文。env_service.env_url: http://127.0.0.1:8080——指向上一章起的 AppWorld 服务。task_manager/exp_manager/attribution_driven_credit_assignment三段，正是第 2/3/4 章的配置落点。
training 段还有 total_epochs: 40、test_freq: 10、val_before_train: true——每 10 步验一次，开训前先验。---
五、自顶向下入口链（一张图记牢）
launcher.py
└─ pty_launch → 起 appworld / reme / logview 伴生服务
└─ subprocess → python -m agentevolver.main_ppo
└─ run_ppo → ray.init
└─ TaskRunner.run
├─ copy_to_local + tokenizer
├─ HET*Worker (fsdp)
├─ load_reward_manager
├─ TaskManager ×2 (train/val)
└─ AgentEvolverRayPPOTrainer.fit()
├─ env_client.step → env_service(/step)
├─ AgentFlow.execute（第 5 章）
├─ adv_processor（第 4 章，开则覆盖 advantages）
└─ exp_manager（第 3 章，开则注入/剥离经验）
一句话收口：launcher 管「伴生服务与配置」，main_ppo 管「Ray 编排与 worker 选型」，ae_ray_trainer 管「fit 主循环」；三大机制作为可插拔开关，在第 4/3 章的钩子里改写优势与上下文。下一章，看任务从哪来——Self-Questioning 之 task_manager。