Python
"""
Read-side pipeline trace logger.
把一次 search 调用的各个阶段(embed / recall / bm25 / tag-match / rrf / evolution /
summary)写入通用 `pipeline_logs` 表,step 字符串统一以 `READ_` 为前缀,与 writer
侧(EXTRACT / RECONCILE / SUMMARY / WRITE_SUMMARY)平行。
对外契约:
- 所有埋点调用都是 best-effort:cache 为空或写入失败时静默忽略,不影响主流程
- step 名是常量,inspector 可按步骤前缀检索(如 `step="READ_RECALL_VEC"`)
- 每条 log 的 parsed 字段存 JSON 化的结构化元数据(便于 inspector 解析 UI)
设计取舍:
- 不引入新表,沿用现有 `store_pipeline_log`
- logger 是无状态工具类,按 request/user/agent 绑定后批量复用
- 内部 best-effort try/except 包死,上层调用方不用 try/except
"""
from __future__ import annotations
import functools
import json
import logging
from typing import Any, Dict, List, Optional
logger = logging.getLogger(__name__)
def _best_effort_log(method):
"""包装 log_* 协程方法:任何异常(含参数签名错误)都静默吞掉。
契约保证「埋点绝不影响主流程」。之前若调用方传错 kwarg,会在参数绑定阶段
抛 TypeError(早于内部 try/except),把整个 search 带崩 → total_found=0。
这里在最外层兜住所有异常,彻底落实 best-effort。
"""
@functools.wraps(method)
async def _wrapper(*args, **kwargs):
try:
return await method(*args, **kwargs)
except Exception as e: # noqa: BLE001 — trace 绝不能影响主流程
logger.debug(f"[read-trace] {getattr(method, '__name__', '?')} swallowed: {e}")
return None
return _wrapper
# ================================================================
# Step 常量
# ================================================================
# Reader 共通
STEP_READ_SCENE_JUDGE = "READ_SCENE_JUDGE" # 生产力(coding)/普通场景判定(search 第一步,client 落库)
STEP_READ_REQUEST = "READ_REQUEST" # 入参快照
STEP_READ_EMBED_QUERY = "READ_EMBED_QUERY" # query embedding
STEP_READ_INTENT = "READ_INTENT" # 意图分类结果(hybrid/*_tag)
# 召回通道
STEP_READ_RECALL_VEC = "READ_RECALL_VEC" # 路 A:主向量召回
STEP_READ_HIDDEN_L0_CONTEXT = "READ_HIDDEN_L0_CONTEXT" # L0 used internally, not returned by Search
STEP_READ_KEYWORD_EMBED = "READ_KEYWORD_EMBED" # 路 B:keyword batch embed
STEP_READ_TAG_MATCH = "READ_TAG_MATCH" # 路 B:tag_index 相似度匹配
STEP_READ_RECALL_TAG = "READ_RECALL_TAG" # 路 B:tag filter 向量召回
# 融合 / 排序 / 合成
STEP_READ_BM25 = "READ_BM25" # 路 C:BM25 重排
STEP_READ_RRF = "READ_RRF" # RRF 融合
STEP_READ_MERGE_SCHEMA = "READ_MERGE_SCHEMA" # schema 并入 + 截断
STEP_READ_EVOLUTION = "READ_EVOLUTION" # 演化链回溯合成
STEP_READ_INTENTION = "READ_INTENTION" # L7 意图召回(Proactive 路,含过期转换/补向量/判重)
# 总览
STEP_READ_GRAPH_RERANK = "READ_GRAPH_RERANK" # 图重排/扩展(用法 A/B/C + episode 框选)
STEP_READ_SUMMARY = "READ_SUMMARY" # 聚合总览(对齐 write 侧 WRITE_SUMMARY)
# Coding(productivity)召回路径
STEP_READ_CODING_EMBED = "READ_CODING_EMBED" # coding query embedding
STEP_READ_CODING_VDB = "READ_CODING_VDB" # coding store 向量召回(min_score 过滤前后)
STEP_READ_CODING_RESULT = "READ_CODING_RESULT" # coding 召回最终结果总览
def _safe_json(obj: Any) -> str:
try:
return json.dumps(obj, ensure_ascii=False, default=str)
except Exception:
return "{}"
def _preview_node(item: Dict[str, Any], *, content_limit: int = 120) -> Dict[str, Any]:
"""把一条 hit 压缩成可读性好、体积小的预览结构。"""
node = item.get("node")
content = ""
layer = ""
tags: List[str] = []
if node is not None:
content = (getattr(node, "content", "") or "")[:content_limit]
try:
layer = node.layer.value if node.layer else ""
except Exception:
layer = ""
try:
tags = list(getattr(node, "tags", None) or [])
except Exception:
tags = []
out = {
"node_id": item.get("node_id", ""),
"score": round(float(item.get("score", 0.0)), 6),
"layer": layer,
"content": content,
"tags": tags,
}
if "_semantic" in item:
out["_semantic"] = round(float(item["_semantic"]), 6)
if "_bm25" in item:
out["_bm25"] = round(float(item["_bm25"]), 6)
if item.get("source"):
out["source"] = item["source"]
return out
def _preview_hits(items: List[Dict[str, Any]], *, top: int = 10) -> List[Dict[str, Any]]:
return [_preview_node(it) for it in (items or [])[:top]]
# ================================================================
# Logger
# ================================================================
def _wrap_log_methods(cls):
"""给所有 log_* 协程方法套上 best-effort 包装(含参数签名错误也吞掉)。"""
import inspect
for name, attr in list(vars(cls).items()):
if name.startswith("log_") and inspect.iscoroutinefunction(attr):
setattr(cls, name, _best_effort_log(attr))
return cls
@_wrap_log_methods
class ReadTraceLogger:
"""
Read pipeline 的轻量 trace 写入器。
使用方式:
tracer_log = ReadTraceLogger(cache, request_id, user_id, agent_id)
await tracer_log.log_embed_query(query, dims=384, cache_hit=False, elapsed_ms=12.3)
...
所有 log_* 方法都 best-effort(cache 为 None / 写入异常 / 参数错误 → 静默跳过,
绝不影响主 search 流程)。
"""
def __init__(
self,
cache: Any,
request_id: str,
user_id: str,
agent_id: str,
reader_version: str = "",
session_id: str = "",
):
self._cache = cache
self._request_id = request_id or ""
self._user_id = user_id or ""
self._agent_id = agent_id or "default_agent"
self._reader_version = reader_version or ""
self._session_id = session_id or ""
@property
def enabled(self) -> bool:
return self._cache is not None and bool(self._request_id)
async def _write(
self,
step: str,
*,
prompt: str = "",
response: str = "",
parsed: Optional[Dict[str, Any]] = None,
memory_ids: Optional[List[str]] = None,
elapsed_ms: float = 0.0,
) -> None:
if not self.enabled:
return
try:
# parsed 统一带上 reader 标签,便于 inspector 区分哪一版 reader
p_dict = dict(parsed or {})
if self._reader_version and "_reader" not in p_dict:
p_dict["_reader"] = self._reader_version
await self._cache.store_pipeline_log(
request_id=self._request_id,
user_id=self._user_id,
agent_id=self._agent_id,
session_id=self._session_id,
step=step,
prompt=prompt,
response=response,
parsed=_safe_json(p_dict),
memory_ids=memory_ids or None,
elapsed_ms=float(elapsed_ms or 0.0),
prompt_tokens=0,
completion_tokens=0,
total_tokens=0,
)
except Exception as e:
logger.debug(f"[read-trace] store_pipeline_log step={step} failed: {e}")
# ------------------------------------------------------------------
# 具体步骤埋点
# ------------------------------------------------------------------
async def log_scene_judge(
self,
*,
query: str,
scene: str,
mode: str,
is_coding: bool,
rewrite_query: Optional[str] = None,
rewrite_used: bool = False,
created_after: Optional[str] = None,
elapsed_ms: float = 0.0,
llm_ms: Optional[float] = None,
gc_delta: Optional[int] = None,
throttle_ms: Optional[float] = None,
) -> None:
"""生产力(coding)/普通场景判定。search 的第一步,由 client 在调 reader 前落库。
mode: "explicit"(显式 scene 指定,未调 LLM)/ "llm"(多 query LLM 判类+改写)
/ "default"(单 query 或链路关闭,默认 normal)
created_after: query rewrite 抽出的时间下界,已转成可读日期字符串(如 "2026-06-24"),
无则 None。
耗时字段语义(务必区分,历史上曾混淆过):
- elapsed_ms → 落库为 `parsed.step_ms`:**本环节整体墙钟耗时**(t0 → 本次调用),
与是否调 LLM 无关。mode=default/explicit 时它就是一段纯同步代码的耗时。
- llm_ms: **仅 mode="llm" 时有值**,是那次 judge/rewrite LLM 调用的净耗时。
mode=default/explicit 不调 LLM → 不传 → parsed 里没有这个字段。
运行时停顿归因字段(None 时不落库,保持 parsed 精简):
- gc_delta: 本段(t0 → 本次调用)内 GC 累计次数增量。>=1 说明期间发生过 GC。
- throttle_ms: 本段内 cgroup CPU 被限流的时长(毫秒)。≈step_ms 说明是容器
CPU throttling 导致的停顿。
三者与 elapsed_ms 同为业务侧同步求值,可信度一致;用于区分
GIL 争抢 / GC 长停顿 / cgroup throttling 三类进程级停顿。
"""
_parsed = {
"scene": scene,
"mode": mode,
"is_coding": is_coding,
"rewrite_query": rewrite_query,
"rewrite_used": rewrite_used,
"created_after": created_after,
}
if llm_ms is not None:
_parsed["llm_ms"] = round(float(llm_ms), 2)
if gc_delta is not None:
_parsed["gc_delta"] = int(gc_delta)
if throttle_ms is not None:
_parsed["throttle_ms"] = round(float(throttle_ms), 2)
await self._write(
STEP_READ_SCENE_JUDGE,
prompt=query or "",
response=_safe_json({
"scene": scene,
"mode": mode,
"is_coding": is_coding,
"rewrite_used": rewrite_used,
"created_after": created_after,
}),
parsed=_parsed,
elapsed_ms=elapsed_ms,
)
async def log_coding_embed(
self,
*,
query: str,
dims: int = 0,
elapsed_ms: float = 0.0,
provider_meta: Optional[Dict[str, Any]] = None,
) -> None:
"""coding 路径:query embedding。"""
parsed: Dict[str, Any] = {"dims": dims}
if provider_meta:
parsed["provider_meta"] = provider_meta
await self._write(
STEP_READ_CODING_EMBED,
prompt=query or "",
response=_safe_json({"dims": dims}),
parsed=parsed,
elapsed_ms=elapsed_ms,
)
async def log_coding_vdb(
self,
*,
query: str,
raw_hits: int,
kept_hits: int,
min_score: float,
top_scores: Optional[List[float]] = None,
workspace_id: Optional[str] = None,
branch: Optional[str] = None,
elapsed_ms: float = 0.0,
) -> None:
"""coding 路径:coding store 向量召回 + min_score 过滤。
raw_hits: 过采样召回条数;kept_hits: min_score 过滤后条数。
top_scores: 过滤前 top 分数,便于诊断"是分数不够还是库为空"。
"""
await self._write(
STEP_READ_CODING_VDB,
prompt=query or "",
response=_safe_json({
"raw_hits": raw_hits,
"kept_hits": kept_hits,
"min_score": min_score,
}),
parsed={
"raw_hits": raw_hits,
"kept_hits": kept_hits,
"min_score": min_score,
"top_scores": [round(float(s), 4) for s in (top_scores or [])[:10]],
"workspace_id": workspace_id,
"branch": branch,
},
elapsed_ms=elapsed_ms,
)
async def log_coding_result(
self,
*,
query: str,
returned: int,
memory_ids: Optional[List[str]] = None,
previews: Optional[List[Dict[str, Any]]] = None,
elapsed_ms: float = 0.0,
) -> None:
"""coding 路径:最终返回结果总览(search 收尾)。"""
await self._write(
STEP_READ_CODING_RESULT,
prompt=query or "",
response=_safe_json({"returned": returned}),
parsed={"returned": returned, "hits": previews or [],
"elapsed_ms": round(float(elapsed_ms or 0.0), 2)},
memory_ids=memory_ids or None,
# 收尾总览:elapsed_ms 是整条 coding search 的总耗时(汇总值,非单环节),
# 落库 elapsed_ms 字段置 0,总耗时保留在 parsed.elapsed_ms。
elapsed_ms=0,
)
async def log_request(
self,
*,
query: str,
limit: int,
layers: Optional[List[str]],
min_score: float = 0.0,
schema_min_score: Optional[float] = None,
schema_limit: Optional[int] = None,
user_ids: List[str],
agent_ids: List[str],
session_ids: List[str],
intention_limit: Optional[int] = None,
) -> None:
# intention_limit:调用方传入的 L7 意图召回上限。0 或 None 都会导致
# reader 跳过 intention 通道;把它明确落进 READ_REQUEST.parsed,才能
# 从日志区分「上游没传」和「reader 内部跳过」这两种截然不同的失败模式
# (0805 事故追查耗时的直接原因)。
parsed = {
"query": query,
"limit": limit,
"layers": layers,
"min_score": min_score,
"schema_min_score": schema_min_score,
"schema_limit": schema_limit,
"intention_limit": intention_limit,
"user_ids": user_ids,
"agent_ids": agent_ids,
"session_ids": session_ids,
}
await self._write(
STEP_READ_REQUEST,
prompt=query or "",
response=_safe_json({
"limit": limit,
"min_score": min_score,
"user_ids": user_ids,
"agent_ids": agent_ids,
"session_ids": session_ids,
}),
parsed=parsed,
)
async def log_embed_query(
self,
*,
query: str,
dims: int,
cache_hit: bool,
elapsed_ms: float = 0.0,
provider_meta: Optional[Dict[str, Any]] = None,
) -> None:
parsed: Dict[str, Any] = {"dims": dims, "cache_hit": cache_hit}
if provider_meta:
parsed["provider_meta"] = provider_meta
await self._write(
STEP_READ_EMBED_QUERY,
prompt=query or "",
response=_safe_json({"dims": dims, "cache_hit": cache_hit}),
parsed=parsed,
elapsed_ms=elapsed_ms,
)
async def log_intent(self, *, query: str, intent: str, keywords: List[str]) -> None:
await self._write(
STEP_READ_INTENT,
prompt=query or "",
response=intent,
parsed={"intent": intent, "keywords": keywords},
)
async def log_recall_vec(
self,
*,
pool_size: int,
hits: List[Dict[str, Any]],
elapsed_ms: float = 0.0,
sparse_query: Optional[Dict[str, Any]] = None,
) -> None:
preview = _preview_hits(hits)
parsed = {
"pool_size": pool_size,
"returned": len(hits),
"hits": preview,
}
if sparse_query is not None:
parsed["sparse_query"] = sparse_query
await self._write(
STEP_READ_RECALL_VEC,
prompt=f"limit={pool_size}",
response=_safe_json({"count": len(hits), "top": preview[:5]}),
parsed=parsed,
memory_ids=[h.get("node_id", "") for h in hits if h.get("node_id")],
elapsed_ms=elapsed_ms,
)
async def log_hidden_l0_context(
self,
*,
hits: List[Dict[str, Any]],
elapsed_ms: float = 0.0,
) -> None:
preview = _preview_hits(hits)
parsed = {
"returned": len(hits),
"hits": preview,
}
await self._write(
STEP_READ_HIDDEN_L0_CONTEXT,
prompt="",
response=_safe_json({"count": len(hits), "top": preview[:5]}),
parsed=parsed,
memory_ids=[h.get("node_id", "") for h in hits if h.get("node_id")],
elapsed_ms=elapsed_ms,
)
async def log_keyword_embed(
self,
*,
keywords: List[str],
vec_count: int,
elapsed_ms: float = 0.0,
provider_metas: Optional[List[Dict[str, Any]]] = None,
) -> None:
parsed: Dict[str, Any] = {"keywords": keywords, "vec_count": vec_count}
if provider_metas is not None:
parsed["provider_metas"] = provider_metas
await self._write(
STEP_READ_KEYWORD_EMBED,
prompt=_safe_json(keywords),
response=_safe_json({"vec_count": vec_count}),
parsed=parsed,
elapsed_ms=elapsed_ms,
)
async def log_tag_match(
self,
*,
keywords: List[str],
hit_tags: List[str],
topk: int,
min_score: float,
elapsed_ms: float = 0.0,
) -> None:
parsed = {
"keywords": keywords,
"hit_tags": hit_tags,
"topk": topk,
"min_score": min_score,
}
await self._write(
STEP_READ_TAG_MATCH,
prompt=_safe_json(keywords),
response=_safe_json(hit_tags),
parsed=parsed,
elapsed_ms=elapsed_ms,
)
async def log_recall_tag(
self,
*,
hit_tags: List[str],
pool_size: int,
hits: List[Dict[str, Any]],
elapsed_ms: float = 0.0,
) -> None:
preview = _preview_hits(hits)
parsed = {
"hit_tags": hit_tags,
"pool_size": pool_size,
"returned": len(hits),
"hits": preview,
}
await self._write(
STEP_READ_RECALL_TAG,
prompt=_safe_json(hit_tags),
response=_safe_json({"count": len(hits), "top": preview[:5]}),
parsed=parsed,
memory_ids=[h.get("node_id", "") for h in hits if h.get("node_id")],
elapsed_ms=elapsed_ms,
)
async def log_bm25(
self,
*,
pool_size: int,
query_terms: List[str],
hits: List[Dict[str, Any]],
raw_hits: Optional[List[Dict[str, Any]]] = None,
bm25_scores: Optional[Dict[str, float]] = None,
normalize_method: Optional[str] = None,
sigmoid_midpoint: Optional[float] = None,
sigmoid_steepness: Optional[float] = None,
has_bm25: Optional[bool] = None,
elapsed_ms: float = 0.0,
sparse_query: Optional[Dict[str, Any]] = None,
) -> None:
"""BM25/keyword 路埋点。
除融合后的 `hits` 外,尽量暴露 BM25 的「具体情况」:
- keyword_count / has_bm25:本 query 后端关键词召回是否命中(决定是否触发加权);
- normalize_method:`passthrough`(后端分已在 [0,1])/
`sigmoid`(经典 BM25 原始分 → sigmoid 归一化);
- sigmoid_midpoint / sigmoid_steepness:sigmoid 归一化参数(随 query 词数自适应);
- bm25_detail:每条关键词命中的 raw → normalized 变换(看清单条 BM25 如何参与打分);
- sparse_query:BM25Encoder.encode_queries 产出的 sparse(nnz + 完整 [[token_id, weight], ...])。
"""
preview = _preview_hits(hits)
# 关键词命中的 raw→normalized 明细(按 raw 分降序,便于排查)
bm25_detail: List[Dict[str, Any]] = []
_scores = bm25_scores or {}
_raw = raw_hits if raw_hits is not None else []
for r in sorted(_raw, key=lambda x: x.get("score", 0.0), reverse=True)[:20]:
nid = r.get("node_id", "")
bm25_detail.append({
"node_id": nid,
"raw": round(float(r.get("score", 0.0)), 6),
"norm": round(float(_scores.get(nid, 0.0)), 6),
})
keyword_count = len(_raw)
_has = has_bm25 if has_bm25 is not None else bool(_scores or _raw)
parsed = {
"pool_size": pool_size,
"query_terms": query_terms,
"keyword_count": keyword_count,
"has_bm25": _has,
"normalize_method": normalize_method,
"sigmoid_midpoint": round(float(sigmoid_midpoint), 6) if sigmoid_midpoint is not None else None,
"sigmoid_steepness": round(float(sigmoid_steepness), 6) if sigmoid_steepness is not None else None,
"bm25_detail": bm25_detail,
"returned": len(hits),
"hits": preview,
}
if sparse_query is not None:
parsed["sparse_query"] = sparse_query
await self._write(
STEP_READ_BM25,
prompt=_safe_json(query_terms),
response=_safe_json({
"keyword_count": keyword_count,
"has_bm25": _has,
"normalize_method": normalize_method,
"top_bm25": bm25_detail[:5],
"sparse_nnz": (sparse_query or {}).get("nnz") if sparse_query else None,
}),
parsed=parsed,
memory_ids=[h.get("node_id", "") for h in hits if h.get("node_id")],
elapsed_ms=elapsed_ms,
)
async def log_rrf(
self,
*,
channels: Dict[str, int], # {"vec": 30, "tag": 18, "bm25": 12}
weights: Dict[str, float],
fused: List[Dict[str, Any]],
confidence: float,
is_low_confidence: bool,
top_n: int = 10,
) -> None:
preview: List[Dict[str, Any]] = []
for item in (fused or [])[:top_n]:
preview.append({
"node_id": item.get("node_id", ""),
"rrf_score": round(float(item.get("rrf_score", 0.0)), 6),
"rank_by_channel": item.get("rrf_rank_by_channel", {}),
"per_channel_score": {
k: round(float(v), 6)
for k, v in (item.get("per_channel_score") or {}).items()
},
})
parsed = {
"channels": channels,
"weights": weights,
"confidence": round(float(confidence), 4),
"is_low_confidence": bool(is_low_confidence),
"top": preview,
}
await self._write(
STEP_READ_RRF,
prompt=_safe_json(weights),
response=_safe_json({
"confidence": round(float(confidence), 4),
"is_low_confidence": bool(is_low_confidence),
"top": preview[:5],
}),
parsed=parsed,
memory_ids=[p["node_id"] for p in preview if p.get("node_id")],
)
async def log_merge_schema(
self,
*,
fused_size: int,
schema_size: int,
merged_size: int,
final_limit: int,
) -> None:
await self._write(
STEP_READ_MERGE_SCHEMA,
prompt="",
response=_safe_json({
"fused_size": fused_size,
"schema_size": schema_size,
"merged_size": merged_size,
"final_limit": final_limit,
}),
parsed={
"fused_size": fused_size,
"schema_size": schema_size,
"merged_size": merged_size,
"final_limit": final_limit,
},
)
async def log_graph_rerank(
self,
*,
stats: Optional[Dict[str, Any]] = None,
pool_size: int = 0,
admitted_ids: Optional[List[str]] = None,
elapsed_ms: float = 0.0,
) -> None:
"""图重排 / 扩展(用法 A/B/C + episode 框选)。
这一步的效果**必须能和"池子变大"区分开**,所以 stats 要同时带上漏斗各级的存量:
edges / propagated / reachable / episode_candidates / prefiltered / admitted / paths。
少了它线上只能看到"结果变了",无法归因到是哪一级放进来的。
"""
st = dict(stats or {})
st["pool_size"] = pool_size
if admitted_ids:
st["admitted_ids"] = list(admitted_ids)[:50]
await self._write(
STEP_READ_GRAPH_RERANK,
prompt="",
response=_safe_json(st),
parsed=st,
memory_ids=list(admitted_ids or [])[:50] or None,
elapsed_ms=elapsed_ms,
)
async def log_evolution(
self,
*,
input_size: int,
evolved_count: int,
elapsed_ms: float = 0.0,
) -> None:
await self._write(
STEP_READ_EVOLUTION,
prompt="",
response=_safe_json({
"input_size": input_size,
"evolved_count": evolved_count,
}),
parsed={
"input_size": input_size,
"evolved_count": evolved_count,
},
elapsed_ms=elapsed_ms,
)
async def log_intention(
self,
*,
stats: Optional[Dict[str, Any]] = None,
elapsed_ms: float = 0.0,
) -> None:
"""L7 意图召回(Proactive 路)分段耗时与数量。
这一步此前**完全没有埋点**,导致 READ_EVOLUTION → READ_SUMMARY 之间
出现无法解释的空白(线上见过 426ms)。stats 由
`_retrieval.intention.recall_intentions()` 通过 stats_out 回填,
分段拆开各子环节,便于直接定位是哪一段慢:
- `vdb_search_ms` VDB 向量检索(超采样捞 L7,fetch_limit=limit×6)
- `expire_ms` 惰性过期转换(逐条 update_payload 转 L2_FACT)
- `backfill_embed_ms` 判重前补拉缺失 embedding(get_embeddings)
- `dedup_ms` 判重(cosine 两两比较,纯 CPU)
- `total_ms` recall_intentions 端到端
数量类:`fetched` / `expired` / `survivors` / `dedup_dropped` / `returned`
`stats.total_ms` 表示函数自身端到端耗时,适合跨调用路径比较。
"""
await self._write(
STEP_READ_INTENTION,
parsed=dict(stats or {}),
elapsed_ms=elapsed_ms,
)
async def log_summary(
self,
*,
query: str,
intent: Optional[str],
confidence: Optional[float],
is_low_confidence: Optional[bool],
channels: Dict[str, int],
total_found: int,
elapsed_ms: float,
returned_memories: List[Dict[str, Any]],
) -> None:
"""一次 search 的总览日志,对齐 writer 侧的 WRITE_SUMMARY 作用。"""
parsed = {
"query": query,
"reader": self._reader_version,
"intent": intent,
"confidence": round(float(confidence), 4) if confidence is not None else None,
"is_low_confidence": is_low_confidence,
"channels": channels,
"total_found": total_found,
"elapsed_ms": round(float(elapsed_ms or 0.0), 2),
"returned": [
{
"memory_id": m.get("memory_id", ""),
"layer": m.get("layer", ""),
"score": round(float(m.get("score", 0.0)), 6),
"content": (m.get("content", "") or "")[:160],
"tags": m.get("tags") or [],
}
for m in (returned_memories or [])[:20]
],
}
await self._write(
STEP_READ_SUMMARY,
prompt=query or "",
response=_safe_json({
"reader": self._reader_version,
"intent": intent,
"confidence": parsed["confidence"],
"total_found": total_found,
"elapsed_ms": parsed["elapsed_ms"],
}),
parsed=parsed,
memory_ids=[m.get("memory_id") for m in (returned_memories or []) if m.get("memory_id")],
# 一次 search 的总览:elapsed_ms 是整条 search 的总耗时(汇总值,非单环节),
# 落库 elapsed_ms 字段置 0,总耗时保留在 parsed.elapsed_ms / response。
elapsed_ms=0,
)