feat: initial commit

2026-06-23 20:29:02 +08:00
commit ea8f6066c4
217 changed files with 60754 additions and 0 deletions
@@ -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)