From 8097ab748400534a09c0d0aebc9dc2ff9560b668 Mon Sep 17 00:00:00 2001
From: orion <orion@op.hangman-lab.top>
Date: Wed, 25 Feb 2026 22:02:00 +0000
Subject: [PATCH] docs(discord-control): add runnable examples and smoke script

---
 Makefile                           |  5 ++-
 README.md                          |  2 +-
 docs/DISCORD_CONTROL.md            | 12 ++++++
 docs/EXAMPLES.discord-control.json | 68 ++++++++++++++++++++++++++++++
 scripts/smoke-discord-control.sh   | 52 +++++++++++++++++++++++
 5 files changed, 137 insertions(+), 2 deletions(-)
 create mode 100644 docs/EXAMPLES.discord-control.json
 create mode 100755 scripts/smoke-discord-control.sh

diff --git a/Makefile b/Makefile
index e24f0a7..5f3893c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: check check-rules test-api up down smoke render-config package-plugin discord-control-up
+.PHONY: check check-rules test-api up down smoke render-config package-plugin discord-control-up smoke-discord-control
 
 check:
 	cd plugin && npm run check
@@ -26,3 +26,6 @@ package-plugin:
 
 discord-control-up:
 	cd discord-control-api && node server.mjs
+
+smoke-discord-control:
+	./scripts/smoke-discord-control.sh
diff --git a/README.md b/README.md
index 68d36cf..687c3fe 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ The no-reply provider returns `NO_REPLY` for any input.
 - `discord-control-api/` — Discord 管理扩展 API（私密频道 + 成员列表）
 - `docs/` — rollout, integration, run-mode notes
 - `scripts/` — smoke/dev/helper checks
-- `Makefile` — common dev commands (`make check`, `make check-rules`, `make test-api`, `make up`)
+- `Makefile` — common dev commands (`make check`, `make check-rules`, `make test-api`, `make smoke-discord-control`, `make up`)
 - `CHANGELOG.md` — milestone summary
 
 ## Quick start (no Docker)
diff --git a/docs/DISCORD_CONTROL.md b/docs/DISCORD_CONTROL.md
index 732926e..aba5993 100644
--- a/docs/DISCORD_CONTROL.md
+++ b/docs/DISCORD_CONTROL.md
@@ -119,6 +119,18 @@ curl -sS http://127.0.0.1:8790/health
 
 ---
 
+## Curl examples
+
+示例文件：`docs/EXAMPLES.discord-control.json`
+
+快速检查脚本：
+
+```bash
+./scripts/smoke-discord-control.sh
+# with env
+# AUTH_TOKEN=xxx CALLER_ID=agent-main GUILD_ID=123 CHANNEL_ID=456 ./scripts/smoke-discord-control.sh
+```
+
 ## Notes
 
 鉴权与内置风格对齐（简化版）：
diff --git a/docs/EXAMPLES.discord-control.json b/docs/EXAMPLES.discord-control.json
new file mode 100644
index 0000000..1943979
--- /dev/null
+++ b/docs/EXAMPLES.discord-control.json
@@ -0,0 +1,68 @@
+{
+  "channel-private-create": {
+    "action": "channel-private-create",
+    "guildId": "123456789012345678",
+    "name": "ops-private",
+    "type": 0,
+    "parentId": "234567890123456789",
+    "topic": "ops only",
+    "position": 3,
+    "nsfw": false,
+    "allowedUserIds": [
+      "345678901234567890",
+      "456789012345678901"
+    ],
+    "allowedRoleIds": [
+      "567890123456789012"
+    ],
+    "allowMask": "67648",
+    "denyEveryoneMask": "1024",
+    "dryRun": true
+  },
+  "channel-private-update-merge": {
+    "action": "channel-private-update",
+    "guildId": "123456789012345678",
+    "channelId": "678901234567890123",
+    "mode": "merge",
+    "addUserIds": [
+      "345678901234567890"
+    ],
+    "addRoleIds": [
+      "567890123456789012"
+    ],
+    "removeTargetIds": [
+      "456789012345678901"
+    ],
+    "allowMask": "67648",
+    "denyMask": "0",
+    "dryRun": true
+  },
+  "channel-private-update-replace": {
+    "action": "channel-private-update",
+    "guildId": "123456789012345678",
+    "channelId": "678901234567890123",
+    "mode": "replace",
+    "addUserIds": [
+      "345678901234567890"
+    ],
+    "addRoleIds": [
+      "567890123456789012"
+    ],
+    "allowMask": "67648",
+    "denyMask": "0",
+    "dryRun": true
+  },
+  "member-list": {
+    "action": "member-list",
+    "guildId": "123456789012345678",
+    "limit": 100,
+    "after": "0",
+    "fields": [
+      "user.id",
+      "user.username",
+      "nick",
+      "roles",
+      "joined_at"
+    ]
+  }
+}
diff --git a/scripts/smoke-discord-control.sh b/scripts/smoke-discord-control.sh
new file mode 100755
index 0000000..613be5c
--- /dev/null
+++ b/scripts/smoke-discord-control.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${BASE_URL:-http://127.0.0.1:8790}"
+AUTH_TOKEN="${AUTH_TOKEN:-}"
+CALLER_ID="${CALLER_ID:-}"
+
+AUTH_HEADER=()
+if [[ -n "$AUTH_TOKEN" ]]; then
+  AUTH_HEADER=(-H "Authorization: Bearer ${AUTH_TOKEN}")
+fi
+
+CALLER_HEADER=()
+if [[ -n "$CALLER_ID" ]]; then
+  CALLER_HEADER=(-H "X-OpenClaw-Caller-Id: ${CALLER_ID}")
+fi
+
+echo "[1] health"
+curl -sS "${BASE_URL}/health" | sed -n '1,20p'
+
+if [[ -z "${GUILD_ID:-}" ]]; then
+  echo "skip action checks: set GUILD_ID (and optional CHANNEL_ID) to run dryRun actions"
+  exit 0
+fi
+
+echo "[2] dry-run private create"
+curl -sS -X POST "${BASE_URL}/v1/discord/action" \
+  -H 'Content-Type: application/json' \
+  "${AUTH_HEADER[@]}" \
+  "${CALLER_HEADER[@]}" \
+  -d "{\"action\":\"channel-private-create\",\"guildId\":\"${GUILD_ID}\",\"name\":\"wg-dryrun\",\"dryRun\":true}" \
+  | sed -n '1,80p'
+
+if [[ -n "${CHANNEL_ID:-}" ]]; then
+  echo "[3] dry-run private update"
+  curl -sS -X POST "${BASE_URL}/v1/discord/action" \
+    -H 'Content-Type: application/json' \
+    "${AUTH_HEADER[@]}" \
+    "${CALLER_HEADER[@]}" \
+    -d "{\"action\":\"channel-private-update\",\"guildId\":\"${GUILD_ID}\",\"channelId\":\"${CHANNEL_ID}\",\"mode\":\"merge\",\"dryRun\":true}" \
+    | sed -n '1,100p'
+fi
+
+echo "[4] member-list (limit=1)"
+curl -sS -X POST "${BASE_URL}/v1/discord/action" \
+  -H 'Content-Type: application/json' \
+  "${AUTH_HEADER[@]}" \
+  "${CALLER_HEADER[@]}" \
+  -d "{\"action\":\"member-list\",\"guildId\":\"${GUILD_ID}\",\"limit\":1,\"fields\":[\"user.id\",\"user.username\"]}" \
+  | sed -n '1,120p'
+
+echo "smoke-discord-control: done"