指南
连接与鉴权发现
同机发现、跨设备配对、开场对账三步
连接与鉴权发现
Bridge 只监听 127.0.0.1。
- MarginNote 设置 → Lab →「MarginNote CLI」已开启
- 令牌三选一：
~/.config/mn-bridge/token（跑过安装命令就有）、用户直接给、环境变量MN_BRIDGE_TOKEN - 用户没装过：设置 → Lab →「Copy Agent Setup Command」，粘进终端执行（写令牌 + 装 Skill + 可选接 MCP）
跨设备下三个不可逆端点需设备端点按 Allow（confirm:true 后挂起最多 60 秒）：
study-sets/{id}/delete、notes/delete、snapshots/{id}/restore。
- 200 = Allow；403
APPROVAL_DENIED= Deny（停下并告知，不换说法重试） - 408
APPROVAL_TIMEOUT= 60 秒无人理（让用户看屏幕后重试，勿自动重试）
MCP 可选接入（0.21 起，省掉手配 token）：
claude mcp add --transport http marginnote http://127.0.0.1:{port}/bridge/v1/mcp \
--header "Authorization: Bearer $TOKEN"接入后仅两个工具：mn_guide（运行时规程）与 mn_call（{method,path,body} 转发到同一批端点）。
同机发现（跨设备跳过本节）
# 别用 grep -i margin | head -1：同机可有十来个 Margin* 容器，首个多半不是运行中的
BRIDGE_JSON=""
for f in ~/Library/Containers/*[Mm]argin*/Data/Library/Application\ Support/MNAgentBridge/bridge.json \
~/Library/Application\ Support/MNAgentBridge/bridge.json; do
[ -r "$f" ] && { BRIDGE_JSON="$f"; break; }
done
# 用 sed 而非 jq（jq 非系统自带）
if [ -n "$BRIDGE_JSON" ]; then
PORT=$(sed -n 's/.*"port"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$BRIDGE_JSON" 2>/dev/null | head -1)
NONCE=$(sed -n 's/.*"instanceNonce"[^"]*"\([^"]*\)".*/\1/p' "$BRIDGE_JSON" 2>/dev/null | head -1)
fi
# 读不到常见于缺完全磁盘访问（TCC EPERM）；lsof 扫不到也不等于没跑（沙盒进程表残缺）
if [ -z "$PORT" ]; then
PORT=$(lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | grep -i margin \
| grep -o '127\.0\.0\.1:[0-9]*' | head -1 | cut -d: -f2)
fi
PORT=${PORT:-42340}
BASE="http://127.0.0.1:$PORT/bridge/v1"
curl -s "$BASE/status" # 有 NONCE 则校验 instanceNonce 一致后续请求一律带 -H "Authorization: Bearer $TOKEN"。
不要带 Origin 头（带了 403 FORBIDDEN_ORIGIN）。云上调试同样受此限制，
见接口总览。
开场对账（连上后第一件事）
读 GET /status
除 bridgeApiVersion/routeCount/apiFingerprint 外，0.34+ 还返回 guideVersion/guideHash（完整 SHA-256）。
规程不一致则刷新
运行时的 guide 版本或 hash 与已加载规程不一致 → 用现有 Bearer读 GET /guide，以返回 Markdown 为当前会话规程。只读刷新：不调 /install、不轮换 token、不覆写磁盘文件。旧 Bridge 无此字段才回落 /capabilities 对账。
读 GET /capabilities
实际注册的全部路由 {routes:[{method,path,requiresMax}]} + presets/anchorModes 等。requiresMax:false 仅表示有效 token 下免 Max，不是免 token。清单里有而规程没写的可用；规程有而清单没有的别调。
403/401 速查
| 现象 | 含义 | 动作 |
|---|---|---|
401 UNAUTHORIZED | 令牌不对 | 重装安装命令换 token；TCP 通说明 Bridge 活着 |
403 FORBIDDEN_ORIGIN | 带了 Origin 头 | 去掉重试（或走本站 Playground 代理） |
403 MAX_REQUIRED | 该写路由需 Max，用户无订阅 | 该写请求不重试不绕路，只读可继续 |
跨设备 403 APPROVAL_DENIED | 用户在设备上按了 Deny | 停下并告知，不换说法重试 |
跨设备 408 APPROVAL_TIMEOUT | 60s 无人理 | 让用户看设备屏幕后重试，不自动重试 |