Imported from reason-machines/devtools-skills (skills/ainovel-cli-vietnamese/SKILL.md). Install upstream with npx skills add reason-machines/devtools-skills --skill ainovel-cli-vietnamese. Copyright stays with the author.

ainovel-cli Vietnamese Skill

Skill by ara.so — Devtools Skills collection.

Overview

ainovel-cli (Vietnamese fork) is an autonomous multi-agent CLI system for long-form Vietnamese novel generation. It orchestrates three specialized agents (Architect, Writer, Editor) through a single LLM loop to produce complete novels from a one-sentence prompt, with support for 500+ chapters, real-time intervention, and automatic checkpoint recovery.

Key capabilities:

• Fully autonomous writing pipeline (world-building → outline → drafting → editing)
• 3-tier context management (chapter → arc → volume) with automatic compression
• Rolling planning: arcs/volumes expand progressively, avoiding empty outlines
• Step-level checkpointing: recovers from crashes, network loss, or Ctrl+C
• Real-time intervention: inject feedback without stopping the process
• 7-dimension quality evaluation (consistency, character, pacing, narrative, foreshadowing, hooks, aesthetics)
• Anti-AI-writing mechanics: built-in criteria to detect and avoid robotic prose
• Multi-provider LLM support: OpenRouter, Anthropic, Gemini, OpenAI, Deepseek, Ollama (local)

Installation

Docker (Recommended)

# Clone the repository
git clone https://github.com/kentjuno/ainovel-cli.git
cd ainovel-cli

# Create directories
mkdir -p config workspace

# Build image
docker build -t ainovel-cli-vi .

# Run TUI
docker run --rm -it \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  -e TERM=xterm-256color \
  ainovel-cli-vi

Windows PowerShell:

docker run --rm -it `
  -v "${PWD}\config:/root/.ainovel" `
  -v "${PWD}\workspace:/workspace" `
  -e TERM=xterm-256color `
  ainovel-cli-vi

Build from Source

git clone https://github.com/kentjuno/ainovel-cli.git
cd ainovel-cli
go build -o ainovel-cli ./cmd/ainovel-cli/

# Run
./ainovel-cli  # Linux/macOS
ainovel-cli.exe  # Windows

Requirements:

• Go ≥ 1.21
• Docker ≥ 24 (for Docker method)
• 4GB free RAM

Configuration

Create config/config.json (Docker) or ~/.ainovel/config.json (source build).

Ollama (Local, Free)

# Install Ollama: https://ollama.com
# Pull model (12B+ recommended)
ollama pull gemma4:12b

config.json:

{
  "provider": "ollama",
  "model": "gemma4:12b",
  "providers": {
    "ollama": {
      "base_url": "http://host.docker.internal:11434/v1",
      "models": ["gemma4:12b", "qwen3.5:27b"]
    }
  }
}

On Linux Docker, use 172.17.0.1 instead of host.docker.internal

OpenRouter

{
  "provider": "openrouter",
  "model": "google/gemini-2.5-flash",
  "providers": {
    "openrouter": {
      "api_key": "${OPENROUTER_API_KEY}",
      "base_url": "https://openrouter.ai/api/v1",
      "models": [
        "google/gemini-2.5-flash",
        "google/gemini-2.5-pro",
        "anthropic/claude-sonnet-4"
      ]
    }
  }
}

Anthropic

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "providers": {
    "anthropic": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "models": ["claude-sonnet-4-6", "claude-opus-4"]
    }
  }
}

Role-Specific Models

Assign different models to each agent role:

{
  "provider": "openrouter",
  "model": "google/gemini-2.5-flash",
  "providers": {
    "openrouter": {
      "api_key": "${OPENROUTER_API_KEY}",
      "base_url": "https://openrouter.ai/api/v1"
    },
    "anthropic": {
      "api_key": "${ANTHROPIC_API_KEY}"
    }
  },
  "roles": {
    "coordinator": {
      "provider": "openrouter",
      "model": "google/gemini-2.5-flash"
    },
    "architect": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6"
    },
    "writer": {
      "provider": "openrouter",
      "model": "google/gemini-2.5-flash"
    },
    "editor": {
      "provider": "openrouter",
      "model": "google/gemini-2.5-flash"
    }
  }
}

Core Commands

Starting a Novel

Launch TUI and enter your prompt in the input field:

Short prompt (system expands automatically):

Cung đấu gia tộc, nhân vật chính xuất thân thấp kém nhưng tài năng ẩn giấu

Detailed prompt (more control):

Tiểu thuyết fantasy cổ đại Việt Nam, nhân vật chính là cô gái nghèo bị bán vào phủ làm tỳ nữ.
Thể loại: cung đấu + ngôn tình. Khoảng 80 chương. Nhân vật nam chính: vương gia lạnh lùng nhưng
thực ra bảo vệ nàng từ bóng tối. Kết thúc có hậu. Viết theo phong cách truyện ngôn tình Việt.

TUI Commands

Type / in the input field to see command list:

Headless Mode

Run without TUI (server/automation):

docker run --rm \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  ainovel-cli-vi \
  --headless \
  --prompt "Viết tiểu thuyết cung đấu, nhân vật chính là cô lao công xuất thân thấp kém"

With custom output:

docker run --rm \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  ainovel-cli-vi \
  --headless \
  --output /workspace/my-novel \
  --prompt "Xuyên không vào game MMORPG, nhân vật chính là NPC buôn bán"

Real-Time Intervention

Inject feedback while writing is ongoing:

Example intervention:

Chương vừa rồi quá nhanh. Hãy bổ sung thêm mô tả tâm lý nhân vật khi họ đối mặt với quyết định khó khăn.

The system will:

1. Evaluate impact scope (affects current chapter only? or entire arc?)
2. Rewrite affected content
3. Continue from corrected state

When to intervene:

• Character acting out of character
• Plot hole detected
• Pacing too fast/slow
• Tone inconsistent with earlier chapters

Customizing Style and Rules

Custom Rules File

Create workspace/<novel-name>/custom_rules.md:

# Quy tắc tuỳ chỉnh

## Phong cách văn
- Dùng ngôn ngữ cổ điển, tránh từ hiện đại
- Đối thoại ngắn gọn, sắc bén
- Mô tả cảnh quan tỉ mỉ nhưng không rườm rà

## Nhân vật
- Nữ chính: kiên cường, thông minh, nhưng dễ tổn thương
- Nam chính: lạnh lùng bề ngoài, nội tâm sâu sắc
- Tránh nhân vật phụ trở thành "công cụ phục vụ cốt truyện"

## Cốt truyện
- Mỗi chương phải có ít nhất 1 xung đột nhỏ
- Tránh giải quyết mâu thuẫn quá dễ dàng
- Phục bút phải tự nhiên, không ép buộc

## Cấm
- KHÔNG dùng "đột nhiên", "bỗng chốc"
- KHÔNG để nhân vật giải thích cảm xúc thẳng thừng ("tôi cảm thấy buồn")
- KHÔNG kết thúc chương bằng cliffhanger giả tạo

The system reads this file automatically and enforces rules during writing.

Anti-AI Writing Checks

Built-in detection (automatically applied):

Mechanical checks:

• Forbidden phrases: "đột nhiên", "bỗng chốc", "tựa hồ như"
• Emotion telling vs. showing: flags direct statements like "cô ấy buồn"
• Adverb overuse: detects excessive "-ly" equivalents in Vietnamese

Semantic checks:

• Character consistency: compares current actions with character profile
• Plot coherence: validates against established world rules
• Foreshadowing tracking: ensures setup elements get payoff

Override checks:

# In custom_rules.md
## Ngoại lệ
- Cho phép "đột nhiên" trong cảnh hành động nhanh
- Cho phép giải thích cảm xúc khi nhân vật tự vấn

Checkpoint Recovery

System auto-saves after every successful tool call. Recovery is automatic on restart.

Manual recovery:

# Resume from last checkpoint (default behavior)
./ainovel-cli

# Resume specific novel
./ainovel-cli --resume /workspace/my-novel

Checkpoint structure:

workspace/
└── my-novel/
    ├── checkpoint.json          # Last successful step
    ├── progress.json            # Overall progress tracker
    ├── outline/                 # Architect output
    │   ├── world.json
    │   ├── characters.json
    │   └── arc_001.json
    ├── drafts/                  # Writer output
    │   ├── chapter_001_v1.md
    │   └── chapter_001_v2.md    # After rewrite
    └── final/                   # Published chapters
        └── chapter_001.md

Recovery scenarios:

• Crash/Ctrl+C: Resumes from last checkpoint
• Network timeout: Retries failed API call, continues from last success
• Manual intervention: Checkpoint created after correction applied

Output Structure

workspace/
└── <novel-name>/
    ├── config.json              # Novel-specific config
    ├── progress.json            # Current writing state
    ├── checkpoint.json          # Recovery point
    ├── custom_rules.md          # User-defined rules (optional)
    ├── outline/
    │   ├── world.json           # World-building
    │   ├── characters.json      # Character profiles
    │   ├── volume_001.json      # Volume outline
    │   ├── arc_001_001.json     # Arc outline (volume 1, arc 1)
    │   └── ...
    ├── drafts/
    │   ├── chapter_001_v1.md    # First draft
    │   ├── chapter_001_v2.md    # After editor feedback
    │   └── ...
    ├── final/
    │   ├── chapter_001.md       # Published version
    │   ├── chapter_002.md
    │   └── ...
    └── exports/
        ├── novel.txt            # Plain text export
        └── novel.epub           # EPUB export

Exporting Novels

Text Export

# Via TUI command
/export

# Default output: workspace/<novel-name>/exports/novel.txt

Custom location:

/export ~/Documents/my-novel.txt

EPUB Export

/export ~/Documents/my-novel.epub

EPUB metadata: The system reads from workspace/<novel-name>/metadata.json:

{
  "title": "Cung Đấu Kiến Trúc",
  "author": "AI Multi-Agent System",
  "language": "vi",
  "description": "Một câu chuyện về...",
  "cover": "cover.jpg"
}

If missing, defaults are used (title from folder name, author "ainovel-cli").

Common Patterns

Pattern: Custom Character Development

# In custom_rules.md

## Quy tắc phát triển nhân vật

### Giai đoạn 1 (chương 1-20): Khởi đầu
- Nữ chính: ngây thơ, dễ bị lợi dụng
- Mỗi 5 chương: 1 sự kiện tổn thương nhỏ (dần cứng rắn)

### Giai đoạn 2 (chương 21-50): Trưởng thành
- Nữ chính bắt đầu chủ động
- Quan hệ với nam chính: từ sợ → tò mò → tin tưởng

### Giai đoạn 3 (chương 51-80): Đỉnh cao
- Nữ chính nắm quyền lực
- Đối đầu với phản diện chính

## Công cụ phát triển
- Sử dụng flashback tiết kiệm (tối đa 1 lần/10 chương)
- Mỗi arc phải có 1 "điểm không thể quay lại"

Pattern: Automated Quality Gates

// In workspace/<novel-name>/config.json
{
  "quality_gates": {
    "min_words_per_chapter": 3000,
    "max_words_per_chapter": 6000,
    "editor_threshold": 7,
    "max_rewrites_per_chapter": 2,
    "auto_pause_on_low_score": true
  }
}

When editor score < 7, system pauses and waits for intervention.

Pattern: Multi-POV Switching

# In custom_rules.md

## POV
- Chương chẵn: POV nữ chính
- Chương lẻ: POV nam chính
- Chương kết arc: POV phản diện (1 lần duy nhất)

## Quy tắc POV
- Không chuyển POV giữa chương
- Dùng ngôi thứ 3 nhìn sát vai
- Mỗi POV có giọng văn riêng (nữ chính: mềm mại; nam chính: ngắn gọn)

Pattern: Foreshadowing Tracker

System automatically tracks foreshadowing elements:

// Auto-generated in workspace/<novel-name>/foreshadowing.json
{
  "items": [
    {
      "id": "fh_001",
      "setup_chapter": 3,
      "content": "Chiếc bình ngọc trong kho báu",
      "expected_payoff_arc": 2,
      "status": "pending"
    },
    {
      "id": "fh_002",
      "setup_chapter": 7,
      "content": "Lời tiên tri về người cứu thế",
      "payoff_chapter": 45,
      "status": "resolved"
    }
  ]
}

Use /diag to check unresolved foreshadowing.

Troubleshooting

Issue: Ollama Model Not Responding

Symptoms:

• Timeout errors
• Empty responses

Solution:

# Check Ollama is running
curl http://localhost:11434/api/tags

# Docker: verify network access
docker run --rm curlimages/curl:latest \
  curl http://host.docker.internal:11434/api/tags

# Linux: use host IP instead
docker run --rm curlimages/curl:latest \
  curl http://172.17.0.1:11434/api/tags

Update config.json with correct base_url.

Issue: Novel Gets Stuck in Loop

Symptoms:

• Coordinator repeats same steps
• No progress for 10+ API calls

Solution:

# Run diagnostics
/diag

# Check output for:
# - "Loop detected: architect called 5 times for same arc"
# - "Writer stuck on chapter X for 3 iterations"

Fix:

1. Use /pause
2. Manually edit workspace/<novel-name>/progress.json:

   {
     "current_step": "writing",
     "current_chapter": 15,
     "stuck_counter": 0  // Reset this
   }

3. /resume

Or inject intervention: "Bỏ qua chương hiện tại, tiếp tục chương kế tiếp"

Issue: Character Acting Inconsistently

Symptoms:

• Character behavior contradicts earlier chapters

Solution:

1. Check workspace/<novel-name>/outline/characters.json
2. Verify character profile is detailed enough:

   {
     "name": "Lý Thanh Vân",
     "personality": [
       "kiên cường",
       "thông minh",
       "dễ tổn thương khi đối mặt với gia đình"
     ],
     "values": [
       "trung thành với người đáng tin",
       "ghét sự lừa dối",
       "không bao giờ từ bỏ"
     ],
     "growth_arc": "từ ngây thơ → thực dụng → bi quan → cân bằng"
   }

3. If profile is shallow, intervene:

   Nhân vật Thanh Vân không được phản ứng như vậy. Cô ấy ghét lừa dối nhất,
   nên phải đối mặt trực tiếp thay vì lẩn tránh. Viết lại cảnh này.
   

Issue: EPUB Export Fails

Symptoms:

• /export novel.epub shows error
• Missing metadata

Solution:

1. Check workspace/<novel-name>/final/ has chapters
2. Create metadata.json:

   {
     "title": "Tên Tiểu Thuyết",
     "author": "Tên Tác Giả",
     "language": "vi",
     "description": "Mô tả ngắn gọn"
   }

3. Retry export

Issue: Docker Permission Denied (Linux)

Symptoms:

• Cannot write to workspace/ or config/

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Or run with correct permissions
docker run --rm -it \
  -v "$PWD/config:/root/.ainovel" \
  -v "$PWD/workspace:/workspace" \
  --user $(id -u):$(id -g) \
  ainovel-cli-vi

Issue: Model Refuses to Follow Protocol

Symptoms:

• Coordinator makes invalid tool calls
• JSON parsing errors

Solution:

• Models < 14B struggle with complex protocols
• Switch to larger model:

  {
    "roles": {
      "coordinator": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6"
      }
    }
  }

• Or use instruction-tuned models: Qwen, Gemma, Claude

Issue: High API Costs

Symptoms:

• Unexpected bill from provider

Solution:

1. Monitor token usage in logs:

   grep "tokens_used" workspace/<novel-name>/logs/*.log

2. Switch expensive roles to cheaper models:

   {
     "roles": {
       "writer": {
         "provider": "openrouter",
         "model": "google/gemini-2.5-flash"  // Cheaper than Claude
       }
     }
   }

3. Use Ollama for drafting, cloud models for editing:

   {
     "roles": {
       "writer": { "provider": "ollama", "model": "qwen3.5:27b" },
       "editor": { "provider": "anthropic", "model": "claude-sonnet-4-6" }
     }
   }

Advanced Usage

Programmatic API (Go)

package main

import (
    "github.com/kentjuno/ainovel-cli/pkg/core"
    "github.com/kentjuno/ainovel-cli/pkg/config"
)

func main() {
    cfg := config.Load("config.json")
    
    novel := core.NewNovel(cfg)
    novel.SetPrompt("Viết truyện xuyên không về lập trình viên")
    
    // Start autonomous writing
    novel.Start()
    
    // Inject intervention during writing
    novel.Intervene("Thêm chi tiết về công nghệ AI trong thế giới game")
    
    // Export when done
    novel.Export("novel.epub")
}

Batch Processing

# Process multiple prompts
cat prompts.txt | while read prompt; do
  docker run --rm \
    -v "$PWD/config:/root/.ainovel" \
    -v "$PWD/workspace:/workspace" \
    ainovel-cli-vi \
    --headless \
    --prompt "$prompt" \
    --output "/workspace/batch_$(date +%s)"
done

Custom Agent Extension

Extend the Writer agent with custom logic:

// In pkg/agents/writer/custom.go
package writer

func (w *Writer) CustomPreProcess(chapter *Chapter) error {
    // Add custom validation before writing
    if chapter.Number%10 == 0 {
        // Every 10th chapter gets special treatment
        chapter.Style = "climax"
    }
    return nil
}

Build with custom code:

go build -tags custom -o ainovel-cli-custom ./cmd/ainovel-cli/

This skill covers the core usage patterns for ainovel-cli Vietnamese edition. The system is designed for autonomous operation, so the primary skill is knowing when and how to intervene, not constant manual control.