Hướng dẫn sử dụng

Bắt đầu nhanh

VietPhrase Writer là công cụ viết truyện tích hợp AI, chạy hoàn toàn trên trình duyệt. Dữ liệu lưu trong IndexedDB của trình duyệt — không gửi lên server nào ngoại trừ API AI khi bạn chủ động yêu cầu.

1. Tạo dự án: Nhấn + Dự án mới, đặt tên truyện, chọn chế độ viết (webnovel / văn học / kịch bản).
2. Lấy API key: Mở Cài đặt AI (biểu tượng bánh răng ở panel phải), chọn provider, dán API key. Hướng dẫn chi tiết ↓
3. Xây dựng Thế giới trước: Điền Thông tin sách (thể loại, tóm tắt), sau đó tạo nhân vật, bối cảnh ở panel Thế giới. Muốn nhanh? Dùng AI tạo Thế giới — mô tả ý tưởng truyện, AI tự sinh hàng loạt entry. Xem thêm Best Practices.
4. Viết chương đầu: Gõ trực tiếp vào editor hoặc dùng AI viết tiếp. Nhấn Tab để chấp nhận ghost text, Esc để hủy.
5. Viết tiếp: Chuyển chương, AI tự tóm tắt chương cũ. Sau vài chương, AI sẽ gợi ý tạo recap tích lũy.

Cài đặt ứng dụng

VietPhrase Writer là PWA (Progressive Web App) — có thể cài như app riêng trên mọi thiết bị. Lợi ích:

• Dữ liệu ổn định hơn: App standalone không bị trình duyệt xóa IndexedDB khi clear cache. Trên iOS Safari, web bình thường có thể bị xóa data sau 7 ngày không dùng — app cài rồi thì không.
• Chạy offline: Mở app không cần internet (trừ khi gọi AI).
• Fullscreen: Không thanh địa chỉ, không tab — trải nghiệm như app native.

iPhone / iPad

1. Mở Safari (bắt buộc dùng Safari), truy cập vietphrase.app/writer.html
2. Nhấn nút Chia sẻ (hình vuông có mũi tên lên) ở thanh dưới
3. Cuộn xuống, chọn "Thêm vào Màn hình chính" (Add to Home Screen)
4. Đặt tên (VD: "Writer") → nhấn Thêm

Android

1. Mở Chrome, truy cập vietphrase.app/writer.html
2. Nhấn menu ⋮ (3 chấm) góc phải trên
3. Chọn "Cài đặt ứng dụng" hoặc "Thêm vào màn hình chính"
4. Xác nhận → icon xuất hiện trên màn hình chính

Windows / macOS / Linux

1. Mở Chrome hoặc Edge, truy cập Writer
2. Nhấn biểu tượng cài đặt ở thanh địa chỉ (hình máy tính có mũi tên), hoặc menu → "Cài đặt ứng dụng"
3. Xác nhận → app mở trong cửa sổ riêng, có icon trên taskbar/dock

Lấy API Key

Google Gemini (khuyên dùng — miễn phí)

1. Truy cập aistudio.google.com/apikey
2. Đăng nhập tài khoản Google.
3. Nhấn Create API key → chọn project (hoặc tạo mới) → nhấn Create.
4. Copy key (dạng AIza...), dán vào ô API Key trong Writer.

OpenAI

1. Truy cập platform.openai.com/api-keys
2. Nhấn Create new secret key, copy key (dạng sk-...).
3. Cần nạp credit trước (tối thiểu $5). Chọn provider OpenAI trong Writer.

DeepSeek

1. Truy cập platform.deepseek.com/api_keys
2. Tạo key, nạp credit. Giá rẻ hơn OpenAI nhiều (~$0.14/1M input tokens).

Google Vertex AI

Dùng cho tổ chức hoặc ai cần quota cao hơn free tier. Chọn provider Gemini (Vertex) trong Writer:

1. Tạo project trên Google Cloud Console, bật Vertex AI API.
2. Dán API key vào Cài đặt AI. Dùng key từ AI Studio hoặc service account key.

Custom / OpenAI-Compatible

Chọn provider Custom, nhập URL endpoint và API key. Hỗ trợ bất kỳ API nào theo chuẩn /v1/chat/completions.

Một số provider có free tier đáng thử:

Provider & Model

AI model thay đổi nhanh — mục này hướng dẫn cách chọn thay vì liệt kê model cụ thể. Bạn nên kiểm tra model mới nhất từ provider.

Gemini Free Tier (khuyên dùng)

Google AI Studio cung cấp free tier hào phóng. Dưới đây là các model text có free quota (tham khảo, có thể thay đổi):

Provider trả phí

Nếu cần chất lượng cao hơn hoặc hết free quota:

Model gợi ý cho viết truyện

Viết truyện / roleplay cần model giỏi sáng tạo, nhất quán nhân vật, và hiểu ngữ cảnh dài. Dưới đây là một số model nổi bật (tính đến đầu 2026):

Thiết lập 2 model: Viết + Tóm tắt

Tóm tắt chương và recap là task nhẹ — không cần model mạnh. Trong Cài đặt AI, ô "Model tóm tắt / recap" cho phép đặt model riêng:

• Model chính = Flash thinking (viết sáng tạo, cần chất lượng)
• Model tóm tắt = Flash Lite (nhanh, quota cao, tiết kiệm RPD)

Thinking models & maxTokens

Các thinking model (Gemini Flash, DeepSeek R1...) dùng token cho suy nghĩ trước khi trả lời. Nếu đặt maxTokens quá thấp, phần văn bản sẽ bị cắt vì budget dành cho thinking. Writer mặc định 8192 tokens — đủ cho hầu hết trường hợp. Tăng lên 12K–16K nếu muốn AI viết đoạn dài hơn.

Quy trình viết

Một quy trình viết hiệu quả với Writer:

1. Thiết lập ban đầu: Tạo project → điền Thông tin sách (thể loại, tóm tắt, phong cách) → chọn Chế độ viết.
2. Xây dựng Thế giới: Thêm nhân vật chính, bối cảnh quan trọng. Có thể dùng AI Generate.
3. Viết chương: Gõ trực tiếp hoặc dùng AI hỗ trợ (Viết tiếp / Mở rộng). Dùng Ghi chú chương để định hướng AI.
4. Chuyển chương: Writer tự tóm tắt chương cũ (nếu bật Auto-summary). AI sẽ nhớ nội dung qua summary.
5. Recap: Sau 7+ chương, Writer gợi ý tạo recap tích lũy — tóm tắt toàn bộ truyện để AI nắm bối cảnh lớn.
6. Lặp lại: Viết tiếp, AI tự điều chỉnh ngữ cảnh dựa trên summary + recap + worldbuilding.

Các chế độ AI

Nhấn vào pill đang chọn lần nữa để bỏ chọn → quay về chế độ chat tự do.

Ghost Text

Khi AI trả lời ở các chế độ viết (Viết tiếp, Viết lại...), văn bản hiện dưới dạng ghost text — chữ mờ xám trong editor:

• Tab — Chấp nhận ghost text, chèn vào bài viết
• Esc — Hủy ghost text
• Hoặc bấm nút Chèn trên toolbar của message trong chat

Chat với AI

Bỏ chọn tất cả pill (Viết tiếp, Viết lại...) để vào chế độ chat tự do. Dùng để:

• Hỏi AI ý kiến về cốt truyện, nhân vật
• Brainstorm ý tưởng cho chương tiếp
• Yêu cầu AI phân tích đoạn văn

Mỗi message AI có toolbar: Copy | Chèn (chèn vào editor) | Thử lại (re-generate).

Context Engine

Context Engine quyết định AI biết gì khi trả lời. Mở token bar (thanh "Input ≈ ... tokens" phía trên ô chat) để xem chi tiết.

Context Inspector

Nhấn vào thanh token để mở Context Inspector — xem chính xác những gì AI nhận được:

• Tag xanh: các phần luôn bật (chế độ viết, thông tin sách, nguyên tắc)
• Tag thế giới: từng entry worldbuilding được trigger, kèm biểu tượng lý do (★ always, 🔑 keyword)
• Tag overflow: entry bị loại vì vượt token budget

Tóm tắt & Recap

Tóm tắt chương (Summary)

AI tạo bản tóm tắt ~150 từ cho mỗi chương, ghi nhận:

• Sự kiện chính
• Chi tiết cần nhớ (tên, số, vật phẩm...)
• Hook chưa giải quyết

Tự động tóm tắt (mặc định bật): Khi chuyển chương, Writer tự chạy summary cho chương vừa rời nếu chương đó >500 từ và chưa có summary. Tắt trong Cài đặt AI nếu muốn tự kiểm soát.

Bạn có thể sửa tay summary bất kỳ lúc nào — ô "Tóm tắt" nằm trong phần meta của chương (sidebar trái).

Recap tích lũy

Khi truyện dài (7+ chương có summary), Writer gợi ý tạo recap — tóm tắt toàn bộ cốt truyện thành ~450 từ. Recap giúp AI nắm bức tranh lớn mà không cần đọc lại từng summary.

Recap tự cập nhật khi đủ điều kiện:

• Lần đầu: ≥7 chương có summary
• Sau đó: 3+ summary mới, hoặc 5000+ từ mới, hoặc 2+ summary bị sửa

Ghi chú chương

Ghi chú chương là công cụ mạnh nhất để điều khiển AI. Nội dung ghi chú được đưa vào cuối system prompt — AI sẽ ưu tiên tuân theo.

Ví dụ ghi chú hiệu quả:

• "Chương này Thanh Vân phát hiện bí mật về sư phụ. Giọng văn căng thẳng, nhiều đối thoại ngắn."
• "Không nhắc đến Dung Nhi. Tập trung vào cảnh chiến đấu ở Huyết Lan Cốc."
• "Kết chương bằng cliffhanger: ai đó xuất hiện bất ngờ."

Nút ✨ cạnh "Ghi chú chương" sẽ dùng AI gợi ý notes dựa trên recap + summary gần nhất.

Vector Memory

Vector Memory cho phép AI "nhớ" chi tiết từ xa trong truyện bằng semantic search. Thay vì chỉ nhớ vài chương gần nhất, AI có thể recall chi tiết từ chương 3 khi đang viết chương 25.

Cách hoạt động

1. Mỗi summary chương + worldbuilding entry được chuyển thành vector (embedding)
2. Khi viết, Writer tìm vector gần nhất với ngữ cảnh hiện tại
3. Kết quả được thêm vào prompt dưới dạng "[Ký ức liên quan]"

Bật Vector Memory

1. Mở Cài đặt AI → phần Vector Memory
2. Bật checkbox "Bật semantic recall từ vector local"
3. Chọn Embedding provider và nhập API key (có thể dùng API key khác với model chính)
4. Nhấn Rebuild vectors để tạo vector cho dữ liệu hiện có

Embedding model khuyên dùng

Worldbuilding cơ bản

Panel Thế giới (sidebar trái) lưu trữ thông tin cố định về truyện: nhân vật, địa điểm, vật phẩm, cốt truyện, thiết lập, nguyên tắc viết.

Danh mục

Tạo entry

1. Chọn tab danh mục → nhấn +
2. Điền tiêu đề, mô tả, ghi chú
3. Đặt keyword (quan trọng!) và chọn chế độ kích hoạt
4. Thêm quan hệ với entry khác nếu cần

Cây phân cấp & Quan hệ

Cây phân cấp (Parent-Child) — Quản lý trực quan

Entry có thể được tổ chức thành cây cha-con để dễ quản lý. Kéo thả entry vào giữa entry khác để biến nó thành con.

🔸 Liên Hoa Môn           (Thiết lập — Always)
   ├ Mạc Huyền Phong      (Nhân vật — Keyword: "Huyền Phong, chưởng môn")
   ├ Châu Thiếu Du        (Nhân vật — Keyword: "Thiếu Du")
   └ Lục Thanh Vân        (Nhân vật — Keyword: "Thanh Vân, Lục Thanh Vân")

Cách tổ chức cây hợp lý:

• Bang phái / tổ chức làm cha → thành viên làm con — gọn sidebar, gập mở nhanh
• Khu vực lớn làm cha → địa điểm cụ thể làm con (VD: "Liên Hoa Sơn" → "Tàng Kinh Các", "Tĩnh Tâm Đường")
• Hệ thống làm cha → chi tiết làm con (VD: "Hệ tu luyện" → "Cảnh giới", "Chiêu thức")

Liên kết quan hệ (Relations) — Kích hoạt liên kết

Relations kết nối các entry với nhau. Mỗi liên kết gồm entry đích + nhãn mô tả quan hệ. Quan trọng: Khi một entry được kích hoạt (keyword match hoặc always), các entry liên kết qua relation cũng tự động được kéo vào context cho AI.

Lục Thanh Vân
  → Mạc Huyền Phong  [chưởng môn, nghi ngờ]
  → Tạ Dung Nhi      [y nữ quen biết, có cảm tình]
  → Châu Thiếu Du    [sư huynh, đối thủ tranh kế vị]
  → Sư phụ Vạn Niên  [sư phụ, mất tích 3 năm]
  → Nguyệt Quang Kiếm [sở hữu]

Tạ Dung Nhi
  → Lục Thanh Vân    [đối tượng chăm sóc]
  → Huyết Liên Hoa   [đang tìm kiếm, cần cho thuốc giải]
  → Huyết Lan Cốc    [nơi giấu bí mật]

Cách tạo relation:

1. Mở entry → nhấn + Liên kết
2. Tìm entry đích (tên hoặc danh mục)
3. Nhập nhãn mô tả quan hệ (VD: "sư muội", "kẻ thù", "sở hữu", "nằm tại")

Tại sao nên dùng Relations?

• Kích hoạt liên kết: Khi entry A trigger, các entry liên kết qua relation tự động được đưa vào context — không cần đặt keyword trùng nhau
• Rõ ràng cho AI: Quan hệ được trình bày riêng biệt, AI hiểu mạng lưới nhân vật chính xác hơn so với đọc văn xuôi "là vợ của X, bạn của Y"
• Cập nhật 1 chỗ: Khi nhân vật đổi phe, chỉ cần sửa nhãn relation — không phải mở từng entry liên quan để sửa mô tả
• Điều hướng nhanh: Click vào chip relation để nhảy sang entry đích

Keyword Activation

Mỗi entry có 3 chế độ kích hoạt:

Token budget

Worldbuilding có giới hạn token (mặc định 2000). Khi tổng entry vượt budget:

• Always được ưu tiên cao nhất
• Keyword tiếp theo
• Manual cuối cùng
• Entry vượt budget bị loại — hiện tag đỏ "overflow" trong Context Inspector

Tăng budget trong Cài đặt AI → "Giới hạn token thế giới" (tối đa 8000).

AI tạo Thế giới

Chuyển sang tab Thế giới trong panel AI (bên phải) để dùng AI generate entries hàng loạt.

Cách dùng

1. Chọn tab Thế giới trong panel AI
2. Mô tả yêu cầu: "Tạo 5 nhân vật chính cho truyện kiếm hiệp, gồm tên, tuổi, tính cách, quan hệ"
3. AI trả về dạng card — mỗi card là 1 entry với đầy đủ thông tin
4. Nhấn Nhập trên từng card, hoặc Nhập tất cả
5. Tiếp tục hội thoại: "Thêm 3 địa điểm quan trọng", "Chi tiết hóa nhân vật X"

Best Practices Worldbuilding

Nguyên tắc "Tảng băng trôi"

Chỉ viết những gì cần thiết để định hình entry. AI không cần tiểu sử 500 từ — chỉ cần đặc điểm nổi bật, động lực, và trạng thái hiện tại. Dùng gạch đầu dòng ngắn thay vì văn xuôi dài.

Tóc trắng, mắt vàng viền mèo, cộc cằn bên ngoài nhưng tốt bụng.
Song kiếm bạc & kẽm, đang tìm con gái nuôi bị bắt cóc.

- Ngoại hình: Tóc trắng, mắt vàng, vết sẹo trên trán
- Tính cách: Cộc cằn bên ngoài, tốt bụng ngầm
- Vũ khí: Song kiếm (bạc & kẽm)
- Động cơ: Tìm con gái nuôi

Bị gãy chân ở ch.15, hiện đi khập khiễng.
Vừa phát hiện bí mật thân thế sư phụ (ch.18).
Đang giấu Nguyệt Quang Kiếm, chưa ai biết.

Diễn biến thế giới (Progressions)

Truyện dài, nhân vật thay đổi: bị thương, chuyển phe, lên level, mất vật phẩm… Nếu phải mở từng entry worldbuilding để cập nhật tay, rất dễ quên. Progressions tự động phát hiện những thay đổi này từ nội dung chương và gợi ý bổ sung vào entry.

Cách hoạt động

1. Khi bạn chuyển chương (hoặc nhấn nút 🔄 trong meta chương), AI đọc nội dung chương vừa viết
2. AI xác định entry nào bị ảnh hưởng (qua keyword + title scan)
3. AI gợi ý các bổ sung / thay thế — hiện dưới dạng panel gợi ý với nút Accept / Reject
4. Bạn duyệt và chấp nhận những gì phù hợp. Progression được gắn vào entry cùng số chương.

Hai loại Progression

Bằng chứng (Evidence)

Mỗi gợi ý progression kèm câu trích dẫn ngắn từ nội dung chương — giúp bạn biết AI dựa vào đâu để đề xuất thay đổi. Bằng chứng hiện trong panel gợi ý và cả trong danh sách progression của entry.

Xem lại Progression

• Trong entry: Mở entry ở panel Thế giới → phần "Diễn biến" liệt kê tất cả progression theo thứ tự chương, kèm bằng chứng.
• Timeline tổng: Nhấn nút ⏱ trên header panel Thế giới để mở Timeline View — xem toàn bộ progression trên mọi entry, nhóm theo chương. Click vào item để nhảy đến entry tương ứng.

Trigger thủ công

Ngoài auto-trigger khi chuyển chương, bạn có thể nhấn nút 🔄 trong thanh meta chương bất kỳ lúc nào (chương cần ≥200 từ). Trigger thủ công hoạt động kể cả khi bạn tắt auto-progressions trong Cài đặt AI.

Nút Accept All

Nhấn Chấp nhận tất cả để accept hàng loạt. Lần nhấn đầu chấp nhận tất cả bổ sung + "arm" các replacement. Nếu có replacement, nút đổi thành "Xác nhận N thay thế?" — nhấn lần 2 để confirm.

Lục Thanh Vân (Nhân vật)
  Mô tả gốc: "Đệ tử đời 4, 19 tuổi, thông minh nhưng bốc đồng"

  + Ch.8: Phát hiện cảnh tượng kinh hoàng trong Huyết Lan Cốc
    Bằng chứng: "...xương người xếp thành hình bông sen..."

  + Ch.15: Mở được cánh cửa bí mật bằng chìa khóa đồng
    Bằng chứng: "...chiếc chìa khóa nhỏ vừa khít ổ khóa rỉ sét..."

  ↻ Ch.28: → "Đệ tử đời 4, 20 tuổi. Trưởng thành qua biến cố,
    giờ là người phơi bày bí mật phái. Được tôn trọng nhưng cô đơn."

Chế độ Kế hoạch

Nhấn tab Kế hoạch (cạnh tab Viết) ở phía trên editor để chuyển sang chế độ kế hoạch — nhìn tổng quan toàn bộ truyện dưới dạng lưới card.

Mỗi card hiển thị

• Tiêu đề chương + số từ
• Ghi chú chương (chỉnh sửa trực tiếp, tự lưu sau 800ms)
• Tóm tắt (preview ngắn, nếu đã generate)
• Tag trạng thái: có summary, có recap, có notes

Chế độ này hữu ích khi:

• Lập kế hoạch nội dung nhiều chương trước khi viết
• Soạn notes hàng loạt cho các chương sắp tới
• Kiểm tra xem chương nào chưa có summary/notes
• Nhìn tổng quan cấu trúc truyện

Chế độ viết

Chọn chế độ viết khi tạo project hoặc đổi trong Cài đặt AI:

Thông tin sách

Phần Thông tin sách (Book Info) nằm trong Cài đặt dự án. Đây là "kim chỉ nam" cho AI — được đưa vào mọi prompt.

Lịch sử & Phiên bản

Snapshot (Bản sao chương)

Writer lưu snapshot của chương trong các tình huống:

• Tự động: Trước khi chấp nhận ghost text (throttle 10 phút — không spam)
• Thủ công: Nhấn nút chụp snapshot trong phần meta chương

Xem và khôi phục snapshot: nhấn nút danh sách snapshot trong meta chương → chọn phiên bản → khôi phục. Writer tự tạo snapshot an toàn trước khi ghi đè.

Lịch sử Chat AI

Mỗi phiên chat với AI được lưu tự động. Nhấn nút đồng hồ ở header panel AI để:

• Xem danh sách session cũ
• Load lại session trước đó (giữ nguyên toàn bộ tin nhắn)
• Tạo session mới (bắt đầu chat sạch)
• Xóa session không cần

Session lưu theo project — chuyển project sẽ thấy session của project đó.

Sao lưu

Xuất dự án

• Xuất backup: Menu → Xuất dự án → tải file .vpwriter.json. Bao gồm toàn bộ: chương, worldbuilding, summary, recap, settings.
• Xuất TXT/Markdown: Menu → Xuất → chọn định dạng. Chỉ xuất nội dung văn bản (không kèm worldbuilding/summary).

Nhập

• Khôi phục dự án: Menu → Nhập → phần "Khôi phục dự án" → chọn file .vpwriter.json. Tạo project mới từ backup.
• Nhập chương: Menu → Nhập → phần "Nhập chương" → chọn file .txt hoặc .md. Thêm chương vào project hiện tại.

Phím tắt

Hỏi đáp thường gặp

AI không nhớ nội dung chương cũ?

Kiểm tra: (1) Bật checkbox Ctx: Trước, (2) Các chương cũ đã có summary chưa, (3) Đã tạo recap chưa. Nếu chưa có summary, AI chỉ thấy 1–2 chương gần nhất.

AI viết sáo rỗng, lặp từ?

Thử: (1) Tăng temperature lên 0.8–0.9, (2) Ghi rõ trong Ghi chú chương phong cách mong muốn, (3) Thêm entry "Nguyên tắc viết" trong Worldbuilding với activationMode: always.

Ghost text không xuất hiện?

Đảm bảo con trỏ đang ở trong editor (click vào vùng soạn thảo). Ghost text chỉ hoạt động ở các chế độ viết (Viết tiếp, Viết lại, Mở rộng, Thu gọn), không hoạt động ở chế độ Chat.

Worldbuilding entry không trigger?

Kiểm tra: (1) Checkbox Ctx: Thế giới đã bật, (2) Entry có activationMode: keyword và keyword đúng, (3) Keyword xuất hiện trong text chương hoặc tin nhắn chat. Mở Context Inspector để xác nhận.

Mất dữ liệu sau khi clear cache?

Dữ liệu Writer lưu trong IndexedDB — thường không bị xóa khi clear cache. Nhưng nếu "Clear all site data" thì sẽ mất. Hãy luôn sao lưu hoặc bật đồng bộ đám mây.

Progression không xuất hiện khi chuyển chương?

Kiểm tra: (1) "Tự động gợi ý diễn biến" đang bật trong Cài đặt AI, (2) Chương có >200 từ, (3) Có entry worldbuilding với keyword phù hợp. Nếu tắt auto, bạn vẫn có thể nhấn nút 🔄 trong meta chương để trigger thủ công.

Tóm tắt tự động không chạy?

Kiểm tra: (1) Đã cấu hình API key, (2) Setting "Tự động tóm tắt khi chuyển chương" đang bật trong Cài đặt AI, (3) Chương có >500 từ, (4) Chương chưa có summary (không ghi đè summary có sẵn).

Dữ liệu lưu ở đâu?

Toàn bộ dữ liệu (dự án viết, worldbuilding, snapshot, cài đặt AI) lưu trong IndexedDB của trình duyệt — nằm trên thiết bị của bạn, không gửi lên server nào. Nên cài app để tránh trình duyệt xóa dữ liệu, và sao lưu thường xuyên.