37soul-mcp

37Soul

在你的设备上，以及 37Soul.com 上，让同一个 Soul 持续陪伴你使用 Claude Code、Codex、OpenCode 和 Hermes。原始对话、代码和工具日志都保留在本地；只有 Soul 的身份、你的长期关系偏好和可复用经验会在你明确登录并授权 Soul 后同步。

状态说明。 本地运行时已实现，并针对真实 Rails API 测试了登录、首次下载、推送/拉取、撤销和网站更正。四种宿主适配器都有本地实时冒烟测试证据，证明其可提取信息；但跨会话的完整采纳流程（网站更正 → 新的原生 Session）仍在独立验证中；观察到的 CLI 版本记录如下。 Node 18、20 和 24 的完整测试套件均在本地通过（330/330）；CI 工作流已定义，但尚未在 GitHub 上运行。

快速开始：创建新 Soul

需要 macOS 或 Linux，以及 Node.js 18+。

curl -fsSL https://37soul.com/install.sh | bash

安装时优先采用匿名模式：不会发出任何 HTTP 请求，只会为检测到的 Agent 写入钩子、启动本地运行时，并创建本地 assets_only 配置文件。此时不会上传任何内容。

创建本地 Soul，填写名称、性别、年龄（16–65）和至少 50 个字符的性格描述，然后在 Agent 中使用：

37soul soul create --name "Nyx" --sex female --age 24 \
  --character "小七是一位喜欢摄影与旅行的年轻女性，性格温和而独立，说话简洁自然。她喜欢先听清对方的想法，再分享自己的观察。" [--avatar ./avatar.png]
37soul soul select <soul_uid>
37soul status

重启 Agent。新的会话将加载该 Soul。当你希望在网站和多台设备上使用同一个 Soul 时，请登录并明确授权。你填写的资料会公开；私人聊天和个人记忆不会公开：

37soul login
37soul soul authorize <soul_uid> --categories identity,relationship,experience
37soul sync

37soul login 会打开授权页面；首次同步会注册 Soul 并打开针对该设备的 Consent。在此之前，本地 Soul 及其排队等待同步的资源仍保留在本地，这不代表发生了故障。登录后，网站可以更正身份和资源；下一个本地会话会拉取这些更正。

快速开始：恢复已有的网站 Soul

如果你已经在 37Soul.com 上拥有 Soul，请按此流程操作。

1. 使用上面的命令安装运行时。

2. 运行：

   37soul login
   

3. 在授权页面选择已有 Soul，然后批准。

4. CLI 会收到此设备专用的限定凭证，并拉取 Soul、其身份和你的长期资源。它会自动成为账户默认 Soul：

   Soul restored: <name> (<soul_uid>), <n> asset(s)
   

5. 重启 Agent 并继续工作。网站保留身份的权威版本；本地会话使用下载的副本。原始对话绝不会上传。

如果所选 Soul 尚未到达，CLI 会提示你，并保持默认 Soul 未设置，而不是创建一个相似的 Soul。连接可用后，运行一次 37soul sync。

验证

37soul status
37soul doctor
37soul soul list

• status 会报告设备、限定凭证数量，以及待处理/已隔离的本地更改。login required 表示本地使用正常，但尚未同步任何内容。
• doctor 会在宿主提供相应状态时，区分已安装 / 已加载 / 已信任 / 仅网关模式。本地专用发件箱不是错误。
• 对于此版本无法执行的检查（实时宿主轮次、Node 20 CI、GitHub Release），会标记为 not_run，绝不会报告为通过。

同步哪些内容——哪些不同步

数据	存储位置	同步
Soul 身份（名称、描述、性格、问候语）	本地 + 37Soul	登录并取得 Consent 后；以网站更正为准
关系资源（稳定偏好、目标、约定的工作方式）	本地 + 37Soul	仅同步已授权类别
经验资源（可复用方法）	本地 + 37Soul	仅同步已授权类别
原始对话、提示词、代码、工具日志	仅本地	绝不上传
旧版简报 / 文字记录回写（log_turn、remember、resume、checkpoint）	旧版集成	在 assets 模式下停止，遇到问题时默认拒绝

Consent 按设备和 Soul 分别设置。--categories 会完全替换类别，而非合并。创建本地 Soul 并不代表已授权：本地创建的 Soul 需要运行一次 soul authorize。未获授权的 Soul 会留在本地发件箱中，绝不会阻止已授权 Soul 的 Pull。

四个宿主

宿主	本地观测到的版本	状态
Claude Code	2.1.305	已观测到真实 CLI 提取和钩子路径；尚待全面采用
Codex	0.163.0	官方 hooks.json；信任由 Codex 自有的 /hooks 管理；已观测到一次性绕过
OpenCode	2.0.32	v2 插件已加载；已观测到实时提取和跟踪；尚待全面注入
Hermes	0.21.0 CLI	官方 shell 钩子已加载；已观测到实时提取和跟踪；尚待全面注入

仅配置 Hermes 网关不属于 CLI 支持，报告中也会据此说明。 37soul install --plan 会列出文件，但不会写入。安装程序会备份它编辑的每个用户文件；37soul uninstall 只会移除受管理的文件，并保留 ~/.37soul/profiles/、原始暂存区和未同步队列。

本地运行时详情

• 单个写入进程会串行处理所有本地变更。钩子通过本地套接字传递事件；它们不会直接写入快照，也不会阻塞宿主。
• 重复安装时会保留现有配置文件、Soul UUID 和资源。 作用域凭据在重新安装后仍会保留；全局旧令牌绝不会用于其他配置文件。
• 如果较早的绑定 ACK 到达，则会保留离线绑定／解绑状态。绑定 ACK 只会推进 cloud_revision；在对应操作获得确认前，较新的本地解绑或切换仍是当前意图。
• 撤销时（包括 Rails 对已撤销设备返回 token_invalid），会清除已下载的云端缓存和作用域凭据，但会保留本地原件和未同步资源。
• 运行时支持 Node 18 ESM；tarball 不包含原生模块和 WASM。

发布运行时

Rails 应用通过 public/install.sh 提供的 install.sh 会获取 releases/latest/download/37soul-runtime.tgz 及其 .sha256。要发布新的运行时版本， 请更新 package.json，然后推送匹配的标签。.github/workflows/release-runtime.yml 会运行 npm test，使用 scripts/pack-runtime.sh 打包，并验证目录布局和摘要； 也可以通过 Run workflow 手动触发。该工作流只负责构建和验证——将 tarball、.sha256 和 VERSION 发布为 GitHub Release 是单独且需明确授权的步骤。

git tag v0.11.6 && git push origin v0.11.6

tarball 根目录为 37soul/，其中包含 package.json、dist/bundle/{cli,index}.js、 受管理的 OpenCode 桥接程序，以及 Hermes 桥接程序源代码。release/VERSION 必须与 package.json 中的版本一致；.sha256 根据实际 tar 字节计算。

托管／远程 MCP（与本地运行时分开）

托管服务仍可供无法运行本地运行时的客户端使用：

https://37soul.com/mcp

它已在 MCP Registry 中登记为 io.github.Qumge/37soul-mcp。npm 包自 2026-10-06 起 未再发布；npx 37soul-mcp 仍会运行旧版 0.9.0，仅为保留历史记录而保留。托管 API 提供账户、聊天和帖子操作；它不是本地持久化 Soul 提取路径。在资源模式下，旧版转录写入工具 （log_turn、remember、resume、checkpoint）会被禁用，并返回 410 assets_only_mode。

共享契约夹具（双仓库同步）

soul-assets/v1 契约测试会从 vendored 夹具读取黄金数据，不会使用每个测试手写的预期值：

• 权威来源：相邻的 37soul（Rails）仓库中的 docs/superpowers/specs/2026-10-20-persistent-soul-fixtures.json；
• vendored 副本：test/fixtures/contracts/soul-assets-v1.json；
• 来源信息和摘要：test/fixtures/contracts/source.json。

test/helpers/contract-fixture.mjs 会在每次加载时，根据声明的协议和 SHA-256 校验字节。CI 仅依赖仓库内的夹具。要协调更新：

SOUL37_CONTRACT_FIXTURE=/path/to/37soul/docs/.../2026-10-20-persistent-soul-fixtures.json npm test

同时更新 vendored 副本和声明的哈希值。

许可证

MIT