# 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)