mapping_engine.py 文件是翻译器 v0.2 的核心决策组件，它基于历史经验数据，实现从效果层观测 (EffectObservation) 到关系层动作参数 (ActionParameters) 的映射。其 Phase-I 实现严格遵循"禁止内生因果假说，仅拟合统计关联"的铁律，采用 KDTree 最近邻查表 作为基线算法。
核心机制与流程
该引擎的核心工作流程是：加载历史经验 → 构建向量索引 → 接收新观测 → 查找相似历史 → 加权平均生成动作。其内部组件与数据流如下表所示：
| 组件/方法 | 核心职责 | 关键设计说明 |
|---|---|---|
TripleStore (依赖) |
提供历史 Triple (观测-动作-结果) 数据的存储与查询能力。 |
映射引擎不直接管理数据，而是依赖外部存储，符合单一职责原则，便于数据管理与映射逻辑解耦 。 |
_obs_cache & _action_cache |
在内存中分别缓存历史观测向量 (List[List[float]]) 和对应的动作参数 (List[ActionParameters])。 |
将观测向量与动作参数分离存储，观测向量用于构建 KDTree 索引，动作参数用于结果检索，实现高效的空间查询。 |
KDTree (来自 sklearn) |
对历史观测向量构建空间索引，用于快速查找最近邻。 | 将高维观测空间（6维）的相似性查询复杂度从 O(N) 降至约 O(log N)，是处理大量历史数据的关键优化 。 |
_rebuild_index() |
从存储中加载数据，重建 KDTree 索引和内存缓存。 | 在初始化或积累一定新数据（如每100条）后触发，平衡了索引更新频率与计算开销。 |
map(obs, k) |
核心接口。输入当前观测，输出推荐的动作参数。 | 1. 样本检查 ：若历史样本不足 (< min_samples)，返回保守默认动作，保证系统基线安全。 2. 最近邻查询 ：使用 KDTree 查找 k 个最相似的历史观测。 3. 加权平均 ：根据查询距离的倒数计算权重，对 k 个邻居的动作参数进行加权平均，生成最终动作。此过程仅为统计拟合，无任何因果推断 。 |
update(triple) |
将新的经验三元组存入存储，并触发周期性的索引重建。 | 实现了在线学习 的闭环：新产生的 Triple 被反馈回系统，用于更新未来的映射决策。 |
核心代码流程与示例
以下代码展示了 MappingEngine 的典型使用流程：
python
import logging
from AFT.GuicangLayer.modules.translator_v0_2.types import (
EffectObservation, ActionParameters, Outcome, Triple, ObservationSource
)
from AFT.GuicangLayer.modules.translator_v0_2.triple_store import TripleStore
from AFT.GuicangLayer.modules.translator_v0_2.mapping_engine import MappingEngine
# 1. 初始化存储和映射引擎
store = TripleStore(base_path="./data/triples")
engine = MappingEngine(triple_store=store, min_samples=50)
# 初始化时，引擎会自动调用 _rebuild_index() 加载历史数据并构建 KDTree
# 2. 模拟接收到新的效果层观测
current_observation = EffectObservation(
spectral_shift=0.12,
entropy_oscillation=2.1,
phase_lock_freq=49.0,
lambda2=0.018,
sri=0.88,
sdi=0.15,
source=ObservationSource.EFFECT_LAYER
)
# 3. 核心映射：根据历史经验，生成推荐的动作参数
recommended_action = engine.map(obs=current_observation, k=3)
print(f"推荐动作参数: {recommended_action}")
# 输出示例: ActionParameters(threshold=0.63, hold_duration=6.5, ...)
# 4.执行推荐动作，并获取结果（此步骤在系统其他部分完成）
# ... 执行动作 ...
execution_outcome = Outcome(success=True, delta_phase=-0.04, convergence_time=3.0, raw_metrics={})
# 5. 形成新的经验三元组，并反馈给引擎以更新其知识库
new_experience = Triple(obs=current_observation, action=recommended_action, outcome=execution_outcome)
engine.update(new_experience)
# update() 方法会将新经验存入 TripleStore，并在积累一定数量后重建 KDTree 索引设计哲学与工程要点
- 统计关联，非因果推断 ：引擎的核心算法（最近邻查找 + 加权平均）仅基于"相似状态对应相似动作"的统计假设，完全避免了构建内部因果模型，符合"铁律"要求 。
logger.debug记录的avg_dist等指标仅用于过程监控，而非因果解释。 - 渐进式学习与安全兜底 ：通过
min_samples参数和_default_action()方法，在系统经验不足时提供保守、安全的默认动作，确保了冷启动阶段的系统稳定性 。 - 可观测性与可调试性 ：通过
logging模块详细记录了索引重建、样本不足警告、映射过程统计等信息，为系统状态监控和算法调试提供了支持 。 - 明确的架构演进路径 ：类文档字符串明确指出此为"Phase-I: KDTree 最近邻查表映射"，为未来升级到更复杂的模型（如神经网络、高斯过程）预留了清晰的接口和替换空间 。当前的
map和update方法构成了稳定的抽象层。