xitto-kernel 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## 0.2.0
+
+第一個功能完整版 —— 從 0.1.0（基礎 kernel + CLI + 腳手架）補齊近乎 xitto-code 等價的能力，
+並加入通用自主 agent。
+
+### 新增
+
+- **記憶 + session resume**：`memory_save`/`memory_list` 工具自動注入；`--resume [id]`、`/sessions`、`/resume`、`/memory`
+- **互動權限確認**：mutating/危險工具執行前彈確認（y/a/n）；`always` 記住；`--yes`/`/auto` 自動核准（危險仍把關）
+- **計劃模式 + 撤銷**：`/plan`（只規劃、擋 mutating）、`/undo`（還原上次 write/edit）
+- **git 能力**（coding pack）：`git_status` / `git_diff` / `git_log` / `git_commit`
+- **子 agent**：`spawn_agent` 派唯讀子 agent 做聚焦調查
+- **hooks**：PreToolUse / PostToolUse（`.xitto-kernel/<pack>/settings.json`）
+- **skills**：漸進揭露（`.xitto-kernel/<pack>/skills/*.md` + `skill` 工具）
+- **MCP**：連 MCP server（stdio），工具以 `mcp__<server>__<tool>` 注入
+- **回合內上下文壓縮**：逼近視窗時摘要較舊對話、保留最近
+- **輕量串流 markdown 渲染** + edit/write 彩色 diff（CLI）
+- **通用自主 agent**：`general` pack（檔案/shell/`web_fetch`/`web_search`）+ **goal loop**
+  （`runGoal` / `--goal "..."` / `/goal`：給目標、反覆做到完成、LLM 自我驗收）
+- **code agent 工具升級（達 Claude Code 等級）**：
+  - `grep`（正則搜內容、`path:line`、glob 過濾）、`glob`（`**` 遞迴找檔）
+  - `read` 附行號 + `offset`/`limit`；`edit` 唯一性檢查 + `replaceAll`（避免改錯位置）
+  - `bash` timeout 參數；`bash_bg` / `bash_output` / `bash_kill`（後台 dev server/watch）
+  - `web_fetch`（coding pack 也能查線上文件）
+  - **TodoWrite**（`todo_write`）：多步任務規劃/追蹤，CLI 即時清單渲染（☐/◐/☑）
+
+### 變更
+
+- `new-agent` 產出的專案預設依賴 `^<version>`（正式版本），`--local` 用 `file:` 開發
+- pack.verify / pack.contextFiles slot 接通 runtime
+
+### 修正
+
+- test script 改 `node --test`（Node 20 不支援 `--test` glob）
+- goal loop 驗收健壯性：寬鬆 JSON 解析 + 連續失敗停止
+
+## 0.1.0
+
+首發：kernel（pack 系統 / 工具 metadata / 守衛鏈 / agent loop / 真實 sandbox(Seatbelt)）、
+互動 CLI、腳手架（`new-agent` 產出獨立專案）、三個範例 pack（coding / data-query / notes）。

package/README.md

@@ -1,5 +1,6 @@
 # xitto-kernel
 
+[![npm](https://img.shields.io/npm/v/xitto-kernel.svg)](https://www.npmjs.com/package/xitto-kernel)
 [![CI](https://github.com/ishoplus/xitto-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/ishoplus/xitto-kernel/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
@@ -27,13 +28,11 @@ xitto-code 經掃描後，約 **8 成已是領域無關的 kernel**；真正跟
 - `~/.xitto-code/providers.json` —— LLM provider 設定（與 xitto-code 共用，內含 API key）。
   沒有的話，複製一份填入 key 即可（格式見 xitto-code 的 `providers.example.json`）。
 
-**一次性設定**（讓 `xitto-kernel` 成為全域命令）
+**安裝**（已發佈 npm）
 ```bash
-cd xitto-kernel
-npm install
-npm link            # 之後任何目錄都能用 xitto-kernel 命令
+npm install -g xitto-kernel    # 全域命令 xitto-kernel
 ```
-> 不想 link 也行：直接 `node /路徑/xitto-kernel/bin/xitto-kernel.js …` 或在 repo 內 `npm start`。
+> 開發本倉庫：`cd xitto-kernel && npm install && npm link`。
 
 **跑內建 pack（互動 CLI）**
 ```bash
@@ -43,7 +42,13 @@ xitto-kernel --pack data-query
 xitto-kernel --sandbox        # 啟動就開 Seatbelt 沙箱
 ```
 
-**CLI 內操作**：直接打需求（模型會自己呼叫工具）；指令 `/help` `/sandbox [on|off]` `/tools` `/clear` `/exit`；`Ctrl+C` 中斷該輪、閒置時再按一次離開。
+**CLI 內操作**：直接打需求（模型會自己呼叫工具）；指令 `/help` `/goal <目標>` `/sandbox` `/plan` `/undo` `/tools` `/memory` `/sessions` `/resume` `/exit`；`Ctrl+C` 中斷該輪、閒置時再按一次離開。
+
+**通用自主 agent（給目標、自己做到完成）**
+```bash
+xitto-kernel --pack general --yes --goal "抓取 example.com 摘要成繁中寫進 summary.txt"
+```
+`general` pack（檔案/shell/web_fetch）+ kernel 的 **goal loop**（反覆 runTurn + LLM 自我驗收，直到達成/無進展/上限）。互動模式用 `/goal <目標>`。
 
 ## 做你自己的領域 agent（不固化）
 
@@ -93,9 +98,10 @@ xitto-kernel/
 │   │   ├── templates/            ✅ 獨立專案樣板（package.json/index.js/pack.js…）
 │   │   └── providers.js          ✅ providers.json 載入（provider 設定屬 app，非 kernel）
 │   └── packs/
-│       ├── coding/               ✅ 參考 pack（read/ls/write/edit/bash 真實工具）
+│       ├── coding/               ✅ 參考 pack（read/ls/write/edit/bash/git）
 │       ├── data-query/           ✅ 第二領域（證明正交）
-│       └── notes/                ✅ 第三領域（知識庫；示範「怎麼做新領域 agent」）
+│       ├── notes/                ✅ 第三領域（知識庫）
+│       └── general/              ✅ 通用自主 agent（檔案/shell/web_fetch + goal loop）
 ├── bin/xitto-kernel.js           ✅ CLI 進入點（run / new-agent）
 ├── test/                         ✅ 41 測試全綠（runTurn + Seatbelt 隔離 + 腳手架 + …）
 └── examples/
@@ -127,7 +133,8 @@ xitto-kernel/
 **git 能力**（coding pack）、**spawn_agent 子 agent**、**PreToolUse/PostToolUse hooks**、
 **skills 漸進揭露**、**MCP 工具接入**、互動 CLI、腳手架（`new-agent` 產出獨立專案）。75 測試全綠。
 
-**仍為接縫（後續）**：發佈到 npm（讓 `file:` 依賴變正式版本；版本已備 0.1.0）。Ink 全功能 TUI 可作為另一個 app（目前 CLI 已有輕量串流 markdown + 彩色 diff）。
+**已發佈 npm**：`npm install -g xitto-kernel`；`new-agent` 產出的專案預設依賴 `^0.1.0`（`--local` 用 file: 開發）。
+**可選後續**：Ink 全功能 TUI 可作為另一個 app（目前 CLI 已有輕量串流 markdown + 彩色 diff）。
 
 **設計取向**：沿用 Node ESM + pi-ai provider 抽象；不重寫 xitto-code（kernel 是抽象，xitto-code 仍可獨立存在）。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xitto-kernel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "領域無關的 agent 底座（kernel + 可插拔 DomainPack），從 xitto-code 抽象而來",
   "keywords": [
@@ -34,7 +34,8 @@
     "bin",
     "docs",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test",

package/src/app/cli.js

@@ -96,6 +96,14 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
       }
       case 'tool_execution_start':
         endStream();
+        if (ev.toolName === 'todo_write' && Array.isArray(ev.args?.todos)) {
+          out(c.cyan('☑ 待辦更新\n'));
+          for (const t of ev.args.todos) {
+            const mark = t.status === 'completed' ? c.green('☑') : t.status === 'in_progress' ? c.yellow('◐') : c.gray('☐');
+            out(`  ${mark} ${t.status === 'completed' ? c.gray(t.content) : t.content}\n`);
+          }
+          break;
+        }
         out(c.yellow('⚙ ' + ev.toolName) + c.gray('(' + summarize(ev.args) + ')\n'));
         diffPreview(ev.toolName, ev.args);
         break;
@@ -130,6 +138,7 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
           '  /sandbox [on|off] 切換沙箱（macOS=Seatbelt 真隔離）',
           '  /auto [on|off]    自動核准 mutating 工具（危險命令仍把關）',
           '  /plan [on|off]    計劃模式（只規劃、擋下實際改動）',
+          '  /goal <目標>      目標驅動自主循環（反覆做到完成）',
           '  /undo            撤銷上一次檔案改動（write/edit）',
           '  /tools           列出此 pack 的工具',
           '  /memory          顯示跨 session 記憶',
@@ -218,6 +227,25 @@ export function runCli({ pack, model, getApiKey, sandbox = false, resume = null,
     q(c.blue('› '), async (raw) => {
       const input = (raw || '').trim();
       if (!input) return loop();
+      // /goal <目標>：目標驅動自主循環（在此 await，避免與下一個提示交錯）
+      if (input.startsWith('/goal ') || input === '/goal') {
+        const goal = input.slice(5).trim();
+        if (!goal) { out(c.gray('用法 /goal <目標>\n')); return loop(); }
+        try {
+          out(c.cyan('🎯 目標：') + goal + '\n');
+          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`)),
+            onEvent, onAgent: (a) => { currentAgent = a; },
+          });
+          endStream(); history = r.history; persist();
+          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'); }
+        finally { currentAgent = null; }
+        out('\n'); return loop();
+      }
       if (handleSlash(input)) return loop();
       try {
         const text = planMode

package/src/app/main.js

@@ -4,28 +4,32 @@ import { join } from 'node:path';
 import { loadModel } from './providers.js';
 import { runCli } from './cli.js';
 import { newAgent } from './scaffold.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';
 
 const e = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
-const green = e(32); const gray = e(90); const red = e(31);
+const green = e(32); const gray = e(90); const red = e(31); const cyan = e(36); const yellow = e(33);
 
 const PACKS = {
   coding: createCodingPack,
   'data-query': createDataQueryPack,
   notes: createNotesPack,
+  general: createGeneralPack,
 };
 
 export async function main(argv = process.argv.slice(2)) {
   // 子指令：new-agent <name> —— 產出獨立 agent 專案（不碰 kernel）
   if (argv[0] === 'new-agent') {
-    const name = argv[1];
+    const name = argv.find((a, i) => i >= 1 && !a.startsWith('--'));
+    const local = argv.includes('--local');
     try {
-      const { target, files } = newAgent(name);
+      const { target, files, dep } = newAgent(name, { local });
       console.log(green(`✓ 已建立獨立 agent 專案：${target}`));
-      console.log(gray(`  ${files.join('  ')}`));
+      console.log(gray(`  ${files.join('  ')}  ·  依賴 xitto-kernel@${dep}`));
       console.log('\n下一步：');
       console.log(gray(`  cd ${name} && npm install && npm start`));
       console.log(gray('  （改 pack.js 換成你的領域；npm update xitto-kernel 升級底座，不固化）'));
@@ -47,6 +51,28 @@ export async function main(argv = process.argv.slice(2)) {
   const cwd = process.cwd();
   const mcp = await loadMcpTools(join(cwd, '.xitto-kernel', opts.pack, 'mcp.json'), (m) => console.log(gray(`  [MCP] ${m}`)));
 
+  // --goal "..."：headless 自主循環（給目標、自己做到完成）後退出，不進互動 CLI
+  if (opts.goal) {
+    const kernel = createKernel(make({ cwd }), {
+      model, getApiKey, extraTools: mcp.tools,
+      sandbox: { enabled: opts.sandbox }, getSandbox: () => opts.sandbox,
+      confirm: opts.yes ? (async () => 'yes') : undefined, // headless：--yes 才自動核准 mutating
+    });
+    console.log(cyan('🎯 目標：') + opts.goal + gray(`  ·  ${opts.pack} pack · ${model.id}`));
+    const res = await kernel.runGoal(opts.goal, {
+      onRound: ({ round, maxRounds }) => console.log(yellow(`\n🔁 第 ${round}/${maxRounds} 輪`)),
+      onCheck: ({ done, remaining }) => console.log(done ? green('  ✓ 驗收：已達成') : gray(`  ↻ 驗收：${remaining}`)),
+      onEvent: (ev) => {
+        if (ev.type === 'tool_execution_start') console.log(yellow(`  ⚙ ${ev.toolName}`) + gray('(' + JSON.stringify(ev.args).slice(0, 80) + ')'));
+        if (ev.type === 'tool_execution_end') console.log(ev.isError ? red('    ⎿ ✗') : gray('    ⎿ ✓'));
+      },
+    });
+    const why = res.stalled ? '無進展停止' : res.aborted ? '中斷' : res.verifyBroken ? '驗收持續失敗' : '到上限';
+    console.log('\n' + (res.done ? green(`✅ 目標達成（${res.rounds} 輪）`) : yellow(`⚠ 未達成（${why}，${res.rounds} 輪）`)));
+    try { await mcp.close(); } catch { /* 略 */ }
+    process.exit(res.done ? 0 : 1);
+  }
+
   runCli({
     pack: make({ cwd }), model, getApiKey,
     sandbox: opts.sandbox, resume: opts.resume, auto: opts.yes,
@@ -55,7 +81,7 @@ export async function main(argv = process.argv.slice(2)) {
 }
 
 function parse(argv) {
-  const o = { pack: 'coding', model: undefined, sandbox: false, help: false, resume: null, yes: false };
+  const o = { pack: 'coding', model: undefined, sandbox: false, help: false, resume: null, yes: false, goal: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--help' || a === '-h') o.help = true;
@@ -63,6 +89,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 === '--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; }
   }
   return o;
@@ -74,9 +101,11 @@ function printHelp() {
     '',
     '用法:',
     '  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；預設 coding）',
+    '  --pack <name>   選擇內建 DomainPack（coding | data-query | notes | general；預設 coding）',
+    '  --goal "..."    給目標，agent 自主反覆做到完成（建議搭配 --pack general）',
     '  --model <id>    指定 model（預設用 providers.json 的 defaultModel）',
     '  --sandbox       啟動即開啟沙箱（macOS=Seatbelt 真隔離）',
     '  --help          顯示說明',

package/src/app/scaffold.js

@@ -17,24 +17,32 @@ const FILES = [
   ['gitignore.tmpl', '.gitignore'],
 ];
 
+const kernelVersion = () => {
+  try { return JSON.parse(readFileSync(join(KERNEL_ROOT, 'package.json'), 'utf8')).version || '0.1.0'; }
+  catch { return '0.1.0'; }
+};
+
 /**
  * 產生一個獨立 agent 專案。
  * @param {string} name                    agent 名（字母/數字/連字號）
- * @param {{ dir?: string, kernelPath?: string }} [opts]
- *        dir：產出根目錄（預設 cwd）；kernelPath：寫進 package.json 的 file: 依賴路徑（預設此 kernel）
- * @returns {{ target: string, files: string[] }}
+ * @param {{ dir?: string, local?: boolean, kernelPath?: string }} [opts]
+ *        dir：產出根目錄（預設 cwd）；local：用 file: 依賴本機 kernel（開發用，預設用 npm 正式版本）
+ * @returns {{ target: string, files: string[], dep: string }}
  */
-export function newAgent(name, { dir = process.cwd(), kernelPath = KERNEL_ROOT } = {}) {
+export function newAgent(name, { dir = process.cwd(), local = false, 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}`);
 
+  // 依賴：預設用 npm 正式版本（^x.y.z）；--local 用 file: 指向本機 kernel（開發測試用）
+  const dep = local ? `file:${kernelPath}` : `^${kernelVersion()}`;
+
   mkdirSync(target, { recursive: true });
-  const subst = (s) => s.replaceAll('__NAME__', name).replaceAll('__KERNEL_PATH__', kernelPath);
+  const subst = (s) => s.replaceAll('__NAME__', name).replaceAll('__KERNEL_DEP__', dep);
   for (const [tmpl, outName] of FILES) {
     writeFileSync(join(target, outName), subst(readFileSync(join(TEMPLATES, tmpl), 'utf8')));
   }
-  return { target, files: FILES.map(([, o]) => o) };
+  return { target, files: FILES.map(([, o]) => o), dep };
 }

package/src/app/templates/package.json.tmpl

@@ -7,6 +7,6 @@
     "start": "node index.js"
   },
   "dependencies": {
-    "xitto-kernel": "file:__KERNEL_PATH__"
+    "xitto-kernel": "__KERNEL_DEP__"
   }
 }

package/src/kernel/bg.js

@@ -0,0 +1,70 @@
+// 後台進程 — bash_bg / bash_output / bash_kill。對標 Claude Code 的 run_in_background + BashOutput + KillShell。
+// 讓 agent 啟動 dev server / watch / build 而不阻塞對話。輸出緩衝在記憶體（上限裁切前段）。
+import { spawn } from 'node:child_process';
+
+const OUTPUT_CAP = 256 * 1024;
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+// 全域只註冊一次 process 退出清理（避免每個 pack 各註冊造成 listener 洩漏）
+const cleanups = new Set();
+let registered = false;
+const ensureCleanup = () => { if (registered) return; registered = true; const run = () => { for (const c of cleanups) try { c(); } catch { /* 略 */ } }; process.once('exit', run); process.once('SIGTERM', run); };
+
+export function createBackgroundTools(cwd) {
+  const procs = new Map();
+  let seq = 0;
+  const append = (proc, d) => {
+    proc.buf += d.toString();
+    if (proc.buf.length > OUTPUT_CAP) { const drop = proc.buf.length - OUTPUT_CAP; proc.buf = proc.buf.slice(drop); proc.readPos = Math.max(0, proc.readPos - drop); proc.truncated = true; }
+  };
+  const killAll = () => { for (const p of procs.values()) if (p.status === 'running') { try { p.child?.kill('SIGTERM'); } catch { /* 略 */ } } };
+  cleanups.add(killAll); ensureCleanup();
+
+  const bashBg = {
+    name: 'bash_bg', label: '後台執行', mutating: true, sandboxable: true,
+    description: '在後台啟動長時間/常駐命令（dev server、watch、build），立即回傳 id 不阻塞。之後 bash_output 讀新輸出、bash_kill 終止。一次性快命令用一般 bash。',
+    parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+    execute: async (_id, { command }) => {
+      const cmd = (command || '').trim();
+      if (!cmd) return txt({ error: 'command 不可為空' });
+      const id = 'bg' + (++seq);
+      const proc = { id, command: cmd, status: 'running', exitCode: null, buf: '', readPos: 0, truncated: false };
+      let child;
+      try { child = spawn(cmd, { shell: true, cwd, stdio: ['ignore', 'pipe', 'pipe'] }); }
+      catch (e) { proc.status = 'error'; proc.error = e.message; procs.set(id, proc); return txt({ error: e.message }); }
+      proc.child = child;
+      child.stdout?.on('data', (d) => append(proc, d));
+      child.stderr?.on('data', (d) => append(proc, d));
+      child.on('exit', (code) => { proc.status = 'exited'; proc.exitCode = code; });
+      child.on('error', (e) => { proc.status = 'error'; proc.error = e.message; });
+      procs.set(id, proc);
+      return txt({ id, status: 'running', hint: `bash_output("${id}") 讀輸出、bash_kill("${id}") 終止` });
+    },
+  };
+
+  const bashOutput = {
+    name: 'bash_output', label: '讀後台輸出', readOnly: true,
+    description: '讀取某後台進程（bash_bg 啟動）自上次以來的新輸出與狀態（running/exited/error）。',
+    parameters: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+    execute: async (_id, { id }) => {
+      const p = procs.get(id);
+      if (!p) return txt({ error: `找不到後台進程 ${id}` });
+      const out = p.buf.slice(p.readPos); p.readPos = p.buf.length;
+      return txt({ id, status: p.status, exitCode: p.exitCode, ...(p.error ? { error: p.error } : {}), ...(p.truncated ? { truncatedFront: true } : {}), output: out });
+    },
+  };
+
+  const bashKill = {
+    name: 'bash_kill', label: '終止後台', readOnly: true,
+    description: '終止一個仍在運行的後台進程（bash_bg 啟動的）。',
+    parameters: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+    execute: async (_id, { id }) => {
+      const p = procs.get(id);
+      if (!p) return txt({ error: `找不到後台進程 ${id}` });
+      if (p.status !== 'running') return txt({ id, status: p.status, note: '進程已結束' });
+      try { p.child?.kill('SIGTERM'); return txt({ id, killed: true }); } catch (e) { return txt({ id, error: e.message }); }
+    },
+  };
+
+  return { tools: [bashBg, bashOutput, bashKill], killAll };
+}

package/src/kernel/goal-loop.js

@@ -0,0 +1,34 @@
+// 目標驅動自主循環 — kernel 內建（領域無關）。給目標 → 反覆 runTurn + LLM 自我驗收，
+// 直到達成 / 到上限 / 無進展。對標 xitto-code 的 /loop。checkGoal 用 LLM 判斷是否完成。
+import { completeSimple } from '@mariozechner/pi-ai';
+import { cacheRetentionFor } from './provider.js';
+
+const JUDGE_SYS = '你是嚴格的驗收員。依「目標」與「對話進展」判斷目標是否已達成。' +
+  '只輸出 JSON：{"done": true|false, "remaining": "若未達成，還差什麼（一句）"}。不要任何多餘文字。';
+
+const asText = (m) => (Array.isArray(m.content) ? m.content.filter((c) => c.type === 'text').map((c) => c.text).join(' ') : String(m?.content || ''));
+
+export function normalizeFeedback(s) { return String(s || '').toLowerCase().replace(/\s+/g, ' ').trim(); }
+
+/**
+ * 用 LLM 判斷目標是否達成。回 { done, remaining, error? }；任何失敗都保守回 done:false（續跑）。
+ */
+export async function checkGoal(goal, messages, model, apiKey, signal) {
+  if (!apiKey) return { done: false, remaining: '(無 API key)', error: true };
+  const recent = messages.slice(-8).map((m) => `${m.role}: ${asText(m).slice(0, 800)}`).join('\n').slice(0, 6000);
+  const ctx = {
+    systemPrompt: JUDGE_SYS,
+    messages: [{ role: 'user', content: [{ type: 'text', text: `目標：\n${goal}\n\n對話進展：\n${recent}\n\n是否已達成？只輸出 JSON。` }], timestamp: Date.now() }],
+  };
+  try {
+    const res = await completeSimple(model, ctx, { maxTokens: 220, apiKey, signal, cacheRetention: cacheRetentionFor(model) });
+    if (res.stopReason === 'error') return { done: false, remaining: '(驗收呼叫失敗)', error: true };
+    const t = res.content.filter((c) => c.type === 'text').map((c) => c.text).join('');
+    // 寬鬆解析：先試 JSON；失敗再用關鍵字判斷完成訊號（MiniMax 等 JSON 輸出不一定乾淨）
+    const m = t.match(/\{[\s\S]*\}/);
+    if (m) { try { const o = JSON.parse(m[0]); return { done: !!o.done, remaining: String(o.remaining || '') }; } catch { /* 落到下方 fallback */ } }
+    if (/"?done"?\s*[:=]\s*true|已達成|已完成|目標(已)?達成/i.test(t)) return { done: true, remaining: '' };
+    if (/"?done"?\s*[:=]\s*false|尚未|未達成|還(需|要|差)/i.test(t)) return { done: false, remaining: t.slice(0, 200) };
+    return { done: false, remaining: '(驗收輸出無法解析)', error: true };
+  } catch (e) { return { done: false, remaining: `(驗收例外:${e?.message || e})`, error: true }; }
+}

package/src/kernel/index.js

@@ -10,10 +10,12 @@ import { composeGuards } from './guard-chain.js';
 import { createPermissionStep } from './security/permission-step.js';
 import { normalizeSandbox, wrapWithSeatbelt } from './security/sandbox.js';
 import { createMemory } from './memory.js';
+import { createTodo } from './todo.js';
 import { createSpawnTool } from './subagent.js';
 import { createSkills } from './skills.js';
 import { loadHooks, runPreToolHooks, runPostToolHooks } from './hooks.js';
 import { maybeCompact, resolveCompactionSettings } from './compaction.js';
+import { checkGoal, normalizeFeedback } from './goal-loop.js';
 import { newSessionId, saveSession, loadSession, listSessions, latestSession } from './session.js';
 
 // 載入 pack.contextFiles：從 cwd 逐層往上找每個檔名，找到就讀入並注入 system prompt（領域規範）。
@@ -98,6 +100,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 todo = createTodo();
   const sessionsDir = join(dataDir, 'sessions');
   const hooks = loadHooks(join(dataDir, 'settings.json')); // PreToolUse/PostToolUse
   const skills = createSkills(join(dataDir, 'skills'));     // 漸進揭露技能
@@ -112,6 +115,7 @@ export function createKernel(pack, config = {}) {
   const baseTools = [
     ...pack.tools().map((t) => wrapUndo(wrapSandboxable(t, { cwd, getSandbox, getSandboxConfig }), { cwd, undoStack })),
     ...memory.tools,
+    todo.tool,
     ...(skills.tool ? [skills.tool] : []),
     ...(config.extraTools || []),  // 外部注入（MCP 工具等）：由 app 層先 async 載入再傳入
   ];
@@ -161,7 +165,7 @@ export function createKernel(pack, config = {}) {
     services,
   });
 
-  return {
+  const api = {
     pack,
     registry,
     mutatingTools,
@@ -170,6 +174,7 @@ export function createKernel(pack, config = {}) {
     permissionPolicy: pack.permissionPolicy || {},
     sandbox: { isOn: () => getSandbox(), config: () => getSandboxConfig() },
     memory,
+    todo: { get: todo.get },
     /** 撤銷上一次檔案改動（write/edit）：還原內容，新建的檔則刪除。 */
     undo: () => {
       const snap = undoStack.pop();
@@ -285,7 +290,51 @@ export function createKernel(pack, config = {}) {
       const lastAssistant = [...messages].reverse().find((m) => m.role === 'assistant');
       const text = (lastAssistant?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('');
       const aborted = lastAssistant?.stopReason === 'aborted';
-      return { text, messages, agent, aborted };
+      return { text, messages, agent, aborted, turnModified };
+    },
+
+    /**
+     * 目標驅動自主循環：反覆 runTurn + LLM 自我驗收，直到達成 / 到上限 / 連續無進展。
+     * @param {string} goal
+     * @param {{ maxRounds?: number, history?: object[], onRound?, onCheck?, onEvent?, onAgent?, signal? }} [opts]
+     * @returns {Promise<{ done: boolean, rounds: number, history: object[], stalled?: boolean, aborted?: boolean }>}
+     */
+    runGoal: async (goal, opts = {}) => {
+      if (!config.model) throw new Error('runGoal 需要 config.model。');
+      const maxRounds = opts.maxRounds || 12;
+      const NO_PROGRESS_CAP = 3;
+      let history = opts.history || [];
+      let instruction = `目標：${goal}\n\n請著手完成這個目標；可自由使用工具（讀寫檔/跑命令/抓網頁/子 agent…）。完成後簡述你做了什麼、如何驗證。`;
+      let lastRemaining = null;
+      let noProgress = 0;
+      let verifyErrors = 0;
+      for (let round = 1; round <= maxRounds; round++) {
+        opts.onRound?.({ round, maxRounds });
+        const r = await api.runTurn(instruction, { history, onEvent: opts.onEvent, onAgent: opts.onAgent });
+        history = r.messages;
+        if (r.aborted) return { done: false, aborted: true, rounds: round, history };
+        let apiKey; try { apiKey = await config.getApiKey(config.model.provider); } catch { /* 略 */ }
+        const judge = config.checkGoal || checkGoal; // 可注入自訂驗收（測試 / app 客製）
+        const v = await judge(goal, history, config.model, apiKey, opts.signal);
+        opts.onCheck?.({ round, done: v.done, remaining: v.remaining });
+        if (v.done) return { done: true, rounds: round, history };
+        noProgress = r.turnModified ? 0 : noProgress + 1;
+        if (noProgress >= NO_PROGRESS_CAP) return { done: false, stalled: true, rounds: round, history };
+        // 驗收壞掉（網路/解析）：remaining 是噪音，不拿來比對；連續壞 3 次就停（別空轉到上限）
+        if (v.error) {
+          verifyErrors += 1;
+          if (verifyErrors >= 3) return { done: false, verifyBroken: true, rounds: round, history };
+          instruction = `（驗收暫時無法判定）請繼續完成目標並自我檢查：${goal}`;
+          continue;
+        }
+        verifyErrors = 0;
+        const rem = normalizeFeedback(v.remaining);
+        if (!r.turnModified && rem && rem === lastRemaining) return { done: false, stalled: true, rounds: round, history };
+        lastRemaining = rem;
+        instruction = `目標尚未達成。驗收回饋：${v.remaining}\n請繼續完成目標：${goal}`;
+      }
+      return { done: false, maxedOut: true, rounds: maxRounds, history };
     },
   };
+  return api;
 }

package/src/kernel/todo.js

@@ -0,0 +1,31 @@
+// 任務待辦清單 — kernel 內建（對標 Claude Code 的 TodoWrite）。多步任務時規劃 + 追蹤進度，
+// 讓使用者看到 agent 在做什麼。傳入完整清單覆蓋（同 Claude Code 語意）。
+const txt = (o) => ({ content: [{ type: 'text', text: typeof o === 'string' ? o : JSON.stringify(o) }] });
+
+export function createTodo() {
+  let list = [];
+  const tool = {
+    name: 'todo_write', label: '待辦', readOnly: true,
+    description: '建立/更新任務待辦清單（傳入完整清單覆蓋）。3 步以上的任務建議用它規劃並隨進度更新狀態；'
+      + '同時最多一個 in_progress。status：pending | in_progress | completed。',
+    parameters: {
+      type: 'object',
+      properties: {
+        todos: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { content: { type: 'string' }, status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] } },
+            required: ['content', 'status'],
+          },
+        },
+      },
+      required: ['todos'],
+    },
+    execute: async (_id, { todos }) => {
+      list = Array.isArray(todos) ? todos.filter((t) => t && typeof t.content === 'string').map((t) => ({ content: t.content, status: t.status || 'pending' })) : [];
+      return txt({ ok: true, count: list.length, todos: list });
+    },
+  };
+  return { tool, get: () => list };
+}

package/src/packs/coding/index.js

@@ -5,12 +5,46 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join, relative } from 'node:path';
 import { execSync } from 'node:child_process';
+import { createBackgroundTools } from '../../kernel/bg.js';
 
 const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
 
+const IGNORE = new Set(['node_modules', '.git', '.xitto-kernel', '.xitto-code', 'dist', 'build', '.next', 'coverage']);
+
+// 遞迴收集檔案路徑（跳過 IGNORE 目錄），上限保護
+function walkFiles(dir, out, limit) {
+  if (out.length >= limit) return;
+  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (out.length >= limit) return;
+    if (e.name.startsWith('.') && e.name !== '.env') { if (IGNORE.has(e.name)) continue; }
+    if (IGNORE.has(e.name)) continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) walkFiles(full, out, limit);
+    else out.push(full);
+  }
+}
+
+// glob 樣式 → 正則（支援 ** 遞迴、* 與 ?）
+function globToRegex(pattern) {
+  let re = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') { if (pattern[i + 1] === '*') { re += '.*'; i++; if (pattern[i + 1] === '/') i++; } else re += '[^/]*'; }
+    else if (ch === '?') re += '[^/]';
+    else if ('.+^${}()|[]\\'.includes(ch)) re += '\\' + ch;
+    else re += ch;
+  }
+  return new RegExp('^' + re + '$');
+}
+
 const SYSTEM_PROMPT = [
   '你是嚴謹的編碼 agent。準則：',
+  '- 探索 codebase：用 glob 找檔、grep 搜內容、read 讀檔（附行號）。',
   '- 編輯既有檔案前必先 read 它的當前內容，不基於臆測修改。',
+  '- edit 的 oldText 要夠精確且唯一（含足夠上下文）；要全部取代用 replaceAll。',
+  '- 多步任務（3 步以上）先用 todo_write 規劃並隨進度更新。',
+  '- 長時間/常駐命令（dev server、watch）用 bash_bg 後台執行，再用 bash_output 看輸出。',
   '- 一次做一件事，改動後說明你做了什麼、如何驗證。',
   '- 破壞性操作先確認。',
   '- 要提交時：先 git_diff 看變更，再用 git_commit 寫一則簡潔、說明「為何」的 commit 訊息。',
@@ -24,15 +58,23 @@ const SYSTEM_PROMPT = [
 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 bg = createBackgroundTools(cwd); // bash_bg / bash_output / bash_kill
 
   const readTool = {
-    name: 'read', label: '讀檔', description: '讀取檔案內容', readOnly: true,
-    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
-    execute: async (_id, { path }) => {
+    name: 'read', label: '讀檔', readOnly: true,
+    description: '讀取檔案內容（每行附行號，方便對照與編輯）。大檔可用 offset(起始行,1-based)+limit(行數) 讀一段。',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, offset: { type: 'number' }, limit: { type: 'number' } }, required: ['path'] },
+    execute: async (_id, { path, offset, limit }) => {
       const p = abs(path);
       if (!existsSync(p)) return txt({ error: '檔案不存在', path });
       readFiles.add(p);
-      return txt(readFileSync(p, 'utf8'));
+      const lines = readFileSync(p, 'utf8').split('\n');
+      const start = Math.max(0, (offset || 1) - 1);
+      const count = limit && limit > 0 ? limit : 2000;
+      const slice = lines.slice(start, start + count);
+      const numbered = slice.map((l, i) => `${String(start + i + 1).padStart(6)}\t${l}`).join('\n');
+      const remain = lines.length - (start + count);
+      return txt(numbered + (remain > 0 ? `\n… 還有 ${remain} 行（用 offset=${start + count + 1} 繼續）` : ''));
     },
   };
 
@@ -58,28 +100,86 @@ export function createCodingPack({ cwd = process.cwd() } = {}) {
   };
 
   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 }) => {
+    name: 'edit', label: '編輯', mutating: true,
+    description: '把檔案中的 oldText 換成 newText。oldText 必須唯一（出現多次會失敗，請加上下文；或設 replaceAll:true 全部取代）。',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, oldText: { type: 'string' }, newText: { type: 'string' }, replaceAll: { type: 'boolean' } }, required: ['path', 'oldText', 'newText'] },
+    execute: async (_id, { path, oldText, newText, replaceAll }) => {
       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 occurrences = before.split(oldText).length - 1;
+      if (occurrences === 0) return txt({ error: 'oldText 未找到（請先 read 確認當前內容）', path });
+      if (occurrences > 1 && !replaceAll) return txt({ error: `oldText 出現 ${occurrences} 次，請提供更精確、唯一的 oldText（含上下文），或設 replaceAll:true`, path });
+      const after = replaceAll ? before.split(oldText).join(newText) : before.replace(oldText, newText);
+      writeFileSync(p, after, 'utf8');
+      return txt({ edited: path, replaced: replaceAll ? occurrences : 1 });
     },
   };
 
   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)'); }
+    name: 'bash', label: 'bash', description: '執行 shell 命令（可選 timeout 秒數，預設 120）。長時間/常駐的命令請改用 bash_bg。', mutating: true, sandboxable: true,
+    parameters: { type: 'object', properties: { command: { type: 'string' }, timeout: { type: 'number' } }, required: ['command'] },
+    execute: async (_id, { command, timeout }) => {
+      const ms = Math.min(600, Math.max(1, timeout || 120)) * 1000;
+      try { return txt(execSync(command, { cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 }) || '(no output)'); }
       catch (e) { return txt({ error: e.message, stdout: e.stdout, stderr: e.stderr }); }
     },
   };
 
+  // ── codebase 導航：grep（搜內容）+ glob（找檔）──
+  const grepTool = {
+    name: 'grep', label: '搜尋內容', readOnly: true,
+    description: '在檔案內容用正則搜尋，回 path:line:文字。可選 path(起點目錄)、glob(檔名過濾如 *.js)。自動跳過 node_modules/.git。',
+    parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' }, glob: { type: 'string' }, ignoreCase: { type: 'boolean' } }, required: ['pattern'] },
+    execute: async (_id, { pattern, path, glob, ignoreCase }) => {
+      let re; try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); } catch (e) { return txt({ error: '正則無效：' + e.message }); }
+      const base = path ? abs(path) : cwd;
+      if (!existsSync(base)) return txt({ error: '目錄不存在', path });
+      const files = []; walkFiles(base, files, 8000);
+      const gre = glob ? globToRegex(glob) : null;
+      const hits = [];
+      for (const f of files) {
+        if (gre && !gre.test(f.split('/').pop())) continue;
+        let content; try { content = readFileSync(f, 'utf8'); } catch { continue; }
+        if (content.includes('')) continue; // 跳過二進位
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (re.test(lines[i])) { hits.push(`${relative(cwd, f)}:${i + 1}: ${lines[i].trim().slice(0, 200)}`); if (hits.length >= 200) break; }
+        }
+        if (hits.length >= 200) break;
+      }
+      return txt(hits.length ? hits.join('\n') + (hits.length >= 200 ? '\n…（結果已截斷至 200）' : '') : '(無匹配)');
+    },
+  };
+
+  const globTool = {
+    name: 'glob', label: '找檔', readOnly: true,
+    description: '用萬用字元樣式找檔（** 遞迴、* ?），相對路徑比對。如 "src/**/*.js"、"**/*.test.js"。',
+    parameters: { type: 'object', properties: { pattern: { type: 'string' }, path: { type: 'string' } }, required: ['pattern'] },
+    execute: async (_id, { pattern, path }) => {
+      const base = path ? abs(path) : cwd;
+      if (!existsSync(base)) return txt({ error: '目錄不存在', path });
+      const files = []; walkFiles(base, files, 8000);
+      const re = globToRegex(pattern);
+      const matched = files.map((f) => relative(cwd, f)).filter((rel) => re.test(rel)).slice(0, 200);
+      return txt({ pattern, count: matched.length, files: matched });
+    },
+  };
+
+  const webFetch = {
+    name: 'web_fetch', label: '抓網頁', readOnly: true,
+    description: '抓取一個 URL 的內容並回傳純文字（HTML 去標籤、截斷）。查線上文件/API 用。',
+    parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+    execute: async (_id, { url }) => {
+      try {
+        const res = await fetch(url, { headers: { 'user-agent': 'Mozilla/5.0 xitto-kernel' }, signal: AbortSignal.timeout(20000) });
+        const html = await res.text();
+        const text = html.replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/&[a-z#0-9]+;/gi, ' ').replace(/\s+/g, ' ').trim().slice(0, 8000);
+        return txt({ url, status: res.status, text: text || '(空)' });
+      } catch (e) { return txt({ error: e?.message || String(e), url }); }
+    },
+  };
+
   // ── 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; } };
@@ -113,7 +213,7 @@ export function createCodingPack({ cwd = process.cwd() } = {}) {
 
   return {
     name: 'coding',
-    tools: () => [readTool, lsTool, writeTool, editTool, bashTool, gitStatus, gitDiff, gitLog, gitCommit],
+    tools: () => [readTool, lsTool, globTool, grepTool, writeTool, editTool, bashTool, ...bg.tools, webFetch, gitStatus, gitDiff, gitLog, gitCommit],
     systemPrompt: SYSTEM_PROMPT,
     contextFiles: ['CLAUDE.md', 'AGENTS.md', 'XITTO.md', '.xitto-code.md'],
     // mutatingTools 省略 → kernel 從工具 metadata 推導（write/edit/bash）

package/src/packs/general/index.js

@@ -0,0 +1,100 @@
+// general pack — 通用自主 agent。廣的 system prompt + 檔案/shell/web 工具。
+// 搭配 kernel 的 runGoal（目標循環）+ 子 agent + MCP，即為「給目標、自己做到完成」的通用 agent。
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join } 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。給你一個目標，你用工具反覆推進直到完成：',
+  '- 可讀寫檔案、跑 shell 命令、搜尋網路（web_search）、抓網頁（web_fetch）、派子 agent 做聚焦調查。',
+  '- 先想清楚步驟再動手；每步簡述你在做什麼。',
+  '- 需要外部資料：先 web_search 找來源，再 web_fetch 讀全文，不要憑空編造。',
+  '- 編輯既有檔案前先 read；破壞性/對外操作前確認。',
+  '- 完成後明確說「已完成」並總結結果與如何驗證。',
+].join('\n');
+
+export function createGeneralPack({ cwd = process.cwd() } = {}) {
+  const readFiles = new Set();
+  const abs = (p) => (isAbsolute(p) ? p : join(cwd, p));
+
+  const read = {
+    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 ls = {
+    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 write = {
+    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 edit = {
+    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 b = readFileSync(p, 'utf8'); if (!b.includes(oldText)) return txt({ error: 'oldText 未找到', path }); writeFileSync(p, b.replace(oldText, newText), 'utf8'); return txt({ edited: path }); },
+  };
+  const bash = {
+    name: 'bash', label: 'bash', description: '執行 shell 命令', mutating: true, sandboxable: true,
+    parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+    execute: async (_id, { command }) => { 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 }); } },
+  };
+  const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36';
+  const stripTags = (s) => String(s).replace(/<[^>]+>/g, '').replace(/&[a-z#0-9]+;/gi, ' ').replace(/\s+/g, ' ').trim();
+
+  const webFetch = {
+    name: 'web_fetch', label: '抓網頁', description: '抓取一個 URL 的內容並回傳純文字（HTML 去標籤、截斷）。讀某頁全文用。', readOnly: true,
+    parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+    execute: async (_id, { url }) => {
+      try {
+        const res = await fetch(url, { headers: { 'user-agent': UA }, signal: AbortSignal.timeout(20000) });
+        const html = await res.text();
+        const text = html
+          .replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ')
+          .replace(/<[^>]+>/g, ' ').replace(/&[a-z#0-9]+;/gi, ' ').replace(/\s+/g, ' ').trim().slice(0, 8000);
+        return txt({ url, status: res.status, text: text || '(空)' });
+      } catch (e) { return txt({ error: e?.message || String(e), url }); }
+    },
+  };
+
+  const webSearch = {
+    name: 'web_search', label: '網路搜尋', readOnly: true,
+    description: '用關鍵字搜尋網路，回傳前幾筆結果（標題 + URL + 摘要）。先 search 找來源，再用 web_fetch 讀全文。',
+    parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+    execute: async (_id, { query }) => {
+      try {
+        const res = await fetch('https://html.duckduckgo.com/html/?q=' + encodeURIComponent(query), { headers: { 'user-agent': UA }, signal: AbortSignal.timeout(20000) });
+        const html = await res.text();
+        const links = [...html.matchAll(/<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g)];
+        const snippets = [...html.matchAll(/class="result__snippet"[^>]*>([\s\S]*?)<\/a>/g)].map((m) => stripTags(m[1]));
+        const decode = (href) => { const u = /uddg=([^&]+)/.exec(href); return u ? decodeURIComponent(u[1]) : href; };
+        const results = links.slice(0, 6).map((m, i) => ({ title: stripTags(m[2]), url: decode(m[1]), snippet: snippets[i] || '' }));
+        return txt({ query, count: results.length, results });
+      } catch (e) { return txt({ error: e?.message || String(e), query }); }
+    },
+  };
+
+  return {
+    name: 'general',
+    tools: () => [read, ls, write, edit, bash, webFetch, webSearch],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['AGENTS.md', 'GENERAL.md'],
+    preToolPolicy: {
+      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} 再編輯。` };
+        }
+        return undefined;
+      },
+    },
+    permissionPolicy: { defaultMode: 'default' },
+  };
+}
+
+export const generalPack = createGeneralPack();