为 ACP block 数据提供机器可读的对外契约（schemaVersion + ./contract 导出）

[tjp72]

下游 pi-billion-memory 目前只能 glob ~/.pi/agent/sessions/**/*.jsonl.acp.json 直接解析 sidecar 来读取 ACP 压缩块。这不是 bug，但绑死私有文件格式的代价是静默失效：字段改名或目录调整时下游会扫到 0 个文件而不报错，最后以「bcp 是不是改了格式」的 issue 形式回到你们这里。

请求很小，按成本从低到高，做到前三条就够；不要求任何行为变更，全部是加法：

1. R1（几分钟）：sidecar 顶层加 schemaVersion（+ producer），并约定「字段缺失 = v1」「未知版本 = 跳过 + 只记一次日志、不得改写」。
2. R2（成本≈0）：package.json 增加 "./contract" subpath 导出：BcpBlockV1 类型 + schema/bcp-block-v1.json（JSON Schema，可选 reader）。跨进程、跨重启都有效，且不需要事件通道。
3. R3（一句文档）：把「sidecar 用 tmp+rename 原子替换」写成承诺（代码已经是这个模式）。
4. R4（可选）：压缩成功落盘后 pi.events.emit("bcp:blocks", …)；明说它只覆盖同进程/同会话，文件仍是 source of truth。
5. R5（可选）：compress 的 details 若要做，请只放有界信息（如 {schemaVersion, acceptedIds, revision}）——details 会写进会话 .jsonl，整份 blocks 会在 sidecar 之外再抄一份。
6. P3（pi.appendEntry 写 custom entry）不是必须，可以以后再说。

背景

• bcp 是 pi 侧压缩的 owner：session_before_compact 返回 cancel: true，压缩由 ACP 完全接管，结果只写 <sessionFile>.acp.json。
• 下游需要这些块做跨会话检索（ACP 块 → SQLite FTS5 → memory_search / memory_expand）。块本身很有价值，但目前没有任何公开接口能拿到。
• 下游坚持零运行时依赖（dependencies: {}），并已把 bcp 声明为可选 peer（"billion-context-pi": ">=0.1.65"）——所以「类型 + schema」这种契约对双方都是最低成本。

现状（0.1.65 dist，可直接核验）

事实	核验方式
压缩由 bcp 接管	grep -o 'session_before_compact", () =>' dist/index.js、grep -o 'cancel: true' dist/index.js
只写 sidecar	grep -o 'STATE_SUFFIX = "[^"]*"' dist/index.js → .acp.json
canonical blocks 不对外	compress 工具结果全部是 details: void 0（dist/compress-tool.d.ts）
入口没有块类型	dist/index.d.ts 只导出 createAcpExtension；exports 只有 "."
没有事件、没有 custom entry	grep -c appendEntry dist/index.js → 0；.emit( → 0
读写无版本校验	dist/state.d.ts 只有 SessionStateStore / LiveRefOrigin 等内部类型
侧挂文件已原子写	writeFile(tmp, JSON.stringify({ ...state, liveRefOrigins }… + rename 模式，但没有对外承诺

旁证：isCompressSuccessText / isCompressNoopText（dist/compress-tool.d.ts）说明连 bcp 自己也要从工具结果的文本里判断成败——文本通道有损，而结构化通道目前不存在。README:216-236 已经把 sidecar 描述为用户可见产物并说明了 #299 的 replay 语义，但没有任何机器可读的版本/契约。

问题

1. 格式耦合：字段改名、路径调整、null 化 → 下游静默失效（扫到 0 文件或解析成 null），没有任何报错。
2. 没有版本标识：无法区分格式代际，只能「解析失败、下轮重试」，也就无法提示用户「升级下游」还是「升级 bcp」。
3. 没有权威数据：compress 的入参是模型产出的草案，最终落盘值可能被你们修正/拒绝；下游拿不到「最终被接受的那份」。
4. 变更没有通知渠道：上游发版后，下游只能靠用户反馈发现问题——而这批反馈往往会打回你们（对我们来说是多一个误报来源，对你们来说是噪音）。

请求（任选，不必全做）

R1 sidecar 顶层加版本标识（几分钟）

{
  "schemaVersion": 1,
  "producer": { "name": "billion-context-pi", "version": "<version>" },
  "blocks": [ /* ... */ ]
}

语义建议一并写进 README / CHANGELOG：

• 字段缺失 = schemaVersion: 1（否则现存 sidecar 全部变成「未知版本」）；
• 未知版本：下游应跳过并只记一次日志，不得改写文件；
• 只在破坏性变更时升版本，其余字段只增不改。

R2 ./contract subpath 导出（成本≈0，最耐久）

"exports": {
  ".":          { "types": "./dist/index.d.ts",     "import": "./dist/index.js" },
  "./contract": { "types": "./dist/contract.d.ts",  "import": "./dist/contract.js" }
}

contract 里只放三样东西：BcpBlockV1 类型、SCHEMA_VERSION 常量、schema/bcp-block-v1.json（JSON Schema）。零运行时依赖、跨进程、跨重启有效，比「承诺事件 payload 只增不改」维护成本低得多；下游可以直接对着 schema 跑校验和集成测试。

R3 把原子写写成承诺

现在的写入模式已经是 tmp+rename；请把它写进 README（或加一条测试）。下游的水位线（mtime/size）+ 整文件替换是绑定的，非原子写会让下游读到撕裂的 JSON。

R4 落盘成功后 emit 事件（可选）

pi.events.emit("bcp:blocks", {
  schemaVersion: 1,
  sessionId,
  sessionFile,
  cwd,
  revision,               // 单调递增（或落盘时间戳），供下游幂等/排序
  reason: "compress",     // compress | prune | ...
  added:   BcpBlock[],    // 本次新增
  updated: BcpBlock[],    // 本次变更（若有）
  removed: string[],      // 被替换/吞并的 blockId（若有）
});

• 建议在「保存成功之后」发出；增量语义维护成本高，就直接发全量 blocks 快照——下游只需要一个明确的「当前真相」；
• 但请写明边界：事件只能覆盖同进程、同会话，而 pbm 的价值在跨会话、可指向任意 sources root 的扫描。事件只是低延迟加成，文件仍是 source of truth。

R5 compress 的 details 若要做，请有界

pi 的 session format 里 toolResult message 带 details?（docs/session-format.md:94-98，:246 / :260 说明语义），也就是说 details 会落盘进会话文件。整份 blocks 放进去 = 在 sidecar 之外再抄一份大内容。建议只放 { schemaVersion, acceptedIds, revision } 这类有界引用，或干脆不做（R1/R2 已覆盖主要收益）。

P3（可选，以后再说）写 custom entry

pi.appendEntry("bcp.blocks", payload) + 下游 ctx.sessionManager.getEntries().filter(e => e.type === "custom" && e.customType === "bcp.blocks")。好处：由 pi 统一持久化、版本迁移、树管理，custom entry 不进 LLM 上下文（pi 文档 docs/extensions.md:1620）。代价：会话文件变大（每次压缩写一份，写放大），且跨会话回填仍要开别人的文件。

块的最小稳定字段（字段名可按你们习惯调整）

interface BcpBlockV1 {
  // --- stable core（建议只增不改）---
  blockId: string;              // 幂等键
  startId: string;
  endId: string;
  summary: string;
  topic?: string;
  // --- optional bag（允许缺失或改语义）---
  compressedTokens?: number;
  msgIds?: string[];
  refs?: string[];
  sourceSessionFile?: string;
  cwd?: string;
  createdAt?: string;           // ISO 8601
}

不需要暴露内部修剪/索引细节，只要「最终被接受的块」。

兼容性

• 以上全部是加法：不改 sidecar 位置、现有读写路径和 pi 集成行为；
• 下游按 blockId 幂等 upsert，文件扫描保留为历史回填；
• 若采纳 R2，建议在 CHANGELOG 承诺：BcpBlockV1 字段只增不改不删，破坏性变更升 schemaVersion。

相关 issue

• 会话迁移（export/import）丢失 .acp.json 状态与 parentSession，导入后会话失去全部压缩块 #299（会话迁移丢 .acp.json、replay 语义）
• 压缩成功也报告压缩范围,防止模型重复压缩同一个范围 #335（压缩成功也报告压缩范围）
• [feat] Persist nudge echoes as session entries (survive restarts, grep-able log) #326（persist nudge echoes as session entries）

它们和本 issue 指向同一个缺口：ACP 状态目前只有「私有文件格式」这一个出口。本 issue 只请求机器可读的版本/类型边界，不请求行为变更。

参考

• pi 文档：docs/extensions.md:1471（pi.appendEntry）、:1620（custom entry 不进 LLM 上下文）、:1729（pi.events）；docs/session-format.md:94-98（toolResult details）、:268（custom entry）、:410-413（SessionManager.appendCustomEntry 等）
• bcp README:216-236（sidecar 用途与 会话迁移（export/import）丢失 .acp.json 状态与 parentSession，导入后会话失去全部压缩块 #299 replay 语义）
• 下游现状：tjp72/pi-billion-memory 的 README 兼容性说明

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到，先给结论：R1+R2+R3 全做（都是加法、零行为变更），R4/R5/P3 按你说的「可选/以后再说」先不动。一句话：给 sidecar 加 schemaVersion+producer、新增 ./contract subpath（BcpBlockV1 类型 + SCHEMA_VERSION 常量 + schema/bcp-block-v1.json）、把 tmp+rename 原子写写成承诺。

审核（功能类，先评估再实现）：

• 合理性：成立。下游只靠 glob .acp.json 解析私有格式，字段改名/路径调整会静默扫到 0 文件不报错——版本标识 + 稳定类型边界是最低成本解法，且不改任何读写路径。
• 系统设计：契合。sidecar 写入只有一个收口点 SessionStateStore.save()（src/state.ts:103），所有 save（compress-tool.ts:379 / runtime.ts:433,465 / state-rebuild）都走它，改一处全覆盖；读取侧 load()/tryLoadParentState() 本就按字段宽松合并（mergeInitialState），加顶层字段是纯加法，不破坏任何现有读路径。
• 耦合性：不污染边界。contract 模块零运行时依赖、不进 pi 集成，跨进程跨重启有效。

实现前需要你确认的两个字段决策（你明确说了「字段名可按你们习惯调整」，我按真实落盘结构对齐，若不同意合并前可改，只是改类型/schema）：

1. 稳定核 = blockId / summary / tier / compressedTokens / createdAt（required）。我没有把 runId/directMessageIds/directBlockIds/survivedCount/generation/active 等内部修剪/索引字段放进契约（你说「不需要暴露内部细节」）。覆盖范围用可选的 startRef? / endRef?（模型可见 ref，如 m00005）+ effectiveMessageIds?（原始消息 id 集）。
2. createdAt 是 number（epoch 毫秒），不是 ISO 8601 字符串——这是 acp-kernel CompressionBlock.createdAt 的真实类型，schema 和类型都按 number 写并注释清楚。

R1 语义我会按你的建议写进 README/CHANGELOG：字段缺失=v1；未知高版本 bcp 侧「记一次日志 + 仍按已知字段宽松加载」（bcp 是生产者，downgrade 时丢状态比容忍更糟，真正「跳过不读」是下游义务）；只在破坏性变更升 schemaVersion，其余只增不改。

正在实现，PR 稍后贴这里。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 **PR 已开：https://github.com/ranxianglei/billion-context-pi/pull/369**（R1+R2+R3，纯加法、零行为变更；已 rebase 到当前 master v0.1.66 / acp-kernel 0.0.63）

一句话中文摘要：给 sidecar 加了 schemaVersion+producer 版本信封、新增 billion-context-pi/contract subpath（BcpBlockV1 类型 + SCHEMA_VERSION 常量 + schema/bcp-block-v1.json）、并把 tmp+rename 原子写写成 README 承诺——下游从此有稳定的机器可读边界，字段改名/路径调整会因版本不匹配而响亮失败而非静默扫到 0 文件。

落地内容：

• R1：sidecar 顶层信封 { schemaVersion, producer:{name,version} }，只在唯一收口点 SessionStateStore.save()（src/state.ts）写入。缺失=v1；未知高版本 bcp 侧宽松加载已知字段 + 每文件记一次 unknown-schema-version 日志（downgrade 可观测不丢状态）；仅破坏性变更升版本。
• R2：import { SCHEMA_VERSION, PRODUCER_NAME, BcpBlockV1, createSidecarEnvelope } from "billion-context-pi/contract"；schema/bcp-block-v1.json 随 npm 包发布（files 已加）。稳定核 required = blockId/summary/tier/compressedTokens/createdAt（epoch ms，非 ISO），可选 topic/startRef/endRef/effectiveMessageIds；内部修剪/索引字段不进契约（additionalProperties:true）。
• R3：README 记录原子写承诺（下游可用 mtime/size 做水位并整文件替换）。
• R4/R5/P3：按你「可选/以后再说」未做，需要我再跟进。

验证（rebase 到 v0.1.66 后全绿）：typecheck ✓ / npm test 700 pass·0 fail·3 skip ✓ / build ✓（产出 dist/contract.js+.d.ts，构建产物运行时冒烟通过）。新增测试 tests/contract.test.ts（schema↔类型漂移守卫 + 信封构造器）+ tests/state.test.ts 两例（信封落盘、高版本宽松加载）。

两个字段决策仍请你过目（不同意合并前改即可，只是类型/schema）：① 稳定核选了 tier+compressedTokens 且不含内部字段；② createdAt 用 number(epoch ms) 对齐真实结构。其余等你 review。

[ranxianglei]

这个对外导出如何使用的

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 用法（我在一个外部 consumer 里端到端跑通了，走的是真实 exports 门控，不是纸面 API）：

前提：./contract 和 ./schema/* 要等 #369 发布后的版本才有（master 已含，下个 release 生效）；你声明的 peer >=0.1.65 届时直接覆盖，无需改依赖。

① 主用法：import 常量/类型 + 按 schemaVersion 门控读 sidecar（这正是 R1+R2 给你的稳定边界——不再裸 glob 私有字段）：

import { promises as fs } from "node:fs";
import { SCHEMA_VERSION } from "billion-context-pi/contract";
import type { BcpBlockV1 } from "billion-context-pi/contract";

const SUPPORTED = new Set([SCHEMA_VERSION]); // 你的 reader 支持的版本

async function readBlocks(sessionFile: string): Promise<BcpBlockV1[]> {
  let raw: string;
  try { raw = await fs.readFile(sessionFile + ".acp.json", "utf8"); }
  catch (e) { if ((e as NodeJS.ErrnoException).code === "ENOENT") return []; throw e; } // 无 sidecar = 无块
  const d = JSON.parse(raw);
  const sv = typeof d.schemaVersion === "number" ? d.schemaVersion : 1; // 缺失 == v1
  if (!SUPPORTED.has(sv)) return [];                                     // 未知高版本 → 跳过，绝不改写
  return Array.isArray(d.blocks) ? d.blocks : [];
}

const blocks = await readBlocks("~/.pi/agent/sessions/<id>.jsonl");
for (const b of blocks) {
  // b.blockId(幂等键) / b.summary(检索文本) / b.tier / b.compressedTokens
  // b.createdAt = epoch 毫秒（不是 ISO！）
  // b.topic? / b.startRef? / b.endRef? / b.effectiveMessageIds?（覆盖的消息范围，供 memory_expand 定位）
  indexForFts(b.blockId, b.summary, b.topic ?? "");
}

② 可选：JSON Schema 校验（零依赖也能跑；想上 ajv 才需要它）——schema 文件现在可经子路径解析：

import { createRequire } from "node:module";
import { promises as fs } from "node:fs";
const require = createRequire(import.meta.url);
const p = require.resolve("billion-context-pi/schema/bcp-block-v1.json");
const schema = JSON.parse(await fs.readFile(p, "utf8")); // required: blockId,summary,tier,compressedTokens,createdAt

要点

• BcpBlockV1 是编译期类型（用 type import）；运行时只 import 值（SCHEMA_VERSION / PRODUCER_NAME / createSidecarEnvelope）。contract 模块零运行时依赖，跨进程/跨重启都有效。
• 版本语义：缺失=v1；未知高版本=跳过+记一次日志、不改写文件；文件仍是 source of truth。
• 顺手补了个小修：原先 schema/ 只进了 files 没进 exports，Node 会因 exports 白名单拒绝解析（ERR_PACKAGE_PATH_NOT_EXPORTED）。现已加 "./schema/bcp-block-v1.json" 子路径导出，上面 ② 的 require.resolve 才能跨包成功——已实测通过。PR feat(contract): machine-readable ACP block contract — schemaVersion + ./contract export (#368) #369 现为 2 个 commit（gate 仍全绿：typecheck ✓ / 700 pass·0 fail ✓ / build ✓）。

一句话：下游 import { SCHEMA_VERSION, BcpBlockV1 } from "billion-context-pi/contract"，读 sidecar 先比对 schemaVersion（缺失当 v1、不认识就跳过不碰），再把 blocks[] 当 BcpBlockV1[] 用即可；要严格校验就 resolve 那份 JSON Schema 喂给 ajv。

[ranxianglei]

这个是一个 sdk 而不是工具摄入磁盘文件？
sdk 要去适配很多东西 比如 pi 环境 这个都照顾不到。建议提供一个命令行工具 比如 acp export 这样的工具。可以导出压缩摘要文件，内核应该已经有了。分 json 格式和 markdown 格式。另外 billion-context 的应该是现成的。需要考虑提供一个统一的工具，尽量都能解析。
开工前需要分析 billion-context 和 billion-context pi 的差异
opencode-acp 也纳入但是可能又有新协议
综合评估

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到，按你说的「开工前先分析」办了。我把三个仓库 + acp-kernel 都拉下来实测了一遍（不是凭印象），给一份综合评估。这一轮只出评估、不动代码，末尾有 3 个要拍板的点。

一句话结论

方向对：SDK（#369 的 contract）和 CLI 是互补，不是替代。contract 解决「pi 侧 sidecar 有版本标识 + 权威类型」，但它确实照顾不到你说的「每个 host 的存储路径/包络都得下游自己知道」这块。一个统一的 acp export CLI 能把「发现文件 → 识别格式 → 版本门控 → 归一化 → 导出 json/md」全收进去，下游零适配。建议做，且建议放一个中立的新包里。

现状核实（实测）

内核「应该已经有了」——部分成立： acp-kernel 里有 markdown 渲染原语 renderHandoff()，还有 buildStatusReport / buildRecap / collectBlockContent。billion-context 已经拿 renderHandoff 包出了 bili export。缺的不是渲染，是跨 host 的文件发现 + 解析 + 归一化 + 独立 bin。

三个项目的落盘格式对比（关键差异点）：

	宿主	sidecar 文件名 / 目录	顶层 envelope	blockId	边界字段	原子写	已有导出	许可
billion-context-pi	pi	~/.pi/agent/sessions/<id>.jsonl.acp.json	{schemaVersion:1, producer:{name,version}, …state}（#369 起）	string	startRef?/endRef?	✅ tmp+rename	❌ 仅 contract	MIT
billion-context (bili)	任意(proxy)+pi/omp/opencode 插件	~/.local/share/billion-context/sessions/<proto>/<host>_<hash24>.json	{version:3, savedAt, id, payload:{state,…}}	string	startRef?/endRef?	✅ tmp+rename(debounce)	✅ bili export(md)	MIT
opencode-acp	opencode	~/.local/share/opencode/storage/plugin/acp/<sessionId>.json	PersistedSessionState{prune.messages…, lastUpdated(ISO)} 无版本号	number	startId/endId（必填）	❌ 普通 writeFile	✅ /acp export(md)	AGPL-3.0

核心判断

1. 概念核心一致：三家都有 blockId / summary / tier(1|2|3) / compressedTokens / createdAt(epoch-ms 数字) / effectiveMessageIds —— 归一化的地基是有的。
2. 分叉在三处：① 文件名/目录约定；② 顶层 envelope（pi 是扁平 schemaVersion+producer，bili 是 {version,savedAt,id,payload}，oacp 是无版本的富状态对象）；③ block 字段名与类型（oacp 把 startRef→startId、directBlockIds 拆成 included/consumed/parent 三个数组、blockId 是 number、另加约十几个去激活/工具 ID 记账字段）。
3. oacp 是离群点：它根本不是 acp-kernel 消费者（是 DCP 的加固 fork）、AGPL、非原子写。你的怀疑成立——它是「又一套新协议」。好消息：我们只读它的文件、不复用它的源码，AGPL 不会传染；代价是要单独维护一套解析启发式，且要容忍撕裂 JSON（因为它非原子写）。

统一 CLI 设计（acp export，建议形态）

• 输入：只读扫描三家已知目录（或接受显式路径/glob），非破坏、不改任何适配器行为。
• 识别+门控：按 envelope 签名判型（有 schemaVersion→pi；{version,payload}→bili；prune.messages→oacp），沿用 contract 语义——缺失当 v1、未知高版本跳过+只记一次日志、绝不改写源文件。
• 输出：--format json|md|both。JSON = 归一化块数组 + provenance（sourceHost/sourceFile/producerName/producerVersion）；MD = 人读摘要（复用 kernel renderHandoff 风格）。
• 容错：解析失败 / 撕裂文件 → 跳过 + 记日志，不中断整批。
• 归一化 schema：以 feat(contract): machine-readable ACP block contract — schemaVersion + ./contract export (#368) #369 的 BcpBlockV1 稳定核为基（blockId 强制 string，oacp 的 number 转字符串）+ provenance + 范围（startId/endId/effectiveMessageIds）。

需要拍板的 3 点（附我的倾向）

• D1 · 放哪？ 推荐 (A) 新中立包（如 acp-tools）：零依赖 node bin，自带各家解析器，不 import 三个适配器（只读它们的文件），避免把三方依赖耦合进来。(B) 塞进 acp-kernel 会污染它「平台无关」的边界（kernel 不该知道 ~/.pi/… 这类 host 路径）且它被 inline bundle、挂 bin 别扭；(C) 扩 bili export 能复用最省事，但会把 pi/opencode 用户绑到 bili 包和它的 proxy 框架上。→ 我推 A。
• D2 · oacp 进不进 v1？ 它格式最偏 + AGPL + 非原子，维护成本最高。你说纳入——我建议 v1 主干先做 pi + bili（同为 acp-kernel 形状，解析器共享、成本低），oacp 做成 best-effort reader（能读就读、读不了跳过记日志），不阻塞主线。确认这个切法？
• D3 · 输出默认值？ bili/oacp 各自已有 md 习惯。建议默认 both + 显式 --output，默认不覆盖已存在文件（防误删用户产物）。

拍完这 3 点我就开工。要不要我先按 A + D2 的切法出一版最小可用（扫 pi+bili → 归一化 json/md），oacp 留接口？