@zhushanwen/pi-session-reader 0.6.1 → 0.8.0

package/src/zcode-anchor-classify.ts

@@ -0,0 +1,74 @@
+/**
+ * [§3.5 entry 兜底归因] zcode subagent-record「在场但锚不完整」的缺失归因判定
+ *（classifyIncompleteEntryAnchor 的 entry 级纯逻辑提取；文件扫描与 readFile I/O
+ * 留在 tool-handler.ts）。零 I/O 纯函数，可完全单测。
+ *
+ * 判定与 entry-anchor.ts 的 zcodeAnchorOfEntry 双键判据同构（v1 快照 / v2 终态条
+ * 双版本门），协议字面量同值（写侧 subagent-core record-entry.ts
+ * SUBAGENT_RECORD_CUSTOM_TYPE，漂移由 entry-anchor.test.ts 守卫）。
+ */
+import type { Entry } from '@zhushanwen/session-core'
+import type { ZcodeAnchorMissingReason } from './discovery/zcode-manifest.js'
+
+/**
+ * v2 条目 data 的认识版本词表（W1 起 = 2）。与写侧 subagent-core
+ * SUBAGENT_RECORD_ENTRY_VERSION 同值——本地持有 + entry-anchor.test.ts 跨包断言
+ * 守卫漂移（生产依赖面不引 subagent-core，同 entry-anchor.ts 的协议字面量模式）。
+ */
+const SUBAGENT_RECORD_ENTRY_V2 = 2
+
+/**
+ * 目标 sa-id 的 zcode 形态 subagent-record data：type/customType/版本关/id/engine
+ * 全过才返回。版本关（W1 v2 学习，entry-anchor.ts zcodeAnchorOfEntry 同口径）：
+ * v1 全量快照（`d.v === 1`，兼容读面）或 v2 终态条（`d.v === 2` ∧
+ * `d.kind === 'settled'`——engineHandle 只在终态条，registered 不携带不归因）。
+ * engine 判别（D5）在此——`d.engine !== 'zcode'` 的记录（pi 形态：
+ * engine 缺省、sessionRef 无 dbPath）不是「zcode 锚不完整」，返回 undefined 跳过
+ * 不归因：误归因 missing-dbPath 会把「pi record 先于 manifest settle 落盘」的正常
+ * 窗口错报成 zcode_anchor_missing（旧版本产物指引不适用）；正确归因 = undefined
+ * → 上层落 zcode_record_not_found。
+ */
+function zcodeRecordDataOf(entry: Entry, saId: string): Record<string, unknown> | undefined {
+  if (entry.type !== 'custom' || entry.customType !== 'subagent-record') return undefined
+  const data: unknown = entry.data
+  if (typeof data !== 'object' || data === null) return undefined
+  const d = data as Record<string, unknown>
+  if (d.id !== saId) return undefined
+  if (d.v === SUBAGENT_RECORD_ENTRY_V2) {
+    if (d.kind !== 'settled') return undefined
+  } else if (d.v !== 1) {
+    return undefined
+  }
+  if (d.engine !== 'zcode') return undefined
+  return d
+}
+
+/** 已匹配 zcode record 的锚完整性链：返回第一个缺失键的归因；锚完整返回 undefined。 */
+function anchorMissingReasonOf(record: Record<string, unknown>): ZcodeAnchorMissingReason | undefined {
+  const handle = record.engineHandle
+  if (typeof handle !== 'object' || handle === null) return 'missing-engineHandle'
+  const ref = (handle as Record<string, unknown>).sessionRef
+  if (typeof ref !== 'object' || ref === null) return 'missing-sessionRef'
+  const r = ref as Record<string, unknown>
+  if (typeof r.sessionId !== 'string' || r.sessionId === '') return 'missing-sessionId'
+  if (typeof r.dbPath !== 'string' || r.dbPath === '') return 'missing-dbPath'
+  return undefined
+}
+
+/**
+ * entries 中第一条「在场但锚不完整」的 zcode subagent-record 的缺失归因；记录完全
+ * 不在场（或命中的记录锚全完整）返回 undefined。锚完整的命中不终止扫描——同 sa-id
+ * 多条记录时后续残缺记录仍可归因（与提取前的整循环行为一致）。
+ */
+export function firstIncompleteAnchorReason(
+  entries: readonly Entry[],
+  saId: string,
+): ZcodeAnchorMissingReason | undefined {
+  for (const entry of entries) {
+    const record = zcodeRecordDataOf(entry, saId)
+    if (record === undefined) continue
+    const reason = anchorMissingReasonOf(record)
+    if (reason !== undefined) return reason
+  }
+  return undefined
+}

package/src/__tests__/real-data.ts

@@ -1,96 +0,0 @@
-import { existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-/**
- * 真实 pi agent 数据常量 + 存在性探测（MF-1：CI 无本机 ~/.pi/agent 目录，
- * 依赖真实数据的用例必须 skipIf 守卫，否则 CI `pnpm extensions:test` 必红）。
- *
- * 用法：测试文件 `import { REAL_AGENT_DIR, HAS_E6 } from './real-data.js'`，
- * 真实数据用例套 `it.skipIf(!HAS_X)` / `describe.skipIf(!HAS_X)`；
- * fixture 用例保持无条件跑。
- *
- * 本文件无 .test.ts 后缀，vitest include 只收集 `src/__tests__/` 下以 .test.ts 结尾的文件，不收集本文件。
- */
-
-/** 真实 pi agent 目录（pi 官方家目录布局，随宿主 homedir 推导），用于集成测试。 */
-export const REAL_AGENT_DIR = join(homedir(), '.pi', 'agent')
-
-/**
- * 全量扫描类真实数据用例的统一超时标定（90s）。
- *
- * 这类用例遍历本机 ~/.pi/agent 全量会话语料（实测 4600+ 文件），空载单用例已需 6-10s；
- * 38 包并行全量测试时 CPU/IO 争抢可降速 3-4 倍，30s 标定必假红。90s ≈ 空载 9 倍余量，
- * 仍能兜住真正的挂死。仅用于遍历全量语料的用例（findSessions / buildFamilyFromFs /
- * resolveSessionRoots 等）；读已知单文件的用例不需要放宽。
- */
-export const REAL_DATA_TIMEOUT_MS = 90_000
-
-/** 5.4MB / 32 turn / 1204 entry 的真实 session（feat-plugin-arch-3 目录）。 */
-export const E6 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'
-/** 真实 fork 家族根（fork 子代 019fe632，隔代 subagent 019fe635 挂在 019fe632 下）。 */
-export const FAM = '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7'
-
-/**
- * E6 的完整文件路径（parser/turns/render 直接 parseSessionFile 用）。
- * 按 sid 运行时定位而非硬编码宿主 workspace 目录名：真实文件挂在哪个 slug 目录随采集机器而异，
- * 硬编码会绑死本机路径形态；定位不到时回落相对布局，由下方 HAS_REAL_SESSION 守卫 skip。
- */
-export const REAL_SESSION = (() => {
-  const fallback = join(REAL_AGENT_DIR, 'sessions', `2026-05-28T03-17-12-844Z_${E6}.jsonl`)
-  if (!existsSync(REAL_AGENT_DIR)) return fallback
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions -name '*${E6}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim() || fallback
-    )
-  } catch {
-    return fallback
-  }
-})()
-
-/** 同步探测真实 session 文件是否存在（不存在则 skip，避免在无该数据的机器上硬失败）。 */
-export function hasRealSession(sid: string): boolean {
-  if (!existsSync(REAL_AGENT_DIR)) return false
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions -name '*${sid}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim().length > 0
-    )
-  } catch {
-    return false
-  }
-}
-
-/**
- * 同步探测真实数据中任意 session 文件存在（main sessions/ 与 subagents/ 双目录）。
- * 与 hasRealSession 的区别：subagent session 文件位于 subagents/<cwd>/sessions/ 下，
- * hasRealSession 只扫主 sessions/ 目录扫不到。用于对活跃数据目录中具体文件（如 fork
- * 子代/隔代 subagent）存在性的守卫探测。
- */
-export function hasAnyRealSession(fragment: string): boolean {
-  if (!existsSync(REAL_AGENT_DIR)) return false
-  try {
-    return (
-      execSync(
-        `find ${REAL_AGENT_DIR}/sessions ${REAL_AGENT_DIR}/subagents -name '*${fragment}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
-        { encoding: 'utf8' },
-      ).trim().length > 0
-    )
-  } catch {
-    return false
-  }
-}
-
-export const HAS_REAL_AGENT_DIR = existsSync(REAL_AGENT_DIR)
-export const HAS_REAL_SUBAGENTS_DIR = existsSync(join(REAL_AGENT_DIR, 'subagents'))
-export const HAS_REAL_SESSION = existsSync(REAL_SESSION)
-export const HAS_E6 = hasRealSession(E6)
-export const HAS_FAM = hasRealSession(FAM)
-/** tool-handler 的 handleSessionRead 套件同时依赖 E6 + FAM。 */
-export const HAS_REAL = HAS_E6 && HAS_FAM

package/src/core/parser.ts

@@ -1,167 +0,0 @@
-import { readFile } from 'node:fs/promises'
-
-/**
- * session JSONL 文件解析后的单行 entry（冻结接口，M2-M5 契约）。
- *
- * 字段对齐 pi session JSONL 各 type 的 payload：
- * - type / id / parentId：树结构字段。root（session header）在文件里无 parentId，
- *   归一化为 null（design §3.5 算法 2 的 root 判定依据）。
- * - message：仅 type=message（role/content/toolCalls）。
- *   toolName/toolCallId：仅 role=toolResult 的 message 透出（probe 实测 515/515 带，
- *   O2/O3 据此精确关联同 turn 内 toolCall 取参数，替代 v1 脆弱的顺序关联）。
- * - customType / data：仅 type=custom。
- * - parentSession / cwd：仅 type=session；parentSession 是 fork 文件指向来源的路径指针。
- * - summary：仅 type=compaction。
- *
- * 注：冻结接口未列的 per-type 附加字段（如 model_change.provider、
- * compaction.firstKeptEntryId、session.version）不在此暴露——M2+ 若需消费，
- * 扩展 Entry 接口并同步 design.md §3.4，不在 parser 层私自保留。
- */
-export interface Entry {
-  type: string
-  id: string
-  parentId: string | null
-  timestamp?: string
-  message?: {
-    role: 'user' | 'assistant' | 'toolResult'
-    content: unknown
-    toolCalls?: unknown[]
-    /** toolResult 的工具名（probe 实测 515/515 带，仅 role=toolResult 时存在） */
-    toolName?: string
-    /** toolResult 关联的 toolCall.id（probe 实测 515/515 全部匹配 toolCall.id） */
-    toolCallId?: string
-  }
-  customType?: string
-  data?: unknown
-  parentSession?: string
-  cwd?: string
-  summary?: unknown
-}
-
-export interface ParseResult {
-  entries: Entry[]
-  /** JSON 解析失败（含缺必填结构字段）的行数 */
-  skippedLines: number
-  totalBytes: number
-  /** 最后一行疑似半行（活跃 session 写入中），区别于中间坏行 */
-  lastLinePartial: boolean
-}
-
-function isMessageRole(v: unknown): v is 'user' | 'assistant' | 'toolResult' {
-  return v === 'user' || v === 'assistant' || v === 'toolResult'
-}
-
-/**
- * 归一化 message 字段（阶段 helper：role 经值守卫收窄，缺/非法 role 时
- * 返回 undefined，调用方丢弃 message 字段——接口 role 必填）。
- */
-function parseEntryMessage(raw: unknown): Entry['message'] | undefined {
-  if (raw === null || typeof raw !== 'object') return undefined
-  const m = raw as Record<string, unknown>
-  if (!isMessageRole(m.role)) return undefined
-  const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
-  if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
-  // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
-  if (typeof m.toolName === 'string') message.toolName = m.toolName
-  if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
-  return message
-}
-
-/** 归一化剩余可选字段（阶段 helper：customType/data/parentSession/cwd/summary）。 */
-function assignOptionalFields(obj: Record<string, unknown>, entry: Entry): void {
-  if (typeof obj.customType === 'string') entry.customType = obj.customType
-  if (obj.data !== undefined) entry.data = obj.data
-  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
-  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
-  if (obj.summary !== undefined) entry.summary = obj.summary
-}
-
-/**
- * 把单个已 JSON.parse 成功的原始对象归一化为 Entry。
- * 缺必填结构字段（type/id）返回 undefined，调用方计为坏行（skippedLines++）。
- */
-function toEntry(raw: unknown): Entry | undefined {
-  if (typeof raw !== 'object' || raw === null) return undefined
-  const obj = raw as Record<string, unknown>
-  if (typeof obj.type !== 'string') return undefined
-
-  // id 解析：pi appendCustomEntry 恒写顶层 id（session-manager.js:820-828）——
-  // 无需 fallback。data.id 是扩展业务字段（如 subagent-identity payload），不是 entry id。
-  // [W4 删除] 原 data.id fallback 分支对 pi 写出的 entry 是死分支（对历史/异构文件
-  // 也无必要——entry id 语义以顶层为准）。
-  const id: unknown = obj.id
-  if (typeof id !== 'string') return undefined
-
-  const entry: Entry = {
-    type: obj.type,
-    id: id as string,
-    parentId: typeof obj.parentId === 'string' ? obj.parentId : null,
-  }
-  if (typeof obj.timestamp === 'string') entry.timestamp = obj.timestamp
-
-  const message = parseEntryMessage(obj.message)
-  if (message !== undefined) entry.message = message
-
-  assignOptionalFields(obj, entry)
-
-  return entry
-}
-
-/**
- * 解析 session JSONL 文本为 entries。
- *
- * 逐行 JSON.parse，坏行（语法错误或缺必填结构字段）计入 skippedLines 并跳过，
- * 不中断整体解析——pi 坏 session 容错（design §2 失败模式）。
- *
- * 末尾换行产生的空行忽略（不计 skipped、不计 partial）。最后一行 parse 失败时
- * lastLinePartial=true（活跃 session 写到一半的半行），区别于中间坏行。
- */
-export function parseSessionContent(content: string): ParseResult {
-  const entries: Entry[] = []
-  let skippedLines = 0
-  let lastLinePartial = false
-
-  const lines = content.split('\n')
-  // 移除末尾因 trailing newline 产生的空行（非真实行）
-  while (lines.length > 0 && lines[lines.length - 1] === '') {
-    lines.pop()
-  }
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]
-    const isLast = i === lines.length - 1
-
-    // 中间空行容错：pi 正常 jsonl 无空行，防御文件损坏；不计 skipped
-    if (line.trim() === '') continue
-
-    let raw: unknown
-    try {
-      raw = JSON.parse(line)
-    } catch {
-      skippedLines++
-      if (isLast) lastLinePartial = true
-      continue
-    }
-
-    const entry = toEntry(raw)
-    if (entry === undefined) {
-      skippedLines++
-      if (isLast) lastLinePartial = true
-      continue
-    }
-    entries.push(entry)
-  }
-
-  return {
-    entries,
-    skippedLines,
-    totalBytes: Buffer.byteLength(content, 'utf8'),
-    lastLinePartial,
-  }
-}
-
-/** 读取 session 文件并解析。文件不存在按 Node fs 原生错误抛出（ENOENT）。 */
-export async function parseSessionFile(filePath: string): Promise<ParseResult> {
-  const content = await readFile(filePath, 'utf8')
-  return parseSessionContent(content)
-}