From c696b913db570b9272d2c061d963c525ed7cbdef Mon Sep 17 00:00:00 2001
From: zlei9 <zlei9@126.com>
Date: Sun, 29 Mar 2026 10:22:04 +0800
Subject: [PATCH] Initial commit with translated description

---
 SKILL.md   | 39 +++++++++++++++++++++++++++++++++++++++
 _meta.json |  6 ++++++
 2 files changed, 45 insertions(+)
 create mode 100644 SKILL.md
 create mode 100644 _meta.json

diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..a179366
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: bluebubbles
+description: "为Clawdbot构建或更新BlueBubbles外部通道插件。"
+---
+
+# BlueBubbles plugin
+
+Use this skill when working on the BlueBubbles channel plugin.
+
+## Layout
+- Extension package: `extensions/bluebubbles/` (entry: `index.ts`).
+- Channel implementation: `extensions/bluebubbles/src/channel.ts`.
+- Webhook handling: `extensions/bluebubbles/src/monitor.ts` (register via `api.registerHttpHandler`).
+- REST helpers: `extensions/bluebubbles/src/send.ts` + `extensions/bluebubbles/src/probe.ts`.
+- Runtime bridge: `extensions/bluebubbles/src/runtime.ts` (set via `api.runtime`).
+- Catalog entry for onboarding: `src/channels/plugins/catalog.ts`.
+
+## Internal helpers (use these, not raw API calls)
+- `probeBlueBubbles` in `extensions/bluebubbles/src/probe.ts` for health checks.
+- `sendMessageBlueBubbles` in `extensions/bluebubbles/src/send.ts` for text delivery.
+- `resolveChatGuidForTarget` in `extensions/bluebubbles/src/send.ts` for chat lookup.
+- `sendBlueBubblesReaction` in `extensions/bluebubbles/src/reactions.ts` for tapbacks.
+- `sendBlueBubblesTyping` + `markBlueBubblesChatRead` in `extensions/bluebubbles/src/chat.ts`.
+- `downloadBlueBubblesAttachment` in `extensions/bluebubbles/src/attachments.ts` for inbound media.
+- `buildBlueBubblesApiUrl` + `blueBubblesFetchWithTimeout` in `extensions/bluebubbles/src/types.ts` for shared REST plumbing.
+
+## Webhooks
+- BlueBubbles posts JSON to the gateway HTTP server.
+- Normalize sender/chat IDs defensively (payloads vary by version).
+- Skip messages marked as from self.
+- Route into core reply pipeline via the plugin runtime (`api.runtime`) and `clawdbot/plugin-sdk` helpers.
+- For attachments/stickers, use `<media:...>` placeholders when text is empty and attach media paths via `MediaUrl(s)` in the inbound context.
+
+## Config (core)
+- `channels.bluebubbles.serverUrl` (base URL), `channels.bluebubbles.password`, `channels.bluebubbles.webhookPath`.
+- Action gating: `channels.bluebubbles.actions.reactions` (default true).
+
+## Message tool notes
+- **Reactions:** The `react` action requires a `target` (phone number or chat identifier) in addition to `messageId`. Example: `action=react target=+15551234567 messageId=ABC123 emoji=❤️`
diff --git a/_meta.json b/_meta.json
new file mode 100644
index 0000000..e34f1a8
--- /dev/null
+++ b/_meta.json
@@ -0,0 +1,6 @@
+{
+  "ownerId": "kn76fefs432zhff78zmv4q1b2x7zymsz",
+  "slug": "bluebubbles",
+  "version": "1.0.0",
+  "publishedAt": 1769405231570
+}
\ No newline at end of file