@momenttttt/pi-zcode-memory 0.0.0-stage → 0.1.1

package/src/config.ts

@@ -0,0 +1,88 @@
+/**
+ * 配置读取：全局 `<agent-dir>/extensions/zcode-memory.json` + 项目 `<cwd>/.pi/zcode-memory.json`，
+ * 深合并、防御式解析。形状与另外三个包一致。
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface ZcodeMemoryConfig {
+  enabled: boolean;
+  /**
+   * 显式指定记忆目录（最高优先级）。路径算法对不上时（工作区标识、工作区路径写法差异），
+   * 这是唯一可靠的兜底。
+   */
+  dir: string | undefined;
+  /** 是否做索引注入。默认开。
+   *  单独留开关是为了排查"注入内容干扰上下文"一类问题，不面向常规使用。 */
+  injectIndex: boolean;
+}
+
+export const DEFAULT_ZCODE_MEMORY_CONFIG: ZcodeMemoryConfig = {
+  enabled: true,
+  dir: undefined,
+  injectIndex: true,
+};
+
+function readJsonIfExists(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return isPlainObject(parsed) ? parsed : {};
+  } catch {
+    // 配置坏了不能让插件崩，退化成默认值
+    return {};
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 深合并：只对普通对象递归，数组与标量后写者胜。 */
+export function deepMerge<T extends Record<string, unknown>>(base: T, override: Record<string, unknown>): T {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = result[key];
+    result[key] = isPlainObject(current) && isPlainObject(value) ? deepMerge(current, value) : value;
+  }
+  return result as T;
+}
+
+/** 把外部 JSON 折算成可信配置；非法值一律退回默认值。 */
+export function parseZcodeMemoryConfig(raw: unknown): ZcodeMemoryConfig {
+  if (!isPlainObject(raw)) return { ...DEFAULT_ZCODE_MEMORY_CONFIG };
+  const config = { ...DEFAULT_ZCODE_MEMORY_CONFIG };
+  if (typeof raw.enabled === "boolean") config.enabled = raw.enabled;
+  if (typeof raw.injectIndex === "boolean") config.injectIndex = raw.injectIndex;
+  if (typeof raw.dir === "string" && raw.dir.trim().length > 0) config.dir = raw.dir.trim();
+  return config;
+}
+
+/**
+ * 定位全局配置目录。
+ *
+ * 优先读 pi 自己的环境变量 `PI_CODING_AGENT_DIR`（`pi --help` 列的就是它，pi 内部的
+ * `getAgentDir()` 也认这个），再退回 `~/.pi/agent`。
+ *
+ * 注意别写成 `PI_AGENT_DIR`：那不是 pi 认的名字，设了它 pi 自己的扩展/设置仍然走
+ * `~/.pi/agent`，于是"我们的全局配置"与"pi 的全局资源"会分叉到两个目录。
+ */
+export function resolveAgentDir(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.PI_CODING_AGENT_DIR;
+  if (typeof fromEnv === "string" && fromEnv.trim().length > 0) return fromEnv;
+  return join(homedir(), ".pi", "agent");
+}
+
+export interface LoadConfigOptions {
+  agentDir?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/** 全局 → 项目，深合并。 */
+export function loadConfig(cwd: string, options: LoadConfigOptions = {}): ZcodeMemoryConfig {
+  const agentDir = options.agentDir ?? resolveAgentDir(options.env ?? process.env);
+  const globalRaw = readJsonIfExists(join(agentDir, "extensions", "zcode-memory.json"));
+  const projectRaw = readJsonIfExists(join(cwd, ".pi", "zcode-memory.json"));
+  return parseZcodeMemoryConfig(deepMerge(globalRaw, projectRaw));
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+/** 写入路径上的可预期失败；`code` 供扩展折算成工具错误文案。 */
+export type MemoryWriteErrorCode =
+  | "invalid_name"
+  | "exists"
+  | "symlink"
+  | "index_conflict"
+  | "io"
+  | "invalid_input";
+
+export class MemoryWriteError extends Error {
+  readonly code: MemoryWriteErrorCode;
+  /** 给模型的下一步建议；拼进工具错误文案。 */
+  readonly hint?: string;
+
+  constructor(code: MemoryWriteErrorCode, message: string, hint?: string) {
+    super(message);
+    this.name = "MemoryWriteError";
+    this.code = code;
+    if (hint !== undefined) this.hint = hint;
+  }
+}

package/src/frontmatter.ts

@@ -0,0 +1,136 @@
+/**
+ * 事实文件 frontmatter 的解析与生成。
+ *
+ * 解析规则：
+ *   - 只在前 30 行里找 frontmatter：扫描窗口必须有界，否则一个没有 frontmatter 的文件要被
+ *     整份读进来才能判定（列表扫描对每个文件都做一次这件事）；定成 30 是因为读这些文件的
+ *     一侧也只看这么多——闭合行更靠后的文件在两边都算"无描述条目"
+ *   - 首行必须是 `---`，闭合行必须是单独的 `---`
+ *   - YAML 解析失败或结果不是映射 → 视为"无描述条目"，不抛错
+ *   - `type` 取 `metadata.type`，退回顶层 `type`；只认四个枚举值
+ *
+ * 生成规则（设计 §2.2）：只写 `name` / `description` / `metadata.node_type` / `metadata.type`，
+ * **不写** `originSessionId`：那是读文件的一方在缺失时自己补的惰性字段，我们不伪造不属于
+ * 自己的会话 id；也不加自定义键（未知键行为未核实）。
+ */
+import { parse as parseYaml } from "yaml";
+
+import { MEMORY_TYPES, type MemoryType } from "./paths.ts";
+
+/** 扫描窗口：frontmatter 必须在前 30 行内闭合。 */
+export const FRONTMATTER_SCAN_LINES = 30;
+
+export interface MemoryFrontmatter {
+  name?: string;
+  description?: string;
+  type?: MemoryType;
+  /** 缺 frontmatter、闭合行找不到、YAML 坏、或不是映射时为 true。 */
+  malformed: boolean;
+}
+
+export interface MemoryDocument {
+  frontmatter: MemoryFrontmatter;
+  /** frontmatter 之后的正文；没有合法 frontmatter 时是整份文档。 */
+  body: string;
+}
+
+/** 统一 BOM 与行尾：解析与读取共用这一条归一化，后面按行处理都只面对 `\n`。 */
+export function normalizeMemoryText(content: string): string {
+  return content.replace(/^\uFEFF/u, "").replace(/\r\n/gu, "\n");
+}
+
+/** 找 frontmatter 的闭合行下标（在前 `FRONTMATTER_SCAN_LINES` 行内），找不到返回 -1。 */
+function findFrontmatterEnd(lines: readonly string[]): number {
+  const limit = Math.min(lines.length, FRONTMATTER_SCAN_LINES);
+  for (let index = 1; index < limit; index += 1) {
+    if (lines[index] === "---") return index;
+  }
+  return -1;
+}
+
+export function parseMemoryDocument(content: string): MemoryDocument {
+  const normalized = normalizeMemoryText(content);
+  const lines = normalized.split("\n");
+  if (lines[0] !== "---") {
+    return { frontmatter: { malformed: true }, body: normalized };
+  }
+  const end = findFrontmatterEnd(lines);
+  if (end < 0) {
+    return { frontmatter: { malformed: true }, body: normalized };
+  }
+  const body = lines.slice(end + 1).join("\n").replace(/^\n+/u, "");
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(lines.slice(1, end).join("\n"));
+  } catch {
+    return { frontmatter: { malformed: true }, body };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { frontmatter: { malformed: true }, body };
+  }
+  const record = parsed as Record<string, unknown>;
+  const metadata =
+    typeof record.metadata === "object" && record.metadata !== null && !Array.isArray(record.metadata)
+      ? (record.metadata as Record<string, unknown>)
+      : undefined;
+  const typeCandidate = metadata?.type ?? record.type;
+  const frontmatter: MemoryFrontmatter = { malformed: false };
+  if (typeof record.name === "string" && record.name.trim().length > 0) frontmatter.name = record.name.trim();
+  if (typeof record.description === "string" && record.description.length > 0) {
+    frontmatter.description = record.description;
+  }
+  if (typeof typeCandidate === "string" && (MEMORY_TYPES as readonly string[]).includes(typeCandidate)) {
+    frontmatter.type = typeCandidate as MemoryType;
+  }
+  return { frontmatter, body };
+}
+
+export function parseMemoryFrontmatter(content: string): MemoryFrontmatter {
+  return parseMemoryDocument(content).frontmatter;
+}
+
+export interface RenderMemoryFileInput {
+  name: string;
+  description: string;
+  type: MemoryType;
+  body: string;
+}
+
+/**
+ * 生成事实文件全文。
+ *
+ * YAML 标量按需加双引号（YAML 兼容 JSON 引号）：description 里常见的 `:`、`#`、引号都不会
+ * 弄坏解析。name 已由写入层校验成安全字符。
+ */
+export function renderMemoryFile(input: RenderMemoryFileInput): string {
+  const body = input.body.replace(/\r\n/gu, "\n").replace(/\n*$/u, "");
+  const frontmatter = [
+    "---",
+    `name: ${yamlScalar(input.name)}`,
+    `description: ${yamlScalar(input.description)}`,
+    "metadata:",
+    "  node_type: memory",
+    `  type: ${input.type}`,
+    "---",
+  ].join("\n");
+  return body.length > 0 ? `${frontmatter}\n${body}\n` : `${frontmatter}\n`;
+}
+
+const SPECIAL_SCALAR = /^(?:true|false|null|yes|no|on|off|~)$/iu;
+const PLAIN_SCALAR = /^[\p{L}\p{N}][\p{L}\p{N} .,;!?()[\]{}'"\\/&%*+\-=<>@^`|~$_-]*$/u;
+
+/** 需要时才加引号：保持文件可读，同时保证任何合法输入都能被 YAML 解析回原值。 */
+function yamlScalar(value: string): string {
+  const singleLine = value.replace(/\s+/gu, " ").trim();
+  if (
+    singleLine.length > 0 &&
+    PLAIN_SCALAR.test(singleLine) &&
+    !SPECIAL_SCALAR.test(singleLine) &&
+    !/^\d/u.test(singleLine) &&
+    !/:\s/u.test(singleLine) &&
+    !/\s#/u.test(singleLine)
+  ) {
+    return singleLine;
+  }
+  return JSON.stringify(singleLine);
+}

package/src/index-content.ts

@@ -0,0 +1,102 @@
+/**
+ * 注入用的索引格式化。
+ *
+ *   - 剥掉开头 frontmatter、剥掉顶层 HTML 注释、trim
+ *   - 截断上限 200 行 / 25 000 字符，超限追加一条 WARNING
+ *
+ * 不引入 markdown 解析器：逐行扫描就够——代码围栏外、行首以 `<!--` 开头的注释块整块剥掉，
+ * 列表项与段落里的注释保持原样（真会出现在索引顶部的注释只有这一种用法）。
+ */
+import { createHash } from "node:crypto";
+
+export const INDEX_LINE_LIMIT = 200;
+export const INDEX_CHARACTER_LIMIT = 25_000;
+
+const LEADING_FRONTMATTER_PATTERN = /^---\s*\n[\s\S]*?---\s*\n?/u;
+
+export interface FormattedMemoryIndex {
+  /** 注入用的正文；索引为空时为 ""。 */
+  text: string;
+  truncated: boolean;
+  lineCount: number;
+  characterCount: number;
+}
+
+export function formatMemoryIndexForInjection(raw: string): FormattedMemoryIndex {
+  const normalized = raw.replace(/^\uFEFF/u, "").replace(/\r\n/gu, "\n");
+  const withoutFrontmatter = normalized.replace(LEADING_FRONTMATTER_PATTERN, "");
+  const decorated = stripTopLevelHtmlComments(withoutFrontmatter);
+  return truncateMemoryIndex(decorated);
+}
+
+/** 只删代码围栏之外、行首就是 `<!--` 的顶层注释块（列表项/段落里的注释保留）。 */
+export function stripTopLevelHtmlComments(content: string): string {
+  if (!content.includes("<!--")) return content;
+  const lines = content.split("\n");
+  const out: string[] = [];
+  let fence: string | undefined;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    const trimmedStart = line.trimStart();
+    const fenceMatch = /^(`{3,}|~{3,})/u.exec(trimmedStart);
+    if (fenceMatch) {
+      if (fence === undefined) fence = fenceMatch[1]![0];
+      else if (trimmedStart.startsWith(fence.repeat(3))) fence = undefined;
+      out.push(line);
+      continue;
+    }
+    if (fence === undefined && trimmedStart.startsWith("<!--")) {
+      let end = index;
+      let closed = trimmedStart.includes("-->");
+      while (!closed && end + 1 < lines.length) {
+        end += 1;
+        if (lines[end]!.includes("-->")) closed = true;
+      }
+      if (closed) {
+        const closeIndex = lines[end]!.indexOf("-->");
+        const rest = lines[end]!.slice(closeIndex + 3);
+        index = end;
+        if (rest.trim().length > 0) out.push(rest);
+        continue;
+      }
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+export function truncateMemoryIndex(content: string): FormattedMemoryIndex {
+  const trimmed = content.trim();
+  if (trimmed.length === 0) {
+    return { text: "", truncated: false, lineCount: 0, characterCount: 0 };
+  }
+  const lines = trimmed.split("\n");
+  const lineCount = lines.length;
+  const characterCount = trimmed.length;
+  const lineTruncated = lineCount > INDEX_LINE_LIMIT;
+  const characterTruncated = characterCount > INDEX_CHARACTER_LIMIT;
+  if (!lineTruncated && !characterTruncated) {
+    return { text: trimmed, truncated: false, lineCount, characterCount };
+  }
+
+  let truncated = lineTruncated ? lines.slice(0, INDEX_LINE_LIMIT).join("\n") : trimmed;
+  if (truncated.length > INDEX_CHARACTER_LIMIT) {
+    const lastNewline = truncated.lastIndexOf("\n", INDEX_CHARACTER_LIMIT);
+    truncated = truncated.slice(0, lastNewline > 0 ? lastNewline : INDEX_CHARACTER_LIMIT);
+  }
+  const warning =
+    `> WARNING: the MEMORY.md index is too long (${lineCount} lines / ${characterCount} characters; ` +
+    `the injection limit is ${INDEX_LINE_LIMIT} lines / ${INDEX_CHARACTER_LIMIT} characters), so only the truncated part above was injected. ` +
+    `Shorten the index lines and move details into the fact files.`;
+  return {
+    text: `${truncated}\n\n${warning}`,
+    truncated: true,
+    lineCount,
+    characterCount,
+  };
+}
+
+/** 注入状态用的内容 hash（对注入正文取，保证"内容没变就不重注"）。 */
+export function memoryIndexHash(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}

package/src/index-file.ts

@@ -0,0 +1,171 @@
+/**
+ * `MEMORY.md` 索引行的维护。
+ *
+ * 索引由模型维护，我们只在 `memory_write` 时插入/更新对应的一行：
+ *   `- [标题](file.md) — 一句话钩子`
+ *
+ * 写前比对 revision（`mtime:<截断毫秒>:size:<字节>`）；不一致就重读重试一次，再失败报错让
+ * 模型重试——**不**静默覆盖别人的改动。这里不是跨进程锁，只是把"读-改-写"的窗口缩到最小；
+ * 跨进程的并发靠 revision 前进被发现，下一次写读到新内容后自己继续。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { atomicWriteFile } from "./atomic.ts";
+import { MemoryWriteError } from "./errors.ts";
+
+export const INDEX_FILENAME = "MEMORY.md";
+
+export interface IndexRevision {
+  /** `mtime:<截断毫秒>:size:<字节>`。 */
+  id: string;
+  mtimeMs: number;
+  sizeBytes: number;
+}
+
+export function revisionIdFromStat(stat: { mtimeMs: number; size: number }): string {
+  return `mtime:${Math.trunc(stat.mtimeMs)}:size:${stat.size}`;
+}
+
+export async function revisionOf(path: string): Promise<IndexRevision | undefined> {
+  try {
+    const info = await stat(path);
+    return { id: revisionIdFromStat(info), mtimeMs: info.mtimeMs, sizeBytes: info.size };
+  } catch (error) {
+    if (isNoEntryError(error)) return undefined;
+    throw error;
+  }
+}
+
+/** 两次 revision 是否一致；"之前不存在、现在也不存在"算一致。 */
+export function sameRevision(left: IndexRevision | undefined, right: IndexRevision | undefined): boolean {
+  if (left === undefined && right === undefined) return true;
+  if (left === undefined || right === undefined) return false;
+  return left.id === right.id;
+}
+
+export interface IndexLineInput {
+  /** 相对记忆目录的文件名（统一 `/`）。 */
+  filename: string;
+  title: string;
+  description: string;
+}
+
+export interface UpsertLineResult {
+  content: string;
+  action: "inserted" | "updated" | "unchanged";
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function indexLineOf(input: IndexLineInput): string {
+  const hook = input.description.replace(/\s+/gu, " ").trim();
+  const link = `- [${input.title}](${input.filename})`;
+  return hook.length > 0 ? `${link} — ${hook}` : link;
+}
+
+/**
+ * 插入或更新一行；已存在等价行时返回 `unchanged`（不写盘）。
+ * 若同一文件已有重复行，保留第一行位置、删掉其余，顺带修掉历史重复。
+ */
+export function upsertMemoryIndexLine(content: string, input: IndexLineInput): UpsertLineResult {
+  const line = indexLineOf(input);
+  const linkPattern = new RegExp(`\\]\\(\\s*${escapeRegExp(input.filename)}\\s*\\)`, "u");
+  const lines = content.length === 0 ? [] : content.split("\n");
+  let replaced = false;
+  let removedDuplicate = false;
+  const next: string[] = [];
+  for (const existing of lines) {
+    if (linkPattern.test(existing)) {
+      if (!replaced) {
+        next.push(line);
+        replaced = true;
+      } else {
+        removedDuplicate = true;
+      }
+      continue;
+    }
+    next.push(existing);
+  }
+  if (replaced) {
+    const updated = next.join("\n");
+    if (updated === content && !removedDuplicate) return { content, action: "unchanged" };
+    return { content: ensureTrailingNewline(updated), action: "updated" };
+  }
+  const base = content.length === 0 ? "" : ensureTrailingNewline(content);
+  return { content: `${base}${line}\n`, action: "inserted" };
+}
+
+function ensureTrailingNewline(content: string): string {
+  return content.endsWith("\n") ? content : `${content}\n`;
+}
+
+async function readIndexOrEmpty(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (isNoEntryError(error)) return "";
+    throw new MemoryWriteError("io", `Failed to read the index: ${path} (${describe(error)})`, "Retry later.");
+  }
+}
+
+export interface UpdateIndexOutcome {
+  indexPath: string;
+  action: "inserted" | "updated" | "unchanged";
+}
+
+export interface UpdateIndexOptions {
+  /** 测试注入：替换 revision 读取，用来确定性地演练"连续两次都读到改动"的失败路径。 */
+  revisionReader?: (path: string) => Promise<IndexRevision | undefined>;
+}
+
+/** 在 `<root>/MEMORY.md` 里插入/更新一行；revision 不一致时重读重试一次。 */
+export async function updateMemoryIndex(
+  root: string,
+  input: IndexLineInput,
+  options: UpdateIndexOptions = {},
+): Promise<UpdateIndexOutcome> {
+  const indexPath = join(root, INDEX_FILENAME);
+  const readRevision = options.revisionReader ?? revisionOf;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const before = await readRevision(indexPath);
+    const existing = await readIndexOrEmpty(indexPath);
+    const result = upsertMemoryIndexLine(existing, input);
+    if (result.action === "unchanged") {
+      return { indexPath, action: "unchanged" };
+    }
+    const now = await readRevision(indexPath);
+    if (!sameRevision(before, now)) {
+      // 读之后有人改过：这次结果作废，重读一次再试
+      continue;
+    }
+    await atomicWriteFile(indexPath, result.content).catch((error: unknown) => {
+      throw new MemoryWriteError(
+        "io",
+        `Failed to write the index: ${indexPath} (${describe(error)})`,
+        "Retry later.",
+      );
+    });
+    return { indexPath, action: result.action };
+  }
+  throw new MemoryWriteError(
+    "index_conflict",
+    `MEMORY.md was changed by another process after you read it (${indexPath}). The index was not written this time, so someone else's changes are not overwritten.`,
+    "Re-read the memory and retry this write.",
+  );
+}
+
+function isNoEntryError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/injection.ts

@@ -0,0 +1,82 @@
+/**
+ * 索引注入的纯决策部分：什么时候注入、会话里怎么重建"已注入"标记。
+ *
+ * 不 import pi；会话条目只按结构化字段读，便于 S1 单测。
+ */
+
+/** 会话标记条目的 customType（`pi.appendEntry` 写入，不进模型上下文）。 */
+export const INJECTED_ENTRY_TYPE = "zcode-memory/injected";
+
+/** 注入消息的 customType（`display: false` 的 custom 消息）。 */
+export const INDEX_MESSAGE_TYPE = "zcode-memory/index";
+
+/** 重建状态时只关心这些字段。 */
+export interface InjectionEntryLike {
+  type?: string;
+  customType?: string;
+  data?: unknown;
+  details?: unknown;
+}
+
+export interface InjectionDecisionInput {
+  messageType: "user" | "custom";
+  enabled: boolean;
+  injectIndex: boolean;
+  indexPresent: boolean;
+  /** 当前索引格式化后的 hash。 */
+  indexHash: string | undefined;
+  /** 当前会话里仍存活的注入 hash。 */
+  injectedHash: string | undefined;
+  /** `/memory reload` 置位。 */
+  force: boolean;
+}
+
+export type InjectionSkipReason =
+  | "disabled"
+  | "custom-run"
+  | "no-index"
+  | "already-injected";
+
+export type InjectionDecision =
+  | { inject: true; reason: "first" | "changed" | "reload" | "lost" }
+  | { inject: false; reason: InjectionSkipReason };
+
+export function decideInjection(input: InjectionDecisionInput): InjectionDecision {
+  if (!input.enabled || !input.injectIndex) return { inject: false, reason: "disabled" };
+  // `pi.sendMessage(..., { triggerTurn: true })` 起的运行不注入：那不是用户轮
+  if (input.messageType === "custom") return { inject: false, reason: "custom-run" };
+  if (!input.indexPresent || input.indexHash === undefined) return { inject: false, reason: "no-index" };
+  if (input.force) return { inject: true, reason: "reload" };
+  if (input.injectedHash === input.indexHash) return { inject: false, reason: "already-injected" };
+  if (input.injectedHash === undefined) return { inject: true, reason: "first" };
+  return { inject: true, reason: "changed" };
+}
+
+function hashOfMarkerData(data: unknown): string | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const value = (data as { indexHash?: unknown }).indexHash;
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * 从**当前上下文投影**的条目里重建"仍存活的注入 hash"。
+ *
+ * 传入的必须是 `buildSessionProjection()` 的条目（只包含压缩后的保留尾部）：注入消息被摘要掉
+ * 之后投影里就没有它了，调用方据此重新注入。标记条目与注入消息成对出现，缺一即视为丢失。
+ */
+export function rebuildInjectedHash(entries: readonly InjectionEntryLike[]): string | undefined {
+  const messageHashes = new Set<string>();
+  for (const entry of entries) {
+    if (entry.type !== "custom_message" || entry.customType !== INDEX_MESSAGE_TYPE) continue;
+    if (entry.details === undefined) continue;
+    const fromDetails = hashOfMarkerData(entry.details);
+    if (fromDetails !== undefined) messageHashes.add(fromDetails);
+  }
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index]!;
+    if (entry.type !== "custom" || entry.customType !== INJECTED_ENTRY_TYPE) continue;
+    const hash = hashOfMarkerData(entry.data);
+    if (hash !== undefined && messageHashes.has(hash)) return hash;
+  }
+  return undefined;
+}