botrun-horse 2.30.0 → 2.34.0

package/modules/legal/index.mjs

@@ -0,0 +1,56 @@
+// modules/legal/index.mjs — 法律查詢模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'legal';
+
+export const schema = {
+  name: 'legal',
+  description: '法律查詢（AI Router + 兩步驟提示工程 + SQLite 快取）[需 --experimental-sqlite]',
+  requires_sqlite: true,
+  subcommands: {
+    ask: '法律問題查詢（Mistral 14B 路由 → 快取命中或 Gemini Pro 搜尋法規 → 法律分析）',
+    cache: '快取管理（list: 列出快取, stats: 統計）',
+  },
+  options: {
+    '--project=<名稱>': { type: 'string', default: 'legal-cache', description: '專案名稱（決定 SQLite 路徑）' },
+    '--skip-cache': { type: 'boolean', default: false, description: '強制跳過快取，直接呼叫大模型' },
+    '--skip-save': { type: 'boolean', default: false, description: '不將結果存入快取' },
+    '--limit=N': { type: 'integer', default: 20, description: '[cache list] 顯示筆數上限' },
+    '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr）' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: [
+    'node --experimental-sqlite bin/bh.mjs legal ask "房東可以隨意趕走我嗎？"',
+    'node --experimental-sqlite bin/bh.mjs legal ask "勞工被無故解雇有哪些保護？" --format=json',
+    'echo "我的房東說要漲租金，我有辦法拒絕嗎？" | node --experimental-sqlite bin/bh.mjs legal ask',
+    'node --experimental-sqlite bin/bh.mjs legal cache list --project=legal-cache',
+    'node --experimental-sqlite bin/bh.mjs legal cache stats',
+    'node --experimental-sqlite bin/bh.mjs legal ask "問題" --skip-cache --project=legal-cache',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdLegalAsk, cmdLegalCacheList, cmdLegalCacheStats } = await import('./command.mjs');
+  switch (subcommand) {
+    case 'ask': await cmdLegalAsk(positionals, flags); break;
+    case 'cache': {
+      const cacheSubcmd = positionals[0];
+      switch (cacheSubcmd) {
+        case 'list': await cmdLegalCacheList(flags); break;
+        case 'stats': await cmdLegalCacheStats(flags); break;
+        default:
+          process.stderr.write(`legal cache: 未知子指令 ${cacheSubcmd}（可用: list, stats）\n`);
+          process.exit(1);
+      }
+      break;
+    }
+    default:
+      if (!subcommand) {
+        const { showCommandHelp } = await import('../../bin/commands/help.mjs');
+        showCommandHelp('legal', { legal: schema });
+      } else {
+        process.stderr.write(`legal: 未知子指令 ${subcommand}\n`);
+        process.exit(1);
+      }
+  }
+}

package/{bin/commands/nchc.mjs → modules/nchc/command.mjs}

@@ -1,5 +1,5 @@
 // bin/commands/nchc.mjs — nchc 指令群組（ask / agent / code / models）
-import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+import { timer, emitError, readStdin } from '../_core/cli-utils.mjs';
 
 export async function cmdNchcAsk(positionals, flags) {
   const elapsed = timer();
@@ -12,7 +12,7 @@ export async function cmdNchcAsk(positionals, flags) {
     process.exit(1);
   }
 
-  const { NchcAdapter } = await import('../../lib/core/adapters/nchc.mjs');
+  const { NchcAdapter } = await import('../_core/adapters/nchc.mjs');
   const adapter = new NchcAdapter({
     model: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
     maxTokens: parseInt(flags['max-tokens']) || 8192,
@@ -89,7 +89,7 @@ export async function cmdNchcAgent(positionals, flags) {
     process.exit(1);
   }
 
-  const { NchcAgent } = await import('../../lib/flows/openai-agent.mjs');
+  const { NchcAgent } = await import('../_core/openai-agent.mjs');
   const agent = new NchcAgent({
     model: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
     maxTurns: parseInt(flags['max-turns']) || 20,
@@ -149,7 +149,7 @@ export async function cmdNchcCode(positionals, flags) {
     process.exit(1);
   }
 
-  const { OpencodeAgent } = await import('../../lib/flows/opencode-agent.mjs');
+  const { OpencodeAgent } = await import('../_core/opencode-agent.mjs');
   const agent = new OpencodeAgent({
     modelID: flags.model || 'Mistral-Large-3-675B-Instruct-2512',
     serverUrl: flags['server-url'] || undefined,

package/modules/nchc/index.mjs

@@ -0,0 +1,48 @@
+// modules/nchc/index.mjs — 國網 GenAI 提問模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'nchc';
+
+export const schema = {
+  name: 'nchc',
+  description: '國網 GenAI AI 提問（Mistral 系列，OpenAI 相容介面）',
+  requires_sqlite: false,
+  subcommands: {
+    ask: '向國網 GenAI 提問（支援串流輸出）',
+    agent: '啟動 Agentic AI 代理（工具呼叫、多輪對話）',
+    code: '啟動 Agentic Coding 代理（@opencode-ai/sdk + 675B，需 opencode CLI）',
+    models: '列出可用模型',
+  },
+  options: {
+    '--model=<名稱>': { type: 'string', default: 'Mistral-Large-3-675B-Instruct-2512', description: '模型名稱' },
+    '--system-prompt=<文字>': { type: 'string', default: '', description: '系統提示詞' },
+    '--max-tokens=N': { type: 'integer', default: 8192, description: '最大輸出 tokens' },
+    '--temperature=N': { type: 'number', default: 0.7, description: '溫度（0.0~1.0）' },
+    '--no-stream': { type: 'boolean', default: false, description: '停用串流' },
+    '--max-turns=N': { type: 'integer', default: 20, description: '[agent] 最大迴圈次數' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: [
+    'bh nchc ask "台灣半導體產業分析"',
+    'bh nchc agent "列出 lib/ 目錄下所有 .mjs 檔案並說明架構"',
+    'bh nchc models',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdNchcAsk, cmdNchcAgent, cmdNchcCode, cmdNchcModels } = await import('./command.mjs');
+  switch (subcommand) {
+    case 'ask': await cmdNchcAsk(positionals, flags); break;
+    case 'agent': await cmdNchcAgent(positionals, flags); break;
+    case 'code': await cmdNchcCode(positionals, flags); break;
+    case 'models': cmdNchcModels(flags); break;
+    default:
+      if (!subcommand) {
+        const { showCommandHelp } = await import('../../bin/commands/help.mjs');
+        showCommandHelp('nchc', { nchc: schema });
+      } else {
+        process.stderr.write(`nchc: 未知子指令 ${subcommand}\n`);
+        process.exit(1);
+      }
+  }
+}

package/modules/ocr/index.mjs

@@ -0,0 +1,17 @@
+// modules/ocr/index.mjs — OCR 辨識模組自動註冊介面（預留）
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'ocr';
+
+export const schema = {
+  name: 'ocr',
+  description: 'OCR 辨識（預留）',
+  requires_sqlite: false,
+  subcommands: { scan: '掃描文件' },
+  options: {},
+  examples: ['bh ocr scan file.pdf'],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  process.stdout.write('ocr 模組尚在開發中\n');
+}

package/{bin/commands/openrouter.mjs → modules/openrouter/command.mjs}

@@ -6,7 +6,7 @@
 //   - Agentic AI 友善：--format=json 回傳結構化 LlmResponse（含 sources、usage、perf）
 //   - KISS：指令層只做 I/O 與格式化，業務邏輯委派至 adapter
 
-import { timer, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+import { timer, emitError, readStdin } from '../_core/cli-utils.mjs';
 
 /**
  * openrouter ask — 向 OpenRouter 任意模型提問
@@ -28,7 +28,7 @@ export async function cmdOpenrouterAsk(positionals, flags) {
   }
 
   // ── 組裝 adapter（直接使用，不經 createLLM factory，保留完整選項控制）──
-  const { OpenRouterAdapter } = await import('../../lib/core/adapters/openrouter.mjs');
+  const { OpenRouterAdapter } = await import('../_core/adapters/openrouter.mjs');
   const adapter = new OpenRouterAdapter({
     model:        flags.model || undefined,               // 預設由 adapter DEFAULTS 決定
     maxTokens:    flags['max-tokens'] ? parseInt(flags['max-tokens']) : undefined,
@@ -47,10 +47,10 @@ export async function cmdOpenrouterAsk(positionals, flags) {
       // ── 非串流模式：等待完整回應 ──
       const result = await adapter.generateContent(askParams);
       if (format === 'json') {
-        const { formatJsonOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        const { formatJsonOutput } = await import('../_core/openrouter-ask.mjs');
         process.stdout.write(formatJsonOutput(result, adapter.model, elapsed()) + '\n');
       } else {
-        const { formatTextOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        const { formatTextOutput } = await import('../_core/openrouter-ask.mjs');
         process.stdout.write(formatTextOutput(result) + '\n');
         if (!flags.quiet) {
           const p = result.perf || {};
@@ -86,7 +86,7 @@ export async function cmdOpenrouterAsk(positionals, flags) {
       }
 
       if (format === 'json') {
-        const { formatJsonOutput } = await import('../../lib/flows/openrouter-ask.mjs');
+        const { formatJsonOutput } = await import('../_core/openrouter-ask.mjs');
         process.stdout.write(formatJsonOutput(meta || {}, adapter.model, elapsed()) + '\n');
       } else {
         process.stdout.write('\n');

package/modules/openrouter/index.mjs

@@ -0,0 +1,49 @@
+// modules/openrouter/index.mjs — OpenRouter AI 提問模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'openrouter';
+
+export const schema = {
+  name: 'openrouter',
+  description: 'OpenRouter AI 提問（400+ 模型，支援網路搜尋）',
+  requires_sqlite: false,
+  subcommands: {
+    ask: '向 OpenRouter 任意模型提問（支援串流 + 網路搜尋）',
+    models: '列出常用模型（含網路搜尋支援說明）',
+  },
+  options: {
+    '--model=<名稱>': { type: 'string', default: 'openai/gpt-4o-mini', description: '模型名稱（任意 OpenRouter 模型 ID，可加 :online 後綴）' },
+    '--web-search': { type: 'boolean', default: false, description: '啟用網路搜尋（plugins: web，適用所有模型）' },
+    '--max-results=N': { type: 'integer', default: 5, description: '搜尋最大結果數（--web-search 時有效）' },
+    '--system-prompt=<文字>': { type: 'string', default: '', description: '系統提示詞' },
+    '--max-tokens=N': { type: 'integer', default: 8192, description: '最大輸出 tokens' },
+    '--temperature=N': { type: 'number', default: 0.7, description: '溫度（0.0~2.0）' },
+    '--no-stream': { type: 'boolean', default: false, description: '停用串流（等待完整回應）' },
+    '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr，GNU parallel 友善）' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式（json 含 sources、usage、perf，適合 Agentic AI）' },
+  },
+  examples: [
+    'bh openrouter ask "台灣今日重要新聞" --web-search',
+    'bh openrouter ask "分析 React vs Vue" --model=anthropic/claude-sonnet-4-6',
+    'bh openrouter ask "最新 AI 研究" --model=perplexity/sonar-pro --format=json',
+    'echo "解釋量子糾纏" | bh openrouter ask --model=openai/gpt-4o',
+    'bh openrouter ask "整理今天新聞" --web-search --quiet --format=json | jq .text',
+    'bh openrouter models',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdOpenrouterAsk, cmdOpenrouterModels } = await import('./command.mjs');
+  switch (subcommand) {
+    case 'ask': await cmdOpenrouterAsk(positionals, flags); break;
+    case 'models': cmdOpenrouterModels(flags); break;
+    default:
+      if (!subcommand) {
+        const { showCommandHelp } = await import('../../bin/commands/help.mjs');
+        showCommandHelp('openrouter', { openrouter: schema });
+      } else {
+        process.stderr.write(`openrouter: 未知子指令 ${subcommand}\n`);
+        process.exit(1);
+      }
+  }
+}

package/modules/portal/index.mjs

@@ -0,0 +1,17 @@
+// modules/portal/index.mjs — 智慧入口模組自動註冊介面（預留）
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'portal';
+
+export const schema = {
+  name: 'portal',
+  description: '智慧入口（預留）',
+  requires_sqlite: false,
+  subcommands: { status: '顯示入口狀態' },
+  options: {},
+  examples: ['bh portal status'],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  process.stdout.write('portal 模組尚在開發中\n');
+}

package/{bin/commands/search.mjs → modules/search/command.mjs}

@@ -1,12 +1,12 @@
 // bin/commands/search.mjs — search 指令群組（query）
-import * as paths from '../../lib/core/paths.mjs';
-import { timer, jsonOut, emitError, readStdin } from '../../lib/core/cli-utils.mjs';
+import * as paths from '../_core/paths.mjs';
+import { timer, jsonOut, emitError, readStdin } from '../_core/cli-utils.mjs';
 
 export async function cmdSearch(subcommand, positionals, flags) {
   const elapsed = timer();
   const format = flags.format || 'text';
   const project = flags.project || 'nstc';
-  const { DocStore } = await import('../../lib/core/db.mjs');
+  const { DocStore } = await import('../_core/db.mjs');
   const dbPathVal = flags.db || paths.dbPath(project);
   const limit = flags.limit ? parseInt(flags.limit) : null;
 

package/modules/search/index.mjs

@@ -0,0 +1,23 @@
+// modules/search/index.mjs — FTS5 全文檢索模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'search';
+
+export const schema = {
+  name: 'search',
+  description: 'FTS5 trigram 全文檢索',
+  requires_sqlite: true,
+  subcommands: { query: '搜尋關鍵字' },
+  options: {
+    '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+    '--db=<DB路徑>': { type: 'string', description: 'SQLite 資料庫路徑' },
+    '--limit=N': { type: 'integer', description: '限制結果數量' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: ['bh search query "研究計畫" --project=nstc'],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdSearch } = await import('./command.mjs');
+  await cmdSearch(subcommand, positionals, flags);
+}

package/{lib/search/index.mjs → modules/search/search-lib.mjs}

@@ -1,7 +1,7 @@
 // lib/search/index.mjs — 搜尋模組入口
 // 整合 FTS5 全文檢索與聯網搜尋
 
-export { DocStore } from '../core/db.mjs';
+export { DocStore } from '../_core/db.mjs';
 export { crawl } from './crawler.mjs';
 
 // TODO: 實作統一搜尋介面

package/{bin/commands/skill.mjs → modules/skill/command.mjs}

@@ -1,7 +1,7 @@
-// bin/commands/skill.mjs — skill 指令群組（list / show / search）
+// modules/skill/command.mjs — skill 指令群組（list / show / search）
 // 無參數 → 列出全部技能
 // 不認識的子指令 → 當關鍵字做全文模糊搜尋
-import { timer, jsonOut, emitError, logProgress } from '../../lib/core/cli-utils.mjs';
+import { timer, jsonOut, emitError, logProgress, VERSION } from '../_core/cli-utils.mjs';
 
 /**
  * skill 指令主路由
@@ -20,7 +20,7 @@ export async function cmdSkill(subcommand, positionals, flags) {
   // --help（可能被 parseArgs 當成 subcommand）
   if (!subcommand || subcommand === '--help' || subcommand === '-h') {
     if (subcommand === '--help' || subcommand === '-h' || flags.help) {
-      const { showCommandHelp } = await import('./help.mjs');
+      const { showCommandHelp } = await import('../../bin/commands/help.mjs');
       showCommandHelp('skill'); return;
     }
     // 無參數 → 列出全部
@@ -38,14 +38,50 @@ export async function cmdSkill(subcommand, positionals, flags) {
   }
 }
 
-/** list — 列出所有技能（依系列分組） */
+/**
+ * 簡易 semver 比較：a > b 回傳 1，a < b 回傳 -1，相等回傳 0
+ */
+function semverCompare(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+/**
+ * 非阻塞檢查 npm registry 最新版本，本地較舊時在 stderr 提醒
+ * @param {string} currentVersion - 目前版本
+ */
+function checkLatestVersion(currentVersion) {
+  const url = 'https://registry.npmjs.org/botrun-horse/latest';
+  fetch(url, { signal: AbortSignal.timeout(3000) })
+    .then(r => r.ok ? r.json() : null)
+    .then(data => {
+      if (!data?.version) return;
+      if (semverCompare(data.version, currentVersion) > 0) {
+        process.stderr.write(
+          `\n⬆ 有新版本 v${data.version}（目前 v${currentVersion}）\n` +
+          `  更新指令: npx -y botrun-horse@latest skill\n\n`,
+        );
+      }
+    })
+    .catch(() => {}); // 網路失敗靜默忽略
+}
+
+/** list — 列出所有技能（依建立時間排序） */
 async function cmdSkillList(flags) {
   const elapsed = timer();
   const format = flags.format || 'text';
-  const { listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
+  const { listPrompts } = await import('./prompt-store.mjs');
 
   const all = listPrompts();
 
+  // 非阻塞版本檢查
+  checkLatestVersion(VERSION);
+
   if (format === 'json') {
     const data = all.map(p => ({
       slug: p.slug,
@@ -57,6 +93,7 @@ async function cmdSkillList(flags) {
     return;
   }
 
+  process.stdout.write(`botrun-horse v${VERSION} — ${all.length} 個技能\n\n`);
   for (let i = 0; i < all.length; i++) {
     if (i > 0) process.stdout.write('\n');
     process.stdout.write(all[i].rawContent + '\n');
@@ -74,12 +111,12 @@ async function cmdSkillShow(positionals, flags) {
     process.exit(1);
   }
 
-  const { getPrompt, listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
+  const { getPrompt, listPrompts } = await import('./prompt-store.mjs');
   let skill = getPrompt(slug);
 
   // 智慧 fallback：精確 slug 找不到 → 自動轉搜尋
   if (!skill) {
-    const { searchPrompts } = await import('../../lib/prompt/prompt-search.mjs');
+    const { searchPrompts } = await import('./prompt-search.mjs');
     const all = listPrompts();
     const results = searchPrompts(all, slug);
 
@@ -131,8 +168,8 @@ async function cmdSkillSearch(positionals, flags) {
     process.exit(1);
   }
 
-  const { listPrompts } = await import('../../lib/prompt/prompt-store.mjs');
-  const { searchPrompts } = await import('../../lib/prompt/prompt-search.mjs');
+  const { listPrompts } = await import('./prompt-store.mjs');
+  const { searchPrompts } = await import('./prompt-search.mjs');
 
   const all = listPrompts();
   const results = searchPrompts(all, query);

package/modules/skill/index.mjs

@@ -0,0 +1,35 @@
+// modules/skill/index.mjs — 技能模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'skill';
+
+export const schema = {
+  name: 'skill',
+  description: '技能管理（無參數=全列出，帶關鍵字=模糊搜尋）— 零框架技能系列',
+  requires_sqlite: false,
+  subcommands: {
+    '(無)': '列出所有技能（依系列分組）',
+    '<關鍵字>': '模糊搜尋技能（加權全文比對）',
+    list: '列出所有技能（同無參數）',
+    show: '顯示指定技能全文（支援智慧 fallback 搜尋）',
+    search: '模糊搜尋技能（同 <關鍵字>）',
+  },
+  options: {
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+    '--quiet': { type: 'boolean', default: false, description: '靜默模式' },
+  },
+  examples: [
+    'bh skill                         # 列出全部技能',
+    'bh skill 零幻覺                   # 模糊搜尋「零幻覺」',
+    'bh skill show botrun-horse-coding',
+    'bh skill show botrun-horse-coding | pbcopy',
+    'bh skill show botrun-horse-coding --format=json',
+    'bh skill search 換位思考',
+    'bh skill show 切片               # 智慧 fallback：slug 不存在 → 自動搜尋',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdSkill } = await import('./command.mjs');
+  await cmdSkill(subcommand, positionals, flags);
+}

package/{lib/prompt → modules/skill}/prompt-search.mjs

@@ -1,4 +1,4 @@
-// lib/prompt/prompt-search.mjs — 加權評分模糊搜尋
+// modules/skill/prompt-search.mjs — 加權評分模糊搜尋
 // 依 slug/name → description → content 順序加權比對
 // SKILL.md 標準 frontmatter（name, description）
 

package/{lib/prompt → modules/skill}/prompt-store.mjs

@@ -1,12 +1,14 @@
-// lib/prompt/prompt-store.mjs — 技能 Repository 層
-// 掃描 lib/prompt/prompts/ 目錄，解析 YAML frontmatter，提供 listPrompts / getPrompt
+// modules/skill/prompt-store.mjs — 技能 Repository 層
+// 掃描 modules/skill/prompts/ 目錄，解析 YAML frontmatter，提供 listPrompts / getPrompt
 
 import fs from 'fs';
 import path from 'path';
-import { root } from '../core/paths.mjs';
+import { fileURLToPath } from 'url';
 
-/** 技能目錄（相對於專案根目錄） */
-const PROMPTS_DIR = () => path.join(root(), 'lib', 'prompt', 'prompts');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 技能目錄（相對於本模組目錄） */
+const PROMPTS_DIR = () => path.join(__dirname, 'prompts');
 
 /**
  * 零依賴 YAML frontmatter 解析
@@ -29,23 +31,38 @@ export function parseFrontmatter(content) {
 }
 
 /**
- * 遞迴掃描目錄下所有 .md 檔案
+ * 遞迴收集目錄下所有 .md 檔案（含建立時間）
  * @param {string} dir - 起始目錄
  * @param {string} baseDir - 根目錄（用於計算相對路徑）
- * @returns {string[]} 相對路徑陣列
+ * @returns {{ relPath: string, birthMs: number }[]}
  */
-function scanMarkdownFiles(dir, baseDir) {
+function collectMarkdownFiles(dir, baseDir) {
   const results = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...scanMarkdownFiles(fullPath, baseDir));
+      results.push(...collectMarkdownFiles(fullPath, baseDir));
     } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
-      results.push(path.relative(baseDir, fullPath));
+      results.push({
+        relPath: path.relative(baseDir, fullPath),
+        birthMs: fs.statSync(fullPath).birthtimeMs,
+      });
     }
   }
-  return results.sort();
+  return results;
+}
+
+/**
+ * 掃描目錄下所有 .md 檔案，依建立時間排序
+ * @param {string} dir - 起始目錄
+ * @param {string} baseDir - 根目錄（用於計算相對路徑）
+ * @returns {string[]} 相對路徑陣列（依建立時間排序，同時間依檔名字母序）
+ */
+function scanMarkdownFiles(dir, baseDir) {
+  return collectMarkdownFiles(dir, baseDir)
+    .sort((a, b) => a.birthMs - b.birthMs || a.relPath.localeCompare(b.relPath))
+    .map(r => r.relPath);
 }
 
 /**

package/modules/skill/prompts/zero-framework/address-matching.md

@@ -0,0 +1,22 @@
+---
+name:           botrun-horse-address-matching
+description:    零框架地址比對 — 母體地址正規化 JSONL、雜湊表 O(1) 快速比對、AI 大腦判斷 top 5、處理缺路名難字全半形門牌不符
+---
+
+地址比對分三階段，避免全中華民國 2300 萬筆母體地址 token 爆漿：
+
+階段一：母體地址正規化
+用 MJS 程式碼將母體地址 CSV 正規化成 JSONL 格式，拆解成程式碼比對需要的結構欄位（縣市、鄉鎮市區、里、鄰、路街、段、巷、弄、號、樓）。
+
+階段二：程式碼快速比對
+建立雜湊表（Hash Map），用地址標準化後的 key 做 O(1) 查詢。對來源地址做相同正規化後比對，輸出相似度最高的 top 5 候選結果。程式碼比對速度約 0.1 秒。
+
+階段三：AI 大腦精準判斷
+將 top 5 候選結果交給大模型，用自然語言理解判斷最終匹配結果。程式碼幫你過濾掉一大堆，大腦就輕鬆了。
+
+常見地址問題處理：
+- 缺路名、缺里鄰資訊
+- 難字（UTF-8/UTF-16 編碼問題）
+- 全形半形不一致
+- 門牌號碼與實際地址不符
+- 停用字與冗餘字元清理

package/modules/skill/prompts/zero-framework/data-integrity.md

@@ -0,0 +1,15 @@
+---
+name:           botrun-horse-data-integrity
+description:    零框架數據完整性檢查 — MJS 程式碼缺值偵測、格式一致性驗證、缺失比例統計、異常代碼列表、HTML 結果報告
+---
+
+我要做程式碼 MJS，然後要做數據完整性檢查，幫我做完之後輸出 HTML 結果報告說明。
+
+檢查項目：
+1. 缺值偵測：逐欄位統計缺失筆數與缺失比例，標示大於 5% 缺失的欄位
+2. 格式一致性驗證：各欄位資料型別是否一致、日期格式是否統一、編碼是否正確
+3. 異常代碼列表：列出不在預期代碼集合內的異常值
+4. 視覺化分佈：使用 Plotly 繪製各欄位分佈圖（不要用其他視覺化套件，Plotly 最穩定）
+
+資料量大時先抽樣（預設 5 萬筆），也可指定不抽樣跑全部。
+最終輸出為可直接開啟的 HTML 結果報告。

package/modules/skill/prompts/zero-framework/data-reasonability.md

@@ -0,0 +1,17 @@
+---
+name:           botrun-horse-data-reasonability
+description:    零框架數據合理性檢查 — MJS 程式碼值域範圍驗證、時間分佈異常偵測、年增率趨勢統計、統計顯著性門檻、HTML 結果報告
+---
+
+幫我執行此任務用 MJS，然後啟動 HTML 技能生成結論報告給我。
+
+合理性檢查項目：
+1. 值域範圍：各欄位最大值與最小值是否在合理區間，標示超出範圍的異常值（例如年份出現 2076 年）
+2. 時間分佈：第一筆與最後一筆的時間範圍、是否存在未來日期或過早日期
+3. 趨勢統計：年增率是否異常跳動
+4. 統計顯著性：資料筆數是否小於 30（統計顯著性門檻）
+5. 邏輯交叉驗證：欄位之間的邏輯關係是否合理（例如出生年份不應晚於登記年份）
+
+分級呈現：嚴重問題、警告項目、合邏輯比例
+資料量大時先抽樣（預設 5 萬筆），也可指定不抽樣跑全部。
+視覺化使用 Plotly。最終輸出為可直接開啟的 HTML 結果報告。

package/modules/skill/prompts/zero-framework/gemini-image-gen.md

@@ -0,0 +1,20 @@
+---
+name:           botrun-horse-gemini-image-gen
+description:    零框架 Gemini 繪圖 — Nano Banana 2 (`gemini-3.1-flash-image-preview`) 繪圖模組，CLI + Hono API、Session 修改、繁體中文 Prompt
+---
+
+幫我查 modules 是否已經包含 Gemini 繪圖模組，若尚未有，建立一個 new module 在 ./modules/ 底下。
+
+上網查 Gemini Nano Banana 2（模型 ID: `gemini-3.1-flash-image-preview`）該怎麼繪圖，上網查清楚最新 API 之後才開始製作。
+
+利用這個模型製作一個繪圖專用的 MJS API，放在 modules 底下，並且：
+- 要支援繁體中文下達 prompt
+- 要支援 Hono API 產生圖片
+- 要支援 CLI 直接產生圖片
+- 要支援 session 改變既有圖片
+
+同時支援 CLI 和 Hono API，分開做也要弄，統整也要弄，整合到現有的 npm 可以調用的 CLI 和 Hono API 統整。
+
+然後用 ./parallel-dag-todo-list/ 檔案追蹤平行做。
+
+驗證採用 BDD TDD SOLID DRY KISS DDD 製作。

package/modules/skill/prompts/zero-framework/gemini-search-cli.md

@@ -0,0 +1,10 @@
+---
+name:           botrun-horse-gemini-search-cli
+description:    零框架 Gemini Search 動態搜尋 CLI — Gemini-3-Flash-Preview 即時上網搜尋、Grounding Search、URL Context、本地快取加速、串流 TTFT 最佳化
+---
+
+我們現在要去做出一個檢索是輸入自然語言的 MJS 的 CLI，你幫我放在適當的位置。自然語言提問以後，我要你呼叫的是 Gemini-3-Flash-Preview 這個大模型。這大模型它可以做上網搜尋，所以它可以做 Grounding Search。它可以做 URL Context Fetch，兩個工具都可以用，你就可以上網去抓資料了。但是它有一個 Thinking Budget，反正它的 Thinking Budget 肯定把它設定到最低最低，最少最少。
+
+然後接下來，在最快的時間之內，因為它是即時問答，所以你要越短的描述越好，不能想太久。一問、一搜、一答，就趕快答出來了。然後已經回答的答案你就把它存在快取裡面。下一次你再提問的時候你可以從快取，快取的做法是這樣：你在 ./CACHE 裡面，你把每一次回答的都有一個標題，然後有一個 .txt。所以當你在提問的時候你先把你有過的檔案的 TXT 檔名列表先丟給 MJS。如果大模型發現快取裡面有的，就直接調快取就不用上網搜尋也不用問大模型了，直接出來了。如果沒有的，在快取裡面的檔案列表都沒有的，那你就透過真實呼叫 Gemini-3-Flash-Preview 上網搜尋把它給回答掉。
+
+你回答的時候 Max Token 的數量，因為這應用場景是人類問答，回答的數量也不用太多，最多 2K 就好了。你要先上網搜尋最新的 SDK API，我會給你一個 Gemini API Key，你就用 Gemini 的 Direct API，然後利用它在 .env 裡面去完成這個 MJS 的 command line 的撰寫，然後把它透過 BDD、TDD、SOLID、DRY、KISS 還有 DDD 的方式去設計它，然後驗證測試到過關為止，謝謝你。

package/modules/skill/prompts/zero-framework/html-report.md

@@ -0,0 +1,15 @@
+---
+name:           botrun-horse-html-report
+description:    零框架 HTML 報告 — 數據分析結果生成可直接開啟的 HTML 結果報告、Plotly 視覺化圖表、分級摘要、專業排版
+---
+
+請啟動 HTML 技能生成結論報告給我。
+
+報告規格：
+1. 輸出為單一 HTML 檔案，可直接用瀏覽器開啟，不需額外伺服器
+2. 視覺化圖表使用 Plotly（CDN 載入），不要用其他視覺化套件
+3. 報告結構：摘要總覽 → 分級問題清單（嚴重/警告/正常）→ 詳細數據表格 → 視覺化圖表
+4. 排版專業清晰，適合列印或簡報使用
+5. 所有數據必須是真正執行程式碼計算出來的結果，禁止模擬或捏造數字
+
+注意：請你真的去執行程式碼以後給我真的 HTML 報告，不要產出模擬資料的報告。