# HATT / MACF 工程与研究交接

以 **v3.4 服务任务上下文与候选关系建模**为方法主线，汇总已完成的训练、行为干预、消融、基线和跨环境实验。整理日期：2026-09-07 至 2026-09-08。

报告分别标明研究目标、当前实现和实验观察。环境参数由冻结训练配置与代码核对；实验表保留训练 seed、checkpoint 选择与评估场景协议。

| 章节 | 内容 |
|---|---|
| [1 · 论文问题与研究目标](01_research.md) | 主贡献的组织、结构性质、服务承诺目标与文献定位 |
| [2 · 环境与 baseline](02_environment.md) | 物理对象、episode、观测/状态/动作、共享信息、奖励及方法选择 |
| [3 · v3.4 方法](03_method.md) | MAPPO、实体编码、AA/AT、服务任务摘要、候选路由、解码 |
| [4 · 实验汇总](04_experiments.md) | 12 组代表性结果、统一条件表格与具体证据 |
| [5 · 关键代码](05_code.md) | 调用链、逐行阅读、源码副本与哈希 |
| [6 · 来源与复核](06_sources.md) | 会话决策、原始实验位置、数据重建与参考文献 |
| [7 · 后续交接](07_handoff.md) | 已设计的源条件配对、后续情境实验与工程接口 |

需要接手实现时，可先阅读环境、方法、代码三章。需要写论文时，可按研究目标、实验汇总、后续验证的顺序阅读。

[下载完整交接包](handoff_bundle.zip) · [下载合并 Markdown](HANDOFF.md) · [正式实验 CSV](evidence/formal_aggregate.csv) · [来源哈希](evidence/sources.json) · [检查记录](bundle_checks.json)

完整包包含离线可读 HTML、Markdown、派生数据、源码快照和生成脚本。原始模型与训练产物继续保存在项目 runs 下；包内来源索引给出对应相对路径。


# 论文问题与研究目标

本交接以 HATT v3.4 的实际实现为方法基准。研究意图依据 2026-09-05 的 Codex 论文讨论与 2026-09-06 的 Claude 实验决策；数值结论依据本包的原始结果索引。会话决定研究方向，代码说明实现，实验说明效果。[会话依据](06_sources.md)

## 研究问题

工程研究一支资源和运动能力不同的机器人队伍，如何在任务逐渐被发现、载荷持续消耗、机器人需要补给的过程中，选择当前服务任务。选择同一配送任务的机器人形成该任务的联盟。任务的剩余需求随实际交付下降，联盟成员随任务选择变化。当前物理模型因此对应持续配送过程中的动态资源分配。[环境实现](02_environment.md)

论文可以围绕这一问题展开：**如何使机器人对候选任务的判断显式依赖于该任务当前的联盟成员，以及成员已经承担的服务任务？** 这一问题将本项目的编码、AA/AT 关系、联盟聚合和任务解码连成同一条方法逻辑。它来自 v3.3AA 的候选成员路由与 v3.4 的服务任务上下文设计。[实现公式](03_method.md)

为便于讨论，记机器人 i 的能力及资源为 x_i，任务 j 的状态为 y_j，当前所属任务为 c_i，配送联盟为 C_j={i:c_i=j}。论文希望学习的任务评分可写为

```text
score(i,j) = F(x_i, y_j, {关系(i,k), 关系(k,j): k∈C_j}, 团队上下文)
```

这个式子是对当前计算图的信息依赖描述。v3.4 的具体 F、集合聚合和有效成员范围见方法章，最终策略通过 PPO 回报训练。[v3.4 forward](code_view/algorithms/algorithm/HATTV34Network.py.html#L194)

## 希望形成的主贡献：围绕任务的关系建模

**以任务为条件组织智能体间的依赖。** 同一名队友对不同任务选择的意义，取决于队友当前归属、服务目标及可贡献资源。v3.3AA 将 i–k 的 AA 消息路由到 k 当前所属的配送任务，并把 k–任务的 AT 消息一同聚合；v3.4 再让 AA 权重读取 k 服务任务的需求、优先级和联盟摘要。这样，候选任务表示同时包含“我与这个任务的匹配”和“这个任务已有成员与我的关系”。[AA/AT 算子](code_view/algorithms/algorithm/HATTV33AANetwork.py.html#L21)、[候选路由](code_view/algorithms/algorithm/HATTV34Network.py.html#L282)

对应的论文创新点可以组织为：**面向动态联盟分配的任务条件化关系策略。** 写作时重点说明关系的条件变量、消息进入哪个候选、两类关系如何共享计算形式，以及最终如何影响任务概率。独立的 AA/AT 参数、共享候选解码器和服务任务摘要是这项贡献的具体实现。[方法层次表](03_method.md)

当前已有两层依据。正式结构实验中，v2.0 完整联盟上下文的五 seed 留出成功率为 72.19%，去联盟上下文为 61.88%；v3.3AA 的 learned 权重三 seed 成功率为 62.50%，uniform-trained 为 54.17%。它们分别为任务上的联盟汇总、可学习成员加权提供了实验依据。v3.4 taskctx 的所选 checkpoint 为 65.10%，同期 noctx 为 62.50%，提供了服务任务上下文的初步效果记录。各项对照范围和末期结果见 E01、E04、E05。[实验结果](04_experiments.md)

## 深化目标：服务承诺与重组价值

成员转移同时改变源任务与目标任务的资源供给。论文希望建立的进一步主张是：策略根据源任务对成员的依赖程度、目标任务价值以及实际转移过程，调整重组选择。此处“服务承诺”具体指当前已分配到任务的机器人及其资源；它与任务是否已经获得实际交付分别记录。[源条件评估代码](code_view/scripts/analysis/evaluate_source_commitment.py.html#L85)

v3.4 已将当前服务任务摘要纳入 AA 权重。现有优先级干预给出了明确的行为依据：v3.3AA learned 在高优先级条件下增加任务概率 0.0419、增加事件任务指派人数 0.490，首次响应平均提前 25.93 步。下一项已设计的验证问题是“该响应如何随源联盟可替代性而改变”；共享状态库、源条件配对和闭环代价是该目标的评估接口。[E06](04_experiments.md)、[交接决策记录](06_sources.md)

在论文中，这一目标可作为主贡献的深化部分，并以“服务任务上下文 → 条件化选择 → 闭环后果”的顺序提供证据。它的当前实现层级是关系权重的条件输入，验证层级是任务价值变化的动作响应。这个定位与实际完成工作相对应。

## 结构性质：任务重编号的一致性

实体编码器和候选解码器在任务之间共享参数，成员集合通过求和/均值聚合。对任务重排，同时重排观测、合法动作掩码和联盟归属映射，动作分布应作相同重排。这个性质为任务 ID 的任意命名提供一致性要求。[重排测试](code_view/tests/test_hatt_network.py.html#L94)

该推导的条件是：所有实体字段和离散归属同步重编号，聚合按相同物理成员执行。共享逐实体函数在重排后逐项对应，集合求和保持相同结果，共享评分器随任务排列输出，因此得到策略等变性。它是本计算图可检查的性质。集合函数与置换等变性已有一般理论基础，相关文献为 [Deep Sets](https://arxiv.org/abs/1703.06114)；本工程将其落实到带有任务归属和动作掩码的联盟策略中。

历史三 seed 的探索槽重排测试中，HATT 成功率均值保持在 69.79%，384 个配对回合的成功/失败标记全部保持一致。v3.4 当前网络测试也通过任务重排与 noctx 对应关系检查。此部分适合作为方法性质与验证依据。[E03](04_experiments.md)、[本次结构核对](evidence/implementation_checks.json)

## 与已选同类方法的关系

| 参考方法 | 文献和官方实现的主要组织方式 | 本项目交接中的研究位置 |
|---|---|---|
| MAPPO | PPO 的多智能体训练实践，提供共享 actor 与集中式价值学习基础 | 作为相同输入、奖励和决策日程下的策略结构对照 |
| CFM / HeteroMRTA | 关注异构任务的联合到达与调度，采用注意力、序贯决策和 constrained flashforward | 作为任务分配/调度方法参照；DelivCoal 适配保留其 pointer 与序贯分配路径 |
| MARL-MRT2A | 使用空间目标策略、路径意图共享和目标修正组织动态联盟分配 | 作为空间策略与任务候选策略的参照；原环境和 DelivCoal 适配分别评估 |

来源：[MAPPO 原文](https://arxiv.org/abs/2103.01955)、[CFM 原文](https://marmotlab.org/publications/73-RAL2025-HetMRTA.pdf)、[MARL-MRT2A 原文](https://arxiv.org/html/2412.20397v2)。表中的实现对应关系详见 [baseline 说明](02_environment.md)。

论文的具体方法贡献应落在当前任务归属驱动的关系路由及服务任务条件输入。PPO、Actor–Critic、注意力和集合聚合分别作为基础方法引用；探索覆盖、路径执行和评估接口作为任务设定与实现依据说明。这一组织方式让每项论文表述都能对应代码或实验。


---

# 环境、信息条件与 baseline

本章以 v3.4 已完成训练的冻结配置和当前 DelivCoal 代码为依据。配置中的研究字段已抽取为 [research_settings.csv](evidence/research_settings.csv)；环境接口尺寸通过实际构造核对。[核对记录](evidence/implementation_checks.json)

## DelivCoal 的物理对象

| 对象 | v3.4 实际设置与工作方式 | 代码依据 |
|---|---|---|
| 地图 | 连续二维正方形，边长 1000；任务和机器人位置随机采样 | [初始化](code_view/envs/delivcoal/env_core.py.html#L721) |
| 智能体 | 总数 12；配置 num_uav=4、num_ugv=8 相加得到总数，Agent 构造时随机采样 Drone/Vehicle 类型 | [Agent](code_view/envs/delivcoal/env_core.py.html#L144)、[生成](code_view/envs/delivcoal/env_core.py.html#L733) |
| 异构能力 | 四个 [0,1) 随机分量分别决定感知半径、移动速度、载荷上限和电量 | [能力映射](code_view/envs/delivcoal/env_core.py.html#L144) |
| 配送任务 | 10 个，位置固定于本回合；初始需求为整数 100–499，初始隐藏 | [任务生成](code_view/envs/delivcoal/env_core.py.html#L750) |
| 任务价值 | priority∈[0.5,1)，deadline fraction∈[0.45,0.95)；通过奖励影响任务服务价值 | [生成](code_view/envs/delivcoal/env_core.py.html#L765)、[奖励](code_view/envs/delivcoal/env_core.py.html#L2036) |
| 危险区 | 10 个随机圆心；本轮默认半径 1.0，路径安全余量 0.5 | [地图](code_view/envs/delivcoal/env_core.py.html#L721)、[绕行函数](code_view/envs/delivcoal/env_core.py.html#L34) |
| 补给站 | 原点 (0,0)，抵达后恢复个体载荷和电量上限 | [补给任务](code_view/envs/delivcoal/env_core.py.html#L791)、[补给](code_view/envs/delivcoal/env_core.py.html#L217) |

若能力向量为 u_i，实际感知半径为 50u_i[0]，每步移动距离为 10+10u_i[1]，初始载荷为 30+floor(70u_i[2])，初始电量为 500+floor(500u_i[3])。存活机器人每个物理步耗电 1。类型标记进入观测，当前这些物理公式由能力分量决定。配置中的 UAV/UGV 感知区间字段被保留，实际发现检查使用上述 `agent.perception`。[Agent 与 discover_along_segment](code_view/envs/delivcoal/env_core.py.html#L144)

机器人沿已规划路径移动。路径规划器读取全部危险圆位置，尝试直线连接，并在圆形危险区附近插入绕行点；actor 读取的状态通过下文的观测接口提供。探测沿实际移动线段检查目标到线段的距离，减少高速移动时漏检目标的情况。[路径与探测](code_view/envs/delivcoal/env_core.py.html#L1004)

## 任务如何完成与联盟如何形成

每名机器人保存当前任务编号 coalition。选择同一 Deliver 槽的存活机器人构成当前配送联盟。机器人抵达任务位置后，一次交付 `min(当前载荷, 剩余需求)`；交付后任务需求下降，需求降至零时标记完成，并向同联盟成员发出完成事件。不同成员可以先后抵达、分次供货；补给后可再次服务任务。[step 配送分支](code_view/envs/delivcoal/env_core.py.html#L1347)

DelivCoal 的任务 `req_vec` 被设为 `[priority,0,0,0]`，四维机器人能力用于感知、移动、携带和续航，任务完成按上述标量交付过程判断。deadline 是软时间要求：它用于紧迫度成本与及时完成奖励；超期任务继续保留到完成或回合结束。[生成与 shaped reward](code_view/envs/delivcoal/env_core.py.html#L765)

这一设定适合研究资源承诺、分次配送与任务服务顺序。多技能同时到达的联合服务要求属于 CFM 原环境的另一种物理设定，参见 [CFM 原文](https://marmotlab.org/publications/73-RAL2025-HetMRTA.pdf)。

## 高层动作与执行过程

| 动作槽 | 数量 / ID | 环境执行 |
|---|---|---|
| Deliver | 10，0–9 | 选择对应任务并沿路径前往配送 |
| Explore | 8，10–17 | 以当前机器人为起点，选择八个方向之一；标称步长 200，方向扰动参数 0.1，目标裁剪到地图边界 |
| Idle | 1，18 | 原地等待，仍参与时间与电量推进 |
| Resupply | 1，19 | 前往原点补给 |

动作合法性由 `available_actions[12,20]` 表示。已发现且尚未完成的配送任务可选；Idle/Resupply 通常可选；过短的边界探索方向被逐机器人屏蔽。[动作掩码](code_view/envs/delivcoal/env_core.py.html#L862)

训练使用 event 重决策：新任务发现或任意任务完成会让存活机器人重新获得任务选择机会；个体动作完成也触发该个体重决策；全体停住时激活存活机器人。其余时间继续执行已有动作。这里的环境事件日程与网络中的 AA sigmoid 权重分别作用于“何时决策”和“如何编码关系”。[事件条件](code_view/envs/delivcoal/env_core.py.html#L902)、[key_event](code_view/envs/delivcoal/env_core.py.html#L1412)

## 一个 episode 的流程

```text
full_random reset：重采样地图、任务、机器人 → 全部机器人获得首次决策机会
      ↓
构造共享已发现任务、队友状态、各自探索候选 → actor 输出合法任务动作
      ↓
更新联盟归属 → 按需规划路径 → 移动、探测、耗电
      ↓
抵达后的交付 / 补给 → 更新任务需求和完成事件
      ↓
计算个体 shaped reward、下一步观测、active mask、终止/截断标志
      ↓
未结束时进入下一物理步；结束后向量环境自动 reset
```

所有配送任务完成、所有机器人死亡或达到 750 步时结束。自然结束与时间截断通过 `bad_mask` 区分，供训练回报处理使用。初始配送任务在 reset 时生成，普通回合中的“新任务”指它被发现；优先级专项实验通过事件注入控制任务揭示时刻。[reset](code_view/envs/delivcoal/env_core.py.html#L813)、[终止处理](code_view/envs/delivcoal/env_core.py.html#L1412)

## Actor 观测与 critic 状态

每个机器人 actor 使用以下 Dict。全部机器人一起推理时，在每个形状前增加一个大小为 12 的 observer 维。

| 字段 | 单个 observer 的形状 | 有效字段 |
|---|---|---|
| ego | [11] | 位置/1000 两维、四维能力、当前联盟编号/19、当前任务类型/3、load/init_load、已发现任务比例、battery/1000 |
| others | [12,11] | 队友位置、四维能力、载荷比、电量、联盟编号、机器人类型、生存标记；observer 自身那一行置零 |
| tasks | [20,6] | 每个动作槽的类型条件化特征；隐藏和已完成配送任务置零 |
| available_actions | [20]，独立输入 | 当前可选任务掩码 |

配送槽六列为 `[x/1000,y/1000,demand/500,剩余deadline比例,priority,type/3]`。开启 coverage 后，探索槽六列为 `[目标x/1000,目标y/1000,候选新增覆盖比例,移动段长度/200,全局未探索比例,type/3]`。Idle、Resupply 使用相同槽宽，类型列说明其语义。任务矩阵因此有 observer 特定的探索行，v3.4 设置 `hatt_shared_task_obs=false`。[观测构造](code_view/envs/delivcoal/env_core.py.html#L1547)

覆盖信息由 20×20 网格中心点近似。移动线段的感知带更新共享覆盖图，候选探索方向估计沿该方向新增的覆盖比例。它是环境维护的探索历史摘要。[coverage](code_view/envs/delivcoal/env_core.py.html#L646)

集中式 critic 使用 `agents[12,11]、tasks[20,8]、global[1]、focal[12,1]`，展平后 305 维。任务状态含全部配送任务及发现/完成标记；global 保存归一化时间；focal 是当前机器人 one-hot。它是环境提供的集中状态特征，完整模拟快照还保存路径、覆盖位图、随机数状态等内部量。[全局状态](code_view/envs/delivcoal/env_core.py.html#L1756)、[focal 构造](code_view/runner/shared/macf_runner.py.html#L570)

## 通信与信息共享假设

DelivCoal 的 actor 可以读取团队所有机器人的状态；任何机器人发现的配送任务进入共享任务状态；覆盖图由团队共同维护。这对应理想的团队信息共享条件。当前 DelivCoal 动作是任务选择，AA 消息在网络前向中计算，观测接口直接提供共享信息。真实通信距离、传输时延和带宽可作为后续环境变量。GymRT2A 使用自己的局部观察与路径意图共享接口，其参数见下一节。[DelivCoal 观测代码](code_view/envs/delivcoal/env_core.py.html#L1665)、[GymRT2A 适配器](code_view/envs/gymrt2a/env_discrete.py.html)

## 奖励与评价

v3.4 调用 `shaped` 奖励。每个机器人获得自己的奖励，包含发现、配送、补给与联盟完成事件，以及共享配送进展、剩余需求和时间成本。代表项为：个体正交付 `0.04×交付量`；共享进展 `25×本步总交付/初始总需求`；联盟完成 `8×priority+8×及时完成项`；剩余需求/紧迫度持续成本；回合全部完成奖励 15，结束时扣除剩余需求及未完成任务成本。该分支的系数直接定义于环境函数。[完整奖励实现](code_view/envs/delivcoal/env_core.py.html#L2036)

Success 表示整个 episode 的配送任务全部完成；任务完成率为完成任务数/10；配送比例为总交付/初始总需求；episode length 是实际物理步数。联盟变化数和 response time 为行为诊断，前者统计归属变化，后者记录任务发现到首次有存活机器人加入的时间。[诊断与记录](code_view/envs/delivcoal/env_core.py.html#L945)、[评估 runner](code_view/runner/shared/macf_runner.py.html)

## 补充环境与迁移方式

| 环境组 | 实际设置 | 已完成工作与对应证据 |
|---|---|---|
| CapCoal 中规模 | 30 个机器人、25 任务、1500 步、nearest 探索、legacy 重决策、random_demand 四维任务需求特征、原 CapCoal 奖励；训练 5000 episodes | HATT v2.0 与 MAPPO64 各 3 seed，独立 128 场景旧 selector 评估，见 E08 |
| GymRT2A 原环境 | 网格地图、不同等级目标、局部视野、邻居通信范围、路径意图共享、A* 运动控制；已复现实验采用 20×20 地图、10 个机器人、100 步回合 | 官方 MARL-MRT2A 5 seed；HATT 空间候选适配 2 seed，见 E09 |
| CFM 官方环境 | 异构技能、任务技能要求、任务持续时间、联合到达与调度，原始 RALTestSet | 官方 checkpoint 50 场景验证及小规模重新训练，见 E10 |

CapCoal 的 `random_demand` 将随机四维任务向量与标量 demand 相关联，实际交付仍按载荷扣减需求。nearest 探索的底层控制器读取最近未发现任务位置。此组与 DelivCoal 的 sector 搜索分开统计。模型在各环境分别训练；GymRT2A 通过专用空间候选 actor 接口迁移。[CapCoal 代码](code_view/envs/capcoal/env_core.py.html)、[GymRT2A 网络](code_view/algorithms/algorithm/HATTGyMRT2ANetwork.py.html)

## Baseline 选取与比较角色

| 方法 | 实际实现 | 比较角色与固定条件 |
|---|---|---|
| MAPPO64 | 展平相同 Dict 输入的 MLP actor，共享 PPO 与集中式 critic | 同训练框架、观测、动作、奖励与 event 日程的结构对照 |
| MAPPO288 | 加宽 actor 的 MAPPO | 对 v2.0 的参数规模控制；v2.0 actor 262,341 参数，MAPPO288 250,530 参数 |
| HATT v2.0 | 独立实体编码、AA 上下文、任务联盟聚合与共享解码 | 有完整五 seed 数据的历史关系模型参照 |
| PCFA-DelivCoal | 优先级/紧迫度排序、载荷承诺、规则联盟组建、探索和补给 | 任务分布一致的确定性规则参照；当前记录为一个 RNG 流顺序生成 128 回合 |
| QMIX / VDN | 共享 recurrent individual-Q，分别采用单调 mixer / utility 求和，团队均值奖励 | 同一批次比较值分解方式；奖励归并与 PPO 个体信用设置分别注明 |
| CFM-DelivCoal | 官方 AttentionNet + pointer、序贯分配、REINFORCE/POMO 训练适配 | 比较序贯分配机制；POMO 副本计入训练交互预算 |
| MARL-MRT2A-DelivCoal | 官方 CNN actor/critic、MAPPO learner、目标修正；任务映射到21×21网格 | 比较空间策略表示；legacy20 和 full27 输入布局按实验分组 |

来源：[PPO](https://arxiv.org/abs/1707.06347)、[MAPPO](https://arxiv.org/abs/2103.01955)、[QMIX](https://arxiv.org/abs/1803.11485)、[VDN](https://arxiv.org/abs/1706.05296)、[CFM](https://marmotlab.org/publications/73-RAL2025-HetMRTA.pdf)、[MARL-MRT2A](https://arxiv.org/html/2412.20397v2)，本地对应文件均在 [代码索引](05_code.md)。PCFA 的 DelivCoal 版本按本项目任务过程适配，规则细节以复制的 `pcfa.py` 为准。


---

# 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。每项效果解释使用对应实验条件。


---

# 实验汇总与可引用结果

本章按实验所回答的问题合并结果。同一表内采用统一指标和 selector；训练协议发生变化时另列实验组。下列百分数中的 ± 是独立训练 seed 均值的样本标准差，单位为百分点；各训练 seed 内的评估场景数另行说明。所有聚合由 [collect_evidence.py](collect_evidence.py) 从结果文件重建，逐 seed 数值、来源路径和源文件 SHA-256 均已保存。[来源清单](evidence/sources.json)

## 评估协议与阅读方式

E01、E02、E04 的正式训练对照与 E05 使用 DelivCoal 的 12 机器人、10 配送任务、750 步、sector coverage、event 日程。训练上限 1500 episodes，配置名义预算 1,125,000 环境步；实际交互步数随回合提前结束而变化。周期验证使用固定 32 场景；validation-best 在验证结果中按成功率、完成率、回合长度、checkpoint 先后顺序锁定，然后执行 128 场景留出测试。last 对应末次训练权重。正式测试种子从 50000 开始，验证种子从 10000 开始。逐 seed 和配置表提供每个实验的确切设置。[正式结果](evidence/formal_by_seed.csv)、[研究参数](evidence/research_settings.csv)

E08、E09、E12 的历史 best/p90/last 保留当时的 selector 名称；p90 是指定位置的 checkpoint。它们在各自实验内比较。E06 在同一策略产生的事件前状态上配对干预；不同策略会产生不同状态。E10、E11 的官方环境与适配环境分别统计。

## E01　联盟上下文与相同 PPO 框架下的整体效果

问题：按配送任务汇总联盟成员的信息，是否有助于完成当前配送环境？五个训练 seed 的固定条件对照如下，指标为 episode 全部完成成功率。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| HATT v2.0 full | 5 | 72.19% ± 5.76 | 65.16% ± 6.02 |
| 去 AA | 5 | 69.22% ± 3.93 | 69.22% ± 4.61 |
| 去 coalition context | 5 | 61.88% ± 10.89 | 57.66% ± 9.65 |
| MAPPO288 | 5 | 22.81% ± 6.45 | 5.94% ± 5.02 |
| MAPPO64 | 5 | 10.16% ± 6.25 | 1.09% ± 0.89 |

完整 v2.0 的任务完成率为 96.44%，去联盟上下文为 94.80%；成功率差为 10.31 个百分点。这组对照为任务上的联盟汇总提供了效果依据。MAPPO288 将 actor 参数量提高到接近 v2.0 的规模，提供相同 PPO 框架下的加宽对照。[五 seed 汇总](evidence/formal_aggregate.csv)、[架构与参数](02_environment.md)

末期轨迹另用最后 10% 的逐 episode actor、每个 actor 8 个场景评估，先在每个训练 seed 内平均，再跨 seed 汇总。full 为 75.50%，no-AA 为 76.48%，no-coalition 为 58.87%，MAPPO288 为 5.07%，MAPPO64 为 3.72%。这项统计描绘末期权重轨迹；其场景种子从 30000 开始，主表采用独立的 128 场景测试。[末期逐 seed](evidence/final_window_by_seed.csv)、[末期聚合](evidence/final_window_aggregate.json)

## E02　探索历史与几何输入的作用

问题：探索候选中的覆盖历史，怎样影响发现和完成任务？下表统一取训练 seed 1–3，比较成功率。geometry-only 保留探索候选相对几何，coverage 条件另外提供覆盖历史摘要；no-coverage 使用对应关闭覆盖输入的设置。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| HATT coverage | 3 | 70.83% ± 7.71 | 65.89% ± 8.35 |
| HATT geometry-only | 3 | 31.51% ± 1.97 | 27.60% ± 4.01 |
| HATT no-coverage | 3 | 33.85% ± 5.86 | 19.27% ± 11.06 |
| MAPPO64 coverage | 3 | 8.33% ± 6.31 | 1.30% ± 1.19 |
| MAPPO64 geometry-only | 3 | 17.45% ± 7.83 | 2.86% ± 2.26 |

完整输入 HATT 的任务发现率为 96.98%，geometry-only 为 89.95%，no-coverage 为 87.24%；相应任务完成率为 96.07%、88.33%、85.63%。在这组场景中，覆盖输入同时对应较高的发现比例和完成比例。这一结果支持将覆盖图摘要写入环境信息条件，并在联盟机制实验中单独记录任务是否已发现。[统一三 seed 结果](evidence/common_three_seeds.json)、[配置差异](evidence/research_settings.csv)

## E03　任务 ID 重排的一致性

问题：重新编号相同物理任务时，冻结策略的闭环行为是否保持对应？实验同步重排任务槽、动作和联盟编号，分别测试 Deliver 槽与 Explore 槽，使用历史 coverage-event 模型、每种模型 3 个训练 seed、各 128 个场景。

HATT 在两种重排中都保持原成功率：三个 seed 为 71.09%、78.13%、60.16%，均值 69.79%；每组 384 个配对回合的成功/失败标记均保持一致。Explore 重排下，MAPPO 均值从 14.58% 变为 2.60%。这里的直接证据是任务重编号下的行为一致性；方法章给出相应计算图推导，v3.4 单元检查覆盖任务/智能体排列与合法动作掩码。[Deliver 配对](evidence/deliver_summary.csv)、[Explore 配对](evidence/explore_summary.csv)、[结构检查](evidence/implementation_checks.json)

## E04　可学习 AA 权重及冻结策略的消息干预

第一组问题是训练时的成员加权方式。learned 与 uniform-trained 各独立训练三个 seed，保持其余设置一致。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| learned | 3 | 62.50% ± 10.16 | 62.50% ± 10.16 |
| uniform-trained | 3 | 54.17% ± 8.88 | 54.69% ± 9.01 |

learned 的所选 checkpoint 任务完成率为 95.00%，uniform-trained 为 93.36%，为学习 AA 加权提供了该训练方案下的效果记录。[训练对照](evidence/formal_by_seed.csv)

第二组固定 learned checkpoint，在推理时改动 AA 消息。相同 128 场景上，learned、uniform-at-inference、zero-at-inference 的三 seed 平均成功率分别为 62.50%、55.21%、67.45%。zero 条件获得了本组最高均值，记录了消息强度调整对现成策略的影响。两组实验分别回答“怎样训练”和“冻结策略怎样依赖当前消息”，分析时保留各自干预定义。[冻结干预逐 seed](evidence/aa_frozen_interventions.json)

这些结果用于组织 v3.3AA/v3.4 的论文依据：成员加权可通过回报学习，其实际作用需要结合候选路由与行为结果观察。E06 进一步记录 AA 置零条件对突发任务的响应。

## E05　v3.4 服务任务上下文的同期训练对照

问题：AA 关系读取邻居当前服务任务的四维摘要后，训练结果怎样变化？taskctx 与 noctx 各三个训练 seed，全部完成 1500 episodes。六个训练任务共有 180 次周期验证、12 次最终测试，合计 7296 次评估回合。taskctx 的服务摘要使 AA 边输入由 3 维变为 7 维，增加 512 个参数。[代码和输入定义](03_method.md)

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| v3.4 taskctx | 3 | 65.10% ± 7.51 | 61.72% ± 4.69 |
| v3.4 noctx | 3 | 62.50% ± 10.16 | 62.50% ± 10.16 |

| selector | taskctx 任务完成率 | noctx 任务完成率 | taskctx 平均长度 | noctx 平均长度 |
|---|---:|---:|---:|---:|
| validation-best | 95.31% | 95.00% | 649.79 | 658.77 |
| last | 94.48% | 94.97% | 657.85 | 660.00 |

| 训练 seed | taskctx 所选 episode | noctx 所选 episode | taskctx 成功回合 /128 | noctx 成功回合 /128 |
|---|---:|---:|---:|---:|
| 1 | 850 | 1500 | 85 | 80 |
| 2 | 700 | 1400 | 92 | 93 |
| 3 | 1500 | 1500 | 73 | 67 |

这轮记录到 validation-best 成功率均值增加 2.60 个百分点，跨训练 seed 标准差分别为 7.51 和 10.16 个百分点。last 的完整结果同时列出，供后续按统一选模协议引用。v3.4 noctx 的本轮汇总数值与历史 v3.3AA learned 对应结果一致，在汇总研究证据时将它们视作同一参考表现。[逐 seed](evidence/formal_by_seed.csv)、[统一三 seed](evidence/common_three_seeds.json)

![v3.4 原始周期验证点及独立测试](assets/validation_and_test.png)

图中横轴使用 training episode。个别周期点在 rollout 结束时落于计划阈值后一回合，原始点保留实际 episode。各 seed 的 validation-best 已在测试前锁定；selected 与 last 恰好相同时，对应测试属于相同权重的重复评价。[周期点](evidence/v34_periodic_validation.csv)、[选模记录](evidence/v34_selection_and_windows.csv)

为连接历史对照，下表统一取训练 seed 1–3，仅展示相同主要训练和测试协议下的成功率。它给出 v3.4 在已有研究环境中的位置。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| v3.4 taskctx | 3 | 65.10% ± 7.51 | 61.72% ± 4.69 |
| v3.4 noctx | 3 | 62.50% ± 10.16 | 62.50% ± 10.16 |
| v2.0 full | 3 | 70.83% ± 7.71 | 65.89% ± 8.35 |
| MAPPO288 | 3 | 27.08% ± 3.52 | 4.17% ± 2.96 |
| MAPPO64 | 3 | 8.33% ± 6.31 | 1.30% ± 1.19 |

## E06　突发高优先级任务与联盟重组

问题：冻结模型如何响应同一任务价值的变化，重选怎样影响源任务与目标任务？实验覆盖五个条件、各三个训练 seed，每 seed 32 个配对场景；共 1440 条闭环轨迹、960 条配对效应记录。在同一模型、同一事件前状态下揭示相同任务，将 priority 设置为 1.0 或 0.5。另在高优先级条件下比较立即 react 和首次保持当前动作的 keep-current，之后继续原策略。[评估实现](code_view/scripts/analysis/evaluate_priority_reconfiguration.py.html)、[配对效应](evidence/priority_reconfiguration_20260905_per_training_seed_summary.csv)

| 条件 | high−low 任务概率 | 指派人数变化 | 首次响应步数变化 |
|---|---:|---:|---:|
| v3.3AA learned | +0.0419 | +0.490 | −25.93 |
| v3.3AA uniform-trained | +0.0260 | +0.396 | −16.23 |
| v3.3AA learned，推理 AA 置零 | +0.0633 | +0.667 | −22.42 |
| v2.0 | +0.0881 | +1.333 | −58.55 |
| MAPPO64 | −0.0012 | 0.000 | +0.03 |

learned 的跨训练 seed 标准差分别为 0.0189、0.065 人和 11.82 步。HATT 条件呈现明确的优先级敏感响应：目标概率、初始分配和响应时刻共同发生变化。全部条件中的事件任务最终完成比例为 100%。这些观测分别刻画策略决策和事件任务后果。[跨 seed 汇总](evidence/priority_reconfiguration_20260905_across_training_seed_summary.csv)

在高优先级的 react−keep-current 比较中，learned 平均首次响应提前 8.14 步；首次重选的 5.198 次归属变化中，2.250 次进入事件任务、2.948 次发生在其他任务之间，1.667 次为源联盟脆弱条件下的退出。最终任务完成率差为 0.00 个百分点，剩余需求差 +1.29，回报差 −1.91±13.73。该实验同时记录了目标响应和全队后果，给后续“源依赖程度 × 目标收益”配对提供了直接设计依据。[同一效应表](evidence/priority_reconfiguration_20260905_across_training_seed_summary.csv)

high−low 的奖励目标随 priority 一起变化，适合分析价值敏感行为。react−keep-current 固定高优先级奖励目标，适合分析允许当次重选后的执行后果。不同方法的状态由各自策略产生，跨方法表格用于比较响应模式；同一物理状态上的方法比较按共享状态库协议执行，详见交接章。

## E07　任务输入语义与尺度

问题：compact6 到 full12 的特征表达如何影响训练？这一系列使用各自固定协议，按桥接、尺度、函数保持初始化分为三个组。指标采用任务完成率。

桥接组在相同单 seed、1500 episodes、legacy 日程下，compact6 的 validation-best 完成率为 33.59%，full12 为 7.42%；同组 MAPPO 为 4.45% 和 1.56%。full12 同时改变字段位置和数值表达，后续实验把这些因素进一步显式控制。[桥接结果](evidence/formal_aggregate.csv)

尺度组采用单 seed、1000 episodes，固定 full12 物理环境；native、恢复 req/priority 尺度、投影至 compact 的任务完成率如下。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| full12 native | 1 | 6.80% | 6.72% |
| full12 恢复尺度 | 1 | 15.47% | 17.58% |
| full12 compact 投影 | 1 | 25.08% | 26.02% |

恢复尺度在本组所选 checkpoint 上将完成率从 6.80% 提高到 15.47%；compact 投影为 25.08%。这组记录说明输入数值尺度和表达方式具有可测量的训练影响。[研究设置](evidence/research_settings.csv)

函数保持初始化组采用 3 个训练 seed、600 episodes、相同 full critic，配对初始化设置如下。

| 条件 | 训练 seed 数 | validation-best | last |
|---|---:|---:|---:|
| compact 投影 | 3 | 6.72% ± 0.75 | 6.59% ± 0.59 |
| full12 函数保持初始化 | 3 | 6.30% ± 0.46 | 6.48% ± 0.21 |
| full12 默认初始化 | 3 | 6.54% ± 0.91 | 6.67% ± 0.16 |

三个条件的所选模型平均任务完成率落在 6.30%–6.72%，末次模型落在 6.48%–6.67%。代码测试检查 compact 投影、字段尺度恢复与函数保持初始化的对应关系，作为继续更换观测接口时的实现基准。[初始化测试](code_view/tests/test_hatt_network.py.html#L309)、[本组逐 seed](evidence/formal_by_seed.csv)

## E08　CapCoal 的独立训练迁移

问题：关系 actor 能否在另一组联盟环境设置中训练并完成任务？采用 30 机器人、25 任务、1500 步、nearest 探索、legacy 日程、random_demand 任务字段，各训练 3 个 seed、5000 episodes，再进行 128 场景旧 selector 评估。表格读取恢复后按 30/25/1500 执行的独立评估记录。

| 模型 | best 成功率 | p90 成功率 | last 成功率 | best 平均长度 | last 平均长度 |
|---|---:|---:|---:|---:|---:|
| HATT v2.0 | 99.48% | 97.40% | 97.92% | 462.35 | 511.99 |
| MAPPO64 | 100.00% | 75.26% | 80.99% | 659.07 | 784.40 |

两种方法在各自 best 上完成了几乎全部场景；HATT 的平均回合长度为 462.35 步，末次模型成功率为 97.92%。这些结果提供另一套任务分布和执行日程下的训练迁移记录。任务初始隐藏，nearest 控制器读取最近未发现任务位置。训练预算、探索机制、奖励均以本组冻结记录为准。[CapCoal 聚合](evidence/capcoal_aggregate.json)、[逐模型结果及元数据](evidence/capcoal_rows.json)

## E09　GymRT2A 空间任务环境

官方 MARL-MRT2A 在 20×20 网格、10 机器人、100 步动态回合、通信范围 8、视野范围 5、路径意图共享设置下完成 5 个 seed、各 300 万步训练。官方记录的最终平均 team return 为 655.824，跨训练 seed 样本标准差约 6.60。[官方训练汇总](evidence/gymrt2a_reproduction_20260724_official_summary.csv)

HATT 专用空间候选 actor 同样训练到 300 万步，使用两个训练 seed；每个 checkpoint 在 96 个留出场景测试，起始 seed 为 20000。best 的平均 team return 为 310.19，平均收集 L1/L2/L3 目标分别为 83.13、56.57、0.089；p90 与 latest 的回报均值为 283.65 和 268.27。这组结果提供 HATT 空间候选接口在原网格任务中的实际学习记录。[HATT 留出表](evidence/gymrt2a_hatt_eval_20260725_heldout_summary.csv)

官方训练日志指标与 HATT 独立留出评估保留各自采样协议。原环境包含等级任务、局部空间观测和路径意图；DelivCoal 中的任务概率与标量配送指标在这里分别映射为空间目标策略和等级收集指标。[适配网络](code_view/algorithms/algorithm/HATTGyMRT2ANetwork.py.html)、[环境接口](code_view/envs/gymrt2a/env_discrete.py.html)

## E10　外部方法的官方环境复现

CFM 官方 checkpoint 在 RALTestSet 的 50 个场景中，上游任务完成比例 `success_rate` 均值为 1.0，makespan 为 28.7448±3.1686，± 为场景标准差。该字段按完成任务数/任务总数计算。CFM 的小规模重新训练在固定 128 场景上，从 update 0 的任务完成比例 19.53%，提高到 update 50 的 98.83%，update 300 为 100%。[官方结果](evidence/cfm_official.json)、[小规模学习](evidence/cfm_small_learning.json)、[上游指标定义](code_view/third_party/heteromrta/worker.py.html#L115)

MARL-MRT2A 的小规模重新训练使用 100 个固定评估回合，team return 从 1000 步的 54.5 提高到 301000 步的 384.3。两条记录共同提供外部代码在原任务上可训练、可评价的复现依据。[学习结果](evidence/mrt2a_small_learning.json)

## E11　外部方法与规则策略的 DelivCoal 适配

第一轮学习方法 screen 使用相同 150000 步预算、训练 seed 10、16 个评估场景。validation-best 的任务完成率：CFM greedy 为 2.50%，MARL-MRT2A 为 13.75%；last 分别为 3.13% 和 3.75%。此组保留了外部方法接入配送环境后的早期学习记录。[适配结果及协议](evidence/external_adaptations.json)

后续采用各自明确的设置形成如下评价：

| 条件 | 训练预算 / seed | 测试 | 所选模型成功率 | 所选模型任务完成率 | 配送比例 |
|---|---|---|---:|---:|---:|
| CFM-long，采样策略 | 375 updates×4 POMO，1500 episodes，名义 112.5 万步 / 10 | 128 场景 | 0.78% | 53.44% | 58.57% |
| MARL-MRT2A cap-lr | 15 万步 / 10 | 128 场景 | 0.00% | 21.25% | 44.68% |
| MARL-MRT2A cap-entropy | 15 万步 / 10 | 128 场景 | 0.00% | 21.25% | 45.69% |
| PCFA-DelivCoal | 确定性规则，无训练 | 128 回合 | 51.56% | 93.83% | 95.08% |

CFM-long 的所选与末次模型相同。MARL-MRT2A cap-lr 与 cap-entropy 的 last 任务完成率分别为 8.75% 和 12.50%。PCFA 平均回合长度为 665.45 步，128 回合由以 50000 初始化的 RNG 流顺序生成；其统计提供相同任务分布上的规则参照。学习方法的独立 seed 数、POMO 交互量、greedy/采样决策和状态信息分别保留于协议中。[外部适配](evidence/external_adaptations.json)、[PCFA 原始指标](evidence/pcfa_results.json)、[规则执行](code_view/runner/pcfa/macf_runner.py.html)

这些结果用于报告外部方法适配后的已测行为与配送水平。与主方法的正式横向比较表采用统一预算、信息字段和选模协议后填写，具体接口由 [交接约定](07_handoff.md) 固定。

## E12　历史设计依据与值分解参照

以下选用每类同批次最具解释力的结果，全部沿用各自旧 best selector；每个数字的原始模型路径保存在逐 seed 表中。

| 实验主题 | 同组方法与 best 成功率 | 训练 seed 数 | 直接观察 |
|---|---|---:|---|
| 特殊动作关系语义 | detached HATT 87.24%，原 HATT notimeout 29.95%，MAPPO notimeout 91.15% | 各 3 | detached 方案在该日程下完成了 87.24% 场景，为控制槽与配送成员分开处理提供依据 |
| 覆盖历史与 recurrence | HATT coverage 74.48%，coverage+RNN 70.31%，RNN 24.22%，MAPPO coverage 4.43% | 各 3 | coverage 条件在该批次形成较高完成水平，支持将探索历史作为显式观测 |
| 值分解 | QMIX、VDN、HATT-QMIX 的任务完成率为 25.67%、26.63%、18.44% | 各 5 | 三种值分解路径均产生部分任务交付与完成，提供同批值学习参照 |

QMIX/VDN 组采用团队均值奖励、recurrent individual-Q 和各自 mixer；与 PPO 主表的奖励信用与更新方式一起作为协议字段保留。[历史聚合](evidence/legacy_aggregate.json)、[逐 seed](evidence/legacy_by_seed.csv)、[QMIX trainer](code_view/algorithms/qmix/qmix.py.html)

## 论文证据的对应关系

| 论文表述的对象 | 可以直接引用的已测内容 | 证据 |
|---|---|---|
| 任务上的联盟信息组织 | 完整/去联盟上下文的同协议训练结果 | E01 |
| 输入与任务编号的一致性 | Deliver/Explore 槽配对重排、v3.4 结构测试 | E03 |
| 关系权重与服务任务条件 | learned/uniform 训练；taskctx/noctx 同期训练；冻结消息干预 | E04、E05 |
| 动态任务价值响应 | 同事件前状态下的概率、成员数与响应时间变化 | E06 |
| 环境信息的实际作用 | 覆盖历史、输入尺度和函数保持初始化的受控结果 | E02、E07 |
| 方法适配与任务差异 | CapCoal 独立训练、GymRT2A 空间候选、外部方法官方及配送适配 | E08–E11 |

每项论文判断应与表中对象保持同一范围。源联盟可替代性与重组全队收益的已定验证方案，作为下一轮研究交接记录于 [07_handoff](07_handoff.md)。


---

# 关键代码快照与调用索引

本包复制了 59 个关键源码/许可文件，保留原相对目录与原始字节。每项提供逐行网页、原文件和 SHA-256。复制范围覆盖本文解释的核心计算链与实验入口；运行依赖、模型和完整数据沿用原工程。

代码阅读顺序为 `train → runner → policy → actor/critic → trainer/buffer`，环境通过离散封装进入 runner。v3.4 actor 的主要依赖为 HATTV33AA 中的关系算子与 HATTV20 中的编码/解码接口。AA 权重同时读取编码后的 query/key 与边特征，其信息依赖按方法章公式解释。

[完整哈希清单](code_manifest.json) · [环境和 actor 检查](evidence/implementation_checks.json)

网页中的行号固定到本次快照。队列等文件包含工作区已有修改，哈希标识的是实际打包内容；git HEAD 记录于清单，便于定位对应基础版本。


## 方法与 PPO 调用链

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [algorithms/algorithm/HATTV34Network.py](code_view/algorithms/algorithm/HATTV34Network.py.html) | v3.4 服务任务上下文、AA/AT 与候选路由；方法章主要实现 | [下载](code/algorithms/algorithm/HATTV34Network.py) |
| [algorithms/algorithm/HATTV33AANetwork.py](code_view/algorithms/algorithm/HATTV33AANetwork.py.html) | TypedRelationEdge 与 v3.3AA 基础；learned/uniform/zero 语义 | [下载](code/algorithms/algorithm/HATTV33AANetwork.py) |
| [algorithms/algorithm/HATTV20Network.py](code_view/algorithms/algorithm/HATTV20Network.py.html) | 实体编码器、CandidateEdgeDecoder、基础 actor 与 schema 投影 | [下载](code/algorithms/algorithm/HATTV20Network.py) |
| [algorithms/algorithm/gaRMAPPOPolicy.py](code_view/algorithms/algorithm/gaRMAPPOPolicy.py.html) | 图模型路由、actor/critic 构造与动作接口 | [下载](code/algorithms/algorithm/gaRMAPPOPolicy.py) |
| [algorithms/algorithm/ga_rmappo.py](code_view/algorithms/algorithm/ga_rmappo.py.html) | PPO 更新、active masks、损失与优化停止条件 | [下载](code/algorithms/algorithm/ga_rmappo.py) |
| [algorithms/algorithm/r_actor_critic.py](code_view/algorithms/algorithm/r_actor_critic.py.html) | MLP/recurrent actor 与集中式 critic | [下载](code/algorithms/algorithm/r_actor_critic.py) |
| [algorithms/algorithm/rMAPPOPolicy.py](code_view/algorithms/algorithm/rMAPPOPolicy.py.html) | 标准 MAPPO 策略对照 | [下载](code/algorithms/algorithm/rMAPPOPolicy.py) |
| [algorithms/algorithm/r_mappo.py](code_view/algorithms/algorithm/r_mappo.py.html) | 标准 PPO trainer | [下载](code/algorithms/algorithm/r_mappo.py) |
| [algorithms/utils/act.py](code_view/algorithms/utils/act.py.html) | 离散策略动作层 | [下载](code/algorithms/utils/act.py) |
| [algorithms/utils/mlp.py](code_view/algorithms/utils/mlp.py.html) | MLP 编码基础 | [下载](code/algorithms/utils/mlp.py) |
| [algorithms/utils/rnn.py](code_view/algorithms/utils/rnn.py.html) | 可选 recurrent 层 | [下载](code/algorithms/utils/rnn.py) |
| [algorithms/utils/distributions.py](code_view/algorithms/utils/distributions.py.html) | 动作分布与 log probability | [下载](code/algorithms/utils/distributions.py) |
| [runner/shared/macf_runner.py](code_view/runner/shared/macf_runner.py.html) | collect/insert、focal state、决策掩码、训练与评价 | [下载](code/runner/shared/macf_runner.py) |
| [runner/shared/base_runner.py](code_view/runner/shared/base_runner.py.html) | 训练器/buffer 初始化及公共流程 | [下载](code/runner/shared/base_runner.py) |
| [utils/shared_gat_buffer.py](code_view/utils/shared_gat_buffer.py.html) | Dict on-policy 数据与 GAE | [下载](code/utils/shared_gat_buffer.py) |
| [utils/shared_buffer.py](code_view/utils/shared_buffer.py.html) | MAPPO 对照 buffer | [下载](code/utils/shared_buffer.py) |
| [utils/obs_utils.py](code_view/utils/obs_utils.py.html) | 观测/state 展平及字段规则 | [下载](code/utils/obs_utils.py) |
| [utils/valuenorm.py](code_view/utils/valuenorm.py.html) | 价值归一化 | [下载](code/utils/valuenorm.py) |


## 环境与执行

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [envs/delivcoal/env_core.py](code_view/envs/delivcoal/env_core.py.html) | 当前主实验物理过程、观测、event、覆盖与奖励 | [下载](code/envs/delivcoal/env_core.py) |
| [envs/delivcoal/env_discrete.py](code_view/envs/delivcoal/env_discrete.py.html) | Gym Dict/Discrete 空间与环境封装 | [下载](code/envs/delivcoal/env_discrete.py) |
| [envs/delivcoal/env_wrappers.py](code_view/envs/delivcoal/env_wrappers.py.html) | 向量环境与自动 reset 接口 | [下载](code/envs/delivcoal/env_wrappers.py) |
| [envs/capcoal/env_core.py](code_view/envs/capcoal/env_core.py.html) | CapCoal 任务生成与执行语义 | [下载](code/envs/capcoal/env_core.py) |
| [envs/capcoal/env_discrete.py](code_view/envs/capcoal/env_discrete.py.html) | CapCoal 空间封装 | [下载](code/envs/capcoal/env_discrete.py) |
| [envs/macf/env_core.py](code_view/envs/macf/env_core.py.html) | MACF 基础环境及历史调用参照 | [下载](code/envs/macf/env_core.py) |
| [envs/gymrt2a/env_discrete.py](code_view/envs/gymrt2a/env_discrete.py.html) | 局部网格观测到 HATT 输入的适配 | [下载](code/envs/gymrt2a/env_discrete.py) |


## 训练和评价入口

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [config.py](code_view/config.py.html) | 参数定义与默认值；冻结有效配置字段见 evidence | [下载](code/config.py) |
| [train/train.py](code_view/train/train.py.html) | 训练入口、环境与 runner 选择 | [下载](code/train/train.py) |
| [train/eval.py](code_view/train/eval.py.html) | checkpoint 加载与独立评价 | [下载](code/train/eval.py) |
| [train/sweep.py](code_view/train/sweep.py.html) | 批量训练、checkpoint 与状态调度 | [下载](code/train/sweep.py) |
| [scripts/experiments/run_staged_validation_queue.py](code_view/scripts/experiments/run_staged_validation_queue.py.html) | 分阶段冻结 checkpoint 评估队列 | [下载](code/scripts/experiments/run_staged_validation_queue.py) |
| [scripts/experiments/run_final_window_queue.py](code_view/scripts/experiments/run_final_window_queue.py.html) | 末期逐 episode actor 评估 | [下载](code/scripts/experiments/run_final_window_queue.py) |


## 机制实验和实现核对

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [scripts/analysis/evaluate_priority_reconfiguration.py](code_view/scripts/analysis/evaluate_priority_reconfiguration.py.html) | 配对优先级事件、首次动作和闭环执行 | [下载](code/scripts/analysis/evaluate_priority_reconfiguration.py) |
| [scripts/analysis/summarize_priority_reconfiguration.py](code_view/scripts/analysis/summarize_priority_reconfiguration.py.html) | 按训练 seed 汇总配对效应 | [下载](code/scripts/analysis/summarize_priority_reconfiguration.py) |
| [scripts/analysis/evaluate_source_commitment.py](code_view/scripts/analysis/evaluate_source_commitment.py.html) | 共享状态库与源条件配对评价入口 | [下载](code/scripts/analysis/evaluate_source_commitment.py) |
| [scripts/analysis/eval_task_slot_permutation.py](code_view/scripts/analysis/eval_task_slot_permutation.py.html) | 任务槽重排、动作映射与配对统计 | [下载](code/scripts/analysis/eval_task_slot_permutation.py) |
| [tests/test_hatt_network.py](code_view/tests/test_hatt_network.py.html) | 排列、梯度、任务上下文、schema 初始化检查 | [下载](code/tests/test_hatt_network.py) |


## 本地基线与跨环境 actor

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [algorithms/algorithm/pcfa.py](code_view/algorithms/algorithm/pcfa.py.html) | 本项目 PCFA 联盟分配与资源规则 | [下载](code/algorithms/algorithm/pcfa.py) |
| [algorithms/algorithm/pcfa_policy.py](code_view/algorithms/algorithm/pcfa_policy.py.html) | 规则策略接口 | [下载](code/algorithms/algorithm/pcfa_policy.py) |
| [runner/pcfa/macf_runner.py](code_view/runner/pcfa/macf_runner.py.html) | PCFA 运行及 RNG 流评估 | [下载](code/runner/pcfa/macf_runner.py) |
| [runner/pcfa/base_runner.py](code_view/runner/pcfa/base_runner.py.html) | PCFA runner 基础 | [下载](code/runner/pcfa/base_runner.py) |
| [algorithms/qmix/qmix.py](code_view/algorithms/qmix/qmix.py.html) | QMIX/VDN trainer | [下载](code/algorithms/qmix/qmix.py) |
| [algorithms/qmix/algorithm/QMixPolicy.py](code_view/algorithms/qmix/algorithm/QMixPolicy.py.html) | individual-Q 策略 | [下载](code/algorithms/qmix/algorithm/QMixPolicy.py) |
| [algorithms/qmix/algorithm/agent_q_function.py](code_view/algorithms/qmix/algorithm/agent_q_function.py.html) | 个体 Q 网络 | [下载](code/algorithms/qmix/algorithm/agent_q_function.py) |
| [algorithms/qmix/algorithm/q_mixer.py](code_view/algorithms/qmix/algorithm/q_mixer.py.html) | 单调 mixer | [下载](code/algorithms/qmix/algorithm/q_mixer.py) |
| [runner/qmix/macf_runner.py](code_view/runner/qmix/macf_runner.py.html) | 值分解 rollout 与评估 | [下载](code/runner/qmix/macf_runner.py) |
| [utils/rec_buffer.py](code_view/utils/rec_buffer.py.html) | off-policy replay | [下载](code/utils/rec_buffer.py) |
| [algorithms/algorithm/HATTGyMRT2ANetwork.py](code_view/algorithms/algorithm/HATTGyMRT2ANetwork.py.html) | GymRT2A 空间候选 HATT actor | [下载](code/algorithms/algorithm/HATTGyMRT2ANetwork.py) |


## 外部方法适配与上游核心

| 原路径 / 逐行阅读 | 对应作用 | 原文件 |
|---|---|---|
| [experiments/reproduction/delivcoal_adapter_common.py](code_view/experiments/reproduction/delivcoal_adapter_common.py.html) | 共享 DelivCoal 配置读取与适配函数 | [下载](code/experiments/reproduction/delivcoal_adapter_common.py) |
| [experiments/reproduction/train_cfm_delivcoal.py](code_view/experiments/reproduction/train_cfm_delivcoal.py.html) | CFM pointer/POMO 配送训练 | [下载](code/experiments/reproduction/train_cfm_delivcoal.py) |
| [experiments/reproduction/eval_cfm_delivcoal.py](code_view/experiments/reproduction/eval_cfm_delivcoal.py.html) | CFM 采样/greedy 留出评价 | [下载](code/experiments/reproduction/eval_cfm_delivcoal.py) |
| [experiments/reproduction/run_marl_mrt2a_delivcoal.py](code_view/experiments/reproduction/run_marl_mrt2a_delivcoal.py.html) | MRT2A 配送训练入口 | [下载](code/experiments/reproduction/run_marl_mrt2a_delivcoal.py) |
| [experiments/reproduction/eval_marl_mrt2a_delivcoal.py](code_view/experiments/reproduction/eval_marl_mrt2a_delivcoal.py.html) | MRT2A 配送留出评价 | [下载](code/experiments/reproduction/eval_marl_mrt2a_delivcoal.py) |
| [third_party/heteromrta/attention.py](code_view/third_party/heteromrta/attention.py.html) | CFM 上游 AttentionNet | [下载](code/third_party/heteromrta/attention.py) |
| [third_party/heteromrta/worker.py](code_view/third_party/heteromrta/worker.py.html) | CFM 上游 rollout 与 success_rate 定义 | [下载](code/third_party/heteromrta/worker.py) |
| [third_party/heteromrta/LICENSE](code_view/third_party/heteromrta/LICENSE.html) | CFM 上游许可 | [下载](code/third_party/heteromrta/LICENSE) |
| [third_party/marl_mrt2a/marl_mrt2a/marl/src/envs/delivcoal_env.py](code_view/third_party/marl_mrt2a/marl_mrt2a/marl/src/envs/delivcoal_env.py.html) | 空间网格、legacy20/full27、路径意图适配 | [下载](code/third_party/marl_mrt2a/marl_mrt2a/marl/src/envs/delivcoal_env.py) |
| [third_party/marl_mrt2a/marl_mrt2a/marl/src/modules/agents/custom_agent.py](code_view/third_party/marl_mrt2a/marl_mrt2a/marl/src/modules/agents/custom_agent.py.html) | MRT2A 上游空间策略网络 | [下载](code/third_party/marl_mrt2a/marl_mrt2a/marl/src/modules/agents/custom_agent.py) |
| [third_party/marl_mrt2a/marl_mrt2a/marl/src/learners/ppo_learner.py](code_view/third_party/marl_mrt2a/marl_mrt2a/marl/src/learners/ppo_learner.py.html) | MRT2A 上游 PPO learner | [下载](code/third_party/marl_mrt2a/marl_mrt2a/marl/src/learners/ppo_learner.py) |
| [third_party/marl_mrt2a/LICENSE](code_view/third_party/marl_mrt2a/LICENSE.html) | MRT2A 上游许可 | [下载](code/third_party/marl_mrt2a/LICENSE) |



---

# 来源、研究决策与复核路径

交接包于 2026-09-07 开始整理，2026-09-08 完成。报告使用三类依据：用户对话确定研究意图；冻结配置和当前代码确定实际条件与实现；实验结果文件确定数值。CHANGELOG 用于定位研究事件与设计沿革。每项数值结论优先回到对应结果文件核对。

## 继承的研究决策

| 时间与会话标识 | 继承内容 | 本包落实位置 |
|---|---|---|
| Codex，2026-09-05，`01a06fba-9652-7f83-bae6-e21a44f3d22e`、`01a070bf-129b-7963-82a9-091741e14e08` | 以 v3.3AA 及更深的关系设计为研究主线；通过冻结策略的特殊情境验证重组行为；论文表述依赖真实材料 | 研究章、E06、后续验证约定 |
| Claude，`ba449dc0-e658-4992-a5f8-fe41a5abe18e.jsonl`，2026-09-06 至 09-07 | 先实现服务任务上下文，命名 v3.4；taskctx/noctx 各三 seed；共享状态库由 v3.3AA 与 MAPPO64 分别生成；优先 critical/replaceable 配对；服务摘要包含被观察成员 k | 方法章、E05、交接章 |
| Codex，`01a02cef-b02b-7c03-ba94-1aad078ef0c5`，始于 2026-08-23，后续持续更新 | 外部方法复现、输入 schema 核对、字段尺度与函数保持初始化 | E07、E10、E11 |
| Codex，`019fbcfb-3d1b-7e60-988e-bb02ab0d5168`，始于 2026-08-01 | event 日程、关系门控与正式评价协议的设计沿革 | 环境流程、E01–E06 |
| Claude，`6a4d4a0b-e819-44d7-93ce-b7e67f643e80`、`0e7d22b5-94c8-441c-8426-11c4d457fb4b`、`cbca4f98-7b10-464b-8392-a1912eaa2b6e` | 方法解释、DelivCoal/CapCoal 及外部基线的历史结果讨论 | 原始产物复核后的实验汇总 |

会话按上述标识在本机会话存储中查阅；本包只保留研究决策摘要。CapCoal 的初始发现条件、v3.4 训练预算、各组 selector 和外部指标定义均按实际代码及冻结产物填写。v3.4 的训练配置为 1500 episodes、名义 112.5 万环境步；任务实际完成数和交互步数由训练记录确定。

## 代表性实验来源

以下为仓库相对路径。网页提供抽取数据下载，完整原始产物继续保存在仓库的 runs/analysis 下。[逐文件 SHA-256](evidence/sources.json)

| 实验 | 原始组目录或分析目录 | 包内可读数据 |
|---|---|---|
| E01 正式 v2.0 | `runs/20260818-0040_hatt-formal-training-sequence` | [正式逐 seed](evidence/formal_by_seed.csv) |
| E02 几何与覆盖 | `runs/20260820-1505_delivcoal_sector-geometry-structural-attribution` | [共同三 seed](evidence/common_three_seeds.json) |
| 末期窗口 | `runs/20260821-1045_delivcoal_final-window-evaluation` | [窗口逐 seed](evidence/final_window_by_seed.csv) |
| E03 槽重排 | `runs/20260808-1622_delivcoal_coverage-slot-permutation` | [Deliver](evidence/deliver_summary.csv)、[Explore](evidence/explore_summary.csv) |
| E04 AA | `runs/20260822-1223_delivcoal_hatt-v33aa-focused` | [冻结干预](evidence/aa_frozen_interventions.json) |
| E05 v3.4 | `runs/20260906-2158_delivcoal_hatt-v34-taskctx-delivcoal-focused`；`analysis/hatt_v34_taskctx_20260907` | [逐 seed](evidence/v34_final_by_seed.csv)、[周期验证](evidence/v34_periodic_validation.csv)、[选模](evidence/v34_selection_and_windows.csv)、[场景配对](evidence/v34_paired_scenarios.csv) |
| E06 优先级 | `analysis/priority_reconfiguration_20260905` | [配对效果](evidence/priority_reconfiguration_20260905_across_training_seed_summary.csv) |
| E07 schema | `runs/20260903-1846_delivcoal_sector-schema-bridge-bcde`；`runs/20260904-1243_hatt-v20-task-schema-causal`；`runs/20260905-1200_hatt-v20-function-preserving-padding` | [正式聚合](evidence/formal_aggregate.csv)、[配置字段](evidence/research_settings.csv) |
| E08 CapCoal | `runs/20260812-2342_delivcoal_capcoal-midscale-legacy-completed-independent-recovery` | [CapCoal](evidence/capcoal_aggregate.json) |
| E09 GymRT2A | `analysis/gymrt2a_reproduction_20260724`；`analysis/gymrt2a_hatt_eval_20260725` | [官方](evidence/gymrt2a_reproduction_20260724_official_summary.csv)、[HATT](evidence/gymrt2a_hatt_eval_20260725_heldout_summary.csv) |
| E10 官方复现 | `runs/20260828_heteromrta-cfm-official-eval-50`；`runs/20260828-1435_small-baseline-convergence` | [CFM](evidence/cfm_official.json)、[CFM 学习](evidence/cfm_small_learning.json)、[MRT2A 学习](evidence/mrt2a_small_learning.json) |
| E11 外部适配 | `runs/20260830-2132_cfm-marl-mrt2a-delivcoal-adapter-screen`；`runs/20260831-1333_cfm-long-s10-sampled`；`runs/20260831-1333_mrt2a-cap-lr-s10`；`runs/20260831-1333_mrt2a-cap-entropy-s10` | [适配协议与结果](evidence/external_adaptations.json) |
| E11 PCFA | `runs/20260828-1330_delivcoal_20260828-pcfa-delivcoal-reproduction` | [PCFA](evidence/pcfa_results.json) |
| E12 历史对照 | `runs/20260725-2214_delivcoal_hatt-v20-detached-causal-delivcoal`；`runs/20260729-1311_delivcoal_hatt-sector-coverage-recurrent-delivcoal`；`runs/20260813-1841_delivcoal_delivcoal-qmix-vdn-hattqmix-five-seed` | [历史逐 seed](evidence/legacy_by_seed.csv) |

`formal_by_seed.csv` 也保存 schema pilot 等相邻实验的结果，供按条件继续查阅。正文选择具有代表性的同条件组；每个训练 job 的两个 selector 分行保存。同一 checkpoint 的重复评价保持标识，跨训练 seed 均值按独立训练任务计算。

## 数值如何重建

在原工程根目录执行：

```bash
conda run -n rl-251031 python html_logs/research_handoff_20260907/collect_evidence.py
conda run -n rl-251031 python html_logs/research_handoff_20260907/write_experiments.py
conda run -n rl-251031 python html_logs/research_handoff_20260907/check_implementation.py
conda run -n rl-251031 python html_logs/research_handoff_20260907/build_bundle.py
```

第一步只读 runs 与指定 analysis 文件，重建抽取结果和来源哈希；第二步据此生成实验表；第三步构造当前环境/网络并运行已有 v3.4 测试；第四步保存当前代码快照、渲染网页、校验链接与生成下载包。重建会更新本报告目录中的对应派生产物。代码快照表示打包时的工作区内容，文件哈希是交接版本的精确标识。[快照清单](code_manifest.json)

## 论文参考来源

| 文献 | 本报告引用用途 |
|---|---|
| [Proximal Policy Optimization Algorithms](https://arxiv.org/abs/1707.06347) | PPO 截断目标与训练框架 |
| [The Surprising Effectiveness of PPO in Cooperative Multi-Agent Games](https://arxiv.org/abs/2103.01955) | MAPPO 基础与多智能体训练参照 |
| [Deep Sets](https://arxiv.org/abs/1703.06114) | 集合聚合、排列性质的已有理论背景 |
| [QMIX: Monotonic Value Function Factorisation for Deep Multi-Agent Reinforcement Learning](https://arxiv.org/abs/1803.11485) | 值分解 baseline 的 mixer 约束 |
| [Value-Decomposition Networks For Cooperative Multi-Agent Learning](https://arxiv.org/abs/1706.05296) | VDN utility 求和 |
| [CFM / HeteroMRTA 原论文，作者实验室 PDF](https://marmotlab.org/publications/73-RAL2025-HetMRTA.pdf) | 异构任务调度、constrained flashforward、官方环境定义 |
| [Learning Policies for Dynamic Coalition Formation in Multi-Robot Task Allocation](https://arxiv.org/html/2412.20397v2) | MARL-MRT2A 的空间策略、意图共享与动态联盟任务 |

文献说明已有方法的定义；本项目的效果数值来自上面的本地实验产物。代码索引包含已使用的外部关键文件与对应许可文件。


---

# 后续研究与工程交接

本章区分已完成的交接内容与后续拟执行工作。当前包已整理 v3.4 方法、完成的训练测试、代表性历史对照与代码快照。以下实验和工程修改是基于现有实现提出的执行约定，供决策后落实。

## 方法主线怎样保持集中

当前可统一描述的方法对象是任务条件化的关系策略：实体编码提供输入；AA/AT 形成关系消息；当前任务归属决定消息进入哪个候选；v3.4 为 AA 增加服务任务摘要；PPO 学习最终任务概率。v3.4 相对 noctx 增加 512 个参数，计算链沿用原有关系算子。[方法章](03_method.md)

从论文组织看，可把“成员关系如何依赖已承担任务，并参与候选评分”作为一个主贡献，把排列一致性作为结构性质，把优先级响应和服务承诺实验作为验证。这一组织的具体依据是候选路由代码、同条件训练结果与冻结策略的事件响应。候选论文表述见 [研究章](01_research.md)，当前可引用数值见 [E01–E06](04_experiments.md)。

后续结构调整可使用同一决策标准：明确新增信息对应的决策条件，给出该条件下可检查的行为，再度量闭环后果。服务任务上下文已经提供了一条这样的输入通路；下一步优先完成沿该通路的实验。

## 已继承的源联盟配对实验

按 Claude 指定会话的决策，状态库分别由 v3.3AA learned 和 MAPPO64 生成，并供所有被测 checkpoint 共用；记录状态来源、回合阶段、任务可见性及原动作。冻结本轮已锁定的 v3.4 taskctx/noctx，并保留 v3.3AA 参考模型。当前入口为 [evaluate_source_commitment.py](code_view/scripts/analysis/evaluate_source_commitment.py.html)。

配对首先以物理载荷定义源任务条件。设源任务剩余需求为 D，焦点成员载荷为 L_i，其他已分配且存活成员的载荷之和为 L_−i。关键成员条件要求 `L_−i < D ≤ L_−i + L_i`；可替代条件要求 `D ≤ L_−i`。这些约束描述当前已承诺载荷的覆盖情况。进一步保存到达时间、可用电量与补给距离，由后续执行确定完成后果。生成器应逐状态输出这些量及约束检查结果。[环境交付定义](code_view/envs/delivcoal/env_core.py.html#L1347)

对合法配对交叉设置源依赖程度与目标优先级，保留相同焦点位置、资源和候选可达性。即时评价保存完整动作概率、实际激活掩码、stay/transfer 动作。随后从同一状态分别强制焦点首次留下或转移，再恢复相同策略闭环执行，记录源任务完成延迟、目标任务提前量、加权完成结果与补给次数。预先固定最终指标，例如在固定终点对已完成任务 priority 求和，并同时保留原环境回报和全队任务完成率。这样可把局部动作响应与固定后续策略下的执行后果关联起来。[优先级实验接口](code_view/scripts/analysis/evaluate_priority_reconfiguration.py.html)

各状态来源、各训练 seed 分层汇总；统计单位保持为独立训练 seed 和配对状态。采样数量、阶段范围与被排除状态的原因在运行前固定。已有 source 脚本可复用状态复制和推理入口，物理标签校验与闭环结果字段按上述约定补齐。

## 同类思路的进一步证明实验

| 情境与控制变量 | 需要观察的行为和后果 | 从现有材料出发的依据 |
|---|---|---|
| 替代成员即将抵达：保留载荷总量，改变替代者预计到达源任务的时间 | 转移时机随替代到达时间的变化；源任务延误、目标提前量 | 指定会话已提出 arriving 条件；当前物理过程为移动后分次交付 |
| 多名成员同时面对新任务：在共享状态上比较全体重选与只激活一个焦点成员 | 同步退出人数、源任务剩余承诺、全队完成后果 | E06 首次重选平均 5.198 次归属变化，包含非事件目标之间的转移 |
| 目标优先级相同，路途/电量成本变化：配对目标位置或焦点剩余电量 | 转移概率与实际抵达、补给、交付时刻的关系 | actor 含资源和位置；路径与补给由环境执行 |
| 全部配送目标已知的状态库，与探索中的状态库分层 | 同一关系机制在不同信息阶段的动作响应与完成后果 | E02 的覆盖输入影响发现率；E06 当前由原策略产生事件前状态 |

这些是待执行的冻结 checkpoint 情境实验。目标是分别读取任务价值、成员可替代性、执行成本和同步决策的作用；每个实验沿用配对状态、明确干预和后续回报的记录格式。全可见状态属于新的评价条件，记录其与训练分布的对应范围。

## 可能需要的工程性修改

| 接口 | 建议的具体更改 | 现状依据与验证方式 |
|---|---|---|
| 服务资源摘要 | 明确选择“除 observer 外的资源”或“全联盟资源”语义；若使用实际载荷缺口，先恢复每个成员载荷上限，再统一归一化 | 当前为 `Σ(load/init_load)/N`，others 排除 observer；用手工两/三成员状态核对守恒和成员范围 |
| 输入字段 | 为 compact/full 的字段名、单位和类型建立可读规格，checkpoint 保存 schema 标识；类型条件字段解码复用统一函数 | E07 给出了尺度/投影对照；已有特征初始化测试可用于回归 |
| 机器人类型 | 按实验目标明确固定 UAV/UGV 数量或随机类型生成；在摘要中保存实际类型计数及能力分布 | 当前 4+8 得到总数 12，Agent 自行随机类型；环境章记录实际公式 |
| 环境信息条件 | 将团队共享信息、任务初始可见性、底层路径可用障碍信息写入运行元数据；如研究有限通信，再显式定义距离、时延和消息内容 | 当前共享观测与全图路径规划，见环境章 |
| 奖励来源 | 将 shaped 分支的有效系数保存为可核对快照；参数外置时做逐状态奖励等值检查 | 当前有效系数定义在 DelivCoal 环境函数内 |
| 评估状态复制 | 保存 RNG、路径、覆盖图、事件、当前归属和资源；导入后核对下一步状态及奖励 | 优先级脚本已有复制路径；源联盟实验依赖同一物理状态 |
| 配对评估产物 | 增加物理标签、干预字段、首次激活、源/目标完成时间和固定终点结果；与聚合 CSV 关联 state_id | E06 已保存概率与轨迹结果，源条件入口可以沿用 |
| 外部方法对齐 | 固定实际输入字段、greedy/采样方式、POMO 交互量、有效决策步和真实环境步；共享独立验证与测试场景 | E11 的现有适配组提供各协议的基准结果 |

这些修改分别服务于可复现性、物理语义和证据质量，可以写入实现附录或实验设置。将其中任一项提升为论文方法贡献时，需要给出对应研究问题与验证结果。

## 训练和评估接口交接

后续修改 checkpoint、周期验证、最终测试或进度网页前，按仓库要求阅读 `docs/EVALUATION_PROGRESS_HANDOFF_20260817.md`，然后逐项核对当前实现。该文件给出目标协议；本包的 E05 表述按已完成产物填写。

维持组级 `status.json` 的唯一写入与原子更新；训练、周期验证、final-window、final-test 分阶段记录 planned/submitted/completed。训练 seed、checkpoint 与评估 seed 分别保留。每个 job 锁定 validation-best/last 后提交独立最终测试，其他训练继续执行。网页读取脱敏静态 JSON，实验数据和模型留在 runs。[队列代码](code_view/scripts/experiments/run_staged_validation_queue.py.html)、[窗口队列](code_view/scripts/experiments/run_final_window_queue.py.html)

交接包保存代码的当前副本与哈希。重启训练或评估前，以目标 run 的配置、checkpoint 兼容性和当时环境版本为依据；本包的代码清单用于定位调用链与审阅。原始运行产物的精确路径见 [来源章](06_sources.md)。