agent-memory 接入层边界重构:RawPayload.assets 映射与 Normalizer 模态能力契约
agent-memory 接入层边界重构:RawPayload.assets 映射与 Normalizer 模态能力契约
本文围绕 F02-assets-ingestor-boundary 设计文档,深入讲解 agent-memory 在“Assets 映射与 Normalizer 能力边界”上的架构决策:为什么资产引用必须由 Ingestor 自行映射、为什么模态支持能力只能由 Normalizer 自己声明,以及这些契约在源码、配置与测试中的具体落地方式。读完本文,你将掌握
RawPayload.assets→MemoryUnit.segments的完整流转链路、modalities()单一能力声明的含义,以及如何为 TEXT/VIDEO 等模态正确装配 Normalizer 并在缺失能力时获得可诊断的统一错误。
背景:旧流程为什么必须重构
在引入本设计之前,MemoryEngine.write 虽然接收 assets 参数,但旧流程没有把它们交给 Ingestor,而是在 ingest 完成后由 Engine 统一把 assets 回填到首个 Segment。这带来两个问题:
- Engine 隐式假设了 Ingestor 的产出结构:Engine 假定 Ingestor 一定产出“首 Segment”,并把资产塞进去,从而与具体实现耦合;
- 自定义 Ingestor 的映射结果会被二次改写:一个已经按自身策略完成 assets 映射的自定义 Ingestor,其产出仍会被 Engine 覆盖或污染,映射策略形同虚设。
重构的核心思路是:把资产映射的责任彻底下放到 Ingestor,Engine 只做防御性传递,不再触碰 Ingestor 的产出结构。这一改动的影响范围覆盖 RawPayload、Ingestor、Normalizer、InMemoryEngine、CloudEngine 以及入口错误映射,并配套建立了统一的“能力错误”语义。
决策 1~2:RawPayload.assets 成为资产引用载体,Engine 只做防御性复制
决策 1:RawPayload 增加 assets: list[str],作为从调用边界传入 Ingestor 的资产引用载体。
在源码中,该字段定义于 jiuwen_memory/common/type_def/raw.py#L18-L28:
@dataclass
class RawPayload:
id: str = "" # 负载 id
scope: Scope = field(default_factory=Scope)
modality: Modality = Modality.TEXT # 来源模态
data: bytes = b"" # 原始字节;与 uri 二选一
uri: str = "" # 原始数据的外部引用(文件路径/URL/对象存储 key)
...
assets: list[str] = field(default_factory=list) # 待 Ingestor 映射的资产引用
决策 2:InMemoryEngine 与 CloudEngine 只对 write 入参做防御性复制,并将副本放入 RawPayload.assets。以 in_memory_engine.py#L298-L308 为例:
payload = RawPayload(
id=payload_id or str(uuid.uuid4()),
scope=scope,
modality=source,
data=b"" if is_video else content.encode("utf-8"),
uri=content if is_video else "",
assets=list(assets or []), # 防御性复制,不共享可变 list 实例
system_metadata=meta,
user_metadata=dict(user_metadata or {}),
occurred_at=occurred_at,
)
list(assets or <a href="https://link.gitcode.com/i/683d316dbe8a636cc821af886da70a08" target="_blank">]) 这一防御性复制非常关键:它保证调用方在 write 之后继续修改自己的 assets 列表,不会影响已经构造的 RawPayload(也不影响后续 Segment 中的资产)。测试 [test_simple_ingestor.py#L38-L53 专门断言了“payload assets 被等值复制到当前 Segment,且不共享可变 list 实例”(units[0].segments[0].assets is not payload.assets)。
决策 3~4:Ingestor 拥有 assets → segments 的映射责任
决策 3 是最核心的职责划分:Ingestor 拥有 assets 到 MemoryUnit.segments 的映射责任。Engine 在 ingest 返回后:
- 不再新建 Segment;
- 不再回填首 Segment;
- 不再改写任何
Segment.assets。
这从制度上杜绝了 Engine 对 Ingestor 产出结构的二次干涉。Segment 的三元结构(content + assets + source)定义于 memory.py#L110-L122:content 是可治理的文本投影(索引与检索的对象),assets 是本段对应的原模态资产引用,source 是本段来源模态。
决策 4 明确了一个重要边界:当前 SimpleIngestor 产出“单 MemoryUnit / 单 Segment”,并把一个 payload 的全部 assets 复制到该 Segment——这只是具体实现行为,不上升为 Ingestor 接口的数量契约。后续的分块、多模态或聚合型 Ingestor 完全可以产出多 MemoryUnit / 多 Segment。
SimpleIngestor 的实现清晰体现了“记录资产引用 → Normalizer 规约投影 → 转换为 MemoryUnit(不落盘)”三步:
def ingest(self, payloads: list[RawPayload]) -> list[MemoryUnit]:
units: list[MemoryUnit] = []
for payload in payloads:
ensure_normalizer_supports(self._normalizer, payload.modality)
now = _now()
units.append(
MemoryUnit(
id=str(uuid.uuid4()),
scope=payload.scope,
segments=[
Segment(
content=self._normalizer.normalize(payload),
assets=list(payload.assets), # 等值复制资产
source=payload.modality,
)
],
source_ref=payload.id,
temporal=Temporal(...),
system_metadata=dict(payload.system_metadata),
user_metadata=dict(payload.user_metadata),
)
)
return units
注意 assets=list(payload.assets) 同样是防御性复制。Ingestor 接口契约本身定义于 jiuwen_memory/ingest/ingestor.py:ingest(payloads) -> list[MemoryUnit],不落盘(落盘与建索引由构建层负责)。
决策 5:modalities() 是“能不能进”的单一能力声明,不代表“数据放哪里”
决策 5 澄清了一个极易混淆的概念:
Normalizer.modalities()只负责声明“是否支持该模态”(能不能进);- 它不负责决定原始数据应放入
RawPayload.data还是RawPayload.uri(数据放哪里是另一份契约)。
接口定义见 normalizer/base.py#L33-L41:
class Normalizer(Plugin):
@abstractmethod
def modalities(self) -> list[Modality]:
"""返回本规约器支持的模态。"""
@abstractmethod
def normalize(self, payload: RawPayload) -> str:
"""将原模态负载规约为可治理的文本/结构投影(content)。"""
同时,RoutingNormalizer 在构造时校验显式 route 的 delegate:如果某个 route 声明的模态不在其 delegate 的 modalities() 支持集合内,直接抛 ValidationError。见 routing_normalizer.py#L21-L35:
def __init__(self, fallback, routes):
self._fallback = fallback
self._routes = dict(routes)
for modality, normalizer in self._routes.items():
supported = normalizer.modalities()
if modality not in supported:
supported_names = sorted(item.value for item in supported)
raise ValidationError(
f"routing normalizer route {modality.value!r} targets "
f"{type(normalizer).__name__!r}, which supports {supported_names}"
)
例如配置 routes: {video: passthrough}(把视频路由给文本直通规约器)就会在装配期直接失败——PassthroughNormalizer 并不声明支持 VIDEO。测试 test_normalizer_capabilities.py#L58-L63 验证直接构造会抛错,test_multimodal_adapter.py#L364-L379 验证 build_kernel() 装配路径同样拒绝该配置。
RoutingNormalizer.normalize() 的运行时路由逻辑也值得注意:self._routes.get(payload.modality, self._fallback),即按模态命中 delegate,未命中时回退到 fallback,且命中后仍会 ensure_normalizer_supports 二次校验。
决策 6:Ingestor 在 normalize 前校验真实 payload,失败即“统一能力错误”
决策 6 规范了错误语义:Ingestor 在 normalize 之前校验真实 payload 的模态;不支持时抛 UnsupportedCapabilityError,该异常携带 capability / value / component 三段结构化信息,且不产生 MemoryUnit、不落盘、不建索引。
异常类型定义于 errors.py#L127-L145:
class UnsupportedCapabilityError(AgentMemoryError):
def __init__(self, capability: str, value: str, component: str, message: str = ""):
self.capability = capability
self.value = value
self.component = component
super().__init__(message or f"{component or 'component'!r} does not support "
f"{capability or 'capability'} {value!r}")
校验入口是 normalizer/base.py#L43-L51 的 ensure_normalizer_supports,由 SimpleIngestor 在每个 payload 处理前调用:
def ensure_normalizer_supports(normalizer: Normalizer, modality: Modality) -> None:
if modality in normalizer.modalities():
return
raise UnsupportedCapabilityError(
capability="modality",
value=modality.value,
component=type(normalizer).__name__,
)
这一“统一能力错误”语义在三条路径上保持一致:
- Ingestor 侧:SimpleIngestor 对不支持模态直接抛错(测试 test_simple_ingestor.py#L56-L68 断言
capability == "modality"、value == "image"、component == "PassthroughNormalizer"); - Normalizer 侧:PassthroughNormalizer / RoutingNormalizer / VideoNormalizer 在
normalize()内同样先ensure_normalizer_supports; - HTTP 视频入口:缺少视频 Normalizer 时,handler.py#L344-L376 的
_ensure_video_chain采用 fail-closed 策略,同样抛UnsupportedCapabilityError(capability="modality", value="video", component=...)。
HTTP 与 CLI 的错误映射:在直接调用 MemoryAPI 的协议边界,共享错误映射将 UnsupportedCapabilityError 与 ValidationError 统一返回 HTTP 400。映射表见 error_response.py#L8-L26,handler 的状态码绑定见 handler.py#L66-L81。CLI 侧在 commands.py#L114 对 ValidationError 同样返回 400。
另一个容易混淆的边界:已配置 Normalizer 但缺少 video Evolver 时,属于装配问题,抛 ValidationError 而非能力错误——因为能力链本身是配齐的,缺的是下游自演进组件。
决策 7:PassthroughNormalizer 的能力边界——哪些模态能“直通”,哪些不能
决策 7 精确划定了文本直通规约器的能力边界。实现见 passthrough_normalizer.py#L31-L46:
@staticmethod
def modalities() -> list[Modality]:
return [Modality.TEXT, Modality.CODE]
def normalize(self, payload: RawPayload) -> str:
ensure_normalizer_supports(self, payload.modality)
if payload.data:
try:
return payload.data.decode("utf-8")
except UnicodeDecodeError as exc:
raise ValidationError("passthrough normalizer requires UTF-8 text data") from exc
if payload.uri and payload.modality == Modality.TEXT:
return payload.uri # 仅 TEXT 保留 URI 兼容回退
if payload.uri:
raise ValidationError("passthrough normalizer only supports URI fallback for TEXT")
raise ValidationError("RawPayload 既无 data 也无 uri,无法规约出文本投影")
可以总结为一张清晰的边界表:
| 模态 | 是否支持 | 行为 |
|---|---|---|
| TEXT | ✅ | 有 data 时 UTF-8 解码;无 data 时有 uri 则保留 URI 兼容回退 |
| CODE | ✅ | 读取 data 中的 UTF-8 文本直通;不读取源码文件(CODE 的 uri 不触发回退,直接抛 ValidationError) |
| DOCUMENT | ❌ | 需要专用解析型 Normalizer,passthrough 不会把文档原件当普通 content |
| IMAGE / AUDIO / VIDEO | ❌ | 不得把 URI 当作普通 content,一律 UnsupportedCapabilityError |
配套测试覆盖了所有边界分支(test_normalizer_capabilities.py):
IMAGE + uri→UnsupportedCapabilityError(match "modality 'image'");TEXT + uri→ 保留 URI 回退(返回"file:///note.txt");CODE + data→ UTF-8 文本直通;DOCUMENT + data→UnsupportedCapabilityError;CODE + uri→ValidationError(match "URI fallback for TEXT");- 非 UTF-8 文本(
b"\xff")→ValidationError(“非法文本投影”)。
注意 UTF-8 解码失败被投影为 ValidationError,而不是能力错误——这符合“能力已声明,但数据本身非法”的语义。
决策 8:不在 Engine/API 维护模态支持列表
决策 8 是一条重要的“反设计”约束:不在 Engine 或 API 层维护任何模态支持列表,也不增加 assets 数量限制、payload/MemoryUnit/Segment 数量限制。
理由是:支持集合完全由可插拔的 Normalizer 自身声明;而原始数据的载体字段选择(data 还是 uri)是另一份契约,两者不能混为一谈。这也是为什么新增模态无需改动 Engine/API——只要注册一个新的 Normalizer 并在 modalities() 中声明即可。
当前 Engine 的载体字段映射限制(仅对 Modality.VIDEO 将 content 写入 RawPayload.uri,其他模态写入 data)被单独记录为已知遗留(见下文),不通过硬编码列表扩散。
拒绝的方案:三条反面教训
设计文档明确拒绝了三个候选方案,各有充分理由:
- 继续由 Engine 回填首 Segment:拒绝。Engine 不了解 Ingestor 的分段策略,首段假设会覆盖或污染自定义映射结果;
- 在接口上固定
1 RawPayload -> 1 MemoryUnit -> 1 Segment:拒绝。当前 SimpleIngestor 的最小实现不应限制后续分块、多模态或聚合型 Ingestor 的空间; - 在 Engine/API 硬编码全局模态允许列表:拒绝。支持集合应由可插拔 Normalizer 自身声明,且载体字段选择是独立契约。
这三条拒绝与决策 1~8 互为表里,共同构成了“职责下放 + 声明式能力 + 不固化最小实现”的架构取向。
验证:从单元测试到装配层回归
设计文档的验证条目全部有对应测试落地,可以按图索骥:
| 验证点 | 测试位置 |
|---|---|
| SimpleIngestor 将 payload assets 等值复制到当前 Segment,且不共享可变 list | tests/unit/ingest/test_simple_ingestor.py#L38-L53 |
| InMemoryEngine / CloudEngine 注入“把 assets 放入第二个 Segment”的测试 Ingestor,验证 Engine 传入 assets 且保留分段结果 | 对应 Engine 写入路径的定向回归(设计基线记录 59 passed) |
错误 video -> passthrough route 在直接构造与 build_kernel() 装配中均失败 |
tests/unit/common/test_normalizer_capabilities.py#L58-L63、tests/unit/multimodal/test_multimodal_adapter.py#L364-L379 |
| SimpleIngestor / PassthroughNormalizer / RoutingNormalizer / VideoNormalizer 覆盖统一运行时能力错误 | tests/unit/common/test_normalizer_capabilities.py#L66-L73(VideoNormalizer 对 TEXT 报 capability=modality, value=text, component=VideoNormalizer) |
| HTTP 与 CLI 通过共享错误映射返回 400 | jiuwen_memory_entry/core/error_response.py、jiuwen_memory_entry/core/handler.py#L66-L81 |
TEXT URI 回退、UTF-8 CODE 直通、DOCUMENT/媒体拒绝、非法 UTF-8 转 ValidationError |
tests/unit/common/test_normalizer_capabilities.py 全量用例 |
实操:为视频模态装配完整的 Normalizer 链
以 examples/config_multimodal.yml 为参照,可以看出一条完整的多模态装配:RoutingNormalizer(fallback 为 passthrough)+ video route 指向 VideoNormalizer,后者依赖 ASR(DashScope 文件转写)与 LLM(文本总结 / 视觉理解)两个下游端口:
memory_api:
globals:
ingest_max_workers: 1
ingest_max_pending_jobs: 2
normalizer:
default:
target: routing
params:
routes:
video:
target: video
params:
asr_port: video # ASR 端口:dashscope_filetrans
asr_chunk_seconds: 600
llm_port: video_text # 文本总结 LLM
vlm_port: video_vision # 视觉理解 LLM
vlm_max_inline_video_bytes: 52428800 # 默认 50 MiB
temp_root: /tmp/agent-memory-video
asr:
video:
target: dashscope_filetrans
params:
asr_model: qwen3-asr-flash-filetrans
asr_base_url: ${DASHSCOPE_ASR_BASE_URL}
asr_api_key: ${DASHSCOPE_API_KEY}
config_namespace: asr.video
llm:
video_text:
target: openai
params:
llm_model: qwen-text
llm_base_url: http://127.0.0.1:8000/v1
llm_api_key: dummy
llm_temperature: 0.0
config_namespace: llm.video_text
video_vision:
target: openai
# ... 同理,指向视觉模型
与本文主题相关的参数含义:
chunk_seconds(默认 30):视频按秒分片,供 VLM 逐片产出视觉摘要;asr_chunk_seconds(默认 600):ASR 转录的分片时长;vlm_max_inline_video_bytes(默认50 * 1024 * 1024):允许内联进 VLM 的原始视频字节上限,见 video_normalizer.py#L30;temp_root:视频流水线的临时工作目录,缺省走系统临时目录;asr_port/llm_port/vlm_port:通过VideoAsrProducer.dep/LlmProducer.dep按名字解析下游插件,装配期缺依赖即报错。
VideoNormalizer 的产出是一段结构化的 JSON 文本投影(clips + events 两部分),包含 visual_summary、detailed_caption、ASR、environment 等字段(见 video_normalizer.py#L192-L220),同时 asset_uri 保留原始视频引用——这正是“规约投影 + 资产引用”双轨设计的落地形态。
已知遗留:当前边界与未来扩展点
设计文档诚实地记录了四个遗留项,也标明了未来演进方向:
RawPayload.assets仅是list[str]引用,不表达资产类型、存储状态或与 Segment 的结构化关系——后续可考虑引入结构化资产描述;- 当前只有 SimpleIngestor,多 MemoryUnit / 多 Segment 的具体映射能力交给后续 Ingestor 实现,不在本次预先固化接口;
- data/uri 载体契约未完整覆盖:
MemoryEngine.write目前只对Modality.VIDEO把content写入RawPayload.uri,其他模态写入data——因此modalities()只决定“能不能进”,不能解决“数据放哪里”;新增其他外部 URI 模态前,需要单独补充显式的 data/uri 载体契约; - 当前没有 DocumentNormalizer:PDF/Office 等文档原件不能通过 passthrough 解析,需在专用实现落地后再声明 DOCUMENT 能力。
小结
Assets 映射与 Normalizer 能力边界的设计,本质上是一次职责下放与契约澄清:资产如何进入记忆单元由 Ingestor 决定,模态是否被支持由 Normalizer 声明,Engine 退化为纯粹的防御性传递者,错误语义统一收敛到可诊断的 UnsupportedCapabilityError / ValidationError。这套边界既保护了自定义 Ingestor 的映射自由,也为后续多模态、分块、聚合型接入能力保留了清晰的扩展位。