xitto-kernel 0.2.0 → 0.3.2

package/src/app/tui.js

@@ -0,0 +1,398 @@
+// Ink（終端版 React）渲染層 — 對標 Claude Code：
+//   1) 已完成訊息進 <Static>：打一次、不重繪、隨終端捲動。
+//   2) 串流中的回覆：已完成的「段落」即時 render markdown 提交進 <Static>（見 appendLive），
+//      動態區只保留「正在輸入的最後一段」並每幀重解析重繪——動態區恆小，避免回覆變長後
+//      動態區高度 ≥ 終端列數而退回 Ink 全螢幕重繪慢路徑（閃爍根因）。
+//   3) 自訂 Input：命令歷史(↑↓)、斜線/@補全(Tab)、多行(反斜線續行/貼上)、游標編輯。
+//   4) 輸入框永遠在最底，上方依序為輸出 / spinner / 頁腳 / 狀態列。
+import React, { useState, useEffect } from 'react';
+import { render, Box, Text, Static, useInput } from 'ink';
+import { md, lexBlocks, codeChunk } from './md-render.js';
+
+const h = React.createElement;
+const DOT = '\x1b[32m⏺\x1b[39m'; // 綠色實心圓，標記回覆/工具（對標 Claude Code）
+// 左側溝槽：第一行加 head 前綴（為 '' 時與其餘行一樣縮排 2 空格，用於「延續區塊」），
+// 讓整段成為一個視覺區塊。延續區塊不再重複 ● 標記。
+export function gutter(text, head = DOT) {
+  const pad = head ? head + ' ' : '  ';
+  return text.split('\n').map((l, i) => (i === 0 ? pad + l : '  ' + l)).join('\n');
+}
+
+// 串流增量提交（對標 Claude Code）：用 markdown 的 block lexer 把 live 切成頂層區塊，
+// 提交「除最後一塊外」的完整區塊進 <Static>，最後一塊（可能還沒打完）留在動態區。
+// 例外：最後一塊是「未閉合且超長的程式碼框」時，逐行提交已完成的程式碼行（見 store.appendLive）。
+
+// live 是否為一個「未閉合的 fenced code block」；是則回 {lang, body}（body 為開頭 fence 之後的程式碼）。
+// 容忍開頭的區塊間空行（前一塊提交後 raw 常殘留前導 \n）。
+function openCodeBlock(text) {
+  const t = text.replace(/^\n+/, '');
+  const m = t.match(/^```([^\n]*)\n/);
+  if (!m) return null;
+  if ((t.match(/```/g) || []).length !== 1) return null; // 只有開頭那組 ``` = 未閉合
+  return { lang: m[1].trim(), body: t.slice(m[0].length) };
+}
+// 超長程式碼框逐行提交的行數門檻：接近一屏才啟動（小/中型 code 仍正常即時渲染、含標頭）。
+function codeFlushLines() {
+  return Math.max(12, (process.stdout?.rows || 24) - 8);
+}
+const INV = '\x1b[7m';
+const INVOFF = '\x1b[27m';
+const GRAY = (s) => `\x1b[90m${s}\x1b[39m`;
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+function waitingVerb(sec) {
+  if (sec < 3) return '思考中';
+  if (sec < 10) return '處理中';
+  if (sec < 30) return '仍在處理';
+  return '長任務處理中';
+}
+
+// 外部 store：plain object + listeners。main() 推狀態，元件 subscribe 後 re-render。
+export function createStore(initial = {}) {
+  let state = {
+    transcript: [], live: '', liveStarted: false, liveCodeLang: null, thinking: '', tool: null, status: '',
+    tasks: '',               // 任務面板：活動區就地更新（不進 Static，避免每步更新堆重複列表）
+    mode: 'idle', planMode: false, permission: null, placeholder: '',
+    busyAt: null,            // 本輪開始時間戳（ms）：思考動畫 + 耗時
+    modelLabel: '', cwdLabel: '', gitLabel: '', permLabel: '', sandboxLabel: '', // 狀態列：模型/目錄/git/權限模式/沙箱
+    ctx: null,               // {used,total} 上下文用量
+    atStart: true,           // 起始乾淨畫面：把輸入框推到終端底部，首次送出後關閉
+    suggestions: [],         // 後續追問建議（ghost text + Tab 接受）
+    selection: null,         // {title, options} 方向鍵選單（權限確認 / ask_user）
+    ask: null,               // {prompt} 純文字問答輸入（ask_user 的「其他（自行輸入）」）
+    ...initial,
+  };
+  const listeners = new Set();
+  let id = 1;
+  let liveStarted = false; // 本段文字是否已輸出過 ● 開頭（首塊帶 ●，段內後續塊為延續、不重複 ●）
+  let codeLang = null;     // 非 null＝正在「逐行提交」一個超長未閉合程式碼框；此時 state.live 只存程式碼本體（無 fence）
+  let scheduled = null;
+  const emitNow = () => { scheduled = null; for (const l of listeners) l(); };
+  const emitThrottled = () => { if (!scheduled) scheduled = setTimeout(emitNow, 40); };
+
+  // 提交一個已完成區塊進 <Static>：rendered 為已渲染好的 ANSI 字串。首塊帶 ●，之後為延續。
+  const commitBlock = (rendered) => {
+    if (!rendered || !rendered.trim()) return;
+    const block = '\n' + gutter(rendered, liveStarted ? '' : DOT);
+    liveStarted = true;
+    state = { ...state, liveStarted: true, transcript: [...state.transcript, { id: id++, text: block }] };
+  };
+
+  return {
+    get: () => state,
+    subscribe(l) { listeners.add(l); return () => listeners.delete(l); },
+    set(p) { state = { ...state, ...p }; emitNow(); },
+    pushBlock(text) {
+      if (text == null || text === '') return;
+      state = { ...state, transcript: [...state.transcript, { id: id++, text }] };
+      emitNow();
+    },
+    appendLive(s) {
+      // --- 模式 A：正在逐行提交超長未閉合程式碼框（state.live 只存程式碼本體、無 fence）---
+      if (codeLang != null) {
+        let body = state.live + s;
+        const close = body.indexOf('```'); // 收尾 fence 到了？
+        if (close !== -1) {
+          const done = body.slice(0, close).replace(/\n$/, '');
+          if (done) commitBlock(codeChunk(done, codeLang, false));
+          codeLang = null;
+          // 收尾 fence 之後的剩餘文字（去掉 fence 本身與其後換行）回到一般模式，留待下次 delta / finalize 處理
+          const rest = body.slice(close + 3).replace(/^[^\n]*\n?/, '');
+          state = { ...state, live: rest, liveCodeLang: null };
+          emitThrottled();
+          return;
+        }
+        const lines = body.split('\n');
+        if (lines.length > codeFlushLines()) {
+          commitBlock(codeChunk(lines.slice(0, -1).join('\n'), codeLang, false)); // 提交已完成行、留最後一行（可能未打完）
+          body = lines[lines.length - 1];
+        }
+        state = { ...state, live: body, liveCodeLang: codeLang };
+        emitThrottled();
+        return;
+      }
+
+      // --- 模式 B：一般 markdown。用 block lexer 切塊，提交除最後一塊外的所有完整區塊 ---
+      let raw = state.live + s;
+      const tokens = lexBlocks(raw);
+      if (tokens.length >= 2) {
+        let committedRaw = '';
+        for (let i = 0; i < tokens.length - 1; i++) committedRaw += tokens[i].raw;
+        if (committedRaw.trim() && raw.startsWith(committedRaw)) {
+          commitBlock(md(committedRaw));
+          raw = raw.slice(committedRaw.length);
+        }
+      }
+      // 最後一塊若是「未閉合且超長」的程式碼框 → 進入模式 A，立即提交首批已完成行（含標頭）
+      const open = openCodeBlock(raw);
+      if (open && open.body.split('\n').length > codeFlushLines()) {
+        codeLang = open.lang;
+        const lines = open.body.split('\n');
+        commitBlock(codeChunk(lines.slice(0, -1).join('\n'), codeLang, true)); // 首塊含 ┌─ lang 標頭
+        state = { ...state, live: lines[lines.length - 1], liveStarted, liveCodeLang: codeLang };
+        emitThrottled();
+        return;
+      }
+      state = { ...state, live: raw, liveStarted };
+      emitThrottled();
+    },
+    appendThinking(s) { state = { ...state, thinking: state.thinking + s }; emitThrottled(); },
+    finalizeLive() {
+      const live = state.live;
+      const started = liveStarted;
+      const cl = codeLang;
+      liveStarted = false; codeLang = null;
+      state = { ...state, live: '', liveStarted: false, liveCodeLang: null, thinking: '' };
+      if (live.trim()) {
+        const rendered = cl != null ? codeChunk(live, cl, false) : md(live);
+        state.transcript = [...state.transcript, { id: id++, text: '\n' + gutter(rendered, started ? '' : DOT) }];
+      }
+      emitNow();
+    },
+    setTool(tool) { state = { ...state, tool }; emitNow(); },
+    setStatus(status) { state = { ...state, status }; emitNow(); },
+    setMode(mode) { state = { ...state, mode }; emitNow(); },
+    setPlan(planMode) { state = { ...state, planMode }; emitNow(); },
+    setPlaceholder(placeholder) { state = { ...state, placeholder }; emitNow(); },
+    askSelect(title, options) { state = { ...state, mode: 'select', selection: { title, options } }; emitNow(); },
+    clearSelect() { state = { ...state, mode: 'busy', selection: null }; emitNow(); },
+    askInput(prompt) { state = { ...state, mode: 'ask', ask: { prompt } }; emitNow(); },
+    clearAsk() { state = { ...state, mode: 'busy', ask: null }; emitNow(); },
+  };
+}
+
+// 通用方向鍵選單（↑↓ / Enter 選、Esc 取消當前提示、Ctrl+C 中斷整輪、數字鍵快選）。
+// onCancel：取消這一次選擇（如權限確認＝拒絕該工具）；onAbort：中斷整個回合（Ctrl+C）。
+const optLabel = (o) => (typeof o === 'string' ? o : (o?.label ?? String(o)));
+export function Select({ title, options, onSelect, onCancel, onAbort }) {
+  const [index, setIndex] = useState(0);
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') { (onAbort || onCancel)(); return; } // Ctrl+C → 中斷整輪
+    if (key.escape) { onCancel(); return; }                              // Esc → 僅取消這次（拒絕該工具）
+    if (key.upArrow) { setIndex((i) => (i - 1 + options.length) % options.length); return; }
+    if (key.downArrow) { setIndex((i) => (i + 1) % options.length); return; }
+    if (key.return) { onSelect(index); return; }
+    const n = parseInt(input, 10);
+    if (!Number.isNaN(n) && n >= 1 && n <= options.length) { onSelect(n - 1); return; }
+  });
+  return h(
+    Box,
+    { flexDirection: 'column', borderStyle: 'round', borderColor: 'yellow', paddingX: 1, marginTop: 1 },
+    title ? h(Text, null, title) : null,
+    ...options.map((o, i) => h(Text, { key: i, color: i === index ? 'cyan' : 'gray' }, `${i === index ? '❯' : ' '} ${i + 1}. ${optLabel(o)}`)),
+    h(Text, { color: 'gray' }, '  ↑↓ 選擇 · Enter 確認 · Esc 取消此項 · Ctrl+C 中斷整輪'),
+  );
+}
+
+// 多行 value + 游標（游標處反白）渲染成字串；空值顯示 ghost/placeholder
+function renderValue(value, cursor, hint) {
+  if (!value) return INV + ' ' + INVOFF + GRAY(hint || '');
+  const at = value.slice(cursor, cursor + 1) || ' ';
+  return value.slice(0, cursor) + INV + at + INVOFF + value.slice(cursor + 1);
+}
+
+// 貼上折疊占位符的「結尾」樣式（退格時用來判斷游標是否落在占位符末端）
+const PASTE_TOKEN_END = /⟦貼上#\d+·\d+行⟧$/;
+
+// 退格邏輯：若游標正好在貼上占位符的結尾，原子刪除整個占位符(連同它代表的內容會在送出時
+// 一併消失)；否則刪一個字元。避免退格只刪掉 ⟧ 破壞占位符→送出殘缺字面、貼上內容靜默遺失。
+// 純函數，便於單測。回傳 { value, cursor }。
+export function backspaceAt(value, cursor) {
+  if (cursor <= 0) return { value, cursor };
+  const m = value.slice(0, cursor).match(PASTE_TOKEN_END);
+  if (m) {
+    const start = cursor - m[0].length;
+    return { value: value.slice(0, start) + value.slice(cursor), cursor: start };
+  }
+  return { value: value.slice(0, cursor - 1) + value.slice(cursor), cursor: cursor - 1 };
+}
+
+// 自訂輸入編輯器（取代 ink-text-input，以支援歷史/補全/多行）
+function Input({ onSubmit, onCtrlC, onEscape, getHistory, complete, placeholder, promptPrefix, promptColor, suggestions }) {
+  const [value, setValue] = useState('');
+  const [cursor, setCursor] = useState(0);
+  const [menu, setMenu] = useState(null);   // {items, index, start}
+  const [histIdx, setHistIdx] = useState(-1);
+  const [draft, setDraft] = useState('');
+  const [pastes, setPastes] = useState([]); // 多行貼上折疊：value 內放占位符，送出時展開
+  // ghost 建議：輸入框為空且有建議時，淡色顯示第一條，Tab 接受
+  const ghost = (!value && suggestions && suggestions.length) ? suggestions[0] : '';
+  const expandPastes = (v) => v.replace(/⟦貼上#(\d+)·\d+行⟧/g, (m, n) => pastes[Number(n) - 1] ?? m);
+  // 依目前輸入自動更新補全選單（邊打邊彈，對標 Claude Code）。
+  // 已是完整唯一匹配（如打完 /help）則不彈，避免接受後又跳出來。
+  const refresh = (v, cur) => {
+    const res = complete ? complete(v.slice(0, cur)) : null;
+    if (!res || !res.items.length) { setMenu(null); return; }
+    const token = v.slice(res.start, cur);
+    if (res.items.length === 1 && res.items[0] === token) { setMenu(null); return; }
+    setMenu({ items: res.items, index: 0, start: res.start });
+  };
+  const put = (v, c) => { const cc = c == null ? v.length : c; setValue(v); setCursor(cc); };
+  const edit = (v, c) => { put(v, c); refresh(v, c == null ? v.length : c); }; // 編輯內容並刷新補全
+
+  useInput((input, key) => {
+    if (key.ctrl && input === 'c') { onCtrlC(); return; }
+    if (key.escape) { if (menu) { setMenu(null); return; } onEscape(); return; }
+
+    if (menu) { // 補全選單導航（開啟時 ↑↓ 走選單、Tab/Enter 接受）
+      if (key.upArrow) { setMenu({ ...menu, index: (menu.index - 1 + menu.items.length) % menu.items.length }); return; }
+      if (key.downArrow) { setMenu({ ...menu, index: (menu.index + 1) % menu.items.length }); return; }
+      if (key.tab || key.return) { const pick = menu.items[menu.index]; edit(value.slice(0, menu.start) + (typeof pick === 'string' ? pick : pick.value)); return; }
+      // 其他鍵：先關選單，落到下面照常處理（並會在編輯後重新刷新）
+      setMenu(null);
+    }
+
+    if (key.tab && ghost) { edit(ghost, ghost.length); return; } // Tab 接受 ghost 建議
+    if (key.tab) { refresh(value, cursor); return; } // 選單未開時 Tab 也可手動觸發
+    if (key.return) {
+      // Shift+Enter / Option(Alt)+Enter → 在游標處換行（多行輸入），不送出
+      if (key.shift || key.meta) { edit(value.slice(0, cursor) + '\n' + value.slice(cursor), cursor + 1); return; }
+      if (value.endsWith('\\')) { edit(value.slice(0, -1) + '\n'); return; } // 反斜線續行
+      const v = expandPastes(value); // 送出前把貼上占位符還原成原文
+      setValue(''); setCursor(0); setMenu(null); setHistIdx(-1); setDraft(''); setPastes([]);
+      onSubmit(v); return;
+    }
+    if (key.upArrow) {
+      const hist = getHistory(); if (!hist.length) return;
+      let i = histIdx; if (i === -1) { setDraft(value); i = 0; } else if (i < hist.length - 1) i++;
+      setHistIdx(i); put(hist[hist.length - 1 - i]); return;
+    }
+    if (key.downArrow) {
+      if (histIdx === -1) return;
+      const hist = getHistory(); const i = histIdx - 1;
+      if (i < 0) { setHistIdx(-1); put(draft); return; }
+      setHistIdx(i); put(hist[hist.length - 1 - i]); return;
+    }
+    // Alt/Option + ←/→：以「詞」為單位移動游標
+    if (key.meta && key.leftArrow) { let i = cursor; while (i > 0 && /\s/.test(value[i - 1])) i--; while (i > 0 && !/\s/.test(value[i - 1])) i--; setCursor(i); return; }
+    if (key.meta && key.rightArrow) { let i = cursor; while (i < value.length && /\s/.test(value[i])) i++; while (i < value.length && !/\s/.test(value[i])) i++; setCursor(i); return; }
+    if (key.leftArrow) { setCursor(Math.max(0, cursor - 1)); return; }
+    if (key.rightArrow) { setCursor(Math.min(value.length, cursor + 1)); return; }
+    if (key.ctrl && input === 'a') { setCursor(0); return; }
+    if (key.ctrl && input === 'e') { setCursor(value.length); return; }
+    if (key.ctrl && input === 'u') { edit(value.slice(cursor), 0); return; }            // 刪到行首
+    if (key.ctrl && input === 'k') { edit(value.slice(0, cursor), cursor); return; }     // 刪到行尾
+    if (key.backspace || key.delete) {
+      const r = backspaceAt(value, cursor); // 游標在貼上占位符末端→原子刪整個占位符
+      if (r.value !== value || r.cursor !== cursor) edit(r.value, r.cursor);
+      return;
+    }
+    if (input) {
+      // 多行貼上：折疊成占位符 ⟦貼上#n·N行⟧，不撐爆輸入框；送出時展開（對標 Claude Code）
+      if (input.includes('\n') && input.length > 1) {
+        const id = pastes.length + 1;
+        const token = `⟦貼上#${id}·${input.split('\n').length}行⟧`;
+        setPastes((p) => [...p, input]);
+        edit(value.slice(0, cursor) + token + value.slice(cursor), cursor + token.length);
+      } else {
+        edit(value.slice(0, cursor) + input + value.slice(cursor), cursor + input.length);
+      }
+    }
+  });
+
+  // 空輸入時，ghost 建議優先顯示（附 ⇥ 提示）；否則顯示 placeholder
+  const hint = ghost ? `${ghost}  \x1b[2m⇥ Tab\x1b[22m` : placeholder;
+  const lines = renderValue(value, cursor, hint).split('\n');
+  return h(
+    Box,
+    { flexDirection: 'column' },
+    h(Box, null, h(Text, { color: promptColor }, promptPrefix), h(Text, null, lines[0])),
+    ...lines.slice(1).map((ln, i) => h(Text, { key: 'l' + i }, '  ' + ln)),
+    menu
+      ? h(Box, { flexDirection: 'column' },
+          ...menu.items.slice(0, 8).map((it, i) => {
+            const val = typeof it === 'string' ? it : it.value;
+            const desc = typeof it === 'string' ? '' : (it.desc ? '  \x1b[90m' + it.desc + '\x1b[39m' : '');
+            return h(Text, { key: 'm' + i, color: i === menu.index ? 'cyan' : 'gray' }, (i === menu.index ? '❯ ' : '  ') + val + desc);
+          }))
+      : null,
+  );
+}
+
+export function App({ store, handlers }) {
+  const [, force] = useState(0);
+  const [tick, setTick] = useState(0);
+  useEffect(() => store.subscribe(() => force((n) => n + 1)), [store]);
+  const s = store.get();
+
+  // spinner / 耗時計時：執行中每 120ms 重繪
+  useEffect(() => {
+    if (s.mode !== 'busy') return undefined;
+    const t = setInterval(() => setTick((n) => n + 1), 120);
+    return () => clearInterval(t);
+  }, [s.mode]);
+
+  // 註：終端 resize 由 index.js 處理（全清螢幕 + 重新掛載），因為 Ink 的增量清行
+  // 會用「換行數」而非「實際終端列數」計算，視窗變窄時會誤算並殘留亂碼。
+
+  const elapsed = s.busyAt ? Math.floor((Date.now() - s.busyAt) / 1000) : 0;
+  const verb = s.live ? '輸出中' : (s.tool ? '執行中' : waitingVerb(elapsed)); // 已開始輸出/工具時改措辭
+  const waiting = s.mode === 'busy'
+    ? `\x1b[35m${SPINNER[tick % SPINNER.length]} ${verb}… ${elapsed}s\x1b[39m ` +
+      GRAY('· 直接打字=引導，Esc/Ctrl+C 中斷')
+    : null;
+
+  const borderColor = s.mode === 'ask' ? 'cyan' : s.mode === 'busy' ? 'magenta' : s.planMode ? 'cyan' : 'gray';
+  const promptColor = s.mode === 'ask' ? 'cyan' : s.planMode ? 'cyan' : 'green';
+
+  // 狀態列：模型 · 目錄 · [計劃] · 上下文 N%
+  let ctxPart = '';
+  if (s.ctx && s.ctx.total) {
+    const pct = Math.min(100, Math.round((s.ctx.used / s.ctx.total) * 100));
+    const col = pct >= 90 ? '31' : pct >= 70 ? '33' : '90';
+    ctxPart = ` \x1b[90m·\x1b[39m \x1b[${col}m上下文 ${pct}%\x1b[39m`;
+  }
+  const planPart = s.planMode ? ' \x1b[90m·\x1b[39m \x1b[36m[計劃]\x1b[39m' : '';
+  const permPart = s.permLabel ? ' \x1b[90m·\x1b[39m \x1b[32m' + s.permLabel + '\x1b[39m' : '';
+  const sandboxPart = s.sandboxLabel ? ' \x1b[90m·\x1b[39m \x1b[33m' + s.sandboxLabel + '\x1b[39m' : '';
+  const gitPart = s.gitLabel ? ' \x1b[90m·\x1b[39m ' + GRAY(s.gitLabel) : '';
+  const statusBar = GRAY(`${s.modelLabel}  ${s.cwdLabel}`) + gitPart + planPart + permPart + sandboxPart + ctxPart;
+
+  // 不再用 spacer 把輸入框頂到屏底。原本算高度撐滿整屏，會讓「活動區」逼近終端列數；
+  // 一旦 outputHeight >= rows，Ink 改走 clearTerminal 全屏重繪慢路徑（Windows conhost 上劇烈閃爍/跳動）。
+  // 改為自頂向下自然捲動：歷史進 <Static>（不計入活動區高度），活動區恆只剩 串流/狀態/輸入 幾行，
+  // Ink 永遠走 eraseLines 增量快路徑。輸入框在內容填滿一屏後自然落到底部（對標 Claude Code）。
+  return h(
+    Box,
+    { flexDirection: 'column' },
+    h(Static, { items: s.transcript }, (item) => h(Box, { key: item.id, flexDirection: 'column' }, h(Text, null, item.text))),
+    s.thinking ? h(Text, { color: 'gray', wrap: 'wrap' }, s.thinking) : null,
+    s.live ? h(Box, { flexDirection: 'column' }, h(Text, null, '\n' + gutter(
+      s.liveCodeLang != null ? codeChunk(s.live, s.liveCodeLang, false) : md(s.live),
+      s.liveStarted ? '' : DOT))) : null,
+    s.tool ? h(Text, { color: 'yellow' }, `⏺ ${s.tool.name}`, s.tool.summary ? h(Text, { color: 'gray' }, `(${s.tool.summary})`) : null) : null,
+    waiting ? h(Text, null, waiting) : null,
+    s.ask ? h(Text, null, s.ask.prompt) : null,
+    s.status ? h(Text, null, '  ' + s.status) : null,
+    // 任務面板：就地更新的活動區元素（非 Static），每次 task_update 在原位重畫、不堆歷史
+    s.tasks ? h(Box, { flexDirection: 'column' }, h(Text, null, GRAY('  任務')), h(Text, null, s.tasks)) : null,
+    statusBar.trim() ? h(Text, null, '  ' + statusBar) : null,
+    (s.mode === 'idle' && !s.selection) ? h(Text, null, GRAY('  ↵ 送出 · ⇧↵ 換行 · / 指令 · @ 檔案 · ↑ 歷史')) : null,
+    // 最底：選單模式渲染 <Select>（取代輸入框），否則渲染輸入框
+    s.selection
+      ? h(Select, {
+          title: s.selection.title,
+          options: s.selection.options,
+          onSelect: handlers.onSelectChoice,
+          onCancel: handlers.onSelectCancel,
+          onAbort: handlers.onSelectAbort,
+        })
+      : h(Box, { borderStyle: 'round', borderColor, paddingX: 1, marginTop: 1 },
+          h(Input, {
+            onSubmit: handlers.onSubmit,
+            onCtrlC: handlers.onCtrlC,
+            onEscape: handlers.onEscape,
+            getHistory: handlers.getHistory,
+            // ask 模式（自行輸入答案）為純文字：關閉斜線/@補全與 ghost 建議，避免 `/`、`@` 誤彈選單
+            complete: s.mode === 'ask' ? undefined : handlers.complete,
+            placeholder: s.mode === 'ask' ? '輸入你的答案，Enter 送出 · Esc 取消' : s.placeholder,
+            promptPrefix: s.mode === 'ask' ? '› ' : (s.planMode ? '[計劃] › ' : '› '),
+            promptColor,
+            suggestions: s.mode === 'ask' ? [] : s.suggestions,
+          })),
+  );
+}
+
+// 掛載 TUI；回傳 Ink instance（含 unmount / waitUntilExit）
+export function mountTui({ store, handlers }) {
+  return render(h(App, { store, handlers }), { exitOnCtrlC: false });
+}

package/src/packs/coding/index.js

@@ -4,40 +4,12 @@
 // 對應 docs/05-example-packs.md「A. coding pack」。
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, relative } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, spawnSync } from 'node:child_process';
 import { createBackgroundTools } from '../../kernel/bg.js';
+import { createGrepTool, createGlobTool } from '../shared/code-nav.js';
 
 const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
 
-const IGNORE = new Set(['node_modules', '.git', '.xitto-kernel', '.xitto-code', 'dist', 'build', '.next', 'coverage']);
-
-// 遞迴收集檔案路徑（跳過 IGNORE 目錄），上限保護
-function walkFiles(dir, out, limit) {
-  if (out.length >= limit) return;
-  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
-  for (const e of entries) {
-    if (out.length >= limit) return;
-    if (e.name.startsWith('.') && e.name !== '.env') { if (IGNORE.has(e.name)) continue; }
-    if (IGNORE.has(e.name)) continue;
-    const full = join(dir, e.name);
-    if (e.isDirectory()) walkFiles(full, out, limit);
-    else out.push(full);
-  }
-}
-
-// glob 樣式 → 正則（支援 ** 遞迴、* 與 ?）
-function globToRegex(pattern) {
-  let re = '';
-  for (let i = 0; i < pattern.length; i++) {
-    const ch = pattern[i];
-    if (ch === '*') { if (pattern[i + 1] === '*') { re += '.*'; i++; if (pattern[i + 1] === '/') i++; } else re += '[^/]*'; }
-    else if (ch === '?') re += '[^/]';
-    else if ('.+^${}()|[]\\'.includes(ch)) re += '\\' + ch;
-    else re += ch;
-  }
-  return new RegExp('^' + re + '$');
-}
-
 const SYSTEM_PROMPT = [
   '你是嚴謹的編碼 agent。準則：',
   '- 探索 codebase：用 glob 找檔、grep 搜內容、read 讀檔（附行號）。',
@@ -121,50 +93,18 @@ export function createCodingPack({ cwd = process.cwd() } = {}) {
     parameters: { type: 'object', properties: { command: { type: 'string' }, timeout: { type: 'number' } }, required: ['command'] },
     execute: async (_id, { command, timeout }) => {
       const ms = Math.min(600, Math.max(1, timeout || 120)) * 1000;
-      try { return txt(execSync(command, { cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 }) || '(no output)'); }
-      catch (e) { return txt({ error: e.message, stdout: e.stdout, stderr: e.stderr }); }
+      // spawnSync 同時捕捉 stdout+stderr（不漏到終端，agent 也看得到錯誤輸出）
+      const r = spawnSync(command, { shell: true, cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 });
+      const output = ((r.stdout || '') + (r.stderr || '')).trim();
+      if (r.error) return txt({ error: r.error.message, output });
+      if (r.status !== 0) return txt({ error: `命令結束碼 ${r.status}`, output: output || '(no output)' });
+      return txt(output || '(no output)');
     },
   };
 
-  // ── codebase 導航：grep（搜內容）+ glob（找檔）──
-  const grepTool = {
-    name: 'grep', label: '搜尋內容', readOnly: true,
-    description: '在檔案內容用正則搜尋，回 path:line:文字。可選 path(起點目錄)、glob(檔名過濾如 *.js)。自動跳過 node_modules/.git。',
-    parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' }, glob: { type: 'string' }, ignoreCase: { type: 'boolean' } }, required: ['pattern'] },
-    execute: async (_id, { pattern, path, glob, ignoreCase }) => {
-      let re; try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); } catch (e) { return txt({ error: '正則無效：' + e.message }); }
-      const base = path ? abs(path) : cwd;
-      if (!existsSync(base)) return txt({ error: '目錄不存在', path });
-      const files = []; walkFiles(base, files, 8000);
-      const gre = glob ? globToRegex(glob) : null;
-      const hits = [];
-      for (const f of files) {
-        if (gre && !gre.test(f.split('/').pop())) continue;
-        let content; try { content = readFileSync(f, 'utf8'); } catch { continue; }
-        if (content.includes('')) continue; // 跳過二進位
-        const lines = content.split('\n');
-        for (let i = 0; i < lines.length; i++) {
-          if (re.test(lines[i])) { hits.push(`${relative(cwd, f)}:${i + 1}: ${lines[i].trim().slice(0, 200)}`); if (hits.length >= 200) break; }
-        }
-        if (hits.length >= 200) break;
-      }
-      return txt(hits.length ? hits.join('\n') + (hits.length >= 200 ? '\n…（結果已截斷至 200）' : '') : '(無匹配)');
-    },
-  };
-
-  const globTool = {
-    name: 'glob', label: '找檔', readOnly: true,
-    description: '用萬用字元樣式找檔（** 遞迴、* ?），相對路徑比對。如 "src/**/*.js"、"**/*.test.js"。',
-    parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' } }, required: ['pattern'] },
-    execute: async (_id, { pattern, path }) => {
-      const base = path ? abs(path) : cwd;
-      if (!existsSync(base)) return txt({ error: '目錄不存在', path });
-      const files = []; walkFiles(base, files, 8000);
-      const re = globToRegex(pattern);
-      const matched = files.map((f) => relative(cwd, f)).filter((rel) => re.test(rel)).slice(0, 200);
-      return txt({ pattern, count: matched.length, files: matched });
-    },
-  };
+  // ── codebase 導航：grep / glob（共用模組）──
+  const grepTool = createGrepTool(cwd);
+  const globTool = createGlobTool(cwd);
 
   const webFetch = {
     name: 'web_fetch', label: '抓網頁', readOnly: true,

package/src/packs/data-query/index.js

@@ -1,66 +1,72 @@
-// data-query pack — 第二個範例領域，用來證明「同介面、kernel 零改動」。
-// 工具為示意 stub（回傳假資料），重點是六個插槽用法與 coding 完全一樣，只是內容換了。
-// 對照：schema-before-query 之於資料查詢 == read-before-edit 之於編碼（同 preToolPolicy 插槽）。
+// data-query pack — 真實資料查詢 agent（用 sqlite3 CLI，零依賴）。
+// 工具對一個 SQLite .db 跑真實 SQL；schema-before-query 守衛（對照 read-before-edit）。
 // 對應 docs/05-example-packs.md「B. data-query pack」。
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join } from 'node:path';
 
 const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
 
+// 用 sqlite3 CLI 跑 SQL（sql 以 argv 傳入，非 shell 內插 → 無 shell 注入）
+function sqlite(dbPath, sql, opts = []) {
+  const r = spawnSync('sqlite3', [...opts, dbPath, sql], { encoding: 'utf8', timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+  if (r.error) return { error: r.error.code === 'ENOENT' ? '找不到 sqlite3 命令（請先安裝）' : r.error.message };
+  if (r.status !== 0) return { error: (r.stderr || '').trim() || `exit ${r.status}` };
+  return { out: (r.stdout || '').trim() };
+}
+
 const SYSTEM_PROMPT = [
-  '你是資料分析 agent。準則：',
+  '你是資料分析 agent，對一個 SQLite 資料庫工作。準則：',
   '- 下查詢前先用 list_tables / describe_table 了解結構。',
-  '- 破壞性 SQL（DROP/TRUNCATE/DELETE 無 WHERE）一律先確認。',
+  '- 唯讀查詢用 sql_query；寫入（INSERT/UPDATE/DELETE/建表）用 sql_exec。',
+  '- 破壞性 SQL（DROP/TRUNCATE/無 WHERE 的 DELETE）先確認。',
+  '- 回答問題時根據真實查詢結果，不要臆測數字。',
 ].join('\n');
 
-/**
- * @param {{ schema?: Record<string,string[]> }} [opts]
- * @returns {import('../../types.js').DomainPack}
- */
-export function createDataQueryPack({ schema = { orders: ['id', 'amount', 'user_id'], users: ['id', 'name'] } } = {}) {
-  let schemaLoaded = false; // describe/list 後設為 true，schema-before-query 守衛據此放行
+export function createDataQueryPack({ cwd = process.cwd(), db } = {}) {
+  const dbPath = db ? (isAbsolute(db) ? db : join(cwd, db)) : join(cwd, 'data.db');
+  let schemaSeen = false;
 
   const listTables = {
-    name: 'list_tables', label: '列表', description: '列出所有資料表', readOnly: true,
+    name: 'list_tables', label: '列表', readOnly: true, description: '列出資料庫所有資料表',
     parameters: { type: 'object', properties: {} },
-    execute: async () => { schemaLoaded = true; return txt(Object.keys(schema)); },
+    execute: async () => { schemaSeen = true; const r = sqlite(dbPath, '.tables'); return txt(r.error ? { error: r.error } : { tables: (r.out || '').split(/\s+/).filter(Boolean) }); },
   };
   const describeTable = {
-    name: 'describe_table', label: '表結構', description: '看某表欄位', readOnly: true,
+    name: 'describe_table', label: '表結構', readOnly: true, description: '看某表的欄位定義（CREATE 語句）',
     parameters: { type: 'object', properties: { table: { type: 'string' } }, required: ['table'] },
-    execute: async (_id, { table }) => { schemaLoaded = true; return txt(schema[table] || { error: '無此表' }); },
+    execute: async (_id, { table }) => { schemaSeen = true; const r = sqlite(dbPath, `.schema ${table}`); return txt(r.error ? { error: r.error } : (r.out || '(無此表)')); },
   };
   const sqlQuery = {
-    name: 'sql_query', label: '查詢', description: '執行唯讀 SQL 查詢', readOnly: true,
+    name: 'sql_query', label: '查詢', readOnly: true, description: '執行唯讀 SQL 查詢（SELECT/WITH/PRAGMA），回 CSV（含表頭）。',
     parameters: { type: 'object', properties: { sql: { type: 'string' } }, required: ['sql'] },
-    execute: async (_id, { sql }) => txt({ note: '（示意）查詢結果', sql, rows: [] }),
+    execute: async (_id, { sql }) => {
+      if (/\b(insert|update|delete|drop|create|alter|replace)\b/i.test(sql)) return txt({ error: '這是寫入型 SQL，請改用 sql_exec' });
+      const r = sqlite(dbPath, sql, ['-header', '-csv']);
+      return txt(r.error ? { error: r.error } : (r.out || '(空結果)'));
+    },
   };
   const sqlExec = {
-    name: 'sql_exec', label: '寫入', description: '執行寫入型 SQL（INSERT/UPDATE/DELETE）', mutating: true,
+    name: 'sql_exec', label: '寫入', mutating: true, description: '執行寫入型 SQL（INSERT/UPDATE/DELETE/CREATE/ALTER）。',
     parameters: { type: 'object', properties: { sql: { type: 'string' } }, required: ['sql'] },
-    execute: async (_id, { sql }) => txt({ note: '（示意）已執行', sql }),
-  };
-  const chartRender = {
-    name: 'chart_render', label: '畫圖', description: '把查詢結果渲染成圖表', readOnly: true,
-    parameters: { type: 'object', properties: { spec: { type: 'object' } }, required: ['spec'] },
-    execute: async (_id, { spec }) => txt({ note: '（示意）已渲染', spec }),
+    execute: async (_id, { sql }) => { const r = sqlite(dbPath, sql); return txt(r.error ? { error: r.error } : { ok: true, out: r.out || '' }); },
   };
 
   return {
     name: 'data-query',
-    tools: () => [listTables, describeTable, sqlQuery, sqlExec, chartRender],
+    tools: () => [listTables, describeTable, sqlQuery, sqlExec],
     systemPrompt: SYSTEM_PROMPT,
     contextFiles: ['SCHEMA.md', 'METRICS.md'],
-    // sql_query 唯讀、sql_exec 才 mutating → 從 metadata 自動推導 mutatingTools=['sql_exec']
+    // 只有 sql_exec 是 mutating → kernel 從 metadata 推導
     preToolPolicy: {
-      // schema-before-query：沒先看過 schema 就下查詢 → 擋
+      // schema-before-query：沒先看過結構就下 SQL → 擋（對照 read-before-edit）
       check: (ctx) => {
-        if ((ctx.name === 'sql_query' || ctx.name === 'sql_exec') && !schemaLoaded) {
+        if ((ctx.name === 'sql_query' || ctx.name === 'sql_exec') && !schemaSeen) {
           return { block: true, reason: '請先用 list_tables / describe_table 了解結構，再下 SQL。' };
         }
         return undefined;
       },
     },
     permissionPolicy: { deny: ['bash:DROP', 'bash:TRUNCATE'], defaultMode: 'default' },
-    // verify 省略 → 查詢無「自我驗收」概念
   };
 }
 

package/src/packs/deep-research/index.js

@@ -0,0 +1,41 @@
+// deep-research pack — 深度研究 agent：拆問題 → 多來源搜尋 → 讀全文查證 → 有引用的結論。
+// 工具：web_search/web_fetch（共用）+ write/read（存/讀報告）。搭配 kernel 的 spawn_agent 可並行子研究。
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createWebSearchTool, createWebFetchTool } from '../shared/web-tools.js';
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+const SYSTEM_PROMPT = [
+  '你是深度研究 agent。給你一個問題，做法：',
+  '- 把問題拆成幾個子查詢，用 web_search 找多個來源（不要只查一次）。',
+  '- 用 web_fetch 讀來源全文查證，不只看搜尋摘要。',
+  '- 交叉比對多個來源；關鍵事實要標注來源 URL。',
+  '- 最後給有引用的結論（重要論點附 [來源: URL]）；可用 write 存成報告檔。',
+  '- 來源衝突或查不到時明說，不杜撰。',
+].join('\n');
+
+export function createDeepResearchPack({ cwd = process.cwd() } = {}) {
+  const abs = (p) => (isAbsolute(p) ? p : join(cwd, p));
+
+  const writeReport = {
+    name: 'write', label: '存報告', mutating: true, description: '把研究報告/筆記寫入檔案（建立或覆寫）。',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+    execute: async (_id, { path, content }) => { writeFileSync(abs(path), content ?? '', 'utf8'); return txt({ written: path, bytes: Buffer.byteLength(content ?? '') }); },
+  };
+  const readTool = {
+    name: 'read', label: '讀檔', readOnly: true, description: '讀回已存的報告/筆記',
+    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    execute: async (_id, { path }) => { const p = abs(path); return existsSync(p) ? txt(readFileSync(p, 'utf8')) : txt({ error: '檔案不存在', path }); },
+  };
+
+  return {
+    name: 'deep-research',
+    tools: () => [createWebSearchTool(), createWebFetchTool(), writeReport, readTool],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['RESEARCH.md'],
+    permissionPolicy: { defaultMode: 'default' },
+  };
+}
+
+export const deepResearchPack = createDeepResearchPack();