xitto-kernel 0.1.0

package/src/kernel/security/sandbox.js

@@ -0,0 +1,111 @@
+// bash 沙箱 — 兩層防護：
+//   (1) 靜態策略(sandboxViolation)：執行前正則分析命令字串，命中網路/提權/越界寫入即阻止。
+//       快速、跨平台、給清楚理由；但靠字串分析，可被混淆/間接執行繞過(如 base64 解碼後執行)。
+//   (2) OS 級真隔離(wrapWithSeatbelt)：macOS 用 sandbox-exec(Seatbelt) 把命令關進 OS 沙箱，
+//       即使命令再怎麼混淆，越界寫入與網路都被核心擋死。非 macOS 自動降級為僅(1)。
+// 兩層並存(defense in depth)：(1) 先擋明顯違規給好理由，(2) 兜住 (1) 漏網的混淆手法。
+import { existsSync, realpathSync } from 'node:fs';
+
+// 網路相關命令
+const NET_RE = /\b(curl|wget|nc|ncat|netcat|ssh|scp|sftp|telnet|rsync|ftp|svn)\b/;
+
+// 預設允許寫入的絕對路徑前綴(其餘絕對路徑寫入視為違規；相對路徑視為工作目錄內，放行)
+export const DEFAULT_SANDBOX = { enabled: false, blockNetwork: true, allowWritePrefixes: ['/tmp', '/private/tmp', '/var/folders'] };
+
+function underAny(p, prefixes) {
+  return prefixes.some((pre) => p === pre || p.startsWith(pre.endsWith('/') ? pre : pre + '/'));
+}
+
+// 回傳違規原因字串，無違規回 null。opts: { blockNetwork, allowWritePrefixes }
+export function sandboxViolation(command, opts = {}) {
+  const { blockNetwork = true, allowWritePrefixes = DEFAULT_SANDBOX.allowWritePrefixes } = opts;
+  const cmd = String(command || '');
+  if (!cmd.trim()) return null;
+  const lc = cmd.toLowerCase();
+
+  if (/(^|[\s;|&(])(sudo|doas)\s/.test(' ' + lc)) return '沙箱模式禁止 sudo/提權';
+  if (blockNetwork && NET_RE.test(lc)) return '沙箱模式禁止網路命令（curl/wget/ssh/nc 等）';
+
+  // 重定向寫入絕對路徑( > /etc/x、>> /usr/y )——不在允許前綴內即違規
+  for (const m of cmd.matchAll(/>>?\s*"?(\/[^\s"'<>;|&]*)/g)) {
+    if (!underAny(m[1], allowWritePrefixes)) return `沙箱模式禁止寫入工作目錄外：${m[1]}`;
+  }
+  // tee 寫入絕對路徑
+  const tee = cmd.match(/\btee\b\s+(?:-a\s+)?"?(\/[^\s"'<>;|&]*)/);
+  if (tee && !underAny(tee[1], allowWritePrefixes)) return `沙箱模式禁止 tee 寫入：${tee[1]}`;
+  // dd of= 絕對路徑
+  const dd = cmd.match(/\bof=\s*"?(\/[^\s"'<>;|&]*)/);
+  if (dd && !underAny(dd[1], allowWritePrefixes)) return `沙箱模式禁止 dd 寫入：${dd[1]}`;
+
+  return null;
+}
+
+// 把 settings.json 的 permissions.sandbox(boolean | 物件)正規化成 { enabled, blockNetwork, allowWritePrefixes }
+export function normalizeSandbox(raw) {
+  if (raw === true) return { ...DEFAULT_SANDBOX, enabled: true };
+  if (raw && typeof raw === 'object') {
+    return {
+      enabled: raw.enabled !== false,
+      blockNetwork: raw.blockNetwork !== false,
+      allowWritePrefixes: Array.isArray(raw.allowWritePrefixes) ? raw.allowWritePrefixes : DEFAULT_SANDBOX.allowWritePrefixes,
+    };
+  }
+  return { ...DEFAULT_SANDBOX };
+}
+
+// ── OS 級真隔離（macOS Seatbelt / sandbox-exec）────────────────────────────
+const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
+
+// 此平台是否能做 OS 級沙箱（目前僅 macOS 的 sandbox-exec）。非 macOS → false（降級為靜態策略）。
+export function seatbeltAvailable() {
+  return process.platform === 'darwin' && existsSync(SANDBOX_EXEC);
+}
+
+// Seatbelt profile 字串字面值轉義（profile 用 "..." 包路徑，需轉義 " 與 \）
+const sbStr = (p) => '"' + String(p).replace(/(["\\])/g, '\\$1') + '"';
+// bash 單引號轉義：把 ' 換成 '\''（讓任意內容能安全塞進 '...' ）
+const shq = (s) => `'` + String(s).replace(/'/g, `'\\''`) + `'`;
+
+// 把路徑展開成「原值 + 符號連結解析後的真實路徑」兩者（去重）。
+// macOS 上 /tmp→/private/tmp、/var→/private/var；Seatbelt 以核心解析後的真實路徑比對，
+// 故 profile 必須含真實路徑，否則 cwd 在 /var/folders 下的寫入會被誤擋。
+function canonicalPaths(paths) {
+  const out = new Set();
+  for (const p of paths) {
+    if (!p) continue;
+    out.add(p);
+    try { out.add(realpathSync(p)); } catch { /* 路徑不存在 → 只保留原值 */ }
+  }
+  return [...out];
+}
+
+// 產生 Seatbelt profile：預設允許一切，再「減去」網路與工作目錄外的寫入。
+// 讀取/執行不限制（建置常需讀系統庫）；寫入只放行 cwd + allowWritePrefixes + /dev（/dev/null 等）。
+export function seatbeltProfile({ cwd, allowWritePrefixes = DEFAULT_SANDBOX.allowWritePrefixes, blockNetwork = true } = {}) {
+  const prefixes = canonicalPaths([cwd, ...(allowWritePrefixes || []), '/dev']);
+  const writeRules = prefixes.map((p) => `    (subpath ${sbStr(p)})`).join('\n');
+  return [
+    '(version 1)',
+    '(allow default)',                       // 基準放行，後面的 deny 覆蓋之（規則後者優先）
+    ...(blockNetwork ? ['(deny network*)'] : []),
+    '(deny file-write*)',                    // 先擋所有寫入
+    '(allow file-write*',                    // 再放行 cwd / 暫存 / /dev 內的寫入
+    writeRules,
+    ')',
+    '',
+  ].join('\n');
+}
+
+// 把命令包進 Seatbelt（sandbox-exec -p，profile 內聯、不留暫存檔）。
+// 回傳改寫後可直接交給 shell 執行的命令字串；非 macOS / 無 sandbox-exec / 空命令 / 無 cwd → 回 null
+// （呼叫端據此跑原命令，行為不變）。profile 與 sandboxViolation 共用同一組策略欄位，兩層一致。
+export function wrapWithSeatbelt(command, { cwd, cfg = {} } = {}) {
+  const cmd = String(command || '');
+  if (!cmd.trim() || !cwd || !seatbeltAvailable()) return null;
+  const profile = seatbeltProfile({
+    cwd,
+    allowWritePrefixes: cfg.allowWritePrefixes || DEFAULT_SANDBOX.allowWritePrefixes,
+    blockNetwork: cfg.blockNetwork !== false,
+  });
+  return `${SANDBOX_EXEC} -p ${shq(profile)} /bin/bash -c ${shq(cmd)}`;
+}

package/src/kernel/session.js

@@ -0,0 +1,36 @@
+// 對話持久化 / resume — kernel 內建。每輪結束存 messages 到 <dir>/<id>.json，可續接。
+// 對標 xitto-code session.js。id 為 YYYYMMDD-HHMMSS。
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const pad = (n) => String(n).padStart(2, '0');
+
+export function newSessionId(now = new Date()) {
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+export function saveSession(dir, id, data) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${id}.json`), JSON.stringify({ id, ...data, savedAt: Date.now() }, null, 2));
+}
+
+export function loadSession(dir, id) {
+  const p = join(dir, `${id}.json`);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+export function listSessions(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => loadSession(dir, f.replace(/\.json$/, '')))
+    .filter(Boolean)
+    .map((d) => ({ id: d.id, count: d.messages?.length || 0, model: d.model?.id, savedAt: d.savedAt || 0 }))
+    // savedAt 新→舊；同毫秒時用 id 遞減（id 為時間戳，字典序=時間序）打破平手，確保 latest 確定性
+    .sort((a, b) => (b.savedAt - a.savedAt) || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+}
+
+export function latestSession(dir) {
+  return listSessions(dir)[0] || null;
+}

package/src/kernel/skills.js

@@ -0,0 +1,37 @@
+// Skills（漸進揭露）— kernel 內建。.xitto-kernel/<pack>/skills/*.md 每檔一個技能。
+// system prompt 只列「名稱 + 簡述」；agent 用 skill 工具按名載入完整步驟。對標 xitto-code skills。
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+const firstDesc = (body) => {
+  const fm = body.match(/^description:\s*(.+)$/mi);
+  if (fm) return fm[1].trim();
+  return (body.split('\n').map((l) => l.replace(/^#+\s*/, '').trim()).find(Boolean)) || '';
+};
+
+export function createSkills(dir) {
+  const skills = [];
+  if (existsSync(dir)) {
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+      try { const body = readFileSync(join(dir, f), 'utf8'); skills.push({ name: f.replace(/\.md$/, ''), desc: firstDesc(body), body }); } catch { /* 略 */ }
+    }
+  }
+
+  const promptSection = () => (skills.length
+    ? '\n\n# 可用技能（需要時用 skill 工具按名載入完整步驟）\n' + skills.map((s) => `- ${s.name}：${s.desc}`).join('\n')
+    : '');
+
+  const tool = skills.length ? {
+    name: 'skill', label: '載入技能', readOnly: true,
+    description: '按名載入一個技能的完整步驟（漸進揭露：prompt 只列名稱+簡述，需要時才載全文）。',
+    parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    execute: async (_id, { name }) => {
+      const s = skills.find((x) => x.name === name);
+      return txt(s ? s.body : { error: '找不到技能', name, available: skills.map((x) => x.name) });
+    },
+  } : null;
+
+  return { skills, promptSection, tool };
+}

package/src/kernel/subagent.js

@@ -0,0 +1,46 @@
+// 子 agent（spawn）— kernel 內建能力。派一個「唯讀」子 agent 做聚焦調查，回傳結論文字，
+// 不把中間工具呼叫污染主對話。對標 Claude Code 的 Task / xitto-code 的 spawn_agent。
+// 子 agent 只拿唯讀工具，故不需守衛/沙箱（無副作用）。
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+const SUB_PROMPT =
+  '你是唯讀調查子 agent。只用提供的唯讀工具（讀檔/搜尋/列目錄/記憶）查證，不臆測、不杜撰；' +
+  '查完後用簡潔文字把結論總結給主 agent（含關鍵檔案/行號/事實），不要長篇大論。';
+
+/**
+ * @param {Object} o
+ * @param {() => object} o.getModel
+ * @param {(provider: string) => string|Promise<string>} o.getApiKey
+ * @param {() => import('../types.js').Tool[]} o.getReadOnlyTools  子 agent 可用的唯讀工具集（不含 spawn_agent 自己）
+ */
+export function createSpawnTool({ getModel, getApiKey, getReadOnlyTools }) {
+  return {
+    name: 'spawn_agent', label: '子 agent', readOnly: true,
+    description: '派一個唯讀子 agent 做聚焦調查（讀檔/搜尋/分析），回傳結論文字。'
+      + '適合：需要深入查證一個子問題、但不想讓中間步驟塞滿主對話時。子 agent 不能改檔或跑命令。',
+    parameters: { type: 'object', properties: { task: { type: 'string', description: '要子 agent 調查的具體任務' } }, required: ['task'] },
+    execute: async (_id, { task }) => {
+      const model = getModel?.();
+      if (!model || !getApiKey) return txt({ error: '無 model/apiKey，無法派子 agent' });
+      const { Agent } = await import('./agent-loop.js');
+      const { defaultStreamFn } = await import('./provider.js');
+      const sub = new Agent({
+        initialState: {
+          systemPrompt: SUB_PROMPT,
+          model,
+          tools: getReadOnlyTools(),
+          thinkingLevel: model.reasoning ? 'low' : 'off',
+        },
+        getApiKey,
+        streamFn: defaultStreamFn(),
+        toolExecution: 'sequential',
+      });
+      try {
+        await sub.prompt(String(task || ''));
+        const last = [...sub.state.messages].reverse().find((m) => m.role === 'assistant');
+        const text = (last?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
+        return txt(text || '(子 agent 無輸出)');
+      } catch (e) { return txt({ error: e?.message || String(e) }); }
+    },
+  };
+}

package/src/kernel/tool-registry.js

@@ -0,0 +1,45 @@
+// 工具註冊表 — metadata 驅動，取代 xitto-code 寫死的 MUTATING/READ_ONLY 領域名單。
+// kernel 只認工具自帶的 mutating/readOnly/sandboxable，不認識任何具體領域。
+// 對應 docs/03-kernel-contract.md「D. 工具 metadata 驅動」。
+
+/** @param {import('../types.js').Tool} t */
+export const isReadOnly = (t) => t?.readOnly === true;
+/** @param {import('../types.js').Tool} t */
+export const isMutating = (t) => t?.mutating === true;
+/** @param {import('../types.js').Tool} t */
+export const isSandboxable = (t) => t?.sandboxable === true;
+
+/**
+ * 推導「會改動狀態」的工具名集合：pack 顯式給 mutatingTools 就用，否則從工具 metadata 推。
+ * @param {import('../types.js').DomainPack} pack
+ * @param {import('../types.js').Tool[]} tools
+ * @returns {string[]}
+ */
+export function deriveMutatingTools(pack, tools) {
+  if (Array.isArray(pack.mutatingTools)) return [...new Set(pack.mutatingTools)];
+  return [...new Set(tools.filter(isMutating).map((t) => t.name))];
+}
+
+/**
+ * 建立工具註冊表（名稱唯一）。
+ * @param {import('../types.js').Tool[]} tools
+ */
+export function createToolRegistry(tools) {
+  if (!Array.isArray(tools)) throw new Error('tools 必須是陣列');
+  const byName = new Map();
+  for (const t of tools) {
+    if (!t || typeof t.name !== 'string' || !t.name) throw new Error('工具缺少有效的 name');
+    if (typeof t.execute !== 'function') throw new Error(`工具「${t.name}」缺少 execute 函數`);
+    if (byName.has(t.name)) throw new Error(`工具名重複：${t.name}`);
+    byName.set(t.name, t);
+  }
+  return {
+    all: () => [...byName.values()],
+    get: (name) => byName.get(name),
+    has: (name) => byName.has(name),
+    names: () => [...byName.keys()],
+    readOnlyNames: () => [...byName.values()].filter(isReadOnly).map((t) => t.name),
+    mutatingNames: () => [...byName.values()].filter(isMutating).map((t) => t.name),
+    sandboxableNames: () => [...byName.values()].filter(isSandboxable).map((t) => t.name),
+  };
+}

package/src/packs/coding/index.js

@@ -0,0 +1,157 @@
+// coding pack — 參考 DomainPack（對標 xitto-code 的編碼能力）。
+// 工具以輕量真實實作示範（read/ls/write/edit 真的動檔案）；bash 走 shell。
+// read-before-edit 守衛與 read 工具透過閉包共享 readFiles 狀態，故能真實生效。
+// 對應 docs/05-example-packs.md「A. coding pack」。
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+const SYSTEM_PROMPT = [
+  '你是嚴謹的編碼 agent。準則：',
+  '- 編輯既有檔案前必先 read 它的當前內容，不基於臆測修改。',
+  '- 一次做一件事，改動後說明你做了什麼、如何驗證。',
+  '- 破壞性操作先確認。',
+  '- 要提交時：先 git_diff 看變更，再用 git_commit 寫一則簡潔、說明「為何」的 commit 訊息。',
+].join('\n');
+
+/**
+ * 建立一個帶獨立 readFiles 狀態的 coding pack。
+ * @param {{ cwd?: string }} [opts]
+ * @returns {import('../../types.js').DomainPack}
+ */
+export function createCodingPack({ cwd = process.cwd() } = {}) {
+  const readFiles = new Set(); // 已 read 過的絕對路徑（read 工具寫入、read-before-edit 守衛讀取）
+  const abs = (p) => (isAbsolute(p) ? p : join(cwd, p));
+
+  const readTool = {
+    name: 'read', label: '讀檔', description: '讀取檔案內容', readOnly: true,
+    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    execute: async (_id, { path }) => {
+      const p = abs(path);
+      if (!existsSync(p)) return txt({ error: '檔案不存在', path });
+      readFiles.add(p);
+      return txt(readFileSync(p, 'utf8'));
+    },
+  };
+
+  const lsTool = {
+    name: 'ls', label: '列目錄', description: '列出目錄內容', readOnly: true,
+    parameters: { type: 'object', properties: { path: { type: 'string' } } },
+    execute: async (_id, { path = '.' }) => {
+      const p = abs(path);
+      if (!existsSync(p)) return txt({ error: '目錄不存在', path });
+      return txt(readdirSync(p).map((n) => n + (statSync(join(p, n)).isDirectory() ? '/' : '')).join('\n'));
+    },
+  };
+
+  const writeTool = {
+    name: 'write', label: '寫檔', description: '建立或覆寫檔案', mutating: true,
+    parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+    execute: async (_id, { path, content }) => {
+      const p = abs(path);
+      writeFileSync(p, content ?? '', 'utf8');
+      readFiles.add(p); // 寫過即視為已知內容
+      return txt({ written: path, bytes: Buffer.byteLength(content ?? '') });
+    },
+  };
+
+  const editTool = {
+    name: 'edit', label: '編輯', description: '把檔案中的 oldText 換成 newText', mutating: true,
+    parameters: { type: 'object', properties: { path: { type: 'string' }, oldText: { type: 'string' }, newText: { type: 'string' } }, required: ['path', 'oldText', 'newText'] },
+    execute: async (_id, { path, oldText, newText }) => {
+      const p = abs(path);
+      if (!existsSync(p)) return txt({ error: '檔案不存在', path });
+      const before = readFileSync(p, 'utf8');
+      if (!before.includes(oldText)) return txt({ error: 'oldText 未找到', path });
+      writeFileSync(p, before.replace(oldText, newText), 'utf8');
+      return txt({ edited: path });
+    },
+  };
+
+  const bashTool = {
+    name: 'bash', label: 'bash', description: '執行 shell 命令', mutating: true, sandboxable: true,
+    parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+    execute: async (_id, { command }) => {
+      // 註：真實的串流/逾時/沙箱包裹由移植 xitto-code 的 bash 工具取得（見 docs/04 第 3 項）。
+      try { return txt(execSync(command, { cwd, encoding: 'utf8', timeout: 120000 }) || '(no output)'); }
+      catch (e) { return txt({ error: e.message, stdout: e.stdout, stderr: e.stderr }); }
+    },
+  };
+
+  // ── git 工具（編碼領域）：kernel 不認識 git，這些是 coding pack 提供的領域能力 ──
+  const git = (a) => { try { return execSync(`git ${a}`, { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }); } catch { return null; } };
+  const isRepo = () => { try { execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'ignore' }); return true; } catch { return false; } };
+
+  const gitStatus = {
+    name: 'git_status', label: 'git 狀態', readOnly: true, description: '顯示目前分支與工作區變更（git status）',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => { if (!isRepo()) return txt({ error: '非 git 倉庫' }); return txt({ branch: (git('rev-parse --abbrev-ref HEAD') || '').trim(), changes: (git('status --short') || '').trim() || '(乾淨)' }); },
+  };
+  const gitDiff = {
+    name: 'git_diff', label: 'git diff', readOnly: true, description: '顯示未提交變更的 diff（staged=true 看已暫存）',
+    parameters: { type: 'object', properties: { staged: { type: 'boolean' } } },
+    execute: async (_id, { staged } = {}) => { if (!isRepo()) return txt({ error: '非 git 倉庫' }); return txt((git(`diff ${staged ? '--cached' : ''}`) || '').trim() || '(無變更)'); },
+  };
+  const gitLog = {
+    name: 'git_log', label: 'git log', readOnly: true, description: '最近的提交記錄',
+    parameters: { type: 'object', properties: { n: { type: 'number' } } },
+    execute: async (_id, { n = 10 } = {}) => { if (!isRepo()) return txt({ error: '非 git 倉庫' }); return txt(git(`log --oneline -${Math.min(50, Math.max(1, n || 10))}`) || '(無提交)'); },
+  };
+  const gitCommit = {
+    name: 'git_commit', label: 'git commit', mutating: true,
+    description: '提交變更。message 由你依 git_diff 撰寫（簡潔說明做了什麼與為何）；all=true 會先 git add -A。',
+    parameters: { type: 'object', properties: { message: { type: 'string' }, all: { type: 'boolean' } }, required: ['message'] },
+    execute: async (_id, { message, all }) => {
+      if (!isRepo()) return txt({ error: '非 git 倉庫' });
+      if (all) git('add -A');
+      try { return txt((execSync(`git commit -m ${JSON.stringify(String(message))}`, { cwd, encoding: 'utf8' }) || '').trim()); }
+      catch (e) { return txt({ error: (e.stdout || e.message || '').toString().trim() }); }
+    },
+  };
+
+  return {
+    name: 'coding',
+    tools: () => [readTool, lsTool, writeTool, editTool, bashTool, gitStatus, gitDiff, gitLog, gitCommit],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['CLAUDE.md', 'AGENTS.md', 'XITTO.md', '.xitto-code.md'],
+    // mutatingTools 省略 → kernel 從工具 metadata 推導（write/edit/bash）
+    verify: {
+      shouldRun: (ctx) => ctx.turnModified,
+      run: async () => {
+        const cmd = detectVerifyCmd(cwd);
+        if (!cmd) return { ok: true };
+        try { execSync(cmd, { cwd, stdio: 'pipe' }); return { ok: true }; }
+        catch (e) { return { ok: false, output: String(e.stdout || e.message).slice(0, 4000) }; }
+      },
+      maxRounds: 2,
+    },
+    preToolPolicy: {
+      // read-before-edit：編輯已存在但未讀過的檔 → 擋下要求先 read
+      check: (ctx) => {
+        if ((ctx.name === 'edit' || ctx.name === 'write') && ctx.args?.path) {
+          const p = abs(ctx.args.path);
+          if (existsSync(p) && !readFiles.has(p)) {
+            return { block: true, reason: `請先用 read 讀取 ${ctx.args.path} 的當前內容，再進行編輯（read-before-edit）。` };
+          }
+        }
+        return undefined;
+      },
+    },
+    permissionPolicy: { sandbox: { enabled: false }, defaultMode: 'default' },
+  };
+}
+
+// 偵測專案的型別/lint 驗證指令（簡化版；真實版見 xitto-code util.detectVerifyCmd）
+function detectVerifyCmd(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    if (pkg.scripts?.typecheck) return 'npm run typecheck';
+    if (pkg.scripts?.lint) return 'npm run lint';
+  } catch { /* 無 package.json → 無驗證指令 */ }
+  return null;
+}
+
+export const codingPack = createCodingPack();
+export { relative }; // 供示範引用

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

@@ -0,0 +1,67 @@
+// data-query pack — 第二個範例領域，用來證明「同介面、kernel 零改動」。
+// 工具為示意 stub（回傳假資料），重點是六個插槽用法與 coding 完全一樣，只是內容換了。
+// 對照：schema-before-query 之於資料查詢 == read-before-edit 之於編碼（同 preToolPolicy 插槽）。
+// 對應 docs/05-example-packs.md「B. data-query pack」。
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+const SYSTEM_PROMPT = [
+  '你是資料分析 agent。準則：',
+  '- 下查詢前先用 list_tables / describe_table 了解結構。',
+  '- 破壞性 SQL（DROP/TRUNCATE/DELETE 無 WHERE）一律先確認。',
+].join('\n');
+
+/**
+ * @param {{ schema?: Record<string,string[]> }} [opts]
+ * @returns {import('../../types.js').DomainPack}
+ */
+export function createDataQueryPack({ schema = { orders: ['id', 'amount', 'user_id'], users: ['id', 'name'] } } = {}) {
+  let schemaLoaded = false; // describe/list 後設為 true，schema-before-query 守衛據此放行
+
+  const listTables = {
+    name: 'list_tables', label: '列表', description: '列出所有資料表', readOnly: true,
+    parameters: { type: 'object', properties: {} },
+    execute: async () => { schemaLoaded = true; return txt(Object.keys(schema)); },
+  };
+  const describeTable = {
+    name: 'describe_table', label: '表結構', description: '看某表欄位', readOnly: true,
+    parameters: { type: 'object', properties: { table: { type: 'string' } }, required: ['table'] },
+    execute: async (_id, { table }) => { schemaLoaded = true; return txt(schema[table] || { error: '無此表' }); },
+  };
+  const sqlQuery = {
+    name: 'sql_query', label: '查詢', description: '執行唯讀 SQL 查詢', readOnly: true,
+    parameters: { type: 'object', properties: { sql: { type: 'string' } }, required: ['sql'] },
+    execute: async (_id, { sql }) => txt({ note: '（示意）查詢結果', sql, rows: [] }),
+  };
+  const sqlExec = {
+    name: 'sql_exec', label: '寫入', description: '執行寫入型 SQL（INSERT/UPDATE/DELETE）', mutating: true,
+    parameters: { type: 'object', properties: { sql: { type: 'string' } }, required: ['sql'] },
+    execute: async (_id, { sql }) => txt({ note: '（示意）已執行', sql }),
+  };
+  const chartRender = {
+    name: 'chart_render', label: '畫圖', description: '把查詢結果渲染成圖表', readOnly: true,
+    parameters: { type: 'object', properties: { spec: { type: 'object' } }, required: ['spec'] },
+    execute: async (_id, { spec }) => txt({ note: '（示意）已渲染', spec }),
+  };
+
+  return {
+    name: 'data-query',
+    tools: () => [listTables, describeTable, sqlQuery, sqlExec, chartRender],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['SCHEMA.md', 'METRICS.md'],
+    // sql_query 唯讀、sql_exec 才 mutating → 從 metadata 自動推導 mutatingTools=['sql_exec']
+    preToolPolicy: {
+      // schema-before-query：沒先看過 schema 就下查詢 → 擋
+      check: (ctx) => {
+        if ((ctx.name === 'sql_query' || ctx.name === 'sql_exec') && !schemaLoaded) {
+          return { block: true, reason: '請先用 list_tables / describe_table 了解結構，再下 SQL。' };
+        }
+        return undefined;
+      },
+    },
+    permissionPolicy: { deny: ['bash:DROP', 'bash:TRUNCATE'], defaultMode: 'default' },
+    // verify 省略 → 查詢無「自我驗收」概念
+  };
+}
+
+export const dataQueryPack = createDataQueryPack();

package/src/packs/notes/index.js

@@ -0,0 +1,79 @@
+// notes pack — 第三個範例領域：知識庫 / 筆記 agent。
+// 用來示範「怎麼從零做一個新領域 agent」（見 docs/06-authoring-a-pack.md）。
+// 工具操作 <cwd>/.notes/*.md；preToolPolicy 用 search-before-add（對照 read-before-edit）。
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+const slug = (t) => String(t).trim().toLowerCase().replace(/[^\w一-鿿]+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'note';
+
+const SYSTEM_PROMPT = [
+  '你是知識庫助手，管理使用者的筆記。準則：',
+  '- 新增筆記前，先 search_notes 確認沒有重複或相關條目。',
+  '- 回答問題時優先 search_notes / read_note 找既有筆記，不要憑空編造。',
+].join('\n');
+
+/**
+ * @param {{ cwd?: string }} [opts]
+ * @returns {import('../../types.js').DomainPack}
+ */
+export function createNotesPack({ cwd = process.cwd() } = {}) {
+  const dir = join(cwd, '.notes');
+  const searched = new Set(); // 已 search/list 過（search-before-add 守衛用）
+  const ensure = () => { if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); };
+  const all = () => (existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.md')) : []);
+
+  const listNotes = {
+    name: 'list_notes', label: '列筆記', description: '列出所有筆記標題', readOnly: true,
+    parameters: { type: 'object', properties: {} },
+    execute: async () => { searched.add('*'); return txt(all().map((f) => f.replace(/\.md$/, '')) || []); },
+  };
+  const searchNotes = {
+    name: 'search_notes', label: '搜尋筆記', description: '依關鍵字搜尋筆記標題與內容', readOnly: true,
+    parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+    execute: async (_id, { query }) => {
+      searched.add('*');
+      const q = String(query || '').toLowerCase();
+      const hits = all().filter((f) => (f + readFileSync(join(dir, f), 'utf8')).toLowerCase().includes(q));
+      return txt({ query, hits: hits.map((f) => f.replace(/\.md$/, '')) });
+    },
+  };
+  const readNote = {
+    name: 'read_note', label: '讀筆記', description: '讀取某篇筆記內容', readOnly: true,
+    parameters: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] },
+    execute: async (_id, { title }) => {
+      const p = join(dir, slug(title) + '.md');
+      return existsSync(p) ? txt(readFileSync(p, 'utf8')) : txt({ error: '找不到筆記', title });
+    },
+  };
+  const addNote = {
+    name: 'add_note', label: '新增筆記', description: '新增一篇筆記（標題 + 內容）', mutating: true,
+    parameters: { type: 'object', properties: { title: { type: 'string' }, body: { type: 'string' } }, required: ['title', 'body'] },
+    execute: async (_id, { title, body }) => {
+      ensure();
+      const p = join(dir, slug(title) + '.md');
+      writeFileSync(p, `# ${title}\n\n${body}\n`, 'utf8');
+      return txt({ saved: title, file: p });
+    },
+  };
+
+  return {
+    name: 'notes',
+    tools: () => [listNotes, searchNotes, readNote, addNote],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['NOTES.md'],
+    // mutatingTools 省略 → 從 metadata 推導（add_note）
+    preToolPolicy: {
+      // search-before-add：沒先 search/list 就新增 → 擋（避免重複，對照 read-before-edit）
+      check: (ctx) => {
+        if (ctx.name === 'add_note' && !searched.has('*')) {
+          return { block: true, reason: '新增前請先 search_notes 或 list_notes 確認沒有重複。' };
+        }
+        return undefined;
+      },
+    },
+    permissionPolicy: { defaultMode: 'default' },
+  };
+}
+
+export const notesPack = createNotesPack();