Memory Search 上游参数增量兼容设计

目标

扩展 Memory Gateway 的 POST /memories/search，在保留现有用户鉴权、 scope 搜索编排、资源隔离、软删除和覆盖修改能力的前提下，支持上游搜索接口的全部请求选项。

本次只修改 /memories/search，不新增 /memories/get，也不提供上游路径的线协议兼容接口。

请求模型

保留现有字段：

user_id：必填，始终用于 Gateway 用户鉴权和本地数据隔离。
user_key：必填，用于 Gateway 用户鉴权。
conversation_id：可选，供 current_chat scope 生成 session 过滤条件。
query：必填。
scope：保留 current_chat、resources、all_user_memory。
app_id、project_id：默认 default。

新增或扩展字段：

agent_id：可选。存在时，上游搜索使用 agent_id；不存在时使用 Gateway 鉴权用户的 user_id。请求中不会同时向上游发送两种 owner ID。
method：支持 keyword、vector、hybrid、agentic，默认 hybrid。
top_k：支持 -1 或 1..100，保留 Gateway 默认值 8。
radius：可选，范围 0..1。
include_profile：布尔值，默认 true。
enable_llm_rerank：布尔值，默认 true。
filters：可选对象，支持上游开放字段过滤 DSL，包括嵌套 AND、OR。

agent_id 只改变上游记忆 owner，不替代 Gateway 的 user_id/user_key 鉴权。这可以防止调用者绕过 Gateway 用户体系，同时允许同一已认证用户查询被授权使用的 agent memory。当前版本不新增 agent 权限表，因此仅校验 Gateway 用户凭据，不声明 agent 的独立所有权关系。

搜索编排与过滤器合并

每一次上游 search 调用都必须透传：

owner：agent_id 或 user_id，二选一；
query；
method；
top_k；
radius，仅在请求提供时发送；
include_profile；
enable_llm_rerank；
app_id；
project_id；
合并后的 filters。

现有 scope 继续生成内部 session 条件：

current_chat：session_id = chat:{conversation_id}；
resources：按批次生成 session_id in [...]；
all_user_memory：不生成 session 条件。

当请求同时提供自定义 filters 和 scope session 条件时，使用以下结构合并：

{
  "AND": [
    {"自定义过滤条件": "..."},
    {"session_id": "scope 生成的条件"}
  ]
}

仅存在其中一个条件时直接使用该条件；两者都不存在时不发送 filters。 Gateway 不解析或重写自定义过滤 DSL 的内部字段，由上游执行完整校验。

agent_id 与所有 scope 均可组合。对于没有对应数据的组合，上游自然返回空数组； Gateway 不额外禁止这些组合，以保持接口简单并完整透传搜索能力。

响应标准化

继续返回 Gateway 的统一结构：

{
  "results": []
}

每个结果新增 memory_type：

上游数组	`memory_type`
`episodes`	`episode`
`profiles`	`profile`
`agent_cases`	`agent_case`
`agent_skills`	`agent_skill`
`unprocessed_messages`	`unprocessed_message`

其余字段保持现状：id、session_id、text、score、source_scope、 resource_id、resource_uri 和 raw。

profile 和 agent skill 等没有 session_id 的结果允许返回 null。资源映射只对能匹配当前用户资源 session 的结果生效，不泄露其他用户的内部资源 URI。

所有类型的结果继续按现有顺序执行：

合并各 scope 的结果；
应用当前用户的 memory tombstone；
按 memory ID 应用当前用户的 active override；
返回统一结果。

错误处理

不合法的 method、top_k 或 radius 由 Gateway 请求模型返回 HTTP 422。
上游过滤 DSL 错误和其他 HTTP 错误继续由现有 client 行为向外传播。
不改变当前 current_chat 缺少 conversation_id 时跳过该 scope 的行为。
不为 agent_id 引入新的数据库表或权限模型。

代码改动

core/api.py
- 扩展 SearchMemoriesRequest。
- 将新增参数传给 service。
core/service.py
- 扩展 search_memories 和 _search_payload。
- 合并自定义 filters 与 scope filters。
- 标准化结果时增加 memory_type。
tests/test_gateway.py
- 验证默认参数透传。
- 验证全部自定义搜索选项透传。
- 验证 agent owner 与用户鉴权身份分离。
- 验证 filters 与 scope 条件使用 AND 合并。
- 验证五类结果的 memory_type。
README.md
- 更新 /memories/search 参数和响应说明。

验收标准

未提供新字段时，上游收到 method=hybrid、include_profile=true、 enable_llm_rerank=true。
所有上游搜索选项均能通过 Gateway 请求并原样传递。
top_k=-1 被接受，top_k=0 和范围外值被拒绝。
自定义 filters 不会覆盖 scope 的资源或聊天 session 隔离条件。
设置 agent_id 后，上游只收到 agent_id，Gateway 仍使用 user_id/user_key 完成鉴权。
每个搜索结果包含准确的 memory_type。
现有 tombstone、override、资源 URI 隔离测试继续通过。

5.2 KiB Raw Permalink Blame History Unescape Escape