xitto-kernel 0.2.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.3.2
+
+- **沒設定就啟動 → 直接進導引**：偵測到沒有 providers.json 且在真實終端時，
+  不再只印提示，而是直接帶進 `init` 設定流程，完成後接續啟動該 pack（非 TTY 仍只給提示）。
+
+## 0.3.1
+
+首次使用導引 —— 不再假設使用者已有 xitto-code。
+
+### 新增
+
+- **`xitto-kernel init`**：互動式設定導引，產生 `~/.xitto-code/providers.json`
+  - 內建 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）
+  - 引導選 provider → 填 model → 處理 API key（環境變數參照 `${NAME}` 不落地，或內嵌）
+  - 既有設定不覆寫；`--force` 合併新 provider
+  - pipe-safe 逐行讀取（可 `echo answers | xitto-kernel init` 腳本化）
+- **沒設定就啟動**：改丟明確提示，引導跑 `xitto-kernel init`（不再叫人去找 xitto-code 的範例檔）
+- README 快速開始改為 安裝 → `init` → 啟動 三步
+
+## 0.3.0
+
+把底座的「能力」與「體驗」補到接近 Claude Code，並擴充領域 pack 與評測。
+
+### 新增
+
+- **完整 Ink TUI**（`--tui`）：持久底部狀態列（model/cwd/git/權限/sandbox/plan/ctx）、`Static` 捲動轉錄、即時串流重繪、Esc 中斷、markdown/程式碼語法高亮、Select 式權限詢問；非真實終端自動退回 readline CLI
+- **新領域 pack**：`deep-research`（多源檢索→深讀→綜整）、`devops`
+- **agent loop 內建化**：把 xitto-code 的 agent loop 移植進 `runTurn`（自帶、用 pi-ai streamFn）
+- **真實 sandbox 接入守衛鏈第 5 格**：macOS Seatbelt（sandbox-exec）OS 層隔離
+- **server app PoC**：把 kernel 包成 HTTP 服務（`/v1/run`、`/v1/stream` SSE、bearer 驗證、per-session workdir）
+- **評測框架**：scorers（answerMatch/stateCheck/toolCalled/allOf）+ SWE-bench mini 與真實 SWE-bench Verified adapter；各 pack eval 套件
+- 套件匯出補上 `./packs/general`、`./packs/deep-research`、`./packs/devops`
+
+### 驗證
+
+- 真實 SWE-bench Verified：coding pack（MiniMax）可重現解出 flask-5014、requests-1142 等
+- 測試 116/116 通過（含 Ink TUI 煙霧測試）
+
 ## 0.2.0
 
 第一個功能完整版 —— 從 0.1.0（基礎 kernel + CLI + 腳手架）補齊近乎 xitto-code 等價的能力，

package/README.md

@@ -23,20 +23,26 @@ xitto-code 經掃描後，約 **8 成已是領域無關的 kernel**；真正跟
 
 ## 快速開始
 
-**前置需求**
-- Node.js ≥ 20
-- `~/.xitto-code/providers.json` —— LLM provider 設定（與 xitto-code 共用，內含 API key）。
-  沒有的話，複製一份填入 key 即可（格式見 xitto-code 的 `providers.example.json`）。
+**前置需求**：Node.js ≥ 20
 
-**安裝**（已發佈 npm）
+**1. 安裝**（已發佈 npm）
 ```bash
 npm install -g xitto-kernel    # 全域命令 xitto-kernel
 ```
 > 開發本倉庫：`cd xitto-kernel && npm install && npm link`。
 
-**跑內建 pack（互動 CLI）**
+**2. 首次設定**（互動導引，產生 `~/.xitto-code/providers.json`）
+```bash
+xitto-kernel init
+```
+引導你選 provider（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂）→ 填 model →
+設定 API key（建議用環境變數參照 `${NAME}`，金鑰不落地）。已是 xitto-code 使用者可直接共用既有設定、跳過此步。
+（沒設定就啟動會提示你跑 `init`；既有設定不會被覆寫，`--force` 才會合併新 provider。）
+
+**3. 跑內建 pack（互動 CLI）**
 ```bash
 xitto-kernel                  # coding agent（讀寫檔案、跑命令）
+xitto-kernel --tui            # 完整 Ink TUI（持久狀態列、串流、Esc 中斷；需真實終端）
 xitto-kernel --pack notes     # 筆記 / 知識庫 agent
 xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
@@ -50,6 +56,22 @@ xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫
 ```
 `general` pack（檔案/shell/web_fetch）+ kernel 的 **goal loop**（反覆 runTurn + LLM 自我驗收，直到達成/無進展/上限）。互動模式用 `/goal <目標>`。
 
+## 當成服務跑（不只 CLI）
+
+kernel 是 UI 無關的，CLI 只是其中一個 app。`src/app/server.js` 是把它包成 **HTTP 服務**的 PoC
+（零依賴 `node:http`）—— 證明「個人工具 → 可服務化底座」：
+
+```bash
+XITTO_SERVER_TOKEN=secret npm run serve     # http://localhost:8787
+curl -s localhost:8787/health
+curl -s -XPOST localhost:8787/v1/run -H "Authorization: Bearer secret" \
+  -H content-type:application/json -d '{"pack":"general","sessionId":"s1","input":"..."}'
+```
+
+特性：bearer token 認證、**per-session 隔離工作目錄 + 歷史**（多輪記得上文）、沙箱（Seatbelt）、
+結構化 JSON 日誌（審計/觀測）、6 個 pack 可選、JSON 或 SSE（`/v1/stream`）串流。
+「個人 vs 生產」是 **app 層**的事 —— 同一個 kernel，CLI 與 server 是兩個 app。
+
 ## 做你自己的領域 agent（不固化）
 
 kernel 是**被依賴的套件**，不是被 clone 的範本。你的 agent 是獨立小專案：
@@ -101,7 +123,9 @@ xitto-kernel/
 │       ├── coding/               ✅ 參考 pack（read/ls/write/edit/bash/git）
 │       ├── data-query/           ✅ 第二領域（證明正交）
 │       ├── notes/                ✅ 第三領域（知識庫）
-│       └── general/              ✅ 通用自主 agent（檔案/shell/web_fetch + goal loop）
+│       ├── general/              ✅ 通用自主 agent（檔案/shell/web/http + goal loop）
+│       ├── deep-research/        ✅ 深度研究（多來源搜尋→查證→有引用結論）
+│       └── devops/               ✅ 維運/SRE（shell + bash_bg + 設定 + 日誌 + 健康檢查）
 ├── bin/xitto-kernel.js           ✅ CLI 進入點（run / new-agent）
 ├── test/                         ✅ 41 測試全綠（runTurn + Seatbelt 隔離 + 腳手架 + …）
 └── examples/
@@ -138,6 +162,23 @@ xitto-kernel/
 
 **設計取向**：沿用 Node ESM + pi-ai provider 抽象；不重寫 xitto-code（kernel 是抽象，xitto-code 仍可獨立存在）。
 
+## 評估（能力可量化）
+
+每個 pack 配一個 EvalSuite（`eval/`，共用 `eval/framework.js`，不進 npm 包）。
+範式：**新領域 agent = 新 pack（會什麼）+ 新 EvalSuite（怎麼打分）**。
+
+| Suite | 對標 | 評分方式 | 跑法 | 參考結果* |
+|------|------|------|------|------|
+| coding | SWE-bench Verified | 隱藏測試 fail→pass（Docker）| `eval/swebench-generate.js` + 官方 harness | 3/8 resolved（真實子集）|
+| coding（迷你）| SWE-bench 風格 | 隱藏測試（免 Docker）| `npm run eval` | 4/4 |
+| general | GAIA 風格 | 答案比對 / 狀態檢查 | `node eval/general-run.js` | 4/4 |
+| data-query | Spider/BIRD 風格 | 真實 SQLite + 答案比對 | `node eval/data-query-run.js` | 4/4 |
+| deep-research | GAIA/研究 | 事實正確 + 真的查證（allOf）| `node eval/deep-research-run.js` | 3/3 |
+| devops | Terminal-Bench 風格 | 狀態檢查（系統/檔案達標）| `node eval/devops-run.js` | 4/4 |
+| 工具呼叫 | BFCL 風格 | 軌跡檢查（呼叫對工具/參數）| `node eval/tool-calling-run.js` | 6/6 |
+
+\* 用 MiniMax-M2.7 跑的參考數字（小樣本）；換模型/擴樣本見 `eval/README.md`。scorer 型：`answerMatch` / `stateCheck` / `toolCalled`。
+
 ## 貢獻
 
 見 [CONTRIBUTING.md](CONTRIBUTING.md)。核心原則：kernel 必須領域無關（安全行為靠工具 metadata，不寫死領域名單）；新領域 = 新增一個 pack，kernel 零改動。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [
@@ -40,6 +40,8 @@
   "scripts": {
     "test": "node --test",
     "demo": "node examples/demo.js",
+    "eval": "node eval/run.js",
+    "serve": "node src/app/server.js",
     "start": "node bin/xitto-kernel.js"
   },
   "exports": {
@@ -47,10 +49,21 @@
     "./app": "./src/app/index.js",
     "./packs/coding": "./src/packs/coding/index.js",
     "./packs/data-query": "./src/packs/data-query/index.js",
-    "./packs/notes": "./src/packs/notes/index.js"
+    "./packs/notes": "./src/packs/notes/index.js",
+    "./packs/general": "./src/packs/general/index.js",
+    "./packs/deep-research": "./src/packs/deep-research/index.js",
+    "./packs/devops": "./src/packs/devops/index.js"
   },
   "dependencies": {
     "@mariozechner/pi-ai": "^0.70.6",
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "cli-highlight": "^2.1.11",
+    "ink": "^5.2.1",
+    "marked": "^12.0.2",
+    "marked-terminal": "^7.3.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "ink-testing-library": "^4.0.0"
   }
 }

package/src/app/cli.js

@@ -41,6 +41,26 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   let history = [];
   let currentAgent = null;
   let streaming = false;
+  const turnUsage = { input: 0, output: 0 }; // 本輪 token 累計（顯示頁腳）
+
+  // 等待 LLM 時的 spinner（首個可見輸出出現即停）
+  const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinTimer = null;
+  const startSpin = () => {
+    if (!process.stdout.isTTY) return; // 非互動（管線）不顯示 spinner，避免 \r 雜訊
+    let i = 0; const t0 = Date.now();
+    spinTimer = setInterval(() => { process.stdout.write(`\r\x1b[2m${FRAMES[i++ % FRAMES.length]} 思考中… ${Math.round((Date.now() - t0) / 1000)}s\x1b[0m\x1b[K`); }, 100);
+  };
+  const stopSpin = () => { if (spinTimer) { clearInterval(spinTimer); spinTimer = null; process.stdout.write('\r\x1b[K'); } };
+
+  // 目前模式標記（提示列前綴，讓使用者隨時看到狀態）
+  const modeTag = () => {
+    const t = [];
+    if (planMode) t.push('plan');
+    if (sandboxOn) t.push('🔒');
+    if (autoApprove) t.push('⚡');
+    return t.length ? c.gray('[' + t.join(' ') + '] ') : '';
+  };
 
   // 互動權限確認：守衛鏈第 5 格對 mutating/危險工具呼叫此函數。autoApprove → 一律放行。
   // 回 'yes'（允許一次）/ 'always'（此工具全部）/ 'no'（拒絕）。
@@ -88,13 +108,15 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   const onEvent = (ev) => {
+    if (ev.type === 'message_end' && ev.message?.usage) { turnUsage.input += ev.message.usage.input || 0; turnUsage.output += ev.message.usage.output || 0; }
     switch (ev.type) {
       case 'message_update': {
         const a = ev.assistantMessageEvent;
-        if (a?.type === 'text_delta' && a.delta) { md.push(a.delta); streaming = true; }
+        if (a?.type === 'text_delta' && a.delta) { stopSpin(); md.push(a.delta); streaming = true; }
         break;
       }
       case 'tool_execution_start':
+        stopSpin();
         endStream();
         if (ev.toolName === 'todo_write' && Array.isArray(ev.args?.todos)) {
           out(c.cyan('☑ 待辦更新\n'));
@@ -202,7 +224,14 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     }
   };
 
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: c.blue('› ') });
+  // 斜線指令 tab 補全
+  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/memory', '/sessions', '/resume', '/clear', '/exit'];
+  const completer = (line) => {
+    if (!line.startsWith('/')) return [[], line];
+    const hits = SLASH.filter((s) => s.startsWith(line));
+    return [hits.length ? hits : SLASH, line];
+  };
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: c.blue('› '), completer, historySize: 200 });
   let closed = false;
   const cleanup = () => { try { rl.close(); } catch { /* 略 */ } try { onExit?.(); } catch { /* 略 */ } };
   const finish = () => { cleanup(); process.exit(0); };
@@ -210,13 +239,13 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
 
   // Ctrl+C：執行中→中斷該輪；閒置→離開
   process.on('SIGINT', () => {
-    if (currentAgent) { currentAgent.abort(); out(c.yellow('\n⏹ 已中斷本輪\n')); }
+    if (currentAgent) { stopSpin(); currentAgent.abort(); out(c.yellow('\n⏹ 已中斷本輪\n')); }
     else { out(c.gray('\n再見。\n')); cleanup(); process.exit(0); }
   });
 
   // 橫幅
   out('\n' + c.cyan('✻ ') + c.bold('xitto-kernel') + c.gray(`  ·  ${pack.name} pack  ·  ${model.id}`) + '\n');
-  out(c.gray(`  沙箱 ${sandboxOn ? '開' : '關'}${seatbeltAvailable() ? '（Seatbelt 可用）' : ''}  ·  /help 看指令  ·  Ctrl+C 中斷/離開`) + '\n');
+  out(c.gray(`  沙箱 ${sandboxOn ? '開' : '關'}${seatbeltAvailable() ? '（Seatbelt 可用）' : ''}  ·  /help · Tab 補全 · ↑↓ 歷史 · Ctrl+C 中斷/離開`) + '\n');
   if (resumedNote) out(c.gray('  ' + resumedNote) + '\n');
   out('\n');
 
@@ -224,7 +253,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     if (closed) return finish();
     let q;
     try { q = rl.question.bind(rl); } catch { return finish(); }
-    q(c.blue('› '), async (raw) => {
+    q(modeTag() + c.blue('› '), async (raw) => {
       const input = (raw || '').trim();
       if (!input) return loop();
       // /goal <目標>：目標驅動自主循環（在此 await，避免與下一個提示交錯）
@@ -233,13 +262,16 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         if (!goal) { out(c.gray('用法 /goal <目標>\n')); return loop(); }
         try {
           out(c.cyan('🎯 目標：') + goal + '\n');
+          turnUsage.input = 0; turnUsage.output = 0;
+          const t0 = Date.now();
           const r = await kernel.runGoal(goal, {
             history,
-            onRound: ({ round, maxRounds }) => out(c.yellow(`\n🔁 第 ${round}/${maxRounds} 輪\n`)),
-            onCheck: ({ done, remaining }) => out(done ? c.green('  ✓ 驗收：已達成\n') : c.gray(`  ↻ ${remaining}\n`)),
+            onRound: ({ round, maxRounds }) => { stopSpin(); out(c.yellow(`\n🔁 第 ${round}/${maxRounds} 輪 `)); startSpin(); },
+            onCheck: ({ done, remaining }) => { stopSpin(); out(done ? c.green('  ✓ 驗收：已達成\n') : c.gray(`  ↻ ${remaining}\n`)); },
             onEvent, onAgent: (a) => { currentAgent = a; },
           });
-          endStream(); history = r.history; persist();
+          stopSpin(); endStream(); history = r.history; persist();
+          out(c.gray(`↳ ${((Date.now() - t0) / 1000).toFixed(1)}s · ${turnUsage.input + turnUsage.output} tokens · ${r.rounds} 輪`) + '\n');
           const why = r.stalled ? '無進展' : r.aborted ? '中斷' : r.verifyBroken ? '驗收持續失敗' : '到上限';
           out('\n' + (r.done ? c.green(`✅ 目標達成（${r.rounds} 輪）`) : c.yellow(`⚠ 未達成（${why}，${r.rounds} 輪）`)) + '\n');
         } catch (err) { endStream(); out(c.red('錯誤：' + err.message) + '\n'); }
@@ -251,13 +283,19 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         const text = planMode
           ? `[計劃模式：只制定計劃，列出你打算做的步驟與會改動的檔案，不要實際寫檔或執行命令]\n\n${input}`
           : input;
+        turnUsage.input = 0; turnUsage.output = 0;
+        const t0 = Date.now();
+        startSpin();
         const r = await kernel.runTurn(text, {
           history, onEvent, onAgent: (a) => { currentAgent = a; },
         });
+        stopSpin();
         endStream();
         history = r.messages;
         persist();                 // 每輪結束自動存檔（可 /resume 續接）
+        out(c.gray(`↳ ${((Date.now() - t0) / 1000).toFixed(1)}s · ${turnUsage.input + turnUsage.output} tokens`) + '\n');
       } catch (err) {
+        stopSpin();
         endStream();
         out(c.red('錯誤：' + err.message) + '\n');
       } finally {

package/src/app/index.js

@@ -1,5 +1,6 @@
 // app 子路徑公開 API（xitto-kernel/app）：外部 agent 專案 import 這些來啟動，不需改 kernel。
 export { runCli } from './cli.js';
+export { createServerApp, startServer } from './server.js';
 export { loadModel, loadProvidersConfig, buildModel } from './providers.js';
 export { newAgent } from './scaffold.js';
 export { main } from './main.js';

package/src/app/init.js

@@ -0,0 +1,134 @@
+// 首次啟動導引：互動式產生 ~/.xitto-code/providers.json。
+// 內建常見 provider 範本（MiniMax / Anthropic / OpenAI / DeepSeek / 自訂），
+// 引導選 provider → 填 model → 處理 API key（環境變數或內嵌），寫檔不覆寫既有設定。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
+const green = e(32); const gray = e(90); const cyan = e(36); const yellow = e(33); const bold = e(1); const red = e(31);
+
+// provider 範本（沿用實測可用的格式；baseUrl/api/model 皆可在引導中改）
+const PRESETS = {
+  minimax: { label: 'MiniMax（M2.7，anthropic 相容）', api: 'anthropic-messages', baseUrl: 'https://api.minimaxi.com/anthropic', env: 'MINIMAX_API_KEY', model: { id: 'MiniMax-M2.7', name: 'MiniMax M2.7', contextWindow: 1000192, maxTokens: 131072 } },
+  anthropic: { label: 'Anthropic Claude', api: 'anthropic-messages', baseUrl: 'https://api.anthropic.com', env: 'ANTHROPIC_API_KEY', model: { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', contextWindow: 200000, maxTokens: 64000 } },
+  openai: { label: 'OpenAI', api: 'openai-completions', baseUrl: 'https://api.openai.com/v1', env: 'OPENAI_API_KEY', model: { id: 'gpt-4o', name: 'GPT-4o', contextWindow: 128000, maxTokens: 16384 } },
+  deepseek: { label: 'DeepSeek', api: 'openai-completions', baseUrl: 'https://api.deepseek.com', env: 'DEEPSEEK_API_KEY', model: { id: 'deepseek-chat', name: 'DeepSeek Chat', contextWindow: 64000, maxTokens: 8192 } },
+  custom: { label: '自訂（手動填全部）', api: 'openai-completions', baseUrl: '', env: 'LLM_API_KEY', model: { id: '', name: '', contextWindow: 32000, maxTokens: 4096 } },
+};
+
+const PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
+
+export { PRESETS };
+
+// 純函數：把答案組成 providers.json 結構（合併既有 providers）。互動殼與測試共用。
+export function buildConfig(a, existing) {
+  const cfg = existing && existing.providers ? existing : { defaultModel: a.modelId, providers: {} };
+  cfg.providers = cfg.providers || {};
+  cfg.providers[a.providerName] = {
+    baseUrl: a.baseUrl, apiKey: a.apiKey, api: a.api,
+    models: [{ id: a.modelId, name: a.modelName || a.modelId, contextWindow: a.contextWindow, maxTokens: a.maxTokens }],
+  };
+  cfg.defaultModel = a.modelId;
+  return cfg;
+}
+
+// pipe-safe 逐行讀取：把 'line' 事件排入佇列，即使管線一次送進整批輸入也能依序消費
+// （readline/promises 的 question() 在非 TTY 管線下會丟失已緩衝的行）。
+function makeAsker() {
+  const rl = createInterface({ input: process.stdin });
+  const queue = []; const waiters = []; let closed = false;
+  rl.on('line', (l) => { const w = waiters.shift(); if (w) w(l); else queue.push(l); });
+  rl.on('close', () => { closed = true; while (waiters.length) waiters.shift()(null); });
+  const nextLine = () => new Promise((res) => { if (queue.length) res(queue.shift()); else if (closed) res(null); else waiters.push(res); });
+  return {
+    close: () => rl.close(),
+    ask: async (q, def) => {
+      process.stdout.write(gray(q + (def ? ` [${def}]` : '') + ' '));
+      const line = await nextLine();
+      return ((line == null ? '' : line).trim()) || def || '';
+    },
+  };
+}
+
+export async function runInit(argv = []) {
+  const force = argv.includes('--force');
+  const path = PATH();
+  const io = makeAsker();
+  const rl = { close: io.close };
+  const ask = io.ask;
+
+  try {
+    console.log('\n' + bold('🚀 xitto-kernel 首次設定') + gray('  —— 建立 LLM provider 設定'));
+    console.log(gray(`設定檔：${path}\n`));
+
+    // 既有檔保護
+    if (existsSync(path) && !force) {
+      console.log(yellow(`已存在設定檔。`) + gray(' 用 `xitto-kernel init --force` 覆寫，或直接編輯該檔。'));
+      let cfg; try { cfg = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔忽略 */ }
+      if (cfg) {
+        const names = Object.keys(cfg.providers || {});
+        console.log(gray(`  目前 provider：${names.join(', ') || '(無)'}　預設 model：${cfg.defaultModel || '(未設)'}`));
+      }
+      rl.close();
+      return;
+    }
+
+    // 1) 選 provider
+    const keys = Object.keys(PRESETS);
+    console.log(bold('1) 選 LLM provider：'));
+    keys.forEach((k, i) => console.log(`   ${cyan(String(i + 1))}. ${PRESETS[k].label}`));
+    const pick = await ask('輸入編號', '1');
+    const presetKey = keys[(parseInt(pick, 10) || 1) - 1] || 'minimax';
+    const preset = PRESETS[presetKey];
+    console.log(green(`   → ${preset.label}\n`));
+
+    // 2) 連線 / model
+    console.log(bold('2) 連線與 model：'));
+    const providerName = await ask('provider 名稱（providers.json 的鍵）', presetKey);
+    const baseUrl = await ask('baseUrl', preset.baseUrl);
+    const api = await ask('api 型別（anthropic-messages | openai-completions）', preset.api);
+    const modelId = await ask('model id', preset.model.id);
+    const modelName = await ask('model 顯示名', preset.model.name || modelId);
+    const contextWindow = parseInt(await ask('contextWindow', String(preset.model.contextWindow)), 10) || preset.model.contextWindow;
+    const maxTokens = parseInt(await ask('maxTokens', String(preset.model.maxTokens)), 10) || preset.model.maxTokens;
+    if (!modelId) { console.log(red('\nmodel id 不可空，已取消。')); rl.close(); return; }
+
+    // 3) API key：環境變數（建議）或內嵌
+    console.log('\n' + bold('3) API key：'));
+    console.log(gray('   a) 用環境變數參照（建議，金鑰不落地在設定檔）'));
+    console.log(gray('   b) 現在貼上金鑰（直接存進設定檔，檔案在你家目錄）'));
+    const mode = (await ask('選 a 或 b', 'a')).toLowerCase();
+    let apiKey; let envHint = '';
+    if (mode === 'b') {
+      const k = await ask('貼上 API key', '');
+      apiKey = k;
+      if (!k) console.log(yellow('   （未填，稍後請手動補上 apiKey）'));
+    } else {
+      const envName = await ask('環境變數名', preset.env);
+      apiKey = '${' + envName + '}';
+      envHint = envName;
+    }
+
+    // 組設定（保留既有 providers，--force 時合併）
+    let existing; if (existsSync(path)) { try { existing = JSON.parse(readFileSync(path, 'utf8')); } catch { /* 壞檔重建 */ } }
+    const cfg = buildConfig({ providerName, baseUrl, api, modelId, modelName, contextWindow, maxTokens, apiKey }, existing);
+
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+
+    console.log('\n' + green('✓ 已寫入 ') + path);
+    if (envHint) {
+      console.log('\n' + bold('下一步：設定環境變數（金鑰）'));
+      console.log(gray(`  export ${envHint}="你的金鑰"   # 加進 ~/.zshrc 永久生效`));
+    }
+    console.log('\n' + bold('啟動：'));
+    console.log(green('  xitto-kernel') + gray('               # coding pack，互動對話'));
+    console.log(green('  xitto-kernel --tui') + gray('         # 完整 Ink TUI（真實終端）'));
+    console.log(green('  xitto-kernel --pack general') + gray(' # 通用 agent'));
+    console.log('');
+  } finally {
+    rl.close();
+  }
+}

package/src/app/main.js

@@ -3,13 +3,17 @@
 import { join } from 'node:path';
 import { loadModel } from './providers.js';
 import { runCli } from './cli.js';
+import { runTui } from './tui-run.js';
 import { newAgent } from './scaffold.js';
+import { runInit } from './init.js';
 import { createKernel } from '../kernel/index.js';
 import { loadMcpTools } from '../kernel/mcp.js';
 import { createCodingPack } from '../packs/coding/index.js';
 import { createDataQueryPack } from '../packs/data-query/index.js';
 import { createNotesPack } from '../packs/notes/index.js';
 import { createGeneralPack } from '../packs/general/index.js';
+import { createDeepResearchPack } from '../packs/deep-research/index.js';
+import { createDevopsPack } from '../packs/devops/index.js';
 
 const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
 const green = e(32); const gray = e(90); const red = e(31); const cyan = e(36); const yellow = e(33);
@@ -19,9 +23,14 @@ const PACKS = {
   'data-query': createDataQueryPack,
   notes: createNotesPack,
   general: createGeneralPack,
+  'deep-research': createDeepResearchPack,
+  devops: createDevopsPack,
 };
 
 export async function main(argv = process.argv.slice(2)) {
+  // 子指令：init —— 首次設定導引，產生 providers.json
+  if (argv[0] === 'init') { await runInit(argv.slice(1)); return; }
+
   // 子指令：new-agent <name> —— 產出獨立 agent 專案（不碰 kernel）
   if (argv[0] === 'new-agent') {
     const name = argv.find((a, i) => i >= 1 && !a.startsWith('--'));
@@ -45,7 +54,26 @@ export async function main(argv = process.argv.slice(2)) {
 
   let model, getApiKey;
   try { ({ model, getApiKey } = loadModel(opts.model)); }
-  catch (err) { console.error('\x1b[31m' + err.message + '\x1b[0m'); process.exit(1); }
+  catch (err) {
+    // 沒設定 + 真實終端：直接帶進設定導引，完成後續跑；非 TTY 才只給提示
+    if (err.noConfig && process.stdin.isTTY) {
+      console.log(cyan('首次使用，沒找到 providers.json —— 進入設定導引。') + gray('（按 Ctrl+C 取消）'));
+      await runInit([]);
+      try { ({ model, getApiKey } = loadModel(opts.model)); }
+      catch (err2) {
+        console.error(red(err2.message));
+        console.error(gray(err2.noConfig ? '（未完成設定，已取消）' : '（設定好像缺東西，可編輯該檔或重跑 `xitto-kernel init`）'));
+        process.exit(1);
+      }
+    } else {
+      console.error(red(err.message));
+      if (err.noConfig) {
+        console.error('\n' + cyan('首次使用？') + ' 跑一次設定導引：');
+        console.error(green('  xitto-kernel init') + gray('   # 選 provider、填 model、設定 API key'));
+      }
+      process.exit(1);
+    }
+  }
 
   // MCP：啟動時連 .xitto-kernel/<pack>/mcp.json 的 server，工具以 extraTools 注入
   const cwd = process.cwd();
@@ -73,6 +101,12 @@ export async function main(argv = process.argv.slice(2)) {
     process.exit(res.done ? 0 : 1);
   }
 
+  if (opts.tui && process.stdin.isTTY) {
+    runTui({ pack: make({ cwd }), model, getApiKey, sandbox: opts.sandbox, resume: opts.resume });
+    return;
+  }
+  if (opts.tui) console.error(gray('（--tui 需要真實終端，退回一般 CLI）'));
+
   runCli({
     pack: make({ cwd }), model, getApiKey,
     sandbox: opts.sandbox, resume: opts.resume, auto: opts.yes,
@@ -89,6 +123,7 @@ function parse(argv) {
     else if (a === '--model') o.model = argv[++i];
     else if (a === '--sandbox') o.sandbox = true;
     else if (a === '--yes' || a === '-y') o.yes = true;
+    else if (a === '--tui') o.tui = true;
     else if (a === '--goal') o.goal = argv[++i];
     else if (a === '--resume') { const nxt = argv[i + 1]; if (nxt && !nxt.startsWith('--')) { o.resume = nxt; i++; } else o.resume = true; }
   }
@@ -100,17 +135,21 @@ function printHelp() {
     'xitto-kernel — 領域無關 agent 底座',
     '',
     '用法:',
+    '  xitto-kernel init                                        首次設定導引（產生 providers.json）',
     '  xitto-kernel [--pack <name>] [--model <id>] [--sandbox] [--resume [id]] [--yes]   互動跑內建 pack',
     '  xitto-kernel --pack general --goal "..." [--yes]         目標驅動自主循環（headless）',
     '  xitto-kernel new-agent <name>                            產出依賴 kernel 的獨立 agent 專案',
     '',
-    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes | general；預設 coding）',
+    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes | general | deep-research | devops；預設 coding）',
     '  --goal "..."    給目標，agent 自主反覆做到完成（建議搭配 --pack general）',
     '  --model <id>    指定 model（預設用 providers.json 的 defaultModel）',
     '  --sandbox       啟動即開啟沙箱（macOS=Seatbelt 真隔離）',
+    '  --tui           完整 Ink TUI（持久狀態列、串流轉錄、Esc 中斷；需真實終端）',
+    '  --resume [id]   接續上次 session（不給 id 接最近一次）',
+    '  --yes, -y       自動核准 mutating 工具（headless / 自主循環常用）',
     '  --help          顯示說明',
     '',
-    '需要 ~/.xitto-code/providers.json（與 xitto-code 共用）。',
+    '首次使用先跑 `xitto-kernel init` 建立 ~/.xitto-code/providers.json（已是 xitto-code 使用者可直接共用）。',
     'new-agent 產出的是獨立專案，import xitto-kernel 而非修改它——升級不固化。',
   ].join('\n'));
 }

package/src/app/md-render.js

@@ -0,0 +1,95 @@
+// Markdown → 終端 ANSI 渲染（對標 Claude Code 的回覆排版）
+// 用 marked 解析、marked-terminal 轉 ANSI（標題、粗體、列表、表格、程式碼區塊語法高亮）。
+// Claude Code 的做法：每來一個 token 就把「目前累積的整段 markdown」重新解析重繪，
+// 半截的 **粗體 / 未閉合的 ``` 會在下一幀補齊後自動修正。本檔提供純函式 md()，
+// 重繪由 Ink 的 re-render 負責（見 tui.js）。
+import { Marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+import { highlight as hl } from 'cli-highlight';
+
+// 終端寬度（隨視窗；最小 40 避免表格擠壞）
+function termWidth() {
+  const w = process.stdout?.columns || 80;
+  return Math.max(40, Math.min(w, 120));
+}
+
+// ANSI 樣式小工具（marked-terminal 的樣式選項接受 (str)=>str 函式）
+const a = (open, close) => (s) => `\x1b[${open}m${s}\x1b[${close}m`;
+const bold = a(1, 22);
+const cyan = a(36, 39);
+const yellow = a(33, 39);
+const gray = a(90, 39);
+
+// 程式碼區塊本體：語法高亮 + 左側豎線邊框（+ 可選語言標籤）。不含前後空行，方便外部逐塊拼接。
+// withHeader=false 用於「同一個 code block 的延續塊」（串流逐行提交時避免重複 ┌─ lang 標頭）。
+export function codeChunk(text, lang, withHeader = true) {
+  let body;
+  try { body = hl(text, { language: lang || 'plaintext', ignoreIllegals: true }); }
+  catch { body = text; }
+  const bar = gray('│') + ' ';
+  const label = (withHeader && lang) ? gray(`┌─ ${lang}`) + '\n' : '';
+  return label + body.replace(/\n$/, '').split('\n').map((l) => bar + l).join('\n');
+}
+
+// 程式碼區塊（marked renderer 用）：前後補空行與內文隔開
+function codeBlock(text, lang) {
+  return '\n' + codeChunk(text, lang, true) + '\n';
+}
+
+// 依寬度快取 Marked 實例：終端 resize 後寬度改變 → 換一個實例，markdown 自動以新寬度重排。
+// 上限保護：resize 反覆拖動會堆積不同寬度的實例，超過上限即淘汰最舊的(LRU 近似)。
+const cache = new Map();
+const MAX_CACHE = 32;
+function renderer(width) {
+  let m = cache.get(width);
+  if (!m) {
+    m = new Marked();
+    m.use(
+      markedTerminal({
+        width,
+        reflowText: true,
+        tab: 2,
+        showSectionPrefix: false,          // 不顯示標題的 # 記號（對標 Claude Code）
+        firstHeading: (s) => bold(cyan(s)), // 一級標題：粗體青
+        heading: (s) => bold(s),            // 其餘標題：粗體
+        strong: (s) => bold(s),
+        codespan: (s) => yellow(s),
+        blockquote: (s) => gray(s),
+        listitem: (s) => s,
+      }),
+    );
+    // 覆寫 code 渲染：加左側邊框（marked-terminal 內建無邊框）
+    m.use({
+      renderer: {
+        code(token, infostring) {
+          const text = typeof token === 'object' ? token.text : token;
+          const lang = (typeof token === 'object' ? token.lang : infostring) || '';
+          return codeBlock(text, lang);
+        },
+      },
+    });
+    if (cache.size >= MAX_CACHE) cache.delete(cache.keys().next().value); // 淘汰最舊
+    cache.set(width, m);
+  }
+  return m;
+}
+
+// 用 marked 的 block lexer 把 markdown 切成頂層區塊 token（含 .raw，串接即原文）。
+// 串流增量提交用：提交「除最後一塊外」的完整區塊，最後一塊（可能還沒打完）留在動態區。
+const lexMarked = new Marked();
+export function lexBlocks(text) {
+  try { return lexMarked.lexer(text); }
+  catch { return [{ type: 'paragraph', raw: text }]; }
+}
+
+// 把 markdown 字串渲染成帶 ANSI 的終端字串。容錯：解析失敗就回原文。
+export function md(text) {
+  if (!text) return '';
+  try {
+    const out = renderer(termWidth()).parse(text);
+    // 無序列表符號 * → •（marked-terminal 的 BULLET_POINT 寫死為 '* '）
+    return (typeof out === 'string' ? out : String(out)).replace(/\n+$/, '').replace(/^(\s*)\* /gm, '$1• ');
+  } catch {
+    return text;
+  }
+}

package/src/app/providers.js

@@ -7,7 +7,7 @@ import { join } from 'node:path';
 const DEFAULT_PATH = () => process.env.XITTO_CODE_CONFIG || join(homedir(), '.xitto-code', 'providers.json');
 
 export function loadProvidersConfig(path = DEFAULT_PATH()) {
-  if (!existsSync(path)) throw new Error(`找不到 providers.json：${path}\n（可複用 xitto-code 的 ~/.xitto-code/providers.json）`);
+  if (!existsSync(path)) { const err = new Error(`找不到 providers.json：${path}`); err.noConfig = true; throw err; }
   return { ...JSON.parse(readFileSync(path, 'utf8')), path };
 }