@zhushanwen/pi-session-reader 0.2.4 → 0.3.1

package/src/tool-handler.ts

@@ -4,7 +4,7 @@
  * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
- * 按 action 分发到 8 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
+ * 按 action 分发到 9 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
@@ -28,6 +28,7 @@ import {
   renderOutline,
   renderExpand,
   renderDetail,
+  formatBytesMarker,
   type OutlineOptions,
   type OutlineResult,
   type EntryBrief,
@@ -126,15 +127,6 @@ function shortCwd(cwd: string): string {
   return parts.slice(-SHORT_CWD_SEGMENTS).join('/')
 }
 
-/** bytes→KB 换算基数（formatOmitted 的 KB 显示）。 */
-const BYTES_PER_KB = 1024
-
-function formatOmitted(bytes: number): string {
-  if (bytes <= 0) return ''
-  if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`
-}
-
 /** F5 必填参数校验。 */
 function requireStr(
   val: string | undefined,
@@ -347,7 +339,7 @@ function formatSessionGc(record: RecordManifest): string {
 /** ES2（SA_ID_NO_MATCH）：sa-id 无精确匹配（可能仍在运行 / 片段输入）。 */
 function formatSaIdNotFound(saId: string): string {
   return (
-    `subagent "${saId}" 无匹配 record（可能仍在运行——终态 record 在 completed/failed 后才写）。` +
+    `subagent "${saId}" 无匹配 record（若刚启动，record 可能尚未落盘）。` +
     `\n👉 用 session_read { action:"family" } 查活跃/已完成的 subagent；` +
     `若是片段输入，请用完整 sa- id 或 action:"find" 重试。`
   )
@@ -439,7 +431,7 @@ function formatOutlineText(r: OutlineResult): string {
     if (b.toolSummary) parts.push(b.toolSummary)
     // v2 O1：补 assistant 结论行（→ ）让 outline 单独可决策
     if (b.assistantBrief) parts.push('→ ' + b.assistantBrief)
-    const om = formatOmitted(b.omittedBytes)
+    const om = formatBytesMarker(b.omittedBytes)
     if (om) parts.push(om)
     if (b.branch) parts.push('[旁支]')
     return parts.join(' · ')
@@ -449,7 +441,7 @@ function formatOutlineText(r: OutlineResult): string {
     `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens${
       r.stats.skippedLines > 0 ? ` · ${r.stats.skippedLines} skipped lines` : ''
     }`,
-    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 或调大 budget]` : '',
+    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 的 turns 参数看指定 turn 范围]` : '',
   ]
     .filter(Boolean)
     .join('\n')
@@ -460,7 +452,7 @@ function formatExpandText(turn: string, entries: EntryBrief[]): string {
   const lines = entries.map(
     (e) =>
       `  [${e.index}] ${e.type}${e.role ? '/' + e.role : ''} ${e.brief}${
-        e.omittedBytes > 0 ? ' ' + formatOmitted(e.omittedBytes) : ''
+        e.omittedBytes > 0 ? ' ' + formatBytesMarker(e.omittedBytes) : ''
       }`,
   )
   return `${turn}\n${lines.join('\n')}`
@@ -681,7 +673,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
       tree = await buildExecutionTree(resolved.sessionId, agentDir, resolved.fileName)
     } catch (e) {
       throw err(
-        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兑底。`,
+        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兜底。`,
       )
     }
     return {
@@ -702,7 +694,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
   return { content: [{ type: 'text', text: formatFamilyText(family) }], details: family }
 }
 
-/** outline：turn 级全貌 TOC（design §3.4 outline，~500 token）。 */
+/** outline：turn 级全貌 TOC（design §3.4 outline，~1500 token；render budget 硬编码 2000）。 */
 async function doOutline(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const resolved = await resolveSessionId(params.session, 'outline', agentDir, params.source)
   if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
@@ -774,29 +766,22 @@ async function doDetail(params: SessionReadParams, agentDir: string): Promise<To
 /** search action 的默认命中数上限。 */
 const SEARCH_DEFAULT_LIMIT = 20
 
-/** search：session 内全文检索（design §3.4 search，M3 新实现）。 */
-async function doSearch(
-  params: SessionReadParams,
-  agentDir: string,
-  signal?: AbortSignal,
-): Promise<ToolResult> {
-  const resolved = await resolveSessionId(params.session, 'search', agentDir, params.source)
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
-  const pattern = requireStr(params.pattern, 'pattern', 'search')
-  const scope = params.scope ?? 'all'
-  const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
-  const { entries } = await safeParse(resolved.fileName)
-  const tree = buildTreeView(entries)
-  const turns = segmentTurns(entries, new Set(tree.leafPath))
-  const regex = compilePattern(pattern)
-  // S-3：启发式降级时在 header 标注，避免 LLM 把 0 hit(s) 误读为「无匹配」（静默错数据）
-  const degraded = isCatastrophicPattern(pattern)
-  const hits: Array<{
-    turnIndex: number
-    entryIndex: number
-    role: string
-    matchSnippet: string
-  }> = []
+/** search 单条命中（turn 内 entry 定位 + 角色 + 摘要片段）。 */
+interface SearchHit {
+  turnIndex: number
+  entryIndex: number
+  role: string
+  matchSnippet: string
+}
+
+/** search 扫描阶段：遍历 turns 收集命中；每 turn 前检查 abort（MF-5 尽早退出）。 */
+function collectSearchHits(
+  turns: Turn[],
+  regex: RegExp,
+  scope: NonNullable<SessionReadParams['scope']>,
+  signal: AbortSignal | undefined,
+): SearchHit[] {
+  const hits: SearchHit[] = []
   for (const t of turns) {
     // MF-5：Esc/abort 后 pi 已丢弃本 turn 结果，尽早退出避免继续扫描长 session
     if (signal?.aborted) {
@@ -818,14 +803,46 @@ async function doSearch(
       }
     }
   }
-  const truncated = hits.length > limit
-  const sliced = truncated ? hits.slice(0, limit) : hits
+  return hits
+}
+
+/** search 收口阶段：结果文本组装（header 标注降级/scope/截断 + 逐行命中列表）。 */
+function formatSearchText(
+  pattern: string,
+  degraded: boolean,
+  scope: NonNullable<SessionReadParams['scope']>,
+  sliced: SearchHit[],
+  truncated: boolean,
+): string {
   const lines = sliced.map(
     (h) => `  T${pad(h.turnIndex)} #${h.entryIndex} ${h.role}: ${h.matchSnippet}`,
   )
-  const text = `${sliced.length} hit(s) for /${pattern}/${degraded ? '（已降级为字面子串匹配）' : ''}${
+  return `${sliced.length} hit(s) for /${pattern}/${degraded ? '（已降级为字面子串匹配）' : ''}${
     scope !== 'all' ? ' scope=' + scope : ''
   }${truncated ? ` (truncated, showing first ${sliced.length})` : ''}\n${lines.join('\n')}`
+}
+
+/** search：session 内全文检索（design §3.4 search，M3 新实现）。 */
+async function doSearch(
+  params: SessionReadParams,
+  agentDir: string,
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  const resolved = await resolveSessionId(params.session, 'search', agentDir, params.source)
+  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  const pattern = requireStr(params.pattern, 'pattern', 'search')
+  const scope = params.scope ?? 'all'
+  const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
+  const { entries } = await safeParse(resolved.fileName)
+  const tree = buildTreeView(entries)
+  const turns = segmentTurns(entries, new Set(tree.leafPath))
+  const regex = compilePattern(pattern)
+  // S-3：启发式降级时在 header 标注，避免 LLM 把 0 hit(s) 误读为「无匹配」（静默错数据）
+  const degraded = isCatastrophicPattern(pattern)
+  const hits = collectSearchHits(turns, regex, scope, signal)
+  const truncated = hits.length > limit
+  const sliced = truncated ? hits.slice(0, limit) : hits
+  const text = formatSearchText(pattern, degraded, scope, sliced, truncated)
   return { content: [{ type: 'text', text }], details: { hits: sliced, truncated } }
 }
 
@@ -1195,8 +1212,16 @@ function extractFiles(turns: Turn[]): ToolResult {
 /** commits 提取的 hash 前后上下文字符数（次路径关键词判定窗口）。 */
 const COMMIT_CONTEXT_CHARS = 30
 
-function extractCommits(turns: Turn[]): ToolResult {
-  // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
+/** commits 预设的单条提取结果（hash + 来源 turn + 置信来源 + 上下文片段）。 */
+interface CommitItem {
+  hash: string
+  turn: number
+  source: 'git-cmd' | 'commit-context'
+  context: string
+}
+
+/** 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）。 */
+function collectBashCommands(turns: Turn[]): Map<string, string> {
   const bashCmds = new Map<string, string>()
   for (const t of turns) {
     for (const e of t.entries) {
@@ -1209,16 +1234,39 @@ function extractCommits(turns: Turn[]): ToolResult {
       }
     }
   }
+  return bashCmds
+}
 
-  type CommitItem = {
-    hash: string
-    turn: number
-    source: 'git-cmd' | 'commit-context'
-    context: string
+/** 单条 toolResult 文本的 hash 提取：git-cmd 全收（高置信），否则按上下文关键词过滤（次路径）。 */
+function matchCommitsInResult(
+  text: string,
+  turnIndex: number,
+  isGitBash: boolean,
+  high: CommitItem[],
+  low: CommitItem[],
+): void {
+  for (const m of text.matchAll(SHORT_HASH_RE)) {
+    const hash = m[0]
+    const idx = m.index ?? 0
+    const ctx = text
+      .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
+      .replace(/\s+/g, ' ')
+      .trim()
+    if (isGitBash) {
+      high.push({ hash, turn: turnIndex, source: 'git-cmd', context: ctx })
+    } else if (COMMIT_CTX_RE.test(ctx)) {
+      low.push({ hash, turn: turnIndex, source: 'commit-context', context: ctx })
+    }
   }
+}
+
+/** 主扫描阶段：遍历 toolResult entry，分类收集高/低置信 commit 候选。 */
+function collectCommitCandidates(
+  turns: Turn[],
+  bashCmds: Map<string, string>,
+): { high: CommitItem[]; low: CommitItem[] } {
   const high: CommitItem[] = []
   const low: CommitItem[] = []
-
   for (const t of turns) {
     for (const e of t.entries) {
       if (e.message?.role !== 'toolResult') continue
@@ -1227,23 +1275,14 @@ function extractCommits(turns: Turn[]): ToolResult {
       if (text === '') continue
       const cmd = msg.toolCallId !== undefined ? bashCmds.get(msg.toolCallId) : undefined
       const isGitBash = msg.toolName === 'bash' && cmd !== undefined && GIT_CMD_RE.test(cmd)
-      for (const m of text.matchAll(SHORT_HASH_RE)) {
-        const hash = m[0]
-        const idx = m.index ?? 0
-        const ctx = text
-          .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
-          .replace(/\s+/g, ' ')
-          .trim()
-        if (isGitBash) {
-          high.push({ hash, turn: t.index, source: 'git-cmd', context: ctx })
-        } else if (COMMIT_CTX_RE.test(ctx)) {
-          low.push({ hash, turn: t.index, source: 'commit-context', context: ctx })
-        }
-      }
+      matchCommitsInResult(text, t.index, isGitBash, high, low)
     }
   }
+  return { high, low }
+}
 
-  // 去重：高置信优先，同 hash 保留首次
+/** 收口阶段：去重，高置信优先，同 hash 保留首次。 */
+function dedupeCommits(high: CommitItem[], low: CommitItem[]): CommitItem[] {
   const seen = new Set<string>()
   const items: CommitItem[] = []
   for (const c of high) {
@@ -1256,6 +1295,14 @@ function extractCommits(turns: Turn[]): ToolResult {
     seen.add(c.hash)
     items.push(c)
   }
+  return items
+}
+
+function extractCommits(turns: Turn[]): ToolResult {
+  // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
+  const bashCmds = collectBashCommands(turns)
+  const { high, low } = collectCommitCandidates(turns, bashCmds)
+  const items = dedupeCommits(high, low)
 
   return renderExtractItems(
     'commits',
@@ -1385,8 +1432,9 @@ interface SkippedRun {
  * session 会抛「session not found in family index」）——resolveSessionId 已把 session 解析到
  * 真实文件（kind==='ok' 保证文件存在，三形态：绝对路径/sa-id 均 existsSync 校验，片段匹配
  * 来自实际 fs 扫描），直接用 resolved.fileName 构造单条目 sessionIdToPath 调 resolveWorkflows
- *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 仅含目标 session，call 引用
- * 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，足够 LLM 跳 outline/detail 深读）。
+ *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 传空 Map（单条目链路无其他
+ * 文件可反查），call 引用 100% 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，
+ * 足够 LLM 跳 outline/detail 深读）。
  *
  * 错误契约（C2）：workflow 概览探索语义，三类错误均返回 ToolResult 不抛错。
  * step 的 call sessionId/sessionFile 是 LLM 跳 outline/detail 的入口（m0 resolveSessionId
@@ -1468,7 +1516,7 @@ async function doWorkflow(params: SessionReadParams, agentDir: string): Promise<
   if (requestedRunId !== undefined) details.requestedRunId = requestedRunId
   if (skippedRuns.length > 0) details.skippedRuns = skippedRuns
 
-  // 全部 run 都跳过的兑底提示（ES-wf-snapshot-read-fail 末段）
+  // 全部 run 都跳过的兜底提示（ES-wf-snapshot-read-fail 末段）
   let text: string
   if (runs.length === 0) {
     text =

package/src/tui/hash-provider.ts

@@ -47,8 +47,6 @@ const AGE_NUM_DIGITS = 2
 export interface AutocompleteCandidate {
   /** 显示文本（满宽 label）。`${age} ${预览/name}`，如 "01m 看看 pi-session-reader..." */
   label: string
-  /** 副信息（次列）。本 provider 不设（undefined）——触发 SelectList 满宽 label 分支 */
-  description?: string
   /** 插入编辑器，如 "#019e6c96-aaaa-bbbb-cccc-dddddddddddd"（design D-3：完整 uuid，非名称；不显示给用户看） */
   insertText: string
 }
@@ -203,7 +201,6 @@ export function createHashAutocompleteProvider(
       const items: AutocompleteItem[] = candidates.map((c) => ({
         value: c.insertText,
         label: c.label,
-        description: c.description,
       }))
       // prefix = 光标前匹配到的整段（# 及片段），applyCompletion 据此定位替换区间
       return { items, prefix: `#${fragment}` }

package/src/tui/session-command.ts

@@ -36,7 +36,7 @@ export function createSessionCommand(
   handler(args: string, ctx: ExtensionCommandContext): Promise<void>
 } {
   return {
-    description: 'Pick a session and insert a #uuid-fragment reference into the editor.',
+    description: 'Pick a session and insert a #uuid reference into the editor.',
     async getArgumentCompletions(argumentPrefix) {
       const trimmed = argumentPrefix.trim()
       const all = await SessionManager.listAll(getCwdSessionDir())

package/vitest.config.ts

@@ -2,6 +2,8 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
+    reporters: ['default', 'junit'],
+    outputFile: { junit: './test-results/vitest-junit.xml' },
     include: ['src/__tests__/**/*.test.ts'],
   },
 })