Arboris-Novel | 面向创作者的写作辅助工具

English | 中文

如果你想使用命令行 + 编辑器的方式，可搭配使用 novel-kit。

写作时容易卡在「主角叫什么」「故事发生在哪」「下一章写什么」这类问题上。Arboris 在需要时帮你理清思路、记录设定、给出可选方向，让想法落成故事。

在线体验： https://arboris.aozhiai.com

交流群

作者公众号

---

界面预览

---

功能概览

设定管理

角色、地点、派系等设定集中记录，随时查阅，避免写到后期前后矛盾（如角色外貌、世界观规则等）。

大纲与故事线

零散的场景和灵感可交给 AI 梳理，生成从开头到结局的主线大纲。

写作辅助

状态不佳时可让 AI 先出草稿再按自己的风格修改；也可自己写开头，让 AI 续写以获取灵感。

多版本对比

支持一次生成多版内容，挑选最符合风格的部分，逐步让模型更贴合你的笔触。

---

项目初衷

目标是做一个能记住你的世界、理解角色、随故事推进的写作伙伴，而不是单纯的自动生成器。因此做了 Arboris 并选择开源，方便更多创作者使用。

---

快速开始

方式一：Docker（容器引擎）部署

# 1. 复制配置文件
cp .env.example .env

# 2. 编辑 .env 中的必填项：
#    - SECRET_KEY: 随机字符串，用于 JWT 等
#    - OPENAI_API_KEY: 大模型 API Key
#    - ADMIN_DEFAULT_PASSWORD: 管理员密码（勿用默认值）

# 3. 启动（默认 SQLite，无需单独安装数据库）
docker compose up -d

# 启动后在浏览器访问 http://localhost:<端口>

方式二：使用 MySQL（关系型数据库）（Compose 内 MySQL）

# .env 中设置 DB_PROVIDER=mysql，然后执行：
DB_PROVIDER=mysql docker compose --profile mysql up -d

方式三：使用自有 MySQL

# 在 .env 中配置数据库地址、用户名、密码后执行：
DB_PROVIDER=mysql docker compose up -d

---

环境变量说明

常用配置如下（完整项见 .env.example）：

配置项	必填吗	说明
SECRET_KEY	✅	JWT（JSON Web Token）加密密钥，需自行随机生成并妥善保管
OPENAI_API_KEY	✅	你的 LLM（大语言模型）API Key（OpenAI 或兼容的）
OPENAI_API_BASE_URL	❌	API（应用程序接口）地址，默认是 OpenAI 官方的
OPENAI_MODEL_NAME	❌	模型名称，默认 gpt-3.5-turbo
ADMIN_DEFAULT_PASSWORD	❌	管理员初始密码，部署后务必修改
ALLOW_USER_REGISTRATION	❌	是否开放注册，默认 false
SMTP_SERVER / SMTP_USERNAME	开放注册时必填	邮件服务，用于发送验证码

数据存储： 默认 SQLite（轻量级数据库），数据在 Docker 卷中。需映射到本地时，在 .env 中设置 SQLITE_STORAGE_SOURCE=./storage。

---

常见问题

基础使用

Q: 不会用 Docker（容器引擎）？
A: 安装 Docker Desktop（Windows/Mac）或 Docker Engine（Linux），按上文命令执行即可。

Q: API Key（应用程序接口密钥）会泄露吗？
A: 不会。密钥仅存在于服务端 .env，不向前端或用户暴露。

Q: 是否支持其他大语言模型（LLM）？
A: 支持。只要提供 OpenAI 兼容接口，在 .env 中配置 OPENAI_API_BASE_URL 即可。

Q: 修改了代码如何参与？
A: 欢迎提交 PR（Pull Request）或 Issue（问题）。

生成小说时的常见错误

Q: 提示"未配置默认 LLM（大语言模型）API Key"怎么办？
A: 检查 .env 文件中的 OPENAI_API_KEY 是否正确配置。如果是个人用户，也可以在个人设置中配置自定义 API Key。

Q: 生成时提示"今日请求次数已达上限"？
A: 系统管理员可能设置了每日请求限制。解决方案：

• 等到明天再试
• 在个人设置中配置自己的 API Key（不受系统配额限制）
• 管理员调整配额限制（修改 daily_request_limit 配置）

Q: 提示"AI 服务响应超时"或"无法连接到 AI 服务"？
A: 网络或 API（应用程序接口）服务问题导致。可以：

• 检查网络连接是否正常
• 确认 OPENAI_API_BASE_URL 配置是否正确
• 如果使用自建服务，检查服务是否正常运行
• 稍后重试

Q: 提示"AI 响应因长度限制被截断"？
A: 生成的内容超过了模型的输出限制。建议：

• 使用支持更长输出的模型

Q: 提示"AI 未返回有效内容"或"AI 服务内部错误"？
A: AI 服务端出现问题。通常是暂时性的，可以：

• 大多是 LLM（大语言模型）服务的问题，尤其是逆向的 API。
• 检查 API Key 是否有效且有足够余额
• 查看后端日志获取详细错误信息

Q: 提示"蓝图中未找到对应章节纲要"？
A: 在生成章节内容前，需要先在蓝图（大纲）中创建对应章节的纲要。请先完善章节大纲再进行生成。

Q: 提示"未配置摘要提示词"？
A: 系统缺少必要的 Prompt 配置。管理员需要在后台配置名为 extraction 的提示词模板，用于生成章节摘要。

Q: 提示"AI 返回的内容格式不正确"或 JSON（JavaScript 对象表示法）解析错误？（较常见）
A: AI 返回内容无法解析为有效 JSON。可能原因与处理方式：

• 原因 1：模型能力不足 - 某些模型难以稳定输出结构化 JSON

  • 解决：切换到能力更强的模型
  • 或使用支持 structured output 的模型

• 原因 2：内容过长 - 某些逆向 API 可能无法支持长输出。

• 临时处理： 重试几次，或更换 AI 模型

Q: 生成的内容质量不理想怎么办？
A: 可以尝试：

• 完善角色、地点、派系等设定信息
• 优化章节纲要，提供更详细的指引
• 使用多版本生成功能，让 AI 生成多个版本后挑选最佳的
• 调整使用的模型，需要长上下文的

---

技术栈

• 后端： Python（编程语言）+ FastAPI（Web 框架）
• 数据库： SQLite（轻量级数据库）（默认）或 MySQL（关系型数据库）+ libsql
• 前端： Vue（前端框架）+ TailwindCSS（CSS 框架）
• 部署： Docker（容器引擎）+ Docker Compose
• AI： OpenAI API（应用程序接口）或兼容接口

---

面向开发者

环境准备

• Python 3.10+（建议使用虚拟环境）
• Node.js（运行环境）18+ 与 npm（包管理器）
• pip（包管理器）/ virtualenv（或你习惯的依赖管理工具）
• 可选：Docker（容器引擎）与 Docker Compose（用于一键部署与发布）

后端本地开发

cd backend
python3 -m venv .venv
source .venv/bin/activate  # Windows 使用 .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

默认会监听 http://127.0.0.1:8000，你可以通过 --host、--port 调整，或加上 --reload 保持热重载。

前端本地开发

cd frontend
npm install
npm run dev

开发服务器默认运行在 http://127.0.0.1:5173，可通过 --host 参数暴露给局域网设备。

打包与构建

• 前端：npm run build，构建产物位于 frontend/dist/
• 后端：确认依赖锁定后，可使用 pip install -r requirements.txt 安装到目标环境，或基于 deploy/Dockerfile 构建镜像
• 静态文件托管：生产环境下可用 Nginx（Web 服务器）等服务托管 dist 目录，并由后端提供 API

发布与部署

推荐在根目录下使用 Compose 文件完成一体化部署：

docker compose -f deploy/docker-compose.yml up -d --build

如需推送镜像，可在 deploy 目录执行 docker build -t <registry>/arboris:<tag> .，测试后再 docker push 发布。

---

参与贡献

• Star 项目
• 在 Issues 中反馈 Bug 或建议
• 提交 PR（Pull Request）贡献代码
• 通过文首二维码加入交流群

---

反馈与致谢

使用 Arboris 写出作品后，欢迎与我们分享。祝写作顺利。

---

许可证

本项目采用 MIT 许可证授权 - 详见 LICENSE 文件。

arboris-novel 快速上手指南

Arboris-Novel 是一款面向创作者的 AI 写作辅助工具。它能帮你理清思路、记录设定、生成大纲并提供续写灵感，让想法落成故事。

---

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 系统要求：Windows / macOS / Linux
• 核心依赖：
  • Docker 及 Docker Compose（推荐方式）
  • 或 Python 3.10+ 与 Node.js 18+（本地开发模式）
• 网络环境：需能访问 OpenAI 兼容接口（建议使用稳定的网络连接）

---

安装步骤

推荐使用 Docker 进行一键部署，无需单独安装数据库。

1. 获取项目代码

git clone https://github.com/t59688/arboris-novel.git
cd arboris-novel

2. 配置环境变量

复制示例配置文件并编辑必填项：

cp .env.example .env

使用编辑器打开 .env 文件，修改以下内容：

• SECRET_KEY: 随机字符串，用于 JWT 加密（建议自行生成）
• OPENAI_API_KEY: 填入你的大模型 API Key（支持 OpenAI 或兼容接口）
• ADMIN_DEFAULT_PASSWORD: 设置管理员初始密码（切勿使用默认值）

注意：若需使用自有 MySQL 数据库，请在 .env 中设置 DB_PROVIDER=mysql 并配置相关连接信息。

3. 启动服务

执行以下命令启动容器（默认使用 SQLite，数据存储在 Docker 卷中）：

docker compose up -d

启动成功后，浏览器访问 http://localhost:<端口> 即可进入后台。

---

基本使用

1. 登录系统

使用您在 .env 中设置的 ADMIN_DEFAULT_PASSWORD 登录管理员账户。如果是个人用户，也可在个人设置中配置自定义 API Key。

2. 核心功能操作

• 设定管理：在“角色”、“地点”、“派系”模块录入世界观设定，避免剧情前后矛盾。
• 大纲生成：利用 AI 梳理零散灵感，生成从开头到结局的主线大纲。
• 辅助写作：
  • 草稿模式：状态不佳时让 AI 生成初稿，再按个人风格修改。
  • 续写模式：自己写开头，让 AI 续写以获取灵感。
  • 多版本对比：一次生成多个版本内容，挑选最符合笔触的部分。

3. 在线体验

如果不希望本地部署，可直接访问在线体验地址： https://arboris.aozhiai.com

---

后续建议

• 数据存储：如需将数据持久化到本地，可在 .env 中设置 SQLITE_STORAGE_SOURCE=./storage。
• 参与贡献：欢迎提交 PR 或 Issue，加入交流群获取更多支持。