zkcoi/novelmaster

Fork 0

T

zkcoi ea8f6066c4 feat: initial commit

2026-06-23 20:29:02 +08:00

noma

feat: initial commit

2026-06-23 20:29:02 +08:00

.gitignore

feat: initial commit

2026-06-23 20:29:02 +08:00

README.md

feat: initial commit

2026-06-23 20:29:02 +08:00

USAGE.md

feat: initial commit

2026-06-23 20:29:02 +08:00

README.md

NovelMaster (Noma) 5.5

OpenNovel Workspace — 融合"欲望心理学引擎"与"硬状态基建"的人机协同长篇网文创作 IDE

项目简介

NovelMaster (Noma) 是基于 Claude Code 的长篇中文网文创作系统，旨在解决 AI 写作中长周期连载（数百至数千章）时面临的遗忘和幻觉两大核心问题。

系统核心采用双 Agent 架构——Context Agent 在写作前构建创作任务简报，Data Agent 在写作后提取实体和状态变化，配合 SQLite-first 数据层、向量检索、欲望心理学引擎驱动的爽感路由，以及六维自动化审查系统，为长篇网文创作提供完整的人机协同 IDE 体验。

核心特性

反幻觉基建

双 Agent 架构 — Context Agent（写作前简报）+ Data Agent（写作后提取），通过文件锁实现原子状态写入
SQLite-first 持久化 — 15+ 张数据表，追踪章节、场景、实体、别名、状态变更、人物关系、阅读力债务和审查指标
三层 RAG 检索 — 小说私有 + 工作区共享 + 插件内置，向量（sqlite-vec）+ BM25 关键词搜索 + Jina 重排序，通过 RRF 融合
线索编织节奏系统 — 管理三条故事线索（主线 60% / 感情 20% / 世界观 20%），可配置红线防止线索失衡
Catchup Agent — 自动检测 retcon 事件的脏标记，在作者修改设定时自动更新角色状态

创作引擎

欲望沙盒（Genesis Contract） — 定义故事核心欲望（权力、爱情、复仇、知识、生存、认可）、伦理边界和奇观体系
六维审查 — 爽点密度、一致性、节奏、OOC 检测、连续性、读者留存检查
心理学武器矩阵 — 三大爽感模型（禁忌僭越、降维打击、认知闭环），配合题材专属参考库
风格保持 — 写作检查清单、风格样本评估、阅读力信号保持语调一致

开发者体验

8 个 Claude Code 技能 — init、plan、write、review、resume、query、learn、dashboard
只读 Web 面板 — 实时项目状态、人物关系图、章节浏览，访问地址 http://127.0.0.1:8765
完整 CLI — 15+ 命令覆盖项目管理、索引、RAG 检索、实体提取和备份

架构设计

Claude Code
├── Skills (init / plan / write / review / query / resume / learn / dashboard)
├── Agents: Context / Data / 多维审查器 / Catchup
├── Data Layer: state.json / index.db / vectors.db / ledger.json
└── OpenNovel Workspace (ONW)
    ├── openspec/     → Genesis Contract（欲望沙盒 + 伦理）
    ├── core_engine/  → 状态机 + 记忆 RAG + LOD/Tick/Retcon
    ├── matrices/     → 多维爽感路由
    ├── interfaces/   → Web 面板（Flask/FastAPI + React）
    └── agents/       → 审查与执行矩阵

快速开始

前置条件

Python 3.14+
Claude Code（含插件支持）
Ollama（本地 Embedding）或 OpenAI 兼容 API（云端 Embedding）
Jina API Key（重排序，可选）

1. 安装插件

claude plugin marketplace add dadizk/novelmaster --scope user
claude plugin install novelmaster@novelmaster-marketplace --scope user

2. 安装依赖

cd NovelMaster/noma
pip install -r requirements.txt

3. 配置 Embedding

创建 .env 文件（项目级 .noma/config.env 或全局 ~/.claude/novelmaster/.env）：

# 云端方案（ModelScope Qwen3）
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_key

# 本地方案（Ollama）
# EMBED_BASE_URL=http://127.0.0.1:11434/v1
# EMBED_MODEL=bge-m3:latest
# EMBED_API_KEY=ollama

# 重排序（可选）
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_jina_key

4. 初始化小说项目

/noma-init --title "我的小说" --genre "xuanhuan" --target-chapters 600

5. 开始写作

/noma-plan 1      # 规划卷纲和章纲
/noma-write 1     # 写第 1 章
/noma-review 1    # 审查第 1 章

技能模块

技能	命令	说明
初始化	`/noma-init`	初始化新小说项目，设定题材、目标章节数和核心欲望
规划	`/noma-plan`	从总大纲生成卷纲和章纲，继承创作约束
写作	`/noma-write`	撰写章节（2000-2500 字），含上下文构建、草稿、审查、润色和数据提取
审查	`/noma-review`	六维章节质量审查，含多个审查 Agent
恢复	`/noma-resume`	恢复中断的任务，精确追踪工作流状态
查询	`/noma-query`	查询角色、能力、势力、道具、伏笔和阅读力状态
学习	`/noma-learn`	将成功写作模式提取到 Wiki 模式库
面板	`/noma-dashboard`	启动只读 Web 面板，可视化项目状态

CLI 命令

所有 CLI 命令通过 noma/scripts/noma.py 统一入口：

# 项目管理
python noma.py where              # 定位项目根目录
python noma.py preflight          # 全组件健康检查
python noma.py use <project>      # 切换活跃项目
python noma.py status             # 查看项目状态概览

# 数据操作
python noma.py index stats        # 索引统计（实体、章节、场景）
python noma.py state              # 查看当前状态快照
python noma.py entity <name>      # 查询实体详情
python noma.py update-state       # 强制状态对齐
python noma.py backup             # 创建项目备份
python noma.py archive <ch>       # 归档已完成章节

# RAG 检索
python noma.py rag search --query "爽点设计"   # 向量搜索
python noma.py rag search --query "打脸" --type keyword  # BM25 关键词搜索

# 上下文与工作流
python noma.py context            # 查看当前上下文包
python noma.py workflow detect    # 检测工作流状态问题
python noma.py migrate            # 跨版本数据迁移
python noma.py wiki               # 管理 Wiki 模式库
python noma.py extract-context    # 手动触发上下文提取

RAG 检索系统

三层架构

层级	路径	范围
小说私有	`.noma/rag/project/`	仅当前小说可用
工作区共享	`.noma/rag/shared/`	工作区内所有小说共享
插件内置	`noma/matrices/shared/`	系统级模板

检索管线

用户查询
    ↓
向量搜索（sqlite-vec, top-k=30） ──┐
BM25 关键词搜索（top-k=20） ───────┤ → RRF 融合（k=60）→ 重排序（Jina, top-n=10）→ 上下文包
    ↓                              │
系统模板（直接匹配） ──────────────┘

RAG 管理命令

# 关键词搜索（推荐用于精确查询）
python noma.py rag search "爽点" --layers system
python noma.py rag search "剑修" --layers project,system

# 列出系统层可用模式
python noma.py rag list --layer system

# 同步模式到系统层
python noma.py rag sync --pattern-id <id>
python noma.py rag sync --all

爽感心理学引擎

三大心理张力模型，用于设计满足感的剧情爽点：

模型	ID	说明
禁忌僭越	`taboo-transgression`	边缘拉扯、危险感、高压情绪释放
降维打击	`overkill-reversal`	碾压、反转、绝地反击、战力差逆转
认知闭环	`cognitive-closure`	多线伏笔收束、解谜快感

每个模型都具备题材感知能力，内置玄幻、狗血甜宠、古言宫斗、现实题材、规则怪谈、知乎短文等题材的专属参考库。

项目结构

NovelMaster/
├── noma/                          # 插件源码
│   ├── .claude/                   # Claude Code 插件配置
│   │   ├── plugin.json            # 插件元信息（v5.5.4, GPL-3.0）
│   │   └── settings.json          # 工具权限
│   ├── SKILL.md                   # 技能入口
│   ├── README.md                  # 本文件
│   ├── requirements.txt           # Python 依赖
│   │
│   ├── openspec/                  # 数据标准
│   │   ├── genesis_contract.json  # 核心欲望 + 伦理 + 奇观
│   │   └── project.md
│   │
│   ├── core_engine/               # 核心引擎模块
│   │   ├── state_manager/         # 状态机（原子写入）
│   │   ├── memory_rag/            # RAG 适配器 + 向量索引
│   │   └── configurators/         # IDE 适配器
│   │
│   ├── agents/                    # Agent 矩阵
│   │   ├── context-agent.md       # 写作前上下文构建
│   │   ├── data-agent.md          # 写作后实体提取
│   │   ├── planners/              # 大纲与章纲规划器
│   │   ├── writers/               # 风格保持文本生成器
│   │   └── checkers/              # 8 个审查 Agent
│   │
│   ├── matrices/                  # 心理学武器库
│   │   ├── catharsis_models/      # 3 大爽感模型
│   │   └── genres/                # 题材专属参考
│   │
│   ├── interfaces/                # 人机界面
│   │   └── web_dashboard/         # Flask/FastAPI + React 面板
│   │
│   ├── scripts/                   # 数据模块 + CLI
│   │   ├── data_modules/          # 配置、状态、索引、RAG、上下文
│   │   └── noma.py                # CLI 入口
│   │
│   ├── skills/                    # Claude Code 技能
│   │   ├── noma-init/             # 项目初始化
│   │   ├── noma-plan/             # 大纲规划
│   │   ├── noma-write/            # 章节写作
│   │   ├── noma-review/           # 质量审查
│   │   ├── noma-resume/           # 任务恢复
│   │   ├── noma-query/            # 数据查询
│   │   ├── noma-learn/            # 模式学习
│   │   └── noma-dashboard/        # Web 面板启动
│   │
│   ├── references/                # 共享引用
│   └── docs/                      # 架构文档
│
├── workspaces/                    # 小说项目
│   └── 九天神帝/                   # 示例小说
│       ├── .noma/                 # 项目数据层
│       ├── 正文/                   # 章节（markdown）
│       ├── 大纲/                   # 大纲
│       ├── 设定集/                 # 角色、地点、势力
│       ├── 审查报告/               # 审查报告
│       └── 输出/                   # 导出内容
│
├── USAGE.md                       # 使用指南（中文）
└── LICENSE                        # GPL-3.0

配置说明

所有配置从 .env 文件加载，优先级顺序：

项目级：<project>/.noma/config.env
全局级：~/.claude/novelmaster/.env
默认值：硬编码回退（ModelScope Qwen3-Embedding-8B、Jina Reranker v3）

关键配置参数

参数	默认值	说明
`EMBED_BASE_URL`	ModelScope API	Embedding 服务地址
`EMBED_MODEL`	Qwen3-Embedding-8B	Embedding 模型名
`RERANK_BASE_URL`	Jina API	重排序服务地址
`RERANK_MODEL`	jina-reranker-v3	重排序模型名
`VECTOR_TOP_K`	30	向量搜索 top-k
`BM25_TOP_K`	20	BM25 搜索 top-k
`RERANK_TOP_N`	10	重排序后 top-n
`RRF_K`	60	RRF 融合常数
`QUEST_RATIO`	0.6	主线比例
`FIRE_RATIO`	0.2	感情线比例
`CONSTELLATION_RATIO`	0.2	世界观线比例

完整配置参考见 docs/rag-and-config.md。

题材支持

题材	目录	核心能力
玄幻/修仙	`xuanhuan/`	修炼等级、能力体系、宗门政治
狗血甜宠	`dog-blood-romance/`	角色原型、情感张力、三角关系
古言/宫斗	`period-drama/`	宫廷权谋、等级制度、政治博弈
现实题材	`realistic/`	社会议题、职场动态、接地气的冲突
规则怪谈	`rules-mystery/`	线索设计、诡计设计、逻辑推理
知乎短文	`zhihu-short/`	钩子技巧、情节压缩、反转结尾

文档索引

文档	路径
架构说明	`noma/docs/architecture.md`
命令详解	`noma/docs/commands.md`
RAG 与配置	`noma/docs/rag-and-config.md`
题材模板	`noma/docs/genres.md`
OpenSpec 数据结构	`noma/docs/openspec.md`
CoreEngine	`noma/docs/core_engine.md`
Matrices	`noma/docs/matrices.md`
Interfaces	`noma/docs/interfaces.md`
Agents	`noma/docs/agents.md`
运维文档	`noma/docs/operations.md`
教程	`noma/docs/Tutorial.md`

许可证

本项目采用 GNU General Public License v3.0 许可 — LICENSE

README.md Unescape Escape

NovelMaster (Noma) 5.5

目录

项目简介

核心特性

反幻觉基建

创作引擎

开发者体验

架构设计

快速开始

前置条件

1. 安装插件

2. 安装依赖

3. 配置 Embedding

4. 初始化小说项目

5. 开始写作

技能模块

CLI 命令

RAG 检索系统

三层架构

检索管线

RAG 管理命令

爽感心理学引擎

项目结构

配置说明

关键配置参数

题材支持

文档索引

许可证

README.md