xitto-kernel 0.1.0

package/docs/06-authoring-a-pack.md

@@ -0,0 +1,86 @@
+# 06 · 怎麼用底座做一個新領域 agent
+
+一句話：**寫一個 DomainPack（最少 3 欄）→ 註冊到 CLI → 跑**。kernel 與其他 pack 零改動。
+
+## 最小可跑（3 個必填欄位）
+
+```js
+// src/packs/hello/index.js
+export function createHelloPack() {
+  return {
+    name: 'hello',
+    systemPrompt: '你是友善的助手，用繁體中文回答。',
+    tools: () => [{
+      name: 'now', label: '時間', description: '回傳目前時間', readOnly: true,
+      parameters: { type: 'object', properties: {} },
+      execute: async () => ({ content: [{ type: 'text', text: new Date().toISOString() }] }),
+    }],
+  };
+}
+```
+
+這樣就是一個能跑的 agent 了。`createKernel(createHelloPack(), { model, getApiKey })` → `runTurn(...)`。
+
+## 工具長什麼樣（kernel 的唯一要求）
+
+kernel 不在乎工具做什麼，只要這個形狀（**metadata 決定安全行為**）：
+
+```js
+{
+  name: 'do_thing',
+  label: '顯示名',
+  description: '給模型看的用途說明（寫清楚，模型靠它決定何時呼叫）',
+  parameters: { /* JSON Schema */ },
+  execute: async (id, params, signal, onUpdate, services) => ({ content: [{ type: 'text', text: '...' }] }),
+
+  // ── metadata：決定 kernel 怎麼對待它 ──
+  readOnly: true,      // 唯讀 → 守衛鏈自動放行、不問權限
+  mutating: true,      // 會改動 → 計劃模式擋它、自動算進 mutatingTools
+  sandboxable: true,   // 走 shell → 沙箱開時自動包進 Seatbelt（只對有 params.command 的工具有意義）
+}
+```
+
+## 六個選填插槽（要更像「專業 agent」時才填）
+
+| 插槽 | 用途 | 範例 |
+|------|------|------|
+| `contextFiles` | 啟動載入的領域規範檔 | `['NOTES.md']` |
+| `mutatingTools` | 顯式指定哪些算改動（不給就從 `tool.mutating` 推） | `['add_note']` |
+| `verify` | 每輪收尾自我驗收 | 連結檢查 / 測試 |
+| `preToolPolicy` | 工具前領域守衛（守衛鏈第 3 格） | 「add 前必先 search」 |
+| `permissionPolicy` | 沙箱/deny 預設 | `{ deny: ['bash:DROP'] }` |
+| `memoryGuide` | 何時主動存記憶的提示 | 領域特化提示 |
+
+> `preToolPolicy` 是領域「規矩」的所在：編碼是 read-before-edit、資料是 schema-before-query、
+> 筆記是 search-before-add ——**同一個插槽，不同領域填不同規矩**。
+
+## 三步驟：從零到能用
+
+### 1) 寫 pack
+`src/packs/<你的領域>/index.js`，export 一個 `create<Name>Pack({ cwd })`。
+
+### 2) 註冊到 CLI
+`src/app/main.js` 的 `PACKS` 加一行：
+```js
+import { createNotesPack } from '../packs/notes/index.js';
+const PACKS = { coding: createCodingPack, 'data-query': createDataQueryPack, notes: createNotesPack };
+```
+
+### 3) 跑
+```bash
+npm start -- --pack notes              # 互動 CLI
+npm start -- --pack notes --sandbox    # 要沙箱就加 --sandbox
+```
+
+## 該把什麼放進工具 vs prompt？
+
+- **工具** = agent 能對世界做的動作（查 DB、發 API、寫檔、跑命令）。要副作用或要拿外部資料 → 工具。
+- **systemPrompt** = 行為準則、口吻、流程規矩、何時用哪個工具。純推理/格式 → prompt。
+- **preToolPolicy** = 硬性前置條件（程式擋，不靠模型自律）。「沒做 X 不准做 Y」→ 守衛。
+
+## 不用碰的東西（kernel 免費給你）
+
+接上任何 pack，自動獲得：多步工具循環、串流、權限/沙箱（含 Seatbelt）、危險命令偵測、
+mutatingTools 推導、計劃模式、Ctrl+C 中斷、多輪歷史、CLI。**領域作者只寫「會什麼、守什麼」。**
+
+完整範例見 `src/packs/notes/`（知識庫 agent），對照 `coding` / `data-query`。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "xitto-kernel",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
+  "keywords": [
+    "agent",
+    "llm",
+    "ai-agent",
+    "agent-framework",
+    "domain-pack",
+    "sandbox",
+    "seatbelt",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "ishoplus",
+  "homepage": "https://github.com/ishoplus/xitto-kernel#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ishoplus/xitto-kernel.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ishoplus/xitto-kernel/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "xitto-kernel": "bin/xitto-kernel.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "demo": "node examples/demo.js",
+    "start": "node bin/xitto-kernel.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./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"
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "^0.70.6",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/src/app/cli.js

@@ -0,0 +1,243 @@
+// App 層：互動式終端 CLI，消費 kernel.runTurn 的事件流。
+// 這是「kernel + 薄 app」的 app 半部——TUI 不在 kernel 內；更豐富的 Ink 前端可作為另一個
+// app 消費同一組 kernel 事件（證明 kernel/app 分離）。
+import readline from 'node:readline';
+import { createKernel } from '../kernel/index.js';
+import { seatbeltAvailable } from '../kernel/security/sandbox.js';
+import { createStreamRenderer } from './markdown.js';
+
+const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
+const c = { gray: e(90), green: e(32), yellow: e(33), red: e(31), cyan: e(36), bold: e(1), blue: e(34) };
+
+const summarize = (args) => {
+  const s = JSON.stringify(args ?? {});
+  return s.length > 60 ? s.slice(0, 57) + '…' : s;
+};
+const preview = (result) => {
+  const t = (result?.content || []).map((x) => x.text || '').join(' ').replace(/\s+/g, ' ').trim();
+  return t.length > 70 ? t.slice(0, 67) + '…' : t;
+};
+
+/**
+ * 啟動互動 CLI。
+ * @param {Object} o
+ * @param {import('../types.js').DomainPack} o.pack
+ * @param {object} o.model
+ * @param {() => string} o.getApiKey
+ * @param {boolean} [o.sandbox]   初始沙箱狀態（預設關）
+ */
+export function runCli({ pack, model, getApiKey, sandbox = false, resume = null, auto = false, extraTools = [], onExit = null }) {
+  let sandboxOn = !!sandbox;
+  let autoApprove = !!auto;
+  let planMode = false;
+  const kernel = createKernel(pack, {
+    model, getApiKey, extraTools,
+    sandbox: { enabled: sandboxOn },        // 提供策略（blockNetwork/allowWritePrefixes）
+    getSandbox: () => sandboxOn,            // on/off 由 CLI 即時切換
+    getPlanMode: () => planMode,            // 計劃模式：守衛擋 mutating 工具
+    confirm: askConfirm,                    // 互動權限確認（mutating/危險工具執行前）
+  });
+
+  let history = [];
+  let currentAgent = null;
+  let streaming = false;
+
+  // 互動權限確認：守衛鏈第 5 格對 mutating/危險工具呼叫此函數。autoApprove → 一律放行。
+  // 回 'yes'（允許一次）/ 'always'（此工具全部）/ 'no'（拒絕）。
+  async function askConfirm(name, args, danger) {
+    if (autoApprove && !danger) return 'yes';   // 自動模式仍對危險命令把關
+    endStream();
+    return new Promise((res) => {
+      const warn = danger ? c.red(`  ⛔ 危險：${danger}\n`) : '';
+      out(warn + c.yellow('  需要許可 ') + c.bold(name) + c.gray('(' + summarize(args) + ')') + '\n');
+      const hint = danger ? '[y]允許一次  [n]拒絕' : '[y]允許  [a]此工具全部  [n]拒絕';
+      try {
+        rl.question(c.yellow(`    ${hint} › `), (ans) => {
+          const a = (ans || '').trim().toLowerCase();
+          if (danger) return res(a === 'y' || a === 'yes' ? 'yes' : 'no');
+          res(a === 'y' || a === 'yes' ? 'yes' : a === 'a' ? 'always' : 'no');
+        });
+      } catch { res('no'); }
+    });
+  }
+
+  // session：續接（--resume [id]）或開新；每輪結束自動存檔
+  let sessionId = kernel.session.newId();
+  let resumedNote = '';
+  if (resume) {
+    const data = resume === true ? (kernel.session.latest() && kernel.session.load(kernel.session.latest().id)) : kernel.session.load(resume);
+    if (data?.messages?.length) { history = data.messages; sessionId = data.id; resumedNote = `（續接 ${data.id}，${data.messages.length} 則）`; }
+    else resumedNote = resume === true ? '（找不到可續的對話，開新）' : `（找不到 session "${resume}"，開新）`;
+  }
+  const persist = () => { try { kernel.session.save(sessionId, history); } catch { /* 略 */ } };
+
+  const out = (s) => process.stdout.write(s);
+  const md = createStreamRenderer(out);             // 串流 markdown 渲染（粗體/標題/code/inline code）
+  const endStream = () => { if (md.active()) md.flush(); streaming = false; };
+
+  // edit/write 的彩色 diff 預覽（紅 - 舊 / 綠 + 新）
+  const diffPreview = (name, args) => {
+    if (name === 'edit' && args?.oldText != null) {
+      for (const l of String(args.oldText).split('\n').slice(0, 8)) out(c.red('  - ' + l) + '\n');
+      for (const l of String(args.newText ?? '').split('\n').slice(0, 8)) out(c.green('  + ' + l) + '\n');
+    } else if (name === 'write' && args?.content != null) {
+      const lines = String(args.content).split('\n');
+      for (const l of lines.slice(0, 8)) out(c.green('  + ' + l) + '\n');
+      if (lines.length > 8) out(c.gray(`  … 共 ${lines.length} 行`) + '\n');
+    }
+  };
+
+  const onEvent = (ev) => {
+    switch (ev.type) {
+      case 'message_update': {
+        const a = ev.assistantMessageEvent;
+        if (a?.type === 'text_delta' && a.delta) { md.push(a.delta); streaming = true; }
+        break;
+      }
+      case 'tool_execution_start':
+        endStream();
+        out(c.yellow('⚙ ' + ev.toolName) + c.gray('(' + summarize(ev.args) + ')\n'));
+        diffPreview(ev.toolName, ev.args);
+        break;
+      case 'tool_execution_end':
+        out((ev.isError ? c.red('  ⎿ ✗') : c.gray('  ⎿ ✓')) + c.gray(' ' + preview(ev.result)) + '\n');
+        break;
+      case 'verify_start':
+        endStream();
+        out(c.gray('  🔎 自動驗收…\n'));
+        break;
+      case 'verify_end':
+        out(ev.ok ? c.gray('  ✓ 驗收通過\n') : c.yellow('  ✗ 驗收失敗，請 agent 修正…\n'));
+        break;
+      case 'hook_fail':
+        out(c.yellow(`  ✗ hook 失敗 ${ev.command}，回灌讓 agent 修正…\n`));
+        break;
+      case 'compact':
+        endStream();
+        out(c.gray(`  ⊙ 已壓縮上下文：${ev.tokensBefore}→${ev.tokensAfter} tokens（摘要 ${ev.summarized} 則，保留 ${ev.kept} 則）\n`));
+        break;
+    }
+  };
+
+  // 斜線指令；回 true 表示已處理（不送 LLM）
+  const handleSlash = (input) => {
+    const [cmd, arg] = input.trim().split(/\s+/);
+    switch (cmd) {
+      case '/exit': case '/quit': cleanup(); process.exit(0); return true;
+      case '/help':
+        out(c.gray([
+          '  /help            說明',
+          '  /sandbox [on|off] 切換沙箱（macOS=Seatbelt 真隔離）',
+          '  /auto [on|off]    自動核准 mutating 工具（危險命令仍把關）',
+          '  /plan [on|off]    計劃模式（只規劃、擋下實際改動）',
+          '  /undo            撤銷上一次檔案改動（write/edit）',
+          '  /tools           列出此 pack 的工具',
+          '  /memory          顯示跨 session 記憶',
+          '  /sessions        列出已保存的對話',
+          '  /resume [id]     續接對話（不給 id=最近一次）',
+          '  /clear           清除歷史（開新 session）',
+          '  /exit            離開',
+        ].join('\n') + '\n'));
+        return true;
+      case '/memory': {
+        const mems = kernel.memory.list();
+        out(mems.length ? c.gray(mems.map((m) => '  • ' + m).join('\n') + '\n') : c.gray('（尚無記憶）\n'));
+        return true;
+      }
+      case '/sessions': {
+        const ss = kernel.session.list();
+        out(ss.length
+          ? c.gray(ss.map((s) => `  ${s.id}  [${s.count} 則${s.model ? ' ' + s.model : ''}]`).join('\n') + '\n')
+          : c.gray('（尚無保存的對話）\n'));
+        return true;
+      }
+      case '/resume': {
+        const target = arg || (kernel.session.latest()?.id);
+        const data = target ? kernel.session.load(target) : null;
+        if (data?.messages?.length) {
+          history = data.messages; sessionId = data.id;
+          out(c.gray(`（已續接 ${data.id}，${data.messages.length} 則）\n`));
+        } else out(c.yellow(`找不到可續接的 session${arg ? ` "${arg}"` : ''}\n`));
+        return true;
+      }
+      case '/sandbox': {
+        sandboxOn = arg ? arg === 'on' : !sandboxOn;
+        const real = seatbeltAvailable();
+        out(sandboxOn
+          ? c.yellow(`🔒 沙箱開${real ? '（macOS Seatbelt OS 級隔離）' : '（靜態策略；此平台無 Seatbelt）'}\n`)
+          : c.gray('沙箱關\n'));
+        return true;
+      }
+      case '/auto':
+        autoApprove = arg ? arg === 'on' : !autoApprove;
+        out(autoApprove ? c.yellow('⚡ 自動核准開（mutating 工具不再逐一確認；危險命令仍把關）\n') : c.gray('自動核准關（mutating 工具會逐一確認）\n'));
+        return true;
+      case '/plan':
+        planMode = arg ? arg === 'on' : !planMode;
+        out(planMode ? c.cyan('📋 計劃模式開（只規劃、擋下 write/edit/bash）\n') : c.gray('計劃模式關\n'));
+        return true;
+      case '/undo': {
+        const r = kernel.undo();
+        out(r.undone ? c.gray(`↩ 已撤銷 ${r.path}${r.created ? '（刪除新建檔）' : ''}\n`) : c.yellow(`${r.reason}\n`));
+        return true;
+      }
+      case '/tools':
+        out(c.gray(kernel.registry.all().map((t) =>
+          `  ${t.name}${t.readOnly ? c.gray(' [唯讀]') : ''}${t.mutating ? c.yellow(' [mutating]') : ''}${t.sandboxable ? c.cyan(' [sandboxable]') : ''}`,
+        ).join('\n') + '\n'));
+        return true;
+      case '/clear': history = []; sessionId = kernel.session.newId(); out(c.gray('（已清除歷史，開新 session）\n')); return true;
+      default:
+        if (cmd.startsWith('/')) { out(c.red(`未知指令 ${cmd}（/help）\n`)); return true; }
+        return false;
+    }
+  };
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, prompt: c.blue('› ') });
+  let closed = false;
+  const cleanup = () => { try { rl.close(); } catch { /* 略 */ } try { onExit?.(); } catch { /* 略 */ } };
+  const finish = () => { cleanup(); process.exit(0); };
+  rl.on('close', () => { closed = true; }); // 管線輸入結束（非 TTY）→ 收尾
+
+  // Ctrl+C：執行中→中斷該輪；閒置→離開
+  process.on('SIGINT', () => {
+    if (currentAgent) { 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');
+  if (resumedNote) out(c.gray('  ' + resumedNote) + '\n');
+  out('\n');
+
+  const loop = () => {
+    if (closed) return finish();
+    let q;
+    try { q = rl.question.bind(rl); } catch { return finish(); }
+    q(c.blue('› '), async (raw) => {
+      const input = (raw || '').trim();
+      if (!input) return loop();
+      if (handleSlash(input)) return loop();
+      try {
+        const text = planMode
+          ? `[計劃模式：只制定計劃，列出你打算做的步驟與會改動的檔案，不要實際寫檔或執行命令]\n\n${input}`
+          : input;
+        const r = await kernel.runTurn(text, {
+          history, onEvent, onAgent: (a) => { currentAgent = a; },
+        });
+        endStream();
+        history = r.messages;
+        persist();                 // 每輪結束自動存檔（可 /resume 續接）
+      } catch (err) {
+        endStream();
+        out(c.red('錯誤：' + err.message) + '\n');
+      } finally {
+        currentAgent = null;
+      }
+      out('\n');
+      loop();
+    });
+  };
+  loop();
+}

package/src/app/index.js

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

package/src/app/main.js

@@ -0,0 +1,87 @@
+// App 進入點：解析參數 → 載入 model（providers.json）→ 選 pack → 啟動 CLI。
+// 子指令：new-agent <name> → 產出依賴 kernel 的獨立 agent 專案。
+import { join } from 'node:path';
+import { loadModel } from './providers.js';
+import { runCli } from './cli.js';
+import { newAgent } from './scaffold.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';
+
+const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
+const green = e(32); const gray = e(90); const red = e(31);
+
+const PACKS = {
+  coding: createCodingPack,
+  'data-query': createDataQueryPack,
+  notes: createNotesPack,
+};
+
+export async function main(argv = process.argv.slice(2)) {
+  // 子指令：new-agent <name> —— 產出獨立 agent 專案（不碰 kernel）
+  if (argv[0] === 'new-agent') {
+    const name = argv[1];
+    try {
+      const { target, files } = newAgent(name);
+      console.log(green(`✓ 已建立獨立 agent 專案：${target}`));
+      console.log(gray(`  ${files.join('  ')}`));
+      console.log('\n下一步：');
+      console.log(gray(`  cd ${name} && npm install && npm start`));
+      console.log(gray('  （改 pack.js 換成你的領域；npm update xitto-kernel 升級底座，不固化）'));
+    } catch (err) { console.error(red(err.message)); process.exit(1); }
+    return;
+  }
+
+  const opts = parse(argv);
+  if (opts.help) return printHelp();
+
+  const make = PACKS[opts.pack];
+  if (!make) { console.error(`未知 pack「${opts.pack}」。可用：${Object.keys(PACKS).join(', ')}`); process.exit(1); }
+
+  let model, getApiKey;
+  try { ({ model, getApiKey } = loadModel(opts.model)); }
+  catch (err) { console.error('\x1b[31m' + err.message + '\x1b[0m'); process.exit(1); }
+
+  // MCP：啟動時連 .xitto-kernel/<pack>/mcp.json 的 server，工具以 extraTools 注入
+  const cwd = process.cwd();
+  const mcp = await loadMcpTools(join(cwd, '.xitto-kernel', opts.pack, 'mcp.json'), (m) => console.log(gray(`  [MCP] ${m}`)));
+
+  runCli({
+    pack: make({ cwd }), model, getApiKey,
+    sandbox: opts.sandbox, resume: opts.resume, auto: opts.yes,
+    extraTools: mcp.tools, onExit: mcp.close,
+  });
+}
+
+function parse(argv) {
+  const o = { pack: 'coding', model: undefined, sandbox: false, help: false, resume: null, yes: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') o.help = true;
+    else if (a === '--pack') o.pack = argv[++i];
+    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 === '--resume') { const nxt = argv[i + 1]; if (nxt && !nxt.startsWith('--')) { o.resume = nxt; i++; } else o.resume = true; }
+  }
+  return o;
+}
+
+function printHelp() {
+  console.log([
+    'xitto-kernel — 領域無關 agent 底座',
+    '',
+    '用法:',
+    '  xitto-kernel [--pack <name>] [--model <id>] [--sandbox] [--resume [id]] [--yes]   互動跑內建 pack',
+    '  xitto-kernel new-agent <name>                            產出依賴 kernel 的獨立 agent 專案',
+    '',
+    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes；預設 coding）',
+    '  --model <id>    指定 model（預設用 providers.json 的 defaultModel）',
+    '  --sandbox       啟動即開啟沙箱（macOS=Seatbelt 真隔離）',
+    '  --help          顯示說明',
+    '',
+    '需要 ~/.xitto-code/providers.json（與 xitto-code 共用）。',
+    'new-agent 產出的是獨立專案，import xitto-kernel 而非修改它——升級不固化。',
+  ].join('\n'));
+}

package/src/app/markdown.js

@@ -0,0 +1,36 @@
+// 輕量串流 markdown 渲染器（零依賴，逐行）。delta 進 buffer，遇換行就把整行套 ANSI 樣式輸出；
+// 末尾未完成的行在 flush 時輸出。支援：標題、code block(```)、inline code(`)、粗體(**)。
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', cyan: '\x1b[36m', green: '\x1b[32m' };
+
+const inline = (s) => s
+  .replace(/\*\*([^*]+)\*\*/g, (_, t) => C.bold + t + C.reset)
+  .replace(/`([^`]+)`/g, (_, t) => C.cyan + t + C.reset);
+
+/**
+ * @param {(s: string) => void} out
+ */
+export function createStreamRenderer(out) {
+  let buf = '';
+  let inCode = false;
+  let firstDone = false;
+
+  const prefix = () => { if (!firstDone) { firstDone = true; return C.green + '● ' + C.reset; } return ''; };
+
+  const renderLine = (line) => {
+    if (/^\s*```/.test(line)) { inCode = !inCode; out(prefix() + C.dim + line + C.reset + '\n'); return; }
+    if (inCode) { out(prefix() + C.cyan + line + C.reset + '\n'); return; }
+    const h = line.match(/^(#{1,6})\s+(.*)/);
+    if (h) { out(prefix() + C.bold + h[2] + C.reset + '\n'); return; }
+    out(prefix() + inline(line) + '\n');
+  };
+
+  return {
+    push: (delta) => {
+      buf += delta;
+      let nl;
+      while ((nl = buf.indexOf('\n')) >= 0) { renderLine(buf.slice(0, nl)); buf = buf.slice(nl + 1); }
+    },
+    flush: () => { if (buf) { renderLine(buf); buf = ''; } firstDone = false; inCode = false; },
+    active: () => firstDone || buf.length > 0,
+  };
+}

package/src/app/providers.js

@@ -0,0 +1,39 @@
+// App 層：從 providers.json 載入並組裝 model（沿用 xitto providers.json 格式）。
+// 這是「provider 設定」，屬 app；kernel 本身 provider 無關（只收 model + getApiKey）。
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+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）`);
+  return { ...JSON.parse(readFileSync(path, 'utf8')), path };
+}
+
+export function buildModel(cfg, modelId) {
+  const providers = cfg.providers || {};
+  const targetId = modelId || cfg.defaultModel;
+  for (const [provider, pcfg] of Object.entries(providers)) {
+    const m = (pcfg.models || []).find((x) => x.id === targetId);
+    if (!m) continue;
+    const model = {
+      id: m.id, name: m.name || m.id, provider,
+      api: pcfg.api || 'openai-completions', baseUrl: pcfg.baseUrl,
+      reasoning: m.reasoning || false, input: m.input || ['text'], output: m.output || ['text'],
+      cost: m.cost || { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: m.contextWindow || 32000, maxTokens: m.maxTokens || 4096,
+      cache: m.cache ?? pcfg.cache,
+    };
+    const apiKey = resolveEnv(pcfg.apiKey || '');
+    return { model, getApiKey: () => apiKey };
+  }
+  throw new Error(`providers.json 找不到 model「${targetId}」`);
+}
+
+// 一步到位：載入設定 + 組裝指定（或預設）model
+export function loadModel(modelId, path) {
+  return buildModel(loadProvidersConfig(path), modelId);
+}
+
+const resolveEnv = (v) => String(v).replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] || '');

package/src/app/scaffold.js

@@ -0,0 +1,40 @@
+// 腳手架：產出「依賴 xitto-kernel 的獨立 agent 專案」（不修改 kernel，故不固化）。
+// 從 templates/*.tmpl 讀樣板 → 代換 __NAME__ / __KERNEL_PATH__ → 寫到 <dir>/<name>/。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const KERNEL_ROOT = resolve(HERE, '..', '..'); // src/app/ → 套件根
+const TEMPLATES = join(HERE, 'templates');
+
+// [樣板檔, 產出檔名]
+const FILES = [
+  ['package.json.tmpl', 'package.json'],
+  ['index.js.tmpl', 'index.js'],
+  ['pack.js.tmpl', 'pack.js'],
+  ['README.md.tmpl', 'README.md'],
+  ['gitignore.tmpl', '.gitignore'],
+];
+
+/**
+ * 產生一個獨立 agent 專案。
+ * @param {string} name                    agent 名（字母/數字/連字號）
+ * @param {{ dir?: string, kernelPath?: string }} [opts]
+ *        dir：產出根目錄（預設 cwd）；kernelPath：寫進 package.json 的 file: 依賴路徑（預設此 kernel）
+ * @returns {{ target: string, files: string[] }}
+ */
+export function newAgent(name, { dir = process.cwd(), kernelPath = KERNEL_ROOT } = {}) {
+  if (!name || !/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
+    throw new Error(`agent 名稱不合法：「${name}」（只能用字母/數字/連字號，且不以連字號開頭）`);
+  }
+  const target = join(dir, name);
+  if (existsSync(target)) throw new Error(`目錄已存在：${target}`);
+
+  mkdirSync(target, { recursive: true });
+  const subst = (s) => s.replaceAll('__NAME__', name).replaceAll('__KERNEL_PATH__', kernelPath);
+  for (const [tmpl, outName] of FILES) {
+    writeFileSync(join(target, outName), subst(readFileSync(join(TEMPLATES, tmpl), 'utf8')));
+  }
+  return { target, files: FILES.map(([, o]) => o) };
+}

package/src/app/templates/README.md.tmpl

@@ -0,0 +1,32 @@
+# __NAME__
+
+用 **xitto-kernel** 底座做的 `__NAME__` 領域 agent。
+這份專案只擁有自己的 pack；runtime 由 xitto-kernel 提供，可獨立升級（不固化）。
+
+## 跑
+
+```bash
+npm install
+npm start                # 互動 CLI
+npm start -- --sandbox   # 開沙箱（macOS=Seatbelt 真隔離）
+```
+
+需要 `~/.xitto-code/providers.json`（與 xitto-code / xitto-kernel 共用）。
+
+## 改成你的領域
+
+編輯 `pack.js`：
+
+- `tools` — 加你的領域工具（`readOnly` / `mutating` / `sandboxable` 決定安全行為）
+- `systemPrompt` — 行為準則
+- `preToolPolicy` — 領域硬規矩（選填，例如「做 X 前必先 Y」）
+
+完整指南見 xitto-kernel 的 `docs/06-authoring-a-pack.md`。
+
+## 升級 kernel
+
+```bash
+npm update xitto-kernel
+```
+
+kernel 修 bug / 加功能都從這裡拿，**這份 agent 不會被固化**。

package/src/app/templates/gitignore.tmpl

@@ -0,0 +1,4 @@
+node_modules/
+*.log
+# kernel 執行期資料（記憶 / session）
+.xitto-kernel/

package/src/app/templates/index.js.tmpl

@@ -0,0 +1,7 @@
+// 啟動：xitto-kernel 當依賴。這份專案只擁有「你的 pack + 幾行啟動」。
+// kernel 升級（npm update xitto-kernel）不影響這裡——不會固化。
+import { runCli, loadModel } from 'xitto-kernel/app';
+import { createPack } from './pack.js';
+
+const { model, getApiKey } = loadModel(); // 讀 ~/.xitto-code/providers.json
+runCli({ pack: createPack({ cwd: process.cwd() }), model, getApiKey });