agentquad 0.3.0

package/src/session-input-dispatcher.js

@@ -0,0 +1,256 @@
+/**
+ * Session Input Dispatcher
+ *
+ * 所有 "把用户文本投递到一个 Claude Code session" 的路径都走这里。
+ * 三档语义：
+ *   - queue_or_send  ：普通文本，busy 时入队，idle 时直发
+ *   - soft_interrupt ：`!` 前缀，busy 时 Esc → 250ms 后投递新文本，丢弃旧队列
+ *   - hard_cancel    ：`!!` 前缀 或精确 `/stop`，busy 时 Ctrl+C，不投递文本
+ */
+
+const QUEUE_LIMIT = 20
+const STALE_MS = 5 * 60 * 1000
+const SOFT_INTERRUPT_DELAY_MS = 250
+// 安全网：awaitingReply=false 但 PTY 已经 N 毫秒没 output → 视为 idle，直接写。
+// 历史 bug：浏览器 / REST 上无关的 input 把 awaitingReply 推回 false 后，dispatcher
+// 把 IM 消息全部 queue，必须等下次 Stop hook 才会 flush；如果 Claude 没新输入就一直卡。
+// 这里给 dispatcher 一个 "Claude 大概率在 idle prompt" 的兜底判断（PTY busy 时是连续
+// 输出 spinner / token，3s 静默基本不可能是真 busy）。
+const IDLE_GRACE_MS = 3000
+
+export function parseTrigger(rawText) {
+  const text = String(rawText || '').trim()
+  if (text === '/stop') return { mode: 'hard_cancel', stripped: '' }
+  if (text.startsWith('!!')) return { mode: 'hard_cancel', stripped: '' }
+  if (text.startsWith('!')) return { mode: 'soft_interrupt', stripped: text.slice(1).trim() }
+  return { mode: 'queue_or_send', stripped: text }
+}
+
+function buildPayload(text, imagePaths) {
+  if (!imagePaths || imagePaths.length === 0) return text
+  const ats = imagePaths.map((p) => `@${p}`).join(' ')
+  return text ? `${ats} ${text}` : ats
+}
+
+function writeToPty(pty, sessionId, payload, logger) {
+  pty.write(sessionId, payload)
+  setTimeout(() => {
+    try { pty.write(sessionId, '\r') } catch (e) {
+      logger?.warn?.(`[dispatcher] submit \\r failed sid=${sessionId}: ${e.message}`)
+    }
+  }, 80)
+}
+
+// 写真实文本到 PTY 后，更新 ai-terminal awaitingReply=false（"已经把输入交给 Claude，现在它在干活"）。
+// 写 Esc / Ctrl+C 这类控制字符不调用此函数，因为它们让 Claude 回到 idle prompt 而不是开始新 turn。
+function markBusyAfterWrite(aiTerminal, sessionId) {
+  try { aiTerminal.markSessionAwaitingReply?.(sessionId, false) } catch { /* ignore */ }
+}
+
+export function createSessionInputDispatcher({ pty, aiTerminal, callbacks = {}, logger = console } = {}) {
+  if (!pty) throw new Error('pty_required')
+  if (!aiTerminal) throw new Error('aiTerminal_required')
+
+  // sessionId → QueueState { items, firstEchoMessageId, staleTimer }
+  const queues = new Map()
+  // sessionId set: 软中断 250ms 窗口内
+  const softInterrupting = new Set()
+
+  function getOrCreateQueue(sessionId) {
+    let q = queues.get(sessionId)
+    if (!q) {
+      q = { items: [], staleTimer: null, firstEchoMessageId: null }
+      queues.set(sessionId, q)
+    }
+    return q
+  }
+
+  async function enqueue({ sessionId, stripped, imagePaths, channel, echoTarget }) {
+    const q = getOrCreateQueue(sessionId)
+    if (q.items.length >= QUEUE_LIMIT) {
+      return { full: true, queueSize: q.items.length }
+    }
+    q.items.push({ text: stripped, imagePaths, enqueuedAt: Date.now() })
+    if (q.staleTimer) clearTimeout(q.staleTimer)
+    q.staleTimer = setTimeout(() => {
+      if (callbacks.onStale) {
+        Promise.resolve(callbacks.onStale({ sessionId, channel, echoTarget, queueSize: q.items.length }))
+          .catch((e) => logger?.warn?.(`[dispatcher] onStale failed: ${e.message}`))
+      }
+    }, STALE_MS)
+    const isFirst = q.items.length === 1
+    const cb = isFirst ? callbacks.onQueueFirstEnqueue : callbacks.onQueueAdditionalEnqueue
+    if (cb) {
+      try {
+        const echo = await cb({ sessionId, channel, echoTarget, queueSize: q.items.length })
+        if (isFirst && echo?.messageId) q.firstEchoMessageId = echo.messageId
+      } catch (e) {
+        logger?.warn?.(`[dispatcher] echo callback failed: ${e.message}`)
+      }
+    }
+    return { full: false, queueSize: q.items.length }
+  }
+
+  async function send({ sessionId, text, imagePaths = [], channel, echoTarget } = {}) {
+    if (!pty.has(sessionId)) {
+      return { action: 'session_ended', sessionId }
+    }
+    const { mode, stripped } = parseTrigger(text)
+    let idle = aiTerminal.isSessionAwaitingReply(sessionId)
+
+    // 兜底：awaitingReply=false 但 PTY 已经静默 ≥ IDLE_GRACE_MS → 视为 idle 直发。
+    // 不动 hard_cancel —— 那一档不依赖 idle 状态（无条件发 \x03 中断），
+    // 这里加 grace 反而会让 idle 走 noop_idle 分支吞掉用户的 /stop。
+    if (!idle && mode !== 'hard_cancel') {
+      try {
+        const sess = aiTerminal?.sessions?.get?.(sessionId)
+        const lastOut = sess?.lastOutputAt || 0
+        if (lastOut > 0 && (Date.now() - lastOut) >= IDLE_GRACE_MS) {
+          logger?.info?.(`[dispatcher] idle-grace promote sid=${sessionId} silent_for_ms=${Date.now() - lastOut} (awaitingReply=${sess?.awaitingReply})`)
+          idle = true
+        }
+      } catch { /* ignore */ }
+    }
+
+    if (idle) {
+      if (mode === 'hard_cancel') {
+        return { action: 'noop_idle', sessionId }
+      }
+      // queue_or_send / soft_interrupt 在 idle 下都等同直发 stripped
+      const payload = buildPayload(stripped, imagePaths)
+      writeToPty(pty, sessionId, payload, logger)
+      markBusyAfterWrite(aiTerminal, sessionId)
+      return { action: 'sent', sessionId }
+    }
+
+    if (mode === 'queue_or_send') {
+      // 诊断：busy 判定 = aiTerminal.isSessionAwaitingReply(sid) 返回 false。Stop hook
+      // 应该已经把 awaitingReply 置 true 了，跑到这里说明 (a) hook 没 fire (b) markS... no-op
+      // (c) 中间被 web UI / REST input / PTY exit 重置回去了。把当前快照打出来，便于排查
+      // "飞书发消息一直被排队"这类卡死。
+      try {
+        const sess = aiTerminal?.sessions?.get?.(sessionId)
+        logger?.warn?.(`[dispatcher] queueing (idle=false) sid=${sessionId} sessionExists=${!!sess} status=${sess?.status || 'null'} awaitingReply=${sess?.awaitingReply} text=${String(stripped || '').slice(0, 40)}`)
+      } catch { /* ignore diag */ }
+      const r = await enqueue({ sessionId, stripped, imagePaths, channel, echoTarget })
+      if (r.full) return { action: 'queue_full', queueSize: r.queueSize, sessionId }
+      return { action: 'queued', queueSize: r.queueSize, sessionId }
+    }
+
+    if (mode === 'soft_interrupt') {
+      if (softInterrupting.has(sessionId)) {
+        // 250ms 窗口内的第 2 个 ! → 降级为入队
+        const r = await enqueue({ sessionId, stripped, imagePaths, channel, echoTarget })
+        if (r.full) return { action: 'queue_full', queueSize: r.queueSize, sessionId }
+        return { action: 'queued', queueSize: r.queueSize, reason: 'soft_interrupt_in_progress', sessionId }
+      }
+      return await performSoftInterrupt({ sessionId, stripped, imagePaths })
+    }
+
+    if (mode === 'hard_cancel') {
+      return await performHardCancel({ sessionId, channel, echoTarget })
+    }
+
+    return { action: 'noop', reason: 'unknown_mode', sessionId }
+  }
+
+  async function performHardCancel({ sessionId, channel, echoTarget }) {
+    const q = queues.get(sessionId)
+    if (q) {
+      if (q.staleTimer) clearTimeout(q.staleTimer)
+      queues.delete(sessionId)
+    }
+    pty.write(sessionId, '\x03')
+    if (callbacks.onHardCancel) {
+      try { await callbacks.onHardCancel({ sessionId, channel, echoTarget }) }
+      catch (e) { logger?.warn?.(`[dispatcher] onHardCancel callback failed: ${e.message}`) }
+    }
+    return { action: 'hard_cancelled', sessionId }
+  }
+
+  async function performSoftInterrupt({ sessionId, stripped, imagePaths }) {
+    // 丢弃旧队列
+    const q = queues.get(sessionId)
+    if (q) {
+      if (q.staleTimer) clearTimeout(q.staleTimer)
+      queues.delete(sessionId)
+    }
+    // 立刻发 Esc
+    pty.write(sessionId, '\x1b')
+    softInterrupting.add(sessionId)
+    // 等 TUI 回到 prompt
+    await new Promise((resolve) => setTimeout(resolve, SOFT_INTERRUPT_DELAY_MS))
+    softInterrupting.delete(sessionId)
+    // 投递新文本（如果有）
+    if (stripped || (imagePaths && imagePaths.length)) {
+      const payload = buildPayload(stripped, imagePaths)
+      writeToPty(pty, sessionId, payload, logger)
+      markBusyAfterWrite(aiTerminal, sessionId)
+    }
+    return { action: 'soft_interrupted', sessionId }
+  }
+
+  async function flushQueue(sessionId) {
+    const q = queues.get(sessionId)
+    if (!q || q.items.length === 0) return { flushed: 0 }
+    const allImages = []
+    const texts = []
+    for (const item of q.items) {
+      if (item.imagePaths && item.imagePaths.length) allImages.push(...item.imagePaths)
+      if (item.text) texts.push(item.text)
+    }
+    const count = q.items.length
+    const combinedText = texts.join('\n')
+    const payload = buildPayload(combinedText, allImages)
+    if (q.staleTimer) { clearTimeout(q.staleTimer); q.staleTimer = null }
+    queues.delete(sessionId)
+    try {
+      writeToPty(pty, sessionId, payload, logger)
+      markBusyAfterWrite(aiTerminal, sessionId)
+    } catch (e) {
+      logger?.warn?.(`[dispatcher] flush write failed sid=${sessionId}: ${e.message}`)
+      return { flushed: 0, error: e.message }
+    }
+    if (callbacks.onFlush) {
+      try { await callbacks.onFlush({ sessionId, count }) }
+      catch (e) { logger?.warn?.(`[dispatcher] onFlush callback failed: ${e.message}`) }
+    }
+    return { flushed: count }
+  }
+
+  async function onSessionIdle(sessionId) {
+    return flushQueue(sessionId)
+  }
+
+  async function onSessionEnd(sessionId) {
+    const q = queues.get(sessionId)
+    if (!q) return
+    if (q.staleTimer) clearTimeout(q.staleTimer)
+    const undelivered = q.items.slice()
+    queues.delete(sessionId)
+    if (callbacks.onSessionEnd) {
+      try {
+        await callbacks.onSessionEnd({
+          sessionId,
+          undeliveredCount: undelivered.length,
+          undeliveredTexts: undelivered.map((it) => it.text),
+        })
+      } catch (e) {
+        logger?.warn?.(`[dispatcher] onSessionEnd callback failed: ${e.message}`)
+      }
+    }
+  }
+
+  function describe() {
+    const byId = {}
+    for (const [sid, q] of queues.entries()) {
+      byId[sid] = {
+        queueSize: q.items.length,
+        oldestEnqueuedAt: q.items[0]?.enqueuedAt ?? null,
+      }
+    }
+    return { sessions: queues.size, byId }
+  }
+
+  return { send, onSessionIdle, onSessionEnd, describe, __test__: { queues, parseTrigger } }
+}

package/src/stats/markdown.js

@@ -0,0 +1,42 @@
+function fmtHours(ms) {
+	return (ms / 3600_000).toFixed(1) + 'h'
+}
+
+function fmtTokens(n) {
+	if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + 'M'
+	if (n >= 1_000) return (n / 1_000).toFixed(1) + 'K'
+	return String(n)
+}
+
+function fmtDate(ms) {
+	const d = new Date(ms)
+	return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+
+function fmtCost(c) {
+	return `$${c.usd.toFixed(2)} / ¥${c.cny.toFixed(1)}`
+}
+
+export function renderMarkdown(r) {
+	const { range, summary, topTodos, byModel } = r
+	const lines = []
+	const title = range.label === '本月' ? '月报' : '周报'
+	lines.push(`# AgentQuad ${title} · ${fmtDate(range.since)} ~ ${fmtDate(range.until)}`)
+	lines.push('')
+	lines.push(`AI 活跃 ${fmtHours(summary.activeMs)}（墙钟 ${fmtHours(summary.wallClockMs)}）· ${summary.sessionCount} 场会话 · 覆盖 ${summary.todoCount} 个任务`)
+	lines.push(`Token ${fmtTokens(summary.tokens.total)}（cache 命中 ${fmtTokens(summary.tokens.cacheRead)}）· 成本 ${fmtCost(summary.cost)}`)
+	if (summary.unboundSessionCount > 0) {
+		lines.push(`> 其中 ${summary.unboundSessionCount} 场未关联任务`)
+	}
+	lines.push('')
+	lines.push('## Top 10 任务')
+	topTodos.forEach((t, i) => {
+		lines.push(`${i + 1}. ${t.title} — 活跃 ${fmtHours(t.activeMs)} · ${fmtCost(t.cost)} · ${t.sessionCount} 场`)
+	})
+	lines.push('')
+	lines.push('## 按模型')
+	for (const m of byModel) {
+		lines.push(`- ${m.key}: ${m.sessions} 场 · ${fmtTokens(m.tokens.input + m.tokens.output)} tok · ${fmtCost(m.cost)}`)
+	}
+	return lines.join('\n')
+}

package/src/stats/report.js

@@ -0,0 +1,207 @@
+import { estimateCost } from '../pricing.js'
+
+function addTokens(a, b) {
+	return {
+		input: a.input + b.input,
+		output: a.output + b.output,
+		cacheRead: a.cacheRead + b.cacheRead,
+		cacheCreation: a.cacheCreation + b.cacheCreation,
+	}
+}
+
+const ZERO = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 }
+const ZERO_COST = { usd: 0, cny: 0 }
+
+function fileTokens(f) {
+	return {
+		input: f.input_tokens || 0,
+		output: f.output_tokens || 0,
+		cacheRead: f.cache_read_tokens || 0,
+		cacheCreation: f.cache_creation_tokens || 0,
+	}
+}
+
+function addCost(a, b) {
+	return { usd: a.usd + b.usd, cny: a.cny + b.cny }
+}
+
+// 每个 transcript_file 按其自身 primary_model 计价。混合模型的桶（summary /
+// byTool / byQuadrant / timeline / 某个 todo 下同时跑了 Opus 和 Sonnet）必须先
+// 逐文件算成本再求和，否则"合并 token 后按单一费率算"会把 Opus 的钱按
+// Sonnet 价打折（低估 5x），或把 Haiku 按 Sonnet 价虚高（高估 3x）。
+function fileCost(f, pricing) {
+	return estimateCost(fileTokens(f), f.primary_model, pricing)
+}
+
+function pickBucketSize(since, until) {
+	return (until - since) > 7 * 86400_000 ? 86400_000 : 3600_000
+}
+
+export function buildReport(db, { since, until = Date.now(), pricing, topN = 10 }) {
+	const raw = db.raw
+	const files = raw.prepare(`
+		SELECT * FROM transcript_files
+		WHERE started_at IS NOT NULL AND started_at >= ? AND started_at < ?
+	`).all(since, until)
+
+	const logs = raw.prepare(`
+		SELECT * FROM ai_session_log
+		WHERE completed_at >= ? AND completed_at < ?
+	`).all(since, until)
+
+	// Build nativeId → todoId fallback map so stats 不用等下一次 scan 补 bound_todo_id
+	// 覆盖：transcript_files.bound_todo_id 为空、但 transcript.native_id 能在任何 todo.aiSessions[] 里找到
+	const todos = db.listTodos()
+	const nativeToTodo = new Map()
+	for (const t of todos) {
+		for (const s of (t.aiSessions || [])) {
+			if (s?.nativeSessionId && s?.tool) {
+				nativeToTodo.set(`${s.tool}:${s.nativeSessionId}`, t.id)
+			}
+		}
+	}
+	const effectiveTodoId = (f) => f.bound_todo_id
+		|| (f.native_id ? nativeToTodo.get(`${f.tool}:${f.native_id}`) : null)
+		|| null
+
+	// summary
+	let totalTokens = { ...ZERO }
+	let totalCost = { ...ZERO_COST }
+	let totalActive = 0
+	let totalWall = 0
+	const coveredTodos = new Set()
+	let unbound = 0
+	for (const f of files) {
+		totalTokens = addTokens(totalTokens, fileTokens(f))
+		totalCost = addCost(totalCost, fileCost(f, pricing))
+		totalActive += f.active_ms || 0
+		const tid = effectiveTodoId(f)
+		if (tid) coveredTodos.add(tid)
+		else unbound++
+	}
+	for (const l of logs) totalWall += l.duration_ms || 0
+
+	// topTodos: group files by effective todoId（bound 或 通过 nativeId 回填）
+	const todoAgg = new Map()
+	for (const f of files) {
+		const tid = effectiveTodoId(f)
+		if (!tid) continue
+		const bucket = todoAgg.get(tid) || {
+			todoId: tid, activeMs: 0, tokens: { ...ZERO }, cost: { ...ZERO_COST }, sessions: 0, models: new Map(),
+		}
+		bucket.activeMs += f.active_ms || 0
+		bucket.tokens = addTokens(bucket.tokens, fileTokens(f))
+		bucket.cost = addCost(bucket.cost, fileCost(f, pricing))
+		bucket.sessions += 1
+		if (f.primary_model) bucket.models.set(f.primary_model, (bucket.models.get(f.primary_model) || 0) + 1)
+		todoAgg.set(tid, bucket)
+	}
+	// wall clock per todo from ai_session_log
+	const todoWall = new Map()
+	for (const l of logs) {
+		todoWall.set(l.todo_id, (todoWall.get(l.todo_id) || 0) + (l.duration_ms || 0))
+	}
+
+	const todoById = new Map(todos.map(t => [t.id, t]))
+
+	const topTodos = [...todoAgg.values()]
+		.map(b => {
+			const t = todoById.get(b.todoId)
+			const topModel = [...b.models.entries()].sort((a, c) => c[1] - a[1])[0]?.[0] || null
+			return {
+				todoId: b.todoId,
+				title: t?.title || '(已删除)',
+				quadrant: t?.quadrant || 0,
+				activeMs: b.activeMs,
+				wallClockMs: todoWall.get(b.todoId) || 0,
+				tokens: b.tokens,
+				cost: b.cost,
+				sessionCount: b.sessions,
+				primaryModel: topModel,
+			}
+		})
+		.sort((a, b) => {
+			if (b.activeMs !== a.activeMs) return b.activeMs - a.activeMs
+			const aTok = a.tokens.input + a.tokens.output + a.tokens.cacheRead + a.tokens.cacheCreation
+			const bTok = b.tokens.input + b.tokens.output + b.tokens.cacheRead + b.tokens.cacheCreation
+			return bTok - aTok
+		})
+		.slice(0, topN)
+
+	// byTool / byQuadrant / byModel
+	const byTool = aggregateBy(files, logs, f => f.tool, l => l.tool, pricing)
+	const byQuadrant = aggregateBy(files, logs,
+		f => { const t = todoById.get(effectiveTodoId(f)); return t ? t.quadrant : null },
+		l => l.quadrant, pricing)
+	const byModel = aggregateBy(files, [], f => f.primary_model || '(unknown)', () => null, pricing, { includeWall: false })
+
+	// timeline
+	const bucketSize = pickBucketSize(since, until)
+	const timelineMap = new Map()
+	for (const f of files) {
+		const b = Math.floor((f.started_at || since) / bucketSize) * bucketSize
+		const cur = timelineMap.get(b) || { t: b, wallClockMs: 0, activeMs: 0, tokens: { ...ZERO }, cost: { ...ZERO_COST } }
+		cur.activeMs += f.active_ms || 0
+		cur.tokens = addTokens(cur.tokens, fileTokens(f))
+		cur.cost = addCost(cur.cost, fileCost(f, pricing))
+		timelineMap.set(b, cur)
+	}
+	for (const l of logs) {
+		const b = Math.floor(l.completed_at / bucketSize) * bucketSize
+		const cur = timelineMap.get(b) || { t: b, wallClockMs: 0, activeMs: 0, tokens: { ...ZERO }, cost: { ...ZERO_COST } }
+		cur.wallClockMs += l.duration_ms || 0
+		timelineMap.set(b, cur)
+	}
+	const timeline = [...timelineMap.values()].sort((a, b) => a.t - b.t)
+
+	return {
+		range: { since, until, label: rangeLabel(since, until) },
+		summary: {
+			wallClockMs: totalWall,
+			activeMs: totalActive,
+			tokens: { ...totalTokens, total: totalTokens.input + totalTokens.output + totalTokens.cacheRead + totalTokens.cacheCreation },
+			cost: totalCost,
+			// transcripts 是 AI 活动的权威来源；ai_session_log 仅覆盖经过 PTY runner 的会话
+			sessionCount: files.length,
+			todoCount: coveredTodos.size,
+			unboundSessionCount: unbound,
+		},
+		topTodos,
+		byTool,
+		byQuadrant,
+		byModel,
+		timeline,
+	}
+}
+
+function aggregateBy(files, logs, keyF, keyL, pricing, { includeWall = true } = {}) {
+	const m = new Map()
+	for (const f of files) {
+		const k = keyF(f)
+		if (k == null) continue
+		const cur = m.get(k) || { key: k, sessions: 0, activeMs: 0, wallClockMs: 0, tokens: { ...ZERO }, cost: { ...ZERO_COST } }
+		cur.sessions += 1
+		cur.activeMs += f.active_ms || 0
+		cur.tokens = addTokens(cur.tokens, fileTokens(f))
+		cur.cost = addCost(cur.cost, fileCost(f, pricing))
+		m.set(k, cur)
+	}
+	if (includeWall) {
+		for (const l of logs) {
+			const k = keyL(l)
+			if (k == null) continue
+			const cur = m.get(k) || { key: k, sessions: 0, activeMs: 0, wallClockMs: 0, tokens: { ...ZERO }, cost: { ...ZERO_COST } }
+			cur.wallClockMs += l.duration_ms || 0
+			m.set(k, cur)
+		}
+	}
+	return [...m.values()]
+}
+
+function rangeLabel(since, until) {
+	const days = Math.round((until - since) / 86400_000)
+	if (days === 7) return '本周'
+	if (days === 30) return '近 30 天'
+	if (days >= 28 && days <= 31) return '本月'
+	return '自定义'
+}

package/src/summarize.js

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process'
+
+const MAX_INPUT_CHARS = 24000
+
+function turnsToText(turns) {
+  const lines = []
+  for (const t of turns) {
+    const role = t.role === 'user' ? '用户'
+      : t.role === 'assistant' ? 'AI'
+      : t.role === 'thinking' ? '思考'
+      : t.role === 'tool_use' ? `工具调用(${t.toolName || ''})`
+      : t.role === 'tool_result' ? '工具输出'
+      : t.role
+    const content = String(t.content || '').slice(0, 2000)
+    lines.push(`【${role}】${content}`)
+  }
+  let text = lines.join('\n\n')
+  if (text.length > MAX_INPUT_CHARS) {
+    const head = text.slice(0, MAX_INPUT_CHARS / 2)
+    const tail = text.slice(-MAX_INPUT_CHARS / 2)
+    text = `${head}\n\n...（中间已省略）...\n\n${tail}`
+  }
+  return text
+}
+
+function runCli(cmd, args, input, timeoutMs = 60000) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] })
+    let out = ''
+    let err = ''
+    const timer = setTimeout(() => {
+      try { proc.kill('SIGTERM') } catch { /* ignore */ }
+      reject(new Error(`${cmd} summarize timeout`))
+    }, timeoutMs)
+    proc.stdout.on('data', d => { out += d.toString() })
+    proc.stderr.on('data', d => { err += d.toString() })
+    proc.on('error', e => { clearTimeout(timer); reject(e) })
+    proc.on('close', code => {
+      clearTimeout(timer)
+      if (code === 0) resolve(out.trim())
+      else reject(new Error(`${cmd} exited ${code}: ${err.slice(0, 500)}`))
+    })
+    if (input != null) {
+      proc.stdin.write(input)
+      proc.stdin.end()
+    }
+  })
+}
+
+function resolveToolInvocation(tool, tools = {}) {
+  const toolConfig = tools?.[tool] || {}
+  const cmd = toolConfig.bin || toolConfig.command || tool
+  const baseArgs = Array.isArray(toolConfig.args) ? toolConfig.args.map((item) => String(item)) : []
+  return { cmd, baseArgs }
+}
+
+const SYSTEM_PROMPT = `你是一个对话摘要助手。请把下面的 AI 开发会话历史压缩为一段结构化的中文摘要，供继续对话使用。要求：
+1) 核心目标与任务背景（1-2 句）
+2) 已确认的关键决策 / 结论（要点列表）
+3) 仍未解决的问题 / 下一步 TODO（要点列表）
+4) 重要的代码路径、函数名、命令（如有）
+不要输出客套话，只输出摘要。`
+
+export async function summarizeTurns(turns, { tool = 'claude', tools } = {}) {
+  if (!Array.isArray(turns) || turns.length === 0) return ''
+  const body = turnsToText(turns)
+  const input = `${SYSTEM_PROMPT}\n\n=== 会话历史 ===\n${body}\n\n=== 请输出摘要 ===\n`
+
+  if (tool === 'codex') {
+    const { cmd, baseArgs } = resolveToolInvocation('codex', tools)
+    try {
+      return await runCli(cmd, [...baseArgs, 'exec', '--skip-git-repo-check', '-'], input)
+    } catch (e) {
+      console.warn('[summarize] codex failed, fallback to claude:', e.message)
+    }
+  }
+  const { cmd, baseArgs } = resolveToolInvocation('claude', tools)
+  try {
+    return await runCli(cmd, [...baseArgs, '-p', '--output-format', 'text'], input)
+  } catch (e) {
+    console.warn('[summarize] claude failed:', e.message)
+    return `（自动摘要失败：${e.message}）\n\n原始会话片段：\n${body.slice(0, 2000)}`
+  }
+}

package/src/system-rules.js

@@ -0,0 +1,52 @@
+/**
+ * 启动 AI session 时自动 prepend 到 prompt 的"工程纪律"。
+ *
+ * 这一段会出现在每条 task 的 prompt 顶部，强化 AI 行为：
+ *   - 拍板必走 ask_user MCP 工具（保证 telegram 端是按钮交互）
+ *   - 不要在 chat 文本里堆"我有 N 个问题"列表（这种格式在 telegram 没按钮，体验差）
+ *
+ * 默认不注入，避免把 Claude Code 推进交互式 TUI。
+ * 想启用：config.aiSession.enforceAskUserRule = true
+ */
+
+const ASK_USER_RULE = `# 工程纪律 · 拍板必须用 ask_user MCP 工具
+
+任何需要用户拍板、确认方向、做选择的场景（包括但不限于：
+"请确认"、"用 X 还是 Y"、"OK 吗"、"哪个方案对"、"我有 N 个问题想问你"），
+必须调用 ask_user MCP 工具，而不是在 chat 文本里写
+✅/✏️、(a)/(b)/(c)、1./2./3. 让用户在 chat 里数字回复。
+
+理由：用户的 chat 客户端（Telegram）会把 ask_user 自动渲染成 inline 按钮，
+一键点选 + 可选 ✏️ 补充细节；而你直接写在文本里的"问题列表"是纯文本，
+用户得手敲数字回，体验差且容易记错。
+
+ask_user 用法：
+  question: 一句话精炼问题（不要堆原因/上下文，那些放在 PTY 输出即可）
+  options:  2-8 个互斥选项（每个 ≤ 30 字，越短越好）
+
+多个独立决策 → 多次调 ask_user（每次一个问题，AI 拿到答案后再问下一个）。
+不要把多个问题塞进一次 ask_user 的 question 里。
+`
+
+export function getAskUserSystemRule() {
+  return ASK_USER_RULE
+}
+
+/**
+ * 拼最终 prompt：
+ *   [system rule]
+ *   ---
+ *   [original prompt：来自 template / user 的内容]
+ *
+ * 入参：
+ *   - originalPrompt: caller 已经拼好的 prompt（template + 任务描述）
+ *   - enforce: 是否启用规则；缺省 false
+ *
+ * 返回：拼装后的 prompt 字符串。enforce=false 时原样返回 originalPrompt。
+ */
+export function applySystemRules(originalPrompt, { enforce = false } = {}) {
+  const orig = String(originalPrompt || '').trim()
+  if (!enforce) return orig
+  if (!orig) return ASK_USER_RULE.trim()
+  return `${ASK_USER_RULE.trim()}\n\n---\n\n${orig}`
+}