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