zkcoi/novelmaster
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial commit

Browse Source
This commit is contained in:
zkcoi
2026-06-23 20:29:02 +08:00
commit ea8f6066c4
217 changed files with 60754 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
noma/docs/README.md
+30
View File
@@ -0,0 +1,30 @@
# 文档中心
本目录承载 `README.md` 之外的详细说明，按模块拆分：
## 文档导航
- [架构与模块](architecture.md)
- [命令详解](commands.md)
- [RAG 与配置](rag-and-config.md)
- [题材模板](genres.md)
- [运维与恢复](operations.md)
## OpenNovel Workspace 结构文档
NovelMaster 基于 OpenNovel Workspace (ONW) 5.0 架构，文档对应关系如下：
| ONW 目录 | 说明 | 文档 |
|----------|------|------|
| `openspec/` | 全局数据标准与契约 | [openspec.md](openspec.md) |
| `core_engine/` | 融合状态机与记忆引擎 | [core_engine.md](core_engine.md) |
| `matrices/` | 心理学与叙事学武器库 | [matrices.md](matrices.md) |
| `interfaces/` | 人机协同创作者上帝控制台 | [interfaces.md](interfaces.md) |
| `agents/` | 审查与执行矩阵 | [agents.md](agents.md) |
## 建议阅读顺序
1. 先看 `../README.md`（安装与上手）
2. 再看 `architecture.md`（理解系统设计）
3. 再看 `openspec.md` / `core_engine.md` / `matrices.md` / `interfaces.md` / `agents.md`（理解 ONW 架构）
4. 最后按需查阅命令和运维文档
noma/docs/Tutorial.md
+331
View File
@@ -0,0 +1,331 @@
# Noma 使用教程 - 从零开始写小说
## 目录
1. [快速开始](#1-快速开始)
2. [Dashboard 使用指南](#2-dashboard-使用指南)
3. [完整写作流程演示](#3-完整写作流程演示)
4. [范式转移教程](#4-范式转移教程)
5. [常见问题](#5-常见问题)
---
## 1. 快速开始
### 1.1 环境准备
```bash
# 1. 下载 noma 项目
cd novelmaster
# 2. 安装 Python 依赖
pip install -r requirements.txt
# 3. 安装 Node.js 依赖 (用于 Dashboard)
cd interfaces/web_dashboard/frontend
npm install
npm run build
cd ../../..
```
### 1.2 创建第一个项目
```bash
# 方式一：交互式创建
python -m scripts.noma init
# 方式二：命令行创建
python -m scripts.noma init --title "我的修仙小说" --genre "xuanhuan"
```
项目创建后会自动生成：
```
my_novel/
├── .noma/novel_data/ # 系统数据 (不要手动修改)
│ ├── state.json # 项目状态
│ ├── ledger.json # 资产账本
│ └── index.db # SQLite 数据库
├── 正文/ # 你的小说正文
├── 大纲/ # 章节大纲
└── 设定集/ # 世界观设定
```
### 1.3 启动 Dashboard
```bash
# 在项目目录下启动
cd my_novel
python -m interfaces.web_dashboard.server
# 或指定项目路径
python -m interfaces.web_dashboard.server --project-root /path/to/my_novel
```
浏览器自动打开 **http://127.0.0.1:8765**
---
## 2. Dashboard 使用指南
### 2.1 界面概览
Dashboard 包含以下模块：
| 模块 | 功能 |
|------|------|
| 📊 数据总览 | 项目进度、主角状态、伏笔追踪 |
| 👤 设定词典 | 角色/地点/物品/势力管理 |
| 🕸️ 关系图谱 | 3D 可视化关系网络 |
| 📝 章节一览 | 所有章节列表和统计 |
| 📁 文档浏览 | 正文/大纲/设定集文件浏览 |
| 🔥 追读力 | 章节吸引力分析 |
### 2.2 数据总览
显示当前项目最重要的指标：
- **总字数/目标字数** - 进度条展示
- **当前章节** - 进度百分比
- **主角状态** - 境界/位置
- **未回收伏笔** - 警告数量
- **Strand Weave** - Quest/Fire/Constellation 比例
### 2.3 设定词典
查看和管理所有实体：
1. **筛选** - 按类型筛选 (角色/地点/物品/势力/招式)
2. **查看详情** - 点击实体查看
3. **状态历史** - 查看属性变化记录
### 2.4 章节一览
| 列 | 说明 |
|----|------|
| 章节 | 第X章 |
| 标题 | 章节标题 |
| 字数 | 字数统计 |
| 地点 | 场景位置 |
| 角色 | 出场角色 |
---
## 3. 完整写作流程演示
下面以"修仙小说"为例，演示从0开始写一部小说。
### 3.1 Step 1: 创建项目
```bash
# 创建项目
python -m scripts.noma init --title "逆天修仙传" --genre "xuanhuan"
```
### 3.2 Step 2: 设定创世契约
编辑 `.noma/novel_data/genesis_contract.json`：
```json
{
"core_desire": {
"primary": "power",
"secondary": ["revenge", "immortality"],
"taboos": ["betray family"]
},
"ethical_inversion": {
"inverted_norms": ["benevolence", "humility"],
"world_rules": ["弱肉强食", "实力为尊"]
},
"core_spectacle": {
"ordinary_state": "修士争斗，资源争夺",
"spectacle_trigger": "以弱胜强，吞噬突破"
}
}
```
### 3.3 Step 3: 规划大纲
创建 `大纲/总纲.md`：
```markdown
# 《逆天修仙传》总纲
## 主角
- 姓名: 叶尘
- 初始: 废物少爷，丹田破碎
- 目标: 登顶修仙巅峰，为父报仇
## 境界体系
炼气 → 筑基 → 金丹 → 元婴 → 化神 → 大乘 → 渡劫
## 主线
1. 觉醒金手指 (1-10章)
2. 拜入宗门 (11-30章)
3. 宗门大比 (31-50章)
4. 揭开身世 (51-80章)
5. 登顶之路 (81-100章)
```
### 3.4 Step 4: 写章节大纲
创建 `大纲/第0001章.md`：
```markdown
# 第0001章大纲: 废物少爷
## 目标
- 字数: 3000字
- Strand: Quest
- 张力: 30/100
## 情节
1. 叶尘被家族放弃
2. 父亲失踪之谜
3. 意外获得金手指
## 钩子
- 钩子1: 父亲失踪 (长线伏笔)
- 钩子2: 金手指来历 (中线伏笔)
## 禁止
- 不要让主角立即爆发
- 不要过早揭示金手指全貌
```
### 3.5 Step 5: 写正文
基于大纲写作，参考 `agents/writers/immersive-writer.md` 的感官描写指导。
### 3.6 Step 6: 审查
```bash
# 审查第1章
python -m scripts.noma review --chapter 1
```
审查项：
- 连贯性检查
- 张力检查
- 一致性检查
- 爽点密度
### 3.7 Step 7: 数据回写
系统自动将以下数据写入数据库：
- 实体提取 (角色/地点/物品)
- 章节摘要
- 状态变化
- RAG 向量索引
### 3.8 Step 8: 继续下一章
重复 Step 4-7。
---
## 4. 范式转移教程
### 4.1 什么是范式转移？
范式转移是指在写作过程中中途改变世界观或设定：
> 例子："写到第50章，突然想把修仙改成克苏鲁风格"
### 4.2 传统方式的问题
- 需要手动修改所有历史章节
- 容易产生逻辑矛盾
- 工作量巨大
### 4.3 Noma 的解决方案：Retcon
Noma 提供热补丁机制，自动处理范式转移：
```
1. 输入新设定 → "改成克苏鲁风格"
↓
2. 扫描账本 → 发现冲突 (浩然正气剑)
↓
3. 生成补丁 → "将正气剑转为邪神之物"
↓
4. 人工确认 → 选择要应用的变更
↓
5. 自动更新 → 数据库/缓存/上下文全部刷新
↓
6. 继续写作 → 基于新设定继续
```
### 4.4 操作步骤
1. 打开 Dashboard
2. 点击左侧菜单 **"Retcon 仲裁台"**
3. 输入新设定描述
4. 查看冲突分析
5. 选择要应用的变更
6. 点击 **"应用补丁"**
---
## 5. 常见问题
### Q: 如何查看项目状态？
```bash
python -m scripts.noma query state
```
或打开 Dashboard → 数据总览
### Q: 如何备份项目？
```bash
python -m scripts.noma backup
```
### Q: 如何迁移到新设备？
1. 复制整个项目文件夹
2. 安装依赖
3. 运行 `python -m scripts.noma migrate`
### Q: Dashboard 无法启动？
```bash
# 检查端口是否被占用
lsof -i :8765
# 指定其他端口
python -m interfaces.web_dashboard.server --port 8888
```
### Q: 如何导入已有的小说？
```bash
# 放到 正文/ 目录
mv my_novel.txt 正文/第0001章-标题.md
# 运行实体提取
python -m scripts.noma extract-entities --chapter 1
```
---
## 附录: CLI 命令速查
| 命令 | 功能 |
|------|------|
| `noma init` | 初始化项目 |
| `noma plan` | 规划大纲 |
| `noma write` | 写章节 |
| `noma review` | 审查章节 |
| `noma query` | 查询状态 |
| `noma resume` | 恢复任务 |
| `noma dashboard` | 启动面板 |
---
## 下一步
- 查看 [架构文档](architecture.md)
- 查看 [命令详解](commands.md)
- 查看 [题材模板](genres.md)
noma/docs/agents.md
+70
View File
@@ -0,0 +1,70 @@
# agents/ 目录说明
## 目录定位
`agents/` 是 OpenNovel Workspace 的**支柱4**，承载审查与执行矩阵。
## 目录结构
```text
agents/
├── planners/ # 负责调度 Hooks 平账与挂载张力模型
├── writers/
│ └── immersive-writer.md # 负责感官颗粒度放大
├── catchup_agent.py # [★特性] 负责计算休眠角色跨越时间后的状态
└── checkers/ # 大一统 Critic Agent
├── tension_checker.py # [★特性] 取代原爽点审查，校验情绪压强释放
└── consistency_checker.py # [★特性] 受"元叙事开关"控制的动态物理连贯性校验
```
## planners/ 子目录
负责调度 Hooks 平账与挂载张力模型：
- 分析当前章节的追读力状态
- 选择并加载适当的 `matrices/catharsis_models/` 模型
- 协调 Writer Agent 和 Checker Agent 的工作流程
## writers/ 子目录
### immersive-writer.md
负责感官颗粒度放大：
- 将大纲中的场景描述转化为高密度感官的文字
- 调用 catharsis model 提供情绪张力
- 保持与 `genesis_contract.json` 的一致性
## catchup_agent.py — 惰性时间推演
[★特性] 当休眠角色被唤醒时（如场景切换回某个背景人物）：
1. 读取该角色最后一次出现的时间和状态
2. 根据 `Tick` 时钟计算跨越的时间差
3. 惰性推演该角色在此期间可能发生的状态变化
4. 更新 `ledger.ts` 中的角色状态
## checkers/ 子目录
### tension_checker.py — 情绪压强校验
[★特性] 取代原爽点审查：
- 校验情绪压强的积累与释放是否符合选定的 catharsis model
- 检测"降维打击"、"禁忌僭越"等爽感路由的执行效果
- 与 `ledger.ts` 中的 hooks_pool 压强联动
### consistency_checker.py — 动态物理连贯性校验
[★特性] 受"元叙事开关"控制：
- 当 `Meta_Narrative_Panel.jsx` 中的第四面墙 Toggle 关闭时，执行严格的物理连贯性校验（战力/地点/时间线）
- 当 Toggle 开启时，自动跳过物理坐标和时间连贯性审查，允许"反规则"写法
- 调用 `genesis_contract.json` 中的约束作为校验基准
## 与其他模块的联动
- **openspec/**: `genesis_contract.json` 驱动 consistency_checker 的校验规则
- **matrices/**: tension_checker 调用 catharsis_models 执行情绪压强校验
- **core_engine/state_manager/**: catchup_agent 订阅 handoff.ts 的脏标记；checker 结果回写 ledger.ts
- **interfaces/web_dashboard/**: Dashboard 展示审查结果和 Agent 状态
noma/docs/architecture.md
+85
View File
@@ -0,0 +1,85 @@
# 系统架构与模块设计
## 核心理念
### 防幻觉三定律
| 定律 | 说明 | 执行方式 |
|------|------|---------|
| **大纲即法律** | 遵循大纲，不擅自发挥 | Context Agent 强制加载章节大纲 |
| **设定即物理** | 遵守设定，不自相矛盾 | Consistency Checker 实时校验 |
| **发明需识别** | 新实体必须入库管理 | Data Agent 自动提取并消歧 |
### Strand Weave 节奏系统
| Strand | 含义 | 理想占比 | 说明 |
|--------|------|---------|------|
| **Quest** | 主线剧情 | 60% | 推动核心冲突 |
| **Fire** | 感情线 | 20% | 人物关系发展 |
| **Constellation** | 世界观扩展 | 20% | 背景/势力/设定 |
节奏红线：
- Quest 连续不超过 5 章
- Fire 断档不超过 10 章
- Constellation 断档不超过 15 章
## OpenNovel Workspace 总体架构
```text
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
├─────────────────────────────────────────────────────────────┤
│ Skills (init / plan / write / review / query / dashboard)│
├─────────────────────────────────────────────────────────────┤
│ Agents: Context / Data / 多维 Checker / Catchup Agent │
├─────────────────────────────────────────────────────────────┤
│ Data Layer: state.json / index.db / vectors.db / ledger │
├─────────────────────────────────────────────────────────────┤
│ OpenNovel Workspace (ONW) │
│ ├── openspec/ (欲望沙盒与定制伦理) │
│ ├── core_engine/ (状态机与记忆引擎 + LOD/Tick/Retcon) │
│ ├── matrices/ (多维爽感路由) │
│ ├── interfaces/ (人机协同 IDE) │
│ └── agents/ (审查与执行矩阵) │
└─────────────────────────────────────────────────────────────┘
```
## 双 Agent 架构
### Context Agent（读）
职责：在写作前构建"创作任务书"，提供本章上下文、约束和追读力策略。
### Data Agent（写）
职责：从正文提取实体与状态变化，更新 `state.json`、`index.db`、`vectors.db`，保证数据链闭环。
## 六维并行审查
| Checker | 检查重点 |
|---------|---------|
| High-point Checker | 爽点密度与质量 |
| Consistency Checker | 设定一致性（战力/地点/时间线） |
| Pacing Checker | Strand 比例与断档 |
| OOC Checker | 人物行为是否偏离人设 |
| Continuity Checker | 场景与叙事连贯性 |
| Reader-pull Checker | 钩子强度、期待管理、追读力 |
## 四大独创系统特性
### 1. 欲望沙盒与定制伦理
打破传统网文分类，以"终极白日梦"和"道德免责声明"为最高执行上下文。核心数据契约包含 `core_desire`（核心欲望）、`ethical_inversion`（废除的现实道德）、`core_spectacle`（奇观日常化）。
### 2. 多维爽感路由
不再死守"打脸升级"，动态调用降维打击、禁忌僭越、延迟满足等高级心理学张力模型。调度机制：大纲 Planner Agent 在规划情节时，从 `matrices/catharsis_models/` 动态加载模型指导 Writer Agent。
### 3. 元叙事与法则覆写
允许人类一键降级物理校验，实现主角打破第四面墙、梦境潜入等"反规则"的神来之笔。界面上的物理开关开启后，自动关闭物理坐标和时间连贯性审查。
### 4. 意图漂移仲裁与热补丁
完美接纳作者中途修改设定的需求，自动扫描全局账本，生成设定兼容补丁，拒绝死锁。`Retcon_Arbitrator.jsx` 界面分析冲突并生成补丁方案。
noma/docs/commands.md
+101
View File
@@ -0,0 +1,101 @@
# 命令详解
## `/noma-init`
用途：初始化小说项目（目录、设定模板、状态文件）。
产出：
- `.noma/novel_data/state.json`
- `设定集/`
- `大纲/总纲.md`
## `/noma-plan [卷号]`
用途：生成卷级规划与章节大纲。
示例：
```bash
/noma-plan 1
/noma-plan 2-3
```
## `/noma-write [章号]`
用途：执行完整章节创作流程（上下文 → 草稿 → 审查 → 润色 → 数据落盘）。
示例：
```bash
/noma-write 1
/noma-write 45
```
常见模式：
- 标准模式：全流程
- 快速模式：`--fast`
- 极简模式：`--minimal`
## `/noma-review [范围]`
用途：对历史章节做多维质量审查。
示例：
```bash
/noma-review 1-5
/noma-review 45
```
## `/noma-query [关键词]`
用途：查询角色、伏笔、节奏、状态等运行时信息。
示例：
```bash
/noma-query 萧炎
/noma-query 伏笔
/noma-query 紧急
```
## `/noma-resume`
用途：任务中断后自动识别断点并恢复。
示例：
```bash
/noma-resume
```
## `/noma-dashboard`
用途：启动只读可视化面板，查看项目状态、实体关系、章节与大纲内容。
示例：
```bash
/noma-dashboard
```
说明：
- 默认只读，不会修改项目文件
- 适合排查上下文、实体关系和章节进度
## `/noma-learn [内容]`
用途：从当前会话或用户输入中提取可复用写作模式，并写入项目记忆。
示例：
```bash
/noma-learn "本章的危机钩设计很有效，悬念拉满"
```
产出：
- `.noma/novel_data/project_memory.json`
noma/docs/core_engine.md
+65
View File
@@ -0,0 +1,65 @@
# core_engine/ 目录说明
## 目录定位
`core_engine/` 是 OpenNovel Workspace 的**支柱2&3**，融合状态机与记忆引擎，承载"视锥剔除与热补丁防腐"特性。
## 目录结构
```text
core_engine/
├── state_manager/
│ ├── handoff.ts # [★特性] 帧交接协议 (含 LOD视锥剔除, Tick时钟)
│ ├── ledger.ts # 动态资产与负债账本
│ └── retcon_manager.ts # [★特性] 意图漂移管理与热补丁生成器
│
├── memory_rag/
│ ├── vectorstore_utils.py # 向量存储工具
│ └── context_cache.py # 上下文静态缓存与 Hash 脏标记更新
│
└── configurators/ # Cursor/Windsurf AI IDE 直接挂载适配器
```
## state_manager/ 子目录
### handoff.ts — 帧交接协议
引入 **LOD (Level of Detail / 视锥剔除)** 与 **Tick (全局时钟)** 机制：
- **LOD 视锥剔除**：只精确交接"在场"人物，休眠的背景人物不参与当前帧计算
- **Tick 全局时钟**：记录多线程悬置动作（Imminent Actions），确保时间线一致性
- **Handoff Commit**：AI 生成的下一章 `handoff.json` Diff 需等待人类审查并 Commit
### ledger.ts — 动态资产与负债账本
跟踪故事中的所有资产（正向积累）和负债（待兑现的承诺/伏笔）：
- 角色获得的能力、道具、资源（资产）
- 埋下的伏笔、承诺的冲突、待解决的悬念（负债）
- 当"元叙事开关"开启时，可监控 `hooks_pool` 压强，触发黑天鹅注入
### retcon_manager.ts — 意图漂移管理与热补丁生成器
当作者中途修改设定（如第150章要将《正统修仙》转入《克苏鲁修仙》）：
1. 扫描 `ledger.ts` 发现主角在第30章获得的【浩然正气剑】与新设定互斥
2. 生成补丁方案：将浩然正气剑设定为"上古邪神骨殖的伪装"，触发反噬转化为生存负债
3. 作者确认后，刷新 RAG 缓存，热补丁生效
## memory_rag/ 子目录
### context_cache.py
- 上下文静态缓存：存储已确认的剧情上下文
- Hash 脏标记更新：当 `retcon_manager.ts` 生成补丁时，强制清空受影响缓存
- 热更新网关：哈希监听器确保补丁作为最高权重压制历史设定幻觉
## configurators/ 子目录
AI IDE 适配器（如 Cursor / Windsurf），使核心引擎可以直接挂载到这些编辑器中。
## 与其他模块的联动
- **openspec/**: `genesis_contract.json` 中的三大变量驱动状态校验逻辑
- **agents/catchup_agent.py**: 订阅 `handoff.ts` 的脏标记，当休眠人物被唤醒时进行惰性时间推演
- **interfaces/web_dashboard/**: 展示 `Retcon_Arbitrator.jsx`（设定修改冲突分析）和 `Handoff_Diff_View.jsx`（交接审查）
noma/docs/genres.md
+53
View File
@@ -0,0 +1,53 @@
# 题材模板说明
系统内置 37+ 网文题材模板，支持单题材与复合题材。
## 玄幻修仙类（示例）
- 修仙
- 系统流
- 高武
- 西幻
- 无限流
- 末世
- 科幻
## 都市现代类（示例）
- 都市异能
- 都市日常
- 都市脑洞
- 现实题材
- 电竞
- 直播文
## 言情类（示例）
- 古言
- 宫斗宅斗
- 青春甜宠
- 豪门总裁
- 职场婚恋
- 民国言情
- 幻想言情
- 现言脑洞
- 女频悬疑
- 种田
- 年代
## 复合题材规则
- 支持 `题材A+题材B`（最多 2 个）
- 建议主辅比例 7:3
- 主线遵循主题材逻辑，副题材提供钩子/规则/爽点
示例：
- `都市脑洞+规则怪谈`
- `修仙+系统流`
## 题材与 Matrices 的关系
题材模板定义了故事的"骨架"，而 `matrices/catharsis_models/` 定义了故事的"灵魂"——即具体的情绪张力模型。
在 `/noma-plan` 生成大纲时，系统会根据所选题材从 `matrices/` 目录动态加载适当的心理学张力模型（如禁忌僭越、降维打击、认知闭环等），指导 Writer Agent 在具体情节中调用相应的爽感路由。
noma/docs/interfaces.md
+46
View File
@@ -0,0 +1,46 @@
# interfaces/ 目录说明
## 目录定位
`interfaces/` 是 OpenNovel Workspace 的**人机协同支柱**，承载"创作者上帝控制台"。
## 目录结构
```text
interfaces/
├── web_dashboard/
│ ├── Handoff_Diff_View.jsx # 状态交接人工审查 Commit 界面
│ ├── Retcon_Arbitrator.jsx # 设定修改冲突分析与补丁确认台
│ └── Meta_Narrative_Panel.jsx # "元叙事开关"与"黑天鹅注入"控制台
│
└── server.py # Dashboard 服务端
```
## web_dashboard/ 子面板
### Handoff_Diff_View.jsx — Commit 阻断台
- 强制展示 AI 生成的下一章 `handoff.json` Diff
- 等待人类微调并 Commit 后，写作流程才会继续
- 包含 LOD 视锥剔除后的在场人物列表和 Tick 时钟状态
### Retcon_Arbitrator.jsx — 设定修改冲突分析
- 当作者在写作中途修改设定时，输入需求
- 系统扫描 `ledger.ts` 和 `hooks_pool.ts` 发现冲突点
- 生成补丁方案供作者确认（如"浩然正气剑反噬"案例）
### Meta_Narrative_Panel.jsx — 元叙事开关与黑天鹅注入
- **第四面墙 Toggle**：物理开关，开启后发送信号给 `core_engine/validators`，自动关闭物理坐标和时间连贯性审查
- **黑天鹅/平账注入器**：UI 监控 `hooks_pool` 压强，当警告灯亮起，人类可点击一键注入"等价对冲债务"或"合理平账大纲提案"
## server.py
Dashboard 服务端，提供 Web UI 的数据接口。
## 与其他模块的联动
- **core_engine/state_manager/**: `Handoff_Diff_View.jsx` 读取 `handoff.ts` 的输出；`Retcon_Arbitrator.jsx` 调用 `retcon_manager.ts`
- **core_engine/memory_rag/**: `context_cache.py` 的脏标记触发 Dashboard 刷新
- **agents/**: Dashboard 展示 Agent 执行状态和审查结果
noma/docs/matrices.md
+61
View File
@@ -0,0 +1,61 @@
# matrices/ 目录说明
## 目录定位
`matrices/` 是 OpenNovel Workspace 的**★特性支柱**，承载心理学与叙事学武器库，即"多维爽感路由"。
## 目录结构
```text
matrices/
├── catharsis_models/ # 高阶爽感路由模型
│ ├── taboo-transgression.md # 禁忌僭越 (边缘拉扯/危险感)
│ ├── overkill-reversal.md # 降维打击与权力倒转
│ └── cognitive-closure.md # 认知闭环 (多线伏笔瞬间收束)
│
├── genres/ # 具体题材细分约束
│ └── ... # 对应 novelmaster-writer 的 genres/ 内容
│
└── shared/ # 共享模板与工具
```
## catharsis_models/ 子目录
改造自 `novelmaster-writer` 原有的 `genres/`（题材库），升维为情绪武器库。
### taboo-transgression.md — 禁忌僭越
边缘拉扯/危险感模型。模板包含：
- 禁忌场景的构建原则
- 道德风险的释放节奏
- 读者心理的安全边际管理
### overkill-reversal.md — 降维打击与权力倒转
降维打击模型。模板包含：
- 实力差距的戏剧化呈现
- 权力倒转的触发条件
- 反转后的余韵设计
### cognitive-closure.md — 认知闭环
多线伏笔瞬间收束模型。模板包含：
- 伏笔的埋设密度与分布
- 收束时的信息密度控制
- 认知缺口的填补节奏
## 调度机制
大纲 **Planner Agent** 在规划情节时，必须从 `matrices/catharsis_models/` 动态 `import` 一个模型来指导 **Writer Agent**。
示例流程：
1. `/noma-plan 1` 触发 Planner Agent
2. Planner 分析当前章节的追读力状态（hooks 压强、cool-point 位置）
3. Planner 选择合适的 catharsis model（如"降维打击"用于即将到来的冲突高潮）
4. Writer Agent 接收模型指导，在正文中调用对应的爽感路由
## 与其他模块的联动
- **openspec/genesis_contract.json**: 三大变量（`core_desire`、`ethical_inversion`、`core_spectacle`）作为常量决定 catharsis model 的选用优先级
- **core_engine/ledger.ts**: 负债（hooks_pool）压强触发 catharsis model 的动态切换
- **agents/checkers/tension_checker.py**: 取代原爽点审查，校验情绪压强释放是否遵循选定的 catharsis model
noma/docs/openspec.md
+46
View File
@@ -0,0 +1,46 @@
# openspec/ 目录说明
## 目录定位
`openspec/` 是 OpenNovel Workspace 的**支柱1**，承载全局数据标准与契约，定义故事的"欲望沙盒与定制伦理"。
## 目录结构
```text
openspec/
├── genesis_contract.json # [★特性] 核心欲望、伦理沙盒、奇观日常化定义
└── project.md # 项目规范文档
```
## genesis_contract.json
在 `novel-writer-openspec` 极度严苛的数据契约能力基础上，强制注入**创世契约 (Genesis Contract)**。
### 核心字段
| 字段 | 说明 | 作用 |
|------|------|------|
| `core_desire` | 核心欲望 | 主角最深层的驱动力，作为 RAG 检索 Top 1 权重 |
| `ethical_inversion` | 废除的现实道德 | 定义故事世界中哪些现实道德被打破或颠覆 |
| `core_spectacle` | 奇观日常化 | 定义故事的核心奇观及其与日常的结合方式 |
### 示例结构
```json
{
"core_desire": "以凡人之躯比肩神明，打破一切阶级桎梏",
"ethical_inversion": ["杀人无需偿命", "弱者无生存权", "情感是弱点"],
"core_spectacle": "修士与凡人共处的蒸汽朋克修仙世界",
"narrative_constraints": {
"max_consecutive_quest_chapters": 5,
"max_fire_gap_chapters": 10,
"max_constellation_gap_chapters": 15
}
}
```
## 与其他模块的联动
- **core_engine/**: `genesis_contract.json` 中的约束会被 `handoff.ts` 和 `consistency_checker.py` 引用，在帧交接和审查时强制校验
- **matrices/**: 三大变量驱动 `catharsis_models/` 中的爽感路由选择
- **interfaces/**: Dashboard 展示创世契约状态，提醒作者核心方向
noma/docs/operations.md
+137
View File
@@ -0,0 +1,137 @@
# 项目结构与运维
## 目录层级（真实运行）
在 Claude Code + Marketplace 安装下，至少有 4 层概念：
1. `WORKSPACE_ROOT`（Claude 工作区根，通常是 `${CLAUDE_PROJECT_DIR}`）
2. `WORKSPACE_ROOT/.claude/`（工作区级指针与配置）
3. `PROJECT_ROOT`（真实小说项目根，`/noma-init` 按书名创建）
4. `CLAUDE_PLUGIN_ROOT`（插件缓存目录，不在项目内）
### A) Workspace 目录（含 `.claude`）
```text
workspace-root/
├── .claude/
│ ├── .noma-current-project # 指向当前小说项目根
│ └── settings.json
├── 小说A/
├── 小说B/
└── ...
```
### B) 小说项目目录（`PROJECT_ROOT`）
```text
project-root/
├── .noma/ # 运行时数据（state/index/vectors/summaries）
├── 正文/ # 正文章节
├── 大纲/ # 总纲与卷纲
└── 设定集/ # 世界观、角色、力量体系
```
## 插件目录（Marketplace 安装）
插件不在小说项目目录内，而在 Claude 插件缓存目录。运行时统一用 `CLAUDE_PLUGIN_ROOT` 引用：
```text
${CLAUDE_PLUGIN_ROOT}/
├── skills/
├── agents/
├── scripts/
└── references/
```
### C) 用户级全局映射（兜底）
当工作区没有可用指针时，会使用用户级 registry 做 `workspace -> current_project_root` 映射：
```text
${CLAUDE_HOME:-~/.claude}/.noma/novel_data/workspaces.json
```
## OpenNovel Workspace 目录结构
```text
noma/
├── openspec/ # [支柱1] 全局数据标准与契约
│ ├── genesis_contract.json # [★特性] 核心欲望、伦理沙盒、奇观日常化定义
│ └── project.md
│
├── core_engine/ # [支柱2&3] 融合状态机与记忆引擎
│ ├── state_manager/
│ │ ├── handoff.ts # [★特性] 帧交接协议 (含 LOD视锥剔除, Tick时钟)
│ │ ├── ledger.ts # 动态资产与负债账本
│ │ └── retcon_manager.ts # [★特性] 意图漂移管理与热补丁生成器
│ │
│ ├── memory_rag/
│ │ ├── vectorstore_utils.py
│ │ └── context_cache.py # 上下文静态缓存与 Hash 脏标记更新
│ │
│ └── configurators/ # Cursor/Windsurf AI IDE 直接挂载适配器
│
├── agents/ # [支柱4] 审查与执行矩阵
│ ├── planners/ # 负责调度 Hooks 平账与挂载张力模型
│ ├── writers/
│ │ └── immersive-writer.md # 负责感官颗粒度放大
│ ├── catchup_agent.py # [★特性] 负责计算休眠角色跨越时间后的状态
│ └── checkers/ # 大一统 Critic Agent
│ ├── tension_checker.py # [★特性] 取代原爽点审查，校验情绪压强释放
│ └── consistency_checker.py # [★特性] 受"元叙事开关"控制的动态物理连贯性校验
│
├── matrices/ # [★特性] 心理学与叙事学武器库
│ ├── catharsis_models/ # 高阶爽感路由模型
│ │ ├── taboo-transgression.md # 禁忌僭越 (边缘拉扯/危险感)
│ │ ├── overkill-reversal.md # 降维打击与权力倒转
│ │ └── cognitive-closure.md # 认知闭环 (多线伏笔瞬间收束)
│ ├── genres/ # 具体题材细分约束
│ └── shared/
│
├── interfaces/ # [人机协同] 创作者上帝控制台
│ ├── web_dashboard/
│ │ ├── Handoff_Diff_View.jsx # 状态交接人工审查 Commit 界面
│ │ ├── Retcon_Arbitrator.jsx # 设定修改冲突分析与补丁确认台
│ │ └── Meta_Narrative_Panel.jsx # "元叙事开关"与"黑天鹅注入"控制台
│ └── server.py
│
└── .workspace/ # 用户的实际创作区
```
## 常用运维命令
统一前置（手动 CLI 场景）：
```bash
export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/noma.py" --project-root "${WORKSPACE_ROOT}" where)"
```
### 索引重建
```bash
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" index process-chapter --chapter 1
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" index stats
```
### 健康报告
```bash
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" status -- --focus all
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" status -- --focus urgency
```
### 向量重建
```bash
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" rag index-chapter --chapter 1
python "${SCRIPTS_DIR}/noma.py" --project-root "${PROJECT_ROOT}" rag stats
```
### 测试入口
```bash
pwsh "${CLAUDE_PLUGIN_ROOT}/scripts/run_tests.ps1" -Mode smoke
pwsh "${CLAUDE_PLUGIN_ROOT}/scripts/run_tests.ps1" -Mode full
```
noma/docs/rag-and-config.md
+48
View File
@@ -0,0 +1,48 @@
# RAG 与配置说明
## RAG 检索架构
```text
查询 → QueryRouter(auto) → vector / bm25 / hybrid / graph_hybrid
└→ RRF 融合 + Rerank → Top-K
```
默认模型：
- Embedding：`Qwen/Qwen3-Embedding-8B`
- Reranker：`jina-reranker-v3`
## 环境变量加载顺序
1. 进程环境变量（最高优先级）
2. 书项目根目录下的 `.env`
3. 用户级全局：`~/.claude/.noma/novel_data/.env`
## `.env` 最小配置
```bash
EMBED_BASE_URL=https://api-inference.modelscope.cn/v1
EMBED_MODEL=Qwen/Qwen3-Embedding-8B
EMBED_API_KEY=your_embed_api_key
RERANK_BASE_URL=https://api.jina.ai/v1
RERANK_MODEL=jina-reranker-v3
RERANK_API_KEY=your_rerank_api_key
```
说明：
- 未配置 Embedding Key 时，语义检索会回退到 BM25。
- 推荐每本书单独配置 `${PROJECT_ROOT}/.env`，避免多项目串配置。
## 热更新网关
在 `core_engine/memory_rag/` 中加入哈希监听器，一旦作者提交"设定补丁 (Retcon)"，系统会：
1. 强制清空受影响的上下文缓存
2. 将补丁作为最高权重压制历史设定幻觉
3. 触发 `retcon_manager.ts` 生成兼容补丁
## RAG 与 Genesis Contract
`openspec/genesis_contract.json` 中定义的三大变量（`core_desire`、`ethical_inversion`、`core_spectacle`）作为常量，永远留存在 RAG 检索的 Top 1 权重中，确保故事核心方向不被稀释。