Skip to content

Latest commit

 

History

History
239 lines (176 loc) · 12.1 KB

SETUP.md

File metadata and controls

239 lines (176 loc) · 12.1 KB

Mebular 部署手册(给 Agent 执行)

面向 Agent:本文件是可执行的部署/加入剧本。用户只负责两件事:说出要做什么、转交配对码。 每一步都给出命令与「期望输出 / 判定」。任何一步失败:先按 §6 处置,不要猜、不要跳过。

0. 会话内接入(每次会话第一步)

目标:在当前会话里直接拿到 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 === true

home 默认已统一: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
  1. 把输出片段合入当前客户端的 MCP 配置(先备份原文件);dsh 形态为客户端桥接(只桥接 Tools)。
  2. 重载客户端(重启该客户端/会话)后生效。
  3. 验证:在本会话调用 memory_status —— 期望返回 deviceId / running(P2P 节点)/ 计数等字段。 注意:storeLock 不在 memory_status 的返回里(那是 CLI mebular 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。

1. 前置检查

node -v          # 期望:v20 或更高
npm -v

判定:node -v 输出 v20+。否则先让用户安装 Node.js LTS,不要继续。

2. 安装 CLI(二选一)

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。)

3. 建一个新的 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。

4. 出一个邀请(让别的设备加入你)

fleet invite --dir ~/.mebular

输出含:二维码(终端渲染)与文本令牌(JSON 的 token 字段,也含 qr/qrSvg)。

安全红线(必须遵守):

  • 令牌是一次性、短时效(默认 15 分钟)的入网凭证:只交给用户,由用户安全转交新设备。
  • 不得把令牌/二维码写入日志、聊天记录、工单或任何外部服务;不得回显密钥材料。
  • 主密钥永不离开本机;邀请过程不复制主密钥。
  • 加入后可自行订阅记忆域(零门槛、热生效);不复制主密钥。

5. 加入一个已有的 Mebular(新设备)

需要用户提供二维码内容或令牌(二者等价):

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。

6. 自检与失败恢复

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 配对即连)。

7. 回报给用户(Agent 输出模板)

部署结果:<新建 | 加入>
设备:<device>
守护 home:<dir>
自检:mebular status = ok,mebular doctor --net 建议:<next 摘要>
下一步:<邀请别人:fleet invite | 在控制台打开 http://127.0.0.1:7331/console>

不要输出令牌、二维码或任何密钥材料;它们只属于用户与新设备之间的转交。