@zhushanwen/pi-session-reader 0.2.2 → 0.2.4

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "main": "index.ts",
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -22,9 +25,9 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/src/core/render.ts

@@ -3,6 +3,35 @@ import { extractToolCalls, formatToolCallSummary, type ToolCallInfo } from './to
 import type { Turn } from './turns.js'
 import type { TreeView } from './tree.js'
 
+// ---------------------------------------------------------------------------
+// 模块常量（渲染口径：截断宽度 / 换算基数 / 降级档位）
+// ---------------------------------------------------------------------------
+
+/** bytes→KB 换算基数（omitted 字节 / read 结果规模的 KB 显示）。 */
+const BYTES_PER_KB = 1024
+/** userBrief 截断字符数（TurnBrief.userBrief 文档口径「截 60 字符」）。 */
+const USER_BRIEF_MAX_CHARS = 60
+/** assistantBrief 截断字符数（TurnBrief.assistantBrief 文档口径「截 80 字符」）。 */
+const ASSISTANT_BRIEF_MAX_CHARS = 80
+/** L2 expand 单 entry brief 截断字符数。 */
+const ENTRY_BRIEF_MAX_CHARS = 100
+/** turn 索引显示宽度（T013 三位补零）。 */
+const TURN_INDEX_WIDTH = 3
+/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。 */
+const OUTLINE_DEFAULT_BUDGET_TOKENS = 2000
+/** token 估算换算基数（chars/4，与 tokenEstimate 口径一致）。 */
+const CHARS_PER_TOKEN = 4
+/** toolResult 摘要头行数（O3 摘要态展示前 N 行）。 */
+const SUMMARY_HEAD_LINE_COUNT = 3
+/** toolResult 摘要单头行截断字符数。 */
+const SUMMARY_HEAD_LINE_MAX_CHARS = 80
+
+/** 行渲染降级档位（design §3.5 算法 1 step3）：0=全有 / 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。 */
+const LINE_LEVEL_FULL = 0
+const LINE_LEVEL_NO_ASSISTANT = 1
+const LINE_LEVEL_SKELETON = 2
+type LineLevel = typeof LINE_LEVEL_FULL | typeof LINE_LEVEL_NO_ASSISTANT | typeof LINE_LEVEL_SKELETON
+
 /**
  * L1 outline 的单行 turn 摘要（design §3.5 算法 1 的渲染单元，冻结接口）。
  *
@@ -163,7 +192,7 @@ function formatToolResultSummary(
   }
   if (toolName === 'read') {
     if (resultText === '') return base
-    const kb = Math.max(1, Math.round(utf8Bytes(resultText) / 1024))
+    const kb = Math.max(1, Math.round(utf8Bytes(resultText) / BYTES_PER_KB))
     return `${base} (${kb}KB)`
   }
   return base
@@ -216,7 +245,7 @@ function computeBrief(turn: Turn): TurnBrief {
   if (turn.isCompaction) {
     const first = turn.entries[0]
     const summaryStr = typeof first?.summary === 'string' ? first.summary : ''
-    userBrief = truncate('[compaction] ' + summaryStr, 60)
+    userBrief = truncate('[compaction] ' + summaryStr, USER_BRIEF_MAX_CHARS)
   } else {
     let userText = ''
     for (const entry of turn.entries) {
@@ -225,7 +254,7 @@ function computeBrief(turn: Turn): TurnBrief {
         userText += extractText(msg.content)
       }
     }
-    userBrief = truncate(userText, 60)
+    userBrief = truncate(userText, USER_BRIEF_MAX_CHARS)
   }
 
   return {
@@ -233,7 +262,7 @@ function computeBrief(turn: Turn): TurnBrief {
     startTime: turn.startTime,
     userBrief,
     toolSummary: formatToolSummary(toolCounts),
-    assistantBrief: truncate(assistantText, 80),
+    assistantBrief: truncate(assistantText, ASSISTANT_BRIEF_MAX_CHARS),
     omittedBytes: omitted,
   }
 }
@@ -258,8 +287,8 @@ function formatHHMM(timestamp?: string): string {
 
 function formatBytesMarker(bytes: number): string {
   if (bytes <= 0) return ''
-  if (bytes < 1024) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / 1024)}KB omitted]`
+  if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
+  return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`
 }
 
 /**
@@ -268,14 +297,14 @@ function formatBytesMarker(bytes: number): string {
  * level: 0=全有（toolSummary + assistantBrief）/ 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。
  * userBrief + omittedBytes 骨架永保。assistantBrief 格式 `→ <结论>`，在 toolSummary 后、omitted 前。
  */
-function formatLine(b: TurnBrief, level: 0 | 1 | 2, branchSize?: number): string {
+function formatLine(b: TurnBrief, level: LineLevel, branchSize?: number): string {
   const parts: string[] = []
-  const head = `T${String(b.index).padStart(3, '0')}`
+  const head = `T${String(b.index).padStart(TURN_INDEX_WIDTH, '0')}`
   const time = formatHHMM(b.startTime)
   parts.push(time ? `${head} ${time}` : head)
   if (b.userBrief) parts.push(b.userBrief)
-  if (level <= 1 && b.toolSummary) parts.push(b.toolSummary)
-  if (level <= 0 && b.assistantBrief) parts.push(`→ ${b.assistantBrief}`)
+  if (level <= LINE_LEVEL_NO_ASSISTANT && b.toolSummary) parts.push(b.toolSummary)
+  if (level <= LINE_LEVEL_FULL && b.assistantBrief) parts.push(`→ ${b.assistantBrief}`)
   const marker = formatBytesMarker(b.omittedBytes)
   if (marker) parts.push(marker)
   if (branchSize !== undefined && branchSize > 0) parts.push(`[旁支 ${branchSize} entries]`)
@@ -306,7 +335,7 @@ export function renderOutline(
   tree: TreeView,
   options?: OutlineOptions,
 ): OutlineResult {
-  const budget = options?.budget ?? 2000
+  const budget = options?.budget ?? OUTLINE_DEFAULT_BUDGET_TOKENS
   const allBranches = options?.allBranches ?? false
   const granularity = options?.granularity ?? 'turn'
 
@@ -344,20 +373,20 @@ export function renderOutline(
   }
 
   // 2. perTurnBudget（token → chars×4）
-  const perTurnCharBudget = (budget / turns.length) * 4
+  const perTurnCharBudget = (budget / turns.length) * CHARS_PER_TOKEN
 
   // 3. 降级序：level 0 全有；超预算降到 level 1 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。design §3.5 算法 1 step3
   const lineCache: string[] = []
   for (const b of briefs) {
     const branchSize = b.branch !== undefined ? tree.branches.get(b.branch) : undefined
-    let line = formatLine(b, 0, branchSize)
+    let line = formatLine(b, LINE_LEVEL_FULL, branchSize)
     if (line.length > perTurnCharBudget) {
       // 超预算：先砍 assistantBrief（level 1），仍超再砍 toolSummary（level 2，骨架）
       b.assistantBrief = ''
-      line = formatLine(b, 1, branchSize)
+      line = formatLine(b, LINE_LEVEL_NO_ASSISTANT, branchSize)
       if (line.length > perTurnCharBudget) {
         b.toolSummary = ''
-        line = formatLine(b, 2, branchSize)
+        line = formatLine(b, LINE_LEVEL_SKELETON, branchSize)
       }
     }
     lineCache.push(line)
@@ -366,9 +395,9 @@ export function renderOutline(
   // 4. 总预算截断（从尾部丢弃）
   let totalChars = lineCache.reduce((s, l) => s + l.length, 0)
   let truncated: number | undefined
-  if (totalChars / 4 > budget) {
+  if (totalChars / CHARS_PER_TOKEN > budget) {
     let kept = lineCache.length
-    while (kept > 0 && totalChars / 4 > budget) {
+    while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
       kept--
       totalChars -= lineCache[kept].length
     }
@@ -377,7 +406,7 @@ export function renderOutline(
     briefs.length = kept
   }
 
-  const tokenEstimate = Math.ceil(totalChars / 4)
+  const tokenEstimate = Math.ceil(totalChars / CHARS_PER_TOKEN)
   return { turns: briefs, stats, tokenEstimate, truncated }
 }
 
@@ -405,7 +434,7 @@ function renderEntryGranularity(
       const b: TurnBrief = {
         index: entryIdx++,
         startTime: e.timestamp,
-        userBrief: truncate(text, 60) || `[${e.type}]`,
+        userBrief: truncate(text, USER_BRIEF_MAX_CHARS) || `[${e.type}]`,
         toolSummary: formatToolSummary(counts),
         assistantBrief: '',
         omittedBytes: entryOmittedBytes(e),
@@ -416,13 +445,13 @@ function renderEntryGranularity(
   }
 
   const lines = briefs.map((b) =>
-    formatLine(b, 0, b.branch !== undefined ? tree.branches.get(b.branch) : undefined),
+    formatLine(b, LINE_LEVEL_FULL, b.branch !== undefined ? tree.branches.get(b.branch) : undefined),
   )
   let totalChars = lines.reduce((s, l) => s + l.length, 0)
   let truncated: number | undefined
-  if (totalChars / 4 > budget) {
+  if (totalChars / CHARS_PER_TOKEN > budget) {
     let kept = lines.length
-    while (kept > 0 && totalChars / 4 > budget) {
+    while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
       kept--
       totalChars -= lines[kept].length
     }
@@ -433,7 +462,7 @@ function renderEntryGranularity(
   return {
     turns: briefs,
     stats,
-    tokenEstimate: Math.ceil(totalChars / 4),
+    tokenEstimate: Math.ceil(totalChars / CHARS_PER_TOKEN),
     truncated,
   }
 }
@@ -459,7 +488,7 @@ function entryBrief(e: Entry, tcMap?: Map<string, ToolCallInfo>): string {
   const msg = e.message
   if (msg !== undefined) {
     if (msg.role === 'user' || msg.role === 'assistant') {
-      return truncate(extractText(msg.content), 100) || `[${msg.role}]`
+      return truncate(extractText(msg.content), ENTRY_BRIEF_MAX_CHARS) || `[${msg.role}]`
     }
     if (msg.role === 'toolResult') {
       const toolCallId = msg.toolCallId
@@ -469,7 +498,7 @@ function entryBrief(e: Entry, tcMap?: Map<string, ToolCallInfo>): string {
   }
   if (e.type === 'compaction') {
     const s = typeof e.summary === 'string' ? e.summary : '[compaction]'
-    return truncate(s, 100)
+    return truncate(s, ENTRY_BRIEF_MAX_CHARS)
   }
   if (e.type === 'custom') return `[custom:${e.customType ?? 'unknown'}]`
   return `[${e.type}]`
@@ -479,7 +508,7 @@ export function renderExpand(turn: Turn): {
   turn: string
   entries: EntryBrief[]
 } {
-  const head = `T${String(turn.index).padStart(3, '0')}`
+  const head = `T${String(turn.index).padStart(TURN_INDEX_WIDTH, '0')}`
   const bits = [`${turn.entries.length} entries`]
   if (turn.startTime !== undefined) bits.push(`started ${formatHHMM(turn.startTime)}`)
   if (turn.isCompaction) bits.push('compaction')
@@ -559,7 +588,7 @@ export function renderDetail(
           // 空文本口径与 formatToolResultSummary 一致：空结果 = 0 行
           //（''.split('\n') 返 [''] length=1，会与 summary 的 (0行) 自相矛盾）
           const lines = text === '' ? [] : text.split('\n')
-          const headLines = lines.slice(0, 3).map((l) => truncate(l, 80)).join(' | ')
+          const headLines = lines.slice(0, SUMMARY_HEAD_LINE_COUNT).map((l) => truncate(l, SUMMARY_HEAD_LINE_MAX_CHARS)).join(' | ')
           out.push({
             type: 'toolResultSummary',
             id: e.id,

package/src/core/toolcall.ts

@@ -10,6 +10,19 @@
  */
 import type { Entry } from './parser.js'
 
+// ---------------------------------------------------------------------------
+// 模块常量（参数摘要的截断宽度 / 换算基数）
+// ---------------------------------------------------------------------------
+
+/** bash 命令参数摘要截断字符数。 */
+const BASH_CMD_MAX_CHARS = 60
+/** subagent task 参数摘要截断字符数。 */
+const SUBAGENT_TASK_MAX_CHARS = 40
+/** 未知工具 arguments JSON 摘要截断字符数。 */
+const ARGS_JSON_MAX_CHARS = 50
+/** bytes→KB 换算基数（write content 的 KB 显示）。 */
+const BYTES_PER_KB = 1024
+
 /** 单次工具调用信息（从 assistant content 的 toolCall block 提取）。 */
 export interface ToolCallInfo {
   id: string
@@ -45,8 +58,10 @@ function coerceArgs(raw: unknown): Record<string, unknown> {
       if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
         return parsed as Record<string, unknown>
       }
-    } catch {
-      // 非法 JSON 字符串 → 空对象兜底（实测 arguments 全为 object，此分支纯防御）
+    } catch (err) {
+      // 非法 JSON 字符串 → 空对象兜底（实测 arguments 全为 object，此分支纯防御）；
+      // 共享层保持零依赖（无 logger 可用），不留 void err 以外的语句
+      void err
     }
   }
   return {}
@@ -103,7 +118,7 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
   switch (name) {
     case 'bash': {
       const cmd = strArg(args, 'command')
-      return cmd !== undefined ? `bash: ${truncate(cmd, 60)}` : 'bash'
+      return cmd !== undefined ? `bash: ${truncate(cmd, BASH_CMD_MAX_CHARS)}` : 'bash'
     }
     case 'read': {
       const p = strArg(args, 'path')
@@ -122,12 +137,12 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
       const head = p !== undefined ? `write: ${basename(p)}` : 'write'
       if (c === undefined) return head
       // utf8 字节转 KB 取整；小文件至少 1KB（0KB 无信息量）
-      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / 1024))
+      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / BYTES_PER_KB))
       return `${head} (${kb}KB)`
     }
     case 'subagent': {
       const task = strArg(args, 'task')
-      return task !== undefined ? `subagent: ${truncate(task, 40)}` : 'subagent'
+      return task !== undefined ? `subagent: ${truncate(task, SUBAGENT_TASK_MAX_CHARS)}` : 'subagent'
     }
     case 'head': {
       const p = strArg(args, 'path')
@@ -159,7 +174,7 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
       // 未知工具：arguments 非空 → name: <json 前50>；空对象 → 仅 name（{} 无信息量）
       if (Object.keys(args).length === 0) return name
       try {
-        return `${name}: ${truncate(JSON.stringify(args), 50)}`
+        return `${name}: ${truncate(JSON.stringify(args), ARGS_JSON_MAX_CHARS)}`
       } catch {
         return name
       }

package/src/discovery/roots.ts

@@ -62,8 +62,10 @@ async function scanJsonlRecursive(
         try {
           const s = await stat(full)
           results.push({ path: full, mtime: s.mtimeMs, size: s.size })
-        } catch {
-          // 文件并发删除等致 stat 失败 → 跳过（不中断整体扫描）
+        } catch (err) {
+          // 文件并发删除等致 stat 失败 → 跳过（不中断整体扫描）；
+          // 本模块零 pi 依赖（无 logger 可用），不留 void err 以外的语句
+          void err
         }
       }
     }

package/src/tool-handler.ts

@@ -91,7 +91,10 @@ export interface ToolResult {
 // 小工具
 // ---------------------------------------------------------------------------
 
-const pad = (n: number): string => String(n).padStart(3, '0')
+/** turn 索引显示宽度（T013 三位补零）。 */
+const TURN_INDEX_WIDTH = 3
+
+const pad = (n: number): string => String(n).padStart(TURN_INDEX_WIDTH, '0')
 
 /** 构造带 👉 恢复指引的 Error（handler 抛出，由 execute 闭包 catch）。 */
 function err(message: string): Error {
@@ -103,24 +106,33 @@ function stripHash(s: string): string {
   return s.replace(/^#+/, '')
 }
 
+/** formatDate 日期段（月/日）补零宽度。 */
+const DATE_FIELD_WIDTH = 2
+
 function formatDate(ms: number): string {
   if (!ms) return ''
   const d = new Date(ms)
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(DATE_FIELD_WIDTH, '0')}-${String(
     d.getDate(),
-  ).padStart(2, '0')}`
+  ).padStart(DATE_FIELD_WIDTH, '0')}`
 }
 
+/** shortCwd 保留的目录末段数。 */
+const SHORT_CWD_SEGMENTS = 2
+
 /** cwd 取末两段缩短显示（完整 cwd 在 details 里）。 */
 function shortCwd(cwd: string): string {
   const parts = cwd.split('/').filter(Boolean)
-  return parts.slice(-2).join('/')
+  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 < 1024) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / 1024)}KB omitted]`
+  if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
+  return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`
 }
 
 /** F5 必填参数校验。 */
@@ -151,13 +163,16 @@ function parseTurnIndex(raw: string): number {
   return parseInt(m[1], 10)
 }
 
+/** turns 范围 "T013-T015" 的段数。 */
+const TURNS_RANGE_PARTS = 2
+
 function parseTurnsRange(raw: string): { start: number; end: number } {
   const parts = raw.split('-').map((s) => s.trim())
   if (parts.length === 1) {
     const i = parseTurnIndex(parts[0])
     return { start: i, end: i }
   }
-  if (parts.length === 2) {
+  if (parts.length === TURNS_RANGE_PARTS) {
     const start = parseTurnIndex(parts[0])
     const end = parseTurnIndex(parts[1])
     if (end < start) {
@@ -349,10 +364,15 @@ function formatSaIdAmbiguous(saId: string, records: RecordManifest[]): string {
   )
 }
 
+/** sessionId 列表行内的短显前缀长度。 */
+const SESSION_ID_PREFIX_LEN = 8
+/** 消歧提示的 uuid 片段长度（比短显略长，引导输入更长片段消歧）。 */
+const HINT_ID_PREFIX_LEN = 12
+
 /** F1 无匹配 message（含最近 10 + 👉）。 */
 function formatNoMatch(query: string, recent: MatchedSession[]): string {
   const lines: string[] = recent.length
-    ? recent.map((m, i) => `  ${i + 1}. ${m.sessionId.slice(0, 8)}… ${m.firstMessagePreview ?? ''}`.trimEnd())
+    ? recent.map((m, i) => `  ${i + 1}. ${m.sessionId.slice(0, SESSION_ID_PREFIX_LEN)}… ${m.firstMessagePreview ?? ''}`.trimEnd())
     : ['  （无历史 session）']
   return (
     `无匹配 session："${query}"。最近 ${recent.length} 个 session：\n${lines.join('\n')}\n` +
@@ -368,7 +388,7 @@ function disambiguate(query: string, candidates: MatchedSession[]): ToolResult {
   )
   const hint =
     candidates[0] !== undefined
-      ? `（如 ${candidates[0].sessionId.slice(0, 12)}）`
+      ? `（如 ${candidates[0].sessionId.slice(0, HINT_ID_PREFIX_LEN)}）`
       : ''
   const text =
     `${candidates.length} 个匹配 "${query}"：\n${lines.join('\n')}\n` +
@@ -400,7 +420,7 @@ function formatFindContent(
   truncated: boolean,
 ): string {
   const lines = matches.map((m, i) => {
-    const parts = [`${i + 1}. ${m.sessionId.slice(0, 8)}…`, formatDate(m.mtime)]
+    const parts = [`${i + 1}. ${m.sessionId.slice(0, SESSION_ID_PREFIX_LEN)}…`, formatDate(m.mtime)]
     if (m.cwd) parts.push(shortCwd(m.cwd))
     if (m.firstMessagePreview) parts.push(m.firstMessagePreview)
     return parts.join(' · ')
@@ -504,10 +524,10 @@ function formatDetailText(
     .map((e) => {
       if (isToolResultSummary(e)) {
         // v2 O3：摘要态渲染（summary + 头 3 行 + 看全文提示）
-        return `---\ntoolResultSummary (${e.id.slice(0, 8)})\n${e.summary}\n     │ 共 ${e.totalLines} 行，前 3 行：${e.headLines}\n     │ （+ includeToolResult:true 看全文）`
+        return `---\ntoolResultSummary (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${e.summary}\n     │ 共 ${e.totalLines} 行，前 3 行：${e.headLines}\n     │ （+ includeToolResult:true 看全文）`
       }
       const role = e.message ? `/${e.message.role}` : ''
-      return `---\n${e.type}${role} (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+      return `---\n${e.type}${role} (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
     })
     .join('\n')
   return `${head}\n${body}`
@@ -517,15 +537,15 @@ function formatFamilyText(f: Family): string {
   const lines: string[] = []
   lines.push(`root: ${f.root.sessionId} (${formatDate(f.root.mtime)})`)
   if (f.parents.length)
-    lines.push(`parents: ${f.parents.map((p) => p.sessionId.slice(0, 8)).join(', ')}`)
+    lines.push(`parents: ${f.parents.map((p) => p.sessionId.slice(0, SESSION_ID_PREFIX_LEN)).join(', ')}`)
   if (f.forks.length)
-    lines.push(`forks: ${f.forks.map((p) => p.sessionId.slice(0, 8)).join(', ')}`)
+    lines.push(`forks: ${f.forks.map((p) => p.sessionId.slice(0, SESSION_ID_PREFIX_LEN)).join(', ')}`)
   if (f.subagents.length)
     lines.push(
       `subagents:\n${f.subagents
         .map(
           (s) =>
-            `  ${s.sessionId.slice(0, 8)} root=${s.rootSessionId.slice(0, 8)} slug=${s.slug}${
+            `  ${s.sessionId.slice(0, SESSION_ID_PREFIX_LEN)} root=${s.rootSessionId.slice(0, SESSION_ID_PREFIX_LEN)} slug=${s.slug}${
               s.cleanedUp ? ' [已清理]' : ''
             }`,
         )
@@ -600,9 +620,12 @@ function searchableText(content: unknown): string {
   return safeStringify(content)
 }
 
+/** search 命中片段的前后上下文字符数。 */
+const SNIPPET_CONTEXT_CHARS = 20
+
 function snippet(text: string, idx: number, len: number): string {
-  const start = Math.max(0, idx - 20)
-  const end = Math.min(text.length, idx + len + 20)
+  const start = Math.max(0, idx - SNIPPET_CONTEXT_CHARS)
+  const end = Math.min(text.length, idx + len + SNIPPET_CONTEXT_CHARS)
   return (
     (start > 0 ? '…' : '') +
     text.slice(start, end).replace(/\s+/g, ' ').trim() +
@@ -614,12 +637,15 @@ function snippet(text: string, idx: number, len: number): string {
 // 各 action 实现
 // ===========================================================================
 
+/** find action 的默认匹配数上限。 */
+const FIND_DEFAULT_LIMIT = 20
+
 /** find：按片段/名称/recent 定位 session（design §3.4 find）。零匹配不抛，返回提示。 */
 async function doFind(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const query = requireStr(params.query, 'query', 'find')
   const { matches, truncated } = await findSessions(query, agentDir, {
     cwd: params.cwd,
-    limit: params.limit ?? 20,
+    limit: params.limit ?? FIND_DEFAULT_LIMIT,
     ...(params.source ? { source: params.source } : {}),
   })
   if (matches.length === 0) {
@@ -745,6 +771,9 @@ 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,
@@ -755,7 +784,7 @@ async function doSearch(
   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 ?? 20
+  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))
@@ -800,6 +829,9 @@ async function doSearch(
   return { content: [{ type: 'text', text }], details: { hits: sliced, truncated } }
 }
 
+/** export full 模式的 entry 分隔线（'=' 重复）宽度。 */
+const EXPORT_SEPARATOR_LEN = 40
+
 /** export：物化摘要到 <agentDir>/tmp/session-view-<id>.md（design §3.4 export，D-8）。 */
 async function doExport(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const format = params.format ?? 'outline'
@@ -830,9 +862,9 @@ async function doExport(params: SessionReadParams, agentDir: string): Promise<To
     text = det
       .map((e) => {
         if (isToolResultSummary(e)) {
-          return `${'='.repeat(40)}\ntoolResultSummary (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+          return `${'='.repeat(EXPORT_SEPARATOR_LEN)}\ntoolResultSummary (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
         }
-        return `${'='.repeat(40)}\n${e.type}${e.message ? '/' + e.message.role : ''} (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+        return `${'='.repeat(EXPORT_SEPARATOR_LEN)}\n${e.type}${e.message ? '/' + e.message.role : ''} (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
       })
       .join('\n')
     label = 'full'
@@ -927,10 +959,13 @@ function truncateText(s: string, max: number): string {
   return s.length <= max ? s : s.slice(0, max) + '…'
 }
 
+/** turnsLabel 展示的 turn 数上限（超出折叠为 +N）。 */
+const TURNS_LABEL_HEAD_COUNT = 5
+
 /** turns 数组紧凑标签（前 5 个 + +N，避免一行过长撑爆预算）。 */
 function turnsLabel(turns: number[]): string {
-  const head = turns.slice(0, 5).map((n) => `T${pad(n)}`)
-  const suffix = turns.length > 5 ? `+${turns.length - 5}` : ''
+  const head = turns.slice(0, TURNS_LABEL_HEAD_COUNT).map((n) => `T${pad(n)}`)
+  const suffix = turns.length > TURNS_LABEL_HEAD_COUNT ? `+${turns.length - TURNS_LABEL_HEAD_COUNT}` : ''
   return head.join(',') + suffix
 }
 
@@ -955,9 +990,12 @@ function computeToolDistribution(
     .sort((a, b) => b.count - a.count)
 }
 
+/** F8 提示展示的工具分布条数上限。 */
+const TOOL_DISTRIBUTION_LIMIT = 10
+
 /** F8：commands/tool-results 的 tool 过滤零匹配 → 返回工具分布 + 👉（不抛错，design §3.3 F8）。 */
 function f8ToolNoMatch(what: ExtractWhat, tool: string, turns: Turn[]): ToolResult {
-  const dist = computeToolDistribution(turns).slice(0, 10)
+  const dist = computeToolDistribution(turns).slice(0, TOOL_DISTRIBUTION_LIMIT)
   const distStr = dist.map((d) => `${d.name}×${d.count}`).join(', ')
   const text = `what=${what} tool="${tool}" 无匹配。该 session 工具：${distStr}。👉 用存在的工具名重试。`
   return { content: [{ type: 'text', text }], details: { what, tool, toolDistribution: dist } }
@@ -975,6 +1013,12 @@ function f8ToolNoMatch(what: ExtractWhat, tool: string, turns: Turn[]): ToolResu
  *
  * getTurns：从 item 提取 turn 列表（files 是 turns 数组，其余单值包数组），供 F9 文案报 turn 范围。
  */
+
+/** UTF8 单字符最大字节数（预算字节→字符的保守换算基数，防多字节字符被切半）。 */
+const UTF8_MAX_BYTES_PER_CHAR = 3
+/** token 估算换算基数（bytes/4 口径，与 render 层 chars/4 同近似）。 */
+const CHARS_PER_TOKEN = 4
+
 export function renderExtractItems<I>(
   what: ExtractWhat,
   items: I[],
@@ -999,7 +1043,7 @@ export function renderExtractItems<I>(
     if (bytes + lineBytes > EXTRACT_BUDGET_BYTES) {
       // 超预算：对当前 line 内部截断到剩余预算（首项超大也截断，但保留截断后的内容）
       const remainingBytes = EXTRACT_BUDGET_BYTES - bytes
-      const charBudget = Math.floor(remainingBytes / 3) // 字节→字符 ×3 近似防 UTF8 切半
+      const charBudget = Math.floor(remainingBytes / UTF8_MAX_BYTES_PER_CHAR) // 字节→字符 ×3 近似防 UTF8 切半
       if (charBudget > 0) {
         const sliced = line.slice(0, charBudget) + '…'
         shown.push(item)
@@ -1031,7 +1075,7 @@ export function renderExtractItems<I>(
     shownTurns.length > 0
       ? `（T${pad(Math.min(...shownTurns))}-T${pad(Math.max(...shownTurns))}）`
       : ''
-  const actualTokens = Math.round(Buffer.byteLength(body, 'utf8') / 4)
+  const actualTokens = Math.round(Buffer.byteLength(body, 'utf8') / CHARS_PER_TOKEN)
   const text =
     body +
     `\n[what=${what} 已显示 ${shown.length}/${items.length} 项${turnRange}，约 ${actualTokens} token 达预算上限。👉 用较小 turns 范围（如 T000-T005）缩小，或换 what 重试。]`
@@ -1148,6 +1192,9 @@ function extractFiles(turns: Turn[]): ToolResult {
  *（git 操作未被 toolResult 捕获）或误报（git log 输出里的其他 hex）。每条标注来源 turn
  * + source + context，agent 可快速辨认。完全语义判断需 LLM，本工具零 LLM 依赖。
  */
+/** commits 提取的 hash 前后上下文字符数（次路径关键词判定窗口）。 */
+const COMMIT_CONTEXT_CHARS = 30
+
 function extractCommits(turns: Turn[]): ToolResult {
   // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
   const bashCmds = new Map<string, string>()
@@ -1184,7 +1231,7 @@ function extractCommits(turns: Turn[]): ToolResult {
         const hash = m[0]
         const idx = m.index ?? 0
         const ctx = text
-          .slice(Math.max(0, idx - 30), idx + hash.length + 30)
+          .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
           .replace(/\s+/g, ' ')
           .trim()
         if (isGitBash) {
@@ -1219,6 +1266,9 @@ function extractCommits(turns: Turn[]): ToolResult {
   )
 }
 
+/** tool-results 正文截断上限（防爆）。 */
+const TOOL_RESULT_TEXT_MAX_CHARS = 500
+
 /**
  * 预设 5：tool-results——role==='toolResult' 文本（design §3.3 D3）。
  * text 截断到 500 字防爆；可选 tool 过滤（msg.toolName）；过滤零匹配 → F8。
@@ -1231,7 +1281,7 @@ function extractToolResults(turns: Turn[], tool: string | undefined): ToolResult
       if (e.message?.role !== 'toolResult') continue
       const tn = e.message.toolName ?? '?'
       if (tool !== undefined && tn !== tool) continue
-      const text = truncateText(extractContentText(e.message.content), 500)
+      const text = truncateText(extractContentText(e.message.content), TOOL_RESULT_TEXT_MAX_CHARS)
       items.push({ turn: t.index, index: ei, toolName: tn, text })
     }
   }