Python
# -*- coding: utf-8 -*-
"""
Coding Memory - Extractor
一次 LLM 调用,对同一段轨迹产出双层草稿:
- 经验层 experiences(有价值才抽):task / search_keys / solution /
boundary_envs / confidence。价值门槛严格,rename a file 这种琐碎操作不该成
memory;只抽取未来可能复发的有价值问题。
- 事实层 fact(模型可返回 0 或 1 条):statement / files。statement 是这次会话的
小结——用户要做什么 / 大致怎么做的 / 结果如何。模型未产出时是否存原文 fallback
由 `MEMORY_CODING_VERBATIM_FALLBACK_ENABLED` 控制,默认关闭。
复用 LLMConfig.model(与 chat extractor 共用同一 LLM 配置)。
"""
import json
import logging
import time
from typing import List, Optional, Dict, Any, Tuple
from ..agent.llm_provider import LLMProvider
from ..pipelines.base import ChatMessage
from ..prompts import (
get_prompt,
normalize_language,
resolve_language,
with_output_language,
)
from .preproc import (
extract_files,
keep_last_k_user_turns,
prepare_extractor_messages,
)
from .judge import _store_coding_log
from .types import CodingMemoryDraft, WorkingFactDraft
logger = logging.getLogger(__name__)
def _resolve_configured_temperature(llm_provider) -> Optional[float]:
"""从 MemoryConfig.llm 解析温度;None = 请求里不带该参数。"""
config = getattr(llm_provider, "config", None)
llm = getattr(config, "llm", None) if config is not None else None
if llm is not None:
if getattr(llm, "omit_temperature", False):
return None
temp = getattr(llm, "temperature", None)
if temp is not None:
return float(temp)
inner = getattr(llm_provider, "_llm_config", None)
temp = getattr(inner, "temperature", None) if inner is not None else None
return float(temp) if temp is not None else None
# subject 是等值比较的硬键,一句话说明抽取跑偏了,按"没抽到主体"处理。
_MAX_SUBJECT_CHARS = 80
# details 存原文,要装得下一份完整计划表 / 配置块,但不能让单条事实吃掉整个提示词。
_MAX_DETAILS_CHARS = 4000
# 兜底 statement 是检索向量,太长会被无关内容稀释;一两段用户原话足够。
# 同一个理由也约束正常路径的长度:提示词把 statement 的软上限定在 1200 字符左右,
# 靠"给定量写成数据而非对话原句"来达到,不靠砍覆盖 —— details 不进检索向量,
# statement 是检索命中后最主要的可读字段。
_VERBATIM_STATEMENT_CHARS = 600
# ================================================================
# Prompt
# ================================================================
from ..prompts.en import CODING_EXTRACT_PROMPT as EXTRACT_PROMPT # noqa: E402,F401 (re-export)
# ================================================================
# Prompt —— scene="coding"(软件工程场景)
# ================================================================
# 与上面 EXTRACT_PROMPT(scene="working") 的关系: 同一个抽取器、同一套占位符
# ({workspace_present}/{branch_present}/{conversation_block})、同一个输出 schema,
# 只换规范。两份并存而不是改一份, 是因为两个场景对 statement 的要求不同,
# 共用一份会让其中一个场景的规范被另一个稀释。
#
# 这份独有的三块(working 侧没有):
# 1. HARD CONSTRAINT 头部 —— 前置覆盖后文任何"想要叙事"的措辞: 语法主语必须是
# CODE 或 DECISION 而非 "the user"; 不许以 "the session was completed" 收尾;
# 必须保留具体症状(报错串/失败命令/错误输出), 那是未来检索的命中面。
# 2. CODE WORK 整节 —— 四件未来 agent 无法从代码反推的东西: 分支名(逐字)、
# 哪一版赢了(settled on A; interim B dropped)、精确坐标(仓相对路径+符号,
# 不是贴代码)、verified 还是仅 written。它明确不要求更长, 要求同样预算花在
# 更高价值的 token 上。
# 3. statement 的三段式 —— OPEN 症状(用户会怎么报) → THEN 坐标+决策 →
# CLOSE 证据状态。硬顶 ~400 latin 字符。
#
# 这份少掉的(working 侧有、coding 侧刻意不带):
# · "问用户"排除段 —— 卡在向用户要参数时强制 experiences: []。coding 场景的
# 轨迹是 agent 自主执行, 不存在这种停顿。
# · statement PART 2 的 TASK-SCOPED GIVENS 逐行记法 —— coding 侧的给定量是
# 代码坐标, 已由 CODE WORK 节覆盖。
# · details 的产物复制规范 —— coding 侧 details 不进检索向量也不注入。
#
# 修改 prompt 时应使用代表性 coding traces 做回归,确认坐标、决策与验证状态仍保留。
from ..prompts.en import CODING_EXTRACT_PROMPT_CODING as EXTRACT_PROMPT_CODING # noqa: E402,F401 (re-export)
# ================================================================
# CodingMemoryExtractor
# ================================================================
class CodingMemoryExtractor:
"""
LLM 驱动的双层抽取器。
输入:本次完整 New Messages + 历史最近 K 个 user-turn;两部分的 LLM 视图均限长
输出:(List[CodingMemoryDraft], List[WorkingFactDraft])
事实层一段轨迹只产一条,所以返回的 fact 列表长度恒为 0 或 1;用列表而不用
Optional 是为了让 writer / reconciler 的签名不必跟着改。
"""
def __init__(
self,
llm_provider: LLMProvider,
max_tokens: int = 6000,
temperature: Optional[float] = None,
cache: Any = None,
scene: str = "working",
verbatim_fallback_enabled: bool = False,
):
# scene 决定用哪份抽取规范。直接构造 extractor 时默认 working;client 的
# scene=None 自动路由会先经三分类 judge,再构造对应 variant。
# "working" → EXTRACT_PROMPT (办公 / 通用生产力)
# "coding" → EXTRACT_PROMPT_CODING (软件工程)
# 非法值不抛错、退回 working:抽取是一次性的,为一个拼错的参数让整段
# 写入失败不值得。
self.scene = "coding" if str(scene or "").strip().lower() == "coding" else "working"
self._prompt_tmpl = (
EXTRACT_PROMPT_CODING if self.scene == "coding" else EXTRACT_PROMPT
)
self.llm_provider = llm_provider
self.max_tokens = max_tokens
# 默认关闭:原文兜底可能把 assistant/tool 轨迹直接写进 statement,随后被
# 搜索消费者当作记忆正文展示。需要旧行为时由 CodingConfig 显式开启。
self.verbatim_fallback_enabled = bool(verbatim_fallback_enabled)
# cache 非空时落 CODING_EXTRACT pipeline log(best-effort)
self.cache = cache
# None → 使用 LLMConfig.temperature(避免硬编码触发 kimi/deepseek 的温度硬约束)
if temperature is None:
# None 一路传到 provider = 不带该参数;此前兜 0.1 会绕过用户配置,
# 在只接受特定 temperature 的网关上(Opus 5 只收 1 或不传)直接 400
temperature = _resolve_configured_temperature(llm_provider)
self.temperature = temperature
@staticmethod
def _language_text(messages: List[ChatMessage]) -> str:
"""Use new user text for routing; tool output must not dominate it."""
user_parts = [
str(message.content or "").strip()
for message in messages
if message.role == "user" and str(message.content or "").strip()
]
if user_parts:
return "\n".join(user_parts)
non_tool_parts = [
str(message.content or "").strip()
for message in messages
if message.role != "tool" and str(message.content or "").strip()
]
if non_tool_parts:
return "\n".join(non_tool_parts)
return "\n".join(
str(message.content or "").strip()
for message in messages
if str(message.content or "").strip()
)
def _select_prompt_template(
self, messages: List[ChatMessage], language: Optional[str] = None,
) -> Tuple[str, str]:
"""Return (template, language code) for this write's new messages.
Explicit ``language`` wins; otherwise zh/en auto-detection over the new
user text (unchanged behaviour).
"""
code = resolve_language(language, self._language_text(messages))
if code == "en":
return self._prompt_tmpl, code
name = (
"CODING_EXTRACT_PROMPT_CODING" if self.scene == "coding"
else "CODING_EXTRACT_PROMPT"
)
return get_prompt(name, code), code
async def extract(
self,
messages: List[ChatMessage],
*,
history_messages: Optional[List[ChatMessage]] = None,
tool_result_max_bytes: int = 2048,
user_id: str,
agent_id: str = "default_agent",
workspace_id: Optional[str] = None,
branch: Optional[str] = None,
session_id: Optional[str] = None,
request_id: str = "",
language: Optional[str] = None,
) -> Tuple[List[CodingMemoryDraft], List[WorkingFactDraft]]:
"""
Args:
messages: 本次 write 的完整新消息;只做单条限长,不裁 turn
history_messages: 之前 write 的历史消息;仅取最近 5 个 user-turn 作消解上下文
user_id / agent_id / workspace_id / branch / session_id: SDK 注入
language: 显式 prompt 语言码;None 时按新 user 文本做 zh/en 自动检测
Returns:
(经验草稿, 事实草稿)。两层都可能为空。只有显式启用
verbatim_fallback_enabled 时,模型没产出 fact 才调用 _verbatim_fact。
"""
if not messages:
return [], []
# New Messages 是本次 write 的抽取主体:无论传入 1 个还是 10 个 user-turn,
# 都必须完整进入 prompt;这里只限制每条 tool / assistant 的体积。
new_messages = prepare_extractor_messages(
messages, tool_max_bytes=tool_result_max_bytes,
)
# Last 5 User Turns 是之前 write 的历史,只用于指代消解和上下文。绝不能拿
# last-K 去裁本次输入,否则 write(10 turns) 会静默丢掉前 5 个 turn。
history_window = keep_last_k_user_turns(
prepare_extractor_messages(
history_messages or [], tool_max_bytes=tool_result_max_bytes,
),
k=5,
)
history_block = self._format_conversation(history_window).strip()
new_block = self._format_conversation(new_messages).strip()
explicit_language = normalize_language(language)
prompt_tmpl, prompt_language = self._select_prompt_template(
new_messages, explicit_language,
)
empty_block = get_prompt("CODING_EMPTY_BLOCK", prompt_language)
conversation_block = get_prompt(
"CODING_CONVERSATION_BLOCK", prompt_language,
).format(
history=history_block or empty_block,
new=new_block or empty_block,
)
prompt = prompt_tmpl.format(
workspace_present=str(bool(workspace_id)).lower(),
branch_present=str(bool(branch)).lower(),
conversation_block=conversation_block,
)
prompt = with_output_language(
prompt, prompt_language, explicit=explicit_language is not None,
)
_t0 = time.perf_counter()
try:
resp = await self.llm_provider.complete(
prompt=prompt,
max_tokens=self.max_tokens,
audit_stage="coding_extract",
)
except Exception as e:
logger.warning(f"[coding-extract] LLM call failed: {e}")
# 经验层不兜底。事实层原文兜底也默认关闭,避免 assistant/tool 轨迹被
# 当作 statement 直接展示;仅在配置显式开启时保留旧行为。
verbatim = (
self._verbatim_fact(messages)
if self.verbatim_fallback_enabled else None
)
fact_source = (
"verbatim_fallback" if verbatim
else "verbatim_fallback_disabled"
if not self.verbatim_fallback_enabled
else "none"
)
await _store_coding_log(
self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
session_id=session_id or "", step="CODING_EXTRACT", prompt=prompt,
response=f"[LLM error] {type(e).__name__}: {str(e)[:300]}",
parsed=json.dumps(
{
"drafts": 0,
"llm_error": True,
"facts": [verbatim.to_dict()] if verbatim else [],
"fact_count": 1 if verbatim else 0,
"fact_source": fact_source,
},
ensure_ascii=False,
),
elapsed_ms=round((time.perf_counter() - _t0) * 1000, 2),
)
return [], ([verbatim] if verbatim else [])
_elapsed = round((time.perf_counter() - _t0) * 1000, 2)
raw_experiences, raw_facts = self._parse_output(resp.content)
# 经验层的 files 走规则抽取(整段轨迹碰过的文件);事实层的 files 由 LLM
# 给,它挑的是"这次真正动过/查过的",比规则抽取的全集更贴会话小结
files = extract_files(messages)
drafts: List[CodingMemoryDraft] = []
for raw in raw_experiences:
d = self._normalize_draft(
raw,
user_id=user_id,
agent_id=agent_id,
workspace_id=workspace_id,
branch=branch,
session_id=session_id,
files=files,
)
if d is not None:
drafts.append(d)
fact_drafts: List[WorkingFactDraft] = []
for raw in raw_facts:
f = self._normalize_fact_draft(raw)
if f is not None:
fact_drafts.append(f)
# details 不信 LLM 的抄写,改从未压缩的 messages 直接取。
#
# 抽取提示词里的对话是窗口化、截断过的(见 preproc),长 assistant 文本的
# 中段在建 prompt 时已经不在了。让模型"逐字抄写"一段它看不到的原文,只能
# 抄出带省略标记的头尾。
#
# details 的意义是留住被摘要丢掉的可寻址产物(计划表、配置块等)。它不进
# 检索向量(见 store._upsert_fact_vec),长度不影响召回,没有理由再走一遍
# 有损通道——直接取原文,只受 details 自己的上限约束。
#
# 注意:绕过一个有损环节不等于修好它。输入侧的截断阈值同样会影响 statement,
# 见 preproc.DEFAULT_ASSISTANT_HEAD_CHARS。
#
# LLM 给的 details 仍然留着当兜底:messages 为空这种情况下它是唯一来源。
verbatim_details = self._verbatim_details(messages)
if verbatim_details:
fact_drafts = [
WorkingFactDraft(
statement=f.statement,
files=f.files,
subject=f.subject,
details=verbatim_details,
)
for f in fact_drafts
]
fact_source = "llm"
if not fact_drafts:
if self.verbatim_fallback_enabled:
verbatim = self._verbatim_fact(messages)
if verbatim is not None:
fact_drafts.append(verbatim)
fact_source = "verbatim_fallback"
else:
fact_source = "none"
else:
fact_source = "verbatim_fallback_disabled"
logger.info(
f"[coding-extract] produced {len(drafts)} experience draft(s), "
f"{'1 session fact' if fact_drafts else 'no session fact'}"
f"{' (verbatim fallback: LLM returned none)' if fact_source == 'verbatim_fallback' else ''}"
f"{' (verbatim fallback disabled)' if fact_source == 'verbatim_fallback_disabled' else ''}"
f" (workspace={workspace_id!r}, branch={branch!r})"
)
# CODING_EXTRACT:无论产出几条 draft(含 0 条)都落一条,便于排查"没抽到"。
# 双层架构下 parsed 同时记录经验草稿与事实草稿,方便追查两层各自产出。
await _store_coding_log(
self.cache, request_id=request_id, user_id=user_id, agent_id=agent_id,
session_id=session_id or "", step="CODING_EXTRACT", prompt=prompt,
response=resp.content or "",
parsed=json.dumps(
{
"experiences": [d.to_dict() for d in drafts],
"experience_count": len(drafts),
"facts": [f.to_dict() for f in fact_drafts],
"fact_count": len(fact_drafts),
"fact_source": fact_source,
},
ensure_ascii=False, default=str,
),
elapsed_ms=_elapsed, prompt_tokens=resp.prompt_tokens,
completion_tokens=resp.completion_tokens, total_tokens=resp.tokens_used,
)
return drafts, fact_drafts
# ------------------------------------------------------------
# Helpers
# ------------------------------------------------------------
@classmethod
def _verbatim_details(cls, messages: List[ChatMessage]) -> str:
"""整段轨迹的原文,作为 details 的权威来源。
取的是未经 keep_last_k_user_turns 压缩的 messages:details 存在的理由就是
留住摘要会丢掉的可寻址产物(第 N 天第 M 餐这种格子),而压缩正是丢它的那一步。
它不进检索向量(store._upsert_fact_vec 只 embed subject + statement),所以
长度只影响存储,不影响召回质量,唯一的上限是 _MAX_DETAILS_CHARS。
从尾部截断:头部是结构化产物的开头(Day 1、配置首行),信息密度最高。
"""
if not messages:
return ""
body = cls._format_conversation(messages).strip()
if not body:
return ""
if len(body) <= _MAX_DETAILS_CHARS:
return body
return body[:_MAX_DETAILS_CHARS] + "\n…(truncated)"
@classmethod
def _verbatim_fact(
cls, messages: List[ChatMessage]
) -> Optional[WorkingFactDraft]:
"""LLM 没给 fact 时的兜底:把轨迹原文存成一条事实。
只在真的一个字都没有时返回 None(空消息、全空内容)。这是最后一道闸门,
判据必须是"有没有内容",不能是"内容够不够好"——够不够好是上面那次 LLM
调用的判断,它已经判错过了,兜底再复读一遍同样的判断就没有意义。
statement 用于检索,所以取用户说的话(用户的话就是未来查询的措辞,
assistant 的复述和工具输出不是);details 放整段原文,供命中后读取。
subject 留空——主体只能靠语义判断,规则抽不出来,空串会让 reconciler 退回
改动前的纯语义判覆盖,而不是拿一个猜错的锚点去卡。
"""
if not messages:
return None
user_texts: List[str] = []
for m in messages:
if m.role == "user" and not m.is_tool_message():
text = (m.content or "").strip()
if text:
user_texts.append(text)
details = cls._verbatim_details(messages)
if not details:
return None
# 用户原话优先,一句都没有(纯工具回放)就退回整段轨迹的开头
head = "\n".join(user_texts).strip() or details
statement = head[:_VERBATIM_STATEMENT_CHARS]
if len(head) > _VERBATIM_STATEMENT_CHARS:
statement += "…"
return WorkingFactDraft(statement=statement, files=[], subject="", details=details)
@staticmethod
def _format_conversation(messages: List[ChatMessage]) -> str:
"""渲染整段对话给 LLM 读。"""
rows: List[str] = []
for i, m in enumerate(messages):
if m.role == "user" and not m.is_tool_message():
rows.append(f"[{i}] user: {m.content}")
elif m.role == "assistant":
line = f"[{i}] assistant: {m.content}"
if m.tool_calls:
tc_summary = "; ".join(
f"{tc.name}({_compact_args(tc.arguments)})"
for tc in m.tool_calls
)
line += f" [tools: {tc_summary}]"
rows.append(line)
elif m.is_tool_message():
tn = m.tool_name or "?"
rows.append(f"[{i}] tool({tn}): {m.content}")
elif m.role == "system":
rows.append(f"[{i}] system: {m.content}")
else:
rows.append(f"[{i}] {m.role}: {m.content}")
return "\n".join(rows)
@classmethod
def _parse_output(
cls, text: str
) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
"""宽松解析 LLM 输出 JSON,返回 (experiences, facts) 两个原始列表。"""
if not text:
return [], []
s = text.strip()
# 去 markdown fence
if s.startswith("```"):
lines = s.split("\n")
body, in_fence = [], False
for line in lines:
if line.startswith("```"):
in_fence = not in_fence
continue
body.append(line)
s = "\n".join(body).strip() or s
obj = None
# 尝试纯 JSON
try:
obj = json.loads(s)
except Exception:
# 找第一个 {...} 块
start = s.find("{")
end = s.rfind("}")
if start != -1 and end > start:
try:
obj = json.loads(s[start: end + 1])
except Exception:
obj = None
if not isinstance(obj, dict):
logger.warning(
f"[coding-extract] failed to parse output ({len(text or '')} chars)"
)
logger.debug(f"[coding-extract] unparsable output: {text!r}")
return [], []
# "memories" 是双层化之前的 key,老 prompt 缓存 / 旧模型可能还这么回
experiences = cls._as_dict_list(obj.get("experiences"))
if not experiences:
experiences = cls._as_dict_list(obj.get("memories"))
return experiences, cls._as_fact_list(obj)
@classmethod
def _as_fact_list(cls, obj: Dict[str, Any]) -> List[Dict[str, Any]]:
"""取出这一段的唯一事实,返回长度 0 或 1 的列表。
现契约是单个 "fact" 对象。"facts" 数组是一段轨迹多条事实那版的形状,老
模型和缓存住的老 prompt 还会这么回,所以继续认,但只留第一条——多出来的
本来就不该存在,丢掉比让它们各自成为一条会话记录更接近本意。
"""
fact = obj.get("fact")
if isinstance(fact, dict):
return [fact]
legacy = cls._as_dict_list(obj.get("facts"))
if len(legacy) > 1:
logger.warning(
f"[coding-extract] legacy 'facts' array with {len(legacy)} entries; "
f"keeping the first, dropping {len(legacy) - 1}"
)
return legacy[:1]
@staticmethod
def _as_dict_list(value: Any) -> List[Dict[str, Any]]:
if not isinstance(value, list):
return []
return [v for v in value if isinstance(v, dict)]
@staticmethod
def _normalize_draft(
raw: Dict[str, Any],
*,
user_id: str,
agent_id: str,
workspace_id: Optional[str],
branch: Optional[str],
session_id: Optional[str],
files: List[str],
) -> Optional[CodingMemoryDraft]:
"""
把 LLM 输出的单条 memory 字典规范化为 CodingMemoryDraft。
返回 None 表示该条无效(缺 task 或 solution)。
"""
task = (raw.get("task") or "").strip()
solution = (raw.get("solution") or "").strip()
if not task or not solution:
logger.debug(f"[coding-extract] drop draft missing task/solution: {raw}")
return None
# search_keys 规范化
sk_raw = raw.get("search_keys") or []
if not isinstance(sk_raw, list):
sk_raw = []
search_keys = [str(s).strip() for s in sk_raw if str(s).strip()]
# 去重 + 与 task 同名的 key 去掉
seen = set()
deduped = []
for k in search_keys:
if k == task:
continue
if k in seen:
continue
seen.add(k)
deduped.append(k)
search_keys = deduped[:5] # 软上限 5
# confidence 规范化
try:
confidence = float(raw.get("confidence", 0.7))
except Exception:
confidence = 0.7
confidence = max(0.0, min(1.0, confidence))
boundary_envs = (raw.get("boundary_envs") or "").strip()
return CodingMemoryDraft(
task=task,
search_keys=search_keys,
solution=solution,
boundary_envs=boundary_envs,
confidence=confidence,
user_id=user_id,
agent_id=agent_id,
workspace_id=workspace_id,
branch=branch,
session_id=session_id,
files=list(files),
extraction_source="auto_extract",
)
@staticmethod
def _normalize_fact_draft(raw: Dict[str, Any]) -> Optional[WorkingFactDraft]:
"""把 LLM 输出的单条 fact 规范化。返回 None 表示 statement 为空。"""
statement = (raw.get("statement") or "").strip()
if not statement:
logger.debug(f"[coding-extract] drop fact missing statement: {raw}")
return None
files_raw = raw.get("files") or []
if not isinstance(files_raw, list):
files_raw = []
seen, files = set(), []
for f in files_raw:
f = str(f).strip()
if f and f not in seen:
seen.add(f)
files.append(f)
subject = " ".join(str(raw.get("subject") or "").split())
# subject 是硬键而不是散文,一句话说明整段跑偏了,宁可当"没定出主体"处理
# (退回纯语义判覆盖)也不要拿一句话去比对相等。
if len(subject) > _MAX_SUBJECT_CHARS:
logger.debug(
f"[coding-extract] subject too long, treated as absent: {subject!r}"
)
subject = ""
details = str(raw.get("details") or "").strip()
if len(details) > _MAX_DETAILS_CHARS:
# 从尾部截,头部是结构化产物的开头(Day 1、配置首行),信息密度最高
details = details[:_MAX_DETAILS_CHARS] + "\n…(truncated)"
return WorkingFactDraft(
statement=statement, files=files, subject=subject, details=details
)
# ================================================================
# Helpers
# ================================================================
def _compact_args(args: Dict[str, Any], max_chars: int = 600) -> str:
"""单行展示 tool args,并为关键命令参数保留足够证据窗口。
仍设上限,避免整段脚本/大 payload 撑爆 prompt;但 80 字符会在常见 PowerShell
命令的 ``-Depth`` / ``-ErrorAction`` 等参数前截断,与 fact 的证据忠实度契约冲突。
"""
if not args:
return ""
try:
s = json.dumps(args, ensure_ascii=False, separators=(",", ":"))
except Exception:
s = str(args)
if len(s) > max_chars:
s = s[: max_chars - 3] + "..."
return s