面向 Agent:本文件是可执行的部署/加入剧本。用户只负责两件事:说出要做什么、转交配对码。 每一步都给出命令与「期望输出 / 判定」。任何一步失败:先按 §6 处置,不要猜、不要跳过。
目标:在当前会话里直接拿到 Mebular 的跨设备记忆能力(MCP 工具面),且不改动任何既有 memory provider。 顺序:① 幂等检查 → ② 无 home 指回 §3/§5(不自建身份)→ ③ 有 home 未在跑则拉起 → ④ 接入当前客户端并验证 → ⑤ 红线。
0.1 幂等:先在跑就直接用(App / 常驻守护都算),不要重复安装/重启
先看守护发现文件 + 健康检查——这一步不依赖 command -v mebular:
HOME_DIR="${MEBULAR_HOME:-$HOME/.mebular}"
RUNNING=0
HOST=127.0.0.1
PORT=7331
RUNTIME_FILE="$HOME_DIR/runtime.json"
# runtime.json 形状:{ "version": "...", "pid": ..., "http": { "host": "...", "port": ... } }
if [ -f "$RUNTIME_FILE" ]; then
HTTP_BLOCK=$(sed -n '/"http"[[:space:]]*:/,/}/p' "$RUNTIME_FILE")
HOST=$(printf '%s\n' "$HTTP_BLOCK" | sed -n 's/.*"host"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
PORT=$(printf '%s\n' "$HTTP_BLOCK" | sed -n 's/.*"port"[[:space:]]*:[[:space:]]*\([0-9][0-9]*\).*/\1/p' | head -n 1)
HOST="${HOST:-127.0.0.1}"
PORT="${PORT:-7331}"
CURL_HOST="$HOST"
case "$HOST" in *:*) CURL_HOST="[$HOST]" ;; esac
if curl -fsS "http://$CURL_HOST:$PORT/healthz" >/dev/null; then
RUNNING=1
echo "Mebular 已在跑(http://$HOST:$PORT),直接用;跳过 §2 CLI 安装,进入 §0.4 接入"
fi
fi
# CLI 可用性分支:与上面的 RUNNING 在**同一 shell 块**内;RUNNING=1 时绝不进入 §2。
if [ "$RUNNING" -eq 0 ]; then
if command -v mebular >/dev/null 2>&1; then
# 幂等判定**只在 home 已存在时**执行 status(无 home 时它会在默认 home 自举身份材料,见 0.2)
if [ -f "$HOME_DIR/config.json" ]; then
MEBULAR_HOME="$HOME_DIR" mebular status # 判定见下(exit 0)
else
echo "无 home → §3 建新 / §5 加入" # 不要在这里跑 status
fi
else
echo "没有 runtime/healthz 且没有 CLI → 按 §2 安装 CLI"
fi
else
echo "RUNNING=1:已在跑,跳过 CLI 安装/拉起,直接进入 §0.4 接入"
fi判定「守护已在跑」:runtime.json 存在且 /healthz 返回 200(App 内置 runtime、常驻服务、前台 serve 都写同一文件)→
RUNNING=1,直接使用本机已有实例,不要重复 install 或再起 serve。已在跑时,command -v mebular 失败不是安装理由;
上面的 CLI 分支在 RUNNING=1 时不会执行,直接进入 §0.4 接入。
判定 status 输出里 storeLock 非 null(形如 {"pid":…,"startedAt":…,"storagePath":…})→
直接使用本机已有实例,不要重复 install 或再起 serve。
注意口径:
status.running是 P2P 节点状态(network.enabled=true才为 true),不是守护进程状态; 默认 home 下它常为false,属正常。判定守护进程请用storeLock(或 0.3 的service status//healthz)。 无config.json时不要自建身份:引导用户从 App 主界面「新建忆云 / 加入忆云」完成(§3/§5)。
0.2 无 home:不要在这里自建身份
mebular status 会在 home 不存在时自举身份材料(user-master-key.json、身份文件)。因此:
- 无
config.json→ 不要跑status;按 §3(建新)或 §5(加入)走,只有用户明确要建新/加入时才创建身份。 - 已有 home(
config.json在)→ 才继续 0.3/0.4。
0.3 有 home 但未在跑:拉起守护
优先常驻(按 packages/service 的平台矩阵:darwin = launchd 用户级 LaunchAgent;linux = systemd --user;win32 = 计划任务 onlogon):
MEBULAR_HOME=~/.mebular mebular service status # 只读:services[0].registered / running
MEBULAR_HOME=~/.mebular mebular service install # 常驻 + 自启(不想自启用 --no-autostart)
MEBULAR_HOME=~/.mebular mebular service status # 判定:services[0].registered === true 且 running === truehome 默认已统一:
mebular缺省用~/.mebular(MEBULAR_HOME可覆盖;bin/mebular.mjs与src/config.mjs共用同一真源src/home.mjs)。上面命令的MEBULAR_HOME=~/.mebular前缀是显式声明 (等价于缺省),跨环境脚本里保留更直观;service 会把该值写进单元的env.MEBULAR_HOME与workingDir。
若所在环境不支持常驻(无 launchd/systemd/计划任务的容器等),改前台拉起:
MEBULAR_HOME=~/.mebular mebular serve --port 7331 # 期望输出含 SERVE_READY {…}确认已拉起(任一即可,判据如下):
MEBULAR_HOME=~/.mebular mebular status # 判据:storeLock 非 null
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:7331/healthz # 判据:200实测(沙箱 home,
mebular serve --port 0):storeLock由null→{"pid":…,"startedAt":…},/healthz=200; 停止后storeLock回到null。service install会注册真实常驻服务,故本沙箱未执行,依据 =mebular service用法 +packages/service/src/units.ts平台矩阵 +service status实跑输出。
0.4 接入当前客户端(MCP 片段)
mebular print-config --client <opencode|claude|cursor|dsh|generic> # 远程形态:追加 --url https://<host>/mcp- 把输出片段合入当前客户端的 MCP 配置(先备份原文件);
dsh形态为客户端桥接(只桥接 Tools)。 - 重载客户端(重启该客户端/会话)后生效。
- 验证:在本会话调用
memory_status—— 期望返回deviceId/running(P2P 节点)/ 计数等字段。 注意:storeLock不在memory_status的返回里(那是 CLImebular status追加的字段,见 0.1/0.3)。 若「没有 mebular 工具」:片段未生效或未重载客户端,回到第 1–2 步。
实测:
MEBULAR_HOME=<沙箱> node packages/mcp/bin/mebular.mjs mcp上tools/call memory_status返回deviceId=device-local、running=false(P2P,默认 home 网络未启用)与 12 个字段;无storeLock。
0.5 红线
不改变任何既有 memory provider 的代码、存储与进程;Mebular 仅以 MCP 工具面叠加提供跨设备记忆。
与既有 provider 的分工/导入/冲突口径见 MEMORY_POLICY.md §8。
node -v # 期望:v20 或更高
npm -v判定:node -v 输出 v20+。否则先让用户安装 Node.js LTS,不要继续。
A. 从 GitHub 钉住提交(推荐;可复现)
SHA=$(git ls-remote https://github.com/Windsander/Mebular.git refs/heads/main | cut -f1)
npm i -g "github:Windsander/Mebular#$SHA"
command -v mebular && command -v fleet判定:command -v mebular && command -v fleet 均有输出;mebular --help(exit 0)与 fleet --version(exit 0)可执行;
mebular tools 列出 29 个工具;记录 $SHA 以便回报。
(mebular --version 不存在:会打印「未知命令:--version」并 exit 2。)
安装时的
prepare会自动完成三包构建(mebular与fleet双 bin 随包发布,无需手动 build;缺省 home 为~/.mebular)。 若该命令以ENOTDIR/git dep preparation failed失败:这是部分 npm(实测 11.19)对全局 git 依赖的 staging 缺陷——与本仓库内容无关(prepare一旦成功、进入全局 reify 才暴露;用基线 SHA 只是更早失败在tsc而看不到)。 遇到时改用下面的 B(本地仓库),它等价且本机已实测可用。
B. 本地仓库(开发者;也是 A 失败时的等价干净路径)
SHA=<要钉住的提交>
git clone https://github.com/Windsander/Mebular.git && cd Mebular
git checkout "$SHA"
npm ci && npm run build
npm i -g .
command -v mebular && command -v fleet(本机实测:npm i -g . → 双 bin 就位、mebular tools=29、fleet --version 含该 SHA、不设 MEBULAR_HOME 起 serve → PROVISION_READY home=~/.mebular。)
fleet quickstart --daemon --dir ~/.mebular --device "$(hostname | tr '[:upper:]' '[:lower:]')"- Windows(PowerShell)把家目录写成:
--dir "$env:USERPROFILE\.mebular"。 - 这一条做了什么:生成本机设备身份 + 守护 home + 加入服务;打印的 JSON 里有
joinEndpoint等字段。
判定:命令退出码 0,且 JSON 含 "ok": true。随后自检:
mebular status # home 由 MEBULAR_HOME 决定,缺省 ~/.mebular
mebular status没有--home参数(传了会被忽略);要指定别的 home 用MEBULAR_HOME=<dir> mebular status。
fleet invite --dir ~/.mebular输出含:二维码(终端渲染)与文本令牌(JSON 的 token 字段,也含 qr/qrSvg)。
安全红线(必须遵守):
- 令牌是一次性、短时效(默认 15 分钟)的入网凭证:只交给用户,由用户安全转交新设备。
- 不得把令牌/二维码写入日志、聊天记录、工单或任何外部服务;不得回显密钥材料。
- 主密钥永不离开本机;邀请过程不复制主密钥。
- 加入后可自行订阅记忆域(零门槛、热生效);不复制主密钥。
需要用户提供二维码内容或令牌(二者等价):
fleet join --qr "<二维码内容>" --daemon --dir ~/.mebular --device "$(hostname | tr '[:upper:]' '[:lower:]')"
# 等价写法:fleet join --token <令牌文件或内联> --daemon --dir ~/.mebular --device <本机名>- Windows(PowerShell):
fleet join --qr "<内容>" --daemon --dir "$env:USERPROFILE\.mebular" --device "$env:COMPUTERNAME"。 - 一步完成:委派身份(不复制主密钥)+ 自动连接 + 按令牌分区自动订阅。
- 默认不需要批准:新设备加入后自行
fleet subscribe即可。
判定:退出码 0,JSON 含 "ok": true。
mebular doctor --net # 网络:地址簿 / LAN 发现 / 打洞 / 桥角色 / 下一步建议
mebular status # 身份 / 存储 / 计数 / 状态哈希常见失败与处置(不要自行改订阅或重置身份):
| 症状 | 处置 |
|---|---|
MCP_INSECURE_CONFIG(缺证书 / 非回环组合非法) |
编辑 ~/.mebular/config.json:把 mcp.http.host 改回 127.0.0.1,或补齐 auth + tls + tlsKey/tlsCert,再重启 mebular serve |
MCP_STORAGE_LOCKED(存储已被占用) |
已有实例持锁:复用该实例,或先停掉它再启动 |
切换 auth=bearer/oauth 后控制台 API 401 |
见控制台「设置 → 诊断 → 恢复指引」;bearer 可粘贴 mebular token grant --scope memory.read,memory.admin 的 token 自救;oauth 需 env secret,否则改回 auth=none(仅回环) |
| 控制台打不开 | mebular serve 是否在跑、日志里是否有上述错误码;再打开 http://127.0.0.1:7331/console 的「诊断」页 |
| 加入后连不上对端 | mebular doctor --net 看 next 建议(LAN 发现 / relay seeds / 白名单) |
更多运维细节见 ../../packages/fleet/RUNBOOK.md(§6 控制台、§9 桥角色、§7 配对即连)。
部署结果:<新建 | 加入>
设备:<device>
守护 home:<dir>
自检:mebular status = ok,mebular doctor --net 建议:<next 摘要>
下一步:<邀请别人:fleet invite | 在控制台打开 http://127.0.0.1:7331/console>
不要输出令牌、二维码或任何密钥材料;它们只属于用户与新设备之间的转交。