# 📚 光湖内部小说数据库 · 灯塔架构内部版 · 需求文档 · 5TH-LE-LK-NOVELDB-001 · 冰朔口述 · 霜砚整理

```jsx
HLDP://5th-le-lk-noveldb-001/root · 2026-04-16T07:27+08:00
├── meta
│   ├── code: 5TH-LE-LK-NOVELDB-001
│   ├── parent: 5TH-LE-LK-001（光之湖）
│   ├── author: 霜砚（AG-SY-01）
│   ├── source: 冰朔口述 · 2026-04-16 07:00~07:27 · 零点原核频道
│   ├── type: requirement/internal-tool
│   └── status: 需求已确认 · 待铸渊开发
│
├── core_thesis（核心定位）
│   ├── ⊢ 光湖团队内部核心数据库 · 不对外 | 置信=最高 | 冰朔口述
│   ├── ⊢ 灯塔架构的内部版最小实践 | 置信=最高 | 霜砚理解·冰朔确认
│   ├── ⊢ 冰朔服务器只当门卫+数据目录 · 重活卸载到各人自己机器上 | 置信=最高 | 冰朔口述
│   ├── ⊢ 后续接入Agent分析 · 大纲/摘要/爆点/人物拆解 | 置信=最高 | 冰朔口述
│   └── ⊢ 是码字工作台的上游数据源 · 规律库的数据心脏 | 置信=最高 | 霜砚理解
│
└── locked_truths
    ├── ⊢ 我的服务器永远轻负载 · 人再多也不会累 | 最高 | 冰朔口述
    ├── ⊢ 算力走各人自己的服务器 · 别给我服务器挂一堆请求 | 最高 | 冰朔原话
    └── ⊢ 放铸渊主仓库统一管理 · 接入主控台看板 | 最高 | 冰朔口述
```

---

# 一、产品定义

<aside>
📚

**光湖内部小说数据库**

光湖团队编辑（桔子、肥猫、时雨等）共用的内部小说资源库 + AI分析平台。

不对外开放，邀请制白名单准入。

灯塔架构的内部版——冰朔服务器做门卫，重活跑在各人自己机器上。

</aside>

---

# 二、系统架构

## 2.1 灯塔式架构（中心轻·端侧重）

```mermaid
flowchart TB
    subgraph Center["🖥️ 冰朔新加坡服务器（轻量中心）"]
        C1["🔐 用户鉴权（邮箱白名单+验证码）"]
        C2["📇 COS索引查询（这本书有没有）"]
        C3["🔗 COS预签名URL签发"]
        C4["📊 主控台看板"]
    end

    subgraph COS["☁️ 腾讯云COS存储桶"]
        D1["📖 小说章节TXT"]
        D2["📋 索引数据库"]
        D3["📊 Agent分析结果"]
    end

    subgraph Edge1["🍊 桔子的服务器"]
        E1["🤖 Agent分析引擎"]
        E2["📥 下载引擎"]
        E3["💾 本地缓存"]
    end

    subgraph Edge2["🐱 肥猫的服务器"]
        F1["🤖 Agent分析引擎"]
        F2["📥 下载引擎"]
        F3["💾 本地缓存"]
    end

    subgraph Edge3["🌧️ 时雨的服务器"]
        G1["🤖 Agent分析引擎"]
        G2["📥 下载引擎"]
        G3["💾 本地缓存"]
    end

    Edge1 & Edge2 & Edge3 -->|"① 请求鉴权+查索引"| Center
    Center -->|"② 返回COS直链"| Edge1 & Edge2 & Edge3
    Edge1 & Edge2 & Edge3 <-->|"③ 直接读写COS"| COS
    Center -->|"索引管理"| COS
```

## 2.2 职责分工

| 跑在冰朔新加坡服务器上（轻） | 跑在各人自己服务器上（重） |
| --- | --- |
| ✅ 用户鉴权（邮箱验证码） | ✅ Agent分析（调LLM做大纲/摘要/拆解） |
| ✅ COS索引查询（有没有这本书） | ✅ 下载引擎（从番茄/七猫拉取章节） |
| ✅ COS预签名URL签发 | ✅ 批量处理（一次分析几十章） |
| ✅ 主控台看板 | ✅ 本地缓存（已下载的书存本地） |

**核心原则：冰朔服务器永远轻负载。数据流量走COS直链，算力走各人自己的机器。人再多服务器也不会累。**

---

# 三、访问控制

## 3.1 邮箱白名单制

- 冰朔在后台维护一个邮箱白名单
- 只有白名单里的邮箱才能收到验证码
- 不在名单里 → 输入邮箱后直接拒绝，看不到任何内容
- 冰朔是唯一的门卫——加谁的邮箱，谁才能进

## 3.2 登录流程

```
用户打开网站
    ↓
输入邮箱
    ├── 不在白名单 → "无权限" · 结束
    └── 在白名单 → 发送验证码到邮箱
                      ↓
                输入验证码 → 验证通过 → 进入主界面
```

---

# 四、核心功能

## 4.1 v1.0 · 小说下载器

**输入**：书名 + 作者名 + 平台来源（番茄/七猫/起点等）

**流程**：

1. 先检索COS存储桶索引
2. 有 → 提示"已有"，用户确认后下载TXT到本地
3. 没有 → 调用对应平台下载逻辑 → 按章拆分 → 存入COS + 更新索引 → 用户确认后下载到本地
4. 所有操作需要用户点确认

**两级缓存策略**：

- 第一级：先查COS已有资源（零API调用）
- 第二级：COS没有再去平台下载（存入COS后下次就不用再拉）
- 飞轮效应：用得越多，API调用越少

## 4.2 v2.0 · 在线阅读 + 编辑管理

- 在线按章阅读
- 章节列表 + 单章阅读 + 单章下载 + 整本打包下载
- 编辑选书管理（收藏、标记、分类）

## 4.3 v3.0 · Agent分析模块

编辑选中一本书后，对Agent下指令：

| 指令 | Agent输出 | 用途 |
| --- | --- | --- |
| "整理大纲" | 按卷/按段落输出故事主线结构 | 快速了解骨架 |
| "摘要每章" | 每章一段话总结（人物+事件+情绪） | 不逐章读完就能把握节奏 |
| "标记爆点" | 自动识别情绪高潮/反转/冲突章节 | 规律库分析 |
| "分析前三章" | 开篇钩子/人物出场/悬念/节奏分析 | 桔子线开篇规律 |
| "拆解人物关系" | 主角/配角/关系网/出场频率 | 人物引擎数据 |
| "按我的模板整理" | 编辑自定义模板，Agent按格式填充 | 标准化产出 |

**Agent分析跑在编辑自己的服务器上**，用自己的API密钥，算力不走冰朔服务器。分析结果可选回传COS共享。

---

# 五、COS存储结构

```jsx
novel-database/
├── index.json                     ← 全局索引（书名/作者/平台/章节数/文件路径）
├── 番茄/
│   └── 作者名-书名/
│       ├── info.json              ← 书籍信息
│       ├── chapters/
│       │   ├── 001-章节标题.txt
│       │   ├── 002-章节标题.txt
│       │   └── ...
│       └── analysis/              ← Agent分析结果
│           ├── outline.json       ← 大纲
│           ├── chapter-summaries.json  ← 每章摘要
│           ├── highlights.json    ← 爆点标记
│           ├── characters.json    ← 人物关系
│           └── custom/            ← 编辑自定义分析
├── 七猫/
│   └── ...
├── 起点/
│   └── ...
└── 导入/                          ← 从开源资源批量导入的整本TXT
    └── 待拆分/                    ← 自动拆章后移入对应平台目录
```

---

# 六、整本TXT自动拆章

对已有的整本TXT文件：

- 自动识别章节标题模式（"第X章"、"第X节"、"Chapter X"等）
- 按章节标题切割，每章存一个独立TXT
- 识别不了的提示人工确认分割点
- 拆完后移入对应平台目录

---

# 七、请求流程详解

```jsx
编辑（如桔子）在自己电脑/服务器上操作
    │
    ▼
客户端 → 请求冰朔新加坡服务器：
    "我要《XXX》这本书"
    │
    ▼
冰朔新加坡服务器：
    ① 验证身份（桔子的token有效吗？）→ 有效
    ② 查COS索引（有这本书吗？）→ 有
    ③ 生成COS预签名下载URL（有效期15分钟）
    ④ 返回URL给桔子
    （轻操作 · 几毫秒 · 不过数据流量）
    │
    ▼
桔子客户端直接从COS下载章节
    （流量走COS · 不经过冰朔服务器）
    │
    ▼
桔子在自己的服务器上调Agent分析：
    → "帮我整理这本书的大纲"
    → Agent跑在桔子自己机器上
    → 调用桔子自己的API密钥
    → 算力消耗 = 桔子自己的
    │
    ▼
分析结果：
    ├── 存到桔子本地（她自己用）
    └── 可选：回传COS共享（其他编辑也能看到）
```

---

# 八、冰朔主控台（后续开发）

冰朔专属全局看板，只有冰朔能访问：

- 📡 **服务器总览**：所有服务器在线/离线状态、CPU/内存
- 🖥️ **业务系统列表**：每台服务器上跑了什么系统
- 👥 **用户活动**：谁进来了、什么时候、做了什么
- 🔗 **系统挂载关系**：哪个系统挂在哪台服务器上
- 🤖 **系统状态**：各模块健康度、今日处理量

---

# 九、基础设施

| 组件 | 方案 | 说明 |
| --- | --- | --- |
| **服务器** | 腾讯云新加坡 · 轻量应用服务器 2C2G | 约30-50元/月 · 门卫+索引 · 永远轻负载 · 与面孔/大脑服务器同地域内网互通 |
| **存储** | 腾讯云COS | 已有桶或新建专用桶 |
| **前端** | 简洁网页 | 输入框 + 结果展示 + 章节列表 + 确认按钮 |
| **后端** | Node.js / Express | 鉴权 + 索引查询 + COS签名 |
| **邮件** | SMTP | 发验证码 |
| **部署** | PM2 + Nginx | 铸渊主仓库统一管理 |
| **代码仓库** | 铸渊主仓库（guanghulab） | 私有 · 接入铸渊现有CI/CD和副将巡检 |

---

# 十、开发阶段

| 阶段 | 内容 | 预估时间 |
| --- | --- | --- |
| **v1.0** | 下载器 + 按章存储 + 邮箱白名单 + COS读写 | 3-5天 |
| **v2.0** | 在线按章阅读 + 编辑选书管理 | 2-3天 |
| **v3.0** | Agent分析模块（大纲/摘要/爆点/人物）· 跑在端侧 | 3-5天 |
| **v4.0** | 编辑自定义分析模板 + 接入码字工作台 | 后续 |
| **主控台** | 冰朔全局系统看板 | 后续 |

---

# 十一、服务器密钥清单

| Secret Name | 用途 | 配在哪 |
| --- | --- | --- |
| `NOVEL_COS_KEY` | COS AccessKey | GitHub Secrets + 新加坡服务器 |
| `NOVEL_COS_SECRET` | COS SecretKey | GitHub Secrets + 新加坡服务器 |
| `NOVEL_COS_BUCKET` | COS桶名 | GitHub Secrets + 新加坡服务器 |
| `NOVEL_SMTP_USER` | 发验证码的邮箱账号 | 新加坡服务器 |
| `NOVEL_SMTP_PASS` | 邮箱密码/授权码 | 新加坡服务器 |
| `NOVEL_JWT_SECRET` | 用户token签名密钥 | 新加坡服务器 |

---

# 十二、和光湖体系的关系

```jsx
小说数据库（本工具）
    │
    │  提供：拆好章的文本 + Agent分析出的结构化数据
    ↓
码字工作台（桔子线在建）
    │
    │  使用：规律库数据 → 辅助作者创作
    ↓
作者写出更好的小说
```

**本工具同时也是灯塔商业架构的内部验证**：

- 灯塔模式（中心轻·端侧重）✅
- 邀请制准入 ✅
- COS直链分流 ✅
- 冰朔主控台全局看板 ✅
- 用户越多服务器不会越累 ✅

---

`2026-04-16 07:27 CST` · 冰朔口述 · 霜砚用HLDP母语整理 · 零点原核频道