# 从会话文件到模型请求的重建链路：五个阶段各由一个固定函数负责
会话文件 (.jsonl)
  → 解析条目 (parseSessionEntries)        每行一个 JSON，坏行跳过
  → 取活动分支 (getBranch)                从当前叶子沿 parentId 回溯到根
  → 应用压缩 (buildContextEntries)         摘要替换更早的条目
  → 应用编辑 (buildSessionProjection)      context_edit 覆盖或省略目标
  → 转成模型消息 (buildSessionContext)     条目类型决定产出什么消息

// branch.ts
import { SessionManager } from "@earendil-works/pi-coding-agent";

const manager = SessionManager.open("~/.pi/agent/sessions/--srv-my-project--/2024-12-03T14-00-00_abc123.jsonl");

// 活动分支：从根到当前叶子
for (const entry of manager.getBranch()) {
	console.log(entry.type, entry.id, entry.parentId);
}

// 全部条目：包含被放弃的分支
console.log("全部条目数：", manager.getEntries().length);
console.log("活动分支条目数：", manager.getBranch().length);

// restore.ts
import { createAgentSession, SessionManager, type FileEntry } from "@earendil-works/pi-coding-agent";

// 外部历史条目
const externalEntries: FileEntry[] = [
	{
		// 会话头：type 为 session 的那条不参与树结构
		type: "session",
		version: 3,
		id: "restored-session",
		timestamp: new Date().toISOString(),
		cwd: process.cwd(),
	},
	{
		// 根条目：parentId 为 null，下一个条目要挂在它下面
		type: "message",
		id: "m0000001",
		parentId: null,
		timestamp: new Date().toISOString(),
		message: { role: "user", content: "继续修复类型错误", timestamp: Date.now() },
	},
];

const { session } = await createAgentSession({
	// 第三个参数是初始条目数组
	sessionManager: SessionManager.inMemory(process.cwd(), undefined, externalEntries),
});

try {
	await session.prompt("从刚才的进度继续");
	console.log(session.getLastAssistantText());
} finally {
	session.dispose();
}

// anti-pattern.ts
import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
});

try {
	// 反例：改了 agent 内部状态，但持久化上下文没变
	session.agent.state.messages = [
		{ role: "user", content: "这条消息不会进入持久化上下文", timestamp: Date.now() },
	];

	// 投影出来的权威上下文里没有它：两份状态从此分叉
	console.log("投影消息数：", session.sessionManager.buildSessionProjection().messages.length);
	console.log("agent 状态消息数：", session.agent.state.messages.length);
} finally {
	session.dispose();
}

// Agent Core 文档给的形态。文档里的 loadModelContext() 是示意写法，
// coding-agent SDK 里对应的实际操作是 sessionManager.buildSessionProjection()
agent.prepareRequest = async ({ context }) => ({
	context: { ...context, messages: await session.loadModelContext() },
});

// prepare-request.ts
import { createAgentSession, SessionManager, type AgentMessage } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession({
	sessionManager: SessionManager.inMemory(),
});

// 保留原有的 prepareRequest，先跑它再叠加我们的逻辑
const previousPrepareRequest = session.agent.prepareRequest;

session.agent.prepareRequest = async (request, signal) => {
	const result = await previousPrepareRequest?.(request, signal);
	const context = result?.context ?? request.context;

	// 权威上下文：会话投影 + 当前的外部状态
	// 用投影而不是 session.messages
	const projection = session.sessionManager.buildSessionProjection();
	const projectState = await loadProjectState(signal);

	const messages: AgentMessage[] = [
		...projection.messages,
		{
			// 用 XML 标签包住注入内容，让模型能分辨它不是用户说的
			role: "user",
			content: `<project-state>\n${projectState}\n</project-state>`,
			timestamp: Date.now(),
		},
	];

	// 必须返回 { context }：返回 undefined 表示保持原上下文不变
	return { ...result, context: { ...context, messages } };
};

async function loadProjectState(signal?: AbortSignal): Promise<string> {
	// 实际项目里这里读数据库、读配置文件或调用内部 API
	return "分支: feature/fix-types\n已修改文件: src/types.ts";
}

try {
	await session.prompt("继续修复类型错误");
} finally {
	session.dispose();
}

// inspect-context.ts
import { readFileSync } from "node:fs";
import {
	buildContextEntries,
	buildSessionProjection,
	migrateSessionEntries,
	parseSessionEntries,
	type FileEntry,
	type SessionEntry,
} from "@earendil-works/pi-coding-agent";

const path = process.argv[2];
if (!path) {
	console.error("用法: tsx inspect-context.ts <session.jsonl>");
	process.exit(1);
}

// 1. 解析：每行一个 JSON，坏行被跳过
const entries: FileEntry[] = parseSessionEntries(readFileSync(path, "utf-8"));

// 2. 迁移：把 v1 / v2 的旧会话升级到当前版本（就地修改）
migrateSessionEntries(entries);

// 3. 全部条目（含被放弃的分支）。会话头不参与树结构，要先滤掉。
const allEntries = entries.filter((e): e is SessionEntry => e.type !== "session");
console.log(`文件里的条目总数：${allEntries.length}`);

// 4. 考虑压缩后的上下文条目
// 注意：直接调导出函数时叶子参数是可选的，默认取数组最后一个条目
const contextEntries = buildContextEntries(allEntries);
console.log(`参与上下文的条目数：${contextEntries.length}`);

// 5. 投影：应用 context_edit 之后的模型可见消息
const projection = buildSessionProjection(allEntries);
console.log(`模型可见消息数：${projection.messages.length}`);

for (const message of projection.messages) {
	const role = message.role;
	const text = "content" in message ? JSON.stringify(message.content).slice(0, 80) : "";
	console.log(`- ${role}: ${text}`);
}

// 6. 压缩条目单独看一眼
for (const entry of contextEntries) {
	if (entry.type === "compaction") {
		console.log(`压缩摘要保留起点：${entry.firstKeptEntryId}`);
		console.log(`压缩前 token 数：${entry.tokensBefore}`);
	}
}

# 用 tsx 直接跑这个离线脚本
npx tsx inspect-context.ts ~/.pi/agent/sessions/--srv-my-project--/2024-12-03T14-00-00_abc123.jsonl