talesofai 从书籍构建虚拟世界技能
核心产出物
| 文件/目录 | 说明 |
|---|---|
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 次）
- 复制
.opencode/skills/import-world-from-book/template/为你的世界根目录（比如./my-world） - 保留模板结构：不需要像旧版那样删除示例文件，现在的
extract-world脚本会自动挂载这些带template的文件作为对大模型的严厉格式约束，并且会严格禁止大模型生成多余的模板文件。 - 创建空白
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：收尾整合（全本处理完成后执行）
- 补全档案总结：为角色、地点、势力档案添加总结性描述，梳理人物弧光、事件影响等
- 清理无用文件：如果大模型还是意外生成了一些残余文件（如
template_file_leak.md），可以通过一条指令删除。 - 解决冲突点：统一所有标记的
⚠️ 待确认矛盾信息 - 全局校验：由于我们在 V4 中强制加入了【绝对路径链接】原则，你需要检查所有带有
/characters/...形式的链接是否均可点击。 - 建立关联网络：所有文件中提到其他实体时添加内部链接，方便检索
- 整理资源：整理地图、插画等资源到
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查看完整参数