@zhushanwen/pi-session-reader 0.3.1 → 0.5.0

package/src/no-match.ts

@@ -0,0 +1,160 @@
+/**
+ * F1 无匹配域（u9，design 2026-09-10 §5.2 / §6.7 子决策 3）。
+ *
+ * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）：F1 自检行 /
+ * 编辑距离候选 / formatNoMatch 渲染，消费方 = tool-handler 的 resolveByFragment
+ * 与 findNoMatch（find 零匹配）。自足模块——只依赖 discovery/core 的纯函数。
+ */
+import { extractSessionIdFromFilename } from './discovery/subagents.js'
+import { basename } from './core/toolcall.js'
+import type { SessionRoot } from './discovery/roots.js'
+
+/**
+ * Levenshtein 编辑距离（纯函数）。单行 DP 滚动数组，O(len(a)×len(b)) 时间。
+ * F1 用它对 uuid query 找最接近的候选 id（§5.2「最接近的候选」），让 agent 一眼自纠
+ *（如 01a08zzz → 01a08aac）。候选量级 ≤ 数千、uuid 36 字符，毫秒级。
+ */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0
+  if (a.length === 0) return b.length
+  if (b.length === 0) return a.length
+  let prev = new Array<number>(b.length + 1)
+  let curr = new Array<number>(b.length + 1)
+  for (let j = 0; j <= b.length; j++) prev[j] = j
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost)
+    }
+    const swap = prev
+    prev = curr
+    curr = swap
+  }
+  return prev[b.length]
+}
+
+/** 首个差异位（1-based，人类位次）；等串/一方为前缀时 undefined（无「X → Y」可标）。 */
+function firstDiffPosition(a: string, b: string): number | undefined {
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) {
+    if (a[i] !== b[i]) return i + 1
+  }
+  return undefined
+}
+
+/** F1 编辑距离候选行上限（§5.2 top-3）。 */
+const NO_MATCH_SUGGESTIONS = 3
+
+/**
+ * F1 自检行根标签列宽（2 空格缩进 + 最长 `[subagent]` 10 字符 + 3 对齐间距，
+ * 同 doctor 表 DOCTOR_ROOT_LABEL_PAD 的对齐思路）。
+ */
+const F1_ROOT_LABEL_PAD = 15
+
+/** ① 自检行：逐根去重标注/文件数 + 合计非空与否 + 归一化已做（只陈述事实）。 */
+function buildSelfCheckLines(roots: SessionRoot[]): string[] {
+  const lines: string[] = ['自检（发现层，只陈述事实）：']
+  let totalFiles = 0
+  for (const r of roots) {
+    if (r.dedupedInto !== undefined) {
+      lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `与 [${r.dedupedInto}] 同路径，已去重`)
+      continue
+    }
+    const count = r.fileCount ?? r.files.length
+    totalFiles += count
+    lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `${r.path}：${count} 文件`)
+  }
+  lines.push(
+    totalFiles > 0
+      ? `  → 候选集非空（共 ${totalFiles} 文件），根解析正常`
+      : '  → 候选集为空（所有候选根均 0 文件）',
+  )
+  lines.push('  → 查询已做 uuid 归一化匹配（小写 + 去连字符）后仍无命中')
+  return lines
+}
+
+/** F1 编辑距离候选（sessionId + source + mtime + 距离）。 */
+interface NoMatchSuggestion {
+  sessionId: string
+  source: string
+  mtime: number
+  distance: number
+}
+
+/** ② 候选集（roots 实扫文件名提取 id，同 id 取 mtime 新者）→ 编辑距离升序 top-3。 */
+function collectSuggestions(query: string, roots: SessionRoot[]): NoMatchSuggestion[] {
+  const candidates = new Map<string, { sessionId: string; source: string; mtime: number }>()
+  for (const r of roots) {
+    if (r.dedupedInto !== undefined) continue
+    for (const f of r.files) {
+      const sid = extractSessionIdFromFilename(basename(f.path))
+      if (sid === '') continue
+      const existing = candidates.get(sid)
+      if (existing === undefined || f.mtime > existing.mtime) {
+        candidates.set(sid, { sessionId: sid, source: r.source, mtime: f.mtime })
+      }
+    }
+  }
+  return [...candidates.values()]
+    .map((c) => ({ ...c, distance: levenshtein(query, c.sessionId) }))
+    .sort((a, b) => a.distance - b.distance || b.mtime - a.mtime)
+    .slice(0, NO_MATCH_SUGGESTIONS)
+}
+
+/** ② 渲染：候选行（source 标注 + 首个差异位）；空候选给明确说明。 */
+function formatSuggestionLines(suggestions: NoMatchSuggestion[], query: string): string[] {
+  const lines = ['最接近的候选（编辑距离）：']
+  if (suggestions.length === 0) {
+    lines.push('  （候选集中无可比对的 session id）')
+  }
+  for (const s of suggestions) {
+    const pos = firstDiffPosition(query, s.sessionId)
+    const diff =
+      pos !== undefined ? `差异在第 ${pos} 位：${query[pos - 1] ?? ''} → ${s.sessionId[pos - 1] ?? ''}` : ''
+    lines.push(`  ${s.sessionId}  ${s.source}  ${diff}`.trimEnd())
+  }
+  return lines
+}
+
+/** ③ 正确做法四条 + ④ 封死 shell 绕行（纯静态文案）。 */
+function guidanceLines(): string[] {
+  return [
+    '',
+    '正确做法：',
+    `  - 改用标题/keyword：session_read { action:"find", query:"<标题关键词>" }`,
+    `  - 已知文件路径时直接传绝对路径：session_read { action:"outline", session:"<绝对路径>.jsonl" }`,
+    `  - 截断/过期 id 用更短前缀：session_read { action:"find", query:"<更短前缀>" }`,
+    `  - 想先看环境与根目录状态：session_read { action:"doctor" }`,
+    '',
+    '不要用 shell find/ls/rg 搜 session 目录，不要 cat/read 原始 .jsonl —— session_read 是唯一入口。',
+  ]
+}
+
+/**
+ * F1 无匹配（u9 重写，design §5.2 形态——逐段规格）：
+ *
+ * ① 事实型自检行：main 根 N 文件 / subagent 根 M 文件 /「候选集非空|为空」/「查询已做
+ *    uuid 归一化匹配（小写+去连字符）后仍无命中」。计数取 roots——调用方在 F1 路径
+ *    恒以无 options 的 resolveSessionRoots 实扫（find/doctor 缓存句柄不注入，§7B 要点 8：
+ *    缓存计数会把 PS-14「首条 assistant 前 0 文件」误报成「主根为空」），即本次实扫结果。
+ *    只陈述事实，**不得**出现「真的没有这个 session」类归因断言（§3.3 教训：大写/去连
+ *    字符输入在归一化前会被错误归因为「不存在」）。
+ * ② 编辑距离最近候选 top-3（标注 source 与差异位），候选 = roots 实扫文件名提取的
+ *    sessionId（extractSessionIdFromFilename 与 buildManifestIndex 同源；非 id 形态
+ *    文件名提不出 → 不进候选，文件名与 header id 同源由 pi 写入保证）。
+ * ③「正确做法」四条：标题/keyword、绝对路径 outline、更短前缀、doctor。
+ * ④ 最后一行封死 shell 绕行：find/ls/rg 搜 session 目录、cat/read 原始 .jsonl 均禁止。
+ *
+ * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 被否项）。
+ */
+export function formatNoMatch(query: string, roots: SessionRoot[]): string {
+  return [
+    `无匹配 session："${query}"`,
+    '',
+    ...buildSelfCheckLines(roots),
+    '',
+    ...formatSuggestionLines(collectSuggestions(query, roots), query),
+    ...guidanceLines(),
+  ].join('\n')
+}

package/src/result-action.ts

@@ -0,0 +1,244 @@
+/**
+ * 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 常量传入（构造期绑定，运行时零查找开销）。
+ *
+ * 设计来源：docs/design/subagent-sync-collect.md §3.1.3 ——
+ *   session_read {"action":"result","session":"sa-aaa"}              // 单个
+ *   session_read {"action":"result","session":"sa-aaa,sa-bbb,sa-ccc"} // 批量（≤10）
+ *   → 每条返回该 subagent session 的最终 assistant 正文（与通知 record.result 同源），
+ *     可选 limit 参数（默认 8000 字符/条，超出截断 + 提示读原文件）。
+ * 定位复用既有发现机制（sa-xxx manifest 反查 / uuid 片段 / 路径），不新造目录或文件。
+ */
+import type { Entry, ParseResult } from './core/parser.js'
+import type { MatchedSession } from './discovery/find.js'
+import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
+import type { ResolveResult, SessionReadAction, SessionReadParams, ToolResult } from './tool-handler.js'
+
+/** result 批量上限（design subagent-sync-collect §3.1.3：一次最多 10 个）。 */
+const RESULT_MAX_BATCH = 10
+
+/** result 单条默认字符上限（design §3.1.3：默认 8000 字符/条）。 */
+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 的注入面（构造期常量绑定）。 */
+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,
+    agentDir: string,
+    source?: 'main' | 'subagent',
+    /** S3：批量预取的 manifest 列表（避免逐 id 重复全量扫描）；单 id 不传。 */
+    prefetchedManifests?: RecordManifest[],
+  ): Promise<ResolveResult>
+  disambiguate(query: string, candidates: MatchedSession[]): ToolResult
+  safeParse(fileName: string): Promise<ParseResult>
+  /** 批量头行短 id 截断宽度（tool-handler SESSION_ID_PREFIX_LEN 同源）。 */
+  sessionIdPrefixLen: number
+}
+
+/**
+ * 从 assistant message content 提取纯 text（text 块顺序拼接）。
+ *
+ * 与 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）。
+ * 本变体的 '' 无分隔拼接是 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
+}
+
+/**
+ * 从 session entries 提取最终结果正文（与完成通知 record.result 同源，A4 逐字节一致的前置）。
+ *
+ * 同源语义（packages/subagent-core/src/execution/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 的
+ * text 块顺序拼接 → 跨 message 非空过滤 join("\\n\\n")。
+ *
+ * 取「最后一条 user message 之后」的 assistant 文本：one-shot（单 user prompt，
+ * collect:sync 的目标形态）与 join-all 逐字节一致；多轮 chatMode session 对齐
+ * 「最终一轮输出」语义。
+ *
+ * 导出供单测白盒锁定同源重建规则（message 内 '' join / 跨 message '\n\n' join /
+ * thinking 与 toolCall 排除 / 空 text 过滤 / 末 user 边界）。
+ */
+export function extractFinalAssistantText(entries: Entry[]): string {
+  let lastUserIdx = -1
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if (entries[i]?.message?.role === 'user') {
+      lastUserIdx = i
+      break
+    }
+  }
+  const texts: string[] = []
+  for (let i = lastUserIdx + 1; i < entries.length; i++) {
+    const e = entries[i]
+    if (e?.message?.role !== 'assistant') continue
+    const text = assistantMessageText(e.message.content)
+    if (text.length > 0) texts.push(text)
+  }
+  return texts.join('\n\n')
+}
+
+/** result 单条取回结果（单条 details 与批量 details.items 共用形状）。 */
+interface ResultItem {
+  /** 调用方原始输入（sa-id / uuid 片段 / 路径） */
+  session: string
+  /** 反查到的真实 session id（header id，非 sa- 占位） */
+  sessionId: string
+  /** session .jsonl 绝对路径（截断提示读原文件用） */
+  sessionFile: string
+  /** 全量正文字符数（截断前口径） */
+  totalChars: number
+  truncated: boolean
+  /** 实际展示正文（截断后含尾提示；未截断时 = 全量正文） */
+  text: string
+}
+
+/** result 截断尾提示（design §3.1.3：超出截断 + 提示读原文件）。 */
+/** result 条目截断提示行。
+ *
+ * [S8 code-simplify 口径注] 本函数的 X = **保留**字符数（limit）；而 subagent-core
+ * notifier.ts buildTruncationPointer 同模板的 X = **丢弃**字符数（total - kept）。
+ * 两处措辞同构但口径相反（主 agent 会先后消费两种通知），统一字符串 = 行为变更，
+ * 勿顺手改口径——读本行时先确认在消费哪一侧。
+ * [C6] 英文去 emoji（对齐 notifier 指针行的纯英文形态，adversarial-review-fixes §3.4）。 */
+function formatResultTruncation(
+  raw: string,
+  sessionFile: string,
+  limit: number,
+  totalChars: number,
+): string {
+  return (
+    `\n\n[truncated ${limit} of ${totalChars} chars — ` +
+    `full text: read ${sessionFile}, or session_read { action:"detail", session:"${raw}" }]`
+  )
+}
+
+/**
+ * result 的 limit 解析：缺省 8000；非有限数/非正数报错（schema 已限 Number，此处防御
+ * + 可单测绕过 schema）。向下取整防小数 slice 语义模糊。
+ */
+function resolveResultLimit(raw: number | undefined): number {
+  if (raw === undefined) return RESULT_DEFAULT_LIMIT
+  if (!Number.isFinite(raw) || raw <= 0) {
+    throw new Error(
+      `limit "${String(raw)}" 无效，需为正数。👉 传正整数重试（缺省 ${RESULT_DEFAULT_LIMIT} 字符/条）。`,
+    )
+  }
+  return Math.floor(raw)
+}
+
+/**
+ * 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()))
+  if (ids.some((id) => id === '')) {
+    throw deps.err(
+      `session 列表含空条目："${trimmed}"。👉 检查逗号分隔格式（如 "sa-aaa,sa-bbb"）重试。`,
+    )
+  }
+  if (ids.length > RESULT_MAX_BATCH) {
+    throw deps.err(
+      `批量取回 ${ids.length} 个 session 超上限：一次最多 ${RESULT_MAX_BATCH} 个。` +
+        `\n👉 分批取回（每批 ≤${RESULT_MAX_BATCH} 个 id）。`,
+    )
+  }
+  return ids
+}
+
+/**
+ * result：取回 subagent session 的最终结果正文（design subagent-sync-collect §3.1.3）。
+ *
+ * 流程：逐 id 走 resolveSessionId 三形态反查（sa-xxx manifest 精确反查 / uuid 片段 /
+ * 绝对路径，multi 走既有 disambiguate）→ safeParse → extractFinalAssistantText
+ *（与通知 record.result 同源）→ limit 截断。定位零新机制，不新造目录或文件。
+ *
+ * content 形态：单 id = 纯正文（无包装，未截断时与 record.result 逐字节一致，A4 取回门）；
+ * 批量 = 每条目 `[i/n] <原始id> (session <短id>)` 头行 + 正文，'\\n\\n---\\n\\n' join。
+ *
+ * 错误路径（明确报错不返空串）：id 无匹配（ES2/F1 风格）、manifest 有但文件不存在
+ *（ES1：GC 或 pi session 延迟写入尚未 flush）、无 assistant 输出（运行中/未写正文）、
+ * 批量超限 / 空条目 / limit 非法。
+ */
+export async function doResult(
+  params: SessionReadParams,
+  agentDir: string,
+  deps: ResultActionDeps,
+): Promise<ToolResult> {
+  const ids = parseResultSessionList(params.session, deps)
+  const limit = resolveResultLimit(params.limit)
+  // S3（code-simplify）：sa- 形态走 manifest 反查，逐 id 调用会重复全量扫 subagents/ 树
+  //（N+1）——批量入口预取一次注入。uuid 片段/路径形态不经 manifest，不预取。
+  const prefetchedManifests = ids.some((id) => id.startsWith('sa-'))
+    ? await listRecordManifests(agentDir)
+    : undefined
+  const items: ResultItem[] = []
+  for (const id of ids) {
+    const resolved = await deps.resolveSessionId(id, 'result', agentDir, params.source, prefetchedManifests)
+    if (resolved.kind === 'multi') return deps.disambiguate(resolved.query, resolved.candidates)
+    const { entries } = await deps.safeParse(resolved.fileName)
+    const text = extractFinalAssistantText(entries)
+    if (text.length === 0) {
+      throw deps.err(
+        `session "${id}" 尚无 assistant 输出（运行中或文件尚未 flush 完整）。` +
+          `\n👉 稍后重试，或用 session_read { action:"outline", session:"${id}" } 看当前进度。`,
+      )
+    }
+    const totalChars = text.length
+    const truncated = totalChars > limit
+    items.push({
+      session: id,
+      sessionId: resolved.sessionId,
+      sessionFile: resolved.fileName,
+      totalChars,
+      truncated,
+      text: truncated
+        ? text.slice(0, limit) + formatResultTruncation(id, resolved.fileName, limit, totalChars)
+        : text,
+    })
+  }
+  if (items.length === 1) {
+    const only = items[0]
+    return {
+      content: [{ type: 'text', text: only.text }],
+      details: { ...only },
+    }
+  }
+  const blocks = items.map(
+    (it, i) =>
+      `[${i + 1}/${items.length}] ${it.session} (session ${it.sessionId.slice(0, deps.sessionIdPrefixLen)}…)\n${it.text}`,
+  )
+  return {
+    content: [{ type: 'text', text: blocks.join(RESULT_BATCH_SEPARATOR) }],
+    details: { count: items.length, items },
+  }
+}