ainovel-cli

ainovel-cli (Bản Tiếng Việt & Đa Ngôn Ngữ)

Công cụ dòng lệnh (CLI) sáng tác tiểu thuyết dài kỳ tự động bằng AI với kiến trúc Đa Agent (Multi-Agent)

Điểm Nổi Bật Của Bản Việt Hóa & Đa Ngôn Ngữ

• Giao diện TUI Việt hóa 100%: Từ Setup Wizard cài đặt ban đầu, màn hình chào mừng, thanh trạng thái, Activity stream trực tiếp, bảng quản lý Provider/Model (/config, /model) đến thông báo lỗi và phím tắt đều được dịch sang Tiếng Việt chuẩn mực, tự nhiên.
• Tùy chọn Ngôn ngữ sáng tác truyện: Hỗ trợ viết truyện bằng Tiếng Việt (mặc định) hoặc Tiếng Trung nguyên bản qua trường "language": "vi" hoặc "language": "zh" trong cấu hình.
• Tích hợp sẵn Ollama Local: Hỗ trợ chạy 100% offline, miễn phí không tốn tiền API với các model mã nguồn mở chạy trên GPU nội bộ (Qwen 2.5 / 3.5, Llama, v.v.).
• ✍️ Bộ Prompt song ngữ & Văn phong chống AI sáo rỗng: 14 prompt hệ thống được tinh chỉnh kỹ lưỡng, kèm file quy chuẩn văn phong tiểu thuyết Tiếng Việt (assets/voice.md) giúp hành văn sống động, gãy gọn, có chiều sâu, bài trừ các mẫu câu sáo rỗng của AI.
• Đồng bộ toàn diện Upstream mới nhất: Sở hữu đầy đủ kiến trúc Đa Agent (Coordinator → Architect → Writer → Editor → Arbiter), Prompt Caching 3 tầng, quy hoạch cuộn 2 tầng (Rolling planning), điểm phục hồi step-level, và toàn bộ 14 lệnh slash commands.

Mục Lục

1. Yêu Cầu Hệ Thống
2. Cài Đặt & Khởi Chạy Nhanh
3. Tùy Chọn Ngôn Ngữ Sáng Tác
4. Cấu Hình Nhà Cung Cấp AI (LLM)
   • Dùng Ollama Cục Bộ (100% Offline)
   • Dùng Cloud API (OpenRouter, Gemini, Claude, OpenAI, DeepSeek)
   • Phối hợp nhiều Model theo vai trò
5. Hướng Dẫn Sử Dụng & Bảng Lệnh TUI
   • Khởi động TUI & Chế độ sáng tác
   • Danh sách Lệnh Điều Khiển (Slash Commands)
   • Can thiệp thời gian thực (Steer)
   • Chế độ chạy ngầm (Headless)
6. Quản Lý Nhiều Bộ Truyện Độc Lập
7. Tính Năng Nâng Cao
   • Chẩn đoán truyện (/diag)
   • Mô phỏng văn phong (/simulate)
   • Đồng bộ sửa đổi thủ công (/sync)
   • Nhập truyện bên ngoài (/import)
   • Xuất truyện hoàn chỉnh (/export TXT/EPUB)
8. Kiến Trúc Kỹ Thuật & Nguyên Lý Hoạt Động
   • Kiến trúc Đa Agent
   • Quy hoạch cuộn 2 tầng (Rolling Planning)
   • Quản lý & Nén ngữ cảnh 4 cấp
   • Đánh giá chất lượng 7 chiều của Editor
   • Khôi phục điểm ngắt (Step-level Recovery)
9. Cấu Trúc Thư Mục Đầu Ra
10. Tùy Biến Văn Phong & Quy Tắc Cá Nhân
11. Tech Stack & License

1. Yêu Cầu Hệ Thống

• Khuyến nghị nhất: Docker & Docker Desktop (Windows / macOS / Linux).
• Hoặc chạy từ Source: Máy tính đã cài đặt Go ≥ 1.21.
• LLM:
  • Máy có GPU (Nvidia VRAM ≥ 12GB) nếu muốn chạy Ollama cục bộ với model Qwen 2.5 / 3.5.
  • Hoặc API Key từ OpenRouter, Anthropic, Google Gemini, OpenAI, DeepSeek.

2. Cài Đặt & Khởi Chạy Nhanh

Bước 1: Clone Repo & Chuẩn Bị Thư Mục

git clone https://github.com/kentjuno/ainovel-cli.git
cd ainovel-cli

# Tạo thư mục chứa cấu hình và thư mục chứa truyện
mkdir -p config workspace novels

Bước 2: Build Docker Image

docker compose build

(Nếu build từ source Go: go build -o ainovel-cli ./cmd/ainovel-cli)

Bước 3: Khởi Chạy TUI

docker compose run --rm ainovel

(Nếu chạy từ file binary: ./ainovel-cli)

Lần đầu chạy, hệ thống sẽ tự động bật Setup Wizard tương tác bằng Tiếng Việt để bạn chọn Provider, nhập API Key/Base URL, chọn Model và Ngôn ngữ sáng tác.

3. Tùy Chọn Ngôn Ngữ Sáng Tác

Trong file cấu hình config/config.json, bạn có thể chỉ định trường "language":

• "language": "vi" (Mặc định): Toàn bộ dàn ý, nhân vật, bối cảnh thế giới, quy chuẩn văn phong chống AI và nội dung từng chương sẽ được sinh ra bằng Tiếng Việt tự nhiên, mượt mà.
• "language": "zh": Nội dung truyện được sinh ra bằng Tiếng Trung nguyên bản (phù hợp nếu bạn viết truyện Trung hoặc muốn dùng công cụ dịch sau).

Ghi chú: Bảng điều khiển TUI, thanh trạng thái, menu và các thông báo lỗi luôn hiển thị 100% bằng Tiếng Việt.

4. Cấu Hình Nhà Cung Cấp AI (LLM)

File cấu hình đặt tại config/config.json:

Dùng Ollama Cục Bộ (100% Offline)

1. Tạo model trên Ollama với Context Window lớn (65536 tokens):
   • Trên PowerShell (Windows):
     powershell复制

     @"
     FROM qwen2.5:14b
     PARAMETER num_ctx 65536
     "@ | Out-File -FilePath "$env:TEMP\ainovel.Modelfile" -Encoding ascii
     
     ollama create ainovel-qwen -f "$env:TEMP\ainovel.Modelfile"

2. Nội dung config/config.json:
   json复制

   {
     "language": "vi",
     "provider": "ollama",
     "model": "ainovel-qwen",
     "providers": {
       "ollama": {
         "base_url": "http://host.docker.internal:11434/v1",
         "stream_idle_timeout": "300s"
       }
     },
     "context_window": 65536,
     "thinking": "off",
     "style": "default"
   }

   ⚠️ Lưu ý mạng Docker: Khi chạy bằng Docker, bắt buộc dùng http://host.docker.internal:11434/v1. Nếu chạy binary trực tiếp trên máy không qua Docker, dùng http://localhost:11434/v1.

Dùng Cloud API (OpenRouter, Gemini, Claude, OpenAI, DeepSeek)

OpenRouter:

{
  "language": "vi",
  "provider": "openrouter",
  "model": "anthropic/claude-3.5-sonnet",
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-YOUR_OPENROUTER_API_KEY"
    }
  },
  "context_window": 128000,
  "thinking": "off",
  "style": "default"
}

Google Gemini:

{
  "language": "vi",
  "provider": "gemini",
  "model": "gemini-2.5-pro",
  "providers": {
    "gemini": {
      "api_key": "YOUR_GEMINI_API_KEY"
    }
  },
  "context_window": 1000000,
  "style": "default"
}

DeepSeek API:

{
  "language": "vi",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "providers": {
    "deepseek": {
      "api_key": "YOUR_DEEPSEEK_API_KEY"
    }
  },
  "context_window": 64000,
  "style": "default"
}

Phối hợp nhiều Model theo vai trò

Hệ thống cho phép gán model mạnh (Claude 3.5 Sonnet / DeepSeek Reasoner) làm Biên tập / Kiến trúc sư và model rẻ/nhanh (DeepSeek Chat / Ollama) làm Người viết:

{
  "language": "vi",
  "provider": "ollama",
  "model": "ainovel-qwen",
  "providers": {
    "ollama": { "base_url": "http://host.docker.internal:11434/v1" },
    "openrouter": { "api_key": "sk-or-v1-YOUR_KEY" }
  },
  "roles": {
    "architect": { "provider": "openrouter", "model": "anthropic/claude-3.5-sonnet" },
    "editor": { "provider": "openrouter", "model": "anthropic/claude-3.5-sonnet" },
    "writer": { "provider": "ollama", "model": "ainovel-qwen" }
  },
  "context_window": 65536,
  "style": "default"
}

5. Hướng Dẫn Sử Dụng & Bảng Lệnh TUI

Khởi động TUI & Chế độ sáng tác

Chạy lệnh:

docker compose run --rm ainovel

Tại màn hình chào mừng:

• Phím Tab: Chuyển đổi giữa 2 chế độ:
  • Bắt đầu nhanh: Nhập 1 câu tóm tắt ý tưởng (ví dụ: "Tiểu thuyết tiên hiệp phàm nhân, nhân vật chính cơ trí, quyết đoán"), AI tự động lập dàn ý và sáng tác ngay.
  • Đồng sáng tác (Co-create): AI sẽ trao đổi cùng bạn từng bước để làm rõ thiết lập thế giới, nhân vật, cốt truyện trước khi viết.
• Phím Enter: Bắt đầu quá trình sáng tác.
• Phím /: Mở thanh tìm kiếm và thực thi lệnh nhanh (Slash Commands).
• Ctrl+C 2 lần: Lưu an toàn toàn bộ trạng thái và thoát ra.

Danh sách Lệnh Điều Khiển (Slash Commands)

Khi đang ở trong giao diện TUI, bạn có thể gõ / để mở bảng chọn lệnh:

Can thiệp thời gian thực (Steer)

Trong lúc AI đang viết, bạn có thể nhập trực tiếp ý kiến sửa đổi vào ô nhập liệu bên dưới bất cứ lúc nào mà không cần tạm dừng hay khởi động lại:

❯ Cho nhân vật phụ A hy sinh ở cuối chương này để tạo bước ngoặt cảm xúc lớn

Sau khi nhấn Enter, Arbiter sẽ tự động đánh giá phạm vi ảnh hưởng và điều phối Writer/Editor cập nhật mạch truyện.

Chế độ chạy ngầm (Headless)

Dành cho việc chạy tự động trên VPS, Server hoặc CI:

# Bắt đầu truyện mới
docker compose run --rm ainovel --headless --prompt "Tiểu thuyết huyền nghi đô thị phá án"

# Viết tiếp truyện đang dở trong thư mục hiện tại
docker compose run --rm ainovel --headless

6. Quản Lý Nhiều Bộ Truyện Độc Lập

Mặc định output sẽ lưu vào thư mục workspace/. Để viết nhiều bộ truyện khác nhau mà không bị xung đột, hãy đặt biến môi trường NOVEL_DIR:

# Trên Windows PowerShell:
$env:NOVEL_DIR = ".\novels\tien-hiep-ky"
docker compose run --rm ainovel

# Viết bộ truyện khác:
$env:NOVEL_DIR = ".\novels\do-thi-di-nang"
docker compose run --rm ainovel

Cấu trúc thư mục đầu ra của mỗi truyện:

novels//output/novel/
├── chapters/            # Các chương hoàn chỉnh đã duyệt (.md)
├── drafts/              # Bản nháp và dàn ý chi tiết từng chương
├── reviews/             # Báo cáo đánh giá của Editor
├── summaries/           # Tóm tắt từng Cung và Tập
├── premise.md           # Ý tưởng & tiền đề cốt truyện
├── characters.md        # Hồ sơ thiết lập nhân vật
├── world_rules.md       # Thiết lập quy tắc thế giới
└── meta/                # Checkpoint, tiến độ, nhật ký token

7. Tính Năng Nâng Cao

Chẩn đoán truyện (/diag)

Gõ /diag trong TUI để hệ thống tự động kiểm tra toàn bộ truyện theo 4 chiều:

• Tiến trình: Phát hiện vòng lặp viết lại, kẹt lệnh can thiệp, nhảy số chương.
• Chất lượng: Theo dõi điểm số đánh giá, tỷ lệ tuân thủ cốt truyện, độ dài chương bất thường.
• Quy hoạch: Kiểm tra các nút thắt/phục bút bị bỏ quên, dàn ý cạn kiệt, thiếu tóm tắt.
• Ngữ cảnh: Nhân vật bị mất tích, đứt gãy dòng thời gian.

Mô phỏng văn phong (/simulate)

Đặt các file văn mẫu (truyện của tác giả bạn yêu thích) vào thư mục simulate/ rồi gõ /simulate. AI sẽ phân tích nhịp điệu, cách dùng từ, cấu trúc câu v