# HATT v3.4：从训练框架到任务选择

本章解释本轮 `graph_model=hatt_v3_4`、`hatt_candidate_aa_mode=learned`、`hatt_aa_task_context=true` 的实际路径。网络沿用共享前馈 MAPPO actor 接口，隐空间宽度 128、4 个关系 head。当前 actor 参数数为 **362,697**；关闭任务上下文的 noctx 为 **362,185**，相差 512。[参数核对](evidence/implementation_checks.json)

## 完整计算链

```text
每个机器人的 Dict 观测 + 合法动作掩码
      ↓
ego / others / tasks 独立实体编码
      ↓
AA(i,k)：我与队友的关系，读取队友当前服务任务摘要
AT(i,j)：我与候选任务的关系
AT(k,c_k)：队友与其当前任务的关系，复用 AT 参数
      ↓
全局均值汇总 → 当前机器人上下文
按当前 Deliver 联盟路由 AA 与成员 AT → 候选任务上下文
      ↓
共享 CandidateEdgeDecoder → 每个任务的 logit → mask → Categorical
      ↓
event 激活机器人执行新选择，其他机器人保持现有任务
      ↓
环境交互 → 结构化 buffer → GAE / PPO 更新

全局 state + focal one-hot → 集中式 MLP critic → Vφ(s,i)
```

入口为 `train/train.py`，训练循环为 `runner/shared/macf_runner.py`，策略封装为 `gaRMAPPOPolicy.py`。图网络接在 actor 路径，critic 使用 `R_Critic` 的集中式状态特征。[策略构造](code_view/algorithms/algorithm/gaRMAPPOPolicy.py.html#L271)

## 第一层：MAPPO 与 Actor–Critic

参数共享 actor 对每名机器人输出任务概率；集中式 critic 根据全局任务和队友状态以及 focal 标记预测该机器人的回报。训练使用当前策略与环境交互的 on-policy 数据。第 t 步记录观测、状态、动作、旧 log probability、价值预测、奖励及各类 mask。[runner](code_view/runner/shared/macf_runner.py.html)、[buffer](code_view/utils/shared_gat_buffer.py.html)

GAE 使用 γ=0.99、λ=0.95 聚合时序差分残差。Actor 的 PPO 目标包含

```text
r_t = exp(log πθ(a_t|o_t) − log πold(a_t|o_t))
Lpolicy = −E[min(r_t A_t, clip(r_t,1−ε,1+ε) A_t)]
```

以及熵项；critic 根据估计回报训练，启用 ValueNorm。更新使用 active mask 选择决策样本，mask/bad_mask 处理死亡和截断。当前 `active_masks` 来自环境的重决策日程，物理步数据连续进入 buffer。[PPO 更新](code_view/algorithms/algorithm/ga_rmappo.py.html#L127)、[回报计算](code_view/utils/shared_gat_buffer.py.html)

| 本轮训练项 | 数值 |
|---|---:|
| 最大训练 environment episodes | 1500 |
| 名义环境步预算 / rollout 长度 | 1,125,000 / 750 |
| rollout 环境数 | 1 |
| PPO epochs / mini-batches | 6 / 1 |
| actor、critic 初始学习率 | 0.0001，线性衰减 |
| PPO clip / entropy coefficient | 0.1 / 0.03 |
| target KL / max clip fraction | 0.03 / 0.35 |
| 最大梯度范数 | 0.5 |
| critic hidden size / layer_N | 64 / 1 |
| recurrent policy | false |

1500 是完成的环境回合数量上限，一个 750 步 rollout 可以包含多个较早结束的回合。因此跨模型学习曲线应使用各自记录的实际 environment steps；本包的 v3.4 曲线保留 training episode 坐标。[冻结研究参数](evidence/research_settings.csv)

PPO 和 MAPPO 为训练框架依据，引用 [PPO](https://arxiv.org/abs/1707.06347) 与 [MAPPO](https://arxiv.org/abs/2103.01955)。工程的研究变量主要位于 actor 的关系表示。

## 第二层：实体编码与离散归属

`FeatureEncoder` 分别把 ego、others、tasks 映射到 128 维隐向量。编码器由线性层、ReLU 和 LayerNorm 组成。ego、others 中的 coalition 编号在进入连续编码器前清零，同时保留原始编号用于构造离散关系：当前任务、是否同一配送联盟，以及成员属于哪个候选任务。[实体编码](code_view/algorithms/algorithm/HATTV34Network.py.html#L194)、[FeatureEncoder](code_view/algorithms/algorithm/HATTV20Network.py.html)

设计目的在于让任意任务编号通过关系索引使用，实体状态通过共享函数编码。实现结果是：任务及其归属同步重排后，解码输出随任务顺序重排。本次执行 `tests.test_hatt_network.HATTV34NetworkTest`，5 项测试通过，其中包含继承的任务重排检查与 noctx/v3.3AA 对应检查。[测试代码](code_view/tests/test_hatt_network.py.html#L752)

## 第三层：同形式、独立参数的 AA 与 AT 关系

两类关系使用 `TypedRelationEdge`。对关系类型 r 的每个 head h，给定 source embedding z_s、target embedding z_t 和边特征 e，计算

```text
q = Wq[r,h] z_s
k = Wk[r,h] z_t
v = Wv[r,h] z_t
g[r,h] = sigmoid(q·k / sqrt(d_head) + edge_bias[r,h](e))
m[r] = Wout[r] concat_h(g[r,h] v)
```

gate 是逐边 sigmoid 权重。AA 和 AT 使用各自的 Wq、Wk、Wv、edge_bias 和 Wout。无效边的 gate 通过 mask 置零。AA 的对照方式包括 learned、固定 0.5 的 uniform，以及输出清零的 zero。[算子实现](code_view/algorithms/algorithm/HATTV33AANetwork.py.html#L21)

AT(i,j) 的三维边特征为任务相对位置两维和“当前是否分配到 j”。AA(i,k) 的基础三维边特征为队友相对位置两维和“是否属于同一配送联盟”。q·k 项同时提供编码后的机器人状态信息。[关系特征](code_view/algorithms/algorithm/HATTV34Network.py.html#L114)

这层的设计目的，是让队友关系与任务匹配使用一致的计算接口，各自学习所需参数。v3.3AA 的 learned/uniform-trained 对照为学习关系权重提供了效果记录；冻结权重的 uniform/zero 实验记录了推理期消息变化对策略行为的影响。详见 E04。[实验依据](04_experiments.md)

## 第四层：v3.4 的服务任务条件

对边 (i,k)，查找队友 k 当前服务的任务 c_k，追加四个标量：任务剩余需求、优先级、所属联盟的载荷比聚合、成员数比例。只在 c_k 为 Deliver 时保留这四维，其他任务类型将这部分上下文置零。[实现](code_view/algorithms/algorithm/HATTV34Network.py.html#L146)

在 compact schema 下，它们精确对应

```text
[D(c_k)/500,
 priority(c_k),
 Σ_{m≠i, living(m), c_m=c_k} (load_m/init_load_m) / N,
 #{m≠i:living(m), c_m=c_k} / N]
```

聚合从 `others` 读取，所以包含 k、排除 observer i。四维服务摘要进入 AA 的 edge_bias；AA 的 source/target 编码保持原来的输入。新增参数只来自 edge_bias 第一层新增的四列，4×128=512。[上下文聚合](code_view/algorithms/algorithm/HATTV34Network.py.html#L151)

设计目的，是让同一对机器人之间的关系权重随队友服务任务的状态而改变。当前载荷摘要的单位是归一化载荷比例，其含义由上式确定。它适合作为服务资源的学习特征，实际物理载荷与成员退出后的任务后果由环境快照和闭环评估读取。[E05](04_experiments.md)

本轮三 seed 留出测试中，taskctx 的 validation-best 成功率 65.10%，noctx 为 62.50%；last 为 61.72% 和 62.50%。这组对照提供“加入任务条件之后整体行为发生了怎样变化”的完整记录。论文关于源联盟可替代性的研究目标与对应评估入口见 [研究章](01_research.md)。

## 第五层：把关系消息组织到对应候选

网络计算 AT(k,c_k)，使用与 AT(i,j) 相同的 AT 参数，输入为队友 embedding、其当前任务 embedding、任务相对队友的位置与 assigned=1。这个消息描述成员对当前服务任务的关系。[成员 AT](code_view/algorithms/algorithm/HATTV34Network.py.html#L242)

对候选配送任务 j，取当前属于 j 的其他存活成员集合 C_j\{i}，把 AA(i,k) 和 AT(k,j) 分别求和，并除以 sqrt(max(1,成员数))。对应候选表示融合五部分：任务 embedding、AT(i,j)、成员 AT 聚合、AA 聚合、成员数/N，然后与原任务 embedding 作残差连接及 LayerNorm。[路由与归一化](code_view/algorithms/algorithm/HATTV34Network.py.html#L282)

同时，所有有效 AA 消息和所有可用 AT 消息分别取均值，结合 ego embedding 形成当前机器人的全局上下文。全局汇总和候选局部汇总复用同一批关系消息。[全局融合](code_view/algorithms/algorithm/HATTV34Network.py.html#L275)

设计目的，是让候选 j 的联盟信息对应它实际拥有的成员。任务类型参与路由：Deliver 接收配送成员消息，Explore、Idle、Resupply 保留自身候选特征和 AT 匹配。历史 detached 实验为特殊控制槽的关系语义提供了依据；正式 v2.0 结构消融为按任务聚合联盟信息提供了效果依据。[E01、E12](04_experiments.md)

## 第六层：共享解码与高层动作

沿用的 `CandidateEdgeDecoder` 对每个候选使用同一评分网络，将机器人上下文、候选上下文和 AT 边特征映射为 logit。非法动作置为极小 logit，形成 Categorical 分布。训练时采样，正式测试时确定性选取最大概率动作。[actor 分布构造](code_view/algorithms/algorithm/HATTV20Network.py.html#L566)

在同一决策时刻，各活跃机器人基于自己的 observer 输入给出任务选择；未激活机器人保持现有任务。因此联合策略可以写作活跃个体分类分布的乘积，并为未激活个体附加保持当前动作的确定性项。联盟由执行后的共同任务归属形成。[runner 动作处理](code_view/runner/shared/macf_runner.py.html)

## 设计与证据对应

| 设计 | 在计算流程中的目的 | 创新性定位 | 已有功能/效果依据 |
|---|---|---|---|
| MAPPO、GAE、集中式 critic | 从执行回报学习任务策略 | 通用训练框架 | 六个 v3.4 训练任务完成；来源为 PPO/MAPPO 方法 |
| 独立实体编码与共享候选打分 | 统一处理任务候选，维护重编号对应 | 任务策略的结构基础 | 任务槽重排实验、v3.4 网络测试 |
| AA/AT 独立关系参数 | 分别学习队友关系与任务匹配 | v3.3AA/v3.4 关系表示组成 | learned/uniform-trained 同条件结果 |
| 当前归属驱动的候选成员路由 | 把成员信息送入对应配送候选 | 任务条件化关系策略的组成 | 正式联盟上下文消融、路由代码与测试 |
| 服务任务上下文进入 AA | 让关系权重读取成员已有服务任务 | v3.4 新增设计 | 512 参数扩展、taskctx/noctx 三 seed 结果 |
| sector coverage | 提供可执行探索目标与搜索历史 | 环境观测与任务实现 | coverage/geometry 因子实验 |
| event 日程 | 将任务决策与物理执行连接 | 环境决策协议 | 事件注入实验中的响应提前记录 |

该表用于论文分层：主方法章节围绕候选任务上的关系信息组织，训练设置章节给出 MAPPO，环境章节给出 coverage 与 event。每项效果解释使用对应实验条件。