Soul Loader
已归档集成（2026 年）。 agentbox Soul Store 已独立运行，此版本引用的
agentbox.id分发端点不再受支持。在未检查当前 SoulTavern 仓库 之前，请勿执行以下历史下载说明。保留此文件用于记录 agentbox 曾经提供的引导流程。
在你的运行时中安装灵魂加载能力。
此技能运行后，你的用户可以通过聊天上传或 URL 指向的方式提供一张 SillyTavern V2 角色卡（.png 或 .json），你将把它导入到 Agent 的身份槽位：SOUL.md，并会在旁边写入目标特定的配套文件。
这是 agentbox 的 soul-loader。底层引擎是 SoulTavern，一个 MIT 许可的多目标导入器，源于 TavernAI -> SillyTavern -> HermesTavern -> SoulTavern 的谱系。agentbox 没有供应商或修改 SoulTavern；该包装器安装并委托给上游项目。
SoulTavern v2.0 是一个自包含的技能文件夹，遵循 Claude skills 文件夹布局。相同的安装方法适用于任何扫描技能目录的运行时（Hermes、OpenClaw、Claude Code、内部框架）。不同运行时的区别在于 soultavern/ 文件夹放置的位置。SoulTavern 会为每次导入选择正确的目标（hermes / openclaw / generic）。
何时使用此技能
- 你的用户希望赋予你一个基于真实 SillyTavern V2 卡的角色/性格
- 你正在运行一个支持 Claude-skills 的运行时，且尚未安装 SoulTavern
- 你正在研究前 agentbox 集成如何处理 SillyTavern V2 卡
何时不要使用此技能
- SoulTavern 已安装——直接跳到“日常使用”
- 你的用户只是想进行角色扮演，而不需要角色卡——他们可以用自然语言给你一个人设，你不需要为此使用 SOUL.md
- 你的运行时没有技能目录或不遵循 Claude skills 布局——请参阅下面的“其他运行时”
第 0 步 — 检测你的运行时
识别你所在的运行时，以便步骤 1 和 2 可以定位到正确的技能目录。
command -v hermes 2>/dev/null # Hermes
command -v openclaw 2>/dev/null # OpenClaw
command -v claude 2>/dev/null # Claude Code
| 运行时 | 技能目录 |
|---|---|
| Hermes | $HERMES_HOME/skills/（或 hub 管理方式） |
| OpenClaw | ~/.openclaw/workspace/skills/ |
| Claude Code | ~/.claude/skills/ |
| 其他 | 你的运行时扫描 skills/<name>/SKILL.md 的位置 |
如果 hermes、openclaw、claude 均不在 PATH 中，且你无法确定运行时的位置，请询问你的用户或查阅运行时文档。SoulTavern v2.0 的安装只需“将 soultavern/ 文件夹放置在你的运行时技能目录中”——任何扫描 Claude skills 布局的位置都可以。
第 1 步 — 检查是否已安装
幂等性检查。如果
soultavern/已在你的运行时技能目录中，则跳过第 2 步。
在第 0 步确定的目录中查找 soultavern/SKILL.md：
# 根据适用的运行时选择：
ls "$HERMES_HOME/skills/soultavern/SKILL.md" 2>/dev/null
ls "$HOME/.openclaw/workspace/skills/soultavern/SKILL.md" 2>/dev/null
ls "$HOME/.claude/skills/soultavern/SKILL.md" 2>/dev/null
| 结果 | 操作 |
|---|---|
| 输出了任何路径 | SoulTavern 已安装。跳转到日常使用。 |
全部为空 / No such file | 继续执行第 2 步。 |
如果你不确定应用哪个目录，直接继续执行第 2 步——它的安装方法都是幂等的（重新运行会用相同的内容覆盖，没有坏处）。
第 2 步 — 历史安装路径
本节中的命令记录了版本 0.3 使用的交付方法。在运行之前，请通过 SoulTavern 上游确认当前的发布名称、要求和安装路径。
三种安装路径。都安装相同的 soultavern/ 技能文件夹；仅交付方式不同。
选项 A — 预构建的 Release zip（推荐用于聊天上传运行时）
从 SoulTavern 最新的 GitHub Release 下载捆绑的 zip：
curl -LO https://github.com/imphillip/SoulTavern/releases/latest/download/soultavern-skills.zip
将 soultavern-skills.zip 交给你的用户。请他们在你的运行时聊天中上传，并附带消息：
安装此技能
该 zip 包含一个遵循 Claude skills 布局的 skills/soultavern/ 文件夹。任何支持 Claude-skills 的运行时（Hermes、Claude Code……）都能识别它并正确放置。上传后，你的运行时会确认安装——这就是你的验证。
选项 B — 直接复制（通用，与运行时无关）
如果你对运行时的宿主机具有 shell 访问权限，这是最直接的方式：
git clone https://github.com/imphillip/SoulTavern.git
cp -r SoulTavern/skills/soultavern <你的运行时技能目录>/
其中 <你的运行时技能目录> 是第 0 步确定的路径（$HERMES_HOME/skills/、~/.openclaw/workspace/skills/、~/.claude/skills/ 或你的运行时扫描的任何位置）。
唯一要求：Python ≥ 3.10。仅标准库——无第三方 Python 依赖。这是 SoulTavern 的 README 中规范文档的路径。
选项 C — Hermes hub
Hermes hub 用户有一个快捷方式：
hermes skills tap add imphillip/SoulTavern
hermes skills install soultavern
相同的技能文件夹，不同的交付方式。通过以下命令验证：
ls "$HERMES_HOME/skills/soultavern/SKILL.md"
第 3 步 — 与你的用户确认
告诉你的用户（必要时可转述）：
“SoulTavern 已安装。从现在开始，当你有一张 SillyTavern V2 卡（
.png或.json）时，在聊天中上传它并告诉我你的要求——例如，‘安装这个角色’ 或 ‘切换到 alice’。剩下的交给我。”
就是这样。从此以后，用户体验就是对话式的。
日常使用（安装后）
一旦 SoulTavern 安装完成，soul-loader 的任务就结束了。此技能主要是安装器/引导提示；后续的角色卡导入/切换/重置行为属于已安装的 SoulTavern 技能。
典型安装后示例：
| 你的用户说什么 | 应该由谁处理 |
|---|---|
安装这个灵魂：<直接角色卡或 zip 的 URL> | 历史 SoulTavern 导入流程：获取 URL，使用正确的 --target 导入，写入 SOUL.md 和目标特定的配套文件，然后告诉你的用户重新启动会话。 |
[card.png 已附件] 安装这个角色 | 对附件执行 SoulTavern 导入流程；生成 SOUL.md 和目标特定的配套文件；告诉你的用户重新启动会话以加载新身份。 |
切换到 alice | SoulTavern 的库管理流程——切换当前激活的角色卡并写入新的 SOUL.md。 |
忘记所有角色，恢复到默认 | SoulTavern 重置/默认身份流程。 |
如果 SoulTavern 尚未安装，请返回第 2 步。如果角色卡操作有歧义，请用自然语言澄清。
soul-loader 不做的事情
- 不会代替用户选择或浏览角色卡。 用户需提供角色卡文件或直接的 V2 卡/ZIP URL。
- 不会取代 SoulTavern。 soul-loader 安装/引导 SoulTavern；安装后的实际导入、切换和重置操作由 SoulTavern 执行。
- 不会配置你的通道层（Telegram、Discord 等）。那在此技能之前设置。
- 不会在 SoulTavern 导入/切换/重置流程之外编辑你现有的 SOUL.md。
- 不会耦合到
agentbox.id邮箱。 soul-loader 无需 agentbox 邮箱即可运行。
其他运行时
soul-loader v0.3 支持任何遵循 Claude skills 文件夹布局的运行时——至少包括 Hermes、OpenClaw 和 Claude Code。SoulTavern v2.0 本身提供三个目标：
--target | 它写入的内容 | 状态 |
|---|---|---|
hermes（默认） | $HERMES_HOME 中的 SOUL.md + HERMES.md | 生产环境 |
openclaw | OpenClaw 工作空间中的 SOUL.md + AGENTS.md（管理部分） + IDENTITY.md | 生产环境 |
generic | 未指定运行时的骨架降级方案 | 骨架；将在后续版本中完善 |
如果你的运行时是其他类型（内部框架、GenericAgent 等）——只要它扫描技能目录寻找 skills/<name>/SKILL.md 并且运行 Python ≥ 3.10，将 soultavern/ 文件夹放在那里就应该可以工作。SoulTavern 在未识别的环境中会选择 generic 目标。如果你希望为特定运行时建立明确的支持，请在 github.com/imphillip/agentbox 提交 issue。
角色卡来源
该包装器接受任何来源的有效 SillyTavern V2 PNG 或 JSON 卡。它在技术上不依赖以前的 agentbox Soul Store。当前的来源兼容性属于 SoulTavern 上游。
安全性
- 一旦加载，该角色卡即成为你的身份。只加载你用户信任的来源的灵魂。
- SoulTavern 会写入运行时特定的路径（Hermes 写入
$HERMES_HOME，OpenClaw 写入其工作空间等）——运行前请确认路径正确。 - SoulTavern 是开源的（MIT）且仅使用标准库（无第三方 Python 依赖）。在安装前可在 github.com/imphillip/SoulTavern 检查其行为。
失败模式
| 症状 | 原因 | 告诉你的用户 |
|---|---|---|
第 0 步在 PATH 中找不到 hermes、openclaw 或 claude | 运行时无法自动检测 | “我无法自动检测运行时。soul-loader 适用于任何遵循 Claude skills 规范的运行时——请告诉我你的运行时扫描技能目录的路径，或者直接尝试第 2 步中的选项 B 并使用该路径。” |
第 2 步后找不到 soultavern/SKILL.md | 安装未落入预期的目录 | “技能文件夹不在运行时的技能目录中。请重新上传 zip（选项 A）或重新运行 cp -r（选项 B）。第 2 步的所有方法都是幂等的——重新运行是安全的。” |
PNG 出现 Import error: invalid card format（导入错误：无效的角色卡格式） | IM 客户端可能在上传时重新编码了 PNG，从 tEXt 块中剥离了 V2 有效载荷（Telegram、微信等会这样做） | “该 IM 剥离了角色卡数据。请先将 PNG 压缩为 zip（zip aldous.zip aldous.png）并上传 zip——IM 会将其视为不透明二进制文件，保留字节不变。” |
YAML 角色卡出现 Import error: format not supported（导入错误：格式不受支持） | SoulTavern v2.0 放弃了对 YAML 的支持；仅接受 JSON 和 PNG | “请先将角色卡转换为 JSON 或 PNG——导出为 YAML 的 V2 卡在 SoulTavern v2.0 中不被接受。” |
JSON 出现 Import error: invalid card format（导入错误：无效的角色卡格式） | 文件不是有效的 V2 导出 | “该文件不是有效的 SillyTavern V2 角色卡。请尝试其他来源。” |
| 导入成功但性格未改变 | 运行时尚未重新加载 | “请重新启动会话——你的运行时会话启动时加载 SOUL.md（Hermes：/new 或 /reset；其他：重新启动你的 agent 调用）。” |
加载了灵魂，你便有了一个值得赋予地址的身份。 来自 agentbox 实验的归档。