Muse Agent Skill — 把 Muse 接入你的编程 Agent

画图，一步到位，零弹窗

你说「让 Muse 画一只加菲猫泡温泉」 → muse_get_images(prompt)（异步任务，不阻塞） → Muse 生成 → 按它身上装好的 zcode-bridge 技能，curl PUT 上传到你的 COS bucket （Mac 预签名 URL，Muse 零凭证；首次在 app 批一次 myqcloud 域名 "永久允许"，此后终身免批） → 直链回传 → 原生 MCP ImageContent 内联显示 + 本地落盘 + 永久直链

对比官方 muse.ai/files 转存（每张图弹一次人工审批，无永久放行选项）， COS 中转只在首次弹一张域名审批卡——选"永久允许"后零弹窗、直链永久有效；未配置 COS 时自动回落官方路线。实测：小奶猫、加菲猫、猫鼠追逐三次端到端，15 秒内落地。

前提：给 Muse 装一次 zcode-bridge 技能（不发就回退官方逐文件审批）

本仓库带两份技能：给你的 agent 装的 skills/muse（工具用法），和给 Muse 自己 装的 muse-side/zcode-bridge。后者是零依赖的纯协议约定，把 muse-side/zcode-bridge.zip 发进与 Muse 的聊天，附这句提示词即可安装：

请把附件里的 zcode-bridge 技能安装到你的工作区
（~/workspace/skills/zcode-bridge/），读完 SKILL.md 后按其协议工作：
今后凡是要通知 Zcode 的结果/图片/任务状态，都按协议格式发到
muse-agent 开头的侧聊会话里。

装好之后：Muse 会执行画图指令里的预签名 curl 上传、并以 Markdown 图片语法回链； muse_notifications 也靠它——Muse 主动推送的消息/图片按协议进侧聊，agent 被动收取。

两条路线，同一套工具

路线 A · 手机配对直连推荐 · 已验证

手机 Muse app 一次 BLE 配对 → 社区 muse-client（官方协议 TS 移植）本机直连，零额外硬件。配对后手机彻底退役。国内网络配 bridge_proxy 一行走代理（proxychains4 免 TUN）。不注册任何本机命令。

路线 B · Linux SDK 常驻 24/7 · 多设备

官方 muse-gadget-sdk systemd 常驻，服务器唯一持凭证，任意多台设备 backend: ssh 共用；Muse 可执行 system.run/file.*（可裁剪）。授权一次，配对机即退役（需 USB 蓝牙）。画图回传走 COS 直链（官方 CLI 只回文本）。

配对凭证可迁移，Windows 也能运行（借一台 Mac/WSL2 授权一次）。切换 backend 一行配置，11 个 MCP 工具面基本一致（muse_notifications 仅路线 A）。

MCP 工具（11 个）

工具	用途
`muse_chat` / `muse_send`	发消息收回答 / 发后即走；默认走 agent 专属 side chat，不污染主聊天
`muse_start_image_generation` + `muse_get_image_result`	异步画图：任务持久化、超时不丢、重查不重画；返回原生 ImageContent + 永久直链
`muse_get_images`	上两步的便捷封装（一步等到底）
`muse_send_image`	把本地图发给 Muse 分析（≤2 MiB）
`muse_notifications`	被动收 Muse 主动推来的消息/图片（配合 zcode-bridge 技能）
`muse_status` / `muse_doctor` / `muse_sessions`	连接体检 / 逐项排障清单（每项带下一步命令）/ 会话管理

快速开始 · 零基础跟跑

从装工具到画出第一张图，照着面板从上往下执行即可，每步带注释。需要准备：一台 Mac + Muse 账号（手机装好 app）+ 国内网络备一个代理客户端。深入手册：配对 · COS 配置 · README

# 0. 前置工具（各装一次；海外网络可跳过 proxychains-ng）
xcode-select --install                                 # Mac 命令行工具（蓝牙权限要用）
curl -LsSf https://astral.sh/uv/install.sh | sh        # uv：跑 MCP server
curl -fsSL https://bun.sh/install | bash               # bun：跑 bridge
brew install proxychains-ng                            # 国内网络免 TUN 代理用

# 1. 克隆仓库 + 装依赖
git clone https://github.com/ahao430/muse-skill && cd muse-skill
uv sync && (cd bridge && bun install)

# 2. SDK token（等同凭证，勿外传）：https://gadgets.muse.ai/settings/sdk-tokens → 新建
mkdir -p ~/.config/muse-agent
echo 'mgst_你的token' > ~/.config/muse-agent/sdk_token

# 3. 国内网络配代理 —— TUN 非必须，日常按进程走 SOCKS
#    （端口换成你代理客户端的 SOCKS 端口，Clash Verge 默认 7897）
echo 'bridge_proxy: http://127.0.0.1:7897' >> ~/.config/muse-agent/config.yaml

# 4. 蓝牙配对（一次性 2 分钟，手机 app: Settings → Devices →
#    Developer mode → Add Device → 选 MuseGadgetXXXXXX）
#    ⚠ 这 2 分钟手机+电脑都要能访问 Meta 域名：手机开自己的代理，
#      电脑开系统代理或 TUN 都行——配完就都不用了
bun bridge/bridge.mjs pair
bun bridge/bridge.mjs status                           # "ready": true 即配对成功

# 5.（推荐）COS 中转 → 画图零弹窗：按 docs/cos.md 手册加三行配置 + selftest
# 6. Muse 侧装桥（一次）：把 muse-side/zcode-bridge.zip 发进 Muse 聊天
#    + 安装提示词（见上方「前提」），不装则回退官方逐文件审批
# 7. 注册 MCP + 安装 agent 技能 ↓ 见下方

# 在有蓝牙的 Linux 上配对一次（USB BLE / 树莓派）：
sudo bash install.sh --sdk-token mgst_… --yes && sudo musegadget pair
scp /var/lib/musegadget/{identity,pairing}.json 你@Mac:~/muse-pairing/

# 部署常驻主机并导入凭证（配对机使命结束）
scripts/provision.sh --host USER@HOST --sdk-token mgst_…
scripts/import_state.sh ~/muse-pairing --host USER@HOST

# 每台设备 config.yaml:
# backend: ssh
# host: USER@HOST
# 国内网络：给常驻主机的 musegadget 服务配 https_proxy（或主机侧透明代理）

# 注册 MCP（Claude Code）：
claude mcp add muse -- uv --directory …/muse-skill run muse-agent
# 然后对 agent 说：「让 Muse 画一张 ……」

# 附：独立 COS 上传技能（skills/cos，纯 stdlib，复用同一份 cos_* 配置）
cp -r skills/cos ~/.agents/skills/cos
python3 ~/.agents/skills/cos/cos.py upload 文件.png --md   # → ![名字](永久直链)

设计要点

诚实的异步

画图拆成 start/result 两步：超时是状态不是错误，任务持久化、重查不重画；审批等待独立成 approval_required 并附指引。

零凭证中转

COS 密钥只在 Mac；Muse 只收到 1 小时一次性预签名 PUT。签名算法纯 Python 自实现，配对/自测命令权威验收。

国内网络现实

TUN 非必须：日常连接由 proxychains4 按进程接管 WSS（系统网络零改动）；代理节点劣化、TLS 重置等网络类失败可重试不判死。

39 项单测 + CI

状态机/去重/超尺寸/不内联/预签名接线全 mock 化；GitHub Actions 跑 pytest 与脚本检查。