@zhushanwen/pi-session-reader 0.5.1 → 0.6.1

package/src/discovery/subagents.ts

@@ -2,9 +2,10 @@ import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import type { Entry } from '../core/parser.js'
-import type { Family, SessionRef, SubagentRef } from '../core/family.js'
+import type { Family, SessionRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
-import { listMainSessions, listSubagentSessions, resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
 
 /**
@@ -56,8 +57,8 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats)
   const family = resolveFamily(sessionId, index)
 
-  // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
-  enrichRefs(family, scan.pathToRef)
+  // ---- 6. workflows（enrichRefs 回填已删除，ext-simplify-04 U4/E2：fileName/cwd 占位
+  //      零文本读者，family 路径维持 core 层占位空串；富字段的消费者 = formatFamilyText 展示）----
   family.workflows = await resolveWorkflows(sessionId, scan.sessionIdToPath, scan.pathToRef)
 
   return family
@@ -71,10 +72,12 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
  * not-found 错误文案：列出实际扫描过的 main 候选根（U1 并入部分，design §6.1 自证能力
  * ——「没有这条 session」与「根配错了」必须可区分，错误信息携带发现层内部状态）。
  * 仅失败路径调用，额外一次 resolveSessionRoots 的扫描成本可接受；根过滤条件与
- * collectMainSessions 实扫集合一致（listMainSessions = agentDir 信号包下未去重的 main 根）。
+ * collectMainSessions 实扫集合一致（agentDir 信号包下未去重的 main 根）。
  */
 async function formatSessionNotFound(sessionId: string, agentDir: string): Promise<string> {
-  const mainRoots = (await resolveSessionRoots({ agentDir })).filter(
+  // subagents:'stat'——本路径只渲染 main 根行，subagent 根不做深扫（ext-simplify-04 A2：
+  // 原默认 'scan' 白扫整个 subagent 根后 filter 丢弃）
+  const mainRoots = (await resolveSessionRoots({ agentDir }, { subagents: 'stat' })).filter(
     (r) => r.source === 'main' && r.dedupedInto === undefined,
   )
   const lines = mainRoots.map((r) => {
@@ -97,9 +100,9 @@ interface FamilyFsScan {
   identities: Entry[]
   /** sessionId → { mtime, size }（buildFamilyIndex 存活判定素材） */
   fileStats: Map<string, { mtime: number; size: number }>
-  /** sessionId → 真实文件路径，供 workflows 找目标文件 + enrich 补 fileName */
+  /** sessionId → 真实文件路径，供 workflows 找目标文件 */
   sessionIdToPath: Map<string, string>
-  /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 enrich + workflow calls 反查 */
+  /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 workflow calls 反查 */
   pathToRef: Map<string, SessionRef>
   /** 已扫描到的 subagent 文件路径集合，供 manifest 孤儿判定（alive 则跳过 manifest） */
   aliveSubPaths: Set<string>
@@ -114,9 +117,13 @@ function indexManifestsBySessionFile(manifests: RecordManifest[]): Map<string, R
 
 /** 步骤 1：main sessions —— 首行 header → headers + fileStats + 路径反查 */
 async function collectMainSessions(agentDir: string, scan: FamilyFsScan): Promise<void> {
-  const mainMetas = await listMainSessions(agentDir)
+  // A3（ext-simplify-04）：直调 resolveSessionRoots + filter（原 listMainSessions 薄包装
+  // 已删除）——agentDir 信号包下 main 源未去重根（[default]+[legacy]，被 [live] 去重的除外）的文件并集
+  const mainMetas = (await resolveSessionRoots({ agentDir }))
+    .filter((r) => r.source === 'main' && r.dedupedInto === undefined)
+    .flatMap((r) => r.files)
   for (const meta of mainMetas) {
-    const h = parseHeaderLine(await readFirstLine(meta.path))
+    const h = parseSessionHeader(await readSessionHeaderFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 跳过（不入 byId）
     const entry: Entry = { type: 'session', id: h.id, parentId: null, cwd: h.cwd ?? '' }
     if (h.parentSession) entry.parentSession = h.parentSession
@@ -171,9 +178,12 @@ async function collectSubagentIdentities(
 ): Promise<void> {
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
-  const subMetas = await listSubagentSessions(agentDir)
+  // A3（ext-simplify-04）：直调 resolveSessionRoots（原 listSubagentSessions 薄包装已删除）
+  //——agentDir 信号包下 [subagent] 根 = <agentDir>/subagents（常量推导，恒唯一）
+  const subMetas =
+    (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
   for (const meta of subMetas) {
-    const h = parseHeaderLine(await readFirstLine(meta.path))
+    const h = parseSessionHeader(await readSessionHeaderFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 无真实 session id，无法 id 修正，跳过
     const realId = h.id
     // header 可解析即视为 alive（MF-3）：identity 在文件尾行、完成时才写入，运行中的 subagent
@@ -244,55 +254,12 @@ function appendOrphanIdentities(manifests: RecordManifest[], scan: FamilyFsScan)
 
 // ============================================================
 // 文件读取 helpers（定长 buffer，避免全文读：subagent 文件均 269KB、总量 ~923MB）
+// 首行 header 读取/解析在 session-header.ts（D5 单源）；本文件仅保留尾行 identity 读取。
 // ============================================================
 
-/** 首行读取 buffer 上限。session header（id/cwd/parentSession）实测 < 300 字节，8KB 足够。 */
-const HEADER_READ_BYTES = 8192
 /** 尾行 identity 读取 buffer 上限。identity 含完整 task 文本可达数 KB；实测 64KB 覆盖 3203/3430。 */
 const TAIL_READ_BYTES = 65536
 
-/** 读文件首行（header）。定长 8KB 一次 read；空文件/读失败返回 undefined。 */
-async function readFirstLine(path: string): Promise<string | undefined> {
-  let fh: FileHandle | undefined
-  try {
-    fh = await open(path, 'r')
-    const buf = Buffer.alloc(HEADER_READ_BYTES)
-    const { bytesRead } = await fh.read(buf, 0, HEADER_READ_BYTES, 0)
-    if (bytesRead === 0) return undefined
-    const text = buf.subarray(0, bytesRead).toString('utf8')
-    const nl = text.indexOf('\n')
-    return nl === -1 ? text : text.slice(0, nl)
-  } catch {
-    return undefined
-  } finally {
-    await fh?.close().catch(() => {})
-  }
-}
-
-interface SessionHeader {
-  id: string
-  cwd?: string
-  parentSession?: string
-}
-
-/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
-function parseHeaderLine(line: string | undefined): SessionHeader | null {
-  if (!line) return null
-  let raw: unknown
-  try {
-    raw = JSON.parse(line)
-  } catch {
-    return null
-  }
-  if (typeof raw !== 'object' || raw === null) return null
-  const o = raw as Record<string, unknown>
-  if (o.type !== 'session' || typeof o.id !== 'string') return null
-  const h: SessionHeader = { id: o.id }
-  if (typeof o.cwd === 'string') h.cwd = o.cwd
-  if (typeof o.parentSession === 'string') h.parentSession = o.parentSession
-  return h
-}
-
 /** readTailIdentity 的成功返回形状（rootSessionId 必有，其余存在才带） */
 type TailIdentity = {
   rootSessionId: string
@@ -488,41 +455,3 @@ export function extractSessionIdFromFilename(name: string): string {
   const candidate = idx >= 0 ? noExt.slice(idx + 1) : noExt
   return /^[0-9a-f-]{8,}$/i.test(candidate) ? candidate : ''
 }
-
-// ============================================================
-// enrich：补 M1 占位字段（fileName / subagent cwd）
-// ============================================================
-
-/**
- * M1 buildFamilyIndex 设 SessionRef.fileName=''（header 推不出路径）、subagent cwd=''
- *（identity 无 cwd）。此处用已扫描的真实文件信息补全：alive 的 ref 补 fileName + cwd；
- * cleanedUp 孤儿（无文件）保持占位。
- */
-function enrichRefs(family: Family, pathToRef: Map<string, SessionRef>): void {
-  // sessionId → 完整 ref（含真实 fileName/cwd），由 pathToRef 反建
-  const bySid = new Map<string, SessionRef>()
-  for (const ref of pathToRef.values()) bySid.set(ref.sessionId, ref)
-
-  const enrichSessionRef = (ref: SessionRef): SessionRef => {
-    const full = bySid.get(ref.sessionId)
-    if (!full) return ref
-    return {
-      ...ref,
-      fileName: full.fileName || ref.fileName,
-      cwd: full.cwd || ref.cwd,
-    }
-  }
-
-  family.root = enrichSessionRef(family.root)
-  family.parents = family.parents.map(enrichSessionRef)
-  family.forks = family.forks.map(enrichSessionRef)
-  family.subagents = family.subagents.map((s) => {
-    const full = bySid.get(s.sessionId)
-    if (!full) return s
-    return {
-      ...s,
-      fileName: full.fileName || s.fileName,
-      cwd: full.cwd || s.cwd,
-    } as SubagentRef
-  })
-}

package/src/doctor.ts

@@ -2,21 +2,12 @@
  * doctor action（u8：design 2026-09-10 §6.2/§6.3/§6.4/§7B 要点 2/4/5/8 + §6.11 U14b 段）。
  *
  * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）：环境判定 + 根表渲染 +
- * doctor 扫描缓存 + 旧布局残留 glob 探测。SessionReadSignals（u3 信号包超集）随域迁移，
- * tool-handler re-export 保持导出面不变（index.ts / 单测白盒 import 路径不变）。
- * statDirMtimeOrNull / DOCTOR_CACHE_TTL_MS 供留守的 u11 metadata 缓存复用（一并导出）。
+ * SessionReadSignals（u3 信号包超集）在域内定义，tool-handler
+ * re-export 供 index.ts 生产消费。原 u8 的扫描缓存机已删除（ext-simplify-04 U3）：
+ * 每次调用实扫，无缓存命中语义；TTL/mtime 判定随 metadata 缓存留在 tool-handler 侧。
  */
-import { existsSync } from 'node:fs'
-import { readdir, stat } from 'node:fs/promises'
-import { join, dirname } from 'node:path'
 import { detectEnvironment, type DetectedEnvironment } from './discovery/env.js'
-import {
-  resolveSessionRoots,
-  type SessionRoot,
-  type SessionRootCache,
-  type SessionRootCacheEntry,
-  type SessionRootSignals,
-} from './discovery/roots.js'
+import { resolveSessionRoots, type SessionRoot, type SessionRootSignals } from './discovery/roots.js'
 import type { SessionReadParams, ToolResult } from './tool-handler.js'
 
 /**
@@ -32,113 +23,11 @@ export interface SessionReadSignals extends SessionRootSignals {
   bundleUrl?: string
 }
 
-/**
- * doctor 扫描缓存（进程内，keyed by 根字面路径；Map 生命周期 = pi 进程生命周期，
- * 即「进程生命周期兜底上限」）。失效 = 秒级 TTL 到期 **或** 根目录 mtime 变化（任一）。
- *
- * 以 SessionRootCache 句柄注入 resolveSessionRoots（§6.3「同一数据源两处渲染」——根
- * 骨架/去重/扫描全在 roots.ts，doctor 只注入缓存与 subagent 扫描模式）；TTL/mtime
- * 失效判定全在本侧实现，roots.ts 不内置。**仅 doctor 消费——find 一律不读缓存**
- *（§7B 要点 8）：find 恒不传 options；若 find 读缓存，最坏形态是 PS-14（首条
- * assistant 前 main 根 0 文件被缓存，之后每次都把「根解析正常」误报成「主根为空」）
- * ——正是本设计要消灭的错误归因。
- */
-interface DoctorCacheEntry extends SessionRootCacheEntry {
-  /** 写入时刻（Date.now()），TTL 判定用 */
-  cachedAt: number
-  /** 根目录 mtime(ms)；目录不存在为 null（存在性翻转即失效） */
-  dirMtimeMs: number | null
-}
-
-const doctorScanCache = new Map<string, DoctorCacheEntry>()
-// §7.5 豁免（development-guide.md「纯性能缓存豁免」）：TTL 纯性能缓存，jiti 双路径加载
-// 分裂成两份仅多一次 miss 重扫，无正确性影响，不升级 globalThis 单例。
-
 /** doctor 根表来源标签列宽（最长 `[subagent]` 10 字符 + 1 对齐间距，§5.1 表格形态）。 */
 const DOCTOR_ROOT_LABEL_PAD = 11
 
-/** 缓存 TTL（秒级，§6.3）。mtime 是主失效通道；TTL 兜「子目录内增删不改变根 mtime」的陈旧面。 */
-export const DOCTOR_CACHE_TTL_MS = 5000
-
-/** stat 根目录 mtime；不存在返回 null（与缓存条目的 null 比对 = 存在性未翻转）。 */
-export async function statDirMtimeOrNull(path: string): Promise<number | null> {
-  try {
-    return (await stat(path)).mtimeMs
-  } catch (err) {
-    // 目录不存在是 doctor 的常态输入（三根降级形态），非异常——void 同 roots.ts 容错
-    void err
-    return null
-  }
-}
-
-/** doctor 侧缓存句柄：get 做失效判定（未命中即删除条目），set 快照 mtime 与写入时刻。 */
-const doctorRootCache: SessionRootCache = {
-  async get(key) {
-    const hit = doctorScanCache.get(key)
-    if (hit === undefined) return undefined
-    if (Date.now() - hit.cachedAt >= DOCTOR_CACHE_TTL_MS) {
-      doctorScanCache.delete(key)
-      return undefined
-    }
-    if ((await statDirMtimeOrNull(key)) !== hit.dirMtimeMs) {
-      doctorScanCache.delete(key)
-      return undefined
-    }
-    return { exists: hit.exists, fileCount: hit.fileCount, scanMs: hit.scanMs }
-  },
-  async set(key, value) {
-    doctorScanCache.set(key, {
-      ...value,
-      cachedAt: Date.now(),
-      dirMtimeMs: await statDirMtimeOrNull(key),
-    })
-  },
-}
-
-/** 旧布局残留条目（§6.11 U14b doctor 侧独立 glob 探测）。 */
-/** 旧布局残留探测单条命中（doctor 与 u14b 启动探测同源判据，§6.11）。 */
-export interface PiLayoutLeftover {
-  path: string
-  kind: 'backup' | 'unmigrated'
-}
-
 /**
- * 旧布局残留独立 glob 探测（§6.11 v9.1）。基点 = dirname(agentDir)（xyz-agent 下 =
- * `<dataDir>`，纯 pi 下 = `~/.pi`）；`pi/`（未迁移）与 `pi.backup-v2-` 前缀目录（迁移备份）
- * 都不在任何候选根推导式内（[legacy] 够不到带时间戳的备份名与 pi/ 层），故须独立探测。
- *
- * 形态判据（与 u14b 启动探测 / u14a 脚本 0a 同源）：目录下含 `agent/` 或 `sessions/`
- * 子目录才算残留——防纯 pi 宿主下任意来源的 `~/.pi/pi/` 目录误报。读探测，每次现查
- * 不入缓存（两次 readdir 成本可忽略，缓存只服务扫盘贵的根）。
- */
-async function detectPiLayoutLeftovers(
-  agentDir: string,
-): Promise<{ base: string; hits: PiLayoutLeftover[] }> {
-  const base = dirname(agentDir)
-  if (agentDir.length === 0) return { base, hits: [] }
-  let names: string[]
-  try {
-    names = (await readdir(base, { withFileTypes: true }))
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name)
-  } catch {
-    return { base, hits: [] }
-  }
-  const hits: PiLayoutLeftover[] = []
-  for (const name of names) {
-    const isUnmigrated = name === 'pi'
-    const isBackup = name.startsWith('pi.backup-v2-')
-    if (!isUnmigrated && !isBackup) continue
-    const dir = join(base, name)
-    // 形态判据：含 agent/ 或 sessions/ 子目录（迁移备份必含其一——备份即原 pi/ 改名）
-    if (!existsSync(join(dir, 'agent')) && !existsSync(join(dir, 'sessions'))) continue
-    hits.push({ path: dir, kind: isBackup ? 'backup' : 'unmigrated' })
-  }
-  return { base, hits }
-}
-
-/**
- * doctor：环境判定 + 根表 + 事实型诊断 + legacy 非空告警 + 旧布局残留探测。
+ * doctor：环境判定 + 根表 + 事实型诊断 + legacy 非空告警。
  *
  * 诊断结论只陈述事实（「最高优先级 main 根 N 文件」），禁止「真的没有 session」类
  * 归因断言（§7B 要点 5 / §3.3 教训）；env/bundleUrl 信号缺失时环境判定按降级输出，
@@ -155,12 +44,10 @@ export async function doDoctor(
   })
   const roots = await resolveSessionRoots(signals, {
     // subagent 根默认只 stat（§6.3 成本控制：只列路径与可扫性）；includeSubagents:true
-    // 才扫（走同一缓存句柄）。find/F1 路径恒不传 options——不读缓存（§7B 要点 8）。
+    // 才扫。无缓存——每次实扫（原缓存机已删，ext-simplify-04 U3，§7B 要点 8 新态）。
     subagents: params.includeSubagents === true ? 'scan' : 'stat',
-    cache: doctorRootCache,
   })
-  const leftovers = await detectPiLayoutLeftovers(signals.agentDir)
-  return renderDoctor(roots, environment, leftovers)
+  return renderDoctor(roots, environment)
 }
 
 /**
@@ -170,24 +57,21 @@ export async function doDoctor(
 export interface DoctorDetails {
   environment: DetectedEnvironment
   roots: SessionRoot[]
-  leftovers: PiLayoutLeftover[]
-  globBase: string
 }
 
 /**
  * 渲染 doctor 输出（§5.1 形态）：环境判定 + evidence + 会话根表（来源标签/路径/存在/
- * 文件数/扫描耗时/去重注记）+ 事实型诊断 + legacy 非空告警 + 旧布局残留（命中才出现）。
+ * 文件数/扫描耗时/去重注记）+ 事实型诊断 + legacy 非空告警。
  */
 function renderDoctor(
   roots: SessionRoot[],
   environment: DetectedEnvironment,
-  leftovers: { base: string; hits: PiLayoutLeftover[] },
 ): ToolResult {
   const lines: string[] = []
 
   // 环境判定行 + evidence（§6.2：判定可被证据推翻，非黑盒断言；evidence 恒非空）
   lines.push(
-    `环境判定：${environment.kind === 'xyz-agent' ? 'xyz-agent（托管）' : 'standalone-pi'}` +
+    `环境判定：${environment.kind === 'taiji' ? 'taiji（托管）' : 'standalone-pi'}` +
       ` · 发行形态：${environment.distribution ?? '未知（不猜）'}`,
   )
   if (environment.dataDir !== undefined) lines.push(`数据目录：${environment.dataDir}`)
@@ -206,19 +90,18 @@ function renderDoctor(
     }
     const facts = [r.exists ? '存在' : '不存在']
     if (r.fileCount === undefined) {
-      // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数
-      //（实扫或缓存命中）；被去重根已在上方提前返回
+      // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数（实扫）；
+      // 被去重根已在上方提前返回
       facts.push('未扫描（subagent 根默认不扫，includeSubagents:true 开启）')
     } else {
       facts.push(`${r.fileCount} 文件`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     }
-    if (r.cached === true) facts.push('缓存命中')
     facts.push(r.source === 'main' ? 'main' : 'subagent')
     lines.push(`     ${facts.join(' · ')}`)
   })
 
   // 事实型诊断（§7B 要点 5）：列表内首个 main 根即最高优先级 main 根（去重只移除后位根，
-  // 首位根恒有计数——实扫或缓存命中）。0 文件也是事实——首条 assistant 前 jsonl 不落盘
+  // 首位根恒有计数——实扫）。0 文件也是事实——首条 assistant 前 jsonl 不落盘
   //（PS-14），不做归因。
   lines.push('')
   const firstMain = roots.find((r) => r.source === 'main')
@@ -238,25 +121,11 @@ function renderDoctor(
     )
   }
 
-  // 旧布局残留（§6.11：命中才列，附同一迁移指引）
-  if (leftovers.hits.length > 0) {
-    lines.push('')
-    lines.push(`旧布局残留探测（基点 ${leftovers.base}）：`)
-    for (const h of leftovers.hits) {
-      lines.push(
-        `  - ${h.path}（${h.kind === 'backup' ? '迁移备份 pi.backup-v2-*' : '未迁移旧布局 pi/'}）`,
-      )
-    }
-    lines.push('  👉 关闭应用后运行 scripts/migrate-pi-layout-v2.mjs 完成迁移。')
-  }
-
   return {
     content: [{ type: 'text', text: lines.join('\n') }],
     details: {
       environment,
       roots,
-      leftovers: leftovers.hits,
-      globBase: leftovers.base,
     } satisfies DoctorDetails,
   }
 }

package/src/extract.ts

@@ -4,9 +4,9 @@
  * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）。
  * design §3.3 D3 的 5 个预设 + F8/F9 规格；F7（what 校验）与 doExtract 编排
  *（resolveSessionId/safeParse/turns 范围限定依赖 tool-handler 私有定位层）留守
- * tool-handler，经本模块导出的 5 预设函数分发。renderExtractItems 导出面不变：
- * tool-handler re-export（单测 F9 白盒 import 路径不变）。纯提取，不调 LLM。
+ * tool-handler，经本模块导出的 5 预设函数分发。纯提取，不调 LLM。
  */
+import { textBlockParts } from './core/render.js'
 import { extractToolCalls, formatToolCallSummary, basename } from './core/toolcall.js'
 import type { Turn } from './core/turns.js'
 import { pad } from './handler-utils.js'
@@ -29,25 +29,12 @@ const SHORT_HASH_RE = /\b[0-9a-f]{7,8}\b/g
 const COMMIT_CTX_RE = /feat:|fix:|refactor:|chore:|docs:|\b(commit|commits|merged|pushed|merge)\b/i
 
 /**
- * 从 message.content 提取纯 text（string 直取；数组拼接 text 块）。
- *
- * 与 render.ts 内部 extractText 同语义，但那未导出；extract 仅需纯 text
- *（user-messages / tool-results 的正文），不要 thinking/toolCall 占位，本地实现。
- * content 是 unknown 做类型守卫。
+ * 从 message.content 提取纯 text（E11 归一：共享核 textBlockParts 组合调用，'\n' join
+ * 语义留在本调用点）。extract 仅需纯 text（user-messages / tool-results 的正文），
+ * 不要 thinking/toolCall 占位。
  */
 function extractContentText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (Array.isArray(content)) {
-    const parts: string[] = []
-    for (const b of content) {
-      if (b !== null && typeof b === 'object') {
-        const o = b as Record<string, unknown>
-        if (o.type === 'text' && typeof o.text === 'string') parts.push(o.text)
-      }
-    }
-    return parts.join('\n')
-  }
-  return ''
+  return textBlockParts(content).join('\n')
 }
 
 /** 截断到 max 字符，超出加省略号（防爆；tool-results 正文用）。 */

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/index.ts

@@ -157,7 +157,7 @@ const guidelines = [
   "workflow action to see workflow run overviews (status/budget/steps). Each step's call sessionId can jump to outline/detail for deep reading.",
   "result action to fetch a subagent's final result text (same content as its completion notice): session takes a single sa-id/uuid/path or a comma-separated batch of at most 10; optional limit caps chars per item (default 8000, truncated items carry a pointer to the full file).",
   'Errors carry a 👉 recovery hint—follow it to retry in one step.',
-  'Unsure about the host environment (pure pi vs xyz-agent) or where session roots live? Run action:"doctor" first—it prints the detected environment and every candidate session root.',
+  'Unsure about the host environment (pure pi vs taiji) or where session roots live? Run action:"doctor" first—it prints the detected environment and every candidate session root.',
 ]
 
 // ---- 工具 description（design §3.4，照搬措辞）----
@@ -231,7 +231,7 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
 
   // ── M4 TUI 层（design §1 + §3.3 D-3/D-4 + 附录 P-hash-trigger）──────────
   // # 引用补全 provider + /session-pick 命令（命令名避开 pi 内置 /session 冲突）。仅 ctx.mode === 'tui' 注册：RPC 模式
-  // （xyz-agent 子进程）不用 pi TUI editor / slash 命令，加载即跳过。
+  // （taiji 子进程）不用 pi TUI editor / slash 命令，加载即跳过。
   //
   // addAutocompleteProvider 挂在 ctx.ui（非 ExtensionAPI），setup 入口无 ctx，
   // 只能在 event handler 里拿——session_start 是最早且每 session 触发的 event。

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 实扫文件名提取的