@zhushanwen/pi-session-reader 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -16,15 +16,15 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-ext-guards": "0.4.2",
-    "@zhushanwen/zcode-session-source": "0.2.4",
-    "@zhushanwen/session-core": "0.11.0"
+    "@zhushanwen/pi-extension-logger": "0.6.2",
+    "@zhushanwen/pi-ext-guards": "0.4.3",
+    "@zhushanwen/zcode-session-source": "0.2.5",
+    "@zhushanwen/session-core": "0.12.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "1.2.1"
+    "@zhushanwen/subagent-core": "1.3.0"
   },
   "files": [
     "index.ts",
@@ -32,10 +32,10 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-ai": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
-    "typebox": "*"
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
+    "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/__tests__/parser.test.ts

@@ -145,8 +145,9 @@ describe('parseSessionContent', () => {
   })
 
   it('message 缺/非法 role → 丢弃 message 字段但保留 entry', () => {
+    // role 样本用词表外的值（'bot'）——'system' 已随 pi 1.0 四值词表放行（session-core D9①）
     const content = [
-      line({ type: 'message', id: 'm1', parentId: null, message: { role: 'system', content: 'x' } }),
+      line({ type: 'message', id: 'm1', parentId: null, message: { role: 'bot', content: 'x' } }),
       line({ type: 'message', id: 'm2', parentId: null, message: { content: 'x' } }),
     ].join('\n')
 

package/src/__tests__/render.test.ts

@@ -226,6 +226,81 @@ describe('renderOutline', () => {
     // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）
     expect(result.stats.totalEntries).toBeGreaterThan(0)
   })
+
+  // ---- D9② 占位行折叠：纯记录条目 turn 不产 outline 行、不占轮次 ----
+
+  function recEntry(id: string, type: string): Entry {
+    // pi 1.0 纯记录条目形态（usage/session_info/model_change 等，无 message 字段）
+    return { type, id, parentId: null }
+  }
+
+  function sysEntry(id: string): Entry {
+    // pi 1.0 system 消息（role=system，工具集变更高频追加）——非对话轴，随折叠
+    return { type: 'message', id, parentId: null, message: { role: 'system', content: 'sys' } }
+  }
+
+  it('9. D9② 纯记录条目 turn 折叠：不产行、totalTurns 只数对话轮，对话 turn 的 T 序号保留原 index', () => {
+    const turns = [
+      turn(0, [recEntry('MC', 'model_change'), recEntry('TL', 'thinking_level_change')]),
+      turn(1, [uEntry('U1', 'first question')], { userEntry: uEntry('U1', 'first question') }),
+      turn(2, [recEntry('US', 'usage')]),
+      turn(3, [uEntry('U2', 'second question')], { userEntry: uEntry('U2', 'second question') }),
+    ]
+    const result = renderOutline(turns, emptyTree(), { budget: 2000 })
+
+    // 记录 turn（0/2）折叠：行只剩两个对话 turn
+    expect(result.turns).toHaveLength(2)
+    expect(result.lines).toHaveLength(2)
+    expect(result.stats.totalTurns).toBe(2)
+    // T 序号 = 原 turn.index（expand/detail 的入口地址稳定，折叠不重编号）
+    expect(result.turns.map((b) => b.index)).toEqual([1, 3])
+    // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据面）：2+1+1+1 = 5
+    expect(result.stats.totalEntries).toBe(5)
+  })
+
+  it('10. D9② system 消息与 custom 审计条目同折叠；custom_message 参与对话流保留', () => {
+    const turns = [
+      turn(0, [sysEntry('S1'), recEntry('C1', 'custom')]),
+      turn(1, [uEntry('U1', 'q')], { userEntry: uEntry('U1', 'q') }),
+    ]
+    const result = renderOutline(turns, emptyTree(), { budget: 2000 })
+    expect(result.turns).toHaveLength(1)
+    expect(result.stats.totalTurns).toBe(1)
+
+    const cm: Entry = { type: 'custom_message', id: 'CM', parentId: null, customType: 'plan-context', content: 'prompt' }
+    const withCm = renderOutline([turn(0, [cm]), turn(1, [uEntry('U1', 'q')], { userEntry: uEntry('U1', 'q') })], emptyTree(), { budget: 2000 })
+    expect(withCm.turns).toHaveLength(2)
+  })
+
+  it('11. D9② entry 粒度同谓词：纯记录条目不产行，entryIdx 只数对话条目', () => {
+    const turns = [
+      turn(0, [recEntry('MC', 'model_change'), uEntry('U0', 'a')], { userEntry: uEntry('U0', 'a') }),
+      turn(1, [recEntry('US', 'usage')]),
+    ]
+    const result = renderOutline(turns, emptyTree(), { granularity: 'entry', budget: 2000 })
+    expect(result.turns).toHaveLength(1)
+    expect(result.turns[0]?.userBrief).toBe('a')
+  })
+
+  it('12. D9② branch_summary 归纯记录折叠：前置 turn 成 turn 不产行（pi 1.0 纯记录类）', () => {
+    // pi 1.0 dist branchWithSummary 落盘形态：{type:'branch_summary', id, parentId, fromId,
+    // summary, details, usage, fromHook}，无 message 字段。归类 = 纯记录（分叉操作痕迹，
+    // 非当前路径对话内容；taiji 无消息编辑入口不产生该形态）
+    const bs: Entry = { type: 'branch_summary', id: 'BS', parentId: null, summary: 'original path digest' }
+    const turns = [
+      turn(0, [bs]),
+      turn(1, [uEntry('U1', 'new branch question')], { userEntry: uEntry('U1', 'new branch question') }),
+    ]
+    const result = renderOutline(turns, emptyTree(), { budget: 2000 })
+    // 折叠：前置 turn 不产行，outline 只剩新路径对话 turn
+    expect(result.turns).toHaveLength(1)
+    expect(result.lines).toHaveLength(1)
+    expect(result.stats.totalTurns).toBe(1)
+    // T 序号保留原 turn.index（expand/detail 入口地址稳定）
+    expect(result.turns.map((b) => b.index)).toEqual([1])
+    // 字节/条目统计保持全量口径：BS + U1 = 2
+    expect(result.stats.totalEntries).toBe(2)
+  })
 })
 
 describe('renderExpand', () => {

package/src/__tests__/session-command.test.ts

@@ -198,7 +198,7 @@ describe('createSessionCommand - handler select 流程', () => {
     listAllSpy.mockRestore()
   })
 
-  it('MF-2 回归：同 cwd 同预览同 age 桶 → label 带短 uuid 后缀消歧，选第 2 条插第 2 条 uuid', async () => {
+  it('MF-2 回归：同 cwd 同预览同 age 桶 → label 带短 uuid 后缀消歧，选中哪条插哪条 uuid', async () => {
     // 两 session：相同首消息 + 相同 timestamp（同 age 桶）→ toCandidate label 完全相同
     const ID1 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'
     const ID2 = '019fffff-1111-2222-3333-444455556666'
@@ -207,15 +207,24 @@ describe('createSessionCommand - handler select 流程', () => {
 
     const cmd = createSessionCommand(() => cwdSessionDir)
     const { ctx, select, setEditorText } = makeFakeCtx()
-    // 用户选第 2 条（label 数组下标 1）
-    select.mockImplementation(async (_title: string, options: string[]) => options[1])
+    // 用户选中 ID2 那一项。pi 1.0.0 起 listSessionsFromDir 对文件名倒序预排序
+    // （files.sort((a,b) => b.localeCompare(a))，session-manager.js），同 modified 下
+    // a.jsonl/b.jsonl 的顺序与 0.84.4（readdir 字母序、无预排序）相反——listAll 本身
+    // 仍保序（mapWithConcurrency 按 index 写回）。不硬编码下标，按 label 中的短 uuid
+    // 定位目标项（消歧后缀保证了可定位性，这正是 MF-2 的承重点）
+    select.mockImplementation(async (_title: string, options: string[]) => {
+      const target = options.find((o) => o.includes(ID2.slice(0, 8)))
+      if (target === undefined) throw new Error(`labels 未含 ID2 短 uuid：${JSON.stringify(options)}`)
+      return target
+    })
     await cmd.handler('', ctx)
 
     // select 收到的 labels 必须两两不同（uuid 后缀消歧生效）
     const labelsArg = select.mock.calls[0][1] as string[]
     expect(labelsArg.length).toBe(2)
     expect(new Set(labelsArg).size).toBe(2)
-    // 插入的是第 2 条 session 的完整 uuid（旧实现 indexOf(label) 会错插第 1 条）；尾随空格与 applyCompletion spacer 语义一致（S-2）
+    // 插入的是被选中的第 2 条 session 完整 uuid（旧实现 indexOf(原始 label) 会错插第 1 条）；
+    // 尾随空格与 applyCompletion spacer 语义一致（S-2）
     expect(setEditorText).toHaveBeenCalledWith(`#${ID2} `)
   })
 })

package/src/__tests__/zcode-routing.test.ts

@@ -310,13 +310,16 @@ describe('变体 M：manifest 主路径（instrument：manifest 锚与 entry 锚
     writeRootSessionFile()
   })
 
-  it('outline：读到 manifest 锚的 sess_bbb（ZBSENTINEL 在，ZASENTINEL 不在），两轮 T000/T001', async () => {
+  it('outline：读到 manifest 锚的 sess_bbb（ZBSENTINEL 在，ZASENTINEL 不在），两轮 T001/T002', async () => {
     const r = await handleSessionRead({ action: 'outline', session: SA_M }, signals())
     const text = r.content[0]?.text ?? ''
     expect(text).toContain('ZBSENTINEL')
     expect(text).not.toContain('ZASENTINEL')
-    expect(text).toContain('T000')
+    // D9② 占位行折叠：T000 = converter 注入的 session_info 前置条目（纯记录，非对话），
+    // 折叠后不产行；对话轮保留原 turn.index（T001/T002），totalTurns 仍 = 2
     expect(text).toContain('T001')
+    expect(text).toContain('T002')
+    expect(text).not.toMatch(/\bT000\b/)
     // outline 的 isCompaction 恒 false 属已登记形态（§4 已接受代价）——无独立压缩 turn
     expect(text).not.toContain('compaction')
   })

package/src/core/render.ts

@@ -343,6 +343,37 @@ function formatLine(b: TurnBrief, level: LineLevel, branchSize?: number): string
 // renderOutline
 // ---------------------------------------------------------------------------
 
+/**
+ * 对话语义条目判定（outline 折叠谓词，D9②）。
+ *
+ * pi 1.0 session 落盘 entry 十一类（session-manager.js appendXxx 家族实装）中，参与
+ * 对话流的仅三类：message（role=user/assistant/toolResult）、compaction、
+ * custom_message（appendCustomMessageEntry——参与 LLM 上下文的注入消息）。其余
+ * ——usage（模型记账，appendUsage 明言不参与 LLM 上下文）/ session_info /
+ * model_change / thinking_level_change / context_edit / custom（扩展审计痕迹，
+ * appendCustomEntry）/ label（entry 书签/标记，appendLabelChange 落盘，targetId
+ * 指向被标记条目，无 message 字段，与 usage 同归折叠侧）/ branch_summary
+ * （branchWithSummary 落盘的分叉痕迹：编辑历史
+ * 消息产生分支时记录被放弃路径的摘要；summary 虽经 sessionEntryToContextMessages
+ * 转 createBranchSummaryMessage 参与 LLM 上下文重放，但语义是被放弃路径的终点而非
+ * 当前路径的对话内容，且 taiji 无消息编辑入口不产生该形态）——是纯记录条目：
+ * 单独成 turn 时（首条 user 前的孤儿堆、
+ * compaction 边界与下一 user 之间的记账堆）outline 渲染出只有 T 序号头的占位行，
+ * 轮次计数被记录条目膨胀。折叠 = 这类条目不产 outline 行；expand/detail 不受影响
+ * （仍按 T 序号完整可达），字节统计（leafParsedBytes/totalEntries）保持全量口径。
+ */
+function isConversationEntry(e: Entry): boolean {
+  if (e.type === 'compaction' || e.type === 'custom_message') return true
+  const msg = e.message
+  if (msg === undefined) return false
+  return msg.role === 'user' || msg.role === 'assistant' || msg.role === 'toolResult'
+}
+
+/** 对话 turn：含任一对话语义条目（纯记录条目 turn 被 outline 折叠，不占轮次）。 */
+function isConversationTurn(t: Turn): boolean {
+  return t.entries.some(isConversationEntry)
+}
+
 function sumBranchEntries(tree: TreeView): number {
   let s = 0
   for (const n of tree.branches.values()) s += n
@@ -423,36 +454,40 @@ export function renderOutline(
   const allBranches = options?.allBranches ?? false
   const granularity = options?.granularity ?? 'turn'
 
+  // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据面）；行与轮次计数走对话集
   const parsedBytes = leafParsedBytes(turns)
   const leafEntryCount = turns.reduce((s, t) => s + t.entries.length, 0)
   // totalEntries = leaf + 旁支子树 + 孤儿；totalBytes 无原始文件字节数（签名不含 ParseResult），
   // 以 leaf entry JSON 字节近似，精确值由 M2 工具层用 ParseResult.totalBytes 覆盖。
   const totalEntriesAll = leafEntryCount + sumBranchEntries(tree) + tree.orphans.length
+  // D9② 占位行折叠：纯记录条目 turn 不产 outline 行、不计入轮次（totalTurns = 对话轮数）；
+  // 保留原 turn.index 作 T 序号——outline 行是 expand/detail 的入口地址，重编号会切断对齐。
+  const dialogTurns = turns.filter(isConversationTurn)
   const stats: OutlineResult['stats'] = {
-    totalTurns: turns.length,
+    totalTurns: dialogTurns.length,
     totalEntries: totalEntriesAll,
     totalBytes: parsedBytes,
     parsedBytes,
     skippedLines: 0,
   }
 
-  if (turns.length === 0) {
+  if (dialogTurns.length === 0) {
     return { turns: [], lines: [], stats, tokenEstimate: 0 }
   }
 
   // granularity:entry —— 每 entry 一行，不聚合 turn（D-1 兜底）
   if (granularity === 'entry') {
-    return renderEntryGranularity(turns, tree, budget, allBranches, stats)
+    return renderEntryGranularity(dialogTurns, tree, budget, allBranches, stats)
   }
 
   // 1. 全量 brief
-  const briefs: TurnBrief[] = turns.map(computeBrief)
+  const briefs: TurnBrief[] = dialogTurns.map(computeBrief)
 
   // allBranches：标注 forkPoint
   if (allBranches) applyBranchLabels(briefs, turns, tree)
 
-  // 2. perTurnBudget（token → chars×4）
-  const perTurnCharBudget = (budget / turns.length) * CHARS_PER_TOKEN
+  // 2. perTurnBudget（token → chars×4；分母 = 对话轮数——折叠行不参与预算分配）
+  const perTurnCharBudget = (budget / dialogTurns.length) * CHARS_PER_TOKEN
 
   // 3. 降级序渲染：level 0 全有 → level 1 砍 assistantBrief → level 2 骨架
   const lineCache = renderDegradingLines(briefs, tree, perTurnCharBudget)
@@ -476,6 +511,8 @@ function renderEntryGranularity(
   let entryIdx = 0
   for (const t of turns) {
     for (const e of t.entries) {
+      // D9②：纯记录条目不产 outline 行（与 turn 粒度同谓词，entryIdx 只数对话条目）
+      if (!isConversationEntry(e)) continue
       const msg = e.message
       let text = ''
       if (msg !== undefined && (msg.role === 'user' || msg.role === 'assistant')) {

package/src/core/turns.ts

@@ -8,6 +8,11 @@ import type { Entry } from '@zhushanwen/session-core'
  * - 前置 turn（preface）：首条 user/compaction 之前出现的 rule-4 entry
  *  （assistant / model_change / thinking_level_change / custom / branch_summary）无处并入时
  *   单独成 turn 0，无 userEntry，isCompaction=false。
+ *
+ * 分段与折叠分工：本函数把全部非 header/compaction/user 条目归入 turn（纯记录条目
+ * 也成 turn）；outline 是否渲染行由 render.ts isConversationEntry 二次裁决——纯记录
+ * 条目（无 message 字段，含 branch_summary）的 turn 不产 outline 行。两处对条目形态
+ * 的认知以 pi dist 实装为同一事实源（entry 全集十一类，见 render.ts 注释枚举）。
  */
 export interface Turn {
   index: number

package/src/handler-utils.ts

@@ -20,8 +20,9 @@ export const SESSION_ID_PREFIX_LEN = 8
 export const pad = (n: number): string => String(n).padStart(TURN_INDEX_WIDTH, '0')
 
 /** 构造带 👉 恢复指引的 Error。契约：handler 直接 throw，execute 不 catch、原样传播给 pi；
- * pi 外层（pi-agent-core agent-loop.js executePreparedToolCall catch，:466-471）统一转
- * isError:true 的 error tool result——返回值上的 isError 字段会被丢弃（错误被标成功）。 */
+ * pi 外层（pi-agent-core agent-loop.js executePreparedToolCall catch，pi 1.0.0 :581-588）
+ * 统一转 isError:true 的 error tool result——统一 throw 为纪律选择（单一错误路径），
+ * 非「返回值 isError 失效」（1.0.0 起返回值标记同样被尊重〔:579〕，双轨写法仍禁用）。 */
 export function err(message: string): Error {
   return new Error(message)
 }

package/src/index.ts

@@ -14,9 +14,9 @@ import { createSessionCommand } from './tui/session-command.js'
  * 分层（同 scheduler/cw-tool）：
  * - tool-handler.ts：纯逻辑 handler，agentDir 注入，零 pi 依赖，可单测
  * - index.ts（本文件）：pi 依赖层，registerTool + getAgentDir() 调用 + execute 闭包
- *   （错误直接 throw 给 pi——pi-agent-core agent-loop 只对 execute throw 置
- *   isError:true，返回值里的 isError 字段被丢弃；W4 修复，锚点
- *   agent-loop.js:453-483/525-547，pi 自带 bash 工具同范式）
+ *   （错误直接 throw 给 pi——pi-agent-core agent-loop 对 execute throw 置 isError:true，
+ *   锚点 agent-loop.js:581-588；1.0.0 起返回值 isError:true 同样被尊重（:579），
+ *   本工具恒走 throw 路径两版语义等价，pi 自带 bash 工具同范式）
  */
 
 // ---- TypeBox 参数 schema（design §3.4 14 字段）----
@@ -208,10 +208,9 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
       _onUpdate: unknown,
       ctx: ExtensionContext | undefined,
     ) {
-      // 错误路径直接 throw：pi 契约只有 throw 才置 isError:true（tool_execution_end /
-      // ToolResultMessage），handler 抛的 Error 文案（含 👉 恢复提示）原样成为
-      // toolResult content，模型仍可读到。曾用 return {isError:true}——被 agent-loop
-      // 丢弃，错误轮被标成功（W4 修复）。
+      // 错误路径直接 throw：pi 契约 throw 置 isError:true（tool_execution_end /
+      // ToolResultMessage；1.0.0 起返回值 isError:true 也被尊重，本工具恒走 throw），
+      // handler 抛的 Error 文案（含 👉 恢复提示）原样成为 toolResult content，模型仍可读到。
       // signal 仅 search 消费（MF-5：长扫描可中断，Esc 不再挂死）；其余 action 有界不接
       // 信号包采集（design §7B）：可选链逐层降级——ctx===undefined（存量单测五参形态）、
       // sessionManager 缺字段、getSessionDir 方法缺失，任一层不成立即 liveSessionDir=undefined