xitto-kernel 0.3.2 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.3.5
+
+- **執行中沉澱經驗 — 專案手冊（程序層）**：agent 摸清專案「做事方法」時自己記下來,跨 session 自動載入。
+  - 新增 kernel 內建工具 `playbook_update`（按 topic 記/更新,同 topic 覆蓋去重）、`playbook_remove`
+  - 落地 `.xitto-kernel/<pack>/playbook.md`；綁 cwd → 天然只對該專案生效(自帶相關性範圍)
+  - 開場自動注入 system prompt（`# 專案手冊`）+ 引導語；與 `memory`(事實層) 分工明確
+  - `/playbook`（查看）、`/playbook forget <主題>`、`/playbook clear`；`api.playbook.{list,update,remove,clear,load,path}`
+  - 5 個測試（topic 去重/多條/落地重載/多行 note/kernel 注入）+ 真實 model 端到端閉環驗證
+    （agent 呼叫 playbook_update → 落地 → 新 session 自動載入）
+
+## 0.3.4
+
+- **漸進式放權（per-pattern 記住批准）**：把「事事都問的煩」和「全自動的怕」同時解掉。
+  - 批准工具時可選 `[a]` 信任整個工具、或 `[c]` 只信任「命令簽章類」（`git status` ≠ `npm install`）
+  - 信任**落地到 `.xitto-kernel/<pack>/allow.json`,跨 session 累積**；重啟後同類自動放行
+  - 自動放行時標示「✓ 已信任」（`onTrusted` 回呼,維持可理解性）
+  - **危險命令永不寫入信任**,即使選 always 也只放行這次
+  - `/trust`（查看）、`/trust forget <項>`、`/trust clear`；`api.permissions.{list,forget,clear,path}`
+  - 新增 `allow-store.js`（`memoryAllowStore` / `fileAllowStore`）；接通既有 `parseAllowFile`/`commandSignature`
+  - 6 個測試 + 跨 kernel 實例（模擬重啟）整合驗證
+
+## 0.3.3
+
+- **背景任務 + 完成通知（非同步交互）**：server 新增「派任務→通知」形態，把 agent 當同事用。
+  - `POST /v1/tasks`：立刻回 `202 + taskId`，後台跑，完成 POST 結果到 `webhook`
+  - `GET /v1/tasks`、`GET /v1/tasks/:id`：列表 / 狀態 + 結果
+  - `GET /v1/tasks/:id/events`：附掛事件流（SSE，replay 緩衝 + 即時）
+  - 限流並發 `XITTO_SERVER_CONCURRENCY`（預設 2）
+  - 抽出 `createTaskStore`（純記憶體、可測）與 `mapEvent`；`/v1/run`/`/v1/stream` 共用 `runKernel`
+  - 5 個任務佇列測試（狀態轉移 / 限流 / 事件緩衝 / 完成回呼 / 訂閱）
+
 ## 0.3.2
 
 - **沒設定就啟動 → 直接進導引**：偵測到沒有 providers.json 且在真實終端時，

package/README.md

@@ -48,7 +48,11 @@ xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
 ```
 
-**CLI 內操作**：直接打需求（模型會自己呼叫工具）；指令 `/help` `/goal <目標>` `/sandbox` `/plan` `/undo` `/tools` `/memory` `/sessions` `/resume` `/exit`；`Ctrl+C` 中斷該輪、閒置時再按一次離開。
+**CLI 內操作**：直接打需求（模型會自己呼叫工具）；指令 `/help` `/goal <目標>` `/sandbox` `/plan` `/undo` `/tools` `/trust` `/memory` `/sessions` `/resume` `/exit`；`Ctrl+C` 中斷該輪、閒置時再按一次離開。
+
+**漸進式放權（trust 隨用累積）**：mutating/危險工具執行前會確認；批准時可選 `[a]` 信任整個工具、或 `[c]` 只信任「該命令簽章類」（如 `git status`、`npm test`——細粒度,`npm install` 仍會問）。選擇會**落地到 `.xitto-kernel/<pack>/allow.json`,跨 session 記得**,下次同類自動放行並標示「✓ 已信任」。`/trust` 查看、`/trust forget <項>` 撤銷、`/trust clear` 全清。一開始謹慎、用著用著越來越順手——危險命令永不寫入信任,每次都把關。
+
+**執行中沉澱經驗（專案手冊）**：agent 摸清「這個專案怎麼做事」(建置/測試/部署指令、慣例、必經步驟、踩過的坑與修法)時,會用 `playbook_update` 按 topic 記進 `.xitto-kernel/<pack>/playbook.md`(同 topic 覆蓋,天然去重)；**下次 session 自動載入系統提示,不必重新摸索**。因檔案綁 cwd,手冊天然只對這個專案生效。`/playbook` 查看、`/playbook forget <主題>`、`/playbook clear`。分工:`memory` 存事實/偏好/決策(扁平),`playbook` 存可重複的程序知識(按主題)。
 
 **通用自主 agent（給目標、自己做到完成）**
 ```bash
@@ -72,6 +76,20 @@ curl -s -XPOST localhost:8787/v1/run -H "Authorization: Bearer secret" \
 結構化 JSON 日誌（審計/觀測）、6 個 pack 可選、JSON 或 SSE（`/v1/stream`）串流。
 「個人 vs 生產」是 **app 層**的事 —— 同一個 kernel，CLI 與 server 是兩個 app。
 
+**背景任務 + 完成通知（非同步交互）** —— 派任務出去、立刻拿到 `taskId`、做完回呼 webhook，不用一直盯著：
+```bash
+# 派任務（立刻回 202 + taskId），完成時 POST 結果到 webhook
+curl -s -XPOST localhost:8787/v1/tasks -H "Authorization: Bearer secret" \
+  -H content-type:application/json \
+  -d '{"pack":"general","mode":"goal","goal":"...","webhook":"https://你的服務/done"}'
+
+curl -s localhost:8787/v1/tasks            -H "Authorization: Bearer secret"   # 列表
+curl -s localhost:8787/v1/tasks/<id>       -H "Authorization: Bearer secret"   # 狀態 + 結果
+curl -sN localhost:8787/v1/tasks/<id>/events -H "Authorization: Bearer secret" # 附掛事件流（SSE，replay+即時）
+```
+限流並發 `XITTO_SERVER_CONCURRENCY`（預設 2）；webhook 完成時收到 `{taskId,status,text,usage,rounds,done}`。
+這把「即時盯著看」延伸到「派任務→通知」的非同步形態（像把 agent 當同事）。
+
 ## 做你自己的領域 agent（不固化）
 
 kernel 是**被依賴的套件**，不是被 clone 的範本。你的 agent 是獨立小專案：

package/package.json

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

package/src/app/cli.js

@@ -36,6 +36,10 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     getSandbox: () => sandboxOn,            // on/off 由 CLI 即時切換
     getPlanMode: () => planMode,            // 計劃模式：守衛擋 mutating 工具
     confirm: askConfirm,                    // 互動權限確認（mutating/危險工具執行前）
+    onTrusted: ({ name, signature, scope }) => {            // 漸進放權：自動放行時標示「已信任」（維持可理解）
+      endStream();
+      out(c.gray(`  ✓ 已信任 ${scope === 'command' ? `「${signature}」類` : name}，自動放行\n`));
+    },
   });
 
   let history = [];
@@ -63,19 +67,25 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   // 互動權限確認：守衛鏈第 5 格對 mutating/危險工具呼叫此函數。autoApprove → 一律放行。
-  // 回 'yes'（允許一次）/ 'always'（此工具全部）/ 'no'（拒絕）。
-  async function askConfirm(name, args, danger) {
+  // 回 'yes'（允許一次）/ 'command'（信任此命令簽章類,跨 session）/ 'always'（信任此工具全部）/ 'no'（拒絕）。
+  async function askConfirm(name, args, danger, meta = {}) {
     if (autoApprove && !danger) return 'yes';   // 自動模式仍對危險命令把關
     endStream();
+    const sig = meta.signature; // 有簽章（bash 類）才提供細粒度「信任這類命令」
     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]拒絕';
+      const hint = danger ? '[y]允許一次  [n]拒絕'
+        : sig ? `[y]允許  [c]信任「${sig}」類  [a]信任 ${name} 全部  [n]拒絕`
+          : `[y]允許  [a]信任 ${name} 全部  [n]拒絕`;
+      out(c.gray('    （c/a 會記住,下次自動放行；/trust 查看與撤銷）\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');
+          if (a === 'a') return res('always');
+          if (a === 'c' && sig) return res('command');
+          res(a === 'y' || a === 'yes' ? 'yes' : 'no');
         });
       } catch { res('no'); }
     });
@@ -163,7 +173,9 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           '  /goal <目標>      目標驅動自主循環（反覆做到完成）',
           '  /undo            撤銷上一次檔案改動（write/edit）',
           '  /tools           列出此 pack 的工具',
+          '  /trust [forget <項>|clear]  已信任的工具/命令（漸進放權,跨 session）',
           '  /memory          顯示跨 session 記憶',
+          '  /playbook [forget <主題>|clear]  專案手冊（agent 沉澱的程序知識,跨 session）',
           '  /sessions        列出已保存的對話',
           '  /resume [id]     續接對話（不給 id=最近一次）',
           '  /clear           清除歷史（開新 session）',
@@ -175,6 +187,36 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
         out(mems.length ? c.gray(mems.map((m) => '  • ' + m).join('\n') + '\n') : c.gray('（尚無記憶）\n'));
         return true;
       }
+      case '/playbook': {
+        const rest = input.trim().slice(cmd.length).trim();
+        if (rest === 'clear') { const { cleared } = kernel.playbook.clear(); out(c.gray(`（已清空專案手冊,移除 ${cleared} 條）\n`)); return true; }
+        if (rest.startsWith('forget ')) {
+          const t = rest.slice('forget '.length).trim();
+          const r = kernel.playbook.remove(t);
+          out(r.removed ? c.gray(`（已移除「${t}」）\n`) : c.yellow(`找不到主題「${t}」\n`));
+          return true;
+        }
+        const entries = kernel.playbook.list();
+        if (!entries.length) { out(c.gray('（尚無專案手冊；agent 摸清做法時會用 playbook_update 累積）\n')); return true; }
+        out(entries.map((e) => c.cyan(`  ## ${e.topic}\n`) + c.gray(e.note.split('\n').map((l) => '  ' + l).join('\n'))).join('\n') + '\n');
+        if (kernel.playbook.path) out(c.gray(`  ↳ ${kernel.playbook.path}（清除：/playbook forget <主題>）\n`));
+        return true;
+      }
+      case '/trust': {
+        const rest = input.trim().slice(cmd.length).trim();
+        if (rest === 'clear') { kernel.permissions.clear(); out(c.gray('（已清除全部信任）\n')); return true; }
+        if (rest.startsWith('forget ')) {
+          const entry = rest.slice('forget '.length).trim();
+          out(kernel.permissions.forget(entry) ? c.gray(`（已撤銷信任：${entry}）\n`) : c.yellow(`找不到信任項「${entry}」\n`));
+          return true;
+        }
+        const { tools, bash } = kernel.permissions.list();
+        if (!tools.length && !bash.length) { out(c.gray('（尚無已信任項；批准工具時選 a/c 即可記住）\n')); return true; }
+        if (tools.length) out(c.gray('  工具（全部放行）：') + tools.join('、') + '\n');
+        if (bash.length) out(c.gray('  命令（簽章類）：') + bash.map((s) => `「${s}」`).join('、') + '\n');
+        if (kernel.permissions.path) out(c.gray(`  ↳ ${kernel.permissions.path}（撤銷：/trust forget <項>）\n`));
+        return true;
+      }
       case '/sessions': {
         const ss = kernel.session.list();
         out(ss.length
@@ -225,7 +267,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
   };
 
   // 斜線指令 tab 補全
-  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/memory', '/sessions', '/resume', '/clear', '/exit'];
+  const SLASH = ['/help', '/goal ', '/sandbox', '/auto', '/plan', '/undo', '/tools', '/trust', '/memory', '/playbook', '/sessions', '/resume', '/clear', '/exit'];
   const completer = (line) => {
     if (!line.startsWith('/')) return [[], line];
     const hits = SLASH.filter((s) => s.startsWith(line));

package/src/app/server.js

@@ -1,6 +1,7 @@
 // Server app（PoC）— 把 kernel 包成 HTTP 服務（零依賴 node:http）。
 // 證明 kernel 能脫離 CLI 跑成服務：bearer token 認證、per-session 隔離工作目錄、沙箱、結構化日誌、
-// JSON 或 SSE 串流。這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
+// JSON 或 SSE 串流，以及「背景任務 + 完成通知（webhook）」—— 派任務出去、做完回呼，不用一直盯著。
+// 這是「另一個 app 消費同一組 kernel 事件」—— 不動 kernel 核心。
 import { createServer } from 'node:http';
 import { mkdirSync } from 'node:fs';
 import { join } from 'node:path';
@@ -20,7 +21,75 @@ 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 = () => 's' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+const newId = (p = 's') => p + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+
+// 把原始 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 === 'message_update' && ev.assistantMessageEvent?.type === 'text_delta') return { type: 'text', delta: ev.assistantMessageEvent.delta };
+  return null;
+};
+
+/**
+ * 背景任務佇列（純記憶體、可測，與 HTTP 無關）。
+ * 派任務 → 限流跑 → 緩衝事件供事後附掛 → 完成回呼（webhook）。
+ * @param {Object} o
+ * @param {(spec:object, emit:(ev:object)=>void)=>Promise<any>} o.runJob  實際執行（回傳值＝任務結果）
+ * @param {number} [o.concurrency]   同時跑幾個（預設 2）
+ * @param {(task:object)=>void} [o.onFinish]  每個任務 settle 後呼叫（拿來發 webhook）
+ * @param {number} [o.maxEvents]     每任務保留最近幾筆事件（預設 500）
+ */
+export function createTaskStore({ runJob, concurrency = 2, onFinish, maxEvents = 500 } = {}) {
+  const tasks = new Map();   // id -> task
+  const queue = [];          // 等待中的 task
+  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', sessionId: t.result?.sessionId || t.spec.sessionId || null, createdAt: t.createdAt, startedAt: t.startedAt, finishedAt: t.finishedAt, error: t.error });
+
+  const emit = (t, ev) => {
+    t.events.push(ev);
+    if (t.events.length > maxEvents) t.events.shift();
+    const s = subs.get(t.id); if (s) for (const fn of s) { try { fn(ev); } catch { /* 訂閱端錯不影響任務 */ } }
+  };
+
+  function pump() {
+    while (active < concurrency && queue.length) {
+      const t = queue.shift();
+      active++;
+      t.status = 'running'; t.startedAt = new Date().toISOString();
+      emit(t, { type: 'status', status: 'running' });
+      Promise.resolve()
+        .then(() => runJob(t.spec, (ev) => emit(t, ev)))
+        .then((result) => { t.status = 'done'; t.result = result; })
+        .catch((e) => { t.status = 'error'; t.error = e.message || String(e); })
+        .finally(() => {
+          t.finishedAt = new Date().toISOString();
+          emit(t, { type: 'end', status: t.status, result: t.result, error: t.error });
+          active--;
+          try { onFinish?.(t); } catch { /* webhook 錯不影響佇列 */ }
+          pump();
+        });
+    }
+  }
+
+  return {
+    enqueue(spec) {
+      const t = { id: newId('t'), status: 'queued', spec: spec || {}, events: [], result: null, error: null, createdAt: new Date().toISOString(), startedAt: null, finishedAt: null };
+      tasks.set(t.id, t);
+      queue.push(t);
+      pump();
+      return t;
+    },
+    get: (id) => tasks.get(id),
+    view: (id) => { const t = tasks.get(id); return t ? view(t) : null; },
+    result: (id) => { const t = tasks.get(id); return t ? { ...view(t), result: t.result } : null; },
+    list: () => [...tasks.values()].map(view),
+    subscribe(id, fn) { let s = subs.get(id); if (!s) { s = new Set(); subs.set(id, s); } s.add(fn); return () => s.delete(fn); },
+    stats: () => ({ active, queued: queue.length, total: tasks.size }),
+  };
+}
 
 /**
  * @param {Object} o
@@ -29,9 +98,10 @@ const newId = () => 's' + Date.now().toString(36) + Math.random().toString(36).s
  * @param {string} [o.token]        bearer token（未設＝不驗證，僅 PoC）
  * @param {string} [o.baseDir]      每個 session 的隔離工作目錄根
  * @param {boolean} [o.sandbox]     是否沙箱（預設 true：服務端跑 agent 應隔離）
+ * @param {number} [o.concurrency]  背景任務同時數（預設 2）
  * @returns {import('node:http').Server}
  */
-export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true } = {}) {
+export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-server', sandbox = true, concurrency = 2 } = {}) {
   const sessions = new Map(); // sessionId -> { pack, history }
   mkdirSync(baseDir, { recursive: true });
 
@@ -39,49 +109,93 @@ export function createServerApp({ model, getApiKey, token, baseDir = '.xitto-ser
   const authed = (req) => !token || (req.headers.authorization === `Bearer ${token}`);
   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' });
+
+  // 共用：跑一輪/一目標，回傳 { sessionId, text, usage, rounds, done }；onEvent 收原始 kernel 事件
+  async function runKernel(spec, onEvent) {
+    const make = PACKS[spec.pack || 'general'];
+    if (!make) throw new Error(`未知 pack「${spec.pack}」，可用：${Object.keys(PACKS).join(', ')}`);
+    const sessionId = spec.sessionId || newId();
+    const sess = sessions.get(sessionId) || { pack: spec.pack || 'general', history: [] };
+    const workdir = join(baseDir, sessionId); mkdirSync(workdir, { recursive: true });
+    const kernel = createKernel(make({ cwd: workdir }), { cwd: workdir, model, getApiKey, sandbox: { enabled: sandbox }, getSandbox: () => sandbox, confirm: async () => 'yes' });
+    const usage = { input: 0, output: 0 };
+    const wrapped = (ev) => { if (ev.type === 'message_end' && ev.message?.usage) { usage.input += ev.message.usage.input || 0; usage.output += ev.message.usage.output || 0; } onEvent?.(ev); };
+    const r = (spec.mode === 'goal')
+      ? await kernel.runGoal(spec.goal || spec.input || '', { history: sess.history, onEvent: wrapped })
+      : await kernel.runTurn(spec.input || '', { history: sess.history, onEvent: wrapped });
+    sess.history = r.messages || r.history || []; sessions.set(sessionId, sess);
+    return { sessionId, text: r.text ?? lastText(sess.history), usage, rounds: r.rounds, done: r.done };
+  }
+
+  // 完成通知：POST 結果到 spec.webhook（http/https），單次嘗試、失敗記日誌不重試（PoC）
+  async function fireWebhook(task) {
+    const url = task.spec.webhook; if (!url || !/^https?:\/\//.test(url)) return;
+    const r = task.result || {};
+    const body = JSON.stringify({ taskId: task.id, status: task.status, error: task.error, sessionId: r.sessionId, text: r.text, usage: r.usage, rounds: r.rounds, done: r.done, finishedAt: task.finishedAt });
+    try { const resp = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body }); log({ webhook: url, task: task.id, status: task.status, code: resp.status }); }
+    catch (e) { log({ webhook: url, task: task.id, error: e.message }); }
+  }
+
+  const tasks = createTaskStore({
+    concurrency,
+    runJob: (spec, emit) => runKernel(spec, (ev) => { const m = mapEvent(ev); if (m) emit(m); }),
+    onFinish: (task) => { log({ task: task.id, pack: task.spec.pack, mode: task.spec.mode || 'turn', status: task.status, ms: task.startedAt ? Date.parse(task.finishedAt) - Date.parse(task.startedAt) : 0 }); fireWebhook(task); },
+  });
 
   return createServer(async (req, res) => {
     const url = new URL(req.url, 'http://localhost');
-    if (req.method === 'GET' && url.pathname === '/health') return json(res, 200, { ok: true, packs: Object.keys(PACKS), model: model.id });
+    const path = url.pathname;
+    if (req.method === 'GET' && path === '/health') return json(res, 200, { ok: true, packs: Object.keys(PACKS), model: model.id, tasks: tasks.stats() });
     if (!authed(req)) return json(res, 401, { error: 'unauthorized（帶 Authorization: Bearer <token>）' });
 
-    if (req.method === 'POST' && (url.pathname === '/v1/run' || url.pathname === '/v1/stream')) {
+    // 同步：跑完才回（JSON 或 SSE 串流）
+    if (req.method === 'POST' && (path === '/v1/run' || path === '/v1/stream')) {
       const body = await readBody(req);
-      const make = PACKS[body.pack || 'general'];
-      if (!make) return json(res, 400, { error: `未知 pack「${body.pack}」，可用：${Object.keys(PACKS).join(', ')}` });
-      const sessionId = body.sessionId || newId();
-      const sess = sessions.get(sessionId) || { pack: body.pack || 'general', history: [] };
-      const workdir = join(baseDir, sessionId); mkdirSync(workdir, { recursive: true });
-      const kernel = createKernel(make({ cwd: workdir }), { cwd: workdir, model, getApiKey, sandbox: { enabled: sandbox }, getSandbox: () => sandbox, confirm: async () => 'yes' });
-
-      const usage = { input: 0, output: 0 };
-      const streaming = url.pathname === '/v1/stream';
-      if (streaming) res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      const streaming = path === '/v1/stream';
+      if (streaming) sseHead(res);
       const sse = (o) => res.write(`data: ${JSON.stringify(o)}\n\n`);
-      const onEvent = (ev) => {
-        if (ev.type === 'message_end' && ev.message?.usage) { usage.input += ev.message.usage.input || 0; usage.output += ev.message.usage.output || 0; }
-        if (!streaming) return;
-        if (ev.type === 'tool_execution_start') sse({ type: 'tool', name: ev.toolName, args: ev.args });
-        else if (ev.type === 'message_update' && ev.assistantMessageEvent?.type === 'text_delta') sse({ type: 'text', delta: ev.assistantMessageEvent.delta });
-      };
-
       const t0 = Date.now();
       try {
-        const r = (body.mode === 'goal')
-          ? await kernel.runGoal(body.goal || body.input || '', { history: sess.history, onEvent })
-          : await kernel.runTurn(body.input || '', { history: sess.history, onEvent });
-        sess.history = r.messages || r.history || []; sessions.set(sessionId, sess);
-        const text = r.text ?? lastText(sess.history);
-        log({ pack: sess.pack, session: sessionId, mode: body.mode || 'turn', tokens: usage.input + usage.output, rounds: r.rounds, ms: Date.now() - t0 });
-        const payload = { sessionId, text, usage, rounds: r.rounds, done: r.done };
-        if (streaming) { sse({ type: 'done', ...payload }); res.end(); }
-        else json(res, 200, payload);
+        const r = await runKernel(body, streaming ? (ev) => { const m = mapEvent(ev); if (m) sse(m); } : undefined);
+        log({ pack: body.pack || 'general', session: r.sessionId, mode: body.mode || 'turn', tokens: r.usage.input + r.usage.output, rounds: r.rounds, ms: Date.now() - t0 });
+        if (streaming) { sse({ type: 'done', ...r }); res.end(); } else json(res, 200, r);
       } catch (e) {
-        log({ pack: sess.pack, session: sessionId, error: e.message });
-        if (streaming) { sse({ type: 'error', error: e.message }); res.end(); } else json(res, 500, { error: e.message });
+        log({ pack: body.pack, error: e.message });
+        if (streaming) { sse({ type: 'error', error: e.message }); res.end(); } else json(res, e.message?.startsWith('未知 pack') ? 400 : 500, { error: e.message });
       }
       return;
     }
+
+    // 背景任務：立刻回 taskId，後台跑，完成發 webhook
+    if (req.method === 'POST' && path === '/v1/tasks') {
+      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 });
+      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() });
+    }
+    if (req.method === 'GET' && path === '/v1/tasks') return json(res, 200, { tasks: tasks.list(), ...tasks.stats() });
+
+    // 任務狀態 / 結果
+    const mTask = path.match(/^\/v1\/tasks\/([^/]+)$/);
+    if (req.method === 'GET' && mTask) { const v = tasks.result(mTask[1]); return v ? json(res, 200, v) : json(res, 404, { error: 'task not found' }); }
+
+    // 附掛背景任務的事件流（replay 緩衝 + 即時；已結束則回放後關閉）
+    const mEv = path.match(/^\/v1\/tasks\/([^/]+)\/events$/);
+    if (req.method === 'GET' && mEv) {
+      const task = tasks.get(mEv[1]);
+      if (!task) return json(res, 404, { error: 'task not found' });
+      sseHead(res);
+      const sse = (o) => res.write(`data: ${JSON.stringify(o)}\n\n`);
+      for (const ev of task.events) sse(ev);
+      if (task.status === 'done' || task.status === 'error') { res.end(); return; }
+      const unsub = tasks.subscribe(task.id, (ev) => { sse(ev); if (ev.type === 'end') { try { unsub(); } catch { /* 略 */ } res.end(); } });
+      req.on('close', () => { try { unsub(); } catch { /* 略 */ } });
+      return;
+    }
+
     json(res, 404, { error: 'not found' });
   });
 }
@@ -90,11 +204,13 @@ export function startServer() {
   const port = Number(process.env.PORT || 8787);
   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 { model, getApiKey } = loadModel(process.env.XITTO_MODEL);
-  const server = createServerApp({ model, getApiKey, token, sandbox });
+  const server = createServerApp({ model, getApiKey, token, sandbox, concurrency });
   server.listen(port, () => {
-    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'}`);
+    console.log(`xitto-kernel server · http://localhost:${port} · model ${model.id} · 沙箱 ${sandbox ? '開' : '關'} · 背景並發 ${concurrency}`);
     console.log(`token: ${token === 'dev-token' ? 'dev-token（請設 XITTO_SERVER_TOKEN）' : '(已設定)'}`);
+    console.log('路由：POST /v1/run · /v1/stream · /v1/tasks（背景+webhook）｜GET /v1/tasks[/:id[/events]] · /health');
   });
   return server;
 }

package/src/kernel/index.js

@@ -8,8 +8,10 @@ import { loadPack } from './pack-loader.js';
 import { createToolRegistry, deriveMutatingTools, isSandboxable } from './tool-registry.js';
 import { composeGuards } from './guard-chain.js';
 import { createPermissionStep } from './security/permission-step.js';
+import { fileAllowStore, memoryAllowStore } from './security/allow-store.js';
 import { normalizeSandbox, wrapWithSeatbelt } from './security/sandbox.js';
 import { createMemory } from './memory.js';
+import { createPlaybook } from './playbook.js';
 import { createTodo } from './todo.js';
 import { createSpawnTool } from './subagent.js';
 import { createSkills } from './skills.js';
@@ -39,7 +41,10 @@ function loadContextFiles(cwd, names) {
 }
 
 const DEFAULT_MEMORY_GUIDE =
-  '遇到值得跨 session 記住的事實（使用者偏好、建置/測試指令、踩過的坑、專案決策）時，當下就存一條。';
+  '遇到值得跨 session 記住的事實（使用者偏好、踩過的坑、專案決策）時，當下就存一條。';
+
+const DEFAULT_PLAYBOOK_GUIDE =
+  '摸清這個專案的「做事方法」(如何建置/測試/執行/部署、慣例、必經步驟、坑與修法)時，用 playbook_update 按 topic 記下來(同 topic 覆蓋)；過時就用 playbook_remove 清掉。下次自動載入，不必重新摸索。分工：memory 存事實/偏好/決策，playbook 存可重複的程序步驟。';
 
 // 把 sandboxable 工具的命令在執行期包進 Seatbelt（macOS OS 級隔離）。
 // 非 macOS / 沙箱關閉 / 無 command → wrapWithSeatbelt 回 null，跑原命令（仍受第 5 格靜態策略保護）。
@@ -100,6 +105,7 @@ export function createKernel(pack, config = {}) {
   // 每個 pack 在 cwd 下有獨立資料夾（記憶、session 分領域存放，互不混）
   const dataDir = join(cwd, '.xitto-kernel', pack.name);
   const memory = createMemory(join(dataDir, 'memory.md'));
+  const playbook = createPlaybook(join(dataDir, 'playbook.md'));
   const todo = createTodo();
   const sessionsDir = join(dataDir, 'sessions');
   const hooks = loadHooks(join(dataDir, 'settings.json')); // PreToolUse/PostToolUse
@@ -115,6 +121,7 @@ export function createKernel(pack, config = {}) {
   const baseTools = [
     ...pack.tools().map((t) => wrapUndo(wrapSandboxable(t, { cwd, getSandbox, getSandboxConfig }), { cwd, undoStack })),
     ...memory.tools,
+    ...playbook.tools,
     todo.tool,
     ...(skills.tool ? [skills.tool] : []),
     ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
@@ -138,20 +145,29 @@ export function createKernel(pack, config = {}) {
   };
 
   const memText = memory.load();
+  const pbText = playbook.load();
   const systemPrompt =
     pack.systemPrompt +
     loadContextFiles(cwd, pack.contextFiles) +          // 注入領域規範檔（CLAUDE.md 等）
-    '\n\n# 記憶\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) +
+    '\n\n# 記憶與專案手冊\n' + (pack.memoryGuide || DEFAULT_MEMORY_GUIDE) + '\n' + DEFAULT_PLAYBOOK_GUIDE +
     (memText ? `\n\n# 已記住的事實（跨 session）\n${memText}` : '') +
+    (pbText ? `\n\n# 專案手冊（這個專案怎麼做事，跨 session 累積）\n${pbText}` : '') +
     skills.promptSection();
 
   const getPlanMode = config.getPlanMode || (() => false);
 
+  // 漸進式放權：已信任的工具/命令簽章跨 session 累積。
+  // 預設落地到 .xitto-kernel/<pack>/allow.json；config.allowStore=false → 不持久化（記憶體版）；給字串 → 自訂路徑。
+  const allowStore = config.allowStore === false ? memoryAllowStore()
+    : fileAllowStore(typeof config.allowStore === 'string' ? config.allowStore : join(dataDir, 'allow.json'));
+
   // 守衛鏈第 5 格：真實權限/沙箱（A 半部：靜態策略 deny/網路/提權/越界寫入 + 危險命令）。
   const permission = createPermissionStep({
     registry, getSandbox, getSandboxConfig,
     deny: pack.permissionPolicy?.deny || [],
     confirm: config.confirm,
+    store: allowStore,
+    onTrusted: config.onTrusted,
   });
 
   const guard = composeGuards({
@@ -172,8 +188,17 @@ export function createKernel(pack, config = {}) {
     systemPrompt,
     services,
     permissionPolicy: pack.permissionPolicy || {},
+    // 已信任清單（漸進放權）：列出 / 移除 / 全清；path 為落地檔（記憶體版為 null）。
+    permissions: {
+      list: () => allowStore.list(),
+      forget: (entry) => allowStore.remove(entry),
+      clear: () => allowStore.clear(),
+      path: allowStore.path,
+    },
     sandbox: { isOn: () => getSandbox(), config: () => getSandboxConfig() },
     memory,
+    // 專案手冊（程序層沉澱）：列出 / 更新 / 移除 / 全清；path 為落地檔。
+    playbook: { list: playbook.list, update: playbook.update, remove: playbook.remove, clear: playbook.clear, load: playbook.load, path: join(dataDir, 'playbook.md') },
     todo: { get: todo.get },
     /** 撤銷上一次檔案改動（write/edit）：還原內容，新建的檔則刪除。 */
     undo: () => {

package/src/kernel/playbook.js

@@ -0,0 +1,89 @@
+// 專案手冊（程序層沉澱）— kernel 內建。agent 執行中把「這個專案怎麼做事」沉澱下來,跨 session 自動載入。
+// 與 memory 的分工：memory 存「事實/偏好/決策」(扁平一行一條)；playbook 存「可重複的程序知識」
+// (建置/測試/部署指令、慣例、必經步驟、踩過的坑與修法),按 topic 組織、同 topic 覆蓋(天然去重)。
+// 落地到 <cwd>/.xitto-kernel/<pack>/playbook.md → 因綁 cwd,天然只對「這個專案」生效(自帶相關性範圍)。
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+const HEADER = '# 專案手冊';
+
+// 解析：以 `## <topic>` 分節,標題下方至下一個 `##` 為 note。
+function parse(md) {
+  if (!md) return [];
+  const entries = [];
+  for (const block of md.split(/\n(?=##\s)/)) {
+    const m = block.match(/^##\s+(.+?)(?:\n([\s\S]*))?$/);
+    if (!m) continue;
+    const topic = m[1].trim();
+    const note = (m[2] || '').trim();
+    if (topic) entries.push({ topic, note });
+  }
+  return entries;
+}
+
+function serialize(entries) {
+  return HEADER + '\n\n' + entries.map((e) => `## ${e.topic}\n${e.note}`).join('\n\n') + '\n';
+}
+
+/**
+ * @param {string} file  手冊檔路徑（如 <cwd>/.xitto-kernel/<pack>/playbook.md）
+ */
+export function createPlaybook(file) {
+  const read = () => (existsSync(file) ? readFileSync(file, 'utf8') : '');
+  const list = () => parse(read());
+  const load = () => read().trim();
+
+  const writeEntries = (entries) => {
+    if (!entries.length) { try { if (existsSync(file)) unlinkSync(file); } catch { /* 略 */ } return; }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, serialize(entries));
+  };
+
+  const update = (topic, note) => {
+    const t = String(topic || '').trim();
+    const n = String(note || '').trim();
+    if (!t) return { error: 'topic 不可為空' };
+    if (!n) return { error: 'note 不可為空' };
+    const entries = list();
+    const i = entries.findIndex((e) => e.topic.toLowerCase() === t.toLowerCase());
+    if (i >= 0) {
+      if (entries[i].note === n) return { skipped: true, topic: entries[i].topic };
+      entries[i] = { topic: entries[i].topic, note: n }; // 保留原始大小寫,只換內容
+      writeEntries(entries);
+      return { updated: entries[i].topic };
+    }
+    entries.push({ topic: t, note: n });
+    writeEntries(entries);
+    return { added: t };
+  };
+
+  const remove = (topic) => {
+    const t = String(topic || '').trim().toLowerCase();
+    const entries = list();
+    const kept = entries.filter((e) => e.topic.toLowerCase() !== t);
+    if (kept.length === entries.length) return { error: '找不到主題', topic };
+    writeEntries(kept);
+    return { removed: topic };
+  };
+
+  const clear = () => { const n = list().length; writeEntries([]); return { cleared: n }; };
+
+  // playbook_* 只動 kernel 自己的手冊檔（agent 簿記）,標 readOnly → 守衛鏈自動放行
+  const tools = [
+    {
+      name: 'playbook_update', label: '記專案手冊', readOnly: true,
+      description: '把這個專案的「做事方法」(程序知識)記下來或更新:建置/測試/執行/部署指令、專案慣例、必經步驟、踩過的坑與修法。按 topic 組織,同 topic 會覆蓋(避免重複)。下次 session 自動載入,省得重新摸索。與 memory 的差別:memory 存事實/偏好/決策,playbook 存可重複的程序步驟。',
+      parameters: { type: 'object', properties: { topic: { type: 'string', description: '主題,如「測試」「建置」「部署地雷」' }, note: { type: 'string', description: '具體做法/步驟/注意事項' } }, required: ['topic', 'note'] },
+      execute: async (_id, { topic, note }) => txt(update(topic, note)),
+    },
+    {
+      name: 'playbook_remove', label: '清專案手冊', readOnly: true,
+      description: '移除一條過時的專案手冊條目(按 topic)。手冊內容過時或錯誤時清掉,避免誤導未來的 session。',
+      parameters: { type: 'object', properties: { topic: { type: 'string' } }, required: ['topic'] },
+      execute: async (_id, { topic }) => txt(remove(topic)),
+    },
+  ];
+
+  return { load, list, update, remove, clear, tools };
+}

package/src/kernel/security/allow-store.js

@@ -0,0 +1,40 @@
+// 漸進式放權的「已信任」儲存：記住使用者批准過的工具/命令簽章,跨 session 累積。
+// 兩種實作：memory（headless/測試,不落地）與 file（落地到 .xitto-kernel/<pack>/allow.json）。
+// 格式與細粒度簽章見 allow.js（parseAllowFile / serializeAllow / commandSignature）。
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseAllowFile, serializeAllow } from './allow.js';
+
+function makeStore(seed, flush, path) {
+  const tools = new Set(seed.tools || []);
+  const bash = new Set(seed.bash || []);
+  const save = () => flush?.(tools, bash);
+  return {
+    path: path || null,
+    hasTool: (n) => tools.has(n),
+    hasSig: (s) => bash.has(s),
+    addTool: (n) => { if (!tools.has(n)) { tools.add(n); save(); } },
+    addSig: (s) => { if (s && !bash.has(s)) { bash.add(s); save(); } },
+    // forget：可傳工具名或 bash 簽章；回傳是否真的移除了
+    remove: (entry) => { const a = tools.delete(entry); const b = bash.delete(entry); if (a || b) save(); return a || b; },
+    clear: () => { const had = tools.size + bash.size > 0; tools.clear(); bash.clear(); if (had) save(); return had; },
+    list: () => ({ tools: [...tools], bash: [...bash] }),
+    size: () => tools.size + bash.size,
+  };
+}
+
+// 記憶體版：session 內有效,重啟即忘（headless / 測試 / 明確關閉持久化時）。
+export function memoryAllowStore(seed = {}) {
+  return makeStore(seed, null, null);
+}
+
+// 檔案版：啟動時載入既有信任,每次變更立即落地。重啟後信任仍在 → 漸進累積。
+export function fileAllowStore(path) {
+  let parsed = { tools: [], bash: [] };
+  try { if (existsSync(path)) parsed = parseAllowFile(JSON.parse(readFileSync(path, 'utf8'))); } catch { /* 壞檔忽略,當空 */ }
+  const flush = (tools, bash) => {
+    try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, serializeAllow(tools, bash) + '\n'); }
+    catch { /* 落地失敗不影響本回合放行 */ }
+  };
+  return makeStore(parsed, flush, path);
+}

package/src/kernel/security/permission-step.js

@@ -5,6 +5,7 @@
 import { sandboxViolation } from './sandbox.js';
 import { dangerousReason } from './danger.js';
 import { commandSignature } from './allow.js';
+import { memoryAllowStore } from './allow-store.js';
 
 /**
  * @param {Object} o
@@ -12,14 +13,15 @@ import { commandSignature } from './allow.js';
  * @param {() => boolean} [o.getSandbox]                沙箱是否開啟
  * @param {() => object} [o.getSandboxConfig]           沙箱策略（blockNetwork/allowWritePrefixes）
  * @param {string[]} [o.deny]                           禁止的工具名 / "bash:<簽章>"
- * @param {(name: string, args: object, danger: string|null) => Promise<'yes'|'no'|'always'|'command'>} [o.confirm]
+ * @param {object} [o.store]                            已信任儲存（漸進放權,跨 session）；預設記憶體版
+ * @param {(name: string, args: object, danger: string|null, meta: {signature?: string}) => Promise<'yes'|'no'|'always'|'command'>} [o.confirm]
  *        互動確認；不提供（headless）時：危險命令一律擋、其餘放行（沙箱靜態違規仍先擋）。
+ * @param {(info: {name: string, signature: string|null, scope: 'tool'|'command'}) => void} [o.onTrusted]
+ *        從已信任儲存自動放行時通知（讓 app 顯示「已信任」,維持可理解性）。
  * @returns {(ctx: { name: string, args: object }) => Promise<import('../../types.js').PolicyDecision>}
  */
-export function createPermissionStep({ registry, getSandbox, getSandboxConfig, deny = [], confirm }) {
+export function createPermissionStep({ registry, getSandbox, getSandboxConfig, deny = [], confirm, store = memoryAllowStore(), onTrusted }) {
   const denySet = new Set(deny);
-  const allowedSignatures = new Set(); // session 內「允許此命令簽章全部」
-  const alwaysTools = new Set();       // session 內「允許此工具全部」（使用者選 always）
 
   return async function permission(ctx) {
     const name = ctx.name;
@@ -45,18 +47,19 @@ export function createPermissionStep({ registry, getSandbox, getSandboxConfig, d
     // 3) 危險命令：即使 always-allow / 無 confirm 也強制把關（headless 直接擋）
     const danger = isShell ? dangerousReason(cmd) : null;
 
-    // 4) 非危險：本工具/命令簽章已 always-allow → 直接過；headless（無 confirm）→ 放行
+    // 4) 非危險：已信任（本工具 or 命令簽章）→ 直接過；headless（無 confirm）→ 放行
     if (!danger) {
-      if (alwaysTools.has(name) || (sig && allowedSignatures.has(sig))) return undefined;
+      if (store.hasTool(name)) { onTrusted?.({ name, signature: null, scope: 'tool' }); return undefined; }
+      if (sig && store.hasSig(sig)) { onTrusted?.({ name, signature: sig, scope: 'command' }); return undefined; }
       if (!confirm) return undefined;
     } else if (!confirm) {
       return { block: true, reason: `偵測到危險命令（${danger}），headless 模式下拒絕執行。` };
     }
 
-    // 5) 互動確認（危險命令即使選 always 也只放行這次，不永久放行）
-    const decision = await confirm(name, ctx.args, danger);
-    if (decision === 'always' && !danger) { alwaysTools.add(name); return undefined; }
-    if (decision === 'command' && sig && !danger) { allowedSignatures.add(sig); return undefined; }
+    // 5) 互動確認（危險命令即使選 always 也只放行這次,不寫入信任）
+    const decision = await confirm(name, ctx.args, danger, { signature: sig || null });
+    if (decision === 'always' && !danger) { store.addTool(name); return undefined; }
+    if (decision === 'command' && sig && !danger) { store.addSig(sig); return undefined; }
     if (decision === 'yes') return undefined;
     return { block: true, reason: `使用者拒絕執行 ${name}。` };
   };