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

1. 项目概述：从“一次性生成”到“可检视的写作工作台”

如果你尝试过用大语言模型（LLM）来创作长篇小说，大概率会遇到这样的困境：你给了一个精彩的开头设定，模型也洋洋洒洒生成了几千字。但当你想要继续写第二章时，要么得把第一章的全文再喂给它（上下文长度不够），要么就得手动提炼“故事梗概”和“人物设定”作为提示词。几章下来，角色性格可能前后矛盾，世界观设定或许悄然漂移，整个创作过程就像在沙地上盖楼，缺乏一个稳固、可追溯、可编辑的“工程基底”。

这正是NovelClaw想要解决的核心问题。它不是一个简单的“提示词包装器”或“一次性故事生成器”。你可以把它理解为一个专为长篇叙事打造的“可检视的写作工作台”。其核心理念是：将长篇创作视为一个持续的、有状态的、可观测的工程过程，而非一次性的黑箱生成事件。

想象一下传统的小说创作软件（如Scrivener）与AI生成能力的结合，再赋予其软件工程般的“可观测性”（Observability）。在NovelClaw里，你的故事状态（人物、世界观、情节大纲）、每一次的生成过程（日志、进度）、产出物（章节文稿）以及最重要的“记忆”（Memory）都被结构化地保存、展示，并可供你随时检视、编辑和复用。这为作者提供了前所未有的控制力和连续性，使得与AI协作完成一部数十万字、结构严谨的长篇作品成为可能。

2. 核心架构与设计哲学：为什么是“动态记忆优先”？

要理解NovelClaw，必须先理解其基石——“动态记忆优先”（Dynamic-Memory-First）的设计哲学。这不仅是其区别于其他AI写作工具的关键，也决定了整个系统的架构形态。

2.1 传统AI写作的“记忆”困境

在典型的AI辅助写作中，“记忆”是脆弱且隐式的。它通常以三种形式存在：

1. 对话历史：保存在聊天上下文里，但受限于Token长度，很快会被挤出窗口。
2. 提示词工程：作者需要手动将关键信息（如“主角是蓝眼睛”）反复写入后续提示。
3. 外部文档：作者自己维护一个Word或Notion文档来记录设定，然后在每次生成时手动复制粘贴相关部分。

这三种方式都存在问题：对话历史会丢失；提示词工程繁琐且容易遗漏；外部文档与生成过程割裂，无法自动关联和更新。

2.2 NovelClaw的解决方案：结构化、可编辑的记忆库

NovelClaw将“记忆”从隐式、临时的状态，提升为显式、持久的一等公民。它内置了多种结构化的记忆库（Memory Banks），例如：

• 角色记忆库：记录每个人物的外貌、性格、背景、关系变化。
• 世界记忆库：存储世界观设定、地理、历史、魔法/科技体系等。
• 情节记忆库：保存故事大纲、已发生的关键事件、伏笔等。
• 风格记忆库：定义作品的叙事风格、语言特色、段落习惯等。

这些记忆库并非静态的配置文件。它们具备两个关键特性：

1. 动态更新：在写作过程中，AI生成的关于角色、世界的新内容，可以被自动或经作者确认后，提取并结构化地写回对应的记忆库。例如，AI在第二章描写了“主角的旧伤在雨天会隐隐作痛”，这个新设定可以被捕捉并更新到“角色记忆库”中。
2. 条件化调用：在生成新章节时，系统会根据当前上下文（如写到哪个场景、涉及哪些人物），自动从庞大的记忆库中检索并注入最相关的记忆片段到提示词中，而不是一股脑地塞进所有信息。

这就构建了一个“创作-记忆-再创作”的增强循环。记忆随着故事生长而不断丰富和精确，而更精确的记忆又反过来指导生成更连贯、更符合设定的新内容。

2.3 三层架构：门户、多智能体与核心工作台

理解了记忆的核心地位，再看NovelClaw的公开代码库结构就清晰了。它采用了清晰的三层架构，将不同的关注点分离开：

• auth-portal(门户层)：这是对外的安全入口。它提供了一个干净的/select-mode路径，让用户选择进入哪个工作模式（主要是NovelClaw）。这层剥离了旧的、可能涉及敏感验证的流程，确保公开代码库的“GitHub安全”（即不包含任何密钥、个人数据或私有配置）。
• multiagent(多智能体层 - 可选)：这是一个“快速构思通道”。当你只有一个模糊的想法时，可以在这里利用多个AI智能体进行头脑风暴，快速生成和筛选故事概念、角色设定等，为进入深度写作做好准备。它是一个可选的加速器。
• novelclaw(核心工作台层)：这才是主战场，即前面详细描述的、围绕动态记忆构建的持续写作工作空间。所有长篇创作的会话、草稿、检视、记忆编辑都在这里进行。

这种架构的好处是职责清晰：门户负责安全和引导，多智能体负责快速启动，核心工作台负责深度、持续的创作。用户可以根据自身需求，选择门户 -> 核心工作台的直达路径，或者在需要时经由多智能体层进行构思预热。

3. 实操上手：从零启动到写出第一个章节

理论说得再多，不如亲手运行一遍。下面我将以Windows环境为例，带你完整走通NovelClaw的本地启动和初次创作流程。这也是项目推荐的“一键启动”路径。

3.1 环境准备与一键启动

NovelClaw的开发者提供了极其便捷的本地启动脚本，大大降低了上手门槛。

1. 获取代码：克隆或下载iLearn-Lab/NovelClaw项目的公开代码库到本地。
2. 运行启动脚本：打开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模型。这是整个工作台的“发动机”。

1. 点击左侧导航栏或访问/console/models，进入模型配置页面。
2. 你会看到一个预设的提供商列表（如OpenAI、Anthropic等）。选择一个你拥有API Key的提供商。
3. 在对应的输入框里填入你的API密钥，并保存。切记：这个密钥只保存在你本地的.env文件或数据库里，不会上传到任何地方。
4. 如果你使用的模型不在默认列表，页面也支持添加自定义的API端点，兼容任何提供OpenAI兼容接口的模型服务（如本地部署的Llama、Qwen等）。

实操心得：模型选择策略对于长篇创作，模型的“长上下文能力”和“指令遵循能力”至关重要。GPT-4-Turbo、Claude 3系列是可靠的选择。如果使用开源模型，建议选择上下文窗口至少为32K的版本。在NovelClaw中，你可以配置多个模型，在不同的写作阶段（如构思用大模型，润色用小模型）进行切换。

3.3 启动第一个写作会话

配置好模型后，真正的创作就可以开始了。进入/console/chat，这里是你的主控台。

1. 发起会话：在聊天界面，选择你刚配置好的模型提供商。然后，像与一个资深编辑或合著者交谈一样，输入你的故事构想。例如：“我想写一个科幻故事，背景是22世纪的人类火星殖民地，主角是一名负责维护老旧生态穹顶的工程师，性格孤僻但内心善良。故事基调是冷峻中带点希望。”
2. 交互式细化：NovelClaw的AI不会立刻开始狂写一万字。它会与你对话，逐步澄清设定。它可能会问：“这个火星殖民地的主要矛盾是什么？是资源短缺、地球公司的压迫，还是穹顶本身的神秘故障？”“主角有没有一个关系特殊的伙伴或对手？” 你需要像真正构思故事一样回答这些问题。这个过程，正是在为后续的“记忆库”填充初始燃料。
3. 移交创作：当你们通过对话，将核心设定、开篇冲突、主要人物都讨论得比较清晰后，你可以说：“好的，基于我们讨论的这些，请开始撰写第一章的草稿。” 此时，聊天会话会生成一个结构化的“创作简报”，并移交到后台的写作任务队列。

3.4 检视运行与产出物

任务提交后，工作台就从“聊天模式”进入了“运行监控模式”。这是体现其“可检视性”的关键环节。

1. 切换到/console/tasks页面，你会看到刚刚创建的任务，状态可能是“运行中”。
2. 点击任务，进入详情页。这里是一个信息仪表盘，你会看到：
   • 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 使用工作台进行持续创作

第一章生成完毕后，创作并未结束，而是进入了新的阶段。

1. 审阅稿件：进入/console/manuscript/read，你可以舒适地阅读已生成的章节。界面通常提供良好的排版和导航。
2. 规划与调整：进入/console/storyboard，这里以看板或大纲形式展示了整个故事的结构。你可以看到已完成的章节和后续章节的计划。你可以直接在这里拖拽调整章节顺序，或编辑章节概要，这些改动会同步到记忆和后续的生成计划中。
3. 维护记忆库：进入/console/memory/banks，这里列出了所有的角色、世界等记忆库。你可以直接点击编辑，修正AI理解错误的地方，或者补充你新想到的细节。例如，把“主角怕黑”这个新设定手动添加到角色记忆中。
4. 继续写作：回到/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，部署流程大致如下：

1. 服务器准备：准备一台Linux服务器（如Ubuntu 22.04），安装Python、Git、Nginx等基础软件。
2. 获取代码：克隆项目到服务器，如/opt/novelclaw。
3. 配置环境：在项目根目录创建.env文件，填入所有必要的配置（数据库URL、API密钥、域名等）。务必设置强密码！
4. 配置服务：使用infra/systemd/下的示例文件，配置三个systemd服务（novelclaw-portal.service,novelclaw-multiagent.service,novelclaw.service），让它们能在后台稳定运行，并开机自启。
5. 配置反向代理：使用Nginx（infra/nginx/有示例配置）将域名（如writing.yourdomain.com）代理到本地的8012端口（核心工作台），并将/select-mode等路径代理到对应的服务端口。同时配置SSL证书（如使用Let‘s Encrypt）启用HTTPS。
6. 启动与测试：启动所有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写出的章节枯燥、逻辑混乱、或忘记了重要设定。
• 排查步骤：
  1. 检查记忆库：首先去/console/memory/banks确认相关的角色、世界设定是否准确、完整。AI只会基于你给它的“记忆”来生成。
  2. 审查故事板：查看当前章节的故事板概要是否清晰。一个模糊的概要（如“主角在城里遇到一些事”）会导致AI自由发挥过度。将其具体化（如“主角在黑市寻找零件时，意外撞见敌对帮派的交易”）。
  3. 分析progress.log：查看生成该章节前，AI记录的chapter_plan事件。看看AI自己理解的“本章计划”是什么，是否与你的预期相符。
  4. 优化提示词与会话：回到聊天会话，不要直接命令“重写”。而是与AI讨论：“我觉得这一章里主角的反应过于平淡了，不符合他之前‘谨慎多疑’的性格。我们在记忆库里是这么定义的。你认为在‘黑市撞见交易’这个情境下，一个谨慎多疑的人更可能有什么样的具体行为和内心活动？” 通过对话引导AI聚焦到具体问题。
• 根本技巧：将NovelClaw视为一个需要清晰指令和高质量输入的“超级实习生”。你给它的背景（记忆）和任务说明（故事板/聊天指令）越清晰、越具体，它的产出就越精准。

6.2 任务运行失败或卡住

• 症状：任务状态长时间处于“运行中”或直接变为“失败”。
• 排查步骤：
  1. 查看worker.log：这是第一现场。通常会有明确的错误信息，如APIError: Invalid API Key,ConnectionTimeout,ContextLengthExceeded。
  2. 检查模型配置：确认/console/models里配置的API密钥有效、额度充足，且端点地址正确（对于自定义模型）。
  3. 检查网络：如果是本地部署访问云端API，确保网络通畅。如果是服务器部署，检查服务器能否访问外部API服务。
  4. 检查资源：查看服务器CPU/内存使用情况。虽然NovelClaw本身不耗大量资源，但若同时运行多个任务，或生成超长文本，可能导致临时内存不足。

6.3 界面加载缓慢或操作无响应

• 症状：页面白屏、按钮点击后很久才有反应。
• 排查步骤：
  1. 浏览器开发者工具：按F12打开，查看“网络”(Network)和“控制台”(Console)标签页。是否有大量资源加载失败（404）？是否有JavaScript错误？
  2. 服务日志：查看后端服务的日志（在终端或systemd journal中），看是否有错误抛出。可能是某个API接口响应慢或出错。
  3. 数据库锁：如果使用SQLite且在频繁读写，偶尔可能遇到数据库锁问题。考虑升级到PostgreSQL以获得更好的并发性能（需要修改数据库连接配置）。
  4. 客户端缓存：尝试强制刷新浏览器（Ctrl+F5），清除缓存。

6.4 如何实现更复杂的叙事技巧？

NovelClaw提供了基础框架，但高级的叙事技巧需要你巧妙地利用现有工具。

• 多视角叙事：在角色记忆库中，为不同视角人物建立详细的“视角滤镜”（如语言风格、知识局限、情感倾向）。在故事板中，为特定章节指定视角人物。在生成该章节的提示词中，系统可以自动注入“以[角色A]的第一人称视角叙述，使用其口语化、多疑的语言风格”这类指令。
• 非线性叙事（如倒叙、插叙）：这需要手动规划。你可以在故事板中创建一个代表“回忆”的章节卡片，将其放在后面，但在章节概要里明确写明“此章为倒叙，内容为三个月前的事件”。同时，确保在生成该章时，相关的历史记忆被正确检索（可能需要手动在记忆库中为该事件打上时间戳标签）。
• 风格模仿：在风格记忆库中，不仅可以定义“文风：冷峻、简洁”，还可以粘贴一段你希望模仿的经典文本段落作为示例。在生成时，可以指令AI“参考风格记忆库中的示例文本的节奏和修辞手法”。

最终，NovelClaw是一个威力巨大的平台，但它不替代作者的创意和判断。它的价值在于将AI从“一个时而惊艳、时常糊涂的即兴表演者”，变成了一个“拥有完美记忆、严格遵循指令、并且工作过程完全透明的协作助手”。掌握它，意味着你将获得一种全新的、可规模化的叙事生产能力，去实现那些以往仅凭个人脑力难以驾驭的宏大故事构想。