墨枢：AI 辅助长篇小说创作系统

墨枢 是一个作者主导的本地小说创作工具，提供章节管理、版本化保存、Story Bible 事实与事件账本、AI 续写、RAG 上下文检索、一致性检查和多维审核。

项目的核心原则是：作者数据是唯一真源，AI 内容经作者审阅；RAG、图谱和统计都是可重建的派生数据。 对话续写、局部改写与「起草下一章」入口均返回候选，作者在创作对话中按三档审核模式裁决；旧 auto-chapter 端点保留候选形态，前端已不再直接调用。 详细设计见 ARCHITECTURE.md。

当前可用能力

• 用户注册、登录和小说所有权隔离。
• 创建小说只需要一个名称，其他信息全部可选。进工作台后可以直接和 AI 交流：你用自己的话讲设定，AI 判断哪些需要落库（类型、简介、世界观、人物、设定事实、卷/章计划），给出结构化提案，你确认后才写入。长篇按两层规划：全书用卷/阶段覆盖（预计篇幅可填 1–3000 章），只有开头若干章给逐章大纲。
• VS Code 式创作工作区：活动栏、章节目录、正文/设定标签、常驻对话和底部保存状态；窄屏使用上下分区。
• 小说级持久对话：讨论与续写共用历史，跨章、刷新后可恢复；输入框固定在底部，较早记录可分页加载。
• 对话回复只作为候选，续写采纳校验章节与正文快照；失败问题保留，可重新编辑发送。
• 对话与高级续写共用有效前章简介，按来源版本、章节范围和预算筛选；对话可展开“本次参考简介”并查看来源原文。
• 创作对话 Agent 可主动查阅设定账本、角色卡、前章简介、全书大纲与前文正文，交稿前可用一致性检查自查草稿；还可经能力工具发起高级续写、编排、选区改写与剧情方向等生成动作，产出一律为候选提案，按本书审核模式处置；检索按作者归属、作品生命周期与章节边界受权，查阅动作在生成状态中可见。
• 高级多阶段续写、编排、局部改写、剧情方向与资料检索是创作对话 Agent 的能力工具：由模型按作者意图自主调用，调用过程在对话中内联展示，管理型内容（章节记忆、文风样本、角色统计）在「设定」页维护。
• 小说与章节基础管理（角色管理后端域已就绪，界面入口规划中）。
• Story Bible 事实账本与剧情事件 CRUD，生成上下文按目标章读取当时有效的事实及已发生事件，计划事件不作为正式剧情注入。
• 设定账本页面：编辑世界观，维护人物事实、剧情事件和伏笔，支持章节关联与状态变更。
• 选区改写：原文与可编辑候选对照，确认后精确替换；支持取消请求，正文变动时阻止旧候选覆盖新稿。
• 整本 TXT 导出：按章节顺序导出全部已保存正文，支持中文文件名。
• 章节摘要分页、正文按需加载、服务端分配下一章编号。
• 章节乐观版本控制，避免迟到的自动保存覆盖新稿。
• 保存同事务保留原文版本与简介任务；改稿使旧简介过期，旧提取结果不能发布为当前记忆。
• 工具区「章节记忆」可查看简介、出处与原文历史；后台提取支持租约恢复和有限重试，默认需显式启用。
• 409 冲突对比弹窗：我的版本 vs 服务端版本，可覆盖、采纳或另存新章。
• 离线草稿保护：断网时草稿留在本机，恢复连接后自动重放保存。
• 有界撤销历史、串行 latest-only 自动保存和可取消的 SSE 请求。
• 工作台键盘快捷键：保存、撤销/重做和相邻章节切换。
• 深浅「纸墨」主题切换，可跟随系统偏好并记住手动选择。
• 统一字数统计：前后端按非空白 Unicode 字符计算章节与全书字数。
• LangGraph 三阶段生成工作流，带统一上下文预算和有限重试。
• Chroma 持久 RAG，按小说和章节范围过滤，支持覆盖更新和清理。
• 模型客户端与输出校验共用入口，截断回复不会成为完整候选；未知故事日不再按第 1 天过滤剧情。
• 六维章节审核（后端已实现、有测试；作者侧目前可经对话 Agent 交稿前自查触达，独立审核入口待露出），限制并发；任一审核失败时不会误报“可发布”。
• Unified MCP 只公布真实实现的能力；未实现操作明确返回失败。

当前技术基线

后端：

• Python 3.12
• FastAPI、Pydantic 2、SQLAlchemy
• SQLite
• LangChain、LangGraph、LlamaIndex
• Chroma
• OpenAI 兼容模型接口（LM Studio 本地模型或 DeepSeek 远程模型）

前端：

• Next.js 15、React 19、TypeScript
• MUI 6、Emotion

PostgreSQL、Qdrant、Redis 和 Neo4j 仍属于可选演进方向。Docker Compose 中存在相关服务定义，不代表当前主链路已经依赖它们。

启动与文档导航

首次安装、模型配置、升级及数据库备份统一见 QUICKSTART.md，避免多处维护启动命令。

需要了解什么	文档
如何写作、连续交流、处理冲突与导出	使用指南
当前架构和数据边界	ARCHITECTURE.md
AI 编排、Prompt、记忆、工具与效果评测	AI 应用架构评审
底层问题与分阶段改造	底层架构评审、架构实施蓝图
原文、简介、大纲、核心设定四层	记忆分层设计（L0-L3 当前范围已接通，受有界扫描与预算约束）
记忆实时性与真实性	记忆实时性与真实性改进方案（快照栅栏、来源和后续演进）
实施状态、验收与待办监督	实施监督
当前状态与下一步优先级	REQUIREMENTS_ANALYSIS.md
API 字段、状态及错误	API 对接文档
前端模块与交互规范	前端开发指南、工作区设计规范
对话与高级工具的传输差异	AI 请求指南
测试范围与运行方式	backend/TESTING.md
固定质量样例与真实效果验收方法	evaluations/README.md（12 例已准备，真实评测未执行）

本地验证

后端：

cd backend
.venv/bin/python run_tests.py --mode all

前端：

cd frontend
npm run lint
npm run typecheck
npm test
npm run build

Node 25/26 若出现原生 localStorage 与 jsdom 冲突，可运行 NODE_OPTIONS=--no-experimental-webstorage npm run test，让浏览器测试使用 jsdom 的存储实现。

run_tests.py 会原样返回 pytest 的退出码，任何依赖、收集或断言失败都会使命令失败。

目录

墨枢/
├── backend/
│   ├── app/api/routes/       API 与权限边界
│   ├── app/crud/             数据访问
│   ├── app/models/           SQLAlchemy 与 Pydantic 模型
│   ├── app/services/         AI、RAG、一致性和审核服务
│   ├── migrations/           Alembic 迁移（结构演进的唯一入口）
│   └── tests/                自动化测试
├── frontend/
│   ├── app/                  Next.js 页面
│   ├── components/           UI 组件
│   ├── hooks/                保存、历史和交互状态
│   └── lib/                  API 与 SSE 客户端
├── docs/
│   ├── design/              架构与记忆设计文档
│   ├── plan/                需求分析与迭代计划（含历史归档）
│   └── guide/               使用与对接指南
├── evaluations/             记忆质量评测基线（cases + 真实运行结果）
├── ARCHITECTURE.md          架构原则与演进边界
└── AGENTS.md                开发规范

已知边界

• 持久对话从本版本开始记录，旧版只存在内存且已清空的交流无法恢复。当前每本小说一条连续对话，尚未支持多个对话分支。

• 创作对话是带受权只读检索工具与提案制能力工具的原生 function calling Agent；基础上下文按预算注入最近历史、当前正文、已确认事实/事件及有效前章简介，生成前由系统锚定权威章数与落点，更多资料与生成动作由模型通过工具按意图主动调用，产出均为候选。

• 已送达对话保存在数据库中；未能送达的问题会在当前页面标记，需恢复连接后重新发送。模型只接收有界的最近上下文（历史最多 8000 字符、最近 20 轮）；尚未实现跨全书对话的长期摘要记忆。

• 停止回复会将记录标记为已取消并忽略迟到结果，不保证上游模型服务同时停止计算。

• 改写支持整段候选审阅与采纳，尚未实现逐句差异高亮和逐句采纳；导出当前仅支持 TXT，EPUB 待实现。

• 结构化 Story Bible 已落地事实与事件账本，并已注入生成上下文；L2 大纲和 L3 人物/物品状态已接入独立模型、来源核验和作者审阅。地点模型与更广的全书语义召回仍未纳入当前核心能力。

• 离线草稿恢复依赖工作台已成功加载章节；无网络冷启动时的章节缓存与自动恢复尚未支持。

• 四层记忆中 L0 原文版本、L1 简介任务、L2 计划/实际大纲、L3 人物/物品状态及有界共享召回已接入网页端；状态变化仍需作者审阅，扫描和上下文预算省略会在 manifest 中说明。DSH 记忆插件是额外适配层。

• 简介提取和 RAG 投影均使用数据库持久任务、租约恢复、版本栅栏和查询/重试入口。

• 真正的模型 token 流仍受生成工作流的编排预算限制；客户端取消已经贯通，但最终正文主要在生成阶段完成后输出。

• init_db.py 已统一空库/旧库/已管理库三种路径，Alembic 是结构演进唯一入口；旧库一次性过渡时会补建缺失表并 stamp head，其列级差异（如旧 chapters 缺检查约束）由兼容补齐覆盖，PostgreSQL 上线前需验证迁移在该方言上的回滚与数据量压测。

项目状态

当前阶段：本地 Alpha，优先保证长篇写作的数据正确性、可恢复性和上下文边界；不把未实现能力标记为完成。