# Import World From Book

> Import World From Book

- Skill: `talesofai/import-world-from-book` (Agent Skill, multi-file: 30 files)
- Install (CLI): `npx skillmds@latest add talesofai/import-world-from-book`
- Raw SKILL.md: https://api.skillmd.com/api/skills/talesofai/import-world-from-book/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: talesofai (https://skillmd.com/u/talesofai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/talesofai/import-world-from-book

---


# 从书籍构建虚拟世界技能

## 核心产出物
| 文件/目录 | 说明 |
|----------|------|
| `WORLD.md` | 世界总览：名称、类型、核心基调、核心设定 |
| `glossary.md` | ✅ 【最高优先级】术语表：记录同一个实体的所有指代方式（别名、简称、昵称、不同称呼、不同语言译名等），所有其他文件必须严格使用本表中的主名称，禁止混用别名 |
| `timeline.md` | 全局极简时间线索引（详细时间线在`story/timeline/`下） |
| `characters/` | 所有角色的完整档案 |
| `locations/` | 所有地点/地理的完整档案 |
| `factions/` | 所有势力/组织/家族/门派/公司的完整档案 |
| `lore/` | 通用设定：规则/魔法/科技/文化/宗教/经济/种族/习俗 |
| `story/` | 完整故事内容：`volumes/`原文章节 + `timeline/`详细时间线 + `biographies/`角色传记 + `events/`事件始末 |
| `raw_text/` | 原文拆分后的所有章节块，**只读，永远不要修改** |
| `assets/` | 资源文件：地图/插画/音频/参考资料等 |

---

## 快速开始

```bash
# 1. 初始化世界文件夹（复制 .opencode/skills/import-world-from-book/template/）
cp -r .opencode/skills/import-world-from-book/template/ ./my-world

# ⚠️ 注意：不要删除 my-world 里的 template 框架文件（如 *_template.md 和 README.md）。现在的脚本会自动把它们作为提取规范。

# 2. 创建空白 glossary.md，WORLD.md 可先留空后续补充

# 3. 拆分书籍为 chunks
cd .opencode/skills/import-world-from-book/scripts
npm run split-book -- -i /path/to/book.epub -o /path/to/my-world/raw_text

# 4. 自动化深度提取世界内容
npm run extract-world -- -w /path/to/my-world
```

---

## 执行流程

### 步骤 1：初始化世界文件夹（仅执行 1 次）
1. 复制 `.opencode/skills/import-world-from-book/template/` 为你的世界根目录（比如 `./my-world`）
2. **保留模板结构**：不需要像旧版那样删除示例文件，现在的 `extract-world` 脚本会自动挂载这些带 `template` 的文件作为对大模型的严厉格式约束，并且会严格禁止大模型生成多余的模板文件。
3. 创建空白 `glossary.md`，`WORLD.md` 可先留空，等提取部分内容后再补充

---

### 步骤 2：拆分书籍为 Chunks
使用 `split-book` 工具将 epub/txt 拆分为适合处理的文本块。

**命令示例：**
```bash
npm run split-book -- -i /path/to/book.epub -o /path/to/my-world/raw_text
```

**常用参数：**
- `-i, --input <path>` - 输入书籍文件（epub/txt，必填）
- `-o, --output <path>` - 输出目录（必填，通常是世界文件夹下的 `raw_text/`）
- `--chunk-size <number>` - 单个 chunk 最大字符数（默认 50000）
- `--start <number>` - 起始章节编号（1-based，默认 1）

**查看完整帮助：**
```bash
npm run split-book -- -h
```

✅ `raw_text/` 中的文件是原始拆分结果，**只读，永远不要修改**

---

### 步骤 3：自动化深度提取世界内容
使用 `extract-world` 工具遍历 `raw_text/` 中的所有 chunk，逐个调用 opencode 进行深度提取。

**命令示例：**
```bash
# 处理所有 chunk（从第 1 个开始）
npm run extract-world -- -w /path/to/my-world

# 从第 5 个 chunk 开始处理
npm run extract-world -- -w /path/to/my-world --start 5

# 只处理第 10-20 个 chunk
npm run extract-world -- -w /path/to/my-world --start 10 --end 20

# 预览要处理的 chunk（不实际执行）
npm run extract-world -- -w /path/to/my-world --dry-run

# 指定 agent 和 model
npm run extract-world -- -w /path/to/my-world --agent my-agent --model provider/model-name
```

**常用参数：**
- `-w, --world-dir <path>` - 世界文件夹路径（必填，包含 `raw_text/`）
- `--start <number>` - 起始 chunk 编号（1-based，默认 1）
- `--end <number>` - 结束 chunk 编号（inclusive，默认处理所有剩余）
- `--dry-run` - 预览模式，只显示要处理的 chunk 不实际执行
- `--agent <name>` - 使用指定的 agent
- `--model <model>` - 使用指定的 model（格式：provider/model-name）

**查看完整帮助：**
```bash
npm run extract-world -- -h
```

**⚠️ 重要说明：**
- 脚本会严格按照 chunk 顺序逐个串行处理，一次只处理一个分块
- 每个 chunk 处理完成后会自动等待 2 秒再处理下一个
- 如遇单个 chunk 处理失败，脚本会记录错误并继续处理下一个 chunk
- 脚本会自动从 `.opencode/skills/import-world-from-book/template` 中加载各种防呆模板去约束大模型，彻底防止死链、丢失格式、丢失中文命名等问题。

---

### 步骤 4：收尾整合（全本处理完成后执行）
1. **补全档案总结**：为角色、地点、势力档案添加总结性描述，梳理人物弧光、事件影响等
2. **清理无用文件**：如果大模型还是意外生成了一些残余文件（如 `template_file_leak.md`），可以通过一条指令删除。
3. **解决冲突点**：统一所有标记的`⚠️ 待确认`矛盾信息
4. **全局校验**：由于我们在 V4 中强制加入了【绝对路径链接】原则，你需要检查所有带有 `/characters/...` 形式的链接是否均可点击。
5. **建立关联网络**：所有文件中提到其他实体时添加内部链接，方便检索
6. **整理资源**：整理地图、插画等资源到`assets/`，删除临时文件

---

## 🛠️ 工具参考

工具位置：`.opencode/skills/import-world-from-book/scripts/`

### 1. `split-book` - 拆分书籍为 Chunks
- 功能：将 epub/txt 拆分为适合处理的独立文本块
- 拆分优先级：章节标记→段落→句子结尾，不会丢失任何内容
- 使用方法：`npm run split-book -- -h` 查看完整参数

### 2. `extract-world` - 自动化深度提取世界内容
- 功能：遍历 `raw_text/` 中的所有 chunk，使用 opencode 逐个进行深度提取
- 基于 opencode run 命令实现，参考文档：https://opencode.ai/docs/cli/#run-1
- 使用方法：`npm run extract-world -- -h` 查看完整参数