世界目录、安装与更新

这一页说明怎样从 GitHub 安装别人做的世界、怎样更新它，以及更新时哪些数据不会被动到。玩家和世界作者看前半部分和最后一节；做工具集成的人看 API 一节。

想自己做一个世界，看第一个世界。想把世界和它需要的插件一起发布，看合集。

官方目录是 covel-worlds。

• 首页默认是英文，另有中文的 README，也可以再加其他语言。
• 官方世界排在前面，社区世界单独收录。
• 作者通过 PR 提交一条结构化的目录条目。世界的内容可以放在作者自己的仓库里。
• 主仓库内置的世界仍然随 Covel 一起发布，不通过这里更新。

WARNING

被目录收录不等于通过了安全审核。第三方世界里的提示词、设置和媒体，仍然需要你自己看过再用。

设置页流程

1. 打开 设置 → 安装与管理。
2. 输入一个公开的 GitHub 仓库链接，或者 /tree/<ref>/<path> 形式的链接。
3. 安装器在这个位置找世界：根目录有 world.yaml 就是一个世界；否则列出下一级目录里的世界（包括 worlds/ 下的），最多 20 个。
4. 勾选要装的世界，确认。它们分别安装。

安装成功后世界立刻可用，不需要重启。

规则：

• 一次装多个世界时，它们的 ID 必须各不相同。
• world.yaml 没有写 id 时，世界的 ID 是它所在文件夹的名字；ZIP 安装时是 ZIP 文件名去掉 .zip。这个名字不能当 ID（例如有空格或大写字母）时安装被拒绝，请在 world.yaml 里写上 id。
• 普通安装不会覆盖已有的东西：ID 和现有的文件夹或数据库里的世界冲突时，安装被拒绝。
• 只安装你选中的世界文件夹。不执行任何脚本，也不替你授权任何插件。
• 同一个链接下的插件会和世界一起列出来，可以在一次确认里装好。安装器不会替你勾选插件，也不会去别的地方找世界需要的插件。例外是仓库用合集清单列出了它们。
• 世界作者应该在 pluginPolicy 里写明需要的插件。玩家在开局之前检查内容、需要的插件和它们的权限。

下载与安全限制和插件安装相同，详见插件安装：

• 查找版本和下载压缩包都走已经配置的代理。
• 链接有同样的限制，下载的内容按固定的 commit 校验。
• 预览有签名，15 分钟内有效。
• 压缩包有大小上限。这个上限针对整个 GitHub 归档，不只是你选的那个文件夹。

预览时做的检查：在一个临时目录里验证世界的清单、外部的维度文件和世界数据的引用。这一步不使用本机的世界 override，所以检查的是包本身。

从 SillyTavern 内容导入

在 设置 → 安装与管理 的 导入 SillyTavern 内容 中选择角色卡或世界书，预览报告后导入为一个世界。这里只做数据转换，不执行脚本；世界立即可用。转换、略过内容和示例见导入指南。不支持导入浏览器私有 BrowserVault。

API

这些接口受“是否允许安装”的开关控制。写入世界还要遵守全局的世界写入权限。

方法	路径	行为
POST	/api/install/st-import	multipart file（可重复）、locale?、name?、preview? → {ok,preview,kind:"world",id,restartRequired:false,report}；契约
POST	/api/install/world/github/preview	{url} → {items}
POST	/api/install/world/github	{token, acceptRisk:true} → 201 {ok:true,kind:"world",id,restartRequired:false}
GET	/api/install/worlds	{items:[{id,version,source,pendingUpdate}]}
POST	/api/install/world/github/update/preview	{id,url?} → current、pinned 或 available + preview
POST	/api/install/world/github/update	{token,acceptRisk:true} → 201 {ok:true,kind:"world",id,restartRequired:true}
DELETE	/api/install/world/github/update/:id	取消暂存更新，返回 {ok:true}

• 预览的形状和插件包的预览相同：id、version、description、author、source、token、expiresAt。author 是清单里的作者名，没有声明时是 null。
• description 是 I18nText，包含加载器合并的 world.<locale>.yaml 摘要翻译，由客户端按界面语言调用 resolveI18nText。
• hasServerCode 固定是 false。它的意思是“这条安装路径不会加载代码”，不是“这个文件夹里没有脚本文件”。
• 安装和更新的签名按“插件还是世界”和“安装还是更新”区分，不能拿一种去冒充另一种。
• ZIP 安装的接口 /api/install/world 仍然可用。
• 从 GitHub 安装时，安装器会在世界文件夹里写一个来源记录 .covel-install.json，之后的更新靠它。ZIP 和手动安装不生成这个记录，也不能自动检查更新。
• .covel-install.json 只由安装器写入。世界包自带这个文件时返回 400，文件名的大小写变体也一样。ZIP、GitHub 和合集成员共用这条规则。

ZIP 安装的校验。 创建世界记录之前，先检查世界数据有没有 error：

• 缺少 descriptor 或 source、source 无法解析、数据不符合它自带的 schema，都返回 400。这次新建的文件夹会被清掉，修好之后可以用同一个 ID 重试。
• warning 不阻止安装。
• 校验不使用本机的 override，也不执行包里的脚本或社区插件的代码。

合集失败时，已激活世界的回滚也使用这里的删除生命周期；已有会话的世界会保留。返回的撤回清单见批量安装契约。

更新与数据保护

检查更新：

• 装的是默认分支或某个指定分支时，可以手动检查更新。
• 装的是某个 tag 或 commit 时，版本是固定的，不会有更新。
• 想换版本，可以填同一个仓库、同一个目录的另一个版本链接。
• 只比较你装的那个世界文件夹。界面显示版本、commit，以及新增、修改和删除的文件。更新需要再确认一次风险。

更新什么时候生效：

1. 确认之后，新文件先下载到用户世界目录的 .covel-updates/<id>/ 里暂存。
2. 下次后端重启时替换，时机在加载世界和开始监听文件之前。
3. 启动时再核对一次来源和全部文件的摘要。核对失败时保留旧文件，并记下错误状态。
4. 替换文件的过程失败时，恢复旧的文件夹。

删除一个世界，也会取消它暂存的更新。

启动时，在应用更新和加载世界之前，清理用户世界目录及其 .covel-updates/ 下未完成的 .covel-install-* 暂存目录。已排队的更新和事务备份保留，继续走更新恢复流程。

删除世界时先把整个包移到 .covel-world-delete-*，再删除数据库记录。进程在这两步之间中断，下次启动会把包放回用户世界目录下以世界 ID 命名的文件夹，保留“删除中”状态，让玩家立即重试删除。记录已删除时，只清理剩余文件，不重建世界。恢复目标被占用、身份不明或数据库不可用时保留暂存文件并记日志，不覆盖其他包。

记录删除成功后，暂存目录先改名为 .covel-uninstall-*，再递归清理。清理失败不影响删除结果，下次启动继续清理；残缺的包不会被加载。

哪些情况会阻止更新：

• 你在本地增加、删除或修改过这个世界的文件。
• 你在 Covel 里改过这个世界。这时世界记录被标为 packageModified：之后的更新不再覆盖它，启动加载和文件监听也不覆盖它。这个改过的版本可以继续使用。

包文件在磁盘上变了、世界记录还保留旧内容时，世界列表显示“有更新可用”。内置世界随应用升级后的变化也会显示。想应用磁盘上的包，在世界详情页点“恢复为包里的版本”。世界数据和设置会被包里的内容替换，已保存的会话保留。这与设置页检查 GitHub 上的新版本是两件事。规则见世界记录和世界包。

CAUTION

删除世界会影响用它开的会话。不要把“删掉重装”当成不丢数据的更新方法。

更新不会动的东西：

• 更新世界不会删除或重写已有的会话，也不会自动同步世界数据。
• 存档里玩家或插件改过的数据，由世界数据同步单独处理：先试算，再检查冲突。
• 世界包之外的 override 不受文件替换的影响。但它们可能改变新包实际生效的内容。
• 回滚文件只是把文件换回去，不负责回滚玩法，也不迁移数据。

应用内校验

没有源码或 pnpm 的玩家可以在 设置 → 安装与管理 点击已安装包的“校验”，也可以选择插件或世界类型后拖入 ZIP。ZIP 校验不会安装包。API 还接受允许目录内的路径；界面暂不提供目录选择器。

未写 id 的世界 ZIP 按包的单层文件夹命名；文件平铺时用 ZIP 文件名去掉 .zip。已安装世界的清单无法解析或文件缺失时，仍可按设置列表中的目录 ID 校验，返回 manifest-invalid；同一 ID 有多个候选目录时拒绝校验，路径包含关系和符号链接检查保持不变。

上传包无法确定有效 ID 时，报告省略 id，返回 identity-invalid 错误和 ok: false，不会采用临时目录名。清单解析错误仍由静态校验器单独报告。

校验只读清单和引用的文件，检查字段、文件、语言和静态声明，绝不导入或执行包内代码，也不修改世界或存档。它复用 CLI 的校验核心；插件 CLI 遇到第一个问题就停止显示，应用会继续收集可以独立检查的问题。

报告包含 kind、可用时的 id、ok、counts.errors、counts.warnings 和 issues。每个问题有 severity、code、message，以及可用时的包内相对路径 file、字段路径或 JSON pointer field、修复提示 hint。摘要可含版本和语言。消息最多 2000 字符；保留前 200 个问题，超限时另加 issues-truncated 警告及省略数量。界面标题和已知代码按界面语言显示，其余消息保留英文；可以复制纯文本报告。

权限与安装相同，使用 host.files：托管实例需要运营者 Bearer 令牌；个人实例沿用安装接口的桌面令牌或显式启用规则。路径必须是对应插件或世界允许根目录内的真实目录，拒绝目录根的符号链接。报告把包内路径转为相对路径，把其他主机路径替换为 <path>，不返回 CLI 专用的原始文本。请求格式见 API。

世界校验使用正在运行的服务端已安装插件作为契约目录，因此缺少插件或契约的警告可能与默认只扫描内置插件的 CLI 不同。世界校验不需要 world.write。