# 小说工作台技术文档

本文档是项目唯一的技术说明，整合当前项目的架构、目录、文件职责、数据存储、接口、核心流程与测试。

最终文档体系只保留三份：

- `README.md`：项目入口、快速开始、默认配置。
- `docs/产品需求文档.md`：产品定位、流程、功能范围、交互。
- `docs/技术文档.md`：本文档，技术实现细节。

## 1. 总体架构

```text
┌─────────────────────────────────────────────────────────────┐
│                        浏览器（Web 前端）                      │
│  web/index.html                                             │
│  web/styles.css                                             │
│  web/app.js                                                 │
│      │                                                      │
│      │  fetch /api/*                                        │
│      ▼                                                      │
│  Node.js 本地服务                                            │
│  web/server.mjs                                             │
│      │                                                      │
│      │  child_process 调用 Python                            │
│      ▼                                                      │
│  Python 工作流脚本                                            │
│  工作流脚本/工作流引擎.py                                      │
│      │                                                      │
│      ├─► 步骤定义.py（字段/任务/格式规则）                      │
│      ├─► LLM配置.py（模型/API/调用统计）                       │
│      ├─► 共享.py（路径/写入/格式门禁）                         │
│      ├─► 资产步骤.py / 章节步骤.py / 提取步骤.py / 校验步骤.py   │
│      ├─► 结构化JSON.py / 世界观JSON.py                        │
│      └─► 同人提取/ 文风评分/ 等外部工具                         │
│              │                                              │
│              ▼                                              │
│  LLM API（OpenAI 兼容接口）                                   │
└─────────────────────────────────────────────────────────────┘
        │
        ▼
  小说项目/<类型>-<小说名>/
  （正文、知识库、提示词、运行记录等本地文件）
```

## 2. 工作区目录结构

```text
小说生成全流程/
├─ 启动工作台.bat               # Windows 一键启动
├─ 启动工作台.sh                # macOS / Linux / Git Bash 一键启动
├─ web/                         # Web 前端与本地服务
│  ├─ index.html                # 页面结构
│  ├─ styles.css                # 样式
│  ├─ app.js                    # 前端交互、流程状态机、本地项目恢复
│  └─ server.mjs                # Node 本地 HTTP 服务与 Python 桥接
├─ 工作流脚本/                  # Python 工作流引擎与步骤模块
│  ├─ 工作流引擎.py             # 唯一命令入口：输入解析、调度、失败输出
│  ├─ 步骤定义.py               # 任务输入字段、任务归属、格式规则、配置枚举
│  ├─ LLM配置.py                # LLM 调用、模型策略、token/耗时统计
│  ├─ 共享.py                   # 项目路径、checked_write、上下文拼装
│  ├─ 资产步骤.py               # 简介/世界观/语言风格/角色卡/关系卡/剧情/账本
│  ├─ 章节步骤.py               # 锚点/配置/台词/快照/正文/改写
│  ├─ 提取步骤.py               # 同人提取五步
│  ├─ 校验步骤.py               # 正文 LLM 校验
│  ├─ 结构化JSON.py             # JSON+Markdown 双文件资产生成
│  ├─ 世界观JSON.py             # 结构化世界观 JSON 生成
│  ├─ 章节输入判别.py           # 章节信息门禁
│  ├─ 小说简介判别.py           # 初始化资料门禁
│  ├─ 验证完整流程.py           # 无模型流程集成验证
│  ├─ 验证工作台验收.py         # 端到端验收
│  ├─ 工作台设置.json           # 模型/提供方/步骤开关/默认资产
│  ├─ 默认提示词/               # 新建项目复制的默认词库
│  ├─ 同人提取/                 # 同人提取参考实现（隔离运行）
│  └─ 文风评分/                 # SLOP/文风评分器（Node/TS）
├─ docs/                        # 产品与技术文档
│  ├─ 产品需求文档.md
│  ├─ 技术文档.md
│  └─ .gitignore
└─ 小说项目/                    # 所有本地小说项目
   ├─ 原创-<小说名>/
   └─ 同人-<小说名>/
```

## 3. 分层职责

### 3.1 前端 `web/app.js`

- 维护当前项目、章节、步骤状态机。
- 调用 `/api/workflow/run` 执行步骤脚本。
- 渲染文件树、文档预览、对话流、失败卡片、用量统计。
- 支持“可更新”全局资产点击后调用对应脚本。
- 启动时从 `小说项目/<项目>/运行记录/workflow-state.json` 恢复进度，并从执行日志回填历史用量。

### 3.2 本地服务 `web/server.mjs`

- 提供静态文件服务与 `/api/*` HTTP 接口。
- 项目/文件/章节/上传/评分/设置/模型列表接口。
- `/api/workflow/run` 启动 Python 工作流引擎子进程，并把结果或失败信息返回前端。
- 失败时解析 Python 输出的 JSON，附带 `usage` 返回给前端。

### 3.3 Python 工作流引擎

- `工作流引擎.py` 是所有脚本的唯一命令入口。
- 通过 `--task`、`--project`、`--input_mode` 接收请求。
- 使用 `步骤定义.py` 校验必填字段，按 `TASK_MODULES` 路由到具体步骤模块。
- 成功输出 `{"ok":true,"outputs":[...],"usage":{...}}`。
- 失败输出 `{"ok":false,"error":"...","usage":{...}}` 到 stderr。

### 3.4 步骤模块

| 模块 | 负责任务 |
| --- | --- |
| `资产步骤.py` | `compile_intro`、`generate_worldview`、`compile_style`、`generate_character`、`compile_relation`、`compile_plot`、`compile_volume`、`compile_ledger`、`generate_characters_batch`、`generate_relations_batch` |
| `章节步骤.py` | `compile_anchor`、`compile_config`、`compile_dialogue`、`compile_snapshot`、`generate_prose`、`rewrite_prose` |
| `提取步骤.py` | `text_stats`、`word_frequency`、`style`、`positive_vocabulary`、`exclusive_vocabulary` |
| `校验步骤.py` | `validate` |
| `结构化JSON.py` | 固定格式资产的 JSON+Markdown 双文件生成与渲染 |
| `世界观JSON.py` | `generate_worldview_json` |

### 3.5 工作流任务与产物

`POST /api/workflow/run` 支持以下任务：

| task | 业务 | 产物 |
| --- | --- | --- |
| `text_stats` | 原文统计 | `提取/原文统计.txt` |
| `word_frequency` | 高频词 | `提取/高频词.txt` |
| `style` | 原文风格 | `提取/原文风格.md` |
| `positive_vocabulary` | 正向词库 | `提取/正向词库.md` |
| `exclusive_vocabulary` | 专属词库 | `提取/专属词库.md` |
| `compile_intro` | 小说简介 | `知识库/小说简介.md/.json` |
| `generate_worldview_json` | 世界观 | `知识库/世界观.md/.json` |
| `compile_style` | 语言风格 | `知识库/语言风格.md/.json` |
| `compile_character_roster` | 角色名单 | `知识库/角色名单.md/.json` |
| `generate_characters_batch` | 批量角色卡 | `知识库/角色卡/角色卡-*.md/.json` |
| `generate_relations_batch` | 批量关系卡 | `知识库/关系卡/关系卡-*.md/.json` |
| `compile_plot` | 剧情书 | `剧情/剧情书.md/.json` |
| `compile_volume` | 剧情卷 | `剧情/剧情卷/<卷名>.md/.json` |
| `compile_ledger` | 信息账本 | `知识库/信息账本.md/.json` |
| `compile_anchor` | 强制设定锚点 | `提示词/<章节>/强制设定锚点.md/.json` |
| `compile_config` | 配置 | `提示词/<章节>/配置.md` |
| `compile_dialogue` | 台词 | `提示词/<章节>/台词.md/.json` |
| `compile_snapshot` | 最终提示词快照 | `提示词/<章节>/最终提示词快照.md` |
| `generate_prose` | 正文 | `正文/<章节>.txt` |
| `rewrite_prose` | 改写正文 | `草稿/<章节>-改写预览.txt` |
| `validate` | 校验与验收 | `提示词/<章节>/校验报告.md/.json` |

## 4. 请求链路

```text
用户在浏览器点击“下一步”或“发送”
  → app.js 组装 task/input/naturalInput
  → POST /api/workflow/run
  → server.mjs 启动 Python：工作流引擎.py --task ... --project ...
  → 引擎解析输入 → 路由到步骤模块
  → 步骤模块读取项目上下文 → 调用 LLM API
  → 写入正式产物文件
  → Python 输出 JSON（outputs + usage）
  → server.mjs 返回 JSON
  → app.js 读取产物、更新文件树/对话/用量
```

### 4.1 命令行调用

所有步骤也可直接调用 Python 引擎：

```bash
# 自然语言输入
python 工作流脚本/工作流引擎.py \
  --task generate_prose \
  --project 原创-作品名 \
  --input_mode natural \
  --natural_input "本章需要……"

# 结构化输入
python 工作流脚本/工作流引擎.py \
  --task compile_anchor \
  --project 原创-作品名 \
  --input_mode structured \
  --input '{"chapter":"第1章：大婚"}'
```

模型、温度、API 配置统一由 `工作流脚本/工作台设置.json` 与 `LLM配置.py` 控制。

## 5. 数据存储

### 5.1 项目目录

每个小说项目位于 `小说项目/<类型>-<小说名>/`。正式资产以普通文件保存，便于查看和 Git 管理。

### 5.2 JSON + Markdown 双文件

固定格式资产同时生成：

- `xxx.json`：结构化源，程序读写。
- `xxx.md`：可读版，网页展示。

### 5.3 运行记录

| 文件 | 作用 |
| --- | --- |
| `运行记录/workflow-state.json` | 项目/章节进度、用户输入、用量统计 |
| `运行记录/执行记录/初始化.jsonl` | 初始化步骤 LLM 调用日志 |
| `运行记录/执行记录/章节-<章节名>.jsonl` | 章节步骤 LLM 调用日志 |
| `运行记录/对话记录.md` | 对话区快照，刷新恢复用 |
| `运行记录/初始化资料.md` | 初始化累积用户信息 |
| `运行记录/章节输入/<章节名>.md` | 本章累积用户信息 |

### 5.4 模型与设置

- `工作流脚本/工作台设置.json` 保存提供方、模型、API Key、步骤开关、默认资产。
- `LLM配置.py` 从该文件读取配置，并支持环境变量覆盖。
- API Key 会通过环境变量传给子进程，不写入项目资产。
- 默认配置：除正文/改写外使用 DeepSeek 官方 API `deepseek-v4-flash`（思考低）；正文与改写使用硅基流动 `deepseek-ai/DeepSeek-V3.2`（不思考）。

## 6. 核心流程

### 6.1 初始化流程

```text
新建项目
→ 小说资料判别（小说简介判别）
→ 小说简介
→ 世界观
→ 语言风格
→ 角色名单
→ 批量角色卡
→ 批量关系卡
→ 剧情书
→ 剧情卷
→ 信息账本
→ 完成初始化
```

### 6.2 章节流程

```text
新建章节
→ 本章信息判别
→ 强制设定锚点
→ 配置
→ 台词
→ 最终提示词快照
→ 正文
→ 校验与验收
```

### 6.3 全局资产更新

顶部“可更新”区域将模块名映射到工作流任务：

| 模块 | 任务 |
| --- | --- |
| 小说简介 | `compile_intro` |
| 世界观 | `generate_worldview_json` |
| 语言风格 | `compile_style` |
| 角色名单 | `compile_character_roster` |
| 角色卡 | `generate_characters_batch` |
| 关系卡 | `generate_relations_batch` |
| 信息账本 | `compile_ledger` |
| 剧情书 | `compile_plot` |

角色卡/关系卡批量脚本会把用户补充透传到每张卡；关系卡在角色名单缺少 relations 时读取已有关系卡 JSON 作为更新来源。

### 6.4 自动模式

- 模式选择为“自动”时，初始化/章节步骤成功后会自动进入下一步。
- 自动推进通过 `maybeAutoContinue` 实现：初始化继续执行下一个未完成步骤，章节继续执行下一个未完成阶段。
- 遇到已有文件需要确认、缺少用户输入或最后一个步骤完成时自动暂停。

### 6.5 三种模式

- **标准模式**：直接发送自然语言，产物生成后由用户选择撤回/重试/下一步。
- **自动模式**：产物生成成功后自动进入下一步；遇到需要确认或缺少输入时暂停。
- **手动模式**：当前仅部分文件支持右侧“结构化编辑”，尚未作为完整模式覆盖全部步骤。

### 6.6 失败与用量

- 失败不覆盖正式产物。
- 失败卡片展示模型、输入/输出 token、耗时。
- 校验类错误显示“校验未通过”。
- 项目用量持久化在 `workflow-state.json`，历史用量从 `执行记录/*.jsonl` 回填。

## 7. 测试

| 脚本 | 说明 |
| --- | --- |
| `工作流脚本/验证完整流程.py` | 无模型完整流程集成验证，自动创建临时项目后删除 |
| `工作流脚本/验证工作台验收.py` | 端到端验收：项目创建/上传/切换/删除、初始化、章节流程、前端契约 |
| `工作流脚本/验证工作台验收.py --live-model` | 真实调用已配置 API 的完整验收 |

运行前需先启动服务：

```bash
cd web
node server.mjs
```

## 8. 文档索引

| 文档 | 内容 |
| --- | --- |
| `README.md` | 项目入口、快速开始、默认模型配置 |
| `docs/产品需求文档.md` | 产品定位、流程、功能范围、交互与验收 |
| `docs/技术文档.md` | 本文档：架构、目录、文件职责、接口、存储、流程 |