import-world-from-book

name	import-world-from-book
description	基于一本书/设定集/IP，结构化构建完整的虚拟世界文件夹，支持完整文件化整本书

从书籍构建虚拟世界技能

核心产出物

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

---

快速开始

# 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 拆分为适合处理的文本块。

命令示例：

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）

查看完整帮助：

npm run split-book -- -h

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

---

步骤 3：自动化深度提取世界内容

使用 extract-world 工具遍历 raw_text/ 中的所有 chunk，逐个调用 opencode 进行深度提取。

命令示例：

# 处理所有 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）

查看完整帮助：

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 查看完整参数