xitto-kernel 0.1.0 → 0.3.0

package/src/packs/coding/index.js

@@ -4,13 +4,19 @@
 // 對應 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';
+import { execSync, spawnSync } from 'node:child_process';
+import { createBackgroundTools } from '../../kernel/bg.js';
+import { createGrepTool, createGlobTool } from '../shared/code-nav.js';
 
 const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
 
 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 +30,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,25 +72,51 @@ 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)'); }
-      catch (e) { return txt({ error: e.message, stdout: e.stdout, stderr: e.stderr }); }
+    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;
+      // spawnSync 同時捕捉 stdout+stderr（不漏到終端，agent 也看得到錯誤輸出）
+      const r = spawnSync(command, { shell: true, cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 });
+      const output = ((r.stdout || '') + (r.stderr || '')).trim();
+      if (r.error) return txt({ error: r.error.message, output });
+      if (r.status !== 0) return txt({ error: `命令結束碼 ${r.status}`, output: output || '(no output)' });
+      return txt(output || '(no output)');
+    },
+  };
+
+  // ── codebase 導航：grep / glob（共用模組）──
+  const grepTool = createGrepTool(cwd);
+  const globTool = createGlobTool(cwd);
+
+  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 }); }
     },
   };
 
@@ -113,7 +153,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/data-query/index.js

@@ -1,66 +1,72 @@
-// data-query pack — 第二個範例領域，用來證明「同介面、kernel 零改動」。
-// 工具為示意 stub（回傳假資料），重點是六個插槽用法與 coding 完全一樣，只是內容換了。
-// 對照：schema-before-query 之於資料查詢 == read-before-edit 之於編碼（同 preToolPolicy 插槽）。
+// data-query pack — 真實資料查詢 agent（用 sqlite3 CLI，零依賴）。
+// 工具對一個 SQLite .db 跑真實 SQL；schema-before-query 守衛（對照 read-before-edit）。
 // 對應 docs/05-example-packs.md「B. data-query pack」。
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, join } from 'node:path';
 
 const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
 
+// 用 sqlite3 CLI 跑 SQL（sql 以 argv 傳入，非 shell 內插 → 無 shell 注入）
+function sqlite(dbPath, sql, opts = []) {
+  const r = spawnSync('sqlite3', [...opts, dbPath, sql], { encoding: 'utf8', timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+  if (r.error) return { error: r.error.code === 'ENOENT' ? '找不到 sqlite3 命令（請先安裝）' : r.error.message };
+  if (r.status !== 0) return { error: (r.stderr || '').trim() || `exit ${r.status}` };
+  return { out: (r.stdout || '').trim() };
+}
+
 const SYSTEM_PROMPT = [
-  '你是資料分析 agent。準則：',
+  '你是資料分析 agent，對一個 SQLite 資料庫工作。準則：',
   '- 下查詢前先用 list_tables / describe_table 了解結構。',
-  '- 破壞性 SQL（DROP/TRUNCATE/DELETE 無 WHERE）一律先確認。',
+  '- 唯讀查詢用 sql_query；寫入（INSERT/UPDATE/DELETE/建表）用 sql_exec。',
+  '- 破壞性 SQL（DROP/TRUNCATE/無 WHERE 的 DELETE）先確認。',
+  '- 回答問題時根據真實查詢結果，不要臆測數字。',
 ].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 守衛據此放行
+export function createDataQueryPack({ cwd = process.cwd(), db } = {}) {
+  const dbPath = db ? (isAbsolute(db) ? db : join(cwd, db)) : join(cwd, 'data.db');
+  let schemaSeen = false;
 
   const listTables = {
-    name: 'list_tables', label: '列表', description: '列出所有資料表', readOnly: true,
+    name: 'list_tables', label: '列表', readOnly: true, description: '列出資料庫所有資料表',
     parameters: { type: 'object', properties: {} },
-    execute: async () => { schemaLoaded = true; return txt(Object.keys(schema)); },
+    execute: async () => { schemaSeen = true; const r = sqlite(dbPath, '.tables'); return txt(r.error ? { error: r.error } : { tables: (r.out || '').split(/\s+/).filter(Boolean) }); },
   };
   const describeTable = {
-    name: 'describe_table', label: '表結構', description: '看某表欄位', readOnly: true,
+    name: 'describe_table', label: '表結構', readOnly: true, description: '看某表的欄位定義（CREATE 語句）',
     parameters: { type: 'object', properties: { table: { type: 'string' } }, required: ['table'] },
-    execute: async (_id, { table }) => { schemaLoaded = true; return txt(schema[table] || { error: '無此表' }); },
+    execute: async (_id, { table }) => { schemaSeen = true; const r = sqlite(dbPath, `.schema ${table}`); return txt(r.error ? { error: r.error } : (r.out || '(無此表)')); },
   };
   const sqlQuery = {
-    name: 'sql_query', label: '查詢', description: '執行唯讀 SQL 查詢', readOnly: true,
+    name: 'sql_query', label: '查詢', readOnly: true, description: '執行唯讀 SQL 查詢（SELECT/WITH/PRAGMA），回 CSV（含表頭）。',
     parameters: { type: 'object', properties: { sql: { type: 'string' } }, required: ['sql'] },
-    execute: async (_id, { sql }) => txt({ note: '（示意）查詢結果', sql, rows: [] }),
+    execute: async (_id, { sql }) => {
+      if (/\b(insert|update|delete|drop|create|alter|replace)\b/i.test(sql)) return txt({ error: '這是寫入型 SQL，請改用 sql_exec' });
+      const r = sqlite(dbPath, sql, ['-header', '-csv']);
+      return txt(r.error ? { error: r.error } : (r.out || '(空結果)'));
+    },
   };
   const sqlExec = {
-    name: 'sql_exec', label: '寫入', description: '執行寫入型 SQL（INSERT/UPDATE/DELETE）', mutating: true,
+    name: 'sql_exec', label: '寫入', mutating: true, description: '執行寫入型 SQL（INSERT/UPDATE/DELETE/CREATE/ALTER）。',
     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 }),
+    execute: async (_id, { sql }) => { const r = sqlite(dbPath, sql); return txt(r.error ? { error: r.error } : { ok: true, out: r.out || '' }); },
   };
 
   return {
     name: 'data-query',
-    tools: () => [listTables, describeTable, sqlQuery, sqlExec, chartRender],
+    tools: () => [listTables, describeTable, sqlQuery, sqlExec],
     systemPrompt: SYSTEM_PROMPT,
     contextFiles: ['SCHEMA.md', 'METRICS.md'],
-    // sql_query 唯讀、sql_exec 才 mutating → 從 metadata 自動推導 mutatingTools=['sql_exec']
+    // 只有 sql_exec 是 mutating → kernel 從 metadata 推導
     preToolPolicy: {
-      // schema-before-query：沒先看過 schema 就下查詢 → 擋
+      // schema-before-query：沒先看過結構就下 SQL → 擋（對照 read-before-edit）
       check: (ctx) => {
-        if ((ctx.name === 'sql_query' || ctx.name === 'sql_exec') && !schemaLoaded) {
+        if ((ctx.name === 'sql_query' || ctx.name === 'sql_exec') && !schemaSeen) {
           return { block: true, reason: '請先用 list_tables / describe_table 了解結構，再下 SQL。' };
         }
         return undefined;
       },
     },
     permissionPolicy: { deny: ['bash:DROP', 'bash:TRUNCATE'], defaultMode: 'default' },
-    // verify 省略 → 查詢無「自我驗收」概念
   };
 }
 

package/src/packs/deep-research/index.js

@@ -0,0 +1,41 @@
+// deep-research pack — 深度研究 agent：拆問題 → 多來源搜尋 → 讀全文查證 → 有引用的結論。
+// 工具：web_search/web_fetch（共用）+ write/read（存/讀報告）。搭配 kernel 的 spawn_agent 可並行子研究。
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createWebSearchTool, createWebFetchTool } from '../shared/web-tools.js';
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+const SYSTEM_PROMPT = [
+  '你是深度研究 agent。給你一個問題，做法：',
+  '- 把問題拆成幾個子查詢，用 web_search 找多個來源（不要只查一次）。',
+  '- 用 web_fetch 讀來源全文查證，不只看搜尋摘要。',
+  '- 交叉比對多個來源；關鍵事實要標注來源 URL。',
+  '- 最後給有引用的結論（重要論點附 [來源: URL]）；可用 write 存成報告檔。',
+  '- 來源衝突或查不到時明說，不杜撰。',
+].join('\n');
+
+export function createDeepResearchPack({ cwd = process.cwd() } = {}) {
+  const abs = (p) => (isAbsolute(p) ? p : join(cwd, p));
+
+  const writeReport = {
+    name: 'write', label: '存報告', mutating: true, description: '把研究報告/筆記寫入檔案（建立或覆寫）。',
+    parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+    execute: async (_id, { path, content }) => { writeFileSync(abs(path), content ?? '', 'utf8'); return txt({ written: path, bytes: Buffer.byteLength(content ?? '') }); },
+  };
+  const readTool = {
+    name: 'read', label: '讀檔', readOnly: true, description: '讀回已存的報告/筆記',
+    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    execute: async (_id, { path }) => { const p = abs(path); return existsSync(p) ? txt(readFileSync(p, 'utf8')) : txt({ error: '檔案不存在', path }); },
+  };
+
+  return {
+    name: 'deep-research',
+    tools: () => [createWebSearchTool(), createWebFetchTool(), writeReport, readTool],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['RESEARCH.md'],
+    permissionPolicy: { defaultMode: 'default' },
+  };
+}
+
+export const deepResearchPack = createDeepResearchPack();

package/src/packs/devops/index.js

@@ -0,0 +1,30 @@
+// devops/SRE pack — 維運自動化 agent。shell 為主 + 後台服務 + 設定檔 + 日誌搜尋 + 健康檢查。
+// 工具全由共用模組組成（fs-tools / code-nav / web-tools / bg）。
+import { createFsTools } from '../shared/fs-tools.js';
+import { createGrepTool, createGlobTool } from '../shared/code-nav.js';
+import { createHttpTool } from '../shared/web-tools.js';
+import { createBackgroundTools } from '../../kernel/bg.js';
+
+const SYSTEM_PROMPT = [
+  '你是 DevOps/SRE agent，做系統維運與自動化。準則：',
+  '- 改動前先看現況（read 設定、bash 查狀態、grep 日誌），不要盲改。',
+  '- 操作盡量「冪等」（重跑不會壞）；寫腳本記得處理錯誤與權限。',
+  '- 長時間/常駐服務（dev server、watch、daemon）用 bash_bg，再用 bash_output 看輸出。',
+  '- 部署/操作後用 http 或命令做健康檢查，確認真的好了。',
+  '- 對正式環境的破壞性操作（刪資料、重啟服務）先確認。',
+].join('\n');
+
+export function createDevopsPack({ cwd = process.cwd() } = {}) {
+  const fs = createFsTools(cwd);
+  const bg = createBackgroundTools(cwd);
+  return {
+    name: 'devops',
+    tools: () => [fs.read, fs.ls, createGlobTool(cwd), createGrepTool(cwd), fs.write, fs.edit, fs.bash, ...bg.tools, createHttpTool()],
+    systemPrompt: SYSTEM_PROMPT,
+    contextFiles: ['RUNBOOK.md', 'AGENTS.md'],
+    preToolPolicy: { check: fs.readBeforeEdit },
+    permissionPolicy: { defaultMode: 'default' },
+  };
+}
+
+export const devopsPack = createDevopsPack();

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, extname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { createGrepTool, createGlobTool } from '../shared/code-nav.js';
+import { createWebFetchTool, createWebSearchTool, createHttpTool } from '../shared/web-tools.js';
+
+const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+const SYSTEM_PROMPT = [
+  '你是通用自主 agent。給你一個目標，你用工具反覆推進直到完成：',
+  '- 可讀寫檔案、grep/glob 找東西、跑 shell、搜尋網路(web_search)、抓網頁(web_fetch)、',
+  '  串接 API(http)、讀圖(read_image)、派子 agent、用待辦(todo_write)規劃多步任務。',
+  '- 先想清楚步驟再動手；每步簡述你在做什麼。',
+  '- 需要外部資料：先 web_search 找來源，再 web_fetch 讀全文；串 API 用 http。不要憑空編造。',
+  '- 還缺的能力（瀏覽器點擊、特定服務）可由使用者掛 MCP server 補上。',
+  '- 編輯既有檔案前先 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 命令（可選 timeout 秒數，預設 120）', 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;
+      const r = spawnSync(command, { shell: true, cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 });
+      const output = ((r.stdout || '') + (r.stderr || '')).trim();
+      if (r.error) return txt({ error: r.error.message, output });
+      if (r.status !== 0) return txt({ error: `命令結束碼 ${r.status}`, output: output || '(no output)' });
+      return txt(output || '(no output)');
+    },
+  };
+  const webFetch = createWebFetchTool();
+  const webSearch = createWebSearchTool();
+  const http = createHttpTool();
+
+  // 多模態：讀圖交給模型「看」（需模型支援影像輸入）
+  const readImage = {
+    name: 'read_image', label: '讀圖', readOnly: true,
+    description: '讀取一張圖片（png/jpg/gif/webp）交給模型分析（截圖/設計稿/圖表）。需模型支援影像輸入。',
+    parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+    execute: async (_id, { path }) => {
+      const p = abs(path);
+      if (!existsSync(p)) return txt({ error: '檔案不存在', path });
+      const mimeType = MIME[extname(p).toLowerCase()];
+      if (!mimeType) return txt({ error: '不支援的格式（png/jpg/gif/webp）', path });
+      try { return { content: [{ type: 'image', data: readFileSync(p).toString('base64'), mimeType }] }; }
+      catch (e) { return txt({ error: e.message }); }
+    },
+  };
+
+  const grepTool = createGrepTool(cwd);
+  const globTool = createGlobTool(cwd);
+
+  return {
+    name: 'general',
+    tools: () => [read, ls, globTool, grepTool, write, edit, bash, webSearch, webFetch, http, readImage],
+    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();

package/src/packs/shared/fs-tools.js

@@ -0,0 +1,82 @@
+// 共用檔案/shell 工具（read/ls/write/edit/bash）+ read-before-edit 守衛。
+// 多個 pack（coding/devops…）共用；read 附行號、edit 唯一性檢查、bash 用 spawnSync 捕捉 stderr。
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+
+/**
+ * @param {string} cwd
+ * @returns {{ read, ls, write, edit, bash, readBeforeEdit }}
+ */
+export function createFsTools(cwd) {
+  const readFiles = new Set();
+  const abs = (p) => (isAbsolute(p) ? p : join(cwd, p));
+
+  const read = {
+    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);
+      const lines = readFileSync(p, 'utf8').split('\n');
+      const start = Math.max(0, (offset || 1) - 1);
+      const count = limit && limit > 0 ? limit : 2000;
+      const numbered = lines.slice(start, start + count).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}）` : ''));
+    },
+  };
+  const ls = {
+    name: 'ls', label: '列目錄', readOnly: true, description: '列出目錄內容',
+    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: '寫檔', mutating: true, description: '建立或覆寫檔案',
+    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: '編輯', mutating: true,
+    description: '把 oldText 換成 newText。oldText 須唯一（多次出現需 replaceAll）。',
+    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');
+      const n = before.split(oldText).length - 1;
+      if (n === 0) return txt({ error: 'oldText 未找到（先 read 確認）', path });
+      if (n > 1 && !replaceAll) return txt({ error: `oldText 出現 ${n} 次，請更精確或設 replaceAll`, path });
+      writeFileSync(p, replaceAll ? before.split(oldText).join(newText) : before.replace(oldText, newText), 'utf8');
+      return txt({ edited: path, replaced: replaceAll ? n : 1 });
+    },
+  };
+  const bash = {
+    name: 'bash', label: 'bash', mutating: true, sandboxable: true,
+    description: '執行 shell 命令（可選 timeout 秒數，預設 120）。長時間/常駐用 bash_bg。',
+    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;
+      const r = spawnSync(command, { shell: true, cwd, encoding: 'utf8', timeout: ms, maxBuffer: 16 * 1024 * 1024 });
+      const output = ((r.stdout || '') + (r.stderr || '')).trim();
+      if (r.error) return txt({ error: r.error.message, output });
+      if (r.status !== 0) return txt({ error: `命令結束碼 ${r.status}`, output: output || '(no output)' });
+      return txt(output || '(no output)');
+    },
+  };
+
+  // read-before-edit 守衛（給 pack 的 preToolPolicy 用）
+  const readBeforeEdit = (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;
+  };
+
+  return { read, ls, write, edit, bash, readBeforeEdit };
+}

package/src/packs/shared/web-tools.js

@@ -0,0 +1,57 @@
+// 共用 web 工具（web_search / web_fetch / http）— general 與 deep-research pack 共用。
+const txt = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s) }] });
+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();
+
+export function createWebFetchTool() {
+  return {
+    name: 'web_fetch', label: '抓網頁', readOnly: true,
+    description: '抓取一個 URL 的內容並回傳純文字（HTML 去標籤、截斷）。讀某頁全文用。',
+    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 }); }
+    },
+  };
+}
+
+export function createWebSearchTool() {
+  return {
+    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 }); }
+    },
+  };
+}
+
+export function createHttpTool() {
+  return {
+    name: 'http', label: 'HTTP 請求',
+    description: '發 HTTP 請求串接 API：method（預設 GET）、headers、body。回 status + headers + body（截斷）。',
+    parameters: { type: 'object', properties: { url: { type: 'string' }, method: { type: 'string' }, headers: { type: 'object' }, body: { type: 'string' } }, required: ['url'] },
+    execute: async (_id, { url, method = 'GET', headers, body }) => {
+      try {
+        const m = String(method).toUpperCase();
+        const res = await fetch(url, { method: m, headers: headers || {}, body: (m === 'GET' || m === 'HEAD') ? undefined : body, signal: AbortSignal.timeout(20000) });
+        const text = (await res.text()).slice(0, 8000);
+        return txt({ url, method: m, status: res.status, headers: Object.fromEntries(res.headers), body: text });
+      } catch (e) { return txt({ error: e?.message || String(e), url }); }
+    },
+  };
+}