botrun-horse 1.0.0

package/lib/flows/gemini-ask.mjs

@@ -0,0 +1,185 @@
+// lib/flows/gemini-ask.mjs — Gemini 提問流程（Application Layer）
+// 職責: 組裝 adapter + 格式化輸出 + 效能測量
+// 原則: KISS — 流程越簡單越好，複雜邏輯在 adapter
+
+import { createLLM } from '../core/llm.mjs';
+
+/**
+ * 取得臺灣當前時間字串，自動注入 system prompt
+ * @returns {string} 例如 "現在時間：2026年2月27日（週四）15:30 (UTC+8 臺灣時間)"
+ */
+function getTaiwanTimePrefix() {
+  const now = new Date();
+  const tw = new Intl.DateTimeFormat('zh-TW', {
+    timeZone: 'Asia/Taipei',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    weekday: 'short',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).formatToParts(now);
+
+  const get = (type) => tw.find(p => p.type === type)?.value || '';
+  return `現在時間：${get('year')}年${get('month')}月${get('day')}日（${get('weekday')}）${get('hour')}:${get('minute')} (UTC+8 臺灣時間)`;
+}
+
+/**
+ * 組裝 system instruction：自動加上臺灣時間前綴
+ * @param {string} [userSystemInstruction] - 使用者提供的 system prompt
+ * @returns {string} 含時間前綴的完整 system instruction
+ */
+function buildSystemInstruction(userSystemInstruction) {
+  const timePrefix = getTaiwanTimePrefix();
+  if (userSystemInstruction) {
+    return `${timePrefix}\n\n${userSystemInstruction}`;
+  }
+  return timePrefix;
+}
+
+/**
+ * 執行 Gemini 提問流程
+ * @param {object} params
+ * @param {string} params.prompt - 使用者提問
+ * @param {string} [params.systemInstruction] - 系統提示詞（與 prompt 分離，讓 Gemini 正確區分角色）
+ * @param {string} [params.thinking='MEDIUM'] - 思考等級
+ * @param {boolean} [params.grounding=true] - 啟用搜尋接地
+ * @param {boolean} [params.urlContext=true] - 啟用 URL 擷取
+ * @param {string} [params.project] - GCP 專案 ID
+ * @param {string} [params.location] - GCP 區域
+ * @returns {Promise<object>} 結構化回應（含 perf 效能指標）
+ */
+export async function geminiAsk({
+  provider = 'gemini-auto',
+  prompt,
+  systemInstruction,
+  thinking = 'MEDIUM',
+  grounding = true,
+  urlContext = true,
+  project,
+  location,
+}) {
+  const adapter = await createLLM({
+    provider,
+    project,
+    location,
+    thinkingLevel: thinking,
+    grounding,
+    urlContext,
+  });
+
+  return adapter.generateContent({ prompt, systemInstruction: buildSystemInstruction(systemInstruction) });
+}
+
+/**
+ * 串流執行 Gemini 提問流程（AsyncGenerator）
+ * yield* 委託 adapter.generateContentStream()
+ * @param {object} params - 同 geminiAsk 參數
+ * @yields {{ type: 'text', text: string } | { type: 'metadata', ... }}
+ */
+export async function* geminiAskStream({
+  provider = 'gemini-auto',
+  prompt,
+  systemInstruction,
+  thinking = 'MEDIUM',
+  grounding = true,
+  urlContext = true,
+  project,
+  location,
+}) {
+  const adapter = await createLLM({
+    provider,
+    project,
+    location,
+    thinkingLevel: thinking,
+    grounding,
+    urlContext,
+  });
+
+  yield* adapter.generateContentStream({ prompt, systemInstruction: buildSystemInstruction(systemInstruction) });
+}
+
+/**
+ * 格式化效能摘要為純文字（多快 + 多省）
+ * @param {object} perf - 效能指標
+ * @param {object} usage - token 用量
+ * @returns {string} 效能摘要
+ */
+export function formatPerfSummary(perf, usage) {
+  const lines = [];
+  lines.push('--- 效能測量 ---');
+
+  // 多快
+  lines.push(`  延遲:       ${perf.latencySec}s (${perf.latencyMs}ms)`);
+  lines.push(`  輸出速度:   ${perf.outputTokensPerSec} tokens/s | ${perf.charsPerSec} 字/s`);
+  lines.push(`  總吞吐量:   ${perf.totalTokensPerSec} tokens/s`);
+
+  // 多省
+  lines.push(`  token 分佈: prompt=${usage.promptTokens} think=${usage.thoughtsTokens} output=${usage.candidatesTokens} total=${usage.totalTokens}`);
+  lines.push(`  思考佔比:   ${(perf.thinkRatio * 100).toFixed(1)}% (思考/總)  | 思考:輸出 = ${perf.thinkToOutputRatio}:1`);
+  lines.push(`  輸出效率:   ${(perf.outputRatio * 100).toFixed(1)}% (有效輸出/總) | ${perf.charsPerToken} 字/token`);
+
+  return lines.join('\n');
+}
+
+/**
+ * 格式化回應為純文字（含引證 + 效能）
+ * @param {object} result - geminiAsk 回應
+ * @returns {string} 格式化文字
+ */
+export function formatTextOutput(result) {
+  const lines = [];
+
+  // 主要回應
+  lines.push(result.text);
+
+  // 引證來源
+  if (result.sources.length > 0) {
+    lines.push('');
+    lines.push('--- 引證來源 ---');
+    for (const src of result.sources) {
+      lines.push(`  [${src.title || src.domain}] ${src.uri}`);
+    }
+  }
+
+  // URL 擷取狀態
+  if (result.urlContext.length > 0) {
+    lines.push('');
+    lines.push('--- URL 擷取 ---');
+    for (const uc of result.urlContext) {
+      const icon = uc.status === 'success' ? 'OK' : 'FAIL';
+      lines.push(`  ${icon}  ${uc.url}`);
+    }
+  }
+
+  // 效能測量
+  if (result.perf) {
+    lines.push('');
+    lines.push(formatPerfSummary(result.perf, result.usage));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 格式化回應為 JSON（含效能指標）
+ * @param {object} result - geminiAsk 回應
+ * @param {string} model - 模型名稱
+ * @param {string} elapsed - 總耗時（含 CLI 初始化）
+ * @returns {string} JSON 字串
+ */
+export function formatJsonOutput(result, model, elapsed) {
+  const output = {
+    _meta: { command: 'gemini ask', model, elapsed },
+    text: result.text,
+    thinking: result.thinking || null,
+    sources: result.sources,
+    searchQueries: result.searchQueries || [],
+    supports: result.supports || [],
+    urlContext: result.urlContext,
+    usage: result.usage,
+    perf: result.perf || null,
+  };
+  return JSON.stringify(output, null, 2);
+}

package/lib/flows/hatch-portal.mjs

@@ -0,0 +1,13 @@
+// lib/flows/hatch-portal.mjs — 智慧入口孵化業務流程
+// 串接：portal → 全自動孵化流程
+
+/**
+ * 執行孵化流程
+ * @param {object} opts
+ * @param {string} opts.project - 專案名稱
+ * @param {object} opts.input - 輸入資料
+ */
+export async function hatchPortal(opts = {}) {
+  // TODO: 實作端到端孵化流程
+  throw new Error('hatchPortal flow 尚未實作');
+}

package/lib/flows/legal-ask.mjs

@@ -0,0 +1,325 @@
+// lib/flows/legal-ask.mjs — 法律查詢單次提問流程（Application Layer）
+//
+// 設計原則：SOLID / DDD / KISS
+//   SRP — 組裝 adapter + cache + router，不直接處理 SQLite 或 HTTP
+//   DDD — 以 LegalQueryResult Value Object 為核心輸出
+//   KISS — 單次 request 完成搜尋+分析（合併多步驟提示工程）
+//
+// 流程：
+//   1. AI Router（Mistral 14B）判斷是否使用快取
+//      → cache hit：直接回傳快取答案，不呼叫大模型
+//      → cache miss：執行單次大模型查詢（搜尋法規 + 法律分析一口氣完成）
+//   2. 儲存到快取，下次 Mistral 14B 可命中
+//
+// LegalQueryResult Value Object：
+//   { question, fromCache, cacheId, tags, step1Laws, step2Answer, sources,
+//     model, routerDecision, perf }
+
+import { createLLM } from '../core/llm.mjs';
+import { AiCache } from '../core/ai-cache.mjs';
+import { AiRouter } from '../core/ai-router.mjs';
+import { dbPath as resolveDbPath } from '../core/paths.mjs';
+
+// ── 合併提示詞（單次 request 完成搜尋 + 分析） ─────────────────────────────
+
+/**
+ * 單次 request 提示：搜尋法規 + 白話法律分析
+ * 利用 Gemini 3 Flash 的 webSearch + thinking 能力，一次完成兩階段工作
+ */
+const LEGAL_SYSTEM = `你是專業的臺灣法律諮詢助理，同時具備法規搜尋與白話解釋能力。
+
+你的工作分為兩個階段，在同一次回答中完成：
+
+【階段一：搜尋法規】
+1. 使用網路搜尋功能搜尋全國法規資料庫（law.moj.gov.tw）及可靠法律來源
+2. 嚴格保留法條原文，一字不差，禁止修改或改寫法條內容
+3. 標注每條法規的完整來源（法規名稱、條號）
+4. 若有相關的司法院解釋或判例，一併列出
+
+【階段二：白話分析】
+1. 只能基於你搜尋到的法律條文回答，嚴禁添加法條以外的推測或臆測
+2. 使用白話文解釋，讓一般民眾也能理解
+3. 清楚說明使用者的「權利」與「義務」
+4. 若法律有例外情形，必須清楚說明
+
+輸出格式（嚴格遵守 JSON）：
+{
+  "laws": [
+    {
+      "law_name": "民法",
+      "article": "第 425 條",
+      "content": "（完整原始法條文字）",
+      "source_url": "https://law.moj.gov.tw/..."
+    }
+  ],
+  "answer": {
+    "summary": "（一句話直接回答是否可行）",
+    "detail": "（白話解釋相關法條，分段說明）",
+    "rights": "（使用者可以主張的權利）",
+    "warnings": "（例外情形或限制）",
+    "cited_laws": ["民法 第 425 條", "土地法 第 100 條"]
+  }
+}
+
+若找不到相關法條，laws 陣列為空，answer 中說明找不到的原因。`;
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 從模型回應中萃取 JSON（容錯：markdown code block、純文字混雜）
+ * @param {string} text
+ * @returns {{ laws: Array, answer: object } | null}
+ */
+function parseResponse(text) {
+  const trimmed = (text || '').trim();
+  // 1. 直接 JSON
+  try { return JSON.parse(trimmed); } catch { /* 繼續 */ }
+  // 2. markdown code block
+  const mdMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (mdMatch) {
+    try { return JSON.parse(mdMatch[1].trim()); } catch { /* 繼續 */ }
+  }
+  // 3. 從文字中提取 {...}
+  const braceMatch = trimmed.match(/\{[\s\S]*\}/);
+  if (braceMatch) {
+    try { return JSON.parse(braceMatch[0]); } catch { /* 繼續 */ }
+  }
+  return null;
+}
+
+/**
+ * 將結構化 answer 物件組合成可讀文字
+ * @param {object} answer - { summary, detail, rights, warnings, cited_laws }
+ * @returns {string}
+ */
+function answerToText(answer) {
+  if (!answer) return '';
+  if (typeof answer === 'string') return answer;
+  const parts = [];
+  if (answer.summary) parts.push(`**法律上的答案**：${answer.summary}`);
+  if (answer.detail) parts.push(`\n**詳細說明**：\n${answer.detail}`);
+  if (answer.rights) parts.push(`\n**您的權利**：\n${answer.rights}`);
+  if (answer.warnings) parts.push(`\n**注意事項**：\n${answer.warnings}`);
+  if (answer.cited_laws?.length) {
+    parts.push(`\n**相關法條引用**：\n${answer.cited_laws.map(l => `- ${l}`).join('\n')}`);
+  }
+  return parts.join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 執行法律查詢（含 AI Router 快取判斷 + 單次大模型提問）
+ *
+ * @param {object} params
+ * @param {string} params.question         - 使用者問題（白話文）
+ * @param {string} [params.project]        - 專案名稱（決定 SQLite 路徑）
+ * @param {object} [params.config]         - 專案 config.json 內容
+ * @param {boolean} [params.skipCache]     - 強制跳過快取，直接呼叫大模型
+ * @param {boolean} [params.skipSave]      - 不將結果存入快取
+ * @returns {Promise<LegalQueryResult>}
+ */
+export async function legalAsk({
+  question,
+  project = 'legal-cache',
+  config = {},
+  skipCache = false,
+  skipSave = false,
+}) {
+  const t0 = performance.now();
+
+  // ── 初始化元件 ──────────────────────────────────────────────────────────
+  const dbPath = resolveDbPath(project);
+  const cache = new AiCache(dbPath);
+  cache.initSchema();
+
+  const routerConfig = config.router || {};
+  const router = new AiRouter({
+    provider: routerConfig.provider || 'nchc',
+    model: routerConfig.model || 'Ministral-3-14B-Instruct-2512',
+    tagCacheThreshold: routerConfig.tagCacheThreshold ?? 2,
+  });
+
+  // ── Phase 1：AI Router 決策 ──────────────────────────────────────────────
+  let routerDecision = null;
+  if (!skipCache) {
+    routerDecision = await router.route(question, cache);
+
+    // 記錄路由決策
+    cache.logRouterDecision({
+      question,
+      decision: routerDecision.decision,
+      cacheId: routerDecision.cacheId,
+      confidence: routerDecision.confidence,
+      tags: routerDecision.tags,
+      reason: routerDecision.reason,
+      latencyMs: routerDecision.latencyMs,
+    });
+
+    // Cache Hit：直接回傳快取答案
+    if (routerDecision.decision === 'cache' && routerDecision.cacheId) {
+      const cached = cache.getById(routerDecision.cacheId);
+      if (cached) {
+        cache.incrementHit(routerDecision.cacheId);
+        const totalMs = Math.round(performance.now() - t0);
+        cache.close();
+        return {
+          question,
+          fromCache: true,
+          cacheId: routerDecision.cacheId,
+          tags: routerDecision.tags,
+          step1Laws: cached.step1Laws ? JSON.parse(cached.step1Laws) : [],
+          step2Answer: cached.step2Answer,
+          sources: cached.sources,
+          model: cached.modelStep1,
+          routerDecision,
+          perf: { totalMs, routerMs: routerDecision.latencyMs },
+        };
+      }
+    }
+  }
+
+  // 萃取標籤（skipCache 模式下仍萃取，以便存快取）
+  const tags = routerDecision?.tags || await router.extractTags(question);
+
+  // ── Phase 2：單次大模型查詢（搜尋 + 分析合併） ─────────────────────────
+  const searchConfig = config.search || {};
+
+  const tLlm = performance.now();
+  const llm = await createLLM({
+    provider: searchConfig.provider || 'openrouter',
+    model: searchConfig.model || 'google/gemini-3-flash-preview',
+    webSearch: searchConfig.webSearch ?? true,
+    maxResults: searchConfig.maxResults || 10,
+    maxTokens: searchConfig.maxTokens || 4096,
+    reasoningEffort: searchConfig.reasoningEffort || 'medium',
+  });
+
+  const llmResult = await llm.generateContent({
+    systemInstruction: LEGAL_SYSTEM,
+    prompt: `使用者問題：${question}`,
+  });
+  const llmMs = Math.round(performance.now() - tLlm);
+
+  // 解析結構化回應
+  const parsed = parseResponse(llmResult.text);
+  let laws = [];
+  let answerText = '';
+
+  if (parsed) {
+    laws = Array.isArray(parsed.laws) ? parsed.laws : [];
+    answerText = answerToText(parsed.answer);
+  } else {
+    // 解析失敗：整段當作純文字回答
+    answerText = llmResult.text;
+  }
+
+  // 整合引證來源
+  const sources = [
+    ...llmResult.sources,
+    ...laws.filter(l => l.source_url).map(l => ({ uri: l.source_url, title: `${l.law_name} ${l.article}` })),
+  ];
+
+  const totalMs = Math.round(performance.now() - t0);
+
+  // ── Phase 3：儲存到快取 ──────────────────────────────────────────────────
+  let newCacheId = null;
+  if (!skipSave) {
+    newCacheId = cache.insertQa({
+      question,
+      tags,
+      step1Laws: JSON.stringify(laws),
+      step2Answer: answerText,
+      sources,
+      modelStep1: llmResult.model,
+      modelStep2: llmResult.model,
+    });
+  }
+
+  cache.close();
+
+  return {
+    question,
+    fromCache: false,
+    cacheId: newCacheId,
+    tags,
+    step1Laws: laws,
+    step2Answer: answerText,
+    sources,
+    model: llmResult.model,
+    routerDecision,
+    perf: {
+      totalMs,
+      routerMs: routerDecision?.latencyMs || 0,
+      llmMs,
+    },
+  };
+}
+
+/**
+ * 格式化 LegalQueryResult 為純文字輸出
+ * @param {LegalQueryResult} result
+ * @returns {string}
+ */
+export function formatLegalResult(result) {
+  const lines = [];
+
+  if (result.fromCache) {
+    lines.push(`✓ 快取命中（ID: ${result.cacheId}，已被使用 ${result.hitCount ?? '?'} 次）`);
+    lines.push(`  標籤：${result.tags.join('、')}`);
+    lines.push('');
+  } else {
+    lines.push(`→ 單次大模型查詢（標籤：${result.tags.join('、')}）`);
+    if (result.cacheId) lines.push(`  已存入快取 ID: ${result.cacheId}`);
+    lines.push('');
+  }
+
+  lines.push('── 法律回答 ─────────────────────────────────────────');
+  lines.push(result.step2Answer);
+
+  if (!result.fromCache && result.step1Laws?.length > 0) {
+    lines.push('');
+    lines.push('── 搜尋到的法條 ─────────────────────────────────────');
+    for (const law of result.step1Laws) {
+      lines.push(`  【${law.law_name} ${law.article}】`);
+      if (law.source_url) lines.push(`  來源：${law.source_url}`);
+    }
+  }
+
+  if (result.sources?.length > 0) {
+    lines.push('');
+    lines.push('── 引證來源 ─────────────────────────────────────────');
+    for (const src of result.sources) {
+      lines.push(`  [${src.title || src.uri}] ${src.uri}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('── 效能 ─────────────────────────────────────────────');
+  lines.push(`  總耗時：${result.perf.totalMs}ms`);
+  if (!result.fromCache) {
+    lines.push(`  路由耗時：${result.perf.routerMs}ms`);
+    lines.push(`  大模型（搜尋+分析）：${result.perf.llmMs}ms`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 格式化為 JSON 輸出
+ * @param {LegalQueryResult} result
+ * @returns {string} JSON 字串
+ */
+export function formatLegalResultJson(result) {
+  return JSON.stringify({
+    _meta: { command: 'legal ask', fromCache: result.fromCache },
+    question: result.question,
+    answer: result.step2Answer,
+    laws: result.step1Laws,
+    sources: result.sources,
+    tags: result.tags,
+    cacheId: result.cacheId,
+    routerDecision: result.routerDecision,
+    perf: result.perf,
+  }, null, 2);
+}

package/lib/flows/openai-agent.mjs

@@ -0,0 +1,167 @@
+// lib/flows/openai-agent.mjs — openai SDK 系列代理（NCHC 直連）
+//
+// 使用 `openai` npm 套件（OpenAI 相容介面）直連 NCHC GenAI 端點。
+// 包含兩個代理類別：
+//
+//   NchcAgent      — 通用代理（唯讀工具：read_file, list_files, grep_content）
+//   NchcCodeAgent  — Coding 代理（繼承 NchcAgent + 寫入工具：write_file, edit_file,
+//                    run_command, create_dir），支援 dryRun 模式
+//
+// 對比：opencode-agent.mjs 使用 @opencode-ai/sdk，需要 opencode server
+//       本檔不需要任何外部 server，直接由 Node.js 呼叫 NCHC API
+//
+// DDD 領域概念：
+//   AgentTask    — 使用者交付的任務描述
+//   ToolDef      — 工具定義（名稱、描述、JSON Schema）
+//   ToolCall     — 代理發出的工具呼叫
+//   ToolResult   — 工具執行結果
+//   AgentEvent   — 事件流（tool_call / tool_result / text / done）
+//   WriteOp      — 寫入操作（path + content，Value Object）
+//   EditOp       — 精確替換操作（old_string 唯一性）
+//   CommandRun   — shell 指令執行（含逾時與退出碼）
+//
+// SOLID：
+//   SRP — 代理只負責對話迴圈；工具定義與執行分開維護
+//   OCP — 工具透過 tools / extraTools 注入，不修改核心邏輯
+//   LSP — NchcCodeAgent IS-A NchcAgent，可互換使用
+//   DIP — _client / toolExecutor 可注入替換（測試友善）
+
+import OpenAI from 'openai';
+
+// ── NCHC 端點常數 ──────────────────────────────────────────────────────────
+
+const NCHC_BASE_URL = 'https://portal.genai.nchc.org.tw/api/v1';
+export const NCHC_DEFAULT_MODEL = 'Mistral-Large-3-675B-Instruct-2512';
+export const NCHC_MAX_AGENT_TURNS = 20;
+
+// ── 工具 schema 從 lib/tools/ 動態載入（OCP：新增工具只需在 lib/tools/ 加檔案）──
+
+export {
+  BUILT_IN_TOOLS,
+  CODING_TOOLS,
+  CODING_TOOL_NAMES,
+  CODING_SYSTEM_PROMPT,
+  executeTool,
+  executeCodeTool,
+} from '../tools/fs-tools.mjs';
+
+import {
+  BUILT_IN_TOOLS,
+  CODING_TOOLS,
+  CODING_TOOL_NAMES,
+  CODING_SYSTEM_PROMPT,
+  executeTool,
+  executeCodeTool,
+} from '../tools/fs-tools.mjs';
+
+// ══════════════════════════════════════════════════════════════════════════
+// NchcAgent — 通用代理（唯讀工具）
+// ══════════════════════════════════════════════════════════════════════════
+
+export class NchcAgent {
+  /**
+   * @param {object} [opts]
+   * @param {string}   [opts.apiKey]       - NCHC_GENAI_API_KEY
+   * @param {string}   [opts.model]        - 模型名稱
+   * @param {object[]} [opts.tools]        - 工具定義陣列（預設 BUILT_IN_TOOLS）
+   * @param {function} [opts.toolExecutor] - 工具執行函式（DIP）
+   * @param {string}   [opts.systemPrompt] - 系統提示詞
+   * @param {number}   [opts.maxTurns]     - 最大迴圈次數
+   * @param {string}   [opts.cwd]          - 工作目錄
+   * @param {object}   [opts._client]      - 注入 OpenAI client（測試用）
+   */
+  constructor(opts = {}) {
+    const apiKey = opts.apiKey || process.env.NCHC_GENAI_API_KEY;
+    if (!apiKey && !opts._client) {
+      throw new Error(
+        'NchcAgent: 需要 NCHC GenAI API Key。\n' +
+        '請設定環境變數 NCHC_GENAI_API_KEY 或傳入 apiKey 參數。'
+      );
+    }
+    this._client = opts._client || new OpenAI({ apiKey, baseURL: NCHC_BASE_URL });
+    this.model = opts.model || NCHC_DEFAULT_MODEL;
+    this.tools = opts.tools || BUILT_IN_TOOLS;
+    this.toolExecutor = opts.toolExecutor || executeTool;
+    this.systemPrompt = opts.systemPrompt ||
+      '你是一個智慧代理（Agentic AI），可以使用工具來協助完成任務。' +
+      '請使用繁體中文回應。在完成任務時，優先使用工具收集資訊，再給出完整答案。';
+    this.maxTurns = opts.maxTurns || NCHC_MAX_AGENT_TURNS;
+    this.cwd = opts.cwd || process.cwd();
+  }
+
+  /**
+   * 執行任務（AsyncGenerator）
+   * @yields {{ type: 'tool_call'|'tool_result'|'text'|'done', ... }}
+   */
+  async *run(task) {
+    const messages = [
+      { role: 'system', content: this.systemPrompt },
+      { role: 'user', content: task },
+    ];
+    let turns = 0;
+    let finalText = '';
+
+    while (turns < this.maxTurns) {
+      turns++;
+      const response = await this._client.chat.completions.create({
+        model: this.model, messages, tools: this.tools, tool_choice: 'auto',
+      });
+      const choice = response.choices[0];
+      const assistantMsg = choice.message;
+      messages.push(assistantMsg);
+
+      if (choice.finish_reason !== 'tool_calls') {
+        finalText = assistantMsg.content || '';
+        yield { type: 'text', text: finalText };
+        break;
+      }
+
+      for (const tc of (assistantMsg.tool_calls || [])) {
+        const name = tc.function.name;
+        let args;
+        try { args = JSON.parse(tc.function.arguments); } catch { args = {}; }
+
+        yield { type: 'tool_call', name, args, callId: tc.id };
+        const result = await this.toolExecutor(name, args, this.cwd);
+        yield { type: 'tool_result', name, result, callId: tc.id };
+        messages.push({ role: 'tool', tool_call_id: tc.id, content: result });
+      }
+    }
+
+    if (turns >= this.maxTurns) {
+      finalText = `[已達最大迴圈次數 ${this.maxTurns}，任務中止]`;
+      yield { type: 'text', text: finalText };
+    }
+    yield { type: 'done', turns, text: finalText };
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// NchcCodeAgent — Coding 代理（IS-A NchcAgent + 寫入工具）
+// ══════════════════════════════════════════════════════════════════════════
+
+export class NchcCodeAgent extends NchcAgent {
+  /**
+   * @param {object} [opts]
+   * @param {boolean}  [opts.dryRun=false]  - true 時不實際寫入/執行
+   * @param {object[]} [opts.extraTools]    - 額外自訂工具（OCP 注入）
+   * @param {function} [opts.toolExecutor]  - 工具執行注入（測試用，DIP）
+   * @param {string}   [opts.systemPrompt]  - 覆蓋預設系統提示詞
+   * （其餘同 NchcAgent）
+   */
+  constructor(opts = {}) {
+    const dryRun = opts.dryRun || false;
+    const combinedExecutor = async (name, args, toolCwd) =>
+      CODING_TOOL_NAMES.has(name)
+        ? executeCodeTool(name, args, toolCwd, dryRun)
+        : executeTool(name, args, toolCwd);
+
+    super({
+      ...opts,
+      tools: [...BUILT_IN_TOOLS, ...CODING_TOOLS, ...(opts.extraTools || [])],
+      toolExecutor: opts.toolExecutor || combinedExecutor,
+      systemPrompt: opts.systemPrompt || CODING_SYSTEM_PROMPT,
+    });
+    this.dryRun = dryRun;
+  }
+}