xitto-kernel 0.6.1 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.6.4
+
+- **許願台「展開過程」+ 彩色 diff（借 Claude Code 的工具卡/⌥展開,翻譯成非技術版）**：
+  - 任務 `progress.log` 累積**完整步驟**（人話動作 + 參數摘要 + isError + 編輯的 `diff`）；`mapEvent` 的 `tool_end` 帶 `diff`
+  - 網頁加「**展開過程（N 步）**」摺疊：預設安靜(只給進度+成品),展開才顯示步驟卡 + **綠 +/紅 - 彩色 diff** → 同畫面服務「只要結果」與「想看細節」兩種人
+  - `_diff` 由 kernel 算好(v0.6.3),這版只是把它帶進網頁
+  - 3 個新測試（tool_end 帶 diff / log 累積 + diff 補齊）+ 真實 server 端到端（建檔→改檔,改檔步驟帶 `- a-b` / `+ a+b`）。測試 182/182
+
+## 0.6.3
+
+- **彩色 diff（編輯一目了然）**：
+  - kernel 新增 `diff.js`（LCS 行級 diff）；**在 `wrapUndo` 集中計算**——用既有的 undo 快照(before)+ 改後內容(after),
+    把 `_diff` 掛在工具結果上（不進 LLM content,僅供 app 渲染）。**所有 pack 的 edit/write 免改**,二進位/超大檔自動跳過
+  - TUI 渲染 `diffBlock`：`⎿ +N -N 行` + 綠 `+` / 紅 `-` 變更行（過長摺疊）
+  - 4 個測試（lineDiff 增刪/新檔/超大、diffBlock 渲染、kernel edit 自動掛 _diff）+ 視覺驗證。測試 180/180
+  - 註：`_diff` 已在 kernel 算好,日後接到許願台網頁很容易（目前先做 TUI）
+
+## 0.6.2
+
+- **TUI 補強（對標 Claude Code 的工具卡）**：
+  - **工具卡**：`⏺ name(args)` 標頭 + `⎿` **多行**結果（首行對齊、續行縮排），過長摺疊成「… +N 行」（取代原本單行截斷）
+  - **參數摘要人性化**：`bash(npm test)`、`edit(src/a.js)`——取最有意義的參數，不再倒整包 JSON
+  - **待辦清單** ☑/◐/☐ 渲染（已有，微調配色）
+  - 成功 `⎿ ✓`（綠）/ 失敗 `⎿ ✗`（紅，多顯示幾行）
+  - `summarize` / `toolBlock` 抽為純函數並匯出 + 2 個測試。測試 176/176。
+  - 仍缺（後續）：編輯的彩色 diff（需 edit 工具回傳前後內容）、底部模式/快捷鍵提示列強化
+
 ## 0.6.1
 
 - **成品溯源/位置**：分邏輯與實體兩層。

package/README.md

@@ -42,7 +42,7 @@ xitto-kernel init
 **3. 跑內建 pack（互動 CLI）**
 ```bash
 xitto-kernel                  # coding agent（讀寫檔案、跑命令）
-xitto-kernel --tui            # 完整 Ink TUI（持久狀態列、串流、Esc 中斷；需真實終端）
+xitto-kernel --tui            # 完整 Ink TUI（持久狀態列、串流、Esc 中斷、工具卡⏺/⎿、彩色 diff、待辦☑；需真實終端）
 xitto-kernel --pack notes     # 筆記 / 知識庫 agent
 xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
@@ -102,6 +102,7 @@ XITTO_SERVER_TOKEN=secret npm run serve   # 然後瀏覽器開 http://localhost:
 - **進行中**:**即時進度 + 活著的證明**——每秒跳動的「已進行 Ns」心跳時鐘、目前階段(思考中/執行中/驗收中)、agent 當下的**思考文字**(💭)、工具動作翻成人話、第幾輪 + 動作數。看得到它在想什麼、做什麼
 - **待辦打勾**:agent 用 `todo_write` 規劃多步任務時,顯示 ☐/◐/☑ 清單,把「未知時長」變成「看得到的剩餘步數」(對標 Claude Code)
 - **隨時可停**:每個進行中任務有「停止」鈕 → `POST /v1/tasks/:id/cancel`(abort 正在跑的 agent)。控制權在使用者手上,降低「啟動了控制不了的東西」的焦慮
+- **展開過程**:預設安靜(只給進度與成品);想看細節按「展開過程」→ 完整步驟卡(讀/改/跑,人話)+ **編輯的彩色 diff**(綠 +/紅 -)。同一畫面服務「只要結果」與「想看細節」兩種人(對標 Claude Code 的 ⏺/⎿ + ctrl+r 展開)
 - **需要你回答**:agent 暫停提問時,跳出問題 + 回答框(澄清通道)
 - **收成品**:完成後顯示摘要 + **產出的檔案**,點檔名可直接看內容(`GET /v1/tasks/:id/file`,防路徑穿越)
 - **歷史成品**:過往交辦的清單(願望 + 狀態),不是聊天串

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.6.1",
+  "version": "0.6.4",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [

package/src/app/server.js

@@ -27,6 +27,9 @@ const newId = (p = 's') => p + Date.now().toString(36) + Math.random().toString(
 const MIME = { md: 'text/markdown', markdown: 'text/markdown', txt: 'text/plain', log: 'text/plain', json: 'application/json', csv: 'text/csv', html: 'text/html', htm: 'text/html', js: 'text/javascript', mjs: 'text/javascript', ts: 'text/plain', py: 'text/plain', sh: 'text/plain', css: 'text/css', xml: 'application/xml', yaml: 'text/plain', yml: 'text/plain', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', pdf: 'application/pdf', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' };
 export function contentTypeFor(name) { const ext = (String(name).split('.').pop() || '').toLowerCase(); return MIME[ext] || 'application/octet-stream'; }
 
+// 工具參數摘要（給「展開過程」步驟卡）：取最有意義的參數。
+const argSummary = (args) => { if (!args || typeof args !== 'object') return ''; const v = args.command ?? args.path ?? args.pattern ?? args.query ?? args.url ?? args.name ?? args.topic; return (v != null && v !== '') ? String(v).replace(/\s+/g, ' ').slice(0, 80) : ''; };
+
 // 交付檔案路徑解析（防穿越）：rel 必須是 workdir 內的相對路徑,否則回 null。
 export function resolveArtifact(workdir, rel) {
   if (typeof rel !== 'string' || !rel || isAbsolute(rel)) return null;
@@ -41,7 +44,7 @@ const webHtml = () => (_webHtml ??= readFileSync(join(dirname(fileURLToPath(impo
 // 把原始 kernel 事件壓成精簡的對外事件（串流端與背景任務共用，避免重複映射）
 export const mapEvent = (ev) => {
   if (ev.type === 'tool_execution_start') return { type: 'tool', name: ev.toolName, args: ev.args };
-  if (ev.type === 'tool_execution_end') return { type: 'tool_end', name: ev.toolName, isError: !!ev.isError };
+  if (ev.type === 'tool_execution_end') return { type: 'tool_end', name: ev.toolName, isError: !!ev.isError, diff: ev.result?._diff || undefined };
   if (ev.type === 'message_update' && ev.assistantMessageEvent?.type === 'text_delta') return { type: 'text', delta: ev.assistantMessageEvent.delta };
   if (ev.type === 'round') return { type: 'round', round: ev.round, maxRounds: ev.maxRounds };
   if (ev.type === 'verify_start') return { type: 'phase', phase: 'verifying' };
@@ -70,9 +73,16 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
     t.events.push(ev);
     if (t.events.length > maxEvents) t.events.shift();
     // 進度追蹤（給 UI 顯示「正在做什麼」,不要只顯示進行中；排除 text 雜訊）
-    const p = (t.progress ||= { steps: 0, round: 0, maxRounds: 0, recent: [], phase: 'starting', thinking: '', todos: [] });
+    const p = (t.progress ||= { steps: 0, round: 0, maxRounds: 0, recent: [], phase: 'starting', thinking: '', todos: [], log: [] });
     if (ev.type === 'tool' && ev.name === 'todo_write') { if (Array.isArray(ev.args?.todos)) p.todos = ev.args.todos; } // 待辦清單（給 UI 打勾）
-    else if (ev.type === 'tool') { p.steps++; p.phase = 'acting'; p.thinking = ''; t._textbuf = ''; p.recent.push({ name: ev.name, args: ev.args }); if (p.recent.length > 6) p.recent.shift(); }
+    else if (ev.type === 'tool') {
+      p.steps++; p.phase = 'acting'; p.thinking = ''; t._textbuf = '';
+      p.recent.push({ name: ev.name, args: ev.args }); if (p.recent.length > 6) p.recent.shift();
+      if (p.log.length < 100) p.log.push({ name: ev.name, summary: argSummary(ev.args) }); // 完整步驟（給「展開過程」）
+    } else if (ev.type === 'tool_end') {
+      const last = p.log[p.log.length - 1];
+      if (last && last.name === ev.name && !('isError' in last)) { last.isError = ev.isError; if (ev.diff) last.diff = ev.diff; }
+    }
     else if (ev.type === 'text') { p.phase = 'thinking'; t._textbuf = ((t._textbuf || '') + (ev.delta || '')).slice(-400); p.thinking = t._textbuf.replace(/\s+/g, ' ').trim().slice(-150); }
     else if (ev.type === 'round') { p.round = ev.round; if (ev.maxRounds) p.maxRounds = ev.maxRounds; p.thinking = ''; t._textbuf = ''; }
     else if (ev.type === 'phase') p.phase = ev.phase;

package/src/app/tui-run.js

@@ -8,8 +8,39 @@ import { createKernel } from '../kernel/index.js';
 import { createStore, mountTui, gutter } from './tui.js';
 import { md } from './md-render.js';
 
-const summarize = (args) => { const s = JSON.stringify(args ?? {}); return s.length > 60 ? s.slice(0, 57) + '…' : s; };
-const Y = (s) => `\x1b[33m${s}\x1b[39m`; const G = (s) => `\x1b[90m${s}\x1b[39m`; const R = (s) => `\x1b[31m${s}\x1b[39m`; const C = (s) => `\x1b[36m${s}\x1b[39m`;
+// 取最有意義的參數當摘要（像 Claude Code：bash(npm test) 而非 bash({"command":...})）
+export const summarize = (args) => {
+  if (!args || typeof args !== 'object') return '';
+  const v = args.command ?? args.path ?? args.pattern ?? args.query ?? args.url ?? args.name ?? args.topic ?? args.file;
+  if (v != null && v !== '') return String(v).replace(/\s+/g, ' ').slice(0, 60);
+  const s = JSON.stringify(args); return s === '{}' ? '' : (s.length > 60 ? s.slice(0, 57) + '…' : s);
+};
+const Y = (s) => `\x1b[33m${s}\x1b[39m`; const G = (s) => `\x1b[90m${s}\x1b[39m`; const R = (s) => `\x1b[31m${s}\x1b[39m`; const C = (s) => `\x1b[36m${s}\x1b[39m`; const Gn = (s) => `\x1b[32m${s}\x1b[39m`;
+
+// 工具卡（對標 Claude Code）：⏺ name(args) 標頭 + ⎿ 多行結果,過長摺疊成「… +N 行」。純函數,可測。
+export function toolBlock(name, summary, result, isError) {
+  const head = Y(`⏺ ${name}`) + (summary ? G(`(${summary})`) : '');
+  const raw = (result?.content || []).map((c) => c.text || '').join('\n').replace(/\s+$/, '');
+  if (!raw.trim()) return head + '\n' + (isError ? R('  ⎿ ✗') : Gn('  ⎿ ✓'));
+  const lines = raw.split('\n');
+  const MAX = isError ? 12 : 6;
+  const shown = lines.slice(0, MAX).map((l, i) => '  ' + (i === 0 ? '⎿ ' : '  ') + l.slice(0, 200));
+  let out = head + '\n' + (isError ? R : G)(shown.join('\n'));
+  if (lines.length > MAX) out += '\n' + G(`     … +${lines.length - MAX} 行`);
+  return out;
+}
+
+// 彩色 diff 區塊（綠 + / 紅 -）：渲染 kernel 掛在 result._diff 的行級 diff。
+export function diffBlock(d) {
+  if (!d) return '';
+  const head = G('  ⎿ ') + Gn(`+${d.added}`) + ' ' + R(`-${d.removed}`) + G(' 行');
+  if (d.tooBig) return head + G('（差異過大,省略內容）');
+  const changed = (d.lines || []).filter((l) => l.t !== ' ');
+  if (!changed.length) return '';
+  const MAX = 30;
+  const body = changed.slice(0, MAX).map((l) => (l.t === '+' ? Gn('    + ' + l.s.slice(0, 200)) : R('    - ' + l.s.slice(0, 200)))).join('\n');
+  return head + '\n' + body + (changed.length > MAX ? '\n' + G(`     … +${changed.length - MAX} 行變更`) : '');
+}
 
 const SLASH = { '/help': '說明', '/goal': '目標循環', '/sandbox': '沙箱', '/auto': '自動核准', '/plan': '計劃模式', '/undo': '撤銷', '/tools': '工具', '/memory': '記憶', '/sessions': '對話', '/resume': '續接', '/cost': '成本', '/clear': '清除', '/exit': '離開' };
 
@@ -48,10 +79,7 @@ export function runTui({ pack, model, getApiKey, sandbox = false, resume = null
   const persist = () => { try { kernel.session.save(sessionId, history); } catch { /* 略 */ } };
 
   // ── kernel 事件 → store ──
-  const toolBlock = (name, result, isError) => {
-    const text = (result?.content || []).map((c) => c.text || '').join(' ').replace(/\s+/g, ' ').trim();
-    return Y(`⏺ ${name}`) + '\n' + (isError ? R('  ⎿ ✗ ' + text.slice(0, 200)) : G('  ⎿ ✓ ' + text.slice(0, 120)));
-  };
+  let pendingSummary = '';
   const onEvent = (ev) => {
     switch (ev.type) {
       case 'message_update': {
@@ -68,15 +96,25 @@ export function runTui({ pack, model, getApiKey, sandbox = false, resume = null
       case 'tool_execution_start':
         store.finalizeLive();
         if (ev.toolName === 'todo_write' && Array.isArray(ev.args?.todos)) {
-          store.pushBlock(C('☑ 待辦') + '\n' + ev.args.todos.map((t) => '  ' + (t.status === 'completed' ? '\x1b[32m☑\x1b[39m ' + G(t.content) : t.status === 'in_progress' ? Y('◐ ') + t.content : G('☐ ' + t.content))).join('\n'));
+          store.pushBlock(C('☑ 待辦') + '\n' + ev.args.todos.map((t) => '  ' + (t.status === 'completed' ? Gn('☑ ') + G(t.content) : t.status === 'in_progress' ? Y('◐ ') + t.content : G('☐ ' + t.content))).join('\n'));
         } else {
-          store.setTool({ name: ev.toolName, summary: summarize(ev.args) });
+          pendingSummary = summarize(ev.args);
+          store.setTool({ name: ev.toolName, summary: pendingSummary });
         }
         break;
-      case 'tool_execution_end':
+      case 'tool_execution_end': {
         store.setTool(null);
-        if (ev.toolName !== 'todo_write') store.pushBlock(toolBlock(ev.toolName, ev.result, ev.isError));
+        if (ev.toolName !== 'todo_write') {
+          const d = ev.result?._diff;
+          if (d && !ev.isError && (d.added || d.removed || d.tooBig)) {
+            store.pushBlock(Y(`⏺ ${ev.toolName}`) + (pendingSummary ? G(`(${pendingSummary})`) : '') + '\n' + diffBlock(d));
+          } else {
+            store.pushBlock(toolBlock(ev.toolName, pendingSummary, ev.result, ev.isError));
+          }
+        }
+        pendingSummary = '';
         break;
+      }
       case 'verify_start': store.finalizeLive(); store.pushBlock(G('  🔎 自動驗收…')); break;
       case 'verify_end': store.pushBlock(ev.ok ? G('  ✓ 驗收通過') : Y('  ✗ 驗收失敗，修正中…')); break;
       case 'compact': store.pushBlock(G(`  ⊙ 已壓縮上下文：${ev.tokensBefore}→${ev.tokensAfter} tokens`)); break;

package/src/app/web/index.html

@@ -42,6 +42,15 @@
   .wsbadge { display:inline-block; font-size:12px; color:var(--dim); margin-left:8px; }
   .loc { margin-top:10px; font-size:12px; color:var(--dim); }
   .loc code { background:#0c0e12; border:1px solid var(--line); border-radius:6px; padding:2px 7px; color:var(--fg); cursor:pointer; }
+  .logtoggle { margin-top:12px; font-size:13px; color:var(--accent); cursor:pointer; user-select:none; }
+  .loglist { margin-top:6px; border-left:2px solid var(--line); padding-left:12px; }
+  .logstep { font-size:13px; color:var(--fg); padding:3px 0; }
+  .logstep.err { color:#f08a8a; }
+  .logstep .dim { color:var(--dim); }
+  .diff { margin:5px 0 6px 14px; font:12px/1.5 ui-monospace,Menlo,monospace; }
+  .dh { color:var(--dim); font-size:11px; margin-bottom:2px; }
+  .dl { white-space:pre-wrap; }
+  .dl.add { color:var(--ok); } .dl.del { color:#f08a8a; }
   .dots::after { content:""; animation:dots 1.4s steps(4,end) infinite; }
   @keyframes dots { 0%{content:""} 25%{content:"·"} 50%{content:"··"} 75%{content:"···"} }
   .summary { margin-top:10px; white-space:pre-wrap; }
@@ -146,6 +155,22 @@ function mdRender(src){
 }
 const IMG=/\.(png|jpe?g|gif|webp|svg)$/i, MD=/\.(md|markdown)$/i, HTMLF=/\.html?$/i, JSONF=/\.json$/i;
 const fileUrl=(id,path,extra="")=>"/v1/tasks/"+id+"/file?path="+encodeURIComponent(path)+"&token="+encodeURIComponent(TOKEN)+extra;
+// 彩色 diff（綠 +／紅 -）：渲染 kernel 算好的 _diff
+function diffHtml(d){
+  if(!d) return "";
+  if(d.tooBig) return `<div class="diff"><span class="dh">+${d.added} -${d.removed} 行（差異過大，省略）</span></div>`;
+  const ch=(d.lines||[]).filter(l=>l.t!==" ").slice(0,40);
+  if(!ch.length) return "";
+  return `<div class="diff"><div class="dh">+${d.added} -${d.removed}</div>${ch.map(l=>`<div class="dl ${l.t==="+"?"add":"del"}">${esc(l.t+" "+l.s)}</div>`).join("")}</div>`;
+}
+// 完整步驟卡（展開過程）：人話動作 + 編輯的彩色 diff
+function logHtml(p){
+  if(!p||!(p.log||[]).length) return `<div class="empty">（尚無步驟）</div>`;
+  return p.log.map(s=>`<div class="logstep ${s.isError?"err":""}">▸ ${esc(TOOL_ZH[s.name]||s.name)}${s.summary?` <span class="dim">${esc(s.summary)}</span>`:""}${s.diff?diffHtml(s.diff):""}</div>`).join("");
+}
+let expandedLog=false;
+function toggleLog(){ expandedLog=!expandedLog; if(liveTask) renderCurrent(liveTask); }
+
 async function viewFile(id, encPath, name){
   const path=decodeURIComponent(encPath); const v=$("#fview"); v.style.display="block";
   const bar=`<div class="vbar">📄 ${esc(name)} · <a href="${fileUrl(id,path)}" target="_blank">開新分頁</a> · <a href="${fileUrl(id,path,'&download=1')}">下載</a></div>`;
@@ -192,12 +217,15 @@ async function poll() {
 
 function renderCurrent(t) {
   const a = t.result?.artifacts, files = a ? [...(a.created||[]).map(f=>[f,"new"]), ...(a.modified||[]).map(f=>[f,"mod"])] : [];
+  const p = t.progress||{}, nLog=(p.log||[]).length;
+  const logSec = nLog ? `<div class="logtoggle" onclick="toggleLog()">${expandedLog?"▾ 收合過程":"▸ 展開過程（"+nLog+" 步）"}</div>${expandedLog?`<div class="loglist">${logHtml(p)}</div>`:""}` : "";
   $("#current").innerHTML = `<div class="card">
     <div class="goal">${esc(t.goal||"任務")}<span class="wsbadge">📁 ${esc(t.workspace||"default")}</span></div>
     <span class="status ${statusClass(t.status)}">${statusText(t.status)}${t.rounds?` · ${t.rounds} 輪`:""}</span>
     ${CANCELLABLE.includes(t.status)?`<button class="cancel" onclick="cancelTask('${t.taskId}')">停止</button>`:""}
     ${t.status==="running"||t.status==="queued"?progressHtml(t):""}
     ${todosHtml(t.progress)}
+    ${logSec}
     ${t.status==="needs-input"?`<div class="qbox"><div class="q">❓ ${esc(t.pending?.question)}</div>
       <input id="ans" placeholder="輸入你的回答，按 Enter 送出"></div>`:""}
     ${t.status==="done"?`<div class="summary">${esc(t.result?.text||"")}</div>`:""}

package/src/kernel/diff.js

@@ -0,0 +1,30 @@
+// 行級 diff（LCS）— 給 TUI/app 渲染彩色 diff。回傳 { lines:[{t,s}], added, removed } 或 { tooBig } 或 null（無變化）。
+// kernel 在 wrapUndo 已抓到 before（undo 快照），改完讀 after，集中算 diff,所有 pack 的 edit/write 免改。
+export function lineDiff(before, after, { maxLines = 600 } = {}) {
+  if (before === after) return null;
+  const a = before == null ? [] : String(before).replace(/\n$/, '').split('\n');
+  const b = after == null ? [] : String(after).replace(/\n$/, '').split('\n');
+  if (a.length === 1 && a[0] === '' && before == null) a.length = 0;
+  if (b.length === 1 && b[0] === '' && after == null) b.length = 0;
+  const m = a.length, n = b.length;
+  if (m > maxLines || n > maxLines) return { tooBig: true, added: n, removed: m };
+
+  // LCS DP（自後往前）
+  const dp = Array.from({ length: m + 1 }, () => new Uint32Array(n + 1));
+  for (let i = m - 1; i >= 0; i--) for (let j = n - 1; j >= 0; j--) dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+
+  const lines = [];
+  let i = 0, j = 0;
+  while (i < m && j < n) {
+    if (a[i] === b[j]) { lines.push({ t: ' ', s: a[i] }); i++; j++; }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { lines.push({ t: '-', s: a[i] }); i++; }
+    else { lines.push({ t: '+', s: b[j] }); j++; }
+  }
+  while (i < m) lines.push({ t: '-', s: a[i++] });
+  while (j < n) lines.push({ t: '+', s: b[j++] });
+
+  const added = lines.filter((l) => l.t === '+').length;
+  const removed = lines.filter((l) => l.t === '-').length;
+  if (!added && !removed) return null;
+  return { lines, added, removed };
+}

package/src/kernel/index.js

@@ -11,6 +11,7 @@ import { createPermissionStep } from './security/permission-step.js';
 import { fileAllowStore, memoryAllowStore } from './security/allow-store.js';
 import { normalizeSandbox, wrapWithSeatbelt, sandboxViolation } from './security/sandbox.js';
 import { dangerousReason } from './security/danger.js';
+import { lineDiff } from './diff.js';
 import { spawnSync } from 'node:child_process';
 import { createMemory } from './memory.js';
 import { createPlaybook } from './playbook.js';
@@ -94,20 +95,31 @@ function wrapSandboxable(tool, { cwd, getSandbox, getSandboxConfig }) {
 
 // undo 快照：mutating 且帶 args.path 的工具（檔案編輯類），執行前記錄檔案原狀，供 kernel.undo() 還原。
 // 「以 path 指涉被改檔案」是常見約定；非檔案型 mutating 工具（bash/sql_exec 無 path）不受影響。
+const isTextContent = (s) => s == null || !String(s).includes("\u0000");
 function wrapUndo(tool, { cwd, undoStack }) {
   if (tool.mutating !== true || typeof tool.execute !== 'function') return tool;
   const orig = tool.execute.bind(tool);
   return {
     ...tool,
-    execute: (id, params, ...rest) => {
+    execute: async (id, params, ...rest) => {
+      let abs = null, before = null;
       if (params?.path) {
-        const p = isAbsolute(params.path) ? params.path : join(cwd, params.path);
+        abs = isAbsolute(params.path) ? params.path : join(cwd, params.path);
         try {
-          undoStack.push({ path: p, rel: params.path, before: existsSync(p) ? readFileSync(p, 'utf8') : null });
+          before = existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+          undoStack.push({ path: abs, rel: params.path, before });
           if (undoStack.length > 50) undoStack.shift();
         } catch { /* 略 */ }
       }
-      return orig(id, params, ...rest);
+      const result = await orig(id, params, ...rest);
+      // 集中算 diff：用 before 快照 + 改後內容，掛在 result._diff（不進 LLM content，僅供 app 渲染）
+      if (abs && result && typeof result === 'object' && isTextContent(before)) {
+        try {
+          const after = existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+          if (isTextContent(after)) { const d = lineDiff(before, after); if (d) result._diff = { path: params.path, ...d }; }
+        } catch { /* 略 */ }
+      }
+      return result;
     },
   };
 }