botrun-horse 2.31.0 → 2.35.0

package/bin/bh.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // bin/bh.mjs — botrun-horse CLI 總入口（路由分派）
-// 多專案架構：lib 放腦、projects 放料、bin/commands/ 放各指令群組
+// 所有指令模組由 modules/*/index.mjs 自動註冊
 //
 // 用法:
 //   node bin/bh.mjs <指令群組> [子指令] [選項]
@@ -8,11 +8,19 @@
 //
 // 所有指令皆支援 --project=<名稱>、--format=json、stdin pipe、--quiet、--print0
 
-import { setupHttpProxy } from '../lib/core/proxy.mjs';
+import path from 'path';
+import { loadEnv } from '../modules/_core/env.mjs';
+loadEnv(); // 載入專案根目錄 .env
+loadEnv(path.join(process.cwd(), '.env'), { override: false }); // 載入使用者 cwd/.env（npx 情境）
+
+import { setupHttpProxy } from '../modules/_core/proxy.mjs';
 setupHttpProxy(); // 必須在所有 fetch 呼叫之前執行（含 @google/genai、Anthropic SDK）
 
-import { parseArgs, VERSION } from '../lib/core/cli-utils.mjs';
-import { COMMANDS } from './commands/schema.mjs';
+import { parseArgs, VERSION } from '../modules/_core/cli-utils.mjs';
+import { discoverModules, collectSchemas } from '../modules/discover.mjs';
+
+const _modules = await discoverModules();
+const COMMANDS = collectSchemas(_modules);
 
 const { command, subcommand, flags, positionals } = parseArgs(process.argv);
 
@@ -21,178 +29,42 @@ if (flags.version || command === '--version' || command === '-V') {
   process.stdout.write(`${VERSION}\n`); process.exit(0);
 }
 
-// ===== Help 快速路由 =====
-if (flags.help && !command) {
+// ===== Help =====
+if (!command || command === 'help' || command === '--help' || command === '-h') {
   const { showHelp } = await import('./commands/help.mjs');
-  showHelp(flags); process.exit(0);
+  showHelp(flags, COMMANDS); process.exit(0);
 }
-if (flags.help && command) {
+if (flags.help) {
   const { showCommandHelp } = await import('./commands/help.mjs');
-  showCommandHelp(command); process.exit(0);
+  showCommandHelp(command, COMMANDS); process.exit(0);
 }
 
-// ===== 指令路由 =====
-switch (command) {
-  case 'doc': {
-    const { cmdDocSplit, cmdDocText, cmdDocIngest } = await import('./commands/doc.mjs');
-    switch (subcommand) {
-      case 'split': await cmdDocSplit(positionals, flags); break;
-      case 'text': await cmdDocText(positionals, flags); break;
-      case 'ingest': await cmdDocIngest(positionals, flags); break;
-      default: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('doc');
-        else { process.stderr.write(`doc: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
-    }
-    break;
-  }
-
-  case 'writing': {
-    const { cmdWritingGenerate } = await import('./commands/writing.mjs');
-    switch (subcommand) {
-      case 'generate': await cmdWritingGenerate(flags); break;
-      default: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('writing');
-        else { process.stderr.write(`writing: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
-    }
-    break;
-  }
-
-  case 'gemini': {
-    const { cmdGeminiAsk } = await import('./commands/gemini.mjs');
-    switch (subcommand) {
-      case 'ask': await cmdGeminiAsk(positionals, flags); break;
-      default: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('gemini');
-        else { process.stderr.write(`gemini: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
-    }
-    break;
-  }
-
-  case 'nchc': {
-    const { cmdNchcAsk, cmdNchcAgent, cmdNchcCode, cmdNchcModels } = await import('./commands/nchc.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: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('nchc');
-        else { process.stderr.write(`nchc: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
-    }
-    break;
-  }
-
-  case 'openrouter': {
-    const { cmdOpenrouterAsk, cmdOpenrouterModels } = await import('./commands/openrouter.mjs');
-    switch (subcommand) {
-      case 'ask': await cmdOpenrouterAsk(positionals, flags); break;
-      case 'models': cmdOpenrouterModels(flags); break;
-      default: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('openrouter');
-        else { process.stderr.write(`openrouter: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
+// ===== commands schema =====
+if (command === 'commands') {
+  const format = flags.format || 'json';
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({
+      _meta: { tool: 'bh', version: VERSION, description: 'botrun-horse 多專案文件處理系統' },
+      commands: COMMANDS,
+    }, null, 2) + '\n');
+  } else {
+    process.stdout.write(`botrun-horse v${VERSION} — 可用指令:\n\n`);
+    for (const [name, cmd] of Object.entries(COMMANDS)) {
+      const sqlite = cmd.requires_sqlite ? ' [需 --experimental-sqlite]' : '';
+      process.stdout.write(`  ${name.padEnd(12)} ${cmd.description}${sqlite}\n`);
     }
-    break;
-  }
-
-  case 'legal': {
-    const { cmdLegalAsk, cmdLegalCacheList, cmdLegalCacheStats } = await import('./commands/legal.mjs');
-    switch (subcommand) {
-      case 'ask': await cmdLegalAsk(positionals, flags); break;
-      case 'cache': {
-        // legal cache {list|stats}
-        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: {
-        const { showCommandHelp } = await import('./commands/help.mjs');
-        if (!subcommand) showCommandHelp('legal');
-        else { process.stderr.write(`legal: 未知子指令 ${subcommand}\n`); process.exit(1); }
-      }
-    }
-    break;
-  }
-
-  case 'dag': {
-    const { cmdDag } = await import('./commands/dag-cmd.mjs');
-    await cmdDag(subcommand, flags);
-    break;
-  }
-
-  case 'search': {
-    const { cmdSearch } = await import('./commands/search.mjs');
-    await cmdSearch(subcommand, positionals, flags);
-    break;
-  }
-
-  case 'db': {
-    const { cmdDb } = await import('./commands/db-cmd.mjs');
-    await cmdDb(subcommand, flags);
-    break;
-  }
-
-  case 'commands': {
-    const format = flags.format || 'json';
-    if (format === 'json') {
-      process.stdout.write(JSON.stringify({
-        _meta: { tool: 'bh', version: VERSION, description: 'botrun-horse 多專案文件處理系統' },
-        commands: COMMANDS,
-      }, null, 2) + '\n');
-    } else {
-      process.stdout.write(`botrun-horse v${VERSION} — 可用指令:\n\n`);
-      for (const [name, cmd] of Object.entries(COMMANDS)) {
-        const sqlite = cmd.requires_sqlite ? ' [需 --experimental-sqlite]' : '';
-        process.stdout.write(`  ${name.padEnd(12)} ${cmd.description}${sqlite}\n`);
-      }
-      process.stdout.write(`\n各指令皆支援 --help、--format=json、--project=<名稱>、--quiet、--print0\n`);
-    }
-    break;
-  }
-
-  case 'skill': {
-    const { cmdSkill } = await import('./commands/skill.mjs');
-    await cmdSkill(subcommand, positionals, flags);
-    break;
-  }
-
-  case 'portal':
-    process.stdout.write('portal 模組尚在開發中\n');
-    break;
-
-  case 'ocr':
-    process.stdout.write('ocr 模組尚在開發中\n');
-    break;
-
-  case 'help':
-  case '--help':
-  case '-h':
-  case undefined: {
-    const { showHelp } = await import('./commands/help.mjs');
-    showHelp(flags);
-    break;
+    process.stdout.write(`\n各指令皆支援 --help、--format=json、--project=<名稱>、--quiet、--print0\n`);
   }
+  process.exit(0);
+}
 
-  default: {
-    process.stderr.write(`未知指令: ${command}\n`);
-    const { showHelp } = await import('./commands/help.mjs');
-    showHelp();
-    process.exit(1);
-  }
+// ===== 模組自動路由 =====
+const mod = _modules.get(command);
+if (mod) {
+  await mod.handler(subcommand, positionals, flags);
+} else {
+  process.stderr.write(`未知指令: ${command}\n`);
+  const { showHelp } = await import('./commands/help.mjs');
+  showHelp(flags, COMMANDS);
+  process.exit(1);
 }

package/bin/commands/help.mjs

@@ -1,8 +1,7 @@
 // bin/commands/help.mjs — 說明輸出（showHelp / showCommandHelp）
-import { parseArgs, VERSION } from '../../lib/core/cli-utils.mjs';
-import { COMMANDS } from './schema.mjs';
+import { parseArgs, VERSION } from '../../modules/_core/cli-utils.mjs';
 
-export function showCommandHelp(cmdName) {
+export function showCommandHelp(cmdName, COMMANDS = {}) {
   const cmd = COMMANDS[cmdName];
   if (!cmd) return;
 
@@ -20,7 +19,7 @@ export function showCommandHelp(cmdName) {
     lines.push('');
   }
   lines.push('用法:');
-  const prefix = cmd.requires_sqlite ? 'node --experimental-sqlite bin/bh.mjs' : 'node bin/bh.mjs';
+  const prefix = cmd.requires_sqlite ? 'node --experimental-sqlite bin/bh.mjs' : 'bh';
   if (cmd.subcommands) {
     lines.push(`  ${prefix} ${cmd.name} <子指令> [選項]`);
     lines.push('');
@@ -46,7 +45,7 @@ export function showCommandHelp(cmdName) {
   process.stdout.write(lines.join('\n') + '\n');
 }
 
-export function showHelp(flags = {}) {
+export function showHelp(flags = {}, COMMANDS = {}) {
   if (flags.format === 'json') {
     process.stdout.write(JSON.stringify({
       _meta: { tool: 'bh', version: VERSION, description: 'botrun-horse 多專案文件處理系統' },
@@ -63,26 +62,27 @@ export function showHelp(flags = {}) {
     return;
   }
 
+  // 從 COMMANDS 動態產生指令列表
+  const cmdLines = [];
+  for (const [name, cmd] of Object.entries(COMMANDS)) {
+    const sqlite = cmd.requires_sqlite ? ' [需 --experimental-sqlite]' : '';
+    const subs = cmd.subcommands
+      ? Object.keys(cmd.subcommands).filter(s => !s.startsWith('(') && !s.startsWith('<')).join('|')
+      : '';
+    const suffix = subs ? ` (${subs})` : '';
+    cmdLines.push(`  ${name.padEnd(20)} ${cmd.description}${suffix}${sqlite}`);
+  }
+
   process.stdout.write(`
 botrun-horse — 多專案文件處理系統 CLI v${VERSION}
 ===================================================
 
 用法:
-  node bin/bh.mjs <指令群組> [子指令] [選項]
-  node --experimental-sqlite bin/bh.mjs <指令>    (SQLite 相關功能)
+  bh <指令群組> [子指令] [選項]
+  npx -y botrun-horse <指令群組> [子指令] [選項]
 
 指令群組:
-  doc <子指令>        文件處理 (split|text|ingest)
-  writing <子指令>    公文撰寫 (generate)
-  gemini <子指令>     Gemini AI 提問 (ask) — thinking + grounding + url context
-  nchc <子指令>       國網 GenAI 提問 (ask|agent|code|models) — Mistral 系列
-  dag <子指令>        DAG 依賴追蹤 (init|status|ready|list)
-  search <子指令>     全文檢索 (query) [需 --experimental-sqlite]
-  db <子指令>         資料庫管理 (stats|docs|pages) [需 --experimental-sqlite]
-  skill [關鍵字]      技能管理（無參數=全列出，帶關鍵字=模糊搜尋）
-  portal <子指令>     智慧入口 (預留)
-  ocr <子指令>        OCR 辨識 (預留)
-  commands           所有指令的結構化 JSON schema
+${cmdLines.join('\n')}
 
 共通選項:
   --help             顯示說明
@@ -92,18 +92,18 @@ botrun-horse — 多專案文件處理系統 CLI v${VERSION}
   --quiet            靜默模式（不輸出進度到 stderr，GNU parallel 友善）
   --print0           NUL 分隔路徑輸出（與 xargs -0 相容）
 
-組合範例:
-  # GNU parallel 批次處理
-  find . -name "*.pdf" -print0 | xargs -0 -P 8 node bin/bh.mjs doc text --quiet
-
-  # 文件處理（PDF + Office 全系列）
-  node --experimental-sqlite bin/bh.mjs doc ingest --dir=pdfs/ --project=nstc
-
-  # Gemini AI 提問
-  node bin/bh.mjs gemini ask "量子糾纏的原理是什麼？"
-  echo "解釋 AI" | node bin/bh.mjs gemini ask --format=json
+快速開始 — AI 繪圖:
+  1. 設定環境變數:  export GEMINI_API_KEY=你的金鑰
+     (到 https://aistudio.google.com/apikey 申請)
+  2. 生圖:  bh imagen generate "一隻貓坐在月亮上"
+  3. 進階:  bh imagen generate "科幻城市" --size=2K --aspect=16:9
 
-  # AI/LLM schema 探索
-  node bin/bh.mjs commands --format=json | jq 'keys'
+更多範例:
+  bh imagen generate "logo 設計" --output=logo.png
+  echo "水彩風格的台北101" | bh imagen generate
+  bh imagen edit photo.png "把背景換成日落海灘"
+  bh imagen serve --port=3000
+  bh gemini ask "量子糾纏的原理是什麼？"
+  bh commands --format=json | jq 'keys'
 `);
 }

package/{lib/flows → modules/_core}/draft-writing.mjs

@@ -1,7 +1,7 @@
 // lib/flows/draft-writing.mjs — 公文撰寫業務流程
 // 串接：config → DAG → writing/generate → 更新狀態
 
-import { loadDag, initState, saveState, loadState } from '../core/dag.mjs';
+import { loadDag, initState, saveState, loadState } from './dag.mjs';
 import { generateAll } from '../writing/generate.mjs';
 
 /**

package/{lib/flows → modules/_core}/gemini-ask.mjs

@@ -2,7 +2,7 @@
 // 職責: 組裝 adapter + 格式化輸出 + 效能測量
 // 原則: KISS — 流程越簡單越好，複雜邏輯在 adapter
 
-import { createLLM } from '../core/llm.mjs';
+import { createLLM } from './llm.mjs';
 
 /**
  * 取得臺灣當前時間字串，自動注入 system prompt

package/{lib/flows → modules/_core}/legal-ask.mjs

@@ -15,10 +15,10 @@
 //   { 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';
+import { createLLM } from './llm.mjs';
+import { AiCache } from './ai-cache.mjs';
+import { AiRouter } from './ai-router.mjs';
+import { dbPath as resolveDbPath } from './paths.mjs';
 
 // ── 合併提示詞（單次 request 完成搜尋 + 分析） ─────────────────────────────
 

package/{lib/flows → modules/_core}/openai-agent.mjs

@@ -43,7 +43,7 @@ export {
   CODING_SYSTEM_PROMPT,
   executeTool,
   executeCodeTool,
-} from '../tools/fs-tools.mjs';
+} from './tools/fs-tools.mjs';
 
 import {
   BUILT_IN_TOOLS,
@@ -52,7 +52,7 @@ import {
   CODING_SYSTEM_PROMPT,
   executeTool,
   executeCodeTool,
-} from '../tools/fs-tools.mjs';
+} from './tools/fs-tools.mjs';
 
 // ══════════════════════════════════════════════════════════════════════════
 // NchcAgent — 通用代理（唯讀工具）

package/{lib/flows → modules/_core}/openrouter-ask.mjs

@@ -2,7 +2,7 @@
 // 職責: 組裝 adapter + 格式化輸出
 // 原則: KISS — 流程越簡單越好，複雜邏輯在 adapter
 
-import { createLLM } from '../core/llm.mjs';
+import { createLLM } from './llm.mjs';
 
 /**
  * 執行 OpenRouter 提問流程（非串流）

package/{bin/commands/dag-cmd.mjs → modules/dag/command.mjs}

@@ -1,5 +1,5 @@
 // bin/commands/dag-cmd.mjs — dag 指令群組（init / status / ready / list）
-import { timer, jsonOut, emitError } from '../../lib/core/cli-utils.mjs';
+import { timer, jsonOut, emitError } from '../_core/cli-utils.mjs';
 
 export async function cmdDag(subcommand, flags) {
   if (!subcommand) {
@@ -9,7 +9,7 @@ export async function cmdDag(subcommand, flags) {
   const {
     loadDag, loadState, saveState, initState,
     getReady, formatStatus,
-  } = await import('../../lib/core/dag.mjs');
+  } = await import('../_core/dag.mjs');
   const format = flags.format || 'text';
   const project = flags.project || 'nstc';
 

package/modules/dag/index.mjs

@@ -0,0 +1,30 @@
+// modules/dag/index.mjs — DAG 依賴追蹤模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'dag';
+
+export const schema = {
+  name: 'dag',
+  description: 'DAG 依賴追蹤管理',
+  requires_sqlite: false,
+  subcommands: {
+    init: '初始化 DAG 狀態',
+    status: '顯示整體 DAG 進度摘要',
+    ready: '列出目前可執行的任務',
+    list: '列出所有任務及其狀態',
+  },
+  options: {
+    '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: [
+    'bh dag init --project=nstc',
+    'bh dag status --project=nstc',
+    'bh dag ready --format=json --project=nstc',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdDag } = await import('./command.mjs');
+  await cmdDag(subcommand, flags);
+}

package/{bin/commands/db-cmd.mjs → modules/db/command.mjs}

@@ -1,13 +1,13 @@
 // bin/commands/db-cmd.mjs — db 指令群組（stats / docs / pages）
-import * as paths from '../../lib/core/paths.mjs';
-import { timer, jsonOut, emitError } from '../../lib/core/cli-utils.mjs';
+import * as paths from '../_core/paths.mjs';
+import { timer, jsonOut, emitError } from '../_core/cli-utils.mjs';
 
 export async function cmdDb(subcommand, flags) {
   if (!subcommand) {
     const { showCommandHelp } = await import('./help.mjs');
     showCommandHelp('db'); return;
   }
-  const { DocStore } = await import('../../lib/core/db.mjs');
+  const { DocStore } = await import('../_core/db.mjs');
   const project = flags.project || 'nstc';
   const dbPathVal = flags.db || paths.dbPath(project);
   const format = flags.format || 'text';

package/modules/db/index.mjs

@@ -0,0 +1,26 @@
+// modules/db/index.mjs — SQLite 資料庫管理模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'db';
+
+export const schema = {
+  name: 'db',
+  description: 'SQLite 資料庫管理',
+  requires_sqlite: true,
+  subcommands: {
+    stats: '顯示 DB 統計',
+    docs: '列出所有文件 metadata',
+    'pages <doc_id>': '列出指定文件的所有頁面',
+  },
+  options: {
+    '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+    '--db=<DB路徑>': { type: 'string', description: 'SQLite 路徑' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: ['bh db stats --project=nstc', 'bh db docs --format=json --project=nstc'],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdDb } = await import('./command.mjs');
+  await cmdDb(subcommand, flags);
+}

package/modules/discover.mjs

@@ -0,0 +1,43 @@
+// modules/discover.mjs — 自動掃描 modules/*/index.mjs，回傳模組註冊表
+// Convention over Configuration：放了 index.mjs 就自動生效
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 掃描 modules/ 下所有子目錄的 index.mjs，載入模組定義
+ * @returns {Promise<Map<string, { name, schema, handler }>>}
+ */
+export async function discoverModules() {
+  const modules = new Map();
+  const entries = fs.readdirSync(__dirname, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('_')) continue;
+    const indexPath = path.join(__dirname, entry.name, 'index.mjs');
+    if (!fs.existsSync(indexPath)) continue;
+
+    const mod = await import(indexPath);
+    if (mod.name && mod.handler) {
+      modules.set(mod.name, mod);
+    }
+  }
+
+  return modules;
+}
+
+/**
+ * 收集所有模組的 schema，回傳 { [name]: schema } 物件
+ * @param {Map} modules - discoverModules() 的結果
+ * @returns {object}
+ */
+export function collectSchemas(modules) {
+  const schemas = {};
+  for (const [name, mod] of modules) {
+    if (mod.schema) schemas[name] = mod.schema;
+  }
+  return schemas;
+}

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

@@ -1,15 +1,15 @@
 // bin/commands/doc.mjs — doc 指令群組（split / text / ingest）
 import path from 'path';
-import * as paths from '../../lib/core/paths.mjs';
+import * as paths from '../_core/paths.mjs';
 import {
   resolveFiles, parallelBatch, timer, jsonOut, emitError,
-} from '../../lib/core/cli-utils.mjs';
+} from '../_core/cli-utils.mjs';
 
 export async function cmdDocSplit(positionals, flags) {
   const elapsed = timer();
   const format = flags.format || 'text';
   const project = flags.project || 'nstc';
-  const { splitPdf } = await import('../../lib/doc/split.mjs');
+  const { splitPdf } = await import('./split.mjs');
   const outdir = flags.outdir || path.join(paths.projectOutput(project), 'split');
   const concurrency = parseInt(flags.concurrency) || 5;
   const files = await resolveFiles(positionals, flags);
@@ -61,7 +61,7 @@ export async function cmdDocSplit(positionals, flags) {
 export async function cmdDocText(positionals, flags) {
   const elapsed = timer();
   const format = flags.format || 'text';
-  const { extractAllPages, extractPage } = await import('../../lib/doc/pdf2text.mjs');
+  const { extractAllPages, extractPage } = await import('./pdf2text.mjs');
   const files = await resolveFiles(positionals, flags);
   const pageNum = flags.page ? parseInt(flags.page) : null;
   const concurrency = parseInt(flags.concurrency) || 5;
@@ -115,7 +115,7 @@ export async function cmdDocIngest(positionals, flags) {
   const elapsed = timer();
   const format = flags.format || 'text';
   const project = flags.project || 'nstc';
-  const { ingestOne, ingestDir, ingestBatch } = await import('../../lib/doc/index.mjs');
+  const { ingestOne, ingestDir, ingestBatch } = await import('./ingest.mjs');
   const dbPathVal = flags.db || paths.dbPath(project);
   const concurrency = parseInt(flags.concurrency) || 5;
   const recursive = !!flags.recursive;

package/modules/doc/index.mjs

@@ -0,0 +1,55 @@
+// modules/doc/index.mjs — 文件處理模組自動註冊介面
+// Convention: 每個 modules/<name>/index.mjs 都 export { name, schema, handler }
+
+export const name = 'doc';
+
+export const schema = {
+  name: 'doc',
+  description: '文件處理（拆頁、轉文字、入庫）— 支援 PDF 與 Office 全系列',
+  requires_sqlite: false,
+  subcommands: {
+    split: '通用 PDF 拆頁（每頁輸出為獨立 PDF）',
+    text: 'PDF 轉純文字（保留頁碼與排版，不需先拆頁）',
+    ingest: 'PDF/Office 入庫流水線（轉文字 → SQLite FTS5）[需 --experimental-sqlite]',
+  },
+  options: {
+    '--project=<名稱>': { type: 'string', default: 'nstc', description: '專案名稱' },
+    '--dir=<路徑>': { type: 'string', description: '掃描單一目錄內所有文件' },
+    '--dirs=<路徑1,路徑2>': { type: 'string', description: '掃描多個目錄（逗號分隔）' },
+    '--outdir=<路徑>': { type: 'string', description: '拆頁輸出目錄（split 指令用）' },
+    '--split-pdf': { type: 'boolean', default: false, description: '[ingest] 同時拆頁成獨立 PDF' },
+    '--recursive': { type: 'boolean', default: false, description: '遞迴掃描子目錄' },
+    '--force': { type: 'boolean', default: false, description: '強制重新入庫（忽略斷點續作紀錄）' },
+    '--concurrency=N': { type: 'integer', default: 5, description: '平行處理數' },
+    '--quiet': { type: 'boolean', default: false, description: '靜默模式（不輸出進度到 stderr，GNU parallel 友善）' },
+    '--print0': { type: 'boolean', default: false, description: 'NUL 分隔路徑輸出（與 xargs -0 相容）' },
+    '--format=json|text': { type: 'string', default: 'text', description: '輸出格式' },
+  },
+  examples: [
+    'bh doc split file1.pdf file2.pdf --project=nstc',
+    'bh doc text --dir=projects/nstc/output/pdfs',
+    'node --experimental-sqlite bin/bh.mjs doc ingest --dir=projects/nstc/pdfs --project=nstc',
+    'node --experimental-sqlite bin/bh.mjs doc ingest --dirs=pdfs/,docs/ --project=nstc --recursive',
+    'node --experimental-sqlite bin/bh.mjs doc ingest file.docx report.xlsx --project=nstc',
+    'node --experimental-sqlite bin/bh.mjs doc ingest --dir=pdfs/ --force --split-pdf --project=nstc',
+    'ls pdfs/*.pdf | node --experimental-sqlite bin/bh.mjs doc ingest --project=nstc',
+    'find . -name "*.pdf" -print0 | xargs -0 -P 4 node bin/bh.mjs doc text --quiet',
+  ],
+};
+
+export async function handler(subcommand, positionals, flags) {
+  const { cmdDocSplit, cmdDocText, cmdDocIngest } = await import('./command.mjs');
+  switch (subcommand) {
+    case 'split': await cmdDocSplit(positionals, flags); break;
+    case 'text': await cmdDocText(positionals, flags); break;
+    case 'ingest': await cmdDocIngest(positionals, flags); break;
+    default:
+      if (!subcommand) {
+        const { showCommandHelp } = await import('../../bin/commands/help.mjs');
+        showCommandHelp('doc', { doc: schema });
+      } else {
+        process.stderr.write(`doc: 未知子指令 ${subcommand}\n`);
+        process.exit(1);
+      }
+  }
+}

package/{lib/doc/index.mjs → modules/doc/ingest.mjs}

@@ -21,7 +21,7 @@ import path from 'path';
 import { splitPdf, getPdfPageCount } from './split.mjs';
 import { extractAllPages } from './pdf2text.mjs';
 import { extractOfficePages, extractTextFilePages, isOfficeFile, isTextFile } from './office2text.mjs';
-import { DocStore } from '../core/db.mjs';
+import { DocStore } from '../_core/db.mjs';
 
 // ─────────────────────────────────────────────────────────
 // 核心入庫函式

package/{lib → modules}/doc/office2text.mjs

@@ -24,7 +24,7 @@ import { promisify } from 'node:util';
 import { mkdtemp, rm, readdir, readFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { toolBin } from '../core/paths.mjs';
+import { toolBin } from '../_core/paths.mjs';
 
 const execFileAsync = promisify(execFile);