All your AI agent sessions in one place — browse, search, resume. Rust + GPUI.
Rust
use crate::models::*;
use base64::engine::general_purpose::{STANDARD as BASE64, URL_SAFE as BASE64_URL_SAFE};
use base64::Engine as _;
use serde_json::Value;
use std::cell::Cell;
const MAX_TRANSCRIPT_IMAGE_BYTES: usize = 64 * 1024 * 1024;
thread_local! {
static IMAGE_DECODE_REMAINING: Cell<Option<usize>> = const { Cell::new(None) };
}
/// 一次会话解析的图片压缩字节总预算。嵌套调用复用外层预算,离开解析作用域后恢复。
pub struct ImageDecodeBudgetGuard {
previous: Option<usize>,
changed: bool,
}
pub fn transcript_image_decode_budget(decode_images: bool) -> ImageDecodeBudgetGuard {
image_decode_budget(decode_images.then_some(MAX_TRANSCRIPT_IMAGE_BYTES))
}
fn image_decode_budget(limit: Option<usize>) -> ImageDecodeBudgetGuard {
IMAGE_DECODE_REMAINING.with(|remaining| {
let previous = remaining.get();
let changed = previous.is_none() && limit.is_some();
if changed {
remaining.set(limit);
}
ImageDecodeBudgetGuard { previous, changed }
})
}
impl Drop for ImageDecodeBudgetGuard {
fn drop(&mut self) {
if self.changed {
IMAGE_DECODE_REMAINING.with(|remaining| remaining.set(self.previous));
}
}
}
/// 预算还放不放得下 `bytes`(只看不扣):读文件之前先问,放不下的连读都不读
fn image_decode_budget_allows(bytes: usize) -> bool {
IMAGE_DECODE_REMAINING.with(|remaining| remaining.get().is_none_or(|left| bytes <= left))
}
fn consume_image_decode_budget(bytes: usize) -> bool {
IMAGE_DECODE_REMAINING.with(|remaining| match remaining.get() {
Some(left) if bytes <= left => {
remaining.set(Some(left - bytes));
true
}
Some(_) => false,
None => true,
})
}
/// JSONL 逐行解成 JSON:空行跳过,读不出(坏 UTF-8)或不是 JSON 的行交成 `Ok(None)`,调用方计
/// 未知行。读错误交一次 `Err` 就结束,调用方 `?` 出去让这次解析失败:`BufRead::lines` 遇到读
/// 错误会一直交回同一个错误(EIO、断开的网络盘、Windows 上被别的进程锁住的文件),`continue`
/// 接着读就是死循环——扫描线程卡在 SCAN_GATE 里,刷新弹窗永远关不掉;当成读完了,半截转录就
/// 带着整个文件的 mtime / size 入库,文件不再变就永远停在半截。解析失败则库里的旧行原样留着、
/// 下一轮再试
pub fn jsonl_values<R: std::io::BufRead>(
reader: R,
) -> impl Iterator<Item = std::io::Result<Option<Value>>> {
jsonl_rows(reader)
}
/// `jsonl_values` 的窄版:每行只反序列化成 `T`(用不到的字段直接跳过,不建整棵 Value 树),
/// 读错误规则相同;读不出、不是 JSON、对不上形状的行交 `Ok(None)`
pub fn jsonl_rows<T: serde::de::DeserializeOwned, R: std::io::BufRead>(
reader: R,
) -> impl Iterator<Item = std::io::Result<Option<T>>> {
jsonl_lines(reader).filter_map(|line| match line {
Ok(Some(line)) if line.trim().is_empty() => None,
Ok(line) => Some(Ok(line.and_then(|line| serde_json::from_str(&line).ok()))),
Err(e) => Some(Err(e)),
})
}
/// `BufRead::lines` 加上上面那条读错误规则:坏 UTF-8 的行字节已经读过,交成 `Ok(None)` 接着读
fn jsonl_lines<R: std::io::BufRead>(reader: R) -> JsonlLines<R> {
JsonlLines {
lines: reader.lines(),
done: false,
}
}
struct JsonlLines<R> {
lines: std::io::Lines<R>,
done: bool,
}
impl<R: std::io::BufRead> Iterator for JsonlLines<R> {
type Item = std::io::Result<Option<String>>;
fn next(&mut self) -> Option<Self::Item> {
if self.done {
return None;
}
match self.lines.next()? {
Ok(line) => Some(Ok(Some(line))),
Err(e) if e.kind() == std::io::ErrorKind::InvalidData => Some(Ok(None)),
Err(e) => {
self.done = true;
Some(Err(e))
}
}
}
}
/// 文件 mtime → epoch ms(各家 adapter 与 watcher 共用)
pub fn mtime_ms(meta: &std::fs::Metadata) -> i64 {
meta.modified().ok().and_then(system_time_ms).unwrap_or(0)
}
/// 文件创建时间 → epoch ms;平台或文件系统不记的给 None
pub fn created_ms(meta: &std::fs::Metadata) -> Option<i64> {
meta.created().ok().and_then(system_time_ms)
}
/// 文件的 (mtime 毫秒, 字节数),跟随符号链接;不是普通文件、读不到元数据给 None
pub fn stat_stamp(path: &std::path::Path) -> Option<(i64, i64)> {
let meta = std::fs::metadata(path).ok()?;
meta.is_file().then(|| (mtime_ms(&meta), meta.len() as i64))
}
fn system_time_ms(t: std::time::SystemTime) -> Option<i64> {
t.duration_since(std::time::UNIX_EPOCH)
.ok()
.map(|d| d.as_millis() as i64)
}
/// 路径末段,`/` 与 `\` 都算分隔符:别的机器写下的路径(Codex 的 state DB 可能是 Windows 机器写的、
/// Grok Bot 的附件在云端电脑上),不能交给本机的 `Path`
pub fn path_tail(path: &str) -> &str {
path.rsplit(['/', '\\']).next().unwrap_or(path)
}
/// 并进 `SessionFileRef.size` 的边车指纹:展示要用的那几个字段的稳定哈希(FNV-1a,段与段之间隔一个
/// 0 字节),取高 32 位——FNV 的低位只由各字节的低位决定,原先按 1024 取模,"Oscar" 与 "Ada 4" 就
/// 撞在一起,改了名也认不出(2026-10-11 Codex review)。size 因此不再是字节数,没有谁拿会话的
/// size 当字节数用(界面、MCP、导出、Clean Up 都现 stat 文件)。按长度求和的话同长的改名认不
/// 出来(Antigravity 与 Kilo 旧版任务还在求和,换过来会让它们的会话各重解析一次)
pub fn sidecar_fingerprint(parts: &[&str]) -> i64 {
let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
for part in parts {
for byte in part.bytes().chain(std::iter::once(0)) {
hash ^= u64::from(byte);
hash = hash.wrapping_mul(0x0100_0000_01b3);
}
}
(hash >> 32) as i64
}
/// cwd → 项目显示名(路径末段;空/异常 = "Unknown project")
pub fn project_name_of(cwd: &str) -> String {
if cwd.is_empty() {
return "Unknown project".to_string();
}
std::path::Path::new(cwd)
.file_name()
.map(|s| s.to_string_lossy().to_string())
.unwrap_or_else(|| "Unknown project".to_string())
}
/// 项目路径的规范形。Windows 形状的路径(`c:\…`、`C:/…`、`//server/…`)盘符改大写,
/// 在 Windows 上斜杠换成反斜杠:VS Code 的 fsPath 写小写盘符,OpenCode 系把目录存成
/// 正斜杠(它自己读出来时再换回),原样用就与别家记下的 `C:\…` 分成两个项目。
/// POSIX 路径(含远程镜像来的)原样
pub fn canonical_project_path(path: &str) -> String {
let drive = matches!(path.as_bytes(), [d, b':', b'\\' | b'/', ..] if d.is_ascii_alphabetic());
if !drive && !path.starts_with("//") {
return path.to_string();
}
let mut out = if cfg!(windows) {
path.replace('/', "\\")
} else {
path.to_string()
};
if drive {
out[..1].make_ascii_uppercase();
}
out
}
/// user 消息的 kind:注入内容归 Meta 折叠
pub fn user_kind(text: &str) -> MessageKind {
if is_injected_user_content(text) {
MessageKind::Meta
} else {
MessageKind::Text
}
}
/// 纯文本消息构造(clip + user 注入判定),多家 adapter 共用
pub fn text_msg(role: Role, text: &str, ts: i64) -> TranscriptMessage {
let (clipped, truncated) = clip(text.trim(), MAX_MSG_TEXT);
let kind = if role == Role::User {
user_kind(text)
} else {
MessageKind::Text
};
TranscriptMessage {
seq: 0,
role,
kind,
text: clipped,
truncated,
tool_calls: Vec::new(),
thinking: None,
timestamp: if ts > 0 { Some(ts) } else { None },
model: None,
images: Vec::new(),
}
}
/// 给模型看、不是对话的上下文(系统提示、状态说明等):System 角色的 Meta 消息——
/// 不进 FTS、不算 message_count、不参与标题推导
pub fn meta_msg(text: &str, ts: i64) -> TranscriptMessage {
let mut m = text_msg(Role::System, text, ts);
m.kind = MessageKind::Meta;
m
}
/// seq 回填——FTS seq 与详情页序号一致(跨文件不变量 1)的统一执行点,
/// 必须在消息序列定型后、入库/返回前调用
pub fn assign_seq(messages: &mut [TranscriptMessage]) {
for (i, m) in messages.iter_mut().enumerate() {
m.seq = i as i64;
}
}
/// 标题推导:首条真实用户消息经清洗,各家共用的回退链
pub fn title_from_messages(messages: &[TranscriptMessage]) -> Option<String> {
messages
.iter()
.filter(|m| m.role == Role::User && m.kind == MessageKind::Text)
.map(|m| clean_title_candidate(&m.text))
.find(|title| !title.is_empty())
}
/// 会话标题:存着的名字为准,没有就退回首条提问;`placeholder` 时反过来——存着的只是占位
/// (ZCode 的 default、MiMo Code 的 fallback),有提问就用提问。都没有给 UNTITLED
pub fn session_title(stored: &str, placeholder: bool, messages: &[TranscriptMessage]) -> String {
let stored = Some(clean_title_candidate(stored)).filter(|t| !t.is_empty());
let asked = || title_from_messages(messages);
if placeholder {
asked().or(stored)
} else {
stored.or_else(asked)
}
.unwrap_or_else(|| UNTITLED.to_string())
}
/// 折掉的一段留下的那条标记:"── N messages <来由> ──",System 角色的 Meta
pub fn collapsed_marker(count: usize, origin: &str, ts: i64) -> TranscriptMessage {
meta_msg(
&format!(
"── {count} message{} {origin} ──",
crate::text::plural(count as i64)
),
ts,
)
}
/// 会话开头从父会话原样复制来的那段(Codex `spawn_agent` 的 fork_turns、Craft Agents
/// 的分支)折成一条 Meta 标记。原样入库就是:子会话偷走父会话的标题、父会话的每一句
/// 在 FTS 里出现两次、Insights 的 prompt 数翻倍。Meta 不进 FTS、不算 message_count、
/// 不参与标题推导,GUI / 导出 / MCP 也都跳过它——留一条而不是整段删掉,是为了"这里
/// 原本有东西"不至于无声消失;内容本体就在父会话里。`parent` 是标记里父会话的叫法
/// (Codex 说 thread)
pub fn collapse_inherited(messages: &mut Vec<TranscriptMessage>, cut: usize, parent: &str) {
if cut == 0 {
return;
}
let inherited = &messages[..cut];
let turns = inherited
.iter()
.filter(|m| m.kind == MessageKind::Text)
.count();
let ts = inherited
.iter()
.find_map(|m| m.timestamp)
.unwrap_or_default();
let marker = collapsed_marker(turns, &format!("inherited from the parent {parent}"), ts);
messages.splice(..cut, std::iter::once(marker));
}
// ---- Claude 式会话目录里的子代理(Claude Code、CodeBuddy / WorkBuddy、Qoder 同构) ----
/// 会话的同名目录(`<projects>/<slug>/<id>/`,子代理转录等边车在里面)
pub fn session_dir(r: &SessionFileRef) -> std::path::PathBuf {
std::path::Path::new(&r.file_path)
.parent()
.unwrap_or(std::path::Path::new("."))
.join(&r.native_id)
}
/// 子代理转录所在会话的目录(目录名就是派它的会话的 id):Task / Agent 派的在
/// `<会话>/subagents/agent-<id>.jsonl`,Workflow 跑出来的再深一层 `subagents/workflows/wf_<id>/`;
/// 同一目录里的 journal.jsonl 是 Workflow 的运行日志,不是转录。这些转录作为子会话入库,但不是
/// 能单独恢复的会话
pub fn subagent_session_dir(path: &std::path::Path) -> Option<&std::path::Path> {
let name = path.file_name()?.to_str()?;
if !(name.starts_with("agent-") && name.ends_with(".jsonl")) {
return None;
}
let named = |dir: &std::path::Path, name: &str| dir.file_name().is_some_and(|n| n == name);
let dir = path.parent()?;
let subagents = if named(dir, "subagents") {
dir
} else {
let run = dir.file_name()?.to_str()?;
let workflows = dir.parent()?;
let subagents = workflows.parent()?;
(run.starts_with("wf_") && named(workflows, "workflows") && named(subagents, "subagents"))
.then_some(subagents)?
};
subagents.parent()
}
pub fn is_subagent_transcript(path: &str) -> bool {
subagent_session_dir(std::path::Path::new(path)).is_some()
}
/// 子代理转录所在会话的原生 id(`AgentAdapter::parent_in_path`)
pub fn subagent_parent(path: &std::path::Path) -> Option<String> {
Some(
subagent_session_dir(path)?
.file_name()?
.to_string_lossy()
.into_owned(),
)
}
/// 一个会话目录里全部子代理转录(Task / Agent 派的与 Workflow 跑出来的),读不出的目录跳过
pub fn subagent_transcripts(session_dir: &std::path::Path) -> Vec<std::path::PathBuf> {
let files = |dir: &std::path::Path| -> Vec<std::path::PathBuf> {
std::fs::read_dir(dir)
.map(|entries| entries.flatten().map(|entry| entry.path()).collect())
.unwrap_or_default()
};
let mut transcripts = Vec::new();
for path in files(&session_dir.join("subagents")) {
if path.file_name().is_some_and(|name| name == "workflows") {
transcripts.extend(files(&path).iter().flat_map(|run| files(run)));
} else {
transcripts.push(path);
}
}
transcripts.retain(|path| subagent_session_dir(path).is_some());
transcripts
}
/// 一个会话目录里全部子代理转录的引用
pub fn subagent_refs(agent: AgentId, session_dir: &std::path::Path) -> Vec<SessionFileRef> {
subagent_transcripts(session_dir)
.iter()
.filter_map(|path| subagent_ref(agent, path))
.collect()
}
/// 监听事件落在子代理转录或它的边车上:换成转录的引用。`session_ok` 判它所在的会话目录是不是这个
/// 实例认的那一层(各家的数据根与目录深度不同)
pub fn subagent_event_ref(
agent: AgentId,
path: &std::path::Path,
session_ok: impl FnOnce(&std::path::Path) -> bool,
) -> Option<SessionFileRef> {
let transcript = match path.file_name()?.to_str()?.strip_suffix(".meta.json") {
Some(stem) => path.with_file_name(format!("{stem}.jsonl")),
None => path.to_path_buf(),
};
if !session_ok(subagent_session_dir(&transcript)?) {
return None;
}
subagent_ref(agent, &transcript)
}
/// 子代理转录的边车 `agent-<id>.meta.json`:agentType / 任务说明 / 派它的 tool_use id
fn subagent_sidecar(transcript: &std::path::Path) -> std::path::PathBuf {
transcript.with_extension("meta.json")
}
/// 子代理转录的引用,边车并进戳(列表与监听同一个)
fn subagent_ref(agent: AgentId, transcript: &std::path::Path) -> Option<SessionFileRef> {
let mut r = default_file_ref(agent, transcript)?;
if let Some((mtime, size)) = stat_stamp(&subagent_sidecar(transcript)) {
r.mtime_ms = r.mtime_ms.max(mtime);
r.size += size;
}
Some(r)
}
/// 一份子代理转录读成 `SidechainInfo`:边车给是谁、干什么、哪次调用派的(没有边车的家这几项为空);
/// 它同时作为子会话入库,`session_id` 就是文件名
pub fn sidechain_info(transcript: &std::path::Path) -> Option<SidechainInfo> {
let id = transcript.file_stem()?.to_string_lossy().to_string();
let sidecar = std::fs::read_to_string(subagent_sidecar(transcript))
.ok()
.and_then(|raw| serde_json::from_str::<Value>(&raw).ok());
let field = |key: &str| {
sidecar
.as_ref()
.and_then(|v| text_at(v, key))
.map(String::from)
};
Some(SidechainInfo {
session_id: Some(id.clone()),
agent_type: field("agentType"),
description: field("description"),
tool_use_id: field("toolUseId"),
id,
})
}
/// 会话直属的子代理(`<会话>/subagents/` 那一层;MCP 的 `subagent` 参数与导出按它读),派活的
/// 调用按边车记的 tool_use id 指向子会话。子代理自己下面没有这一层目录,给空
pub fn link_subagents(
session_dir: &std::path::Path,
mainline: &mut [TranscriptMessage],
) -> Vec<SidechainInfo> {
let Ok(entries) = std::fs::read_dir(session_dir.join("subagents")) else {
return Vec::new();
};
let sidechains: Vec<SidechainInfo> = entries
.flatten()
.map(|entry| entry.path())
.filter(|path| subagent_session_dir(path).is_some())
.filter_map(|path| sidechain_info(&path))
.collect();
let by_call: std::collections::HashMap<&str, &SidechainInfo> = sidechains
.iter()
.filter_map(|s| s.tool_use_id.as_deref().map(|id| (id, s)))
.collect();
for call in mainline.iter_mut().flat_map(|m| m.tool_calls.iter_mut()) {
if let Some(sidechain) = by_call.get(call.id.as_str()) {
call.child_id = sidechain.session_id.clone();
}
}
sidechains
}
/// Claude 式布局的会话转录:会话里派活的调用指向它派出去的子会话(`link_subagents`)
pub fn transcript_with_subagents(
r: &SessionFileRef,
meta: SessionMeta,
mut mainline: Vec<TranscriptMessage>,
unknown_line_count: u32,
) -> ParsedTranscript {
let sidechains = link_subagents(&session_dir(r), &mut mainline);
ParsedTranscript {
meta,
mainline,
sidechains,
unknown_line_count,
}
}
/// 按 id 读会话直属的一份子代理转录(`AgentAdapter::load_sidechain`,MCP 的 `subagent` 参数);
/// 没有这份给空
pub fn load_subagent(
r: &SessionFileRef,
id: &str,
parse: impl FnOnce(&std::path::Path) -> anyhow::Result<Vec<TranscriptMessage>>,
) -> anyhow::Result<Vec<TranscriptMessage>> {
let file = session_dir(r).join("subagents").join(format!("{id}.jsonl"));
if !file.is_file() {
return Ok(Vec::new());
}
parse(&file)
}
/// 子代理转录作为子会话:是 agent 派出去的(Insights 不算),标题取边车记的任务说明——没有就照常
/// (多半是派活那句话)。不是子代理转录的不动
pub fn mark_subagent(meta: &mut SessionMeta, transcript: &std::path::Path) {
if subagent_session_dir(transcript).is_none() {
return;
}
meta.spawned = true;
if let Some(task) = sidechain_info(transcript)
.and_then(|info| info.description)
.map(|task| clean_title_candidate(&task))
.filter(|task| !task.is_empty())
{
meta.title = task;
}
}
/// 子代理自己的文件:转录与它的边车(删除时一起走)
pub fn subagent_paths(transcript: &str) -> Vec<String> {
let sidecar = subagent_sidecar(std::path::Path::new(transcript));
let mut paths = vec![transcript.to_string()];
if sidecar.is_file() {
paths.push(sidecar.to_string_lossy().to_string());
}
paths
}
/// `AgentAdapter::file_ref` 的默认实现:非空 .jsonl,stem 即 native_id。
/// 覆写方可在此结果上做路径过滤或 native_id 改写。
pub fn default_file_ref(agent: AgentId, path: &std::path::Path) -> Option<SessionFileRef> {
let name = path.file_name()?.to_string_lossy().to_string();
if name.starts_with('.') {
return None;
}
let stem = name.strip_suffix(".jsonl")?;
let meta = std::fs::metadata(path).ok()?;
if !meta.is_file() || meta.len() == 0 {
return None;
}
Some(SessionFileRef {
agent,
native_id: stem.to_string(),
file_path: path.to_string_lossy().to_string(),
mtime_ms: mtime_ms(&meta),
size: meta.len() as i64,
})
}
/// Claude 式 projects 树(Qoder / CodeBuddy / WorkBuddy)的会话枚举:根直属的
/// `<session>.jsonl` 与下一层 `<slug>/<session>.jsonl` 都收——自定义 location
/// 允许直接选中某个 slug 目录;会话同名目录里派出去的子代理(`<session>/subagents/`)
/// 作为子会话一并收,别的边车不收(递归的 list_jsonl_refs 会把它们吞进来)。按路径排序
pub fn list_project_tree_refs(root: &std::path::Path, agent: AgentId) -> Vec<SessionFileRef> {
let mut refs = Vec::new();
let Ok(entries) = std::fs::read_dir(root) else {
return refs;
};
let is_dir = |entry: &std::fs::DirEntry| entry.file_type().is_ok_and(|t| t.is_dir());
for entry in entries.flatten() {
let path = entry.path();
if is_dir(&entry) {
// slug 目录(里面是会话),或者根本身就是 slug 目录时的会话同名目录
refs.extend(subagent_refs(agent, &path));
let Ok(inner) = std::fs::read_dir(&path) else {
continue;
};
for e in inner.flatten() {
if is_dir(&e) {
refs.extend(subagent_refs(agent, &e.path()));
} else if let Some(r) = default_file_ref(agent, &e.path()) {
refs.push(r);
}
}
} else if let Some(r) = default_file_ref(agent, &path) {
refs.push(r);
}
}
refs.sort_by(|a, b| a.file_path.cmp(&b.file_path));
refs
}
/// Claude 式 projects 树里监听事件对应的会话(Qoder / CodeBuddy / WorkBuddy):根下一两层的
/// `<session>.jsonl`,或会话同名目录里的子代理转录(边车的事件换成转录的引用)。更深的
/// 别的边车(state、memory)都不是
pub fn project_tree_file_ref(
root: &std::path::Path,
agent: AgentId,
path: &std::path::Path,
) -> Option<SessionFileRef> {
let relative = path.strip_prefix(root).ok()?;
if relative.components().count() <= 2 {
return default_file_ref(agent, path);
}
// 会话同名目录在根下一两层(根是 projects 目录或某个 slug 目录)
subagent_event_ref(agent, path, |session| {
session
.strip_prefix(root)
.is_ok_and(|session| session.components().count() <= 2)
})
}
/// 上面那棵树里有没有任何会话文件:env 候选根只在探到真实数据时才采信
/// (存在但空的候选不能遮掉默认根)。见首个就停,不做完整枚举——它跑在
/// adapter 构造时、也就是应用启动路径上
pub fn project_tree_has_session(root: &std::path::Path, agent: AgentId) -> bool {
let Ok(entries) = std::fs::read_dir(root) else {
return false;
};
entries.flatten().any(|entry| {
let path = entry.path();
if entry.file_type().is_ok_and(|t| t.is_dir()) {
std::fs::read_dir(&path).is_ok_and(|inner| {
inner
.flatten()
.any(|e| default_file_ref(agent, &e.path()).is_some())
})
} else {
default_file_ref(agent, &path).is_some()
}
})
}
/// `optional_string` 的借用版:`key` 上修剪过、非空的字符串
pub fn text_at<'a>(v: &'a Value, key: &str) -> Option<&'a str> {
v.get(key)
.and_then(Value::as_str)
.map(str::trim)
.filter(|s| !s.is_empty())
}
/// `key` 上是 `true`(缺席、别的类型都算不是)
pub fn true_at(v: &Value, key: &str) -> bool {
v.get(key).and_then(Value::as_bool) == Some(true)
}
/// JSON 里"有就是非空字符串、否则没有"的字段:标题、模型名、cwd 一类
pub fn optional_string(v: Option<&Value>) -> Option<String> {
v.and_then(Value::as_str)
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_string)
}
/// usage 对象 → 本次调用的 token 数:`total_tokens` 优先;否则 Anthropic 形
/// input / output / cache 四项之和;再否则 OpenAI completions 形 prompt +
/// completion(Qoder 与 CodeBuddy 的 rawUsage 共用)
pub fn usage_tokens(usage: &Value) -> i64 {
let total = usage
.get("total_tokens")
.and_then(Value::as_i64)
.unwrap_or(0);
if total > 0 {
return total;
}
let message_tokens: i64 = [
"input_tokens",
"output_tokens",
"cache_creation_input_tokens",
"cache_read_input_tokens",
]
.iter()
.map(|key| usage.get(*key).and_then(Value::as_i64).unwrap_or(0))
.sum();
if message_tokens > 0 {
return message_tokens;
}
["prompt_tokens", "completion_tokens"]
.iter()
.map(|key| usage.get(*key).and_then(Value::as_i64).unwrap_or(0))
.sum()
}
/// 递归枚举 `dir` 下的 `*.jsonl` 普通文件。file_type 来自 readdir、不额外
/// stat;根不存在或不是目录给空迭代(各家 list_session_files 对缺根自行降级,
/// 不变量 8①)。想在文件边界再加判据的家(codex)拿它喂自己的 `file_ref` 漏斗
pub fn jsonl_entries(dir: &std::path::Path) -> impl Iterator<Item = walkdir::DirEntry> {
walkdir::WalkDir::new(dir)
.min_depth(1)
.into_iter()
.flatten()
.filter(|entry| {
entry.file_type().is_file() && entry.file_name().to_string_lossy().ends_with(".jsonl")
})
}
/// 递归枚举目录下非空 .jsonl 为 SessionFileRef;`native_id` 从文件 stem 提取
/// 会话 id(多数家恒等,codex 需剥 rollout 前缀)
pub fn list_jsonl_refs(
dir: &std::path::Path,
agent: AgentId,
native_id: impl Fn(&str) -> String,
) -> Vec<SessionFileRef> {
let mut refs = Vec::new();
for entry in jsonl_entries(dir) {
let name = entry.file_name().to_string_lossy();
let Some(stem) = name.strip_suffix(".jsonl") else {
continue;
};
let Ok(meta) = entry.metadata() else { continue };
if meta.len() == 0 {
continue;
}
refs.push(SessionFileRef {
agent,
native_id: native_id(stem),
file_path: entry.path().to_string_lossy().to_string(),
mtime_ms: mtime_ms(&meta),
size: meta.len() as i64,
});
}
refs
}
/// content blocks → 文本和图片。支持各家目前出现的 Anthropic、OpenAI、
/// Gemini、Pi/Kiro 与 OpenCode 形状;未知、远程、本地路径或过大的图片退回占位符。
#[derive(Debug, Default)]
pub struct ParsedContent {
pub text: String,
pub images: Vec<ImageAttachment>,
}
impl ParsedContent {
/// 追加一个正文块,并保持已经记录的图片偏移不变。
pub fn push_text(&mut self, value: &str) {
self.push_text_with_separator(value, "\n\n");
}
pub fn push_text_with_separator(&mut self, value: &str, separator: &str) {
let value = value.trim();
if value.is_empty() {
return;
}
if !self.text.is_empty() {
self.text.push_str(separator);
}
self.text.push_str(value);
}
/// 追加另一段已解析内容;图片偏移随正文基址一起平移。
pub fn append(&mut self, other: Self) {
self.append_with_separator(other, "\n\n");
}
pub fn append_with_separator(&mut self, mut other: Self, separator: &str) {
let had_text = !self.text.is_empty();
let has_other_text = !other.text.is_empty();
let base = self.text.len();
let separator_len = if had_text && has_other_text {
separator.len()
} else {
0
};
for image in &mut other.images {
image.text_offset += base
+ if image.text_offset > 0 {
separator_len
} else {
0
};
}
if has_other_text {
if separator_len > 0 {
self.text.push_str(separator);
}
self.text.push_str(&other.text);
}
self.images.extend(other.images);
}
fn push_image(&mut self, mut image: ImageAttachment) {
image.text_offset = self.text.len();
self.images.push(image);
}
}
/// 把新内容并入已存在的消息,并同步平移图片的正文偏移。
fn append_content_to_message(message: &mut TranscriptMessage, content: ParsedContent) {
let mut combined = ParsedContent {
text: std::mem::take(&mut message.text),
images: std::mem::take(&mut message.images),
};
combined.append_with_separator(content, "\n\n");
message.text = combined.text;
message.images = combined.images;
}
/// 一次模型调用的产出并进最后一条助手消息(最后一条不是助手就先开一条空的),返回它的下标
/// (登记工具调用用)。整个 agentic 回合并成一条,单行 `text_msg` 的 clip 靠不住:正文合并后
/// 统一压 MAX_MSG_TEXT(截过之后只收图片),thinking 压 MAX_TOOL_IO、截过就不再拼接——反复
/// 对已带截断标记的串再 clip,标记前会一次次多出换行。截过的串连标记一起必然长过上限,所以
/// 守卫是 `<=`:恰好停在上限上的还要再收一次,不然后面的正文悄悄丢掉、连标记都没有。
/// 最后一条还没有时间时用这一次的
pub fn merge_into_last_assistant(
messages: &mut Vec<TranscriptMessage>,
ts: i64,
content: ParsedContent,
thinking: &str,
) -> usize {
if !matches!(messages.last(), Some(m) if m.role == Role::Assistant) {
messages.push(text_msg(Role::Assistant, "", ts));
}
let ix = messages.len() - 1;
let last = &mut messages[ix];
if last.timestamp.is_none() && ts > 0 {
last.timestamp = Some(ts);
}
if !content.text.is_empty() || !content.images.is_empty() {
if last.text.len() <= MAX_MSG_TEXT {
append_content_to_message(last, content);
if last.text.len() > MAX_MSG_TEXT {
last.text = clip(&last.text, MAX_MSG_TEXT).0;
last.truncated = true;
}
} else {
append_images_to_message_end(last, content.images);
}
}
let thinking = thinking.trim();
if !thinking.is_empty() && last.thinking.as_deref().map_or(0, str::len) <= MAX_TOOL_IO {
match &mut last.thinking {
Some(t) => {
t.push_str("\n\n");
t.push_str(thinking);
if t.len() > MAX_TOOL_IO {
*t = clip(t, MAX_TOOL_IO).0;
}
}
slot => *slot = Some(clip(thinking, MAX_TOOL_IO).0),
}
}
ix
}
/// 工具结果不属于消息正文流;其图片统一放到现有正文末尾。
pub fn append_images_to_message_end(
message: &mut TranscriptMessage,
mut images: Vec<ImageAttachment>,
) {
for image in &mut images {
image.text_offset = message.text.len();
}
message.images.extend(images);
}
pub fn content_parts(v: &Value, decode_images: bool) -> ParsedContent {
let mut parsed = ParsedContent::default();
collect_content(v, decode_images, 0, &mut parsed);
parsed
}
fn collect_content(v: &Value, decode_images: bool, depth: usize, parsed: &mut ParsedContent) {
if depth > 4 {
return;
}
match v {
Value::String(value) => {
parsed.push_text(value);
}
Value::Array(parts) => {
for part in parts {
collect_content(part, decode_images, depth + 1, parsed);
}
}
Value::Object(_) => {
if is_image_part(v) {
if decode_images {
if let Some(image) = decode_image_part(v, depth) {
parsed.push_image(image);
return;
}
}
parsed.push_text(IMAGE_PLACEHOLDER);
return;
}
let kind = part_kind(v);
if matches!(kind.as_deref(), Some("text" | "input_text" | "output_text")) {
if let Some(value) = v
.get("text")
.or_else(|| v.get("data"))
.and_then(Value::as_str)
{
parsed.push_text(value);
}
return;
}
// Gemini 的普通 part 没有 type;Grok 的 content wrapper 则需要
// 再下钻一层。reasoning/tool 块由各 adapter 自己分桶,不在这里混入正文。
if kind.is_none() {
if let Some(value) = v.get("text").and_then(Value::as_str) {
parsed.push_text(value);
return;
}
if let Some(inner) = v.get("content") {
collect_content(inner, decode_images, depth + 1, parsed);
return;
}
}
if matches!(kind.as_deref(), Some("content" | "part")) {
if let Some(inner) = v.get("content").or_else(|| v.get("data")) {
collect_content(inner, decode_images, depth + 1, parsed);
}
}
}
_ => {}
}
}
/// 工具结果与普通消息块的区别是:未知对象在旧解析器里会以 JSON 原文显示。
/// 图片仍走统一解码,无法识别的非图片对象则保留这个兼容行为。
pub fn tool_result_parts(v: &Value, decode_images: bool) -> ParsedContent {
let values = v
.as_array()
.map(Vec::as_slice)
.unwrap_or_else(|| std::slice::from_ref(v));
let mut result = ParsedContent::default();
for value in values {
let parsed = content_parts(value, decode_images);
if !parsed.text.is_empty() {
result.append_with_separator(parsed, "\n");
} else if parsed.images.is_empty() && !value.is_null() {
if let Ok(json) = serde_json::to_string(value) {
result.push_text_with_separator(&json, "\n");
}
} else {
result.append_with_separator(parsed, "\n");
}
}
result
}
fn part_kind(v: &Value) -> Option<String> {
v.get("type")
.or_else(|| v.get("kind"))
.and_then(Value::as_str)
.map(|value| value.to_ascii_lowercase().replace('-', "_"))
}
fn image_media_type(v: &Value) -> Option<String> {
["media_type", "mediaType", "mime_type", "mimeType", "mime"]
.iter()
.find_map(|key| v.get(*key).and_then(Value::as_str))
.filter(|value| value.starts_with("image/"))
.map(|value| {
value
.split(';')
.next()
.unwrap_or(value)
.to_ascii_lowercase()
})
}
pub fn is_image_part(v: &Value) -> bool {
part_kind(v).is_some_and(|kind| kind.contains("image"))
|| image_media_type(v).is_some()
|| v.get("inlineData").is_some()
|| v.get("inline_data").is_some()
|| v.get("image_url").is_some()
|| v.get("imageUrl").is_some()
|| v.get("source")
.is_some_and(|source| image_media_type(source).is_some())
}
pub fn has_image_content(v: &Value) -> bool {
if is_image_part(v) {
return true;
}
match v {
Value::Array(values) => values.iter().any(has_image_content),
Value::Object(_) => v
.get("content")
.or_else(|| v.get("data"))
.is_some_and(has_image_content),
_ => false,
}
}
fn decode_image_part(v: &Value, depth: usize) -> Option<ImageAttachment> {
if depth > 5 {
return None;
}
for key in ["source", "inlineData", "inline_data"] {
if let Some(inner) = v.get(key) {
if let Some(image) = decode_image_part(inner, depth + 1) {
return Some(image);
}
}
}
let media_type = image_media_type(v);
for key in [
"image_url",
"imageUrl",
"url",
"uri",
"fileUri",
"file_uri",
"path",
] {
if let Some(source) = v.get(key) {
if let Some(value) = source.as_str() {
if let Some(image) = decode_image_source(value, media_type.as_deref()) {
return Some(image);
}
} else if let Some(image) = decode_image_part(source, depth + 1) {
return Some(image);
}
}
}
if let Some(data) = v.get("data") {
match data {
Value::String(value) => {
if value.starts_with("data:") {
return decode_data_uri(value);
}
if media_type.as_deref() == Some("image/svg+xml") && value.contains("<svg") {
return attachment_from_bytes(value.as_bytes().to_vec(), media_type.as_deref());
}
return decode_base64_image(value, media_type.as_deref());
}
Value::Array(values) if values.len() <= MAX_IMAGE_BYTES as usize => {
let bytes = values
.iter()
.map(Value::as_u64)
.collect::<Option<Vec<_>>>()?
.into_iter()
.map(u8::try_from)
.collect::<Result<Vec<_>, _>>()
.ok()?;
return attachment_from_bytes(bytes, media_type.as_deref());
}
Value::Object(_) => return decode_image_part(data, depth + 1),
_ => {}
}
}
None
}
fn decode_image_source(value: &str, _media_type: Option<&str>) -> Option<ImageAttachment> {
if value.starts_with("data:") {
return decode_data_uri(value);
}
// 会话文件是不可信输入,不能允许其中的 path/file:// 指向任意本地文件。
// 各适配器只解析会话自身携带的 data URI/base64/byte-array 图片。
None
}
fn decode_base64_image(data: &str, media_type: Option<&str>) -> Option<ImageAttachment> {
if data.len() > MAX_IMAGE_B64 {
return None;
}
let compact;
let data = if data.bytes().any(|byte| byte.is_ascii_whitespace()) {
compact = data
.bytes()
.filter(|byte| !byte.is_ascii_whitespace())
.collect::<Vec<_>>();
compact.as_slice()
} else {
data.as_bytes()
};
let bytes = BASE64
.decode(data)
.or_else(|_| BASE64_URL_SAFE.decode(data))
.ok()?;
attachment_from_bytes(bytes, media_type)
}
/// `data:image/png;base64,...` → 图片附件。只接受 image MIME 与 base64,
/// 不下载 http(s) URL。
pub fn decode_data_uri(uri: &str) -> Option<ImageAttachment> {
let rest = uri.strip_prefix("data:")?;
let (metadata, data) = rest.split_once(',')?;
let mut fields = metadata.split(';');
let media_type = fields.next()?;
if !media_type.starts_with("image/") || !fields.any(|field| field == "base64") {
return None;
}
decode_base64_image(data, Some(media_type))
}
/// 会话自己目录里的图片文件(Antigravity 的 `.user_uploaded/`)→ 图片附件。只给 adapter 自己
/// 枚举出来的文件用,**不要拿转录内容里写的路径来调**——那条路一律不解引用本地路径(见
/// `image_parser_never_dereferences_local_paths`)。解开符号链接后必须仍在 `session` 目录里:
/// 远程镜像原样保留符号链接,指到外面的会读到本机的文件(中间哪一层目录是链接都一样)。
/// 类型按字节嗅探;解码预算与 base64 那条路同一份(调用方的解析要开着
/// `transcript_image_decode_budget`),按 stat 到的大小先问预算再读
pub fn image_from_session_file(
session: &std::path::Path,
path: &std::path::Path,
) -> Option<ImageAttachment> {
let real = std::fs::canonicalize(path).ok()?;
if !real.starts_with(std::fs::canonicalize(session).ok()?) {
return None;
}
let len = std::fs::metadata(&real).ok()?.len();
if len == 0 || len > MAX_IMAGE_BYTES || !image_decode_budget_allows(len as usize) {
return None;
}
attachment_from_bytes(std::fs::read(&real).ok()?, None)
}
/// URI / 目录名里的 percent-encoding(`%2F` → `/`)。逐字节解,不成对的 `%` 原样留着,
/// 后面跟着多字节字符也不会切坏(按 `&str` 下标切会 panic)
pub fn percent_decode(input: &str) -> String {
let bytes = input.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut ix = 0;
while ix < bytes.len() {
if bytes[ix] == b'%' && ix + 2 < bytes.len() {
if let (Some(high), Some(low)) = (hex_digit(bytes[ix + 1]), hex_digit(bytes[ix + 2])) {
out.push((high << 4) | low);
ix += 3;
continue;
}
}
out.push(bytes[ix]);
ix += 1;
}
String::from_utf8_lossy(&out).into_owned()
}
fn hex_digit(c: u8) -> Option<u8> {
Some(match c {
b'0'..=b'9' => c - b'0',
b'a'..=b'f' => c - b'a' + 10,
b'A'..=b'F' => c - b'A' + 10,
_ => return None,
})
}
fn attachment_from_bytes(bytes: Vec<u8>, media_type: Option<&str>) -> Option<ImageAttachment> {
if bytes.is_empty() || bytes.len() as u64 > MAX_IMAGE_BYTES {
return None;
}
let media_type = media_type
.filter(|value| value.starts_with("image/"))
.map(str::to_string)
.or_else(|| sniff_image_media_type(&bytes).map(str::to_string))?;
if !consume_image_decode_budget(bytes.len()) {
return None;
}
Some(ImageAttachment {
media_type,
bytes,
text_offset: 0,
})
}
fn sniff_image_media_type(bytes: &[u8]) -> Option<&'static str> {
if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
Some("image/png")
} else if bytes.starts_with(&[0xff, 0xd8, 0xff]) {
Some("image/jpeg")
} else if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
Some("image/gif")
} else if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP" {
Some("image/webp")
} else if bytes.starts_with(b"BM") {
Some("image/bmp")
} else if bytes.starts_with(b"II*\0") || bytes.starts_with(b"MM\0*") {
Some("image/tiff")
} else if std::str::from_utf8(&bytes[..bytes.len().min(512)])
.ok()
.is_some_and(|head| head.contains("<svg"))
{
Some("image/svg+xml")
} else {
None
}
}
pub const IMAGE_PLACEHOLDER: &str = "[image]";
/// 拆掉 Codex Desktop 文件清单包装,但保留 `My request` 后的真实提问。
pub fn unwrap_file_preamble(text: &str) -> Option<String> {
const HEADS: &[&str] = &[
"# Files mentioned by the user",
"# Files pasted by the user",
];
const MARKERS: &[&str] = &["## My request for Codex:", "## My request:"];
let text = text.trim_start();
if !HEADS.iter().any(|head| text.starts_with(head)) {
return None;
}
Some(
MARKERS
.iter()
.find_map(|marker| text.find(marker).map(|index| (marker, index)))
.map(|(marker, index)| text[index + marker.len()..].trim().to_string())
.unwrap_or_default(),
)
}
/// 剥掉 Codex Desktop 写入正文的 `<image ...>` 标签。真正的图片通常同时
/// 存在于 input_image 内容块;临时文件路径失效时不再污染正文。
pub fn strip_image_tags(text: &str) -> String {
const INJECTED_PREFIX: &str = "<image name=[Image #";
if !text.contains(INJECTED_PREFIX) {
return text.to_string();
}
let mut out = String::with_capacity(text.len());
let mut rest = text;
while let Some(start) = rest.find(INJECTED_PREFIX) {
out.push_str(&rest[..start]);
let after = &rest[start..];
let Some(open_end) = after.find('>').map(|index| index + 1) else {
out.push_str(after);
return out;
};
let open_tag = &after[..open_end];
if !open_tag.contains("] path=") {
out.push_str(&after[..INJECTED_PREFIX.len()]);
rest = &after[INJECTED_PREFIX.len()..];
continue;
}
let end = after[open_end..]
.find("</image>")
.map(|index| open_end + index + "</image>".len())
.unwrap_or(open_end);
rest = &after[end..];
}
out.push_str(rest);
out.trim().to_string()
}
/// 按 mtime 失效的单值缓存(边车映射/SQLite 全表在一轮扫描内的重复调用)。
/// build 返回 None 时不缓存失败结果,mtime 不变也会在下次重试。
pub struct MtimeCache<T: Clone>(std::sync::Mutex<Option<(i64, T)>>);
impl<T: Clone> MtimeCache<T> {
pub fn new() -> Self {
Self(std::sync::Mutex::new(None))
}
pub fn get_or_try_build(&self, mtime: i64, build: impl FnOnce() -> Option<T>) -> Option<T> {
self.get_or_build_result(mtime, || build().ok_or(())).ok()
}
/// 同 `get_or_try_build`,但 build 失败时交回**上一次成功的值**(戳不更新,下次照样
/// 重试)。给"读不出来也得给个答案"的调用方:ZCode 的隐藏名单与行清单这类接口表达
/// 不了"不知道",而空答案的后果是全部放出 / 全部删掉(2026-09-21 review),旧答案
/// 至少是上一次的事实。从没成功过才是 None
pub fn get_or_stale(&self, mtime: i64, build: impl FnOnce() -> Option<T>) -> Option<T> {
self.get_or_try_build(mtime, build)
.or_else(|| self.latest())
}
/// 上一次成功读到的值,不看戳、不重读。扫描末尾才问的快照(`parent_links`)要的是这一轮
/// 枚举入库的那一份:库在扫描期间被写过时按戳重读,只是把整个枚举查询再跑一遍,多读到的
/// 新会话这一轮也没入库
pub fn latest(&self) -> Option<T> {
self.0.lock().unwrap().as_ref().map(|(_, v)| v.clone())
}
/// build 带错误:Ok 才缓存,Err 原样带回、不记——"失败不缓存"是这个缓存本来的
/// 契约,只是多把原因交出去(记忆目录列不出、读不出时 scanner 要靠 Err 跳过该组,
/// 不能拿到一个空的 Ok);`get_or_try_build` 是它的 Option 壳
pub fn get_or_build_result<E>(
&self,
mtime: i64,
build: impl FnOnce() -> Result<T, E>,
) -> Result<T, E> {
{
let cache = self.0.lock().unwrap();
if let Some((t, v)) = cache.as_ref() {
if *t == mtime {
return Ok(v.clone());
}
}
}
let v = build()?;
*self.0.lock().unwrap() = Some((mtime, v.clone()));
Ok(v)
}
}
/// tool_use 块 → ToolCallView(preview + pretty-print input 三件套统一)
/// 工具调用的参数:模型常把它写成 JSON 字符串,解得开就用解开的,解不开(命令行、自由文本)
/// 原样留着
pub fn decoded_arguments(args: &Value) -> std::borrow::Cow<'_, Value> {
match args.as_str().and_then(|s| serde_json::from_str(s).ok()) {
Some(parsed) => std::borrow::Cow::Owned(parsed),
None => std::borrow::Cow::Borrowed(args),
}
}
pub fn tool_call_view(
id: String,
name: &str,
input: &Value,
output: Option<String>,
is_error: bool,
) -> ToolCallView {
let input_json = if input.is_null() {
String::new()
} else {
serde_json::to_string_pretty(input).unwrap_or_default()
};
ToolCallView {
id,
name: if name.is_empty() {
"tool".to_string()
} else {
name.to_string()
},
input_preview: make_preview(input),
input: if input_json.is_empty() {
None
} else {
Some(clip(&input_json, MAX_TOOL_IO).0)
},
output: output.map(|o| clip(&o, MAX_TOOL_IO).0),
is_error,
child_id: None,
}
}
/// 截断到 max 字符(按 char 边界),返回 (text, truncated)
/// `clip` 的按字符版:预算是字符数——记忆正文多是中文(约 3 字节一字),按字节截会把
/// 9000 字的文件在 6600 字处截断、提示却说"20000 of 9000 characters"(2026-09-22 review)
pub fn clip_chars(s: &str, max_chars: usize) -> (String, bool) {
match s.char_indices().nth(max_chars) {
None => (s.to_string(), false),
Some((end, _)) => (format!("{}\n… (truncated)", &s[..end]), true),
}
}
pub fn clip(s: &str, max: usize) -> (String, bool) {
if s.len() <= max {
return (s.to_string(), false);
}
// 找不超过 max 的最大 char 边界
let mut end = max;
while end > 0 && !s.is_char_boundary(end) {
end -= 1;
}
(format!("{}\n… (truncated)", &s[..end]), true)
}
/// RFC3339 字符串 → epoch ms,解析失败 = 0
pub fn iso_ms(s: &str) -> i64 {
chrono::DateTime::parse_from_rfc3339(s)
.map(|d| d.timestamp_millis())
.unwrap_or(0)
}
/// SQLite `datetime('now')` 风格("2026-05-15 06:23:37" 或带 T/毫秒/Z)→ epoch ms(按 UTC)
pub fn sqlite_dt_ms(s: &str) -> i64 {
let ms = iso_ms(s);
if ms > 0 {
return ms;
}
let t = s.replace(' ', "T");
let with_z = if t.ends_with('Z') { t } else { format!("{t}Z") };
iso_ms(&with_z)
}
/// ISO8601 字符串或 unix 秒/毫秒 → epoch ms
pub fn to_epoch_ms(v: &Value) -> i64 {
match v {
Value::Number(n) => epoch_ms(n.as_f64().unwrap_or(0.0)),
Value::String(s) => iso_ms(s),
_ => 0,
}
}
/// unix 秒或毫秒(> 1e12 当毫秒)→ epoch ms;非正数给 0。秒/毫秒的唯一裁定点
pub fn epoch_ms(n: f64) -> i64 {
if n > 1e12 {
n as i64
} else if n > 0.0 {
(n * 1000.0) as i64
} else {
0
}
}
/// 清洗标题候选:剥 slash-command 壳与 system-reminder 等标签,压单行截断。空串=不可用
pub fn clean_title_candidate(raw: &str) -> String {
clean_user_text(raw, false)
}
/// 用户那句话折成一行(新会话开场交接里的 "last asked"):与标题同一套清洗,只是 slash 命令
/// 写回用户敲的样子 `/name args`——标题只留参数,交接里要看得出是哪条命令。空串 = 不是人说的
/// 话(只剩 `/model` 一类命令的输出等)
pub fn clean_prompt_line(raw: &str) -> String {
clean_user_text(raw, true)
}
/// 两者共用的清洗;`whole_command` 定 slash 命令写成 `/name args`,还是只留参数(没有参数退
/// 命令名)
fn clean_user_text(raw: &str, whole_command: bool) -> String {
let raw = codex_ide_request(raw).unwrap_or(raw);
let mut s = strip_tag_block(raw, "system-reminder");
s = strip_tag_block(&s, "local-command-caveat");
s = strip_tag_block(&s, "local-command-stdout");
// Kimi 派出去的 explore 子代理收到的任务前面垫着仓库现状
s = strip_tag_block(&s, "git-context");
let args = extract_tag(&s, "command-args");
let name = extract_tag(&s, "command-name");
if args.is_some() || name.is_some() {
let args = args.filter(|a| !a.trim().is_empty());
s = match (whole_command, name, args) {
(true, Some(name), args) => format!("{name} {}", args.unwrap_or_default()),
(_, name, args) => args.or(name).unwrap_or_default(),
};
}
// 去掉残余短标签
let mut out = String::with_capacity(s.len());
let mut chars = s.chars().peekable();
while let Some(c) = chars.next() {
if c == '<' {
let mut tag = String::new();
let mut closed = false;
for c2 in chars.by_ref() {
if c2 == '>' {
closed = true;
break;
}
if c2 == '\n' || tag.len() > 60 {
break;
}
tag.push(c2);
}
if !closed {
out.push('<');
out.push_str(&tag);
} else {
out.push(' ');
}
} else {
out.push(c);
}
}
crate::text::one_line(&out.replace(IMAGE_PLACEHOLDER, " "), MAX_TITLE)
}
/// Codex IDE 扩展把编辑器上下文(活动文件、打开的标签页、选中的代码)包在提问外面,
/// `## My request for Codex:` 之后才是用户的话。只给标题与交接用:正文原样保留,选中的
/// 代码是用户特意附上的
fn codex_ide_request(text: &str) -> Option<&str> {
let (_, request) = text
.trim_start()
.strip_prefix("# Context from my IDE setup:")?
.split_once("## My request for Codex:")?;
Some(request)
}
fn strip_tag_block(s: &str, tag: &str) -> String {
let open = format!("<{tag}>");
let close = format!("</{tag}>");
let mut out = String::with_capacity(s.len());
let mut rest = s;
loop {
match rest.find(&open) {
None => {
out.push_str(rest);
return out;
}
Some(i) => {
out.push_str(&rest[..i]);
out.push(' ');
match rest[i..].find(&close) {
None => return out,
Some(j) => rest = &rest[i + j + close.len()..],
}
}
}
}
}
pub(crate) fn extract_tag(s: &str, tag: &str) -> Option<String> {
let open = format!("<{tag}>");
let close = format!("</{tag}>");
let i = s.find(&open)?;
let j = s[i + open.len()..].find(&close)?;
Some(s[i + open.len()..i + open.len() + j].to_string())
}
/// `<tag>…</tag>` 的内文(去首尾空白);没有或为空 = None
pub(crate) fn tag_inner(text: &str, tag: &str) -> Option<String> {
extract_tag(text, tag)
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty())
}
/// IDE/CLI 注入型"用户"消息:非用户手打,详情里应归 Meta 折叠,不参与标题推导。
pub fn is_injected_user_content(text: &str) -> bool {
let t = text.trim_start();
const PREFIXES: &[&str] = &[
"<recommended_plugins",
"<environment_context",
"<user_action",
"<user_instructions",
"<permissions",
"<workspace",
"<system-",
"<context ",
"<session_context",
"IMPORTANT: Do NOT read",
"Caveat: The messages below",
"# Files pasted by the user",
"# Files mentioned by the user",
"## Referenced ChatGPT conversation",
// Codex 把 AGENTS.md 作为 user 消息注入
"# AGENTS.md instructions",
// Claude Code 的后台任务(子代理、后台命令)结束时以 user 行注入的通知,不是人打的字;
// 不认它的话它会当成提问进 Insights、给分支会话起出 "b69tgbuwc toolu_…" 这种标题
"<task-notification",
// Codex 的 subagent / 分支线程:父会话的整段 transcript 被打包成
// 一条 role=user 消息喂进来,里面含父会话的 assistant 输出。不认它
// 的话,父会话里 AI 说的话会显示成这个会话里用户发的
"The following is the Codex agent history",
];
if PREFIXES.iter().any(|p| t.starts_with(p)) {
return true;
}
// Codex 的 skill 展开体:skill-name + SKILL.md 路径 + frontmatter(不带 $,
// 用户手打的 "$skill" 引用是另一条独立消息,不受影响)。路径子串两种
// 分隔符都认——Windows 上 Codex 写进日志的是反斜杠路径,只匹配 '/'
// 会让展开体漏过滤、灌进正文与 FTS(2026-08-25 review)
t.contains("/.codex/plugins/")
|| t.contains(r"\.codex\plugins\")
|| ((t.contains("/plugins/cache/") || t.contains(r"\plugins\cache\"))
&& t.contains("SKILL.md"))
}
/// tool 输入的单行摘要
pub fn make_preview(input: &Value) -> String {
const MAX: usize = 200;
let cand = if let Value::Object(obj) = input {
[
"command",
"file_path",
"path",
"pattern",
"query",
"url",
"description",
]
.iter()
.find_map(|k| {
obj.get(*k)
.and_then(|v| v.as_str())
.filter(|s| !s.trim().is_empty())
})
.map(|s| s.to_string())
.or_else(|| serde_json::to_string(input).ok())
} else if let Value::String(s) = input {
Some(s.clone())
} else {
serde_json::to_string(input).ok()
};
let one = cand
.unwrap_or_default()
.split_whitespace()
.collect::<Vec<_>>()
.join(" ");
let chars: Vec<char> = one.chars().collect();
if chars.len() > MAX {
let mut t: String = chars[..MAX].iter().collect();
t.push('…');
t
} else {
one
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Claude Code 后台任务结束的通知是注入内容,不是提问;正文里提到这个词的照算人话
#[test]
fn task_notifications_are_injected_content() {
assert!(is_injected_user_content(
"<task-notification>\n<task-id>b69tgbuwc</task-id>\n<status>completed</status>"
));
assert!(!is_injected_user_content(
"为什么 <task-notification> 会被当成提问?"
));
}
#[test]
fn sidecar_fingerprints_tell_renames_apart() {
// 按 1024 取模时这两个名字撞在同一个值上(2026-10-11 Codex review)
assert_ne!(
sidecar_fingerprint(&["Oscar", ""]),
sidecar_fingerprint(&["Ada 4", ""])
);
// 段界算数:字段之间挪一个字不是同一份
assert_ne!(
sidecar_fingerprint(&["ab", "c"]),
sidecar_fingerprint(&["a", "bc"])
);
}
#[test]
fn jsonl_lines_stop_on_a_persistent_read_error() {
// 一直读不出来(EIO、断开的网络盘):交一次 Err 就结束,不打转
struct Broken;
impl std::io::Read for Broken {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
Err(std::io::Error::other("disk gone"))
}
}
let mut lines = jsonl_lines(std::io::BufReader::new(Broken));
assert!(matches!(lines.next(), Some(Err(_))));
assert!(lines.next().is_none());
// 坏 UTF-8 的行跳过,接着读
let data: &[u8] = b"{\"a\":1}\n\xff\xfe\n{\"b\":2}\n";
let lines: Vec<_> = jsonl_lines(data).map(Result::unwrap).collect();
assert_eq!(
lines,
vec![
Some("{\"a\":1}".to_string()),
None,
Some("{\"b\":2}".to_string())
]
);
// 解成 JSON:空行跳过,坏行与不是 JSON 的行都交 None
let data: &[u8] = b"{\"a\":1}\n\n \nnot json\n\xff\n{\"b\":2}";
let values: Vec<_> = jsonl_values(data).map(Result::unwrap).collect();
assert_eq!(
values,
vec![
Some(serde_json::json!({"a": 1})),
None,
None,
Some(serde_json::json!({"b": 2}))
]
);
}
#[test]
fn merging_into_the_last_assistant_caps_text_and_thinking() {
let content = |text: &str| ParsedContent {
text: text.to_string(),
images: Vec::new(),
};
let mut messages = vec![text_msg(Role::User, "hi", 1)];
// 最后一条是用户:先开一条空的助手消息
assert_eq!(
merge_into_last_assistant(&mut messages, 0, content(""), "plan"),
1
);
assert_eq!(messages[1].timestamp, None);
let big = "x".repeat(MAX_MSG_TEXT);
let long_thinking = "t".repeat(MAX_TOOL_IO);
for ts in [2, 3] {
merge_into_last_assistant(&mut messages, ts, content(&big), &long_thinking);
}
assert_eq!(messages.len(), 2);
let reply = &messages[1];
assert_eq!(reply.timestamp, Some(2), "还没有时间的用第一次带时间的");
assert!(reply.truncated);
assert_eq!(reply.text.matches("(truncated)").count(), 1);
let thinking = reply.thinking.clone().unwrap();
assert!(thinking.starts_with("plan\n\n"));
assert_eq!(thinking.matches("(truncated)").count(), 1);
// 到上限后不再拼接,也不再反复 clip
merge_into_last_assistant(&mut messages, 4, content(""), "more");
assert_eq!(messages[1].thinking.as_deref(), Some(thinking.as_str()));
}
#[test]
fn percent_decode_walks_bytes() {
assert_eq!(percent_decode("/Users/a%20b/%E4%B8%AD"), "/Users/a b/中");
// 不成对的 `%`、后面跟多字节字符的 `%` 原样留着,不 panic
assert_eq!(percent_decode("100%"), "100%");
assert_eq!(percent_decode("%中%z9"), "%中%z9");
}
/// Windows 形状的项目路径换成别家记的写法:盘符大写、Windows 上正斜杠换反斜杠;
/// POSIX 路径(含远程镜像来的)原样
#[test]
fn project_paths_are_canonical() {
assert_eq!(canonical_project_path("/Users/x/app"), "/Users/x/app");
assert_eq!(canonical_project_path(r"c:\Users\x\app"), r"C:\Users\x\app");
if cfg!(windows) {
assert_eq!(canonical_project_path("c:/Users/x/app"), r"C:\Users\x\app");
assert_eq!(
canonical_project_path("//nas/share/app"),
r"\\nas\share\app"
);
} else {
assert_eq!(canonical_project_path("c:/Users/x/app"), "C:/Users/x/app");
assert_eq!(canonical_project_path("//nas/share/app"), "//nas/share/app");
}
}
#[test]
fn clip_chars_counts_characters() {
let s = "记忆正文一共九个字";
assert_eq!(clip_chars(s, 9), (s.to_string(), false));
let (cut, truncated) = clip_chars(s, 4);
assert!(truncated);
assert!(cut.starts_with("记忆正文\n…"), "{cut}");
}
const IMAGE_SHAPES: &str = include_str!("../../tests/fixtures/image_content_shapes.json");
#[test]
fn readable_agent_image_shapes_decode_only_for_transcripts() {
let fixtures: Vec<Value> = serde_json::from_str(IMAGE_SHAPES).expect("image fixtures");
assert_eq!(fixtures.len(), 7);
for fixture in fixtures {
let name = fixture["name"].as_str().expect("fixture name");
let content = &fixture["content"];
let indexed = content_parts(content, false);
assert_eq!(indexed.text, IMAGE_PLACEHOLDER, "index shape {name}");
assert!(indexed.images.is_empty(), "index bytes {name}");
let transcript = content_parts(content, true);
assert!(transcript.text.is_empty(), "transcript text {name}");
assert_eq!(transcript.images.len(), 1, "transcript image {name}");
assert_eq!(transcript.images[0].media_type, "image/png", "mime {name}");
assert!(
transcript.images[0].bytes.starts_with(b"\x89PNG\r\n\x1a\n"),
"png bytes {name}"
);
}
}
#[test]
fn image_parser_is_bounded_and_never_fetches_remote_urls() {
let remote = serde_json::json!({
"type": "image",
"image_url": "https://example.com/private.png"
});
let parsed = content_parts(&remote, true);
assert_eq!(parsed.text, IMAGE_PLACEHOLDER);
assert!(parsed.images.is_empty());
let non_image = serde_json::json!({
"type": "document",
"source": {"type": "base64", "media_type": "application/pdf", "data": "AA=="}
});
assert!(!is_image_part(&non_image));
let parsed = content_parts(&non_image, true);
assert!(parsed.text.is_empty());
assert!(parsed.images.is_empty());
let oversized = format!("data:image/png;base64,{}", "A".repeat(MAX_IMAGE_B64 + 1));
assert!(decode_data_uri(&oversized).is_none());
}
#[test]
fn transcript_image_budget_is_aggregate_and_restores_after_scope() {
let png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
let image = serde_json::json!({
"type": "image",
"media_type": "image/png",
"data": png
});
{
let _budget = image_decode_budget(Some(100));
assert_eq!(content_parts(&image, true).images.len(), 1);
let rejected = content_parts(&image, true);
assert!(rejected.images.is_empty());
assert_eq!(rejected.text, IMAGE_PLACEHOLDER);
}
assert_eq!(content_parts(&image, true).images.len(), 1);
}
#[test]
fn image_parser_handles_wrappers_mimeless_data_and_tool_fallbacks() {
let png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
let wrapped = serde_json::json!({
"content": {"type": "image", "data": png}
});
let parsed = content_parts(&wrapped, true);
assert_eq!(parsed.images.len(), 1);
assert_eq!(parsed.images[0].media_type, "image/png");
let object = serde_json::json!({"exit_code": 0, "duration_ms": 12});
let parsed = tool_result_parts(&object, true);
assert!(parsed.images.is_empty());
let expected: serde_json::Value =
serde_json::from_str(r#"{"duration_ms":12,"exit_code":0}"#).unwrap();
let actual: serde_json::Value = serde_json::from_str(&parsed.text).unwrap();
assert_eq!(actual, expected);
}
#[test]
fn image_parser_preserves_text_image_order() {
let png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
let content = serde_json::json!([
{"type": "text", "text": "前面的说明"},
{"type": "image", "media_type": "image/png", "data": png},
{"type": "text", "text": "后面的说明"}
]);
let parsed = content_parts(&content, true);
assert_eq!(parsed.text, "前面的说明\n\n后面的说明");
assert_eq!(parsed.images.len(), 1);
assert_eq!(parsed.images[0].text_offset, "前面的说明".len());
}
#[test]
fn image_parser_never_dereferences_local_paths() {
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().join("secret.png");
std::fs::write(&path, b"not really an image").expect("fixture");
let content = serde_json::json!({
"type": "image",
"media_type": "image/png",
"path": path
});
let parsed = content_parts(&content, true);
assert_eq!(parsed.text, IMAGE_PLACEHOLDER);
assert!(parsed.images.is_empty());
}
#[test]
fn codex_wrappers_keep_only_the_user_request() {
let wrapped = concat!(
"# Files mentioned by the user:\n\n",
"## Screenshot.png: /tmp/Screenshot.png\n\n",
"## My request:\n",
"看看这里 <image name=[Image #1] path=\"/tmp/missing.png\">ignored</image> 怎么了"
);
let request = unwrap_file_preamble(wrapped).expect("wrapped request");
assert_eq!(strip_image_tags(&request), "看看这里 怎么了");
// IDE 扩展的编辑器上下文只在标题与交接里拆掉;正文不经这里,选中的代码还在
let ide = concat!(
"# Context from my IDE setup:\n\n",
"## Active file: src/login.rs\n\n",
"## Active selection of the file:\nfn login() {}\n\n",
"## My request for Codex:\n",
"修一下登录按钮\n"
);
assert_eq!(unwrap_file_preamble(ide), None);
assert_eq!(clean_title_candidate(ide), "修一下登录按钮");
assert_eq!(clean_prompt_line(ide), "修一下登录按钮");
let ordinary = "为什么 <image src=\"avatar.png\"></image> 没有显示?";
assert_eq!(strip_image_tags(ordinary), ordinary);
assert_eq!(clean_title_candidate("[image] 看看这里"), "看看这里");
}
#[test]
fn title_skips_pure_image_messages() {
let mut image = text_msg(Role::User, IMAGE_PLACEHOLDER, 1);
image.images.push(ImageAttachment {
media_type: "image/png".to_string(),
bytes: vec![1],
text_offset: 0,
});
let text = text_msg(Role::User, "后面的真实问题", 2);
assert_eq!(
title_from_messages(&[image, text]).as_deref(),
Some("后面的真实问题")
);
}
}