@zhushanwen/pi-session-reader 0.5.0 → 0.6.0

package/src/handler-utils.ts

@@ -1,16 +1,22 @@
 /**
- * tool-handler 共享小工具（max-lines 拆分轮机械提取，零行为变更）。
+ * tool-handler 共享小工具（max-lines 拆分轮机械提取；ext-simplify-04 E5 扩充，零行为变更）。
  *
  * 从 tool-handler.ts「小工具」与「turn/turns 索引解析」段搬出：pad/err/turn 索引解析
- * 被留守的 tool-handler 与拆出的 search-across.ts / extract.ts 共同消费——放独立低层
- * 模块保持单向依赖（handler-utils ← 各域模块 ← tool-handler），不引入循环 import
- *（result-action.ts 的 Deps 注入先例解决不了纯函数跨模块复用，低层模块更直接）。
- * stripHash/formatDate/shortCwd/requireStr 仅 tool-handler 留守部分使用，不在此列。
+ * 被留守的 tool-handler 与拆出的 search-across.ts / extract.ts 共同消费；
+ * err 原属此列，E5 起同包 helper 获取范式单一化——result-action.ts 不再经
+ * ResultActionDeps 注入 err/stripHash/requireStr/SESSION_ID_PREFIX_LEN，与本模块
+ * 其他消费者一样直接 import。formatDate/shortCwd 仅 tool-handler 留守部分使用，不在此列。
+ * requireStr 的 action 参数类型经 type import 取自 tool-handler.ts（编译期擦除，
+ * 无运行时循环——与域模块对本模块「仅 type import」同一先例）。
  */
+import type { SessionReadAction } from './tool-handler.js'
 
 /** turn 索引显示宽度（T013 三位补零）。 */
 const TURN_INDEX_WIDTH = 3
 
+/** sessionId 列表行内的短显前缀长度。 */
+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；
@@ -20,6 +26,23 @@ export function err(message: string): Error {
   return new Error(message)
 }
 
+/** 剥 # 前缀（TUI `#e6c96` 引用 → 纯片段，design §3.3 D-3/D-4）。 */
+export function stripHash(s: string): string {
+  return s.replace(/^#+/, '')
+}
+
+/** F5 必填参数校验。 */
+export function requireStr(
+  val: string | undefined,
+  name: string,
+  action: SessionReadAction,
+): string {
+  if (val === undefined || val === null || val.trim() === '') {
+    throw err(`action:"${action}" 需要参数 "${name}"。👉 补上 "${name}" 重试。`)
+  }
+  return val.trim()
+}
+
 // ---------------------------------------------------------------------------
 // turn / turns 索引解析
 // ---------------------------------------------------------------------------

package/src/no-match.ts

@@ -136,8 +136,9 @@ function guidanceLines(): string[] {
  *
  * ① 事实型自检行：main 根 N 文件 / subagent 根 M 文件 /「候选集非空|为空」/「查询已做
  *    uuid 归一化匹配（小写+去连字符）后仍无命中」。计数取 roots——调用方在 F1 路径
- *    恒以无 options 的 resolveSessionRoots 实扫（find/doctor 缓存句柄不注入，§7B 要点 8：
- *    缓存计数会把 PS-14「首条 assistant 前 0 文件」误报成「主根为空」），即本次实扫结果。
+ *    恒以无 options 的 resolveSessionRoots 实扫（根扫描无缓存——doctor 缓存机已删除，
+ *    ext-simplify-04 U3，§7B 要点 8 新态；原 PS-14「缓存计数误报主根为空」的防污染
+ *    规则随之失效），即本次实扫结果。
  *    只陈述事实，**不得**出现「真的没有这个 session」类归因断言（§3.3 教训：大写/去连
  *    字符输入在归一化前会被错误归因为「不存在」）。
  * ② 编辑距离最近候选 top-3（标注 source 与差异位），候选 = roots 实扫文件名提取的

package/src/result-action.ts

@@ -1,12 +1,14 @@
 /**
  * result action（subagent-sync-collect U6：design subagent-sync-collect.md §3.1.3）。
  *
- * 从 tool-handler.ts 机械提取（max-lines 拆分轮）：纯移动零行为变更。tool-handler 的
- * 定位/解析 helper（err/stripHash/requireStr/resolveSessionId/disambiguate/safeParse）
- * 为文件私有且被其余 9 个 action 共用，不便搬移——经 {@link ResultActionDeps} 注入，
- * tool-handler.ts 构造 RESULT_ACTION_DEPS 常量传入（构造期绑定，运行时零查找开销）。
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮）：纯移动零行为变更。纯函数 helper
+ *（err/stripHash/requireStr/SESSION_ID_PREFIX_LEN）直接 import 自 handler-utils
+ *（ext-simplify-04 E5 收敛：同包 helper 获取范式单一化）；resolveSessionId/disambiguate/
+ * safeParse 仍为 tool-handler 文件私有且被其余 9 个 action 共用，不便搬移——经
+ * {@link ResultActionDeps} 注入，入口分发处 per-call 构造（resolveSessionId 被信号包
+ * liveSessionDir 的包装覆盖）。
  *
- * 设计来源：docs/design/subagent-sync-collect.md §3.1.3 ——
+ * 设计来源：docs/design/subagent-sync-collect.md §3.1.3（已删除，git 可追溯）——
  *   session_read {"action":"result","session":"sa-aaa"}              // 单个
  *   session_read {"action":"result","session":"sa-aaa,sa-bbb,sa-ccc"} // 批量（≤10）
  *   → 每条返回该 subagent session 的最终 assistant 正文（与通知 record.result 同源），
@@ -14,8 +16,10 @@
  * 定位复用既有发现机制（sa-xxx manifest 反查 / uuid 片段 / 路径），不新造目录或文件。
  */
 import type { Entry, ParseResult } from './core/parser.js'
+import { textBlockParts } from './core/render.js'
 import type { MatchedSession } from './discovery/find.js'
 import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
+import { err, requireStr, SESSION_ID_PREFIX_LEN, stripHash } from './handler-utils.js'
 import type { ResolveResult, SessionReadAction, SessionReadParams, ToolResult } from './tool-handler.js'
 
 /** result 批量上限（design subagent-sync-collect §3.1.3：一次最多 10 个）。 */
@@ -27,11 +31,8 @@ const RESULT_DEFAULT_LIMIT = 8000
 /** result 批量条目分隔符（与 notifier 批通知 "\n\n---\n\n" join 同款）。 */
 const RESULT_BATCH_SEPARATOR = '\n\n---\n\n'
 
-/** result action 对 tool-handler 私有 helper 的注入面（构造期常量绑定）。 */
+/** result action 对 tool-handler 文件私有 helper 的注入面（入口分发处 per-call 构造）。 */
 export interface ResultActionDeps {
-  err(message: string): Error
-  stripHash(s: string): string
-  requireStr(val: string | undefined, name: string, action: SessionReadAction): string
   resolveSessionId(
     rawSession: string | undefined,
     action: SessionReadAction,
@@ -42,8 +43,6 @@ export interface ResultActionDeps {
   ): Promise<ResolveResult>
   disambiguate(query: string, candidates: MatchedSession[]): ToolResult
   safeParse(fileName: string): Promise<ParseResult>
-  /** 批量头行短 id 截断宽度（tool-handler SESSION_ID_PREFIX_LEN 同源）。 */
-  sessionIdPrefixLen: number
 }
 
 /**
@@ -52,29 +51,26 @@ export interface ResultActionDeps {
  * 与 record 侧 text_delta 直累积同构：同一 message 内多个 text 块无分隔拼接
  *（流式 delta 逐段 append），thinking/toolCall 块不入 record.text，此处同样排除。
  *
- * [S7 code-simplify 登记] 本包内第 4 个同構「text 块提取」变体（其余三处均在
- * tool-handler.ts / discovery/find.ts）：messageReadableText（'' join + 占位符）、
- * extractContentText（'\n' join）、extractTextFromContent（' ' join + 空返 undefined）。
+ * [S7 code-simplify 登记] 本变体经 E11 归一到共享核 textBlockParts（core/render.ts，
+ * 块 → string[]），join 语义留在本调用点。包内完整映射（共享核 1 + 特异 3）：
+ * - 共享核 textBlockParts：白名单 type==='text' 取 text；本函数（'' join）/
+ *   extract.ts extractContentText（'\n' join）/ find.ts extractTextFromContent
+ *   （' ' join + 空返 undefined）三个纯 text 变体均为其组合调用
+ * - 特异保留 3 个（filter 集不同，不可归一）：tool-handler.ts messageReadableText
+ *   （thinking/toolCall 占位）、search-across.ts searchableText（JSON 兜底）、
+ *   render.ts extractText（排除法——白名单与排除法在未知 type 块上不等价）
+ *
  * 本变体的 '' 无分隔拼接是 A4 取回逐字节一致锁定的硬理由（对齐 record.result 的
  * 流式 delta 无分隔累积），不可与带分隔符的变体合并——差异是行为敏感点，勿「顺手统一」。
  */
 function assistantMessageText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (!Array.isArray(content)) return ''
-  let out = ''
-  for (const block of content) {
-    if (block !== null && typeof block === 'object') {
-      const o = block as Record<string, unknown>
-      if (o.type === 'text' && typeof o.text === 'string') out += o.text
-    }
-  }
-  return out
+  return textBlockParts(content).join('')
 }
 
 /**
  * 从 session entries 提取最终结果正文（与完成通知 record.result 同源，A4 逐字节一致的前置）。
  *
- * 同源语义（packages/subagent-core/src/execution/execution-record.ts getFullText，只读参考）：
+ * 同源语义（packages/subagent-core/src/execution/persistence/execution-record.ts getFullText，只读参考）：
  * record.result = AgentResult.text = getFullText(record) = 全部 assistant turn 文本
  * filter(非空，空白串按非空) join("\\n\\n")；pi 每 turn_end 对应一条 assistant message
  *（agent-session.js turn_end 携带 message），故文件侧重建 = 每条 assistant message 的
@@ -120,8 +116,7 @@ interface ResultItem {
   text: string
 }
 
-/** result 截断尾提示（design §3.1.3：超出截断 + 提示读原文件）。 */
-/** result 条目截断提示行。
+/** result 条目截断提示行（design §3.1.3：超出截断 + 提示读原文件）。
  *
  * [S8 code-simplify 口径注] 本函数的 X = **保留**字符数（limit）；而 subagent-core
  * notifier.ts buildTruncationPointer 同模板的 X = **丢弃**字符数（total - kept）。
@@ -158,16 +153,16 @@ function resolveResultLimit(raw: number | undefined): number {
  * result 的 session 列表解析：单 id 或逗号批量（≤10）。
  * 空条目（如 "sa-a," 或连续逗号）与超限均明确报错（含上限数字与 👉）。
  */
-function parseResultSessionList(raw: string | undefined, deps: ResultActionDeps): string[] {
-  const trimmed = deps.requireStr(raw, 'session', 'result')
-  const ids = trimmed.split(',').map((s) => deps.stripHash(s.trim()))
+function parseResultSessionList(raw: string | undefined): string[] {
+  const trimmed = requireStr(raw, 'session', 'result')
+  const ids = trimmed.split(',').map((s) => stripHash(s.trim()))
   if (ids.some((id) => id === '')) {
-    throw deps.err(
+    throw err(
       `session 列表含空条目："${trimmed}"。👉 检查逗号分隔格式（如 "sa-aaa,sa-bbb"）重试。`,
     )
   }
   if (ids.length > RESULT_MAX_BATCH) {
-    throw deps.err(
+    throw err(
       `批量取回 ${ids.length} 个 session 超上限：一次最多 ${RESULT_MAX_BATCH} 个。` +
         `\n👉 分批取回（每批 ≤${RESULT_MAX_BATCH} 个 id）。`,
     )
@@ -194,7 +189,7 @@ export async function doResult(
   agentDir: string,
   deps: ResultActionDeps,
 ): Promise<ToolResult> {
-  const ids = parseResultSessionList(params.session, deps)
+  const ids = parseResultSessionList(params.session)
   const limit = resolveResultLimit(params.limit)
   // S3（code-simplify）：sa- 形态走 manifest 反查，逐 id 调用会重复全量扫 subagents/ 树
   //（N+1）——批量入口预取一次注入。uuid 片段/路径形态不经 manifest，不预取。
@@ -208,7 +203,7 @@ export async function doResult(
     const { entries } = await deps.safeParse(resolved.fileName)
     const text = extractFinalAssistantText(entries)
     if (text.length === 0) {
-      throw deps.err(
+      throw err(
         `session "${id}" 尚无 assistant 输出（运行中或文件尚未 flush 完整）。` +
           `\n👉 稍后重试，或用 session_read { action:"outline", session:"${id}" } 看当前进度。`,
       )
@@ -235,7 +230,7 @@ export async function doResult(
   }
   const blocks = items.map(
     (it, i) =>
-      `[${i + 1}/${items.length}] ${it.session} (session ${it.sessionId.slice(0, deps.sessionIdPrefixLen)}…)\n${it.text}`,
+      `[${i + 1}/${items.length}] ${it.session} (session ${it.sessionId.slice(0, SESSION_ID_PREFIX_LEN)}…)\n${it.text}`,
   )
   return {
     content: [{ type: 'text', text: blocks.join(RESULT_BATCH_SEPARATOR) }],

package/src/search-across.ts

@@ -5,7 +5,6 @@
  * pattern 编译/文本提取/命中收集/渲染与跨会话检索共享同一扫描管线（safeParse →
  * buildTreeView → segmentTurns → collectSearchHits），拆为独立低层模块保持单向依赖
  *（tool-handler 的 doSearch 消费本模块导出，本模块只反向 type import 公共类型）。
- * searchAcrossSessions 导出面不变：tool-handler re-export（单测白盒 import 路径不变）。
  */
 import { dirname } from 'node:path'
 import {
@@ -348,7 +347,9 @@ function formatCrossSearchText(d: CrossSearchDetails): string {
   return `${formatCrossSearchHead(d, hitSessions.length)}\n${lines.join('\n')}`
 }
 
-/** searchAcrossSessions 的可选参数（byteBudget 供测试注入小预算）。 */
+/** searchAcrossSessions 的可选参数。byteBudget 为测试注入缝（E10 定性）：非模型可见参数
+ * （session_read schema 无此入参），存在动机 = 测试注入小预算触发预算截断用例，不必构造
+ * 64MB fixture；生产路径（doSearch）不传，走 SEARCH_SCAN_BYTE_BUDGET 默认。 */
 interface CrossSearchOptions {
   scope?: NonNullable<SessionReadParams['scope']>
   limit?: number
@@ -463,8 +464,8 @@ async function attachScannedTitles(
 }
 
 /**
- * 跨会话内容检索主体（u12 导出：byteBudget 参数供测试注入小预算，工具路径经 doSearch
- * 走默认 SEARCH_SCAN_BYTE_BUDGET）。
+ * 跨会话内容检索主体（u12 导出：byteBudget 为测试注入缝，非模型可见——工具路径经
+ * doSearch 走默认 SEARCH_SCAN_BYTE_BUDGET）。
  *
  * 流程：窄化拒绝（候选 > MULTI_SEARCH_MAX_SESSIONS，V8）→ buildSessionFileIndex（一次
  * 根扫描，id 语义与 find 候选同源）→ 按传入顺序逐个「复用单会话扫描管线」（safeParse →