xitto-kernel 0.5.0 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 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
+
+- **成品溯源/位置**：分邏輯與實體兩層。
+  - **邏輯位置(workspace)**：成品卡永遠標出 `📁 所屬空間`,一眼知道每份成品屬於哪個專案
+  - **實體路徑**：預設**不外露**(託管不洩漏伺服器絕對路徑);僅**本地模式**(`XITTO_SERVER_LOCAL=1` 或 `createServerApp({local:true})`)在 result 附 `workspaceDir`,網頁顯示「📂 檔案位置」(點擊複製,供到 Finder/Explorer 找檔)
+  - 真實 live 驗證:本地模式回絕對路徑 `/…/ws/<workspace>`、託管模式 `workspaceDir` 為 undefined。測試 174/174。
+
+## 0.6.0
+
+成品管理 + 類型感知呈現 + 專案空間（一次補上三組優化）。
+
+- **成品/過程檔管理**：
+  - 系統提示引導 agent：成品放工作目錄根用好檔名，暫存/草稿放 `tmp/`
+  - `runOutcome` 的成品掃描排除 `tmp/`（過程檔不污染交付清單）；job 完成後 server 自動清 `tmp/`
+- **類型感知的成品呈現**：
+  - file 端點按副檔名給對的 `content-type`（圖片能顯示、md/html 能渲染），支援 `?download=1`、二進位正確回傳
+  - 網頁類型感知檢視：markdown **排版渲染**（零依賴內嵌渲染器）、圖片 `<img>`、HTML 沙箱 iframe、JSON 美化、其餘下載；每個檔有「開新分頁／下載」
+  - `?token=` 查詢參數認證（img/iframe/下載這類無法帶 header 的瀏覽器 GET）
+- **專案／空間（對應 Claude Code 的「目錄」,但可選＋命名＋有預設）**：
+  - 網頁加「專案」下拉 + 新專案；不同空間的**檔案與五層沉澱各自獨立**；歷史按空間過濾
+  - 任務 view 帶 `workspace`；POST `/v1/tasks` 接受 `workspace`（修：原本被 enqueue 丟棄）
+- 3 個新測試（content-type / view.workspace / tmp 不算成品）+ 真實 server 端到端
+  （markdown 成品渲染、tmp 清理、download header、query token、workspace 隔離）。測試 174/174。
+
 ## 0.5.0
 
 - **持久工作空間（許願台成品間的關係）**：每個成品仍是獨立對話,但共用一個持久工作空間。

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,11 +102,14 @@ 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`,防路徑穿越)
 - **歷史成品**:過往交辦的清單(願望 + 狀態),不是聊天串
 
-**持久工作空間(成品間的關係)**:每個成品是**獨立的對話**(不續接前一個,避免 context 暴脹),但**共用一個持久工作空間**(`.xitto-server/ws/<workspace>`,預設 `default`)——所以 ① **檔案留存**,後面的任務能接續前面的成果(「把我上次做的 plan.md 翻成英文」);② **五層沉澱跨成品累積**(偏好/技能/經驗/信任)——它**越用越懂你**,不再是每次都從零開始的陌生人。`workspace` 可在 POST 時指定(多使用者各自一個)。
+**持久工作空間(成品間的關係)**:每個成品是**獨立的對話**(不續接前一個,避免 context 暴脹),但**共用一個持久工作空間**(`.xitto-server/ws/<workspace>`,預設 `default`)——所以 ① **檔案留存**,後面的任務能接續前面的成果(「把我上次做的 plan.md 翻成英文」);② **五層沉澱跨成品累積**(偏好/技能/經驗/信任)——它**越用越懂你**,不再是每次都從零開始的陌生人。`workspace` 可在 POST 時指定(多使用者各自一個);網頁有「專案」下拉切換,每份成品卡標出 `📁 所屬空間`。
+
+**溯源/檔案位置**:成品記錄它的**邏輯位置(workspace)**;**實體絕對路徑**預設不外露(託管不洩漏伺服器路徑),只在**本地模式**(`XITTO_SERVER_LOCAL=1`)才在成品附「📂 檔案位置」供你到 Finder/Explorer 找檔。
 
 零依賴單一 HTML(`src/app/web/index.html`),polling 不靠 SSE。token 注入頁面供同源呼叫——本地自用零設定;**正式部署請前置真實認證**。
 

package/package.json

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

package/src/app/server.js

@@ -3,8 +3,8 @@
 // JSON 或 SSE 串流，以及「背景任務 + 完成通知（webhook）」—— 派任務出去、做完回呼，不用一直盯著。
 // 這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
 import { createServer } from 'node:http';
-import { mkdirSync, readFileSync, existsSync } from 'node:fs';
-import { join, dirname, isAbsolute, relative } from 'node:path';
+import { mkdirSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { join, dirname, isAbsolute, relative, basename, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createKernel } from '../kernel/index.js';
 import { loadModel } from './providers.js';
@@ -23,6 +23,13 @@ const PACKS = {
 const lastText = (history) => ([...(history || [])].reverse().find((m) => m.role === 'assistant')?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
 const newId = (p = 's') => p + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
 
+// 交付檔案的 content-type（讓圖片能顯示、md/html 能渲染、其餘可下載）。
+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;
@@ -37,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' };
@@ -60,15 +67,22 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
   const subs = new Map();    // id -> Set<(ev)=>void>
   let active = 0;
 
-  const view = (t) => ({ taskId: t.id, status: t.status, pack: t.spec.pack || 'general', mode: t.spec.mode || 'turn', goal: t.spec.goal || t.spec.input || '', sessionId: t.result?.sessionId || t.spec.sessionId || null, createdAt: t.createdAt, startedAt: t.startedAt, finishedAt: t.finishedAt, error: t.error, pending: t.pending || null, progress: t.progress || null });
+  const view = (t) => ({ taskId: t.id, status: t.status, pack: t.spec.pack || 'general', mode: t.spec.mode || 'turn', workspace: t.spec.workspace || 'default', goal: t.spec.goal || t.spec.input || '', sessionId: t.result?.sessionId || t.spec.sessionId || null, createdAt: t.createdAt, startedAt: t.startedAt, finishedAt: t.finishedAt, error: t.error, pending: t.pending || null, progress: t.progress || null });
 
   const emit = (t, ev) => {
     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;
@@ -158,12 +172,13 @@ export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents =
  * @param {number} [o.concurrency]  背景任務同時數（預設 2）
  * @returns {import('node:http').Server}
  */
-export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true, concurrency = 2 } = {}) {
+export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true, concurrency = 2, local = false } = {}) {
   const sessions = new Map(); // sessionId -> { pack, history }
   mkdirSync(baseDir, { recursive: true });
 
   const json = (res, code, obj) => { res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(obj)); };
-  const authed = (req) => !token || (req.headers.authorization === `Bearer ${token}`);
+  // header bearer 為主；img/iframe/下載這類瀏覽器發起的 GET 無法帶 header,允許 ?token=（同源、PoC）
+  const authed = (req) => { if (!token) return true; if (req.headers.authorization === `Bearer ${token}`) return true; try { return new URL(req.url, 'http://x').searchParams.get('token') === token; } catch { return false; } };
   const log = (o) => console.log(JSON.stringify({ ts: new Date().toISOString(), ...o }));
   const readBody = (req) => new Promise((resolve) => { let b = ''; req.on('data', (c) => { b += c; if (b.length > 1e6) req.destroy(); }); req.on('end', () => { try { resolve(JSON.parse(b || '{}')); } catch { resolve({}); } }); });
   const sseHead = (res) => res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' });
@@ -186,11 +201,13 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
       // 結果導向：回傳交付物（做了什麼 + 產出的檔案 + 是否達成），對話只是過程
       const o = await kernel.runOutcome(spec.goal || spec.input || '', { history: sess.history, onEvent: wrapped, onAgent, onRound: (i) => wrapped({ type: 'round', round: i.round, maxRounds: i.maxRounds }) });
       sess.history = o.history || []; sessions.set(sessionId, sess);
-      return { sessionId, workspace, text: o.summary || lastText(sess.history), usage, rounds: o.rounds, done: o.done, aborted: o.aborted, artifacts: o.artifacts };
+      try { rmSync(join(workdir, 'tmp'), { recursive: true, force: true }); } catch { /* 清過程檔,失敗無妨 */ }
+      // 溯源：邏輯位置 workspace 永遠記；實體路徑只在本地模式給（託管不洩漏伺服器路徑）
+      return { sessionId, workspace, workspaceDir: local ? resolve(workdir) : undefined, text: o.summary || lastText(sess.history), usage, rounds: o.rounds, done: o.done, aborted: o.aborted, artifacts: o.artifacts };
     }
     const r = await kernel.runTurn(spec.input || '', { history: sess.history, onEvent: wrapped, onAgent });
     sess.history = r.messages || r.history || []; sessions.set(sessionId, sess);
-    return { sessionId, workspace, text: r.text ?? lastText(sess.history), usage, rounds: r.rounds, done: r.done };
+    return { sessionId, workspace, workspaceDir: local ? resolve(workdir) : undefined, text: r.text ?? lastText(sess.history), usage, rounds: r.rounds, done: r.done };
   }
 
   // 完成通知：POST 結果到 spec.webhook（http/https），單次嘗試、失敗記日誌不重試（PoC）
@@ -245,7 +262,7 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
       const body = await readBody(req);
       if (!PACKS[body.pack || 'general']) return json(res, 400, { error: `未知 pack「${body.pack}」，可用：${Object.keys(PACKS).join(', ')}` });
       if (body.webhook && !/^https?:\/\//.test(body.webhook)) return json(res, 400, { error: 'webhook 需為 http(s) URL' });
-      const t = tasks.enqueue({ pack: body.pack, mode: body.mode, input: body.input, goal: body.goal, sessionId: body.sessionId, webhook: body.webhook });
+      const t = tasks.enqueue({ pack: body.pack, mode: body.mode, input: body.input, goal: body.goal, sessionId: body.sessionId, webhook: body.webhook, workspace: body.workspace });
       log({ task: t.id, action: 'enqueue', pack: body.pack || 'general', mode: body.mode || 'turn' });
       return json(res, 202, { taskId: t.id, status: t.status, ...tasks.stats() });
     }
@@ -280,11 +297,17 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
     if (req.method === 'GET' && mFile) {
       const t = tasks.get(mFile[1]); const ws = t?.result?.workspace;
       if (!ws) return json(res, 404, { error: '無交付物（任務尚未完成?）' });
-      const full = resolveArtifact(join(baseDir, 'ws', ws), url.searchParams.get('path'));
+      const rel = url.searchParams.get('path');
+      const full = resolveArtifact(join(baseDir, 'ws', ws), rel);
       if (!full) return json(res, 400, { error: 'path 不合法' });
       if (!existsSync(full)) return json(res, 404, { error: '檔案不存在' });
-      try { res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' }); return res.end(readFileSync(full)); }
-      catch (e) { return json(res, 500, { error: e.message }); }
+      try {
+        const ct = contentTypeFor(rel);
+        const isText = /^text\/|json|xml|javascript|svg/.test(ct);
+        const headers = { 'content-type': ct + (isText ? '; charset=utf-8' : '') };
+        if (url.searchParams.get('download')) headers['content-disposition'] = `attachment; filename="${encodeURIComponent(basename(rel))}"`;
+        res.writeHead(200, headers); return res.end(readFileSync(full));
+      } catch (e) { return json(res, 500, { error: e.message }); }
     }
 
     // 附掛背景任務的事件流（replay 緩衝 + 即時；已結束則回放後關閉）
@@ -310,11 +333,12 @@ export function startServer() {
   const token = process.env.XITTO_SERVER_TOKEN || 'dev-token';
   const sandbox = process.env.XITTO_SERVER_SANDBOX !== 'off';
   const concurrency = Number(process.env.XITTO_SERVER_CONCURRENCY || 2);
+  const local = process.env.XITTO_SERVER_LOCAL === '1' || process.env.XITTO_SERVER_LOCAL === 'true';
   const { model, getApiKey } = loadModel(process.env.XITTO_MODEL);
-  const server = createServerApp({ model, getApiKey, token, sandbox, concurrency });
+  const server = createServerApp({ model, getApiKey, token, sandbox, concurrency, local });
   server.listen(port, () => {
     console.log(`🪄 許願台：http://localhost:${port}/  （瀏覽器打開即用——說出目標、交付成品）`);
-    console.log(`xitto-kernel server · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'} · 背景並發 ${concurrency}`);
+    console.log(`xitto-kernel server · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'} · 背景並發 ${concurrency}${local ? ' · 本地模式(顯示檔案位置)' : ''}`);
     console.log(`token: ${token === 'dev-token' ? 'dev-token（請設 XITTO_SERVER_TOKEN）' : '(已設定)'}`);
     console.log('API：POST /v1/run · /v1/stream · /v1/tasks · /v1/tasks/:id/{answer,cancel}｜GET /v1/tasks[/:id[/events|/file]] · /health');
   });

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

@@ -39,6 +39,18 @@
   .todo.completed { color:var(--ok); }
   button.cancel { margin-left:10px; padding:3px 12px; font-size:12px; background:transparent; color:#f08a8a; border:1px solid #5b3030; }
   button.cancel:hover { background:#2a1818; }
+  .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; }
@@ -52,8 +64,17 @@
   .hist { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:11px 14px; margin:8px 0; cursor:pointer; }
   .hist:hover { border-color:var(--accent); }
   .hist .g { font-size:14px; } .hist .m { color:var(--dim); font-size:12px; }
-  pre.viewer { background:#0c0e12; border:1px solid var(--line); border-radius:10px; padding:12px; overflow:auto; max-height:360px; white-space:pre-wrap; font:13px/1.5 ui-monospace,Menlo,monospace; }
   .empty { color:var(--dim); font-size:13px; }
+  .viewer { margin-top:10px; border:1px solid var(--line); border-radius:10px; padding:12px; background:#0c0e12; }
+  .vbar { font-size:12px; color:var(--dim); margin-bottom:8px; }
+  .vbar a { color:var(--accent); text-decoration:none; }
+  .vimg { max-width:100%; border-radius:8px; }
+  .vframe { width:100%; height:420px; border:0; background:#fff; border-radius:8px; }
+  .viewer-pre { white-space:pre-wrap; font:13px/1.5 ui-monospace,Menlo,monospace; margin:0; color:var(--fg); overflow:auto; max-height:420px; }
+  .md { line-height:1.65; } .md h1,.md h2,.md h3,.md h4 { margin:.7em 0 .3em; line-height:1.3; }
+  .md code { background:#1a1d24; padding:1px 5px; border-radius:4px; font-size:.9em; }
+  .md pre.code { background:#1a1d24; padding:10px; border-radius:8px; overflow:auto; }
+  .md ul { margin:.3em 0 .3em 1.2em; } .md a { color:var(--accent); } .md p { margin:.5em 0; }
 </style>
 </head>
 <body>
@@ -61,6 +82,9 @@
   <header>
     <h1>🪄 xitto 許願台</h1>
     <span class="sub">說出你想完成的事，交給它去做、做完給你成品</span>
+    <span class="spacer"></span>
+    <select id="space" title="專案／空間：不同專案的檔案與記憶各自獨立"></select>
+    <button class="ghost" id="newspace" title="新專案">＋</button>
   </header>
 
   <div class="ask">
@@ -105,12 +129,69 @@ setInterval(() => { if (liveTask && (liveTask.status==="running"||liveTask.statu
 const LABELS = { general:"通用", coding:"程式", "data-query":"查資料", notes:"筆記", "deep-research":"研究", devops:"維運" };
 $("#pack").innerHTML = PACKS.map(p=>`<option value="${p}" ${p==="general"?"selected":""}>${LABELS[p]||p}</option>`).join("");
 
+// 專案／空間（對應 Claude Code 的「目錄」,但可選＋命名＋有預設；不同空間的檔案與沉澱各自獨立）
+let spaces = JSON.parse(localStorage.getItem("xk_spaces")||'["default"]');
+let curSpace = localStorage.getItem("xk_space")||"default";
+function renderSpaces(){ $("#space").innerHTML = spaces.map(s=>`<option ${s===curSpace?"selected":""}>${esc(s)}</option>`).join(""); }
+$("#space").onchange = () => { curSpace=$("#space").value; localStorage.setItem("xk_space",curSpace); $("#current").innerHTML=""; loadHistory(); };
+$("#newspace").onclick = () => { const n=(prompt("新專案名稱（英數/底線/連字號）：")||"").trim().replace(/[^a-zA-Z0-9_-]/g,""); if(!n)return; if(!spaces.includes(n))spaces.push(n); curSpace=n; localStorage.setItem("xk_spaces",JSON.stringify(spaces)); localStorage.setItem("xk_space",curSpace); renderSpaces(); $("#current").innerHTML=""; loadHistory(); };
+renderSpaces();
+
+// 極簡 markdown 渲染（零依賴、可離線；夠用於 agent 產的報告）
+function mdRender(src){
+  const lines=String(src).replace(/\r/g,"").split("\n"); const out=[]; let inCode=false,buf=[],inList=false;
+  const inline=s=>esc(s).replace(/`([^`]+)`/g,'<code>$1</code>').replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>').replace(/\*([^*]+)\*/g,'<em>$1</em>').replace(/\[([^\]]+)\]\((https?:[^)]+)\)/g,'<a href="$2" target="_blank">$1</a>');
+  const closeL=()=>{ if(inList){out.push("</ul>");inList=false;} };
+  for(const ln of lines){
+    if(/^```/.test(ln)){ if(inCode){out.push("<pre class='code'>"+esc(buf.join("\n"))+"</pre>");buf=[];inCode=false;}else{closeL();inCode=true;} continue; }
+    if(inCode){ buf.push(ln); continue; }
+    const h=ln.match(/^(#{1,4})\s+(.*)/); if(h){ closeL(); out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`); continue; }
+    const li=ln.match(/^\s*(?:[-*]|\d+\.)\s+(.*)/); if(li){ if(!inList){out.push("<ul>");inList=true;} out.push("<li>"+inline(li[1])+"</li>"); continue; }
+    if(ln.trim()===""){ closeL(); continue; }
+    closeL(); out.push("<p>"+inline(ln)+"</p>");
+  }
+  closeL(); if(inCode)out.push("<pre class='code'>"+esc(buf.join("\n"))+"</pre>");
+  return out.join("");
+}
+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>`;
+  if(IMG.test(name)){ v.innerHTML=bar+`<img class="vimg" src="${fileUrl(id,path)}">`; return; }
+  if(HTMLF.test(name)){ v.innerHTML=bar+`<iframe class="vframe" sandbox src="${fileUrl(id,path)}"></iframe>`; return; }
+  v.innerHTML=bar+`<div class="empty">載入中…</div>`;
+  const txt=await fetch(fileUrl(id,path)).then(r=>r.ok?r.text():null).catch(()=>null);
+  if(txt==null){ v.innerHTML=bar+`<div class="empty">（無法以文字呈現，請下載）</div>`; return; }
+  let body;
+  if(MD.test(name)) body=`<div class="md">${mdRender(txt)}</div>`;
+  else if(JSONF.test(name)){ try{ body=`<pre class="viewer-pre">${esc(JSON.stringify(JSON.parse(txt),null,2))}</pre>`; }catch{ body=`<pre class="viewer-pre">${esc(txt)}</pre>`; } }
+  else body=`<pre class="viewer-pre">${esc(txt)}</pre>`;
+  v.innerHTML=bar+body;
+}
+
 let activeId = null, polling = null;
 
 $("#go").onclick = async () => {
   const goal = $("#goal").value.trim(); if (!goal) return;
   $("#go").disabled = true;
-  const r = await api("/v1/tasks", { method:"POST", body: JSON.stringify({ pack:$("#pack").value, mode:"goal", goal }) }).then(r=>r.json());
+  const r = await api("/v1/tasks", { method:"POST", body: JSON.stringify({ pack:$("#pack").value, mode:"goal", goal, workspace: curSpace }) }).then(r=>r.json());
   $("#go").disabled = false;
   if (r.error) { alert(r.error); return; }
   $("#goal").value = "";
@@ -136,18 +217,22 @@ 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||"任務")}</div>
+    <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>`:""}
     ${t.status==="error"?`<div class="summary">⚠ ${esc(t.error)}</div>`:""}
-    ${files.length?`<div class="files">📦 成品：${files.map(([f,k])=>`<span class="file ${k==="mod"?"mod":""}" onclick="viewFile('${t.taskId}','${esc(f)}')">${k==="mod"?"~":"+"} ${esc(f)}</span>`).join("")}</div>`:""}
-    <pre class="viewer" id="fview" style="display:none"></pre>
+    ${files.length?`<div class="files">📦 成品：${files.map(([f,k])=>`<span class="file ${k==="mod"?"mod":""}" onclick="viewFile('${t.taskId}','${encodeURIComponent(f)}','${esc(f)}')">${k==="mod"?"~":"+"} ${esc(f)}</span>`).join("")}</div>`:""}
+    ${t.result&&t.result.workspaceDir?`<div class="loc">📂 檔案位置：<code title="點擊複製" onclick="navigator.clipboard&&navigator.clipboard.writeText('${esc(t.result.workspaceDir)}')">${esc(t.result.workspaceDir)}</code></div>`:""}
+    <div class="viewer" id="fview" style="display:none"></div>
   </div>`;
   if (t.status==="needs-input") {
     const inp = $("#ans"); inp.focus();
@@ -159,15 +244,9 @@ function renderCurrent(t) {
   }
 }
 
-async function viewFile(id, path) {
-  const v = $("#fview"); v.style.display="block"; v.textContent="載入中…";
-  const r = await api("/v1/tasks/"+id+"/file?path="+encodeURIComponent(path));
-  v.textContent = r.ok ? await r.text() : "（無法讀取）";
-}
-
 async function loadHistory() {
   const r = await api("/v1/tasks").then(r=>r.json());
-  const list = (r.tasks||[]).filter(t=>t.mode==="goal").reverse();
+  const list = (r.tasks||[]).filter(t=>t.mode==="goal" && (t.workspace||"default")===curSpace).reverse();
   $("#history").innerHTML = list.length ? list.map(t=>`<div class="hist" onclick="openTask('${t.taskId}')">
     <div class="g">${esc(t.goal||t.taskId)} <span class="status ${statusClass(t.status)}">${statusText(t.status)}</span></div>
     <div class="m">${esc(t.createdAt)}</div></div>`).join("") : `<div class="empty">還沒有任何任務。</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';
@@ -45,7 +46,7 @@ function loadContextFiles(cwd, names) {
 }
 
 // 交付物偵測：掃工作目錄前後快照,diff 出「產出/改動的檔案」（pack 無關,連 bash 寫的也抓得到）。
-const SKIP_SCAN = new Set(['.xitto-kernel', 'node_modules', '.git', '.swebench-repos', '.xitto-server']);
+const SKIP_SCAN = new Set(['.xitto-kernel', 'node_modules', '.git', '.swebench-repos', '.xitto-server', 'tmp']);
 function scanWorkdir(dir, base = dir, acc = new Map(), depth = 0) {
   if (depth > 8 || acc.size > 5000) return acc;
   let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
@@ -72,6 +73,9 @@ const DEFAULT_PLAYBOOK_GUIDE =
 const DEFAULT_EPISODE_GUIDE =
   '完成有價值的任務後，用 episode_record 記一筆情節(做了什麼+結果+tags)；遇到相似任務時系統會自動召回最相關的幾筆供參考，也可主動用 episode_recall 查。';
 
+const DEFAULT_OUTPUT_GUIDE =
+  '產出檔案時：最終成品放工作目錄根、用清楚好懂的檔名(如 report.md、budget.csv，別用 tmp_3.txt)；中間/暫存檔(下載、草稿、解壓內容、爬到的原始資料)一律放 tmp/ 目錄——那是過程檔，不算成品也可能被清掉。';
+
 // 把 sandboxable 工具的命令在執行期包進 Seatbelt（macOS OS 級隔離）。
 // 非 macOS / 沙箱關閉 / 無 command → wrapWithSeatbelt 回 null，跑原命令（仍受第 5 格靜態策略保護）。
 function wrapSandboxable(tool, { cwd, getSandbox, getSandboxConfig }) {
@@ -91,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;
     },
   };
 }
@@ -221,6 +236,7 @@ export function createKernel(pack, config = {}) {
     pack.systemPrompt +
     loadContextFiles(cwd, pack.contextFiles) +          // 注入領域規範檔（CLAUDE.md 等）
     '\n\n# 記憶與專案手冊\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) + '\n' + DEFAULT_PLAYBOOK_GUIDE + '\n' + DEFAULT_EPISODE_GUIDE +
+    '\n\n# 成品與暫存\n' + DEFAULT_OUTPUT_GUIDE +
     (memText ? `\n\n# 已記住的事實（跨 session）\n${memText}` : '') +
     (pbText ? `\n\n# 專案手冊（這個專案怎麼做事，跨 session 累積）\n${pbText}` : '') +
     (askUserTool ? '\n\n# 詢問\n盡量自主完成目標。只在缺少關鍵資訊、無法合理推斷、或決策會明顯改變結果時，才用 ask_user 問使用者；能用合理預設就別問。' : '') +