@zhushanwen/pi-session-reader 0.13.3 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -16,16 +16,16 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.26.0",
-    "@zhushanwen/pi-ext-guards": "0.5.0",
+    "@zhushanwen/pi-ext-guards": "0.5.1",
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/session-core": "0.12.0",
-    "@zhushanwen/zcode-session-source": "0.2.9"
+    "@zhushanwen/extension-protocol": "0.27.0",
+    "@zhushanwen/session-core": "0.13.0",
+    "@zhushanwen/zcode-session-source": "0.2.10"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "2.1.2"
+    "@zhushanwen/subagent-core": "2.2.0"
   },
   "files": [
     "index.ts",

package/src/__tests__/parser.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest'
 import { mkdtemp, writeFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { parseSessionContent, parseSessionFile, type Entry } from '@zhushanwen/session-core'
+import { parseSessionContent, parseSessionFile, UnknownMessageRoleError, type Entry } from '@zhushanwen/session-core'
 
 /** 构造单行 JSONL entry 字符串 */
 function line(obj: Record<string, unknown>): string {
@@ -22,7 +22,6 @@ describe('parseSessionContent', () => {
     const result = parseSessionContent(content)
 
     expect(result.skippedLines).toBe(0)
-    expect(result.lastLinePartial).toBe(false)
     expect(result.entries).toHaveLength(5)
 
     const [s, u, a, c, custom] = result.entries
@@ -69,29 +68,25 @@ describe('parseSessionContent', () => {
     expect(result.entries[0].id).toBe('a')
     expect(result.entries[1].id).toBe('b')
     expect(result.skippedLines).toBe(1)
-    // 最后一行解析成功 → 非 partial
-    expect(result.lastLinePartial).toBe(false)
   })
 
-  it('空字符串：entries 为空，skippedLines=0，非 partial', () => {
+  it('空字符串：entries 为空，skippedLines=0', () => {
     const result = parseSessionContent('')
 
     expect(result.entries).toEqual([])
     expect(result.skippedLines).toBe(0)
-    expect(result.lastLinePartial).toBe(false)
     expect(result.totalBytes).toBe(0)
   })
 
-  it('末尾换行不产生幽灵行（不计 skipped/partial）', () => {
+  it('末尾换行不产生幽灵行（不计 skipped）', () => {
     const content = line({ type: 'message', id: 'a', parentId: null }) + '\n'
     const result = parseSessionContent(content)
 
     expect(result.entries).toHaveLength(1)
     expect(result.skippedLines).toBe(0)
-    expect(result.lastLinePartial).toBe(false)
   })
 
-  it('最后一行是半 JSON：lastLinePartial=true，仍计入 skippedLines', () => {
+  it('最后一行是半 JSON：仍计入 skippedLines', () => {
     const content =
       line({ type: 'message', id: 'a', parentId: null }) + '\n' + '{"type":"message","id":"x"'
     const result = parseSessionContent(content)
@@ -99,7 +94,6 @@ describe('parseSessionContent', () => {
     expect(result.entries).toHaveLength(1)
     expect(result.entries[0].id).toBe('a')
     expect(result.skippedLines).toBe(1)
-    expect(result.lastLinePartial).toBe(true)
   })
 
   it('JSON 合法但缺必填结构字段（type/id）视为坏行', () => {
@@ -114,8 +108,6 @@ describe('parseSessionContent', () => {
     expect(result.entries).toHaveLength(1)
     expect(result.entries[0].id).toBe('ok')
     expect(result.skippedLines).toBe(2)
-    // 最后那条坏行也是最后一行 → partial
-    expect(result.lastLinePartial).toBe(true)
   })
 
   it('custom entry 无顶层 id → 坏行跳过（W4：data.id fallback 死分支已删，pi appendCustomEntry 恒写顶层 id）', () => {
@@ -144,23 +136,29 @@ describe('parseSessionContent', () => {
     expect(result.entries[0].parentId).toBeNull()
   })
 
-  it('message 缺/非法 role → 丢弃 message 字段但保留 entry', () => {
+  it('message 非法/缺失 role → 整文件解析抛 UnknownMessageRoleError（fail-fast 不静默丢内容）', () => {
     // role 样本用词表外的值（'bot'）——'system' 已随 pi 1.0 四值词表放行（session-core D9①）
     const content = [
       line({ type: 'message', id: 'm1', parentId: null, message: { role: 'bot', content: 'x' } }),
-      line({ type: 'message', id: 'm2', parentId: null, message: { content: 'x' } }),
     ].join('\n')
 
-    const result = parseSessionContent(content)
+    expect(() => parseSessionContent(content)).toThrow(UnknownMessageRoleError)
+    expect(() => parseSessionContent(content)).toThrow(/第 1 行.*"bot"/)
 
-    expect(result.entries).toHaveLength(2)
+    // message 存在但缺失 role 同样 fail-fast（role 不在词表）
+    const missingRole = line({ type: 'message', id: 'm2', parentId: null, message: { content: 'x' } })
+    expect(() => parseSessionContent(missingRole)).toThrow(UnknownMessageRoleError)
+
+    // message 键整体缺省照常产出 entry（无 message 结构可校验）
+    const noMessage = line({ type: 'message', id: 'm3', parentId: null })
+    const result = parseSessionContent(noMessage)
+    expect(result.entries).toHaveLength(1)
     expect(result.entries[0].message).toBeUndefined()
-    expect(result.entries[1].message).toBeUndefined()
   })
 })
 
 describe('parseSessionFile', () => {
-  it('磁盘文件全量解析：entries 数 = 行数 / 0 skipped / 非 partial / totalBytes 与内容一致', async () => {
+  it('磁盘文件全量解析：entries 数 = 行数 / 0 skipped / totalBytes 与内容一致', async () => {
     // mkdtemp 自建自删的 fixture 文件（不读本机真实数据目录）：session header +
     // 10 条链式 message 的最小行集，验证「文件读取 → 逐行解析」回路的完整性与计数字段
     const dir = await mkdtemp(join(tmpdir(), 'parser-file-'))
@@ -187,7 +185,6 @@ describe('parseSessionFile', () => {
 
       expect(result.entries).toHaveLength(11)
       expect(result.skippedLines).toBe(0)
-      expect(result.lastLinePartial).toBe(false)
       expect(result.totalBytes).toBe(Buffer.byteLength(content, 'utf8'))
     } finally {
       await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })

package/src/discovery/entry-anchor.ts

@@ -100,31 +100,28 @@ function extractZcodeSessionRefAnchor(engineHandle: unknown): ZcodeAnchor | unde
  * 多候选文件：按候选列表顺序逐文件扫，文件内有命中锚（含末条裁决后）即止——
  * 候选顺序 = 调用方声明的优先级（liveSessionDir 优先），不跨文件合并。
  *
- * 行级容错：逐行解析由基座 parseSessionContent 承担（坏行跳过继续、末行半行记
- * lastLinePartial 不中断）——best-effort，不因一行坏 JSON 失败整文件。
+ * 行级容错：坏行（非法 JSON/缺 type/id）由基座 parseSessionContent 跳过继续；message
+ * 存在但 role 不在词表时基座整文件解析抛 UnknownMessageRoleError（fail-fast，不静默
+ * 丢内容）——readParsedEntriesBestEffort 把两类读失败（IO / 解析 fail-fast）统一收敛为
+ * undefined，候选跳过。
  *
- * 候选文件读失败（不存在/不可读）= 该候选无命中，跳过继续下一候选；本函数契约
- * 是「锚或 not-found」，IO 错误同样收敛到 not-found 信号（调用方映射错误码），
+ * 候选文件读失败（不存在/不可读/解析 fail-fast）= 该候选无命中，跳过继续下一候选；
+ * 本函数契约是「锚或 not-found」，IO 错误同样收敛到 not-found 信号（调用方映射错误码），
  * 不向上抛。
  *
  * 读取用 node:fs/promises 的 async readFile——本函数跑在 pi 扩展进程内，同步
  * readFileSync 全文读入会阻塞事件循环（同函数族 classifyIncompleteEntryAnchor
  * 同形态；对照 readSessionHeaderIdSync 只在首行 4KB 有界读时才允许同步）。
  *
- * @returns 命中的锚；所有候选均未命中（或全部候选不可读）→ undefined（not-found 信号）
+ * @returns 命中的锚；所有候选均未命中（或全部候选不可读/解析失败）→ undefined（not-found 信号）
  */
 export async function findZcodeEntryAnchor(
   candidateFiles: readonly string[],
   saId: string,
 ): Promise<ZcodeAnchor | undefined> {
   for (const file of candidateFiles) {
-    let content: string
-    try {
-      content = await readFile(file, 'utf8')
-    } catch {
-      continue
-    }
-    const { entries } = parseSessionContent(content)
+    const entries = await readParsedEntriesBestEffort(file)
+    if (entries === undefined) continue
     let anchor: ZcodeAnchor | undefined
     for (const entry of entries) {
       const hit = zcodeAnchorOfEntry(entry, saId)
@@ -134,3 +131,23 @@ export async function findZcodeEntryAnchor(
   }
   return undefined
 }
+
+/**
+ * 读 session 文件并解析为 entries 的 best-effort 形态：读取失败（不存在/不可读）或
+ * 解析 fail-fast（message 存在但 role 不在词表等）都返回 undefined——候选扫描语境的
+ * 容错读（失败候选不贡献结果）；需要显式报错的主读链不走本函数（tool-handler
+ * safeParse 把解析错误转为带 👉 的工具错误）。
+ */
+export async function readParsedEntriesBestEffort(file: string): Promise<Entry[] | undefined> {
+  let content: string
+  try {
+    content = await readFile(file, 'utf8')
+  } catch {
+    return undefined
+  }
+  try {
+    return parseSessionContent(content).entries
+  } catch {
+    return undefined
+  }
+}

package/src/tool-handler.ts

@@ -46,7 +46,11 @@ import {
 } from './discovery/archive-match.js'
 import { resolveSessionRoots } from './discovery/roots.js'
 import { readSessionHeaderIdSync } from './discovery/session-header.js'
-import { findZcodeEntryAnchor, type ZcodeAnchor } from './discovery/entry-anchor.js'
+import {
+  findZcodeEntryAnchor,
+  readParsedEntriesBestEffort,
+  type ZcodeAnchor,
+} from './discovery/entry-anchor.js'
 import {
   listZcodeManifests,
   readZcodeManifest,
@@ -59,11 +63,7 @@ import {
   type RecordManifest,
 } from './discovery/subagents.js'
 import { readRunSnapshot, resolveWorkflows } from './discovery/workflows.js'
-import {
-  parseSessionContent,
-  parseSessionFile,
-  type ParseResult,
-} from '@zhushanwen/session-core'
+import { parseSessionFile, type ParseResult } from '@zhushanwen/session-core'
 import { parseRunRecordStream, parseRunSnapshot, renderWorkflowOverview, type WorkflowOverview } from './core/workflow.js'
 import { buildTreeView } from './core/tree.js'
 import { segmentTurns } from './core/turns.js'
@@ -358,13 +358,11 @@ async function classifyIncompleteEntryAnchor(
   saId: string,
 ): Promise<ZcodeAnchorMissingReason | undefined> {
   for (const file of candidateFiles) {
-    let content: string
-    try {
-      content = await readFile(file, 'utf8')
-    } catch {
-      continue
-    }
-    const reason = firstIncompleteAnchorReason(parseSessionContent(content).entries, saId)
+    // 读取/解析失败（含非法 message role 的 fail-fast 抛错）按候选跳过：归因分类是
+    // best-effort 附加信息，最终 not-found 错误仍由调用方显式抛出
+    const entries = await readParsedEntriesBestEffort(file)
+    if (entries === undefined) continue
+    const reason = firstIncompleteAnchorReason(entries, saId)
     if (reason !== undefined) return reason
   }
   return undefined
@@ -566,7 +564,7 @@ async function loadZcodeParsed(anchor: ZcodeAnchor, agentDir: string): Promise<P
     }
     // ParseResult 形状对齐：zcode 库读无「文件字节/坏行」概念（strict Entry 树已由
     // converter 保证），totalBytes/skippedLines 恒 0
-    return { entries: normalized.entries, totalBytes: 0, skippedLines: 0, lastLinePartial: false }
+    return { entries: normalized.entries, totalBytes: 0, skippedLines: 0 }
   } catch (e) {
     if (e instanceof Error && e.message.startsWith('[zcode_')) throw e // 本函数产出的错误范围原样传播
     throw err(zcodeReadErrorMessage(e, agentDir))