Python
# -*- coding: utf-8 -*-
"""
Coding Memory 预处理工具(规则,零 LLM)
- has_any_tool_message : 检测 messages 是否含 tool 消息(O(1) 决定是否进 coding 链)
- strip_tool_messages : 把 tool 消息 + assistant tool_calls 字段 strip 掉,留给 chat 链
- truncate_tool_message : 长 tool_result 头尾保留中段截断(不做 schema 化压缩)
- extract_files : 从 tool_calls.arguments 抽 path / file_path 等常见键
- extract_tool_summary : 写 LLM judge 时给的简化视图
使用方式与 scene 路由见 docs/scene_coding_usage.md。
"""
import re
from typing import Any, Dict, List, Optional, Tuple
from ..pipelines.base import ChatMessage
# ================================================================
# 路径键名(跨 OpenAI / Anthropic / Claude Code 通用)
# ================================================================
PATH_KEYS: Tuple[str, ...] = (
"path", "file_path", "filename", "file", "filepath",
"target_path", "notebook_path", "src_path", "dst_path",
)
# ================================================================
# 检测 / 过滤
# ================================================================
def has_any_tool_message(messages: List[ChatMessage]) -> bool:
"""messages 中是否存在 tool 消息或 assistant 的 tool_calls。"""
return any(m.is_tool_message() or m.has_tool_calls() for m in messages)
def strip_tool_messages(messages: List[ChatMessage]) -> List[ChatMessage]:
"""
给现有 chat 链路用:去掉 role=tool 的消息;
含 tool_calls 的 assistant 消息保留 content(去掉 tool_calls 字段);
若 strip 后 content 为空且无 tool_calls 则丢弃。
"""
out: List[ChatMessage] = []
for m in messages:
if m.is_tool_message():
continue
if m.has_tool_calls():
# 保留 text,丢 tool_calls;content 为空就整条丢弃
if m.content.strip():
out.append(ChatMessage(role=m.role, content=m.content))
# else: 整条丢
continue
out.append(m)
return out
# ================================================================
# tool_result 截断(不做 schema 化压缩)
# ================================================================
DEFAULT_MAX_TOOL_RESULT_BYTES = 2048
DEFAULT_HEAD_BYTES = 1024
DEFAULT_TAIL_BYTES = 512
# 本模块自己产出的省略标记。截断结果会再次经过截断(落库前一次、读历史时又一次),
# 认出自己的标记才能保证幂等:已截断的文本再截一次原样返回,而不是把省略计数改写。
_TOOL_OMIT_MARKER_RE = re.compile(r"\n\n\[\.\.\.\d+ bytes omitted by truncate\.\.\.\]\n\n")
# 标记本身的字节数上限(数字位数有限),用于判断「已截断且只超出一个标记的长度」。
_TOOL_OMIT_MARKER_MAX_BYTES = 128
_ASSISTANT_OMIT_MARKER_RE = re.compile(r" \[\.\.\.\d+ chars omitted\.\.\.\] ")
def truncate_tool_result_text(
text: str,
max_bytes: int = DEFAULT_MAX_TOOL_RESULT_BYTES,
head_bytes: int = DEFAULT_HEAD_BYTES,
tail_bytes: int = DEFAULT_TAIL_BYTES,
) -> str:
"""
长字符串头尾保留中段截断。
跨平台 tool 输出 schema 不统一,规则化压缩("Read 取行数 / Bash 取 exit code")注定失败;
最稳妥做法是按字节截断,把信号交给 LLM 自己消化。
"""
if not isinstance(text, str):
text = "" if text is None else str(text)
raw = text.encode("utf-8")
if len(raw) <= max_bytes:
return text
# 已截断过(max_bytes 很小时标记本身会让结果略超上限):原样返回,保证幂等。
if (
len(raw) <= max_bytes + _TOOL_OMIT_MARKER_MAX_BYTES
and _TOOL_OMIT_MARKER_RE.search(text)
):
return text
# 自定义 max_bytes 可能小于默认 head+tail(1024+512)。按原比例缩放内容窗口,
# 给省略标记预留空间,不能因为窗口和过大而把超限原文直接返回。
marker_budget = min(96, max(24, max_bytes // 4))
content_budget = max(2, max_bytes - marker_budget)
requested = max(1, head_bytes + tail_bytes)
if head_bytes + tail_bytes > content_budget:
head_bytes = max(1, int(content_budget * head_bytes / requested))
tail_bytes = max(1, content_budget - head_bytes)
head = raw[:head_bytes].decode("utf-8", errors="ignore")
tail = raw[-tail_bytes:].decode("utf-8", errors="ignore")
omitted = len(raw) - head_bytes - tail_bytes
return (
head
+ f"\n\n[...{omitted} bytes omitted by truncate...]\n\n"
+ tail
)
def truncate_tool_message(
msg: ChatMessage,
max_bytes: int = DEFAULT_MAX_TOOL_RESULT_BYTES,
) -> ChatMessage:
"""对 role=tool 的消息内容做截断。其它 role 原样返回。"""
if not msg.is_tool_message():
return msg
if len(msg.content.encode("utf-8")) <= max_bytes:
return msg
new_content = truncate_tool_result_text(msg.content, max_bytes=max_bytes)
# 不修改原对象(messages 可能被 caller 复用)
return ChatMessage(
role=msg.role,
content=new_content,
name=msg.name,
tool_calls=list(msg.tool_calls),
tool_call_id=msg.tool_call_id,
tool_name=msg.tool_name,
)
def truncate_messages(
messages: List[ChatMessage],
max_bytes: int = DEFAULT_MAX_TOOL_RESULT_BYTES,
) -> List[ChatMessage]:
"""对整个 messages 列表的所有 tool 消息做截断。"""
return [truncate_tool_message(m, max_bytes=max_bytes) for m in messages]
# ================================================================
# 长会话窗口压缩:last-K user-turn + assistant 头尾截断
# ================================================================
DEFAULT_LAST_K_USER_TURNS = 5
# 原值是 head 200 + tail 200。那是按"assistant 文本是行文、只需还原意图"设的,
# 但 assistant 的最后一段常常**就是交付物本身**(一份行程表、一段配置、一个答案),
# 对它做头尾截断等于把答卷中间撕掉再让人抄。
#
# 阈值取 6000(head+tail 各 3000):大多数正常交付物在此长度内可完整保留;超过阈值
# 的通常是反复试错的长轨迹,**仍然要截**——保留它只会稀释注意力。
DEFAULT_ASSISTANT_HEAD_CHARS = 3000
DEFAULT_ASSISTANT_TAIL_CHARS = 3000
def truncate_assistant_text(
text: str,
head_chars: int = DEFAULT_ASSISTANT_HEAD_CHARS,
tail_chars: int = DEFAULT_ASSISTANT_TAIL_CHARS,
) -> str:
"""
assistant.content 的字符级头尾截断。
跟 tool_result 不同,assistant 文本一般不会"超大",但长 trajectory 累积下来
仍会膨胀 prompt。默认 head 3000 + tail 3000:assistant 的收尾段常常就是交付物
本身,阈值的取法见模块里 DEFAULT_ASSISTANT_HEAD_CHARS 上方的说明。
注意:tool_calls 列表不在此截断;在 _format_conversation 中由 caller 决定渲染策略。
"""
if not isinstance(text, str):
text = "" if text is None else str(text)
if len(text) <= head_chars + tail_chars:
return text
# 已截断过:中段恰好是本函数的省略标记 → 原样返回,保证幂等(否则会把
# 省略计数改写成标记自身的长度)。
if _ASSISTANT_OMIT_MARKER_RE.fullmatch(text[head_chars:len(text) - tail_chars]):
return text
omitted = len(text) - head_chars - tail_chars
return (
text[:head_chars]
+ f" [...{omitted} chars omitted...] "
+ text[-tail_chars:]
)
def truncate_assistant_messages(
messages: List[ChatMessage],
head_chars: int = DEFAULT_ASSISTANT_HEAD_CHARS,
tail_chars: int = DEFAULT_ASSISTANT_TAIL_CHARS,
) -> List[ChatMessage]:
"""截断列表内所有 assistant 文本,但不裁掉任何消息或 user-turn。
``New Messages`` 必须完整覆盖本次 write 传入的所有 turn;last-K 只属于历史
上下文。这个 helper 因此只限制单条 assistant 的体积,不做窗口选择。
"""
out: List[ChatMessage] = []
for m in messages:
if m.role != "assistant" or not m.content:
out.append(m)
continue
new_content = truncate_assistant_text(
m.content,
head_chars=head_chars,
tail_chars=tail_chars,
)
if new_content == m.content:
out.append(m)
continue
out.append(ChatMessage(
role=m.role,
content=new_content,
name=m.name,
tool_calls=list(m.tool_calls),
tool_call_id=m.tool_call_id,
tool_name=m.tool_name,
))
return out
def prepare_extractor_messages(
messages: List[ChatMessage],
*,
tool_max_bytes: int = DEFAULT_MAX_TOOL_RESULT_BYTES,
assistant_head_chars: int = DEFAULT_ASSISTANT_HEAD_CHARS,
assistant_tail_chars: int = DEFAULT_ASSISTANT_TAIL_CHARS,
) -> List[ChatMessage]:
"""限制单条消息体积,同时完整保留输入中的所有 turn。
供 ``New Messages`` 使用。顺序必须是先裁 tool result,再裁 assistant 文本;
两步都不改变消息数量和先后关系。
"""
return truncate_assistant_messages(
truncate_messages(messages, max_bytes=tool_max_bytes),
head_chars=assistant_head_chars,
tail_chars=assistant_tail_chars,
)
def keep_last_k_user_turns(
messages: List[ChatMessage],
k: int = DEFAULT_LAST_K_USER_TURNS,
assistant_head_chars: int = DEFAULT_ASSISTANT_HEAD_CHARS,
assistant_tail_chars: int = DEFAULT_ASSISTANT_TAIL_CHARS,
) -> List[ChatMessage]:
"""
对长 trajectory 压缩为最近 K 个 user-turn 的窗口,并对其中 assistant
消息做头尾截断。
一个 "user-turn" 定义为:一条真实 user 消息(非 tool_result-only)+ 之后
直到下一条真实 user 消息之前的所有 assistant / tool / tool_result 消息。
设计动机:
- extractor 的 conversation_block 现状是整段渲染,长 batch 会让 LLM 注意力稀释、
under-extract
- tool_result 已有字节截断(head 1024 + tail 512),但 assistant 长文本和
消息条数本身没有上限
- 此函数只压缩**消息条数**和 assistant 文本长度;tool_result 由
truncate_messages 处理,不变
Args:
messages: 完整的 ChatMessage 列表(顺序)
k: 保留最近多少个 user-turn(默认 5)
assistant_head_chars / assistant_tail_chars: assistant 文本头尾保留字符数
Returns:
截断后的 messages 列表(保序,含 tool_call_id 等元字段不变)。
如果消息为空或 user-turn 数 ≤ k,原样返回(仍会做 assistant 截断以保持行为一致)。
"""
if not messages:
return messages
# 1) 找到所有真实 user-turn 的起始位置("真实" = role=user 且不是 tool_result-only)
user_turn_starts: List[int] = []
for idx, m in enumerate(messages):
if m.role == "user" and not m.is_tool_message():
user_turn_starts.append(idx)
# 2) 决定窗口起点:保留最后 k 个 user-turn → 取倒数第 k 个起点
if len(user_turn_starts) > k:
window_start = user_turn_starts[-k]
else:
window_start = 0
windowed = messages[window_start:]
# 3) 对 assistant 消息做头尾截断(保留 tool_calls)
out: List[ChatMessage] = []
for m in windowed:
if m.role == "assistant" and m.content:
new_content = truncate_assistant_text(
m.content,
head_chars=assistant_head_chars,
tail_chars=assistant_tail_chars,
)
if new_content == m.content:
out.append(m)
else:
out.append(ChatMessage(
role=m.role,
content=new_content,
name=m.name,
tool_calls=list(m.tool_calls),
tool_call_id=m.tool_call_id,
tool_name=m.tool_name,
))
else:
out.append(m)
return out
# ================================================================
# 文件路径抽取
# ================================================================
def extract_files(messages: List[ChatMessage]) -> List[str]:
"""
从 messages 中所有 tool_calls.arguments 抽 path / file_path / filename 等常见键。
返回去重后排序的 path 列表。跨 OpenAI / Anthropic / Claude Code 都稳定有效,
属于 tool 信号里少数能规则化处理的部分。
"""
paths: set = set()
for m in messages:
for tc in m.tool_calls:
if not isinstance(tc.arguments, dict):
continue
for k in PATH_KEYS:
v = tc.arguments.get(k)
if isinstance(v, str) and v:
paths.add(v)
return sorted(paths)
# ================================================================
# 写入 / search 端 LLM 输入的简化视图
# ================================================================
def extract_tool_summary(messages: List[ChatMessage]) -> List[Dict[str, Any]]:
"""
给 LLM judge / extractor 的 turn 级简化视图。
每个 turn = 一个 user 消息 + 之后到下一个 user 之前所有 assistant/tool 消息的 tool_names 集合。
chat 路径不会调用此函数(无 tool 消息直接走旧链)。
返回:
[
{"turn": 0, "user": "...", "tools": ["Read", "Edit"], "has_tool_result": True},
...
]
"""
out: List[Dict[str, Any]] = []
cur: Optional[Dict[str, Any]] = None
def _flush():
if cur is not None:
# 去重保序
seen = set()
cur["tools"] = [t for t in cur["tools"] if not (t in seen or seen.add(t))]
out.append(cur)
for m in messages:
if m.role == "user" and not m.is_tool_message():
_flush()
cur = {
"turn": len(out),
"user": (m.content or "").strip(),
"tools": [],
"has_tool_result": False,
}
else:
if cur is None:
# 没有 user 起头时(可能是历史 assistant),开一个匿名 turn
cur = {"turn": len(out), "user": "", "tools": [], "has_tool_result": False}
if m.has_tool_calls():
for tc in m.tool_calls:
if tc.name:
cur["tools"].append(tc.name)
if m.is_tool_message():
cur["has_tool_result"] = True
if m.tool_name:
cur["tools"].append(m.tool_name)
_flush()
return out