Arboris 长篇小说自动化流水线说明

本文档描述 Arboris 在「从概念到章节成稿」过程中的完整自动化流程、涉及的提示词、上下文载荷与模型参数。

1. 总体流程概览

项目创建 → 概念对话 → 蓝图生成/编辑 → 章节生成 → 版本评审/选择
     ↑                                            ↓
  （持续迭代） ← 手动编辑 ← 向量入库 ← 摘要提取 ← RAG 检索支撑下一章

关键能力由以下组件协作完成：

阶段	主要接口	提示词 ID	模型温度	说明
概念对话	`POST /api/novels/{id}/concept/converse`	`concept`（附带 JSON schema 指令）	0.8	引导用户梳理世界观与剧情要素
蓝图生成	`POST /api/novels/{id}/blueprint/generate`	`screenwriting`	0.3	基于概念对话整理正式蓝图
章节生成	`POST /api/writer/novels/{id}/chapters/generate`	`writing`	0.9	结合蓝图、前情摘要与 RAG 结果生成章节草稿
章节评审	`POST /api/writer/novels/{id}/chapters/evaluate`	`evaluation`	0.3	对全部候选版本给出改进建议
摘要提取	调用 `LLMService.get_summary`（生成/编辑/选择时触发）	`extraction`	0.15	对最终正文提炼真实摘要

所有提示词原文保存在 backend/prompts/ 目录，可由 Prompt 管理界面动态更新。

入口：POST /api/novels/{project_id}/blueprint/generate
上下文：
- 概念对话中成功解析的用户/助手消息（提取自存档 JSON）
提示词：screenwriting
LLM 参数：温度 0.3，超时 480 秒
输出：结构化蓝图 JSON，映射到 NovelBlueprint（世界观、角色、章节纲要等）
后续：
- PATCH /api/novels/{project_id}/blueprint 可局部修改蓝图
- save_blueprint 路径用于手动覆盖生成结果

入口：POST /api/writer/novels/{project_id}/chapters/generate，请求体 GenerateChapterRequest
上下文组装：
1. 蓝图：剔除章节细节字段（章节摘要、对话、角色动态等），仅保留世界观框架。
2. 已完成章节摘要：逐章真实摘要；若缺失则调用 get_summary 以 extraction 提示词生成。
3. 上一章桥接：上一章真实摘要 + 正文末尾 500 字。
4. RAG 检索结果（由 ChapterContextService 提供）：
  - 查询向量来源：章节标题 + 纲要摘要 + 可选写作指令 → LLMService.get_embedding
  - 文本来源：VectorStoreService.query_chunks/query_summaries（若数据库不支持向量函数，则回退到应用层余弦距离排序）
  - 默认 Top-K：正文片段 5 条、章节摘要 3 条（可通过环境变量调整）
5. 写作提示词：writing
LLM 参数：温度 0.9，超时 600 秒，候选版本数默认为 3（可通过系统配置或环境变量覆盖）
输出：章节候选版本数组（JSON），写入 ChapterVersion；Chapter 状态设置为 generating。

注意：章节上下文生成失败（如无向量库）时，流程会降级为“蓝图 + 历史摘要”模式继续执行。

选择版本：POST /api/writer/novels/{project_id}/chapters/select
- 选定后调用 get_summary（温度 0.15）生成真实摘要
- 触发 ChapterIngestionService.ingest_chapter 切分正文、摘要并写入向量库
手动编辑：POST /api/writer/novels/{project_id}/chapters/edit
- 更新正文、重算摘要
- 同样触发向量入库，以覆盖旧 chunk

默认使用 LangChain RecursiveCharacterTextSplitter：
- chunk_size = settings.vector_chunk_size（默认 480）
- chunk_overlap = min(settings.vector_chunk_overlap, chunk_size // 2)（默认 120）
- 分隔符优先级：双换行 > 单换行 > 句号/问号/感叹号 > 逗号 > 空格 ➜ 确保靠近语义边界
若未安装对应依赖，则回退到内置段落 + 标点切分算法，配合日志提示。
摘要文本也使用同一套流程（通常为单条向量）。

后端服务：VectorStoreService
存储实现：libsql（可本地 file:，亦可云端），需手动配置 VECTOR_DB_URL
表结构：
- rag_chunks（正文分块）：id、project_id、chapter_number、chunk_index、chapter_title、content、embedding、metadata
- rag_summaries（章节摘要）：id、project_id、chapter_number、title、summary、embedding
检索策略：
- 优先使用 libsql 的 vector_distance_cosine；若未启用，回退到 Python 端计算余弦距离（排序后截取 Top-K）。
- 查询向量由 LLMService.get_embedding 生成，支持 OpenAI 与 Ollama（通过 EMBEDDING_PROVIDER 切换）。

配置项	说明	默认/来源
`OPENAI_*`	默认生成模型配置	`.env` 或系统配置表
`EMBEDDING_PROVIDER`	嵌入提供方（`openai` / `ollama`）	`.env`
`EMBEDDING_MODEL` / `OLLAMA_EMBEDDING_MODEL`	具体嵌入模型名	`.env`
`VECTOR_DB_URL`	libsql 数据库地址（支持 `file:`）	`.env`
`VECTOR_TOP_K_CHUNKS` / `VECTOR_TOP_K_SUMMARIES`	检索数量	`.env` / 系统配置
`WRITER_CHAPTER_VERSION_COUNT`	章节候选版本数	系统配置 / 环境变量

确保在部署环境中提前安装新依赖：

pip install -r backend/requirements.txt

如需进一步开发，请配合此文档查看对应模块的实现文件（backend/app/services/*、backend/app/api/routers/*、backend/prompts/*），保持提示词与代码逻辑的一致性。