NovelClaw：基于动态记忆与可观测架构的AI长篇叙事工作台

1. 项目概述从“一次性生成”到“可检视的写作工作台”如果你尝试过用大语言模型LLM来创作长篇小说大概率会遇到这样的困境你给了一个精彩的开头设定模型也洋洋洒洒生成了几千字。但当你想要继续写第二章时要么得把第一章的全文再喂给它上下文长度不够要么就得手动提炼“故事梗概”和“人物设定”作为提示词。几章下来角色性格可能前后矛盾世界观设定或许悄然漂移整个创作过程就像在沙地上盖楼缺乏一个稳固、可追溯、可编辑的“工程基底”。这正是NovelClaw想要解决的核心问题。它不是一个简单的“提示词包装器”或“一次性故事生成器”。你可以把它理解为一个专为长篇叙事打造的“可检视的写作工作台”。其核心理念是将长篇创作视为一个持续的、有状态的、可观测的工程过程而非一次性的黑箱生成事件。想象一下传统的小说创作软件如Scrivener与AI生成能力的结合再赋予其软件工程般的“可观测性”Observability。在NovelClaw里你的故事状态人物、世界观、情节大纲、每一次的生成过程日志、进度、产出物章节文稿以及最重要的“记忆”Memory都被结构化地保存、展示并可供你随时检视、编辑和复用。这为作者提供了前所未有的控制力和连续性使得与AI协作完成一部数十万字、结构严谨的长篇作品成为可能。2. 核心架构与设计哲学为什么是“动态记忆优先”要理解NovelClaw必须先理解其基石——“动态记忆优先”Dynamic-Memory-First的设计哲学。这不仅是其区别于其他AI写作工具的关键也决定了整个系统的架构形态。2.1 传统AI写作的“记忆”困境在典型的AI辅助写作中“记忆”是脆弱且隐式的。它通常以三种形式存在对话历史保存在聊天上下文里但受限于Token长度很快会被挤出窗口。提示词工程作者需要手动将关键信息如“主角是蓝眼睛”反复写入后续提示。外部文档作者自己维护一个Word或Notion文档来记录设定然后在每次生成时手动复制粘贴相关部分。这三种方式都存在问题对话历史会丢失提示词工程繁琐且容易遗漏外部文档与生成过程割裂无法自动关联和更新。2.2 NovelClaw的解决方案结构化、可编辑的记忆库NovelClaw将“记忆”从隐式、临时的状态提升为显式、持久的一等公民。它内置了多种结构化的记忆库Memory Banks例如角色记忆库记录每个人物的外貌、性格、背景、关系变化。世界记忆库存储世界观设定、地理、历史、魔法/科技体系等。情节记忆库保存故事大纲、已发生的关键事件、伏笔等。风格记忆库定义作品的叙事风格、语言特色、段落习惯等。这些记忆库并非静态的配置文件。它们具备两个关键特性动态更新在写作过程中AI生成的关于角色、世界的新内容可以被自动或经作者确认后提取并结构化地写回对应的记忆库。例如AI在第二章描写了“主角的旧伤在雨天会隐隐作痛”这个新设定可以被捕捉并更新到“角色记忆库”中。条件化调用在生成新章节时系统会根据当前上下文如写到哪个场景、涉及哪些人物自动从庞大的记忆库中检索并注入最相关的记忆片段到提示词中而不是一股脑地塞进所有信息。这就构建了一个“创作-记忆-再创作”的增强循环。记忆随着故事生长而不断丰富和精确而更精确的记忆又反过来指导生成更连贯、更符合设定的新内容。2.3 三层架构门户、多智能体与核心工作台理解了记忆的核心地位再看NovelClaw的公开代码库结构就清晰了。它采用了清晰的三层架构将不同的关注点分离开auth-portal(门户层)这是对外的安全入口。它提供了一个干净的/select-mode路径让用户选择进入哪个工作模式主要是NovelClaw。这层剥离了旧的、可能涉及敏感验证的流程确保公开代码库的“GitHub安全”即不包含任何密钥、个人数据或私有配置。multiagent(多智能体层 - 可选)这是一个“快速构思通道”。当你只有一个模糊的想法时可以在这里利用多个AI智能体进行头脑风暴快速生成和筛选故事概念、角色设定等为进入深度写作做好准备。它是一个可选的加速器。novelclaw(核心工作台层)这才是主战场即前面详细描述的、围绕动态记忆构建的持续写作工作空间。所有长篇创作的会话、草稿、检视、记忆编辑都在这里进行。这种架构的好处是职责清晰门户负责安全和引导多智能体负责快速启动核心工作台负责深度、持续的创作。用户可以根据自身需求选择门户 - 核心工作台的直达路径或者在需要时经由多智能体层进行构思预热。3. 实操上手从零启动到写出第一个章节理论说得再多不如亲手运行一遍。下面我将以Windows环境为例带你完整走通NovelClaw的本地启动和初次创作流程。这也是项目推荐的“一键启动”路径。3.1 环境准备与一键启动NovelClaw的开发者提供了极其便捷的本地启动脚本大大降低了上手门槛。获取代码克隆或下载iLearn-Lab/NovelClaw项目的公开代码库到本地。运行启动脚本打开PowerShell进入项目根目录执行那个醒目的.\START_LOCAL.bat批处理文件。这个脚本背后做了大量工作我们可以拆解一下清理端口确保本地8010, 8011, 8012端口没有被占用。环境配置从安全的模板文件生成本地的.env配置文件。这里是一个关键点模板里只包含配置项的结构如API_KEY而不包含真实的密钥。这是保证代码库“GitHub安全”的关键实践。创建虚拟环境为所有服务Portal, MultiAgent, NovelClaw创建一个共享的Python虚拟环境.venv-shared并安装所有依赖。这避免了为每个应用单独配置环境的繁琐。启动全部服务依次启动门户运行在8010端口、多智能体8011端口和核心工作台8012端口三个服务。启动成功后你的命令行窗口会保持运行显示各个服务的日志。此时你可以打开浏览器了。3.2 核心工作台初探与模型配置按照项目推荐的最佳路径我们访问http://127.0.0.1:8010/select-mode。你会看到一个简洁的模式选择页面选择“NovelClaw”系统会自动跳转到核心工作台的主仪表盘http://127.0.0.1:8012/dashboard。在开始创作之前必须完成的一步是配置AI模型。这是整个工作台的“发动机”。点击左侧导航栏或访问/console/models进入模型配置页面。你会看到一个预设的提供商列表如OpenAI、Anthropic等。选择一个你拥有API Key的提供商。在对应的输入框里填入你的API密钥并保存。切记这个密钥只保存在你本地的.env文件或数据库里不会上传到任何地方。如果你使用的模型不在默认列表页面也支持添加自定义的API端点兼容任何提供OpenAI兼容接口的模型服务如本地部署的Llama、Qwen等。实操心得模型选择策略对于长篇创作模型的“长上下文能力”和“指令遵循能力”至关重要。GPT-4-Turbo、Claude 3系列是可靠的选择。如果使用开源模型建议选择上下文窗口至少为32K的版本。在NovelClaw中你可以配置多个模型在不同的写作阶段如构思用大模型润色用小模型进行切换。3.3 启动第一个写作会话配置好模型后真正的创作就可以开始了。进入/console/chat这里是你的主控台。发起会话在聊天界面选择你刚配置好的模型提供商。然后像与一个资深编辑或合著者交谈一样输入你的故事构想。例如“我想写一个科幻故事背景是22世纪的人类火星殖民地主角是一名负责维护老旧生态穹顶的工程师性格孤僻但内心善良。故事基调是冷峻中带点希望。”交互式细化NovelClaw的AI不会立刻开始狂写一万字。它会与你对话逐步澄清设定。它可能会问“这个火星殖民地的主要矛盾是什么是资源短缺、地球公司的压迫还是穹顶本身的神秘故障”“主角有没有一个关系特殊的伙伴或对手” 你需要像真正构思故事一样回答这些问题。这个过程正是在为后续的“记忆库”填充初始燃料。移交创作当你们通过对话将核心设定、开篇冲突、主要人物都讨论得比较清晰后你可以说“好的基于我们讨论的这些请开始撰写第一章的草稿。” 此时聊天会话会生成一个结构化的“创作简报”并移交到后台的写作任务队列。3.4 检视运行与产出物任务提交后工作台就从“聊天模式”进入了“运行监控模式”。这是体现其“可检视性”的关键环节。切换到/console/tasks页面你会看到刚刚创建的任务状态可能是“运行中”。点击任务进入详情页。这里是一个信息仪表盘你会看到worker.log后台工作进程的详细日志记录了AI调用、函数执行等底层信息。如果生成出错这里是第一排查点。progress.log这是最重要的进度追踪文件。它以结构化的JSON格式实时记录了创作的关键节点例如{event: global_outline, data: {title: 火星余烬, chapters: [...]}} {event: chapter_outline_ready, data: {chapter: 1, outline: ...}} {event: memory_snapshot, data: {characters: {...}, world: {...}}}通过它你可以清晰地看到AI是如何一步步构建故事框架、规划章节、并更新记忆的。chapters/目录这里存放着生成的章节纯文本文件。第一章完成后你就能在这里看到chapter_001.txt。output.txt有时会包含整合后的输出或摘要。在这个过程中你并非被动的等待者。你可以随时查看进度如果发现AI跑偏比如给主角安上了一个你们没讨论过的超能力你可以中断任务回头去编辑“记忆库”或调整提示然后重新开始。这种“观察-干预-修正”的循环是可控创作的核心。3.5 使用工作台进行持续创作第一章生成完毕后创作并未结束而是进入了新的阶段。审阅稿件进入/console/manuscript/read你可以舒适地阅读已生成的章节。界面通常提供良好的排版和导航。规划与调整进入/console/storyboard这里以看板或大纲形式展示了整个故事的结构。你可以看到已完成的章节和后续章节的计划。你可以直接在这里拖拽调整章节顺序或编辑章节概要这些改动会同步到记忆和后续的生成计划中。维护记忆库进入/console/memory/banks这里列出了所有的角色、世界等记忆库。你可以直接点击编辑修正AI理解错误的地方或者补充你新想到的细节。例如把“主角怕黑”这个新设定手动添加到角色记忆中。继续写作回到/console/chat你会发现之前的会话还在。你可以直接说“基于第一章和当前的故事板请继续写第二章。” 系统会自动携带最新的、经过你审阅和修正过的全部记忆角色、世界、已发生情节来生成后续内容从而保证极强的连贯性。至此你已经完成了一个完整的“构思-生成-检视-修正-继续”的写作循环。NovelClaw的价值在这个循环中得以完整呈现它将离散的AI生成动作整合进了一个具有状态持久性、过程可观测、资产可管理的专业工作流中。4. 深入解析核心功能模块与高级用法掌握了基本流程后我们来深入拆解NovelClaw的几个核心功能模块了解如何利用它们提升创作效率与作品质量。4.1 故事板不止于大纲的动态规划器故事板模块远不止是一个静态的大纲列表。它是一个动态的叙事规划中心。可视化结构通常以卡片或列表形式展示章节颜色或标签可能区分“已完成”、“写作中”、“已规划”、“待修订”等状态。章节级控制你可以为每个章节单独指定写作目标如“本章需要揭露反派的一个秘密”、“本章侧重描写火星风暴的壮观景象”、视角人物、甚至情感基调。这些指令会在该章节生成时作为强约束条件注入提示词。灵活调整长篇创作中调整结构是常事。你可以通过拖拽轻松将第10章的一个场景移到第8章作为伏笔故事板会帮你处理后续章节概要的连锁调整建议。注意事项故事板的“建议”属性AI生成的故事板是强大的助手但绝非不可更改的圣旨。它基于当前记忆和叙事逻辑推导出的“最可能路径”。作为作者你应当积极审查和修改它。如果你有一个绝妙的戏剧性转折想法即使AI认为概率不高也应该手动更新故事板。记住你才是故事的最终决策者。4.2 记忆库编辑器故事的基石数据库记忆库是NovelClaw的“单一事实来源”。维护好它是保证故事一致性的不二法门。结构化 vs 非结构化记忆库通常支持两种形式。一是高度结构化的字段如角色姓名、年龄、外貌、性格标签、关键经历。二是非结构化的“笔记”或“事实片段”如世界“殖民历37年发生了‘静海叛乱’其影响持续至今”。结构化数据便于AI精确检索和使用非结构化数据则保留了灵活性和叙事细节。关联与检索高级的用法是为记忆条目建立关联。例如将“角色A”与“地点B”关联并注明“A在B地有一段痛苦的回忆”。当故事写到B地时系统更有可能检索到这条关联记忆并生成相应的内心描写或对话。版本与快照在关键节点如完成一个重要故事弧可以手动创建记忆库快照。这相当于一个“存档点”如果后续的创作方向走偏你可以快速回滚到某个版本的记忆状态而不是在杂乱的历史记录中手动撤销。4.3 运行与日志分析调试你的创作过程对于有技术背景或追求精细控制的作者运行详情页是一个宝库。progress.log深度解读这个文件是理解AI“思考过程”的窗口。除了记录事件它可能还包含AI在规划章节时的“推理链”Chain-of-Thought比如“因为主角在上章表现出犹豫本章应安排一个事件逼迫他做出坚定选择以完成角色成长。” 看到这些你就能判断AI的叙事逻辑是否符合你的预期。性能与成本监控worker.log中会记录每次API调用的Token消耗和耗时。对于长篇创作成本是一个现实考量。通过分析日志你可以识别哪些步骤消耗最大进而优化提示词或调整生成策略比如是先生成详细大纲再写还是边写边规划。错误排查如果生成突然中断或内容质量骤降日志是首要排查点。可能是API调用超时、上下文溢出、或是提示词中的某些指令导致了模型混乱。清晰的日志能帮你快速定位问题。4.4 多智能体模式的协同创作虽然核心工作流在NovelClaw但MultiAgent层提供了有趣的补充。你可以将它想象成一个“创意会议室”里面坐着几位各司其职的专家头脑风暴者负责天马行空地提出各种故事点子。批判者负责挑刺指出点子中的逻辑漏洞或俗套之处。设定完善者负责将选中的点子扩展成初步的世界观和角色设定。你作为“主编”向这个会议室提出一个模糊的需求如“一个关于记忆交易的悬疑故事”它们会内部讨论、辩论、迭代最终给你几个相对成熟的方案。你可以将这个方案一键导入到NovelClaw作为新项目的起点。这非常适合在正式动笔前快速探索和验证不同的创意方向。5. 部署实践与项目维护指南对于希望长期使用或与小团队共享的创作者将NovelClaw部署到私人服务器是更稳定的选择。项目文档提供了清晰的指引这里提炼关键点和避坑经验。5.1 安全第一理解“GitHub Safe”原则项目反复强调“GitHub-safe”这是开源协作的基石。其核心是“代码与配置分离”。代码仓库 (apps/,scripts/,docs/)只包含应用程序逻辑、脚本和文档。绝对不包含真实的API密钥、数据库密码等任何秘密。运行时生成的数据库文件 (app.db)。包含个人写作内容的项目状态快照。本地调试的临时文件。环境配置 (.env文件)通过.env.example或infra/env/下的模板提供配置项结构。实际部署时在服务器上创建真实的.env文件并确保它被.gitignore排除在版本控制之外。数据与状态运行产生的所有数据数据库、上传文件、生成的作品都应存储在代码目录之外或至少是在.gitignore明确忽略的路径下。遵循这个原则你可以放心地Fork项目、提交功能改进而不用担心泄露自己的私密信息。5.2 生产环境部署要点参考DEPLOYMENT.md部署流程大致如下服务器准备准备一台Linux服务器如Ubuntu 22.04安装Python、Git、Nginx等基础软件。获取代码克隆项目到服务器如/opt/novelclaw。配置环境在项目根目录创建.env文件填入所有必要的配置数据库URL、API密钥、域名等。务必设置强密码配置服务使用infra/systemd/下的示例文件配置三个systemd服务novelclaw-portal.service,novelclaw-multiagent.service,novelclaw.service让它们能在后台稳定运行并开机自启。配置反向代理使用Nginxinfra/nginx/有示例配置将域名如writing.yourdomain.com代理到本地的8012端口核心工作台并将/select-mode等路径代理到对应的服务端口。同时配置SSL证书如使用Let‘s Encrypt启用HTTPS。启动与测试启动所有systemd服务检查日志通过域名访问服务。避坑指南部署常见问题端口冲突确保服务器防火墙开放了所需端口如80, 443, 8010-8012并且这些端口没有被其他程序占用。依赖安装失败建议在服务器上使用python -m venv venv创建虚拟环境然后在虚拟环境中运行pip install -r requirements.txt。注意检查Python版本需要3.10。数据库权限问题如果使用SQLite确保运行服务的用户如www-data或你创建的系统用户对数据库文件所在目录有读写权限。静态文件404检查FastAPI应用的静态文件配置路径是否正确以及Nginx配置中是否正确处理了静态文件请求。5.3 数据备份与迁移你的创作数据故事、记忆库是核心资产定期备份至关重要。备份数据库定期复制apps/novelclaw/local_web_portal/data/app.db文件或你配置的其他数据库到安全位置。备份生成产物runs/目录下的内容包含了所有生成日志和章节文本也应纳入备份计划。迁移升级升级到新版本时建议先完整备份现有数据和数据库。然后更新代码运行数据库迁移命令如果项目提供了alembic迁移脚本。在测试环境验证无误后再在生产环境切换。6. 常见问题与排查技巧实录在实际使用中你可能会遇到一些典型问题。以下是我在深度使用和测试中积累的排查经验。6.1 内容生成质量不佳或偏离预期这是最常见的问题根源通常不在工具本身而在“人机协作”的流程上。症状AI写出的章节枯燥、逻辑混乱、或忘记了重要设定。排查步骤检查记忆库首先去/console/memory/banks确认相关的角色、世界设定是否准确、完整。AI只会基于你给它的“记忆”来生成。审查故事板查看当前章节的故事板概要是否清晰。一个模糊的概要如“主角在城里遇到一些事”会导致AI自由发挥过度。将其具体化如“主角在黑市寻找零件时意外撞见敌对帮派的交易”。分析progress.log查看生成该章节前AI记录的chapter_plan事件。看看AI自己理解的“本章计划”是什么是否与你的预期相符。优化提示词与会话回到聊天会话不要直接命令“重写”。而是与AI讨论“我觉得这一章里主角的反应过于平淡了不符合他之前‘谨慎多疑’的性格。我们在记忆库里是这么定义的。你认为在‘黑市撞见交易’这个情境下一个谨慎多疑的人更可能有什么样的具体行为和内心活动” 通过对话引导AI聚焦到具体问题。根本技巧将NovelClaw视为一个需要清晰指令和高质量输入的“超级实习生”。你给它的背景记忆和任务说明故事板/聊天指令越清晰、越具体它的产出就越精准。6.2 任务运行失败或卡住症状任务状态长时间处于“运行中”或直接变为“失败”。排查步骤查看worker.log这是第一现场。通常会有明确的错误信息如APIError: Invalid API Key,ConnectionTimeout,ContextLengthExceeded。检查模型配置确认/console/models里配置的API密钥有效、额度充足且端点地址正确对于自定义模型。检查网络如果是本地部署访问云端API确保网络通畅。如果是服务器部署检查服务器能否访问外部API服务。检查资源查看服务器CPU/内存使用情况。虽然NovelClaw本身不耗大量资源但若同时运行多个任务或生成超长文本可能导致临时内存不足。6.3 界面加载缓慢或操作无响应症状页面白屏、按钮点击后很久才有反应。排查步骤浏览器开发者工具按F12打开查看“网络”(Network)和“控制台”(Console)标签页。是否有大量资源加载失败404是否有JavaScript错误服务日志查看后端服务的日志在终端或systemd journal中看是否有错误抛出。可能是某个API接口响应慢或出错。数据库锁如果使用SQLite且在频繁读写偶尔可能遇到数据库锁问题。考虑升级到PostgreSQL以获得更好的并发性能需要修改数据库连接配置。客户端缓存尝试强制刷新浏览器CtrlF5清除缓存。6.4 如何实现更复杂的叙事技巧NovelClaw提供了基础框架但高级的叙事技巧需要你巧妙地利用现有工具。多视角叙事在角色记忆库中为不同视角人物建立详细的“视角滤镜”如语言风格、知识局限、情感倾向。在故事板中为特定章节指定视角人物。在生成该章节的提示词中系统可以自动注入“以[角色A]的第一人称视角叙述使用其口语化、多疑的语言风格”这类指令。非线性叙事如倒叙、插叙这需要手动规划。你可以在故事板中创建一个代表“回忆”的章节卡片将其放在后面但在章节概要里明确写明“此章为倒叙内容为三个月前的事件”。同时确保在生成该章时相关的历史记忆被正确检索可能需要手动在记忆库中为该事件打上时间戳标签。风格模仿在风格记忆库中不仅可以定义“文风冷峻、简洁”还可以粘贴一段你希望模仿的经典文本段落作为示例。在生成时可以指令AI“参考风格记忆库中的示例文本的节奏和修辞手法”。最终NovelClaw是一个威力巨大的平台但它不替代作者的创意和判断。它的价值在于将AI从“一个时而惊艳、时常糊涂的即兴表演者”变成了一个“拥有完美记忆、严格遵循指令、并且工作过程完全透明的协作助手”。掌握它意味着你将获得一种全新的、可规模化的叙事生产能力去实现那些以往仅凭个人脑力难以驾驭的宏大故事构想。