pi-firecode 0.8.1 → 1.0.0

package/review/card.ts

@@ -11,6 +11,7 @@
 import { getMarkdownTheme, type ExtensionAPI, type Theme } from "@earendil-works/pi-coding-agent";
 import { Box, type Component, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { Language } from "../config.js";
+import { HEAT_COLORS, paint } from "../flame.js";
 import { formatDuration } from "../format.js";
 import type { CardData, StopReason } from "./state.js";
 
@@ -30,6 +31,28 @@ const CARD_KINDS = new Set([
 ]);
 const CARD_TONES = new Set(["success", "warning", "error", "neutral", "accent"]);
 
+/**
+ * 卡标题前的单色字形与它的语义色，按卡种类一处定义：构建时写进 details.icon，渲染时按种类上色。
+ * 字形与全局体系一致（✓ ✗ ◌ ‖ 与审查的盲文点阵），颜色只表达结论：通过绿、失败与未完成红、取消灰，
+ * 审查过程中的中性卡（开始、顾问指引）用审查的金色——品牌火焰不用于中性状态。
+ */
+const MARKS = {
+	start: { glyph: "⠿", color: "review" },
+	advisor: { glyph: "⠿", color: "review" },
+	pass: { glyph: "✓", color: "success" },
+	fail: { glyph: "✗", color: "error" },
+	stop: { glyph: "✗", color: "error" },
+	timeout: { glyph: "◌", color: "error" },
+	error: { glyph: "◌", color: "error" },
+	cancel: { glyph: "‖", color: "muted" },
+} as const satisfies Record<CardData["kind"], { glyph: string; color: "review" | "success" | "error" | "muted" }>;
+
+function paintMark(details: CardDetails, theme: Theme): string {
+	const mark = MARKS[details.kind as CardData["kind"]];
+	if (!mark) return details.icon;
+	return mark.color === "review" ? paint(HEAT_COLORS.gold, details.icon) : theme.fg(mark.color, details.icon);
+}
+
 export type CardDetails = {
 	version: typeof VERSION;
 	kind: CardData["kind"];
@@ -101,7 +124,7 @@ class ReviewCard implements Component {
 function nativeCard(details: CardDetails, theme: Theme): Component {
 	// 全家卡统一：无垂直内边距；消息间距由宿主 CustomMessageComponent 提供，不再叠加。
 	const box = new Box(1, 0, (text) => theme.bg(backgroundFor(details.tone), text));
-	box.addChild(new Text(`${details.icon} ${details.title}`, 0, 0));
+	box.addChild(new Text(`${paintMark(details, theme)} ${details.title}`, 0, 0));
 	box.addChild(new Spacer(1));
 	box.addChild(new Markdown(details.lines.join("\n"), 0, 0, getMarkdownTheme()));
 	return box;
@@ -157,7 +180,7 @@ function started(card: Extract<CardData, { kind: "start" }>, language: Language)
 			? `Models: ${card.models.map(shortModel).join(", ")}`
 			: `模型：${card.models.map(shortModel).join("、")}`,
 	];
-	return spec(language, "start", title, lines, "neutral", "🔥");
+	return spec("start", title, lines, "neutral");
 }
 
 function shortModel(model: string) {
@@ -169,7 +192,7 @@ function passed(card: Extract<CardData, { kind: "pass" }>, language: Language):
 	const lines = withFooter(formatReviewResultLines(card.summary), [
 		elapsedLine(card.elapsedMs, card.totalElapsedMs, card.round > 1, language),
 	]);
-	return spec(language, "pass", title, lines, "success", "✅");
+	return spec("pass", title, lines, "success");
 }
 
 function failed(card: Extract<CardData, { kind: "fail" }>, language: Language): BuiltCard {
@@ -183,12 +206,10 @@ function failed(card: Extract<CardData, { kind: "fail" }>, language: Language):
 			: [elapsedLine(card.elapsedMs, card.totalElapsedMs, false, language)]),
 	];
 	return spec(
-		language,
 		"fail",
 		title,
 		withFooter(formatReviewResultLines(card.details), footer),
 		"warning",
-		"❌",
 	);
 }
 
@@ -203,16 +224,16 @@ function stopped(card: Extract<CardData, { kind: "stop" }>, language: Language):
 			language,
 		);
 		const body = [advisorModelLine(card.advisorModel, language), "", ...adviceLines(card.advisor.advice)];
-		return spec(language, "stop", title, withFooter(body, footer), "warning", "❌");
+		return spec("stop", title, withFooter(body, footer), "warning");
 	}
 	const title = qualityTitle(card.round, language === "en" ? "Review failed" : "审查未通过", language);
 	const body = formatReviewResultLines(card.details || stopReason(card.reason, language));
-	return spec(language, "stop", title, withFooter(body, footer), "warning", "❌");
+	return spec("stop", title, withFooter(body, footer), "warning");
 }
 
 function cancelled(card: Extract<CardData, { kind: "cancel" }>, language: Language): BuiltCard {
 	const title = language === "en" ? "Review cancelled" : "审查已取消";
-	return spec(language, "cancel", title, [reasonText(card.reason, language)], "neutral", "⏸");
+	return spec("cancel", title, [reasonText(card.reason, language)], "neutral");
 }
 
 function timedOut(_card: Extract<CardData, { kind: "timeout" }>, language: Language): BuiltCard {
@@ -221,7 +242,7 @@ function timedOut(_card: Extract<CardData, { kind: "timeout" }>, language: Langu
 		language === "en" ? "Blocker: review timed out" : "卡点：审查超时",
 		language === "en" ? "Reason: overall time limit exceeded" : "原因：超过总体时限",
 	];
-	return spec(language, "timeout", title, lines, "warning", "🛑");
+	return spec("timeout", title, lines, "warning");
 }
 
 /** 终止原因的展示文案（reducer 只出枚举，这里本地化）。 */
@@ -250,7 +271,7 @@ function errored(card: Extract<CardData, { kind: "error" }>, language: Language)
 			? []
 			: ["", elapsedLine(card.elapsedMs, card.totalElapsedMs, false, language)]),
 	];
-	return spec(language, "error", title, lines, "warning", "🛑");
+	return spec("error", title, lines, "warning");
 }
 
 /** 顾问卡与审查结果卡同构：裁决进标题，正文用粗体模型分节行开头。 */
@@ -259,10 +280,10 @@ function advisorCard(card: Extract<CardData, { kind: "advisor" }>, language: Lan
 	const title = language === "en" ? `Advisor guidance · ${decision}` : `顾问指引 · ${decision}`;
 	const body = [advisorModelLine(card.advisorModel, language), "", ...adviceLines(card.advisor.advice)];
 	const footer = card.elapsedMs === undefined ? [] : [elapsedLine(card.elapsedMs, undefined, false, language)];
-	return spec(language, "advisor", title, withFooter(body, footer), "neutral", "🧭");
+	return spec("advisor", title, withFooter(body, footer), "neutral");
 }
 
-/** 裁决词→人话文案的唯一映射：卡标题与活动条摘要共用，防两处文案漂移。 */
+/** 裁决词→人话文案的唯一映射：卡标题与审查活动行共用，防两处文案漂移。 */
 export function decisionText(verdict: "continue" | "narrow" | "stop", language: Language) {
 	return language === "en"
 		? { continue: "Continue fixing", narrow: "Narrow scope", stop: "Stop fixing" }[verdict]
@@ -304,7 +325,7 @@ function elapsedLine(
 	const elapsed = showTotal && totalMs !== undefined
 		? `${formatDuration(ms)} / ${language === "en" ? "total" : "总"} ${formatDuration(totalMs)}`
 		: formatDuration(ms);
-	return language === "en" ? `⏱ Elapsed: ${elapsed}` : `⏱ 用时：${elapsed}`;
+	return language === "en" ? `Elapsed: ${elapsed}` : `用时：${elapsed}`;
 }
 
 function formatReviewResultLines(review: string) {
@@ -365,21 +386,13 @@ const REDUNDANT_REVIEW_LINES = new Set([
 ]);
 
 function spec(
-	language: Language,
-	kind: CardDetails["kind"],
+	kind: CardData["kind"],
 	title: string,
 	lines: string[],
 	tone: CardDetails["tone"],
-	icon: string,
 ): BuiltCard {
-	const localized = localize(lines, language);
 	return {
 		content: `${title}\n${lines.join("\n")}`,
-		details: { version: VERSION, kind, title, lines: localized, tone, icon },
+		details: { version: VERSION, kind, title, lines, tone, icon: MARKS[kind].glyph },
 	};
 }
-
-/** details 行已本地化成品；content 里除标题外都是事实，不做二次翻译。 */
-function localize(lines: string[], language: Language) {
-	return lines;
-}

package/review/checkpoint.ts

@@ -40,10 +40,7 @@ export class CheckpointConflictError extends Error {
 
 /** 只读会话访问（checkpoint 读/写前的 CAS 读取）。 */
 export interface CheckpointReadContext {
-	sessionManager?: {
-		getBranch?: () => unknown[];
-		getEntries?: () => unknown[];
-	};
+	sessionManager: { getBranch(): unknown[] };
 }
 
 const PHASES = new Set([
@@ -319,10 +316,7 @@ export function readCheckpoint(ctx: CheckpointReadContext): ReviewState | undefi
 }
 
 function latestEntry(ctx: CheckpointReadContext): Record<string, unknown> | undefined {
-	const entries =
-		ctx.sessionManager?.getBranch?.() ??
-		ctx.sessionManager?.getEntries?.() ??
-		[];
+	const entries = ctx.sessionManager.getBranch();
 	for (let index = entries.length - 1; index >= 0; index -= 1) {
 		const entry = entries[index];
 		if (!isRecord(entry) || entry.type !== "custom") continue;

package/review/evidence.ts

@@ -10,6 +10,7 @@
  * toolResult 正文仍跳过（输出体积大且非一手证据——审查者应自行重跑验证命令）。
  */
 import type { Language } from "../config.js";
+import { textOf } from "../format.js";
 
 export const DEFAULT_EVIDENCE_TOKENS = 24_000;
 /** 单条消息渲染上限，防单条超长消息撑爆预算。 */
@@ -21,13 +22,20 @@ export interface Evidence {
 	omitted: number;
 }
 
+interface Render {
+	language: Language;
+	/** 会话文件：截断标记据此告诉审查者完整原文在哪里。内存会话没有。 */
+	sessionFile?: string;
+	failedCalls: ReadonlySet<string>;
+}
+
 export function buildEvidence(
 	entries: readonly unknown[],
 	language: Language,
-	budgetTokens = DEFAULT_EVIDENCE_TOKENS,
+	{ budgetTokens = DEFAULT_EVIDENCE_TOKENS, sessionFile }: { budgetTokens?: number; sessionFile?: string } = {},
 ): Evidence {
-	const failedCalls = collectFailedCalls(entries);
-	const blocks = entries.flatMap((entry) => renderEntry(entry, language, failedCalls));
+	const render: Render = { language, ...(sessionFile ? { sessionFile } : {}), failedCalls: collectFailedCalls(entries) };
+	const blocks = entries.flatMap((entry) => renderEntry(entry, render));
 	if (blocks.length === 0) return { text: "", omitted: 0 };
 	// 锚点必须是首条用户消息（原始需求）：它之前可能排着其他扩展的可显示消息，
 	// 盲取第一块会把真正的需求锚点让进预算竞争、在长会话里被裁掉。
@@ -78,11 +86,8 @@ function collectFailedCalls(entries: readonly unknown[]): ReadonlySet<string> {
 	return failed;
 }
 
-function renderEntry(
-	entry: unknown,
-	language: Language,
-	failedCalls: ReadonlySet<string>,
-): EvidenceBlock[] {
+function renderEntry(entry: unknown, render: Render): EvidenceBlock[] {
+	const { language } = render;
 	if (!isRecord(entry)) return [];
 	switch (entry.type) {
 		case "message": {
@@ -91,25 +96,25 @@ function renderEntry(
 			if (message.role === "user")
 				return [
 					{
-						text: `## ${userLabel(language)}\n${clip(messageText(message.content))}`,
+						text: `## ${userLabel(language)}\n${clip(textOf(message.content), render)}`,
 						role: "user" as const,
 					},
 				];
 			if (message.role === "assistant")
-				return [{ text: `## ${assistantLabel(language)}\n${assistantBody(message.content, language, failedCalls)}` }];
+				return [{ text: `## ${assistantLabel(language)}\n${assistantBody(message.content, render)}` }];
 			return [];
 		}
 		case "custom_message": {
 			if (entry.display !== true) return [];
-			return [{ text: `## ${customLabel(language, String(entry.customType ?? ""))}\n${clip(messageText(entry.content))}` }];
+			return [{ text: `## ${customLabel(language, String(entry.customType ?? ""))}\n${clip(textOf(entry.content), render)}` }];
 		}
 		case "compaction":
 			return typeof entry.summary === "string" && entry.summary
-				? [{ text: `## ${summaryLabel(language)}\n${clip(entry.summary)}` }]
+				? [{ text: `## ${summaryLabel(language)}\n${clip(entry.summary, render)}` }]
 				: [];
 		case "branch_summary":
 			return typeof entry.summary === "string" && entry.summary
-				? [{ text: `## ${branchSummaryLabel(language)}\n${clip(entry.summary)}` }]
+				? [{ text: `## ${branchSummaryLabel(language)}\n${clip(entry.summary, render)}` }]
 				: [];
 		default:
 			return [];
@@ -137,26 +142,19 @@ function branchSummaryLabel(language: Language) {
 }
 
 /** assistant 正文 = 文本段 + 工具调用轨迹；纯工具回合也因此留下编辑记录。 */
-function assistantBody(
-	content: unknown,
-	language: Language,
-	failedCalls: ReadonlySet<string>,
-): string {
-	if (typeof content === "string") return clip(content);
+function assistantBody(content: unknown, render: Render): string {
+	if (typeof content === "string") return clip(content, render);
 	if (!Array.isArray(content)) return "";
 	const trail = content
-		.map((part) => toolCallLine(asRecord(part), language, failedCalls))
+		.map((part) => toolCallLine(asRecord(part), render))
 		.filter(Boolean)
 		.join("\n");
-	const body = clip(messageText(content));
+	const body = clip(textOf(content), render);
 	return [body, trail].filter(Boolean).join("\n");
 }
 
-function toolCallLine(
-	part: Record<string, unknown> | undefined,
-	language: Language,
-	failedCalls: ReadonlySet<string>,
-): string {
+function toolCallLine(part: Record<string, unknown> | undefined, render: Render): string {
+	const { language, failedCalls } = render;
 	if (part?.type !== "toolCall" || typeof part.name !== "string" || !part.name) return "";
 	const args = asRecord(part.arguments);
 	const target =
@@ -171,33 +169,33 @@ function toolCallLine(
 				? " (failed)"
 				: "（失败）"
 			: "";
-	return `${`[${part.name}] ${clipLine(target)}`.trimEnd()}${failed}`;
+	return `${`[${part.name}] ${clipLine(target, render)}`.trimEnd()}${failed}`;
 }
 
 /** 单行轨迹上限：防超长 bash 命令撑大证据块；路径不受影响。 */
 const TOOL_LINE_MAX_CHARS = 200;
 
-function clipLine(text: string) {
+function clipLine(text: string, { language, sessionFile }: Render) {
 	const single = text.replace(/\s+/gu, " ").trim();
-	return single.length <= TOOL_LINE_MAX_CHARS ? single : `${single.slice(0, TOOL_LINE_MAX_CHARS)}…`;
-}
-
-function messageText(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	return content
-		.map((part) => {
-			const record = asRecord(part);
-			return record?.type === "text" && typeof record.text === "string"
-				? record.text
-				: "";
-		})
-		.join("\n");
+	if (single.length <= TOOL_LINE_MAX_CHARS) return single;
+	const where = sessionFile ?? (language === "en" ? "the session file" : "会话文件");
+	const note = language === "en"
+		? `…[truncated, ${single.length} chars; full original in ${where}]`
+		: `…[截断，原文 ${single.length} 字，完整原文在 ${where}]`;
+	return `${single.slice(0, TOOL_LINE_MAX_CHARS)}${note}`;
 }
 
-function clip(text: string) {
+/**
+ * 截断处必须写明是证据组装的截断：裸省略号会被审查者当成回复本身没写完（长交付物曾因此连判 FAIL）。
+ * 完整原文在会话文件里，审查者能用 read 自行核对。
+ */
+function clip(text: string, { language, sessionFile }: Render) {
 	if (text.length <= MESSAGE_MAX_CHARS) return text.trim();
-	return `${text.slice(0, MESSAGE_MAX_CHARS).trim()}\n[…]`;
+	const where = sessionFile ?? (language === "en" ? "the session file" : "会话文件");
+	const note = language === "en"
+		? `[evidence truncated: this message has ${text.length} characters, only the first ${MESSAGE_MAX_CHARS} are shown; the full original is in ${where} — read it if you need to verify]`
+		: `[证据截断：本条消息原文 ${text.length} 字，此处只给出前 ${MESSAGE_MAX_CHARS} 字；完整原文在 ${where}，需要核对时用 read 查看]`;
+	return `${text.slice(0, MESSAGE_MAX_CHARS).trim()}\n${note}`;
 }
 
 /**