跳轉到

CLI 概覽

gonovelmaker 提供強大的命令列介面（CLI），讓您能夠高效管理小說專案、生成內容和匯出成果。

設計理念

CLI 工具設計遵循以下原則：

  • 🎯 直觀易用：命令名稱清晰明瞭，參數設計合理
  • 🔄 工作流導向：支援完整的創作工作流程
  • 📊 結構化輸出：支援 JSON 格式，便於整合與自動化
  • 🔧 靈活設定：支援設定檔和命令列參數

基本用法

novelmaker-obs [command] [flags]

查看所有可用命令：

novelmaker-obs --help

查看特定命令的說明：

novelmaker-obs [command] --help

命令分類

專案管理

初始化和管理小說專案結構：

命令 功能 用途
init 初始化專案 建立新的小說專案結構
scan 掃描專案 分析現有專案內容
config-check 檢查設定 驗證設定檔是否正確

後端管理

管理 LLM 後端設定：

命令 功能 用途
backend add 新增/編輯後端 設定 LLM API 後端
backend list 列出後端 查看所有已設定的後端
backend list-available-models 列出可用模型 查詢後端支援的所有模型
backend check 檢查後端 測試後端連線是否正常
backend use 設定預設後端 切換使用的後端
backend remove 移除後端 刪除後端設定

內容生成

使用 AI 生成小說內容：

命令 功能 用途
chapter gen-next 生成下一章節 基於現有內容生成新章節
chapter regen 重新生成章節 重新生成現有章節
chapter gen-empty 建立空白章節 建立章節範本供手動撰寫
character gen 生成角色 建立新的角色檔案
character regen 重新生成角色 更新現有角色描述
character gen-img 生成角色圖片 使用 DALL-E 生成角色圖像

匯出與外掛

匯出內容和管理外掛：

命令 功能 用途
export 匯出小說 將完整小說匯出為文字檔
update-plugin 更新外掛 更新 Obsidian Novel Maker 外掛

通用參數

全域旗標

這些旗標可用於所有命令：

旗標 簡寫 說明 預設值
--help -h 顯示命令說明 -
--version -v 顯示版本資訊 -

常用旗標

某些命令共用的旗標：

旗標 簡寫 說明 適用命令
--json -j 輸出 JSON 格式 scan, gen-*
--model - 覆蓋文字模型 gen-*
--timeout - 設定 API 超時 gen-*

工作流程

典型創作流程

graph LR
    A[初始化專案] --> B[設定後端]
    B --> C[生成角色]
    C --> D[生成章節]
    D --> E{繼續創作?}
    E -->|是| D
    E -->|否| F[匯出小說]

命令使用順序

  1. 初始化專案 

    novelmaker-obs init

  2. 設定 LLM 後端 

    # 新增後端
novelmaker-obs backend add openai \
  --type openai \
  --api_key "sk-xxx" \
  --model "gpt-4o"

# 設為預設
novelmaker-obs backend use openai

# 檢查連線
novelmaker-obs backend check openai

  3. 建立世界觀和角色 

    novelmaker-obs character gen --name "主角" --prompt "主角設定"

  4. 生成章節 

    novelmaker-obs chapter gen-next --title "第一章"

  5. 檢視專案狀態 

    novelmaker-obs scan

  6. 匯出成果 

    novelmaker-obs export --output novel.txt --type txt

輸出格式

標準輸出

預設情況下，命令會以人類可讀的格式輸出：

✅ 專案初始化成功！
📁 專案路徑: /path/to/your/vault
📖 已建立範例檔案：
  - Config/project.md
  - Character/character_sample.md
  - Story/001_prologue.md

JSON 輸出

使用 --json 旗標取得結構化輸出：

{
  "success": true,
  "project_path": "/path/to/your/vault",
  "files_created": [
    "Config/project.md",
    "Character/character_sample.md",
    "Story/001_prologue.md"
  ]
}

自動化整合

JSON 輸出非常適合整合到 CI/CD 流程或自訂腳本中。

設定優先順序

當多個來源提供相同設定時，優先順序為：

  1. 命令列參數（最高優先）
  2. 設定檔 (~/.novelmaker/config.toml)
  3. 預設值（最低優先）

範例：

# 設定檔中設定 model = "gpt-4o"
# 但命令列覆蓋為 gpt-4o-mini
novelmaker-obs chapter gen-next --title "測試" --model gpt-4o-mini

效能考量

批次操作

對於大量操作，建議：

  1. 使用 --json 輸出便於解析
  2. 適當設定 --timeout 避免長時間等待
  3. 考慮使用腳本自動化重複任務

API 用量優化

  • 使用 chapter gen-empty 建立草稿，手動編輯後再生成
  • 調整 --prev-chapters 參數控制上下文大小
  • 使用較小的模型（如 gpt-4o-mini）進行測試

下一步